@pellux/goodvibes-tui 2.0.14 → 2.0.16

package/src/runtime/recovery-prompt.ts

@@ -1,9 +1,9 @@
 /**
- * recovery-prompt.ts — the startup "a recovery snapshot exists, do you want
+ * recovery-prompt.ts, the startup "a recovery snapshot exists, do you want
  * it?" flow.
  *
  * A crash-recovery snapshot used to get one sentence in the boot resume
- * notice, which left the operator to read it and retype a command — and for a
+ * notice, which left the operator to read it and retype a command, and for a
  * session that crashed before its first clean save, there was no command that
  * reached the snapshot at all, so the sentence was a dead end. This module
  * replaces that with an explicit two-step ask:
@@ -14,13 +14,13 @@
  * Rules this flow keeps:
  *   - Nothing is ever applied without the user picking Resume. There is no
  *     silent auto-restore path here, and this module never loads a snapshot
- *     just to look at it — `checkRecoveryFile` reports, and only an explicit
+ *     just to look at it, `checkRecoveryFile` reports, and only an explicit
  *     yes reaches the code that opens the file.
  *   - The SDK's `applyRecoverySnapshot` is what runs on that yes, and it will
  *     not run without the confirmation token this flow hands it. It reads,
  *     retires and applies in one operation, load-then-delete: the file is
  *     retired only after a successful load, so a failed read can never destroy
- *     state that was never actually recovered — and a successful load can
+ *     state that was never actually recovered, and a successful load can
  *     never leave a restored snapshot behind to be offered again.
  *   - Every fact shown is one we actually have (session id, snapshot age,
  *     title when the snapshot carries one, byte size when the file is where
@@ -44,8 +44,8 @@
  *     is offered again on the next launch, not again in this one.
  *   - Remove is permanent, not just for this file. The decision is written to
  *     the durable ledger in recovery-decisions.ts, so a snapshot that comes
- *     back byte-for-byte — because a session still running on an older build
- *     is rewriting it every minute — is deleted on sight instead of asked
+ *     back byte-for-byte, because a session still running on an older build
+ *     is rewriting it every minute, is deleted on sight instead of asked
  *     about again. Deleting the file used to be the entire memory of the
  *     answer, which is how the same question survived being answered three
  *     times.
@@ -79,7 +79,7 @@ export type SelectionOpener = (
 
 export interface RecoveryPromptDeps {
   readonly surface: SessionSurface;
-  /** The shell's selection-modal opener. Absent in headless hosts — the flow then does nothing at all. */
+  /** The shell's selection-modal opener. Absent in headless hosts, the flow then does nothing at all. */
   readonly openSelection: SelectionOpener | undefined;
   /**
    * Apply an explicitly-accepted snapshot to the live conversation and report
@@ -106,7 +106,7 @@ export interface RecoveryPromptDeps {
    * session (`checkRecoveryFile`). Used by the `--continue` / bare `--resume`
    * pre-resume check (cli/tui-startup.ts): resuming a named session straight
    * from its durable store would silently drop the tail of messages held only
-   * in a snapshot newer than that store — the same rule `checkRecoveryFile`
+   * in a snapshot newer than that store, the same rule `checkRecoveryFile`
    * uses, just scoped to the one session being resumed instead of "whichever
    * session has the newest snapshot".
    */
@@ -115,7 +115,7 @@ export interface RecoveryPromptDeps {
 
 // ─── Honest fact formatting ─────────────────────────────────────────────────
 
-/** Human-readable age of a snapshot. Coarse on purpose — the exact second is not a fact worth claiming. */
+/** Human-readable age of a snapshot. Coarse on purpose, the exact second is not a fact worth claiming. */
 export function formatSnapshotAge(ageMs: number): string {
   if (ageMs < 0) return 'just now';
   const minutes = Math.floor(ageMs / 60_000);
@@ -155,7 +155,7 @@ export function describeRecoverySnapshot(
 
 /**
  * The offer modal's rows. The snapshot's facts ride on the Resume row's
- * `detail` — both because that is where they are decision-relevant ("this is
+ * `detail`, both because that is where they are decision-relevant ("this is
  * what you would be loading") and because `detail` is the only field the
  * selection overlay wraps rather than truncates, so the full description
  * survives any terminal width.
@@ -226,8 +226,8 @@ function defaultSnapshotBytes(surface: SessionSurface, sessionId: string): numbe
 
 /**
  * Snapshots the user has already answered about (Keep or dismissal) during
- * this process's lifetime. Two offer paths exist in one boot — the targeted
- * pre-resume check for `--continue`/`--resume` and the general startup offer —
+ * this process's lifetime. Two offer paths exist in one boot, the targeted
+ * pre-resume check for `--continue`/`--resume` and the general startup offer,
  * and both can find the same snapshot; an answer given to either binds both,
  * so "stays quiet for the rest of the run" holds across the pair. Resume and
  * Remove retire the file itself, so only the declined cases need remembering.
@@ -236,7 +236,7 @@ const answeredThisRun = new Set<string>();
 
 /**
  * Test seam: a fresh process has no answered offers. Only clears the
- * in-process Keep memory — removal decisions are durable on purpose and live
+ * in-process Keep memory, removal decisions are durable on purpose and live
  * in the surface's own directory, so a test gets a clean ledger by using a
  * fresh temp surface, the same way a real user gets one by using a different
  * machine.
@@ -259,7 +259,7 @@ const MAX_RECORDED_REMOVAL_PASSES = 8;
  *
  * A snapshot whose session is in the removal ledger is deleted here and NOT
  * offered: the user answered that question already, and re-asking because the
- * file came back is the defect. Deleting rather than merely skipping matters —
+ * file came back is the defect. Deleting rather than merely skipping matters,
  * skipping would leave the file to mask an older, genuinely-orphaned snapshot
  * underneath it forever.
  */
@@ -298,7 +298,7 @@ export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<R
     // targeted --continue offer and the general startup offer can both find
     // it). The earlier answer stands; don't ask twice.
     if (answeredThisRun.has(info.sessionId)) return 'kept';
-    // Another terminal is actively refreshing this snapshot — it is that
+    // Another terminal is actively refreshing this snapshot, it is that
     // instance's live state, not an orphaned crash.
     if (checkSessionLiveness(deps.surface, info.sessionId).live) return 'none';
     const open = deps.openSelection;
@@ -318,8 +318,8 @@ export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<R
         // is gone" are not the same news.
         deps.receipt(
           result.refusal === 'no-snapshot'
-            ? 'Recovery snapshot could not be read — it was left on disk and will be offered again next launch.'
-            : `Recovery snapshot for session ${info.sessionId} could not be restored — the file was damaged, and reading it retired it. Nothing was changed in this session.`,
+            ? 'Recovery snapshot could not be read; it was left on disk and will be offered again next launch.'
+            : `Recovery snapshot for session ${info.sessionId} could not be restored; the file was damaged, and reading it retired it. Nothing was changed in this session.`,
         );
         deps.render();
         return 'resume-failed';
@@ -345,14 +345,14 @@ export async function offerRecoverySnapshot(deps: RecoveryPromptDeps): Promise<R
       // it in the first place.
       recordRecoveryRemoval(deps.surface, info.sessionId);
       deps.receipt(removed
-        ? `Recovery point removed (session ${info.sessionId}) — it will not be offered again, even if the file reappears.`
-        : `No recovery point was found to remove (session ${info.sessionId}) — if one reappears for that session it will be discarded, not offered.`);
+        ? `Recovery point removed (session ${info.sessionId}): it will not be offered again, even if the file reappears.`
+        : `No recovery point was found to remove (session ${info.sessionId}): if one reappears for that session it will be discarded, not offered.`);
       deps.render();
       return 'removed';
     }
 
     answeredThisRun.add(info.sessionId);
-    deps.receipt(`Recovery point kept (session ${info.sessionId}) — it will be offered again next launch.`);
+    deps.receipt(`Recovery point kept (session ${info.sessionId}): it will be offered again next launch.`);
     deps.render();
     return 'kept';
   } catch {

package/src/runtime/relay-reachability-bridge.ts

@@ -1,5 +1,5 @@
 /**
- * relay-reachability-bridge.ts — what this terminal can honestly say about the
+ * relay-reachability-bridge.ts, what this terminal can honestly say about the
  * outbound relay's live state.
  *
  * The relay is a DAEMON capability. The reachability controller is composed
@@ -9,7 +9,7 @@
  * registers with the relay and can mint a pairing payload for it.
  *
  * This terminal is a client. It never constructs a `DaemonServer`, so it holds
- * no controller of its own, and it has no handle to the adopted daemon's — the
+ * no controller of its own, and it has no handle to the adopted daemon's, the
  * control plane exposes no verb for one. The operator contract's `relay`
  * category carries the two step-up ceremony verbs (`stepup.challenge.mint`,
  * `stepup.credential.register`) and nothing that reports registration state or
@@ -55,7 +55,7 @@ export interface RelayReadAccessors {
  */
 export const RELAY_STATE_NOT_READABLE_HERE =
   'The daemon holds the relay connection and the control plane exposes no verb for its state, '
-  + 'so this terminal cannot read it — ask the machine running the daemon.';
+  + 'so this terminal cannot read it; ask the machine running the daemon.';
 
 /** The two relay accessors, spread into `externalServices` from bootstrap.ts. */
 export const relayReadAccessors: RelayReadAccessors = {

package/src/runtime/release-artifacts.ts

@@ -1,5 +1,5 @@
 /**
- * Release-artifact naming and checksum verification — re-exported from the
+ * Release-artifact naming and checksum verification, re-exported from the
  * SDK's canonical update policy module (platform/runtime/self-update), which
  * was hoisted from this file's semantics. One mechanism everywhere: the
  * asset naming convention (`goodvibes[-daemon]-{platform}-{arch}`), the

package/src/runtime/resume-notice.ts

@@ -1,9 +1,9 @@
 /**
- * resume-notice.ts — the boot-time "previous session found" transcript notice.
+ * resume-notice.ts, the boot-time "previous session found" transcript notice.
  *
  * item 1: a supervision-journey audit of 1.7.0 found that the TUI
  * accumulates rich resumable state on disk (a saved conversation, workspace
- * checkpoints, WRFC chain history) but never surfaces any of it at startup —
+ * checkpoints, WRFC chain history) but never surfaces any of it at startup,
  * an operator has no way to know it exists short of already knowing the
  * right command. This module builds ONE compact, honest system-message block
  * printed after the splash and before the first prompt, summarizing exactly
@@ -14,17 +14,17 @@
  *     (session.ts) opens a zero-typing picker over saved sessions when
  *     called bare, and resumes directly when given an id/name; `/sessions`
  *     (session-content.ts) forwards a `resume <id>` subcommand to the same
- *     `/session resume` path. All three spellings — `/resume <id>`,
- *     `/session resume <id>`, `/sessions resume <id>` — reach the identical
+ *     `/session resume` path. All three spellings, `/resume <id>`,
+ *     `/session resume <id>`, `/sessions resume <id>`, reach the identical
  *     resume routine. This notice leads with the zero-typing picker
  *     (`/resume`) and keeps the direct, exact-id form (`/session resume
  *     <id>`) as a secondary hint, for the case of already knowing which
  *     session to reach for.
  *   - `/checkpoints` works with zero arguments and behaves correctly at any
- *     checkpoint count (including zero) — advertised whenever the checkpoint
+ *     checkpoint count (including zero), advertised whenever the checkpoint
  *     manager is available in this session.
  *   - `/recall` (memory) is only advertised when the memory API is actually
- *     wired up in this session (context.clients?.knowledgeApi?.memory) —
+ *     wired up in this session (context.clients?.knowledgeApi?.memory),
  *     some runtimes don't have it, and claiming it works there would not be
  *     honest.
  *   - Every clause is independently gated on real data: a claim about
@@ -34,7 +34,7 @@
  *     It used to get a clause here, which meant an operator's only route back
  *     to a crashed session was reading a sentence and retyping a command. It
  *     is now an explicit ask-then-retire modal raised right after first
- *     render — see runtime/recovery-prompt.ts. Keeping a passive clause here
+ *     render, see runtime/recovery-prompt.ts. Keeping a passive clause here
  *     as well would announce the same snapshot twice.
  */
 
@@ -56,7 +56,7 @@ import type { SystemMessageRouter } from '../core/system-message-router.ts';
  * existed lack it; for those we fall back to the owner-decision log, where
  * cancelChain() also records a `chain_cancelled` decision. A chain still
  * non-terminal after rehydrate's zombie-reap check (see wrfc-persistence.ts)
- * is reported as 'interrupted' — re-imported and live again, not history.
+ * is reported as 'interrupted', re-imported and live again, not history.
  */
 export type ChainOutcome = 'passed' | 'failed' | 'cancelled' | 'interrupted';
 
@@ -91,7 +91,7 @@ export function mostRecentChain(chains: readonly WrfcChain[]): WrfcChain | null
 export interface ResumeNoticeFacts {
   /** Number of user turns in the last saved session. Null when there is no prior session (or it could not be read). */
   readonly turnCount: number | null;
-  /** Session id of the last saved session — needed to build a truthful, directly-runnable resume hint. Null when there is no prior session. */
+  /** Session id of the last saved session, needed to build a truthful, directly-runnable resume hint. Null when there is no prior session. */
   readonly lastSessionId: string | null;
   /** Number of workspace checkpoints. Null when the checkpoint manager is unavailable in this session (not the same as zero). */
   readonly checkpointCount: number | null;
@@ -107,7 +107,7 @@ function plural(n: number, word: string): string {
 
 /**
  * Build the boot resume notice text, or null when there is nothing to
- * report (no prior session, no checkpoints ever taken, no chain history —
+ * report (no prior session, no checkpoints ever taken, no chain history,
  * a clean/new working directory prints nothing, respecting quiet startup).
  */
 export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
@@ -123,7 +123,7 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
   if (hasSession) summary.push(plural(facts.turnCount!, 'turn'));
   // Show the checkpoint count whenever it's knowable and there's a reason to
   // (anchored to an existing session, or checkpoints genuinely exist even
-  // without one) — never guessed when the manager is unavailable.
+  // without one), never guessed when the manager is unavailable.
   if (checkpointsKnown && (hasSession || hasCheckpoints)) summary.push(plural(checkpointCount, 'checkpoint'));
   if (hasChainHistory) summary.push(`last chain: ${facts.lastChainOutcome}`);
 
@@ -132,11 +132,11 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
 
   const hints: string[] = [];
   // Lead with the zero-typing picker (/resume), keep the direct exact-id
-  // form as a secondary hint — see the header doc for why both are honest.
+  // form as a secondary hint, see the header doc for why both are honest.
   if (hasSession) hints.push(`/resume to continue (or /session resume ${facts.lastSessionId} directly)`);
   if (hasCheckpoints) hints.push('/checkpoints to browse');
   if (facts.memoryAvailable) hints.push('/recall for memory');
-  if (hints.length > 0) notice += ` — ${hints.join(' · ')}`;
+  if (hints.length > 0) notice += `: ${hints.join(' · ')}`;
 
   return notice;
 }
@@ -144,9 +144,9 @@ export function buildResumeNotice(facts: ResumeNoticeFacts): string | null {
 // ─── Fact gathering (I/O) ────────────────────────────────────────────────────
 
 export interface ResumeNoticeDeps {
-  /** The app's declare-once session-storage handle — the same one the runtime writes the pointer through. */
+  /** The app's declare-once session-storage handle, the same one the runtime writes the pointer through. */
   readonly surface: SessionSurface;
-  /** Only `load()` is needed — kept narrow for testability. */
+  /** Only `load()` is needed, kept narrow for testability. */
   readonly sessionManager: Pick<SessionManager, 'load'>;
   /** Undefined when checkpoints are not wired up in this session at all. Only `list()` is needed. */
   readonly checkpointManager: Pick<WorkspaceCheckpointManager, 'list'> | undefined;
@@ -158,11 +158,11 @@ export interface ResumeNoticeDeps {
 
 /**
  * Read the last session's real turn count from its saved JSONL file. A user
- * turn is one stored message with role 'user' — the number of times the
+ * turn is one stored message with role 'user', the number of times the
  * operator spoke, which is what "N turns" means to a human reading the
  * notice (as opposed to a raw message count, which double-counts replies).
  * Returns null when there is no last-session pointer, or the pointed-to
- * session file is missing/corrupt — never a claim about a session that
+ * session file is missing/corrupt, never a claim about a session that
  * cannot actually be resumed.
  */
 function readLastSessionTurns(deps: Pick<ResumeNoticeDeps, 'surface' | 'sessionManager'>): { turnCount: number; lastSessionId: string } | null {
@@ -173,7 +173,7 @@ function readLastSessionTurns(deps: Pick<ResumeNoticeDeps, 'surface' | 'sessionM
     const turnCount = messages.filter((m) => (m as { role?: unknown }).role === 'user').length;
     return { turnCount, lastSessionId };
   } catch {
-    // Pointer file present but the session it points to is gone/corrupt —
+    // Pointer file present but the session it points to is gone/corrupt,
     // there is nothing truthful to resume.
     return null;
   }
@@ -185,7 +185,7 @@ async function readCheckpointCount(mgr: ResumeNoticeDeps['checkpointManager']):
     return (await mgr.list()).length;
   } catch {
     // Checkpoint manager present but its cached init() rejection makes every
-    // call fail forever (see services.ts) — treat as "unknown", not zero.
+    // call fail forever (see services.ts), treat as "unknown", not zero.
     return null;
   }
 }
@@ -194,7 +194,7 @@ async function readCheckpointCount(mgr: ResumeNoticeDeps['checkpointManager']):
  * Gather real facts from disk/services and, if there is anything to report,
  * print ONE compact system message via `deps.router.high`. No-op (and no
  * message) when there is no prior session, no checkpoints, and no chain
- * history — a fresh working directory stays quiet. Nothing here ever mutates
+ * history, a fresh working directory stays quiet. Nothing here ever mutates
  * the conversation: this is a report, not a restore.
  */
 export async function announceResumeState(deps: ResumeNoticeDeps): Promise<void> {

package/src/runtime/runtime-services-types.ts

@@ -1,12 +1,12 @@
 /**
- * runtime-services-types.ts — the public contract createRuntimeServices() takes
+ * runtime-services-types.ts, the public contract createRuntimeServices() takes
  * and returns.
  *
  * Split out of services.ts (the composition root that builds every one of
  * these fields) so the construction logic can stay under the repo's
  * architecture line-count gate without trimming 35 arbitrary lines to clear
  * the number. This module owns ONLY the shape of the input options and the
- * output surface — no runtime code, no wiring order, nothing that constructs
+ * output surface, no runtime code, no wiring order, nothing that constructs
  * anything. services.ts re-exports both types from here, so no import site
  * anywhere else in the app had to change.
  */
@@ -87,14 +87,14 @@ export interface RuntimeServicesOptions {
    * Threaded into `SecretsManager` so the override MOVES the daemon-scoped
    * credential store; without it a daemon told to run out of a temp tree still
    * read the real home's daemon secrets, so an "isolated" test daemon held the
-   * owner's live credentials. One name for one thing — `resolveGoodVibesHomeOwnership`
+   * owner's live credentials. One name for one thing, `resolveGoodVibesHomeOwnership`
    * is the single reader that produces it.
    */
   readonly daemonHomeDirectory?: string | undefined;
   /** Host power seam opt-in. Fork mirrors the SDK: non-spawning unavailable-seam
    * default (idle-power-services.ts); this product always passes createHostPowerSeam(), since it never has a co-located daemon to own its own inhibitor. */
   readonly powerSeam?: Parameters<typeof wireIdlePowerAndLiveTurn>[0]['powerSeam'];
-  /** Live session id, read per crash-residue sweep so the running session is exempt — see durability-services.ts. */
+  /** Live session id, read per crash-residue sweep so the running session is exempt, see durability-services.ts. */
   readonly currentSessionId?: (() => string | null) | undefined;
   /**
    * Wake-word boot provisioning opt-in. Same shape as `powerSeam`: the real
@@ -108,9 +108,9 @@ export interface RuntimeServicesOptions {
 export interface RuntimeServices {
   readonly workingDirectory: string;
   readonly homeDirectory: string;
-  /** The surface segment this runtime's stores live under (platform runtime 2.0.8 requires it — a blank segment resolved to the unscoped control-plane orphan). */
+  /** The surface segment this runtime's stores live under (platform runtime 2.0.8 requires it, a blank segment resolved to the unscoped control-plane orphan). */
   readonly surfaceRoot: string;
-  /** The declare-once session-storage handle every session reader and writer threads through — see session-storage-services.ts. */
+  /** The declare-once session-storage handle every session reader and writer threads through, see session-storage-services.ts. */
   readonly surface: SessionSurface;
   readonly shellPaths: ShellPathService;
   readonly configManager: ConfigManager;
@@ -123,11 +123,11 @@ export interface RuntimeServices {
   readonly routeBindings: RouteBindingManager;
   readonly surfaceRegistry: SurfaceRegistry;
   readonly channelPlugins: ChannelPluginRegistry;
-  /** The one router this surface delivers through — AutomationDeliveryManager's own, not a second copy of it. */
+  /** The one router this surface delivers through, AutomationDeliveryManager's own, not a second copy of it. */
   readonly channelDeliveryRouter: ChannelDeliveryRouter;
   readonly watcherRegistry: WatcherRegistry;
   /**
-   * This surface's own record of the asks IT raised — what the approval card
+   * This surface's own record of the asks IT raised, what the approval card
    * and the panel render. Not authoritative: `requestApproval` below raises the
    * same ask on the daemon, whose record every other surface reads.
    */
@@ -152,7 +152,7 @@ export interface RuntimeServices {
   readonly clientBuildGuard: ClientBuildGuard;
   /**
    * This surface offering its live conversation to the daemon, so a rewind
-   * driven from anywhere can reach the messages — which only this process
+   * driven from anywhere can reach the messages, which only this process
    * holds. Started on adoption; released on disposal.
    */
   readonly conversationRewindHost: ConversationRewindHostClient;
@@ -160,7 +160,7 @@ export interface RuntimeServices {
   readonly daemonConfig: DaemonConfigClient;
   /** Daemon-scoped credential writes: `credentials.set`/`delete` on the daemon, one verified sequence. */
   readonly daemonCredentials: DaemonCredentialsClient;
-  /** The terminal prompt, late-bound — the UI layer patches the real one in after boot. */
+  /** The terminal prompt, late-bound, the UI layer patches the real one in after boot. */
   readonly localPromptRef: { requestPermission: (request: PermissionPromptRequest) => Promise<PermissionPromptDecision> };
   /** The live session id an ask belongs to; written by the bootstrap tail. */
   readonly liveSessionIdRef: { value: string | null };
@@ -173,18 +173,18 @@ export interface RuntimeServices {
   /** Durable user-origin permission rules (remembered approvals); permissions.rules.* surface. Mirrors the SDK composition. */
   readonly userPermissionRuleStore: UserPermissionRuleStore;
   /**
-   * An EMPTY verb catalog. This product answers no verbs — it is a client. The
+   * An EMPTY verb catalog. This product answers no verbs, it is a client. The
    * field exists because the SDK's `startExternalServices` takes a daemon-grade
    * `RuntimeServices` even in the adopt-only mode this surface runs in, and
    * because plugin loading is handed one. Nothing is ever served off it: with
    * `adoptOnly` no `DaemonServer` is constructed, so a descriptor registered
    * here has no listener behind it. Plugin registrations that need to be
-   * ANSWERED belong daemon-side — see docs/decisions for the plugin split.
+   * ANSWERED belong daemon-side, see docs/decisions for the plugin split.
    */
   readonly gatewayMethods: GatewayMethodCatalog;
   /** Step-up (re-auth) for this surface's own privileged actions. */
   readonly stepUpService: StepUpService;
-  /** This installation's pairing tokens — the bearer a phone or browser presents. */
+  /** This installation's pairing tokens, the bearer a phone or browser presents. */
   readonly pairingTokens: PairingTokenManager;
   /** Paired-phone posture over `devices.*` verbs; the `phone` tool calls through it. */
   readonly devices: DevicesClient;
@@ -229,7 +229,7 @@ export interface RuntimeServices {
   readonly worktreeRegistry: WorktreeRegistry;
   readonly sandboxSessionRegistry: SandboxSessionRegistry;
   readonly webhookNotifier: WebhookNotifier;
-  /** Terminal focus tracker — fed by input/handler-feed.ts, read by the alert notifiers in core/. */
+  /** Terminal focus tracker, fed by input/handler-feed.ts, read by the alert notifiers in core/. */
   readonly focusTracker: FocusTracker;
   readonly replayEngine: DeterministicReplayEngine;
   readonly providerOptimizer: ProviderOptimizer;
@@ -258,13 +258,13 @@ export interface RuntimeServices {
   readonly contextAccountingHolder: ContextAccountingHolder; // bound at bootstrap.ts; see context-accounting-source.ts
   readonly wrfcController: WrfcController;
   readonly processManager: ProcessManager;
-  /** The phase/work-item orchestration engine — see runtime/workstream-services.ts. */
+  /** The phase/work-item orchestration engine, see runtime/workstream-services.ts. */
   readonly orchestrationEngine: OrchestrationEngine;
   readonly workstreamCommands: WorkstreamCommandService;
-  /** The repo source-tree code index — see runtime/code-index-services.ts. */
+  /** The repo source-tree code index, see runtime/code-index-services.ts. */
   readonly codeIndexStore: CodeIndexStore;
   readonly codeIndexReindexScheduler: CodeIndexReindexScheduler; // tool-site reindex
-  /** Daily snapshots of every SQLite store this runtime writes, with bounded retention; unref'd timers (mirrors the SDK composition — hosts that tear down a runtime stop() it themselves). */
+  /** Daily snapshots of every SQLite store this runtime writes, with bounded retention; unref'd timers (mirrors the SDK composition, hosts that tear down a runtime stop() it themselves). */
   readonly storeSnapshotScheduler: StoreSnapshotScheduler;
   readonly appendOnlyRetentionScheduler: ReturnType<typeof createDurabilityServices>['appendOnlyRetentionScheduler']; // periodic append-only sweep; unref'd timers, stop() on teardown
   /** Stops the recurring crash-residue sweep; idempotent, unref'd timer (hosts that tear a runtime down call it). */
@@ -280,18 +280,18 @@ export interface RuntimeServices {
   /** Controller the governor uses to pause/resume the deferrable background jobs under pressure. */
   readonly pauseController: PauseController;
   readonly sessionLiveTurnControls: SessionLiveTurnControlsHolder;
-  /** Unified live process registry (agents, WRFC chains, workflows, watchers, background processes) backing the Fleet panel; archive-aware — finished subtrees can be moved to the session archive view. */
+  /** Unified live process registry (agents, WRFC chains, workflows, watchers, background processes) backing the Fleet panel; archive-aware, finished subtrees can be moved to the session archive view. */
   readonly processRegistry: ArchivableProcessRegistry;
   /**
    * What the Fleet panel reads: this surface's own registry rows UNION the
    * adopted daemon's, deduped by node id with the local (live, actionable) copy
-   * winning. Interval-refreshed on the daemon half — see client/fleet-union.ts.
+   * winning. Interval-refreshed on the daemon half, see client/fleet-union.ts.
    */
   readonly fleetReadModel: FleetUnionReadModel;
   readonly modeManager: ModeManager;
   readonly fileUndoManager: FileUndoManager;
   readonly workspaceCheckpointManager: WorkspaceCheckpointManager;
-  /** Per-workspace trust gate — restricts write/execute/delegate tools until the workspace is trusted. */
+  /** Per-workspace trust gate, restricts write/execute/delegate tools until the workspace is trusted. */
   readonly workspaceTrustManager: WorkspaceTrustManager;
   readonly integrationHelpers: IntegrationHelperService;
   /** Re-root path-bound stores (MemoryStore, ProjectIndex) to a new working directory, called by WorkspaceSwapManager after verification; stores needing a process restart just warn-log and keep serving the old path until the daemon restarts with the new --working-dir. */

package/src/runtime/services.ts

@@ -1,25 +1,25 @@
 /**
- * services.ts — the terminal app's composition root, as a CLIENT.
+ * services.ts, the terminal app's composition root, as a CLIENT.
  *
- * Every gateway-serving piece — the `GatewayMethodCatalog`, the
+ * Every gateway-serving piece, the `GatewayMethodCatalog`, the
  * inbox/triage/drafts/routing handlers, the cluster group and its election,
- * the device-posture runtime and its housekeeping, the mail service deps —
+ * the device-posture runtime and its housekeeping, the mail service deps,
  * lives in the daemon product. This composition serves no verbs, elects
  * nothing, polls no mailbox, and supervises no remote runner. It builds what
  * a TURN needs in this process and reaches the daemon for the rest.
  *
  * ── The floor comes from the SDK ───────────────────────────────────────────
  *
- * The loop essentials — the agent graph, the model stack, config/secrets/
+ * The loop essentials, the agent graph, the model stack, config/secrets/
  * services, hooks, plugins, MCP, the file-tool caches, permissions as a client,
- * the spine clients — are composed by `createClientRuntimeServices`, the SDK's
+ * the spine clients, are composed by `createClientRuntimeServices`, the SDK's
  * one implementation of that shape. Not a fork of it and not a copy of it: the
  * agent product composes the same function, so a wiring step added there
  * cannot silently miss this product.
  *
  * The SDK's own note on that shape applies here literally: it is a FLOOR, not a
  * ceiling. Everything below the `createClientRuntimeServices` call is what THIS
- * surface adds on top — panels, keybindings, the WRFC controller wired over the
+ * surface adds on top, panels, keybindings, the WRFC controller wired over the
  * client's own `agentManager`, the workstream engine, the fleet read model, the
  * voice stack with its local playback sink, the knowledge stack the recall
  * surfaces read. None of those need daemon furniture; they are simply not
@@ -29,7 +29,7 @@
  * ── The two things that look like daemon furniture and are not ─────────────
  *
  * `sessionBroker` and `approvalBroker` are still constructed. They are this
- * surface's own record of the sessions it is running and the asks it raised —
+ * surface's own record of the sessions it is running and the asks it raised,
  * what the transcript, the session panel and the approval card read. They are
  * NOT authoritative: session identity is mirrored to the daemon's spine
  * (register/heartbeat/inputs) and an ask is raised on the daemon
@@ -110,7 +110,7 @@ export type { RuntimeServicesOptions, RuntimeServices } from './runtime-services
 export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeServices {
   const disposalScope = createDisposalScope('RuntimeServices'); const workingDirectory = options.workingDir; // disposal seam: see ./disposal-wiring.ts
   const homeDirectory = options.homeDirectory;
-  // Built before anything that touches session state — see session-storage-services.ts.
+  // Built before anything that touches session state, see session-storage-services.ts.
   const { surface, sessionManager } = createSessionStorageServices({ workingDirectory, homeDirectory, surfaceRoot: GOODVIBES_TUI_SURFACE_ROOT });
   const configManager = options.configManager;
   const featureFlags = options.featureFlags ?? createFeatureFlagManager();
@@ -135,7 +135,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // pure (it derives paths, it opens nothing), so building it twice costs
   // nothing and keeps the ordering honest.
   const shellPaths = createShellPathService({ workingDirectory, homeDirectory });
-  // The surface's own record of the asks it raised — what the approval card and
+  // The surface's own record of the asks it raised, what the approval card and
   // the panel read. The AUTHORITATIVE record is the daemon's; the raiser below
   // keeps the two in step (see the SDK's client/approval-raiser.ts).
   const approvalBroker = new ApprovalBroker({
@@ -166,7 +166,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     // The push channel for a decision made on another surface. Without it the
     // raiser learns by re-reading the record on an interval; with it a phone's
     // answer reaches this terminal in the time one SSE frame takes. The interval
-    // stays as the fallback — see client/approval-updates.ts.
+    // stays as the fallback, see client/approval-updates.ts.
     subscribeApprovalUpdates: createTerminalApprovalUpdateSubscriber({ configManager, homeDirectory }),
   });
 
@@ -235,7 +235,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // handed one. With adoptOnly no DaemonServer is constructed, so nothing is
   // ever served off it.
   const gatewayMethods = new GatewayMethodCatalog();
-  // The credential/identity seam (credential-composition.ts) — this
+  // The credential/identity seam (credential-composition.ts), this
   // installation's own pairing tokens and step-up service.
   const { stepUpService, pairingTokens } = composeCredentialServices({
     workingDirectory, homeDirectory, configManager,
@@ -258,7 +258,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     runtimeStore: options.runtimeStore,
     runtimeBus: options.runtimeBus,
   });
-  // WRFC over the client's own agent graph — the "floor, not ceiling" case,
+  // WRFC over the client's own agent graph, the "floor, not ceiling" case,
   // verbatim: the review/fix workstream controller needs the agent manager and
   // the message bus, and nothing daemon-side at all.
   const wrfcController = new WrfcController(options.runtimeBus, agentMessageBus, {
@@ -278,8 +278,8 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // the same runner whether it came from the local broker or from the daemon's
   // queue. The wire half is inert until bootstrap.ts adopts a daemon (see
   // the SDK's client/session-dispatch.ts); binding one runner to both is what stops a
-  // continuation delivered over the wire from taking a different path — and a
-  // different set of routing options — than one raised locally.
+  // continuation delivered over the wire from taking a different path, and a
+  // different set of routing options, than one raised locally.
   const wireSessionDispatch = createWireSessionDispatch({
     hostedSessionIds: () => (liveSessionIdRef.value ? [liveSessionIdRef.value] : []),
     // The reply half. A continuation dispatched here runs in THIS process, so
@@ -382,7 +382,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
       return record.id;
     },
   });
-  // Knowledge/wiki + home-graph stack (governor backpressure wired in) — see knowledge-services.ts.
+  // Knowledge/wiki + home-graph stack (governor backpressure wired in), see knowledge-services.ts.
   const {
     knowledgeStore, agentKnowledgeStore, homeGraphKnowledgeStore,
     knowledgeSemanticService, homeGraphSemanticService, agentKnowledgeSemanticService,
@@ -390,7 +390,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
     projectPlanningService, projectPlanningProjectId, workPlanStore,
   } = createKnowledgeServices({ configManager, providerRegistry, artifactStore, memoryRegistry, runtimeBus: options.runtimeBus, workingDirectory, homeDirectory, isBackgroundPaused: isKnowledgeBackgroundPaused, admitExpensiveWork });
   // Voice: the PROVIDERS are local (a spoken turn plays out of this terminal's
-  // own speaker) — synthesis reaches `voice.tts.stream` when a daemon serves it
+  // own speaker), synthesis reaches `voice.tts.stream` when a daemon serves it
   // and falls back to a local provider otherwise; see audio/spoken-turn-wiring.ts.
   const voiceProviders = new VoiceProviderRegistry();
   ensureBuiltinVoiceProviders(voiceProviders, { readConfig: (key) => configManager.get(key as Parameters<typeof configManager.get>[0]) });
@@ -435,7 +435,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   const idempotencyStore = new IdempotencyStore();
   // ONE router, not two. This surface used to build a second ChannelDeliveryRouter
   // from the same four arguments AutomationDeliveryManager builds its own from,
-  // and expose that second one — so the router on the service surface and the
+  // and expose that second one, so the router on the service surface and the
   // router replies actually leave through were different objects, and a delivery
   // strategy registered on the exposed one reached nothing. The SDK's
   // RuntimeServices contract requires the field; it now names the real router.
@@ -467,7 +467,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // adopted daemon's rows. The daemon runs work no registry here knows about
   // (scheduled jobs, channel-driven runs, sessions other surfaces started, the
   // external agents it observes), and a panel showing only half the fleet is
-  // worse than one showing none — the half it shows looks complete.
+  // worse than one showing none, the half it shows looks complete.
   const fleetReadModel = createFleetUnionReadModel({
     local: createFleetReadModel(processRegistry, options.runtimeBus),
     verbs,
@@ -500,7 +500,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   });
   admitExpensiveWorkRef.current = (label) => memoryGovernor.admitExpensiveWork(label);
 
-  // Managed local-voice provisioning (voice.local.status/install) — single-flight
+  // Managed local-voice provisioning (voice.local.status/install), single-flight
   // one-act install + no-network status; see voice-setup-services.ts.
   const { voiceSetup, stopWakeHousekeeping } = wireVoiceSetup({ configManager, shellPaths, voiceProviders, admitExpensiveWork,
     provisionWakeModelsAtBoot: options.provisionWakeModelsAtBoot === true });
@@ -517,7 +517,7 @@ export function createRuntimeServices(options: RuntimeServicesOptions): RuntimeS
   // "allow for this project" persists and later fetches never ask.
   const localhostFetchApproval = buildLocalhostFetchApproval({ requestApproval: (input) => requestApproval(input), configManager });
   // Exec stuck on a terminal prompt rides the same raiser; the typed answer feeds
-  // the continuing run. Built once and shared with every setDependencies site —
+  // the continuing run. Built once and shared with every setDependencies site,
   // a wholesale replace that forgets it hangs interactive prompts.
   const execPromptAnswerHandler = buildExecPromptAnswerHandler({ requestApproval: (input) => requestApproval(input) });
   agentOrchestrator.setDependencies({

package/src/runtime/session-continuity-hints.ts

@@ -1,5 +1,5 @@
 /**
- * session-continuity-hints — the recovery snapshot's continuity summary.
+ * session-continuity-hints, the recovery snapshot's continuity summary.
  *
  * Extracted from main.ts (which sits at the architecture line cap) so the
  * startup wiring there stays within budget. Builds the small counts/paths