onto-mcp 0.3.0

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

@@ -0,0 +1,168 @@
+/**
+ * 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;
+}

package/dist/core-runtime/cli/spawn-watcher.js

@@ -0,0 +1,173 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Attempt to spawn the onto:review live watcher in a side pane / split / new tab
+ * using the most appropriate terminal multiplexer detected from the environment.
+ *
+ * Detection priority (most universal first):
+ *   1. tmux (any OS, via $TMUX env var) — splits the pane identified by
+ *      `$TMUX_PANE` so the watcher stays beside the invoking pane even if
+ *      the user has switched panes during startReviewSession.
+ *   2. iTerm2 on macOS (via $TERM_PROGRAM === 'iTerm.app') — targets the
+ *      session identified by `$ITERM_SESSION_ID`, which is inherited from
+ *      the invoking session at process start, so splits land beside the
+ *      pane that actually launched onto:review. If the env var is missing
+ *      or no matching session is found, the spawn is refused (returns
+ *      spawned: false) rather than falling back to the currently-focused
+ *      tab — a default target would land the watcher on whichever tab happens to
+ *      be frontmost at spawn time, which is the bug this path exists to
+ *      avoid.
+ *   3. Apple Terminal on macOS (via $TERM_PROGRAM === 'Apple_Terminal')
+ *      — best effort; Terminal.app lacks a stable session identifier, so
+ *      the spawn opens a new tab rather than a tab-targeted split.
+ *
+ * `sessionRoot` is required. It is passed through to the watcher script as
+ * an explicit argument, which bypasses the `.onto/review/.latest-session`
+ * pointer and therefore avoids the cross-session race that the global
+ * pointer would otherwise create under concurrent review invocations.
+ *
+ * Returns silently with `spawned: false` if no supported mechanism is found.
+ * The caller should print an explicit recovery hint in that case.
+ *
+ * This function never throws — it returns a result object instead, so the
+ * runtime continues even if the spawn fails.
+ */
+export function spawnWatcherPane(projectRoot, sessionRoot, ontoHome) {
+    // Resolution order for the watcher helper:
+    //   1. <projectRoot>/scripts/onto-review-watch.sh — co-located with the
+    //      review target (onto repo invocations, full-repo projects).
+    //   2. <ontoHome>/scripts/onto-review-watch.sh   — install-local script when
+    //      projectRoot is an isolated workspace and the watcher helper lives in
+    //      the repo home.
+    // Without the install-local script branch, any invocation with --project-root pointed at a
+    // non-repo location silently degrades to "watcher script not found"
+    // (observed 2026-04-22 self-review finding). The two-slot search keeps
+    // deterministic wrappers viable without forcing them to symlink or copy.
+    const candidates = [
+        path.join(projectRoot, "scripts", "onto-review-watch.sh"),
+    ];
+    if (ontoHome && ontoHome !== projectRoot) {
+        candidates.push(path.join(ontoHome, "scripts", "onto-review-watch.sh"));
+    }
+    const watcherScript = candidates.find((c) => fs.existsSync(c));
+    if (!watcherScript) {
+        return { spawned: false, reason: "watcher script not found" };
+    }
+    const watcherArgs = `bash "${watcherScript}" "${sessionRoot}"`;
+    // Dry-run mode: detect the mechanism that would be used and report it,
+    // but skip the actual tmux/osascript spawn call. Intended for smoke
+    // tests and CI that want to cover the detection-priority regressions
+    // without producing a visible side pane or extra terminal tab on every
+    // run. Enabled via `ONTO_WATCHER_DRY_RUN=1`.
+    const dryRun = process.env.ONTO_WATCHER_DRY_RUN === "1";
+    // Priority 1: tmux (works on any OS, most universal)
+    if (process.env.TMUX) {
+        if (dryRun) {
+            return { spawned: true, mechanism: "tmux", dry_run: true };
+        }
+        try {
+            // Target the originating pane explicitly via $TMUX_PANE so the split
+            // does not land on whichever pane happens to be active at spawn time.
+            const tmuxArgs = ["split-window", "-h", "-l", "60"];
+            const originPane = process.env.TMUX_PANE;
+            if (originPane) {
+                tmuxArgs.push("-t", originPane);
+            }
+            tmuxArgs.push(watcherArgs);
+            const result = spawnSync("tmux", tmuxArgs, { stdio: "ignore" });
+            if (result.status === 0) {
+                // Refocus original pane so user keeps typing in Claude Code / shell
+                spawnSync("tmux", ["select-pane", "-l"], { stdio: "ignore" });
+                return { spawned: true, mechanism: "tmux" };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    // Priority 2: iTerm2 on macOS
+    // Target the originating session via $ITERM_SESSION_ID (inherited at
+    // process start), so the split lands beside the pane that launched
+    // onto:review even if the user has since switched tabs or windows.
+    //
+    // Format note: $ITERM_SESSION_ID is `wXtYpZ:UUID` but AppleScript's
+    // `id of session` returns the UUID only. We compare both forms to stay
+    // robust across iTerm2 builds, and require the script to print an
+    // explicit "matched" sentinel before reporting success. If no match
+    // (e.g. the originating tab has been closed, or the env var is absent),
+    // we return spawned: false and let the caller print the manual hint —
+    // splitting into `current session of current tab` would land on whatever
+    // tab happens to be focused at spawn time, which is not the intended UX.
+    if (process.platform === "darwin" &&
+        process.env.TERM_PROGRAM === "iTerm.app") {
+        const rawSessionId = process.env.ITERM_SESSION_ID;
+        if (rawSessionId) {
+            if (dryRun) {
+                return { spawned: true, mechanism: "iterm2", dry_run: true };
+            }
+            try {
+                const sessionUuid = rawSessionId.includes(":")
+                    ? (rawSessionId.split(":").pop() ?? rawSessionId)
+                    : rawSessionId;
+                const escapedCmd = watcherArgs
+                    .replace(/\\/g, "\\\\")
+                    .replace(/"/g, '\\"');
+                const escapedFull = rawSessionId
+                    .replace(/\\/g, "\\\\")
+                    .replace(/"/g, '\\"');
+                const escapedUuid = sessionUuid
+                    .replace(/\\/g, "\\\\")
+                    .replace(/"/g, '\\"');
+                const script = `tell application "iTerm2"\n` +
+                    `  repeat with w in windows\n` +
+                    `    repeat with t in tabs of w\n` +
+                    `      repeat with s in sessions of t\n` +
+                    `        if (id of s is "${escapedUuid}") or (id of s is "${escapedFull}") then\n` +
+                    `          tell s\n` +
+                    `            split vertically with default profile command "${escapedCmd}"\n` +
+                    `          end tell\n` +
+                    `          return "matched"\n` +
+                    `        end if\n` +
+                    `      end repeat\n` +
+                    `    end repeat\n` +
+                    `  end repeat\n` +
+                    `  return "no-match"\n` +
+                    `end tell`;
+                const result = spawnSync("osascript", ["-e", script], {
+                    encoding: "utf8",
+                });
+                if (result.status === 0 && result.stdout.trim() === "matched") {
+                    return { spawned: true, mechanism: "iterm2" };
+                }
+            }
+            catch {
+                // fall through
+            }
+        }
+    }
+    // Priority 3: Apple Terminal on macOS
+    if (process.platform === "darwin" &&
+        process.env.TERM_PROGRAM === "Apple_Terminal") {
+        if (dryRun) {
+            return { spawned: true, mechanism: "apple_terminal", dry_run: true };
+        }
+        try {
+            const escapedCmd = watcherArgs.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+            const script = `tell application "Terminal"\n` +
+                `  do script "${escapedCmd}"\n` +
+                `end tell`;
+            const result = spawnSync("osascript", ["-e", script], { stdio: "ignore" });
+            if (result.status === 0) {
+                return { spawned: true, mechanism: "apple_terminal" };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return {
+        spawned: false,
+        reason: "no supported terminal multiplexer detected (tmux, iTerm2, Apple Terminal)",
+    };
+}