@pugi/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/core/repl/session.js

@@ -42,14 +42,33 @@ const MAX_TOOL_CALLS = 200;
 const MAX_RECONNECT_ATTEMPTS = 10;
 const RECONNECT_BASE_MS = 250;
 const RECONNECT_MAX_MS = 5_000;
+/**
+ * α6.5 filewatch throttle: minimum gap between two file-change
+ * system lines surfaced in the conversation pane. Per the sprint
+ * spec, a noisy save burst should not flood the transcript - we
+ * coalesce all chokidar batches that arrive inside the window into
+ * a single "file changed: ..." line.
+ */
+const FILEWATCH_SYSTEM_LINE_GAP_MS = 5_000;
+/**
+ * Hard cap on the size of `pendingFilewatchBatches`. The throttle window
+ * is 5s, but a `tsc --watch` style tool can fire dozens of `change`
+ * events per second for hours on end if the operator leaves the REPL
+ * up. Without a cap, every batch arriving inside the throttle window
+ * would accumulate forever, holding refs to thousands of FilewatchBatch
+ * objects (each carrying its own events array). On overflow we drop
+ * the OLDEST batch and surface a one-shot system warning so the
+ * operator knows the buffer is shedding. triple-review P1 (PR #380).
+ */
+const PENDING_FILEWATCH_BATCH_CAP = 100;
 /**
  * Cap on silent session-recreate attempts on HTTP 404 from the SSE
  * stream. When admin-api restarts it drops its in-memory session
  * store, so the saved sessionId returns 404 on every subscribe. The
  * CLI mints a fresh server session, swaps the consumer over, and
- * keeps running — but we cap the recovery to 3 attempts inside 60s
+ * keeps running - but we cap the recovery to 3 attempts inside 60s
  * so a truly down admin-api fails loud instead of spinning forever.
- * (α6.14.2 wave 5 — CEO dogfood fix.)
+ * (α6.14.2 wave 5 - CEO dogfood fix.)
  */
 const MAX_SESSION_RECREATE_ATTEMPTS = 3;
 const SESSION_RECREATE_WINDOW_MS = 60_000;
@@ -84,19 +103,19 @@ export class ReplSession {
      * `detail` field carries the cumulative model output. `agent.completed`
      * arrives last and previously overwrote the visible detail to the
      * literal string `'shipped'` while the transcript line said only
-     * `shipped.` — the actual reply text was lost. By caching the last
+     * `shipped.` - the actual reply text was lost. By caching the last
      * non-trivial detail here, we can flush it into the transcript when
      * the agent completes so the operator sees what the persona actually
      * said. CEO wave-2 fix 2026-05-25.
      */
     lastStepDetail = new Map();
     /**
-     * Optional local SessionStore — α6.4. When non-null, every
+     * Optional local SessionStore - α6.4. When non-null, every
      * appendRow() call mirrors the row into the JSONL log so the
      * conversation can be restored via `/resume`. Errors from the store
      * are swallowed to a single system line (degradation, not crash).
      * The store is opened by the CLI bootstrap and closed via
-     * `ReplSession.close()`. The store ownership is shared — the
+     * `ReplSession.close()`. The store ownership is shared - the
      * SqliteSessionStore is process-wide singleton-ish under the
      * lockfile, so close-on-quit is safe.
      */
@@ -111,15 +130,85 @@ export class ReplSession {
     localSessionId;
     /**
      * One-shot guard so a store error only emits ONE system line per
-     * session — without this, a stuck filesystem would spam the operator
+     * session - without this, a stuck filesystem would spam the operator
      * with `[store]` errors on every keystroke.
      */
     storeErrorEmitted = false;
+    /**
+     * Privacy mode fetched on bootstrap from /api/admin/privacy/mode and
+     * surfaced via `renderPrivacyBanner` (one-line system message after
+     * splash). Cached on the session so the in-REPL `/privacy` slash
+     * command can render the live mode without a second round-trip on
+     * the input box's thread. Null means "not yet fetched" (still
+     * connecting) OR "fetch failed" (offline / unauthenticated). The
+     * `/privacy` slash falls back to the contract doc with an "unknown"
+     * banner when null.
+     *
+     * Triple-review P1 fix (2026-05-25): the prior build defined
+     * `renderPrivacyBanner` but never called it, and `/privacy` always
+     * rendered with `null` mode. The contract was advertised but the
+     * operator had no mode visibility.
+     */
+    privacyMode = null;
+    /**
+     * α6.5 Tier 0 / Tier 1 / chokidar wiring. The bootstrap builds the
+     * skeleton + working set + watcher once and hands them to the
+     * session. The session uses them to:
+     *
+     *   - render `/context` (count + cap + total bytes + skeleton size).
+     *   - emit throttled "file changed" system lines on watcher batches.
+     *   - forget removed files from the working set on `unlink`.
+     *
+     * All three are optional - tests and minimal callers pass null /
+     * undefined and the session degrades to "no three-tier integration"
+     * silently. The watcher's own lifecycle is owned by the bootstrap
+     * (we do NOT close it in `close()`).
+     */
+    repoSkeleton;
+    workingSet;
+    watcher;
+    /**
+     * Epoch ms of the last filewatch system line. Initialised to 0 so
+     * the FIRST batch always emits; subsequent batches inside the gap
+     * are coalesced into the next emit window.
+     */
+    lastFilewatchLineAtEpochMs = 0;
+    /**
+     * Buffer of batches whose emission was throttled. Drained on the
+     * next within-window batch by overwriting the throttled line with
+     * a summary that mentions how many additional files were touched.
+     * Capped at PENDING_FILEWATCH_BATCH_CAP to bound memory growth
+     * under long-running noisy filewatch sources (tsc --watch on a
+     * 200-file project hammering for hours). triple-review P1 (PR #380).
+     */
+    pendingFilewatchBatches = [];
+    /**
+     * One-shot guard so the overflow-warning system line emits only once
+     * per session rather than spamming the operator with `[filewatch]
+     * shedding` on every dropped batch.
+     */
+    pendingFilewatchOverflowWarned = false;
+    /**
+     * Bound subscriber refs so close() can detach the listeners from the
+     * shared watcher. The bootstrap owns the watcher lifecycle (it calls
+     * watcher.close() on REPL teardown), but the session MUST detach its
+     * own listeners on close() so any chokidar event landing between
+     * session.close() and watcher.close() does not run handlers on a
+     * dead session. Without detachment, recordFilewatchBatch would
+     * touch this.workingSet / this.transcript on a closed session.
+     * triple-review P1 (PR #380).
+     */
+    filewatchBatchHandler = (batch) => {
+        this.recordFilewatchBatch(batch);
+    };
+    filewatchCapHandler = (info) => {
+        this.recordFilewatchCapExceeded(info);
+    };
     /**
      * Rolling dedupe set for `<pugi-ask>` and `<pugi-plan-review>`
      * signatures. The persona may emit the same envelope twice on network
      * retry; we suppress the duplicate so the operator does not see two
-     * stacked modals. Capped at 32 entries — generous for a real session,
+     * stacked modals. Capped at 32 entries - generous for a real session,
      * defensive against a hostile flood. (α6.3.)
      */
     seenTagSignatures = [];
@@ -144,6 +233,16 @@ export class ReplSession {
         this.options = options;
         this.store = options.store ?? null;
         this.localSessionId = options.localSessionId;
+        this.repoSkeleton = options.repoSkeleton ?? null;
+        this.workingSet = options.workingSet ?? null;
+        this.watcher = options.watcher ?? null;
+        // Subscribe to the chokidar watcher when present. Late-binding
+        // happens here so the bootstrap can construct the session and
+        // attach the watcher in one pass without re-validating shape.
+        if (this.watcher) {
+            this.watcher.on('batch', this.filewatchBatchHandler);
+            this.watcher.on('capExceeded', this.filewatchCapHandler);
+        }
         this.state = {
             sessionId: undefined,
             workspaceLabel: options.workspaceLabel,
@@ -187,12 +286,58 @@ export class ReplSession {
             });
             this.patch({ sessionId, connection: 'connecting' });
             this.openStream();
+            // alpha 6.13 privacy banner. Fire-and-forget - never blocks the
+            // input box on the network round-trip. The banner is a single
+            // system-line so the operator sees the active mode under the
+            // splash without an extra slash command. Mode is cached on the
+            // session so `/privacy` later renders the live value without a
+            // second fetch. Failure to fetch (offline, unauthenticated,
+            // admin-api down) is silent - the operator can still type
+            // `/privacy` to see the contract.
+            void this.fetchAndAnnouncePrivacyMode().catch(() => undefined);
         }
         catch (error) {
             this.appendSystemLine(`Could not open Pugi session: ${this.errorMessage(error)}`);
             this.patch({ connection: 'offline' });
         }
     }
+    /**
+     * Fetch the tenant's current privacy mode from
+     * `GET /api/admin/privacy/mode`, cache it on the session, and emit
+     * a one-line system banner so the operator sees their active mode
+     * right under the bootstrap splash. Failure is silent - missing
+     * banner is preferable to a noisy "could not fetch privacy mode"
+     * line on every login.
+     *
+     * Triple-review P1 fix (2026-05-25): without this call,
+     * `renderPrivacyBanner` was defined but never reached the wire, and
+     * `/privacy` always rendered with `null` mode.
+     */
+    async fetchAndAnnouncePrivacyMode() {
+        const { renderPrivacyBanner, isPrivacyMode } = await import('./privacy-banner.js');
+        try {
+            const url = `${this.options.apiUrl.replace(/\/+$/, '')}/api/admin/privacy/mode`;
+            const res = await fetch(url, {
+                headers: {
+                    authorization: `Bearer ${this.options.apiKey}`,
+                    accept: 'application/json',
+                },
+            });
+            if (!res.ok) {
+                // Silent fail - banner is decoration, not a blocking surface.
+                return;
+            }
+            const payload = (await res.json());
+            const mode = payload.mode;
+            if (typeof mode === 'string' && isPrivacyMode(mode)) {
+                this.privacyMode = mode;
+                this.appendSystemLine(renderPrivacyBanner(mode));
+            }
+        }
+        catch {
+            // Silent fail - offline / DNS / unauth all collapse to no banner.
+        }
+    }
     /**
      * Tear down the SSE stream and stop the reconnect timer. The session
      * id stays valid server-side; `pugi resume <id>` reopens later.
@@ -207,6 +352,16 @@ export class ReplSession {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = undefined;
         }
+        // Detach watcher listeners so any chokidar event landing between
+        // session.close() and the bootstrap-owned watcher.close() does NOT
+        // run a handler on a dead session. The handlers themselves also
+        // hard-guard on `this.closed`, but detaching is the load-bearing
+        // fix - it severs the strong reference the watcher held on the
+        // session callback, which otherwise blocks GC. triple-review P1 (PR #380).
+        if (this.watcher) {
+            this.watcher.off('batch', this.filewatchBatchHandler);
+            this.watcher.off('capExceeded', this.filewatchCapHandler);
+        }
     }
     /* ------------- input handling -------------- */
     /**
@@ -284,6 +439,10 @@ export class ReplSession {
                 await this.dispatchResume();
                 return verdict;
             }
+            case 'context': {
+                this.dispatchContext();
+                return verdict;
+            }
             case 'ask': {
                 // α6.3: synthesise a local yes/no `<pugi-ask>` modal so the
                 // operator can exercise the question UI without a persona-side
@@ -299,6 +458,15 @@ export class ReplSession {
                 this.patch({ pendingAsk: askTag, pendingAskSource: 'local' });
                 return verdict;
             }
+            case 'privacy': {
+                // alpha 6.13: print the full mode contract + current banner
+                // inline. The current mode is resolved lazily by the helper -
+                // when unauthenticated or offline the banner falls back to
+                // "(unknown - mode lookup pending)" and the contract doc still
+                // renders so the operator can read the alternatives.
+                await this.dispatchPrivacy();
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;
@@ -306,7 +474,26 @@ export class ReplSession {
         }
     }
     /**
-     * In-REPL `/resume` — α6.4. Lists the 10 most recent sessions from
+     * In-REPL `/privacy` - alpha 6.13. Prints the full 3-mode contract
+     * doc + the current mode banner inline. The current mode is fetched
+     * via the admin-api /api/admin/privacy/mode endpoint when the
+     * operator is authenticated; otherwise the banner falls back to
+     * "(unknown)" and the contract doc still renders so the operator
+     * can compare modes without leaving the REPL.
+     */
+    async dispatchPrivacy() {
+        const { renderPrivacyContractDoc } = await import('./privacy-banner.js');
+        // Triple-review P1 fix (2026-05-25): use the bootstrap-cached mode
+        // so the operator sees the LIVE current mode in the banner header
+        // instead of "(unknown)". The fetch happens once on session start;
+        // if it failed (offline / unauth) the cache stays null and the
+        // banner falls back to "(unknown)" - same UX as before, just with
+        // the happy path actually delivering the mode.
+        const doc = renderPrivacyContractDoc(this.privacyMode);
+        this.appendSystemLine(doc);
+    }
+    /**
+     * In-REPL `/resume` - α6.4. Lists the 10 most recent sessions from
      * the local SessionStore and prints them as a numbered system menu.
      * The Ink-side picker UI is deferred to the next sprint; today the
      * operator gets a deterministic list + the exact command to relaunch
@@ -352,12 +539,12 @@ export class ReplSession {
     /* ------------- α6.3 office-hours surface -------------- */
     /**
      * Surface an `<pugi-ask>` modal manually. Returned promise resolves
-     * with the operator's verdict — used by the `pugi ask "<q>"` shell
+     * with the operator's verdict - used by the `pugi ask "<q>"` shell
      * command and by the `/ask` slash. The resolver is wired into the
      * session state via `pendingAsk` so the REPL UI can render the modal
      * and forward `onResolve` back through `resolveAsk()`.
      *
-     * NOTE: idempotent on a duplicate signature — a second presentAsk
+     * NOTE: idempotent on a duplicate signature - a second presentAsk
      * with the same question + option values returns the first
      * outstanding promise rather than stacking two modals.
      */
@@ -370,7 +557,7 @@ export class ReplSession {
             return this.outstandingAskPromise;
         }
         // If a DIFFERENT ask is open, reject the new one with a clear
-        // error rather than silently queueing — the persona should never
+        // error rather than silently queueing - the persona should never
         // emit two concurrent asks, and surfacing the bug fails loud.
         if (this.outstandingAskPromise) {
             return Promise.reject(new Error('presentAsk: another ask is already pending. Resolve it first.'));
@@ -584,6 +771,129 @@ export class ReplSession {
         this.appendSystemLine(`Workspace: ${this.state.workspaceLabel}.`);
         this.appendSystemLine(`CLI: pugi ${this.state.cliVersion}.`);
     }
+    /**
+     * α6.5 `/context` slash handler. Surfaces the three-tier context
+     * summary as a stack of system lines. Sections (in order):
+     *
+     *   1. Tier 0 (repo skeleton) - size in bytes, branch, package
+     *      manager, languages. Skipped when no skeleton was injected
+     *      (REPL launched outside a workspace or with --no-context).
+     *
+     *   2. Tier 1 (working set) - `count / capacity` plus the total
+     *      size in bytes plus the oldest entry's age in seconds.
+     *      Always emits even when empty so the operator can confirm
+     *      the tier is wired.
+     *
+     *   3. Tier 2 (RAG) - one-line heads-up that the Anvil-side
+     *      workspace lands in α6.5b.
+     *
+     * The renderer never mutates state.
+     */
+    dispatchContext() {
+        if (this.repoSkeleton) {
+            const parts = [`Tier 0 skeleton: ${this.repoSkeleton.totalSize} bytes`];
+            if (this.repoSkeleton.branch)
+                parts.push(`branch ${this.repoSkeleton.branch}`);
+            if (this.repoSkeleton.packageManager)
+                parts.push(this.repoSkeleton.packageManager);
+            if (this.repoSkeleton.primaryLanguages.length > 0) {
+                parts.push(`langs ${this.repoSkeleton.primaryLanguages.slice(0, 3).join('/')}`);
+            }
+            this.appendSystemLine(parts.join(' - '));
+        }
+        else {
+            this.appendSystemLine('Tier 0 skeleton: not loaded (run pugi init or launch in a workspace).');
+        }
+        if (this.workingSet) {
+            const summary = this.workingSet.summary();
+            const ageLine = summary.oldestTouchedAtEpochMs !== null
+                ? ` - oldest touch ${formatAgeSeconds(this.now() - summary.oldestTouchedAtEpochMs)} ago`
+                : '';
+            this.appendSystemLine(`Tier 1 working set: ${summary.count}/${summary.capacity} files, ${summary.totalSizeBytes} bytes${ageLine}.`);
+        }
+        else {
+            this.appendSystemLine('Tier 1 working set: not wired.');
+        }
+        this.appendSystemLine('Tier 2 RAG: deferred to α6.5b (Anvil-side per-tenant workspace).');
+    }
+    /**
+     * α6.5 chokidar batch handler. Forwards each event to the working
+     * set tracker (so `unlink` evicts and `add`/`change` bump the
+     * recency) and emits at most one throttled system line per
+     * `FILEWATCH_SYSTEM_LINE_GAP_MS` window.
+     *
+     * The transcript surface intentionally shows ONE filename + the
+     * count of additional changes (`file changed: src/foo.ts (+3 more)`).
+     * The full event list is preserved in the buffer for future
+     * `/context --files` deep-dive (not in α6.5 Phase 1).
+     */
+    recordFilewatchBatch(batch) {
+        // Hard-guard against post-close invocation. close() detaches the
+        // watcher listeners, but the EventEmitter contract allows the
+        // currently-dispatching emit() call to finish delivering to every
+        // listener captured at the start of emit(). If the session closes
+        // mid-emit, the handler can still fire on a dead session. Returning
+        // early keeps the working set + transcript untouched.
+        // triple-review P1 (PR #380).
+        if (this.closed)
+            return;
+        if (this.workingSet) {
+            for (const event of batch.events) {
+                if (event.kind === 'unlink') {
+                    this.workingSet.forget(event.absPath);
+                }
+                // Note: we do NOT auto-track add/change here. The working set
+                // reflects files the AGENT touched - filewatch is informational.
+                // Future wiring: bash/read/edit tools will call track() directly.
+            }
+        }
+        const nowMs = this.now();
+        const sinceLast = nowMs - this.lastFilewatchLineAtEpochMs;
+        if (sinceLast < FILEWATCH_SYSTEM_LINE_GAP_MS && this.lastFilewatchLineAtEpochMs !== 0) {
+            // Inside the throttle window - buffer for future deep-dive but
+            // do not emit a system line. Cap the buffer at
+            // PENDING_FILEWATCH_BATCH_CAP and drop the oldest on overflow so
+            // a noisy filewatch source cannot drive unbounded memory growth
+            // across a long REPL session. triple-review P1 (PR #380).
+            if (this.pendingFilewatchBatches.length >= PENDING_FILEWATCH_BATCH_CAP) {
+                this.pendingFilewatchBatches.shift();
+                if (!this.pendingFilewatchOverflowWarned) {
+                    this.pendingFilewatchOverflowWarned = true;
+                    this.appendSystemLine(`Filewatch buffer at cap (${PENDING_FILEWATCH_BATCH_CAP} batches) - shedding oldest. Source may be a build watcher in a tight loop.`);
+                }
+            }
+            this.pendingFilewatchBatches.push(batch);
+            return;
+        }
+        const totalEvents = this.pendingFilewatchBatches.reduce((acc, b) => acc + b.events.length, 0) + batch.events.length;
+        const head = batch.events[0];
+        if (!head) {
+            // Empty batch - should not happen given the watcher guards,
+            // but defensive.
+            this.pendingFilewatchBatches = [];
+            return;
+        }
+        const wsLine = this.workingSet
+            ? ` (working set: ${this.workingSet.size()}/${this.workingSet.capacityLimit()})`
+            : '';
+        const tail = totalEvents > 1 ? ` (+${totalEvents - 1} more)` : '';
+        this.appendSystemLine(`file ${head.kind}: ${head.path}${tail}${wsLine}`);
+        this.lastFilewatchLineAtEpochMs = nowMs;
+        this.pendingFilewatchBatches = [];
+    }
+    /**
+     * α6.5 chokidar cap-exceeded handler. The watcher closes itself
+     * when it crosses the watched-paths cap; the session surfaces a
+     * single system line so the operator knows live updates are off.
+     * The conversation stays usable - we just lose the file-changed
+     * badge for the rest of the session.
+     */
+    recordFilewatchCapExceeded(info) {
+        // Same post-close guard as recordFilewatchBatch. triple-review P1 (PR #380).
+        if (this.closed)
+            return;
+        this.appendSystemLine(`Filewatch off: ${info.watchedCount} watched paths exceeded cap (${info.cap}). Falling back to manual stat-on-read.`);
+    }
     /**
      * Fetch one URL via the web_fetch tool and inject the resulting
      * Markdown into the transcript as an operator-attributed brief. The
@@ -716,11 +1026,11 @@ export class ReplSession {
                 // synchronously in some transports). If that second 404 arrives
                 // with recreatingSession === true, we must SHORT-CIRCUIT it too
                 // rather than fall through to the legacy "Stream interrupted"
-                // path — otherwise the operator sees the exact 404 line the
+                // path - otherwise the operator sees the exact 404 line the
                 // recreate is trying to suppress.
                 if (this.isSessionNotFoundError(error)) {
                     if (this.recreatingSession) {
-                        // Recreate already in flight — drop the duplicate 404 on the
+                        // Recreate already in flight - drop the duplicate 404 on the
                         // floor. The first recreate will either succeed (new stream
                         // opens, this dead handle is gone) or fall through to the
                         // loud "keeps dropping" / "session recreate refused" paths
@@ -770,7 +1080,7 @@ export class ReplSession {
             this.recentRecreateAtMs.shift();
         }
         if (this.recentRecreateAtMs.length >= MAX_SESSION_RECREATE_ATTEMPTS) {
-            // Cap exceeded — fall back to the loud "give up" path so the
+            // Cap exceeded - fall back to the loud "give up" path so the
             // operator sees something is actually wrong.
             this.appendSystemLine('Admin API session keeps dropping (HTTP 404 x3). Type /quit and `pugi resume` to retry.');
             this.patch({ connection: 'offline' });
@@ -784,7 +1094,7 @@ export class ReplSession {
             this.streamHandle.close();
             this.streamHandle = undefined;
         }
-        // Reset reconnect attempt + lastEventId — the new session is a
+        // Reset reconnect attempt + lastEventId - the new session is a
         // fresh stream, not a continuation of the dead one.
         this.reconnectAttempt = 0;
         this.lastEventId = undefined;
@@ -804,7 +1114,7 @@ export class ReplSession {
             this.openStream();
         }
         catch (error) {
-            // The recreate POST itself failed — fall back to the existing
+            // The recreate POST itself failed - fall back to the existing
             // backoff reconnect so the operator still sees retry progress.
             this.appendSystemLine(`Session recreate refused (${this.errorMessage(error)}). Reconnecting.`);
             this.scheduleReconnect();
@@ -964,7 +1274,7 @@ export class ReplSession {
                         // splits per line so word-wrap stays correct.
                         //
                         // Claude triple-review P1 (PR #369): the prior `includes('```')`
-                        // gate only caught fences — multi-line bullets fragmented
+                        // gate only caught fences - multi-line bullets fragmented
                         // per row showed as `▸ Mira • read PUGI.md / ▸ Mira • patched
                         // bug / ...` instead of a single grouped bullet block.
                         if (looksLikeMarkdown(finalDetail)) {
@@ -1076,7 +1386,7 @@ export class ReplSession {
         // colon / whitespace) so the prefix the pane adds is the only one
         // visible. We also drop any leaked `<workspace-context-NONCE>`
         // wrapper the model sometimes echoes back at the head of its
-        // first turn — that envelope is for prompt scaffolding, not for
+        // first turn - that envelope is for prompt scaffolding, not for
         // the operator's eyes.
         const stripped = stripPersonaPrefixEcho(personaSlug, text);
         this.appendRow({ source: 'persona', text: stripped, personaSlug });
@@ -1106,7 +1416,7 @@ export class ReplSession {
      * Best-effort write of one transcript row into the local
      * SessionStore. Swallows errors after emitting one system line so a
      * broken store never blocks the conversation. Public callers go
-     * through `appendRow` — this method is private on purpose.
+     * through `appendRow` - this method is private on purpose.
      */
     persistRow(row) {
         if (!this.store)
@@ -1138,14 +1448,14 @@ export class ReplSession {
         });
     }
     /**
-     * Restore a transcript from a stored event log — α6.4. Called by
+     * Restore a transcript from a stored event log - α6.4. Called by
      * the CLI bootstrap when the operator runs `pugi resume <id>` or
      * picks an entry from the `/resume` picker. Replays each event into
      * the local transcript WITHOUT writing back to the store so the
      * restore is idempotent.
      *
      * Implementation note: we briefly disable persistence by setting
-     * `storeErrorEmitted` BEFORE the replay and clearing it after — but
+     * `storeErrorEmitted` BEFORE the replay and clearing it after - but
      * the cleaner path is to bypass `appendRow` entirely and patch
      * state directly. We do the latter so persistRow does not double-
      * write the restored events.
@@ -1157,7 +1467,7 @@ export class ReplSession {
             if (row)
                 rows.push(row);
         }
-        // Cap at MAX_TRANSCRIPT_ROWS — the same cap appendRow uses so the
+        // Cap at MAX_TRANSCRIPT_ROWS - the same cap appendRow uses so the
         // window math stays consistent post-restore.
         const capped = rows.slice(-MAX_TRANSCRIPT_ROWS);
         this.patch({ transcript: capped });
@@ -1193,7 +1503,7 @@ export class ReplSession {
         // a fresh `agent.step` carries the full body up to the current
         // token (matches the wave-2 caching contract above). We pass the
         // raw detail through the extractors directly rather than keeping a
-        // separate buffer — but we still record the pre-extraction body so
+        // separate buffer - but we still record the pre-extraction body so
         // a partial open tag is preserved when the next chunk arrives.
         this.askBuffer.set(taskId, detail);
         const askResult = extractAskTags(detail);
@@ -1202,7 +1512,7 @@ export class ReplSession {
             if (this.seenTagSignatures.includes(tag.signature))
                 continue;
             this.recordSeenTag(tag.signature);
-            // Only one pending ask at a time — drop additional tags in the
+            // Only one pending ask at a time - drop additional tags in the
             // same step into the cleaned body as a system warning. The
             // persona's prompt forbids concurrent asks, so this branch is a
             // defensive guard against a misbehaving model.
@@ -1287,7 +1597,7 @@ export class ReplSession {
 /**
  * Map a stored SessionEvent back into a TranscriptRow for `/resume`
  * replay. Returns null when the event has no operator-visible body
- * (e.g. tool.start without a text payload — those land back as
+ * (e.g. tool.start without a text payload - those land back as
  * tool stream rows, not transcript rows). The shape mirrors the
  * `persistRow` mapping in reverse:
  *
@@ -1345,7 +1655,7 @@ function eventToTranscriptRow(event) {
 /**
  * Heuristic: does this text contain Markdown structures that benefit
  * from atomic grouping? Code fences, bullet lists, numbered lists,
- * headings — anything where per-line splitting would fragment visual
+ * headings - anything where per-line splitting would fragment visual
  * grouping (Claude triple-review P1 PR #369).
  */
 function looksLikeMarkdown(text) {
@@ -1375,6 +1685,31 @@ function safePersonaName(role) {
         return role;
     }
 }
+/**
+ * Render a millisecond delta as a compact human-readable age. Used by
+ * `/context` to surface the oldest working-set entry's age:
+ *
+ *   < 60s        -> `45s`
+ *   < 1h         -> `4m`
+ *   < 24h        -> `2h`
+ *   >= 24h       -> `3d`
+ *
+ * Negative deltas (clock skew) clamp to `0s`.
+ */
+function formatAgeSeconds(deltaMs) {
+    const ms = Math.max(0, deltaMs);
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.floor(hours / 24);
+    return `${days}d`;
+}
 /**
  * Convenience: list the legal role slugs the operator can target with
  * `/stop`. Surfaced in the slash command help overlay and in the
@@ -1474,7 +1809,7 @@ function parseStatusFromTail(tail) {
 /*                                                                    */
 /* Mirrors `tui/ask-modal.tsx#encodeAskVerdict` so the session can     */
 /* synthesise the operator-side echo without dragging an Ink module    */
-/* into the test surface. The two encoders MUST agree byte-for-byte —  */
+/* into the test surface. The two encoders MUST agree byte-for-byte -  */
 /* a divergence would silently mis-prefix the persona's follow-up.    */
 /* ------------------------------------------------------------------ */
 function encodeAskVerdictLocal(verdict) {
@@ -1629,10 +1964,10 @@ export function synthesiseLocalAskTag(question) {
  *   "<workspace-context-abc>Pugi, привет" -> "привет"
  *   "обычный ответ без префикса"          -> "обычный ответ без префикса"
  *
- * The strip is conservative — we only remove the display name when it
+ * The strip is conservative - we only remove the display name when it
  * is followed by a separator (comma, colon, dash, space) so a sentence
  * that legitimately contains the name mid-text ("спроси у Pugi") is
- * not mangled. (α6.14.2 wave 5 — CEO dogfood fix.)
+ * not mangled. (α6.14.2 wave 5 - CEO dogfood fix.)
  */
 export function stripPersonaPrefixEcho(personaSlug, text) {
     let working = text.trimStart();
@@ -1652,7 +1987,7 @@ export function stripPersonaPrefixEcho(personaSlug, text) {
     }
     // Resolve the display name from the canonical roster. Unknown slugs
     // (forward-compat with future personas streamed by a newer server)
-    // skip the strip — better to leave the text alone than to mis-strip.
+    // skip the strip - better to leave the text alone than to mis-strip.
     const persona = getPersona(personaSlug);
     if (!persona)
         return working;
@@ -1671,7 +2006,7 @@ export function stripPersonaPrefixEcho(personaSlug, text) {
     // name two or three times back-to-back when the pane prefix also
     // injects "▸ Pugi"; without the loop, only the first token would be
     // peeled and the operator would still see "▸ Pugi Pugi, координатор".
-    // Cap at 3 iterations — beyond that the text is either pathological
+    // Cap at 3 iterations - beyond that the text is either pathological
     // or unrelated and we should not keep chewing it. Bail when an
     // iteration makes no progress to avoid infinite loops on a regex that
     // matches an empty string (defence-in-depth even though the current