@joenandez/academy 0.4.0 → 0.5.12

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

@@ -0,0 +1,124 @@
+// Arguments, scope, filters, the token cap, and the text layout of the curator feed. Pure functions; the script wires them.
+import { resolve } from 'node:path';
+import { DAY } from './curator-feed-sources.mjs';
+
+const die = (message) => {
+  process.stderr.write(`${JSON.stringify({ event: 'curator_feed.bad_args', error: message })}\n`);
+  process.exit(1);
+};
+
+export function parseArgs(argv) {
+  const get = (flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const since = Date.parse(get('--since') ?? '');
+  const until = get('--until') === undefined ? Date.now() : Date.parse(get('--until'));
+  const out = get('--out');
+  if (Number.isNaN(since)) die('--since must be an ISO timestamp');
+  if (Number.isNaN(until)) die('--until must be an ISO timestamp');
+  if (!out) die('--out is required');
+  const maxTokens = Number(get('--max-tokens') ?? 25000);
+  if (!(Number.isFinite(maxTokens) && maxTokens > 0))
+    die('--max-tokens must be a finite positive number');
+  return {
+    since: Math.max(since, until - 7 * DAY),
+    until,
+    out: resolve(out),
+    all: argv.includes('--all'),
+    project: get('--project'),
+    topic: get('--topic'),
+    branch: get('--branch'),
+    maxTokens,
+  };
+}
+
+// --- Output ---
+const tilde = (p, home) => (p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p);
+const stamp = (ms) => new Date(ms).toISOString().slice(0, 16).replace('T', ' ') + 'Z';
+
+export function render({ win, counts, tokens, sources, obsHomes, entries, home, notes }) {
+  const sourceLine = Object.entries(sources)
+    .map(([n, s]) =>
+      n === 'observations' && obsHomes.length
+        ? `${n} ${s} (${obsHomes.map((h) => tilde(h, home)).join(', ')})`
+        : `${n} ${s}`,
+    )
+    .join(' · ');
+  const byProject = new Map();
+  for (const e of entries) byProject.set(e.project, [...(byProject.get(e.project) ?? []), e]);
+  const sections = [...byProject.keys()].sort().map(
+    (p) =>
+      `## ${p}\n${byProject
+        .get(p)
+        .sort((a, b) => a.ts - b.ts)
+        .map((e) => e.md)
+        .join('\n\n')}`,
+  );
+  return (
+    `# Curator feed ${stamp(win.since)} → ${stamp(win.until)}\n` +
+    `Prompts ${counts.prompts} · Emails ${counts.emails} · Observations ${counts.observations} · Cut ${counts.cut} · ~${Math.round(tokens / 1000)}k tokens\n` +
+    `Sources: ${sourceLine}\n${notes.map((n) => `${n}\n`).join('')}\n${sections.join('\n\n')}\n`
+  );
+}
+
+// Scope, then filters. A header line counts every entry a filter leaves out, and those without the field.
+export function applyScope(all, win, agentName) {
+  const notes = [];
+  let kept = all;
+  if (!win.all) {
+    if (agentName) {
+      kept = kept.filter(({ entry }) => entry.agent === agentName);
+      notes.push(`Scope: agent ${agentName}`);
+    } else {
+      notes.push('Scope: ACADEMY_AGENT_NAME is not set, so all agents are shown (same as --all)');
+    }
+  }
+  for (const field of ['project', 'topic', 'branch']) {
+    if (win[field] === undefined) continue;
+    const has = kept.filter(({ entry }) => entry[field]);
+    const match = has.filter(({ entry }) => entry[field] === win[field]);
+    notes.push(
+      `Filter ${field}=${win[field]}: ${kept.length - match.length} entries left out (${kept.length - has.length} have no ${field})`,
+    );
+    kept = match;
+  }
+  return { kept, notes };
+}
+
+// Over the cap, drop the oldest entries; the cut note counts toward the estimate.
+// `build(rest, lines)` returns { counts, final }.
+export function fitToCap({ kept, win, notes, build }) {
+  const oldestFirst = [...kept].sort((a, b) => a.entry.ts - b.entry.ts);
+  const buildCut = (cut) => {
+    const dropped = new Set(oldestFirst.slice(0, cut));
+    const before = stamp(oldestFirst[cut]?.entry.ts ?? win.until);
+    const lines = cut
+      ? [
+          ...notes,
+          `Trimmed: ${cut} oldest entries before ${before} to stay under ${win.maxTokens} tokens. Narrow with --since, --project, --topic, --branch, or a higher --max-tokens.`,
+        ]
+      : notes;
+    return build(
+      kept.filter((k) => !dropped.has(k)),
+      lines,
+    );
+  };
+  const fits = (b) => Math.round(b.final.length / 4) <= win.maxTokens;
+  const whole = buildCut(0);
+  if (fits(whole)) return whole;
+  // From one cut on, each extra cut only shrinks the text, so bisect for the smallest that fits.
+  let [lo, hi] = [1, kept.length];
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (fits(buildCut(mid))) hi = mid;
+    else lo = mid + 1;
+  }
+  const best = kept.length ? buildCut(lo) : whole;
+  // Even with every entry cut, the header can be over a tiny cap: refuse rather than exceed it.
+  if (!fits(best))
+    die(
+      `--max-tokens ${win.maxTokens} is below the feed header (~${Math.round(best.final.length / 4)} tokens); raise it`,
+    );
+  return best;
+}

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

@@ -0,0 +1,172 @@
+// Shared readers for curator-feed.mjs and its source modules, plus the Claude prompts. Read-only.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { bridgeWorkspaceOf, stripBridgeContext } from '../../hooks/memory_bridge.mjs';
+import { NIGHTLY_SKILL_BY_KIND, nightlyRoute } from './nightly.mjs';
+import { nightlyPrompt } from './nightly-launch.mjs';
+
+export const DAY = 86_400_000;
+// Academy's generated nightly prompts, matched whole and only as a session's first entry:
+// a typed prompt that starts the same way stays.
+const NIGHTLY = new Set(
+  Object.entries(NIGHTLY_SKILL_BY_KIND).flatMap(([kind, skill]) => [
+    nightlyPrompt(skill),
+    nightlyRoute(kind),
+  ]),
+);
+// Generated envelopes (Claude and Codex), removed only when complete: opening tag through its
+// closing tag. What is left is the typed prompt; nothing left means automation. An opening tag
+// with no closing tag is typed text. Codex wraps AGENTS.md as a header line plus <INSTRUCTIONS>.
+// A Helm job entry is its envelope plus the job prompt Helm wrote after it, so both go.
+// Skill bodies, image notes, re-invocations, and compact summaries carry isMeta/isCompactSummary.
+const ENVELOPE = new RegExp(
+  '# AGENTS\\.md instructions for [^\\n]+\\n\\n<INSTRUCTIONS>[\\s\\S]*?</INSTRUCTIONS>|' +
+    '<helm-context>[\\s\\S]*?</helm-context>[\\s\\S]*|' +
+    '<(task-notification|tldr_messages|local-command-[a-z]+|system-reminder|' +
+    'environment_context|user_instructions|INSTRUCTIONS|turn_aborted|skill|subagent_notification|' +
+    'permissions instructions)(?:\\s[^>]*)?>[\\s\\S]*?</\\1>',
+  'g',
+);
+// The built-in slash command wrapper (name, message, args in any order) is an envelope too.
+const BUILTIN_COMMAND =
+  /<command-name>\/(?:clear|compact|exit|model|config|resume|status|cost|mcp|plugin|login)<\/command-name>/;
+// Claude Code writes these interrupt notes unflagged, so they match whole.
+const INTERRUPTS = new Set([
+  '[Request interrupted by user]',
+  '[Request interrupted by user for tool use]',
+]);
+// Spectre's plan-review receipt template with <placeholder> hashes, anywhere in an entry. The
+// entry stays and its heading is marked as a likely agent-written brief: a pasted or quoted
+// receipt may carry the user's words, so this rule never drops. A real receipt (hex hashes) is unmarked.
+// shortcut: coupled to Spectre's receipt (spectre-execute/references/plan-review.md step 4);
+// revisit when that format changes or Spectre flags its headless entries.
+export const REVIEW_BRIEF =
+  /^REVIEW_COMPLETE\nROUTE .+\nREPORT_SHA256 sha256:<.+\nPLAN_SHA256 sha256:<.+\nDISPOSITION .+\nPLAN_REVIEW_[A-Z]+_OK$/m;
+const absent = (e) => e.code === 'ENOENT' || e.code === 'ENOTDIR';
+
+// ENOENT/ENOTDIR -> fallback (absent); any other error is a real failure.
+export function ifPresent(read, fallback) {
+  try {
+    return read();
+  } catch (e) {
+    if (absent(e)) return fallback;
+    throw e;
+  }
+}
+export const ls = (dir) => ifPresent(() => readdirSync(dir), null);
+export const jsonLines = (file) =>
+  readFileSync(file, 'utf8')
+    .split('\n')
+    .flatMap((l) => {
+      try {
+        return l ? [JSON.parse(l)] : [];
+      } catch {
+        return [];
+      }
+    });
+export const mtimeMs = (f) => statSync(f).mtimeMs;
+export const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
+export const textOf = (content) => {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return null;
+  const texts = content.filter((b) => b?.type === 'text').map((b) => b.text ?? '');
+  return texts.length ? texts.join('\n') : null;
+};
+export const inWindow = (ts, win) => ts >= win.since && ts < win.until;
+export const stripEnvelopes = (t) =>
+  (BUILTIN_COMMAND.test(t)
+    ? t.replace(/<command-(message|name|args)>[\s\S]*?<\/command-\1>/g, '')
+    : t
+  )
+    .replace(ENVELOPE, '')
+    .trim();
+
+export function projectOf(cwd) {
+  const ws = bridgeWorkspaceOf(cwd);
+  return ws
+    ? { project: ws.project, topic: ws.workspace }
+    : { project: basename(cwd || '') || 'unknown', topic: null };
+}
+
+// --- A. Claude prompts ---
+function assistantText(e) {
+  if (!Array.isArray(e.message?.content)) return '';
+  const texts = e.message.content.filter((b) => b?.type === 'text').map((b) => b.text ?? '');
+  return texts.join(' ').trim();
+}
+
+function clean(raw) {
+  let t = raw;
+  const m =
+    /<command-message>([^<]*)<\/command-message>\s*<command-name>[^<]*<\/command-name>(?:\s*<command-args>(.*?)<\/command-args>)?/s.exec(
+      t,
+    );
+  if (m) t = `/${m[1]} ${m[2] ?? ''}`.trim();
+  return stripBridgeContext(stripEnvelopes(t)).trim();
+}
+
+// Temp and eval folders, matched as whole path prefixes: /tmpfoo is not /tmp.
+export const isTempCwd = (cw) =>
+  ['/tmp', '/private', '/var/folders'].some((d) => cw === d || cw.startsWith(`${d}/`));
+const isAutoEntry = (e, raw, first) =>
+  e.isMeta || e.isCompactSummary || (first && NIGHTLY.has(raw)) || INTERRUPTS.has(raw);
+
+// One user entry -> a prompt, or null when it is outside the window, automatic, or noise.
+function claudePrompt(e, raw, ctx) {
+  const ts = Date.parse(e.timestamp);
+  if (!inWindow(ts, ctx.win) || isAutoEntry(e, raw, ctx.first)) return null;
+  const cw = e.cwd || ctx.cwd || '';
+  if (isTempCwd(cw)) return null;
+  const text = clean(raw);
+  if (!text || text === 'Reply READY') return null;
+  return {
+    runtime: 'claude',
+    ts,
+    cwd: cw,
+    branch: e.gitBranch || null,
+    sessionId: ctx.sessionId,
+    turnId: e.promptId ?? null,
+    text,
+    prev: ctx.lastAsst,
+  };
+}
+
+// One transcript entry -> a prompt or null; assistant entries only feed the next prompt's `prev`.
+function claudeEntryPrompt(e, ctx) {
+  if (e.cwd && !ctx.cwd) ctx.cwd = e.cwd;
+  if (e.type === 'assistant') {
+    ctx.lastAsst = assistantText(e) || ctx.lastAsst;
+    return null;
+  }
+  if (e.type !== 'user') return null;
+  const raw = textOf(e.message?.content)?.trim();
+  if (raw == null) return null;
+  // Per entry, not per session: the user can type follow-ups into a Helm-started session.
+  const p = claudePrompt(e, raw, ctx);
+  ctx.first = false;
+  return p;
+}
+
+function claudeFilePrompts(file, sessionId, win) {
+  const prompts = [];
+  const ctx = { win, sessionId, cwd: null, lastAsst: '', first: true };
+  for (const e of jsonLines(file)) {
+    const p = claudeEntryPrompt(e, ctx);
+    if (p) prompts.push(p);
+  }
+  return prompts;
+}
+
+export function claudePrompts(home, win) {
+  const base = join(home, '.claude', 'projects');
+  const prompts = [];
+  for (const dir of ls(base) ?? []) {
+    if (dir === 'subagents') continue;
+    for (const f of ls(join(base, dir)) ?? []) {
+      const file = join(base, dir, f);
+      if (!f.endsWith('.jsonl') || mtimeMs(file) < win.since) continue;
+      prompts.push(...claudeFilePrompts(file, f.slice(0, -6), win));
+    }
+  }
+  return prompts;
+}

package/scripts/cli/curator-feed.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// Writes the curator's daily input feed: the user's own prompts (Claude + Codex), their inbound
+// emails, and the memory-bridge observation for each prompt. A plain script, not an `academy`
+// command. Usage: curator-feed.mjs --since <ISO> [--until <ISO>] --out <path>
+//   [--all] [--project <p>] [--topic <t>] [--branch <b>] [--max-tokens <n>]
+// Without --all the feed holds only the entries of ACADEMY_AGENT_NAME.
+// Prints one JSON line. Exit 0 when the file is written, 1 when it cannot be.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { DatabaseSync } from 'node:sqlite';
+import {
+  REVIEW_BRIEF,
+  claudePrompts,
+  ifPresent,
+  jsonLines,
+  ls,
+  oneLine,
+  projectOf,
+} from './curator-feed-sources.mjs';
+import { codexPrompts } from './curator-feed-codex.mjs';
+import { checkedObservation, observations, previousRun } from './curator-feed-observations.mjs';
+import { applyScope, fitToCap, parseArgs, render } from './curator-feed-scope.mjs';
+
+const CUT_AT = 2000;
+const SHORT = 60;
+const BRIEF_MARK = "[likely agent-written brief, not the user's words]";
+const PT = new Intl.DateTimeFormat('en-GB', {
+  timeZone: 'America/Los_Angeles',
+  hour: '2-digit',
+  minute: '2-digit',
+  hourCycle: 'h23',
+});
+const ptTime = (ms) => PT.format(new Date(ms));
+
+const fail = (source, error, id) =>
+  process.stderr.write(
+    `${JSON.stringify({ event: 'curator_feed.source_failed', source, ...(id !== undefined && { id }), error: String(error?.message ?? error) })}\n`,
+  );
+
+const NO_AGENTS = {
+  ofSession: () => 'direct chat',
+  ofCwd: () => 'direct chat',
+};
+
+function indexAgentRows(rows, name, { bySession, byDir, byCwd }) {
+  for (const r of rows) {
+    if (r.sessionId) bySession.set(r.sessionId, name);
+    if (r.agentDir) byDir.set(r.agentDir, name);
+    if (r.cwd) byCwd.push({ cwd: r.cwd, at: Date.parse(r.timestamp), name });
+  }
+}
+
+function loadAgents(root) {
+  const bySession = new Map();
+  const byDir = new Map();
+  const byCwd = [];
+  for (const id of ls(root) ?? []) {
+    try {
+      const yaml = ifPresent(() => readFileSync(join(root, id, 'agent.yaml'), 'utf8'), '');
+      const name = /^name:\s*["']?([^"'\n]+?)["']?\s*$/m.exec(yaml)?.[1] ?? id;
+      const rows = ifPresent(() => jsonLines(join(root, id, 'memory', 'sessions.jsonl')), []);
+      indexAgentRows(rows, name, { bySession, byDir, byCwd });
+    } catch (e) {
+      sources.agents = 'error';
+      fail('agents', e);
+    }
+  }
+  return {
+    ofSession: (sid) => bySession.get(sid) ?? 'direct chat',
+    // An agent's own home names it at any time; another cwd names the agent last seen there.
+    ofCwd: (cwd, at) =>
+      byDir.get(cwd) ??
+      byCwd.filter((r) => r.cwd === cwd && r.at <= at).sort((a, b) => b.at - a.at)[0]?.name ??
+      'direct chat',
+  };
+}
+
+// Fork duplicates: a prompt of SHORT chars or more with the same text in another session within
+// 2 minutes keeps the earliest only. Short replies ("yes") typed twice both stay; a short reply
+// that a fork copied (same turn id) is one prompt. Short prompts key by turn id too, so another
+// turn with the same text between two copies does not hide the copy.
+export function dedupeForks(prompts) {
+  const kept = new Map();
+  return prompts
+    .sort((a, b) => a.ts - b.ts)
+    .filter((p) => {
+      const key = p.text.length >= SHORT ? p.text : p.turnId != null && `${p.turnId}\0${p.text}`;
+      const seen = key && kept.get(key);
+      if (seen && seen.sessionId !== p.sessionId && p.ts - seen.ts <= 2 * 60_000) return false;
+      if (key) kept.set(key, p);
+      return true;
+    });
+}
+
+// --- B. Emails ---
+const EMAIL_SQL = `
+      select m.id, m.body, m.metadata, m.created_at, c.metadata as conv, pm.body as parent_body, pm.created_at as parent_at, pr.external_principal_ref as parent_ref
+      from messages m
+      left join conversations c on c.id = m.conversation_id
+      left join messages pm on pm.id = m.in_reply_to_message_id
+      left join principals pr on pr.id = pm.sender_principal_id
+      where m.origin = 'inbound' and m.created_at >= ? and m.created_at < ? order by m.created_at`;
+
+const parseJson = (s) => {
+  try {
+    return JSON.parse(s ?? '{}') ?? {};
+  } catch {
+    return {};
+  }
+};
+
+function emailOf(r, agents) {
+  const cwd = /^[a-z-]+:(\/.*)$/.exec(r.parent_ref ?? '')?.[1] ?? null;
+  const { project, topic } = cwd ? projectOf(cwd) : { project: 'unknown', topic: null };
+  return {
+    ts: Date.parse(r.created_at),
+    id: r.id,
+    body: r.body ?? '',
+    subject: parseJson(r.conv).subject ?? '',
+    channel: parseJson(r.metadata).provider_metadata?.channel ?? '',
+    parent: oneLine((r.parent_body ?? '').slice(0, 300)),
+    project,
+    topic,
+    agent: cwd ? agents.ofCwd(cwd, Date.parse(r.parent_at ?? r.created_at)) : 'direct chat',
+  };
+}
+
+export function emails(home, win, agents) {
+  const file = join(home, '.tldr-agents', 'tightbeam', 'tightbeam.db');
+  if (!existsSync(file)) return null;
+  const db = new DatabaseSync(file, { readOnly: true });
+  try {
+    return db
+      .prepare(EMAIL_SQL)
+      .all(new Date(win.since).toISOString(), new Date(win.until).toISOString())
+      .map((r) => emailOf(r, agents));
+  } finally {
+    db.close();
+  }
+}
+
+// --- Output ---
+const cutText = (text) =>
+  text.length > CUT_AT ? `${text.slice(0, CUT_AT)}[cut: ${text.length} chars]` : text;
+const quote = (text) =>
+  text
+    .split('\n')
+    .map((l) => `> ${l}`)
+    .join('\n');
+const short8 = (s) => String(s ?? '').slice(0, 8);
+function promptEntry(p, obs, agents) {
+  const { project, topic } = projectOf(p.cwd);
+  const branch = p.branch ?? obs?.branch;
+  const brief = REVIEW_BRIEF.test(p.text) ? ` · ${BRIEF_MARK}` : '';
+  const agent = agents.ofSession(p.sessionId);
+  const lines = [
+    `### ${ptTime(p.ts)} PT · ${p.runtime} · ${project}${topic ? `/${topic}` : ''}/${branch ?? '-'} · session ${short8(p.sessionId)} · turn ${short8(p.turnId)} · ${agent}${brief}`,
+    `cwd: ${p.cwd}`,
+    quote(cutText(p.text)),
+  ];
+  if (p.text.length < SHORT && p.prev) lines.push(`re: ${oneLine(p.prev.slice(-300))}`);
+  if (obs) {
+    const tags = obs.tags?.length ? ` [${obs.tags.join(', ')}]` : '';
+    const files = obs.files?.length ? ` (${obs.files.join(', ')})` : '';
+    lines.push(`Result — ${obs.actionStatus ?? ''}${tags}${files}`);
+    if (obs.summary) lines.push(obs.summary);
+  }
+  return { ts: p.ts, project, agent, topic, branch, md: lines.join('\n') };
+}
+
+function emailEntry(m) {
+  const lines = [
+    `### ${ptTime(m.ts)} PT · email → ${m.agent}${m.topic ? ` (${m.topic})` : ` (${m.project})`} · "${m.subject}" · msg_${m.id.replace(/^msg_/, '').slice(0, 8)}`,
+    `channel: ${m.channel}`,
+  ];
+  if (m.parent) lines.push(`re: ${m.parent}`);
+  lines.push(quote(cutText(m.body)));
+  return {
+    ts: m.ts,
+    project: m.project,
+    agent: m.agent,
+    topic: m.topic,
+    branch: null,
+    md: lines.join('\n'),
+  };
+}
+
+// --- Main ---
+const win = parseArgs(process.argv.slice(2));
+const home = process.env.HOME || homedir();
+const agentsRoot =
+  process.env.AGENTS_ROOT || join(process.env.ACADEMY_HOME || join(home, '.academy'), 'agents');
+const sources = {
+  agents: 'ok',
+  claude: 'ok',
+  codex: 'ok',
+  tightbeam: 'ok',
+  observations: 'ok',
+  previousRun: 'ok',
+};
+const guard = (name, fn, fallback) => {
+  try {
+    return fn();
+  } catch (e) {
+    sources[name] = 'error';
+    fail(name, e);
+    return fallback;
+  }
+};
+const agents = guard('agents', () => loadAgents(agentsRoot), NO_AGENTS);
+
+const claude = guard('claude', () => claudePrompts(home, win), []);
+const codex = guard(
+  'codex',
+  () => {
+    const r = codexPrompts(home, win);
+    if (r === null) sources.codex = 'missing';
+    return r ?? [];
+  },
+  [],
+);
+const prompts = dedupeForks([...claude, ...codex]);
+const mails = guard(
+  'tightbeam',
+  () => {
+    const r = emails(home, win, agents);
+    if (r === null) sources.tightbeam = 'missing';
+    return r ?? [];
+  },
+  [],
+);
+let obsHomes = [];
+const byTurn = guard(
+  'observations',
+  () => {
+    const r = observations(process.env, win);
+    obsHomes = r.homes;
+    if (!r.byTurn) sources.observations = 'missing';
+    return r.byTurn ?? new Map();
+  },
+  new Map(),
+);
+const prev = guard('previousRun', () => previousRun(home, agentsRoot), null);
+
+// One bad row is skipped with one stderr line; it never stops the file.
+const entryOf = (source, id, make) => {
+  try {
+    return make();
+  } catch (e) {
+    fail(source, e, id);
+    return null;
+  }
+};
+const observedOf = (p, obs = byTurn.get(`${p.sessionId}|${p.turnId}`)) =>
+  obs && entryOf('observations', obs.id ?? p.turnId, () => checkedObservation(obs));
+const observed = new Map(prompts.map((p) => [p, observedOf(p)]));
+const shown = (items, source, idOf, make) =>
+  items.flatMap((item) => {
+    const entry = entryOf(source(item), idOf(item), () => make(item));
+    return entry ? [{ item, entry }] : [];
+  });
+const shownPrompts = shown(
+  prompts,
+  (p) => p.runtime,
+  (p) => p.turnId ?? p.sessionId,
+  (p) => promptEntry(p, observed.get(p), agents),
+);
+const shownMails = shown(
+  mails,
+  () => 'tightbeam',
+  (m) => m.id,
+  emailEntry,
+);
+const { kept, notes } = applyScope(
+  [...shownPrompts, ...shownMails],
+  win,
+  process.env.ACADEMY_AGENT_NAME || null,
+);
+function build(rest, lines) {
+  const mine = rest.filter(({ item }) => observed.has(item));
+  const counts = {
+    prompts: mine.length,
+    emails: rest.length - mine.length,
+    observations: mine.filter(({ item }) => observed.get(item)).length,
+    cut: mine.filter(({ item }) => item.text.length > CUT_AT).length,
+  };
+  const args = {
+    win,
+    counts,
+    sources,
+    obsHomes,
+    entries: rest.map((k) => k.entry),
+    home,
+    notes: lines,
+  };
+  const text = render({ ...args, tokens: 0 });
+  return {
+    counts,
+    final: render({ ...args, tokens: Math.round(text.length / 4) }),
+  };
+}
+const { counts, final } = fitToCap({ kept, win, notes, build });
+const tokensEstimate = Math.round(final.length / 4);
+
+try {
+  mkdirSync(dirname(win.out), { recursive: true });
+  writeFileSync(win.out, final);
+} catch (e) {
+  fail('write', e);
+  process.stdout.write(
+    `${JSON.stringify({ ok: false, out: win.out, error: String(e.message) })}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `${JSON.stringify({ ok: true, out: win.out, ...counts, tokensEstimate, sources, previousRun: prev })}\n`,
+);

package/scripts/cli/default-name.mjs

@@ -0,0 +1,73 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  AGENTS_ROOT,
+  LockTimeoutError,
+  activeCommandName,
+  agentDir,
+  contractError,
+  validateAgentsRoot,
+} from './core.mjs';
+import { agentIdOrNull } from './agent-id.mjs';
+import { withRootEventLock } from './eventlog.mjs';
+
+const DEFAULT_NAME_WORDS = 'one two three four five six seven eight nine ten'.split(' ');
+
+function* defaultNames(kind) {
+  for (const word of DEFAULT_NAME_WORDS) yield `${kind}-${word}`;
+  for (let n = DEFAULT_NAME_WORDS.length + 1; ; n += 1) yield `${kind}-${n}`;
+}
+
+// Non-exiting, unlike assertAgentNameFree: it runs inside the root event lock,
+// and a pick that skips a taken name must not end the process. A name is taken
+// by any live or archived id or current name.
+export function isAgentNameFree(name) {
+  return agentIdOrNull(name) === null;
+}
+
+/** Claims an explicit name: true, false when taken, or the mkdir error. */
+export function claimName(name, json) {
+  try {
+    return underNameClaimLock(`the name "${name}"`, json, () => claimFreeName(name));
+  } catch (error) {
+    return error;
+  }
+}
+
+// Makes the folder for a free name; false when the name is taken. Only under the lock.
+function claimFreeName(name) {
+  if (!isAgentNameFree(name)) return false;
+  try {
+    mkdirSync(join(AGENTS_ROOT, name));
+    return true;
+  } catch (error) {
+    // Another writer outside this lock may have made the folder.
+    if (error.code !== 'EEXIST') throw error;
+    return false;
+  }
+}
+
+// The final name check and the mkdir claim share the root event lock, so two
+// creates cannot take one name. Conflicts are reported after the lock
+// releases. appendLifecycleEvent takes the same lock, so it runs after the claim.
+export function claimDefaultName(kind, json) {
+  validateAgentsRoot(json);
+  return underNameClaimLock(`a default name for ${kind}`, json, () => {
+    for (const name of defaultNames(kind)) {
+      if (claimFreeName(name)) return { name, dir: agentDir(name) };
+    }
+  });
+}
+
+/** Runs `claim` under the root event lock; a lock timeout exits after release. */
+function underNameClaimLock(what, json, claim) {
+  try {
+    return withRootEventLock(claim);
+  } catch (error) {
+    if (!(error instanceof LockTimeoutError)) throw error;
+    const message = `failed to claim ${what}: ${error.message}`;
+    if (json) contractError(activeCommandName(), error.code, message, error.fields);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}