@awebai/oats 0.69.5 → 0.69.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/bin/oats.mjs +78 -320
  2. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  3. package/docs/design/2026-10-29-warm-reader.md +261 -0
  4. package/docs/design/README.md +4 -0
  5. package/docs/desktop-cli-api.md +250 -12
  6. package/docs/execution-targets.md +11 -2
  7. package/docs/implementation.md +26 -8
  8. package/docs/integrations.md +1 -1
  9. package/docs/knowledge.md +14 -7
  10. package/docs/named-test-runs.md +4 -0
  11. package/docs/official-catalog.md +3 -3
  12. package/docs/packages.md +12 -12
  13. package/docs/release-notes/v0.69.6.md +165 -0
  14. package/docs/schedules.md +8 -1
  15. package/docs/tui.md +21 -4
  16. package/docs/upgrading.md +9 -5
  17. package/docs/workspaces.md +2 -2
  18. package/lib/argv.mjs +41 -0
  19. package/lib/automation-scope.mjs +6 -4
  20. package/lib/automations.mjs +61 -11
  21. package/lib/captured-context.mjs +12 -0
  22. package/lib/hot-reads.mjs +21 -15
  23. package/lib/install-stamp.mjs +61 -0
  24. package/lib/instance-events.mjs +8 -6
  25. package/lib/instance-listing.mjs +13 -5
  26. package/lib/kernel-features.mjs +10 -0
  27. package/lib/local-edit.mjs +1 -1
  28. package/lib/local-inputs.mjs +3 -0
  29. package/lib/member-clone.mjs +15 -11
  30. package/lib/read-call.mjs +143 -0
  31. package/lib/reader.mjs +203 -0
  32. package/lib/remote.mjs +47 -6
  33. package/lib/resolved-deployment.mjs +12 -4
  34. package/lib/roster-read.mjs +199 -0
  35. package/lib/session-input.mjs +35 -11
  36. package/lib/workspace-read.mjs +160 -0
  37. package/package-catalog.json +2 -2
  38. package/package.json +1 -1
  39. package/packages/client/cli-locator.mjs +1 -0
  40. package/packages/client/cli-probe-contract.mjs +4 -2
  41. package/packages/client/deployment-observer.mjs +8 -3
  42. package/packages/client/deployment-panel.mjs +17 -1
  43. package/packages/client/deployment-read-cli.mjs +48 -27
  44. package/packages/client/own-codes.mjs +3 -0
  45. package/packages/client/warm-reader.mjs +241 -0
  46. package/packages/tui/lib/client.mjs +2 -1
  47. package/packages/tui/lib/read.mjs +59 -11
  48. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -52,9 +52,13 @@ from it, and the test lists the stable surface a second client may import.
52
52
  layers that each do one thing. `lib/term/` is the terminal: the key parser,
53
53
  cell widths, safe text, the screen and the guard that restores the terminal;
54
54
  only the screen and the guard write an escape byte. `lib/read.mjs` is every
55
- effect of reading: for each deployment opened in a run it runs the kernel
56
- of the same install and the shared liveness collector as children, through
57
- the shared observer and refresh loop; it runs that kernel's read of the
55
+ effect of reading: for each deployment opened in a run it reads through
56
+ the shared observer and refresh loop, its background reads through one
57
+ warm `oats reader --stdio` of the kernel of the same install (the shared
58
+ `createWarmReader`), every other read through that kernel as a child, and,
59
+ for a kernel without feature `status-liveness`, the shared liveness
60
+ collector as a child too; a void cycle's reads are answered at once,
61
+ the warm reader's included; it runs that kernel's read of the
58
62
  other machines (`oats server roster --json`), one at a time and awaited by
59
63
  no cycle; it ends every read child and lets changes finish; and it makes the one look at the file
60
64
  system the workspace switcher needs (whether a picked row is a deployment).
@@ -100,7 +104,13 @@ and the rules its tests pin.
100
104
  | `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
101
105
  | `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
102
106
  | `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
103
- | `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
107
+ | `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630), and the warm reader's start (`oats reader --stdio`, whose reads `reader.mjs` imports itself): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
108
+ | `roster-read.mjs`, `workspace-read.mjs`, `read-call.mjs` | the deployment reads (awebai/oats#1630): `oats status` (`roster-read.mjs`: the roster, its drift and its workspace identity) and `oats workspace status` (`workspace-read.mjs`: members, packages, automations, the desktop facts, and the rows `oats sync` reports too), one implementation behind the CLI and a process that answers them many times. Each has an answer function (`statusAnswer`, `workspaceStatusAnswer`: `{ exit, answer, stderr }`, `answer` the JSON the CLI prints, a refusal included) and a data function (`statusView`, `workspaceStatusView`) bin's text renderer reads. `read-call.mjs` is one call's scope: it takes an explicit context (the absolute `dir`, `maxAge`, the caller's read session, the cache, an optional deployments observer), resets at its start every piece of module-level state the reads can reach (`READ_STATE`; `test/read-call-state.test.mjs` scans the reads' import closure and fails on a binding with no row), answers refusals as envelopes, and drains the session's notices. Within one call, two pieces of work are not repeated: `listInstances` hands the records it read to the rest of the read (`records`: `legacyCapturedHomes` and the waiting read take them instead of parsing them again), and `workspace status` asks git for each member clone's remotes once (`remotes`, shared by the automation scope and the desktop facts); both are maps the read makes and drops, never module state. A call registers no process listener, closes no session and reads no argv or cwd: the CLI passes `commandSession` (created at the first remote read, with its exit and signal listeners) and closes it at the end of the command, as for every verb. The read part of the dispatch is there too (`parseMaxAge`, `readBudget`, `callSession`); `test/read-call-equivalence.test.mjs` answers both reads many times in one process and compares each answer with a fresh CLI run's. Leaves: never `core.mjs`. Kernel-private, not in `./core` |
109
+ | `reader.mjs` | `oats reader --stdio`, the warm reader (awebai/oats#1630; [the contract](desktop-cli-api.md#the-warm-reader), [the decisions](design/2026-10-29-warm-reader.md)): a client's child that answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, through `read-call.mjs` and the two answer functions, never a copy of them. It loads every module the reads import lazily (`PRELOAD`) before its hello; classifies a request with `hot-reads.mjs` `hotRead` and expands its flags with `argv.mjs`, then runs the dispatch's read part in the CLI's order (the flag syntax, `--max-age`, the inherited context), so a refusal there is the CLI's own answer; answers one request at a time, in arrival order, each with its own read session, closed at its end, and its deployments observer; changes its working directory to the request's `--dir` for the read and back to the install root after, because the programs the reads run by name resolve a relative `PATH` entry against it (a second lane must first give each child its own cwd). It compares `install-stamp.mjs`'s stamp, taken by `bin` before the kernel loaded, when a request starts and before its answer is written: a change refuses `E_READER_STALE` and exits. Its stdout carries protocol lines only (other writes go to stderr); a request in flight at exit has its session closed from the `exit` handler. `test/reader-protocol.test.mjs` pins the protocol and `PRELOAD` against the reads' closure. `oats reader --stdio` is a hot-read form, so `bin` loads only its dispatch's leaves for it, never `core.mjs` (`test/cli-hot-reads.test.mjs`). Kernel-private, not in `./core`. Dependency-free |
110
+ | `install-stamp.mjs` | the warm reader's install stamp: `stat` of the install's code and data (package.json, bin/oats.mjs, the catalog, every file under lib/, the docs schemas, each runtime dependency's package.json where it resolves now, the Node binary) as one string. Node built-ins only: `bin` imports it statically and takes the reader's baseline before any kernel module loads; `reader.mjs` compares each request against it |
111
+ | `argv.mjs` | how the kernel reads `--flag=value` ([Flag syntax](desktop-cli-api.md#flags)): `expandInlineValues`, which the CLI's dispatch runs once on its argv and the reader on each request's, so both give a malformed flag the same `E_BAD_ARGS`, and `flagValue`, a flag's value in an expanded argv. Kernel-private, not in `./core`. Dependency-free |
112
+ | `kernel-features.mjs` | `KERNEL_FEATURES`, the features this kernel implements: `features` in `version --json` and in `status --json`; `READER_API`, the warm reader's protocol number (`readerApi` in `version --json` and in the reader's hello). Kernel-private, not in `./core` |
113
+ | `captured-context.mjs` | the refusal (`E_UNSUPPORTED_MODE`) of an environment that carries `OATS_RESOLUTION` or `OATS_DEPLOYMENT`, which the dispatch asks for every command but `version` and `reader`; the reader asks it for each request instead, so it starts and answers each read as the CLI would. Dependency-free |
104
114
  | `version.mjs`, `deployment-path.mjs`, `write-file-atomic.mjs`, `agents-root.mjs`, `soul-listing.mjs`, `instance-address.mjs`, `session-inspect.mjs`, `instance-listing.mjs`, `drift.mjs`, `package-catalog.mjs`, `member-clone.mjs`, `reserved-launch-env.mjs`, `automation-scope.mjs`, `automation-api.mjs`, `semver.mjs` | the leaves the hot reads load instead of the modules that re-export them (awebai/oats#1630): the version; the canonical deployment path; the atomic file write; the agents root; souls and instance homes; `resolveInstance`; `inspectInstanceSession`; `listInstances` and the status rows; soul and module drift; the official package catalog; discovery and member clones; the reserved launch environment; the automation scope; the automation API versions; `compareSemver`. Each name is still exported, under the same name, from the module it left (`core.mjs`, `packages.mjs`, `instance-lifecycle.mjs`, `materialize.mjs`, `instance-resolution.mjs`, `schedule.mjs`, `automations.mjs`, `servers.mjs`), so `./core` is unchanged (`test/core-exports.test.mjs`), and no leaf imports `core.mjs` or the module it left. Code a hot read reaches goes in a leaf, never in `core.mjs` |
105
115
  | `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
106
116
  | `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) |
@@ -138,10 +148,10 @@ and the rules its tests pin.
138
148
  | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
139
149
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
140
150
  | `file-pieces.mjs` | a regular file's bytes read in pieces of 1 MiB (`readFilePieces`, `hashFile`, and `readFileUpTo` for a home's `instance.json`, read whole up to 16 MiB for its neutral form), for every digest of the retire path: what a digest holds of a file is bounded whatever its size (Node reads no file over 2 GiB whole), and a file is read for the size it had when it was opened. One that ends before that size refuses with `E_WORK_INSPECTION_FAILED` |
141
- | `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
151
+ | `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; a shell-labelled pane is a fallback shell only when that scan shows the pane's own process as a shell with no non-shell descendant, and a scan that cannot show it throws its reason (unknown, never idle: #1641); `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
142
152
  | `servers.mjs` | routing commands to a registered server |
143
153
  | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
144
- | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`agents-root.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
154
+ | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`agents-root.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. A process that answers many reads sets its observer with `atExit: false` and settles it at the end of each read (`read-call.mjs`), which also forgets what the last one reported (`resetResolvedDeployment`). Dependency-free |
145
155
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
146
156
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
147
157
  | `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 |
@@ -338,7 +348,7 @@ gets the plain per-call behaviour. Within a session:
338
348
  exit hook (`closeNow`), and the system reaps them once the process is gone;
339
349
  - a session may have a `deadline` (`READ_REMOTE_BUDGET_MS`, 12 s after it
340
350
  starts): the CLI gives one to `status` and `workspace status` only
341
- (`readBudgetMs`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
351
+ (`read-call.mjs` `readBudget`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
342
352
  not a contract). Every
343
353
  remote step then gets what is left of it instead of its own default: each
344
354
  git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
@@ -491,7 +501,15 @@ atomically, a corrupt one is a miss, and `pruneStores` bounds the store
491
501
  (`PARSED_LIMITS`, least recently used first). `--max-age` adds the observation
492
502
  store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
493
503
  one record per (repo key, ref args, url digest), so two spellings of one repo
494
- keep a record each; the url itself is never written. Adding a cached item
504
+ keep a record each; the url itself is never written. Beside it,
505
+ `<cache>/.observed-facts/` holds the remote facts that are not heads
506
+ (`factObservation`): today the `gh` login `workspace status` places automations
507
+ with for display ([the `gh` login, display only](desktop-cli-api.md#the-gh-login-display-only)).
508
+ A record is named by the digest of its fact's context (`ghLoginParts` in
509
+ `automations.mjs`: never a token value) and holds only the answer and when it
510
+ was observed; only `workspace-read.mjs` passes the reuse to `ghLogin` (its
511
+ `lookup`, with the display's 5 s wait), so a tick, a poll or a run always asks
512
+ `gh` live. `pruneStores` bounds both stores alike. Adding a cached item
495
513
  means choosing an item name unique to its producer (the item string its
496
514
  call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
497
515
  adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
@@ -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.6.0
43
+ oats.okf: v5.7.0
44
44
  oats.aweb: v1.32.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
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.6.0** (OATS **>=0.69.2**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.7.0** (OATS **>=0.69.2**). 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 |
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
25
25
  ```yaml
26
26
  # oats-workspace.yaml (excerpt)
27
27
  packages:
28
- oats.okf: v5.6.0
28
+ oats.okf: v5.7.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,11 +50,11 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. 5.6.0 requires OATS >=0.69.2: its
53
+ just editing a version line. From 5.6.0 it requires OATS >=0.69.2: its
54
54
  `knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
55
55
  which an older kernel refuses. Upgrade OATS first, then the package.
56
56
 
57
- **Upgrade:** pin `oats.okf: v5.6.0` and run `oats sync`. Only new spawns get
57
+ **Upgrade:** pin `oats.okf: v5.7.0` and run `oats sync`. Only new spawns get
58
58
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
59
59
  homes keep their copied provider even after a session restart; from 5.4.0, a
60
60
  stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
@@ -68,7 +68,9 @@ proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
68
68
  the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
69
69
  that line, so run `oats sync` to 5.5.0 or later before instances on 5.5.0
70
70
  propose. 5.6.0 lists new harvesters and knowledge maintainers under the
71
- clients' Background section; existing ones do not move.
71
+ clients' Background section; existing ones do not move. 5.7.0 stops parking
72
+ harvest PRs under `okf-needs-human` (step 4 of [the flow](#the-flow)); PRs an
73
+ older maintainer parked are re-reviewed by the steps in okf's CHANGELOG.
72
74
 
73
75
  ### Bindings document
74
76
 
@@ -280,8 +282,13 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
280
282
  for a labelled PR. A gh error can leave remote effects, so partial or
281
283
  uncertain publication is not completion or permission to clean up.
282
284
  4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
283
- Human-accepted decisions are not silently superseded; the review path
284
- keeps its human gate. A PR is not accepted knowledge until merged.
285
+ A PR is not accepted knowledge until merged. Human-accepted decisions are
286
+ not silently superseded. Before oats.okf 5.7.0 the maintainer labels a PR
287
+ that would supersede one `okf-needs-human` and leaves it to a human. From
288
+ 5.7.0 the review never parks a PR: such a supersession merges only with the
289
+ human's acceptance cited (checked when the record is on GitHub, otherwise
290
+ recorded as source-reported), and is closed without it
291
+ ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
285
292
 
286
293
  The promotion test belongs to
287
294
  [What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge),
@@ -187,6 +187,10 @@ leaves out the request's two variables, the runner's command files
187
187
  (`GITHUB_ENV`, `GITHUB_OUTPUT`, `GITHUB_PATH`, `GITHUB_STATE`,
188
188
  `GITHUB_STEP_SUMMARY`) and node's nested-run marker. So `GITHUB_WORKFLOW` and
189
189
  `GITHUB_EVENT_NAME` reach the test, and on Linux so does `XDG_RUNTIME_DIR`.
190
+ It puts the tested tree's `node_modules/.bin` first on `PATH`, as `npm test`
191
+ does in pull-request CI and the release workflow: a test that starts a
192
+ fixture instance finds there the `pi` that the workflow's `npm ci` installs
193
+ in the tested tree.
190
194
 
191
195
  A guard is a switch, not a proof. Anyone can set these variables on their own
192
196
  machine, and a guarded test that runs there drives that machine's real
@@ -9,8 +9,8 @@ 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.16.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.6.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.16.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.32.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -30,7 +30,7 @@ no lock and adds nothing to an existing workspace.
30
30
  ## Find and use packages
31
31
 
32
32
  - A workspace pins an official package by **bare version** in its
33
- `packages:` map (`oats.okf: v5.6.0`); `oats sync` resolves it through the
33
+ `packages:` map (`oats.okf: v5.7.0`); `oats sync` resolves it through the
34
34
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
35
35
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
36
36
  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.6.0 # bare version → the official catalog
47
+ oats.okf: v5.7.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.6.0`, `5.6.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.7.0`, `5.7.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.6.0` or `oats-framework/v1.16.3`) and the payload path. An id
54
+ convention (`v5.7.0` or `oats-framework/v1.16.4`) 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,8 +74,8 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.16.3
78
- oats.okf: v5.6.0
77
+ oats.framework: v1.16.4
78
+ oats.okf: v5.7.0
79
79
  oats.aweb: v1.32.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -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.6.0 ✓ (@ ec169fd6)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.7.0 ✓ (@ 56dbc167)
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
@@ -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.6.0",
164
- "commit": "ec169fd6ab20abea1eea26fe8eff3a9b547e7210",
163
+ "version": "5.7.0",
164
+ "commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
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.6.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.3", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.7.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.4", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.16.3`
362
- resolves to tag `oats-framework/v1.16.3`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.16.4`
362
+ resolves to tag `oats-framework/v1.16.4`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -0,0 +1,165 @@
1
+ # OATS 0.69.6
2
+
3
+ Unreleased
4
+
5
+ 0.69.6 makes the Desktop and `oats tui` refresh without starting a new CLI
6
+ process for every read. Both now read through one warm `oats reader --stdio`,
7
+ and under the new feature `status-liveness` they take each instance's
8
+ liveness from `oats status` instead of running their own terminal probe.
9
+ `oats status` and `oats workspace status` also do less work per read. A
10
+ working instance no longer reads idle when the process scan can't see it.
11
+ The catalog moves to oats.okf 5.7.0, whose knowledge maintainer never parks a
12
+ harvest PR for a human, and to oats.framework 1.16.4.
13
+
14
+ ## Upgrade
15
+
16
+ - **Either order of the Desktop and the CLI works.**
17
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
18
+ installed the CLI first is fine too: the 0.69.6 Desktop accepts OATS CLIs
19
+ `>=0.26.0 <0.70.0`, and so does the 0.69.5 Desktop. The warm reader needs
20
+ both: a Desktop or TUI uses it only with a CLI that lists feature
21
+ `warm-reader`, and otherwise reads through the CLI, as before.
22
+ - **Package moves:** the official catalog pins oats.okf 5.7.0 and
23
+ oats.framework 1.16.4, with no change to their OATS floors. A deployment
24
+ takes them with `oats sync`. Running instances keep the modules they were
25
+ spawned with: new spawns get the new ones, and a stopped home moves with
26
+ `oats instance upgrade`.
27
+ - **Knowledge PRs parked on `okf-needs-human`:** on the review host of the
28
+ workspace's harvest-review trigger, once its lock has oats.okf 5.7.0,
29
+ re-review each one as Provider updates (below) says. A label left in place
30
+ does nothing, and no new review starts on its own.
31
+
32
+ ## Added
33
+
34
+ - The warm reader, `oats reader --stdio` (feature `warm-reader`,
35
+ `readerApi: 1`, #1630). A client starts it as its own child, from the same
36
+ install it runs its CLI reads with, and sends it `oats status --json` and
37
+ `oats workspace status --json` reads over its stdin and stdout, one JSON
38
+ line each way, many times. It answers with the kernel's own read code, kept
39
+ loaded: warm code, not warm data. Every request reads the deployment
40
+ afresh, and each answer's `exit` and `answer` are what the same CLI read
41
+ prints and exits with, with cwd = `--dir`. What it cannot answer that way it
42
+ refuses (`E_READER_BAD_REQUEST`, `E_READER_UNSUPPORTED`), and the client
43
+ runs the CLI. A reader whose install changed under it (an upgrade, a Node
44
+ upgrade) answers nothing more from the old code: it refuses with
45
+ `E_READER_STALE` and exits. It ends when its client closes its stdin or
46
+ dies. Bare `oats reader` is `E_USAGE`. The protocol and the client rules
47
+ are in [The warm reader](../desktop-cli-api.md#the-warm-reader); the
48
+ decisions in [the design record](../design/2026-10-29-warm-reader.md).
49
+ - Feature `status-liveness`: `oats status --json` instance rows' `running`
50
+ and `runtimeState` are the complete local liveness reading, read live at
51
+ every call under the kernel's pane rule, so a client that sees the feature
52
+ in the probe needs no liveness probe of its own beside the roster
53
+ ([The roster](../desktop-cli-api.md#the-roster-oats-status---json)).
54
+
55
+ ## Changed
56
+
57
+ - **OATS Desktop: the poll's reads go through the warm reader** (#1630).
58
+ Where the installed CLI lists `warm-reader` (`readerApi: 1`), the Desktop's
59
+ bundled server starts one `oats reader --stdio` from that CLI. It answers
60
+ the background `oats status` and `oats workspace status` reads of every
61
+ refresh cycle (`--max-age` above 0) with the kernel's read code kept
62
+ loaded, instead of a Node start per read. The answers are the CLI's own and
63
+ are checked the same way. A live read (the first cycle, a refresh after a
64
+ change, Refresh) still runs the CLI. Whenever the reader is absent, refuses,
65
+ times out, stops answering or exits, that read runs the CLI as before.
66
+ After repeated failures the Desktop uses the CLI until the CLI changes. A
67
+ reader whose install was upgraded under it makes the Desktop probe the CLI
68
+ again. The reader dies with the server that started it, also when the app
69
+ or the server is killed. Nothing about it is shown. `/api/cli` reports its
70
+ state as a diagnostic.
71
+ - **OATS Desktop: no liveness child under `status-liveness`.** With a CLI
72
+ that lists `status-liveness`, the refresh cycle no longer starts its
73
+ terminal-liveness child. A local row's running state, reason and tmux
74
+ record are the ones `oats status` reports, and a reason on a local row is
75
+ always the kernel's. As a result, an instance home with no tmux record
76
+ (every spawn records one) has no terminal for the Desktop to open, where
77
+ the child used to fill in the default session. With an older CLI the child
78
+ runs as before.
79
+
80
+ - `oats tui` reads its deployments in the background through one warm
81
+ `oats reader --stdio` of its own kernel, when that kernel lists feature
82
+ `warm-reader`, in place of two kernel commands per deployment each cycle.
83
+ Its answers are the commands' own, and a live read (`r`), every read
84
+ before the reader is ready and every read it does not answer still run
85
+ the commands, as before. Under feature `status-liveness` the TUI no
86
+ longer runs its probe of the terminals: each instance's running state,
87
+ reason and tmux record are the ones `oats status` reports. As a result,
88
+ an instance home with no tmux record (every spawn records one) has no
89
+ terminal for the TUI to open, where the probe used to fill in the default
90
+ session. With an older kernel the probe runs as before (#1630; [What it
91
+ reads, and what it runs](../tui.md#what-it-reads-and-what-it-runs)).
92
+ - The warm reader (`oats reader --stdio`, #1630) starts with only the code
93
+ its reads use: the CLI no longer loads its whole command set for it first.
94
+ On a real deployment its hello comes in about 140–180 ms instead of about
95
+ 300, and it holds about 20 MiB less memory while it answers a poll. Its protocol, its answers
96
+ and its install stamp are unchanged; a client needs no change
97
+ ([The warm reader](../desktop-cli-api.md#the-warm-reader)).
98
+
99
+ - `oats status` and `oats workspace status` do less work per read, with the same answers ([awebai/oats#1630](https://github.com/awebai/oats/issues/1630)). `status` shares each instance home's `instance.json`, as its listing read it, with its legacy-home check and its waiting-claim read instead of each parsing it again, and `workspace status` asks git for a member clone's remotes once, where it verified the clone an automation lives in twice. Nothing is kept between reads, in the CLI or in the warm reader (`oats reader --stdio`).
100
+
101
+ - **`oats workspace status --max-age <s>` reuses the host's `gh` login, for display only** ([awebai/oats#1630](https://github.com/awebai/oats/issues/1630); [Observation reuse](../desktop-cli-api.md#the-gh-login-display-only)). To show where each workspace trigger and schedule runs, `workspace status` asks `gh api user` which account this host acts as: a GitHub API call on every read, which a client polling every few seconds made every few seconds, and most of each read's time. Under `--max-age <s>` it now reuses a login observed at most `<s>` seconds ago, as it reuses remote heads, and counts it in the `observation` block (`reused`, `observedAt`). A login is reused only under the same `gh` context (host, `gh` binary, which token variables are set, `GH_HOST`, the config directory and its `hosts.yml`); no token or digest of one is kept; a failed answer is never reused and ends the reuse of the one before it. Without `--max-age`, or with `0`, it asks every time. What runs does not change: a schedule tick, `oats trigger poll` and every run still ask `gh` live. Within `<s>`, a token revoked on GitHub still shows the login, as a moved head shows unmoved.
102
+ - **A `gh` that hangs costs `oats workspace status` 5 s, not 30.** The display waits at most 5 s for `gh api user` (ticks and runs keep 30 s); a `gh` that does not answer in time reads `owner-mismatch`, as one that is not logged in does.
103
+
104
+
105
+ ## Fixed
106
+
107
+ - **A working instance no longer reads idle when the process scan cannot see it.** tmux names the launch's own shell as a pane's command while the harness runs below it, so `oats status` and `oats session inspect` decide such a pane from the process table. A table that could not establish the fallback prompt still read it: a `ps` that could not see the pane's process (another PID namespace, a pane respawned between the two reads), a process in the pane with no command name, or a line that is not a process each made a running harness read `running: false` (idle) in the Desktop and the TUI. `false` now needs the pane's own shell in the table with no non-shell process below it; anything else reads `running: null` with the reason as `runtimeError` (`session inspect`: `E_SESSION_UNAVAILABLE`), and a lifecycle command refuses rather than taking the pane for a fallback shell. A pane at its fallback prompt still reads `running: false` with `runtimeState: "shell"` ([awebai/oats#1641](https://github.com/awebai/oats/issues/1641); [The roster](../desktop-cli-api.md#the-roster-oats-status---json)).
108
+
109
+ ## Provider updates
110
+
111
+ - **oats.okf 5.7.0: the knowledge maintainer never parks a harvest PR**
112
+ ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
113
+ When a deployment pins oats.okf 5.7.0, a PR that would supersede a
114
+ human-accepted decision is settled at review instead of waiting for a
115
+ human under the `okf-needs-human` label. The OATS floor is unchanged.
116
+ - It is closed when it cites no acceptance (who accepted the change, when
117
+ and where).
118
+ - A cited record on GitHub (an issue or PR comment, or a commit) is
119
+ checked: it must exist at the cited link, under the account the citation
120
+ names, and say the cited thing. Confirmed, the PR merges as an explicit
121
+ supersession with the acceptance recorded as verified at its link, which
122
+ shows the account and the record, not that the human typed it: agents
123
+ may post under their human's account. Otherwise it is closed.
124
+ - A relay on GitHub (a record that presents itself as an agent reporting
125
+ the human's words) is checked the same way: it must exist at the cited
126
+ link and say that the relaying agent reported the human's acceptance of
127
+ this change. Confirmed, the PR merges as an explicit supersession with
128
+ the acceptance recorded as `source-reported (relay at <link>)`, never as
129
+ verified; otherwise it is closed.
130
+ - A cited record the maintainer cannot read (mail, a session, a call) is
131
+ trusted without a check: the PR merges as an explicit supersession with
132
+ the acceptance recorded as source-reported.
133
+ - `oats okf-maintenance review-context` no longer reports `blocked`, and
134
+ `settled` now means only that the PR is not open.
135
+ - **Re-review each parked PR.** A label left in place is inert, but the
136
+ PR is reviewed again only on a new `harvest-review` event. The trigger
137
+ polls: a close it never saw is no reopen. On the trigger's review host,
138
+ once its lock has 5.7.0:
139
+ 1. Retire the knowledge-maintainer instances left from older reviews,
140
+ running or stopped: a retained home holds a concurrency slot (`max`
141
+ 2, `perKey` 1), and one composed from an older package keeps the old
142
+ behaviour.
143
+ 2. Remove `okf-needs-human` from each parked PR, then close it.
144
+ 3. Wait until `oats trigger status <id> --json` shows a `lastPoll`
145
+ after the closes with `ok: true` and `prs` under 100 (every 2m). Only
146
+ such a poll records a close: a failed poll records none (keep
147
+ waiting), and one that fetched 100 open PRs may be truncated (stop
148
+ and report the poll cap; do not reopen). `oats trigger test` does not
149
+ count: it records nothing.
150
+ 4. Reopen each PR, and check that `oats trigger status <id> --json`
151
+ lists a `pending` or `fired` entry with `event: "reopened"` for each
152
+ PR's number. At most two reviews run at once; the rest wait as `held`
153
+ until a maintainer retires.
154
+
155
+ Never clear the trigger's dedup state.
156
+ - [Knowledge operations: the flow](../knowledge.md#the-flow), step 4,
157
+ says what holds before and after 5.7.0.
158
+
159
+ - **oats.framework 1.16.4: oats.setup 2.9.5.** oats.setup's `/oats-onboarding`
160
+ pins `oats.okf: v5.7.0` in its knowledge section (text only), so a new
161
+ deployment sets up knowledge operations whose review never parks a harvest
162
+ PR. The floors and the other capabilities are unchanged.
163
+ - **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
164
+ `oats.framework: v1.16.4`. New spawns get it, and a stopped home moves with
165
+ `oats instance upgrade`.
package/docs/schedules.md CHANGED
@@ -542,7 +542,14 @@ Otherwise the item is listed with a reason: `assigned-elsewhere`,
542
542
  else or not at all), `host-unnamed`, or `untrusted` (placed here but not
543
543
  trusted: it never runs, and `oats workspace status` warns with the exact
544
544
  line to add). Both names come from a commit, so anyone who can commit to a
545
- member could name your host; trust is the operator's own yes. A trust entry
545
+ member could name your host; trust is the operator's own yes.
546
+
547
+ `oats workspace status` shows the same placement. Under `--max-age <s>` it
548
+ may show it with a `gh` login observed up to `<s>` seconds ago, and it waits
549
+ at most 5 s for `gh` (a `gh` that does not answer in time reads
550
+ `owner-mismatch`): [the `gh` login, display only](desktop-cli-api.md#the-gh-login-display-only).
551
+ What runs never depends on that: a tick, `oats trigger poll` and every run
552
+ ask `gh` live and wait up to 30 s. A trust entry
546
553
  that names no workspace automation is a warning (`automation-trust-stale`),
547
554
  not an error: its member may not have synced yet. Your own `oats trigger
548
555
  add` / `oats schedule add` definitions need no trust.
package/docs/tui.md CHANGED
@@ -2366,10 +2366,27 @@ with the Desktop (`packages/client/`).
2366
2366
  deployment, run with **the kernel it shipped with** (the `bin/oats.mjs` of
2367
2367
  the same install, with the Node that runs the TUI), never an `oats` found
2368
2368
  on `PATH`. Each has 30 seconds and 4 MiB.
2369
- - **Then one probe of the terminals**: a small program of the shared readers
2370
- asks tmux which instances have a live pane (`tmux list-panes`, and `ps`
2371
- for what runs in them). It has 30 seconds. An instance the kernel itself
2372
- reported as unknown is not probed and stays unknown.
2369
+ - **The background reads go through one warm reader** when that kernel
2370
+ lists feature `warm-reader`: `oats reader --stdio`, started once by the
2371
+ TUI as it starts every kernel command (`node <bin> reader --stdio`, in a
2372
+ session of its own), answers them from one process with the same answers
2373
+ as the two commands. A live read (`r`, the return from a suspend, a row
2374
+ opened in the switcher), every read before the reader is ready, and every
2375
+ read it does not answer are the two commands, as above: nothing waits for
2376
+ it and nothing shows it. The rules are the Desktop's: the client rules
2377
+ of [The warm reader](desktop-cli-api.md#the-warm-reader). An install that changed
2378
+ under the run leaves the TUI on the two commands until it is started
2379
+ again. The reader ends when the TUI does: the TUI holds its stdin, and
2380
+ closing it, on the way out or by the TUI's death, ends it.
2381
+ - **Then one probe of the terminals**, only for a kernel without feature
2382
+ `status-liveness`: a small program of the shared readers asks tmux which
2383
+ instances have a live pane (`tmux list-panes`, and `ps` for what runs in
2384
+ them). It has 30 seconds. An instance the kernel itself reported as
2385
+ unknown is not probed and stays unknown. A kernel with the feature reads
2386
+ that itself, live, in `oats status`: no probe runs, and each instance is
2387
+ as the kernel reported it, its tmux record included. An instance home
2388
+ with no tmux record (every spawn records one) then has no terminal to
2389
+ open, where the probe fills in the default session.
2373
2390
  - **Every deployment opened in the run is read each time**, at most two at
2374
2391
  a time.
2375
2392
  - **How often:** 5 seconds after the last read ended; 30 seconds once ten
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.5** ([release notes](release-notes/v0.69.5.md)).
10
- The 0.69.5 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.6** ([release notes](release-notes/v0.69.6.md)).
10
+ The 0.69.6 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.5,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.6,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.5 first
23
- npm install -g @awebai/oats@0.69.5 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.6 first
23
+ npm install -g @awebai/oats@0.69.6 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -172,6 +172,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
172
172
  must follow is in its release's Upgrade section whether or not it is listed
173
173
  here.
174
174
 
175
+ - **[0.69.6](release-notes/v0.69.6.md#upgrade):** the catalog pins oats.okf
176
+ 5.7.0 and oats.framework 1.16.4. On the review host of a workspace's
177
+ harvest-review trigger, re-review each knowledge PR parked on
178
+ `okf-needs-human` as its notes say.
175
179
  - **[0.69.5](release-notes/v0.69.5.md#upgrade):** the catalog pins oats.okf
176
180
  5.6.0 and oats.cloning 1.1.0, which require OATS >=0.69.2. Every host that
177
181
  shares a workspace runs OATS 0.69.2 or later before any of them syncs to
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.16.3 # bare version → resolves through the official catalog
58
- oats.okf: v5.6.0
57
+ oats.framework: v1.16.4 # bare version → resolves through the official catalog
58
+ oats.okf: v5.7.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
package/lib/argv.mjs ADDED
@@ -0,0 +1,41 @@
1
+ /** lib/argv.mjs — how the kernel reads `--flag=value` (docs/desktop-cli-api.md "Flag syntax"): the CLI's
2
+ * dispatch expands its argv here once, and a process answering reads (lib/reader.mjs) expands each request's
3
+ * argv here, so both give a malformed flag the same E_BAD_ARGS. Kernel-private, not exported from `./core`.
4
+ * Dependency-free. */
5
+
6
+ /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
7
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
8
+ /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
9
+ * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
10
+ * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
11
+ * expanded, it would be a flag token every reader sees, which the spaced form can never carry. */
12
+ /** Free-text flags whose inline value may start with `--` (`--message=--deploy failed`). Such a
13
+ * value is kept out of argv, where it would read as a flag (`--message=--clear` must not
14
+ * clear), and flag() answers it from `inline`. */
15
+ const INLINE_TEXT_FLAGS = new Set(["message"]);
16
+ /** Free-text flags whose inline value is always kept whole, the empty one included:
17
+ * `--description=` clears a trigger's or schedule's description. */
18
+ const INLINE_WHOLE_FLAGS = new Set(["description"]);
19
+ export function expandInlineValues(argv) {
20
+ const out = [];
21
+ const inline = new Map();
22
+ let problem;
23
+ for (const a of argv) {
24
+ const eq = a.indexOf("=");
25
+ if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
26
+ const name = a.slice(2, eq), value = a.slice(eq + 1);
27
+ if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
28
+ problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
29
+ out.push(`--${name}`, value);
30
+ }
31
+ return { argv: out, problem, inline };
32
+ }
33
+
34
+ /** A flag's value in an expanded argv (`args`, `inline`: expandInlineValues's): its free text from `inline`, the word
35
+ * after it, `true` when it has none (the next word is absent, empty or another flag), undefined when it is not given.
36
+ * The first `--name` wins. */
37
+ export function flagValue(args, inline, name) {
38
+ const i = args.indexOf(`--${name}`);
39
+ if (i >= 0 && inline.has(name)) return inline.get(name);
40
+ return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
41
+ }
@@ -25,11 +25,13 @@ export function childEnv() {
25
25
  }
26
26
 
27
27
  /** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
28
- * an unreadable oats-local.yaml means no workspace automations (the local jobs still run). */
29
- export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map() } = {}) {
28
+ * an unreadable oats-local.yaml means no workspace automations (the local jobs still run). `remotes`:
29
+ * lib/member-clone.mjs verifyMemberClone's, for a read that verifies the same clones again. `lookup`: the
30
+ * status display's gh login lookup (lib/automations.mjs ghLogin), never an act's. */
31
+ export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map(), remotes, lookup } = {}) {
30
32
  let local = null;
31
33
  try { local = loadLocal(ws).local; } catch { local = null; }
32
- const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local });
33
- const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
34
+ const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local }, { remotes });
35
+ const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf, lookup });
34
36
  return Object.assign(ctx, { ws, local });
35
37
  }