@awebai/oats 0.58.0 → 0.60.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 (63) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +80 -8
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +18 -2
  5. package/docs/implementation.md +3 -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/release-notes/v0.60.0.md +104 -0
  12. package/docs/servers.md +4 -1
  13. package/docs/souls-and-instances.md +21 -0
  14. package/docs/tui.md +753 -119
  15. package/docs/workspaces.md +2 -2
  16. package/lib/core.mjs +258 -57
  17. package/lib/read-ahead-worker.mjs +119 -0
  18. package/lib/read-ahead.mjs +115 -0
  19. package/lib/retire-state.mjs +33 -0
  20. package/lib/servers.mjs +9 -1
  21. package/lib/session-input.mjs +53 -26
  22. package/package-catalog.json +3 -3
  23. package/package.json +1 -1
  24. package/packages/client/capability-catalog.mjs +93 -0
  25. package/packages/client/capability-facts.mjs +59 -0
  26. package/packages/client/capability-rows.mjs +121 -0
  27. package/packages/client/catalog-messages.mjs +12 -0
  28. package/packages/client/cli-locator.mjs +2 -2
  29. package/packages/client/deployment-data.mjs +4 -0
  30. package/packages/client/deployment-panel.mjs +3 -0
  31. package/packages/client/instance-acts.mjs +23 -8
  32. package/packages/client/instance-presentation.mjs +3 -2
  33. package/packages/client/instance-tree.mjs +84 -39
  34. package/packages/client/lifecycle-confirmation.mjs +9 -3
  35. package/packages/client/remote-roster.mjs +4 -1
  36. package/packages/client/retire-in-flight.mjs +65 -0
  37. package/packages/client/retire-state.mjs +30 -0
  38. package/packages/client/soul-catalog.mjs +8 -0
  39. package/packages/client/soul-facts.mjs +7 -0
  40. package/packages/client/spawn-apply.mjs +13 -4
  41. package/packages/client/spawn-messages.mjs +8 -0
  42. package/packages/client/subsequence-score.mjs +15 -0
  43. package/packages/tui/README.md +23 -10
  44. package/packages/tui/lib/actions.mjs +63 -5
  45. package/packages/tui/lib/client.mjs +17 -1
  46. package/packages/tui/lib/config.mjs +7 -2
  47. package/packages/tui/lib/main.mjs +364 -82
  48. package/packages/tui/lib/model.mjs +614 -57
  49. package/packages/tui/lib/panel.mjs +436 -125
  50. package/packages/tui/lib/read.mjs +52 -26
  51. package/packages/tui/lib/store.mjs +1025 -65
  52. package/packages/tui/lib/term/keys.mjs +9 -2
  53. package/packages/tui/lib/term/text.mjs +4 -0
  54. package/packages/tui/lib/term/through.mjs +12 -1
  55. package/packages/tui/lib/views/capabilities.mjs +239 -0
  56. package/packages/tui/lib/views/frame.mjs +433 -99
  57. package/packages/tui/lib/views/help.mjs +61 -15
  58. package/packages/tui/lib/views/instances.mjs +43 -25
  59. package/packages/tui/lib/views/palette.mjs +66 -0
  60. package/packages/tui/lib/views/souls.mjs +270 -0
  61. package/packages/tui/lib/views/spawn.mjs +301 -0
  62. package/packages/tui/lib/views/split.mjs +29 -0
  63. 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
@@ -2797,8 +2800,13 @@ its absence.
2797
2800
  redacted) plus `home` and `instance` (from the directory; a disagreeing
2798
2801
  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
2799
2802
  the row's recorded tmux socket and session, never the caller's `$TMUX`;
2803
+ `true` means the harness is running, using the same pane and shell-descendant
2804
+ rule as session inspection. A fallback shell is `false` with `runtimeState:
2805
+ "shell"`, even though the window remains; a dead pane or absent window is
2806
+ `false`. A wrapper shell with a live non-shell descendant stays `true`;
2800
2807
  `null` with `runtimeState: "unreachable"` and the tmux error as
2801
- `runtimeError` when that server cannot be read, and also when its socket
2808
+ `runtimeError` when that server or its panes cannot be read (including a split
2809
+ agent window or a failed shell-descendant process scan), and also when its socket
2802
2810
  file is missing while a process works in the home or the process scan
2803
2811
  cannot run, `runtimeError` then naming the processes or the scan's error
2804
2812
  ([#624](execution-targets.md#missing-socket); with no process in the home
@@ -2806,8 +2814,9 @@ its absence.
2806
2814
  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
2807
2815
  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
2808
2816
  in the row),
2809
- `identity` when a provider recorded one, `rollbackIncomplete` and
2810
- `retirePending` when present, and the Desktop facts below.
2817
+ `identity` when a provider recorded one, `rollbackIncomplete`,
2818
+ `retirePending` and [`retire`](#row-retire) when present, and the Desktop
2819
+ facts below.
2811
2820
  - <a id="unreadable-record-row"></a>**A home whose `instance.json` cannot be
2812
2821
  read** (OATS 0.52.0) is listed like every other, and one such home never
2813
2822
  fails the listing. Its row has the fields of a home with no `instance.json`
@@ -2842,10 +2851,61 @@ its absence.
2842
2851
  waiting"). Its rules are the events read's ([Waiting on you](#waiting-on-you)):
2843
2852
  one bounded read of the home's log per running row. A remote roster row
2844
2853
  carries what the remote kernel reports; an older kernel omits the field.
2845
- `running` is the window's presence, which a crashed harness's fallback
2846
- shell or a retained dead pane keeps, so a row with a claim is checked
2847
- against its session (as `oats session inspect` observes it) and reads
2848
- `null` unless a harness runs there.
2854
+ From OATS 0.60.0 `running` is the harness's liveness, so a fallback shell
2855
+ or a retained dead pane already reads `running: false` and carries no
2856
+ claim; the claim still needs the home's session receipt to name a target.
2857
+ An older kernel's `running` is the window's presence, and it checks a row
2858
+ with a claim against its session (as `oats session inspect` observes it),
2859
+ reading `null` unless a harness runs there.
2860
+ - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
2861
+ 0.59.0): `{state, since, self, code?, message?}` while a retire of the home
2862
+ is running, scheduled or owed; absent otherwise, and from older kernels.
2863
+ `retirePending` keeps its meaning (the self-retire marker is there) and is
2864
+ not replaced. Status only reads: it takes no claim, removes no file and
2865
+ signals no process. `self` is `true` when the self-retire marker
2866
+ (`.oats-retire-pending-<instance>.json`, [souls-and-instances.md](souls-and-instances.md#self-retire-not-completed))
2867
+ is beside the home, whatever the claim says, and `false` for a retire
2868
+ another process runs (an `oats retire` holding the home's claim). The
2869
+ marker is read first:
2870
+
2871
+ | Beside the home | `state` | `self` | `since` |
2872
+ |---|---|---|---|
2873
+ | 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` |
2874
+ | the marker, no failed result, its completion process alive | `running` | `true` | the marker's `requestedAt` |
2875
+ | 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` |
2876
+ | the marker, no failed result, its completion process gone | `interrupted` | `true` | the marker's `requestedAt` |
2877
+ | a marker that cannot be read as an object | `unknown` | `true` | the marker file's modification time |
2878
+ | no marker; the home's claim held by a retire whose holder is alive | `running` | `false` | the claim's `since` |
2879
+ | no marker; the same, the holder's liveness cannot be read | `unknown` | `false` | the claim's `since` |
2880
+ | no marker; the claim's holder gone, a stop's claim, or no claim | absent | | |
2881
+
2882
+ A result with `ok: true` beside a marker still there reads as no result.
2883
+ `code` is the result's `error.code` when it matches `^E_[A-Z0-9_]+$`, and
2884
+ is left out otherwise (the state stays `failed`); `message` is its
2885
+ `error.message` on one line and cut to a retire's one-line reason (at most
2886
+ 2048 UTF-16 code units, a cut ending in `…`), left out when empty: each is
2887
+ a string or absent, never `null`, and only on `failed`. `since` is always
2888
+ there, an instant as `toISOString()` writes it: the time in the table when
2889
+ it is one, else the marker file's modification time (the claim file's for
2890
+ a claim); a `retire` whose time cannot be read at all is not given. A
2891
+ failed retire that owes the home nothing leaves no marker: its row carries
2892
+ no `retire`, and its agent row's `retireFailures[]` holds the outcome, as
2893
+ before. A retire that was killed while it held the claim leaves a claim
2894
+ whose holder is gone, which reads absent.
2895
+
2896
+ **How the clients read it** (`packages/client/retire-state.mjs`): `since`
2897
+ a string, `self` a boolean, `code` an `E_…` code and `message` a string,
2898
+ each optional field absent or a string, never `null`. Any other field is
2899
+ dropped. A value with any field out of this shape is dropped whole, never
2900
+ repaired, and the row reads as if it had none; it never fails the roster.
2901
+ `retirePending` is read on its own and kept as reported. The Desktop and
2902
+ `oats tui` read `running` and `unknown` as **Retiring…**, `failed` as
2903
+ **Retire failed** (its `message` and `code` shown as OATS's words, through
2904
+ the display filter) and `interrupted` as **Retire didn't finish**. A row
2905
+ with `retirePending` and no `retire` (a kernel without the feature) reads
2906
+ **Retiring…**. `rollbackIncomplete` and `spawnInProgress` are read before
2907
+ it. A remote roster row's `retire` is read by the same rule
2908
+ ([remote rows](#remote-row-retire)).
2849
2909
  - **`modules`** becomes drift rows `{name, from, commit, current, status,
2850
2910
  reason?}` when the workspace was read. `status` is `current`, `moved` or
2851
2911
  `missing` (`reason`: `capability-absent`, `package-absent`, or the member's
@@ -3014,6 +3074,18 @@ route target:
3014
3074
  `producer`) is `null`, and an unknown `reason` or an invalid `message` is
3015
3075
  `null` inside a claim that still counts. As on a local row, the host
3016
3076
  reports a claim only for a running instance.
3077
+ - <a id="remote-row-retire"></a>**`retire`** (feature `status-retire-state`, OATS 0.59.0) is on a row only
3078
+ when the host's row has the key: a host whose kernel predates the feature,
3079
+ and a saved route the host did not list, carry none. When present it is
3080
+ passed through the [local row's](#row-retire) rule again on this side: a
3081
+ `state` that is not one of `running`, `unknown`, `failed`, `interrupted`, a
3082
+ `since` that is not a `toISOString()` instant, a `self` that is not a
3083
+ boolean, or a value that is not an object drops the key; a `code` that is
3084
+ not a kernel code, a `code` or `message` that is not a string, and a `code`
3085
+ or `message` on a state other than `failed` are left out, and `message` is
3086
+ cut to the same bound. `oats status --server
3087
+ <id> --json` relays the host's answer verbatim, `retire` included, as it
3088
+ does every other field.
3017
3089
  - **`addressable`** (0.31): `true` for every row the host reports. Routed
3018
3090
  session and lifecycle commands reach it by `--home`, or by name when the
3019
3091
  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
@@ -51,8 +51,13 @@ deployment's `session.tmuxSession`, else `OATS_TMUX_SESSION`, else
51
51
  session it recorded, and `oats status` reads each home on its recorded tmux
52
52
  socket and session, never the caller's `$TMUX` server: a caller outside the
53
53
  agents' tmux (ssh, cron, a plain terminal) sees the same liveness as `session
54
- inspect`. A recorded server that cannot be read gives `running: null` with
55
- `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
54
+ inspect`. `running` means the harness is running, not merely that its window
55
+ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
56
+ a retained dead pane also reads `false`. A wrapper shell with a live non-shell
57
+ descendant still reads `true`. Status shares session inspection's pane rule,
58
+ with one batched pane read per socket/session and one lazy process scan across
59
+ all shell panes. A recorded server or pane that cannot be read gives
60
+ `running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
56
61
  inspect --json` reports the session a new spawn would open in as `session`
57
62
  (`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
58
63
  session it would open in, on the OATS tmux server (`E_INSTANCE_NAME_TAKEN`); a
@@ -1039,6 +1044,17 @@ oats session attach --home /abs/home --detach-key 'C-\'
1039
1044
  harness, `shell` for a fallback shell,
1040
1045
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
1041
1046
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
1047
+ With feature `session-inspect-size` in `oats version --json`, a present
1048
+ terminal also reports `size: { cols, rows }`: positive integer window width
1049
+ and height in cells. The kernel reads tmux's `window_width` and
1050
+ `window_height` in the same call as the pane identity, so a viewer can open
1051
+ its PTY at the window's current size without constructing a tmux target.
1052
+ Split windows remain refused. `size` is absent when `present` is false,
1053
+ including a retained dead pane. Malformed dimensions are an
1054
+ `E_SESSION_UNAVAILABLE` error containing `invalid tmux pane response`.
1055
+ `session inspect --server <id> --home <home> --json` relays the execution
1056
+ host's size; check that host's feature list before relying on it. This is a
1057
+ snapshot: inspect again to observe a resize.
1042
1058
  A home without its session receipt is refused with
1043
1059
  `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
1044
1060
  spelling that differs from the on-disk one, the path a kernel before 0.49.0
@@ -120,7 +120,10 @@ 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 |
126
+ | `session-input.mjs` | session inspection and input transport. `createSessionPaneInspector` interprets one window's panes 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 |
124
127
  | `servers.mjs` | routing commands to a registered server |
125
128
  | `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
129
  | `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.29.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.3` (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.29.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.3`) 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.3
78
+ oats.okf: v5.2.1
79
+ oats.aweb: v1.29.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.29.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.3", "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.3`
362
+ resolves to tag `oats-framework/v1.12.3`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.