@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/governance/engine/stage-runner.js

@@ -0,0 +1,664 @@
+/**
+ * `gov_dispatch`: run one stage of the current phase (governance-mode 7.2, 8.2-8.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE DIVISION OF LABOUR. This module owns everything BEFORE and AFTER the children run:
+ * legality, budget, assignment, briefs, the stage record, the single automatic redispatch of
+ * whatever came back without a submission, the pause on abort, and the digest. It owns NONE
+ * of the judgement: when a child calls `gov_submit_*` / `ledger_*` the adjudication half
+ * (`submissions.ts`, `inspector.ts`) books the ledger and routes the work package
+ * synchronously inside that tool call. That is why a stage that is aborted half way keeps
+ * every submission already made, and why "resume re-runs only what is missing" needs no
+ * bookkeeping here: a routed WP is simply no longer eligible for the stage.
+ *
+ * A MISSING SUBMISSION IS NOT A MISDEED (8.4). Infrastructure failures, a model that
+ * wandered off and a context that ran out all look the same from here, so the first answer
+ * is one reminder-bearing redispatch of only the missing WPs, and the second is `blocked`
+ * with `blockedAt` set to this stage - never a deduction.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { assignRoundRobin } from '../roles.js';
+import { detectOwnershipViolations } from '../rules/suspicion.js';
+import { activeAgents } from '../rules/ledger-state.js';
+import { formatNotAccepted, isRecord, Issues } from '../tools/normalize-util.js';
+import { STAGE_KINDS } from '../types.js';
+import { accumulateUsage, shouldStopNewStages } from './budget.js';
+import { composeDigest, refusal } from './digest.js';
+import { openBudgetEscalation } from './lifecycle.js';
+import { applyPendingPause, pausedByUserRefusal } from './pause.js';
+import { recoverInterruptedStage } from './rebuild.js';
+import { renderLedgerLine } from './report.js';
+import { buildSubagentSpec } from './spec-builder.js';
+import { checkStage, markBlocked } from './state-machine.js';
+import { changeListOf, latestReview, latestTest, latestWork, pendingAppeal, reviewConclusion, reworkItemsFor, } from './submission-queries.js';
+const INSPECTOR_IDENTITY = 'insp';
+const PAUSE_RESUME_HINT = 'PAUSED: the stage was interrupted. Completed submissions were kept.';
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+function parseDispatchInput(raw) {
+    const issues = new Issues();
+    const args = isRecord(raw) ? raw : {};
+    const stage = issues.oneOf(args.stage, 'stage', STAGE_KINDS, { required: true });
+    const wps = issues
+        .list(args.wps, 'wps', 16, GOV_LIMITS.wpIdChars * 4)
+        .map((w) => w.toLowerCase());
+    const notes = {};
+    if (isRecord(args.notes)) {
+        for (const [key, value] of Object.entries(args.notes)) {
+            const text = typeof value === 'string' ? value.trim() : '';
+            if (text !== '')
+                notes[key.toLowerCase()] = text.slice(0, GOV_LIMITS.noteChars);
+        }
+    }
+    if (issues.errors.length > 0 || stage === undefined) {
+        return { ok: false, errors: issues.errors.length > 0 ? issues.errors : ['stage is required.'] };
+    }
+    return {
+        ok: true,
+        value: {
+            stage,
+            ...(wps.length > 0 ? { wps } : {}),
+            ...(Object.keys(notes).length > 0 ? { notes } : {}),
+        },
+        notes: issues.notes,
+    };
+}
+// ---------------------------------------------------------------------------
+// Assignment
+// ---------------------------------------------------------------------------
+/** Follow `replacedBy` links so a stale assignee id still resolves to a live identity. */
+function liveIdentity(core, id) {
+    let current = id;
+    for (let hops = 0; hops < 8; hops += 1) {
+        const record = core.ledger.agents[current];
+        if (record === undefined || record.replacedBy === null)
+            return current;
+        current = record.replacedBy;
+    }
+    return current;
+}
+function takeoverMap(core) {
+    const out = {};
+    for (const agent of Object.values(core.ledger.agents)) {
+        if (agent.replacedBy !== null)
+            out[agent.id] = agent.replacedBy;
+    }
+    return out;
+}
+function groupDevs(core, run, wpIds) {
+    const byIdentity = new Map();
+    for (const id of wpIds) {
+        const wp = run.workPackages[id];
+        if (wp === undefined)
+            continue;
+        const identity = liveIdentity(core, wp.assignee ?? 'dev1');
+        wp.assignee = identity;
+        byIdentity.set(identity, [...(byIdentity.get(identity) ?? []), id]);
+    }
+    return [...byIdentity.entries()].map(([identity, ids]) => ({
+        identity,
+        role: 'DEV',
+        wpIds: ids,
+    }));
+}
+function groupByRole(core, run, role, wpIds) {
+    const ceiling = core.deps.getTeamCeiling();
+    const identities = activeAgents(core.ledger, role)
+        .map((a) => a.id)
+        .slice(0, Math.max(1, ceiling));
+    const sticky = {};
+    for (const id of wpIds) {
+        const wp = run.workPackages[id];
+        const prior = role === 'REV' ? wp?.reviewer : wp?.tester;
+        if (prior)
+            sticky[id] = prior;
+    }
+    const assignments = assignRoundRobin({
+        wpIds,
+        identities,
+        sticky,
+        takeover: takeoverMap(core),
+    });
+    for (const a of assignments) {
+        for (const id of a.wpIds) {
+            const wp = run.workPackages[id];
+            if (wp === undefined)
+                continue;
+            if (role === 'REV')
+                wp.reviewer = a.identity;
+            else
+                wp.tester = a.identity;
+        }
+    }
+    return assignments.map((a) => ({ identity: a.identity, role, wpIds: a.wpIds }));
+}
+/** The newest integrate report of `phase` that carries an RCA (from the artifact cache). */
+function latestRca(core, phase) {
+    let best;
+    for (const item of core.submissionCache.values()) {
+        if (item.kind !== 'inspector' || item.stage !== 'integrate')
+            continue;
+        if (item.phase !== phase.index || item.rca === undefined)
+            continue;
+        if (best === undefined || item.at >= best.at)
+            best = item;
+    }
+    return best?.rca;
+}
+/**
+ * The WPs a `fix` stage works on: the ones whose DEV the last RCA names as primary or
+ * contributing (oversight reviewers and testers do not write code), else the whole phase.
+ */
+function fixTargets(core, run, phase, requested) {
+    if (requested.length > 0)
+        return [...requested];
+    const live = phase.wpIds.filter((id) => run.workPackages[id]?.status !== 'dropped');
+    const rca = latestRca(core, phase);
+    if (rca === undefined)
+        return live;
+    const devs = new Set(rca.attributions
+        .filter((a) => a.level !== 'oversight')
+        .map((a) => liveIdentity(core, a.agentId)));
+    const named = live.filter((id) => devs.has(liveIdentity(core, run.workPackages[id]?.assignee ?? '')));
+    return named.length > 0 ? named : live;
+}
+/** The RCA as prose for the fix brief (the failing checks, the boundary, who is attributed). */
+function rcaText(core, phase) {
+    const rca = latestRca(core, phase);
+    if (rca === undefined)
+        return undefined;
+    const checks = rca.failingChecks.map((c) => `${c.name} (${c.files.join(', ') || 'no files'})`);
+    const who = rca.attributions.map((a) => `${a.agentId} ${a.level}/${a.contract}: ${a.note}`);
+    return [
+        `Failing checks: ${checks.join('; ') || '(none recorded)'}`,
+        `Module boundary failure: ${rca.boundary ? 'yes' : 'no'}; ` +
+            `systemic: ${rca.systemic ? 'yes' : 'no'}`,
+        `Attribution: ${who.join(' | ') || '(none)'}`,
+    ]
+        .join('\n')
+        .slice(0, 1800);
+}
+function buildGroups(core, run, stage, phase, wpIds) {
+    switch (stage) {
+        case 'dev':
+            return groupDevs(core, run, wpIds);
+        case 'fix':
+            return groupDevs(core, run, fixTargets(core, run, phase, wpIds));
+        case 'review':
+            return groupByRole(core, run, 'REV', wpIds);
+        case 'test':
+            return groupByRole(core, run, 'TEST', wpIds);
+        case 'settle':
+        case 'integrate':
+            return [
+                {
+                    identity: INSPECTOR_IDENTITY,
+                    role: 'INSP',
+                    wpIds: phase.wpIds.filter((id) => run.workPackages[id]?.status !== 'dropped'),
+                },
+            ];
+    }
+}
+// ---------------------------------------------------------------------------
+// Briefs
+// ---------------------------------------------------------------------------
+function predecessorOf(core, identity) {
+    return Object.values(core.ledger.agents).find((a) => a.replacedBy === identity);
+}
+function digestFindings(wp, core) {
+    const review = latestReview(core, wp.id);
+    if (review === undefined)
+        return 'no review on record';
+    const findings = review.findings
+        .slice(0, 6)
+        .map((f) => `[${f.severity}] ${f.file}${f.line ? `:${f.line}` : ''} ${f.issue}`);
+    return `${review.verdict} by ${review.identity}; ${review.findings.length} finding(s)${findings.length > 0 ? `: ${findings.join(' | ')}` : ''}`.slice(0, 900);
+}
+function digestTest(wp, core) {
+    const test = latestTest(core, wp.id);
+    if (test === undefined)
+        return 'no test report on record';
+    const gaps = test.traceability.filter((t) => t.status !== 'covered').length;
+    return (`${test.verdict} by ${test.identity}; ${test.traceability.length} requirement(s), ` +
+        `${gaps} gap/unverified; ${test.issues.length} issue(s); ${test.claims.length} claim(s); ` +
+        `boundary tests ${test.boundaryTestsWritten ? 'written' : 'not written'}`).slice(0, 600);
+}
+function autoEventLines(core, phaseIndex) {
+    const rows = [];
+    for (const agent of Object.values(core.ledger.agents)) {
+        for (const entry of agent.history) {
+            if (entry.phase !== phaseIndex || entry.by !== 'engine')
+                continue;
+            if (typeof entry.code !== 'string' || entry.delta === 0)
+                continue;
+            rows.push({ seq: entry.seq, text: renderLedgerLine(entry, agent.id) });
+        }
+    }
+    return rows
+        .sort((a, b) => a.seq - b.seq)
+        .slice(-40)
+        .map((r) => r.text);
+}
+function inspectorMaterial(core, run, ctx) {
+    const wps = ctx.groups[0]?.wpIds.map((id) => run.workPackages[id]).filter((w) => w !== undefined) ?? [];
+    const reviewDigest = {};
+    const testDigest = {};
+    for (const wp of wps) {
+        reviewDigest[wp.id] = digestFindings(wp, core);
+        testDigest[wp.id] = digestTest(wp, core);
+    }
+    const health = core.health();
+    return {
+        autoEvents: autoEventLines(core, ctx.phase.index),
+        openClaims: run.claims
+            .filter((c) => c.status === 'open')
+            .map((c) => ({
+            id: c.id,
+            kind: c.kind,
+            raisedBy: c.raisedBy,
+            against: c.against,
+            wpId: c.wpId,
+            text: c.justification.slice(0, 300),
+        })),
+        flags: core.phaseFlags.get(ctx.phase.index) ?? [],
+        reviewDigest,
+        testDigest,
+        integrationAttempt: ctx.phase.integrationAttempts,
+        healthWarning: health !== null && health < GOV_LIMITS.healthWarnThreshold,
+        viewEvents: core.viewLog.get(ctx.phase.index) ?? [],
+    };
+}
+function briefFor(core, run, ctx, group, missingOnly) {
+    const wps = group.wpIds
+        .map((id) => run.workPackages[id])
+        .filter((w) => w !== undefined);
+    const record = core.ledger.agents[group.identity];
+    const predecessor = predecessorOf(core, group.identity);
+    const failure = predecessor ? core.ledger.failureAnalyses[predecessor.id] : undefined;
+    const peers = ctx.groups.filter((g) => g.identity !== group.identity).map((g) => g.identity);
+    const brief = {
+        run: {
+            runId: run.runId,
+            goal: run.goal,
+            profile: run.profile,
+            spec: ctx.specText,
+            contracts: run.contracts,
+            integrationCommands: run.integrationCommands,
+        },
+        identity: group.identity,
+        role: group.role,
+        generation: record?.generation ?? 0,
+        tokens: record ? record.confirmed + record.provisional : 0,
+        phase: ctx.phase.index + 1,
+        stage: ctx.stage,
+        wps,
+        peers,
+        ...(failure ? { predecessor: failure } : {}),
+        ...(missingOnly && missingOnly.length > 0 ? { missingOnly: [...missingOnly] } : {}),
+    };
+    return addRoleMaterial(core, run, ctx, brief);
+}
+function withRca(text) {
+    return text === undefined ? {} : { rcaText: text };
+}
+function addRoleMaterial(core, run, ctx, brief) {
+    const ids = brief.wps.map((w) => w.id);
+    switch (ctx.stage) {
+        case 'dev':
+        case 'fix': {
+            const requiredChanges = {};
+            const previousOwn = {};
+            for (const id of ids) {
+                const items = ctx.stage === 'dev' ? reworkItemsFor(core, id) : [];
+                if (items.length > 0)
+                    requiredChanges[id] = items;
+                const own = latestWork(core, id);
+                if (own)
+                    previousOwn[id] = own.summary.slice(0, 600);
+            }
+            return {
+                ...brief,
+                ...(Object.keys(requiredChanges).length > 0 ? { requiredChanges } : {}),
+                ...(Object.keys(previousOwn).length > 0 ? { previousOwn } : {}),
+                ...(Object.keys(ctx.notes).length > 0 ? { notes: ctx.notes } : {}),
+                ...(ctx.stage === 'fix' ? withRca(rcaText(core, ctx.phase)) : {}),
+            };
+        }
+        case 'review': {
+            const workSubmissions = {};
+            const appeals = {};
+            for (const id of ids) {
+                const work = latestWork(core, id);
+                if (work)
+                    workSubmissions[id] = work;
+                const appeal = pendingAppeal(core, id);
+                if (appeal)
+                    appeals[id] = appeal;
+            }
+            return { ...brief, workSubmissions, ...(Object.keys(appeals).length > 0 ? { appeals } : {}) };
+        }
+        case 'test': {
+            const changeLists = {};
+            const reviewVerdicts = {};
+            for (const id of ids) {
+                changeLists[id] = changeListOf(core, id);
+                const verdict = reviewConclusion(core, id);
+                if (verdict)
+                    reviewVerdicts[id] = verdict;
+            }
+            return { ...brief, changeLists, reviewVerdicts };
+        }
+        case 'settle':
+        case 'integrate':
+            return { ...brief, inspector: inspectorMaterial(core, run, ctx) };
+    }
+}
+// ---------------------------------------------------------------------------
+// Stage bookkeeping
+// ---------------------------------------------------------------------------
+const RUNNING_STATUS = {
+    dev: 'dev_running',
+    review: 'review_running',
+    test: 'test_running',
+};
+function markRunning(core, run, ctx) {
+    const status = RUNNING_STATUS[ctx.stage];
+    for (const group of ctx.groups) {
+        core.setAgentState(group.identity, 'queued');
+        if (status === undefined)
+            continue;
+        for (const id of group.wpIds) {
+            const wp = run.workPackages[id];
+            if (wp === undefined)
+                continue;
+            wp.status = status;
+            delete wp.blockedAt;
+        }
+    }
+    run.dispatches += 1;
+    run.status = 'executing';
+    run.stage = {
+        kind: ctx.stage,
+        phase: ctx.phase.index,
+        wpIds: ctx.groups.flatMap((g) => g.wpIds),
+        startedAt: core.now(),
+        status: 'running',
+    };
+    core.log('stage_started', 'engine', {
+        stage: ctx.stage,
+        phase: ctx.phase.index,
+        groups: ctx.groups.map((g) => ({ identity: g.identity, wps: g.wpIds })),
+    });
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'stage_started', snapshot }));
+}
+/** WPs of the stage that still lack a submission (or `['ledger_settle']` for the inspector). */
+function missingOf(core, ctx) {
+    if (ctx.stage === 'settle' || ctx.stage === 'integrate') {
+        return core.inspectorOutcome === null ? ['ledger_settle'] : [];
+    }
+    return ctx.groups.flatMap((g) => g.wpIds).filter((id) => !core.stageSubmitted.has(id));
+}
+function restrictGroups(groups, missing) {
+    const wanted = new Set(missing);
+    return groups
+        .map((g) => ({ ...g, wpIds: g.wpIds.filter((id) => wanted.has(id)) }))
+        .filter((g) => g.wpIds.length > 0 || g.role === 'INSP');
+}
+function noteOwnership(core, run, ctx, out) {
+    if (ctx.stage !== 'dev' && ctx.stage !== 'fix' && ctx.stage !== 'test')
+        return;
+    for (const child of out.runs) {
+        const group = ctx.groups.find((g) => g.identity === child.label);
+        if (group === undefined)
+            continue;
+        const owned = group.wpIds.flatMap((id) => run.workPackages[id]?.files ?? []);
+        const bad = detectOwnershipViolations(child.filesTouched, owned);
+        if (bad.length === 0)
+            continue;
+        const text = `${child.label} touched files outside its work package ` +
+            `(${group.wpIds.join(', ')}): ${bad.slice(0, 5).join(', ')}`;
+        core.phaseFlags.set(ctx.phase.index, [...(core.phaseFlags.get(ctx.phase.index) ?? []), text]);
+    }
+}
+function noteChildFailures(core, out) {
+    for (const child of out.runs) {
+        if (child.phase !== 'failed' || child.error === undefined)
+            continue;
+        core.stageWarnings.push(`${child.label} failed: ${child.error.slice(0, 160)}`);
+    }
+}
+async function dispatchGroups(core, run, ctx, groups, options) {
+    const specs = groups.map((g) => buildSubagentSpec(briefFor(core, run, { ...ctx, groups }, g, options.missingOnly ? g.wpIds : undefined)));
+    for (const g of groups)
+        core.setAgentState(g.identity, 'queued');
+    const outcome = await core.deps.withPausedWatchdog(() => core.deps.runtime.dispatch(specs, specs.length, options.controller.signal));
+    run.usage = accumulateUsage(run.usage, outcome, core.deps.modelCost?.());
+    noteOwnership(core, run, ctx, outcome);
+    noteChildFailures(core, outcome);
+    return outcome;
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/** `gov_dispatch`. Always returns text; an interrupted stage is `PAUSED:`, not an error. */
+export async function runStage(core, raw, signal) {
+    const run = core.run;
+    if (run === null)
+        return refusal(core, 'no governance run is active; call gov_run start first.');
+    const parsed = parseDispatchInput(raw);
+    if (!parsed.ok)
+        return formatNotAccepted('gov_dispatch', parsed.errors);
+    const { stage, wps, notes } = parsed.value;
+    // A pause the user asked for outranks a new stage, whatever the orchestrator wants:
+    // without this gate a parallel tool call could start one between the request and the
+    // stage end and quietly eat the pause. Its twin is the redeem point below; they land
+    // together or not at all (governance-mode-v1-1 V-3).
+    if (core.pauseRequested || core.userPaused)
+        return pausedByUserRefusal(core);
+    run.limits.budgetTokens = core.config().budgetTokens;
+    const legal = checkStage(run, stage, wps, { teamCeiling: core.deps.getTeamCeiling() });
+    if (!legal.ok)
+        return legal.message;
+    if (shouldStopNewStages(run.usage, run.limits.budgetTokens)) {
+        const escalation = openBudgetEscalation(core);
+        const flush = await core.flush();
+        const text = composeDigest(core, { headline: `ESCALATION: ${escalation.topic}` });
+        return flush === null ? text : `${text}\n${flush}`;
+    }
+    if (signal?.aborted) {
+        return composeDigest(core, {
+            headline: 'PAUSED: the call was interrupted before the stage started, so nothing was dispatched.',
+        });
+    }
+    const phase = run.phases[legal.phase];
+    const dropped = stage !== 'dev' && stage !== 'fix' && notes !== undefined;
+    core.resetStageScratch();
+    if (dropped) {
+        core.stageWarnings.push('NOTE: orchestrator notes are accepted for dev and fix only; they were discarded ' +
+            '(each role sees only what it is allowed to see).');
+    }
+    const controller = core.beginStage(signal);
+    try {
+        const ctx = {
+            stage,
+            phase,
+            groups: buildGroups(core, run, stage, phase, legal.wpIds),
+            notes: stage === 'dev' || stage === 'fix' ? (notes ?? {}) : {},
+            specText: (await core.deps.store.readRunFile(run.runId, 'spec.md')) ?? run.goal,
+        };
+        const text = await executeStage(core, run, ctx, controller);
+        // Redeem a pending `/gov pause` HERE, while the stage is still "active", so a request
+        // that arrives in the tail of the stage waits for this hook instead of racing it.
+        return await applyPendingPause(core, text);
+    }
+    catch (error) {
+        // An unexpected throw must not eat the user's pause (the run itself is intact).
+        await applyPendingPause(core, '').catch(() => undefined);
+        throw error;
+    }
+    finally {
+        core.endStage();
+    }
+}
+async function executeStage(core, run, ctx, controller) {
+    if (ctx.groups.length === 0) {
+        return refusal(core, `stage '${ctx.stage}' has no work package to run.`);
+    }
+    markRunning(core, run, ctx);
+    let aborted = false;
+    try {
+        let missing = missingOf(core, ctx);
+        let groups = ctx.groups;
+        for (let attempt = 0; attempt <= GOV_LIMITS.maxAutoRedispatch && !aborted; attempt += 1) {
+            const outcome = await dispatchGroups(core, run, ctx, groups, {
+                controller,
+                missingOnly: attempt > 0,
+            });
+            aborted = outcome.aborted || controller.signal.aborted;
+            missing = missingOf(core, ctx);
+            if (aborted || missing.length === 0)
+                break;
+            groups = restrictGroups(ctx.groups, missing);
+        }
+        if (aborted)
+            return await pauseAfterAbort(core, run, ctx);
+        return await finishStage(core, run, ctx, missing);
+    }
+    catch (error) {
+        return await failStage(core, run, ctx, error);
+    }
+}
+async function pauseAfterAbort(core, run, ctx) {
+    recoverInterruptedStage(run);
+    if (run.stage)
+        run.stage.status = 'aborted';
+    run.status = 'paused';
+    core.log('stage_ended', 'engine', {
+        stage: ctx.stage,
+        phase: ctx.phase.index,
+        status: 'aborted',
+    });
+    core.log('run_paused', 'engine', { reason: 'aborted' });
+    core.clearActivity();
+    for (const g of ctx.groups)
+        core.setAgentState(g.identity, 'idle');
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'stage_ended', snapshot, card: null }));
+    core.emit((snapshot) => ({ type: 'run_paused', snapshot, reason: 'aborted' }));
+    const flush = await core.flush();
+    const text = composeDigest(core, {
+        headline: PAUSE_RESUME_HINT,
+        results: core.stageResults,
+        ledger: core.stageLedgerLines,
+        warnings: core.stageWarnings,
+        standings: true,
+    });
+    return flush === null ? text : `${text}\n${flush}`;
+}
+async function failStage(core, run, ctx, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    recoverInterruptedStage(run);
+    if (run.stage)
+        run.stage.status = 'aborted';
+    core.log('stage_ended', 'engine', {
+        stage: ctx.stage,
+        phase: ctx.phase.index,
+        status: 'failed',
+        error: message.slice(0, 200),
+    });
+    core.clearActivity();
+    for (const g of ctx.groups)
+        core.setAgentState(g.identity, 'failed');
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'stage_ended', snapshot, card: null }));
+    await core.flush();
+    return composeDigest(core, {
+        headline: `NOT ACCEPTED: the team could not run the ${ctx.stage} stage (${message.slice(0, 200)}). ` +
+            'Nothing was recorded for this stage and no GT was deducted.',
+        results: core.stageResults,
+        warnings: core.stageWarnings,
+    });
+}
+function blockMissing(core, run, ctx, missing) {
+    if (ctx.stage === 'fix') {
+        core.stageWarnings.push(`No fix submission from: ${missing.join(', ')} after one retry (no GT deducted). ` +
+            'Integrate again to see where things stand.');
+        return;
+    }
+    if (ctx.stage === 'settle' || ctx.stage === 'integrate') {
+        core.stageWarnings.push(`The inspector finished without calling ledger_settle after one retry, so nothing was ` +
+            `recorded for the ${ctx.stage} stage (no GT changed). Dispatch ${ctx.stage} again.`);
+        return;
+    }
+    for (const id of missing) {
+        markBlocked(run, id, ctx.stage);
+        core.stageWarnings.push(`WP ${id} is BLOCKED at ${ctx.stage}: no submission after one retry (no GT deducted). ` +
+            `Dispatch ${ctx.stage} for it again.`);
+    }
+}
+function settleAgentStates(core, ctx, missing) {
+    const lacking = new Set(missing);
+    for (const g of ctx.groups) {
+        const own = g.wpIds.filter((id) => lacking.has(id)).length;
+        const gaps = g.role === 'INSP' ? missing.length : own;
+        core.setAgentState(g.identity, gaps > 0 ? 'failed' : 'submitted');
+    }
+}
+async function finishStage(core, run, ctx, missing) {
+    if (missing.length > 0)
+        blockMissing(core, run, ctx, missing);
+    if (ctx.stage === 'fix')
+        ctx.phase.fixCycles += 1;
+    if (run.stage)
+        run.stage.status = 'done';
+    settleAgentStates(core, ctx, missing);
+    core.log('stage_ended', 'engine', {
+        stage: ctx.stage,
+        phase: ctx.phase.index,
+        status: 'done',
+        missing,
+    });
+    core.clearActivity();
+    core.checkpoint();
+    // The integrate verdict emits its OWN `stage_ended` carrying the phase card; every other
+    // stage (and an integrate that produced no verdict) is announced here, exactly once.
+    const verdictEmitted = ctx.stage === 'integrate' && core.inspectorOutcome?.kind === 'integrate';
+    if (!verdictEmitted)
+        core.emit((snapshot) => ({ type: 'stage_ended', snapshot, card: null }));
+    core.exportScoreboard();
+    const flush = await core.flush();
+    const text = composeDigest(core, stageDigest(core, run, ctx, missing));
+    return flush === null ? text : `${text}\n${flush}`;
+}
+function stageDigest(core, run, ctx, missing) {
+    const open = run.escalations.filter((e) => e.status === 'open');
+    const outcome = core.inspectorOutcome;
+    const total = ctx.groups.flatMap((g) => g.wpIds).length;
+    const done = total - (ctx.stage === 'settle' || ctx.stage === 'integrate' ? 0 : missing.length);
+    let headline;
+    if (open.length > 0) {
+        headline = `ESCALATION: ${open.map((e) => `${e.id}: ${e.topic}`).join(' | ')}`;
+    }
+    else if ((ctx.stage === 'settle' || ctx.stage === 'integrate') && outcome === null) {
+        headline = `NOT ACCEPTED: the ${ctx.stage} stage produced no result. Nothing was recorded.`;
+    }
+    else if (outcome !== null) {
+        headline = `OK: ${outcome.headline}`;
+    }
+    else if (ctx.stage === 'fix') {
+        headline = `OK: fix stage finished (cycle ${ctx.phase.fixCycles}).`;
+    }
+    else {
+        headline = `OK: ${ctx.stage} stage finished: ${done}/${total} submission(s) recorded.`;
+    }
+    return {
+        headline,
+        results: core.stageResults,
+        ledger: core.stageLedgerLines,
+        warnings: core.stageWarnings,
+        standings: true,
+    };
+}

package/dist/governance/engine/start-input.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `gov_run start` argument normalization (governance-mode 7.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * REPAIR FIRST, REJECT SECOND, and never create anything on a rejection: a malformed
+ * `start` must leave no run directory, no ledger and no lock behind, because the model's
+ * natural response to `NOT ACCEPTED` is to call `start` again with a corrected payload.
+ * Every problem is listed at once - a model that learns about one defect per call burns a
+ * round trip per defect, and each round trip is an LLM turn.
+ *
+ * The schema in `lead-tools.ts` declares SHAPE only (plan-tools.ts P0-4: `ajv` is an
+ * optional dependency, so a numeric bound in the schema would behave differently depending
+ * on whether it installed). Every bound is enforced HERE, deterministically.
+ */
+import type { StartInput } from '../types.js';
+import { type Normalized } from '../tools/normalize-util.js';
+/** Validate a raw `gov_run start` payload. Pure; never throws. */
+export declare function normalizeStartInput(raw: unknown): Normalized<StartInput>;