@delegance/claude-autopilot 5.5.2 → 7.2.0

package/dist/src/core/run-state/lock.js

@@ -0,0 +1,206 @@
+// src/core/run-state/lock.ts
+//
+// Per-run advisory lock. Wraps `proper-lockfile` with a sidecar metadata file
+// (`.lock-meta.json`) that records WHICH writer (pid + hostHash) owns the
+// lock, so a second invocation can either fail-fast with a precise error or
+// take over with `forceTakeover()`.
+//
+// proper-lockfile itself only stores `mtime`; it doesn't track owner identity,
+// so we maintain it ourselves alongside the lock.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Persistence protocol — Per-run
+// advisory lock", "Single-writer invariant".
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import * as os from 'node:os';
+import lockfile from 'proper-lockfile';
+import { GuardrailError } from "../errors.js";
+/** File proper-lockfile guards. We pin a specific name so relocation /
+ *  copy of the run dir doesn't accidentally inherit a stale lock from
+ *  another path. */
+const LOCK_TARGET = '.lock';
+/** Sidecar JSON that records the current owner. Kept separate from the
+ *  proper-lockfile-managed `.lock` directory so we never race the
+ *  acquisition primitive. */
+const LOCK_META = '.lock-meta.json';
+/** Default stale timeout. After this many ms with no `update`, the lock is
+ *  considered stale and another writer may acquire. Matches proper-lockfile
+ *  default (10s). */
+const DEFAULT_STALE_MS = 10_000;
+/** Hash the hostname so we never persist raw machine identity. */
+export function makeWriterId() {
+    return {
+        pid: process.pid,
+        hostHash: crypto.createHash('sha256').update(os.hostname()).digest('hex').slice(0, 16),
+    };
+}
+function lockTargetPath(runDir) {
+    return path.join(runDir, LOCK_TARGET);
+}
+function metaPath(runDir) {
+    return path.join(runDir, LOCK_META);
+}
+function writeMeta(runDir, meta) {
+    fs.writeFileSync(metaPath(runDir), JSON.stringify(meta, null, 2), 'utf8');
+}
+function readMeta(runDir) {
+    const p = metaPath(runDir);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function deleteMeta(runDir) {
+    try {
+        fs.unlinkSync(metaPath(runDir));
+    }
+    catch { /* idempotent */ }
+}
+/** True iff a process with the given PID is alive on THIS host. We refuse
+ *  to make a determination for off-host PIDs (different hostHash) and treat
+ *  them as alive — better to bail with `lock_held` than to silently steal a
+ *  lock owned by another machine sharing a network filesystem. */
+export function isPidAlive(writerId) {
+    if (!writerId)
+        return false;
+    const me = makeWriterId();
+    if (writerId.hostHash !== me.hostHash) {
+        // Different host. We can't probe — assume alive (safer default).
+        return true;
+    }
+    if (writerId.pid <= 0)
+        return false;
+    if (writerId.pid === me.pid)
+        return true;
+    try {
+        // POSIX trick: kill(pid, 0) checks existence without delivering a signal.
+        process.kill(writerId.pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process → not alive. EPERM = exists but we can't
+        // signal it → still alive. Anything else, default to alive.
+        const code = err.code;
+        if (code === 'ESRCH')
+            return false;
+        return true;
+    }
+}
+/** Acquire the per-run advisory lock. Throws GuardrailError(lock_held) if
+ *  another writer owns it. The caller is expected to hold the returned
+ *  handle for the duration of the run and call `release()` on shutdown. */
+export async function acquireRunLock(runDir, opts = {}) {
+    fs.mkdirSync(runDir, { recursive: true });
+    const target = lockTargetPath(runDir);
+    if (!fs.existsSync(target))
+        fs.writeFileSync(target, '');
+    const writerId = opts.writerId ?? makeWriterId();
+    const stale = opts.stale ?? DEFAULT_STALE_MS;
+    let release;
+    try {
+        release = await lockfile.lock(target, {
+            stale,
+            retries: opts.retries ?? 0,
+        });
+    }
+    catch (err) {
+        // Fail-closed with a typed error so callers can build a good message.
+        const owner = readMeta(runDir);
+        throw new GuardrailError(`run lock held: cannot acquire ${target}: ${err.message}`, {
+            code: 'lock_held',
+            provider: 'run-state',
+            details: {
+                runDir,
+                owner: owner?.writerId ?? null,
+                acquiredAt: owner?.acquiredAt ?? null,
+            },
+        });
+    }
+    // Write our metadata. We do this AFTER acquisition so a partial-create
+    // (if we crash here) leaves us as the orphaned owner rather than a phantom.
+    writeMeta(runDir, { writerId, acquiredAt: new Date().toISOString() });
+    let released = false;
+    return {
+        writerId,
+        release: async () => {
+            if (released)
+                return;
+            released = true;
+            // Always try to clear meta even if release throws; the lockfile is
+            // the authoritative gate, and a stale meta with no .lock around
+            // would be merely cosmetic.
+            try {
+                await release();
+            }
+            finally {
+                deleteMeta(runDir);
+            }
+        },
+    };
+}
+/** Update the lastSeq field in the lock metadata. Best-effort; never throws.
+ *  The events.ndjson is the source of truth, so a missed update is harmless. */
+export function updateLockSeq(runDir, lastSeq) {
+    const meta = readMeta(runDir);
+    if (!meta)
+        return;
+    try {
+        writeMeta(runDir, { ...meta, lastSeq });
+    }
+    catch {
+        // intentionally swallowed — observability sidecar
+    }
+}
+/** Non-blocking peek at who currently owns the lock. Returns null if no
+ *  metadata is present (which generally means no live writer either, but
+ *  callers should not infer aliveness from that alone). */
+export function peekLockOwner(runDir) {
+    return readMeta(runDir);
+}
+/** Forcibly take ownership. Returns the `lock.takeover` event the caller
+ *  should append (the events log is sequenced by the appender, so this
+ *  function deliberately does NOT write to events.ndjson itself).
+ *
+ *  Throws GuardrailError(lock_held) if the previous writer is still alive
+ *  per `isPidAlive` — taking over a live writer would corrupt the log.
+ *
+ *  After this call returns, the caller should:
+ *    1. Append the returned event via `appendEvent`.
+ *    2. Call `acquireRunLock` to obtain the new handle.
+ *    Both steps run after takeover. We do not auto-acquire here so the
+ *    caller can decide on its own retry / stale-ms strategy.
+ */
+export function forceTakeover(runDir, reason) {
+    const previous = readMeta(runDir);
+    const previousWriter = previous?.writerId ?? null;
+    if (isPidAlive(previousWriter)) {
+        throw new GuardrailError(`run lock takeover refused: previous writer is still alive`, {
+            code: 'lock_held',
+            provider: 'run-state',
+            details: { runDir, previousWriter, reason },
+        });
+    }
+    // Wipe the proper-lockfile state too so the next acquire doesn't trip
+    // over a stale entry. lockfile.lock creates a directory at `${file}.lock`;
+    // we remove it so the subsequent acquire path is clean.
+    try {
+        fs.rmSync(lockTargetPath(runDir) + '.lock', { recursive: true, force: true });
+    }
+    catch {
+        // ignore — proper-lockfile will recreate on next acquire
+    }
+    deleteMeta(runDir);
+    // Caller appends this with `appendEvent`. Returning the input shape (no
+    // seq/ts/runId/schema_version/writerId yet) — the appender fills them in.
+    return {
+        event: 'lock.takeover',
+        previousWriter,
+        reason,
+    };
+}
+//# sourceMappingURL=lock.js.map

package/dist/src/core/run-state/phase-context.d.ts

@@ -0,0 +1,60 @@
+import type { ExternalRef, RunEvent, WriterId } from './types.ts';
+/** What every running phase receives. Public — re-exported from
+ *  phase-runner.ts. */
+export interface PhaseContext {
+    runDir: string;
+    runId: string;
+    phaseIdx: number;
+    writerId: WriterId;
+    /** Append a `phase.cost` event during the run. Adapters / SDK calls
+     *  should call this whenever a cost ledger entry would be written. */
+    emitCost(entry: PhaseCostInput): void;
+    /** Persist an externalRef so resume decisions can read back from the run.
+     *  Phase 6 will wire `onResume` to consult these; Phase 2 just records. */
+    emitExternalRef(ref: Omit<ExternalRef, 'observedAt'>): void;
+    /** Inject a child sub-phase. Records as a separate phase.start under the
+     *  parent. Useful for things like council (which has N inner consults).
+     *  Optional in Phase 2 — see phase-runner.ts. */
+    subPhase?<SI, SO>(child: import('./phase-runner.ts').RunPhase<SI, SO>, input: SI): Promise<SO>;
+}
+export interface PhaseCostInput {
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number;
+}
+/** Inputs the runner needs to build a context. `subPhase` is optional —
+ *  phase-runner.ts wires it when nested sub-phases are supported. */
+export interface BuildPhaseContextInput {
+    runDir: string;
+    runId: string;
+    phaseName: string;
+    phaseIdx: number;
+    writerId: WriterId;
+    /** Optional sub-phase factory; pass-through to the returned context. */
+    subPhase?: PhaseContext['subPhase'];
+}
+/** Construct a PhaseContext bound to a specific (runDir, runId, phaseIdx,
+ *  phaseName, writerId). The returned object is a thin facade over
+ *  `appendEvent`; it is a pure function in the no-IO sense — actual disk IO
+ *  happens lazily on each emit call. */
+export declare function buildPhaseContext(input: BuildPhaseContextInput): PhaseContext;
+/** Helper for phase-runner.ts: aggregate every phase.cost event for a given
+ *  phase index from an in-memory event stream. Returned in USD.
+ *
+ *  v6.2.0 — pass `'*'` (the cross-phase sentinel) to sum cost across the
+ *  whole run (every `phase.cost` event regardless of phaseIdx). The
+ *  orchestrator uses this for run-scope budget enforcement; per-phase
+ *  callers keep passing a numeric phaseIdx for the legacy semantics. */
+export declare function sumPhaseCost(events: RunEvent[], phaseIdx: number | '*'): number;
+/** Helper for phase-runner.ts: collect every external ref recorded for a
+ *  given phase index from an in-memory event stream. Dedup by kind+id. */
+export declare function collectExternalRefs(events: RunEvent[], phaseIdx: number): ExternalRef[];
+/** Helper: count successful prior attempts of a given phase (matched by
+ *  phaseIdx). Lets the runner detect "this phase already succeeded —
+ *  short-circuit on idempotent replay". */
+export declare function countPhaseSuccesses(events: RunEvent[], phaseIdx: number): number;
+/** Helper: count attempts of a given phase (number of phase.start events
+ *  for that phaseIdx). The next attempt's `attempt` field is `count + 1`. */
+export declare function countPhaseAttempts(events: RunEvent[], phaseIdx: number): number;
+//# sourceMappingURL=phase-context.d.ts.map

package/dist/src/core/run-state/phase-context.js

@@ -0,0 +1,108 @@
+// src/core/run-state/phase-context.ts
+//
+// Internal helpers used by `runPhase` to assemble the `PhaseContext` passed
+// into `RunPhase.run`. Kept separate from the public surface in
+// phase-runner.ts so tests can probe the cost / externalRef plumbing without
+// going through the full lifecycle wrapper.
+//
+// The functions here only KNOW about Phase 1's appendEvent; they don't
+// orchestrate phase.start / phase.success / phase.failed (that's
+// phase-runner.ts). They are essentially the "ctx surface" the running phase
+// uses to write costs and external references during the run.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Phase contract", "Idempotency
+// rules + external operation ledger".
+import { appendEvent } from "./events.js";
+/** Construct a PhaseContext bound to a specific (runDir, runId, phaseIdx,
+ *  phaseName, writerId). The returned object is a thin facade over
+ *  `appendEvent`; it is a pure function in the no-IO sense — actual disk IO
+ *  happens lazily on each emit call. */
+export function buildPhaseContext(input) {
+    const { runDir, runId, phaseName, phaseIdx, writerId, subPhase } = input;
+    const emitCost = (entry) => {
+        appendEvent(runDir, {
+            event: 'phase.cost',
+            phase: phaseName,
+            phaseIdx,
+            provider: entry.provider,
+            inputTokens: entry.inputTokens,
+            outputTokens: entry.outputTokens,
+            costUSD: entry.costUSD,
+        }, { writerId, runId });
+    };
+    const emitExternalRef = (ref) => {
+        const fullRef = {
+            ...ref,
+            observedAt: new Date().toISOString(),
+        };
+        appendEvent(runDir, {
+            event: 'phase.externalRef',
+            phase: phaseName,
+            phaseIdx,
+            ref: fullRef,
+        }, { writerId, runId });
+    };
+    const ctx = {
+        runDir,
+        runId,
+        phaseIdx,
+        writerId,
+        emitCost,
+        emitExternalRef,
+    };
+    if (subPhase)
+        ctx.subPhase = subPhase;
+    return ctx;
+}
+/** Helper for phase-runner.ts: aggregate every phase.cost event for a given
+ *  phase index from an in-memory event stream. Returned in USD.
+ *
+ *  v6.2.0 — pass `'*'` (the cross-phase sentinel) to sum cost across the
+ *  whole run (every `phase.cost` event regardless of phaseIdx). The
+ *  orchestrator uses this for run-scope budget enforcement; per-phase
+ *  callers keep passing a numeric phaseIdx for the legacy semantics. */
+export function sumPhaseCost(events, phaseIdx) {
+    let total = 0;
+    for (const ev of events) {
+        if (ev.event === 'phase.cost') {
+            if (phaseIdx === '*' || ev.phaseIdx === phaseIdx)
+                total += ev.costUSD;
+        }
+    }
+    return total;
+}
+/** Helper for phase-runner.ts: collect every external ref recorded for a
+ *  given phase index from an in-memory event stream. Dedup by kind+id. */
+export function collectExternalRefs(events, phaseIdx) {
+    const out = [];
+    for (const ev of events) {
+        if (ev.event === 'phase.externalRef' && ev.phaseIdx === phaseIdx) {
+            const dup = out.find(r => r.kind === ev.ref.kind && r.id === ev.ref.id);
+            if (!dup)
+                out.push(ev.ref);
+        }
+    }
+    return out;
+}
+/** Helper: count successful prior attempts of a given phase (matched by
+ *  phaseIdx). Lets the runner detect "this phase already succeeded —
+ *  short-circuit on idempotent replay". */
+export function countPhaseSuccesses(events, phaseIdx) {
+    let n = 0;
+    for (const ev of events) {
+        if (ev.event === 'phase.success' && ev.phaseIdx === phaseIdx)
+            n += 1;
+    }
+    return n;
+}
+/** Helper: count attempts of a given phase (number of phase.start events
+ *  for that phaseIdx). The next attempt's `attempt` field is `count + 1`. */
+export function countPhaseAttempts(events, phaseIdx) {
+    let n = 0;
+    for (const ev of events) {
+        if (ev.event === 'phase.start' && ev.phaseIdx === phaseIdx)
+            n += 1;
+    }
+    return n;
+}
+//# sourceMappingURL=phase-context.js.map

package/dist/src/core/run-state/phase-registry.d.ts

@@ -0,0 +1,137 @@
+import type { GuardrailConfig } from '../config/types.ts';
+import type { RunPhase } from './phase-runner.ts';
+import type { ExternalRefKind } from './types.ts';
+import { type ScanInput, type ScanOutput, type ScanCommandOptions } from '../../cli/scan.ts';
+import { type SpecInput, type SpecOutput, type SpecCommandOptions } from '../../cli/spec.ts';
+import { type PlanInput, type PlanOutput, type PlanCommandOptions } from '../../cli/plan.ts';
+import { type ImplementInput, type ImplementOutput, type ImplementCommandOptions } from '../../cli/implement.ts';
+import { type MigrateInput, type MigrateOutput, type MigrateCommandOptions } from '../../cli/migrate.ts';
+import { type PrInput, type PrOutput, type PrCommandOptions } from '../../cli/pr.ts';
+/** v6.2.0 — early-exit sentinel returned by a builder when the verb's
+ *  pre-flight (no targets, no LLM key, dry-run, …) decided it can exit
+ *  without running through the engine lifecycle. The orchestrator surfaces
+ *  this exit code straight through and short-circuits — no further phases
+ *  run, no `run.complete` event is emitted (we never created a run dir
+ *  in this branch). */
+export interface PhaseEarlyExit {
+    kind: 'early-exit';
+    exitCode: number;
+}
+/** Result of a successful builder call. Carries everything the orchestrator
+ *  needs to drive a single-phase `runPhase` invocation. */
+export interface PhaseBuilt<I, O> {
+    kind: 'phase';
+    phase: RunPhase<I, O>;
+    input: I;
+    /** Loaded `guardrail.config.yaml` (or the default). The orchestrator
+     *  uses this for `engine.enabled` resolution; per-phase wrappers also
+     *  forward it to `runPhaseWithLifecycle`. */
+    config: GuardrailConfig;
+    /** Translate the phase output back into the legacy stdout banner +
+     *  exit code path. The orchestrator calls this once per phase after
+     *  `runPhase` returns. */
+    renderResult: (output: O) => number;
+}
+/** Each registered phase defines a `build(deps)` that produces either a
+ *  `PhaseBuilt` (the happy path) or a `PhaseEarlyExit` (pre-flight bailed).
+ *  The generic `<I, O>` is preserved at the declaration site via
+ *  `satisfies PhaseRegistration<I, O>` so the registry doesn't collapse
+ *  to `PhaseRegistration<unknown, unknown>` on lookup.
+ *
+ *  v6.2.1 — `preEffectRefKinds` and `postEffectRefKinds` capture the per-
+ *  phase idempotency contract. A side-effecting phase MUST declare both:
+ *  the registry rejects any `hasSideEffects: true` registration that omits
+ *  them. The orchestrator's resume preflight reads them back to decide
+ *  skip-already-applied vs retry vs needs-human. Read-only phases (scan /
+ *  spec / plan / implement-as-of-v6.2.0) omit both — they never enter the
+ *  preflight branch.
+ *
+ *  The kinds named here MUST be subsets of `ExternalRefKind`. The registry
+ *  doesn't statically verify the phase body emits them (would require
+ *  runtime introspection of `ctx.emitExternalRef` calls); it only requires
+ *  the contract DECLARATION so the orchestrator knows what to read back. */
+export interface PhaseRegistration<I, O, Opts = unknown> {
+    build: (deps: Opts) => Promise<PhaseBuilt<I, O> | PhaseEarlyExit>;
+    /** Human-readable name shown in CLI banners + `runs show` output. */
+    displayName: string;
+    /** v6.2.1 — true iff the registered phase declares `hasSideEffects: true`
+     *  on its `RunPhase` shape. Required so the registry's `registerPhase`
+     *  helper can enforce the side-effect idempotency contract at registration
+     *  time without needing to instantiate the phase. Read-only phases
+     *  (scan / spec / plan / implement) omit this or set it to false. */
+    hasSideEffects?: boolean;
+    /** v6.2.1 — kinds the phase emits BEFORE invoking its side effect. Used
+     *  by the orchestrator's resume preflight to detect "we started this work
+     *  but didn't finish." Required when `hasSideEffects: true`. */
+    preEffectRefKinds?: readonly ExternalRefKind[];
+    /** v6.2.1 — kinds the phase emits AFTER its side effect completes
+     *  successfully. Used by the resume preflight's skip-already-applied
+     *  check (all post-effect refs `merged`/`live` ⇒ skip). Required when
+     *  `hasSideEffects: true`; may be empty when the pre-effect ref doubles
+     *  as the reconciliation ref (e.g. `pr`'s `github-pr` is recorded
+     *  pre-effect with the same id `gh` reports post-create). */
+    postEffectRefKinds?: readonly ExternalRefKind[];
+}
+/**
+ * v6.2.1 — registry-time guard that enforces the side-effect idempotency
+ * contract. Throws `Error` (caught by the registry-rejection test) when a
+ * `hasSideEffects: true` registration omits the contract arrays.
+ *
+ * Why a runtime throw and not a type-level check: the contract arrays are
+ * declarative metadata, not type-derivable from the builder signature. A
+ * structural type constraint would require duplicating each builder's
+ * shape into a wider type — overkill for a one-line registry-time check
+ * that runs once at module load.
+ */
+export declare function registerPhase<I, O, Opts = unknown>(reg: PhaseRegistration<I, O, Opts>): PhaseRegistration<I, O, Opts>;
+/** v6.2.0 — phase registry. `as const` preserves the literal name → entry
+ *  pairs; `satisfies` per-entry validates the builder signature without
+ *  collapsing the inferred shape.
+ *
+ *  Adding a new phase: extract its `build<Phase>Phase()` builder out of the
+ *  CLI verb (parity test required — see spec WARNING #4), then register
+ *  here. The orchestrator picks it up automatically.
+ *
+ *  v6.2.1 — `migrate` and `pr` enter the registry. Both are side-effecting,
+ *  so each declares its idempotency contract via `preEffectRefKinds` /
+ *  `postEffectRefKinds`. `registerPhase()` runs at module load and throws
+ *  if a side-effect entry omits the contract — that's the registry-time
+ *  enforcement gate the v6.2.1 spec requires. Read-only phases (scan /
+ *  spec / plan / implement) omit both arrays. */
+export declare const PHASE_REGISTRY: {
+    readonly scan: PhaseRegistration<ScanInput, ScanOutput, ScanCommandOptions>;
+    readonly spec: PhaseRegistration<SpecInput, SpecOutput, SpecCommandOptions>;
+    readonly plan: PhaseRegistration<PlanInput, PlanOutput, PlanCommandOptions>;
+    readonly implement: PhaseRegistration<ImplementInput, ImplementOutput, ImplementCommandOptions>;
+    readonly migrate: PhaseRegistration<MigrateInput, MigrateOutput, MigrateCommandOptions>;
+    readonly pr: PhaseRegistration<PrInput, PrOutput, PrCommandOptions>;
+};
+/** Literal union of registered phase names. Adding a new phase to
+ *  PHASE_REGISTRY automatically extends this type. */
+export type PhaseName = keyof typeof PHASE_REGISTRY;
+/** The default `--mode=full` ordering. v6.2.0 shipped scan → spec → plan →
+ *  implement; v6.2.1 extends with migrate → pr (per spec section "Phase
+ *  ordering"). After v6.2.1 ships, `claude-autopilot autopilot` runs the
+ *  full 6-phase pipeline under one runId. */
+export declare const DEFAULT_FULL_PHASES: readonly PhaseName[];
+/** Look up a phase entry by name. Returns the registration with its full
+ *  typed shape preserved (the `as const` + `satisfies` pattern means the
+ *  caller can still reach `PhaseInput<'scan'>` even though the lookup is
+ *  dynamic). Throws if the name is not registered — callers that want a
+ *  graceful fallback should validate against `PHASE_REGISTRY` keys
+ *  beforehand (see `validatePhaseNames` below). */
+export declare function getPhase<N extends PhaseName>(name: N): typeof PHASE_REGISTRY[N];
+/** All registered phase names in declaration order. Useful for `--help`
+ *  text and pre-flight `--phases` validation. */
+export declare function listPhaseNames(): readonly PhaseName[];
+/** Validate a user-supplied list of phase names against the registry.
+ *  Returns the unknown names (empty array on full match) so the caller
+ *  can produce a clear `invalid_config` error before any run dir is
+ *  created. */
+export declare function validatePhaseNames(names: readonly string[]): {
+    ok: true;
+} | {
+    ok: false;
+    unknown: string[];
+};
+//# sourceMappingURL=phase-registry.d.ts.map

package/dist/src/core/run-state/phase-registry.js

@@ -0,0 +1,162 @@
+// src/core/run-state/phase-registry.ts
+//
+// v6.2.0 — typed phase registry for the multi-phase orchestrator.
+//
+// The new top-level `claude-autopilot autopilot` verb (see src/cli/autopilot.ts)
+// drives N phases under one runId. To do that without losing per-phase I/O
+// types it needs a typed registry: `name → builder` where the builder's
+// `RunPhase<I, O>` shape is preserved through dynamic dispatch. The naive
+// `Record<PhaseName, PhaseRegistration<unknown, unknown>>` shape would
+// collapse every entry to `unknown`-on-both-sides, defeating the purpose
+// of the v6 phase contract.
+//
+// The trick (per codex NOTE #5 on the v6.2 spec):
+//   - Each entry is annotated with `satisfies PhaseRegistration<I, O>` to
+//     force-check that the builder returns the correct shape.
+//   - The wrapping `as const` preserves the literal `name → entry` pairs so
+//     `keyof typeof PHASE_REGISTRY` is the literal union, not a generic
+//     `string`.
+//   - Per-entry I/O types stay reachable through TypeScript's structural
+//     inference on the satisfies constraint.
+//
+// v6.2.0 ships with FOUR registered phases: `scan`, `spec`, `plan`,
+// `implement`. The remaining six pipeline verbs (`brainstorm`, `costs`,
+// `fix`, `review`, `validate`) are intentionally unregistered for v6.2.0:
+//
+//   - `migrate` and `pr` need explicit per-phase idempotency contracts
+//     (preflight readback + externalRef recorded BEFORE the side-effect)
+//     before they can land in a multi-phase orchestrator. v6.2.1 gates on
+//     those contracts.
+//   - `brainstorm`, `costs`, `fix`, `review`, `validate` are advisory /
+//     read-only verbs that don't fit the pipeline shape (per spec
+//     "phase ordering" section). Users who want them in a custom run
+//     should compose them via the eventual `--phases=<csv>` option once
+//     they are extracted in a follow-up release.
+//
+// Spec: docs/specs/v6.2-multi-phase-orchestrator.md "Phase registry".
+import { buildScanPhase, } from "../../cli/scan.js";
+import { buildSpecPhase, } from "../../cli/spec.js";
+import { buildPlanPhase, } from "../../cli/plan.js";
+import { buildImplementPhase, } from "../../cli/implement.js";
+import { buildMigratePhase, } from "../../cli/migrate.js";
+import { buildPrPhase, } from "../../cli/pr.js";
+/**
+ * v6.2.1 — registry-time guard that enforces the side-effect idempotency
+ * contract. Throws `Error` (caught by the registry-rejection test) when a
+ * `hasSideEffects: true` registration omits the contract arrays.
+ *
+ * Why a runtime throw and not a type-level check: the contract arrays are
+ * declarative metadata, not type-derivable from the builder signature. A
+ * structural type constraint would require duplicating each builder's
+ * shape into a wider type — overkill for a one-line registry-time check
+ * that runs once at module load.
+ */
+export function registerPhase(reg) {
+    if (reg.build === undefined) {
+        throw new Error(`registry: missing build for ${reg.displayName}`);
+    }
+    if (reg.hasSideEffects) {
+        const pre = reg.preEffectRefKinds;
+        const post = reg.postEffectRefKinds;
+        if (!pre || pre.length === 0 || !post) {
+            throw new Error(`registry: side-effect phase ${reg.displayName} missing idempotency contract — ` +
+                `declare preEffectRefKinds + postEffectRefKinds`);
+        }
+    }
+    return reg;
+}
+// ---------------------------------------------------------------------------
+// The actual registry
+// ---------------------------------------------------------------------------
+/** v6.2.0 — phase registry. `as const` preserves the literal name → entry
+ *  pairs; `satisfies` per-entry validates the builder signature without
+ *  collapsing the inferred shape.
+ *
+ *  Adding a new phase: extract its `build<Phase>Phase()` builder out of the
+ *  CLI verb (parity test required — see spec WARNING #4), then register
+ *  here. The orchestrator picks it up automatically.
+ *
+ *  v6.2.1 — `migrate` and `pr` enter the registry. Both are side-effecting,
+ *  so each declares its idempotency contract via `preEffectRefKinds` /
+ *  `postEffectRefKinds`. `registerPhase()` runs at module load and throws
+ *  if a side-effect entry omits the contract — that's the registry-time
+ *  enforcement gate the v6.2.1 spec requires. Read-only phases (scan /
+ *  spec / plan / implement) omit both arrays. */
+export const PHASE_REGISTRY = {
+    scan: registerPhase({
+        build: buildScanPhase,
+        displayName: 'Scan',
+    }),
+    spec: registerPhase({
+        build: buildSpecPhase,
+        displayName: 'Spec',
+    }),
+    plan: registerPhase({
+        build: buildPlanPhase,
+        displayName: 'Plan',
+    }),
+    implement: registerPhase({
+        build: buildImplementPhase,
+        displayName: 'Implement',
+    }),
+    migrate: registerPhase({
+        build: buildMigratePhase,
+        displayName: 'Migrate',
+        hasSideEffects: true,
+        preEffectRefKinds: ['migration-batch'],
+        postEffectRefKinds: ['migration-version'],
+    }),
+    pr: registerPhase({
+        build: buildPrPhase,
+        displayName: 'PR',
+        hasSideEffects: true,
+        // The github-pr ref is recorded pre-effect with the same id gh reports
+        // post-create — it serves both purposes. postEffectRefKinds is empty
+        // by design, not by omission. The contract guard accepts an empty
+        // array; only `undefined` triggers the rejection.
+        preEffectRefKinds: ['github-pr'],
+        postEffectRefKinds: [],
+    }),
+};
+/** The default `--mode=full` ordering. v6.2.0 shipped scan → spec → plan →
+ *  implement; v6.2.1 extends with migrate → pr (per spec section "Phase
+ *  ordering"). After v6.2.1 ships, `claude-autopilot autopilot` runs the
+ *  full 6-phase pipeline under one runId. */
+export const DEFAULT_FULL_PHASES = [
+    'scan',
+    'spec',
+    'plan',
+    'implement',
+    'migrate',
+    'pr',
+];
+/** Look up a phase entry by name. Returns the registration with its full
+ *  typed shape preserved (the `as const` + `satisfies` pattern means the
+ *  caller can still reach `PhaseInput<'scan'>` even though the lookup is
+ *  dynamic). Throws if the name is not registered — callers that want a
+ *  graceful fallback should validate against `PHASE_REGISTRY` keys
+ *  beforehand (see `validatePhaseNames` below). */
+export function getPhase(name) {
+    const entry = PHASE_REGISTRY[name];
+    if (!entry) {
+        throw new Error(`[phase-registry] unknown phase: "${name}". Registered: ${listPhaseNames().join(', ')}`);
+    }
+    return entry;
+}
+/** All registered phase names in declaration order. Useful for `--help`
+ *  text and pre-flight `--phases` validation. */
+export function listPhaseNames() {
+    return Object.keys(PHASE_REGISTRY);
+}
+/** Validate a user-supplied list of phase names against the registry.
+ *  Returns the unknown names (empty array on full match) so the caller
+ *  can produce a clear `invalid_config` error before any run dir is
+ *  created. */
+export function validatePhaseNames(names) {
+    const known = new Set(listPhaseNames());
+    const unknown = names.filter(n => !known.has(n));
+    if (unknown.length > 0)
+        return { ok: false, unknown };
+    return { ok: true };
+}
+//# sourceMappingURL=phase-registry.js.map