@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/create.mjs

@@ -1,26 +1,36 @@
-import { existsSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pendingMarkerPath } from '../../hooks/memory_store.mjs';
 import {
   ACADEMY_ROOT,
   AGENTS_ROOT,
   CLI_NAME,
+  KIND_PROFILES,
   activeCommandName,
   NIGHTLY_JOB_CRON,
   agentDir,
   contractError,
   contractOk,
+  exitJsonError,
+  kindOf,
   LockTimeoutError,
   RuntimeUnavailableError,
   resolveExecutable,
   validateAgentsRoot,
   validateName,
 } from './core.mjs';
+import { resolveTldrAgentsBinary, spawnTldrTasksArgs, tldrSpawnOptions } from './tldr.mjs';
+import { scheduleFailureReason } from './schedule-errors.mjs';
 import { assertNotArchived } from './archived.mjs';
+import { claimDefaultName, claimName, isAgentNameFree } from './default-name.mjs';
 import { LogCorruptError, appendLifecycleEvent } from './eventlog.mjs';
 import { agentRecord } from './inspect.mjs';
-import { deleteNightlyConsolidation } from './lifecycle.mjs';
+import { nextSteps } from './next-steps.mjs';
+import { isStopped } from './agent-gate.mjs';
+import { deleteAcademyJobs } from './lifecycle.mjs';
+import { nightlyRoute } from './nightly.mjs';
+import { academyRuntimeArgs, registerKindTasks } from './owner-jobs.mjs';
 import {
   renderAcademySystemPrompt,
   scaffoldBootFiles,
@@ -36,9 +46,50 @@ import {
 // raises RuntimeUnavailableError instead of exiting mid-operation.
 export const MUST_EXIST = { throwOnMissing: true };
 
-export function createAgent(name, json = false) {
-  const { dir, nightlyTask } = provisionAgent(name, json);
-  reportCreated(name, dir, nightlyTask, json);
+const DEFAULT_KIND = 'specialist';
+export const INTRO_PENDING_MARKER = 'intro-pending.md';
+
+// `guided` is the caller saying a person at a terminal made this create:
+// 'opening' (a first session starts right after, so the report says that) or
+// 'later' (--no-start, so the report names `run`). Either replaces the Next:
+// block. `main.mjs` starts the session: this module cannot import run.mjs,
+// which imports this one. With no name, the first free default name is claimed
+// and returned.
+export function createAgent(
+  name,
+  json = false,
+  { kind = DEFAULT_KIND, invalidOption, guided } = {},
+) {
+  assertCreateOptions(kind, invalidOption, json);
+  const created = provisionAgent(name, json, kind);
+  reportCreated(created.name, created.dir, created.jobs, json, guided);
+  return created.name;
+}
+
+// Both refusals come before the name is asked about, so a create Academy will
+// not perform writes nothing. `invalid_spec` is the published code for an
+// unknown option; there is no sixteenth code for it.
+function assertCreateOptions(kind, invalidOption, json) {
+  if (invalidOption !== undefined) {
+    refuseCreate(
+      `Unknown create option: ${invalidOption}. Use create <name> [--kind <kind>] [--no-start] [--json].`,
+      { option: invalidOption },
+      json,
+    );
+  }
+  if (Object.hasOwn(KIND_PROFILES, kind)) return;
+  const kinds = Object.keys(KIND_PROFILES).join(', ');
+  refuseCreate(
+    `Agent kind "${kind}" is not a kind Academy supports. Use ${kinds}.`,
+    { kind },
+    json,
+  );
+}
+
+function refuseCreate(message, fields, json) {
+  if (json) exitJsonError('invalid_spec', message, fields);
+  console.error(`Error: ${message}`);
+  process.exit(1);
 }
 
 // The one creation path. `create` reports what it returns as a create and the
@@ -47,22 +98,48 @@ export function createAgent(name, json = false) {
 // events. A second scaffolder would be a second definition of what an Academy
 // agent is, and the two would disagree the first time one of them learned a
 // rule the other did not.
-export function provisionAgent(name, json = false) {
+export function provisionAgent(name, json = false, kind = DEFAULT_KIND) {
+  const claimed = name === undefined ? claimDefaultName(kind, json) : claimNamedDir(name, json);
+  return provisionAgentDir(claimed.dir, claimed.name, json, kind);
+}
+
+// The mkdir is the one point where this request comes to own the directory. It
+// shares the root event lock with every other name claim, and the final check
+// runs inside it, where nothing exits. The loser refuses after release and
+// removes nothing, because what is there belongs to the winner. Rollback is
+// for a directory this request made.
+function claimNamedDir(name, json) {
   const dir = assertAgentNameFree(name, json);
-  scaffoldAgentDir(dir, name, json);
-  const nightlyTask = registerNightlyConsolidationTask(dir, name);
-  if (!nightlyTask.registered && !nightlyTask.skipped) {
-    rmSync(dir, { recursive: true, force: true });
-    failNightlyRegistration(name, nightlyTask, json);
+  const claimed = claimName(name, json);
+  if (claimed instanceof Error) failScaffold(name, claimed, json);
+  // The same checks, asked again after release, exit with the code that fits.
+  if (!claimed) refuseTakenName(name, assertAgentNameFree(name, json), json);
+  return { name, dir };
+}
+
+function provisionAgentDir(dir, name, json, kind) {
+  scaffoldAgentDir(dir, name, json, kind);
+  const jobs = registerAcademyJobs(dir, name);
+  const failed = jobs.find((job) => !job.registered && !job.skipped);
+  if (failed) {
+    unregisterJobs(dir, jobs);
+    failJobRegistration(name, failed, json);
   }
   try {
     appendLifecycleEvent('agent_created', name, dir);
   } catch (error) {
-    if (nightlyTask.registered) deleteNightlyConsolidation(name, realpathSync(dir));
-    rmSync(dir, { recursive: true, force: true });
+    unregisterJobs(dir, jobs);
     failLifecyclePublish(name, error, json);
   }
-  return { dir, nightlyTask };
+  return { name, dir, jobs };
+}
+
+// The rollback of a create that will not stand: every job it registered goes
+// with the directory, so a retry of the name starts from nothing.
+function unregisterJobs(dir, jobs) {
+  const ids = registeredJobIds(jobs);
+  if (ids.length > 0) deleteAcademyJobs(realpathSync(dir), ids);
+  rmSync(dir, { recursive: true, force: true });
 }
 
 // The name question, asked before anything is written. The headless hire asks
@@ -71,11 +148,15 @@ export function provisionAgent(name, json = false) {
 export function assertAgentNameFree(name, json = false) {
   validateName(name);
   validateAgentsRoot();
+  const dir = agentDir(name);
+  if (isAgentNameFree(name)) return dir;
   // A fresh agent must not take a name the holding area still owns: unarchiving
   // it afterwards could only ever collide.
-  assertNotArchived(name, json);
-  const dir = agentDir(name);
-  if (!existsSync(dir)) return dir;
+  assertNotArchived(basename(dir), json);
+  return refuseTakenName(name, dir, json);
+}
+
+function refuseTakenName(name, dir, json) {
   const message = `Agent "${name}" already exists at ${dir}`;
   if (json) {
     contractError(activeCommandName(), 'agent_exists', message, { name, dir: resolve(dir) });
@@ -84,30 +165,45 @@ export function assertAgentNameFree(name, json = false) {
   process.exit(1);
 }
 
-function scaffoldAgentDir(dir, name, json) {
+function scaffoldAgentDir(dir, name, json, kind) {
   try {
-    mkdirSync(dir, { recursive: false });
-    const today = scaffoldBootFiles(dir, name);
-    writeAgentYaml(dir, name, today);
+    const today = new Date().toISOString().slice(0, 10);
+    // agent.yaml first: the kind it names selects the surfaces scaffolded next.
+    writeAgentYaml(dir, name, today, kind);
+    scaffoldBootFiles(dir, name, today);
     writeAgentClaudeMd(dir, name);
     writeSkillsScaffold(dir, name);
     writeSettingsLocal(dir);
     writePluginSymlink(dir);
     writeOwnershipMarker(dir, name);
+    if (kind === 'principal') writeIntroPendingMarker(dir);
     renderAcademySystemPrompt(dir, name);
   } catch (error) {
     rmSync(dir, { recursive: true, force: true });
-    if (json) throw error;
-    console.error(`Error: failed to create agent "${name}": ${error.message}`);
-    process.exit(1);
+    failScaffold(name, error, json);
   }
 }
 
+// Not a boot surface and never in the prompt: `academy run` reads it to seed the
+// first message, and the intro skill deletes it once the first work has started.
+function writeIntroPendingMarker(dir) {
+  writeFileSync(
+    join(dir, INTRO_PENDING_MARKER),
+    'The first-session intro is not finished. The principal-intro skill removes this file.\n',
+  );
+}
+
+function failScaffold(name, error, json) {
+  if (json) throw error;
+  console.error(`Error: failed to create agent "${name}": ${error.message}`);
+  process.exit(1);
+}
+
 // A host with no scheduler binary used to exit from inside the resolver, which
 // skipped the rollback, the event, and the envelope, and left an orphan agent
 // that no client could see and no retry could replace.
-function failNightlyRegistration(name, nightlyTask, json) {
-  const message = `failed to register nightly consolidation job for "${name}": ${nightlyTask.reason}`;
+function failJobRegistration(name, failed, json) {
+  const message = `failed to register ${jobLabel(failed.id)} "${failed.id}" for "${name}": ${failed.reason}`;
   if (json) contractError(activeCommandName(), 'runtime_unavailable', message, { name });
   console.error(`Error: ${message}`);
   process.exit(1);
@@ -127,16 +223,19 @@ function failLifecyclePublish(name, error, json) {
   process.exit(1);
 }
 
-function reportCreated(name, dir, nightlyTask, json) {
+function reportCreated(name, dir, jobs, json, guided) {
   if (json) {
-    contractOk('create', {
-      created: true,
-      ...agentRecord(name),
-      scheduledJobId: nightlyTask.registered ? nightlyTask.id : null,
-    });
+    // A new Owner is a draft until its mandate is signed (`start`), so it is never started here.
+    const fields = { created: true, ...agentRecord(name), ...scheduledJobFields(jobs) };
+    contractOk('create', kindOf(dir) === 'owner' ? { ...fields, started: false } : fields);
     return;
   }
 
+  const [nightlyTask, ...ownerTasks] = jobs;
+  if (guided) {
+    reportGuidedCreated(name, nightlyTask, guided);
+    return;
+  }
   console.log(`Created agent "${name}" at ${dir}`);
   if (nightlyTask.registered) {
     console.log(
@@ -145,23 +244,42 @@ function reportCreated(name, dir, nightlyTask, json) {
   } else {
     console.log(`Nightly consolidation job not registered: ${nightlyTask.reason}`);
   }
+  for (const task of ownerTasks) console.log(`Registered ${jobLabel(task.id)} "${task.id}".`);
   console.log('');
   console.log('Next:');
-  console.log(`  ${CLI_NAME} hire           # interactive hire flow to populate the 8 surfaces`);
-  console.log(`  ${CLI_NAME} run ${name}    # launch Claude Code in the agent's home`);
+  console.log(nextSteps(name, kindOf(dir)).join('\n'));
 }
 
-function localTimezone() {
+// The guided path is a person at a terminal making a Principal: short lines, no paths.
+function reportGuidedCreated(name, nightlyTask, guided) {
+  console.log(`✓ Created ${name}`);
+  if (nightlyTask.registered) {
+    const [minute, hour] = NIGHTLY_JOB_CRON.split(' ');
+    const time = `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`;
+    console.log(`✓ Nightly run at ${time} ${nightlyTask.timezone}`);
+  } else {
+    console.log(`Nightly consolidation job not registered: ${nightlyTask.reason}`);
+  }
+  if (guided === 'opening') {
+    console.log(`Opening your first session with ${name}…`);
+    console.log(`Next time: ${CLI_NAME} run ${name}`);
+  } else {
+    console.log(`Start it when you are ready: ${CLI_NAME} run ${name}`);
+  }
+}
+
+export function localTimezone() {
   return (
     process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'America/Los_Angeles'
   );
 }
 
-// The job is registered once and then runs unattended for months, so it carries
-// no runtime: a token here would be a snapshot of the scalar as it stood on
-// registration day, and the child run would rewrite every later operator edit
-// back to it. `nightly` reads the persisted scalar instead.
-export function registerNightlyConsolidationTask(dir, name) {
+// The command job is registered once and then runs unattended for months, so it
+// carries no runtime: a token here would be a snapshot of the scalar as it stood
+// on registration day, and the child run would rewrite every later operator
+// edit back to it. `nightly` reads the persisted scalar instead. An Owner's
+// provider job must name its runtime; `run --agent` re-registers it on change.
+function registerNightlyConsolidationTask(dir, name) {
   const id = `${name}-nightly-consolidation`;
   if (process.env.ACADEMY_SKIP_NIGHTLY_TASK === '1') {
     return {
@@ -171,20 +289,20 @@ export function registerNightlyConsolidationTask(dir, name) {
       reason: 'skipped by ACADEMY_SKIP_NIGHTLY_TASK=1',
     };
   }
+  if (isStopped(dir)) return { id, registered: false, skipped: true, reason: 'agent is stopped' };
 
   const timezone = localTimezone();
-  const runArgs = ['nightly', name];
   let academyBin;
-  let helmTasksBin;
+  let tldrAgentsBin;
   try {
     academyBin = resolveExecutable('ACADEMY_BIN', join(ACADEMY_ROOT, 'bin', 'academy'), MUST_EXIST);
-    helmTasksBin = resolveExecutable('ACADEMY_HELM_TASKS_BIN', 'helm-tasks', MUST_EXIST);
+    tldrAgentsBin = resolveTldrAgentsBinary();
   } catch (error) {
     if (!(error instanceof RuntimeUnavailableError)) throw error;
     return { id, registered: false, reason: error.message };
   }
 
-  const args = [
+  const args = spawnTldrTasksArgs([
     'schedule',
     '--cwd',
     dir,
@@ -196,45 +314,75 @@ export function registerNightlyConsolidationTask(dir, name) {
     timezone,
     '--condition-file-exists',
     pendingMarkerPath(dir),
-    '--command',
-    academyBin,
-    '--env-json',
-    JSON.stringify({ AGENTS_ROOT: resolve(AGENTS_ROOT) }),
-    '--replace',
+    ...nightlyJobLaunch(dir, name, academyBin),
+    '--merge',
     '--tags',
     'academy,nightly,consolidation',
     '--timeout-sec',
     '3600',
-    '--',
-    ...runArgs,
-  ];
+    ...nightlyJobCommandArgs(dir, name),
+  ]);
 
-  const result = spawnSync(helmTasksBin, args, {
-    cwd: dir,
-    encoding: 'utf8',
-    env: process.env,
-  });
+  const task = runSchedule(tldrAgentsBin, dir, id, args);
+  return task.registered ? { ...task, timezone } : task;
+}
 
-  if (result.error) return { id, registered: false, reason: result.error.message };
-  if (result.status !== 0) {
-    const reason = helmFailureReason(result.stderr || result.stdout, result.status);
-    return { id, registered: false, reason };
-  }
-  return { id, registered: true, timezone };
+export function runSchedule(tldrAgentsBin, dir, id, args) {
+  const result = spawnSync(tldrAgentsBin, args, tldrSpawnOptions(dir));
+  if (result.error || result.status !== 0)
+    return { id, registered: false, reason: scheduleFailureReason(result) };
+  return { id, registered: true };
 }
 
-export function helmFailureReason(output, status) {
-  const fallback = `helm-tasks exited ${status}`;
-  const text = output?.trim();
-  if (!text) return fallback;
-  try {
-    const parsed = JSON.parse(text);
-    const message = parsed.errors?.[0]?.message || parsed.data?.activation?.health?.reason;
-    if (message) return message;
-  } catch {
-    // Fall through to text truncation for non-JSON helm output.
-  }
-  return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+// Every Academy job an agent of its kind runs, nightly first. The skip flag
+// that silences the nightly silences the set, and an Owner whose nightly did
+// not register does not go on to half a schedule. A stopped agent's nightly is
+// skipped, so it registers nothing.
+export function registerAcademyJobs(dir, name) {
+  const nightly = registerNightlyConsolidationTask(dir, name);
+  return nightly.registered ? registerKindTasks(dir, name, nightly) : [nightly];
+}
+
+export const registeredJobIds = (jobs) => jobs.filter((job) => job.registered).map((job) => job.id);
+
+export const jobLabel = (id) =>
+  id.endsWith('-nightly-consolidation')
+    ? 'nightly consolidation job'
+    : id.endsWith('-principal-brief')
+      ? 'Principal brief job'
+      : 'Owner job';
+
+// `scheduledJobId` keeps its published meaning, the nightly; the set is
+// additive, so a client that knows only the nightly reads what it always did.
+export function scheduledJobFields(jobs) {
+  const [nightly] = jobs;
+  return {
+    scheduledJobId: nightly.registered ? nightly.id : null,
+    scheduledJobIds: registeredJobIds(jobs),
+  };
+}
+
+// An Owner's nightly runs through the Academy provider, like its other Academy
+// jobs; `academy run` derives ACADEMY_NIGHTLY_JOB from the job id and enters
+// the same routine as `academy nightly`. A provider job carries no env: the
+// scheduler refuses it there. Every other kind keeps the command job, which
+// carries its env and already records the real exit.
+function nightlyJobLaunch(dir, name, academyBin) {
+  const env = { AGENTS_ROOT: resolve(AGENTS_ROOT) };
+  if (kindOf(dir) !== 'owner') return ['--command', academyBin, '--env-json', JSON.stringify(env)];
+  return [
+    '--provider',
+    'academy',
+    '--academy-agent',
+    name,
+    ...academyRuntimeArgs(dir),
+    '--prompt',
+    nightlyRoute('owner'),
+  ];
+}
+
+function nightlyJobCommandArgs(dir, name) {
+  return kindOf(dir) === 'owner' ? [] : ['--', 'nightly', name];
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/scripts/cli/curator-feed-codex.mjs

@@ -0,0 +1,81 @@
+// Codex prompt reader for curator-feed.mjs. Read-only.
+import { readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { MEMORY_BRIDGE_CODEX_ORIGINATOR } from '../../hooks/memory_bridge.mjs';
+import {
+  inWindow,
+  isTempCwd,
+  jsonLines,
+  mtimeMs,
+  stripEnvelopes,
+} from './curator-feed-sources.mjs';
+
+const CODEX_ORIGINATORS = [
+  MEMORY_BRIDGE_CODEX_ORIGINATOR,
+  'codex_cli_rs',
+  'codex-tui',
+  'codex_tui',
+  'codex_vscode',
+];
+
+function codexText(p) {
+  return (p.content ?? [])
+    .filter((b) => ['input_text', 'output_text'].includes(b?.type))
+    .map((b) => b.text ?? '')
+    .join('\n')
+    .trim();
+}
+
+const codexPrompt = ({ p, meta, n, ts, text, prev }) => ({
+  runtime: 'codex',
+  ts,
+  cwd: meta.cwd || '',
+  branch: meta.git?.branch || null,
+  sessionId: meta.id ?? basename(n, '.jsonl'),
+  turnId: p.internal_chat_message_metadata_passthrough?.turn_id ?? null,
+  text,
+  prev,
+});
+
+function codexFilePrompts(lines, meta, n, win) {
+  const prompts = [];
+  let last = '';
+  for (const e of lines) {
+    const p = e.payload ?? {};
+    if (e.type !== 'response_item' || p.type !== 'message') continue;
+    const tx = codexText(p);
+    if (p.role === 'assistant') {
+      last = tx || last;
+      continue;
+    }
+    const ts = Date.parse(e.timestamp);
+    if (p.role !== 'user' || !inWindow(ts, win)) continue;
+    const text = stripEnvelopes(tx);
+    if (text) prompts.push(codexPrompt({ p, meta, n, ts, text, prev: last }));
+  }
+  return prompts;
+}
+
+const isCodexUserSession = (meta) =>
+  CODEX_ORIGINATORS.includes(meta?.originator) && !isTempCwd(meta.cwd || '');
+
+export function codexPrompts(home, win) {
+  const base = join(home, '.codex', 'sessions');
+  let names;
+  try {
+    names = readdirSync(base, { recursive: true });
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+  const prompts = [];
+  for (const n of names) {
+    const file = join(base, n);
+    if (!n.endsWith('.jsonl') || mtimeMs(file) < win.since) continue;
+    const lines = jsonLines(file);
+    const meta = lines[0]?.payload;
+    if (!isCodexUserSession(meta)) continue;
+    prompts.push(...codexFilePrompts(lines, meta, n, win));
+  }
+  return prompts;
+}

package/scripts/cli/curator-feed-observations.mjs

@@ -0,0 +1,97 @@
+// Memory-bridge observations and the previous curator run's token use, for curator-feed.mjs. Read-only.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { bridgeHomes } from '../../hooks/memory_bridge.mjs';
+import { DAY, ifPresent, jsonLines, ls, mtimeMs, textOf } from './curator-feed-sources.mjs';
+
+// --- C. Observations ---
+const observationRows = (file) => ifPresent(() => jsonLines(file), []);
+
+function observationFiles(homes, win) {
+  const dates = [];
+  for (let d = Math.floor((win.since - DAY) / DAY) * DAY; d <= win.until + DAY; d += DAY)
+    dates.push(new Date(d).toISOString().slice(0, 10));
+  const files = [];
+  for (const h of homes)
+    for (const project of ls(h) ?? [])
+      for (const ws of ls(join(h, project)) ?? [])
+        for (const date of dates)
+          files.push(join(h, project, ws, 'memory', 'observations', `${date}.jsonl`));
+  return files;
+}
+
+// Rows without an id cannot be told apart, so only rows with an id dedupe.
+function isNewObservation(o, seen) {
+  if (!o.sessionId || (o.id && seen.has(o.id))) return false;
+  if (o.id) seen.add(o.id);
+  return true;
+}
+
+export function observations(env, win) {
+  const homes = bridgeHomes(env).filter((h) => existsSync(h));
+  if (!homes.length) return { homes, byTurn: null };
+  const seen = new Set();
+  const byTurn = new Map();
+  for (const file of observationFiles(homes, win)) {
+    for (const o of observationRows(file)) {
+      if (!isNewObservation(o, seen)) continue;
+      const key = `${o.sessionId}|${o.turnId}`;
+      if (!(Date.parse(byTurn.get(key)?.timestamp) >= Date.parse(o.timestamp))) byTurn.set(key, o);
+    }
+  }
+  return { homes, byTurn };
+}
+
+// A malformed observation row throws here, apart from its prompt: only its Result is skipped.
+export function checkedObservation(obs) {
+  for (const k of ['tags', 'files'])
+    if (obs[k] != null && !(Array.isArray(obs[k]) && obs[k].every((s) => typeof s === 'string')))
+      throw new Error(`${k} is not a list of strings`);
+  for (const k of ['actionStatus', 'summary', 'branch'])
+    if (obs[k] != null && typeof obs[k] !== 'string') throw new Error(`${k} is not a string`);
+  return obs;
+}
+
+// --- D. Previous run tokens ---
+function isCuratorRun(lines) {
+  const first = textOf(
+    lines.find((e) => e.type === 'user' && textOf(e.message?.content) != null)?.message?.content,
+  );
+  return Boolean(
+    first?.startsWith('<helm-context>') && first.includes('HELM_JOB_ID=curator-user-nightly'),
+  );
+}
+
+function tokensOf(lines) {
+  const byId = new Map();
+  for (const e of lines)
+    if (e.type === 'assistant' && e.message?.id && e.message.usage)
+      byId.set(e.message.id, e.message.usage);
+  const sum = (k) => [...byId.values()].reduce((n, u) => n + (u[k] ?? 0), 0);
+  return {
+    calls: byId.size,
+    cacheRead: sum('cache_read_input_tokens'),
+    cacheWrite: sum('cache_creation_input_tokens'),
+    output: sum('output_tokens'),
+  };
+}
+
+// shortcut: Claude transcripts only; add Codex token_count when a curator runs on Codex.
+export function previousRun(home, agentsRoot) {
+  const dir = join(
+    home,
+    '.claude',
+    'projects',
+    join(agentsRoot, 'curator').replace(/[^A-Za-z0-9]/g, '-'),
+  );
+  const current = process.env.CLAUDE_CODE_SESSION_ID;
+  const files = (ls(dir) ?? [])
+    .filter((f) => f.endsWith('.jsonl') && f !== `${current}.jsonl`)
+    .map((f) => ({ file: join(dir, f), at: mtimeMs(join(dir, f)) }))
+    .sort((a, b) => b.at - a.at);
+  for (const { file } of files) {
+    const lines = jsonLines(file);
+    if (isCuratorRun(lines)) return tokensOf(lines);
+  }
+  return null;
+}