@aragon-agent/cli 0.6.43 → 0.6.45

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

@@ -0,0 +1,56 @@
+/**
+ * Cooperative pause: `/gov pause` (governance-mode-v1-1 6, V-1..V-4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHAT IT IS. The user asks the run to stop at the next clean boundary: the stage that is
+ * running finishes (every submission lands, every GT is booked, nothing is killed or rolled
+ * back), and THEN the run becomes `paused`. If no stage is running the run pauses at once.
+ * `Esc` is the other, harder control and is unchanged: it aborts the stage and throws away
+ * whatever it had not yet committed.
+ *
+ * WHAT IT IS NOT. It adds no `RunStatus`, no event type and no ledger entry: the pause is the
+ * existing `paused` status and the existing `run_paused` event with `reason:
+ * 'user_requested'`, so resume, the lock, the panel and the replay all work unchanged (V-1).
+ * Pausing never touches the ledger (V-4), and the request itself is a memory-only flag: a
+ * process that dies while one is pending restarts into the crash-recovered `paused` state
+ * (V-2), never into a run that "paused itself" for a reason nobody remembers.
+ *
+ * THE TWO REDEEM POINTS. `applyPendingPause` (a stage just ended) and `requestPause` (no
+ * stage is active) are the only places a request becomes a pause, so there is no third path
+ * for it to leak through (V-3). A run that is `escalated` is NEVER overwritten: an open
+ * escalation is more important than a pause and would vanish from the user's view.
+ */
+import type { EngineCore } from './engine-core.js';
+export type PauseOutcome = 'paused_now' | 'pending' | 'already_paused' | 'escalated' | 'no_run';
+/**
+ * AGENT-FACING (the Orchestrator reads these as tool results). Each one stands on its own:
+ * the orchestrator block has no `PAUSED:` clause, so the sentence itself must say "stop".
+ * It also forbids `gov_run resume` because only the person who paused may resume; the
+ * digest's usual `NEXT: resume` line is replaced for the same reason.
+ */
+export declare const PAUSED_BY_USER_HEADLINE: string;
+export declare const PAUSE_APPLIED_LINE: string;
+export declare const PAUSE_DROPPED_LINE = "Pause request dropped: the run is already waiting on you (escalated).";
+/**
+ * Replace the digest's trailing `NEXT:` block (it is always the last section), optionally
+ * putting `above` on the line just before it.
+ */
+export declare function replaceNextBlock(text: string, line: string, above?: string): string;
+/** The refusal `gov_dispatch` returns while a pause is pending or applied. */
+export declare function pausedByUserRefusal(core: EngineCore): string;
+/**
+ * Turn the run into `paused`. Idempotent and conservative: anything but `executing` is
+ * left exactly as it is (`paused` already is what was asked; `escalated` outranks it).
+ * Returns whether this call did the pausing.
+ */
+export declare function settlePause(core: EngineCore, reason: 'user_requested'): Promise<boolean>;
+/**
+ * A stage just returned `text`. If the user asked for a pause meanwhile, redeem it now.
+ * Always clears the request: whatever the outcome, it has been dealt with.
+ */
+export declare function applyPendingPause(core: EngineCore, text: string): Promise<string>;
+/** `/gov pause`. The caller reports the outcome; this only changes engine state. */
+export declare function requestPause(core: EngineCore): Promise<PauseOutcome>;
+/** `/gov pause cancel`. True when a pending request was actually withdrawn. */
+export declare function cancelPause(core: EngineCore): boolean;

package/dist/governance/engine/pause.js

@@ -0,0 +1,107 @@
+/**
+ * Cooperative pause: `/gov pause` (governance-mode-v1-1 6, V-1..V-4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHAT IT IS. The user asks the run to stop at the next clean boundary: the stage that is
+ * running finishes (every submission lands, every GT is booked, nothing is killed or rolled
+ * back), and THEN the run becomes `paused`. If no stage is running the run pauses at once.
+ * `Esc` is the other, harder control and is unchanged: it aborts the stage and throws away
+ * whatever it had not yet committed.
+ *
+ * WHAT IT IS NOT. It adds no `RunStatus`, no event type and no ledger entry: the pause is the
+ * existing `paused` status and the existing `run_paused` event with `reason:
+ * 'user_requested'`, so resume, the lock, the panel and the replay all work unchanged (V-1).
+ * Pausing never touches the ledger (V-4), and the request itself is a memory-only flag: a
+ * process that dies while one is pending restarts into the crash-recovered `paused` state
+ * (V-2), never into a run that "paused itself" for a reason nobody remembers.
+ *
+ * THE TWO REDEEM POINTS. `applyPendingPause` (a stage just ended) and `requestPause` (no
+ * stage is active) are the only places a request becomes a pause, so there is no third path
+ * for it to leak through (V-3). A run that is `escalated` is NEVER overwritten: an open
+ * escalation is more important than a pause and would vanish from the user's view.
+ */
+import { composeDigest, USER_PAUSED_NEXT } from './digest.js';
+/**
+ * AGENT-FACING (the Orchestrator reads these as tool results). Each one stands on its own:
+ * the orchestrator block has no `PAUSED:` clause, so the sentence itself must say "stop".
+ * It also forbids `gov_run resume` because only the person who paused may resume; the
+ * digest's usual `NEXT: resume` line is replaced for the same reason.
+ */
+export const PAUSED_BY_USER_HEADLINE = 'PAUSED: the user paused this run. Do not dispatch more stages and do not call ' +
+    'gov_run resume yourself; tell the user it is paused and wait for them to run /gov resume.';
+export const PAUSE_APPLIED_LINE = "PAUSED: the run is now paused at the user's request after this stage. Do not dispatch " +
+    'more stages; tell the user and wait.';
+export const PAUSE_DROPPED_LINE = 'Pause request dropped: the run is already waiting on you (escalated).';
+/**
+ * Replace the digest's trailing `NEXT:` block (it is always the last section), optionally
+ * putting `above` on the line just before it.
+ */
+export function replaceNextBlock(text, line, above) {
+    const at = text.lastIndexOf('\nNEXT:');
+    const head = at < 0 ? text : text.slice(0, at);
+    const lead = above === undefined ? '' : `\n${above}`;
+    return `${head}${lead}\nNEXT:\n  ${line}`;
+}
+/** The refusal `gov_dispatch` returns while a pause is pending or applied. */
+export function pausedByUserRefusal(core) {
+    const text = composeDigest(core, { headline: PAUSED_BY_USER_HEADLINE });
+    return replaceNextBlock(text, USER_PAUSED_NEXT);
+}
+/**
+ * Turn the run into `paused`. Idempotent and conservative: anything but `executing` is
+ * left exactly as it is (`paused` already is what was asked; `escalated` outranks it).
+ * Returns whether this call did the pausing.
+ */
+export async function settlePause(core, reason) {
+    const run = core.run;
+    core.pauseRequested = false;
+    if (run === null || run.status !== 'executing')
+        return false;
+    run.status = 'paused';
+    core.userPaused = true;
+    core.log('run_paused', 'engine', { reason });
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'run_paused', snapshot, reason }));
+    await core.flush();
+    return true;
+}
+/**
+ * A stage just returned `text`. If the user asked for a pause meanwhile, redeem it now.
+ * Always clears the request: whatever the outcome, it has been dealt with.
+ */
+export async function applyPendingPause(core, text) {
+    if (!core.pauseRequested)
+        return text;
+    const run = core.run;
+    if (run !== null && run.status === 'executing' && (await settlePause(core, 'user_requested'))) {
+        return replaceNextBlock(text, USER_PAUSED_NEXT, PAUSE_APPLIED_LINE);
+    }
+    core.pauseRequested = false;
+    core.emit((snapshot) => ({ type: 'agent_state', snapshot }));
+    return run?.status === 'escalated' ? `${text}\n${PAUSE_DROPPED_LINE}` : text;
+}
+/** `/gov pause`. The caller reports the outcome; this only changes engine state. */
+export async function requestPause(core) {
+    const run = core.run;
+    if (run === null || run.status === 'closed' || run.status === 'abandoned')
+        return 'no_run';
+    if (run.status === 'paused')
+        return 'already_paused';
+    if (run.status === 'escalated')
+        return 'escalated';
+    if (core.isStageActive()) {
+        core.pauseRequested = true;
+        core.emit((snapshot) => ({ type: 'agent_state', snapshot }));
+        return 'pending';
+    }
+    return (await settlePause(core, 'user_requested')) ? 'paused_now' : 'already_paused';
+}
+/** `/gov pause cancel`. True when a pending request was actually withdrawn. */
+export function cancelPause(core) {
+    if (!core.pauseRequested)
+        return false;
+    core.pauseRequested = false;
+    core.emit((snapshot) => ({ type: 'agent_state', snapshot }));
+    return true;
+}

package/dist/governance/engine/phase-members.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Who belongs to a phase, and the small ledger queries the inspector stages share.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ */
+import { hasBooked } from '../rules/ledger-state.js';
+import type { PhaseState, RunState, WorkPackage } from '../types.js';
+import type { EngineCore } from './engine-core.js';
+/** The live (not dropped) work packages of a phase, in plan order. */
+export declare function livePhaseWps(run: RunState, phase: PhaseState): WorkPackage[];
+/** Active scored agents that worked on the phase: its DEVs, REVs and TESTs, deduplicated. */
+export declare function phaseMembers(core: EngineCore, phase: PhaseState): string[];
+/** True when the agent already took an integration root-cause hit (D13) in this phase. */
+export declare function wasPrimaryInPhase(core: EngineCore, agentId: string, phaseIndex: number): boolean;
+export declare function alreadyBooked(core: EngineCore, agentId: string, code: Parameters<typeof hasBooked>[2], incidentId: string): boolean;

package/dist/governance/engine/phase-members.js

@@ -0,0 +1,34 @@
+/**
+ * Who belongs to a phase, and the small ledger queries the inspector stages share.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ */
+import { hasBooked } from '../rules/ledger-state.js';
+/** The live (not dropped) work packages of a phase, in plan order. */
+export function livePhaseWps(run, phase) {
+    return phase.wpIds
+        .map((id) => run.workPackages[id])
+        .filter((wp) => wp !== undefined && wp.status !== 'dropped');
+}
+/** Active scored agents that worked on the phase: its DEVs, REVs and TESTs, deduplicated. */
+export function phaseMembers(core, phase) {
+    const run = core.requireRun();
+    const ids = new Set();
+    for (const wp of livePhaseWps(run, phase)) {
+        for (const id of [wp.assignee, wp.reviewer, wp.tester]) {
+            if (id !== null && core.ledger.agents[id]?.status === 'active')
+                ids.add(id);
+        }
+    }
+    return [...ids];
+}
+/** True when the agent already took an integration root-cause hit (D13) in this phase. */
+export function wasPrimaryInPhase(core, agentId, phaseIndex) {
+    const agent = core.ledger.agents[agentId];
+    if (agent === undefined)
+        return false;
+    return agent.history.some((e) => e.code === 'D13' && e.phase === phaseIndex);
+}
+export function alreadyBooked(core, agentId, code, incidentId) {
+    return hasBooked(core.ledger, agentId, code, incidentId);
+}

package/dist/governance/engine/phase-planner.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Phase planner: validate a work-package graph and layer it into phases
+ * (governance-mode section 8.1 "phase layering").
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock, no randomness.
+ *
+ * Phases are topological layers of `dependsOn`: a WP's phase is one more than the
+ * deepest phase among its dependencies, so everything in one phase is independent and
+ * runs in parallel. Parallel WPs must not own the same files - two developers editing one
+ * file in the same stage is a merge conflict the governance model has no stage to
+ * resolve - so same-layer ownership overlap is REJECTED with a message that names both
+ * WPs and tells the orchestrator how to fix the plan (move one to a later layer).
+ *
+ * EVERY failure begins `NOT ACCEPTED:` so the tool layer can return it as plain text
+ * (D-15: a rejected plan is a normal reply, not an error result). Messages name where a
+ * limit comes from (a config key vs the structural ceiling) so the user knows which knob
+ * to turn.
+ */
+import type { ContractInput, WorkPackageInput } from '../types.js';
+export interface PlannerConfig {
+    /** `governance.maxWorkPackages` (already clamped by config, re-clamped here). */
+    maxWorkPackages: number;
+    /** `governance.maxPhases`. */
+    maxPhases: number;
+    /** `min(team.maxSubagents, hardMax)`; only used to emit the chunking NOTE. */
+    teamCeiling?: number;
+}
+export interface PlanInput {
+    workPackages: readonly WorkPackageInput[];
+    contracts?: readonly ContractInput[];
+    config: PlannerConfig;
+}
+export interface PlannedPhase {
+    /** 0-based. */
+    index: number;
+    wpIds: string[];
+}
+export type PlanResult = {
+    ok: true;
+    phases: PlannedPhase[];
+    /** wp id -> 0-based phase index. */
+    phaseOf: Record<string, number>;
+    notes: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+/** First dependency cycle as `a -> b -> a`, or null. Deterministic (input order). */
+export declare function findCycle(wps: readonly WorkPackageInput[]): string[] | null;
+/** True when a path (or glob) plausibly names a test file or test directory. */
+export declare function looksLikeTestPath(path: string): boolean;
+/** Validate and layer a plan. Never throws; failures are `{ ok:false, errors }`. */
+export declare function planPhases(input: PlanInput): PlanResult;

package/dist/governance/engine/phase-planner.js

@@ -0,0 +1,282 @@
+/**
+ * Phase planner: validate a work-package graph and layer it into phases
+ * (governance-mode section 8.1 "phase layering").
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure: no I/O, no clock, no randomness.
+ *
+ * Phases are topological layers of `dependsOn`: a WP's phase is one more than the
+ * deepest phase among its dependencies, so everything in one phase is independent and
+ * runs in parallel. Parallel WPs must not own the same files - two developers editing one
+ * file in the same stage is a merge conflict the governance model has no stage to
+ * resolve - so same-layer ownership overlap is REJECTED with a message that names both
+ * WPs and tells the orchestrator how to fix the plan (move one to a later layer).
+ *
+ * EVERY failure begins `NOT ACCEPTED:` so the tool layer can return it as plain text
+ * (D-15: a rejected plan is a normal reply, not an error result). Messages name where a
+ * limit comes from (a config key vs the structural ceiling) so the user knows which knob
+ * to turn.
+ */
+import { GOV_LIMITS } from '../limits.js';
+const WP_ID_PATTERN = /^[a-z0-9-]+$/;
+const NOT_ACCEPTED = 'NOT ACCEPTED:';
+function effectiveLimit(configured, hard, key) {
+    if (configured > hard) {
+        return { value: hard, source: `structural limit (config ${key} was ${configured})` };
+    }
+    return { value: configured, source: `config ${key}` };
+}
+function reject(errors) {
+    const prefixed = errors.map((e) => (e.startsWith(NOT_ACCEPTED) ? e : `${NOT_ACCEPTED} ${e}`));
+    return { ok: false, errors: prefixed };
+}
+// ---------------------------------------------------------------------------
+// Step 1: structural validation (ids, references)
+// ---------------------------------------------------------------------------
+function validateCount(input) {
+    const count = input.workPackages.length;
+    if (count === 0)
+        return ['at least one work package is required.'];
+    const limit = effectiveLimit(input.config.maxWorkPackages, GOV_LIMITS.hardMaxWorkPackages, 'governance.maxWorkPackages');
+    if (count > limit.value) {
+        return [`${count} work packages exceed the limit of ${limit.value} (${limit.source}).`];
+    }
+    return [];
+}
+function validateIds(wps) {
+    const errors = [];
+    const seen = new Set();
+    for (const wp of wps) {
+        const idOk = typeof wp.id === 'string' &&
+            wp.id.length >= 1 &&
+            wp.id.length <= GOV_LIMITS.wpIdChars &&
+            WP_ID_PATTERN.test(wp.id);
+        if (!idOk) {
+            errors.push(`work package id ${JSON.stringify(wp.id)} is invalid; use 1-${GOV_LIMITS.wpIdChars} ` +
+                'characters from [a-z0-9-].');
+            continue;
+        }
+        if (seen.has(wp.id))
+            errors.push(`duplicate work package id '${wp.id}'.`);
+        seen.add(wp.id);
+    }
+    return errors;
+}
+function validateDependencies(wps) {
+    const ids = new Set(wps.map((wp) => wp.id));
+    const errors = [];
+    for (const wp of wps) {
+        for (const dep of wp.dependsOn ?? []) {
+            if (dep === wp.id)
+                errors.push(`work package '${wp.id}' depends on itself.`);
+            else if (!ids.has(dep)) {
+                errors.push(`work package '${wp.id}' depends on unknown work package '${dep}'.`);
+            }
+        }
+    }
+    return errors;
+}
+function validateContracts(wps, contracts) {
+    const ids = new Set(wps.map((wp) => wp.id));
+    const errors = [];
+    for (const contract of contracts) {
+        if (!ids.has(contract.producer)) {
+            errors.push(`contract '${contract.id}' names unknown producer work package '${contract.producer}'.`);
+        }
+        for (const consumer of contract.consumers) {
+            if (!ids.has(consumer)) {
+                errors.push(`contract '${contract.id}' names unknown consumer work package '${consumer}'.`);
+            }
+        }
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Step 2: cycles and layering
+// ---------------------------------------------------------------------------
+/** First dependency cycle as `a -> b -> a`, or null. Deterministic (input order). */
+export function findCycle(wps) {
+    const deps = new Map(wps.map((wp) => [wp.id, wp.dependsOn ?? []]));
+    const state = new Map();
+    const stack = [];
+    const visit = (id) => {
+        if (state.get(id) === 'done')
+            return null;
+        if (state.get(id) === 'visiting')
+            return [...stack.slice(stack.indexOf(id)), id];
+        state.set(id, 'visiting');
+        stack.push(id);
+        for (const dep of deps.get(id) ?? []) {
+            const cycle = visit(dep);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(id, 'done');
+        return null;
+    };
+    for (const wp of wps) {
+        const cycle = visit(wp.id);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+function layerOf(wps) {
+    const deps = new Map(wps.map((wp) => [wp.id, wp.dependsOn ?? []]));
+    const memo = {};
+    const depth = (id) => {
+        const cached = memo[id];
+        if (cached !== undefined)
+            return cached;
+        const list = deps.get(id) ?? [];
+        const value = list.length === 0 ? 0 : 1 + Math.max(...list.map(depth));
+        memo[id] = value;
+        return value;
+    };
+    for (const wp of wps)
+        depth(wp.id);
+    return memo;
+}
+function normalizePath(raw) {
+    return raw
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/^\.\//, '')
+        .replace(/\/{2,}/g, '/');
+}
+function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*' && glob[i + 1] === '*') {
+            out += '.*';
+            i++;
+        }
+        else if (ch === '*')
+            out += '[^/]*';
+        else if (ch === '?')
+            out += '[^/]';
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${out}$`);
+}
+/** Strip trailing `/`, `/**`, `/*` so `src/auth/**` and `src/auth` compare as one scope. */
+function toScope(raw) {
+    const display = normalizePath(raw);
+    const folded = display.toLowerCase();
+    const base = folded.replace(/(\/\*\*?|\/)+$/, '');
+    const hasGlob = /[*?]/.test(base);
+    return { display, base, hasGlob, matcher: hasGlob ? globToRegExp(base) : null };
+}
+function isSegmentPrefix(prefix, path) {
+    return prefix === '' || path === prefix || path.startsWith(`${prefix}/`);
+}
+function literalDirOf(base) {
+    const segments = base.split('/');
+    const firstGlob = segments.findIndex((s) => /[*?]/.test(s));
+    return segments.slice(0, firstGlob < 0 ? segments.length : firstGlob).join('/');
+}
+function scopesOverlap(a, b) {
+    if (!a.hasGlob && !b.hasGlob) {
+        return isSegmentPrefix(a.base, b.base) || isSegmentPrefix(b.base, a.base);
+    }
+    if (a.hasGlob && b.hasGlob) {
+        const dirA = literalDirOf(a.base);
+        const dirB = literalDirOf(b.base);
+        return isSegmentPrefix(dirA, dirB) || isSegmentPrefix(dirB, dirA);
+    }
+    const [glob, literal] = a.hasGlob ? [a, b] : [b, a];
+    return ((glob.matcher?.test(literal.base) ?? false) ||
+        isSegmentPrefix(literal.base, literalDirOf(glob.base)));
+}
+function findOverlaps(wps, phaseOf) {
+    const errors = [];
+    for (let i = 0; i < wps.length; i++) {
+        for (let j = i + 1; j < wps.length; j++) {
+            const a = wps[i];
+            const b = wps[j];
+            if (phaseOf[a.id] !== phaseOf[b.id])
+                continue;
+            const clash = firstClash(a.files, b.files);
+            if (!clash)
+                continue;
+            errors.push(`work packages '${a.id}' and '${b.id}' both own '${clash.a}' ` +
+                `(overlaps '${clash.b}') in phase ${phaseOf[a.id] + 1}. ` +
+                `Move one of them to a later layer (add a dependsOn) or split the file ownership.`);
+        }
+    }
+    return errors;
+}
+function firstClash(filesA, filesB) {
+    const scopesB = filesB.map(toScope);
+    for (const rawA of filesA) {
+        const scopeA = toScope(rawA);
+        const hit = scopesB.find((scopeB) => scopesOverlap(scopeA, scopeB));
+        if (hit)
+            return { a: scopeA.display, b: hit.display };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Step 4: notes
+// ---------------------------------------------------------------------------
+const TEST_PATH = new RegExp([
+    '(^|/)(__tests__|tests?|specs?)(/|$)',
+    '\\.(test|spec)\\.[a-z0-9]+$',
+    '(^|/)test_[^/]+\\.py$',
+    '_test\\.[a-z0-9]+$',
+].join('|'), 'i');
+/** True when a path (or glob) plausibly names a test file or test directory. */
+export function looksLikeTestPath(path) {
+    return TEST_PATH.test(normalizePath(path));
+}
+function buildNotes(wps, phases, teamCeiling) {
+    const notes = [];
+    for (const wp of wps) {
+        if (!wp.files.some(looksLikeTestPath)) {
+            notes.push(`NOTE: work package '${wp.id}' lists no test path in files; the tester may only write ` +
+                'files a work package owns (add its test paths, or ignore this for docs/config-only ' +
+                'work).');
+        }
+    }
+    const widest = Math.max(...phases.map((p) => p.wpIds.length));
+    if (teamCeiling !== undefined && widest > teamCeiling) {
+        notes.push(`NOTE: stages will be dispatched in chunks of ${teamCeiling} (team.maxSubagents); ` +
+            `the widest phase has ${widest} work packages.`);
+    }
+    return notes;
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/** Validate and layer a plan. Never throws; failures are `{ ok:false, errors }`. */
+export function planPhases(input) {
+    const wps = input.workPackages;
+    const early = [...validateCount(input), ...validateIds(wps)];
+    if (early.length > 0)
+        return reject(early);
+    const refs = [...validateDependencies(wps), ...validateContracts(wps, input.contracts ?? [])];
+    if (refs.length > 0)
+        return reject(refs);
+    const cycle = findCycle(wps);
+    if (cycle)
+        return reject([`dependency cycle: ${cycle.join(' -> ')}`]);
+    const phaseOf = layerOf(wps);
+    const phaseCount = Math.max(...Object.values(phaseOf)) + 1;
+    const phaseLimit = effectiveLimit(input.config.maxPhases, GOV_LIMITS.hardMaxPhases, 'governance.maxPhases');
+    if (phaseCount > phaseLimit.value) {
+        return reject([
+            `the dependency chain needs ${phaseCount} phases, over the limit of ${phaseLimit.value} ` +
+                `(${phaseLimit.source}). Flatten the dependencies or merge work packages.`,
+        ]);
+    }
+    const overlaps = findOverlaps(wps, phaseOf);
+    if (overlaps.length > 0)
+        return reject(overlaps);
+    const phases = Array.from({ length: phaseCount }, (_, index) => ({
+        index,
+        wpIds: wps.filter((wp) => phaseOf[wp.id] === index).map((wp) => wp.id),
+    }));
+    return { ok: true, phases, phaseOf, notes: buildNotes(wps, phases, input.config.teamCeiling) };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Resume / replay helpers (governance-mode 8.4, 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHAT IS REBUILT AND WHAT IS NOT. `events.jsonl` is the truth for the LEDGER: every ledger
+ * mutation is one logged op, so the ledger is replayed exactly (I-G2). `run.json` is a
+ * checkpoint the engine rewrites after every mutation that changes WP / phase state, so it
+ * is normally current; if it is missing or unreadable the run cannot be reconstructed from
+ * the log (the log carries ledger ops and audit rows, not the full WP graph) and the caller
+ * must say so loudly instead of guessing.
+ */
+import type { ReplayFn } from '../store/run-store.js';
+import type { RunState } from '../types.js';
+/**
+ * Put every WP that was mid-stage back to the status it was waiting in, and mark a still
+ * `running` stage `interrupted`. WPs that already received their submission were routed on
+ * by the adjudication half and are untouched - which is exactly what makes a resume
+ * re-dispatch only the WPs that lack a submission. Returns the ids that were reset.
+ */
+export declare function recoverInterruptedStage(run: RunState): string[];
+/**
+ * `RunStore.load` replay callback: rebuild the ledger from the op log. The run checkpoint is
+ * kept as is (only its `seq` is brought up to the log tail, because the engine stamps every
+ * checkpoint with the tail it had when it wrote it).
+ */
+export declare const replayCheckpoints: ReplayFn;

package/dist/governance/engine/rebuild.js

@@ -0,0 +1,57 @@
+/**
+ * Resume / replay helpers (governance-mode 8.4, 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHAT IS REBUILT AND WHAT IS NOT. `events.jsonl` is the truth for the LEDGER: every ledger
+ * mutation is one logged op, so the ledger is replayed exactly (I-G2). `run.json` is a
+ * checkpoint the engine rewrites after every mutation that changes WP / phase state, so it
+ * is normally current; if it is missing or unreadable the run cannot be reconstructed from
+ * the log (the log carries ledger ops and audit rows, not the full WP graph) and the caller
+ * must say so loudly instead of guessing.
+ */
+import { EngineCore } from './engine-core.js';
+/** Waiting status a WP returns to when its in-flight stage was interrupted. */
+function waitingStatusFor(wp) {
+    switch (wp.status) {
+        case 'dev_running':
+            return wp.reworkCount > 0 ? 'rework' : 'pending';
+        case 'review_running':
+            return 'awaiting_review';
+        case 'test_running':
+            return 'awaiting_test';
+        default:
+            return null;
+    }
+}
+/**
+ * Put every WP that was mid-stage back to the status it was waiting in, and mark a still
+ * `running` stage `interrupted`. WPs that already received their submission were routed on
+ * by the adjudication half and are untouched - which is exactly what makes a resume
+ * re-dispatch only the WPs that lack a submission. Returns the ids that were reset.
+ */
+export function recoverInterruptedStage(run) {
+    const reset = [];
+    for (const id of run.wpOrder) {
+        const wp = run.workPackages[id];
+        if (wp === undefined)
+            continue;
+        const waiting = waitingStatusFor(wp);
+        if (waiting === null)
+            continue;
+        wp.status = waiting;
+        reset.push(id);
+    }
+    if (run.stage !== null && run.stage.status === 'running')
+        run.stage.status = 'interrupted';
+    return reset;
+}
+/**
+ * `RunStore.load` replay callback: rebuild the ledger from the op log. The run checkpoint is
+ * kept as is (only its `seq` is brought up to the log tail, because the engine stamps every
+ * checkpoint with the tail it had when it wrote it).
+ */
+export const replayCheckpoints = ({ run, events, tailSeq }) => ({
+    ledger: EngineCore.replayLedger(events, tailSeq),
+    ...(run === null ? {} : { run: { ...run, seq: Math.max(run.seq, tailSeq) } }),
+});