@awebai/oats 0.65.0 → 0.67.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
@@ -119,6 +119,8 @@ see the [official catalog](official-catalog.md) for current pins.
119
119
  | `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
120
120
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
121
121
  | `soul-skills` | `oats inspect --soul <soul> --skills` and its `souls[].skills`: the soul's own skills, the ones a spawn of it copies, with each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
122
+ | `soul-composed-skills` | `oats inspect --soul <soul> --composed-skills` and its `souls[].composedSkills`: every skill a spawn of the soul gives its instance, its own and its capabilities', each with its `source` and each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)). The same kernels name each capability skill of `spawn --preview`'s `skills[]` as the spawn does ([The preview](#the-preview)) | |
123
+ | `spawn-suggest-name` | `oats spawn <soul> --preview --suggest-name`: the preview also chooses the name, from the task, through the soul's own harness, and says how in `naming` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)). Suggested names work on claude and pi; codex is numbered (`unsupported-harness`). Routed, the host needs the feature | |
122
124
  | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
123
125
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
124
126
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
@@ -135,6 +137,7 @@ see the [official catalog](official-catalog.md) for current pins.
135
137
  | `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
136
138
  | `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
137
139
  | `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
140
+ | `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
138
141
  | `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
139
142
  | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
140
143
 
@@ -437,7 +440,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
437
440
  ### `oats inspect`
438
441
 
439
442
  ```text
440
- oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
443
+ oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
441
444
  ```
442
445
 
443
446
  An instance subject, abridged:
@@ -463,7 +466,7 @@ An instance subject, abridged:
463
466
  "recordedDefaultTeam":{"label":"eng","team":null,"from":"soul"},
464
467
  "knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"status","kind":"view","available":true,"reason":null}]},
465
468
  "instance":{"home":"/w/agents/rm/instances/rm-1","instance":"rm-1","agent":"rm","harness":"pi","model":null,"yolo":null,"launched":false,
466
- "createdAt":"2026-09-28T10:08:01.281Z","resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
469
+ "createdAt":"2026-09-28T10:08:01.281Z","color":null,"resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
467
470
  "instructions":{"file":"/w/agents/rm/instances/rm-1/AGENTS.md","text":"…","truncated":false,
468
471
  "sources":[{"source":"capability:oats.okf","file":"/w/agents/rm/instances/rm-1/.oats/modules/oats.okf/injects/okf.md"}]}},
469
472
  "identity":null,
@@ -479,7 +482,7 @@ An instance subject, abridged:
479
482
  | `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
480
483
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
481
484
  | `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
482
- | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
485
+ | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)) |
483
486
  | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
484
487
  | `problems` | below |
485
488
  | `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
@@ -588,6 +591,48 @@ probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
588
591
  and nothing is sent. Every text is untrusted repository content: render it as
589
592
  plain text or through a sanitising renderer.
590
593
 
594
+ `composedSkills` (feature `soul-composed-skills`) is present only with
595
+ `--composed-skills`, which takes a soul subject (`--home` is `E_BAD_ARGS`) and
596
+ combines with `--instructions` and `--skills`; without the flag the key is
597
+ absent and nothing extra is composed. It lists every skill an instance of this
598
+ soul gets: the soul's own and each capability's.
599
+
600
+ ```json
601
+ "composedSkills":[{"name":"oats-operate","source":"module:oats.core","path":".oats/modules/oats.core/skills/oats-operate",
602
+ "description":"…","files":[{"path":".oats/modules/oats.core/skills/oats-operate/SKILL.md","bytes":1234,"text":"…","binary":false,"truncated":false}],
603
+ "filesTruncated":false},
604
+ {"name":"release-checklist","source":"soul","path":"skills/release-checklist","description":"Cutting a release.",
605
+ "files":[…],"filesTruncated":false}]
606
+ ```
607
+
608
+ - One row per skill, sorted by `name` in codepoint order. `source` is
609
+ `"soul"` or `"module:<capability id>"`, the vocabulary of `instance.json`
610
+ `skills` and of the spawn preview.
611
+ - `path` is POSIX. A soul skill's is relative to the soul directory, as in
612
+ `skills`; a capability skill's is relative to the instance home, where the
613
+ instance carries the capability's copy (`.oats/modules/<id>/…`). Each
614
+ file's `path` starts with its skill's.
615
+ - The rest of a row, and every rule for its files, is `skills`' above, with
616
+ one difference: the whole field carries at most 2 MiB (2,097,152 bytes) of
617
+ `text`, summed over every file in answer order, whichever source it comes
618
+ from. Problems name `composedSkills: ` instead of `skills: `.
619
+ - It is computed by the same scratch materialization as `--instructions`
620
+ (one serves both when both are given): the soul's skills by the
621
+ enumerator spawn uses, read from the soul copy, and the capability skills
622
+ materialize placed, read from the scratch copy before it is removed. It
623
+ runs no hooks and writes nothing in the deployment.
624
+ - It is `null` when a spawn would refuse a collision between a soul skill and
625
+ a capability skill (names compare case-insensitively), with the problem
626
+ `{code: "E_SKILL_DUPLICATE", message: "composedSkills: skill \"<name>\"
627
+ from soul collides with module <id>'s skill"}`, the sentence spawn refuses
628
+ with. It is `null` when the soul resolves but cannot be composed here, with
629
+ the composition's code and sentence, naming `composedSkills`. It is `null`
630
+ with `soul-skills-unreadable` when the soul's own skills cannot be listed.
631
+
632
+ Routed with `--server <id>`, `--composed-skills` travels to the host; a host
633
+ whose probe does not advertise `soul-composed-skills` is refused with
634
+ `E_REMOTE_INCOMPATIBLE`, and nothing is sent.
635
+
591
636
  **Layers.** `id` is the capability filling the slot or `null`. `from`
592
637
  (feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
593
638
  or a home spawned before it was recorded.
@@ -987,7 +1032,8 @@ before a kernel that writes it ships. A change of meaning moves
987
1032
  the time it ran.
988
1033
 
989
1034
  **`add`** lists the deployment at or above `<dir>` (default: the working
990
- directory), canonical, and clears a `remove`. → `{"path":"/home/me/acme","added":true}`;
1035
+ directory: the nearest directory whose `oats-local.yaml` is a regular file,
1036
+ not a link), canonical, and clears a `remove`. → `{"path":"/home/me/acme","added":true}`;
991
1037
  `added: false` when it was listed already, and nothing is written. `--via
992
1038
  tui|desktop` names the client that adds it (default `cli`); any other value is
993
1039
  `E_BAD_ARGS`. Outside every deployment: `E_LOCAL_MISSING {dir}`.
@@ -2429,7 +2475,13 @@ it to a temporary copy (`soulFetched: true`).
2429
2475
  - `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
2430
2476
  `member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
2431
2477
  strings, module skills as `{name, source: "module:<cap>"}`) are display
2432
- only: bind to `modules[]` and `decision`.
2478
+ only: bind to `modules[]` and `decision`. A module skill's `name` is a
2479
+ skill the spawn copies, by the rule it copies by: a manifest entry that
2480
+ holds skill directories lists each of them, and a manifest with no
2481
+ `skills` lists each `skills/<dir>/` holding a `SKILL.md`, read at the
2482
+ module's commit (feature `soul-composed-skills`; earlier kernels named such
2483
+ an entry by its own directory, `skills`, and listed nothing for a manifest
2484
+ with no `skills`).
2433
2485
  - `resolution` (24 hex) hashes `declRevision` (the declarations) and
2434
2486
  `payloadRevision` (the merged payloads). `workspace` is the host key;
2435
2487
  `standalone` marks a standalone view. `task` is the task text or `null`.
@@ -2449,6 +2501,102 @@ it to a temporary copy (`soulFetched: true`).
2449
2501
  new head and revision. An apply with `--expect-decision` may reuse heads
2450
2502
  too (feature `spawn-apply-max-age`, [Apply](#apply)).
2451
2503
 
2504
+ #### The suggested name (feature `spawn-suggest-name`)
2505
+
2506
+ ```text
2507
+ oats spawn <soul> --preview --suggest-name --task-file <f> [the flags of a real spawn] [--json]
2508
+ ```
2509
+
2510
+ A preview that also chooses the instance's name, from the task (`--task-file`,
2511
+ or `--task <text>`). Like every preview it writes nothing and runs no hooks.
2512
+ - `--suggest-name` without `--preview`, or with `--name` or `--purpose`, is
2513
+ `E_BAD_ARGS`.
2514
+ - **The call.** The kernel makes one non-interactive call through the
2515
+ harness, executable and environment the spawn would launch (the launch
2516
+ configuration's `env`, not its `args`), with this prompt on stdin, never in
2517
+ argv:
2518
+
2519
+ > Name an agent for this task: 2–4 lowercase words joined by hyphens, describing the work, not the role. Reply with the name only.
2520
+ >
2521
+ > Task:
2522
+ > <the task text, at most 4000 characters>
2523
+
2524
+ It runs from a fresh empty temporary directory, removed afterwards, with no
2525
+ `OATS_INSTANCE*` variable, without a shell, in its own process group. It is
2526
+ made after the preview's harness checks (the executable's lookup and the
2527
+ harness package probes, from where the home will be) and before anything
2528
+ that depends on the name (placement, branch, home). It takes what those
2529
+ checks leave of the preview's one 20 s preflight budget, which is not
2530
+ raised for it: the group is killed after 20 s, or when the budget runs out
2531
+ first. Its time counts in `preflight.elapsedMs`; `preflight.status` stays
2532
+ that of the checks, so a numbered preview after a `timeout` is confirmed
2533
+ like any other. At most 4 KiB of its output is read.
2534
+ - **It starts none of the user's code: no MCP server, hook, plugin,
2535
+ extension or project setting, and no tool on either harness.** Three
2536
+ exceptions are stated:
2537
+ - Claude Code's own built-in plugins (`cc-plugin-*@builtin`) load as
2538
+ they always do, `--bare` included.
2539
+ - Hooks in the host's managed policy (`managed-settings.json`) still
2540
+ apply: they are the host admin's.
2541
+ - pi runs its own credential commands (`!command` keys and headers in
2542
+ models.json), as every pi launch does: they are its login.
2543
+
2544
+ A claude login through `apiKeyHelper` is not read (`--setting-sources
2545
+ ""`): such a user gets `harness-failed` and a numbered name.
2546
+
2547
+ Each harness's argv is proven to start nothing else
2548
+ (`scripts/naming-isolation-proof.mjs`, a recorded run against fixtures,
2549
+ rerun by an operator after a harness upgrade). The proof covers claude
2550
+ 2.1.288 and pi 1.3.0, on Linux; macOS is not proven.
2551
+ - **claude**, model `haiku`: `-p --tools "" --strict-mcp-config
2552
+ --setting-sources "" --disable-slash-commands --no-session-persistence
2553
+ --output-format text --model haiku`. Its native login is kept, which
2554
+ `--bare` would not keep.
2555
+ - **pi**, the instance's model: `-p --no-session --no-tools
2556
+ --no-extensions --no-mcp --no-skills --no-prompt-templates --no-themes
2557
+ --no-context-files --no-approve [--model <m>]`.
2558
+ - **codex** is not supported. Its naming call is not proven to start
2559
+ nothing, so a codex soul is numbered with `unsupported-harness`.
2560
+ - **The name.**
2561
+ 1. The reply's first non-empty line, as a slug.
2562
+ 2. Without one or more trailing `-<role>`. The role is the last word of the
2563
+ soul's name, after any package qualifier.
2564
+ 3. At most 4 words, cut at a word boundary to fit
2565
+ `64 − 1 − len(role)`.
2566
+ 4. Nothing left, or only the role, is `invalid-reply`.
2567
+ 5. The name is `<descriptive>-<role>`. A name that is taken (an instance,
2568
+ a soul or a live window, as for `--name`) gets `-2`, `-3`, and so on.
2569
+ - **The answer** is the full preview, plus `naming`:
2570
+
2571
+ ```json
2572
+ "naming": { "source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku" }
2573
+ ```
2574
+
2575
+ ```json
2576
+ "naming": { "source": "numbered", "reason": "timeout", "message": "claude gave no name within 20 s", "ms": 20000 }
2577
+ ```
2578
+
2579
+ - With `source: "suggested"`, `instance`, `home`, `branch` and `decision`
2580
+ are those of a preview with `--name <instance>`: an apply with `--name
2581
+ <instance> --expect-decision <revision>` matches it.
2582
+ - With `source: "numbered"`, they are today's numbered name, and the apply
2583
+ goes without `--name`.
2584
+ - `reason` is one of a closed set:
2585
+ - `no-task`: no task, or a blank one; no call is made.
2586
+ - `unsupported-harness`: no call is made.
2587
+ - `timeout`.
2588
+ - `harness-failed`: a nonzero exit, a signal, or no executable. `message`
2589
+ gives the exit or the signal, never the output.
2590
+ - `invalid-reply`.
2591
+ - `model` is `null` when the harness runs its own default.
2592
+ - A failure is never an error: the preview answers.
2593
+ - The text preview prints `name: suggested by claude (haiku) in 2310 ms` or
2594
+ `name: numbered (<reason>: <message>)`.
2595
+ - **`--server`:** the call runs on the target machine, through the routed
2596
+ preview, and the task travels as a routed spawn's does. A host that does
2597
+ not advertise `spawn-suggest-name` is refused (`E_REMOTE_INCOMPATIBLE`)
2598
+ before the spawn is sent.
2599
+
2452
2600
  **Provider settings.**
2453
2601
  - `providers` is the `--provider` map as typed.
2454
2602
  - `settings.<cap>`: the merged payload (manifest defaults, then workspace,
@@ -2582,6 +2730,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2582
2730
  `E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
2583
2731
  a silent `-2`.
2584
2732
  - The name is part of the decision.
2733
+ - `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
2734
+ descriptive name for the task, `<descriptive>-<role>`, which the apply then
2735
+ passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
2585
2736
 
2586
2737
  ### Spawn origin
2587
2738
 
@@ -3005,6 +3156,12 @@ its absence.
3005
3156
  An older kernel's `running` is the window's presence, and it checks a row
3006
3157
  with a claim against its session (as `oats session inspect` observes it),
3007
3158
  reading `null` unless a harness runs there.
3159
+ - **`color`** (feature `instance-color`): the instance's colour, one of
3160
+ `sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
3161
+ from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
3162
+ a `color` in `instance.json` never stands in for it. Every row has it,
3163
+ an unreadable record's row included (`null`). Presentation only: it is not
3164
+ identity and never addresses anything.
3008
3165
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
3009
3166
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
3010
3167
  is running, scheduled or owed; absent otherwise, and from older kernels.
@@ -3165,7 +3322,7 @@ route target:
3165
3322
  "soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
3166
3323
  "modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
3167
3324
  "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
3168
- "retirePending":false,"rollbackIncomplete":false,
3325
+ "color":"sage","retirePending":false,"rollbackIncomplete":false,
3169
3326
  "savedRoute":false,"addressable":true,"missingRemotely":false}],
3170
3327
  "retireFailures":[]}
3171
3328
  ```
@@ -3358,9 +3515,9 @@ whose key is not known; an unparsable ref is `E_REPO_REF`.
3358
3515
 
3359
3516
  ```json
3360
3517
  {"file":"/Users/me/.oats/servers.json",
3361
- "servers":[{"id":"altair-aweb","sshHost":"altair","workspace":"/Users/me/Agents/aweb","path":"/opt/homebrew/bin","label":"altair",
3518
+ "servers":[{"id":"altair-aweb","sshHost":"altair","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
3362
3519
  "workspaceKey":"github.com/awebai/ac",
3363
- "target":{"sshHost":"altair","workspace":"/Users/me/Agents/aweb","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
3520
+ "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
3364
3521
  "unknownWorkspace":["build"]}
3365
3522
  ```
3366
3523
 
@@ -3378,7 +3535,7 @@ contradicts fails the check with `E_SERVER_WORKSPACE_MISMATCH`, `details:
3378
3535
  ### `oats server connect` (feature `server-connect`)
3379
3536
 
3380
3537
  ```text
3381
- oats server connect <id> --ssh <host> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>]
3538
+ oats server connect <id> --ssh <host> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>]
3382
3539
  [--oats <path>] [--path <dirs>] [--label <text>] [--install-oats] [--replace] --json
3383
3540
  ```
3384
3541
 
@@ -3460,6 +3617,7 @@ instance's own machine: the local command, with `--server <id>` added.
3460
3617
  | `oats instance git\|diff <name> --server <id> …` | `instance-git` | `instance-git`, `instanceGitApi: 1` |
3461
3618
  | `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
3462
3619
  | `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
3620
+ | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
3463
3621
 
3464
3622
  - The flags are the local command's. The instance is addressed like every
3465
3623
  routed instance command ([servers.md](servers.md#run-there)): `--home` as
@@ -3730,7 +3888,7 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
3730
3888
 
3731
3889
  ### Waiting on you
3732
3890
 
3733
- Feature `waiting-on-you` (OATS 0.40.0): an instance blocked on a human (a
3891
+ Feature `waiting-on-you` (OATS 0.40.0): an instance waiting on a human (a
3734
3892
  permission prompt, a question, an agent asking for an answer) says so through
3735
3893
  a producer's claim. **Claims are display-only:** nothing in the kernel acts
3736
3894
  on `waitingOnYou`. In particular `oats session input` behaves exactly as
@@ -5378,6 +5536,60 @@ removal begins, and only with the home kept (`reached.home: "kept"`). A
5378
5536
  typed refusal keeps its code, its details and its own words; the inspections'
5379
5537
  and the recovery's refusals end with the sentence of their phase, once.
5380
5538
 
5539
+ ## An instance's colour (`oats instance color`)
5540
+
5541
+ Feature `instance-color` (awebai/oats#1421).
5542
+
5543
+ ```text
5544
+ oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]
5545
+ ```
5546
+
5547
+ The colour is presentation, not identity. Anyone may change it at any time,
5548
+ the agent on its own instance included, and it is never an address.
5549
+
5550
+ - **The palette** is closed: `sand`, `sage`, `slate`, `mauve`, `clay`,
5551
+ `olive`, the clients' own (`packages/client/soul-colors.mjs`).
5552
+ - **The record** is `<home>/.oats-color.json`, `{"colorApi": 1, "color":
5553
+ "sage", "at": "<ISO time>"}`, mode 0600, written atomically. `--clear`
5554
+ removes it. It is a kernel-owned home file: a capability cannot declare it
5555
+ as its own, and it is no change to the home at retire.
5556
+ - **A reader** takes a regular file only, without following a link, of at
5557
+ most 4 KiB. Anything that is not such a valid record reads as no colour
5558
+ (`null`), never as an error.
5559
+ - **The instance** is addressed as `oats instance stop` addresses it, and
5560
+ refused with the same answers: not found, ambiguous, a `--home` that is not
5561
+ its home, a record that cannot be read.
5562
+
5563
+ The answer:
5564
+
5565
+ ```json
5566
+ {"instanceColorApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","color":"sage","changed":true}
5567
+ ```
5568
+
5569
+ `color` is `null` after `--clear`. Setting the colour the instance already
5570
+ has answers `changed: false` and writes nothing; so does clearing an instance
5571
+ with no colour.
5572
+
5573
+ | Code | When |
5574
+ |---|---|
5575
+ | `E_BAD_ARGS` | The colour is not in the palette: `"<value>" is not an instance colour: use one of sand, sage, slate, mauve, clay, olive, or --clear`. Also: both a colour and `--clear`, neither, or two colours |
5576
+ | *(as `oats instance stop`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
5577
+ | `E_INSTANCE_RETIRING` | A retire of the home is in flight (its pending marker, or a live retire holding the home's lifecycle claim, which the command reads and never takes, as `oats worktree add` reads it), or the home is quarantined. Nothing was written |
5578
+ | `E_LIFECYCLE_BUSY` | The home's claim file cannot be read as a claim, or a retire's liveness cannot be read, as for `oats worktree add` |
5579
+
5580
+ Routed with `--server <id>`, the command runs on the host
5581
+ ([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
5582
+ not advertise `instance-color` is refused with `E_REMOTE_INCOMPATIBLE`, and
5583
+ nothing is sent.
5584
+
5585
+ Where it is read: `color` on [status rows](#the-roster-oats-status---json),
5586
+ on [remote roster rows](#the-remote-roster-oats-server-roster---json) (only a
5587
+ palette name is relayed, anything else is `null`), and on `oats inspect
5588
+ --home` as `instance.color`. A client draws a row's colour by one rule,
5589
+ `instanceColor(row)` in `packages/client/instance-presentation.mjs`: the
5590
+ row's palette name, else none. Colour never says a state alone: a client's
5591
+ mark keeps the state by its shape.
5592
+
5381
5593
  ## Sessions and launch configurations
5382
5594
 
5383
5595
  ### Input
package/docs/desktop.md CHANGED
@@ -201,28 +201,46 @@ repository at a time; "N of M shown" appears while a pill or the search
201
201
  narrows the list.
202
202
 
203
203
  A soul's page (open a soul from **Workspace › Souls**) ends with
204
- **Instructions**, what its instances are told: the soul's own `AGENTS.md`,
205
- read like a capability's injected instructions (a navigation tree on the left,
206
- the file on the right), at its path in the soul's repository. It comes from the
207
- same inspection as the rest of the page, so **Refresh** re-reads it and keeps
208
- what you had open, and your place in it. A file over 200,000 characters is
209
- shown cut, and says so.
210
-
211
- With an OATS that composes a soul's instructions (0.46.0 and later), the tree
212
- also has **Instance**: its **AGENTS.md**, *after spawn, with injects*, is the
213
- file a spawn of this soul on this computer would write, with one entry per part
214
- (the soul's own text, then each block OATS and the soul's capabilities add, in
215
- order). Open it to read the whole document; choose a part to go to it. Each
216
- part's header says where it comes from (**From this soul** or **Injected by …**)
217
- and names its file; a capability's part has **Open capability**, and **Copy
218
- composed AGENTS.md** copies the exact file. When the soul can't be composed
219
- here, the group says so and the problem shows at the top of the page. For a
220
- soul on another machine (a server workspace), the page shows the composed file
221
- when that machine supports it: this computer's OATS must be 0.49.0 or later, to
222
- pass on what each server reports about itself, and the server's OATS must say
223
- it composes a soul's instructions (0.49.0 and later report this). Until a
224
- server reports it (an older server, or one whose last read failed), its soul
225
- pages show only the soul's own `AGENTS.md`, with no **Instance** group.
204
+ **Instructions**, what its instances are told, read like a capability's
205
+ injected instructions (a navigation tree on the left, the file on the right).
206
+ The tree has two sections, a rule between them:
207
+
208
+ - **Defined in this soul**: its own `AGENTS.md`, at its path in the soul's
209
+ repository, and, with an OATS that reports a soul's skills, its **Skills**.
210
+ Open a skill to list its files; a file opens in the reader under its
211
+ repository path.
212
+ - **Composed for an instance**: what an instance of this soul gets. Its
213
+ **AGENTS.md**, *after spawn, with injects*, and its **Skills**, each saying
214
+ where it comes from. With an OATS that lists every skill a spawn gives the
215
+ instance (0.67.0 and later), the Skills are that list: the soul's own, each
216
+ **From this soul**, and the ones its capabilities add, each **From** the
217
+ capability. A capability's skill file opens under its place in the instance
218
+ home (`.oats/modules/<capability>/…`), with **Open capability** above it. With
219
+ an older OATS the skills listed are the soul's own, and a note says that the
220
+ skills capabilities add are listed by a newer OATS. For a soul on another
221
+ machine, the server's OATS must list them too, as for the composed
222
+ AGENTS.md below.
223
+
224
+ Both come from the same inspection as the rest of the page, so **Refresh**
225
+ re-reads them and keeps what you had open, and your place in it. A file over
226
+ 200,000 characters is shown cut, and says so.
227
+
228
+ The composed **AGENTS.md** needs an OATS that composes a soul's instructions
229
+ (0.46.0 and later). It is the file a spawn of this soul on this computer would
230
+ write, with one entry per part (the soul's own text, then each block OATS and
231
+ the soul's capabilities add, in order). Open it to read the whole document;
232
+ choose a part to go to it. Each part's header says where it comes from
233
+ (**From this soul** or **Injected by …**) and names its file; a capability's
234
+ part has **Open capability**, and **Copy composed AGENTS.md** copies the exact
235
+ file. When the soul can't be composed here, the section says so and the problem
236
+ shows at the top of the page. For a soul on another machine (a server
237
+ workspace), the page shows the composed file when that machine supports it:
238
+ this computer's OATS must be 0.49.0 or later, to pass on what each server
239
+ reports about itself, and the server's OATS must say it composes a soul's
240
+ instructions (0.49.0 and later report this). Until a server reports it (an
241
+ older server, or one whose last read failed), its soul pages show no composed
242
+ **AGENTS.md**. A soul's skills follow the same rule, with the server's OATS
243
+ saying it reports them.
226
244
 
227
245
  The **Spawn** dialog's left column, **What will be created**, starts with the
228
246
  new instance's name and its home. Then come where it works, its harness and
@@ -230,6 +248,44 @@ model (with where that choice came from), its default team and the teams it may
230
248
  also join, and its relationship when it has one. Under them are its core
231
249
  capabilities and its other capabilities.
232
250
 
251
+ The dialog's first field is the **Opening instruction**, and the dialog opens
252
+ with the cursor in it (after a restored instruction's text). In a narrow window,
253
+ **What will be created** comes after the form's last field, above **Spawn**:
254
+ scroll down with the fields to read it.
255
+
256
+ The dialog's last field before **Developer settings** is **Name · optional**.
257
+ Left empty, the kernel numbers the new instance (`<soul>-<n>`). A name you type
258
+ is used in lowercase and gets the soul's role, the last word of the soul's
259
+ name, as its suffix:
260
+ `desktop-improvements` for `oats-desktop-expert` becomes
261
+ `desktop-improvements-expert`. A name that already ends in the role, or is
262
+ the role, stays as typed. The line under the field shows the final name, and a
263
+ name that is too long, invalid or already taken is explained there. With an
264
+ OATS older than 0.26.0, which can't take an exact name, and for a spawn on a
265
+ server, what you type is a purpose instead: the instance is named
266
+ `<soul>-<purpose>`, and the field shows that prefix.
267
+
268
+ **Named from its task.** When the installed OATS can suggest names (feature
269
+ `spawn-suggest-name`), the help under an empty Name reads "Left empty, the
270
+ instance is named from its task." Once the Opening instruction holds at
271
+ least three words and you stop typing for about a second and a half, the
272
+ Desktop asks OATS for a name. The soul's own harness reads the instruction
273
+ and replies with a short name for the work, and the role is added as its
274
+ suffix. The name shows as the field's placeholder ("will be named
275
+ release-notes-manager"), on the line under the field ("(from the task)") and
276
+ in **What will be created**. It belongs to the instruction it was made for:
277
+ when you change the instruction it goes, until the next pause. Typing in Name
278
+ replaces it and stops suggestions for the rest of the dialog, even if you
279
+ empty the field again. Press **Spawn** with Name empty and no name yet, and the
280
+ dialog says **Naming…** and asks once, however short the instruction. When OATS
281
+ can't name it, the instance is numbered and a notification says why, for
282
+ example "Named oats-desktop-expert-3: naming took longer than 20 seconds."
283
+ That happens when there is no instruction, when the harness doesn't suggest
284
+ names (Codex), when there is no answer within 20 seconds, when the harness
285
+ couldn't be asked, and when its reply wasn't a name. Each request is a call
286
+ to the harness's model: nothing is asked before you type, nothing runs on a
287
+ timer, and a spawn on a server is not named this way.
288
+
233
289
  When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
234
290
  names them, in the order they run, and says this can take several minutes. Such
235
291
  a spawn may run for a long time: its roster row reads **Setting up worktree…**
@@ -545,6 +601,29 @@ right of its parent, and related instances are grouped together. Siblings are
545
601
  joined by a dotted line through their dots. A parent's line to its children
546
602
  runs just to the right of the dotted line, so the two never merge.
547
603
 
604
+ ## An instance's colour
605
+
606
+ An instance can have a colour, one of the soul palette's six (Sand, Sage,
607
+ Slate, Mauve, Clay, Olive). Its dot shows it wherever the instance is listed:
608
+ the sidebar, its terminal tab, the command palette and the overview. A running
609
+ instance's dot is filled with the colour, a stopped one's is a ring in it. An
610
+ instance whose state is unknown keeps the warning dot, and one without a colour
611
+ looks as before. The shape says the state, never the colour alone.
612
+
613
+ To set it, open **Instance: name and colour…** from the command palette, or
614
+ press Ctrl+Alt+R (⌥⌘R on macOS). It acts on the instance of the terminal you
615
+ are in, else the focused sidebar row, else the active terminal tab's instance.
616
+ The dialog shows the instance's name, which can't be changed yet, and the
617
+ colours as buttons: **None** and the six. Arrow keys move between them; Enter,
618
+ Space or a click sets the colour at once, and **Saved.** or OATS's refusal
619
+ appears under the title. The dialog stays open until you close it.
620
+
621
+ The colour is the instance's own, kept in its home by OATS
622
+ (`oats instance color`). Setting one needs OATS 0.67.0 or later on this
623
+ computer, and for an instance on a server, on that server too; until then the
624
+ buttons are disabled and the dialog says which is missing. An instance whose
625
+ home is being spawned or retired can't be given a colour meanwhile.
626
+
548
627
  ## Identity marks and harness badges
549
628
 
550
629
  Souls, capabilities and workspaces carry a coloured two-letter mark beside
@@ -80,7 +80,7 @@ and the rules its tests pin.
80
80
  | `souls/` | this repository's own souls (a workspace member) |
81
81
  | `docs/` | the reference pages, schemas, design records and release notes |
82
82
  | `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
83
- | `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)) |
83
+ | `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)), and the naming call's isolation proof (`naming-isolation-proof.mjs`, run by hand against real harnesses) |
84
84
  | `test/` | the kernel and CLI suites, with their fixtures |
85
85
 
86
86
  ## Kernel modules
@@ -92,11 +92,12 @@ and the rules its tests pin.
92
92
  | `workspace.mjs` | workspace, membership and soul files; discovery |
93
93
  | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
94
94
  | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
95
- | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally |
96
- | `materialize.mjs` | copying modules into a home and composing it |
95
+ | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
96
+ | `materialize.mjs` | copying modules into a home and composing it; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
97
97
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
98
98
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
99
- | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
99
+ | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul`, `inspect --soul --instructions` and `--composed-skills` (its `inScratch` reads the scratch home before it is removed, so the two flags share one materialization) |
100
+ | `instance-naming.mjs` | the suggested instance name of `spawn --preview --suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself; driven by `core.mjs` `spawnBody`, after the preview's harness checks, where a suggested name is then placed as `--name` would place it. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
100
101
  | `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
101
102
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
102
103
  | `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
@@ -110,7 +111,7 @@ and the rules its tests pin.
110
111
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
111
112
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
112
113
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
113
- | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
114
+ | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through |
114
115
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
115
116
  | `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
116
117
  | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire` and `oats instance stop --apply` (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
@@ -127,7 +128,7 @@ and the rules its tests pin.
127
128
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
128
129
  | `session-input.mjs` | session inspection and input transport. `createSessionPaneInspector` interprets one window's panes for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
129
130
  | `servers.mjs` | routing commands to a registered server |
130
- | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
131
+ | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
131
132
  | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`core.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
132
133
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
133
134
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
@@ -515,6 +516,15 @@ the rule:
515
516
  `HOME` of its own needs nothing. When the run has ended, a row added to the
516
517
  person's list during the run under a temporary directory fails the run,
517
518
  naming it.
519
+ - The auto-add never lists a deployment under a temporary directory
520
+ (awebai/oats#1397), so a test that needs it to list one makes its
521
+ deployments outside them: `test/helpers/outside-temporary.mjs`
522
+ `outsideTemporaryBase(t)`, a 0700 base in `/var/tmp` named
523
+ `oats-deployments-test-<run>.<n>-…` and removed when the test ends. Where
524
+ `/var/tmp` is missing, not writable or itself temporary, such a test skips,
525
+ saying why; it never falls back to `/tmp`. The run reads `/var/tmp` for its
526
+ own bases when it has ended: one still there is left behind, named for its
527
+ file and removed.
518
528
  - When the run has ended it reads each file's directory. If one is not empty
519
529
  the run fails, even if every test passed, and names each file and what it
520
530
  left.
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v5.2.1
44
- oats.aweb: v1.29.0
44
+ oats.aweb: v1.30.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.13.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.13.5` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
14
+ | `oats.aweb` | `v1.30.0` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |