@pellux/goodvibes-tui 2.0.13 → 2.0.15

package/src/input/commands/workstream-runtime.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// workstream-runtime.ts — /workstream
+// workstream-runtime.ts, /workstream
 //
 // UX over the OrchestrationEngine (@pellux/goodvibes-sdk/platform/orchestration,
 //) via its command-facing facade wired onto RuntimeServices as
@@ -8,11 +8,11 @@
 // already is (bootstrap-command-context.ts).
 //
 // Render precedent: TRANSCRIPT + subcommand approve (like /plan approve,
-// planning-runtime.ts), NOT a panel — a multi-phase proposal is too rich for
+// planning-runtime.ts), NOT a panel, a multi-phase proposal is too rich for
 // a one-line confirm overlay, and Pillar-3 doctrine keeps work visible in the
 // transcript. create -> approve -> launch is a real three-step flow (edit and
 // cancel apply to the pending proposal too). The transcript IS the plan-review
-// gate: between create and approve the proposal is reshapable in place —
+// gate: between create and approve the proposal is reshapable in place,
 // edit-item rewrites one item's brief, remove-item drops an item (and unlinks
 // it from siblings' dependencies), move-item reorders authoring order, and
 // each re-renders the whole proposal and clears any prior approval, so nothing
@@ -20,7 +20,7 @@
 // immediately materializes a real, ticking-eligible Workstream with no
 // pre-creation "draft" concept, so approval happens on a TUI-held draft
 // (workstream-services.ts's WorkstreamDraft) before anything is created in
-// the engine at all — see that module's header doc for the full reality-wins
+// the engine at all, see that module's header doc for the full reality-wins
 // divergence from the design brief.
 // ---------------------------------------------------------------------------
 
@@ -43,7 +43,7 @@ function shortId(id: string): string {
 /**
  * The engine's ONLY two terminal work-item states (mirrors the SDK's own
  * internal TERMINAL_ITEM_STATES in platform/runtime/fleet/adapters/
- * orchestration.ts and engine.ts's kill() guard — neither is exported, so
+ * orchestration.ts and engine.ts's kill() guard, neither is exported, so
  * this is kept in lockstep by hand). Deriving "active" as NOT-terminal
  * instead of enumerating the non-terminal states means a state this module
  * doesn't know about yet (as 'blocked-budget' once was here) is still
@@ -56,7 +56,7 @@ function isActiveItemState(state: WorkItemState): boolean {
   return !TERMINAL_ITEM_STATES.has(state);
 }
 
-/** Mirrors the engine's templateForPhase (phase-runner.ts): only 'review'/'gate' phases run the general template — everything else, INCLUDING 'custom', runs the engineer template regardless of phase.role's text. */
+/** Mirrors the engine's templateForPhase (phase-runner.ts): only 'review'/'gate' phases run the general template, everything else, INCLUDING 'custom', runs the engineer template regardless of phase.role's text. */
 function templateForPhaseKind(kind: PhaseKind): string {
   return kind === 'review' || kind === 'gate' ? 'general' : 'engineer';
 }
@@ -64,13 +64,13 @@ function templateForPhaseKind(kind: PhaseKind): string {
 /**
  * Pre-fan-out quota consultation for /workstream launch. Assesses whether the
  * draft's work-item count (the fan-out this launch is about to create, worst
- * case — items can run concurrently within a phase) is likely to exhaust the
+ * case, items can run concurrently within a phase) is likely to exhaust the
  * active provider's quota window, grounded in observed rate-limit signals
  * (quota.fanout.get). Returns a printable warning + evidence when the daemon
  * reports 'likely-exhausts'; returns null for 'unlikely'/'unknown' (no
  * evidence of risk is not itself evidence of safety, so those verdicts never
  * block) and whenever the check itself can't run (daemon unavailable/
- * unreachable, or no active provider) — an infra gap in the quota check is
+ * unreachable, or no active provider), an infra gap in the quota check is
  * not grounds to block launching work the operator already approved.
  */
 async function checkFanoutQuotaWarning(ctx: CommandContext, draft: WorkstreamDraft): Promise<string | null> {
@@ -93,12 +93,12 @@ async function checkFanoutQuotaWarning(ctx: CommandContext, draft: WorkstreamDra
     ev.observedLimit !== undefined ? `observedLimit=${ev.observedLimit}` : null,
   ].filter((part): part is string => part !== null);
   return [
-    `[workstream launch] WARNING — ${provider} likely exhausts its quota window for ${agentCount} agent(s) fanning out.`,
+    `[workstream launch] WARNING: ${provider} likely exhausts its quota window for ${agentCount} agent(s) fanning out.`,
     `  reason: ${assessment.reason}`,
     `  evidence: ${evidenceParts.join(' ')}`,
     '',
     `Launch anyway: /workstream launch ${draft.id} --force`,
-    'Cancel: do nothing — the approved proposal stays ready to launch later.',
+    'Cancel: do nothing; the approved proposal stays ready to launch later.',
   ].join('\n');
 }
 
@@ -106,12 +106,12 @@ async function checkFanoutQuotaWarning(ctx: CommandContext, draft: WorkstreamDra
  * Launch an already-approved draft through its gates (best-of-N attempt
  * validation, then the fan-out quota warning unless `--force`), and print the
  * outcome. Shared by `launch` and by `approve` (which launches in the same act
- * — the one confirmed step that replaces the old approve-then-retype ceremony).
+ *, the one confirmed step that replaces the old approve-then-retype ceremony).
  */
 async function launchApprovedDraft(ctx: CommandContext, service: WorkstreamCommandService, id: string, draft: WorkstreamDraft, force: boolean): Promise<void> {
   const attemptsCheck = validateAttempts(draft.spec);
   if (attemptsCheck.violations.length > 0) {
-    ctx.print(`Cannot launch ${id} — best-of-N plan constraints are violated:\n${attemptsCheck.violations.map((v) => `  - ${v}`).join('\n')}\nFix the plan (or drop the attempts) and re-approve.`);
+    ctx.print(`Cannot launch ${id}: best-of-N plan constraints are violated:\n${attemptsCheck.violations.map((v) => `  - ${v}`).join('\n')}\nFix the plan (or drop the attempts) and re-approve.`);
     return;
   }
   if (!force) {
@@ -126,15 +126,15 @@ async function launchApprovedDraft(ctx: CommandContext, service: WorkstreamComma
     ctx.print(`Could not launch ${id}.`);
     return;
   }
-  ctx.print(`Launched workstream ${result.workstreamId} — track it with /workstream status ${result.workstreamId} or the Fleet panel.`);
+  ctx.print(`Launched workstream ${result.workstreamId}: track it with /workstream status ${result.workstreamId} or the Fleet panel.`);
 }
 
 /**
  * phase.role for a 'custom' phase is the free-text description passed to
- * `/workstream insert-phase` — it is purely COSMETIC. Neither
+ * `/workstream insert-phase`, it is purely COSMETIC. Neither
  * templateForPhase nor buildPhaseTask (phase-runner.ts, engine-side) ever
  * reads it: a custom phase always runs the engineer template against the
- * work item's own task text. Rendering it as `<kind> — <role>` like a real
+ * work item's own task text. Rendering it as `<kind>, <role>` like a real
  * role would falsely imply the description drives what the phase does, so
  * custom phases get an explicit "this is a description, not a role" label
  * instead.
@@ -143,7 +143,7 @@ function formatPhaseLabel(phase: { readonly kind: PhaseKind; readonly role: Phas
   if (phase.kind === 'custom') {
     return `custom: "${phase.role}" (runs the ${templateForPhaseKind(phase.kind)} template)`;
   }
-  return `${phase.kind} — ${phase.role}`;
+  return `${phase.kind}: ${phase.role}`;
 }
 
 /**
@@ -151,7 +151,7 @@ function formatPhaseLabel(phase: { readonly kind: PhaseKind; readonly role: Phas
  * `args` (create/edit both accept it ahead of, or interleaved with, the task
  * text). Returns the flag stripped out so the remaining tokens are the task
  * text exactly as before this flag existed. An unrecognized value is a hard
- * error (never silently ignored or defaulted) — a typo'd isolation mode
+ * error (never silently ignored or defaulted), a typo'd isolation mode
  * must never quietly launch in the wrong one.
  */
 function extractIsolationFlag(args: readonly string[]): { isolation?: WorkstreamIsolation; rest: string[]; error?: string } {
@@ -174,7 +174,7 @@ function extractIsolationFlag(args: readonly string[]): { isolation?: Workstream
 
 /**
  * Per-item merge-state text for `/workstream status` (worktree isolation
- * only — see formatItemMergeState's caller). Distinct from `item.state` (the
+ * only, see formatItemMergeState's caller). Distinct from `item.state` (the
  * pipeline verdict): an item can be terminally 'passed' while its branch is
  * still 'merge pending' in the integration lane, or stuck at
  * 'merge-conflict' with its worktree deliberately kept for inspection.
@@ -213,7 +213,7 @@ function formatItemDependencyNote(item: WorkItem, ws: Workstream): string {
 /**
  * Compact item + dependency graph for the draft-approval view (BIG-3 item 4):
  * items in ordinal order (the spec preserves the proposal's order), each with
- * an honest text 'after: X, Y' clause when it depends on siblings — no fake DAG
+ * an honest text 'after: X, Y' clause when it depends on siblings, no fake DAG
  * art. Dependency ids are resolved back to titles from the spec itself.
  */
 function formatDraftItems(spec: CreateWorkstreamInput): string[] {
@@ -225,7 +225,7 @@ function formatDraftItems(spec: CreateWorkstreamInput): string[] {
     const attempts = (it.attempts ?? 1) > 1 ? `  [best-of-${it.attempts}${it.autoAcceptWinner ? ', auto-accept winner' : ''}]` : '';
     lines.push(`  ${i + 1}. ${it.title}${after}${attempts}`);
     // Show the brief (the instructions the item's agent runs) only when it says
-    // something the title doesn't — an edited brief (via /workstream edit-item)
+    // something the title doesn't, an edited brief (via /workstream edit-item)
     // must be visible on the review surface, but a decomposition whose title and
     // brief coincide would just repeat itself.
     if (it.task.trim() && it.task.trim() !== it.title.trim()) {
@@ -265,13 +265,13 @@ function formatProvenance(p: WorkstreamDraftProvenance): string {
   return 'Decomposition: heuristic (configured)';
 }
 
-/** The engine's own PlanProposal is deliberately not rendered as the launchable spec — see workstream-services.ts's buildSpec doc. This renders the REAL launchable spec (so the proposal and the launch are always the same plan) plus an honest provenance line describing how the goal was decomposed. */
+/** The engine's own PlanProposal is deliberately not rendered as the launchable spec, see workstream-services.ts's buildSpec doc. This renders the REAL launchable spec (so the proposal and the launch are always the same plan) plus an honest provenance line describing how the goal was decomposed. */
 function renderDraftProposal(draft: WorkstreamDraft): string {
   const lines: string[] = [];
-  lines.push(`Workstream proposal ${draft.id} — "${draft.task}"`);
+  lines.push(`Workstream proposal ${draft.id}: "${draft.task}"`);
   lines.push(`Isolation: ${draft.spec.isolation ?? 'shared (default)'}`);
   lines.push(
-    `Planner: strategy=${draft.gate.strategy} (${draft.gate.reasonCode}) — ${AdaptivePlanner.explainReasonCode(draft.gate.reasonCode)}`,
+    `Planner: strategy=${draft.gate.strategy} (${draft.gate.reasonCode}); ${AdaptivePlanner.explainReasonCode(draft.gate.reasonCode)}`,
   );
   lines.push(formatProvenance(draft.provenance));
   // Honest mapping boundary (BIG-3 item 4): a multi-item proposal launches as
@@ -281,8 +281,8 @@ function renderDraftProposal(draft: WorkstreamDraft): string {
   const multiItem = draft.spec.items.length > 1;
   lines.push(
     multiItem
-      ? `Mapping: multi-item plan — ${draft.spec.items.length} items run the engineer→review pipeline, dependency-scheduled.`
-      : 'Mapping: single-item compat chain (engineer→review) — no multi-item structure to schedule.',
+      ? `Mapping: multi-item plan; ${draft.spec.items.length} items run the engineer→review pipeline, dependency-scheduled.`
+      : 'Mapping: single-item compat chain (engineer→review); no multi-item structure to schedule.',
   );
   lines.push('Phases:');
   draft.spec.phases.forEach((phase, i) => {
@@ -299,7 +299,7 @@ function renderDraftProposal(draft: WorkstreamDraft): string {
     lines.push('Best-of-N: plan is INVALID and cannot launch until fixed:');
     for (const v of attemptsCheck.violations) lines.push(`  ✗ ${v}`);
   } else if (attemptsCheck.hasAttempts) {
-    lines.push('Best-of-N: worktree + stable-id constraints satisfied — winners are chosen via /workstream attempts pick, and any dependents wait for the winner to be picked and merged.');
+    lines.push('Best-of-N: worktree + stable-id constraints satisfied; winners are chosen via /workstream attempts pick, and any dependents wait for the winner to be picked and merged.');
   }
   for (const n of attemptsCheck.notes) lines.push(`  note: ${n}`);
   lines.push(
@@ -312,18 +312,18 @@ function renderDraftProposal(draft: WorkstreamDraft): string {
   // Honest durability note (see workstream-services.ts's REALITY-WINS doc):
   // the engine has no pre-launch draft concept, but the TUI journals this
   // proposal to disk (.goodvibes/orchestration/drafts/) and reloads it at
-  // startup, so it survives a restart and is here to launch afterward — its
+  // startup, so it survives a restart and is here to launch afterward, its
   // approval state included.
-  lines.push('Note: saved to .goodvibes/orchestration/drafts/ — survives a restart until you launch or cancel it.');
+  lines.push('Note: saved to .goodvibes/orchestration/drafts/; survives a restart until you launch or cancel it.');
   return lines.join('\n');
 }
 
 function renderWorkstreamStatus(ws: Workstream): string {
   const isolated = ws.isolation === 'worktree';
   const lines: string[] = [];
-  lines.push(`Workstream ${ws.id} — "${ws.title}"`);
+  lines.push(`Workstream ${ws.id}: "${ws.title}"`);
   lines.push(`Isolation: ${ws.isolation ?? 'shared'}`);
-  // Origin provenance (BIG-3 item 1) — only present on workstreams assembled
+  // Origin provenance (BIG-3 item 1), only present on workstreams assembled
   // from a decomposition proposal; absent for compat/authored ones.
   if (ws.provenance) {
     const pv = ws.provenance;
@@ -344,7 +344,7 @@ function renderWorkstreamStatus(ws: Workstream): string {
     lines.push(`  ${shortId(item.id)}  [${item.state}]  ${item.title}  — phase: ${item.currentPhaseId ?? '—'}${depNote}${mergeNote}`);
   }
   if (isolated) {
-    // Honest terminal-summary truth (never inferred from item.state alone —
+    // Honest terminal-summary truth (never inferred from item.state alone,
     // an item can be terminally 'passed' with its branch still unmerged):
     // an item counts as unmerged the instant it enters the integration lane
     // (mergeState 'pending') and stays counted through a conflict or any
@@ -352,8 +352,8 @@ function renderWorkstreamStatus(ws: Workstream): string {
     const unmerged = ws.items.filter((item) => item.mergeState === 'pending' || item.mergeState === 'conflict' || item.worktreeKept);
     lines.push(
       unmerged.length > 0
-        ? `Unmerged items: ${unmerged.length} (${unmerged.map((item) => shortId(item.id)).join(', ')}) — this run is NOT fully integrated yet.`
-        : 'Unmerged items: none — every terminated item is merged (or had nothing to merge).',
+        ? `Unmerged items: ${unmerged.length} (${unmerged.map((item) => shortId(item.id)).join(', ')}); this run is NOT fully integrated yet.`
+        : 'Unmerged items: none; every terminated item is merged (or had nothing to merge).',
     );
   }
   return lines.join('\n');
@@ -387,7 +387,7 @@ function resolveWorkstream(service: WorkstreamCommandService, ref: string): Work
  * approve/edit/launch/*-item all fail this way when `id` doesn't resolve to a
  * held draft. Drafts are now journaled to disk and reloaded at startup (see
  * renderDraftProposal's note and workstream-services.ts's REALITY-WINS doc), so
- * a restart no longer silently wipes them — a missing id is a typo or a
+ * a restart no longer silently wipes them, a missing id is a typo or a
  * stale/already-launched proposal, and the plain message is the honest guess.
  * `service` is kept in the signature so callers stay uniform and a future
  * "did you mean <closest id>?" hint has somewhere to live.
@@ -458,7 +458,7 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
         const target = ref ? resolveWorkstream(service, ref) : (live.length === 1 ? live[0] : undefined);
         if (!target) {
           if (!ref && live.length > 1) {
-            ctx.print(`Multiple workstreams running — specify one: ${live.map((ws) => shortId(ws.id)).join(', ')}`);
+            ctx.print(`Multiple workstreams running: specify one: ${live.map((ws) => shortId(ws.id)).join(', ')}`);
             return;
           }
           ctx.print(ref ? `No workstream found: ${ref}` : 'No workstreams running. Use /workstream list to see pending proposals.');
@@ -489,7 +489,7 @@ export function registerWorkstreamRuntimeCommands(registry: CommandRegistry): vo
           gate: templateGate,
         });
         if (!inserted) {
-          ctx.print(`Could not insert phase — is "${id}" still an active workstream?`);
+          ctx.print(`Could not insert phase: is "${id}" still an active workstream?`);
           return;
         }
         ctx.print(`Inserted phase "${description}" into ${shortId(ws.id)} after ordinal ${lastOrdinal} (new ordinal ${inserted.ordinal}).`);

package/src/input/commands/worktree-runtime.ts

@@ -4,7 +4,7 @@ import type { CommandRegistry } from '../command-registry.ts';
 import { openCommandPanel, requireShellPaths } from './runtime-services.ts';
 import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
 
-/** Compact per-row setup-state tag for /worktree review — absent when setup has never run; failure stands out. */
+/** Compact per-row setup-state tag for /worktree review, absent when setup has never run; failure stands out. */
 export function formatSetupTag(setup: ManagedWorktreeMeta['setup']): string {
   if (!setup) return '';
   if (setup.state === 'failed') return ' setup:FAILED';
@@ -12,13 +12,13 @@ export function formatSetupTag(setup: ManagedWorktreeMeta['setup']): string {
   return ' setup:skipped';
 }
 
-/** Full setup-state block for /worktree inspect — the failing step + captured output when failed. */
+/** Full setup-state block for /worktree inspect, the failing step + captured output when failed. */
 export function formatSetupDetail(setup: ManagedWorktreeMeta['setup']): string[] {
   if (!setup) return ['  setup: never run'];
   if (setup.state !== 'failed') return [`  setup: ${setup.state}`];
   const failingStep = setup.steps.find((step) => !step.ok);
   return [
-    `  setup: FAILED — ${setup.error ?? 'unknown error'}`,
+    `  setup: FAILED; ${setup.error ?? 'unknown error'}`,
     ...(failingStep
       ? [
           `    failing step (${failingStep.kind}): ${failingStep.label}${failingStep.exitCode !== undefined ? ` (exit ${failingStep.exitCode})` : ''}`,
@@ -94,7 +94,7 @@ export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void
         try {
           const { setup } = await rpc.sdk.operator.invoke('worktrees.setup.run', { path });
           if (setup.state === 'skipped') {
-            ctx.print('[worktree setup] skipped — no setup commands or carry-over globs are configured.');
+            ctx.print('[worktree setup] skipped: no setup commands or carry-over globs are configured.');
           } else if (setup.state === 'succeeded') {
             ctx.print(`[worktree setup] succeeded (${setup.steps.length} step(s)).`);
           } else {
@@ -148,7 +148,7 @@ export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void
       if (sub === 'discard') {
         // Discard is a real destructive act, not a metadata flip: route it
         // through the worktrees.discard operator verb (preservation commit,
-        // git worktree removal, honest receipt) — the SAME behavior as the
+        // git worktree removal, honest receipt), the SAME behavior as the
         // Fleet panel's D key. Typing the verb with an explicit path is the
         // confirmation.
         const path = args[1];
@@ -167,7 +167,7 @@ export function registerWorktreeRuntimeCommands(registry: CommandRegistry): void
             ctx.print([
               `[worktree discard] Discarded ${receipt.path}`,
               `  branch kept: ${receipt.branch || '(unknown)'}`,
-              `  preservation commit: ${receipt.preservedCommit || '(none — nothing to preserve)'}`,
+              `  preservation commit: ${receipt.preservedCommit || '(none; nothing to preserve)'}`,
               `  ${receipt.detail}`,
             ].join('\n'));
           } else {

package/src/input/composer-capture.ts

@@ -1,11 +1,11 @@
 /**
- * Composer capture intents — leading markers in the composer that write to
+ * Composer capture intents, leading markers in the composer that write to
  * memory instead of (or in addition to) sending a turn.
  *
  *   `!# <text>`  pins <text> to session memory AND sends it as a normal prompt
  *                (pre-existing behavior).
  *   `# <text>`   captures <text> as a session-memory note and does NOT send a
- *                turn — a pure "jot this down" gesture. A single leading `#`
+ *                turn, a pure "jot this down" gesture. A single leading `#`
  *                only; `##...` (markdown headings) is left alone so it can be
  *                sent as an ordinary prompt.
  *
@@ -38,7 +38,7 @@ const AT_MODEL_PATTERN = /@model:([^\s]+)/g;
  * The switch is a real, persisted selection (config `provider.model`), not a
  * per-turn override, so the runtime labels are updated alongside it and each
  * one is announced. An unknown id is reported as unknown rather than silently
- * dropped — the user asked for a specific backend and did not get it.
+ * dropped, the user asked for a specific backend and did not get it.
  */
 export function applyAtModelDirective(input: string, deps: AtModelDeps): string {
   let text = input;
@@ -84,7 +84,7 @@ function truncateForChip(text: string): string {
  * the returned `text` is empty, the caller should not send a turn.
  */
 export function applyComposerCapture(input: string, deps: ComposerCaptureDeps): ComposerCaptureResult {
-  // `!#` — pin to session memory and continue to send as a prompt.
+  // `!#`, pin to session memory and continue to send as a prompt.
   if (input.startsWith('!#')) {
     const memoryText = input.slice(2).trim();
     if (!memoryText) {
@@ -96,7 +96,7 @@ export function applyComposerCapture(input: string, deps: ComposerCaptureDeps):
     return { text: memoryText, captured: true };
   }
 
-  // `#` (single, not `##`) — capture a note to session memory; do not send.
+  // `#` (single, not `##`), capture a note to session memory; do not send.
   const leading = input.replace(/^\s+/, '');
   if (leading.startsWith('#') && !leading.startsWith('##')) {
     const noteText = leading.slice(1).trim();

package/src/input/concealed-input.ts

@@ -17,7 +17,7 @@
 export interface ConcealedInputRequest {
   /**
    * Short label describing what is being asked for, e.g. 'Password' or
-   * 'API key'. Surfaced by the caller (e.g. as a system message) — the composer
+   * 'API key'. Surfaced by the caller (e.g. as a system message), the composer
    * itself only masks; it does not print the label.
    */
   readonly label?: string;
@@ -30,7 +30,7 @@ export interface ConcealedInputRequest {
 /**
  * Mask a composer buffer for display. Every UTF-16 code unit except a newline
  * becomes a bullet, so the masked string has the EXACT same length and line
- * structure as the plaintext — word-wrap and cursor-position math (which index
+ * structure as the plaintext, word-wrap and cursor-position math (which index
  * the string by code unit) stay correct while no plaintext character ever
  * reaches the screen buffer.
  */

package/src/input/config-modal-types.ts

@@ -1,14 +1,14 @@
 import type { ModalSectionStyle } from '../renderer/modal-factory.ts';
 
 /**
- * Config-modal host — the shared seam every MIGRATE-TO-MODAL surface
+ * Config-modal host, the shared seam every MIGRATE-TO-MODAL surface
  * (provider-health, services, subscription, remote, local-auth, settings-sync,
  * sandbox, and the ecosystem/governance set) is expressed through.
  *
  * A surface is PURE DATA + ACTIONS: it hands the host a `buildView()` that maps
  * live read-models to a tabbed, list-structured view, plus a declarative action
  * table. The host owns all key routing (tab switch, list nav, Esc, confirm) and
- * the stable-layout liveness contract — the surface never touches the input
+ * the stable-layout liveness contract, the surface never touches the input
  * system directly (the charter's "do not invent a parallel input system").
  *
  * Liveness doctrine (charter: "live data, stable layout"): `buildView()` is
@@ -41,7 +41,7 @@ export interface ConfigModalRow {
 
 /** One tab (section) of a surface. Tabs are switched with left/right or Tab. */
 export interface ConfigModalTab {
-  /** Stable id — preserves the active tab across refresh + re-open. */
+  /** Stable id, preserves the active tab across refresh + re-open. */
   readonly id: string;
   /** Tab-strip label. */
   readonly label: string;
@@ -61,7 +61,7 @@ export interface ConfigModalView {
   readonly title: string;
   readonly tabs: readonly ConfigModalTab[];
   /**
-   * Non-null when the read-model is unavailable/degraded — the host renders a
+   * Non-null when the read-model is unavailable/degraded, the host renders a
    * banner and still shows whatever tabs/rows are present (honest degraded
    * state rather than a blank or a throw).
    */
@@ -79,7 +79,7 @@ export interface ConfigModalActionContext {
   /** Print a line to the conversation transcript. */
   readonly print: (message: string) => void;
   /**
-   * Execute a slash command — the same seam panels used via
+   * Execute a slash command, the same seam panels used via
    * `PanelIntegrationContext.executeCommand`. This is how a migrated action
    * preserves parity: the mutation still runs through its existing, tested
    * command (e.g. `/settings-sync resolve`, `/local-auth delete-user`).
@@ -87,14 +87,14 @@ export interface ConfigModalActionContext {
   readonly executeCommand?: (name: string, args: string[]) => Promise<unknown>;
   /** Open another named modal surface (cross-surface navigation, e.g. the
    *  services surface jumping to the subscription surface). Swaps the active
-   *  surface in place — the same seam ctx.openModal uses. */
+   *  surface in place, the same seam ctx.openModal uses. */
   readonly openModal?: (name: string) => void;
   /**
-   * Submit text to the chat/model as a real user turn — the same composer
+   * Submit text to the chat/model as a real user turn, the same composer
    * submission seam `handleUserInput` uses (threaded from CommandContext.submitInput).
    * Generic across surfaces (any modal may hand free-form input to the model).
    *
-   * ORDERING GUARD: a turn must never start while a modal owns the keyboard —
+   * ORDERING GUARD: a turn must never start while a modal owns the keyboard,
    * that is the modal-liveness hazard (a live turn painting under a modal that
    * still captures keys). Callers MUST `close()` the modal BEFORE invoking
    * `submitInput`. The planning modal's free-form submit follows this ordering.
@@ -107,11 +107,11 @@ export interface ConfigModalActionContext {
   /** Close the modal (focus returns to whatever opened it). */
   readonly close: () => void;
   /**
-   * Switch the active tab and select a row within it, by id — the in-surface
+   * Switch the active tab and select a row within it, by id, the in-surface
    * "jump" affordance (e.g. the Memory modal's Proposals tab jumping to an
    * affected record in the Review Queue tab, rather than opening a second
    * modal). Host-owned, populated by ConfigModal itself (like `close`/
-   * `setStatus`) — a surface's `onAction` calls it, never constructs it. A
+   * `setStatus`), a surface's `onAction` calls it, never constructs it. A
    * no-op if either id is not present in the surface's current structure; the
    * surface should check reachability itself and print an honest status line
    * when it isn't, rather than relying on a silent no-op.
@@ -124,10 +124,10 @@ export interface ConfigModalAction {
   /**
    * Trigger key: a single printable char ('r', 'd') or a named key ('enter').
    * Must not collide with the host-reserved nav keys (up/down/left/right/tab/
-   * j/k/escape/'/') — those are consumed by the host before actions are
+   * j/k/escape/'/'), those are consumed by the host before actions are
    * consulted. '/' arms the host's type-to-filter (item 1); while
    * filtering, EVERY printable key (not just j/k) is captured by the query
-   * instead of firing an action — see handleConfigModalToken.
+   * instead of firing an action, see handleConfigModalToken.
    */
   readonly key: string;
   /** Action id passed to `onAction`. */
@@ -149,23 +149,23 @@ export interface ConfigModalAction {
 }
 
 /**
- * A named config-modal surface. Pure seam — the host knows nothing about the
+ * A named config-modal surface. Pure seam, the host knows nothing about the
  * surface's data. Built once (closing over its read-models) and registered on
  * PanelManager via `registerModalSurface`; opened by name from a panel-id
  * redirect hit or `ctx.openModal(name)`.
  */
 export interface ConfigModalSurface {
-  /** Modal name — the key `registerModalRedirect` / `ctx.openModal` use. */
+  /** Modal name, the key `registerModalRedirect` / `ctx.openModal` use. */
   readonly name: string;
   /** Fallback title (buildView().title wins per tick). */
   readonly title: string;
   /**
    * Build the current view from live read-models. Called on open, on every
-   * interaction boundary, AND on every render tick. MUST be pure and cheap —
+   * interaction boundary, AND on every render tick. MUST be pure and cheap,
    * snapshot reads only, no async, no mutation.
    */
   buildView(): ConfigModalView;
-  /** Declarative action table (optional — a read-only surface has none). */
+  /** Declarative action table (optional, a read-only surface has none). */
   readonly actions?: readonly ConfigModalAction[];
   /** Handle an action fired by its key. */
   onAction?(actionId: string, ctx: ConfigModalActionContext): void;