@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/doctor.mjs

@@ -1,9 +1,10 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import {
   ACADEMY_ROOT,
   AGENTS_ROOT,
+  CLI_NAME,
   CONTRACT_VERSION,
   agentDir,
   auditAgentsRoot,
@@ -11,11 +12,14 @@ import {
   printJson,
   resolveExecutable,
 } from './core.mjs';
+import { beadsStatus } from './beads.mjs';
 import { eventLogPath } from './eventlog.mjs';
 import { isAgentDirectory } from './inspect.mjs';
 import { backfillPlan } from './migrate.mjs';
+import { FLAGGED_NIGHTLY_STATUSES, nightlyStatus } from './nightly.mjs';
 import { runtimeProviderOrNull } from './runtime.mjs';
 import { unattributableSessionCount } from './sessions.mjs';
+import { readAgentYaml } from './yaml.mjs';
 
 // The frozen capability answer at contract_version 1. `notes`, `nightly`,
 // `clean`, `root`, and `run` all keep working and none of them is contract, so
@@ -38,6 +42,8 @@ const PUBLISHED_COMMANDS = [
   'unarchive',
   'delete',
   'migrate',
+  'start',
+  'stop',
 ];
 
 /** Published above and built by no phase yet. Empty: every command is real. */
@@ -63,6 +69,7 @@ export function reportHealth(json) {
     commands: PUBLISHED_COMMANDS,
     runtimes: runtimeAvailability(),
     errors: audit.problem ? [] : healthErrors(),
+    agents: audit.problem ? [] : agentEntries(),
   };
 
   if (audit.problem) return reportUnusableRoot(payload, audit.problem, json);
@@ -188,6 +195,44 @@ function agentNames() {
   }
 }
 
+// Additive to v1: each agent's last nightly receipt, so a nightly that failed
+// or never ran is visible without reading agent files. An Owner also reports
+// its `bd`, probed once for all Owners. The raw kind scalar is read, not
+// kindOf, because doctor must report an agent whose kind it cannot read.
+// `name` is the current name; `dir` is the fixed id folder a rename keeps.
+function agentEntries() {
+  let beads;
+  return agentNames().map((id) => {
+    const dir = resolve(agentDir(id));
+    const yaml = readAgentYaml(dir);
+    const entry = { name: yaml.name || id, dir, nightly: nightlyStatus(dir) };
+    if (yaml.kind !== 'owner') return entry;
+    beads ??= beadsStatus();
+    return { ...entry, beads };
+  });
+}
+
+const HOUR_MS = 60 * 60 * 1000;
+
+function ageOf(at) {
+  if (!at) return '-';
+  const hours = Math.floor((Date.now() - Date.parse(at)) / HOUR_MS);
+  if (hours < 1) return '<1h ago';
+  return hours < 48 ? `${hours}h ago` : `${Math.floor(hours / 24)}d ago`;
+}
+
+function printNightly({ name, nightly }) {
+  if (!nightly) {
+    console.log(`  nightly      ${name.padEnd(12)} none`);
+    return;
+  }
+  const flag = FLAGGED_NIGHTLY_STATUSES.has(nightly.status) ? '  FLAG' : '';
+  const reason = nightly.reason ? `  ${nightly.reason}` : '';
+  console.log(
+    `  nightly      ${name.padEnd(12)} ${nightly.status}  ${ageOf(nightly.at)}${reason}${flag}`,
+  );
+}
+
 function printReport(payload) {
   console.log(`academy ${payload.version}  contract ${CONTRACT_VERSION}`);
   console.log(`  packageRoot  ${payload.packageRoot}`);
@@ -198,6 +243,26 @@ function printReport(payload) {
   }
   console.log(`  commands     ${payload.commands.join(' ')}`);
   for (const entry of payload.errors) {
-    console.log(`  health       ${entry.code} ${entry.count}`);
+    console.log(`  health       ${entry.code} ${entry.count}  ${HEALTH_REPAIRS[entry.code]}`);
   }
+  for (const agent of payload.agents) printNightly(agent);
+  for (const agent of payload.agents) if (agent.beads) printBeads(agent);
 }
+
+function printBeads({ name, beads }) {
+  if (beads.status === 'ok') {
+    console.log(`  beads        ${name.padEnd(12)} ok  ${beads.version}`);
+    return;
+  }
+  console.log(
+    `  beads        ${name.padEnd(12)} ${beads.status}  ${beads.version ?? '-'}  install bd ${beads.range}  FLAG`,
+  );
+}
+
+// Human text only. `--json` carries the bare code and count, and a client maps
+// the code to its repair from the integration guide's health table.
+const HEALTH_REPAIRS = {
+  unowned_agents: `run \`${CLI_NAME} migrate\` to write the missing ownership markers`,
+  invalid_runtime_agents: 'set `runtime:` in each agent.yaml to claude_code or codex',
+  unattributable_sessions: 'historical records, excluded from `sessions`; no repair',
+};

package/scripts/cli/eventlog.mjs

@@ -62,10 +62,14 @@ function logCreatedRecord() {
   return { seq: 1, event: 'log_created', logId: randomUUID(), ts: new Date().toISOString() };
 }
 
+// The one root lock. Not re-entrant: a caller holding it must not append an event.
+export function withRootEventLock(fn) {
+  return withFileLock(join(agentsRootParent(), 'events.lock'), fn);
+}
+
 export function appendLifecycleEvent(event, name, dir, extra = {}) {
-  const parent = agentsRootParent();
   const eventsPath = eventLogPath();
-  withFileLock(join(parent, 'events.lock'), () => {
+  withRootEventLock(() => {
     const text = readEventLog(eventsPath);
     const records = text === null ? [logCreatedRecord()] : [];
     const previous = text === null ? 1 : lastSeq(text, eventsPath);

package/scripts/cli/exit-code.mjs

@@ -0,0 +1,9 @@
+import { constants } from 'node:os';
+
+// The exit code a child's result stands for. A child killed by a signal did
+// not finish, so it exits 128 + the signal number, as a shell reports it,
+// never 0: a scheduler and the nightly record must not read it as a pass.
+export function childExitCode(result) {
+  if (result.status !== null && result.status !== undefined) return result.status;
+  return result.signal ? 128 + (constants.signals[result.signal] ?? 0) : 1;
+}

package/scripts/cli/first-run.mjs

@@ -0,0 +1,115 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentAgentName } from './agent-id.mjs';
+import { CLI_NAME, RuntimeUnavailableError } from './core.mjs';
+import { ownerJobIds } from './owner-jobs.mjs';
+import { helmFailureReason } from './schedule-errors.mjs';
+import { resolveTldrAgentsBinary, spawnTldrTasksArgs, tldrSpawnOptions } from './tldr.mjs';
+
+// One first daily run of an Owner, asked of tldr only when no review exists
+// and no earlier first run is live. tldr returns once the session is handed
+// off; a failure after that is in tldr run history, not here.
+export function requestFirstRun(dir, id, scheduledJobIds) {
+  const [jobId] = ownerJobIds(id);
+  const skipReason = notNeededReason(dir, scheduledJobIds, jobId);
+  if (skipReason) return skipped(jobId, skipReason);
+  let bin;
+  try {
+    bin = resolveTldrAgentsBinary();
+  } catch (error) {
+    if (!(error instanceof RuntimeUnavailableError)) throw error;
+    return failedFirstRun(jobId, error.code, error.message);
+  }
+  return blockedByHistory(bin, dir, jobId) ?? launchFirstRun(bin, dir, jobId);
+}
+
+function notNeededReason(dir, scheduledJobIds, jobId) {
+  if (!scheduledJobIds.includes(jobId)) return 'daily_job_not_registered';
+  return hasReview(dir) ? 'first_review_exists' : null;
+}
+
+// The result that stops a launch, or null when history shows no live first run.
+function blockedByHistory(bin, dir, jobId) {
+  const history = tldrTasks(bin, dir, ['history', '--cwd', dir, '--id', jobId]);
+  const events = historyEvents(history);
+  // No reliable evidence that no first run is live: a request could start a second one.
+  if (!events) {
+    const why =
+      history.error || history.status !== 0 ? helmFailureReason(history) : 'no ok envelope';
+    const retry = `run ${CLI_NAME} start ${currentAgentName(dir)} again to request the first run, or it runs at its next scheduled time`;
+    return failedFirstRun(
+      jobId,
+      'history_unavailable',
+      `its run history is unreadable (${why})`,
+      retry,
+    );
+  }
+  const live = liveRunId(events, dir);
+  return live ? { ...skipped(jobId, 'first_run_active'), runId: live } : null;
+}
+
+// Exit 1 with an `errors[0].code` is a launch tldr refused at once.
+function launchFirstRun(bin, dir, jobId) {
+  const result = tldrTasks(bin, dir, ['run', '--cwd', dir, '--id', jobId]);
+  const envelope = firstJsonObject(result.stdout);
+  if (result.error || result.status !== 0) {
+    const code = envelope?.errors?.[0]?.code ?? 'launch_failed';
+    return failedFirstRun(jobId, code, helmFailureReason(result));
+  }
+  return { status: 'requested', jobId, runId: envelope?.data?.event?.run_id ?? null };
+}
+
+const skipped = (jobId, reason) => ({ status: 'skipped', jobId, reason });
+
+function failedFirstRun(jobId, code, reason, retry = `${jobId} runs at its next scheduled time`) {
+  const firstRun = {
+    status: 'failed',
+    jobId,
+    code,
+    message: `The first daily run did not launch: ${reason}. The jobs stay registered; ${retry}.`,
+  };
+  console.error(JSON.stringify({ event: 'start.first_run', status: 'warn', result: firstRun }));
+  return firstRun;
+}
+
+function hasReview(dir) {
+  const reviews = join(dir, 'reviews');
+  return existsSync(reviews) && readdirSync(reviews).some((file) => file.endsWith('.html'));
+}
+
+function tldrTasks(bin, dir, args) {
+  return spawnSync(bin, spawnTldrTasksArgs(args), tldrSpawnOptions(dir));
+}
+
+// tldr keeps no end for a handed-off session in history (A1): the newest
+// hand-off is live until its session outcome file exists.
+function liveRunId(events, dir) {
+  const newest = events
+    .filter((event) => event.reason === 'skyhook_started' && event.run_id)
+    .sort((a, b) => String(a.ts).localeCompare(String(b.ts)))
+    .at(-1);
+  if (!newest) return null;
+  const outcome = join(dir, '.helm', 'runs', 'session-outcomes', `${newest.run_id}.json`);
+  return existsSync(outcome) ? null : newest.run_id;
+}
+
+// The history events, or null when tldr failed or printed no ok envelope.
+function historyEvents(result) {
+  if (result.error || result.status !== 0) return null;
+  const envelope = firstJsonObject(result.stdout);
+  return envelope?.ok === true ? (envelope.data?.events ?? []) : null;
+}
+
+// tldr prints a log line before its JSON, so read the first line that parses.
+function firstJsonObject(output) {
+  for (const line of (output ?? '').split('\n')) {
+    if (!line.trim().startsWith('{')) continue;
+    try {
+      return JSON.parse(line);
+    } catch {
+      // not the envelope; keep looking
+    }
+  }
+  return null;
+}

package/scripts/cli/heartbeat.mjs

@@ -0,0 +1,135 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { beadsEnv } from './beads.mjs';
+import { kindOf, resolveExecutable } from './core.mjs';
+import { printHelmSkip } from './helm-skip.mjs';
+
+// The run type of an Owner job's run, `daily` or `heartbeat`, derived from its
+// job id at the run entry (run-context.mjs); a provider job carries no env.
+export const OWNER_RUN_FLAG = 'ACADEMY_OWNER_RUN';
+
+/** The stopped items a heartbeat session is started for, comma separated. */
+const STOPPED_ITEMS_ENV = 'ACADEMY_STOPPED_ITEMS';
+
+// Each Owner session claims Beads items as its own actor, `<agent>@<pid>`, the
+// pid of the `academy run` that waits on it (beads.mjs). An item stays its
+// holder's while that process is alive. A live pid is trusted only while the
+// item was updated in the last six hours, so a reused pid cannot hold an item
+// for ever. An actor with no pid (claimed before per-session actors, or by
+// hand) has no run to wait for.
+const HOLDER_PID = /@(\d+)$/;
+const HOLDER_TRUST_MS = 6 * 60 * 60 * 1000;
+const BD_TIMEOUT_MS = 10_000;
+// `bd gate check` asks GitHub about each gh:pr and gh:run gate.
+const GATE_CHECK_TIMEOUT_MS = 30_000;
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+function holderRunning(item, now) {
+  const pid = HOLDER_PID.exec(item.assignee ?? '')?.[1];
+  if (!pid) return false;
+  // An item with no readable update time is judged by its pid alone.
+  if (now - Date.parse(item.updated_at) >= HOLDER_TRUST_MS) return false;
+  return pidAlive(Number(pid));
+}
+
+function bd(args, timeout = BD_TIMEOUT_MS) {
+  const bin = resolveExecutable('ACADEMY_BD_BIN', 'bd', { throwOnMissing: true });
+  return spawnSync(bin, args, {
+    encoding: 'utf8',
+    timeout,
+    env: { ...process.env, ...beadsEnv() },
+  });
+}
+
+// The embedded database serves one command at a time, so a burst of writers can
+// hold a `bd` call past its timeout or make it fail on the lock. That is a busy
+// tracker, not a broken one: the next beat tries again.
+class BeadsBusyError extends Error {}
+
+function isBusy(result) {
+  return result.error?.code === 'ETIMEDOUT' || /\b(locked|busy)\b/i.test(result.stderr ?? '');
+}
+
+function bdJson(args) {
+  const result = bd([...args, '--json']);
+  if (result.error || result.status !== 0) {
+    const message = result.error?.message || result.stderr.trim() || `bd exit ${result.status}`;
+    throw isBusy(result) ? new BeadsBusyError(message) : new Error(message);
+  }
+  const parsed = JSON.parse(result.stdout || '[]');
+  if (!Array.isArray(parsed)) throw new Error(`bd ${args[0]} returned no list`);
+  return parsed;
+}
+
+// Closes the gates whose condition is met (a merged PR, an elapsed timer), so
+// their items count in this beat. A failed check (no network, gh signed out)
+// leaves the gates closed for now and does not stop the beat.
+function checkGates() {
+  const result = bd(['gate', 'check'], GATE_CHECK_TIMEOUT_MS);
+  return result.error || result.status !== 0 ? 'failed' : 'checked';
+}
+
+/**
+ * Work a stopped run left behind: this Owner's items (label `owner:<agent>`)
+ * in progress, not blocked by a gate, and not held by a session that is still
+ * running. `bd blocked` only names ids to leave out. No user database is an
+ * error: nothing can be known about the work.
+ */
+function stoppedWork(name, now) {
+  const database = beadsEnv().BEADS_DIR;
+  if (!existsSync(database)) throw new Error(`no Beads database at ${database}`);
+  const gates = checkGates();
+  const blocked = new Set(bdJson(['blocked']).map((item) => item.id));
+  const items = bdJson(['list', '--status', 'in_progress', '--label', `owner:${name}`])
+    .filter((item) => item.id && !blocked.has(item.id) && !holderRunning(item, now))
+    .map((item) => item.id);
+  return { items, gates };
+}
+
+const BEADS_SKIPS = new Set(['beads_unavailable', 'beads_busy']);
+
+function heartbeatDecision(name, now = Date.now()) {
+  let found;
+  try {
+    found = stoppedWork(name, now);
+  } catch (error) {
+    const reason = error instanceof BeadsBusyError ? 'beads_busy' : 'beads_unavailable';
+    return { action: 'skip', reason, error: error.message };
+  }
+  const { items, gates } = found;
+  if (items.length === 0) return { action: 'skip', reason: 'nothing_due', gates };
+  return { action: 'run', reason: 'stopped_work', items, gates };
+}
+
+// The entry check of a scheduled Owner heartbeat. It decides without a model:
+// nothing to do ends the run with a skip the scheduler records, and stopped
+// work starts the session with the items' ids in its env.
+export function guardOwnerHeartbeat(dir, name, env = process.env) {
+  if (env[OWNER_RUN_FLAG] !== 'heartbeat' || kindOf(dir) !== 'owner') return;
+  const started = Date.now();
+  const result = heartbeatDecision(name, started);
+  const warn = BEADS_SKIPS.has(result.reason) || result.gates === 'failed';
+  console.error(
+    JSON.stringify({
+      event: 'owner.heartbeat',
+      status: warn ? 'warn' : 'info',
+      params: { agent: name },
+      result,
+      latencyMs: Date.now() - started,
+    }),
+  );
+  if (result.action === 'run') {
+    env[STOPPED_ITEMS_ENV] = result.items.join(',');
+    return;
+  }
+  printHelmSkip(result.reason, name, env);
+  process.exit(0);
+}

package/scripts/cli/helm-skip.mjs

@@ -0,0 +1,20 @@
+import { writeSync } from 'node:fs';
+import { schedulerJobId } from './tldr.mjs';
+
+// Contract C1 with tldr (.spectre/features/agent-kinds-mvp/external/
+// tldr-provider-outcome-contract.md): a scheduler-launched run that decides on
+// purpose to start no model session says so on stdout, so the scheduler
+// records a skip instead of a failed start and launches no fallback. The line
+// is the boundary record for the skip; each call site already logs its own
+// decision. Written synchronously, because the callers exit right after.
+
+let printed = false;
+
+/** Prints the helm.skip line once per process, only under a scheduler job id. */
+export function printHelmSkip(reason, agent, env = process.env) {
+  const jobId = schedulerJobId(env);
+  if (printed || !jobId) return;
+  printed = true;
+  const line = { type: 'helm.skip', version: 1, source: 'academy', reason, agent, job_id: jobId };
+  writeSync(1, `${JSON.stringify(line)}\n`);
+}

package/scripts/cli/hire-headless.mjs

@@ -1,5 +1,5 @@
 import { rmSync, realpathSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import {
   ACADEMY_ROOT,
@@ -7,13 +7,20 @@ import {
   contractOk,
   exitJsonError,
   resolveExecutable,
+  surfacesFor,
   validateName,
 } from './core.mjs';
-import { MUST_EXIST, assertAgentNameFree, provisionAgent } from './create.mjs';
+import {
+  MUST_EXIST,
+  assertAgentNameFree,
+  provisionAgent,
+  registeredJobIds,
+  scheduledJobFields,
+} from './create.mjs';
 import { appendLifecycleEvent } from './eventlog.mjs';
 import { HireSpecError, readHireSpec } from './hire-spec.mjs';
 import { agentRecord } from './inspect.mjs';
-import { deleteNightlyConsolidation } from './lifecycle.mjs';
+import { deleteAcademyJobs } from './lifecycle.mjs';
 import { writeAgentYamlScalar } from './yaml.mjs';
 
 // `hire --spec <path> [--json]` — the headless form. The interactive form
@@ -29,7 +36,7 @@ import { writeAgentYamlScalar } from './yaml.mjs';
 // entirely, so the runtime never decides what an Academy agent is.
 
 /**
- * How long the runtime gets before it is killed. A `-p` turn that writes eight
+ * How long the runtime gets before it is killed. A `-p` turn that writes several
  * surfaces is minutes of work, and a client waiting on a synchronous command
  * cannot wait on a wedged child forever.
  */
@@ -96,20 +103,31 @@ function writeSpecScalars(dir, spec) {
 // change. `role` and `objective` are caller-supplied text and reach the model
 // here, which is why they are capped and single-line and why the child is given
 // no authority over creation, naming, scheduling or the event log.
-function headlessHirePrompt({ name, role, objective }) {
+function headlessHirePrompt(dir, { name, role, objective }) {
   return [
     `Use the Academy hire skill to finish hiring the agent "${name}".`,
     'Its home is the current working directory and already holds the scaffolded',
     'boot surfaces, agent.yaml and ownership marker.',
     `Role: ${role}`,
     `Objective: ${objective}`,
-    'Rewrite the eight surface files in place and stop. Do not create, rename,',
-    'archive or delete any agent, and do not write outside this directory.',
+    `Rewrite these surface files in place and stop: ${hiredSurfaceFiles(dir)}.`,
+    'Do not create, rename, archive or delete any agent, and do not write',
+    'outside this directory.',
     'There is no user to ask, so make your own best inference and proceed.',
   ].join('\n');
 }
 
-// `acceptEdits` rather than `bypassPermissions`: the child has to write eight
+// The agent's own surfaces from the kind registry, minus local rules (they
+// record corrections made after the hire) and the shared user files (the
+// curator writes them, and they live outside this directory).
+function hiredSurfaceFiles(dir) {
+  return surfacesFor(dir)
+    .filter(({ name, path }) => name !== 'local-rules' && dirname(path) === resolve(dir))
+    .map(({ name }) => `${name}.md`)
+    .join(', ');
+}
+
+// `acceptEdits` rather than `bypassPermissions`: the child has to write its
 // markdown files in its own working directory and needs nothing beyond that.
 // stdio is captured on both streams and stdin is closed, so a runtime that
 // falls back to asking a question fails fast instead of holding the timeout.
@@ -118,7 +136,7 @@ function runHeadlessRuntime(claudeBin, dir, spec) {
     claudeBin,
     [
       '-p',
-      headlessHirePrompt(spec),
+      headlessHirePrompt(dir, spec),
       '--permission-mode',
       'acceptEdits',
       '--plugin-dir',
@@ -175,14 +193,15 @@ function excerpt(output) {
 // the agent_created that was already published. Leaving the half-hired agent
 // would register nightly consolidation for a specialist nobody hired and would
 // block every retry of the same name behind a manual delete.
-function rollbackHire(name, dir, nightlyTask) {
+function rollbackHire(name, dir, jobs) {
   let dirReal = resolve(dir);
   try {
     dirReal = realpathSync(dir);
   } catch {
     /* already gone; the unschedule still names the canonical path */
   }
-  if (nightlyTask.registered) deleteNightlyConsolidation(name, dirReal);
+  const registered = registeredJobIds(jobs);
+  if (registered.length > 0) deleteAcademyJobs(dirReal, registered);
   rmSync(dir, { recursive: true, force: true });
   try {
     appendLifecycleEvent('agent_deleted', name, dir);
@@ -194,20 +213,16 @@ function rollbackHire(name, dir, nightlyTask) {
   }
 }
 
-function failRuntime(name, dir, nightlyTask, fault, json) {
-  const rollbackFault = rollbackHire(name, dir, nightlyTask);
+function failRuntime(name, dir, jobs, fault, json) {
+  const rollbackFault = rollbackHire(name, dir, jobs);
   const fields = { name, ...fault.fields };
   if (rollbackFault) fields.rollbackFault = rollbackFault;
   failHire('runtime_unavailable', `hire of "${name}" failed: ${fault.message}`, fields, json);
 }
 
-function reportHired(name, dir, nightlyTask, json) {
+function reportHired(name, dir, jobs, json) {
   if (json) {
-    contractOk('hire', {
-      hired: true,
-      ...agentRecord(name),
-      scheduledJobId: nightlyTask.registered ? nightlyTask.id : null,
-    });
+    contractOk('hire', { hired: true, ...agentRecord(name), ...scheduledJobFields(jobs) });
     return;
   }
   console.log(`Hired agent "${name}" at ${dir}`);
@@ -221,9 +236,9 @@ export function hireFromSpec({ spec, json, invalidOption }) {
   validateName(parsed.name);
   assertAgentNameFree(parsed.name, json);
   const claudeBin = resolveHireRuntime(json);
-  const { dir, nightlyTask } = provisionAgent(parsed.name, json);
+  const { dir, jobs } = provisionAgent(parsed.name, json);
   writeSpecScalars(dir, parsed);
   const fault = runtimeFault(runHeadlessRuntime(claudeBin, dir, parsed), claudeBin);
-  if (fault) failRuntime(parsed.name, dir, nightlyTask, fault, json);
-  reportHired(parsed.name, dir, nightlyTask, json);
+  if (fault) failRuntime(parsed.name, dir, jobs, fault, json);
+  reportHired(parsed.name, dir, jobs, json);
 }

package/scripts/cli/hire.mjs

@@ -2,6 +2,7 @@ import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { childExitCode } from './exit-code.mjs';
 import {
   ACADEMY_ROOT,
   AGENTS_ROOT,
@@ -67,6 +68,11 @@ export function hireAgent(passthrough, json = false) {
   });
 }
 
+// A multi-line prompt would break the one-line dry-run view, so the inline
+// append value prints as a JSON string, as Codex's `developer_instructions` does.
+const dryRunArgs = (args) =>
+  args.map((arg, i) => (args[i - 1] === '--append-system-prompt' ? JSON.stringify(arg) : arg));
+
 export function launchClaude(args, { cwd, env, message }) {
   console.log(message);
   const claudeBin =
@@ -74,7 +80,7 @@ export function launchClaude(args, { cwd, env, message }) {
       ? process.env.ACADEMY_CLAUDE_BIN || 'claude'
       : resolveExecutable('ACADEMY_CLAUDE_BIN', 'claude');
   if (process.env.ACADEMY_DRY_RUN === '1') {
-    console.log(`[dry-run] ${claudeBin} ${args.join(' ')}`);
+    console.log(`[dry-run] ${claudeBin} ${dryRunArgs(args).join(' ')}`);
     console.log(`[dry-run] cwd=${cwd}`);
     if (env?.ACADEMY_AGENT_DIR) console.log(`[dry-run] ACADEMY_AGENT_DIR=${env.ACADEMY_AGENT_DIR}`);
     if (env?.ACADEMY_PROJECT_DIR)
@@ -88,5 +94,5 @@ export function launchClaude(args, { cwd, env, message }) {
     );
     process.exit(1);
   }
-  process.exit(result.status ?? 0);
+  process.exit(childExitCode(result));
 }