@awebai/oats 0.66.0 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
@@ -89,6 +89,7 @@ see the [official catalog](official-catalog.md) for current pins.
89
89
  | `schedule-history`, `schedule-read-2` | run history with identity and provenance (gate on `schedule-read-2`) | `scheduleHistoryApi: 3` |
90
90
  | `workspace-v2` | `onboard`, `sync`, `package`, `workspace status`, `capabilities`, `souls` | `workspaceApi: 2` |
91
91
  | `instance-modules` | `instance.json` `modules`/`providers`/`workspace`; module drift in status; preview `modules[]` | |
92
+ | `instance-upgrade` | `oats instance upgrade` plan/apply/undo for stopped local homes; optional `upgrade` hook; `modules.<cap>.previous`; `modules-upgraded` event; start/restart package `drift` | |
92
93
  | `spawn-provider-payload` | `oats spawn … --provider <cap> <key>=<value>` | |
93
94
  | `served-identity` | `decision.effective.providers`; the served `identity` in inspect and status | |
94
95
  | `packages-no-approval` | no package approval anywhere | |
@@ -119,6 +120,8 @@ see the [official catalog](official-catalog.md) for current pins.
119
120
  | `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
121
  | `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
122
  | `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)) | |
123
+ | `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)) | |
124
+ | `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
125
  | `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
126
  | `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
127
  | `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,8 +138,11 @@ see the [official catalog](official-catalog.md) for current pins.
135
138
  | `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
139
  | `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
140
  | `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`) | |
141
+ | `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
142
  | `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
143
  | `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 | |
144
+ | `instance-suggest-name` | `oats instance suggest-name --soul <soul> (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn of `<soul>` would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
145
+ | `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
140
146
 
141
147
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
142
148
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -437,7 +443,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
437
443
  ### `oats inspect`
438
444
 
439
445
  ```text
440
- oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
446
+ oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
441
447
  ```
442
448
 
443
449
  An instance subject, abridged:
@@ -463,7 +469,7 @@ An instance subject, abridged:
463
469
  "recordedDefaultTeam":{"label":"eng","team":null,"from":"soul"},
464
470
  "knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"status","kind":"view","available":true,"reason":null}]},
465
471
  "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",
472
+ "createdAt":"2026-09-28T10:08:01.281Z","color":null,"resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
467
473
  "instructions":{"file":"/w/agents/rm/instances/rm-1/AGENTS.md","text":"…","truncated":false,
468
474
  "sources":[{"source":"capability:oats.okf","file":"/w/agents/rm/instances/rm-1/.oats/modules/oats.okf/injects/okf.md"}]}},
469
475
  "identity":null,
@@ -479,7 +485,7 @@ An instance subject, abridged:
479
485
  | `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
480
486
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
481
487
  | `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 |
488
+ | `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
489
  | `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
490
  | `problems` | below |
485
491
  | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
@@ -588,6 +594,48 @@ probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
588
594
  and nothing is sent. Every text is untrusted repository content: render it as
589
595
  plain text or through a sanitising renderer.
590
596
 
597
+ `composedSkills` (feature `soul-composed-skills`) is present only with
598
+ `--composed-skills`, which takes a soul subject (`--home` is `E_BAD_ARGS`) and
599
+ combines with `--instructions` and `--skills`; without the flag the key is
600
+ absent and nothing extra is composed. It lists every skill an instance of this
601
+ soul gets: the soul's own and each capability's.
602
+
603
+ ```json
604
+ "composedSkills":[{"name":"oats-operate","source":"module:oats.core","path":".oats/modules/oats.core/skills/oats-operate",
605
+ "description":"…","files":[{"path":".oats/modules/oats.core/skills/oats-operate/SKILL.md","bytes":1234,"text":"…","binary":false,"truncated":false}],
606
+ "filesTruncated":false},
607
+ {"name":"release-checklist","source":"soul","path":"skills/release-checklist","description":"Cutting a release.",
608
+ "files":[…],"filesTruncated":false}]
609
+ ```
610
+
611
+ - One row per skill, sorted by `name` in codepoint order. `source` is
612
+ `"soul"` or `"module:<capability id>"`, the vocabulary of `instance.json`
613
+ `skills` and of the spawn preview.
614
+ - `path` is POSIX. A soul skill's is relative to the soul directory, as in
615
+ `skills`; a capability skill's is relative to the instance home, where the
616
+ instance carries the capability's copy (`.oats/modules/<id>/…`). Each
617
+ file's `path` starts with its skill's.
618
+ - The rest of a row, and every rule for its files, is `skills`' above, with
619
+ one difference: the whole field carries at most 2 MiB (2,097,152 bytes) of
620
+ `text`, summed over every file in answer order, whichever source it comes
621
+ from. Problems name `composedSkills: ` instead of `skills: `.
622
+ - It is computed by the same scratch materialization as `--instructions`
623
+ (one serves both when both are given): the soul's skills by the
624
+ enumerator spawn uses, read from the soul copy, and the capability skills
625
+ materialize placed, read from the scratch copy before it is removed. It
626
+ runs no hooks and writes nothing in the deployment.
627
+ - It is `null` when a spawn would refuse a collision between a soul skill and
628
+ a capability skill (names compare case-insensitively), with the problem
629
+ `{code: "E_SKILL_DUPLICATE", message: "composedSkills: skill \"<name>\"
630
+ from soul collides with module <id>'s skill"}`, the sentence spawn refuses
631
+ with. It is `null` when the soul resolves but cannot be composed here, with
632
+ the composition's code and sentence, naming `composedSkills`. It is `null`
633
+ with `soul-skills-unreadable` when the soul's own skills cannot be listed.
634
+
635
+ Routed with `--server <id>`, `--composed-skills` travels to the host; a host
636
+ whose probe does not advertise `soul-composed-skills` is refused with
637
+ `E_REMOTE_INCOMPATIBLE`, and nothing is sent.
638
+
591
639
  **Layers.** `id` is the capability filling the slot or `null`. `from`
592
640
  (feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
593
641
  or a home spawned before it was recorded.
@@ -2430,7 +2478,13 @@ it to a temporary copy (`soulFetched: true`).
2430
2478
  - `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
2431
2479
  `member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
2432
2480
  strings, module skills as `{name, source: "module:<cap>"}`) are display
2433
- only: bind to `modules[]` and `decision`.
2481
+ only: bind to `modules[]` and `decision`. A module skill's `name` is a
2482
+ skill the spawn copies, by the rule it copies by: a manifest entry that
2483
+ holds skill directories lists each of them, and a manifest with no
2484
+ `skills` lists each `skills/<dir>/` holding a `SKILL.md`, read at the
2485
+ module's commit (feature `soul-composed-skills`; earlier kernels named such
2486
+ an entry by its own directory, `skills`, and listed nothing for a manifest
2487
+ with no `skills`).
2434
2488
  - `resolution` (24 hex) hashes `declRevision` (the declarations) and
2435
2489
  `payloadRevision` (the merged payloads). `workspace` is the host key;
2436
2490
  `standalone` marks a standalone view. `task` is the task text or `null`.
@@ -2450,6 +2504,137 @@ it to a temporary copy (`soulFetched: true`).
2450
2504
  new head and revision. An apply with `--expect-decision` may reuse heads
2451
2505
  too (feature `spawn-apply-max-age`, [Apply](#apply)).
2452
2506
 
2507
+ #### The suggested name (feature `spawn-suggest-name`)
2508
+
2509
+ ```text
2510
+ oats spawn <soul> --preview --suggest-name --task-file <f> [the flags of a real spawn] [--json]
2511
+ ```
2512
+
2513
+ A preview that also chooses the instance's name, from the task (`--task-file`,
2514
+ or `--task <text>`). Like every preview it writes nothing and runs no hooks.
2515
+ - `--suggest-name` with `--name`, `--purpose` or `--expect-decision` is
2516
+ `E_BAD_ARGS`. Without `--preview` it names an apply
2517
+ ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
2518
+ - **The call.** The kernel makes one non-interactive call through the
2519
+ harness, executable and environment the spawn would launch (the launch
2520
+ configuration's `env`, not its `args`), with this prompt on stdin, never in
2521
+ argv:
2522
+
2523
+ > Name an agent for this task: 2–4 lowercase words joined by hyphens, describing the work, not the role. Reply with the name only.
2524
+ >
2525
+ > Task:
2526
+ > <the task text, at most 4000 characters>
2527
+
2528
+ It runs from a fresh empty temporary directory, removed afterwards, with no
2529
+ `OATS_INSTANCE*` variable, without a shell, in its own process group. It is
2530
+ made after the preview's harness checks (the executable's lookup and the
2531
+ harness package probes, from where the home will be) and before anything
2532
+ that depends on the name (placement, branch, home). It takes what those
2533
+ checks leave of the preview's one 20 s preflight budget, which is not
2534
+ raised for it: the group is killed after 20 s, or when the budget runs out
2535
+ first. Its time counts in `preflight.elapsedMs`; `preflight.status` stays
2536
+ that of the checks, so a numbered preview after a `timeout` is confirmed
2537
+ like any other. At most 4 KiB of its output is read.
2538
+ - **It starts none of the user's code: no MCP server, hook, plugin,
2539
+ extension or project setting, and no tool on either harness.** Three
2540
+ exceptions are stated:
2541
+ - Claude Code's own built-in plugins (`cc-plugin-*@builtin`) load as
2542
+ they always do, `--bare` included.
2543
+ - Hooks in the host's managed policy (`managed-settings.json`) still
2544
+ apply: they are the host admin's.
2545
+ - pi runs its own credential commands (`!command` keys and headers in
2546
+ models.json), as every pi launch does: they are its login.
2547
+
2548
+ A claude login through `apiKeyHelper` is not read (`--setting-sources
2549
+ ""`): such a user gets `harness-failed` and a numbered name.
2550
+
2551
+ Each harness's argv is proven to start nothing else
2552
+ (`scripts/naming-isolation-proof.mjs`, a recorded run against fixtures,
2553
+ rerun by an operator after a harness upgrade). The proof covers claude
2554
+ 2.1.288 and pi 1.3.0, on Linux; macOS is not proven.
2555
+ - **claude**, model `haiku`: `-p --tools "" --strict-mcp-config
2556
+ --setting-sources "" --disable-slash-commands --no-session-persistence
2557
+ --output-format text --model haiku`. Its native login is kept, which
2558
+ `--bare` would not keep.
2559
+ - **pi**, the instance's model: `-p --no-session --no-tools
2560
+ --no-extensions --no-mcp --no-skills --no-prompt-templates --no-themes
2561
+ --no-context-files --no-approve [--model <m>]`.
2562
+ - **codex** is not supported. Its naming call is not proven to start
2563
+ nothing, so a codex soul is numbered with `unsupported-harness`.
2564
+ - **The name.**
2565
+ 1. The reply's first non-empty line, as a slug.
2566
+ 2. Without one or more trailing `-<role>`. The role is the last word of the
2567
+ soul's name, after any package qualifier.
2568
+ 3. At most 4 words, cut at a word boundary to fit
2569
+ `64 − 1 − len(role)`.
2570
+ 4. Nothing left, or only the role, is `invalid-reply`.
2571
+ 5. The name is `<descriptive>-<role>`. A name that is taken (an instance,
2572
+ a soul or a live window, as for `--name`) gets `-2`, `-3`, and so on.
2573
+ - **The answer** is the full preview, plus `naming`:
2574
+
2575
+ ```json
2576
+ "naming": { "source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku" }
2577
+ ```
2578
+
2579
+ ```json
2580
+ "naming": { "source": "numbered", "reason": "timeout", "message": "claude gave no name within 20 s", "ms": 20000 }
2581
+ ```
2582
+
2583
+ - With `source: "suggested"`, `instance`, `home`, `branch` and `decision`
2584
+ are those of a preview with `--name <instance>`: an apply with `--name
2585
+ <instance> --expect-decision <revision>` matches it.
2586
+ - With `source: "numbered"`, they are today's numbered name, and the apply
2587
+ goes without `--name`.
2588
+ - `reason` is one of a closed set:
2589
+ - `no-task`: no task, or a blank one; no call is made.
2590
+ - `unsupported-harness`: no call is made.
2591
+ - `timeout`.
2592
+ - `harness-failed`: a nonzero exit, a signal, or no executable. `message`
2593
+ gives the exit or the signal, never the output.
2594
+ - `invalid-reply`.
2595
+ - `model` is `null` when the harness runs its own default.
2596
+ - A failure is never an error: the preview answers.
2597
+ - The text preview prints `name: suggested by claude (haiku) in 2310 ms` or
2598
+ `name: numbered (<reason>: <message>)`.
2599
+ - **`--server`:** the call runs on the target machine, through the routed
2600
+ preview, and the task travels as a routed spawn's does. A host that does
2601
+ not advertise `spawn-suggest-name` is refused (`E_REMOTE_INCOMPATIBLE`)
2602
+ before the spawn is sent.
2603
+
2604
+ #### On an apply (feature `spawn-apply-suggest-name`)
2605
+
2606
+ ```text
2607
+ oats spawn <soul> --suggest-name --task-file <f> [the flags of a real spawn] [--json]
2608
+ ```
2609
+
2610
+ An apply with `--suggest-name` and no `--name`, `--purpose` or
2611
+ `--expect-decision` names the instance on the machine that spawns, by the
2612
+ preview's call and rules above, through the soul's harness.
2613
+ - The name is `<descriptive>-<role>`, made unique as a preview's is, and it is
2614
+ placed exactly as `--name <name>` would be.
2615
+ - On any failure the instance is numbered as it is today, and `naming` says
2616
+ why. A failed call is never an error: the spawn goes on.
2617
+ - The call is made before anything is placed, after the executable is
2618
+ resolved and the harness packages probed. An apply has no preflight
2619
+ budget: the call has its own 20 s. Every later bound of the apply (the
2620
+ hooks, the launch) starts after it, so the apply can take up to 20 s longer
2621
+ than without the flag. A caller with its own deadline on the apply allows
2622
+ for that.
2623
+ - The result carries `naming`, in the preview's shape and with its closed
2624
+ `reason` set, whenever `--suggest-name` was given
2625
+ ([Apply](#apply), its result). The text answer prints a
2626
+ `name: suggested by …` or `name: numbered (…)` line.
2627
+ - **A race.** Another soul's spawn that takes the name between the naming
2628
+ and the placement makes this apply `E_INSTANCE_NAME_TAKEN`, as for `--name`
2629
+ (nothing was created by this call; spawn again for another name). The same
2630
+ soul's is `E_PLACEMENT_TAKEN`, as for any name.
2631
+ - Without `--suggest-name`, an apply is unchanged: numbered, with no call.
2632
+ - **`--server`:** the call runs on the host, through the routed apply. A host
2633
+ that does not advertise `spawn-apply-suggest-name` is refused
2634
+ (`E_REMOTE_INCOMPATIBLE`) before the spawn is sent; the route never drops
2635
+ the flag. A caller that would rather have the host number the instance
2636
+ checks the host's `probe.features` and does not send the flag.
2637
+
2453
2638
  **Provider settings.**
2454
2639
  - `providers` is the `--provider` map as typed.
2455
2640
  - `settings.<cap>`: the merged payload (manifest defaults, then workspace,
@@ -2489,7 +2674,8 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
2489
2674
  - The home is reserved with a non-recursive `mkdir`. A concurrent loser
2490
2675
  refuses `E_PLACEMENT_TAKEN {instance, home}` having touched nothing. Names
2491
2676
  are deployment-wide: a same-name race with another soul ends in
2492
- `E_INSTANCE_NAME_TAKEN` (for `--name`) or `E_PLACEMENT_TAKEN`.
2677
+ `E_INSTANCE_NAME_TAKEN` (for `--name` and a suggested name) or
2678
+ `E_PLACEMENT_TAKEN`.
2493
2679
  - A refused child spawn appends `child-spawn-refused` to the parent's log (on
2494
2680
  apply only).
2495
2681
  - `--max-age <s>` with `--expect-decision <revision>` (feature
@@ -2566,7 +2752,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
2566
2752
  `wakeScheduleError` (a requested wake), `worktreeHooks` (feature
2567
2753
  `worktree-event`: only when the spawn ran `worktree` hooks, the receipt
2568
2754
  `[{capability, ok, required, log, exitCode, signal?, timedOut?,
2569
- contract?}]`, `log` being the hook's log file).
2755
+ contract?}]`, `log` being the hook's log file), `naming` (feature
2756
+ `spawn-apply-suggest-name`: only with `--suggest-name`, `{source, reason?,
2757
+ message?, ms, harness?, model?}` as on the preview).
2570
2758
  - A spawn that runs `worktree` hooks can take up to 30 minutes per hook
2571
2759
  ([the worktree event](capabilities.md#the-worktree-event)).
2572
2760
 
@@ -2583,6 +2771,90 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2583
2771
  `E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
2584
2772
  a silent `-2`.
2585
2773
  - The name is part of the decision.
2774
+ - Routed (`--server`), `--name` needs a host that advertises `spawn-name`:
2775
+ `E_REMOTE_INCOMPATIBLE` otherwise, with nothing sent. A saved route here
2776
+ under that name is `E_ROUTE_EXISTS`, before the spawn is sent.
2777
+ - `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
2778
+ descriptive name for the task, `<descriptive>-<role>`, which the apply then
2779
+ passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
2780
+ An apply with `--suggest-name` (feature `spawn-apply-suggest-name`) chooses
2781
+ it itself ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
2782
+ - `oats instance suggest-name` (feature `instance-suggest-name`) chooses one on
2783
+ this machine for a spawn on another
2784
+ ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
2785
+
2786
+ ### A name for a spawn elsewhere (`oats instance suggest-name`)
2787
+
2788
+ Feature `instance-suggest-name`.
2789
+
2790
+ ```text
2791
+ oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] --json
2792
+ ```
2793
+
2794
+ The name a spawn of `<soul>` would get by `--suggest-name`, chosen on the
2795
+ machine that asks (a Desktop's, with the spawn dialog open) for a spawn that
2796
+ may land on another.
2797
+
2798
+ - **What it touches.** It resolves no workspace, writes nothing, records
2799
+ nothing and reserves no name. It reads only this machine's launch
2800
+ configurations (the `oats-local.yaml` in reach of `--dir`, else the working
2801
+ directory) and the OATS tmux server's environment, as a spawn's pane would
2802
+ have it; it resolves no souls, members, lock or remote. The deployment it
2803
+ reads is not added to this computer's deployments list.
2804
+ - **The soul is only a name.** It gives the role (the last word of the name,
2805
+ after any package qualifier) and needn't exist on this machine. It is
2806
+ checked as a soul name's shape (`<soul>`, `<package>/<soul>`,
2807
+ `<package>--<soul>`), never resolved.
2808
+ - **Not made unique.** The words, role and length rules are the preview's
2809
+ ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)), but no
2810
+ `-2` is added: the machine the spawn lands on owns uniqueness, and a name
2811
+ taken there is its `E_INSTANCE_NAME_TAKEN` at the apply.
2812
+ - **The harness and model.** The harness is `--harness`, else the
2813
+ configuration's, else claude. Its executable and environment are what a
2814
+ spawn on this machine would launch it with: `--launch-config` if given
2815
+ (`none` for the bare harness), else this machine's default configuration
2816
+ for that harness, else the harness's own executable. The model is
2817
+ `--model`, else the configuration's: `@native-default` is the harness's
2818
+ own, and a preference list names its first entry (no catalogue is
2819
+ probed: the naming call is the only process the command starts). It
2820
+ matters for pi; claude always names with `haiku`. The task text goes to this machine's harness and model, as the
2821
+ preview's naming does.
2822
+ - **The call** is the preview's, with the same prompt, argv and isolation,
2823
+ and its model call is bounded as the preview's is: at most 20 s and 4 KiB
2824
+ of output.
2825
+ - **The answer** is the usual envelope, `ok: true` whether the name was
2826
+ suggested or numbered:
2827
+
2828
+ ```json
2829
+ {"schemaVersion": 1, "ok": true, "result": {"name": "fix-flaky-login-developer", "naming": {"source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku"}}}
2830
+ ```
2831
+
2832
+ ```json
2833
+ {"schemaVersion": 1, "ok": true, "result": {"naming": {"source": "numbered", "reason": "harness-failed", "message": "claude could not be run: claude is not installed on this machine (claude binary not found on PATH)", "ms": 0}}}
2834
+ ```
2835
+
2836
+ - `name` is present only when `naming.source` is `"suggested"`.
2837
+ - `naming` has the preview's shape, and `naming.reason` its closed set:
2838
+ `no-task` (`--task ""`, or a blank task file; no call is made),
2839
+ `unsupported-harness` (codex; no call is made), `timeout`,
2840
+ `harness-failed` (a nonzero exit, a signal, or no executable here: no
2841
+ such executable, or a configuration's `{fromEnv}` reference not set
2842
+ here; `message` names the cause, never a value), `invalid-reply`.
2843
+ - A naming failure is not an error: `ok: true` with
2844
+ `naming.source: "numbered"`.
2845
+ - The text answer is the name, or `numbered (<reason>: <message>)`.
2846
+ - **Refusals** (`E_BAD_ARGS` unless named): no `--soul`, or one that is not
2847
+ a soul name's shape; neither or both of `--task` and `--task-file`, or one
2848
+ that cannot be read; a `--harness` other than pi, claude or codex; a
2849
+ `--harness` that is not the named configuration's; a flag or argument it
2850
+ does not take; `--server`. An unknown `--launch-config` is
2851
+ `E_LAUNCH_CONFIG_UNKNOWN`.
2852
+ - **Never routed.** `oats instance` commands route through `--server`, but
2853
+ this one runs where it is asked: a name for another machine is decided
2854
+ here. `--server` is refused before anything is sent.
2855
+ - **When the feature is missing** (an older local kernel), a client spawns
2856
+ without a name: the host numbers the instance, or names it itself if it
2857
+ advertises `spawn-apply-suggest-name` and the client sends `--suggest-name`.
2586
2858
 
2587
2859
  ### Spawn origin
2588
2860
 
@@ -2832,9 +3104,9 @@ A failed `add` reports the same facts about its rollback in `details`:
2832
3104
  | `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
2833
3105
  | `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
2834
3106
  | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2835
- | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
3107
+ | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message), or an unregistered residue differs from the recorded branch (the message and `details.git` list the modified or nonignored untracked paths). The record is kept. Save the changes, or discard, then retry |
2836
3108
  | `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
2837
- | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
3109
+ | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, removal could not be verified, or an unregistered residue could not be checked against its recorded branch or deleted; the record is kept. A failure after Git started removal reports possible partial deletion and the retry, never that nothing was removed. A missing or invalid `.git` marker names the manual step: save any work, remove the directory by hand, then run `remove` again to drop the record. See [extra-tree removal recovery](souls-and-instances.md#extra-trees) |
2838
3110
  | `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
2839
3111
 
2840
3112
  A rollback that cannot finish keeps the record and says so in the message
@@ -2879,6 +3151,11 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
2879
3151
  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
2880
3152
  `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
2881
3153
  `<home>/.agents/skills/<cap>/<skill>/`).
3154
+ After a package upgrade, the moved row also carries
3155
+ `previous: {from, commit, digest, materializedAt, receipt}`: one level, for
3156
+ its latest move. Readers tolerate this additive field. The verified copy
3157
+ for undo lives at `<home>/.oats/previous/<receipt>/`; each move replaces the
3158
+ previous state, and retirement preserves it in recovery.
2882
3159
  - `branch`: for a worktree instance, the branch its worktree was created on.
2883
3160
  For an attached or checkout instance, the branch the tree's HEAD named at
2884
3161
  the spawn, or `null` when HEAD was detached or named a ref OATS carries no
@@ -3006,6 +3283,12 @@ its absence.
3006
3283
  An older kernel's `running` is the window's presence, and it checks a row
3007
3284
  with a claim against its session (as `oats session inspect` observes it),
3008
3285
  reading `null` unless a harness runs there.
3286
+ - **`color`** (feature `instance-color`): the instance's colour, one of
3287
+ `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
3288
+ from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
3289
+ a `color` in `instance.json` never stands in for it. Every row has it,
3290
+ an unreadable record's row included (`null`). Presentation only: it is not
3291
+ identity and never addresses anything.
3009
3292
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
3010
3293
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
3011
3294
  is running, scheduled or owed; absent otherwise, and from older kernels.
@@ -3166,7 +3449,7 @@ route target:
3166
3449
  "soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
3167
3450
  "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
3451
  "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
3169
- "retirePending":false,"rollbackIncomplete":false,
3452
+ "color":"sage","retirePending":false,"rollbackIncomplete":false,
3170
3453
  "savedRoute":false,"addressable":true,"missingRemotely":false}],
3171
3454
  "retireFailures":[]}
3172
3455
  ```
@@ -3461,6 +3744,7 @@ instance's own machine: the local command, with `--server <id>` added.
3461
3744
  | `oats instance git\|diff <name> --server <id> …` | `instance-git` | `instance-git`, `instanceGitApi: 1` |
3462
3745
  | `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
3463
3746
  | `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
3747
+ | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
3464
3748
 
3465
3749
  - The flags are the local command's. The instance is addressed like every
3466
3750
  routed instance command ([servers.md](servers.md#run-there)): `--home` as
@@ -3594,6 +3878,10 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
3594
3878
  bytes}`. Only a regular file is opened (no symlinks, same device and inode
3595
3879
  after open), and at most its last 4 MiB is read (`"tail"`).
3596
3880
  - **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
3881
+ `modules-upgraded` (`data: {receipt, modules:[{capability, from, to}]}`,
3882
+ written after the module swap and retirement baseline complete),
3883
+ `upgrade-refused` (a failure with no successful or uncertain apply-hook outcome,
3884
+ naming the failed step or module; older clients tolerate the unknown kind),
3597
3885
  `retire-planned`, `retired`, `retire-refused` (0.53.0,
3598
3886
  [below](#retire-refused-event)), `worktree-retained`, `worktree-removed`,
3599
3887
  `branch-deleted` (not written since 0.41.0: no retire deletes a branch;
@@ -3731,7 +4019,7 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
3731
4019
 
3732
4020
  ### Waiting on you
3733
4021
 
3734
- Feature `waiting-on-you` (OATS 0.40.0): an instance blocked on a human (a
4022
+ Feature `waiting-on-you` (OATS 0.40.0): an instance waiting on a human (a
3735
4023
  permission prompt, a question, an agent asking for an answer) says so through
3736
4024
  a producer's claim. **Claims are display-only:** nothing in the kernel acts
3737
4025
  on `waitingOnYou`. In particular `oats session input` behaves exactly as
@@ -3826,6 +4114,84 @@ oats instance attention [--message <text>] [--clear] --json
3826
4114
  readable `instance.json`), `E_HOME_MISMATCH`, `E_EVENTS_FAILED` (the write
3827
4115
  failed; nothing else is affected).
3828
4116
 
4117
+ ## Upgrading an instance's package modules
4118
+
4119
+ Requires the `instance-upgrade` feature in `oats version --json` or `oats status --json`.
4120
+
4121
+ ```text
4122
+ oats instance upgrade <instance> --plan [--json]
4123
+ oats instance upgrade <instance> --plan-revision <revision> --idempotency-key <key> [--json]
4124
+ oats instance upgrade <instance> --undo --plan [--json]
4125
+ oats instance upgrade <instance> --undo --plan-revision <revision> --idempotency-key <key> [--json]
4126
+ ```
4127
+
4128
+ This local act resolves an instance like `oats retire`, from its deployment
4129
+ or a parent's home. It uses the lifecycle claim and requires a stopped,
4130
+ readable session. A running or unreadable session is `E_SESSION_RUNNING`,
4131
+ naming `oats instance stop <instance>`, upgrade, then session start. It does
4132
+ not support `--server` or several homes in one call.
4133
+
4134
+ A read-only plan stages package copies outside the home, verifies the locked
4135
+ commit and integrity as spawn does, then removes that staging. Its revision
4136
+ hashes the facts. Each moving module reports `{capability,
4137
+ from:{version,commit,digest}, to:{version,commit,integrity},
4138
+ skills:{added,removed,changed}, inject, hooks, provider:{decision,reason}}`.
4139
+ `inject` and `hooks` indicate changes. The plan also lists kept modules and
4140
+ member drift and `homeChangedSinceSpawn` (both excluded from `planRevision`).
4141
+ A package no longer in the lock is kept. Member modules and
4142
+ the soul body never move. A provider refusal refuses the whole act.
4143
+
4144
+ Apply rechecks the revision under the lifecycle claim (`E_PLAN_STALE` with
4145
+ a fresh plan on mismatch) and records an idempotency receipt. It stages the
4146
+ whole modules, skills, inject and hook composition through spawn's composer,
4147
+ using the soul at its recorded commit. It saves and verifies the previous
4148
+ state before provider hooks run, swaps the composition, updates only a clean
4149
+ home's retirement `homeFingerprint`, commits the receipt, then appends
4150
+ `modules-upgraded`. A dirty home keeps its baseline file byte-identical, so
4151
+ older kernels also preserve its pre-upgrade edits at retirement. Work-tree
4152
+ fingerprints and digest versions always remain as recorded. The moved module record's `previous`
4153
+ is described under [`instance.json`](#instancejson).
4154
+ Upgrade runs no launch hooks. When a moved module's new manifest has no launch
4155
+ hook, apply removes its recorded launch/environment contribution in the same
4156
+ journaled metadata swap. When it still declares a launch hook, the existing
4157
+ contribution stays with settings and trust refreshed, until the next start
4158
+ replaces it wholesale. Undo restores the recorded contribution from the
4159
+ backed-up `instance.json`. There is no pending dropped-hook state to resolve
4160
+ at start, so consecutive upgrades need no intervening start.
4161
+ Receipts live at `<home>/.oats/upgrade-receipt.<key>.json`. Retirement's baseline
4162
+ excludes only that exact receipt filename pattern and `.oats/.staging-upgrade-*`;
4163
+ `.oats/previous/` is ordinary home content covered by the baseline.
4164
+
4165
+ Before the commit boundary, failure restores composed home bytes and removes
4166
+ staging and the saved previous state only when no provider hook succeeded or
4167
+ has an uncertain outcome. A non-zero hook result must be explicitly observed
4168
+ and recorded in the same invocation to permit this rollback. A hook reporting
4169
+ failure must leave no effects of its own; provider host effects are its
4170
+ responsibility.
4171
+
4172
+ Before spawning a hook, the receipt records `step: "hook <capability>"` and
4173
+ `hooks.inFlight: <capability>`. Resuming an unknown in-flight outcome durably
4174
+ records `uncertain: [<capability>]` before retry work. Even a kill before spawn
4175
+ counts as uncertain if not-started cannot be proved. After any success or
4176
+ uncertainty, failure records `partial`: the error names pending work and asks
4177
+ for the same `--idempotency-key` to finish forward. Retry re-runs pending
4178
+ idempotent hooks, including an uncertain one. A subsequent hook failure stays
4179
+ partial; it cannot authorize rollback. Start refuses with `E_UPGRADE_PARTIAL`
4180
+ while the receipt is partial. If completion is impossible, the remedy is respawn.
4181
+
4182
+ The commit boundary is after swap and baseline: the receipt becomes
4183
+ `status: "complete"` with `steps.cleaned: false` before the success event and staging cleanup.
4184
+ Successful cleanup sets `steps.cleaned: true`. A failure after that boundary
4185
+ leaves the upgrade committed. The same-key retry finishes event publication
4186
+ and cleanup, without
4187
+ hooks or copies. Start is allowed with one warning naming that retry; a new
4188
+ upgrade or undo plan refuses until cleanup finishes. `E_UPGRADE_PARTIAL`
4189
+ applies only before commit. Retirement adds no special cleanup behavior.
4190
+
4191
+ `--undo` uses the latest verified previous state and the restored version's
4192
+ `upgrade` hook, under the same adoption and failure protocol. A version
4193
+ without that hook cannot be restored through this act; respawn instead.
4194
+
3829
4195
  ## Lifecycle: stop and retire
3830
4196
 
3831
4197
  Feature `lifecycle-plans` (and `retire-retention`), `lifecycleApi: 1`. A
@@ -4202,6 +4568,7 @@ in flight.
4202
4568
 
4203
4569
  Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
4204
4570
  hold the home's claim for their whole run, and `oats worktree add` reads it.
4571
+ This table covers those three commands; the upgrade pairs follow separately.
4205
4572
  Each cell is the answer of the command that **arrives**. It is given at once
4206
4573
  and before any effect: that command stopped, ran, copied, made and removed
4207
4574
  nothing, and the command already on the home is not disturbed.
@@ -4216,6 +4583,25 @@ nothing, and the command already on the home is not disturbed.
4216
4583
  | the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
4217
4584
  | the holder of the claim is gone | not refused | not refused | not refused | not refused |
4218
4585
 
4586
+ <a id="upgrade-lifecycle-pairs"></a>
4587
+ The `instance-upgrade` pairs use the same home's lifecycle claim:
4588
+
4589
+ | On the home | Arriving command | Answer |
4590
+ |---|---|---|
4591
+ | a retire is running | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
4592
+ | a self-retire is scheduled | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
4593
+ | a stop or upgrade apply is running | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
4594
+ | a holder's verb is unknown, its liveness cannot be read, or the claim is unreadable | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
4595
+ | the holder of the claim is gone | `oats instance upgrade` apply | not refused after claim takeover checks |
4596
+ | an upgrade apply is running | `oats retire` or `oats instance stop --apply` | `E_LIFECYCLE_BUSY` |
4597
+ | an upgrade apply is running | `oats worktree add` | not refused |
4598
+
4599
+ Upgrade requires a stopped session. Start and restart do not take or read the
4600
+ lifecycle claim: upgrade instead holds their existing `.oats-start.lock`
4601
+ mutex until its final invocation receipt is persisted. A start blocked by an
4602
+ upgrade mutex names the same-key retry. A partial receipt refuses starts through the remaining
4603
+ finalization. The following stop/retire notes describe the original table.
4604
+
4219
4605
  - **A holder is answered before a stale plan, by both verbs.** A guarded
4220
4606
  retire and a stop apply compare the revision they were sent only once
4221
4607
  they hold the claim, so beside a holder the answer is the cell above
@@ -4291,7 +4677,7 @@ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
4291
4677
  stop this may be a child of the instance asked for.**
4292
4678
  - `lock`: the file that names the holder. `pid` and `since`: the holder's
4293
4679
  pid and when it took the claim.
4294
- - **`action`: the holder's verb**, `"retire"` or `"stop"`. A claim written
4680
+ - **`action`: the holder's verb**, `"retire"`, `"stop"` or `"upgrade"`. A claim written
4295
4681
  by a kernel before this feature has no verb and reads as `"retire"`. A
4296
4682
  reader treats a value it does not know as busy.
4297
4683
  - <a id="claim-file-text"></a>**Text of a claim file is never part of an
@@ -5130,7 +5516,7 @@ line and says that nothing was done:
5130
5516
  second for a retire, which does not wait).
5131
5517
  `details` is `{instance, home, lock, holder: "unknown"}`; the message is
5132
5518
  `<lock> is not a readable claim; nothing was done — inspect it and remove
5133
- it if no oats retire or oats instance stop holds it, then retry`.
5519
+ it if no oats retire, oats instance stop or oats instance upgrade holds it, then retry`.
5134
5520
  - A claim whose holder is gone and that this kernel cannot take over is
5135
5521
  never removed either: its `nonce` is not the 32 hexadecimal digits a claim
5136
5522
  carries (a file written or damaged by hand); or it is the claim of a
@@ -5142,7 +5528,7 @@ line and says that nothing was done:
5142
5528
  The message is `the
5143
5529
  process that held <lock> (pid <pid>) is gone, and this file is not a claim
5144
5530
  this kernel can take over (<why>); nothing was done — inspect <lock> and
5145
- remove it if no oats retire or oats instance stop holds it, then retry` (0.52.0, #874; before,
5531
+ remove it if no oats retire, oats instance stop or oats instance upgrade holds it, then retry` (0.52.0, #874; before,
5146
5532
  the first was answered as a live holder, to wait for, and the second as
5147
5533
  `E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
5148
5534
  does not exist). Removing that one file lets the next retire take the
@@ -5379,6 +5765,60 @@ removal begins, and only with the home kept (`reached.home: "kept"`). A
5379
5765
  typed refusal keeps its code, its details and its own words; the inspections'
5380
5766
  and the recovery's refusals end with the sentence of their phase, once.
5381
5767
 
5768
+ ## An instance's colour (`oats instance color`)
5769
+
5770
+ Feature `instance-color` (awebai/oats#1421).
5771
+
5772
+ ```text
5773
+ oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]
5774
+ ```
5775
+
5776
+ The colour is presentation, not identity. Anyone may change it at any time,
5777
+ the agent on its own instance included, and it is never an address.
5778
+
5779
+ - **The palette** is closed: `sand`, `sage`, `slate`, `mauve`, `clay`,
5780
+ `olive`, the clients' own (`packages/client/soul-colors.mjs`).
5781
+ - **The record** is `<home>/.oats-color.json`, `{"colorApi": 1, "color":
5782
+ "sage", "at": "<ISO time>"}`, mode 0600, written atomically. `--clear`
5783
+ removes it. It is a kernel-owned home file: a capability cannot declare it
5784
+ as its own, and it is no change to the home at retire.
5785
+ - **A reader** takes a regular file only, without following a link, of at
5786
+ most 4 KiB. Anything that is not such a valid record reads as no colour
5787
+ (`null`), never as an error.
5788
+ - **The instance** is addressed as `oats instance stop` addresses it, and
5789
+ refused with the same answers: not found, ambiguous, a `--home` that is not
5790
+ its home, a record that cannot be read.
5791
+
5792
+ The answer:
5793
+
5794
+ ```json
5795
+ {"instanceColorApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","color":"sage","changed":true}
5796
+ ```
5797
+
5798
+ `color` is `null` after `--clear`. Setting the colour the instance already
5799
+ has answers `changed: false` and writes nothing; so does clearing an instance
5800
+ with no colour.
5801
+
5802
+ | Code | When |
5803
+ |---|---|
5804
+ | `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 |
5805
+ | *(as `oats instance stop`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
5806
+ | `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 |
5807
+ | `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` |
5808
+
5809
+ Routed with `--server <id>`, the command runs on the host
5810
+ ([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
5811
+ not advertise `instance-color` is refused with `E_REMOTE_INCOMPATIBLE`, and
5812
+ nothing is sent.
5813
+
5814
+ Where it is read: `color` on [status rows](#the-roster-oats-status---json),
5815
+ on [remote roster rows](#the-remote-roster-oats-server-roster---json) (only a
5816
+ palette name is relayed, anything else is `null`), and on `oats inspect
5817
+ --home` as `instance.color`. A client draws a row's colour by one rule,
5818
+ `instanceColor(row)` in `packages/client/instance-presentation.mjs`: the
5819
+ row's palette name, else none. Colour never says a state alone: a client's
5820
+ mark keeps the state by its shape.
5821
+
5382
5822
  ## Sessions and launch configurations
5383
5823
 
5384
5824
  ### Input
@@ -5427,6 +5867,16 @@ oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --
5427
5867
  Features `session-start`, `session-restart`, and `launch-config` for the
5428
5868
  selection flags. See [the start workflow](desktop-instance-start.md).
5429
5869
 
5870
+ Start and restart keep the home's recorded module copies. Their successful
5871
+ results with package drift include `drift:[{capability, recorded:{version,commit},
5872
+ locked:{version,commit}}]` for package modules behind the deployment lock,
5873
+ and omit the field when none are behind. Text prints one line after the start:
5874
+ `<n> package module(s) behind the lock (<cap> <version> @ <shortcommit> → <version> @ <shortcommit>); to move them: oats instance stop <instance>; oats instance upgrade <instance> --plan`.
5875
+ Restart has no upgrade flag. A partial upgrade receipt refuses a start with
5876
+ `E_UPGRADE_PARTIAL`, naming the retry with the original idempotency key.
5877
+ A committed receipt with `steps.cleaned: false` permits start and adds one
5878
+ warning naming the same-key cleanup retry.
5879
+
5430
5880
  - The result is `{instance, agent, home, harness, backend, model,
5431
5881
  launchConfig, yolo, target, startedAt, restartCount, reused, warnings}`,
5432
5882
  plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply,