onto-mcp 0.3.1 → 0.3.2

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

@@ -4,13 +4,16 @@ 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, writeYamlDocument, } 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 { collectReviewInvocationArtifactRefs, prepareReviewInvocationRequest, runReviewInvocation, } from "../core-runtime/review/review-invocation-runner.js";
 import { completeReviewSession } from "../core-runtime/cli/complete-review-session.js";
-import { buildExecutorConfigFromRealization, reviewPrepareOnly, runReviewInvokeCli, } from "../core-runtime/cli/review-invoke.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";
@@ -24,6 +27,14 @@ export class ReviewContinuationError extends Error {
         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) => {
@@ -89,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));
 }
@@ -147,36 +111,44 @@ async function readOptionalYaml(filePath) {
 async function readOptionalReviewRecord(filePath) {
     if (!(await fileExists(filePath)))
         return null;
-    return readValidatedReviewRecord(filePath);
-}
-async function readOptionalText(filePath) {
-    if (!(await fileExists(filePath)))
-        return undefined;
-    return fs.readFile(filePath, "utf8");
-}
-function isInsidePath(root, candidate) {
-    const relative = path.relative(path.resolve(root), path.resolve(candidate));
-    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-async function realpathIfExists(targetPath) {
     try {
-        return await fs.realpath(targetPath);
+        return await readValidatedReviewRecord(filePath);
     }
     catch {
         return null;
     }
 }
-async function realpathNearestExisting(targetPath) {
-    let current = path.resolve(targetPath);
-    while (true) {
-        const real = await realpathIfExists(current);
-        if (real)
-            return real;
-        const parent = path.dirname(current);
-        if (parent === current)
-            return null;
-        current = parent;
-    }
+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);
@@ -190,115 +162,6 @@ async function assertSamePath(args) {
     }
     throw new Error(`${args.label} mismatch: expected ${expected}, received ${actual}`);
 }
-async function assertRefInsideSession(args) {
-    const sessionRoot = path.resolve(args.sessionRoot);
-    const resolvedRef = path.isAbsolute(args.ref)
-        ? path.resolve(args.ref)
-        : path.resolve(sessionRoot, args.ref);
-    if (!isInsidePath(sessionRoot, resolvedRef)) {
-        throw new Error(`Review continuation blocked because ${args.label} escapes the session root: ${resolvedRef}`);
-    }
-    const realSessionRoot = (await realpathIfExists(sessionRoot)) ?? sessionRoot;
-    const realRef = await realpathIfExists(resolvedRef);
-    if (realRef && !isInsidePath(realSessionRoot, realRef)) {
-        throw new Error(`Review continuation blocked because ${args.label} realpath escapes the session root: ${realRef}`);
-    }
-    if (!realRef) {
-        const realNearest = await realpathNearestExisting(path.dirname(resolvedRef));
-        if (realNearest && !isInsidePath(realSessionRoot, realNearest)) {
-            throw new Error(`Review continuation blocked because ${args.label} parent realpath escapes the session root: ${realNearest}`);
-        }
-    }
-}
-async function validateReviewExecutionPlanSessionBoundary(args) {
-    const { executionPlan, sessionRoot } = args;
-    const plannedSessionRoot = path.isAbsolute(executionPlan.session_root)
-        ? executionPlan.session_root
-        : path.resolve(sessionRoot, executionPlan.session_root);
-    await assertSamePath({
-        label: "ReviewExecutionPlan.session_root",
-        expected: sessionRoot,
-        actual: plannedSessionRoot,
-    });
-    const refs = [
-        { label: "interpretation_artifact_path", ref: executionPlan.interpretation_artifact_path },
-        { label: "binding_output_path", ref: executionPlan.binding_output_path },
-        { label: "session_metadata_path", ref: executionPlan.session_metadata_path },
-        { label: "execution_preparation_root", ref: executionPlan.execution_preparation_root },
-        { label: "round1_root", ref: executionPlan.round1_root },
-        { label: "prompt_packets_root", ref: executionPlan.prompt_packets_root },
-        {
-            label: "teamlead_deliberation_prompt_packet_path",
-            ref: executionPlan.teamlead_deliberation_prompt_packet_path,
-        },
-        { label: "synthesize_prompt_packet_path", ref: executionPlan.synthesize_prompt_packet_path },
-        { label: "actor_invocation_profiles_path", ref: executionPlan.actor_invocation_profiles_path },
-        { label: "actor_consumer_bindings_path", ref: executionPlan.actor_consumer_bindings_path },
-        { label: "domain_binding_path", ref: executionPlan.domain_binding_path },
-        { label: "review_target_profile_path", ref: executionPlan.review_target_profile_path },
-        {
-            label: "review_value_alignment_criteria_path",
-            ref: executionPlan.review_value_alignment_criteria_path,
-        },
-        { label: "review_context_manifest_path", ref: executionPlan.review_context_manifest_path },
-        { label: "synthesis_output_path", ref: executionPlan.synthesis_output_path },
-        { label: "finding_ledger_path", ref: executionPlan.finding_ledger_path },
-        {
-            label: "finding_relation_graph_path",
-            ref: executionPlan.finding_relation_graph_path,
-        },
-        { label: "issue_ledger_path", ref: executionPlan.issue_ledger_path },
-        { label: "issue_stance_matrix_path", ref: executionPlan.issue_stance_matrix_path },
-        { label: "deliberation_plan_path", ref: executionPlan.deliberation_plan_path },
-        { label: "problem_framing_path", ref: executionPlan.problem_framing_path },
-        { label: "lens_completion_barrier_path", ref: executionPlan.lens_completion_barrier_path },
-        { label: "deliberation_root_path", ref: executionPlan.deliberation_root_path },
-        { label: "deliberation_output_path", ref: executionPlan.deliberation_output_path },
-        { label: "execution_result_path", ref: executionPlan.execution_result_path },
-        { label: "error_log_path", ref: executionPlan.error_log_path },
-        { label: "final_output_path", ref: executionPlan.final_output_path },
-        { label: "review_record_path", ref: executionPlan.review_record_path },
-        ...executionPlan.lens_execution_seats.map((seat) => ({
-            label: `lens_execution_seats.${seat.lens_id}.output_path`,
-            ref: seat.output_path,
-        })),
-        ...executionPlan.lens_prompt_packet_seats.flatMap((seat) => [
-            {
-                label: `lens_prompt_packet_seats.${seat.lens_id}.packet_path`,
-                ref: seat.packet_path,
-            },
-            {
-                label: `lens_prompt_packet_seats.${seat.lens_id}.output_path`,
-                ref: seat.output_path,
-            },
-        ]),
-        ...executionPlan.issue_artifact_prompt_packet_seats.flatMap((seat) => [
-            {
-                label: `issue_artifact_prompt_packet_seats.${seat.artifact_id}.packet_path`,
-                ref: seat.packet_path,
-            },
-            {
-                label: `issue_artifact_prompt_packet_seats.${seat.artifact_id}.output_path`,
-                ref: seat.output_path,
-            },
-        ]),
-        ...executionPlan.lens_deliberation_prompt_packet_seats.flatMap((seat) => [
-            {
-                label: `lens_deliberation_prompt_packet_seats.${seat.lens_id}.packet_path`,
-                ref: seat.packet_path,
-            },
-            {
-                label: `lens_deliberation_prompt_packet_seats.${seat.lens_id}.output_path`,
-                ref: seat.output_path,
-            },
-        ]),
-    ];
-    for (const { label, ref } of refs) {
-        if (!ref)
-            continue;
-        await assertRefInsideSession({ sessionRoot, ref, label });
-    }
-}
 function buildOpeningBriefPresentation(input) {
     return {
         prompt: [
@@ -340,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}`,
@@ -373,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) {
@@ -622,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 ?? []) {
@@ -637,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) {
@@ -656,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) {
@@ -691,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))
@@ -825,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
@@ -848,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"
@@ -872,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({
@@ -904,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",
@@ -922,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) {
@@ -986,74 +1360,118 @@ async function buildPreparedOpeningBriefInput(sessionRoot, executionPlan) {
         },
     };
 }
-function parseReviewInvokeOutput(stdout) {
-    for (const line of [...stdout].reverse()) {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith("{"))
-            continue;
-        try {
-            return JSON.parse(trimmed);
-        }
-        catch {
-            // Keep looking: progress messages are not JSON.
-        }
-    }
-    throw new Error("review invocation completed without a structured JSON result.");
-}
-function isReviewInvokeShape(value) {
-    if (value === null || typeof value !== "object")
-        return false;
-    const reviewResult = value.review_result;
-    return reviewResult !== null && typeof reviewResult === "object";
+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 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"),
+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),
     };
-    const entries = [];
-    for (const [key, filePath] of Object.entries(candidates)) {
-        if (await fileExists(filePath))
-            entries.push([key, filePath]);
+    if (executionPlan) {
+        llmPresentation.openingBrief = buildOpeningBriefPresentation(await buildPreparedOpeningBriefInput(sessionRoot, executionPlan));
     }
-    return Object.fromEntries(entries);
+    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"));
-    return buildReviewPipelineExecutionLedger({
-        sessionRoot: args.sessionRoot,
-        artifactRefs: args.artifactRefs,
-        executionPlan: args.executionPlan,
-        executionResult: args.executionResult,
-        reviewRunManifest,
-        lensCompletionBarrier,
-    });
+    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")
@@ -1319,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();
     }
@@ -1331,8 +1749,8 @@ export function createOntoReviewCoreApi(options = {}) {
     const ontoHome = resolveRequiredOntoHome(options.ontoHome);
     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);
@@ -1347,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)
@@ -1368,141 +1794,223 @@ 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;
-                        }
-                    },
-                }
-                : undefined;
-            const captured = await withCapturedConsole(async () => {
-                const exitCode = await runReviewInvokeCli(argv);
-                if (exitCode !== 0) {
-                    throw new Error(`review invocation failed with exit code ${exitCode}`);
-                }
-                return exitCode;
-            }, captureObserver);
-            const parsed = parseReviewInvokeOutput(captured.stdout);
-            if (!isReviewInvokeShape(parsed)) {
-                throw new Error("review invocation returned an unexpected result shape.");
-            }
-            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 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 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 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 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 llmPresentation = {
-                openingBrief: buildOpeningBriefPresentation(openingBriefInput),
-                progress: buildProgressPresentation(progressInput),
-                ...(progressInput.halt
-                    ? {
-                        halt: buildHaltPresentation({
-                            ...progressInput,
-                            presentation_kind: "halt",
+            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,
+                    };
+                }
+                catch (error) {
+                    if (observedSessionRoot) {
+                        await updateActiveAttemptTerminal({
+                            sessionRoot: observedSessionRoot,
+                            status: "failed",
+                            errorMessage: error instanceof Error ? error.message : String(error),
+                        });
                     }
-                    : {}),
-                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,
-            };
+                    throw error;
+                }
+            })();
+            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;
+            }
+            return fullRun;
         },
         async continueReview(request) {
             const resolvedSessionRoot = path.resolve(request.sessionRoot);
@@ -1530,10 +2038,36 @@ export function createOntoReviewCoreApi(options = {}) {
                 expected: sessionMetadataPath,
                 actual: executionPlan.session_metadata_path,
             });
-            await validateReviewExecutionPlanSessionBoundary({
+            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,
@@ -1618,6 +2152,15 @@ export function createOntoReviewCoreApi(options = {}) {
                 });
             };
             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);
@@ -1645,6 +2188,12 @@ export function createOntoReviewCoreApi(options = {}) {
                 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);
@@ -1656,6 +2205,11 @@ export function createOntoReviewCoreApi(options = {}) {
                         : {}),
                     restored_artifact_backups: restoredArtifactBackups,
                 });
+                await updateActiveAttemptTerminal({
+                    sessionRoot: resolvedSessionRoot,
+                    status: "failed",
+                    errorMessage,
+                });
                 throw new ReviewContinuationError({
                     message: `Review continuation failed: ${errorMessage}`,
                     originalError: error,
@@ -1681,6 +2235,7 @@ export function createOntoReviewCoreApi(options = {}) {
             return {
                 sessionId: postStatus.sessionId,
                 sessionRoot: resolvedSessionRoot,
+                decision: "executed",
                 status: postStatus.status,
                 continuationPlan,
                 continuationAttempt: {
@@ -1705,6 +2260,77 @@ export function createOntoReviewCoreApi(options = {}) {
                     : {}),
             };
         },
+        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: 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) {
             const resolvedSessionRoot = path.resolve(sessionRoot);
             const artifactRefs = await collectArtifactRefs(resolvedSessionRoot);
@@ -1721,15 +2347,22 @@ export function createOntoReviewCoreApi(options = {}) {
                 ? 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,
@@ -1761,6 +2394,10 @@ export function createOntoReviewCoreApi(options = {}) {
                     ...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") {
@@ -1774,6 +2411,10 @@ export function createOntoReviewCoreApi(options = {}) {
                     ...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) {
@@ -1787,6 +2428,10 @@ export function createOntoReviewCoreApi(options = {}) {
                     ...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 {
@@ -1799,16 +2444,28 @@ export function createOntoReviewCoreApi(options = {}) {
                 ...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({
@@ -1835,12 +2492,32 @@ 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,
@@ -1860,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 {