ultra-builder-pro-cli 0.26.1 → 3.0.2

package/adapters/zcode.js

@@ -0,0 +1,375 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const {
+  copyHooks,
+  copySkills,
+  inspectPlugin,
+  markManaged,
+  publishManagedTrees,
+  removeManaged,
+  writePluginProvenance,
+} = require('./_shared/plugin-core.cjs');
+const {
+  captureAbsent,
+  ensureDir,
+  isManaged,
+  managedMetadata,
+  pruneCreatedEmpty,
+  removeTree,
+  writeAtomic,
+} = require('./_shared/file-ops.cjs');
+const { zcodeBinary } = require('./_shared/host-profile.cjs');
+
+const PLUGIN_NAME = 'ultra-builder-pro';
+const INLINE_PLUGIN_ID = `${PLUGIN_NAME}@inline`;
+
+function resolveTarget(ctx = {}) {
+  if (ctx.configDir) return path.resolve(ctx.configDir);
+  const configured = ctx.zcodeHome || ctx.env?.ZCODE_HOME || process.env.ZCODE_HOME;
+  return configured ? path.resolve(configured) : path.join(ctx.homeDir || os.homedir(), '.zcode');
+}
+
+function resolveCliRoot(ctx = {}) {
+  return path.join(resolveTarget(ctx), 'cli');
+}
+
+function resolveConfigFile(ctx = {}) {
+  return path.join(resolveCliRoot(ctx), 'config.json');
+}
+
+function resolveMarketplaceRoot(ctx = {}) {
+  return path.join(resolveCliRoot(ctx), 'plugins', 'marketplaces', PLUGIN_NAME);
+}
+
+function resolveMarketplaceFile(ctx = {}) {
+  return path.join(resolveMarketplaceRoot(ctx), 'marketplace.json');
+}
+
+function resolvePluginRoot(ctx = {}) {
+  return path.join(resolveMarketplaceRoot(ctx), 'plugin');
+}
+
+function resolveRepoRoot(ctx = {}) {
+  return ctx.repoRoot || path.resolve(__dirname, '..');
+}
+
+function assertPluginScope(ctx = {}) {
+  if (ctx.scope === 'local' && !ctx.configDir) {
+    throw new Error('ZCode plugins are user-scoped; use global scope or an isolated configDir');
+  }
+}
+
+function hookProcess(name) {
+  return {
+    type: 'process',
+    command: 'python3',
+    args: [`\${ZCODE_PLUGIN_ROOT}/hooks/adapters/zcode.py`, name],
+    timeoutMs: 10000,
+  };
+}
+
+function buildHooksManifest() {
+  return {
+    hooks: {
+      SessionStart: [
+        { matcher: 'startup|resume|clear', hooks: [hookProcess('session_context.py')] },
+        { matcher: 'compact', hooks: [hookProcess('compact_context.py')] },
+      ],
+      PreToolUse: [
+        { matcher: 'Write|Edit|ApplyPatch|Grep', hooks: [hookProcess('mid_workflow_recall.py')] },
+        { matcher: 'Bash', hooks: [hookProcess('block_dangerous_commands.py')] },
+      ],
+      PostToolUse: [
+        { matcher: 'Write|Edit|ApplyPatch', hooks: [hookProcess('post_edit_guard.py')] },
+      ],
+    },
+  };
+}
+
+function loadConfig(file) {
+  if (!fs.existsSync(file)) return {};
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!value || Array.isArray(value) || typeof value !== 'object') {
+    throw new Error(`invalid ZCode config: ${file}`);
+  }
+  if (value.plugins !== undefined && (
+    !value.plugins || Array.isArray(value.plugins) || typeof value.plugins !== 'object'
+  )) throw new Error(`invalid ZCode plugins config: ${file}`);
+  if (value.plugins?.dirs !== undefined && (
+    !Array.isArray(value.plugins.dirs)
+    || !value.plugins.dirs.every((entry) => typeof entry === 'string' && entry)
+  )) throw new Error(`invalid ZCode plugins.dirs config: ${file}`);
+  if (value.plugins?.enabled !== undefined && typeof value.plugins.enabled !== 'boolean') {
+    throw new Error(`invalid ZCode plugins.enabled config: ${file}`);
+  }
+  return value;
+}
+
+function configOwnership(file, pluginRoot) {
+  const exists = fs.existsSync(file);
+  const config = loadConfig(file);
+  const plugins = config.plugins;
+  return {
+    file_created: !exists,
+    plugins_created: plugins === undefined,
+    enabled_created: plugins === undefined || !Object.hasOwn(plugins, 'enabled'),
+    enabled_previous: plugins?.enabled,
+    dirs_created: plugins === undefined || !Object.hasOwn(plugins, 'dirs'),
+    dir_preexisting: Array.isArray(plugins?.dirs) && plugins.dirs.includes(pluginRoot),
+  };
+}
+
+function registeredConfig(config, pluginRoot) {
+  const plugins = config.plugins ? { ...config.plugins } : {};
+  const dirs = Array.isArray(plugins.dirs) ? [...plugins.dirs] : [];
+  if (!dirs.includes(pluginRoot)) dirs.push(pluginRoot);
+  plugins.enabled = true;
+  plugins.dirs = dirs;
+  return { ...config, plugins };
+}
+
+function unregisteredConfig(config, pluginRoot, ownership) {
+  if (!config.plugins || Array.isArray(config.plugins) || typeof config.plugins !== 'object') {
+    throw new Error('cannot unregister Ultra from an invalid ZCode plugins config');
+  }
+  const next = { ...config, plugins: { ...config.plugins } };
+  if (!ownership.dir_preexisting && Array.isArray(next.plugins.dirs)) {
+    next.plugins.dirs = next.plugins.dirs.filter((entry) => entry !== pluginRoot);
+  }
+  if (ownership.dirs_created && next.plugins.dirs?.length === 0) delete next.plugins.dirs;
+
+  if (ownership.enabled_created) {
+    if (next.plugins.enabled === true) delete next.plugins.enabled;
+  } else if (next.plugins.enabled === true && ownership.enabled_previous !== true) {
+    next.plugins.enabled = ownership.enabled_previous;
+  }
+  if (ownership.plugins_created && Object.keys(next.plugins).length === 0) delete next.plugins;
+  return next;
+}
+
+function buildStaging(repoRoot, staging, publishedRoot) {
+  const plugin = path.join(staging, 'plugin');
+  const skills = copySkills({ runtime: 'zcode', repoRoot, skillRoot: path.join(plugin, 'skills') });
+  copyHooks({
+    runtime: 'zcode', repoRoot, hookRoot: path.join(plugin, 'hooks'),
+    hooksManifest: buildHooksManifest(),
+  });
+  const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  writeAtomic(path.join(plugin, '.zcode-plugin', 'plugin.json'), `${JSON.stringify({
+    name: PLUGIN_NAME,
+    version: pkg.version,
+    description: 'File-first Ultra Builder Pro workflows for ZCode.',
+    author: { name: pkg.author },
+    homepage: pkg.homepage,
+    repository: pkg.repository?.url || pkg.repository,
+    license: pkg.license,
+    skills: './skills',
+    hooks: './hooks/hooks.json',
+  }, null, 2)}\n`);
+  writeAtomic(path.join(staging, 'marketplace.json'), `${JSON.stringify({
+    name: PLUGIN_NAME,
+    plugins: [{
+      name: PLUGIN_NAME,
+      version: pkg.version,
+      description: 'File-first Ultra Builder Pro workflows for ZCode.',
+      source: './plugin',
+    }],
+  }, null, 2)}\n`);
+  markManaged(plugin, { adapter: 'zcode', plugin: PLUGIN_NAME, version: pkg.version });
+  writePluginProvenance({
+    adapter: 'zcode', repoRoot, stagingRoot: plugin, publishedRoot,
+    contracts: {
+      plugin_manifest: { root: 'plugin', path: '.zcode-plugin/plugin.json' },
+      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
+      hook_adapter: { root: 'plugin', path: 'hooks/adapters/zcode.py' },
+    },
+  });
+  return { skills };
+}
+
+function shouldRunHostCli(ctx = {}) {
+  if (typeof ctx.runHostCli === 'boolean') return ctx.runHostCli;
+  return ctx.scope === 'global' && !ctx.configDir;
+}
+
+function zcodeCommand(ctx, args) {
+  const selected = ctx.zcodeBin || process.env.ZCODE_BIN || zcodeBinary();
+  const command = selected.endsWith('.cjs') || selected.endsWith('.js') ? process.execPath : selected;
+  const argv = command === selected ? args : [selected, ...args];
+  const result = spawnSync(command, argv, {
+    encoding: 'utf8',
+    timeout: ctx.hostCliTimeoutMs || 30000,
+    env: { ...process.env, HOME: ctx.homeDir || os.homedir() },
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || '').trim() || `zcode ${args.join(' ')} failed`);
+  }
+  return result.stdout;
+}
+
+function nativePlugin(ctx) {
+  const value = JSON.parse(zcodeCommand(ctx, ['plugins', 'list', '--json']));
+  if (!Array.isArray(value.plugins)) throw new Error('zcode plugins list --json must include plugins');
+  return value.plugins.find((entry) => entry?.id === INLINE_PLUGIN_ID) || null;
+}
+
+function install(ctx = {}) {
+  assertPluginScope(ctx);
+  const target = resolveMarketplaceRoot(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const configRoot = resolveTarget(ctx);
+  const configFile = resolveConfigFile(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  if (fs.existsSync(target) && !isManaged(target)) {
+    throw new Error(`refusing to replace unmanaged ZCode marketplace: ${target}`);
+  }
+  const previousMetadata = managedMetadata(target) || {};
+  const cleanupAbsent = previousMetadata.cleanup_absent || captureAbsent(configRoot, [
+    '.', 'cli', path.join('cli', 'plugins'), path.join('cli', 'plugins', 'marketplaces'),
+    path.join('cli', 'config.json'),
+  ]);
+  const ownership = previousMetadata.config_ownership || configOwnership(configFile, pluginRoot);
+  const configExisted = fs.existsSync(configFile);
+  const configBefore = configExisted ? fs.readFileSync(configFile, 'utf8') : null;
+  const nextConfig = registeredConfig(loadConfig(configFile), pluginRoot);
+  ensureDir(path.dirname(target));
+  const staging = fs.mkdtempSync(path.join(path.dirname(target), `.${PLUGIN_NAME}-staging-`));
+  const recovery = fs.existsSync(target)
+    ? fs.mkdtempSync(path.join(path.dirname(target), `.${PLUGIN_NAME}-recovery-`))
+    : null;
+  if (recovery) fs.cpSync(target, recovery, { recursive: true });
+  try {
+    const copied = buildStaging(repoRoot, staging, pluginRoot);
+    markManaged(staging, {
+      adapter: 'zcode', plugin: PLUGIN_NAME,
+      cleanup_absent: cleanupAbsent,
+      config_ownership: ownership,
+    });
+    publishManagedTrees([{ source: staging, target, label: 'ZCode marketplace' }]);
+    writeAtomic(configFile, `${JSON.stringify(nextConfig, null, 2)}\n`);
+    if (shouldRunHostCli(ctx)) {
+      const plugin = nativePlugin(ctx);
+      if (!plugin || plugin.enabled !== true || path.resolve(plugin.rootPath) !== path.resolve(pluginRoot)) {
+        throw new Error('ZCode did not activate the managed Ultra inline plugin');
+      }
+    }
+    if (recovery) removeTree(recovery);
+    return {
+      target,
+      marketplaceRoot: target,
+      marketplaceFile: resolveMarketplaceFile(ctx),
+      pluginRoot,
+      skillRoot: path.join(pluginRoot, 'skills'),
+      hookRoot: path.join(pluginRoot, 'hooks'),
+      configFile,
+      copied,
+    };
+  } catch (error) {
+    const rollback = [];
+    try {
+      if (configExisted) writeAtomic(configFile, configBefore);
+      else if (fs.existsSync(configFile)) fs.unlinkSync(configFile);
+    } catch (rollbackError) { rollback.push(rollbackError); }
+    try {
+      if (fs.existsSync(target)) removeTree(target);
+      if (recovery) fs.renameSync(recovery, target);
+    } catch (rollbackError) { rollback.push(rollbackError); }
+    if (fs.existsSync(staging)) removeTree(staging);
+    pruneCreatedEmpty(configRoot, cleanupAbsent);
+    if (rollback.length) throw new AggregateError([error, ...rollback], 'ZCode install and rollback failed');
+    throw error;
+  }
+}
+
+function doctor(ctx = {}) {
+  assertPluginScope(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const report = inspectPlugin({
+    adapter: 'zcode', repoRoot: resolveRepoRoot(ctx), pluginRoot,
+    skillRoot: path.join(pluginRoot, 'skills'), hookRoot: path.join(pluginRoot, 'hooks'),
+    manifestFile: path.join(pluginRoot, '.zcode-plugin', 'plugin.json'),
+  });
+  let marketplaceValid = false;
+  try {
+    const marketplace = JSON.parse(fs.readFileSync(resolveMarketplaceFile(ctx), 'utf8'));
+    marketplaceValid = marketplace?.name === PLUGIN_NAME
+      && Array.isArray(marketplace.plugins)
+      && marketplace.plugins.some((entry) => entry?.name === PLUGIN_NAME && entry?.source === './plugin');
+  } catch {}
+  report.checks.marketplace = { status: marketplaceValid ? 'pass' : 'fail' };
+  if (!marketplaceValid) report.issues.push({ code: 'ZCODE_MARKETPLACE_INVALID' });
+
+  let registered = false;
+  try {
+    const config = loadConfig(resolveConfigFile(ctx));
+    registered = config.plugins?.enabled !== false
+      && Array.isArray(config.plugins?.dirs)
+      && config.plugins.dirs.includes(pluginRoot);
+  } catch {}
+  report.checks.registration = { status: registered ? 'pass' : 'fail' };
+  if (!registered) report.issues.push({ code: 'ZCODE_PLUGIN_NOT_REGISTERED' });
+
+  if (shouldRunHostCli(ctx)) {
+    let discovered = false;
+    try {
+      const plugin = nativePlugin(ctx);
+      discovered = !!plugin && plugin.enabled === true
+        && path.resolve(plugin.rootPath) === path.resolve(pluginRoot)
+        && plugin.skillCount === 14;
+    } catch {}
+    report.checks.native_registry = { status: discovered ? 'pass' : 'fail' };
+    if (!discovered) report.issues.push({ code: 'ZCODE_NATIVE_DISCOVERY_FAILED' });
+  }
+  report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
+  return report;
+}
+
+function uninstall(ctx = {}) {
+  assertPluginScope(ctx);
+  const target = resolveMarketplaceRoot(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const configRoot = resolveTarget(ctx);
+  const metadata = managedMetadata(target) || {};
+  const ownership = metadata.config_ownership;
+  const cleanupAbsent = metadata.cleanup_absent || [];
+  if (fs.existsSync(target) && !ownership) {
+    throw new Error(`missing ZCode config ownership in ${target}`);
+  }
+  const configFile = resolveConfigFile(ctx);
+  const configBefore = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : null;
+  if (ownership) {
+    const next = unregisteredConfig(loadConfig(configFile), pluginRoot, ownership);
+    if (ownership.file_created && Object.keys(next).length === 0) fs.unlinkSync(configFile);
+    else writeAtomic(configFile, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  try {
+    const removed = removeManaged(target, 'ZCode marketplace');
+    const cleaned = pruneCreatedEmpty(configRoot, cleanupAbsent);
+    return { target, marketplaceRoot: target, pluginRoot, removed: { marketplace: removed }, cleaned };
+  } catch (error) {
+    if (configBefore !== null) writeAtomic(configFile, configBefore);
+    throw error;
+  }
+}
+
+module.exports = {
+  name: 'zcode',
+  PLUGIN_NAME,
+  INLINE_PLUGIN_ID,
+  buildHooksManifest,
+  resolveTarget,
+  resolveCliRoot,
+  resolveConfigFile,
+  resolveMarketplaceRoot,
+  resolveMarketplaceFile,
+  resolvePluginRoot,
+  install,
+  doctor,
+  uninstall,
+};

package/bin/delegate-worker.cjs

@@ -70,11 +70,24 @@ function parseJson(value) {
   try { return JSON.parse(text); } catch { return null; }
 }
 
+function parseFencedJson(value) {
+  if (typeof value !== 'string') return [];
+  const parsed = [];
+  const fences = /```(?:json)?\s*([\s\S]*?)\s*```/gi;
+  for (const match of value.matchAll(fences)) {
+    try { parsed.push(JSON.parse(match[1])); } catch {}
+  }
+  return parsed;
+}
+
 function collectResultCandidates(value, candidates, depth = 0) {
   if (depth > 12 || value === null || value === undefined) return;
   if (typeof value === 'string') {
     const parsed = parseJson(value);
     if (parsed !== null) collectResultCandidates(parsed, candidates, depth + 1);
+    for (const fenced of parseFencedJson(value)) {
+      collectResultCandidates(fenced, candidates, depth + 1);
+    }
     return;
   }
   if (Array.isArray(value)) {
@@ -93,6 +106,7 @@ function extractModelResult(spec) {
   for (const file of [spec.host_output, spec.stdout]) {
     if (!file || !fs.existsSync(file) || fs.statSync(file).size === 0) continue;
     const text = fs.readFileSync(file, 'utf8');
+    collectResultCandidates(text, candidates);
     const full = parseJson(text);
     if (full !== null) collectResultCandidates(full, candidates);
     for (const line of text.split('\n')) {
@@ -167,6 +181,12 @@ function mechanical(spec, exitCode, signal) {
   return {
     delegation_id: spec.delegation_id,
     host: spec.host,
+    transport_maturity: spec.transport_maturity ?? null,
+    transport_surface: spec.transport_surface ?? null,
+    // The explicit experimental acknowledgment travels to every terminal
+    // result — finished, failed, cancelled, or interrupted — so no result can
+    // imply an undocumented surface was silently launched.
+    ...(spec.experimental_ack === true ? { experimental_ack: true } : {}),
     instruction_digest: spec.instruction_digest,
     permission_digest: spec.permission_digest,
     output_schema_digest: spec.output_schema_digest,

package/bin/delegate.cjs

@@ -5,7 +5,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync, spawn } = require('node:child_process');
 
-const { hostProfile } = require('../adapters/_shared/host-profile.cjs');
+const { hostProfile, transportSurface } = require('../adapters/_shared/host-profile.cjs');
 const { writeAtomic } = require('../adapters/_shared/file-ops.cjs');
 
 const PERMISSION_SCHEMA = 'ultra-delegation-permission-v1';
@@ -21,28 +21,28 @@ const RESULT_JSON_SCHEMA = Object.freeze({
     'questions', 'residual_risks',
   ],
   properties: {
-    $schema: { const: RESULT_SCHEMA },
-    status: { enum: ['finished', 'blocked', 'failed'] },
-    summary: { type: 'string', minLength: 1 },
+    $schema: { type: 'string', const: RESULT_SCHEMA },
+    status: { type: 'string', enum: ['finished', 'blocked', 'failed'] },
+    summary: { type: 'string' },
     changed_files: {
-      type: 'array', uniqueItems: true, items: { type: 'string', minLength: 1 },
+      type: 'array', items: { type: 'string' },
     },
     checks: {
       type: 'array',
       items: {
         type: 'object',
         additionalProperties: false,
-        required: ['command', 'status'],
+        required: ['command', 'status', 'output_ref'],
         properties: {
-          command: { type: 'string', minLength: 1 },
-          status: { enum: ['passed', 'failed', 'not_run'] },
-          output_ref: { type: 'string', minLength: 1 },
+          command: { type: 'string' },
+          status: { type: 'string', enum: ['passed', 'failed', 'not_run'] },
+          output_ref: { type: 'string' },
         },
       },
     },
-    evidence: { type: 'array', items: { type: 'string', minLength: 1 } },
-    questions: { type: 'array', items: { type: 'string', minLength: 1 } },
-    residual_risks: { type: 'array', items: { type: 'string', minLength: 1 } },
+    evidence: { type: 'array', items: { type: 'string' } },
+    questions: { type: 'array', items: { type: 'string' } },
+    residual_risks: { type: 'array', items: { type: 'string' } },
   },
 });
 
@@ -115,8 +115,10 @@ function validateWorktree(worktree) {
 
 function readPermission(file, worktree) {
   let payload;
+  let source;
   try {
-    payload = JSON.parse(fs.readFileSync(file, 'utf8'));
+    source = fs.readFileSync(file, 'utf8');
+    payload = JSON.parse(source);
   } catch {
     throw new Error('permission must be valid JSON');
   }
@@ -167,24 +169,40 @@ function readPermission(file, worktree) {
   if (payload.external_effects.length !== 0) {
     throw new Error('permission external_effects must be empty; the primary host performs separately authorized effects');
   }
-  return { writableRoots, writableRootPaths };
+  return {
+    writableRoots,
+    writableRootPaths,
+    source,
+    digest: crypto.createHash('sha256').update(source).digest('hex'),
+  };
 }
 
-function delegatePrompt({ instruction, permission, worktree, readOnly }) {
+function delegatePrompt({
+  instructionSource, instructionDigest, permissionSource, permissionDigest,
+  worktree, readOnly,
+}) {
   return [
     'Execute one bounded Ultra Builder Pro delegation in the isolated Git worktree.',
-    `Read the immutable instruction file: ${instruction}`,
-    `Read the immutable permission file: ${permission}`,
+    'The launcher embedded the digest-bound packet below. Do not access packet paths outside the worktree.',
+    `Instruction SHA-256: ${instructionDigest}`,
+    '--- instruction.md ---',
+    instructionSource.trimEnd(),
+    '--- end instruction.md ---',
+    `Permission SHA-256: ${permissionDigest}`,
+    '--- permission.json ---',
+    permissionSource.trimEnd(),
+    '--- end permission.json ---',
     `Use this worktree as the only filesystem boundary: ${worktree}`,
     readOnly
       ? 'This is read-only delegation. Do not create, modify, or delete any project file.'
       : 'Modify only paths covered by permission.writable_roots.',
     'Do not perform external effects, edit the primary checkout, or change Ultra task authority.',
+    'Batch independent reads in the earliest tool turn. Do not emit a preliminary result, and reserve a final turn for the one terminal JSON response.',
     `Return exactly one JSON object as the final response using $schema ${RESULT_SCHEMA}.`,
-    'The exact fields are status, summary, changed_files, checks, evidence, questions, and residual_risks.',
+    'The exact fields are $schema, status, summary, changed_files, checks, evidence, questions, and residual_risks.',
     'status is finished, blocked, or failed. blocked requires at least one question.',
     'changed_files must exactly list every repository-relative path changed in the worktree.',
-    'checks items use command, status (passed, failed, or not_run), and optional output_ref.',
+    'checks items use command, status (passed, failed, or not_run), and output_ref. Use a short evidence reference when no file exists.',
     'Do not write the receipt yourself. The launcher validates structured output, process exit, permissions, and the actual Git diff before publication.',
   ].join('\n');
 }
@@ -193,6 +211,10 @@ function selectedBinary(runtime, fallback) {
   return process.env[`UBP_DELEGATE_${runtime.toUpperCase()}_BIN`] || fallback;
 }
 
+function selectedModel(runtime, explicit) {
+  return explicit || process.env[`UBP_DELEGATE_${runtime.toUpperCase()}_MODEL`] || null;
+}
+
 function parsePairs(argv, allowed) {
   const values = {};
   for (let index = 0; index < argv.length; index += 2) {
@@ -208,8 +230,12 @@ function parsePairs(argv, allowed) {
 }
 
 function parseRun(argv) {
-  const values = parsePairs(argv, new Set([
-    '--to', '--instruction', '--permission', '--worktree', '--timeout',
+  // --ack-experimental is the one valueless flag: launching an experimental
+  // transport must be a visible choice, never a silent default.
+  const ackExperimental = argv.includes('--ack-experimental');
+  const pairs = argv.filter((arg) => arg !== '--ack-experimental');
+  const values = parsePairs(pairs, new Set([
+    '--to', '--instruction', '--permission', '--worktree', '--timeout', '--model',
   ]));
   for (const key of ['--to', '--instruction', '--permission', '--worktree']) {
     if (!values[key]) throw new Error(`delegate run requires ${key}`);
@@ -221,7 +247,9 @@ function parseRun(argv) {
   return {
     to: values['--to'], instruction: values['--instruction'],
     permission: values['--permission'], worktree: values['--worktree'],
+    model: values['--model'] || null,
     timeoutMs: Math.ceil(timeout * 1000),
+    ackExperimental,
   };
 }
 
@@ -238,6 +266,28 @@ function run(argv, { projectRoot = process.cwd() } = {}) {
   const args = parseRun(argv);
   projectRoot = fs.realpathSync(projectRoot);
   const profile = hostProfile(args.to);
+  if (args.model && !profile.supportsModelSelection) {
+    throw new Error(`delegate --model is not supported by host ${args.to}`);
+  }
+  const model = profile.supportsModelSelection ? selectedModel(args.to, args.model) : null;
+  const binary = selectedBinary(args.to, profile.binary);
+  const transportMaturity = profile.transportMaturity;
+  const transportSurfaceNote = transportSurface(args.to, binary);
+  if (transportMaturity === 'experimental' && !args.ackExperimental) {
+    throw new Error(
+      `delegate --to ${args.to} would launch ${transportSurfaceNote}. `
+      + 'This transport is experimental (verified-local only; the provider publishes no '
+      + 'stability contract), and it is not the documented ZCode Desktop interactive '
+      + 'surface. Acknowledge explicitly with --ack-experimental to proceed, or pick a '
+      + 'documented transport.',
+    );
+  }
+  if (transportMaturity === 'experimental') {
+    process.stderr.write(
+      `ultra-delegate: warning: host '${args.to}' runs ${transportSurfaceNote}; `
+      + `recovery: ubp delegate cancel --delegation <dir>\n`,
+    );
+  }
   const instruction = projectPath(projectRoot, args.instruction, 'instruction');
   const permission = projectPath(projectRoot, args.permission, 'permission');
   const worktree = projectPath(projectRoot, args.worktree, 'worktree', { directory: true });
@@ -248,6 +298,7 @@ function run(argv, { projectRoot = process.cwd() } = {}) {
   }
   const baseHead = validateWorktree(worktree);
   const permissionContract = readPermission(permission, worktree);
+  const instructionSource = fs.readFileSync(instruction, 'utf8');
   const delegationRoot = path.dirname(instruction);
   const delegationId = path.basename(delegationRoot);
   const result = path.join(delegationRoot, 'result.json');
@@ -272,8 +323,8 @@ function run(argv, { projectRoot = process.cwd() } = {}) {
     throw error;
   }
   const startedAt = new Date().toISOString();
-  const instructionDigest = sha256(instruction);
-  const permissionDigest = sha256(permission);
+  const instructionDigest = crypto.createHash('sha256').update(instructionSource).digest('hex');
+  const permissionDigest = permissionContract.digest;
   try {
     fs.writeFileSync(lockFd, `${JSON.stringify({ pid: process.pid, started_at: startedAt })}\n`);
     fs.closeSync(lockFd);
@@ -287,15 +338,25 @@ function run(argv, { projectRoot = process.cwd() } = {}) {
       schemaFile: outputSchema,
       schemaJson: JSON.stringify(RESULT_JSON_SCHEMA),
       hostOutput,
+      model,
     };
     const prompt = delegatePrompt({
-      instruction, permission, worktree, readOnly: profileOptions.readOnly,
+      instructionSource,
+      instructionDigest,
+      permissionSource: permissionContract.source,
+      permissionDigest,
+      worktree,
+      readOnly: profileOptions.readOnly,
     });
     const workerSpec = {
       $schema: 'ultra-delegation-worker-spec-v1',
       delegation_id: delegationId,
       host: args.to,
-      command: selectedBinary(args.to, profile.binary),
+      model,
+      command: binary,
+      transport_maturity: transportMaturity,
+      transport_surface: transportSurfaceNote,
+      experimental_ack: transportMaturity === 'experimental' ? args.ackExperimental : undefined,
       args: profile.delegateArgv(prompt, worktree, profileOptions),
       cwd: worktree,
       instruction,
@@ -341,6 +402,10 @@ function run(argv, { projectRoot = process.cwd() } = {}) {
       status: 'started',
       delegation_id: delegationId,
       host: args.to,
+      model,
+      transport_maturity: transportMaturity,
+      transport_surface: transportSurfaceNote,
+      ...(transportMaturity === 'experimental' ? { experimental_ack: args.ackExperimental } : {}),
       worker_pid: worker.pid,
       instruction_digest: instructionDigest,
       permission_digest: permissionDigest,
@@ -415,6 +480,10 @@ function failureFromSpec(spec, failureType, summary) {
     failure_type: failureType,
     delegation_id: spec.delegation_id,
     host: spec.host,
+    transport_maturity: spec.transport_maturity ?? null,
+    transport_surface: spec.transport_surface ?? null,
+    // Terminal recovery results carry the same transport truth as live ones.
+    ...(spec.experimental_ack === true ? { experimental_ack: true } : {}),
     instruction_digest: spec.instruction_digest,
     permission_digest: spec.permission_digest,
     output_schema_digest: spec.output_schema_digest,