muonroi-cli 1.3.4 → 1.4.1

package/dist/src/ee/transcript-emit.js

@@ -0,0 +1,140 @@
+/**
+ * Transcript emit — resilient sidecar to extractSession.
+ *
+ * Writes the in-memory ModelMessage[] of the current session to a JSONL file
+ * under `~/.experience/muonroi-cli-sessions/{sessionId}.jsonl` using the SAME
+ * shape that Claude Code's `~/.claude/projects/*.jsonl` uses (one entry per
+ * message with `{ message: { role, content: [...blocks] } }`).
+ *
+ * Why this exists alongside extract-session.ts:
+ * - extractSession() POSTs directly to EE /api/extract — fast path, depends on
+ *   the engine being up at the moment of session-end / clear / compact.
+ * - This module is the SLOW PATH: dump-to-disk so the EE stop-extractor
+ *   backfill loop can pick the file up later, even if:
+ *     1. EE was offline at session-end (network blip, engine restart),
+ *     2. user closed the terminal with X (Node exits before HTTP fires),
+ *     3. user ran /compact (we want lessons from the compacted history too).
+ *
+ * The output mirrors Claude's JSONL shape so the existing
+ * stop-extractor `buildClaudeSessionData()` parser handles it unmodified —
+ * we just add a new scan path.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function experienceRoot() {
+    return path.join(os.homedir(), ".experience");
+}
+function emitRoot() {
+    return path.join(experienceRoot(), "muonroi-cli-sessions");
+}
+const MAX_BLOCK_CHARS = 8000;
+/**
+ * Gate: only emit when the user has opted into the experience engine by
+ * creating `~/.experience/config.json`. A fresh clone of muonroi-cli on a
+ * machine with no EE installed must NOT create `~/.experience/` — that would
+ * be silent filesystem litter for a feature the user did not install.
+ * Override with `MUONROI_DISABLE_TRANSCRIPT_EMIT=1` to force-disable even when
+ * EE is installed (e.g. for CI runs).
+ */
+function isEnabled() {
+    if (process.env.MUONROI_DISABLE_TRANSCRIPT_EMIT === "1")
+        return false;
+    try {
+        return fs.existsSync(path.join(experienceRoot(), "config.json"));
+    }
+    catch {
+        return false;
+    }
+}
+function ensureDir(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        /* fail-open */
+    }
+}
+function clip(s) {
+    if (s.length <= MAX_BLOCK_CHARS)
+        return s;
+    return `${s.slice(0, MAX_BLOCK_CHARS)}... [truncated ${s.length - MAX_BLOCK_CHARS} chars]`;
+}
+function normalizeContent(content) {
+    if (typeof content === "string")
+        return [{ type: "text", text: clip(content) }];
+    if (!Array.isArray(content))
+        return [];
+    const out = [];
+    for (const part of content) {
+        if (!part || typeof part !== "object")
+            continue;
+        const p = part;
+        if (p.type === "text" && typeof p.text === "string") {
+            out.push({ type: "text", text: clip(p.text) });
+            continue;
+        }
+        if ((p.type === "tool-call" || p.type === "tool_call") && p.toolName) {
+            out.push({ type: "tool_use", name: p.toolName, input: p.input ?? {} });
+            continue;
+        }
+        if (p.type === "tool-result" || p.type === "tool_result") {
+            const body = p.output ?? p.result ?? "";
+            out.push({ type: "tool_result", content: clip(typeof body === "string" ? body : JSON.stringify(body)) });
+        }
+    }
+    return out;
+}
+function toJsonlEntry(msg, reason) {
+    const role = msg.role;
+    if (role !== "user" && role !== "assistant" && role !== "tool" && role !== "system")
+        return null;
+    const content = normalizeContent(msg.content);
+    if (content.length === 0)
+        return null;
+    return {
+        message: { role, content },
+        ts: new Date().toISOString(),
+        source: "muonroi-cli",
+        reason,
+    };
+}
+/**
+ * Emit the session transcript to disk for later EE backfill.
+ *
+ * Returns the path written to, or null if no eligible content / sessionId.
+ * All errors swallowed — this is best-effort, never blocks shutdown.
+ */
+export function emitTranscriptToDisk(messages, sessionId, reason, cwd) {
+    try {
+        if (!isEnabled())
+            return null;
+        if (!sessionId)
+            return null;
+        if (!Array.isArray(messages) || messages.length === 0)
+            return null;
+        const entries = messages.map((m) => toJsonlEntry(m, reason)).filter((e) => e !== null);
+        if (entries.length === 0)
+            return null;
+        ensureDir(emitRoot());
+        const reasonSuffix = reason === "cli-exit" ? "" : `.${reason}`;
+        const filename = `${sessionId}${reasonSuffix}.jsonl`;
+        const target = path.join(emitRoot(), filename);
+        const meta = {
+            type: "session_meta",
+            cwd: cwd ? cwd.replace(/\\/g, "/") : null,
+            runtime: "muonroi-cli",
+            ts: new Date().toISOString(),
+        };
+        const lines = [JSON.stringify(meta), ...entries.map((e) => JSON.stringify(e))];
+        fs.writeFileSync(target, `${lines.join("\n")}\n`, "utf8");
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
+export function getEmitRoot() {
+    return emitRoot();
+}
+//# sourceMappingURL=transcript-emit.js.map

package/dist/src/ee/types.d.ts

@@ -193,8 +193,15 @@ export interface ExtractRequest {
     meta?: {
         sessionId?: string;
         tenantId?: string;
-        source?: "cli-exit" | "cli-clear" | "hook-stop";
+        source?: "cli-exit" | "cli-clear" | "hook-stop" | "cli-compact" | "cli-compact-checkpoint" | "tool-artifact";
         scope?: string;
+        iteration?: number;
+        tokensBefore?: number;
+        toolCallId?: string;
+        toolName?: string;
+        reason?: string;
+        elidedAtStep?: number;
+        [k: string]: unknown;
     };
 }
 export interface ExtractResponse {
@@ -329,6 +336,28 @@ export interface EESearchOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
 }
+export interface EERecallEntry {
+    id: string;
+    collection: string | null;
+}
+export interface EERecallResponse {
+    /** Formatted recall index carrying `[id col]` handles (null when nothing matched). */
+    text: string | null;
+    entries: EERecallEntry[];
+    count: number;
+    query?: string;
+}
+export interface EERecallOptions {
+    /** Scope hint → body.project_slug (advisory under recallMode). */
+    project?: string;
+    /** Working dir → body.cwd (server derives project_slug + attribution). */
+    cwd?: string;
+    /** Stable session id → body.sourceSession (slice-2 stitch detection). */
+    sourceSession?: string;
+    /** Override per-call timeout. Defaults to 15000ms — server bounds recall at ~8s internally; allow margin for embed + 3-leg search + network. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
 export interface EEUserResponse {
     user: string;
 }
@@ -342,6 +371,11 @@ export interface EEClient {
     routeModel(req: RouteModelRequest, signal?: AbortSignal): Promise<RouteModelResponse | null>;
     coldRoute(req: ColdRouteRequest, signal?: AbortSignal): Promise<ColdRouteResponse | null>;
     feedback(payload: FeedbackPayload): void;
+    noiseFeedback(payload: {
+        pointId: string;
+        collection: string;
+        reason: "wrong_repo" | "wrong_language" | "wrong_task" | "stale_rule";
+    }): void;
     touch(principle_uuid: string, tenantId: string): void;
     routeFeedback(payload: RouteFeedbackPayload): void;
     promptStale(req: PromptStaleRequest): Promise<PromptStaleResponse | null>;
@@ -355,6 +389,8 @@ export interface EEClient {
     importPrinciple(data: unknown): Promise<EEImportResponse | null>;
     routeTask(req: RouteTaskRequest): Promise<RouteTaskResponse | null>;
     search(query: string, opts?: EESearchOptions | number): Promise<EESearchResponse | null>;
+    /** Active recall via /api/recall (recallMode). Returns [id col] index + records a surface. */
+    recall(query: string, opts?: EERecallOptions): Promise<EERecallResponse | null>;
     user(): Promise<EEUserResponse | null>;
     brainProxy(prompt: string, timeoutMs?: number): Promise<string | null>;
     pilContext(prompt: string, options?: {

package/dist/src/flow/__tests__/migration.test.js

@@ -9,7 +9,7 @@ describe("migration", () => {
         tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-migrate-"));
     });
     afterEach(async () => {
-        await fs.rm(tmpDir, { recursive: true, force: true });
+        await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
     });
     describe("detectLegacyFlow", () => {
         it("returns true when .quick-codex-flow/ exists", async () => {

package/dist/src/flow/__tests__/run-manager-product.test.js

@@ -9,7 +9,7 @@ describe("run-manager product extension", () => {
         tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "muonroi-flow-test-"));
     });
     afterEach(async () => {
-        await fs.rm(tmpDir, { recursive: true, force: true });
+        await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
     });
     it("should create 6 files in createRun", async () => {
         const run = await createRun(tmpDir);

package/dist/src/flow/__tests__/run-manager.test.js

@@ -13,7 +13,7 @@ describe("run-manager", () => {
         flowDir = await ensureFlowDir(tmpDir);
     });
     afterEach(async () => {
-        await fs.rm(tmpDir, { recursive: true, force: true });
+        await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
     });
     describe("createRun", () => {
         it("creates runs/<id>/ with roadmap.md, state.md, delegations.md, gray-areas.md", async () => {

package/dist/src/flow/__tests__/scaffold-checkpoint.test.js

@@ -11,7 +11,7 @@ beforeEach(async () => {
     cwd = await fs.mkdtemp(path.join(os.tmpdir(), "muonroi-checkpoint-"));
 });
 afterEach(async () => {
-    await fs.rm(cwd, { recursive: true, force: true });
+    await fs.rm(cwd, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
 });
 const baseInputs = {
     projectName: "todo-app",
@@ -87,7 +87,7 @@ describe("scaffold-checkpoint", () => {
     it("listResumable returns empty array when flow dir missing", async () => {
         const empty = await fs.mkdtemp(path.join(os.tmpdir(), "muonroi-empty-"));
         expect(await listResumableScaffoldCheckpoints(empty)).toEqual([]);
-        await fs.rm(empty, { recursive: true, force: true });
+        await fs.rm(empty, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
     });
 });
 //# sourceMappingURL=scaffold-checkpoint.test.js.map

package/dist/src/flow/__tests__/scaffold.test.js

@@ -9,7 +9,7 @@ describe("scaffold", () => {
         tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-scaffold-"));
     });
     afterEach(async () => {
-        await fs.rm(tmpDir, { recursive: true, force: true });
+        await fs.rm(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
     });
     it("FLOW_DIR_NAME equals .muonroi-flow", () => {
         expect(FLOW_DIR_NAME).toBe(".muonroi-flow");

package/dist/src/flow/__tests__/warning-persist.test.js

@@ -18,7 +18,7 @@ async function makeTempDir(prefix) {
 }
 afterEach(async () => {
     for (const d of tempDirs) {
-        await rm(d, { recursive: true, force: true }).catch(() => { });
+        await rm(d, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }).catch(() => { });
     }
     tempDirs = [];
 });

package/dist/src/generated/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PACKAGE_VERSION = "1.3.4";
+export declare const PACKAGE_VERSION = "1.4.1";
 export declare const PACKAGE_DESCRIPTION = "BYOK AI coding agent with multi-model council debate, role-based routing, and auto-compact.";

package/dist/src/generated/version.js

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by scripts/sync-version.cjs. DO NOT EDIT BY HAND.
 // Sourced from package.json at build time so it survives bun --compile bundling.
-export const PACKAGE_VERSION = "1.3.4";
+export const PACKAGE_VERSION = "1.4.1";
 export const PACKAGE_DESCRIPTION = "BYOK AI coding agent with multi-model council debate, role-based routing, and auto-compact.";
 //# sourceMappingURL=version.js.map

package/dist/src/gsd/__tests__/directives.test.js

@@ -24,6 +24,41 @@ describe("buildDirective", () => {
         expect(out.blocking).toBe(false);
         expect(out.text).toMatch(/GSD-quick/i);
     });
+    it("emits a fix-first debug variant when phase is debug (session 7d56a049e1e3 regression)", () => {
+        const complexity = scoreComplexity("fix CI fail");
+        const out = buildDirective({ complexity, phase: "debug", grayAreas: [] });
+        expect(out.tier).toBe("standard");
+        expect(out.text).toMatch(/DEBUG task/);
+        expect(out.text).toMatch(/FIX-FIRST/);
+        expect(out.text).toMatch(/≤ 8 read_file/);
+        expect(out.text).toMatch(/edit_file/);
+    });
+    it("standard non-debug phases use the generic GSD-quick directive (regression: don't apply fix-first cap to plan/execute)", () => {
+        const complexity = scoreComplexity("add a counter feature");
+        const out = buildDirective({ complexity, phase: "execute", grayAreas: [] });
+        expect(out.text).not.toMatch(/FIX-FIRST/);
+        expect(out.text).not.toMatch(/read_file calls before/);
+    });
+    it("emits a human-facing question directive for informational/meta prompts (session 829a83888dd2)", () => {
+        // A self/meta CLI question routed through GSD must NOT get the
+        // implement/verify scaffold — that leaked a "2-3 line plan" preamble +
+        // process narration into the human-facing answer.
+        const complexity = scoreComplexity("how does this CLI affect you?");
+        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true });
+        expect(out.blocking).toBe(false);
+        expect(out.text).toMatch(/QUESTION \/ explanatory/);
+        expect(out.text).toMatch(/written for the HUMAN/);
+        expect(out.text).not.toMatch(/2-3 line plan/);
+        expect(out.text).not.toMatch(/Implement directly/);
+    });
+    it("informational overrides even a heavy tier (a question never implements)", () => {
+        const complexity = scoreComplexity("redo the entire architecture and map everything across all repos");
+        expect(complexity.tier).toBe("heavy");
+        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true });
+        expect(out.blocking).toBe(false);
+        expect(out.text).toMatch(/QUESTION \/ explanatory/);
+        expect(out.text).not.toMatch(/MANDATORY/);
+    });
     it("emits a minimal quick directive", () => {
         const complexity = scoreComplexity("fix typo");
         const out = buildDirective({ complexity, phase: null, grayAreas: [] });

package/dist/src/gsd/__tests__/types.test.js

@@ -7,7 +7,8 @@ describe("GSD types", () => {
         expect(GSD_PHASES).toContain("execute");
         expect(GSD_PHASES).toContain("verify");
         expect(GSD_PHASES).toContain("review");
-        expect(GSD_PHASES.length).toBe(5);
+        expect(GSD_PHASES).toContain("debug");
+        expect(GSD_PHASES.length).toBe(6);
     });
     it("isGsdPhase returns true for valid phases", () => {
         expect(isGsdPhase("discuss")).toBe(true);
@@ -15,6 +16,18 @@ describe("GSD types", () => {
         expect(isGsdPhase("execute")).toBe(true);
         expect(isGsdPhase("verify")).toBe(true);
         expect(isGsdPhase("review")).toBe(true);
+        expect(isGsdPhase("debug")).toBe(true);
+    });
+    it("detectGsdPhase routes fix/debug language to debug phase (session 127140a47b56)", () => {
+        // Position-based detection: when a debug keyword appears first, debug wins.
+        expect(detectGsdPhase("fix CI fail")).toBe("debug");
+        expect(detectGsdPhase("fix lỗi và check lại CI")).toBe("debug");
+        expect(detectGsdPhase("sửa bug này giúp tôi")).toBe("debug");
+        expect(detectGsdPhase("debug this crash")).toBe("debug");
+        // The exact session 127140a47b56 prompt — "fix" beats later "check".
+        expect(detectGsdPhase("action github đang run fail check và fix cho tôi")).toBe("debug");
+        // Without explicit debug keywords, "check" still falls through to verify.
+        expect(detectGsdPhase("check that this works")).toBe("verify");
     });
     it("isGsdPhase returns false for invalid strings", () => {
         expect(isGsdPhase("unknown")).toBe(false);

package/dist/src/gsd/directives.d.ts

@@ -21,6 +21,16 @@ export interface DirectiveInput {
     complexity: ComplexityResult;
     phase: GsdPhase | null;
     grayAreas: GrayAreaQuestion[];
+    /**
+     * True when the prompt is informational/explanatory (a question or a
+     * self/meta analysis) rather than a request to change code. The deliverable
+     * is an ANSWER, not a diff — so the implement/verify flow is nonsensical and
+     * (live repro, session 829a83888dd2) leaks into the user-facing reply as a
+     * "2-3 line plan" preamble + process narration ("per contract 2/5/7", "emit
+     * respond_general"), agent-ifying an answer meant for a human. When set,
+     * buildDirective emits a human-facing question directive instead.
+     */
+    informational?: boolean;
 }
 export interface DirectiveOutput {
     text: string;

package/dist/src/gsd/directives.js

@@ -46,26 +46,62 @@ function buildHeavy(input) {
 }
 function buildStandard(input) {
     const phaseHint = input.phase ? ` (detected phase: ${input.phase})` : "";
+    // Debug-phase variant: tighten exploration budget. Session 7d56a049e1e3
+    // ran 109 tool calls (58 bash + 33 read_file + 16 grep + 2 mcp) over 6
+    // minutes WITHOUT a single edit_file / write_file — agent over-researched
+    // the CI failure instead of attempting a fix. Add an explicit exploration
+    // cap and require committing to a hypothesis early.
+    if (input.phase === "debug") {
+        return [
+            `${HEADER} DEBUG task${phaseHint} — apply GSD-quick mindset, FIX-FIRST.`,
+            "Flow:",
+            "  1. State a 2-3 line hypothesis (what is failing, your best guess of why) BEFORE reading more than 3 files.",
+            "  2. Apply the smallest plausible fix with edit_file / write_file. Do NOT keep exploring — commit to a hypothesis, ship the diff, iterate on failure.",
+            "  3. Verify the fix (rerun the failing command / test) and report evidence.",
+            "Hard limits — exceed only if a tool result genuinely contradicts your hypothesis:",
+            "  - ≤ 8 read_file calls before first edit_file",
+            "  - ≤ 5 grep calls before first edit_file",
+            "  - ≤ 10 bash log-fetching calls (gh run view, cat log, etc.) before first edit_file",
+            "If hard limits are blown and you still have no fix, STOP and report what you tried + why you're stuck. Do NOT keep searching.",
+        ].join("\n");
+    }
     return [
         `${HEADER} STANDARD task${phaseHint} — apply GSD-quick mindset.`,
         "Flow:",
-        "  1. State a 2–3 line plan in your reply.",
+        "  1. State a 2-3 line plan in your reply.",
         "  2. Implement directly with the appropriate tools.",
         "  3. Verify (tests / type-check / quick smoke) and report evidence.",
         "Skip the discuss/research subagent dance unless a real ambiguity blocks step 1.",
     ].join("\n");
 }
+function buildQuestion() {
+    // Informational / question / meta-analysis turns. The deliverable is the
+    // answer itself — there is no code to implement or test. Keep the agent's
+    // process OUT of the reply: a human asked, a human reads the result.
+    return [
+        `${HEADER} QUESTION / explanatory request — no code change is being asked for.`,
+        "Answer it directly and completely, written for the HUMAN who asked:",
+        "  1. Investigate only as needed — read/grep the specific files that ground your answer this turn.",
+        "  2. Lead with the answer. Use clear prose + structure (headings, bullets). Where a claim rests on the code, cite a concise file:line inline.",
+        "  3. Do NOT output an implementation plan, do NOT narrate your own process or restate these instructions, and do NOT name internal layers / contract rules / tools as if the reader were the agent.",
+        "There is no implement/verify step — the answer is the deliverable.",
+    ].join("\n");
+}
 function buildQuick(input) {
     const phaseHint = input.phase ? ` phase=${input.phase}` : "";
     return `${HEADER} QUICK task${phaseHint} — handle inline. No plan, no subagents. Make the smallest correct change and report.`;
 }
 export function buildDirective(input) {
+    // Informational/meta prompts answer a human — never apply the
+    // implement/verify scaffold (it agent-ifies the reply), regardless of tier.
+    if (input.informational) {
+        return { text: buildQuestion(), tier: input.complexity.tier, blocking: false };
+    }
     switch (input.complexity.tier) {
         case "heavy":
             return { text: buildHeavy(input), tier: "heavy", blocking: true };
         case "standard":
             return { text: buildStandard(input), tier: "standard", blocking: false };
-        case "quick":
         default:
             return { text: buildQuick(input), tier: "quick", blocking: false };
     }

package/dist/src/gsd/gray-areas.js

@@ -85,7 +85,7 @@ export function detectGrayAreas(prompt) {
     }
     const questions = [];
     for (const rule of RULES) {
-        const specified = (rule.present && rule.present.test(prompt)) || (rule.missing && !rule.missing.test(prompt));
+        const specified = rule.present?.test(prompt) || (rule.missing && !rule.missing.test(prompt));
         if (!specified) {
             questions.push(rule.build(prompt));
             if (questions.length >= MAX_QUESTIONS)

package/dist/src/gsd/types.d.ts

@@ -1,4 +1,4 @@
-export declare const GSD_PHASES: readonly ["discuss", "plan", "execute", "verify", "review"];
+export declare const GSD_PHASES: readonly ["discuss", "plan", "execute", "verify", "review", "debug"];
 export type GsdPhase = (typeof GSD_PHASES)[number];
 export type WorkflowKind = "task" | "product";
 export declare function isGsdPhase(value: string): value is GsdPhase;

package/dist/src/gsd/types.js

@@ -1,15 +1,29 @@
-export const GSD_PHASES = ["discuss", "plan", "execute", "verify", "review"];
+export const GSD_PHASES = ["discuss", "plan", "execute", "verify", "review", "debug"];
 export function isGsdPhase(value) {
     return GSD_PHASES.includes(value);
 }
+// PHASE_KEYWORDS notes (session 127140a47b56 root cause):
+// - "debug" is a phase that detection must prefer over "verify" / "execute"
+//   when bug/fail/error language is present. Without it, "fix CI fail check"
+//   matched "check" → verify, and the agent entered GSD-quick verify flow on
+//   what was actually a debug request.
+// - "fix" is now part of `debug` keywords (was missing); "build" stays in
+//   execute but loses precedence to debug fix-language.
+// - Vietnamese verbs added so multilingual prompts route correctly.
 const PHASE_KEYWORDS = {
-    discuss: ["discuss", "brainstorm", "explore", "think about", "consider"],
-    plan: ["plan", "design", "architect", "outline", "roadmap"],
-    execute: ["execute", "implement", "build", "create", "write", "code", "develop"],
-    verify: ["verify", "validate", "test", "check", "confirm", "ensure"],
-    review: ["review", "audit", "inspect", "examine", "evaluate"],
+    debug: ["debug", "fix", "bug", "broken", "fail", "failing", "error", "crash", "regression", "sửa", "lỗi", "hỏng"],
+    discuss: ["discuss", "brainstorm", "explore", "think about", "consider", "thảo luận"],
+    plan: ["plan", "design", "architect", "outline", "roadmap", "lập kế hoạch"],
+    execute: ["execute", "implement", "build", "create", "write", "code", "develop", "triển khai", "viết"],
+    verify: ["verify", "validate", "test", "check", "confirm", "ensure", "kiểm tra"],
+    review: ["review", "audit", "inspect", "examine", "evaluate", "đánh giá"],
 };
+// PHASE_PRIORITY notes:
+// - debug ranks ABOVE execute and verify. When a prompt contains both "fix"
+//   (debug) and "check" (verify), the debug intent should win — the user is
+//   asking us to fix something, the check is incidental.
 const PHASE_PRIORITY = {
+    debug: 6,
     execute: 5,
     verify: 4,
     discuss: 3,

package/dist/src/headless/__tests__/council-answers.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { createCouncilAutoAnswerer, handleCouncilChunk, parseCouncilAnswersFile } from "../council-answers.js";
+import { createCouncilAutoAnswerer, createHeadlessCouncilAutoAnswerer, handleCouncilChunk, parseCouncilAnswersFile, } from "../council-answers.js";
 function q(over) {
     return {
         questionId: "qid",
@@ -103,6 +103,31 @@ describe("createCouncilAutoAnswerer", () => {
         expect(file.clarify).toEqual(["a", "b"]);
     });
 });
+describe("createHeadlessCouncilAutoAnswerer (headless never hangs)", () => {
+    it("ALWAYS returns an active answerer even with no file and no --yes", () => {
+        // Regression: previously headless gated the answerer on `--yes`, so a prompt
+        // that triggered council without --yes left the responder promise unresolved
+        // and the process hung forever (0 output). Headless has no TUI to answer, so
+        // the answerer must always be present and auto-proceed with the recommended
+        // (defaultIndex) option.
+        const a = createHeadlessCouncilAutoAnswerer({});
+        expect(a).not.toBeNull();
+        const answer = a.answerQuestion(q({
+            phase: "post-debate",
+            defaultIndex: 1,
+            options: [
+                { label: "A", value: "a", kind: "choice" },
+                { label: "B", value: "b", kind: "choice" },
+            ],
+        }));
+        expect(answer).toBe("b"); // recommended (defaultIndex) option
+        expect(a.approvePreflight()).toBe(true);
+    });
+    it("still honors a scripted --council-answers file", () => {
+        const a = createHeadlessCouncilAutoAnswerer({ file: { clarify: ["mongo"] } });
+        expect(a.answerQuestion(q({ phase: "clarify" }))).toBe("mongo");
+    });
+});
 describe("handleCouncilChunk (interception wiring)", () => {
     function makeSink() {
         return {

package/dist/src/headless/council-answers.d.ts

@@ -16,8 +16,8 @@ export interface CouncilAnswersFile {
     /** FIFO queues keyed by phase. Strings are option `value`s or freetext. */
     clarify?: string[];
     preflight?: string[];
-    ["plan-confirm"]?: string[];
-    ["post-debate"]?: string[];
+    "plan-confirm"?: string[];
+    "post-debate"?: string[];
     /** Default approval for every council_preflight chunk. Omitted → true. */
     preflightApprove?: boolean;
 }
@@ -29,6 +29,21 @@ export declare function createCouncilAutoAnswerer(opts: {
     enabled: boolean;
     file?: CouncilAnswersFile;
 }): CouncilAutoAnswerer | null;
+/**
+ * Headless council policy. Headless (`-p` / `--verify`) has NO TUI to render an
+ * askcard, so a council question must never block — otherwise the responder
+ * promise never resolves and the process hangs with zero output (observed
+ * 2026-06-05: a code/analyze prompt that triggers auto-council hung forever
+ * without `--yes`). This always returns an active answerer that auto-proceeds
+ * with the recommended (`defaultIndex`) option and approves preflights. A
+ * `--council-answers` file customizes per-phase answers; `--yes` is implied in
+ * headless mode (no human to confirm), so it is no longer required to avoid the
+ * hang. Each auto-answer is logged to stderr by `handleCouncilChunk` for
+ * cost/decision transparency.
+ */
+export declare function createHeadlessCouncilAutoAnswerer(opts: {
+    file?: CouncilAnswersFile;
+}): CouncilAutoAnswerer;
 /**
  * Sink for the headless interceptor — abstracts the Agent's
  * `respondToCouncilQuestion` / `respondToCouncilPreflight` methods so this

package/dist/src/headless/council-answers.js

@@ -6,6 +6,9 @@ export function createCouncilAutoAnswerer(opts) {
         preflight: [...(opts.file?.preflight ?? [])],
         "plan-confirm": [...(opts.file?.["plan-confirm"] ?? [])],
         "post-debate": [...(opts.file?.["post-debate"] ?? [])],
+        "pil-interview": [],
+        "pil-acceptance": [],
+        "tool-loop-cap": [],
     };
     const preflightApprove = opts.file?.preflightApprove ?? true;
     return {
@@ -21,6 +24,24 @@ export function createCouncilAutoAnswerer(opts) {
         },
     };
 }
+/**
+ * Headless council policy. Headless (`-p` / `--verify`) has NO TUI to render an
+ * askcard, so a council question must never block — otherwise the responder
+ * promise never resolves and the process hangs with zero output (observed
+ * 2026-06-05: a code/analyze prompt that triggers auto-council hung forever
+ * without `--yes`). This always returns an active answerer that auto-proceeds
+ * with the recommended (`defaultIndex`) option and approves preflights. A
+ * `--council-answers` file customizes per-phase answers; `--yes` is implied in
+ * headless mode (no human to confirm), so it is no longer required to avoid the
+ * hang. Each auto-answer is logged to stderr by `handleCouncilChunk` for
+ * cost/decision transparency.
+ */
+export function createHeadlessCouncilAutoAnswerer(opts) {
+    // enabled is forced true: in headless there is no interactive answerer, so
+    // auto-proceeding with recommended defaults is the only non-hanging behavior.
+    // createCouncilAutoAnswerer never returns null when enabled is true.
+    return createCouncilAutoAnswerer({ enabled: true, file: opts.file });
+}
 function defaultAnswerFor(q) {
     if (q.options && q.options.length > 0) {
         const idx = typeof q.defaultIndex === "number" && q.defaultIndex >= 0 && q.defaultIndex < q.options.length