@awebai/oats 0.69.18 → 0.69.19

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.
@@ -1188,7 +1188,7 @@ own configuration.
1188
1188
  naming the release, not with a schema error.
1189
1189
  3. The blast radius is every soul that composes the capability, on every host
1190
1190
  below the release: one capability can stop every developer soul of a
1191
- workspace from spawning, as in lfx-oats-workspace#22, where one capability
1191
+ workspace from spawning, as in lab-oats-workspace#22, where one capability
1192
1192
  took down every developer soul.
1193
1193
  4. To limit it, put the hook in a small capability composed only by the souls
1194
1194
  that need the setup.
package/docs/container.md CHANGED
@@ -250,47 +250,50 @@ aw workspace connect --service <the team's aweb server>
250
250
  The commands are as `aw` 1.36.57 documents them in its own `--help`. The
251
251
  sequences have not yet been run in a container.
252
252
 
253
- Before it copies anything, the spawn checks three things and refuses the
254
- seat when one is missing:
253
+ Before it copies or locks anything, the spawn checks five things, and
254
+ refuses the seat with its fix when one is missing:
255
255
 
256
256
  - `signing.key`, the member's key;
257
257
  - the server: `aweb_url` in `workspace.yaml` (`aw workspace connect` writes
258
- it);
258
+ it). The seat's service comes only from there: `OATS_AWEB_URL` is not read;
259
259
  - the team: the deployment's default team, or else the active team in
260
- `teams.yaml`.
260
+ `teams.yaml`;
261
+ - `teams.yaml` itself;
262
+ - a membership of that team in `teams.yaml`, matched as aw matches it. When
263
+ there is none, accept the team's invite (`aw id team accept-invite`) or
264
+ fetch its certificate (`aw id team fetch-cert`) in the seat's directory, or
265
+ make the seat's team the deployment's default.
261
266
 
262
- The member's certificate under `team-certs/` is not checked at that point,
263
- and the seat does not work without it: the spawn copies the seat, fails when
264
- it connects or reads the identity back, and removes the copy.
267
+ The member's certificate file under `team-certs/` is not checked at that
268
+ point, and the seat does not work without it: the spawn copies the seat,
269
+ fails when it connects or reads the identity back, and removes the copy.
265
270
 
266
271
  One seat serves one instance at a time. The spawn writes
267
272
  `.aw-retained-seat.json` beside the seat's `.aw` and refuses a second spawn
268
273
  while the first instance's home exists; retiring that instance releases the
269
- seat. Two cases need the operator:
274
+ seat. Every change of that lock is one guarded step, using two private files
275
+ beside it, `.aw-retained-seat.json.guard` and `.aw-retained-seat.json.held`.
276
+ A change that was killed can leave one of them behind. The next spawn or
277
+ take-over then refuses, naming the file and its fix, and the next retire
278
+ reports it. Nothing removes such a file automatically. Two cases need the
279
+ operator:
270
280
 
271
281
  - **The holder's home exists and its runtime is known to be dead.** Spawn
272
282
  with `identity.takeOver=true`. If that runtime is in fact alive, there are
273
283
  then two seats with one key; stop the old one.
274
- - **The holder's home is gone without a retire** (a home removed by hand, a
275
- volume restored). Every later spawn is still refused, as "taken by another
276
- spawn a moment ago", and `identity.takeOver` does not apply. Remove
277
- `.aw-retained-seat.json` by hand once the home is confirmed gone
278
- ([awebai/oats-aweb#227](https://github.com/awebai/oats-aweb/issues/227)).
284
+ - **The holder's home is not on this host** (a home removed by hand, a volume
285
+ restored, or a home on another host that shares the seat). The spawn
286
+ refuses, naming the holder as the lock records it (instance, host, since
287
+ and home) and the release. A lock is never released by age. Once that seat
288
+ is confirmed gone, spawn with `identity.takeOver=true`, which clears the lock
289
+ with a warning, or remove the lock file the refusal names.
279
290
 
280
291
  Retiring never revokes the member's certificate: on a server that is not the
281
292
  hosted service, whoever holds the controller key removes a member
282
- (`aw id team remove-member`).
283
-
284
- Known limits of this route, until their fixes are released:
285
-
286
- - **A restart can lose the seat's identity.** A seat made this way may not
287
- get `AWEB_IDENTITY_HOME` at a restart
288
- ([awebai/oats-aweb#226](https://github.com/awebai/oats-aweb/issues/226)).
289
- Check `aw whoami` in the home after a restart; if it is not the seat, retire
290
- the instance and spawn it again.
291
- - **Do not interrupt a seat's spawn.** A spawn killed after it connected can
292
- delete the standing identity's workspace at the server
293
- ([awebai/oats-aweb#228](https://github.com/awebai/oats-aweb/issues/228)).
293
+ (`aw id team remove-member`). A seat's spawn that fails or is killed never
294
+ deletes the standing identity's workspace at the server: its retire releases
295
+ the lock and prints the `aw workspace connect` that binds the identity back to
296
+ its seat.
294
297
 
295
298
  The pinned OATS release supports this file-backed launch configuration:
296
299
 
@@ -492,3 +495,173 @@ fixtures. The SSH guard requires flat
492
495
  `Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
493
496
  equals-delimited keywords and quoted keywords. Follow the repository's
494
497
  local check limits; full suites run in CI.
498
+
499
+ ## Image CI and publication
500
+
501
+ [Team image](../.github/workflows/team-image.yml) builds `container/agent`
502
+ from the pull request's exact head commit, on an Ubuntu 24.04 amd64 runner.
503
+ It also supports a manual verification run at the selected ref. Actions are
504
+ pinned by commit, and the verification token has only `contents: read`.
505
+ After acceptance, verification also runs the real Docker export, Skopeo
506
+ compression and configuration-digest checks used before publication, without
507
+ a registry credential or any registry/release write.
508
+
509
+ Manual verification offers two additional proofs:
510
+
511
+ - `default_payload_proof` builds the registry context a second time without
512
+ the additive BuildKit mount and compares the full installed `/opt/agent`
513
+ payload: file paths, sizes, content hashes, modes, directories and link
514
+ targets. Image history and IDs may differ; payload differences fail.
515
+ - `packed_kernel` prepares a private context from the selected commit and
516
+ runs the image with that commit's own `npm pack` kernel. This job is
517
+ manual-only until the image owner's compatible final baseline lands.
518
+ Ordinary PR verification keeps the committed context in the meantime.
519
+ An incompatible baseline fails explicitly, with no registry-kernel fallback
520
+ and no wider lock allowance. The committed baseline needs final OATS
521
+ 0.69.18+ and aw 1.36.59+ with the compatible exact runtime closure.
522
+ With the committed baseline, the packed job refuses; its positive real
523
+ packed-image acceptance is **NOT RUN** until that compatible baseline lands.
524
+
525
+ Packing disables lifecycle scripts and uses a private npm home/cache, empty
526
+ user/global configs and an explicit public registry. Every packed file must
527
+ be in the kernel's literal `package.json.files` list, including the explicitly
528
+ declared manifest and license. The tarball is checked against its SHA512
529
+ integrity and the exact checkout's regular Git files, sizes, bytes and modes;
530
+ links, unsafe paths and untracked/generated payloads refuse. The source
531
+ checkout stays unchanged.
532
+
533
+ Only the private image manifest changes to the fixed
534
+ `file:../oats-build-inputs/oats-pr-kernel.tgz` dependency. The same tarball is
535
+ provided in the closed context and a private host-side sibling directory,
536
+ so npm lock generation and the build resolve the same bytes. The existing
537
+ `npm ci --ignore-scripts` RUN gets a read-only context mount at
538
+ `/opt/oats-build-inputs`; no tarball COPY, build argument, new lifecycle
539
+ execution or runtime mount is added. The registry release context and its
540
+ strict metadata checks keep their own path. Both adapters protect every
541
+ unrelated CLI and lock entry, addition, removal and root/metadata field.
542
+
543
+ After the unmodified acceptance, the packed job checks the installed kernel's
544
+ exact own-file set, sizes, modes and hashes against the HEAD inventory in
545
+ the same accepted container. Version equality alone is insufficient: two
546
+ commits may share a version. Separately resolved nested dependencies remain
547
+ governed by the image lock. A changed inventory artifact or installed file
548
+ fails before digest preparation. The closed context, tarball, generated
549
+ manifest/lock, source inventory and build metadata are retained as artifacts;
550
+ npm config/cache are outside the uploaded context. Source SHA and
551
+ integrity/inventory/lock hashes are retained in those artifacts. Acceptance
552
+ reports the image ID in its log and passes it between workflow steps to bind
553
+ the export to the accepted image. These checks do not broaden the receipt's
554
+ supervisor, agent or containment claims.
555
+
556
+ The shared fixture, `.github/scripts/team-image-accept.sh`, starts the
557
+ committed Compose service on a disposable internal bridge with IPv6 off and
558
+ an isolated gateway (Docker Engine 28+). It provisions private state, a
559
+ throwaway SSH public key, a resolver file and an empty root:20001 0750 login
560
+ directory, waits for the service's SSH healthcheck, then runs the image's
561
+ unmodified `accept.sh --evidence target-amd64`. Cleanup removes the service,
562
+ network and fixture paths on success or failure. This is image acceptance;
563
+ it provisions no seat or inference token. The script's `NOT RUN` items
564
+ remain outside this check.
565
+
566
+ The `publish-team-image` job in
567
+ [Release](../.github/workflows/release.yml) waits for the existing `publish`
568
+ job, so npm publication and the GitHub Release precede the image. Its
569
+ single job-level `if: ${{ false }}` keeps publication disabled pending the
570
+ registry decision for the proposed `ghcr.io/oats-project/team-agent` target.
571
+ GHCR creates a new package as private by default. Verification remains
572
+ enabled. Enabling publication requires the registry decision and a reviewed
573
+ change to the switch.
574
+
575
+ Before enabling, the registry owner must complete these separately authorized
576
+ setup steps and include their evidence as a checklist in the enabling PR:
577
+
578
+ 1. Push the approved digest from a verified run.
579
+ 2. Set the package visibility to public.
580
+ 3. Grant this repository's Actions write access.
581
+ 4. Record the pinned-client observation that an unused exact version tag
582
+ returns `manifest unknown`.
583
+
584
+ Package creation is this manual setup step, never an automatic release-job
585
+ bootstrap. The job treats only `manifest unknown` as an absent tag. It refuses
586
+ `name unknown`, `denied`, authentication and transport errors. The registry
587
+ owner resolves bootstrap and access problems without broadening the matcher.
588
+
589
+ Publication requires a stable `vX.Y.Z` release tag (at least 0.69.18).
590
+ The release job copies only the tagged image's literal `.dockerignore`
591
+ allowlist into a private build context, sets its OATS dependency to exactly
592
+ `X.Y.Z`, and regenerates that copy's lock with npm scripts disabled and the
593
+ public registry selected explicitly. The source checkout and Dockerfile
594
+ stay unchanged. The committed aw pin must be a final version of at least
595
+ 1.36.59 and match its lock; prereleases cannot pass the guard.
596
+
597
+ The generated lock may change only the OATS entry, its root dependency
598
+ specification and its own exact runtime dependencies. Other entries,
599
+ including aw, Claude and unrelated transitive packages, must remain equal
600
+ to the committed lock, including additions and removals. Registry version,
601
+ tarball URL and SHA512 integrity must match the new kernel and its exact
602
+ dependencies. A missing compatible committed baseline fails the build;
603
+ it does not widen the allowance. The image owner maintains that baseline.
604
+ The effective manifest, generated lock and source/version/integrity metadata
605
+ are retained as a run artifact. Lock regeneration is audited rather than
606
+ claimed to reproduce the entire image across retries.
607
+
608
+ After building the private context, the release job runs the existing real
609
+ acceptance and separately executes `oats version --json` in that same
610
+ container. The installed kernel must equal `X.Y.Z` before registry login.
611
+ The fixture records the accepted container's image ID. Export must inspect
612
+ that same ID, then use `docker save` on the immutable ID. Skopeo reads the
613
+ archive and compresses layers into a private directory, preserving its
614
+ Docker v2s2 manifest type. Docker's CLI negotiates the Engine API; Skopeo
615
+ uses no daemon connection. The release lane installs and verifies the
616
+ reviewed Ubuntu Skopeo package version `1.13.3+ds1-2ubuntu0.24.04.3`, whose
617
+ error text it parses; changing that input requires another review and real
618
+ preparation run. PR verification installs the available archive package
619
+ without an exact apt pin and records its version in the step summary.
620
+
621
+ Keeping the manifest type avoids rewriting configuration bytes. The
622
+ prepared configuration digest must equal the hash of the archive's raw
623
+ configuration, binding the manifest and root filesystem to the accepted
624
+ image. This binding uses archive bytes rather than assuming Docker's image
625
+ ID is a configuration digest. The classic store has real runner evidence;
626
+ the containerd store branch has fixture coverage and still needs a real run.
627
+ Skopeo [copies with preserved digests](https://github.com/containers/skopeo/blob/main/docs/skopeo-copy.1.md)
628
+ to `repository@sha256:...`.
629
+
630
+ The same manifest also gets the exact release retention tag `X.Y.Z`, with
631
+ no leading `v`, `latest`, major or minor aliases. Before any registry write,
632
+ a different digest at that tag is refused; a same-digest retry is idempotent.
633
+ Only an explicit manifest-not-found result permits creation. Authentication,
634
+ transport and other lookup errors fail closed. After copying the digest,
635
+ the job copies the same manifest to the absent version tag and verifies its
636
+ resolved digest. The release workflow serializes its own writes; this
637
+ preflight is not a registry compare-and-swap against independent writers.
638
+ Deployments, chart values, deploy/team and release receipts continue to use
639
+ the digest reference. The version tag is for retention and human inspection.
640
+
641
+ After the version tag is written, a failed final verification or receipt edit
642
+ requires manual recovery of that published digest: verify the existing tag
643
+ against the original run's retained build inputs and acceptance evidence, then
644
+ restore its owned receipt block. Use the original digest output/summary when
645
+ available; a failed final inspect may precede that output. A workflow rerun
646
+ rebuilds and can yield a different digest that correctly refuses. Never retag
647
+ to make the rerun pass.
648
+
649
+ The digest is a job output and appears in the run summary. An owned block
650
+ in the existing GitHub Release notes records the immutable image reference,
651
+ source tag and commit, installed kernel, generated lock hash and npm kernel
652
+ integrity. A retry replaces only that image's block, preserving other prose.
653
+ The receipt's PASS list covers image build, non-root user, read-only root,
654
+ sshd startup and image/configuration digest binding. Supervisor startup,
655
+ admitted-seat spawn, wake delivery, package sync, inference, mail/chat,
656
+ viewer, governance, platform containment and network/egress-bypass checks
657
+ remain **NOT RUN**. Version and lock checks do not prove supervisor startup
658
+ or agent readiness; those claims need direct acceptance coverage.
659
+
660
+ Only that job has `packages: write`; `contents: write` lets it replace its
661
+ owned receipt block. Among run-step environments, only the publish step
662
+ receives `GITHUB_TOKEN`. The SHA-pinned first-party checkout and setup-node
663
+ actions use their default action token inputs; checkout does not persist
664
+ credentials. The publish step stores
665
+ registry authentication in a private temporary file and removes it on exit.
666
+ It receives no npm publish credential. To roll back a deployed image, select
667
+ the previous reviewed digest in the deployment configuration.
@@ -25,8 +25,8 @@ Local `oats-local.yaml` (the deployment's per-machine file, never committed):
25
25
 
26
26
  ```yaml
27
27
  teams:
28
- antares-oats: { team: antares-oats:ana.aweb.ai } # a local (personal) team: label → provider id
29
- defaultTeam: antares-oats
28
+ builder-oats: { team: builder-oats:ana.aweb.ai } # a local (personal) team: label → provider id
29
+ defaultTeam: builder-oats
30
30
  souls:
31
31
  disabled: [...]
32
32
  teams: # the extra teams each soul's instances MAY join here
@@ -35,4 +35,4 @@ Hosts that ran workspace automations before 0.30 must add their `trust` lines. T
35
35
  notes say so. No host of ours runs one today, so there's nothing to migrate.
36
36
 
37
37
  ## Unblocks
38
- The okf review trigger on Juan's host: it runs once his host trusts it.
38
+ The okf review trigger on an operator's host: it runs once that host trusts it.
@@ -2166,7 +2166,7 @@ The messaging provider's `teams` operation (`messaging:teams`) is produced by
2166
2166
  the provider (oats.aweb 1.17 or later), not the kernel:
2167
2167
 
2168
2168
  ```json
2169
- {"defaultTeam":{"label":"antares","team":"antares:ana.aweb.ai","from":"deployment"},
2169
+ {"defaultTeam":{"label":"builder","team":"builder:ana.aweb.ai","from":"deployment"},
2170
2170
  "eligible":[{"label":"oats","team":"oats:oats.aweb.ai","joined":true}],
2171
2171
  "joined":[{"label":"oats","team":"oats:oats.aweb.ai","identityHome":"/w/agents/oe/instances/oe-1/.aw-teams/oats","receive":"live","since":"2026-09-28T09:00:00.000Z"}],
2172
2172
  "left":[{"label":"reviewers","team":"reviewers:acme.aweb.ai","at":"2026-09-28T09:30:00.000Z","reason":"no-longer-eligible"}],
@@ -4177,9 +4177,9 @@ whose key is not known; an unparsable ref is `E_REPO_REF`.
4177
4177
 
4178
4178
  ```json
4179
4179
  {"file":"/Users/me/.oats/servers.json",
4180
- "servers":[{"id":"altair-aweb","sshHost":"altair","operatorSshHost":"altair-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
4181
- "workspaceKey":"github.com/awebai/ac",
4182
- "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
4180
+ "servers":[{"id":"devbox-aweb","sshHost":"devbox","operatorSshHost":"devbox-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"devbox",
4181
+ "workspaceKey":"github.com/example/app",
4182
+ "target":{"sshHost":"devbox","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
4183
4183
  "unknownWorkspace":["build"]}
4184
4184
  ```
4185
4185
 
@@ -4205,18 +4205,18 @@ An envelope, `ok: true` whenever no step failed, human steps included
4205
4205
  ([servers.md](servers.md#connect-a-machine) has what each step does):
4206
4206
 
4207
4207
  ```json
4208
- {"id":"altair-aweb","ready":false,
4208
+ {"id":"devbox-aweb","ready":false,
4209
4209
  "registration":null,
4210
4210
  "steps":[{"step":"ssh","status":"ok"},
4211
4211
  {"step":"oats","status":"done","detail":"installed @awebai/oats 0.39.0 (was missing)"},
4212
4212
  {"step":"git","status":"needs-human","code":"E_REMOTE_UNREADABLE",
4213
- "detail":"cannot read remote https://github.com/awebai/ac (auth): on macOS a session without a terminal …",
4214
- "remedy":"on altair: on macOS a session without a terminal … (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: …",
4213
+ "detail":"cannot read remote https://github.com/example/app (auth): on macOS a session without a terminal …",
4214
+ "remedy":"on devbox: on macOS a session without a terminal … (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: …",
4215
4215
  "hint":"keychain-non-interactive"},
4216
4216
  {"step":"deployment","status":"skipped","detail":"waits for git"},
4217
4217
  {"step":"register","status":"skipped","detail":"waits for git"},
4218
4218
  {"step":"readiness","status":"skipped","detail":"waits for git"}],
4219
- "human":["on altair: on macOS a session without a terminal … or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)"]}
4219
+ "human":["on devbox: on macOS a session without a terminal … or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)"]}
4220
4220
  ```
4221
4221
 
4222
4222
  - `steps` is always the six steps `ssh`, `oats`, `git`, `deployment`,
@@ -7175,7 +7175,7 @@ whatever the rows say:
7175
7175
  | `already-running` | none |
7176
7176
  | `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`, or any refusal of a home that is gone: it stopped, started or was removed between the read and the start), `lifecycle-busy` (OATS 0.69.2: OATS is stopping, upgrading or retiring the home, or its retire is owed; read from its row, with a `message`, or answered by its start, with the start's `code`, `E_INSTANCE_RETIRING` or `E_LIFECYCLE_BUSY`, and `message`; nothing started) |
7177
7177
  | `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) |
7178
- | `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) |
7178
+ | `refused` | `start-refused` (`code` and `message`: the start's own refusal, and `nextAttemptAt`: a refused start launched nothing, so it does not answer the loss, and a sweep tries it again no sooner than that time), `start-refused-retrying` (an earlier sweep in this boot was refused for this home and start and its delay has not run: reported again with that `code`, `message` and `nextAttemptAt`, nothing started; the delay is 1 minute after the first refusal and doubles at each further one, up to 15 minutes, and the retries end when the loss is `not-seen-recently`), `keeps-getting-lost` (sweeps started this home 3 times in the last hour and it was lost again each time: nothing started, no `code`, a `message` that says so and `nextAttemptAt`, when the oldest of those starts is an hour old and a sweep starts the home again; a home that used up its starts 3 hours in a row is given up: the row has no `nextAttemptAt`, its `message` says a person starts it, and the loss is answered) |
7179
7179
 
7180
7180
  The kernel defines every `sessionEnd`, `resume` and row name in one
7181
7181
  module, `lib/session-resume-contract.mjs`; a change to one is a contract
@@ -7188,11 +7188,15 @@ whatever the rows say:
7188
7188
  runs in the OATS tmux server's cgroup, not a scope of its own, and why).
7189
7189
  Each start still records it in its own home's events. `--plan` has none.
7190
7190
  - A lost home is answered with the first that applies: `lifecycle-busy`,
7191
- `not-seen-recently`, `refused-this-boot`, `keeps-getting-lost`, then its
7192
- start. A sweep that is not a plan answers each lost home once: a later
7193
- sweep answers that loss `not-seen-recently`. A `lifecycle-busy` row does
7194
- not answer it: whatever OATS was doing to the home decides what it is
7195
- next, and a later sweep reads it again.
7191
+ `not-seen-recently`, `start-refused-retrying`, `keeps-getting-lost`, then
7192
+ its start. A sweep that is not a plan answers each lost home it started
7193
+ once: a later sweep answers that loss `not-seen-recently`. Four rows do
7194
+ not answer the loss, and a later sweep reads the home again:
7195
+ `lifecycle-busy` (whatever OATS was doing to the home decides what it is
7196
+ next), `start-refused` and `start-refused-retrying` (nothing was
7197
+ launched), and `keeps-getting-lost` (until its hour has passed; one
7198
+ without `nextAttemptAt` does answer it). The counts and the delays are
7199
+ one boot's: a reboot starts them again.
7196
7200
  - A home whose self-retire is scheduled or owed reads no `sessionEnd`; a
7197
7201
  launched one that does not run is listed `skipped`, `lifecycle-busy`, as
7198
7202
  a lost one is.
@@ -7275,12 +7279,15 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7275
7279
  nothing of how far it got. A child that ended without an answer is
7276
7280
  reported under that code too, in `sweep.error` or on stderr, and does not
7277
7281
  end the run.
7278
- - **What it runs, in order.** The resume sweep once (`oats session resume`).
7282
+ - **What it runs, in order.** The resume sweep (`oats session resume`).
7279
7283
  Then at second 0 of every minute: `oats schedule tick --host` when the
7280
- host schedule registry lists a scope, and a listing of every deployment's
7281
- instances, which records what runs for the next start's sweep. Each is a
7282
- child process. A minute whose tick still runs is skipped; a minute missed
7283
- is never replayed. With no scope registered it ticks nothing and says so.
7284
+ host schedule registry lists a scope, and the resume sweep again, which
7285
+ starts a home lost while the host runs, within the sweep's own bounds, and
7286
+ records what runs for a later sweep. Each is a child process. A minute
7287
+ whose tick still runs is skipped, and a sweep that still runs is not run
7288
+ beside itself; a minute missed is never replayed. With no scope registered
7289
+ it ticks nothing and says so. A sweep is said on stderr when its outcomes
7290
+ differ from those of the sweep before.
7284
7291
  - **On SIGTERM or SIGINT.** No further minute starts; a tick or a sweep that
7285
7292
  runs gets 10 seconds to finish naturally, then a private admission fence
7286
7293
  stops further launches and owned child groups get a further 5-second
@@ -7296,7 +7303,7 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
7296
7303
  modes. **The answer** is written once, when the run ends:
7297
7304
  `result` `{schemaVersion: 1, plan: false, signal, warnings, sweep, ticks, stopped}`.
7298
7305
  `signal` is `"SIGTERM"` or `"SIGINT"`; `warnings` an array of strings;
7299
- `sweep` the sweep's own `result`
7306
+ `sweep` the first sweep's own `result`
7300
7307
  ([The machine sweep](#the-machine-sweep-oats-session-resume)), or
7301
7308
  `{error: {code, message}}` when it failed (the run goes on); `ticks`
7302
7309
  `{run, skipped, failed, noScope}`, minutes counted; `stopped` one row per
package/docs/desktop.md CHANGED
@@ -686,10 +686,10 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
686
686
  One sentence above them says what a machine is: "Each machine runs this
687
687
  workspace in a folder of its own. The instances under a machine run on
688
688
  that machine." **All** stacks one section per deployment, each headed by
689
- its machine and folder ("This Mac · ~/acme", "altair · ~/northwind"),
690
- with "Instances on this machine" or "Instances on altair" under it. Then
691
- each deployment has a tab of its own, named by its machine ("altair";
692
- "This Mac · oats-v2" when this Mac holds two). A workspace with one
689
+ its machine and folder ("This Mac · ~/acme", "devbox · ~/northwind"),
690
+ with "Instances on this machine" or "Instances on devbox" under it. Then
691
+ each deployment has a tab of its own, named by its machine ("devbox";
692
+ "This Mac · acme-2" when this Mac holds two). A workspace with one
693
693
  deployment shows just that deployment's tab, its tree under the same
694
694
  heading. The tab you chose is
695
695
  remembered per workspace. With two or more deployments, the sidebar's
@@ -712,7 +712,7 @@ heading. The tab you chose is
712
712
  can't read other machines. A server that can't be reached stays under the
713
713
  workspace it last reported, marked "remembered".
714
714
  - **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
715
- altair"), with a mark when one of them isn't live.
715
+ devbox"), with a mark when one of them isn't live.
716
716
  - **Not matched to a workspace.** A deployment that can't be matched is
717
717
  listed on its own under that heading in the list, with its machine and
718
718
  a short reason; choosing it opens its tab on the Machines tab. When this
@@ -973,13 +973,20 @@ right of its parent, and related instances are grouped together. Siblings are
973
973
  joined by a dotted line through their dots. A parent's line to its children
974
974
  runs just to the right of the dotted line, so the two never merge.
975
975
 
976
+ The newest instance is on top: the tree is in spawn order, newest first, at
977
+ every level. A group of related instances sits where its first instance's
978
+ spawn time puts it, so spawning a child doesn't move the group, and starting
979
+ or stopping an instance moves nothing. Instances spawned at the same moment
980
+ are in name order, and an instance whose spawn time can't be read comes after
981
+ every one whose time can.
982
+
976
983
  A parent's line joins only the children that do its work. When the instances'
977
984
  OATS has the `instance-same-work` feature, a child the kernel reports as doing
978
985
  its parent's work (`sameWork: true` in its row, set with `oats spawn …
979
986
  --same-work` or `oats instance same-work <instance> on`) is joined to its
980
987
  parent, and any other child keeps its place and its indent with no line to its
981
988
  parent. Under one parent the joined children are listed first, then the others,
982
- each part in name order, so the parent's line ends at its last joined child and
989
+ each part newest first, so the parent's line ends at its last joined child and
983
990
  never passes one it doesn't join. Nothing else marks the flag: no label, no
984
991
  tag, and nothing for a screen reader, which still hears each child "under" its
985
992
  parent in the command palette. The command palette draws the same lines, in
@@ -1350,7 +1350,9 @@ The sweep resumes a lost home only when OATS can vouch for the loss, from
1350
1350
  what its own reads of that home saw (`oats status`, OATS Desktop and `oats
1351
1351
  tui` reading it, and the sweep's own read). All four must hold:
1352
1352
 
1353
- 1. OATS saw the home running for its current start.
1353
+ 1. OATS saw the home running for its current start. A start the sweep itself
1354
+ made counts as seen, so a home that is lost again before any read saw it
1355
+ running is still started again, within the hour's count below.
1354
1356
  2. No earlier sweep answered this loss. A sweep answers each lost home once,
1355
1357
  whatever it did with it (resumed, started fresh, blocked, refused or
1356
1358
  skipped), except a home it skipped because OATS was stopping, upgrading
@@ -1454,21 +1456,34 @@ refused. A home removed between the read and its start is reported
1454
1456
  `resume-lock-stuck` problem, with the path and what to do. It reads the
1455
1457
  lock and takes nothing. A free lock, a sweep that runs and a lock a gone
1456
1458
  sweep left are not reported.
1457
- - A loss is answered once: whatever a sweep did with it (resumed, refused,
1458
- skipped or blocked), no later sweep starts it again, in this boot or after
1459
- a reboot; a later sweep reports it `not-seen-recently`. A `lifecycle-busy`
1460
- skip is the one that answers nothing: the next sweep reads the home again. A refused resume is
1461
- never retried automatically: it is also noted for the boot, and reported
1462
- `refused-this-boot` should that answer be lost.
1463
- - A home lost unexpectedly is started by sweeps at most 3 times in a boot. A home lost again
1464
- after each resume (a harness that crashes the host or its terminal server,
1465
- say) is then reported `keeps-getting-lost`, and that loss is answered: no
1466
- sweep starts it again, after a reboot either. Start it by hand: its next
1467
- loss is a new one, with a new count in each boot. Every sweep start that launched
1468
- something counts (resumed, fresh or blocked), by home, as soon as that start
1469
- has answered, so a sweep killed while other starts run has counted it; a
1470
- refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
1471
- bounded nor counted.
1459
+ - A loss a sweep started is answered once: whether that start resumed, came
1460
+ up fresh or is blocked, no later sweep starts it again, in this boot or
1461
+ after a reboot; a later sweep reports it `not-seen-recently`. A
1462
+ `lifecycle-busy` skip answers nothing: the next sweep reads the home again.
1463
+ - A refused start answers nothing either. It launched nothing, and what
1464
+ refused it (a launch variable not set, no wake broker yet) is how the host
1465
+ was at that moment. The sweep notes it and tries that home again no sooner
1466
+ than 1 minute later, then 2, 4 and 8, and every 15 minutes after that; a
1467
+ sweep that runs before then reports it `start-refused-retrying`, with the
1468
+ refusal's code and the time of the next attempt, and starts nothing. The
1469
+ retries end when the loss is 24 hours old (`not-seen-recently`).
1470
+ - A home lost unexpectedly is started by sweeps at most 3 times in an hour. A
1471
+ home lost again after each resume (a harness that crashes the host or its
1472
+ terminal server, say) is then reported `keeps-getting-lost`, with the time
1473
+ the oldest of those starts is an hour old: a sweep starts the home again
1474
+ then. Every sweep start that launched something counts (resumed, fresh or
1475
+ blocked), by home, as soon as that start has answered, so a sweep killed
1476
+ while other starts run has counted it; a refused, skipped or busy one does
1477
+ not. The count and the retry delays are kept for one boot: a reboot starts
1478
+ both again. `oats session start --resume` run by hand is neither bounded
1479
+ nor counted.
1480
+ - That does not go on for ever. A home that uses up its 3 starts in 3 hours
1481
+ in a row is given up: its row has no time of a next attempt, the loss is
1482
+ answered, and no sweep starts it again until a person does. Hours are in a
1483
+ row when each begins less than an hour after the one before it cleared.
1484
+ Only an hour without one begins the count again: no start does. A person
1485
+ may start a home that was given up, and if it is lost again in a used-up
1486
+ hour it is given up again at once.
1472
1487
  A stop of the current start with the host is different: a successful
1473
1488
  restore after that administrative stop neither spends nor resets the
1474
1489
  crash budget, and the crash ceiling cannot prevent it. A failed or
@@ -1505,7 +1520,7 @@ refused. A home removed between the read and its start is reported
1505
1520
  restarts on the same kernel, including when read from older qualified
1506
1521
  records. A kernel reboot gives a fresh budget. Loss judgements remain
1507
1522
  per start, and a running look of a newly resumed start resets its prior
1508
- seen/lost judgement. Every new `oats host run` invokes the sweep;
1523
+ seen/lost judgement. Every `oats host run` invokes the sweep at its start and each minute;
1509
1524
  successful restores after a host stop remain eligible as described above.
1510
1525
  - The lock, the per-boot note and the record of what status saw live in
1511
1526
  `session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
@@ -128,11 +128,11 @@ and the rules its tests pin.
128
128
  | `shell-word.mjs` | `shellWord` and `shq`: one word of a command the kernel prints for a person to paste into a shell. It imports nothing, so `launch-preference.mjs` quotes by the rule `core.mjs` re-exports |
129
129
  | `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
130
130
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer; a job's slot (`acquireJobLock`, `releaseJobLock`) is taken by renaming a directory that already holds its record into place, and released by renaming it out before it is removed, so it is never there without its record; a slot whose record cannot be read (`unreadableSlot`, over `jobLockInfo`) marks only its job invalid in the tick, is released by `reconcile --clear`, and is doctor's `schedule-slot-unreadable` problem; a slot whose schedule is gone (`scheduleAbsence`: a local one not in `oats-schedules.json`; a workspace one not in the saved snapshot, its member read at a commit and no problem of it that could hide one; never refreshed there) is counted until reconcile --clear releases it with the job's attempt and state (`orphanSlot`, `reconcileOrphanSlot`), and is doctor's `schedule-slot-orphaned` problem, as is a workspace one absent that cannot be shown gone |
131
- | `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: one producer, `listInstances`; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
131
+ | `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: local listings and the sweep recording homes it started; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
132
132
  | `stable-node.mjs` | the one rule for a node path written into anything that outlives the process: the host timer's unit and `OATS_NODE_BIN` ([capabilities](capabilities.md#the-node-a-hook-writes-down)). It imports nothing of the kernel |
133
133
  | `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
134
134
  | `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
135
- | `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep once and the tick and the listing each minute, every one an owned child group (`host-run-work.mjs`) so that the loop stays free for the signal. On SIGTERM no minute is armed; active work gets 10 s, then the private scratch-file fence is closed and owned groups get 5 s of cancellation. The private bootstrap carries the fence only through kernel child argv, never public flags or environment. A detached kernel group atomically registers its pid/start and waits for the owner to verify it and acknowledge responsibility before importing launch-capable code; cancellation therefore does not depend on an intermediate supervisor remaining responsive. Schedule/trigger loops, resume batches and core launch boundaries read it synchronously, because a synchronous tick cannot service IPC while a command runs. Interrupted attempts remain unknown. The host-run claim stays held until owned work ends. After a final bounded listing, each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
135
+ | `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep at the start, then the tick and the sweep each minute, every one an owned child group (`host-run-work.mjs`) so that the loop stays free for the signal. On SIGTERM no minute is armed; active work gets 10 s, then the private scratch-file fence is closed and owned groups get 5 s of cancellation. The private bootstrap carries the fence only through kernel child argv, never public flags or environment. A detached kernel group atomically registers its pid/start and waits for the owner to verify it and acknowledge responsibility before importing launch-capable code; cancellation therefore does not depend on an intermediate supervisor remaining responsive. Schedule/trigger loops, resume batches and core launch boundaries read it synchronously, because a synchronous tick cannot service IPC while a command runs. Interrupted attempts remain unknown. The host-run claim stays held until owned work ends. After a final bounded listing, each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
136
136
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
137
137
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
138
138
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v6.0.3
44
- oats.aweb: v1.41.0
44
+ oats.aweb: v1.42.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.25.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
12
+ | `oats.framework` | `oats-framework/v1.25.2` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
13
  | `oats.okf` | `v6.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.41.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
14
+ | `oats.aweb` | `v1.42.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
package/docs/packages.md CHANGED
@@ -55,7 +55,7 @@ packages:
55
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
56
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
57
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
58
- convention (`v5.8.0` or `oats-framework/v1.25.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.25.2`) and the payload path. An id
59
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
60
60
  a package outside the catalog"). The catalog is the reviewed official list
61
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -78,9 +78,9 @@ members:
78
78
  - git:github.com/acme/agents
79
79
  - git:github.com/acme/platform
80
80
  packages:
81
- oats.framework: v1.25.0
81
+ oats.framework: v1.25.2
82
82
  oats.okf: v6.0.3
83
- oats.aweb: v1.41.0
83
+ oats.aweb: v1.42.1
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -155,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
155
155
  ## `oats package add | remove`
156
156
 
157
157
  ```bash
158
- oats package add oats.aweb v1.41.0 # a catalog version
158
+ oats package add oats.aweb v1.42.1 # a catalog version
159
159
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
160
160
  oats package remove acme.tools
161
161
  ```
@@ -432,11 +432,11 @@ A soul that names one of the package's capabilities with
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
434
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.0.3", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.25.0", "path": "oats-package" }
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.25.2", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.25.0`
441
- resolves to tag `oats-framework/v1.25.0`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.25.2`
441
+ resolves to tag `oats-framework/v1.25.2`. Resolving through the catalog never
442
442
  advances a lock by itself: `oats sync` does, and says so.