@joenandez/academy 0.4.0-rc.1

package/scripts/cli/migrate.mjs

@@ -0,0 +1,183 @@
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  AGENTS_ROOT,
+  LockTimeoutError,
+  NAME_RE,
+  agentLifecycleLockPath,
+  checkAgentsRoot,
+  contractOk,
+  exitJsonError,
+  isInside,
+  isSymlink,
+  withFileLock,
+} from './core.mjs';
+import { ownershipFault } from './lifecycle.mjs';
+import { writeOwnershipMarker } from './scaffold.mjs';
+
+const MARKER = '.academy-agent.json';
+
+// The ownership backfill. Agents scaffolded before the marker existed fail
+// every ownership-gated command, and this is the one operator-invoked repair
+// for that. It writes the marker and nothing else: it never creates an agent,
+// never rewrites agent content, and never touches a directory it cannot prove
+// is the agent's own slot inside AGENTS_ROOT.
+
+// Containment is the invariant, and it is proved against the resolved path, not
+// the joined one. A symlink inside the root pointing anywhere else — outside
+// the root, or at another agent beside it — is refused, because writing "kai"
+// ownership through it would mark a directory Academy does not own.
+function slotFault(dirReal, rootReal, name) {
+  if (!isInside(dirReal, rootReal)) return `resolves outside AGENTS_ROOT: ${dirReal}`;
+  if (dirReal !== join(rootReal, name)) {
+    return `resolves to another directory inside AGENTS_ROOT: ${dirReal}`;
+  }
+  return null;
+}
+
+// Guarded rather than raised: `doctor` counts the outstanding backfill through
+// this same plan and must never exit from inside a probe.
+function rootEntries(root) {
+  try {
+    return readdirSync(root)
+      .filter((entry) => NAME_RE.test(entry))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+// Containment is proved for the directory; the marker is a second path and
+// needs its own proof. `existsSync` follows symlinks, so a dangling or non-JSON
+// symlink at the marker reads as "no marker", and `writeFileSync` then opens
+// with O_TRUNC and follows the link to whatever it names. Asked before
+// ownership on purpose: a marker symlinked at a valid file outside the root
+// would otherwise pass the gate silently instead of being reported.
+function markerFault(dirReal) {
+  const markerPath = join(dirReal, MARKER);
+  if (isSymlink(markerPath)) return `ownership marker is a symlink: ${markerPath}`;
+  return null;
+}
+
+function classify(root, rootReal, name) {
+  const dir = join(root, name);
+  let dirReal;
+  try {
+    dirReal = realpathSync(dir);
+  } catch (error) {
+    return { refused: { name, dir, reason: `cannot be resolved: ${error.message}` } };
+  }
+  const fault = slotFault(dirReal, rootReal, name);
+  if (fault) return { refused: { name, dir, reason: fault } };
+  // Not an agent directory, so not a repair. Marking a directory holding no
+  // agent.yaml would create an agent, which the backfill must never do.
+  if (!statSync(dirReal).isDirectory()) return {};
+  if (!existsSync(join(dirReal, 'agent.yaml'))) return {};
+  const marker = markerFault(dirReal);
+  if (marker) return { refused: { name, dir, reason: marker } };
+  if (ownershipFault(name, dirReal) === null) return {};
+  // dirReal is carried, not recomputed at the write: joining the unvalidated
+  // path again would traverse the same symlink chain a second time and land
+  // somewhere the classification never proved.
+  return { repair: { name, dir, dirReal } };
+}
+
+// The one enumeration. `migrate` repairs exactly this set and `doctor` counts
+// exactly this set, so the reported outstanding count and the repair can never
+// disagree.
+export function backfillPlan() {
+  const root = resolve(AGENTS_ROOT);
+  let rootReal = root;
+  try {
+    rootReal = realpathSync(root);
+  } catch {
+    /* an unresolvable root yields no candidates */
+  }
+  const repair = [];
+  const refused = [];
+  for (const name of rootEntries(root)) {
+    const outcome = classify(root, rootReal, name);
+    if (outcome.repair) repair.push(outcome.repair);
+    if (outcome.refused) refused.push(outcome.refused);
+  }
+  return { agentsRoot: root, rootReal, repair, refused };
+}
+
+// The whole root is classified before the first write, so the last write lands
+// long after its entry was judged. The lock serialises the commands; it does
+// not revalidate, so the entry is classified again inside it and skipped when
+// it no longer qualifies.
+function writeOneMarker(root, rootReal, { name, dir }) {
+  return withFileLock(agentLifecycleLockPath(dir), () => {
+    const current = classify(root, rootReal, name);
+    if (current.refused) return current;
+    if (!current.repair) return { skipped: true };
+    writeOwnershipMarker(current.repair.dirReal, name);
+    return { written: true };
+  });
+}
+
+// One unwritable directory is one refusal, not an abandoned sweep. The operator
+// asked for every outstanding marker and has to learn which ones landed, and
+// `refused[]` is the channel the payload already publishes for exactly that.
+// Only a lock timeout escapes: it is the one fault that fails the command.
+function writeMarkers(plan) {
+  const migrated = [];
+  for (const entry of plan.repair) {
+    let outcome;
+    try {
+      outcome = writeOneMarker(plan.agentsRoot, plan.rootReal, entry);
+    } catch (error) {
+      if (error instanceof LockTimeoutError) throw error;
+      outcome = { refused: { name: entry.name, dir: entry.dir, reason: error.message } };
+    }
+    if (outcome.written) migrated.push(entry);
+    if (outcome.refused) plan.refused.push(outcome.refused);
+  }
+  return migrated;
+}
+
+export function backfillOwnership({ json, dryRun, invalidOption }) {
+  if (invalidOption !== undefined) return unreadableInvocation(invalidOption, json);
+  checkAgentsRoot(json);
+  const plan = backfillPlan();
+  let migrated = plan.repair;
+  try {
+    if (!dryRun) migrated = writeMarkers(plan);
+  } catch (error) {
+    if (!(error instanceof LockTimeoutError)) throw error;
+    if (json) exitJsonError(error.code, error.message, error.fields);
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+  if (json) {
+    contractOk('migrate', {
+      agentsRoot: plan.agentsRoot,
+      dryRun: Boolean(dryRun),
+      migrated: migrated.map(published),
+      refused: plan.refused,
+    });
+    return;
+  }
+  printBackfill(plan, migrated, dryRun);
+}
+
+// The resolved directory the write targets is internal. A published record
+// carries the two keys it always carried.
+function published({ name, dir }) {
+  return { name, dir };
+}
+
+function unreadableInvocation(option, json) {
+  const message = `Unknown migrate option: ${option}. Use [--dry-run] [--json].`;
+  if (json) exitJsonError('invalid_spec', message, { option });
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function printBackfill(plan, migrated, dryRun) {
+  const verb = dryRun ? 'would write' : 'wrote';
+  console.log(`migrate ${plan.agentsRoot}: ${verb} ${migrated.length} ownership marker(s)`);
+  for (const { name, dir } of migrated) console.log(`  marker  ${name}  ${dir}`);
+  for (const entry of plan.refused) console.log(`  refused ${entry.name}  ${entry.reason}`);
+}

package/scripts/cli/notes.mjs

@@ -0,0 +1,104 @@
+import { appendFileSync, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { AGENTS_ROOT, CLI_NAME, agentDir, isInside, validateName } from './core.mjs';
+import { ownershipFault } from './lifecycle.mjs';
+
+// `notes` is not a published contract command, so it has no envelope to answer
+// in. It still names the published code for the fault: the containment defect
+// is real whether or not the command is contract, and an operator reading
+// stderr needs the same vocabulary every other command uses.
+function notesFault(code, message) {
+  console.error(`Error: ${code}: ${message}`);
+  process.exit(1);
+}
+
+// The identity gate. ACADEMY_AGENT_DIR arrives from the environment, which is
+// not a source Academy can verify, so an accepted directory must prove both
+// that it resolves inside AGENTS_ROOT and that Academy owns it. Without this,
+// `notes add` is an arbitrary append under an identity nobody checked.
+// `migrate` is the repair path for an agent scaffolded before the marker.
+function containedAgentDir(candidate) {
+  const dir = resolve(candidate);
+  if (!isInside(dir, AGENTS_ROOT)) {
+    notesFault('unsafe_agent_path', `agent directory resolves outside AGENTS_ROOT: ${dir}`);
+  }
+  let real;
+  try {
+    real = realpathSync(dir);
+  } catch {
+    // Not there at all. `ensureAgentHome` is the second gate and says so.
+    return dir;
+  }
+  const fault = ownershipFault(basename(real), real);
+  if (fault) notesFault('not_academy_owned', `${fault} at ${real}`);
+  return real;
+}
+
+function namedAgentDir(name) {
+  validateName(name);
+  return containedAgentDir(agentDir(name));
+}
+
+function resolveNotesAgentDir(explicitName) {
+  if (explicitName) return namedAgentDir(explicitName);
+  const home = process.env.ACADEMY_AGENT_DIR || process.env.ACADEMY_AGENT_HOME;
+  if (home) return containedAgentDir(home);
+  if (process.env.ACADEMY_AGENT_NAME) return namedAgentDir(process.env.ACADEMY_AGENT_NAME);
+  console.error(`Error: no agent resolved for \`${CLI_NAME} notes\`.`);
+  console.error('Pass an agent name, or run inside an agent so ACADEMY_AGENT_DIR is set.');
+  console.error(
+    `Usage: ${CLI_NAME} notes add [<agent>] "text"  |  ${CLI_NAME} notes list [<agent>] [--last N]`,
+  );
+  process.exit(1);
+}
+
+function ensureAgentHome(dir) {
+  if (!existsSync(dir)) {
+    console.error(`Agent home not found at ${dir}`);
+    process.exit(1);
+  }
+  return dir;
+}
+
+// Local-time stamp `YYYY-MM-DD HH:MM` (not UTC — spec §Appended Format).
+function localNoteStamp(d = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+export function notesAdd(name, text) {
+  if (!text || !text.trim()) {
+    console.error('Error: note text required.');
+    console.error(`Usage: ${CLI_NAME} notes add [<agent>] "text"`);
+    process.exit(1);
+  }
+  const dir = ensureAgentHome(resolveNotesAgentDir(name));
+  const notesPath = join(dir, 'notes.md');
+  // Append-only: never read or rewrite the whole file (spec §Behavior).
+  appendFileSync(notesPath, `- ${localNoteStamp()}: ${text}\n`);
+  console.log(`Noted → ${notesPath}`);
+}
+
+export function notesList(name, last) {
+  const dir = ensureAgentHome(resolveNotesAgentDir(name));
+  const notesPath = join(dir, 'notes.md');
+  if (!existsSync(notesPath)) {
+    console.log('(no notes yet)');
+    return;
+  }
+  // A note bullet is a top-level `- ` line — excludes headers, `_(…)_` italics,
+  // and `---` rules in the scaffold.
+  const bullets = readFileSync(notesPath, 'utf8')
+    .split('\n')
+    .filter((line) => line.startsWith('- '));
+  const recent = bullets.slice(-last);
+  if (recent.length === 0) {
+    console.log('(no notes yet)');
+    return;
+  }
+  console.log(recent.join('\n'));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────────────────

package/scripts/cli/rename.mjs

@@ -0,0 +1,172 @@
+import { existsSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readJsonFile } from './codex.mjs';
+import {
+  agentDir,
+  agentLifecycleLockPath,
+  contractOk,
+  exitJsonError,
+  validateName,
+  withFileLock,
+} from './core.mjs';
+import { archivedAgentDir, assertNotArchived, isArchivedAgent } from './archived.mjs';
+import { registerNightlyConsolidationTask } from './create.mjs';
+import { appendLifecycleEvent } from './eventlog.mjs';
+import { agentRecord } from './inspect.mjs';
+import {
+  DeleteAgentError,
+  assertOwnedAgentForDelete,
+  deleteJsonError,
+  deleteNightlyConsolidation,
+  preflightOwnedAgent,
+  reportLifecycleFailure,
+} from './lifecycle.mjs';
+import { AgentSpecError, rewriteAgentYamlScalar } from './yaml.mjs';
+
+// `rename <old> <new>`. The ownership marker is the blocker: both validators
+// reject a directory whose marker names another agent, so a rename that moved
+// the directory without rewriting `.academy-agent.json` would leave the agent
+// permanently `not_academy_owned` — no delete, no archive, no second rename.
+// The move, the marker and the `name:` scalar are therefore one critical
+// section, and the lock is taken exactly once around all three.
+
+export function renameAgent(name, newName, json, invalidOption) {
+  if (invalidOption !== undefined) return unreadableInvocation(invalidOption, json);
+  preflightOwnedAgent(name, json);
+  validateName(newName);
+  // The target name is asked the same two questions `create` asks it, and for
+  // the same reason `create` asks them: a live agent moved onto a name the
+  // holding area already owns leaves two records under one name, and every
+  // published command then answers `agent_archived` for the live one. No
+  // published command can reach it again.
+  assertNotArchived(newName, json);
+  refuseExistingTarget(newName, json);
+  try {
+    withFileLock(agentLifecycleLockPath(agentDir(name)), () =>
+      renameAgentLocked(name, newName, json),
+    );
+  } catch (error) {
+    reportLifecycleFailure(error, 'rename', name, json);
+  }
+}
+
+// Refused before the lock is taken, because every exit path here ends the
+// process and a lock released by nothing would strand the agent for good.
+function refuseExistingTarget(newName, json) {
+  const target = agentDir(newName);
+  if (!existsSync(target)) return;
+  deleteJsonError(
+    'agent_exists',
+    `Agent "${newName}" already exists at ${resolve(target)}`,
+    { name: newName, dir: resolve(target) },
+    json,
+  );
+}
+
+function renameAgentLocked(name, newName, json) {
+  const { dirReal } = assertOwnedAgentForDelete(name, agentDir(name));
+  // Reported as the absolute joined path, never the realpath: a client keying
+  // agents on `dir` matches this against the record `create` gave it.
+  const previousDir = resolve(agentDir(name));
+  const target = agentDir(newName);
+  if (existsSync(target)) {
+    throw new DeleteAgentError(
+      'agent_exists',
+      `Agent "${newName}" already exists at ${resolve(target)}`,
+      { name: newName, dir: resolve(target) },
+    );
+  }
+  refuseArchivedTarget(newName);
+  // Named by the joined path, like every other path this command reports.
+  assertRewritableAgentYaml(previousDir);
+
+  // Unschedule before the move. Registration replaces on the *new* identifier,
+  // so an old job left behind would fire nightly against a directory that has
+  // moved, forever.
+  const unscheduled = deleteNightlyConsolidation(name, dirReal);
+  if (!unscheduled.ok) {
+    throw new DeleteAgentError(
+      unscheduled.code ?? 'unschedule_failed',
+      `Refusing to rename "${name}" because nightly unschedule failed: ${unscheduled.reason}`,
+      { name },
+    );
+  }
+
+  renameSync(dirReal, target);
+  rewriteOwnershipMarker(target, newName);
+  // The unlocked writer: this section already holds the agent's lifecycle lock,
+  // and `writeAgentYamlScalar` would take the same lock again and time out.
+  rewriteAgentYamlScalar(target, 'name', newName);
+  assertOwnedAgentForDelete(newName, target);
+  const nightly = registerNightlyConsolidationTask(target, newName);
+
+  // The move is complete and consistent by here. An append failure is reported
+  // and the move stands, as `createAgent` reports a failed publish: unwinding a
+  // rename whose old scheduled job is already gone would lose more than it
+  // repairs.
+  appendLifecycleEvent('agent_renamed', newName, resolve(target), {
+    previousName: name,
+    previousDir,
+  });
+  reportRenamed({ name, newName, previousDir, target, unscheduled, nightly, json });
+}
+
+// Mirrored inside the lock exactly as `existsSync(target)` is mirrored above:
+// an agent archived between the preflight and the lock must not be overwritten
+// by a rename that checked before the holding area claimed the name.
+function refuseArchivedTarget(newName) {
+  if (!isArchivedAgent(newName)) return;
+  const dir = resolve(archivedAgentDir(newName));
+  throw new DeleteAgentError(
+    'agent_archived',
+    `Agent "${newName}" is archived at ${dir}. Unarchive it first.`,
+    { name: newName, dir },
+  );
+}
+
+// The `name:` scalar is rewritten after the move, so a rewrite that throws
+// there leaves the directory moved, the marker rewritten, the old nightly job
+// unregistered, the new one never registered and no `agent_renamed` event
+// appended — while the client is told the rename failed. Proved rewritable
+// before any of it, the same refusal costs nothing.
+function assertRewritableAgentYaml(dir) {
+  const path = join(dir, 'agent.yaml');
+  if (statSync(path).isFile()) return;
+  throw new AgentSpecError(`agent.yaml at ${path} is not a regular file Academy can rewrite.`, {
+    path,
+  });
+}
+
+// The marker is rewritten, not rewritten from scratch: `createdAt` records when
+// the agent was hired, which a rename does not change.
+function rewriteOwnershipMarker(dir, name) {
+  const path = join(dir, '.academy-agent.json');
+  const marker = readJsonFile(path, {});
+  writeFileSync(path, `${JSON.stringify({ ...marker, name }, null, 2)}\n`);
+}
+
+function reportRenamed({ name, newName, previousDir, target, unscheduled, nightly, json }) {
+  const scheduledJobId = nightly.registered ? nightly.id : null;
+  if (json) {
+    contractOk('rename', {
+      renamed: true,
+      ...agentRecord(newName),
+      previousName: name,
+      previousDir,
+      unscheduledJobId: unscheduled.id,
+      scheduledJobId,
+    });
+    return;
+  }
+  console.log(`Renamed agent "${name}" to "${newName}" (${previousDir} → ${resolve(target)}).`);
+  console.log(`Unregistered nightly consolidation job "${unscheduled.id}".`);
+  if (scheduledJobId) console.log(`Registered nightly consolidation job "${scheduledJobId}".`);
+  else console.log(`Nightly consolidation job not registered: ${nightly.reason}`);
+}
+
+function unreadableInvocation(option, json) {
+  const message = `Unknown rename option: ${option}. Use rename <old> <new> [--json].`;
+  if (json) exitJsonError('invalid_spec', message, { option });
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}

package/scripts/cli/run.mjs

@@ -0,0 +1,227 @@
+import { existsSync, unlinkSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pendingMarkerPath } from '../../hooks/memory_store.mjs';
+import {
+  codexRuntimeContextPath,
+  launchCodex,
+  readJsonFile,
+  writeCodexHooks,
+  writeCodexProfile,
+} from './codex.mjs';
+import {
+  CLI_NAME,
+  ACADEMY_CLI_PATH,
+  SCHEDULED_CLAUDE_PERMISSION_ARGS,
+  SCHEDULED_CODEX_PERMISSION_ARGS,
+  LockTimeoutError,
+  agentDir,
+  delegateLegacyRun,
+  isInside,
+  legacyAcademyRoot,
+  validateName,
+} from './core.mjs';
+import { registerNightlyConsolidationTask } from './create.mjs';
+import { launchClaude } from './hire.mjs';
+import { readRuntimeProvider, toRuntimeProvider, toRuntimeToken } from './runtime.mjs';
+import { AgentSpecError, writeAgentYamlScalar } from './yaml.mjs';
+import {
+  renderAcademySystemPrompt,
+  writeProjectCodexSkillBridge,
+  writeProjectPluginInstance,
+  writeSkillsScaffold,
+} from './scaffold.mjs';
+
+// The agent's runtime is only knowable once the agent is resolved. A bare run
+// reads what the agent already declared, so it can neither launch the wrong
+// provider nor re-register the nightly job under one. Only an explicit --agent
+// is a decision, and only a decision is persisted.
+function resolveRuntime(dir, requested) {
+  if (!requested) return toRuntimeToken(readRuntimeProvider(dir));
+  persistRuntime(dir, requested);
+  return requested;
+}
+
+// `run` is outside the envelope, so the durable write's typed failures are
+// rendered the way every other run failure is: one actionable line. Anything
+// untyped still throws, because a run has no envelope to hide it in.
+function persistRuntime(dir, requested) {
+  try {
+    writeAgentYamlScalar(dir, 'runtime', toRuntimeProvider(requested));
+  } catch (error) {
+    const typed = error instanceof LockTimeoutError || error instanceof AgentSpecError;
+    if (!typed) throw error;
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+function prepareAgentRun(name, requestedRuntime, passthrough) {
+  validateName(name);
+  const dir = agentDir(name);
+  if (!existsSync(dir)) {
+    console.error(`Agent "${name}" not found at ${dir}`);
+    console.error(`Run \`${CLI_NAME} create ${name}\` or \`${CLI_NAME} hire\` first.`);
+    process.exit(1);
+  }
+
+  const legacyRoot = legacyAcademyRoot(dir);
+  if (legacyRoot) {
+    delegateLegacyRun(name, passthrough, legacyRoot);
+    return null;
+  }
+
+  const runtime = resolveRuntime(dir, requestedRuntime);
+  writeSkillsScaffold(dir, name);
+  const systemPromptPath = renderAcademySystemPrompt(dir, name);
+  const projectDir = resolve(process.cwd());
+  const inAgentHome = isInside(projectDir, dir);
+  const codex =
+    runtime === 'codex'
+      ? { ...writeCodexProfile(dir, name), runtimeContextPath: codexRuntimeContextPath() }
+      : undefined;
+  if (codex) writeCodexHooks(codex.runtimeContextPath);
+  const nightlyTask = registerNightlyConsolidationTask(dir, name);
+  if (!nightlyTask.registered && process.env.ACADEMY_SKIP_NIGHTLY_TASK !== '1') {
+    console.error(
+      `Warning: nightly consolidation job "${nightlyTask.id}" not updated: ${nightlyTask.reason}`,
+    );
+  }
+
+  const env = {
+    ...process.env,
+    ACADEMY_AGENT_DIR: dir,
+    ACADEMY_AGENT_NAME: name,
+  };
+  return { codex, dir, env, inAgentHome, name, passthrough, projectDir, runtime, systemPromptPath };
+}
+
+function launchInAgentHome(context) {
+  const { codex, dir, env, name, passthrough, systemPromptPath } = context;
+  if (!codex) {
+    launchClaude(['--system-prompt-file', systemPromptPath, ...passthrough], {
+      cwd: dir,
+      env,
+      message: `Launching ${name} with Claude Code in agent home (${dir})`,
+    });
+    return;
+  }
+  launchCodex(
+    [
+      '--profile',
+      codex.profileName,
+      '-C',
+      dir,
+      '--add-dir',
+      dir,
+      '-c',
+      `model_instructions_file=${JSON.stringify(systemPromptPath)}`,
+      ...passthrough,
+    ],
+    { cwd: dir, env, message: `Launching ${name} with Codex in agent home (${dir})`, ...codex },
+  );
+}
+
+function launchInProject(context) {
+  const { codex, dir, env, name, passthrough, projectDir, systemPromptPath } = context;
+  if (codex) {
+    writeProjectCodexSkillBridge(projectDir, dir);
+    launchCodex(
+      [
+        '--profile',
+        codex.profileName,
+        '-C',
+        projectDir,
+        '--add-dir',
+        dir,
+        '-c',
+        `model_instructions_file=${JSON.stringify(systemPromptPath)}`,
+        ...passthrough,
+      ],
+      {
+        cwd: projectDir,
+        env: { ...env, ACADEMY_PROJECT_DIR: projectDir },
+        message: `Launching ${name} with Codex for project ${basename(projectDir)}`,
+        ...codex,
+      },
+    );
+    return;
+  }
+
+  const pluginDir = writeProjectPluginInstance(projectDir, name, dir);
+  launchClaude(
+    ['--plugin-dir', pluginDir, '--system-prompt-file', systemPromptPath, ...passthrough],
+    {
+      cwd: projectDir,
+      env: { ...env, ACADEMY_PROJECT_DIR: projectDir },
+      message: `Launching ${name} with Claude Code for project ${basename(projectDir)} (plugin: ${pluginDir})`,
+    },
+  );
+}
+
+export function runAgent(name, runtime, passthrough) {
+  const context = prepareAgentRun(name, runtime, passthrough);
+  if (!context) return;
+  if (context.inAgentHome) launchInAgentHome(context);
+  else launchInProject(context);
+}
+
+// Runtime-agnostic by construction. An `--agent` on this command line comes
+// from a job an earlier build registered; it is accepted and ignored, because
+// the persisted scalar is the only source of truth a scheduled run may read.
+// The child is spawned bare, so it persists nothing and cannot revert the
+// operator's edit — editing agent.yaml is the published way to change a
+// runtime, and a nightly that carried a snapshot undid that edit every night.
+export function runNightly(name) {
+  validateName(name);
+  const dir = agentDir(name);
+  if (!existsSync(dir)) {
+    console.error(`Agent "${name}" not found at ${dir}`);
+    process.exit(1);
+  }
+  const runtime = toRuntimeToken(readRuntimeProvider(dir));
+
+  const markerPath = pendingMarkerPath(dir);
+  if (!existsSync(markerPath)) {
+    console.log(
+      `Skipping nightly consolidation for ${name}: no new session activity since the last run.`,
+    );
+    return;
+  }
+
+  const revision = Number(readJsonFile(markerPath, {}).revision);
+  const prompt = [
+    "Use the nightly-consolidation skill to consolidate today's pending observation memory.",
+    'Update the v3 memory surfaces conservatively, write the dreams report,',
+    'and finish with the dreams report path.',
+  ].join(' ');
+  const providerArgs =
+    runtime === 'codex'
+      ? [...SCHEDULED_CODEX_PERMISSION_ARGS, prompt]
+      : [...SCHEDULED_CLAUDE_PERMISSION_ARGS, '-p', prompt];
+  const result = spawnSync(
+    process.execPath,
+    [ACADEMY_CLI_PATH, 'run', name, '--', ...providerArgs],
+    {
+      stdio: 'inherit',
+      cwd: dir,
+      env: {
+        ...process.env,
+        ACADEMY_SKIP_NIGHTLY_TASK: '1',
+        ACADEMY_NIGHTLY_RUN: '1',
+      },
+    },
+  );
+  const status = result.status ?? 1;
+
+  if (status === 0 && existsSync(markerPath)) {
+    const currentRevision = Number(readJsonFile(markerPath, {}).revision);
+    if (currentRevision === revision) unlinkSync(markerPath);
+  }
+
+  process.exit(status);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `list` — list all agents
+// ─────────────────────────────────────────────────────────────────────────────