@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/owner-jobs.mjs

@@ -0,0 +1,201 @@
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isDraftOwner } from './agent-gate.mjs';
+import { AGENTS_ROOT, RuntimeUnavailableError, kindOf } from './core.mjs';
+import { localTimezone, runSchedule } from './create.mjs';
+import { ownerConfig, ownerDailyCron, ownerHeartbeatCron } from './owner-config.mjs';
+import { runtimeProviderOrNull } from './runtime.mjs';
+import { resolveTldrAgentsBinary, spawnTldrTasksArgs, tldrSpawnOptions } from './tldr.mjs';
+
+// An Owner's two Academy jobs beside its nightly: the daily open and the
+// heartbeat. Registered by `registerAcademyJobs` in create.mjs and deleted by
+// id through `academyJobIds` in lifecycle.mjs.
+
+export const ownerJobIds = (name) => [`${name}-owner-daily`, `${name}-owner-heartbeat`];
+
+// A Principal's morning brief job, beside its nightly. Built from the folder id.
+export const principalJobIds = (name) => [`${name}-principal-brief`];
+
+// The Owner schedules these one-off sessions itself through the router skill, so
+// the CLI never registers them; lifecycle must still delete them by id.
+export const ownerSessionJobIds = (name) => [`${name}-owner-next`, `${name}-owner-eod`];
+
+const OWNER_ROUTES = {
+  daily: 'Daily open: use the owner-work skill.',
+  heartbeat: 'Scheduled heartbeat: use the owner-heartbeat skill.',
+};
+
+// Every Owner job that runs through the Academy provider, the nightly included,
+// names the runtime: the provider builds a different argv for each one.
+export function academyRuntimeArgs(dir) {
+  return ['--academy-runtime', runtimeProviderOrNull(dir) === 'codex' ? 'codex' : 'claude'];
+}
+
+// A daily run can last the whole work session, so both jobs get its length.
+const OWNER_JOB_TIMEOUT_SEC = '10800';
+const ownerJob = (run) => ({
+  route: OWNER_ROUTES[run],
+  tags: `academy,owner,${run}`,
+  timeoutSec: OWNER_JOB_TIMEOUT_SEC,
+});
+const BRIEF_JOB = {
+  route: 'Morning brief: use the principal-brief skill.',
+  tags: 'academy,principal,brief',
+  timeoutSec: '3600',
+};
+
+// The provider jobs beside a registered nightly: an Owner's daily open and
+// heartbeat, a Principal's 07:00 morning brief (an ordinary run with its prompt,
+// no run flag). A provider run finds its agent only in the default root, so each
+// set warns when registered elsewhere; a Principal's nightly is a command job
+// with its env, so it is not in the warning. Other kinds have none.
+export function registerKindTasks(dir, name, nightly) {
+  const kind = kindOf(dir);
+  if (kind === 'owner') return warnOnNamedAgentsRoot([nightly, ...registerOwnerTasks(dir, name)]);
+  if (kind !== 'principal') return [nightly];
+  const [id] = principalJobIds(name);
+  const schedule = ['--cron', '0 7 * * *', '--timezone', localTimezone()];
+  return [
+    nightly,
+    ...warnOnNamedAgentsRoot([scheduleOwnerJob(dir, name, id, BRIEF_JOB, schedule)]),
+  ];
+}
+
+// The daily open and the heartbeat. Like the Owner nightly they name a
+// runtime, and `run --agent` re-registers the set whenever the runtime changes.
+// They carry no job env: the scheduler refuses env on a provider job and would
+// not pass it to the run. `academy run` derives ACADEMY_OWNER_RUN from the job
+// id instead (run-context.mjs). Both are cron lines in owner_timezone, so the
+// schedule alone keeps them inside owner_hours. A draft Owner (no signed
+// mandate) gets neither: nothing runs until the user signs it.
+function registerOwnerTasks(dir, name) {
+  if (isDraftOwner(dir)) return [];
+  const { owner_hours, owner_timezone, owner_heartbeat } = ownerConfig(dir);
+  const [dailyId, heartbeatId] = ownerJobIds(name);
+  const timezone = ['--timezone', owner_timezone];
+  const dailyCron = ownerDailyCron(owner_hours);
+  const daily = dailyCron
+    ? scheduleOwnerJob(dir, name, dailyId, ownerJob('daily'), ['--cron', dailyCron, ...timezone])
+    : unscheduled(dailyId, `owner_hours "${owner_hours}" has no opening time`);
+  const heartbeatCron = ownerHeartbeatCron(owner_hours, owner_heartbeat);
+  const heartbeat = heartbeatCron
+    ? scheduleOwnerJob(dir, name, heartbeatId, ownerJob('heartbeat'), [
+        '--cron',
+        heartbeatCron,
+        ...timezone,
+      ])
+    : unscheduled(
+        heartbeatId,
+        `owner_hours "${owner_hours}" with owner_heartbeat "${owner_heartbeat}" has no heartbeat cron`,
+      );
+  return [daily, heartbeat];
+}
+
+const unscheduled = (id, reason) => ({ id, registered: false, reason });
+
+// The permission mode a new Owner job runs with. tldr stores it on the job and
+// renders it into the provider argv, so it is visible and editable in tldr.
+const DEFAULT_PERMISSION_MODE = { claude: 'bypassPermissions', codex: 'danger-full-access' };
+
+function tldrTasks(bin, dir, args, input) {
+  const result = spawnSync(bin, spawnTldrTasksArgs(args), tldrSpawnOptions(dir, { input }));
+  if (result.error || result.status !== 0) return null;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return {};
+  }
+}
+
+// `tasks schedule` does not store `--permission-mode` for a provider job, and a
+// partial patch replaces the job's execution hints, so this reads the job and
+// writes its whole hints back with the default. A mode the user chose is never
+// changed. Academy's default for the other runtime is not valid for this one,
+// so a runtime change swaps it.
+function permissionModeFor(dir, stored) {
+  const runtime = runtimeProviderOrNull(dir) === 'codex' ? 'codex' : 'claude';
+  const other = DEFAULT_PERMISSION_MODE[runtime === 'codex' ? 'claude' : 'codex'];
+  return stored && stored !== other ? null : DEFAULT_PERMISSION_MODE[runtime];
+}
+
+function ensurePermissionMode(bin, dir, id) {
+  const hints = tldrTasks(bin, dir, ['get', '--cwd', dir, '--id', id, '--json'])?.data?.job
+    ?.execution_hints;
+  const config = hints?.provider_config;
+  const mode = config && permissionModeFor(dir, config.runtime_options?.permission_mode);
+  let result = config ? 'kept' : 'unknown';
+  if (mode) {
+    const runtimeOptions = { ...config.runtime_options, permission_mode: mode };
+    const patch = {
+      execution_hints: {
+        ...hints,
+        provider_config: { ...config, runtime_options: runtimeOptions },
+      },
+    };
+    const args = ['update', '--cwd', dir, '--id', id, '--stdin', '--json'];
+    result = tldrTasks(bin, dir, args, JSON.stringify(patch)) ? 'set' : 'failed';
+  }
+  // Quiet when it worked: lifecycle `--json` clients read stderr for the error
+  // envelope, so only a problem earns a line there.
+  if (result === 'set' || result === 'kept') return;
+  console.error(
+    JSON.stringify({ event: 'jobs.permission_mode', status: 'warn', params: { job: id }, result }),
+  );
+}
+
+function scheduleOwnerJob(dir, name, id, { route, tags, timeoutSec }, schedule) {
+  let tldrAgentsBin;
+  try {
+    tldrAgentsBin = resolveTldrAgentsBinary();
+  } catch (error) {
+    if (!(error instanceof RuntimeUnavailableError)) throw error;
+    return { id, registered: false, reason: error.message };
+  }
+  const args = spawnTldrTasksArgs([
+    'schedule',
+    '--cwd',
+    dir,
+    '--id',
+    id,
+    ...schedule,
+    '--provider',
+    'academy',
+    '--academy-agent',
+    name,
+    ...academyRuntimeArgs(dir),
+    '--prompt',
+    route,
+    '--overlap-policy',
+    'forbid',
+    '--merge',
+    '--tags',
+    tags,
+    '--timeout-sec',
+    timeoutSec,
+  ]);
+  const job = runSchedule(tldrAgentsBin, dir, id, args);
+  if (job.registered) ensurePermissionMode(tldrAgentsBin, dir, id);
+  return job;
+}
+
+// A provider run gets no job env, so no AGENTS_ROOT: `academy run` looks for
+// the agent under the default root. An agent anywhere else registers, but its
+// provider jobs will not find it, so the registration says so. A set with a
+// failed job is reported as that failure instead.
+function warnOnNamedAgentsRoot(jobs) {
+  const agentsRoot = resolve(AGENTS_ROOT);
+  if (agentsRoot === join(homedir(), '.academy', 'agents')) return jobs;
+  if (jobs.some((job) => !job.registered && !job.skipped)) return jobs;
+  const ids = jobs.filter((job) => job.registered).map((job) => job.id);
+  const warning = `Provider jobs run under the default AGENTS_ROOT (~/.academy/agents), not ${agentsRoot}; they will not find this agent`;
+  console.error(
+    JSON.stringify({
+      event: 'jobs.agents_root',
+      status: 'warn',
+      message: warning,
+      params: { agentsRoot, jobs: ids },
+    }),
+  );
+  return jobs.map((job) => (job.registered ? { ...job, warning } : job));
+}

package/scripts/cli/prompt-append.mjs

@@ -0,0 +1,135 @@
+import { readFileSync } from 'node:fs';
+import { decodeTomlString } from './toml-string.mjs';
+
+// Academy's prompt is appended to the provider's own prompt, never a
+// replacement for it. A launch carries exactly one Academy appended-prompt
+// value (Claude: inline text; Codex: one key); a prompt the caller already
+// appends in the passthrough is folded in after Academy's, and its own flag is
+// dropped.
+//
+// Why Claude gets the inline form: Claude keeps only the last value of each
+// append form, but one `--append-system-prompt <text>` and one
+// `--append-system-prompt-file <path>` combine. A host's terminal wrapper can put
+// its own `--append-system-prompt-file` ahead of our arguments, so a file flag
+// from Academy would replace the host's session context. The inline form
+// leaves the file form to the wrapper. An incoming file flag is merged into our
+// inline value too (not left in the passthrough): an Agent Pane launch through
+// that wrapper would otherwise carry two file flags, and one would be lost.
+
+const CLAUDE_INLINE_FLAG = '--append-system-prompt';
+const CLAUDE_FILE_FLAG = '--append-system-prompt-file';
+const CODEX_KEY = 'developer_instructions';
+
+function logAppend(runtime, incomingCount, bytes) {
+  console.error(
+    JSON.stringify({
+      event: 'run.prompt_append',
+      params: { runtime: runtime ?? 'claude', incoming: incomingCount },
+      result: { bytes },
+      status: 'merged',
+    }),
+  );
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+// Splits `argv` into the arguments that are not an incoming prompt and the
+// incoming values, in order. `match(arg, next)` returns `{ value, consumed }`
+// for an argument that carries one, else undefined.
+function takeIncoming(argv, match) {
+  const rest = [];
+  const values = [];
+  for (let i = 0; i < argv.length; i++) {
+    const hit = match(argv[i], argv[i + 1]);
+    if (!hit) {
+      rest.push(argv[i]);
+      continue;
+    }
+    values.push(hit.value);
+    i += hit.consumed - 1;
+  }
+  return { rest, values };
+}
+
+// An incoming Claude append: `{ value, consumed, file }` for either flag in
+// either spelling (`--flag v` or `--flag=v`), else undefined.
+function matchClaudeAppend(arg, next) {
+  for (const [flag, file] of [
+    [CLAUDE_FILE_FLAG, true],
+    [CLAUDE_INLINE_FLAG, false],
+  ]) {
+    if (arg === flag) {
+      if (next === undefined) fail(`${flag} needs ${file ? 'a file path' : 'text'}`);
+      return { value: { text: next, file }, consumed: 2 };
+    }
+    if (arg.startsWith(`${flag}=`)) {
+      return { value: { text: arg.slice(flag.length + 1), file }, consumed: 1 };
+    }
+  }
+  return undefined;
+}
+
+// Every spelling of a Codex override that carries `developer_instructions`:
+// `-c k=v`, `-c=k=v`, `-ck=v`, `--config k=v` and `--config=k=v`. Other keys
+// are not matched, so they stay in the passthrough.
+const CODEX_INSTRUCTIONS = new RegExp(`^${CODEX_KEY}\\s*=\\s*(.*)$`, 's');
+const CODEX_ATTACHED = /^(?:-c=?|--config=)/;
+
+function instructionsValue(kv) {
+  const value = CODEX_INSTRUCTIONS.exec(kv)?.[1];
+  return value === undefined ? undefined : decodeTomlString(value);
+}
+
+function matchCodexInstructions(arg, next) {
+  if (arg === '-c' || arg === '--config') {
+    if (next === undefined) fail(`${arg} needs a value`);
+    const value = next === undefined ? undefined : instructionsValue(next);
+    return value === undefined ? undefined : { value, consumed: 2 };
+  }
+  const attached = CODEX_ATTACHED.exec(arg);
+  const value = attached ? instructionsValue(arg.slice(attached[0].length)) : undefined;
+  return value === undefined ? undefined : { value, consumed: 1 };
+}
+
+function readIncomingFile(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (error) {
+    return fail(`cannot read ${CLAUDE_FILE_FLAG} ${path}: ${error.message}`);
+  }
+}
+
+const incomingClaudeText = ({ text, file }) => (file ? readIncomingFile(text) : text);
+
+const joinPrompts = (academy, incoming) =>
+  [academy.trimEnd(), ...incoming.map((text) => text.trim())].join('\n\n') + '\n';
+
+/**
+ * The one place a launch decides how Academy's prompt reaches the provider.
+ * `promptPath` holds the rendered Academy prompt. Returns the provider args that
+ * carry it and the passthrough with any incoming appended prompt removed.
+ *
+ * Claude: the prompt (plus any incoming one, after it) is passed as
+ * `--append-system-prompt <text>`; no file is written per run.
+ * Codex: pending spike S2 confirmation, the merged prompt is passed as
+ * `-c developer_instructions=<JSON string>`.
+ */
+export function appendedPromptLaunch({ runtime, promptPath, passthrough }) {
+  const academy = readFileSync(promptPath, 'utf8');
+  const codex = runtime === 'codex';
+  const { rest, values } = takeIncoming(
+    passthrough,
+    codex ? matchCodexInstructions : matchClaudeAppend,
+  );
+  const incoming = codex ? values : values.map(incomingClaudeText);
+  const prompt = incoming.length ? joinPrompts(academy, incoming) : academy;
+  if (incoming.length) logAppend(runtime, incoming.length, prompt.length);
+
+  const promptArgs = codex
+    ? ['-c', `${CODEX_KEY}=${JSON.stringify(prompt)}`]
+    : [CLAUDE_INLINE_FLAG, prompt];
+  return { promptArgs, passthrough: rest };
+}

package/scripts/cli/rename.mjs

@@ -1,6 +1,5 @@
-import { existsSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { readJsonFile } from './codex.mjs';
 import {
   agentDir,
   agentLifecycleLockPath,
@@ -9,126 +8,84 @@ import {
   validateName,
   withFileLock,
 } from './core.mjs';
+import { liveJobIds } from './agent-gate.mjs';
+import { agentIdOrNull, currentAgentName } from './agent-id.mjs';
 import { archivedAgentDir, assertNotArchived, isArchivedAgent } from './archived.mjs';
-import { registerNightlyConsolidationTask } from './create.mjs';
-import { appendLifecycleEvent } from './eventlog.mjs';
+import { jobLabel } from './create.mjs';
+import { appendLifecycleEvent, withRootEventLock } from './eventlog.mjs';
 import { agentRecord } from './inspect.mjs';
 import {
   DeleteAgentError,
   assertOwnedAgentForDelete,
-  deleteJsonError,
-  deleteNightlyConsolidation,
+  kindJobIds,
   preflightOwnedAgent,
   reportLifecycleFailure,
 } from './lifecycle.mjs';
 import { AgentSpecError, rewriteAgentYamlScalar } from './yaml.mjs';
 
-// `rename <old> <new>`. The ownership marker is the blocker: both validators
-// reject a directory whose marker names another agent, so a rename that moved
-// the directory without rewriting `.academy-agent.json` would leave the agent
-// permanently `not_academy_owned` — no delete, no archive, no second rename.
-// The move, the marker and the `name:` scalar are therefore one critical
-// section, and the lock is taken exactly once around all three.
+// `rename <old> <new>` writes the agent.yaml `name:` scalar and nothing else
+// that identifies the agent. The folder is the fixed id: live sessions hold its
+// absolute path, and the scheduled jobs, the ownership marker and the Beads
+// labels are keyed on it, so a rename is safe at any time, mid-session too.
 
 export function renameAgent(name, newName, json, invalidOption) {
   if (invalidOption !== undefined) return unreadableInvocation(invalidOption, json);
-  preflightOwnedAgent(name, json);
+  const { id } = preflightOwnedAgent(name, json);
   validateName(newName);
-  // The target name is asked the same two questions `create` asks it, and for
-  // the same reason `create` asks them: a live agent moved onto a name the
-  // holding area already owns leaves two records under one name, and every
-  // published command then answers `agent_archived` for the live one. No
-  // published command can reach it again.
   assertNotArchived(newName, json);
-  refuseExistingTarget(newName, json);
   try {
-    withFileLock(agentLifecycleLockPath(agentDir(name)), () =>
-      renameAgentLocked(name, newName, json),
-    );
+    withFileLock(agentLifecycleLockPath(agentDir(id)), () => renameAgentLocked(id, newName, json));
   } catch (error) {
     reportLifecycleFailure(error, 'rename', name, json);
   }
 }
 
-// Refused before the lock is taken, because every exit path here ends the
-// process and a lock released by nothing would strand the agent for good.
-function refuseExistingTarget(newName, json) {
-  const target = agentDir(newName);
-  if (!existsSync(target)) return;
-  deleteJsonError(
-    'agent_exists',
-    `Agent "${newName}" already exists at ${resolve(target)}`,
-    { name: newName, dir: resolve(target) },
-    json,
-  );
-}
-
-function renameAgentLocked(name, newName, json) {
-  const { dirReal } = assertOwnedAgentForDelete(name, agentDir(name));
+function renameAgentLocked(id, newName, json) {
   // Reported as the absolute joined path, never the realpath: a client keying
   // agents on `dir` matches this against the record `create` gave it.
-  const previousDir = resolve(agentDir(name));
-  const target = agentDir(newName);
-  if (existsSync(target)) {
-    throw new DeleteAgentError(
-      'agent_exists',
-      `Agent "${newName}" already exists at ${resolve(target)}`,
-      { name: newName, dir: resolve(target) },
-    );
-  }
-  refuseArchivedTarget(newName);
-  // Named by the joined path, like every other path this command reports.
-  assertRewritableAgentYaml(previousDir);
+  const dir = resolve(agentDir(id));
+  assertOwnedAgentForDelete(id, dir);
+  assertRewritableAgentYaml(dir);
+  const previousName = currentAgentName(dir);
+
+  // The final check and the write share the root event lock with `create`'s
+  // name claim, so one name is never taken twice. The checks inside throw, so
+  // the lock releases before any exit and before the event append takes it.
+  withRootEventLock(() => {
+    refuseTakenName(id, newName);
+    // The unlocked writer: this section already holds the agent's lifecycle lock.
+    rewriteAgentYamlScalar(dir, 'name', newName);
+  });
+  renameSeededText(dir, previousName, newName);
+
+  // An append failure is reported and the new name stands, as `createAgent`
+  // reports a failed publish.
+  appendLifecycleEvent('agent_renamed', newName, dir, { previousName, previousDir: dir });
+  reportRenamed({ id, dir, previousName, newName, json });
+}
 
-  // Unschedule before the move. Registration replaces on the *new* identifier,
-  // so an old job left behind would fire nightly against a directory that has
-  // moved, forever.
-  const unscheduled = deleteNightlyConsolidation(name, dirReal);
-  if (!unscheduled.ok) {
+// Taken means any other live or archived agent's id or current name. The
+// agent's own id or name is free to it, so a rename back to the id works.
+function refuseTakenName(id, newName) {
+  const holder = agentIdOrNull(newName);
+  if (holder === null || holder === id) return;
+  const archived = isArchivedAgent(holder);
+  const dir = resolve(archived ? archivedAgentDir(holder) : agentDir(holder));
+  if (archived) {
     throw new DeleteAgentError(
-      unscheduled.code ?? 'unschedule_failed',
-      `Refusing to rename "${name}" because nightly unschedule failed: ${unscheduled.reason}`,
-      { name },
+      'agent_archived',
+      `Agent "${newName}" is archived at ${dir}. Unarchive it first.`,
+      { name: newName, dir },
     );
   }
-
-  renameSync(dirReal, target);
-  rewriteOwnershipMarker(target, newName);
-  // The unlocked writer: this section already holds the agent's lifecycle lock,
-  // and `writeAgentYamlScalar` would take the same lock again and time out.
-  rewriteAgentYamlScalar(target, 'name', newName);
-  assertOwnedAgentForDelete(newName, target);
-  const nightly = registerNightlyConsolidationTask(target, newName);
-
-  // The move is complete and consistent by here. An append failure is reported
-  // and the move stands, as `createAgent` reports a failed publish: unwinding a
-  // rename whose old scheduled job is already gone would lose more than it
-  // repairs.
-  appendLifecycleEvent('agent_renamed', newName, resolve(target), {
-    previousName: name,
-    previousDir,
+  throw new DeleteAgentError('agent_exists', `Agent "${newName}" already exists at ${dir}`, {
+    name: newName,
+    dir,
   });
-  reportRenamed({ name, newName, previousDir, target, unscheduled, nightly, json });
 }
 
-// Mirrored inside the lock exactly as `existsSync(target)` is mirrored above:
-// an agent archived between the preflight and the lock must not be overwritten
-// by a rename that checked before the holding area claimed the name.
-function refuseArchivedTarget(newName) {
-  if (!isArchivedAgent(newName)) return;
-  const dir = resolve(archivedAgentDir(newName));
-  throw new DeleteAgentError(
-    'agent_archived',
-    `Agent "${newName}" is archived at ${dir}. Unarchive it first.`,
-    { name: newName, dir },
-  );
-}
-
-// The `name:` scalar is rewritten after the move, so a rewrite that throws
-// there leaves the directory moved, the marker rewritten, the old nightly job
-// unregistered, the new one never registered and no `agent_renamed` event
-// appended — while the client is told the rename failed. Proved rewritable
-// before any of it, the same refusal costs nothing.
+// Proved rewritable before the name claim, so an agent.yaml Academy cannot
+// write is refused with nothing changed.
 function assertRewritableAgentYaml(dir) {
   const path = join(dir, 'agent.yaml');
   if (statSync(path).isFile()) return;
@@ -137,31 +94,55 @@ function assertRewritableAgentYaml(dir) {
   });
 }
 
-// The marker is rewritten, not rewritten from scratch: `createdAt` records when
-// the agent was hired, which a rename does not change.
-function rewriteOwnershipMarker(dir, name) {
-  const path = join(dir, '.academy-agent.json');
-  const marker = readJsonFile(path, {});
-  writeFileSync(path, `${JSON.stringify({ ...marker, name }, null, 2)}\n`);
+// Only the line create seeded changes: the first match in its file, which
+// sits above anything the user adds. Every other line stays, where
+// `writeAgentClaudeMd` would replace them all. Names match NAME_RE, so they
+// need no regex escaping.
+const youAre = (old, name) => [new RegExp(`^You are ${old}([.,])`, 'm'), `You are ${name}$1`];
+const SEEDED_LINES = {
+  'identity.md': youAre,
+  'mandate.md': youAre,
+  'CLAUDE.md': (old, name) => [new RegExp(`^# ${old}$`, 'm'), `# ${name}`],
+};
+
+function renameSeededText(dir, previousName, newName) {
+  for (const [file, seeded] of Object.entries(SEEDED_LINES)) {
+    const path = join(dir, file);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, 'utf8');
+    let renamed = text.replace(...seeded(previousName, newName));
+    if (file === 'CLAUDE.md') {
+      renamed = renamed.replace(`\`academy run ${previousName}\``, `\`academy run ${newName}\``);
+    }
+    if (renamed !== text) writeFileSync(path, renamed);
+  }
 }
 
-function reportRenamed({ name, newName, previousDir, target, unscheduled, nightly, json }) {
-  const scheduledJobId = nightly.registered ? nightly.id : null;
+function reportRenamed({ id, dir, previousName, newName, json }) {
   if (json) {
+    // The jobs keep their fixed-id names and none is unscheduled. Read from the
+    // agent's state, not from tldr: a stopped agent or a draft Owner has fewer.
+    const scheduledJobIds = liveJobIds(dir, kindJobIds(id, dir));
     contractOk('rename', {
       renamed: true,
-      ...agentRecord(newName),
-      previousName: name,
-      previousDir,
-      unscheduledJobId: unscheduled.id,
-      scheduledJobId,
+      ...agentRecord(id),
+      previousName,
+      previousDir: dir,
+      unscheduledJobId: null,
+      unscheduledJobIds: [],
+      scheduledJobId: scheduledJobIds[0] ?? null,
+      scheduledJobIds,
     });
     return;
   }
-  console.log(`Renamed agent "${name}" to "${newName}" (${previousDir} → ${resolve(target)}).`);
-  console.log(`Unregistered nightly consolidation job "${unscheduled.id}".`);
-  if (scheduledJobId) console.log(`Registered nightly consolidation job "${scheduledJobId}".`);
-  else console.log(`Nightly consolidation job not registered: ${nightly.reason}`);
+  console.log(`Renamed agent "${previousName}" to "${newName}". Folder ${dir} and jobs unchanged.`);
+}
+
+export function reportRegisteredJobs(jobs) {
+  for (const job of jobs) {
+    if (job.registered) console.log(`Registered ${jobLabel(job.id)} "${job.id}".`);
+    else console.log(`${jobLabel(job.id)} "${job.id}" not registered: ${job.reason}`);
+  }
 }
 
 function unreadableInvocation(option, json) {

package/scripts/cli/run-context.mjs

@@ -0,0 +1,50 @@
+import { NIGHTLY_JOB_FLAG } from './nightly.mjs';
+import { ownerJobIds } from './owner-jobs.mjs';
+import { OWNER_RUN_FLAG } from './heartbeat.mjs';
+import { schedulerJobId } from './tldr.mjs';
+
+// An Academy-provider job reaches `academy run` with no job env: the scheduler
+// sets only its own context, which names the job. Its run flags are derived
+// from that id once, at the run entry, and written to process.env, so the
+// heartbeat check and every child after see explicit flags and never derive
+// again. Command jobs and tests keep setting the flags explicitly.
+
+// Any of these present means the run type is already decided. The nightly
+// child carries ACADEMY_NIGHTLY_RUN and the scheduler's job id it inherited,
+// so this is also what keeps it from entering the nightly routine again.
+const RUN_FLAGS = [OWNER_RUN_FLAG, NIGHTLY_JOB_FLAG, 'ACADEMY_NIGHTLY_RUN'];
+
+function flagsByJobId(name) {
+  const [dailyId, heartbeatId] = ownerJobIds(name);
+  return {
+    [`${name}-nightly-consolidation`]: { [NIGHTLY_JOB_FLAG]: '1' },
+    [dailyId]: { [OWNER_RUN_FLAG]: 'daily' },
+    [heartbeatId]: { [OWNER_RUN_FLAG]: 'heartbeat' },
+  };
+}
+
+/** The run flags the scheduler context implies for `name`. Pure. */
+export function deriveRunFlags(name, env) {
+  const jobId = schedulerJobId(env);
+  if (!jobId) return { jobId: null, derived: {}, reason: 'no_job' };
+  if (RUN_FLAGS.some((flag) => env[flag])) return { jobId, derived: {}, reason: 'explicit_flags' };
+  const derived = flagsByJobId(name)[jobId];
+  return derived
+    ? { jobId, derived, reason: 'academy_job' }
+    : { jobId, derived: {}, reason: 'other_job' };
+}
+
+// A job that is not one of this agent's Academy jobs (a one-off, another
+// assignment) derives nothing and runs the way a user's run does.
+export function applyRunContext(name, env = process.env) {
+  const { jobId, derived, reason } = deriveRunFlags(name, env);
+  if (!jobId) return;
+  Object.assign(env, derived);
+  console.error(
+    JSON.stringify({
+      event: 'run.context',
+      params: { agent: name, jobId },
+      result: { derived, reason },
+    }),
+  );
+}