@awebai/oats 0.67.1 → 0.68.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
package/bin/oats.mjs CHANGED
@@ -26,13 +26,14 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
28
  import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
29
+ import { assertNoPartialUpgrade } from "../lib/upgrade-state.mjs";
29
30
  import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
30
31
  import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
31
32
  import {
32
33
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
33
34
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
34
35
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
35
- findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
36
+ findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
36
37
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
37
38
  } from "../lib/core.mjs";
38
39
  import {
@@ -107,7 +108,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
107
108
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
108
109
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
109
110
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
110
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name"];
111
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "instance-suggest-name", "spawn-apply-suggest-name"];
111
112
  /** Commands `--server <id>` runs on a registered server. */
112
113
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
113
114
  const flag = (name) => {
@@ -1318,10 +1319,68 @@ function retiredInstanceAddresses(root, name, home) {
1318
1319
  * instance's work tree. The instance is addressed qualified: an explicit
1319
1320
  * --home, or a name under the --dir scope (team roots included) that resolves
1320
1321
  * to exactly one home; several homes refuse with every candidate named. */
1321
- function instanceCmd() {
1322
+ async function instanceUpgradeCmd(name, bail) {
1323
+ const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
1324
+ if (!name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1325
+ if (serverFlagOf(args)) return bail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
1326
+ const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
1327
+ if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1328
+ const planOnly = args.includes("--plan"), undo = args.includes("--undo");
1329
+ if (revision === true || key === true || (planOnly && (revision !== undefined || key !== undefined))) return bail("E_BAD_ARGS", usage);
1330
+ dropAmbientRoot();
1331
+ try {
1332
+ const root = ensureRoot(dirFlag());
1333
+ const { planUpgrade, applyUpgrade } = await import("../lib/instance-upgrade.mjs");
1334
+ const result = planOnly ? await planUpgrade(dirFlag(), root, name, { home, undo })
1335
+ : await applyUpgrade(dirFlag(), root, name, { home, undo, planRevision: revision, idempotencyKey: key });
1336
+ if (JSON_MODE) { jsonOk(result); return; }
1337
+ console.log(`${undo ? "undo package upgrade" : "package upgrade"} ${name}: ${planOnly ? `plan ${result.planRevision}` : result.status}${result.replayed ? " (replayed receipt)" : ""}`);
1338
+ for (const row of result.modules) console.log(` ${row.capability}: ${row.from.version} @ ${row.from.commit.slice(0,12)} → ${row.to.version} @ ${row.to.commit.slice(0,12)}${row.provider?.decision === "refuse" ? `; refused: ${row.provider.reason}` : ""}`);
1339
+ for (const row of result.kept || []) console.log(` ${row.capability}: kept (${row.reason})`);
1340
+ for (const row of result.memberDrift || []) console.log(` ${row.module}: member drift (${row.reason || row.status}); respawn to move it`);
1341
+ if (planOnly) console.log(` home changed since spawn: ${result.homeChangedSinceSpawn ? "yes (retire preserves a recovery copy)" : "no"}`);
1342
+ if (planOnly) console.log(`apply with: oats instance upgrade ${name}${undo ? " --undo" : ""} --plan-revision ${result.planRevision} --idempotency-key <key>`);
1343
+ } catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
1344
+ }
1345
+
1346
+ /** The flags `oats instance suggest-name` reads, each taking a value (`--json` aside). */
1347
+ const SUGGEST_NAME_FLAGS = new Set(["soul", "task", "task-file", "harness", "model", "launch-config", "dir"]);
1348
+ /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
1349
+ * of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
1350
+ * (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
1351
+ async function instanceSuggestNameCmd(bail) {
1352
+ const usage = "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
1353
+ // A flag's value as given, the empty text included (`--task ""` is an empty task, not a missing one).
1354
+ const value = (name) => {
1355
+ const i = args.indexOf(`--${name}`);
1356
+ if (i < 0) return undefined;
1357
+ const v = inlineValues.has(name) ? inlineValues.get(name) : args[i + 1];
1358
+ if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
1359
+ return v;
1360
+ };
1361
+ for (let i = 2; i < args.length; i++) {
1362
+ const a = args[i];
1363
+ if (a === "--json") continue;
1364
+ if (!a.startsWith("--") || !SUGGEST_NAME_FLAGS.has(a.slice(2))) return bail("E_BAD_ARGS", `oats instance suggest-name: unexpected ${a.startsWith("--") ? "flag" : "argument"} ${JSON.stringify(a)}; ${usage}`);
1365
+ if (!inlineValues.has(a.slice(2))) i++;
1366
+ }
1367
+ const soul = value("soul"), task = value("task"), taskFile = value("task-file");
1368
+ if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
1369
+ if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
1370
+ let text = task;
1371
+ if (taskFile !== undefined) { try { text = readFileSync(taskFile, "utf8"); } catch (e) { return bail("E_BAD_ARGS", `--task-file ${taskFile} cannot be read (${e.code || "error"})`); } }
1372
+ let r;
1373
+ try { r = await suggestSpawnName({ dir: dirFlag(), soul, task: text, harness: value("harness"), model: value("model"), launchConfig: value("launch-config") }); }
1374
+ catch (e) { return bail(e.code || "E_BAD_ARGS", e.message, e.details); }
1375
+ if (JSON_MODE) { jsonOk(r); return; }
1376
+ console.log(r.name ?? namingLine(r.naming));
1377
+ }
1378
+ async function instanceCmd() {
1322
1379
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
1323
1380
  const sub = args[1], name = args[2];
1381
+ if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1324
1382
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1383
+ if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
1325
1384
  const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message <text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
1326
1385
  if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1327
1386
  dropAmbientRoot();
@@ -2733,12 +2792,14 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
2733
2792
  * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2734
2793
  const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
2735
2794
  const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "suggest-name", "yolo"]);
2736
- /** `--suggest-name` (feature spawn-suggest-name): a preview's, with no --name or --purpose. The kernel
2737
- * refuses the same (core.mjs spawnBody); the CLI says it before anything is read or sent. */
2795
+ /** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
2796
+ * with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
2797
+ * CLI says it before anything is read or sent. */
2738
2798
  function suggestNameProblem(argv) {
2739
2799
  if (!argv.includes("--suggest-name")) return undefined;
2740
- if (!argv.includes("--preview")) return "--suggest-name is a preview's: it chooses the name a spawn would get; pass --preview";
2741
- if (argv.some((a) => ["--name", "--purpose"].includes(a.split("=")[0]))) return "--suggest-name chooses the name: it takes no --name or --purpose";
2800
+ const given = (flag) => argv.some((a) => a.split("=")[0] === flag);
2801
+ if (given("--expect-decision")) return "--suggest-name chooses the name, and --expect-decision's decision already binds one: apply the previewed name with --name <instance> --expect-decision <revision>";
2802
+ if (given("--name") || given("--purpose")) return "--suggest-name chooses the name: it takes no --name or --purpose";
2742
2803
  return undefined;
2743
2804
  }
2744
2805
  /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
@@ -2767,6 +2828,13 @@ function herdrSpawnFlag() {
2767
2828
  if (flag("herdr-socket") !== undefined) return "--herdr-socket";
2768
2829
  return undefined;
2769
2830
  }
2831
+ /** How a name was chosen (`naming`: features spawn-suggest-name, spawn-apply-suggest-name,
2832
+ * instance-suggest-name), for a text line; null without one. */
2833
+ function namingLine(naming) {
2834
+ if (naming?.source === "suggested") return `suggested by ${terminalText(naming.harness)}${naming.model ? ` (${terminalText(naming.model)})` : ""} in ${naming.ms} ms`;
2835
+ if (naming?.source === "numbered") return `numbered (${terminalText(naming.reason)}: ${terminalText(naming.message)})`;
2836
+ return null;
2837
+ }
2770
2838
  /** A spawn preview's text: the local one, or a host's answer to a routed
2771
2839
  * preview (`server`, its id), which this side printed the same way (#610). */
2772
2840
  function printSpawnPreview(r, { server, soulFetched = false } = {}) {
@@ -2774,8 +2842,7 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2774
2842
  const harness = r.harness ?? r.runtime;
2775
2843
  console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2776
2844
  // Feature spawn-suggest-name: how the name was chosen.
2777
- if (r.naming?.source === "suggested") console.log(`name: suggested by ${terminalText(r.naming.harness)}${r.naming.model ? ` (${terminalText(r.naming.model)})` : ""} in ${r.naming.ms} ms`);
2778
- else if (r.naming?.source === "numbered") console.log(`name: numbered (${terminalText(r.naming.reason)}: ${terminalText(r.naming.message)})`);
2845
+ { const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
2779
2846
  if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
2780
2847
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2781
2848
  }
@@ -2794,7 +2861,7 @@ async function spawnCmd() {
2794
2861
  };
2795
2862
  checkDirectoryOptions(requestedWork); // before anything is resolved or written
2796
2863
  const name = args[1];
2797
- if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>] [--preview [--suggest-name]] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--no-launch] [--json]");
2864
+ if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--no-launch] [--json]");
2798
2865
  // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
2799
2866
  // ANY side effect, including root discovery.
2800
2867
  // Local souls (local-agents/) are gone with the workspace model: a soul is a member
@@ -3056,11 +3123,14 @@ async function spawnCmd() {
3056
3123
  launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
3057
3124
  // #796: the worktree hooks this spawn ran, with their logs; only when it ran any.
3058
3125
  ...(r.worktreeHooks ? { worktreeHooks: r.worktreeHooks } : {}),
3126
+ // Feature spawn-apply-suggest-name: how the name was chosen; only with --suggest-name.
3127
+ ...(r.naming ? { naming: r.naming } : {}),
3059
3128
  });
3060
3129
  return;
3061
3130
  }
3062
3131
  console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
3063
3132
  console.log(` home: ${shortPath(r.home)}`);
3133
+ { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
3064
3134
  if (r.base) console.log(` base: ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
3065
3135
  for (const h of r.worktreeHooks || []) console.log(` setup: ${h.capability} worktree hook ${h.ok ? "ok" : "FAILED"} (log: ${shortPath(h.log)})`);
3066
3136
  if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
@@ -3533,6 +3603,8 @@ async function sessionCmd() {
3533
3603
  // recorded launch stays frozen (a changed preference never reaches an existing home on its own).
3534
3604
  const reselectLaunch = args.includes("--reselect-launch");
3535
3605
  if (reselectLaunch && launchConfig !== undefined) bad("--reselect-launch applies the launch preferences; --launch-config names one explicitly — choose one");
3606
+ // Refuse before launch selection or live-team discovery can prepare this home.
3607
+ assertNoPartialUpgrade(home);
3536
3608
  const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), env: process.env, ...(await homeLiveTeams(home)) };
3537
3609
  if (args[1] === "restart") {
3538
3610
  const grace = flag("stop-grace");
@@ -3562,6 +3634,11 @@ async function sessionCmd() {
3562
3634
  console.log(JSON.stringify(result, null, 2));
3563
3635
  // A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
3564
3636
  for (const w of result?.warnings || []) console.error(` WARNING: ${terminalText(w)}`);
3637
+ if (result?.drift?.length) {
3638
+ const version = (v) => `${v.version ?? "?"} @ ${String(v.commit ?? "?").slice(0, 7)}`;
3639
+ const modules = result.drift.map((d) => `${d.capability} ${version(d.recorded)} → ${version(d.locked)}`).join(", ");
3640
+ console.error(terminalText(`${result.drift.length} package module(s) behind the lock (${modules}); to move them: oats instance stop ${shellQuote(result.instance)}; oats instance upgrade ${shellQuote(result.instance)} --plan`));
3641
+ }
3565
3642
  }
3566
3643
  } catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
3567
3644
  }
@@ -4640,6 +4717,7 @@ async function serverRouteCmd() {
4640
4717
  else if (cmd === "spawn") {
4641
4718
  console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
4642
4719
  console.log(` remote home: ${r.home}`);
4720
+ { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
4643
4721
  console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
4644
4722
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
4645
4723
  console.log(` attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
@@ -4734,7 +4812,8 @@ try {
4734
4812
  // listResolved): a listed deployment costs one bounded read of the list. Never on --server (the remote's path is not this computer's), never for
4735
4813
  // help, and silent: no output, no change to the command's answer or exit status.
4736
4814
  const LISTS_ITS_DEPLOYMENT = new Set(["automations", "capabilities", "doctor", "harness", "inspect", "instance", "launch-config", "operation", "package", "pane", "readiness", "retire", "schedule", "session", "soul", "souls", "spawn", "status", "sync", "teams", "trigger", "update", "workspace", "worktree"]);
4737
- if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
4815
+ // `instance suggest-name` records nothing (#1490 §2): the oats-local.yaml it reads is not listed.
4816
+ if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !(cmd === "instance" && args[1] === "suggest-name") && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
4738
4817
  if (cmd === "onboard") {
4739
4818
  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
4740
4819
  await onboardCmd();
@@ -4746,6 +4825,9 @@ else {
4746
4825
  // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
4747
4826
  const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
4748
4827
  if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
4828
+ if (cmd === "instance" && args[1] === "upgrade" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
4829
+ // #1490 §2: the name is decided on the machine that asks, for a spawn that lands elsewhere.
4830
+ if (cmd === "instance" && args[1] === "suggest-name" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)");
4749
4831
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4750
4832
  else if (cmd === "server") await serverCmd();
4751
4833
  else if (cmd === "deployments") deploymentsCmd();
@@ -4765,7 +4847,7 @@ else if (cmd === "update") {
4765
4847
  }
4766
4848
  else if (cmd === "harness") harnessTrustCmd();
4767
4849
  else if (cmd === "readiness") await readinessCmd();
4768
- else if (cmd === "instance") instanceCmd();
4850
+ else if (cmd === "instance") await instanceCmd();
4769
4851
  else if (cmd === "worktree") await worktreeCmd();
4770
4852
  else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
4771
4853
  else if (cmd === "sync") await syncCmd();
@@ -5005,10 +5087,12 @@ Usage:
5005
5087
  instance.json providers.<capability>)
5006
5088
  [--preview] decide everything, create no instance; --json
5007
5089
  includes the decision revision for confirmation
5008
- [--suggest-name] with --preview, no --name or --purpose: the soul's
5009
- harness names the instance for its task
5010
- (<descriptive>-<role>); else it is numbered, and
5011
- naming.reason says why (claude and pi)
5090
+ [--suggest-name] no --name, --purpose or --expect-decision: the
5091
+ soul's harness, on the machine that spawns, names
5092
+ the instance for its task (<descriptive>-<role>,
5093
+ made unique); else it is numbered, and
5094
+ naming.reason says why (claude and pi); on a
5095
+ preview or an apply
5012
5096
  [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
5013
5097
  [--idempotency-key <key>] with --expect-decision, replay the completed receipt
5014
5098
  for the same key and confirmed decision; a different
@@ -5146,6 +5230,10 @@ Usage:
5146
5230
  oats instance attention [--message <text>] [--clear] [--json]
5147
5231
  run by the agent from its home: "I need a human's
5148
5232
  answer" (waiting --producer agent --reason attention)
5233
+ oats instance upgrade <instance> --plan [--undo] [--json]
5234
+ Preview package module moves and provider adoption; session must be stopped.
5235
+ oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--undo] [--json]
5236
+ Move whole package modules to the verified lock; --undo uses the latest previous copies.
5149
5237
  oats instance stop <instance> --plan [--no-recursive] [--json]
5150
5238
  what Stop would touch: session state, recorded
5151
5239
  children, dirty work; a planRevision to apply
@@ -5155,6 +5243,14 @@ Usage:
5155
5243
  oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
5156
5244
  the instance's colour, presentation only: sand,
5157
5245
  sage, slate, mauve, clay or olive; --clear removes it
5246
+ oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
5247
+ [--model <m>] [--launch-config <n>] [--dir <d>] [--json]
5248
+ a name for a spawn of <soul> (only a name: it gives
5249
+ the role) by this machine's harness, as a preview's
5250
+ --suggest-name chooses it, not made unique (where it
5251
+ lands decides that); else numbered, and naming.reason
5252
+ says why. Reads only this machine's launch
5253
+ configurations; writes and reserves nothing; no --server
5158
5254
  oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
5159
5255
  [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
5160
5256
  [--preview] [--json] <base> (the clone's refs are not moved), then run the
@@ -94,17 +94,19 @@ A self-contained package has an `oats.json`:
94
94
  slot.
95
95
  - `skills` entries can be skill directories or roots containing skills.
96
96
  - `inject` is optional instance instruction Markdown.
97
- - The hooks are `spawn`, `launch`, `retire` and `worktree`
98
- ([The worktree event](#the-worktree-event)). A hook is a
97
+ - The hooks are `spawn`, `launch`, `retire`, `worktree` and `upgrade`
98
+ ([The worktree event](#the-worktree-event),
99
+ [The upgrade event](#the-upgrade-event)). A hook is a
99
100
  command string, or `{ command, required }`. `required: true` is valid **only
100
101
  on `spawn` and `worktree`**: a required spawn hook's failure fails the spawn
101
102
  and rolls it back,
102
103
  instead of producing an instance whose capability never configured itself —
103
104
  an aweb identity that could not be minted leaves an agent believing it can be
104
105
  woken by mail. A required `worktree` hook's failure fails the spawn the same
105
- way, or removes the tree `oats worktree add` made. Every other hook stays
106
- best-effort and only warns, so advisory
107
- work never becomes a spawn blocker. `launch` and `retire` cannot be
106
+ way, or removes the tree `oats worktree add` made. `launch` and `retire` stay
107
+ best-effort and only warn, so advisory work never becomes a spawn blocker.
108
+ `upgrade` has its own adoption and failure protocol and cannot be required.
109
+ `launch` and `retire` cannot be
108
110
  required: they run outside a spawn transaction, so there is no moment to
109
111
  enforce them. A `soul-scaffold` hook is tolerated and ignored.
110
112
  - An **event this kernel does not run** (a newer kernel's) is accepted from
@@ -845,6 +847,53 @@ turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
845
847
  into the capture hooks and the capture service's unit. In the third case
846
848
  `oats setup` carries the warning, a dry run included.
847
849
 
850
+ ### The upgrade event
851
+
852
+ `OATS_EVENT=upgrade` lets a staged destination package module adopt the state
853
+ of a stopped instance, for `oats instance upgrade` and `--undo`. It runs from
854
+ the staged new copy, with the usual lifecycle environment plus:
855
+
856
+ - `OATS_UPGRADE_PHASE`: `plan` or `apply`;
857
+ - `OATS_META`: the old recorded `capabilityMeta[capability]`;
858
+ - `OATS_UPGRADE_FROM`: JSON containing the recorded `from`, `commit` and
859
+ `digest`;
860
+ - `OATS_UPGRADE_TO`: JSON containing the locked destination entry;
861
+ - `OATS_UPGRADE_MODULE_DIR`: the module's final `<home>/.oats/modules/<cap>`
862
+ directory. Register host artifacts against this path, never the staging path,
863
+ which is removed after the move.
864
+
865
+ In `plan`, the hook is read-only. It prints `{"adopt":true}`, or
866
+ `{"adopt":false,"reason":"…","remedy":"…"}`. A module with recorded
867
+ capability metadata, or whose recorded old or destination manifest declares
868
+ `spawn` or `launch`, must declare this
869
+ hook; otherwise the plan refuses it and names respawn as the remedy. A module
870
+ with neither state nor those hooks can move without an upgrade hook.
871
+
872
+ In `apply`, the hook may change provider state inside the home and its own
873
+ host registrations. On success it prints `{meta, warning?}` and exits zero;
874
+ the kernel records `meta` as the module's new capability metadata. Apply must
875
+ be idempotent. A non-zero exit must leave no effects of its own, using
876
+ atomicity or compensation. The kernel treats that result as a hook reporting
877
+ failure; rollback restores composed home bytes only, and provider host effects
878
+ remain the provider's responsibility. The refusal error retains a bounded
879
+ provider `warning`, or stderr when no warning was reported.
880
+
881
+ Before commit, a failed upgrade rolls back only if no hook succeeded and no
882
+ hook outcome is uncertain. A hook's non-zero result must be observed and
883
+ recorded in that invocation to establish that it reported failure. A killed
884
+ or interrupted hook has an uncertain outcome, even if no success was recorded;
885
+ the receipt preserves that uncertainty before retrying it. Once a hook succeeds
886
+ or becomes uncertain, the act only finishes forward. Retry may run the same
887
+ idempotent hook again; a later refusal does not permit restoring old modules.
888
+ Its `partial` receipt names the same idempotency key to retry pending work,
889
+ or respawn if it cannot finish. Start refuses a partial upgrade. See
890
+ [the operator workflow](upgrading.md#moving-existing-homes-to-locked-package-versions).
891
+ After swap and baseline commit the receipt, the kernel publishes the success
892
+ event and cleans staging. A failure after commit is retried without hooks or
893
+ copies; start is allowed with a warning naming that retry.
894
+ Undo uses the hook of the version being restored, so it requires that version
895
+ to support adoption too. The event must never declare `required: true`.
896
+
848
897
  ### The worktree event
849
898
 
850
899
  `OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
@@ -302,6 +302,10 @@
302
302
  },
303
303
  "retire": {"$ref":"#/$defs/OptionalHook"},
304
304
  "launch": {"$ref":"#/$defs/OptionalHook"},
305
+ "upgrade": {
306
+ "$ref":"#/$defs/OptionalHook",
307
+ "description":"Runs from the staged destination module for a stopped home's package upgrade or undo. OATS_UPGRADE_PHASE=plan is read-only and prints {adopt:true} or {adopt:false,reason,remedy}; apply prints {meta,warning?} on success. A non-zero apply must leave no provider effects through atomicity or compensation: kernel rollback covers composed home bytes only. Receives OATS_META (recorded state), OATS_UPGRADE_FROM (recorded from/commit/digest) and OATS_UPGRADE_TO (locked destination entry) as JSON. Never required."
308
+ },
305
309
  "worktree": {
306
310
  "description": "Runs once in each tree the kernel creates: ./work of a work: worktree spawn (after the spawn hooks) and each `oats worktree add`. Its cwd is the new tree; see docs/capabilities.md, The worktree event.",
307
311
  "oneOf":[
@@ -0,0 +1,192 @@
1
+ # Upgrading an existing home's package modules (#1450)
2
+
3
+ Status: decided 2026-10-22 (Pepe, option (b) on #1450, with the five conditions of the lane:release view). This supersedes workspace model v2 items 10–11 **for package modules only**: "a package pin being bumped affects only new spawns" and "the refresh is a new spawn, never an in-place recompose". The soul body still stays at its spawn commit. Member modules still change only through a respawn.
4
+
5
+ ## Why
6
+
7
+ A home keeps the modules it was spawned with, and `oats session restart` starts that copy again. So a provider fix never reaches a live seat short of a respawn.
8
+
9
+ On 2026-10-22 a seat spawned on oats.aweb 1.17.1 was restarted. Its renewal revoked the old grant without re-registering the wake broker, a bug fixed in 1.17.3. Mail stopped arriving, and readiness, which also ran from the frozen 1.17.1 copy, stayed green. Respawning a long-lived coordinator to pick up a fix is not an acceptable remedy.
10
+
11
+ ## The act
12
+
13
+ ```
14
+ oats instance upgrade <instance> --plan [--json]
15
+ oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--json]
16
+ oats instance upgrade <instance> --undo --plan [--json]
17
+ oats instance upgrade <instance> --undo --plan-revision <rev> --idempotency-key <key> [--json]
18
+ ```
19
+
20
+ It runs from the deployment, or from a parent's home, with the same instance resolution as `oats retire`.
21
+
22
+ **What moves.** Every recorded module whose `from.kind` is `package` and whose recorded commit differs from the deployment lock's commit for that package moves to the locked package version. That is exactly the set that `driftOf` reports as "package moved since".
23
+ - Modules move whole: copy, skills, inject and hooks together (condition 1).
24
+ - A module of a package the lock no longer holds is not moved. The plan lists it as `kept: package no longer locked`.
25
+ - Member modules and the soul body are never moved. The plan lists member drift as information.
26
+
27
+ **Preconditions (all checked at plan and again at apply, under the instance's lifecycle claim):**
28
+ - **The session is stopped.** If it is running, or its state can't be read, the act refuses with `E_SESSION_RUNNING` and the remedy `oats instance stop <instance>`, then upgrade, then `oats session start`. Nothing changes under a running harness.
29
+ - **No retire or other lifecycle act is in flight.** Use the existing claim.
30
+ - Upgrade also holds the existing `.oats-start.lock` mutex until its final
31
+ invocation receipt is persisted; start/restart do not take the lifecycle
32
+ claim. Start acquires this path with `mkdir`; upgrade creates an exclusive
33
+ regular file with `wx`, so either kind refuses an occupied path. Upgrade
34
+ takes the lifecycle claim first and may reclaim only a regular-file mutex,
35
+ including an empty file left by a killed opener. It never reclaims a
36
+ directory. Start never reclaims the mutex and its busy message names the
37
+ same-key upgrade retry. A partial receipt refuses starts until finalization
38
+ completes.
39
+ - **The previous-state directory has no stray entries.** Check it before any
40
+ provider plan or apply hook runs.
41
+ - **The lock's package commit and integrity verify,** just as at spawn (`moduleSource`).
42
+
43
+ ## Plan (condition 3)
44
+
45
+ The plan is read-only. It returns:
46
+ - `homeChangedSinceSpawn`, whether retirement must preserve home changes;
47
+ - a revision, sha256 over the package-move facts (member drift and home-change reporting are informational), the same `planRevision` pattern as stop and retire;
48
+ - per moving module: `{capability, from:{version,commit,digest}, to:{version,commit,integrity}, skills:{added,removed,changed}, inject:changed?, hooks:changed?, provider:{decision, reason}}`;
49
+ - kept modules, with the reason;
50
+ - member drift, for information.
51
+
52
+ The plan writes nothing into the home, because the retire baseline compares home bytes. Like stop and retire plans, it touches nothing there. It stages the new copies in a temporary directory outside the home (`mkdtemp` under the OS temp dir) and removes that directory when it finishes.
53
+
54
+ **Provider adoption (condition 2).** For each moving module, the kernel needs to know whether the *new* version can take over the state the old version laid out. The kernel never guesses.
55
+ - **New lifecycle event `upgrade`.** It is approved in `lib/capability-contract.mjs` and `docs/capability-manifest.schema.json`. It must not be `required`. The kernel runs it from the **staged new copy**, with the usual `lifecycleHookEnv` plus:
56
+ - `OATS_UPGRADE_PHASE=plan|apply`;
57
+ - `OATS_META` (the recorded `capabilityMeta[cap]`, i.e. the old version's state);
58
+ - `OATS_UPGRADE_FROM` (JSON: the recorded `from`, commit, digest);
59
+ - `OATS_UPGRADE_TO` (JSON: the locked entry).
60
+ - **In `plan`** the hook is read-only and prints one of:
61
+ - `{"adopt": true}`;
62
+ - `{"adopt": false, "reason": "...", "remedy": "..."}`, for example naming the respawn.
63
+ - **In `apply`** it may change only provider state inside the home or provider-owned host registrations. One example is oats.aweb re-registering the wake broker against the recorded `grant.home`. It prints `{meta, warning?}` and exits 0, or exits non-zero to refuse.
64
+ A hook that exits non-zero must leave no effects of its own, by atomicity or
65
+ compensation. The kernel treats a failed hook as having made no changes;
66
+ its rollback covers composed home bytes, not provider-owned host effects.
67
+ Errors retain a bounded provider `warning` or stderr diagnosis, identify a
68
+ hook that reported failure, and state that host effects are the provider's responsibility.
69
+ - **Rules:**
70
+ - A moving module with recorded `capabilityMeta`, or one whose old or new manifest declares `spawn` or `launch` hooks, must declare `upgrade`. Otherwise its plan decision is `refuse: <cap> does not declare an upgrade hook; respawn the instance to change it`.
71
+ - A module with neither (skills/inject only) is adopted without a hook.
72
+ - One refusing module refuses the whole upgrade. There are no partial upgrades.
73
+ - **Older kernels.** An older kernel already treats an unknown non-required event as a warning (`capability-contract.mjs:52`), so a provider can declare `upgrade` before every host has the new kernel.
74
+
75
+ ## Apply
76
+
77
+ Apply runs under the claim, with the plan revision re-checked. A stale plan refuses with `E_PLAN_STALE` and attaches a fresh plan. Apply is idempotent per `--idempotency-key`, with a receipt like retire's, and does the following in order:
78
+
79
+ 1. **Stage.** Stage the new module copies in `<home>/.oats/.staging-upgrade-<receipt>`, on the same filesystem so the renames are atomic, and recompose the derived files there. Use the **same code as spawn**: refactor `materialize()` so that composing a home from a resolution can target an existing home. Do not write a second composer. The derived files are:
80
+ - `.agents/skills`;
81
+ - `AGENTS.md`: the soul body at the **recorded soul commit**, the kernel blocks, then each module's inject. If the soul body at that commit can't be read, refuse;
82
+ - in `instance.json`: `modules`, `capabilities[]`, `capabilityRuntime[]` (the absolute hook commands that retire runs), `skills[]`, `instructions[]`, `composition`, `launch.hooks.contributions`, `resolutionRevision`.
83
+ Read the soul body through discovery's path rule at that recorded commit:
84
+ a member soul uses `souls/<agent>/AGENTS.md`; a package soul uses its
85
+ manifest's explicit path. Upgrade never runs launch hooks. If a moved
86
+ module's new manifest has no launch hook, remove its recorded launch and
87
+ environment contribution inside the same journaled metadata swap. If it
88
+ still declares a launch hook, keep the contribution, with settings and trust
89
+ updated from the rebuilt capability, until the next start replaces it
90
+ wholesale through the standard launch refresh. Undo restores the recorded
91
+ contribution from the backed-up `instance.json`. No pending dropped-hook
92
+ state or `unsetEnv` JSON field is introduced; consecutive upgrades without
93
+ a start do not depend on an older previous manifest.
94
+ 2. **Keep the previous state.** This happens before anything outside staging changes. Copy `.oats/modules/<cap>` for each moving module, and the current `instance.json` and `AGENTS.md`, to `<home>/.oats/previous/<receipt>/` with `copyTreeSafe`, then verify the copy. This is not the retirement recovery root, so it is not mistaken for a retained retire.
95
+ 3. **Provider hooks.** Run each moving module's `upgrade` hook (`apply`) from the staged copy, in the plan's module order. `OATS_UPGRADE_MODULE_DIR` names its final `<home>/.oats/modules/<cap>` path: host registrations must use that path, never staging. Hooks must be idempotent in `apply`, because a retry runs them again.
96
+ Before spawning a hook, persist `step: "hook <capability>"` and
97
+ `hooks.inFlight: <capability>`. If execution is interrupted while that
98
+ outcome is unknown, resume must durably record `uncertain: [<capability>]`
99
+ before any retry work. The act then remains forward-only even when
100
+ `steps.hooks` contains no recorded success. A kill between that marker and
101
+ spawn also counts as uncertain unless not-started can be proved.
102
+ 4. **Swap.** Swap in place using materialize's rollback journal. Each moved module gets `modules.<cap>.previous = {from, commit, digest, materializedAt, receipt}` (one level, the latest move). `capabilityMeta[cap]` becomes the hook's `meta`.
103
+ 5. **Baseline.** Under the lifecycle claim, before staging, previous copies or
104
+ provider apply hooks change the home, compare it against the existing
105
+ retirement baseline with the same exclusions and comparison as retirement.
106
+ The plan shows `homeChangedSinceSpawn: true|false`. If the home is clean,
107
+ replace only `homeFingerprint` after the move, atomically. If it is dirty,
108
+ leave the entire baseline file byte-identical. Its old fingerprint keeps
109
+ classing the home as "changed instance-home bytes", including for older
110
+ kernels, which would ignore a new dirty-marker field. Later upgrades keep
111
+ that same dirty baseline; retirement writes its ordinary recovery copy.
112
+ An upgrade never re-takes `generatedWorkFingerprint` or changes the recorded
113
+ `digestVersion`: all work-tree changes remain compared against spawn.
114
+ Existing runtime authority and exclusions remain as recorded. No baseline
115
+ field, format migration or new recovery mechanism is introduced.
116
+ Upgrade receipts (the exact `upgrade-receipt.<key>.json` naming pattern)
117
+ and `.oats/.staging-upgrade-*` remain excluded. `.oats/previous/` is ordinary
118
+ home content. The comparison and clean replacement project out only the
119
+ upgrade's existing regular-file `.oats-start.lock`, using the exact-path
120
+ `transientHomePaths` validation. Future retire fingerprints still hash any
121
+ mutex left behind. A change made before the move is still a change at retire.
122
+ 6. **Commit.** After swap and baseline, record receipt `status: complete`
123
+ with `steps.cleaned: false`. This is the commit boundary: no success event
124
+ may be written before it, so rollback cannot leave a `modules-upgraded` row.
125
+ 7. **Event, then cleanup.** Append `modules-upgraded` with
126
+ `{receipt, modules:[{capability, from, to}]}`, deduplicated by receipt on
127
+ retry. The event kind is documented in the Desktop API and has a Desktop
128
+ label. Then clean staging and record `steps.cleaned: true`. A post-commit
129
+ failure leaves a committed upgrade: the same-key retry completes event
130
+ publication and cleanup without hooks or copies. Start remains allowed
131
+ with one warning naming that retry. A new upgrade or undo plan refuses
132
+ until finalization finishes, so staging cannot mix with another move.
133
+ Retirement keeps its existing behavior: staging is excluded and previous
134
+ copies remain ordinary home content.
135
+
136
+ **When a step fails before the commit boundary.** The rule is set by whether any provider hook's `apply` has succeeded or has an uncertain outcome. A hook can change host state (oats.aweb's wake re-register, for example), and restoring old modules under host state the new version adopted is the same mismatch #1450 is about.
137
+ - **No hook has succeeded or has an uncertain outcome:** roll back fully after a failure in steps 1–2. For a hook, only an explicit non-zero result observed and recorded in the same invocation, with no prior success or uncertainty, permits full rollback. Discard the staging and `<home>/.oats/previous/<receipt>`, change nothing in the home, and record a refusal event that names the step or module.
138
+ - **A hook has succeeded or has an uncertain outcome:** the act only finishes forward. The receipt records `partial` with the steps and modules already done. The error names what is pending, and says to retry with the same `--idempotency-key`. That retry re-runs pending work, including an uncertain idempotent hook, and finishes the swap, baseline and event. If the retried hook fails, the act stays `partial`; it never restores old modules. If the act can't be finished, the remedy named is a respawn. The home is never put back by hand under adopted or possibly adopted host state.
139
+ - **The session start** refuses while a `partial` receipt for the home exists (`E_UPGRADE_PARTIAL`, naming the retry).
140
+
141
+ **`--undo`** plans and applies the reverse move to `modules.<cap>.previous`, with the same steps and hooks; it is the `upgrade` hook of the version being restored. It works only for the latest move, and only while `<home>/.oats/previous/<receipt>` exists and verifies. The same adoption rule applies, so undo works only toward a version that declares `upgrade`. A move from a version without the hook, such as the motivating oats.aweb 1.17.1, cannot be undone through the act: its `.oats/previous/<receipt>` stays for inspection by hand, and the remedy for a bad move is a respawn.
142
+
143
+ **Lifetime of `.oats/previous/`.** Each home keeps one previous state, which the next move replaces. Retire carries it in its recovery copy like any other home content.
144
+
145
+ ## Restart and start (condition 4)
146
+
147
+ - `oats session start` and `oats session restart` never move modules.
148
+ - When a home has package drift, both print one line after the start, and the JSON gets `drift:[{capability, recorded, locked}]`: `<n> package module(s) behind the lock (<cap> <recorded> → <locked>); to move them: oats instance stop <i>; oats instance upgrade <i> --plan`.
149
+ `recorded` and `locked` are each `{version, commit}`. The text renders each
150
+ as `<version> @ <shortcommit>`, so a moved commit is visible even when the
151
+ version string is unchanged. Homes without package drift omit this field and
152
+ preserve the existing start/restart answer shape. If the lock cannot be read
153
+ (including malformed JSON or an unsupported lock version), start/restart
154
+ proceed, omit `drift`, and print one warning naming the lock and the reason.
155
+ - No flag on restart runs the upgrade.
156
+
157
+ ## Kernel stays runtime-neutral (condition 5)
158
+
159
+ The kernel knows modules, hooks, plans and receipts only. Anything aweb-specific lives in the provider's `upgrade` hook, such as grant-home adoption, the wake re-register, or refusing a 1.17.x meta shape it cannot adopt.
160
+
161
+ ## Surfaces
162
+
163
+ - **CLI:** `oats instance upgrade` with help text, in `bin/oats.mjs`.
164
+ - **Docs:**
165
+ - `docs/souls-and-instances.md:200` and `docs/first-team.md:166`: the invariant now reads "a running instance never changes under itself; a stopped one can be moved to the locked package versions with `oats instance upgrade`".
166
+ - `docs/desktop-cli-api.md`: the command, the event, `modules.<cap>.previous`, the start/restart `drift`.
167
+ - `docs/upgrading.md`: the deploy step after a package bump.
168
+ - The oats-operate skill.
169
+ - A release note.
170
+ - **`oats status`:** no change. Drift clears by itself after a move.
171
+ - **Desktop:** `modules.<cap>.previous` is a new field in JSON the Desktop reads. The implementation PR names lane:lfx as that reader and includes a test that the Desktop tolerates the field.
172
+
173
+ ## Out of scope
174
+
175
+ - Member modules and the soul body (still a respawn).
176
+ - Remote homes (`--server`).
177
+ - Moving several homes in one call (a deploy loops over instances).
178
+ - Desktop UI beyond the event label.
179
+ - Automatic upgrades.
180
+ - oats.aweb's `upgrade` hook, which is a separate provider spec and PR and ships after this kernel release with a kernel floor.
181
+
182
+ ## Acceptance
183
+
184
+ - Real-fixture tests:
185
+ - a stopped home on an older package version moves to the locked one. Afterwards its skills, AGENTS.md inject, hook commands, `modules` and `previous` match a fresh spawn on the locked version, apart from identity and timestamps;
186
+ - a running home refuses;
187
+ - a provider refusal changes nothing;
188
+ - a stale plan refuses;
189
+ - an idempotency replay works;
190
+ - `--undo` restores the previous bytes;
191
+ - retire after a move sees no unexplained home change.
192
+ - A live check on a scratch seat, after the provider's hook ships: a global-grant session seat spawned on an old oats.aweb is upgraded and restarted, then a signed mail is presented in the resumed session.
@@ -22,6 +22,10 @@ successor, with a link to its full text.
22
22
  - [Team model 3](2026-10-02-team-model-3.md): the teams a soul may join, and
23
23
  its default, are committed in the workspace; local teams only where the
24
24
  workspace allows them.
25
+ - [Module upgrade](2026-10-22-module-upgrade.md): `oats instance upgrade` moves
26
+ a stopped home's package modules to the locked versions, with plan, apply,
27
+ provider adoption and undo (supersedes workspace model v2 items 10–11 for
28
+ package modules).
25
29
 
26
30
  The Desktop's design brief for designers is in
27
31
  [packages/desktop/docs](../../packages/desktop/docs/design-brief.md).