@pellux/goodvibes-tui 1.1.0 → 1.9.0

package/src/panels/panel-manager.ts

@@ -2,7 +2,12 @@
 // PanelManager — central manager for panel lifecycle, navigation, and split
 // ---------------------------------------------------------------------------
 
-import type { Panel, PanelRegistration, PanelCategory } from './types.ts';
+import type { Panel, PanelRegistration, PanelCategory, PanelDeepLinkTarget } from './types.ts';
+export type { PanelDeepLinkTarget } from './types.ts';
+// Type-only, erased at runtime, routed through the `@/` alias (not a relative
+// path) so it stays out of the relative-import graph the architecture
+// cycle-checker walks — same discipline as the PanelManager import in types.ts.
+import type { ConfigModalSurface } from '@/input/config-modal-types.ts';
 
 // ---------------------------------------------------------------------------
 // Pane
@@ -31,6 +36,29 @@ export class PanelManager {
   private retainedPanels = new Map<string, Panel>();
   /** Old/absorbed panel id -> merged target id (WO-1xx console merges). */
   private aliases = new Map<string, string>();
+  /**
+   * Retired panel id -> modal name (W6.1 purge, MIGRATE-TO-MODAL surfaces).
+   * Unlike `aliases` (panel -> panel), a hit here means no panel is ever
+   * constructed for this id — `open()` invokes `openModalCallback` instead
+   * and returns a sentinel. Registrations are added by WO-A/B; this map and
+   * the open()-time check are WO-C's mechanism only.
+   */
+  private modalRedirects = new Map<string, string>();
+  /**
+   * Modal name -> the surface the config-modal host renders (W6.1). Built once
+   * in builtin-modals.ts (closing over read-models) and looked up by
+   * ui-openers' openModal callback. Distinct from `modalRedirects` (panel id ->
+   * modal name): a redirect resolves a legacy panel id to a name; this map
+   * resolves that name to the actual surface data/actions.
+   */
+  private modalSurfaces = new Map<string, ConfigModalSurface>();
+  /**
+   * Late-bound: the modal stack is constructed after PanelManager (same
+   * ordering constraint as the openAgentDetail callback in
+   * builtin/shared.ts), so this is injected via a setter rather than the
+   * constructor.
+   */
+  private openModalCallback?: (modalName: string) => void;
   private _visible: boolean = false;
   private _splitRatio: number = 0.6;
 
@@ -99,10 +127,76 @@ export class PanelManager {
     this.aliases.set(aliasId, targetId);
   }
 
+  /**
+   * Register a redirect so `open(panelId)` opens the named modal instead of
+   * constructing a panel (MIGRATE-TO-MODAL surfaces). Checked in open()
+   * before alias/registry resolution.
+   */
+  registerModalRedirect(panelId: string, modalName: string): void {
+    this.modalRedirects.set(panelId, modalName);
+  }
+
+  /**
+   * Inject the callback `open()` invokes when it hits a modal redirect.
+   * Late-bound via setter because the modal stack is constructed after
+   * PanelManager (mirrors the openAgentDetail callback pattern).
+   */
+  setOpenModalCallback(callback: (modalName: string) => void): void {
+    this.openModalCallback = callback;
+  }
+
+  /**
+   * The modal name `panelIdOrAlias` redirects to, if any — lets callers
+   * (e.g. the `/panel` command) print "moved to the <name> modal" before or
+   * instead of calling open().
+   */
+  getModalRedirect(panelIdOrAlias: string): string | undefined {
+    return this.modalRedirects.get(panelIdOrAlias);
+  }
+
+  /**
+   * Register the surface (data + actions) the config-modal host renders for a
+   * modal name. Called from builtin-modals.ts alongside registerModalRedirect.
+   */
+  registerModalSurface(surface: ConfigModalSurface): void {
+    this.modalSurfaces.set(surface.name, surface);
+  }
+
+  /** Resolve a modal name to its registered surface, if any. */
+  getModalSurface(name: string): ConfigModalSurface | undefined {
+    return this.modalSurfaces.get(name);
+  }
+
   private _resolveId(panelId: string): string {
     return this.aliases.get(panelId) ?? panelId;
   }
 
+  /**
+   * Placeholder returned by open() for a modal-redirected id. Never pushed
+   * into a pane, never retained, never rendered — it exists only so open()
+   * can keep its non-null `Panel` return type without constructing the real
+   * (deleted) panel view. `name` carries the modal name so a caller that
+   * inspects the returned panel's `name` (rather than calling
+   * getModalRedirect() beforehand) still gets an honest answer.
+   */
+  private _modalRedirectSentinel(panelId: string, modalName: string): Panel {
+    return {
+      id: panelId,
+      name: modalName,
+      icon: '·',
+      category: 'session',
+      onActivate: () => {},
+      onDeactivate: () => {},
+      onDestroy: () => {},
+      render: () => [],
+      isTransient: true,
+      isPinned: false,
+      needsRender: false,
+      invalidate: () => {},
+      markRendered: () => {},
+    };
+  }
+
   getRegisteredTypes(): PanelRegistration[] {
     return [...this.registry];
   }
@@ -135,7 +229,12 @@ export class PanelManager {
     this._cachedWorkspaceTabs = null;
   }
 
-  open(panelIdOrAlias: string, pane?: 'top' | 'bottom'): Panel {
+  open(panelIdOrAlias: string, pane?: 'top' | 'bottom', target?: PanelDeepLinkTarget): Panel {
+    const modalName = this.modalRedirects.get(panelIdOrAlias);
+    if (modalName !== undefined) {
+      this.openModalCallback?.(modalName);
+      return this._modalRedirectSentinel(panelIdOrAlias, modalName);
+    }
     const panelId = this._resolveId(panelIdOrAlias);
     this._recordRecent(panelId);
     const existingPane = this._findPaneOf(panelId);
@@ -146,12 +245,12 @@ export class PanelManager {
       // pane (fixes `/panel open <id> top` and the panel-list T/B move keys).
       if (pane && pane !== existingPane) {
         this._moveBetweenPanes(existingPane, pane, panelId);
-        return this.getPanel(panelId)!;
+        return this._deliverDeepLink(this.getPanel(panelId)!, target);
       }
       this._activateByIdInPane(panelId, existingPane);
       this._focusedPane = existingPane;
       if (existingPane === 'bottom') this._bottomPaneVisible = true;
-      return this._getPane(existingPane).panels[this._getPane(existingPane).activeIndex]!;
+      return this._deliverDeepLink(this._getPane(existingPane).panels[this._getPane(existingPane).activeIndex]!, target);
     }
 
     const targetPane = pane ?? this._focusedPane;
@@ -173,6 +272,16 @@ export class PanelManager {
     }
     panel.onActivate();
     this._invalidateWorkspaceTabs();
+    return this._deliverDeepLink(panel, target);
+  }
+
+  /**
+   * Hand an optional deep-link target (DEBT-5 item 4) to a panel that just
+   * resolved from open(). Panels without a "node" concept simply don't
+   * implement `receiveDeepLink` — the call is a no-op via optional chaining.
+   */
+  private _deliverDeepLink(panel: Panel, target: PanelDeepLinkTarget | undefined): Panel {
+    if (target) panel.receiveDeepLink?.(target);
     return panel;
   }
 
@@ -387,9 +496,12 @@ export class PanelManager {
           this.bottomPane.panels.push(panel);
           this.bottomPane.activeIndex = 0;
         } else {
-          // Open a predictable default panel in the bottom pane (the panel list),
-          // rather than an arbitrary registration-order-dependent panel.
-          const defaultPanel = this._getRegistration('panel-list') ?? this.registry[0];
+          // Open a predictable default panel in the bottom pane. W6.1 purge:
+          // 'panel-list' was deleted (dead weight over a 5-panel registry —
+          // see the DELETE disposition), so the default is explicitly
+          // 'fleet' rather than falling back to registry[0] (whatever
+          // registers first, currently 'git' — see risk 5 in the brief).
+          const defaultPanel = this._getRegistration('fleet') ?? this.registry[0];
           if (defaultPanel) {
             this.open(defaultPanel.id, 'bottom');
           }
@@ -493,9 +605,11 @@ export class PanelManager {
 
   toggle(): void {
     this._visible = !this._visible;
-    // Auto-open a default panel if toggling visible with nothing open
+    // Auto-open a default panel if toggling visible with nothing open.
+    // W6.1 purge: explicitly 'fleet' rather than registry[0] — see the
+    // matching comment in toggleBottomPane() above.
     if (this._visible && this.topPane.panels.length === 0 && this.bottomPane.panels.length === 0) {
-      const defaultPanel = this._getRegistration('panel-list') ?? this.registry[0];
+      const defaultPanel = this._getRegistration('fleet') ?? this.registry[0];
       if (defaultPanel) this.open(defaultPanel.id);
     }
   }

package/src/panels/polish-core.ts

@@ -1,12 +1,7 @@
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth } from '../utils/terminal-width.ts';
-import { resolveUiTones } from '../renderer/theme.ts';
-
-// DEFAULT_PANEL_PALETTE is built from the mode-resolved chrome tones
-// (resolveUiTones) rather than the static UI_TONES constant — WO-001 single
-// read path. Mode is fixed to 'dark' until the terminal-bg-probe lands.
-const UI_TONES = resolveUiTones('dark');
+import { activeUiTones, registerThemeRefresh } from '../renderer/theme.ts';
 
 // ---------------------------------------------------------------------------
 // Panel palette + core line primitives.
@@ -36,24 +31,36 @@ export interface PanelPalette {
   readonly selectBg?: string;
 }
 
-export const DEFAULT_PANEL_PALETTE: Readonly<Required<PanelPalette>> = {
-  header: UI_TONES.fg.primary,
-  headerBg: UI_TONES.bg.title,
-  label: UI_TONES.fg.muted,
-  value: UI_TONES.fg.primary,
-  dim: UI_TONES.fg.dim,
-  info: UI_TONES.state.info,
-  good: UI_TONES.state.good,
-  warn: UI_TONES.state.warn,
-  bad: UI_TONES.state.bad,
-  empty: UI_TONES.fg.empty,
-  surfaceBg: UI_TONES.bg.surface,
-  sectionBg: UI_TONES.bg.section,
-  summaryBg: UI_TONES.bg.summary,
-  inputBg: UI_TONES.bg.input,
-  accent: UI_TONES.fg.secondary,
-  selectBg: UI_TONES.bg.selected,
-} as const;
+// Built from the mode-resolved chrome tones (activeUiTones). Because 100+ call
+// sites read this object by reference, mode changes rebuild it IN PLACE via the
+// registered refresher below rather than re-resolving per call — see theme.ts's
+// active-mode runtime note. This refresher is registered before any panel's
+// extendPalette() runs (panels import polish → polish-core first), so on a mode
+// flip the base is rebuilt before the extended palettes re-merge from it.
+function buildPanelPalette(): Required<PanelPalette> {
+  const t = activeUiTones();
+  return {
+    header: t.fg.primary,
+    headerBg: t.bg.title,
+    label: t.fg.muted,
+    value: t.fg.primary,
+    dim: t.fg.dim,
+    info: t.state.info,
+    good: t.state.good,
+    warn: t.state.warn,
+    bad: t.state.bad,
+    empty: t.fg.empty,
+    surfaceBg: t.bg.surface,
+    sectionBg: t.bg.section,
+    summaryBg: t.bg.summary,
+    inputBg: t.bg.input,
+    accent: t.fg.secondary,
+    selectBg: t.bg.selected,
+  };
+}
+
+export const DEFAULT_PANEL_PALETTE: Readonly<Required<PanelPalette>> = buildPanelPalette();
+registerThemeRefresh(() => Object.assign(DEFAULT_PANEL_PALETTE as Required<PanelPalette>, buildPanelPalette()));
 
 /**
  * Extend the base panel palette with domain-specific colors.
@@ -73,7 +80,13 @@ export function extendPalette<T extends Record<string, string>>(
   base: typeof DEFAULT_PANEL_PALETTE,
   extras: T,
 ): typeof DEFAULT_PANEL_PALETTE & T {
-  return { ...base, ...extras };
+  const merged = { ...base, ...extras } as typeof DEFAULT_PANEL_PALETTE & T;
+  // Self-register an in-place rebuild so every extendPalette-derived panel
+  // palette (cost/token/git/skills/diff/wrfc) tracks the active mode with zero
+  // per-panel churn. Runs AFTER the base refresher (registered at module eval,
+  // before any panel calls this), so `base` already carries the new-mode values.
+  registerThemeRefresh(() => Object.assign(merged as Record<string, string>, base, extras));
+  return merged;
 }
 
 export function buildPanelLine(

package/src/panels/project-planning-answer-actions.ts

@@ -13,7 +13,7 @@ export interface PlanningAnswerAction {
   readonly label: string;
   readonly detail: string;
   readonly answer: string;
-  readonly kind?: 'answer' | 'approve' | 'dismiss';
+  readonly kind?: 'answer' | 'approve';
   readonly disabled?: boolean;
 }
 
@@ -35,8 +35,12 @@ function compactAnswerDetail(text: string): string {
  * canned suggestions first (de-duplicated by normalized answer text — a
  * question that matches more than one keyword category, e.g. scope +
  * recommendedAnswer echoing one of the scope answers verbatim, must not show
- * the same suggested answer twice), then the fixed ask-narrower/custom/
- * dismiss actions.
+ * the same suggested answer twice), then the fixed ask-narrower/custom actions.
+ *
+ * DEBT-3: dismissing planning is no longer a pseudo answer-row — it is a
+ * first-class confirmed modal action (the `d` key), so no dismiss row is
+ * produced here. A canned answer records against the current open question via
+ * /plan answer; the custom row's free-form text is submitted to chat.
  */
 export function buildAnswerActions(question: ProjectPlanningQuestion, draftAnswer: string): PlanningAnswerAction[] {
   const canned: PlanningAnswerAction[] = [];
@@ -119,16 +123,9 @@ export function buildAnswerActions(question: ProjectPlanningQuestion, draftAnswe
   actions.push({
     id: 'custom',
     label: 'Submit typed answer',
-    detail: draftAnswer ? compactAnswerDetail(draftAnswer) : 'Type an answer first; this row becomes the custom answer.',
+    detail: draftAnswer ? compactAnswerDetail(draftAnswer) : 'Type an answer first; this row submits it to chat.',
     answer: draftAnswer.trim(),
     disabled: !draftAnswer.trim(),
   });
-  actions.push({
-    id: 'dismiss-planning',
-    label: 'Close planning and continue without it',
-    detail: 'Pause project planning for this workspace. Normal chat continues; /plan can reopen it later.',
-    answer: 'Pause project planning for this workspace and continue without the planning panel.',
-    kind: 'dismiss',
-  });
   return actions;
 }

package/src/panels/skills-panel.ts

@@ -5,8 +5,6 @@ import { createEmptyLine } from '../types/grid.ts';
 import { type ConfirmState, handleConfirmInput, renderConfirmLines } from './confirm-state.ts';
 import { getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
 import { ScrollableListPanel } from './scrollable-list-panel.ts';
-import { FilePreviewPanel } from './file-preview-panel.ts';
-import type { PanelIntegrationContext } from './types.ts';
 import type { ComponentHealthMonitor } from '../runtime/perf/panel-health-monitor.ts';
 import { listInstalledEcosystemEntries, type EcosystemCatalogPathOptions, type ShellPathService } from '@/runtime/index.ts';
 import {
@@ -257,11 +255,6 @@ export class SkillsPanel extends ScrollableListPanel<SkillRecord> {
   // I1: confirm state for destructive delete
   private confirm: ConfirmState | null = null;
   private readyPromise: Promise<void> | null = null;
-  // Staged pending action consumed by handlePanelIntegrationAction (same
-  // pattern as diff-panel.ts's pendingOpenPreview): Enter marks the intent
-  // here, the actual PanelManager/preview wiring happens once the
-  // integration context is available.
-  private pendingOpenPreview = false;
 
   public constructor(options: SkillsPanelOptions) {
     super('skills', 'Skills', '▩', 'automation-control', options.componentHealthMonitor);
@@ -374,50 +367,13 @@ export class SkillsPanel extends ScrollableListPanel<SkillRecord> {
 
   public override onDestroy(): void {}
 
-  protected override onSelect(_skill: SkillRecord): void {
-    // Enter opens the skill's markdown source in the preview panel — see
-    // handlePanelIntegrationAction for the actual PanelManager wiring
-    // (needs the integration context, not available here). Selection itself
-    // is read back from getVisibleItems() in that hook. onSelect is only
-    // invoked by ScrollableListPanel's navigation handler when the filter is
-    // not active, so no manual guard is needed here.
-    this.pendingOpenPreview = true;
-  }
-
-  /**
-   * Cross-panel integration hook — Enter opens the selected skill's markdown
-   * source in the preview panel via the same open/focus bridge DiffPanel
-   * uses (src/input/panel-integration-actions.ts), without this panel
-   * needing to know about PanelManager pane/focus mechanics beyond what ctx
-   * exposes.
-   */
-  public handlePanelIntegrationAction(_key: string, ctx: PanelIntegrationContext): boolean {
-    if (!this.pendingOpenPreview) return false;
-    this.pendingOpenPreview = false;
-    const skill = this.getSelectedItem();
-    if (!skill) return false;
-
-    const pm = ctx.panelManager;
-    let previewPanel = pm.getPanel('preview');
-    if (previewPanel instanceof FilePreviewPanel) {
-      const pane = pm.getPaneOf('preview');
-      pm.activateById('preview');
-      if (pane) pm.focusPane(pane);
-    } else {
-      const targetPane: 'top' | 'bottom' = pm.isBottomPaneVisible()
-        ? (pm.getFocusedPane() === 'top' ? 'bottom' : 'top')
-        : 'bottom';
-      const opened = pm.open('preview', targetPane);
-      pm.show();
-      pm.focusPane(targetPane);
-      previewPanel = opened instanceof FilePreviewPanel ? opened : null;
-    }
-    if (previewPanel instanceof FilePreviewPanel) {
-      previewPanel.openFile(skill.path);
-      return true;
-    }
-    return false;
-  }
+  // W6.1 (the purge): Enter used to open the skill's markdown source in the
+  // preview panel via a staged pendingOpenPreview flag + handlePanelIntegrationAction
+  // (same pattern diff-panel.ts used). 'preview' is DELETE-disposition with no
+  // successor surface (no file-picker-overlay preview to repoint to either —
+  // verified), so that cross-panel jump was removed rather than repointed;
+  // Enter is currently a no-op on this list (browse-only until WO-B migrates
+  // Skills to a modal).
 
   public handleInput(key: string): boolean {
     // I1: y/n confirmation dialog for delete

package/src/panels/types.ts

@@ -16,6 +16,18 @@ export interface PanelIntegrationContext {
   readonly executeCommand?: (name: string, args: string[]) => Promise<unknown>;
 }
 
+/**
+ * A cross-panel deep-link target (DEBT-5 item 4): a specific node a panel
+ * should select + reveal when opened via `PanelManager.open(id, pane, target)`,
+ * e.g. a Fleet tree node keyed by its process id and (optionally) its
+ * ProcessKind for disambiguation. Panel-agnostic on purpose — only panels that
+ * have a "node" concept implement `Panel.receiveDeepLink`.
+ */
+export interface PanelDeepLinkTarget {
+  readonly id: string;
+  readonly kind?: string;
+}
+
 /**
  * Named logical key identifiers emitted by the input tokenizer.
  * These are the ONLY key names that will appear in `handleInput` calls;
@@ -126,6 +138,31 @@ export interface Panel {
    * back to its built-in `instanceof` routing.
    */
   handlePanelIntegrationAction?(key: string, ctx: PanelIntegrationContext): boolean;
+
+  /**
+   * Optional: called by the global Ctrl+X (`panel-close`) shortcut BEFORE it
+   * closes this panel (handler-shortcuts.ts). Return `true` to consume
+   * Ctrl+X for an in-panel action instead — e.g. FleetPanel (Wave-3 session
+   * tabs) detaches its active tab and leaves the panel open. Return `false`
+   * (or omit this hook) to fall through to the ordinary close behavior.
+   * Ctrl+X never reaches a panel's own `handleInput` (ctrl/meta combos are
+   * intercepted earlier — see handlePanelFocusToken in
+   * src/input/handler-feed-routes.ts), so this is the one seam a panel has
+   * to intervene before the global shortcut acts.
+   */
+  interceptPanelClose?(): boolean;
+
+  /**
+   * Optional: consume a deep-link target handed in by `PanelManager.open(id,
+   * pane, target)` (DEBT-5 item 4) — select + reveal the matching node on the
+   * panel's next snapshot. A panel without a "node" concept simply doesn't
+   * implement this (the call is a no-op via optional chaining in
+   * PanelManager). A panel that DOES implement it owns its own honest
+   * "not found" surface (e.g. FleetPanel.setError) when the target no longer
+   * resolves — PanelManager has no transcript/print seam to report on its
+   * behalf.
+   */
+  receiveDeepLink?(target: PanelDeepLinkTarget): void;
 }
 
 export interface PanelRegistration extends Pick<Panel, 'id' | 'name' | 'icon' | 'category'> {

package/src/permissions/hunk-selection.ts

@@ -0,0 +1,179 @@
+import type { PermissionPromptRequest } from '@pellux/goodvibes-sdk/platform/permissions';
+
+/**
+ * Per-hunk accept/reject at the approval gate (W1.3 v1).
+ *
+ * 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
+ * splitting would require a genuinely new SDK diff/patch-apply primitive,
+ * flagged as an explicit v2 follow-up, not built here.
+ *
+ * NOTE ON SDK TYPES: the installed @pellux/goodvibes-sdk (0.36.0) does not
+ * yet export `EditItem`/`EditInput` from its `platform/tools` subpath (that
+ * export is added in the in-flight SDK change for this work order, landing
+ * in 0.37). Until then this module reads `request.args.edits` defensively
+ * off a narrow local structural type rather than importing a not-yet-published
+ * symbol, per the cross-repo compile contract for this wave.
+ */
+
+/** Structural shape of one EditItem, read defensively — see module doc. */
+export interface EditItemLike {
+  readonly path: string;
+  readonly find: string;
+  readonly replace: string;
+  readonly id?: string | undefined;
+}
+
+export interface HunkSelectionState {
+  readonly hunks: readonly EditItemLike[];
+  readonly cursor: number;
+  readonly selected: ReadonlySet<number>;
+}
+
+export type HunkCommit = 'apply' | 'cancel' | null;
+
+/**
+ * Structural widening of the installed SDK's `PermissionPromptDecision`
+ * (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
+ * (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.
+ */
+export interface PermissionPromptDecisionWithModifiedArgs {
+  approved: boolean;
+  remember?: boolean;
+  modifiedArgs?: Record<string, unknown>;
+}
+
+export interface HunkKeyResult {
+  readonly state: HunkSelectionState;
+  readonly commit: HunkCommit;
+}
+
+/** Runtime guard: is `value` shaped like an EditItem? */
+function isEditItemLike(value: unknown): value is EditItemLike {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate['path'] === 'string' &&
+    typeof candidate['find'] === 'string' &&
+    typeof candidate['replace'] === 'string' &&
+    (candidate['id'] === undefined || typeof candidate['id'] === 'string')
+  );
+}
+
+/** Extracts a validated EditItemLike[] from a permission request's args, or null if not edit-shaped. */
+function readEditItems(args: Record<string, unknown>): EditItemLike[] | null {
+  const edits = args['edits'];
+  if (!Array.isArray(edits) || edits.length === 0) return null;
+  const items: EditItemLike[] = [];
+  for (const entry of edits) {
+    if (!isEditItemLike(entry)) return null;
+    items.push(entry);
+  }
+  return items;
+}
+
+/**
+ * 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).
+ */
+export function isHunkSelectable(request: PermissionPromptRequest): boolean {
+  if (request.tool !== 'edit') return false;
+  const items = readEditItems(request.args);
+  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). */
+export function buildHunkSelectionState(request: PermissionPromptRequest): HunkSelectionState {
+  const hunks = readEditItems(request.args) ?? [];
+  return {
+    hunks,
+    cursor: 0,
+    selected: new Set(hunks.map((_, i) => i)),
+  };
+}
+
+/**
+ * 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.
+ */
+export function applyHunkKey(state: HunkSelectionState, data: string): HunkKeyResult {
+  const lower = data.toLowerCase().trim();
+
+  if (data === 'j' || data === '\x1b[B') {
+    return { state: { ...state, cursor: Math.min(state.hunks.length - 1, state.cursor + 1) }, commit: null };
+  }
+  if (data === 'k' || data === '\x1b[A') {
+    return { state: { ...state, cursor: Math.max(0, state.cursor - 1) }, commit: null };
+  }
+  if (data === ' ') {
+    const next = new Set(state.selected);
+    if (next.has(state.cursor)) {
+      next.delete(state.cursor);
+    } else {
+      next.add(state.cursor);
+    }
+    return { state: { ...state, selected: next }, commit: null };
+  }
+  if (lower === 'a') {
+    return { state: { ...state, selected: new Set(state.hunks.map((_, i) => i)) }, commit: null };
+  }
+  if (data === '\r' || data === '\n') {
+    if (state.selected.size === 0) {
+      // No-op: nothing selected, prompt stays open rather than applying an empty edit.
+      return { state, commit: null };
+    }
+    return { state, commit: 'apply' };
+  }
+  if (lower === 'y') {
+    // Bypass-navigation shortcut: preserves muscle memory for non-hunk prompts.
+    return { state: { ...state, selected: new Set(state.hunks.map((_, i) => i)) }, commit: 'apply' };
+  }
+  if (lower === 'n' || data === '\x1b' || data === '\x03') {
+    return { state, commit: 'cancel' };
+  }
+
+  return { state, commit: null };
+}
+
+/**
+ * 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.
+ */
+export function buildModifiedEditArgs(
+  request: PermissionPromptRequest,
+  state: HunkSelectionState,
+): Record<string, unknown> {
+  const filtered = state.hunks.filter((_, i) => state.selected.has(i));
+  return { ...request.args, edits: filtered };
+}
+
+/**
+ * buildPendingPermissionExtras — the `hunkState` + wrapped `resolve` fields
+ * 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 never grow it.
+ */
+export function buildPendingPermissionExtras(
+  request: PermissionPromptRequest,
+  resolvePromise: (decision: PermissionPromptDecisionWithModifiedArgs) => void,
+): {
+  hunkState: HunkSelectionState | undefined;
+  resolve: (approved: boolean, remember?: boolean, modifiedArgs?: Record<string, unknown>) => void;
+} {
+  return {
+    hunkState: isHunkSelectable(request) ? buildHunkSelectionState(request) : undefined,
+    resolve: (approved, remember = false, modifiedArgs) => resolvePromise({ approved, remember, modifiedArgs }),
+  };
+}