ultra-builder-pro-cli 0.20.0 → 0.22.0

package/adapters/_shared/codex-assets.cjs

@@ -8,6 +8,8 @@ const { spawnSync } = require('node:child_process');
 const yaml = require('js-yaml');
 const {
   CORE_PUBLIC_SKILLS,
+  RUNTIME_SUPPORT_FILES,
+  RUNTIME_WORKER_FILES,
   WORKFLOW_HOOK_FILES,
   skillPolicy,
   skillsForRuntime,
@@ -21,7 +23,10 @@ const {
   removeTree,
   writeAtomic,
 } = require('./file-ops.cjs');
-const { interactionContract } = require('./interaction-contract.cjs');
+const {
+  adaptInteractionGuidance,
+  interactionContract,
+} = require('./interaction-contract.cjs');
 
 const PLUGIN_NAME = 'ultra-builder-pro';
 const MANAGED_MARKER = 'Managed by Ultra Builder Pro Codex adapter.';
@@ -104,7 +109,7 @@ function adaptSkillAsset(input, targetName, _rel) {
 }
 
 function adaptHostText(input, skillName = '') {
-  let text = String(input);
+  let text = adaptInteractionGuidance(input, 'codex');
   text = text.replaceAll('codex-collab', 'cc-collab');
   text = text.replaceAll('CLAUDE.md', 'AGENTS.md');
   text = text.replaceAll('$CLAUDE_PLUGIN_ROOT/skills', '~/plugins/ultra-builder-pro/skills');
@@ -122,11 +127,6 @@ function adaptHostText(input, skillName = '') {
     text = adaptCodexPrimaryText(text, skillName);
   }
 
-  if (skillName === 'learn') {
-    text = text.replaceAll("current host's user skill directory", '`~/.agents/skills`');
-    text += `\n\n## Codex packaging requirement\n\nEach learned pattern must be a valid skill directory, not a loose Markdown file. The generated\n\`SKILL.md\` must start with only \`name\` and \`description\` frontmatter. Also create\n\`agents/openai.yaml\` with \`policy.allow_implicit_invocation: false\`. A new Codex task is required\nbefore the learned skill appears in discovery.\n`;
-  }
-
   return text;
 }
 
@@ -135,7 +135,6 @@ function adaptedDescription(sourceDescription, targetName) {
     'cc-collab': 'Ask Claude Code for an independent read-only analysis while Codex owns verification and synthesis. Use only when the user explicitly requests CC or Claude Code collaboration.',
     'ultra-verify': 'Run Codex-primary cross-model verification with a read-only Claude Code advisor. Use only when the user explicitly requests independent model verification.',
     'ultra-dev': 'Execute one authoritative Ultra task with Codex-native implementation, verification, and review. Use when a dependency-ready slice is ready for development.',
-    'learn': 'Extract one verified reusable workflow from the current Codex task into a portable user skill. Use when the user explicitly asks to preserve the method.',
   };
   return special[targetName] || adaptHostText(String(sourceDescription || `${titleCase(targetName)} workflow for Codex.`), targetName)
     .replace(/\s+/g, ' ')
@@ -295,6 +294,16 @@ function copyHooks(repoRoot, pluginRoot) {
 function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
   const source = path.join(repoRoot, 'mcp-server', 'server.cjs');
   const cliSource = path.join(repoRoot, 'adapters', '_shared', 'codex-ultra-tools-entry.cjs');
+  const runtimeWorkerSources = new Map([
+    [
+      'session-close-journal-worker.cjs',
+      path.join(repoRoot, 'orchestrator', 'session-close-journal-worker.cjs'),
+    ],
+    [
+      'doctor-backup-worker.cjs',
+      path.join(repoRoot, 'mcp-server', 'lib', 'doctor-backup-worker.cjs'),
+    ],
+  ]);
   const runtimeRoot = path.join(pluginRoot, 'runtime');
   const buildRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-codex-mcp-build-'));
   let nccCli;
@@ -359,6 +368,54 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
     removeTree(cliBuildRoot);
   }
 
+  for (const workerFile of RUNTIME_WORKER_FILES) {
+    const workerSource = runtimeWorkerSources.get(workerFile);
+    if (!workerSource) {
+      throw new Error(`Ultra runtime worker source is not registered: ${workerFile}`);
+    }
+    const workerBuildRoot = fs.mkdtempSync(path.join(
+      os.tmpdir(),
+      `ubp-${path.basename(workerFile, '.cjs')}-build-`,
+    ));
+    try {
+      const bundled = spawnSync(process.execPath, [
+        nccCli,
+        'build',
+        workerSource,
+        '-o',
+        workerBuildRoot,
+        '--no-cache',
+        '--quiet',
+      ], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      if (bundled.error) throw bundled.error;
+      if (bundled.status !== 0) {
+        const detail = (bundled.stderr || bundled.stdout || '').trim();
+        throw new Error(
+          `ncc failed to bundle Ultra runtime worker ${workerFile}${detail ? `: ${detail}` : ''}`,
+        );
+      }
+      const workerOutput = path.join(workerBuildRoot, 'index.cjs');
+      if (!fs.existsSync(workerOutput)) {
+        throw new Error(`ncc did not emit Ultra runtime worker ${workerFile}`);
+      }
+      fs.copyFileSync(workerOutput, path.join(runtimeRoot, workerFile));
+    } finally {
+      removeTree(workerBuildRoot);
+    }
+  }
+
+  for (const supportFile of RUNTIME_SUPPORT_FILES) {
+    const sourceFile = path.join(repoRoot, 'mcp-server', 'lib', supportFile);
+    if (!fs.existsSync(sourceFile) || !fs.statSync(sourceFile).isFile()) {
+      throw new Error(`Ultra runtime support asset is missing: ${supportFile}`);
+    }
+    fs.copyFileSync(sourceFile, path.join(runtimeRoot, supportFile));
+  }
+
   const runtimeBootstrap = runtime === 'kimi' ? `
 const fs = require('node:fs');
 const pluginRoot = path.resolve(__dirname, '..');
@@ -381,9 +438,6 @@ if (!process.env.UBP_ROOT_DIR) {
   }
   process.env.UBP_ROOT_DIR = rootDir;
 }
-if (!process.env.UBP_DB_PATH) {
-  process.env.UBP_DB_PATH = path.join(process.env.UBP_ROOT_DIR, '.ultra', 'state.db');
-}
 ` : '';
 
   const launcher = `'use strict';
@@ -409,6 +463,10 @@ main().catch((error) => {
     path.join(repoRoot, 'mcp-server', 'hook-event.cjs'),
     path.join(runtimeRoot, 'hook-event.cjs'),
   );
+  fs.copyFileSync(
+    path.join(repoRoot, 'mcp-server', 'lib', 'plan-publication-worker.cjs'),
+    path.join(runtimeRoot, 'plan-publication-worker.cjs'),
+  );
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));

package/adapters/_shared/interaction-contract.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+const { PUBLIC_CAPABILITY_GRAPH } = require('./runtime-assets.cjs');
+
 const SURFACES = Object.freeze({
   claude: Object.freeze({
     primary: 'AskUserQuestion',
@@ -23,12 +25,16 @@ const SURFACES = Object.freeze({
   }),
 });
 
+const GENERIC_QUESTION_GUIDANCE =
+  /Use the host-native structured question surface declared by the installed interaction\s+contract(?: when it exists)?\./g;
+
 function interactionContract(runtime) {
   const question = SURFACES[runtime];
   if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
   return {
-    schema_version: '1.1',
+    schema_version: '1.2',
     runtime,
+    public_capability_graph: PUBLIC_CAPABILITY_GRAPH,
     authority: {
       user: [
         'product_intent',
@@ -54,10 +60,13 @@ function interactionContract(runtime) {
       semantic_selection_flow: [
         'inspect',
         'suggest',
-        'ask_if_unresolved',
+        'host_native_ask',
         'normalize',
         'persist',
+        'apply',
+        'read_back',
       ],
+      adapter_authority: 'none',
       dependent_decisions: 'one_at_a_time',
       independent_low_load_questions: { maximum: 3 },
       explicit_current_intent: 'normalize_without_reconfirmation',
@@ -67,9 +76,11 @@ function interactionContract(runtime) {
     },
     persistence: {
       accepted_intent: 'trust_as_current_authority',
+      accepted_intent_recall: 'breadcrumb_and_decision_list',
       user_interaction_proof: 'not_required',
       raw_prompt_or_transcript: 'never_store',
       pending_question: 'store_only_when_recovery_requires_it',
+      application_evidence: 'record_applied_refs_when_another_authority_changes',
     },
     routing: {
       semantic_recommendation_owner: 'host_model',
@@ -80,4 +91,26 @@ function interactionContract(runtime) {
   };
 }
 
-module.exports = { SURFACES, interactionContract };
+function interactionPrompt(runtime) {
+  const contract = interactionContract(runtime);
+  const surface = contract.interaction.question_surface;
+  const host = {
+    claude: 'Claude Code',
+    codex: 'Codex',
+    opencode: 'OpenCode',
+    kimi: 'Kimi Code',
+  }[runtime];
+  const primary = runtime === 'opencode' ? `\`${surface.primary}\`` : surface.primary;
+  return `Use ${host} ${primary} when ${surface.availability.replaceAll('_', ' ')} permits it.`;
+}
+
+function adaptInteractionGuidance(input, runtime) {
+  return String(input).replace(GENERIC_QUESTION_GUIDANCE, interactionPrompt(runtime));
+}
+
+module.exports = {
+  SURFACES,
+  adaptInteractionGuidance,
+  interactionContract,
+  interactionPrompt,
+};

package/adapters/_shared/runtime-assets.cjs

@@ -8,7 +8,6 @@
  */
 
 const CORE_PUBLIC_SKILLS = Object.freeze([
-  'learn',
   'ultra-init',
   'ultra-research',
   'ultra-plan',
@@ -22,6 +21,34 @@ const CORE_PUBLIC_SKILLS = Object.freeze([
   'ultra-doctor',
 ]);
 
+const PUBLIC_CAPABILITY_MODES = Object.freeze({
+  'ultra-init': 'setup',
+  'ultra-research': 'workflow',
+  'ultra-plan': 'workflow',
+  'ultra-dev': 'workflow',
+  'ultra-test': 'workflow',
+  'ultra-review': 'workflow',
+  'ultra-deliver': 'workflow',
+  'ultra-status': 'read_only',
+  'ultra-think': 'reasoning',
+  'ultra-change': 'workflow',
+  'ultra-doctor': 'diagnostic',
+});
+
+const PUBLIC_CAPABILITY_GRAPH = Object.freeze(Object.fromEntries(
+  CORE_PUBLIC_SKILLS.map((name) => [
+    name,
+    Object.freeze({
+      mode: PUBLIC_CAPABILITY_MODES[name],
+      activation: 'explicit_only',
+      next_capability_source: 'mcp_allowed_transitions',
+      recommendation_owner: 'host_model',
+      selection_owner: 'user',
+      automatic_invocation: false,
+    }),
+  ]),
+));
+
 const INTERNAL_AGENT_SKILLS = Object.freeze([
   'code-review-expert',
   'security-rules',
@@ -56,12 +83,22 @@ const WORKFLOW_HOOK_FILES = Object.freeze([
   'context_spine.py',
   'health_check.py',
   'pre_stop_check.py',
+  'runtime_paths.py',
   'subagent_tracker.py',
   'workflow_checkpoint.py',
   'workflow_context.py',
   'workflow_resume.py',
 ]);
 
+const RUNTIME_WORKER_FILES = Object.freeze([
+  'session-close-journal-worker.cjs',
+  'doctor-backup-worker.cjs',
+]);
+
+const RUNTIME_SUPPORT_FILES = Object.freeze([
+  'archive-mutation-worker.py',
+]);
+
 function skillsForRuntime(runtime) {
   const collab = COLLAB_SKILLS_BY_RUNTIME[runtime];
   if (!collab) throw new Error(`unsupported Ultra runtime: ${runtime}`);
@@ -84,11 +121,14 @@ function skillPolicy(name) {
 
 module.exports = {
   CORE_PUBLIC_SKILLS,
+  PUBLIC_CAPABILITY_GRAPH,
   INTERNAL_AGENT_SKILLS,
   SUPPORTED_RUNTIMES,
   COLLAB_SKILLS_BY_RUNTIME,
   MCP_DEPENDENT_SKILLS,
+  RUNTIME_SUPPORT_FILES,
   WORKFLOW_HOOK_FILES,
+  RUNTIME_WORKER_FILES,
   isSupportedRuntime,
   skillPolicy,
   skillsForRuntime,

package/adapters/claude.js

@@ -16,6 +16,7 @@ const {
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
 const { parse: parseFrontmatter, serialize: serializeFrontmatter } = require('./_shared/frontmatter.cjs');
+const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
@@ -55,13 +56,14 @@ function copySkills(repoRoot, target, names) {
     if (!fs.existsSync(source)) throw new Error(`missing allowlisted Claude skill: ${name}`);
     const files = copyTree(source, path.join(target, 'skills', name), {
       transform(buf, rel) {
-        if (rel !== 'SKILL.md') return buf;
+        if (rel !== 'SKILL.md') {
+          return rel.endsWith('.md')
+            ? Buffer.from(adaptInteractionGuidance(buf.toString('utf8'), 'claude'))
+            : buf;
+        }
         const { fm, body } = parseFrontmatter(buf.toString('utf8'));
         if (!fm) throw new Error(`missing frontmatter in Claude skill: ${name}`);
-        let adaptedBody = body;
-        if (name === 'learn') {
-          adaptedBody = adaptedBody.replaceAll("current host's user skill directory", '`~/.claude/skills`');
-        }
+        let adaptedBody = adaptInteractionGuidance(body, 'claude');
         if (name === 'ultra-review') {
           adaptedBody = adaptedBody.replace(
             /the current host's native bounded-worker\s+mechanism/g,

package/adapters/codex.js

@@ -8,7 +8,7 @@
  *   skills/**           -> ~/plugins/ultra-builder-pro/skills/**
  *   agents/*.md         -> ~/.codex/agents/*.toml
  *   hooks/*.py          -> plugin hooks with a Codex wire adapter
- *   mcp-server          -> plugin .mcp.json (project cwd owns .ultra/state.db)
+ *   mcp-server          -> plugin .mcp.json (project cwd owns .ultra/.runtime/state.db)
  *   plugin marketplace  -> ~/.agents/plugins/marketplace.json
  *
  * Deprecated ~/.codex/prompts and ~/.codex/skills projection is intentionally

package/adapters/kimi.js

@@ -16,6 +16,7 @@ const {
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
 const { parse: parseFm, serialize: serializeFm } = require('./_shared/frontmatter.cjs');
+const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
@@ -66,7 +67,7 @@ function loadRegistry(file) {
 }
 
 function kimiTextTransform(input, assetName = '') {
-  let text = String(input);
+  let text = adaptInteractionGuidance(input, 'kimi');
   text = text.replaceAll('$CLAUDE_PLUGIN_ROOT', '$KIMI_PLUGIN_ROOT');
   text = text.replaceAll('~/.claude/skills', '~/.kimi-code/skills');
   text = text.replaceAll('~/.claude/hooks', '~/.kimi-code/hooks');
@@ -99,17 +100,10 @@ function kimiTextTransform(input, assetName = '') {
       'Kimi `AgentSwarm` for parallel reviewers or one foreground Kimi `Agent` for a single reviewer, using the worker prompt files under `$KIMI_PLUGIN_ROOT/agents/`',
     );
   }
-  if (assetName === 'learn') {
-    text = text.replaceAll("current host's user skill directory", '`~/.kimi-code/skills`');
-  }
   text = text.replace(
     /(^|[\s`("'])\/ultra-(?!builder-pro:)([a-z][a-z0-9-]*)/gm,
     '$1/ultra-builder-pro:ultra-$2',
   );
-  text = text.replace(
-    /(^|[\s`("'])\/learn(?=$|[\s`),.;:])/gm,
-    '$1/ultra-builder-pro:learn',
-  );
   text = text.replace(
     /(^|[\s`("'])\/clear(?=$|[\s`),.;:])/gm,
     '$1/new',

package/adapters/opencode.js

@@ -15,6 +15,7 @@ const {
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
@@ -67,7 +68,7 @@ function lowercaseFrontmatterTransform(buf, relPath) {
 }
 
 function openCodeTextTransform(input, assetName = '') {
-  let text = String(input);
+  let text = adaptInteractionGuidance(input, 'opencode');
   text = text.replaceAll('$CLAUDE_PLUGIN_ROOT/skills', '~/.config/opencode/skills');
   text = text.replaceAll('~/.claude/skills', '~/.config/opencode/skills');
   text = text.replaceAll('~/.claude/hooks', '~/.config/opencode/.ultra-builder-pro/hooks');
@@ -96,9 +97,6 @@ function openCodeTextTransform(input, assetName = '') {
       'the OpenCode `task` tool using the installed bounded review agents',
     );
   }
-  if (assetName === 'learn') {
-    text = text.replaceAll("current host's user skill directory", '`~/.config/opencode/skills`');
-  }
   return text;
 }
 
@@ -335,48 +333,41 @@ function preflightAssets(repoRoot, target) {
 
 function pluginSource() {
   return `// Managed by Ultra Builder Pro. Rebuild through the adapter; do not edit in place.
-import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
+const TEAM_TASK_LEDGER = ".ultra/tasks/tasks.json";
+const LIVE_TASK_PROJECTION = ".ultra/.runtime/projections/tasks.json";
 const NODE_BINARY = ${JSON.stringify(process.execPath)};
 const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url));
 const BREADCRUMB_CLI = path.resolve(
   PLUGIN_DIR, "..", ${JSON.stringify(BUNDLE_DIR)}, "runtime", "breadcrumb.cjs",
 );
 
-function findUltraRoot(directory) {
-  let current = path.resolve(directory);
-  while (true) {
-    const stateDb = path.join(current, ".ultra", "state.db");
-    if (fs.existsSync(stateDb) && fs.statSync(stateDb).isFile()) return current;
-    const parent = path.dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
 function readUltraContext(directory) {
-  const root = findUltraRoot(directory);
-  if (!root) return null;
   try {
-    const raw = execFileSync(NODE_BINARY, [BREADCRUMB_CLI, root], {
-      cwd: root,
+    const raw = execFileSync(NODE_BINARY, [BREADCRUMB_CLI, "--discover", directory], {
+      cwd: directory,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       timeout: 5000,
     });
     const value = JSON.parse(raw);
+    const root = value?.root;
+    if (typeof root !== "string" || !root) return null;
     // A canonical breadcrumb is injectable only while DB authority proves an active workflow.
     if (!value?.breadcrumb || !value.breadcrumb.workflow
         || typeof value.text !== "string" || !value.text) {
       return { root, breadcrumb: null, text: null };
     }
     return { root, breadcrumb: value.breadcrumb, text: value.text };
-  } catch {
-    return { root, breadcrumb: null, text: null };
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error);
+    if (/RUNTIME_(?:STATE_CONFLICT|PATH_UNSAFE|ORPHAN_SIDECAR|ROOT_INVALID|AUTHORITY_MISMATCH)|both legacy .*runtime.*state\\.db/i.test(detail)) {
+      throw new Error(detail.trim());
+    }
+    return null;
   }
 }
 
@@ -392,11 +383,30 @@ function targetPaths(tool, args) {
   return [...new Set(paths)];
 }
 
-function isTasksProjection(active, candidate) {
+function managedTaskRootForTarget(baseRoot, candidate) {
   const target = path.isAbsolute(candidate)
     ? path.resolve(candidate)
-    : path.resolve(active.root, candidate);
-  return target === path.resolve(active.root, TASKS_PROJECTION);
+    : path.resolve(baseRoot, candidate);
+  if (target === path.resolve(baseRoot, TEAM_TASK_LEDGER)
+      || target === path.resolve(baseRoot, LIVE_TASK_PROJECTION)) return baseRoot;
+  if (path.basename(target) !== "tasks.json") return null;
+  const parent = path.dirname(target);
+  if (path.basename(parent) === "tasks"
+      && path.basename(path.dirname(parent)) === ".ultra") {
+    return path.dirname(path.dirname(parent));
+  }
+  if (path.basename(parent) === "projections"
+      && path.basename(path.dirname(parent)) === ".runtime"
+      && path.basename(path.dirname(path.dirname(parent))) === ".ultra") {
+    return path.dirname(path.dirname(path.dirname(parent)));
+  }
+  return null;
+}
+
+function protectsManagedTaskFile(baseRoot, candidate) {
+  const targetRoot = managedTaskRootForTarget(baseRoot, candidate);
+  if (!targetRoot) return false;
+  return Boolean(readUltraContext(targetRoot));
 }
 
 export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
@@ -417,13 +427,16 @@ export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
     },
     "tool.execute.before": async (input, output) => {
       refresh();
-      if (!active) return;
       const tool = String(input?.tool ?? "").toLowerCase();
       if (!["write", "edit", "apply_patch"].includes(tool)) return;
-      if (targetPaths(tool, output?.args).some((candidate) => isTasksProjection(active, candidate))) {
+      if (targetPaths(tool, output?.args).some(
+        (candidate) => protectsManagedTaskFile(root, 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 and run ultra-doctor when state or projection health is degraded."
+          "Ultra Builder Pro refused a direct write to an MCP-managed task file. " +
+          ".ultra/tasks/tasks.json is the MCP-published team checkpoint and " +
+          ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. " +
+          "Use the Ultra MCP task or task.ledger tools."
         );
       }
     },