@warren-dean/code-kit 0.11.0 → 0.12.0

package/hooks/lib/rules.mjs

@@ -35,6 +35,8 @@ import { globToRegExp, matchesAny } from './glob.mjs';
 export const APPROVAL_LOG = '.claude/approval-log.jsonl';
 export const APPROVALS_DIR = '.claude/approvals';
 export const APPROVAL_MINUTES = 60;
+// CARD-7: a request waits until it's answered or dropped, and at most a week, so a forgotten one doesn't linger.
+export const REQUEST_DAYS = 7;
 // A dependency approval lasts until the lane commits the install it allows (the story may resume
 // hours later), and at most a week, so a forgotten one doesn't linger.
 export const DEPENDENCY_APPROVAL_DAYS = 7;
@@ -62,6 +64,8 @@ export const RELAYED = '(given in chat, recorded by the lead)';
 export const PANE = '(approved in the code-kit pane)';
 /** Refusals a person's approval would allow, for the mod's band and `code-kit requests`. */
 export const REQUESTS_FILE = '.claude/state/requests.jsonl';
+/** Every approval given through code-kit, and every one used up, kept for the history (CARD-6). */
+export const GIVEN_FILE = '.claude/state/approvals-given.jsonl';
 
 /** The command the lead runs to record approvals a person gave in chat. */
 /** Marks an approval the lead granted on its own, within `approvals.delegate`; `rule` names the rule. */
@@ -107,11 +111,52 @@ export function approvalHowTo(names, actor, root, allows = 'these edits', config
 export function grantApprovals(root, names, lane, reason, marks = {}) {
   const dir = lane ? join(approvalsDir(root), lane) : approvalsDir(root);
   mkdirSync(dir, { recursive: true });
-  return names.map((name) => {
+  const at = new Date().toISOString();
+  const files = names.map((name) => {
     const file = join(dir, name);
     writeFileSync(file, `${reason.trim()} ${marks[name] ?? RELAYED}\n`);
     return file;
   });
+  noteGiven(
+    root,
+    names.map((name) => ({
+      at,
+      name,
+      ...(lane ? { lane } : {}),
+      reason: `${reason.trim()} ${marks[name] ?? RELAYED}`,
+    })),
+  );
+  return files;
+}
+
+const givenFile = (root) => join(projectWorktrees(root)[0] ?? root, GIVEN_FILE);
+
+function noteGiven(root, entries) {
+  try {
+    const file = givenFile(root);
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, entries.map((e) => `${JSON.stringify(e)}\n`).join(''));
+  } catch {
+    // the approval stands; only its history misses it
+  }
+}
+
+/** The approvals given through code-kit (and those used up), oldest first. */
+export function approvalsGiven(root) {
+  try {
+    return readFileSync(givenFile(root), 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l)];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
 }
 
 /** `path` with symlinks resolved, even if it doesn't exist yet (macOS /var → /private/var). */
@@ -249,8 +294,21 @@ export function useApproval(root, name, actor) {
   for (const file of [
     ...(actor?.kind === 'lane' ? [join(dir, actor.lane, name)] : []),
     join(dir, name),
-  ])
-    if (inForce(file)) return rmSync(file, { force: true });
+  ]) {
+    const a = inForce(file);
+    if (!a) continue;
+    // Kept in the history, and as the answer to the request it was given for, once its file is gone.
+    noteGiven(root, [
+      {
+        at: a.grantedAt,
+        name,
+        ...(file !== join(dir, name) ? { lane: actor.lane } : {}),
+        reason: a.reason,
+        usedAt: new Date().toISOString(),
+      },
+    ]);
+    return rmSync(file, { force: true });
+  }
 }
 
 const requestsFile = (root) => join(projectWorktrees(root)[0] ?? root, REQUESTS_FILE);
@@ -259,8 +317,8 @@ const sameRequest = (a, b) =>
   a.what === b.what &&
   [...a.names].sort().join() === [...b.names].sort().join();
 
-/** Every request recorded, oldest first; unreadable lines are skipped. */
-export function readRequests(root) {
+/** Every line of the requests file: the requests, and the drops (`{ drop: true, of }`). */
+function requestRecords(root) {
   try {
     return readFileSync(requestsFile(root), 'utf8')
       .split('\n')
@@ -277,12 +335,45 @@ export function readRequests(root) {
   }
 }
 
+/** Every request recorded, oldest first; unreadable lines are skipped. */
+export const readRequests = (root) => requestRecords(root).filter((r) => !r.drop);
+
+/** CARD-7: whether a request was dropped (the person dismissed it, or the lead said it's no longer needed). */
+const droppedIn = (drops, r) => drops.some((d) => d.of === r.at && sameRequest(d, r));
+
+/**
+ * CARD-7: drops open requests: `which` is a request's number in `openRequests`' order (1 is the
+ * newest), or 'all'. By the person (`by: 'person'`, from the pane) or the lead, once nobody needs it.
+ */
+export function dropRequests(root, which, { by, reason = null }, now = Date.now()) {
+  const open = openRequests(root, now);
+  const picked = which === 'all' ? open : [open[Number(which) - 1]].filter(Boolean);
+  if (!picked.length)
+    return {
+      ok: false,
+      why: open.length
+        ? `There's no open request ${which}: there are ${open.length} (code-kit requests lists them, newest first).`
+        : 'No approval requests are open.',
+    };
+  const file = requestsFile(root);
+  mkdirSync(dirname(file), { recursive: true });
+  for (const r of picked)
+    appendFileSync(
+      file,
+      `${JSON.stringify({ drop: true, of: r.at, actor: r.actor, names: r.names, what: r.what, by, reason, at: new Date(now).toISOString() })}\n`,
+    );
+  return { ok: true, dropped: picked };
+}
+
 /**
  * Records that `actor` was refused something the approvals `names` would allow, once: the same
- * actor, names and command or file within the approval lifetime count as one request. Recording
- * never changes the refusal, so any failure here is ignored.
+ * actor, names and command or file while one is still open count as one request. Recording never
+ * changes the refusal, so any failure here is ignored.
  */
 export function recordRequest(root, actor, names, what, why, now = Date.now()) {
+  // A read-only agent (a reviewer) is never approved to write: what it changed goes back, not to the
+  // person as a request.
+  if (actor?.kind === 'readonly') return;
   try {
     const request = {
       at: new Date(now).toISOString(),
@@ -292,10 +383,7 @@ export function recordRequest(root, actor, names, what, why, now = Date.now()) {
       what: String(what).slice(0, 200),
       why: String(why).slice(0, 300),
     };
-    const fresh = readRequests(root).filter(
-      (r) => now - Date.parse(r.at) < APPROVAL_MINUTES * 60_000,
-    );
-    if (fresh.some((r) => sameRequest(r, request))) return;
+    if (openRequests(root, now).some((r) => sameRequest(r, request))) return;
     const file = requestsFile(root);
     mkdirSync(dirname(file), { recursive: true });
     appendFileSync(file, `${JSON.stringify(request)}\n`);
@@ -304,19 +392,172 @@ export function recordRequest(root, actor, names, what, why, now = Date.now()) {
   }
 }
 
-/** Requests from the last 60 minutes that an approval in force doesn't yet answer, newest first. */
+/**
+ * CARD-7: requests nobody has answered yet, newest first: each waits until an approval answers it, its
+ * file is committed by someone who could, or it's dropped, and at most REQUEST_DAYS.
+ */
 export function openRequests(root, now = Date.now()) {
   const open = [];
+  const given = approvalsGiven(root);
+  const drops = requestRecords(root).filter((r) => r.drop);
+  // The newest of the same request speaks for it: an older copy doesn't come back once that's dropped.
+  const seen = [];
   for (const r of readRequests(root).reverse()) {
-    if (now - Date.parse(r.at) >= APPROVAL_MINUTES * 60_000) continue;
-    if (open.some((o) => sameRequest(o, r))) continue;
+    if (now - Date.parse(r.at) >= REQUEST_DAYS * 24 * 60 * 60_000) continue;
+    if (seen.some((o) => sameRequest(o, r))) continue;
+    seen.push(r);
+    if (droppedIn(drops, r)) continue;
+    // From before read-only agents stopped asking: only the lead and the lanes are ever approved.
+    if (!r.lane && r.actor !== 'lead session') continue;
     const actor = r.lane ? { kind: 'lane', lane: r.lane } : { kind: 'lead' };
     if (r.names.every((n) => approval(root, n, actor))) continue;
+    // Answered already: approved after it was asked (since expired, or used up by the commit it
+    // allowed), or the file it named was committed since by someone who could.
+    if (r.names.every((n) => grantedSince(root, given, n, r))) continue;
+    if (committedSince(root, r)) continue;
     open.push(r);
   }
   return open;
 }
 
+/** Whether `name` was approved for the request's lane (or for everyone) at or after it was asked. */
+function grantedSince(root, given, name, r) {
+  const asked = Date.parse(r.at);
+  if (
+    given.some(
+      (g) => g.name === name && (!g.lane || g.lane === r.lane) && Date.parse(g.at) >= asked,
+    )
+  )
+    return true;
+  const dir = approvalsDir(root);
+  return [...(r.lane ? [join(dir, r.lane, name)] : []), join(dir, name)].some((file) => {
+    try {
+      return statSync(file).isFile() && statSync(file).mtimeMs >= asked;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Whether the file a request named has been committed, on any branch, since it was asked. */
+function committedSince(root, r) {
+  const path = String(r.what);
+  if (/\s/.test(path) || (!path.includes('/') && !path.includes('.'))) return false;
+  try {
+    const out = execFileSync(
+      'git',
+      [
+        '-C',
+        root,
+        'log',
+        '--all',
+        '-1',
+        '--format=%ct',
+        `--since=@${Math.floor(Date.parse(r.at) / 1000)}`,
+        '--',
+        path,
+      ],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    return Boolean(out.trim());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * CARD-6: every approval given, newest first: { at, name, lane, reason, by, files, branches, used,
+ * expired }. From the approvals given through code-kit, the approvals on disk (a person's own `!` echo
+ * included), and the audit log in every worktree, so an approval shows before its branch merges.
+ */
+export function approvalHistory(root, now = Date.now()) {
+  const grants = [];
+  const near = (a, b) => Math.abs(Date.parse(a) - Date.parse(b)) < 2000;
+  const add = (g) => {
+    const found = grants.find(
+      (x) => x.name === g.name && (x.lane ?? null) === (g.lane ?? null) && near(x.at, g.at),
+    );
+    if (found) {
+      if (g.usedAt) found.used = true;
+      return found;
+    }
+    const grant = {
+      at: g.at,
+      name: g.name,
+      lane: g.lane ?? null,
+      reason: g.reason ?? '',
+      files: [],
+      branches: [],
+      used: Boolean(g.usedAt),
+    };
+    grants.push(grant);
+    return grant;
+  };
+  for (const g of approvalsGiven(root)) add(g);
+  const dir = approvalsDir(root);
+  const look = (folder, lane) => {
+    let names = [];
+    try {
+      names = readdirSync(folder);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const file = join(folder, name);
+      const st = statSync(file);
+      if (st.isDirectory()) {
+        if (!lane) look(file, name);
+        continue;
+      }
+      add({
+        at: new Date(st.mtimeMs).toISOString(),
+        name,
+        lane,
+        reason: readFileSync(file, 'utf8').trim(),
+      });
+    }
+  };
+  look(dir, null);
+  const seen = new Set();
+  for (const tree of projectWorktrees(root).length ? projectWorktrees(root) : [root]) {
+    let lines = [];
+    try {
+      lines = readFileSync(join(tree, APPROVAL_LOG), 'utf8').split('\n').filter(Boolean);
+    } catch {
+      continue;
+    }
+    for (const line of lines) {
+      if (seen.has(line)) continue;
+      seen.add(line);
+      let e;
+      try {
+        e = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!e.approval || e.approval === 'lead') continue;
+      const grant =
+        grants.find((x) => x.name === e.approval && near(x.at, e.grantedAt ?? e.at)) ??
+        add({ at: e.grantedAt ?? e.at, name: e.approval, reason: e.reason });
+      if (e.file && !grant.files.includes(e.file)) grant.files.push(e.file);
+      if (e.branch && !grant.branches.includes(e.branch)) grant.branches.push(e.branch);
+    }
+  }
+  return grants
+    .map((g) => ({
+      ...g,
+      by: /within the delegated rules/.test(g.reason)
+        ? 'the lead, within your delegated rules'
+        : /given in chat, recorded by the lead/.test(g.reason)
+          ? 'you, in chat'
+          : /in the [\w -]+ pane/.test(g.reason)
+            ? 'you, in the pane'
+            : 'you',
+      expired: g.used || now - Date.parse(g.at) >= approvalMinutes(g.name) * 60_000,
+    }))
+    .sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+}
+
 /** Approvals in force now: [{ name, lane?, reason, grantedAt, minutesLeft }]. */
 export function approvalsInForce(root, now = Date.now()) {
   const dir = approvalsDir(root);
@@ -434,6 +675,8 @@ export function writeProblem(actor, rel, root, config) {
   // A package a person approved may change the manifests and lockfiles its install rewrites.
   if (dependencyChange(actor, rel, root, config)) return null;
   const guarded = protectedEntry(rel, config);
+  if (actor.kind === 'readonly' && (guarded || !matchesAny(rel, config.anyActor)))
+    return readonlyProblem(actor, rel);
   // The lead writes protected files without an approval: the person reviews them in the pull request,
   // and every committed change is in the audit log. Anyone else needs a person's approval as well.
   if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
@@ -441,12 +684,16 @@ export function writeProblem(actor, rel, root, config) {
     return `${rel} is ${guarded.why} and needs a person's approval. Ask the lead (a person) to run\n${approvalHowTo(guarded.approval, actor, root, undefined, config)}`;
   }
   if (matchesAny(rel, config.anyActor)) return null;
-  if (actor.kind === 'readonly') return `${actor.label} is read-only; it may not write ${rel}.`;
+  if (actor.kind === 'readonly') return readonlyProblem(actor, rel);
   if (!owns(actor, rel, config)) return ownershipProblem(actor, rel, config);
   const specs = actor.kind === 'lane' && config.docs?.specs;
   return (specs && specCheckProblem(rel, root)) || screenProblem(rel, root, config);
 }
 
+/** A read-only agent's write, refused, with how to undo one a command it ran made (a build, a generator). */
+const readonlyProblem = (actor, rel) =>
+  `${actor.label} is read-only; it may not write ${rel}. If a command you ran changed it (a build, a formatter or a code generator), put it back with git restore -- ${rel} (or delete it if it's new), and run such commands only in a throwaway worktree of the branch.`;
+
 function outsideAllowed(actor, rel, root, config) {
   if (actor.kind !== 'lead') return false;
   const target = resolve(root, rel);

package/hooks/mod/art.mjs

@@ -107,7 +107,7 @@ export function spriteSvg(pose, tint, { lead = false } = {}) {
 
 /**
  * A lane's pose (VIEW-3): stalled when flagged or quiet past the restart time, waiting while a call
- * of its is held or its request is open, working while its agent is at work, quiet when it has
+ * of its is held, its request is open or its story waits on the person's answer, working while its agent is at work, quiet when it has
  * gone quiet, done once its branch is finished, idle otherwise.
  */
 export function poseOf(
@@ -115,7 +115,7 @@ export function poseOf(
   { live = null, waiting = false, flagged = false, shown = lane.state } = {},
 ) {
   if (flagged || live?.level === 'stalled') return 'stalled';
-  if (waiting) return 'waiting';
+  if (waiting || shown === 'waiting on you') return 'waiting';
   if (live?.level === 'quiet') return 'quiet';
   if (lane.active) return 'working';
   if (['in review', 'queued'].includes(shown)) return 'done';

package/hooks/mod/decisions.mjs

@@ -2,6 +2,7 @@
 // the person, each with its lineage. The band's "you" lines say what needs them; a decision card says why:
 // what they asked for, the story and requirements it belongs to, what the agent was doing, what was already
 // settled, why the lead couldn't settle this itself, and each option with what happens next.
+import { askWords } from './view.mjs';
 
 /** The kinds of band line that are the person's to decide; the rest are notes. */
 export const DECISION_KINDS = new Set([
@@ -17,6 +18,10 @@ export const DECISION_KINDS = new Set([
   'teamIntent',
   'teamReview',
   'teamDrift',
+  'question',
+  'brief',
+  'denied',
+  'report',
 ]);
 
 /** What each answer does, in the person's words. */
@@ -40,8 +45,97 @@ const EFFECT = {
     'The issue closes as agreed, with your words; then put it in the specs or decisions so every agent builds on it.',
   dropIntent: 'The issue closes as dropped, and the team carries on as agreed before.',
   team: 'Opens the Team tab: who is building what, and what changed since you last looked.',
+  openDecision: 'Opens it here, with what each answer does.',
+  dropRequest: "Nobody needs it any more: it stops waiting, and nothing's approved.",
+  answer: 'Type your answer; the lead is told it and carries on.',
+  answerBrief: "Type your answer; the lead records it in the brief's decisions and builds on it.",
+  laterBrief: 'It waits; it comes back next session.',
+  runDenied:
+    'Puts it in your prompt after !, so you run it yourself; press Enter to run it, then Done it.',
+  deniedDone: 'The lead is told you ran it, or allowed it, and carries on.',
+  deniedNo: "The lead is told you won't run it now, and carries on with other work.",
+  sendReport:
+    "Files it on code-kit's GitHub under your account (a comment instead, if it's filed already).",
+  discardReport: "It's not sent, and goes.",
 };
 
+/**
+ * CARD-8: one card per decision. A band line can stand for several (approvals waiting, held calls, the
+ * lead's questions, the brief's, Claude Code's refusals, reports); each becomes its own line here, with
+ * the decision it's about, so each card's options answer that one.
+ */
+function eachDecision(line) {
+  if (line.kind === 'approvals' && line.asks?.length > 1)
+    return line.asks.map((a) => ({
+      ...line,
+      text: `Approve ${askWords(a.request, a.files)}`,
+      request: a.request,
+      files: a.files,
+    }));
+  if (line.kind === 'approvals')
+    return [{ ...line, text: `Approve ${askWords(line.request, line.files)}` }];
+  if (line.kind === 'held' && line.calls?.length > 1)
+    return line.calls.map((c) => ({ ...line, text: c.text, held: c.held }));
+  if (line.kind === 'question')
+    return (line.questions ?? [line.question]).map((q) => ({
+      ...line,
+      text: q.question,
+      question: q,
+    }));
+  if (line.kind === 'brief')
+    return (line.briefs ?? [line.brief]).map((b) => ({
+      ...line,
+      text: `From your brief: ${b.question}`,
+      brief: b,
+    }));
+  if (line.kind === 'denied')
+    return (line.denials ?? [line.denial]).map((d) => ({
+      ...line,
+      text: `Claude Code refused ${d.who}'s ${d.what}`,
+      denial: d,
+      actions: [
+        ...(d.command ? [{ id: 'runDenied', label: 'Put it in the prompt' }] : []),
+        { id: 'deniedDone', label: 'Done it' },
+        { id: 'deniedNo', label: 'Not now' },
+      ],
+    }));
+  if (line.kind === 'report')
+    return (line.reports ?? [line.report]).map((r) => ({ ...line, text: r.title, report: r }));
+  return [line];
+}
+
+/** A card's options: the line's own actions, or, for the kinds a card answers differently, its own. */
+function optionsOf(line) {
+  if (line.kind === 'approvals')
+    return [
+      { id: 'approve', label: 'Approve…' },
+      { id: 'dropRequest', label: 'Not needed' },
+    ];
+  // ASK-2: each of the lead's options answers it at once; any answer can be typed instead.
+  if (line.kind === 'question')
+    return [
+      ...line.question.options.map((o, i) => ({
+        id: `answerWith-${i}`,
+        act: 'answerWith',
+        label: o.label,
+        effect: o.effect,
+        line: { ...line, choice: o.label },
+      })),
+      { id: 'answer', label: line.question.options.length ? 'Something else…' : 'Answer…' },
+    ];
+  if (line.kind === 'brief')
+    return [
+      { id: 'answerBrief', label: 'Answer…' },
+      { id: 'laterBrief', label: 'Later' },
+    ];
+  if (line.kind === 'report')
+    return [
+      { id: 'sendReport', label: 'Send' },
+      { id: 'discardReport', label: 'Discard' },
+    ];
+  return line.actions;
+}
+
 /** Why a line needs the person, when the line itself doesn't say. */
 function whyOf(line, check) {
   if (line.kind === 'held') {
@@ -75,6 +169,17 @@ function whyOf(line, check) {
   if (line.kind === 'teamReview') return "It's in a lane you own, so its review is yours.";
   if (line.kind === 'teamDrift')
     return "The team's drift check found your work building on something that has since changed, or heading into someone else's: settle it before it merges.";
+  if (line.kind === 'question')
+    return (
+      line.question.why ??
+      "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.`;
+  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')
+    return "code-kit got in an agent's way. It's sent under your GitHub account to a public repository, so read what it says first.";
   return null;
 }
 
@@ -102,6 +207,7 @@ export function limitsWhy(outside) {
 function storyOf(line, state) {
   const stories = state?.stories ?? [];
   const lane = line.held?.lane ?? line.request?.lane ?? line.stall?.lane ?? null;
+  if (line.question?.story) return stories.find((s) => s.id === line.question.story) ?? null;
   if (line.story) return stories.find((s) => s.id === line.story.id) ?? line.story;
   if (line.stall?.story) return stories.find((s) => s.id === line.stall.story) ?? null;
   if (line.branch) return stories.find((s) => s.branch === line.branch) ?? null;
@@ -123,7 +229,8 @@ export function decisionCards(lines, context = {}) {
   const titles = new Map((status?.requirements ?? []).map((r) => [r.id, r.title]));
   return lines
     .filter((l) => DECISION_KINDS.has(l.kind) && !l.mission)
-    .map((line, i) => {
+    .flatMap((source) => eachDecision(source).map((line) => ({ source, line })))
+    .map(({ source, line }, i) => {
       const story = storyOf(line, state);
       const lane = line.held?.lane ?? line.request?.lane ?? line.stall?.lane ?? story?.lane ?? null;
       const settled = [
@@ -140,6 +247,8 @@ export function decisionCards(lines, context = {}) {
         id: `${line.kind}-${i}`,
         kind: line.kind,
         line,
+        // 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,
         story: story
@@ -151,15 +260,21 @@ export function decisionCards(lines, context = {}) {
         })),
         doing:
           line.held?.command ??
-          line.request?.what ??
+          (line.request ? askWords(line.request, line.files ?? [line.request.what]) : null) ??
           (line.proposal?.label ? `Next step: ${line.proposal.label}` : null) ??
           (line.intent
             ? `Intent #${line.intent.id}: ${line.intent.about}${line.intent.touches.length ? ` (touches ${line.intent.touches.join(', ')})` : ''}`
             : null) ??
-          (line.pull ? `Pull request #${line.pull.number} on ${line.pull.branch}` : null),
+          (line.pull ? `Pull request #${line.pull.number} on ${line.pull.branch}` : null) ??
+          (line.question?.blocks ? `${line.question.story} waits on your answer.` : null) ??
+          (line.denial ? (line.denial.command ?? line.denial.what) : null) ??
+          (line.report ? line.report.body : null),
         settled,
         why: whyOf(line, check),
-        options: line.actions.map((a) => ({ ...a, effect: EFFECT[a.id] ?? null })),
+        options: optionsOf(line).map((a) => ({
+          ...a,
+          effect: a.effect ?? EFFECT[a.act ?? a.id] ?? null,
+        })),
       };
     });
 }

package/hooks/mod/loop.mjs

@@ -14,6 +14,55 @@ const LEAD_STEPS = new Set([
   'update',
 ]);
 
+/** The steps that name stories, which an agent already at work on one shouldn't be asked to start again. */
+const STORY_STEPS = new Set(['dispatch', 'review', 'lead', 'design']);
+const AT_WORK = new Set(['pending', 'running', 'waiting']);
+
+/**
+ * LOOP-9: the stories agents are at work on now, by the task each was started with: a lane agent is
+ * started as "ST-12 booking form", a reviewer as "Review web/st-12". `code-kit next` reads only the
+ * branches, so it can't tell a branch still being built, or already under review, from one waiting.
+ */
+export function storiesInFlight(agents) {
+  const ids = new Set();
+  for (const a of agents ?? []) {
+    if (!AT_WORK.has(a.status)) continue;
+    const text = `${a.description ?? ''}`;
+    for (const m of text.matchAll(/\bST-(\d+)\b/gi)) ids.add(`ST-${m[1]}`);
+    for (const m of text.matchAll(/\b[\w-]+\/st-(\d+)\b/gi)) ids.add(`ST-${m[1]}`);
+  }
+  return ids;
+}
+
+/**
+ * LOOP-9: the step from `code-kit next`, without the stories already in flight. A step left with none
+ * gives way to the next one `next` listed; with nothing left, the loop waits, saying for what, until an
+ * agent finishes (which moves the project on).
+ */
+export function withoutInFlight(step, inFlight) {
+  if (!step || !inFlight?.size) return step;
+  const chain = [step, ...(step.then ?? [])].map(({ then: _then, ...s }) => s);
+  const kept = [];
+  const busy = [];
+  for (const s of chain) {
+    if (!STORY_STEPS.has(s.step)) {
+      kept.push(s);
+      continue;
+    }
+    const ids = (s.args ?? '').split(/\s+/).filter(Boolean);
+    const free = ids.filter((id) => !inFlight.has(id.toUpperCase()));
+    busy.push(...ids.filter((id) => inFlight.has(id.toUpperCase())));
+    if (free.length) kept.push({ ...s, args: free.join(' ') });
+  }
+  if (kept.length) return { ...kept[0], ...(kept.length > 1 ? { then: kept.slice(1) } : {}) };
+  const names = [...new Set(busy)];
+  return {
+    step: 'wait',
+    why: `${names.join(', ')} ${names.length === 1 ? 'is' : 'are'} still with ${names.length === 1 ? 'its agent' : 'their agents'}; the loop goes on when one finishes`,
+    inFlight: names,
+  };
+}
+
 /**
  * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
  * take. Every ready story is named: the dispatch skill decides how many lanes go (LOOP-2). A prompt

package/hooks/mod/panes.mjs

@@ -43,6 +43,7 @@ const GLYPH = {
   'in review': '◐',
   queued: '◆',
   'sent back': '↩',
+  'waiting on you': '?',
   blocked: '■',
   idle: '·',
   ready: '○',
@@ -64,6 +65,7 @@ export function countsOf(state, queue = []) {
     ['in review', n('in review')],
     ['queued', n('queued')],
     ['sent back', n('sent back')],
+    ['waiting on you', n('waiting on you')],
     ['blocked', n('blocked')],
     ['ready', state.ready.length],
     ['merged', (state.stories ?? []).filter((s) => s.state === 'done').length],
@@ -1338,7 +1340,7 @@ export function decisionsTab(cards, ui, { Box, Text, Button }, on) {
               label: o.label,
               ...(o.hotkey ? { hotkey: o.hotkey } : {}),
               variant: 'primary',
-              onPress: () => on.onNeed(o.id, card.line),
+              onPress: () => on.onNeed(o.act ?? o.id, o.line ?? card.line),
             }),
             ...(o.effect ? [text(o.effect, { dimColor: true, wrap: 'wrap' })] : []),
           ],