@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/orchestration/engine.js

@@ -17,9 +17,10 @@ import { checkBudget } from './budget.js';
 import { createCancellationRegistry } from './cancellation.js';
 import { runPhase } from './phase-runner.js';
 import { snapshotDirtyTree } from './dirty-guard.js';
+import { createWorktreeIsolationManager } from './worktree-isolation.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 { computeClaims, dependencyStatus, firstPhase, nextPhaseAfter, reviewPhaseBefore, sortedPhases } from './scheduler.js';
+import { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage, mergeWorkItemUsage, } from './types.js';
 import { logger } from '../utils/logger.js';
 import { summarizeError } from '../utils/error-display.js';
 function generateId(prefix) {
@@ -61,6 +62,16 @@ export function createOrchestrationEngine(deps) {
     if (launchDirtySnapshot.size > 0) {
         emit({ type: 'dirty-tree-at-launch', paths: [...launchDirtySnapshot.keys()] });
     }
+    // Worktree-isolation lane (only ever exercised by a workstream created with
+    // isolation: 'worktree' — see createWorkstream/runItemPhase/failItem below).
+    // Constructing this unconditionally is cheap: it does no I/O until a
+    // worktree-mode workstream actually calls into it.
+    const worktreeIsolation = createWorktreeIsolationManager({
+        projectRoot: deps.projectRoot,
+        emit,
+        now,
+        keptWorktreeCap: deps.keptWorktreeCap,
+    });
     function getWorkstream(id) {
         return workstreams.get(id) ?? null;
     }
@@ -89,6 +100,7 @@ export function createOrchestrationEngine(deps) {
             id: spec.id ?? generateId('item'),
             title: spec.title,
             task: spec.task,
+            dependsOn: spec.dependsOn ? [...spec.dependsOn] : [],
             currentPhaseId: startPhaseId,
             state: startPhaseId ? 'pending' : 'passed',
             allAgentIds: [],
@@ -109,6 +121,8 @@ export function createOrchestrationEngine(deps) {
             phases,
             items: [],
             budget: input.budget,
+            isolation: input.isolation,
+            provenance: input.provenance,
             createdAt: now(),
         };
         const first = firstPhase(workstream)?.id ?? null;
@@ -156,7 +170,12 @@ export function createOrchestrationEngine(deps) {
             item.currentPhaseId = null;
             item.state = 'passed';
             item.completedAt = now();
-            emit({ type: 'item-passed', workstreamId: workstream.id, itemId: item.id });
+            emit({
+                type: 'item-passed',
+                workstreamId: workstream.id,
+                itemId: item.id,
+                ...(item.warnings && item.warnings.length > 0 ? { warnings: [...item.warnings] } : {}),
+            });
         }
     }
     function failItem(workstream, item, reason) {
@@ -164,6 +183,33 @@ export function createOrchestrationEngine(deps) {
         item.completedAt = now();
         item.failureReason = reason;
         emit({ type: 'item-failed', workstreamId: workstream.id, itemId: item.id, reason });
+        // Worktree-mode fail/kill cleanup rule (remove only if clean, else KEEP —
+        // data safety): covers every failItem call site uniformly, including
+        // kill() and the tick()-catch path for a throw before any phase outcome.
+        // No-op (instantly resolves) for a shared-isolation workstream, or an
+        // item that never reached a claim and therefore never got a worktree.
+        if (workstream.isolation === 'worktree') {
+            void worktreeIsolation.cleanupTerminated(workstream, item).catch((error) => {
+                logger.error('orchestration engine: worktree cleanup after item failure did not complete', {
+                    itemId: item.id, error: summarizeError(error),
+                });
+            });
+        }
+    }
+    /**
+     * Record a NON-FATAL bookkeeping note on an item without touching its
+     * terminal status (DEBT-4 item 1). Used for post-gate faults that do not
+     * negate the phase's passed work — e.g. a scoped commit that could not
+     * complete. The item still passes/advances; the warning rides along on
+     * `item.warnings` and, for a terminal pass, in the `item-passed` event, so a
+     * passed-with-caveats outcome is visible instead of hidden or mislabelled.
+     */
+    function warnItem(item, note) {
+        (item.warnings ??= []).push(note);
+        logger.warn('orchestration engine: non-fatal bookkeeping warning on a passed work item', {
+            itemId: item.id,
+            note,
+        });
     }
     /** Indirection to defeat TS's cross-await narrowing of item.state — see the call site below. */
     function currentState(item) {
@@ -174,6 +220,24 @@ export function createOrchestrationEngine(deps) {
         item.state = 'in-phase';
         item.currentPhaseId = phase.id;
         item.blockedReason = undefined;
+        // Worktree mode: ensure this item has its dedicated worktree BEFORE
+        // spawning its phase agent (idempotent — a no-op from the item's second
+        // phase onward, since the worktree persists across the item's whole run;
+        // see WorktreeIsolationManager.ensureWorktree). A setup failure here is a
+        // genuine phase-run failure (there is nowhere isolated for the agent to
+        // work) — fail the item honestly rather than silently falling back to the
+        // shared tree, which would defeat isolation's whole purpose.
+        let itemWorktree;
+        if (workstream.isolation === 'worktree') {
+            try {
+                itemWorktree = await worktreeIsolation.ensureWorktree(workstream, item);
+            }
+            catch (error) {
+                logger.error('orchestration engine: failed to prepare item worktree', { itemId: item.id, error: summarizeError(error) });
+                failItem(workstream, item, `worktree isolation setup failed: ${summarizeError(error)}`);
+                return;
+            }
+        }
         const priorReports = getPhaseResults(workstream.id).filter((r) => r.itemId === item.id);
         const outcome = await runPhase(workstream, item, phase, priorReports, {
             agentManager: deps.agentManager,
@@ -186,8 +250,26 @@ export function createOrchestrationEngine(deps) {
             priceUsage: deps.priceUsage,
             skipClaimVerification: deps.skipClaimVerification,
             launchDirtySnapshot,
+            itemWorktree,
         });
-        item.usage = mergeUsageFromResult(item.usage, outcome.result.usage);
+        // ── Bookkeeping region (AFTER the phase produced its outcome) ───────────
+        // From here on everything is bookkeeping layered on top of a verdict the
+        // phase has ALREADY reached (outcome.result.gate + agentStatus). It must
+        // never be able to turn a passed phase into a failed item: the item's
+        // terminal status derives ONLY from that phase outcome, plus the narrow
+        // negating set (bookkeeping.ts). A bookkeeping fault becomes a warning on a
+        // passed item (warnItem), never a failure — that is what makes "item failed
+        // while every phase passed and the commit landed" unrepresentable
+        // (DEBT-4 item 1). A throw BEFORE this point — inside runPhase, e.g. a gate
+        // subprocess that never yielded a verdict — legitimately reaches tick()'s
+        // catch and fails the item, because there is then no phase outcome to
+        // stand on.
+        try {
+            item.usage = mergeWorkItemUsage(item.usage, outcome.result.usage);
+        }
+        catch (error) {
+            warnItem(item, `usage rollup skipped: ${summarizeError(error)}`);
+        }
         const results = completedResults.get(workstream.id) ?? [];
         results.push(outcome.result);
         completedResults.set(workstream.id, results);
@@ -209,6 +291,22 @@ export function createOrchestrationEngine(deps) {
             return;
         }
         if (outcome.result.gate.passed) {
+            // The PHASE PASSED. Post-gate commit bookkeeping can only WARN this item
+            // (or, for the narrow negating set, fail it) — it can never contradict
+            // the passed verdict the gate already reached.
+            const commit = outcome.result.commit;
+            if (commit?.status === 'failed' && commit.negating) {
+                // Negating set: the commit/merge left the workspace corrupted, so the
+                // recorded pass can no longer be trusted — this is the one post-gate
+                // condition that genuinely fails the item.
+                failItem(workstream, item, `phase gate passed but the workspace was left unrecorded/corrupted: ${commit.reason ?? 'commit failed'}`);
+                return;
+            }
+            if (commit?.status === 'failed') {
+                // Non-negating: the gate passed and the workspace is coherent, so the
+                // work stands. Surface the miss as a warning, never a failure.
+                warnItem(item, `scoped commit did not complete (non-fatal): ${commit.reason ?? 'commit failed'}`);
+            }
             // 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
@@ -218,6 +316,16 @@ export function createOrchestrationEngine(deps) {
                 ? (reviewPhaseBefore(workstream, phase) ?? nextPhaseAfter(workstream, phase.ordinal) ?? null)
                 : (nextPhaseAfter(workstream, phase.ordinal) ?? null);
             routeItem(workstream, item, forwardTarget, phase.id);
+            // The item just terminated PASSED (no further phase) — in worktree mode
+            // its branch now enters the single sequential integration lane
+            // (completion order, not claim order). Fire-and-forget: the lane
+            // manages its own ordering and never rejects (see
+            // WorktreeIsolationManager.enqueueIntegration), so tick() is never
+            // blocked waiting on a merge that may itself await a sibling ahead of
+            // it in the lane.
+            if (forwardTarget === null && workstream.isolation === 'worktree') {
+                void worktreeIsolation.enqueueIntegration(workstream, item);
+            }
             return;
         }
         // A review's FAILING gate with unsatisfied constraints gets one more
@@ -233,22 +341,66 @@ export function createOrchestrationEngine(deps) {
         }
         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',
-        };
+    /**
+     * Dependency-gate pre-pass (BIG-3 item 2), run at the top of every tick
+     * BEFORE computeClaims. For each item still sitting at its FIRST phase in a
+     * pre-claim state (pending / awaiting-capacity / blocked-dependency) with
+     * declared dependencies, classify those dependencies and either release or
+     * refuse the item:
+     *   - every dependency 'passed' → RELEASE: if it was 'blocked-dependency',
+     *     restore it to 'pending' and clear blockedReason (emit
+     *     item-dependency-cleared) so computeClaims can pick it up this same tick.
+     *   - any dependency unmet → REFUSE: set 'blocked-dependency' with an honest
+     *     blockedReason ('waiting on: …' or 'dependency failed: …'), recomputed
+     *     every tick so it stays current as dependencies change; emit
+     *     item-blocked-dependency only on a NEW block (never once per idle tick).
+     *
+     * Only FIRST-phase items are gated. Once an item's dependencies are all
+     * passed at its first claim they stay passed (passed is terminal), so a
+     * mid-pipeline item (currentPhaseId past the first phase) is never re-gated.
+     * A retried item (engine.retryItem) is reset back to the first phase and is
+     * therefore re-gated here — which is exactly why a failed dependency's
+     * dependents recover only once the dependency is retried AND passes.
+     * A FAILED dependency keeps the dependent blocked (recoverable), never fails
+     * it — refuse-not-kill.
+     */
+    function applyDependencyGates(workstream) {
+        const first = firstPhase(workstream);
+        if (!first)
+            return;
+        for (const item of workstream.items) {
+            if (item.dependsOn.length === 0)
+                continue;
+            if (item.currentPhaseId !== first.id)
+                continue; // only gate at entry (first phase)
+            if (item.state !== 'pending' && item.state !== 'awaiting-capacity' && item.state !== 'blocked-dependency')
+                continue;
+            const status = dependencyStatus(workstream, item);
+            if (status.ready) {
+                if (item.state === 'blocked-dependency') {
+                    item.state = 'pending';
+                    item.blockedReason = undefined;
+                    emit({ type: 'item-dependency-cleared', workstreamId: workstream.id, itemId: item.id });
+                }
+                continue;
+            }
+            const reason = status.failed.length > 0
+                ? `dependency failed: ${status.failed.join(', ')}`
+                : `waiting on: ${status.waiting.join(', ')}`;
+            const wasAlreadyBlocked = item.state === 'blocked-dependency';
+            item.state = 'blocked-dependency';
+            item.blockedReason = reason;
+            if (!wasAlreadyBlocked) {
+                emit({
+                    type: 'item-blocked-dependency',
+                    workstreamId: workstream.id,
+                    itemId: item.id,
+                    phaseId: item.currentPhaseId ?? '',
+                    reason,
+                    deps: [...item.dependsOn],
+                });
+            }
+        }
     }
     function tick(workstreamId) {
         if (disposed)
@@ -256,6 +408,10 @@ export function createOrchestrationEngine(deps) {
         const workstream = workstreams.get(workstreamId);
         if (!workstream)
             return;
+        // Dependency gate FIRST — release/refuse first-phase items by their
+        // dependencies before computeClaims decides capacity (which never sees a
+        // 'blocked-dependency' item, see scheduler.ts computeClaims).
+        applyDependencyGates(workstream);
         const claims = computeClaims(workstream);
         for (const { item, phase } of claims) {
             const budgetCheck = checkBudget(workstream);
@@ -276,7 +432,14 @@ export function createOrchestrationEngine(deps) {
             }
             void runItemPhase(workstream, item, phase)
                 .catch((error) => {
-                logger.error('orchestration engine: phase run threw', {
+                // Reaching here means runItemPhase rejected BEFORE the phase produced
+                // an outcome — the run threw inside runPhase (spawn, gate execution,
+                // etc.) with no gate verdict to stand on. That is a genuine phase
+                // failure, so failing the item is honest. Post-outcome bookkeeping
+                // faults never reach here: runItemPhase converts them to warnings on
+                // a passed item (or, for the negating set, an explicit failItem) —
+                // see its bookkeeping region (DEBT-4 item 1).
+                logger.error('orchestration engine: phase run threw before producing an outcome', {
                     workstreamId, itemId: item.id, phaseId: phase.id, error: summarizeError(error),
                 });
                 failItem(workstream, item, summarizeError(error));
@@ -320,6 +483,35 @@ export function createOrchestrationEngine(deps) {
         tick(workstreamId);
         return true;
     }
+    /**
+     * See the OrchestrationEngine.retryItem doc. Resets a failed item to
+     * 'pending' at the first phase; clears the terminal fields and the per-phase
+     * visit budget (a fresh fix-cycle allowance for the retry) but RETAINS
+     * accumulated `usage` (monotone — a retry adds to the tally, never wipes it).
+     * In worktree mode a still-present KEPT worktree is reused (ensureWorktree is
+     * idempotent on worktreePath); a worktree already removed after the failure
+     * is recreated at the next first claim.
+     */
+    function retryItem(itemId) {
+        const found = findItemAndWorkstream(itemId);
+        if (!found)
+            return false;
+        const { workstream, item } = found;
+        if (item.state !== 'failed')
+            return false;
+        const first = firstPhase(workstream);
+        if (!first)
+            return false;
+        item.state = 'pending';
+        item.currentPhaseId = first.id;
+        item.failureReason = undefined;
+        item.completedAt = undefined;
+        item.blockedReason = undefined;
+        item.visits.clear();
+        emit({ type: 'item-retried', workstreamId: workstream.id, itemId, reason: 'reset to re-run after failure' });
+        tick(workstream.id);
+        return true;
+    }
     function serializeWorkstream(workstreamId) {
         const workstream = workstreams.get(workstreamId);
         if (!workstream)
@@ -371,6 +563,18 @@ export function createOrchestrationEngine(deps) {
         reconcileImportedItems(workstream);
         workstreams.set(workstream.id, workstream);
         completedResults.set(workstream.id, [...snapshot.completedResults]);
+        // Orphan worktree reconciliation (worktree mode only) — SYNCHRONOUS and
+        // done BEFORE this function returns, i.e. before any caller can call
+        // start()/tick() on this workstream. An on-disk `ws/<wsShort>/*` worktree
+        // not already recorded on one of the just-imported items is a crash
+        // artifact from a prior process; adopt it onto a matching unresolved item
+        // or report it for the operator (NEVER deleted on sight) — see
+        // WorktreeIsolationManager.reconcileOrphans for why this must not race
+        // the first tick()'s claim (it would otherwise risk creating a second
+        // worktree at the same deterministic path).
+        if (workstream.isolation === 'worktree') {
+            worktreeIsolation.reconcileOrphans(workstream);
+        }
         return true;
     }
     function resumeWorkstream(workstreamId) {
@@ -407,6 +611,7 @@ export function createOrchestrationEngine(deps) {
         start,
         kill,
         updateBudget,
+        retryItem,
         getPhaseResults,
         serializeWorkstream,
         importWorkstream,

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

@@ -1,5 +1,5 @@
 /** 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 type { BudgetCeiling, CommitExclusion, GateOutcome, ItemMergeState, OrchestrationEvent, OrchestrationEventListener, Phase, PhaseGateSpec, PhaseKind, PhaseResult, PhaseRole, PhaseSpec, SerializedWorkItem, SerializedWorkstream, WorkItem, WorkItemSpec, WorkItemState, WorkItemUsage, Workstream, WorkstreamIsolation, WorkstreamProvenance, 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';
@@ -8,11 +8,13 @@ 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 { engineerReviewPhases, fromChainSpec } from './controller-compat.js';
+export { fromPlanProposal } from './proposal-workstream.js';
+export type { FromPlanProposalOptions } from './proposal-workstream.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';
+export { computeClaims, dependencyStatus, firstPhase, nextPhaseAfter, phaseById, reviewPhaseBefore, sortedPhases, } from './scheduler.js';
+export type { DependencyStatus, PhaseClaim } from './scheduler.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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,cAAc,EACd,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,mBAAmB,EACnB,oBAAoB,EACpB,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,oBAAoB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,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,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/platform/orchestration/index.js

@@ -4,7 +4,8 @@ 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 { engineerReviewPhases, fromChainSpec } from './controller-compat.js';
+export { fromPlanProposal } from './proposal-workstream.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';
+export { computeClaims, dependencyStatus, firstPhase, nextPhaseAfter, phaseById, reviewPhaseBefore, sortedPhases, } from './scheduler.js';

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

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/persistence.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAerF,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEhB,KAAK,oBAAoB,EAEzB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAYpB,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,oBAAoB,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,oBAAoB,GAAG,UAAU,CAElF;AAED,qJAAqJ;AACrJ,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAa3H;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CA6BrF;AAUD,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAsB3G;AAED,uHAAuH;AACvH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAWvE;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAUnI;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,EAC1D,mBAAmB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,WAAW,EAAE,EACrE,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,KAAK,MAAM,IAAI,GACvE,MAAM,IAAI,CA4BZ"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/persistence.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAerF,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEhB,KAAK,oBAAoB,EAEzB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAepB,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,oBAAoB,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,oBAAoB,GAAG,UAAU,CAElF;AAED,qJAAqJ;AACrJ,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAa3H;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CA6BrF;AAUD,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAsB3G;AAED,uHAAuH;AACvH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAWvE;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAUnI;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,EAC1D,mBAAmB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,WAAW,EAAE,EACrE,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,KAAK,MAAM,IAAI,GACvE,MAAM,IAAI,CA4BZ"}

package/dist/platform/orchestration/persistence.js

@@ -18,7 +18,10 @@ function serializeWorkItem(item) {
     return { ...item, visits: Object.fromEntries(item.visits) };
 }
 function deserializeWorkItem(raw) {
-    return { ...raw, visits: new Map(Object.entries(raw.visits)) };
+    // `dependsOn` (BIG-3 item 2) defaults to [] for snapshots written before the
+    // field existed, so an older snapshot deserializes as an un-gated item rather
+    // than crashing the dependency pre-pass on an undefined array.
+    return { ...raw, dependsOn: raw.dependsOn ?? [], visits: new Map(Object.entries(raw.visits)) };
 }
 export function serializeWorkstream(workstream) {
     return { ...workstream, items: workstream.items.map(serializeWorkItem) };

package/dist/platform/orchestration/phase-runner.d.ts

@@ -47,6 +47,7 @@
 import type { AgentManager } from '../tools/agent/manager.js';
 import type { ConfigManager } from '../config/manager.js';
 import type { RuntimeEventBus } from '../runtime/events/index.js';
+import { type CommitWorkingTreeResult } from '../agents/worktree.js';
 import type { CancellationRegistry } from './cancellation.js';
 import { type DirtyLaunchSnapshot } from './dirty-guard.js';
 import type { Phase, PhaseResult, WorkItem, WorkItemUsage, Workstream } from './types.js';
@@ -56,9 +57,22 @@ export type PhaseRunnerAgentManagerLike = Pick<AgentManager, 'spawn' | 'getStatu
 export interface WrfcWorktreeOps {
     merge(agentId: string): Promise<boolean>;
     cleanup(agentId: string): Promise<void>;
-    commitWorkingTree(message: string, paths?: string[]): Promise<string | null>;
+    commitWorkingTree(message: string, paths?: string[]): Promise<CommitWorkingTreeResult>;
     currentHead(): Promise<string | null>;
 }
+/**
+ * The minimal surface of an item's IsolatedWorktree (worktree.ts) that the
+ * phase-runner needs in `worktree` isolation mode: the on-disk `path` (used as
+ * the spawned agent's working directory) and a scoped `commit` onto the item
+ * branch. Notably NOT merge/cleanup — in worktree mode the item worktree
+ * persists across the item's phases and the engine's sequential integration
+ * lane owns the merge-back and cleanup, so a phase NEVER merges to base or
+ * removes the worktree.
+ */
+export interface PhaseItemWorktree {
+    readonly path: string;
+    commit(message: string, paths?: string[]): Promise<CommitWorkingTreeResult>;
+}
 export interface PhaseRunnerDeps {
     readonly agentManager: PhaseRunnerAgentManagerLike;
     readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
@@ -75,12 +89,25 @@ export interface PhaseRunnerDeps {
      * today's behavior: no exclusion, every candidate path is committed.
      */
     readonly launchDirtySnapshot?: DirtyLaunchSnapshot | undefined;
+    /**
+     * Present ONLY in `worktree` isolation mode: this item's dedicated worktree
+     * (created by the engine at first claim). When set, the phase's scoped commit
+     * lands on the item branch INSIDE this worktree (not the shared projectRoot),
+     * and the spawned agent runs with its working directory set to the worktree
+     * path. Absent ⇒ shared mode, every existing behavior unchanged.
+     */
+    readonly itemWorktree?: PhaseItemWorktree | undefined;
 }
 export interface PhaseRunOutcome {
     readonly result: PhaseResult;
     readonly agentStatus: 'completed' | 'failed' | 'cancelled';
 }
-/** Combines a new phase's usage into a work item's running total. Single-source cost (never independently re-priced here). */
+/**
+ * Combines a new phase's usage into a work item's running total. Single-source
+ * cost (never independently re-priced here). Thin alias over the canonical
+ * {@link mergeWorkItemUsage} (types.ts) so the phase-runner, the engine, and
+ * the fleet rollup adapters all fold usage through exactly one implementation.
+ */
 export declare function mergeUsage(a: WorkItemUsage, b: WorkItemUsage): WorkItemUsage;
 /** Runs one WorkItem through one Phase to completion (or cancellation/failure). Recurses (bounded by transportRetryLimit) on a transport-classified spawn failure. */
 export declare function runPhase(workstream: Workstream, item: WorkItem, phase: Phase, priorReports: readonly PhaseResult[], deps: PhaseRunnerDeps): Promise<PhaseRunOutcome>;

package/dist/platform/orchestration/phase-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phase-runner.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/phase-runner.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAelE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAiC,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,KAAK,EAAgC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExH,+FAA+F;AAC/F,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,YAAY,EACZ,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,4BAA4B,GAAG,2BAA2B,CAC9F,CAAC;AAEF,4JAA4J;AAC5J,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7E,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,2BAA2B,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,aAAa,CAAC,CAAC;IACnE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,eAAe,CAAC,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACvG,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CAChE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;CAC5D;AA8ED,8HAA8H;AAC9H,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,aAAa,CAgB5E;AAyGD,sKAAsK;AACtK,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,eAAe,CAAC,CAuG1B"}
+{"version":3,"file":"phase-runner.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/phase-runner.ts"],"names":[],"mappings":"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"}