@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/engine/inspector.js

@@ -0,0 +1,396 @@
+/**
+ * `ledger_apply` / `ledger_rule` / `ledger_settle` - the engine side (governance-mode 5.4,
+ * 5.6, 5.7, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE INSPECTOR HAS NO SECOND ACCOUNTING PATH (I-G7). Everything it books goes through the
+ * same `core.ledgerOp` as the engine's own events, with the same catalogue deltas and the
+ * same caps; the only difference is `by: "inspector:insp"` and the evidence it must attach.
+ * It cannot name its own amount, cannot target itself (I-G5) and cannot book a mechanical
+ * code - those are refused here even if the tool layer let them through.
+ */
+import { getLogger } from '../../logging/logger.js';
+import { GOV_LIMITS } from '../limits.js';
+import { ruleClaim } from '../rules/claims.js';
+import { eventDef, isEventCode, isInspectorBookable } from '../rules/events-table.js';
+import { teamHealthStatus } from '../rules/elimination.js';
+import { settlePhaseR1R2 } from '../rules/settlement.js';
+import { normalizeLedgerApply, normalizeLedgerRule, normalizeLedgerSettle, } from '../tools/inspector-tools.js';
+import { formatNotAccepted } from '../tools/normalize-util.js';
+import { applyEvents } from './aftermath.js';
+import { artifactIdFor, persistArtifact } from './artifact-persist.js';
+import { PHASE_WP_SEGMENT } from '../store/artifacts.js';
+import { announceEscalation, applyIntegrationFailure, applyIntegrationPass, staticVerificationProblem, } from './integration.js';
+import { livePhaseWps } from './phase-members.js';
+import { renderInspectorMarkdown } from './submission-render.js';
+import { latestReview, submissionsOf } from './submission-queries.js';
+import { nextEscalationId, openEscalation } from './state-machine.js';
+const NOT_ACCEPTED = 'NOT ACCEPTED:';
+const INSPECTOR_ACTOR = 'insp';
+const INSPECTOR_BY = `inspector:${INSPECTOR_ACTOR}`;
+function guarded(tool, fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        getLogger().warn('agent', 'governance.inspector_internal_error', { tool, message });
+        return (`${NOT_ACCEPTED} internal error while recording ${tool} (${message}). Nothing was ` +
+            `recorded.`);
+    }
+}
+/** The inspector tools only make sense inside a running settle / integrate stage. */
+function inspectorStage(core, tool) {
+    const run = core.run;
+    if (run === null)
+        return `${NOT_ACCEPTED} no governance run is active.`;
+    const stage = run.stage;
+    if (stage === null ||
+        stage.status !== 'running' ||
+        (stage.kind !== 'settle' && stage.kind !== 'integrate')) {
+        const now = stage ? `${stage.kind} (${stage.status})` : 'none';
+        return (`${NOT_ACCEPTED} ${tool} is only available in a running settle or integrate stage ` +
+            `(current: ${now}).`);
+    }
+    const phase = run.phases[stage.phase];
+    if (phase === undefined)
+        return `${NOT_ACCEPTED} the stage refers to an unknown phase.`;
+    return { run, kind: stage.kind, phase };
+}
+// ---------------------------------------------------------------------------
+// ledger_apply
+// ---------------------------------------------------------------------------
+function applyPreconditions(core, input) {
+    if (!isEventCode(input.code))
+        return `${NOT_ACCEPTED} unknown event code "${String(input.code)}".`;
+    if (!isInspectorBookable(input.code)) {
+        return (`${NOT_ACCEPTED} this event is handled by the engine (${input.code}: ` +
+            `${eventDef(input.code).title}).`);
+    }
+    if (input.agentId.toLowerCase() === INSPECTOR_ACTOR) {
+        return `${NOT_ACCEPTED} the inspector is not scored and cannot be the subject of an event.`;
+    }
+    const agent = core.ledger.agents[input.agentId];
+    if (agent === undefined) {
+        return (`${NOT_ACCEPTED} unknown agent "${input.agentId}". Roster: ` +
+            `${Object.keys(core.ledger.agents).join(', ')}.`);
+    }
+    if (agent.status !== 'active') {
+        return (`${NOT_ACCEPTED} ${agent.id} is already ` +
+            `eliminated${agent.replacedBy ? ` (replaced by ${agent.replacedBy})` : ''}; book against ` +
+            `the successor.`);
+    }
+    const def = eventDef(input.code);
+    if (def.role !== 'ALL' && def.role !== agent.role) {
+        return (`${NOT_ACCEPTED} ${input.code} applies to ${def.role} agents; ${agent.id} is ` +
+            `${agent.role}.`);
+    }
+    if (input.evidence.trim().length < GOV_LIMITS.evidenceMinChars) {
+        return (`${NOT_ACCEPTED} evidence must be concrete (at least ${GOV_LIMITS.evidenceMinChars} ` +
+            `characters: files, lines, quotes). No evidence, no event.`);
+    }
+    return null;
+}
+/** The same judgment about the same agent and work package is booked once per phase. */
+function alreadyJudged(core, input, phase) {
+    const agent = core.ledger.agents[input.agentId];
+    if (agent === undefined)
+        return false;
+    return agent.history.some((e) => e.code === input.code &&
+        e.phase === phase &&
+        e.wpId === input.wpId &&
+        e.by === INSPECTOR_BY &&
+        (input.incidentId === undefined || e.incidentId === input.incidentId));
+}
+export function handleInspectorApply(core, input) {
+    return guarded('ledger_apply', () => {
+        const normalized = normalizeLedgerApply(input);
+        if (!normalized.ok)
+            return formatNotAccepted('ledger_apply', normalized.errors);
+        const value = normalized.value;
+        const stage = inspectorStage(core, 'ledger_apply');
+        if (typeof stage === 'string')
+            return stage;
+        const problem = applyPreconditions(core, value);
+        if (problem !== null)
+            return problem;
+        const wp = value.wpId === undefined ? undefined : stage.run.workPackages[value.wpId];
+        if (value.wpId !== undefined && wp === undefined) {
+            return `${NOT_ACCEPTED} unknown work package "${value.wpId}".`;
+        }
+        const phase = wp ? wp.phase : stage.phase.index;
+        if (alreadyJudged(core, value, phase)) {
+            return (`${NOT_ACCEPTED} ${value.code} was already booked for ` +
+                `${value.agentId}${value.wpId ? ` on ${value.wpId}` : ''} in this phase.`);
+        }
+        const event = {
+            code: value.code,
+            agentId: value.agentId,
+            at: core.now(),
+            phase,
+            by: INSPECTOR_BY,
+            reason: value.reason,
+            evidence: value.evidence,
+            ...(value.wpId !== undefined ? { wpId: value.wpId } : {}),
+            ...(value.incidentId !== undefined ? { incidentId: value.incidentId } : {}),
+        };
+        const booked = applyEvents(core, [event], { actor: INSPECTOR_ACTOR, phase });
+        core.checkpoint();
+        const mine = booked.find((b) => b.agentId === value.agentId && b.entry.code === value.code);
+        if (mine === undefined) {
+            return (`${NOT_ACCEPTED} the ledger refused ${value.code} for ${value.agentId} (agent not ` +
+                `scorable right now).`);
+        }
+        const cap = mine.entry.capped
+            ? ` CAPPED: requested ${mine.entry.capped.requested}, applied ` +
+                `${mine.entry.capped.applied}; state this in your settle summary.`
+            : '';
+        const sign = mine.entry.delta > 0 ? '+' : '';
+        return (`OK: booked ${value.code} ` +
+            `${sign}${mine.entry.delta}${mine.entry.settlement === 'provisional' ? 'P' : ''} for ` +
+            `${value.agentId}.${cap}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// ledger_rule
+// ---------------------------------------------------------------------------
+export function handleInspectorRule(core, input) {
+    return guarded('ledger_rule', () => {
+        const normalized = normalizeLedgerRule(input);
+        if (!normalized.ok)
+            return formatNotAccepted('ledger_rule', normalized.errors);
+        const value = normalized.value;
+        const stage = inspectorStage(core, 'ledger_rule');
+        if (typeof stage === 'string')
+            return stage;
+        const claim = stage.run.claims.find((c) => c.id === value.claimId);
+        if (claim === undefined) {
+            const open = stage.run.claims.filter((c) => c.status === 'open').map((c) => c.id);
+            return (`${NOT_ACCEPTED} unknown claim "${value.claimId}". Open claims: ` +
+                `${open.join(', ') || '(none)'}.`);
+        }
+        if (claim.status !== 'open')
+            return `${NOT_ACCEPTED} claim ${claim.id} is already ${claim.status}.`;
+        const ruled = ruleClaim({
+            state: core.ledger,
+            claim,
+            decision: value.decision,
+            ruling: value.ruling,
+            at: core.now(),
+            inspectorId: INSPECTOR_ACTOR,
+        });
+        Object.assign(claim, ruled.claim);
+        core.log('ruling', INSPECTOR_ACTOR, { claimId: claim.id, decision: value.decision });
+        applyEvents(core, ruled.events, { actor: INSPECTOR_ACTOR, phase: claim.phase });
+        core.checkpoint();
+        const remaining = stage.run.claims.filter((c) => c.status === 'open').length;
+        const booked = ruled.events.map((e) => `${e.code} ${e.agentId}`).join(', ');
+        return [
+            `OK: claim ${claim.id} ` +
+                `${value.decision}${booked ? ` (booked: ${booked})` : ' (no event booked)'}.`,
+            ...ruled.notes,
+            `${remaining} open claim(s) remain.`,
+        ].join('\n');
+    });
+}
+// ---------------------------------------------------------------------------
+// ledger_settle
+// ---------------------------------------------------------------------------
+function rejectionRecords(core, wps) {
+    const out = [];
+    for (const wp of wps) {
+        const reviews = submissionsOf(core, wp.id, 'review');
+        reviews.forEach((review, index) => {
+            if (review.verdict !== 'NEEDS_REWORK')
+                return;
+            const ids = new Set(review.findings.map((f) => f.id));
+            const withdrawn = reviews
+                .slice(index + 1)
+                .some((later) => later.appealResponses.some((a) => a.decision === 'withdraw' && ids.has(a.findingId)));
+            out.push({
+                id: review.id,
+                wpId: wp.id,
+                reviewer: review.identity,
+                hasBlockerOrMajor: review.findings.some((f) => f.severity === 'blocker' || f.severity === 'major'),
+                withdrawn,
+            });
+        });
+    }
+    return out;
+}
+function payPhaseBonuses(core, run, phase) {
+    const wps = livePhaseWps(run, phase);
+    const reviewedWps = wps.flatMap((wp) => {
+        const review = latestReview(core, wp.id);
+        const passed = review !== undefined && review.verdict !== 'NEEDS_REWORK';
+        return passed ? [{ wpId: wp.id, reviewer: review.identity }] : [];
+    });
+    const result = settlePhaseR1R2({
+        state: core.ledger,
+        phase: phase.index,
+        at: core.now(),
+        reviewedWps,
+        testedOkWpIds: wps.filter((w) => w.status === 'tested_ok').map((w) => w.id),
+        claims: run.claims,
+        rejections: rejectionRecords(core, wps),
+    });
+    applyEvents(core, result.events, { phase: phase.index });
+    return result.notes;
+}
+function openInspectorEscalations(core, run, phase, input) {
+    const opened = [];
+    for (const item of input.escalations) {
+        const escalation = {
+            id: nextEscalationId(run),
+            level: 'L3',
+            kind: item.kind,
+            phase: phase.index,
+            topic: item.topic,
+            positions: item.positions,
+            status: 'open',
+            ...(item.wpId !== undefined ? { wpId: item.wpId } : {}),
+        };
+        openEscalation(run, escalation);
+        announceEscalation(core, escalation);
+        core.stageWarnings.push(`ESCALATION ${escalation.id}: ${item.topic}`);
+        opened.push(escalation);
+    }
+    return opened;
+}
+function buildReport(core, input, phase) {
+    const target = {
+        phase: phase.index,
+        wpId: PHASE_WP_SEGMENT,
+        stage: input.kind,
+        identity: INSPECTOR_ACTOR,
+    };
+    const report = {
+        kind: 'inspector',
+        id: artifactIdFor(core, target),
+        phase: phase.index,
+        stage: input.kind,
+        at: core.now(),
+        summary: input.summary,
+        contractChecks: input.contractChecks,
+        escalations: input.escalations,
+        ...(input.integration ? { integration: input.integration } : {}),
+        ...(input.rca ? { rca: input.rca } : {}),
+    };
+    persistArtifact(core, target, report.id, report, renderInspectorMarkdown(report));
+    return report;
+}
+/** `reports/phase-N.md`: settlement and integration reports of the phase, in order. */
+function writePhaseReport(core, phase) {
+    const reports = [...core.submissionCache.values()]
+        .filter((r) => r.kind === 'inspector' && r.phase === phase.index)
+        .sort((a, b) => a.at - b.at);
+    core.writeFile(`reports/phase-${phase.index + 1}.md`, reports.map(renderInspectorMarkdown).join('\n---\n\n'));
+}
+function validateSettleInput(core, stage, input) {
+    if (input.kind !== stage.kind) {
+        return (`${NOT_ACCEPTED} this is the ${stage.kind} stage; ledger_settle kind must be ` +
+            `"${stage.kind}".`);
+    }
+    if (input.phase - 1 !== stage.phase.index) {
+        return (`${NOT_ACCEPTED} phase must be ${stage.phase.index + 1} (the running phase), not ` +
+            `${input.phase}.`);
+    }
+    if (core.stageSubmitted.has(INSPECTOR_ACTOR)) {
+        return `${NOT_ACCEPTED} already settled: ledger_settle is called exactly once per stage.`;
+    }
+    return null;
+}
+function settleStage(core, stage, input) {
+    const { run, phase } = stage;
+    const open = run.claims.filter((c) => c.phase === phase.index && c.status === 'open');
+    if (open.length > 0) {
+        return (`${NOT_ACCEPTED} ${open.length} claim(s) are not ruled: ` +
+            `${open.map((c) => c.id).join(', ')}. ` +
+            'Rule each with ledger_rule (upheld or rejected), then call ledger_settle.');
+    }
+    const notes = payPhaseBonuses(core, run, phase);
+    const mismatches = input.contractChecks.filter((c) => c.status === 'mismatch');
+    const opened = openInspectorEscalations(core, run, phase, input);
+    phase.settled = true;
+    const report = buildReport(core, input, phase);
+    writePhaseReport(core, phase);
+    core.stageSubmitted.add(INSPECTOR_ACTOR);
+    const headline = `phase ${phase.index + 1} settled`;
+    core.inspectorOutcome = { kind: 'settle', phase: phase.index, passed: true, headline };
+    core.log('submission', INSPECTOR_ACTOR, {
+        kind: 'inspector',
+        stage: 'settle',
+        reportId: report.id,
+    });
+    core.stageResults.push(`settle: ${input.summary.slice(0, 160)}`);
+    core.checkpoint();
+    const health = teamHealthStatus(core.ledger);
+    return [
+        `OK: settle recorded for phase ${phase.index + 1}.`,
+        ...notes,
+        mismatches.length > 0
+            ? `${mismatches.length} contract mismatch(es) recorded ` +
+                `(${mismatches.map((m) => m.contractId).join(', ')}); book D14/D15 with ledger_apply ` +
+                `if you have not.`
+            : 'All checked contracts are consistent.',
+        opened.length > 0 ? `${opened.length} escalation(s) opened for the user.` : '',
+        health.advisory ?? '',
+    ]
+        .filter((l) => l !== '')
+        .join('\n');
+}
+function integrateStage(core, stage, input) {
+    const { run, phase } = stage;
+    const integration = input.integration;
+    if (integration === undefined) {
+        return (`${NOT_ACCEPTED} integrate needs integration: {result: pass | fail | not_run, ` + `commands}.`);
+    }
+    if (integration.result === 'fail' && input.rca === undefined) {
+        return (`${NOT_ACCEPTED} integration failed: include rca {failingChecks, boundary, ` +
+            `attributions, systemic}.`);
+    }
+    if (integration.result === 'not_run') {
+        const problem = staticVerificationProblem(run, phase, input);
+        if (problem !== null)
+            return problem;
+    }
+    const report = buildReport(core, input, phase);
+    core.stageSubmitted.add(INSPECTOR_ACTOR);
+    core.log('submission', INSPECTOR_ACTOR, {
+        kind: 'inspector',
+        stage: 'integrate',
+        reportId: report.id,
+    });
+    const verdict = integration.result === 'fail'
+        ? applyIntegrationFailure(core, phase, input.rca)
+        : applyIntegrationPass(core, phase, { accepted: true });
+    openInspectorEscalations(core, run, phase, input);
+    writePhaseReport(core, phase);
+    core.inspectorOutcome = {
+        kind: 'integrate',
+        phase: phase.index,
+        passed: verdict.passed,
+        headline: verdict.headline,
+    };
+    core.stageResults.push(`integrate: ${verdict.headline}`);
+    core.checkpoint();
+    const prefix = verdict.passed ? 'OK: integration passed.' : 'OK: integration failure recorded.';
+    return [prefix, ...verdict.lines].join('\n');
+}
+export function handleInspectorSettle(core, input) {
+    return guarded('ledger_settle', () => {
+        const normalized = normalizeLedgerSettle(input);
+        if (!normalized.ok)
+            return formatNotAccepted('ledger_settle', normalized.errors);
+        const stage = inspectorStage(core, 'ledger_settle');
+        if (typeof stage === 'string')
+            return stage;
+        const problem = validateSettleInput(core, stage, normalized.value);
+        if (problem !== null)
+            return problem;
+        return stage.kind === 'settle'
+            ? settleStage(core, stage, normalized.value)
+            : integrateStage(core, stage, normalized.value);
+    });
+}

package/dist/governance/engine/integration.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The integrate stage's verdict (governance-mode 5.7): pass releases escrow and pays the
+ * collective; fail attributes the failure, claws escrow back from the primary and opens a
+ * fix cycle - or, when the fix budget is spent, an escalation to the user.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * `integrationAttempts` is incremented HERE (every integrate) and `fixCycles` by the stage
+ * runner (every fix); the legality table and `isIntegrationExhausted` read both, so each
+ * counter must have exactly one writer.
+ */
+import type { Escalation, PhaseState, RcaInput, RunState } from '../types.js';
+import type { LedgerSettleInput } from '../tools/inspector-tools.js';
+import type { EngineCore } from './engine-core.js';
+export interface IntegrationVerdict {
+    /** Did the phase become integrated? */
+    passed: boolean;
+    headline: string;
+    /** Text lines for the inspector's `OK:` answer. */
+    lines: string[];
+}
+/** Contracts whose producer or a consumer belongs to the phase (and are still live). */
+export declare function contractsOfPhase(run: RunState, phase: PhaseState): string[];
+/**
+ * `not_run` is legal only when there is nothing to run: no registered commands, and every
+ * live contract of the phase statically checked `ok`. Returns a refusal text or null.
+ */
+export declare function staticVerificationProblem(run: RunState, phase: PhaseState, input: LedgerSettleInput): string | null;
+/** Pass: escrow -> confirmed, D12, C1 (first attempt only), tail check, WPs integrated. */
+export declare function applyIntegrationPass(core: EngineCore, phase: PhaseState, options: {
+    accepted: boolean;
+}): IntegrationVerdict;
+export declare function announceEscalation(core: EngineCore, escalation: Escalation): void;
+/** Fail: attribute, claw back, count the attempt, escalate when the fix budget is gone. */
+export declare function applyIntegrationFailure(core: EngineCore, phase: PhaseState, rca: RcaInput): IntegrationVerdict;

package/dist/governance/engine/integration.js

@@ -0,0 +1,220 @@
+/**
+ * The integrate stage's verdict (governance-mode 5.7): pass releases escrow and pays the
+ * collective; fail attributes the failure, claws escrow back from the primary and opens a
+ * fix cycle - or, when the fix budget is spent, an escalation to the user.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * `integrationAttempts` is incremented HERE (every integrate) and `fixCycles` by the stage
+ * runner (every fix); the legality table and `isIntegrationExhausted` read both, so each
+ * counter must have exactly one writer.
+ */
+import { expandRca } from '../rules/rca.js';
+import { applyEvents, afterLedgerChange, emitLedger, runTailCheck } from './aftermath.js';
+import { escalationCard, phaseCard } from './cards.js';
+import { alreadyBooked, livePhaseWps, phaseMembers, wasPrimaryInPhase } from './phase-members.js';
+import { isIntegrationExhausted, nextEscalationId, openEscalation, recordRework, } from './state-machine.js';
+const NOT_ACCEPTED = 'NOT ACCEPTED:';
+/** Contracts whose producer or a consumer belongs to the phase (and are still live). */
+export function contractsOfPhase(run, phase) {
+    const inPhase = new Set(livePhaseWps(run, phase).map((w) => w.id));
+    return run.contracts
+        .filter((c) => c.voided !== true && (inPhase.has(c.producer) || c.consumers.some((id) => inPhase.has(id))))
+        .map((c) => c.id);
+}
+/**
+ * `not_run` is legal only when there is nothing to run: no registered commands, and every
+ * live contract of the phase statically checked `ok`. Returns a refusal text or null.
+ */
+export function staticVerificationProblem(run, phase, input) {
+    if (run.integrationCommands.length > 0) {
+        return (`${NOT_ACCEPTED} integration commands are registered ` +
+            `(${run.integrationCommands.join(' | ')}); ` +
+            'run them and report result pass or fail, not not_run.');
+    }
+    const required = contractsOfPhase(run, phase);
+    const checks = new Map(input.contractChecks.map((c) => [c.contractId, c.status]));
+    const missing = required.filter((id) => !checks.has(id));
+    if (missing.length > 0) {
+        return (`${NOT_ACCEPTED} static verification must check every contract; missing: ` +
+            `${missing.join(', ')}.`);
+    }
+    const bad = required.filter((id) => checks.get(id) !== 'ok');
+    if (bad.length > 0) {
+        return (`${NOT_ACCEPTED} contract(s) ${bad.join(', ')} did not check ok. Report integration result ` +
+            'fail with an rca, or verify them and report ok.');
+    }
+    return null;
+}
+function cleanDeveloperEvents(core, phase) {
+    const run = core.requireRun();
+    const at = core.now();
+    const events = [];
+    for (const wp of livePhaseWps(run, phase)) {
+        const dev = wp.assignee;
+        if (dev === null || core.ledger.agents[dev]?.status !== 'active')
+            continue;
+        if (wasPrimaryInPhase(core, dev, phase.index))
+            continue;
+        const incidentId = `d12:${wp.id}`;
+        if (alreadyBooked(core, dev, 'D12', incidentId))
+            continue;
+        events.push({
+            code: 'D12',
+            agentId: dev,
+            at,
+            phase: phase.index,
+            by: 'engine',
+            reason: `integration passed with ${wp.id} clean`,
+            wpId: wp.id,
+            incidentId,
+        });
+    }
+    return events;
+}
+/** Pass: escrow -> confirmed, D12, C1 (first attempt only), tail check, WPs integrated. */
+export function applyIntegrationPass(core, phase, options) {
+    const run = core.requireRun();
+    const firstAttempt = phase.integrationAttempts === 0;
+    phase.integrationAttempts += 1;
+    phase.lastIntegrationFailed = false;
+    const members = phaseMembers(core, phase);
+    const at = core.now();
+    const escrow = core.ledgerOp({ op: 'confirm_escrow', phase: phase.index, at });
+    core.noteBooked(escrow.booked);
+    applyEvents(core, cleanDeveloperEvents(core, phase), { phase: phase.index });
+    if (firstAttempt) {
+        const op = {
+            op: 'collective',
+            spec: {
+                code: 'C1',
+                at,
+                phase: phase.index,
+                by: 'engine',
+                reason: 'integration passed first time',
+                participants: members,
+                incidentId: `c1:p${phase.index}`,
+            },
+        };
+        core.noteBooked(core.ledgerOp(op).booked);
+    }
+    phase.integrated = true;
+    phase.integrationAccepted = options.accepted;
+    for (const wp of livePhaseWps(run, phase)) {
+        if (wp.status === 'tested_ok')
+            wp.status = 'integrated';
+    }
+    core.log('escrow', 'engine', { phase: phase.index, released: escrow.booked.length });
+    core.emit((snapshot) => ({ type: 'escrow', snapshot, phase: phase.index, released: true }));
+    runTailCheck(core, phase.index);
+    afterLedgerChange(core, { phase: phase.index });
+    emitLedger(core);
+    core.exportScoreboard();
+    const headline = `integration passed (attempt ${phase.integrationAttempts})`;
+    const card = phaseCard(core, phase.index, headline, 'ok');
+    core.emit((snapshot) => ({ type: 'stage_ended', snapshot, card }));
+    return {
+        passed: true,
+        headline,
+        lines: [
+            `Phase ${phase.index + 1} integrated; escrow ` +
+                `released${firstAttempt ? '; collective C1 awarded' : ''}.`,
+        ],
+    };
+}
+/** WPs implicated by an RCA: the ones owned by attributed agents, else every live WP. */
+function implicatedWps(run, phase, rca) {
+    const ids = new Set(rca.attributions.map((a) => a.agentId));
+    const live = livePhaseWps(run, phase);
+    const owned = live.filter((wp) => wp.assignee !== null && ids.has(wp.assignee));
+    return owned.length > 0 ? owned : live;
+}
+function sendBackToDev(core, phase, rca) {
+    const run = core.requireRun();
+    const lines = [];
+    for (const wp of implicatedWps(run, phase, rca)) {
+        const outcome = recordRework(run, wp.id);
+        lines.push(`${wp.id}: ${outcome.outcome} (${outcome.reworkCount}/${outcome.limit})`);
+        if (outcome.escalation !== null) {
+            openEscalation(run, outcome.escalation);
+            core.stageWarnings.push(`ESCALATION ${outcome.escalation.id}: ${wp.id} reached the rework limit.`);
+            announceEscalation(core, outcome.escalation);
+        }
+    }
+    phase.settled = false;
+    return lines;
+}
+export function announceEscalation(core, escalation) {
+    core.log('escalation', 'engine', { escalation });
+    core.emit((snapshot) => ({
+        type: 'escalation',
+        snapshot,
+        escalation,
+        card: escalationCard(core, escalation),
+    }));
+}
+/** Fix budget spent and still failing: hand the decision to the user (L3). */
+function escalateIfExhausted(core, phase) {
+    const run = core.requireRun();
+    if (!isIntegrationExhausted(run, phase))
+        return [];
+    const escalation = {
+        id: nextEscalationId(run),
+        level: 'L3',
+        kind: 'integration_exhausted',
+        phase: phase.index,
+        topic: `Phase ${phase.index + 1} integration still fails after ${phase.fixCycles} fix ` +
+            `cycle(s).`,
+        positions: [],
+        status: 'open',
+    };
+    openEscalation(run, escalation);
+    core.stageWarnings.push(`ESCALATION ${escalation.id}: integration fix cycles are exhausted; ask the user.`);
+    announceEscalation(core, escalation);
+    return [`Fix cycles exhausted: escalated to the user (${escalation.id}).`];
+}
+/** Fail: attribute, claw back, count the attempt, escalate when the fix budget is gone. */
+export function applyIntegrationFailure(core, phase, rca) {
+    phase.integrationAttempts += 1;
+    const lines = [];
+    const incidentId = `integ-p${phase.index + 1}-a${phase.integrationAttempts}`;
+    const expansion = expandRca(rca, {
+        state: core.ledger,
+        phase: phase.index,
+        at: core.now(),
+        incidentId,
+        fixCycles: phase.fixCycles,
+        by: 'inspector:insp',
+        participants: phaseMembers(core, phase),
+    });
+    lines.push(...expansion.breakdown);
+    if (expansion.individualDefect) {
+        phase.lastIntegrationFailed = false;
+        lines.push('Not an integration failure: affected work goes back to its developer.');
+        lines.push(...sendBackToDev(core, phase, rca));
+        return finishFailure(core, phase, lines, 'individual defect, sent back to development');
+    }
+    phase.lastIntegrationFailed = true;
+    const op = { op: 'incident', events: expansion.events, clawbacks: expansion.clawbacks };
+    const { booked } = core.ledgerOp(op, 'insp');
+    core.noteBooked(booked);
+    for (const b of booked) {
+        if (b.entry.capped !== undefined) {
+            const { requested, applied } = b.entry.capped;
+            const text = `CAPPED ${String(b.entry.code)} on ${b.agentId}: requested ${requested}, ` +
+                `applied ${applied} (single-incident limit).`;
+            core.stageWarnings.push(text);
+            lines.push(text);
+        }
+    }
+    afterLedgerChange(core, { phase: phase.index });
+    emitLedger(core);
+    lines.push(...escalateIfExhausted(core, phase));
+    return finishFailure(core, phase, lines, `integration failed (attempt ${phase.integrationAttempts})`);
+}
+function finishFailure(core, phase, lines, headline) {
+    core.exportScoreboard();
+    const card = phaseCard(core, phase.index, headline, 'error');
+    core.emit((snapshot) => ({ type: 'stage_ended', snapshot, card }));
+    return { passed: false, headline, lines };
+}

package/dist/governance/engine/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Run lifecycle: start, resume, close, abandon, resolve, status (governance-mode 7.2, 8.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Every function here answers with plain text that begins `OK:` / `NOT ACCEPTED:` /
+ * `ESCALATION:` and ends with `NEXT:` (D-16, 14.5). A refusal is a normal tool RESULT, never
+ * an error: an error result invites an identical retry, a result that says what to do
+ * instead does not.
+ */
+import type { Escalation } from '../types.js';
+import type { EngineCore } from './engine-core.js';
+export declare const BUDGET_TOPIC_PREFIX = "Team token budget";
+/** `gov_run start`. Creates nothing unless every check passes (7.2). */
+export declare function startRun(core: EngineCore, raw: unknown, signal?: AbortSignal): Promise<string>;
+/** Retention prune, once per engine instance, never blocking and never throwing. */
+export declare function pruneOnce(core: EngineCore): void;
+/** `gov_run resume`. Only WPs that lack a submission for their stage will be re-run. */
+export declare function resumeRun(core: EngineCore, runId?: string): Promise<string>;
+/** `gov_run status`: the board as text. Rebuildable by a compacted orchestrator (R-11). */
+export declare function statusText(core: EngineCore): string;
+/** `gov_run close`: only when every phase is integrated (or the run was abandoned). */
+export declare function closeRun(core: EngineCore, summary?: string): Promise<string>;
+/** `gov_run abandon`: keeps every artifact, ends the run, frees the directory for a new one. */
+export declare function abandonRun(core: EngineCore, reason: string): Promise<string>;
+/** Open a budget escalation (called by the stage runner when the cap is hit). */
+export declare function openBudgetEscalation(core: EngineCore): Escalation;
+/** `gov_run resolve`: the user's L3 ruling, optionally with a disposition (7.2). */
+export declare function resolveEscalation(core: EngineCore, raw: unknown): Promise<string>;