ultra-builder-pro-cli 0.22.0 → 0.24.0

package/.ultra-template/docs/research/README.md

@@ -49,7 +49,7 @@ copying memory, code-graph payloads, or large source material into Ultra.
 
 ## Completion
 
-Update the affected baseline specification, record the report through `workflow.step`,
-include it in `baseline.record` evidence when material, and record unresolved work in
-the authoritative gap ledger. The final synthesis also binds the three specifications
-and research distillate. Do not create a condensed duplicate of the baseline.
+Update the affected baseline specification, register the report through typed
+`ultra.record`, reference it from the Research Stage Checkpoint, and record unresolved
+work in the authoritative gap ledger. The final synthesis also binds the baseline
+specifications and research distillate. Do not create a condensed duplicate.

package/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] — 2026-07-30
+
+### Added
+
+- Added normalized Decision Records, reversible Stage Checkpoints, bounded Context
+  Envelopes, and immutable Worker Packets as the shared evidence and handoff model
+  across Skills, Hooks, agents, SQLite, and tracked `.ultra` artifacts.
+- Added a native Grok Build plugin so Claude Code, Codex, OpenCode, Kimi Code, and
+  Grok Build share the same eleven explicit workflows and seven-tool MCP kernel.
+- Added schema 22 backup-first migration and real-history compatibility for v4.4,
+  v4.5, v0.22, and v0.23 state and team-ledger formats.
+- Added packaged `better-sqlite3` provenance, platform and Node ABI verification,
+  and durable Doctor and archive workers for every supported host.
+
+### Changed
+
+- Completed the MCP boundary reduction: Skills own adaptive semantic procedure;
+  MCP owns persistence, identity, transactions, leases, paths, recovery, and
+  irreversible safety; Hooks only observe or inject bounded context; agents consume
+  immutable Worker Packets without writing SQLite authority.
+- Folded Plan artifact publication into the accepted Plan checkpoint so a later
+  export cannot invalidate its own authority.
+- Replaced semantic supervisor failures with mutable diagnostics and repairable
+  drafts. Only corruption, unsafe paths, concurrency conflicts, permission failures,
+  and irreversible external effects remain hard blockers.
+- Made `ultra.context`, `ultra.sync`, and `ultra.doctor` own their inspection and
+  repair preflight so an older valid ledger cannot block the tools required to
+  migrate it.
+- Reduced packaged and documented MCP contracts to the exact seven public tools;
+  removed the retired fine-grained schemas, fixtures, and command bypasses.
+
+### Fixed
+
+- Fixed accepted or stale workflow runs becoming permanently self-locked after an
+  artifact changed, and made reversible stages reopenable without rewriting
+  immutable accepted history.
+- Fixed v0.23 team ledgers using `research_run_id` being rejected under the newer
+  `research_checkpoint_id` digest contract.
+- Fixed native SQLite drivers and Doctor workers being absent or unresolved in
+  installed plugins.
+- Fixed session acquisition, archive recovery, Context identity, and Worker Packet
+  cleanup paths leaving partial authority after failure.
+- Fixed installed interaction guidance failing to render each host's native question
+  surface while keeping canonical Skills host-neutral.
+
+## [0.23.0] — 2026-07-30
+
+### Added
+
+- Added a seven-tool public MCP kernel: `ultra.context`, `ultra.record`,
+  `ultra.checkpoint`, `ultra.sync`, `ultra.session`, `ultra.archive`, and
+  `ultra.doctor`.
+- Added idempotent batched recording, content-addressed Context snapshots, and
+  semantic checkpoints that commit accepted workflow authority in one model
+  round trip.
+- Added mutable diagnostic envelopes for rejected draft checkpoints and
+  archive preflights so the host model can correct or abandon the same draft.
+
+### Changed
+
+- Moved workflow sequencing and semantic judgment back into the eleven public
+  Skills. MCP now owns persistence, schema, transaction, concurrency, path,
+  recovery, and irreversible-effect boundaries instead of directing the model.
+- Reduced the unconditional `tools/list` surface from 60 fine-grained tools to
+  seven high-level tools. The 0.22 fine-grained contracts remain callable but
+  hidden for one compatibility release.
+- Made draft Changes and nonterminal workflows reversible while keeping
+  accepted revisions immutable and replaceable through a new draft.
+- Updated Claude Code, Codex, OpenCode, and Kimi assets to use the same narrow
+  capability graph while preserving each host's native question and bounded
+  worker surfaces.
+
+### Fixed
+
+- Fixed Plan drafts becoming permanently self-locked when a task or exported
+  artifact changed after validation.
+- Fixed semantic validation failures surfacing as MCP transport errors and
+  forcing models into repeated repair calls.
+- Fixed duplicate Context compilation creating competing snapshots for the
+  same semantic inputs.
+- Fixed `ultra.context` creating `.ultra` state merely by inspecting an
+  uninitialized project.
+
 ## [0.22.0] — 2026-07-30
 
 ### Added

package/README.md

@@ -2,8 +2,8 @@
 
 **An adaptive delivery harness for AI coding agents.**
 
-Ultra Builder Pro helps Claude Code, Codex, OpenCode, and Kimi Code carry a
-software project from an unclear request to a verified, recoverable delivery.
+Ultra Builder Pro helps Claude Code, Codex, OpenCode, Kimi Code, and Grok Build
+carry a software project from an unclear request to a verified, recoverable delivery.
 It keeps the user and the agent aligned, preserves project authority across
 sessions, and prevents specifications from quietly drifting away from the code.
 
@@ -44,7 +44,7 @@ Ultra Builder Pro addresses those gaps with four ideas:
    and asks the user only for material intent, scope, risk, or authorization
    decisions—normally one dependent decision at a time.
 3. **Durable project authority.** `.ultra/.runtime/state.db` records checkout-local
-   lifecycle, decisions, workflows, evidence digests, sessions, incidents, and
+   lifecycle facts, decisions, checkpoints, evidence digests, sessions, incidents, and
    recovery state across host sessions. Tracked semantic artifacts plus the
    MCP-published `.ultra/tasks/tasks.json` checkpoint carry reviewed project intent
    across Git checkouts without committing SQLite, leases, or telemetry.
@@ -65,13 +65,13 @@ flowchart TB
     U["User<br/>goals, acceptance, trade-offs, risk, and external authorization"]
 
     subgraph HOST["Supported coding host"]
-        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code"]
+        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code / Grok Build"]
         MODEL["Host agent<br/>inspect, recommend, implement, test, and review"]
         ADAPTER["Host adapter<br/>native questions, commands, tools, and lifecycle wiring"]
     end
 
     SKILLS["Eleven explicit Ultra Skills<br/>init / research / think / change / plan / dev<br/>test / review / deliver / status / doctor"]
-    MCP["Ultra MCP<br/>60 typed tools across nine families"]
+    MCP["Ultra MCP safety kernel<br/>exactly 7 public tools"]
     DB[(".ultra/.runtime/state.db<br/>SQLite lifecycle and index authority")]
     LEDGER[".ultra/tasks/tasks.json<br/>Git team checkpoint for portable baseline, Change, and task state"]
     VIEWS[".ultra/.runtime/projections<br/>checkout-local generated views"]
@@ -103,13 +103,41 @@ The responsibility split is deliberate:
 |---|---|
 | **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
 | **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
-| **Ultra MCP** | Checkout-local state, evidence references, digests, freshness, locks, valid transitions, hard recovery, and Git checkpoint publish/import |
+| **Ultra MCP** | Structure validation, durable checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery; never semantic route selection |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of MCP-owned checkpoint and generated projection paths |
 
-The MCP does not replace the model's judgment. A hook does not decide product
-strategy. A prompt does not become durable authority merely because it appeared
-in a conversation.
+The MCP does not replace the model's judgment or pre-authorize a semantic route. It
+reports draft diagnostics and commits accepted checkpoints. A hook does not decide
+product strategy. A prompt does not become durable authority merely because it
+appeared in a conversation.
+
+### The seven-tool MCP kernel
+
+The public model-facing surface is intentionally small:
+
+| Tool | Responsibility |
+|---|---|
+| `ultra.context` | Read the complete current spine without side effects |
+| `ultra.record` | Batch typed draft facts and events with idempotency |
+| `ultra.checkpoint` | Attempt one semantic stage checkpoint; rejection leaves the draft editable |
+| `ultra.sync` | Inspect, import, or publish the Git team checkpoint |
+| `ultra.session` | Own the transactional execution lease |
+| `ultra.archive` | Converge and archive through the recoverable filesystem/DB boundary |
+| `ultra.doctor` | Inspect or repair mechanical health, backup first |
+
+Retired fine-grained operation names are neither discoverable nor callable. Workflow
+prose stays in Skills, model judgment stays with the host, and SQLite records what
+happened rather than deciding what the model is allowed to think next.
+
+The enforcement gradient is:
+
+```text
+exploration and iteration: advisory
+durable semantic checkpoint: validated and recoverable
+corruption / unsafe path / real concurrency / permission: fail closed
+irreversible external effect: explicit owner authority plus fail closed
+```
 
 ### How owner intent becomes durable authority
 
@@ -121,9 +149,9 @@ flowchart TD
     CLEAR -->|"Yes"| NORMALIZE["Normalize the accepted intent"]
     CLEAR -->|"No: a material choice remains"| ASK["Ask one dependent question through the host-native question tool"]
     ASK --> NORMALIZE
-    NORMALIZE --> DECISION["Persist the normalized result through decision.*"]
-    DECISION --> APPLY["Apply it through the owning MCP operation or digest-bound artifact"]
-    APPLY --> AUTHORITY["Bind state, artifact digest, provenance, and downstream effects"]
+    NORMALIZE --> RECORD["Batch the normalized result through ultra.record"]
+    RECORD --> CHECKPOINT["Attempt the owning ultra.checkpoint when authority is ready"]
+    CHECKPOINT --> AUTHORITY["Bind state, artifact digest, provenance, and downstream effects"]
     AUTHORITY --> READBACK["Read back the authoritative result"]
     READBACK --> RESUME["Resume the exact workflow step and recommend the next explicit capability"]
 ```
@@ -136,8 +164,9 @@ and effects—not chain-of-thought, raw prompts, transcripts, or UI receipts.
 
 ## What you get
 
-- Native plugins for **Claude Code**, **OpenCode**, **Codex**, and **Kimi Code**.
-- One workflow vocabulary across all four hosts.
+- Native plugins for **Claude Code**, **OpenCode**, **Codex**, **Kimi Code**, and
+  **Grok Build**.
+- One workflow vocabulary across all five hosts.
 - Deterministic initialization for new, existing, monorepo, and older Ultra
   projects.
 - Evidence-backed greenfield research and brownfield adoption.
@@ -189,6 +218,7 @@ npx --yes ultra-builder-pro-cli@latest --claude --global
 npx --yes ultra-builder-pro-cli@latest --opencode --global
 npx --yes ultra-builder-pro-cli@latest --codex --global
 npx --yes ultra-builder-pro-cli@latest --kimi --global
+npx --yes ultra-builder-pro-cli@latest --grok --global
 ```
 
 Use `--local` instead of `--global` to install into the current project's host
@@ -299,9 +329,9 @@ already resolves the route. The normalized accepted coverage is then stored in
 - `deferred` — record the consequence and accepted owner.
 
 The catalog is not a mandatory document set or questionnaire. Omitted areas
-create no workflow rows; an explicit exclusion is recorded only when retaining
-that rationale is useful. MCP validates state, evidence, and transitions; it
-does not store or prove the preceding UI interaction.
+   create no workflow rows; an explicit exclusion is recorded only when retaining
+   that rationale is useful. MCP validates accepted checkpoints and mechanical
+   integrity; it does not store or prove the preceding UI interaction.
 
 Older projection-only Ultra projects are preserved and routed through a
 backup-first migration or rebaseline. The first supported checkpoint publication
@@ -358,19 +388,19 @@ The next piece of daily work starts with a new `ultra-change`.
 | `ultra-test` | Run the risk-selected verification profile and persist the gate result |
 | `ultra-review` | Coordinate independent specification-fidelity and engineering review |
 | `ultra-deliver` | Reconcile specifications, close local authority, and archive the change |
-| `ultra-status` | Read the current breadcrumb, blockers, evidence, and allowed transitions |
+| `ultra-status` | Read the current context, warnings, blockers, and evidence |
 | `ultra-doctor` | Diagnose installation or project-state faults and expose safe recovery |
 
-These eleven capabilities are the complete public Ultra command graph. Each capability
-returns current `allowed_transitions`; the host may recommend one, but another public
-capability starts only after an explicit user command or skill invocation.
+These eleven capabilities are the complete public Ultra command graph. The host model
+recommends the next capability from current context and owner intent; SQLite does not
+encode the semantic route. Another public capability starts only after an explicit
+user command or skill invocation.
 
 ### Command interaction graph
 
-Every solid handoff below means: the current capability returns
-`allowed_transitions`, the model recommends a route, and the owner explicitly
-invokes the next public capability. It does not mean that one public command
-silently launches another.
+Every solid handoff below means: the current capability returns context and checkpoint
+diagnostics, the model recommends a route, and the owner explicitly invokes the next
+public capability. It does not mean that one public command silently launches another.
 
 ```mermaid
 flowchart TD
@@ -425,7 +455,7 @@ health without selecting product intent.
 ```text
 .ultra/
   .runtime/                # local mutable state; ignored by Git
-    state.db               # lifecycle, index, transition, and freshness authority
+    state.db               # facts, indexes, checkpoints, leases, CAS, and recovery
     checkpoint.json        # advisory recovery projection
     projections/           # generated local task and task-context views
     backups/               # verified migration and recovery snapshots
@@ -434,17 +464,18 @@ health without selecting product intent.
     worktrees/             # registered local Git worktrees
     telemetry/             # local operational telemetry
   specs/                   # digest-bound product and architecture baseline
+  decisions/baseline/      # normalized accepted baseline decisions
   changes/
     active/<id>/           # all current Change semantics and evidence
       intent.md            # accepted Change Contract
-      findings.md          # durable Change findings
+      decisions/           # normalized accepted Change decisions
       progress.md          # generated human-readable projection
       research/            # Change-only findings and research reports
       delta/               # typed baseline overlay and semantic payloads
       documentation/       # documentation overlay and reconciliation evidence
       plan.json            # machine-readable task topology
       plan.md              # deterministic human plan projection
-      contexts/            # immutable role/task context snapshots
+      contexts/            # immutable canonical Context Envelopes
       test/                # Change-scoped test reports
       review/              # Change-scoped review workers and summary
       delivery/            # Change-scoped delivery evidence
@@ -459,8 +490,8 @@ health without selecting product intent.
 
 Together, `.ultra/` is Ultra's project-local cross-session workflow memory. The
 host model writes semantic specifications and evidence through the active
-workflow. MCP records lifecycle state, references, digests, provenance, and
-accepted intent, then rejects stale or illegal transitions. The DB is the
+capability. MCP records lifecycle state, references, digests, provenance, and
+accepted intent, then validates durable checkpoints and mechanical integrity. The DB is the
 lifecycle and index authority for one checkout; registered digest-bound files carry
 the semantic or evidence bodies that the DB references. The Git checkpoint is a
 portable, digest-chained handoff of baseline, Change, and durable task records. It is
@@ -551,12 +582,14 @@ host's existing model session.
 - **Project state is unhealthy:** invoke `ultra-doctor` or run
   `ultra-tools system doctor`. Repairs and schema migrations are backup-first.
 - **The team checkpoint disagrees with local state:** run `ultra-status`, inspect the
-  typed ledger condition, then use the recommended `task.ledger_import` or
-  `task.ledger_publish` path. Never edit `.ultra/tasks/tasks.json` by hand.
+  typed ledger condition, then use `ultra.sync` to import or publish after reviewing
+  any real conflict. Never edit `.ultra/tasks/tasks.json` by hand.
 - **A generated view disagrees with MCP:** trust `.ultra/.runtime/state.db`; never edit
   `.ultra/.runtime/projections/` by hand.
-- **A workflow appears blocked:** use `ultra-status` to read the exact current
-  workflow, blocker, owner decision, and mechanically valid transitions.
+- **A draft checkpoint is rejected:** use `ultra-status` to read the exact warnings
+  and blockers, fix the same mutable draft, and retry. If the attempt is no longer
+  relevant, leave it as history and open a new draft revision; no hidden workflow
+  state must be cancelled first.
 - **Kimi reports a native-module ABI error:** ensure an external Node.js 22+
   executable is available on `PATH`; the generated Kimi MCP launcher uses
   `env node`.
@@ -586,7 +619,7 @@ and `test:rest`.
 |---|---|
 | [Architecture](./docs/ARCHITECTURE.md) | Components, authority boundaries, and live integration paths |
 | [Workflow Lifecycle](./docs/WORKFLOW-LIFECYCLE.md) | Command ownership, transitions, invalidation, recovery, and convergence |
-| [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, and Kimi presentation details |
+| [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, Kimi Code, and Grok Build presentation details |
 | [Legacy CLI Crosswalk](./docs/LEGACY-CLI-CROSSWALK.md) | What was preserved, strengthened, or replaced from the original Ultra Builder Pro |
 | [Agent Context](./docs/AGENT-CONTEXT.md) | Context Manifest and host-agent execution contract |
 | [Plugin Isolation Contract](./docs/PLUGIN-ISOLATION-CONTRACT.md) | Plugin ownership, explicit activation, idle behavior, and user-instruction isolation |

package/adapters/_shared/codex-assets.cjs

@@ -30,44 +30,6 @@ const {
 
 const PLUGIN_NAME = 'ultra-builder-pro';
 const MANAGED_MARKER = 'Managed by Ultra Builder Pro Codex adapter.';
-const CODEX_NATIVE_MCP_REPLACEMENTS = Object.freeze({
-  'review.run': {
-    surface: 'native_custom_agents',
-    replacement: '$ultra-builder-pro:ultra-review with the installed review-* agents',
-  },
-  'review.verdict': {
-    surface: 'native_custom_agents',
-    replacement: 'review-coordinator synthesis using the Ultra unified review artifact',
-  },
-  'impact.radius': {
-    surface: 'codex_code_discovery',
-    replacement: 'indexed code graph tools when current, otherwise targeted repository reads',
-  },
-  'impact.changes': {
-    surface: 'codex_code_discovery',
-    replacement: 'git diff plus indexed code graph tools when current',
-  },
-  'impact.dependents': {
-    surface: 'codex_code_discovery',
-    replacement: 'indexed caller/dependency tracing when current, otherwise targeted repository search',
-  },
-  'skill.resolve': {
-    surface: 'plugin_skill_discovery',
-    replacement: 'Codex plugin skill discovery with explicit $ultra-builder-pro:<skill> invocation',
-  },
-  'skill.manifest': {
-    surface: 'plugin_skill_discovery',
-    replacement: 'the installed plugin skill SKILL.md and agents/openai.yaml contract',
-  },
-  'ask.question': {
-    surface: 'request_user_input',
-    replacement: 'use request_user_input when available, otherwise ask one concise direct question',
-  },
-  'ask.menu': {
-    surface: 'request_user_input',
-    replacement: 'use request_user_input when available, otherwise present one concise direct choice',
-  },
-});
 const COMMAND_NAMES = Object.freeze(CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review'));
 const SKILL_REFERENCE_NAMES = Object.freeze([
   ...COMMAND_NAMES,
@@ -77,6 +39,11 @@ const SKILL_REFERENCE_NAMES = Object.freeze([
 ]);
 const CODEX_PRIMARY_SKILLS = new Set([...COMMAND_NAMES, 'ultra-review']);
 const TEXT_EXTENSIONS = new Set(['.md', '.json', '.py', '.sh', '.txt', '.yaml', '.yml']);
+const NATIVE_PACKAGES = Object.freeze([
+  'better-sqlite3',
+  'bindings',
+  'file-uri-to-path',
+]);
 
 function titleCase(name) {
   const special = { 'cc-collab': 'Claude Code Collaboration' };
@@ -96,7 +63,7 @@ function adaptCodexPrimaryText(input, skillName) {
   let text = String(input);
   if (skillName === 'ultra-review') {
     text = text.replace(
-      /the current host's native bounded-worker\s+mechanism/g,
+      /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
       'native Codex custom agents installed for the selected review workers',
     );
   }
@@ -273,7 +240,7 @@ function buildHooksManifest(pluginRoot) {
   };
 }
 
-function copyHooks(repoRoot, pluginRoot) {
+function copyHooks(repoRoot, pluginRoot, publishedRoot = pluginRoot) {
   const sourceRoot = path.join(repoRoot, 'hooks');
   const targetRoot = path.join(pluginRoot, 'hooks');
   ensureDir(targetRoot);
@@ -287,7 +254,7 @@ function copyHooks(repoRoot, pluginRoot) {
   );
   writeAtomic(
     path.join(targetRoot, 'hooks.json'),
-    JSON.stringify(buildHooksManifest(pluginRoot), null, 2) + '\n',
+    JSON.stringify(buildHooksManifest(publishedRoot), null, 2) + '\n',
   );
 }
 
@@ -322,6 +289,8 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
       buildRoot,
       '--no-cache',
       '--quiet',
+      '-e',
+      'better-sqlite3',
     ], {
       cwd: repoRoot,
       encoding: 'utf8',
@@ -347,6 +316,8 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
       cliBuildRoot,
       '--no-cache',
       '--quiet',
+      '-e',
+      'better-sqlite3',
     ], {
       cwd: repoRoot,
       encoding: 'utf8',
@@ -386,6 +357,8 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
         workerBuildRoot,
         '--no-cache',
         '--quiet',
+        '-e',
+        'better-sqlite3',
       ], {
         cwd: repoRoot,
         encoding: 'utf8',
@@ -416,6 +389,52 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
     fs.copyFileSync(sourceFile, path.join(runtimeRoot, supportFile));
   }
 
+  const nodeModulesRoot = path.join(runtimeRoot, 'node_modules');
+  for (const packageName of NATIVE_PACKAGES) {
+    let packageFile;
+    try {
+      packageFile = require.resolve(`${packageName}/package.json`, { paths: [repoRoot] });
+    } catch (error) {
+      throw new Error(`Ultra native runtime dependency ${packageName} is unavailable: ${error.message}`);
+    }
+    copyTree(
+      path.dirname(packageFile),
+      path.join(nodeModulesRoot, packageName),
+    );
+  }
+  const nativeRelative = path.join(
+    'node_modules',
+    'better-sqlite3',
+    'build',
+    'Release',
+    'better_sqlite3.node',
+  );
+  const nativeFile = path.join(runtimeRoot, nativeRelative);
+  if (!fs.existsSync(nativeFile) || !fs.statSync(nativeFile).isFile()) {
+    throw new Error(`Ultra native SQLite driver is missing after staging: ${nativeFile}`);
+  }
+  const betterSqlitePackage = JSON.parse(fs.readFileSync(
+    path.join(nodeModulesRoot, 'better-sqlite3', 'package.json'),
+    'utf8',
+  ));
+  writeAtomic(path.join(runtimeRoot, 'native-runtime.json'), JSON.stringify({
+    schema_version: 1,
+    platform: process.platform,
+    arch: process.arch,
+    modules: process.versions.modules,
+    node_version: process.versions.node,
+    package: {
+      name: 'better-sqlite3',
+      version: betterSqlitePackage.version,
+    },
+    native_module: nativeRelative.split(path.sep).join('/'),
+    native_sha256: crypto.createHash('sha256').update(fs.readFileSync(nativeFile)).digest('hex'),
+  }, null, 2) + '\n');
+  fs.copyFileSync(
+    path.join(repoRoot, 'adapters', '_shared', 'runtime-native.cjs'),
+    path.join(runtimeRoot, 'runtime-native.cjs'),
+  );
+
   const runtimeBootstrap = runtime === 'kimi' ? `
 const fs = require('node:fs');
 const pluginRoot = path.resolve(__dirname, '..');
@@ -443,10 +462,12 @@ if (!process.env.UBP_ROOT_DIR) {
   const launcher = `'use strict';
 
 const path = require('node:path');
+const { inspectRuntimeNative } = require('./runtime-native.cjs');
 
 process.env.UBP_RUNTIME_ROOT = path.resolve(__dirname, '..');
 ${runtimeBootstrap}
 
+inspectRuntimeNative(__dirname);
 const { main } = require('./index.cjs');
 
 main().catch((error) => {
@@ -456,8 +477,8 @@ main().catch((error) => {
 `;
   writeAtomic(path.join(runtimeRoot, 'launch.cjs'), launcher);
   fs.copyFileSync(
-    path.join(repoRoot, 'mcp-server', 'breadcrumb.cjs'),
-    path.join(runtimeRoot, 'breadcrumb.cjs'),
+    path.join(repoRoot, 'mcp-server', 'hook-context.cjs'),
+    path.join(runtimeRoot, 'hook-context.cjs'),
   );
   fs.copyFileSync(
     path.join(repoRoot, 'mcp-server', 'hook-event.cjs'),
@@ -491,14 +512,6 @@ main().catch((error) => {
     path.join(specRoot, 'interaction-contract.json'),
     JSON.stringify(interactionContract(runtime), null, 2) + '\n',
   );
-  if (runtime === 'codex') {
-    fs.copyFileSync(sourceToolsFile, path.join(specRoot, 'upstream-mcp-tools.yaml'));
-    writeAtomic(path.join(specRoot, 'codex-capability-map.json'), JSON.stringify({
-      runtime: 'codex',
-      live_mcp_tools: REGISTERED_TOOLS,
-      codex_native_replacements: CODEX_NATIVE_MCP_REPLACEMENTS,
-    }, null, 2) + '\n');
-  }
   const sourceSchema = path.join(repoRoot, 'spec', 'schemas', 'state-db.sql');
   const targetSchema = path.join(specRoot, 'schemas', 'state-db.sql');
   ensureDir(path.dirname(targetSchema));
@@ -516,9 +529,49 @@ main().catch((error) => {
     launcher: path.join(runtimeRoot, 'launch.cjs'),
     bundle: path.join(runtimeRoot, 'index.cjs'),
     ultraTools: path.join(runtimeRoot, 'ultra-tools.cjs'),
+    nativeManifest: path.join(runtimeRoot, 'native-runtime.json'),
   };
 }
 
+function mcpCommand(launcher) {
+  if (process.platform === 'win32') {
+    return { command: 'node.exe', args: [launcher] };
+  }
+  return { command: '/usr/bin/env', args: ['node', launcher] };
+}
+
+function inspectInstalledRuntime(runtimeRoot) {
+  const report = {
+    status: 'healthy',
+    checks: {},
+    issues: [],
+  };
+  try {
+    const detail = require(path.join(runtimeRoot, 'runtime-native.cjs'))
+      .inspectRuntimeNative(runtimeRoot);
+    report.checks.native_runtime = { status: 'pass', ...detail };
+  } catch (error) {
+    report.status = 'degraded';
+    report.checks.native_runtime = { status: 'fail' };
+    report.issues.push({
+      code: error.code || 'RUNTIME_NATIVE_MISSING',
+      message: error.message,
+      ...(error.details || {}),
+    });
+  }
+  return report;
+}
+
+function applyNativeDoctor(report, runtimeRoot) {
+  const native = inspectInstalledRuntime(runtimeRoot);
+  report.checks = { ...(report.checks || {}), ...native.checks };
+  report.issues = [...(report.issues || []), ...native.issues];
+  if (report.status !== 'missing') {
+    report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
+  }
+  return report;
+}
+
 function pluginContentHash(pluginRoot, baseVersion) {
   const hash = crypto.createHash('sha256');
   hash.update(baseVersion);
@@ -530,13 +583,14 @@ function pluginContentHash(pluginRoot, baseVersion) {
   return hash.digest('hex').slice(0, 12);
 }
 
-function buildPlugin({ repoRoot, pluginRoot }) {
+function buildPlugin({ repoRoot, pluginRoot, publishedRoot = pluginRoot }) {
   if (fs.existsSync(pluginRoot)) {
     const marker = path.join(pluginRoot, '.ubp-managed');
-    if (!fs.existsSync(marker)) {
+    const entries = fs.readdirSync(pluginRoot);
+    if (entries.length > 0 && !fs.existsSync(marker)) {
       throw new Error(`refusing to replace unmanaged plugin directory: ${pluginRoot}`);
     }
-    removeTree(pluginRoot);
+    if (entries.length > 0) removeTree(pluginRoot);
   }
   ensureDir(pluginRoot);
 
@@ -550,14 +604,18 @@ function buildPlugin({ repoRoot, pluginRoot }) {
     installedSkills.push(name);
   }
 
-  copyHooks(repoRoot, pluginRoot);
+  copyHooks(repoRoot, pluginRoot, publishedRoot);
   const mcpRuntime = buildMcpRuntime(repoRoot, pluginRoot);
+  const command = mcpCommand(path.join(
+    publishedRoot,
+    path.relative(pluginRoot, mcpRuntime.launcher),
+  ));
   writeAtomic(path.join(pluginRoot, '.mcp.json'), JSON.stringify({
     mcpServers: {
       [PLUGIN_NAME]: {
         type: 'stdio',
-        command: process.execPath,
-        args: [mcpRuntime.launcher],
+        command: command.command,
+        args: command.args,
       },
     },
   }, null, 2) + '\n');
@@ -571,7 +629,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
   const manifest = {
     name: PLUGIN_NAME,
     version,
-    description: 'Codex-native Ultra Builder Pro workflows, agents, hooks, and MCP task state.',
+    description: 'Codex-native Ultra Builder Pro workflows with a persistent safety kernel.',
     author: { name: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors' },
     homepage: pkg.homepage,
     repository: 'https://github.com/rocky2431/ultra-builder-pro-cli',
@@ -582,7 +640,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
     interface: {
       displayName: 'Ultra Builder Pro',
       shortDescription: 'Codex-native engineering workflows and verification gates.',
-      longDescription: 'Complete Codex adaptation of Ultra Builder Pro skills, command workflows, custom agents, lifecycle hooks, and project-local MCP state.',
+      longDescription: 'Complete Codex adaptation of Ultra Builder Pro skills, command workflows, custom agents, lifecycle hooks, and a project-local persistence and safety kernel.',
       developerName: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors',
       category: 'Developer Tools',
       capabilities: ['Interactive', 'Write'],
@@ -597,7 +655,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
   };
   writeAtomic(path.join(pluginRoot, '.codex-plugin', 'plugin.json'), JSON.stringify(manifest, null, 2) + '\n');
   writeAtomic(path.join(pluginRoot, '.ubp-managed'), JSON.stringify({ source: 'ubp', adapter: 'codex', version }, null, 2) + '\n');
-  return { root: pluginRoot, version, skills: installedSkills.sort() };
+  return { root: publishedRoot, version, skills: installedSkills.sort() };
 }
 
 function tomlMultiline(value) {
@@ -658,6 +716,9 @@ module.exports = {
   buildCommandMap,
   buildHooksManifest,
   buildMcpRuntime,
+  inspectInstalledRuntime,
+  applyNativeDoctor,
+  mcpCommand,
   buildPlugin,
   buildAgentToml,
   installAgents,