@joenandez/academy 0.5.17-rc.1 → 0.5.17

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "academy",
   "description": "Academy v3 — portable AI agents.",
-  "version": "0.5.17-rc.1",
+  "version": "0.5.17",
   "hooks": "./hooks/hooks.json"
 }

package/CHANGELOG.md

@@ -3,6 +3,164 @@
 This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The heading at the top of this file is the version in `package.json`.
 
+## 0.5.17 — 2026-11-11
+
+This release collects the 0.5.17 release candidates (rc.1 to rc.6, below) and
+the work merged after rc.6. npm `latest` was 0.5.13 before this release; the
+0.5.14 to 0.5.16 notes below ship with it.
+
+### Added
+
+- **`tldr-agents` and `backstory` commands.** A global install puts
+  `academy`, `tldr-agents`, and `backstory` on your PATH. `tldr-agents` runs
+  the same tldr that Academy uses.
+- **Delivery for every agent kind.** One skill links Scope, Plan, Build,
+  Validate, and Ship, with worker delegation, TDD, risk-based review, and
+  resumable execution checkpoints. Skills can bundle linked Markdown
+  references.
+- **Work triage and a ranked priority list.** A `triage` skill gives each Beads
+  item one structured state. Owners and Principals keep a ranked priority
+  list, triage checks it daily, and Principals sync it to the user's Workstream
+  order. Agents search Beads before they file and report status from Beads
+  only.
+- **Academy Operating Standard.** New `explore-options` and
+  `academy-performance-review` skills.
+- **A per-agent default model, Leads, and `--display-name`.** `academy create`
+  and `academy rename` take `--display-name`; an agent can have a default
+  model and Leads.
+- **`academy list --agent-row <name>`** reports one agent's row, including a
+  draft Owner.
+- **Owner cadence.** Owners size work to the mandate's cadence, recover due
+  check-ins without a nightly run, and keep reviews within cadence while work
+  waits. The first Owner welcome does not depend on cadence.
+- **The Principal morning brief goes to every channel** the user set up and
+  covers the Principal's own work and queue. The user-nightly learns the
+  user's preferences.
+
+### Changed
+
+- **One install command.** Install with `npm install -g @joenandez/academy`,
+  then run `tldr-agents setup`. tldr comes from the npm registry, pinned to
+  `@joenandez/tldr` 0.3.0-rc.3; Academy no longer bundles it. If you installed
+  `@joenandez/tldr` globally, uninstall it first.
+- **Stopping an agent turns off its work loop.** Nightly consolidation stays
+  scheduled. An Owner heartbeat only restarts stopped work.
+- **Nightly consolidation waits for 10 new observations.** Smaller inputs carry
+  over to a later run.
+- **Nightly and Owner daily jobs have a late-start window**, as does the
+  Principal morning brief.
+- **Subagent guidance.** Agents use workers for bounded work and handle small
+  checks themselves.
+- Each Workstream names its production version and release cycle (`Prod:`).
+
+### Fixed
+
+- **`npm install -g` no longer fails on macOS.** The registry dependency
+  installs with default npm settings.
+- **Copilot setup on macOS without the Claude Code tldr plugin.** Academy
+  skips the runtime-only copy and uses the npm package. The Copilot pre-launch
+  error names `tldr-agents setup`.
+- A one-run runtime switch (`--runtime-once`) launches without the stored
+  model.
+- Owner stopped-claim recovery, the Copilot cold-start placeholder id, a
+  late-swept observation file, and stopped-agent loop checks (identified by
+  scheduler job ID).
+- The triage backfill acts only where the live state matches its backup.
+
+### Removed
+
+- **The bundled tldr** (`vendor/tldr`).
+
+### Install / upgrade
+
+- Run `npm install -g @joenandez/academy`, then run `tldr-agents setup` to
+  replace any old Copilot hooks record.
+
+## 0.5.17-rc.6 — 2026-10-28
+
+### Fixed
+
+- Keep delivery's internal resource helpers private so the package passes the
+  required dead-code gate. This replaces the local rc.5 candidate; neither RC
+  was published to npm or the public repository.
+
+## 0.5.17-rc.5 — 2026-10-28
+
+### Added
+
+- **Delivery for every agent kind.** One compact skill links Scope, Plan, Build,
+  Validate, and Ship. Agents load only the stage they need. It includes worker
+  delegation, TDD, product validation, risk-based adversarial review, durable
+  feature records, and resumable execution checkpoints.
+- **Bundled skill references.** Agent creation and launch refresh install linked
+  Markdown references on both runtime skill surfaces. Refresh preserves unknown
+  files and reports ownership conflicts before writing.
+
+### Changed
+
+- **Stopping an agent turns off its work loop.** Nightly consolidation remains
+  scheduled. A stopped Owner receives the loop-off operating model and can still
+  respond to on-demand work.
+- **Nightly consolidation waits for 20 new observations.** Smaller inputs carry
+  over to a later run.
+- **Owner heartbeats only restart stopped work.** A heartbeat no longer starts a
+  session for idle ready work; the Owner paces itself with booked sessions and
+  the daily open. Reverts the idle start from #4.
+
+### Fixed
+
+- A late-swept observation file still counts as waiting nightly input.
+- Stopped-agent checks identify loop runs by scheduler job ID, so they do not
+  block unrelated on-demand sessions.
+
+## 0.5.17-rc.4 — 2026-10-28
+
+### Added
+
+- **Work triage.** A new `triage` skill for every agent kind. Each Beads item
+  has one structured state: untriaged, triaged, next, now, blocked, waiting on
+  the user's decision (a human gate), PR open, merged but not released,
+  parked, or done with proof. Principals triage before the morning brief, and
+  Owners at the start of the daily open. Each nightly makes statuses true, and
+  the curator cleans up duplicates and items with no owner or Workstream. On
+  its first run, each agent drafts its own ranking criteria for the user to
+  confirm and converts its open items.
+- **Capture, status, and surfacing rules** in every session. Agents search
+  Beads before they file and add to a match. They report status from Beads
+  only, and show related open items when the user discusses an area.
+
+### Changed
+
+- Each Workstream names its production version and release cycle (`Prod:`).
+- New Owner tasks take their Workstream's `owner:` label.
+
+## 0.5.17-rc.3 — 2026-10-27
+
+### Changed
+
+- **Subagent guidance.** Agents use workers for bounded work and handle small
+  checks themselves. They check the model and capacity pool, pass context and
+  evidence requirements, run independent tasks in parallel, and verify the
+  result. Owners delegate substantial execution and handle small checks.
+
+## 0.5.17-rc.2 — 2026-10-27
+
+### Fixed
+
+- **Copilot setup on macOS without the Claude Code tldr plugin.** Academy
+  skips the runtime-only copy that setup leaves behind and uses the npm
+  package. The tldr command and Copilot hooks use a runnable installation.
+
+### Changed
+
+- **tldr 0.3.0-rc.2.** Academy pins this exact version. It fixes Copilot hook
+  registration on macOS and replaces the record made by tldr 0.3.0-rc.1.
+
+### Install / upgrade
+
+- Run `npm install -g @joenandez/academy@next`, then run
+  `tldr-agents setup` to replace the old Copilot hooks record.
+
 ## 0.5.17-rc.1 — 2026-10-27
 
 ### Added

package/README.md

@@ -70,7 +70,7 @@ Six universal skills ship with every agent: `check-in`, `work-graph`, `nightly-c
 
 ## Commands
 
-Sixteen commands are contract. `doctor` publishes the list, and a client should read it from there rather than hard-coding it.
+Eighteen commands are contract. `doctor` publishes the list, and a client should read it from there rather than hard-coding it.
 
 ```bash
 academy doctor [--json]              # discovery, health, and the version source
@@ -80,16 +80,19 @@ academy tokens <name> [--json]       # compiled prompt size by surface
 academy budget <name> [--json]       # surfaces over their cap
 academy sessions [--agent <name>] [--json]
 academy events --since <seq> [--logid <id>] [--json]
-academy create [<name>] [--json]    # no name: the next default for the kind
+academy create [<name>] [--kind <kind>] [--model <id>] [--display-name <text>] [--json]
 academy hire                         # interactive
 academy hire --spec <file> [--json]  # headless
-academy rename <old> <new> [--json]  # changes the name only; no job changes
+academy rename <old> [<new>] [--display-name <text>] [--json]  # no folder or job changes
 academy archive <name> [--json]
 academy unarchive <name> [--json]
 academy delete <name> [--json]
 academy migrate [--dry-run] [--json]
 academy start <name> [--mandate <file>] [--json]  # register jobs; an Owner needs a signed mandate
-academy stop <name> [--json]         # delete the jobs; the files stay
+academy stop <name> [--json]         # loop off; keeps the nightly and files
+academy set-model <name> <model> [--json]           # default model; run passes it on
+academy lead set <agent> --project <path> [--json]  # one Lead per project
+academy lead clear --project <path> [--json]
 ```
 
 `run`, `nightly`, `notes`, `clean`, and `root` also work and are deliberately not contract: `run` spawns with inherited stdio and can never emit an envelope, `nightly` is called by the scheduler, and the rest are conveniences for a person.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joenandez/academy",
-  "version": "0.5.17-rc.1",
+  "version": "0.5.17",
   "description": "Academy v3 — portable AI agents with 8 boot surfaces and a skills primitive.",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
     "knip": "5.70.2"
   },
   "dependencies": {
-    "@joenandez/tldr": "0.3.0-rc.1",
+    "@joenandez/tldr": "0.3.0-rc.3",
     "acpx": "0.21.0"
   }
 }

package/scripts/cli/agent-gate.mjs

@@ -3,11 +3,13 @@ import { join } from 'node:path';
 import { currentAgentName } from './agent-id.mjs';
 import { CLI_NAME, kindOf } from './core.mjs';
 import { printHelmSkip } from './helm-skip.mjs';
+import { ownerJobIds, ownerSessionJobIds, principalJobIds } from './owner-jobs.mjs';
 import { schedulerJobId } from './tldr.mjs';
 import { readAgentYaml } from './yaml.mjs';
 
-// Decision D1: nothing runs until the user signs the mandate, and a stopped
-// agent runs nothing. Job registration and every run entry ask these two.
+// Decision D1: nothing runs until the user signs the mandate. A stopped agent
+// runs no loop job (daily, heartbeat, next, eod, brief); a person, a message
+// wake and the nightly still run. Job registration and every run entry ask these.
 
 // The hire placeholder the Owner mandate template carries until a person
 // writes the mandate. Matched as a substring, so the template may change around it.
@@ -32,14 +34,20 @@ export function isDraftOwner(dir) {
 }
 
 // Of a kind's job ids, nightly first, the ones registered while the agent is
-// in this state: none when stopped, only the nightly for a draft Owner.
+// in this state: only the nightly when stopped or for a draft Owner.
 export function liveJobIds(dir, ids) {
-  if (isStopped(dir)) return [];
-  return isDraftOwner(dir) ? ids.slice(0, 1) : ids;
+  return isStopped(dir) || isDraftOwner(dir) ? ids.slice(0, 1) : ids;
 }
 
-function notStartedReason(dir) {
-  if (isStopped(dir)) return 'agent_stopped';
+// A loop run is a run whose scheduler job id is a loop job's id. Env flags such
+// as ACADEMY_OWNER_RUN do not count: children inherit them.
+const isLoopRun = (id) =>
+  [...ownerJobIds(id), ...ownerSessionJobIds(id), ...principalJobIds(id)].includes(
+    schedulerJobId(),
+  );
+
+function notStartedReason(dir, id) {
+  if (isStopped(dir) && isLoopRun(id)) return 'agent_stopped';
   if (isDraftOwner(dir)) return 'owner_draft';
   return null;
 }
@@ -48,7 +56,7 @@ function notStartedReason(dir) {
 // failed delete included, ends as a skip the scheduler records; a person is
 // told to start the agent.
 export function refuseNotStarted(dir, id) {
-  const reason = notStartedReason(dir);
+  const reason = notStartedReason(dir, id);
   if (!reason) return;
   const jobId = schedulerJobId();
   console.error(
@@ -63,8 +71,10 @@ export function refuseNotStarted(dir, id) {
     printHelmSkip(reason, id);
     process.exit(0);
   }
+  // Only owner_draft reaches a person: agent_stopped needs a loop job id.
   const name = currentAgentName(dir);
-  const state = reason === 'agent_stopped' ? 'is stopped' : 'has no signed mandate';
-  console.error(`Agent "${name}" ${state}. Run \`${CLI_NAME} start ${name}\` to start it.`);
+  console.error(
+    `Agent "${name}" has no signed mandate. Run \`${CLI_NAME} start ${name}\` to start it.`,
+  );
   process.exit(1);
 }

package/scripts/cli/agent-row.mjs

@@ -0,0 +1,24 @@
+import { isDraftOwner, isStopped } from './agent-gate.mjs';
+import { agentIdOf } from './agent-id.mjs';
+import { agentNames, agentRecord } from './inspect.mjs';
+import { toRuntimeToken } from './runtime.mjs';
+
+// One row for tldr's message wake: where to start the agent and on which runtime.
+// Any kind answers. An archived agent is not in the roster, so it reads as unknown.
+// draft: an Owner with no signed mandate, which academy run refuses to start.
+export function printAgentRow(name) {
+  const id = agentIdOf(name);
+  if (!agentNames().includes(id)) {
+    console.error(`Error: "${name}" is not an agent in this Academy.`);
+    process.exit(1);
+  }
+  const { name: agent, dir, runtimeProvider } = agentRecord(id, { strictRuntime: true });
+  const row = {
+    name: agent,
+    cwd: dir,
+    runtime: toRuntimeToken(runtimeProvider),
+    stopped: isStopped(dir),
+    draft: isDraftOwner(dir),
+  };
+  console.log(JSON.stringify(row));
+}

package/scripts/cli/agent-settings.mjs

@@ -0,0 +1,104 @@
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  LockTimeoutError,
+  agentDir,
+  agentLifecycleLockPath,
+  contractOk,
+  exitJsonError,
+  withFileLock,
+} from './core.mjs';
+import { agentRecord } from './inspect.mjs';
+import { writeLead } from './leads.mjs';
+import { preflightOwnedAgent, reportLifecycleFailure } from './lifecycle.mjs';
+import { agentModel, isModelId } from './model.mjs';
+import { rewriteAgentYamlScalar } from './yaml.mjs';
+
+// `set-model` and `lead`: the two settings Academy keeps for a client that
+// cannot keep them itself. Neither is in the frozen v1 command list; both answer
+// in the envelope with the published codes.
+
+function refuse(code, message, fields, json) {
+  if (json) exitJsonError(code, message, fields);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+// `set-model <name> <model> [--json]`: rewrites the agent.yaml `model:` scalar.
+export function setAgentModel({ name, model, json, invalidOption }) {
+  if (invalidOption !== undefined) {
+    const usage = 'Use set-model <name> <model> [--json].';
+    refuse('invalid_spec', `Unknown set-model option: ${invalidOption}. ${usage}`, {}, json);
+  }
+  if (!isModelId(model)) {
+    refuse('invalid_spec', `Model "${model ?? ''}" is not a model id Academy can store.`, {}, json);
+  }
+  const { id } = preflightOwnedAgent(name, json);
+  const dir = agentDir(id);
+  let previousModel;
+  try {
+    withFileLock(agentLifecycleLockPath(dir), () => {
+      previousModel = agentModel(dir);
+      rewriteAgentYamlScalar(dir, 'model', model);
+    });
+  } catch (error) {
+    reportLifecycleFailure(error, 'set the model of', name, json);
+  }
+  if (json) contractOk('set-model', { ...agentRecord(id), previousModel });
+  else console.log(`Default model for "${name}" is now ${model}.`);
+}
+
+const LEAD_USAGE =
+  'Use lead set <agent> --project <path> [--json] or lead clear --project <path> [--json].';
+
+// Checked in order; the first rule that matches names the fault.
+const LEAD_ARG_RULES = [
+  [(a) => a.invalidOption !== undefined, (a) => `Unknown lead option: ${a.invalidOption}.`],
+  [
+    (a) => !['set', 'clear'].includes(a.action),
+    (a) => `Unknown lead action: ${a.action ?? '(none)'}.`,
+  ],
+  [(a) => !a.project, () => 'lead needs --project <path>.'],
+  [(a) => a.action === 'set' && !a.name, () => 'lead set needs an agent.'],
+  [(a) => a.action === 'clear' && a.name, () => 'lead clear takes no agent.'],
+];
+
+function leadArgsFault(parsed) {
+  const rule = LEAD_ARG_RULES.find(([matches]) => matches(parsed));
+  return rule ? rule[1](parsed) : null;
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// `lead set <agent> --project <path>` / `lead clear --project <path>`. One Lead per
+// project: a set replaces the project's previous Lead. The project is its
+// normalized absolute path (relative to the cwd when relative).
+export function leadCommand(parsed) {
+  const { action, name, json } = parsed;
+  const fault = leadArgsFault(parsed);
+  if (fault) refuse('invalid_spec', `${fault} ${LEAD_USAGE}`, {}, json);
+  const project = resolve(parsed.project);
+  let id = null;
+  if (action === 'set') {
+    ({ id } = preflightOwnedAgent(name, json));
+    if (!isDirectory(project)) {
+      refuse('invalid_spec', `Project folder not found: ${project}`, { project }, json);
+    }
+  }
+  let previousLead;
+  try {
+    previousLead = writeLead(project, id);
+  } catch (error) {
+    if (!(error instanceof LockTimeoutError)) throw error;
+    refuse(error.code, error.message, error.fields, json);
+  }
+  if (json) contractOk('lead', { action, project, lead: id, previousLead });
+  else if (id) console.log(`"${name}" now leads ${project}.`);
+  else console.log(`${project} has no Lead.`);
+}

package/scripts/cli/args-kinds.mjs

@@ -1,11 +1,14 @@
-// `create <name> [--kind <kind>] [--no-start] [--json]`. Like `rename`, an option Academy
-// does not know stays on the command so the handler answers it inside the
-// envelope the caller asked for. The kind stays a raw string: only `create` can
-// answer an unsupported one in the envelope.
+// `create <name> [--kind <kind>] [--model <id>] [--display-name <text>] [--no-start]
+// [--json]`. Like
+// `rename`, an option Academy does not know stays on the command so the handler
+// answers it inside the envelope the caller asked for. The kind and model stay
+// raw strings: only `create` can answer an unsupported one in the envelope.
 export function parseCreateArgs(command, rest) {
   const json = rest.includes('--json');
   let name;
   let kind;
+  let model;
+  let displayName;
   let noStart = false;
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
@@ -13,10 +16,14 @@ export function parseCreateArgs(command, rest) {
     else if (arg === '--no-start') noStart = true;
     else if (arg === '--kind') kind = rest[++i] ?? '';
     else if (arg.startsWith('--kind=')) kind = arg.slice('--kind='.length);
+    else if (arg === '--model') model = rest[++i] ?? '';
+    else if (arg.startsWith('--model=')) model = arg.slice('--model='.length);
+    else if (arg === '--display-name') displayName = rest[++i] ?? '';
+    else if (arg.startsWith('--display-name=')) displayName = arg.slice('--display-name='.length);
     else if (arg.startsWith('--')) return { command, json, name, invalidOption: arg };
     else name ??= arg;
   }
-  return { command, json, name, kind, noStart };
+  return { command, json, name, kind, model, displayName, noStart };
 }
 
 // `skills check <agent> [--json]`. Like `create`, an option Academy does not
@@ -31,3 +38,34 @@ export function parseSkillsArgs(command, rest) {
   }
   return { command, json, action: positional[0], name: positional[1] };
 }
+
+// `set-model <name> <model> [--json]`. The model stays a raw string, so the
+// handler answers a missing or unusable one in the envelope.
+export function parseSetModelArgs(command, rest) {
+  const json = rest.includes('--json');
+  const positional = [];
+  for (const arg of rest) {
+    if (arg === '--json') continue;
+    else if (arg.startsWith('--')) return { command, json, invalidOption: arg };
+    else positional.push(arg);
+  }
+  return { command, json, name: positional[0], model: positional[1] };
+}
+
+// `lead set <agent> --project <path> [--json]` and `lead clear --project <path> [--json]`.
+export function parseLeadArgs(command, rest) {
+  const json = rest.includes('--json');
+  const positional = [];
+  let project;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--json') continue;
+    else if (arg === '--project') project = rest[++i] ?? '';
+    else if (arg.startsWith('--project=')) project = arg.slice('--project='.length);
+    else if (arg.startsWith('--')) return { command, json, invalidOption: arg };
+    else positional.push(arg);
+  }
+  const [action, name, extra] = positional;
+  if (extra !== undefined) return { command, json, invalidOption: extra };
+  return { command, json, action, name, project };
+}

package/scripts/cli/args-owner.mjs

@@ -1,15 +1,19 @@
-// `rename <old> <new> [--json]`. Like `events`, `migrate` and `sessions`, an
-// option Academy does not know stays on the command so the handler answers it
-// inside the envelope the caller asked for.
+// `rename <old> [<new>] [--display-name <text>] [--json]`. Like `events`,
+// `migrate` and `sessions`, an option Academy does not know stays on the command
+// so the handler answers it inside the envelope the caller asked for.
 export function parseRenameArgs(command, rest) {
   const json = rest.includes('--json');
   const positional = [];
-  for (const arg of rest) {
+  let displayName;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
     if (arg === '--json') continue;
+    else if (arg === '--display-name') displayName = rest[++i] ?? '';
+    else if (arg.startsWith('--display-name=')) displayName = arg.slice('--display-name='.length);
     else if (arg.startsWith('--')) return { command, json, invalidOption: arg };
     else positional.push(arg);
   }
-  return { command, json, name: positional[0], newName: positional[1] };
+  return { command, json, name: positional[0], newName: positional[1], displayName };
 }
 
 const START_OPTIONS = {

package/scripts/cli/args.mjs

@@ -1,4 +1,9 @@
-import { parseCreateArgs, parseSkillsArgs } from './args-kinds.mjs';
+import {
+  parseCreateArgs,
+  parseLeadArgs,
+  parseSetModelArgs,
+  parseSkillsArgs,
+} from './args-kinds.mjs';
 import { parseNotesArgs } from './args-notes.mjs';
 import { parseRenameArgs, parseStartArgs } from './args-owner.mjs';
 import { parseRunArgs } from './args-run.mjs';
@@ -30,10 +35,7 @@ const COMMAND_PARSERS = {
   archive: (command, rest) => namedJsonCommand(command, rest),
   unarchive: (command, rest) => namedJsonCommand(command, rest),
   sessions: (command, rest) => parseSessionsArgs(command, rest),
-  list: (command, rest) =>
-    hasFlag(rest, '--slack-rows')
-      ? { command, slackRows: true, name: rest.find((arg) => !arg.startsWith('--')) }
-      : jsonOnlyCommand(command, rest),
+  list: (command, rest) => parseListArgs(command, rest),
   inspect: (command, rest) => namedJsonCommand(command, rest),
   tokens: (command, rest) => namedJsonCommand(command, rest),
   budget: (command, rest) => namedJsonCommand(command, rest),
@@ -47,6 +49,8 @@ const COMMAND_PARSERS = {
   root: (command, rest) => jsonOnlyCommand(command, rest),
   notes: (_command, rest) => parseNotesArgs(rest),
   skills: (command, rest) => parseSkillsArgs(command, rest),
+  'set-model': (command, rest) => parseSetModelArgs(command, rest),
+  lead: (command, rest) => parseLeadArgs(command, rest),
 };
 
 export function parseArgs(argv) {
@@ -62,6 +66,13 @@ function hasFlag(args, flag) {
   return args.includes(flag);
 }
 
+function parseListArgs(command, rest) {
+  const named = rest.find((arg) => !arg.startsWith('--'));
+  if (hasFlag(rest, '--slack-rows')) return { command, slackRows: true, name: named };
+  if (hasFlag(rest, '--agent-row')) return { command, agentRow: true, name: named };
+  return jsonOnlyCommand(command, rest);
+}
+
 function jsonOnlyCommand(command, rest) {
   return { command, json: hasFlag(rest, '--json') };
 }
@@ -163,9 +174,20 @@ Usage: ${CLI_NAME} <command> [options]
 
 Commands:
   doctor [--json]         Report Academy's version, roots, runtimes, and capability
-  create [<name>] [--kind specialist|principal|owner] [--no-start] [--json]
+  create [<name>] [--kind specialist|principal|owner] [--model <id>]
+         [--display-name <text>] [--no-start] [--json]
                           Scaffold a portable agent at ~/.academy/agents/<name>/ (default
-                          specialist); a terminal Principal opens its first session
+                          specialist); a terminal Principal opens its first session;
+                          --model stores its default model; --display-name stores a
+                          person-facing name ("Principal Two"); <name> stays kebab-case
+  set-model <name> <model> [--json]
+                          Change an agent's default model; run passes it to the
+                          runtime (Claude --model, Codex -m) unless the caller does
+  lead set <agent> --project <path> [--json]
+                          Make <agent> the Lead of a project, replacing any
+                          previous Lead (one per project)
+  lead clear --project <path> [--json]
+                          Remove a project's Lead
   hire                    Interactive hire flow — produces 8 boot files via Claude Code
   hire --spec <path> [--json]
                           Headless hire from a JSON specification file
@@ -184,21 +206,26 @@ Commands:
   sessions [--agent <name>] [--json]
                           List sessions whose agent directory is inside
                           AGENTS_ROOT
-  rename <old> <new> [--json]
+  rename <old> [<new>] [--display-name <text>] [--json]
                           Change an agent's name: the name: field and the seeded
                           name lines. No folder moves and no job changes; safe
-                          any time, also mid-session
+                          any time, also mid-session. --display-name sets the
+                          display name; without <new> it changes only that
   start <name> [--mandate <file>] [--hours <h>] [--contact <c>] [--trust 1-4] [--json]
                           Start an agent and register its jobs; an Owner needs a
                           signed mandate and gets one first daily run
-  stop <name> [--json]    Stop an agent and delete its jobs; its files stay
+  stop <name> [--json]    Turn off an agent's loop; it stays available and keeps
+                          its nightly
   archive <name> [--json] Move an agent into the archived holding area
   unarchive <name> [--json]
                           Restore an archived agent to its canonical slot
-  list                    List all agents
+  list [--json]           List all agents; --json records add model, created_by
+                          (user, a creating agent's id, or null) and lead_of
   list --slack-rows [<name>]
                           Print Slack launch rows {name, cwd, runtime, command}
                           for every Owner and Principal, or only <name>
+  list --agent-row <name> Print one JSON row for any agent:
+                          {name, cwd, runtime, stopped, draft}
   inspect <name>          Inspect one agent
   tokens <name>           Estimate generated prompt tokens by surface
   budget <name>           Check prompt token budget by surface
@@ -212,6 +239,9 @@ Examples:
   ${CLI_NAME} doctor --json
   ${CLI_NAME} create kai
   ${CLI_NAME} create ada --kind principal --json
+  ${CLI_NAME} create ada --kind principal --model opus --json
+  ${CLI_NAME} set-model ada sonnet --json
+  ${CLI_NAME} lead set ada --project ~/Dev/app --json
   ${CLI_NAME} hire
   ${CLI_NAME} hire --spec ./kai.json --json
   ${CLI_NAME} run kai
@@ -222,6 +252,7 @@ Examples:
   ${CLI_NAME} migrate --dry-run --json
   ${CLI_NAME} sessions --agent kai --json
   ${CLI_NAME} rename kai nova --json
+  ${CLI_NAME} rename principal-two --display-name "Principal Two" --json
   ${CLI_NAME} start owner-one --mandate ./mandate.md --trust 3 --json
   ${CLI_NAME} stop owner-one --json
   ${CLI_NAME} notes add "User prefers short status updates before edits"

package/scripts/cli/copilot/child-env.mjs

@@ -50,6 +50,8 @@ export function childEnvironment(env) {
     // The daemon's managed-resume launch binding must survive the child boundary.
     'TIGHTBEAM_LAUNCH_MODE',
     'TIGHTBEAM_LAUNCH_TOKEN',
+    // A cold start names the placeholder its SessionStart must adopt.
+    'TIGHTBEAM_PLACEHOLDER_ENDPOINT_ID',
     'TLDR_AGENT_HOME',
     // Academy's generated Beads store, session actor and telemetry switch; acpx lets the
     // parent's values win over any name not listed here.