@kasenri/dsh-orbit 0.5.1

package/lib/supervisor.js

@@ -0,0 +1,792 @@
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { buildEvidenceBundle, formatEvidenceBundle } from "./evidence.js";
+import { assertCommanderDecision, assertStrategyDecision, assertTimeoutDecision, assertWatchdogDecision, assertGuardWatchdogDecision, COMMANDER_FINAL_EVALUATE_SCHEMA, COMMANDER_PLAN_SCHEMA, COMMANDER_STEP_EVALUATE_SCHEMA, COMMANDER_STRATEGY_SCHEMA, WATCHDOG_GUARD_SCHEMA, WATCHDOG_RUNTIME_SCHEMA, WATCHDOG_STRATEGY_SCHEMA, WATCHDOG_TIMEOUT_SCHEMA, } from "./decisions.js";
+import { applyCommanderNeedsUser, applyCorrectionStep, applyExecutorCapabilityUnavailable, applyExecutorInterrupted, applyExecutorResume, applyExecutorSuccess, applyFinalAppend, applyFinalSuccess, applyPlan, applyStepPass, baseStepIdOf, beginStep, clearExecutorChild, clearGuardRecovery, correctionBlockCode, correctionDepthOf, createInitialState, enterBudgetExhausted, enterNeedsUser, markStrategyChallengeUsed, normalizePlan, openWatchdogAttempt, recordGuardRecovery, recordPlanFailure, recordWatchdogDecision, restoreEvaluationState, resumeFromNeedsUser, stopRun, } from "./kernel.js";
+import { truncateSafe } from "./sanitize.js";
+import { OrbitStateStore } from "./state-store.js";
+import { COMMANDER_EXTENSION_MS, COMMANDER_HARD_CEILING_MS, COMMANDER_SOFT_DEADLINE_MS, DEFAULT_CAPABILITIES, EXECUTOR_TIMEOUT_MS, GUARD_ESCALATION_THRESHOLD, GUARD_FIRST_INSTRUCTION, GUARD_NEEDS_USER_INSTRUCTION, GUARD_RECOVERY_CAP, GUARD_REPEAT_INSTRUCTION, GUARD_RETRY_INSTRUCTION, MAX_EXECUTOR_INTERRUPT_RETRIES, MAX_WATCHDOG_CALLS_PER_STEP, WATCHDOG_TIMEOUT_MS, } from "./types.js";
+const COMMANDER_PLAN_PROMPT = (goal, constraints) => `You are the Orbit Commander. Produce the smallest set of 2-5 logical engineering steps for this goal.
+Rules: ordinary engineering steps must omit capabilities. Add capability "browser" only when the step must drive a real web page, and "web-api-recon" when it must analyze captured network/API traffic. Keep it minimal.
+Submit your final plan through the structured result protocol.
+Goal: ${goal}
+Hard constraints: ${constraints.join('; ') || 'none'}`;
+const COMMANDER_STEP_PROMPT = (goal, step, evidence, state) => `You are the Orbit Commander doing STEP_EVALUATE. Verify the real project state; do not trust the Executor claim alone. Treat verified execution evidence as authoritative.
+Allowed decisions ONLY: PASS_CURRENT_STEP | CORRECT_CURRENT_STEP | NEEDS_USER.
+- CORRECT_CURRENT_STEP requires a concrete next step goal (optional capabilities).
+Submit your final judgment through the structured result protocol.
+Original goal: ${goal}
+Current step ${step.id}: ${step.goal}
+Iteration counters: loop ${state.loop.used}/${state.loop.max}
+Executor claim:
+${evidence}`;
+const COMMANDER_FINAL_PROMPT = (goal, plan, evidence, state) => `You are the Orbit Commander doing FINAL_EVALUATE. All planned steps are done. Decide whether the original goal is truly satisfied against the real project state.
+Allowed decisions ONLY: SUCCESS | APPEND | NEEDS_USER.
+- APPEND requires next steps or a next step goal; appends are bounded by the remaining loop budget.
+Submit your final judgment through the structured result protocol.
+Original goal: ${goal}
+Plan summary: ${plan.summary}
+Steps: ${plan.steps.map((step) => `${step.id}:${step.goal}[${step.status}]`).join('; ')}
+Loop: ${state.loop.used}/${state.loop.max}
+Executor claim:
+${evidence}`;
+const COMMANDER_STRATEGY_PROMPT = (goal, base, challenge, state) => `You are the Orbit Commander reconsidering strategy after a repeated correction on ${base} (STRATEGY_RECONSIDER).
+Allowed decisions ONLY: KEEP_APPROACH | REPLACE_CURRENT_STEP | NEEDS_USER.
+- REPLACE_CURRENT_STEP requires a replacement goal.
+Submit your final judgment through the structured result protocol.
+Goal: ${goal}
+Loop: ${state.loop.used}/${state.loop.max}
+Watchdog challenge: ${challenge}`;
+const WATCHDOG_RUNTIME_PROMPT = (step, reason, telemetry) => `You are the Orbit Smart Watchdog doing RUNTIME_DIAGNOSE. Diagnose only the current runtime anomaly. Do not review code quality.
+Allowed decisions ONLY: RESUME_CHILD | RESTART_STEP | NEEDS_USER | RUNTIME_BUG.
+Submit your final judgment through the structured result protocol.
+Failed step ${step.id}: ${step.goal}
+Runtime anomaly: ${reason}
+Telemetry: ${JSON.stringify(telemetry ?? {})}`;
+const WATCHDOG_STRATEGY_PROMPT = (step, reason, state) => `You are the Orbit Smart Watchdog doing STRATEGY_CHALLENGE. Ask: is the current approach tunnel vision? Is this blocker truly required? Is there a simpler route?
+Submit one focused challenge question through the structured result protocol.
+Step ${step.id}: ${step.goal}
+Repeated correction: ${reason}
+Loop: ${state.loop.used}/${state.loop.max}`;
+const WATCHDOG_GUARD_PROMPT = (code, count, stepId) => `You are the Orbit Smart Watchdog doing GUARD_ESCALATION. A safety guard blocked a tool ${count} times.
+Allowed decisions ONLY: RETRY_DIFFERENTLY | NEEDS_USER.
+Submit your final judgment through the structured result protocol.
+Guard code: ${code}
+Step: ${stepId}`;
+const WATCHDOG_TIMEOUT_PROMPT = (mode, elapsed, extensions, telemetry) => `You are the Orbit Smart Watchdog doing COMMANDER_TIMEOUT_REVIEW. The Commander has run ${elapsed}ms with ${extensions} extension(s).
+Allowed decisions ONLY: EXTEND | INTERRUPT | NEEDS_USER.
+Submit your final judgment through the structured result protocol.
+Mode: ${mode}
+Telemetry: ${JSON.stringify(telemetry ?? {})}`;
+export class OrbitSupervisor {
+    store;
+    host;
+    config;
+    /** Evidence for the step that just settled; never persisted into state.json. */
+    stepEvidence;
+    constructor(store, host, config) {
+        this.store = store;
+        this.host = host;
+        this.config = config;
+    }
+    now() {
+        return this.host.now();
+    }
+    createState(input) {
+        return createInitialState({
+            runId: typeof input.run_id === 'string' && input.run_id.length > 0 ? input.run_id : randomUUID(),
+            now: this.now(),
+            goal: (input.goal ?? '').trim(),
+            ...(input.preset !== undefined ? { preset: input.preset } : {}),
+            routes: this.config.resolveRoutes?.() ?? this.config.defaultRoutes,
+            ...(input.approved_loop_count !== undefined ? { approvedLoopCount: input.approved_loop_count } : {}),
+            ...(input.max_loops !== undefined ? { maxLoops: input.max_loops } : {}),
+            ...(input.user_hard_constraints ? { userHardConstraints: input.user_hard_constraints } : {}),
+            githubAllowed: input.github_allowed === true,
+        });
+    }
+    async bootstrap(input, signal) {
+        const requestedGoal = (input.goal ?? '').trim();
+        let state = this.store.readState();
+        const raw = this.store.readRawState();
+        const legacy = raw !== null && raw['schema_version'] !== 2;
+        if (legacy && requestedGoal) {
+            state = this.store.writeState(this.createState(input));
+        }
+        else if (!state) {
+            if (!requestedGoal)
+                return { ok: false, action: 'run', message: 'ORBIT_GOAL_REQUIRED: provide a goal to start a run.' };
+            state = this.store.writeState(this.createState(input));
+        }
+        else if (input.run_id && input.run_id !== state.run_id && !legacy) {
+            return { ok: false, action: 'run', message: `ORBIT_RUN_NOT_FOUND: ${input.run_id}` };
+        }
+        if (['SUCCESS', 'STOPPED', 'BUDGET_EXHAUSTED'].includes(state.phase) && requestedGoal) {
+            state = this.store.writeState(this.createState(input));
+        }
+        if (!legacy && requestedGoal && state.goal && state.goal !== requestedGoal) {
+            return {
+                ok: false,
+                action: 'run',
+                run_id: state.run_id,
+                message: 'ORBIT_ACTIVE_RUN_EXISTS: current Lite run owns this project; resume it or stop it before starting a different goal.',
+            };
+        }
+        if (state.phase === 'NEEDS_USER' && requestedGoal) {
+            resumeFromNeedsUser(state);
+            this.store.writeState(state);
+        }
+        return this.run(state, signal);
+    }
+    async run(state, signal) {
+        if (signal?.aborted)
+            return this.result(state, false, 'ORBIT_ABORTED');
+        const projectDir = join(this.store.stateDir, '..');
+        const competitors = await this.host.otherMutationDrivers(projectDir);
+        if (competitors.length > 0) {
+            return {
+                ok: false,
+                action: 'run',
+                run_id: state.run_id,
+                phase: state.phase,
+                status: state.status,
+                message: `ORBIT_MUTATION_DRIVER_CONFLICT: ${competitors.join(', ')} already owns mutation in this workspace.`,
+            };
+        }
+        if (state.phase === 'NEEDS_USER')
+            return this.result(state, true, 'ORBIT_AWAITING_USER');
+        if (state.phase === 'SUCCESS')
+            return this.result(state, true);
+        if (state.phase === 'STOPPED')
+            return this.result(state, true);
+        if (state.phase === 'BUDGET_EXHAUSTED')
+            return this.result(state, true);
+        if (state.plan.steps.length === 0 && state.phase === 'PLAN') {
+            const planOutcome = await this.makePlan(state, signal);
+            if (planOutcome)
+                return planOutcome;
+        }
+        if (state.phase === 'EVALUATE' && state.child?.status === 'completed' && state.current_step) {
+            const step = state.plan.steps.find((candidate) => candidate.id === state.current_step?.id);
+            if (!step) {
+                enterNeedsUser(state, 'EVALUATE_STEP_MISSING');
+                this.store.writeState(state);
+                return this.result(state, false);
+            }
+            const outcome = await this.commanderEvaluate(state, step, false, signal);
+            const applied = await this.applyCommanderOutcome(state, outcome, step, false, signal);
+            if (applied)
+                return applied;
+            return this.run(state, signal);
+        }
+        const step = state.plan.steps.find((candidate) => candidate.status === 'running') ??
+            state.plan.steps.find((candidate) => candidate.status === 'pending');
+        if (!step) {
+            const outcome = await this.commanderEvaluate(state, undefined, true, signal);
+            const applied = await this.applyCommanderOutcome(state, outcome, undefined, true, signal);
+            if (applied)
+                return applied;
+            return this.run(state, signal);
+        }
+        if (state.loop.used >= state.loop.max) {
+            enterBudgetExhausted(state, 'LOOP_BUDGET_EXHAUSTED');
+            this.store.writeState(state);
+            return this.result(state, false);
+        }
+        beginStep(state, step);
+        this.store.writeState(state);
+        const executed = await this.executeStep(state, step, signal);
+        if (executed.done)
+            return this.result(state, executed.ok, executed.message);
+        return this.run(state, signal);
+    }
+    // ── tool scoping ───────────────────────────────────────────────────────────
+    /**
+     * Build an allow-filter from configured names, keeping only tools that are
+     * actually registered (an unknown name makes `tools.restrict()` fail).
+     */
+    toolAllow(names, label) {
+        const allowed = names.filter((name) => this.host.hasTool(name));
+        if (allowed.length === 0) {
+            throw new Error(`ORBIT_TOOL_FILTER_EMPTY: none of [${names.join(', ')}] are registered for ${label}`);
+        }
+        return { allow: allowed };
+    }
+    // ── commander supervised path ──────────────────────────────────────────────
+    async makePlan(state, signal) {
+        const outcome = await this.runCommander(state, 'PLAN', COMMANDER_PLAN_PROMPT(state.goal, state.user_hard_constraints), COMMANDER_PLAN_SCHEMA, signal);
+        if (outcome.kind === 'needs_user')
+            return this.setNeedsUser(state, outcome.reason);
+        if (outcome.kind === 'interrupted') {
+            recordPlanFailure(state, truncateSafe(outcome.reason, 500));
+            this.store.writeState(state);
+            return this.result(state, false, outcome.reason);
+        }
+        try {
+            const plan = normalizePlan(outcome.structured);
+            applyPlan(state, plan);
+            this.store.writeState(state);
+            return undefined;
+        }
+        catch (error) {
+            const reason = truncateSafe(error instanceof Error ? error.message : String(error), 500);
+            recordPlanFailure(state, reason);
+            this.store.writeState(state);
+            return this.result(state, false, reason);
+        }
+    }
+    async commanderEvaluate(state, step, final, signal) {
+        const mode = final ? 'FINAL_EVALUATE' : 'STEP_EVALUATE';
+        const evidence = this.evidenceFor(state, step) ?? state.commander?.summary ?? state.last_error ?? 'no evidence recorded';
+        const prompt = final
+            ? COMMANDER_FINAL_PROMPT(state.goal, state.plan, evidence, state)
+            : COMMANDER_STEP_PROMPT(state.goal, step, evidence, state);
+        const outcome = await this.runCommander(state, mode, prompt, final ? COMMANDER_FINAL_EVALUATE_SCHEMA : COMMANDER_STEP_EVALUATE_SCHEMA, signal);
+        if (outcome.kind === 'needs_user')
+            return { kind: 'needs_user', reason: outcome.reason };
+        if (outcome.kind === 'interrupted')
+            return { kind: 'interrupted', reason: outcome.reason };
+        try {
+            const decision = assertCommanderDecision(outcome.structured, mode);
+            return { kind: 'decision', decision };
+        }
+        catch (error) {
+            // Invalid/temporary output is recoverable; it must not become NEEDS_USER.
+            return { kind: 'interrupted', reason: truncateSafe(error instanceof Error ? error.message : String(error), 500) };
+        }
+    }
+    /**
+     * Format the settled step's evidence bundle. Only the step that just finished
+     * qualifies; after a cold resume the bundle is gone and the caller falls back
+     * to the durable state summary.
+     */
+    evidenceFor(state, step) {
+        const stepId = step?.id ?? state.current_step?.id;
+        if (!this.stepEvidence || this.stepEvidence.stepId !== stepId)
+            return undefined;
+        return formatEvidenceBundle(this.stepEvidence.bundle);
+    }
+    /**
+     * The single adaptive Commander runner for PLAN, STEP_EVALUATE, FINAL_EVALUATE
+     * and STRATEGY_RECONSIDER. 360s/600s soft reviews, 840s deterministic ceiling;
+     * EXTEND always keeps the same child. Decisions arrive as DSH-native
+     * structured results; a requested schema without a capture is a failure.
+     */
+    async runCommander(state, mode, prompt, outputSchema, signal) {
+        const startedAt = this.now();
+        let handle;
+        try {
+            handle = await this.host.startRole({
+                role: 'commander',
+                label: `commander-${mode.toLowerCase()}`,
+                prompt,
+                route: state.routes.commander,
+                toolFilter: this.toolAllow(this.config.commanderReadOnlyTools, `commander ${mode}`),
+                outputSchema,
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch (error) {
+            return { kind: 'interrupted', reason: truncateSafe(error instanceof Error ? error.message : String(error), 500) };
+        }
+        try {
+            for (let extensions = 0;;) {
+                const deadline = extensions === 0
+                    ? COMMANDER_SOFT_DEADLINE_MS
+                    : extensions === 1
+                        ? COMMANDER_SOFT_DEADLINE_MS + COMMANDER_EXTENSION_MS
+                        : COMMANDER_HARD_CEILING_MS;
+                const remaining = Math.max(0, deadline - (this.now() - startedAt));
+                const raced = await this.raceWithSleep(handle.result, remaining, signal);
+                if (raced.kind === 'work') {
+                    if (raced.value.interrupted)
+                        return { kind: 'interrupted', reason: raced.value.reason ?? `${mode}_INTERRUPTED` };
+                    if (raced.value.structured === undefined) {
+                        return { kind: 'interrupted', reason: `${mode}_STRUCTURED_OUTPUT_MISSING` };
+                    }
+                    return { kind: 'output', output: raced.value.output, structured: raced.value.structured };
+                }
+                if (raced.kind === 'aborted' || signal?.aborted) {
+                    await this.cancelHandle(handle, 'ORBIT_ABORTED');
+                    return { kind: 'interrupted', reason: 'ORBIT_ABORTED' };
+                }
+                if (extensions >= 2) {
+                    await this.cancelHandle(handle, 'COMMANDER_HARD_TIMEOUT');
+                    return { kind: 'interrupted', reason: 'COMMANDER_HARD_TIMEOUT' };
+                }
+                const review = await this.commanderTimeoutReview(state, mode, this.now() - startedAt, extensions, handle, signal);
+                if (review.decision === 'EXTEND') {
+                    extensions += 1;
+                    continue;
+                }
+                await this.cancelHandle(handle, review.decision === 'NEEDS_USER' ? 'COMMANDER_NEEDS_USER' : 'COMMANDER_TIMEOUT_INTERRUPTED');
+                if (review.decision === 'NEEDS_USER')
+                    return { kind: 'needs_user', reason: review.reason ?? 'COMMANDER_TIMEOUT_NEEDS_USER' };
+                return { kind: 'interrupted', reason: 'COMMANDER_TIMEOUT_INTERRUPTED' };
+            }
+        }
+        finally {
+            await this.disposeHandle(handle);
+        }
+    }
+    async commanderTimeoutReview(state, mode, elapsed, extensions, commanderHandle, signal) {
+        // Telemetry must describe the *current* Commander child, never a past Executor.
+        const telemetry = await commanderHandle.runtimeSnapshot?.();
+        const result = await this.runAuxRole(state, {
+            role: 'watchdog',
+            label: 'watchdog-commander-timeout',
+            prompt: WATCHDOG_TIMEOUT_PROMPT(mode, elapsed, extensions, telemetry),
+            outputSchema: WATCHDOG_TIMEOUT_SCHEMA,
+            ...(signal ? { signal } : {}),
+        });
+        if (!result || result.interrupted) {
+            return { decision: extensions === 0 ? 'EXTEND' : 'INTERRUPT', reason: 'Smart Watchdog unavailable' };
+        }
+        try {
+            return assertTimeoutDecision(result.structured);
+        }
+        catch {
+            return { decision: extensions === 0 ? 'EXTEND' : 'INTERRUPT', reason: 'Smart Watchdog invalid output' };
+        }
+    }
+    // ── executor runtime ───────────────────────────────────────────────────────
+    async executeStep(state, step, signal) {
+        const capabilities = step.capabilities ?? [];
+        if (capabilities.includes('browser') && !this.host.hasTool(this.config.browserTools[0] ?? 'agent_browser')) {
+            applyExecutorCapabilityUnavailable(state, step.id);
+            this.store.writeState(state);
+            return { done: false, ok: false };
+        }
+        let toolFilter;
+        try {
+            const capabilityTools = capabilities.includes('browser') ? [...this.config.browserTools] : [];
+            toolFilter = this.toolAllow([...this.config.executorTools, ...capabilityTools], `executor ${step.id}`);
+        }
+        catch (error) {
+            const reason = truncateSafe(error instanceof Error ? error.message : String(error), 500);
+            enterNeedsUser(state, reason);
+            this.store.writeState(state);
+            return { done: true, ok: false, message: reason };
+        }
+        let handle;
+        try {
+            handle = await this.host.startRole({
+                role: 'executor',
+                label: `executor-${step.id}`,
+                prompt: this.executorPrompt(state, step),
+                route: state.routes.executor,
+                toolFilter,
+                capabilities,
+                ...(signal ? { signal } : {}),
+                ...(state.child?.id && state.child.status === 'interrupted' ? { resumeOf: state.child.id } : {}),
+            });
+        }
+        catch (error) {
+            const reason = truncateSafe(error instanceof Error ? error.message : String(error), 500);
+            enterNeedsUser(state, reason);
+            this.store.writeState(state);
+            return { done: true, ok: false, message: reason };
+        }
+        const result = await this.awaitExecutor(handle, signal);
+        if (result.interrupted) {
+            const retries = applyExecutorInterrupted(state, {
+                ...(result.childId ? { childId: result.childId } : {}),
+                lastError: truncateSafe(result.reason ?? 'EXECUTOR_INTERRUPTED', 500),
+            });
+            this.store.writeState(state);
+            if (signal?.aborted)
+                return { done: true, ok: false, message: 'ORBIT_ABORTED' };
+            if (result.reason === 'USER_HARD_SCOPE_VIOLATION') {
+                enterNeedsUser(state);
+                this.store.writeState(state);
+                return { done: true, ok: false, message: 'USER_HARD_SCOPE_VIOLATION' };
+            }
+            const recovery = await this.runtimeWatchdog(state, step, result, retries, signal);
+            if (recovery === 'needs_user') {
+                enterNeedsUser(state);
+                this.store.writeState(state);
+                return { done: true, ok: false, message: state.last_error ?? undefined };
+            }
+            if (recovery === 'resume' && result.childId) {
+                applyExecutorResume(state, result.childId);
+                this.store.writeState(state);
+                return { done: false, ok: false };
+            }
+            if (recovery === 'restart') {
+                await this.cancelHandle(handle, 'ORBIT_RESTART_STEP');
+                await this.disposeHandle(handle);
+                clearExecutorChild(state);
+                this.store.writeState(state);
+                return { done: false, ok: false };
+            }
+            if (retries >= MAX_EXECUTOR_INTERRUPT_RETRIES) {
+                enterNeedsUser(state, `EXECUTOR_INTERRUPTED: ${state.last_error ?? ''}`);
+                this.store.writeState(state);
+                return { done: true, ok: false, message: state.last_error ?? undefined };
+            }
+            return { done: false, ok: false };
+        }
+        applyExecutorSuccess(state, {
+            ...(result.childId ? { childId: result.childId } : {}),
+            summary: truncateSafe(result.output, 2000),
+            changedFiles: result.changedFiles ?? this.host.changedFiles(join(this.store.stateDir, '..')),
+            testSummary: result.testSummary ?? [],
+        });
+        this.stepEvidence = {
+            stepId: step.id,
+            bundle: buildEvidenceBundle({
+                settlement: result.settlement,
+                executorOutput: result.output,
+                changedFiles: state.changed_files,
+                tools: result.toolEvidence,
+                telemetry: result.telemetry,
+            }),
+        };
+        this.store.writeState(state);
+        await this.disposeHandle(handle);
+        return { done: false, ok: false };
+    }
+    /** Deterministic executor runtime timeout; a timeout does not destroy the child. */
+    async awaitExecutor(handle, signal) {
+        const timeoutMs = this.config.executorTimeoutMs ?? EXECUTOR_TIMEOUT_MS;
+        const raced = await this.raceWithSleep(handle.result, timeoutMs, signal);
+        if (raced.kind === 'work')
+            return raced.value;
+        const telemetry = await handle.runtimeSnapshot?.();
+        return {
+            ...(handle.childId ? { childId: handle.childId } : {}),
+            output: '',
+            interrupted: true,
+            reason: raced.kind === 'aborted' ? 'ORBIT_ABORTED' : 'EXECUTOR_TIMEOUT',
+            ...(telemetry ? { telemetry } : {}),
+        };
+    }
+    executorPrompt(state, step) {
+        const lines = [
+            'You are the Orbit Executor. Implement exactly the current step with real tools and real verification.',
+            `Current step ${step.id}: ${step.goal}`,
+            `Working directory: ${join(this.store.stateDir, '..')}`,
+            `Hard constraints: ${state.user_hard_constraints.join('; ') || 'none'}`,
+        ];
+        if ((step.capabilities ?? []).length > 0)
+            lines.push(`Capabilities: ${(step.capabilities ?? []).join(', ')}`);
+        lines.push('Return a compact evidence summary: what changed, commands/tests run, and residual risks.');
+        return lines.join('\n');
+    }
+    // ── decision application ───────────────────────────────────────────────────
+    async applyCommanderOutcome(state, outcome, step, final, signal) {
+        clearGuardRecovery(state);
+        if (outcome.kind === 'interrupted') {
+            // Recoverable: the run stops and a later resume retries the same phase.
+            state.last_error = truncateSafe(outcome.reason, 500);
+            this.store.writeState(state);
+            return this.result(state, false, outcome.reason);
+        }
+        if (outcome.kind === 'needs_user')
+            return this.setNeedsUser(state, outcome.reason);
+        const decision = outcome.decision;
+        if (decision.decision === 'NEEDS_USER') {
+            applyCommanderNeedsUser(state, decision.reason ?? 'COMMANDER_NEEDS_USER');
+            this.store.writeState(state);
+            return this.result(state, false);
+        }
+        if (decision.decision === 'SUCCESS') {
+            applyFinalSuccess(state, decision.summary);
+            this.store.writeState(state);
+            return this.result(state, true);
+        }
+        if (decision.decision === 'PASS_CURRENT_STEP') {
+            applyStepPass(state, step, decision.summary);
+            this.store.writeState(state);
+            return undefined;
+        }
+        if (decision.decision === 'CORRECT_CURRENT_STEP') {
+            return this.applyCorrection(state, step, decision, signal);
+        }
+        if (decision.decision === 'APPEND') {
+            const append = applyFinalAppend(state, decision);
+            if (append === 'invalid') {
+                return this.setNeedsUser(state, 'COMMANDER_EVALUATION_OUTPUT_INVALID: append needs next_steps or next_step_goal');
+            }
+            this.store.writeState(state);
+            if (append === 'budget_exhausted')
+                return this.result(state, false);
+            return undefined;
+        }
+        // FINAL_EVALUATE must not return PASS/CORRECT; assertCommanderDecision already rejects it.
+        return this.setNeedsUser(state, 'COMMANDER_FINAL_DECISION_INVALID');
+    }
+    setNeedsUser(state, reason) {
+        enterNeedsUser(state, truncateSafe(reason, 500));
+        this.store.writeState(state);
+        return this.result(state, false);
+    }
+    async applyCorrection(state, step, decision, signal) {
+        if (!step || !decision.next_step_goal) {
+            return this.setNeedsUser(state, 'COMMANDER_EVALUATION_OUTPUT_INVALID: correction needs next_step_goal');
+        }
+        const base = baseStepIdOf(step.id);
+        const correctionDepth = correctionDepthOf(step.id);
+        const blocked = correctionBlockCode(state, step);
+        if (blocked)
+            return this.setNeedsUser(state, blocked);
+        let nextGoal = decision.next_step_goal;
+        if (correctionDepth === 1 && state.strategy_challenge?.base_step_id !== base) {
+            const reconsider = await this.strategyChallenge(state, base, step, decision.reason ?? 'repeated correction', signal);
+            if (reconsider.kind === 'needs_user')
+                return this.setNeedsUser(state, reconsider.reason);
+            if (reconsider.kind === 'interrupted') {
+                // Temporary failure: keep the run resumable and do NOT consume the challenge.
+                restoreEvaluationState(state, truncateSafe(reconsider.reason, 500));
+                this.store.writeState(state);
+                return this.result(state, false, reconsider.reason);
+            }
+            if (reconsider.kind === 'replace')
+                nextGoal = reconsider.replacementGoal;
+        }
+        applyCorrectionStep(state, step, {
+            nextGoal,
+            capabilities: decision.next_step_capabilities,
+        });
+        this.store.writeState(state);
+        return undefined;
+    }
+    async strategyChallenge(state, base, step, reason, signal) {
+        const challengeResult = await this.runAuxRole(state, {
+            role: 'watchdog',
+            label: 'watchdog-strategy',
+            prompt: WATCHDOG_STRATEGY_PROMPT(step, reason, state),
+            outputSchema: WATCHDOG_STRATEGY_SCHEMA,
+            ...(signal ? { signal } : {}),
+        });
+        if (!challengeResult || challengeResult.interrupted) {
+            return { kind: 'interrupted', reason: 'SMART_WATCHDOG_UNAVAILABLE' };
+        }
+        if (challengeResult.structured === undefined) {
+            return { kind: 'interrupted', reason: 'SMART_WATCHDOG_STRATEGY_STRUCTURED_OUTPUT_MISSING' };
+        }
+        const challengeValue = challengeResult.structured;
+        const challenge = typeof challengeValue.question === 'string' ? challengeValue.question.trim() : '';
+        if (!challenge)
+            return { kind: 'interrupted', reason: 'SMART_WATCHDOG_STRATEGY_OUTPUT_INVALID: question is required' };
+        const outcome = await this.runCommander(state, 'STRATEGY_RECONSIDER', COMMANDER_STRATEGY_PROMPT(state.goal, base, challenge, state), COMMANDER_STRATEGY_SCHEMA, signal);
+        if (outcome.kind === 'needs_user')
+            return { kind: 'needs_user', reason: outcome.reason };
+        if (outcome.kind === 'interrupted')
+            return { kind: 'interrupted', reason: outcome.reason };
+        try {
+            const decision = assertStrategyDecision(outcome.structured);
+            if (decision.decision === 'NEEDS_USER')
+                return { kind: 'needs_user', reason: decision.reason ?? 'COMMANDER_STRATEGY_NEEDS_USER' };
+            markStrategyChallengeUsed(state, base);
+            if (decision.decision === 'REPLACE_CURRENT_STEP')
+                return { kind: 'replace', replacementGoal: decision.replacement_goal };
+            return { kind: 'keep' };
+        }
+        catch (error) {
+            return { kind: 'interrupted', reason: truncateSafe(error instanceof Error ? error.message : String(error), 500) };
+        }
+    }
+    async runtimeWatchdog(state, step, result, retries, signal) {
+        const capReached = openWatchdogAttempt(state, step.id, {
+            atCap: state.last_error?.slice(0, 500),
+            attempt: truncateSafe(result.reason ?? state.last_error ?? '', 500),
+        });
+        if (capReached) {
+            this.store.writeState(state);
+            return 'needs_user';
+        }
+        this.store.writeState(state);
+        const watchdogResult = await this.runAuxRole(state, {
+            role: 'watchdog',
+            label: 'watchdog-runtime',
+            prompt: WATCHDOG_RUNTIME_PROMPT(step, result.reason ?? 'runtime failure', result.telemetry),
+            outputSchema: WATCHDOG_RUNTIME_SCHEMA,
+            ...(signal ? { signal } : {}),
+        });
+        if (!watchdogResult || watchdogResult.interrupted) {
+            recordWatchdogDecision(state, 'UNAVAILABLE');
+            this.store.writeState(state);
+            return 'fallback';
+        }
+        let diagnosis;
+        try {
+            diagnosis = assertWatchdogDecision(watchdogResult.structured);
+        }
+        catch {
+            recordWatchdogDecision(state, 'UNAVAILABLE');
+            this.store.writeState(state);
+            return 'fallback';
+        }
+        recordWatchdogDecision(state, diagnosis.decision);
+        this.store.writeState(state);
+        if (diagnosis.decision === 'NEEDS_USER' || diagnosis.decision === 'RUNTIME_BUG')
+            return 'needs_user';
+        if (diagnosis.decision === 'RESUME_CHILD') {
+            return result.childId && retries < MAX_EXECUTOR_INTERRUPT_RETRIES ? 'resume' : 'fallback';
+        }
+        return state.current_step?.id === step.id && !signal?.aborted && retries < MAX_EXECUTOR_INTERRUPT_RETRIES ? 'restart' : 'fallback';
+    }
+    // ── guards ─────────────────────────────────────────────────────────────────
+    async recordGuardBlock(code, reason) {
+        const state = this.store.readState();
+        if (!state)
+            return { disposition: 'block_continue', code, count: 0, watchdog_calls: 0, instruction: GUARD_FIRST_INSTRUCTION };
+        const stepId = state.current_step?.id ?? state.plan.steps.find((candidate) => candidate.status === 'running')?.id ?? '';
+        const count = recordGuardRecovery(state, stepId, code);
+        this.store.writeState(state);
+        if (count < GUARD_ESCALATION_THRESHOLD) {
+            return {
+                disposition: 'block_continue',
+                code,
+                count,
+                watchdog_calls: 0,
+                instruction: count >= 2 ? GUARD_REPEAT_INSTRUCTION : GUARD_FIRST_INSTRUCTION,
+            };
+        }
+        if (count > GUARD_RECOVERY_CAP)
+            return this.guardNeedsUser(state, code, reason, count);
+        const watchdog = await this.guardEscalation(state, code, count);
+        if (watchdog.decision === 'NEEDS_USER')
+            return this.guardNeedsUser(state, code, reason, count, watchdog.instruction);
+        return { disposition: 'block_continue', code, count, watchdog_calls: 1, instruction: watchdog.instruction ?? GUARD_RETRY_INSTRUCTION };
+    }
+    async guardEscalation(state, code, count) {
+        const result = await this.runAuxRole(state, {
+            role: 'watchdog',
+            label: 'watchdog-guard',
+            prompt: WATCHDOG_GUARD_PROMPT(code, count, state.current_step?.id ?? ''),
+            outputSchema: WATCHDOG_GUARD_SCHEMA,
+        });
+        if (!result || result.interrupted)
+            return this.guardWatchdogFallback(count);
+        try {
+            return assertGuardWatchdogDecision(result.structured);
+        }
+        catch {
+            return this.guardWatchdogFallback(count);
+        }
+    }
+    guardWatchdogFallback(count) {
+        return count >= GUARD_RECOVERY_CAP
+            ? { decision: 'NEEDS_USER', instruction: GUARD_NEEDS_USER_INSTRUCTION }
+            : { decision: 'RETRY_DIFFERENTLY', instruction: GUARD_RETRY_INSTRUCTION };
+    }
+    guardNeedsUser(state, code, reason, count, instruction) {
+        enterNeedsUser(state, `ORBIT_GUARD_ESCALATION: ${reason.slice(0, 300)}`);
+        this.store.writeState(state);
+        return { disposition: 'block_needs_user', code, count, watchdog_calls: 0, instruction: instruction ?? GUARD_NEEDS_USER_INSTRUCTION };
+    }
+    // ── role lifecycle helpers ─────────────────────────────────────────────────
+    /**
+     * One-shot auxiliary role (watchdogs and similar). Always releases the handle,
+     * even on interruption or timeout.
+     */
+    async runAuxRole(state, request) {
+        const names = request.role === 'watchdog' ? this.config.watchdogTools : this.config.commanderReadOnlyTools;
+        let handle;
+        try {
+            handle = await this.host.startRole({
+                role: request.role,
+                label: request.label,
+                prompt: request.prompt,
+                route: state.routes[request.role],
+                toolFilter: this.toolAllow(names, request.role),
+                ...(request.outputSchema ? { outputSchema: request.outputSchema } : {}),
+                ...(request.signal ? { signal: request.signal } : {}),
+            });
+            const timeoutMs = request.timeoutMs ?? this.config.watchdogTimeoutMs ?? WATCHDOG_TIMEOUT_MS;
+            const raced = await this.raceWithSleep(handle.result, timeoutMs, request.signal);
+            if (raced.kind === 'work')
+                return raced.value;
+            await this.cancelHandle(handle, raced.kind === 'aborted' ? 'ORBIT_ABORTED' : 'WATCHDOG_TIMEOUT');
+            return {
+                ...(handle.childId ? { childId: handle.childId } : {}),
+                output: '',
+                interrupted: true,
+                reason: raced.kind === 'aborted' ? 'ORBIT_ABORTED' : 'WATCHDOG_TIMEOUT',
+            };
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            if (handle)
+                await this.disposeHandle(handle);
+        }
+    }
+    async cancelHandle(handle, reason) {
+        try {
+            if (handle.cancel)
+                await handle.cancel(reason);
+            else
+                await this.host.interruptRole(handle, reason);
+        }
+        catch {
+            // cancellation is best-effort; dispose still runs
+        }
+    }
+    async disposeHandle(handle) {
+        try {
+            if (handle.dispose)
+                await handle.dispose();
+            else
+                await this.host.releaseRole(handle);
+        }
+        catch {
+            // idempotent cleanup
+        }
+    }
+    /** Race a work promise against a sleeping deadline, aborting the timer cleanly. */
+    async raceWithSleep(work, timeoutMs, signal) {
+        const controller = new AbortController();
+        const onAbort = () => controller.abort();
+        signal?.addEventListener('abort', onAbort, { once: true });
+        const timeout = this.host
+            .sleep(timeoutMs, controller.signal)
+            .then(() => ({ kind: 'timeout' }))
+            .catch(() => ({ kind: 'aborted' }));
+        try {
+            return await Promise.race([
+                work.then((value) => {
+                    controller.abort();
+                    return { kind: 'work', value };
+                }),
+                timeout,
+            ]);
+        }
+        finally {
+            controller.abort();
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    // ── lifecycle ──────────────────────────────────────────────────────────────
+    stop(action, runId) {
+        const state = this.store.readState();
+        if (!state)
+            return { ok: false, action, message: 'ORBIT_RUN_NOT_FOUND: no active run.' };
+        if (runId && runId !== state.run_id)
+            return { ok: false, action, message: `ORBIT_RUN_NOT_FOUND: ${runId}` };
+        stopRun(state);
+        this.store.writeState(state);
+        return this.result(state, true);
+    }
+    async status() {
+        const state = this.store.readState();
+        if (!state)
+            return { ok: false, action: 'status', message: 'ORBIT_RUN_NOT_FOUND: no run state.' };
+        return this.result(state, true);
+    }
+    result(state, ok, message) {
+        // Tool output must be lossless JSON: optional state fields are omitted, not
+        // emitted as `undefined`.
+        const data = {
+            goal: state.goal,
+            preset: state.preset,
+            loop: state.loop,
+            remaining_budget: state.remaining_budget,
+            current_step: state.current_step,
+            child: state.child,
+            plan: state.plan,
+            commander: state.commander,
+            smart_watchdog: state.smart_watchdog,
+            strategy_challenge: state.strategy_challenge,
+            guard_recovery: state.guard_recovery,
+            last_error: state.last_error,
+            changed_files: state.changed_files,
+            test_summary: state.test_summary,
+            driver_ownership: state.driver_ownership,
+            state_revision: state.state_revision,
+        };
+        return {
+            ok,
+            action: 'run',
+            run_id: state.run_id,
+            phase: state.phase,
+            status: state.status,
+            ...(message ? { message } : {}),
+            data: Object.fromEntries(Object.entries(data).filter(([, value]) => value !== undefined)),
+        };
+    }
+}
+export { DEFAULT_CAPABILITIES };