onto-mcp 0.3.0 → 0.3.2

package/dist/core-api/review-api.js

@@ -1,14 +1,40 @@
+import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { resolveOntoHome } from "../core-runtime/discovery/onto-home.js";
 import { loadCoreLensRegistry } from "../core-runtime/discovery/lens-registry.js";
-import { fileExists, isoFromTimestamp, isoNow, readYamlDocument, } from "../core-runtime/review/review-artifact-utils.js";
+import { fileExists, isDeprecatedDomainAlias, isoFromTimestamp, isoNow, normalizeDomainValue, readYamlDocument, writeYamlDocument, } from "../core-runtime/review/review-artifact-utils.js";
+import { assertPathInsideRoot, realpathIfExists, } from "../core-runtime/path-boundary.js";
+import { assertReviewExecutionPlanSessionBoundary, } from "../core-runtime/review/execution-plan-boundary.js";
 import { buildReviewRouteVisibilityFromSession, } from "../core-runtime/review/route-visibility.js";
 import { readValidatedReviewRecord } from "../core-runtime/review/review-record-validation.js";
 import { readReviewResultClassification } from "../core-runtime/review/review-result-classification.js";
 import { REVIEW_EXECUTION_STEP_IDS, REVIEW_PROGRESS_STEPS, REVIEW_PROGRESS_TOTAL_STEPS, reviewProgressStepById, reviewProgressStepIdFromHalt, } from "../core-runtime/review/review-progress-contract.js";
-import { reviewPrepareOnly, runReviewInvokeCli } from "../core-runtime/cli/review-invoke.js";
+import { collectReviewInvocationArtifactRefs, prepareReviewInvocationRequest, runReviewInvocation, } from "../core-runtime/review/review-invocation-runner.js";
+import { completeReviewSession } from "../core-runtime/cli/complete-review-session.js";
+import { buildExecutorConfigFromRealization, } from "../core-runtime/cli/review-invoke.js";
+import { executeReviewPromptExecution, } from "../core-runtime/cli/run-review-prompt-execution.js";
+import { buildReviewPipelineExecutionLedger, } from "../core-runtime/review/pipeline-execution-ledger.js";
+import { buildReviewContinuationPlan, } from "../core-runtime/review/continuation-plan.js";
+export class ReviewContinuationError extends Error {
+    failureContent;
+    originalError;
+    constructor(args) {
+        super(args.message);
+        this.name = "ReviewContinuationError";
+        this.originalError = args.originalError;
+        this.failureContent = args.failureContent;
+    }
+}
+export class ReviewDomainResolutionError extends Error {
+    domainResolution;
+    constructor(args) {
+        super(args.message);
+        this.name = "ReviewDomainResolutionError";
+        this.domainResolution = args.domainResolution;
+    }
+}
 function stringifyConsoleArgs(args) {
     return args
         .map((arg) => {
@@ -74,53 +100,6 @@ async function withCapturedConsole(action, observer) {
 function resolveRequiredOntoHome(explicit) {
     return resolveOntoHome(explicit);
 }
-function appendCommonReviewArgs(args, request, ontoHome) {
-    const result = [
-        ...args,
-        request.target,
-        request.intent,
-        "--project-root",
-        path.resolve(request.projectRoot),
-    ];
-    result.push("--onto-home", ontoHome);
-    if (request.domain && request.noDomain) {
-        throw new Error("Use either domain or noDomain, not both.");
-    }
-    if (request.domain) {
-        result.push("--domain", request.domain);
-    }
-    if (request.noDomain) {
-        result.push("--no-domain");
-    }
-    if (request.reviewMode) {
-        result.push("--review-mode", request.reviewMode);
-    }
-    if (request.targetScopeKind) {
-        result.push("--target-scope-kind", request.targetScopeKind);
-    }
-    if (request.primaryRef) {
-        result.push("--primary-ref", request.primaryRef);
-    }
-    for (const memberRef of request.memberRefs ?? []) {
-        result.push("--member-ref", memberRef);
-    }
-    if (request.bundleKind) {
-        result.push("--bundle-kind", request.bundleKind);
-    }
-    if (request.diffRange) {
-        result.push("--diff-range", request.diffRange);
-    }
-    if (request.executorRealization) {
-        result.push("--executor-realization", request.executorRealization);
-    }
-    for (const lensId of request.lensIds ?? []) {
-        result.push("--lens-id", lensId);
-    }
-    if (request.confirmValueAlignment) {
-        result.push("--confirm-value-alignment");
-    }
-    return result;
-}
 function basenameSessionId(sessionRoot) {
     return path.basename(path.resolve(sessionRoot));
 }
@@ -132,19 +111,63 @@ async function readOptionalYaml(filePath) {
 async function readOptionalReviewRecord(filePath) {
     if (!(await fileExists(filePath)))
         return null;
-    return readValidatedReviewRecord(filePath);
+    try {
+        return await readValidatedReviewRecord(filePath);
+    }
+    catch {
+        return null;
+    }
 }
 async function readOptionalText(filePath) {
     if (!(await fileExists(filePath)))
         return undefined;
     return fs.readFile(filePath, "utf8");
 }
+async function resolveReviewRecordFinalOutputPath(args) {
+    const sessionRoot = path.resolve(args.sessionRoot);
+    const rawRef = args.finalOutputRef ?? path.join(sessionRoot, "final-output.md");
+    const candidates = path.isAbsolute(rawRef)
+        ? [path.resolve(rawRef)]
+        : [
+            path.resolve(sessionRoot, rawRef),
+            ...(args.projectRoot ? [path.resolve(args.projectRoot, rawRef)] : []),
+        ];
+    for (const candidate of candidates) {
+        if (!(await fileExists(candidate)))
+            continue;
+        await assertPathInsideRoot({
+            root: sessionRoot,
+            candidate,
+            label: "ReviewRecord.final_output_ref",
+        });
+        return candidate;
+    }
+    const fallback = candidates[0] ?? path.join(sessionRoot, "final-output.md");
+    await assertPathInsideRoot({
+        root: sessionRoot,
+        candidate: fallback,
+        label: "ReviewRecord.final_output_ref",
+    });
+    return fallback;
+}
+async function assertSamePath(args) {
+    const expected = path.resolve(args.expected);
+    const actual = path.resolve(args.actual);
+    if (expected === actual)
+        return;
+    const realExpected = await realpathIfExists(expected);
+    const realActual = await realpathIfExists(actual);
+    if (realExpected && realActual && path.resolve(realExpected) === path.resolve(realActual)) {
+        return;
+    }
+    throw new Error(`${args.label} mismatch: expected ${expected}, received ${actual}`);
+}
 function buildOpeningBriefPresentation(input) {
     return {
         prompt: [
             "Explain this onto review opening brief to the user before execution.",
             "Use only the provided input facts. Do not infer or invent target scope, boundary, domain, lens set, model, provider, or execution mode.",
-            "Cover: what is being reviewed, why, filesystem boundary, selected domain, review mode and lens set, execution path, model/provider settings, and where the user can change configuration.",
+            "Cover: what is being reviewed, why, filesystem boundary, selected domain and domain selection reason, review mode and lens set, execution path, model/provider settings, and where the user can change configuration.",
             "Keep it structured and concise. Use the user's conversation language.",
         ].join("\n"),
         input,
@@ -180,6 +203,399 @@ const OPENING_PRESENTATION_SOURCE_REF_KEYS = [
     "review_target_profile",
     "review_context_manifest",
 ];
+const ACTIVE_REVIEW_ATTEMPT_FILENAME = "active-review-attempt.yaml";
+const ENVIRONMENT_WARNINGS_FILENAME = "environment-warnings.yaml";
+const REVIEW_CANCEL_REQUEST_FILENAME = "review-cancel-request.yaml";
+const DEFAULT_ACTIVE_ATTEMPT_STALE_AFTER_SECONDS = 1_200;
+const REVIEW_RUNNER_WARNING_PREFIX = "[review runner warning]";
+function activeAttemptPath(sessionRoot) {
+    return path.join(sessionRoot, ACTIVE_REVIEW_ATTEMPT_FILENAME);
+}
+function environmentWarningsPath(sessionRoot) {
+    return path.join(sessionRoot, ENVIRONMENT_WARNINGS_FILENAME);
+}
+function reviewCancelRequestPath(sessionRoot) {
+    return path.join(sessionRoot, REVIEW_CANCEL_REQUEST_FILENAME);
+}
+function activeAttemptStaleAfterSeconds() {
+    const parsed = Number(process.env.ONTO_REVIEW_ACTIVE_ATTEMPT_STALE_AFTER_SECONDS);
+    return Number.isFinite(parsed) && parsed > 0
+        ? Math.floor(parsed)
+        : DEFAULT_ACTIVE_ATTEMPT_STALE_AFTER_SECONDS;
+}
+function stripDomainTokenValue(domainValue) {
+    const trimmed = domainValue.trim();
+    return trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function normalizeRefForHash(ref) {
+    if (!ref)
+        return null;
+    return path.normalize(ref).split(path.sep).join(path.posix.sep);
+}
+function canonicalReviewRequestIdentity(input) {
+    if (!input.target || !input.intent)
+        return null;
+    return {
+        schema: "review-request-identity-v2",
+        target: normalizeRefForHash(input.target),
+        intent: input.intent,
+        domain: input.domain ? normalizeDomainValue(input.domain) : null,
+        targetScopeKind: input.targetScopeKind,
+        primaryRef: normalizeRefForHash(input.primaryRef ?? undefined),
+        memberRefs: input.memberRefs.map((ref) => normalizeRefForHash(ref) ?? ref).sort(),
+        bundleKind: input.bundleKind,
+        reviewMode: input.reviewMode,
+        lensIds: [...input.lensIds].sort(),
+    };
+}
+function hashReviewRequestIdentity(identity) {
+    if (!identity)
+        return null;
+    return crypto.createHash("sha256").update(stableJson(identity)).digest("hex");
+}
+function requestHashForReviewInput(args) {
+    return hashReviewRequestIdentity(canonicalReviewRequestIdentity({
+        target: args.target,
+        intent: args.intent,
+        domain: args.noDomain ? "none" : args.domain ?? null,
+        targetScopeKind: args.targetScopeKind ?? null,
+        primaryRef: args.primaryRef ?? null,
+        memberRefs: args.memberRefs ?? [],
+        bundleKind: args.bundleKind ?? null,
+        reviewMode: args.reviewMode ?? null,
+        lensIds: args.lensIds ?? [],
+    }));
+}
+function requestHashFromArtifacts(args) {
+    const scope = args.interpretation?.target_scope_candidate;
+    return hashReviewRequestIdentity(canonicalReviewRequestIdentity({
+        target: args.metadata?.requested_target ?? null,
+        intent: args.interpretation?.intent_summary ?? null,
+        domain: args.binding?.resolved_session_domain ??
+            args.metadata?.requested_domain_token ??
+            null,
+        targetScopeKind: scope?.kind ?? null,
+        primaryRef: scope?.primary_ref ?? null,
+        memberRefs: scope?.member_refs ?? [],
+        bundleKind: scope?.bundle_kind ?? null,
+        reviewMode: args.binding?.resolved_review_mode ??
+            args.interpretation?.review_mode_recommendation ??
+            null,
+        lensIds: args.binding?.resolved_lens_set ??
+            args.interpretation?.lens_selection_plan?.recommended_lenses ??
+            [],
+    }));
+}
+function domainTokenResolution(args) {
+    const requestedToken = args.requestedToken ?? "";
+    const stripped = stripDomainTokenValue(requestedToken);
+    const normalized = args.normalizedDomain ?? null;
+    const suggestionIds = args.suggestionIds ?? [];
+    if (normalized === "none") {
+        return {
+            requestedToken,
+            normalizedDomain: null,
+            resolution: "no_domain",
+            suggestionIds,
+        };
+    }
+    if (!normalized) {
+        return {
+            requestedToken,
+            normalizedDomain: null,
+            resolution: suggestionIds.length > 0 ? "suggestion" : "unknown",
+            suggestionIds,
+        };
+    }
+    return {
+        requestedToken,
+        normalizedDomain: normalized,
+        resolution: stripped.length > 0 && normalizeDomainValue(stripped) !== stripped
+            ? "alias"
+            : "exact",
+        suggestionIds,
+    };
+}
+async function availableDomainIds(projectRoot, ontoHome) {
+    const roots = [
+        path.join(path.resolve(projectRoot), ".onto", "domains"),
+        path.join(os.homedir(), ".onto", "domains"),
+        path.join(ontoHome, ".onto", "domains"),
+    ];
+    const ids = new Set();
+    for (const root of roots) {
+        for (const id of await listDomainDirs(root)) {
+            ids.add(id);
+        }
+    }
+    return [...ids].sort();
+}
+function domainSimilarityScore(requested, candidate) {
+    const requestedTokens = new Set(requested.toLowerCase().split(/[-_\s]+/).filter(Boolean));
+    const candidateTokens = new Set(candidate.toLowerCase().split(/[-_\s]+/).filter(Boolean));
+    let overlap = 0;
+    for (const token of requestedTokens) {
+        if (candidateTokens.has(token))
+            overlap += 1;
+    }
+    if (candidate.toLowerCase().includes(requested.toLowerCase()) ||
+        requested.toLowerCase().includes(candidate.toLowerCase())) {
+        overlap += 2;
+    }
+    return overlap;
+}
+function suggestDomainIds(requestedToken, availableIds) {
+    const stripped = stripDomainTokenValue(requestedToken).toLowerCase();
+    if (!stripped)
+        return [];
+    return availableIds
+        .map((id) => ({ id, score: domainSimilarityScore(stripped, id) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, 5)
+        .map((entry) => entry.id);
+}
+async function validateRequestedDomainForDispatch(request, ontoHome) {
+    if (!request.domain || request.noDomain)
+        return;
+    const normalizedDomain = normalizeDomainValue(request.domain);
+    if (normalizedDomain === "none")
+        return;
+    const domains = await availableDomainIds(request.projectRoot, ontoHome);
+    if (domains.includes(normalizedDomain))
+        return;
+    const suggestionIds = suggestDomainIds(request.domain, domains);
+    throw new ReviewDomainResolutionError({
+        message: suggestionIds.length > 0
+            ? `Unknown review domain ${request.domain}. Did you mean: ${suggestionIds.join(", ")}?`
+            : `Unknown review domain ${request.domain}; no safe domain suggestion is available.`,
+        domainResolution: domainTokenResolution({
+            requestedToken: request.domain,
+            normalizedDomain: null,
+            suggestionIds,
+        }),
+    });
+}
+function reviewTerminalStatus(status) {
+    return (status === "completed" ||
+        status === "completed_with_degradation" ||
+        status === "halted_partial" ||
+        status === "failed");
+}
+async function readTargetMaterialSupport(sessionRoot, executionPlan) {
+    const targetProfilePath = executionPlan?.review_target_profile_path ??
+        path.join(sessionRoot, "execution-preparation", "review-target-profile.yaml");
+    const targetProfile = await readOptionalYaml(targetProfilePath);
+    const profile = targetProfile?.material_profile;
+    if (!profile)
+        return null;
+    return {
+        targetMaterialKind: profile.target_material_kind,
+        supportStatus: profile.support_status,
+        unsupportedReason: profile.unsupported_reason,
+        detectionConfidence: profile.detection.confidence,
+        detectionConfidenceBasis: profile.detection.confidence_basis,
+    };
+}
+async function readEnvironmentWarnings(sessionRoot) {
+    const artifact = await readOptionalYaml(environmentWarningsPath(sessionRoot));
+    return artifact?.warnings ?? [];
+}
+async function writeEnvironmentWarningsFromStderr(args) {
+    const warningLines = args.stderr
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith(REVIEW_RUNNER_WARNING_PREFIX))
+        .map((line) => line.slice(REVIEW_RUNNER_WARNING_PREFIX.length).trim())
+        .filter((line) => line.length > 0);
+    if (warningLines.length === 0)
+        return [];
+    const existing = await readEnvironmentWarnings(args.sessionRoot);
+    const seenMessages = new Set(existing.map((warning) => warning.message));
+    const observedAt = isoNow();
+    const additions = [];
+    for (const [index, message] of warningLines.entries()) {
+        if (seenMessages.has(message))
+            continue;
+        const digest = crypto
+            .createHash("sha256")
+            .update(`${observedAt}\n${index}\n${message}`)
+            .digest("hex")
+            .slice(0, 12);
+        additions.push({
+            warningId: `environment-warning-${digest}`,
+            source: "review_runner_warning",
+            message,
+            fatality: "non_fatal",
+            affectedCapability: "review_execution_observability",
+            outputTrustImpact: "unknown",
+            observedAt,
+        });
+    }
+    const warnings = [...existing, ...additions];
+    if (warnings.length > 0) {
+        await writeYamlDocument(environmentWarningsPath(args.sessionRoot), {
+            schema_version: "1",
+            session_id: basenameSessionId(args.sessionRoot),
+            created_at: observedAt,
+            warnings,
+        });
+    }
+    return warnings;
+}
+function activeUnitsForInitialReview(executionPlan) {
+    const lensIds = (executionPlan?.lens_execution_seats ?? []).map((seat) => seat.lens_id);
+    return lensIds.length > 0
+        ? lensIds.map((lensId) => `lens:${lensId}`)
+        : ["review_execution"];
+}
+function requestedUnitsMatchActive(activeUnits, targetUnits) {
+    if (activeUnits.length === 0)
+        return false;
+    if (!targetUnits || targetUnits.length === 0)
+        return true;
+    const normalizedActive = new Set(activeUnits.flatMap((unit) => {
+        const suffix = unit.includes(":") ? unit.split(":").at(-1) ?? unit : unit;
+        return [unit, suffix];
+    }));
+    return targetUnits.some((unit) => normalizedActive.has(unit));
+}
+async function writeActiveAttemptStarted(args) {
+    const sessionMetadata = await readOptionalYaml(path.join(args.sessionRoot, "session-metadata.yaml"));
+    const artifactRefs = await collectArtifactRefs(args.sessionRoot);
+    const observed = await artifactObservation(artifactRefs);
+    const now = isoNow();
+    const artifact = {
+        schema_version: "1",
+        attempt_id: args.attemptId,
+        attempt_kind: args.attemptKind,
+        session_id: sessionMetadata?.session_id ?? basenameSessionId(args.sessionRoot),
+        session_root: args.sessionRoot,
+        project_root: sessionMetadata?.project_root ?? null,
+        created_at: now,
+        updated_at: now,
+        status: "started",
+        active_units: args.activeUnits,
+        requested_frontier_units: args.requestedFrontierUnits ?? [],
+        run_control: {
+            stale_after_seconds: activeAttemptStaleAfterSeconds(),
+            source_tool: args.sourceTool,
+            request_hash: args.requestHash,
+        },
+        latest_observed_artifact_ref: observed.ref,
+    };
+    await writeYamlDocument(activeAttemptPath(args.sessionRoot), artifact);
+}
+async function updateActiveAttemptTerminal(args) {
+    const attemptPath = activeAttemptPath(args.sessionRoot);
+    const existing = await readOptionalYaml(attemptPath);
+    if (!existing)
+        return;
+    const artifactRefs = await collectArtifactRefs(args.sessionRoot);
+    const observed = await artifactObservation(artifactRefs);
+    await writeYamlDocument(attemptPath, {
+        ...existing,
+        updated_at: isoNow(),
+        status: args.status,
+        latest_observed_artifact_ref: observed.ref,
+        ...(args.errorMessage !== undefined ? { error_message: args.errorMessage } : {}),
+    });
+}
+async function activeAttemptProjection(sessionRoot) {
+    const attemptPath = activeAttemptPath(sessionRoot);
+    const artifact = await readOptionalYaml(attemptPath);
+    if (!artifact)
+        return null;
+    const updatedMs = parseTimestampMs(artifact.updated_at);
+    const secondsSinceUpdated = secondsBetween(Date.now(), updatedMs);
+    const staleAfterSeconds = artifact.run_control?.stale_after_seconds ?? DEFAULT_ACTIVE_ATTEMPT_STALE_AFTER_SECONDS;
+    const isStale = artifact.status === "started" &&
+        secondsSinceUpdated !== null &&
+        secondsSinceUpdated > staleAfterSeconds;
+    return {
+        attemptId: artifact.attempt_id,
+        attemptKind: artifact.attempt_kind,
+        status: artifact.status,
+        sessionId: artifact.session_id,
+        sessionRoot: artifact.session_root,
+        startedAt: artifact.created_at,
+        updatedAt: artifact.updated_at,
+        activeUnits: artifact.active_units ?? [],
+        requestedFrontierUnits: artifact.requested_frontier_units ?? [],
+        latestObservedArtifactRef: artifact.latest_observed_artifact_ref ?? null,
+        staleAfterSeconds,
+        secondsSinceUpdated,
+        isStale,
+        attemptManifestRef: attemptPath,
+    };
+}
+async function buildRunControl(sessionRoot, status) {
+    const activeAttempt = await activeAttemptProjection(sessionRoot);
+    const cancellationRequestRef = await fileExists(reviewCancelRequestPath(sessionRoot))
+        ? reviewCancelRequestPath(sessionRoot)
+        : null;
+    const cancellationRequested = cancellationRequestRef !== null;
+    const alreadyRunning = status === "running" &&
+        activeAttempt?.status === "started" &&
+        !activeAttempt.isStale;
+    const lifecycleState = status === "completed" || status === "completed_with_degradation"
+        ? "completed"
+        : status === "halted_partial"
+            ? "halted"
+            : activeAttempt?.status === "failed"
+                ? "failed_attempt"
+                : activeAttempt?.status === "started" && activeAttempt.isStale
+                    ? "stale_active"
+                    : cancellationRequested
+                        ? "cancellation_requested"
+                        : alreadyRunning
+                            ? "active"
+                            : status === "prepared"
+                                ? "prepared"
+                                : "unknown";
+    const continuationAvailable = status === "prepared" ||
+        status === "halted_partial" ||
+        lifecycleState === "failed_attempt" ||
+        lifecycleState === "stale_active";
+    const cancellationAvailable = alreadyRunning && !cancellationRequested;
+    const statusReason = lifecycleState === "active"
+        ? "review attempt is actively running and can be cancelled"
+        : lifecycleState === "cancellation_requested"
+            ? "cancellation has already been requested and will be observed at a runtime checkpoint"
+            : lifecycleState === "stale_active"
+                ? "active attempt is stale; use review_status evidence before continuing"
+                : lifecycleState === "failed_attempt"
+                    ? "active attempt failed before a stronger terminal execution artifact was written"
+                    : lifecycleState === "prepared"
+                        ? "review is prepared but no worker attempt is active"
+                        : lifecycleState === "halted"
+                            ? "review has halted through execution artifacts"
+                            : lifecycleState === "completed"
+                                ? "review is terminally completed"
+                                : "no actionable run-control state is available";
+    return {
+        activeAttempt,
+        lifecycleState,
+        alreadyRunning,
+        cancellationAvailable,
+        cancellationRequested,
+        cancellationRequestRef,
+        continuationAvailable,
+        retryAvailable: continuationAvailable,
+        retrySemantics: "use_review_continue",
+        hostTimeoutSemantics: "review_continues_under_session",
+        statusReason,
+    };
+}
 function compactSeverityCounts(summary) {
     return [
         `blocker=${summary.severity_counts.blocker}`,
@@ -213,140 +629,6 @@ function buildHaltPresentation(input) {
         input,
     };
 }
-function progressEvent(args) {
-    return {
-        presentation_contract_version: REVIEW_PRESENTATION_CONTRACT_VERSION,
-        event_kind: "mcp_progress",
-        sequence: args.sequence,
-        generated_at: isoNow(),
-        source: args.source,
-        stage: args.stage,
-        session_root: args.sessionRoot,
-        message: args.message,
-        progress: {
-            current: args.current,
-            total: args.total ?? 100,
-            ...(args.exactStep !== undefined ? { exact_step: args.exactStep } : {}),
-            ...(args.exactTotal !== undefined ? { exact_total: args.exactTotal } : {}),
-            ...(args.label !== undefined ? { label: args.label } : {}),
-        },
-    };
-}
-function progressUnitsForInvokeStep(step) {
-    switch (step) {
-        case 1:
-            return 5;
-        case 2:
-            return 10;
-        case 3:
-            return 90;
-        default:
-            return 0;
-    }
-}
-function progressUnitsForRuntimeStep(step, total) {
-    if (total <= 0)
-        return 10;
-    return Math.min(89, 10 + Math.round((step / total) * 75));
-}
-function parseSessionRootLine(projectRoot, line) {
-    const match = /^\s*session_root:\s+(.+?)\s*$/.exec(line);
-    if (!match?.[1])
-        return null;
-    const rawSessionRoot = match[1];
-    return path.isAbsolute(rawSessionRoot)
-        ? rawSessionRoot
-        : path.resolve(projectRoot, rawSessionRoot);
-}
-function consoleLineProgressEvent(args) {
-    const plannedSessionRoot = parseSessionRootLine(args.projectRoot, args.line);
-    if (plannedSessionRoot) {
-        return {
-            sessionRoot: plannedSessionRoot,
-            event: progressEvent({
-                sequence: args.sequence,
-                source: "review_invoke_console",
-                stage: "session_planned",
-                sessionRoot: plannedSessionRoot,
-                message: `Review session planned at ${plannedSessionRoot}.`,
-                current: 1,
-                label: "session planned",
-            }),
-        };
-    }
-    if (args.line.trim() === "[review start]") {
-        return {
-            sessionRoot: args.sessionRoot,
-            event: progressEvent({
-                sequence: args.sequence,
-                source: "review_invoke_console",
-                stage: "start_preview",
-                sessionRoot: args.sessionRoot,
-                message: "Review start preview generated.",
-                current: 0,
-                label: "start preview",
-            }),
-        };
-    }
-    const invokeStepMatch = /^\[review invoke\] step (\d+)\/3\s+(.+?)\s*$/.exec(args.line);
-    if (invokeStepMatch?.[1] && invokeStepMatch[2]) {
-        const step = Number.parseInt(invokeStepMatch[1], 10);
-        const label = invokeStepMatch[2];
-        return {
-            sessionRoot: args.sessionRoot,
-            event: progressEvent({
-                sequence: args.sequence,
-                source: "review_invoke_console",
-                stage: "invoke_step",
-                sessionRoot: args.sessionRoot,
-                message: label,
-                current: progressUnitsForInvokeStep(step),
-                exactStep: step,
-                exactTotal: 3,
-                label,
-            }),
-        };
-    }
-    const runtimeStepMatch = /^\[review progress\]\s+(\d+)\/(\d+)\s+(.+?)\s*$/.exec(args.line);
-    if (runtimeStepMatch?.[1] && runtimeStepMatch[2] && runtimeStepMatch[3]) {
-        const step = Number.parseInt(runtimeStepMatch[1], 10);
-        const total = Number.parseInt(runtimeStepMatch[2], 10);
-        const label = runtimeStepMatch[3];
-        return {
-            sessionRoot: args.sessionRoot,
-            event: progressEvent({
-                sequence: args.sequence,
-                source: "review_invoke_console",
-                stage: "runtime_step",
-                sessionRoot: args.sessionRoot,
-                message: label,
-                current: progressUnitsForRuntimeStep(step, total),
-                exactStep: step,
-                exactTotal: total,
-                label,
-            }),
-        };
-    }
-    const completedMatch = /^\[review invoke\] completed 3\/3\s+(.+?)\s*$/.exec(args.line);
-    if (completedMatch?.[1]) {
-        const label = completedMatch[1];
-        return {
-            sessionRoot: args.sessionRoot,
-            event: progressEvent({
-                sequence: args.sequence,
-                source: "review_invoke_console",
-                stage: "completed",
-                sessionRoot: args.sessionRoot,
-                message: label,
-                current: 98,
-                exactStep: 3,
-                exactTotal: 3,
-                label,
-            }),
-        };
-    }
-    return null;
-}
 function generatedFromArtifactRefs(artifactRefs, keys = PRESENTATION_SOURCE_REF_KEYS) {
     const refs = {};
     for (const key of keys) {
@@ -462,6 +744,241 @@ function livenessSummary(args) {
             return `Review is still active at ${args.currentLabel ?? "unknown step"}, but no artifact change has been observed for the stale threshold.${active}${lastArtifact}${since}`;
     }
 }
+const RUNTIME_UNIT_STALE_AFTER_SECONDS = 300;
+async function observeFile(filePath) {
+    if (!filePath)
+        return { exists: false, size: 0, mtimeMs: null };
+    try {
+        const stat = await fs.stat(filePath);
+        return {
+            exists: true,
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+    catch {
+        return { exists: false, size: 0, mtimeMs: null };
+    }
+}
+function allReviewUnitResults(executionResult) {
+    if (!executionResult)
+        return [];
+    return [
+        ...executionResult.lens_execution_results,
+        ...(executionResult.issue_artifact_execution_results ?? []),
+        ...(executionResult.deliberation_execution_results ?? []),
+        ...(executionResult.synthesize_execution_result
+            ? [executionResult.synthesize_execution_result]
+            : []),
+    ];
+}
+function parseRuntimeLogHeading(rawHeading) {
+    const match = /^##\s+(.+?)\s+\|\s+(.+?)\s*$/.exec(rawHeading.trim());
+    if (!match?.[2])
+        return null;
+    return {
+        at: match[1] ?? null,
+        title: match[2],
+    };
+}
+function bodyScalar(body, key) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`^${escaped}:\\s*(.+?)\\s*$`, "m").exec(body);
+    return match?.[1] ?? null;
+}
+function parseAttempt(body) {
+    const raw = bodyScalar(body, "attempt");
+    if (!raw)
+        return null;
+    const match = /^(\d+)/.exec(raw.trim());
+    if (!match?.[1])
+        return null;
+    const parsed = Number.parseInt(match[1], 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function runtimeSignalFromEntry(entry) {
+    const [headingLine, ...bodyLines] = entry.split(/\r?\n/);
+    if (!headingLine)
+        return null;
+    const heading = parseRuntimeLogHeading(headingLine);
+    if (!heading)
+        return null;
+    const body = bodyLines.join("\n");
+    const title = heading.title;
+    const titlePatterns = [
+        {
+            kind: "started",
+            pattern: /^runner dispatch started: (.+?)\s*$/,
+            summary: "runner dispatch started",
+        },
+        {
+            kind: "retry",
+            pattern: /^runner dispatch retry: (.+?)\s*$/,
+            summary: "runner dispatch retry",
+        },
+        {
+            kind: "completed",
+            pattern: /^runner (?:nested )?dispatch completed: (.+?)\s*$/,
+            summary: "runner dispatch completed",
+        },
+        {
+            kind: "failed",
+            pattern: /^(?:lens|deliberation|issue_artifact|synthesize) failure: (.+?)\s*$/,
+            summary: "runner dispatch failed",
+        },
+    ];
+    for (const candidate of titlePatterns) {
+        const match = candidate.pattern.exec(title);
+        if (!match?.[1])
+            continue;
+        const atMs = parseTimestampMs(heading.at);
+        return {
+            unitId: match[1],
+            kind: candidate.kind,
+            summary: candidate.summary,
+            at: heading.at,
+            atMs,
+            attempt: candidate.kind === "retry" ? parseAttempt(body) : null,
+            failureMessage: candidate.kind === "failed" ? bodyScalar(body, "message") : null,
+        };
+    }
+    return null;
+}
+async function runtimeLogSignalsByUnit(errorLogPath) {
+    const text = await readOptionalText(errorLogPath);
+    const signals = new Map();
+    if (!text)
+        return signals;
+    for (const rawEntry of text.split(/\n(?=## )/)) {
+        const signal = runtimeSignalFromEntry(rawEntry.trimEnd());
+        if (!signal)
+            continue;
+        signals.set(signal.unitId, [...(signals.get(signal.unitId) ?? []), signal]);
+    }
+    return signals;
+}
+function latestRuntimeSignal(signals) {
+    if (signals.length === 0)
+        return null;
+    return signals.reduce((latest, signal) => {
+        const latestMs = latest.atMs ?? -1;
+        const signalMs = signal.atMs ?? -1;
+        return signalMs >= latestMs ? signal : latest;
+    });
+}
+function runtimeSignalCount(signals, kind) {
+    return signals.filter((signal) => signal.kind === kind).length;
+}
+function runtimeUnitAlias(unitKind, unitId) {
+    if (unitKind === "lens")
+        return `lens:${unitId}`;
+    if (unitKind === "deliberation" && unitId.startsWith("deliberation-")) {
+        return `deliberation:${unitId.replace(/^deliberation-/, "")}`;
+    }
+    return unitId;
+}
+function runtimeUnitStepId(unitKind) {
+    if (unitKind === "lens")
+        return "lens_dispatch";
+    if (unitKind === "deliberation")
+        return "lens_deliberation_responses";
+    return null;
+}
+async function deriveRuntimeUnitProgress(args) {
+    const executionPlan = args.executionPlan;
+    if (!executionPlan)
+        return [];
+    const signalsByUnit = await runtimeLogSignalsByUnit(executionPlan.error_log_path);
+    const terminalResultsByUnit = new Map(allReviewUnitResults(args.executionResult).map((result) => [
+        result.unit_id,
+        result,
+    ]));
+    const lensUnits = executionPlan.lens_execution_seats.map((seat) => {
+        const packetPath = executionPlan.lens_prompt_packet_seats.find((packetSeat) => packetSeat.lens_id === seat.lens_id)?.packet_path ?? null;
+        return {
+            unitId: seat.lens_id,
+            unitKind: "lens",
+            packetPath,
+            outputPath: seat.output_path,
+            runningLogRef: path.join(path.dirname(seat.output_path), `.${seat.lens_id}.running.log`),
+        };
+    });
+    const projections = [];
+    for (const unit of lensUnits) {
+        const output = await observeFile(unit.outputPath);
+        const runningLog = await observeFile(unit.runningLogRef);
+        const signals = signalsByUnit.get(unit.unitId) ?? [];
+        const latestSignal = latestRuntimeSignal(signals);
+        const terminalResult = terminalResultsByUnit.get(unit.unitId);
+        const retryCount = runtimeSignalCount(signals, "retry");
+        const hasStarted = signals.some((signal) => signal.kind === "started") ||
+            runningLog.exists;
+        const attemptCount = Math.max(terminalResult ? 1 : 0, hasStarted ? retryCount + 1 : 0);
+        let latestSignalName = latestSignal?.summary ?? null;
+        let latestSignalAt = latestSignal?.at ?? null;
+        let latestSignalMs = latestSignal?.atMs ?? null;
+        if (runningLog.exists &&
+            runningLog.mtimeMs !== null &&
+            (latestSignalMs === null || runningLog.mtimeMs > latestSignalMs)) {
+            latestSignalName = "running log updated";
+            latestSignalAt = isoFromTimestamp(runningLog.mtimeMs);
+            latestSignalMs = runningLog.mtimeMs;
+        }
+        let status = "pending";
+        let failureMessage = latestSignal?.failureMessage ?? null;
+        if (terminalResult?.status === "failed") {
+            status = "failed";
+            latestSignalName = "terminal execution result failed";
+            latestSignalAt = terminalResult.completed_at;
+            latestSignalMs = parseTimestampMs(terminalResult.completed_at);
+            failureMessage = terminalResult.failure_message ?? failureMessage;
+        }
+        else if (terminalResult?.status === "completed" ||
+            latestSignal?.kind === "completed" ||
+            (output.exists && output.size > 0)) {
+            status = "completed";
+            if (!latestSignalName || (output.mtimeMs !== null && output.mtimeMs > (latestSignalMs ?? -1))) {
+                latestSignalName = "output file present";
+                latestSignalAt = output.mtimeMs === null ? null : isoFromTimestamp(output.mtimeMs);
+                latestSignalMs = output.mtimeMs;
+            }
+        }
+        else if (latestSignal?.kind === "failed") {
+            status = "failed";
+            failureMessage = latestSignal.failureMessage;
+        }
+        else if (latestSignal?.kind === "retry") {
+            const seconds = secondsBetween(args.nowMs, latestSignalMs);
+            status =
+                seconds !== null && seconds > RUNTIME_UNIT_STALE_AFTER_SECONDS
+                    ? "running_stale"
+                    : "retrying";
+        }
+        else if (hasStarted) {
+            const seconds = secondsBetween(args.nowMs, latestSignalMs);
+            status =
+                seconds !== null && seconds > RUNTIME_UNIT_STALE_AFTER_SECONDS
+                    ? "running_stale"
+                    : "running";
+        }
+        projections.push({
+            unitId: unit.unitId,
+            publicAlias: runtimeUnitAlias(unit.unitKind, unit.unitId),
+            unitKind: unit.unitKind,
+            progressStepId: runtimeUnitStepId(unit.unitKind),
+            status,
+            packetPath: unit.packetPath,
+            outputPath: unit.outputPath,
+            runningLogRef: runningLog.exists ? unit.runningLogRef : null,
+            latestSignal: latestSignalName,
+            latestSignalAt,
+            secondsSinceLatestSignal: secondsBetween(args.nowMs, latestSignalMs),
+            attemptCount,
+            failureMessage,
+        });
+    }
+    return projections;
+}
 async function existingSeatIds(seats) {
     const existing = [];
     for (const seat of seats ?? []) {
@@ -477,7 +994,7 @@ async function completedProgressStepIds(params) {
     const completed = [];
     if (params.executionPlan)
         completed.push("manifest_validation");
-    const plannedLensIds = params.executionPlan?.lens_execution_seats.map((seat) => seat.lens_id) ?? [];
+    const plannedLensIds = (params.executionPlan?.lens_execution_seats ?? []).map((seat) => seat.lens_id);
     const completedLensIds = await existingSeatIds(params.executionPlan?.lens_execution_seats);
     const allPlannedLensesCompleted = plannedLensIds.length > 0 && completedLensIds.length >= plannedLensIds.length;
     if (allPlannedLensesCompleted || params.artifactRefs.lens_completion_barrier) {
@@ -496,8 +1013,7 @@ async function completedProgressStepIds(params) {
     if (params.artifactRefs.deliberation_plan)
         completed.push("deliberation_plan");
     const deliberationIds = await existingSeatIds(params.executionPlan?.lens_deliberation_prompt_packet_seats);
-    const plannedDeliberationIds = params.executionPlan?.lens_deliberation_prompt_packet_seats.map((seat) => seat.lens_id) ??
-        [];
+    const plannedDeliberationIds = (params.executionPlan?.lens_deliberation_prompt_packet_seats ?? []).map((seat) => seat.lens_id);
     if ((plannedDeliberationIds.length > 0 &&
         deliberationIds.length >= plannedDeliberationIds.length) ||
         params.artifactRefs.deliberation_output) {
@@ -531,14 +1047,13 @@ async function activeUnits(params) {
         return typeof unitId === "string" && unitId.length > 0 ? [unitId] : [];
     }
     if (params.currentStepId === "lens_dispatch") {
-        const planned = params.executionPlan?.lens_execution_seats.map((seat) => seat.lens_id) ?? [];
+        const planned = (params.executionPlan?.lens_execution_seats ?? []).map((seat) => seat.lens_id);
         const completed = new Set(await existingSeatIds(params.executionPlan?.lens_execution_seats));
         const pending = planned.filter((lensId) => !completed.has(lensId));
         return (pending.length > 0 ? pending : planned).map((lensId) => `lens:${lensId}`);
     }
     if (params.currentStepId === "lens_deliberation_responses") {
-        const planned = params.executionPlan?.lens_deliberation_prompt_packet_seats.map((seat) => seat.lens_id) ??
-            [];
+        const planned = (params.executionPlan?.lens_deliberation_prompt_packet_seats ?? []).map((seat) => seat.lens_id);
         const completed = new Set(await existingSeatIds(params.executionPlan?.lens_deliberation_prompt_packet_seats));
         return planned
             .filter((lensId) => !completed.has(lensId))
@@ -665,6 +1180,24 @@ async function buildReviewStatusPresentationInput(params) {
     const completedStatus = params.status === "completed" || params.status === "completed_with_degradation";
     const sessionStartMs = parseTimestampMs(params.executionResult?.execution_started_at) ??
         parseTimestampMs(sessionMetadata?.created_at);
+    const unitProgress = await deriveRuntimeUnitProgress({
+        executionPlan: params.executionPlan,
+        executionResult: params.executionResult,
+        nowMs,
+    });
+    const runtimeActiveUnits = unitProgress
+        .filter((unit) => unit.status === "running" ||
+        unit.status === "retrying" ||
+        unit.status === "running_stale")
+        .map((unit) => unit.publicAlias);
+    const progressActiveUnits = currentStepId === "lens_dispatch" && unitProgress.length > 0
+        ? runtimeActiveUnits
+        : await activeUnits({
+            status: params.status,
+            currentStepId,
+            executionPlan: params.executionPlan,
+            executionResult: params.executionResult,
+        });
     const progress = {
         current_step: completedStatus
             ? totalSteps
@@ -688,12 +1221,7 @@ async function buildReviewStatusPresentationInput(params) {
                 params.artifactRefs.execution_plan ? "execution_plan" : null,
             ].filter((step) => step !== null)
             : completedSteps,
-        active_units: await activeUnits({
-            status: params.status,
-            currentStepId,
-            executionPlan: params.executionPlan,
-            executionResult: params.executionResult,
-        }),
+        active_units: progressActiveUnits,
         pending_units: completedStatus
             ? []
             : params.status === "prepared"
@@ -712,6 +1240,7 @@ async function buildReviewStatusPresentationInput(params) {
                     : currentStepId
                         ? `next ${stepById(currentStepId).label} artifact or timeout`
                         : null,
+        unit_progress: unitProgress,
     };
     const completedLensIds = await existingSeatIds(params.executionPlan?.lens_execution_seats);
     const halt = haltPresentation({
@@ -744,6 +1273,8 @@ async function buildReviewStatusPresentationInput(params) {
             secondsSinceLastArtifact,
         }),
     };
+    const runControl = await buildRunControl(params.sessionRoot, params.status);
+    const targetMaterialSupport = await readTargetMaterialSupport(params.sessionRoot, params.executionPlan);
     return {
         presentation_contract_version: REVIEW_PRESENTATION_CONTRACT_VERSION,
         presentation_kind: "progress",
@@ -762,6 +1293,9 @@ async function buildReviewStatusPresentationInput(params) {
         }),
         result_classification_summary: resultClassificationSummary,
         halt,
+        run_control: runControl,
+        target_material_support: targetMaterialSupport,
+        environment_warnings: await readEnvironmentWarnings(params.sessionRoot),
     };
 }
 async function buildPreparedOpeningBriefInput(sessionRoot, executionPlan) {
@@ -798,6 +1332,7 @@ async function buildPreparedOpeningBriefInput(sessionRoot, executionPlan) {
                 resolved_host_runtime: binding.resolved_host_runtime,
                 boundary_policy: binding.boundary_policy,
                 effective_boundary_state: binding.effective_boundary_state,
+                binding_notes: binding.binding_notes ?? [],
             }
             : null,
         review_target_profile: reviewTargetProfile
@@ -825,60 +1360,328 @@ async function buildPreparedOpeningBriefInput(sessionRoot, executionPlan) {
         },
     };
 }
-function parseReviewInvokeOutput(stdout) {
-    for (const line of [...stdout].reverse()) {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith("{"))
+async function buildReviewRunHandle(args) {
+    const artifactRefs = await collectArtifactRefs(args.sessionRoot);
+    const executionPlan = await readOptionalYaml(path.join(args.sessionRoot, "execution-plan.yaml"));
+    const metadata = await readOptionalYaml(path.join(args.sessionRoot, "session-metadata.yaml"));
+    const interpretation = await readOptionalYaml(path.join(args.sessionRoot, "interpretation.yaml"));
+    const binding = await readOptionalYaml(path.join(args.sessionRoot, "binding.yaml"));
+    const targetProfile = await readOptionalYaml(executionPlan?.review_target_profile_path ??
+        path.join(args.sessionRoot, "execution-preparation", "review-target-profile.yaml"));
+    const requestHash = args.requestHash ??
+        requestHashFromArtifacts({ metadata, interpretation, binding });
+    const normalizedDomain = binding?.resolved_session_domain ??
+        targetProfile?.domain ??
+        (metadata?.requested_domain_token
+            ? normalizeDomainValue(metadata.requested_domain_token)
+            : null);
+    return {
+        schemaVersion: "1",
+        sessionId: metadata?.session_id ?? executionPlan?.session_id ?? basenameSessionId(args.sessionRoot),
+        sessionRoot: args.sessionRoot,
+        invocationId: args.invocationId,
+        status: args.status,
+        projectRoot: metadata?.project_root ?? null,
+        target: {
+            requestedTarget: metadata?.requested_target ?? targetProfile?.requested_target ?? null,
+            targetScopeKind: targetProfile?.target_scope_kind ?? null,
+            targetMaterialKind: targetProfile?.target_material_kind ?? null,
+        },
+        domain: domainTokenResolution({
+            requestedToken: metadata?.requested_domain_token ?? null,
+            normalizedDomain,
+        }),
+        artifactRefs: {
+            sessionMetadata: artifactRefs.session_metadata ?? null,
+            executionPlan: artifactRefs.execution_plan ?? null,
+            reviewRunManifest: artifactRefs.review_run_manifest ?? null,
+            executionResult: artifactRefs.execution_result ?? null,
+            finalOutput: artifactRefs.final_output ?? null,
+            reviewRecord: artifactRefs.review_record ?? null,
+        },
+        requestHash,
+        pollAfterSeconds: reviewTerminalStatus(args.status) ? null : 5,
+    };
+}
+async function buildRunningReviewRunResult(args) {
+    const sessionRoot = path.resolve(args.sessionRoot);
+    const artifactRefs = await collectArtifactRefs(sessionRoot);
+    const failures = await collectStructuredFailures(sessionRoot);
+    const executionPlan = await readOptionalYaml(path.join(sessionRoot, "execution-plan.yaml"));
+    const executionResult = await readOptionalYaml(path.join(sessionRoot, "execution-result.yaml"));
+    const reviewRecord = await readOptionalReviewRecord(path.join(sessionRoot, "review-record.yaml"));
+    const progressInput = await buildReviewStatusPresentationInput({
+        sessionRoot,
+        status: "running",
+        artifactRefs,
+        executionPlan,
+        executionResult,
+        reviewRecord,
+    });
+    const runHandle = await buildReviewRunHandle({
+        sessionRoot,
+        status: "running",
+        invocationId: args.invocationId,
+        ...(args.requestHash !== undefined ? { requestHash: args.requestHash } : {}),
+    });
+    const llmPresentation = {
+        progress: buildProgressPresentation(progressInput),
+    };
+    if (executionPlan) {
+        llmPresentation.openingBrief = buildOpeningBriefPresentation(await buildPreparedOpeningBriefInput(sessionRoot, executionPlan));
+    }
+    return {
+        sessionId: runHandle.sessionId,
+        sessionRoot,
+        status: "running",
+        finalOutputPath: executionPlan?.final_output_path ?? path.join(sessionRoot, "final-output.md"),
+        reviewRecordPath: executionPlan?.review_record_path ?? path.join(sessionRoot, "review-record.yaml"),
+        executionResultPath: executionPlan?.execution_result_path ?? path.join(sessionRoot, "execution-result.yaml"),
+        reviewRunManifestPath: path.join(sessionRoot, "review-run-manifest.yaml"),
+        deliberationStatus: null,
+        participatingLensIds: [],
+        degradedLensIds: [],
+        artifactRefs,
+        ...failures,
+        routeVisibility: await buildReviewRouteVisibilityFromSession(sessionRoot),
+        llmPresentation,
+        runHandle,
+        runControl: progressInput.run_control,
+        targetMaterialSupport: progressInput.target_material_support,
+        environmentWarnings: progressInput.environment_warnings,
+    };
+}
+async function collectArtifactRefs(sessionRoot) {
+    return collectReviewInvocationArtifactRefs(sessionRoot);
+}
+async function buildPipelineExecutionLedgerIfPossible(args) {
+    if (!args.executionPlan)
+        return undefined;
+    const reviewRunManifest = await readOptionalYaml(path.join(args.sessionRoot, "review-run-manifest.yaml"));
+    const lensCompletionBarrier = await readOptionalYaml(path.join(args.sessionRoot, "lens-completion-barrier.yaml"));
+    try {
+        return await buildReviewPipelineExecutionLedger({
+            sessionRoot: args.sessionRoot,
+            artifactRefs: args.artifactRefs,
+            executionPlan: args.executionPlan,
+            executionResult: args.executionResult,
+            reviewRunManifest,
+            lensCompletionBarrier,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function workerExecutorToRealization(workerExecutor) {
+    if (workerExecutor === "mock")
+        return "mock";
+    if (workerExecutor === "codex")
+        return "codex";
+    if (workerExecutor === "direct_call")
+        return "ts_inline_http";
+    return null;
+}
+function workerExecutorFromRealization(realization) {
+    if (realization === "mock")
+        return "mock";
+    if (realization === "codex")
+        return "codex";
+    return "direct_call";
+}
+function reviewExecutionHostFromRuntime(hostRuntime, workerExecutor) {
+    if (workerExecutor === "mock")
+        return "standalone";
+    if (workerExecutor === "codex")
+        return "codex";
+    if (hostRuntime === "openai" ||
+        hostRuntime === "anthropic" ||
+        hostRuntime === "grok" ||
+        hostRuntime === "lmstudio") {
+        return hostRuntime;
+    }
+    return "openai";
+}
+function reviewExecutionProfileFromManifest(manifest) {
+    const profile = manifest?.review_execution_profile;
+    const route = profile?.runtime_route;
+    const workerExecutor = route?.worker_executor;
+    if (workerExecutor !== "mock" &&
+        workerExecutor !== "codex" &&
+        workerExecutor !== "direct_call") {
+        return undefined;
+    }
+    if (profile?.mode !== "main-workers" &&
+        profile?.mode !== "nested-workers") {
+        return undefined;
+    }
+    if (profile.teamlead === null ||
+        typeof profile.teamlead !== "object" ||
+        profile.lens === null ||
+        typeof profile.lens !== "object" ||
+        profile.synthesize === null ||
+        typeof profile.synthesize !== "object" ||
+        typeof profile.deliberation !== "string") {
+        return undefined;
+    }
+    const host = reviewExecutionHostFromRuntime(route?.host_runtime, workerExecutor);
+    const runtimeProvider = typeof route?.runtime_provider === "string" &&
+        route.runtime_provider !== "mock" &&
+        route.runtime_provider !== "codex"
+        ? route.runtime_provider
+        : undefined;
+    const authMode = route?.auth_mode === "api_key" ||
+        route?.auth_mode === "oauth" ||
+        route?.auth_mode === "local"
+        ? route.auth_mode
+        : undefined;
+    const reconstructed = {
+        mode: profile.mode,
+        teamlead: profile.teamlead,
+        lens: profile.lens,
+        synthesize: profile.synthesize,
+        deliberation: profile.deliberation,
+        worker_executor: workerExecutor,
+        host,
+        trace: Array.isArray(profile.trace)
+            ? profile.trace.filter((item) => typeof item === "string")
+            : [],
+    };
+    if (runtimeProvider) {
+        reconstructed.provider =
+            runtimeProvider;
+    }
+    if (authMode) {
+        reconstructed.auth =
+            authMode;
+    }
+    if (typeof profile.model === "string")
+        reconstructed.model = profile.model;
+    if (typeof profile.effort === "string")
+        reconstructed.effort = profile.effort;
+    if (typeof profile.service_tier === "string") {
+        reconstructed.service_tier = profile.service_tier;
+    }
+    if (typeof profile.base_url === "string") {
+        reconstructed.base_url = profile.base_url;
+    }
+    return reconstructed;
+}
+function reviewExecutionProfileFromActorProfiles(args) {
+    const profiles = args.actorProfiles?.profiles ?? [];
+    const teamlead = profiles.find((profile) => profile.actor_kind === "teamlead");
+    const lens = profiles.find((profile) => profile.actor_kind === "lens");
+    const synthesize = profiles.find((profile) => profile.actor_kind === "synthesize");
+    if (!teamlead || !lens || !synthesize)
+        return undefined;
+    const workerExecutor = workerExecutorFromRealization(args.executorRealization);
+    const host = reviewExecutionHostFromRuntime(teamlead.host_runtime, workerExecutor);
+    const runtimeProvider = teamlead.runtime_provider &&
+        teamlead.runtime_provider !== "mock" &&
+        teamlead.runtime_provider !== "codex"
+        ? teamlead.runtime_provider
+        : undefined;
+    const reconstructed = {
+        mode: "main-workers",
+        teamlead: { seat: teamlead.seat, llm: "inherit" },
+        lens: { seat: lens.seat, llm: "inherit" },
+        synthesize: { seat: synthesize.seat, llm: "inherit" },
+        deliberation: "controlled-lens-deliberation",
+        worker_executor: workerExecutor,
+        host,
+        trace: ["reconstructed_from_actor_invocation_profiles_for_continuation"],
+    };
+    if (runtimeProvider) {
+        reconstructed.provider =
+            runtimeProvider;
+    }
+    if (teamlead.auth_mode === "api_key" ||
+        teamlead.auth_mode === "oauth" ||
+        teamlead.auth_mode === "local") {
+        reconstructed.auth =
+            teamlead.auth_mode;
+    }
+    if (teamlead.model)
+        reconstructed.model = teamlead.model;
+    if (teamlead.effort)
+        reconstructed.effort = teamlead.effort;
+    if (teamlead.service_tier)
+        reconstructed.service_tier = teamlead.service_tier;
+    if (teamlead.base_url)
+        reconstructed.base_url = teamlead.base_url;
+    return reconstructed;
+}
+function executorRealizationFromManifest(manifest) {
+    return workerExecutorToRealization(manifest?.review_execution_profile?.runtime_route?.worker_executor);
+}
+function continuationAttemptId() {
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..+$/, "Z");
+    return `${timestamp}-${crypto.randomUUID().slice(0, 8)}`;
+}
+async function copySupersededArtifacts(args) {
+    const backupRoot = path.join(args.attemptRoot, "superseded-artifacts");
+    const backups = [];
+    for (const [index, sourceRef] of args.artifactRefs.entries()) {
+        if (!(await fileExists(sourceRef)))
             continue;
+        await fs.mkdir(backupRoot, { recursive: true });
+        const backupRef = path.join(backupRoot, `${String(index + 1).padStart(3, "0")}-${path.basename(sourceRef)}`);
+        await fs.copyFile(sourceRef, backupRef);
+        backups.push({ sourceRef, backupRef });
+    }
+    return backups;
+}
+async function restoreSupersededArtifacts(backups) {
+    const restores = [];
+    for (const backup of backups) {
         try {
-            return JSON.parse(trimmed);
+            await fs.mkdir(path.dirname(backup.sourceRef), { recursive: true });
+            await fs.copyFile(backup.backupRef, backup.sourceRef);
+            restores.push({ ...backup, restored: true });
         }
-        catch {
-            // Keep looking: progress messages are not JSON.
+        catch (error) {
+            restores.push({
+                ...backup,
+                restored: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
         }
     }
-    throw new Error("review invocation completed without a structured JSON result.");
+    return restores;
 }
-function isReviewInvokeShape(value) {
-    if (value === null || typeof value !== "object")
-        return false;
-    const reviewResult = value.review_result;
-    return reviewResult !== null && typeof reviewResult === "object";
+function continuationSessionArtifactRefs(args) {
+    return [
+        args.executionPlan.execution_result_path,
+        path.join(args.sessionRoot, "review-run-manifest.yaml"),
+        path.join(args.sessionRoot, "degradation-summary.yaml"),
+        args.executionPlan.error_log_path,
+        args.executionPlan.synthesis_output_path,
+        args.executionPlan.deliberation_output_path,
+        args.executionPlan.final_output_path,
+        args.executionPlan.review_record_path,
+    ];
 }
-async function collectArtifactRefs(sessionRoot) {
-    const candidates = {
-        session_metadata: path.join(sessionRoot, "session-metadata.yaml"),
-        interpretation: path.join(sessionRoot, "interpretation.yaml"),
-        binding: path.join(sessionRoot, "binding.yaml"),
-        execution_plan: path.join(sessionRoot, "execution-plan.yaml"),
-        execution_result: path.join(sessionRoot, "execution-result.yaml"),
-        actor_invocation_profiles: path.join(sessionRoot, "execution-preparation", "actor-invocation-profiles.yaml"),
-        actor_consumer_bindings: path.join(sessionRoot, "execution-preparation", "actor-consumer-bindings.yaml"),
-        domain_binding: path.join(sessionRoot, "execution-preparation", "domain-binding.yaml"),
-        review_value_alignment_criteria: path.join(sessionRoot, "execution-preparation", "review-value-alignment-criteria.yaml"),
-        review_target_profile: path.join(sessionRoot, "execution-preparation", "review-target-profile.yaml"),
-        review_context_manifest: path.join(sessionRoot, "execution-preparation", "review-context-manifest.yaml"),
-        lens_completion_barrier: path.join(sessionRoot, "lens-completion-barrier.yaml"),
-        finding_ledger: path.join(sessionRoot, "finding-ledger.yaml"),
-        finding_relation_graph: path.join(sessionRoot, "finding-relation-graph.yaml"),
-        issue_ledger: path.join(sessionRoot, "issue-ledger.yaml"),
-        issue_stance_matrix: path.join(sessionRoot, "issue-stance-matrix.yaml"),
-        deliberation_plan: path.join(sessionRoot, "deliberation-plan.yaml"),
-        problem_framing: path.join(sessionRoot, "problem-framing.yaml"),
-        deliberation_output: path.join(sessionRoot, "deliberation.md"),
-        synthesis_output: path.join(sessionRoot, "synthesis.md"),
-        review_run_manifest: path.join(sessionRoot, "review-run-manifest.yaml"),
-        degradation_summary: path.join(sessionRoot, "degradation-summary.yaml"),
-        error_log: path.join(sessionRoot, "error-log.md"),
-        final_output: path.join(sessionRoot, "final-output.md"),
-        review_record: path.join(sessionRoot, "review-record.yaml"),
-    };
-    const entries = [];
-    for (const [key, filePath] of Object.entries(candidates)) {
-        if (await fileExists(filePath))
-            entries.push([key, filePath]);
+async function resolveContinuationRequestText(args) {
+    if (typeof args.requestText === "string" && args.requestText.trim().length > 0) {
+        return args.requestText;
     }
-    return Object.fromEntries(entries);
+    const reviewRecord = await readOptionalReviewRecord(path.join(args.sessionRoot, "review-record.yaml"));
+    if (reviewRecord?.request_text)
+        return reviewRecord.request_text;
+    const interpretation = await readOptionalYaml(path.join(args.sessionRoot, "interpretation.yaml"));
+    if (interpretation?.intent_summary)
+        return interpretation.intent_summary;
+    const targetProfile = await readOptionalYaml(path.join(args.sessionRoot, "execution-preparation", "review-target-profile.yaml"));
+    if (targetProfile?.review_intent_summary) {
+        return targetProfile.review_intent_summary;
+    }
+    const metadata = await readOptionalYaml(path.join(args.sessionRoot, "session-metadata.yaml"));
+    return metadata?.requested_target
+        ? `Continue review for ${metadata.requested_target}`
+        : "Continue review";
 }
 async function directoryHasMarkdownFiles(directoryPath) {
     try {
@@ -934,7 +1737,7 @@ async function listDomainDirs(root) {
     try {
         const entries = await fs.readdir(root, { withFileTypes: true });
         return entries
-            .filter((entry) => entry.isDirectory())
+            .filter((entry) => entry.isDirectory() && !isDeprecatedDomainAlias(entry.name))
             .map((entry) => entry.name)
             .sort();
     }
@@ -944,10 +1747,10 @@ async function listDomainDirs(root) {
 }
 export function createOntoReviewCoreApi(options = {}) {
     const ontoHome = resolveRequiredOntoHome(options.ontoHome);
-    return {
+    const api = {
         async prepareReview(request) {
-            const argv = appendCommonReviewArgs([], request, ontoHome);
-            const { result } = await withCapturedConsole(() => reviewPrepareOnly(argv));
+            await validateRequestedDomainForDispatch(request, ontoHome);
+            const result = await prepareReviewInvocationRequest(request, { ontoHome });
             const sessionRoot = path.resolve(result.session_root);
             const executionPlan = await readYamlDocument(path.join(sessionRoot, "execution-plan.yaml"));
             const openingBriefInput = await buildPreparedOpeningBriefInput(sessionRoot, executionPlan);
@@ -962,9 +1765,17 @@ export function createOntoReviewCoreApi(options = {}) {
             };
         },
         async runReview(request) {
-            const argv = appendCommonReviewArgs(["--no-watch"], request, ontoHome);
+            await validateRequestedDomainForDispatch(request, ontoHome);
+            const requestHash = requestHashForReviewInput(request);
+            const invocationId = `initial-${continuationAttemptId()}`;
             let progressSequence = 0;
             let observedSessionRoot = null;
+            let sessionRootResolved = false;
+            let activeAttemptWrite = null;
+            let resolveSessionRoot = () => { };
+            const sessionRootSeen = new Promise((resolve) => {
+                resolveSessionRoot = resolve;
+            });
             const emitProgress = (event) => {
                 const observer = request.progressObserver;
                 if (!observer)
@@ -983,133 +1794,541 @@ export function createOntoReviewCoreApi(options = {}) {
                     // Progress notifications are transport-only and must not affect review execution.
                 }
             };
-            const captureObserver = request.progressObserver
-                ? {
-                    stdout: (text) => {
-                        for (const line of text.split(/\r?\n/)) {
-                            const parsed = consoleLineProgressEvent({
-                                line,
-                                projectRoot: request.projectRoot,
-                                sessionRoot: observedSessionRoot,
-                                sequence: progressSequence + 1,
-                            });
-                            if (!parsed)
-                                continue;
-                            observedSessionRoot = parsed.sessionRoot ?? observedSessionRoot;
-                            try {
-                                request.progressObserver?.(parsed.event);
-                            }
-                            catch {
-                                // Progress notifications are transport-only and must not affect review execution.
-                            }
-                            progressSequence = parsed.event.sequence;
-                        }
+            const noteSessionRoot = (sessionRoot) => {
+                const resolved = path.resolve(sessionRoot);
+                observedSessionRoot = resolved;
+                if (sessionRootResolved)
+                    return;
+                sessionRootResolved = true;
+                resolveSessionRoot(resolved);
+                activeAttemptWrite = (async () => {
+                    const executionPlan = await readOptionalYaml(path.join(resolved, "execution-plan.yaml"));
+                    await writeActiveAttemptStarted({
+                        sessionRoot: resolved,
+                        attemptId: invocationId,
+                        attemptKind: "initial_review",
+                        sourceTool: "onto.review",
+                        requestHash,
+                        activeUnits: activeUnitsForInitialReview(executionPlan),
+                    });
+                })().catch(() => {
+                    // Active-attempt metadata is an operational projection; review
+                    // execution remains artifact-truthful even if this write fails.
+                });
+            };
+            const runnerProgressObserver = (event) => {
+                if (event.sessionRoot)
+                    noteSessionRoot(event.sessionRoot);
+                const stage = event.phase === "prepare"
+                    ? "session_planned"
+                    : event.phase === "execute"
+                        ? "runtime_step"
+                        : event.phase === "project"
+                            ? "completed"
+                            : "invoke_step";
+                const current = event.phase === "resolve"
+                    ? 5
+                    : event.phase === "prepare"
+                        ? 20
+                        : event.phase === "execute"
+                            ? event.status === "completed" ? 80 : 40
+                            : event.phase === "complete"
+                                ? event.status === "completed" ? 95 : 85
+                                : 100;
+                emitProgress({
+                    source: "artifact_status",
+                    stage,
+                    session_root: event.sessionRoot ?? observedSessionRoot,
+                    message: event.message,
+                    progress: {
+                        current,
+                        total: 100,
+                        label: event.phase,
                     },
+                });
+            };
+            const fullRun = (async () => {
+                try {
+                    const invocation = await runReviewInvocation(request, {
+                        ontoHome,
+                        noWatch: true,
+                        progressObserver: runnerProgressObserver,
+                    });
+                    const parsed = invocation.output;
+                    const result = parsed.review_result;
+                    const status = result.record_status ?? "halted_partial";
+                    const startPreview = {
+                        entrypointPlan: parsed.entrypoint_plan,
+                        routeSummary: parsed.route_summary,
+                        ...(parsed.bounded_invoke_steps !== undefined
+                            ? { boundedInvokeSteps: parsed.bounded_invoke_steps }
+                            : {}),
+                    };
+                    const resolvedResultSessionRoot = path.resolve(result.session_root);
+                    noteSessionRoot(resolvedResultSessionRoot);
+                    await activeAttemptWrite;
+                    await writeEnvironmentWarningsFromStderr({
+                        sessionRoot: resolvedResultSessionRoot,
+                        stderr: invocation.stderr,
+                    });
+                    await updateActiveAttemptTerminal({
+                        sessionRoot: resolvedResultSessionRoot,
+                        status: status === "halted_partial" ? "halted_partial" : "completed",
+                    });
+                    const artifactRefs = await collectArtifactRefs(resolvedResultSessionRoot);
+                    const failures = await collectStructuredFailures(resolvedResultSessionRoot);
+                    const executionPlan = await readOptionalYaml(path.join(resolvedResultSessionRoot, "execution-plan.yaml"));
+                    const executionResult = await readOptionalYaml(path.join(resolvedResultSessionRoot, "execution-result.yaml"));
+                    const pipelineExecutionLedger = await buildPipelineExecutionLedgerIfPossible({
+                        sessionRoot: resolvedResultSessionRoot,
+                        artifactRefs,
+                        executionPlan,
+                        executionResult,
+                    });
+                    const reviewRecord = await readOptionalReviewRecord(path.join(resolvedResultSessionRoot, "review-record.yaml"));
+                    const resultClassificationSummary = await readReviewResultClassification(resolvedResultSessionRoot);
+                    const progressInput = await buildReviewStatusPresentationInput({
+                        sessionRoot: resolvedResultSessionRoot,
+                        status,
+                        artifactRefs,
+                        executionPlan,
+                        executionResult,
+                        reviewRecord,
+                    });
+                    const openingBriefInput = executionPlan
+                        ? await buildPreparedOpeningBriefInput(resolvedResultSessionRoot, executionPlan)
+                        : {
+                            presentation_contract_version: REVIEW_PRESENTATION_CONTRACT_VERSION,
+                            presentation_kind: "opening_brief",
+                            session_id: basenameSessionId(resolvedResultSessionRoot),
+                            session_root: resolvedResultSessionRoot,
+                            status,
+                            generated_from_artifact_refs: generatedFromArtifactRefs(artifactRefs),
+                            start_preview: startPreview,
+                        };
+                    const finalResultInput = {
+                        presentation_contract_version: REVIEW_PRESENTATION_CONTRACT_VERSION,
+                        presentation_kind: "final_result",
+                        session_id: basenameSessionId(resolvedResultSessionRoot),
+                        session_root: resolvedResultSessionRoot,
+                        status,
+                        generated_from_artifact_refs: generatedFromArtifactRefs(artifactRefs),
+                        result_overview: parsed.result_overview ?? null,
+                        result_classification_summary: resultClassificationSummary,
+                        review_result: result,
+                    };
+                    const llmPresentation = {
+                        openingBrief: buildOpeningBriefPresentation(openingBriefInput),
+                        progress: buildProgressPresentation(progressInput),
+                        ...(progressInput.halt
+                            ? {
+                                halt: buildHaltPresentation({
+                                    ...progressInput,
+                                    presentation_kind: "halt",
+                                }),
+                            }
+                            : {}),
+                        finalResult: buildFinalResultPresentation(finalResultInput),
+                    };
+                    emitProgress({
+                        source: "artifact_status",
+                        stage: "final_status",
+                        session_root: resolvedResultSessionRoot,
+                        message: `Review finished with status ${status}.`,
+                        progress: {
+                            current: 100,
+                            total: 100,
+                            label: "final status",
+                        },
+                    });
+                    return {
+                        sessionId: basenameSessionId(result.session_root),
+                        sessionRoot: resolvedResultSessionRoot,
+                        status,
+                        finalOutputPath: result.final_output_path,
+                        reviewRecordPath: result.review_record_path,
+                        executionResultPath: result.execution_result_path,
+                        reviewRunManifestPath: result.review_run_manifest_path ??
+                            path.join(resolvedResultSessionRoot, "review-run-manifest.yaml"),
+                        deliberationStatus: result.deliberation_status ?? null,
+                        participatingLensIds: result.participating_lens_ids ?? [],
+                        degradedLensIds: result.degraded_lens_ids ?? [],
+                        ...(result.summary !== undefined ? { summary: result.summary } : {}),
+                        ...(parsed.result_overview !== undefined
+                            ? { resultOverview: parsed.result_overview }
+                            : {}),
+                        artifactRefs,
+                        ...(pipelineExecutionLedger ? { pipelineExecutionLedger } : {}),
+                        resultClassificationSummary,
+                        ...failures,
+                        routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedResultSessionRoot),
+                        startPreview,
+                        llmPresentation,
+                        runHandle: await buildReviewRunHandle({
+                            sessionRoot: resolvedResultSessionRoot,
+                            status,
+                            invocationId,
+                        }),
+                        runControl: progressInput.run_control,
+                        targetMaterialSupport: progressInput.target_material_support,
+                        environmentWarnings: progressInput.environment_warnings,
+                    };
                 }
-                : undefined;
-            const captured = await withCapturedConsole(async () => {
-                const exitCode = await runReviewInvokeCli(argv);
-                if (exitCode !== 0) {
-                    throw new Error(`review invocation failed with exit code ${exitCode}`);
+                catch (error) {
+                    if (observedSessionRoot) {
+                        await updateActiveAttemptTerminal({
+                            sessionRoot: observedSessionRoot,
+                            status: "failed",
+                            errorMessage: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    throw error;
                 }
-                return exitCode;
-            }, captureObserver);
-            const parsed = parseReviewInvokeOutput(captured.stdout);
-            if (!isReviewInvokeShape(parsed)) {
-                throw new Error("review invocation returned an unexpected result shape.");
+            })();
+            if (request.returnRunningAfterMs !== undefined) {
+                const waitMs = Math.max(0, request.returnRunningAfterMs);
+                const earlyRunning = (async () => {
+                    const sessionRoot = await sessionRootSeen;
+                    if (activeAttemptWrite)
+                        await activeAttemptWrite;
+                    if (waitMs > 0) {
+                        await new Promise((resolve) => setTimeout(resolve, waitMs));
+                    }
+                    return buildRunningReviewRunResult({
+                        sessionRoot,
+                        invocationId,
+                    });
+                })();
+                const winner = await Promise.race([
+                    fullRun.then((result) => ({ kind: "completed", result })),
+                    earlyRunning.then((result) => ({ kind: "running", result })),
+                ]);
+                if (winner.kind === "running") {
+                    fullRun.catch(() => {
+                        // The session artifacts and active-attempt projection record the failure.
+                    });
+                }
+                return winner.result;
             }
-            const result = parsed.review_result;
-            const status = result.record_status ?? "halted_partial";
-            const startPreview = {
-                entrypointPlan: parsed.entrypoint_plan,
-                routeSummary: parsed.route_summary,
-                ...(parsed.bounded_invoke_steps !== undefined
-                    ? { boundedInvokeSteps: parsed.bounded_invoke_steps }
-                    : {}),
-            };
-            const resolvedResultSessionRoot = path.resolve(result.session_root);
-            const artifactRefs = await collectArtifactRefs(resolvedResultSessionRoot);
-            const failures = await collectStructuredFailures(resolvedResultSessionRoot);
-            const executionPlan = await readOptionalYaml(path.join(resolvedResultSessionRoot, "execution-plan.yaml"));
-            const executionResult = await readOptionalYaml(path.join(resolvedResultSessionRoot, "execution-result.yaml"));
-            const reviewRecord = await readOptionalReviewRecord(path.join(resolvedResultSessionRoot, "review-record.yaml"));
-            const resultClassificationSummary = await readReviewResultClassification(resolvedResultSessionRoot);
-            const progressInput = await buildReviewStatusPresentationInput({
-                sessionRoot: resolvedResultSessionRoot,
-                status,
+            return fullRun;
+        },
+        async continueReview(request) {
+            const resolvedSessionRoot = path.resolve(request.sessionRoot);
+            const sessionMetadataPath = path.join(resolvedSessionRoot, "session-metadata.yaml");
+            const sessionMetadata = await readOptionalYaml(sessionMetadataPath);
+            if (!sessionMetadata) {
+                throw new Error(`Cannot continue review without session-metadata.yaml: ${resolvedSessionRoot}`);
+            }
+            const projectRoot = path.resolve(request.projectRoot ?? sessionMetadata.project_root);
+            await assertSamePath({
+                label: "ReviewSessionMetadata.project_root",
+                expected: projectRoot,
+                actual: sessionMetadata.project_root,
+            });
+            const artifactRefs = await collectArtifactRefs(resolvedSessionRoot);
+            const executionPlan = await readOptionalYaml(path.join(resolvedSessionRoot, "execution-plan.yaml"));
+            if (!executionPlan) {
+                throw new Error(`Cannot continue review without execution-plan.yaml: ${resolvedSessionRoot}`);
+            }
+            if (executionPlan.session_id !== sessionMetadata.session_id) {
+                throw new Error(`Review continuation session id mismatch: metadata=${sessionMetadata.session_id}, executionPlan=${executionPlan.session_id}`);
+            }
+            await assertSamePath({
+                label: "ReviewExecutionPlan.session_metadata_path",
+                expected: sessionMetadataPath,
+                actual: executionPlan.session_metadata_path,
+            });
+            await assertReviewExecutionPlanSessionBoundary({
+                sessionRoot: resolvedSessionRoot,
+                executionPlan,
+            });
+            const activeRunControl = await buildRunControl(resolvedSessionRoot, "running");
+            if (activeRunControl.alreadyRunning &&
+                requestedUnitsMatchActive(activeRunControl.activeAttempt?.activeUnits ?? [], request.targetUnits)) {
+                const status = await api.getReviewStatus(resolvedSessionRoot);
+                return {
+                    sessionId: status.sessionId,
+                    sessionRoot: resolvedSessionRoot,
+                    decision: "already_running",
+                    status: "running",
+                    artifactRefs: status.artifactRefs,
+                    failureRefs: status.failureRefs,
+                    ...(status.pipelineExecutionLedger
+                        ? { pipelineExecutionLedger: status.pipelineExecutionLedger }
+                        : {}),
+                    resultClassificationSummary: await readReviewResultClassification(resolvedSessionRoot),
+                    ...(status.routeVisibility !== undefined
+                        ? { routeVisibility: status.routeVisibility }
+                        : {}),
+                    ...(status.llmPresentation !== undefined
+                        ? { llmPresentation: status.llmPresentation }
+                        : {}),
+                    ...(activeRunControl.activeAttempt
+                        ? { activeAttempt: activeRunControl.activeAttempt }
+                        : {}),
+                };
+            }
+            const executionResult = await readOptionalYaml(path.join(resolvedSessionRoot, "execution-result.yaml"));
+            const pipelineExecutionLedger = await buildPipelineExecutionLedgerIfPossible({
+                sessionRoot: resolvedSessionRoot,
                 artifactRefs,
                 executionPlan,
                 executionResult,
-                reviewRecord,
             });
-            const openingBriefInput = executionPlan
-                ? await buildPreparedOpeningBriefInput(resolvedResultSessionRoot, executionPlan)
-                : {
-                    presentation_contract_version: REVIEW_PRESENTATION_CONTRACT_VERSION,
-                    presentation_kind: "opening_brief",
-                    session_id: basenameSessionId(resolvedResultSessionRoot),
-                    session_root: resolvedResultSessionRoot,
+            if (!pipelineExecutionLedger) {
+                throw new Error(`Cannot continue review without a PipelineExecutionLedger: ${resolvedSessionRoot}`);
+            }
+            const continuationPlan = buildReviewContinuationPlan({
+                ledger: pipelineExecutionLedger,
+                ...(request.targetUnits !== undefined
+                    ? { targetUnits: request.targetUnits }
+                    : {}),
+            });
+            if (!continuationPlan.eligible) {
+                throw new Error(`Review continuation is not eligible: ${continuationPlan.ineligibleReason ?? "unknown reason"}`);
+            }
+            const reviewRunManifest = await readOptionalYaml(path.join(resolvedSessionRoot, "review-run-manifest.yaml"));
+            const executorRealization = request.executorRealization ??
+                executorRealizationFromManifest(reviewRunManifest);
+            if (!executorRealization) {
+                throw new Error("Review continuation requires executorRealization when the prior review-run-manifest does not expose a worker executor.");
+            }
+            const actorProfiles = await readOptionalYaml(executionPlan.actor_invocation_profiles_path ??
+                path.join(resolvedSessionRoot, "execution-preparation", "actor-invocation-profiles.yaml"));
+            const manifestReviewExecutionProfile = request.executorRealization === undefined
+                ? reviewExecutionProfileFromManifest(reviewRunManifest)
+                : undefined;
+            const actorProfileReviewExecutionProfile = manifestReviewExecutionProfile
+                ? undefined
+                : reviewExecutionProfileFromActorProfiles({
+                    actorProfiles,
+                    executorRealization,
+                });
+            const reviewExecutionProfile = manifestReviewExecutionProfile ?? actorProfileReviewExecutionProfile;
+            const reviewExecutionProfileSource = manifestReviewExecutionProfile
+                ? "review-run-manifest"
+                : actorProfileReviewExecutionProfile
+                    ? "actor-invocation-profiles"
+                    : "none";
+            const attemptId = continuationAttemptId();
+            const attemptRoot = path.join(resolvedSessionRoot, "continuation-attempts", attemptId);
+            const continuationPlanPath = path.join(attemptRoot, "continuation-plan.yaml");
+            const attemptManifestPath = path.join(attemptRoot, "continuation-attempt.yaml");
+            await writeYamlDocument(continuationPlanPath, continuationPlan);
+            const supersededArtifactBackups = await copySupersededArtifacts({
+                attemptRoot,
+                artifactRefs: [
+                    ...new Set([
+                        ...continuationPlan.supersededArtifactRefs,
+                        ...continuationSessionArtifactRefs({
+                            sessionRoot: resolvedSessionRoot,
+                            executionPlan,
+                        }),
+                    ]),
+                ],
+            });
+            const attemptStartedAt = isoNow();
+            const writeAttemptManifest = async (status, extra = {}) => {
+                await writeYamlDocument(attemptManifestPath, {
+                    schema_version: "1",
+                    attempt_id: attemptId,
+                    session_id: executionPlan.session_id,
+                    session_root: resolvedSessionRoot,
+                    created_at: attemptStartedAt,
+                    updated_at: isoNow(),
                     status,
-                    generated_from_artifact_refs: generatedFromArtifactRefs(artifactRefs),
-                    start_preview: startPreview,
-                };
-            const finalResultInput = {
-                presentation_contract_version: REVIEW_PRESENTATION_CONTRACT_VERSION,
-                presentation_kind: "final_result",
-                session_id: basenameSessionId(resolvedResultSessionRoot),
-                session_root: resolvedResultSessionRoot,
-                status,
-                generated_from_artifact_refs: generatedFromArtifactRefs(artifactRefs),
-                result_overview: parsed.result_overview ?? null,
-                result_classification_summary: resultClassificationSummary,
-                review_result: result,
+                    executor_realization: executorRealization,
+                    target_units: request.targetUnits ?? [],
+                    continuation_plan_ref: continuationPlanPath,
+                    superseded_artifact_backups: supersededArtifactBackups,
+                    execution_route_provenance: {
+                        executor_realization: executorRealization,
+                        review_execution_profile_source: reviewExecutionProfileSource,
+                        requested_executor_realization: request.executorRealization ?? null,
+                        previous_execution_realization: executionPlan.execution_realization,
+                        previous_host_runtime: executionPlan.host_runtime,
+                    },
+                    ...extra,
+                });
             };
-            const llmPresentation = {
-                openingBrief: buildOpeningBriefPresentation(openingBriefInput),
-                progress: buildProgressPresentation(progressInput),
-                ...(progressInput.halt
-                    ? {
-                        halt: buildHaltPresentation({
-                            ...progressInput,
-                            presentation_kind: "halt",
-                        }),
-                    }
+            await writeAttemptManifest("started");
+            await writeActiveAttemptStarted({
+                sessionRoot: resolvedSessionRoot,
+                attemptId,
+                attemptKind: "continuation",
+                sourceTool: "onto.review_continue",
+                requestHash: null,
+                activeUnits: continuationPlan.frontierUnits.map((unit) => unit.unitId),
+                requestedFrontierUnits: request.targetUnits ?? [],
+            });
+            let promptExecutionResult;
+            try {
+                const executorConfig = buildExecutorConfigFromRealization(executorRealization, ontoHome);
+                promptExecutionResult = (await withCapturedConsole(() => executeReviewPromptExecution({
+                    projectRoot,
+                    sessionRoot: resolvedSessionRoot,
+                    defaultExecutorConfig: executorConfig,
+                    ...(reviewExecutionProfile ? { reviewExecutionProfile } : {}),
+                    continuationPlan,
+                }))).result;
+                if (promptExecutionResult.synthesis_executed) {
+                    const requestText = await resolveContinuationRequestText({
+                        sessionRoot: resolvedSessionRoot,
+                        ...(request.requestText ? { requestText: request.requestText } : {}),
+                    });
+                    await withCapturedConsole(() => completeReviewSession([
+                        "--project-root",
+                        projectRoot,
+                        "--session-root",
+                        resolvedSessionRoot,
+                        "--request-text",
+                        requestText,
+                    ]));
+                }
+                await writeAttemptManifest(promptExecutionResult.synthesis_executed
+                    ? "completed"
+                    : "halted_partial", { prompt_execution_result: promptExecutionResult });
+                await updateActiveAttemptTerminal({
+                    sessionRoot: resolvedSessionRoot,
+                    status: promptExecutionResult.synthesis_executed
+                        ? "completed"
+                        : "halted_partial",
+                });
+            }
+            catch (error) {
+                const restoredArtifactBackups = await restoreSupersededArtifacts(supersededArtifactBackups);
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                await writeAttemptManifest("failed", {
+                    error_message: errorMessage,
+                    ...(promptExecutionResult
+                        ? { prompt_execution_result: promptExecutionResult }
+                        : {}),
+                    restored_artifact_backups: restoredArtifactBackups,
+                });
+                await updateActiveAttemptTerminal({
+                    sessionRoot: resolvedSessionRoot,
+                    status: "failed",
+                    errorMessage,
+                });
+                throw new ReviewContinuationError({
+                    message: `Review continuation failed: ${errorMessage}`,
+                    originalError: error,
+                    failureContent: {
+                        mcp_error_code: "ONTO_REVIEW_CONTINUATION_FAILED",
+                        session_id: executionPlan.session_id,
+                        session_root: resolvedSessionRoot,
+                        attempt_id: attemptId,
+                        attempt_root: attemptRoot,
+                        attempt_manifest_ref: attemptManifestPath,
+                        continuation_plan_ref: continuationPlanPath,
+                        continuation_plan: continuationPlan,
+                        superseded_artifact_backups: supersededArtifactBackups,
+                        restored_artifact_backups: restoredArtifactBackups,
+                        error_message: errorMessage,
+                    },
+                });
+            }
+            if (!promptExecutionResult) {
+                throw new Error("Review continuation finished without prompt execution result.");
+            }
+            const postStatus = await api.getReviewStatus(resolvedSessionRoot);
+            return {
+                sessionId: postStatus.sessionId,
+                sessionRoot: resolvedSessionRoot,
+                decision: "executed",
+                status: postStatus.status,
+                continuationPlan,
+                continuationAttempt: {
+                    attemptId,
+                    attemptRoot,
+                    continuationPlanPath,
+                    attemptManifestPath,
+                    supersededArtifactBackups,
+                },
+                promptExecutionResult,
+                artifactRefs: postStatus.artifactRefs,
+                ...(postStatus.pipelineExecutionLedger
+                    ? { pipelineExecutionLedger: postStatus.pipelineExecutionLedger }
+                    : {}),
+                resultClassificationSummary: await readReviewResultClassification(resolvedSessionRoot),
+                failureRefs: postStatus.failureRefs,
+                ...(postStatus.routeVisibility !== undefined
+                    ? { routeVisibility: postStatus.routeVisibility }
+                    : {}),
+                ...(postStatus.llmPresentation !== undefined
+                    ? { llmPresentation: postStatus.llmPresentation }
                     : {}),
-                finalResult: buildFinalResultPresentation(finalResultInput),
             };
-            emitProgress({
-                source: "artifact_status",
-                stage: "final_status",
-                session_root: resolvedResultSessionRoot,
-                message: `Review finished with status ${status}.`,
-                progress: {
-                    current: 100,
-                    total: 100,
-                    label: "final status",
-                },
+        },
+        async cancelReview(request) {
+            const resolvedSessionRoot = path.resolve(request.sessionRoot);
+            const sessionMetadata = await readOptionalYaml(path.join(resolvedSessionRoot, "session-metadata.yaml"));
+            if (!sessionMetadata) {
+                throw new Error(`Cannot cancel review without session-metadata.yaml: ${resolvedSessionRoot}`);
+            }
+            const projectRoot = path.resolve(request.projectRoot ?? sessionMetadata.project_root);
+            await assertSamePath({
+                label: "ReviewSessionMetadata.project_root",
+                expected: projectRoot,
+                actual: sessionMetadata.project_root,
             });
+            const statusBeforeCancel = await api.getReviewStatus(resolvedSessionRoot);
+            if (reviewTerminalStatus(statusBeforeCancel.status)) {
+                return {
+                    sessionId: statusBeforeCancel.sessionId,
+                    sessionRoot: resolvedSessionRoot,
+                    decision: "already_terminal",
+                    status: statusBeforeCancel.status,
+                    cancelRequestPath: reviewCancelRequestPath(resolvedSessionRoot),
+                    reason: "review is already terminal",
+                    artifactRefs: statusBeforeCancel.artifactRefs,
+                    ...(statusBeforeCancel.runControl
+                        ? { runControl: statusBeforeCancel.runControl }
+                        : {}),
+                    ...(statusBeforeCancel.llmPresentation
+                        ? { llmPresentation: statusBeforeCancel.llmPresentation }
+                        : {}),
+                };
+            }
+            if (!statusBeforeCancel.runControl?.cancellationAvailable) {
+                return {
+                    sessionId: statusBeforeCancel.sessionId,
+                    sessionRoot: resolvedSessionRoot,
+                    decision: "not_cancellable",
+                    status: statusBeforeCancel.status,
+                    cancelRequestPath: reviewCancelRequestPath(resolvedSessionRoot),
+                    reason: statusBeforeCancel.runControl?.statusReason ??
+                        "review is not currently cancellable",
+                    artifactRefs: statusBeforeCancel.artifactRefs,
+                    ...(statusBeforeCancel.runControl
+                        ? { runControl: statusBeforeCancel.runControl }
+                        : {}),
+                    ...(statusBeforeCancel.llmPresentation
+                        ? { llmPresentation: statusBeforeCancel.llmPresentation }
+                        : {}),
+                };
+            }
+            const reason = request.reason?.trim() || "operator requested cancellation";
+            const cancelRequest = {
+                schema_version: "1",
+                session_id: sessionMetadata.session_id,
+                requested_at: isoNow(),
+                requested_by: "mcp",
+                reason,
+            };
+            const cancelRequestPath = reviewCancelRequestPath(resolvedSessionRoot);
+            await writeYamlDocument(cancelRequestPath, cancelRequest);
+            const status = await api.getReviewStatus(resolvedSessionRoot);
             return {
-                sessionId: basenameSessionId(result.session_root),
-                sessionRoot: resolvedResultSessionRoot,
-                status,
-                finalOutputPath: result.final_output_path,
-                reviewRecordPath: result.review_record_path,
-                executionResultPath: result.execution_result_path,
-                reviewRunManifestPath: result.review_run_manifest_path ??
-                    path.join(resolvedResultSessionRoot, "review-run-manifest.yaml"),
-                deliberationStatus: result.deliberation_status ?? null,
-                participatingLensIds: result.participating_lens_ids ?? [],
-                degradedLensIds: result.degraded_lens_ids ?? [],
-                ...(result.summary !== undefined ? { summary: result.summary } : {}),
-                ...(parsed.result_overview !== undefined
-                    ? { resultOverview: parsed.result_overview }
-                    : {}),
-                artifactRefs,
-                resultClassificationSummary,
-                ...failures,
-                routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedResultSessionRoot),
-                startPreview,
-                llmPresentation,
+                sessionId: status.sessionId,
+                sessionRoot: resolvedSessionRoot,
+                decision: "requested",
+                status: status.status,
+                cancelRequestPath,
+                reason,
+                artifactRefs: status.artifactRefs,
+                ...(status.runControl ? { runControl: status.runControl } : {}),
+                ...(status.llmPresentation ? { llmPresentation: status.llmPresentation } : {}),
             };
         },
         async getReviewStatus(sessionRoot) {
@@ -1118,16 +2337,32 @@ export function createOntoReviewCoreApi(options = {}) {
             const failures = await collectStructuredFailures(resolvedSessionRoot);
             const executionPlan = await readOptionalYaml(path.join(resolvedSessionRoot, "execution-plan.yaml"));
             const executionResult = await readOptionalYaml(path.join(resolvedSessionRoot, "execution-result.yaml"));
+            const pipelineExecutionLedger = await buildPipelineExecutionLedgerIfPossible({
+                sessionRoot: resolvedSessionRoot,
+                artifactRefs,
+                executionPlan,
+                executionResult,
+            });
+            const continuationPlan = pipelineExecutionLedger
+                ? buildReviewContinuationPlan({ ledger: pipelineExecutionLedger })
+                : undefined;
             const reviewRecord = await readOptionalReviewRecord(path.join(resolvedSessionRoot, "review-record.yaml"));
+            const activeAttempt = await activeAttemptProjection(resolvedSessionRoot);
+            const activeRunInProgress = activeAttempt?.status === "started" && !activeAttempt.isStale;
             const status = reviewRecord
                 ? reviewRecord.record_status
                 : executionResult?.execution_status === "halted_partial"
                     ? "halted_partial"
-                    : executionPlan
-                        ? await hasRunArtifacts(resolvedSessionRoot, artifactRefs)
-                            ? "running"
-                            : "prepared"
-                        : "unknown";
+                    : activeAttempt?.status === "failed"
+                        ? "failed"
+                        : activeAttempt?.status === "halted_partial"
+                            ? "halted_partial"
+                            : executionPlan
+                                ? (activeRunInProgress ||
+                                    await hasRunArtifacts(resolvedSessionRoot, artifactRefs))
+                                    ? "running"
+                                    : "prepared"
+                                : "unknown";
             const progressInput = await buildReviewStatusPresentationInput({
                 sessionRoot: resolvedSessionRoot,
                 status,
@@ -1154,9 +2389,15 @@ export function createOntoReviewCoreApi(options = {}) {
                     sessionRoot: resolvedSessionRoot,
                     status,
                     artifactRefs,
+                    ...(pipelineExecutionLedger ? { pipelineExecutionLedger } : {}),
+                    ...(continuationPlan ? { continuationPlan } : {}),
                     ...failures,
                     routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedSessionRoot),
                     llmPresentation,
+                    runControl: progressInput.run_control,
+                    targetMaterialSupport: progressInput.target_material_support,
+                    environmentWarnings: progressInput.environment_warnings,
+                    unitProgress: progressInput.progress.unit_progress,
                 };
             }
             if (executionResult?.execution_status === "halted_partial") {
@@ -1165,9 +2406,15 @@ export function createOntoReviewCoreApi(options = {}) {
                     sessionRoot: resolvedSessionRoot,
                     status,
                     artifactRefs,
+                    ...(pipelineExecutionLedger ? { pipelineExecutionLedger } : {}),
+                    ...(continuationPlan ? { continuationPlan } : {}),
                     ...failures,
                     routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedSessionRoot),
                     llmPresentation,
+                    runControl: progressInput.run_control,
+                    targetMaterialSupport: progressInput.target_material_support,
+                    environmentWarnings: progressInput.environment_warnings,
+                    unitProgress: progressInput.progress.unit_progress,
                 };
             }
             if (executionPlan) {
@@ -1176,9 +2423,15 @@ export function createOntoReviewCoreApi(options = {}) {
                     sessionRoot: resolvedSessionRoot,
                     status,
                     artifactRefs,
+                    ...(pipelineExecutionLedger ? { pipelineExecutionLedger } : {}),
+                    ...(continuationPlan ? { continuationPlan } : {}),
                     ...failures,
                     routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedSessionRoot),
                     llmPresentation,
+                    runControl: progressInput.run_control,
+                    targetMaterialSupport: progressInput.target_material_support,
+                    environmentWarnings: progressInput.environment_warnings,
+                    unitProgress: progressInput.progress.unit_progress,
                 };
             }
             return {
@@ -1186,21 +2439,41 @@ export function createOntoReviewCoreApi(options = {}) {
                 sessionRoot: resolvedSessionRoot,
                 status: "unknown",
                 artifactRefs,
+                ...(pipelineExecutionLedger ? { pipelineExecutionLedger } : {}),
+                ...(continuationPlan ? { continuationPlan } : {}),
                 ...failures,
                 routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedSessionRoot),
                 llmPresentation,
+                runControl: progressInput.run_control,
+                targetMaterialSupport: progressInput.target_material_support,
+                environmentWarnings: progressInput.environment_warnings,
+                unitProgress: progressInput.progress.unit_progress,
             };
         },
-        async getReviewResult(sessionRoot) {
+        async getReviewResult(sessionRoot, options = {}) {
             const resolvedSessionRoot = path.resolve(sessionRoot);
+            const projectionLevel = options.projectionLevel ?? "full";
             const artifactRefs = await collectArtifactRefs(resolvedSessionRoot);
             const { failureRefs } = await collectStructuredFailures(resolvedSessionRoot);
             const reviewRecordPath = path.join(resolvedSessionRoot, "review-record.yaml");
             const reviewRecord = await readValidatedReviewRecord(reviewRecordPath);
-            const finalOutputPath = reviewRecord.final_output_ref ?? path.join(resolvedSessionRoot, "final-output.md");
-            const finalOutputText = await readOptionalText(finalOutputPath);
+            const resultSessionMetadata = await readOptionalYaml(path.join(resolvedSessionRoot, "session-metadata.yaml"));
+            const finalOutputPath = await resolveReviewRecordFinalOutputPath({
+                sessionRoot: resolvedSessionRoot,
+                projectRoot: resultSessionMetadata?.project_root ?? null,
+                finalOutputRef: reviewRecord.final_output_ref,
+            });
+            const finalOutputText = projectionLevel === "compact"
+                ? undefined
+                : await readOptionalText(finalOutputPath);
             const executionPlan = await readOptionalYaml(path.join(resolvedSessionRoot, "execution-plan.yaml"));
             const executionResult = await readOptionalYaml(path.join(resolvedSessionRoot, "execution-result.yaml"));
+            const pipelineExecutionLedger = await buildPipelineExecutionLedgerIfPossible({
+                sessionRoot: resolvedSessionRoot,
+                artifactRefs,
+                executionPlan,
+                executionResult,
+            });
             const resultClassificationSummary = await readReviewResultClassification(resolvedSessionRoot);
             const status = reviewRecord.record_status;
             const progressInput = await buildReviewStatusPresentationInput({
@@ -1219,15 +2492,36 @@ export function createOntoReviewCoreApi(options = {}) {
                 status,
                 generated_from_artifact_refs: generatedFromArtifactRefs(artifactRefs),
                 result_classification_summary: resultClassificationSummary,
-                review_record: reviewRecord,
+                review_record: projectionLevel === "full" ? reviewRecord : null,
+                review_record_summary: {
+                    review_record_id: reviewRecord.review_record_id,
+                    record_status: reviewRecord.record_status,
+                    resolved_lens_ids: reviewRecord.resolved_lens_ids,
+                    participating_lens_ids: reviewRecord.participating_lens_ids,
+                    degraded_lens_ids: reviewRecord.degraded_lens_ids,
+                    deliberation_status: reviewRecord.deliberation_status,
+                },
             };
+            const targetMaterialSupport = await readTargetMaterialSupport(resolvedSessionRoot, executionPlan);
+            const environmentWarnings = await readEnvironmentWarnings(resolvedSessionRoot);
             return {
                 sessionId: reviewRecord.session_id,
                 sessionRoot: resolvedSessionRoot,
-                reviewRecord,
+                projectionLevel,
+                reviewRecordSummary: {
+                    reviewRecordId: reviewRecord.review_record_id,
+                    recordStatus: reviewRecord.record_status,
+                    requestText: reviewRecord.request_text,
+                    resolvedLensIds: reviewRecord.resolved_lens_ids,
+                    participatingLensIds: reviewRecord.participating_lens_ids,
+                    degradedLensIds: reviewRecord.degraded_lens_ids,
+                    deliberationStatus: reviewRecord.deliberation_status,
+                },
+                ...(projectionLevel === "full" ? { reviewRecord } : {}),
                 finalOutputPath,
                 reviewRunManifestPath: path.join(resolvedSessionRoot, "review-run-manifest.yaml"),
                 artifactRefs,
+                ...(pipelineExecutionLedger ? { pipelineExecutionLedger } : {}),
                 resultClassificationSummary,
                 failureRefs,
                 routeVisibility: await buildReviewRouteVisibilityFromSession(resolvedSessionRoot),
@@ -1243,9 +2537,87 @@ export function createOntoReviewCoreApi(options = {}) {
                         : {}),
                     finalResult: buildFinalResultPresentation(finalResultInput),
                 },
+                targetMaterialSupport,
+                environmentWarnings,
                 ...(finalOutputText !== undefined ? { finalOutputText } : {}),
             };
         },
+        async findLatestReviewSessions(query) {
+            const projectRoot = path.resolve(query.projectRoot);
+            const reviewRoot = path.join(projectRoot, ".onto", "review");
+            let entries;
+            try {
+                entries = await fs.readdir(reviewRoot, { withFileTypes: true });
+            }
+            catch {
+                return [];
+            }
+            const createdAfterMs = query.createdAfter
+                ? parseTimestampMs(query.createdAfter)
+                : null;
+            const targetFilter = query.target ? path.normalize(query.target) : null;
+            const domainFilter = query.domain ? normalizeDomainValue(query.domain) : null;
+            const matches = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const sessionRoot = path.join(reviewRoot, entry.name);
+                const metadata = await readOptionalYaml(path.join(sessionRoot, "session-metadata.yaml"));
+                if (!metadata)
+                    continue;
+                const interpretation = await readOptionalYaml(path.join(sessionRoot, "interpretation.yaml"));
+                const binding = await readOptionalYaml(path.join(sessionRoot, "binding.yaml"));
+                const targetProfile = await readOptionalYaml(path.join(sessionRoot, "execution-preparation", "review-target-profile.yaml"));
+                const createdAt = metadata.created_at ?? null;
+                const createdAtMs = parseTimestampMs(createdAt);
+                if (createdAfterMs !== null &&
+                    createdAtMs !== null &&
+                    createdAtMs < createdAfterMs) {
+                    continue;
+                }
+                if (targetFilter &&
+                    path.normalize(metadata.requested_target) !== targetFilter &&
+                    path.normalize(targetProfile?.requested_target ?? "") !== targetFilter) {
+                    continue;
+                }
+                const normalizedDomain = binding?.resolved_session_domain ??
+                    targetProfile?.domain ??
+                    normalizeDomainValue(metadata.requested_domain_token ?? "");
+                if (domainFilter &&
+                    normalizeDomainValue(normalizedDomain) !== domainFilter) {
+                    continue;
+                }
+                const requestHash = requestHashFromArtifacts({
+                    metadata,
+                    interpretation,
+                    binding,
+                });
+                if (query.requestHash && requestHash !== query.requestHash) {
+                    continue;
+                }
+                const artifactRefs = await collectArtifactRefs(sessionRoot);
+                const status = (await api.getReviewStatus(sessionRoot)).status;
+                matches.push({
+                    sessionId: metadata.session_id ?? entry.name,
+                    sessionRoot,
+                    createdAt,
+                    requestedTarget: metadata.requested_target ?? null,
+                    requestedDomainToken: metadata.requested_domain_token ?? null,
+                    normalizedDomain: normalizedDomain === "none" || normalizedDomain.length === 0
+                        ? null
+                        : normalizeDomainValue(normalizedDomain),
+                    requestHash,
+                    status,
+                    artifactRefs,
+                });
+            }
+            matches.sort((a, b) => {
+                const left = parseTimestampMs(a.createdAt) ?? 0;
+                const right = parseTimestampMs(b.createdAt) ?? 0;
+                return right - left;
+            });
+            return matches.slice(0, query.limit ?? 5);
+        },
         async listLenses() {
             const registry = loadCoreLensRegistry();
             return {
@@ -1268,4 +2640,5 @@ export function createOntoReviewCoreApi(options = {}) {
             return [...names].sort();
         },
     };
+    return api;
 }