onto-mcp 0.3.2 → 0.4.0

package/dist/core-runtime/cli/review-invoke-resolver-caching.test.js

@@ -1,201 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { tryResolveTopologyForHandoff, tryTopologyDerivedExecutor, } from "./review-invoke.js";
-// ---------------------------------------------------------------------------
-// P9.3-m1 Resolver caching invariants (2026-04-21):
-//
-// `runReviewInvokeCli` resolves `resolveExecutionTopology` exactly once
-// per invocation and threads the result as `cached` to 3 downstream
-// consumers. This file protects the cache plumbing from future
-// regressions — a caller that accidentally drops the `cached` argument
-// (reverting to the 3x resolver-call pattern) would re-emit the full
-// `[topology]` STDERR trace, which these tests assert does NOT happen.
-//
-// The `[topology] signals:` line is the most stable counter because
-// `resolveExecutionTopology` emits it exactly once at the very start of
-// each invocation (see execution-topology-resolver.ts:413). When the
-// helpers honour `cached`, they skip the resolver entirely and this
-// line MUST NOT appear.
-// ---------------------------------------------------------------------------
-const FAKE_HOME = "/tmp/fake-onto-home";
-const CACHED_LITELLM_TOPOLOGY = {
-    id: "cc-teams-litellm-sessions",
-    teamlead_location: "claude-teamcreate",
-    lens_spawn_mechanism: "litellm-http",
-    max_concurrent_lenses: 3,
-    transport_rank: "S2",
-    deliberation_channel: "synthesizer-only",
-    plan_trace: ["cached-by-runReviewInvokeCli"],
-};
-const CACHED_CC_MAIN_TOPOLOGY = {
-    id: "cc-main-agent-subagent",
-    teamlead_location: "onto-main",
-    lens_spawn_mechanism: "claude-agent-tool",
-    max_concurrent_lenses: 3,
-    transport_rank: "S0",
-    deliberation_channel: "synthesizer-only",
-    plan_trace: ["cached-by-runReviewInvokeCli"],
-};
-describe("tryResolveTopologyForHandoff — cached topology bypass", () => {
-    const originalEnv = { ...process.env };
-    let stderrSpy;
-    beforeEach(() => {
-        delete process.env.CLAUDECODE;
-        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-    });
-    afterEach(() => {
-        stderrSpy.mockRestore();
-        for (const k of Object.keys(process.env)) {
-            if (!(k in originalEnv))
-                delete process.env[k];
-        }
-        for (const [k, v] of Object.entries(originalEnv)) {
-            process.env[k] = v;
-        }
-    });
-    function signalsTraceLines() {
-        return stderrSpy.mock.calls
-            .map((c) => String(c[0]))
-            .filter((l) => l.startsWith("[topology] signals:"));
-    }
-    it("cached=ExecutionTopology → descriptor returned without re-running resolver", () => {
-        const descriptor = tryResolveTopologyForHandoff({}, CACHED_LITELLM_TOPOLOGY);
-        expect(descriptor).not.toBeNull();
-        expect(descriptor.id).toBe("cc-teams-litellm-sessions");
-        expect(descriptor.teamlead_location).toBe("claude-teamcreate");
-        expect(signalsTraceLines()).toHaveLength(0);
-    });
-    it("cached=null → returns null without re-running resolver", () => {
-        const descriptor = tryResolveTopologyForHandoff({}, null);
-        expect(descriptor).toBeNull();
-        expect(signalsTraceLines()).toHaveLength(0);
-    });
-    it("cached=undefined → legacy behaviour (resolver runs, emits signals)", () => {
-        // Two-argument call path preserved for test-harness compatibility;
-        // this branch is what existing tests exercise.
-        tryResolveTopologyForHandoff({});
-        expect(signalsTraceLines()).toHaveLength(1);
-    });
-});
-describe("tryTopologyDerivedExecutor — cached topology bypass", () => {
-    const originalEnv = { ...process.env };
-    let stderrSpy;
-    beforeEach(() => {
-        delete process.env.CLAUDECODE;
-        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-    });
-    afterEach(() => {
-        stderrSpy.mockRestore();
-        for (const k of Object.keys(process.env)) {
-            if (!(k in originalEnv))
-                delete process.env[k];
-        }
-        for (const [k, v] of Object.entries(originalEnv)) {
-            process.env[k] = v;
-        }
-    });
-    function signalsTraceLines() {
-        return stderrSpy.mock.calls
-            .map((c) => String(c[0]))
-            .filter((l) => l.startsWith("[topology] signals:"));
-    }
-    it("cached=ExecutionTopology (binary-backed) → executor returned without re-running resolver", () => {
-        const result = tryTopologyDerivedExecutor({ llm_base_url: "http://localhost:4000" }, FAKE_HOME, CACHED_LITELLM_TOPOLOGY);
-        expect(result).not.toBeNull();
-        expect(result.bin).toBe("node");
-        expect(result.args[0]).toContain("inline-http-review-unit-executor.js");
-        expect(signalsTraceLines()).toHaveLength(0);
-    });
-    it("cached=ExecutionTopology (no standalone binary) → null without re-running resolver", () => {
-        const result = tryTopologyDerivedExecutor({}, FAKE_HOME, CACHED_CC_MAIN_TOPOLOGY);
-        expect(result).toBeNull();
-        expect(signalsTraceLines()).toHaveLength(0);
-    });
-    it("cached=null → null without re-running resolver", () => {
-        const result = tryTopologyDerivedExecutor({}, FAKE_HOME, null);
-        expect(result).toBeNull();
-        expect(signalsTraceLines()).toHaveLength(0);
-    });
-    it("cached=undefined → legacy behaviour (resolver runs, emits signals)", () => {
-        process.env.CLAUDECODE = "1";
-        tryTopologyDerivedExecutor({}, FAKE_HOME);
-        expect(signalsTraceLines()).toHaveLength(1);
-    });
-});
-// ---------------------------------------------------------------------------
-// Integration-layer invariant: exercise the 3-consumer contract that
-// `runReviewInvokeCli` depends on. The stderr-based tests above prove
-// the helper-level contract; these tests prove the full-dispatch
-// consumer sequence (tryResolveTopologyForHandoff + tryTopologyDerivedExecutor
-// twice — the shape invoked by resolveExecutorConfig for default +
-// synthesize) adds up to ZERO resolver invocations when the cache is
-// threaded. If a future refactor drops the `cached` argument from any
-// consumer, the signals-line count will jump from 0 to 1-or-more and
-// this test will fail — catching the very regression class MINOR-1 of
-// the P9.3-m1 review flagged.
-// ---------------------------------------------------------------------------
-describe("runReviewInvokeCli full-dispatch consumer sequence — invariant", () => {
-    const originalEnv = { ...process.env };
-    let stderrSpy;
-    beforeEach(() => {
-        delete process.env.CLAUDECODE;
-        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-    });
-    afterEach(() => {
-        stderrSpy.mockRestore();
-        for (const k of Object.keys(process.env)) {
-            if (!(k in originalEnv))
-                delete process.env[k];
-        }
-        for (const [k, v] of Object.entries(originalEnv)) {
-            process.env[k] = v;
-        }
-    });
-    function signalsTraceCount() {
-        return stderrSpy.mock.calls
-            .map((c) => String(c[0]))
-            .filter((l) => l.startsWith("[topology] signals:")).length;
-    }
-    it("3 consumers with shared cachedTopology → resolver runs 0 times", () => {
-        // Simulate the runReviewInvokeCli full-dispatch sequence:
-        // 1. runReviewInvokeCli resolves once at the top (we fabricate the
-        //    result here as `cachedTopology` — NOT included in the spy count).
-        // 2. tryResolveTopologyForHandoff(config, cachedTopology) — coordinator_start
-        //    path would have called this but it returns earlier; included here
-        //    for completeness of the 3-consumer contract.
-        // 3. tryTopologyDerivedExecutor ×2 (default + synthesize via
-        //    resolveExecutorConfig).
-        const cachedTopology = CACHED_LITELLM_TOPOLOGY;
-        const config = { llm_base_url: "http://localhost:4000" };
-        tryResolveTopologyForHandoff(config, cachedTopology);
-        tryTopologyDerivedExecutor(config, FAKE_HOME, cachedTopology);
-        tryTopologyDerivedExecutor(config, FAKE_HOME, cachedTopology);
-        // ZERO resolver calls: cache bypassed all 3 consumers.
-        expect(signalsTraceCount()).toBe(0);
-    });
-    it("regression probe: 3 consumers with cached=undefined → resolver runs 3 times", () => {
-        // This is the PRE-fix behaviour. If someone accidentally reverts the
-        // caching (drops the `cached` argument from all 3 consumers), the
-        // count would be 3 — proving the test catches the exact regression.
-        process.env.CLAUDECODE = "1";
-        const config = { llm_base_url: "http://localhost:4000" };
-        tryResolveTopologyForHandoff(config);
-        tryTopologyDerivedExecutor(config, FAKE_HOME);
-        tryTopologyDerivedExecutor(config, FAKE_HOME);
-        expect(signalsTraceCount()).toBe(3);
-    });
-    it("3 consumers with cachedTopology=null → resolver runs 0 times, all return null", () => {
-        // `null` propagation: all 3 consumers see cached=null and short-circuit
-        // without invoking the resolver.
-        const config = { llm_base_url: "http://localhost:4000" };
-        const descriptor = tryResolveTopologyForHandoff(config, null);
-        const exec1 = tryTopologyDerivedExecutor(config, FAKE_HOME, null);
-        const exec2 = tryTopologyDerivedExecutor(config, FAKE_HOME, null);
-        expect(descriptor).toBeNull();
-        expect(exec1).toBeNull();
-        expect(exec2).toBeNull();
-        expect(signalsTraceCount()).toBe(0);
-    });
-});

package/dist/core-runtime/cli/review-invoke-topology-dispatch.test.js

@@ -1,192 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { tryTopologyDerivedExecutor } from "./review-invoke.js";
-// ---------------------------------------------------------------------------
-// Topology-derived executor dispatch invariants (P9.3, 2026-04-21):
-//
-// (1) Dispatch is always attempted — the former opt-in gate
-//     (`execution_topology_priority` pre-P9.1, `config.review` presence
-//     in P9.2) is removed. Resolver's universal `main_native` degrade
-//     guarantees a viable topology whenever a host is reachable.
-// (2) Resolved topology whose lens_spawn_mechanism has a standalone
-//     binary → returns the mapped ReviewUnitExecutorConfig (caller
-//     appends subagent/model args as usual).
-// (3) Resolved topology whose mechanism has NO standalone binary
-//     (claude-agent-tool, claude-teamcreate-member, codex-nested's
-//     teamlead location) → returns null (fall through to coordinator
-//     or dedicated orchestrators).
-// (4) No reachable host (resolver returns `no_host`) → returns null.
-// (5) `[plan:executor]` STDERR line emitted on successful topology
-//     derivation, so operators can see topology → binary mapping.
-// ---------------------------------------------------------------------------
-const FAKE_HOME = "/tmp/fake-onto-home";
-function withInjectedSignals(config, overrides = {}) {
-    // `tryTopologyDerivedExecutor` reads env implicitly via
-    // resolveExecutionTopology; most tests need CLAUDECODE=1 to satisfy
-    // the cc-main-* requirement. Tests manipulate process.env directly.
-    return config;
-}
-describe("tryTopologyDerivedExecutor — null paths (fall through)", () => {
-    const originalEnv = { ...process.env };
-    beforeEach(() => {
-        delete process.env.CLAUDECODE;
-        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-    });
-    afterEach(() => {
-        for (const k of Object.keys(process.env)) {
-            if (!(k in originalEnv))
-                delete process.env[k];
-        }
-        for (const [k, v] of Object.entries(originalEnv)) {
-            process.env[k] = v;
-        }
-    });
-    it("no config.review block + no host → null (resolver returns no_host)", () => {
-        // P9.3 (2026-04-21): dispatch attempts axis-first resolution for
-        // every review invocation. Without CLAUDECODE / codex signals the
-        // resolver's main_native degrade cannot map → no_host → null.
-        const result = tryTopologyDerivedExecutor({}, FAKE_HOME);
-        expect(result).toBeNull();
-    });
-    it("no config.review block + CC host → null (cc-main-agent-subagent has no standalone binary)", () => {
-        // P9.3 invariant: even without a review block the resolver maps
-        // main_native → cc-main-agent-subagent under CLAUDECODE=1. That
-        // topology's mechanism is claude-agent-tool which has no
-        // standalone binary, so dispatch falls through to coordinator.
-        process.env.CLAUDECODE = "1";
-        const result = tryTopologyDerivedExecutor({}, FAKE_HOME);
-        expect(result).toBeNull();
-    });
-    it("missing ontoHome → null (required to resolve executor path)", () => {
-        process.env.CLAUDECODE = "1";
-        const result = tryTopologyDerivedExecutor({ review: { subagent: { provider: "main-native" } } }, undefined);
-        expect(result).toBeNull();
-    });
-    it("review axis resolves to claude-agent-tool (cc-main-agent-subagent) → null (coordinator handoff is the seat)", () => {
-        process.env.CLAUDECODE = "1";
-        const result = tryTopologyDerivedExecutor({ review: { subagent: { provider: "main-native" } } }, FAKE_HOME);
-        expect(result).toBeNull();
-    });
-    it("review axis resolves but no host signals → null (no_host case)", () => {
-        // CLAUDECODE unset, no codex signals. Axis block derives to
-        // main_native shape but the mapping is unreachable — no_host.
-        const result = tryTopologyDerivedExecutor({ review: { subagent: { provider: "main-native" } } }, FAKE_HOME);
-        expect(result).toBeNull();
-    });
-    it("review axis resolves to codex-nested-subprocess → null (PR-H dispatch branch is the seat)", () => {
-        // Nested codex requires only codexAvailable; but the mapping module
-        // rejects it (its teamlead is codex-subprocess, not a per-lens binary).
-        // Without CLAUDECODE and with no real codex binary on the test
-        // machine's PATH the resolver will return no_host; that's fine —
-        // the test asserts null regardless, which is correct PR-F behaviour
-        // for nested topology anyway.
-        const result = tryTopologyDerivedExecutor({
-            review: {
-                teamlead: { model: { provider: "codex", model_id: "gpt-5.4" } },
-                subagent: { provider: "codex", model_id: "gpt-5.4" },
-            },
-        }, FAKE_HOME);
-        expect(result).toBeNull();
-    });
-});
-describe("tryTopologyDerivedExecutor — successful derivation", () => {
-    const originalEnv = { ...process.env };
-    let stderrSpy;
-    beforeEach(() => {
-        delete process.env.CLAUDECODE;
-        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-    });
-    afterEach(() => {
-        stderrSpy.mockRestore();
-        for (const k of Object.keys(process.env)) {
-            if (!(k in originalEnv))
-                delete process.env[k];
-        }
-        for (const [k, v] of Object.entries(originalEnv)) {
-            process.env[k] = v;
-        }
-    });
-    function topologyLogLines() {
-        return stderrSpy.mock.calls
-            .map((c) => String(c[0]))
-            .filter((l) => l.startsWith("[plan:executor]"));
-    }
-    it("cc-teams-litellm-sessions axis block → litellm executor binary", () => {
-        process.env.CLAUDECODE = "1";
-        // P9.2 (2026-04-21): topology is selected exclusively through the
-        // `config.review` axis block — legacy `execution_topology_priority`
-        // field was removed from OntoConfig.
-        const axisConfig = {
-            review: {
-                subagent: { provider: "litellm", model_id: "gpt-4o" },
-            },
-            llm_base_url: "http://localhost:4000",
-        };
-        // Without experimental flag, teams shape cannot activate → axis-first
-        // fails → degrade to main_native → cc-main-agent-subagent (no
-        // standalone binary) → null.
-        const result = tryTopologyDerivedExecutor(withInjectedSignals(axisConfig), FAKE_HOME);
-        expect(result).toBeNull();
-        process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
-        const result2 = tryTopologyDerivedExecutor(withInjectedSignals(axisConfig), FAKE_HOME);
-        expect(result2).not.toBeNull();
-        expect(result2.bin).toBe("node");
-        expect(result2.args[0]).toContain("inline-http-review-unit-executor.js");
-        expect(result2.args[0]).toContain(FAKE_HOME);
-    });
-    it("successful derivation emits [plan:executor] STDERR", () => {
-        process.env.CLAUDECODE = "1";
-        process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
-        tryTopologyDerivedExecutor({
-            review: {
-                subagent: { provider: "litellm", model_id: "gpt-4o" },
-            },
-            llm_base_url: "http://localhost:4000",
-        }, FAKE_HOME);
-        const lines = topologyLogLines();
-        expect(lines.length).toBe(1);
-        expect(lines[0]).toContain("topology=cc-teams-litellm-sessions");
-        expect(lines[0]).toContain("bin=node");
-        expect(lines[0]).toContain("inline-http-review-unit-executor.js");
-    });
-    it("no [plan:executor] line when topology falls through", () => {
-        // cc-main-agent-subagent has no standalone binary → fall through,
-        // so no [plan:executor] line should be emitted for this derivation.
-        // The resolver picks cc-main-agent-subagent via the axis block.
-        process.env.CLAUDECODE = "1";
-        tryTopologyDerivedExecutor({ review: { subagent: { provider: "main-native" } } }, FAKE_HOME);
-        expect(topologyLogLines()).toHaveLength(0);
-    });
-});
-describe("tryTopologyDerivedExecutor — axis-first decides (P9.2)", () => {
-    const originalEnv = { ...process.env };
-    beforeEach(() => {
-        delete process.env.CLAUDECODE;
-        delete process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
-        vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-    });
-    afterEach(() => {
-        vi.restoreAllMocks();
-        for (const k of Object.keys(process.env)) {
-            if (!(k in originalEnv))
-                delete process.env[k];
-        }
-        for (const [k, v] of Object.entries(originalEnv)) {
-            process.env[k] = v;
-        }
-    });
-    it("review axis selects the binary-backed topology when declared", () => {
-        process.env.CLAUDECODE = "1";
-        process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
-        // Axis block declares subagent=litellm → shape=main-teams_foreign →
-        // TopologyId=cc-teams-litellm-sessions (standalone binary).
-        const result = tryTopologyDerivedExecutor({
-            review: {
-                subagent: { provider: "litellm", model_id: "gpt-4o" },
-            },
-            llm_base_url: "http://localhost:4000",
-        }, FAKE_HOME);
-        expect(result).not.toBeNull();
-        expect(result.args[0]).toContain("inline-http-review-unit-executor.js");
-    });
-});

package/dist/core-runtime/cli/session-root-guard.js

@@ -1,168 +0,0 @@
-/**
- * Session Root Guard — DD-8 (Step 11a).
- *
- * Design authority:
- *   - learn-phase3-design-v9.md DD-8 (.layout-version.yaml + runtime gate)
- *   - learn-phase3-design-v5.md DD-8 (UF-SYN-05/06 — marker rename + version gate)
- *   - learn-phase3-design-v4.md DD-8 (case taxonomy: new user / legacy / mixed)
- *
- * Responsibility:
- *   - Inspect `<projectRoot>/.onto/.layout-version.yaml` and decide whether
- *     the session layout is ready for Phase 3 commands (promote /
- *     reclassify-insights / migrate-session-roots).
- *   - Detect legacy session directories that match the pre-v3 pattern
- *     (`.onto/sessions/{id}/` directly, no `review/` subdir).
- *   - Surface 4 cases with deterministic actions:
- *       1. New user (no marker, no legacy)        → write marker, allow
- *       2. Legacy + no marker                     → MigrationRequiredError
- *       3. Marker present + legacy still exists   → warn but allow (operator
- *                                                    should re-run migration)
- *       4. Marker present + no legacy             → allow
- *   - Reject the marker when its layout_version doesn't match SUPPORTED.
- *
- * Modes:
- *   - "enforce" (default): write marker on first run, throw on legacy.
- *   - "inspect": pure read, no I/O writes, no throw. Used by diagnostics
- *     that should not trigger migration as a side effect.
- *
- * Why a separate module:
- *   - Phase 3 commands (promote, reclassify-insights) call this from src/cli.ts
- *     before doing anything else, so the gate is the first thing they hit.
- *   - The migrate-session-roots command also uses inspectMigrationStatus()
- *     to compute what would be migrated.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { REGISTRY } from "../learning/shared/artifact-registry.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-export const SUPPORTED_LAYOUT_VERSION = "v3";
-export const LAYOUT_MARKER_FILENAME = ".layout-version.yaml";
-const KNOWN_SESSION_SUBDIRS = ["review", "promote", "reclassify-insights"];
-/** Legacy session id pattern: YYYYMMDD-{6+ hex}. */
-const LEGACY_SESSION_PATTERN = /^\d{8}-[a-f0-9]{6,}$/;
-// ---------------------------------------------------------------------------
-// Path helpers
-// ---------------------------------------------------------------------------
-export function getLayoutMarkerPath(projectRoot) {
-    return path.join(projectRoot, ".onto", LAYOUT_MARKER_FILENAME);
-}
-export function getSessionsDir(projectRoot) {
-    return path.join(projectRoot, ".onto", "sessions");
-}
-/**
- * Pure read of layout marker + legacy directory enumeration.
- *
- * Performs no I/O writes and never throws on missing files. The caller
- * decides what to do with the resulting status.
- */
-export function inspectMigrationStatus(projectRoot) {
-    const markerPath = getLayoutMarkerPath(projectRoot);
-    const status = {
-        marker_present: false,
-        marker_path: markerPath,
-        marker_compatible: false,
-        marker_layout_version: null,
-        legacy_session_count: 0,
-        legacy_session_ids: [],
-    };
-    if (fs.existsSync(markerPath)) {
-        status.marker_present = true;
-        try {
-            const marker = REGISTRY.loadFromFile("layout_version", markerPath);
-            status.marker_layout_version = marker.layout_version;
-            status.marker_compatible = marker.layout_version === SUPPORTED_LAYOUT_VERSION;
-        }
-        catch {
-            // Marker file exists but is malformed. Treat as incompatible.
-            status.marker_compatible = false;
-        }
-    }
-    const sessionsDir = getSessionsDir(projectRoot);
-    if (fs.existsSync(sessionsDir)) {
-        const entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
-        const legacy = entries.filter((e) => e.isDirectory() &&
-            !KNOWN_SESSION_SUBDIRS.includes(e.name) &&
-            LEGACY_SESSION_PATTERN.test(e.name));
-        status.legacy_session_count = legacy.length;
-        status.legacy_session_ids = legacy.map((e) => e.name).sort();
-    }
-    return status;
-}
-// ---------------------------------------------------------------------------
-// Marker writer
-// ---------------------------------------------------------------------------
-export function writeLayoutMarker(projectRoot) {
-    const markerPath = getLayoutMarkerPath(projectRoot);
-    fs.mkdirSync(path.dirname(markerPath), { recursive: true });
-    const marker = {
-        schema_version: "1",
-        layout_version: SUPPORTED_LAYOUT_VERSION,
-        written_at: new Date().toISOString(),
-    };
-    REGISTRY.saveToFile("layout_version", markerPath, marker);
-}
-// ---------------------------------------------------------------------------
-// Errors
-// ---------------------------------------------------------------------------
-export class MigrationRequiredError extends Error {
-    status;
-    constructor(message, status) {
-        super(message);
-        this.status = status;
-        this.name = "MigrationRequiredError";
-    }
-}
-export class IncompatibleLayoutError extends Error {
-    status;
-    constructor(message, status) {
-        super(message);
-        this.status = status;
-        this.name = "IncompatibleLayoutError";
-    }
-}
-/**
- * Phase 3 command entry guard. Call from src/cli.ts BEFORE any promote /
- * reclassify-insights / promote --apply / migrate-session-roots subcommand.
- *
- * Returns the inspected status so callers can log or branch on it.
- *
- * Throws:
- *   - `MigrationRequiredError` when legacy sessions exist without a marker
- *     (case 2). The operator must run `onto migrate-session-roots`.
- *   - `IncompatibleLayoutError` when the marker exists but its
- *     layout_version is not the supported one (forward-compat guard).
- */
-export function ensureSessionRootsMigrated(projectRoot, mode = "enforce") {
-    const status = inspectMigrationStatus(projectRoot);
-    if (mode === "inspect")
-        return status;
-    // Case 1: new user — write marker and allow.
-    if (!status.marker_present && status.legacy_session_count === 0) {
-        writeLayoutMarker(projectRoot);
-        return inspectMigrationStatus(projectRoot);
-    }
-    // Case 2: legacy + no marker — hard fail.
-    if (!status.marker_present && status.legacy_session_count > 0) {
-        const sample = status.legacy_session_ids.slice(0, 5).join(", ");
-        const more = status.legacy_session_count > 5
-            ? ` ... and ${status.legacy_session_count - 5} more`
-            : "";
-        throw new MigrationRequiredError(`Legacy session roots detected (${status.legacy_session_count} session(s)). ` +
-            `Run 'onto migrate-session-roots' before continuing.\n` +
-            `Affected: ${sample}${more}`, status);
-    }
-    // Case 3: marker present + legacy still exists — warn (re-run migration).
-    if (status.marker_present && status.legacy_session_count > 0) {
-        process.stderr.write(`[onto] warning: ${status.legacy_session_count} legacy session(s) found ` +
-            `despite layout marker. Re-run 'onto migrate-session-roots' to clean up.\n`);
-    }
-    // Case 4: marker present + no legacy → check version compat.
-    if (status.marker_present && !status.marker_compatible) {
-        throw new IncompatibleLayoutError(`Layout marker version "${status.marker_layout_version}" is not ` +
-            `supported (expected "${SUPPORTED_LAYOUT_VERSION}"). ` +
-            `Upgrade Phase 3 tooling or restore a compatible marker.`, status);
-    }
-    return status;
-}