@pellux/goodvibes-tui 2.0.14 → 2.0.15

package/src/permissions/broker-approval-card.ts

@@ -1,17 +1,17 @@
 /**
- * broker-approval-card — render a broker-originated approval ask as a real
+ * broker-approval-card, render a broker-originated approval ask as a real
  * TUI approval card.
  *
  * The approval broker publishes every ask (local runtime asks, plus
  * broker-originated ones like the CI fix-session offer). Local asks carry a
  * `localPrompt` that opens their own card; broker-originated asks do not, so
- * before this they were invisible in the TUI — the ask sat pending with no
+ * before this they were invisible in the TUI, the ask sat pending with no
  * surface. This helper opens a card straight from broker state for those.
  *
  * A local ask's own prompt is opened by the broker immediately AFTER it
  * publishes (see ApprovalBroker.requestApproval), so the open here is deferred
  * one microtask and re-checks: if a card (the local one, or another broker
- * card) is already up, it does nothing — only a genuinely unhandled ask surfaces.
+ * card) is already up, it does nothing, only a genuinely unhandled ask surfaces.
  * The card's resolve answers the broker directly via resolveApproval, so a TUI
  * decision on a broker-originated ask reaches every waiter on that record.
  */
@@ -21,7 +21,7 @@ import type { ApprovalRequesterLookup } from './hunk-selection.ts';
 import type { PendingPermissionState } from '../shell/blocking-input.ts';
 import type { PermissionPromptRequest, RememberTier } from '@pellux/goodvibes-sdk/platform/permissions';
 
-/** The broker seam this helper answers through — a subset of ApprovalBroker. */
+/** The broker seam this helper answers through, a subset of ApprovalBroker. */
 export interface BrokerApprovalCardBroker extends ApprovalRequesterLookup {
   getApproval(approvalId: string): { readonly status: string; readonly request: PermissionPromptRequest } | null;
   resolveApproval(
@@ -46,7 +46,7 @@ export interface BrokerApprovalChangeParams {
     readonly request: PermissionPromptRequest;
     /** The REAL attachable session id once an ACCEPTED ask (e.g. a ci:fix-session offer) has spawned its session. */
     readonly fixSessionId?: string | undefined;
-    /** The honest failure when an accepted ask's spawn did NOT produce an attachable session — mutually exclusive with fixSessionId. */
+    /** The honest failure when an accepted ask's spawn did NOT produce an attachable session, mutually exclusive with fixSessionId. */
     readonly fixSessionError?: string | undefined;
   };
   readonly getPending: () => PendingPermissionState | null;
@@ -55,7 +55,7 @@ export interface BrokerApprovalChangeParams {
   readonly render: () => void;
   /**
    * Fired when a record carries the id of a session an accepted ask spawned
-   * (the CI fix-session). The surface that accepted — attached now — turns this
+   * (the CI fix-session). The surface that accepted, attached now, turns this
    * into a jump/attach affordance. Called each time the field is seen; the
    * caller de-duplicates by id.
    */
@@ -74,7 +74,7 @@ export interface BrokerApprovalChangeParams {
 const isActiveStatus = (status: string): boolean => status === 'pending' || status === 'claimed';
 
 export interface FixSessionAffordanceDeps {
-  /** Announce the ready fix session as one actionable line — never a retype instruction. */
+  /** Announce the ready fix session as one actionable line, never a retype instruction. */
   readonly notify: (message: string) => void;
   /** Arm the one-key jump with the spawned session id; the surface consumes it on the jump key. */
   readonly arm: (fixSessionId: string) => void;
@@ -83,7 +83,7 @@ export interface FixSessionAffordanceDeps {
 /**
  * Build the one-key jump/attach affordance for a spawned fix-session: the first
  * time a given session id is seen it ARMS the jump (the surface attaches on the
- * jump key — the machine does the resume, the user never retypes an id) and
+ * jump key, the machine does the resume, the user never retypes an id) and
  * surfaces a one-line actionable notice. Repeats are no-ops (de-duplicated by
  * id), so the live record update and the listApprovals refresh path can both
  * feed it safely.
@@ -94,7 +94,7 @@ export function buildFixSessionAffordance(deps: FixSessionAffordanceDeps): (fixS
     if (seen.has(fixSessionId)) return;
     seen.add(fixSessionId);
     deps.arm(fixSessionId);
-    deps.notify('[CI] Fix session ready — press j to jump to it.');
+    deps.notify('[CI] Fix session ready: press j to jump to it.');
   };
 }
 
@@ -116,7 +116,7 @@ export function buildFixSessionErrorNotice(notify: (message: string) => void): (
 export interface FixSessionAttachKeyDeps {
   /** The armed fix-session id (the surface clears the arm before calling this). */
   readonly armedFixSessionId: string;
-  /** Attach/jump to the fix session — runs the resume so the user never retypes an id. */
+  /** Attach/jump to the fix session, runs the resume so the user never retypes an id. */
   readonly attach: (fixSessionId: string) => void;
   readonly render: () => void;
 }
@@ -163,8 +163,8 @@ export function handleBrokerApprovalChange(params: BrokerApprovalChangeParams):
   const active = isActiveStatus(approval.status);
 
   // An accepted ask that spawned a session (the CI fix-session) publishes its
-  // REAL session id as a record update — the live in-process handle to jump to
-  // it — or, when the spawn failed, an honest error instead of a dead id
+  // REAL session id as a record update, the live in-process handle to jump to
+  // it, or, when the spawn failed, an honest error instead of a dead id
   // (mutually exclusive). Both arrive after the card has resolved and cleared,
   // so surface them independently of the card lifecycle below.
   if (approval.fixSessionId) params.onFixSessionStarted?.(approval.fixSessionId);
@@ -172,7 +172,7 @@ export function handleBrokerApprovalChange(params: BrokerApprovalChangeParams):
 
   const pending = getPending();
   if (pending && pending.callId === approval.callId) {
-    // This is the card already on screen — clear it once its approval resolves.
+    // This is the card already on screen, clear it once its approval resolves.
     if (!active) { setPending(null); render(); }
     return;
   }

package/src/permissions/hunk-selection.ts

@@ -6,7 +6,7 @@ import type { PermissionAttribution, PermissionPromptRequest, RememberTier } fro
  * Scoped to the `edit` tool only: EditInput.edits is already an array of
  * independent, atomic find/replace units (each a natural "hunk"), so no
  * diff/hunk-apply primitive is needed here. The `write` (whole-file
- * overwrite) tool stays whole-payload accept/reject — true whole-file hunk
+ * overwrite) tool stays whole-payload accept/reject, true whole-file hunk
  * splitting would require a genuinely new SDK diff/patch-apply primitive,
  * flagged as an explicit v2 follow-up, not built here.
  *
@@ -18,7 +18,7 @@ import type { PermissionAttribution, PermissionPromptRequest, RememberTier } fro
  * symbol, per the cross-repo compile contract for this wave.
  */
 
-/** Structural shape of one EditItem, read defensively — see module doc. */
+/** Structural shape of one EditItem, read defensively, see module doc. */
 export interface EditItemLike {
   readonly path: string;
   readonly find: string;
@@ -39,7 +39,7 @@ export type HunkCommit = 'apply' | 'cancel' | null;
  * (0.36.0, no `modifiedArgs` field yet) so main.ts can resolve a decision
  * carrying `modifiedArgs` without a nominal import of a not-yet-published
  * SDK symbol. Assign to a variable of this type before calling the SDK's
- * typed `resolve(decision: PermissionPromptDecision)` — passing a variable
+ * typed `resolve(decision: PermissionPromptDecision)`, passing a variable
  * (not an object literal) sidesteps TypeScript's excess-property check, and
  * the extra field is invisible to 0.36.0 callers, structurally compatible
  * once 0.37 adds it for real.
@@ -50,7 +50,7 @@ export interface PermissionPromptDecisionWithModifiedArgs {
   modifiedArgs?: Record<string, unknown>;
   /** Generalizing remember tier: 'session' | 'exact' | 'command-class' | 'path' | 'tool'. */
   rememberTier?: RememberTier;
-  /** Free-text from the user; most useful on deny — rides the structured "user declined" tool result. */
+  /** Free-text from the user; most useful on deny, rides the structured "user declined" tool result. */
   reason?: string;
 }
 
@@ -90,7 +90,7 @@ function readEditItems(args: Record<string, unknown>): EditItemLike[] | null {
 }
 
 /**
- * isHunkSelectable — true iff this is a multi-edit `edit` tool call. Single-edit
+ * isHunkSelectable, true iff this is a multi-edit `edit` tool call. Single-edit
  * `edit` calls, `write` calls, and everything else keep the exact current
  * y/a/n flow untouched (zero behavior change for the common case).
  */
@@ -100,7 +100,7 @@ export function isHunkSelectable(request: PermissionPromptRequest): boolean {
   return items !== null && items.length > 1;
 }
 
-/** Builds initial hunk-selection state — all hunks selected by default (matches today's "y = approve everything" expectation as the zero-navigation path). */
+/** Builds initial hunk-selection state, all hunks selected by default (matches today's "y = approve everything" expectation as the zero-navigation path). */
 export function buildHunkSelectionState(request: PermissionPromptRequest): HunkSelectionState {
   const hunks = readEditItems(request.args) ?? [];
   return {
@@ -111,7 +111,7 @@ export function buildHunkSelectionState(request: PermissionPromptRequest): HunkS
 }
 
 /**
- * applyHunkKey — pure reducer over raw stdin `data` for an active hunk-selection
+ * applyHunkKey, pure reducer over raw stdin `data` for an active hunk-selection
  * prompt. Mirrors the outer y/a/n prompt's raw-data key routing (not the
  * normalized panel key vocabulary) since Space must be distinguishable from
  * the trimmed/lowercased `key` the outer switch uses.
@@ -156,7 +156,7 @@ export function applyHunkKey(state: HunkSelectionState, data: string): HunkKeyRe
 }
 
 /**
- * buildModifiedEditArgs — returns request.args with `edits` filtered to exactly
+ * buildModifiedEditArgs, returns request.args with `edits` filtered to exactly
  * the selected hunks (in original order), preserving every other EditInput
  * field (match/transaction/output/dry_run/validate) untouched.
  */
@@ -178,7 +178,7 @@ export interface ApprovalRequesterLookup {
 }
 
 /**
- * Human label for a `mcp-server` or `sandbox-escalation` attribution — the two
+ * Human label for a `mcp-server` or `sandbox-escalation` attribution, the two
  * non-agent origins the approval broker can name (see PermissionAttribution in
  * the SDK). `background-agent` deliberately falls through to the
  * broker-metadata lookup below instead, which resolves a richer label
@@ -206,7 +206,7 @@ function describeNonAgentAttribution(attribution: PermissionAttribution): string
  * for a request exists by the time its local prompt is shown), preferring an
  * explicit requester recorded in the broker record's metadata (agentId /
  * agent / requestedBy / actor / actorSurface), then the owning session id.
- * Returns null when nothing identifying is available — the prompt then omits
+ * Returns null when nothing identifying is available, the prompt then omits
  * the attribution line rather than guessing a name.
  */
 export function resolveApprovalRequester(
@@ -238,11 +238,11 @@ export function resolveApprovalRequester(
 }
 
 /**
- * buildPendingPermissionExtras — the `hunkState` + wrapped `resolve` fields
+ * buildPendingPermissionExtras, the `hunkState` + wrapped `resolve` fields
  * (plus the input-debounce timestamp and requester attribution) main.ts spreads
  * onto its PendingPermissionState alongside `...request`. Bundled into one
  * helper (rather than inlined in main.ts) to keep main.ts's net line count at
- * zero for this change — main.ts sits at the 800-line architecture cap and must
+ * zero for this change, main.ts sits at the 800-line architecture cap and must
  * never grow it.
  *
  * `openedAt` is the moment the prompt appeared; the blocking-input handler uses
@@ -264,7 +264,7 @@ export function buildPendingPermissionExtras(
   replyBuffer: string | undefined;
 } {
   // An exec-prompt ask (a running command waiting on stdin) opens straight in
-  // answer mode: every printable key types the answer — a run whose prompt
+  // answer mode: every printable key types the answer, a run whose prompt
   // needs a literal 'y' must never have it eaten as a card command key.
   const isExecPrompt = request.attribution?.kind === 'exec-prompt';
   return {

package/src/permissions/prompt.ts

@@ -66,7 +66,7 @@ function collectField(arr: unknown, field: string): string[] {
 }
 
 /**
- * The real display target(s) of a tool invocation — the paths/commands/urls a
+ * The real display target(s) of a tool invocation, the paths/commands/urls a
  * user needs to see, extracted from the actual arg shapes so a nested
  * `{files:[{path}]}` no longer falls through to a raw JSON blob. (2a.)
  * Returns [] when nothing recognisable is present (caller falls back).
@@ -103,17 +103,17 @@ function categoryVerb(category: PermissionCategory): string {
 /**
  * Single source of truth for how many Line rows the hunk-list section
  * occupies: 1 header row + up to MAX_VISIBLE_HUNKS checkbox rows + 1 trailer
- * row (rendered as "+N more" when truncated, blank otherwise — always
+ * row (rendered as "+N more" when truncated, blank otherwise, always
  * present so the row count never depends on which branch fires). Both
  * getPromptHeight and createPromptLines call this SAME function, so they
- * cannot drift apart (Risk 2 — main.ts's render loop reserves viewport
+ * cannot drift apart (Risk 2, main.ts's render loop reserves viewport
  * space from getPromptHeight *before* the real render happens).
  */
 /**
  * The optional sandbox model-judgment tier (see sandbox-judgment.ts in the
- * SDK) annotates an escalation ask by pushing one string — verbatim
+ * SDK) annotates an escalation ask by pushing one string, verbatim
  * "model judgment: looks safe because…" / "model judgment: flags risk
- * because…" — onto `analysis.reasons`, alongside the sandbox-boundary and
+ * because…", onto `analysis.reasons`, alongside the sandbox-boundary and
  * policy reasons. Pulled out here so it gets its own clearly-labeled row
  * instead of blending into the generic Review bullets, where the truncation
  * to 2 reasons could silently cut it (it is typically the LAST reason
@@ -162,7 +162,7 @@ export class PermissionPromptUI {
     return targets.length > 0 ? targets : [getDisplayArg(request.tool, request.args)];
   }
 
-  /** Path-field row texts — one per target when few, a "N files:" summary when many. */
+  /** Path-field row texts, one per target when few, a "N files:" summary when many. */
   private static pathRowTexts(targets: string[], maxLen: number): string[] {
     const clamp = (s: string): string => (s.length > maxLen ? `...${s.slice(-(maxLen - 3))}` : s);
     if (targets.length <= 1) return [clamp(targets[0] ?? '(unknown)')];
@@ -183,11 +183,11 @@ export class PermissionPromptUI {
   ): boolean {
     if (hunkState || detailsExpanded) return false;
     // Shell execution, delegation and network requests always show the full
-    // card — their action semantics (command, side effects, host, checklist)
+    // card, their action semantics (command, side effects, host, checklist)
     // warrant scrutiny even when the risk model rates them low. Only mundane
     // low-risk filesystem reads/writes condense. (2b.)
     if (request.category === 'execute' || request.category === 'delegate') return false;
-    // Remember tiers are one-key choices that must be visible to be usable —
+    // Remember tiers are one-key choices that must be visible to be usable,
     // a request carrying rememberOptions always shows the full card.
     if (request.rememberOptions && request.rememberOptions.length > 0) return false;
     const analysis = this.fallbackAnalysis(request);
@@ -238,13 +238,13 @@ export class PermissionPromptUI {
     const clamp = (s: string): string => (s.length > width ? `${s.slice(0, Math.max(0, width - 3))}...` : s);
     return options.map((option, index) => {
       const labelCol = index === 0 ? 'Remember ' : ' '.repeat(9);
-      return clamp(`   ${labelCol}: [${index + 1}] ${option.label} — ${option.detail}`);
+      return clamp(`   ${labelCol}: [${index + 1}] ${option.label}; ${option.detail}`);
     });
   }
 
   /**
    * The FULL command of an execute ask, wrapped across as many rows as it
-   * needs — never truncated. Empty for non-execute asks and for asks without
+   * needs, never truncated. Empty for non-execute asks and for asks without
    * a string command. Shared by getPromptHeight and createPromptLines.
    */
   private static commandRowTexts(request: PermissionPromptRequest, width: number): string[] {
@@ -340,7 +340,7 @@ export class PermissionPromptUI {
 
   /**
    * Assemble the card's view state from the pending-permission slot and the
-   * broker's live queue (the honest count of OTHER pending asks — coalesced
+   * broker's live queue (the honest count of OTHER pending asks, coalesced
    * asks share one record, so they are never double-counted). One helper so
    * main.ts passes identical state to getPromptHeight and createPromptLines.
    */
@@ -372,7 +372,7 @@ export class PermissionPromptUI {
     const attributionLines = requestedBy ? 1 : 0;
     const rememberLines = this.rememberRowTexts(request, hunkState, width).length;
     // Condensed low-risk card: top separator, title, [attribution], [preview],
-    // summary, choices, bottom separator — see createPromptLines' condensed branch.
+    // summary, choices, bottom separator, see createPromptLines' condensed branch.
     if (this.isCondensed(request, hunkState, detailsExpanded)) return 5 + attributionLines + rememberLines;
     const analysis = this.fallbackAnalysis(request);
     const { annotation: judgmentAnnotation, rest: reasonsMinusJudgment } = extractModelJudgmentAnnotation(analysis.reasons);
@@ -445,7 +445,7 @@ export class PermissionPromptUI {
     // Honest queue: how many OTHER broker asks are waiting behind this one.
     // They surface in turn as each is answered; the count keeps that visible.
     const queueSuffix = view?.queueCount && view.queueCount > 0
-      ? ` — ${view.queueCount} more waiting`
+      ? `: ${view.queueCount} more waiting`
       : '';
 
     // Attribution line (which agent/process is asking) and the remember block
@@ -506,14 +506,14 @@ export class PermissionPromptUI {
       lines.push(UIFactory.stringToLine(`   ${labelCol}: ${rowText}`.padEnd(width), width, { fg: TEXT }));
     });
 
-    // The FULL command of an execute ask, wrapped — never truncated. The Path
+    // The FULL command of an execute ask, wrapped, never truncated. The Path
     // row above stays as the one-line subject; this block is the whole truth.
     for (const rowText of this.commandRowTexts(request, width)) {
       lines.push(UIFactory.stringToLine(rowText.padEnd(width), width, { fg: TEXT }));
     }
 
     // Exec-prompt attribution: the running command and the terminal prompt it
-    // is stuck on, wrapped in full — the typed answer feeds this run's stdin.
+    // is stuck on, wrapped in full, the typed answer feeds this run's stdin.
     for (const rowText of this.execPromptRowTexts(request, width)) {
       lines.push(UIFactory.stringToLine(rowText.padEnd(width), width, { fg: WARN }));
     }
@@ -541,7 +541,7 @@ export class PermissionPromptUI {
     // Sandbox escalation row: when the sandbox-aware exec gate turned an
     // auto-allow into an ask because the boundary-safe command still needs host
     // access, name what it wants ("wants network …"). The escalation text is the
-    // SDK policy's, verbatim — this row only surfaces it.
+    // SDK policy's, verbatim, this row only surfaces it.
     const sandboxAnnotation = readSandboxAskAnnotation(request);
     if (sandboxAnnotation && sandboxAnnotation.sandboxEscalations.length > 0) {
       const escalations = sandboxAnnotation.sandboxEscalations.join('; ');
@@ -572,8 +572,8 @@ export class PermissionPromptUI {
 
     // Model-judgment annotation: gets its own clearly-labeled row (never
     // subject to the Review truncation below) so a `sandbox-model-judgment`
-    // verdict — "model judgment: looks safe because…" / "flags risk because…"
-    // — is never silently cut. See extractModelJudgmentAnnotation.
+    // verdict, "model judgment: looks safe because…" / "flags risk because…"
+    //, is never silently cut. See extractModelJudgmentAnnotation.
     const { annotation: judgmentAnnotation, rest: reasonsMinusJudgment } = extractModelJudgmentAnnotation(analysis.reasons);
     if (judgmentAnnotation) {
       const maxJudgmentLen = Math.max(10, width - 16);
@@ -598,7 +598,7 @@ export class PermissionPromptUI {
     const checklistLine = `   Checklist : ${truncatedChecklist}`;
     lines.push(UIFactory.stringToLine(checklistLine.padEnd(width), width, { fg: DIM }));
 
-    // Raw args row — the full tool arguments live here in the details view so
+    // Raw args row, the full tool arguments live here in the details view so
     // the Path field above can render clean path(s), never a JSON blob. (2a.)
     const rawArgs = JSON.stringify(args);
     const maxRawLen = Math.max(10, width - 16);
@@ -609,14 +609,14 @@ export class PermissionPromptUI {
     lines.push(UIFactory.stringToLine(' '.repeat(width), width));
 
     // Real colored diff for a write/edit ask (adds green, removals red, hunk
-    // headers blue — the same diff-view machinery the transcript uses).
+    // headers blue, the same diff-view machinery the transcript uses).
     const diffTextLines = this.writeDiffLines(request, hunkState);
     if (diffTextLines) {
       lines.push(...renderDiffView(diffTextLines.join('\n'), width));
     }
 
     if (hunkState) {
-      // Hunk list — see hunkListRowCount() for the row-count contract this
+      // Hunk list, see hunkListRowCount() for the row-count contract this
       // block must match exactly (Risk 2: getPromptHeight/createPromptLines
       // parity is what keeps main.ts's render loop from clipping the
       // viewport).
@@ -631,7 +631,7 @@ export class PermissionPromptUI {
         const box = selected.has(i) ? '[x]' : '[ ]';
         const findPreview = hunk.find.replace(/\n/g, '⏎').slice(0, maxPreviewLen);
         const replacePreview = hunk.replace.replace(/\n/g, '⏎').slice(0, maxPreviewLen);
-        const rowText = `   ${box} ${i + 1}. ${hunk.path} — "${findPreview}" -> "${replacePreview}"`;
+        const rowText = `   ${box} ${i + 1}. ${hunk.path}: "${findPreview}" -> "${replacePreview}"`;
         const isCursor = i === cursor;
         lines.push(UIFactory.stringToLine(
           rowText.padEnd(width),

package/src/permissions/sandbox-exec-gate.ts

@@ -1,16 +1,16 @@
 /**
- * sandbox-exec-gate.ts — sandbox-aware layer over the exec approval ask.
+ * sandbox-exec-gate.ts, sandbox-aware layer over the exec approval ask.
  *
  * The per-command exec sandbox already RUNS boundary-safe commands inside a
  * bubblewrap boundary (the SDK exec tool's runner half). This is the APPROVAL
  * half: when the base permission policy would prompt ("ask") for an exec, and
  * the sandbox is genuinely active, a command that runs entirely inside the OS
- * boundary with no host-access need should auto-allow instead of prompting —
+ * boundary with no host-access need should auto-allow instead of prompting,
  * and a command that still needs host access should surface as an explicit ask
  * that NAMES what it wants ("wants network …", "wants host privilege
  * escalation").
  *
- * The decision is the SDK's `decideSandboxedExec` — never re-implemented here.
+ * The decision is the SDK's `decideSandboxedExec`, never re-implemented here.
  * This module only (a) reads the live sandbox posture, (b) extracts the exec
  * command(s) from the request, (c) maps the SDK decision onto the existing ask
  * callback: allow → approve without prompting; ask → attach the named
@@ -20,7 +20,7 @@
  *
  * This runs INSIDE the permission machinery's ask layer (like trustGatedAsk), so
  * it composes with the real layer chain and is only ever consulted for execs the
- * base policy already resolved to "ask" — it can never turn a deny into an allow,
+ * base policy already resolved to "ask", it can never turn a deny into an allow,
  * and the frozen catastrophic block is untouched.
  */
 import { decideSandboxedExec } from '@pellux/goodvibes-sdk/platform/runtime/permissions/sandbox-policy';
@@ -57,7 +57,7 @@ export interface SandboxExecAskDeps {
   readonly readEgressAllowlist: () => readonly string[];
   /**
    * Honest host availability of the exec sandbox backend. Probing the host spawns
-   * bwrap, so the caller passes a memoized probe — invoked at most once, and only
+   * bwrap, so the caller passes a memoized probe, invoked at most once, and only
    * when an exec ask actually arrives while the feature + config are on.
    */
   readonly detectAvailability: () => SandboxAvailability;

package/src/providers/provider-classification.ts

@@ -1,5 +1,5 @@
 /**
- * provider-classification.ts — how a provider is paid for: a raw API key, a
+ * provider-classification.ts, how a provider is paid for: a raw API key, a
  * cloud account, a stored subscription/OAuth session, a local runtime, or
  * honestly unknown.
  *

package/src/providers/reasoning-effort-surface.ts

@@ -1,5 +1,5 @@
 /**
- * reasoning-effort-surface.ts — the TUI's single reading of the SDK's
+ * reasoning-effort-surface.ts, the TUI's single reading of the SDK's
  * per-model reasoning-effort spec.
  *
  * Every effort-shaped surface (the `/effort` command, the model picker's
@@ -12,12 +12,12 @@
  * The honest presentation differs per spec kind, so the wording is generated
  * here rather than templated at each call site:
  *
- *   - `effort`        — the model names its levels; offer exactly those.
- *   - `budget_tokens` — the model takes a thinking-token budget, so each level
+ *   - `effort`       , the model names its levels; offer exactly those.
+ *   - `budget_tokens`, the model takes a thinking-token budget, so each level
  *                       is shown with the budget it sends.
- *   - `toggle`        — reasoning is on or off only; say so, and do not imply
+ *   - `toggle`       , reasoning is on or off only; say so, and do not imply
  *                       that the levels in between mean anything.
- *   - `unavailable`   — nothing is configurable; the picker says that instead
+ *   - `unavailable`  , nothing is configurable; the picker says that instead
  *                       of presenting an empty list.
  *
  * A `fallback`-sourced spec is a labelled guess: neither the live catalog nor
@@ -176,7 +176,7 @@ export function effortPresentationForModel(model: EffortModelLike): EffortPresen
       headline = `${name} takes a thinking-token budget; each level below sends the budget shown.`;
       break;
     case 'toggle':
-      headline = `${name} only exposes reasoning on or off — there is no depth to choose.`;
+      headline = `${name} only exposes reasoning on or off; there is no depth to choose.`;
       break;
     case 'unavailable':
       headline = `${name} has no configurable reasoning level; it runs at its own fixed depth.`;
@@ -212,7 +212,7 @@ export function describeEffortForModel(model: EffortModelLike, current: string |
   }
 
   if (resolved.value === undefined) {
-    lines.push(`  Sent on the wire: nothing — ${model.displayName ?? model.id} runs at its own default.`);
+    lines.push(`  Sent on the wire: nothing; ${model.displayName ?? model.id} runs at its own default.`);
   } else if (spec.kind === 'budget_tokens') {
     lines.push(`  Sent on the wire: ${wire} = ${budgetTokensForLevel(resolved.value, spec).toLocaleString()}`);
   } else {
@@ -256,16 +256,16 @@ export function describeConfiguredEffort(registryKey: string, configured: string
   const resolved = resolveEffortForModelSurface(configured === '' ? undefined : configured, model);
   const wire = describeReasoningWire(spec, providerId);
 
-  if (spec.kind === 'unavailable') return `not sent — ${modelId} has no configurable reasoning level`;
+  if (spec.kind === 'unavailable') return `not sent: ${modelId} has no configurable reasoning level`;
   if (spec.source === 'fallback') {
-    return `${resolved.value ?? '(model default)'} — unverified: ${modelId} is not in the model catalog, so some providers send nothing for it`;
+    return `${resolved.value ?? '(model default)'}: unverified: ${modelId} is not in the model catalog, so some providers send nothing for it`;
   }
-  if (resolved.value === undefined) return `not sent — ${modelId} applies its own default`;
+  if (resolved.value === undefined) return `not sent: ${modelId} applies its own default`;
   if (spec.kind === 'budget_tokens') {
     return `${resolved.value} (${wire} = ${budgetTokensForLevel(resolved.value, spec).toLocaleString()})`;
   }
   if (resolved.value !== configured && configured !== '') {
-    return `${resolved.value} (${wire}) — '${configured}' is not available on ${modelId}`;
+    return `${resolved.value} (${wire}): '${configured}' is not available on ${modelId}`;
   }
   return `${resolved.value} (${wire})`;
 }
@@ -273,7 +273,7 @@ export function describeConfiguredEffort(registryKey: string, configured: string
 /**
  * Re-resolve a configured level against a model that is about to serve, for
  * the model-switch and failover paths. Returns the level to use and, when it
- * had to change, the SDK's own sentence explaining why — printed verbatim so
+ * had to change, the SDK's own sentence explaining why, printed verbatim so
  * the wording cannot drift from the resolution that produced it.
  */
 export function remapEffortForServingModel(

package/src/renderer/ansi-sanitize.ts

@@ -3,13 +3,13 @@
  *
  * The TUI grid renders content character-by-character via writeStyledText,
  * which already drops zero-width characters (including ESC \x1b) by checking
- * display width. However, that is incidental protection — not a contract.
+ * display width. However, that is incidental protection, not a contract.
  * This module provides explicit, intentional sanitization.
  *
  * Strategy:
  * - STRIP all non-SGR escape sequences (cursor moves, OSC, BEL, alt-screen,
  *   DECSET/private mode, and any other CSI/ESC sequences).
- * - PRESERVE SGR color/style codes (\x1b[<params>m) — used legitimately by
+ * - PRESERVE SGR color/style codes (\x1b[<params>m), used legitimately by
  *   the TUI's own colorized output paths.
  * - STRIP bare BEL (\x07) characters.
  *
@@ -46,11 +46,10 @@ const BEL = /\x07/g;
  * @returns Sanitized string safe for grid rendering
  */
 export function stripDangerousAnsi(input: string): string {
-  // Step 1: Extract and preserve SGR sequences by replacing them with placeholders,
-  // then strip all other escape sequences, then restore SGR sequences.
-  // This approach avoids complex negative lookahead regexes.
+  // SGR sequences are extracted to placeholders before the other escape
+  // sequences are stripped, then restored, to avoid complex negative
+  // lookahead regexes.
 
-  // Collect SGR sequences and replace with unique markers
   const sgrTokens: string[] = [];
   const withPlaceholders = input.replace(SGR_PATTERN, (match) => {
     const idx = sgrTokens.length;

package/src/renderer/autocomplete-overlay.ts

@@ -33,7 +33,7 @@ function putText(line: Line, startX: number, maxWidth: number, text: string, sty
  *
  * A row's description renders inline only when it genuinely fits beside the
  * command name; otherwise the FULL description wraps onto its own line(s)
- * below the command name, with no line cap — descriptive text is never
+ * below the command name, with no line cap, descriptive text is never
  * clipped (same fix as selection-modal-overlay.ts's modal rule). Item
  * visibility is row-budget aware (a wrapped description can cost more than
  * one physical row), always showing the selected item in full and falling
@@ -55,7 +55,7 @@ export function renderAutocompleteOverlay(
     chromeRows,
     minContentRows: 6,
     // Rows grow with wrapped descriptions (never clipped) rather than
-    // staying pinned at a small constant — still bounded by the viewport.
+    // staying pinned at a small constant, still bounded by the viewport.
     maxContentRows: Math.max(10, viewportHeight - chromeRows - 4),
   });
   const layout = createOverlayBoxLayout(width, metrics.margin, metrics.boxWidth);
@@ -90,7 +90,7 @@ export function renderAutocompleteOverlay(
 
   // palette curation (item 4): on a bare '/' (query === ''), the results
   // list is "common tier" (score 2) followed by "alphabetical rest" (score
-  // 1) — see CommandRegistry.fuzzyMatch. commonCount marks that boundary;
+  // 1), see CommandRegistry.fuzzyMatch. commonCount marks that boundary;
   // a one-row separator draws there when it falls inside the visible window.
   const hasCommonSeparator = state.query === '' && state.commonCount > 0 && state.commonCount < total;
 
@@ -187,7 +187,7 @@ export function renderAutocompleteOverlay(
       });
       lines.push(line);
     } else {
-      // Doesn't fit beside the command name — wrap the FULL description onto
+      // Doesn't fit beside the command name, wrap the FULL description onto
       // its own line(s) below at the full row width, rather than clipping it.
       lines.push(line);
       for (const wrapped of wrapWithHangingIndent(command.description, wrapWidth, '')) {
@@ -216,7 +216,7 @@ export function renderAutocompleteOverlay(
 
   const footerLine = createOverlayContentLine(width, layout);
   // vocab unification: "Run"/"Close" match the /help selection modal's
-  // hint bar (selection-modal-overlay.ts) — both surfaces execute a command
+  // hint bar (selection-modal-overlay.ts), both surfaces execute a command
   // on Enter, so they now say so the same way.
   const hints = '[Tab] Complete  [Up/Down] Navigate  [Enter] Run  [Esc] Close';
   putText(

package/src/renderer/block-actions-overlay.ts

@@ -1,5 +1,5 @@
 /**
- * renderBlockActionsMenu — renders the BlockActionsMenu (src/renderer/block-actions.ts)
+ * renderBlockActionsMenu, renders the BlockActionsMenu (src/renderer/block-actions.ts)
  * as a docked overlay, so opening it via Enter-on-an-empty-composer actually
  * shows something. Follows the established docked-overlay pattern (see
  * selection-modal-overlay.ts / bookmark-modal.ts): ModalFactory sizes the box

package/src/renderer/bookmark-modal.ts

@@ -1,5 +1,5 @@
 /**
- * renderBookmarkModal — renders the /bookmarks modal as Line[] using ModalFactory.
+ * renderBookmarkModal, renders the /bookmarks modal as Line[] using ModalFactory.
  *
  * Shows a list of bookmarked blocks with:
  *   - label (block type + excerpt)

package/src/renderer/code-block.ts

@@ -14,7 +14,7 @@ import { UI_TONES } from './ui-primitives.ts';
  * tree-sitter parse doesn't visibly shift color mid-stream.
  * `accent` and `bg` are chrome (the language-label header bar and the body
  * background), not syntax tokens, and keep their original VS Code Dark+
- * values — folded here from two separate literals (one in the header, one
+ * values, folded here from two separate literals (one in the header, one
  * duplicated on the footer line) into a single named source.
  */
 const FALLBACK_THEME = {
@@ -389,7 +389,7 @@ export function renderCodeBlock(
         }
         line[cx] = createStyledCell(ch, { fg: token.fg, bg: BG, bold: token.bold, italic: token.italic });
         // Bound the wide-glyph placeholder against the body's own right edge
-        // (effectiveWidth), not the full line width — otherwise a 2-column
+        // (effectiveWidth), not the full line width, otherwise a 2-column
         // glyph landing on the last body column spills its placeholder cell
         // into the reserved right-margin band the header/footer stop at.
         if (cw === 2 && cx + 1 < effectiveWidth) line[cx + 1] = { ...line[cx], char: '' };