@pellux/goodvibes-sdk 0.37.1 → 0.38.0

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

@@ -0,0 +1,87 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Phase-runner (Wave 4, wo701) — runs one WorkItem through one Phase: spawn
+ * agent, await completion, verify claims, run gates, commit, cleanup.
+ *
+ * REUSES the hardened WRFC primitives verbatim (same functions WrfcController
+ * itself calls, so behavior can't fork): verifyEngineerClaims
+ * (wrfc-reporting.ts) for the phantom-work guard, runWrfcGateChecks
+ * (wrfc-gate-runtime.ts) for quality gates, AgentWorktree.commitWorkingTree
+ * for scoped commits, and the transport-retry / WrfcChainFailureKind pattern
+ * (isTransportFailureMessage + getWrfcTransportRetryLimit/DelayMs) for
+ * bounded respawn-on-transport-blip.
+ *
+ * REALITY-WINS DIVERGENCE from the brief's design (c): WrfcController itself
+ * (wrfc-controller.ts, verified) never calls AgentWorktree.create() for its
+ * role agents — engineer/reviewer/fixer/integrator all run in the SAME
+ * shared `projectRoot` working directory; AgentWorktree is used ONLY for its
+ * commitWorkingTree/merge/cleanup surface (merge/cleanup are safe no-ops
+ * when no isolated worktree dir exists, which is always, today). There is no
+ * per-agent `workingDirectory` override anywhere in AgentInput /
+ * AgentOrchestratorRunContext.createRunContext() (verified: the latter is
+ * fixed per AgentOrchestrator instance, not per-spawn), so a spawned agent
+ * cannot actually be pointed at an isolated worktree directory without new
+ * cross-cutting plumbing through AgentManager/AgentOrchestrator construction
+ * — well beyond this module's boundary, and not something WrfcController
+ * itself has either. This module therefore mirrors WrfcController's ACTUAL
+ * (shared-directory) behavior rather than the brief's aspirational
+ * per-item-isolated-worktree fan-out; true fan-out isolation is a valuable,
+ * separately-scoped follow-up (see the work-order report).
+ *
+ * SECOND REALITY-WINS DIVERGENCE: AgentManager.spawn()'s root-spawn
+ * normalization (tools/agent/wrfc-batch-policy.ts isRootReviewRoleTask) force
+ * -rewrites any PARENTLESS spawn whose template is literally
+ * reviewer/tester/verifier/qa/review/test, OR whose task text matches
+ * ROLE_ACTION_RE/ROLE_PREFIX_RE (e.g. "review the diff"), into an
+ * 'engineer'-templated WRFC-owner chain with `dangerously_disable_wrfc`
+ * forced back to `false` — REGARDLESS of what this module passes in.
+ * Phase-runner spawns are always parentless (a workstream has no owning
+ * AgentRecord), so it must dodge that heuristic by construction: never
+ * literally template review/test-flavored phases as one of those role
+ * strings (use 'general' instead — see templateForPhase), and phrase
+ * review-phase prompts with "assess/evaluate" rather than "review/test/
+ * verify" (see buildPhaseTask). This is load-bearing: changing this wording
+ * without checking wrfc-batch-policy.ts's regexes again risks silently
+ * re-activating the WRFC hijack for review-kind phases.
+ */
+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 { CancellationRegistry } from './cancellation.js';
+import { type DirtyLaunchSnapshot } from './dirty-guard.js';
+import type { Phase, PhaseResult, WorkItem, WorkItemUsage, Workstream } from './types.js';
+/** Narrow structural pick — testable with stubs, mirrors AgentManagerLike (wrfc-config.ts). */
+export type PhaseRunnerAgentManagerLike = Pick<AgentManager, 'spawn' | 'getStatus' | 'cancel' | 'registerCancellationSignal' | 'releaseCancellationSignal'>;
+/** Structural pick of AgentWorktree's surface — matches WrfcController's WrfcWorktreeOps injection seam exactly, so the same test doubles work for both. */
+export interface WrfcWorktreeOps {
+    merge(agentId: string): Promise<boolean>;
+    cleanup(agentId: string): Promise<void>;
+    commitWorkingTree(message: string, paths?: string[]): Promise<string | null>;
+    currentHead(): Promise<string | null>;
+}
+export interface PhaseRunnerDeps {
+    readonly agentManager: PhaseRunnerAgentManagerLike;
+    readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
+    readonly runtimeBus: RuntimeEventBus;
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly createWorktree?: (() => WrfcWorktreeOps) | undefined;
+    readonly cancellation: CancellationRegistry;
+    readonly priceUsage?: ((model: string | undefined, usage: WorkItemUsage) => number | null) | undefined;
+    readonly skipClaimVerification?: boolean | undefined;
+    /**
+     * The dirty-tree snapshot taken synchronously at engine launch (Wave 6,
+     * wo-F item 4 — see dirty-guard.ts). Absent (undefined) degrades to
+     * today's behavior: no exclusion, every candidate path is committed.
+     */
+    readonly launchDirtySnapshot?: DirtyLaunchSnapshot | 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). */
+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>;
+//# sourceMappingURL=phase-runner.d.ts.map

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

@@ -0,0 +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"}

package/dist/platform/orchestration/phase-runner.js

@@ -0,0 +1,274 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+import { AgentWorktree } from '../agents/worktree.js';
+import { parseCompletionReport, } from '../agents/completion-report.js';
+import { verifyEngineerClaims } from '../agents/wrfc-reporting.js';
+import { runWrfcGateChecks } from '../agents/wrfc-gate-runtime.js';
+import { getWrfcTransportRetryDelayMs, getWrfcTransportRetryLimit } from '../agents/wrfc-config.js';
+import { isTransportFailureMessage } from '../types/errors.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+import { excludeUntouchedLaunchResidue } from './dirty-guard.js';
+function templateForPhase(phase) {
+    return phase.kind === 'review' || phase.kind === 'gate' ? 'general' : 'engineer';
+}
+function buildPhaseTask(item, phase, priorReports) {
+    const priorContext = priorReports.length > 0
+        ? `\n\nPrior phase reports for this work item:\n${priorReports.map((r) => `- ${r.phaseId}: ${r.report.summary}`).join('\n')}`
+        : '';
+    if (phase.kind === 'review' || phase.kind === 'gate') {
+        return `Assess the following work item's changes against its constraints and report findings. Do not modify files.\n\nWork item: ${item.title}\n${item.task}${priorContext}`;
+    }
+    if (phase.kind === 'fix') {
+        return `Address the following findings for this work item.\n\nWork item: ${item.title}\n${item.task}${priorContext}`;
+    }
+    return `${item.task}${priorContext}`;
+}
+function genericReport(summary) {
+    return { version: 1, archetype: 'generic', summary, result: summary };
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function awaitAgentTermination(runtimeBus, agentManager, agentId) {
+    return new Promise((resolve) => {
+        const unsubscribe = runtimeBus.onDomain('agents', (envelope) => {
+            const event = envelope.payload;
+            if (event.agentId !== agentId)
+                return;
+            if (event.type !== 'AGENT_COMPLETED' && event.type !== 'AGENT_FAILED' && event.type !== 'AGENT_CANCELLED')
+                return;
+            unsubscribe();
+            const status = event.type === 'AGENT_COMPLETED' ? 'completed' : event.type === 'AGENT_CANCELLED' ? 'cancelled' : 'failed';
+            resolve({ status, record: agentManager.getStatus(agentId) });
+        });
+    });
+}
+function usageFromRecord(record, priceUsage) {
+    const u = record?.usage;
+    const base = {
+        inputTokens: u?.inputTokens ?? 0,
+        outputTokens: u?.outputTokens ?? 0,
+        cacheReadTokens: u?.cacheReadTokens ?? 0,
+        cacheWriteTokens: u?.cacheWriteTokens ?? 0,
+        reasoningTokens: u?.reasoningTokens,
+        llmCallCount: u?.llmCallCount ?? 0,
+        turnCount: u?.turnCount ?? 0,
+        toolCallCount: record?.toolCallCount ?? 0,
+    };
+    let costUsd = null;
+    let costState = 'unpriced';
+    if (u && priceUsage) {
+        try {
+            const priced = priceUsage(record?.model, { ...base, costUsd: null, costState: 'unpriced' });
+            if (priced !== null) {
+                costUsd = priced;
+                costState = 'priced';
+            }
+        }
+        catch {
+            // stays unpriced — never fabricate a cost from a throwing pricer.
+        }
+    }
+    return { ...base, costUsd, costState };
+}
+/** Combines a new phase's usage into a work item's running total. Single-source cost (never independently re-priced here). */
+export function mergeUsage(a, b) {
+    const sawReasoning = a.reasoningTokens !== undefined || b.reasoningTokens !== undefined;
+    const bothPriced = a.costState === 'priced' && b.costState === 'priced';
+    const neitherPriced = a.costUsd === null && b.costUsd === null;
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+        reasoningTokens: sawReasoning ? (a.reasoningTokens ?? 0) + (b.reasoningTokens ?? 0) : undefined,
+        llmCallCount: a.llmCallCount + b.llmCallCount,
+        turnCount: a.turnCount + b.turnCount,
+        toolCallCount: a.toolCallCount + b.toolCallCount,
+        costUsd: a.costUsd !== null && b.costUsd !== null ? a.costUsd + b.costUsd : (a.costUsd ?? b.costUsd),
+        costState: bothPriced ? 'priced' : neitherPriced ? 'unpriced' : 'estimated',
+    };
+}
+/** Quality gates (global-config-driven, reused VERBATIM) + phase-required-gate assertion + phantom guard + reviewer constraint findings. */
+async function evaluateGate(workstream, phase, report, deps) {
+    const results = [...await runWrfcGateChecks({
+            configManager: deps.configManager,
+            projectRoot: deps.projectRoot,
+            runtimeBus: deps.runtimeBus,
+            sessionId: deps.sessionId,
+            chainId: workstream.id,
+        })];
+    const ranNames = new Set(results.map((r) => r.gate));
+    const missingRequired = phase.gate.gates.filter((name) => !ranNames.has(name));
+    for (const name of missingRequired) {
+        results.push({ gate: name, passed: false, output: 'required gate is not configured/enabled', durationMs: 0 });
+    }
+    if (report.archetype === 'engineer' && !deps.skipClaimVerification) {
+        const verification = verifyEngineerClaims(report, deps.projectRoot);
+        if (verification.kind === 'unverified' || verification.kind === 'unverifiable_no_claims') {
+            results.push({ gate: 'phantom-work-guard', passed: false, output: verification.summary, durationMs: 0 });
+        }
+    }
+    let constraintFindings;
+    let unsatisfiedConstraintIds;
+    if (report.archetype === 'reviewer') {
+        const reviewer = report;
+        constraintFindings = reviewer.constraintFindings ?? [];
+        const unsatisfied = constraintFindings.filter((f) => !f.satisfied);
+        unsatisfiedConstraintIds = unsatisfied.map((f) => f.constraintId);
+        if (!reviewer.passed || unsatisfied.length > 0) {
+            results.push({
+                gate: 'reviewer-verdict',
+                passed: false,
+                output: unsatisfied.length > 0
+                    ? `${unsatisfied.length} unsatisfied constraint(s): ${unsatisfied.map((f) => f.constraintId).join(', ')}`
+                    : 'reviewer did not pass',
+                durationMs: 0,
+            });
+        }
+    }
+    return {
+        passed: results.every((r) => r.passed),
+        results,
+        constraintFindings,
+        unsatisfiedConstraintIds,
+    };
+}
+async function commitPhaseWork(item, phase, agentId, worktree, deps) {
+    if (phase.gate.scope === 'off')
+        return undefined;
+    let paths = phase.gate.scope === 'scoped' ? item.touchedPaths : undefined;
+    let exclusion;
+    if (paths && paths.length > 0 && deps.launchDirtySnapshot) {
+        const launchSnapshot = deps.launchDirtySnapshot;
+        if (launchSnapshot.size > 0) {
+            const { included, excluded } = excludeUntouchedLaunchResidue(deps.projectRoot, paths, launchSnapshot);
+            if (excluded.length > 0) {
+                exclusion = { excludedPaths: excluded, skipped: included.length === 0 };
+                if (included.length === 0) {
+                    // Every candidate path is untouched launch-dirty residue — an
+                    // honest "nothing this phase did needs committing", not a silent
+                    // no-op AND not a fallback to sweeping the whole working tree.
+                    logger.info('orchestration phase-runner: scoped commit skipped — every candidate path is untouched launch-dirty residue', {
+                        itemId: item.id,
+                        phaseId: phase.id,
+                        excludedPaths: excluded,
+                    });
+                    return exclusion;
+                }
+                logger.info('orchestration phase-runner: excluded untouched launch-dirty residue from scoped commit', {
+                    itemId: item.id,
+                    phaseId: phase.id,
+                    excludedPaths: excluded,
+                });
+                paths = [...included];
+            }
+        }
+    }
+    try {
+        await worktree.commitWorkingTree(`orchestration: ${item.title} — ${phase.kind} phase`, paths);
+        await worktree.merge(agentId);
+    }
+    catch (error) {
+        logger.warn('orchestration phase-runner: commit/merge failed', { itemId: item.id, phaseId: phase.id, error: summarizeError(error) });
+    }
+    return exclusion;
+}
+/** Runs one WorkItem through one Phase to completion (or cancellation/failure). Recurses (bounded by transportRetryLimit) on a transport-classified spawn failure. */
+export async function runPhase(workstream, item, phase, priorReports, deps) {
+    const startedAt = Date.now();
+    const createWorktree = deps.createWorktree ?? (() => new AgentWorktree(deps.projectRoot));
+    const worktree = createWorktree();
+    const record = deps.agentManager.spawn({
+        mode: 'spawn',
+        task: buildPhaseTask(item, phase, priorReports),
+        template: templateForPhase(phase),
+        dangerously_disable_wrfc: true,
+    });
+    record.workItemId = item.id;
+    item.agentId = record.id;
+    item.allAgentIds.push(record.id);
+    item.branch ??= `agent/${item.id}`;
+    const signal = deps.cancellation.start(item.id);
+    deps.agentManager.registerCancellationSignal(record.id, signal);
+    let outcome;
+    try {
+        outcome = await awaitAgentTermination(deps.runtimeBus, deps.agentManager, record.id);
+    }
+    finally {
+        deps.agentManager.releaseCancellationSignal(record.id);
+        deps.cancellation.release(item.id);
+    }
+    const usage = usageFromRecord(outcome.record, deps.priceUsage);
+    if (outcome.status === 'cancelled') {
+        await worktree.cleanup(record.id).catch(() => undefined);
+        return {
+            agentStatus: 'cancelled',
+            result: {
+                itemId: item.id,
+                phaseId: phase.id,
+                agentId: record.id,
+                report: genericReport('cancelled by operator'),
+                gate: { passed: false, results: [] },
+                startedAt,
+                completedAt: Date.now(),
+                usage,
+            },
+        };
+    }
+    if (outcome.status === 'failed') {
+        const transportFailure = isTransportFailureMessage(outcome.record?.error ?? '');
+        const retryLimit = getWrfcTransportRetryLimit(deps.configManager);
+        if (transportFailure && item.transportRetryCount < retryLimit) {
+            item.transportRetryCount += 1;
+            await worktree.cleanup(record.id).catch(() => undefined);
+            await sleep(getWrfcTransportRetryDelayMs(deps.configManager));
+            return runPhase(workstream, item, phase, priorReports, deps);
+        }
+        await worktree.cleanup(record.id).catch(() => undefined);
+        return {
+            agentStatus: 'failed',
+            result: {
+                itemId: item.id,
+                phaseId: phase.id,
+                agentId: record.id,
+                report: genericReport(outcome.record?.error ?? 'agent failed'),
+                gate: { passed: false, results: [] },
+                startedAt,
+                completedAt: Date.now(),
+                usage,
+            },
+        };
+    }
+    const report = parseCompletionReport(outcome.record?.fullOutput ?? '') ?? genericReport(outcome.record?.fullOutput ?? '');
+    if (report.archetype === 'engineer') {
+        const engineerReport = report;
+        for (const path of [...engineerReport.filesCreated, ...engineerReport.filesModified, ...engineerReport.filesDeleted]) {
+            if (!item.touchedPaths.includes(path))
+                item.touchedPaths.push(path);
+        }
+    }
+    const gate = await evaluateGate(workstream, phase, report, deps);
+    let commitExclusion;
+    if (gate.passed) {
+        commitExclusion = await commitPhaseWork(item, phase, record.id, worktree, deps);
+    }
+    await worktree.cleanup(record.id).catch(() => undefined);
+    return {
+        agentStatus: 'completed',
+        result: {
+            itemId: item.id,
+            phaseId: phase.id,
+            agentId: record.id,
+            report,
+            gate,
+            startedAt,
+            completedAt: Date.now(),
+            usage,
+            ...(commitExclusion ? { commitExclusion } : {}),
+        },
+    };
+}

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

@@ -0,0 +1,45 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Scheduler (Wave 4, wo701) — pure capacity-matching helpers, no side
+ * effects. The hard departure from WrfcController's pairwise
+ * engineer<->reviewer binding (startReview:883/startFix:1042): each tick,
+ * for every phase in ordinal order, free capacity slots (capacity minus
+ * in-flight) are filled from whichever waiting items are queued for that
+ * phase — an item advances the instant ITS gate passes, claimed by
+ * whatever slot happens to be free, never bound to a specific sibling item.
+ */
+import type { Phase, WorkItem, Workstream } from './types.js';
+export declare function sortedPhases(workstream: Workstream): Phase[];
+export declare function firstPhase(workstream: Workstream): Phase | undefined;
+/**
+ * The next phase in ORDINARY forward progression. Deliberately skips
+ * 'fix'-kind phases: a dynamically-inserted fix phase sits at an ordinal
+ * after its review (see engine.ts findOrInsertFixPhase) but is reachable
+ * ONLY via the explicit review-failure re-route, never as "what comes next"
+ * for an item whose review already passed — otherwise a later item that
+ * never needed fixing would wrongly detour through it.
+ */
+export declare function nextPhaseAfter(workstream: Workstream, ordinal: number): Phase | undefined;
+export declare function phaseById(workstream: Workstream, phaseId: string): Phase | undefined;
+/** The nearest preceding review-kind phase — the return target after a dynamically-inserted fix phase's gate passes. Purely structural (survives serialization with zero extra bookkeeping). */
+export declare function reviewPhaseBefore(workstream: Workstream, phase: Phase): Phase | undefined;
+export interface PhaseClaim {
+    readonly item: WorkItem;
+    readonly phase: Phase;
+}
+/**
+ * Which (item, phase) pairs have free capacity to claim RIGHT NOW. Pure —
+ * no side effects, no budget check (the caller applies budget.checkBudget
+ * before actually claiming, since budget is a *decision*, not a capacity
+ * fact this function should own).
+ *
+ * 'blocked-budget' items are deliberately included in the waiting set, not
+ * just 'pending'/'awaiting-capacity': a budget block is a recoverable
+ * decision (see BudgetCeiling/WorkItemState docs, types.ts), never a
+ * capacity fact, so a previously-blocked item must be reconsidered on every
+ * tick the instant a slot is free — the caller's budget.checkBudget call
+ * re-decides it fresh each time, honestly re-blocking it if the ceiling
+ * still refuses.
+ */
+export declare function computeClaims(workstream: Workstream): PhaseClaim[];
+//# sourceMappingURL=scheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/scheduler.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE9D,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,KAAK,EAAE,CAE5D;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEzF;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEpF;AAED,gMAAgM;AAChM,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAEzF;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,EAAE,CAiBlE"}

package/dist/platform/orchestration/scheduler.js

@@ -0,0 +1,57 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export function sortedPhases(workstream) {
+    return [...workstream.phases].sort((a, b) => a.ordinal - b.ordinal);
+}
+export function firstPhase(workstream) {
+    return sortedPhases(workstream)[0];
+}
+/**
+ * The next phase in ORDINARY forward progression. Deliberately skips
+ * 'fix'-kind phases: a dynamically-inserted fix phase sits at an ordinal
+ * after its review (see engine.ts findOrInsertFixPhase) but is reachable
+ * ONLY via the explicit review-failure re-route, never as "what comes next"
+ * for an item whose review already passed — otherwise a later item that
+ * never needed fixing would wrongly detour through it.
+ */
+export function nextPhaseAfter(workstream, ordinal) {
+    return sortedPhases(workstream).find((p) => p.ordinal > ordinal && p.kind !== 'fix');
+}
+export function phaseById(workstream, phaseId) {
+    return workstream.phases.find((p) => p.id === phaseId);
+}
+/** The nearest preceding review-kind phase — the return target after a dynamically-inserted fix phase's gate passes. Purely structural (survives serialization with zero extra bookkeeping). */
+export function reviewPhaseBefore(workstream, phase) {
+    return sortedPhases(workstream).filter((p) => p.ordinal < phase.ordinal && p.kind === 'review').pop();
+}
+/**
+ * Which (item, phase) pairs have free capacity to claim RIGHT NOW. Pure —
+ * no side effects, no budget check (the caller applies budget.checkBudget
+ * before actually claiming, since budget is a *decision*, not a capacity
+ * fact this function should own).
+ *
+ * 'blocked-budget' items are deliberately included in the waiting set, not
+ * just 'pending'/'awaiting-capacity': a budget block is a recoverable
+ * decision (see BudgetCeiling/WorkItemState docs, types.ts), never a
+ * capacity fact, so a previously-blocked item must be reconsidered on every
+ * tick the instant a slot is free — the caller's budget.checkBudget call
+ * re-decides it fresh each time, honestly re-blocking it if the ceiling
+ * still refuses.
+ */
+export function computeClaims(workstream) {
+    const claims = [];
+    for (const phase of sortedPhases(workstream)) {
+        const inFlight = workstream.items.filter((item) => item.currentPhaseId === phase.id && item.state === 'in-phase').length;
+        let free = phase.capacity - inFlight;
+        if (free <= 0)
+            continue;
+        const waiting = workstream.items.filter((item) => item.currentPhaseId === phase.id
+            && (item.state === 'pending' || item.state === 'awaiting-capacity' || item.state === 'blocked-budget'));
+        for (const item of waiting) {
+            if (free <= 0)
+                break;
+            claims.push({ item, phase });
+            free -= 1;
+        }
+    }
+    return claims;
+}