@pellux/goodvibes-tui 2.0.13 → 2.0.15

package/src/runtime/onboarding/fast-path.ts

@@ -1,14 +1,14 @@
 /**
- * fast-path.ts — minimum-steps first run.
+ * fast-path.ts, minimum-steps first run.
  *
  * The full onboarding wizard is comprehensive but long (5+ steps for a brand
  * new user). The fast path gets a new user to a working session in the fewest
  * possible steps:
  *   - If a provider API key is already configured (env / secrets), skip
- *     onboarding entirely — write the check marker and drop straight into a
+ *     onboarding entirely, write the check marker and drop straight into a
  *     working session. ZERO steps.
  *   - Otherwise ask exactly one question: start now on the default model, or
- *     run the full guided setup. Dismissing (Esc) starts now — so it is
+ *     run the full guided setup. Dismissing (Esc) starts now, so it is
  *     always skippable. The start-now copy is GENERATED from the default
  *     model's registered auth state (buildOnboardingModelCopy), so a
  *     "no API key needed" promise can only render when the provider is
@@ -39,7 +39,7 @@ export interface OnboardingFastPathDeps {
   readonly render: () => void;
 }
 
-/** Read configured provider ids defensively — returns [] if the surface can't answer. */
+/** Read configured provider ids defensively, returns [] if the surface can't answer. */
 function readConfiguredProviderIds(commandContext: CommandContext): string[] | null {
   const registry = commandContext.provider?.providerRegistry;
   if (!registry || typeof registry.getConfiguredProviderIds !== 'function') return null;
@@ -89,10 +89,10 @@ export function startOnboardingFastPath(deps: OnboardingFastPathDeps): void {
   }
 
   if (configured.length > 0) {
-    // A provider key already exists — nothing to ask. Straight to a working session.
+    // A provider key already exists, nothing to ask. Straight to a working session.
     writeOnboardingCheckMarker(shellPaths, MARKER_OPTIONS);
     commandContext.print?.(
-      `Ready — provider configured (${configured.join(', ')}). Run /onboarding anytime for full setup.`,
+      `Ready: provider configured (${configured.join(', ')}). Run /onboarding anytime for full setup.`,
     );
     render();
     return;
@@ -104,7 +104,7 @@ export function startOnboardingFastPath(deps: OnboardingFastPathDeps): void {
     { id: 'full-setup', label: 'Full guided setup', detail: 'Choose provider, model, channels, and more', primaryAction: 'select' },
   ];
   commandContext.openSelection(
-    'Welcome to GoodVibes — get started',
+    'Welcome to GoodVibes: get started',
     items,
     { allowSearch: false, primaryVerbLabel: 'Choose' },
     (result) => {

package/src/runtime/onboarding/progress.ts

@@ -90,7 +90,7 @@ export interface WriteWizardProgressOptions {
  * project switches and is shared with the resume-prompt check at startup.
  *
  * Masked (password) fields are deliberately excluded from the serialised
- * textState by the caller — this function accepts whatever is passed in and
+ * textState by the caller, this function accepts whatever is passed in and
  * does NOT filter. Callers must strip sensitive fields before calling.
  */
 export function writeWizardProgress(
@@ -143,6 +143,6 @@ export function hasResumableWizardProgress(
   const state = options.state ?? readWizardProgress(shellPaths);
   if (!state.payload) return false;
   const age = (options.now ?? Date.now()) - state.payload.savedAt;
-  // age < 0 means savedAt is in the future (clock skew / tampered file) — treat as non-resumable.
+  // age < 0 means savedAt is in the future (clock skew / tampered file), treat as non-resumable.
   return age >= 0 && age < PROGRESS_MAX_AGE_MS;
 }

package/src/runtime/onboarding/provider-key-capture.ts

@@ -2,14 +2,14 @@
  * Provider-agnostic key capture for onboarding.
  *
  * The onboarding wizard offers an API-key field for every provider the registry
- * knows accepts a key — derived from each provider's registration-time auth
+ * knows accepts a key, derived from each provider's registration-time auth
  * state (describeAuthState), never a hardcoded vendor list. This module holds
  * the two shared pieces that keep the wizard step and the apply step in lockstep:
  *
- *  1. enrichProviderAccountsSnapshot — stamps each provider-account record with
+ *  1. enrichProviderAccountsSnapshot, stamps each provider-account record with
  *     the secrets-store key it reads its API key from (its declared auth env
  *     var), read live from the provider registry.
- *  2. deriveProviderKeyCaptureTargets / providerKeyFieldId — the single source
+ *  2. deriveProviderKeyCaptureTargets / providerKeyFieldId, the single source
  *     of truth for which providers get a key field and how those fields are
  *     named, used by both the field builder and the apply writer.
  */
@@ -99,7 +99,7 @@ export interface SubscriptionStatusTarget {
 /**
  * The providers onboarding shows a subscription-status row for: every provider
  * that declares a subscription route (registration truth), plus any provider
- * with an active or pending subscription session — so a live session is never
+ * with an active or pending subscription session, so a live session is never
  * hidden just because its account record was absent. Ordered by provider id.
  */
 export function deriveSubscriptionStatusTargets(

package/src/runtime/onboarding/snapshot.ts

@@ -402,7 +402,7 @@ export async function collectOnboardingSnapshot(
       snapshot: authSnapshotResult.value,
     },
     bindSettings: {
-      // danger.daemon (since removed — see docs/decisions/2026-07-05-daemon-by-default.md)
+      // danger.daemon (since removed, see docs/decisions/2026-07-05-daemon-by-default.md)
       // used to gate the earlier opt-in daemon posture; this site read it RAW
       // (not through resolveDaemonEnabled) so the wizard's network-mode
       // classification tracked "did the user explicitly request the legacy
@@ -412,7 +412,7 @@ export async function collectOnboardingSnapshot(
       // already evaluated this to `false` (unset, or an explicit `danger.daemon:
       // false` both did); the alias's removal migration preserves the one case
       // that changes real daemon behavior (explicit `false` -> `daemon.enabled:
-      // false`) but does not resurrect a signal for "explicitly true" — that path
+      // false`) but does not resurrect a signal for "explicitly true", that path
       // was always a no-op for actual daemon operation. With the alias gone there
       // is no signal left to read, so this is pinned at its steady-state value.
       daemonEnabled: false,

package/src/runtime/onboarding/state.ts

@@ -20,9 +20,9 @@ const ONBOARDING_RUNTIME_STATE_FILE = 'onboarding-state.json';
  * This is the simplest correct approach for two same-host processes (daemon
  * + TUI) that both run this read-modify-write path:
  *
- *   - Acquire: open(<statefile>.lock, O_CREAT|O_EXCL|O_WRONLY) — atomic on POSIX.
+ *   - Acquire: open(<statefile>.lock, O_CREAT|O_EXCL|O_WRONLY), atomic on POSIX.
  *   - Stale detection: if the lockfile mtime is >= LOCK_STALE_MS old, force-remove.
- *   - Retry: up to LOCK_MAX_RETRIES rapid non-blocking attempts (no sleep — main-thread safe).
+ *   - Retry: up to LOCK_MAX_RETRIES rapid non-blocking attempts (no sleep, main-thread safe).
  *   - Release: unlink the lockfile (best-effort on failure).
  *
  * O_EXCL was chosen over flock(2) because it works on all POSIX targets
@@ -103,7 +103,7 @@ function acquireLock(lp: string): boolean {
     } catch { /* lockfile does not exist — expected happy path */ }
 
     try {
-      // 'wx' ≡ O_CREAT | O_EXCL | O_WRONLY — fails atomically if file exists.
+      // 'wx' ≡ O_CREAT | O_EXCL | O_WRONLY, fails atomically if file exists.
       const fd = openSync(lp, 'wx');
       closeSync(fd);
       return true;
@@ -180,7 +180,7 @@ export function writeOnboardingAcknowledgementState(
   const acquired = acquireLock(lp);
   if (!acquired) {
     // Lock exhaustion: another process has held the lock for all LOCK_MAX_RETRIES
-    // attempts. Proceeding without the lock — the atomic write (rename) prevents
+    // attempts. Proceeding without the lock, the atomic write (rename) prevents
     // torn files, but under true concurrent contention a concurrent read-modify-write
     // may result in a lost-update (last writer wins). Surfaced here so it is
     // detectable in logs rather than silently discarded.

package/src/runtime/onboarding/types.ts

@@ -128,7 +128,7 @@ export interface OnboardingSurfacesSnapshot {
  * systemd unit (see `../legacy-daemon-migration.ts`'s `LegacyUnitInfo`), carried
  * on the snapshot so the Network step can show the guided migration action only
  * when there is actually something to migrate. Never implies anything was
- * touched — detection only.
+ * touched, detection only.
  */
 export interface OnboardingLegacyDaemonSnapshot {
   readonly present: boolean;
@@ -137,7 +137,7 @@ export interface OnboardingLegacyDaemonSnapshot {
   /**
    * Follow-up: the unit name this tool actually manages on this host,
    * resolved from the `service.serviceName` config key at snapshot-collection
-   * time (`resolveConfiguredServiceName`, `../legacy-daemon-migration.ts`) —
+   * time (`resolveConfiguredServiceName`, `../legacy-daemon-migration.ts`),
    * so the wizard's detection banner names the real unit instead of the
    * hardcoded default. Optional so snapshots built without config access
    * (fallbacks, older fixtures) stay valid; readers fall back to
@@ -156,7 +156,7 @@ export interface OnboardingProviderAccountRecord {
   readonly activeRoute: string;
   readonly authFreshness: string;
   /**
-   * The secrets-store key this provider reads its API key from — its declared
+   * The secrets-store key this provider reads its API key from, its declared
    * auth env var, read from the live provider's registration-time auth state.
    * Present only for providers that accept an API key; absent for keyless /
    * subscription-only providers. Used to offer provider-agnostic key entry in
@@ -283,7 +283,7 @@ export type OnboardingApplyOperation =
       readonly value: string;
       /**
        * Which secret tier the value is filed in. 'daemon' is the tier the
-       * daemon reads with every surface closed — see
+       * daemon reads with every surface closed, see
        * config/secret-config.ts#defaultSecretBackedScope.
        */
       readonly scope?: 'project' | 'user' | 'daemon';

package/src/runtime/orchestrator-core-services.ts

@@ -21,11 +21,11 @@ export type OrchestratorCoreServicesSource = Pick<
  * The single source of truth for the `Orchestrator.setCoreServices()` payload
  * fields shared by BOTH call sites (runtime/bootstrap.ts and main.ts). Each
  * site spreads this and adds its own site-specific extras (bootstrap:
- * cacheHitTracker; main: favoritesStore) — setCoreServices() merges, so the
+ * cacheHitTracker; main: favoritesStore), setCoreServices() merges, so the
  * later main.ts call only overlays, never erases.
  *
  * BLOCKER regression guard: `memoryRegistry` here is what turns
- * on per-turn passive knowledge injection for the MAIN interactive session —
+ * on per-turn passive knowledge injection for the MAIN interactive session,
  * the SDK turn loop hard-gates on `coreServices.memoryRegistry` (undefined is
  * a silent no-op: Orchestrator.getTurnInjections() stays empty forever and
  * `/recall injections` renders a misleading empty state). Both call sites once
@@ -35,12 +35,12 @@ export type OrchestratorCoreServicesSource = Pick<
  *
  * SDK 1.2.0 FULL DETACH: the SDK's turn loop reads `memoryRegistry.getAll()`
  * SYNCHRONOUSLY (`TurnKnowledgeRegistrySource`), but the memory spine's wire
- * reads are asynchronous — a sync function cannot await the wire. Per
+ * reads are asynchronous, a sync function cannot await the wire. Per
  * docs/decisions/2026-07-06-memory-wire-full-detach.md (SDK repo) this is
  * satisfied by the spine's freshness-stamped recall snapshot instead of the
  * raw local `memoryRegistry`: `getAll()` reads `memorySpine.recallSnapshot()`,
  * which returns whatever the last `refreshRecallSnapshot()` (an async
- * pre-turn hook — see the `handleUserInput` call sites) captured, honestly
+ * pre-turn hook, see the `handleUserInput` call sites) captured, honestly
  * empty/stale until refreshed. This is what lets per-turn knowledge injection
  * detach from the local store file when a daemon is adopted, instead of
  * always reading the (possibly divergent) local registry regardless of mode.
@@ -75,7 +75,7 @@ export function buildSharedOrchestratorCoreServices(input: {
  * the CURRENT route (wire when adopted, local otherwise) so the synchronous
  * per-turn knowledge injection (`memoryRegistry.getAll()` above) reads
  * up-to-date records instead of whatever the previous refresh captured.
- * Failures are swallowed — an honest stale/empty snapshot (with its own
+ * Failures are swallowed, an honest stale/empty snapshot (with its own
  * degradation note, surfaced via `recallSnapshot().note`) is preferable to
  * blocking the user's turn on a memory-read failure.
  */

package/src/runtime/path-shadow-startup.ts

@@ -1,5 +1,5 @@
 /**
- * path-shadow-startup.ts — this terminal's boot-time reachability report.
+ * path-shadow-startup.ts, this terminal's boot-time reachability report.
  *
  * The check itself (the PATH scan, the `--version` probes, the cost discipline
  * that keeps a healthy start free of spawns and network calls, and the wording)
@@ -21,7 +21,7 @@ const TERMINAL_PACKAGE_NAME = '@pellux/goodvibes-tui';
 /** The command name the shell resolves this terminal by. */
 const TERMINAL_COMMAND_NAME = 'goodvibes';
 
-/** The same release lookup `/update` uses — there is deliberately no second source of truth. */
+/** The same release lookup `/update` uses, there is deliberately no second source of truth. */
 function resolveLatestRelease(): Promise<string | undefined> {
   return boundedLatestRelease(async () => {
     const result = await checkForUpdate(fetch as UpdateFetchLike, VERSION);
@@ -32,7 +32,7 @@ function resolveLatestRelease(): Promise<string | undefined> {
 /**
  * Boot-time wiring. Prints one high-priority system message per line so the
  * report reads as prose rather than a single wrapped paragraph, and swallows
- * everything — a reachability check must never block or crash boot.
+ * everything, a reachability check must never block or crash boot.
  */
 export async function announceInstallReachability(router: SystemMessageRouter): Promise<void> {
   await announceReachability(

package/src/runtime/perf/panel-contracts.ts

@@ -1,5 +1,5 @@
 /**
- * Panel resource contracts — backward-compat shim.
+ * Panel resource contracts, backward-compat shim.
  *
  * Re-exports the SDK's component contract types and helpers. TUI code that
  * previously used local `ComponentResourceContract` / `ComponentHealthState`

package/src/runtime/power-keepawake-remote.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// power-keepawake-remote.ts — forward the keep-awake toggle to an adopted
+// power-keepawake-remote.ts, forward the keep-awake toggle to an adopted
 // EXTERNAL daemon over the power.keepAwake.set operator verb.
 //
 // In the external/adopted-daemon topology the in-process PowerManager is NOT
@@ -7,12 +7,12 @@
 // closes. The owner ruling is that keep-awake is daemon-held: it must survive
 // the TUI closing. The config file does NOT carry it across (power.keepAwake is
 // not a cross-surface shared key), so the toggle is forwarded to the daemon
-// over the verb instead — best-effort, gated on reachability. Mirrors the
+// over the verb instead, best-effort, gated on reachability. Mirrors the
 // agent's own power-keep-awake-remote seam.
 //
 // A single config subscriber carries ALL THREE toggle paths (/power, Alt+A, the
-// settings modal): each lands on the power.keepAwake config key — the local
-// PowerManager persists it on set, and the settings modal writes it directly —
+// settings modal): each lands on the power.keepAwake config key, the local
+// PowerManager persists it on set, and the settings modal writes it directly,
 // so subscribing to that one key catches every origin. When there is no adopted
 // external daemon (`isExternalDaemon()` false), this is a no-op: there is nothing
 // to forward to.
@@ -34,7 +34,7 @@ export interface KeepAwakeRemoteDeps {
 /**
  * Best-effort forward of the keep-awake toggle to the adopted external daemon so
  * the DAEMON holds the inhibitor (surviving the TUI closing). A no-op in the
- * embedded topology and quiet when the daemon is unreachable — a transient
+ * embedded topology and quiet when the daemon is unreachable, a transient
  * daemon hiccup never breaks the local toggle.
  */
 export async function forwardKeepAwakeToDaemon(enabled: boolean, deps: KeepAwakeRemoteDeps): Promise<void> {
@@ -61,7 +61,7 @@ export function installKeepAwakeRemoteForward(deps: KeepAwakeRemoteDeps): () =>
 
 /**
  * Fetch the adopted DAEMON's power.status.get (null when unreachable or not in
- * the external topology). The chip's external-mode poll source — the adopted
+ * the external topology). The chip's external-mode poll source, the adopted
  * wire is plain HTTP with no event bridge, so the chip syncs by polling.
  */
 export async function fetchDaemonPowerState(deps: KeepAwakeRemoteDeps): Promise<PowerState | null> {

package/src/runtime/process-lifecycle.ts

@@ -32,14 +32,14 @@ import type { ConversationMessageSnapshot } from '../core/conversation.ts';
 
 /** Shutdown grace period before the "saving session…" line prints. Below this, exit stays quiet. */
 const SAVE_NOTICE_AFTER_MS = 300;
-/** Hard shutdown timeout — matches the pre-existing race below (was previously an inline literal). */
+/** Hard shutdown timeout, matches the pre-existing race below (was previously an inline literal). */
 const SHUTDOWN_HARD_TIMEOUT_MS = 3000;
 
 /**
  * Whether a recovery snapshot actually exists on disk for this session. The
  * periodic autosave (see recovery-autosave.ts) only writes on a 60s tick and
  * skips empty conversations entirely, so a session that dies sooner than that
- * (or never had anything in it) has no snapshot at all — the exit receipt
+ * (or never had anything in it) has no snapshot at all, the exit receipt
  * must not claim otherwise. Never throws: a stat failure just means "absent".
  */
 function defaultRecoverySnapshotExists(surface: SessionSurface, sessionId: string): boolean {
@@ -58,7 +58,7 @@ export interface ProcessLifecycleAnsi {
   readonly KEYBOARD_EXT_DISABLE: string;
   readonly MOUSE_DISABLE: string;
   readonly CURSOR_SHOW: string;
-  /** Disables terminal focus-event reporting (DECSET ?1004l) — see main.ts FOCUS_ENABLE. */
+  /** Disables terminal focus-event reporting (DECSET ?1004l), see main.ts FOCUS_ENABLE. */
   readonly FOCUS_DISABLE: string;
 }
 
@@ -88,7 +88,7 @@ export interface ProcessLifecycleDeps {
   readonly shutdownHardTimeoutMs?: number;
   /**
    * Overridable for tests; defaults to a real filesystem existence check
-   * (defaultRecoverySnapshotExists). Never throws — a stat failure reads as
+   * (defaultRecoverySnapshotExists). Never throws, a stat failure reads as
    * "absent" rather than taking the exit path down.
    */
   readonly recoverySnapshotExists?: (surface: SessionSurface, sessionId: string) => boolean;
@@ -145,7 +145,7 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     _unhandledRejectionCount++;
     const msg = summarizeError(reason);
     if (_unhandledRejectionCount > 3) {
-      logger.error('CRITICAL: cascading unhandled rejections — consider restarting', {
+      logger.error('CRITICAL: cascading unhandled rejections; consider restarting', {
         count: _unhandledRejectionCount,
         windowMs: now - _unhandledRejectionWindowStart,
         error: String(reason),
@@ -176,7 +176,7 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
   // The injected `ansi` restore sequences are mapped onto the package's escape
   // set so the exact bytes the TUI has always emitted are preserved. The no-alt
   // exit deliberately uses the package's CLEAR_VIEWPORT_HOME ('\x1b[2J\x1b[H',
-  // no ESC[3J) — never ansi.CLEAR_SCREEN, which carries the scrollback-wiping 3J.
+  // no ESC[3J), never ansi.CLEAR_SCREEN, which carries the scrollback-wiping 3J.
   const terminalLifecycle = createTerminalLifecycle({
     write: (data) => { stdout.write(data); },
     noAltScreen,
@@ -200,17 +200,17 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
 
   const uncaughtExceptionHandler = (err: Error): void => {
     restoreTerminal();
-    logger.error('uncaughtException — terminal restored, exiting', { error: summarizeError(err) });
+    logger.error('uncaughtException: terminal restored, exiting', { error: summarizeError(err) });
     // The line naming the crash is the only record of it. process.exit does not
     // drain the activity log's buffer, so it goes to disk here rather than
-    // relying on the exit hook that also runs — the crash log is worth stating
+    // relying on the exit hook that also runs, the crash log is worth stating
     // the intent for at the site that produces it.
     flushActivityLogSync();
     process.exit(1);
   };
   const terminationSignalHandler = (signal: NodeJS.Signals): void => {
     restoreTerminal();
-    logger.error(`Received ${signal} — terminal restored, exiting`, {});
+    logger.error(`Received ${signal}: terminal restored, exiting`, {});
     flushActivityLogSync();
     process.exit(signal === 'SIGHUP' ? 129 : 143);
   };
@@ -251,7 +251,7 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
       try { stdout.write('saving session…\n'); } catch { /* best-effort */ }
     }, saveNoticeAfterMs);
     try {
-      // Race the graceful shutdown against a hard timeout — externalServices.stop() can hang
+      // Race the graceful shutdown against a hard timeout, externalServices.stop() can hang
       // and we must still exit; deferredStartup.drain only budgets 100ms internally.
       // The spoken-audio drain runs concurrently and is internally capped below
       // this budget, so it never extends the exit beyond the hard timeout.
@@ -273,17 +273,17 @@ export function installProcessLifecycle(deps: ProcessLifecycleDeps): ProcessLife
     if (shutdownOk) {
       deleteRecoveryFile({ surface: ctx.services.surface }, ctx.runtime.sessionId);
     } else {
-      // The hard timeout won the race — the durable save never confirmed, so
+      // The hard timeout won the race, the durable save never confirmed, so
       // whatever the periodic autosave last wrote (see recovery-autosave.ts)
       // is deliberately kept above. But that autosave only ticks every 60s
       // and skips empty conversations, so a session that dies sooner than
-      // that (or never had anything in it) has no snapshot to keep — check
+      // that (or never had anything in it) has no snapshot to keep, check
       // before claiming otherwise, since a silent exit here previously left
       // no trace that anything was amiss.
       const kept = recoverySnapshotExists(ctx.services.surface, ctx.runtime.sessionId);
       const line = kept
-        ? 'exit before save completed — a recovery snapshot was kept for next launch\n'
-        : 'exit before save completed — no recovery snapshot had been written yet\n';
+        ? 'exit before save completed: a recovery snapshot was kept for next launch\n'
+        : 'exit before save completed: no recovery snapshot had been written yet\n';
       try { stdout.write(line); } catch { /* best-effort */ }
     }
     // Best-effort, unconditional: this process is exiting either way, so its

package/src/runtime/provider-fallback.ts

@@ -1,10 +1,10 @@
 /**
- * provider-fallback.ts — boot-time model routability, the part the SDK does
+ * provider-fallback.ts, boot-time model routability, the part the SDK does
  * not cover.
  *
  * The pre-catalog fallback registration for the configured model
  * (`ensureConfiguredModelIsRoutable`) is the SDK's own
- * (`@pellux/goodvibes-sdk/platform/providers`) — this file only imports it for
+ * (`@pellux/goodvibes-sdk/platform/providers`), this file only imports it for
  * `ensureBootModelResolvable` below, which is NOT in the SDK: it is the
  * boot-time custom-provider-readiness wrapper this app's boot path needs and
  * the SDK's floor does not compose.
@@ -16,7 +16,7 @@ import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 /**
  * Boot-time custom-provider readiness. Custom providers register
  * asynchronously (services.ts fires initCustomProviders() without awaiting),
- * while the boot path resolves the current model synchronously — without
+ * while the boot path resolves the current model synchronously, without
  * waiting here, a saved provider.model that points at a custom provider
  * throws "not in registry" before the first frame renders. The routability
  * guard must re-run after ready(): its services-composition pass bails when

package/src/runtime/recovery-autosave.ts

@@ -1,5 +1,5 @@
 /**
- * recovery-autosave.ts — periodic recovery-file autosave + liveness-marker
+ * recovery-autosave.ts, periodic recovery-file autosave + liveness-marker
  * refresh, extracted out of main.ts to keep it under the architecture
  * line-count gate.
  *
@@ -22,8 +22,8 @@ export interface StartRecoveryAutosaveOptions {
   readonly runtime: { readonly sessionId: string };
   /**
    * The app's declare-once session-storage handle. Both the snapshot and the
-   * liveness marker resolve off it, so the startup recovery offer — which
-   * reads through the same handle — looks in the directory this writer used.
+   * liveness marker resolve off it, so the startup recovery offer, which
+   * reads through the same handle, looks in the directory this writer used.
    */
   readonly surface: SessionSurface;
   readonly buildSessionContinuityHints: () => Parameters<typeof buildPersistedSessionContext>[2];

package/src/runtime/recovery-decisions.ts

@@ -1,11 +1,11 @@
 /**
- * recovery-decisions.ts — a durable record of the recovery snapshots the user
+ * recovery-decisions.ts, a durable record of the recovery snapshots the user
  * has already said "Remove" to.
  *
  * The defect this exists for: answering Remove deletes the snapshot file, and
  * that was the whole memory of the decision. Anything that puts the file back
- * — a session still running on an older build rewriting its snapshot every
- * 60s, a restored backup, a synced directory — produced the same question
+ *, a session still running on an older build rewriting its snapshot every
+ * 60s, a restored backup, a synced directory, produced the same question
  * again on the next launch, and again after the next removal, with no way for
  * the user to make it stop. A decision the product forgets the instant it acts
  * on it is not a decision the user gets to make.
@@ -17,7 +17,7 @@
  * run.
  *
  * WHERE IT LIVES, and why not under `surface.stateDir`:
- * `<homeDirectory>/.goodvibes/<surfaceRoot>/recovery-decisions.json` — home-
+ * `<homeDirectory>/.goodvibes/<surfaceRoot>/recovery-decisions.json`, home-
  * anchored, matching session-liveness-marker.ts, and deliberately NOT the
  * project-anchored `surface.stateDir`. The snapshots this defends against
  * include the ones in the SDK's legacy shared recovery directory, which is
@@ -38,7 +38,7 @@ import type { SessionSurface } from '@/runtime/index.ts';
 /** One "the user removed this snapshot" decision. */
 export interface RecoveryRemovalRecord {
   readonly sessionId: string;
-  /** The project the decision was made in. Provenance — matching is on sessionId alone. */
+  /** The project the decision was made in. Provenance, matching is on sessionId alone. */
   readonly workspace: string;
   readonly removedAt: number;
 }
@@ -51,12 +51,12 @@ export interface RecoveryRemovalRecord {
  * Note what is deliberately NOT the pruning rule: "drop records whose snapshot
  * file no longer exists". Every record in here describes a file that was just
  * deleted, so that rule would empty the ledger immediately and reinstate the
- * exact defect it was written to fix — the point is precisely to still
+ * exact defect it was written to fix, the point is precisely to still
  * remember once the file comes back. Age and count are the honest bounds.
  *
- * Both bounds are enforced wherever records actually leave the disk —
+ * Both bounds are enforced wherever records actually leave the disk,
  * pruneRecoveryDecisions (once per boot) and recordRecoveryRemoval (every
- * write) — and both DISCLOSE what they discarded. A deletion nobody reports is
+ * write), and both DISCLOSE what they discarded. A deletion nobody reports is
  * indistinguishable from data loss, so the counts go in the log with the ledger
  * path, the TTL and the cap alongside them.
  */
@@ -93,8 +93,8 @@ interface LedgerLoad {
 }
 
 /**
- * Load and filter the ledger. Validation is by CONTENT — the file is parsed and
- * every entry is shape-checked — so a torn, truncated or zero-byte ledger left
+ * Load and filter the ledger. Validation is by CONTENT, the file is parsed and
+ * every entry is shape-checked, so a torn, truncated or zero-byte ledger left
  * by a crash reads as "no decisions recorded" instead of being trusted because
  * it exists. Never throws: a corrupt file must not be able to take a boot down,
  * and the worst outcome of losing it is that the user is asked once more.
@@ -127,7 +127,7 @@ function loadLedger(surface: SessionSurface, nowMs: number): LedgerLoad {
  * a corrupt file must not be able to take a boot down, and the worst outcome
  * of losing it is that the user is asked once more.
  *
- * This is a filtered READ — it discards nothing from disk, so it stays silent.
+ * This is a filtered READ, it discards nothing from disk, so it stays silent.
  * Disclosure belongs to the calls that actually delete: {@link pruneRecoveryDecisions}
  * and {@link recordRecoveryRemoval}.
  */
@@ -139,8 +139,8 @@ export function readRecoveryRemovals(surface: SessionSurface, nowMs: number = Da
  * Write `records` to the ledger through a temp file and an atomic rename.
  *
  * A plain `writeFileSync` onto the live path truncates first and fills after,
- * so a crash — or a second TUI in another terminal writing the same home-
- * anchored ledger at the same moment — could leave a half-written array that a
+ * so a crash, or a second TUI in another terminal writing the same home-
+ * anchored ledger at the same moment, could leave a half-written array that a
  * later boot reads as an empty or corrupt ledger, silently forgetting every
  * decision the user made. `rename` is atomic on the same filesystem: a reader
  * sees either the whole old ledger or the whole new one. The temp name carries
@@ -180,7 +180,7 @@ export interface RecoveryDecisionsPruneOutcome {
  * Apply both bounds to the on-disk ledger and say what was discarded.
  *
  * `readRecoveryRemovals` filters in memory on every call, so the expired
- * records were already inert — but they stayed on disk until the next time the
+ * records were already inert, but they stayed on disk until the next time the
  * user happened to answer "Remove", which on a machine where that never happens
  * again is never. This makes the reap explicit and, crucially, VISIBLE: a
  * silent deletion is indistinguishable from data loss, so every pass that drops
@@ -189,7 +189,7 @@ export interface RecoveryDecisionsPruneOutcome {
  * Idempotent and safe to run from two processes at once: it is a pure function
  * of the file's content plus `nowMs`, the rewrite is a temp-file-plus-rename,
  * and a second run over an already-pruned ledger drops nothing and writes
- * nothing. Best-effort — a ledger that cannot be pruned is left exactly as it
+ * nothing. Best-effort, a ledger that cannot be pruned is left exactly as it
  * was and never breaks a boot.
  */
 export function pruneRecoveryDecisions(surface: SessionSurface, nowMs: number = Date.now()): RecoveryDecisionsPruneOutcome {
@@ -209,7 +209,7 @@ export function pruneRecoveryDecisions(surface: SessionSurface, nowMs: number =
     // Do NOT rewrite: an unreadable ledger might be a transient read failure,
     // and replacing it with `[]` would turn "could not read" into "forgot every
     // decision the user made". Say so and leave it alone.
-    logger.warn('recovery decisions: ledger present but unreadable — left untouched, decisions may be re-asked', {
+    logger.warn('recovery decisions: ledger present but unreadable; left untouched, decisions may be re-asked', {
       ledger: path,
     });
     return outcome;
@@ -246,7 +246,7 @@ export function isRecoveryRemovalRecorded(surface: SessionSurface, sessionId: st
 }
 
 /**
- * Record that the user chose Remove for `sessionId`. Idempotent — a repeat
+ * Record that the user chose Remove for `sessionId`. Idempotent, a repeat
  * removal of a snapshot that came back refreshes the existing record's
  * timestamp rather than adding a second one, so the ledger cannot grow by one
  * entry per reappearance.
@@ -265,7 +265,7 @@ export function recordRecoveryRemoval(surface: SessionSurface, sessionId: string
       // Appending onto an unreadable ledger would rewrite it as a one-record
       // array, silently discarding whatever the user decided before. Say so
       // rather than quietly resetting their history.
-      logger.warn('recovery decisions: ledger unreadable — recording this removal replaces it', {
+      logger.warn('recovery decisions: ledger unreadable; recording this removal replaces it', {
         ledger: path,
         sessionId,
       });
@@ -290,6 +290,6 @@ export function recordRecoveryRemoval(surface: SessionSurface, sessionId: string
       });
     }
   } catch {
-    // Best-effort by construction — see the doc comment above.
+    // Best-effort by construction, see the doc comment above.
   }
 }

package/src/runtime/recovery-offer-wiring.ts

@@ -1,5 +1,5 @@
 /**
- * recovery-offer-wiring.ts — binds the startup recovery offer
+ * recovery-offer-wiring.ts, binds the startup recovery offer
  * (runtime/recovery-prompt.ts) to this shell's live objects.
  *
  * Kept out of main.ts so the entrypoint stays under the architecture
@@ -12,7 +12,7 @@
  *     actually happened. The transcript journal rebinds on that field
  *     (turn-event-wiring.ts), and every later turn snapshot keys off it.
  *     Without this the restored conversation would be written back under the
- *     fresh boot session id — the recovery point would be gone and its content
+ *     fresh boot session id, the recovery point would be gone and its content
  *     would live somewhere the user never asked for. It moves AFTER the apply
  *     rather than before, so a refusal (nothing on disk, a damaged file) leaves
  *     this boot on its own session instead of adopting one it never loaded.
@@ -67,7 +67,7 @@ export function buildRecoveryOfferWiring(input: RecoveryOfferWiringInput): Recov
           saveSource: 'user',
         });
       };
-      // The user picked "Resume it" in the offer modal — that answer, and
+      // The user picked "Resume it" in the offer modal, that answer, and
       // nothing else, is what unlocks the restore.
       const result = applyRecoverySnapshot({
         sessionId,
@@ -91,7 +91,7 @@ export function buildRecoveryOfferWiring(input: RecoveryOfferWiringInput): Recov
       // Unconditional, and the reason is the whole point of this feature: a
       // crash-recovery snapshot is NOT a session-store entry. The snapshot
       // file has just been retired by the read that loaded it, so until this
-      // write lands the recovered conversation exists only in memory — the
+      // write lands the recovered conversation exists only in memory, the
       // pointer below would name a session nothing could load, and `/session
       // resume <id>` would still not reach it. The gap-closure persist above
       // only fires when the journal actually had records to replay, so it