@awebai/oats 0.55.1 → 0.57.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 (82) hide show
  1. package/bin/oats.mjs +96 -72
  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 +375 -37
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +65 -11
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +153 -11
  10. package/docs/integrations.md +5 -3
  11. package/docs/knowledge.md +117 -43
  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/release-notes/v0.57.0.md +283 -0
  17. package/docs/schedules.md +8 -3
  18. package/docs/servers.md +21 -5
  19. package/docs/souls-and-instances.md +134 -19
  20. package/docs/tui.md +215 -31
  21. package/docs/upgrading.md +4 -1
  22. package/docs/workspaces.md +26 -6
  23. package/lib/automations.mjs +3 -4
  24. package/lib/bounded-read.mjs +18 -0
  25. package/lib/capability-show.mjs +13 -2
  26. package/lib/claim.mjs +3 -4
  27. package/lib/core.mjs +919 -278
  28. package/lib/errors.mjs +39 -0
  29. package/lib/harness-trust-write.mjs +119 -40
  30. package/lib/harness-trust.mjs +31 -18
  31. package/lib/instance-inspect.mjs +160 -11
  32. package/lib/instance-lifecycle.mjs +90 -37
  33. package/lib/packages.mjs +8 -5
  34. package/lib/pi-bridge.mjs +18 -19
  35. package/lib/remote.mjs +88 -51
  36. package/lib/retire-output.mjs +9 -4
  37. package/lib/schedule.mjs +3 -4
  38. package/lib/servers.mjs +39 -6
  39. package/lib/session-viewer.mjs +25 -1
  40. package/lib/triggers.mjs +3 -4
  41. package/lib/workspace.mjs +6 -6
  42. package/lib/worktree.mjs +33 -8
  43. package/lib/write-through-private-file.mjs +26 -0
  44. package/package-catalog.json +2 -2
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +108 -13
  47. package/packages/client/cli-locator.mjs +16 -14
  48. package/packages/client/deployment-panel.mjs +4 -3
  49. package/packages/client/display-text.mjs +2 -1
  50. package/packages/client/instance-events-contract.mjs +4 -3
  51. package/packages/client/instance-lifecycle.mjs +235 -0
  52. package/packages/client/instance-presentation.mjs +9 -0
  53. package/packages/client/instance-tree.mjs +10 -8
  54. package/packages/client/kernel-lines.mjs +3 -3
  55. package/packages/client/launch-contract.mjs +11 -0
  56. package/packages/client/launch-prompt-outcome.mjs +1 -1
  57. package/packages/client/lifecycle-cli.mjs +12 -6
  58. package/packages/client/lifecycle-confirmation.mjs +407 -0
  59. package/packages/client/lifecycle-contract.mjs +6 -2
  60. package/packages/client/own-codes.mjs +1 -0
  61. package/packages/client/panel-views.mjs +39 -2
  62. package/packages/client/readiness-contract.mjs +2 -2
  63. package/packages/client/remote-roster.mjs +50 -5
  64. package/packages/client/roster-sections.mjs +3 -3
  65. package/packages/client/session-start.mjs +98 -0
  66. package/packages/client/start-gate.mjs +46 -0
  67. package/packages/client/start-messages.mjs +17 -0
  68. package/packages/client/workspace-views.mjs +2 -2
  69. package/packages/tui/README.md +21 -8
  70. package/packages/tui/lib/actions.mjs +11 -2
  71. package/packages/tui/lib/client.mjs +9 -2
  72. package/packages/tui/lib/config.mjs +39 -9
  73. package/packages/tui/lib/main.mjs +168 -20
  74. package/packages/tui/lib/model.mjs +315 -13
  75. package/packages/tui/lib/open.mjs +45 -0
  76. package/packages/tui/lib/read.mjs +171 -16
  77. package/packages/tui/lib/store.mjs +171 -10
  78. package/packages/tui/lib/term/tty.mjs +71 -12
  79. package/packages/tui/lib/views/act.mjs +85 -0
  80. package/packages/tui/lib/views/frame.mjs +145 -33
  81. package/packages/tui/lib/views/help.mjs +46 -11
  82. package/skills/oats-getting-started/SKILL.md +6 -3
@@ -27,19 +27,30 @@ The command writes only the canonical deployment root's native trust leaf:
27
27
  It writes that leaf into every configuration file a launch of the deployment
28
28
  reads. The targets of each selected harness are:
29
29
 
30
- - the ambient file, selected by the operator's own `CLAUDE_CONFIG_DIR` or
31
- `CODEX_HOME`, else the default above;
30
+ - the ambient file: the one a launch of this deployment with no launch
31
+ configuration reads. It is read as every check of a launch reads it
32
+ ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)):
33
+ the `CLAUDE_CONFIG_DIR` or `CODEX_HOME` of the deployment's tmux
34
+ session, else of the OATS tmux server, else the default above under that
35
+ session's or server's `HOME`. It is not the operator's own shell's when
36
+ the server holds another account;
32
37
  - one file for each launch configuration (`launch-configs:` in the
33
38
  deployment's `oats-local.yaml`) of that harness whose `env` sets
34
39
  `CLAUDE_CONFIG_DIR` (claude) or `CODEX_HOME` (codex), as a literal or a
35
40
  `{fromEnv: NAME}` reference resolved from the environment the command runs
36
- in.
41
+ in;
42
+ - one file for each launch configuration of that harness whose `env` sets
43
+ `HOME` and not that variable, when its launch has no such variable at
44
+ all (the session and the server set none either): the default file above
45
+ under that `HOME`, which is the file its launch reads. When the session
46
+ or the server sets the variable, that launch reads the ambient file, and
47
+ the configuration has no file of its own.
37
48
 
38
49
  Targets with the same canonical directory are one file. Each plan entry says
39
50
  whether it is the ambient file (`ambient`) and which launch configurations
40
51
  use it (`launchConfigs`). A launch configuration whose reference is not set,
41
- whose path is not absolute, or whose directory does not exist is a named
42
- `problem` on its entry. OATS never creates a harness configuration directory:
52
+ whose path is not absolute or selects no usable directory, or whose directory does not exist is a named
53
+ `problem` on its entry, for a `HOME` as for the harness's own variable. OATS never creates a harness configuration directory:
43
54
  create it, or start the harness with it once, then rerun. A missing ambient
44
55
  directory (`~/.codex` for a user who has never run Codex, for example) means
45
56
  the harness has not run as this user: with `--harness all` that harness's
@@ -49,6 +60,42 @@ whole plan before a write, as an unsupported file does.
49
60
  Each file is verified through the reader under the environment that selects
50
61
  it.
51
62
 
63
+ The plan shows what will be written before anything is. `warnings` says
64
+ what selects the ambient file when a selector does (`CLAUDE_CONFIG_DIR
65
+ selects <dir> (the global CLAUDE_CONFIG_DIR of the OATS tmux server
66
+ (<socket>)); effective file <file>`). Four cases have no pane to read:
67
+
68
+ - **No OATS tmux server runs.** The command does not start one, and does not
69
+ start your login shell to find out what one would hold. The ambient file
70
+ is then the operator's own, and `warnings` says so: `claude: the pane's
71
+ environment is not established until a spawn starts the OATS tmux server
72
+ (none runs); read instead: this process's CLAUDE_CONFIG_DIR (not set),
73
+ this process's HOME`.
74
+ - **The command has no tmux on its `PATH`.** It makes no read, and no
75
+ prediction: the ambient file is the operator's own, as with no server, and
76
+ `warnings` says so: `claude: the pane's environment is not established:
77
+ this process has no tmux on its PATH to read the OATS tmux server with;
78
+ read instead: …`. If a server does run on this host, run the command with
79
+ a `PATH` that holds tmux, so that it writes for the file launches read.
80
+ - **tmux could not say whether the server runs.** `tmux -L oats
81
+ list-sessions` was refused or cut off. That is a read that failed, not
82
+ "no server runs": one may run, under another account. The ambient target is `refused`, nothing is written, to
83
+ any file, and the command answers `E_RUNTIME_ENDPOINT_UNKNOWN` with what
84
+ failed: `… could not read the OATS tmux server for session <name>:
85
+ <failure>. What has to answer, as this process: \`tmux -L oats
86
+ list-sessions\`. A server that could not be asked may run under another
87
+ account than this process's, so this process's file is not written in its
88
+ place`. Run the command where that tmux command answers.
89
+ - **A server runs and its environment cannot be read** (the read fails, or
90
+ the value holds a `$`, a line break or a character tmux prints encoded;
91
+ `HOME` cleared or missing when there is no selector). The ambient target
92
+ is `refused` with a `problem` that names which name, where it was read
93
+ and what would make it readable, and nothing is written, to any file: the
94
+ command answers `E_RUNTIME_ENDPOINT_UNKNOWN`. It never writes to a file
95
+ guessed from the operator's shell. When a launch configuration's target is
96
+ refused as well, the code is `E_CONFIG_BROKEN`, as for that target alone,
97
+ and the details hold both.
98
+
52
99
  Nonempty override directories must be absolute. Directory aliases are resolved;
53
100
  symlink/nonregular/hardlinked leaves, foreign ownership and ACLs refuse. On Linux, GNU ls's single `.` security-context marker is accepted;
54
101
  the context must be readable, match the same-directory candidate before replacement,
@@ -59,8 +106,8 @@ they are not a live SELinux-host qualification.
59
106
 
60
107
  On macOS, any extended-attribute (`@`) or ACL (`+`) marker deliberately refuses,
61
108
  including `com.apple.provenance`. This v1 writer does not copy or remove those
62
- attributes. Inspect the selected file; a refusal never authorizes stripping its
63
- metadata automatically. Existing file permissions are preserved.
109
+ attributes. See [When the writer refuses](#when-the-writer-refuses); a refusal
110
+ never authorizes stripping its metadata automatically. Existing file permissions are preserved.
64
111
  No configuration directory is ever created; a new file uses 0600. The plan shows the effective file,
65
112
  semantic key, current/desired trust scalar, byte digests and override provenance;
66
113
  it never returns other config values or credentials.
@@ -71,6 +118,55 @@ records. Existing Codex root-trust/yolo per-invocation overrides are unchanged.
71
118
  This command does not enable development-channel prompt consent, change permission
72
119
  mode, authenticate, install a plugin, or establish model/channel readiness.
73
120
 
121
+ ## When the writer refuses
122
+
123
+ The writer refuses a configuration file it cannot replace exactly as it found
124
+ it, and then writes nothing at all. The refused entry's `problem` names the
125
+ file and the check that refused it, in fixed wording; it never repeats the
126
+ file's content or a parser message:
127
+
128
+ | `problem` says the file | Meaning |
129
+ | --- | --- |
130
+ | is not a regular file (a symbolic link, directory or other type) | The path is a link, a directory or another type; only a plain file is replaced. |
131
+ | has more than one hard link | Replacing it would split it from its other names. |
132
+ | is owned by another user | Only a file the current user owns is replaced. |
133
+ | has setuid, setgid or sticky bits set | Special mode bits are not carried across a replacement. |
134
+ | has an extended-attribute (@) or ACL (+) marker in ls ... | macOS extended attributes (such as `com.apple.provenance`) or an ACL, or an ACL on Linux: this writer neither copies nor removes them. The `problem` also gives the way forward, below. |
135
+ | has a Linux security context that cannot be read | `ls -Z` gave no usable context for a file whose `ls` mode shows one. |
136
+ | its metadata could not be read (the ls probe failed or its answer is not recognized) | `ls` failed, or printed a mode this writer does not recognize. |
137
+ | changed while it was being read | Another writer replaced it during the read; rerun. |
138
+ | is not in a usable configuration directory (a path that is not a directory, or one with no existing ancestor) | The directory that should hold the file is not a directory. Target resolution normally reports this first, as the named problem below. |
139
+ | is larger than 8 MiB | The file is over the size the writer reads. |
140
+ | is not valid UTF-8 | The bytes do not decode losslessly. |
141
+ | is not in the supported format (see "Qualified scope and formats" in docs/harness-trust.md) | The editor or the trust reader does not support its shape; see [Qualified scope and formats](#qualified-scope-and-formats). |
142
+ | could not be read (`<errno code>`) | Any other read error, by its code alone (for example `EACCES`). |
143
+
144
+ When the `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `HOME` that selects the ambient
145
+ file (read as described above) is not an absolute path, or selects no usable
146
+ directory, the ambient entry's `problem` names that variable and where it was
147
+ read, never its value: `the file a claude launch with no launch configuration
148
+ reads could not be established: <where> is not an absolute path`.
149
+ Launch-configuration, missing-directory and unreadable-environment problems
150
+ are described above.
151
+
152
+ **The macOS marker.** On macOS, a configuration file that Claude rewrites can
153
+ carry `com.apple.provenance`, and the writer refuses it. Do not edit the file or
154
+ its attributes. Instead, start a Claude session with the configuration
155
+ directory the launch uses (the same `CLAUDE_CONFIG_DIR`, or none for
156
+ `~/.claude.json`), in the deployment folder, and accept Claude's own
157
+ folder-trust dialog there. The `harness-trust` item of `oats readiness` is the
158
+ check that this is met: it reads the file without the writer's metadata
159
+ checks. Until it passes, spawns in that deployment warn with the line shown in
160
+ [Launch-time checks and readiness](#launch-time-checks-and-readiness). The
161
+ same applies to an ACL marker on Linux, and to Codex with its own trust prompt
162
+ and `CODEX_HOME`.
163
+
164
+ **A refusal does not block the rest of an upgrade.** Only
165
+ `oats harness trust` runs the writer. `oats sync`, `oats readiness` and
166
+ `oats doctor` never call it and start no session; the `harness-trust` item of
167
+ readiness is never required, so a missing trust does not make the deployment
168
+ not ready.
169
+
74
170
  ## Qualified scope and formats
75
171
 
76
172
  Claude 2.1.289 darwin-arm64 was qualified against pinned native source and a
@@ -118,19 +214,40 @@ do not automatically write a second root or answer a trust dialog.
118
214
 
119
215
  Spawn, `session start|restart`, `launch-config preview` and `oats readiness`
120
216
  read folder trust from the file the launch's own environment selects: the
121
- host's environment plus the launch configuration's `env`. Codex's
122
- per-invocation home trust follows the same file. They never write it.
217
+ launch configuration's `env`, else the environment the launch's tmux pane
218
+ will have, never the calling process's in its place
219
+ ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)).
220
+ Codex's per-invocation home trust follows the same file. They never write
221
+ it.
123
222
 
124
223
  Readiness reports one `harness-trust` item (in `checks.configured`, never
125
224
  required) for the launch a home recorded, or for the launch a soul selects.
126
225
  It passes, naming the file, when that file trusts the deployment root or an
127
226
  ancestor (for Claude, up to a Git boundary; a yolo Codex launch always
128
- passes). Otherwise it warns, and the spawn warns with the same text:
227
+ passes). Otherwise it warns, and the spawn warns with the same text, which
228
+ names where the launch gets the file from:
129
229
 
130
230
  ```text
131
- <harness> folder trust is not established in <file>: oats harness trust --dir <deployment>
231
+ <harness> folder trust is not established in <file> (<where from>): oats harness trust --dir <deployment>
132
232
  ```
133
233
 
234
+ `<where from>` is, for example, `the CLAUDE_CONFIG_DIR of launch
235
+ configuration work`, `the CODEX_HOME of tmux session agents` or `under the
236
+ global HOME of the OATS tmux server (<socket>)`. Two more answers:
237
+
238
+ - **The pane's environment could not be read** (a spawn or a start, and
239
+ readiness with a server running): `<harness> folder trust: the
240
+ configuration file this launch will read could not be established (<why,
241
+ and what would make it readable>); nothing is said about its trust`. The
242
+ readiness item is `unknown`, with `file` null.
243
+ - **No pane to read** (readiness with no server running, a spawn with
244
+ `--no-launch`): the file read is the calling process's, and `<where
245
+ from>` says so (`the pane's environment is not established until a spawn
246
+ starts the OATS tmux server (none runs); read instead: this process's
247
+ CODEX_HOME (not set), this process's HOME`). The readiness item is then
248
+ `unknown` whether or not that file establishes trust; a spawn with
249
+ `--no-launch` warns only when it does not.
250
+
134
251
  A missing root entry does not prove that the harness will prompt (a native
135
252
  gate can skip the question), so neither says the session will stop. A launch
136
253
  configuration whose reference is not set on this host is named instead of a
@@ -79,19 +79,19 @@ 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
86
86
 
87
87
  | module | owns |
88
88
  |---|---|
89
- | `remote.mjs` | repo refs, reading Git remotes, content digests; `redactUrl` owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
89
+ | `remote.mjs` | repo refs, reading Git remotes, content digests; `displayRepoRef` and `displayDiagnosticText` select reference-value and kernel-prose contexts for one private renderer, which owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
90
90
  | `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
91
91
  | `workspace.mjs` | workspace, membership and soul files; discovery |
92
92
  | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
93
93
  | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
94
- | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit |
94
+ | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally |
95
95
  | `materialize.mjs` | copying modules into a home and composing it |
96
96
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
97
97
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
@@ -112,6 +112,7 @@ and the rules its tests pin.
112
112
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
113
113
  | `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
114
114
  | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire` and `oats instance stop --apply` (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
115
+ | `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, an exact mode, a failed removal reported, a sync) keeps its own code |
115
116
  | `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL. Two questions, two functions: `processStart` says whose a pid is (a zombie still holds its pid and start, which is what proves a recorded process group), `processLiveness` says whether the `oats` command a record names can still act (a zombie cannot: it is gone). Ask `processLiveness` only about an `oats` command's own process, never about a hook's or a harness's pid. `runPs` is the one way the kernel calls `ps` where an identity is read: the program, the fixed environment and how the answer is classified. `isStartToken` says the shape of a start token, once, beside its writer: it decides what of a record may be shown (`claim.mjs` `shownHolder`, `unknownGroupNote`), never whether a process lives |
116
117
  | `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS`), never from the caller's `PATH`. `ps` runs on the same directories: `worktree-hooks.mjs`'s `PS_ENV` takes its `PATH` from them |
117
118
  | `tmux-server-scope.mjs` | whether the OATS tmux server starts in a systemd scope of its own: the creator's cgroup judged (Linux, inside a `.service`, unified hierarchy), the scope's name and the warning when it cannot |
@@ -125,10 +126,10 @@ and the rules its tests pin.
125
126
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
126
127
  | `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
127
128
  | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts, one Enter only on equality with a tolerance entry |
128
- | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
129
+ | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches; the table of the variable that moves each harness's folder (`HARNESS_FOLDER_VAR`) and the one reader of a launch configuration's (`launchConfigFolder`), used by the trust code, `pi-bridge.mjs` and `core.mjs`: it reads only files and imports none of them. What a launch's pane will have for those variables, `PATH` and `HOME` is `launchEnvironment` in `core.mjs`, the one answer every check of a launch reads ([execution-targets.md](execution-targets.md#the-checks-read-the-pane)); it carries the names the launch removes (`removedLaunchEnv`: declared by its capabilities, not in their payload), which `launchEffectiveEnv` leaves out and the window command (`paneCommand`) unsets ([capabilities.md](capabilities.md#a-declared-name-is-the-providers)) |
129
130
  | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
130
131
  | `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
131
- | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings and the plan `oats update` runs ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
132
+ | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings, and the plan `oats update` runs with its line that the Desktop goes first ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
132
133
 
133
134
  The schedule registry stores explicit concurrency caps, leaving the schedule
134
135
  cap absent for its effective default of five. `readRegistry()` is a pure,
@@ -192,6 +193,30 @@ The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
192
193
  a provider. Provider behaviour lives in capabilities; the kernel supplies
193
194
  their contracts ([layers](layers.md)).
194
195
 
196
+ ### Remote diagnostic display
197
+
198
+ `lib/remote.mjs` exposes explicit display entry points for direct module callers:
199
+
200
+ - `displayRepoRef(value, { pinned = false, rejectedValue = false } = {})`
201
+ renders selected reference values, including nested keys and values. For a
202
+ pinned source, `pinned: true` splits the complete `<ref>@<commit>` value;
203
+ `pinned: { ref, commit }` supplies its original components. Both forms
204
+ require a recognised reference and a 40-hex commit, with no plain fallback.
205
+ - `displayDiagnosticText(value, source = null, { fragment = false, refusal = false, substitute = true, rejectedValue = false } = {})`
206
+ renders kernel-authored diagnostic prose using its selected original source
207
+ values, including fragments and refusal explanations.
208
+ - `scrubGitLine(line, url = null)` handles Git-authored lines through the
209
+ [whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics)
210
+ before control and length formatting.
211
+
212
+ All three delegate to the existing private `renderRemoteDisplay`; construction
213
+ and withholding policy live there. Each public entry fixes its context and
214
+ extracts only its named options, so an extra option cannot select Git-line
215
+ handling through either of the other entry points. These exports are for
216
+ internal/direct-module callers: `lib/remote.mjs` is not in the package export
217
+ map. Call sites choose the entry matching the origin of the value or prose;
218
+ there is no implicit-context `redactUrl` export or compatibility shim.
219
+
195
220
  ### The remote read path
196
221
 
197
222
  Every CLI command owns one read session (`createReadSession` in
@@ -301,9 +326,31 @@ fetch passes it with `-c remote.origin.url=`). A server without partial
301
326
  fetches gets whole trees; the cache records that (`oats.fetch = full` in its
302
327
  config) and the CLI prints the session's notice once, on stderr. Partial
303
328
  caches need git 2.45 or later (`PARTIAL_FETCH_GIT`, the first git with
304
- `GIT_NO_LAZY_FETCH`): with an older git every cache fetches whole trees, a
305
- partial cache it meets is deleted and fetched again whole, and the same
306
- notice says why.
329
+ `GIT_NO_LAZY_FETCH`): only a successfully parsed version below that floor
330
+ authorizes a version-driven rebuild. With that older git every cache fetches
331
+ whole trees, a partial cache it meets is deleted and fetched again whole,
332
+ and the same notice says why. An existing full cache stays full even when a
333
+ later probe reports a modern git.
334
+
335
+ One private strict version probe owns the memo per `exec`: concurrent callers
336
+ share the in-flight probe, and a parsed success is retained. A rejection,
337
+ unparseable result, or waiter leaving on timeout/cancellation removes only
338
+ that probe's own memo entry, so a later call
339
+ can retry without an old failure evicting a newer probe. `gitVersion(exec,
340
+ opts)` wraps this same probe for compatibility, returning a version or `null`;
341
+ it never memoizes a failure as `null`. The cache read path's `readVersion`
342
+ uses the strict probe and maps failure through the existing
343
+ `E_REMOTE_UNREADABLE` classification. Unparseable output is `unknown`; a
344
+ probe's own `timedOut` remains `timeout` even before a session deadline.
345
+ Each waiter can leave on its own timeout or cancellation. The launching
346
+ caller supplies the shared Git process's timeout and signal: when those end
347
+ the probe, every remaining waiter receives that original failure, even with
348
+ time left on its own deadline. A later call retries; leaving a wait never
349
+ changes the outcome delivered to peers still awaiting that probe.
350
+ These refusals apply with or without a read session and preserve the
351
+ existing partial cache, its fetch mode and its commit pins; failure never
352
+ reaches the version comparison as an older git. Raw version stdout and
353
+ command arguments are not diagnostic text.
307
354
 
308
355
  The fetch of a commit negotiates: git tells the server the commits the cache
309
356
  holds (its pins), and the pack holds only what they lack, a few kilobytes for
@@ -396,7 +443,7 @@ scaling by call count.
396
443
 
397
444
  | command | what it checks |
398
445
  |---|---|
399
- | `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 |
400
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`) |
401
448
  | `npm run check` | syntax of every shipped file |
402
449
  | `npm run check:pi` | the pi adapter's TypeScript |
@@ -425,6 +472,65 @@ its own; a line a child wrote into a pipe the test reads is the test's, and
425
472
  does not count. `test/unasserted-warnings.test.mjs` pins the rule with nested
426
473
  runs.
427
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
+
428
534
  Desktop's standalone tests (`cd packages/desktop && npm ci && npm test`) must
429
535
  load with only Desktop dependencies installed. The release builds Desktop that
430
536
  way: its `desktop-build` job installs and tests inside `packages/desktop` and
@@ -488,6 +594,31 @@ which fails with `ENOTEMPTY` (awebai/oats#451). So:
488
594
 
489
595
  Never paper over such a race with a retry around the cleanup.
490
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
+
491
622
  A test never reaches the operator's tmux. The kernel creates sessions on the
492
623
  server named `oats` (`tmux -L oats`), which tmux resolves under `TMUX_TMPDIR`,
493
624
  and acts on every existing session through its recorded socket
@@ -577,7 +708,12 @@ inherits it (awebai/oats#816):
577
708
  - **A short base.** `fixtureBase(prefix)` makes the fixture directory under
578
709
  the platform's temporary directory, or under `/tmp` when that is longer than
579
710
  20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
580
- realpath, taken once.
711
+ realpath, taken once. Under the root run the temporary directory is the
712
+ test file's own (above), and is used whatever its length, so that nothing a
713
+ fixture makes is outside what the run reads; the run keeps it short. The
714
+ helper knows it by what the runner makes (`ot-XXXXXX/<n>`, with the file
715
+ `<n>.file` beside it) and by no variable, so a process a test starts with
716
+ `inheritedEnv()` uses it too.
581
717
  - **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
582
718
  name or branch segment) and `pathOfLength(base, n)` (an absolute path under
583
719
  the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
@@ -696,4 +832,10 @@ inherits it (awebai/oats#816):
696
832
  still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
697
833
  and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
698
834
  `t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
699
- built removes its base itself.
835
+ built removes its base itself. Removing the base is not ending the fixture:
836
+ only `fx.cleanup` stops the fixture's tmux server, checks for leftover
837
+ processes and removes the fixture's private `TMUX_TMPDIR`
838
+ (`privateTmuxTmpdir()`), which is made beside the base and never inside it.
839
+ So a fixture that was made and never ended leaves that directory, and the
840
+ root run fails on it (awebai/oats#1025). A file that collects its fixtures
841
+ 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.0.5
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.