@awebai/oats 0.56.0 → 0.57.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 (64) hide show
  1. package/bin/oats.mjs +18 -10
  2. package/docs/configuration.md +17 -27
  3. package/docs/desktop-cli-api.md +59 -3
  4. package/docs/desktop.md +25 -4
  5. package/docs/execution-targets.md +6 -1
  6. package/docs/implementation.md +106 -5
  7. package/docs/integrations.md +8 -4
  8. package/docs/knowledge.md +93 -38
  9. package/docs/official-catalog.md +3 -3
  10. package/docs/packages.md +12 -12
  11. package/docs/release-notes/v0.57.0.md +283 -0
  12. package/docs/release-notes/v0.57.1.md +275 -0
  13. package/docs/schedules.md +8 -3
  14. package/docs/servers.md +18 -0
  15. package/docs/souls-and-instances.md +126 -15
  16. package/docs/tui.md +333 -95
  17. package/docs/workspaces.md +2 -2
  18. package/lib/core.mjs +439 -126
  19. package/lib/instance-lifecycle.mjs +45 -9
  20. package/lib/session-viewer.mjs +29 -4
  21. package/lib/worktree.mjs +23 -2
  22. package/package-catalog.json +2 -2
  23. package/package.json +1 -1
  24. package/packages/client/cli-adapter.mjs +9 -7
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/composed-gate.mjs +34 -0
  27. package/packages/client/inspect-boundary.mjs +157 -0
  28. package/packages/client/inspect-cache.mjs +86 -0
  29. package/packages/client/instance-lifecycle.mjs +10 -3
  30. package/packages/client/keyed-catalog.mjs +132 -0
  31. package/packages/client/launch-prompt-outcome.mjs +1 -1
  32. package/packages/client/launch-view.mjs +46 -0
  33. package/packages/client/session-attach.mjs +7 -5
  34. package/packages/client/soul-catalog.mjs +77 -0
  35. package/packages/client/soul-colors.mjs +31 -0
  36. package/packages/client/soul-facts.mjs +85 -0
  37. package/packages/client/soul-rows.mjs +48 -0
  38. package/packages/client/spawn-apply-cli.mjs +11 -6
  39. package/packages/client/spawn-apply.mjs +212 -0
  40. package/packages/client/spawn-messages.mjs +131 -85
  41. package/packages/client/spawn-preview-contract.mjs +3 -0
  42. package/packages/client/spawn-preview-facts.mjs +119 -0
  43. package/packages/client/spawn-preview.mjs +152 -0
  44. package/packages/client/spawn-transaction.mjs +136 -0
  45. package/packages/tui/README.md +43 -13
  46. package/packages/tui/lib/actions.mjs +18 -2
  47. package/packages/tui/lib/client.mjs +4 -0
  48. package/packages/tui/lib/config.mjs +9 -14
  49. package/packages/tui/lib/main.mjs +241 -55
  50. package/packages/tui/lib/model.mjs +230 -29
  51. package/packages/tui/lib/panel.mjs +955 -0
  52. package/packages/tui/lib/read.mjs +134 -24
  53. package/packages/tui/lib/store.mjs +184 -31
  54. package/packages/tui/lib/term/capture.mjs +260 -0
  55. package/packages/tui/lib/term/screen.mjs +44 -8
  56. package/packages/tui/lib/term/style.mjs +78 -6
  57. package/packages/tui/lib/term/text.mjs +24 -4
  58. package/packages/tui/lib/term/through.mjs +213 -0
  59. package/packages/tui/lib/term/tty.mjs +7 -60
  60. package/packages/tui/lib/views/act.mjs +85 -0
  61. package/packages/tui/lib/views/frame.mjs +153 -37
  62. package/packages/tui/lib/views/help.mjs +22 -14
  63. package/skills/oats-getting-started/SKILL.md +4 -3
  64. package/packages/tui/lib/open.mjs +0 -45
package/bin/oats.mjs CHANGED
@@ -2936,7 +2936,7 @@ async function spawnCmd() {
2936
2936
  ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
2937
2937
  // Directory execution uses deployment configuration, not an ambient Git
2938
2938
  // checkout (especially when invoked via --dir from a source instance).
2939
- // An attached instance's repository is its work tree owner's (derived by the kernel).
2939
+ // An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
2940
2940
  repo: preparedRepo !== undefined ? preparedRepo : ["directory", "attached"].includes(requestedWork || agent.work)
2941
2941
  ? repo : repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
2942
2942
  work: requestedWork, workDir, harness: harnessFlag(), backend, yolo, model: flag("model"), branch,
@@ -3090,13 +3090,15 @@ function retireCmd() {
3090
3090
  revalidate = () => {
3091
3091
  try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
3092
3092
  if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
3093
- return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
3093
+ return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
3094
3094
  };
3095
3095
  } else {
3096
3096
  // A plain or --self retire reads its recorded children the same way: under the claim, as they
3097
3097
  // are when the retire starts (an earlier retire that kept the home has repaired lineage by
3098
3098
  // then), and none when there are none.
3099
- revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
3099
+ // The instances the plan lists under `ambiguous` go with them: the retire does not act on
3100
+ // them, and says what it left the ones attached to a tree it moved or removed with.
3101
+ revalidate = () => { const recorded = descendantsOf(root, name); return { ...(recorded.length ? { children: recorded } : {}), ...(recorded.ambiguous?.length ? { ambiguous: recorded.ambiguous } : {}) }; };
3100
3102
  }
3101
3103
  let r;
3102
3104
  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
@@ -3155,9 +3157,11 @@ function retireCmd() {
3155
3157
  process.exit(1);
3156
3158
  }
3157
3159
  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
3158
- // An attached child the retire repointed to the retained worktree (#718), as its link now reads.
3159
- const followsWorktree = (k) => { if (r.retention?.worktree !== "retained") return false; try { return readlinkSync(join(k.home, "work")) === r.retention.movedTo; } catch { return false; } };
3160
- for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${followsWorktree(k) ? `; its work now links to the retained worktree ${r.retention.movedTo}` : ""}`);
3160
+ // An attached child the retire repointed to a retained worktree, work/ (#718) or an extra tree
3161
+ // (#964), as its link now reads.
3162
+ const retainedAt = [...(r.retention?.worktree === "retained" ? [r.retention.movedTo] : []), ...(r.extraWorktrees || []).filter((t) => t.outcome === "retained").map((t) => t.movedTo)];
3163
+ const followsWorktree = (k) => { try { const to = readlinkSync(join(k.home, "work")); return retainedAt.includes(to) ? to : null; } catch { return null; } };
3164
+ for (const k of r.childrenStopped || []) { const to = followsWorktree(k); console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${to ? `; its work now links to the retained worktree ${to}` : ""}`); }
3161
3165
  // Preserving work and not saying so leaves the operator believing it is gone,
3162
3166
  // which is most of the harm of deleting it. Name the classes and the path.
3163
3167
  for (const line of workRecoveryLines(r)) console.log(line);
@@ -4665,9 +4669,11 @@ Usage:
4665
4669
  oats tui [--dir <path>] [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md):
4666
4670
  the instances of the workspace of the deployment at or
4667
4671
  above <path> (default: where you are), on this machine
4668
- and on the machines registered here; it changes nothing.
4669
- ? help, w workspaces, q quit. Needs a terminal on stdin and
4670
- stdout and has no --json form; --ascii = ASCII rules and marks
4672
+ and on the machines registered here. Enter opens an agent's
4673
+ terminal; it stops, starts, restarts and retires them after a
4674
+ confirmation. ? help, w workspaces, q quit. Needs a terminal on
4675
+ stdin and stdout and has no --json form; --ascii = ASCII rules
4676
+ and marks
4671
4677
  oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
4672
4678
  --workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
4673
4679
  [--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
@@ -4922,7 +4928,9 @@ Usage:
4922
4928
  again with the same arguments: a no-op; --preview:
4923
4929
  the clone, path, branch, base and hooks, nothing done
4924
4930
  oats worktree remove --purpose <p> [--json] git worktree remove of a tree made by add (a dirty
4925
- tree is refused: E_WORKTREE_DIRTY); the branch is kept
4931
+ tree is refused: E_WORKTREE_DIRTY; so is the work of an
4932
+ attached instance whose session is running or cannot
4933
+ be read: E_CHILDREN_RUNNING); the branch is kept
4926
4934
  oats readiness (--soul <n> | --home <abs>) [--policy] [--json]
4927
4935
  readinessApi 2 for a soul or an instance home:
4928
4936
  installed | configured | member | providers, each
@@ -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
@@ -2542,7 +2542,11 @@ what could not be printed is dropped. Its result:
2542
2542
 
2543
2543
  `remove` answers `{purpose, path, removed: true, rolledBack, branch,
2544
2544
  branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
2545
- `rolledBack` is `false` and `branchKept` is `true`. When it completed an
2545
+ `rolledBack` is `false` and `branchKept` is `true`. When an instance whose
2546
+ session is stopped was [attached](souls-and-instances.md#extra-trees) to the
2547
+ removed tree, `warnings` carries one string for it: `<instance>: its work
2548
+ was <tree>, which was removed; its work link <home>/work now points at a
2549
+ path that is gone`. With no attached instance the answer is what it was. When it completed an
2546
2550
  interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
2547
2551
  whether the branch still exists. The rollback deletes the branch only when
2548
2552
  that add created it, no worktree has it checked out, and it still points at
@@ -2654,6 +2658,7 @@ A failed `add` reports the same facts about its rollback in `details`:
2654
2658
  | `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
2655
2659
  | `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
2656
2660
  | `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
2661
+ | `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
2657
2662
  | `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
2658
2663
  | `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
2659
2664
 
@@ -4337,7 +4342,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4337
4342
  - of other homes: the children as the plan names them (`instance`,
4338
4343
  `agent`, `home`; a child's agent is the name its soul's file gives),
4339
4344
  the edges that could not be followed (`facts.ambiguous`, whole) and the
4340
- children attached to this home's `work/`.
4345
+ instances attached to this home's `work/` and to each of its extra
4346
+ trees, the recorded children and those of a name that is not unique
4347
+ alike: the plan's notes name them (#964).
4341
4348
 
4342
4349
  A key that is derived is bound through what it is derived from:
4343
4350
  `facts.ownWorktree` and `defaults.retainWorktree` (the reading), and
@@ -4538,6 +4545,32 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
4538
4545
  --discard-worktree the worktree is removed and their work link will
4539
4546
  dangle`. It holds for either choice; no other key changes. A relink that
4540
4547
  fails is a string in the receipt's `warnings`.
4548
+ - The note of an extra tree that recorded children are attached to (their
4549
+ `work` is a link to that tree) names them and says what the retire leaves
4550
+ them with. For a tree that would be removed it ends `; attached child
4551
+ instance(s) <names> use it as their work, and their work link would then
4552
+ point at a path that is gone`; for one that would be re-homed, `; attached
4553
+ child instance(s) <names> use it as their work, and the retire repoints
4554
+ their work link to it`. A tree the retire refuses is neither moved nor
4555
+ removed, and its note says nothing of them. Names too long for the note
4556
+ give way to `<n> of the recorded children`. They are strings in `notes`: no
4557
+ key changes. Who is attached to each tree is part of `planRevision`
4558
+ ([what the revision binds](#retire-revision-work)).
4559
+ - The retire does not act on an instance listed under `ambiguous`, and one
4560
+ that is attached to a tree of this home is named with what that leaves it
4561
+ with. An extra tree's note gains a clause of its own, after the one for
4562
+ the recorded children: `; attached instance(s) <names>, listed under
4563
+ ambiguous, use it as their work: the retire does not stop them, and their
4564
+ work link would then point at a path that is gone` for a tree that would
4565
+ be removed, and `…: the retire neither stops them nor repoints their work
4566
+ link, which would then point at a path that is gone (the tree would be at
4567
+ <movedTo>)` for one that would be re-homed. For `work/` it is a note of
4568
+ its own, in a worktree-mode plan: `attached instance(s) <names>, listed
4569
+ under ambiguous, use this home's work/ as their work: the retire neither
4570
+ stops them nor repoints their work link, which will then point at a path
4571
+ that is gone, whether the worktree is retained (the receipt names where)
4572
+ or removed with --discard-worktree`. The note for the recorded children
4573
+ above is unchanged.
4541
4574
  - `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
4542
4575
  (a detached checkout or attached spawn before 0.49.0, #641): it is not a
4543
4576
  branch name, so `facts.work.drift` is `false` for it as well.
@@ -4648,6 +4681,29 @@ A first retire prints the **raw receipt**, not an envelope:
4648
4681
  removed unplanned (OATS 0.52.0; it was `E_PLAN_STALE`, a code that says
4649
4682
  nothing happened, answered after the hooks: #895).
4650
4683
  The key is additive.
4684
+ - `warnings` also says what the retire left the attached children of a tree
4685
+ it moved or removed with, one string per child, for `work/` and for each
4686
+ extra tree. A child that could not be repointed to a retained tree:
4687
+ `<child>: its work link could not be repointed to the retained worktree
4688
+ <movedTo> (<why>) and still points at <link>; repoint it by hand: ln -sfn
4689
+ …`, or `<child>: its attachment changed during the retire, so its work was
4690
+ left as it is now and not repointed to the retained worktree <movedTo>;
4691
+ inspect <home>/work`. A child of a tree the retire removed (a clean extra
4692
+ tree, or `work/` with `--discard-worktree`): `<child>: its work was
4693
+ <tree>, which this retire removed (<why>); its work link <home>/work now
4694
+ points at a path that is gone`. A child that was repointed has no string:
4695
+ the text summary's `child <name>` line says where its work now links. No
4696
+ key is new.
4697
+
4698
+ An attached instance the plan lists under `ambiguous` is not stopped and
4699
+ not repointed, and has a string for each tree that was moved or removed:
4700
+ the sentence above for a removed tree, followed by ` (it records this
4701
+ instance as its parent under a name that is not unique, so the retire did
4702
+ not stop it)`, or, for a re-homed tree, `<instance>: its work was <tree>,
4703
+ which this retire re-homed to <movedTo>; its work link <home>/work was not
4704
+ repointed and now points at a path that is gone (it records … did not stop
4705
+ it); to repoint it by hand: ln -sfn …`. A `--self` retirement's receipt
4706
+ does not carry these strings.
4651
4707
  - `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
4652
4708
  notCopied?, afterHooks?}`, present when a recovery was written. One retire
4653
4709
  writes at most one recovery directory, and `path` is that directory.
@@ -4736,7 +4792,7 @@ nothing is established. A plain or
4736
4792
  always does (`[]` when there are none). One child still running after the
4737
4793
  grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
4738
4794
  `E_INSTANCE_RETIRING`, `E_LIFECYCLE_BUSY`, …), refuses everything: nothing is retired, exit 1,
4739
- `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
4795
+ <a id="retire-children-running"></a>`E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
4740
4796
  `code`, always a [kernel code](#kernel-codes); the message says `still running after a bounded stop`
4741
4797
  only of a child whose row lists processes in `stillRunning`, and `<child> could not be stopped
4742
4798
  (<code>)` of any other, OATS 0.52.0). **`--force` does not bypass it**: `--force` covers incomplete
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
 
@@ -353,10 +363,17 @@ join** says who else may join it. Both are read from the workspace's committed
353
363
  `souls:`; a team nobody may join yet says so. The address (the team on the
354
364
  messaging provider) and the members running in it follow.
355
365
 
356
- The **Setup** tab's List view starts with the workspace's **host**, the
357
- repository that holds `oats-workspace.yaml`, and marks every repository the
358
- workspace trusts for souls and capabilities as a **Member**. The host is a
359
- member too. A legend under the title explains both badges.
366
+ The **Setup** tab's List view is one column. Under the workspace's name, one
367
+ line counts its members (and those that need attention), its packages and the
368
+ state of the lock. The next line says where the workspace is declared. An
369
+ **Overview** says that the workspace's **host**, the repository that holds
370
+ `oats-workspace.yaml`, defines the workspace: its member repositories and its
371
+ packages. **For developers** (folded) explains how a repository becomes a
372
+ member and what each member state means. Then **Shared through Git** lists
373
+ what the workspace declares (Members, with the host first and tagged
374
+ **Host**, Packages and Defaults). **This computer** lists what is not shared:
375
+ this deployment's settings, lock, CLI and instances, the member clones, and
376
+ the machines that run the workspace.
360
377
 
361
378
  ## A workspace's machines
362
379
 
@@ -435,6 +452,10 @@ any other exit code. Closing the tab ends the reconnecting. Reconnecting
435
452
  never stops or restarts the agent on the server: only the local ssh viewer
436
453
  ends.
437
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
+
438
459
  ## Copy from a terminal
439
460
 
440
461
  Drag over an agent's output to select it, as in any terminal. The selection
@@ -1076,7 +1076,12 @@ oats session attach --home /abs/home --detach-key 'C-\'
1076
1076
  acceptance evidence remain separate contracts.
1077
1077
  - **attach** is interactive and takes no `--json`. It opens a temporary tmux
1078
1078
  session linked to the agent's window alone.
1079
- Closing the viewer leaves the agent running.
1079
+ Closing the viewer leaves the agent running. When the agent's window ends
1080
+ (for example, the instance is stopped or retired), the viewer ends too: it
1081
+ sets tmux's `detach-on-destroy on` for its own session, so a server
1082
+ configured with `detach-on-destroy off` never moves the viewer's client to
1083
+ another session, another agent's terminal. Your own sessions keep your
1084
+ setting.
1080
1085
 
1081
1086
  On tmux 3.2 and later the viewer's tmux client asks for synchronized
1082
1087
  output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
@@ -79,7 +79,7 @@ and the rules its tests pin.
79
79
  | `souls/` | this repository's own souls (a workspace member) |
80
80
  | `docs/` | the reference pages, schemas, design records and release notes |
81
81
  | `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
82
- | `scripts/` | the test runner (`run-tests.mjs`) and its reporter of unasserted warnings, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane and the assembly of release-notes entries |
82
+ | `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 and the assembly of release-notes entries |
83
83
  | `test/` | the kernel and CLI suites, with their fixtures |
84
84
 
85
85
  ## Kernel modules
@@ -443,7 +443,7 @@ scaling by call count.
443
443
 
444
444
  | command | what it checks |
445
445
  |---|---|
446
- | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output |
446
+ | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs`, which also fails the run when an `oats: warning:` line is left in a test file's output, or a test file leaves something in its temporary directory |
447
447
  | `npm run test:session` | the suites that have followed a variable of the session that runs them, with every such variable set to a value that cannot work (`scripts/test-session-inheritance.mjs`) |
448
448
  | `npm run check` | syntax of every shipped file |
449
449
  | `npm run check:pi` | the pi adapter's TypeScript |
@@ -472,6 +472,65 @@ its own; a line a child wrote into a pipe the test reads is the test's, and
472
472
  does not count. `test/unasserted-warnings.test.mjs` pins the rule with nested
473
473
  runs.
474
474
 
475
+ **A test file leaves nothing behind.** Where a test makes a directory, it
476
+ registers the removal there (`t.after`, or a list the file empties when it has
477
+ ended), so a test that fails or times out removes it too; and a fixture is
478
+ ended, not only removed (`v2Deployment({ t })`, below). A file whose setup is
479
+ shared by its tests does that setup in a `test.before` hook, not at its top
480
+ level: a file that throws while it loads runs no hook, `test.after` included,
481
+ so a step that failed would leave what the steps before it made
482
+ (test/tui-acts.test.mjs). On a development host
483
+ the leftovers of runs that passed once used up the inodes of the temporary
484
+ file system, and every test that makes a directory then failed with "no
485
+ space", whatever the change under test (awebai/oats#1025). The root run holds
486
+ the rule:
487
+
488
+ - `scripts/run-tests.mjs` makes one directory for the run, and each test
489
+ file's process is preloaded with `scripts/test-file-tmpdir.mjs`, which gives
490
+ the file a directory of its own inside it: as `TMPDIR`, and as
491
+ `TMUX_TMPDIR`, which is tmux's default place. A tmux client that runs with
492
+ no `TMUX_TMPDIR` of a fixture makes its socket directory there, where the
493
+ run sees it, instead of reaching the host's default server. `TMUX` is not
494
+ changed: a client that names no server (no `-L` or `-S`) and inherits
495
+ `TMUX`, as in a run from a session inside tmux, still uses that session's
496
+ server and makes nothing the run sees. The run names its directory to the
497
+ preload in `OATS_TEST_RUN_DIR`, and the preload takes that variable out of
498
+ the file's environment before any code of the file runs. No test sees it,
499
+ nor any process a test starts.
500
+ - When the run has ended it reads each file's directory. If one is not empty
501
+ the run fails, even if every test passed, and names each file and what it
502
+ left.
503
+ - One name is not counted, by its exact name: `node-compile-cache`. Node makes
504
+ it under the temporary directory when a tool a test starts asks for a
505
+ compile cache (npm does), so under the root run it is made in the file's
506
+ own directory and goes with the run's. It is Node's, not something the file
507
+ left. A developer's shared cache, the one in the platform's temporary
508
+ directory, is neither used nor removed by a root run; a file run alone uses
509
+ it as before, and no test deletes it. The run's processes do not inherit
510
+ `NODE_COMPILE_CACHE` either: with a developer's set, no process of the run
511
+ writes into that cache.
512
+ - The run's directory is removed when the run has ended, whatever was left in
513
+ it. A run that is killed leaves that one directory: `ot-*` under the
514
+ temporary directory, or under `/tmp` when that path is longer than 20
515
+ characters.
516
+ - A file's directory, `<parent>/ot-XXXXXX/<n>`, takes from a socket's path
517
+ what `/tmp` alone did not. ssh binds a control socket at
518
+ `<OATS_HOME_DIR>/ssh/<40 hex>` plus a 17-byte suffix, in 104 bytes: 86 for
519
+ the path. A fixture whose `OATS_HOME_DIR` holds it keeps it short: a
520
+ 5-character prefix and `<base>/h` (`o-up-`) come to 85 bytes when the
521
+ run's parent resolves to at most 12 characters, as `/tmp` does on Linux
522
+ and on macOS (`/private/tmp`), with up to 999 files. Longer, the kernel
523
+ warns that the path is too long and runs ssh without connection reuse,
524
+ which fails the run as any unasserted warning does: run the suite with a
525
+ `TMPDIR` of `/tmp` then.
526
+ - The run sees what is made under the file's temporary directory: by the
527
+ file's process, by a process it starts with that environment, and by the
528
+ fixture helpers (`fixtureBase` and `privateTmuxTmpdir`, below), in a
529
+ process the test started with `inheritedEnv()` too. It does not see what a
530
+ process makes when a test built its environment without `TMPDIR`.
531
+
532
+ `test/left-behind.test.mjs` pins the rule with nested runs.
533
+
475
534
  Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
476
535
  load with only Desktop dependencies installed. The release builds Desktop that
477
536
  way: its `desktop-build` job installs and tests inside `packages/desktop` and
@@ -535,6 +594,31 @@ which fails with `ENOTEMPTY` (awebai/oats#451). So:
535
594
 
536
595
  Never paper over such a race with a retry around the cleanup.
537
596
 
597
+ A process that a test kills can leave such a writer too. Killing a process
598
+ that starts processes of its own ends that one alone: a child it had just
599
+ started goes on by itself and writes where it was told to after its parent has
600
+ gone, and it has not run a line yet, so it has announced itself nowhere. The
601
+ Desktop server's tests are the case: the server runs the CLI, and a fake CLI
602
+ writes its log in the test's directory. Such a test starts the process with
603
+ `startGroup` and closes it with `closeGroup`
604
+ (`test/helpers/process-group.mjs`):
605
+
606
+ - `startGroup` starts it as `spawn` does, as the leader of a process group of
607
+ its own, which holds whatever it starts.
608
+ - `closeGroup` kills that one process and waits until its group, that process
609
+ among it, is empty. The bound, 30 s, covers the whole close from its start:
610
+ a group that outlives it fails the test and names every process that is
611
+ left, the killed one too if it still runs. Only then does the test remove
612
+ what they worked in.
613
+ - A group of its own is not in the terminal's foreground group, so an
614
+ interrupt of the test's process does not reach it. The helper passes it on:
615
+ on `SIGINT`, `SIGTERM` or `SIGHUP` it kills every group that process
616
+ started, whole, and then the signal ends the process as it would have. A
617
+ test process killed with `SIGKILL` passes nothing on: what it started stays,
618
+ as any child of a process killed that way does.
619
+
620
+ `test/process-group.test.mjs` pins the three.
621
+
538
622
  A test never reaches the operator's tmux. The kernel creates sessions on the
539
623
  server named `oats` (`tmux -L oats`), which tmux resolves under `TMUX_TMPDIR`,
540
624
  and acts on every existing session through its recorded socket
@@ -581,7 +665,13 @@ and acts on every existing session through its recorded socket
581
665
  (`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
582
666
  bytes a terminal sends (`send-keys -l`). A pane program that must show the
583
667
  keys it reads puts its terminal in raw mode first: in cooked mode a control
584
- 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`.
585
675
  - A test of a full-screen program (`oats tui`) uses a pane of a private
586
676
  server as its terminal (`test/tui-terminal.test.mjs`): the real CLI is typed
587
677
  at an interactive shell in the pane, keys go in with `send-keys`, the screen
@@ -624,7 +714,12 @@ inherits it (awebai/oats#816):
624
714
  - **A short base.** `fixtureBase(prefix)` makes the fixture directory under
625
715
  the platform's temporary directory, or under `/tmp` when that is longer than
626
716
  20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
627
- realpath, taken once.
717
+ realpath, taken once. Under the root run the temporary directory is the
718
+ test file's own (above), and is used whatever its length, so that nothing a
719
+ fixture makes is outside what the run reads; the run keeps it short. The
720
+ helper knows it by what the runner makes (`ot-XXXXXX/<n>`, with the file
721
+ `<n>.file` beside it) and by no variable, so a process a test starts with
722
+ `inheritedEnv()` uses it too.
628
723
  - **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
629
724
  name or branch segment) and `pathOfLength(base, n)` (an absolute path under
630
725
  the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
@@ -743,4 +838,10 @@ inherits it (awebai/oats#816):
743
838
  still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
744
839
  and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
745
840
  `t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
746
- built removes its base itself.
841
+ built removes its base itself. Removing the base is not ending the fixture:
842
+ only `fx.cleanup` stops the fixture's tmux server, checks for leftover
843
+ processes and removes the fixture's private `TMUX_TMPDIR`
844
+ (`privateTmuxTmpdir()`), which is made beside the base and never inside it.
845
+ So a fixture that was made and never ended leaves that directory, and the
846
+ root run fails on it (awebai/oats#1025). A file that collects its fixtures
847
+ ends each of them in the hook that used to remove their bases.
@@ -40,7 +40,7 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.1.0
43
+ oats.okf: v5.2.0
44
44
  oats.aweb: v1.27.3
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
@@ -84,8 +84,10 @@ operations in full.
84
84
  | `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
85
85
 
86
86
  - **`oats.okf`** consults the soul's external OKF bases, keeps instance
87
- knowledge, and briefs eligible working instances to propose durable claims
88
- at checkpoints by directly spawning `oats.okf/knowledge-harvester`. The
87
+ knowledge, and teaches the harvest duty in its IMPORTANT inject block and
88
+ compulsory `okf-propose` skill, not the task briefing. Eligible instances
89
+ propose durable claims at finished tasks or PR hand-overs by directly
90
+ spawning `oats.okf/knowledge-harvester`. The
89
91
  soul-only `knowledge: { harvest: off }` forbids harvest while retaining
90
92
  consultation. No host switch or automatic transcript/retire capture remains;
91
93
  `knowledge-maintainer` reviews the resulting Git PRs.
@@ -98,7 +100,9 @@ operations in full.
98
100
  becomes quiet after the kernel records a completed confirmation. If Claude
99
101
  ignored the flag, readiness reports `claude-channels-unavailable`.
100
102
  `settings.oats.aweb.delivery: session` or
101
- `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:
102
106
  its membership certificates and workspaces, one entry per alias with its
103
107
  sources, status and kind (global identities first), and says when either
104
108
  source is incomplete. After `oats server connect`, `oats aweb connect