@pellux/goodvibes-sdk 0.37.2 → 0.38.0

package/dist/platform/orchestration/dirty-guard.js

@@ -0,0 +1,147 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Dirty-residue guard (Wave 6, wo-F item 4) — prevents an orchestration
+ * engine run's scoped commit from sweeping in uncommitted changes that were
+ * ALREADY sitting in the working tree before this engine launched (typically
+ * residue left behind by a previously killed run sharing the same
+ * `projectRoot`, since phase-runner.ts's WorkItem.touchedPaths accumulates
+ * across phases/retries and never resets — see phase-runner.ts runPhase).
+ *
+ * Mechanism: snapshot every dirty path + a binary-safe content hash at
+ * engine-launch time (`snapshotDirtyTree`). At scoped-commit time, a
+ * candidate path is excluded only when it was ALREADY dirty at launch AND
+ * its content hash is unchanged since launch — i.e. this run never touched
+ * it. A path that was clean at launch, or whose hash changed, is included:
+ * this run is the one that dirtied (or re-dirtied) it.
+ *
+ * `snapshotDirtyTree` is deliberately SYNCHRONOUS (Bun.spawnSync, mirroring
+ * GitService's own sync helpers — initRepo/isGitRepo/getRepoRoot,
+ * platform/git/service.ts) rather than shelling out through simple-git's
+ * async API: the engine factory (engine.ts) is a synchronous function that
+ * must have a settled snapshot before its first phase can possibly reach a
+ * commit, and a promise backed by real child-process I/O cannot be relied
+ * on to resolve within a caller's microtask-only wait (subprocess exit is
+ * delivered via the event loop's macrotask phases, not microtasks) — a real
+ * regression seen against tests that only drain microtasks. One blocking
+ * `git status` call at launch (paid once, exactly like GitService.initRepo)
+ * avoids that whole class of timing hazard entirely.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+/** Dirty paths under this prefix are GoodVibes' own internal state, never a candidate for a scoped commit — excluded from the snapshot so they never pollute the 'dirty-tree-at-launch' event. */
+const INTERNAL_STATE_PREFIX = '.goodvibes/';
+/** Content hash of a file's current working-tree bytes. Binary-safe (raw bytes, not text). Returns null when the path does not exist on disk (a working-tree deletion). */
+export function hashWorkingTreeFile(cwd, relativePath) {
+    const absolutePath = join(cwd, relativePath);
+    if (!existsSync(absolutePath))
+        return null;
+    try {
+        return createHash('sha256').update(readFileSync(absolutePath)).digest('hex');
+    }
+    catch (error) {
+        logger.warn('orchestration dirty-guard: failed to hash working-tree file', {
+            path: relativePath,
+            error: summarizeError(error),
+        });
+        return null;
+    }
+}
+/**
+ * Parse `git status --porcelain -z --untracked-files=all` output into a set of
+ * paths. The `-z` (NUL-terminated) format is used deliberately because it emits
+ * paths VERBATIM: git's default porcelain C-quotes any path containing
+ * non-ASCII or special bytes (core.quotePath defaults to true), rendering
+ * `café.txt` as `"caf\303\251.txt"`. Keying the launch snapshot on that quoted
+ * string while excludeUntouchedLaunchResidue / hashWorkingTreeFile receive the
+ * RAW path would silently bypass exclusion (residue leaks into scoped commits)
+ * and make the content hash read the wrong (nonexistent, quoted) filename. With
+ * `-z` there is no quoting, so snapshot keys match the raw paths used
+ * everywhere else.
+ *
+ * Record shape: each NUL-terminated record is `XY<space><path>`. A rename or
+ * copy (X or Y is 'R'/'C') is split across TWO NUL-terminated fields — the
+ * destination first, then the origin. We keep the destination (the actual
+ * scoped-commit candidate, already in this record) and consume the following
+ * origin field so it is never mis-parsed as its own dirty path.
+ */
+function parsePorcelainPaths(output) {
+    const paths = new Set();
+    const records = output.split('\0');
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        // Skips the trailing empty field left by the final NUL, plus any record too
+        // short to hold a 2-char status pair + separator + a 1-char path.
+        if (record.length < 4)
+            continue;
+        const x = record[0];
+        const y = record[1];
+        // A rename/copy record is followed by a second NUL-separated field (the
+        // origin path). Consume it so the next iteration does not treat it as a
+        // standalone status record — done before any early-continue below.
+        if (x === 'R' || y === 'R' || x === 'C' || y === 'C')
+            i++;
+        const path = record.slice(3);
+        if (path.startsWith(INTERNAL_STATE_PREFIX))
+            continue;
+        paths.add(path);
+    }
+    return paths;
+}
+/**
+ * Snapshot every dirty path (staged + unstaged + untracked) in `cwd`'s
+ * working tree right now, each with a content hash. Call once at engine
+ * launch, before any phase of this run has had a chance to touch anything.
+ * Never throws: a git failure (e.g. `cwd` is not a repo) degrades to an
+ * empty snapshot, which makes the exclusion guard a no-op (today's
+ * behavior) rather than blocking commits.
+ */
+export function snapshotDirtyTree(cwd) {
+    try {
+        const result = Bun.spawnSync(['git', '-C', cwd, 'status', '--porcelain', '-z', '--untracked-files=all']);
+        if (result.exitCode !== 0)
+            return new Map();
+        const output = new TextDecoder().decode(result.stdout);
+        const paths = parsePorcelainPaths(output);
+        const snapshot = new Map();
+        for (const path of paths)
+            snapshot.set(path, hashWorkingTreeFile(cwd, path));
+        return snapshot;
+    }
+    catch (error) {
+        logger.warn('orchestration dirty-guard: failed to snapshot dirty tree at launch', { error: summarizeError(error) });
+        return new Map();
+    }
+}
+/**
+ * Partition `candidatePaths` into paths safe to include in a scoped commit
+ * vs. paths that must be excluded because they are untouched launch-dirty
+ * residue. A path is excluded only when BOTH:
+ *  - it appears in `launchSnapshot` (it was already dirty before this run), AND
+ *  - its current content hash equals the hash recorded at launch (this run
+ *    never actually changed it).
+ * Everything else is included — a path absent from the snapshot was clean
+ * at launch (this run is what dirtied it), and a path whose hash changed
+ * was genuinely touched by this run even though it started out dirty.
+ */
+export function excludeUntouchedLaunchResidue(cwd, candidatePaths, launchSnapshot) {
+    const included = [];
+    const excluded = [];
+    for (const path of candidatePaths) {
+        if (!launchSnapshot.has(path)) {
+            included.push(path);
+            continue;
+        }
+        const hashAtLaunch = launchSnapshot.get(path) ?? null;
+        const hashNow = hashWorkingTreeFile(cwd, path);
+        if (hashAtLaunch === hashNow) {
+            excluded.push(path);
+        }
+        else {
+            included.push(path);
+        }
+    }
+    return { included, excluded };
+}

package/dist/platform/orchestration/engine.d.ts

@@ -0,0 +1,57 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+import type { PhaseRunnerAgentManagerLike, WrfcWorktreeOps } from './phase-runner.js';
+import { type BudgetCeiling, type OrchestrationEventListener, type Phase, type PhaseResult, type PhaseSpec, type WorkItemSpec, type WorkItemUsage, type Workstream } from './types.js';
+import type { ConfigManager } from '../config/manager.js';
+import type { RuntimeEventBus } from '../runtime/events/index.js';
+export interface OrchestrationEngineDeps {
+    readonly agentManager: PhaseRunnerAgentManagerLike;
+    readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+    readonly runtimeBus: RuntimeEventBus;
+    readonly projectRoot: string;
+    readonly sessionId?: string | undefined;
+    readonly createWorktree?: (() => WrfcWorktreeOps) | undefined;
+    readonly priceUsage?: ((model: string | undefined, usage: WorkItemUsage) => number | null) | undefined;
+    readonly skipClaimVerification?: boolean | undefined;
+    /** Bounds re-review cycles through a dynamically-inserted fix phase. Default 5 (mirrors WrfcController's default maxFixAttempts). */
+    readonly maxPhaseVisits?: number | undefined;
+    readonly now?: (() => number) | undefined;
+    /** Set false to skip wiring the debounced disk writer (tests that don't want filesystem side effects). Default true. */
+    readonly persist?: boolean | undefined;
+}
+export interface CreateWorkstreamInput {
+    readonly id?: string | undefined;
+    readonly title: string;
+    readonly phases: readonly PhaseSpec[];
+    readonly items: readonly WorkItemSpec[];
+    readonly budget?: BudgetCeiling | undefined;
+}
+export interface OrchestrationEngine {
+    createWorkstream(input: CreateWorkstreamInput): Workstream;
+    getWorkstream(id: string): Workstream | null;
+    listWorkstreams(): Workstream[];
+    insertPhase(workstreamId: string, afterOrdinal: number, spec: PhaseSpec): Phase | null;
+    /** Begin (or resume ticking) a workstream's pipeline. Idempotent — safe to call on an already-running workstream. */
+    start(workstreamId: string): void;
+    /** Abort a work item's in-flight agent (if any) and mark it terminally failed. Never affects sibling items. */
+    kill(itemId: string): boolean;
+    /**
+     * Replace (or clear, via `undefined`) a workstream's budget ceiling and
+     * immediately re-tick it, so any item already sitting in 'blocked-budget'
+     * gets reconsidered right away — the only recovery path for that state
+     * (see WorkItemState's 'blocked-budget' doc, types.ts). Returns false if
+     * the workstream doesn't exist.
+     */
+    updateBudget(workstreamId: string, ceiling: BudgetCeiling | undefined): boolean;
+    getPhaseResults(workstreamId: string): readonly PhaseResult[];
+    serializeWorkstream(workstreamId: string): string | null;
+    /** Import a serialized snapshot (a full WorkstreamSnapshot JSON string, see persistence.ts). Refuses to overwrite a non-terminal in-memory workstream unless force=true. */
+    importWorkstream(snapshotJson: string, force?: boolean): boolean;
+    /** Import + start from the on-disk snapshot for one workstream id. */
+    resumeWorkstream(workstreamId: string): boolean;
+    /** Import + start every snapshot under .goodvibes/orchestration/. Returns the count resumed. */
+    resumeAllFromDisk(): number;
+    on(listener: OrchestrationEventListener): () => void;
+    dispose(): void;
+}
+export declare function createOrchestrationEngine(deps: OrchestrationEngineDeps): OrchestrationEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/platform/orchestration/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/engine.ts"],"names":[],"mappings":"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"}

package/dist/platform/orchestration/engine.js

@@ -0,0 +1,418 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * OrchestrationEngine (Wave 4, wo701) — owns Workstream state and drives the
+ * pipeline. WRAPS a canned/authored workstream; does not rewrite or touch
+ * WrfcController (stage 1 of the 3-stage migration — see controller-compat.ts
+ * and the work-order report).
+ *
+ * The tick loop is reactive, not timer-driven: `start()` runs one tick;
+ * every phase-run completion re-runs tick() for its workstream. Because JS
+ * is single-threaded, computeClaims()'s synchronous read of in-flight counts
+ * is never racing a concurrent claim — items are marked 'in-phase'
+ * synchronously before any `await` inside the claim loop, so a re-entrant
+ * tick() (triggered by an earlier completion resolving on a later turn of
+ * the microtask queue) always sees up-to-date state.
+ */
+import { checkBudget } from './budget.js';
+import { createCancellationRegistry } from './cancellation.js';
+import { runPhase } from './phase-runner.js';
+import { snapshotDirtyTree } from './dirty-guard.js';
+import { deserializeWorkstream as deserializeWorkstreamModel, deserializeWorkstreamSnapshot, attachDebouncedWriter, listSnapshotWorkstreamIds, loadWorkstreamSnapshot, serializeWorkstreamSnapshot, } from './persistence.js';
+import { computeClaims, firstPhase, nextPhaseAfter, reviewPhaseBefore, sortedPhases } from './scheduler.js';
+import { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage, } from './types.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+function generateId(prefix) {
+    return `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
+}
+export function createOrchestrationEngine(deps) {
+    const now = deps.now ?? (() => Date.now());
+    const sessionId = deps.sessionId ?? crypto.randomUUID().slice(0, 8);
+    const maxPhaseVisits = deps.maxPhaseVisits ?? 5;
+    const workstreams = new Map();
+    const completedResults = new Map();
+    const cancellation = createCancellationRegistry();
+    const listeners = new Set();
+    let disposed = false;
+    function emit(event) {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                logger.warn('orchestration engine: listener threw', { error: summarizeError(error) });
+            }
+        }
+    }
+    function on(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+    // Dirty-residue guard (Wave 6, wo-F item 4): snapshot the working tree's
+    // dirty paths + content hashes ONCE, right at engine launch (synchronous —
+    // see dirty-guard.ts's doc comment for why this must not be a promise
+    // backed by real subprocess I/O), before any phase of this run has had a
+    // chance to touch anything. A previously killed run sharing this same
+    // projectRoot can leave uncommitted residue behind; this snapshot is what
+    // lets a later scoped commit tell "residue from before this run" apart
+    // from "this run's own changes" (see dirty-guard.ts and phase-runner.ts's
+    // commitPhaseWork).
+    const launchDirtySnapshot = snapshotDirtyTree(deps.projectRoot);
+    if (launchDirtySnapshot.size > 0) {
+        emit({ type: 'dirty-tree-at-launch', paths: [...launchDirtySnapshot.keys()] });
+    }
+    function getWorkstream(id) {
+        return workstreams.get(id) ?? null;
+    }
+    function listWorkstreams() {
+        return Array.from(workstreams.values());
+    }
+    function getPhaseResults(workstreamId) {
+        return completedResults.get(workstreamId) ?? [];
+    }
+    const unsubscribeWriter = deps.persist === false
+        ? () => undefined
+        : attachDebouncedWriter(deps.projectRoot, getWorkstream, getPhaseResults, on);
+    function buildPhase(spec, ordinal, insertedAt) {
+        return {
+            id: spec.id ?? generateId('phase'),
+            ordinal,
+            role: spec.role,
+            capacity: spec.capacity,
+            gate: spec.gate,
+            kind: spec.kind,
+            ...(insertedAt !== undefined ? { insertedAt } : {}),
+        };
+    }
+    function buildItem(spec, startPhaseId) {
+        return {
+            id: spec.id ?? generateId('item'),
+            title: spec.title,
+            task: spec.task,
+            currentPhaseId: startPhaseId,
+            state: startPhaseId ? 'pending' : 'passed',
+            allAgentIds: [],
+            visits: new Map(),
+            touchedPaths: [],
+            usage: emptyWorkItemUsage(),
+            transportRetryCount: 0,
+            createdAt: now(),
+            ...(startPhaseId ? {} : { completedAt: now() }),
+        };
+    }
+    function createWorkstream(input) {
+        const phases = input.phases.map((spec, index) => buildPhase(spec, index + 1));
+        const workstream = {
+            id: input.id ?? generateId('ws'),
+            title: input.title,
+            schemaVersion: CURRENT_WORKSTREAM_SCHEMA_VERSION,
+            phases,
+            items: [],
+            budget: input.budget,
+            createdAt: now(),
+        };
+        const first = firstPhase(workstream)?.id ?? null;
+        workstream.items = input.items.map((spec) => buildItem(spec, first));
+        workstreams.set(workstream.id, workstream);
+        completedResults.set(workstream.id, []);
+        return workstream;
+    }
+    function insertPhase(workstreamId, afterOrdinal, spec) {
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return null;
+        const following = sortedPhases(workstream).filter((p) => p.ordinal > afterOrdinal);
+        const nextOrdinal = following[0]?.ordinal ?? afterOrdinal + 1;
+        const ordinal = (afterOrdinal + nextOrdinal) / 2;
+        const phase = buildPhase(spec, ordinal, now());
+        workstream.phases.push(phase);
+        emit({ type: 'phase-inserted', workstreamId, phase });
+        return phase;
+    }
+    function findOrInsertFixPhase(workstream, reviewPhase) {
+        const existing = workstream.phases.find((p) => p.kind === 'fix' && reviewPhaseBefore(workstream, p)?.id === reviewPhase.id);
+        if (existing)
+            return existing;
+        return insertPhase(workstream.id, reviewPhase.ordinal, {
+            role: 'fixer',
+            capacity: reviewPhase.capacity,
+            gate: reviewPhase.gate,
+            kind: 'fix',
+        });
+    }
+    function visitsFor(item, phaseId) {
+        return item.visits.get(phaseId) ?? 0;
+    }
+    function recordVisit(item, phaseId) {
+        item.visits.set(phaseId, visitsFor(item, phaseId) + 1);
+    }
+    function routeItem(workstream, item, toPhase, fromPhaseId) {
+        if (toPhase) {
+            item.currentPhaseId = toPhase.id;
+            item.state = 'awaiting-capacity';
+            emit({ type: 'item-advanced', workstreamId: workstream.id, itemId: item.id, fromPhaseId, toPhaseId: toPhase.id });
+        }
+        else {
+            item.currentPhaseId = null;
+            item.state = 'passed';
+            item.completedAt = now();
+            emit({ type: 'item-passed', workstreamId: workstream.id, itemId: item.id });
+        }
+    }
+    function failItem(workstream, item, reason) {
+        item.state = 'failed';
+        item.completedAt = now();
+        item.failureReason = reason;
+        emit({ type: 'item-failed', workstreamId: workstream.id, itemId: item.id, reason });
+    }
+    /** Indirection to defeat TS's cross-await narrowing of item.state — see the call site below. */
+    function currentState(item) {
+        return item.state;
+    }
+    async function runItemPhase(workstream, item, phase) {
+        recordVisit(item, phase.id);
+        item.state = 'in-phase';
+        item.currentPhaseId = phase.id;
+        item.blockedReason = undefined;
+        const priorReports = getPhaseResults(workstream.id).filter((r) => r.itemId === item.id);
+        const outcome = await runPhase(workstream, item, phase, priorReports, {
+            agentManager: deps.agentManager,
+            configManager: deps.configManager,
+            runtimeBus: deps.runtimeBus,
+            projectRoot: deps.projectRoot,
+            sessionId,
+            createWorktree: deps.createWorktree,
+            cancellation,
+            priceUsage: deps.priceUsage,
+            skipClaimVerification: deps.skipClaimVerification,
+            launchDirtySnapshot,
+        });
+        item.usage = mergeUsageFromResult(item.usage, outcome.result.usage);
+        const results = completedResults.get(workstream.id) ?? [];
+        results.push(outcome.result);
+        completedResults.set(workstream.id, results);
+        emit({ type: 'workstream-persisted', workstreamId: workstream.id });
+        // kill() already transitioned the item to 'failed' synchronously before
+        // this promise settled — don't clobber that terminal state. Read through
+        // currentState() (not a direct `item.state` narrowing site) since TS's
+        // control-flow analysis otherwise "remembers" the 'in-phase' assignment
+        // above as if it still held after the `await`, even though kill() can
+        // mutate the same object concurrently while this call was in flight.
+        if (currentState(item) === 'failed')
+            return;
+        if (outcome.agentStatus === 'cancelled') {
+            failItem(workstream, item, 'cancelled by operator');
+            return;
+        }
+        if (outcome.agentStatus === 'failed') {
+            failItem(workstream, item, outcome.result.report.summary);
+            return;
+        }
+        if (outcome.result.gate.passed) {
+            // A fix phase's PASSING gate routes BACK to the review phase it was
+            // inserted after (dynamic insertion places 'fix' at an ordinal AFTER
+            // its review, per design (b) — "inserts a fix phase after review and
+            // re-routes that item back"), not forward past it. Every other kind
+            // advances to the next phase by ordinal as usual.
+            const forwardTarget = phase.kind === 'fix'
+                ? (reviewPhaseBefore(workstream, phase) ?? nextPhaseAfter(workstream, phase.ordinal) ?? null)
+                : (nextPhaseAfter(workstream, phase.ordinal) ?? null);
+            routeItem(workstream, item, forwardTarget, phase.id);
+            return;
+        }
+        // A review's FAILING gate with unsatisfied constraints gets one more
+        // cycle through a (found-or-inserted) fix phase, bounded by visits. A
+        // fix phase's own FAILING gate (the fixer didn't actually fix anything —
+        // phantom guard or quality gates caught it) is a genuine terminal
+        // failure, not something to retry-loop.
+        const unsatisfied = outcome.result.gate.unsatisfiedConstraintIds ?? [];
+        if (phase.kind === 'review' && unsatisfied.length > 0 && visitsFor(item, phase.id) < maxPhaseVisits) {
+            const fixPhase = findOrInsertFixPhase(workstream, phase);
+            routeItem(workstream, item, fixPhase, phase.id);
+            return;
+        }
+        failItem(workstream, item, outcome.result.gate.results.filter((r) => !r.passed).map((r) => `${r.gate}: ${r.output}`).join('; ') || 'gate failed');
+    }
+    function mergeUsageFromResult(current, added) {
+        const sawReasoning = current.reasoningTokens !== undefined || added.reasoningTokens !== undefined;
+        const bothPriced = current.costState === 'priced' && added.costState === 'priced';
+        const neitherPriced = current.costUsd === null && added.costUsd === null;
+        return {
+            inputTokens: current.inputTokens + added.inputTokens,
+            outputTokens: current.outputTokens + added.outputTokens,
+            cacheReadTokens: current.cacheReadTokens + added.cacheReadTokens,
+            cacheWriteTokens: current.cacheWriteTokens + added.cacheWriteTokens,
+            reasoningTokens: sawReasoning ? (current.reasoningTokens ?? 0) + (added.reasoningTokens ?? 0) : undefined,
+            llmCallCount: current.llmCallCount + added.llmCallCount,
+            turnCount: current.turnCount + added.turnCount,
+            toolCallCount: current.toolCallCount + added.toolCallCount,
+            costUsd: current.costUsd !== null && added.costUsd !== null ? current.costUsd + added.costUsd : (current.costUsd ?? added.costUsd),
+            costState: bothPriced ? 'priced' : neitherPriced ? 'unpriced' : 'estimated',
+        };
+    }
+    function tick(workstreamId) {
+        if (disposed)
+            return;
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return;
+        const claims = computeClaims(workstream);
+        for (const { item, phase } of claims) {
+            const budgetCheck = checkBudget(workstream);
+            if (!budgetCheck.allowed) {
+                // Re-checked on every tick (computeClaims keeps 'blocked-budget'
+                // items in the waiting set — see scheduler.ts) rather than a
+                // one-time transition: the reason can change between checks (e.g.
+                // token ceiling was the blocker, then a cost ceiling is reached
+                // too), so keep it current even though the event only fires once
+                // per NEW block to avoid spamming listeners on every idle tick.
+                const wasAlreadyBlocked = item.state === 'blocked-budget';
+                item.state = 'blocked-budget';
+                item.blockedReason = budgetCheck.reason;
+                if (!wasAlreadyBlocked) {
+                    emit({ type: 'item-blocked-budget', workstreamId, itemId: item.id, phaseId: phase.id, reason: budgetCheck.reason ?? 'budget ceiling reached' });
+                }
+                continue;
+            }
+            void runItemPhase(workstream, item, phase)
+                .catch((error) => {
+                logger.error('orchestration engine: phase run threw', {
+                    workstreamId, itemId: item.id, phaseId: phase.id, error: summarizeError(error),
+                });
+                failItem(workstream, item, summarizeError(error));
+            })
+                .finally(() => {
+                if (!disposed)
+                    tick(workstreamId);
+            });
+        }
+    }
+    function start(workstreamId) {
+        tick(workstreamId);
+    }
+    function findItemAndWorkstream(itemId) {
+        for (const workstream of workstreams.values()) {
+            const item = workstream.items.find((i) => i.id === itemId);
+            if (item)
+                return { workstream, item };
+        }
+        return null;
+    }
+    function kill(itemId) {
+        const found = findItemAndWorkstream(itemId);
+        if (!found)
+            return false;
+        const { workstream, item } = found;
+        if (item.state === 'passed' || item.state === 'failed')
+            return false;
+        cancellation.abort(itemId);
+        if (item.agentId)
+            deps.agentManager.cancel(item.agentId, 'kill');
+        failItem(workstream, item, 'cancelled by operator');
+        emit({ type: 'item-cancelled', workstreamId: workstream.id, itemId, reason: 'cancelled by operator' });
+        return true;
+    }
+    function updateBudget(workstreamId, ceiling) {
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return false;
+        workstream.budget = ceiling;
+        tick(workstreamId);
+        return true;
+    }
+    function serializeWorkstream(workstreamId) {
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return null;
+        return serializeWorkstreamSnapshot(workstream, getPhaseResults(workstreamId));
+    }
+    function isTerminalWorkstream(workstream) {
+        return workstream.items.every((item) => item.state === 'passed' || item.state === 'failed');
+    }
+    /**
+     * An item persisted as 'in-phase' was mid-run when the snapshot was
+     * written (the debounced writer, persistence.ts, captures state
+     * synchronously — see runItemPhase — so this is always a crash artifact,
+     * never a live agent this process could still be waiting on). Left
+     * verbatim, it would count as an OCCUPIED capacity slot forever
+     * (computeClaims, scheduler.ts) while never being in the re-claimable
+     * waiting set, permanently starving every sibling in the same phase.
+     * Requeue it as 'pending' and drop the stale agentId so the next tick()
+     * reclaims it like any other waiting item — its prior PhaseResult (if any)
+     * was only ever pushed AFTER phase completion (see runItemPhase), so
+     * re-running the phase from here cannot produce a duplicate result.
+     */
+    function reconcileImportedItems(workstream) {
+        for (const item of workstream.items) {
+            if (item.state !== 'in-phase')
+                continue;
+            item.state = 'pending';
+            item.agentId = undefined;
+            emit({
+                type: 'item-requeued',
+                workstreamId: workstream.id,
+                itemId: item.id,
+                reason: 're-queued after restart — was in-phase when the snapshot was written',
+            });
+        }
+    }
+    function importWorkstream(snapshotJson, force = false) {
+        const snapshot = deserializeWorkstreamSnapshot(snapshotJson);
+        if (!snapshot)
+            return false;
+        const workstream = deserializeWorkstreamModel(snapshot.workstream);
+        const existing = workstreams.get(workstream.id);
+        if (existing && !isTerminalWorkstream(existing) && !force) {
+            logger.warn('orchestration engine: importWorkstream refused — existing workstream is non-terminal; use force=true to overwrite', {
+                workstreamId: workstream.id,
+            });
+            return false;
+        }
+        reconcileImportedItems(workstream);
+        workstreams.set(workstream.id, workstream);
+        completedResults.set(workstream.id, [...snapshot.completedResults]);
+        return true;
+    }
+    function resumeWorkstream(workstreamId) {
+        if (!workstreams.has(workstreamId)) {
+            const snapshot = loadWorkstreamSnapshot(deps.projectRoot, workstreamId);
+            if (!snapshot)
+                return false;
+            if (!importWorkstream(JSON.stringify(snapshot)))
+                return false;
+        }
+        tick(workstreamId);
+        return true;
+    }
+    function resumeAllFromDisk() {
+        let count = 0;
+        for (const workstreamId of listSnapshotWorkstreamIds(deps.projectRoot)) {
+            if (resumeWorkstream(workstreamId))
+                count += 1;
+        }
+        return count;
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        unsubscribeWriter();
+        listeners.clear();
+    }
+    return {
+        createWorkstream,
+        getWorkstream,
+        listWorkstreams,
+        insertPhase,
+        start,
+        kill,
+        updateBudget,
+        getPhaseResults,
+        serializeWorkstream,
+        importWorkstream,
+        resumeWorkstream,
+        resumeAllFromDisk,
+        on,
+        dispose,
+    };
+}

package/dist/platform/orchestration/index.d.ts

@@ -0,0 +1,18 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export type { BudgetCeiling, CommitExclusion, GateOutcome, OrchestrationEvent, OrchestrationEventListener, Phase, PhaseGateSpec, PhaseKind, PhaseResult, PhaseRole, PhaseSpec, SerializedWorkItem, SerializedWorkstream, WorkItem, WorkItemSpec, WorkItemState, WorkItemUsage, Workstream, WorkstreamSnapshot, } from './types.js';
+export { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage } from './types.js';
+export type { CreateWorkstreamInput, OrchestrationEngine, OrchestrationEngineDeps } from './engine.js';
+export { createOrchestrationEngine } from './engine.js';
+export type { CancellationRegistry } from './cancellation.js';
+export { createCancellationRegistry } from './cancellation.js';
+export type { BudgetCheck } from './budget.js';
+export { checkBudget } from './budget.js';
+export { deserializeWorkstream, deserializeWorkstreamSnapshot, listSnapshotWorkstreamIds, loadWorkstreamSnapshot, serializeWorkstream, serializeWorkstreamSnapshot, writeWorkstreamSnapshot, } from './persistence.js';
+export { fromChainSpec } from './controller-compat.js';
+export type { PhaseRunnerAgentManagerLike, PhaseRunnerDeps, PhaseRunOutcome, WrfcWorktreeOps } from './phase-runner.js';
+export { runPhase } from './phase-runner.js';
+export type { DirtyLaunchSnapshot, ScopedCommitExclusion } from './dirty-guard.js';
+export { excludeUntouchedLaunchResidue, hashWorkingTreeFile, snapshotDirtyTree } from './dirty-guard.js';
+export { computeClaims, firstPhase, nextPhaseAfter, phaseById, reviewPhaseBefore, sortedPhases, } from './scheduler.js';
+export type { PhaseClaim } from './scheduler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/orchestration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAMrF,YAAY,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,0BAA0B,EAC1B,KAAK,EACL,aAAa,EACb,SAAS,EACT,WAAW,EACX,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iCAAiC,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEnF,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAExD,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,YAAY,EAAE,2BAA2B,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACxH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzG,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/platform/orchestration/index.js

@@ -0,0 +1,10 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage } from './types.js';
+export { createOrchestrationEngine } from './engine.js';
+export { createCancellationRegistry } from './cancellation.js';
+export { checkBudget } from './budget.js';
+export { deserializeWorkstream, deserializeWorkstreamSnapshot, listSnapshotWorkstreamIds, loadWorkstreamSnapshot, serializeWorkstream, serializeWorkstreamSnapshot, writeWorkstreamSnapshot, } from './persistence.js';
+export { fromChainSpec } from './controller-compat.js';
+export { runPhase } from './phase-runner.js';
+export { excludeUntouchedLaunchResidue, hashWorkingTreeFile, snapshotDirtyTree } from './dirty-guard.js';
+export { computeClaims, firstPhase, nextPhaseAfter, phaseById, reviewPhaseBefore, sortedPhases, } from './scheduler.js';