mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-03 07:18:03 +01:00
garrytanandcapy-ai[bot]
ee2ce02e58
Standing approvals: the newest row about autoplan recommendations decides, so a later refusal blocks older grants; rows whose id or date is not the recorded shape are never cited; the project is fixed at init from the plan's physical path (run.json project_root) so a symlinked plans folder or a checkpoint restore cannot borrow another repository's record. Gate cost: recReopens counts every phase revise can keep or add and prices answers already recorded at the gate; run --json emits one payload; the Captain brief's ### Cost sits above the relaying trailer. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
488 lines
36 KiB
TypeScript
488 lines
36 KiB
TypeScript
/**
|
||
* autoplan-run — the unattended /autoplan loop as an explicit, durable state
|
||
* machine (plan B2). The run directory the parent chose (`--out`) holds
|
||
* `run.json` (the B0 manifest, extended with the runner's state), an
|
||
* append-only `attempts.jsonl` journal (dispatch intent before anything
|
||
* else, so a crash is reconcilable), `run.lock` (one writer at a time),
|
||
* `spend.json` (lib/spend-ledger.ts) and every prompt, result and consensus
|
||
* file. `next` prepares the current phase (snapshot, prompts), journals one
|
||
* attempt per pending voice and stops with `awaiting_result`; `submit` binds
|
||
* a reviewer's result (receipt, canonical findings, model family) exactly
|
||
* once, settles its reservation and closes the phase through reconciliation
|
||
* (lib/autoplan-gate.ts) when both voices are terminal; `resume` takes
|
||
* ownership and marks attempts with intent but no terminal record
|
||
* EXECUTION_UNKNOWN, never redispatching them on its own. Thin bin:
|
||
* bin/gstack-autoplan.
|
||
*/
|
||
import * as crypto from 'node:crypto';
|
||
import * as fs from 'node:fs';
|
||
import * as os from 'node:os';
|
||
import * as path from 'node:path';
|
||
import { canonicalRows, parseReceipt, parseRecordFindings, parseReviewResult, type CanonicalFinding } from './autoplan-reconcile';
|
||
import { amendmentSteps, applyGuidance, closeDeferred, closePhase, finishGate } from './autoplan-gate';
|
||
import { GSTACK_VERSION } from './autoplan-migrate';
|
||
import { driftLine, normalizeFindingFile, repoRoot, reviewHash, scaffold } from './autoplan-plan-text';
|
||
import { PHASES, SNAPSHOT_TOOL, attemptFile, bindPromptResult, detectScope, driverFile, extractHeading, phaseOrder, reviewSkillFile, scopeLines, scopeSourceLabel, sectionLoadFor, snapshotTool, writePrompts, type Phase, type Scope, type ScopeFlags } from './autoplan-prompts';
|
||
import { recoverRevise } from './autoplan-revise';
|
||
import { FILES, RunError, journal, now, pendingAmendments, readDecisions, readJournal, readState, voiceTerminal, writeState, type AttemptState, type PhaseState, type RunState, type Voice, type VoiceState } from './autoplan-state';
|
||
import { checkPlanReality, checkRealityRows, PLAN_REALITY_CHECKER } from './plan-reality';
|
||
import type { RunStatus } from './headless-artifacts';
|
||
import { sha256File } from './headless-artifacts';
|
||
import { outsideConsent } from './outside-consent';
|
||
import { familyConflict, modelFamily } from './outside-voice-runner';
|
||
import { renderSpend, reserve, settle, summarize, readLedger } from './spend-ledger';
|
||
import { DEFAULT_MAX_ROUNDS, attemptEstimate, overCap, resumeStop, roundCap, roundOf, roundsLine, stopForBudget, stopLines } from './autoplan-budget';
|
||
import { annotateConfirm, confirmBlock } from './autoplan-confirm';
|
||
|
||
/** An unreadable run.lock younger than this is a lock some other gstack is still writing, never a stale one. */
|
||
const LOCK_WRITE_GRACE_MS = 30_000;
|
||
|
||
/** Exclusive ownership for one command: a lock whose pid is alive is never stolen; a dead pid's lock is reclaimed. */
|
||
export function withRunLock<T>(out: string, fn: () => T, opts: { steal?: boolean } = {}): T {
|
||
fs.mkdirSync(out, { recursive: true });
|
||
const lock = path.join(out, FILES.lock);
|
||
const mine = JSON.stringify({ pid: process.pid, host: os.hostname(), at: now() });
|
||
const staged = `${lock}.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
|
||
fs.writeFileSync(staged, mine);
|
||
for (let i = 0; ; i++) {
|
||
try {
|
||
fs.linkSync(staged, lock);
|
||
fs.unlinkSync(staged);
|
||
break;
|
||
} catch (e: any) {
|
||
if (e.code !== 'EEXIST') { fs.rmSync(staged, { force: true }); throw e; }
|
||
let owner: { pid?: number; host?: string; at?: string } = {};
|
||
let unreadable = false;
|
||
try { owner = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch { unreadable = true; }
|
||
let alive = false;
|
||
if (unreadable) {
|
||
try { alive = Date.now() - fs.statSync(lock).mtimeMs < LOCK_WRITE_GRACE_MS; } catch { /* gone: retry the link */ }
|
||
} else if (owner.host === os.hostname() && typeof owner.pid === 'number') {
|
||
try { process.kill(owner.pid, 0); alive = true; } catch (k: any) { alive = k.code === 'EPERM'; }
|
||
} else if (owner.host && owner.host !== os.hostname()) alive = !opts.steal;
|
||
if (alive) { fs.rmSync(staged, { force: true }); throw new RunError('RUN_LOCKED', unreadable ? `${lock} is being written by another command` : `pid ${owner.pid} on ${owner.host} since ${owner.at}`, 3); }
|
||
try { fs.unlinkSync(lock); } catch { /* raced with its owner's exit */ }
|
||
if (i > 50) { fs.rmSync(staged, { force: true }); throw new RunError('RUN_LOCKED', `could not reclaim ${lock}`, 3); }
|
||
}
|
||
}
|
||
try { return fn(); } finally { try { if (fs.readFileSync(lock, 'utf8') === mine) fs.unlinkSync(lock); } catch { /* already gone */ } }
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// init
|
||
// ---------------------------------------------------------------------------
|
||
export interface InitOptions { plan: string; out: string; cwd: string; scope?: ScopeFlags; planHeading?: string; outsideEnabled?: boolean; spendCap?: number | null; sessionKind?: string; deadlineMin?: number; light?: boolean; runId?: string; scaffold?: boolean; maxRounds?: number }
|
||
|
||
/** `lines` receives what init itself reports (SCAFFOLDED:). A plan with one section heading missing refuses, or with `scaffold` is reviewed from a scaffolded copy. */
|
||
export function initRun(o: InitOptions, lines: string[] = []): RunState {
|
||
const out = path.resolve(o.out);
|
||
const input = path.resolve(o.plan);
|
||
let source = input;
|
||
if (!fs.existsSync(source)) throw new Error(`plan not found: ${source}`);
|
||
// The plan's physical directory names the project: a symlinked plans/ folder must not borrow the link's repository.
|
||
const projectRoot = repoRoot(path.dirname(fs.realpathSync(input)));
|
||
let scaffolded = false;
|
||
if (o.planHeading) {
|
||
const section = extractHeading(fs.readFileSync(source, 'utf8'), o.planHeading);
|
||
if (section === undefined) throw new Error(`heading ${JSON.stringify(o.planHeading)} not found in ${source}`);
|
||
fs.mkdirSync(out, { recursive: true });
|
||
source = path.join(out, FILES.source);
|
||
fs.writeFileSync(source, section);
|
||
} else {
|
||
const diag = scaffold(fs.readFileSync(source, 'utf8'));
|
||
if (diag.problem && (!o.scaffold || !diag.text)) throw new RunError('PLAN_SECTIONS_INVALID', `${source}: ${diag.problem}`, 3);
|
||
if (diag.text) {
|
||
fs.mkdirSync(out, { recursive: true });
|
||
source = path.join(out, FILES.source);
|
||
fs.writeFileSync(source, diag.text);
|
||
scaffolded = true;
|
||
lines.push(`SCAFFOLDED: added "${diag.added}" (copy at ${source}; ${input} unchanged)`);
|
||
}
|
||
}
|
||
fs.mkdirSync(out, { recursive: true });
|
||
const active = path.join(out, FILES.active);
|
||
const restore = path.join(out, FILES.restore);
|
||
const init = snapshotTool(['init', source, active, restore], o.cwd);
|
||
const scope = detectScope(active, o.cwd, o.scope ?? {}, path.resolve(o.plan));
|
||
const order = phaseOrder(scope);
|
||
const run = o.runId ?? `${path.basename(out)}-${new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14)}`;
|
||
// codex_reviews gates the outside voice here, before any dispatch: a refusal is a terminal not_run outcome per phase.
|
||
const consent = (o.outsideEnabled ?? true) ? outsideConsent({ userInvoked: false }) : undefined;
|
||
const consentMissing = consent && !consent.allowed ? consent.lines[0] : undefined;
|
||
const sessionKind = o.sessionKind ?? process.env.GSTACK_SESSION_KIND ?? 'unattended';
|
||
const phases: Record<string, PhaseState> = {};
|
||
for (const p of PHASES) if (!order.includes(p)) phases[p] = { skipped: p === 'design' ? 'no UI scope detected' : 'no developer-facing scope detected', native: { status: 'skipped' }, outside: { status: 'skipped' } };
|
||
const state: RunState = {
|
||
schema_version: 1, run, status: 'running', required_phases: order, phases, artifacts: {}, revision: 0, out,
|
||
plan_source: init.sourcePlan, active_plan: init.activePlan, restore: init.restorePath, scope, phase_order: order,
|
||
outside_enabled: (o.outsideEnabled ?? true) && !consentMissing, attempt_counter: 0, spend_cap_usd: o.spendCap ?? null,
|
||
...(consentMissing ? { outside_not_run: { reason: 'consent_missing', detail: consentMissing } } : {}),
|
||
session_kind: sessionKind, host: 'gstack-autoplan', max_rounds: o.maxRounds ?? (sessionKind === 'unattended' ? DEFAULT_MAX_ROUNDS : null), history: [], created_at: now(), updated_at: now(),
|
||
deviations: ['autoplan guard: not enforced by this host; publication order is unverified (GUARD_NOT_INSTALLED)'],
|
||
...(o.deadlineMin ? { deadline_at: new Date(Date.now() + o.deadlineMin * 60_000).toISOString() } : {}),
|
||
...(o.light ? { light: true } : {}),
|
||
gstack_version: GSTACK_VERSION, plan_input: input, scope_flags: { ...(o.scope ?? {}) }, ...(projectRoot ? { project_root: projectRoot } : {}),
|
||
...(o.planHeading ? { plan_heading: o.planHeading } : {}), ...(scaffolded ? { scaffolded: true } : {}),
|
||
};
|
||
fs.writeFileSync(path.join(out, 'timing.json'), JSON.stringify({ schema_version: 1, run, phases: [], started_at: now(), session_kind: state.session_kind }, null, 2) + '\n');
|
||
journal(out, { event: 'init', run, plan_source: source, scope, phase_order: order, ...(consentMissing ? { outside: 'not_run', reason: 'consent_missing' } : {}) });
|
||
writeState(state);
|
||
return state;
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// next
|
||
// ---------------------------------------------------------------------------
|
||
export function currentPhase(state: RunState): Phase | undefined {
|
||
return state.phase_order.find(p => !state.phases[p]?.closed_at);
|
||
}
|
||
export function voiceState(state: RunState, phase: Phase, voice: Voice): VoiceState {
|
||
const ps = (state.phases[phase] ??= {});
|
||
return (ps[voice] ??= { status: 'pending' });
|
||
}
|
||
const openAttempt = (v: VoiceState) => v.attempts?.find(a => a.state === 'dispatched' || a.state === 'execution_unknown');
|
||
|
||
export interface NextOptions { out: string; cwd: string; estimateUsd?: number; redispatch?: string[] }
|
||
export interface NextResult { state: RunState; phase?: Phase; attempts: Array<{ attempt: string; voice: Voice; prompt: string; result: string; model_family: string; new: boolean }>; lines: string[] }
|
||
|
||
function openPhase(state: RunState, phase: Phase, cwd: string): void {
|
||
const ps = (state.phases[phase] ??= {});
|
||
if (ps.snapshot) return;
|
||
const methodology = snapshotTool(['methodology', phase, reviewSkillFile(phase), state.restore], cwd);
|
||
const snap = snapshotTool(['create', phase, state.active_plan, state.restore, methodology.methodologyPath], cwd);
|
||
// Every later phase reviews with its closed predecessors' consensus as data
|
||
// (not only Eng): a DX or design reviewer who never saw the CEO consensus
|
||
// re-raises what the CEO phase already reconciled (field gate rev 2).
|
||
const prior: Array<{ phase: string; text: string }> = [];
|
||
for (const p of state.phase_order) {
|
||
if (p === phase) break;
|
||
if (!state.phases[p]?.closed_at) continue;
|
||
const file = path.join(state.out, `${p}-consensus.md`);
|
||
if (!fs.existsSync(file)) throw new RunError('CONSENSUS_MISSING', `${p} closed without ${p}-consensus.md`, 3);
|
||
prior.push({ phase: p, text: fs.readFileSync(file, 'utf8') });
|
||
}
|
||
const sections = sectionLoadFor(phase, state.scope, state.session_kind === 'unattended' || state.light ? 'light' : 'full');
|
||
const decided = (state.gate_rev ?? 0) >= 1 ? readDecisions(state.out).filter(r => r.chosen != null && r.status !== 'pending')
|
||
.map(r => `r${r.gate_rev} ${(r.label ?? r.id).toLowerCase()}${r.chosen} ${r.title}${r.chosen_text ? ` -> ${r.chosen_text}` : ''}`) : [];
|
||
const confirm = confirmBlock(state, phase, snap.snapshotPath, roundOf(state, phase));
|
||
const prompts = writePrompts({ phase, snapshot: { nativePrompt: snap.nativePrompt, snapshotPath: snap.snapshotPath, sha256: snap.sha256 }, outDir: state.out, priorConsensus: prior, sections, decided, confirm: confirm?.text });
|
||
if (confirm) ps.confirm = confirm.confirm;
|
||
ps.snapshot = snap.sha256; ps.snapshot_dir = path.dirname(snap.snapshotPath); ps.snapshot_path = snap.snapshotPath; ps.methodology = methodology.methodologyPath; ps.opened_at = now();
|
||
ps.sections = { loaded: sections.loaded, skipped: sections.skipped, checklist: !!sections.checklist };
|
||
ps.native = { status: 'pending', attempts: [] };
|
||
const notRun = state.outside_not_run as { reason: string; detail: string } | undefined;
|
||
ps.outside = state.outside_enabled ? { status: 'pending', attempts: [] }
|
||
: notRun ? { status: 'disabled', outcome: 'not_run', reason: notRun.reason, detail: notRun.detail } : { status: 'disabled' };
|
||
ps.prompts = prompts;
|
||
journal(state.out, { event: 'phase_opened', phase, snapshot: snap.sha256, prompts: Object.fromEntries(Object.entries(prompts).map(([k, p]) => [k, path.relative(state.out, p)])) });
|
||
}
|
||
|
||
export function nextStep(o: NextOptions): NextResult {
|
||
const state = readState(path.resolve(o.out));
|
||
const lines: string[] = [];
|
||
const result: NextResult = { state, attempts: [], lines };
|
||
if (state.status === 'incomplete' && state.stop) { lines.push(...stopLines(state)); return result; }
|
||
if (state.status === 'gate_pending' || state.status === 'complete' || state.status === 'incomplete' || state.status === 'refused') return result;
|
||
if (state.deadline_at && Date.parse(state.deadline_at) < Date.now()) { state.status = 'interrupted'; writeState(state); lines.push(`DEADLINE: passed at ${state.deadline_at}`); return result; }
|
||
const pending = pendingAmendments(state).map(a => a.decision);
|
||
if (pending.length) {
|
||
const each = pendingAmendments(state).map(a => `APPLY ${a.item ?? a.decision}: ${applyGuidance(a)}`).join('; ');
|
||
throw new RunError('PLAN_AMEND_PENDING', `accepted at the gate but not in the plan: ${pending.join(', ')} (${each}); ${amendmentSteps(state, state.out)} (or --withdraw <id>)`, 3);
|
||
}
|
||
let phase = currentPhase(state);
|
||
while (phase && !state.phases[phase]?.snapshot && overCap(state, phase)) {
|
||
lines.push(...closeDeferred(state, phase, { reason: `round cap: round ${roundOf(state, phase)} would pass max ${roundCap(state, phase)}`, by: 'runner', cause: 'cap' }).lines);
|
||
phase = currentPhase(state);
|
||
}
|
||
if (!phase) { finishGate(state); writeState(state); return result; }
|
||
const first = !state.phase_order.some(p => state.phases[p]?.snapshot);
|
||
openPhase(state, phase, o.cwd);
|
||
const ps = state.phases[phase]!;
|
||
result.phase = phase;
|
||
lines.push(`PHASE: ${phase} snapshot=${ps.snapshot} order=${state.phase_order.join(',')}`);
|
||
const drift = driftLine(state, 'PLAN_CHANGED');
|
||
if (drift) lines.push(drift);
|
||
if (first) lines.push(...scopeLines(state.scope), `DRIVER: ${driverFile()}`);
|
||
if (ps.outside?.reason === 'consent_missing') lines.push(`OUTSIDE: ${phase} not_run reason=consent_missing`, String(ps.outside.detail));
|
||
if (ps.sections) lines.push(`Skipped sections: ${ps.sections.skipped.length ? ps.sections.skipped.join(',') : 'none'} (scope: ui=${state.scope.ui ? 'yes' : 'no'},dx=${state.scope.dx ? 'yes' : 'no'},source=${scopeSourceLabel(state.scope)}; checklist=${ps.sections.checklist ? 'loaded' : 'none'})`);
|
||
const prompts = ps.prompts!;
|
||
const estimate = attemptEstimate(state, o.estimateUsd, process.env);
|
||
if (estimate.line) lines.push(estimate.line);
|
||
const fresh = (['native', 'outside'] as const).filter(voice => { const v = voiceState(state, phase!, voice); const open = openAttempt(v); return !voiceTerminal(v) && (!open || (open.state === 'execution_unknown' && o.redispatch?.includes(open.attempt))); });
|
||
const before = summarize(readLedger(path.join(state.out, FILES.spend), state.spend_cap_usd));
|
||
if (state.spend_cap_usd !== null && fresh.length && before.worst_case_usd + fresh.length * estimate.usd > state.spend_cap_usd + 1e-9) {
|
||
const stop = stopForBudget(state, phase, fresh.length * estimate.usd);
|
||
writeState(state);
|
||
throw new RunError('SPEND_CAP_EXCEEDED', `spent ${before.spent_usd} + reserved ${before.reserved_usd} + unknown ${before.unknown_usd} + ${fresh.length} x estimate ${estimate.usd} > cap ${state.spend_cap_usd}; the run stopped incomplete (budget_exhausted)`, 3, { status: 'incomplete', lines: [...lines, ...stop] });
|
||
}
|
||
for (const voice of ['native', 'outside'] as const) {
|
||
const v = voiceState(state, phase, voice);
|
||
if (voiceTerminal(v)) continue;
|
||
const open = openAttempt(v);
|
||
if (open?.state === 'execution_unknown') {
|
||
if (!o.redispatch?.includes(open.attempt)) throw new RunError('EXECUTION_UNKNOWN', `${open.attempt} (${phase} ${voice})`, 3);
|
||
open.state = 'superseded'; open.terminal_at = now();
|
||
settle(path.join(state.out, FILES.spend), open.attempt, 'unknown');
|
||
journal(state.out, { event: 'superseded', attempt: open.attempt, phase, voice });
|
||
} else if (open) {
|
||
result.attempts.push({ attempt: open.attempt, voice, prompt: open.prompt, result: open.result, model_family: familyHint(state, voice), new: false });
|
||
continue;
|
||
}
|
||
const attempt = `${state.run}-a${++state.attempt_counter}`;
|
||
try { reserve(path.join(state.out, FILES.spend), attempt, estimate.usd, { cap: state.spend_cap_usd, label: `${phase}/${voice}` }); }
|
||
catch (e: any) { if (e.code === 'SPEND_CAP_EXCEEDED') { state.attempt_counter--; writeState(state); throw new RunError('SPEND_CAP_EXCEEDED', e.message, 3); } throw e; }
|
||
const row: AttemptState = { attempt, state: 'dispatched', prompt: prompts[voice], result: path.join(state.out, attemptFile(phase, voice, attempt.slice(state.run.length + 1), 'md')), estimate_usd: estimate.usd, dispatched_at: now() };
|
||
bindPromptResult(row.prompt, row.result);
|
||
journal(state.out, { event: 'dispatched', attempt, phase, voice, snapshot: ps.snapshot, prompt: path.relative(state.out, row.prompt), prompt_sha256: sha256File(row.prompt), result: path.relative(state.out, row.result), estimate_usd: estimate.usd });
|
||
(v.attempts ??= []).push(row);
|
||
v.attempt = attempt; v.status = 'running';
|
||
result.attempts.push({ attempt, voice, prompt: row.prompt, result: row.result, model_family: familyHint(state, voice), new: true });
|
||
}
|
||
state.status = 'awaiting_result';
|
||
writeState(state);
|
||
for (const a of result.attempts) lines.push(`ATTEMPT: ${a.attempt} phase=${phase} voice=${a.voice} prompt=${a.prompt} result=${a.result} model_family=${a.model_family}${a.new ? '' : ' (open)'}`);
|
||
lines.push(renderSpend(summarize(readLedger(path.join(state.out, FILES.spend)))), roundsLine(state));
|
||
return result;
|
||
}
|
||
function familyHint(state: RunState, voice: Voice): string {
|
||
if (voice === 'native') return state.native_model ? `same as ${state.native_model}` : 'the parent’s own model (recorded at submit)';
|
||
return state.native_model ? `not ${modelFamily(state.native_model)}` : 'differs from the native reviewer';
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// submit
|
||
// ---------------------------------------------------------------------------
|
||
export interface SubmitOptions {
|
||
out: string; phase: string; voice: Voice; model?: string; cwd: string; runner?: string; usageUsd?: number; reconcile?: string;
|
||
/** Exactly one of: a canonical result, a hand-run record, or a terminal outside outcome. */
|
||
result?: string; record?: string; unavailable?: string; failed?: string;
|
||
/** Optional when exactly one attempt is open for the phase and voice; required for an attested bind. */
|
||
attempt?: string; attest?: string;
|
||
}
|
||
export interface SubmitResult { state: RunState; closed: boolean; findings: number; lines: string[] }
|
||
|
||
/** Report-only PLAN_REALITY on the active plan, once per Implementation-plan hash and checker (revise clears it). */
|
||
function recordPlanReality(state: RunState): string[] {
|
||
let text: string;
|
||
try { text = fs.readFileSync(state.active_plan, 'utf8'); } catch { return []; }
|
||
const sha = reviewHash(text);
|
||
if (state.plan_reality?.plan_sha256 === sha && state.plan_reality.checker === PLAN_REALITY_CHECKER) return [];
|
||
const rows = checkRealityRows(text, { phase: 'plan', sessionKind: state.session_kind });
|
||
const plan = checkPlanReality(text, { sessionKind: state.session_kind });
|
||
const verdict = rows.verdict !== 'complete' ? rows.verdict : plan.verdict;
|
||
state.plan_reality = { plan_sha256: sha, checker: PLAN_REALITY_CHECKER, verdict, line: `${rows.line}; ${plan.line}` };
|
||
journal(state.out, { event: 'plan_reality', plan_sha256: sha, checker: PLAN_REALITY_CHECKER, verdict });
|
||
return [`${rows.line} (report only)`, `${plan.line} (report only)`, ...plan.numberLines];
|
||
}
|
||
|
||
function resolveAttempt(v: VoiceState, attempt: string | undefined, phase: string, voice: Voice): AttemptState {
|
||
const open = openAttempt(v);
|
||
if (!open || (attempt !== undefined && open.attempt !== attempt)) {
|
||
throw new RunError('ATTEMPT_MISMATCH', `${attempt ?? '(none given)'} is not the open attempt for ${phase} ${voice}${open ? ` (${open.attempt} is)` : ''}`, 3);
|
||
}
|
||
return open;
|
||
}
|
||
|
||
/** The record's receipt and findings: a matching INPUT line binds verified; none binds only on --attest with --attempt, never across a later revise. */
|
||
function readRecord(state: RunState, phase: Phase, open: AttemptState, o: SubmitOptions, text: string): { findings: CanonicalFinding[]; source: VoiceState['findings_source']; receipt: 'verified' | 'attested' } {
|
||
const receipt = parseReceipt(text, { phase, sha256: state.phases[phase]!.snapshot! });
|
||
if (receipt.present && !receipt.ok) throw new RunError('RESULT_RECEIPT_MISSING', receipt.error!);
|
||
if (!receipt.present) {
|
||
if (!o.attest) throw new RunError('RESULT_RECEIPT_MISSING', `${o.record} has no INPUT: ${phase} <sha256> line; bind it on your word with --attest "<reason>" --attempt ${open.attempt}, or have the reviewer start with the INPUT line its prompt names`);
|
||
if (!o.attempt) throw new RunError('ATTEMPT_MISMATCH', `an attested bind names its attempt: pass --attempt ${open.attempt}`, 3);
|
||
const revised = readJournal(state.out).find(r => r.event === 'plan_revised' && String(r.ts) > open.dispatched_at);
|
||
if (revised) throw new RunError('RESULT_RECEIPT_MISSING', `the plan was revised after ${open.attempt} was dispatched (${revised.ts}); an attestation cannot say which plan was read: redispatch with gstack-autoplan next --redispatch, or bind a record with the INPUT line`);
|
||
}
|
||
const parsed = parseRecordFindings(text);
|
||
if (parsed.errors.length) throw new RunError('RESULT_FINDINGS_MISSING', parsed.errors.join('; '));
|
||
return { findings: parsed.findings, source: parsed.source, receipt: receipt.present ? 'verified' : 'attested' };
|
||
}
|
||
|
||
export function submitResult(o: SubmitOptions): SubmitResult {
|
||
const state = readState(path.resolve(o.out));
|
||
if (!(PHASES as readonly string[]).includes(o.phase)) throw new RunError('PHASE_NOT_AWAITING', `${o.phase} is not a phase`, 3);
|
||
const phase = o.phase as Phase;
|
||
const ps = state.phases[phase];
|
||
const v = ps?.[o.voice];
|
||
if (ps?.skipped) throw new RunError('PHASE_NOT_AWAITING', `${phase} is skipped (${ps.skipped})`, 3);
|
||
if (!ps?.snapshot) throw new RunError('PHASE_NOT_AWAITING', `${phase} has not been opened; run gstack-autoplan next --out ${state.out} first`, 3);
|
||
if (!v || ps.closed_at || voiceTerminal(v)) throw new RunError('PHASE_NOT_AWAITING', `${phase} ${o.voice} is ${v?.status ?? 'not opened'}`, 3);
|
||
if (o.unavailable !== undefined || o.failed !== undefined) {
|
||
const lines = closeOutside(state, phase, o.unavailable !== undefined ? 'unavailable' : 'failed', (o.unavailable ?? o.failed)!);
|
||
writeState(state);
|
||
return { state, closed: !!ps.closed_at, findings: 0, lines };
|
||
}
|
||
const open = resolveAttempt(v, o.attempt, phase, o.voice);
|
||
const file = (o.record ?? o.result)!;
|
||
const owner = new RegExp(`^${phase}-${o.voice}\\.(a\\d+)\\.md$`).exec(path.basename(file));
|
||
if (owner && path.dirname(path.resolve(file)) === state.out && `${state.run}-${owner[1]}` !== open.attempt) {
|
||
throw new RunError('ATTEMPT_MISMATCH', `${path.basename(file)} is the result path of ${state.run}-${owner[1]}, not of the open attempt ${open.attempt} (result=${open.result})`, 3);
|
||
}
|
||
if (!fs.existsSync(file)) throw new RunError('RESULT_RECEIPT_MISSING', `result file not found: ${file}`);
|
||
const text = fs.readFileSync(file, 'utf8');
|
||
let bind: ReturnType<typeof readRecord>;
|
||
if (o.record) bind = readRecord(state, phase, open, o, text);
|
||
else {
|
||
const parsed = parseReviewResult(text, { phase, sha256: ps.snapshot });
|
||
if (!parsed.receipt.ok) throw new RunError('RESULT_RECEIPT_MISSING', parsed.errors[0]!);
|
||
if (!parsed.fenceFound || parsed.errors.length) throw new RunError('RESULT_FINDINGS_MISSING', parsed.errors.join('; '));
|
||
bind = { findings: parsed.findings, source: 'fence', receipt: 'verified' };
|
||
}
|
||
const model = o.model!;
|
||
let conflict: string | undefined;
|
||
if (o.voice === 'outside') conflict = familyConflict(model, state.native_model);
|
||
else if (state.outside_model) conflict = familyConflict(state.outside_model, model);
|
||
else if (modelFamily(model) === 'unknown') conflict = `native model ${JSON.stringify(model)} has no recognized family`;
|
||
if (conflict) throw new RunError('MODEL_FAMILY_CONFLICT', conflict, 3);
|
||
|
||
// Bind: a sealed copy of the reviewer's bytes under an attempt-owned name the reviewer never writes, per-voice
|
||
// canonical rows, journal, ledger, manifest. Nothing above this line wrote; a later edit of `file` changes nothing bound.
|
||
const bound = path.join(state.out, attemptFile(phase, o.voice, open.attempt.slice(state.run.length + 1), 'bound.md'));
|
||
const tmp = `${bound}.${process.pid}.tmp`;
|
||
fs.writeFileSync(tmp, text, process.platform === 'win32' ? {} : { mode: 0o444 });
|
||
fs.renameSync(tmp, bound);
|
||
if (process.env.GSTACK_AUTOPLAN_FAULT === 'submit-after-seal') throw new Error('fault injected: submit interrupted after sealing (GSTACK_AUTOPLAN_FAULT, tests only)');
|
||
const planFiles = [ps.snapshot_path, ps.snapshot_path && path.join(path.dirname(ps.snapshot_path), 'source-implementation.md'), state.active_plan].filter((p): p is string => !!p);
|
||
const pathCtx = { cwd: o.cwd, planFiles, planSource: state.plan_source, planName: path.basename(state.plan_input ?? state.plan_source) };
|
||
const round = roundOf(state, phase);
|
||
const rows = canonicalRows(bind.findings.map(f => { const { file, line, ...rest } = f; return { ...rest, ...normalizeFindingFile({ file, line }, pathCtx) }; }), { run: state.run, phase, voice: o.voice, model, round });
|
||
const confirm = round > 1 ? annotateConfirm(state, phase, rows, { planName: pathCtx.planName, planSource: state.plan_source, snapshotPath: ps.snapshot_path! }) : undefined;
|
||
fs.writeFileSync(`${bound}.findings.jsonl`, rows.map(r => JSON.stringify(r)).join('\n') + (rows.length ? '\n' : ''));
|
||
const sha = sha256File(bound);
|
||
const provider = o.runner ?? 'host-subagent';
|
||
const receipt = { receipt: bind.receipt, findings_source: bind.source, reviewed_sha256: ps.snapshot, ...(bind.receipt === 'attested' ? { attest_reason: o.attest } : {}) };
|
||
journal(state.out, { event: 'submitted', attempt: open.attempt, phase, voice: o.voice, result: path.basename(bound), result_sha256: sha, model, runner: provider, findings: rows.length, usage_usd: o.usageUsd ?? 'unknown', ...receipt });
|
||
settle(path.join(state.out, FILES.spend), open.attempt, o.usageUsd ?? 'unknown');
|
||
open.state = 'submitted'; open.terminal_at = now();
|
||
Object.assign(v, { status: 'completed', model, provider, output: path.basename(bound), result_sha256: sha, findings: rows.length, attempt: open.attempt, usage: { usd: o.usageUsd ?? 'unknown' }, ...receipt } satisfies Partial<VoiceState>);
|
||
if (bind.receipt === 'attested') (state.deviations ??= []).push(`receipt attested: ${phase} ${o.voice} ${open.attempt} bound from a hand-run record without a reviewer receipt (snapshot ${ps.snapshot.slice(0, 12)}; reason: ${o.attest})`);
|
||
state.artifacts[path.basename(bound)] = { path: path.basename(bound), sha256: sha };
|
||
if (o.voice === 'native') state.native_model = model; else state.outside_model = model;
|
||
const lines = [`BOUND: ${open.attempt} phase=${phase} voice=${o.voice} model=${model} findings=${rows.length} sha256=${sha.slice(0, 12)} receipt=${bind.receipt}${confirm ? ` round=${round} correlated=${confirm.correlated} settled=${confirm.settled}` : ''}`];
|
||
lines.push(...recordPlanReality(state));
|
||
const closed = ps.native?.status === 'completed' && voiceTerminal(ps.outside);
|
||
if (closed) lines.push(...closeAndAdvance(state, phase, o.reconcile));
|
||
else state.status = 'awaiting_result';
|
||
writeState(state);
|
||
return { state, closed, findings: rows.length, lines };
|
||
}
|
||
|
||
function closeAndAdvance(state: RunState, phase: Phase, reconcile?: string): string[] {
|
||
const close = closePhase(state, phase, { overridesFile: reconcile });
|
||
if (!currentPhase(state)) finishGate(state); else state.status = 'running';
|
||
return [`PHASE_CLOSED: ${phase} confirmed=${close.consensus.confirmed}${close.consensus.unverified ? ` unverified=${close.consensus.unverified}` : ''} disagree=${close.consensus.disagree} new=${close.consensus.new} native_only=${close.consensus.native_only} coverage=${close.consensus.coverage}`];
|
||
}
|
||
|
||
/**
|
||
* Record the outside voice of `phase` unavailable or failed: its open attempt
|
||
* is cancelled and the outcome journaled with that attempt id before the
|
||
* manifest is written (resume replays it); closes the phase when native is bound.
|
||
*/
|
||
export function closeOutside(state: RunState, phase: Phase, status: 'unavailable' | 'failed', detail: string): string[] {
|
||
const v = voiceState(state, phase, 'outside');
|
||
const open = openAttempt(v);
|
||
journal(state.out, { event: 'outside_' + status, phase, attempt: open?.attempt ?? null, detail });
|
||
if (open) { open.state = 'cancelled'; open.terminal_at = now(); settle(path.join(state.out, FILES.spend), open.attempt, 'unknown'); }
|
||
Object.assign(v, { status, detail });
|
||
const lines = [`OUTSIDE: ${phase} ${status} (${detail})`];
|
||
if (state.phases[phase]?.native?.status === 'completed') lines.push(...closeAndAdvance(state, phase));
|
||
else if (state.status !== 'gate_pending') state.status = 'awaiting_result';
|
||
return lines;
|
||
}
|
||
|
||
/** Mark the outside voice of the current phase unavailable/failed (the runner could not run); closes the phase if native is bound. */
|
||
export function markOutside(out: string, phase: Phase, status: 'unavailable' | 'failed', detail: string): RunState {
|
||
const state = readState(out);
|
||
closeOutside(state, phase, status, detail);
|
||
writeState(state);
|
||
return state;
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// resume
|
||
// ---------------------------------------------------------------------------
|
||
export interface ResumeResult { state: RunState; unknown: string[]; rebound: string[]; lines: string[] }
|
||
|
||
export function resumeRun(out: string): ResumeResult {
|
||
const recovered = recoverRevise(out);
|
||
const state = readState(out);
|
||
const rows = readJournal(out);
|
||
const terminal = new Set(rows.filter(r => ['submitted', 'cancelled', 'superseded', 'outside_unavailable', 'outside_failed', 'attempt_deferred'].includes(r.event)).map(r => r.attempt));
|
||
const unknown: string[] = [];
|
||
const rebound: string[] = [];
|
||
// An outside outcome journaled before its manifest write: replay it onto the attempt it names, never onto a later round.
|
||
for (const r of rows) {
|
||
if (r.event !== 'outside_unavailable' && r.event !== 'outside_failed') continue;
|
||
const ps = state.phases[r.phase];
|
||
const v = ps?.outside;
|
||
const a = v?.attempts?.find(x => x.attempt === r.attempt);
|
||
if (!a || !v || voiceTerminal(v) || ps.closed_at) continue;
|
||
if (a.state === 'dispatched' || a.state === 'execution_unknown') { a.state = 'cancelled'; a.terminal_at = r.ts; }
|
||
Object.assign(v, { status: r.event.slice('outside_'.length), detail: r.detail });
|
||
}
|
||
for (const r of rows) {
|
||
if (r.event !== 'dispatched') continue;
|
||
const ps = state.phases[r.phase];
|
||
const v = ps?.[r.voice as Voice];
|
||
const a = v?.attempts?.find(x => x.attempt === r.attempt);
|
||
if (terminal.has(r.attempt)) {
|
||
// A submit that journaled but died before run.json: re-bind from the journal and the file on disk.
|
||
const sub = rows.find(x => x.event === 'submitted' && x.attempt === r.attempt);
|
||
const result = sub && path.resolve(out, sub.result);
|
||
if (sub && result && a && a.state !== 'submitted' && fs.existsSync(result) && sha256File(result) === sub.result_sha256) {
|
||
a.state = 'submitted'; a.terminal_at = sub.ts;
|
||
Object.assign(v!, { status: 'completed', model: sub.model, provider: sub.runner ?? 'unknown', output: path.basename(result), result_sha256: sub.result_sha256, findings: sub.findings, attempt: sub.attempt,
|
||
...(sub.receipt ? { receipt: sub.receipt, findings_source: sub.findings_source, reviewed_sha256: sub.reviewed_sha256, ...(sub.attest_reason ? { attest_reason: sub.attest_reason } : {}) } : {}) });
|
||
state.artifacts[path.basename(result)] = { path: path.basename(result), sha256: sub.result_sha256 };
|
||
if (r.voice === 'native') state.native_model = sub.model; else state.outside_model = sub.model;
|
||
rebound.push(r.attempt);
|
||
}
|
||
continue;
|
||
}
|
||
if (!a) { (v!.attempts ??= []).push({ attempt: r.attempt, state: 'execution_unknown', prompt: path.resolve(out, r.prompt), result: path.resolve(out, r.result), estimate_usd: r.estimate_usd ?? 0, dispatched_at: r.ts }); v!.status = 'running'; }
|
||
else if (a.state === 'dispatched') a.state = 'execution_unknown';
|
||
else continue;
|
||
journal(out, { event: 'execution_unknown', attempt: r.attempt, phase: r.phase, voice: r.voice, by: 'resume' });
|
||
unknown.push(r.attempt);
|
||
}
|
||
for (const phase of state.phase_order) {
|
||
const ps = state.phases[phase];
|
||
if (!ps?.snapshot || ps.closed_at) continue;
|
||
if (ps.native?.status === 'completed' && voiceTerminal(ps.outside)) closePhase(state, phase, {});
|
||
}
|
||
const stopped = resumeStop(state);
|
||
if (!currentPhase(state) && !['gate_pending', 'amend_pending', 'complete', 'incomplete', 'refused'].includes(state.status)) finishGate(state);
|
||
else if (state.status === 'interrupted' || state.status === 'running' || state.status === 'awaiting_result') {
|
||
const anyOpen = state.phase_order.some(p => (['native', 'outside'] as const).some(v => openAttempt(voiceState(state, p, v))));
|
||
state.status = anyOpen ? 'awaiting_result' : 'running';
|
||
}
|
||
journal(out, { event: 'resumed', unknown, rebound, status: state.status });
|
||
writeState(state);
|
||
const lines = [...recovered, ...stopped, `RESUMED: run=${state.run} status=${state.status} execution_unknown=${unknown.length} rebound=${rebound.length}`];
|
||
for (const a of unknown) lines.push(`EXECUTION_UNKNOWN: ${a}`);
|
||
return { state, unknown, rebound, lines };
|
||
}
|
||
|
||
export function statusLines(state: RunState): string[] {
|
||
const lines = [`RUN: ${state.run} status=${state.status} revision=${state.revision} out=${state.out}`, `SCOPE: ui=${state.scope.ui} dx=${state.scope.dx} order=${state.phase_order.join(',')} gate_rev=${state.gate_rev ?? 0}`];
|
||
for (const p of PHASES) {
|
||
const ps = state.phases[p];
|
||
if (!ps) { lines.push(`PHASE: ${p} pending`); continue; }
|
||
if (ps.skipped) { lines.push(`PHASE: ${p} skipped (${ps.skipped})`); continue; }
|
||
const v = (voice: Voice) => { const s = ps[voice]; return `${voice}=${s?.status ?? 'pending'}${s?.model ? `:${s.model}` : ''}${s?.attempt ? `@${s.attempt}` : ''}`; };
|
||
lines.push(`PHASE: ${p} ${ps.closed_at ? (ps.deferred ? `closed-deferred(${ps.deferred.reason})` : 'closed') : ps.snapshot ? 'open' : 'pending'} ${v('native')} ${v('outside')}${ps.consensus ? ` confirmed=${(ps.consensus as any).confirmed} disagree=${(ps.consensus as any).disagree} new=${(ps.consensus as any).new}` : ''}`);
|
||
}
|
||
for (const a of pendingAmendments(state)) lines.push(`AMEND_PENDING: ${a.decision} ${a.item ?? ''}${a.changes ? ` changes=${a.changes}` : ''} -> ${applyGuidance(a)}`);
|
||
for (const p of state.phase_order) for (const voice of ['native', 'outside'] as const) {
|
||
const open = state.phases[p]?.[voice] && openAttempt(state.phases[p]![voice]!);
|
||
if (open) lines.push(`PENDING: ${open.attempt} phase=${p} voice=${voice} result=${open.result}`);
|
||
}
|
||
if (fs.existsSync(path.join(state.out, FILES.spend))) lines.push(renderSpend(summarize(readLedger(path.join(state.out, FILES.spend)))));
|
||
lines.push(roundsLine(state), ...stopLines(state));
|
||
for (const d of state.capped_deltas ?? []) lines.push(`CAPPED_DELTA: v${d.k} ${d.phase} +${d.added} -${d.removed} ${d.status}`);
|
||
return lines;
|
||
}
|
||
export const TERMINAL: readonly RunStatus[] = ['complete', 'gate_pending', 'amend_pending', 'incomplete', 'refused', 'interrupted'];
|
||
export { SNAPSHOT_TOOL, RunError, FILES, readState, writeState, readJournal, journal };
|
||
export type { RunState, Voice, VoiceState, AttemptState };
|