@awebai/oats 0.59.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 (35) hide show
  1. package/docs/desktop-cli-api.md +12 -5
  2. package/docs/execution-targets.md +7 -2
  3. package/docs/implementation.md +1 -0
  4. package/docs/integrations.md +1 -1
  5. package/docs/official-catalog.md +2 -2
  6. package/docs/packages.md +7 -7
  7. package/docs/release-notes/v0.60.0.md +104 -0
  8. package/docs/tui.md +123 -15
  9. package/docs/workspaces.md +1 -1
  10. package/lib/core.mjs +42 -15
  11. package/lib/session-input.mjs +45 -28
  12. package/package-catalog.json +2 -2
  13. package/package.json +1 -1
  14. package/packages/client/capability-catalog.mjs +93 -0
  15. package/packages/client/capability-facts.mjs +59 -0
  16. package/packages/client/capability-rows.mjs +121 -0
  17. package/packages/client/catalog-messages.mjs +12 -0
  18. package/packages/client/cli-locator.mjs +2 -2
  19. package/packages/client/soul-catalog.mjs +8 -0
  20. package/packages/client/soul-facts.mjs +7 -0
  21. package/packages/client/spawn-messages.mjs +8 -0
  22. package/packages/client/subsequence-score.mjs +15 -0
  23. package/packages/tui/README.md +1 -1
  24. package/packages/tui/lib/actions.mjs +1 -1
  25. package/packages/tui/lib/client.mjs +7 -2
  26. package/packages/tui/lib/main.mjs +58 -9
  27. package/packages/tui/lib/model.mjs +136 -46
  28. package/packages/tui/lib/store.mjs +133 -16
  29. package/packages/tui/lib/views/capabilities.mjs +239 -0
  30. package/packages/tui/lib/views/frame.mjs +55 -20
  31. package/packages/tui/lib/views/help.mjs +9 -4
  32. package/packages/tui/lib/views/palette.mjs +9 -4
  33. package/packages/tui/lib/views/souls.mjs +6 -4
  34. package/packages/tui/lib/views/spawn.mjs +5 -3
  35. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -2800,8 +2800,13 @@ its absence.
2800
2800
  redacted) plus `home` and `instance` (from the directory; a disagreeing
2801
2801
  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
2802
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`;
2803
2807
  `null` with `runtimeState: "unreachable"` and the tmux error as
2804
- `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
2805
2810
  file is missing while a process works in the home or the process scan
2806
2811
  cannot run, `runtimeError` then naming the processes or the scan's error
2807
2812
  ([#624](execution-targets.md#missing-socket); with no process in the home
@@ -2846,10 +2851,12 @@ its absence.
2846
2851
  waiting"). Its rules are the events read's ([Waiting on you](#waiting-on-you)):
2847
2852
  one bounded read of the home's log per running row. A remote roster row
2848
2853
  carries what the remote kernel reports; an older kernel omits the field.
2849
- `running` is the window's presence, which a crashed harness's fallback
2850
- shell or a retained dead pane keeps, so a row with a claim is checked
2851
- against its session (as `oats session inspect` observes it) and reads
2852
- `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.
2853
2860
  - <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
2854
2861
  0.59.0): `{state, since, self, code?, message?}` while a retire of the home
2855
2862
  is running, scheduled or owed; absent otherwise, and from older kernels.
@@ -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
@@ -123,6 +123,7 @@ and the rules its tests pin.
123
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 |
124
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
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 |
126
127
  | `servers.mjs` | routing commands to a registered server |
127
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 |
128
129
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v5.2.1
44
- oats.aweb: v1.28.0
44
+ oats.aweb: v1.29.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -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.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.12.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
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) | |
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` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
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.1` or `oats-framework/v1.12.2`) 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.2
77
+ oats.framework: v1.12.3
78
78
  oats.okf: v5.2.1
79
- oats.aweb: v1.28.0
79
+ oats.aweb: v1.29.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -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.28.0 # 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
  ```
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
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" }
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.2`
362
- resolves to tag `oats-framework/v1.12.2`. 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.
@@ -0,0 +1,104 @@
1
+ # OATS 0.60.0
2
+
3
+ 2026-10-16
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.59 Desktop refuses a 0.60.0 CLI. The
9
+ 0.60.0 Desktop accepts OATS CLIs `>=0.26.0 <0.61.0`.
10
+
11
+ - **`running` in a status row now means the harness is running**
12
+ ([#364](https://github.com/awebai/oats/issues/364)). A window left at its
13
+ fallback shell after Stop reads `running: false`, `runtimeState: "shell"`;
14
+ before, it read `true` because the window existed. A script or tool that
15
+ reads `oats status --json` to see whether an agent is running now gets the
16
+ answer the lifecycle commands give. See Changed.
17
+
18
+ - **The official catalog moves two pins:** oats.framework 1.12.2 → 1.12.3
19
+ and oats.aweb 1.28.0 → 1.29.0 (see Provider updates). The other packages
20
+ are unchanged. A deployment takes them by changing its pins and running
21
+ `oats sync`. Only new spawns use them.
22
+
23
+ ## Added
24
+
25
+ - **`oats tui` lists the open workspace's capabilities**
26
+ ([#855](https://github.com/awebai/oats/issues/855)). `3`, or the leader
27
+ then `3`, shows the Capabilities view, which until now was a placeholder:
28
+ the capabilities in the OATS Desktop's sections (Workspace owned, Repo
29
+ owned, Packages), grouped by repository or package, each with its layer.
30
+ The detail beside it says what the capability is, where it comes from,
31
+ the skills, commands and hooks it provides, and the souls that use it,
32
+ each with how many of its instances here carry it and how many of those
33
+ are on an older version. In the detail, `Up`/`Down` mark a soul and
34
+ `Enter` shows it in the Souls view. The list is the Desktop's, read with
35
+ `oats capabilities` only once the view is first shown, and again only
36
+ when the workspace changes, or with `r`. The palette lists the
37
+ capabilities once they are read. See
38
+ [the TUI page](../tui.md#the-capabilities-view).
39
+
40
+ ## Changed
41
+
42
+ - **`oats status` reports whether the harness is running**
43
+ ([#364](https://github.com/awebai/oats/issues/364)). After Stop leaves a
44
+ fallback shell, the row reads `running: false` with `runtimeState: "shell"`,
45
+ even though its tmux window remains. A live harness remains running, and an
46
+ unreadable session remains unknown. Pane reads are batched per socket and
47
+ session.
48
+
49
+ - **OATS Desktop accepts an `oats` CLI 0.60.x.** Its band is now
50
+ `>=0.26.0 <0.61.0`. 0.60 adds no new gate on the band: a status row's
51
+ `running: false` with `runtimeState: "shell"` for a window at its fallback
52
+ shell is what the Desktop's own terminal probe already reports for a local
53
+ row, and a server's rows now read the same way.
54
+
55
+ - **`oats tui` polish** ([#855](https://github.com/awebai/oats/issues/855)).
56
+ The footer names `[/] tab` while two tabs or more are open. The help's
57
+ Marks section lists the soul mark `■` (`#` in ASCII) and a refused soul's
58
+ `!`. A split one above the other joins the list's bar with `├` (`+` in
59
+ ASCII).
60
+
61
+ ## Fixed
62
+
63
+ - **`r` in the `oats tui` Souls view keeps the souls when the read fails**
64
+ ([#1301](https://github.com/awebai/oats/issues/1301)). In 0.59.0, `r`
65
+ forgot the souls before reading them again, so a read that failed left
66
+ only the failure. Now the souls stay listed while `r` reads, and a read
67
+ that fails keeps them under a heading that says it failed, as the
68
+ Capabilities view does. See [the TUI page](../tui.md#the-souls-view).
69
+
70
+ - **`oats tui`: a package soul's instances are its own in the Souls view**
71
+ ([#855](https://github.com/awebai/oats/issues/855)). In 0.59.0 the Souls
72
+ view counted no instances for a soul that comes from a package, and `i`
73
+ on it listed none: the view did not match the name its instances carry,
74
+ `<package>--<soul>`. Its row now counts its instances on this machine,
75
+ `i` lists them in the Instances view, and its detail names them. See
76
+ [the TUI page](../tui.md#the-souls-view).
77
+
78
+ ## Provider updates
79
+
80
+ - **oats.framework 1.12.3, oats.core 2.6.3: `/oats-operate` says what
81
+ `running` means** ([#364](https://github.com/awebai/oats/issues/364)).
82
+ From OATS 0.60.0, a status row's `running` is the harness's liveness: a
83
+ window left at its fallback shell after Stop reads `running: false`,
84
+ `runtimeState: "shell"`. The skill dates the rule, since an older kernel
85
+ still reports such a window as running. Instruction text only; the floors
86
+ are unchanged. A deployment gets it by pinning `oats.framework: v1.12.3`
87
+ and running `oats sync`.
88
+
89
+ - **oats.aweb 1.29.0: the agent status publisher.** The catalog and this
90
+ workspace pin `oats.aweb: v1.29.0`.
91
+ - `oats aweb health enable | status | disable | publish` publishes, once a
92
+ minute, a signed status for every agent of the deployment to aweb:
93
+ whether it can be reached (`yes`, `degraded`, `no` or `unknown`), why
94
+ not, and who fixes it. It is opt-in and host-only
95
+ (`settings.oats.aweb.health` in `oats-local.yaml`), runs in the
96
+ deployment directory, never inside an instance, and needs aw 1.36.38 to
97
+ publish (checked before anything is sent). `disable` clears every
98
+ designation it made.
99
+ - `/oats-aweb`: on macOS, `oats aweb wake install` runs from the desktop
100
+ login, not over ssh.
101
+ - The floors are unchanged (OATS >=0.52.0, aw >=1.36.33). A deployment
102
+ gets it by pinning `oats.aweb: v1.29.0` and running `oats sync`; only
103
+ new spawns use it. The provider's reference is its
104
+ `docs/health-publisher.md`.
package/docs/tui.md CHANGED
@@ -109,9 +109,9 @@ runs.
109
109
  open them in the list, and [the leader](#the-leader) then `1`, `2` or `3`
110
110
  from anywhere; the leader's hint, [the palette](#the-palette) and the
111
111
  help name those keys. [The Souls view](#the-souls-view) lists the open
112
- workspace's souls; the Capabilities view says what it will hold and what
113
- to run until then, `oats capabilities`. On the right is the time of the
114
- read of this machine that the screen shows: it moves with every read.
112
+ workspace's souls, and [the Capabilities view](#the-capabilities-view)
113
+ its capabilities. On the right is the time of the read of this machine
114
+ that the screen shows: it moves with every read.
115
115
  - **The footer** is one row of keys from the first column, with no rule
116
116
  above it. It names `C-\ commands` first, in every focus: the leader,
117
117
  which reaches every action. Then come the actions that apply now, as many
@@ -402,7 +402,10 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
402
402
  it is asked, hold a place among the four. An instance that cannot be
403
403
  opened says why, as it does with no tab open.
404
404
  - **Switching.** `[` and `]` in the Instances view, from the list or the
405
- detail, show the tab before or after the shown one. The leader then
405
+ detail, show the tab before or after the shown one; the footer names them
406
+ (`[/] tab`) after the terminal's keys while two tabs or more are open, and
407
+ gives them up after the acts, `workspaces`, `refresh` and `close`, before
408
+ `detail`. The leader then
406
409
  `Left` or `Right` does the same from any focus, and from another view
407
410
  goes to the Instances view first.
408
411
  - The strip does not wrap: on the first tab `[` does nothing, and on the
@@ -562,7 +565,9 @@ them, from the same code.
562
565
  nothing. `Esc` closes the detail, then clears a kept filter, then goes
563
566
  back to the instances.
564
567
  - **When it reads:** the first time the view is shown, never before: a run
565
- that never shows it never runs `oats souls`. After that, a read of the
568
+ that never shows it, nor [the Capabilities
569
+ view](#the-capabilities-view) or [the spawn prompt](#spawning-an-agent),
570
+ which need the souls too, never runs `oats souls`. After that, a read of the
566
571
  workspace reads the souls again only when the workspace changed (its
567
572
  commit, a member's, its externals), and `r` does. While the first read is
568
573
  under way the view says `Reading souls…`. A read that fails says why,
@@ -577,6 +582,98 @@ them, from the same code.
577
582
  `n` or `N` spawns an agent of the selected soul: [Spawning an
578
583
  agent](#spawning-an-agent).
579
584
 
585
+ ## The Capabilities view
586
+
587
+ `3`, or the leader then `3`, shows the capabilities of the open workspace:
588
+ the ones its repositories and its packages offer, as the OATS Desktop lists
589
+ them, from the same code.
590
+
591
+ ```
592
+ acme-platform 3 running
593
+ Instances Souls Capabilities read 14:03:27
594
+ ──────────────────────────────────────┬─────────────────────────────────────────
595
+ Workspace owned │ aweb Messaging
596
+ oats · member repo · host │ Messaging over aweb, mail and chat,
597
+ > aweb Messaging │ for every instance of the workspace.
598
+ tools · member repo │
599
+ notes │ Comes from
600
+ Packages │ Repository oats
601
+ oats-okf · package · v1.2.0 │ Latest bbbbbbb
602
+ okf-knowledge Knowledge │ Path capabilities/aweb
603
+ │
604
+ │ Provides
605
+ │ Skills oats-aweb, aweb-messaging
606
+ │ Hooks SessionStart
607
+ │
608
+ │ Used by 2 souls
609
+ │ ■ dev ·2 · 1 on an older version
610
+ │ ■ reviewer ·1
611
+ ```
612
+
613
+ - **The list** is in the Desktop's sections: Workspace owned, Repo owned
614
+ and Packages. A section with no capability is not drawn, so Repo owned
615
+ stands only when the workspace has one. Under a section each repository
616
+ or package has a dim heading, its name and a note: `oats · member repo ·
617
+ host` (`-` in ASCII). A row is the capability's name, then its layer's
618
+ label, dim, when it has one: `Knowledge`, `Messaging`, `Tasks`. The list
619
+ keys move among the capabilities and pass over the headings. `/` filters
620
+ by name, and a group or a section the filter leaves empty is hidden. A
621
+ workspace with none says so, and that `oats capabilities` says why.
622
+ - **The detail** beside it, top to bottom:
623
+ - the name, its layer's label and the description;
624
+ - **Comes from**, a label and a value a line: for a repository's
625
+ capability its repository, its latest commit, its path and its
626
+ fingerprint, and for a repo-owned one that it is that repository's
627
+ souls' only; for a package's, the package, the version it is pinned to
628
+ and where that comes from, the commit and the fingerprint;
629
+ - **Provides**: its skills, commands and hooks, each kind the kernel
630
+ reports with its names; a kind it could not list says `Not listable: a
631
+ spawn of it would refuse.`, and one with no name `None`;
632
+ - **Used by**, with the count of souls beside it: one line per soul, its
633
+ colour mark (as in the Souls view), its name, a dim count of its
634
+ instances on this machine that carry the capability, `·2` (`x2` in
635
+ ASCII; `·0` too), and, when some of them are on an older version of
636
+ it, `· 1 on an older version` in the warning style. Eight at most, then
637
+ `+n`. With an OATS that reports what each soul is composed of (the
638
+ `souls-capabilities` feature, 0.45.0), these are the souls that include
639
+ it, and with none it says `No soul here includes it.` With an older
640
+ OATS they are the souls whose instances carry it, and with none it says
641
+ `No instance carries it yet.` A soul the souls catalog does not list is
642
+ drawn uncoloured. With the feature, until the souls are read it says
643
+ `Reading souls…`, and a read of them that fails says why, in the
644
+ warning style.
645
+ - **`Enter`** gives the detail the focus (under 80 columns it takes the
646
+ list's place), with a mark, `>` in reverse video, on the first soul of
647
+ Used by. `Up` and `Down` move the mark among the listed souls, and the
648
+ detail scrolls to keep it in sight. Past the first or the last soul, and
649
+ with the other movement keys, the detail scrolls; with no soul listed
650
+ every movement key scrolls it. `Enter` on the marked soul shows it in
651
+ [the Souls view](#the-souls-view), selected; on a soul the souls catalog
652
+ does not list it does nothing. `Tab` moves between the list and the
653
+ detail.
654
+ - **`r`** reads the capabilities again; while a read is under way it starts
655
+ nothing. `Esc` closes the detail, then clears a kept filter, then goes
656
+ back to the instances.
657
+ - **When it reads:** the first time the view is shown, never before: a run
658
+ that never shows it never runs `oats capabilities`. It reads the souls
659
+ too, for Used by, when they were not read yet. After that, a read of the
660
+ workspace reads the capabilities again only when the workspace changed
661
+ (its commit, a member's, its externals, its packages or its lock), and
662
+ `r` does. While the first read is under way the view says `Reading
663
+ capabilities…`. A read that fails says why, `Couldn't read this
664
+ workspace's capabilities:` and the message, with `r` to try again; one
665
+ that fails after a good one keeps the capabilities it had, under a
666
+ heading that says it failed and when they were read; the selected
667
+ capability's detail says why in full, under its name.
668
+ - **What is kept:** the selected capability and the filter, when the view
669
+ is left and shown again, for the run.
670
+ - **Only this machine's:** the view lists the capabilities of a workspace of
671
+ this machine. With none open it says so.
672
+
673
+ [The palette](#the-palette) lists the capabilities once they are read,
674
+ each with where it comes from; choosing one shows this view with it
675
+ selected.
676
+
580
677
  ## The switcher
581
678
 
582
679
  `w` opens the switcher: what this run can show, over the whole body of the
@@ -827,7 +924,7 @@ The line after leaving says so and names `oats status` to see it.
827
924
  | `r` | read now |
828
925
  | `1` | the Instances view |
829
926
  | `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
830
- | `3` | the Capabilities view, which says what it will hold and what to run until then; `Esc` or `1` goes back |
927
+ | `3` | [the Capabilities view](#the-capabilities-view); `Esc` or `1` goes back |
831
928
  | `w` | opens [the switcher](#the-switcher) |
832
929
  | `Enter` | in the list of instances, opens the selected agent's terminal in a new [tab](#tabs) beside the list, or shows its tab when it has one, with the focus in it; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
833
930
  | `z` | gives the shown terminal the focus and the whole body |
@@ -919,15 +1016,19 @@ is open no terminal is drawn and the TUI reads the keys.
919
1016
  recently opened or shown in this run first (when the first is the shown tab's,
920
1017
  the second is selected as it opens), then the list's order, each with its
921
1018
  state mark, its name and, for another machine, `on <machine>`; the souls
922
- of the open workspace, once [the Souls view](#the-souls-view) has read
923
- them (choosing one shows that view with it selected; the palette never
924
- reads them); the views, Instances, Souls and Capabilities; the acts the
1019
+ of the open workspace, once they were read (by [the Souls
1020
+ view](#the-souls-view), the Capabilities view or a spawn), and choosing
1021
+ one shows the Souls view with it selected; its capabilities, once [the
1022
+ Capabilities view](#the-capabilities-view) has read them, each with where
1023
+ it comes from, dim, and choosing one shows that view with it selected
1024
+ (the palette never reads either); the views, Instances, Souls and
1025
+ Capabilities; the acts the
925
1026
  instance offers now (the shown terminal's when the palette was opened from
926
1027
  its focus, else the selected one's), with `Spawn another <soul>` once the
927
1028
  catalog lists its soul; then Spawn an agent, Workspaces, Refresh and Help, and [the split's](#splits)
928
1029
  rows where each applies.
929
1030
  Each row says at its right edge what kind it is: `instance`, `soul`,
930
- `view`, `act` or `command`.
1031
+ `capability`, `view`, `act` or `command`.
931
1032
  - **Typing filters it** with the Desktop's subsequence match, a prefix
932
1033
  first: each kind keeps the rows that match, the best first.
933
1034
  `Backspace` removes a character, and a paste adds its first line.
@@ -1057,8 +1158,15 @@ with the Desktop (`packages/client/`).
1057
1158
  look again.
1058
1159
  - **The souls are one more read**, `oats souls --json` for the open
1059
1160
  workspace, by the same kernel, with 60 seconds and 4 MiB: only once [the
1060
- Souls view](#the-souls-view) was shown, then only when the workspace
1061
- changed, and on `r` there.
1161
+ Souls view](#the-souls-view), [the Capabilities
1162
+ view](#the-capabilities-view) or [the spawn prompt](#spawning-an-agent)
1163
+ was shown, then only when the workspace changed, and on `r` in the Souls
1164
+ view.
1165
+ - **The capabilities are one more read**, `oats capabilities --json` for
1166
+ the open workspace, read as the souls are: by the same kernel, with 60
1167
+ seconds and 4 MiB, only once [the Capabilities
1168
+ view](#the-capabilities-view) was shown, then only when the workspace
1169
+ changed (its packages and its lock count too), and on `r` there.
1062
1170
  - **A spawn's preview is one more read**, `oats spawn <soul> --preview
1063
1171
  --json` with the choices shown, by the same kernel, with 30 seconds: only
1064
1172
  while [the spawn prompt](#spawning-an-agent) is open, and again when a
@@ -1226,7 +1334,7 @@ with the Desktop (`packages/client/`).
1226
1334
  | start an agent with another harness or model | `oats session start --home <home>` with its options |
1227
1335
  | spawn an agent on another machine | `oats spawn <soul> --server <id>` |
1228
1336
  | spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
1229
- | see capabilities | `oats capabilities` |
1337
+ | see a capability's skills and files | `oats capabilities show <name>` |
1230
1338
  | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
1231
1339
  | check a machine | `oats server check <id>` |
1232
1340
  | remove a machine | `oats server remove <id>` |
@@ -1247,8 +1355,8 @@ version:
1247
1355
  machine's heading when it is not the header's time. A view of one machine
1248
1356
  has no heading: there the header names the machine (`on garnet`) and
1249
1357
  carries the time.
1250
- - The Souls view lists a workspace of this machine's souls, and
1251
- Capabilities, when it comes, is this machine's too.
1358
+ - The Souls and Capabilities views list a workspace of this machine's
1359
+ souls and capabilities: both are this machine's.
1252
1360
  - There is no sorting and no mouse, and a deployment's heading cannot be
1253
1361
  folded. An open terminal has no scrollback but the viewer's own.
1254
1362
  - Up to four terminals are open at a time, as tabs, in at most two
@@ -54,7 +54,7 @@ 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.12.2 # bare version → resolves through the official catalog
57
+ oats.framework: v1.12.3 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
package/lib/core.mjs CHANGED
@@ -46,7 +46,7 @@ import { initializeNativeHistory, prepareNativeStart } from "../packages/record/
46
46
  import { sameDirectory } from "../packages/record/lib/directory-identity.mjs";
47
47
  import { noteRuntimeName } from "./deprecation.mjs";
48
48
  import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
49
- import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
49
+ import { createSessionPaneInspector, inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
50
50
  import { appendEvent, incarnationOf, liveWaiting, recordStartBoundary, retireRefusedReason } from "./instance-events.mjs";
51
51
  import { killGroup } from "./process-group.mjs";
52
52
  import { interruptExitStatus, isStartToken, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
@@ -5170,8 +5170,8 @@ export function servedIdentityLine(identity) {
5170
5170
  /** The window names of `session` on the tmux server at `socket`: `{ windows }`, empty when the server
5171
5171
  * or the session is gone, with `missingSocket` (tmux's words) when the socket file is missing, which
5172
5172
  * alone does not say the server is gone (#624); `{ error }` when the server could not be read. */
5173
- function recordedTmuxWindows(socket, session) {
5174
- try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean) }; }
5173
+ function recordedTmuxWindows(socket, session, io) {
5174
+ try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], io).split("\n").filter(Boolean) }; }
5175
5175
  catch (e) {
5176
5176
  const absence = tmuxServerAbsence(e);
5177
5177
  if (absence === "missing-socket") return { windows: [], missingSocket: tmuxFailure(e, "tmux list-windows failed") };
@@ -5179,20 +5179,46 @@ function recordedTmuxWindows(socket, session) {
5179
5179
  return { error: String(e.stderr ?? e.message ?? "").trim() || "tmux list-windows failed" };
5180
5180
  }
5181
5181
  }
5182
- /** A status row's liveness from its session's windows: unknown (not false) when the server could not
5182
+ /** A status row's harness liveness from its session's panes: unknown (not false) when the server could not
5183
5183
  * be read, and, for a row whose server holds its endpoint (`endpoint`), when its socket file is
5184
5184
  * missing while a process works in the home or the scan (`scanHome()`, processesInHome's answer for
5185
5185
  * it) cannot tell (#624). */
5186
- function tmuxLiveness({ windows, error, missingSocket }, window, scanHome, endpoint) {
5186
+ function tmuxLiveness({ windows, error, missingSocket, panes }, window, scanHome, endpoint, inspectPanes) {
5187
5187
  if (error) return { running: null, runtimeState: "unreachable", runtimeError: error };
5188
5188
  const running = windows.includes(window);
5189
5189
  const why = !running && missingSocket && endpoint ? missingSocketUnestablished(missingSocket, scanHome()) : null;
5190
- return why ? { running: null, runtimeState: "unreachable", runtimeError: why } : { running };
5190
+ if (why) return { running: null, runtimeState: "unreachable", runtimeError: why };
5191
+ if (!running) return { running: false };
5192
+ try {
5193
+ const observed = inspectPanes(panes.get(window) ?? []);
5194
+ return { running: harnessRunning(observed), ...(observed.state === "shell" ? { runtimeState: "shell" } : {}) };
5195
+ } catch (e) { return { running: null, runtimeState: "unreachable", runtimeError: tmuxFailure(e, "tmux pane inspection failed") }; }
5196
+ }
5197
+ /** One extra read per socket/session, never per row. Keep window discovery's missing-socket
5198
+ * handling; a failed pane read after successful discovery is unknown, not proof of a stop. */
5199
+ function statusTmuxPanes(snapshot, socket, session, io) {
5200
+ if (!snapshot.windows?.length) return snapshot;
5201
+ try {
5202
+ const args = ["list-panes", "-s", "-t", `=${session}`, "-F", "#{window_name}\t#{pane_id}\t#{pane_dead}\t#{pane_current_command}\t#{pane_pid}"];
5203
+ const output = socket ? tmuxOn(socket, args, io) : (io?.exec || execFileSync)("tmux", ["-u", ...args], {
5204
+ encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
5205
+ });
5206
+ const panes = new Map();
5207
+ for (const line of output.split("\n").filter(Boolean)) {
5208
+ const tab = line.indexOf("\t");
5209
+ if (tab < 0) throw new Error("invalid tmux pane response");
5210
+ const window = line.slice(0, tab);
5211
+ if (!panes.has(window)) panes.set(window, []);
5212
+ panes.get(window).push(line.slice(tab + 1));
5213
+ }
5214
+ return { ...snapshot, panes };
5215
+ } catch (e) { return { error: tmuxFailure(e, "tmux list-panes failed") }; }
5191
5216
  }
5192
5217
  export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5193
5218
  // Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
5194
- // socket, never the ambient $TMUX server, once per socket and session per call, so status costs no
5195
- // more child processes as homes grow. A home without a recorded socket reads the default server.
5219
+ // socket, never the ambient $TMUX server: one window read and one pane read per socket/session,
5220
+ // plus one lazy process scan for shell descendants, independent of the number of homes.
5221
+ // A home without a recorded socket reads the default server.
5196
5222
  // A row whose socket file is missing is checked against one process scan of the host, made the
5197
5223
  // first time a row needs it and shared by every row (`io` reaches it: processesInHome).
5198
5224
  let hostScan;
@@ -5200,10 +5226,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5200
5226
  hostScan ??= hostProcesses(io);
5201
5227
  return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
5202
5228
  };
5229
+ const inspectPanes = createSessionPaneInspector(io);
5203
5230
  const tmuxByEndpoint = new Map();
5204
5231
  const windowsOf = (session, socket) => {
5205
5232
  const key = JSON.stringify([socket ?? null, session]);
5206
- if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : defaultTmuxWindows(session));
5233
+ if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, statusTmuxPanes(
5234
+ socket ? recordedTmuxWindows(socket, session, io) : defaultTmuxWindows(session), socket, session, io));
5207
5235
  return tmuxByEndpoint.get(key);
5208
5236
  };
5209
5237
  const readInstancesOf = (agentDir) => {
@@ -5253,7 +5281,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5253
5281
  : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
5254
5282
  // A home that records no socket and no launch (--no-launch) reads the default server only
5255
5283
  // by default: that server's missing socket says nothing about it, and stays "not running".
5256
- !!meta.tmux?.socket || meta.launched === true);
5284
+ !!meta.tmux?.socket || meta.launched === true, inspectPanes);
5257
5285
  const identity = servedIdentityOf(meta);
5258
5286
  // Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
5259
5287
  // else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
@@ -5272,13 +5300,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5272
5300
  };
5273
5301
  // Feature waiting-on-you: a producer's live claim that the instance is
5274
5302
  // blocked on a human, read only for a running row (one bounded read of
5275
- // its home log); null otherwise, and null means unknown. `running` is
5276
- // the window's presence, which a crashed harness's fallback shell or a
5277
- // retained dead pane keeps: a row with a claim is shown only when its
5278
- // session is observed running a harness, as session inspect reports it.
5303
+ // its home log); null otherwise, and null means unknown. Pane liveness is
5304
+ // already observed in the batch; still require the independent receipt
5305
+ // to agree before showing a claim, just as session inspect does.
5279
5306
  let waitingOnYou = liveness.running === true ? liveWaiting(home) : null;
5280
5307
  if (waitingOnYou) {
5281
- try { const s = instanceSessionTarget(home); if (!s.target || !harnessRunning(inspectSessionTarget(s.target))) waitingOnYou = null; }
5308
+ try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
5282
5309
  catch { waitingOnYou = null; }
5283
5310
  }
5284
5311
  // `retire` is only ever the value read above: a record that carries one (hand-edited, or