@joenandez/academy 0.4.0-rc.1

package/scripts/cli/inspect.mjs

@@ -0,0 +1,286 @@
+import { existsSync, lstatSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  AGENTS_ROOT,
+  CLI_NAME,
+  ENFORCED_SURFACES,
+  NAME_RE,
+  SURFACES,
+  SURFACE_CAPS,
+  TOTAL_SURFACE_CAP,
+  agentDir,
+  checkAgentsRoot,
+  contractOk,
+  exitJsonError,
+  validateName,
+} from './core.mjs';
+import { archivedAgentDir, archivedAgentNames, assertNotArchived } from './archived.mjs';
+import { assertContainedAgentDir } from './lifecycle.mjs';
+import { readEventLogWatermark } from './eventlog.mjs';
+import { readRuntimeProvider, runtimeProviderOrNull } from './runtime.mjs';
+import { academySystemPromptPath, buildAcademySystemPrompt, tokenRecord } from './scaffold.mjs';
+import { readAgentYaml } from './yaml.mjs';
+
+export function listAgents() {
+  const entries = agentNames();
+  if (entries.length === 0 && archivedAgentNames().length === 0) {
+    console.log(`(no agents yet — try \`${CLI_NAME} hire\` or \`${CLI_NAME} create <name>\`)`);
+    return;
+  }
+  for (const name of entries) printRosterLine(name, agentDir(name), '');
+  for (const name of archivedAgentNames()) {
+    printRosterLine(name, archivedAgentDir(name), '(archived) ');
+  }
+}
+
+function printRosterLine(name, dir, prefix) {
+  const role = readAgentYaml(dir).role || '(no role set)';
+  console.log(`  ${(prefix + name).padEnd(20)} ${role}`);
+}
+
+// The watermark is read before the roster, and that order is the contract. Read
+// after, an agent created between the two reads would be missing from the
+// roster and below the watermark, so no later `events --since` could ever
+// deliver it. Read before, the same agent is in the roster and its event is
+// re-delivered, which the client's seq dedup absorbs.
+//
+// `agents` is the working roster and `archived` names what it leaves out. An
+// archived agent that simply vanished would be indistinguishable from a deleted
+// one, and this is the documented re-sync path after a replay gap.
+export function listAgentsJson() {
+  const { lastSeq, logId } = readEventLogWatermark();
+  contractOk('list', {
+    agents: agentNames().map((name) => agentRecord(name)),
+    archived: archivedAgentNames().map((name) =>
+      agentRecord(name, { dir: archivedAgentDir(name) }),
+    ),
+    lastSeq,
+    logId,
+  });
+}
+
+// The single directory-listing entry point for the agents root. The root audit
+// runs first so an unusable root is reported rather than read as empty.
+// Name-filtering before the stat keeps the archive, lock, and delete-quarantine
+// dot-directories out of the roster, and the guarded stat lets an entry deleted
+// mid-scan disappear quietly instead of throwing a non-envelope stack trace.
+function agentNames() {
+  if (!checkAgentsRoot().exists) return [];
+  return readAgentsRoot().filter(isAgentDirectory).sort();
+}
+
+// A root that passed the audit but cannot be listed is not a usable root, and
+// reporting it empty would tell a re-syncing client to drop its whole roster.
+function readAgentsRoot() {
+  try {
+    return readdirSync(AGENTS_ROOT);
+  } catch (error) {
+    exitJsonError('unsafe_agent_path', `AGENTS_ROOT cannot be listed: ${error.message}`, {
+      agentsRoot: resolve(AGENTS_ROOT),
+    });
+    return [];
+  }
+}
+
+// lstat, not stat: a symlinked entry is not an agent Academy owns, and `delete`
+// rejects it as unsafe. Listing it would make the two commands disagree.
+export function isAgentDirectory(entry) {
+  if (!NAME_RE.test(entry)) return false;
+  try {
+    return lstatSync(join(AGENTS_ROOT, entry)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// `strictRuntime` is the difference between a roster and an answer. The roster
+// degrades per agent so one unparseable `runtime:` cannot hide the healthy
+// agents beside it — `list` is the documented re-sync path, and a client locked
+// out of it has no recovery left. A direct question about one agent raises
+// instead. Neither path ever names a provider the scalar did not.
+export function agentRecord(
+  name,
+  { dir = agentDir(name), includeSurfaces = false, strictRuntime = false } = {},
+) {
+  const yaml = readAgentYaml(dir);
+  const record = {
+    name,
+    dir: resolve(dir),
+    displayName: yaml.displayName || yaml.display_name || yaml.name || name,
+    runtimeProvider: strictRuntime ? readRuntimeProvider(dir) : runtimeProviderOrNull(dir),
+  };
+  if (yaml.role) record.role = yaml.role;
+  if (includeSurfaces) record.surfaces = surfacePresence(dir);
+  return record;
+}
+
+function surfacePresence(dir) {
+  return Object.fromEntries(
+    SURFACES.map((surface) => [surface, existsSync(join(dir, `${surface}.md`))]),
+  );
+}
+
+export function inspectAgent(name, json) {
+  validateName(name);
+  checkAgentsRoot();
+  assertNotArchived(name);
+  const dir = agentDir(name);
+  if (!existsSync(dir)) {
+    const message = `Agent "${name}" not found at ${dir}`;
+    if (json) exitJsonError('agent_not_found', message, { name });
+    console.error(message);
+    process.exit(1);
+  }
+  assertContainedAgentDir(name, dir);
+
+  const record = agentRecord(name, { includeSurfaces: true, strictRuntime: true });
+  if (json) {
+    contractOk('inspect', record);
+    return;
+  }
+
+  console.log(`${record.name} (${record.runtimeProvider})`);
+  console.log(`  dir: ${record.dir}`);
+  console.log(`  displayName: ${record.displayName}`);
+  if (record.role) console.log(`  role: ${record.role}`);
+}
+
+function roundPercent(part, total) {
+  if (!total) return 0;
+  return Math.round((part / total) * 1000) / 10;
+}
+
+function promptTokenReport(name) {
+  validateName(name);
+  checkAgentsRoot();
+  assertNotArchived(name);
+  const dir = resolve(agentDir(name));
+  if (!existsSync(dir)) return { missing: true, dir };
+  assertContainedAgentDir(name, dir);
+
+  const built = buildAcademySystemPrompt(dir, name);
+  const total = tokenRecord(built.prompt);
+  const overheadText = [
+    ...built.intro,
+    ...built.surfaces.flatMap((surface) => [surface.marker, '']),
+  ].join('\n');
+  const overhead = tokenRecord(overheadText);
+  const surfaces = built.surfaces.map((surface) => {
+    const count = tokenRecord(surface.content);
+    return {
+      name: surface.name,
+      file: surface.file,
+      path: surface.path,
+      exists: surface.exists,
+      ...count,
+      percent: roundPercent(count.estimatedTokens, total.estimatedTokens),
+    };
+  });
+
+  return {
+    agent: name,
+    dir,
+    promptPath: academySystemPromptPath(dir),
+    tokenizer: 'estimated:chars-and-words-v1',
+    total,
+    overhead: {
+      ...overhead,
+      percent: roundPercent(overhead.estimatedTokens, total.estimatedTokens),
+    },
+    surfaces,
+  };
+}
+
+export function printPromptTokens(name, json) {
+  const report = promptTokenReport(name);
+  if (report.missing) {
+    const message = `Agent "${name}" not found at ${report.dir}`;
+    if (json) exitJsonError('agent_not_found', message, { name });
+    console.error(message);
+    process.exit(1);
+  }
+
+  if (json) {
+    contractOk('tokens', report);
+    return;
+  }
+
+  console.log(`${report.agent} prompt token estimate`);
+  console.log(`tokenizer: ${report.tokenizer}`);
+  console.log('');
+  console.log(
+    `${'total'.padEnd(12)} ${String(report.total.estimatedTokens).padStart(7)} tokens  ${String(report.total.chars).padStart(7)} chars`,
+  );
+  console.log(
+    `${'overhead'.padEnd(12)} ${String(report.overhead.estimatedTokens).padStart(7)} tokens  ${String(report.overhead.chars).padStart(7)} chars  ${report.overhead.percent.toFixed(1).padStart(5)}%`,
+  );
+  console.log('');
+  for (const surface of report.surfaces) {
+    console.log(
+      `${surface.name.padEnd(12)} ${String(surface.estimatedTokens).padStart(7)} tokens  ${String(surface.chars).padStart(7)} chars  ${surface.percent.toFixed(1).padStart(5)}%`,
+    );
+  }
+}
+
+export function printSurfaceBudget(name, json) {
+  const tokenReport = promptTokenReport(name);
+  if (tokenReport.missing) {
+    const message = `Agent "${name}" not found at ${tokenReport.dir}`;
+    if (json) exitJsonError('agent_not_found', message, { name });
+    console.error(message);
+    process.exit(1);
+  }
+
+  const surfaces = tokenReport.surfaces.map((surface) => {
+    const cap = SURFACE_CAPS[surface.name];
+    const overBy = Math.max(0, surface.estimatedTokens - cap);
+    return {
+      name: surface.name,
+      estimatedTokens: surface.estimatedTokens,
+      cap,
+      overBy,
+      withinCap: overBy === 0,
+      enforced: ENFORCED_SURFACES.has(surface.name),
+    };
+  });
+  const totalEstimatedTokens = surfaces.reduce((sum, surface) => sum + surface.estimatedTokens, 0);
+  const violations = surfaces.filter((surface) => !surface.withinCap);
+  const report = {
+    agent: tokenReport.agent,
+    dir: tokenReport.dir,
+    withinBudget: !violations.some((surface) => surface.enforced),
+    total: {
+      estimatedTokens: totalEstimatedTokens,
+      cap: TOTAL_SURFACE_CAP,
+      overBy: Math.max(0, totalEstimatedTokens - TOTAL_SURFACE_CAP),
+    },
+    surfaces,
+    violations,
+  };
+
+  const exitCode = report.violations.some((surface) => surface.enforced) ? 1 : 0;
+  if (json) {
+    contractOk('budget', report);
+    return;
+  }
+
+  console.log(`${report.agent} prompt budget`);
+  console.log(
+    `${'total'.padEnd(12)} ${String(report.total.estimatedTokens).padStart(7)} / ${String(report.total.cap).padStart(4)} tokens  ${report.total.overBy === 0 ? 'OK' : `OVER by ${report.total.overBy}`}`,
+  );
+  console.log('');
+  for (const surface of report.surfaces) {
+    const status = surface.withinCap ? 'OK' : `OVER by ${surface.overBy}`;
+    const mode = surface.enforced ? 'enforced' : 'advisory';
+    console.log(
+      `${surface.name.padEnd(12)} ${String(surface.estimatedTokens).padStart(7)} / ${String(surface.cap).padStart(4)} tokens  ${status}  ${mode}`,
+    );
+  }
+  console.log('');
+  console.log(exitCode === 0 ? 'PASS' : 'FAIL');
+  process.exitCode = exitCode;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `clean` — truncate transient surfaces
+// ─────────────────────────────────────────────────────────────────────────────

package/scripts/cli/lifecycle.mjs

@@ -0,0 +1,296 @@
+import { existsSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readJsonFile } from './codex.mjs';
+import {
+  AGENTS_ROOT,
+  agentDir,
+  agentLifecycleLockPath,
+  contractOk,
+  exitJsonError,
+  isInside,
+  isSymlink,
+  jsonMode,
+  LockTimeoutError,
+  RuntimeUnavailableError,
+  resolveExecutable,
+  validateAgentsRoot,
+  validateName,
+  withFileLock,
+} from './core.mjs';
+import { assertNotArchived, holdingAreaOrNull } from './archived.mjs';
+import { LogCorruptError, appendLifecycleEvent } from './eventlog.mjs';
+import { AgentSpecError } from './yaml.mjs';
+import { MUST_EXIST, helmFailureReason } from './create.mjs';
+import { TEMPLATES } from './templates.mjs';
+
+export function cleanAgent(name) {
+  validateName(name);
+  const dir = agentDir(name);
+  if (!existsSync(dir)) {
+    console.error(`Agent "${name}" not found at ${dir}`);
+    process.exit(1);
+  }
+  // Reset notes.md and threads.md to scaffolded state. Other surfaces are
+  // load-bearing (identity/role/knowledge) or natural-decay (dailys/goals/priorities).
+  const today = new Date().toISOString().slice(0, 10);
+  writeFileSync(join(dir, 'notes.md'), TEMPLATES['notes.md'](name, today));
+  writeFileSync(join(dir, 'threads.md'), TEMPLATES['threads.md'](name, today));
+  console.log(`Cleaned transient surfaces for "${name}" (notes.md, threads.md).`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `destroy` — nuke an agent (--force required)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function deleteJsonError(code, message, fields = {}, json = false) {
+  if (json) exitJsonError(code, message, fields);
+  console.error(message);
+  process.exit(1);
+}
+
+export class DeleteAgentError extends Error {
+  constructor(code, message, fields = {}) {
+    super(message);
+    this.code = code;
+    this.fields = fields;
+  }
+}
+
+// Ownership is one question, asked by every command that acts on an agent
+// directory and by `doctor` when it counts what `migrate` still has to fix.
+// It answers with the fault text, or null when the directory is owned.
+export function ownershipFault(name, dir) {
+  const markerPath = join(dir, '.academy-agent.json');
+  if (!existsSync(markerPath) || !existsSync(join(dir, 'agent.yaml'))) {
+    return `Agent "${name}" is missing Academy ownership metadata`;
+  }
+  const marker = readJsonFile(markerPath, {});
+  if (marker.capability !== 'academy-agent' || marker.name !== name) {
+    return `Agent "${name}" ownership metadata is invalid`;
+  }
+  return null;
+}
+
+// The slot an agent directory is allowed to occupy, and the whole boundary
+// once the canonical rule is relaxed. `canonical` is every command's default;
+// `archived` is the holding area, checked exactly as strictly; `contained` is
+// the delete quarantine, which sits directly inside the root under a name no
+// agent can have.
+export const SLOT = { canonical: 'canonical', archived: 'archived', contained: 'contained' };
+
+// The holding area is resolved by the one rule in archived.mjs, which every
+// read and every write now shares: an unprovable `.archived` has no slots at
+// all, so an archived agent can never resolve to some other directory.
+function archivedSlot(name) {
+  const holding = holdingAreaOrNull();
+  return holding === null ? null : join(holding, name);
+}
+
+function slotFault(name, dirReal, rootReal, slot) {
+  if (!isInside(dirReal, rootReal)) return `Agent "${name}" resolves outside AGENTS_ROOT`;
+  if (slot === SLOT.contained) return null;
+  const expected = slot === SLOT.archived ? archivedSlot(name) : join(rootReal, name);
+  if (expected === dirReal) return null;
+  return `Agent "${name}" does not occupy its ${slot} slot inside AGENTS_ROOT`;
+}
+
+// Where an agent directory is allowed to be, with no question about what is
+// inside it. Stated once, because a boundary expressed in two places is a
+// boundary that disagrees with itself the first time one end learns a rule the
+// other has not: `delete`, `rename` and `archive` ask it through
+// `ownedAgentFault` below before they move a directory, and `inspect`, `tokens`
+// and `budget` ask it directly before they publish one.
+function containmentFault(name, dir, slot) {
+  if (isSymlink(dir)) {
+    return {
+      code: 'unsafe_agent_path',
+      message: `Agent "${name}" is not an owned Academy directory: ${dir}`,
+    };
+  }
+  let rootReal;
+  let dirReal;
+  try {
+    rootReal = realpathSync(AGENTS_ROOT);
+    dirReal = realpathSync(dir);
+  } catch (error) {
+    return {
+      code: 'unsafe_agent_path',
+      message: `Agent "${name}" cannot be resolved: ${error.message}`,
+    };
+  }
+  const misplaced = slotFault(name, dirReal, rootReal, slot);
+  if (misplaced) return { code: 'unsafe_agent_path', message: misplaced };
+  return { dirReal };
+}
+
+// One rule, two reactions. `delete` exits on it before taking the lock and
+// throws on it inside; a validator stated twice is a validator that disagrees
+// with itself the first time one end learns a rule the other has not.
+function ownedAgentFault(name, dir, slot) {
+  if (!existsSync(dir)) {
+    return { code: 'agent_not_found', message: `Agent "${name}" not found at ${dir}` };
+  }
+  const contained = containmentFault(name, dir, slot);
+  if (contained.code) return contained;
+  const fault = ownershipFault(name, dir);
+  if (fault) return { code: 'not_academy_owned', message: fault };
+  return { dir, dirReal: contained.dirReal };
+}
+
+// The containment half, as the raising check a read command owes. A read moves
+// nothing, so it never asks the ownership question — an unowned directory is
+// still readable, and `migrate` is the answer to it. It asks where the slot
+// landed, because a read that follows one out of the root publishes content
+// from outside it under a `dir` field claiming to be inside.
+export function assertContainedAgentDir(name, dir, json = jsonMode()) {
+  const fault = containmentFault(name, dir, SLOT.canonical);
+  if (fault.code) deleteJsonError(fault.code, fault.message, { name }, json);
+}
+
+export function validateOwnedAgentDir(name, dir, json = false, slot = SLOT.canonical) {
+  const outcome = ownedAgentFault(name, dir, slot);
+  if (outcome.code) deleteJsonError(outcome.code, outcome.message, { name }, json);
+  return outcome;
+}
+
+// The shared preflight for `delete`, `rename` and `archive`. `unarchive` is the
+// one lifecycle command that may address an archived agent, so it preflights
+// against the holding area instead of coming through here.
+export function preflightOwnedAgent(name, json = false) {
+  validateName(name);
+  validateAgentsRoot();
+  assertNotArchived(name, json);
+  return validateOwnedAgentDir(name, agentDir(name), json);
+}
+
+export function assertOwnedAgentForDelete(name, dir, slot = SLOT.canonical) {
+  const outcome = ownedAgentFault(name, dir, slot);
+  if (outcome.code) throw new DeleteAgentError(outcome.code, outcome.message, { name });
+  return outcome;
+}
+
+export function deleteNightlyConsolidation(name, dir) {
+  const id = `${name}-nightly-consolidation`;
+  // Resolved inside the lock, so exiting here would strand the lock directory
+  // and make every later delete of this agent unanswerable.
+  let helmTasksBin;
+  try {
+    helmTasksBin = resolveExecutable('ACADEMY_HELM_TASKS_BIN', 'helm-tasks', MUST_EXIST);
+  } catch (error) {
+    if (!(error instanceof RuntimeUnavailableError)) throw error;
+    return { ok: false, id, code: error.code, reason: error.message };
+  }
+  const result = spawnSync(helmTasksBin, ['delete', '--cwd', dir, '--id', id], {
+    cwd: dirname(dir),
+    encoding: 'utf8',
+    env: process.env,
+  });
+  if (result.error) return { ok: false, id, reason: result.error.message };
+  if (result.status !== 0)
+    return {
+      ok: false,
+      id,
+      reason: helmFailureReason(result.stderr || result.stdout, result.status),
+    };
+  return { ok: true, id };
+}
+
+// The one failure path `delete`, `rename` and `archive` share. Each stated the
+// typed set itself and then printed prose and exited, so an untyped throw never
+// reached the floor in `main.mjs` — and every one of those throws happens after
+// the directory has already moved. A --json client was told the operation
+// failed, in bytes it cannot parse, about a move that stands.
+export function reportLifecycleFailure(error, verb, name, json) {
+  if (
+    error instanceof DeleteAgentError ||
+    error instanceof LockTimeoutError ||
+    error instanceof LogCorruptError ||
+    error instanceof AgentSpecError
+  ) {
+    deleteJsonError(error.code, error.message, error.fields, json);
+  }
+  // Rethrown, not printed: `main.mjs` renders `internal_error`, the floor under
+  // the envelope. A shell user keeps the prose, which is more useful at a
+  // terminal, and the stack the floor would swallow.
+  if (json) throw error;
+  console.error(`Error: failed to ${verb} agent "${name}": ${error.message}`);
+  process.exit(1);
+}
+
+export function deleteAgent(name, json) {
+  preflightOwnedAgent(name, json);
+  const lockDir = agentLifecycleLockPath(agentDir(name));
+  try {
+    withFileLock(lockDir, () => deleteAgentLocked(name, json));
+  } catch (error) {
+    reportLifecycleFailure(error, 'delete', name, json);
+  }
+}
+
+function deleteAgentLocked(name, _json) {
+  const { dir, dirReal } = assertOwnedAgentForDelete(name, agentDir(name));
+  const quarantine = join(
+    resolve(AGENTS_ROOT),
+    `.${name}.delete-quarantine.${process.pid}.${Date.now()}`,
+  );
+  renameSync(dir, quarantine);
+  assertOwnedAgentForDelete(name, quarantine, SLOT.contained);
+
+  const unscheduled = deleteNightlyConsolidation(name, dirReal);
+  if (!unscheduled.ok) {
+    if (!existsSync(dir)) {
+      renameSync(quarantine, dir);
+    } else {
+      throw new DeleteAgentError(
+        'unschedule_failed_restore_blocked',
+        `Refusing to delete "${name}" because nightly unschedule failed and ${dir} is occupied: ${unscheduled.reason}`,
+        { name, quarantine },
+      );
+    }
+    throw new DeleteAgentError(
+      unscheduled.code ?? 'unschedule_failed',
+      `Refusing to delete "${name}" because nightly unschedule failed: ${unscheduled.reason}`,
+      { name },
+    );
+  }
+  rmSync(quarantine, { recursive: true, force: false });
+  appendLifecycleEvent('agent_deleted', name, dir);
+  if (_json) {
+    // Absolute, like every other command's `dir`: a client keying agents on the
+    // field must be able to match its create record against this confirmation.
+    contractOk('delete', {
+      deleted: true,
+      name,
+      dir: resolve(dir),
+      unscheduledJobId: unscheduled.id,
+    });
+    return;
+  }
+  console.log(`Deleted agent "${name}" (removed ${dir}).`);
+}
+
+export function destroyAgent(name, force) {
+  validateName(name);
+  const dir = agentDir(name);
+  if (!existsSync(dir)) {
+    console.error(`Agent "${name}" not found at ${dir}`);
+    process.exit(1);
+  }
+  if (!force) {
+    console.error(`Refusing to destroy "${name}" without --force.`);
+    console.error(`This removes ${dir} and all its files.`);
+    process.exit(1);
+  }
+  rmSync(dir, { recursive: true, force: true });
+  console.log(`Destroyed agent "${name}" (removed ${dir}).`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `notes` — append-only micro-steering staging on an agent's notes.md
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Resolve the target agent home for a notes command. Precedence: explicit
+// <agent> arg → ACADEMY_AGENT_DIR → ACADEMY_AGENT_HOME (spec synonym) →
+// ACADEMY_AGENT_NAME → error. The *_DIR/_HOME vars are absolute agent-home
+// paths; ACADEMY_AGENT_DIR is what `academy run` exports.

package/scripts/cli/main.mjs

@@ -0,0 +1,102 @@
+import { resolve } from 'node:path';
+import { parseArgs, printUsage } from './args.mjs';
+import {
+  ACADEMY_ROOT,
+  AGENTS_ROOT,
+  CONTRACT_VERSION,
+  contractOk,
+  exitJsonError,
+  jsonMode,
+  setActiveCommand,
+} from './core.mjs';
+import { archiveAgent, unarchiveAgent } from './archive.mjs';
+import { createAgent } from './create.mjs';
+import { UNIMPLEMENTED_COMMANDS, reportHealth } from './doctor.mjs';
+import { readEvents } from './events.mjs';
+import { hireAgent } from './hire.mjs';
+import { hireFromSpec } from './hire-headless.mjs';
+import {
+  inspectAgent,
+  listAgents,
+  listAgentsJson,
+  printPromptTokens,
+  printSurfaceBudget,
+} from './inspect.mjs';
+import { cleanAgent, deleteAgent, destroyAgent } from './lifecycle.mjs';
+import { backfillOwnership } from './migrate.mjs';
+import { notesAdd, notesList } from './notes.mjs';
+import { renameAgent } from './rename.mjs';
+import { runAgent, runNightly } from './run.mjs';
+import { readSessions } from './sessions.mjs';
+
+const COMMAND_HANDLERS = {
+  ...Object.fromEntries(UNIMPLEMENTED_COMMANDS.map((command) => [command, unimplementedCommand])),
+  doctor: (parsed) => reportHealth(parsed.json),
+  help: (parsed) => {
+    printUsage();
+    process.exit(parsed.exitCode ?? 0);
+  },
+  create: (parsed) => createAgent(parsed.name, parsed.json),
+  // `--spec` is the only thing that selects the headless form; without it the
+  // interactive launch runs exactly as it always has.
+  hire: (parsed) =>
+    parsed.spec === null ? hireAgent(parsed.passthrough, parsed.json) : hireFromSpec(parsed),
+  run: (parsed) => runAgent(parsed.name, parsed.runtime, parsed.passthrough),
+  nightly: (parsed) => runNightly(parsed.name),
+  events: (parsed) => readEvents(parsed),
+  migrate: (parsed) => backfillOwnership(parsed),
+  rename: (parsed) => renameAgent(parsed.name, parsed.newName, parsed.json, parsed.invalidOption),
+  archive: (parsed) => archiveAgent(parsed.name, parsed.json),
+  unarchive: (parsed) => unarchiveAgent(parsed.name, parsed.json),
+  sessions: (parsed) => readSessions(parsed),
+  list: (parsed) => (parsed.json ? listAgentsJson() : listAgents()),
+  inspect: (parsed) => inspectAgent(parsed.name, parsed.json),
+  tokens: (parsed) => printPromptTokens(parsed.name, parsed.json),
+  budget: (parsed) => printSurfaceBudget(parsed.name, parsed.json),
+  clean: (parsed) => cleanAgent(parsed.name),
+  delete: (parsed) => deleteAgent(parsed.name, parsed.json),
+  destroy: (parsed) => destroyAgent(parsed.name, parsed.force),
+  root: (parsed) => {
+    if (parsed.json)
+      contractOk('root', { packageRoot: ACADEMY_ROOT, agentsRoot: resolve(AGENTS_ROOT) });
+    else console.log(ACADEMY_ROOT);
+  },
+  notes: (parsed) => {
+    if (parsed.action === 'add') notesAdd(parsed.name, parsed.text);
+    else notesList(parsed.name, parsed.last);
+  },
+};
+
+// `doctor` advertises the whole contract_version 1 command set, including the
+// commands later phases build. Answering those in the envelope is what keeps
+// the capability list honest: a client that calls what doctor named gets a
+// parseable failure naming the gap, not a usage dump with no contract shape.
+// `internal_error` is the floor under the envelope and the only one of the
+// fifteen codes that fits — inventing a sixteenth is not permitted.
+function unimplementedCommand(parsed) {
+  const message = `Command "${parsed.command}" is published at contract_version ${CONTRACT_VERSION} but is not implemented in this build.`;
+  if (parsed.json) exitJsonError('internal_error', message);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  setActiveCommand(parsed.command, parsed.json);
+  const handler = COMMAND_HANDLERS[parsed.command];
+  if (!handler) {
+    printUsage();
+    process.exit(1);
+  }
+  try {
+    handler(parsed);
+  } catch (error) {
+    // The floor under the envelope, not the primary handler: a --json caller
+    // gets a parseable failure for a throw no command anticipated. A shell user
+    // keeps the stack trace, which is more useful at a terminal.
+    if (!jsonMode()) throw error;
+    exitJsonError('internal_error', error.message);
+  }
+}
+
+main();