@awebai/oats 0.55.1 → 0.56.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 (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. package/skills/oats-getting-started/SKILL.md +6 -3
@@ -45,7 +45,7 @@ see the [official catalog](official-catalog.md) for current pins.
45
45
  "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
46
  "server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
47
47
  "lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
48
- "soul-launch","retire-plan-own-worktree"],
48
+ "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key"],
49
49
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
50
50
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
51
51
  "capabilityShowApi":1}
@@ -117,6 +117,7 @@ see the [official catalog](official-catalog.md) for current pins.
117
117
  | `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
118
118
  | `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)) | |
119
119
  | `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)) | |
120
+ | `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)) | |
120
121
  | `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 | |
121
122
  | `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 | |
122
123
  | `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) |
@@ -128,6 +129,8 @@ see the [official catalog](official-catalog.md) for current pins.
128
129
  | `launch-prompt-dev-channel` | the kernel confirms Claude's development-channel prompt whenever it launches Claude with `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`, with no consent setting; `launchPromptAnswers` gone from previews; `consentSource` gone from `launch-prompt` events, which carry `claudeVersion`, `claudeVersionSource` and, on a miss, `differed`; `launchPrompts.status: "not-engaged"` and `"flag-ignored"`; `launchPrompts` in a launched spawn's answer; the `launch-prompt` readiness warning, OATS 0.52.0 ([Launch prompt results](#launch-prompt-results)) | |
129
130
  | `soul-launch` | `oats soul launch set\|remove`, the writer of `oats-local.yaml` `souls.launch`, and `E_LAUNCH_PREFERENCE_UNKNOWN`, OATS 0.53.0 ([`oats soul launch`](#oats-soul-launch)). Gate on the probe: a kernel without it answers `E_USAGE` | `soulLaunchApi: 1` (payload only) |
130
131
  | `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
132
+ | `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 | |
133
+ | `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 | |
131
134
 
132
135
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
133
136
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -137,6 +140,33 @@ Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
137
140
  **Gate on the probe, never by trying.** An older kernel can ignore an unknown
138
141
  flag and act: without `lifecycle-plans`, `retire --plan` retires.
139
142
 
143
+ ## Text output
144
+
145
+ A command's text (without `--json`) is for a person and is not part of this
146
+ contract. Some of its lines hold text the kernel did not write: a path as the
147
+ system or Git names it, a branch name, a hook's or a host's own words. In the
148
+ lines below, each character a terminal would act on, or that hides or
149
+ reorders text (a control character such as an escape or a newline, a bidi
150
+ override: the set the kernel never prints in text it did not write), is
151
+ spelled `\u{<hex>}` (OATS 0.53.0 for the local retire's warnings, #973; the
152
+ rest 0.56.0, #1006), so that such a name cannot clear the screen, write a
153
+ line of its own or reverse what follows it:
154
+
155
+ - the `note:` lines of `oats retire --plan`, `oats instance stop --plan`,
156
+ `oats instance git` and `oats readiness`;
157
+ - the `WARNING:` lines of `oats spawn` (its preview, and with `--server`
158
+ too), of the `oats session` commands (a start's or a restart's launch-hook
159
+ warnings, on stderr) and of `oats doctor` (a pi bridge's version skew);
160
+ - the lines of `oats retire`, local and with `--server`, for the recovery it
161
+ wrote, for the extra trees it handled and for the receipt's warnings. A
162
+ retire with `--server` prints the receipt's warnings as a local one does.
163
+
164
+ A newline in such a value is spelled too, so the value stays on its line.
165
+ Text that already holds the characters of a spelling (`\u{1b}` written out)
166
+ prints as it is: a spelling is not meant to be read back. Every other line of
167
+ text output prints what it holds as it is. The JSON is never changed by
168
+ this: its strings are what they are.
169
+
140
170
  ## The envelope and dispatch errors
141
171
 
142
172
  Every `--json` command except those below prints exactly one JSON object on
@@ -390,7 +420,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
390
420
  ### `oats inspect`
391
421
 
392
422
  ```text
393
- oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions]) [--max-age <s>] --json
423
+ oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
394
424
  ```
395
425
 
396
426
  An instance subject, abridged:
@@ -475,6 +505,72 @@ travels to the host; a host whose probe does not advertise
475
505
  `soul-composed-instructions` is refused with `E_REMOTE_INCOMPATIBLE`, and
476
506
  nothing is sent.
477
507
 
508
+ `skills` (feature `soul-skills`) is present only with `--skills`, which takes
509
+ a soul subject (`--home` is `E_BAD_ARGS`) and combines with `--instructions`;
510
+ without the flag the key is absent and no skill file is read. It lists the
511
+ soul's own skills, exactly the ones a spawn of it copies (not its
512
+ capabilities' skills), read from the same soul copy as `instructions`:
513
+
514
+ ```json
515
+ "skills":[{"name":"release-checklist","path":"skills/release-checklist","description":"Cutting a release.",
516
+ "files":[{"path":"skills/release-checklist/SKILL.md","bytes":812,"text":"---\nname: release-checklist\n…","binary":false,"truncated":false},
517
+ {"path":"skills/release-checklist/references/notes.md","bytes":2048,"text":null,"binary":false,"truncated":false,"omitted":true}],
518
+ "filesTruncated":false}]
519
+ ```
520
+
521
+ - `skills` is the list sorted by `name` in codepoint order; `[]` when the
522
+ soul has no skills of its own (no `skills/` directory, or none with a
523
+ `SKILL.md`); `null` when they could not be listed, with a problem below,
524
+ including a skill directory whose `SKILL.md` could not be examined.
525
+ It is also `null` when the soul's copy failed, and that copy's problem
526
+ explains it.
527
+ - A skill is a child directory of `skills/` holding a regular-file
528
+ `SKILL.md`, or `skills/` itself when it holds one (`name` is then
529
+ `skills`). `path` is POSIX and relative to the soul directory. Its
530
+ `description` is the `SKILL.md` front matter's `description`, by the same
531
+ function as [`oats capabilities show`](#oats-capabilities-show), which reads
532
+ the file up to 4 MiB: `null` when the file is unreadable, a symbolic link,
533
+ binary or over 4 MiB, or has no such string, and cut to 1024 bytes.
534
+ - `files` is every regular file under the skill directory, recursively,
535
+ sorted by `path` in codepoint order, each `path` relative to the soul
536
+ directory. At most 200 are listed; beyond that `filesTruncated` is `true`.
537
+ `files` is `null` (and `filesTruncated` `false`) when the files could not
538
+ be listed: an entry whose name is not a safe path component (`.git` in any
539
+ case, a backslash, a control character), or a listed file that cannot be
540
+ read safely (unreadable, gone, changed type, or refused as below). Could
541
+ not list never reads as listed nothing.
542
+ - A file is `{path, bytes, text, binary, truncated}`, by `oats capabilities
543
+ show`'s rules: `bytes` is its real size; `binary` (a NUL or invalid UTF-8
544
+ in its first 262,147 bytes) has `text: null` and `truncated: false`;
545
+ otherwise `text` is at most 262,144 bytes, cut on a code point boundary,
546
+ and `truncated` says it was cut.
547
+ - The whole field carries at most 1 MiB (1,048,576 bytes) of `text`, as
548
+ UTF-8, summed over its files in answer order. The file whose text would
549
+ pass that, and every file after it, has `text: null, binary: false,
550
+ truncated: false, omitted: true`; no other file has `omitted`, and a binary
551
+ file costs nothing. So `text` is `null` only with `binary: true` or
552
+ `omitted: true`.
553
+ - No symbolic link is followed. A symlinked file or directory inside a skill
554
+ is not listed, a symlinked skill directory is not a skill, and a symlinked
555
+ `skills/` makes `skills` `null` with a problem. FIFOs, sockets and devices
556
+ are not listed and never opened. A directory is listed, and a file read,
557
+ only once its real path lies inside its skill's, and the skill's inside the
558
+ soul's; one that does not makes the skill's `files` `null`. A file is
559
+ opened without following a symbolic link and must be the regular file the
560
+ listing found. One race remains: a parent directory swapped for a symbolic
561
+ link in the instant between that check and the open can redirect a read.
562
+ Only someone who can write the deployment's `agents/` tree can do that, and
563
+ they already control the soul copy and every instance's `AGENTS.md`.
564
+ - Problems are `{code, message}` in `problems[]`, each message starting
565
+ `skills: `: `soul-skills-unreadable` when the list is `null`, and
566
+ `soul-skill-files-unreadable`, naming the skill's `path`, for a skill whose
567
+ `files` is `null`.
568
+
569
+ Routed with `--server <id>`, `--skills` travels to the host; a host whose
570
+ probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
571
+ and nothing is sent. Every text is untrusted repository content: render it as
572
+ plain text or through a sanitising renderer.
573
+
478
574
  **Layers.** `id` is the capability filling the slot or `null`. `from`
479
575
  (feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
480
576
  or a home spawned before it was recorded.
@@ -507,10 +603,9 @@ message}`.
507
603
 
508
604
  A soul whose resolution is refused is an inspect error with the resolver's
509
605
  code and details (`E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`,
510
- `E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `E_REQUIREMENT_INACTIVE`,
511
- `E_TEAM_UNKNOWN`, and `E_WORKSPACE_SCHEMA` reason `local-teams-closed`);
512
- readiness reports the same condition
513
- as an item. Soul lookup errors are those of [spawn](#spawn-errors).
606
+ `E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `E_TEAM_UNKNOWN`, and
607
+ `E_WORKSPACE_SCHEMA` reason `local-teams-closed`); readiness reports the same
608
+ condition as an item. Soul lookup errors are those of [spawn](#spawn-errors).
514
609
 
515
610
  <a id="oats-readiness---home-----soul----dir----policy---json--readinessapi-2"></a>
516
611
  ### `oats readiness`
@@ -2353,6 +2448,16 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2353
2448
  <a id="spawn-errors"></a>
2354
2449
  ### Spawn errors
2355
2450
 
2451
+ A spawn answers the kernel's own code, as raised, whatever stage raised it
2452
+ (feature `spawn-kernel-codes`, OATS 0.56.0). Beyond the codes below that is
2453
+ any code of the kernel a spawn reaches: the deployment's files, where the home
2454
+ may be, the composition written into the home, reading a package or member at
2455
+ its commit, the harness's packages, the session, and the work and what a
2456
+ failed spawn leaves. **A code says nothing about how far the spawn got:**
2457
+ `details.unconfirmed` does. `E_SPAWN_FAILED` is for an error with no kernel
2458
+ code; a kernel without `spawn-kernel-codes` answers it for most codes its
2459
+ kernel stage raised as well.
2460
+
2356
2461
  | Code | Details | When |
2357
2462
  |---|---|---|
2358
2463
  | `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
@@ -2368,7 +2473,6 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2368
2473
  | `E_SLOT_CONFLICT`, `E_SKILL_DUPLICATE` | | the composition conflicts |
2369
2474
  | `E_WORKSPACE_SCHEMA` | `{path, key, reason}` | a removed key or invalid payload |
2370
2475
  | `E_CLONE_MISSING`, `E_CLONE_MISMATCH` | | the member's clone is missing or wrong |
2371
- | `E_REQUIREMENT_INACTIVE` | `{soul, capabilities, context, remedy}` | a declared requirement is not active |
2372
2476
  | `E_CHILD_SPAWNS_DISABLED` | `{parent, policy}` | the parent's policy is off |
2373
2477
  | `E_PARENT_NOT_FOUND`, `E_RELATIVE_NOT_FOUND` | | the anchor name matches no instance |
2374
2478
  | `E_RELATIVE_AMBIGUOUS` | | the anchor matches several instances (`--relative-root` picks one) or a same-named instance would shadow the edge |
@@ -2378,12 +2482,16 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
2378
2482
  | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
2379
2483
  | `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}`; retained launch-prompt outcomes additionally carry `{retained: true, target, parentLineageCommitted, launchPrompts}` | See [launch prompt results](#launch-prompt-results). |
2380
2484
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
2485
+ | `E_HARNESS_UNAVAILABLE` | `{harness, from, at, fix}` | the chosen harness has no executable on this machine ([launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) |
2486
+ | `E_CLAUDE_CONFIG_REMOVED` | `{file, executable, fix}` | a new claude launch with an `oats-claude-config` in reach ([configuration.md](configuration.md)) |
2487
+ | `E_HARNESS_RESOURCE_MISSING` | | a harness package a capability requires for the selected harness is not installed, disabled, or cannot be verified ([capabilities.md](capabilities.md)); raised before any home exists, at a preview too, and again by an apply after the home, the work and the hooks when the pane it got differs from the one it checked in a name the probe reads, or selects another program (another creator started the OATS tmux server): then the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start, a restart and a launch plan's `harness-packages` check answer the same code |
2381
2488
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
2382
2489
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
2383
2490
  | `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number |
2384
2491
  | `E_REQUIRED_HOOK_FAILED` | `{hooks}`, plus `unconfirmed: true` when compensation cannot finish | a required `spawn` or `worktree` hook failed or timed out; the spawn is rolled back. `hooks` holds the receipt of the event that failed: one entry per hook that ran, `{capability, ok, required, log, exitCode?, signal?, timedOut?, contract?}`, paths only. `log` is `null` for a spawn hook (it keeps no log) and once the rollback removed the home; a retained home keeps a `worktree` hook's log path. Never `home`. Before 0.49.0 a required spawn hook's failure answered `E_SPAWN_FAILED` |
2385
2492
  | `E_HOOK_ENVIRONMENT_CONTRACT` | the same as `E_REQUIRED_HOOK_FAILED`, the failed entry with `contract: "environment"` | a `spawn` hook answered an `env` its manifest does not allow, or a `worktree` hook answered `env` at all |
2386
- | `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
2493
+ | `E_RUNTIME_ENDPOINT_UNKNOWN` | | the session cannot be established: the OATS tmux server cannot be read at an apply (before any effect, or after the home, the work and the hooks), or the pane's `PATH`, `HOME` or harness folder cannot be read for the harness package check ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)), before anything is probed or created, or at the apply's second check after the hooks, as for `E_HARNESS_RESOURCE_MISSING`. Once the home exists the spawn is rolled back, with `details.unconfirmed` when that cannot finish. A start and a restart answer the same code |
2494
+ | `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish; `cause` for an error with a system code, or a defect | an error with no kernel code |
2387
2495
 
2388
2496
  Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
2389
2497
  keyed spawn is incomplete (`E_SPAWN_INCOMPLETE`) or compensation cannot confirm
@@ -2798,7 +2906,7 @@ messaging identity's `address` (else `alias`), or `null`.
2798
2906
  ### The remote roster (`oats server roster --json`)
2799
2907
 
2800
2908
  ```text
2801
- oats server roster [--server <id>] [--per-target <ms>] [--budget <ms>] --json
2909
+ oats server roster [--server <id>] [--workspace-key <key>]... [--per-target <ms>] [--budget <ms>] --json
2802
2910
  ```
2803
2911
 
2804
2912
  An envelope; `result` is `{groups, bounds}` (remote `roster`,
@@ -2883,7 +2991,9 @@ route target:
2883
2991
  name is unique on the host ([addressing](servers.md#run-there); a shared
2884
2992
  name is `E_AMBIGUOUS` with `error.details.candidates: [{agent, home}]`). A
2885
2993
  saved-route row the host did not list is addressable only while the host's
2886
- answer is unknown (`missingRemotely: false`).
2994
+ answer is unknown (`missingRemotely: false`). A row the host was reached
2995
+ for and did not list (`missingRemotely: true`) is the one
2996
+ [`server forget`](#forget-a-saved-route-oats-server-forget---json) is for.
2887
2997
  - **`savedRoute`**: the instance was spawned from this machine and has a
2888
2998
  saved route here. Information only; no action depends on it.
2889
2999
  - `running` is `null` when unknown; `backend` is `tmux` for a row with a tmux
@@ -2896,6 +3006,92 @@ route target:
2896
3006
  group's probe. Before 0.55.0 `bounds` also carried `skipped`, the number of
2897
3007
  groups the budget did not reach; it is gone with `E_ROSTER_BUDGET`.
2898
3008
 
3009
+ <a id="roster-workspace-key"></a>
3010
+ **`--workspace-key <key>`** (feature `roster-workspace-key`, OATS 0.56.0,
3011
+ #1124) narrows the roster to the groups that can belong to the given
3012
+ workspaces, so a host registered for another workspace, switched off or not,
3013
+ costs a window nothing. The flag is repeatable and every occurrence counts;
3014
+ `--workspace-key=<key>`, one argument per key, is the same (`--workspace-key=`
3015
+ and a value that starts with `--` are `E_BAD_ARGS`).
3016
+ With one or more keys, a group is probed and returned when:
3017
+
3018
+ 1. its registration's `workspaceKey` is one of the keys;
3019
+ 2. its registration's `workspaceKey` is not known (absent; `oats server
3020
+ check <id>` learns it);
3021
+ 3. it has no registration for its target (`registrationPresent: false`:
3022
+ saved routes only, the registration removed or changed to another
3023
+ target). Its workspace is unknown, so it is always probed: it holds the
3024
+ rows the Desktop offers Forget on (#1131), which no window's filter may
3025
+ hide.
3026
+
3027
+ A group whose registration names another workspace is neither probed nor
3028
+ returned, its saved routes under that registration and target with it. A
3029
+ group is judged by its registration when it has one, so a saved route whose
3030
+ target differs from the registration's is a group of its own, kind 3. A key
3031
+ is compared with the registration's `workspaceKey` by exact string equality:
3032
+ it is the canonical key a host's `status --json` reports as `workspace.key`,
3033
+ never parsed as a repository reference. An empty or missing value, or one
3034
+ with whitespace or a control character, is `E_BAD_ARGS`. `--server` and
3035
+ `--workspace-key` both narrow. Without the flag the answer is exactly as
3036
+ above. With it the answer's shape is unchanged (no filter is echoed in it);
3037
+ only which groups appear changes, and a key that matches nothing leaves the
3038
+ kinds 2 and 3. In text mode, keys that leave no group print `no remote groups
3039
+ for the given workspace keys`.
3040
+
3041
+ The Desktop reads one roster for all its windows: it passes the workspace key
3042
+ of every open window's view in one read, member-derived keys included (a
3043
+ registration records the key its host reports, whatever its `keyFrom`). A key
3044
+ that is `null`, or one the kernel would refuse, is no registration's: a view
3045
+ without a usable key adds none. The read is unfiltered when the Desktop has no
3046
+ window set or no roster answer yet, when a window shows the switcher, when a
3047
+ view without a usable key holds another machine's deployment (whose
3048
+ registration cannot then be named), and when no key is usable.
3049
+
3050
+ <a id="forget-a-saved-route-oats-server-forget---json"></a>
3051
+ ### Forget a saved route (`oats server forget --json`)
3052
+
3053
+ ```text
3054
+ oats server forget <server> --instance <instance> --json
3055
+ ```
3056
+
3057
+ It removes this computer's saved route to `<instance>` through `<server>`,
3058
+ the file under `$OATS_HOME_DIR/remote/<server>/`, and nothing else. It runs
3059
+ nothing on the host and does not contact it: the home there, if it still
3060
+ exists, is untouched ([servers.md](servers.md#what-this-machine-keeps)). It
3061
+ shipped in 0.22.3 with the roster's `missingRemotely`, so every kernel that
3062
+ reports a gone row answers it; there is no feature name.
3063
+
3064
+ An envelope; `result` is:
3065
+
3066
+ ```json
3067
+ {"server":"build","instance":"dev-a","home":"/srv/team/agents/dev/instances/dev-a",
3068
+ "target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},"forgotten":true}
3069
+ ```
3070
+
3071
+ - **`server`** and **`instance`**: the arguments, echoed.
3072
+ - **`home`**: the instance's home on the host, as the route recorded it.
3073
+ - **`target`**: the route's target (`{sshHost, workspace, oatsPath, …}`) as
3074
+ the route file recorded it, less the `herdrPath` a route written before
3075
+ 0.31.0 may hold.
3076
+ - **`forgotten`**: always `true` on success.
3077
+
3078
+ A refusal is `ok: false` with `error: {code, message}` only (no `details`,
3079
+ no `fix`), exit 1, and removes nothing:
3080
+
3081
+ - `E_USAGE`: no server id, or no `--instance` value.
3082
+ - `E_SERVER_INVALID`: the server id is not `^[a-z0-9][a-z0-9-]{0,63}$`.
3083
+ - `E_BAD_ARGS`: the instance name is not `^[a-z0-9][a-z0-9-]*$`.
3084
+ - `E_SNAPSHOT_UNKNOWN`: this computer has no saved route for that instance
3085
+ through that server id (a second forget of the same row answers this).
3086
+ - `E_SNAPSHOT_UNREADABLE`: the route file is not valid JSON; the file is
3087
+ kept.
3088
+
3089
+ The Desktop runs it only for a remote roster row with `missingRemotely:
3090
+ true`, after a confirmation, with exactly the row's `server` and `instance`
3091
+ as the arguments. It never shows `home` or `target`, and it reads the remote
3092
+ roster again after every outcome, a refusal and an unknown one included,
3093
+ instead of editing the row.
3094
+
2899
3095
  <a id="servers-per-workspace"></a>
2900
3096
  ### Servers per workspace (feature `servers-per-workspace`)
2901
3097
 
@@ -3424,8 +3620,9 @@ that is not an object; OATS 0.52.0) decides only for itself.
3424
3620
  repair its lineage. Its session may go on running under a parent that was
3425
3621
  retired; `oats status` is where it shows.
3426
3622
  - A spawn that names such a home as its parent or anchor is refused
3427
- (`E_SPAWN_FAILED`, the same sentence with `nothing was spawned`): the
3428
- parent's child-spawn policy and the lineage are in that record.
3623
+ (`E_UNIDENTIFIED_INSTANCE_HOME`, the same sentence with `nothing was
3624
+ spawned`; `E_SPAWN_FAILED` before 0.56.0): the parent's child-spawn policy
3625
+ and the lineage are in that record.
3429
3626
  - `oats session inspect`, `input` and `attach` on that home answer
3430
3627
  `E_RUNTIME_ENDPOINT_UNKNOWN`, and `oats instance events` still reads its
3431
3628
  logs.
@@ -4100,13 +4297,76 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4100
4297
  one Git names for it, <repository>, and does not write it into the
4101
4298
  record`. No key of the plan is new.
4102
4299
 
4103
- What `work/` is decides what the retire does with it, so it is part of
4104
- `planRevision` wherever it is not what the work mode alone says: when an
4105
- own tree became a directory of the home, or the other way round, between
4106
- the plan and the apply (a record's work mode that changed, a receipt that
4107
- is gone), or the repository read from Git changed, a guarded apply refuses
4108
- with `E_PLAN_STALE` before anything runs. Every other home has the
4109
- revision it had.
4300
+ <a id="retire-revision-work"></a>**A retire plan's `planRevision` binds
4301
+ everything the plan shows, except the facts that move by themselves**
4302
+ (0.56.0, #1065), which are these:
4303
+ - `at`, the instant of the read;
4304
+ - the counts against the branch's upstream and against the default branch
4305
+ (`facts.work.upstream.ahead` and `.behind`, `facts.work.base.ahead` and
4306
+ `.behind`), and the default branch's name (`facts.work.base.ref`): a
4307
+ fetch by anyone who shares the clone moves the remote's refs, and
4308
+ creates a missing `origin/HEAD`, where that name is read;
4309
+ - a child's session (`facts.children[].session`): a child's process ends
4310
+ when it ends, and a child that will not stop refuses the retire by
4311
+ itself (`E_CHILDREN_RUNNING`).
4312
+
4313
+ Everything else a plan shows is in its revision, in every home:
4314
+ - what the plan reports of the record: its work mode (`facts.workMode`),
4315
+ its repository (`facts.repo`), its branch (`facts.recordedBranch`) and
4316
+ whether it records a launch;
4317
+ - what `work/` is by this reading, with the repository Git names for
4318
+ `work/` wherever it is a registered work tree;
4319
+ - what Git says of `work/`: the commit, the branch and whether `HEAD` is
4320
+ detached, whether that branch is not the one the record names
4321
+ (`facts.work.drift`, as the plan shows it: it comes from a second read
4322
+ of the record, so it is not derived from `facts.recordedBranch`),
4323
+ the counts of changed and untracked files, the branch's upstream by its
4324
+ name (`facts.work.upstream.ref`) and the remote's host and path
4325
+ (`facts.work.remote`); and where Git gives no answer, the reason
4326
+ (`facts.work.reason`);
4327
+ - the session as the plan shows it (`facts.session`, whole: its state,
4328
+ and the `reason` or the `note` of one that is not established), which
4329
+ the record's launch and endpoint decide where the session's receipt
4330
+ does not;
4331
+ - the home's extra trees (`facts.extraWorktrees`, whole);
4332
+ - where a recovery would be written and the declared roots it leaves
4333
+ out, as the spawn's receipt gives them: the roots with their owners,
4334
+ not the note made from them, which is shortened past its budget and
4335
+ then reads alike for two lists of one length. A changed recovery
4336
+ exclusion changes the revision (it did not before 0.56.0);
4337
+ - of other homes: the children as the plan names them (`instance`,
4338
+ `agent`, `home`; a child's agent is the name its soul's file gives),
4339
+ the edges that could not be followed (`facts.ambiguous`, whole) and the
4340
+ children attached to this home's `work/`.
4341
+
4342
+ A key that is derived is bound through what it is derived from:
4343
+ `facts.ownWorktree` and `defaults.retainWorktree` (the reading), and
4344
+ every note and every line of the plan's text.
4345
+ `lifecycleApi`, `action`, `facts.pullRequest` and the defaults
4346
+ `deleteBranch`, `stopChildren` and `retainChildren` have one value in
4347
+ every plan of a kernel.
4348
+
4349
+ So two plans of one home that differ in anything else they show never
4350
+ share a revision, and a guarded apply after one of those things moved (a
4351
+ record's work mode, repository or branch that was rewritten, a receipt
4352
+ that is gone, an own tree that became a directory of the home, a
4353
+ directory of the home that became a work tree of another repository, a
4354
+ file where nothing was at `work/`, a receipt that declares another root)
4355
+ is refused with `E_PLAN_STALE` and the fresh plan, before anything runs.
4356
+ Two reads of a home that nobody touched give one revision.
4357
+
4358
+ Before 0.56.0 the revision held of the record its launch alone, of the
4359
+ session its state alone, and the reading only where its answer was not
4360
+ the one the record's work mode alone gives, or where the retire took the
4361
+ repository from Git because the record named none (0.53.0): a record
4362
+ rewritten between a plan and its apply could leave the plan's revision
4363
+ as it was.
4364
+ **Every retire plan read under an older kernel is stale under this one,
4365
+ once:** its apply is refused with `E_PLAN_STALE` and the fresh plan, and
4366
+ the person confirms again. A repeated apply with the idempotency key of a
4367
+ retire that did run is answered from its stored receipt as before,
4368
+ whatever revision it carries: the receipt is looked for before any plan
4369
+ is read.
4110
4370
  - A link at `work/` is never the instance's own tree: the retire removes
4111
4371
  the link with the home and does not touch what it leads to, whatever the
4112
4372
  record says (0.53.0, #973). The record is a file the instance can write;
@@ -4142,13 +4402,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4142
4402
  stored in the link; nothing acts on it. When the link does not resolve,
4143
4403
  the string ends `and it led nowhere that could be read`. The receipt holds
4144
4404
  the path as the system gave it. The retire's text (without `--json`)
4145
- prints every warning of the receipt on one line and spells each character
4146
- a terminal would act on, or that hides or reorders text (a control
4147
- character such as an escape or a newline, a bidi override: the set the
4148
- kernel never prints in text it did not write), as `\u{<hex>}`, so that a
4149
- name cannot clear the screen or write a line of its own. The JSON is not
4150
- changed by that: its strings are what they were. No key of the plan or of
4151
- the receipt is new.
4405
+ prints every warning of the receipt on one line, spelled as
4406
+ [Text output](#text-output) says. The JSON is not changed by that: its
4407
+ strings are what they were. No key of the plan or of the receipt is new.
4152
4408
  - A link at `work/` that is no longer a link when the retire inspects the
4153
4409
  home again (a retire hook, or anything else, put a directory or a file in
4154
4410
  its place) refuses with `E_WORK_INSPECTION_FAILED` and keeps the home, in
@@ -4211,7 +4467,7 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4211
4467
  case. Read an unknown `state` as not idle.
4212
4468
  - `notes` says what a retire would copy to recovery (0.42), in up to two
4213
4469
  strings read from the home's retirement baseline and the work mode, without
4214
- hashing anything:
4470
+ hashing a file of the home:
4215
4471
 
4216
4472
  ```text
4217
4473
  recovery: the home is copied to /w/agents/dev/instances/.oats-retirement/recovery before the home is removed, when it changed since spawn; not copied: .aw, .aweb-identity, .aweb-identity-*, .oats-aweb (oats.aweb)
@@ -4233,7 +4489,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4233
4489
  The second is the line above in worktree mode, `recovery: work/ is copied
4234
4490
  there when it is not empty` in directory mode, and absent in checkout,
4235
4491
  attached and workspace modes. They are strings in `notes`: no other key
4236
- changes, and `planRevision` is unaffected.
4492
+ changes. From 0.56.0 the declared roots are part of `planRevision`, as
4493
+ the baseline gives them and not as the note says them (#1065,
4494
+ [the plan's revision](#retire-revision-work)); before it they were not.
4237
4495
  - `facts.extraWorktrees` (0.42.1) lists the instance's
4238
4496
  [extra trees](souls-and-instances.md#extra-trees-at-retire): linked
4239
4497
  worktrees at `<home>/.work-*` that Git confirms. It is an array, empty when
@@ -4898,7 +5156,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
4898
5156
  `restart`),
4899
5157
  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
4900
5158
  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
4901
- started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`
5159
+ started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`,
5160
+ `E_HARNESS_RESOURCE_MISSING` (a harness package an active capability
5161
+ requires is not installed, disabled, or cannot be verified: nothing was
5162
+ started; `E_HARNESS_PACKAGE` before 0.56.0), `E_SESSION_FAILED`
4902
5163
  (any error that is not the kernel's; with
4903
5164
  [`details.cause`](#kernel-codes) when it has a code of its own or is a
4904
5165
  defect, and without it when it is a refusal without a code).
@@ -4981,7 +5242,11 @@ accept `--server <id>`.
4981
5242
  launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
4982
5243
  declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
4983
5244
  true} | {name, reference: true}], command (redacted), prompt, hooks,
4984
- preflight: [{check, ok, detail}], ok}`.
5245
+ preflight: [{check, ok, detail, code?}], ok}`. A failed check carries the
5246
+ code a start would refuse with; the `harness-packages` check's is the
5247
+ gate's own, `E_HARNESS_RESOURCE_MISSING` (`E_HARNESS_PACKAGE` before
5248
+ 0.56.0). A fault of the gate, which is no verdict on a package, is not a
5249
+ row: the preview fails as a whole.
4985
5250
 
4986
5251
  `launchConfigDefault` (0.32) is `true` when `launchConfig` is this host's
4987
5252
  default for the harness rather than a chosen configuration; the spawn preview
@@ -5454,12 +5719,20 @@ It uses the existing success/error JSON envelope. Result:
5454
5719
 
5455
5720
  There is one entry per target file: the ambient file of each selected harness,
5456
5721
  then one per launch configuration whose `env` sets `CLAUDE_CONFIG_DIR` or
5457
- `CODEX_HOME`, deduplicated by canonical directory. `ambient` says whether the
5458
- operator's own environment selects the file; `launchConfigs` names the launch
5459
- configurations that do (sorted). A launch configuration whose directory cannot
5722
+ `CODEX_HOME`, or sets `HOME` when its launch has no such variable at all
5723
+ (its default file under that `HOME`), deduplicated by canonical directory. `ambient` says whether the
5724
+ file is the one a launch with no launch configuration reads (by the
5725
+ environment its tmux pane will have, or the operator's own when no OATS tmux
5726
+ server runs, which `warnings` then says:
5727
+ [harness-trust.md](harness-trust.md)); `launchConfigs` names the launch
5728
+ configurations that select it (sorted). A launch configuration whose directory cannot
5460
5729
  be resolved (an unset reference, a relative path) or does not exist is a
5461
5730
  `refused` entry with a `problem` string naming it; `file` is null when the path
5462
- is unresolved. The directory is never created.
5731
+ is unresolved. The directory is never created. A file the writer refuses (its
5732
+ type, links, owner, mode bits, `ls` metadata markers, size, encoding or format)
5733
+ is a `refused` entry whose `problem` is the file and the check that refused it,
5734
+ in fixed wording that never includes the file's content; such an entry's
5735
+ `current` and digests do not describe the file's trust.
5463
5736
 
5464
5737
  Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted|skipped`. `skipped` (with `reason`) is a harness whose ambient configuration directory does not exist under `--harness all`; it is never created.
5465
5738
  `current` contains only the known trust scalar, or null when missing. Codex's key
@@ -5472,7 +5745,16 @@ unverifiable observations). The intent retains the candidate digest. Apply's aud
5472
5745
  in warnings, without native configuration contents.
5473
5746
 
5474
5747
  Preflight failures, including any entry `problem`, use `E_CONFIG_BROKEN` with the
5475
- result in details; the message names each problem. Apply failures
5748
+ result in details; the message names each problem. One case has its own code:
5749
+ when the only refused entries are ambient ones whose file could not be
5750
+ established, because a server runs and the environment of its panes cannot be
5751
+ read, or because tmux could not say whether the server runs (its
5752
+ `list-sessions` refused or cut off; with no tmux on the command's `PATH`
5753
+ no read is made, and the operator's own file is the target, said in
5754
+ `warnings`), the code is `E_RUNTIME_ENDPOINT_UNKNOWN` (`Harness trust targets cannot be
5755
+ established; nothing was written: …`), with the same details: the entry is
5756
+ `refused`, `file` null, with its `problem`. With a refused launch
5757
+ configuration's entry beside it, `E_CONFIG_BROKEN` wins. Apply failures
5476
5758
  use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
5477
5759
  reason is the closed set `locked|changed|audit|write|verify`; the message names the
5478
5760
  failed files. Partial writes are