@warren-dean/code-kit 0.12.2 → 0.13.0

package/hooks/lib/regression.mjs

@@ -0,0 +1,321 @@
+// Regression (docs/specs/18-regression.md). REG-1: a fix comes with a test that fails without it, as the
+// bug, and passes with it. REG-2: a test isn't weakened (deleted, skipped, cut down, its snapshot
+// rewritten) without the person's `tests` approval, which the lead can't delegate. The commit hook
+// refuses a weakening commit; verify finds what a branch weakened, from git.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { runChecks } from './checks.mjs';
+import { matchesAny } from './glob.mjs';
+import { readStories } from './plan.mjs';
+
+/** The approval that lets a test be weakened: the person's only. */
+export const TESTS_APPROVAL = 'tests';
+
+// Test files by the usual conventions, when the config names none (`tests`).
+const TEST =
+  /(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
+export const SNAPSHOT = /(^|\/)__snapshots__\/|\.snap$/;
+
+/** Whether `rel` is a test: the config's `tests` globs, or the usual conventions. */
+export const isTestFile = (rel, config) =>
+  !rel.endsWith('.md') && (config?.tests?.length ? matchesAny(rel, config.tests) : TEST.test(rel));
+
+// A case's name: it('…') / test('…') in JavaScript, def test_… in Python, func Test… in Go, @Test in JVM.
+const JS_CASE =
+  /\b(?:it|test)(?:\.(?:each\s*\([^)]*\)|concurrent|serial|skip|only|todo|fixme|fails))*\s*\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/g;
+const PY_CASE = /^\s*(?:async\s+)?def\s+(test_\w+)/gm;
+const GO_CASE = /^func\s+(Test\w+)\s*\(/gm;
+const JVM_CASE = /@Test\b[^{;]*?\b(?:void|fun)\s+(\w+)\s*\(/g;
+// Markers that skip or focus a test, so the rest stop running.
+const SKIPS = [
+  /\b(?:it|test|describe|suite|context)\.(?:skip|only|todo|fixme)\s*\(/,
+  /\b(?:xit|xtest|xdescribe|fit|fdescribe)\s*\(/,
+  /@pytest\.mark\.(?:skip|skipif|xfail)\b/,
+  /\bpytest\.skip\s*\(/,
+  /\bunittest\.skip/,
+  /\bt\.Skip(?:f|Now)?\s*\(/,
+  /@(?:Disabled|Ignore)\b/,
+];
+const ASSERTION =
+  /\bexpect\s*\(|\bassert\w*\s*[.(]|\bt\.(?:Error|Errorf|Fatal|Fatalf|Fail)\b|\bshould\.\w/g;
+
+const skipLines = (text) =>
+  String(text ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => SKIPS.some((r) => r.test(l)));
+
+/** What a test file holds: its cases' names, its skip and focus markers, and how many assertions. */
+export function testShape(text) {
+  const t = String(text ?? '');
+  const cases = [
+    ...[...t.matchAll(JS_CASE)].map((m) => m[2]),
+    ...[...t.matchAll(PY_CASE)].map((m) => m[1]),
+    ...[...t.matchAll(GO_CASE)].map((m) => m[1]),
+    ...[...t.matchAll(JVM_CASE)].map((m) => m[1]),
+  ];
+  return { cases, skips: skipLines(t), assertions: (t.match(ASSERTION) ?? []).length };
+}
+
+const clip = (s, n = 70) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+const quoteList = (names) =>
+  names
+    .slice(0, 3)
+    .map((n) => `"${clip(n, 50)}"`)
+    .join(', ') + (names.length > 3 ? ` and ${names.length - 3} more` : '');
+
+/** How `after` weakens `before`, in words; empty when it doesn't. */
+export function weakenings(before, after) {
+  const was = testShape(before);
+  const now = testShape(after);
+  const reasons = [];
+  const old = new Set(was.skips);
+  const added = now.skips.filter((l) => !old.has(l));
+  if (added.length || now.skips.length > was.skips.length)
+    reasons.push(
+      `adds a skip or focus marker${
+        added.length
+          ? ` (${added
+              .slice(0, 2)
+              .map((l) => `\`${clip(l, 60)}\``)
+              .join(', ')})`
+          : ''
+      }`,
+    );
+  if (now.cases.length < was.cases.length) {
+    const left = new Set(now.cases);
+    const gone = was.cases.filter((c) => !left.has(c));
+    reasons.push(
+      `has ${was.cases.length - now.cases.length} fewer test case${was.cases.length - now.cases.length === 1 ? '' : 's'}${gone.length ? ` (${quoteList(gone)} gone)` : ''}`,
+    );
+  } else if (now.assertions < was.assertions)
+    reasons.push(
+      `has ${was.assertions - now.assertions} fewer assertion${was.assertions - now.assertions === 1 ? '' : 's'} (${was.assertions} → ${now.assertions})`,
+    );
+  return reasons;
+}
+
+/**
+ * REG-2: the tests a set of changes weakens: [{ file, reasons }]. `changes` is [{ status: 'A'|'M'|'D',
+ * file, from? }] (from: a rename's old path); `before(path)` and `after(path)` read the two sides, null
+ * when the file isn't there. A deleted test whose cases all reappear in an added one was moved, not cut.
+ */
+export function weakenedTests(changes, before, after, config) {
+  const found = [];
+  const added = changes.filter((c) => c.status === 'A' && isTestFile(c.file, config));
+  for (const c of changes) {
+    const was = c.from ?? c.file;
+    if (SNAPSHOT.test(was) && c.status !== 'A') {
+      if (c.status === 'D' || before(was) !== after(c.file))
+        found.push({
+          file: c.file,
+          reasons: [c.status === 'D' ? 'deletes a snapshot' : 'rewrites a snapshot'],
+        });
+      continue;
+    }
+    if (!isTestFile(was, config) || c.status === 'A') continue;
+    const old = before(was);
+    if (old === null) continue;
+    if (c.status === 'D') {
+      const cases = testShape(old).cases;
+      const moved =
+        cases.length > 0 &&
+        added.some((a) => {
+          const there = new Set(testShape(after(a.file)).cases);
+          return cases.every((n) => there.has(n));
+        });
+      if (!moved)
+        found.push({
+          file: c.file,
+          reasons: [
+            `deletes the test file${cases.length ? ` (${cases.length} case${cases.length === 1 ? '' : 's'})` : ''}`,
+          ],
+        });
+      continue;
+    }
+    const reasons = weakenings(old, after(c.file));
+    if (reasons.length) found.push({ file: c.file, reasons });
+  }
+  return found;
+}
+
+const git = (root, ...args) =>
+  execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+const showAt = (root, ref, rel) => {
+  try {
+    return git(root, 'show', `${ref}:${rel}`);
+  } catch {
+    return null;
+  }
+};
+
+/** REG-2 for a branch: what it weakened since `from` (where it left the base), judged from git. */
+export function branchWeakenings(root, from, config) {
+  const changes = git(root, 'diff', '--name-status', '-M', from, 'HEAD')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      const [status, a, b] = l.split('\t');
+      return status.startsWith('R')
+        ? { status: 'M', from: a, file: b }
+        : { status: status[0] === 'D' ? 'D' : status[0] === 'A' ? 'A' : 'M', file: a };
+    });
+  return weakenedTests(
+    changes,
+    (rel) => showAt(root, from, rel),
+    (rel) => showAt(root, 'HEAD', rel),
+    config,
+  );
+}
+
+/**
+ * REG-2 for a commit about to be made: `files` as the commit hook lists them, HEAD against the
+ * working tree.
+ */
+export function commitWeakenings(root, files, config) {
+  const read = (rel) => {
+    try {
+      return readFileSync(join(root, rel), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+  const changes = files.map((file) => {
+    const was = showAt(root, 'HEAD', file) !== null;
+    const is = existsSync(join(root, file));
+    return { status: !was ? 'A' : is ? 'M' : 'D', file };
+  });
+  return weakenedTests(changes, (rel) => showAt(root, 'HEAD', rel), read, config);
+}
+
+/**
+ * REG-1: what a branch fixes, or null when it isn't a fix: its plan story's `**Fixes:**` line (branch
+ * `<lane>/st-<n>`), or a branch named `<lane>/fix-…`.
+ */
+export function fixOf(root, branch, config) {
+  if (!branch) return null;
+  const story = branch.match(/^[^/]+\/(st-\d+)$/i)?.[1]?.toUpperCase();
+  if (story && config.docs?.plan) {
+    const s = readStories(root, config.docs.plan).find((x) => x.id === story);
+    if (s?.fixes) return { story: s.id, what: s.fixes };
+  }
+  if (/^[^/]+\/fix-/.test(branch))
+    return { story: null, what: branch.split('/').slice(1).join('/').slice(4).replace(/-/g, ' ') };
+  return null;
+}
+
+// A failure that only says the test can't reach what it calls: the fix added it, so it proves nothing.
+const UNREACHABLE =
+  /Cannot find module|is not a function|does not provide an export named|is not exported|has no exported member|error TS2305|error TS2339|error TS2724|error TS2614|ImportError|ModuleNotFoundError|cannot import name|undefined: \w|\[build failed\]|ReferenceError: \w+ is not defined/;
+// Signs a test ran and an assertion failed.
+const ASSERTED =
+  /AssertionError|AssertionFailedError|Expected:|Received:|expected .+ to |toBe|toEqual|assert\w* failed|^\s*--- FAIL|Error: expect\(/m;
+
+/** Whether a failure's output only shows the tests couldn't reach what the fix adds. */
+export const onlyUnreachable = (output) =>
+  UNREACHABLE.test(output) && !ASSERTED.test(output.replace(UNREACHABLE, ''));
+
+// The folders an install puts beside the code, which a fresh checkout lacks.
+const INSTALLS = new Set(['node_modules', '.venv', 'venv']);
+
+/** Links the checkout's installs (node_modules and the like, wherever git ignores them) into `dir`. */
+function linkInstalls(root, dir) {
+  let ignored = [];
+  try {
+    ignored = git(root, 'ls-files', '--others', '--ignored', '--exclude-standard', '--directory')
+      .split('\n')
+      .map((l) => l.replace(/\/$/, ''))
+      .filter((l) => l && INSTALLS.has(basename(l)));
+  } catch {
+    return;
+  }
+  for (const rel of ignored) {
+    const to = join(dir, rel);
+    if (!existsSync(dirname(to)) || existsSync(to)) continue;
+    try {
+      symlinkSync(join(root, rel), to, 'dir');
+    } catch {
+      // the check then says what it couldn't run
+    }
+  }
+}
+
+/**
+ * REG-1: whether a fix's tests prove its bug. In a temporary worktree of the branch (with the
+ * checkout's installs linked in, after `regression.prepare`), the checks covering the tests it added
+ * or changed must pass, and fail, as the bug, once every change outside the tests goes back to `from`.
+ * Problems in words; empty when the tests prove it.
+ */
+export function proveFix({ root, from, base, changed, config, fix }) {
+  const what = `This branch fixes ${fix.what}${fix.story ? ` (${fix.story})` : ''}`;
+  const tests = changed.filter(
+    (f) => isTestFile(f, config) && !SNAPSHOT.test(f) && showAt(root, 'HEAD', f) !== null,
+  );
+  if (!tests.length)
+    return [
+      `${what}, but it adds or changes no test. Add a test that fails without the fix: it's what stops the bug coming back.`,
+    ];
+  const covering = config.checks.filter((c) =>
+    tests.some((f) => matchesAny(f, c.files) && !matchesAny(f, c.exclude)),
+  );
+  if (!covering.length)
+    return [
+      `${what}, but no check runs its tests (${tests.join(', ')}), so code-kit can't show they fail without it. Add a check whose files match them.`,
+    ];
+  const strict = { ...config, checks: covering.map((c) => ({ ...c, ifMissing: 'fail' })) };
+  const actor = { kind: 'lead', label: 'lead' };
+  const dir = mkdtempSync(join(tmpdir(), 'code-kit-fix-'));
+  rmSync(dir, { recursive: true });
+  try {
+    git(root, 'worktree', 'add', '--quiet', '--detach', dir, 'HEAD');
+    linkInstalls(root, dir);
+    const prepare = config.regression?.prepare;
+    if (prepare) {
+      const res = spawnSync(prepare, { cwd: dir, shell: true, encoding: 'utf8', timeout: 900000 });
+      if (res.status !== 0)
+        return [
+          `regression.prepare (\`${prepare}\`) failed in a fresh checkout, so the fix's tests couldn't run:\n${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-20).join('\n')}`,
+        ];
+    }
+    const { failure: withFix } = runChecks(strict, tests, dir, actor);
+    if (withFix)
+      return [
+        `${what}, but its tests don't pass in a fresh checkout of the branch (${withFix.title.replace(/ Fix it:$/, '')}), so code-kit can't tell whether they fail without it. If they need an install or a build first, set regression.prepare.${withFix.output ? `\n${String(withFix.output).trim().split('\n').slice(-20).join('\n')}` : ''}`,
+      ];
+    for (const f of changed) {
+      if (isTestFile(f, config) || SNAPSHOT.test(f)) continue;
+      if (showAt(root, from, f) !== null) git(dir, 'checkout', from, '--', f);
+      else rmSync(join(dir, f), { force: true });
+    }
+    const { failure: without } = runChecks(strict, tests, dir, actor);
+    if (!without)
+      return [
+        `${what}, but its tests (${tests.join(', ')}) also pass without the fix, so they don't prove the bug and it can come back. Write a test that fails on ${base} and passes here.`,
+      ];
+    const output = `${without.title}\n${without.output ?? ''}`;
+    if (onlyUnreachable(output)) {
+      const line =
+        output
+          .split('\n')
+          .find((l) => UNREACHABLE.test(l))
+          ?.trim() ?? '';
+      return [
+        `${what}, but its tests fail without the fix only because they call what the fix adds (${clip(line, 120)}). A test that goes through the existing code fails on an assertion when the bug is there: write that one.`,
+      ];
+    }
+    return [];
+  } finally {
+    try {
+      git(root, 'worktree', 'remove', '--force', dir);
+    } catch {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+}

package/hooks/lib/verify.mjs

@@ -10,6 +10,7 @@ import { CONFIG_FILE } from './config.mjs';
 import { isDependencyFile } from './dependencies.mjs';
 import { matchesAny } from './glob.mjs';
 import { layerProblems } from './layers.mjs';
+import { TESTS_APPROVAL, branchWeakenings, fixOf, proveFix } from './regression.mjs';
 import {
   APPROVAL_LOG,
   SECRETS,
@@ -152,17 +153,46 @@ function historySecrets(root, from, changed) {
   return problems;
 }
 
+/** The branch checked out at `root`, or null when HEAD is detached. */
+function currentBranchOf(root) {
+  try {
+    const name = git(root, 'rev-parse', '--abbrev-ref', 'HEAD').trim();
+    return name === 'HEAD' ? null : name;
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Every problem with the branch, grouped: { ownership, protected, layers, baseline, design, checks }.
- * `lane` holds the branch to that lane's paths; `checks: false` leaves the project's checks to CI's
- * own steps.
+ * The files changed, every problem with the branch, grouped as { ownership, protected, layers,
+ * baseline, design, tests, regression, checks }, and the checks `skipped` because a tool isn't
+ * installed. `lane` holds the branch to that lane's paths; `checks: false` leaves the project's
+ * checks to CI's own steps. `fixes` runs a fix's tests without the fix (REG-1; with the
+ * checks unless said); `branch` names the branch when the checkout is detached.
  */
-export function verifyBranch({ root, base, config, lane = null, checks = true }) {
+export function verifyBranch({
+  root,
+  base,
+  config,
+  lane = null,
+  checks = true,
+  fixes = checks,
+  branch = null,
+}) {
   // Where the branch left the base: the base may have moved on since (new log entries, a smaller baseline).
   const from = git(root, 'merge-base', base, 'HEAD').trim();
   const changed = branchChanges(root, base);
   const present = changed.filter((f) => existsSync(join(root, f)));
-  const found = { ownership: [], protected: [], layers: [], baseline: [], design: [], checks: [] };
+  const found = {
+    ownership: [],
+    protected: [],
+    layers: [],
+    baseline: [],
+    design: [],
+    tests: [],
+    regression: [],
+    checks: [],
+  };
   const { entries, problems: logProblems } = logEntries(root, from);
   found.protected.push(...logProblems);
   const logged = new Map(entries.map((e) => [e.file, e]));
@@ -235,11 +265,27 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
           found.baseline.push(`${BASELINE_FILE} gained ${p}; it only shrinks.`);
   }
 
+  // REG-2: a test weakened on the branch needs the person's `tests` approval, logged by the commit.
+  for (const w of branchWeakenings(root, from, config)) {
+    const approved = entries.some((e) => e.file === w.file && e.approval === TESTS_APPROVAL);
+    if (!approved)
+      found.tests.push(
+        `${w.file} ${w.reasons.join(', and ')}. A weakened test can hide a regression, so it needs the person's tests approval, which the commit records in ${APPROVAL_LOG}. Restore the test and fix the code, or ask the person.`,
+      );
+  }
+
+  // REG-1: a fix's tests fail without it, as the bug.
+  const fix = fixes ? fixOf(root, branch ?? currentBranchOf(root), config) : null;
+  if (fix) found.regression.push(...proveFix({ root, from, base, changed, config, fix }));
+
+  let skipped = [];
   if (checks) {
     const actor = lane
       ? { kind: 'lane', lane, label: `${lane} lane branch` }
       : { kind: 'lead', label: 'lead' };
-    const failure = runChecks(config, changed, root, actor);
+    const ran = runChecks(config, changed, root, actor);
+    skipped = ran.skipped;
+    const { failure } = ran;
     if (failure)
       found.checks.push(
         `${failure.title}\n${String(failure.output ?? '')
@@ -248,5 +294,5 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
           .join('\n')}`.trim(),
       );
   }
-  return { changed, found };
+  return { changed, found, skipped };
 }

package/hooks/mod/decisions.mjs

@@ -189,7 +189,10 @@ function headlineOf(line, story) {
       sub: `from the lead${forStory}${line.question.blocks ? ', which waits on it' : ''}`,
     };
   if (line.kind === 'brief')
-    return { headline: line.brief.question, sub: `open in ${line.brief.path}` };
+    return {
+      headline: line.brief.question,
+      sub: `open in ${line.brief.path}${line.brief.blocks ? ` · holds up ${line.brief.blocks}` : ''}`,
+    };
   if (line.kind === 'denied')
     return {
       headline: `Claude Code refused ${line.denial.who}'s call`,
@@ -239,7 +242,7 @@ function whyOf(line, check) {
       "The lead can't settle this itself: it's yours to decide, and the lead builds on your answer."
     );
   if (line.kind === 'brief')
-    return `It's an open question in ${line.brief.path}: what gets built depends on your answer.`;
+    return `It's an open question in ${line.brief.path}, left for you: what gets built depends on your answer. Not sure what it means? Ask about it when you answer.`;
   if (line.kind === 'denied')
     return `Claude Code's own permission check refused it${line.denial.reason ? ` (${line.denial.reason})` : ''}, which code-kit can't approve past: only you can run it or allow it.`;
   if (line.kind === 'report')
@@ -297,9 +300,11 @@ export function decisionCards(lines, context = {}) {
     .map(({ source, line }, i) => {
       const story = storyOf(line, state);
       const lane = line.held?.lane ?? line.request?.lane ?? line.stall?.lane ?? story?.lane ?? null;
+      // Approvals in force bear on an approval or a held call, not on a question about the product.
+      const aboutApprovals = ['held', 'approvals', 'stalled'].includes(line.kind);
       const settled = [
         ...journal.filter((e) => story && e.story === story.id).map((e) => e.text),
-        ...inForce
+        ...(aboutApprovals ? inForce : [])
           .filter((a) => !lane || !a.lane || a.lane === lane)
           .slice(0, 3)
           .map(
@@ -318,7 +323,22 @@ export function decisionCards(lines, context = {}) {
         // The band line it came from: one line can stand for several decisions (CARD-8).
         source,
         title: line.text,
-        asked: [request, goal].filter(Boolean).join(' · ') || null,
+        // CARD-9: what they asked for in a line (the brief's title, not its whole problem).
+        asked:
+          [request && clip(firstSentence(request), 140), goal].filter(Boolean).join(' · ') || null,
+        // The question itself, and the brief's own columns for it (who decides, what it holds up).
+        details: [
+          ...(line.kind === 'brief'
+            ? [
+                { label: 'Question', value: line.brief.question },
+                ...(line.brief.owner ? [{ label: 'Who decides', value: line.brief.owner }] : []),
+                ...(line.brief.blocks ? [{ label: 'Holds up', value: line.brief.blocks }] : []),
+              ]
+            : []),
+          ...(line.kind === 'question'
+            ? [{ label: 'Question', value: line.question.question }]
+            : []),
+        ],
         story: story
           ? { id: story.id, title: story.title ?? '', branch: story.branch ?? null }
           : null,

package/hooks/mod/loop.mjs

@@ -75,7 +75,7 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
   // MQ-2: the head of the merge queue, where the lead merges within the delegated rules.
   if (step.step === 'merge')
     return ids.length
-      ? `Merge ${ids[0]}, next in the merge queue: run node "${cli}" queue merge --delegated. It verifies the branch against the base as it is now, and sends it back to its lane if it conflicts or fails.`
+      ? `Merge ${ids[0]}, next in the merge queue: run node "${cli}" queue merge --delegated. It verifies the branch against the base as it is now, and sends it back to its lane if it conflicts or fails; a branch that moved after its review leaves the queue for you to review again.`
       : null;
   // SETUP-2: the base has no rules yet; the lead puts the approved ones there, then merges as usual.
   if (step.step === 'rules')

package/hooks/mod/panes.mjs

@@ -1357,7 +1357,17 @@ export function decisionsTab(cards, ui, { Box, Text, Button }, on) {
     paddingX: 1,
     rowGap: 0,
     children: [
-      text(card.headline, { bold: true, wrap: 'wrap' }),
+      text(
+        card.kind === 'brief'
+          ? 'An open question in your brief'
+          : card.kind === 'question'
+            ? 'A question from the lead'
+            : card.headline,
+        { bold: true, wrap: 'wrap' },
+      ),
+      ...(card.details ?? []).map((d) =>
+        row(d.label, d.value, d.label === 'Question' ? { bold: true } : {}),
+      ),
       ...(card.asked ? [row('You asked for', card.asked)] : []),
       ...(card.story
         ? [

package/hooks/mod/register.mjs

@@ -21,6 +21,7 @@ import {
   answerPane,
   approvalAsidePrompt,
   approvePane,
+  questionAsidePrompt,
   commandItself,
   band,
   bandLines,
@@ -564,12 +565,24 @@ export function register(on) {
       answerWith: (line) => act.sendAnswer({ kind: 'question', ...line.question }, line.choice),
       // ASK-2, ASK-4: Answer… opens a box for the person's own words.
       answer: async (line) => {
-        answering = { kind: 'question', ...line.question, text: '', error: null };
+        answering = {
+          kind: 'question',
+          ...line.question,
+          text: '',
+          error: null,
+          aside: { thread: [], draft: '' },
+        };
         await $.ui.open({ id: ANSWER_ID, title: 'Answer', focus: true, closeOnEscape: true });
         $.ui.invalidate('ui.render');
       },
       answerBrief: async (line) => {
-        answering = { kind: 'brief', ...line.brief, text: '', error: null };
+        answering = {
+          kind: 'brief',
+          ...line.brief,
+          text: '',
+          error: null,
+          aside: { thread: [], draft: '' },
+        };
         await $.ui.open({ id: ANSWER_ID, title: 'Answer', focus: true, closeOnEscape: true });
         $.ui.invalidate('ui.render');
       },
@@ -613,17 +626,24 @@ export function register(on) {
           }
         }
         notice = null;
-        const said = /[.!?]$/.test(text) ? text : `${text}.`;
-        await $.prompt.submit({
-          text:
-            q.kind === 'question'
-              ? `The person answered ${q.id} (${q.question}): ${said}${q.blocks ? ` ${q.story} no longer waits on them.` : ''} Carry on with it.`
-              : `The person answered an open question in ${q.path}, "${q.question}": ${said} Record it in the brief's decision log, take it out of the open questions, and carry on with it.`,
-        });
+        // Answered, the decision goes at once; the lead hears it as a turn of its own once it's idle, which
+        // can be long after (so the prompt isn't waited on).
         if (q.kind === 'brief') {
           briefLater.add(q.question);
           model = { ...model, brief: (model.brief ?? []).filter((b) => b.question !== q.question) };
         }
+        if (q.kind === 'question')
+          model = { ...model, questions: (model.questions ?? []).filter((x) => x.id !== q.id) };
+        $.ui.invalidate('ui.render');
+        const said = /[.!?]$/.test(text) ? text : `${text}.`;
+        $.prompt
+          .submit({
+            text:
+              q.kind === 'question'
+                ? `The person answered ${q.id} (${q.question}): ${said}${q.blocks ? ` ${q.story} no longer waits on them.` : ''} Carry on with it.`
+                : `The person answered an open question in ${q.path}, "${q.question}": ${said} Record it in the brief's decision log, take it out of the open questions, and carry on with it.`,
+          })
+          .catch(() => {});
         await act.reload();
         return true;
       },
@@ -634,16 +654,20 @@ export function register(on) {
       deniedDone: async (line) => {
         denied.delete(line.denial.id);
         $.ui.invalidate('ui.render');
-        await $.prompt.submit({
-          text: `The person ran it themselves, or allowed it: ${line.denial.command ?? line.denial.what} (Claude Code had refused it for ${line.denial.who}). Check it worked, and carry on.`,
-        });
+        $.prompt
+          .submit({
+            text: `The person ran it themselves, or allowed it: ${line.denial.command ?? line.denial.what} (Claude Code had refused it for ${line.denial.who}). Check it worked, and carry on.`,
+          })
+          .catch(() => {});
       },
       deniedNo: async (line) => {
         denied.delete(line.denial.id);
         $.ui.invalidate('ui.render');
-        await $.prompt.submit({
-          text: `The person won't run ${line.denial.command ?? line.denial.what} now (Claude Code refused it for ${line.denial.who}). Don't try to get around it: carry on with other work, and if a story can't go on without it, ask with code-kit ask --blocks.`,
-        });
+        $.prompt
+          .submit({
+            text: `The person won't run ${line.denial.command ?? line.denial.what} now (Claude Code refused it for ${line.denial.who}). Don't try to get around it: carry on with other work, and if a story can't go on without it, ask with code-kit ask --blocks.`,
+          })
+          .catch(() => {});
       },
       // REPORT-3: the person sends a drafted report to code-kit's GitHub, or discards it.
       sendReport: async (line) => {
@@ -675,6 +699,40 @@ export function register(on) {
           heldId: line.held.id,
           outside: line.held.outside ?? null,
         }),
+      // ACT-5: a side call over the lead's own conversation (it shares the prompt cache, and nothing is
+      // added to the conversation); before the lead's first reply, from the prompt's facts alone.
+      sideCall: async (prompt) => {
+        const failed = (err) => ({ isAnswered: false, reason: String(err?.message ?? err) });
+        const reply = await $.model.fork({ prompt }).catch(failed);
+        if (reply.isAnswered || reply.reason !== 'nothing-to-fork') return reply;
+        return $.model.complete({ model: 'sonnet', prompt, maxTokens: 800 }).catch(failed);
+      },
+      // ASK-5: a question about a question, asked in the answer box before answering.
+      askAnswer: async (question) => {
+        const q = question.trim();
+        if (!answering || !q) return;
+        const asked = answering;
+        const turn = { question: q, pending: true };
+        const thread = asked.aside.thread;
+        answering = { ...asked, aside: { thread: [...thread, turn], draft: '' } };
+        $.ui.invalidate('ui.render');
+        const reply = await act.sideCall(questionAsidePrompt({ q: asked, thread, question: q }));
+        if (!answering || answering.question !== asked.question) return;
+        const done = reply.isAnswered
+          ? { question: q, answer: reply.text }
+          : {
+              question: q,
+              error: `No answer: ${reply.reason}${reply.status ? ` (${reply.status})` : ''}`,
+            };
+        answering = {
+          ...answering,
+          aside: {
+            ...answering.aside,
+            thread: answering.aside.thread.map((t) => (t === turn ? done : t)),
+          },
+        };
+        $.ui.invalidate('ui.render');
+      },
       // ACT-5: a question about the approval, answered in its pane by a side call over the lead's own
       // conversation (it shares the prompt cache, and nothing is added to the conversation); before the
       // lead's first reply, from code-kit's facts alone.
@@ -694,13 +752,7 @@ export function register(on) {
           thread,
           question: q,
         });
-        let reply = await $.model
-          .fork({ prompt })
-          .catch((err) => ({ isAnswered: false, reason: String(err?.message ?? err) }));
-        if (!reply.isAnswered && reply.reason === 'nothing-to-fork')
-          reply = await $.model
-            .complete({ model: 'sonnet', prompt, maxTokens: 800 })
-            .catch((err) => ({ isAnswered: false, reason: String(err?.message ?? err) }));
+        const reply = await act.sideCall(prompt);
         // Answered for this approval only: a pane closed or moved on meanwhile keeps what it has.
         if (!approving || approving.request !== asked.request) return;
         const done = reply.isAnswered
@@ -2004,6 +2056,11 @@ export function register(on) {
       },
       onSubmit: (value) => act.confirmAnswer(value),
       onCancel: () => act.cancelAnswer(),
+      onAskInput: (value) => {
+        answering = { ...answering, aside: { ...answering.aside, draft: value } };
+        $.ui.invalidate('ui.render');
+      },
+      onAsk: (value) => act.askAnswer(value),
     });
   });