@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/inspect.mjs

@@ -3,15 +3,14 @@ import { join, resolve } from 'node:path';
 import {
   AGENTS_ROOT,
   CLI_NAME,
-  ENFORCED_SURFACES,
+  KIND_PROFILES,
   NAME_RE,
-  SURFACES,
-  SURFACE_CAPS,
-  TOTAL_SURFACE_CAP,
   agentDir,
   checkAgentsRoot,
   contractOk,
   exitJsonError,
+  kindOf,
+  surfacesFor,
   validateName,
 } from './core.mjs';
 import { archivedAgentDir, archivedAgentNames, assertNotArchived } from './archived.mjs';
@@ -20,6 +19,7 @@ import { readEventLogWatermark } from './eventlog.mjs';
 import { readRuntimeProvider, runtimeProviderOrNull } from './runtime.mjs';
 import { academySystemPromptPath, buildAcademySystemPrompt, tokenRecord } from './scaffold.mjs';
 import { readAgentYaml } from './yaml.mjs';
+import { currentAgentName } from './agent-id.mjs';
 
 export function listAgents() {
   const entries = agentNames();
@@ -33,9 +33,12 @@ export function listAgents() {
   }
 }
 
-function printRosterLine(name, dir, prefix) {
+// The current name, and the fixed id after it when a rename made them differ.
+function printRosterLine(id, dir, prefix) {
   const role = readAgentYaml(dir).role || '(no role set)';
-  console.log(`  ${(prefix + name).padEnd(20)} ${role}`);
+  const name = currentAgentName(dir);
+  const label = name === id ? name : `${name} (id: ${id})`;
+  console.log(`  ${(prefix + label).padEnd(20)} ${role}`);
 }
 
 // The watermark is read before the roster, and that order is the contract. Read
@@ -104,20 +107,26 @@ export function agentRecord(
 ) {
   const yaml = readAgentYaml(dir);
   const record = {
-    name,
+    name: yaml.name || name,
     dir: resolve(dir),
     displayName: yaml.displayName || yaml.display_name || yaml.name || name,
     runtimeProvider: strictRuntime ? readRuntimeProvider(dir) : runtimeProviderOrNull(dir),
+    kind: strictRuntime ? kindOf(dir) : rosterKind(yaml),
   };
   if (yaml.role) record.role = yaml.role;
   if (includeSurfaces) record.surfaces = surfacePresence(dir);
   return record;
 }
 
+// The roster degrades an unsupported kind to null the way it degrades the
+// runtime; a missing one is a Specialist, as `kindOf` reads it.
+function rosterKind(yaml) {
+  const kind = yaml.kind || 'specialist';
+  return Object.hasOwn(KIND_PROFILES, kind) ? kind : null;
+}
+
 function surfacePresence(dir) {
-  return Object.fromEntries(
-    SURFACES.map((surface) => [surface, existsSync(join(dir, `${surface}.md`))]),
-  );
+  return Object.fromEntries(surfacesFor(dir).map(({ name, path }) => [name, existsSync(path)]));
 }
 
 export function inspectAgent(name, json) {
@@ -145,12 +154,17 @@ export function inspectAgent(name, json) {
   if (record.role) console.log(`  role: ${record.role}`);
 }
 
+// Staged `## Proposed` lines reach the prompt but do not count toward the user cap.
+function withoutProposed({ name, content }) {
+  return name === 'user' ? content.split(/^## Proposed\s*$/m)[0] : content;
+}
+
 function roundPercent(part, total) {
   if (!total) return 0;
   return Math.round((part / total) * 1000) / 10;
 }
 
-function promptTokenReport(name) {
+function promptTokenReport(name, budgetOnly = false) {
   validateName(name);
   checkAgentsRoot();
   assertNotArchived(name);
@@ -158,7 +172,7 @@ function promptTokenReport(name) {
   if (!existsSync(dir)) return { missing: true, dir };
   assertContainedAgentDir(name, dir);
 
-  const built = buildAcademySystemPrompt(dir, name);
+  const built = buildAcademySystemPrompt(dir, currentAgentName(dir));
   const total = tokenRecord(built.prompt);
   const overheadText = [
     ...built.intro,
@@ -166,7 +180,7 @@ function promptTokenReport(name) {
   ].join('\n');
   const overhead = tokenRecord(overheadText);
   const surfaces = built.surfaces.map((surface) => {
-    const count = tokenRecord(surface.content);
+    const count = tokenRecord(budgetOnly ? withoutProposed(surface) : surface.content);
     return {
       name: surface.name,
       file: surface.file,
@@ -223,7 +237,7 @@ export function printPromptTokens(name, json) {
 }
 
 export function printSurfaceBudget(name, json) {
-  const tokenReport = promptTokenReport(name);
+  const tokenReport = promptTokenReport(name, true);
   if (tokenReport.missing) {
     const message = `Agent "${name}" not found at ${tokenReport.dir}`;
     if (json) exitJsonError('agent_not_found', message, { name });
@@ -231,8 +245,11 @@ export function printSurfaceBudget(name, json) {
     process.exit(1);
   }
 
+  // Both the token report and the limits come from surfacesFor, so a surface
+  // is joined by its name, never by its position in the list.
+  const limits = new Map(surfacesFor(tokenReport.dir).map((limit) => [limit.name, limit]));
   const surfaces = tokenReport.surfaces.map((surface) => {
-    const cap = SURFACE_CAPS[surface.name];
+    const { cap, enforced } = limits.get(surface.name);
     const overBy = Math.max(0, surface.estimatedTokens - cap);
     return {
       name: surface.name,
@@ -240,10 +257,11 @@ export function printSurfaceBudget(name, json) {
       cap,
       overBy,
       withinCap: overBy === 0,
-      enforced: ENFORCED_SURFACES.has(surface.name),
+      enforced,
     };
   });
   const totalEstimatedTokens = surfaces.reduce((sum, surface) => sum + surface.estimatedTokens, 0);
+  const totalCap = surfaces.reduce((sum, surface) => sum + surface.cap, 0);
   const violations = surfaces.filter((surface) => !surface.withinCap);
   const report = {
     agent: tokenReport.agent,
@@ -251,8 +269,8 @@ export function printSurfaceBudget(name, json) {
     withinBudget: !violations.some((surface) => surface.enforced),
     total: {
       estimatedTokens: totalEstimatedTokens,
-      cap: TOTAL_SURFACE_CAP,
-      overBy: Math.max(0, totalEstimatedTokens - TOTAL_SURFACE_CAP),
+      cap: totalCap,
+      overBy: Math.max(0, totalEstimatedTokens - totalCap),
     },
     surfaces,
     violations,

package/scripts/cli/lifecycle.mjs

@@ -1,9 +1,10 @@
 import { existsSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { readJsonFile } from './codex.mjs';
 import {
   AGENTS_ROOT,
+  CLI_NAME,
   agentDir,
   agentLifecycleLockPath,
   contractOk,
@@ -13,16 +14,18 @@ import {
   jsonMode,
   LockTimeoutError,
   RuntimeUnavailableError,
-  resolveExecutable,
   validateAgentsRoot,
   validateName,
   withFileLock,
 } from './core.mjs';
 import { assertNotArchived, holdingAreaOrNull } from './archived.mjs';
 import { LogCorruptError, appendLifecycleEvent } from './eventlog.mjs';
-import { AgentSpecError } from './yaml.mjs';
-import { MUST_EXIST, helmFailureReason } from './create.mjs';
+import { AgentSpecError, readAgentYaml } from './yaml.mjs';
+import { agentIdOf, currentAgentName } from './agent-id.mjs';
+import { helmFailureReason } from './schedule-errors.mjs';
+import { ownerJobIds, ownerSessionJobIds, principalJobIds } from './owner-jobs.mjs';
 import { TEMPLATES } from './templates.mjs';
+import { resolveTldrAgentsBinary, spawnTldrTasksArgs, tldrSpawnOptions } from './tldr.mjs';
 
 export function cleanAgent(name) {
   validateName(name);
@@ -31,19 +34,20 @@ export function cleanAgent(name) {
     console.error(`Agent "${name}" not found at ${dir}`);
     process.exit(1);
   }
-  // Reset notes.md and threads.md to scaffolded state. Other surfaces are
-  // load-bearing (identity/role/knowledge) or natural-decay (dailys/goals/priorities).
+  // Reset notes.md only. It is the one transient surface. work.md is durable:
+  // it holds the goals and Workstreams the nightly run keeps, so clean never
+  // resets it.
   const today = new Date().toISOString().slice(0, 10);
-  writeFileSync(join(dir, 'notes.md'), TEMPLATES['notes.md'](name, today));
-  writeFileSync(join(dir, 'threads.md'), TEMPLATES['threads.md'](name, today));
-  console.log(`Cleaned transient surfaces for "${name}" (notes.md, threads.md).`);
+  const current = currentAgentName(dir);
+  writeFileSync(join(dir, 'notes.md'), TEMPLATES['notes.md'](current, today));
+  console.log(`Cleaned transient surfaces for "${current}" (notes.md).`);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // `destroy` — nuke an agent (--force required)
 // ─────────────────────────────────────────────────────────────────────────────
 
-export function deleteJsonError(code, message, fields = {}, json = false) {
+function deleteJsonError(code, message, fields = {}, json = false) {
   if (json) exitJsonError(code, message, fields);
   console.error(message);
   process.exit(1);
@@ -57,17 +61,25 @@ export class DeleteAgentError extends Error {
   }
 }
 
+const MIGRATE_HINT = `Run \`${CLI_NAME} migrate\` to write it.`;
+
 // Ownership is one question, asked by every command that acts on an agent
 // directory and by `doctor` when it counts what `migrate` still has to fix.
 // It answers with the fault text, or null when the directory is owned.
+// A marker fault on a directory holding agent.yaml is exactly what `migrate`
+// repairs, so the text names it; with no agent.yaml there is no agent to
+// repair, and pointing at `migrate` would send the operator nowhere.
 export function ownershipFault(name, dir) {
-  const markerPath = join(dir, '.academy-agent.json');
-  if (!existsSync(markerPath) || !existsSync(join(dir, 'agent.yaml'))) {
+  if (!existsSync(join(dir, 'agent.yaml'))) {
     return `Agent "${name}" is missing Academy ownership metadata`;
   }
+  const markerPath = join(dir, '.academy-agent.json');
+  if (!existsSync(markerPath)) {
+    return `Agent "${name}" is missing Academy ownership metadata. ${MIGRATE_HINT}`;
+  }
   const marker = readJsonFile(markerPath, {});
   if (marker.capability !== 'academy-agent' || marker.name !== name) {
-    return `Agent "${name}" ownership metadata is invalid`;
+    return `Agent "${name}" ownership metadata is invalid. ${MIGRATE_HINT}`;
   }
   return null;
 }
@@ -144,7 +156,8 @@ function ownedAgentFault(name, dir, slot) {
 // landed, because a read that follows one out of the root publishes content
 // from outside it under a `dir` field claiming to be inside.
 export function assertContainedAgentDir(name, dir, json = jsonMode()) {
-  const fault = containmentFault(name, dir, SLOT.canonical);
+  // The slot is the id folder `dir` names, whichever name addressed it.
+  const fault = containmentFault(basename(resolve(dir)), dir, SLOT.canonical);
   if (fault.code) deleteJsonError(fault.code, fault.message, { name }, json);
 }
 
@@ -157,11 +170,14 @@ export function validateOwnedAgentDir(name, dir, json = false, slot = SLOT.canon
 // The shared preflight for `delete`, `rename` and `archive`. `unarchive` is the
 // one lifecycle command that may address an archived agent, so it preflights
 // against the holding area instead of coming through here.
+// Every check after the name resolves asks about the fixed id: the folder,
+// its slot and its marker are all keyed by it, never by the current name.
 export function preflightOwnedAgent(name, json = false) {
   validateName(name);
   validateAgentsRoot();
-  assertNotArchived(name, json);
-  return validateOwnedAgentDir(name, agentDir(name), json);
+  const id = agentIdOf(name);
+  assertNotArchived(id, json);
+  return { ...validateOwnedAgentDir(id, agentDir(id), json), id };
 }
 
 export function assertOwnedAgentForDelete(name, dir, slot = SLOT.canonical) {
@@ -170,30 +186,61 @@ export function assertOwnedAgentForDelete(name, dir, slot = SLOT.canonical) {
   return outcome;
 }
 
-export function deleteNightlyConsolidation(name, dir) {
-  const id = `${name}-nightly-consolidation`;
+// Every Academy job the agent's kind registers, nightly first. Read before the
+// directory moves, and read leniently: an unreadable kind must not exit inside
+// the lifecycle lock, and only an Owner has jobs beyond the nightly.
+export function academyJobIds(name, dir) {
+  const ids = kindJobIds(name, dir);
+  return readAgentYaml(dir).kind === 'owner' ? [...ids, ...ownerSessionJobIds(name)] : ids;
+}
+
+// The jobs Academy itself registers for the agent's kind, nightly first; the
+// Owner's self-scheduled sessions are not among them.
+export function kindJobIds(name, dir) {
+  const nightly = `${name}-nightly-consolidation`;
+  const { kind } = readAgentYaml(dir);
+  if (kind === 'owner') return [nightly, ...ownerJobIds(name)];
+  return kind === 'principal' ? [nightly, ...principalJobIds(name)] : [nightly];
+}
+
+// Each id is deleted by its exact (cwd, id) pair, so no other agent's job can
+// match. Stops at the first failure and names it; `id` on success is the
+// nightly, the published `unscheduledJobId`.
+export function deleteAcademyJobs(dir, ids) {
   // Resolved inside the lock, so exiting here would strand the lock directory
   // and make every later delete of this agent unanswerable.
-  let helmTasksBin;
+  let tldrAgentsBin;
   try {
-    helmTasksBin = resolveExecutable('ACADEMY_HELM_TASKS_BIN', 'helm-tasks', MUST_EXIST);
+    tldrAgentsBin = resolveTldrAgentsBinary();
   } catch (error) {
     if (!(error instanceof RuntimeUnavailableError)) throw error;
-    return { ok: false, id, code: error.code, reason: error.message };
+    return { ok: false, id: ids[0], code: error.code, reason: error.message };
   }
-  const result = spawnSync(helmTasksBin, ['delete', '--cwd', dir, '--id', id], {
-    cwd: dirname(dir),
-    encoding: 'utf8',
-    env: process.env,
-  });
-  if (result.error) return { ok: false, id, reason: result.error.message };
-  if (result.status !== 0)
-    return {
-      ok: false,
-      id,
-      reason: helmFailureReason(result.stderr || result.stdout, result.status),
-    };
-  return { ok: true, id };
+  for (const id of ids) {
+    const failure = deleteJob(tldrAgentsBin, dir, id);
+    if (failure) return { ok: false, id, reason: failure };
+  }
+  return { ok: true, id: ids[0], ids };
+}
+
+function deleteJob(tldrAgentsBin, dir, id) {
+  const result = spawnSync(
+    tldrAgentsBin,
+    spawnTldrTasksArgs(['delete', '--cwd', dir, '--id', id]),
+    tldrSpawnOptions(dirname(dir)),
+  );
+  if (result.error || result.status !== 0) return helmFailureReason(result);
+  return null;
+}
+
+// The refusal `delete` and `archive` raise when a job of the set
+// would not go.
+export function unscheduleError(verb, name, unscheduled) {
+  return new DeleteAgentError(
+    unscheduled.code ?? 'unschedule_failed',
+    `Refusing to ${verb} "${name}" because unscheduling "${unscheduled.id}" failed: ${unscheduled.reason}`,
+    { name },
+  );
 }
 
 // The one failure path `delete`, `rename` and `archive` share. Each stated the
@@ -219,40 +266,38 @@ export function reportLifecycleFailure(error, verb, name, json) {
 }
 
 export function deleteAgent(name, json) {
-  preflightOwnedAgent(name, json);
-  const lockDir = agentLifecycleLockPath(agentDir(name));
+  const { id } = preflightOwnedAgent(name, json);
+  const lockDir = agentLifecycleLockPath(agentDir(id));
   try {
-    withFileLock(lockDir, () => deleteAgentLocked(name, json));
+    withFileLock(lockDir, () => deleteAgentLocked(id, json));
   } catch (error) {
-    reportLifecycleFailure(error, 'delete', name, json);
+    reportLifecycleFailure(error, 'delete', id, json);
   }
 }
 
-function deleteAgentLocked(name, _json) {
-  const { dir, dirReal } = assertOwnedAgentForDelete(name, agentDir(name));
+function deleteAgentLocked(id, _json) {
+  const { dir, dirReal } = assertOwnedAgentForDelete(id, agentDir(id));
+  const name = currentAgentName(dirReal);
+  const jobIds = academyJobIds(id, dirReal);
   const quarantine = join(
     resolve(AGENTS_ROOT),
-    `.${name}.delete-quarantine.${process.pid}.${Date.now()}`,
+    `.${id}.delete-quarantine.${process.pid}.${Date.now()}`,
   );
   renameSync(dir, quarantine);
-  assertOwnedAgentForDelete(name, quarantine, SLOT.contained);
+  assertOwnedAgentForDelete(id, quarantine, SLOT.contained);
 
-  const unscheduled = deleteNightlyConsolidation(name, dirReal);
+  const unscheduled = deleteAcademyJobs(dirReal, jobIds);
   if (!unscheduled.ok) {
     if (!existsSync(dir)) {
       renameSync(quarantine, dir);
     } else {
       throw new DeleteAgentError(
         'unschedule_failed_restore_blocked',
-        `Refusing to delete "${name}" because nightly unschedule failed and ${dir} is occupied: ${unscheduled.reason}`,
+        `Refusing to delete "${name}" because unscheduling "${unscheduled.id}" failed and ${dir} is occupied: ${unscheduled.reason}`,
         { name, quarantine },
       );
     }
-    throw new DeleteAgentError(
-      unscheduled.code ?? 'unschedule_failed',
-      `Refusing to delete "${name}" because nightly unschedule failed: ${unscheduled.reason}`,
-      { name },
-    );
+    throw unscheduleError('delete', name, unscheduled);
   }
   rmSync(quarantine, { recursive: true, force: false });
   appendLifecycleEvent('agent_deleted', name, dir);
@@ -264,6 +309,7 @@ function deleteAgentLocked(name, _json) {
       name,
       dir: resolve(dir),
       unscheduledJobId: unscheduled.id,
+      unscheduledJobIds: unscheduled.ids,
     });
     return;
   }

package/scripts/cli/main.mjs

@@ -1,8 +1,10 @@
 import { resolve } from 'node:path';
+import { isatty } from 'node:tty';
 import { parseArgs, printUsage } from './args.mjs';
 import {
   ACADEMY_ROOT,
   AGENTS_ROOT,
+  CLI_NAME,
   CONTRACT_VERSION,
   contractOk,
   exitJsonError,
@@ -28,6 +30,8 @@ import { notesAdd, notesList } from './notes.mjs';
 import { renameAgent } from './rename.mjs';
 import { runAgent, runNightly } from './run.mjs';
 import { readSessions } from './sessions.mjs';
+import { checkSkills } from './skills-check.mjs';
+import { startAgent, stopAgent } from './start.mjs';
 
 const COMMAND_HANDLERS = {
   ...Object.fromEntries(UNIMPLEMENTED_COMMANDS.map((command) => [command, unimplementedCommand])),
@@ -36,7 +40,7 @@ const COMMAND_HANDLERS = {
     printUsage();
     process.exit(parsed.exitCode ?? 0);
   },
-  create: (parsed) => createAgent(parsed.name, parsed.json),
+  create: createCommand,
   // `--spec` is the only thing that selects the headless form; without it the
   // interactive launch runs exactly as it always has.
   hire: (parsed) =>
@@ -45,6 +49,8 @@ const COMMAND_HANDLERS = {
   nightly: (parsed) => runNightly(parsed.name),
   events: (parsed) => readEvents(parsed),
   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),
   archive: (parsed) => archiveAgent(parsed.name, parsed.json),
   unarchive: (parsed) => unarchiveAgent(parsed.name, parsed.json),
@@ -53,6 +59,7 @@ const COMMAND_HANDLERS = {
   inspect: (parsed) => inspectAgent(parsed.name, parsed.json),
   tokens: (parsed) => printPromptTokens(parsed.name, parsed.json),
   budget: (parsed) => printSurfaceBudget(parsed.name, parsed.json),
+  skills: (parsed) => checkSkills(parsed),
   clean: (parsed) => cleanAgent(parsed.name),
   delete: (parsed) => deleteAgent(parsed.name, parsed.json),
   destroy: (parsed) => destroyAgent(parsed.name, parsed.force),
@@ -62,11 +69,34 @@ const COMMAND_HANDLERS = {
     else console.log(ACADEMY_ROOT);
   },
   notes: (parsed) => {
-    if (parsed.action === 'add') notesAdd(parsed.name, parsed.text);
+    if (parsed.action === 'add') notesAdd(parsed.name, parsed.text, { user: parsed.user });
     else notesList(parsed.name, parsed.last);
   },
 };
 
+const PRINCIPAL_PITCH = [
+  'New Principal',
+  'Your main agent. You direct the work; it does the work with you.',
+  'It keeps its job, its memory, and your work between sessions.',
+];
+
+// Only a person at a terminal has a session opened for them. Every other
+// create (--json, a pipe, a script, another kind) is the plain create. No
+// create asks a question: a missing name is the first free default name.
+function createCommand(parsed) {
+  const atTerminal = isatty(0) && isatty(1);
+  const guided = parsed.kind === 'principal' && !parsed.json && !parsed.invalidOption && atTerminal;
+  if (!guided) return createAgent(parsed.name, parsed.json, parsed);
+  if (parsed.name === undefined) console.log(`${PRINCIPAL_PITCH.join('\n')}\n`);
+  const name = createAgent(parsed.name, false, {
+    ...parsed,
+    guided: parsed.noStart ? 'later' : 'opening',
+  });
+  if (parsed.name === undefined)
+    console.log(`Rename it any time: ${CLI_NAME} rename ${name} <new-name>`);
+  if (!parsed.noStart) runAgent(name, null, []);
+}
+
 // `doctor` advertises the whole contract_version 1 command set, including the
 // commands later phases build. Answering those in the envelope is what keeps
 // the capability list honest: a client that calls what doctor named gets a

package/scripts/cli/memory-env.mjs

@@ -0,0 +1,124 @@
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  bridgeClaudeSettingsArgs,
+  bridgeEnvPresent,
+  bridgeHooksInUserSettings,
+  bridgeLaunch,
+  bridgeLauncher,
+} from '../../hooks/memory_bridge.mjs';
+import { ACADEMY_CLI_PATH, isInside } from './core.mjs';
+import { childExitCode } from './exit-code.mjs';
+import { readAgentYaml } from './yaml.mjs';
+
+// Set on the relaunched run so it launches its provider directly instead of
+// wrapping itself again. Cleared before the provider starts.
+export const MEMORY_RELAUNCH_FLAG = 'ACADEMY_MEMORY_RELAUNCH';
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// The agent home is not a memory workspace, so a run started there falls
+// through to the workspace the agent declares, if any.
+function memoryWorkspace(dir, cwd, env) {
+  const declared = readAgentYaml(dir).memory_workspace;
+  const candidates = [
+    env.ACADEMY_PROJECT_DIR,
+    isInside(cwd, dir) ? null : cwd,
+    declared ? resolve(dir, declared) : null,
+  ];
+  const found = candidates.find((path) => path && isDirectory(path));
+  return found ? resolve(found) : null;
+}
+
+/** Whether a run of the agent in `dir` from `cwd` launches with a memory workspace. */
+export function resolveMemoryEnv(dir, { cwd, env }) {
+  if (bridgeEnvPresent(env)) return { status: 'on', reason: 'inherited', workspace: null };
+  const launcher = bridgeLauncher(env);
+  if (!launcher) return { status: 'off', reason: 'wrapper_missing', workspace: null };
+  const workspace = memoryWorkspace(dir, cwd, env);
+  if (!workspace) return { status: 'off', reason: 'no_memory_workspace', workspace: null };
+  return { status: 'on', reason: null, workspace, launcher };
+}
+
+/** The receipt form of a decision: no launcher internals. */
+export function memoryEnvRecord({ status, reason, workspace }) {
+  return { status, reason, workspace };
+}
+
+function logMemoryEnv(name, decision) {
+  const event = decision.status === 'on' ? 'memory.env_on' : 'memory.env_off';
+  const params =
+    decision.status === 'on'
+      ? {
+          agent: name,
+          workspace: decision.workspace,
+          source: decision.reason ?? 'resolved',
+        }
+      : { agent: name, reason: decision.reason };
+  console.error(JSON.stringify({ event, params }));
+}
+
+// The client's settings load only when the user's own Claude settings do not
+// already run its hooks: both sets would fire on every turn otherwise.
+function claudeSettingsArgs({ name, runtime, passthrough, launcher }) {
+  if (runtime === 'codex' || passthrough.includes('--settings')) return [];
+  const source = bridgeHooksInUserSettings(process.env) ? 'global' : 'injected';
+  console.error(JSON.stringify({ event: 'memory.settings', params: { agent: name, source } }));
+  return source === 'global' ? [] : bridgeClaudeSettingsArgs(launcher);
+}
+
+function relaunchArgs({ name, requestedRuntime, runtime, passthrough, launcher }) {
+  const providerArgs = [
+    ...claudeSettingsArgs({ name, runtime, passthrough, launcher }),
+    ...passthrough,
+  ];
+  return [
+    ACADEMY_CLI_PATH,
+    'run',
+    name,
+    ...(requestedRuntime ? ['--agent', requestedRuntime] : []),
+    ...(providerArgs.length > 0 ? ['--', ...providerArgs] : []),
+  ];
+}
+
+// Re-runs this same `academy run` under the memory wrapper, so the provider,
+// its hooks, and any runtime context all see the resolved memory env. Returns
+// only when the run should launch directly: memory resolved nothing, the env
+// was inherited, or the wrapper could not start. A user's run always launches.
+export function relaunchWithMemoryEnv(run) {
+  if (process.env[MEMORY_RELAUNCH_FLAG] === '1') return;
+  const decision = resolveMemoryEnv(run.dir, {
+    cwd: process.cwd(),
+    env: process.env,
+  });
+  if (!decision.launcher) {
+    logMemoryEnv(run.name, decision);
+    return;
+  }
+  const launch = bridgeLaunch(decision.launcher, {
+    command: process.execPath,
+    args: relaunchArgs({ ...run, launcher: decision.launcher }),
+    env: { ...process.env, [MEMORY_RELAUNCH_FLAG]: '1' },
+    workspaceCwd: decision.workspace,
+  });
+  logMemoryEnv(run.name, decision);
+  const result = spawnSync(launch.command, launch.args, {
+    stdio: 'inherit',
+    env: launch.env,
+  });
+  if (result.error) {
+    logMemoryEnv(run.name, {
+      status: 'off',
+      reason: `wrapper_failed: ${result.error.code}`,
+    });
+    return;
+  }
+  process.exit(childExitCode(result));
+}

package/scripts/cli/migrate.mjs

@@ -59,27 +59,33 @@ function markerFault(dirReal) {
   return null;
 }
 
+function refusal(name, dir, reason) {
+  return { refused: { name, dir, reason } };
+}
+
+function holdsAgent(dirReal) {
+  return statSync(dirReal).isDirectory() && existsSync(join(dirReal, 'agent.yaml'));
+}
+
 function classify(root, rootReal, name) {
   const dir = join(root, name);
   let dirReal;
   try {
     dirReal = realpathSync(dir);
   } catch (error) {
-    return { refused: { name, dir, reason: `cannot be resolved: ${error.message}` } };
+    return refusal(name, dir, `cannot be resolved: ${error.message}`);
   }
   const fault = slotFault(dirReal, rootReal, name);
-  if (fault) return { refused: { name, dir, reason: fault } };
+  if (fault) return refusal(name, dir, fault);
   // Not an agent directory, so not a repair. Marking a directory holding no
   // agent.yaml would create an agent, which the backfill must never do.
-  if (!statSync(dirReal).isDirectory()) return {};
-  if (!existsSync(join(dirReal, 'agent.yaml'))) return {};
+  if (!holdsAgent(dirReal)) return {};
   const marker = markerFault(dirReal);
-  if (marker) return { refused: { name, dir, reason: marker } };
-  if (ownershipFault(name, dirReal) === null) return {};
+  if (marker) return refusal(name, dir, marker);
   // dirReal is carried, not recomputed at the write: joining the unvalidated
   // path again would traverse the same symlink chain a second time and land
   // somewhere the classification never proved.
-  return { repair: { name, dir, dirReal } };
+  return ownershipFault(name, dirReal) === null ? {} : { repair: { name, dir, dirReal } };
 }
 
 // The one enumeration. `migrate` repairs exactly this set and `doctor` counts

package/scripts/cli/next-steps.mjs

@@ -0,0 +1,13 @@
+import { CLI_NAME } from './core.mjs';
+
+// What `create` prints under "Next:". A new Owner is a draft: it starts once its mandate is signed.
+export function nextSteps(name, kind) {
+  const hire = `  ${CLI_NAME} hire           # interactive hire flow to populate the boot surfaces`;
+  if (kind !== 'owner') {
+    return [hire, `  ${CLI_NAME} run ${name}    # launch Claude Code in the agent's home`];
+  }
+  return [
+    `  ${CLI_NAME} start ${name} --mandate <file>  # sign the mandate and start the draft`,
+    `  ${CLI_NAME} hire           # drafts the mandate with you`,
+  ];
+}