@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/scripts/orchestrate-parent.ts

@@ -0,0 +1,1155 @@
+#!/usr/bin/env bun
+/** PreToolUse fat-gate + persist rewrite. Stop writes session receipt. SubagentStop intercepts need: search|exec|slice|fetch.
+Fail-open: parse/crash → empty stdout, exit 0.
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { MAX_PROMPT_CHARS, rewriteSpawnToolInput, spawnCapReason } from "./scrub-spawn-prompt.ts";
+import {
+  answerDeny,
+  answerRewrite,
+  fatHookOutput,
+  processFatTools,
+  rewriteScratchPath,
+  stampPlanSave,
+  WRITE_PATH_FIELDS,
+} from "./gate-fat-tools.ts";
+import { projectEdit } from "./gitignore-guard.ts";
+import { holdingCheckout, LESSONS_DIR, matchLessons, persistLesson } from "./lessons.ts";
+import { persistPlan, preparePlanUpdate, validatePlan } from "./persist-plan.ts";
+import { persistRoadmap, prepareRoadmapUpdate, validateRoadmap } from "./persist-roadmap.ts";
+import { persistHandoff } from "./persist-handoff.ts";
+import { persistImplementation, isFullImplementationBody, validateImplementation } from "./persist-implementation.ts";
+import {
+  isUnderDir,
+  isUnderHandoffs,
+  isUnderImplementations,
+  isUnderPlans,
+  isUnderRoadmaps,
+  isUnderTmp,
+  persistTmp,
+} from "./persist-tmp.ts";
+import { parseNeed } from "./parse-need.ts";
+import { resolveJobCwd, runJob } from "./job.ts";
+import { otherLines, recordHook } from "./board.ts";
+import { canonicalPath, resolveRoots, resolveTyped, type Roots } from "./workspace-root.ts";
+import { isRecord, type HookInput } from "./hook-input.ts";
+import { processHookIo, readHookInput, type HookIo } from "./hook-io.ts";
+import { gitAskedWords, mainCheckoutWriteReason } from "./worktree.ts";
+import {
+  closingLine,
+  parseApproval,
+  parseClosingLine,
+  parseMode,
+  parseStrategy,
+  STRATEGIES,
+  stampPath as strategyStampPath,
+  type Mode,
+} from "./strategy.ts";
+import { readEnv } from "../env.ts";
+
+type ToolInput = Record<string, unknown>;
+type Strategy = (typeof STRATEGIES)[number];
+/** A reviewed plan or roadmap, as the closing line names it. */
+type Approvable = Parameters<typeof closingLine>[0][number];
+interface ApprovalItem extends Approvable {
+  path: string;
+  mtime: number;
+}
+/** What every persist function answers to a full-content save. */
+type PersistOutcome = { ok: true; path: string; content: string } | { ok: false; error: string };
+type Persist = (args: { workspaceRoot: string; checkout: string; content: string }) => PersistOutcome;
+type StrategyWrite = { ok: true; content: string | null } | { ok: false; error: string };
+
+export const ORCHESTRATOR_LOGS_DIR = ".tmp/repo/orchestrator-logs";
+/** One-release dual-read; drop next release. */
+export const LEGACY_ORCHESTRATOR_LOGS_DIR = ".tmp/orchestrator-logs";
+export const DENY_REASON = "denied";
+const TRANSCRIPT_TAIL_BYTES = 512 * 1024;
+const SPAWN_TOOLS = new Set(["spawnsubagent", "task", "agent", "spawnagent"]);
+const WRITE_TOOLS = new Set(["write", "edit", "searchreplace"]);
+const INTERCEPT_JOBS = new Set(["search", "exec", "slice", "fetch"]);
+const MAX_INTERCEPT = 3;
+const MAX_STOP = 3;
+const AUTO_RE = /^\s*\/auto\s*$/;
+const ASK_RE = /^\s*\/ask\s*$/;
+const AWAY_RE = /^\s*\/away\s*$/;
+export const SESSION_GATE_STAMP = "session-gate";
+/** One-release dual-read of 0.5 leftover stamp. */
+export const AUTO_ASK_STAMP = "auto-ask";
+export const ASK_STOP_REASON = "ask after this step";
+export const AWAY_STOP_REASON =
+  'away: do not ask; decide, log "- decision: {question} → {choice}, because {why}" in the plan, and continue';
+const WAIT_SCOUT = "[orchestrator]: wait scout";
+
+/** What a handler decides: the exit code and, when the host should see one, the one reply `main` writes. */
+interface HookResult {
+  code: number;
+  reply?: object;
+}
+const PASS: HookResult = { code: 0 };
+const replyWith = (reply: object): HookResult => ({ code: 0, reply });
+
+export function main(_argv?: string[], io: HookIo = processHookIo()): number {
+  try {
+    const data = readHookInput(io) ?? {};
+    const event = eventKey(readEnv().GROK_HOOK_EVENT || data.hookEventName || data.hook_event_name || "");
+    const result = routeEvent(event, data);
+    if (result.reply) io.write(JSON.stringify(result.reply));
+    return result.code;
+  } catch {
+    return 0;
+  }
+}
+
+function routeEvent(event: string, data: HookInput): HookResult {
+  if (event === "pretooluse") return preToolUse(data);
+  if (event === "userpromptsubmit") return userPromptSubmit(data);
+  if (event === "beforesubmitprompt") return beforeSubmitPrompt(data);
+  if (event === "stop") return stop(data);
+  if (event === "subagentstop") return interceptNeed(data, "SubagentStop");
+  return PASS;
+}
+
+function preToolUse(data: HookInput): HookResult {
+  const toolName = String(data.toolName || data.tool_name || "");
+  const toolKey = eventKey(toolName);
+  const toolInput = data.toolInput ?? data.tool_input;
+
+  if (SPAWN_TOOLS.has(toolKey)) {
+    const verdict = rewriteSpawn(toolInput, data);
+    if ("deny" in verdict) return replyWith(verdict.deny);
+    recordReviewSpawn(data, toolInput);
+    return verdict.updated ? replyWith(answerRewrite(data, verdict.updated)) : PASS;
+  }
+  if (WRITE_TOOLS.has(toolKey)) {
+    // A full-content plan Write is answered below, before the gate sees it, so the stamp is written here.
+    if (typeof toolInput?.content === "string") stampPlanSave(data);
+    const persisted = parentWrite(data, toolInput);
+    if (persisted !== null) return persisted;
+  }
+  const fat = emitFat(data);
+  if (fat !== null) return fat;
+  const notice = toolInput && WRITE_TOOLS.has(toolKey) ? lessonNotice(data, toolInput) : null;
+  return notice ? replyWith(notice) : PASS;
+}
+
+/** The path the host named, in whichever field it used; "" when none. */
+function writeTarget(toolInput: ToolInput): string {
+  for (const key of ["file_path", "filePath", "path", "target_file"]) {
+    const v = toolInput[key];
+    if (typeof v === "string" && v) return v;
+  }
+  return "";
+}
+
+export function isLessonFile(filePath: string, workspaceRoot: string | null | undefined): boolean {
+  return isUnderDir(filePath, workspaceRoot, LESSONS_DIR.split("/"));
+}
+
+// Lessons that match a file this session edits, each shown once per session. Fails open.
+function lessonNotice(data: HookInput, toolInput: ToolInput): object | null {
+  try {
+    const roots = resolveRoots(data);
+    const target = writeTarget(toolInput);
+    if (!target) return null;
+    const abs = resolveTyped(roots, target);
+    const holder = holdingCheckout(abs, roots);
+    if (isLessonFile(abs, holder) || rewriteScratchPath(abs, roots) || isUnderDir(abs, roots.root, [".tmp", "repo"]))
+      return null;
+    const rows = matchLessons({ roots, files: [abs] });
+    if (!rows.length) return null;
+    const sid = sessionIdOf(data);
+    const seenFile = sid ? path.join(roots.root, ".tmp", "repo", "sessions", sid, "lessons-seen.json") : "";
+    let seen: string[] = [];
+    if (seenFile) {
+      try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(seenFile, "utf8"));
+        seen = Array.isArray(parsed) ? parsed.filter((v): v is string => typeof v === "string") : [];
+      } catch {
+        seen = [];
+      }
+    }
+    const fresh = rows.filter((r) => !seen.includes(r.file));
+    if (!fresh.length) return null;
+    if (seenFile) {
+      fs.mkdirSync(path.dirname(seenFile), { recursive: true });
+      fs.writeFileSync(seenFile, JSON.stringify([...seen, ...fresh.map((r) => r.file)]));
+    }
+    const rel = path.relative(holder, abs).split(path.sep).join("/");
+    const lines = fresh.map((r) => `- ${r.file} (hits ${r.hits}): ${r.summary}`);
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: `Recorded lessons match ${rel}:\n${lines.join("\n")}`,
+      },
+    };
+  } catch {
+    return null; // A lessons read error never blocks an edit.
+  }
+}
+
+// A lesson Write is validated, rendered, and reindexed in the checkout that holds it, and the host saves it; an Edit
+// cannot be reindexed before it lands. The main checkout takes none: the deny answers here, since the gate never sees this Write.
+function lessonWrite(data: HookInput, roots: Roots, ws: string, rawPath: string, toolInput: ToolInput): HookResult {
+  const abs = path.resolve(ws, rawPath);
+  const shared = mainCheckoutWriteReason(abs, roots);
+  if (shared) return replyWith(answerDeny(data, shared));
+  const body = toolInput.content;
+  if (typeof body !== "string") {
+    return replyWith(
+      answerDeny(
+        data,
+        "Edit is not allowed on lesson files. Write the full lesson (60 lines max) or run bun repo lessons hit <slug> --evidence <text>",
+      ),
+    );
+  }
+  const result = persistLesson({ workspaceRoot: ws, filePath: canonicalPath(abs), content: body });
+  if (!result.ok) return replyWith(answerDeny(data, result.error));
+  return replyWith(answerRewrite(data, Object.assign(withPath(toolInput, abs), { content: result.content })));
+}
+
+function emitFat(data: HookInput): HookResult | null {
+  const fat = fatHookOutput(data, processFatTools(data));
+  return fat ? replyWith(fat) : null;
+}
+
+// Hosts name the target differently; point every key the host sent at the absolute file.
+function withPath(toolInput: ToolInput, abs: string): ToolInput {
+  const next: ToolInput = Object.assign({}, toolInput);
+  const keys: string[] = WRITE_PATH_FIELDS.filter((key) => typeof next[key] === "string" && next[key]);
+  for (const key of keys) next[key] = abs;
+  return next;
+}
+
+// An Edit of a saved plan is checked against the text it would produce; a valid one runs as sent.
+function planEdit(data: HookInput, abs: string, toolInput: ToolInput): HookResult | null {
+  const previous = fs.readFileSync(abs, "utf8");
+  const next = projectEdit(previous, toolInput);
+  if (next == null) return null;
+  const errors = validatePlan(path.basename(abs), next, { fresh: false, previous });
+  return errors.length ? replyWith(answerDeny(data, errors.join("; "))) : null;
+}
+
+// An Edit of a saved roadmap is checked the same way.
+function roadmapEdit(data: HookInput, abs: string, toolInput: ToolInput): HookResult | null {
+  const previous = fs.readFileSync(abs, "utf8");
+  const next = projectEdit(previous, toolInput);
+  if (next == null) return null;
+  const errors = validateRoadmap(path.basename(abs), next, { fresh: false, previous });
+  return errors.length ? replyWith(answerDeny(data, errors.join("; "))) : null;
+}
+
+function parentWrite(data: HookInput, toolInput: ToolInput | undefined): HookResult | null {
+  if (!toolInput) return replyWith(answerDeny(data, DENY_REASON));
+  const roots = resolveRoots(data);
+  const ws = roots.root;
+  const typed = writeTarget(toolInput);
+  if (!typed) return null;
+  const rawPath = rewriteScratchPath(typed, roots) || path.resolve(roots.cwd, typed);
+  // Classify in the roots' spelling; answers keep the typed spelling, which Claude Code's read-before-write knows.
+  const canon = canonicalPath(rawPath);
+  let persist: Persist;
+  let approvable = false;
+  const holder = holdingCheckout(canon, roots);
+  if (isLessonFile(canon, holder)) return lessonWrite(data, roots, holder, rawPath, toolInput);
+  if (isUnderPlans(canon, ws)) {
+    const abs = path.resolve(rawPath);
+    let exists = false;
+    try {
+      exists = fs.statSync(abs).isFile();
+    } catch {
+      exists = false;
+    }
+    if (exists && typeof toolInput.content !== "string") return approvedEdit(data, abs, planEdit(data, abs, toolInput));
+    persist = exists ? (args: Parameters<Persist>[0]) => preparePlanUpdate({ ...args, filePath: abs }) : persistPlan;
+    approvable = true;
+  } else if (isUnderRoadmaps(canon, ws)) {
+    const roadmapPath = path.resolve(rawPath);
+    let exists = false;
+    try {
+      exists = fs.statSync(roadmapPath).isFile();
+    } catch {
+      exists = false;
+    }
+    if (exists && typeof toolInput.content !== "string") {
+      return approvedEdit(data, roadmapPath, roadmapEdit(data, roadmapPath, toolInput));
+    }
+    persist = exists
+      ? (args: Parameters<Persist>[0]) => prepareRoadmapUpdate({ ...args, filePath: roadmapPath })
+      : persistRoadmap;
+    approvable = true;
+  } else if (isUnderHandoffs(canon, ws)) {
+    persist = persistHandoff;
+  } else if (isUnderImplementations(canon, ws)) {
+    persist = persistImplementation;
+    const abs = path.resolve(rawPath);
+    const content = typeof toolInput.content === "string" ? toolInput.content : "";
+    const named = /^\s*IMPL_NAME:/m.test(content);
+    let exists = false;
+    try {
+      exists = fs.statSync(abs).isFile();
+    } catch {
+      exists = false;
+    }
+    if (!named && exists) {
+      if (!isFullImplementationBody(content)) return null;
+      const errors = validateImplementation(path.basename(abs), content);
+      if (errors.length) return replyWith(answerDeny(data, errors.join("; ")));
+      return replyWith(answerRewrite(data, Object.assign(withPath(toolInput, abs), { content })));
+    }
+  } else if (isUnderTmp(canon, ws)) {
+    persist = persistTmp;
+  } else {
+    return null;
+  }
+  const content = typeof toolInput.content === "string" ? toolInput.content : "";
+  const result = persist({ workspaceRoot: ws, checkout: roots.checkout, content });
+  if (!result.ok) return replyWith(answerDeny(data, result.error));
+  const saved = path.resolve(ws, result.path);
+  if (approvable) recordApproval(data, saved);
+  return replyWith(answerRewrite(data, Object.assign(withPath(toolInput, saved), { content: result.content })));
+}
+
+// A valid Edit (null) passes through to the host; it still counts as a save.
+function approvedEdit(data: HookInput, abs: string, denied: HookResult | null): HookResult | null {
+  if (denied === null) recordApproval(data, abs);
+  return denied;
+}
+
+// One closing line asks for approval; a bare `y` approves exactly what it names.
+const APPROVABLE_STATUS: Record<Approvable["kind"], Set<string>> = {
+  plan: new Set(["ready"]),
+  roadmap: new Set(["draft", "locked"]),
+};
+const TURN_START_STAMP = "turn-start";
+const APPROVAL_BLOCK_STAMP = "approval-block";
+
+export function closingLineOf(msg: unknown):
+  | {
+      kind: "plan" | "roadmap";
+      serial: number;
+      strategy: "default" | "review-fast" | "review-deep";
+    }[]
+  | null {
+  const lines = String(msg || "")
+    .split("\n")
+    .map((l) => l.replace(/^[\s`*_>]+/, "").replace(/[\s`*_]+$/, ""))
+    .filter(Boolean);
+  return parseClosingLine(lines.at(-1) || "");
+}
+
+const itemKey = (item: ItemRef): string => `${item.kind} ${item.serial}`;
+const queueText = (items: Approvable[]): string => items.map(itemKey).join(", then ");
+
+function sessionFile(data: HookInput, name: string): string | null {
+  const sid = sessionIdOf(data);
+  if (!sid || sid === "default") return null;
+  return path.join(resolveRoots(data).root, ".tmp", "repo", "sessions", sid, name);
+}
+
+const approvalsFile = (data: HookInput): string | null => sessionFile(data, "approvals.txt");
+
+function readLines(file: string): string[] {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function recordApproval(data: HookInput, abs: string): void {
+  const file = approvalsFile(data);
+  if (!file || readLines(file).includes(abs)) return;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, abs + "\n");
+  } catch {
+    /* fail-open */
+  }
+}
+
+function frontmatterOf(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return out;
+  // Group 1 always participates in a match, so m[1] is a string.
+  for (const line of m[1]!.split(/\r?\n/)) {
+    const kv = /^([a-z]+):\s*(.*)$/.exec(line);
+    // Both groups always participate in a match.
+    if (kv) out[kv[1]!] = kv[2]!.trim();
+  }
+  return out;
+}
+
+// True when a roadmap slice's Location names this plan; Windows paths compare case-insensitively.
+export function isSliceOf(planPath: string, roadmapText: string, impl: typeof path = path): boolean {
+  const norm = (p: string): string => {
+    const n = impl.normalize(impl.resolve(p));
+    return impl === path.win32 ? n.toLowerCase() : n;
+  };
+  const target = norm(planPath);
+  for (const m of String(roadmapText).matchAll(/^\s*Location:\s*(.+?)\s*$/gm)) {
+    // The Location group always participates in a match.
+    if (norm(m[1]!) === target) return true;
+  }
+  return false;
+}
+
+function inProgressRoadmaps(ws: string): string[] {
+  const dir = path.join(ws, ".tmp", "repo", "roadmaps");
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.endsWith(".md"));
+  } catch {
+    return [];
+  }
+  const texts: string[] = [];
+  for (const name of names) {
+    try {
+      const text = fs.readFileSync(path.join(dir, name), "utf8");
+      if (frontmatterOf(text).status === "in-progress") texts.push(text);
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  return texts;
+}
+
+/*
+ * A review's lifecycle, per item, keyed `plan N` / `roadmap N` and never by path text:
+ *   unreviewed  no review spawn recorded and `reviews` is 0
+ *   open        a review spawn recorded `reviews` at spawn, and the file's `reviews` is not above it yet
+ *   settled     `reviews` is above the recorded number, or nothing was recorded and `reviews` is at least 1
+ * Only a settled item may be named by a closing line, approved with `y`, or handed off with `h`.
+ */
+type ItemRef = Pick<Approvable, "kind" | "serial">;
+type ReviewState = "unreviewed" | "open" | "settled";
+type ReviewsOpen = Record<string, number>;
+const REVIEW_SPAWN_RE = /^\s*\/review-(plan|roadmap)\s+(\d+)(?!\S)/;
+const ITEM_DIRS: Record<Approvable["kind"], string> = { plan: "plans", roadmap: "roadmaps" };
+
+const reviewsOpenFile = (data: HookInput): string | null => sessionFile(data, "reviews-open.json");
+
+function readReviewsOpen(data: HookInput): ReviewsOpen {
+  const file = reviewsOpenFile(data);
+  if (!file) return {};
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!isRecord(parsed)) return {};
+    const out: ReviewsOpen = {};
+    for (const [k, v] of Object.entries(parsed)) if (typeof v === "number") out[k] = v;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// The saved file for a plan or roadmap serial, found through its directory; null when none holds that serial.
+function itemFile(ws: string, ref: ItemRef): string | null {
+  const dir = path.join(ws, ".tmp", "repo", ITEM_DIRS[ref.kind]);
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.startsWith(`${ref.serial}-`) && n.endsWith(".md"));
+  } catch {
+    return null;
+  }
+  for (const name of names) {
+    const abs = path.join(dir, name);
+    try {
+      if (Number(frontmatterOf(fs.readFileSync(abs, "utf8")).serial) === ref.serial) return abs;
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  return null;
+}
+
+const reviewsOf = (fm: Record<string, string>): number => Number(fm.reviews) || 0;
+
+function reviewState(open: ReviewsOpen, ref: ItemRef, reviews: number): ReviewState {
+  const atSpawn = open[itemKey(ref)];
+  if (atSpawn !== undefined) return reviews > atSpawn ? "settled" : "open";
+  return reviews >= 1 ? "settled" : "unreviewed";
+}
+
+// The review state of the file a ref names; null when no file holds it.
+function reviewStateOf(ws: string, open: ReviewsOpen, ref: ItemRef): ReviewState | null {
+  const file = itemFile(ws, ref);
+  if (!file) return null;
+  return reviewState(open, ref, reviewsOf(frontmatterOf(fs.readFileSync(file, "utf8"))));
+}
+
+// A spawn whose prompt starts `/review-plan N` or `/review-roadmap N` records the item's `reviews` at spawn.
+function recordReviewSpawn(data: HookInput, toolInput: ToolInput | undefined): void {
+  try {
+    const m = REVIEW_SPAWN_RE.exec(typeof toolInput?.prompt === "string" ? toolInput.prompt : "");
+    const file = reviewsOpenFile(data);
+    if (!m || !file) return;
+    const ref: ItemRef = { kind: m[1] === "plan" ? "plan" : "roadmap", serial: Number(m[2]) };
+    const abs = itemFile(resolveRoots(data).root, ref);
+    if (!abs) return;
+    const reviews = reviewsOf(frontmatterOf(fs.readFileSync(abs, "utf8")));
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ ...readReviewsOpen(data), [itemKey(ref)]: reviews }));
+    fs.renameSync(tmp, file);
+  } catch {
+    /* fail-open: no record means the file's reviews decides */
+  }
+}
+
+// Stop reason when the reply's closing line names an item whose review has not settled.
+function closingReviewReason(data: HookInput, named: Approvable[] | null): string | null {
+  if (!named) return null;
+  const ws = resolveRoots(data).root;
+  const open = readReviewsOpen(data);
+  for (const n of named) {
+    const state = reviewStateOf(ws, open, n);
+    if (state === "unreviewed")
+      return `${itemKey(n)} has reviews: 0; run /review-${n.kind} ${n.serial} in a fresh agent first`;
+    if (state === "open") {
+      return `${itemKey(n)}'s review has not settled; wait for it, settle its findings with reviews bumped, then end with the closing line`;
+    }
+  }
+  return null;
+}
+
+// Reviewed plans and roadmaps this session saved that still wait for a `y`, in first-save order.
+function approvableItems(data: HookInput): ApprovalItem[] {
+  const file = approvalsFile(data);
+  if (!file) return [];
+  const ws = resolveRoots(data).root;
+  const running = inProgressRoadmaps(ws);
+  const open = readReviewsOpen(data);
+  const items: ApprovalItem[] = [];
+  for (const abs of readLines(file)) {
+    const kind: Approvable["kind"] | null = isUnderPlans(abs, ws)
+      ? "plan"
+      : isUnderRoadmaps(abs, ws)
+        ? "roadmap"
+        : null;
+    if (!kind) continue;
+    let text: string;
+    let mtime: number;
+    try {
+      text = fs.readFileSync(abs, "utf8");
+      mtime = fs.statSync(abs).mtimeMs;
+    } catch {
+      continue;
+    }
+    const fm = frontmatterOf(text);
+    const ref: ItemRef = { kind, serial: Number(fm.serial) };
+    if (!APPROVABLE_STATUS[kind].has(fm.status ?? "") || reviewState(open, ref, reviewsOf(fm)) !== "settled") continue;
+    if (kind === "plan" && running.some((t) => isSliceOf(abs, t))) continue;
+    const strategy = parseStrategy(fm.strategy);
+    if (!strategy) continue;
+    items.push({ ...ref, strategy, path: abs, mtime });
+  }
+  return items;
+}
+
+function stampMtime(data: HookInput, prefix: string): number | null {
+  const p = resolveStamp(data, prefix);
+  if (!p) return null;
+  return fs.statSync(p).mtimeMs;
+}
+
+// Stop reason when this turn saved a reviewed item and the reply does not end with a closing line covering it.
+function approvalBlockReason(data: HookInput, msg: string): string | null {
+  if (!approvalsFile(data) || resolveStamp(data, APPROVAL_BLOCK_STAMP)) return null;
+  const turnStart = stampMtime(data, TURN_START_STAMP);
+  if (turnStart == null) return null;
+  const items = approvableItems(data);
+  const pending = items.filter((i) => i.mtime >= turnStart);
+  if (!pending.length) return null;
+  const named = closingLineOf(msg);
+  const known = new Set(items.map(itemKey));
+  // The strategy a line shows must be the one the file holds, so a bare `y` never runs one the person did not see.
+  const shownTruly = (n: Approvable): boolean =>
+    items.some((i) => itemKey(i) === itemKey(n) && i.strategy === n.strategy);
+  const covered =
+    named &&
+    pending.every((p) => named.some((n) => itemKey(n) === itemKey(p))) &&
+    named.every((n) => known.has(itemKey(n)) && shownTruly(n));
+  if (covered) return null;
+  return `end with: ${closingLine(items)}`;
+}
+
+const runOf = (i: ApprovalItem): string =>
+  i.kind === "plan"
+    ? `run /implement-plan ${i.serial} (${i.path})`
+    : `set status locked, then run /implement-roadmap ${i.serial} (${i.path})`;
+const approveStep = (i: ApprovalItem): string => `${itemKey(i)}: ${runOf(i)}`;
+const strategyStep = (i: ApprovalItem, strategy: Strategy): string =>
+  `${itemKey(i)}: strategy ${strategy} was written to its frontmatter; re-read the ${i.kind}, then ${runOf(i)}`;
+
+// The file's text with its `strategy:` frontmatter line set, validated through the persist module; null when nothing would change.
+function strategyWrite(ws: string, item: ApprovalItem, strategy: Strategy): StrategyWrite {
+  const previous = fs.readFileSync(item.path, "utf8");
+  const m = /^---\r?\n[\s\S]*?\r?\n---(?=\r?\n)/.exec(previous);
+  if (!m) return { ok: false, error: "no frontmatter" };
+  const next = m[0].replace(/^strategy:.*$/m, `strategy: ${strategy}`) + previous.slice(m[0].length);
+  if (next === previous) return { ok: true, content: null };
+  const prepare = item.kind === "plan" ? preparePlanUpdate : prepareRoadmapUpdate;
+  const result = prepare({ workspaceRoot: ws, filePath: item.path, content: next });
+  if (!result.ok) return { ok: false, error: result.error };
+  return { ok: true, content: result.content };
+}
+
+// Context for a reply of `y`, `y <strategy>`, `h`, `h fast` or `h deep` that answers the previous reply's closing line.
+function approvalContext(data: HookInput, prompt: string): string {
+  const reply = parseApproval(prompt);
+  if (!reply) return "";
+  const tp = data.transcript_path || data.transcriptPath;
+  if (!tp) return "";
+  const named = closingLineOf(lastAssistantFromTranscript(tp));
+  if (!named) return "";
+  if (reply.kind === "unknown") {
+    return `unknown strategy "${reply.word}"; use y, ${STRATEGIES.map((s) => `y ${s}`)
+      .slice(0, -1)
+      .join(", ")} or y ${STRATEGIES.at(-1)}`;
+  }
+  const refused = reply.kind === "handoff" ? "h did not hand off" : "y did not approve";
+  const ws = resolveRoots(data).root;
+  const open = readReviewsOpen(data);
+  for (const n of named) {
+    const state = reviewStateOf(ws, open, n);
+    if (state && state !== "settled") {
+      return `${refused} ${itemKey(n)}: its review has not settled; wait for it, then end with the closing line again`;
+    }
+  }
+  const items = approvableItems(data);
+  const resolved: ApprovalItem[] = [];
+  for (const n of named) {
+    const hit = items.find((i) => itemKey(i) === itemKey(n));
+    if (!hit) return "";
+    resolved.push(hit);
+  }
+  const wanted = reply.strategy;
+  // A bare reply runs the strategy each file holds, so it must be the one the line showed.
+  // resolved is built one-to-one from named, so named[k] exists.
+  if (wanted === null && resolved.some((i, k) => i.strategy !== named[k]!.strategy)) return "";
+  const writes: StrategyChange[] = [];
+  for (const i of resolved) {
+    if (wanted === null) {
+      writes.push({ item: i, content: null });
+      continue;
+    }
+    const w = strategyWrite(ws, i, wanted);
+    if (!w.ok) return `${refused} ${itemKey(i)}: strategy ${wanted} could not be written (${w.error})`;
+    writes.push({ item: i, content: w.content });
+  }
+  try {
+    for (const w of writes) if (w.content !== null) fs.writeFileSync(w.item.path, w.content);
+  } catch (err) {
+    return `${refused} ${queueText(named)}: strategy ${wanted} could not be written (${String(err)})`;
+  }
+  if (reply.kind === "handoff") return handoffContext(data, ws, writes, wanted);
+  const approves = `y approves ${queueText(named)}: `;
+  return (
+    approves +
+    writes
+      .map((w) => (w.content === null || wanted === null ? approveStep(w.item) : strategyStep(w.item, wanted)))
+      .join("; ")
+  );
+}
+
+type StrategyChange = { item: ApprovalItem; content: string | null };
+
+const handoffLeaf = (i: ApprovalItem): string =>
+  i.kind === "plan" ? `/implement-plan ${i.serial}` : `set status locked, then /implement-roadmap ${i.serial}`;
+
+// One handoff for the whole queue line, in its order; Watch-outs stay empty because the files carry their own.
+function handoffBody(sid: string, queue: { item: ApprovalItem; strategy: Strategy }[]): string {
+  const name = `run ${queue.map((q) => itemKey(q.item)).join(" then ")}`;
+  return [
+    `HANDOFF_NAME: ${name}`,
+    "",
+    `# ${name}`,
+    "",
+    "## Goal",
+    `Run ${queueText(queue.map((q) => q.item))} in a fresh session.`,
+    "",
+    "## State",
+    ...queue.map((q) => `- ${itemKey(q.item)}: ${q.item.path} (strategy: ${q.strategy})`),
+    "",
+    "## Context",
+    `- handed off by an h reply in session ${sid}`,
+    "",
+    "## Next",
+    "1 [ ] Run the queue in order",
+    ...queue.map((q, k) => `1.${k + 1} [ ] ${handoffLeaf(q.item)}`),
+    "",
+    "## Watch-outs",
+    "(none)",
+    "",
+  ].join("\n");
+}
+
+function handoffContext(data: HookInput, ws: string, writes: StrategyChange[], wanted: Strategy | null): string {
+  const queue = writes.map((w) => ({ item: w.item, strategy: wanted ?? w.item.strategy, written: w.content !== null }));
+  const shown = queue
+    .map((q) => `${itemKey(q.item)} (strategy ${q.strategy}${q.written ? " written" : ""})`)
+    .join(", then ");
+  const result = persistHandoff({ workspaceRoot: ws, content: handoffBody(sessionIdOf(data), queue) });
+  if (!result.ok)
+    return `h did not hand off ${queueText(queue.map((q) => q.item))}: the handoff could not be written (${result.error})`;
+  const abs = path.resolve(ws, result.path);
+  return `h handed off ${shown} to ${abs}; tell the person to run /pickup ${result.serial} in a fresh session, and do no work here`;
+}
+
+/** A spawn over the prompt cap is denied; otherwise the scrubbed input, or null when nothing changed. */
+function rewriteSpawn(
+  toolInput: ToolInput | undefined,
+  data: HookInput,
+): { deny: object } | { updated: ToolInput | null } {
+  const updated = rewriteSpawnToolInput(toolInput);
+  const prompt =
+    updated && typeof updated.prompt === "string"
+      ? updated.prompt
+      : toolInput && typeof toolInput.prompt === "string"
+        ? toolInput.prompt
+        : "";
+  if (prompt.length > MAX_PROMPT_CHARS) {
+    return { deny: answerDeny(data, spawnCapReason(resolveRoots(data).root)) };
+  }
+  return { updated };
+}
+
+function userPromptOf(data: HookInput): string {
+  return String(data.prompt ?? data.userPrompt ?? data.user_prompt ?? data.content ?? "");
+}
+
+function isHostStopBanner(prompt: string): boolean {
+  if (/^\s*Stop hook feedback:/.test(prompt)) return true;
+  if (/Blocked by stop hook/.test(prompt)) return true;
+  if (/task[-_ ]?notification/i.test(prompt)) return true;
+  return false;
+}
+
+function countLines(file: string): number {
+  try {
+    return fs
+      .readFileSync(file, "utf8")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean).length;
+  } catch {
+    return 0;
+  }
+}
+
+function sessionReceiptContext(data: HookInput): string {
+  const sid = sessionIdOf(data);
+  if (!sid || sid === "default") return "";
+  const dir = path.join(resolveRoots(data).root, ".tmp", "repo", "sessions", sid);
+  if (!fs.existsSync(dir)) return "";
+  const wrote = countLines(path.join(dir, "wrote.txt"));
+  const read = countLines(path.join(dir, "read.txt"));
+  return `${wrote} wrote, ${read} read. session=.tmp/repo/sessions/${sid}/`;
+}
+
+function writeSessionReceipt(data: HookInput, msg: string): void {
+  const sid = sessionIdOf(data);
+  if (!sid || sid === "default") return;
+  const dir = path.join(resolveRoots(data).root, ".tmp", "repo", "sessions", sid);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    return;
+  }
+  const wrote = countLines(path.join(dir, "wrote.txt"));
+  const read = countLines(path.join(dir, "read.txt"));
+  const first = firstNonEmptyStripped(msg).slice(0, 200);
+  const lines = [first, `${wrote} wrote, ${read} read.`, `session=.tmp/repo/sessions/${sid}/`].filter(Boolean);
+  try {
+    fs.writeFileSync(path.join(dir, "receipt.txt"), lines.join("\n") + "\n");
+  } catch {
+    /* fail-open */
+  }
+}
+
+// What git the user's latest message asked for, read by the gate; each prompt overwrites it, so an empty list clears it.
+function writeGitAsked(data: HookInput, prompt: string): void {
+  const sid = sessionIdOf(data);
+  // The gate finds this file beside the session's strategy stamp, with the sid cleaned the same way.
+  if (!sid.replace(/[^\w-]/g, "")) return;
+  try {
+    const dir = path.dirname(strategyStampPath(resolveRoots(data).root, sid));
+    fs.mkdirSync(dir, { recursive: true });
+    const dest = path.join(dir, "git-asked.json");
+    const tmp = `${dest}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ words: gitAskedWords(prompt) }));
+    fs.renameSync(tmp, dest);
+  } catch {
+    /* fail-open: no stamp means no grant */
+  }
+}
+
+// Cursor's beforeSubmitPrompt does only this: no /ask stamp, board line, approval or reply.
+function beforeSubmitPrompt(data: HookInput): HookResult {
+  writeGitAsked(data, userPromptOf(data));
+  return PASS;
+}
+
+function userPromptSubmit(data: HookInput): HookResult {
+  const prompt = userPromptOf(data);
+  if (isHostStopBanner(prompt)) return PASS;
+  writeGitAsked(data, prompt);
+  unlinkStamp(data, "stop-block");
+  const approval = approvalContext(data, prompt);
+  if (approvalsFile(data)) {
+    writeStamp(data, TURN_START_STAMP, String(Date.now()));
+    unlinkStamp(data, APPROVAL_BLOCK_STAMP);
+  }
+  applySessionGateSlash(data, prompt);
+  let ctx = effectiveSessionContext(data);
+  if (approval) ctx = `${ctx}\n${approval}`;
+  try {
+    recordHook(data, readEnv());
+    const others = otherLines(data, readEnv());
+    if (others) ctx = `${ctx}\n${others}`;
+  } catch {
+    // Board is best-effort. The session receipt still ships.
+  }
+  return replyWith({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: ctx,
+    },
+  });
+}
+
+export function isWaitScoutExact(msg: unknown): boolean {
+  const nonempty = String(msg || "")
+    .split("\n")
+    .filter((l) => l.trim());
+  if (nonempty.length !== 1) return false;
+  // The length check above leaves exactly one line.
+  return nonempty[0]!.replace(/^[\s`*_>]+/, "") === WAIT_SCOUT;
+}
+
+export function hasStepAsk(msg: unknown): boolean {
+  if (isWaitScoutExact(msg) || closingLineOf(msg)) return true;
+  return String(msg || "")
+    .split("\n")
+    .map((l) => l.replace(/^[\s`*_>]+/, "").trim())
+    .filter(Boolean)
+    .some((l) => l.includes("?"));
+}
+
+function firstNonEmptyStripped(msg: unknown): string {
+  for (const line of String(msg || "").split("\n")) {
+    if (!line.trim()) continue;
+    return line.replace(/^[\s`*_>]+/, "");
+  }
+  return "";
+}
+
+function payloadAssistantMessage(data: HookInput): string {
+  return data.lastAssistantMessage || data.last_assistant_message || "";
+}
+
+function isAssistantRecord(obj: unknown): obj is Record<string, unknown> {
+  if (!isRecord(obj)) return false;
+  const type = String(obj.type || "").toLowerCase();
+  if (type === "user" || type === "human" || type === "tool" || type === "tool_result") {
+    return false;
+  }
+  if (type === "assistant") return true;
+  const role = String(obj.role || (isRecord(obj.message) && obj.message.role) || "").toLowerCase();
+  if (role === "user" || role === "human") return false;
+  return role === "assistant";
+}
+
+function assistantTextFromRecord(obj: unknown): string | null {
+  if (!isAssistantRecord(obj)) return null;
+  const msg = isRecord(obj.message) ? obj.message : obj;
+  const content = msg.content ?? obj.content;
+  if (Array.isArray(content)) {
+    const texts: string[] = [];
+    for (const part of content) {
+      if (!isRecord(part)) continue;
+      const pt = String(part.type || "");
+      if (pt === "tool_use" || pt === "tool_result" || pt === "function_call") continue;
+      if (typeof part.text === "string" && part.text) texts.push(part.text);
+    }
+    const joined = texts.join("\n").trim();
+    return joined ? joined : null;
+  }
+  if (typeof content === "string" && content.trim()) return content;
+  if (typeof obj.text === "string" && obj.text.trim()) return obj.text;
+  return null;
+}
+
+export function lastAssistantFromTranscript(filePath: string): string {
+  try {
+    if (!filePath) return "";
+    const st = fs.statSync(filePath);
+    const start = Math.max(0, st.size - TRANSCRIPT_TAIL_BYTES);
+    const fd = fs.openSync(filePath, "r");
+    try {
+      const buf = Buffer.alloc(st.size - start);
+      fs.readSync(fd, buf, 0, buf.length, start);
+      const text = buf.toString("utf8");
+      const lines = text.split("\n");
+      if (start > 0 && lines.length) lines.shift();
+      let last = "";
+      for (const line of lines) {
+        const t = line.trim();
+        if (!t) continue;
+        let rec: unknown;
+        try {
+          rec = JSON.parse(t);
+        } catch {
+          continue;
+        }
+        const extracted = assistantTextFromRecord(rec);
+        if (extracted) last = extracted;
+      }
+      return last;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+
+function stop(data: HookInput): HookResult {
+  if (data.subagentType || data.subagent_type) {
+    return interceptNeed(data, "Stop");
+  }
+  if (data.stopHookActive || data.stop_hook_active) {
+    return PASS;
+  }
+  const reason = String(data.reason || "");
+  if (reason && reason !== "end_turn") return PASS;
+
+  const payloadMsg = payloadAssistantMessage(data);
+  let msg = payloadMsg;
+  if (!msg) {
+    const tp = data.transcript_path || data.transcriptPath || "";
+    msg = lastAssistantFromTranscript(tp);
+  }
+  writeSessionReceipt(data, msg);
+  if (isWaitScoutExact(msg)) return PASS;
+  const named = closingLineOf(msg);
+  const reviewReason = closingReviewReason(data, named);
+  if (reviewReason) return replyWith({ decision: "block", reason: reviewReason });
+  const approvalReason = approvalBlockReason(data, msg);
+  if (approvalReason) {
+    writeStamp(data, APPROVAL_BLOCK_STAMP, "1");
+    return replyWith({ decision: "block", reason: approvalReason });
+  }
+  const mode = effectiveModeOf(data);
+  if (mode === "away" && !named && endsWithQuestion(msg)) return cappedStopBlock(data, AWAY_STOP_REASON);
+  if (mode === "ask" && !hasStepAsk(msg)) return cappedStopBlock(data, ASK_STOP_REASON);
+  return PASS;
+}
+
+// The ask and away blocks share one counter and its cap, so a true blocker still reaches the person.
+function cappedStopBlock(data: HookInput, reason: string): HookResult {
+  const n = readStampInt(data, "stop-block");
+  if (n >= MAX_STOP) return PASS;
+  writeStamp(data, "stop-block", String(n + 1));
+  return replyWith({ decision: "block", reason });
+}
+
+function endsWithQuestion(msg: string): boolean {
+  const last = msg
+    .split("\n")
+    .map((l) => l.replace(/[\s`*_]+$/, ""))
+    .filter(Boolean)
+    .at(-1);
+  return Boolean(last?.endsWith("?"));
+}
+
+function interceptNeed(data: HookInput, hookEventName: string): HookResult {
+  const roots = resolveRoots(data);
+  if (data.stopHookActive || data.stop_hook_active) {
+    return PASS;
+  }
+  const msg = data.lastAssistantMessage || data.last_assistant_message || "";
+  const parsed = parseNeed(msg);
+  if (!parsed.ok) {
+    return PASS;
+  }
+  const jobs = parsed.jobs;
+  if (jobs.length > 4 || !jobs.every((j) => INTERCEPT_JOBS.has(j.job))) {
+    return PASS;
+  }
+
+  let n = readStampInt(data, "need-intercept");
+  if (n >= MAX_INTERCEPT) {
+    return PASS;
+  }
+
+  const cwd = roots.cwd;
+  const parts: string[] = [];
+  for (const job of jobs) {
+    let result: { fallback: boolean; text: string };
+    try {
+      const jobCwd = job.cwd ? resolveJobCwd(job.cwd, cwd) : cwd;
+      if (!jobCwd) {
+        result = { fallback: true, text: "FALLBACK\n" };
+      } else {
+        result = runJob({
+          job: job.job,
+          query: job.query,
+          cwd: jobCwd,
+          root: roots.root,
+          path: job.path,
+          glob: job.glob,
+          stash: job.stash,
+          from: job.from,
+          to: job.to,
+        });
+      }
+    } catch {
+      result = { fallback: true, text: "FALLBACK\n" };
+    }
+    if (result.fallback) {
+      return PASS;
+    }
+    parts.push(result.text.trimEnd());
+  }
+  writeStamp(data, "need-intercept", String(n + 1));
+  const reason = parts.join("\n");
+  return replyWith({
+    decision: "block",
+    hookSpecificOutput: {
+      hookEventName,
+      additionalContext: reason,
+    },
+  });
+}
+
+function stampPath(data: HookInput, prefix: string): string {
+  const root = resolveRoots(data).root;
+  const sid = sessionIdOf(data) || "default";
+  return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
+}
+
+function legacyStampPath(data: HookInput, prefix: string): string {
+  const root = resolveRoots(data).root;
+  const sid = sessionIdOf(data) || "default";
+  return path.join(root, LEGACY_ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
+}
+
+function resolveStamp(data: HookInput, prefix: string): string | null {
+  const neu = stampPath(data, prefix);
+  if (fs.existsSync(neu)) return neu;
+  const old = legacyStampPath(data, prefix);
+  if (fs.existsSync(old)) return old;
+  return null;
+}
+
+function writeStamp(data: HookInput, prefix: string, body: string): string {
+  const p = stampPath(data, prefix);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body);
+  return p;
+}
+
+function readStampInt(data: HookInput, prefix: string): number {
+  const p = resolveStamp(data, prefix);
+  if (!p) return 0;
+  const n = parseInt(fs.readFileSync(p, "utf8"), 10);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return n;
+}
+
+function sessionIdOf(data: HookInput): string {
+  return readEnv().GROK_SESSION_ID || data.sessionId || data.session_id || "";
+}
+
+function unlinkQuiet(p: string): void {
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    /* missing is fine */
+  }
+}
+
+function unlinkStamp(data: HookInput, prefix: string): void {
+  unlinkQuiet(stampPath(data, prefix));
+  unlinkQuiet(legacyStampPath(data, prefix));
+}
+
+function sessionGateStampPath(data: HookInput, prefix: string): string | null {
+  const root = resolveRoots(data).root;
+  const sid = sessionIdOf(data);
+  if (!root || !sid || sid === "default") return null;
+  return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
+}
+
+function resolveSessionGateStamp(data: HookInput): string | null {
+  for (const prefix of [SESSION_GATE_STAMP, AUTO_ASK_STAMP]) {
+    const neu = sessionGateStampPath(data, prefix);
+    if (neu && fs.existsSync(neu)) return neu;
+    const old = path.join(resolveRoots(data).root, LEGACY_ORCHESTRATOR_LOGS_DIR, prefix + "-" + sessionIdOf(data));
+    if (sessionIdOf(data) && fs.existsSync(old)) return old;
+  }
+  return null;
+}
+
+function applySessionGateSlash(data: HookInput, prompt: string): void {
+  let slash = "";
+  if (AUTO_RE.test(prompt)) slash = "auto";
+  else if (ASK_RE.test(prompt)) slash = "ask";
+  else if (AWAY_RE.test(prompt)) slash = "away";
+  if (!slash) return;
+  const p = sessionGateStampPath(data, SESSION_GATE_STAMP);
+  const legacy = sessionGateStampPath(data, AUTO_ASK_STAMP);
+  if (!p || !legacy) return;
+  unlinkQuiet(legacy);
+  if (slash === "auto") {
+    unlinkQuiet(p);
+    return;
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, slash);
+}
+
+/**
+ * The mode this session runs: the newest in-progress plan or roadmap in this session's approvals with a valid `mode:`,
+ * else the /ask or /away stamp, else auto. Another session's files never count.
+ */
+export function effectiveModeOf(data: HookInput): Mode {
+  const file = approvalsFile(data);
+  for (const abs of file ? readLines(file).reverse() : []) {
+    try {
+      const fm = frontmatterOf(fs.readFileSync(abs, "utf8"));
+      const mode = parseMode(fm.mode);
+      if (fm.status === "in-progress" && mode) return mode;
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  try {
+    const p = resolveSessionGateStamp(data);
+    const stamped = p ? parseMode(fs.readFileSync(p, "utf8").trim()) : null;
+    if (stamped) return stamped;
+  } catch {
+    /* fall through */
+  }
+  return "auto";
+}
+
+export function effectiveSessionContext(data: HookInput): string {
+  const gate = effectiveModeOf(data);
+  const receipt = sessionReceiptContext(data);
+  return receipt ? `sessionGate=${gate}. ${receipt}` : `sessionGate=${gate}`;
+}
+
+function eventKey(s: unknown): string {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+}