ether
diff --git a/‎CHANGELOG.md‎
Lines changed: 4 additions & 1 deletion b/‎CHANGELOG.md‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎admin/src/components/UpdateBanner.tsx‎
Lines changed: 39 additions & 1 deletion b/‎admin/src/components/UpdateBanner.tsx‎
Lines changed: 39 additions & 1 deletion
diff --git a/‎admin/src/pages/UpdatePage.tsx‎
Lines changed: 48 additions & 3 deletions b/‎admin/src/pages/UpdatePage.tsx‎
Lines changed: 48 additions & 3 deletions
diff --git a/‎admin/src/store/store.ts‎
Lines changed: 1 addition & 0 deletions b/‎admin/src/store/store.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎doc/admin/updates.md‎
Lines changed: 32 additions & 2 deletions b/‎doc/admin/updates.md‎
Lines changed: 32 additions & 2 deletions
@@ -8,7 +8,10 @@
   - Terminal `rollback-failed` state surfaces a strong banner; the admin clicks Acknowledge once they've manually recovered to clear the lock and re-allow Tier 2 attempts.
   - New settings under `updates.*`: `preApplyGraceMinutes`, `drainSeconds`, `rollbackHealthCheckSeconds`, `diskSpaceMinMB`, `requireSignature`, `trustedKeysPath`. Tag signature verification is opt-in (default `false`) — see `doc/admin/updates.md` for the keyring setup.
   - **A process supervisor (systemd / pm2 / docker `--restart=unless-stopped`) is required to apply updates.** Without one, exit 75 leaves the instance down.
-  - Tiers 3 (auto with grace window) and 4 (autonomous in maintenance window) remain designed but unimplemented and will land in subsequent releases.
+- **Self-update subsystem — Tier 3 (auto with grace window).**
+  - On a git install, set `updates.tier: "auto"` to have new releases applied automatically after `preApplyGraceMinutes`. During the grace window, `/admin/update` shows a live countdown plus Cancel and Apply now buttons. Schedules are persisted to `var/update-state.json`, so an Etherpad restart during the grace window rehydrates the timer instead of losing the schedule. A new release tag detected mid-grace re-arms the timer; if `adminEmail` is set, a one-shot `grace-start` notification fires per scheduled tag (issue #7607).
+  - The terminal `rollback-failed` state continues to disable auto/autonomous attempts globally until acknowledged; manual click stays available because an admin click *is* the intervention the terminal state requires.
+  - Tier 4 (autonomous in a maintenance window) remains designed but unimplemented and will land in a subsequent release.
 
 # 2.7.3
 
 
@@ -1,8 +1,16 @@
-import {useEffect} from 'react';
+import {useEffect, useState} from 'react';
 import {Link} from 'react-router-dom';
 import {Trans, useTranslation} from 'react-i18next';
 import {useStore} from '../store/store';
 
+const fmtRemaining = (ms: number): string => {
+  if (ms <= 0) return '0s';
+  const s = Math.floor(ms / 1000);
+  const m = Math.floor(s / 60);
+  const sec = s % 60;
+  return m > 0 ? `${m}m ${sec}s` : `${sec}s`;
+};
+
 export const UpdateBanner = () => {
   const {t} = useTranslation();
   const updateStatus = useStore((s) => s.updateStatus);
@@ -17,6 +25,19 @@ export const UpdateBanner = () => {
     return () => { cancelled = true; };
   }, [setUpdateStatus]);
 
+  const scheduledFor = updateStatus?.execution?.status === 'scheduled'
+    ? (updateStatus.execution as {scheduledFor: string}).scheduledFor
+    : null;
+  const [remainingMs, setRemainingMs] = useState<number>(() =>
+    scheduledFor ? Math.max(0, new Date(scheduledFor).getTime() - Date.now()) : 0);
+  useEffect(() => {
+    if (!scheduledFor) return;
+    const target = new Date(scheduledFor).getTime();
+    setRemainingMs(Math.max(0, target - Date.now()));
+    const id = setInterval(() => setRemainingMs(Math.max(0, target - Date.now())), 1000);
+    return () => clearInterval(id);
+  }, [scheduledFor]);
+
   if (!updateStatus) return null;
 
   // Terminal rollback-failed wins over the regular "update available" banner —
@@ -31,6 +52,23 @@ export const UpdateBanner = () => {
     );
   }
 
+  // Tier 3: scheduled update — show countdown banner instead of the plain
+  // "update available" one.
+  if (updateStatus.execution?.status === 'scheduled') {
+    const exec = updateStatus.execution as {targetTag: string; scheduledFor: string};
+    return (
+      <div className="update-banner update-banner-scheduled" role="status">
+        <strong>
+          <Trans
+            i18nKey="update.banner.scheduled"
+            values={{tag: exec.targetTag, remaining: fmtRemaining(remainingMs)}}
+          />
+        </strong>{' '}
+        <Link to="/update">{t('update.banner.cta')}</Link>
+      </div>
+    );
+  }
+
   if (!updateStatus.latest) return null;
   if (updateStatus.currentVersion === updateStatus.latest.version) return null;
 
 
@@ -11,6 +11,14 @@ type FetchState =
 
 const IN_FLIGHT_STATUSES = ['preflight', 'draining', 'executing', 'rolling-back'];
 
+const fmtRemaining = (ms: number): string => {
+  if (ms <= 0) return '0s';
+  const s = Math.floor(ms / 1000);
+  const m = Math.floor(s / 60);
+  const sec = s % 60;
+  return m > 0 ? `${m}m ${sec}s` : `${sec}s`;
+};
+
 export const UpdatePage = () => {
   const {t} = useTranslation();
   const us = useStore((s) => s.updateStatus);
@@ -79,6 +87,21 @@ export const UpdatePage = () => {
     }
   };
 
+  // Tier 3 countdown — derive scheduledFor outside the conditional returns so
+  // the hook order is stable on every render.
+  const scheduledFor = us?.execution?.status === 'scheduled'
+    ? (us.execution as {scheduledFor: string}).scheduledFor
+    : null;
+  const [remainingMs, setRemainingMs] = useState<number>(() =>
+    scheduledFor ? Math.max(0, new Date(scheduledFor).getTime() - Date.now()) : 0);
+  useEffect(() => {
+    if (!scheduledFor) return;
+    const target = new Date(scheduledFor).getTime();
+    setRemainingMs(Math.max(0, target - Date.now()));
+    const id = setInterval(() => setRemainingMs(Math.max(0, target - Date.now())), 1000);
+    return () => clearInterval(id);
+  }, [scheduledFor]);
+
   if (fetchState.kind === 'loading') {
     return <div>{t('admin.loading', {defaultValue: 'Loading...'})}</div>;
   }
@@ -110,12 +133,20 @@ export const UpdatePage = () => {
 
   const upToDate = !us.latest || us.currentVersion === us.latest.version;
   const showApply = !!us.policy?.canManual
-    && (status === 'idle' || status === 'verified')
+    && (status === 'idle' || status === 'verified' || status === 'scheduled')
     && !us.lockHeld
     && !upToDate;
-  const showCancel = status === 'preflight' || status === 'draining';
+  const showCancel = status === 'preflight' || status === 'draining' || status === 'scheduled';
   const showAcknowledge = status === 'preflight-failed' || status === 'rolled-back' || status === 'rollback-failed';
 
+  // Optional-chain the execution lookup: some integration-test stubs of
+  // /admin/update/status omit Tier 2/3 fields entirely (see
+  // update-banner.spec.ts), and accessing `.status` on an undefined
+  // execution would crash the whole page before the h1 renders.
+  const scheduled = us.execution?.status === 'scheduled'
+    ? us.execution as {targetTag: string; scheduledFor: string}
+    : null;
+
   return (
     <div className="update-page">
       <h1><Trans i18nKey="update.page.title"/></h1>
@@ -152,10 +183,24 @@ export const UpdatePage = () => {
         </p>
       )}
 
+      {scheduled && (
+        <section className="update-scheduled" aria-live="polite">
+          <h2><Trans i18nKey="update.page.scheduled.title"/></h2>
+          <p>
+            <Trans
+              i18nKey="update.page.scheduled.countdown"
+              values={{tag: scheduled.targetTag, remaining: fmtRemaining(remainingMs)}}
+            />
+          </p>
+        </section>
+      )}
+
       <div className="update-actions">
         {showApply && (
           <button onClick={() => post('/admin/update/apply')} disabled={actionInFlight}>
-            {t('update.page.apply')}
+            {status === 'scheduled'
+              ? t('update.page.scheduled.apply_now')
+              : t('update.page.apply')}
           </button>
         )}
         {showCancel && (
 
@@ -5,6 +5,7 @@ import {InstalledPlugin} from "../pages/Plugin.ts";
 
 export type Execution =
   | {status: 'idle'}
+  | {status: 'scheduled'; targetTag: string; scheduledFor: string; startedAt: string}
   | {status: 'preflight'; targetTag: string; startedAt: string}
   | {status: 'preflight-failed'; targetTag: string; reason: string; at: string}
   | {status: 'draining'; targetTag: string; drainEndsAt: string; startedAt: string}
 
@@ -4,7 +4,7 @@ Etherpad ships with a built-in update subsystem.
 
 - **Tier 1 (notify)** — default. A banner appears in the admin UI when a new release is available, and pad users see a discreet badge if the running version is severely outdated or flagged as vulnerable. No execution.
 - **Tier 2 (manual click)** — admins on a git install can click "Apply update" at `/admin/update`. Etherpad drains active sessions, runs `git fetch / checkout / pnpm install / pnpm run build:ui`, and exits with code 75 so a process supervisor restarts it on the new version. Auto-rolls back on failure.
-- **Tier 3 (auto with grace window)** — designed, not yet implemented.
+- **Tier 3 (auto with grace window)** — opt-in. On a git install, a newly detected release transitions execution state to `scheduled` and is applied after `preApplyGraceMinutes`. During the grace window, `/admin/update` shows a live countdown plus Cancel and Apply now buttons; an admin email (if `adminEmail` is set) fires once per scheduled tag.
 - **Tier 4 (autonomous in maintenance window)** — designed, not yet implemented.
 
 ## Settings
@@ -42,7 +42,7 @@ In `settings.json`:
 | `updates.checkIntervalHours` | `6` | How often to poll GitHub Releases. |
 | `updates.githubRepo` | `"ether/etherpad"` | Override for forks. |
 | `updates.requireAdminForStatus` | `false` | Lock the `/admin/update/status` endpoint to authenticated admin sessions. Default `false` matches existing Etherpad behavior — `/health` already exposes `releaseId` publicly, and changelog data comes from a public GitHub release. Set `true` to hide the full update payload from non-admins without disabling the updater (`tier: "off"` is the heavier opt-out that removes the endpoints entirely). |
-| `updates.preApplyGraceMinutes` | `0` | **Tier 3 only.** Wait this many minutes between detecting a new release and starting the drain so the admin can cancel. Has no effect at tier `"manual"`. |
+| `updates.preApplyGraceMinutes` | `0` | **Tier 3 only.** Wait this many minutes between detecting a new release and starting the drain so the admin can cancel via `/admin/update`. `0` applies immediately when allowed. Clamped to `[0, 7*24*60]` (one week). Has no effect at tier `"manual"`. |
 | `updates.drainSeconds` | `60` | How long to broadcast "restart imminent" announcements to active pads before exiting. T-60 / T-30 / T-10 broadcasts fire automatically at the matching offsets within this window. |
 | `updates.rollbackHealthCheckSeconds` | `60` | After a fresh boot post-update, give `/health` this long to come up. If it doesn't, RollbackHandler restores the previous SHA. |
 | `updates.diskSpaceMinMB` | `500` | Pre-flight refuses to start an update unless the install volume has at least this many MB free. |
@@ -156,6 +156,36 @@ The check shells out to `git verify-tag <tag>`. The keyring at `trustedKeysPath`
 
 Tier 2 deliberately refuses to apply on `installMethod: "docker"` because in-container `git fetch / pnpm install / build:ui` doesn't survive a container restart — the orchestrator brings the container back up on the same image tag and the work is lost. Docker installs stay on Tier 1 (banner + version status) for now.
 
+## Tier 3 — auto with grace window
+
+Tier 3 builds on Tier 2 by scheduling the apply automatically when a new release is detected. The same `git fetch / checkout / pnpm install / build:ui / exit 75` pipeline runs — only the trigger changes.
+
+To enable, on a git install: set `updates.tier: "auto"` and (optionally) `updates.preApplyGraceMinutes` to the grace duration you want.
+
+### What happens when a new release lands
+
+1. The periodic version checker (`updates.checkIntervalHours`) hits GitHub Releases.
+2. If `policy.canAuto` is true (install is git, no terminal `rollback-failed` state, tier is `"auto"` or `"autonomous"`), the scheduler transitions `execution.status` to `scheduled` with `scheduledFor = now + preApplyGraceMinutes`.
+3. The schedule is persisted to `var/update-state.json`, so an Etherpad restart inside the grace window rehydrates the timer rather than losing the schedule.
+4. `/admin/update` shows a live countdown panel plus two buttons:
+    - **Cancel** — `POST /admin/update/cancel` returns the state to `idle` and drops the in-process timer.
+    - **Apply now** — `POST /admin/update/apply` skips the remaining grace; the regular Tier 2 pipeline runs immediately.
+5. When the timer fires, the scheduler runs the exact same pipeline as a manual Tier 2 click: pre-flight → drain → execute → exit 75.
+
+### Re-scheduling and stale state
+
+- If a newer release tag appears while a schedule is pending, the scheduler re-arms the timer for the new tag. The `email.graceStartTag` dedupe field guards against duplicate `grace-start` notifications.
+- If `updates.tier` is flipped back to `"manual"` or `"notify"` while a schedule is pending, the next periodic check cancels the schedule (state back to `idle`).
+- `rollback-failed` disables Tier 3 globally. The admin must `POST /admin/update/acknowledge` (or visit `/admin/update` and click Acknowledge) before any further auto-schedules are armed. Tier 2 manual click stays available because the admin click *is* the intervention the terminal state requires.
+
+### Email (`adminEmail` set)
+
+A single `grace-start` notification fires per scheduled tag:
+
+> [Etherpad] Auto-update scheduled for 2.7.2
+
+with the `scheduledFor` timestamp. Etherpad core does not yet wire SMTP; the message logs as `(would send email)` until a future PR adds a transport. Cadence and dedupe still update correctly.
+
 The right way to give docker admins an in-product Apply button is to delegate to the orchestrator rather than mutate the container. Two patterns to consider in a follow-up PR:
 
 - **Instructions-only.** When the page detects `installMethod: docker` *and* a newer release exists, swap the policy-denial copy for actionable instructions (`docker pull etherpad/etherpad:<tag>` for plain docker; `docker compose pull && docker compose up -d` for compose). Cheap, no new attack surface.