@dtlabs/ai-toolkit 0.12.0 → 0.14.0

package/bin/cli.js

@@ -4,6 +4,7 @@ const path = require('path');
 const crypto = require('crypto');
 const readline = require('readline');
 const executionLedger = require('../lib/execution-ledger');
+const agentRegistry   = require('../lib/agent-registry');
 const packageRoot = path.join(__dirname, '..');
 
 // ── colors ────────────────────────────────────────────────────────────────────
@@ -46,6 +47,10 @@ function fileHash(filePath) {
   return crypto.createHash('md5').update(fs.readFileSync(filePath)).digest('hex');
 }
 
+function computeFileSha256(filePath) {
+  return 'sha256:' + crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
 function readJsonSafe(filePath) {
   try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
 }
@@ -289,7 +294,7 @@ function moveToTrash(destRoot, relativePath) {
   }
 }
 
-function writeManifest(destRoot, fileList, installationMode) {
+function writeManifest(destRoot, fileList, installationMode, fileHashes) {
   const manifestPath = path.join(destRoot, '.claude', MANIFEST_FILE);
   const trashDir = path.join(destRoot, '.claude', '.ai-toolkit-trash');
   const filtered = fileList.filter(rel => {
@@ -302,6 +307,18 @@ function writeManifest(destRoot, fileList, installationMode) {
     installationMode: installationMode,
     files: filtered.map(f => f.replace(/\\/g, '/')),
   };
+  if (fileHashes !== undefined && fileHashes !== null) {
+    // Enforce set(files) == set(keys(fileHashes)) invariant (AC-40).
+    const filesSet  = new Set(manifest.files);
+    const hashesSet = new Set(Object.keys(fileHashes).map(k => k.replace(/\\/g, '/')));
+    if (filesSet.size !== hashesSet.size || [...filesSet].some(f => !hashesSet.has(f))) {
+      throw new Error(
+        'writeManifest: set(files) ≠ set(keys(fileHashes)). ' +
+        'Every installed file must have exactly one hash entry.'
+      );
+    }
+    manifest.fileHashes = fileHashes;
+  }
   try {
     ensureDir(manifestPath);
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
@@ -415,7 +432,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
 
   if (modified.length === 0) {
     console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
-    writeManifest(destRoot, newFileSet, installationMode);
+    writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
     return;
   }
 
@@ -426,7 +443,7 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
       fs.copyFileSync(e.src, e.dest);
       console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
     }
-    writeManifest(destRoot, newFileSet, installationMode);
+    writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
     return;
   }
 
@@ -455,7 +472,20 @@ async function runInstall(label, mappings, force, destRoot, dryRun = false, inst
     `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
   );
 
-  writeManifest(destRoot, newFileSet, installationMode);
+  writeManifest(destRoot, newFileSet, installationMode, _buildFileHashes(destRoot, newFileSet));
+}
+
+// Compute SHA-256 for every relative path in relPaths under destRoot.
+// Files that cannot be read are silently skipped (they won't appear in fileHashes).
+function _buildFileHashes(destRoot, relPaths) {
+  const fileHashes = {};
+  for (const relPath of relPaths) {
+    const absPath = path.join(destRoot, relPath);
+    try {
+      fileHashes[relPath] = computeFileSha256(absPath);
+    } catch (_) { /* ignore unreadable files */ }
+  }
+  return fileHashes;
 }
 
 // ── subagent spawn-depth check (verify & advise only — never write) ────────────
@@ -1486,6 +1516,157 @@ function runDoctorResolution(options) {
   L('');
 }
 
+// ── runDoctorAgents ───────────────────────────────────────────────────────────
+
+// US-08-TASK-BE-01 (FTR-017):
+// Read-only diagnostic report for all registered toolkit agents.
+// Never modifies, creates, or deletes any file (AC-14).
+//
+// Parameters (via options object):
+//   projectDir (string): target project directory (defaults to process.cwd())
+//   home       (string): override for os.homedir() to enable test isolation
+//
+// Output: human-readable report on stdout; always exits 0.
+function runDoctorAgents(options) {
+  const os = require('os');
+
+  const opts             = options || {};
+  const effectiveHome    = opts.home       !== undefined ? path.resolve(opts.home)       : os.homedir();
+  const effectiveProject = opts.projectDir !== undefined ? path.resolve(opts.projectDir) : process.cwd();
+
+  const records = agentRegistry.listRegisteredAgents(effectiveProject, effectiveHome);
+
+  const STATUS_ICON = {
+    'verified':          '[OK]',
+    'conflict':          '[!!]',
+    'hash-unverifiable': '[??]',
+    'unobservable':      '[??]',
+    'not-installed':     '[--]',
+    'not-applicable':    '[NA]',
+  };
+
+  const lines = [];
+  lines.push('');
+  lines.push('ai-toolkit doctor agents');
+  lines.push('─'.repeat(72));
+  lines.push('');
+
+  const statusCounts      = {};
+  const unobservable      = [];
+  const conflicts         = [];
+  const hashUnverifiable  = [];
+
+  for (const rec of records) {
+    const status = rec.status;
+    statusCounts[status] = (statusCounts[status] || 0) + 1;
+
+    const icon = STATUS_ICON[status] || '[??]';
+    lines.push('  ' + icon + ' ' + rec.agentId);
+    lines.push('      native:  ' + rec.nativeName);
+    lines.push('      scope:   ' + (rec.scope          || '—'));
+    lines.push('      version: ' + (rec.toolkitVersion || '—'));
+    if (rec.path)            lines.push('      path:    ' + rec.path);
+    if (rec.sha256)          lines.push('      sha256:  ' + rec.sha256);
+    if (rec.integrityDetail) lines.push('      detail:  ' + rec.integrityDetail);
+    if (rec.error)           lines.push('      error:   ' + rec.error);
+    if (rec.deprecated)      lines.push('      DEPRECATED — target: ' + (rec.deprecationTarget || '(unspecified)'));
+    lines.push('');
+
+    if (status === 'unobservable')      unobservable.push(rec);
+    else if (status === 'conflict')     conflicts.push(rec);
+    else if (status === 'hash-unverifiable') hashUnverifiable.push(rec);
+  }
+
+  // ── Summary ──────────────────────────────────────────────────────────────────
+  lines.push('─'.repeat(72));
+  lines.push('Summary:');
+  for (const [status, count] of Object.entries(statusCounts)) {
+    lines.push('  ' + (STATUS_ICON[status] || '[??]') + ' ' + status + ': ' + count);
+  }
+  lines.push('');
+
+  // ── Unobservable WARNING (AC-33) ──────────────────────────────────────────────
+  if (unobservable.length > 0) {
+    lines.push('WARNING: unobservable scope(s) detected.');
+    lines.push('  The following agents exist in plugin or session scopes that cannot be');
+    lines.push('  enumerated from the filesystem. Dispatch is NOT blocked. The mandatory');
+    lines.push('  mitigation is gaia-* namespacing — a uniquely prefixed native name is');
+    lines.push('  extremely unlikely to collide with a plugin or session agent.');
+    for (const rec of unobservable) {
+      lines.push('    - ' + rec.agentId + ' (' + rec.nativeName + ')');
+    }
+    lines.push('');
+  }
+
+  // ── hash-unverifiable remediation ────────────────────────────────────────────
+  if (hashUnverifiable.length > 0) {
+    lines.push('Remediation for hash-unverifiable agent(s):');
+    lines.push('  Reinstall or upgrade the toolkit runtime to generate integrity hashes.');
+    lines.push('  Command: ai-toolkit --local <project-dir> --force');
+    lines.push('');
+  }
+
+  // ── Conflict detail ───────────────────────────────────────────────────────────
+  if (conflicts.length > 0) {
+    lines.push('Conflicts:');
+    for (const rec of conflicts) {
+      const detail = rec.integrityDetail || rec.error || 'ambiguous installation';
+      lines.push('  ' + rec.agentId + ': ' + detail);
+      if (rec.path) lines.push('    path: ' + rec.path);
+    }
+    lines.push('');
+  }
+
+  // ── Foreign observable agents (AC-09) ────────────────────────────────────────
+  const catalogNativeNames = new Set(agentRegistry.CATALOG.map(function (e) { return e.nativeNames.claude; }));
+  const agentsDirs = [];
+  var projectAgentsDir = path.join(effectiveProject, '.claude', 'agents');
+  var globalAgentsDir  = path.join(effectiveHome,    '.claude', 'agents');
+  if (fs.existsSync(projectAgentsDir)) agentsDirs.push({ dir: projectAgentsDir, scope: 'project' });
+  if (fs.existsSync(globalAgentsDir))  agentsDirs.push({ dir: globalAgentsDir,  scope: 'global'  });
+
+  var foreignAgents = [];
+  for (var di = 0; di < agentsDirs.length; di++) {
+    var entry = agentsDirs[di];
+    try {
+      var files = fs.readdirSync(entry.dir).filter(function (f) { return f.endsWith('.md'); });
+      for (var fi = 0; fi < files.length; fi++) {
+        var nativeName = files[fi].replace(/\.md$/, '');
+        if (!catalogNativeNames.has(nativeName)) {
+          foreignAgents.push({ nativeName: nativeName, path: path.join(entry.dir, files[fi]), scope: entry.scope });
+        }
+      }
+    } catch (_) { /* ignore unreadable dirs */ }
+  }
+
+  if (foreignAgents.length > 0) {
+    lines.push('Foreign observable agents (not in toolkit catalog):');
+    lines.push('  These agents are present in an observable scope but are NOT registered');
+    lines.push('  toolkit agents. They do NOT block dispatch. Review and remove if stale.');
+    for (var fai = 0; fai < foreignAgents.length; fai++) {
+      var fa = foreignAgents[fai];
+      lines.push('  [foreign/' + fa.scope + '] ' + fa.nativeName);
+      lines.push('    path: ' + fa.path);
+    }
+    lines.push('');
+  }
+
+  // ── Deprecated / legacy agents ───────────────────────────────────────────────
+  var deprecated = records.filter(function (r) { return r.deprecated; });
+  if (deprecated.length > 0) {
+    lines.push('Deprecated agents (Phase A legacy names):');
+    for (var dpi = 0; dpi < deprecated.length; dpi++) {
+      var drec = deprecated[dpi];
+      lines.push('  ' + drec.agentId + ' (' + drec.nativeName + ')');
+      if (drec.deprecationTarget) lines.push('    rename target: ' + drec.deprecationTarget);
+    }
+    lines.push('  Remediation: reinstall the toolkit after Phase B renames are complete.');
+    lines.push('');
+  }
+
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
 // ── validatePurityGuard ───────────────────────────────────────────────────────
 
 // US-05-TASK-BE-03 (FTR-015):
@@ -1554,7 +1735,7 @@ function runValidatePurity(sourceDir) {
 // projects. Keyed by category name; value is a Set of item names to skip.
 // See AGENTS.md hard constraints.
 const TOOLKIT_INTERNAL_ASSETS = {
-  agents: new Set(['install-toolkit.md']),
+  agents: new Set(['gaia-install-toolkit.md']),
   skills: new Set(['install-toolkit']),
 };
 
@@ -1695,7 +1876,9 @@ async function main() {
     return;
   }
 
-  if (argv[0] === '--local') {
+  if (argv[0] === 'workflow') {
+    await require('../lib/workflow-runner').main(argv.slice(1));
+  } else if (argv[0] === '--local') {
     await installLocal(argv[1] || '.', force, dryRun);
   } else if (argv[0] === '--global') {
     const homeIdx = argv.indexOf('--home');
@@ -1764,6 +1947,14 @@ async function main() {
     const home       = homeIdx    !== -1 ? remaining[homeIdx    + 1] : undefined;
     runDoctorResolution({ projectDir, home });
     process.exit(0);
+  } else if (argv[0] === 'doctor' && argv[1] === 'agents') {
+    const remaining  = argv.slice(2);
+    const projectIdx = remaining.indexOf('--project');
+    const homeIdx    = remaining.indexOf('--home');
+    const projectDir = projectIdx !== -1 ? remaining[projectIdx + 1] : process.cwd();
+    const home       = homeIdx    !== -1 ? remaining[homeIdx    + 1] : undefined;
+    runDoctorAgents({ projectDir, home });
+    process.exit(0);
   } else if (argv[0] === 'validate-purity') {
     runValidatePurity(argv[1]);
   } else if (argv[0] === 'resolve-asset') {
@@ -1832,7 +2023,7 @@ async function main() {
         process.stderr.write(`Error spawning script: ${result.error.message}\n`);
         process.exit(1);
       }
-      process.exit(result.status || 0);
+      process.exit(Number.isInteger(result.status) ? result.status : 1);
     } catch (err) {
       process.stderr.write(err.message + '\n');
       process.exit(1);
@@ -1918,8 +2109,12 @@ async function main() {
       process.stderr.write(err.message + '\n');
       process.exit(1);
     }
+  } else if (argv[0] === 'agents') {
+    await handleAgentsCommand(argv.slice(1));
   } else if (argv[0] === 'ledger') {
     handleLedgerCommand(argv.slice(1));
+  } else if (argv[0] === 'executor') {
+    await handleExecutorCommand(argv.slice(1));
   } else if (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
     await installLocal(argv[0], force, dryRun);
   } else {
@@ -1938,7 +2133,7 @@ function shellQuotePosix(arg) {
 
 function parseLedgerArgs(argv) {
   const PREFIX_RE = /^[A-Za-z]+-\d+$/;
-  const result = { prefix: undefined, agent: undefined, attempt: 1, tokens: undefined, dir: undefined, phase: undefined, model: undefined, error: undefined };
+  const result = { prefix: undefined, agent: undefined, attempt: 1, tokens: undefined, dir: undefined, phase: undefined, model: undefined, error: undefined, metadata: undefined };
 
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
@@ -1996,6 +2191,36 @@ function parseLedgerArgs(argv) {
         throw new Error('parseLedgerArgs: --error must be a non-empty string');
       }
       result.error = val;
+    } else if (flag === '--metadata-json') {
+      i++;
+      if (!val) {
+        throw new Error('parseLedgerArgs: --metadata-json must be a non-empty JSON string');
+      }
+      try {
+        result.metadata = Object.assign(result.metadata || {}, JSON.parse(val));
+      } catch (_) {
+        throw new Error('parseLedgerArgs: --metadata-json is not valid JSON: ' + val);
+      }
+    } else if (flag === '--agent-id') {
+      i++;
+      if (!val) throw new Error('parseLedgerArgs: --agent-id must be a non-empty string');
+      result.metadata = Object.assign(result.metadata || {}, { agentId: val });
+    } else if (flag === '--native-name') {
+      i++;
+      if (!val) throw new Error('parseLedgerArgs: --native-name must be a non-empty string');
+      result.metadata = Object.assign(result.metadata || {}, { nativeAgentName: val });
+    } else if (flag === '--toolkit-version') {
+      i++;
+      if (!val) throw new Error('parseLedgerArgs: --toolkit-version must be a non-empty string');
+      result.metadata = Object.assign(result.metadata || {}, { toolkitVersion: val });
+    } else if (flag === '--scope') {
+      i++;
+      if (!val) throw new Error('parseLedgerArgs: --scope must be a non-empty string');
+      result.metadata = Object.assign(result.metadata || {}, { resolutionScope: val });
+    } else if (flag === '--hash') {
+      i++;
+      if (!val) throw new Error('parseLedgerArgs: --hash must be a non-empty string');
+      result.metadata = Object.assign(result.metadata || {}, { definitionHash: val });
     }
   }
 
@@ -2040,7 +2265,7 @@ function handleLedgerCommand(argv) {
 
   if (subcommand === 'open') {
     try {
-      const result = executionLedger.open(args.dir, args.prefix, args.agent, args.phase, args.model, args.attempt);
+      const result = executionLedger.open(args.dir, args.prefix, args.agent, args.phase, args.model, args.attempt, args.metadata);
       process.stdout.write(sortedJson(result) + '\n');
       process.exitCode = 0;
     } catch (err) {
@@ -2083,6 +2308,615 @@ function handleLedgerCommand(argv) {
   }
 }
 
+// ── agents dispatcher ─────────────────────────────────────────────────────────
+// Routes `ai-toolkit agents <subcommand> [flags]` to the appropriate
+// registry function.  All domain logic lives in lib/agent-registry.js;
+// this function only parses CLI flags and invokes registry functions —
+// it is NOT a second registry.
+//
+// Subcommands:
+//   list      --project <dir> [--format json] [--home <dir>]
+//               → calls listRegisteredAgents(); enumerates ONLY catalog toolkit
+//                 agents (never foreign/plugin); exits 0 on success.
+//   resolve   --project <dir> --id <canonicalId> [--home <dir>] [--require-verified]
+//               → without --require-verified: diagnostic mode.
+//                 Exit-code contract:
+//                   exit 0 — verified | hash-unverifiable | hash-mismatch
+//                   exit 1 — not-found | conflict | manifest-missing |
+//                            not-installed | not-applicable
+//               → with --require-verified: operational mode.
+//                 Exit-code contract:
+//                   exit 0 — verified ONLY (v0.13.0+ manifest with matching hash)
+//                   exit 1 — any other status; structured JSON error written to stderr
+//                 A v0.12.0 manifest (no fileHashes) is a HARD STOP under --require-verified.
+//   preflight --project <dir> --pipeline <name> [--home <dir>]
+//               → verifies every agent in the named pipeline using --require-verified semantics.
+//                 Required agent set is derived from CATALOG.allowedPipelines.
+//                 Exit-code contract:
+//                   exit 0 — all agents verified; JSON summary on stdout
+//                   exit 1 — any agent unverified or pipeline unknown; JSON error on stderr
+async function handleAgentsCommand(argv) {
+  const os = require('os');
+  const subcommand = argv[0];
+  const remaining  = argv.slice(1);
+
+  let projectDir      = null;
+  let home            = undefined;
+  let format          = 'json';
+  let agentId         = null;
+  let requireVerified = false;
+  let pipeline        = null;
+
+  for (let i = 0; i < remaining.length; i++) {
+    if      (remaining[i] === '--project'          && remaining[i + 1]) { projectDir      = remaining[++i]; }
+    else if (remaining[i] === '--home'             && remaining[i + 1]) { home            = remaining[++i]; }
+    else if (remaining[i] === '--format'           && remaining[i + 1]) { format          = remaining[++i]; }
+    else if (remaining[i] === '--id'               && remaining[i + 1]) { agentId         = remaining[++i]; }
+    else if (remaining[i] === '--pipeline'         && remaining[i + 1]) { pipeline        = remaining[++i]; }
+    else if (remaining[i] === '--require-verified')                      { requireVerified = true; }
+  }
+
+  if (subcommand === 'list') {
+    if (!projectDir) {
+      process.stderr.write('Error: agents list requires --project <dir>\n');
+      process.exitCode = 1;
+      return;
+    }
+    const effectiveHome    = home !== undefined ? path.resolve(home) : os.homedir();
+    const effectiveProject = path.resolve(projectDir);
+    const records = agentRegistry.listRegisteredAgents(effectiveProject, effectiveHome);
+    if (format === 'json') {
+      process.stdout.write(JSON.stringify(records, null, 2) + '\n');
+    } else {
+      for (const r of records) {
+        process.stdout.write(r.agentId + '\t' + r.nativeName + '\t' + r.status + '\n');
+      }
+    }
+    process.exitCode = 0;
+
+  } else if (subcommand === 'resolve') {
+    if (!projectDir) {
+      process.stderr.write('Error: agents resolve requires --project <dir>\n');
+      process.exitCode = 1;
+      return;
+    }
+    if (!agentId) {
+      process.stderr.write('Error: agents resolve requires --id <canonicalId>\n');
+      process.exitCode = 1;
+      return;
+    }
+    const effectiveHome    = home !== undefined ? path.resolve(home) : os.homedir();
+    const effectiveProject = path.resolve(projectDir);
+    let record;
+    try {
+      record = await agentRegistry.resolveAgent({
+        projectDir:      effectiveProject,
+        agentId:         agentId,
+        homeDir:         effectiveHome,
+        requireVerified: requireVerified,
+      });
+    } catch (err) {
+      // requireVerified=true throws RESOLUTION_FAILED for non-verified agents;
+      // the thrown error carries err.record with the full resolution record.
+      const errorRecord = err.record
+        ? Object.assign({}, err.record, { code: err.code })
+        : { agentId: agentId, status: 'resolution-failed', error: err.message, code: err.code || 'UNKNOWN' };
+      process.stderr.write(JSON.stringify(errorRecord, null, 2) + '\n');
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(JSON.stringify(record, null, 2) + '\n');
+    if (requireVerified) {
+      // Operational mode: exit 0 only for verified (non-verified would have thrown above)
+      process.exitCode = record.status === 'verified' ? 0 : 1;
+    } else {
+      // Diagnostic mode: exit 0 for agent present in any integrity state
+      const exitZeroStatuses = new Set(['verified', 'hash-unverifiable', 'hash-mismatch']);
+      process.exitCode = exitZeroStatuses.has(record.status) ? 0 : 1;
+    }
+
+  } else if (subcommand === 'preflight') {
+    if (!projectDir) {
+      process.stderr.write('Error: agents preflight requires --project <dir>\n');
+      process.exitCode = 1;
+      return;
+    }
+    if (!pipeline) {
+      process.stderr.write('Error: agents preflight requires --pipeline <name>\n');
+      process.exitCode = 1;
+      return;
+    }
+    const effectiveHome    = home !== undefined ? path.resolve(home) : os.homedir();
+    const effectiveProject = path.resolve(projectDir);
+
+    // Derive the required agent set from the CATALOG's allowedPipelines field.
+    const pipelineAgents = agentRegistry.CATALOG.filter(function (e) {
+      return Array.isArray(e.allowedPipelines) && e.allowedPipelines.indexOf(pipeline) !== -1;
+    });
+    if (pipelineAgents.length === 0) {
+      process.stderr.write(
+        JSON.stringify({ status: 'preflight-failed', error: 'Unknown pipeline: ' + pipeline }, null, 2) + '\n'
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    const results    = [];
+    let   allPassed  = true;
+    for (let i = 0; i < pipelineAgents.length; i++) {
+      const entry = pipelineAgents[i];
+      try {
+        const rec = await agentRegistry.resolveAgent({
+          projectDir:      effectiveProject,
+          agentId:         entry.agentId,
+          homeDir:         effectiveHome,
+          requireVerified: true,
+        });
+        results.push({ agentId: rec.agentId, status: rec.status });
+      } catch (err) {
+        allPassed = false;
+        const errRec = err.record
+          ? Object.assign({}, err.record, { code: err.code })
+          : { agentId: entry.agentId, status: 'resolution-failed', error: err.message, code: err.code || 'RESOLUTION_FAILED' };
+        results.push(errRec);
+      }
+    }
+
+    if (allPassed) {
+      process.stdout.write(
+        JSON.stringify({ status: 'preflight-ok', pipeline: pipeline, agents: results }, null, 2) + '\n'
+      );
+      process.exitCode = 0;
+    } else {
+      process.stderr.write(
+        JSON.stringify({ status: 'preflight-failed', pipeline: pipeline, agents: results }, null, 2) + '\n'
+      );
+      process.exitCode = 1;
+    }
+
+  } else if (subcommand === 'cleanup') {
+    // Reject any mutating flags up-front (AC-15).
+    const hasDelete = remaining.indexOf('--delete') !== -1;
+    const hasForce  = remaining.indexOf('--force')  !== -1;
+    if (hasDelete || hasForce) {
+      process.stderr.write(
+        'Error: agents cleanup does not support mutating flags (--delete, --force) in this version.\n' +
+        '       Only --dry-run is supported; no files are ever modified or deleted.\n'
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!projectDir) {
+      process.stderr.write('Error: agents cleanup requires --project <dir>\n');
+      process.exitCode = 1;
+      return;
+    }
+    const effectiveHome    = home !== undefined ? path.resolve(home) : os.homedir();
+    const effectiveProject = path.resolve(projectDir);
+
+    // Locate the active manifest (project-scoped takes precedence over global).
+    const projectManifestPath = path.join(effectiveProject, '.claude', MANIFEST_FILE);
+    const globalManifestPath  = path.join(effectiveHome,    '.claude', MANIFEST_FILE);
+
+    let installRoot    = null;
+    let manifestData   = null;
+
+    if (fs.existsSync(projectManifestPath)) {
+      installRoot  = effectiveProject;
+      manifestData = readJsonSafe(projectManifestPath);
+    } else if (fs.existsSync(globalManifestPath)) {
+      installRoot  = effectiveHome;
+      manifestData = readJsonSafe(globalManifestPath);
+    }
+
+    if (!installRoot || !manifestData || !Array.isArray(manifestData.files)) {
+      process.stdout.write(
+        JSON.stringify({ status: 'no-manifest', candidates: [], missing: [] }, null, 2) + '\n'
+      );
+      process.exitCode = 0;
+      return;
+    }
+
+    // Build the set of absolute paths that the current payload would install
+    // into the same install root.  Anything NOT in this set is a potential orphan.
+    // buildExpectedPayload takes the .claude dir (same convention as the installer).
+    const expectedPayload = buildExpectedPayload(path.join(installRoot, '.claude'));
+
+    const candidates = [];
+    const missing    = [];
+
+    for (const relPath of manifestData.files) {
+      if (typeof relPath !== 'string') continue;
+      const absPath = path.resolve(installRoot, relPath);
+
+      // If still in the current payload → not a cleanup candidate.
+      if (expectedPayload.has(absPath)) continue;
+
+      // Not in current payload: check disk state.
+      if (fs.existsSync(absPath)) {
+        candidates.push({ path: relPath, absPath: absPath, status: 'candidate' });
+      } else {
+        missing.push({ path: relPath, absPath: absPath, status: 'missing' });
+      }
+    }
+
+    const output = {
+      status:     'dry-run',
+      installRoot: installRoot,
+      candidates: candidates.map(function (c) { return { path: c.path, status: c.status }; }),
+      missing:    missing.map(function (m)    { return { path: m.path, status: m.status }; }),
+    };
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    process.exitCode = 0;
+
+  } else {
+    process.stderr.write(
+      'Error: unknown agents subcommand: ' + (subcommand || '(none)') + '\n'
+    );
+    process.exitCode = 1;
+  }
+}
+
+// ── executor CLI git-context helpers ─────────────────────────────────────────
+// US-09-TASK-INFRA-01 (FTR-018): lib/task-executor/index.js's execute()/stop()
+// take only `project` and derive commonDir/executionRoot themselves via their
+// own internal _resolveCommonGitDir/_currentBranchRef helpers — but
+// reconcile()/resume()/replan() take `executionRoot`/`projectDir`/`taskRef` as
+// SEPARATE, already-derived arguments instead. Neither internal helper is
+// exported from that module (module.exports there is deliberately narrow —
+// see its own export list), and this task's brief is explicit: do not modify
+// lib/task-executor/index.js. These two helpers duplicate that exact same
+// git-command technique (same argv, same error codes: GIT_SPAWN_FAILED,
+// GIT_REF_RESOLUTION_FAILED, EXECUTE_VALIDATION_ERROR for a detached HEAD) so
+// the CLI can compute the values reconcile/resume/replan need from the single
+// --project flag the Tech-Spec's CLI contract actually exposes for them.
+function _executorResolveCommonGitDir(projectDir) {
+  const { spawnSync } = require('child_process');
+  const res = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd: projectDir, shell: false, encoding: 'utf8', windowsHide: true,
+  });
+  if (res.error || res.status !== 0) {
+    const err = new Error(
+      'executor: failed to resolve the common Git directory for "' + projectDir + '": ' +
+        (res.error ? res.error.message : (res.stderr || '').trim())
+    );
+    err.code = 'GIT_SPAWN_FAILED';
+    throw err;
+  }
+  return path.resolve(projectDir, res.stdout.trim());
+}
+
+function _executorExecutionRoot(projectDir) {
+  return path.join(_executorResolveCommonGitDir(projectDir), 'ai-toolkit', 'execution');
+}
+
+function _executorCurrentBranchRef(projectDir) {
+  const { spawnSync } = require('child_process');
+  const res = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: projectDir, shell: false, encoding: 'utf8', windowsHide: true,
+  });
+  if (res.error || res.status !== 0) {
+    const err = new Error(
+      'executor: failed to resolve the current branch for "' + projectDir + '": ' +
+        (res.error ? res.error.message : (res.stderr || '').trim())
+    );
+    err.code = 'GIT_REF_RESOLUTION_FAILED';
+    throw err;
+  }
+  const name = res.stdout.trim();
+  if (name === 'HEAD') {
+    const err = new Error(
+      'executor: "' + projectDir + '" has a detached HEAD — a task ref cannot be derived automatically'
+    );
+    err.code = 'EXECUTE_VALIDATION_ERROR';
+    throw err;
+  }
+  return name;
+}
+
+// ── executor exit-code mapping ───────────────────────────────────────────────
+// FTR-018-Tech-Spec.md section 10 defines a FIXED 9-value exit-code enum for
+// the executor CLI (0 success; 1 unexpected I/O; 2 invalid config/input;
+// 3 ownership/live worker conflict; 4 evidence/plan/approval mismatch;
+// 5 worker/verification/review failure; 6 integration conflict; 7 runtime not
+// qualified; 8 paused awaiting human decision) — but the lib/task-executor/*.js
+// + lib/execution-ledger.js + lib/agent-registry.js modules underneath it
+// collectively throw several dozen distinct `err.code` values. This table is
+// the single explicit, documented judgment call synthesizing all of them into
+// the fixed enum; it does not re-derive or duplicate the underlying modules'
+// own validation, it only classifies their already-thrown codes for exit
+// status purposes. Grouping rules, in the order applied:
+//
+//   3 (ownership/live worker conflict) — every lease/ownership-lock code, and
+//     every code meaning "a competing coordinator or live worker exists":
+//     LEASE_HELD, LEASE_NOT_OWNER, LEASE_STILL_LIVE, LEASE_LIVENESS_UNKNOWN,
+//     LEASE_NOT_FOUND, GUARD_HELD, NO_LOCK_HELD, COMPETING_COORDINATOR_LIVE,
+//     COMPETING_COORDINATOR_LIVENESS_UNKNOWN, LIVE_WORKER_BLOCKS_REPLAN.
+//
+//   4 (evidence/plan/approval mismatch) — everything meaning "the plan,
+//     approval, or recorded evidence does not match what was expected",
+//     including "expected evidence/record could not be found" (same bucket as
+//     PLAN_NOT_FOUND, per this task's own brief) and immutable-record replay
+//     conflicts (a conflicting second decision is itself an evidence
+//     mismatch, not an I/O failure): SUCCESSOR_NOT_APPROVED,
+//     SUCCESSOR_PLAN_NOT_FOUND, PLAN_NOT_FOUND, PLAN_PARSE_ERROR,
+//     REPLAN_UNKNOWN_TASK_MAPPING, ATTEMPT_NUMBER_MISMATCH,
+//     STATE_READBACK_MISMATCH, STATE_NOT_FOUND, STATE_TASK_NOT_FOUND,
+//     STATE_ATTEMPT_NOT_FOUND, STATE_TASK_EXISTS, TREE_MISMATCH,
+//     PARENT_MISMATCH, COMMIT_REINSPECTION_MISMATCH,
+//     INTEGRATION_PARENT_MISMATCH, INTEGRATION_REINSPECTION_MISMATCH,
+//     INTEGRATION_WORKTREE_STATE_MISMATCH, INTEGRATION_WORKTREE_NOT_CLEAN,
+//     INTEGRATION_SOURCE_NOT_FOUND, INTEGRATION_SOURCE_NOT_ON_BRANCH,
+//     UNEXPECTED_INDEX_CHANGE, STAGING_MISMATCH, DEFINITION_HASH_MISMATCH,
+//     SHA_REGISTRATION_CONFLICT, SHA_REGISTRATION_STAGE_ERROR,
+//     INTEGRATION_SHA_CONFLICT, INTEGRATION_SHA_STAGE_ERROR,
+//     CHECKPOINT_INTENT_STAGE_ERROR, RECEIPT_CONFLICT, RECEIPT_NOT_FOUND,
+//     INTENT_CONFLICT, INTENT_NOT_FOUND, METADATA_CONFLICT,
+//     ACTIVITY_NOT_FOUND, TERMINAL_CONFLICT.
+//
+//   5 (worker/verification/review failure) — the dispatched agent/worker
+//     process itself failed, could not be verified, or could not be spawned:
+//     CLAUDE_SPAWN_FAILED, AGENT_NOT_VERIFIED, RESOLUTION_FAILED.
+//
+//   6 (integration conflict) — INTEGRATION_CONFLICT.
+//
+//   7 (runtime not qualified) — PLATFORM_NOT_QUALIFIED.
+//
+//   2 (invalid config/input) — every *_VALIDATION_ERROR code (there are many;
+//     matched by suffix in mapExecutorErrorToExitCode below rather than
+//     enumerated one-by-one), plus UNSUPPORTED_CONCURRENCY (Tech-Spec:
+//     "reject, never downgrade"), CLAUDE_EXECUTABLE_NOT_FOUND ("unsupported
+//     executable ... fail before mutation"), UNKNOWN_AGENT_TYPE,
+//     METADATA_RESERVED_FIELD, METADATA_UNKNOWN_KEY, INVALID_STATUS.
+//
+//   1 (unexpected I/O) — the DEFAULT for everything else, including every
+//     *_CORRUPTED/CORRUPT_* code, every GIT_*_FAILED/*_FAILED git-command-
+//     spawn code, STATE_UNRECOVERABLE, and — explicitly, per this task's own
+//     brief — NOT_IMPLEMENTED. `status`/`diagnose` are still NOT_IMPLEMENTED
+//     stubs in lib/task-executor/index.js (attributed to US-06-TASK-BE-01/02,
+//     neither of which has actually built their real body yet); this CLI
+//     wires them through exactly like the other five commands and lets that
+//     error surface through this same mapping table honestly — it is not
+//     hidden or special-cased, it simply falls into the default bucket.
+//
+// 8 (paused awaiting human decision) has no throw site and is deliberately
+// absent from this table: execute()'s/resume()'s 'paused' run status is a
+// SUCCESS-path result field (returned, not thrown), so no error code maps to
+// exit 8 here. It is instead selected on the success path, in
+// handleExecutorCommand's own emitSuccess helper below, by inspecting
+// result.runStatus.
+const EXECUTOR_EXIT_CODE_BY_ERROR_CODE = {
+  // 3 — ownership / live worker conflict
+  LEASE_HELD: 3, LEASE_NOT_OWNER: 3, LEASE_STILL_LIVE: 3, LEASE_LIVENESS_UNKNOWN: 3,
+  LEASE_NOT_FOUND: 3, GUARD_HELD: 3, NO_LOCK_HELD: 3, COMPETING_COORDINATOR_LIVE: 3,
+  COMPETING_COORDINATOR_LIVENESS_UNKNOWN: 3, LIVE_WORKER_BLOCKS_REPLAN: 3,
+
+  // 4 — evidence / plan / approval mismatch
+  SUCCESSOR_NOT_APPROVED: 4, SUCCESSOR_PLAN_NOT_FOUND: 4, PLAN_NOT_FOUND: 4,
+  PLAN_PARSE_ERROR: 4, REPLAN_UNKNOWN_TASK_MAPPING: 4, ATTEMPT_NUMBER_MISMATCH: 4,
+  STATE_READBACK_MISMATCH: 4, STATE_NOT_FOUND: 4, STATE_TASK_NOT_FOUND: 4,
+  STATE_ATTEMPT_NOT_FOUND: 4, STATE_TASK_EXISTS: 4, TREE_MISMATCH: 4,
+  PARENT_MISMATCH: 4, COMMIT_REINSPECTION_MISMATCH: 4, INTEGRATION_PARENT_MISMATCH: 4,
+  INTEGRATION_REINSPECTION_MISMATCH: 4, INTEGRATION_WORKTREE_STATE_MISMATCH: 4,
+  INTEGRATION_WORKTREE_NOT_CLEAN: 4, INTEGRATION_SOURCE_NOT_FOUND: 4,
+  INTEGRATION_SOURCE_NOT_ON_BRANCH: 4, UNEXPECTED_INDEX_CHANGE: 4, STAGING_MISMATCH: 4,
+  DEFINITION_HASH_MISMATCH: 4, SHA_REGISTRATION_CONFLICT: 4, SHA_REGISTRATION_STAGE_ERROR: 4,
+  INTEGRATION_SHA_CONFLICT: 4, INTEGRATION_SHA_STAGE_ERROR: 4, CHECKPOINT_INTENT_STAGE_ERROR: 4,
+  RECEIPT_CONFLICT: 4, RECEIPT_NOT_FOUND: 4, INTENT_CONFLICT: 4, INTENT_NOT_FOUND: 4,
+  METADATA_CONFLICT: 4, ACTIVITY_NOT_FOUND: 4, TERMINAL_CONFLICT: 4,
+
+  // 5 — worker / verification / review failure
+  CLAUDE_SPAWN_FAILED: 5, AGENT_NOT_VERIFIED: 5, RESOLUTION_FAILED: 5,
+
+  // 6 — integration conflict
+  INTEGRATION_CONFLICT: 6,
+
+  // 7 — runtime not qualified
+  PLATFORM_NOT_QUALIFIED: 7,
+
+  // 2 — invalid config/input (non-*_VALIDATION_ERROR entries; every
+  // *_VALIDATION_ERROR code is matched by suffix in mapExecutorErrorToExitCode
+  // below rather than listed here)
+  UNSUPPORTED_CONCURRENCY: 2, CLAUDE_EXECUTABLE_NOT_FOUND: 2, UNKNOWN_AGENT_TYPE: 2,
+  METADATA_RESERVED_FIELD: 2, METADATA_UNKNOWN_KEY: 2, INVALID_STATUS: 2,
+
+  // 1 — unexpected I/O (explicit entries kept for documentation clarity even
+  // though 1 is also the default fallback below)
+  STATE_CORRUPTED: 1, RECEIPT_CORRUPTED: 1, INTENT_CORRUPTED: 1, LEASE_CORRUPTED: 1,
+  CORRUPT_LEDGER: 1, STATE_UNRECOVERABLE: 1, NOT_IMPLEMENTED: 1,
+  GIT_SPAWN_FAILED: 1, GIT_STATUS_FAILED: 1, GIT_ADD_FAILED: 1, GIT_WRITE_TREE_FAILED: 1,
+  GIT_DIFF_FAILED: 1, GIT_COMMIT_TREE_FAILED: 1, REF_UPDATE_FAILED: 1, GIT_CAT_FILE_FAILED: 1,
+  GIT_MERGE_BASE_FAILED: 1, GIT_REV_PARSE_FAILED: 1, GIT_CHERRY_PICK_FAILED: 1,
+  GIT_REF_RESOLUTION_FAILED: 1, INTEGRATION_CLEANUP_FAILED: 1,
+};
+
+function mapExecutorErrorToExitCode(code) {
+  if (typeof code === 'string' && Object.prototype.hasOwnProperty.call(EXECUTOR_EXIT_CODE_BY_ERROR_CODE, code)) {
+    return EXECUTOR_EXIT_CODE_BY_ERROR_CODE[code];
+  }
+  // Suffix-based catch-all for the many *_VALIDATION_ERROR codes
+  // (DISPATCH_VALIDATION_ERROR, LEASE_VALIDATION_ERROR,
+  // CLAUDE_PROCESS_VALIDATION_ERROR, STATE_VALIDATION_ERROR,
+  // STAGING_VALIDATION_ERROR, DETECT_CHANGED_PATHS_VALIDATION_ERROR,
+  // COMMIT_VALIDATION_ERROR, INTEGRATION_VALIDATION_ERROR,
+  // WORKTREE_VALIDATION_ERROR, SLOT_POOL_VALIDATION_ERROR,
+  // SHA_REGISTRATION_VALIDATION_ERROR, INTEGRATION_SHA_VALIDATION_ERROR,
+  // CHECKPOINT_INTENT_VALIDATION_ERROR, EXECUTE_VALIDATION_ERROR,
+  // STOP_VALIDATION_ERROR, and any future addition following the same naming
+  // convention) — every one of them means "malformed caller input", i.e.
+  // exit 2, without needing its own table row.
+  if (typeof code === 'string' && code.endsWith('_VALIDATION_ERROR')) {
+    return 2;
+  }
+  // Unknown/unmapped code, including a missing .code entirely: safe default.
+  return 1;
+}
+
+// ── executor dispatcher ───────────────────────────────────────────────────────
+// US-09-TASK-INFRA-01 (FTR-018): Routes `ai-toolkit executor <subcommand>
+// [flags]` to lib/task-executor/index.js's execute/status/diagnose/stop/
+// reconcile/resume/replan (the seven commands of the CLI contract in
+// FTR-018-Tech-Spec.md section 10). All executor domain logic lives in
+// lib/task-executor/*.js; this function only parses CLI flags, derives the
+// couple of git-context values reconcile()/resume()/replan() require but do
+// not derive themselves (see _executorExecutionRoot/_executorCurrentBranchRef
+// above), and maps thrown error codes to the Tech-Spec's fixed exit-code enum
+// (see mapExecutorErrorToExitCode above) — it is NOT a second copy of any
+// executor logic.
+//
+// Flag-rejection mechanism for "no --force*, lock/state path overrides,
+// implicit --abandon or runtime concurrency adjustment" (Tech-Spec section
+// 10): this parser simply never recognizes such flags for any subcommand
+// below. An unrecognized flag is silently ignored rather than explicitly
+// rejected — there is nothing to reject because nothing here ever reads an
+// arbitrary flag by name and forwards it to a filesystem path or lock
+// primitive; only the whitelisted flags per subcommand are ever read via
+// getFlag()/hasFlag().
+async function handleExecutorCommand(argv) {
+  const subcommand = argv[0];
+  const remaining = argv.slice(1);
+
+  function getFlag(name) {
+    const idx = remaining.indexOf(name);
+    return idx !== -1 && remaining[idx + 1] !== undefined ? remaining[idx + 1] : undefined;
+  }
+
+  function emitSuccess(result) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    // Tech-Spec section 10 exit code 8 ("paused awaiting human decision") is a
+    // SUCCESS-path outcome, not an error — only execute()'s and resume()'s
+    // result objects can legitimately carry `runStatus: 'paused'` (see the
+    // exit-code mapping comment above EXECUTOR_EXIT_CODE_BY_ERROR_CODE for why
+    // no *_ERROR code maps to 8). reconcile/stop/replan results never carry a
+    // `runStatus` field at all, and status/diagnose never reach this success
+    // path (still NOT_IMPLEMENTED) — so this check is a no-op for every other
+    // subcommand's result shape and never needs to be scoped by subcommand.
+    process.exitCode = result && result.runStatus === 'paused' ? 8 : 0;
+  }
+
+  function emitError(err) {
+    const code = err && err.code ? err.code : undefined;
+    const exitCode = mapExecutorErrorToExitCode(code);
+    process.stderr.write(JSON.stringify({
+      status: 'error',
+      code: code || 'UNKNOWN',
+      message: err && err.message ? err.message : String(err),
+    }, null, 2) + '\n');
+    process.exitCode = exitCode;
+  }
+
+  function usageError(message) {
+    process.stderr.write('Error: ' + message + '\n');
+    process.exitCode = 2;
+  }
+
+  const projectDir = path.resolve(getFlag('--project') || process.cwd());
+
+  try {
+    const taskExecutor = require('../lib/task-executor');
+
+    if (subcommand === 'start') {
+      const feature = getFlag('--feature');
+      if (!feature) { usageError('executor start requires --feature'); return; }
+      const maxConcurrencyRaw = getFlag('--max-concurrency');
+      const taskTimeoutMsRaw  = getFlag('--task-timeout-ms');
+      const agentBudgetUsdRaw = getFlag('--agent-budget-usd');
+      const result = await taskExecutor.execute({
+        project: projectDir,
+        feature: feature,
+        maxConcurrency: maxConcurrencyRaw === undefined ? undefined : Number(maxConcurrencyRaw),
+        claudePath: getFlag('--claude-path'),
+        taskTimeoutMs: taskTimeoutMsRaw === undefined ? undefined : Number(taskTimeoutMsRaw),
+        agentBudgetUsd: agentBudgetUsdRaw === undefined ? undefined : Number(agentBudgetUsdRaw),
+      });
+      emitSuccess(result);
+
+    } else if (subcommand === 'status') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor status requires --run-id'); return; }
+      const result = await taskExecutor.status({ project: projectDir, runId: runId });
+      emitSuccess(result);
+
+    } else if (subcommand === 'diagnose') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor diagnose requires --run-id'); return; }
+      const result = await taskExecutor.diagnose({ project: projectDir, runId: runId });
+      emitSuccess(result);
+
+    } else if (subcommand === 'stop') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor stop requires --run-id'); return; }
+      const result = await taskExecutor.stop({
+        project: projectDir,
+        runId: runId,
+        mode: getFlag('--mode') || 'graceful',
+      });
+      emitSuccess(result);
+
+    } else if (subcommand === 'reconcile' || subcommand === 'resume') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor ' + subcommand + ' requires --run-id'); return; }
+      const executionRoot = _executorExecutionRoot(projectDir);
+      const taskRef        = _executorCurrentBranchRef(projectDir);
+      const fn = subcommand === 'reconcile' ? taskExecutor.reconcile : taskExecutor.resume;
+      const result = await fn({
+        executionRoot: executionRoot,
+        runId: runId,
+        projectDir: projectDir,
+        taskRef: taskRef,
+      });
+      emitSuccess(result);
+
+    } else if (subcommand === 'replan') {
+      const runId    = getFlag('--run-id');
+      const feature  = getFlag('--feature');
+      if (!runId)   { usageError('executor replan requires --run-id'); return; }
+      if (!feature) { usageError('executor replan requires --feature (the approved successor plan)'); return; }
+
+      // --task-mapping-json is NOT one of the Tech-Spec table's listed
+      // arguments for replan (only --run-id/--feature are) — but
+      // lib/task-executor/index.js's replan() requires args.taskMapping to be
+      // an array (DISPATCH_VALIDATION_ERROR otherwise) and never invents one
+      // itself (see its own doc comment: "taskMapping is an explicit,
+      // caller-supplied old->new task ID mapping"). Following this session's
+      // established pattern of flagging gaps rather than papering over them:
+      // this flag is documented here as a necessary CLI-layer extension
+      // beyond the literal table, using the same `--*-json` structured-input
+      // convention the ledger subcommand already established
+      // (--metadata-json). Omitting it defaults to an empty mapping (a valid
+      // array — "no task carries forward" — never rejected by replan()).
+      let taskMapping = [];
+      const taskMappingJson = getFlag('--task-mapping-json');
+      if (taskMappingJson !== undefined) {
+        try {
+          taskMapping = JSON.parse(taskMappingJson);
+        } catch (parseErr) {
+          usageError('--task-mapping-json is not valid JSON: ' + parseErr.message);
+          return;
+        }
+      }
+
+      const executionRoot = _executorExecutionRoot(projectDir);
+      const taskRef        = _executorCurrentBranchRef(projectDir);
+      const result = await taskExecutor.replan({
+        executionRoot: executionRoot,
+        runId: runId,
+        projectDir: projectDir,
+        taskRef: taskRef,
+        feature: feature,
+        taskMapping: taskMapping,
+      });
+      emitSuccess(result);
+
+    } else {
+      usageError('unknown executor subcommand: ' + (subcommand || '(none)'));
+    }
+  } catch (err) {
+    emitError(err);
+  }
+}
+
 // ── entry point guard ─────────────────────────────────────────────────────────
 // Run the CLI only when invoked directly (node bin/cli.js).
 // When required as a module (e.g., by Jest), skip main() and export pure
@@ -2127,5 +2961,13 @@ if (require.main === module) {
     handleLedgerCommand,
     sortedJson,
     resolveFeaturesRoot,
+    computeFileSha256,
+    handleAgentsCommand,
+    handleExecutorCommand,
+    mapExecutorErrorToExitCode,
+    EXECUTOR_EXIT_CODE_BY_ERROR_CODE,
+    _executorResolveCommonGitDir,
+    _executorExecutionRoot,
+    _executorCurrentBranchRef,
   };
 }