@awebai/oats 0.60.0 → 0.62.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -19
- package/bin/oats.mjs +68 -21
- package/docs/capabilities.md +1 -1
- package/docs/configuration.md +9 -0
- package/docs/desktop-cli-api.md +28 -5
- package/docs/desktop.md +7 -0
- package/docs/execution-targets.md +49 -3
- package/docs/first-team.md +8 -0
- package/docs/implementation.md +2 -1
- package/docs/named-test-runs.md +382 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.61.0.md +155 -0
- package/docs/release-notes/v0.62.0.md +223 -0
- package/docs/tui.md +10 -4
- package/docs/upgrading.md +133 -11
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +2 -2
- package/lib/doctor-capture.mjs +35 -0
- package/lib/session-viewer.mjs +86 -7
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/instance-presentation.mjs +10 -0
- package/packages/client/instance-tree.mjs +48 -6
- package/packages/record/README.md +87 -13
- package/packages/record/bin/capture-hook.mjs +8 -0
- package/packages/record/bin/capture.mjs +143 -124
- package/packages/record/bin/recall.mjs +8 -3
- package/packages/record/bin/setup.mjs +115 -225
- package/packages/record/bin/turn-record.mjs +2 -2
- package/packages/record/docs/capture-service.md +1443 -28
- package/packages/record/docs/capture-status.schema.json +429 -12
- package/packages/record/lib/capture-admission.mjs +82 -0
- package/packages/record/lib/capture-aw-unit.mjs +137 -0
- package/packages/record/lib/capture-aw.mjs +31 -12
- package/packages/record/lib/capture-budget.mjs +31 -0
- package/packages/record/lib/capture-cc.mjs +39 -6
- package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
- package/packages/record/lib/capture-cleanup-work.mjs +77 -0
- package/packages/record/lib/capture-command-operation.mjs +37 -0
- package/packages/record/lib/capture-command-output.mjs +61 -0
- package/packages/record/lib/capture-command-worker.mjs +6 -0
- package/packages/record/lib/capture-command.mjs +48 -0
- package/packages/record/lib/capture-completion.mjs +152 -0
- package/packages/record/lib/capture-context.mjs +50 -0
- package/packages/record/lib/capture-default-roots.mjs +30 -0
- package/packages/record/lib/capture-discovery.mjs +114 -0
- package/packages/record/lib/capture-failures.mjs +45 -0
- package/packages/record/lib/capture-health-doctor.mjs +13 -0
- package/packages/record/lib/capture-health-installation.mjs +117 -0
- package/packages/record/lib/capture-health.mjs +116 -0
- package/packages/record/lib/capture-hook-ownership.mjs +58 -0
- package/packages/record/lib/capture-hook-runner.mjs +17 -0
- package/packages/record/lib/capture-hook.mjs +26 -0
- package/packages/record/lib/capture-index-inventory.mjs +205 -0
- package/packages/record/lib/capture-index-outcomes.mjs +113 -0
- package/packages/record/lib/capture-index-reset.mjs +109 -0
- package/packages/record/lib/capture-index-work.mjs +77 -0
- package/packages/record/lib/capture-issue-preparation.mjs +73 -0
- package/packages/record/lib/capture-issues.mjs +15 -2
- package/packages/record/lib/capture-lock.mjs +102 -16
- package/packages/record/lib/capture-native-unit.mjs +322 -0
- package/packages/record/lib/capture-pass.mjs +102 -0
- package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
- package/packages/record/lib/capture-retained-scratch.mjs +213 -0
- package/packages/record/lib/capture-retry.mjs +102 -0
- package/packages/record/lib/capture-run.mjs +125 -0
- package/packages/record/lib/capture-scratch.mjs +12 -3
- package/packages/record/lib/capture-service-definition.mjs +104 -0
- package/packages/record/lib/capture-service-install.mjs +362 -0
- package/packages/record/lib/capture-service-ownership.mjs +137 -0
- package/packages/record/lib/capture-service-runner.mjs +18 -0
- package/packages/record/lib/capture-small-snapshot.mjs +85 -0
- package/packages/record/lib/capture-source-discovery.mjs +319 -0
- package/packages/record/lib/capture-source-queue.mjs +199 -0
- package/packages/record/lib/capture-source-work.mjs +85 -0
- package/packages/record/lib/capture-state.mjs +16 -71
- package/packages/record/lib/capture-status.mjs +171 -0
- package/packages/record/lib/capture-supervisor.mjs +117 -0
- package/packages/record/lib/capture-watch.mjs +32 -0
- package/packages/record/lib/capture-work-session.mjs +238 -0
- package/packages/record/lib/capture-worker.mjs +58 -0
- package/packages/record/lib/derived-state.mjs +28 -15
- package/packages/record/lib/file-lines.mjs +22 -6
- package/packages/record/lib/formats.mjs +4 -3
- package/packages/record/lib/index-capture.mjs +97 -0
- package/packages/record/lib/index-db.mjs +3 -17
- package/packages/record/lib/index-reset.mjs +19 -0
- package/packages/record/lib/store.mjs +36 -11
- package/packages/record/lib/transcript-prefix.mjs +125 -0
- package/packages/tui/lib/client.mjs +2 -2
- package/packages/tui/lib/model.mjs +15 -5
- package/packages/tui/lib/views/palette.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +1 -1
- package/docs/macos-test-runs.md +0 -246
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
# OATS 0.62.0
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
## Upgrade
|
|
6
|
+
|
|
7
|
+
- The bounded periodic capture service ships in this release; 0.56.0 through
|
|
8
|
+
0.61.0 do not include it. Upgrade in this order: install this release's
|
|
9
|
+
compatible Desktop first, then this CLI and the matching pi bridge, then run
|
|
10
|
+
this CLI's setup conversion once per user on each host, from that user's
|
|
11
|
+
shell, then its health and doctor checks. Do not use these flags or diagnostics as
|
|
12
|
+
pre-upgrade checks on 0.61.0 or older binaries, which do not have them. See
|
|
13
|
+
[capture service release order](../upgrading.md#capture-service-release-order).
|
|
14
|
+
- Run `oats setup` (standalone: `turn-record setup`) once per user on each
|
|
15
|
+
host, from that user's shell, with the deployment's owner and root: setup
|
|
16
|
+
writes that user's `~/.claude*/settings.json` and user manager. Installing the CLI
|
|
17
|
+
alone converts nothing: persisted hooks and manager definitions change only
|
|
18
|
+
when setup runs. Owned capture watchers convert to the periodic service there.
|
|
19
|
+
A foreign, disabled or masked definition is refused before any change, with
|
|
20
|
+
two printed commands that keep the owner and root: `--replace-service` to
|
|
21
|
+
replace only the named capture service, or `--no-service` to keep the
|
|
22
|
+
operator's service and skip service files and manager calls. Repair unknown
|
|
23
|
+
or unreadable state before retrying; replacement never waives it.
|
|
24
|
+
`--dry-run` writes nothing and calls no manager. Keep the backups setup
|
|
25
|
+
reports under `<root>/service-backups/`.
|
|
26
|
+
- Setup rewrites the owned `Stop`/`SessionEnd` capture hooks in every
|
|
27
|
+
`~/.claude*/settings.json` from `async: true`, `timeout: 120` to the hook
|
|
28
|
+
entry `bin/capture-hook.mjs` with `async: false`, `timeout: 10`, even where
|
|
29
|
+
the command already matches. 0.61.0 cannot load that entry, so after a
|
|
30
|
+
rollback the hook exits 1 instead of blocking Claude's Stop; the upgrade
|
|
31
|
+
guide gives the rollback steps. Until setup runs, the persisted hooks keep
|
|
32
|
+
the old fields.
|
|
33
|
+
- Setup rewrites each `~/.claude*/settings.json` it changes with mode `0600`.
|
|
34
|
+
- The capture status file keeps `schemaVersion: 1` while it gains fields, a
|
|
35
|
+
contract decision: 0.61.0 reads a status written by this release as invalid
|
|
36
|
+
(see the rollback note in the upgrade guide).
|
|
37
|
+
- A service refusal changes nothing. A service failure after preflight no
|
|
38
|
+
longer skips capture: setup still writes the hooks and runs the first pass,
|
|
39
|
+
then exits 1 and ends with a fixed-format
|
|
40
|
+
setup summary naming the hooks written, the first pass's result, the
|
|
41
|
+
service failure, what that failed apply had already changed (the backup
|
|
42
|
+
directory, units stopped or disabled, definitions written, the pending
|
|
43
|
+
marker), and the remedy. Setup has no `--json`; see #1330.
|
|
44
|
+
- A plain rerun finishes setup's own failed activation: setup records it in a
|
|
45
|
+
private `<root>/capture-service-pending.json` marker, removed once activation
|
|
46
|
+
is verified, so a timer its failed enable left disabled is retried without a
|
|
47
|
+
flag (#1099). A disabled unit without that marker is still the operator's
|
|
48
|
+
choice and needs `--replace-service` or `--no-service`. Until the rerun,
|
|
49
|
+
`capture --health` and `oats doctor` warn `capture-service-pending`: the
|
|
50
|
+
periodic schedule is not verified. Apply has no atomic rollback: a manager
|
|
51
|
+
failure can leave backups, stopped jobs or written definitions in place.
|
|
52
|
+
- After conversion, check `oats capture --health` (or
|
|
53
|
+
`turn-record capture --health`) against the intended root, and the capture
|
|
54
|
+
warnings of `oats doctor`, keeping the same `HOME` and `TURN_RECORD_ROOT`.
|
|
55
|
+
The health rows are `capture-status-missing`, `capture-status-invalid`,
|
|
56
|
+
`capture-success-stale`, `capture-pass-failed`, `capture-input-set-aside`,
|
|
57
|
+
`capture-setup-required` (an owned capture watcher or hook that setup has
|
|
58
|
+
not converted) and `capture-service-pending` (setup's activation is not
|
|
59
|
+
verified); `oats doctor` reports a failed health command as
|
|
60
|
+
`capture-health-unavailable`. Definition files, an `ok` diagnosis or no
|
|
61
|
+
warnings do not prove the schedule is registered and enabled. A missing recent success can reflect sleep or an
|
|
62
|
+
off-host machine; progress or cleared issues alone are not success. Update
|
|
63
|
+
the CLI before relying on complete piped health output.
|
|
64
|
+
|
|
65
|
+
## Added
|
|
66
|
+
|
|
67
|
+
- **Named test files can be run by hand on a Linux runner whose user manager
|
|
68
|
+
works** ([#1108](https://github.com/awebai/oats/issues/1108)). The workflow
|
|
69
|
+
`Linux tests` (`linux-tests.yml`) is the Linux counterpart of `macOS tests`.
|
|
70
|
+
It runs named test files of a named ref, each alone, on `ubuntu-24.04`:
|
|
71
|
+
at most 10 files, 20 minutes a file, 240 minutes a job. Before the
|
|
72
|
+
header, it enables lingering for the runner user and waits at most 60
|
|
73
|
+
seconds for `systemctl --user` to answer. The header says whether
|
|
74
|
+
the manager answered, and a manager that did not answer fails the run
|
|
75
|
+
before anything is installed. Its terms are the macOS workflow's:
|
|
76
|
+
dispatch only, a read-only token, no secret, artifact or cache, and no
|
|
77
|
+
input in a shell line. Both workflows run one script. The workflow's name
|
|
78
|
+
is a contract that guarded tests key on, together with `workflow_dispatch`
|
|
79
|
+
and `linux`. The macOS workflow's name, inputs and printed evidence are
|
|
80
|
+
unchanged ([named test runs](../named-test-runs.md)).
|
|
81
|
+
|
|
82
|
+
## Changed
|
|
83
|
+
|
|
84
|
+
- **Capture runs as bounded supervised passes.** Ordinary capture,
|
|
85
|
+
`--sessions-only`, `--aw-only`, `--no-index` and `--retry-set-aside` run one
|
|
86
|
+
pass through a fixed supervisor and worker under the root lock. A partial
|
|
87
|
+
pass exits 0 with work pending; an operational failure exits nonzero; a
|
|
88
|
+
missing worker receipt is reported as unknown, never as zero counts. Ordinary
|
|
89
|
+
lock overlap exits 0 and keeps the holder's receipt; a recovery that overlaps
|
|
90
|
+
is not performed and exits 1. `index: updated` is printed only for a complete
|
|
91
|
+
pass with indexing enabled. `--no-index` appends without opening the search
|
|
92
|
+
index and never reports a fresh all-stage success. Ordinary `--json` stays a
|
|
93
|
+
usage error and retry JSON keeps `{appended, pending}`. `--reset-cursors`,
|
|
94
|
+
the exact `--home`/`--file` proofs and the public synchronous APIs keep their
|
|
95
|
+
contracts.
|
|
96
|
+
- A pass resumes across worker replacement: source discovery, the index
|
|
97
|
+
inventory, index reset (separately admitted, atomic), retained recovery
|
|
98
|
+
cleanup and run accounting all commit in bounded pages. Interrupted work keeps
|
|
99
|
+
its retry evidence and backs off 30, 60, 120, then 240 minutes while healthy
|
|
100
|
+
work continues. Success is recorded only after an all-stage audit of sources,
|
|
101
|
+
index, admissions, retries and cleanup.
|
|
102
|
+
- A raw source record over 8 MiB is never allocated whole or captured. The
|
|
103
|
+
complete records before it are captured, and the input is set aside at that
|
|
104
|
+
record's start offset. Records after it stay pending until the operator edits
|
|
105
|
+
the source or adds the whole input to `<root>/ignore`; `--retry-set-aside`
|
|
106
|
+
retries the input, but the oversized record still blocks it, in every case.
|
|
107
|
+
The limit applies only beyond what is already captured: native recovery
|
|
108
|
+
(after cache loss, a reset, a retry or a rewritten source) proves captured
|
|
109
|
+
records of any size by streamed per-line digests, so sessions that already
|
|
110
|
+
hold records over 8 MiB keep capturing their later growth. Known limitation:
|
|
111
|
+
an oversized line before a session's first timestamped line captures
|
|
112
|
+
nothing before it. `--health` names the edit-or-ignore remedy for these
|
|
113
|
+
entries.
|
|
114
|
+
- Foreground `--watch` keeps its two-second debounce and 15-minute fallback,
|
|
115
|
+
runs one pass at a time and coalesces notifications into one pending rerun.
|
|
116
|
+
- **Hooks launch capture detached.** `capture --hook` starts the supervisor in
|
|
117
|
+
its own session without the harness's pipes. Exit 0 means **capture
|
|
118
|
+
launched**, not initialization or completion; launch and usage errors exit 1,
|
|
119
|
+
never Claude's Stop-blocking 2. The harness waits only for the launcher;
|
|
120
|
+
no launch latency is measured. Foreign hooks, groups and unrelated fields are
|
|
121
|
+
kept, and `--install-hint` prints the same fields, keeping
|
|
122
|
+
`--sessions-only --no-index`.
|
|
123
|
+
- **Setup installs a periodic service.** On macOS,
|
|
124
|
+
`ai.aweb.turn-record-capture` runs at load and every 900 seconds
|
|
125
|
+
(`StartInterval`), with no `KeepAlive`. On Linux, a finite
|
|
126
|
+
`turn-record-capture.service` (`MemoryMax=2G`, `RuntimeMaxSec=300`, no
|
|
127
|
+
restart) is started by `turn-record-capture.timer` one minute after boot and
|
|
128
|
+
every 15 minutes. Each start runs one pass with all sources and indexing.
|
|
129
|
+
Setup reports "periodic capture scheduled (every 15 minutes)" only after
|
|
130
|
+
verifying registration and enablement, never a permanent PID. An unchanged,
|
|
131
|
+
enabled schedule is left running, preserving a pass in flight.
|
|
132
|
+
- Setup takes `--root`, `--replace-service`, `--no-service` and `--dry-run`, and
|
|
133
|
+
preflights every named service file, the manager state and the hook edits
|
|
134
|
+
before changing anything. `E_CAPTURE_SERVICE_FOREIGN` refuses definitions or
|
|
135
|
+
registrations it does not own; on macOS that includes a registration of the
|
|
136
|
+
capture label from another plist path, refused naming that path even with
|
|
137
|
+
`--replace-service`. `E_CAPTURE_SERVICE_DISABLED` states the manager state it
|
|
138
|
+
observed, without claiming the operator disabled it. Refusals and failures
|
|
139
|
+
print the user-facing command with the selected `--owner` and `--root`:
|
|
140
|
+
`oats setup …` when the kernel environment handed in a node (`OATS_NODE_BIN`,
|
|
141
|
+
also set in instance shells), otherwise `turn-record setup …`; both record
|
|
142
|
+
the same node.
|
|
143
|
+
- Setup's first pass runs through the same supervisor with `setup` attribution,
|
|
144
|
+
all sources and indexing, under the running Node; the hooks and service record
|
|
145
|
+
a stable Node. `--no-service` still runs it and `--dry-run` starts none.
|
|
146
|
+
Partial and overlapping passes exit 0 without claiming completion.
|
|
147
|
+
- **`capture --health [--json]`** distinguishes no installation (no capture
|
|
148
|
+
service definition, capture hook or setup pending marker: a record root
|
|
149
|
+
alone, as one recall or manual capture leaves it, is not one), unknown
|
|
150
|
+
evidence, missing or invalid status, stale or absent success, newer failures,
|
|
151
|
+
unfinished runs and owned capture watchers that need setup. It reads no source
|
|
152
|
+
content or manager state and changes nothing. A capture pass that finds the
|
|
153
|
+
status file unreadable moves it aside to `capture-status.json.invalid-<UTC
|
|
154
|
+
stamp>` and writes a new status; a foreground, setup, watch or service pass
|
|
155
|
+
names the moved-aside file on stderr, a hook pass leaves only the file. Reader failures exit nonzero;
|
|
156
|
+
warnings exit 0. Reads are bounded, with a cooperative deadline.
|
|
157
|
+
- **`oats doctor`** runs package capture health once, with a finite timeout and
|
|
158
|
+
output bound, and turns its rows into warnings. A failed, timed-out or invalid
|
|
159
|
+
health run is `capture-health-unavailable`. Remedies say `oats` under the
|
|
160
|
+
kernel and `turn-record` standalone. Doctor's exit and output contracts are
|
|
161
|
+
unchanged.
|
|
162
|
+
- `recall --thread <thread> --json` lists a thread in capture sequence. For a
|
|
163
|
+
thread spanning aweb accounts the cross-account sequence is unspecified, and
|
|
164
|
+
an ID window may contain turns from more than one account. Text thread
|
|
165
|
+
listings without a query stay timestamp-sorted.
|
|
166
|
+
- Real macOS and Linux manager lifecycle, storage and synchronization costs, and
|
|
167
|
+
full hosted service qualification are verified separately from the isolated
|
|
168
|
+
fixtures.
|
|
169
|
+
- **OATS Desktop accepts an `oats` CLI 0.62.x.** Its band is now
|
|
170
|
+
`>=0.26.0 <0.63.0`. 0.62 adds no new gate on the band: the Desktop does
|
|
171
|
+
not read the capture service, and `oats session attach` keeps the
|
|
172
|
+
arguments and exit codes the Desktop's viewer relies on.
|
|
173
|
+
|
|
174
|
+
## Fixed
|
|
175
|
+
|
|
176
|
+
- Capture CLI reporting finishes naturally, so piped stdout and stderr drain
|
|
177
|
+
before exit: health samples, truncation banners, JSON receipts and error
|
|
178
|
+
messages are no longer cut off. Exit codes are unchanged, and health cannot
|
|
179
|
+
fall through to a capture.
|
|
180
|
+
- **A viewer from `oats session attach` no longer outlives an attach that
|
|
181
|
+
died without detaching** ([#1332](https://github.com/awebai/oats/issues/1332)).
|
|
182
|
+
A cgroup-wide `systemctl kill`, a stop timeout, oomd or a killed ssh used
|
|
183
|
+
to leave the `oatsview-*` session, and a keyed viewer's key table, on the
|
|
184
|
+
agents' tmux server. Now the viewer's client sets a `client-detached` hook
|
|
185
|
+
on its own session once it has attached, so the server removes the session
|
|
186
|
+
when the client's connection drops without a word from it (`oats` and its
|
|
187
|
+
client SIGKILLed together), and with it a keyed viewer's key table; a
|
|
188
|
+
client that ends any other way leaves the viewer to `oats`, or, if `oats`
|
|
189
|
+
has died, to the next attach's sweep. A
|
|
190
|
+
viewer session that ends another way has its table unbound by one global
|
|
191
|
+
hook entry, `session-closed[900]`, the only one OATS owns on the agents'
|
|
192
|
+
server: keep your own `session-closed` hooks at other indexes (tmux 3.2 and
|
|
193
|
+
later; before 3.2 the sweep removes the table). The viewer never uses tmux's
|
|
194
|
+
`destroy-unattached`, which crashes a tmux 3.4 server when another client
|
|
195
|
+
detaches the viewer ([#1336](https://github.com/awebai/oats/issues/1336)).
|
|
196
|
+
A global `client-detached` hook of yours does not run for a viewer's
|
|
197
|
+
client whose connection dropped: the viewer's own hook takes its place. Every attach also
|
|
198
|
+
sweeps what earlier attaches left before it opens its viewer.
|
|
199
|
+
It removes a viewer session that has no client and whose attach is gone,
|
|
200
|
+
and every viewer key table whose session is gone. When the sweep removed
|
|
201
|
+
something, the attach says so in one line on stderr. Exit statuses are
|
|
202
|
+
unchanged, a leave by the detach key's 20 included
|
|
203
|
+
([execution targets](../execution-targets.md#inspect-input-and-attach)).
|
|
204
|
+
|
|
205
|
+
## Provider updates
|
|
206
|
+
|
|
207
|
+
- **oats.framework 1.13.1, oats.setup 2.8.1: record capture setup is a
|
|
208
|
+
person-run step** ([#1108](https://github.com/awebai/oats/issues/1108)).
|
|
209
|
+
From OATS 0.62.0, `/oats-setup-model` and the setup briefing name the record
|
|
210
|
+
capture conversion `oats setup` as the third install the person runs from
|
|
211
|
+
their own shell, beside the host wake broker and the host timer, and say how
|
|
212
|
+
to read `turn-record capture --health` and `oats doctor`'s capture warnings.
|
|
213
|
+
Every new line names the release it starts in. Instruction text only; the
|
|
214
|
+
floors are unchanged. A deployment gets it by pinning
|
|
215
|
+
`oats.framework: v1.13.1` and running `oats sync`.
|
|
216
|
+
|
|
217
|
+
## Documentation
|
|
218
|
+
|
|
219
|
+
- **`docs/macos-test-runs.md` is now
|
|
220
|
+
[`docs/named-test-runs.md`](../named-test-runs.md)** and covers both
|
|
221
|
+
runners. It adds each workflow's name as a guard contract and says what a
|
|
222
|
+
Linux run is not evidence of: a hosted VM's user manager with lingering is
|
|
223
|
+
not a person's login session.
|
package/docs/tui.md
CHANGED
|
@@ -145,9 +145,13 @@ runs.
|
|
|
145
145
|
shown in quotation marks, and names nobody. A reason that is withheld is
|
|
146
146
|
`[withheld]` alone. Then it shows what it needs from you with how long
|
|
147
147
|
it has waited and its own message, harness and model, work mode and
|
|
148
|
-
branch, team, parent, when it last started, and its home.
|
|
149
|
-
|
|
150
|
-
|
|
148
|
+
branch, team, parent and siblings, when it last started, and its home.
|
|
149
|
+
The siblings are the instances at the other end of an explicit sibling
|
|
150
|
+
link, either way, as the Desktop reads them: `sibling of a`, `sibling of
|
|
151
|
+
a and b`, `sibling of a, b and c`. They are read inside the instance's
|
|
152
|
+
own deployment, and a name that is no instance there, or two of them, is
|
|
153
|
+
not shown. From 80 columns up it stands beside the list; on a narrower
|
|
154
|
+
terminal `Tab` opens it as a page.
|
|
151
155
|
- **Opening an agent.** `Enter` on an instance that runs opens its terminal
|
|
152
156
|
beside the list, where the detail was, as a tab: see
|
|
153
157
|
[Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
|
|
@@ -1015,7 +1019,9 @@ is open no terminal is drawn and the TUI reads the keys.
|
|
|
1015
1019
|
- **It lists, in this order:** the instances that can be opened, the most
|
|
1016
1020
|
recently opened or shown in this run first (when the first is the shown tab's,
|
|
1017
1021
|
the second is selected as it opens), then the list's order, each with its
|
|
1018
|
-
state mark, its name
|
|
1022
|
+
state mark, its name, for another machine `on <machine>`, and, dim, its
|
|
1023
|
+
siblings as the detail names them (`sibling of <names>`), which are cut
|
|
1024
|
+
first when the row is short and are never matched by a query; the souls
|
|
1019
1025
|
of the open workspace, once they were read (by [the Souls
|
|
1020
1026
|
view](#the-souls-view), the Capabilities view or a spawn), and choosing
|
|
1021
1027
|
one shows the Souls view with it selected; its capabilities, once [the
|
package/docs/upgrading.md
CHANGED
|
@@ -74,6 +74,100 @@ Versions are compared as semver, so a prerelease is below its release:
|
|
|
74
74
|
no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
|
|
75
75
|
installed over it.
|
|
76
76
|
|
|
77
|
+
## Capture service release order
|
|
78
|
+
|
|
79
|
+
The bounded periodic capture service (service A) is **not shipped in
|
|
80
|
+
[0.56.0](release-notes/v0.56.0.md) through [0.61.0](release-notes/v0.61.0.md)**
|
|
81
|
+
([0.57.0](release-notes/v0.57.0.md), [0.57.1](release-notes/v0.57.1.md),
|
|
82
|
+
[0.58.0](release-notes/v0.58.0.md), [0.59.0](release-notes/v0.59.0.md) and
|
|
83
|
+
[0.60.0](release-notes/v0.60.0.md) included). Those releases retain the
|
|
84
|
+
existing capture watcher, and upgrading to any of them does not install the
|
|
85
|
+
periodic service. The capture algorithms and recovery commands already
|
|
86
|
+
released do not prove that migration happened.
|
|
87
|
+
|
|
88
|
+
For those released versions, follow their own Upgrade sections and the steps
|
|
89
|
+
above. In particular, install the target Desktop before the CLI: the 0.61.0
|
|
90
|
+
Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI.
|
|
91
|
+
|
|
92
|
+
Service A ships in [0.62.0](release-notes/v0.62.0.md). Read its Upgrade
|
|
93
|
+
section and keep this order: install the 0.62.0 Desktop first (it accepts CLIs
|
|
94
|
+
`>=0.26.0 <0.63.0`), then the 0.62.0 CLI and matching pi bridge. Only **after
|
|
95
|
+
installing that CLI**, run its setup conversion once per user on each host,
|
|
96
|
+
from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
|
|
97
|
+
watcher is replaced by the periodic service; foreign or disabled definitions
|
|
98
|
+
require an explicit operator choice. The conversion accepts `setup --root <dir>`
|
|
99
|
+
and `--replace-service`; refusal prints a quoted command preserving owner/root.
|
|
100
|
+
Choose `--no-service` to skip service files and manager operations entirely.
|
|
101
|
+
`--dry-run` writes nothing and calls no manager, so disabled/registered state
|
|
102
|
+
remains unexamined. Replaced definitions are backed up nonoverwriting under
|
|
103
|
+
the selected record root; retain the reported backup and inspect any partial
|
|
104
|
+
apply error before retrying. Replacement never waives unknown state or changed
|
|
105
|
+
identities. A CLI install alone is not conversion.
|
|
106
|
+
Use that release's capture health and doctor checks after conversion. Do not
|
|
107
|
+
run the service diagnostics or conversion flags as prerequisites on 0.61.0 or
|
|
108
|
+
older binaries, which do not have them, or assume that an older health command
|
|
109
|
+
proves periodic activation. The [capture reference](../packages/record/docs/capture-service.md)
|
|
110
|
+
distinguishes the implemented foundation from an installed service.
|
|
111
|
+
|
|
112
|
+
The first capture after that upgrade rebuilds the record root's derived
|
|
113
|
+
capture state and index from the existing journals: it validates each journal,
|
|
114
|
+
proves each session's captured prefix against a fresh staged copy of its
|
|
115
|
+
source, and indexes every record. This cost is paid once, and it grows linearly with the
|
|
116
|
+
number of streams and their bytes. On the hosted Linux runner (4 CPUs) it took
|
|
117
|
+
about 20 seconds per 1,000 streams of typical small sessions, and about 4
|
|
118
|
+
minutes per GB of journals overall: a record of about 1,300 streams and 8 GB of
|
|
119
|
+
journals needs roughly half an hour of capture work in about seven bounded
|
|
120
|
+
passes, which under the service's 15-minute interval is one to two hours of
|
|
121
|
+
elapsed time. A later pass over unchanged sessions does no content work and
|
|
122
|
+
costs about 2 ms per stream on the same runner (about 3 s at 1,300 streams),
|
|
123
|
+
growing linearly with the number of streams. Each pass stops at its deadline. A first upgrade that is interrupted or reaches its deadline resumes
|
|
124
|
+
from its durable checkpoints on the next pass (journal validation, index
|
|
125
|
+
cursors, the prefix proof and the staged copies of sources over 8 MiB) rather
|
|
126
|
+
than starting over; a smaller session's staged copy is made again. Reducing the
|
|
127
|
+
repeated source reads of small sessions is tracked in
|
|
128
|
+
[#1337](https://github.com/awebai/oats/issues/1337).
|
|
129
|
+
|
|
130
|
+
**Going back to 0.61.0.** Until the steps below are done, two things fail at
|
|
131
|
+
every trigger:
|
|
132
|
+
|
|
133
|
+
- each `Stop` and `SessionEnd` hook this release's setup wrote exits 1,
|
|
134
|
+
because its command names `bin/capture-hook.mjs`, a file 0.61.0 does not
|
|
135
|
+
have; Claude does not block on it;
|
|
136
|
+
- the periodic service's start fails every 15 minutes: on Linux
|
|
137
|
+
`turn-record-capture.timer` starts a unit whose runner 0.61.0 does not have,
|
|
138
|
+
and on macOS the `ai.aweb.turn-record-capture` job fails the same way.
|
|
139
|
+
|
|
140
|
+
To go back:
|
|
141
|
+
|
|
142
|
+
1. Install 0.61.0: `npm install -g @awebai/oats@0.61.0`.
|
|
143
|
+
2. From the same user's shell, run 0.61.0's setup with the same owner:
|
|
144
|
+
`oats setup --owner <owner>`. It installs its capture watcher (on Linux as
|
|
145
|
+
`turn-record-capture.service`, on macOS under the same
|
|
146
|
+
`ai.aweb.turn-record-capture` label) and adds its own `Stop` and
|
|
147
|
+
`SessionEnd` hooks. 0.61.0's setup takes no `--root` (it refuses one):
|
|
148
|
+
everything it starts records into `$TURN_RECORD_ROOT` as that process sees
|
|
149
|
+
it, else `~/.turn-record`. Its first pass runs with setup's environment, so
|
|
150
|
+
`TURN_RECORD_ROOT=<root> oats setup --owner <owner>` points that pass at
|
|
151
|
+
another root; its hooks see Claude's environment; its watcher's service
|
|
152
|
+
sets none, so the watcher gets only the user manager's environment and
|
|
153
|
+
records into `~/.turn-record` unless the user manager itself sets
|
|
154
|
+
`TURN_RECORD_ROOT`. With any other root, the watcher and the record you
|
|
155
|
+
were using part ways.
|
|
156
|
+
3. In each `~/.claude*/settings.json`, delete the hook entries under `Stop` and
|
|
157
|
+
`SessionEnd` whose command names `capture-hook.mjs`: 0.61.0's setup does not
|
|
158
|
+
recognize them and leaves them in place.
|
|
159
|
+
4. On Linux, remove the timer:
|
|
160
|
+
`systemctl --user disable --now turn-record-capture.timer`, then delete
|
|
161
|
+
`~/.config/systemd/user/turn-record-capture.timer` and run
|
|
162
|
+
`systemctl --user daemon-reload`.
|
|
163
|
+
|
|
164
|
+
After going back to 0.61.0, its `oats capture --health` reports the capture
|
|
165
|
+
status file this release wrote as invalid, and a capture by 0.61.0 clears the
|
|
166
|
+
run history in that file. A later capture with this release writes a fresh
|
|
167
|
+
status. 0.61.0 ignores the captured frontier this release keeps in an AW log's
|
|
168
|
+
cursor during a rescan and drops it when it rewrites that cursor; it reads that
|
|
169
|
+
log without a record limit, so nothing is lost.
|
|
170
|
+
|
|
77
171
|
## Which pi folders
|
|
78
172
|
|
|
79
173
|
pi keeps its packages in one folder: `~/.pi/agent`, or the folder
|
|
@@ -197,6 +291,20 @@ at the version are left alone.
|
|
|
197
291
|
|
|
198
292
|
## What `oats doctor` reports
|
|
199
293
|
|
|
294
|
+
From the next release after 0.61.0 (service A), deployment doctor also delegates once to
|
|
295
|
+
the record package's offline health reader. Text and JSON carry its diagnosis
|
|
296
|
+
as existing warning rows. `capture-health-unavailable` means the bounded command
|
|
297
|
+
or reader failed, timed out, exceeded its output limit or returned an invalid
|
|
298
|
+
envelope; inspect `oats capture --health --json` with the same root environment.
|
|
299
|
+
Doctor retains its warning exit semantics. `TURN_RECORD_ROOT` selects the root,
|
|
300
|
+
otherwise the caller's `~/.turn-record` applies; `--soul` remains composition-only.
|
|
301
|
+
The kernel adds no status/DB/freshness parser or manager probe. Remedies use
|
|
302
|
+
`oats`, preserving literal user paths and existing owner guidance. Neither no
|
|
303
|
+
warnings nor definition bytes prove enabled scheduling. See the
|
|
304
|
+
[owning boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation)
|
|
305
|
+
for reader/transport limits and remaining qualification. This does not change
|
|
306
|
+
the released 0.56–0.61 upgrade prerequisites above.
|
|
307
|
+
|
|
200
308
|
`oats doctor` prints one warning per folder whose bridge is not the kernel's
|
|
201
309
|
version, naming the folder and why it is looked at:
|
|
202
310
|
|
|
@@ -233,9 +341,9 @@ under npm's global prefix (`npm prefix -g`).
|
|
|
233
341
|
removes the kernel with it. Four things name that kernel by its path: each
|
|
234
342
|
instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
|
|
235
343
|
of a Claude instance, the host timer's unit, and what `oats setup` installs
|
|
236
|
-
(the turn record's capture hooks and its
|
|
237
|
-
|
|
238
|
-
outlast that version.
|
|
344
|
+
(the turn record's capture hooks and its periodic capture service, which
|
|
345
|
+
name the capture scripts inside the kernel). OATS cannot make a path
|
|
346
|
+
inside a Node version outlast that version.
|
|
239
347
|
|
|
240
348
|
Both layouts can exist on one host: check the prefix in the shell that
|
|
241
349
|
installs the CLI.
|
|
@@ -248,7 +356,7 @@ record the `node` that runs them, by one rule
|
|
|
248
356
|
- **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
|
|
249
357
|
the `node` running the kernel. `brew upgrade node` repoints it, so the
|
|
250
358
|
recorded path outlasts the upgrade: the hooks, the timer and the capture
|
|
251
|
-
|
|
359
|
+
service need nothing done.
|
|
252
360
|
- **Otherwise**, a `node` on `PATH` that is the same file as the one running
|
|
253
361
|
the kernel. With mise that is the version's own install, which does not
|
|
254
362
|
outlast the version (other version managers were not measured).
|
|
@@ -258,18 +366,32 @@ record the `node` that runs them, by one rule
|
|
|
258
366
|
|
|
259
367
|
**What `oats setup` records is in your own files, not in an instance home:**
|
|
260
368
|
the capture hooks (`Stop` and `SessionEnd`) in every `~/.claude*/settings.json`
|
|
261
|
-
of the user who ran it, and the capture
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
369
|
+
of the user who ran it, and the periodic capture service's definitions. On
|
|
370
|
+
macOS that is `~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist`, a
|
|
371
|
+
launchd job with `StartInterval` 900; on Linux, a finite
|
|
372
|
+
`~/.config/systemd/user/turn-record-capture.service` started by
|
|
373
|
+
`turn-record-capture.timer` every 15 minutes. Each start runs one bounded
|
|
374
|
+
capture pass and exits. No spawn, start or restart writes them: only
|
|
375
|
+
`oats setup` run again does. It replaces its own hooks and definitions, and
|
|
376
|
+
converts a capture watcher an earlier setup installed; it does not add a
|
|
377
|
+
second one. A definition it does not recognize as its own, or one found
|
|
378
|
+
disabled or masked, is refused with a printed choice: `--replace-service` to
|
|
379
|
+
replace it, or `--no-service` to keep it and skip service files and manager
|
|
380
|
+
calls. One exception on macOS: the capture label registered from another plist
|
|
381
|
+
is refused even with `--replace-service`; remove that registration yourself,
|
|
382
|
+
or keep it with `--no-service`. A service manager failure does not skip
|
|
383
|
+
capture: setup still writes the hooks and runs the first pass, exits 1 and
|
|
384
|
+
prints a setup summary of what changed; rerun the printed command, which
|
|
385
|
+
finishes setup's own activation without a flag. Until then `oats doctor` warns
|
|
386
|
+
`capture-service-pending`. `--dry-run` prints what setup would do and changes
|
|
387
|
+
nothing ([Capture service release order](#capture-service-release-order)).
|
|
266
388
|
|
|
267
389
|
Once the recorded `node` no longer exists (an old version removed under a
|
|
268
390
|
version manager, for example), the hooks fail without a message, so the
|
|
269
391
|
instance stops reporting that it waits on you, and
|
|
270
392
|
`oats schedule host status` reports `node-missing`. The capture hooks then
|
|
271
|
-
fail at every stop of every Claude Code session of that user, and
|
|
272
|
-
|
|
393
|
+
fail at every stop of every Claude Code session of that user, and every
|
|
394
|
+
15-minute start of the capture service fails.
|
|
273
395
|
|
|
274
396
|
**A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
|
|
275
397
|
not follow the rule. Its hooks record the path of the `node` its hook ran
|
package/docs/workspaces.md
CHANGED
|
@@ -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.
|
|
57
|
+
oats.framework: v1.13.1 # 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
|
@@ -6978,11 +6978,11 @@ function stopRecordedChildren(children, signalled) {
|
|
|
6978
6978
|
});
|
|
6979
6979
|
}
|
|
6980
6980
|
|
|
6981
|
-
export async function attachInstanceSession(home, { detachKey } = {}) {
|
|
6981
|
+
export async function attachInstanceSession(home, { detachKey, onSwept } = {}) {
|
|
6982
6982
|
if (detachKey !== undefined) requireDetachKey(detachKey);
|
|
6983
6983
|
const s = instanceSessionTarget(home);
|
|
6984
6984
|
if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
|
|
6985
|
-
return attachSessionTarget(s.target, { detachKey });
|
|
6985
|
+
return attachSessionTarget(s.target, { detachKey, onSwept });
|
|
6986
6986
|
}
|
|
6987
6987
|
|
|
6988
6988
|
export function inputInstanceSession(home, text) {
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
import { fileURLToPath } from "node:url";
|
|
3
|
+
import { validCaptureHealthEnvelope } from "../packages/record/lib/capture-status.mjs";
|
|
4
|
+
|
|
5
|
+
const entry = fileURLToPath(new URL("../packages/record/lib/capture-health-doctor.mjs", import.meta.url));
|
|
6
|
+
const timeout = 20000, maxBuffer = 1024 * 1024;
|
|
7
|
+
const unavailable = detail => [{ code: "capture-health-unavailable", message:
|
|
8
|
+
`Capture health is unavailable (${detail}). Run oats capture --health --json to inspect the package reader failure; no capture or repair was attempted.` }];
|
|
9
|
+
|
|
10
|
+
// One fixed package command. No status/DB reads or diagnosis rules live here.
|
|
11
|
+
// Injection is an internal transport fixture seam, never a CLI/env override.
|
|
12
|
+
export function doctorCaptureWarnings({ env = process.env, cwd = process.cwd(), run = spawnSync } = {}) {
|
|
13
|
+
const childEnv = Object.fromEntries(["HOME", "USERPROFILE", "TMPDIR", "XDG_CACHE_HOME", "TURN_RECORD_ROOT"]
|
|
14
|
+
.filter(key => env[key] !== undefined).map(key => [key, env[key]]));
|
|
15
|
+
let result;
|
|
16
|
+
try {
|
|
17
|
+
result = run(process.execPath, [
|
|
18
|
+
...process.execArgv.filter(arg => arg === "--experimental-sqlite"), entry,
|
|
19
|
+
], { cwd, env: childEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
|
|
20
|
+
timeout, maxBuffer, killSignal: "SIGKILL", windowsHide: true });
|
|
21
|
+
} catch { return unavailable("command transport failed"); }
|
|
22
|
+
if (!result || result.error || result.signal || result.status !== 0) {
|
|
23
|
+
// Do not promote unvalidated stderr or failed stdout into diagnosis rows.
|
|
24
|
+
return unavailable(result?.error?.code === "ETIMEDOUT" ? "command timed out" :
|
|
25
|
+
result?.error?.code === "ENOBUFS" ? "command output exceeded its bound" : "command or reader failed");
|
|
26
|
+
}
|
|
27
|
+
if (typeof result.stdout !== "string" || typeof result.stderr !== "string" ||
|
|
28
|
+
Buffer.byteLength(result.stdout) + Buffer.byteLength(result.stderr) > maxBuffer)
|
|
29
|
+
return unavailable("command output exceeded its bound");
|
|
30
|
+
let health;
|
|
31
|
+
try { health = JSON.parse(result.stdout); }
|
|
32
|
+
catch { return unavailable("invalid package response"); }
|
|
33
|
+
if (!validCaptureHealthEnvelope(health)) return unavailable("invalid package health envelope");
|
|
34
|
+
return health.rows.map(({ code, message }) => ({ code, message }));
|
|
35
|
+
}
|
package/lib/session-viewer.mjs
CHANGED
|
@@ -32,9 +32,59 @@ const MOUSE_BINDINGS = [
|
|
|
32
32
|
["MouseDrag1Pane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -M"],
|
|
33
33
|
];
|
|
34
34
|
/** What a detach key runs, as ONE bind-key argument (a bare `;` argument would end bind-key and
|
|
35
|
-
* run the rest at once): mark the viewer session,
|
|
36
|
-
*
|
|
37
|
-
|
|
35
|
+
* run the rest at once): mark the viewer session, keep it past its last client (its
|
|
36
|
+
* client-detached hook, below, would remove it, and the mark with it, before the attach reads the
|
|
37
|
+
* mark), then detach the client that pressed the key. The attach's cleanup removes the session; the next attach's sweep does,
|
|
38
|
+
* if the attach died first. A constant: no caller text is ever part of a tmux command string. */
|
|
39
|
+
const DETACH_BINDING = "set-option @oats-detached 1 ; set-hook -u client-detached ; detach-client";
|
|
40
|
+
/** A viewer session's name, which its key table shares: `oatsview-<pid of the attach>-<8 hex>`.
|
|
41
|
+
* One pattern for the sweep and the hook below; the 8 hex digits are spelled out because a
|
|
42
|
+
* format inside tmux's `#{...}` cannot hold `}`. */
|
|
43
|
+
const VIEWER_NAME_PATTERN = `^oatsview-([0-9]+)-${"[0-9a-f]".repeat(8)}$`;
|
|
44
|
+
const VIEWER_NAME = new RegExp(VIEWER_NAME_PATTERN);
|
|
45
|
+
/** The index of the one global hook entry the kernel owns on the agents' server,
|
|
46
|
+
* `session-closed[900]` (docs/execution-targets.md, "Inspect, input and attach"). */
|
|
47
|
+
export const VIEWER_CLOSED_HOOK_INDEX = 900;
|
|
48
|
+
/** What that entry runs when a session closes: when the session's name is a viewer's, unbind the
|
|
49
|
+
* key table of that name. A key table belongs to the server and outlives its session. The
|
|
50
|
+
* viewer's own client-detached hook (the attach, below) unbinds it when it ends the session; a
|
|
51
|
+
* session can also end with no client detaching from it (its window ended, a kill-session), and
|
|
52
|
+
* only a global session-closed hook runs then: a session's own hooks are gone with it. The name is matched before it reaches a command. `run-shell -C`
|
|
53
|
+
* expands the name; tmux before 3.2 has no -C, the entry does nothing there, and the next attach's
|
|
54
|
+
* sweep removes the table. A constant: setting it again leaves the server as it was. */
|
|
55
|
+
const VIEWER_CLOSED_HOOK = `if-shell -F '#{m/r:${VIEWER_NAME_PATTERN},#{hook_session_name}}' "run-shell -C 'unbind-key -a -q -T #{hook_session_name}'"`;
|
|
56
|
+
/** Whether a process exists: kill(pid, 0), and EPERM (another user's) exists too. */
|
|
57
|
+
function processAlive(pid) {
|
|
58
|
+
try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Remove what attaches that died without detaching left on the server, and answer how many of
|
|
62
|
+
* each went. A viewer session goes when no client is attached and the attach named in it is gone;
|
|
63
|
+
* an attach that is alive may not have attached its client yet, or may be between a leave by its
|
|
64
|
+
* key and its own cleanup. A key table goes when no session has its name. Keys are listed before
|
|
65
|
+
* sessions: a viewer makes its session before its table, so a table listed belongs to a session
|
|
66
|
+
* that the later list shows, unless that session has ended. Nothing whose name is not a viewer's
|
|
67
|
+
* is touched, the shared locked table included. A failed call removes nothing and counts nothing:
|
|
68
|
+
* the attach goes on, and the next one sweeps again. */
|
|
69
|
+
function sweepViewers(run) {
|
|
70
|
+
const swept = { sessions: 0, tables: 0 };
|
|
71
|
+
let tables, sessions;
|
|
72
|
+
try {
|
|
73
|
+
tables = new Set(run(["list-keys"]).split("\n").map((line) => /^bind-key\s+(?:-r\s+)?-T\s+(\S+)\s/.exec(line)?.[1]).filter((t) => VIEWER_NAME.test(t ?? "")));
|
|
74
|
+
sessions = run(["list-sessions", "-F", "#{session_name}\t#{session_attached}"]).split("\n").map((line) => line.split("\t"));
|
|
75
|
+
} catch { return swept; }
|
|
76
|
+
const kept = new Set();
|
|
77
|
+
for (const [name, attached] of sessions) {
|
|
78
|
+
const viewer = VIEWER_NAME.exec(name);
|
|
79
|
+
if (!viewer || attached !== "0" || processAlive(Number(viewer[1]))) { kept.add(name); continue; }
|
|
80
|
+
try { run(["kill-session", "-t", `=${name}`]); swept.sessions++; } catch { kept.add(name); }
|
|
81
|
+
}
|
|
82
|
+
for (const table of tables) {
|
|
83
|
+
if (kept.has(table)) continue;
|
|
84
|
+
try { run(["unbind-key", "-a", "-q", "-T", table]); swept.tables++; } catch { /* the next attach sweeps again */ }
|
|
85
|
+
}
|
|
86
|
+
return swept;
|
|
87
|
+
}
|
|
38
88
|
|
|
39
89
|
/** Whether a `tmux -V` answer names a release with the client's `-T <features>` flag (tmux 3.2):
|
|
40
90
|
* `tmux X.Y` with an optional letter suffix only. A development build (`tmux next-3.6`,
|
|
@@ -61,6 +111,7 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
|
|
|
61
111
|
const run = (args) => exec("tmux", ["-u", "-S", target.socket, ...args], {
|
|
62
112
|
encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"], detached: true,
|
|
63
113
|
}).trim();
|
|
114
|
+
const swept = sweepViewers(run);
|
|
64
115
|
const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
|
|
65
116
|
// A keyed viewer reads a table of its own, named as its session: a binding in the locked table
|
|
66
117
|
// would be every viewer's, and the next viewer's unbind would remove it.
|
|
@@ -91,7 +142,11 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
|
|
|
91
142
|
run(["unbind-key", "-a", "-q", "-T", table]);
|
|
92
143
|
for (const binding of MOUSE_BINDINGS) run(["bind-key", "-T", table, ...binding]);
|
|
93
144
|
// The key is its own argv element, after the grammar admitted it.
|
|
94
|
-
if (detachKey !== undefined)
|
|
145
|
+
if (detachKey !== undefined) {
|
|
146
|
+
run(["bind-key", "-T", table, detachKey, DETACH_BINDING]);
|
|
147
|
+
// The table goes when the session does, however the session ended; no other index is touched.
|
|
148
|
+
run(["set-hook", "-g", `session-closed[${VIEWER_CLOSED_HOOK_INDEX}]`, VIEWER_CLOSED_HOOK]);
|
|
149
|
+
}
|
|
95
150
|
run(["set-option", "-t", viewer, "mouse", "on"]);
|
|
96
151
|
const env = { ...process.env }; delete env.TMUX;
|
|
97
152
|
/** Whether the detach key's binding ran: it marks the viewer session before it detaches. A
|
|
@@ -113,7 +168,28 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
|
|
|
113
168
|
clientFeatures.set(exec, sync);
|
|
114
169
|
}
|
|
115
170
|
const features = clientFeatures.get(exec) ? ["-T", "sync"] : [];
|
|
116
|
-
|
|
171
|
+
// The client sets the viewer session's client-detached hook itself, after its attach succeeded
|
|
172
|
+
// (a command chained after attach-session runs only then; a viewer whose client never attached
|
|
173
|
+
// is the cleanup's, or the next attach's sweep's): when a client goes and none is left, the hook
|
|
174
|
+
// kills the viewer session. tmux finds this session's hook only when the client's connection
|
|
175
|
+
// drops with no word from the client: a SIGKILL of the attach and its client (oomd, a stop
|
|
176
|
+
// timeout), a crashed client. A client that leaves any other way (a hang-up or SIGTERM, which
|
|
177
|
+
// the client answers with MSG_EXITING; a `detach-client`; the detach key) has its session
|
|
178
|
+
// cleared before it has left, and the hook is then looked up on another session: the attach's
|
|
179
|
+
// own cleanup removes such a viewer, or, when the attach has died, the next attach's sweep.
|
|
180
|
+
// Never `destroy-unattached on` instead: on tmux 3.4 a `detach-client` from another client only
|
|
181
|
+
// flags the detached client CLIENT_EXIT; until that client answers (MSG_EXITING) it keeps its
|
|
182
|
+
// session, but recalculate_sizes no longer counts it as attached, so the next client lost
|
|
183
|
+
// (any command client) runs server_check_unattached, which destroys the session under it, and
|
|
184
|
+
// the server's next loop dereferences the session's NULL curw: SIGSEGV, every agent's session
|
|
185
|
+
// gone (#1336). client-detached fires only once the client has left the server's client list.
|
|
186
|
+
// A keyed viewer's hook unbinds its table too: tmux runs no hook for what a hook's own commands
|
|
187
|
+
// cause, so the session-closed entry does not run for a session this kill-session ends. The
|
|
188
|
+
// unbind comes first: a command list stops at a command that fails, as this kill-session does
|
|
189
|
+
// when the session has already ended.
|
|
190
|
+
const removal = table === LOCKED_TABLE ? `kill-session -t =${viewer}` : `unbind-key -a -q -T ${table} ; kill-session -t =${viewer}`;
|
|
191
|
+
const attach = ["attach-session", "-t", `=${viewer}`, ";", "set-hook", "-t", `=${viewer}:`, "client-detached", `if-shell -F '#{==:#{session_attached},0}' '${removal}'`];
|
|
192
|
+
return { binary: "tmux", args: ["-u", "-S", target.socket, ...features, ...attach], env, cleanup, detached, session: viewer, swept };
|
|
117
193
|
} catch (e) { cleanup(); throw e; }
|
|
118
194
|
}
|
|
119
195
|
|
|
@@ -131,8 +207,9 @@ function holdQuit() {
|
|
|
131
207
|
}
|
|
132
208
|
|
|
133
209
|
/** Attach this terminal to a viewer of the target and answer the client's status, or
|
|
134
|
-
* SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach.
|
|
135
|
-
|
|
210
|
+
* SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach. `onSwept` is given what
|
|
211
|
+
* the preparation swept, `{ sessions, tables }`, before the client starts. */
|
|
212
|
+
export async function attachSessionTarget(target, { detachKey, onSwept } = {}) {
|
|
136
213
|
if (detachKey !== undefined) { requireDetachKey(detachKey); holdQuit(); }
|
|
137
214
|
// HUP, TERM and INT are held from before the viewer session exists until its cleanup has
|
|
138
215
|
// finished: one that arrives in between, early or late, finds a listener and not the default
|
|
@@ -153,6 +230,8 @@ export async function attachSessionTarget(target, { detachKey } = {}) {
|
|
|
153
230
|
// key pressed again, and the attach ends as a detach.
|
|
154
231
|
if (detachKey !== undefined) onQuit = () => { if (viewer.detached()) return; quit = true; stop(); };
|
|
155
232
|
try {
|
|
233
|
+
// Inside the try: a report that throws (a closed stderr) still has the viewer removed.
|
|
234
|
+
onSwept?.(viewer.swept);
|
|
156
235
|
// A signal received during the synchronous preparation is dispatched only in a poll phase of
|
|
157
236
|
// the event loop. Two setImmediate hops run at least one, wherever this attach was called
|
|
158
237
|
// from, so such a signal stops the attach here, before a client takes the terminal: one loop
|