@pellux/goodvibes-tui 2.0.14 → 2.0.16

package/src/runtime/session-inbound-inputs.ts

@@ -8,17 +8,17 @@
  * Charter: when the owning surface is LIVE (heartbeating within the daemon's
  * SURFACE_ROUTE_FRESHNESS window), a steer is DELIVERED to that surface rather
  * than spawning a daemon-side executor (which would fail on the daemon's empty
- * model registry). The daemon already does its half — `sessions.steer` /
+ * model registry). The daemon already does its half, `sessions.steer` /
  * `sessions.followUp` to a surface-managed session with a fresh participant
  * QUEUES the input for the surface (mode 'queued-for-surface') instead of
  * spawning. This poller is the surface completing that contract:
  *
  *   1. poll `sessions.inputs.list` for QUEUED inputs on ITS OWN sessionId
  *      (the query is scoped by sessionId, so a steer for another session can
- *      never land here — the per-session isolation the concurrent-sessions
+ *      never land here, the per-session isolation the concurrent-sessions
  *      charter requires);
  *   2. hand each steer/follow-up to `onSteer` (the surface-side injection into
- *      the TUI's turn machinery — narrate "steer received from <surface>" and
+ *      the TUI's turn machinery, narrate "steer received from <surface>" and
  *      fire the next-turn boundary), skipping the TUI's own submissions;
  *   3. acknowledge on the wire via `sessions.inputs.deliver` (queued → delivered)
  *      so every surface sees delivery truth live and the input is not re-picked.
@@ -26,7 +26,7 @@
  * Discipline (mirrors SessionSpineClient): every wire call is best-effort and
  * never throws into the render/keystroke path; a failed poll leaves the cursor
  * where it was so the input is retried on the next tick (deliver is the only
- * de-dup — an input already advanced past 'queued' is not returned again).
+ * de-dup, an input already advanced past 'queued' is not returned again).
  */
 
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
@@ -35,7 +35,7 @@ import type {
   SharedSessionInputRecord,
 } from '@pellux/goodvibes-sdk/platform/control-plane';
 
-/** The TUI's own participant surfaceId — inputs it authored are never re-injected. */
+/** The TUI's own participant surfaceId, inputs it authored are never re-injected. */
 export const TUI_SURFACE_ID = 'surface:tui';
 
 /** The narrow inbound wire surface this poller needs. Structurally satisfied by
@@ -75,7 +75,7 @@ export interface SessionInboundInputPollerOptions {
   readonly intervalMs?: number;
   readonly now?: () => number;
   readonly log?: InboundLogger;
-  /** The poller's own surfaceId — inputs it authored are skipped (default TUI). */
+  /** The poller's own surfaceId, inputs it authored are skipped (default TUI). */
   readonly ownSurfaceId?: string;
 }
 
@@ -92,7 +92,7 @@ export class SessionInboundInputPoller {
   private client: SpineInboundInputsClient | null = null;
   private timer: ReturnType<typeof setInterval> | null = null;
   private polling = false;
-  /** Exclusive createdAt cursor, per session — a session swap resets it. */
+  /** Exclusive createdAt cursor, per session, a session swap resets it. */
   private cursor = 0;
   private cursorSessionId: string | null = null;
 
@@ -120,7 +120,7 @@ export class SessionInboundInputPoller {
       this.timer = setInterval(() => { void this.pollOnce(); }, this.intervalMs);
       this.timer.unref?.();
     }
-    this.log.info('session inbound-input poller activated — collecting queued steers for this surface', {});
+    this.log.info('session inbound-input poller activated: collecting queued steers for this surface', {});
   }
 
   /** Detach the backend and stop polling (daemon mode resolved to non-external, or lost). */
@@ -185,9 +185,9 @@ export class SessionInboundInputPoller {
         try {
           this.onSteer(steer);
         } catch (error) {
-          // A failing injection must not wedge the poll loop or drop the ack —
+          // A failing injection must not wedge the poll loop or drop the ack,
           // narrate-and-continue; the input is still acked so it is not re-picked.
-          this.log.debug('session inbound steer injection threw — continuing', {
+          this.log.debug('session inbound steer injection threw; continuing', {
             error: error instanceof Error ? error.message : String(error),
           });
         }
@@ -196,14 +196,14 @@ export class SessionInboundInputPoller {
           await client.deliverInput(sessionId, input.id, { consumed: false });
           delivered += 1;
         } catch (error) {
-          this.log.debug('session inbound deliver ack failed — will retry', {
+          this.log.debug('session inbound deliver ack failed; will retry', {
             error: error instanceof Error ? error.message : String(error),
           });
         }
       }
     } catch (error) {
       // Poll failed entirely (daemon gone, transient): keep the cursor, retry next tick.
-      this.log.debug('session inbound-input poll failed — retry next tick', {
+      this.log.debug('session inbound-input poll failed: retry next tick', {
         error: error instanceof Error ? error.message : String(error),
       });
     } finally {

package/src/runtime/session-resume-liveness-confirm.ts

@@ -1,5 +1,5 @@
 /**
- * session-resume-liveness-confirm.ts — the "this session is open somewhere
+ * session-resume-liveness-confirm.ts, the "this session is open somewhere
  * else" check for the session-browser / panel resume seam.
  *
  * `/session resume <id>` already refuses to resume a session whose liveness
@@ -12,7 +12,7 @@
  * Semantics are unchanged from the text-command check and stay best-effort: a
  * missing, stale, or unreadable marker means "we can't tell", and the resume
  * proceeds exactly as it always did. The marker belonging to THIS process is
- * ignored too — re-resuming the session already open here is not a fork.
+ * ignored too, re-resuming the session already open here is not a fork.
  */
 import { checkSessionLiveness } from '@pellux/goodvibes-sdk/platform/runtime/operations';
 import type { SessionSurface } from '@/runtime/index.ts';
@@ -28,8 +28,8 @@ export type LiveResumeSelectionOpener = (
 /**
  * The confirm modal's title. Short by necessity: the selection overlay
  * truncates its title to the box width (selection-modal-overlay.ts), so
- * anything the operator must actually read — the pid, and what resuming would
- * do — belongs in a row's `detail`, which that overlay wraps instead.
+ * anything the operator must actually read, the pid, and what resuming would
+ * do, belongs in a row's `detail`, which that overlay wraps instead.
  */
 export const LIVE_RESUME_CONFIRM_TITLE = 'Session open elsewhere';
 

package/src/runtime/session-spine-transport.ts

@@ -11,7 +11,7 @@
  * satisfied by `HttpTransport.operator.sessions`), and `createTuiSpineTransport`
  * folds it into the SDK's `SpineTransport` the SAME way the SDK's own
  * consumability proof (`session-spine-daemon-integration.test.ts`) does:
- * resolve -> `'ok'`, throw -> `'offline'`. The TUI never emits `'rejected'` — it
+ * resolve -> `'ok'`, throw -> `'offline'`. The TUI never emits `'rejected'`, it
  * has no durable-refusal vocabulary to fold (that distinction is the agent's
  * REST mirror's job, per the SDK's divergence ruling #6/#7).
  */
@@ -25,7 +25,7 @@ import type { SpineResult, SpineTransport } from '@pellux/goodvibes-sdk/platform
 /**
  * The minimal wire surface this adapter needs. Structurally satisfied by BOTH
  * the SDK's in-process `OperatorClient['sessions']` (DirectTransport) and the
- * wire `HttpTransportOperatorClient['sessions']` (HttpTransport) — bootstrap.ts
+ * wire `HttpTransportOperatorClient['sessions']` (HttpTransport), bootstrap.ts
  * only ever constructs an Http-backed instance in practice, but this is
  * deliberately typed against the narrow shape rather than either concrete
  * transport type so it has no compile-time dependency on which transport
@@ -39,7 +39,7 @@ export interface SpineSessionsClient {
 /**
  * Adapt the TUI's typed `SpineSessionsClient` into the SDK `SessionSpineClient`'s
  * injected `SpineTransport`. A rejecting wire call is treated as a transient
- * connectivity fault (`'offline'`) rather than a durable refusal — the same
+ * connectivity fault (`'offline'`) rather than a durable refusal, the same
  * binary reachability model the pre-extraction TUI-local client used.
  */
 export function createTuiSpineTransport(sessionsClient: SpineSessionsClient): SpineTransport {

package/src/runtime/store/domains/panels.ts

@@ -1,5 +1,5 @@
 /**
- * Panels domain state — tracks the panel-first operator UX surfaces:
+ * Panels domain state, tracks the panel-first operator UX surfaces:
  * which panels are open, their layout, and focus state.
  */
 
@@ -43,7 +43,7 @@ export interface PanelState {
 }
 
 /**
- * PanelDomainState — panel layout and focus management.
+ * PanelDomainState, panel layout and focus management.
  */
 export interface PanelDomainState {
   // ── Domain metadata ────────────────────────────────────────────────────────

package/src/runtime/store/domains/ui-perf.ts

@@ -1,5 +1,5 @@
 /**
- * UI performance domain state — tracks TUI render performance,
+ * UI performance domain state, tracks TUI render performance,
  * frame rates, and input responsiveness metrics.
  */
 
@@ -31,7 +31,7 @@ export interface InputLatencySample {
 }
 
 /**
- * UiPerfDomainState — TUI render and input performance metrics.
+ * UiPerfDomainState, TUI render and input performance metrics.
  */
 export interface UiPerfDomainState {
   // ── Domain metadata ────────────────────────────────────────────────────────

package/src/runtime/store/index.ts

@@ -1,5 +1,5 @@
 /**
- * Runtime store — Zustand vanilla store for goodvibes-tui.
+ * Runtime store, Zustand vanilla store for goodvibes-tui.
  *
  * Uses `createStore` from `zustand/vanilla` (NOT the React `create` hook)
  * because goodvibes-tui is a terminal app with no React renderer.

package/src/runtime/store/selectors/index.ts

@@ -135,7 +135,7 @@ export const selectSurfacePerf = selectUiPerf;
 // Derived selectors
 // ---------------------------------------------------------------------------
 
-/** Active model summary — the three most-used fields for display and routing. */
+/** Active model summary, the three most-used fields for display and routing. */
 export interface ActiveModelSummary {
   providerId: string;
   modelId: string;

package/src/runtime/store/state.ts

@@ -1,5 +1,5 @@
 /**
- * RuntimeState — the canonical top-level state shape for the goodvibes-tui
+ * RuntimeState, the canonical top-level state shape for the goodvibes-tui
  * runtime store. All domain slices are defined here.
  *
  * Each domain includes revision, lastUpdatedAt, and source metadata fields.
@@ -66,7 +66,7 @@ import { createInitialIntelligenceState } from '@/runtime/index.ts';
 import { createInitialUiPerfState } from './domains/ui-perf.ts';
 
 /**
- * RuntimeState — the complete state shape managed by the runtime store.
+ * RuntimeState, the complete state shape managed by the runtime store.
  *
  * Domain slices, each with revision/lastUpdatedAt/source metadata.
  * All mutations must go through typed domain dispatch APIs.

package/src/runtime/ui-services.ts

@@ -42,7 +42,7 @@ export interface UiSessionServices {
   readonly sessionManager: RuntimeServices['sessionManager'];
   /**
    * The panel-facing session READ source is the cross-surface union
-   * facade, not the raw local broker — in adopted-daemon ('external') mode the
+   * facade, not the raw local broker, in adopted-daemon ('external') mode the
    * local broker misses sessions hosted for other surfaces. Sync signature
    * preserved; the facade's cache makes that honest (see session-union-cache.ts).
    */
@@ -59,7 +59,7 @@ export interface UiPlatformServices {
   readonly surfaceRegistry: RuntimeServices['surfaceRegistry'];
   readonly subscriptionManager: RuntimeServices['subscriptionManager'];
   readonly secretsManager: SecretsManager;
-  /** Per-device pairing tokens — backs the pairing modal QR and the settings device surface. */
+  /** Per-device pairing tokens, backs the pairing modal QR and the settings device surface. */
   readonly pairingTokens: RuntimeServices['pairingTokens'];
   readonly tokenAuditor: RuntimeServices['tokenAuditor'];
   readonly replayEngine: RuntimeServices['replayEngine'];
@@ -119,7 +119,7 @@ export interface UiRuntimeSharedServices {
     readonly processRegistry: RuntimeServices['processRegistry'];
     /** The Fleet panel's read model: local rows union the adopted daemon's. */
     readonly fleetReadModel: RuntimeServices['fleetReadModel'];
-    /** The shared runtime event bus — the Fleet panel subscribes to its 'communication' domain for the honest steer-consumed signal. */
+    /** The shared runtime event bus, the Fleet panel subscribes to its 'communication' domain for the honest steer-consumed signal. */
     readonly runtimeBus: RuntimeServices['runtimeBus'];
   };
 }

package/src/runtime/workspace-checkpointing.ts

@@ -4,7 +4,7 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { RuntimeEventBus, SessionSurface } from '@/runtime/index.ts';
 
 /**
- * createWorkspaceCheckpointing — build the per-workspace checkpoint manager and
+ * createWorkspaceCheckpointing, build the per-workspace checkpoint manager and
  * kick off its initialization. Extracted from services.ts so the (load-bearing)
  * failure-mode notes below live with the code they describe.
  */
@@ -22,14 +22,14 @@ export function createWorkspaceCheckpointing(opts: {
   configManager: ConfigManager;
 }): WorkspaceCheckpointManager {
   // Checkpoint root-guard from the user's `checkpoints.*` config (docs/configuration.md;
-  // inert until the platform SDK's checkpoint manager exposes the keys — see the reader's note).
+  // inert until the platform SDK's checkpoint manager exposes the keys, see the reader's note).
   const manager = new WorkspaceCheckpointManager(
     withCheckpointGuardSettings({ workspaceRoot: opts.workspaceRoot, surface: opts.surface, runtimeBus: opts.runtimeBus }, opts.configManager),
   );
   // Fire-and-forget: subscriptions go live immediately if init() succeeds.
   // If it rejects, WorkspaceCheckpointManager caches that rejection on
   // `initPromise` and never clears it, so every later call (create/list/
-  // diff/restore — each awaits init() first) re-throws the same error
+  // diff/restore, each awaits init() first) re-throws the same error
   // forever: checkpointing becomes entirely unavailable for the rest of the
   // session, not "degraded to manual-only". The `.catch(() => {})` here only
   // exists to prevent an unhandled rejection at startup; the checkpoint

package/src/runtime/wrfc-persistence.ts

@@ -1,5 +1,5 @@
 /**
- * WRFC chain persistence — snapshot active chains to disk on every lifecycle
+ * WRFC chain persistence, snapshot active chains to disk on every lifecycle
  * event so that a crash/restart can surface interrupted chains to the operator,
  * and so that terminal chains (passed/failed/cancelled) remain visible as
  * bounded history rather than vanishing the moment they finish.
@@ -20,14 +20,14 @@
  *
  *    A chain that looked interrupted (non-terminal) in the old snapshot can be
  *    reaped to terminal IN PLACE by `WrfcController.importChain` (the zombie-reap pass:
- *    no member agent survived the restart — see wrfc-controller.ts). This
+ *    no member agent survived the restart, see wrfc-controller.ts). This
  *    module always re-checks `chain.state` AFTER the import call, never the
  *    pre-import classification, so a reaped chain is treated as history, not
  *    re-surfaced as interrupted and never re-imported again on a later restart.
  *
  * 3. Terminal-history retention (bounded, most-recently-completed first):
  *    Previously, every terminal chain was pruned from the snapshot the moment
- *    it was written or rehydrated — a killed/finished chain vanished from
+ *    it was written or rehydrated, a killed/finished chain vanished from
  *    wrfc-chains.json entirely, including across a restart, so nothing could
  *    ever honestly report "last chain: <state>". Terminal chains are now
  *    RETAINED, capped at MAX_TERMINAL_HISTORY (20) most-recently-completed,
@@ -38,7 +38,7 @@
  *      - across a restart, via rehydrate() seeding that cache from whatever
  *        was already terminal in the prior snapshot instead of discarding it.
  *    A corrupt or version-mismatched snapshot is quarantined by renaming it
- *    to `<path>.unrecognized` — never a hard crash.
+ *    to `<path>.unrecognized`, never a hard crash.
  *
  * Snapshot path: `.goodvibes/tui/wrfc-chains.json`
  * Snapshot schema: `{ version: 1, writtenAt: number, chains: WrfcChain[] }`
@@ -58,7 +58,7 @@ const DEBOUNCE_MS = 250;
 /** Bounded terminal-history retention: keep the most recent K chains, prune beyond. */
 const MAX_TERMINAL_HISTORY = 20;
 
-/** Terminal states — chains in these states will not be surfaced as interrupted. */
+/** Terminal states, chains in these states will not be surfaced as interrupted. */
 const TERMINAL_STATES = new Set<WrfcState>(['passed', 'failed']);
 
 /** Non-terminal (interruptible) states. */
@@ -90,7 +90,7 @@ export interface WrfcControllerReader {
    * Re-import a chain recovered from a previous process so it reappears in the
    * controller's in-memory map and becomes selectable/resumable from the panel.
    * Optional so read-only test doubles can omit it; the real WrfcController
-   * provides it. `force` is left at its default — on a fresh start the map is
+   * provides it. `force` is left at its default, on a fresh start the map is
    * empty so importing never clobbers a live chain.
    */
   importChain?(chain: WrfcChain, force?: boolean): boolean;
@@ -99,9 +99,9 @@ export interface WrfcControllerReader {
 export interface WrfcPersistenceOptions {
   /** Absolute path to the snapshot file, e.g. `.goodvibes/tui/wrfc-chains.json`. */
   readonly snapshotPath: string;
-  /** Factory for the current SystemMessageRouter — may return null before it is wired. */
+  /** Factory for the current SystemMessageRouter, may return null before it is wired. */
   readonly getSystemMessageRouter: () => SystemMessageRouter | null;
-  /** WrfcController access — listChains() (read) plus optional importChain() (re-import on rehydrate). */
+  /** WrfcController access, listChains() (read) plus optional importChain() (re-import on rehydrate). */
   readonly controller: WrfcControllerReader;
 }
 
@@ -152,7 +152,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
   /**
    * Bounded terminal-history cache (most-recently-completed first once
    * trimmed). Survives past WrfcController's own in-memory cleanup of
-   * terminated chains (60s after termination — see wrfc-controller.ts
+   * terminated chains (60s after termination, see wrfc-controller.ts
    * scheduleChainCleanup) so a chain that ages out of listChains() is not
    * silently dropped from the persisted snapshot.
    */
@@ -209,7 +209,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
       // chain. The accessor is optional for read-only test doubles.
       //
       // NOTE: importChain may reap this chain to a terminal state IN PLACE
-      // (zombie reap: no member agent survived the restart) —
+      // (zombie reap: no member agent survived the restart),
       // always read chain.state AFTER this call below, never the pre-import
       // classification captured by candidateInterrupted.
       this.controller.importChain?.(chain);
@@ -218,7 +218,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
     // Re-partition after the reap check: a chain that looked interrupted
     // before import may now be terminal. Only genuinely still-live chains are
     // surfaced to the operator as interrupted; anything reaped just now joins
-    // history instead — it is done, not a resurrection candidate, and must
+    // history instead, it is done, not a resurrection candidate, and must
     // never be handed to importChain again on a future restart (a chain only
     // ever lands in candidateInterrupted while its persisted state is
     // non-terminal; once it's history its state is terminal for good).
@@ -230,7 +230,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
     for (const chain of this._interruptedChains) {
       const msg =
         `[WRFC] Chain ${chain.id.slice(0, 12)} (${chain.task.slice(0, 60).trim()}) ` +
-        `was interrupted by a restart — state was '${chain.state}' ` +
+        `was interrupted by a restart; state was '${chain.state}' ` +
         `after ${chain.reviewCycles} review cycle${chain.reviewCycles !== 1 ? 's' : ''}`;
       router?.wrfc(msg, 'high');
     }
@@ -238,7 +238,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
     // Rewrite the snapshot only when something actually changed: a chain was
     // reaped just now, or the history cap pruned an entry that was on disk.
     // Terminal chains are RETAINED (bounded to MAX_TERMINAL_HISTORY, most
-    // recently completed first) instead of erased — post-restart surfaces
+    // recently completed first) instead of erased, post-restart surfaces
     // (fleet, the resume notice, /wrfc history) need this to honestly report
     // e.g. "last chain: cancelled".
     if (reapedJustNow.length > 0 || alreadyTerminal.length !== this._terminalHistory.length) {
@@ -299,7 +299,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
   /**
    * Combine the live chains the controller is currently tracking with any
    * historical terminal chains the live map has already forgotten (e.g. after
-   * WrfcController's own 60s in-memory cleanup) — so the persisted file never
+   * WrfcController's own 60s in-memory cleanup), so the persisted file never
    * loses a terminal chain just because the live map stopped carrying it.
    * Live entries win on id collision since they are always the freshest copy.
    */
@@ -313,7 +313,7 @@ class WrfcPersistenceImpl implements WrfcPersistence {
     try {
       atomicWriteFileSync(this.snapshotPath, JSON.stringify(snapshot), { mkdirp: true });
     } catch {
-      // Best-effort — never crash the TUI over a persistence failure.
+      // Best-effort, never crash the TUI over a persistence failure.
     }
   }
 

package/src/scripts/process-messages.ts

@@ -1,4 +1,4 @@
-// CLI utility script — not imported by the app. console usage is intentional.
+// CLI utility script, not imported by the app. console usage is intentional.
 import { readFileSync } from 'fs';
 import { AgentMessageBus } from '@pellux/goodvibes-sdk/platform/agents';
 

package/src/shell/blocking-input.ts

@@ -9,7 +9,7 @@ export type PendingPermissionState = PermissionRequest & {
   detailsExpanded?: boolean;
   /**
    * Active typed-reply mode: 'deny-reason' (started by typing while the card
-   * is up — Enter denies with the typed reason as feedback) or 'exec-answer'
+   * is up, Enter denies with the typed reason as feedback) or 'exec-answer'
    * (an exec-prompt ask; Enter approves with the typed answer feeding the
    * running command's stdin). Undefined = plain card keys.
    */
@@ -19,8 +19,8 @@ export type PendingPermissionState = PermissionRequest & {
   /**
    * Epoch ms when the prompt first appeared. Keystrokes that arrive within
    * APPROVAL_INPUT_DEBOUNCE_MS of this are swallowed (not interpreted as an
-   * approve/deny response) so text typed ahead — before the user saw the
-   * prompt — cannot accidentally answer it.
+   * approve/deny response) so text typed ahead, before the user saw the
+   * prompt, cannot accidentally answer it.
    */
   openedAt?: number;
   /** Requester attribution ("session abc12345" / a named agent) shown on the prompt; absent when unknown. */
@@ -99,7 +99,7 @@ export function handleBlockingShellInput(
 
     // Typed-reply mode: deny-with-reason (started by typing on any card) or
     // exec-answer (an exec-prompt ask opens in this mode). Every printable
-    // key is text here — nothing is a card command.
+    // key is text here, nothing is a card command.
     if (req.replyMode) {
       const buffer = req.replyBuffer ?? '';
       if (data === '\r' || data === '\n') {
@@ -109,7 +109,7 @@ export function handleBlockingShellInput(
           req.resolve(true, false, { answer: buffer });
         } else {
           // Deny is feedback: the reason rides the structured "user declined"
-          // tool result so the model can adapt — the turn is NOT aborted.
+          // tool result so the model can adapt, the turn is NOT aborted.
           req.resolve(false, false, undefined, { reason: buffer });
         }
         render();
@@ -143,8 +143,8 @@ export function handleBlockingShellInput(
       return { handled: true, pendingPermission };
     }
 
-    // Scroll, mouse, PageUp/Down, arrow, and panel-navigation keys — plus a
-    // bare Esc — are not card answers. Pass them through to the normal input
+    // Scroll, mouse, PageUp/Down, arrow, and panel-navigation keys, plus a
+    // bare Esc, are not card answers. Pass them through to the normal input
     // handler so the transcript stays scrollable and Esc only drops focus. The
     // request stays pending (answer it with y/n or a remember tier when ready);
     // Ctrl+C above is still the hard abort, and 'n' still denies.
@@ -161,7 +161,7 @@ export function handleBlockingShellInput(
     }
 
     if (key === 'a') {
-      // Legacy always-this-session choice — the 'session' remember tier.
+      // Legacy always-this-session choice, the 'session' remember tier.
       req.resolve(true, true, undefined, { rememberTier: 'session' });
       render();
       return { handled: true, pendingPermission: null };
@@ -182,7 +182,7 @@ export function handleBlockingShellInput(
     }
 
     if (key === 'n') {
-      // Plain deny — feedback to the model (the SDK renders an honest "user
+      // Plain deny, feedback to the model (the SDK renders an honest "user
       // declined" result), never a turn abort. Ctrl+C above is the hard stop;
       // Esc drops focus (handled above) rather than denying.
       req.resolve(false, false);

package/src/shell/recovery-input-helpers.ts

@@ -9,7 +9,7 @@
  * happen ONLY when the user explicitly asks (a CLI flag, a slash command, or
  * a prompt), never automatically at bare launch (owner ruling). A live
  * recovery snapshot is now surfaced, never applied, by the boot resume
- * notice — see announceResumeState in runtime/resume-notice.ts.
+ * notice, see announceResumeState in runtime/resume-notice.ts.
  */
 
 export interface ErrorAffordanceDeps {
@@ -24,7 +24,7 @@ export interface ErrorAffordanceDeps {
 /**
  * Handle one keypress while the error-retry affordance is active.
  * 'r' retries on the current provider when armed; 'm' opens the model
- * picker — also gated on armed, since switching models here only makes
+ * picker, also gated on armed, since switching models here only makes
  * sense in service of the same retry this affordance is offering, not as a
  * general-purpose model-picker shortcut. Returns true when the key was
  * consumed; any other key (or 'm'/'r' while unarmed) returns false so the

package/src/shell/retry-affordance.ts

@@ -1,11 +1,11 @@
 /**
- * retry-affordance.ts — the one-key retry/switch-model affordance shown
+ * retry-affordance.ts, the one-key retry/switch-model affordance shown
  * right after a user-visible TURN_ERROR: 'r' re-submits on the current
  * provider, 'm' opens the model picker, any other key disarms it silently.
  *
  * Rendered as a transient FOOTER status line (see retryAffordanceHint,
  * wired into ShellFooterBuildOptions.retryHint in shell-surface.ts) rather
- * than a permanent transcript message — it disappears the moment it's
+ * than a permanent transcript message, it disappears the moment it's
  * disarmed, instead of sitting in the scrollback claiming an affordance
  * that no longer does anything. Extracted from main.ts to keep the
  * entrypoint under the architecture line cap.
@@ -13,7 +13,7 @@
  * The affordance is also time-bounded: arming starts a disarm timer so a
  * stray 'r' hours later can never fire a real, paid retry against the
  * provider. The timer's window is exactly what the footer hint's visibility
- * implies — when it fires, the state disarms AND retryAffordanceHint(state)
+ * implies, when it fires, the state disarms AND retryAffordanceHint(state)
  * goes back to null in the same tick, so the key dies at the same moment
  * the hint disappears.
  */
@@ -37,7 +37,7 @@ export interface RetryAffordanceState {
   exhausted: boolean;
   /** Internal: the pending disarm timer's handle, or null while unarmed. */
   timer: ReturnType<typeof setTimeout> | null;
-  /** Internal: injected timer primitives — real setTimeout/clearTimeout in production. */
+  /** Internal: injected timer primitives, real setTimeout/clearTimeout in production. */
   readonly schedule: RetryAffordanceSchedule;
   /** Internal: the disarm window in ms. */
   readonly windowMs: number;
@@ -50,7 +50,7 @@ export interface CreateRetryAffordanceStateOptions {
   readonly windowMs?: number;
   /** Overridable for tests so the disarm timer doesn't require a real 60s wait. */
   readonly schedule?: RetryAffordanceSchedule;
-  /** Called once the window elapses with no keypress and the state has been disarmed — main.ts hooks this to its render loop so the footer hint clears the instant the key goes dead. */
+  /** Called once the window elapses with no keypress and the state has been disarmed, main.ts hooks this to its render loop so the footer hint clears the instant the key goes dead. */
   readonly onExpire?: () => void;
 }
 
@@ -72,7 +72,7 @@ function clearPendingTimer(state: RetryAffordanceState): void {
   }
 }
 
-/** Arm the affordance — call only when a retry is actually possible (a live retryCtx).
+/** Arm the affordance, call only when a retry is actually possible (a live retryCtx).
  *  Starts (or restarts, if already armed) the disarm timer. */
 export function armRetryAffordance(state: RetryAffordanceState, exhausted: boolean): void {
   clearPendingTimer(state);
@@ -83,13 +83,13 @@ export function armRetryAffordance(state: RetryAffordanceState, exhausted: boole
     state.armed = false;
     state.onExpire?.();
   }, state.windowMs);
-  // Never let this timer hold the process open — a background retry-window
+  // Never let this timer hold the process open, a background retry-window
   // countdown is not a reason to keep the event loop alive.
   (timer as unknown as { unref?: () => void }).unref?.();
   state.timer = timer;
 }
 
-/** Disarm the affordance — any key other than the ones it recognizes disarms it,
+/** Disarm the affordance, any key other than the ones it recognizes disarms it,
  *  and cancels the pending disarm timer so it never fires on a state that's
  *  already been reset (or re-armed by a subsequent error). */
 export function disarmRetryAffordance(state: RetryAffordanceState): void {
@@ -106,7 +106,7 @@ export function retryAffordanceHint(state: RetryAffordanceState): string | null
 }
 
 /** Arm the affordance whenever a user-visible error surfaces AND a retry is
- *  actually possible — wired here (not inline in main.ts) to keep the
+ *  actually possible, wired here (not inline in main.ts) to keep the
  *  entrypoint under the architecture line cap. */
 export function wireRetryAffordanceOnError(
   onErrorSurfaced: (cb: (exhausted: boolean) => void) => void,