@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/docs/upgrading.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # Upgrading OATS on a host
2
2
 
3
+ This page opens with the upgrade to the latest version. The steps that are
4
+ the same for every release follow, then what each older release asks of a
5
+ host that comes from it.
6
+
7
+ ## Upgrading to the latest version
8
+
9
+ The latest version is **OATS 0.67.1** ([release notes](release-notes/v0.67.1.md)).
10
+ The 0.67.1 Desktop accepts OATS CLIs `>=0.26.0 <0.68.0`.
11
+
12
+ **First, read the `## Upgrade` section of every release after yours, up to
13
+ 0.67.1,** in the [release notes](release-notes/): it says what to do before
14
+ the CLI changes, and what else must change with it (the Desktop, another
15
+ tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
+ names the releases that ask for more than the steps below. `oats version`
17
+ prints the version you have.
18
+
19
+ Then, on each host:
20
+
21
+ ```sh
22
+ # 0. where the Desktop is installed: Desktop 0.67.1 first
23
+ npm install -g @awebai/oats@0.67.1 # 1. the CLI
24
+ oats update # 2. in each deployment: the plan, then it asks before it runs
25
+ oats doctor # 3. in the same deployment
26
+ ```
27
+
28
+ The Desktop's installers are the assets of the
29
+ [GitHub Release](https://github.com/awebai/oats/releases) of that version
30
+ ([OATS Desktop](desktop.md#install)). Then restart the pi sessions that were
31
+ running: a session keeps the bridge it loaded when it started.
32
+ [The steps](#the-steps) says what each step does and why they come in this
33
+ order.
34
+
35
+ An agent with the oats.setup capability does this with you through its
36
+ `/oats-upgrade` skill. It reads this page and the release notes at the
37
+ latest release's tag, never the copy in the installed CLI, which describes
38
+ the version you are upgrading from.
39
+
40
+ ## The steps
41
+
3
42
  Upgrading OATS means three things, in this order, on each host, and one
4
43
  before them where the Desktop is installed:
5
44
 
@@ -14,17 +53,14 @@ must be at the same version: a pi session with an older bridge runs old
14
53
  extension code against a new kernel. A host that launches no pi instance has
15
54
  no bridge, and step 2 has nothing to move.
16
55
 
17
- **A release's own steps are in its notes.** Read the `## Upgrade` section of
18
- every version between yours and the new one in the
19
- [release notes](release-notes/) first: it says what to do before the CLI
20
- changes, and what else must change with it (the Desktop, another tool, a
21
- package pin). This page is the part that is the same for every release.
56
+ **A release's own steps are in its notes**, in its `## Upgrade` section.
57
+ This page is the part that is the same for every release.
22
58
 
23
59
  **Why the Desktop goes first.** A Desktop accepts a CLI up to its own minor
24
60
  version and refuses a newer one: with the CLI moved first, the Desktop that
25
61
  is still running lists no instance until it is replaced. The new Desktop
26
62
  accepts the older CLI in the meantime. The CLI can move by two commands, the
27
- `npm install` below and an `oats update` whose plan installs it: step 0 comes
63
+ `npm install` and an `oats update` whose plan installs it: step 0 comes
28
64
  before either.
29
65
 
30
66
  **Package versions are a different thing.** `oats update` moves the CLI and
@@ -32,18 +68,8 @@ the bridge, never a package. A deployment's capabilities come from the
32
68
  packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
33
69
  ([Packages](packages.md)).
34
70
 
35
- ## The steps
36
-
37
- ```sh
38
- # 0. where the Desktop is installed: the new version's Desktop first
39
- npm install -g @awebai/oats # 1. the CLI
40
- oats update # 2. in a deployment: the plan, then it asks before it runs
41
- oats doctor # 3. in the same deployment
42
- ```
43
-
44
71
  Run steps 2 and 3 in every deployment on the host, or name one from anywhere
45
- with `oats update --dir <deployment>`. Then restart the pi sessions that were
46
- running: a session keeps the bridge it loaded when it started.
72
+ with `oats update --dir <deployment>`.
47
73
 
48
74
  In a terminal, `oats update` shows its plan and asks before it runs anything.
49
75
  Without a terminal (a script, an agent's shell) it runs only with `--yes`.
@@ -74,7 +100,66 @@ Versions are compared as semver, so a prerelease is below its release:
74
100
  no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
75
101
  installed over it.
76
102
 
77
- ## Capture service release order
103
+ ## Coming from an older version
104
+
105
+ Read the `## Upgrade` section of every release after yours, up to the
106
+ latest: each release's own steps are there, and only there. This list is a
107
+ guide to them, not a replacement: it names, newest first, the releases whose
108
+ Upgrade section asks a host for more than [the steps](#the-steps), the order
109
+ of the Desktop and the CLI, and an optional package pin. A change a script
110
+ must follow is in its release's Upgrade section whether or not it is listed
111
+ here.
112
+
113
+ - **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
114
+ 0.67.1:** the leader is Ctrl+X in OATS Desktop and in `oats tui`, on every
115
+ platform; a leader you rebound is kept. A `tui.json` that gives `ctrl+x` to an action and names no leader
116
+ stops `oats tui` from starting: give that action another key, or name a
117
+ leader ([Change the keys](tui.md#change-the-keys-tuijson)). On Linux and
118
+ Windows the shared shortcuts are Ctrl+Alt; a terminal that passes
119
+ Ctrl+Shift apart from Ctrl takes the Ctrl+Shift option.
120
+ - **[0.66.0](release-notes/v0.66.0.md#upgrade):** `oats tui` moves its key
121
+ file to `~/.oats/config/tui.json`; `oats server connect` needs `--dir`.
122
+ - **[0.62.0](release-notes/v0.62.0.md#upgrade):** after the CLI, run
123
+ `oats setup` once per user on each host, from that user's shell: the
124
+ capture service ([Capture service release order](#capture-service-release-order)).
125
+ - **[0.61.0](release-notes/v0.61.0.md#upgrade):** restart a pi instance stuck
126
+ on its opening task once the bridge has moved; `oats onboard`'s
127
+ `next.spawn` names the soul that holds oats.setup.
128
+ - **[0.60.0](release-notes/v0.60.0.md#upgrade):** `running` in
129
+ `oats status --json` means the harness is running.
130
+ - **[0.59.0](release-notes/v0.59.0.md#upgrade):** with oats.aweb 1.28.0, a
131
+ host that needs the wake broker installs it once (`oats aweb wake install`,
132
+ from its own login session); `oats tui`'s back key is pressed twice.
133
+ - **[0.58.0](release-notes/v0.58.0.md#upgrade):** on a Mac, upgrade the CLI
134
+ before the next reboot.
135
+ - **[0.57.1](release-notes/v0.57.1.md#upgrade):** upgrade the hosts a Desktop
136
+ reaches over `--server` too; `oats tui`'s panel needs tmux 3.2 or later.
137
+ - **[0.57.0](release-notes/v0.57.0.md#upgrade):** a retire plan taken before
138
+ the upgrade is refused once (`E_PLAN_STALE`); `oats worktree remove` may
139
+ refuse with `E_CHILDREN_RUNNING`; with oats.okf 5.2.0, new spawns carry the
140
+ harvest duty unless the soul opts out.
141
+ - **[0.56.0](release-notes/v0.56.0.md#upgrade):** new refusal codes for
142
+ scripts; `open-workspace` in `tui.json` is `open`; a launch gets only its
143
+ capabilities' declared environment.
144
+ - **[0.55.1](release-notes/v0.55.1.md#upgrade):** pin oats.aweb 1.27.3 and run
145
+ `oats sync`: on 1.27.2, readiness reports every home the host wake broker
146
+ serves as `unavailable`.
147
+ - **[0.55.0](release-notes/v0.55.0.md#upgrade):** the first capture after the
148
+ upgrade takes longer.
149
+ - **[0.53.0](release-notes/v0.53.0.md#upgrade):** from 0.51 or earlier, do
150
+ 0.52.0's steps first (aw 1.36.33 or later, before `oats sync`); once the
151
+ CLI is 0.53.0, run `oats update` in each deployment that launches pi (an
152
+ older CLI's `oats update` moves the default pi folder only); run
153
+ `oats setup` again where it was run; restart Claude Code instances on a
154
+ Homebrew `node`; rerun `oats aweb resident create` for an existing
155
+ resident custody unit; `oats doctor` names unmatched `souls.launch` keys.
156
+
157
+ **Coming from before 0.53.0:** read the whole notes of every release after
158
+ yours: up to 0.39.0 the section may be called `## Upgrading` or
159
+ `## Upgrading from <version>`, and some releases give their order under
160
+ another heading (0.49.0's oats.okf 5.0 cutover, for one).
161
+
162
+ ### Capture service release order
78
163
 
79
164
  The bounded periodic capture service (service A) is **not shipped in
80
165
  [0.56.0](release-notes/v0.56.0.md) through [0.61.0](release-notes/v0.61.0.md)**
@@ -85,16 +170,13 @@ existing capture watcher, and upgrading to any of them does not install the
85
170
  periodic service. The capture algorithms and recovery commands already
86
171
  released do not prove that migration happened.
87
172
 
88
- For those released versions, follow their own Upgrade sections and the steps
89
- above. In particular, install the target Desktop before the CLI: the 0.61.0
90
- Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI.
173
+ For those released versions, follow their own Upgrade sections and
174
+ [the steps](#the-steps), the target Desktop before the CLI.
91
175
 
92
176
  Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
177
  release. Read 0.62.0's Upgrade section and keep this order: install the
94
- Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
- `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
96
- Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`, the 0.66.0 Desktop `>=0.26.0 <0.67.0`), then that
97
- release's CLI and matching pi bridge. Only **after
178
+ Desktop of the release you upgrade to first (its notes give the CLIs
179
+ it accepts), then that release's CLI and matching pi bridge. Only **after
98
180
  installing that CLI**, run its setup conversion once per user on each host,
99
181
  from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
100
182
  watcher is replaced by the periodic service; foreign or disabled definitions
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.13.4 # bare version → resolves through the official catalog
57
+ oats.framework: v1.13.5 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -180,13 +180,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
180
180
  * declaration may not cover them: these exact names, and every exact name
181
181
  * starting with one of these prefixes (the events log; the stop, restart and
182
182
  * start receipts and locks; the rollback marker; AGENTS.md backups; the
183
- * attachments directory). This is the one list: a new kernel-written top-level
183
+ * attachments directory; the instance colour, `.oats-color.json`). This is the one list: a new kernel-written top-level
184
184
  * home entry MUST be added here and to the `not` patterns of
185
185
  * `retirement.disposable.home` in docs/capability-manifest.schema.json. A
186
186
  * prefix declaration can reach none of them except through `.oats-`, which is
187
187
  * refused whole; `.oats-<provider>` as an exact name stays declarable. */
188
188
  const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
189
- const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments"];
189
+ const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color"];
190
190
 
191
191
  /** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
192
192
  * name or prefix), "kernel-owned", or undefined when it is sound. */
package/lib/core.mjs CHANGED
@@ -50,6 +50,7 @@ import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
50
50
  import { createSessionPaneInspector, inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
51
51
  import { appendEvent, incarnationOf, liveWaiting, recordStartBoundary, retireRefusedReason } from "./instance-events.mjs";
52
52
  import { killGroup } from "./process-group.mjs";
53
+ import { NAMING_TIMEOUT_MS, suggestInstanceName } from "./instance-naming.mjs";
53
54
  import { interruptExitStatus, isStartToken, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
54
55
  import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, claimUnheld, claimWrite, readClaim, releaseClaim, removeGoneClaim, shownHolder, unwritableCode } from "./claim.mjs";
55
56
  import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
@@ -62,6 +63,7 @@ import { PANE_PATH_FIX, harnessNotOnPanePath, harnessUnavailable, launchConfigAm
62
63
  import { shq, shellWord } from "./shell-word.mjs";
63
64
  import { CONFIG_DIR_VAR, HARNESS_FOLDER_VAR, claudeTrusts, codexTrustsRoot, harnessConfigFile, harnessTrustWarning, launchConfigFolder } from "./harness-trust.mjs";
64
65
  async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
66
+ async function plannedSkillsDefault(prepared) { const m = await import("./instance-resolution.mjs"); return m.plannedPreparedSkills(prepared); }
65
67
  // Capability rows for a PREPARED spawn (workspace model): the one function that
66
68
  // turns a Resolution's modules into the row shape hooks/environment/requirements/
67
69
  // retirement consume. Called twice per spawn — PLANNED before the home exists
@@ -90,6 +92,7 @@ import { assertSameWorktreeHead, gitRead, gitRefPresence, gitRepoRead, gitRepoRu
90
92
  import { systemTool } from "./system-tools.mjs";
91
93
  import { creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
92
94
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
95
+ import { readInstanceColor } from "./instance-color.mjs";
93
96
  /** The package and capability id grammar (namespaced, lowercase): an id names a
94
97
  * directory (a home's module copy), so no path spelling fits it. */
95
98
  const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
@@ -608,7 +611,9 @@ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME
608
611
  "OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS",
609
612
  // The test seams of #915: the cgroup the kernel judges itself in, and the directories its systemd-run
610
613
  // comes from (lib/tmux-server-scope.mjs, lib/system-tools.mjs).
611
- "OATS_TEST_CGROUP", "OATS_TEST_SYSTEM_TOOL_DIRS"]);
614
+ "OATS_TEST_CGROUP", "OATS_TEST_SYSTEM_TOOL_DIRS",
615
+ // The test seam of #1421 §3: the naming call's time limit (lib/instance-naming.mjs NAMING_TIMEOUT_MS).
616
+ "OATS_TEST_NAMING_TIMEOUT_MS"]);
612
617
  export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
613
618
  const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
614
619
  export function validateLaunchConfig(name, entry, where) {
@@ -3822,6 +3827,20 @@ function* spawnBody(root, agent, o = {}) {
3822
3827
  }
3823
3828
  }
3824
3829
 
3830
+ // --suggest-name (feature spawn-suggest-name, awebai/oats#1421 §3): a preview that also chooses the
3831
+ // name, by a naming call through this launch's harness and executable, under its environment, after
3832
+ // the preflight's probes and within its one budget (below, where the executable is known). Until
3833
+ // then the preview proceeds with the numbered name, holding any refusal that is that name's own
3834
+ // (`provisional`); a suggested name is then placed exactly as `--name <suggested>` is, so the
3835
+ // preview's instance, home, branch and decision are that preview's, and an apply with `--name
3836
+ // <instance> --expect-decision <revision>` matches it. Otherwise the numbered name stands, its held
3837
+ // refusal with it. `naming` says which, and why; a failed call is never an error.
3838
+ let naming, provisional;
3839
+ const suggesting = o.suggestName === true;
3840
+ if (suggesting) {
3841
+ if (o.preview !== true) throw oatsError("E_BAD_ARGS", "--suggest-name is a preview's: it chooses the name a spawn would get; pass --preview");
3842
+ if (o.name !== undefined || o.purpose !== undefined || o.instance !== undefined) throw oatsError("E_BAD_ARGS", "--suggest-name chooses the name: it takes no --name or --purpose");
3843
+ }
3825
3844
  if (o.name !== undefined && (o.purpose !== undefined || o.instance !== undefined)) throw oatsError("E_BAD_ARGS", "name and purpose are mutually exclusive: --name is the exact instance name, --purpose derives <soul>-<purpose>");
3826
3845
  let instance;
3827
3846
  if (o.name !== undefined) instance = explicitInstanceName(o.name);
@@ -3951,6 +3970,7 @@ function* spawnBody(root, agent, o = {}) {
3951
3970
  // too, since the anchor's instance.json is re-pointed.
3952
3971
  let anchorHome;
3953
3972
  let anchorRoot;
3973
+ let reverseShadow = () => null;
3954
3974
  if (relativeTo) {
3955
3975
  const hits = [];
3956
3976
  for (const h of findInstanceHomes(root, relativeTo)) hits.push({ root, home: h.home });
@@ -3985,11 +4005,16 @@ function* spawnBody(root, agent, o = {}) {
3985
4005
  // relation=parent re-points the ANCHOR at the NEW instance by bare name:
3986
4006
  // that reverse edge must round-trip from the ANCHOR's root as well.
3987
4007
  if (relation === "parent") {
3988
- const rev = findInstanceHome(chosen.root, instance);
3989
4008
  // The new instance does not exist yet — a hit here IS a shadow.
3990
- if (rev) throw Object.assign(
3991
- new Error(`relation "parent": an existing instance named "${instance}" (${rev.home}) would shadow the new instance from the anchor's root — the re-pointed edge would resolve to the wrong instance; pick a different --purpose or --name`),
3992
- { code: "E_RELATIVE_AMBIGUOUS" });
4009
+ reverseShadow = (name) => {
4010
+ const rev = findInstanceHome(chosen.root, name);
4011
+ return rev ? Object.assign(
4012
+ new Error(`relation "parent": an existing instance named "${name}" (${rev.home}) would shadow the new instance from the anchor's root — the re-pointed edge would resolve to the wrong instance; pick a different --purpose or --name`),
4013
+ { code: "E_RELATIVE_AMBIGUOUS" }) : null;
4014
+ };
4015
+ const shadow = reverseShadow(instance);
4016
+ if (shadow && !suggesting) throw shadow;
4017
+ provisional ??= shadow ?? undefined;
3993
4018
  }
3994
4019
  }
3995
4020
  }
@@ -4070,47 +4095,54 @@ function* spawnBody(root, agent, o = {}) {
4070
4095
  }
4071
4096
  }
4072
4097
 
4073
- const home = join(agent._dir, "instances", instance);
4074
- // A home that exists already is the same refusal as losing the exclusive mkdir below (a
4075
- // concurrent apply that got there first, or anything else): E_PLACEMENT_TAKEN, nothing created.
4076
- if (existsSync(home)) throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} already exists at ${home}; nothing was created by this call`), { instance, home });
4077
- // AUTHORITATIVE placement check, on the DESTINATION rather than on lexical
4078
- // paths, immediately before the first side effect. The earlier root/agent-dir
4079
- // checks are lexical and can be walked around by a symlink anywhere along the
4080
- // way — `agents/alias -> <linked-worktree>/agents/dev`, or a pre-existing
4081
- // `agent._dir/instances` symlink — which classifies as the primary checkout
4082
- // while the home is really created in the worktree (reviewer-249aa7b).
4083
- // Resolving through the nearest existing ancestor is what closes that.
4084
- const homeReal = realPathOrNearest(home);
4085
- const homeCanonical = canonicalDeploymentPath(homeReal);
4086
- if (resolve(homeCanonical) !== resolve(homeReal)) {
4087
- throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, inside a linked Git worktree — homes must be created in the primary checkout (${homeCanonical}); a symlink on the path to the agent directory or its instances/ dir does not change where the home really lands`);
4088
- }
4089
- // CONTAINMENT, which the check above does not give. canonicalDeploymentPath
4090
- // only redirects paths inside a LINKED WORKTREE; an escape to a directory Git
4091
- // does not own at all comes back unchanged and passed (reviewer-aggregate2 —
4092
- // reproduced: a pre-existing `instances/` symlink to a sibling temp dir spawned
4093
- // successfully, reporting a home under the deployment while the real one, with
4094
- // the capability credentials a hook writes into it, was created outside).
4095
- // The home must BE the immediate `instances/` child of the resolved agent
4096
- // directory, and that directory must live in this deployment.
4097
- const withinDir = (child, parent) => {
4098
- const rel = relative(parent, child);
4099
- return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
4098
+ // The home and its placement checks, for a name: the numbered one here, a suggested one again below.
4099
+ const place = (name) => {
4100
+ const home = join(agent._dir, "instances", name);
4101
+ // A home that exists already is the same refusal as losing the exclusive mkdir below (a
4102
+ // concurrent apply that got there first, or anything else): E_PLACEMENT_TAKEN, nothing created.
4103
+ if (existsSync(home)) throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${name} already exists at ${home}; nothing was created by this call`), { instance: name, home });
4104
+ // AUTHORITATIVE placement check, on the DESTINATION rather than on lexical
4105
+ // paths, immediately before the first side effect. The earlier root/agent-dir
4106
+ // checks are lexical and can be walked around by a symlink anywhere along the
4107
+ // way — `agents/alias -> <linked-worktree>/agents/dev`, or a pre-existing
4108
+ // `agent._dir/instances` symlink — which classifies as the primary checkout
4109
+ // while the home is really created in the worktree (reviewer-249aa7b).
4110
+ // Resolving through the nearest existing ancestor is what closes that.
4111
+ const homeReal = realPathOrNearest(home);
4112
+ const homeCanonical = canonicalDeploymentPath(homeReal);
4113
+ if (resolve(homeCanonical) !== resolve(homeReal)) {
4114
+ throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, inside a linked Git worktree — homes must be created in the primary checkout (${homeCanonical}); a symlink on the path to the agent directory or its instances/ dir does not change where the home really lands`);
4115
+ }
4116
+ // CONTAINMENT, which the check above does not give. canonicalDeploymentPath
4117
+ // only redirects paths inside a LINKED WORKTREE; an escape to a directory Git
4118
+ // does not own at all comes back unchanged and passed (reviewer-aggregate2 —
4119
+ // reproduced: a pre-existing `instances/` symlink to a sibling temp dir spawned
4120
+ // successfully, reporting a home under the deployment while the real one, with
4121
+ // the capability credentials a hook writes into it, was created outside).
4122
+ // The home must BE the immediate `instances/` child of the resolved agent
4123
+ // directory, and that directory must live in this deployment.
4124
+ const withinDir = (child, parent) => {
4125
+ const rel = relative(parent, child);
4126
+ return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
4127
+ };
4128
+ const agentDirReal = realPathOrNearest(agent._dir);
4129
+ // The only base is the agents root: souls and capability-defined agents alike
4130
+ // live directly under it (the 0.25 local-agents/ bases are gone). The root itself
4131
+ // may legitimately be a symlink (it is the deployment anchor, and OATS is pointed
4132
+ // AT it); the agent dirs OATS derives from it may not lead somewhere else.
4133
+ const allowedBases = [realPathOrNearest(root)];
4134
+ if (!allowedBases.some((b) => withinDir(agentDirReal, b))) {
4135
+ throw oatsError("E_NO_CANONICAL_ROOT", `agent directory for "${agent.name}" resolves to ${agentDirReal}, which is outside this deployment (${allowedBases.join(", ")}) — a symlinked agent directory would place the home, and any capability credentials written into it, outside the deployment entirely`);
4136
+ }
4137
+ const expectedHome = join(agentDirReal, "instances", name);
4138
+ if (resolve(homeReal) !== resolve(expectedHome)) {
4139
+ throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, not to ${expectedHome} — a symlinked instances/ directory does not change where the home really lands, and OATS will not create an instance (or the capability credentials that go in it) outside the agent's own directory`);
4140
+ }
4141
+ return { home, homeReal, expectedHome };
4100
4142
  };
4101
- const agentDirReal = realPathOrNearest(agent._dir);
4102
- // The only base is the agents root: souls and capability-defined agents alike
4103
- // live directly under it (the 0.25 local-agents/ bases are gone). The root itself
4104
- // may legitimately be a symlink (it is the deployment anchor, and OATS is pointed
4105
- // AT it); the agent dirs OATS derives from it may not lead somewhere else.
4106
- const allowedBases = [realPathOrNearest(root)];
4107
- if (!allowedBases.some((b) => withinDir(agentDirReal, b))) {
4108
- throw oatsError("E_NO_CANONICAL_ROOT", `agent directory for "${agent.name}" resolves to ${agentDirReal}, which is outside this deployment (${allowedBases.join(", ")}) — a symlinked agent directory would place the home, and any capability credentials written into it, outside the deployment entirely`);
4109
- }
4110
- const expectedHome = join(agentDirReal, "instances", instance);
4111
- if (resolve(homeReal) !== resolve(expectedHome)) {
4112
- throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, not to ${expectedHome} — a symlinked instances/ directory does not change where the home really lands, and OATS will not create an instance (or the capability credentials that go in it) outside the agent's own directory`);
4113
- }
4143
+ let home, homeReal, expectedHome;
4144
+ try { ({ home, homeReal, expectedHome } = place(instance)); }
4145
+ catch (e) { if (!suggesting) throw e; provisional ??= e; home = join(agent._dir, "instances", instance); }
4114
4146
  // Compose and PREFLIGHT before the home exists. Composition is pure (it only
4115
4147
  // reads the soul, config chain and capability content), so resolving it here
4116
4148
  // lets every "declared but missing" failure happen with zero side effects to
@@ -4132,8 +4164,14 @@ function* spawnBody(root, agent, o = {}) {
4132
4164
  // Where this launch will run (launchEnvironment): what its configuration sets, else its pane's.
4133
4165
  // `expectedEnv` is the preflight's answer, over the pane this plan expects; the launch reads the
4134
4166
  // session it actually gets (below). A spawn that launches nothing has no pane to read.
4135
- const launchEnvOn = (pane, removed = []) => launchEnvironment({ configEnv: launchConfig?.env, configName: launchConfig?.name, removed, env: process.env, pane, cwd: home });
4136
- const expectedEnv = launchEnvOn(launch ? () => expectedPaneEnvironment(tmuxSessionPlan, session, undefined, home) : NO_LAUNCH);
4167
+ // The pane's working directory only resolves the relative entries of its PATH and its harness
4168
+ // configuration folders. While the name is open (a suggesting preview), a sibling of the homes that
4169
+ // no instance can be named stands in for the home: its `..` entries resolve as the home's do, and
4170
+ // nothing is inside either, so the executable and the probes are the ones the final home would get,
4171
+ // and the naming call runs that same executable.
4172
+ const paneCwd = suggesting ? join(agent._dir, "instances", ".oats-suggest-name") : home;
4173
+ const launchEnvOn = (pane, removed = []) => launchEnvironment({ configEnv: launchConfig?.env, configName: launchConfig?.name, removed, env: process.env, pane, cwd: paneCwd });
4174
+ const expectedEnv = launchEnvOn(launch ? () => expectedPaneEnvironment(tmuxSessionPlan, session, undefined, paneCwd) : NO_LAUNCH);
4137
4175
  // A launched harness is looked up where its pane will look it up (launchLookup): this is the
4138
4176
  // preflight against the expected PATH; the launch looks again on the session it gets. Without a
4139
4177
  // launch (or a known destination) the lookup is this process's PATH, as before.
@@ -4174,8 +4212,33 @@ function* spawnBody(root, agent, o = {}) {
4174
4212
  const note = unestablishedNote(expectedEnv, [...new Set(checks.flatMap(([, names]) => names))]);
4175
4213
  return note ? `${checks.map(([what]) => what).join(", ")}: ${note}` : null;
4176
4214
  };
4177
- if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
4178
4215
  const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
4216
+ // The naming call (#1421 §3): the probes have run, so it takes what is left of their budget (at most
4217
+ // its own 20 s). Its time counts in the preflight's elapsedMs, but the preflight's status stays its
4218
+ // checks': a call the budget ends is `naming.reason` "timeout", and the numbered preview it leaves is
4219
+ // as confirmable as a plain one.
4220
+ let suggested;
4221
+ if (suggesting) {
4222
+ const seam = Number(process.env.OATS_TEST_NAMING_TIMEOUT_MS), own = seam > 0 ? seam : NAMING_TIMEOUT_MS;
4223
+ const left = preflightStarted + preflightBudgetMs - Date.now(), souls = deploymentSoulNames(root, o.prepared), homes = deploymentInstanceHomes(root);
4224
+ let windows;
4225
+ const suggestion = yield () => suggestInstanceName({
4226
+ soulName: agent.name, harness, bin, instanceModel: model || null, task, timeoutMs: Math.min(own, left),
4227
+ env: () => launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {}, launch: expectedEnv, harness }),
4228
+ taken: (n) => homes.has(n) || souls.has(n) || (windows ??= oatsTmuxWindows(session)).includes(n),
4229
+ });
4230
+ naming = suggestion.naming;
4231
+ suggested = suggestion.name;
4232
+ }
4233
+ if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
4234
+ // A suggested name is placed as `--name` places it (its shadow, its home); otherwise the numbered name
4235
+ // keeps its own refusal.
4236
+ if (suggested) {
4237
+ instance = suggested;
4238
+ const shadow = reverseShadow(instance);
4239
+ if (shadow) throw shadow;
4240
+ ({ home, homeReal, expectedHome } = place(instance));
4241
+ } else if (provisional) throw provisional;
4179
4242
 
4180
4243
  if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
4181
4244
  // K6: everything a spawn decides is decided by here — and nothing has been
@@ -4226,10 +4289,15 @@ function* spawnBody(root, agent, o = {}) {
4226
4289
  if (o.preview === true) {
4227
4290
  const decision = buildDecision();
4228
4291
  // Workspace model (M3): the preview reports what APPLY will produce — every
4229
- // module as a capability (name + origin) and every module skill by its
4230
- // directory basename with a `module:<cap>` source — not the classic chain's view.
4292
+ // module as a capability (name + origin) and every module skill with a
4293
+ // `module:<cap>` source — not the classic chain's view. The skill names are the
4294
+ // ones materialize copies, by its own precedence (lib/materialize.mjs
4295
+ // plannedModuleSkills: the resolution's rows, else the manifest's, else skills/*
4296
+ // read over the remote), so a root of skills (`skills: ["skills"]`) lists each skill
4297
+ // under it and a manifest with no `skills` its skills/ children, as
4298
+ // `inspect --soul --composed-skills` does.
4231
4299
  const preparedCapabilities = o.prepared.resolution.modules.map((m) => ({ name: m.name, origin: m.from.kind === "package" ? `package:${m.from.package}@${m.from.version}` : `member:${m.from.repoKey}@${m.from.commit}` }));
4232
- const preparedSkills = o.prepared.resolution.modules.flatMap((m) => (m.manifest?.skills || []).filter((s) => typeof s === "string" && s).map((s) => ({ name: basename(s.replace(/\/+$/, "")), source: `module:${m.name}` })));
4300
+ const preparedSkills = (yield () => (o.plannedSkills ?? plannedSkillsDefault)(o.prepared)).map((s) => ({ name: s.name, source: `module:${s.module}` }));
4233
4301
  // R5 (0.25.2, decision 14): the preview shows the provider payloads the apply
4234
4302
  // will record — `providers` is the --provider map exactly as parsed (what the
4235
4303
  // operator typed; prepareInstance keeps it on prepared.spawn.providers) and
@@ -4260,6 +4328,7 @@ function* spawnBody(root, agent, o = {}) {
4260
4328
  relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
4261
4329
  policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities,
4262
4330
  skills: [...expectedResources.filter((r) => r.type === "skill-tree" && !r.deferred).flatMap((r) => r.entries || []), ...preparedSkills], task: task || null,
4331
+ ...(naming ? { naming } : {}),
4263
4332
  });
4264
4333
  }
4265
4334
  if (o.expectDecision !== undefined) {
@@ -5343,7 +5412,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5343
5412
  // `retire` is only ever the value read above: a record that carries one (hand-edited, or
5344
5413
  // copied from a row) never stands in for it.
5345
5414
  const { retire: _recordedRetire, ...recorded } = meta;
5346
- return { ...recorded, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
5415
+ // Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
5416
+ // null, after the record so that nothing in instance.json stands in for it.
5417
+ return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
5347
5418
 
5348
5419
  });
5349
5420
  };
@@ -5892,7 +5963,8 @@ function retireGitProbe(repo, args, { encoding } = {}) {
5892
5963
  * MUST be added in the same change to the names a capability may not declare
5893
5964
  * as its own (`retirement.disposable.home`: KERNEL_HOME_NAMES and
5894
5965
  * KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
5895
- const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json"]);
5966
+ // `.oats-color.json` (feature instance-color) is presentation anyone may change at any time: never work.
5967
+ const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json"]);
5896
5968
  const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
5897
5969
  /** Harness project settings in the home are configuration, not work: the
5898
5970
  * home's `.claude/` is harness layout the kernel already shapes (the skills
@@ -9838,7 +9910,7 @@ const claimCommand = (action) => action === "stop" ? "oats instance stop" : `oat
9838
9910
  /** What each verb that meets a held claim says it did not do: the words its refusals end with,
9839
9911
  * before any effect. After a takeover ended a dead holder's step, every verb says the same
9840
9912
  * (lib/errors.mjs nothingAfter). */
9841
- const CLAIM_NOTHING = { retire: "nothing was done", stop: "nothing was stopped", "worktree add": "no tree was made" };
9913
+ const CLAIM_NOTHING = { retire: "nothing was done", stop: "nothing was stopped", "worktree add": "no tree was made", "instance color": "the colour was not changed" };
9842
9914
 
9843
9915
  /** The refusals of `arriving` ("retire", "stop", or "worktree add", which reads the claim and does
9844
9916
  * not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
@@ -0,0 +1,58 @@
1
+ /** An instance's colour (feature instance-color, awebai/oats#1421 §2): presentation, never identity
2
+ * or an address. Anyone may set it at any time; it is a home file of its own, `<home>/.oats-color.json`,
3
+ * so that a start or restart, which rewrites instance.json, can never lose it.
4
+ *
5
+ * The record is `{ colorApi: 1, color, at }`, written atomically (writeThroughPrivateFile) at mode
6
+ * 0600; clearing removes the file. A reader takes a regular file only, without following a link, up
7
+ * to RECORD_MAX bytes: anything that is not a valid record reads as no colour (null), never an
8
+ * error. Dependency-free: the status rows, inspect and the command all read it through here. */
9
+ import { lstatSync, rmSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { readFileHead } from "./bounded-read.mjs";
12
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
13
+
14
+ /** The closed palette, the clients' own (packages/client/soul-colors.mjs SOUL_COLORS): the kernel
15
+ * imports nothing from packages/, so it keeps this copy, which test/instance-color.test.mjs pins equal. */
16
+ export const INSTANCE_COLORS = Object.freeze(["sand", "sage", "slate", "mauve", "clay", "olive"]);
17
+ /** The record's own version, and the command answer's. */
18
+ export const COLOR_API = 1;
19
+ export const INSTANCE_COLOR_API = 1;
20
+ /** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
21
+ * fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
22
+ export const COLOR_FILE = ".oats-color.json";
23
+ /** A record larger than this is not one. */
24
+ export const RECORD_MAX = 4096;
25
+
26
+ /** A palette name exactly, else null: what a reader keeps of any value (a relayed row's included). */
27
+ export const paletteColor = (value) => (typeof value === "string" && INSTANCE_COLORS.includes(value) ? value : null);
28
+
29
+ /** The colour `home` records, or null: no file, not a regular file (a link is never followed), over
30
+ * RECORD_MAX bytes, unreadable, not JSON, another colorApi or a name outside the palette. Never throws. */
31
+ export function readInstanceColor(home) {
32
+ try {
33
+ const { bytes, size } = readFileHead(join(home, COLOR_FILE), RECORD_MAX + 1);
34
+ if (size > RECORD_MAX) return null;
35
+ const record = JSON.parse(bytes.toString("utf8"));
36
+ if (!record || typeof record !== "object" || Array.isArray(record) || record.colorApi !== COLOR_API) return null;
37
+ return paletteColor(record.color);
38
+ } catch { return null; }
39
+ }
40
+
41
+ /** Record `color` (a palette name) for `home`, or remove the record when `color` is null.
42
+ * → `{ color, changed }`. The colour the home already shows is no change: nothing is written. A clear
43
+ * removes whatever file stands at the name (an unreadable one included) and is a change only when a
44
+ * colour was shown. The caller validated `color` and holds the right to change the home. */
45
+ export function writeInstanceColor(home, color, { now = () => new Date() } = {}) {
46
+ const path = join(home, COLOR_FILE);
47
+ const before = readInstanceColor(home);
48
+ if (color === null) {
49
+ let present = false;
50
+ try { lstatSync(path); present = true; } catch (e) { if (e?.code !== "ENOENT") throw e; }
51
+ if (present) rmSync(path, { force: true });
52
+ return { color: null, changed: before !== null };
53
+ }
54
+ if (before === color) return { color, changed: false };
55
+ const bytes = JSON.stringify({ colorApi: COLOR_API, color, at: now().toISOString() }) + "\n";
56
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
57
+ return { color, changed: true };
58
+ }