muonroi-cli 1.8.4 → 1.8.5

package/dist/src/product-loop/sprint-runner.d.ts

@@ -26,6 +26,77 @@ import type { ContinueFeedback } from "./feedback-routing.js";
 import type { DriverContext, IterationState, ProductSpec, RoleSlot } from "./types.js";
 /** @internal Test-only: reset CB-2 retry state for a given runId. */
 export declare function _resetCb2RetryUsed(runId: string): void;
+/**
+ * Idle-chunk ceiling for the implementation stage (ms). Override with
+ * MUONROI_SPRINT_IMPL_IDLE_MS. This is a TIME-SINCE-LAST-CHUNK budget, not a
+ * total-turn cap — a legitimately long implementation streams progress the
+ * whole way, so it may run for many minutes, but it must never go completely
+ * silent (no chunk at all) for this long.
+ */
+export declare function getImplIdleTimeoutMs(): number;
+/**
+ * Hard total-elapsed ceiling for the implementation stage (ms). Override with
+ * MUONROI_SPRINT_IMPL_TOTAL_MS. Unlike the idle budget this is armed once and is
+ * NOT reset by chunks, so it catches a hang that keeps the idle guard alive with
+ * heartbeat/status chunks. Generous by default so a legitimately large sprint is
+ * not cut short; a genuine hang still terminates within this ceiling.
+ */
+export declare function getImplTotalTimeoutMs(): number;
+/**
+ * Whether the implement stage runs in an ISOLATED bounded sub-agent context
+ * (ctx.runIsolatedTask) instead of the shared top-level turn (processMessageFn).
+ * Default ON. Disable with MUONROI_SPRINT_ISOLATED_IMPL=0.
+ *
+ * The isolated path is the fix for the live ctx-overflow wedge: the flat
+ * processMessageFn turn inherited the full council-debate history (~5.9M tokens
+ * observed), started implementation already at ~94% context, then wedged after a
+ * mid-turn compaction. A fresh child context (getSubAgentBudgetChars cap +
+ * independent in-loop compaction) never inherits the debate, so it starts near
+ * empty and its clutter is absorbed as one compact ToolResult.
+ */
+export declare function getSprintIsolatedImplEnabled(): boolean;
+/**
+ * Pure decision: use the isolated sub-agent path for the implement stage?
+ * True only when the flag is on AND the driver actually provides the bridge
+ * (legacy/test drivers omit runIsolatedTask → fall back to processMessageFn).
+ * Extracted for unit testing without spinning up a full runSprint.
+ */
+export declare function shouldUseIsolatedImpl(hasBridge: boolean, enabled?: boolean): boolean;
+/**
+ * Imperative execution directive prepended to the sprint plan before it is
+ * handed to the orchestrator. The raw plan synthesis is a declarative design
+ * document; without this prefix the impl turn narrates it back instead of
+ * applying edits. Exported for test assertion. @internal
+ */
+export declare const IMPL_EXECUTION_DIRECTIVE: string;
+/**
+ * Wrap the implementation `processMessageFn` stream with an idle-chunk watchdog.
+ *
+ * Root cause it addresses (observed live 2026-07-08, /ideal resume of the
+ * gsd-core migration): the implementation stage delegates to the host
+ * orchestrator turn via `ctx.processMessageFn(implPrompt)` and consumes it with
+ * `for await (const chunk of implGen)`. The orchestrator turn finished its final
+ * LLM response cleanly (finishReason "stop", text-only) but the generator then
+ * suspended post-finish and never completed — the `for await` blocked for 17+
+ * minutes with NO chunk, NO phaseDone, NO advance to Verify, NO error. Because
+ * the LLM STREAM had already finished, the orchestrator's mid-stream
+ * time-to-next-chunk stall-watchdog does not fire — the hang is on the JS side
+ * after the stream terminator.
+ *
+ * TWO complementary guards (a single idle guard was observed live to be
+ * defeated: the impl created 2 files then emitted only non-progress heartbeat
+ * chunks for 9+ min, resetting a per-chunk idle timer without ever completing):
+ *   - `idleMs` — resets on every yielded chunk; catches a TOTALLY silent stall
+ *     (the post-finish hang above, zero chunks) quickly.
+ *   - `totalMs` — armed ONCE at entry, NOT reset by chunks; a hard ceiling that
+ *     fires even when heartbeat/status chunks keep the idle guard alive while no
+ *     real progress is made.
+ * Either firing throws so the caller's existing try/catch converts the wedge
+ * into a visible phaseError (the sprint then surfaces + can recover), exactly
+ * like `runVerifyWithWatchdog` does for the verify stage. The suspended
+ * orchestrator promise may leak in the background, but the run recovers.
+ */
+export declare function withImplIdleWatchdog(gen: AsyncGenerator<StreamChunk, void, unknown>, idleMs: number, sprintN: number, totalMs?: number): AsyncGenerator<StreamChunk, void, unknown>;
 export { computeFailureSignature, loadVerifyFailureSignatures, pushFailureToEE, recordVerifyFailureAndMaybePush, saveVerifyFailureSignatures, type VerifyFailureRecord, type VerifyFailureSignatures, } from "./verify-failure-tracking.js";
 export interface RunSprintArgs {
     sprintN: number;
@@ -60,4 +131,44 @@ export interface RunSprintArgs {
  * Throws on circuit-breaker halt — caller (loop driver) catches and writes
  * the appropriate halt state to manifest/state.
  */
+/** Path to the persisted per-sprint plan synthesis (Wave 2). @internal */
+export declare function sprintPlanPath(runDir: string, sprintN: number): string;
+/**
+ * Wave 2: read a persisted sprint plan if present. Returns "" when absent or on
+ * read error (caller then runs the planning council). Never throws.
+ *
+ * The planning council is non-deterministic — re-running it on a resumed/retried
+ * sprint produces a different design AND a different target folder, which is why
+ * the impl turn was observed re-scaffolding in a new location each run. Reusing
+ * the persisted plan makes per-sprint planning idempotent so the same target
+ * files are continued across resume.
+ */
+export declare function readPersistedSprintPlan(planPath: string): Promise<string>;
+/** Wave 2: persist a sprint plan synthesis for idempotent resume. Never throws. */
+export declare function persistSprintPlan(planPath: string, synthesis: string): Promise<void>;
+/**
+ * Extract repo-relative target file paths a sprint plan names (src/…, packages/…,
+ * tests/…). Deduped, capped. Used by Wave 3 (existing targets → continue) and 4A
+ * (missing targets → completeness re-check). Never throws.
+ */
+export declare function extractPlanTargetPaths(planSynthesis: string, cap?: number): string[];
+/**
+ * Wave 3: plan-named target file paths that ALREADY EXIST on disk, so the impl
+ * turn continues them rather than re-scaffolding in a new location. Empty on a
+ * greenfield sprint (files don't exist yet) → no injection.
+ */
+export declare function detectExistingPlanTargets(planSynthesis: string, cwd: string, cap?: number): Promise<string[]>;
+/**
+ * 4A: plan-named target file paths that STILL DO NOT EXIST after the impl turn —
+ * i.e. action items the implementer left unaddressed. Drives the post-impl
+ * completeness re-check (spend an extra turn ONLY when there is proven-incomplete
+ * work, unlike an unconditional reviewer pass). Empty ⇒ every named target landed.
+ */
+export declare function computeMissingPlanTargets(planSynthesis: string, cwd: string, cap?: number): Promise<string[]>;
+/**
+ * 4A completeness re-check toggle. Default ON; disable with
+ * MUONROI_SPRINT_IMPL_RECHECK=0. When on, and the impl turn left plan-named
+ * target files missing, ONE focused follow-up turn is spent to finish them.
+ */
+export declare function getImplRecheckEnabled(): boolean;
 export declare function runSprint(args: RunSprintArgs): AsyncGenerator<StreamChunk, IterationState, unknown>;