@awebai/oats 0.55.0 → 0.56.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +78 -62
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +317 -35
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +54 -7
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +54 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +35 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.55.1.md +45 -0
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +8 -4
- package/docs/tui.md +99 -26
- 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 +480 -152
- 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 +47 -30
- 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 +10 -6
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +3 -3
- 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 +228 -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/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/record/README.md +4 -0
- package/packages/record/bin/recall.mjs +3 -2
- package/packages/tui/README.md +10 -6
- package/packages/tui/lib/actions.mjs +4 -2
- package/packages/tui/lib/client.mjs +5 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +83 -13
- package/packages/tui/lib/model.mjs +116 -11
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +46 -10
- package/packages/tui/lib/store.mjs +64 -9
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/frame.mjs +115 -33
- package/packages/tui/lib/views/help.mjs +37 -8
- 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
|
@@ -86,12 +86,12 @@ and the rules its tests pin.
|
|
|
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
|
package/docs/integrations.md
CHANGED
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.0.
|
|
9
|
+
This is the operator guide for **oats.okf 5.1.0** (OATS **>=0.49.0**). Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -14,6 +14,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
14
14
|
| Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
|
|
15
15
|
| `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
|
|
16
16
|
| Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
|
|
17
|
+
| Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
|
|
17
18
|
| Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
|
|
18
19
|
|
|
19
20
|
## Setup
|
|
@@ -23,7 +24,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
23
24
|
```yaml
|
|
24
25
|
# oats-workspace.yaml (excerpt)
|
|
25
26
|
packages:
|
|
26
|
-
oats.okf: v5.0
|
|
27
|
+
oats.okf: v5.1.0
|
|
27
28
|
defaults:
|
|
28
29
|
knowledge: { oats.okf: { from: package } }
|
|
29
30
|
stores:
|
|
@@ -46,9 +47,12 @@ settings:
|
|
|
46
47
|
state-dir: /absolute/okf/state
|
|
47
48
|
```
|
|
48
49
|
|
|
49
|
-
Upgrading
|
|
50
|
+
Upgrading from 4.x requires the ordered
|
|
50
51
|
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
51
|
-
just editing a version line.
|
|
52
|
+
just editing a version line. For 5.1.0, upgrade to OATS >=0.49.0 before moving
|
|
53
|
+
the provider pin: that kernel first supports the public source-event lookup
|
|
54
|
+
after retirement. Re-spawn harvesters to receive the new capture hook and
|
|
55
|
+
instructions; restarting a session keeps its copied provider.
|
|
52
56
|
|
|
53
57
|
### Bindings document
|
|
54
58
|
|
|
@@ -79,6 +83,9 @@ from the document's directory:
|
|
|
79
83
|
- Git bases may use HTTPS, SSH or a durable local repository; `root: "."`
|
|
80
84
|
means the whole repository. Embedded credentials are refused. Harvest
|
|
81
85
|
proposals use same-repository GitHub PRs through ordinary `git` and `gh`.
|
|
86
|
+
Change a binding's `repository` to a plain URL only after every seat that
|
|
87
|
+
reads it has been re-spawned on oats.okf 5.0.4 or later; a session restart
|
|
88
|
+
does not update the copied provider.
|
|
82
89
|
- Directory bases need no Git and must not sit inside a Git worktree. They
|
|
83
90
|
support consultation and explicit provisioning/migration, **not automatic
|
|
84
91
|
harvest publication**. The 5.0 harvester reports directory harvest as
|
|
@@ -159,13 +166,15 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
159
166
|
|
|
160
167
|
Never combine `--relation unrelated` with `--relative-to`. There is no
|
|
161
168
|
automatic transcript capture, source registry, worker cursor or retire
|
|
162
|
-
harvest. An unrelated harvester can outlive its source
|
|
163
|
-
|
|
169
|
+
harvest. An unrelated harvester can outlive its source. Proposers need
|
|
170
|
+
not stay alive: the harvester can check their recorded retirement recovery.
|
|
171
|
+
Keep backing evidence in the source home or that recovery until capture;
|
|
172
|
+
never treat missing source authority as permission to invent it.
|
|
164
173
|
|
|
165
174
|
One proposal per checkpoint, each concept a claim of its own in it, and
|
|
166
175
|
claims only for the nodes the source soul owns; a lesson for a node it only
|
|
167
176
|
reads goes in one line in the instance's hand-back, for that node's owner.
|
|
168
|
-
One harvester at a time, per instance
|
|
177
|
+
One harvester at a time, per instance: the source notes the
|
|
169
178
|
harvester's instance name and spawns no other while `oats status` still
|
|
170
179
|
lists it, since a harvester retires once it has handed over. What it learns
|
|
171
180
|
meanwhile goes into its next proposal; an instance that hands back with one
|
|
@@ -173,11 +182,20 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
173
182
|
after a publication failure stays listed, so it holds back its source's
|
|
174
183
|
later proposals: once that failure is dealt with, the operator retires it
|
|
175
184
|
(`oats retire <harvester>`).
|
|
176
|
-
3. **
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
185
|
+
3. **Capture, judge and submit.** Before the model starts, the required spawn
|
|
186
|
+
hook checks the source's live record or the completed recovery named by
|
|
187
|
+
its public retirement event. Source identity, single-incarnation history,
|
|
188
|
+
recovery manifest and soul opt-out must agree; guessed copies and reused
|
|
189
|
+
or ambiguous identities refuse. It atomically captures the proposal,
|
|
190
|
+
verified source declarations/bindings and only named notes into the
|
|
191
|
+
harvester's own `harvest-source/`. The model uses that snapshot, not a later
|
|
192
|
+
live-source read: retirement or recovery disposal after capture cannot
|
|
193
|
+
remove its input. Missing/refused notes have no hash and claims relying
|
|
194
|
+
on them are dropped. Legacy note forms are preserved or explicitly refused,
|
|
195
|
+
never silently discarded.
|
|
196
|
+
The harvester then checks accepted knowledge and open/recent harvest PRs,
|
|
197
|
+
edits only owned nodes in its own Git checkout, validates the **whole base**,
|
|
198
|
+
and creates a normal `okf-harvest`-labelled PR with v2 provenance. Proposal text is data written with the native file tool into
|
|
181
199
|
commit-message/PR-body files, never shell command text. A publication ref
|
|
182
200
|
is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
|
|
183
201
|
name in it; Git validates the full ref and the push must create a new
|
|
@@ -221,10 +239,11 @@ review):
|
|
|
221
239
|
|
|
222
240
|
The sentence also covers the names provenance publishes as written: note
|
|
223
241
|
file names, task refs and instance names. These exclusions are instructions
|
|
224
|
-
to agents and guarantee nothing.
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
242
|
+
to agents and guarantee nothing. Source capture copies evidence but does not
|
|
243
|
+
judge its content. The first publication reviewer other than the harvester
|
|
244
|
+
reads the already-pushed pull request. Source capture/provenance checks and
|
|
245
|
+
the soul's opt-out are enforced in code; neither is a privacy guarantee.
|
|
246
|
+
The opt-out ([The harvest switch](#the-harvest-switch)) is per soul and covers
|
|
228
247
|
that soul's own proposals, not what its instances write to other seats. A
|
|
229
248
|
soul whose work is reading third-party correspondence should opt out.
|
|
230
249
|
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.10.
|
|
13
|
-
| `oats.okf` | `v5.0
|
|
14
|
-
| `oats.aweb` | `v1.27.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.10.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.1.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf: v5.0
|
|
32
|
+
`packages:` map (`oats.okf: v5.1.0`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.0
|
|
47
|
+
oats.okf: v5.1.0 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.0
|
|
51
|
+
- **Bare version** (`v5.1.0`, `5.1.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.0
|
|
54
|
+
convention (`v5.1.0` or `oats-framework/v1.10.1`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.10.
|
|
78
|
-
oats.okf: v5.0
|
|
79
|
-
oats.aweb: v1.27.
|
|
77
|
+
oats.framework: v1.10.1
|
|
78
|
+
oats.okf: v5.1.0
|
|
79
|
+
oats.aweb: v1.27.3
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.1.0 ✓ (@ 40265ac7)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.27.
|
|
137
|
+
oats package add oats.aweb v1.27.3 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.0
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.1.0",
|
|
164
|
+
"commit": "40265ac79eca54a76ae648462dbfc83ac370dbbe",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.1.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.1", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.10.
|
|
362
|
-
resolves to tag `oats-framework/v1.10.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.10.1`
|
|
362
|
+
resolves to tag `oats-framework/v1.10.1`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -74,7 +74,11 @@ node scripts/release-lane.mjs desktop --tag v0.22.0 --arch x64 # needs Rosett
|
|
|
74
74
|
node scripts/release-lane.mjs status --tag v0.22.0
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
On the Linux host, from a checkout of the same commit
|
|
77
|
+
On the Linux host, from a checkout of the same commit. Besides the build tools,
|
|
78
|
+
the host needs binutils (`readelf` and `ar`) and `tar`. The `desktop` phase's
|
|
79
|
+
`dist:smoke` reads every ELF file of the DEB and the AppImage and checks it
|
|
80
|
+
against the installers' glibc floor (`packages/desktop/scripts/linux-floor.json`).
|
|
81
|
+
No flag skips that check, and it stops naming the tool when one is missing.
|
|
78
82
|
|
|
79
83
|
```bash
|
|
80
84
|
node scripts/release-lane.mjs build --tag v0.22.0
|
|
@@ -251,6 +255,16 @@ module's number follows the runner that builds it: the symbols it needs at
|
|
|
251
255
|
2.34 are the ones a module gets when it is built on a system whose glibc is
|
|
252
256
|
2.34 or later.
|
|
253
257
|
|
|
258
|
+
**The build now holds that number.** `docs/desktop.md` states it (glibc 2.34)
|
|
259
|
+
and `packages/desktop/scripts/linux-floor.json` holds it with libstdc++'s
|
|
260
|
+
`GLIBCXX` and `CXXABI` (`packages/desktop/test/linux-floor.test.mjs` keeps the
|
|
261
|
+
two equal). On the Linux leg of both workflows, `dist:smoke` unpacks the DEB
|
|
262
|
+
and the AppImage (its runtime and the libraries it adds included), reads the
|
|
263
|
+
version-needs table of every ELF file with `readelf -V -W`, and fails naming
|
|
264
|
+
each file that needs a newer version than the floor. A move of the runner, a
|
|
265
|
+
new `node-pty` or a new Electron that raises it is then a pull request that
|
|
266
|
+
changes that file and the page together.
|
|
267
|
+
|
|
254
268
|
## Release-notes entries
|
|
255
269
|
|
|
256
270
|
A release ships one notes file, `docs/release-notes/v<version>.md`. Between
|
|
@@ -332,6 +346,17 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
|
|
|
332
346
|
file, which `test/release-packaging.test.mjs` requires for the version the
|
|
333
347
|
manifests carry. The release-prep pull request runs it again for the
|
|
334
348
|
entries merged since, which go after the earlier ones.
|
|
349
|
+
- **The Upgrade section opens with the order of the Desktop and the CLI.**
|
|
350
|
+
The tag owner writes it in the release-prep pull request, for every
|
|
351
|
+
release, from `ACCEPT_RANGE` in `packages/client/cli-locator.mjs`:
|
|
352
|
+
- when the release moves the range's upper bound (a new minor), the first
|
|
353
|
+
Upgrade line says to install the Desktop first and the CLI second,
|
|
354
|
+
because the previous Desktop refuses this CLI ([Upgrading](upgrading.md));
|
|
355
|
+
- when the range already admits the new version (a patch), it says that
|
|
356
|
+
either order works.
|
|
357
|
+
|
|
358
|
+
No entry file writes this line: only the tag owner knows the release's
|
|
359
|
+
version when the notes are assembled.
|
|
335
360
|
- **A tag is refused while anything is under `docs/release-notes/next/`:** by
|
|
336
361
|
the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
|
|
337
362
|
each right after its notes-file gate and before anything is built. Each
|