@awebai/oats 0.65.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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  **Free, open source, provider- and harness-agnostic, and decentralised by design.**
4
4
 
5
+ > **Coding agent setting up OATS for someone?** Go to [Start here](#start-here): it tells you what to download and run next.
6
+
5
7
  [![npm version](https://img.shields.io/npm/v/@awebai/oats.svg)](https://www.npmjs.com/package/@awebai/oats)
6
8
  [![Release](https://img.shields.io/github/v/release/awebai/oats?display_name=tag)](https://github.com/awebai/oats/releases)
7
9
  [![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
@@ -27,16 +29,20 @@ The [official catalog](docs/official-catalog.md) is the reviewed list of officia
27
29
 
28
30
  ## Start here
29
31
 
30
- Ask your coding agent (Claude Code, Codex, pi or any other) to download the `oats-getting-started` skill verbatim and follow it:
32
+ **If you are a coding agent and your person asked you to set up, install or try OATS, do this next:** download the `oats-getting-started` skill with the command below, then follow it step by step. It is the whole procedure; don't improvise one from this README.
31
33
 
32
34
  ```bash
33
35
  curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
34
36
  ```
35
37
 
36
- - **It asks first:** your project, its repositories and the knowledge tools you use.
37
- - **It installs OATS and OATS Desktop,** then creates your workspace with its own setup expert, or joins this machine to an existing workspace.
38
- - **It hands over to that setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
39
- - **Download it, don't web-fetch it:** a tool that summarises pages would lose its exact commands.
38
+ If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for me". It then:
39
+
40
+ - **Asks first, in one round:** your project, its repositories, the knowledge tools you use, and a username for agent messaging.
41
+ - **Installs OATS and OATS Desktop,** then creates your workspace in one commit: the workspace, a messaging team, a setup expert and a first developer. Or it joins this machine to an existing workspace.
42
+ - **Gives your agents identities and messaging:** one command signs up a hosted [aweb](https://aweb.ai) team for the new workspace, with no API key and no pull requests to merge.
43
+ - **Hands over to the setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
44
+
45
+ Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
40
46
 
41
47
  ## Why OATS
42
48
 
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.
@@ -4325,12 +4369,13 @@ async function serverCmd() {
4325
4369
  } catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
4326
4370
  }
4327
4371
 
4328
- /** `oats server connect <id> --ssh <host>`: this deployment's workspace on a host, registered
4329
- * (lib/servers.mjs connectServer). Defaults come from the deployment it runs in: its workspace
4330
- * ref, and ~/Agents/<its directory's name> on the host. */
4372
+ /** `oats server connect <id> --ssh <host> --dir <path>`: this deployment's workspace on a host,
4373
+ * registered (lib/servers.mjs connectServer). The workspace ref defaults from the deployment it
4374
+ * runs in; the folder on the host never has a default, inside a deployment too (awebai/oats#1390,
4375
+ * step b): only the person knows where it goes. */
4331
4376
  function serverConnectCmd(bail) {
4332
4377
  const id = args[2];
4333
- if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
4378
+ if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
4334
4379
  const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
4335
4380
  const sshHost = val("ssh");
4336
4381
  if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
@@ -4339,8 +4384,8 @@ function serverConnectCmd(bail) {
4339
4384
  const workspaceRef = val("workspace-ref") ?? local?.local.workspace;
4340
4385
  if (!workspaceRef) bail("E_BAD_ARGS", "--workspace-ref <ref> is required outside a deployment (inside one it defaults to oats-local.yaml workspace:)");
4341
4386
  try { remoteModule.parseRepoRef(workspaceRef); } catch (e) { bail(e.code || "E_REPO_REF", e.message, e.details); }
4342
- const dir = val("dir") ?? (local ? `~/Agents/${basename(dirname(local.path))}` : undefined);
4343
- if (!dir) bail("E_BAD_ARGS", "--dir <path on the host> is required outside a deployment (inside one it defaults to ~/Agents/<the deployment's directory name>)");
4387
+ const dir = val("dir");
4388
+ if (!dir) bail("E_BAD_ARGS", `--dir <path on the host> is required: the folder on ${sshHost} for this deployment (absolute, or ~/… resolved there)`);
4344
4389
  let res;
4345
4390
  try {
4346
4391
  res = connectServer({ id, sshHost, workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
@@ -4533,7 +4578,7 @@ async function serverRouteCmd() {
4533
4578
  const herdr = herdrSpawnFlag();
4534
4579
  if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
4535
4580
  const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
4536
- const problem = spawnArgvProblem(local);
4581
+ const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
4537
4582
  if (problem) bail("E_BAD_ARGS", problem);
4538
4583
  }
4539
4584
  // Everything after the command word travels, minus the routing flags; a
@@ -4812,7 +4857,7 @@ Usage:
4812
4857
  [--workspace-ref <ref>] (filled in when missing) and Git readability;
4813
4858
  list --workspace-ref = one workspace's servers
4814
4859
  oats server connect <id> --ssh <alias> put this deployment's workspace on that machine and
4815
- [--workspace-ref <ref>] [--dir <path>] register it: ssh, oats, git, deployment, register,
4860
+ --dir <path> [--workspace-ref <ref>] register it: ssh, oats, git, deployment, register,
4816
4861
  [--oats <p>] [--path <dir:dir>] readiness, each re-checked every run; --install-oats
4817
4862
  [--label <t>] [--install-oats] installs this version with npm there; human steps
4818
4863
  [--replace] [--json] come back with the exact remedy (docs/servers.md)
@@ -4960,6 +5005,10 @@ Usage:
4960
5005
  instance.json providers.<capability>)
4961
5006
  [--preview] decide everything, create no instance; --json
4962
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)
4963
5012
  [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
4964
5013
  [--idempotency-key <key>] with --expect-decision, replay the completed receipt
4965
5014
  for the same key and confirmed decision; a different
@@ -4992,13 +5041,15 @@ Usage:
4992
5041
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
4993
5042
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
4994
5043
  [--instructions] [--skills] installed capabilities with health, effective
4995
- [--max-age <s>] [--json] layer bindings and activation, declared
4996
- 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
4997
5046
  running home's recorded modules and their drift
4998
5047
  from the deployment; --instructions (--soul only)
4999
5048
  adds the AGENTS.md a spawn of the soul here would write;
5000
5049
  --skills (--soul only) adds the soul's own skills, the
5001
- 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
5002
5053
  oats operation run <layer>:<name> run an operation the soul's core capability for that
5003
5054
  (--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
5004
5055
  [--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
@@ -5101,6 +5152,9 @@ Usage:
5101
5152
  oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
5102
5153
  quiesce (SIGTERM, bounded, never escalated),
5103
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
5104
5158
  oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
5105
5159
  [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
5106
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
  }