ultra-builder-pro-cli 0.6.0 → 0.8.1

package/adapters/_shared/tests/provenance.test.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const provenance = require('../provenance.cjs');
+
+function fixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-provenance-'));
+  fs.mkdirSync(path.join(root, 'runtime'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'hooks'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'runtime', 'launch.cjs'), 'module.exports = true;\n');
+  fs.writeFileSync(path.join(root, 'hooks', 'hooks.json'), '{}\n');
+  const file = path.join(root, 'provenance.json');
+  provenance.writeProvenance({
+    file,
+    adapter: 'claude',
+    packageInfo: { name: 'ultra-builder-pro-cli', version: '1.2.3' },
+    repository: 'https://example.test/ultra-builder-pro',
+    sourceCommit: '0123456789abcdef0123456789abcdef01234567',
+    roots: { plugin: root },
+    assets: [
+      { root: 'plugin', path: 'hooks/hooks.json' },
+      { root: 'plugin', path: 'runtime/launch.cjs' },
+    ],
+    contracts: {
+      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
+      mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+    },
+  });
+  return { root, file };
+}
+
+test('writeProvenance + inspectProvenance produce a normalized healthy report', () => {
+  const fx = fixture();
+  try {
+    const manifest = JSON.parse(fs.readFileSync(fx.file, 'utf8'));
+    assert.equal(manifest.schema_version, 1);
+    assert.equal(manifest.adapter, 'claude');
+    assert.equal(manifest.package.version, '1.2.3');
+    assert.equal(manifest.source.repository, 'https://example.test/ultra-builder-pro');
+    assert.match(manifest.content.digest, /^[0-9a-f]{64}$/);
+    assert.deepEqual(manifest.assets.map((asset) => asset.path), [
+      'hooks/hooks.json', 'runtime/launch.cjs',
+    ]);
+
+    const report = provenance.inspectProvenance({
+      file: fx.file,
+      expectedAdapter: 'claude',
+      expectedPackageVersion: '1.2.3',
+    });
+    assert.equal(report.status, 'healthy');
+    assert.deepEqual(report.issues, []);
+    assert.equal(report.checks.assets.checked, 2);
+    assert.equal(report.checks.contracts.checked, 2);
+  } finally {
+    fs.rmSync(fx.root, { recursive: true, force: true });
+  }
+});
+
+test('inspectProvenance detects content drift and missing contract targets', () => {
+  const fx = fixture();
+  try {
+    fs.writeFileSync(path.join(fx.root, 'runtime', 'launch.cjs'), 'tampered\n');
+    fs.unlinkSync(path.join(fx.root, 'hooks', 'hooks.json'));
+    const report = provenance.inspectProvenance({
+      file: fx.file,
+      expectedAdapter: 'claude',
+      expectedPackageVersion: '1.2.3',
+    });
+    assert.equal(report.status, 'degraded');
+    assert.ok(report.issues.some((issue) => issue.code === 'ASSET_HASH_MISMATCH'));
+    assert.ok(report.issues.some(
+      (issue) => issue.code === 'CONTRACT_TARGET_MISSING' && issue.contract === 'hooks_manifest',
+    ));
+  } finally {
+    fs.rmSync(fx.root, { recursive: true, force: true });
+  }
+});
+
+test('inspectProvenance fails closed for missing, corrupt, or mismatched manifests', () => {
+  const fx = fixture();
+  try {
+    const mismatch = provenance.inspectProvenance({
+      file: fx.file,
+      expectedAdapter: 'codex',
+      expectedPackageVersion: '9.9.9',
+    });
+    assert.equal(mismatch.status, 'degraded');
+    assert.ok(mismatch.issues.some((issue) => issue.code === 'ADAPTER_MISMATCH'));
+    assert.ok(mismatch.issues.some((issue) => issue.code === 'PACKAGE_VERSION_MISMATCH'));
+
+    fs.writeFileSync(fx.file, 'not-json');
+    const corrupt = provenance.inspectProvenance({ file: fx.file });
+    assert.equal(corrupt.status, 'degraded');
+    assert.equal(corrupt.issues[0].code, 'PROVENANCE_INVALID');
+
+    fs.unlinkSync(fx.file);
+    const missing = provenance.inspectProvenance({ file: fx.file });
+    assert.equal(missing.status, 'missing');
+    assert.equal(missing.issues[0].code, 'PROVENANCE_MISSING');
+  } finally {
+    fs.rmSync(fx.root, { recursive: true, force: true });
+  }
+});
+
+test('packageSource never attributes an enclosing consumer repository commit to the package', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-provenance-source-'));
+  try {
+    execFileSync('git', ['init', '-q'], { cwd: root });
+    execFileSync('git', ['config', 'user.email', 'test@ubp.dev'], { cwd: root });
+    execFileSync('git', ['config', 'user.name', 'ubp-test'], { cwd: root });
+    fs.writeFileSync(path.join(root, 'README.md'), '# consumer\n');
+    execFileSync('git', ['add', 'README.md'], { cwd: root });
+    execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: root });
+    const packageRoot = path.join(root, 'node_modules', 'ultra-builder-pro-cli');
+    fs.mkdirSync(packageRoot, { recursive: true });
+    fs.writeFileSync(path.join(packageRoot, 'package.json'), JSON.stringify({
+      name: 'ultra-builder-pro-cli',
+      version: '1.2.3',
+      repository: { url: 'https://example.test/ultra-builder-pro' },
+    }));
+
+    const source = provenance.packageSource(packageRoot);
+    assert.equal(source.sourceCommit, null);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/adapters/_shared/tests/runtime-assets.test.cjs

@@ -27,6 +27,8 @@ const CORE = [
   'ultra-deliver',
   'ultra-status',
   'ultra-think',
+  'ultra-change',
+  'ultra-doctor',
 ];
 
 const INTERNAL = [

package/adapters/claude.js

@@ -15,6 +15,7 @@ const {
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
   WORKFLOW_HOOK_FILES,
@@ -26,6 +27,7 @@ const MCP_SERVER_NAME = PLUGIN_NAME;
 const SOURCE_TAG = 'ubp';
 const SENTINEL_KEY = '_ubp_manifest';
 const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
+const PROVENANCE_FILE = 'provenance.json';
 
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return ctx.configDir;
@@ -155,9 +157,39 @@ function install(ctx = {}) {
     license: pkg.license || 'MIT',
   }, null, 2) + '\n');
   markManaged(target, { adapter: 'claude', plugin: PLUGIN_NAME });
+  const source = provenance.packageSource(repoRoot);
+  const provenanceFile = path.join(target, PROVENANCE_FILE);
+  report.provenance = provenance.writeProvenance({
+    file: provenanceFile,
+    adapter: 'claude',
+    ...source,
+    roots: { plugin: target },
+    assets: provenance.assetRefsForTree('plugin', target, {
+      exclude: ['.ubp-managed', PROVENANCE_FILE],
+    }),
+    contracts: {
+      plugin_manifest: { root: 'plugin', path: '.claude-plugin/plugin.json' },
+      mcp_registration: { root: 'plugin', path: '.mcp.json' },
+      mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
+      checkpoint_hook: { root: 'plugin', path: 'hooks/workflow_checkpoint.py' },
+      resume_hook: { root: 'plugin', path: 'hooks/workflow_resume.py' },
+    },
+  });
+  report.provenance.file = provenanceFile;
   return report;
 }
 
+function doctor(ctx = {}) {
+  const repoRoot = resolveRepoRoot(ctx);
+  const source = provenance.packageSource(repoRoot);
+  return provenance.inspectProvenance({
+    file: path.join(resolvePluginRoot(ctx), PROVENANCE_FILE),
+    expectedAdapter: 'claude',
+    expectedPackageVersion: source.packageInfo.version,
+  });
+}
+
 function uninstall(ctx = {}) {
   const target = resolvePluginRoot(ctx);
   const report = { target, removed: {}, config: { updated: false } };
@@ -179,4 +211,5 @@ module.exports = {
   resolvePluginRoot,
   install,
   uninstall,
+  doctor,
 };

package/adapters/codex.js

@@ -33,6 +33,7 @@ const {
   buildPlugin,
   installAgents,
 } = require('./_shared/codex-assets.cjs');
+const provenance = require('./_shared/provenance.cjs');
 
 const MCP_SERVER_NAME = PLUGIN_NAME;
 const SOURCE_TAG = 'ubp';
@@ -40,6 +41,7 @@ const MARKER_BEGIN = '# >>> ultra-builder-pro managed block — do not edit by h
 const MARKER_END = '# <<< ultra-builder-pro managed block';
 const RUNTIME_MANIFEST_DIR = 'ultra-builder-pro';
 const RUNTIME_MANIFEST_FILE = 'install-manifest.json';
+const PROVENANCE_FILE = 'provenance.json';
 const HOOK_ADAPTER_RELATIVE = path.join('hooks', 'adapters', 'codex.py');
 
 function resolveTarget(ctx = {}) {
@@ -355,6 +357,30 @@ function install(ctx = {}) {
     agents: agents.installed,
     hookCacheVersions,
   });
+  const source = provenance.packageSource(repoRoot);
+  const provenanceFile = path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE);
+  const provenanceManifest = provenance.writeProvenance({
+    file: provenanceFile,
+    adapter: 'codex',
+    ...source,
+    roots: { plugin: pluginRoot, config: configDir },
+    assets: [
+      ...provenance.assetRefsForTree('plugin', pluginRoot, {
+        exclude: ['.ubp-managed'],
+      }),
+      ...agents.installed.map((file) => ({ root: 'config', path: path.join('agents', file) })),
+      { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
+    ],
+    contracts: {
+      plugin_manifest: { root: 'plugin', path: '.codex-plugin/plugin.json' },
+      mcp_registration: { root: 'plugin', path: '.mcp.json' },
+      mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
+      hook_adapter: { root: 'plugin', path: HOOK_ADAPTER_RELATIVE },
+      runtime_manifest: { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
+    },
+  });
+  provenanceManifest.file = provenanceFile;
 
   return {
     target: configDir,
@@ -365,10 +391,70 @@ function install(ctx = {}) {
     hookCompatibility,
     legacy,
     manifestFile,
+    provenance: provenanceManifest,
     config: { updated: legacy.configUpdated },
   };
 }
 
+function doctor(ctx = {}) {
+  const configDir = resolveTarget(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  const marketplaceFile = resolveMarketplaceFile(ctx);
+  const source = provenance.packageSource(repoRoot);
+  const report = provenance.inspectProvenance({
+    file: path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE),
+    expectedAdapter: 'codex',
+    expectedPackageVersion: source.packageInfo.version,
+  });
+
+  let runtimeManifest = null;
+  try {
+    runtimeManifest = readRuntimeManifest(configDir);
+  } catch (error) {
+    report.issues.push({ code: 'RUNTIME_MANIFEST_INVALID', message: error.message });
+  }
+  const runtimeManifestOk = runtimeManifest?.source === SOURCE_TAG
+    && runtimeManifest.adapter === 'codex'
+    && runtimeManifest.plugin?.root === pluginRoot
+    && typeof runtimeManifest.plugin?.version === 'string';
+  if (!runtimeManifestOk && !report.issues.some((entry) => entry.code === 'RUNTIME_MANIFEST_INVALID')) {
+    report.issues.push({ code: 'RUNTIME_MANIFEST_INVALID', path: runtimeManifestFile(configDir) });
+  }
+  report.checks.runtime_manifest = { status: runtimeManifestOk ? 'pass' : 'fail' };
+
+  let marketplaceOk = false;
+  try {
+    const marketplace = loadMarketplace(marketplaceFile);
+    const entry = marketplace.plugins.find((plugin) => plugin?.name === PLUGIN_NAME);
+    marketplaceOk = entry?.source?.source === 'local'
+      && entry.source.path === `./plugins/${PLUGIN_NAME}`;
+  } catch (error) {
+    report.issues.push({ code: 'MARKETPLACE_REGISTRATION_INVALID', message: error.message });
+  }
+  if (!marketplaceOk && !report.issues.some((entry) => entry.code === 'MARKETPLACE_REGISTRATION_INVALID')) {
+    report.issues.push({ code: 'MARKETPLACE_REGISTRATION_INVALID', path: marketplaceFile });
+  }
+  report.checks.marketplace = { status: marketplaceOk ? 'pass' : 'fail' };
+
+  let hookTargetsOk = runtimeManifestOk;
+  if (runtimeManifestOk) {
+    const cacheRoot = pluginCacheRoot(configDir, runtimeManifest.marketplace?.name || 'personal');
+    const currentCacheRequired = shouldRunPluginCli(ctx);
+    for (const version of runtimeManifest.hook_cache_versions || []) {
+      if (version === runtimeManifest.plugin.version && !currentCacheRequired) continue;
+      const adapter = path.join(cacheRoot, version, HOOK_ADAPTER_RELATIVE);
+      if (!fs.existsSync(adapter)) {
+        hookTargetsOk = false;
+        report.issues.push({ code: 'HOOK_TARGET_MISSING', version, path: adapter });
+      }
+    }
+  }
+  report.checks.hook_targets = { status: hookTargetsOk ? 'pass' : 'fail' };
+  if (report.status !== 'missing') report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
+  return report;
+}
+
 function removeManagedAgents(configDir, manifest) {
   const agentRoot = path.join(configDir, 'agents');
   const requested = manifest && Array.isArray(manifest.agents)
@@ -440,6 +526,7 @@ module.exports = {
   resolveMarketplaceFile,
   install,
   uninstall,
+  doctor,
   _internal: {
     stripManagedBlock,
     hasManagedBlock,

package/adapters/opencode.js

@@ -15,6 +15,7 @@ const {
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
   skillsForRuntime,
@@ -34,6 +35,7 @@ const SOURCE_TAG = 'ubp';
 const BUNDLE_DIR = '.ultra-builder-pro';
 const MANAGED_TEXT_MARKER = '<!-- ultra-builder-pro:managed -->';
 const PLUGIN_MARKER = '// Managed by Ultra Builder Pro.';
+const PROVENANCE_FILE = 'provenance.json';
 const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
 
 function resolveTarget(ctx = {}) {
@@ -337,20 +339,55 @@ import path from "node:path";
 
 const TERMINAL = new Set(["committed", "completed", "done", "cancelled"]);
 const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
+const PROVIDER_FIELDS = new Set(["provider", "project", "reference", "revision", "indexed_head", "status"]);
+
+function providerMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const clean = {};
+  for (const [kind, ref] of Object.entries(value)) {
+    if (!["memory", "code_graph"].includes(kind) || !ref || typeof ref !== "object" || Array.isArray(ref)) continue;
+    clean[kind] = Object.fromEntries(Object.entries(ref).filter(([key]) => PROVIDER_FIELDS.has(key)));
+  }
+  return clean;
+}
 
-function findActiveWorkflow(directory) {
+function findUltraContext(directory) {
   let current = path.resolve(directory);
   while (true) {
-    const file = path.join(current, ".ultra", "workflow-state.json");
-    if (fs.existsSync(file)) {
+    const ultra = path.join(current, ".ultra");
+    const workflowFile = path.join(ultra, "workflow-state.json");
+    const statePresent = fs.existsSync(path.join(ultra, "state.db"));
+    let workflow = null;
+    if (fs.existsSync(workflowFile)) {
       try {
-        const state = JSON.parse(fs.readFileSync(file, "utf8"));
-        return state && !TERMINAL.has(state.status) ? { root: current, state } : null;
+        const state = JSON.parse(fs.readFileSync(workflowFile, "utf8"));
+        workflow = state && !TERMINAL.has(state.status) ? state : null;
       } catch (error) {
-        process.stderr.write(\`[ultra-builder-pro] cannot read \${file}: \${error.message}\\n\`);
-        return null;
+        process.stderr.write(\`[ultra-builder-pro] cannot read \${workflowFile}: \${error.message}\\n\`);
+      }
+    }
+    const changes = [];
+    const changeRoot = path.join(ultra, "changes", "active");
+    if (fs.existsSync(changeRoot)) {
+      for (const entry of fs.readdirSync(changeRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const manifestPath = path.join(changeRoot, entry.name, "context-manifest.json");
+        if (!fs.existsSync(manifestPath)) continue;
+        try {
+          const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+          if (manifest?.change) changes.push({
+            ...manifest.change,
+            providers: providerMetadata(manifest.providers),
+            manifestPath: path.relative(current, manifestPath),
+          });
+        } catch (error) {
+          process.stderr.write(\`[ultra-builder-pro] cannot read \${manifestPath}: \${error.message}\\n\`);
+        }
       }
     }
+    if (statePresent || workflow || changes.length > 0) {
+      return { root: current, workflow, changes, statePresent };
+    }
     const parent = path.dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -358,16 +395,42 @@ function findActiveWorkflow(directory) {
 }
 
 function contextText(active) {
-  const state = active.state;
-  return [
-    "[Ultra active workflow]",
-    \`Project: \${active.root}\`,
-    \`Command: \${state.command ?? "unknown"}\`,
-    \`Task: \${state.task_id ?? state.task ?? "unknown"}\`,
-    \`Step: \${state.step ?? "unknown"}\`,
-    \`Status: \${state.status ?? "active"}\`,
-    "Authority: .ultra/state.db; recovery: .ultra/workflow-state.json.",
-  ].join("\\n");
+  const lines = [];
+  if (active.workflow) {
+    const state = active.workflow;
+    lines.push(
+      "[Ultra active workflow]",
+      \`Project: \${active.root}\`,
+      \`Command: \${state.command ?? "unknown"}\`,
+      \`Task: \${state.task_id ?? state.task ?? "unknown"}\`,
+      \`Step: \${state.step ?? "unknown"}\`,
+      \`Status: \${state.status ?? "active"}\`,
+    );
+  }
+  if (active.changes.length > 0) {
+    const change = active.changes[0];
+    lines.push(
+      "[Ultra continuous change]",
+      \`Project: \${active.root}\`,
+      \`Change: \${change.id} (\${change.kind ?? "unknown"}, \${change.status ?? "active"})\`,
+      \`Title: \${change.title ?? "unknown"}\`,
+      \`Intent: \${change.intent ?? "unknown"}\`,
+      \`Context manifest: \${change.manifestPath}\`,
+      \`External providers (metadata references only): \${JSON.stringify(change.providers)}\`,
+    );
+    if (active.changes.length > 1) lines.push(
+      \`Active change count: \${active.changes.length}; resolve scope with change.list before mutation.\`,
+    );
+  }
+  if (!active.workflow && active.changes.length === 0) {
+    lines.push(
+      "[Ultra baseline]",
+      \`Project: \${active.root}\`,
+      "No active continuous change. Start daily work with the ultra-change workflow.",
+    );
+  }
+  lines.push("Authority: .ultra/state.db; generated JSON/Markdown are projections or artifacts.");
+  return lines.join("\\n");
 }
 
 function targetPaths(tool, args) {
@@ -391,8 +454,8 @@ function isTasksProjection(active, candidate) {
 
 export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
   const root = worktree || directory;
-  let active = findActiveWorkflow(root);
-  const refresh = () => { active = findActiveWorkflow(root); };
+  let active = findUltraContext(root);
+  const refresh = () => { active = findUltraContext(root); };
   return {
     event: async ({ event }) => {
       if (["session.created", "session.compacted", "session.idle"].includes(event?.type)) refresh();
@@ -413,7 +476,7 @@ export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
       if (targetPaths(tool, output?.args).some((candidate) => isTasksProjection(active, candidate))) {
         throw new Error(
           "Ultra Builder Pro refused a direct write to .ultra/tasks/tasks.json. " +
-          ".ultra/state.db is authoritative; use MCP task tools or run the required v4.4 to v4.5 migration."
+          ".ultra/state.db is authoritative; use MCP task tools and run ultra-doctor when state or projection health is degraded."
         );
       }
     },
@@ -454,6 +517,69 @@ function install(ctx = {}) {
   delete next[LEGACY_SENTINEL_KEY];
   writeAtomic(configFile, JSON.stringify(next, null, 2) + '\n');
   report.config.updated = true;
+  const source = provenance.packageSource(repoRoot);
+  const bundleAssets = provenance.assetRefsForTree('config', bundleRoot, {
+    exclude: [PROVENANCE_FILE],
+  }).map((asset) => ({ ...asset, path: path.join(BUNDLE_DIR, asset.path) }));
+  const skillMarkers = skillsForRuntime('opencode').map((name) => ({
+    root: 'config', path: path.join('skills', name, '.ubp-managed'),
+  }));
+  const provenanceFile = path.join(bundleRoot, PROVENANCE_FILE);
+  report.provenance = provenance.writeProvenance({
+    file: provenanceFile,
+    adapter: 'opencode',
+    ...source,
+    roots: { config: target },
+    assets: [
+      ...report.copied.commands.map((file) => ({ root: 'config', path: path.join('commands', file) })),
+      ...report.copied.skills.map((file) => ({ root: 'config', path: path.join('skills', file) })),
+      ...skillMarkers,
+      ...report.copied.agents.map((file) => ({ root: 'config', path: path.join('agents', file) })),
+      { root: 'config', path: path.join('plugins', 'ultra-builder-pro.js') },
+      ...bundleAssets,
+    ],
+    contracts: {
+      host_plugin: { root: 'config', path: path.join('plugins', 'ultra-builder-pro.js') },
+      mcp_config: { root: 'config', path: 'opencode.json' },
+      mcp_launcher: { root: 'config', path: path.join(BUNDLE_DIR, 'runtime', 'launch.cjs') },
+    },
+  });
+  report.provenance.file = provenanceFile;
+  return report;
+}
+
+function doctor(ctx = {}) {
+  const target = resolveTarget(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  const source = provenance.packageSource(repoRoot);
+  const report = provenance.inspectProvenance({
+    file: path.join(target, BUNDLE_DIR, PROVENANCE_FILE),
+    expectedAdapter: 'opencode',
+    expectedPackageVersion: source.packageInfo.version,
+  });
+  const configFile = path.join(target, 'opencode.json');
+  const expectedLauncher = path.join(target, BUNDLE_DIR, 'runtime', 'launch.cjs');
+  let registrationOk = false;
+  try {
+    const config = readJsonSafe(configFile);
+    const entry = config.mcp && config.mcp[MCP_SERVER_NAME];
+    registrationOk = entry?.type === 'local'
+      && entry.enabled === true
+      && Array.isArray(entry.command)
+      && entry.command[0] === process.execPath
+      && entry.command[1] === expectedLauncher;
+  } catch (error) {
+    report.issues.push({ code: 'MCP_REGISTRATION_INVALID', message: error.message });
+  }
+  if (!registrationOk && !report.issues.some((entry) => entry.code === 'MCP_REGISTRATION_INVALID')) {
+    report.issues.push({
+      code: 'MCP_REGISTRATION_INVALID',
+      path: configFile,
+      expected_launcher: expectedLauncher,
+    });
+  }
+  report.checks.registration = { status: registrationOk ? 'pass' : 'fail' };
+  if (report.status !== 'missing') report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
   return report;
 }
 
@@ -529,4 +655,5 @@ module.exports = {
   resolveTarget,
   install,
   uninstall,
+  doctor,
 };

package/adapters/tests/codex.test.cjs

@@ -21,8 +21,10 @@ const {
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const COMMANDS = [
   'learn',
+  'ultra-change',
   'ultra-deliver',
   'ultra-dev',
+  'ultra-doctor',
   'ultra-init',
   'ultra-plan',
   'ultra-research',
@@ -89,7 +91,7 @@ test('install builds one Codex-native plugin with complete skill and command cov
 
     const expectedSkills = skillsForRuntime('codex').sort();
     assert.deepEqual(skillNames(layout.pluginRoot), expectedSkills);
-    assert.equal(expectedSkills.length, 16);
+    assert.equal(expectedSkills.length, 18);
     assert.ok(!fs.existsSync(path.join(layout.pluginRoot, 'skills', 'codex-collab')));
     assert.ok(!fs.existsSync(path.join(layout.pluginRoot, 'skills', 'learned')));
 
@@ -229,8 +231,8 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     const liveSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'mcp-tools.yaml'), 'utf8'));
     const upstreamSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'upstream-mcp-tools.yaml'), 'utf8'));
     const capabilityMap = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'codex-capability-map.json'), 'utf8'));
-    assert.equal(liveSpec.tools.length, 21);
-    assert.equal(upstreamSpec.tools.length, 21);
+    assert.equal(liveSpec.tools.length, 29);
+    assert.equal(upstreamSpec.tools.length, 29);
     assert.deepEqual(upstreamSpec.tools.map((tool) => tool.name).sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.deepEqual(capabilityMap.live_mcp_tools.sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.equal(Object.keys(capabilityMap.codex_native_replacements).length, 9);
@@ -360,3 +362,40 @@ test('uninstall removes only UBP-managed plugin and agents', () => {
     cleanup(layout);
   }
 });
+
+test('doctor checks the current Codex cache hook target for a CLI-managed global install', () => {
+  const layout = mkLayout();
+  try {
+    install(layout);
+    const runtimeManifest = JSON.parse(fs.readFileSync(
+      path.join(layout.configDir, 'ultra-builder-pro', 'install-manifest.json'),
+      'utf8',
+    ));
+    const version = runtimeManifest.plugin.version;
+    const cacheAdapter = path.join(
+      codex._internal.pluginCacheRoot(layout.configDir, 'personal'),
+      version,
+      'hooks',
+      'adapters',
+      'codex.py',
+    );
+    const doctorCtx = {
+      homeDir: layout.homeDir,
+      scope: 'global',
+      repoRoot: REPO_ROOT,
+      runPluginCli: true,
+    };
+
+    const degraded = codex.doctor(doctorCtx);
+    assert.equal(degraded.status, 'degraded');
+    assert.ok(degraded.issues.some((entry) => (
+      entry.code === 'HOOK_TARGET_MISSING' && entry.version === version
+    )));
+
+    fs.mkdirSync(path.dirname(cacheAdapter), { recursive: true });
+    fs.copyFileSync(path.join(layout.pluginRoot, 'hooks', 'adapters', 'codex.py'), cacheAdapter);
+    assert.equal(codex.doctor(doctorCtx).status, 'healthy');
+  } finally {
+    cleanup(layout);
+  }
+});

package/adapters/tests/opencode.test.cjs

@@ -171,13 +171,14 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
     assert.match(plugin, /\.ultra[\\/]tasks[\\/]tasks\.json/);
     assert.match(plugin, /throw new Error/);
     assert.match(plugin, /session\.compacted/);
-    assert.doesNotMatch(plugin, /memory|recall|journal|observation/);
+    assert.doesNotMatch(plugin, /memory\.(?:retain|recall|reflect)|journal|observation|prompt[_ -]?capture/);
+    assert.match(plugin, /metadata references only/);
   } finally {
     fs.rmSync(target, { recursive: true, force: true });
   }
 });
 
-test('OpenCode before-tool hook blocks tasks.json writes only during an active workflow', async () => {
+test('OpenCode context covers active changes and projection writes are blocked for Ultra projects', async () => {
   const target = mkTarget();
   const project = mkTarget();
   try {
@@ -186,15 +187,21 @@ test('OpenCode before-tool hook blocks tasks.json writes only during an active w
     const module = await import(pathToFileURL(pluginFile).href);
     const plugin = await module.UltraBuilderProPlugin({ directory: project });
 
-    await plugin['tool.execute.before'](
-      { tool: 'edit' },
-      { args: { filePath: '.ultra/tasks/tasks.json' } },
-    );
-
     fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
-    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
-      command: 'ultra-plan', task_id: 'plan', step: 'persist', status: 'active',
+    fs.writeFileSync(path.join(project, '.ultra', 'state.db'), 'owned-by-ultra');
+    const changeRoot = path.join(project, '.ultra', 'changes', 'active', 'daily-fix');
+    fs.mkdirSync(changeRoot, { recursive: true });
+    fs.writeFileSync(path.join(changeRoot, 'context-manifest.json'), JSON.stringify({
+      change: { id: 'daily-fix', title: 'Daily fix', kind: 'quick', status: 'active', intent: 'Fix drift' },
+      providers: { memory: { provider: 'cloud-mem', status: 'available' } },
     }));
+
+    const output = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, output);
+    assert.match(output.system.join('\n'), /Ultra continuous change/);
+    assert.match(output.system.join('\n'), /daily-fix/);
+    assert.match(output.system.join('\n'), /metadata references only/);
+
     await assert.rejects(
       plugin['tool.execute.before'](
         { tool: 'apply_patch' },