onto-mcp 0.3.2 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # Onto MCP
 
 `onto-mcp` is the TypeScript product core for ontology-as-code review. The
-public interface is MCP-native; repository-local npm scripts remain development
-harnesses for verification and debugging.
+public interface is MCP-native; repository-local verification harnesses are
+internal and are not product entrypoints.
 
 ```text
 .onto contracts and domain documents
@@ -34,19 +34,30 @@ cross-process goal contract lives at
 7. `ReviewRecord` assembly
 8. concise human-readable final output
 
-`reconstruct` now has a current design contract under
-`.onto/processes/reconstruct/`, material-aware runtime helpers, and a bounded
-direct-call integral runner. The runner classifies target material, expands
-directory targets into per-member source observations, writes the initial source
-frontier, runs reconstruct lens judgments and exploration synthesis through a
-configured LLM provider, validates evidence refs, computes deterministic metrics, and writes
-`final-output.md`, `reconstruct-run-manifest.yaml`, and the primary
-`reconstruct-record.yaml`. Code is the first fixture; the runner path is shared
-with spreadsheet/document/database material through source profiles and
-material-specific observers. The current public run path defaults to
+`reconstruct` is the next active productization slice. It has active contracts
+under `.onto/processes/reconstruct/`, MCP/direct-call wiring, material-aware
+runtime helpers, and a bounded integral runner. Code is the first partially
+wired runtime profile. Spreadsheet, document, and database profiles are
+contract-active but runtime-planned until their adapters are implemented; mixed
+targets are partial-composite only. The current runner classifies target
+material, expands supported directory targets into per-member source
+observations, writes the initial source frontier, runs reconstruct lens
+judgments and exploration synthesis through a configured LLM provider, validates
+available evidence refs, computes deterministic metrics, and writes
+`reconstruct-run-manifest.yaml`. It emits `final-output.md` and the primary
+`reconstruct-record.yaml` only through the validated handoff path after
+`handoff-decision-validation.yaml` and
+`reconstruct-run-manifest.pre-handoff-validation.yaml` pass; otherwise terminal
+projection must be blocked or limitation-backed. The final
+`reconstruct-run-manifest.post-publication-validation.yaml` is a post-publication audit for the
+complete manifest after final output and record refs exist. The
+current public run path defaults to
 `direct_call` semantic authoring and host-mediated confirmation. It fails loud
-when provider/model/credentials, LLM-authored artifact shape, or runtime gates
-are invalid; domain context selection remains deferred.
+when provider/model/credentials, LLM-authored artifact shape, unsupported
+material, or runtime gates are invalid. Optional reconstruct `domain` input
+admits that domain's `competency_qs.md` into the run governing snapshot for
+domain competency trace validation; there is no separate active
+domain competency selection artifact.
 `evolve` has a future material-kind adapter contract at
 `.onto/processes/evolve/material-kind-adapter-contract.md`, but no active
 runtime or MCP tool. `learn` and `govern` remain separate design slices.
@@ -65,6 +76,36 @@ Start the MCP server:
 onto mcp
 ```
 
+### Register with hosts
+
+`npm install` only puts the `onto` binary on PATH — each MCP host (Claude Code,
+Codex, Claude Desktop, Cursor) must additionally be told to launch it. `onto
+register` does that in one step. The same global binary is shared by every host.
+
+```bash
+onto register                  # interactive: pick detected hosts (terminal only)
+onto register --all --yes      # non-interactive: every detected host
+onto register --hosts cursor,codex --yes
+onto register --list           # show detection status, write nothing
+onto register --hosts cursor --dry-run   # preview the change, write nothing
+```
+
+Mechanism per host:
+
+| Host | How it is registered |
+|---|---|
+| Claude Code | `claude mcp add onto -s user -- onto mcp` (user scope = all projects) |
+| Codex CLI | `codex mcp add onto -- onto mcp` |
+| Claude Desktop | edits `mcpServers.onto` in `claude_desktop_config.json` |
+| Cursor | edits `mcpServers.onto` in `~/.cursor/mcp.json` |
+
+For the CLI-backed hosts, `onto register` prefers the official CLI and falls back
+to printing manual instructions when it is not on PATH. JSON edits preserve any
+servers already present and are idempotent (re-running reports `skipped`).
+Registration writes only host-owned config; it never writes onto runtime data.
+Restart the host app after registering to pick up the new server. Override the
+launched command or server name with `--command <cmd>` / `--name <id>`.
+
 For project-local installs, add `onto-mcp` to the project and run the local
 binary:
 
@@ -86,7 +127,7 @@ Available MCP tools:
 | `onto.list_domains` | List available domain ids |
 | `onto.list_source_profiles` | List reconstruct source profiles |
 | `onto.observe_source` | Materialize reconstruct material profile, inventory, source observations, and initial record |
-| `onto.validate_reconstruct_directive` | Validate LLM-authored reconstruct directive files |
+| `onto.validate_reconstruct_directive` | Validate LLM-authored reconstruct artifacts |
 | `onto.reconstruct` | Run the material-aware direct-call reconstruct path with runtime validation gates |
 | `onto.reconstruct_status` | Read reconstruct session status, progress, counts, and artifact refs |
 | `onto.reconstruct_result` | Read `reconstruct-record.yaml`, run manifest, progress projection, and final output |
@@ -95,6 +136,20 @@ MCP results include `llmPresentation` prompts. The runtime supplies bounded
 facts; the host LLM should use those prompts to explain the opening brief and
 final result to the user without inventing settings or findings.
 
+When `onto.review`, `onto.review_continue`, or `onto.reconstruct` starts, the
+runtime writes a session-local `runtime-events.ndjson` stream and tries to open
+`scripts/onto-runtime-watch.sh` in a supported terminal split/tab. Current
+automatic attach targets are `tmux`, Codex Desktop with a configured launcher
+path, Warp, Cursor, iTerm2, and Apple Terminal. Codex Desktop attach never uses
+UI keystroke automation by default; set
+`ONTO_RUNTIME_WATCHER_CODEX_APP_LAUNCHER=/absolute/path/to/launcher.sh` to
+enable it. The launcher receives `watcherScript`, `sessionRoot`, `projectRoot`,
+and `watcherCommand` as positional arguments. Unsupported hosts can set
+`ONTO_RUNTIME_WATCHER_COMMAND` with a launcher template containing
+`{watcherCommand}`. Each stream line is source-tagged by pipeline,
+unit/stage/process, and stdout/stderr/status. Set `ONTO_RUNTIME_WATCHER=0` to
+disable the automatic terminal attach.
+
 Minimal reconstruct MCP call shape:
 
 ```json
@@ -104,6 +159,7 @@ Minimal reconstruct MCP call shape:
     "projectRoot": "/path/to/project",
     "targetRefs": ["src/example.ts"],
     "intent": "Create a bounded reconstruct Seed from this target.",
+    "domain": "ontology",
     "sessionRoot": ".onto/reconstruct/example-run"
   }
 }
@@ -114,36 +170,9 @@ Minimal reconstruct MCP call shape:
 with an `llm` provider/model before running. Test-only mock helpers are not
 product completion evidence.
 
-Repository-local development harness:
-
-```bash
-npm run review:invoke -- <target> "<intent>"
-```
-
-`review:invoke` prints a structured start preview before execution begins:
-
-- review target and filesystem boundary
-- request intent
-- selected domain and selection mode
-- review mode and lens ids
-- execution mode, seats, deliberation mode, concurrency
-- model auth/provider/model/effort/service tier
-- settings locations and MCP/dev-harness override points
-
-During execution, the runner prints numbered progress markers for the bounded
-review stages. At completion, it prints a structured result overview:
-
-- outcome status and deliberation status
-- target/domain/review mode
-- planned, participating, and degraded lens counts
-- comprehensive `Final Review Result` explanation from synthesize
-- issue count plus severity/timing/closure classification
-- top problem definitions from `problem-framing.yaml`
-- primary artifact paths
-
 For MCP clients, prefer the `llmPresentation.openingBrief` and
-`llmPresentation.finalResult` prompt/input pairs over CLI stdout when presenting
-start and finish explanations.
+`llmPresentation.finalResult` prompt/input pairs when presenting start and
+finish explanations.
 
 Runtime hardening is available as a development verification harness:
 
@@ -235,53 +264,84 @@ Primary outputs:
 
 A reconstruct session writes artifacts under `.onto/reconstruct/<session-id>/`.
 
-Implemented direct-call, runtime-gated outputs:
+Target runtime-gated outputs below are a non-authoritative quick map. The active
+artifact and gate catalog authority is
+`.onto/processes/reconstruct/reconstruct-contract-registry.yaml`.
 
 | Artifact | Owner | Purpose |
 |---|---|---|
 | `target-material-profile.yaml` | runtime | detected `target_material_kind`, support status, and selected source profiles |
+| `target-material-profile-validation.yaml` | runtime | material profile gate status and selected-profile closure |
 | `source-inventory.yaml` | runtime | material-specific inventory units and scan boundary |
-| `initial-source-frontier.yaml` | runtime | first observation frontier derived from inventory |
-| `source-observations.yaml` | runtime | structural observations with stable evidence ids |
+| `source-observations.yaml` | runtime | structural observations with stable evidence ids and source content fingerprints |
 | `source-observation-directive.yaml` | host LLM author | selected observations for evidence use |
 | `source-observation-directive-validation.yaml` | runtime | validation of selected observation refs |
+| `*.reuse-provenance.yaml` | runtime | sidecar proof that same-session resume reuses authored YAML only when invocation, source, governing snapshot, and artifact hash match |
 | `rounds/<round-id>/lens-judgments/*.yaml` | host LLM author | reconstruct lens judgments over trusted observations |
 | `rounds/<round-id>/exploration-synthesis.yaml` | host LLM author | integrated gaps and next-source needs |
 | `rounds/<round-id>/source-frontier.yaml` | host LLM author | requested next source refs or no-next-frontier rationale |
-| `rounds/<round-id>/source-frontier-validation.yaml` | runtime | boundary, duplicate, and inventory validation for the frontier |
-| `seed-candidate.yaml` | host LLM author | evidence-backed Seed candidate with separate `claim_id` and user-facing `name` |
-| `seed-candidate-validation.yaml` | runtime | Seed claim name, shape, and evidence-ref validation |
-| `claim-realization-map.yaml` | host LLM author | claim-level evidence stance |
-| `claim-realization-map-validation.yaml` | runtime | claim id, stance enum, and evidence linkage validation |
-| `seed-confirmation.yaml` | host/user mediated | accepted, rejected, partial, or deferred Seed confirmation |
-| `seed-confirmation-validation.yaml` | runtime | confirmation transition validation and derived claim sets |
-| `competency-questions.yaml` | host LLM author | questions linked to confirmed claims |
-| `competency-questions-validation.yaml` | runtime | CQ id, eligible-claim coverage, claim-link, and evidence validation |
-| `competency-question-assessment.yaml` | host LLM author | answer status for every authoritative CQ |
-| `competency-question-assessment-validation.yaml` | runtime | exactly-once CQ assessment validation |
+| `rounds/<round-id>/source-frontier-validation.yaml` | runtime | frontier validation plus explicit dependency proof on `target-material-profile-validation.yaml` |
+| `candidate-inventory.yaml` | host LLM author | salient object, actor, action, workflow, permission, data source, constraint, and concept candidates |
+| `candidate-disposition.yaml` | host LLM author | one disposition for every salient candidate, including planned target seed refs for promoted candidates |
+| `candidate-disposition-validation.yaml` | runtime | inventory/disposition closure and projection validation |
+| `ontology-seed.yaml` | host LLM author | primary actionable ontology seed |
+| `ontology-seed-validation.yaml` | runtime | seed layer, id, binding, disposition, and evidence-ref validation |
+| `claim-realization-map.yaml` | host LLM author | one realization stance for every ontology seed claim |
+| `claim-realization-map-validation.yaml` | runtime | seed-claim closure and realization evidence validation |
+| `competency-questions.yaml` | host LLM author | questions linked to the declared purpose, seed layers, registry facets, proof-contract refs, admitted domain competency ids, and diagnostic/claim-based dispositions |
+| `competency-questions-validation.yaml` | runtime | question id, derived evidence scope, seed-link, evidence, registry facet/proof refs, exactly-one admitted domain competency coverage, and run-manifest admitted domain trace validation |
+| `competency-question-assessment.yaml` | host LLM author + runtime projections | answer status, required seed refs, evidence refs, and downstream effect for every authoritative CQ |
+| `competency-question-assessment-validation.yaml` | runtime | exactly-once CQ assessment validation plus answer-status/downstream-effect and seed/evidence closure |
+| `seed-confirmation.yaml` | host/user mediated | confirmation or limitation decision over validated seed claims before CQ authoring |
+| `seed-confirmation-validation.yaml` | runtime | confirmation closure and CQ eligibility over the validated seed; terminal readiness is owned by `handoff-decision-validation.yaml` |
 | `failure-classification.yaml` | host LLM author | material failure and gap classification |
 | `failure-classification-validation.yaml` | runtime | failure enum, linkage, and materiality validation |
 | `revision-proposal.yaml` | host LLM author | bounded revision/deferral proposals |
 | `revision-proposal-validation.yaml` | runtime | proposal id, target, action, and regression guard validation |
-| `reconstruct-metrics.yaml` | runtime | deterministic counts, unresolved/deferred counts, and pass rate |
-| `stop-decision.yaml` | host LLM author | stop, continue, or ask-user decision based on metrics |
-| `final-output.md` | host LLM author | user-facing result grounded in artifacts and provenance-checked by runtime |
-| `reconstruct-run-manifest.yaml` | runtime | step refs, `performed_by` provenance, execution profile, and happy-path scope |
+| `reconstruct-metrics.yaml` | runtime | deterministic counts, answerability bucket counts, unresolved/deferred counts, and pass rate |
+| `stop-decision.yaml` | host LLM author | proposed stop/continue/ask-user decision; not the readiness authority |
+| `handoff-decision-validation.yaml` | runtime | canonical readiness projection from runtime gates plus `stop-decision.yaml` consistency before final output and record projection |
+| `final-output.md` | host LLM author + runtime footer | user-facing result grounded in artifacts, seed validity, and handoff limitations |
+| `reconstruct-run-manifest.yaml` | runtime | step refs, `performed_by` provenance, execution profile, requested domain ids, and happy-path scope |
+| `reconstruct-run-manifest.post-publication-validation.yaml` | runtime | post-publication registry hash, active contract hash, source profile migration, validator, reference-standard, pattern-catalog URI/snapshot, version, and migration snapshot consistency after final output and record refs exist |
 | `reconstruct-record.yaml` | runtime | primary structured reconstruct artifact |
 
-Current deferred reconstruct artifacts are recorded in
-`reconstruct-run-manifest.yaml` under `happy_path_scope.deferred_artifacts`:
-`domain_context_selection` and `domain_context_selection_validation`. Those
-require additional domain selection semantics and are outside the current
-direct-call path.
-
-The reconstruct design contract also defines validation artifacts for those
-stages, stable reconstruct stage ids, cross-artifact id authority, and progress
-UX expectations in `.onto/processes/reconstruct/reconstruct-execution-ux-contract.md`.
-Seed discovery is further constrained by
-`.onto/processes/reconstruct/top-level-concept-discovery-contract.md`, which
-defines the Seed as a purpose-relative top-level concept discovery artifact
-rather than a full ontology or broad claim ledger.
+The runtime keeps full source evidence in `source-observations.yaml`. LLM
+authoring calls may receive compact prompt projections, such as selected
+observations with shortened text excerpts, while validation still checks all
+generated evidence refs against the full artifact truth.
+Terminal projection uses `handoff-decision-validation.yaml.readiness_projection`
+as the readiness authority and requires both validated handoff and a validated
+pre-handoff run-manifest snapshot. The final
+`reconstruct-run-manifest.post-publication-validation.yaml` is the post-publication audit for the
+complete manifest after `final-output.md` and `reconstruct-record.yaml` refs are
+known; it is not a prerequisite for the pre-handoff readiness projection. The
+same artifact records `gate_projection[]`, where each
+active gate is evaluated through the registry `required_when_predicate_catalog`
+before validation status is required.
+
+Contract-planned conditional proof authorities are not emitted by the current
+runtime until their validator surfaces are implemented:
+
+| planned artifact | planned authority |
+|---|---|
+| `rounds/<round-id>/source-observation-delta.yaml` / `rounds/<round-id>/source-observation-delta-validation.yaml` | multi-round observation lineage before newly observed frontier evidence is used |
+| `rounds/<round-id>/source-observation-reentry-validation.yaml` | post-use re-entry validation for frontier-triggered observations cited downstream |
+| `query-proofs.yaml` / `query-proofs-validation.yaml` | executable query/API proof rows when queryability or implementation access is claimed |
+| `visualization-proofs.yaml` / `visualization-proofs-validation.yaml` | visualization surface proof rows when static or overview visualization is claimed |
+| `graph-exploration-proofs.yaml` / `graph-exploration-proofs-validation.yaml` | graph navigation/exploration proof rows when traversal or large-graph exploration is claimed |
+| `required-when-evaluation.yaml` / `required-when-evaluation-validation.yaml` | standalone audited conditional-gate applicability trace; the current terminal handoff projection embeds predicate input/result details in `handoff-decision-validation.yaml.gate_projection[]` |
+| `ontology-handoff mapping proof` | per-axis ontology handoff mapping gate once that validator is implemented |
+
+The active seed target is defined by
+`.onto/processes/reconstruct/foundry-style-ontology-seed-contract.md`.
+The full recomposition plan is
+`.onto/processes/reconstruct/actionable-ontology-seed-recomposition-design.md`.
+The active contract, source profile, lens judgment, artifact, gate, readiness, and
+projection authority registry is
+`.onto/processes/reconstruct/reconstruct-contract-registry.yaml`.
+The seed is valid only when process completion, seed validation, downstream
+gates, and handoff limitations are reported separately and consistently.
 
 ## Repository Map
 
@@ -305,6 +365,5 @@ npm run check:ts-core
 npm run build:ts-core
 npm run test:mcp:review
 npm run test:review:hardening
-npm run test:e2e
 git diff --check
 ```

package/dist/cli.js

@@ -7,8 +7,7 @@ import { readOntoVersion } from "./core-runtime/release-channel/release-channel.
  * Public binary surface for the MCP-native product.
  *
  * Product tools are exposed through MCP (`onto mcp`). Review and other
- * runtime flows are no longer public `onto <activity>` CLI commands. The
- * `npm run review:*` scripts remain internal development harnesses.
+ * runtime flows are no longer public `onto <activity>` CLI commands.
  */
 function loadOntoEnvFile(filePath) {
     if (!fs.existsSync(filePath))
@@ -35,10 +34,11 @@ function loadOntoEnvFile(filePath) {
 }
 function printHelp() {
     console.log([
-        "Usage: onto mcp",
+        "Usage: onto <command>",
         "",
         "Active interface:",
         "  mcp            Start the MCP stdio tool server",
+        "  register       Register the onto MCP server into supported hosts",
         "",
         "Available MCP tools:",
         "  onto.review",
@@ -54,9 +54,6 @@ function printHelp() {
         "  onto.reconstruct_status",
         "  onto.reconstruct_result",
         "",
-        "Development harness:",
-        "  npm run review:invoke -- <target> \"<intent>\"",
-        "",
         "Options:",
         "  --version, -v  Show version",
         "  --help, -h     Show this help",
@@ -65,8 +62,7 @@ function printHelp() {
 function unsupportedCommandMessage(subcommand) {
     return [
         `[onto] Unsupported public CLI subcommand: ${subcommand}`,
-        "Active public command: onto mcp",
-        "Development harness: npm run review:invoke -- <target> \"<intent>\"",
+        "Active public commands: onto mcp, onto register",
     ].join("\n");
 }
 async function main() {
@@ -79,6 +75,10 @@ async function main() {
             const { startMcpServer } = await import("./mcp/server.js");
             return startMcpServer();
         }
+        case "register": {
+            const { runRegister } = await import("./core-runtime/onboard/register.js");
+            return runRegister(argv.slice(1));
+        }
         case "--version":
         case "-v": {
             const version = await readOntoVersion();

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

@@ -4,14 +4,19 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { RECONSTRUCT_STAGE_IDS, } from "../core-runtime/reconstruct/artifact-types.js";
 import { materializeReconstructPreparationArtifacts, } from "../core-runtime/reconstruct/materialize-preparation.js";
+import { writeTargetMaterialProfileValidationArtifact, } from "../core-runtime/reconstruct/material-profile-validation.js";
 import { assembleReconstructRecord, } from "../core-runtime/reconstruct/record.js";
 import { createAutoAcceptReconstructConfirmationProvider, createDirectCallReconstructConfirmationProvider, createDirectCallReconstructDirectiveAuthor, createMockReconstructDirectiveAuthor, runReconstruct, } from "../core-runtime/reconstruct/run.js";
 import { resolveSettingsChain, } from "../core-runtime/discovery/settings-chain.js";
+import { resolveOntoHome, } from "../core-runtime/discovery/onto-home.js";
 import { resolveLlmProviderConfig, } from "../core-runtime/llm/llm-caller.js";
-import { writeSeedCandidateValidationArtifact, } from "../core-runtime/reconstruct/seed-candidate-validation.js";
+import { writeActionableOntologySeedValidationArtifact, writeCandidateDispositionValidationArtifact, } from "../core-runtime/reconstruct/actionable-seed-validation.js";
 import { writeSourceObservationDirectiveValidationArtifact, } from "../core-runtime/reconstruct/directive-validation.js";
 import { loadReconstructSourceProfiles, } from "../core-runtime/reconstruct/source-profiles.js";
+import { assertReconstructDomainId, } from "../core-runtime/reconstruct/domain-id.js";
 import { buildReconstructPipelineExecutionLedger, } from "../core-runtime/reconstruct/pipeline-execution-ledger.js";
+import { spawnRuntimeWatcherPane, } from "../core-runtime/cli/spawn-watcher.js";
+import { appendRuntimeStatusEventSync, runWithRuntimeObservationContext, } from "../core-runtime/observability/runtime-stream-observation.js";
 async function directoryExists(directoryPath) {
     try {
         const stat = await fs.stat(directoryPath);
@@ -53,8 +58,17 @@ async function resolveProfilesRoot(args) {
 function defaultDirectiveValidationOutputPath(request) {
     return path.join(path.dirname(path.resolve(request.directivePath)), "source-observation-directive-validation.yaml");
 }
-function defaultSeedValidationOutputPath(request) {
-    return path.join(path.dirname(path.resolve(request.seedCandidatePath)), "seed-candidate-validation.yaml");
+function defaultCandidateDispositionValidationOutputPath(request) {
+    return path.join(path.dirname(path.resolve(request.candidateDispositionPath)), "candidate-disposition-validation.yaml");
+}
+function defaultOntologySeedValidationOutputPath(request) {
+    return path.join(path.dirname(path.resolve(request.ontologySeedPath)), "ontology-seed-validation.yaml");
+}
+function defaultReconstructContractRegistryPath(ontoHome) {
+    return path.join(path.resolve(ontoHome ?? process.cwd()), ".onto", "processes", "reconstruct", "reconstruct-contract-registry.yaml");
+}
+function reconstructContractRegistryPathFromProfilesRoot(profilesRoot) {
+    return path.resolve(profilesRoot, "..", "reconstruct-contract-registry.yaml");
 }
 async function readYamlArtifact(filePath) {
     return parseYaml(await fs.readFile(filePath, "utf8"));
@@ -131,19 +145,30 @@ function deriveReconstructProgress(args) {
                 args.record.validation_summary.unresolved_count,
             passRate: args.metrics?.pass_rate ?? args.record.validation_summary.pass_rate,
         },
+        answerabilitySummary: args.metrics
+            ? {
+                declaredQuestionCount: args.metrics.answerability_summary.declared_question_count,
+                supportedQuestionCount: args.metrics.answerability_summary.supported_question_count,
+                deferredQuestionCount: args.metrics.answerability_summary.deferred_question_count,
+                unsupportedQuestionCount: args.metrics.answerability_summary.unsupported_question_count,
+                supportedActionCount: args.metrics.answerability_summary.supported_action_count,
+                unsupportedActionCount: args.metrics.answerability_summary.unsupported_action_count,
+            }
+            : null,
         stages,
     };
 }
 function recordArtifactRefsFromPreparation(refs) {
     return {
         target_material_profile: refs.target_material_profile,
+        target_material_profile_validation: refs.target_material_profile_validation ?? null,
         source_inventory: refs.source_inventory,
         initial_source_frontier: refs.initial_source_frontier,
         source_observations: refs.source_observations,
     };
 }
 export function createOntoReconstructCoreApi(options = {}) {
-    const ontoHome = options.ontoHome ? path.resolve(options.ontoHome) : undefined;
+    const ontoHome = resolveOntoHome(options.ontoHome);
     return {
         async listSourceProfiles(projectRoot = process.cwd()) {
             const resolvedProjectRoot = path.resolve(projectRoot);
@@ -173,10 +198,19 @@ export function createOntoReconstructCoreApi(options = {}) {
                 filesystemAllowedRoots: request.filesystemAllowedRoots?.map((root) => resolveFromBase(projectRoot, root)) ??
                     [projectRoot],
             });
+            const targetMaterialProfileValidationPath = path.join(sessionRoot, "target-material-profile-validation.yaml");
+            await writeTargetMaterialProfileValidationArtifact({
+                targetMaterialProfilePath: preparationRefs.target_material_profile,
+                registryPath: reconstructContractRegistryPathFromProfilesRoot(profilesRoot),
+                outputPath: targetMaterialProfileValidationPath,
+            });
             const recordPath = path.join(sessionRoot, "reconstruct-record.yaml");
             const reconstructRecord = await assembleReconstructRecord({
                 sessionRoot,
-                artifactRefs: recordArtifactRefsFromPreparation(preparationRefs),
+                artifactRefs: recordArtifactRefsFromPreparation({
+                    ...preparationRefs,
+                    target_material_profile_validation: targetMaterialProfileValidationPath,
+                }),
                 outputPath: recordPath,
             });
             return {
@@ -207,26 +241,75 @@ export function createOntoReconstructCoreApi(options = {}) {
             const llmConfig = resolveLlmProviderConfig({ config: settings });
             const semanticAuthorRealization = request.semanticAuthorRealization ?? "direct_call";
             const confirmationProviderRealization = request.confirmationProviderRealization ?? "direct_call";
+            if (request.domain) {
+                assertReconstructDomainId(request.domain, "reconstruct domain");
+            }
             const directiveAuthor = semanticAuthorRealization === "mock"
                 ? createMockReconstructDirectiveAuthor()
                 : createDirectCallReconstructDirectiveAuthor({ llmConfig });
             const confirmationProvider = confirmationProviderRealization === "mock"
                 ? createAutoAcceptReconstructConfirmationProvider()
                 : createDirectCallReconstructConfirmationProvider({ llmConfig });
-            return runReconstruct({
-                projectRoot,
-                targetRefs,
-                intent: request.intent,
+            appendRuntimeStatusEventSync({
+                pipeline: "reconstruct",
                 sessionRoot,
-                profilesRoot,
-                semanticAuthorRealization,
-                confirmationProviderRealization,
-                directiveAuthor,
-                confirmationProvider,
-                llmConfig,
-                filesystemAllowedRoots: request.filesystemAllowedRoots?.map((root) => resolveFromBase(projectRoot, root)) ??
-                    [projectRoot],
+                sourceLabel: "onto.reconstruct",
+                message: "reconstruct session starting",
+                stageId: "start",
+            });
+            const watcherResult = spawnRuntimeWatcherPane(projectRoot, sessionRoot, ontoHome);
+            appendRuntimeStatusEventSync({
+                pipeline: "reconstruct",
+                sessionRoot,
+                sourceLabel: "runtime-watcher",
+                message: watcherResult.spawned
+                    ? `watcher ${watcherResult.dry_run ? "detected" : "attached"} via ${watcherResult.mechanism}`
+                    : `watcher not attached: ${watcherResult.reason ?? "unknown reason"}`,
+                stageId: "start",
             });
+            try {
+                const result = await runWithRuntimeObservationContext({
+                    pipeline: "reconstruct",
+                    sessionRoot,
+                    source: {
+                        kind: "llm",
+                        label: "reconstruct",
+                    },
+                }, () => runReconstruct({
+                    projectRoot,
+                    targetRefs,
+                    intent: request.intent,
+                    sessionRoot,
+                    profilesRoot,
+                    ...(request.domain ? { domain: request.domain } : {}),
+                    ...(request.resumeMode ? { resumeMode: request.resumeMode } : {}),
+                    semanticAuthorRealization,
+                    confirmationProviderRealization,
+                    directiveAuthor,
+                    confirmationProvider,
+                    llmConfig,
+                    filesystemAllowedRoots: request.filesystemAllowedRoots?.map((root) => resolveFromBase(projectRoot, root)) ??
+                        [projectRoot],
+                }));
+                appendRuntimeStatusEventSync({
+                    pipeline: "reconstruct",
+                    sessionRoot,
+                    sourceLabel: "onto.reconstruct",
+                    message: "reconstruct session completed",
+                    stageId: "complete",
+                });
+                return result;
+            }
+            catch (error) {
+                appendRuntimeStatusEventSync({
+                    pipeline: "reconstruct",
+                    sessionRoot,
+                    sourceLabel: "onto.reconstruct",
+                    message: `reconstruct session failed: ${error instanceof Error ? error.message : String(error)}`,
+                    stageId: "complete",
+                });
+                throw error;
+            }
         },
         async validateSourceObservationDirective(request) {
             return writeSourceObservationDirectiveValidationArtifact({
@@ -237,23 +320,26 @@ export function createOntoReconstructCoreApi(options = {}) {
                     : defaultDirectiveValidationOutputPath(request),
             });
         },
-        async validateSeedCandidate(request) {
-            return writeSeedCandidateValidationArtifact({
-                seedCandidatePath: path.resolve(request.seedCandidatePath),
+        async validateCandidateDisposition(request) {
+            return writeCandidateDispositionValidationArtifact({
+                candidateInventoryPath: path.resolve(request.candidateInventoryPath),
+                candidateDispositionPath: path.resolve(request.candidateDispositionPath),
                 sourceObservationsPath: path.resolve(request.sourceObservationsPath),
+                registryPath: path.resolve(request.registryPath ?? defaultReconstructContractRegistryPath(ontoHome)),
                 outputPath: request.outputPath
                     ? path.resolve(request.outputPath)
-                    : defaultSeedValidationOutputPath(request),
-                ...(request.sourceObservationDirectivePath
-                    ? {
-                        sourceObservationDirectivePath: path.resolve(request.sourceObservationDirectivePath),
-                    }
-                    : {}),
-                ...(request.sourceObservationDirectiveValidationPath
-                    ? {
-                        sourceObservationDirectiveValidationPath: path.resolve(request.sourceObservationDirectiveValidationPath),
-                    }
-                    : {}),
+                    : defaultCandidateDispositionValidationOutputPath(request),
+            });
+        },
+        async validateActionableOntologySeed(request) {
+            return writeActionableOntologySeedValidationArtifact({
+                ontologySeedPath: path.resolve(request.ontologySeedPath),
+                candidateDispositionPath: path.resolve(request.candidateDispositionPath),
+                sourceObservationsPath: path.resolve(request.sourceObservationsPath),
+                registryPath: path.resolve(request.registryPath ?? defaultReconstructContractRegistryPath(ontoHome)),
+                outputPath: request.outputPath
+                    ? path.resolve(request.outputPath)
+                    : defaultOntologySeedValidationOutputPath(request),
             });
         },
         async assembleRecord(request) {