@awebai/oats 0.66.0 → 0.68.0

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 (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  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 +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  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-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
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 {
@@ -60,18 +61,18 @@ import { kernelNode, stableNode } from "../lib/stable-node.mjs";
60
61
  import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
61
62
 
62
63
  import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
63
- import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
64
+ import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
64
65
  import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
65
66
  import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
66
67
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
67
- import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
68
+ import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
68
69
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
69
70
  import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
70
71
  import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
71
72
 
72
73
  const rawArgs = process.argv.slice(2);
73
74
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
74
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "skills", "verbose", "yes", "yolo"]);
75
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
75
76
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
76
77
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
77
78
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -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"];
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) => {
@@ -572,10 +573,13 @@ async function inspectCmd() {
572
573
  // Feature soul-skills: opt-in, soul subject only; without it no skill file is read.
573
574
  const skills = args.includes("--skills");
574
575
  if (skills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--skills lists a soul's own skills before a spawn: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
576
+ // Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
577
+ const composedSkills = args.includes("--composed-skills");
578
+ if (composedSkills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--composed-skills lists the skills a spawn of a soul would give its instance: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
575
579
  let t = await workspaceTarget(bail, { command: "inspect" });
576
580
  if (t) {
577
581
  if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
578
- if (instructions) t = await withComposedInstructions(t);
582
+ if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
579
583
  if (skills) t = await withSkills(t);
580
584
  const doc = inspectDocument(t, { kernel: OATS_VERSION });
581
585
  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
@@ -628,6 +632,11 @@ function printWorkspaceInspect(doc) {
628
632
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
629
633
  const composed = doc.souls[0].composedInstructions;
630
634
  if (composed !== undefined) console.log(composed ? `\nComposed AGENTS.md (a spawn here, resolution ${composed.resolution ?? "?"}${composed.truncated ? ", truncated" : ""}):\n\n${composed.text}` : "\nComposed AGENTS.md: unavailable (see the problems above)");
635
+ const composedSkills = doc.souls[0].composedSkills;
636
+ if (composedSkills !== undefined) {
637
+ if (!composedSkills) console.log("\nComposed skills: unavailable (see the problems above)");
638
+ else { console.log(`\nComposed skills (a spawn here): ${composedSkills.length || "none"}`); for (const k of composedSkills) console.log(` ${k.name} ${k.source === "soul" ? "soul" : k.source.slice("module:".length)}`); }
639
+ }
631
640
  }
632
641
 
633
642
  /** `{ teams, defaultTeam, teamsSource }` for a session start of a workspace home: its teams read
@@ -1310,12 +1319,70 @@ function retiredInstanceAddresses(root, name, home) {
1310
1319
  * instance's work tree. The instance is addressed qualified: an explicit
1311
1320
  * --home, or a name under the --dir scope (team roots included) that resolves
1312
1321
  * to exactly one home; several homes refuse with every candidate named. */
1313
- 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() {
1314
1379
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
1315
1380
  const sub = args[1], name = args[2];
1381
+ if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1316
1382
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1317
- 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]";
1318
- if (!["git", "diff", "stop", "events"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1383
+ if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
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]";
1385
+ if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1319
1386
  dropAmbientRoot();
1320
1387
  if (sub === "events") {
1321
1388
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1348,6 +1415,29 @@ function instanceCmd() {
1348
1415
  return;
1349
1416
  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
1350
1417
  }
1418
+ if (sub === "color") {
1419
+ // Feature instance-color: presentation only, so no plan; addressed as stop addresses an instance.
1420
+ const homeOpt = flag("home");
1421
+ if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1422
+ const colorUsage = "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
1423
+ // The words after the instance that are not a flag or the value of --home or --dir: the colour, at most one.
1424
+ const words = [];
1425
+ for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1426
+ const clear = args.includes("--clear");
1427
+ if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
1428
+ const value = words[0];
1429
+ if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
1430
+ if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
1431
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1432
+ try {
1433
+ const r = setInstanceColor(dirFlag(), root, name, { home: homeOpt, color: clear ? null : value });
1434
+ if (JSON_MODE) { jsonOk(r); return; }
1435
+ console.log(`${r.instance}: ${r.color === null ? "no colour" : `colour ${r.color}`}${r.changed ? "" : " (unchanged)"}`);
1436
+ return;
1437
+ } catch (e) {
1438
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1439
+ }
1440
+ }
1351
1441
  if (sub === "stop") {
1352
1442
  // K3: plan → apply. The plan is what a confirmation shows; apply carries
1353
1443
  // its revision back and refuses if reality moved.
@@ -2701,7 +2791,17 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
2701
2791
  * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
2702
2792
  * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2703
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"]);
2704
- const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
2794
+ const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "suggest-name", "yolo"]);
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. */
2798
+ function suggestNameProblem(argv) {
2799
+ if (!argv.includes("--suggest-name")) return undefined;
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";
2803
+ return undefined;
2804
+ }
2705
2805
  /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
2706
2806
  * soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
2707
2807
  * flag() reads it; a missing value is the flag's own check. */
@@ -2728,12 +2828,21 @@ function herdrSpawnFlag() {
2728
2828
  if (flag("herdr-socket") !== undefined) return "--herdr-socket";
2729
2829
  return undefined;
2730
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
+ }
2731
2838
  /** A spawn preview's text: the local one, or a host's answer to a routed
2732
2839
  * preview (`server`, its id), which this side printed the same way (#610). */
2733
2840
  function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2734
2841
  // A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
2735
2842
  const harness = r.harness ?? r.runtime;
2736
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)" : ""}`);
2844
+ // Feature spawn-suggest-name: how the name was chosen.
2845
+ { const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
2737
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");
2738
2847
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2739
2848
  }
@@ -2752,7 +2861,7 @@ async function spawnCmd() {
2752
2861
  };
2753
2862
  checkDirectoryOptions(requestedWork); // before anything is resolved or written
2754
2863
  const name = args[1];
2755
- if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>] [--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]");
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]");
2756
2865
  // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
2757
2866
  // ANY side effect, including root discovery.
2758
2867
  // Local souls (local-agents/) are gone with the workspace model: a soul is a member
@@ -2763,6 +2872,7 @@ async function spawnCmd() {
2763
2872
  const nameFlag = flag("name");
2764
2873
  if (nameFlag === true) bail("E_BAD_ARGS", "--name needs an instance name (a slug: lowercase letters and digits, single dashes between them)");
2765
2874
  if (nameFlag !== undefined && flag("purpose") !== undefined) bail("E_BAD_ARGS", "--name and --purpose are mutually exclusive: --name is the exact instance name, --purpose derives <agent>-<purpose>");
2875
+ { const problem = suggestNameProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
2766
2876
  // The slug rule is checked here too, before any side effect (soul fetch).
2767
2877
  if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
2768
2878
  if (args.includes("--ephemeral")) bail("E_BAD_ARGS", "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics");
@@ -2957,6 +3067,7 @@ async function spawnCmd() {
2957
3067
  // K6: --preview decides everything and touches nothing; --base <ref>
2958
3068
  // selects a worktree's start point; --model @native-default is the
2959
3069
  // explicit "harness's own default" (distinct from omitting --model).
3070
+ ...(args.includes("--suggest-name") ? { suggestName: true } : {}),
2960
3071
  ...(args.includes("--preview") ? { preview: true, subject: { soul: name, agentsRoot: agentsRootFlag !== undefined ? String(agentsRootFlag) : null, dir: flag("dir") !== undefined && flag("dir") !== true ? String(flag("dir")) : null } } : {}),
2961
3072
  ...(flag("base") !== undefined && flag("base") !== true ? { baseRef: flag("base") } : {}),
2962
3073
  // A confirmed preview binds this apply (K6b): drift → E_DECISION_STALE, nothing created.
@@ -3012,11 +3123,14 @@ async function spawnCmd() {
3012
3123
  launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
3013
3124
  // #796: the worktree hooks this spawn ran, with their logs; only when it ran any.
3014
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 } : {}),
3015
3128
  });
3016
3129
  return;
3017
3130
  }
3018
3131
  console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
3019
3132
  console.log(` home: ${shortPath(r.home)}`);
3133
+ { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
3020
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})`);
3021
3135
  for (const h of r.worktreeHooks || []) console.log(` setup: ${h.capability} worktree hook ${h.ok ? "ok" : "FAILED"} (log: ${shortPath(h.log)})`);
3022
3136
  if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
@@ -3489,6 +3603,8 @@ async function sessionCmd() {
3489
3603
  // recorded launch stays frozen (a changed preference never reaches an existing home on its own).
3490
3604
  const reselectLaunch = args.includes("--reselect-launch");
3491
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);
3492
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)) };
3493
3609
  if (args[1] === "restart") {
3494
3610
  const grace = flag("stop-grace");
@@ -3518,6 +3634,11 @@ async function sessionCmd() {
3518
3634
  console.log(JSON.stringify(result, null, 2));
3519
3635
  // A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
3520
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
+ }
3521
3642
  }
3522
3643
  } catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
3523
3644
  }
@@ -4534,7 +4655,7 @@ async function serverRouteCmd() {
4534
4655
  const herdr = herdrSpawnFlag();
4535
4656
  if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
4536
4657
  const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
4537
- const problem = spawnArgvProblem(local);
4658
+ const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
4538
4659
  if (problem) bail("E_BAD_ARGS", problem);
4539
4660
  }
4540
4661
  // Everything after the command word travels, minus the routing flags; a
@@ -4596,6 +4717,7 @@ async function serverRouteCmd() {
4596
4717
  else if (cmd === "spawn") {
4597
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"}`);
4598
4719
  console.log(` remote home: ${r.home}`);
4720
+ { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
4599
4721
  console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
4600
4722
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
4601
4723
  console.log(` attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
@@ -4690,7 +4812,8 @@ try {
4690
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
4691
4813
  // help, and silent: no output, no change to the command's answer or exit status.
4692
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"]);
4693
- 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);
4694
4817
  if (cmd === "onboard") {
4695
4818
  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
4696
4819
  await onboardCmd();
@@ -4702,6 +4825,9 @@ else {
4702
4825
  // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
4703
4826
  const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
4704
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)");
4705
4831
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4706
4832
  else if (cmd === "server") await serverCmd();
4707
4833
  else if (cmd === "deployments") deploymentsCmd();
@@ -4721,7 +4847,7 @@ else if (cmd === "update") {
4721
4847
  }
4722
4848
  else if (cmd === "harness") harnessTrustCmd();
4723
4849
  else if (cmd === "readiness") await readinessCmd();
4724
- else if (cmd === "instance") instanceCmd();
4850
+ else if (cmd === "instance") await instanceCmd();
4725
4851
  else if (cmd === "worktree") await worktreeCmd();
4726
4852
  else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
4727
4853
  else if (cmd === "sync") await syncCmd();
@@ -4961,6 +5087,12 @@ Usage:
4961
5087
  instance.json providers.<capability>)
4962
5088
  [--preview] decide everything, create no instance; --json
4963
5089
  includes the decision revision for confirmation
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
4964
5096
  [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
4965
5097
  [--idempotency-key <key>] with --expect-decision, replay the completed receipt
4966
5098
  for the same key and confirmed decision; a different
@@ -4993,13 +5125,15 @@ Usage:
4993
5125
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
4994
5126
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
4995
5127
  [--instructions] [--skills] installed capabilities with health, effective
4996
- [--max-age <s>] [--json] layer bindings and activation, declared
4997
- operations with availability; --home answers the
5128
+ [--composed-skills] [--max-age <s>] layer bindings and activation, declared
5129
+ [--json] operations with availability; --home answers the
4998
5130
  running home's recorded modules and their drift
4999
5131
  from the deployment; --instructions (--soul only)
5000
5132
  adds the AGENTS.md a spawn of the soul here would write;
5001
5133
  --skills (--soul only) adds the soul's own skills, the
5002
- ones a spawn copies, with each file's text
5134
+ ones a spawn copies, with each file's text;
5135
+ --composed-skills (--soul only) adds every skill a spawn
5136
+ would give the instance, its capabilities' included
5003
5137
  oats operation run <layer>:<name> run an operation the soul's core capability for that
5004
5138
  (--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
5005
5139
  [--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
@@ -5096,12 +5230,27 @@ Usage:
5096
5230
  oats instance attention [--message <text>] [--clear] [--json]
5097
5231
  run by the agent from its home: "I need a human's
5098
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.
5099
5237
  oats instance stop <instance> --plan [--no-recursive] [--json]
5100
5238
  what Stop would touch: session state, recorded
5101
5239
  children, dirty work; a planRevision to apply
5102
5240
  oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
5103
5241
  quiesce (SIGTERM, bounded, never escalated),
5104
5242
  children first; home/work/launch retained
5243
+ oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
5244
+ the instance's colour, presentation only: sand,
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
5105
5254
  oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
5106
5255
  [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
5107
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
@@ -272,7 +274,7 @@ A self-contained package has an `oats.json`:
272
274
  `.a*`);
273
275
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
274
276
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
275
- `.oats-agents-md`, `.oats-start` or `.oats-attachments`: the top-level
277
+ `.oats-agents-md`, `.oats-start`, `.oats-attachments` or `.oats-color`: the top-level
276
278
  entries the kernel itself writes in an instance home;
277
279
  - a prefix that starts with `.oats-`.
278
280
 
@@ -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
@@ -996,15 +1045,15 @@ latest-state capability.
996
1045
  ### oats.core: needs input
997
1046
 
998
1047
  oats.core (2.4.0 and later, kernel 0.40.0 and later) tells the deployment
999
- when an instance is blocked on a human, in two independent ways. Each shows
1048
+ when an instance is waiting on a human, in two independent ways. Each shows
1000
1049
  on `oats status` and in `oats instance events`. The verbs' contract
1001
1050
  (`oats instance waiting`, `oats instance attention`, the `waiting` event) is
1002
1051
  in [desktop-cli-api.md](desktop-cli-api.md#waiting-on-you). Claims are
1003
1052
  display-only: nothing in the kernel acts on them.
1004
1053
 
1005
1054
  **The agent's own claim.** The oats.core inject and `/oats-operate` teach
1006
- every instance this protocol. When it has asked a human something and cannot
1007
- continue without the answer, it runs
1055
+ every instance this protocol. Whenever it needs anything from a human (a
1056
+ question, a decision, an approval, a credential, any input it waits on), it runs
1008
1057
  `oats instance attention --message "<one line>"` from its home and ends its
1009
1058
  turn. Once it has the answer, it runs `oats instance attention --clear`. The
1010
1059
  claim belongs to producer `agent`. Only `--clear` or the next session start,
@@ -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":[
@@ -362,7 +366,7 @@
362
366
  "description": "Home entries the kernel owns cannot be declared.",
363
367
  "anyOf": [
364
368
  {"pattern": "^\\.(?:oats|agents|claude)$"},
365
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments)"},
369
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
366
370
  {"pattern": "^\\.oats-.*\\*$"}
367
371
  ]
368
372
  }