@awebai/oats 0.58.0 → 0.59.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +68 -3
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +11 -0
  5. package/docs/implementation.md +2 -0
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +4 -4
  8. package/docs/official-catalog.md +4 -4
  9. package/docs/packages.md +14 -14
  10. package/docs/release-notes/v0.59.0.md +288 -0
  11. package/docs/servers.md +4 -1
  12. package/docs/souls-and-instances.md +21 -0
  13. package/docs/tui.md +644 -118
  14. package/docs/workspaces.md +2 -2
  15. package/lib/core.mjs +216 -42
  16. package/lib/read-ahead-worker.mjs +119 -0
  17. package/lib/read-ahead.mjs +115 -0
  18. package/lib/retire-state.mjs +33 -0
  19. package/lib/servers.mjs +9 -1
  20. package/lib/session-input.mjs +14 -4
  21. package/package-catalog.json +3 -3
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-data.mjs +4 -0
  25. package/packages/client/deployment-panel.mjs +3 -0
  26. package/packages/client/instance-acts.mjs +23 -8
  27. package/packages/client/instance-presentation.mjs +3 -2
  28. package/packages/client/instance-tree.mjs +84 -39
  29. package/packages/client/lifecycle-confirmation.mjs +9 -3
  30. package/packages/client/remote-roster.mjs +4 -1
  31. package/packages/client/retire-in-flight.mjs +65 -0
  32. package/packages/client/retire-state.mjs +30 -0
  33. package/packages/client/spawn-apply.mjs +13 -4
  34. package/packages/tui/README.md +23 -10
  35. package/packages/tui/lib/actions.mjs +63 -5
  36. package/packages/tui/lib/client.mjs +12 -1
  37. package/packages/tui/lib/config.mjs +7 -2
  38. package/packages/tui/lib/main.mjs +315 -82
  39. package/packages/tui/lib/model.mjs +523 -56
  40. package/packages/tui/lib/panel.mjs +436 -125
  41. package/packages/tui/lib/read.mjs +52 -26
  42. package/packages/tui/lib/store.mjs +908 -65
  43. package/packages/tui/lib/term/keys.mjs +9 -2
  44. package/packages/tui/lib/term/text.mjs +4 -0
  45. package/packages/tui/lib/term/through.mjs +12 -1
  46. package/packages/tui/lib/views/frame.mjs +394 -95
  47. package/packages/tui/lib/views/help.mjs +54 -13
  48. package/packages/tui/lib/views/instances.mjs +43 -25
  49. package/packages/tui/lib/views/palette.mjs +61 -0
  50. package/packages/tui/lib/views/souls.mjs +268 -0
  51. package/packages/tui/lib/views/spawn.mjs +299 -0
  52. package/packages/tui/lib/views/split.mjs +29 -0
  53. package/skills/oats-getting-started/SKILL.md +2 -2
package/bin/oats.mjs CHANGED
@@ -104,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
104
104
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
105
105
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
106
106
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
107
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age"];
107
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size"];
108
108
  /** Commands `--server <id>` runs on a registered server. */
109
109
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
110
110
  const flag = (name) => {
@@ -45,7 +45,8 @@ see the [official catalog](official-catalog.md) for current pins.
45
45
  "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
46
46
  "server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
47
47
  "lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
48
- "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age"],
48
+ "soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
49
+ "status-retire-state","session-inspect-size"],
49
50
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
50
51
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
51
52
  "capabilityShowApi":1}
@@ -122,6 +123,7 @@ see the [official catalog](official-catalog.md) for current pins.
122
123
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
123
124
  | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
124
125
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
126
+ | `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
125
127
  | `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
126
128
  | `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
127
129
  | `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
@@ -132,6 +134,7 @@ see the [official catalog](official-catalog.md) for current pins.
132
134
  | `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
133
135
  | `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
134
136
  | `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
137
+ | `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
135
138
 
136
139
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
137
140
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -2806,8 +2809,9 @@ its absence.
2806
2809
  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
2807
2810
  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
2808
2811
  in the row),
2809
- `identity` when a provider recorded one, `rollbackIncomplete` and
2810
- `retirePending` when present, and the Desktop facts below.
2812
+ `identity` when a provider recorded one, `rollbackIncomplete`,
2813
+ `retirePending` and [`retire`](#row-retire) when present, and the Desktop
2814
+ facts below.
2811
2815
  - <a id="unreadable-record-row"></a>**A home whose `instance.json` cannot be
2812
2816
  read** (OATS 0.52.0) is listed like every other, and one such home never
2813
2817
  fails the listing. Its row has the fields of a home with no `instance.json`
@@ -2846,6 +2850,55 @@ its absence.
2846
2850
  shell or a retained dead pane keeps, so a row with a claim is checked
2847
2851
  against its session (as `oats session inspect` observes it) and reads
2848
2852
  `null` unless a harness runs there.
2853
+ - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
2854
+ 0.59.0): `{state, since, self, code?, message?}` while a retire of the home
2855
+ is running, scheduled or owed; absent otherwise, and from older kernels.
2856
+ `retirePending` keeps its meaning (the self-retire marker is there) and is
2857
+ not replaced. Status only reads: it takes no claim, removes no file and
2858
+ signals no process. `self` is `true` when the self-retire marker
2859
+ (`.oats-retire-pending-<instance>.json`, [souls-and-instances.md](souls-and-instances.md#self-retire-not-completed))
2860
+ is beside the home, whatever the claim says, and `false` for a retire
2861
+ another process runs (an `oats retire` holding the home's claim). The
2862
+ marker is read first:
2863
+
2864
+ | Beside the home | `state` | `self` | `since` |
2865
+ |---|---|---|---|
2866
+ | the marker, and the result file `.oats-retired-<instance>.json` with `ok: false` | `failed`, with `code` and `message` | `true` | the result's `completedAt`, else the marker's `requestedAt` |
2867
+ | the marker, no failed result, its completion process alive | `running` | `true` | the marker's `requestedAt` |
2868
+ | the marker, no failed result, the completion's liveness cannot be read, or the marker names no completion process | `unknown` | `true` | the marker's `requestedAt` |
2869
+ | the marker, no failed result, its completion process gone | `interrupted` | `true` | the marker's `requestedAt` |
2870
+ | a marker that cannot be read as an object | `unknown` | `true` | the marker file's modification time |
2871
+ | no marker; the home's claim held by a retire whose holder is alive | `running` | `false` | the claim's `since` |
2872
+ | no marker; the same, the holder's liveness cannot be read | `unknown` | `false` | the claim's `since` |
2873
+ | no marker; the claim's holder gone, a stop's claim, or no claim | absent | | |
2874
+
2875
+ A result with `ok: true` beside a marker still there reads as no result.
2876
+ `code` is the result's `error.code` when it matches `^E_[A-Z0-9_]+$`, and
2877
+ is left out otherwise (the state stays `failed`); `message` is its
2878
+ `error.message` on one line and cut to a retire's one-line reason (at most
2879
+ 2048 UTF-16 code units, a cut ending in `…`), left out when empty: each is
2880
+ a string or absent, never `null`, and only on `failed`. `since` is always
2881
+ there, an instant as `toISOString()` writes it: the time in the table when
2882
+ it is one, else the marker file's modification time (the claim file's for
2883
+ a claim); a `retire` whose time cannot be read at all is not given. A
2884
+ failed retire that owes the home nothing leaves no marker: its row carries
2885
+ no `retire`, and its agent row's `retireFailures[]` holds the outcome, as
2886
+ before. A retire that was killed while it held the claim leaves a claim
2887
+ whose holder is gone, which reads absent.
2888
+
2889
+ **How the clients read it** (`packages/client/retire-state.mjs`): `since`
2890
+ a string, `self` a boolean, `code` an `E_…` code and `message` a string,
2891
+ each optional field absent or a string, never `null`. Any other field is
2892
+ dropped. A value with any field out of this shape is dropped whole, never
2893
+ repaired, and the row reads as if it had none; it never fails the roster.
2894
+ `retirePending` is read on its own and kept as reported. The Desktop and
2895
+ `oats tui` read `running` and `unknown` as **Retiring…**, `failed` as
2896
+ **Retire failed** (its `message` and `code` shown as OATS's words, through
2897
+ the display filter) and `interrupted` as **Retire didn't finish**. A row
2898
+ with `retirePending` and no `retire` (a kernel without the feature) reads
2899
+ **Retiring…**. `rollbackIncomplete` and `spawnInProgress` are read before
2900
+ it. A remote roster row's `retire` is read by the same rule
2901
+ ([remote rows](#remote-row-retire)).
2849
2902
  - **`modules`** becomes drift rows `{name, from, commit, current, status,
2850
2903
  reason?}` when the workspace was read. `status` is `current`, `moved` or
2851
2904
  `missing` (`reason`: `capability-absent`, `package-absent`, or the member's
@@ -3014,6 +3067,18 @@ route target:
3014
3067
  `producer`) is `null`, and an unknown `reason` or an invalid `message` is
3015
3068
  `null` inside a claim that still counts. As on a local row, the host
3016
3069
  reports a claim only for a running instance.
3070
+ - <a id="remote-row-retire"></a>**`retire`** (feature `status-retire-state`, OATS 0.59.0) is on a row only
3071
+ when the host's row has the key: a host whose kernel predates the feature,
3072
+ and a saved route the host did not list, carry none. When present it is
3073
+ passed through the [local row's](#row-retire) rule again on this side: a
3074
+ `state` that is not one of `running`, `unknown`, `failed`, `interrupted`, a
3075
+ `since` that is not a `toISOString()` instant, a `self` that is not a
3076
+ boolean, or a value that is not an object drops the key; a `code` that is
3077
+ not a kernel code, a `code` or `message` that is not a string, and a `code`
3078
+ or `message` on a state other than `failed` are left out, and `message` is
3079
+ cut to the same bound. `oats status --server
3080
+ <id> --json` relays the host's answer verbatim, `retire` included, as it
3081
+ does every other field.
3017
3082
  - **`addressable`** (0.31): `true` for every row the host reports. Routed
3018
3083
  session and lifecycle commands reach it by `--home`, or by name when the
3019
3084
  name is unique on the host ([addressing](servers.md#run-there); a shared
package/docs/desktop.md CHANGED
@@ -227,9 +227,8 @@ a spawn may run for a long time: its roster row reads **Setting up worktree…**
227
227
  until the worktree is ready, and offers no actions meanwhile. If the spawn was
228
228
  interrupted or a capability couldn't set up the worktree, the spawn was rolled
229
229
  back, and the notification says that nothing was created. A home whose spawn
230
- didn't finish its cleanup reads **Spawn didn't finish**, and one whose retire
231
- didn't finish reads **Retire didn't finish**; both offer only **Retire
232
- instance…**, which completes them. A server spawn whose worktree hooks take
230
+ didn't finish its cleanup reads **Spawn didn't finish**, and offers only
231
+ **Retire instance…**, which completes it. A server spawn whose worktree hooks take
233
232
  more than about a minute is not yet supported from the Desktop; use the CLI on
234
233
  the server. Every dropdown in the app has the
235
234
  same themed look, and its open list follows the light or dark theme.
@@ -257,6 +256,34 @@ With an OATS older than 0.52.0, after an interrupted stop the instance can be
257
256
  started and then cannot be stopped while `.oats-stop-pending.json` exists in
258
257
  its home.
259
258
 
259
+ **A retire in progress reads Retiring…, never as a failure.** An instance's
260
+ roster row reads **Retiring…** while:
261
+
262
+ - OATS reports its retire running, or cannot tell whether the process
263
+ holding the retire still runs;
264
+ - its OATS does not report a retire's state yet (no `retire` on the row)
265
+ and the instance has a retire pending;
266
+ - the Desktop's own retire of it was sent and the roster has not been read
267
+ since its answer came. A retire that OATS refused, or whose plan had
268
+ changed, runs nothing, and the row reads as the roster says at once.
269
+
270
+ A retiring row offers no Start, Stop, Restart or Open, and no inline
271
+ button. **Retire instance…** stays in the row's menu, after its usual
272
+ confirmation: OATS refuses a second retire while one runs, and when the
273
+ holder can't be read it may be the only way on.
274
+
275
+ When the retire has ended without finishing, the row says so and offers only
276
+ **Retire instance…**, which finishes it:
277
+
278
+ - **Retire failed**: a self-retire's completion recorded an error. Its
279
+ reason is OATS's own message, with its code, shown through the same
280
+ display filter as every other text from OATS (control characters and
281
+ line breaks never reach the screen, a long message is cut, a message that
282
+ looks like a secret is withheld). With a code and no message, the reason
283
+ is OATS's code, shown the same way.
284
+ - **Retire didn't finish**: a scheduled completion is gone and left no
285
+ outcome.
286
+
260
287
  ## One workspace, several machines
261
288
 
262
289
  The switcher lists each workspace once, however many deployments it has: the
@@ -1039,6 +1039,17 @@ oats session attach --home /abs/home --detach-key 'C-\'
1039
1039
  harness, `shell` for a fallback shell,
1040
1040
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
1041
1041
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
1042
+ With feature `session-inspect-size` in `oats version --json`, a present
1043
+ terminal also reports `size: { cols, rows }`: positive integer window width
1044
+ and height in cells. The kernel reads tmux's `window_width` and
1045
+ `window_height` in the same call as the pane identity, so a viewer can open
1046
+ its PTY at the window's current size without constructing a tmux target.
1047
+ Split windows remain refused. `size` is absent when `present` is false,
1048
+ including a retained dead pane. Malformed dimensions are an
1049
+ `E_SESSION_UNAVAILABLE` error containing `invalid tmux pane response`.
1050
+ `session inspect --server <id> --home <home> --json` relays the execution
1051
+ host's size; check that host's feature list before relying on it. This is a
1052
+ snapshot: inspect again to observe a resize.
1042
1053
  A home without its session receipt is refused with
1043
1054
  `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
1044
1055
  spelling that differs from the on-disk one, the path a kernel before 0.49.0
@@ -120,7 +120,9 @@ and the rules its tests pin.
120
120
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
121
121
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
122
122
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
123
+ | `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
123
124
  | `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 |
125
+ | `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 |
124
126
  | `servers.mjs` | routing commands to a registered server |
125
127
  | `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 |
126
128
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.2.0
44
- oats.aweb: v1.27.3
43
+ oats.okf: v5.2.1
44
+ oats.aweb: v1.28.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
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.2.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.2.1** (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 |
@@ -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.2.0
28
+ oats.okf: v5.2.1
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,10 +50,10 @@ 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. For 5.2.0, OATS >=0.49.0 remains required:
53
+ just editing a version line. For 5.2.1, OATS >=0.49.0 remains required:
54
54
  that kernel first supports the public source-event lookup after retirement.
55
55
 
56
- **Upgrade:** pin `oats.okf: v5.2.0` and run `oats sync`. Only new spawns get
56
+ **Upgrade:** pin `oats.okf: v5.2.1` and run `oats sync`. Only new spawns get
57
57
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
58
  homes keep their copied provider even after a session restart. Deployments
59
59
  whose briefings never mentioned harvesting now get knowledge proposals at
@@ -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.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
12
+ | `oats.framework` | `oats-framework/v1.12.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.28.0` | `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.2.0`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.2.1`); `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.2.0 # bare version → the official catalog
47
+ oats.okf: v5.2.1 # 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.2.0`, `5.2.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.2.1`, `5.2.1`, `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.2.0` or `oats-framework/v1.12.0`) and the payload path. An id
54
+ convention (`v5.2.1` or `oats-framework/v1.12.2`) 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.12.0
78
- oats.okf: v5.2.0
79
- oats.aweb: v1.27.3
77
+ oats.framework: v1.12.2
78
+ oats.okf: v5.2.1
79
+ oats.aweb: v1.28.0
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.2.0 ✓ (@ 2ac86ccb)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.1 ✓ (@ 72e989b9)
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.3 # a catalog version
137
+ oats package add oats.aweb v1.28.0 # 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.2.0",
164
- "commit": "2ac86ccba6ea3da19acf43274dd6d30ab2037653",
163
+ "version": "5.2.1",
164
+ "commit": "72e989b926e8ac1b7b912785beff396d1fc41cbb",
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.2.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.0", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.2", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.12.0`
362
- resolves to tag `oats-framework/v1.12.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.12.2`
362
+ resolves to tag `oats-framework/v1.12.2`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.