@pellux/goodvibes-tui 1.13.1 → 1.14.0

package/src/runtime/workstream-draft-edits.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// workstream-draft-edits.ts — pure item edits for a not-yet-launched proposal
+//
+// The plan-review gate (see /workstream, input/commands/workstream-runtime.ts)
+// lets a human reshape a decomposed proposal BEFORE anything is spent: rewrite
+// one item's brief, drop an item, or reorder items. These are pure functions
+// over the launchable CreateWorkstreamInput (@pellux/goodvibes-sdk/platform/
+// orchestration) — no engine calls, no I/O — so the same spec that is edited
+// here is byte-for-byte what launch hands createWorkstream. Extracted from
+// workstream-services.ts to keep that construction module lean (its own
+// header explains the 800-line-cap discipline) and to give the edits a clean
+// unit-test target.
+//
+// HONEST SCOPE (stated so the review surface never overstates what an edit
+// does):
+//   - editItemBrief rewrites an item's `task` (the instructions its agent
+//     runs), never its `title` (the short label). The engineer/review phase
+//     template is unchanged — a brief is WHAT the item does, not HOW the
+//     pipeline runs it.
+//   - removeItem also strips the removed item's id from every other item's
+//     `dependsOn`, so the spec never carries a dangling dependency into
+//     fromPlanProposal's assembly (which would otherwise reject it). It
+//     refuses to remove the last item — a workstream needs at least one.
+//   - moveItem reorders the AUTHORING order (the ordinals shown in the review
+//     and the tie-break when the engine has a free capacity slot and several
+//     claimable items). It never rewrites dependencies, so it cannot create a
+//     cycle; the engine still schedules strictly by dependency + capacity, not
+//     by array position. Reordering is a presentation/authoring act, not a
+//     scheduling override — and is documented as such where it is offered.
+// ---------------------------------------------------------------------------
+
+import type { CreateWorkstreamInput, WorkItemSpec } from '@pellux/goodvibes-sdk/platform/orchestration';
+
+/** Success carries the rewritten spec; failure carries an honest, user-facing reason. */
+export type DraftEditResult = { readonly spec: CreateWorkstreamInput } | { readonly error: string };
+
+/**
+ * Resolve a user-typed item reference to a 0-based index. A reference is
+ * either the 1-based ordinal shown in the proposal (the primary handle) or an
+ * item id / unique id-prefix (the stable handle that survives reordering). An
+ * ambiguous or unmatched reference resolves to undefined so the caller can
+ * refuse honestly rather than editing the wrong item.
+ */
+export function resolveItemIndex(items: readonly WorkItemSpec[], ref: string): number | undefined {
+  const trimmed = ref.trim();
+  const ordinal = Number(trimmed);
+  if (Number.isInteger(ordinal) && ordinal >= 1 && ordinal <= items.length) return ordinal - 1;
+  const matches = items
+    .map((item, index) => ({ item, index }))
+    .filter(({ item }) => item.id !== undefined && item.id.startsWith(trimmed));
+  return matches.length === 1 ? matches[0]!.index : undefined;
+}
+
+function unresolvedError(items: readonly WorkItemSpec[], ref: string): string {
+  return `No draft item matches "${ref}". Use a number from 1 to ${items.length}, or an item id.`;
+}
+
+/** Rewrite one item's brief (its `task`). Empty/whitespace briefs are refused. */
+export function editItemBrief(spec: CreateWorkstreamInput, ref: string, brief: string): DraftEditResult {
+  const index = resolveItemIndex(spec.items, ref);
+  if (index === undefined) return { error: unresolvedError(spec.items, ref) };
+  const trimmed = brief.trim();
+  if (!trimmed) return { error: 'A new brief cannot be empty.' };
+  const items = spec.items.map((item, i) => (i === index ? { ...item, task: trimmed } : item));
+  return { spec: { ...spec, items } };
+}
+
+/** Drop one item and strip its id from every sibling's dependsOn. Refuses to empty the plan. */
+export function removeItemFromSpec(spec: CreateWorkstreamInput, ref: string): DraftEditResult {
+  const index = resolveItemIndex(spec.items, ref);
+  if (index === undefined) return { error: unresolvedError(spec.items, ref) };
+  if (spec.items.length <= 1) return { error: 'Cannot remove the last item — a workstream needs at least one.' };
+  const removedId = spec.items[index]!.id;
+  const items = spec.items
+    .filter((_, i) => i !== index)
+    .map((item) =>
+      removedId && item.dependsOn?.includes(removedId)
+        ? { ...item, dependsOn: item.dependsOn.filter((dep) => dep !== removedId) }
+        : item,
+    );
+  return { spec: { ...spec, items } };
+}
+
+/** Reorder one item to a new 1-based authoring position. Never touches dependencies. */
+export function moveItemInSpec(spec: CreateWorkstreamInput, ref: string, toPosition: number): DraftEditResult {
+  const index = resolveItemIndex(spec.items, ref);
+  if (index === undefined) return { error: unresolvedError(spec.items, ref) };
+  if (!Number.isInteger(toPosition) || toPosition < 1 || toPosition > spec.items.length) {
+    return { error: `Position must be a whole number from 1 to ${spec.items.length}.` };
+  }
+  const items = [...spec.items];
+  const [moved] = items.splice(index, 1);
+  items.splice(toPosition - 1, 0, moved!);
+  return { spec: { ...spec, items } };
+}

package/src/runtime/workstream-draft-store.ts

@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------------
+// workstream-draft-store.ts — durable journal for not-yet-launched proposals
+//
+// A /workstream proposal (WorkstreamDraft, workstream-services.ts) is TUI-owned
+// state the OrchestrationEngine has no concept of — its only creation entry
+// point materializes a real, ticking workstream with no pre-launch "draft"
+// stage (see that module's REALITY-WINS header). Earlier waves therefore held
+// drafts in memory only, and a restart between create and launch silently lost
+// them. This store journals each draft to disk so the plan-review gate survives
+// a restart and is resumable: the same reshaped, approved proposal is still
+// there to launch afterward.
+//
+// This is TUI-side persistence, NOT an engine feature — it sits ALONGSIDE the
+// engine's own .goodvibes/orchestration/<id>.json workstream snapshots, under a
+// drafts/ subdirectory, and is loaded by the command facade at construction the
+// same way the engine's resumeAllFromDisk() reloads live workstreams. A draft
+// is a pure-data object (id/task/spec/gate/proposal/provenance/approved), so a
+// plain JSON round-trip is lossless.
+//
+// Every operation is guarded and NEVER throws: a missing directory, an
+// unreadable or malformed file, or a write failure degrades to "that draft
+// isn't there" rather than crashing session startup — mirroring the engine
+// persistence layer's own quarantine-don't-propagate discipline.
+// ---------------------------------------------------------------------------
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { WorkstreamDraft } from './workstream-draft-types.ts';
+
+export interface WorkstreamDraftStore {
+  /** Every valid draft on disk, oldest first. A directory that doesn't exist yet ⇒ []. Malformed files are skipped, never fatal. */
+  loadAll(): WorkstreamDraft[];
+  /** Write (or overwrite) one draft's snapshot. Silently no-ops on any I/O failure — a lost journal write must never break the in-memory flow. */
+  save(draft: WorkstreamDraft): void;
+  /** Delete one draft's snapshot (on launch or cancel). Missing file ⇒ no-op. */
+  remove(id: string): void;
+}
+
+/** Draft ids are `wsd_<hex>`; this refuses anything else so a crafted id can never escape the drafts directory. */
+function isSafeId(id: string): boolean {
+  return /^[A-Za-z0-9_-]{1,64}$/.test(id);
+}
+
+function isDraftShape(value: unknown): value is WorkstreamDraft {
+  if (typeof value !== 'object' || value === null) return false;
+  const d = value as Record<string, unknown>;
+  return (
+    typeof d.id === 'string'
+    && typeof d.task === 'string'
+    && typeof d.approved === 'boolean'
+    && typeof d.createdAt === 'number'
+    && typeof d.spec === 'object' && d.spec !== null
+    && Array.isArray((d.spec as Record<string, unknown>).items)
+  );
+}
+
+export function createWorkstreamDraftStore(projectRoot: string): WorkstreamDraftStore {
+  const dir = join(projectRoot, '.goodvibes', 'orchestration', 'drafts');
+  const fileFor = (id: string): string => join(dir, `${id}.json`);
+
+  return {
+    loadAll(): WorkstreamDraft[] {
+      let entries: string[];
+      try {
+        entries = readdirSync(dir);
+      } catch {
+        return []; // directory not created yet, or unreadable — nothing to resume
+      }
+      const drafts: WorkstreamDraft[] = [];
+      for (const entry of entries) {
+        if (!entry.endsWith('.json')) continue;
+        try {
+          const parsed: unknown = JSON.parse(readFileSync(join(dir, entry), 'utf8'));
+          if (isDraftShape(parsed) && isSafeId(parsed.id)) drafts.push(parsed);
+        } catch {
+          // A malformed or half-written snapshot is skipped, never fatal.
+        }
+      }
+      return drafts.sort((a, b) => a.createdAt - b.createdAt);
+    },
+    save(draft: WorkstreamDraft): void {
+      if (!isSafeId(draft.id)) return;
+      try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(fileFor(draft.id), JSON.stringify(draft), 'utf8');
+      } catch {
+        // A failed journal write leaves the in-memory draft intact and usable;
+        // only its restart-durability is lost, which is strictly better than
+        // failing the edit the user just made.
+      }
+    },
+    remove(id: string): void {
+      if (!isSafeId(id)) return;
+      try {
+        rmSync(fileFor(id), { force: true });
+      } catch {
+        // Already gone, or unremovable — nothing more to do.
+      }
+    },
+  };
+}

package/src/runtime/workstream-draft-types.ts

@@ -0,0 +1,42 @@
+// ---------------------------------------------------------------------------
+// workstream-draft-types.ts — the not-yet-launched proposal's data shape
+//
+// Extracted from workstream-services.ts purely to give the durable draft store
+// (workstream-draft-store.ts) a type to persist WITHOUT importing back into the
+// service construction module — that back-edge would form an import cycle the
+// architecture check rejects. workstream-services.ts re-exports both types, so
+// every existing importer (the /workstream command, the tests) keeps importing
+// them from there unchanged.
+// ---------------------------------------------------------------------------
+
+import type { CreateWorkstreamInput } from '@pellux/goodvibes-sdk/platform/orchestration';
+import type { DecompositionGate, PlanProposal } from '@pellux/goodvibes-sdk/platform/core';
+
+/**
+ * Honest provenance for how a draft's decomposition was produced. Derived from
+ * the SDK decomposition service's outcome so the draft render can state plainly
+ * whether a planning agent decomposed the goal, or the heuristic path did (and
+ * if so, why).
+ */
+export interface WorkstreamDraftProvenance {
+  readonly kind: 'agent' | 'heuristic-configured' | 'gate-declined' | 'fallback';
+  readonly itemCount: number;
+  readonly agentCostUsd?: number | undefined;
+  readonly agentTokens?: number | undefined;
+  readonly elapsedMs?: number | undefined;
+  readonly fallbackReason?: string | undefined;
+}
+
+/** A not-yet-launched /workstream proposal. TUI-owned (the engine has no draft concept) and journaled to disk via workstream-draft-store.ts so it survives a restart. See workstream-services.ts's header doc. */
+export interface WorkstreamDraft {
+  readonly id: string;
+  task: string;
+  spec: CreateWorkstreamInput;
+  readonly gate: DecompositionGate;
+  /** The engine-agnostic decomposition proposal (model- or heuristic-produced). */
+  proposal: PlanProposal;
+  /** How that proposal came to be, for honest rendering. */
+  provenance: WorkstreamDraftProvenance;
+  approved: boolean;
+  readonly createdAt: number;
+}

package/src/runtime/workstream-services.ts

@@ -17,15 +17,20 @@
 // (input/commands/workstream-runtime.ts) needs a create -> propose -> approve
 // -> launch flow (Pillar-3 doctrine: render the plan in the transcript before
 // spending anything, mirroring /plan's approve step). REALITY-WINS DIVERGENCE
-// from the wo703 design brief: the brief recommended an "engine-owned/
-// journal-backed" draft so `/workstream status` could re-render a pending
-// proposal after a restart; the real engine (verified against the linked SDK
-// build) exposes no pre-creation draft concept at all, so WorkstreamDraft
-// below is process-lifetime-only state, owned by this module's facade
-// instance (constructed once, threaded onto CommandContext) — never a
-// module-level ambient global. A draft that existed only in memory is lost on
-// restart, same as an unsent chat draft; that is a real, stated limitation,
-// not a bug.
+// from the wo703 design brief: the brief recommended an ENGINE-owned draft; the
+// real engine (verified against the linked SDK build) exposes no pre-creation
+// draft concept at all, so WorkstreamDraft below is TUI-owned state, held on
+// this module's facade instance (constructed once, threaded onto
+// CommandContext) — never a module-level ambient global. Durability is
+// likewise TUI-owned: rather than leaving the brief's restart requirement
+// unmet, the facade journals every draft to disk through
+// workstream-draft-store.ts (a drafts/ subdirectory ALONGSIDE the engine's own
+// workstream snapshots) and reloads them at construction, so a create / reshape
+// / approve done before a restart is still here to launch afterward. The engine
+// gains no draft concept; the TUI persists its OWN facade state. A journal
+// write that fails degrades to in-memory-only for that one draft — never a
+// crash — and the store never resurrects a launched draft (its snapshot is
+// removed the moment the engine takes ownership).
 // ---------------------------------------------------------------------------
 
 import {
@@ -40,7 +45,6 @@ export type { OrchestrationEngine } from '@pellux/goodvibes-sdk/platform/orchest
 import {
   AdaptivePlanner,
   decomposeGoal,
-  type DecompositionGate,
   type DecompositionServiceConfig,
   type DecomposeGoalResult,
   type PlannerInputs,
@@ -51,6 +55,8 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { AgentManager } from '@pellux/goodvibes-sdk/platform/tools';
 import type { RuntimeEventBus } from '@/runtime/index.ts';
 import { calcSessionCost, isModelPriced } from '../export/cost-utils.ts';
+import { editItemBrief, moveItemInSpec, removeItemFromSpec } from './workstream-draft-edits.ts';
+import { createWorkstreamDraftStore } from './workstream-draft-store.ts';
 
 export interface WorkstreamServicesDeps {
   readonly agentManager: Pick<AgentManager, 'spawn' | 'getStatus' | 'cancel' | 'registerCancellationSignal' | 'releaseCancellationSignal'>;
@@ -60,34 +66,11 @@ export interface WorkstreamServicesDeps {
   readonly projectRoot: string;
 }
 
-/**
- * Honest provenance for how a draft's decomposition was produced. Derived from
- * the SDK decomposition service's outcome so the draft render can state plainly
- * whether a planning agent decomposed the goal, or the heuristic path did (and
- * if so, why).
- */
-export interface WorkstreamDraftProvenance {
-  readonly kind: 'agent' | 'heuristic-configured' | 'gate-declined' | 'fallback';
-  readonly itemCount: number;
-  readonly agentCostUsd?: number | undefined;
-  readonly agentTokens?: number | undefined;
-  readonly elapsedMs?: number | undefined;
-  readonly fallbackReason?: string | undefined;
-}
-
-/** A not-yet-launched /workstream proposal. See this file's header doc for why it lives here rather than on the engine. */
-export interface WorkstreamDraft {
-  readonly id: string;
-  task: string;
-  spec: CreateWorkstreamInput;
-  readonly gate: DecompositionGate;
-  /** The engine-agnostic decomposition proposal (model- or heuristic-produced). */
-  proposal: PlanProposal;
-  /** How that proposal came to be, for honest rendering. */
-  provenance: WorkstreamDraftProvenance;
-  approved: boolean;
-  readonly createdAt: number;
-}
+// WorkstreamDraft + WorkstreamDraftProvenance live in workstream-draft-types.ts
+// (so the durable store can persist them without an import cycle) and are
+// re-exported here so every existing importer keeps its import site unchanged.
+export type { WorkstreamDraft, WorkstreamDraftProvenance } from './workstream-draft-types.ts';
+import type { WorkstreamDraft, WorkstreamDraftProvenance } from './workstream-draft-types.ts';
 
 /** `ctx.session.workstreamEngine`'s real shape: the live engine plus the draft-proposal bookkeeping the engine itself has no concept of. */
 export interface WorkstreamCommandService {
@@ -98,6 +81,16 @@ export interface WorkstreamCommandService {
   listDrafts(): WorkstreamDraft[];
   /** Re-derive a held draft's spec + decomposition from a new task string. Clears any prior approval — an edit must be re-approved. `isolation` omitted ⇒ keeps the draft's current choice (an edit that only changes the task text must not silently reset isolation back to shared). */
   editDraft(id: string, task: string, isolation?: WorkstreamIsolation): Promise<WorkstreamDraft | undefined>;
+  /**
+   * Plan-review-gate item edits over a held draft's launchable spec (see
+   * workstream-draft-edits.ts). Each returns the updated draft on success,
+   * `{ error }` with an honest user-facing reason on a bad reference/argument,
+   * or `undefined` when no draft with that id is held. Every successful edit
+   * clears approval — a reshaped plan must be re-approved before launch.
+   */
+  editItem(id: string, itemRef: string, brief: string): WorkstreamDraft | { error: string } | undefined;
+  removeItem(id: string, itemRef: string): WorkstreamDraft | { error: string } | undefined;
+  moveItem(id: string, itemRef: string, toPosition: number): WorkstreamDraft | { error: string } | undefined;
   approveDraft(id: string): WorkstreamDraft | undefined;
   removeDraft(id: string): boolean;
   /** Materialize an approved draft into a real, running Workstream (engine.createWorkstream + start), then drop the draft. Null when the draft is missing or not approved. */
@@ -187,6 +180,13 @@ function createWorkstreamCommandService(
 ): WorkstreamCommandService {
   const drafts = new Map<string, WorkstreamDraft>();
 
+  // TUI-side draft journal (workstream-draft-store.ts). Load every persisted
+  // proposal at construction so a create/reshape/approve done before a restart
+  // is still here to launch afterward — the plan-review gate survives restart,
+  // exactly as the live-workstream snapshots do via resumeAllFromDisk().
+  const store = createWorkstreamDraftStore(projectRoot);
+  for (const persisted of store.loadAll()) drafts.set(persisted.id, persisted);
+
   /**
    * Run the SDK decomposition service: it spawns a bounded, read-only planning
    * agent (which surfaces in the fleet like any agent — kill/steer reach it,
@@ -238,6 +238,27 @@ function createWorkstreamCommandService(
     return fromChainSpec({ id: `item-${crypto.randomUUID().slice(0, 8)}`, task }, configManager);
   }
 
+  /**
+   * Apply a pure item edit (workstream-draft-edits.ts) to a held draft's spec.
+   * Threads the three outcomes straight through: `undefined` (no such draft) so
+   * the command layer can print its not-found message, `{ error }`
+   * (a bad reference/argument) verbatim, or the mutated draft. A successful edit
+   * clears approval — a reshaped plan must be re-approved before it can launch.
+   */
+  function applyItemEdit(
+    id: string,
+    edit: (spec: CreateWorkstreamInput) => import('./workstream-draft-edits.ts').DraftEditResult,
+  ): WorkstreamDraft | { error: string } | undefined {
+    const draft = drafts.get(id);
+    if (!draft) return undefined;
+    const result = edit(draft.spec);
+    if ('error' in result) return { error: result.error };
+    draft.spec = result.spec;
+    draft.approved = false;
+    store.save(draft);
+    return draft;
+  }
+
   return {
     engine,
     async proposeDraft(task: string, isolation?: WorkstreamIsolation): Promise<WorkstreamDraft> {
@@ -254,6 +275,7 @@ function createWorkstreamCommandService(
         createdAt: Date.now(),
       };
       drafts.set(draft.id, draft);
+      store.save(draft);
       return draft;
     },
     getDraft: (id) => drafts.get(id),
@@ -268,21 +290,30 @@ function createWorkstreamCommandService(
       draft.proposal = result.proposal;
       draft.provenance = toProvenance(result);
       draft.approved = false;
+      store.save(draft);
       return draft;
     },
+    editItem: (id, itemRef, brief) => applyItemEdit(id, (spec) => editItemBrief(spec, itemRef, brief)),
+    removeItem: (id, itemRef) => applyItemEdit(id, (spec) => removeItemFromSpec(spec, itemRef)),
+    moveItem: (id, itemRef, toPosition) => applyItemEdit(id, (spec) => moveItemInSpec(spec, itemRef, toPosition)),
     approveDraft(id) {
       const draft = drafts.get(id);
       if (!draft) return undefined;
       draft.approved = true;
+      store.save(draft); // approval must survive restart too — a resumed approved draft launches straight away
       return draft;
     },
-    removeDraft: (id) => drafts.delete(id),
+    removeDraft(id) {
+      store.remove(id);
+      return drafts.delete(id);
+    },
     launchDraft(id) {
       const draft = drafts.get(id);
       if (!draft || !draft.approved) return null;
       const workstream = engine.createWorkstream(draft.spec);
       engine.start(workstream.id);
       drafts.delete(id);
+      store.remove(id); // launched: the engine now owns it (its own journal), so drop the draft snapshot
       return { workstreamId: workstream.id };
     },
   };

package/src/shell/blocking-input.ts

@@ -12,8 +12,25 @@ export type PendingPermissionState = PermissionRequest & {
   hunkState?: HunkSelectionState;
   /** True once the user pressed `d` to expand a condensed low-risk card. (UX-B 2b.) */
   detailsExpanded?: boolean;
+  /**
+   * Epoch ms when the prompt first appeared. Keystrokes that arrive within
+   * APPROVAL_INPUT_DEBOUNCE_MS of this are swallowed (not interpreted as an
+   * approve/deny response) so text typed ahead — before the user saw the
+   * prompt — cannot accidentally answer it.
+   */
+  openedAt?: number;
+  /** Requester attribution ("session abc12345" / a named agent) shown on the prompt; absent when unknown. */
+  requestedBy?: string;
 };
 
+/**
+ * Settle window after a permission prompt appears during which buffered
+ * keystrokes are ignored rather than interpreted as the response. 350ms is long
+ * enough to absorb type-ahead from before the prompt rendered, short enough not
+ * to feel laggy to a user reacting to the prompt itself.
+ */
+export const APPROVAL_INPUT_DEBOUNCE_MS = 350;
+
 export type BlockingInputHandlerOptions = {
   data: string;
   pendingPermission: PendingPermissionState | null;
@@ -58,6 +75,8 @@ export type BlockingInputHandlerOptions = {
    * posture is not restored.
    */
   reopenPanels?: (snapshot: SessionSnapshot) => void;
+  /** Injectable clock for the approval-input debounce; defaults to Date.now(). Tests only. */
+  now?: number;
 };
 
 export type BlockingInputHandlerResult = {
@@ -89,6 +108,16 @@ export function handleBlockingShellInput(
   if (pendingPermission) {
     const req = pendingPermission;
 
+    // Input debounce: swallow any key that arrives within the settle window
+    // after the prompt appeared, so type-ahead text from before the user saw
+    // the prompt cannot answer it (neither approve, deny, nor navigate). The
+    // prompt stays open; re-render and consume the key.
+    const now = options.now ?? Date.now();
+    if (req.openedAt !== undefined && now - req.openedAt < APPROVAL_INPUT_DEBOUNCE_MS) {
+      render();
+      return { handled: true, pendingPermission, recoveryPending };
+    }
+
     if (req.hunkState) {
       const { state, commit } = applyHunkKey(req.hunkState, data);
       if (commit === 'apply') {

package/src/shell/ui-openers.ts

@@ -14,6 +14,7 @@ import type { MemoryEmbeddingProviderRegistry } from '@pellux/goodvibes-sdk/plat
 import type { ServiceInspectionQuery } from '../runtime/ui-service-queries.ts';
 import type { EmbeddingProviderPickerEntry, ModelPickerTargetInfo } from '../input/model-picker.ts';
 import type { SelectionItem } from '../input/selection-modal.ts';
+import { categorizeBuiltinCommands } from '../input/commands.ts';
 import { syncServiceSettingToPlatform } from './service-settings-sync.ts';
 import { setActiveThemeMode } from '../renderer/theme.ts';
 import { THEME_MODE_CONFIG_KEY, coerceThemeModeSetting } from '../renderer/theme-mode-config.ts';
@@ -41,6 +42,23 @@ type WireShellUiOpenersOptions = {
   render: () => void;
 };
 
+let commandCategoryMapCache: Map<string, string> | null = null;
+
+/**
+ * Map each built-in command name to its reference category, memoized. Drives
+ * the command palette's category grouping from the same single source of truth
+ * as the generated docs (categorizeBuiltinCommands), so the palette is always
+ * registry-derived and never a hand-maintained list.
+ */
+function getCommandCategoryMap(): Map<string, string> {
+  if (!commandCategoryMapCache) {
+    commandCategoryMapCache = new Map(
+      categorizeBuiltinCommands().map((entry) => [entry.command.name, entry.category]),
+    );
+  }
+  return commandCategoryMapCache;
+}
+
 /**
  * Derive the configuredVia tier for a provider.
  * Tier order mirrors SDK provider-routes.ts: env → secrets → subscription → undefined.
@@ -457,6 +475,53 @@ export function wireShellUiOpeners(options: WireShellUiOpenersOptions): void {
     render();
   };
 
+  commandContext.openCommandPalette = () => {
+    // The palette is built live from the command registry — never a hardcoded
+    // list — so it can never drift from the real command set. Category labels
+    // come from the same source the generated docs use (getCommandCategoryMap).
+    const registry = input.commandRegistry;
+    if (!registry) return;
+    const categoryByName = getCommandCategoryMap();
+    const items: SelectionItem[] = registry
+      .getAll()
+      .slice()
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((cmd) => {
+        const argsHint = cmd.argsHint ?? cmd.usage;
+        const detailParts: string[] = [];
+        if (cmd.description) detailParts.push(cmd.description);
+        if (argsHint) detailParts.push(`(args: ${argsHint})`);
+        if ((cmd.aliases ?? []).length > 0) detailParts.push(`[aka ${(cmd.aliases ?? []).map((a) => `/${a}`).join(', ')}]`);
+        return {
+          id: cmd.name,
+          label: `/${cmd.name}`,
+          detail: detailParts.join(' '),
+          category: categoryByName.get(cmd.name) ?? 'Other',
+          primaryAction: 'select' as const,
+        };
+      });
+    commandContext.openSelection?.(
+      'Command Palette',
+      items,
+      { allowSearch: true, primaryVerbLabel: 'Run' },
+      (result) => {
+        if (!result) return;
+        const cmd = registry.get(result.item.id);
+        if (!cmd) return;
+        // Pre-fill the composer with the command (and a trailing space so the
+        // inline args hint shows what the command wants). Keyboard-first: focus
+        // returns to the composer with command mode armed so the user fills any
+        // args and presses Enter — matching tab-completion's fill behavior.
+        input.prompt = `/${cmd.name} `;
+        input.cursorPos = input.prompt.length;
+        input.commandMode = true;
+        input.autocomplete?.reset();
+        commandContext.focusPrompt?.();
+        render();
+      },
+    );
+  };
+
   commandContext.focusPanels = () => {
     panelManager.focusPanels();
     render();

package/src/verification/verification-ledger.ts

@@ -27,6 +27,60 @@ export interface VerificationLedger {
   };
 }
 
+/**
+ * Baseline count of `Settings schema and persistence` items with real local
+ * behavior verification, as measured when this ledger was first authored. New
+ * schema keys added since then are accounted for explicitly (see
+ * FEATURE_KNOB_LOCAL_SETTINGS) rather than folded into this number, so the
+ * baseline stays an auditable fixed point.
+ */
+const SETTINGS_BEHAVIOR_BASELINE = 184;
+
+/**
+ * Config keys promoted into CONFIG_SCHEMA for the flag-gated feature knobs
+ * (SDK commit f5c4af31, "config: add schema keys for flag-gated feature
+ * knobs"). Adding these 28 keys raised the settings inventory `total` without a
+ * matching rise in behavior-verified coverage, which dropped
+ * `localBehaviorPercent` below its floor. Each key is a local, non-external
+ * setting whose full persistence behavior — schema default, set → write →
+ * reload round-trip, and reset-to-default — is exercised by
+ * `src/test/verification/feature-knob-settings-persistence.test.ts`. They are
+ * therefore genuinely behavior-verified locally and counted as such here.
+ */
+export const FEATURE_KNOB_LOCAL_SETTINGS = [
+  'provider.optimizerMode',
+  'provider.optimizerPinnedModel',
+  'permissions.divergenceThreshold',
+  'permissions.maxDivergenceRecords',
+  'tools.overflowSpillBackend',
+  'notifications.burstWindowMs',
+  'notifications.burstThreshold',
+  'notifications.burstCooldownMs',
+  'fetch.sanitizeMode',
+  'fetch.trustedHosts',
+  'fetch.blockedHosts',
+  'security.tokenAudit.rotationCadenceDays',
+  'security.tokenAudit.rotationWarningDays',
+  'security.tokenAudit.managed',
+  'integrations.delivery.maxRetries',
+  'integrations.delivery.initialDelayMs',
+  'integrations.delivery.maxDelayMs',
+  'integrations.delivery.maxDlqSize',
+  'integrations.delivery.sloEnforced',
+  'policy.bundleSource',
+  'policy.bundlePath',
+  'agents.passiveInjection.budgetTokens',
+  'agents.passiveInjection.relevanceFloor',
+  'agents.passiveInjection.codeLimit',
+  'agents.contextCompactThreshold',
+  'runtime.toolBudget.maxMs',
+  'runtime.toolBudget.maxTokens',
+  'runtime.toolBudget.maxCostUsd',
+] as const;
+
+/** Settings with real local behavior verification: the authored baseline plus the newly persistence-tested feature-knob keys. */
+const SETTINGS_BEHAVIOR_VERIFIED = SETTINGS_BEHAVIOR_BASELINE + FEATURE_KNOB_LOCAL_SETTINGS.length;
+
 const EXTERNAL_SLASH_COMMANDS = new Set([
   'auth',
   'bridge',
@@ -137,8 +191,8 @@ export function buildVerificationLedger(root: string): VerificationLedger {
       area: 'Settings schema and persistence',
       total: settings,
       localSignalVerified: settings,
-      localBehaviorVerified: 184,
-      externalOutcomeRequired: settings - 184,
+      localBehaviorVerified: SETTINGS_BEHAVIOR_VERIFIED,
+      externalOutcomeRequired: settings - SETTINGS_BEHAVIOR_VERIFIED,
       notes: 'Every schema setting can be validated for schema/default/load/write/location; external side effects remain separate.',
     },
     {

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '1.13.1';
+let _version = '1.14.0';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;