@awebai/oats 0.57.0 → 0.58.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 (60) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +19 -28
  3. package/docs/desktop-cli-api.md +38 -15
  4. package/docs/desktop.md +14 -0
  5. package/docs/execution-targets.md +10 -1
  6. package/docs/implementation.md +7 -1
  7. package/docs/integrations.md +3 -1
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.57.1.md +275 -0
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/servers.md +18 -0
  13. package/docs/souls-and-instances.md +9 -0
  14. package/docs/tui.md +224 -87
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +11 -4
  17. package/lib/session-viewer.mjs +29 -4
  18. package/package-catalog.json +1 -1
  19. package/package.json +1 -1
  20. package/packages/client/cli-adapter.mjs +9 -7
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/composed-gate.mjs +34 -0
  23. package/packages/client/inspect-boundary.mjs +157 -0
  24. package/packages/client/inspect-cache.mjs +86 -0
  25. package/packages/client/keyed-catalog.mjs +132 -0
  26. package/packages/client/launch-view.mjs +46 -0
  27. package/packages/client/panel-views.mjs +1 -1
  28. package/packages/client/session-attach.mjs +7 -5
  29. package/packages/client/soul-catalog.mjs +77 -0
  30. package/packages/client/soul-colors.mjs +31 -0
  31. package/packages/client/soul-facts.mjs +85 -0
  32. package/packages/client/soul-rows.mjs +48 -0
  33. package/packages/client/spawn-apply-cli.mjs +19 -8
  34. package/packages/client/spawn-apply.mjs +216 -0
  35. package/packages/client/spawn-messages.mjs +131 -85
  36. package/packages/client/spawn-preview-cli.mjs +2 -1
  37. package/packages/client/spawn-preview-contract.mjs +3 -0
  38. package/packages/client/spawn-preview-facts.mjs +119 -0
  39. package/packages/client/spawn-preview.mjs +164 -0
  40. package/packages/client/spawn-transaction.mjs +136 -0
  41. package/packages/record/lib/directory-identity.mjs +14 -0
  42. package/packages/record/lib/native-history.mjs +6 -5
  43. package/packages/tui/README.md +32 -11
  44. package/packages/tui/lib/actions.mjs +10 -1
  45. package/packages/tui/lib/config.mjs +9 -14
  46. package/packages/tui/lib/main.mjs +165 -57
  47. package/packages/tui/lib/model.mjs +28 -24
  48. package/packages/tui/lib/panel.mjs +1019 -0
  49. package/packages/tui/lib/read.mjs +5 -14
  50. package/packages/tui/lib/store.mjs +77 -30
  51. package/packages/tui/lib/term/capture.mjs +260 -0
  52. package/packages/tui/lib/term/screen.mjs +44 -8
  53. package/packages/tui/lib/term/style.mjs +78 -6
  54. package/packages/tui/lib/term/text.mjs +24 -4
  55. package/packages/tui/lib/term/through.mjs +213 -0
  56. package/packages/tui/lib/term/tty.mjs +7 -60
  57. package/packages/tui/lib/views/frame.mjs +126 -40
  58. package/packages/tui/lib/views/help.mjs +12 -10
  59. package/skills/oats-getting-started/SKILL.md +3 -2
  60. package/packages/tui/lib/open.mjs +0 -45
package/bin/oats.mjs CHANGED
@@ -104,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
104
104
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
105
105
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
106
106
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
107
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key"];
107
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age"];
108
108
  /** Commands `--server <id>` runs on a registered server. */
109
109
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
110
110
  const flag = (name) => {
@@ -1484,16 +1484,24 @@ function sayReadNotices() {
1484
1484
  for (const notice of readSession?.notices.splice(0) ?? []) process.stderr.write(`oats: warning: ${notice}\n`);
1485
1485
  }
1486
1486
  /** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
1487
- * → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
1488
- const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, trigger poll, and the read forms of teams and soul teams";
1487
+ * → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`.
1488
+ * Write verbs refuse it: a writer acting on a reused observation could persist a fact the workspace no
1489
+ * longer holds. A preview-bound spawn apply is the exception: its fence (--expect-decision) binds it to
1490
+ * the decision the operator confirmed, so a reused head applies nothing beyond that decision. */
1491
+ const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, spawn --expect-decision <revision>, trigger poll, and the read forms of teams and soul teams";
1489
1492
  function maxAgeRefusal(command, head) {
1490
1493
  const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
1491
- const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
1494
+ const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs and a preview-bound spawn apply reuse observations (${MAX_AGE_READS})`;
1492
1495
  if (head.includes("--server")) return "--max-age cannot be combined with --server: observation reuse is local to this machine";
1493
1496
  switch (command) {
1494
1497
  case "status": case "souls": case "capabilities": case "inspect": return null;
1495
- // A preview reads (feature spawn-preview-max-age); an apply always observes live.
1496
- case "spawn": return head.includes("--preview") ? null : refuse("spawn");
1498
+ // A preview reads (feature spawn-preview-max-age); an apply only when a confirmed decision binds it
1499
+ // (feature spawn-apply-max-age), with a value as spawn reads it: a bare --expect-decision binds nothing.
1500
+ case "spawn": {
1501
+ const expected = flag("expect-decision");
1502
+ if (head.includes("--preview") || (expected !== undefined && expected !== true)) return null;
1503
+ return "--max-age is not accepted by `oats spawn` without --expect-decision: a spawn apply reuses observations only with --expect-decision <revision>, which binds it to the decision a preview showed";
1504
+ }
1497
1505
  case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
1498
1506
  case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
1499
1507
  // `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
@@ -2686,8 +2694,8 @@ async function status() {
2686
2694
  const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
2687
2695
  /** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
2688
2696
  * `--instance` is refused by a local spawn (with its replacement) but still travels to an older
2689
- * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview: the
2690
- * dispatch allow-list (maxAgeRefusal) refuses it on an apply. */
2697
+ * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
2698
+ * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2691
2699
  const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
2692
2700
  const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
2693
2701
  /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
@@ -4803,7 +4811,8 @@ Usage:
4803
4811
  instance.json providers.<capability>)
4804
4812
  [--preview [--max-age <s>]] decide everything, create nothing; the JSON's
4805
4813
  decision binds an apply (--expect-decision <rev>);
4806
- --max-age reuses recent heads (preview only)
4814
+ --max-age reuses recent heads, on a preview and
4815
+ on an apply bound by --expect-decision only
4807
4816
  oats retire <instance> [--force] retire an instance (window, hooks,
4808
4817
  [--self] worktree, home); --self = retire the
4809
4818
  [--keep-dir] [--json] CALLING instance: the window dies, then
@@ -4981,9 +4990,13 @@ Observation reuse (feature observe-max-age):
4981
4990
  remote again; the JSON
4982
4991
  then carries observation { observedAt (the oldest
4983
4992
  head used), reused, localRevision (a digest of
4984
- the local configuration read) }. Refused
4993
+ the local configuration read) }. A spawn apply
4994
+ bound by --expect-decision takes it too (feature
4995
+ spawn-apply-max-age): its decision fence holds,
4996
+ and its JSON carries no observation. Refused
4985
4997
  (E_BAD_ARGS) by every other command, an edit form,
4986
- a spawn apply, and with --server
4998
+ a spawn apply without --expect-decision, and with
4999
+ --server
4987
5000
 
4988
5001
  Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
4989
5002
  }
@@ -87,9 +87,14 @@ Loading development channels” prompt through the **approved route**: the
87
87
  development prompt. Claude admits the plugin when a root-owned machine
88
88
  managed-settings file lists it. The route does not depend on the Claude
89
89
  version and needs no OATS mechanism beyond these settings. The operator's
90
- ordered procedure is the `oats.setup` host step “Claude channel delivery
91
- (approved route)” in `/oats-workspace-config`, which `/oats-onboarding` card 4
92
- calls; the provider's side is `/oats-aweb` §4.
90
+ ordered procedure is the `oats.setup` skill `/oats-host-delivery`, whose
91
+ Choice 1 is this route and whose Choice 2 is the host wake broker;
92
+ `/oats-onboarding` card 4 makes both choices and card 8 checks them. The provider's side is
93
+ `/oats-aweb` §4.
94
+
95
+ An unset `claudeChannelMode` is development mode, so a host that never makes
96
+ the choice runs every Claude home with the development prompt. Set the key
97
+ explicitly, to `approved` or, as a recorded fallback, `development`.
93
98
 
94
99
  **The managed-settings file** is a host change made by a human admin with
95
100
  sudo. OATS never writes it.
@@ -127,7 +132,11 @@ settings:
127
132
  ```
128
133
 
129
134
  With channel delivery, pi uses its `@awebai/pi` extension and Codex always
130
- uses the host broker.
135
+ uses the host broker. The broker (`aw wake run`, one per host user) also wakes
136
+ every joined team and every `delivery: session` home. Without it, joined teams
137
+ are poll-only. It runs as a per-user launchd or systemd service that the
138
+ operator installs, with `AW_WAKE_OATS_BIN` and a `PATH` that reaches `oats`,
139
+ `node` and `tmux`. That procedure is Choice 2 of `/oats-host-delivery`.
131
140
 
132
141
  **The plugin.** `aweb-channel` must be installed from the marketplace named
133
142
  `awebai-marketplace` (GitHub `awebai/claude-plugins`) and enabled, in the
@@ -142,29 +151,10 @@ without the operator's word.
142
151
  confirm: [the development-channel confirmation](#the-development-channel-confirmation)
143
152
  applies only to a launch with the development-channel flag.
144
153
 
145
- **Verify:**
146
-
147
- 1. `oats spawn <soul> --preview` shows `settings.oats.aweb.claudeChannelMode:
148
- approved` and `delivery: channel`.
149
- 2. The started session shows no development prompt, and its banner shows
150
- “Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace
151
- inject directly in this session”, followed by “restart without --channels
152
- to stop”. At normal terminal widths the banner wraps over two rows: look
153
- for each part, not for one string.
154
- 3. The banner says none of `not on the approved channels allowlist`,
155
- `not on your org's approved channels list`, `blocked by org policy` or
156
- `plugin not installed`.
157
- 4. Receive is proven only by the `/oats-aweb` nonce exchange.
158
-
159
- **Failure banners**, their cause and remedy:
160
-
161
- | What the session shows | Cause | Remedy |
162
- |---|---|---|
163
- | `not on the approved channels allowlist` | the effective managed policy has no `allowedChannelPlugins` (no file, the file not read, or the key missing), so Anthropic's default list applied | write or fix the file |
164
- | `not on your org's approved channels list` | the effective policy has an `allowedChannelPlugins` without this plugin and marketplace pair: the names in the file are wrong, or a higher source (server-managed settings or MDM) supplies its own list | fix the entry, or have the organization admin add it |
165
- | `blocked by org policy` (then “Inbound messages will be silently dropped”) | the effective policy lacks `channelsEnabled: true`, which Team/Enterprise subscribers need, and API-key use whenever any managed policy exists | add the key, or have the organization admin set it |
166
- | `plugin:aweb-channel@awebai-marketplace · plugin not installed` | the plugin is not installed in the launch's Claude config directory | install and enable it there |
167
- | the development prompt still appears | the home started in development mode, not approved: the host setting is missing, or the home was spawned before the change | set `claudeChannelMode: approved`, then respawn the home |
154
+ **Verify** with the success list and the failure-banner table of
155
+ `/oats-host-delivery`, Choice 1: the preview's mode, the admitted banner
156
+ with no failure banner, then the `/oats-aweb` nonce exchange, which alone
157
+ proves receive.
168
158
 
169
159
  **Limits.** Channels are an Anthropic research preview. Anthropic's
170
160
  account-level feature flag gates channels on every route. The allowlist
@@ -621,5 +611,6 @@ the bounded parsed-read cache and the observations `--max-age` reuses; all of
621
611
  it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
622
612
  catalog file. The read verbs (`status`, `workspace status`, `souls`,
623
613
  `capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
624
- `spawn --preview`) take `--max-age <seconds>` to reuse a remote head observed that recently
614
+ `spawn --preview`), and a spawn apply bound by `--expect-decision`, take
615
+ `--max-age <seconds>` to reuse a remote head observed that recently
625
616
  ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).
@@ -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","spawn-kernel-codes","soul-skills","roster-workspace-key"],
48
+ "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age"],
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}
@@ -131,6 +131,7 @@ see the [official catalog](official-catalog.md) for current pins.
131
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
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
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 | |
134
+ | `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`) | |
134
135
 
135
136
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
136
137
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -308,6 +309,7 @@ it and answer live, without the block.
308
309
  oats status | workspace status | souls | capabilities | inspect --soul|--home
309
310
  | teams | soul teams <soul> … --max-age <seconds> --json
310
311
  oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
312
+ oats spawn <soul> … --expect-decision <revision> --max-age <seconds> --json (feature spawn-apply-max-age)
311
313
  oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
312
314
  oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
313
315
  ```
@@ -327,10 +329,13 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
327
329
  - **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
328
330
  preview's `result` gains the same block, so you can say "as of
329
331
  `<observedAt>`". The `decision` covers the heads the preview used, reused
330
- or live: a reused head the member has since moved from makes the apply
331
- (which always observes live) refuse `E_DECISION_STALE`, and the apply
332
- records the head it observed, so the next preview under `--max-age` shows
333
- it with a new `decision.revision`. The apply itself refuses the flag.
332
+ or live: a reused head the member has since moved from makes an apply
333
+ that observes live refuse `E_DECISION_STALE`, and the apply records the
334
+ head it observed, so the next preview under `--max-age` shows it with a new
335
+ `decision.revision`. The preview-bound apply takes the flag from
336
+ `spawn-apply-max-age` (OATS 0.58.0): with `--expect-decision`, it reuses
337
+ heads as the preview does, and its decision fence is unchanged
338
+ ([Apply](#apply)). Its answer carries no block.
334
339
  - **`localRevision`:** 24 lowercase hex characters, opaque. It digests every
335
340
  piece of local configuration the kernel read for this answer:
336
341
  `oats-local.yaml` (and each closer `oats-local.yaml` it looked for and did
@@ -361,18 +366,25 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
361
366
  spelling of the same repository (ssh vs https) or for a different ref; its
362
367
  commit can no longer be fetched. Each is observed live, as without the flag.
363
368
  A live observation that fails is the usual error, never an older head.
364
- - **Refusals:** every other command, a spawn apply (with or without
365
- `--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`)
369
+ - **Refusals:** every other command, every edit form (`teams add|remove|default`)
366
370
  and any `--server`
367
371
  invocation refuse the flag before reading or writing anything (the removed
368
372
  `soul teams --add|--remove|--default|--clear-default` answer their own
369
373
  `E_BAD_ARGS` first), with
370
374
  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
371
- verbs reuse observations (status, workspace status, souls, capabilities,
372
- capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
373
- and the read forms of teams and soul teams)" and,
375
+ verbs and a preview-bound spawn apply reuse observations (status, workspace
376
+ status, souls, capabilities, capabilities show, inspect --soul|--home,
377
+ spawn --preview, spawn --expect-decision <revision>, trigger poll, and the
378
+ read forms of teams and soul teams)" and,
374
379
  with `--server`, "--max-age cannot be combined with --server: observation
375
- reuse is local to this machine".
380
+ reuse is local to this machine". A spawn apply without `--expect-decision`
381
+ (or with no value after it) refuses it with `E_BAD_ARGS` "--max-age is not
382
+ accepted by \`oats spawn\` without --expect-decision: a spawn apply reuses
383
+ observations only with --expect-decision <revision>, which binds it to the
384
+ decision a preview showed". Write verbs refuse the flag because a writer
385
+ acting on a reused observation could persist a fact the workspace no longer
386
+ holds; a preview-bound apply is the exception because its fence binds it to
387
+ the decision the operator confirmed.
376
388
  A capability command's argv (`oats <namespace> …`) is its provider's: the
377
389
  kernel neither reads nor refuses `--max-age` there. The same holds for
378
390
  `capture`, `recall`, `setup` and `experimental`, which parse their own argv:
@@ -2316,10 +2328,11 @@ it to a temporary copy (`soulFetched: true`).
2316
2328
  localRevision}`, shaped exactly as the read verbs' block; without it the
2317
2329
  preview is exactly as before, and no other field changes shape.
2318
2330
  - `decision.revision` covers the heads the preview used, reused or live.
2319
- Apply never reuses (it refuses `--max-age`): a head that moved since the
2320
- reused observation refuses `E_DECISION_STALE`, and the apply records what
2321
- it observed, so re-preview under `--max-age` to get the new head and
2322
- revision.
2331
+ An apply without `--max-age` (or with `--max-age 0`) observes live: a head
2332
+ that moved since the reused observation refuses `E_DECISION_STALE`, and the
2333
+ apply records what it observed, so re-preview under `--max-age` to get the
2334
+ new head and revision. An apply with `--expect-decision` may reuse heads
2335
+ too (feature `spawn-apply-max-age`, [Apply](#apply)).
2323
2336
 
2324
2337
  **Provider settings.**
2325
2338
  - `providers` is the `--provider` map as typed.
@@ -2363,6 +2376,16 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
2363
2376
  `E_INSTANCE_NAME_TAKEN` (for `--name`) or `E_PLACEMENT_TAKEN`.
2364
2377
  - A refused child spawn appends `child-spawn-refused` to the parent's log (on
2365
2378
  apply only).
2379
+ - `--max-age <s>` with `--expect-decision <revision>` (feature
2380
+ `spawn-apply-max-age`, OATS 0.58.0) reuses member heads this machine
2381
+ observed at most `<s>` seconds ago, exactly as the preview does (the same
2382
+ values and fallbacks to a live observation), so an apply right after its
2383
+ preview asks no remote again. The decision is computed from those heads, and
2384
+ one that differs from `<revision>` is `E_DECISION_STALE`, as without the
2385
+ flag. The answer (success, replay, every refusal) has no `observation`
2386
+ block: the preview already gave its "as of".
2387
+ Without `--expect-decision` the flag is `E_BAD_ARGS`
2388
+ ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)).
2366
2389
 
2367
2390
  **Idempotency** (feature `spawn-idempotency-2`): `--idempotency-key <key>`
2368
2391
  with `--expect-decision` records the key and decision in `instance.json`.
package/docs/desktop.md CHANGED
@@ -166,6 +166,16 @@ workspace on a server: `name — server`).
166
166
  - Tabs belong to their window: a workspace's terminals and tabs stay in the
167
167
  window they were opened in, and switching that window back to the
168
168
  workspace brings them back.
169
+ - A tab's terminal ends ("session ended") when its instance's tmux window
170
+ goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
171
+ another instance's terminal. Stopping an instance leaves its tab open.
172
+ - When a roster read shows an instance retired, from the Desktop, the CLI,
173
+ another agent or another machine, every tab of that instance closes, in
174
+ every split. In each split the next tab (or else the previous one) becomes
175
+ active, and the focus moves to it only if it was in a closed tab. A
176
+ workspace that isn't shown closes them the next time its roster is read.
177
+ An instance respawned under the same name is a new instance: opening it
178
+ opens a new tab.
169
179
 
170
180
  ## Capabilities and spawning
171
181
 
@@ -442,6 +452,10 @@ any other exit code. Closing the tab ends the reconnecting. Reconnecting
442
452
  never stops or restarts the agent on the server: only the local ssh viewer
443
453
  ends.
444
454
 
455
+ A remote instance's tabs close only when its server answers without it
456
+ (retired there, or gone from it), never because the server can't be reached
457
+ or its roster read is out of date.
458
+
445
459
  ## Copy from a terminal
446
460
 
447
461
  Drag over an agent's output to select it, as in any terminal. The selection
@@ -349,6 +349,10 @@ than the server's checked one account and launched with another
349
349
  given the pane's `PATH` as the pane reads it, a relative entry (and an
350
350
  empty one) resolved against the pane's working directory, the home.
351
351
  The command a refusal names keeps the harness's name as declared.
352
+ The Claude probe (`claude plugin list --json`) sets `DISABLE_TELEMETRY=1`
353
+ for its own run, so Claude skips its telemetry flush at exit: that selects
354
+ no account and changes no answer, and no launch, install step or other
355
+ probe gets it.
352
356
  - **The folder-trust check only warns**: `<harness> folder trust: the
353
357
  configuration file this launch will read could not be established
354
358
  (<why, and what would make it readable>); nothing is said about its
@@ -1076,7 +1080,12 @@ oats session attach --home /abs/home --detach-key 'C-\'
1076
1080
  acceptance evidence remain separate contracts.
1077
1081
  - **attach** is interactive and takes no `--json`. It opens a temporary tmux
1078
1082
  session linked to the agent's window alone.
1079
- Closing the viewer leaves the agent running.
1083
+ Closing the viewer leaves the agent running. When the agent's window ends
1084
+ (for example, the instance is stopped or retired), the viewer ends too: it
1085
+ sets tmux's `detach-on-destroy on` for its own session, so a server
1086
+ configured with `detach-on-destroy off` never moves the viewer's client to
1087
+ another session, another agent's terminal. Your own sessions keep your
1088
+ setting.
1080
1089
 
1081
1090
  On tmux 3.2 and later the viewer's tmux client asks for synchronized
1082
1091
  output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
@@ -665,7 +665,13 @@ and acts on every existing session through its recorded socket
665
665
  (`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
666
666
  bytes a terminal sends (`send-keys -l`). A pane program that must show the
667
667
  keys it reads puts its terminal in raw mode first: in cooked mode a control
668
- byte is a signal or an edit, not input.
668
+ byte is a signal or an edit, not input. A signal to the command's process
669
+ group (what a pty hang-up or a C-c delivers) needs the command to be a group
670
+ of its own: the pane's script starts `trap : INT; set -m`, so the shell
671
+ survives to record the status (bash would otherwise end itself after a job
672
+ that INT ended). A `tmux` first on the command's `PATH` times the signal
673
+ against one of the command's tmux calls; it finds the group with
674
+ `ps -o pgid= -p $PPID`.
669
675
  - A test of a full-screen program (`oats tui`) uses a pane of a private
670
676
  server as its terminal (`test/tui-terminal.test.mjs`): the real CLI is typed
671
677
  at an interactive shell in the pane, keys go in with `send-keys`, the screen
@@ -100,7 +100,9 @@ operations in full.
100
100
  becomes quiet after the kernel records a completed confirmation. If Claude
101
101
  ignored the flag, readiness reports `claude-channels-unavailable`.
102
102
  `settings.oats.aweb.delivery: session` or
103
- `settings.oats.aweb.claudeChannelMode: approved` stop the prompt. `oats aweb roster` lists the team:
103
+ `settings.oats.aweb.claudeChannelMode: approved` stop the prompt. Which one a
104
+ host uses, and its host wake broker, are the operator's choices in
105
+ oats.setup's `/oats-host-delivery`. `oats aweb roster` lists the team:
104
106
  its membership certificates and workspaces, one entry per alias with its
105
107
  sources, status and kind (global identities first), and says when either
106
108
  source is incomplete. After `oats server connect`, `oats aweb connect
@@ -9,7 +9,7 @@ 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.10.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.2.0`, `5.2.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.2.0` or `oats-framework/v1.10.2`) and the payload path. An id
54
+ convention (`v5.2.0` or `oats-framework/v1.12.0`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.10.2
77
+ oats.framework: v1.12.0
78
78
  oats.okf: v5.2.0
79
79
  oats.aweb: v1.27.3
80
80
  teams:
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.2", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.0", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.10.2`
362
- resolves to tag `oats-framework/v1.10.2`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.12.0`
362
+ resolves to tag `oats-framework/v1.12.0`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.