@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.
- package/bin/oats.mjs +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
package/docs/harness-trust.md
CHANGED
|
@@ -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
|
|
31
|
-
|
|
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.
|
|
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
|
-
|
|
122
|
-
|
|
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
|
|
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
|
package/docs/implementation.md
CHANGED
|
@@ -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`)
|
|
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; `
|
|
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`):
|
|
305
|
-
|
|
306
|
-
|
|
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.
|
package/docs/integrations.md
CHANGED
|
@@ -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
|
|
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
|
|
88
|
-
|
|
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.
|