ultra-builder-pro-cli 0.7.0 → 0.9.0

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 = {}) {
@@ -515,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;
 }
 
@@ -590,4 +655,5 @@ module.exports = {
   resolveTarget,
   install,
   uninstall,
+  doctor,
 };

package/adapters/tests/codex.test.cjs

@@ -362,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/kimi-hook.test.cjs

@@ -0,0 +1,122 @@
+'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 { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const ADAPTER = path.join(REPO_ROOT, 'hooks', 'adapters', 'kimi.py');
+
+function run(feature, payload, args = []) {
+  return spawnSync('python3', [ADAPTER, feature, ...args], {
+    cwd: REPO_ROOT,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+  });
+}
+
+test('Kimi hook adapter rejects non-workflow policy hooks without blocking the host', () => {
+  const result = run('block_dangerous_commands.py', {
+    session_id: 'session-1',
+    cwd: REPO_ROOT,
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Shell',
+    tool_input: { command: 'git reset --hard' },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(JSON.parse(result.stdout).message, /refused unknown feature/);
+});
+
+test('Kimi hook adapter translates active edit context to the native message field', () => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-hook-'));
+  try {
+    fs.mkdirSync(path.join(project, '.ultra'));
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-dev', task_id: 'task-7', step: '4.5', status: 'review_pending',
+    }));
+    const result = run('active_task_context.py', {
+      session_id: 'session-2',
+      cwd: project,
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Edit',
+      tool_input: { file_path: 'src/a.py' },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.match(output.message, /task-7/);
+    assert.equal(output.hookSpecificOutput, undefined);
+  } finally {
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('Kimi hook adapter emits the native deny contract for projection writes', () => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-hook-deny-'));
+  try {
+    fs.mkdirSync(path.join(project, '.ultra'));
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-plan', task_id: 'plan', step: 'persist', status: 'active',
+    }));
+    const result = run('active_task_context.py', {
+      session_id: 'session-deny',
+      cwd: project,
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Write',
+      tool_input: { file_path: '.ultra/tasks/tasks.json' },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.hookSpecificOutput.permissionDecision, 'deny');
+    assert.match(output.hookSpecificOutput.permissionDecisionReason, /\.ultra\/state\.db/);
+  } finally {
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('Kimi subagent fields are normalized for the existing lifecycle tracker', () => {
+  const script = [
+    'import importlib.util, json, pathlib',
+    `p = pathlib.Path(${JSON.stringify(ADAPTER)})`,
+    's = importlib.util.spec_from_file_location("kimi_hook_adapter", p)',
+    'm = importlib.util.module_from_spec(s)',
+    's.loader.exec_module(m)',
+    'payload = {"hook_event_name":"SubagentStart","agent_name":"review-code","session_id":"s"}',
+    'print(json.dumps(m.normalize_input(payload)))',
+  ].join('; ');
+  const result = spawnSync('python3', ['-c', script], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), {
+    hook_event_name: 'SubagentStart',
+    agent_name: 'review-code',
+    session_id: 's',
+    agent_id: 'review-code',
+    agent_type: 'review-code',
+  });
+});
+
+test('Kimi stop blocks and recovery context use the exact structured-output schema', () => {
+  const script = [
+    'import importlib.util, json, pathlib',
+    `p = pathlib.Path(${JSON.stringify(ADAPTER)})`,
+    's = importlib.util.spec_from_file_location("kimi_hook_adapter", p)',
+    'm = importlib.util.module_from_spec(s)',
+    's.loader.exec_module(m)',
+    'values = [m.adapt_output({"decision":"block","reason":"finish gates"}, "Stop"), m.adapt_output({"additionalContext":"restored"}, "PostCompact")]',
+    'print(json.dumps(values))',
+  ].join('; ');
+  const result = spawnSync('python3', ['-c', script], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), [
+    {
+      hookSpecificOutput: {
+        message: 'finish gates',
+        permissionDecision: 'deny',
+        permissionDecisionReason: 'finish gates',
+      },
+    },
+    { message: 'restored' },
+  ]);
+});

package/adapters/tests/kimi.test.cjs

@@ -0,0 +1,255 @@
+'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 kimi = require('../kimi.js');
+const {
+  CORE_PUBLIC_SKILLS,
+  WORKFLOW_HOOK_FILES,
+  skillsForRuntime,
+} = require('../_shared/runtime-assets.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PLUGIN_ID = 'ultra-builder-pro';
+
+function mkTarget() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-'));
+}
+
+function layout(home) {
+  return {
+    pluginRoot: path.join(home, 'plugins', 'managed', PLUGIN_ID),
+    registryFile: path.join(home, 'plugins', 'installed.json'),
+  };
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+test('install builds and registers one Kimi-native plugin without changing config.toml', () => {
+  const home = mkTarget();
+  const { pluginRoot, registryFile } = layout(home);
+  const configFile = path.join(home, 'config.toml');
+  const userConfig = '[[hooks]]\nevent = "Stop"\ncommand = "/user/hook.sh"\n';
+  try {
+    fs.writeFileSync(configFile, userConfig);
+    const report = kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+
+    assert.equal(report.target, pluginRoot);
+    assert.equal(fs.readFileSync(configFile, 'utf8'), userConfig);
+    assert.ok(fs.existsSync(path.join(pluginRoot, '.ubp-managed')));
+    assert.ok(fs.existsSync(path.join(pluginRoot, 'provenance.json')));
+
+    const registry = readJson(registryFile);
+    assert.equal(registry.version, 1);
+    assert.equal(registry.plugins.length, 1);
+    assert.deepEqual(registry.plugins[0], {
+      id: PLUGIN_ID,
+      root: pluginRoot,
+      source: 'local-path',
+      enabled: true,
+      installedAt: registry.plugins[0].installedAt,
+      updatedAt: registry.plugins[0].updatedAt,
+      originalSource: REPO_ROOT,
+    });
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Kimi manifest exposes native skills, commands, hooks, session bootstrap, and MCP', () => {
+  const home = mkTarget();
+  const { pluginRoot } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const manifest = readJson(path.join(pluginRoot, 'kimi.plugin.json'));
+
+    assert.equal(manifest.name, PLUGIN_ID);
+    assert.deepEqual(manifest.skills, ['./skills']);
+    assert.deepEqual(manifest.commands, ['./commands']);
+    assert.deepEqual(manifest.sessionStart, { skill: 'using-ultra-builder-pro' });
+    assert.equal(manifest.agents, undefined, 'Kimi 0.26/0.27 has no custom-agent manifest field');
+    assert.deepEqual(manifest.mcpServers[PLUGIN_ID], {
+      transport: 'stdio',
+      command: process.platform === 'win32' ? 'node.exe' : 'env',
+      args: process.platform === 'win32'
+        ? ['./runtime/launch.cjs']
+        : ['node', './runtime/launch.cjs'],
+      enabled: true,
+    });
+
+    const hookText = JSON.stringify(manifest.hooks);
+    assert.match(hookText, /hooks\/adapters\/kimi\.py/);
+    for (const hook of WORKFLOW_HOOK_FILES) assert.match(hookText, new RegExp(hook.replace('.', '\\.')));
+    assert.doesNotMatch(hookText, /memory|recall|journal|prompt[_ -]?capture|block_dangerous|post_edit_guard/i);
+
+    const commands = fs.readdirSync(path.join(pluginRoot, 'commands')).sort();
+    assert.deepEqual(commands, CORE_PUBLIC_SKILLS.map((name) => `${name}.md`).sort());
+    const commandText = fs.readFileSync(path.join(pluginRoot, 'commands', 'ultra-init.md'), 'utf8');
+    assert.match(commandText, /Use the registered `ultra-init` skill/);
+    assert.match(commandText, /\$ARGUMENTS/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Kimi assets are allowlisted and adapted to native tools and paths', () => {
+  const home = mkTarget();
+  const { pluginRoot } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+
+    const skills = fs.readdirSync(path.join(pluginRoot, 'skills'), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory()
+        && fs.existsSync(path.join(pluginRoot, 'skills', entry.name, 'SKILL.md')))
+      .map((entry) => entry.name)
+      .sort();
+    assert.deepEqual(skills, [...skillsForRuntime('kimi'), 'using-ultra-builder-pro'].sort());
+
+    const learn = fs.readFileSync(path.join(pluginRoot, 'skills', 'learn', 'SKILL.md'), 'utf8');
+    const review = fs.readFileSync(path.join(pluginRoot, 'skills', 'ultra-review', 'SKILL.md'), 'utf8');
+    const init = fs.readFileSync(path.join(pluginRoot, 'skills', 'ultra-init', 'SKILL.md'), 'utf8');
+    const bootstrap = fs.readFileSync(
+      path.join(pluginRoot, 'skills', 'using-ultra-builder-pro', 'SKILL.md'),
+      'utf8',
+    );
+    assert.match(learn, /~\/.kimi-code\/skills\/learned-<pattern-slug>-unverified\/SKILL\.md/);
+    assert.match(review, /Kimi `AgentSwarm`/);
+    assert.match(review, /5 specialized reviewers/);
+    assert.doesNotMatch(review, /6 specialized|ALL 6/);
+    assert.match(review, /\$KIMI_PLUGIN_ROOT\/agents\/review-code\.md/);
+    assert.match(review, /`prompt_template` containing\s+`\{\{item\}\}`/);
+    assert.match(review, /selected reviewer names as the `items` array/);
+    assert.match(review, /Launch the coordinator with one foreground Kimi `Agent` call/);
+    assert.doesNotMatch(review, /background mode|Set Kimi `AgentSwarm` parallel execution|Launch review-coordinator with Kimi `AgentSwarm`/);
+    assert.match(init, /\| Kimi \| `\/ultra-builder-pro:ultra-init/);
+    assert.doesNotMatch(init, /codex exec "run \/ultra-init/);
+    assert.match(bootstrap, /\.ultra\/state\.db/);
+    assert.match(bootstrap, /external providers/);
+
+    const allPromptAssets = [];
+    for (const root of ['commands', 'skills', 'agents']) {
+      const pending = [path.join(pluginRoot, root)];
+      while (pending.length) {
+        const current = pending.pop();
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+          const file = path.join(current, entry.name);
+          if (entry.isDirectory()) pending.push(file);
+          else if (entry.isFile() && /\.(?:md|json)$/.test(entry.name)) allPromptAssets.push(file);
+        }
+      }
+    }
+    const foreign = /~\/.claude|~\/.codex|~\/.config\/opencode|CLAUDE\.md|TaskCreate|TaskUpdate|TaskList|AskUserQuestion|run_in_background:\s*true|\$CLAUDE_PLUGIN_ROOT|Kimi `Shell`/;
+    for (const file of allPromptAssets) {
+      const text = fs.readFileSync(file, 'utf8');
+      assert.doesNotMatch(text, foreign, file);
+      assert.doesNotMatch(text, /(^|[\s`("'])\/ultra-(?!builder-pro:)[a-z]/m, file);
+    }
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('reinstall preserves unrelated records and existing Kimi capability choices', () => {
+  const home = mkTarget();
+  const { registryFile } = layout(home);
+  try {
+    fs.mkdirSync(path.dirname(registryFile), { recursive: true });
+    fs.writeFileSync(registryFile, JSON.stringify({
+      version: 1,
+      plugins: [{
+        id: 'mine', root: '/tmp/mine', source: 'local-path', enabled: true,
+        installedAt: '2026-01-01T00:00:00.000Z', originalSource: '/tmp/mine',
+      }],
+    }, null, 2));
+
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const first = readJson(registryFile);
+    const ultra = first.plugins.find((entry) => entry.id === PLUGIN_ID);
+    ultra.enabled = false;
+    ultra.capabilities = { mcpServers: { [PLUGIN_ID]: { enabled: false } } };
+    fs.writeFileSync(registryFile, JSON.stringify(first, null, 2));
+
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const second = readJson(registryFile);
+    assert.deepEqual(second.plugins.map((entry) => entry.id).sort(), ['mine', PLUGIN_ID]);
+    const refreshed = second.plugins.find((entry) => entry.id === PLUGIN_ID);
+    assert.equal(refreshed.installedAt, ultra.installedAt);
+    assert.equal(refreshed.enabled, false);
+    assert.deepEqual(refreshed.capabilities, ultra.capabilities);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('uninstall removes only the owned Kimi plugin record and managed root', () => {
+  const home = mkTarget();
+  const { pluginRoot, registryFile } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const registry = readJson(registryFile);
+    registry.plugins.unshift({
+      id: 'mine', root: '/tmp/mine', source: 'local-path', enabled: true,
+      installedAt: '2026-01-01T00:00:00.000Z', originalSource: '/tmp/mine',
+    });
+    fs.writeFileSync(registryFile, JSON.stringify(registry, null, 2));
+
+    kimi.uninstall({ configDir: home });
+    assert.equal(fs.existsSync(pluginRoot), false);
+    assert.deepEqual(readJson(registryFile).plugins.map((entry) => entry.id), ['mine']);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('install and uninstall refuse to replace or remove an unmanaged Kimi root', () => {
+  const home = mkTarget();
+  const { pluginRoot, registryFile } = layout(home);
+  try {
+    fs.mkdirSync(pluginRoot, { recursive: true });
+    fs.writeFileSync(path.join(pluginRoot, 'user.txt'), 'keep');
+    assert.throws(
+      () => kimi.install({ configDir: home, repoRoot: REPO_ROOT }),
+      /unmanaged Kimi plugin/,
+    );
+
+    fs.mkdirSync(path.dirname(registryFile), { recursive: true });
+    fs.writeFileSync(registryFile, JSON.stringify({
+      version: 1,
+      plugins: [{
+        id: PLUGIN_ID, root: pluginRoot, source: 'local-path', enabled: true,
+        installedAt: '2026-01-01T00:00:00.000Z', originalSource: '/tmp/foreign',
+      }],
+    }));
+    assert.throws(() => kimi.uninstall({ configDir: home }), /unmanaged Kimi plugin/);
+    assert.equal(fs.readFileSync(path.join(pluginRoot, 'user.txt'), 'utf8'), 'keep');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('doctor validates registration and provenance without mutating the Kimi home', () => {
+  const home = mkTarget();
+  const { registryFile } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const before = fs.readFileSync(registryFile);
+    const healthy = kimi.doctor({ configDir: home, repoRoot: REPO_ROOT });
+    assert.equal(healthy.status, 'healthy', JSON.stringify(healthy, null, 2));
+    assert.deepEqual(fs.readFileSync(registryFile), before);
+
+    const registry = readJson(registryFile);
+    registry.plugins[0].enabled = false;
+    fs.writeFileSync(registryFile, JSON.stringify(registry, null, 2));
+    const degraded = kimi.doctor({ configDir: home, repoRoot: REPO_ROOT });
+    assert.equal(degraded.status, 'degraded');
+    assert.ok(degraded.issues.some((issue) => issue.code === 'PLUGIN_REGISTRATION_INVALID'));
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/agents/debugger.md

@@ -115,6 +115,18 @@ If **3 consecutive fix attempts fail**, and each reveals new problems in differe
 {test output proving fix resolves the issue, no regressions}
 ```
 
+When the parent assigns an Ultra `incident` change, also map the verified report
+into the exact durable `diagnosis.md` contract:
+
+- `Reproduction`: the smallest repeatable symptom and exact trigger;
+- `Hypotheses`: falsifiable hypotheses and the evidence that accepted/rejected each;
+- `Root cause`: the earliest incorrect state and why it occurred;
+- `Regression test`: the failing-first test and its final passing command;
+- `Recovery`: rollback, retry, repair, or operator action when applicable.
+
+Return this content to the primary agent. Do not write `.ultra/state.db` or claim
+incident convergence; the primary agent owns the change artifact and verification.
+
 ## Rules
 
 - Never guess. Every claim must have evidence from code or output.

package/bin/handbook.js

@@ -14,8 +14,8 @@ const {
 function usage() {
   return [
     'Usage:',
-    '  ubp-handbook preview --runtime <claude|codex|opencode> [--file <path>]',
-    '  ubp-handbook apply   --runtime <claude|codex|opencode> [--file <path>]',
+    '  ubp-handbook preview --runtime <claude|codex|opencode|kimi> [--file <path>]',
+    '  ubp-handbook apply   --runtime <claude|codex|opencode|kimi> [--file <path>]',
     '',
     'The apply command creates a timestamped backup before changing an existing file.',
   ].join('\n');