@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/decision/FactContinuations.js

@@ -0,0 +1,472 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { checkRunners, commandLine, isCheckCall, isReplaySafeCheck, isVerificationCheck } from './checks.js';
+export const PREPARE_FINISH = 'prepare_finish';
+export const FACT_CONTINUATION_GUIDANCE = 'Minimize model turns: batch independent reads and related file writes. Do not spend a turn only announcing a plan. When prepare_finish is available, implementation is finished and the verification is test, build, lint or typecheck commands, call prepare_finish LAST in the final edit batch (its description says how); for any other verification, finish normally. Do not add discretionary QA after the requested verification is sufficient. User instructions, workspace requirements and graph completion contracts still apply.';
+/** The tool description, naming the shell the model actually has. */
+export function prepareFinishDescription(shell = 'PowerShell') {
+    return `After finishing implementation, call LAST in your final edit batch with the checks to run and your complete final result. The runtime runs the checks through normal approvals, completes the verification todos you name and submits the result without another coding-model call; a failed or unclear check returns control to you. Each check is one standalone test, build, lint or typecheck command with the timeout you would give it yourself, e.g. {"name": "${shell}", "arguments": {"command": "npm run build", "timeout": 300000}}: one entry per command, no ;, &&, ||, pipes, redirects or conditionals. Do not add optional QA. completion.tests must be [] (the runtime records what ran).`;
+}
+/**
+ * Repairs shape slips that would otherwise cost a whole coding-model turn, without changing what
+ * runs: a note beside a check (`justification`, `description`), a check whose arguments were written
+ * beside its name, a bare command given as the tool name, and evidence lines in completion.tests,
+ * which the runtime fills in itself. Everything else is left for validation to reject.
+ */
+export function prepareFinishArguments(args, tools) {
+    if (!object(args))
+        return args;
+    const next = { ...args };
+    if (Array.isArray(args.checks))
+        next.checks = args.checks.map((raw) => {
+            if (!object(raw) || typeof raw.name !== 'string')
+                return raw;
+            const { justification: _justification, description: _description, ...item } = raw;
+            let { name, arguments: given, ...fields } = item;
+            if (given === undefined) {
+                given = fields;
+                fields = {};
+            }
+            if (!tools.has(name) && tools.shell && object(given) && !Object.keys(given).length && /\s/.test(name.trim())) {
+                given = { command: name.trim() };
+                name = tools.shell;
+            }
+            return { name, arguments: given, ...fields };
+        });
+    if (object(args.completion) && Array.isArray(args.completion.tests) && args.completion.tests.length)
+        next.completion = { ...args.completion, tests: [] };
+    return next;
+}
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const canonical = (v) => Array.isArray(v) ? v.map(canonical) : object(v)
+    ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)).map(([k, x]) => [k, canonical(x)])) : v;
+// A note or a longer deadline does not change what a check verifies: the same command run again
+// with another description or timeout replaces its earlier evidence instead of standing beside it.
+const NOT_IDENTITY = new Set(['description', 'justification', 'timeout', 'timeout_ms']);
+export const checkKey = (call) => createHash('sha256').update(call.name + ':' + JSON.stringify(canonical(Object.fromEntries(Object.entries(call.arguments).filter(([key]) => !NOT_IDENTITY.has(key)))))).digest('hex');
+const metadata = new Set([PREPARE_FINISH, 'update_todos', 'update_widget']);
+const probability = (value, bar) => value === undefined || !Number.isFinite(value) || value < 0 || value > 1 ? undefined : value >= bar - 1e-9 ? true : value <= 1 - bar + 1e-9 ? false : undefined;
+const concrete = (o) => ({ name: o.call.name, arguments: structuredClone(o.args) });
+const description = (call) => commandLine(call.arguments) ?? call.name;
+const FAILURE_TEXT = /(?:^|\n)\s*(?:Exit code: [1-9]\d*|[ℹ#]\s*fail\s+[1-9]\d*|Test Suites:\s*[1-9]\d* failed)|\b[1-9]\d* failed\b|\b(?:FAIL|FAILED)\b|error TS\d+/m;
+/** A JSON report's own verdict; null when the output is not a report that decides one. */
+function structuredVerdict(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null; /* Shell text is handled by the caller. */
+    }
+    if (!object(value))
+        return null;
+    // QA reports contain an aggregate verdict, while the displayed result rows can be
+    // truncated (qa.deep returns at most 25 of up to 32 checks). Never let passing
+    // displayed rows override a failed or blocked overall run/merge gate.
+    if (['issues', 'failed', 'blocked', 'dirty'].includes(String(value.verdict ?? value.status)))
+        return false;
+    if (object(value.gate) && ['failed', 'blocked'].includes(String(value.gate.verdict)))
+        return false;
+    // Unknown verdicts/gates are not positive verification evidence.
+    if (value.verdict !== undefined && !['clean', 'ready'].includes(String(value.verdict)))
+        return undefined;
+    if (value.gate !== undefined && (!object(value.gate) || value.gate.verdict !== 'ready'))
+        return undefined;
+    const rows = Array.isArray(value.results) ? value.results : [value];
+    if (rows.some(r => object(r) && ['failed', 'blocked'].includes(String(r.status))))
+        return false;
+    // A QA pipeline where every check was skipped is not verification.
+    if (rows.length && rows.every(r => object(r) && ['passed', 'skipped'].includes(String(r.status)))) {
+        return rows.some(r => object(r) && r.status === 'passed') ? true : undefined;
+    }
+    return null;
+}
+/** Exact owned outputs can be settled locally. Unknown or clipped formats are not a pass. */
+export function localCheckResult(observation) {
+    if (observation.isError || !observation.executionSucceeded)
+        return false;
+    if (observation.localCheckStatus !== undefined)
+        return observation.localCheckStatus;
+    const text = observation.output.replace(/\x1b\[[0-9;]*m/g, '');
+    // A report's own verdict comes first: exit 0 never turns a reported failure into a pass.
+    const structured = structuredVerdict(text);
+    if (structured === false)
+        return false;
+    // An exit status is exact even when the output was clipped: a standalone verification command
+    // (no pipeline, isVerificationCheck) exits 0 only when it passed. A failure the runner printed
+    // but did not exit on still counts, and a report that leaves its verdict open stays open.
+    if (observation.exitCode !== undefined) {
+        if (observation.exitCode !== 0 || FAILURE_TEXT.test(text))
+            return false;
+        return structured === null ? true : structured;
+    }
+    if (observation.truncated)
+        return undefined;
+    if (structured !== null)
+        return structured;
+    if (FAILURE_TEXT.test(text))
+        return false;
+    if (/(?:^|\n)\s*(?:Exit code: 0|[ℹ#]\s*fail\s+0)\s*(?:\n|$)/m.test(text))
+        return true;
+    return undefined;
+}
+export function taskConstraints(task, nodeInstruction = '') {
+    const noChecks = /\b(?:do not|don't|never)\s+(?:run|execute|perform)\s+(?:any\s+)?(?:checks|qa|verification)\b|\bonly\s+generat(?:e|es)\s+(?:the\s+)?code\b/i.test(task);
+    const noTests = noChecks || /\b(?:do not|don't|never)\s+(?:run|execute)\s+(?:any\s+|automated\s+)?tests\b/i.test(task);
+    const text = task + '\n' + nodeInstruction;
+    const commands = [];
+    const addCommand = (command) => {
+        const normalized = command.trim();
+        if (normalized && !commands.includes(normalized))
+            commands.push(normalized);
+    };
+    // A required command is a task constraint even when it uses a custom script name
+    // unknown to the check-runner allowlist. This list is for coverage, NOT permission
+    // to auto-execute a command. Unsupported commands force the coding model to finish.
+    for (const match of text.matchAll(/[`"]([^`"\n]+)[`"]/g)) {
+        const command = match[1].trim();
+        const preceding = text.slice(Math.max(0, (match.index ?? 0) - 100), match.index ?? 0);
+        const requested = /\b(?:run|execute|rerun|re-run|must|required|requires|verify|check|before completing)\b[^.!?\n]{0,90}$/i.test(preceding);
+        if (isCheckCall('shell', 'shell', { command }) || requested && /^(?:npm|pnpm|yarn|bun|npx|node|python3?|pytest|cargo|go|make|dotnet|mvn|gradle|\.\/|\.\\\\)\s+\S+/i.test(command))
+            addCommand(command);
+    }
+    // Also capture unquoted imperatives, e.g. "run npm run ci:local before
+    // completing". Never infer an executable command merely from a script name.
+    for (const match of text.matchAll(/\b(?:run|execute|rerun|re-run)\s+((?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?[\w:.-]+)|(?:(?:npx|node|python3?|pytest|cargo|go|make|dotnet|mvn)\s+[^\s`"',;]+))/gi)) {
+        addCommand(match[1]);
+    }
+    const kinds = new Set();
+    if (!noTests && /\b(?:run|rerun|re-run|execute|pass|passing)\s+(?:the\s+|all\s+|affected\s+|required\s+)*(?:test(?:s|\s+suite)?|unit\s+tests)\b|\bmake sure\b[^.\n]{0,80}\btests?\b/i.test(text))
+        kinds.add('test');
+    if (!noChecks && /\b(?:run|execute)\s+(?:the\s+)?build\b|\bbuild\s+(?:the\s+)?(?:project|application|package)\b/i.test(text))
+        kinds.add('build');
+    if (!noChecks && /\b(?:run|execute)\s+(?:the\s+)?lint\b/i.test(text))
+        kinds.add('lint');
+    if (!noChecks && /\b(?:run|execute|keep)\b[^.\n]{0,50}\b(?:typecheck|type-check|type check|tsc)\b/i.test(text))
+        kinds.add('typecheck');
+    return { noTests, noChecks, commands: noChecks ? [] : commands.filter(c => !noTests || checkKind(c) !== 'test'), kinds };
+}
+function checkKind(line) {
+    if (/\b(?:tsc|typecheck|type-check|mypy)\b/.test(line))
+        return 'typecheck';
+    if (/\b(?:lint|eslint|ruff|clippy)\b/.test(line))
+        return 'lint';
+    if (/\bbuild\b/.test(line))
+        return 'build';
+    if (/\b(?:test|pytest|vitest|jest|unittest|mocha|ava|ctest)\b/.test(line))
+        return 'test';
+    return 'check';
+}
+/** Invocation-local policy. It never generates tool arguments or final answer text. */
+export class FactContinuations {
+    options;
+    revision = 0;
+    checks = new Map();
+    checkSeq = 0;
+    staged;
+    plan;
+    queued;
+    taskNeedsChecks;
+    taskNeedsChecksSource = 'deterministic';
+    retried = new Set();
+    rechecked = new Set();
+    pendingAutomatic;
+    task;
+    taskUpdated = false;
+    constraints;
+    syntheticCount = 0;
+    finishHint = false;
+    constructor(options) {
+        this.options = options;
+        this.task = options.task;
+        this.constraints = taskConstraints(this.task, [this.options.nodeInstruction, this.options.workspaceInstructions].filter(Boolean).join('\n'));
+    }
+    get finishing() { return this.finishHint; }
+    get proposed() { return !!this.plan || !!this.staged; }
+    async emit(action, data = {}) {
+        await this.options.emit('efficiency.facts.action', { action, ...data });
+    }
+    invalidate(reason, update) {
+        this.plan = this.staged = undefined;
+        this.queued = undefined;
+        this.pendingAutomatic = undefined;
+        this.finishHint = false;
+        if (update !== undefined || reason === 'steering' || reason === 'model_changed') {
+            if (reason === 'steering' || update !== undefined)
+                this.taskUpdated = true;
+            this.taskNeedsChecks = undefined;
+            this.taskNeedsChecksSource = 'deterministic';
+            this.checks.clear();
+            this.revision++;
+            if (update)
+                this.task += `\nLatest task update:\n${update}`;
+            this.constraints = taskConstraints(this.task, [this.options.nodeInstruction, this.options.workspaceInstructions].filter(Boolean).join('\n'));
+        }
+    }
+    /** An actual model call expires unexecuted proposals; it does not discard check failures. */
+    modelResumed() {
+        this.plan = this.staged = undefined;
+        this.queued = undefined;
+        this.pendingAutomatic = undefined;
+        this.syntheticCount = 0;
+    }
+    stage(args, lastInBatch) {
+        this.plan = this.staged = undefined;
+        this.queued = undefined;
+        if (this.taskUpdated)
+            throw new Error('Task was redirected; finish through the model under the updated requirements.');
+        const mandated = taskConstraints('', [this.options.nodeInstruction, this.options.workspaceInstructions].filter(Boolean).join('\n'));
+        if (this.constraints.noChecks && (mandated.commands.length || mandated.kinds.size)
+            || this.constraints.noTests && (mandated.kinds.has('test') || mandated.commands.some(c => checkKind(c) === 'test'))) {
+            throw new Error('Verification instructions conflict; automatic completion cannot waive required checks.');
+        }
+        if (!lastInBatch)
+            throw new Error('prepare_finish must be the final call in the batch.');
+        if (Object.keys(args).some(k => !['checks', 'completion', 'verificationTodoIds'].includes(k)) || !Array.isArray(args.checks)
+            || args.checks.length > 8 || !object(args.completion) || Buffer.byteLength(JSON.stringify(args)) > 16_384)
+            throw new Error('Invalid finish plan (maximum 8 checks and 16 KiB).');
+        const value = args.completion;
+        if (Object.keys(value).some(k => !['summary', 'tests', 'outcome', 'output', 'artifacts'].includes(k)))
+            throw new Error('Unknown completion field.');
+        if (typeof value.summary !== 'string' || !value.summary.trim() || !Array.isArray(value.tests) || value.tests.length) {
+            throw new Error('Provide the complete proposed summary and tests: []; observed check evidence is filled in by the runtime.');
+        }
+        const checks = args.checks.map((input) => {
+            if (!object(input) || Object.keys(input).some(k => !['name', 'arguments'].includes(k)) || typeof input.name !== 'string' || !object(input.arguments))
+                throw new Error('A check needs a name and exact arguments.');
+            const tool = this.options.catalog(input.name);
+            if (!tool)
+                throw new Error(`Unknown or unavailable tool "${input.name.slice(0, 80)}": a check is the shell tool's name with its arguments, e.g. {"name": "<shell>", "arguments": {"command": "npm test"}}.`);
+            if (!isVerificationCheck(input.name, tool.family, input.arguments)) {
+                // Say which check and what to do instead: a retried plan costs a whole coding-model turn.
+                const shown = (commandLine(input.arguments) ?? input.name).replace(/\s+/g, ' ').slice(0, 160);
+                throw new Error(`"${shown}" is not a standalone test, build, lint or typecheck command, so it cannot be prepared. Give each such command its own check, without ;, &&, ||, pipes, redirects or conditionals. If your verification is anything else, such as running your own script, do not call prepare_finish; finish normally.`);
+            }
+            const call = { name: input.name, arguments: structuredClone(input.arguments) };
+            if (this.constraints.noChecks || this.constraints.noTests && (checkKind(description(call)) === 'test' || /^qa\.(?:fast|test|deep)$/.test(call.name))) {
+                throw new Error('This check conflicts with the user\'s explicit verification opt-out.');
+            }
+            return call;
+        });
+        if (new Set(checks.map(checkKey)).size !== checks.length)
+            throw new Error('Duplicate prepared check.');
+        const ids = args.verificationTodoIds ?? [];
+        if (!Array.isArray(ids) || ids.length > 32 || ids.some(id => typeof id !== 'string') || new Set(ids).size !== ids.length)
+            throw new Error('Invalid verification todo ids.');
+        const todos = this.options.todos();
+        if (ids.some(id => { const todo = todos.find(t => t.id === id); return todo && !/^(?:run|rerun|re-run|verify|test|check|lint|build|typecheck|smoke)[ :\-]/i.test(todo.text); }))
+            throw new Error('Only explicitly verification-only todos may be completed automatically.');
+        if (ids.some(id => !todos.some(todo => todo.id === id)))
+            throw new Error('Verification todo does not exist.');
+        if (todos.some(todo => todo.status !== 'completed' && !ids.includes(todo.id)))
+            throw new Error('Finish implementation and other non-verification todos before preparing completion.');
+        if (ids.length && !checks.length)
+            throw new Error('Verification todos require declared checks.');
+        const alreadyPassed = [...this.checks.values()].filter(e => e.passed && e.pure && e.revision === this.revision).map(e => e.call);
+        if (!this.coversRequirements([...alreadyPassed, ...checks]))
+            throw new Error('The plan omits verification explicitly required by the task or node.');
+        this.staged = { checks, completion: structuredClone(value), verificationTodoIds: ids, permission: this.options.permission(), revision: this.revision };
+    }
+    coversRequirements(calls) {
+        const commands = new Set(calls.map(description));
+        const kinds = new Set(calls.map(c => checkKind(description(c))));
+        return this.constraints.commands.every(command => commands.has(command)) && [...this.constraints.kinds].every(kind => kinds.has(kind));
+    }
+    verified() {
+        const rows = [...this.checks.values()];
+        const current = (e) => e.passed === true && e.pure && e.revision === this.revision;
+        // A compound command (`npm run build; node --test`) can never prove a pass itself. It stops
+        // blocking once every runner it contains, including one nested in a conditional, has passed
+        // later, on its own, on the current workspace. Anything else in the line keeps it blocking (checkRunners).
+        const superseded = (e) => {
+            const runners = checkRunners(commandLine(e.call.arguments) ?? '');
+            return !!runners?.length && runners.every(command => rows.some(r => current(r) && r.seq > e.seq
+                && r.call.name === e.call.name && description(r.call) === command));
+        };
+        return rows.length > 0 && rows.every(e => current(e) || !e.pure && superseded(e)) && this.coversRequirements(rows.map(e => e.call));
+    }
+    async ask(input, signal) {
+        signal.throwIfAborted();
+        if (this.options.remoteFactsEnabled === false)
+            return undefined;
+        const start = performance.now();
+        const value = await this.options.fact(input, signal);
+        signal.throwIfAborted();
+        await this.options.emit('efficiency.facts.answered', { waitMs: Math.round(performance.now() - start), asked: [input.id], answered: value === undefined ? 0 : 1 });
+        return probability(value, input.id === 'checks_passed' ? .95 : .9);
+    }
+    async needsChecks(signal) {
+        if (this.constraints.noChecks) {
+            this.taskNeedsChecksSource = 'deterministic';
+            return false;
+        }
+        if (this.constraints.commands.length || this.constraints.kinds.size) {
+            this.taskNeedsChecksSource = 'deterministic';
+            return true;
+        }
+        if (this.taskNeedsChecks !== undefined)
+            return this.taskNeedsChecks;
+        const answer = await this.ask({ id: 'task_needs_checks', state: { task: [this.task, this.options.nodeInstruction ? `Node instruction (also part of the task):\n${this.options.nodeInstruction}` : ''].filter(Boolean).join('\n\n') } }, signal);
+        // Do not cache a timeout/unavailable/uncertain answer as a permanent fact.
+        if (answer !== undefined) {
+            this.taskNeedsChecks = answer;
+            this.taskNeedsChecksSource = 'jev';
+        }
+        return answer;
+    }
+    async observe(batch, signal) {
+        signal.throwIfAborted();
+        this.finishHint = false;
+        const automatic = this.pendingAutomatic;
+        this.pendingAutomatic = undefined;
+        const failed = batch.filter(o => o.isError || !o.executionSucceeded);
+        if (failed.some(o => o.readOnly || metadata.has(o.call.name)))
+            this.revision++;
+        const work = batch.filter(o => !metadata.has(o.call.name));
+        let wrote = false;
+        for (const observation of work) {
+            const call = concrete(observation);
+            const check = isCheckCall(call.name, observation.family, call.arguments);
+            const pure = isVerificationCheck(call.name, observation.family, call.arguments);
+            if (!observation.readOnly && !pure) {
+                this.revision++; // Failed writes/commands may have partially mutated the workspace too.
+                wrote ||= observation.family === 'filesystem-write' && !observation.isError && observation.executionSucceeded;
+            }
+            if (!check)
+                continue;
+            let passed = pure ? localCheckResult(observation) : undefined;
+            let source = 'deterministic';
+            // Only a result that can enable a continuation merits an external interpretation. A failed
+            // execution is known false; a compound command never proves the final workspace verified.
+            if (pure && passed === undefined && !observation.truncated && !failed.length && (this.plan || this.staged || this.options.todos().length > 0)) {
+                passed = await this.ask({ id: 'checks_passed', state: { tool_results: [{ tool: call.name, command: description(call), succeeded: observation.executionSucceeded && !observation.isError, output: observation.output }] } }, signal);
+                if (passed !== undefined)
+                    source = 'jev';
+            }
+            const key = checkKey(call);
+            this.checks.delete(key); // Re-inserted last, so the map's order is the order checks ran.
+            this.checks.set(key, { call, passed, pure, source, revision: this.revision, seq: ++this.checkSeq, evidence: `${description(call)}: ${passed === true ? 'passed' : passed === false ? 'failed' : 'unconfirmed'}` });
+        }
+        if (failed.length)
+            this.plan = this.staged = undefined;
+        if (this.staged) {
+            const declaration = batch.findIndex(o => o.call.name === PREPARE_FINISH);
+            if (declaration < 0 || declaration !== batch.length - 1 || failed.length
+                || work.some(o => o.family !== 'filesystem-write' && !isVerificationCheck(o.call.name, o.family, o.args)))
+                this.staged = undefined;
+            else {
+                this.staged.revision = this.revision;
+                this.plan = this.staged;
+                this.staged = undefined;
+                await this.options.emit('efficiency.prepared.declared', { steps: this.plan.checks.length + 1, chars: JSON.stringify(this.plan).length, triggers: 0 });
+            }
+        }
+        // Any later non-verification mutation invalidates the complete proposed result. A successful
+        // check itself does not, and only the explicitly named verification todos may be ticked off.
+        if (this.plan && (this.plan.revision !== this.revision || this.plan.permission !== this.options.permission()))
+            this.plan = undefined;
+        if (automatic?.kind === 'check' && this.plan) {
+            const evidence = automatic.tool && this.checks.get(checkKey(automatic.tool));
+            if (!evidence?.passed || evidence.revision !== this.revision)
+                this.plan = undefined;
+            else
+                this.plan.checks = this.plan.checks.filter(c => checkKey(c) !== checkKey(automatic.tool));
+        }
+        if (this.plan && !failed.length) {
+            const todos = this.options.todos();
+            if (todos.some(t => t.status !== 'completed' && !this.plan.verificationTodoIds.includes(t.id)))
+                this.plan = undefined;
+            else {
+                const next = this.plan.checks.find(c => {
+                    const e = this.checks.get(checkKey(c));
+                    return !e?.passed || e.revision !== this.revision;
+                });
+                if (next) {
+                    this.queue('check', next, this.verificationSource());
+                    return;
+                }
+                const noChecks = !this.checks.size && await this.needsChecks(signal) === false
+                    && (!this.options.workspaceInstructions?.trim() || this.constraints.noChecks);
+                if (this.verified() || noChecks) {
+                    const ids = this.plan.verificationTodoIds;
+                    if (todos.some(t => ids.includes(t.id) && t.status !== 'completed')) {
+                        this.queue('todos', { name: 'update_todos', arguments: { todos: todos.map(t => ids.includes(t.id) ? { ...t, status: 'completed' } : t) } }, noChecks ? this.taskNeedsChecksSource : this.verificationSource());
+                    }
+                    else {
+                        // Report what passed on the final workspace, not a compound command its parts superseded.
+                        const completion = { ...this.plan.completion, tests: [...this.checks.values()].filter(e => e.passed === true && e.pure && e.revision === this.revision).map(e => e.evidence) };
+                        this.queued = { id: randomUUID(), kind: 'complete', completion, permission: this.plan.permission, evidenceSource: noChecks ? this.taskNeedsChecksSource : this.verificationSource() };
+                    }
+                    return;
+                }
+                this.plan = undefined;
+            }
+        }
+        if (failed.length === 1 && this.syntheticCount < 3) {
+            const o = failed[0];
+            const call = concrete(o);
+            const key = checkKey(call);
+            if (o.readOnly && !this.retried.has(key) && !/denied|permission|not allowed|requires a complete Read|ENOENT|not found|invalid|unavailable/i.test(o.output)) {
+                if (await this.ask({ id: 'temporary_failure', state: { failed_call: [{ tool: call.name, command: description(call), error: o.output }] } }, signal) === true) {
+                    this.retried.add(key);
+                    this.queue('retry', call, 'jev');
+                    return;
+                }
+            }
+        }
+        const open = this.options.todos().filter(t => t.status !== 'completed');
+        const implementationOpen = open.some(t => !/^(?:run|rerun|re-run|verify|test|check|lint|build|typecheck|smoke)(?:[ :\-]|$)/i.test(t.text));
+        if (!this.taskUpdated && !failed.length && wrote && !implementationOpen && this.syntheticCount < 3) {
+            const previous = [...this.checks.values()].find(e => e.pure && e.passed === false && isReplaySafeCheck(e.call.name, this.options.catalog(e.call.name)?.family, e.call.arguments));
+            if (previous && await this.needsChecks(signal) === true) {
+                const key = `${this.revision}:${checkKey(previous.call)}`;
+                if (!this.rechecked.has(key)) {
+                    this.rechecked.add(key);
+                    this.queue('recheck', previous.call, previous.source === 'jev' || this.taskNeedsChecksSource === 'jev' ? 'jev' : 'deterministic');
+                    return;
+                }
+            }
+        }
+        if (!this.taskUpdated && !failed.length && this.options.todos().length > 0 && !open.length && this.verified()) {
+            this.finishHint = true;
+            await this.emit('finish_hint', { reason: 'required_checks_passed' });
+        }
+    }
+    verificationSource() {
+        return [...this.checks.values()].some(e => e.revision === this.revision && e.passed === true && e.source === 'jev') ? 'jev' : 'deterministic';
+    }
+    queue(kind, tool, evidenceSource = 'deterministic') {
+        this.queued = { id: randomUUID(), kind, tool: structuredClone(tool), permission: this.options.permission(), evidenceSource };
+    }
+    /** Called at the normal model boundary. Returning a value must not call the coding adapter. */
+    take(allowedTools) {
+        const next = this.queued;
+        this.queued = undefined;
+        if (!next)
+            return undefined;
+        if (next.permission !== this.options.permission() || (next.tool && !allowedTools.has(next.tool.name)) || !allowedTools.has('complete_agent') || this.syntheticCount >= 12) {
+            this.invalidate('stale_permissions_or_catalog');
+            return undefined;
+        }
+        if (this.plan) {
+            const todos = this.options.todos();
+            const ids = this.plan.verificationTodoIds;
+            if (todos.some(t => t.status !== 'completed' && !ids.includes(t.id))
+                || ids.some(id => !todos.some(t => t.id === id))) {
+                this.invalidate('todos_changed');
+                return undefined;
+            }
+            if (next.kind === 'todos' && next.tool)
+                next.tool.arguments = {
+                    todos: todos.map(t => ids.includes(t.id) ? { ...t, status: 'completed' } : t),
+                };
+            if (next.kind === 'complete' && todos.some(t => t.status !== 'completed'))
+                return undefined;
+        }
+        if (next.kind === 'complete' && (!this.plan || this.plan.revision !== this.revision))
+            return undefined;
+        this.syntheticCount++;
+        this.pendingAutomatic = next;
+        return next;
+    }
+    completionAccepted() { this.plan = this.staged = undefined; this.finishHint = false; }
+}

package/dist/src/decision/FactServiceGate.d.ts

@@ -0,0 +1,12 @@
+/** A request-scoped circuit: errors never become answers, and an outage must not delay every turn. */
+export declare class FactServiceGate {
+    private readonly now;
+    private until;
+    private reason;
+    private probe;
+    constructor(now?: () => number);
+    acquire(): boolean;
+    get blockedReason(): string;
+    success(): void;
+    failure(reason: string): void;
+}

package/dist/src/decision/FactServiceGate.js

@@ -0,0 +1,37 @@
+/** A request-scoped circuit: errors never become answers, and an outage must not delay every turn. */
+export class FactServiceGate {
+    now;
+    until = 0;
+    reason = '';
+    probe = false;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    acquire() {
+        if (this.until === 0)
+            return true;
+        if (this.now() < this.until || this.probe)
+            return false;
+        this.probe = true;
+        return true;
+    }
+    get blockedReason() { return this.reason || 'decision_service_unavailable'; }
+    success() {
+        // An older concurrent success cannot reopen a circuit another request just tripped.
+        if (this.until !== 0 && !this.probe)
+            return;
+        this.until = 0;
+        this.reason = '';
+        this.probe = false;
+    }
+    failure(reason) {
+        this.probe = false;
+        if (reason === 'cancelled' || reason === 'decision_input_too_large')
+            return;
+        this.reason = reason;
+        // A new run gets a fresh gate. An unsupported protocol or rejected credentials cannot be
+        // repaired by repeatedly issuing the same request inside the current run.
+        this.until = ['decision_protocol_unsupported', 'authentication_required', 'decision_daily_limit_reached', 'provider_unavailable'].includes(reason)
+            ? Infinity : this.now() + 30_000;
+    }
+}

package/dist/src/decision/PreparedSteps.d.ts

@@ -0,0 +1,51 @@
+import type { Completion } from '../runtime.js';
+import type { ModelResponse, Tool } from '../types.js';
+import type { DecisionBatch, DecisionCandidate } from './types.js';
+export declare const PREPARE_STEPS = "prepare_steps";
+/**
+ * A deterministic trigger: the step runs after the batch it followed without a decision request,
+ * when that batch's outcome matches. `success` is every execution call succeeded; `failure` is at
+ * least one failed; `always` is either. Only investigate and verify steps may declare one, and
+ * every other restriction on automatic actions (catalog, approvals, limits) still applies.
+ */
+export type PreparedTrigger = 'success' | 'failure' | 'always';
+export declare const PREPARED_TRIGGERS: readonly PreparedTrigger[];
+export interface PreparedStep extends DecisionCandidate {
+    tool?: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    completion?: Completion;
+    when?: PreparedTrigger;
+}
+export interface PreparedStepsOptions {
+    /** Accept `when` triggers; off keeps the shipped schema byte for byte. */
+    continuations?: boolean;
+    /** Preparation overhead, reported once per accepted call. */
+    onDeclared?: (declared: {
+        steps: number;
+        chars: number;
+        triggers: number;
+    }) => void;
+}
+export declare function boundedDecisionText(text: string, bytes: number): string;
+/** Deliberately narrower than tool families: no automatic retry of shell, browser or writes. */
+export declare function retrySafe(tool: Tool | undefined): boolean;
+/** Invocation-local concrete actions authored by the coding model; Jev may only select IDs. */
+export declare class PreparedSteps {
+    private steps;
+    clear(): void;
+    candidates(): DecisionCandidate[];
+    take(id: string): PreparedStep | undefined;
+    /** How many steps are held; a cleared set reports zero. */
+    get size(): number;
+    /**
+     * The first declared step whose trigger matches the batch outcome, removed from the set. The
+     * declaration order is the model's preference order; no scoring happens here.
+     */
+    takeTriggered(outcome: 'success' | 'failure'): PreparedStep | undefined;
+    tool(catalog: Tool[], options?: PreparedStepsOptions): Tool;
+}
+export declare function permittedContinuation(step: PreparedStep, batch: DecisionBatch): boolean;
+export declare function preparedResponse(step: PreparedStep, verification: string[]): ModelResponse;
+export declare function postToolGuidance(batch: DecisionBatch): string;