@joenandez/academy 0.5.17-rc.2 → 0.5.18

package/scripts/cli/core.mjs

@@ -53,6 +53,9 @@ export const UNIVERSAL_SKILLS = [
   'knowledge-curation',
   'local-rules',
   'skill-method',
+  'delivery',
+  'triage',
+  'explore-options',
 ];
 export const NIGHTLY_JOB_CRON = '0 22 * * *';
 // Unattended runs bypass permissions: auto mode refused every memory write
@@ -165,15 +168,13 @@ export const KIND_PROFILES = {
   specialist: { surfaces: surfaceSet(1000), skills: [...UNIVERSAL_SKILLS, 'user-nightly'] },
   principal: {
     surfaces: surfaceSet(500),
+    // A Principal runs its own pack nightly, so it has no nightly-consolidation.
     skills: [
       'principal-nightly',
       'principal-brief',
       'principal-intro',
-      'work-graph',
-      'check-in',
-      'knowledge-curation',
-      'local-rules',
-      'skill-method',
+      'academy-performance-review',
+      ...UNIVERSAL_SKILLS.filter((skill) => skill !== 'nightly-consolidation'),
     ],
   },
   owner: { surfaces: surfaceSet(1000), skills: [...OWNER_PACK, ...UNIVERSAL_SKILLS] },
@@ -351,13 +352,13 @@ function sleep(ms) {
 }
 
 export function withFileLock(lockDir, fn) {
-  const started = Date.now();
+  const [started, limit] = [Date.now(), Number(process.env.ACADEMY_LOCK_TIMEOUT_MS) || 5000];
   while (true) {
     try {
       mkdirSync(lockDir, { recursive: false });
       break;
     } catch {
-      if (Date.now() - started > 5000) throw new LockTimeoutError(lockDir);
+      if (Date.now() - started > limit) throw new LockTimeoutError(lockDir);
       sleep(25);
     }
   }

package/scripts/cli/create-options.mjs

@@ -0,0 +1,43 @@
+import { KIND_PROFILES, exitJsonError } from './core.mjs';
+import { isModelId } from './model.mjs';
+import { toRuntimeProvider } from './runtime.mjs';
+import { DISPLAY_NAME_RULE, isDisplayName } from './yaml.mjs';
+
+// Every refusal comes 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.
+export function assertCreateOptions(kind, invalidOption, json, { model, displayName, runtime }) {
+  if (invalidOption !== undefined) {
+    refuseCreate(
+      `Unknown create option: ${invalidOption}. Use create <name> [--kind <kind>] [--model <id>] [--display-name <text>] [--runtime claude-code|codex|copilot] [--no-start] [--json].`,
+      { option: invalidOption },
+      json,
+    );
+  }
+  if (model !== undefined && !isModelId(model)) {
+    refuseCreate(`Model "${model}" is not a model id Academy can store.`, { model }, json);
+  }
+  if (runtime !== undefined && !toRuntimeProvider(runtime)) {
+    refuseCreate(
+      `Runtime "${runtime}" is not a runtime Academy supports. Use claude-code, codex, or copilot.`,
+      { runtime },
+      json,
+    );
+  }
+  if (displayName !== undefined && !isDisplayName(displayName)) {
+    refuseCreate(DISPLAY_NAME_RULE, { displayName }, 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);
+}

package/scripts/cli/create.mjs

@@ -5,13 +5,11 @@ import { pendingMarkerPath } from '../../hooks/memory_store.mjs';
 import {
   ACADEMY_ROOT,
   CLI_NAME,
-  KIND_PROFILES,
   activeCommandName,
   NIGHTLY_JOB_CRON,
   agentDir,
   contractError,
   contractOk,
-  exitJsonError,
   kindOf,
   LockTimeoutError,
   RuntimeUnavailableError,
@@ -25,8 +23,10 @@ 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 { creatorOf } from './leads.mjs';
+import { assertCreateOptions } from './create-options.mjs';
+import { toRuntimeProvider } from './runtime.mjs';
 import { nextSteps } from './next-steps.mjs';
-import { isStopped } from './agent-gate.mjs';
 import { deleteAcademyJobs } from './lifecycle.mjs';
 import {
   ensureNightlyPermissionMode,
@@ -63,49 +63,25 @@ export const INTRO_PENDING_MARKER = 'intro-pending.md';
 export function createAgent(
   name,
   json = false,
-  { kind = DEFAULT_KIND, invalidOption, guided } = {},
+  { kind = DEFAULT_KIND, model, displayName, runtime, invalidOption, guided } = {},
 ) {
-  assertCreateOptions(kind, invalidOption, json);
-  const created = provisionAgent(name, json, kind);
+  assertCreateOptions(kind, invalidOption, json, { model, displayName, runtime });
+  // Stored in the provider form `run --agent` writes, before the jobs register.
+  const yamlOptions = { model, displayName, runtime: runtime && toRuntimeProvider(runtime) };
+  const created = provisionAgent(name, json, kind, yamlOptions);
   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
 // headless hire reports the same thing as a hire, so an agent hired without a
 // terminal is indistinguishable from a created one in ownership, scheduling and
 // 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, kind = DEFAULT_KIND) {
+export function provisionAgent(name, json = false, kind = DEFAULT_KIND, yamlOptions = {}) {
   const claimed = name === undefined ? claimDefaultName(kind, json) : claimNamedDir(name, json);
-  return provisionAgentDir(claimed.dir, claimed.name, json, kind);
+  return provisionAgentDir(claimed.dir, claimed.name, json, kind, yamlOptions);
 }
 
 // The mkdir is the one point where this request comes to own the directory. It
@@ -122,8 +98,8 @@ function claimNamedDir(name, json) {
   return { name, dir };
 }
 
-function provisionAgentDir(dir, name, json, kind) {
-  scaffoldAgentDir(dir, name, json, kind);
+function provisionAgentDir(dir, name, json, kind, yamlOptions) {
+  scaffoldAgentDir(dir, name, json, kind, yamlOptions);
   const jobs = registerAcademyJobs(dir, name);
   const failed = jobs.find((job) => !job.registered && !job.skipped);
   if (failed) {
@@ -170,11 +146,11 @@ function refuseTakenName(name, dir, json) {
   process.exit(1);
 }
 
-function scaffoldAgentDir(dir, name, json, kind) {
+function scaffoldAgentDir(dir, name, json, kind, yamlOptions = {}) {
   try {
     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);
+    writeAgentYaml(dir, name, today, kind, { ...yamlOptions, createdBy: creatorOf() });
     scaffoldBootFiles(dir, name, today);
     writeAgentClaudeMd(dir, name);
     writeSkillsScaffold(dir, name);
@@ -273,6 +249,9 @@ function reportGuidedCreated(name, nightlyTask, guided) {
   }
 }
 
+// A 22:00 nightly missed while the Mac slept still fires on wake until ~08:00 (10 h).
+const NIGHTLY_MISFIRE_GRACE_SEC = '36000';
+
 export function localTimezone() {
   return (
     process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'America/Los_Angeles'
@@ -291,7 +270,6 @@ 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();
   let academyBin;
   let tldrAgentsBin;
@@ -313,6 +291,8 @@ function registerNightlyConsolidationTask(dir, name) {
     id,
     '--cron',
     NIGHTLY_JOB_CRON,
+    '--misfire-grace-sec',
+    NIGHTLY_MISFIRE_GRACE_SEC,
     '--timezone',
     timezone,
     '--condition-file-exists',
@@ -339,8 +319,8 @@ export function runSchedule(tldrAgentsBin, dir, id, args) {
 
 // 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.
+// not register does not go on to half a schedule. A stopped agent registers its
+// nightly only (registerKindTasks).
 export function registerAcademyJobs(dir, name) {
   const nightly = registerNightlyConsolidationTask(dir, name);
   return nightly.registered ? registerKindTasks(dir, name, nightly) : [nightly];

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

@@ -1,8 +1,16 @@
 // Memory-bridge observations and the previous curator run's token use, for curator-feed.mjs. Read-only.
-import { existsSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readSync } 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';
+import {
+  DAY,
+  ifPresent,
+  jsonLines,
+  ls,
+  mtimeMs,
+  parseJsonLines,
+  textOf,
+} from './curator-feed-sources.mjs';
 
 // --- C. Observations ---
 const observationRows = (file) => ifPresent(() => jsonLines(file), []);
@@ -62,6 +70,33 @@ function isCuratorRun(lines) {
   );
 }
 
+// The Helm marker is in the first user entry, which real transcripts reach after up to ~110 KB of
+// hook and attachment lines. Read only that head, in chunks, never the whole transcript.
+// shortcut: a first user entry past the cap is "not a match"; raise the cap if heads grow.
+const HEAD_CAP = 256 * 1024;
+const HEAD_CHUNK = 64 * 1024;
+const hasUserText = (e) => e.type === 'user' && textOf(e.message?.content) != null;
+
+function headIsCuratorRun(file) {
+  const fd = openSync(file, 'r');
+  try {
+    let head = Buffer.alloc(0);
+    while (head.length < HEAD_CAP) {
+      const chunk = Buffer.alloc(HEAD_CHUNK);
+      const n = readSync(fd, chunk, 0, HEAD_CHUNK, head.length);
+      if (!n) return isCuratorRun(parseJsonLines(head.toString('utf8')));
+      head = Buffer.concat([head, chunk.subarray(0, n)]);
+      // Complete lines only: the last one may be cut mid-line or mid-character.
+      const complete = head.toString('utf8', 0, head.lastIndexOf(10) + 1);
+      const lines = parseJsonLines(complete);
+      if (lines.some(hasUserText)) return isCuratorRun(lines);
+    }
+    return false;
+  } finally {
+    closeSync(fd);
+  }
+}
+
 function tokensOf(lines) {
   const byId = new Map();
   for (const e of lines)
@@ -90,8 +125,7 @@ export function previousRun(home, agentsRoot) {
     .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);
+    if (headIsCuratorRun(file)) return tokensOf(jsonLines(file));
   }
   return null;
 }

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

@@ -54,16 +54,15 @@ export function ifPresent(read, fallback) {
   }
 }
 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 parseJsonLines = (text) =>
+  text.split('\n').flatMap((l) => {
+    try {
+      return l ? [JSON.parse(l)] : [];
+    } catch {
+      return [];
+    }
+  });
+export const jsonLines = (file) => parseJsonLines(readFileSync(file, 'utf8'));
 export const mtimeMs = (f) => statSync(f).mtimeMs;
 export const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
 export const textOf = (content) => {

package/scripts/cli/doctor.mjs

@@ -44,6 +44,9 @@ const PUBLISHED_COMMANDS = [
   'migrate',
   'start',
   'stop',
+  // Additive to v1: an agent's default model and a project's Lead.
+  'set-model',
+  'lead',
 ];
 
 /** Published above and built by no phase yet. Empty: every command is real. */

package/scripts/cli/heartbeat.mjs

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { beadsEnv } from './beads.mjs';
 import { kindOf, resolveExecutable } from './core.mjs';
 import { printHelmSkip } from './helm-skip.mjs';
-import { bookedFollowup, followupOf, listJobs, otherSession } from './owner-sessions.mjs';
+import { bookedFollowup } from './owner-sessions.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.
@@ -11,8 +11,6 @@ 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';
-/** The ungated ready items an idle heartbeat session is started for, comma separated. */
-const READY_ITEMS_ENV = 'ACADEMY_READY_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
@@ -85,9 +83,8 @@ function checkGates() {
 /**
  * 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. Those a running session holds are `held`. `bd blocked` only names
- * ids to leave out. No user database is an error: nothing can be known about
- * the work.
+ * 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;
@@ -95,41 +92,14 @@ function stoppedWork(name, now) {
   const gates = checkGates();
   const blocked = new Set(bdJson(['blocked']).map((item) => item.id));
   const items = [];
-  const held = [];
   for (const item of bdJson(['list', '--status', 'in_progress', '--label', `owner:${name}`])) {
-    if (item.id && !blocked.has(item.id)) (holderRunning(item, now) ? held : items).push(item.id);
+    if (item.id && !blocked.has(item.id) && !holderRunning(item, now)) items.push(item.id);
   }
-  return { items, held, gates, blocked };
+  return { items, gates };
 }
 
 const BEADS_SKIPS = new Set(['beads_unavailable', 'beads_busy']);
 
-// Owners release their claims when a session ends, so ready work can sit with
-// nothing in progress. Without a booked follow-up or a live session it needs a
-// start. An item a live holder has in progress is a live session, whatever the
-// jobs show. Any failed lookup skips: a missed start waits one beat, a wrong
-// start burns a model session. An epic is left out: it reads ready while all
-// its children wait, and its children are the work.
-function idleDecision(dir, name, now, ownRunId, { blocked, held, gates }) {
-  try {
-    const items = bdJson(['ready', '--label', `owner:${name}`, '--exclude-type', 'workstream,epic'])
-      .map((item) => item.id)
-      .filter((id) => id && !blocked.has(id));
-    if (items.length === 0) return { action: 'skip', reason: 'nothing_due', gates };
-    const jobs = listJobs(dir);
-    const followup = jobs.map((job) => followupOf(job, name, now)).find(Boolean);
-    if (followup) return { action: 'skip', reason: 'followup_booked', items, followup, gates };
-    const other =
-      held.length > 0
-        ? { reason: 'session_running', held }
-        : otherSession(jobs, dir, name, now, ownRunId);
-    if (other) return { action: 'skip', ...other, items, gates };
-    return { action: 'run', reason: 'idle_ready_work', items, gates };
-  } catch (error) {
-    return { action: 'skip', reason: 'idle_lookup_failed', error: error.message, gates };
-  }
-}
-
 function heartbeatDecision(dir, name, now = Date.now(), ownRunId = undefined) {
   let found;
   try {
@@ -138,7 +108,9 @@ function heartbeatDecision(dir, name, now = Date.now(), ownRunId = undefined) {
     const reason = error instanceof BeadsBusyError ? 'beads_busy' : 'beads_unavailable';
     return { action: 'skip', reason, error: error.message };
   }
-  if (found.items.length === 0) return idleDecision(dir, name, now, ownRunId, found);
+  // New ready work is the daily open's job; a heartbeat only restarts stopped work.
+  if (found.items.length === 0)
+    return { action: 'skip', reason: 'nothing_due', gates: found.gates };
   return stoppedDecision(dir, name, now, ownRunId, found);
 }
 
@@ -196,7 +168,6 @@ export function guardOwnerHeartbeat(dir, name, env = process.env) {
   const result = heartbeatDecision(dir, name, started, env.HELM_RUN_ID);
   const warn =
     BEADS_SKIPS.has(result.reason) ||
-    result.reason === 'idle_lookup_failed' ||
     result.gates === 'failed' ||
     result.followup === 'lookup_failed';
   console.error(
@@ -209,8 +180,7 @@ export function guardOwnerHeartbeat(dir, name, env = process.env) {
     }),
   );
   if (result.action === 'run') {
-    env[result.reason === 'stopped_work' ? STOPPED_ITEMS_ENV : READY_ITEMS_ENV] =
-      result.items.join(',');
+    env[STOPPED_ITEMS_ENV] = result.items.join(',');
     process.once('exit', () => logOutcome(result.items));
     return;
   }

package/scripts/cli/inspect.mjs

@@ -1,5 +1,5 @@
 import { existsSync, lstatSync, readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import {
   AGENTS_ROOT,
   CLI_NAME,
@@ -16,6 +16,7 @@ import {
 import { archivedAgentDir, archivedAgentNames, assertNotArchived } from './archived.mjs';
 import { assertContainedAgentDir } from './lifecycle.mjs';
 import { readEventLogWatermark } from './eventlog.mjs';
+import { leadOf } from './leads.mjs';
 import { readRuntimeProvider, runtimeProviderOrNull } from './runtime.mjs';
 import { academySystemPromptPath, buildAcademySystemPrompt, tokenRecord } from './scaffold.mjs';
 import { readAgentYaml } from './yaml.mjs';
@@ -112,6 +113,10 @@ export function agentRecord(
     displayName: yaml.displayName || yaml.display_name || yaml.name || name,
     runtimeProvider: strictRuntime ? readRuntimeProvider(dir) : runtimeProviderOrNull(dir),
     kind: strictRuntime ? kindOf(dir) : rosterKind(yaml),
+    // Additive: the default model (A4), who created the agent, and the projects it leads (A8).
+    model: yaml.model || null,
+    created_by: yaml.created_by || null,
+    lead_of: leadOf(basename(dir)),
   };
   if (yaml.role) record.role = yaml.role;
   if (includeSurfaces) record.surfaces = surfacePresence(dir);

package/scripts/cli/leads.mjs

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { AGENTS_ROOT, NAME_RE } from './core.mjs';
+import { withRootEventLock } from './eventlog.mjs';
+
+// A8 provenance: who created an agent (`created_by:` in its agent.yaml, written
+// once by `create`) and each project's Lead. Leads live in one file beside the
+// event log: a map from the project's normalized absolute path to the agent's
+// fixed id, so a rename keeps it. A map key holds one value, so "one Lead per
+// project" needs no check, and every change is one atomic write.
+
+const leadsPath = () => join(dirname(resolve(AGENTS_ROOT)), 'leads.json');
+
+// Strict: a write must never replace a file it cannot read, or every Lead in it is lost.
+function readLeadMap() {
+  let text;
+  try {
+    text = readFileSync(leadsPath(), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+  const projects = JSON.parse(text).projects;
+  if (projects && typeof projects === 'object' && !Array.isArray(projects)) return projects;
+  throw new Error(`${leadsPath()} has no "projects" map. Move it aside to start a new one.`);
+}
+
+function writeLeadMap(projects) {
+  const sorted = Object.fromEntries(
+    Object.keys(projects)
+      .sort()
+      .map((key) => [key, projects[key]]),
+  );
+  const temp = `${leadsPath()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify({ version: 1, projects: sorted }, null, 2)}\n`);
+  renameSync(temp, leadsPath());
+}
+
+// Sets (an id) or clears (null) the Lead of `project`; returns the previous Lead or null.
+export function writeLead(project, id) {
+  return withRootEventLock(() => {
+    const projects = readLeadMap();
+    const previous = projects[project] ?? null;
+    if (id) projects[project] = id;
+    else delete projects[project];
+    if (previous !== id) writeLeadMap(projects);
+    return previous;
+  });
+}
+
+// A deleted agent leads nothing, and a later agent given the same id must not
+// inherit its projects. The delete has already happened, so a fault is reported, not raised.
+export function dropLeadsOf(id) {
+  try {
+    withRootEventLock(() => {
+      const projects = readLeadMap();
+      const kept = Object.entries(projects).filter(([, lead]) => lead !== id);
+      if (kept.length !== Object.keys(projects).length) writeLeadMap(Object.fromEntries(kept));
+    });
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        event: 'leads.drop_failed',
+        status: 'warn',
+        params: { agent: id, path: leadsPath() },
+        result: { error: error.message },
+      }),
+    );
+  }
+}
+
+// The roster read degrades like the rest of `list`: an unreadable file reports no Leads.
+export function leadOf(id) {
+  let projects;
+  try {
+    projects = readLeadMap();
+  } catch {
+    return [];
+  }
+  return Object.keys(projects)
+    .filter((project) => projects[project] === id)
+    .sort();
+}
+
+// Who is creating the agent: the agent whose session runs this create (`academy
+// run` exports its home as ACADEMY_AGENT_DIR), else the user. A home outside this
+// AGENTS_ROOT names no agent here, so the creator stays unknown (null).
+export function creatorOf(env = process.env) {
+  if (!env.ACADEMY_AGENT_DIR) return 'user';
+  const home = resolve(env.ACADEMY_AGENT_DIR);
+  const id = basename(home);
+  const inRoster = dirname(home) === resolve(AGENTS_ROOT) && NAME_RE.test(id);
+  return inRoster && existsSync(join(home, 'agent.yaml')) ? id : null;
+}

package/scripts/cli/lifecycle.mjs

@@ -20,6 +20,7 @@ import {
 } from './core.mjs';
 import { assertNotArchived, holdingAreaOrNull } from './archived.mjs';
 import { LogCorruptError, appendLifecycleEvent } from './eventlog.mjs';
+import { dropLeadsOf } from './leads.mjs';
 import { AgentSpecError, readAgentYaml } from './yaml.mjs';
 import { agentIdOf, currentAgentName } from './agent-id.mjs';
 import { helmFailureReason } from './schedule-errors.mjs';
@@ -300,6 +301,7 @@ function deleteAgentLocked(id, _json) {
     throw unscheduleError('delete', name, unscheduled);
   }
   rmSync(quarantine, { recursive: true, force: false });
+  dropLeadsOf(id);
   appendLifecycleEvent('agent_deleted', name, dir);
   if (_json) {
     // Absolute, like every other command's `dir`: a client keying agents on the
@@ -329,6 +331,7 @@ export function destroyAgent(name, force) {
     process.exit(1);
   }
   rmSync(dir, { recursive: true, force: true });
+  dropLeadsOf(basename(dir));
   console.log(`Destroyed agent "${name}" (removed ${dir}).`);
 }
 

package/scripts/cli/main.mjs

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { isatty } from 'node:tty';
+import { printAgentRow } from './agent-row.mjs';
 import { parseArgs, printUsage } from './args.mjs';
 import {
   ACADEMY_ROOT,
@@ -11,6 +12,7 @@ import {
   jsonMode,
   setActiveCommand,
 } from './core.mjs';
+import { leadCommand, setAgentModel } from './agent-settings.mjs';
 import { archiveAgent, unarchiveAgent } from './archive.mjs';
 import { createAgent } from './create.mjs';
 import { UNIMPLEMENTED_COMMANDS, reportHealth } from './doctor.mjs';
@@ -52,12 +54,15 @@ const COMMAND_HANDLERS = {
   migrate: (parsed) => backfillOwnership(parsed),
   start: (parsed) => startAgent(parsed),
   stop: (parsed) => stopAgent(parsed.name, parsed.json),
-  rename: (parsed) => renameAgent(parsed.name, parsed.newName, parsed.json, parsed.invalidOption),
+  'set-model': (parsed) => setAgentModel(parsed),
+  lead: (parsed) => leadCommand(parsed),
+  rename: (parsed) => renameAgent(parsed),
   archive: (parsed) => archiveAgent(parsed.name, parsed.json),
   unarchive: (parsed) => unarchiveAgent(parsed.name, parsed.json),
   sessions: (parsed) => readSessions(parsed),
   list: (parsed) => {
     if (parsed.slackRows) printSlackRows(parsed.name);
+    else if (parsed.agentRow) printAgentRow(parsed.name);
     else if (parsed.json) listAgentsJson();
     else listAgents();
   },

package/scripts/cli/model.mjs

@@ -0,0 +1,45 @@
+import { runtimeProviderOrNull, toRuntimeToken } from './runtime.mjs';
+import { readAgentYaml } from './yaml.mjs';
+
+// An agent's default model: the agent.yaml `model:` scalar beside `runtime:`.
+// `create --model` writes it, `set-model` changes it, and `run` passes it to
+// the runtime unless the caller already chose a model.
+
+// Aliases (opus), full ids, routed ids (openrouter/openai/gpt-5.1), Bedrock ids
+// with a version (`...:0`) and Claude's `[1m]` suffix. Nothing that would end a
+// YAML plain scalar early or read as two argv words.
+const MODEL_RE = /^[A-Za-z0-9][\w.:/@+[\]-]{0,199}$/;
+
+export const isModelId = (value) => typeof value === 'string' && MODEL_RE.test(value);
+
+export const agentModel = (dir) => readAgentYaml(dir).model || null;
+
+// The caller's flag wins: Claude's `--model`, Codex's `-m`/`--model`, and a
+// Codex `-c model=...` override, in every spelling those CLIs accept.
+const MODEL_FLAG = /^(?:-m|--model)(?:=|$)/;
+const CONFIG_MODEL = /^\s*model\s*=/;
+
+function codexConfigValue(arg, next) {
+  if (arg === '-c' || arg === '--config') return next;
+  return arg.match(/^(?:--config=|-c=?)(.+)$/s)?.[1];
+}
+
+function callerChoseModel(argv, codex) {
+  return argv.some(
+    (arg, i) =>
+      MODEL_FLAG.test(arg) ||
+      (codex && CONFIG_MODEL.test(codexConfigValue(arg, argv[i + 1]) ?? '')),
+  );
+}
+
+// The stored model names a model of the persisted runtime, so a one-run switch
+// to another runtime drops it. A one-shot Codex run takes `-m` after `exec`.
+export function withModel(dir, runtime, passthrough) {
+  const model = runtime === toRuntimeToken(runtimeProviderOrNull(dir)) ? agentModel(dir) : null;
+  const codex = runtime === 'codex';
+  if (!model || callerChoseModel(passthrough, codex)) return passthrough;
+  if (!codex) return ['--model', model, ...passthrough];
+  const exec = passthrough.indexOf('exec');
+  if (exec === -1) return ['-m', model, ...passthrough];
+  return [...passthrough.slice(0, exec + 1), '-m', model, ...passthrough.slice(exec + 1)];
+}