@awebai/oats 0.66.0 → 0.67.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 (65) hide show
  1. package/bin/oats.mjs +66 -13
  2. package/docs/capabilities.md +4 -4
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/desktop-cli-api.md +217 -6
  5. package/docs/desktop.md +101 -22
  6. package/docs/implementation.md +6 -5
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-lane.md +16 -0
  10. package/docs/release-notes/v0.67.0.md +366 -0
  11. package/docs/release-notes/v0.67.1.md +64 -0
  12. package/docs/servers.md +3 -2
  13. package/docs/souls-and-instances.md +20 -3
  14. package/docs/tui.md +570 -176
  15. package/docs/upgrading.md +107 -25
  16. package/docs/workspaces.md +1 -1
  17. package/lib/capability-contract.mjs +2 -2
  18. package/lib/core.mjs +126 -54
  19. package/lib/instance-color.mjs +58 -0
  20. package/lib/instance-inspect.mjs +107 -23
  21. package/lib/instance-lifecycle.mjs +21 -1
  22. package/lib/instance-naming.mjs +187 -0
  23. package/lib/instance-resolution.mjs +5 -1
  24. package/lib/materialize.mjs +62 -11
  25. package/lib/servers.mjs +15 -6
  26. package/lib/soul-composition.mjs +7 -3
  27. package/package-catalog.json +1 -1
  28. package/package.json +1 -1
  29. package/packages/client/cli-adapter.mjs +37 -5
  30. package/packages/client/cli-locator.mjs +2 -2
  31. package/packages/client/composed-gate.mjs +10 -2
  32. package/packages/client/deployment-data.mjs +5 -0
  33. package/packages/client/deployment-identity.mjs +40 -0
  34. package/packages/client/deployment-panel.mjs +3 -1
  35. package/packages/client/inspect-boundary.mjs +11 -7
  36. package/packages/client/inspect-cache.mjs +2 -2
  37. package/packages/client/instance-name.mjs +28 -0
  38. package/packages/client/instance-presentation.mjs +11 -0
  39. package/packages/client/keymap.mjs +85 -24
  40. package/packages/client/keys-file.mjs +122 -0
  41. package/packages/client/own-codes.mjs +4 -2
  42. package/packages/client/panel-views.mjs +62 -9
  43. package/packages/client/spawn-naming.mjs +31 -0
  44. package/packages/client/spawn-preview-cli.mjs +22 -7
  45. package/packages/client/spawn-preview-contract.mjs +24 -0
  46. package/packages/client/spawn-preview-facts.mjs +8 -4
  47. package/packages/client/spawn-preview.mjs +47 -2
  48. package/packages/tui/README.md +3 -3
  49. package/packages/tui/lib/actions.mjs +57 -14
  50. package/packages/tui/lib/client.mjs +8 -4
  51. package/packages/tui/lib/config.mjs +50 -9
  52. package/packages/tui/lib/main.mjs +40 -13
  53. package/packages/tui/lib/model.mjs +167 -63
  54. package/packages/tui/lib/read.mjs +53 -1
  55. package/packages/tui/lib/store.mjs +148 -54
  56. package/packages/tui/lib/term/keys.mjs +19 -5
  57. package/packages/tui/lib/term/kitty.mjs +36 -11
  58. package/packages/tui/lib/term/through.mjs +61 -28
  59. package/packages/tui/lib/views/frame.mjs +158 -79
  60. package/packages/tui/lib/views/help.mjs +109 -26
  61. package/packages/tui/lib/views/instances.mjs +59 -20
  62. package/packages/tui/lib/views/palette.mjs +14 -4
  63. package/packages/tui/lib/views/souls.mjs +2 -2
  64. package/packages/tui/lib/views/switcher.mjs +6 -1
  65. package/skills/oats-getting-started/SKILL.md +13 -8
package/bin/oats.mjs CHANGED
@@ -60,18 +60,18 @@ import { kernelNode, stableNode } from "../lib/stable-node.mjs";
60
60
  import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
61
61
 
62
62
  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";
63
+ import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
64
64
  import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
65
65
  import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
66
66
  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";
67
+ import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
68
68
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
69
69
  import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
70
70
  import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
71
71
 
72
72
  const rawArgs = process.argv.slice(2);
73
73
  /** 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"]);
74
+ 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
75
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
76
76
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
77
77
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -107,7 +107,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
107
107
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
108
108
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
109
109
  * 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"];
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
111
  /** Commands `--server <id>` runs on a registered server. */
112
112
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
113
113
  const flag = (name) => {
@@ -572,10 +572,13 @@ async function inspectCmd() {
572
572
  // Feature soul-skills: opt-in, soul subject only; without it no skill file is read.
573
573
  const skills = args.includes("--skills");
574
574
  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/)");
575
+ // Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
576
+ const composedSkills = args.includes("--composed-skills");
577
+ 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
578
  let t = await workspaceTarget(bail, { command: "inspect" });
576
579
  if (t) {
577
580
  if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
578
- if (instructions) t = await withComposedInstructions(t);
581
+ if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
579
582
  if (skills) t = await withSkills(t);
580
583
  const doc = inspectDocument(t, { kernel: OATS_VERSION });
581
584
  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
@@ -628,6 +631,11 @@ function printWorkspaceInspect(doc) {
628
631
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
629
632
  const composed = doc.souls[0].composedInstructions;
630
633
  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)");
634
+ const composedSkills = doc.souls[0].composedSkills;
635
+ if (composedSkills !== undefined) {
636
+ if (!composedSkills) console.log("\nComposed skills: unavailable (see the problems above)");
637
+ 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)}`); }
638
+ }
631
639
  }
632
640
 
633
641
  /** `{ teams, defaultTeam, teamsSource }` for a session start of a workspace home: its teams read
@@ -1314,8 +1322,8 @@ function instanceCmd() {
1314
1322
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
1315
1323
  const sub = args[1], name = args[2];
1316
1324
  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);
1325
+ 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
+ if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1319
1327
  dropAmbientRoot();
1320
1328
  if (sub === "events") {
1321
1329
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1348,6 +1356,29 @@ function instanceCmd() {
1348
1356
  return;
1349
1357
  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
1350
1358
  }
1359
+ if (sub === "color") {
1360
+ // Feature instance-color: presentation only, so no plan; addressed as stop addresses an instance.
1361
+ const homeOpt = flag("home");
1362
+ if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1363
+ const colorUsage = "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
1364
+ // The words after the instance that are not a flag or the value of --home or --dir: the colour, at most one.
1365
+ const words = [];
1366
+ 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]); }
1367
+ const clear = args.includes("--clear");
1368
+ if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
1369
+ const value = words[0];
1370
+ if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
1371
+ if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
1372
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1373
+ try {
1374
+ const r = setInstanceColor(dirFlag(), root, name, { home: homeOpt, color: clear ? null : value });
1375
+ if (JSON_MODE) { jsonOk(r); return; }
1376
+ console.log(`${r.instance}: ${r.color === null ? "no colour" : `colour ${r.color}`}${r.changed ? "" : " (unchanged)"}`);
1377
+ return;
1378
+ } catch (e) {
1379
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1380
+ }
1381
+ }
1351
1382
  if (sub === "stop") {
1352
1383
  // K3: plan → apply. The plan is what a confirmation shows; apply carries
1353
1384
  // its revision back and refuses if reality moved.
@@ -2701,7 +2732,15 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
2701
2732
  * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
2702
2733
  * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2703
2734
  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"]);
2735
+ 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. */
2738
+ function suggestNameProblem(argv) {
2739
+ 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";
2742
+ return undefined;
2743
+ }
2705
2744
  /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
2706
2745
  * soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
2707
2746
  * flag() reads it; a missing value is the flag's own check. */
@@ -2734,6 +2773,9 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2734
2773
  // A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
2735
2774
  const harness = r.harness ?? r.runtime;
2736
2775
  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
+ // 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)})`);
2737
2779
  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
2780
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2739
2781
  }
@@ -2752,7 +2794,7 @@ async function spawnCmd() {
2752
2794
  };
2753
2795
  checkDirectoryOptions(requestedWork); // before anything is resolved or written
2754
2796
  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]");
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]");
2756
2798
  // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
2757
2799
  // ANY side effect, including root discovery.
2758
2800
  // Local souls (local-agents/) are gone with the workspace model: a soul is a member
@@ -2763,6 +2805,7 @@ async function spawnCmd() {
2763
2805
  const nameFlag = flag("name");
2764
2806
  if (nameFlag === true) bail("E_BAD_ARGS", "--name needs an instance name (a slug: lowercase letters and digits, single dashes between them)");
2765
2807
  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>");
2808
+ { const problem = suggestNameProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
2766
2809
  // The slug rule is checked here too, before any side effect (soul fetch).
2767
2810
  if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
2768
2811
  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 +3000,7 @@ async function spawnCmd() {
2957
3000
  // K6: --preview decides everything and touches nothing; --base <ref>
2958
3001
  // selects a worktree's start point; --model @native-default is the
2959
3002
  // explicit "harness's own default" (distinct from omitting --model).
3003
+ ...(args.includes("--suggest-name") ? { suggestName: true } : {}),
2960
3004
  ...(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
3005
  ...(flag("base") !== undefined && flag("base") !== true ? { baseRef: flag("base") } : {}),
2962
3006
  // A confirmed preview binds this apply (K6b): drift → E_DECISION_STALE, nothing created.
@@ -4534,7 +4578,7 @@ async function serverRouteCmd() {
4534
4578
  const herdr = herdrSpawnFlag();
4535
4579
  if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
4536
4580
  const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
4537
- const problem = spawnArgvProblem(local);
4581
+ const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
4538
4582
  if (problem) bail("E_BAD_ARGS", problem);
4539
4583
  }
4540
4584
  // Everything after the command word travels, minus the routing flags; a
@@ -4961,6 +5005,10 @@ Usage:
4961
5005
  instance.json providers.<capability>)
4962
5006
  [--preview] decide everything, create no instance; --json
4963
5007
  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)
4964
5012
  [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
4965
5013
  [--idempotency-key <key>] with --expect-decision, replay the completed receipt
4966
5014
  for the same key and confirmed decision; a different
@@ -4993,13 +5041,15 @@ Usage:
4993
5041
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
4994
5042
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
4995
5043
  [--instructions] [--skills] installed capabilities with health, effective
4996
- [--max-age <s>] [--json] layer bindings and activation, declared
4997
- operations with availability; --home answers the
5044
+ [--composed-skills] [--max-age <s>] layer bindings and activation, declared
5045
+ [--json] operations with availability; --home answers the
4998
5046
  running home's recorded modules and their drift
4999
5047
  from the deployment; --instructions (--soul only)
5000
5048
  adds the AGENTS.md a spawn of the soul here would write;
5001
5049
  --skills (--soul only) adds the soul's own skills, the
5002
- ones a spawn copies, with each file's text
5050
+ ones a spawn copies, with each file's text;
5051
+ --composed-skills (--soul only) adds every skill a spawn
5052
+ would give the instance, its capabilities' included
5003
5053
  oats operation run <layer>:<name> run an operation the soul's core capability for that
5004
5054
  (--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
5005
5055
  [--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
@@ -5102,6 +5152,9 @@ Usage:
5102
5152
  oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
5103
5153
  quiesce (SIGTERM, bounded, never escalated),
5104
5154
  children first; home/work/launch retained
5155
+ oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
5156
+ the instance's colour, presentation only: sand,
5157
+ sage, slate, mauve, clay or olive; --clear removes it
5105
5158
  oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
5106
5159
  [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
5107
5160
  [--preview] [--json] <base> (the clone's refs are not moved), then run the
@@ -272,7 +272,7 @@ A self-contained package has an `oats.json`:
272
272
  `.a*`);
273
273
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
274
274
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
275
- `.oats-agents-md`, `.oats-start` or `.oats-attachments`: the top-level
275
+ `.oats-agents-md`, `.oats-start`, `.oats-attachments` or `.oats-color`: the top-level
276
276
  entries the kernel itself writes in an instance home;
277
277
  - a prefix that starts with `.oats-`.
278
278
 
@@ -996,15 +996,15 @@ latest-state capability.
996
996
  ### oats.core: needs input
997
997
 
998
998
  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
999
+ when an instance is waiting on a human, in two independent ways. Each shows
1000
1000
  on `oats status` and in `oats instance events`. The verbs' contract
1001
1001
  (`oats instance waiting`, `oats instance attention`, the `waiting` event) is
1002
1002
  in [desktop-cli-api.md](desktop-cli-api.md#waiting-on-you). Claims are
1003
1003
  display-only: nothing in the kernel acts on them.
1004
1004
 
1005
1005
  **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
1006
+ every instance this protocol. Whenever it needs anything from a human (a
1007
+ question, a decision, an approval, a credential, any input it waits on), it runs
1008
1008
  `oats instance attention --message "<one line>"` from its home and ends its
1009
1009
  turn. Once it has the answer, it runs `oats instance attention --clear`. The
1010
1010
  claim belongs to producer `agent`. Only `--clear` or the next session start,
@@ -362,7 +362,7 @@
362
362
  "description": "Home entries the kernel owns cannot be declared.",
363
363
  "anyOf": [
364
364
  {"pattern": "^\\.(?:oats|agents|claude)$"},
365
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments)"},
365
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
366
366
  {"pattern": "^\\.oats-.*\\*$"}
367
367
  ]
368
368
  }
@@ -119,6 +119,8 @@ see the [official catalog](official-catalog.md) for current pins.
119
119
  | `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
120
120
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
121
121
  | `soul-skills` | `oats inspect --soul <soul> --skills` and its `souls[].skills`: the soul's own skills, the ones a spawn of it copies, with each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
122
+ | `soul-composed-skills` | `oats inspect --soul <soul> --composed-skills` and its `souls[].composedSkills`: every skill a spawn of the soul gives its instance, its own and its capabilities', each with its `source` and each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)). The same kernels name each capability skill of `spawn --preview`'s `skills[]` as the spawn does ([The preview](#the-preview)) | |
123
+ | `spawn-suggest-name` | `oats spawn <soul> --preview --suggest-name`: the preview also chooses the name, from the task, through the soul's own harness, and says how in `naming` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)). Suggested names work on claude and pi; codex is numbered (`unsupported-harness`). Routed, the host needs the feature | |
122
124
  | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
123
125
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
124
126
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
@@ -135,6 +137,7 @@ see the [official catalog](official-catalog.md) for current pins.
135
137
  | `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
136
138
  | `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
137
139
  | `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
140
+ | `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
138
141
  | `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
139
142
  | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
140
143
 
@@ -437,7 +440,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
437
440
  ### `oats inspect`
438
441
 
439
442
  ```text
440
- oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
443
+ oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
441
444
  ```
442
445
 
443
446
  An instance subject, abridged:
@@ -463,7 +466,7 @@ An instance subject, abridged:
463
466
  "recordedDefaultTeam":{"label":"eng","team":null,"from":"soul"},
464
467
  "knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"status","kind":"view","available":true,"reason":null}]},
465
468
  "instance":{"home":"/w/agents/rm/instances/rm-1","instance":"rm-1","agent":"rm","harness":"pi","model":null,"yolo":null,"launched":false,
466
- "createdAt":"2026-09-28T10:08:01.281Z","resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
469
+ "createdAt":"2026-09-28T10:08:01.281Z","color":null,"resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
467
470
  "instructions":{"file":"/w/agents/rm/instances/rm-1/AGENTS.md","text":"…","truncated":false,
468
471
  "sources":[{"source":"capability:oats.okf","file":"/w/agents/rm/instances/rm-1/.oats/modules/oats.okf/injects/okf.md"}]}},
469
472
  "identity":null,
@@ -479,7 +482,7 @@ An instance subject, abridged:
479
482
  | `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
480
483
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
481
484
  | `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
482
- | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
485
+ | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)) |
483
486
  | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
484
487
  | `problems` | below |
485
488
  | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
@@ -588,6 +591,48 @@ probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
588
591
  and nothing is sent. Every text is untrusted repository content: render it as
589
592
  plain text or through a sanitising renderer.
590
593
 
594
+ `composedSkills` (feature `soul-composed-skills`) is present only with
595
+ `--composed-skills`, which takes a soul subject (`--home` is `E_BAD_ARGS`) and
596
+ combines with `--instructions` and `--skills`; without the flag the key is
597
+ absent and nothing extra is composed. It lists every skill an instance of this
598
+ soul gets: the soul's own and each capability's.
599
+
600
+ ```json
601
+ "composedSkills":[{"name":"oats-operate","source":"module:oats.core","path":".oats/modules/oats.core/skills/oats-operate",
602
+ "description":"…","files":[{"path":".oats/modules/oats.core/skills/oats-operate/SKILL.md","bytes":1234,"text":"…","binary":false,"truncated":false}],
603
+ "filesTruncated":false},
604
+ {"name":"release-checklist","source":"soul","path":"skills/release-checklist","description":"Cutting a release.",
605
+ "files":[…],"filesTruncated":false}]
606
+ ```
607
+
608
+ - One row per skill, sorted by `name` in codepoint order. `source` is
609
+ `"soul"` or `"module:<capability id>"`, the vocabulary of `instance.json`
610
+ `skills` and of the spawn preview.
611
+ - `path` is POSIX. A soul skill's is relative to the soul directory, as in
612
+ `skills`; a capability skill's is relative to the instance home, where the
613
+ instance carries the capability's copy (`.oats/modules/<id>/…`). Each
614
+ file's `path` starts with its skill's.
615
+ - The rest of a row, and every rule for its files, is `skills`' above, with
616
+ one difference: the whole field carries at most 2 MiB (2,097,152 bytes) of
617
+ `text`, summed over every file in answer order, whichever source it comes
618
+ from. Problems name `composedSkills: ` instead of `skills: `.
619
+ - It is computed by the same scratch materialization as `--instructions`
620
+ (one serves both when both are given): the soul's skills by the
621
+ enumerator spawn uses, read from the soul copy, and the capability skills
622
+ materialize placed, read from the scratch copy before it is removed. It
623
+ runs no hooks and writes nothing in the deployment.
624
+ - It is `null` when a spawn would refuse a collision between a soul skill and
625
+ a capability skill (names compare case-insensitively), with the problem
626
+ `{code: "E_SKILL_DUPLICATE", message: "composedSkills: skill \"<name>\"
627
+ from soul collides with module <id>'s skill"}`, the sentence spawn refuses
628
+ with. It is `null` when the soul resolves but cannot be composed here, with
629
+ the composition's code and sentence, naming `composedSkills`. It is `null`
630
+ with `soul-skills-unreadable` when the soul's own skills cannot be listed.
631
+
632
+ Routed with `--server <id>`, `--composed-skills` travels to the host; a host
633
+ whose probe does not advertise `soul-composed-skills` is refused with
634
+ `E_REMOTE_INCOMPATIBLE`, and nothing is sent.
635
+
591
636
  **Layers.** `id` is the capability filling the slot or `null`. `from`
592
637
  (feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
593
638
  or a home spawned before it was recorded.
@@ -2430,7 +2475,13 @@ it to a temporary copy (`soulFetched: true`).
2430
2475
  - `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
2431
2476
  `member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
2432
2477
  strings, module skills as `{name, source: "module:<cap>"}`) are display
2433
- only: bind to `modules[]` and `decision`.
2478
+ only: bind to `modules[]` and `decision`. A module skill's `name` is a
2479
+ skill the spawn copies, by the rule it copies by: a manifest entry that
2480
+ holds skill directories lists each of them, and a manifest with no
2481
+ `skills` lists each `skills/<dir>/` holding a `SKILL.md`, read at the
2482
+ module's commit (feature `soul-composed-skills`; earlier kernels named such
2483
+ an entry by its own directory, `skills`, and listed nothing for a manifest
2484
+ with no `skills`).
2434
2485
  - `resolution` (24 hex) hashes `declRevision` (the declarations) and
2435
2486
  `payloadRevision` (the merged payloads). `workspace` is the host key;
2436
2487
  `standalone` marks a standalone view. `task` is the task text or `null`.
@@ -2450,6 +2501,102 @@ it to a temporary copy (`soulFetched: true`).
2450
2501
  new head and revision. An apply with `--expect-decision` may reuse heads
2451
2502
  too (feature `spawn-apply-max-age`, [Apply](#apply)).
2452
2503
 
2504
+ #### The suggested name (feature `spawn-suggest-name`)
2505
+
2506
+ ```text
2507
+ oats spawn <soul> --preview --suggest-name --task-file <f> [the flags of a real spawn] [--json]
2508
+ ```
2509
+
2510
+ A preview that also chooses the instance's name, from the task (`--task-file`,
2511
+ or `--task <text>`). Like every preview it writes nothing and runs no hooks.
2512
+ - `--suggest-name` without `--preview`, or with `--name` or `--purpose`, is
2513
+ `E_BAD_ARGS`.
2514
+ - **The call.** The kernel makes one non-interactive call through the
2515
+ harness, executable and environment the spawn would launch (the launch
2516
+ configuration's `env`, not its `args`), with this prompt on stdin, never in
2517
+ argv:
2518
+
2519
+ > Name an agent for this task: 2–4 lowercase words joined by hyphens, describing the work, not the role. Reply with the name only.
2520
+ >
2521
+ > Task:
2522
+ > <the task text, at most 4000 characters>
2523
+
2524
+ It runs from a fresh empty temporary directory, removed afterwards, with no
2525
+ `OATS_INSTANCE*` variable, without a shell, in its own process group. It is
2526
+ made after the preview's harness checks (the executable's lookup and the
2527
+ harness package probes, from where the home will be) and before anything
2528
+ that depends on the name (placement, branch, home). It takes what those
2529
+ checks leave of the preview's one 20 s preflight budget, which is not
2530
+ raised for it: the group is killed after 20 s, or when the budget runs out
2531
+ first. Its time counts in `preflight.elapsedMs`; `preflight.status` stays
2532
+ that of the checks, so a numbered preview after a `timeout` is confirmed
2533
+ like any other. At most 4 KiB of its output is read.
2534
+ - **It starts none of the user's code: no MCP server, hook, plugin,
2535
+ extension or project setting, and no tool on either harness.** Three
2536
+ exceptions are stated:
2537
+ - Claude Code's own built-in plugins (`cc-plugin-*@builtin`) load as
2538
+ they always do, `--bare` included.
2539
+ - Hooks in the host's managed policy (`managed-settings.json`) still
2540
+ apply: they are the host admin's.
2541
+ - pi runs its own credential commands (`!command` keys and headers in
2542
+ models.json), as every pi launch does: they are its login.
2543
+
2544
+ A claude login through `apiKeyHelper` is not read (`--setting-sources
2545
+ ""`): such a user gets `harness-failed` and a numbered name.
2546
+
2547
+ Each harness's argv is proven to start nothing else
2548
+ (`scripts/naming-isolation-proof.mjs`, a recorded run against fixtures,
2549
+ rerun by an operator after a harness upgrade). The proof covers claude
2550
+ 2.1.288 and pi 1.3.0, on Linux; macOS is not proven.
2551
+ - **claude**, model `haiku`: `-p --tools "" --strict-mcp-config
2552
+ --setting-sources "" --disable-slash-commands --no-session-persistence
2553
+ --output-format text --model haiku`. Its native login is kept, which
2554
+ `--bare` would not keep.
2555
+ - **pi**, the instance's model: `-p --no-session --no-tools
2556
+ --no-extensions --no-mcp --no-skills --no-prompt-templates --no-themes
2557
+ --no-context-files --no-approve [--model <m>]`.
2558
+ - **codex** is not supported. Its naming call is not proven to start
2559
+ nothing, so a codex soul is numbered with `unsupported-harness`.
2560
+ - **The name.**
2561
+ 1. The reply's first non-empty line, as a slug.
2562
+ 2. Without one or more trailing `-<role>`. The role is the last word of the
2563
+ soul's name, after any package qualifier.
2564
+ 3. At most 4 words, cut at a word boundary to fit
2565
+ `64 − 1 − len(role)`.
2566
+ 4. Nothing left, or only the role, is `invalid-reply`.
2567
+ 5. The name is `<descriptive>-<role>`. A name that is taken (an instance,
2568
+ a soul or a live window, as for `--name`) gets `-2`, `-3`, and so on.
2569
+ - **The answer** is the full preview, plus `naming`:
2570
+
2571
+ ```json
2572
+ "naming": { "source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku" }
2573
+ ```
2574
+
2575
+ ```json
2576
+ "naming": { "source": "numbered", "reason": "timeout", "message": "claude gave no name within 20 s", "ms": 20000 }
2577
+ ```
2578
+
2579
+ - With `source: "suggested"`, `instance`, `home`, `branch` and `decision`
2580
+ are those of a preview with `--name <instance>`: an apply with `--name
2581
+ <instance> --expect-decision <revision>` matches it.
2582
+ - With `source: "numbered"`, they are today's numbered name, and the apply
2583
+ goes without `--name`.
2584
+ - `reason` is one of a closed set:
2585
+ - `no-task`: no task, or a blank one; no call is made.
2586
+ - `unsupported-harness`: no call is made.
2587
+ - `timeout`.
2588
+ - `harness-failed`: a nonzero exit, a signal, or no executable. `message`
2589
+ gives the exit or the signal, never the output.
2590
+ - `invalid-reply`.
2591
+ - `model` is `null` when the harness runs its own default.
2592
+ - A failure is never an error: the preview answers.
2593
+ - The text preview prints `name: suggested by claude (haiku) in 2310 ms` or
2594
+ `name: numbered (<reason>: <message>)`.
2595
+ - **`--server`:** the call runs on the target machine, through the routed
2596
+ preview, and the task travels as a routed spawn's does. A host that does
2597
+ not advertise `spawn-suggest-name` is refused (`E_REMOTE_INCOMPATIBLE`)
2598
+ before the spawn is sent.
2599
+
2453
2600
  **Provider settings.**
2454
2601
  - `providers` is the `--provider` map as typed.
2455
2602
  - `settings.<cap>`: the merged payload (manifest defaults, then workspace,
@@ -2583,6 +2730,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2583
2730
  `E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
2584
2731
  a silent `-2`.
2585
2732
  - The name is part of the decision.
2733
+ - `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
2734
+ descriptive name for the task, `<descriptive>-<role>`, which the apply then
2735
+ passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
2586
2736
 
2587
2737
  ### Spawn origin
2588
2738
 
@@ -3006,6 +3156,12 @@ its absence.
3006
3156
  An older kernel's `running` is the window's presence, and it checks a row
3007
3157
  with a claim against its session (as `oats session inspect` observes it),
3008
3158
  reading `null` unless a harness runs there.
3159
+ - **`color`** (feature `instance-color`): the instance's colour, one of
3160
+ `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
3161
+ from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
3162
+ a `color` in `instance.json` never stands in for it. Every row has it,
3163
+ an unreadable record's row included (`null`). Presentation only: it is not
3164
+ identity and never addresses anything.
3009
3165
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
3010
3166
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
3011
3167
  is running, scheduled or owed; absent otherwise, and from older kernels.
@@ -3166,7 +3322,7 @@ route target:
3166
3322
  "soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
3167
3323
  "modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
3168
3324
  "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
3169
- "retirePending":false,"rollbackIncomplete":false,
3325
+ "color":"sage","retirePending":false,"rollbackIncomplete":false,
3170
3326
  "savedRoute":false,"addressable":true,"missingRemotely":false}],
3171
3327
  "retireFailures":[]}
3172
3328
  ```
@@ -3461,6 +3617,7 @@ instance's own machine: the local command, with `--server <id>` added.
3461
3617
  | `oats instance git\|diff <name> --server <id> …` | `instance-git` | `instance-git`, `instanceGitApi: 1` |
3462
3618
  | `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
3463
3619
  | `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
3620
+ | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
3464
3621
 
3465
3622
  - The flags are the local command's. The instance is addressed like every
3466
3623
  routed instance command ([servers.md](servers.md#run-there)): `--home` as
@@ -3731,7 +3888,7 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
3731
3888
 
3732
3889
  ### Waiting on you
3733
3890
 
3734
- Feature `waiting-on-you` (OATS 0.40.0): an instance blocked on a human (a
3891
+ Feature `waiting-on-you` (OATS 0.40.0): an instance waiting on a human (a
3735
3892
  permission prompt, a question, an agent asking for an answer) says so through
3736
3893
  a producer's claim. **Claims are display-only:** nothing in the kernel acts
3737
3894
  on `waitingOnYou`. In particular `oats session input` behaves exactly as
@@ -5379,6 +5536,60 @@ removal begins, and only with the home kept (`reached.home: "kept"`). A
5379
5536
  typed refusal keeps its code, its details and its own words; the inspections'
5380
5537
  and the recovery's refusals end with the sentence of their phase, once.
5381
5538
 
5539
+ ## An instance's colour (`oats instance color`)
5540
+
5541
+ Feature `instance-color` (awebai/oats#1421).
5542
+
5543
+ ```text
5544
+ oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]
5545
+ ```
5546
+
5547
+ The colour is presentation, not identity. Anyone may change it at any time,
5548
+ the agent on its own instance included, and it is never an address.
5549
+
5550
+ - **The palette** is closed: `sand`, `sage`, `slate`, `mauve`, `clay`,
5551
+ `olive`, the clients' own (`packages/client/soul-colors.mjs`).
5552
+ - **The record** is `<home>/.oats-color.json`, `{"colorApi": 1, "color":
5553
+ "sage", "at": "<ISO time>"}`, mode 0600, written atomically. `--clear`
5554
+ removes it. It is a kernel-owned home file: a capability cannot declare it
5555
+ as its own, and it is no change to the home at retire.
5556
+ - **A reader** takes a regular file only, without following a link, of at
5557
+ most 4 KiB. Anything that is not such a valid record reads as no colour
5558
+ (`null`), never as an error.
5559
+ - **The instance** is addressed as `oats instance stop` addresses it, and
5560
+ refused with the same answers: not found, ambiguous, a `--home` that is not
5561
+ its home, a record that cannot be read.
5562
+
5563
+ The answer:
5564
+
5565
+ ```json
5566
+ {"instanceColorApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","color":"sage","changed":true}
5567
+ ```
5568
+
5569
+ `color` is `null` after `--clear`. Setting the colour the instance already
5570
+ has answers `changed: false` and writes nothing; so does clearing an instance
5571
+ with no colour.
5572
+
5573
+ | Code | When |
5574
+ |---|---|
5575
+ | `E_BAD_ARGS` | The colour is not in the palette: `"<value>" is not an instance colour: use one of sand, sage, slate, mauve, clay, olive, or --clear`. Also: both a colour and `--clear`, neither, or two colours |
5576
+ | *(as `oats instance stop`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
5577
+ | `E_INSTANCE_RETIRING` | A retire of the home is in flight (its pending marker, or a live retire holding the home's lifecycle claim, which the command reads and never takes, as `oats worktree add` reads it), or the home is quarantined. Nothing was written |
5578
+ | `E_LIFECYCLE_BUSY` | The home's claim file cannot be read as a claim, or a retire's liveness cannot be read, as for `oats worktree add` |
5579
+
5580
+ Routed with `--server <id>`, the command runs on the host
5581
+ ([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
5582
+ not advertise `instance-color` is refused with `E_REMOTE_INCOMPATIBLE`, and
5583
+ nothing is sent.
5584
+
5585
+ Where it is read: `color` on [status rows](#the-roster-oats-status---json),
5586
+ on [remote roster rows](#the-remote-roster-oats-server-roster---json) (only a
5587
+ palette name is relayed, anything else is `null`), and on `oats inspect
5588
+ --home` as `instance.color`. A client draws a row's colour by one rule,
5589
+ `instanceColor(row)` in `packages/client/instance-presentation.mjs`: the
5590
+ row's palette name, else none. Colour never says a state alone: a client's
5591
+ mark keeps the state by its shape.
5592
+
5382
5593
  ## Sessions and launch configurations
5383
5594
 
5384
5595
  ### Input