onto-mcp 0.4.11 → 0.4.13

package/dist/core-runtime/target-material-kind.js

@@ -66,6 +66,11 @@ const SPREADSHEET_EXTENSIONS = new Set([
     ".xlsm",
     ".xlsx",
 ]);
+/** True when the ref's name denotes spreadsheet/workbook material by extension
+ *  (the canonical SPREADSHEET_EXTENSIONS set). Pure — no IO. */
+export function isSpreadsheetRef(ref) {
+    return SPREADSHEET_EXTENSIONS.has(path.extname(ref).toLowerCase());
+}
 const DOCUMENT_EXTENSIONS = new Set([
     ".adoc",
     ".doc",
@@ -275,6 +280,20 @@ export function reviewMaterialSupportStatus(kind) {
             reason: null,
         };
     }
+    if (kind === "spreadsheet") {
+        // KIND-level claim: review has a per-material spreadsheet adapter — kind-derived
+        // review obligations (reviewMaterialGoals) backed by a structural inventory that is
+        // rendered into materialized-input (structure inspected only; formula results are
+        // NOT recalculated). The PER-TARGET-FORMAT gate lives in the review materializer:
+        // when a specific ref uses an unsupported workbook format (.xls/.xlsb/.ods) or is
+        // unreadable, the materializer downgrades the recorded support_status from this
+        // kind-level supported to partial, so a `supported`/`null` profile is never emitted
+        // for a workbook the inventory could not actually read.
+        return {
+            status: "supported",
+            reason: null,
+        };
+    }
     if (kind === "unknown") {
         return {
             status: "unknown",
@@ -292,3 +311,42 @@ export function reviewMaterialSupportStatus(kind) {
         reason: "review records target material kind, but material-specific validation is not implemented yet",
     };
 }
+/**
+ * Kind-derived review obligations for the review target profile's `review_goal`.
+ * These are the persisted, downstream-projected (problem-framing) review dimensions a
+ * per-material review adapter adds on top of the artifact-role and domain goals — a
+ * distinct surface from the ephemeral prompt-render `material_kind_obligations` prose.
+ *
+ * Spreadsheet obligations are distilled from the structural-audit checklist (read/observe
+ * scope only — no authoring, no recalculation, no business interpretation) and every goal
+ * is backed by a `WorkbookStructuralInventory` field that review renders into
+ * materialized-input (see review-artifact-utils `renderSpreadsheetStructuralView`):
+ *
+ * - formula_integrity            ← formula_cells_total (>0) + formula_patterns (formula text) + error_cells
+ * - cross_sheet_reference_integrity ← formula_patterns[].cross_sheet_refs + cross_sheet_key_overlap
+ * - named_range_hygiene          ← named_ranges (name/scope/refers_to)
+ * - data_validation_coverage     ← data_validations (range/rule_summary)
+ * - access_and_protection_hygiene ← sheets[].hidden/protected + macro_present
+ * - structural_risk_signals      ← risk_signals + external_links + error_cells
+ *
+ * The structure-inspected-only honesty is carried by the invariant render header and the
+ * review-target-profile contract, NOT by a review_goal string (uniqueStrings may dedupe or
+ * reorder it, and it would collide with the inventory's `inspection_method` literal).
+ *
+ * Other kinds return `[]` until their per-material review adapters land. `mixed` returns
+ * `[]` (a spreadsheet inside a mixed bundle does not yet receive spreadsheet obligations —
+ * a known C-review limitation, consistent with the mixed support state).
+ */
+export function reviewMaterialGoals(kind) {
+    if (kind === "spreadsheet") {
+        return [
+            "formula_integrity",
+            "cross_sheet_reference_integrity",
+            "named_range_hygiene",
+            "data_validation_coverage",
+            "access_and_protection_hygiene",
+            "structural_risk_signals",
+        ];
+    }
+    return [];
+}

package/dist/mcp/server.js

@@ -345,7 +345,7 @@ const RECONSTRUCT_INPUT_SCHEMA = {
         resumeMode: {
             type: "string",
             enum: ["fresh", "reuse_existing_authored_artifacts"],
-            description: "Optional promoted resume mode. fresh rejects same-session duplicate starts; reuse_existing_authored_artifacts admits a same-request resume attempt only when authored-artifact provenance can prove a current match.",
+            description: "Optional promoted resume mode. fresh rejects same-session duplicate starts; reuse_existing_authored_artifacts admits a same-request resume attempt only when authored-artifact provenance can prove a current match, and lets reconstruct semantic-map recover a validated same-batch dispatch-incomplete frontier.",
         },
         semanticAuthorRealization: {
             type: "string",
@@ -357,6 +357,18 @@ const RECONSTRUCT_INPUT_SCHEMA = {
             enum: ["direct_call"],
             description: "Explicit confirmation provider realization. direct_call uses configured llm provider.",
         },
+        llmEffort: {
+            type: "string",
+            description: "Optional reasoning-effort pin applied to both reconstruct actors (live only; mock ignores it).",
+        },
+        judgeLlmEffort: {
+            type: "string",
+            description: "Opt-in: run the answer-support judge at a different reasoning effort than the semantic author (live only). Reduces same-model rubber-stamping.",
+        },
+        judgeModel: {
+            type: "string",
+            description: "Opt-in: swap the answer-support judge MODEL (on the semantic author's provider; live only). An unsupported model degrades to the author model (INV-MODEL-1); a degrade is recorded as a runtime status note.",
+        },
     },
 };
 const RECONSTRUCT_SESSION_INPUT_SCHEMA = {
@@ -455,7 +467,7 @@ const TOOL_DEFINITIONS = [
     },
     {
         name: "onto_review_continue",
-        description: "Continue a review session when runControl.continuationAvailable is true by reusing trusted PipelineExecutionLedger units and rerunning only the continuation frontier and downstream units.",
+        description: "The default way to resume a review that halted, timed out, or is prepared (runControl.continuationAvailable=true): reuses trusted PipelineExecutionLedger units and reruns only the continuation frontier and downstream units. Prefer this over starting a new onto_review — it keeps already-completed work. This is the operational resume of a session; it is not the continue_review finding action-candidate (which means the review should expand its evidence boundary).",
         inputSchema: REVIEW_CONTINUE_INPUT_SCHEMA,
     },
     {
@@ -495,12 +507,12 @@ const TOOL_DEFINITIONS = [
     },
     {
         name: "onto_reconstruct",
-        description: "Run the material-aware reconstruct path with live semantic authoring, runtime validation gates, final-output.md, and reconstruct-record.yaml refs.",
+        description: "Run the material-aware reconstruct path with live semantic authoring and runtime validation gates. Returns final-output.md and reconstruct-record.yaml refs on completion, or a bounded record-less failed projection for a trusted provider output-ceiling terminal.",
         inputSchema: RECONSTRUCT_INPUT_SCHEMA,
     },
     {
         name: "onto_reconstruct_read",
-        description: "Read a reconstruct session — stage progress, liveness, and count summary at projectionLevel compact/standard; the full record, run manifest, and final output at projectionLevel=full. Replaces onto_reconstruct_status and onto_reconstruct_result.",
+        description: "Read a reconstruct session — stage progress, liveness, and count summary at projectionLevel compact/standard; the full record, run manifest, and final output at projectionLevel=full. A trusted provider failure before record assembly returns the bounded record-less failed projection at every level. Replaces onto_reconstruct_status and onto_reconstruct_result.",
         inputSchema: RECONSTRUCT_READ_INPUT_SCHEMA,
     },
 ];
@@ -521,7 +533,7 @@ export function advertisedToolDefinitions() {
     const simple = new Set(OntoSimpleProfileToolNames);
     return TOOL_DEFINITIONS.filter((tool) => simple.has(tool.name));
 }
-const USAGE_GUIDE = `# Using onto via MCP
+export const USAGE_GUIDE = `# Using onto via MCP
 
 onto is an ontology-as-code review runtime. The host LLM drives it through MCP
 tools; the runtime owns artifacts and validation. Two product paths exist:
@@ -566,6 +578,13 @@ reported through canonical route visibility. Listing tools needs no provider.
    result (full adds the ReviewRecord and final output text); a halted or failed
    session returns the status/failure projection.
    Present using the result's llmPresentation prompts.
+4. If the review halted (status "halted") and runControl.continuationAvailable is
+   true, the default next action is \`onto_review_continue\` with the same
+   sessionRoot: it resumes the session, reuses already-completed units, and
+   reruns only the failed/missing frontier and its downstream. Prefer it over
+   starting a fresh \`onto_review\`. (This operational resume is distinct from the
+   \`continue_review\` finding action-candidate, which means "expand the review's
+   evidence boundary because it was insufficient".)
 
 Other review tools: \`onto_prepare_review\` (materialize without executing) then
 \`onto_review_continue\`; \`onto_review_cancel\` to stop a running session.
@@ -1518,6 +1537,9 @@ export async function callTool(name, args, options = {}) {
                     ...(parsed.resumeMode !== undefined ? { resumeMode: parsed.resumeMode } : {}),
                     semanticAuthorRealization: parsed.semanticAuthorRealization,
                     confirmationProviderRealization: parsed.confirmationProviderRealization,
+                    ...(parsed.llmEffort !== undefined ? { llmEffort: parsed.llmEffort } : {}),
+                    ...(parsed.judgeLlmEffort !== undefined ? { judgeLlmEffort: parsed.judgeLlmEffort } : {}),
+                    ...(parsed.judgeModel !== undefined ? { judgeModel: parsed.judgeModel } : {}),
                     ...(sessionRoot ? { sessionRoot } : {}),
                     ...(profilesRoot ? { profilesRoot } : {}),
                     ...(filesystemAllowedRoots ? { filesystemAllowedRoots } : {}),

package/dist/mcp/tool-schemas.js

@@ -90,6 +90,14 @@ export const OntoReconstructToolInputSchema = OntoObserveSourceToolInputSchema.e
     resumeMode: z.enum(["fresh", "reuse_existing_authored_artifacts"]).optional(),
     semanticAuthorRealization: z.enum(["direct_call"]).default("direct_call"),
     confirmationProviderRealization: z.enum(["direct_call"]).default("direct_call"),
+    // Optional reasoning-effort pin applied to both reconstruct actors (live only).
+    llmEffort: z.string().min(1).optional(),
+    // Opt-in per-stage answer-support JUDGE overrides (live only). judgeLlmEffort
+    // runs the judge at a different effort; judgeModel swaps the judge MODEL on the
+    // semantic author's provider. An unsupported judgeModel degrades to the author
+    // model (INV-MODEL-1); the judge otherwise inherits the semantic-author config.
+    judgeLlmEffort: z.string().min(1).optional(),
+    judgeModel: z.string().min(1).optional(),
 }).strict();
 export const OntoReconstructSessionInputSchema = z.object({
     sessionRoot: z.string().min(1),

package/dist/tui/app.js

@@ -0,0 +1,167 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `onto watch` Ink application — a small screen router over read-only data:
+ *   selector → pick a session;  tree → live WorkflowTree HUD;  log → event tail.
+ * Keys: ↑↓/enter (selector), tab (tree↔log), s (→selector), r (refresh tree),
+ * q (quit). It only reads projections + tails the event stream — never mutates
+ * run state.
+ */
+import { Box, Text, useApp, useInput } from "ink";
+import { useEffect, useState } from "react";
+import { followRuntimeEvents } from "./data/event-follower.js";
+import { loadTreeViewModel } from "./data/projection-poll.js";
+import { readOutputTail } from "./data/node-detail.js";
+import { LogScreen } from "./screens/log.js";
+import { NodeDetail } from "./screens/node-detail.js";
+import { SessionSelector } from "./screens/session-selector.js";
+import { WorkflowTree } from "./screens/workflow-tree.js";
+import { isTerminalStatus, } from "./view-model/tree-view-model.js";
+export function WatchApp({ sessions, initialSession, ontoHome, defaultPollMs = 1000, nowMs, }) {
+    const { exit } = useApp();
+    const [screen, setScreen] = useState(initialSession ? "tree" : "selector");
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const [session, setSession] = useState(initialSession ?? null);
+    const [vm, setVm] = useState(null);
+    const [treeError, setTreeError] = useState(null);
+    const [events, setEvents] = useState([]);
+    const [nonce, setNonce] = useState(0);
+    const [nodeCursor, setNodeCursor] = useState(0);
+    const [tail, setTail] = useState([]);
+    const flatNodes = vm ? vm.phases.flatMap((p) => p.nodes) : [];
+    const selectedNode = flatNodes.length > 0
+        ? flatNodes[Math.min(nodeCursor, flatNodes.length - 1)]
+        : null;
+    useInput((input, key) => {
+        if (input === "q") {
+            exit();
+            return;
+        }
+        if (screen === "selector") {
+            if (key.upArrow)
+                setSelectedIndex((i) => Math.max(0, i - 1));
+            else if (key.downArrow) {
+                setSelectedIndex((i) => Math.min(sessions.length - 1, i + 1));
+            }
+            else if (key.return && sessions[selectedIndex]) {
+                setSession(sessions[selectedIndex]);
+                setVm(null);
+                setTreeError(null);
+                setEvents([]);
+                setNodeCursor(0);
+                // Bump the poll nonce so the tree effect re-runs even when the chosen
+                // session is the one already selected (same ref → deps unchanged);
+                // otherwise setVm(null) would leave the HUD stuck on "loading…".
+                setNonce((n) => n + 1);
+                setScreen("tree");
+            }
+            return;
+        }
+        if (input === "s")
+            setScreen("selector");
+        else if (key.tab)
+            setScreen((s) => (s === "tree" ? "log" : "tree"));
+        else if (screen === "tree" && input === "r")
+            setNonce((n) => n + 1);
+        else if (screen === "tree" && key.upArrow) {
+            setNodeCursor((c) => Math.max(0, c - 1));
+        }
+        else if (screen === "tree" && key.downArrow) {
+            setNodeCursor((c) => Math.min(Math.max(0, flatNodes.length - 1), c + 1));
+        }
+    });
+    // Tree projection poll — respects the projection interval, stops at terminal status.
+    useEffect(() => {
+        if (!session)
+            return;
+        let cancelled = false;
+        let timer;
+        async function tick() {
+            try {
+                const next = await loadTreeViewModel(session, ontoHome ? { ontoHome } : {});
+                if (cancelled)
+                    return;
+                setVm(next);
+                setTreeError(null);
+                if (isTerminalStatus(next.status))
+                    return;
+                timer = setTimeout(() => void tick(), Math.max(500, next.liveness.pollMs ?? defaultPollMs));
+            }
+            catch (caught) {
+                if (!cancelled) {
+                    setTreeError(caught instanceof Error ? caught.message : String(caught));
+                    // Keep the live loop alive: a transient read/parse error (e.g. a file
+                    // mid-rewrite) self-recovers on the next tick. The error stays visible
+                    // until a successful poll clears it (setTreeError(null) above).
+                    timer = setTimeout(() => void tick(), Math.max(500, defaultPollMs));
+                }
+            }
+        }
+        void tick();
+        return () => {
+            cancelled = true;
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [session, ontoHome, defaultPollMs, nonce]);
+    // Live event tail for the Log screen.
+    useEffect(() => {
+        if (!session)
+            return;
+        const controller = new AbortController();
+        let cancelled = false;
+        void (async () => {
+            for await (const event of followRuntimeEvents(session.sessionRoot, {
+                signal: controller.signal,
+            })) {
+                // Skip a late event from the aborted (previous-session) follower so it
+                // never lands in the new session's tail.
+                if (cancelled)
+                    break;
+                setEvents((prev) => [...prev, event].slice(-500));
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [session]);
+    // Drill-down: read the selected node's output tail (read-only).
+    const selectedOutputPath = selectedNode?.outputPath ?? null;
+    // A running node's `.running.log` keeps growing, so re-read its tail on every
+    // poll tick (keyed on the vm the poll replaces). A terminal node's tail is
+    // stable, so for it we key only on the path and skip the per-tick re-read.
+    const tailIsStable = selectedNode != null
+        && (selectedNode.status === "completed"
+            || selectedNode.status === "failed"
+            || selectedNode.status === "skipped");
+    const tailRefreshKey = tailIsStable ? null : vm;
+    useEffect(() => {
+        let cancelled = false;
+        if (!selectedOutputPath) {
+            setTail([]);
+            return;
+        }
+        void readOutputTail(selectedOutputPath).then((lines) => {
+            if (!cancelled)
+                setTail(lines);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [selectedOutputPath, tailRefreshKey]);
+    if (screen === "selector") {
+        return (_jsx(SessionSelector, { sessions: sessions, selectedIndex: selectedIndex, ...(nowMs !== undefined ? { nowMs } : {}) }));
+    }
+    if (!session)
+        return _jsx(Text, { children: "no session selected" });
+    if (screen === "log") {
+        return _jsx(LogScreen, { sessionId: session.sessionId, events: events });
+    }
+    if (treeError) {
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "red", children: `onto watch error: ${treeError}` }), _jsx(Text, { dimColor: true, children: "[s]essions  [r]etry  [q]uit" })] }));
+    }
+    if (!vm) {
+        return _jsx(Text, { children: `loading ${session.pipeline} session ${session.sessionId}…` });
+    }
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(WorkflowTree, { vm: vm, ...(selectedNode ? { selectedNodeId: selectedNode.id } : {}) }), selectedNode ? _jsx(NodeDetail, { node: selectedNode, tail: tail }) : null] }));
+}

package/dist/tui/data/event-follower.js

@@ -0,0 +1,116 @@
+/**
+ * Tails a session's append-only `runtime-events.ndjson` for the `onto watch`
+ * TUI. Read-only: it never writes the stream. Reads existing lines, then polls
+ * for appended lines (offset-tracked) and yields parsed events until aborted.
+ */
+import fs from "node:fs/promises";
+import { runtimeStreamEventLogPath, } from "../../core-api/runtime-observation.js";
+function parseEventLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        // Defensive: only accept well-formed runtime_stream events.
+        if (parsed && parsed.event_kind === "runtime_stream")
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** One-shot read of all events currently in the session's stream. */
+export async function readRuntimeEvents(sessionRoot) {
+    const logPath = runtimeStreamEventLogPath(sessionRoot);
+    let raw;
+    try {
+        raw = await fs.readFile(logPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    return raw.split("\n").map(parseEventLine).filter((event) => event !== null);
+}
+/** Bytes of historical backlog read on start — the UI only keeps the last 500. */
+const DEFAULT_BACKLOG_BYTES_CAP = 256 * 1024;
+/**
+ * Async iterator over a session's runtime events: emits a bounded tail of the
+ * existing backlog (unless disabled), then appended events as they land, until
+ * `signal` aborts. Tracks a byte offset and only re-parses the trailing partial
+ * line on each tick.
+ */
+export async function* followRuntimeEvents(sessionRoot, options = {}) {
+    const { pollMs = 500, signal, emitBacklog = true, backlogBytesCap = DEFAULT_BACKLOG_BYTES_CAP, } = options;
+    const logPath = runtimeStreamEventLogPath(sessionRoot);
+    let offset = 0;
+    let pending = "";
+    let dropPartialLine = false;
+    // Bound the initial backlog so a large historical log never loads whole: with
+    // emitBacklog, keep only the last backlogBytesCap bytes (dropping the partial
+    // leading line); without it, start at EOF and only follow appended lines.
+    try {
+        const { size } = await fs.stat(logPath);
+        if (!emitBacklog) {
+            offset = size;
+        }
+        else if (size > backlogBytesCap) {
+            offset = size - backlogBytesCap;
+            dropPartialLine = true;
+        }
+    }
+    catch {
+        // Stream not created yet — start from 0 and pick it up when it appears.
+    }
+    while (!signal?.aborted) {
+        let chunk = "";
+        try {
+            const handle = await fs.open(logPath, "r");
+            try {
+                const stat = await handle.stat();
+                if (stat.size < offset) {
+                    // File shrank/rotated — restart from the top.
+                    offset = 0;
+                    pending = "";
+                    dropPartialLine = false;
+                }
+                if (stat.size > offset) {
+                    const length = stat.size - offset;
+                    const buffer = Buffer.alloc(length);
+                    // Advance only by bytes actually read; a short read must not skip the
+                    // unread tail or decode the zero-filled remainder of the buffer.
+                    const { bytesRead } = await handle.read(buffer, 0, length, offset);
+                    chunk = buffer.toString("utf8", 0, bytesRead);
+                    offset += bytesRead;
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            // Stream not created yet — wait and retry.
+        }
+        // Abort may have landed during the fs read; bail before yielding so a late
+        // event from an aborted follower never reaches the consumer.
+        if (signal?.aborted)
+            return;
+        if (chunk) {
+            pending += chunk;
+            const lines = pending.split("\n");
+            // Keep the trailing (possibly partial) line for the next tick.
+            pending = lines.pop() ?? "";
+            if (dropPartialLine) {
+                // The first bounded read started mid-file; drop the partial leading line.
+                lines.shift();
+                dropPartialLine = false;
+            }
+            for (const line of lines) {
+                const event = parseEventLine(line);
+                if (event)
+                    yield event;
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}

package/dist/tui/data/node-detail.js

@@ -0,0 +1,42 @@
+/**
+ * Reads the tail of a tree node's authored output / running log (the node's
+ * `outputPath`) for the drill-down detail pane. Read-only; returns [] when the
+ * path is absent or unreadable.
+ *
+ * The detail pane re-reads on every poll tick for a running node whose
+ * `.running.log` keeps growing, so this reads only a bounded suffix from the end
+ * of the file (not the whole file) to keep cost independent of file size.
+ */
+import fs from "node:fs/promises";
+/** Bytes read from the end of the file — ample for `maxLines` of tail. */
+const TAIL_BYTES_CAP = 64 * 1024;
+export async function readOutputTail(outputPath, maxLines = 12) {
+    if (!outputPath)
+        return [];
+    let handle;
+    try {
+        handle = await fs.open(outputPath, "r");
+        const { size } = await handle.stat();
+        const start = size > TAIL_BYTES_CAP ? size - TAIL_BYTES_CAP : 0;
+        const length = size - start;
+        if (length <= 0)
+            return [];
+        const buffer = Buffer.alloc(length);
+        // Decode only the bytes actually read (a short read must not leave the
+        // zero-filled remainder of the buffer in the decoded text).
+        const { bytesRead } = await handle.read(buffer, 0, length, start);
+        let text = buffer.toString("utf8", 0, bytesRead);
+        // When we started mid-file, drop the leading partial line.
+        if (start > 0) {
+            const newline = text.indexOf("\n");
+            text = newline >= 0 ? text.slice(newline + 1) : "";
+        }
+        return text.split("\n").filter((line) => line.length > 0).slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/tui/data/projection-poll.js

@@ -0,0 +1,26 @@
+/**
+ * Loads a session's {@link TreeViewModel} by calling the same core-api read
+ * projection the MCP read tools use, then routing it through the pipeline's
+ * adapter. Read-only. The poll LOOP (interval, abort) lives in the Ink app; this
+ * module is the single-shot fetch so it stays trivially testable.
+ */
+import { createOntoReviewCoreApi } from "../../core-api/review-api.js";
+import { createOntoReconstructCoreApi } from "../../core-api/reconstruct-api.js";
+import { reviewStatusToTreeViewModel } from "../view-model/review-adapter.js";
+import { reconstructStatusToTreeViewModel } from "../view-model/reconstruct-adapter.js";
+/** Single-shot read of the current TreeViewModel for a session. */
+export async function loadTreeViewModel(ref, deps = {}) {
+    const options = deps.ontoHome ? { ontoHome: deps.ontoHome } : {};
+    if (ref.pipeline === "review") {
+        const api = createOntoReviewCoreApi(options);
+        // Request the full projection: the standard projection compacts
+        // unit_progress `outputPath`/`runningLogRef` with an ellipsis, and the TUI
+        // does local file I/O (drill-down tail) on those paths — they must be
+        // untruncated.
+        const status = await api.getReviewStatus(ref.sessionRoot, { projectionLevel: "full" });
+        return reviewStatusToTreeViewModel(status, ref.sessionRoot);
+    }
+    const api = createOntoReconstructCoreApi(options);
+    const status = await api.getRunStatus(ref.sessionRoot);
+    return reconstructStatusToTreeViewModel(status, ref.sessionRoot);
+}

package/dist/tui/data/session-discovery.js

@@ -0,0 +1,65 @@
+/**
+ * Enumerates review/reconstruct session directories under a project's `.onto/`
+ * for the `onto watch` SessionSelector. Read-only listing; status enrichment is
+ * left to the caller (which polls getReviewStatus / getRunStatus per session).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runtimeStreamEventLogPath } from "../../core-api/runtime-observation.js";
+const PIPELINE_DIRS = {
+    review: "review",
+    reconstruct: "reconstruct",
+};
+async function listPipelineSessions(projectRoot, pipeline) {
+    const root = path.join(path.resolve(projectRoot), ".onto", PIPELINE_DIRS[pipeline]);
+    let entries;
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const sessions = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const sessionRoot = path.join(root, entry.name);
+        let modifiedMs = 0;
+        try {
+            modifiedMs = (await fs.stat(sessionRoot)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        // The root dir mtime misses content appends (a running session keeps
+        // appending to runtime-events.ndjson and nested running logs without
+        // touching the dir entry), so fold in the event log's mtime as the primary
+        // activity signal — otherwise an active session can sort below older ones.
+        try {
+            const eventMs = (await fs.stat(runtimeStreamEventLogPath(sessionRoot))).mtimeMs;
+            if (eventMs > modifiedMs)
+                modifiedMs = eventMs;
+        }
+        catch {
+            // No event log yet — fall back to the dir mtime.
+        }
+        sessions.push({
+            pipeline,
+            sessionId: entry.name,
+            sessionRoot,
+            modifiedMs,
+        });
+    }
+    return sessions;
+}
+/**
+ * Lists all review + reconstruct sessions under `projectRoot/.onto/`, most
+ * recently modified first.
+ */
+export async function discoverSessions(projectRoot) {
+    const [review, reconstruct] = await Promise.all([
+        listPipelineSessions(projectRoot, "review"),
+        listPipelineSessions(projectRoot, "reconstruct"),
+    ]);
+    return [...review, ...reconstruct].sort((a, b) => b.modifiedMs - a.modifiedMs);
+}