muonroi-cli 1.3.4 → 1.4.1

package/dist/src/orchestrator/scope-reminder.d.ts

@@ -0,0 +1,102 @@
+/**
+ * src/orchestrator/scope-reminder.ts
+ *
+ * Phase 04 / Plan 4A — REQ-005 scope reminder.
+ *
+ * Re-anchors fast-tier cheap models (DeepSeek V4 Flash etc.) to their
+ * original intent at structural cadence so multi-round tool loops do not
+ * drift off-task. The reminder is injected into the tool_result/system
+ * message channel — NOT into the system prompt — because the system prompt
+ * is repeatedly compacted by B3/B4 once cumulative input grows.
+ *
+ * Locked behaviour (04-CONTEXT.md "Scope reminder 4A"):
+ *   - Cadence K: 3 small / 5 medium / 8 large; hard floor K >= 3
+ *   - Format (<= 200 chars):
+ *       [scope-check step N/CEILING — task=TASKTYPE size=SIZE]
+ *       original: "PROMPT_SNIPPET (first 100 chars)"
+ *       still on scope? if no → emit final answer; if yes → continue.
+ *   - Soft-warn fires ONCE per session at step === floor(ceiling * 0.7)
+ *
+ * Wired by both orchestrator loops:
+ *   - src/orchestrator/message-processor.ts (top-level streamText loop)
+ *   - src/orchestrator/stream-runner.ts (sub-agent streamText loop)
+ *
+ * All cadence math is pure. Soft-warn one-shot state lives on
+ * `globalThis.__muonroiSoftWarnFired: Map<sessionId, Set<step>>` to match
+ * the cross-cutting state pattern used by cross-turn-dedup (G3).
+ */
+export type ComplexitySize = "small" | "medium" | "large";
+/** Hard floor for K. Never let cadence drop below this. */
+export declare const SCOPE_REMINDER_FLOOR_K = 3;
+/** Hard cap on the produced reminder string. 4V harness asserts this. */
+export declare const SCOPE_REMINDER_MAX_CHARS = 200;
+/** First-N chars of original prompt embedded in the reminder. */
+export declare const SCOPE_REMINDER_PROMPT_SNIPPET_CHARS = 100;
+/**
+ * Resolve cadence K for a complexity-size. Floor at SCOPE_REMINDER_FLOOR_K
+ * defends against garbage size strings reaching this path at runtime
+ * (e.g. from an older trace replay where the bucket label changed).
+ */
+export declare function cadenceForSize(size: ComplexitySize | string | null | undefined): number;
+/**
+ * True iff `step` is a non-zero multiple of K. step 0 is the pre-loop
+ * boundary — never inject a reminder before the agent has done any work.
+ */
+export declare function shouldInjectReminder(step: number, k: number): boolean;
+/**
+ * One-shot soft-warn guard. Returns true exactly once per session when
+ * `step === floor(ceiling * 0.7)`. Subsequent calls for the same session
+ * (any step) return false.
+ *
+ * State: `globalThis.__muonroiSoftWarnFired: Map<sessionId, true>`
+ * — mirror of the cross-turn-dedup G3 pattern. The map persists for the
+ * lifetime of the CLI process; cleared at process exit.
+ */
+export declare function shouldInjectSoftWarn(step: number, ceiling: number, sessionId: string): boolean;
+/**
+ * One-shot ceiling-crossing guard. Returns true exactly once per session at
+ * the first step strictly past `naturalCeiling`. After that, subsequent calls
+ * for the same session return false — the orchestrator should rely on the
+ * regular cadence reminder (every K steps) to anchor a model that keeps
+ * working past the budget. Without this guard, sessions that went deep past
+ * ceiling (e.g. step 77 / ceiling 6 in session 1f29e238a816) received the
+ * "past natural budget" strong reminder on EVERY step, generating 70+
+ * redundant reminders that bloat tool_result channel and force the model
+ * into a "YES still on scope" loop on every tool call.
+ */
+export declare function shouldInjectCeilingCrossing(step: number, naturalCeiling: number, sessionId: string): boolean;
+export interface BuildScopeReminderOpts {
+    step: number;
+    ceiling: number;
+    taskType: string;
+    size: string;
+    originalPrompt: string;
+}
+/**
+ * Produce the locked reminder string, guaranteed <= SCOPE_REMINDER_MAX_CHARS.
+ * Format reproduced verbatim from 04-CONTEXT.md so 4V harness assertions
+ * (`[scope-check step 3/`, `still on scope?`) match.
+ */
+export declare function buildScopeReminder(opts: BuildScopeReminderOpts): string;
+/**
+ * Append `reminder` to a `messages` array via the tool_result channel.
+ *
+ * Strategy:
+ *   - If the last message has role "tool" with at least one tool-result
+ *     part, append a synthetic tool-result part carrying the reminder text.
+ *     Pairing with an existing assistant tool-call is preserved by reusing
+ *     the last result's `toolCallId` + `toolName` so the AI SDK does not
+ *     drop the message for being orphaned.
+ *   - Otherwise push a fresh `{role:"system", content: reminder}` at end.
+ *
+ * Returns a NEW array. Input is not mutated. When `reminder` is empty the
+ * input is returned by identity (no allocations).
+ */
+export declare function attachReminderToMessages<T>(messages: ReadonlyArray<T>, reminder: string): T[];
+/**
+ * Companion to buildScopeReminder for anti-mù.
+ * Returns a short note (under SCOPE_REMINDER_MAX_CHARS budget when combined) that
+ * tells the agent to self-check against persisted EE checkpoints.
+ * Used by prepareStep / sub-agent paths after compaction.
+ */
+export declare function buildCheckpointReminder(iteration: number, hasEECheckpoint: boolean): string;

package/dist/src/orchestrator/scope-reminder.js

@@ -0,0 +1,221 @@
+/**
+ * src/orchestrator/scope-reminder.ts
+ *
+ * Phase 04 / Plan 4A — REQ-005 scope reminder.
+ *
+ * Re-anchors fast-tier cheap models (DeepSeek V4 Flash etc.) to their
+ * original intent at structural cadence so multi-round tool loops do not
+ * drift off-task. The reminder is injected into the tool_result/system
+ * message channel — NOT into the system prompt — because the system prompt
+ * is repeatedly compacted by B3/B4 once cumulative input grows.
+ *
+ * Locked behaviour (04-CONTEXT.md "Scope reminder 4A"):
+ *   - Cadence K: 3 small / 5 medium / 8 large; hard floor K >= 3
+ *   - Format (<= 200 chars):
+ *       [scope-check step N/CEILING — task=TASKTYPE size=SIZE]
+ *       original: "PROMPT_SNIPPET (first 100 chars)"
+ *       still on scope? if no → emit final answer; if yes → continue.
+ *   - Soft-warn fires ONCE per session at step === floor(ceiling * 0.7)
+ *
+ * Wired by both orchestrator loops:
+ *   - src/orchestrator/message-processor.ts (top-level streamText loop)
+ *   - src/orchestrator/stream-runner.ts (sub-agent streamText loop)
+ *
+ * All cadence math is pure. Soft-warn one-shot state lives on
+ * `globalThis.__muonroiSoftWarnFired: Map<sessionId, Set<step>>` to match
+ * the cross-cutting state pattern used by cross-turn-dedup (G3).
+ */
+/** Hard floor for K. Never let cadence drop below this. */
+export const SCOPE_REMINDER_FLOOR_K = 3;
+/** Locked cadence table per 04-CONTEXT.md. */
+const CADENCE_TABLE = {
+    small: 3,
+    medium: 5,
+    large: 8,
+};
+/** Hard cap on the produced reminder string. 4V harness asserts this. */
+export const SCOPE_REMINDER_MAX_CHARS = 200;
+/** First-N chars of original prompt embedded in the reminder. */
+export const SCOPE_REMINDER_PROMPT_SNIPPET_CHARS = 100;
+/**
+ * Resolve cadence K for a complexity-size. Floor at SCOPE_REMINDER_FLOOR_K
+ * defends against garbage size strings reaching this path at runtime
+ * (e.g. from an older trace replay where the bucket label changed).
+ */
+export function cadenceForSize(size) {
+    const k = CADENCE_TABLE[size];
+    if (typeof k === "number" && k >= SCOPE_REMINDER_FLOOR_K)
+        return k;
+    return SCOPE_REMINDER_FLOOR_K;
+}
+/**
+ * True iff `step` is a non-zero multiple of K. step 0 is the pre-loop
+ * boundary — never inject a reminder before the agent has done any work.
+ */
+export function shouldInjectReminder(step, k) {
+    if (!Number.isFinite(step) || step <= 0)
+        return false;
+    if (!Number.isFinite(k) || k < 1)
+        return false;
+    return step % k === 0;
+}
+/**
+ * One-shot soft-warn guard. Returns true exactly once per session when
+ * `step === floor(ceiling * 0.7)`. Subsequent calls for the same session
+ * (any step) return false.
+ *
+ * State: `globalThis.__muonroiSoftWarnFired: Map<sessionId, true>`
+ * — mirror of the cross-turn-dedup G3 pattern. The map persists for the
+ * lifetime of the CLI process; cleared at process exit.
+ */
+export function shouldInjectSoftWarn(step, ceiling, sessionId) {
+    if (!Number.isFinite(step) || step <= 0)
+        return false;
+    if (!Number.isFinite(ceiling) || ceiling <= 0)
+        return false;
+    const threshold = Math.floor(ceiling * 0.7);
+    if (step !== threshold)
+        return false;
+    const g = globalThis;
+    let fired = g.__muonroiSoftWarnFired;
+    if (!(fired instanceof Map)) {
+        fired = new Map();
+        g.__muonroiSoftWarnFired = fired;
+    }
+    if (fired.has(sessionId))
+        return false;
+    fired.set(sessionId, true);
+    return true;
+}
+/**
+ * One-shot ceiling-crossing guard. Returns true exactly once per session at
+ * the first step strictly past `naturalCeiling`. After that, subsequent calls
+ * for the same session return false — the orchestrator should rely on the
+ * regular cadence reminder (every K steps) to anchor a model that keeps
+ * working past the budget. Without this guard, sessions that went deep past
+ * ceiling (e.g. step 77 / ceiling 6 in session 1f29e238a816) received the
+ * "past natural budget" strong reminder on EVERY step, generating 70+
+ * redundant reminders that bloat tool_result channel and force the model
+ * into a "YES still on scope" loop on every tool call.
+ */
+export function shouldInjectCeilingCrossing(step, naturalCeiling, sessionId) {
+    if (!Number.isFinite(step) || step <= 0)
+        return false;
+    if (!Number.isFinite(naturalCeiling) || naturalCeiling <= 0)
+        return false;
+    if (step <= naturalCeiling)
+        return false;
+    const g = globalThis;
+    let fired = g.__muonroiCeilingCrossingFired;
+    if (!(fired instanceof Map)) {
+        fired = new Map();
+        g.__muonroiCeilingCrossingFired = fired;
+    }
+    if (fired.has(sessionId))
+        return false;
+    fired.set(sessionId, true);
+    return true;
+}
+/**
+ * Produce the locked reminder string, guaranteed <= SCOPE_REMINDER_MAX_CHARS.
+ * Format reproduced verbatim from 04-CONTEXT.md so 4V harness assertions
+ * (`[scope-check step 3/`, `still on scope?`) match.
+ */
+export function buildScopeReminder(opts) {
+    const { step, ceiling, taskType, size, originalPrompt } = opts;
+    const snippetRaw = (originalPrompt ?? "").slice(0, SCOPE_REMINDER_PROMPT_SNIPPET_CHARS);
+    // Escape embedded double quotes so the JSON-looking snippet stays parseable
+    // when an LLM tries to extract it. Backslash itself is NOT escaped because
+    // the snippet is plain prose — repeated escaping would inflate length.
+    const snippet = snippetRaw.replace(/"/g, '\\"');
+    const header = `[scope-check step ${step}/${ceiling} — task=${taskType} size=${size}]`;
+    const middle = `original: "${snippet}"`;
+    // Tail kept short so the 100-char snippet + header always fit under the
+    // 200-char hard cap (4V harness assertion). Spec phrasing "if no → emit
+    // final answer; if yes → continue" inflates this past 60 chars, which
+    // combined with a 50-char header + 100-char snippet overruns 200. The
+    // 4V assertion only cares about "[scope-check step N/" + verbatim
+    // snippet, so the trimmed tail is the minimal-impact concession.
+    const tail = "still on scope? if no, finalize.";
+    const joined = `${header}\n${middle}\n${tail}`;
+    if (joined.length <= SCOPE_REMINDER_MAX_CHARS)
+        return joined;
+    // Defensive hard truncation. Header / tail are bounded by their own
+    // string literals + small ints; only the snippet can blow the budget
+    // when taskType/size labels are pathologically long. Re-derive a smaller
+    // snippet that fits.
+    const fixedOverhead = `[scope-check step ${step}/${ceiling} — task=${taskType} size=${size}]\noriginal: ""\n${tail}`
+        .length;
+    const room = Math.max(0, SCOPE_REMINDER_MAX_CHARS - fixedOverhead);
+    const trimmed = snippet.slice(0, room);
+    const candidate = `${header}\noriginal: "${trimmed}"\n${tail}`;
+    if (candidate.length <= SCOPE_REMINDER_MAX_CHARS)
+        return candidate;
+    // Absolute last resort — hard slice. Better to lose readability than to
+    // exceed the contractual cap that 4V asserts on.
+    return candidate.slice(0, SCOPE_REMINDER_MAX_CHARS);
+}
+/**
+ * Append `reminder` to a `messages` array via the tool_result channel.
+ *
+ * Strategy:
+ *   - If the last message has role "tool" with at least one tool-result
+ *     part, append a synthetic tool-result part carrying the reminder text.
+ *     Pairing with an existing assistant tool-call is preserved by reusing
+ *     the last result's `toolCallId` + `toolName` so the AI SDK does not
+ *     drop the message for being orphaned.
+ *   - Otherwise push a fresh `{role:"system", content: reminder}` at end.
+ *
+ * Returns a NEW array. Input is not mutated. When `reminder` is empty the
+ * input is returned by identity (no allocations).
+ */
+export function attachReminderToMessages(messages, reminder) {
+    if (!reminder)
+        return messages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+        return [{ role: "system", content: reminder }];
+    }
+    const last = messages[messages.length - 1];
+    if (last && last.role === "tool" && Array.isArray(last.content)) {
+        const parts = last.content;
+        // Append reminder text INTO the last tool-result part's output value.
+        // We must NOT create a new tool-result part with a duplicate toolCallId —
+        // AI SDK v6 serializes multi-part `tool` messages into one OpenAI tool
+        // message per part, and duplicate tool_call_id causes DeepSeek/OpenAI to
+        // reject the request with "messages with role 'tool' must be a response
+        // to a preceding message with 'tool_calls'". Mutating the existing part
+        // keeps the 1:1 tool_call ↔ tool_result pairing intact.
+        for (let i = parts.length - 1; i >= 0; i--) {
+            const p = parts[i];
+            if (p.type !== "tool-result")
+                continue;
+            const out_parts = parts.slice();
+            const oldOut = p.output;
+            const oldValue = typeof oldOut?.value === "string" ? oldOut.value : "";
+            out_parts[i] = {
+                ...p,
+                output: { type: "text", value: `${oldValue}\n\n${reminder}` },
+            };
+            const rewritten = { ...last, content: out_parts };
+            const out = messages.slice();
+            out[out.length - 1] = rewritten;
+            return out;
+        }
+    }
+    // Fallback path — push a fresh system-role message.
+    return [...messages, { role: "system", content: reminder }];
+}
+/**
+ * Companion to buildScopeReminder for anti-mù.
+ * Returns a short note (under SCOPE_REMINDER_MAX_CHARS budget when combined) that
+ * tells the agent to self-check against persisted EE checkpoints.
+ * Used by prepareStep / sub-agent paths after compaction.
+ */
+export function buildCheckpointReminder(iteration, hasEECheckpoint) {
+    // Enhanced per anti-mù (ideas 3+4): lighter KEEP_TOOL_IDS + on-demand artifact fetch.
+    const base = `[checkpoint status iter=${iteration}${hasEECheckpoint ? " (EE persisted)" : ""}] Task finished? Emit PRESERVE or KEEP_TOOL_IDS: id1,id2. High-value elided? Use ee_query tool with "tool-artifact id=XXX".`;
+    if (base.length <= 220)
+        return base;
+    return base.slice(0, 220);
+}
+//# sourceMappingURL=scope-reminder.js.map

package/dist/src/orchestrator/scope-reminder.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * src/orchestrator/scope-reminder.test.ts
+ *
+ * Phase 04 / Plan 4A — REQ-005 scope reminder cadence + format + soft-warn.
+ *
+ * Locked behaviour per 04-CONTEXT.md (Scope reminder 4A):
+ *   - Cadence K: 3 small / 5 medium / 8 large; hard floor K >= 3
+ *   - Format (<=200 chars):
+ *       [scope-check step N/CEILING — task=TASKTYPE size=SIZE]
+ *       original: "PROMPT_SNIPPET (first 100 chars)"
+ *       still on scope? if no → emit final answer; if yes → continue.
+ *   - Soft-warn fires ONCE per session at step === floor(ceiling * 0.7)
+ *   - Reminder lives in tool_result/system message — never in system prompt
+ */
+export {};

package/dist/src/orchestrator/scope-reminder.test.js

@@ -0,0 +1,204 @@
+/**
+ * src/orchestrator/scope-reminder.test.ts
+ *
+ * Phase 04 / Plan 4A — REQ-005 scope reminder cadence + format + soft-warn.
+ *
+ * Locked behaviour per 04-CONTEXT.md (Scope reminder 4A):
+ *   - Cadence K: 3 small / 5 medium / 8 large; hard floor K >= 3
+ *   - Format (<=200 chars):
+ *       [scope-check step N/CEILING — task=TASKTYPE size=SIZE]
+ *       original: "PROMPT_SNIPPET (first 100 chars)"
+ *       still on scope? if no → emit final answer; if yes → continue.
+ *   - Soft-warn fires ONCE per session at step === floor(ceiling * 0.7)
+ *   - Reminder lives in tool_result/system message — never in system prompt
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { attachReminderToMessages, buildScopeReminder, cadenceForSize, shouldInjectCeilingCrossing, shouldInjectReminder, shouldInjectSoftWarn, } from "./scope-reminder.js";
+describe("cadenceForSize", () => {
+    it("locks 3/5/8 for small/medium/large with hard floor >= 3", () => {
+        expect(cadenceForSize("small")).toBe(3);
+        expect(cadenceForSize("medium")).toBe(5);
+        expect(cadenceForSize("large")).toBe(8);
+    });
+    it("defends the K >= 3 hard floor against unknown sizes", () => {
+        // Cast through unknown — the public contract is "small"|"medium"|"large"
+        // but a caller can still pass garbage at runtime. Floor must hold.
+        expect(cadenceForSize("tiny")).toBeGreaterThanOrEqual(3);
+    });
+});
+describe("shouldInjectReminder", () => {
+    it("returns true at every multiple of K, false elsewhere", () => {
+        expect(shouldInjectReminder(0, 3)).toBe(false); // step 0 is pre-loop
+        expect(shouldInjectReminder(1, 3)).toBe(false);
+        expect(shouldInjectReminder(2, 3)).toBe(false);
+        expect(shouldInjectReminder(3, 3)).toBe(true);
+        expect(shouldInjectReminder(4, 3)).toBe(false);
+        expect(shouldInjectReminder(5, 3)).toBe(false);
+        expect(shouldInjectReminder(6, 3)).toBe(true);
+        expect(shouldInjectReminder(9, 3)).toBe(true);
+    });
+    it("works for K=5 (medium) and K=8 (large)", () => {
+        expect(shouldInjectReminder(5, 5)).toBe(true);
+        expect(shouldInjectReminder(10, 5)).toBe(true);
+        expect(shouldInjectReminder(7, 5)).toBe(false);
+        expect(shouldInjectReminder(8, 8)).toBe(true);
+        expect(shouldInjectReminder(16, 8)).toBe(true);
+        expect(shouldInjectReminder(9, 8)).toBe(false);
+    });
+    it("never fires for non-positive step", () => {
+        expect(shouldInjectReminder(-1, 3)).toBe(false);
+        expect(shouldInjectReminder(0, 3)).toBe(false);
+    });
+});
+describe("shouldInjectSoftWarn", () => {
+    beforeEach(() => {
+        // Reset global one-shot guard between tests.
+        globalThis.__muonroiSoftWarnFired = undefined;
+    });
+    afterEach(() => {
+        globalThis.__muonroiSoftWarnFired = undefined;
+    });
+    it("fires once at floor(ceiling * 0.7) per session", () => {
+        // ceiling 10 -> floor(7) = 7
+        expect(shouldInjectSoftWarn(6, 10, "sess-A")).toBe(false);
+        expect(shouldInjectSoftWarn(7, 10, "sess-A")).toBe(true);
+        // Subsequent calls within same session return false.
+        expect(shouldInjectSoftWarn(7, 10, "sess-A")).toBe(false);
+        expect(shouldInjectSoftWarn(8, 10, "sess-A")).toBe(false);
+    });
+    it("fires independently per session id", () => {
+        expect(shouldInjectSoftWarn(7, 10, "sess-A")).toBe(true);
+        // Different session — fresh one-shot.
+        expect(shouldInjectSoftWarn(7, 10, "sess-B")).toBe(true);
+        expect(shouldInjectSoftWarn(7, 10, "sess-B")).toBe(false);
+    });
+    it("does not fire below threshold", () => {
+        // ceiling 20 -> floor(14)
+        expect(shouldInjectSoftWarn(13, 20, "s1")).toBe(false);
+        expect(shouldInjectSoftWarn(14, 20, "s1")).toBe(true);
+    });
+});
+describe("shouldInjectCeilingCrossing", () => {
+    beforeEach(() => {
+        globalThis.__muonroiCeilingCrossingFired = undefined;
+    });
+    afterEach(() => {
+        globalThis.__muonroiCeilingCrossingFired = undefined;
+    });
+    it("fires exactly once per session at the first step past the natural ceiling", () => {
+        expect(shouldInjectCeilingCrossing(6, 6, "s1")).toBe(false); // equal, not past
+        expect(shouldInjectCeilingCrossing(7, 6, "s1")).toBe(true); // first crossing
+        expect(shouldInjectCeilingCrossing(8, 6, "s1")).toBe(false); // already fired
+        expect(shouldInjectCeilingCrossing(77, 6, "s1")).toBe(false); // still suppressed
+    });
+    it("fires independently per session", () => {
+        expect(shouldInjectCeilingCrossing(7, 6, "a")).toBe(true);
+        expect(shouldInjectCeilingCrossing(7, 6, "b")).toBe(true);
+        expect(shouldInjectCeilingCrossing(8, 6, "b")).toBe(false);
+    });
+    it("never fires below or at the ceiling", () => {
+        expect(shouldInjectCeilingCrossing(1, 6, "x")).toBe(false);
+        expect(shouldInjectCeilingCrossing(6, 6, "x")).toBe(false);
+    });
+    it("rejects non-positive or non-finite inputs", () => {
+        expect(shouldInjectCeilingCrossing(0, 6, "x")).toBe(false);
+        expect(shouldInjectCeilingCrossing(-1, 6, "x")).toBe(false);
+        expect(shouldInjectCeilingCrossing(7, 0, "x")).toBe(false);
+        expect(shouldInjectCeilingCrossing(Number.NaN, 6, "x")).toBe(false);
+    });
+});
+describe("buildScopeReminder", () => {
+    it("contains verbatim first 100 chars of prompt and stays <= 200 chars", () => {
+        const prompt = "A".repeat(200);
+        const out = buildScopeReminder({
+            step: 3,
+            ceiling: 10,
+            taskType: "refactor",
+            size: "small",
+            originalPrompt: prompt,
+        });
+        expect(out.length).toBeLessThanOrEqual(200);
+        // First 100 chars of prompt must appear verbatim.
+        expect(out).toContain("A".repeat(100));
+        // Header marker present (4V harness asserts this exact prefix).
+        expect(out).toMatch(/\[scope-check step 3\//);
+        expect(out).toContain("still on scope?");
+    });
+    it("uses whole prompt when shorter than 100 chars (no padding)", () => {
+        const out = buildScopeReminder({
+            step: 5,
+            ceiling: 14,
+            taskType: "debug",
+            size: "medium",
+            originalPrompt: "short prompt",
+        });
+        expect(out).toContain('"short prompt"');
+        expect(out.length).toBeLessThanOrEqual(200);
+    });
+    it("escapes embedded quote characters in the snippet", () => {
+        const out = buildScopeReminder({
+            step: 3,
+            ceiling: 10,
+            taskType: "generate",
+            size: "small",
+            originalPrompt: 'fix bug with "quoted" word',
+        });
+        // Embedded quote must be escaped to keep the snippet parseable.
+        expect(out).toMatch(/\\"quoted\\"/);
+        expect(out.length).toBeLessThanOrEqual(200);
+    });
+    it("hard-truncates final string to 200 chars defensively", () => {
+        // Even with monster taskType / size labels, hard cap holds.
+        const out = buildScopeReminder({
+            step: 9999,
+            ceiling: 99999,
+            taskType: "x".repeat(50),
+            size: "y".repeat(50),
+            originalPrompt: "P".repeat(500),
+        });
+        expect(out.length).toBeLessThanOrEqual(200);
+    });
+});
+describe("attachReminderToMessages", () => {
+    it("appends reminder text to the last tool message", () => {
+        const messages = [
+            { role: "user", content: "do the thing" },
+            {
+                role: "tool",
+                content: [
+                    {
+                        type: "tool-result",
+                        toolCallId: "id1",
+                        toolName: "read_file",
+                        output: { type: "text", value: "file contents" },
+                    },
+                ],
+            },
+        ];
+        const out = attachReminderToMessages(messages, "[scope-check step 3/10] etc");
+        expect(out.length).toBe(2);
+        const last = out[1];
+        expect(last.role).toBe("tool");
+        // Reminder text appears appended either as a new tool-result text
+        // value, or as a wrapper around the existing one. The contract is:
+        // the reminder string is now present in the JSON-stringified last msg.
+        expect(JSON.stringify(last)).toContain("[scope-check step 3/10] etc");
+    });
+    it("appends a system message when last message is text-only assistant", () => {
+        const messages = [
+            { role: "user", content: "hi" },
+            { role: "assistant", content: "ok" },
+        ];
+        const out = attachReminderToMessages(messages, "remind");
+        expect(out.length).toBe(3);
+        const tail = out[2];
+        expect(tail.role).toBe("system");
+        expect(tail.content).toBe("remind");
+    });
+    it("returns input unchanged when reminder is empty", () => {
+        const messages = [{ role: "user", content: "hi" }];
+        const out = attachReminderToMessages(messages, "");
+        expect(out).toEqual(messages);
+    });
+});
+//# sourceMappingURL=scope-reminder.test.js.map

package/dist/src/orchestrator/stall-rescue.d.ts

@@ -0,0 +1,67 @@
+/**
+ * src/orchestrator/stall-rescue.ts
+ *
+ * Best-effort answer rescue when a streaming model call stalls mid-turn.
+ *
+ * Root cause it addresses (live obs 2026-06-04, deepseek-v4-flash session
+ * 734e65cffdf6): on a long open-ended task the model looped, the loop-guard
+ * fired, then the main stream stalled. The stall branch in message-processor
+ * yields a bare "Model not responding" and `return`s — so a turn that already
+ * ran dozens of tool calls (read_file, grep, bash …) leaves the user with NO
+ * synthesis of any of that work. The normal F6 forced-finalize path that would
+ * coax a text answer out of a tool-only last step is never reached because the
+ * abort short-circuits before it.
+ *
+ * The rescue: on stall, if the turn gathered any tool outputs, make ONE
+ * forced-finalize call (toolChoice:"none", its own stall timeout) over the
+ * conversation plus a compact digest of those outputs, asking the model to give
+ * its best final answer from what it already has. If that returns text, the turn
+ * is rescued; otherwise we fall back to the bare stall message.
+ *
+ * This module is pure/instrumentation-free so it unit-tests without the AI SDK:
+ * the caller injects `finalize`, and the live stall (nondeterministic) is not
+ * needed to verify the rescue logic.
+ */
+/** One tool output captured during the turn, already truncated by the caller. */
+export interface StallToolResult {
+    tool: string;
+    text: string;
+}
+/** Max tool outputs folded into the synthesis digest (most recent win). */
+export declare const STALL_RESCUE_MAX_RESULTS = 8;
+/** Max chars kept per tool output in the digest. */
+export declare const STALL_RESCUE_MAX_CHARS_PER_RESULT = 1500;
+/**
+ * Capture a tool result into a capped ring buffer (mutates `buffer`). Keeps the
+ * buffer bounded in BOTH count and per-entry size so a long turn can't blow
+ * memory or the eventual synthesis prompt.
+ */
+export declare function pushStallToolResult(buffer: StallToolResult[], tool: string, rawText: string): void;
+/**
+ * Build the synthesis messages: the existing conversation plus one synthetic
+ * user turn carrying the original request and a digest of the tool outputs
+ * gathered before the stall. Pure — returns a fresh array, never mutates input.
+ */
+export declare function buildStallSynthesisMessages(baseMessages: unknown[], userText: string, toolResults: StallToolResult[]): unknown[];
+export interface StallRescueParams {
+    baseMessages: unknown[];
+    userText: string;
+    toolResults: StallToolResult[];
+    system?: string;
+    /**
+     * Injected finalize call (production: a thin wrapper over `forcedFinalize`).
+     * Must resolve to the synthesized text (may be empty) or reject on failure.
+     */
+    finalize: (args: {
+        system?: string;
+        messages: unknown[];
+    }) => Promise<{
+        text: string;
+    }>;
+}
+/**
+ * Attempt to rescue a final answer after a stall. Returns the synthesized text,
+ * or null when there is nothing to synthesize from / the finalize call fails or
+ * yields no text. Never throws — the caller falls back to the stall message.
+ */
+export declare function attemptStallRescue(params: StallRescueParams): Promise<string | null>;