@dtlabs/ai-toolkit 0.11.0 → 0.13.0

package/bin/cli.js

@@ -3,6 +3,8 @@ const fs   = require('fs');
 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 ────────────────────────────────────────────────────────────────────
@@ -45,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; }
 }
@@ -288,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 => {
@@ -301,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');
@@ -414,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;
   }
 
@@ -425,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;
   }
 
@@ -454,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) ────────────
@@ -580,67 +611,6 @@ function mergeAllowlist(destDir) {
   return { status: 'merged', preserved };
 }
 
-// INFRA-T01 (FTR-013):
-// Append a new entry to {featureDir}/{prefix}-token-ledger.json atomically.
-// If the file does not exist it is created. If JSON is malformed the file is
-// overwritten with a single-element array containing the new entry.
-//
-// Algorithm:
-//   1. Read and parse the existing ledger (or start with [])
-//   2. Push the new entry
-//   3. Write the full array back in one synchronous write (atomic)
-function appendLedgerEntry(featureDir, prefix, entry) {
-  const filePath = path.join(featureDir, `${prefix}-token-ledger.json`);
-  let ledger = [];
-  if (fs.existsSync(filePath)) {
-    try {
-      const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-      ledger = Array.isArray(parsed) ? parsed : [];
-    } catch (_) {
-      console.log(`Warning: could not parse token ledger at ${filePath} — starting fresh`);
-      ledger = [];
-    }
-  }
-  ledger.push(entry);
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf8');
-}
-
-// INFRA-T02 (FTR-013):
-// Find and update an existing entry in {featureDir}/{prefix}-token-ledger.json
-// by agent key, atomically. Searches from the end of the array so that the most
-// recent entry for a given key is updated (handles any accidental duplicates).
-// If the file does not exist or the key is not found the call is a silent no-op.
-//
-// Algorithm:
-//   1. Read and parse the existing ledger (silent return on missing/malformed)
-//   2. Find the last entry where entry.agent === agentKey
-//   3. Object.assign the updates onto that entry
-//   4. Write the full array back in one synchronous write (atomic)
-function updateLedgerEntry(featureDir, prefix, agentKey, updates) {
-  const filePath = path.join(featureDir, `${prefix}-token-ledger.json`);
-  if (!fs.existsSync(filePath)) return;
-  let ledger;
-  try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    ledger = Array.isArray(parsed) ? parsed : [];
-  } catch (_) {
-    console.log(`Warning: could not parse token ledger at ${filePath} — skipping update for "${agentKey}"`);
-    return;
-  }
-  let idx = -1;
-  for (let i = ledger.length - 1; i >= 0; i--) {
-    if (ledger[i] && ledger[i].agent === agentKey) { idx = i; break; }
-  }
-  if (idx === -1) {
-    console.log(`Warning: ledger entry not found for agent key "${agentKey}"`);
-    return;
-  }
-  Object.assign(ledger[idx], updates);
-  fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2), 'utf8');
-}
-
 // US-05-T01:
 // Idempotently append `.claude/settings.local.json` to {destDir}/.gitignore.
 // Creates .gitignore if it does not exist (AC-06, AC-07).
@@ -672,6 +642,113 @@ function updateGitignore(destDir) {
   }
 }
 
+// ── resolveFeaturesRoot ───────────────────────────────────────────────────────
+
+// US-05-TASK-BE-01 (FTR-016):
+// Resolve the features root directory for a given working directory.
+//
+// Ordered precedence — ALL candidates are gathered before deciding so that
+// ambiguity (multiply-declared AGENTS.md entries, multiple inconsistent
+// defaults) can be detected rather than silently swallowed:
+//   1. Explicit override via options.featuresRoot (highest precedence)
+//   2. features_root: convention parsed from <cwd>/AGENTS.md
+//   3. A single existing conventional default directory
+//
+// AGENTS.md grammar parser (deterministic):
+//   - Ignores HTML-comment lines of the form <!-- ... --> (same input line)
+//   - Strips inline # comments from the value and trims trailing whitespace
+//   - Counts only active (non-commented) declarations when detecting the
+//     multiply-declared error; throws when two or more are found
+//
+// Returns an absolute path.
+// Throws a clear structured Error on ambiguous or multiply-declared roots.
+//
+// Parameters:
+//   cwd     (string): project root directory
+//   options (object): { featuresRoot? } — explicit override, highest precedence
+function resolveFeaturesRoot(cwd, options) {
+  const opts        = options || {};
+  const resolvedCwd = path.resolve(cwd);
+
+  // Conventional default directories tried when no higher-precedence source is found.
+  const CONVENTIONAL_DEFAULTS = [
+    'internal_docs/features',
+    'docs/features',
+  ];
+
+  // ── AGENTS.md grammar parser ──────────────────────────────────────────────
+  // Returns an array of trimmed value strings for each ACTIVE features_root:
+  // declaration found in <cwdDir>/AGENTS.md.  Deterministic: same input →
+  // same result; does not rely on filesystem ordering.
+  function parseAgentsMdDeclarations(cwdDir) {
+    const agentsMdPath = path.join(cwdDir, 'AGENTS.md');
+    if (!fs.existsSync(agentsMdPath)) return [];
+    let content;
+    try { content = fs.readFileSync(agentsMdPath, 'utf8'); } catch (_) { return []; }
+
+    const declarations = [];
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+
+      // Ignore HTML comment lines: <!-- anything -->
+      if (/^<!--.*-->$/.test(trimmed)) continue;
+
+      // Match active features_root: declarations
+      const match = trimmed.match(/^features_root:\s*(.*)$/);
+      if (!match) continue;
+
+      // Strip inline # comment, then trim
+      let value = match[1];
+      const hashIdx = value.indexOf('#');
+      if (hashIdx !== -1) value = value.substring(0, hashIdx);
+      value = value.trim();
+
+      if (value) declarations.push(value);
+    }
+    return declarations;
+  }
+
+  // ── Source 1: Explicit override ───────────────────────────────────────────
+  if (opts.featuresRoot !== undefined && opts.featuresRoot !== null && opts.featuresRoot !== '') {
+    return path.resolve(resolvedCwd, opts.featuresRoot);
+  }
+
+  // ── Source 2: AGENTS.md features_root: convention ────────────────────────
+  const agentsDeclarations = parseAgentsMdDeclarations(resolvedCwd);
+  if (agentsDeclarations.length > 1) {
+    throw new Error(
+      `resolveFeaturesRoot: AGENTS.md declares features_root: ${agentsDeclarations.length} times ` +
+      `(values: ${agentsDeclarations.map(v => JSON.stringify(v)).join(', ')}); ` +
+      'only one active declaration is allowed'
+    );
+  }
+  if (agentsDeclarations.length === 1) {
+    return path.resolve(resolvedCwd, agentsDeclarations[0]);
+  }
+
+  // ── Source 3: Conventional defaults — use only when exactly one exists ────
+  const existingDefaults = CONVENTIONAL_DEFAULTS
+    .map(d => path.resolve(resolvedCwd, d))
+    .filter(d => { try { return fs.statSync(d).isDirectory(); } catch (_) { return false; } });
+
+  if (existingDefaults.length === 1) {
+    return existingDefaults[0];
+  }
+
+  if (existingDefaults.length > 1) {
+    throw new Error(
+      `resolveFeaturesRoot: multiple conventional default directories exist ` +
+      `(${existingDefaults.join(', ')}); declare features_root: in AGENTS.md to disambiguate`
+    );
+  }
+
+  throw new Error(
+    `resolveFeaturesRoot: no features root found under ${resolvedCwd}. ` +
+    'Declare features_root: in AGENTS.md or create one of the conventional default directories ' +
+    `(${CONVENTIONAL_DEFAULTS.join(', ')})`
+  );
+}
+
 // ── payload & detection ───────────────────────────────────────────────────────
 
 // Returns file-level {src, dest} mappings (absolute paths) for ALL distributable
@@ -1439,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):
@@ -1507,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']),
 };
 
@@ -1717,6 +1945,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') {
@@ -1862,6 +2098,19 @@ async function main() {
       for (const r of results) process.stdout.write(r + '\n');
     }
     process.exit(0);
+  } else if (argv[0] === 'resolve-features-root') {
+    try {
+      const resolved = resolveFeaturesRoot(process.cwd());
+      process.stdout.write(resolved + '\n');
+      process.exit(0);
+    } catch (err) {
+      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 (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
     await installLocal(argv[0], force, dryRun);
   } else {
@@ -1870,6 +2119,441 @@ async function main() {
   }
 }
 
+// ── shell quoting helper ──────────────────────────────────────────────────────
+function shellQuotePosix(arg) {
+  const s = String(arg);
+  if (s.indexOf('\0') !== -1) throw new Error('shellQuotePosix: argument contains a NUL byte');
+  if (s.indexOf('\n') !== -1) throw new Error('shellQuotePosix: argument contains a newline');
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+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, metadata: undefined };
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const val  = argv[i + 1];
+
+    if (flag === '--prefix') {
+      i++;
+      if (!val || !PREFIX_RE.test(val)) {
+        throw new Error(
+          'parseLedgerArgs: --prefix must match /^[A-Za-z]+-\\d+$/ (e.g. FTR-016), got: ' + val
+        );
+      }
+      result.prefix = val;
+    } else if (flag === '--agent') {
+      i++;
+      if (!val) {
+        throw new Error('parseLedgerArgs: --agent must be a non-empty string');
+      }
+      result.agent = val;
+    } else if (flag === '--attempt') {
+      i++;
+      const n = Number(val);
+      if (!Number.isInteger(n)) {
+        throw new Error('parseLedgerArgs: --attempt must be an integer, got: ' + val);
+      }
+      result.attempt = n;
+    } else if (flag === '--tokens') {
+      i++;
+      const n = Number(val);
+      if (!Number.isInteger(n) || n < 1) {
+        throw new Error('parseLedgerArgs: --tokens must be an integer >= 1, got: ' + val);
+      }
+      result.tokens = n;
+    } else if (flag === '--dir') {
+      i++;
+      if (!val) {
+        throw new Error('parseLedgerArgs: --dir must be a non-empty string');
+      }
+      result.dir = val;
+    } else if (flag === '--phase') {
+      i++;
+      if (!val) {
+        throw new Error('parseLedgerArgs: --phase must be a non-empty string');
+      }
+      result.phase = val;
+    } else if (flag === '--model') {
+      i++;
+      if (!val) {
+        throw new Error('parseLedgerArgs: --model must be a non-empty string');
+      }
+      result.model = val;
+    } else if (flag === '--error') {
+      i++;
+      if (!val) {
+        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 });
+    }
+  }
+
+  if (!result.prefix) {
+    throw new Error('parseLedgerArgs: --prefix is required');
+  }
+  if (!result.agent) {
+    throw new Error('parseLedgerArgs: --agent is required and must be non-empty');
+  }
+
+  return result;
+}
+
+// Serialize obj to JSON with all object keys sorted recursively.
+// Used by the ledger subcommand to produce deterministic stdout output.
+function sortedJson(obj) {
+  return JSON.stringify(obj, (key, val) => {
+    if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+      const sorted = {};
+      for (const k of Object.keys(val).sort()) sorted[k] = val[k];
+      return sorted;
+    }
+    return val;
+  }, 2);
+}
+
+// ── ledger dispatcher ─────────────────────────────────────────────────────────
+// Routes `ai-toolkit ledger <subcommand> [flags]` to the per-operation
+// handlers in lib/execution-ledger.js. All operation logic lives in that
+// module; this function only parses shared flags and routes.
+function handleLedgerCommand(argv) {
+  const subcommand = argv[0];
+  const flags = argv.slice(1);
+  let args;
+  try {
+    args = parseLedgerArgs(flags);
+  } catch (err) {
+    process.stderr.write(sortedJson({ message: err.message, status: 'error' }) + '\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (subcommand === 'open') {
+    try {
+      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) {
+      process.stderr.write(sortedJson({ message: err.message, status: 'error' }) + '\n');
+      process.exitCode = 1;
+    }
+    return;
+  } else if (subcommand === 'close') {
+    try {
+      const result = executionLedger.close(args.dir, args.prefix, args.agent, args.tokens, args.attempt);
+      process.stdout.write(sortedJson(result) + '\n');
+      process.exitCode = 0;
+    } catch (err) {
+      process.stderr.write(sortedJson({ message: err.message, status: 'error' }) + '\n');
+      process.exitCode = 1;
+    }
+    return;
+  } else if (subcommand === 'fail') {
+    try {
+      const result = executionLedger.fail(args.dir, args.prefix, args.agent, args.error, args.attempt);
+      process.stdout.write(sortedJson(result) + '\n');
+      process.exitCode = 0;
+    } catch (err) {
+      process.stderr.write(sortedJson({ message: err.message, status: 'error' }) + '\n');
+      process.exitCode = 1;
+    }
+    return;
+  } else if (subcommand === 'skip') {
+    try {
+      const result = executionLedger.skip(args.dir, args.prefix, args.agent, args.phase, args.model, args.attempt);
+      process.stdout.write(sortedJson(result) + '\n');
+      process.exitCode = 0;
+    } catch (err) {
+      process.stderr.write(sortedJson({ message: err.message, status: 'error' }) + '\n');
+      process.exitCode = 1;
+    }
+    return;
+  } else {
+    throw new Error('handleLedgerCommand: unknown subcommand: ' + subcommand);
+  }
+}
+
+// ── 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;
+  }
+}
+
 // ── 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
@@ -1898,8 +2582,6 @@ if (require.main === module) {
     writeSettings,
     mergeAllowlist,
     updateGitignore,
-    appendLedgerEntry,
-    updateLedgerEntry,
     resolveClaudeRuntimeAsset,
     runDoctorResolution,
     validatePurityGuard,
@@ -1911,5 +2593,12 @@ if (require.main === module) {
     hasToolkitPayloadFiles,
     isToolkitInstalled,
     runVerifyInstall,
+    shellQuotePosix,
+    parseLedgerArgs,
+    handleLedgerCommand,
+    sortedJson,
+    resolveFeaturesRoot,
+    computeFileSha256,
+    handleAgentsCommand,
   };
 }