@awebai/oats 0.68.1 → 0.69.1
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/bin/oats.mjs +102 -22
- package/docs/capabilities.md +49 -5
- package/docs/configuration.md +68 -2
- package/docs/desktop-cli-api.md +355 -12
- package/docs/desktop-instance-start.md +88 -3
- package/docs/desktop.md +108 -10
- package/docs/execution-targets.md +514 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +28 -11
- package/docs/integrations.md +1 -1
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +4 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/servers.md +44 -5
- package/docs/souls-and-instances.md +11 -7
- package/docs/tui.md +77 -12
- package/docs/upgrading.md +12 -7
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +345 -89
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/launch-prompt-fixtures/README.md +62 -0
- package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
- package/lib/launch-prompt-fixtures.mjs +49 -0
- package/lib/launch-prompt-resume.mjs +55 -0
- package/lib/login-environment.mjs +27 -9
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +117 -23
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +32 -0
- package/lib/session-resume.mjs +310 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +2 -1
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +38 -4
- package/package-catalog.json +10 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -0
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +7 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/session-attach.mjs +35 -5
- package/packages/client/session-resume-cli.mjs +64 -0
- package/packages/client/session-resume-trigger.mjs +167 -0
- package/packages/client/session-resume.mjs +332 -0
- package/packages/client/tmux-status.mjs +30 -7
- package/packages/client/waiting-on-you.mjs +11 -4
- package/packages/client/workspace-step.mjs +17 -5
- package/packages/record/lib/last-conversation.mjs +123 -0
- package/packages/record/lib/session-roots.mjs +10 -1
- package/packages/tui/lib/client.mjs +1 -1
- package/packages/tui/lib/main.mjs +5 -3
- package/packages/tui/lib/model.mjs +45 -12
- package/packages/tui/lib/store.mjs +8 -7
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/frame.mjs +72 -7
- package/packages/tui/lib/views/help.mjs +8 -3
- package/packages/tui/lib/views/instances.mjs +3 -2
- package/skills/oats-getting-started/SKILL.md +117 -4
package/docs/desktop-cli-api.md
CHANGED
|
@@ -49,7 +49,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
49
49
|
"status-retire-state","session-inspect-size","session-inspect-running","deployments-list"],
|
|
50
50
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
51
51
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
52
|
-
"capabilityShowApi":1}
|
|
52
|
+
"capabilityShowApi":1,"sessionViewer":{"prefixScroll":true}}
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
- The Desktop accepts `desktopApi === 1` and a released `version` inside
|
|
@@ -65,6 +65,14 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
65
65
|
probe before a routed mutation. From 0.31: `readiness`, `instance-events`,
|
|
66
66
|
`instance-git` and `lifecycle-plans` name the
|
|
67
67
|
[routed reads and plans](#routed-reads-and-plans).
|
|
68
|
+
- `sessionViewer` (feature `session-attach-prefix-scroll`) is a fact of
|
|
69
|
+
this host, not of the binary: `prefixScroll` is `true` when a viewer
|
|
70
|
+
without a detach key binds `C-b [` here, that is when the `tmux` on
|
|
71
|
+
`PATH` is 3.3 or later (`tmuxForwardsBoundKey`, lib/session-viewer.mjs),
|
|
72
|
+
and `false` with an older tmux or none. The kernel asks `tmux -V` afresh
|
|
73
|
+
at every run and keeps no answer, so read it again after a tmux upgrade.
|
|
74
|
+
The feature is in every kernel's list that has the field, whatever this
|
|
75
|
+
host's tmux: gate on the feature, then read the field.
|
|
68
76
|
- In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
|
|
69
77
|
|
|
70
78
|
### Features
|
|
@@ -129,6 +137,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
129
137
|
| `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
130
138
|
| `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
131
139
|
| `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
|
|
140
|
+
| `session-attach-no-status-line` | `oats session attach … --no-status-line`, local and `--server`: a viewer without a detach key, without its status line (`Shift+PgUp or C-b [ to scroll back`), for a caller that shows the scroll keys itself ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe: a kernel without it ignores the flag and shows the line. A routed attach sends it to any host, with no probe of its own | |
|
|
141
|
+
| `session-attach-prefix-scroll` | `sessionViewer: {prefixScroll}` on `oats version --json` and `oats status --json`, and `probe.sessionViewer` on each `oats server roster --json` group: whether that host's viewer without a detach key binds `C-b [` (tmux 3.3 and later), read afresh per host at each run. A kernel with the feature has the viewer's `Shift+PgUp` binding; one without it may not, so don't name the viewer's scroll keys for its tabs ([execution-targets.md](execution-targets.md#inspect-input-and-attach)) | |
|
|
132
142
|
| `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
|
|
133
143
|
| `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
|
|
134
144
|
| `lifecycle-claim-stop` | `oats instance stop --apply` holds the claim of every target (the file one retire of a home at a time is ordered by), so a stop is refused beside a retire in flight (`E_INSTANCE_RETIRING`) or another stop (`E_LIFECYCLE_BUSY`), a retire beside a stop (`E_LIFECYCLE_BUSY`), and `oats worktree add` beside a retire (`E_INSTANCE_RETIRING`), each before any effect ([Commands that meet on one home](#lifecycle-pairs)); a stop that was killed refuses nothing afterwards, and `<home>/.oats-stop-pending.json` is no longer written or read: a client's own handling of a stale stop marker is not needed for a kernel that lists this; `error.details.action` (the holder's verb) on those refusals, and `error.details.holder` on every `E_LIFECYCLE_BUSY` ([`details.holder`](#busy-holder)); the codes a stop and a retire answer only before any effect, as one list ([the list](#before-effect-codes)), with two retire answers that came after an effect given codes outside it (`E_WORK_PRESERVATION_FAILED`, `E_RUNTIME_QUIESCE_FAILED`), OATS 0.52.0. Gate on the probe; routed with `--server`, on the host's list | |
|
|
@@ -143,6 +153,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
143
153
|
| `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
|
|
144
154
|
| `instance-suggest-name` | `oats instance suggest-name --soul <soul> (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn of `<soul>` would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
|
|
145
155
|
| `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
|
|
156
|
+
| `session-resume` | sessions come back after a shutdown, OATS 0.69 (#1559): `sessionEnd` on `oats status --json` instance rows ([`sessionEnd`](#row-session-end)); `oats session start --resume --home <abs>` and its `resume` answer ([Resume a lost session](#resume-a-lost-session---resume)); the machine sweep `oats session resume [--deployment <dir>] [--plan] --json` ([`oats session resume`](#the-machine-sweep-oats-session-resume)); `E_RESUME_BUSY`, `E_RESUME_NOT_LOST`. Local only: `--server` is `E_BAD_ARGS`. Gate a client's resume-on-open on the probe: a kernel without it has no `session resume` | |
|
|
146
157
|
|
|
147
158
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
148
159
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -2453,6 +2464,10 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2453
2464
|
otherwise. Show it, and `yolo`, whenever it is `true`. An explicit
|
|
2454
2465
|
`--launch-config none` asks for the bare harness and bypasses the default;
|
|
2455
2466
|
to run the host's default, omit `--launch-config`.
|
|
2467
|
+
- `launchConfigSource` (0.69) is the directory of the file that declares
|
|
2468
|
+
`launchConfig`: the deployment, or `~/.oats/config` for
|
|
2469
|
+
[this machine's launch configurations](configuration.md#this-machines-launch-configurations);
|
|
2470
|
+
`null` when there is no `launchConfig`. A spawn records the same value.
|
|
2456
2471
|
- `modelSource` is `"explicit"`, `"soul default"`, `"launch-config <name>"`,
|
|
2457
2472
|
`"native default"` or `"native default (explicit)"` (`--model
|
|
2458
2473
|
@native-default`). Omitting `--model` and asking for the native default are
|
|
@@ -3231,8 +3246,12 @@ its absence.
|
|
|
3231
3246
|
"shell"`, even though the window remains; a dead pane or absent window is
|
|
3232
3247
|
`false`. A wrapper shell with a live non-shell descendant stays `true`;
|
|
3233
3248
|
`null` with `runtimeState: "unreachable"` and the tmux error as
|
|
3234
|
-
`runtimeError` when that server or its panes cannot be read (including a
|
|
3235
|
-
|
|
3249
|
+
`runtimeError` when that server or its panes cannot be read (including a
|
|
3250
|
+
window where OATS cannot tell which pane is the agent's
|
|
3251
|
+
([which pane is the agent's](execution-targets.md#which-pane-is-the-agents)),
|
|
3252
|
+
a session with two windows of the instance's name, or a failed
|
|
3253
|
+
shell-descendant process scan; a window whose agent's pane is found reads by
|
|
3254
|
+
that pane alone), and also when its socket
|
|
3236
3255
|
file is missing while a process works in the home or the process scan
|
|
3237
3256
|
cannot run, `runtimeError` then naming the processes or the scan's error
|
|
3238
3257
|
([#624](execution-targets.md#missing-socket); with no process in the home
|
|
@@ -3283,6 +3302,31 @@ its absence.
|
|
|
3283
3302
|
An older kernel's `running` is the window's presence, and it checks a row
|
|
3284
3303
|
with a claim against its session (as `oats session inspect` observes it),
|
|
3285
3304
|
reading `null` unless a harness runs there.
|
|
3305
|
+
- <a id="row-session-end"></a>**`sessionEnd`** (feature `session-resume`, OATS
|
|
3306
|
+
0.69): how the last session of a launched home that does not run ended:
|
|
3307
|
+
`lost` (the host went down, its tmux server died, or the harness was killed
|
|
3308
|
+
by a signal: the sweep brings it back when it can vouch for the loss,
|
|
3309
|
+
[Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
|
|
3310
|
+
`oats instance stop`, Desktop's Stop) or `exited` (the harness ended by
|
|
3311
|
+
itself: `/exit`, its own error). Present only on a row that reads
|
|
3312
|
+
`running: false` and records `launched: true`, a row at its fallback shell
|
|
3313
|
+
(`runtimeState: "shell"`) included; absent while it runs or reads unknown
|
|
3314
|
+
(`running: null`), for a home never launched, on rows with `retirePending`,
|
|
3315
|
+
`rollbackIncomplete` or `spawnInProgress`, and from older kernels. Read
|
|
3316
|
+
from the home's current start (`startId`; its time is the last
|
|
3317
|
+
`restarts[].startedAt`, else `createdAt`) and two kernel-private files of
|
|
3318
|
+
the home, not a contract ([execution-targets.md](execution-targets.md#how-a-sessions-end-is-read)).
|
|
3319
|
+
A home spawned before 0.69 and never restarted since reads `lost` when its
|
|
3320
|
+
harness ended on its own; its next start covers it.
|
|
3321
|
+
- **A local status read records what it sees** (feature `session-resume`,
|
|
3322
|
+
OATS 0.69): per home, its current start, when it was last seen running and
|
|
3323
|
+
first seen not running, with the boot of each, in a kernel-private file of
|
|
3324
|
+
this machine, one per deployment, under `~/.oats/session-resume/seen/`
|
|
3325
|
+
(`$OATS_HOME_DIR` when set), beside the sweep's per-boot note; it is not a
|
|
3326
|
+
contract, and only the sweep reads it. It never changes the answer: not the
|
|
3327
|
+
output, not the exit status, and nothing is printed, whether or not it can
|
|
3328
|
+
be read or written. A status routed with `--server` records nothing on this
|
|
3329
|
+
machine ([execution-targets.md](execution-targets.md#which-losses-come-back)).
|
|
3286
3330
|
- **`color`** (feature `instance-color`): the instance's colour, one of
|
|
3287
3331
|
`sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
|
|
3288
3332
|
from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
|
|
@@ -3357,6 +3401,10 @@ its absence.
|
|
|
3357
3401
|
relays a host's features from the status answer it already pulls. It is
|
|
3358
3402
|
emitted at output time, never part of a reused observation. A kernel
|
|
3359
3403
|
before 0.49.0 omits it.
|
|
3404
|
+
- **`sessionViewer`** (feature `session-attach-prefix-scroll`): this host's
|
|
3405
|
+
`{prefixScroll}`, as `version --json` answers it, read afresh at each
|
|
3406
|
+
run and never part of a reused observation, so a roster relays it from
|
|
3407
|
+
the status answer it already pulls.
|
|
3360
3408
|
- `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
|
|
3361
3409
|
`warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
|
|
3362
3410
|
|
|
@@ -3436,7 +3484,7 @@ route target:
|
|
|
3436
3484
|
```json
|
|
3437
3485
|
{"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
|
|
3438
3486
|
"target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
|
|
3439
|
-
"probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"]},"agentsRoot":"/srv/team/agents",
|
|
3487
|
+
"probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"],"sessionViewer":{"prefixScroll":true}},"agentsRoot":"/srv/team/agents",
|
|
3440
3488
|
"workspace":{"reachable":true,"key":"github.com/acme/team","ref":"git:github.com/acme/team","keyFrom":"workspace","standalone":false,"defaultTeam":{"label":"default","team":"acme:team"},
|
|
3441
3489
|
"teams":{"default":"acme:team"},"teamsFrom":"observed"},
|
|
3442
3490
|
"souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
|
|
@@ -3454,9 +3502,10 @@ route target:
|
|
|
3454
3502
|
"retireFailures":[]}
|
|
3455
3503
|
```
|
|
3456
3504
|
|
|
3457
|
-
- **`probe`**: `{ok: true, features}` when the host's
|
|
3458
|
-
pulled, else `{ok: false, error: {code, message}}`
|
|
3459
|
-
out, `E_SSH`; or the host answered `ok: false`),
|
|
3505
|
+
- **`probe`**: `{ok: true, features, sessionViewer}` when the host's
|
|
3506
|
+
`status --json` was pulled, else `{ok: false, error: {code, message}}`
|
|
3507
|
+
(ssh failed or timed out, `E_SSH`; or the host answered `ok: false`),
|
|
3508
|
+
with no `features` and no `sessionViewer` key.
|
|
3460
3509
|
Every group is probed at once, each within its own deadline, so a group's
|
|
3461
3510
|
`probe` depends only on its own host: one that does not answer in time is
|
|
3462
3511
|
`E_SSH` with `ssh to <host> timed out: no answer within <n> s`, and every
|
|
@@ -3475,6 +3524,13 @@ route target:
|
|
|
3475
3524
|
its version. Read it as `Array.isArray(probe?.features)`: not an array
|
|
3476
3525
|
means unknown; `[]` is a valid answer (a host with no features), not
|
|
3477
3526
|
unknown.
|
|
3527
|
+
- **`probe.sessionViewer`** (feature `session-attach-prefix-scroll`): the
|
|
3528
|
+
host's `{prefixScroll}`, relayed from the `sessionViewer` of its
|
|
3529
|
+
[`status --json`](#the-roster-oats-status---json), never probed. It is
|
|
3530
|
+
relayed as a copy of `{prefixScroll}` only when that is a boolean;
|
|
3531
|
+
anything else, or a host whose kernel predates the field, is `null`.
|
|
3532
|
+
Read it only for a host whose `probe.features` lists
|
|
3533
|
+
`session-attach-prefix-scroll`.
|
|
3478
3534
|
- **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
|
|
3479
3535
|
own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
|
|
3480
3536
|
relayed verbatim, or `null` when the host reports none (a deployment
|
|
@@ -3696,7 +3752,9 @@ An envelope, `ok: true` whenever no step failed, human steps included
|
|
|
3696
3752
|
- `registration` is the registration as written or found (`sshHost`,
|
|
3697
3753
|
`workspace`: the absolute path the host resolved for `--dir`, never `~`;
|
|
3698
3754
|
`workspaceKey`; and `oatsPath`, `path`,
|
|
3699
|
-
`label` when set
|
|
3755
|
+
`label` when set, given or, without `--path`, read from the host user's
|
|
3756
|
+
[login shell](servers.md#the-hosts-login-shell-path)), `null` until the
|
|
3757
|
+
`register` step has run.
|
|
3700
3758
|
- `human` lists the remedies of the `needs-human` steps, in order. A
|
|
3701
3759
|
`readiness` step that needs a human has one line per problem
|
|
3702
3760
|
(`<souls>: <subject>: <reason>[ → <remedy>]`, plus `readiness not checked
|
|
@@ -4012,7 +4070,10 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
4012
4070
|
message}` per producer with a live claim in the current incarnation
|
|
4013
4071
|
(cleared ones included). A producer's latest row with `data.waitingOnYou`
|
|
4014
4072
|
decides. `waitingOnYou` is `{since, producer, reason, message}` of the
|
|
4015
|
-
newest positive claim
|
|
4073
|
+
newest positive claim that has a message, so a claim with no text never
|
|
4074
|
+
hides one with text; when its `reason` is `null`, the newest text-less
|
|
4075
|
+
claim's reason fills it. With no message anywhere it is the newest
|
|
4076
|
+
positive claim, or `null` (unknown, not "not waiting"). See
|
|
4016
4077
|
[Waiting on you](#waiting-on-you) for the producers and the rules.
|
|
4017
4078
|
- Errors: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`,
|
|
4018
4079
|
`E_BAD_ARGS`, `E_EVENTS_FAILED`.
|
|
@@ -4063,8 +4124,14 @@ oats instance attention [--message <text>] [--clear] --json
|
|
|
4063
4124
|
only ever the message, never a flag (`--message=--clear` sets the message
|
|
4064
4125
|
"--clear"). The spaced form `--message --deploy` reads `--deploy` as a
|
|
4065
4126
|
flag and is `E_BAD_ARGS`. It is stored as given, only on a
|
|
4066
|
-
positive claim. The reader applies the same rule again
|
|
4067
|
-
|
|
4127
|
+
positive claim. The reader applies the same rule again, with one
|
|
4128
|
+
difference: a stored message over 200 code points (a row from another
|
|
4129
|
+
producer or an older writer, or a remote kernel's claim) is cut to 200, the
|
|
4130
|
+
last one `…`. So `waitingOnYou.message` and each `waitingClaims[].message`
|
|
4131
|
+
are never longer than 200 code points, whoever wrote them. The cut counts
|
|
4132
|
+
code points: a surrogate pair is never split, but a combining mark may be
|
|
4133
|
+
left out. A message that is still invalid after that (a refused character,
|
|
4134
|
+
a hand-edited log) reads as `null`, and the claim still counts.
|
|
4068
4135
|
A stored `reason` outside `permission`, `question`, `attention` reads as
|
|
4069
4136
|
`null` too, and a row whose `producer` is neither `kernel` nor a valid
|
|
4070
4137
|
producer id, or whose `at` is not a date, is no claim at all.
|
|
@@ -4475,7 +4542,12 @@ leaves nothing of its own in the home: the private file each of the two
|
|
|
4475
4542
|
writes goes through (`.oats-stop.json.tmp-<pid>`,
|
|
4476
4543
|
`.oats-stop-receipt.<key>.json.<pid>.tmp`) is removed when its write or its
|
|
4477
4544
|
rename fails. Before 0.53.0 each apply on a full disk left both there,
|
|
4478
|
-
empty.
|
|
4545
|
+
empty. With no record of the stop, the instance then reads
|
|
4546
|
+
[`sessionEnd: "lost"`](#row-session-end), and a resume sweep would start it
|
|
4547
|
+
again: stop it once more when the disk has space (a stop of an instance that
|
|
4548
|
+
reads `lost` records the stop, signalling nothing). The exit marker of the
|
|
4549
|
+
harness's window (0.69) is not the stop's: the window's shell writes it when
|
|
4550
|
+
the harness ends, and on a full disk its write fails too.
|
|
4479
4551
|
|
|
4480
4552
|
In 0.52.0 a stop whose claim could not be written for one of those five
|
|
4481
4553
|
codes was refused like the others, before anything was signalled
|
|
@@ -5861,7 +5933,9 @@ harness receipt. See [execution targets](execution-targets.md).
|
|
|
5861
5933
|
|
|
5862
5934
|
```text
|
|
5863
5935
|
oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
|
|
5936
|
+
oats session start --resume --home <abs> --json
|
|
5864
5937
|
oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
|
|
5938
|
+
oats session resume [--deployment <dir>] [--plan] --json
|
|
5865
5939
|
```
|
|
5866
5940
|
|
|
5867
5941
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
@@ -5941,6 +6015,152 @@ warning naming the same-key cleanup retry.
|
|
|
5941
6015
|
[`details.cause`](#kernel-codes) when it has a code of its own or is a
|
|
5942
6016
|
defect, and without it when it is a refusal without a code).
|
|
5943
6017
|
|
|
6018
|
+
#### Resume a lost session (`--resume`)
|
|
6019
|
+
|
|
6020
|
+
`oats session start --resume --home <abs> --json` (feature `session-resume`,
|
|
6021
|
+
OATS 0.69) is the ordinary start of a home whose session was lost
|
|
6022
|
+
([`sessionEnd: "lost"`](#row-session-end)), in the harness's own last
|
|
6023
|
+
conversation: the same locks, checks, recorded recipe and launch hooks under
|
|
6024
|
+
the captured settings, with the conversation's selector and the resume
|
|
6025
|
+
notice in place of the task prompt
|
|
6026
|
+
([execution-targets.md](execution-targets.md#resume-after-a-shutdown)). Its
|
|
6027
|
+
answer is the ordinary start answer plus one object:
|
|
6028
|
+
|
|
6029
|
+
```json
|
|
6030
|
+
"resume": {
|
|
6031
|
+
"resumed": true,
|
|
6032
|
+
"reason": "no-conversation",
|
|
6033
|
+
"harness": "claude",
|
|
6034
|
+
"sessionId": "<the harness's session id>",
|
|
6035
|
+
"waiting": "resume-confirmation"
|
|
6036
|
+
}
|
|
6037
|
+
```
|
|
6038
|
+
|
|
6039
|
+
- `resumed: true` with `sessionId` when it continues that conversation;
|
|
6040
|
+
`resumed: false` with `reason` when it started fresh on `TASK.md` instead:
|
|
6041
|
+
`no-conversation` (no transcript of this incarnation whose cwd is the
|
|
6042
|
+
home), `no-receipts` (no native-record receipt of this incarnation names
|
|
6043
|
+
where the harness writes), `resume-unproven` (Codex, until a resume of it
|
|
6044
|
+
is proven end to end on a signed-in host).
|
|
6045
|
+
- `waiting: "resume-confirmation"`: the start **succeeded** (exit 0, the
|
|
6046
|
+
session runs and is kept) and Claude is waiting for its human to choose how
|
|
6047
|
+
to resume a long conversation (its resume-cost dialog). No key was sent.
|
|
6048
|
+
Absent otherwise, an unrecognised screen after the bound included.
|
|
6049
|
+
- Refused before anything is read, `E_BAD_ARGS`: `--resume` with
|
|
6050
|
+
`--launch-config`, `--harness`, `--model`, `--yolo`, `--no-yolo` or
|
|
6051
|
+
`--reselect-launch`; `--resume` on `session restart`; `--server`.
|
|
6052
|
+
- Refused `E_RESUME_NOT_LOST` when the home did not lose its session
|
|
6053
|
+
(`stopped`, `exited`, never launched), read under the start lock before
|
|
6054
|
+
any launch hook runs; nothing was started.
|
|
6055
|
+
- Refused `E_LAUNCH_ENV_CHANGED` when a `{fromEnv}` value differs from the
|
|
6056
|
+
one the start it brings back ran with (checked after `E_LAUNCH_ENV_MISSING`):
|
|
6057
|
+
the message names the variables, sorted, never a value; nothing was
|
|
6058
|
+
started. A home with no record of its last start's values (last started
|
|
6059
|
+
by an earlier kernel, or a record that does not read) is resumed, and
|
|
6060
|
+
`warnings` carries once `<instance>'s launch environment could not be
|
|
6061
|
+
verified this once (it was last started before OATS recorded it); its
|
|
6062
|
+
next start records it` ([The launch environment a resume runs
|
|
6063
|
+
under](execution-targets.md#the-launch-environment-a-resume-runs-under)).
|
|
6064
|
+
- Every refusal of an ordinary start answers as it does there
|
|
6065
|
+
(`E_SESSION_RUNNING`, `E_SESSION_START_BUSY`, `E_SESSION_UNKNOWN`,
|
|
6066
|
+
`E_LAUNCH_LEGACY` for a home with no recipe, `E_LAUNCH_ENV_MISSING`, …); a
|
|
6067
|
+
development-channel prompt that stops it is `E_SPAWN_INCOMPLETE` with
|
|
6068
|
+
`details.launchPrompts`, unchanged. A start by hand is neither bounded
|
|
6069
|
+
nor counted by the sweep's 3 resumes per home per boot.
|
|
6070
|
+
- What is persisted is the ordinary launch: `instance.json` `command`, the
|
|
6071
|
+
pending receipt and the recipe never carry the selector or the notice, so a
|
|
6072
|
+
later ordinary start opens a fresh conversation.
|
|
6073
|
+
|
|
6074
|
+
### The machine sweep (`oats session resume`)
|
|
6075
|
+
|
|
6076
|
+
`oats session resume [--deployment <dir>] [--plan] --json` (feature
|
|
6077
|
+
`session-resume`, OATS 0.69) starts with `--resume` every home of this
|
|
6078
|
+
machine's deployments whose session was lost. A client runs it once when it
|
|
6079
|
+
opens. It reads this computer's list of deployments without writing it
|
|
6080
|
+
([This computer's deployments](#this-computers-deployments-oats-deployments)),
|
|
6081
|
+
and never sweeps one `oats deployments remove` took out;
|
|
6082
|
+
`--deployment <dir>` sweeps that one directory instead, listed or not. Each
|
|
6083
|
+
home starts as a child process of the kernel, in its own deployment's scope,
|
|
6084
|
+
at most 4 at once.
|
|
6085
|
+
|
|
6086
|
+
The answer is the standard envelope, exit 0 whenever the sweep ran,
|
|
6087
|
+
whatever the rows say:
|
|
6088
|
+
|
|
6089
|
+
```json
|
|
6090
|
+
{"schemaVersion":1,"ok":true,"result":{
|
|
6091
|
+
"schemaVersion": 1,
|
|
6092
|
+
"plan": false,
|
|
6093
|
+
"deployments": [
|
|
6094
|
+
{ "deployment": "/abs/dep", "state": "ok", "swept": true },
|
|
6095
|
+
{ "deployment": "/abs/gone", "state": "missing", "swept": false, "reason": "not-ok" }
|
|
6096
|
+
],
|
|
6097
|
+
"rows": [
|
|
6098
|
+
{ "deployment": "/abs/dep", "instance": "x", "home": "/abs/dep/agents/s/instances/x", "outcome": "resumed", "sessionId": "…" },
|
|
6099
|
+
{ "deployment": "/abs/dep", "instance": "y", "home": "…", "outcome": "fresh", "reason": "no-conversation" },
|
|
6100
|
+
{ "deployment": "/abs/dep", "instance": "z", "home": "…", "outcome": "already-running" }
|
|
6101
|
+
]}}
|
|
6102
|
+
```
|
|
6103
|
+
|
|
6104
|
+
- **`deployments[]`**: one entry per deployment considered, sorted by path.
|
|
6105
|
+
`state` is the list's state of it (`ok`, `missing`, `not-a-deployment`,
|
|
6106
|
+
`unreadable`). `swept: false` has a `reason`: `not-ok` (its state is not
|
|
6107
|
+
`ok`) or `unreadable` (its status could not be read; `code` and `message`
|
|
6108
|
+
then). Nothing opts a deployment out: stopping an instance with OATS is
|
|
6109
|
+
the only way to keep it down.
|
|
6110
|
+
- **`rows[]`**: one row per home that is lost (whatever its outcome),
|
|
6111
|
+
running (`already-running`) or unknown (`skipped`, `unknown`); stopped,
|
|
6112
|
+
exited and never-launched homes are not listed. Fields: `deployment`,
|
|
6113
|
+
`instance`, `home`, `outcome`, and only when they apply `reason`, `code`,
|
|
6114
|
+
`message`, `launchPrompts`, `sessionId` (resumed) and `warnings` (the
|
|
6115
|
+
start's warnings verbatim, an array of strings, present only when not
|
|
6116
|
+
empty: a client lists `channel-cache-unchecked` from here), without the
|
|
6117
|
+
host-wide ones the sweep's own `warnings` carries.
|
|
6118
|
+
|
|
6119
|
+
| `outcome` | `reason` |
|
|
6120
|
+
|---|---|
|
|
6121
|
+
| `resumed` | none |
|
|
6122
|
+
| `fresh` | `no-conversation`, `no-receipts`, `resume-unproven` |
|
|
6123
|
+
| `already-running` | none |
|
|
6124
|
+
| `skipped` | `not-seen-recently` (the sweep cannot vouch for this loss: OATS never saw the home running for its current start, an earlier sweep already answered the loss, the loss was first seen 24 hours ago or more, or, within one boot, it was first seen 24 hours or more after the last running look; with a `message` that says which, nothing started: [Which losses come back](execution-targets.md#which-losses-come-back)), `unknown` (running reads `null`, or the start could not establish it: `code` `E_SESSION_UNKNOWN`), `start-busy` (`E_SESSION_START_BUSY`: a concurrent start), `not-lost` (`E_RESUME_NOT_LOST` or `E_SESSION_RUNNING`: it stopped or started between the read and the start) |
|
|
6125
|
+
| `blocked` | `resume-confirmation` (Claude's resume-cost dialog: the session runs and waits for its human), `launch-prompt` (`code` `E_SPAWN_INCOMPLETE`, with `launchPrompts`: the session is kept) |
|
|
6126
|
+
| `refused` | `start-refused` (`code` and `message`: the start's own refusal), `refused-this-boot` (an earlier sweep in this boot was refused for this home and start, and its answer to the loss was lost: reported again with that `code` and `message`, nothing started; a refused loss is never retried automatically, after a reboot either), `keeps-getting-lost` (sweeps started this home 3 times in this boot and it was lost again each time: nothing started, no `code`, a `message` that says so; no sweep starts this loss again, after a reboot either: a person starts it by hand) |
|
|
6127
|
+
|
|
6128
|
+
The kernel defines every `sessionEnd`, `resume` and row name in one
|
|
6129
|
+
module, `lib/session-resume-contract.mjs`; a change to one is a contract
|
|
6130
|
+
change ([#1567](https://github.com/awebai/oats/issues/1567)).
|
|
6131
|
+
|
|
6132
|
+
- **`warnings`**, beside `rows`, present only when there is one: an array
|
|
6133
|
+
of distinct strings, each a warning the sweep's starts said of the host
|
|
6134
|
+
rather than of their home, once whatever the number of starts that said
|
|
6135
|
+
it, verbatim. Today that is only the agent-scope warning (the harness
|
|
6136
|
+
runs in the OATS tmux server's cgroup, not a scope of its own, and why).
|
|
6137
|
+
Each start still records it in its own home's events. `--plan` has none.
|
|
6138
|
+
- A lost home is answered with the first that applies: `not-seen-recently`,
|
|
6139
|
+
`refused-this-boot`, `keeps-getting-lost`, then its start. A sweep that is
|
|
6140
|
+
not a plan answers each lost home once: a later sweep answers that loss
|
|
6141
|
+
`not-seen-recently`.
|
|
6142
|
+
- `--plan`: the same shape with `"plan": true`; nothing is started, no lock
|
|
6143
|
+
taken, no note written, no loss answered (its own status read records what
|
|
6144
|
+
it sees, as any local status read does). A lost home's outcome is the prediction: `resumed`
|
|
6145
|
+
(with `sessionId`) or `fresh` with its reason (and the launch-environment
|
|
6146
|
+
warning a start would give), `refused` for a noted refusal, a home sweeps
|
|
6147
|
+
started 3 times in this boot, a home with no recipe, or a launch reference
|
|
6148
|
+
the start would refuse (`E_LAUNCH_ENV_MISSING`, `E_LAUNCH_ENV_CHANGED`,
|
|
6149
|
+
from the sweep's environment). Clients should not call `--plan` on open.
|
|
6150
|
+
- **One sweep per machine.** A second sweep while one runs answers
|
|
6151
|
+
`E_RESUME_BUSY` through the standard failure envelope
|
|
6152
|
+
(`{"schemaVersion":1,"ok":false,"error":{"code":"E_RESUME_BUSY","message":"…"}}`,
|
|
6153
|
+
exit 1); nothing was started, and a client shows no notice. The lock and
|
|
6154
|
+
the per-boot note (refusals, and each home's count of sweep starts that
|
|
6155
|
+
launched something: `resumed`, `fresh`, `blocked`) are kernel-private,
|
|
6156
|
+
not a contract. Without a boot id (neither Linux nor macOS) nothing is
|
|
6157
|
+
noted or counted.
|
|
6158
|
+
- Errors: `E_RESUME_BUSY`; `E_BAD_ARGS` (`--deployment` that is not a
|
|
6159
|
+
deployment directory, `--server`, an unknown flag or an argument); without
|
|
6160
|
+
`--deployment`, the list's own errors (`E_DEPLOYMENTS_INVALID`,
|
|
6161
|
+
`E_DEPLOYMENTS_VERSION`). A home's start failure is a row, never the
|
|
6162
|
+
sweep's failure.
|
|
6163
|
+
|
|
5944
6164
|
### Upload
|
|
5945
6165
|
|
|
5946
6166
|
```text
|
|
@@ -5957,6 +6177,129 @@ stored file); a remote upload adds `server`, `instance` and `stderr?`. Errors:
|
|
|
5957
6177
|
sha256 mismatch; the remote file is left), `E_SESSION_UNKNOWN`,
|
|
5958
6178
|
`E_REMOTE_INCOMPATIBLE`.
|
|
5959
6179
|
|
|
6180
|
+
### How the clients run the sweep
|
|
6181
|
+
|
|
6182
|
+
The kernel's machine sweep, `oats session resume --json`
|
|
6183
|
+
([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)), is
|
|
6184
|
+
run by a client when it opens and again when its rosters show a lost session
|
|
6185
|
+
([When Desktop opens](desktop-instance-start.md#when-desktop-opens)). The
|
|
6186
|
+
clients share one trigger, one runner and one reader, so the Desktop and the
|
|
6187
|
+
TUI decide, run and read it the same way.
|
|
6188
|
+
|
|
6189
|
+
**The trigger**, `createResumeTrigger({ cli, run, read, now, onReading })`
|
|
6190
|
+
(`packages/client/session-resume-trigger.mjs`), holds the rule:
|
|
6191
|
+
|
|
6192
|
+
- `launch()` arms it and runs the launch sweep, with no floor. A client calls
|
|
6193
|
+
it once, after anything the sweep reads is in place (the Desktop: after the
|
|
6194
|
+
startup deployments-list step). `observed()` does nothing before it.
|
|
6195
|
+
- `observed(rows, { localDeploymentIds })` is given each roster's instance
|
|
6196
|
+
rows as the client reads them, with the ids of that read's local
|
|
6197
|
+
deployments (the Desktop: `instances` of each accepted `/api/panel` reply,
|
|
6198
|
+
and `localDeploymentIds(reply)`, its `deployments[]` entries with
|
|
6199
|
+
`local: true`). It starts a sweep only when none is in flight, at least
|
|
6200
|
+
`RESUME_MIN_INTERVAL_MS` (30 s) has passed since the last sweep that ran
|
|
6201
|
+
started, and `lostLocalHomes(rows, localDeploymentIds)` names a home that
|
|
6202
|
+
is not settled. Locality is the roster's, by deployment id: a row is local
|
|
6203
|
+
only when its `deployment.id` (the panel's tag) is one of the local ids. A
|
|
6204
|
+
remote deployment's row, a row with no tag, and every row when no ids are
|
|
6205
|
+
given are not local; a client never acts on another host's loss.
|
|
6206
|
+
`lostLocalHomes` keeps a local row's absolute `home` when its `sessionEnd`
|
|
6207
|
+
says the session was lost and it is not running; it is the one place that
|
|
6208
|
+
reads `sessionEnd`'s meaning. There is no timer and no queue.
|
|
6209
|
+
- After a sweep that a status read started completes (quiet or a notice),
|
|
6210
|
+
every instance it was started for waits until it changes: it runs, or it is
|
|
6211
|
+
no longer lost. A busy, failed or unsupported sweep, or a plan, settles
|
|
6212
|
+
nothing. A home a read releases while the sweep runs is settled by neither
|
|
6213
|
+
the snapshot nor the answer: that read is newer. A home
|
|
6214
|
+
is also settled when a sweep could not resume it, found it was not lost, or
|
|
6215
|
+
skipped it because the kernel had not seen it running recently. A sweep
|
|
6216
|
+
that resumed it, started it fresh, left it waiting for you or found it
|
|
6217
|
+
running unsettles it, and so does a later roster row that is running or not
|
|
6218
|
+
lost. So a home that cannot be resumed costs at most one sweep after the
|
|
6219
|
+
launch's. Which rows mean which is read in `session-resume.mjs` alone
|
|
6220
|
+
(`sweepSettlement`, `sweepCompleted`).
|
|
6221
|
+
- `cli()` gives the accepted probe or null, or a promise of either, and is
|
|
6222
|
+
asked at each would-be start: the sweep runs only when `resumeSupported`
|
|
6223
|
+
holds. When it does not, nothing runs and the floor does not move.
|
|
6224
|
+
- Before reading an answer, it drops each `refused` row whose
|
|
6225
|
+
`(home, reason, code)` an earlier sweep of this trigger already reported,
|
|
6226
|
+
so a standing refusal is reported once. A home released (above) forgets its
|
|
6227
|
+
reported refusals: refused again after it recovered, it is news. Every other
|
|
6228
|
+
row is kept. The same goes for the result's own `warnings` (about the host):
|
|
6229
|
+
one a notice of this trigger showed is left out of later answers by its
|
|
6230
|
+
exact string, for the whole run; one only a quiet sweep carried stays news.
|
|
6231
|
+
- `onReading(reading)` is called for every finished sweep, whatever the
|
|
6232
|
+
reading. `launch()` and `observed()` never throw or reject; a `run` that
|
|
6233
|
+
rejects reads as `failed`, `E_CLI_FAILED`. `dispose()` drops later readings
|
|
6234
|
+
and cancels nothing: a sweep in flight runs to its end.
|
|
6235
|
+
|
|
6236
|
+
The Desktop's main process queues each `notice` reading's summary (at most
|
|
6237
|
+
10, the oldest dropped first) and tells every live window
|
|
6238
|
+
(`session-resume:ready`). A window takes the whole queue
|
|
6239
|
+
(`session-resume:take`, behind the trusted-frame guard) and posts each summary
|
|
6240
|
+
as its own notice.
|
|
6241
|
+
|
|
6242
|
+
**The runner**, `runResumeSweep` (`packages/client/session-resume-cli.mjs`):
|
|
6243
|
+
|
|
6244
|
+
- It runs only when the probe is accepted, its `bin` is absolute and its
|
|
6245
|
+
`features` list `session-resume` (`resumeSupported`). Otherwise it runs
|
|
6246
|
+
nothing and answers `E_CLI_UNAVAILABLE` or `E_RESUME_FEATURE`. Nothing falls
|
|
6247
|
+
back.
|
|
6248
|
+
- The argv is exactly `session resume --json`, with no `--deployment`, no
|
|
6249
|
+
`--plan` and no `--server`. The working directory is `/`, so the kernel
|
|
6250
|
+
resolves no deployment from the client's own. The environment is the
|
|
6251
|
+
client's, without what Desktop's packaging adds (`cliEnvironment`) and without
|
|
6252
|
+
the instance variables (`withoutInstanceVariables`,
|
|
6253
|
+
`packages/client/kernel-environment.mjs`): a client started inside an
|
|
6254
|
+
instance's pane must not scope the sweep to that instance. `OATS_HOME_DIR`
|
|
6255
|
+
passes through.
|
|
6256
|
+
- It sets no deadline. The sweep runs in a process session of its own, and its
|
|
6257
|
+
stdout and stderr are files, not pipes: `execFileToFiles`
|
|
6258
|
+
(`packages/client/file-output-exec.mjs`) unlinks them right after the spawn
|
|
6259
|
+
and reads them back from its own descriptors. Neither the client's exit nor
|
|
6260
|
+
a signal to it reaches the sweep, and nothing is left on disk. A caller that
|
|
6261
|
+
passes its own exec must keep those three properties: detached, file-backed,
|
|
6262
|
+
and never signalling the child.
|
|
6263
|
+
- It answers the kernel's envelope: the result at exit 0, and an `ok:false`
|
|
6264
|
+
envelope whatever the exit (`E_RESUME_BUSY` exits 1). Otherwise it answers
|
|
6265
|
+
a code of its own, with no message: `E_CLI_OUTPUT_LIMIT` (more than 4 MiB),
|
|
6266
|
+
`E_CLI_PROTOCOL` (no envelope), `E_CLI_FAILED` (a nonzero exit without an
|
|
6267
|
+
`ok:false` envelope, or an exec that throws). No stderr and no exception text
|
|
6268
|
+
reaches the answer.
|
|
6269
|
+
|
|
6270
|
+
**The reader**, `readResumeSweep` (`packages/client/session-resume.mjs`),
|
|
6271
|
+
gives one of five readings: `unsupported` (nothing ran), `busy`
|
|
6272
|
+
(`E_RESUME_BUSY`), `failed` with a code, `quiet`, or `notice` with a summary.
|
|
6273
|
+
A plan answer (`plan: true`) is quiet.
|
|
6274
|
+
|
|
6275
|
+
- The summary is facts: per row its instance, its deployment and its outcome's
|
|
6276
|
+
reason, never a word of the kernel's text. `already-running` and `skipped`
|
|
6277
|
+
rows are counted nowhere. A notice exists only when a row is `resumed`,
|
|
6278
|
+
`fresh`, `blocked` or `refused`. Unchecked deployments are lines inside such
|
|
6279
|
+
a notice, never a notice on their own; a deployment the kernel reports as
|
|
6280
|
+
`opted-out` (an older kernel) reads as unchecked, with no reason.
|
|
6281
|
+
- It is tolerant. A row without a string `instance` and `deployment`, with an
|
|
6282
|
+
unknown `outcome`, or whose name the display filter withholds or empties, is
|
|
6283
|
+
dropped. An unknown `reason` under a known outcome is read as no reason and
|
|
6284
|
+
worded generically. A refusal's `code` is kept only when it matches
|
|
6285
|
+
`^E_[A-Z0-9_]{1,64}$`.
|
|
6286
|
+
- The result's own `warnings`, about the host and not one home, are the
|
|
6287
|
+
summary's `host` (`{warnings, omitted}`, always present), kept and cut as a
|
|
6288
|
+
row's are (below). They never make a notice alone; a notice shows them after
|
|
6289
|
+
the unchecked deployments, under "OATS says about this computer:".
|
|
6290
|
+
- A row's `warnings` are kept whole and in order, each as one display line
|
|
6291
|
+
(`displayLine`), and cut by position only, at the bounds of
|
|
6292
|
+
`launchFlagIgnored` (16 lines, 4096 UTF-16 units; `boundedWarnings`,
|
|
6293
|
+
`packages/client/launch-prompt-outcome.mjs`). No warning is picked, matched
|
|
6294
|
+
or dropped by its words.
|
|
6295
|
+
- A refused row's `message` is the kernel's prose. It is shown only after
|
|
6296
|
+
"OATS says:", attributed, through the display filter, and never matched.
|
|
6297
|
+
- The summary keeps at most 100 rows, in the answer's order, and counts the
|
|
6298
|
+
rest. The headline counts the real totals. `resumeSummaryFact` is the
|
|
6299
|
+
summary's decoder at a boundary (the Desktop's main process hands it to a
|
|
6300
|
+
window over IPC), and `resumeNotice` writes the headline and the Details in
|
|
6301
|
+
the clients' own words.
|
|
6302
|
+
|
|
5960
6303
|
### Launch configurations
|
|
5961
6304
|
|
|
5962
6305
|
```text
|
|
@@ -43,9 +43,12 @@ entry, or falls back to the recorded launch when it is no longer offered.
|
|
|
43
43
|
|
|
44
44
|
Enter a model or leave the field blank to use the selected launch's default.
|
|
45
45
|
An old harness's model is not carried to a different harness. Available local model
|
|
46
|
-
suggestions are advisory; a model ID can also be typed. Start
|
|
47
|
-
|
|
48
|
-
|
|
46
|
+
suggestions are advisory; a model ID can also be typed. Start opens a fresh
|
|
47
|
+
harness conversation on the saved briefing and state. The one exception is a
|
|
48
|
+
resume after a shutdown, a reboot or a crash, which continues the instance's
|
|
49
|
+
own last conversation ([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown));
|
|
50
|
+
it replaces the earlier rule that no start resumes a conversation (OATS 0.69).
|
|
51
|
+
A Start or Restart from this dialog is never a resume. Once the kernel accepts the start or restart, the
|
|
49
52
|
dialog closes and Desktop opens the instance's terminal as soon as its row is
|
|
50
53
|
running with a terminal session, so whatever the harness shows first (a
|
|
51
54
|
confirmation such as Claude Code's development-channels prompt, an error, the
|
|
@@ -238,3 +241,85 @@ child remains running; a fallback shell or dead pane is stopped. Errors that
|
|
|
238
241
|
prevent a reliable observation remain unknown. A row that records a Herdr
|
|
239
242
|
target (Herdr was removed in 0.31.0) is never observed: it shows the kernel's
|
|
240
243
|
`E_HERDR_REMOVED` text, and Open and Start are disabled.
|
|
244
|
+
|
|
245
|
+
## When Desktop opens
|
|
246
|
+
|
|
247
|
+
After a shutdown, a reboot or a crash, the instances that were running have
|
|
248
|
+
lost their sessions. OATS Desktop asks the kernel to resume them: it runs
|
|
249
|
+
`oats session resume --json`
|
|
250
|
+
([Resume after a shutdown](execution-targets.md#resume-after-a-shutdown)), and
|
|
251
|
+
the kernel does the rest. The kernel looks
|
|
252
|
+
at every deployment on this computer's list (local deployments only, never a
|
|
253
|
+
server's) and resumes each lost session as it decides. What the kernel does to
|
|
254
|
+
a session, when it starts one fresh from its briefing instead, and when it
|
|
255
|
+
stops trying for one that keeps losing its session, is the kernel's rule,
|
|
256
|
+
written beside the command. A session lost long ago is not resumed
|
|
257
|
+
automatically, and Desktop says nothing about it; `oats session start
|
|
258
|
+
--resume` still brings it back by hand. Desktop owns no session: it runs the
|
|
259
|
+
command, waits for the answer and shows a summary. There is no switch to turn
|
|
260
|
+
it off.
|
|
261
|
+
|
|
262
|
+
**When it runs.** Once when Desktop opens, after Desktop has imported its
|
|
263
|
+
saved workspaces into this computer's deployments list, because the sweep
|
|
264
|
+
reads that list. After that, whenever Desktop reads a roster that shows an
|
|
265
|
+
instance of a local deployment, as the roster names its deployments, whose
|
|
266
|
+
session was lost and that is not running, and only then:
|
|
267
|
+
|
|
268
|
+
- at most one sweep at a time, and at least 30 seconds after the last one
|
|
269
|
+
started (the one at launch counts);
|
|
270
|
+
- after a sweep that a status read started, every instance it was started
|
|
271
|
+
for waits until it changes (it runs, or it is no longer lost); so does an
|
|
272
|
+
instance any sweep could not resume, found was not lost, or left because it
|
|
273
|
+
was lost long ago. Such an instance does not set off another sweep until a
|
|
274
|
+
later roster shows it running or no longer lost, or a sweep resumes it;
|
|
275
|
+
- never for another machine's instances.
|
|
276
|
+
|
|
277
|
+
There is no timer and no queue: a read that comes too soon starts nothing,
|
|
278
|
+
and the next read asks again. A new window, a workspace switch, a restarted
|
|
279
|
+
backend or Desktop coming to the front start nothing on their own. The rule
|
|
280
|
+
is shared with the TUI (`packages/client/session-resume-trigger.mjs`), and
|
|
281
|
+
the kernel's machine lock and its record of this boot make running it from
|
|
282
|
+
several clients safe. It runs only when the installed OATS CLI advertises the
|
|
283
|
+
`session-resume` feature. Without it, nothing runs and nothing is said.
|
|
284
|
+
|
|
285
|
+
**The notice.** When a sweep resumed an instance, started one fresh, left one
|
|
286
|
+
waiting for you or could not resume one, one window shows a notice that stays
|
|
287
|
+
until you dismiss it. Switching that window's workspace does not take it away.
|
|
288
|
+
The headline counts them ("OATS resumed 3 instances whose sessions were lost.
|
|
289
|
+
1 of them is waiting for you: open its terminal."). Its Details list each
|
|
290
|
+
instance, in this order: those waiting for you (at a launch prompt, or to
|
|
291
|
+
choose how to resume it: open its terminal), those that could not be resumed,
|
|
292
|
+
those that started fresh and why, then those resumed in their own
|
|
293
|
+
conversation. An instance that keeps losing its session is listed with those
|
|
294
|
+
that could not be resumed: the kernel stops resuming it, and it stays down
|
|
295
|
+
until you start it yourself. The deployments the sweep did not check are
|
|
296
|
+
listed after them. Text from OATS appears only after "OATS says:", as a quote.
|
|
297
|
+
The Details show at most 100 instances, then say how many more there are.
|
|
298
|
+
|
|
299
|
+
Each sweep with something to report gives a notice of its own. An instance
|
|
300
|
+
that could not be resumed is reported once: a later sweep that finds it the
|
|
301
|
+
same way leaves it out, and says nothing if that was all it found. Once it has
|
|
302
|
+
been resumed, or shown running or no longer lost, a later refusal is reported
|
|
303
|
+
again. More than three notices fold into one entry, "N notices about resumed
|
|
304
|
+
sessions". Desktop keeps the last 10 notices no window has shown yet, so a
|
|
305
|
+
window that opens after a sweep has finished still gets them, and only one
|
|
306
|
+
window ever shows each. Closing that window loses it.
|
|
307
|
+
|
|
308
|
+
OATS can also warn about this computer rather than one instance (how the
|
|
309
|
+
sessions it resumes are run on this machine, say). Such a warning is shown
|
|
310
|
+
once each time Desktop runs, in the next notice, after the deployments, under
|
|
311
|
+
"OATS says about this computer:". A warning alone never makes a notice.
|
|
312
|
+
|
|
313
|
+
There is no notice when nothing was lost, when the sessions were already
|
|
314
|
+
running, when another sweep holds the machine (another Desktop, the TUI, or
|
|
315
|
+
`oats session resume` run by hand), or when the only thing to report is a
|
|
316
|
+
deployment that was not checked. A sweep that fails writes one line with its
|
|
317
|
+
code to Desktop's log, and shows nothing.
|
|
318
|
+
|
|
319
|
+
**Quitting does not stop a sweep.** The sweep runs in a process session of its
|
|
320
|
+
own, and writes its answer to files rather than to Desktop. Quitting Desktop,
|
|
321
|
+
or Desktop crashing, while it runs leaves it to finish. Its answer is then
|
|
322
|
+
not shown.
|
|
323
|
+
|
|
324
|
+
How the clients run the command and read its answer is in
|
|
325
|
+
[desktop-cli-api.md](desktop-cli-api.md#how-the-clients-run-the-sweep).
|