squadrant 0.19.0 → 0.19.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "squadrant",
   "packageManager": "pnpm@10.30.3",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Multi-project orchestration for your coding agents (Claude, Codex, opencode, Gemini)",
   "type": "module",
   "bin": {

package/plugin/skills/captain-ops/SKILL.md

@@ -214,7 +214,7 @@ You don't have an Agent Team or `TaskCreate`/`TaskUpdate` tools — those were C
 
 If you ever need a bounded check (not a loop), use a fixed counter (≤ 3 attempts with a sleep between), or watch the mailbox seq — never an unbounded `until` loop.
 
-### Handling CREW IDLE
+### Handling CREW IDLE / BLOCKED
 
 CREW IDLE is **ambiguous** — the watchdog did not detect a heartbeat, which can happen when:
 - **(a)** The crew finished but never ran `squadrant crew signal done` (issue #278 — common for claude/opencode before the completion-protocol fix).
@@ -226,12 +226,13 @@ On CREW IDLE, do a **single on-demand spot-check** (allowed — not a polling lo
 | Spot-check shows | Captain action |
 |-----------------|----------------|
 | Completed work (PR opened, commits pushed, results reported) but no CREW DONE | Treat as the #278 case — review, then follow the HUMAN REVIEW GATE contract: surface the diff and wait for operator go-ahead; never merge unprompted. If not actually done, **re-task**: send the next instruction via `crew send` (the #148 re-open flow). |
-| Crew asked a question or is waiting for a decision | Respond via `crew send`. Do NOT terminalize — it will signal done after the next turn. |
+| Crew asked a question or is waiting for a decision (plain text, no rendered options) | Respond via `crew send`. Do NOT terminalize — it will signal done after the next turn. |
+| Crew has an **open AskUserQuestion/permission prompt** (a rendered `❯ 1. …` option list) | `crew send` will correctly **refuse** to touch it — don't fight the refusal or fall back to `crew close` + re-spawn. Read the options with `squadrant crew read <project> <name>`, then answer deliberately with `squadrant crew answer <project> <name> <option>` (#592). Never guess with a bare Enter. |
 | Still mid-task / transient idle | Leave it; wait for the next daemon event. |
 
 **Do not re-send the original task** if the crew appears to have completed it — that triggers a duplicate run. Read the crew screen or diff first, then decide: terminalize vs re-task vs leave.
 
-This is the captain-side backstop: even if the completion-protocol imperative is skipped, the lifecycle still terminalizes because the captain classifies intent instead of letting the task strand at IDLE.
+This is the captain-side backstop: even if the completion-protocol imperative is skipped, the lifecycle still terminalizes because the captain classifies intent instead of letting the task strand at IDLE. The same BLOCKED-on-a-real-prompt case applies whether the daemon fires an explicit CREW BLOCKED event or you only notice via a spot-check on IDLE.
 
 When a crew sends you a status message via `squadrant runtime send <project> "<message>"`, it lands in your captain pane. Acknowledge, then update your handoff if a meaningful decision was made.
 

package/scripts/control-event-table.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// Generates docs/generated/control-events.md: every ControlEvent variant vs its
+// producers (emit sites) and consumers (state-machine case, reduce.ts allowlist,
+// telegram formatter), plus registered LifecycleSource count vs CLAUDE.md's claim.
+//
+// `--check` regenerates the table in memory and exits non-zero if it differs
+// from what's on disk, OR if a ControlEvent variant has zero shipped producers
+// and is not in KNOWN_ZERO_PRODUCER below. That's what makes a new zombie event
+// or doc drift fail `pnpm test` instead of sitting unnoticed.
+//
+// Plain Node, no dependencies. See docs/specs/2026-08-29-event-architecture-design.md §1.5, §11.
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const CONTROL_TYPES_FILE = join(ROOT, "packages/shared/src/types/control.ts");
+const STATE_MACHINE_FILE = join(ROOT, "packages/core/src/state-machine.ts");
+const REDUCE_FILE = join(ROOT, "packages/core/src/daemon/reduce.ts");
+const TELEGRAM_FORMAT_FILE = join(ROOT, "packages/core/src/telegram/format.ts");
+const SQUADRANTD_FILE = join(ROOT, "packages/cli/src/squadrantd.ts");
+const CLAUDE_MD_FILE = join(ROOT, "CLAUDE.md");
+const OUT_FILE = join(ROOT, "docs/generated/control-events.md");
+const PACKAGES_DIR = join(ROOT, "packages");
+
+// Variants verified (2026-08-29 event-architecture design, §1.5) to have a
+// state-machine case, a reduce.ts allowlist entry, and (for task.idle) a
+// telegram formatter — but zero shipped producers. Removing an entry here
+// without giving it a real producer is a lie; adding one back is a real
+// regression. Either way this list must be a deliberate edit, not silent.
+const KNOWN_ZERO_PRODUCER = ["heartbeat", "task.idle", "task.reconcile-failed"];
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function walkSourceFiles(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name === "__tests__" || entry.name === "dist" || entry.name === "node_modules") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkSourceFiles(full, out);
+    else if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx"))) out.push(full);
+  }
+  return out;
+}
+
+function extractVariants(controlTypesText) {
+  const variants = [];
+  const re = /^\s*\|\s*\{\s*type:\s*"([^"]+)"/gm;
+  let m;
+  while ((m = re.exec(controlTypesText))) variants.push(m[1]);
+  return variants;
+}
+
+// Producer = a line constructing `{ type: "<variant>" ... }` as an object
+// literal (an emit site). Excludes the union definition itself and
+// `Extract<ControlEvent, { type: "..." }>` type-level narrowing, which reads
+// like construction but declares nothing.
+function findProducers(files, variant) {
+  const re = new RegExp(`type:\\s*["']${escapeRe(variant)}["']`);
+  const hits = [];
+  for (const file of files) {
+    if (file === CONTROL_TYPES_FILE) continue;
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.includes("Extract<")) continue;
+      if (re.test(line)) hits.push(`${relative(ROOT, file)}:${i + 1}`);
+    }
+  }
+  return hits;
+}
+
+function hasCase(text, variant) {
+  return new RegExp(`case\\s+["']${escapeRe(variant)}["']\\s*:`).test(text);
+}
+
+function extractKnownEventTypes(reduceText) {
+  const m = reduceText.match(/KNOWN_EVENT_TYPES[^=]*=\s*new Set\(\[([\s\S]*?)\]\)/);
+  if (!m) throw new Error("KNOWN_EVENT_TYPES not found in reduce.ts");
+  return new Set([...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]));
+}
+
+function extractLifecycleSources(squadrantdText) {
+  const block = squadrantdText.match(/ctx\.lifecycleSources\s*=\s*\[([\s\S]*?)\];/);
+  if (!block) throw new Error("ctx.lifecycleSources assignment not found in squadrantd.ts");
+  const varNames = [...block[1].matchAll(/(\w+)/g)].map((x) => x[1]);
+  return varNames.map((varName) => {
+    const decl = squadrantdText.match(new RegExp(`const\\s+${escapeRe(varName)}\\s*=\\s*new\\s+(\\w+)\\(`));
+    return decl ? decl[1] : varName;
+  });
+}
+
+function extractClaudeMdClaim(claudeMdText) {
+  const m = claudeMdText.match(/(\d+)\s+`LifecycleSource`\s+implementations/);
+  return m ? Number(m[1]) : null;
+}
+
+function buildTable() {
+  const controlTypesText = readFileSync(CONTROL_TYPES_FILE, "utf8");
+  const stateMachineText = readFileSync(STATE_MACHINE_FILE, "utf8");
+  const reduceText = readFileSync(REDUCE_FILE, "utf8");
+  const telegramText = readFileSync(TELEGRAM_FORMAT_FILE, "utf8");
+  const squadrantdText = readFileSync(SQUADRANTD_FILE, "utf8");
+  const claudeMdText = existsSync(CLAUDE_MD_FILE) ? readFileSync(CLAUDE_MD_FILE, "utf8") : "";
+
+  const variants = extractVariants(controlTypesText);
+  const sourceFiles = walkSourceFiles(PACKAGES_DIR);
+  const knownEventTypes = extractKnownEventTypes(reduceText);
+
+  const rows = variants.map((variant) => {
+    const producers = findProducers(sourceFiles, variant);
+    const zombie = producers.length === 0;
+    const allowedZombie = KNOWN_ZERO_PRODUCER.includes(variant);
+    return {
+      variant,
+      producers,
+      stateMachine: hasCase(stateMachineText, variant),
+      reduceAllowlist: knownEventTypes.has(variant),
+      telegramFormatter: hasCase(telegramText, variant),
+      zombie,
+      allowedZombie,
+    };
+  });
+
+  const unauthorizedZombies = rows.filter((r) => r.zombie && !r.allowedZombie).map((r) => r.variant);
+  const staleAllowlistEntries = KNOWN_ZERO_PRODUCER.filter(
+    (v) => !rows.some((r) => r.variant === v && r.zombie),
+  );
+
+  const registeredSources = extractLifecycleSources(squadrantdText);
+  const claudeMdClaim = extractClaudeMdClaim(claudeMdText);
+
+  const lines = [];
+  lines.push("<!-- GENERATED by scripts/control-event-table.mjs — do not hand-edit. -->");
+  lines.push("<!-- Regenerate: node scripts/control-event-table.mjs -->");
+  lines.push("");
+  lines.push("# ControlEvent producer/consumer table");
+  lines.push("");
+  lines.push(
+    "Every `ControlEvent` variant (`packages/shared/src/types/control.ts`) against its shipped " +
+      "producers and consumers. ⚠ marks a variant with zero shipped producers — see " +
+      "`docs/specs/2026-08-29-event-architecture-design.md` §1.5 / §11.",
+  );
+  lines.push("");
+  lines.push("| Variant | Producers | state-machine.ts | reduce.ts allowlist | telegram formatter |");
+  lines.push("|---|---|---|---|---|");
+  for (const r of rows) {
+    const variantCell = r.zombie ? `⚠ \`${r.variant}\`` : `\`${r.variant}\``;
+    const producerCell = r.zombie ? "0 (known zombie)" : String(r.producers.length);
+    lines.push(
+      `| ${variantCell} | ${producerCell} | ${r.stateMachine ? "✓" : "—"} | ${
+        r.reduceAllowlist ? "✓" : "—"
+      } | ${r.telegramFormatter ? "✓" : "—"} |`,
+    );
+  }
+  lines.push("");
+  lines.push("## Producer sites");
+  lines.push("");
+  for (const r of rows) {
+    if (r.producers.length === 0) continue;
+    lines.push(`- \`${r.variant}\``);
+    for (const hit of r.producers) lines.push(`  - ${hit}`);
+  }
+  lines.push("");
+  lines.push("## Known zero-producer variants (allowlisted)");
+  lines.push("");
+  if (KNOWN_ZERO_PRODUCER.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const v of KNOWN_ZERO_PRODUCER) lines.push(`- \`${v}\``);
+  }
+  lines.push("");
+  lines.push("## LifecycleSource implementations");
+  lines.push("");
+  lines.push(`Registered in \`packages/cli/src/squadrantd.ts\` (\`ctx.lifecycleSources\`): **${registeredSources.length}**`);
+  lines.push("");
+  for (const cls of registeredSources) lines.push(`- \`${cls}\``);
+  lines.push("");
+  lines.push(
+    `CLAUDE.md claims: **${claudeMdClaim === null ? "not found" : claudeMdClaim}** ${
+      claudeMdClaim === registeredSources.length ? "(matches ✓)" : "(⚠ DRIFT — does not match)"
+    }`,
+  );
+  lines.push("");
+
+  const content = lines.join("\n");
+  return { content, unauthorizedZombies, staleAllowlistEntries, registeredSources, claudeMdClaim };
+}
+
+function main() {
+  const check = process.argv.includes("--check");
+  const { content, unauthorizedZombies, staleAllowlistEntries } = buildTable();
+
+  let failed = false;
+
+  if (unauthorizedZombies.length > 0) {
+    console.error(
+      `control-event-table: new zero-producer ControlEvent variant(s) not in KNOWN_ZERO_PRODUCER: ${unauthorizedZombies.join(", ")}`,
+    );
+    console.error("Either add a producer, or deliberately add the variant to KNOWN_ZERO_PRODUCER in scripts/control-event-table.mjs.");
+    failed = true;
+  }
+
+  if (staleAllowlistEntries.length > 0) {
+    console.error(
+      `control-event-table: KNOWN_ZERO_PRODUCER lists variant(s) that now have a producer — remove from the allowlist: ${staleAllowlistEntries.join(", ")}`,
+    );
+    failed = true;
+  }
+
+  if (check) {
+    const onDisk = existsSync(OUT_FILE) ? readFileSync(OUT_FILE, "utf8") : null;
+    if (onDisk !== content) {
+      console.error(`control-event-table: ${OUT_FILE} is stale. Run: node scripts/control-event-table.mjs`);
+      failed = true;
+    }
+    process.exit(failed ? 1 : 0);
+  }
+
+  writeFileSync(OUT_FILE, content);
+  console.log(`control-event-table: wrote ${relative(ROOT, OUT_FILE)}`);
+  process.exit(failed ? 1 : 0);
+}
+
+main();

package/templates/captain.claude.md

@@ -9,6 +9,7 @@ You are a **project captain** for Squadrant. You lead ONE project. You are a **c
 3. Even a one-line fix gets a crew session. You plan, delegate, review.
 4. **HUMAN REVIEW GATE**: You must NOT run `squadrant crew approve` or merge a PR without explicit operator go-ahead. The default is pause-and-show-the-diff. Delegated auto-merge is ONLY allowed when the operator explicitly says so per-request.
 5. **ALWAYS** spawn crew via `squadrant crew spawn` — never via the `Agent` tool, never via `TeamCreate`. Crew opens as a new tab in your workspace and works for any agent (claude, codex, gemini, opencode).
+6. If a question you asked resolves without a human answer (e.g. a synthetic 'No response after Ns — continued without an answer' from an AFK timeout), never treat it as approval. Take only the safe, reversible option; if none exists, take no action and report that you are still waiting.
 
 ## ALWAYS do on session start
 

package/templates/captain.generic.md

@@ -23,6 +23,7 @@ You are a project captain coordinating work via cmux workspaces. You are a coord
    ```
 5. **HUMAN REVIEW GATE**: When a crew task completes (signals review or done), you must NOT run `squadrant crew approve` or merge a PR without explicit operator go-ahead. The default is pause-and-show-the-diff. Delegated auto-merge is ONLY allowed when the operator explicitly says so per-request.
 6. Record learnings (script: `~/.config/squadrant/scripts/record-learning.sh`).
+7. If a question you asked resolves without a human answer (e.g. a synthetic 'No response after Ns — continued without an answer' from an AFK timeout), never treat it as approval. Take only the safe, reversible option; if none exists, take no action and report that you are still waiting.
 
 ## Crew Spawning
 

package/templates/crew.claude.md

@@ -10,6 +10,8 @@ You are a crew member working on a specific task within a git worktree.
 4. You do NOT create Agent Teams (no nested teams).
 5. When your task is complete, report back to your captain.
 6. Commit your work to your worktree branch frequently.
+7. Never write to a captain's memory directory or MEMORY.md — propose durable learnings in your done message instead.
+8. If a question you asked resolves without a human answer (e.g. a synthetic 'No response after Ns — continued without an answer' from an AFK timeout), never treat it as approval. Take only the safe, reversible option; if none exists, take no action and report that you are still waiting.
 
 ## Your Worktree
 

package/templates/crew.generic.md

@@ -10,6 +10,8 @@ If asked "who are you?", answer that you are a crew member working on an assigne
 2. You are a single agent session working alone on your task. Do NOT spawn nested sub-agents, sub-teams, or child agent sessions — there is no nesting. Complete the work yourself in this session.
 3. When your task is complete, commit your work and report back.
 4. Commit your work frequently with descriptive messages.
+5. Never write to a captain's memory directory or MEMORY.md — propose durable learnings in your done message instead.
+6. If a question you asked resolves without a human answer (e.g. a synthetic 'No response after Ns — continued without an answer' from an AFK timeout), never treat it as approval. Take only the safe, reversible option; if none exists, take no action and report that you are still waiting.
 
 ## Your Worktree
 

package/templates/crew.opencode.md

@@ -10,6 +10,8 @@ If asked "who are you?", answer that you are a crew member working on an assigne
 2. You are a single agent session working alone on your task. Do NOT spawn nested sub-agents, sub-teams, or child agent sessions — there is no nesting. Complete the work yourself in this session.
 3. When your task is complete, commit your work and report back.
 4. Commit your work frequently with descriptive messages.
+5. Never write to a captain's memory directory or MEMORY.md — propose durable learnings in your done message instead.
+6. If a question you asked resolves without a human answer (e.g. a synthetic 'No response after Ns — continued without an answer' from an AFK timeout), never treat it as approval. Take only the safe, reversible option; if none exists, take no action and report that you are still waiting.
 
 ## Your Worktree