ultra-builder-pro-cli 0.17.1 → 0.19.1

package/adapters/_shared/codex-assets.cjs

@@ -223,47 +223,52 @@ function buildCommandMap() {
   return Object.fromEntries(COMMAND_NAMES.map((name) => [`/${name}`, `$ultra-builder-pro:${name}`]));
 }
 
-function hookCommand(feature, ...args) {
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\"'\"'")}'`;
+}
+
+function hookCommand(pluginRoot, feature, ...args) {
+  const adapter = path.join(path.resolve(pluginRoot), 'hooks', 'adapters', 'codex.py');
   return [
-    'python3 "$PLUGIN_ROOT/hooks/adapters/codex.py"',
-    JSON.stringify(feature),
-    ...args.map((arg) => JSON.stringify(arg)),
+    `python3 ${shellQuote(adapter)}`,
+    shellQuote(feature),
+    ...args.map((arg) => shellQuote(arg)),
   ].join(' ');
 }
 
-function commandHook(feature, timeout, statusMessage, ...args) {
+function commandHook(pluginRoot, feature, timeout, statusMessage, ...args) {
   return {
     type: 'command',
-    command: hookCommand(feature, ...args),
+    command: hookCommand(pluginRoot, feature, ...args),
     timeout,
     statusMessage,
   };
 }
 
-function buildHooksManifest() {
+function buildHooksManifest(pluginRoot) {
   return {
     hooks: {
       SessionStart: [
-        { hooks: [commandHook('health_check.py', 5, 'Checking Ultra runtime')] },
-        { hooks: [commandHook('workflow_context.py', 10, 'Loading active Ultra workflow')] },
+        { hooks: [commandHook(pluginRoot, 'health_check.py', 5, 'Checking Ultra runtime')] },
+        { hooks: [commandHook(pluginRoot, 'workflow_context.py', 10, 'Loading active Ultra workflow')] },
       ],
       PreToolUse: [
-        { matcher: 'Edit|Write|apply_patch', hooks: [commandHook('active_task_context.py', 3, 'Checking active Ultra task')] },
+        { matcher: 'Edit|Write|apply_patch', hooks: [commandHook(pluginRoot, 'active_task_context.py', 3, 'Checking active Ultra task')] },
       ],
       PreCompact: [
-        { matcher: 'manual|auto', hooks: [commandHook('workflow_checkpoint.py', 10, 'Saving Ultra workflow checkpoint')] },
+        { matcher: 'manual|auto', hooks: [commandHook(pluginRoot, 'workflow_checkpoint.py', 10, 'Saving Ultra workflow checkpoint')] },
       ],
       PostCompact: [
-        { hooks: [commandHook('workflow_resume.py', 10, 'Restoring Ultra workflow checkpoint')] },
+        { hooks: [commandHook(pluginRoot, 'workflow_resume.py', 10, 'Restoring Ultra workflow checkpoint')] },
       ],
       Stop: [
-        { hooks: [commandHook('pre_stop_check.py', 5, 'Reporting Ultra workflow position')] },
+        { hooks: [commandHook(pluginRoot, 'pre_stop_check.py', 5, 'Reporting Ultra workflow position')] },
       ],
       SubagentStart: [
-        { hooks: [commandHook('subagent_tracker.py', 5, 'Tracking Ultra subagent', 'start')] },
+        { hooks: [commandHook(pluginRoot, 'subagent_tracker.py', 5, 'Tracking Ultra subagent', 'start')] },
       ],
       SubagentStop: [
-        { hooks: [commandHook('subagent_tracker.py', 5, 'Tracking Ultra subagent', 'stop')] },
+        { hooks: [commandHook(pluginRoot, 'subagent_tracker.py', 5, 'Tracking Ultra subagent', 'stop')] },
       ],
     },
   };
@@ -281,7 +286,10 @@ function copyHooks(repoRoot, pluginRoot) {
     path.join(sourceRoot, 'adapters', 'codex.py'),
     path.join(targetRoot, 'adapters', 'codex.py'),
   );
-  writeAtomic(path.join(targetRoot, 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
+  writeAtomic(
+    path.join(targetRoot, 'hooks.json'),
+    JSON.stringify(buildHooksManifest(pluginRoot), null, 2) + '\n',
+  );
 }
 
 function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {

package/adapters/_shared/file-ops.cjs

@@ -18,13 +18,50 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
 
+function resolveAtomicTarget(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isSymbolicLink()) return file;
+    try {
+      return fs.realpathSync(file);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`refusing to replace dangling symlink: ${file}`);
+      }
+      throw error;
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') return file;
+    throw error;
+  }
+}
+
 function writeAtomic(file, content) {
   ensureDir(path.dirname(file));
+  // Rename over the resolved target rather than over a user-managed symlink.
+  // This keeps dotfile-manager links intact while retaining atomic replacement.
+  const target = resolveAtomicTarget(file);
+  ensureDir(path.dirname(target));
+  let mode = null;
+  try {
+    mode = fs.statSync(target).mode & 0o7777;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
   // randomUUID defeats predictable tmp-name attacks and PID+ms collisions
   // when two writers hit the same path inside one millisecond.
-  const tmp = `${file}.tmp-${crypto.randomUUID()}`;
-  fs.writeFileSync(tmp, content);
-  fs.renameSync(tmp, file);
+  const tmp = `${target}.tmp-${crypto.randomUUID()}`;
+  try {
+    fs.writeFileSync(tmp, content, mode === null ? undefined : { mode });
+    if (mode !== null) fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, target);
+  } finally {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
 }
 
 function listRelative(root, { exclude = DEFAULT_EXCLUDES } = {}) {

package/adapters/_shared/provenance.cjs

@@ -90,15 +90,76 @@ function digestEntries(entries) {
   return hash.digest('hex');
 }
 
+function runGit(repoRoot, args, encoding = 'utf8') {
+  const result = spawnSync('git', args, {
+    cwd: repoRoot,
+    encoding,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return result.status === 0 ? result.stdout : null;
+}
+
 function sourceCommit(repoRoot) {
   if (!fs.existsSync(path.join(repoRoot, '.git'))) return null;
-  const result = spawnSync('git', ['rev-parse', 'HEAD'], {
-    cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-  });
-  const value = result.status === 0 ? result.stdout.trim() : '';
+  const result = runGit(repoRoot, ['rev-parse', 'HEAD']);
+  const value = typeof result === 'string' ? result.trim() : '';
   return /^[0-9a-f]{40,64}$/i.test(value) ? value : null;
 }
 
+function sourceWorktreeState(repoRoot, commit) {
+  if (!fs.existsSync(path.join(repoRoot, '.git'))) {
+    return { sourceDirty: null, sourceWorktreeDigest: null };
+  }
+  const status = runGit(
+    repoRoot, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--', '.'], null,
+  );
+  if (!Buffer.isBuffer(status)) {
+    return { sourceDirty: null, sourceWorktreeDigest: null };
+  }
+  const trackedDiff = commit
+    ? runGit(repoRoot, ['diff', '--binary', 'HEAD', '--', '.'], null)
+    : runGit(repoRoot, ['diff', '--binary', '--cached', '--', '.'], null);
+  const unstagedDiff = commit
+    ? Buffer.alloc(0)
+    : runGit(repoRoot, ['diff', '--binary', '--', '.'], null);
+  const untrackedOutput = runGit(
+    repoRoot, ['ls-files', '--others', '--exclude-standard', '-z', '--', '.'],
+  );
+  if (!Buffer.isBuffer(trackedDiff) || !Buffer.isBuffer(unstagedDiff)
+    || typeof untrackedOutput !== 'string') {
+    return { sourceDirty: null, sourceWorktreeDigest: null };
+  }
+
+  const hash = crypto.createHash(DIGEST_ALGORITHM);
+  hash.update('ultra-source-worktree-v1\0');
+  hash.update(commit || 'unborn');
+  hash.update('\0');
+  hash.update(status);
+  hash.update('\0');
+  hash.update(trackedDiff);
+  hash.update('\0');
+  hash.update(unstagedDiff);
+  hash.update('\0');
+  const untrackedPaths = untrackedOutput.split('\0').filter(Boolean).sort();
+  for (const relative of untrackedPaths) {
+    const target = path.resolve(repoRoot, relative);
+    if (target !== repoRoot && !target.startsWith(`${path.resolve(repoRoot)}${path.sep}`)) {
+      return { sourceDirty: null, sourceWorktreeDigest: null };
+    }
+    const stat = fs.lstatSync(target);
+    hash.update(relative);
+    hash.update('\0');
+    if (stat.isSymbolicLink()) hash.update(fs.readlinkSync(target));
+    else if (stat.isFile()) hash.update(fs.readFileSync(target));
+    hash.update('\0');
+  }
+  return {
+    sourceDirty: status.length > 0,
+    sourceWorktreeDigest: hash.digest('hex'),
+  };
+}
+
 function repositoryUrl(pkg) {
   if (typeof pkg.repository === 'string') return pkg.repository;
   if (pkg.repository && typeof pkg.repository.url === 'string') return pkg.repository.url;
@@ -107,10 +168,12 @@ function repositoryUrl(pkg) {
 
 function packageSource(repoRoot) {
   const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  const commit = sourceCommit(repoRoot);
   return {
     packageInfo: { name: pkg.name, version: pkg.version },
     repository: repositoryUrl(pkg),
-    sourceCommit: sourceCommit(repoRoot),
+    sourceCommit: commit,
+    ...sourceWorktreeState(repoRoot, commit),
   };
 }
 
@@ -123,11 +186,18 @@ function assetRefsForTree(rootName, root, { exclude = [] } = {}) {
 
 function writeProvenance({
   file, adapter, packageInfo, repository, sourceCommit: commit = null,
+  sourceDirty: dirty = null, sourceWorktreeDigest: worktreeDigest = null,
   roots: inputRoots, assets: inputAssets, contracts: inputContracts = {},
 }) {
   if (!file || !adapter || !packageInfo?.name || !packageInfo?.version || !repository) {
     throw new Error('provenance file, adapter, package, version, and repository are required');
   }
+  if (dirty !== null && typeof dirty !== 'boolean') {
+    throw new Error('provenance source dirty state must be a boolean or null');
+  }
+  if (worktreeDigest !== null && !/^[0-9a-f]{64}$/i.test(worktreeDigest)) {
+    throw new Error('provenance source worktree digest must be a SHA-256 digest or null');
+  }
   const roots = normalizeRoots(inputRoots);
   const refs = normalizeAssetRefs(inputAssets, roots);
   const assets = refs.map((ref) => {
@@ -145,7 +215,12 @@ function writeProvenance({
     schema_version: SCHEMA_VERSION,
     adapter,
     package: { name: packageInfo.name, version: packageInfo.version },
-    source: { repository, commit: commit || null },
+    source: {
+      repository,
+      commit: commit || null,
+      dirty,
+      worktree_digest: worktreeDigest,
+    },
     installed_at: new Date().toISOString(),
     roots,
     content: { algorithm: DIGEST_ALGORITHM, digest: digestEntries(assets) },
@@ -188,6 +263,15 @@ function inspectProvenance({ file, expectedAdapter = null, expectedPackageVersio
     if (!manifest.package?.name || !manifest.package?.version || !manifest.source?.repository) {
       throw new Error('package and source metadata required');
     }
+    if (manifest.source.dirty !== undefined && manifest.source.dirty !== null
+      && typeof manifest.source.dirty !== 'boolean') {
+      throw new Error('source dirty state must be a boolean or null');
+    }
+    if (manifest.source.worktree_digest !== undefined
+      && manifest.source.worktree_digest !== null
+      && !/^[0-9a-f]{64}$/i.test(manifest.source.worktree_digest)) {
+      throw new Error('source worktree digest must be a SHA-256 digest or null');
+    }
   } catch (error) {
     return invalidReport(
       manifestPath, 'degraded', issue('PROVENANCE_INVALID', { message: error.message }), expectedAdapter,

package/adapters/_shared/runtime-assets.cjs

@@ -51,16 +51,6 @@ const MCP_DEPENDENT_SKILLS = Object.freeze([
   'ultra-doctor',
 ]);
 
-const RETIRED_SKILLS = Object.freeze([
-  'agent-browser',
-  'find-skills',
-  'recall',
-  'use-railway',
-  'vercel-composition-patterns',
-  'vercel-react-best-practices',
-  'vercel-react-native-skills',
-]);
-
 const WORKFLOW_HOOK_FILES = Object.freeze([
   'active_task_context.py',
   'context_spine.py',
@@ -98,7 +88,6 @@ module.exports = {
   SUPPORTED_RUNTIMES,
   COLLAB_SKILLS_BY_RUNTIME,
   MCP_DEPENDENT_SKILLS,
-  RETIRED_SKILLS,
   WORKFLOW_HOOK_FILES,
   isSupportedRuntime,
   skillPolicy,

package/adapters/claude.js

@@ -68,10 +68,12 @@ function copySkills(repoRoot, target, names) {
             'Claude Code Task workers using the installed review agent definitions',
           );
         }
+        const policy = skillPolicy(name);
         return Buffer.from(serializeFrontmatter({
           name,
           description: fm.description,
-          'user-invocable': skillPolicy(name).userInvocable,
+          'user-invocable': policy.userInvocable,
+          ...(policy.userInvocable ? { 'disable-model-invocation': true } : {}),
         }, adaptedBody));
       },
     });

package/adapters/kimi.js

@@ -20,6 +20,7 @@ const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
   WORKFLOW_HOOK_FILES,
+  skillPolicy,
   skillsForRuntime,
 } = require('./_shared/runtime-assets.cjs');
 
@@ -28,7 +29,6 @@ const MCP_SERVER_NAME = PLUGIN_ID;
 const PROVENANCE_FILE = 'provenance.json';
 const REGISTRY_RELATIVE = path.join('plugins', 'installed.json');
 const MANAGED_RELATIVE = path.join('plugins', 'managed', PLUGIN_ID);
-const BOOTSTRAP_SKILL = 'using-ultra-builder-pro';
 
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return path.resolve(ctx.configDir);
@@ -127,11 +127,13 @@ function transformSkill(buf, relPath, skillName) {
   if (!relPath.endsWith('.md')) return buf;
   const { fm, body } = parseFm(source);
   if (!fm) return Buffer.from(kimiTextTransform(source, skillName), 'utf8');
+  const policy = skillPolicy(skillName);
   const nativeFm = {
     name: String(fm.name || skillName),
     description: kimiTextTransform(fm.description || `${skillName} workflow`, skillName)
       .replace(/\s+/g, ' ')
       .trim(),
+    ...(policy.userInvocable ? { disableModelInvocation: true } : {}),
   };
   return Buffer.from(serializeFm(nativeFm, kimiTextTransform(body, skillName)), 'utf8');
 }
@@ -162,29 +164,6 @@ function copySkills(repoRoot, pluginRoot) {
     });
     installed.push(name);
   }
-  const bootstrapRoot = path.join(pluginRoot, 'skills', BOOTSTRAP_SKILL);
-  ensureDir(bootstrapRoot);
-  writeAtomic(path.join(bootstrapRoot, 'SKILL.md'), `---
-name: ${BOOTSTRAP_SKILL}
-description: Bootstrap the Kimi-native Ultra Builder Pro runtime contract at session start.
----
-
-# Ultra Builder Pro for Kimi Code
-
-Kimi Code is the primary host and owns all edits, evidence, and final verification. Use the
-namespaced \`/ultra-builder-pro:ultra-*\` commands or invoke the registered Ultra skills directly.
-
-- \`.ultra/state.db\` is the only durable Ultra authority. JSON and Markdown under \`.ultra/\` are
-  projections or workflow artifacts and must never replace MCP state writes.
-- Memory and code graph data belong to separately installed external providers. Ultra stores only
-  provider metadata references and never captures prompts, transcripts, or cross-session memory.
-- Use Kimi \`TodoList\` for session coordination and Kimi \`Agent\` / \`AgentSwarm\` for bounded
-  workers. Bundled files under \`$KIMI_PLUGIN_ROOT/agents/\` are worker prompt templates.
-- Before compaction, Ultra saves its workflow checkpoint. After compaction or recovery, inspect
-  \`.ultra/runtime/checkpoint.json\` and call the Ultra status/doctor MCP tools before continuing.
-- If no Ultra workflow is active, the lifecycle hooks remain advisory except projection protection.
-`);
-  installed.push(BOOTSTRAP_SKILL);
   return installed;
 }
 
@@ -280,7 +259,6 @@ function writeManifest(repoRoot, pluginRoot) {
     homepage: pkg.homepage,
     license: pkg.license || 'MIT',
     skills: ['./skills'],
-    sessionStart: { skill: BOOTSTRAP_SKILL },
     mcpServers: { [MCP_SERVER_NAME]: mcpManifest() },
     hooks: buildHooksManifest(),
     commands: ['./commands'],
@@ -351,9 +329,6 @@ function writePluginProvenance(repoRoot, target) {
       mcp_launcher: { root: 'plugin', path: path.join('runtime', 'launch.cjs') },
       hook_event_helper: { root: 'plugin', path: path.join('runtime', 'hook-event.cjs') },
       hook_adapter: { root: 'plugin', path: path.join('hooks', 'adapters', 'kimi.py') },
-      session_bootstrap: {
-        root: 'plugin', path: path.join('skills', BOOTSTRAP_SKILL, 'SKILL.md'),
-      },
     },
   });
   return { file, manifest };
@@ -444,7 +419,7 @@ function doctor(ctx = {}) {
       && manifest.skills.includes('./skills')
       && Array.isArray(manifest.commands)
       && manifest.commands.includes('./commands')
-      && manifest.sessionStart?.skill === BOOTSTRAP_SKILL;
+      && manifest.sessionStart === undefined;
     const mcp = manifest.mcpServers?.[MCP_SERVER_NAME];
     const expected = mcpManifest();
     mcpOk = !!mcp
@@ -508,7 +483,6 @@ module.exports = {
   name: 'kimi',
   PLUGIN_ID,
   MCP_SERVER_NAME,
-  BOOTSTRAP_SKILL,
   buildHooksManifest,
   kimiTextTransform,
   resolveTarget,

package/adapters/opencode.js

@@ -38,6 +38,11 @@ const PLUGIN_MARKER = '// Managed by Ultra Builder Pro.';
 const PROVENANCE_FILE = 'provenance.json';
 const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
 
+function discoverableSkillNames() {
+  return skillsForRuntime('opencode')
+    .filter((name) => !CORE_PUBLIC_SKILLS.includes(name));
+}
+
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return ctx.configDir;
   if (ctx.scope === 'global') {
@@ -97,16 +102,26 @@ function openCodeTextTransform(input, assetName = '') {
   return text;
 }
 
-function openCodeCommandTransform(buf, relPath, commandName) {
+function openCodeCommandTransform(buf, relPath, commandName, workflowFile) {
   if (!relPath.endsWith('.md')) return buf;
-  const { fm, body } = parseFm(buf.toString('utf8'));
-  if (!fm) return Buffer.from(openCodeTextTransform(buf.toString('utf8'), commandName), 'utf8');
+  const { fm } = parseFm(buf.toString('utf8'));
+  if (!fm) throw new Error(`missing frontmatter in OpenCode command: ${commandName}`);
   const nativeFm = {
     description: openCodeTextTransform(fm.description || `${commandName} workflow`, commandName)
       .replace(/\s+/g, ' ')
       .trim(),
   };
-  return Buffer.from(serializeFm(nativeFm, openCodeTextTransform(body, commandName)), 'utf8');
+  const body = [
+    `# Run ${commandName}`,
+    '',
+    `Read and follow \`${workflowFile}\` as the only workflow definition.`,
+    'This explicit command is the activation boundary; do not substitute a model-discovered',
+    'public skill or start another public Ultra workflow automatically.',
+    '',
+    'Arguments: $ARGUMENTS',
+    '',
+  ].join('\n');
+  return Buffer.from(serializeFm(nativeFm, body), 'utf8');
 }
 
 function openCodeSkillAssetTransform(buf, relPath, skillName) {
@@ -229,7 +244,10 @@ function copyCommands(repoRoot, target) {
     const file = `${name}.md`;
     const source = path.join(repoRoot, 'commands', file);
     if (!fs.existsSync(source)) throw new Error(`missing allowlisted OpenCode command: ${file}`);
-    const transformed = withManagedMarker(openCodeCommandTransform(fs.readFileSync(source), file, name));
+    const workflowFile = path.join(target, BUNDLE_DIR, 'workflows', name, 'SKILL.md');
+    const transformed = withManagedMarker(
+      openCodeCommandTransform(fs.readFileSync(source), file, name, workflowFile),
+    );
     writeAtomic(path.join(output, file), transformed);
     copied.push(file);
   }
@@ -238,7 +256,7 @@ function copyCommands(repoRoot, target) {
 
 function copySkills(repoRoot, target) {
   const copied = [];
-  const names = skillsForRuntime('opencode');
+  const names = discoverableSkillNames();
   const skillsRoot = path.join(target, 'skills');
   ensureDir(skillsRoot);
   for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
@@ -262,6 +280,22 @@ function copySkills(repoRoot, target) {
   return copied;
 }
 
+function copyPrivateWorkflows(repoRoot, bundleRoot) {
+  const copied = [];
+  const workflowsRoot = path.join(bundleRoot, 'workflows');
+  for (const name of CORE_PUBLIC_SKILLS) {
+    const source = path.join(repoRoot, 'skills', name);
+    if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+      throw new Error(`missing allowlisted OpenCode workflow: ${name}`);
+    }
+    const files = copyTree(source, path.join(workflowsRoot, name), {
+      transform: (buf, relPath) => openCodeSkillAssetTransform(buf, relPath, name),
+    });
+    copied.push(...files.map((rel) => path.join('workflows', name, rel)));
+  }
+  return copied;
+}
+
 function copyAgents(repoRoot, target) {
   const sourceRoot = path.join(repoRoot, 'agents');
   const output = path.join(target, 'agents');
@@ -279,7 +313,7 @@ function preflightAssets(repoRoot, target) {
   for (const name of COMMAND_NAMES) {
     assertManagedTextTarget(path.join(target, 'commands', `${name}.md`), 'command');
   }
-  for (const name of skillsForRuntime('opencode')) {
+  for (const name of discoverableSkillNames()) {
     const destination = path.join(target, 'skills', name);
     if (fs.existsSync(destination) && !isManaged(destination)) {
       throw new Error(`refusing to replace unmanaged OpenCode skill: ${destination}`);
@@ -316,8 +350,8 @@ const BREADCRUMB_CLI = path.resolve(
 function findUltraRoot(directory) {
   let current = path.resolve(directory);
   while (true) {
-    const ultra = path.join(current, ".ultra");
-    if (fs.existsSync(ultra) && fs.statSync(ultra).isDirectory()) return current;
+    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;
@@ -335,12 +369,13 @@ function readUltraContext(directory) {
       timeout: 5000,
     });
     const value = JSON.parse(raw);
-    if (!value?.breadcrumb || typeof value.text !== "string" || !value.text) {
-      throw new Error("canonical breadcrumb response is incomplete");
+    // 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 (error) {
-    process.stderr.write(\`[ultra-builder-pro] cannot read canonical breadcrumb: \${error.message}\\n\`);
+  } catch {
     return { root, breadcrumb: null, text: null };
   }
 }
@@ -415,6 +450,7 @@ function install(ctx = {}) {
   const bundleRoot = path.join(target, BUNDLE_DIR);
   if (fs.existsSync(bundleRoot)) removeTree(bundleRoot);
   ensureDir(bundleRoot);
+  report.copied.workflows = copyPrivateWorkflows(repoRoot, bundleRoot);
   const runtime = buildMcpRuntime(repoRoot, bundleRoot, { runtime: 'opencode' });
   markManaged(bundleRoot, { adapter: 'opencode', asset: 'runtime-bundle' });
   const configFile = path.join(target, 'opencode.json');
@@ -433,7 +469,7 @@ function install(ctx = {}) {
   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) => ({
+  const skillMarkers = discoverableSkillNames().map((name) => ({
     root: 'config', path: path.join('skills', name, '.ubp-managed'),
   }));
   const provenanceFile = path.join(bundleRoot, PROVENANCE_FILE);

package/docs/AGENT-CONTEXT.md

@@ -12,8 +12,8 @@ Ultra Builder Pro owns only:
   `ultra-think`, plus the daily `ultra-change` and diagnostic `ultra-doctor`;
 - four internal agent-only rule skills: `code-review-expert`, `security-rules`,
   `integration-rules`, and `testing-rules`;
-- the host-specific collaboration companions, `ultra-verify`, and the minimal
-  Kimi session bootstrap required to establish the shared runtime boundary;
+- the host-specific collaboration companions, `ultra-verify`, and host-native
+  explicit command or skill entry points;
 - bounded review/debug agents, workflow-only hooks, MCP task state, and the
   portable CLI/orchestrator.
 
@@ -191,20 +191,17 @@ Archive before prune; the confirmation token is intentionally required.
     └── delivery/<workflow-id>.json
 ```
 
-## 10. User handbook integration
+## 10. Plugin and user-instruction isolation
 
-General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
-Ultra Builder Pro contributes one managed section only. Preview or apply it with:
+General engineering doctrine and long-term personal preferences live in each
+host's durable `CLAUDE.md` or `AGENTS.md`. Ultra never writes those files. Its
+workflow doctrine remains in plugin-owned skills and is loaded only through an
+explicit public invocation.
 
-```bash
-ubp-handbook preview --runtime codex
-ubp-handbook apply --runtime codex
-```
-
-Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. Apply creates a
-timestamped backup, replaces only the marked block, and can migrate the old
-Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
-user section. Plugin adapters themselves do not silently overwrite handbooks.
+Installation and uninstall own only adapter-declared commands, skills, workers,
+hooks, runtime assets, provenance, and host registration. Project authority is
+created only by an explicit `ultra-init`, and uninstall never deletes `.ultra/`.
+See [`PLUGIN-ISOLATION-CONTRACT.md`](./PLUGIN-ISOLATION-CONTRACT.md).
 
 ## 11. Verification