@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.8

package/src/commands/plan-ledger.js

@@ -0,0 +1,370 @@
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createLocalSqliteDatabaseSync } from '../local/sqlite.js';
+import { applyRuntimeMigrationsSync } from '../local/migrations.js';
+import { getLocalDatabasePath, readProjectConfig } from '../lib/project-config.js';
+import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
+
+function id(prefix) {
+  return prefix + '_' + Date.now().toString(36) + '_' + randomBytes(4).toString('hex');
+}
+
+function parseJson(value, fallback) {
+  try { return JSON.parse(String(value || '')); }
+  catch { return fallback; }
+}
+
+function repositoryIdFor(root, git, config) {
+  return config?.repository?.id
+    || (git?.repoFullName ? 'github:' + git.repoFullName.toLowerCase() : null)
+    || 'local:' + root;
+}
+
+export function openPlanLedger(cwd = process.cwd()) {
+  const git = tryResolveGitContext({ cwd });
+  const root = git?.root || path.resolve(cwd);
+  const config = readProjectConfig(root);
+  const dbPath = path.resolve(root, getLocalDatabasePath(config));
+  const db = createLocalSqliteDatabaseSync(dbPath);
+  applyRuntimeMigrationsSync(db);
+  db.exec('PRAGMA foreign_keys = ON;');
+  return {
+    db, dbPath, root, git,
+    repositoryId: repositoryIdFor(root, git, config),
+    close() { db.close(); },
+  };
+}
+
+function planMetadata(ctx, input = {}) {
+  return {
+    schema: 'agentsam.plan.v1',
+    repository_id: ctx.repositoryId,
+    repository_root: ctx.root,
+    branch: ctx.git?.branch || null,
+    revision: ctx.git?.revisionSha || null,
+    dirty: Boolean(ctx.git?.dirty),
+    goal: input.goal || input.title || '',
+    acceptance: input.acceptance || [],
+    evidence: input.evidence || [],
+    scope: input.scope || {},
+    created_by: input.createdBy || 'cli',
+  };
+}
+
+function taskMetadata(ctx, input = {}) {
+  return {
+    schema: 'agentsam.todo.v1',
+    repository_id: ctx.repositoryId,
+    kind: input.kind || 'work',
+    depends_on: input.dependsOn || [],
+    acceptance: input.acceptance || [],
+    evidence: input.evidence || [],
+    blocker_reason: input.blockerReason || null,
+  };
+}
+
+function hydratePlan(row) {
+  return row ? { ...row, metadata: parseJson(row.metadata_json, {}) } : null;
+}
+
+function hydrateTask(row) {
+  return row ? { ...row, metadata: parseJson(row.metadata_json, {}) } : null;
+}
+
+function refreshPlanCounts(ctx, planId) {
+  const counts = ctx.db.prepare(
+    "SELECT COUNT(*) AS total, " +
+    "SUM(CASE WHEN status = 'complete' THEN 1 ELSE 0 END) AS done, " +
+    "SUM(CASE WHEN status = 'blocked' THEN 1 ELSE 0 END) AS blocked " +
+    "FROM agentsam_todo WHERE plan_id = ?"
+  ).get(planId);
+  ctx.db.prepare(
+    'UPDATE agentsam_plans SET tasks_total = ?, tasks_done = ?, tasks_blocked = ?, updated_at_unix = unixepoch() WHERE id = ?'
+  ).run(Number(counts?.total || 0), Number(counts?.done || 0), Number(counts?.blocked || 0), planId);
+}
+
+export function createPlan(ctx, input) {
+  const title = String(input?.title || '').trim();
+  if (!title) throw new Error('plan_title_required');
+  const goal = String(input?.goal || title).trim();
+  const planId = id('plan');
+  const metadata = planMetadata(ctx, { ...input, title, goal });
+  ctx.db.prepare(
+    "INSERT INTO agentsam_plans (" +
+    "id, account_id, session_id, agent_run_id, plan_type, title, status, summary_text, token_budget, metadata_json" +
+    ") VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)"
+  ).run(
+    planId,
+    input?.accountId || null,
+    input?.sessionId || null,
+    input?.agentRunId || null,
+    input?.planType || 'feature',
+    title,
+    goal,
+    input?.tokenBudget ?? null,
+    JSON.stringify(metadata),
+  );
+  return getPlan(ctx, planId);
+}
+
+export function listPlans(ctx, { all = false } = {}) {
+  const sql =
+    "SELECT * FROM agentsam_plans " +
+    "WHERE json_extract(metadata_json, '$.repository_id') = ? " +
+    (all ? '' : "AND status IN ('draft','active') ") +
+    "ORDER BY updated_at_unix DESC, created_at_unix DESC";
+  return ctx.db.prepare(sql).all(ctx.repositoryId).map(hydratePlan);
+}
+
+export function getCurrentPlan(ctx) {
+  const row = ctx.db.prepare(
+    "SELECT p.* FROM agentsam_plans p " +
+    "WHERE json_extract(p.metadata_json, '$.repository_id') = ? " +
+    "AND p.status IN ('active','draft') " +
+    "ORDER BY " +
+    "EXISTS(SELECT 1 FROM agentsam_todo t WHERE t.plan_id = p.id AND t.status = 'running') DESC, " +
+    "CASE p.status WHEN 'active' THEN 0 ELSE 1 END, p.updated_at_unix DESC, p.created_at_unix DESC LIMIT 1"
+  ).get(ctx.repositoryId);
+  return hydratePlan(row);
+}
+
+export function getPlan(ctx, planId = 'current') {
+  const plan = planId === 'current'
+    ? getCurrentPlan(ctx)
+    : hydratePlan(ctx.db.prepare('SELECT * FROM agentsam_plans WHERE id = ? LIMIT 1').get(planId));
+  if (!plan) return null;
+  const tasks = ctx.db.prepare(
+    'SELECT * FROM agentsam_todo WHERE plan_id = ? ORDER BY sort_order ASC, created_at_unix ASC'
+  ).all(plan.id).map(hydrateTask);
+  return { ...plan, tasks };
+}
+
+export function addPlanStep(ctx, input) {
+  const plan = getPlan(ctx, input?.planId || 'current');
+  if (!plan) throw new Error('active_plan_required');
+  const title = String(input?.title || '').trim();
+  if (!title) throw new Error('step_title_required');
+  const taskId = id('todo');
+  const order = ctx.db.prepare(
+    'SELECT COALESCE(MAX(sort_order), 0) + 10 AS next_order FROM agentsam_todo WHERE plan_id = ?'
+  ).get(plan.id)?.next_order || 10;
+  ctx.db.prepare(
+    "INSERT INTO agentsam_todo (" +
+    "id, account_id, plan_id, agent_run_id, title, description, status, priority, sort_order, token_budget, requires_approval, metadata_json" +
+    ") VALUES (?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?)"
+  ).run(
+    taskId,
+    input?.accountId || plan.account_id || null,
+    plan.id,
+    input?.agentRunId || null,
+    title,
+    input?.description || null,
+    input?.priority || 'medium',
+    Number(order),
+    input?.tokenBudget ?? null,
+    input?.requiresApproval ? 1 : 0,
+    JSON.stringify(taskMetadata(ctx, input)),
+  );
+  refreshPlanCounts(ctx, plan.id);
+  return hydrateTask(ctx.db.prepare('SELECT * FROM agentsam_todo WHERE id = ?').get(taskId));
+}
+
+const PRIORITY_ORDER = Object.freeze({ critical: 0, high: 1, medium: 2, low: 3 });
+
+function getTask(ctx, taskId) {
+  return hydrateTask(ctx.db.prepare('SELECT * FROM agentsam_todo WHERE id = ? LIMIT 1').get(taskId));
+}
+
+function dependencyBlockers(ctx, task) {
+  const ids = Array.isArray(task?.metadata?.depends_on) ? task.metadata.depends_on : [];
+  if (!ids.length) return [];
+  const blockers = [];
+  for (const dependencyId of ids) {
+    const dependency = getTask(ctx, dependencyId);
+    if (!dependency || dependency.status !== 'complete') {
+      blockers.push({
+        id: dependencyId,
+        status: dependency?.status || 'missing',
+        title: dependency?.title || null,
+      });
+    }
+  }
+  return blockers;
+}
+
+function pendingAcceptance(task) {
+  const entries = Array.isArray(task?.metadata?.acceptance) ? task.metadata.acceptance : [];
+  return entries.filter((entry) => {
+    if (typeof entry === 'string') return true;
+    if (!entry || typeof entry !== 'object') return false;
+    return entry.required !== false && entry.status !== 'accepted';
+  });
+}
+
+export function getNextPlanStep(ctx, { planId = 'current', start = false } = {}) {
+  const plan = getPlan(ctx, planId);
+  if (!plan) throw new Error('plan_not_found');
+  const rank = (a, b) => {
+    const priority = (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99);
+    if (priority !== 0) return priority;
+    if (Number(a.sort_order) !== Number(b.sort_order)) return Number(a.sort_order) - Number(b.sort_order);
+    return Number(a.created_at_unix) - Number(b.created_at_unix);
+  };
+  const running = (plan.tasks || []).filter((task) => task.status === 'running').sort(rank);
+  if (running.length) {
+    const selected = running[0];
+    return {
+      plan: { id: plan.id, title: plan.title, status: plan.status },
+      step: selected,
+      selection: 'running',
+      blocked: [],
+      evidence: selected?.metadata?.evidence || [],
+      acceptance: selected?.metadata?.acceptance || [],
+      depends_on: selected?.metadata?.depends_on || [],
+      recommended_action: 'agentsam plan show ' + plan.id,
+    };
+  }
+
+  const candidates = (plan.tasks || [])
+    .filter((task) => task.status === 'open')
+    .sort(rank);
+
+  const blocked = [];
+  let selected = null;
+  for (const task of candidates) {
+    const blockers = dependencyBlockers(ctx, task);
+    if (!blockers.length) {
+      selected = task;
+      break;
+    }
+    blocked.push({ task_id: task.id, blockers });
+  }
+
+  if (selected && start) selected = setPlanStepStatus(ctx, selected.id, 'running');
+  return {
+    plan: { id: plan.id, title: plan.title, status: plan.status },
+    step: selected,
+    selection: selected ? (start ? 'started' : 'open') : 'none',
+    blocked,
+    evidence: selected?.metadata?.evidence || [],
+    acceptance: selected?.metadata?.acceptance || [],
+    depends_on: selected?.metadata?.depends_on || [],
+    recommended_action: selected ? ('agentsam plan ' + (start ? 'show ' : 'start ') + selected.id) : null,
+  };
+}
+
+export function addPlanStepEvidence(ctx, taskId, input = {}) {
+  const task = getTask(ctx, taskId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  const type = String(input.type || 'evidence').trim();
+  const ref = String(input.ref || '').trim();
+  if (!ref) throw new Error('evidence_ref_required');
+  const metadata = { ...task.metadata };
+  const evidence = Array.isArray(metadata.evidence) ? [...metadata.evidence] : [];
+  const duplicate = evidence.some((entry) => entry && typeof entry === 'object' && entry.type === type && entry.ref === ref);
+  if (!duplicate) {
+    evidence.push({
+      type,
+      ref,
+      hash: input.hash ? String(input.hash) : null,
+      note: input.note ? String(input.note) : null,
+      added_at_unix: Math.floor(Date.now() / 1000),
+    });
+  }
+  metadata.evidence = evidence;
+  ctx.db.prepare('UPDATE agentsam_todo SET metadata_json = ?, updated_at_unix = unixepoch() WHERE id = ?')
+    .run(JSON.stringify(metadata), taskId);
+  return getTask(ctx, taskId);
+}
+
+export function acceptPlanStep(ctx, taskId, criterion, { evidenceRef = null } = {}) {
+  const task = getTask(ctx, taskId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  const text = String(criterion || '').trim();
+  if (!text) throw new Error('acceptance_criterion_required');
+  const metadata = { ...task.metadata };
+  const entries = Array.isArray(metadata.acceptance) ? [...metadata.acceptance] : [];
+  const now = Math.floor(Date.now() / 1000);
+  let matched = false;
+  metadata.acceptance = entries.map((entry) => {
+    const entryText = typeof entry === 'string' ? entry : String(entry?.criterion || '');
+    if (entryText !== text) return entry;
+    matched = true;
+    return {
+      criterion: text,
+      required: typeof entry === 'object' ? entry.required !== false : true,
+      status: 'accepted',
+      accepted_at_unix: now,
+      evidence_ref: evidenceRef || (typeof entry === 'object' ? entry.evidence_ref || null : null),
+    };
+  });
+  if (!matched) {
+    metadata.acceptance.push({
+      criterion: text,
+      required: true,
+      status: 'accepted',
+      accepted_at_unix: now,
+      evidence_ref: evidenceRef || null,
+    });
+  }
+  ctx.db.prepare('UPDATE agentsam_todo SET metadata_json = ?, updated_at_unix = unixepoch() WHERE id = ?')
+    .run(JSON.stringify(metadata), taskId);
+  return getTask(ctx, taskId);
+}
+
+export function addPlanDependency(ctx, taskId, dependencyId) {
+  const task = getTask(ctx, taskId);
+  const dependency = getTask(ctx, dependencyId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  if (!dependency) throw new Error('dependency_not_found:' + dependencyId);
+  if (task.plan_id !== dependency.plan_id) throw new Error('dependency_cross_plan_not_allowed');
+  if (task.id === dependency.id) throw new Error('dependency_self_reference');
+  const metadata = { ...task.metadata };
+  const dependsOn = new Set(Array.isArray(metadata.depends_on) ? metadata.depends_on : []);
+  dependsOn.add(dependency.id);
+  metadata.depends_on = [...dependsOn];
+  ctx.db.prepare('UPDATE agentsam_todo SET metadata_json = ?, updated_at_unix = unixepoch() WHERE id = ?')
+    .run(JSON.stringify(metadata), taskId);
+  return getTask(ctx, taskId);
+}
+
+export function setPlanStepStatus(ctx, taskId, status, { reason = null } = {}) {
+  const allowed = new Set(['open', 'running', 'blocked', 'complete', 'cancelled']);
+  if (!allowed.has(status)) throw new Error('invalid_step_status:' + status);
+  const task = getTask(ctx, taskId);
+  if (!task) throw new Error('step_not_found:' + taskId);
+  if (status === 'complete') {
+    const blockers = dependencyBlockers(ctx, task);
+    if (blockers.length) throw new Error('step_dependencies_incomplete:' + blockers.map((row) => row.id).join(','));
+    const acceptance = pendingAcceptance(task);
+    if (acceptance.length) {
+      const labels = acceptance.map((entry) => typeof entry === 'string' ? entry : entry.criterion).filter(Boolean);
+      throw new Error('step_acceptance_incomplete:' + labels.join(' | '));
+    }
+  }
+  const metadata = { ...task.metadata };
+  if (status === 'blocked') metadata.blocker_reason = reason || metadata.blocker_reason || 'blocked';
+  else metadata.blocker_reason = null;
+
+  let startedSql = 'started_at_unix';
+  let completedSql = 'NULL';
+  if (status === 'running') startedSql = 'COALESCE(started_at_unix, unixepoch())';
+  if (status === 'complete') completedSql = 'unixepoch()';
+  if (status === 'cancelled') completedSql = 'COALESCE(completed_at_unix, unixepoch())';
+
+  ctx.db.prepare(
+    'UPDATE agentsam_todo SET status = ?, metadata_json = ?, started_at_unix = ' + startedSql +
+    ', completed_at_unix = ' + completedSql + ', updated_at_unix = unixepoch() WHERE id = ?'
+  ).run(status, JSON.stringify(metadata), taskId);
+  refreshPlanCounts(ctx, task.plan_id);
+  return hydrateTask(ctx.db.prepare('SELECT * FROM agentsam_todo WHERE id = ?').get(taskId));
+}
+
+export function setPlanStatus(ctx, planId, status) {
+  const allowed = new Set(['draft', 'active', 'complete', 'abandoned']);
+  if (!allowed.has(status)) throw new Error('invalid_plan_status:' + status);
+  const plan = getPlan(ctx, planId || 'current');
+  if (!plan) throw new Error('plan_not_found');
+  ctx.db.prepare('UPDATE agentsam_plans SET status = ?, updated_at_unix = unixepoch() WHERE id = ?').run(status, plan.id);
+  return getPlan(ctx, plan.id);
+}

package/src/commands/plan.js

@@ -0,0 +1,183 @@
+import { runBrand } from './brand.js';
+import {
+  acceptPlanStep,
+  addPlanDependency,
+  addPlanStep,
+  addPlanStepEvidence,
+  createPlan,
+  getNextPlanStep,
+  getPlan,
+  listPlans,
+  openPlanLedger,
+  setPlanStatus,
+  setPlanStepStatus,
+} from './plan-ledger.js';
+
+function parse(argv = []) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (!value.startsWith('--')) {
+      opts._.push(value);
+      continue;
+    }
+    const key = value.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      opts[key] = next;
+      i += 1;
+    } else {
+      opts[key] = true;
+    }
+  }
+  return opts;
+}
+
+function renderPlan(plan) {
+  if (!plan) return 'No active local plan.\n';
+  const lines = [
+    '',
+    'AgentSam plan',
+    '',
+    '  id        ' + plan.id,
+    '  title     ' + plan.title,
+    '  type      ' + plan.plan_type,
+    '  status    ' + plan.status,
+    '  goal      ' + (plan.metadata?.goal || plan.summary_text || ''),
+    '  repo      ' + (plan.metadata?.repository_id || 'unknown'),
+    '  revision  ' + (plan.metadata?.revision || 'uncommitted/unknown'),
+    '  progress  ' + plan.tasks_done + '/' + plan.tasks_total + ' complete - ' + plan.tasks_blocked + ' blocked',
+  ];
+  if (plan.tasks?.length) {
+    lines.push('', '  steps');
+    for (const step of plan.tasks) {
+      const marker = step.status === 'complete' ? '[x]' : step.status === 'blocked' ? '[!]' : step.status === 'running' ? '[>]' : '[ ]';
+      lines.push('    ' + marker + ' ' + step.id + '  [' + step.status + '] ' + step.title);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function help() {
+  console.log([
+    '',
+    'agentsam plan - durable project-local work plans',
+    '',
+    '  agentsam plan new "<title>" [--goal "..."] [--type feature|sprint|refactor|incident|daily|run]',
+    '  agentsam plan list [--all] [--json]',
+    '  agentsam plan show [current|PLAN_ID] [--json]',
+    '  agentsam plan next [--plan PLAN_ID] [--start] [--json]',
+    '  agentsam plan add "<step>" [--plan PLAN_ID] [--kind inspect|implement|verify|deploy|decision] [--acceptance "..."]',
+    '  agentsam plan evidence TODO_ID --type TYPE --ref REF [--note "..."]',
+    '  agentsam plan accept TODO_ID "<criterion>" [--evidence REF]',
+    '  agentsam plan depends TODO_ID DEPENDENCY_ID',
+    '  agentsam plan start TODO_ID',
+    '  agentsam plan done TODO_ID',
+    '  agentsam plan block TODO_ID [--reason "..."]',
+    '  agentsam plan cancel TODO_ID',
+    '  agentsam plan complete [PLAN_ID]',
+    '  agentsam plan abandon [PLAN_ID]',
+    '',
+    'Existing domain plan:',
+    '  agentsam plan brand [--goap] [--json] [--write]',
+    '',
+  ].join('\n'));
+}
+
+export async function runPlan(argv = []) {
+  const opts = parse(argv);
+  const [sub, ...rest] = opts._;
+  if (!sub || sub === 'help' || opts.help) return help();
+  if (sub === 'brand') {
+    return runBrand(['plan', ...rest, ...(opts.json ? ['--json'] : []), ...(opts.goap ? ['--goap'] : []), ...(opts.write ? ['--write'] : [])]);
+  }
+
+  const ctx = openPlanLedger(process.cwd());
+  try {
+    let result;
+    if (sub === 'new') {
+      result = createPlan(ctx, {
+        title: rest.join(' '),
+        goal: opts.goal,
+        planType: opts.type || 'feature',
+        tokenBudget: opts.budget ? Number(opts.budget) : null,
+      });
+    } else if (sub === 'list') {
+      result = listPlans(ctx, { all: Boolean(opts.all) });
+    } else if (sub === 'show') {
+      result = getPlan(ctx, rest[0] || 'current');
+    } else if (sub === 'next') {
+      result = getNextPlanStep(ctx, { planId: opts.plan || 'current', start: Boolean(opts.start) });
+    } else if (sub === 'add') {
+      result = addPlanStep(ctx, {
+        planId: opts.plan || 'current',
+        title: rest.join(' '),
+        description: opts.description || null,
+        priority: opts.priority || 'medium',
+        kind: opts.kind || 'work',
+        tokenBudget: opts.budget ? Number(opts.budget) : null,
+        requiresApproval: Boolean(opts.approval),
+        acceptance: opts.acceptance ? [{ criterion: String(opts.acceptance), required: true, status: 'pending' }] : [],
+      });
+    } else if (sub === 'evidence') {
+      if (!rest[0]) throw new Error('TODO_ID is required');
+      result = addPlanStepEvidence(ctx, rest[0], { type: opts.type, ref: opts.ref, note: opts.note, hash: opts.hash });
+    } else if (sub === 'accept') {
+      if (!rest[0]) throw new Error('TODO_ID is required');
+      result = acceptPlanStep(ctx, rest[0], rest.slice(1).join(' '), { evidenceRef: opts.evidence || null });
+    } else if (sub === 'depends') {
+      if (!rest[0] || !rest[1]) throw new Error('TODO_ID and DEPENDENCY_ID are required');
+      result = addPlanDependency(ctx, rest[0], rest[1]);
+    } else if (['start', 'done', 'block', 'cancel'].includes(sub)) {
+      const taskId = rest[0];
+      if (!taskId) throw new Error('TODO_ID is required');
+      const status = { start: 'running', done: 'complete', block: 'blocked', cancel: 'cancelled' }[sub];
+      result = setPlanStepStatus(ctx, taskId, status, { reason: opts.reason || null });
+    } else if (sub === 'complete' || sub === 'abandon') {
+      result = setPlanStatus(ctx, rest[0] || 'current', sub === 'complete' ? 'complete' : 'abandoned');
+    } else {
+      return help();
+    }
+
+    if (opts.json) console.log(JSON.stringify(result, null, 2));
+    else if (sub === 'list') {
+      if (!result.length) console.log('\nNo local plans for this repository.\n');
+      else {
+        console.log('\nAgentSam plans\n');
+        for (const plan of result) console.log('  ' + plan.id + '  [' + plan.status + '] ' + plan.title + '  ' + plan.tasks_done + '/' + plan.tasks_total);
+        console.log('');
+      }
+    } else if (sub === 'next') {
+      if (!result.step) {
+        console.log('\nNo executable open step. Check dependencies or plan completion.\n');
+      } else {
+        console.log([
+          '',
+          'Next executable step',
+          '',
+          '  ' + result.step.id,
+          '  ' + result.step.title,
+          '',
+          '  kind       ' + (result.step.metadata?.kind || 'work'),
+          '  priority   ' + result.step.priority,
+          '  plan       ' + result.plan.title,
+          '  depends    ' + (result.depends_on.length ? result.depends_on.join(', ') : 'none'),
+          '  status     ' + result.step.status,
+          '  evidence   ' + result.evidence.length,
+          '  acceptance ' + result.acceptance.length,
+          '',
+          '  Recommended',
+          '    ' + result.recommended_action,
+          '',
+        ].join('\n'));
+      }
+    } else if (['add','evidence','accept','depends'].includes(sub) || ['start', 'done', 'block', 'cancel'].includes(sub)) {
+      console.log('\n  ' + result.id + '  [' + result.status + '] ' + result.title + '\n');
+    } else {
+      console.log(renderPlan(result));
+    }
+    return result;
+  } finally {
+    ctx.close();
+  }
+}

package/src/commands/security.js

@@ -1,5 +1,4 @@
 import fs from 'node:fs';
-import { scanProjectSecurity, reportExitCode, repairProject, formatSecurityReport } from '../security/index.js';
 import { runProcess } from '../security/process.js';
 import { diagnosticFromError, renderDiagnosticError } from '../errors/index.js';
 
@@ -19,6 +18,54 @@ const help = [
   'Exit: 0 clean/verified, 1 unresolved findings or command failure, 2 incomplete/error.',
   ''
 ].join('\n');
+
+async function loadSecurityModules() {
+  // Deferred until after any pre-install child command (e.g. npm ci) so the
+  // Merkle/TypeScript trust-boundary stack is not required before dependencies exist.
+  return import('../security/index.js');
+}
+
+/** Bootstrap-safe receipt when the child install/build command fails — never import the heavy scan stack. */
+function bootstrapSafeCommandFailureReceipt(result, childArgs) {
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  return {
+    schema_version: 1,
+    ok: false,
+    complete: true,
+    status: 'command-failed',
+    command: childArgs,
+    command_exit_code: result.code,
+    signal: result.signal || null,
+    stdout,
+    stderr,
+    log: stdout + (stdout && stderr ? '\n' : '') + stderr,
+    issues: [`Child command exited with code ${result.code}`],
+    findings: [],
+    results: [],
+    dependency_count: 0,
+    checked_count: 0,
+    dependency_complete: false,
+  };
+}
+
+function formatCommandFailureReport(report) {
+  const lines = [
+    'Agent Sam · security · COMMAND-FAILED',
+    '',
+    'Command: ' + (Array.isArray(report.command) ? report.command.join(' ') : String(report.command || '')),
+    'Exit code: ' + String(report.command_exit_code),
+  ];
+  if (report.signal) lines.push('Signal: ' + report.signal);
+  for (const issue of report.issues || []) lines.push('  ! ' + issue);
+  if (report.stderr) {
+    lines.push('', 'stderr:', report.stderr.trimEnd());
+  } else if (report.stdout) {
+    lines.push('', 'stdout:', report.stdout.trimEnd());
+  }
+  return lines.join('\n') + '\n';
+}
+
 export async function runSecurity(argv) {
   const ownArgs = argv.slice(0, argv.indexOf('--') < 0 ? argv.length : argv.indexOf('--'));
   if (ownArgs.includes('--help') || ownArgs.includes('-h') || !argv.length) { process.stdout.write(help); return; }
@@ -52,13 +99,29 @@ export async function runSecurity(argv) {
     const abort = () => controller.abort();
     process.once('SIGINT', abort); process.once('SIGTERM', abort);
     let report;
+    let reportExitCode;
+    let formatSecurityReport;
     try {
       if (command === 'run') {
         const result = await runProcess(childArgs[0], childArgs.slice(1), { cwd: options.projectRoot || process.cwd(), signal: options.signal });
-        report = await scanProjectSecurity({ ...options, log: result.stdout + '\n' + result.stderr });
+        // Child failure must surface as command-failed without importing Merkle/TypeScript.
+        if (result.code !== 0) {
+          report = bootstrapSafeCommandFailureReceipt(result, childArgs);
+          process.stdout.write(options.json ? JSON.stringify(report, null, 2) + '\n' : formatCommandFailureReport(report));
+          process.exitCode = 1;
+          return;
+        }
+        const security = await loadSecurityModules();
+        reportExitCode = security.reportExitCode;
+        formatSecurityReport = security.formatSecurityReport;
+        report = await security.scanProjectSecurity({ ...options, log: result.stdout + '\n' + result.stderr });
         report.command_exit_code = result.code;
-        if (result.code) { report.ok = false; report.status = 'command-failed'; }
-      } else report = command === 'repair' ? await repairProject(options) : await scanProjectSecurity(options);
+      } else {
+        const security = await loadSecurityModules();
+        reportExitCode = security.reportExitCode;
+        formatSecurityReport = security.formatSecurityReport;
+        report = command === 'repair' ? await security.repairProject(options) : await security.scanProjectSecurity(options);
+      }
     } finally {
       process.removeListener('SIGINT', abort); process.removeListener('SIGTERM', abort);
     }