@awebai/oats 0.43.2 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/bin/oats.mjs +119 -37
  2. package/docs/capabilities.md +37 -1
  3. package/docs/configuration.md +65 -0
  4. package/docs/desktop-cli-api.md +149 -4
  5. package/docs/execution-targets.md +75 -0
  6. package/docs/implementation.md +14 -1
  7. package/docs/knowledge.md +2 -1
  8. package/docs/oats-local.schema.json +19 -1
  9. package/docs/oats-workspace.schema.json +1 -1
  10. package/docs/release-notes/v0.43.3.md +22 -0
  11. package/docs/release-notes/v0.44.0.md +161 -0
  12. package/docs/schedules.md +27 -9
  13. package/docs/souls-and-instances.md +7 -0
  14. package/lib/core.mjs +254 -88
  15. package/lib/instance-events.mjs +1 -1
  16. package/lib/instance-inspect.mjs +39 -6
  17. package/lib/launch-prompt-fixtures/README.md +49 -0
  18. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +35 -0
  19. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +35 -0
  20. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +35 -0
  21. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +35 -0
  22. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +77 -0
  23. package/lib/launch-prompt-fixtures.mjs +114 -0
  24. package/lib/launch-prompt-policy.mjs +73 -0
  25. package/lib/launch-prompt-transport.mjs +102 -0
  26. package/lib/launch-prompts.mjs +216 -0
  27. package/lib/operator-coverage.mjs +134 -0
  28. package/lib/remote.mjs +15 -9
  29. package/lib/schedule.mjs +57 -10
  30. package/lib/teams-verbs.mjs +3 -3
  31. package/lib/triggers.mjs +2 -2
  32. package/lib/workspace.mjs +20 -2
  33. package/package.json +1 -1
  34. package/skills/oats-getting-started/SKILL.md +15 -0
@@ -447,7 +447,10 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
447
447
  - Four checks, each `{status, items}`. An item is `{subject, status,
448
448
  required, reason, producer, evidence, remedy}`, plus `capability: {id}` on a
449
449
  per-capability item and the keys named below. Statuses are `pass | fail |
450
- unknown | not-applicable`.
450
+ unknown | not-applicable`. An item's `reason`, `remedy` and kernel
451
+ `problems[].message` are at most 1000 characters (0.44.0). Longer text,
452
+ such as a remote error, is clipped with `…`. A provider's `result` is
453
+ relayed verbatim.
451
454
  - A check's status rolls up its required items (any `fail` → `fail`, else any
452
455
  `unknown` → `unknown`, else `pass`; `not-applicable` with none required).
453
456
  - `summary.ready` is true when every required item passes or is
@@ -467,6 +470,8 @@ naming `oats sync`; team refusals go under `configured` instead.
467
470
  **`configured`.** Producer `capability manifest`: each manifest `requires`
468
471
  command, `evidence: {command}`, the manifest's `install` hint as remedy.
469
472
  Producer `team model`: the soul's [team readiness items](#team-readiness-items).
473
+ Producer `operator coverage` (0.44.0): the workspace's and the soul's teams'
474
+ [operator coverage items](#operator-coverage-items), warnings only.
470
475
 
471
476
  **`member`** (producer `workspace discovery`): the soul's repository is a
472
477
  confirmed member (`evidence: {repoKey, workspace, commit}`); `fail` when not
@@ -672,13 +677,22 @@ same argument, given once). The ref is checked before anything is written.
672
677
  ### `oats sync`
673
678
 
674
679
  ```text
675
- oats sync [--dir <d>] --json
680
+ oats sync [--dir <d>] [--plan] --json
676
681
  ```
677
682
 
678
683
  Discovers the workspace, confirms membership, resolves `packages:`, writes
679
684
  `oats-lock.json` (lockfileVersion 3), takes the automations snapshot and
680
685
  reports. It creates `agents/` if missing.
681
686
 
687
+ `--plan` (0.44.0) previews: the same discovery, resolution and report, with
688
+ `plan: true`, and nothing written (no lock, no `agents/`, no automations
689
+ snapshot; the remote cache fills as any read fills it). `changes[]` is what a
690
+ bare `oats sync` would apply, `workspace.lock` the lock it would write, and
691
+ `automations` counts what it would snapshot. A flag or a positional `sync` does
692
+ not read is refused with `E_BAD_ARGS` (`details: {flag}` or `{argument}`) before
693
+ anything is read or written. A kernel before 0.44.0 ignores `--plan` and
694
+ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
695
+
682
696
  ```json
683
697
  {"syncApi":1,"automations":{"triggers":3,"schedules":2,"problems":1,"takenAt":"2026-09-26T19:58:09.281Z"},
684
698
  "workspace":{"name":"acme","key":"github.com/acme/agents","url":"https://github.com/acme/agents.git","commit":"45b86f64…",
@@ -693,6 +707,7 @@ reports. It creates `agents/` if missing.
693
707
  "problems":[],"warnings":[]}
694
708
  ```
695
709
 
710
+ - `plan`: `true` on a `--plan` answer, absent otherwise.
696
711
  - `automations`: counts from the snapshot this sync took.
697
712
  - `workspace.name` is `standalone:<repo>` on a standalone view.
698
713
  - `members[]`: `status` is `confirmed | not-listed | no-backlink |
@@ -1098,7 +1113,10 @@ operator guide: [workspaces.md](workspaces.md#teams).
1098
1113
  home's own record, as always.
1099
1114
  - **A soul's key** is its qualified name: `<package>/<soul>`, or
1100
1115
  `<member>/<soul>` with the member repository's name (as `souls.disabled`
1101
- names it). A label matches `[a-z0-9][a-z0-9._-]*`.
1116
+ names it). A label matches `[a-z0-9][a-z0-9._-]*` and is at most 64
1117
+ characters (0.44.0). A longer one is refused: `E_WORKSPACE_SCHEMA` in
1118
+ either file, `E_BAD_ARGS` from `oats teams add`, and `E_TRIGGER_INVALID`
1119
+ (`field: spawn.teams`) in a trigger.
1102
1120
  - **Team ids.** A `team` value (in either file, and `oats teams add --team`)
1103
1121
  matches `^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$`: the kernel's safety rule
1104
1122
  (never `-`-led, no whitespace or control characters, bounded). Otherwise
@@ -1324,6 +1342,77 @@ hasn't observed its workspace yet; run oats sync"`. A removed key in
1324
1342
  `oats-local.yaml` makes doctor answer that refusal, as for any unreadable
1325
1343
  local file.
1326
1344
 
1345
+ <a id="operator-coverage-items"></a>
1346
+ ### Operator coverage items
1347
+
1348
+ (0.44.0, [#671](https://github.com/awebai/oats/issues/671)) Every workspace
1349
+ needs an operator: a soul that composes `oats.setup`. A soul the workspace
1350
+ offers **covers** it when all of these hold on this machine:
1351
+
1352
+ - it is a confirmed member's soul, a locked package soul or an external soul;
1353
+ - it is not in `souls.disabled`;
1354
+ - it resolves as a spawn would;
1355
+ - its modules include `oats.setup`;
1356
+ - it empties no layer slot the workspace fills, so it keeps the workspace's
1357
+ core, messaging and knowledge.
1358
+
1359
+ It covers a team when that team is among its resolved teams. Detection is by
1360
+ composition only: a soul's name never counts, and there is no role marker. An
1361
+ eligible soul is not a launched or authorized seat. These are warnings: they
1362
+ never refuse anything, and nothing is spawned.
1363
+
1364
+ `oats readiness` lists them under `checks.configured` with `producer:
1365
+ "operator coverage"`, `required: false`, `code`, `reason` and `remedy`. Team
1366
+ items cover the subject's own teams only.
1367
+
1368
+ | Code | Subject | Status | Keys | When |
1369
+ |---|---|---|---|---|
1370
+ | `operator-soul-missing` | `operator` | `fail` | `evidence.excluded` | no soul the workspace offers composes `oats.setup` |
1371
+ | `operator-team-uncovered` | `team <label>` | `fail` | `label` | no such soul is eligible for one of the subject's teams |
1372
+ | `operator-coverage-unknown` | `operator` | `unknown` | | a question is still open and a source could not be read; it never asserts absence |
1373
+
1374
+ A source could not be read when:
1375
+
1376
+ - the workspace itself could not be read;
1377
+ - only its member view could (an unreadable host);
1378
+ - discovery dropped a member as `cannot-read`;
1379
+ - a soul file or listing could not be read;
1380
+ - a resolution hit `E_REMOTE_UNREADABLE`.
1381
+
1382
+ A covering soul that was found is still reported. Any other refusal belongs to
1383
+ the soul, since a spawn would meet it too, so that soul does not cover.
1384
+
1385
+ `evidence.excluded` lists the souls that cannot cover although they are
1386
+ relevant, each as `{soul, code}`:
1387
+
1388
+ - a soul whose `soul.yaml` names `oats.setup` but that is disabled
1389
+ (`E_SOUL_DISABLED`), ambiguous (`E_SOUL_AMBIGUOUS`) or refused (the
1390
+ resolution's code);
1391
+ - a soul that composes `oats.setup` but empties a slot the workspace fills
1392
+ (`slot-none`, with `slots`).
1393
+
1394
+ Coverage that holds adds no item.
1395
+
1396
+ `oats doctor` stays offline. It resolves the souls from this machine's cache
1397
+ only (no git process, no network) and checks the workspace and **every**
1398
+ declared team. It lists `operator-soul-missing` and `operator-team-uncovered`
1399
+ under `problems[]` as `{code, label?, message, remedy}` (text: `! <code>:
1400
+ <message>`, then the remedy).
1401
+
1402
+ Doctor reads the resolutions that `oats souls`, readiness and spawn keep in the
1403
+ cache. `oats sync` alone does not resolve souls. When the cache cannot answer,
1404
+ doctor adds no problem. Instead it adds one `information[]` line, starting
1405
+ `operator-coverage-unknown:`, whose remedy is `oats sync`, then `oats souls`.
1406
+ The cache cannot answer when:
1407
+
1408
+ - the machine never synced;
1409
+ - the cache was pruned;
1410
+ - a soul was not yet resolved here;
1411
+ - the deployment uses a configured `standalone:` view, whose membership read
1412
+ is not cached. There, ask readiness.
1413
+
1414
+ Any other error, such as an invalid lock, is named as itself.
1415
+
1327
1416
  <a id="soul-launch-preferences-feature-launch-preference-oats-0300"></a>
1328
1417
  ## Launch preferences
1329
1418
 
@@ -1460,6 +1549,48 @@ shows the drift as `launch-changed`.
1460
1549
  No verb writes `souls.launch`; it is plain YAML. A GUI that edits it checks
1461
1550
  the result with `oats inspect --soul <name> --json`.
1462
1551
 
1552
+ ## Launch prompt results
1553
+
1554
+ Spawn preview adds `launchPromptAnswers` with the strict effective boolean
1555
+ `awebDevelopmentChannel` and `consentSource` (a config-file
1556
+ JSON pointer or `null`). This is a policy report, not a terminal observation
1557
+ or readiness assertion. Only the aweb development-channel confirmation is
1558
+ covered, restricted to the qualified Claude executable digest, platform and
1559
+ geometry documented under [launch consent](configuration.md#exact-home-launch-prompt-consent).
1560
+ Folder-trust prompts remain unexpected and blocked.
1561
+
1562
+ An observed launch has `launchPrompts: {status, answers, reason, receipt}`.
1563
+ `receipt` carries the actual checked launch-prompt event-write results,
1564
+ including partial log availability; it is not a receive-readiness receipt.
1565
+ The `launch-prompt` event records the launch start and pane/PID identity,
1566
+ consent provenance, signature identifier/digest, action and outcome. Intent is
1567
+ durable before input; submission (`submitted`, `failed`, `uncertain`) and an
1568
+ observed screen transition are distinct. Unexpected raw screen text is never
1569
+ included in the receipt.
1570
+
1571
+ Spawn and start both reuse `E_SPAWN_INCOMPLETE` for retained prompt outcomes,
1572
+ with `launchPrompts.status` set to `blocked` or `incomplete`. Error details
1573
+ preserve `instance`, `home`, `launched:"unknown"`, `unconfirmed:true` and add
1574
+ `retained:true`, `target`,
1575
+ `parentLineageCommitted`, and `launchPrompts`. Unknown prompts report
1576
+ `blocked: unexpected prompt`. An incomplete audit can follow a possible key;
1577
+ clients must not offer automatic key retry. `launched:false` in retained
1578
+ metadata does not mean there is no process or that another harness may be
1579
+ allocated. Use runtime inspection and the existing start/restart lifecycle.
1580
+ Same-key spawn replay cannot convert a blocked outcome to successful spawn.
1581
+
1582
+ `answers` can contain a `submitted` answer even when the final status is
1583
+ `blocked`: the accepted installed-plugin and plugin-absent completion banners
1584
+ pin specific model/billing/effort/permission text. A different normal-looking banner can block after Enter
1585
+ while the actual pane is active. Consumers must preserve that submitted receipt
1586
+ and never translate this outcome into “nothing started” or automatic retry.
1587
+ The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
1588
+ is part of the shipping contract.
1589
+
1590
+ Strict Desktop/pi readers must accept these additive fields and the new event
1591
+ kind before a writer containing them ships. For operator recovery, see
1592
+ [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
1593
+
1463
1594
  ## Spawn
1464
1595
 
1465
1596
  ### The preview
@@ -1702,7 +1833,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
1702
1833
  | `E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN` | see above | |
1703
1834
  | `E_DECISION_STALE` | `{decision}` | |
1704
1835
  | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
1705
- | `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}` | |
1836
+ | `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}`; retained launch-prompt outcomes additionally carry `{retained: true, target, parentLineageCommitted, launchPrompts}` | See [launch prompt results](#launch-prompt-results). |
1706
1837
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
1707
1838
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
1708
1839
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
@@ -2761,6 +2892,20 @@ selection flags. See [the start workflow](desktop-instance-start.md).
2761
2892
  - Restart is one command: the kernel validates the new selection before
2762
2893
  stopping, and owns the stop, lock, launch recovery and metadata. Never
2763
2894
  restart by retiring and spawning.
2895
+ - Launch recovery (0.44.0). A start keeps its launch receipt in the home
2896
+ until the next start replaces it. The next start **adopts** a receipt only
2897
+ for a start `instance.json` does not record (one whose metadata write
2898
+ failed): it records that target and launches nothing again. A receipt for
2899
+ a start `instance.json` already records, on the target it records, is
2900
+ **completed**, and none of it is recorded again: a newer launch recipe or
2901
+ provider metadata stays. A plain start then answers `E_SESSION_RUNNING`
2902
+ while that target runs, writing nothing and running no hook; a restart, or
2903
+ a start after the target is gone or the harness exited, starts from
2904
+ `instance.json` as it is, and its own receipt replaces the old one. A
2905
+ receipt that names the recorded start on another target is ambiguous:
2906
+ `E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
2907
+ that target and the way out: stop it, then `oats session restart`, which
2908
+ goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
2764
2909
  - A lost response does not mean the launch failed: check status before a
2765
2910
  retry. A remote home's saved route names its execution host.
2766
2911
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
@@ -578,6 +578,81 @@ its children, waits `--stop-grace <seconds>` (default 20, at most 300), then
578
578
  starts in place. It never escalates: a harness still running is reported
579
579
  (`E_SESSION_STOP_FAILED`) and nothing is launched.
580
580
 
581
+ ### Launch prompt outcomes
582
+
583
+ For a home with [explicit host-local consent](configuration.md#exact-home-launch-prompt-consent),
584
+ spawn, start and restart can observe only the process created by that invocation.
585
+ A new window supplies the exact pane identity. Reusing a pane requires a changed
586
+ numeric process ID and fresh visible bytes differing from the pre-respawn
587
+ screen. An already-running process, stale screen or scrollback grants no input
588
+ authority. Home, socket, pane, PID, geometry and exact visible signature are
589
+ rechecked before each key.
590
+
591
+ Observation is bounded to 30 seconds with 100 ms intervals. Only accepted
592
+ version/platform-specific startup and prompt frames keep authority open;
593
+ unexpected output permanently closes it. Only the exact aweb development-channel
594
+ confirmation can be answered, once, with one Enter. Folder-trust and API-key
595
+ prompts are unexpected and block; no multi-prompt sequence is authorized.
596
+ For a qualified launch, the controller saves the exclusively owned window's
597
+ size policy and dimensions, temporarily pins it to the fixture's 110x35
598
+ geometry, and confirms the size before matching. It audits restoration on
599
+ every exit, including timeout and failure; a replaced process/window is never
600
+ resized during cleanup. Pinning a reused pane cannot establish freshness: that
601
+ must already be proved at its original geometry. The selected-option frame
602
+ is rechecked before Enter. Uncertain submission is never retried. Only the
603
+ qualified Claude executable/platform/geometry in
604
+ [configuration](configuration.md#exact-home-launch-prompt-consent) has an enabled
605
+ development-channel fixture. Installed version alone grants no match. Ordinary
606
+ `session input` and wake delivery do not enter this controller.
607
+
608
+ Both spawn and start return `E_SPAWN_INCOMPLETE` for retained prompt failures.
609
+ With `launchPrompts.status` set to `blocked`, the home, actual terminal target,
610
+ provider effects and committed parent lineage are retained. Only an opted-in
611
+ launch commits a new parent link before dispatch; ordinary launches keep their
612
+ post-launch lineage commit and compensate a failed anchor write. That preserves
613
+ timing, not overwrite behavior: even non-opted-in parent spawns now refuse an
614
+ anchor edited or removed since the original pre-hook snapshot, instead of
615
+ replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
616
+ `answers`, `reason` and event `receipt`; unknown prompts use
617
+ `blocked: unexpected prompt`. Status `incomplete` means the audit could not be
618
+ completed, including a possible key followed by an audit failure. It is
619
+ not proof that no input was sent. Both outcomes record `launched:false` while
620
+ retaining the real process/endpoint for inspection: this is never permission
621
+ to allocate another harness.
622
+
623
+ If metadata or pending-receipt recording fails after controller completion,
624
+ the API escalates to `incomplete` and appends a checked `launch-prompt` incomplete
625
+ event, retaining prior answers and receipts. Failed audit writes remain
626
+ `incomplete`; they never authorize another key or retry.
627
+
628
+ A replaced or unverifiable launch home is the explicit auditing exception.
629
+ There is no new home or deployment row: resolving either log through current
630
+ home metadata could address the replacement incarnation. The API reports
631
+ `launch home identity changed; metadata retained at original home`, preserves
632
+ prior evidence, and adds `{ok:false, results:[]}` to the receipt array. That
633
+ entry means zero audit destinations were attempted, not a successful write.
634
+ No audit or metadata write is directed into the replacement home.
635
+
636
+ A blocked result can follow a successfully submitted Enter. The accepted
637
+ completion families cover exact installed-plugin and plugin-absent banners;
638
+ different model, billing, effort or permission text can leave the pane active while
639
+ reporting a retained block. Inspect `answers` and the event receipts; never infer
640
+ that nothing started or nothing was answered. See the
641
+ [completion limitation](configuration.md#exact-home-launch-prompt-consent).
642
+
643
+ Retiring a blocked or incomplete spawned home can preserve a recovery copy
644
+ labelled `changed instance-home bytes`, even without authored changes: the
645
+ kernel changed metadata from `launched:true` to `false` after its baseline.
646
+ This conservative recovery is intentional. The independent runtime receipt
647
+ still controls the endpoint, and a mismatched metadata endpoint is refused.
648
+
649
+ Inspect the retained home with `oats session inspect --home <home>` and attach
650
+ if needed. A later `oats session start --home <home>` uses the ordinary running
651
+ process checks; it cannot answer into a still-running retained launch. Repeating
652
+ spawn, including the same idempotency key, does not replay prompt answers or
653
+ create a duplicate home. A genuinely new process in a later launch gets its own
654
+ bounded authority. A prompt receipt does not assert receive readiness.
655
+
581
656
  ### Stop
582
657
 
583
658
  `oats instance stop <instance> --plan` reports the session state, recorded
@@ -58,12 +58,15 @@ published to npm. Its developer docs are in
58
58
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
59
59
  | `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 |
60
60
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
61
+ | `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 |
61
62
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
62
63
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
63
64
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
64
65
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
65
66
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
66
67
  | `servers.mjs` | routing commands to a registered server |
68
+ | `launch-prompt-policy.mjs` | strict host-local exact-home aweb development-channel consent, canonical directory validation and config provenance |
69
+ | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts and the fixture-gated exact aweb development-channel signature |
67
70
  | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
68
71
 
69
72
  The schedule registry stores explicit concurrency caps, leaving the schedule
@@ -116,6 +119,14 @@ timeouts/errors are unchanged. Screen comparison can set only the observational
116
119
  use inert command runners and clocks; they do not qualify broker delivery or
117
120
  harness acceptance.
118
121
 
122
+ Schedule doctor diagnostics read saved definitions, run state, snapshot and
123
+ validated local configuration without constructing a live placement context.
124
+ Only a persisted attempt is described as blocking another run; an unknown last
125
+ observation may be refreshed by a later eligible tick. Workspace exclusions
126
+ can be diagnosed offline, but owner authorization cannot be established there,
127
+ so the remedy remains diagnostic prose. This does not add retained-state
128
+ reconciliation outside current placement or mutate attempts and locks.
129
+
119
130
  The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
120
131
  a provider. Provider behaviour lives in capabilities; the kernel supplies
121
132
  their contracts ([layers](layers.md)).
@@ -192,7 +203,9 @@ gets the plain per-call behaviour. Within a session:
192
203
  the half-initialised cache's wait and the lock-race backoff. What the
193
204
  deadline ends is a `timeout` (a peel or version it ended is never read as a
194
205
  missing commit or an older git), so an unread member degrades as any
195
- unreadable one. A cut wait never changes what it judges: past the deadline
206
+ unreadable one. A peel is judged by git's own result (`timedOut`), never by
207
+ the wall clock: git's timer can fire a moment before `Date.now()` reaches the
208
+ deadline. A cut wait never changes what it judges: past the deadline
196
209
  no lock is taken or reclaimed (live, stale or unreadable), and a cache
197
210
  directory waited for less than in full is not taken for a crash's leftover;
198
211
  - every git child is ended with SIGTERM first and SIGKILL only after a
package/docs/knowledge.md CHANGED
@@ -227,7 +227,8 @@ identical copies in both role capabilities.
227
227
  `--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
228
228
  soul as a spawn would, fetches its module at the locked commit into
229
229
  `<deployment>/.oats/modules/` and runs it with the soul's merged settings
230
- and `OATS_SOUL`, the soul's source at that commit.
230
+ and `OATS_SOUL`, the soul's source at that commit, with the soul's
231
+ `OATS_AGENT` and `OATS_SOUL_ID` as its hooks get them.
231
232
  An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.
232
233
 
233
234
  ### Consult
@@ -26,6 +26,24 @@
26
26
  "additionalProperties": { "type": "string", "minLength": 1 },
27
27
  "description": "<repo key>: <path on this machine> for member clones outside the convention."
28
28
  },
29
+ "launchPromptAnswers": {
30
+ "type": "object",
31
+ "additionalProperties": false,
32
+ "properties": {
33
+ "homes": {
34
+ "type": "object",
35
+ "additionalProperties": {
36
+ "type": "object",
37
+ "additionalProperties": false,
38
+ "properties": {
39
+ "awebDevelopmentChannel": { "type": "boolean" }
40
+ }
41
+ },
42
+ "description": "Exact absolute canonical instance-home paths only; no wildcard or ancestor inheritance. Runtime validation resolves existing ancestors for homes not yet created."
43
+ }
44
+ },
45
+ "description": "Host-only consent to the bounded exact aweb development-channel confirmation. Missing awebDevelopmentChannel is false; provider settings and captured recipes do not grant consent."
46
+ },
29
47
  "settings": {
30
48
  "type": "object",
31
49
  "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
@@ -155,6 +173,6 @@
155
173
  },
156
174
  "$defs": {
157
175
  "launchPreference": { "type": "object", "additionalProperties": false, "required": ["harness"], "properties": { "harness": { "enum": ["pi", "claude", "codex"], "description": "The harness the role should run on." }, "model": { "type": "string", "minLength": 1, "pattern": "^[^\\s-][^\\s]*$", "description": "A model id for that harness; absent: the harness's own model." } } },
158
- "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" }
176
+ "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$", "maxLength": 64, "description": "A team label: at most 64 characters (0.44.0), the length the Desktop shows." }
159
177
  }
160
178
  }
@@ -60,7 +60,7 @@
60
60
  },
61
61
  "$defs": {
62
62
  "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
63
- "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
63
+ "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$", "maxLength": 64, "description": "A team label: at most 64 characters (0.44.0), the length the Desktop shows." },
64
64
  "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
65
65
  "packageId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
66
66
  "packageVersion": {
@@ -0,0 +1,22 @@
1
+ # OATS 0.43.3
2
+
3
+ ## Added
4
+
5
+ - A dispatched capability command (`oats <namespace> <command>`) now gets
6
+ `OATS_AGENT` and `OATS_SOUL_ID`, with the values its soul's lifecycle hooks
7
+ get: the soul's agents-root name and its stable id (`<repoKey>#<soul>`, or
8
+ `package:<id>#<soul>`). The same soul gives the same values from an
9
+ instance home, from the deployment with `--soul` or as the default soul,
10
+ and in its hooks
11
+ ([#688](https://github.com/awebai/oats/issues/688)). From the deployment,
12
+ `OATS_SOUL` is a per-commit or temporary copy of the soul, so a provider
13
+ keys durable state on `OATS_SOUL_ID` instead: `oats okf harvest` needs this
14
+ to keep its owner across runs
15
+ ([oats-okf#54](https://github.com/awebai/oats-okf/issues/54)).
16
+ See [Commands and hooks](../capabilities.md#commands-and-hooks).
17
+
18
+ ## Changed
19
+
20
+ - An `OATS_AGENT` or `OATS_SOUL_ID` in the caller's environment no longer
21
+ reaches a dispatched command, as an ambient `OATS_SOUL` already did not: it
22
+ named another soul.
@@ -0,0 +1,161 @@
1
+ # OATS 0.44.0
2
+
3
+ ## Added
4
+
5
+ - **The launcher can answer one launch prompt for a home you opt in**
6
+ ([#708](https://github.com/awebai/oats/issues/708)). `oats-local.yaml`
7
+ gains the host-only strict boolean
8
+ `launchPromptAnswers.homes.<canonical-home>.awebDevelopmentChannel`, default
9
+ false: no existing home is opted in, and provider development mode is not
10
+ consent. For an opted-in home, a spawn or start the kernel itself launches
11
+ answers Claude Code's aweb development-channel confirmation with one Enter,
12
+ and only on an exact match of a qualified fixture (Claude 2.1.289,
13
+ `darwin-arm64`, 110x35, bound to the executable's SHA-256; completion frames
14
+ with the aweb plugin absent or installed). Everything else is blocked:
15
+ folder trust, API keys and any other or changed prompt. Session input and
16
+ wake delivery gain no prompt authority.
17
+ - The spawn preview reports the home's effective policy and its source
18
+ (`launchPromptAnswers`), and an opted-in launch warns that a harness
19
+ update can block it until fixtures are refreshed. There is never a
20
+ fallback key or a broader matcher.
21
+ - A blocked or uncertain launch keeps the home and pane and answers
22
+ `E_SPAWN_INCOMPLETE` with additive `launchPrompts` details (`status`,
23
+ `answers`, `reason`, `receipt`). Inspect the pane; never resend or
24
+ relaunch automatically. A submitted answer is not readiness, and a
25
+ retained `launched:false` is not proof the process is gone.
26
+ - Every answer and every outcome is a checked `launch-prompt` instance
27
+ event, including metadata or receipt failures after the controller
28
+ finished. A replaced home is the one exception: nothing is written into
29
+ the replacement.
30
+ - `workspaceTrust` is refused with instructions to remove it; folder trust
31
+ is [oats#712](https://github.com/awebai/oats/issues/712).
32
+ - Other model, billing, effort or permission banners after a submitted Enter
33
+ still block (`E_SPAWN_INCOMPLETE`, `blocked`).
34
+
35
+ See [configuration](../configuration.md#exact-home-launch-prompt-consent)
36
+ and [recovery](../execution-targets.md#launch-prompt-outcomes).
37
+ - **The Desktop shows launch-prompt consent and retained launches**
38
+ ([#711](https://github.com/awebai/oats/issues/711)). The spawn dialog shows a
39
+ home's development-channel consent and its source. A retained launch says
40
+ why and gives one next step: inspect the existing pane, then
41
+ `oats session start --home` (no new spawn, no retry). Activity shows
42
+ `launch-prompt` events.
43
+ - A provider's readiness binding check and a layer operation
44
+ (`oats operation run`) get `OATS_SOUL_ID`, and `OATS_AGENT` with the value
45
+ the soul's hooks and dispatched commands get, from a home and with
46
+ `--soul`: every provider surface now sees one soul identity
47
+ ([#707](https://github.com/awebai/oats/issues/707)). The readiness answer is
48
+ unchanged. See [Readiness check](../capabilities.md#readiness-check-bindingcheck).
49
+ - Readiness and doctor warn when a workspace has no operator soul
50
+ ([#671](https://github.com/awebai/oats/issues/671)). An operator soul is a
51
+ soul the workspace offers that composes `oats.setup`. The codes are:
52
+ - `operator-soul-missing`: no such soul;
53
+ - `operator-team-uncovered`: none is eligible for a team;
54
+ - `operator-coverage-unknown`: coverage cannot be read. It never asserts
55
+ absence.
56
+
57
+ Detection is by composition, never by a soul's name. Disabled and
58
+ unresolvable souls do not count, nor does one that empties a layer the
59
+ workspace fills. These are warnings only (`required: false`): nothing
60
+ refuses or spawns, and an eligible soul is not a launched seat.
61
+ - Readiness reports the subject's own teams.
62
+ - Doctor stays offline. It resolves from this machine's cache, which `oats
63
+ souls` fills, and checks every declared team. When the cache cannot answer,
64
+ it says coverage is unknown.
65
+
66
+ See [Operator coverage items](../desktop-cli-api.md#operator-coverage-items).
67
+
68
+ ## Changed
69
+
70
+ - **A team label is at most 64 characters**
71
+ ([#726](https://github.com/awebai/oats/issues/726)). Both
72
+ `oats-workspace.yaml` and `oats-local.yaml` now refuse a longer label. The
73
+ refusal is `E_WORKSPACE_SCHEMA`, and the message names the label and the
74
+ 64-character limit. `oats teams add` and a trigger's `spawn.teams` apply
75
+ the same bound.
76
+ - **Who this breaks:** a workspace or deployment with a label over 64
77
+ characters. The Desktop could never show such a label: it refused the
78
+ whole readiness answer.
79
+ - **What to do:**
80
+ - Shorten the label wherever it is used: `teams:`, `defaultTeam:`,
81
+ `souls:`, oats-local.yaml, and a trigger's `spawn.teams`.
82
+ - Respawn any instance whose recorded default team had the long label.
83
+ It keeps its spawn-time record, so readiness for it still reports
84
+ the long label.
85
+
86
+ See [Teams](../desktop-cli-api.md#teams).
87
+ - For `--soul` on a package soul, a readiness binding check and a layer
88
+ operation get `OATS_AGENT` as `<package>--<soul>`, the value its hooks
89
+ get, instead of the bare soul name.
90
+ - **Ordinary parent spawns refuse an edited anchor**
91
+ ([#708](https://github.com/awebai/oats/issues/708)). A `relation: parent`
92
+ spawn keeps its post-launch lineage timing but now refuses when the anchor's
93
+ `instance.json` was edited or removed since the spawn read it, instead of
94
+ overwriting the change with stale data.
95
+ - **Retirement keeps a recovery copy after a blocked spawn**: a blocked
96
+ spawn's kernel metadata transition counts as a changed home, so retirement
97
+ keeps a recovery copy even when no authored bytes changed.
98
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.45.0`**, so it runs against
99
+ this release's kernel; the Desktop 0.43.x refuses a 0.44 CLI. Upgrade the
100
+ Desktop and the CLI together.
101
+
102
+ ## Fixed
103
+
104
+ - **Readiness clips long item text**
105
+ ([#725](https://github.com/awebai/oats/issues/725)). An item's `reason`,
106
+ `remedy` and kernel `problems[].message` are at most 1000 characters,
107
+ clipped with `…`. A provider's refusal code over 128 characters, or with
108
+ control characters, is reported as `provider-unavailable`. Before, a long
109
+ remote error made the Desktop refuse the whole readiness answer. One
110
+ example is the workspace discovery error in the member and package-soul
111
+ items. A provider's own `result` is still relayed verbatim.
112
+ - **A commit the read just fetched is no longer reported missing**
113
+ ([#728](https://github.com/awebai/oats/issues/728)). When a read's deadline
114
+ or git's own timeout ended the check that a commit is in the cache, the
115
+ read reported the commit missing or "not a commit" (`not-found`), even one
116
+ it had just fetched. git's timer can fire a moment before the wall
117
+ clock reaches the deadline. Such a check is now the read's `timeout`
118
+ (`E_REMOTE_UNREADABLE`, reason `timeout`, stage `fetch`), judged by git's
119
+ own result. This covers a commit already in the cache, too: it is no
120
+ longer refetched or reported missing after a timed-out check. No new codes
121
+ or fields.
122
+
123
+ - **`oats sync --plan` previews; it used to apply**
124
+ ([#731](https://github.com/awebai/oats/issues/731)). `sync` ignored
125
+ `--plan`, so the "preview" wrote the lock. `--plan` now runs the same
126
+ discovery and resolution and gives the same report (`plan: true` in JSON;
127
+ the text says what a bare `oats sync` would change) and writes nothing: no
128
+ lock, no `agents/`, no automations snapshot. `oats sync` also refuses a flag
129
+ or positional it does not read with `E_BAD_ARGS`, naming it and the usage,
130
+ instead of ignoring it. A script that passed an unknown flag to `sync` now
131
+ fails: drop the flag. See [`oats sync`](../desktop-cli-api.md#oats-sync).
132
+
133
+ - **Schedule doctor distinguishes retained attempts from unknown observations**
134
+ ([#584](https://github.com/awebai/oats/issues/584)). Offline workspace warnings
135
+ describe saved placement exclusions or unverifiable authorization instead
136
+ of promising a reconciliation command that cannot run. Unknown observations
137
+ without an attempt no longer claim execution is blocked pending reconciliation.
138
+ For a local schedule whose retained state doctor cannot vouch for (captured
139
+ execution state, an invalid or mismatched stored definition or ID, unreadable
140
+ lock custody, or invalid local configuration), doctor no longer prints a
141
+ reconcile command and says why instead. This fixes diagnosis only:
142
+ retained-state recovery outside current workspace placement remains
143
+ unsupported, and attempts, locks and slot rules are unchanged.
144
+ - A restart no longer brings back older launch settings from the receipt of
145
+ a start that had already completed
146
+ ([#691](https://github.com/awebai/oats/issues/691)). A start keeps its
147
+ launch receipt, and the next start replayed it over `instance.json` even
148
+ when `instance.json` already recorded that start: an older launch recipe
149
+ (hook env, contributions) and older provider metadata replaced newer ones
150
+ before the launch hooks ran, and a plain `session start` on a running
151
+ instance wrote them before answering `E_SESSION_RUNNING`. Now a receipt for
152
+ a recorded start, on the recorded target, is never applied again. With
153
+ such a receipt, a plain start on a running instance answers
154
+ `E_SESSION_RUNNING` with nothing written and no hook run; a restart, or a
155
+ start after the target is gone, starts from `instance.json` as it is, and
156
+ its new receipt replaces the old one. An interrupted start (its metadata
157
+ write failed) is still adopted as before, with no second launch. A receipt
158
+ that names the recorded start on another, still running target is refused
159
+ as ambiguous (`E_SESSION_UNKNOWN`); the message names that target, and a
160
+ restart once it is stopped clears it. Nothing needs editing by hand. See
161
+ [Start and restart](../desktop-cli-api.md#start-and-restart).
package/docs/schedules.md CHANGED
@@ -430,8 +430,9 @@ you), `launch-failed`, `unknown`, and for wake jobs `delivered`, `started` or
430
430
  `skipped`. The kernel never claims a task succeeded.
431
431
 
432
432
  `unknown` means the launch's side effects are unconfirmed: a command timed out
433
- or answered no envelope, or an attempt was never recorded. The job is skipped
434
- until `oats schedule reconcile <id>`, which adopts only an attributable
433
+ or answered no envelope, or an attempt was never recorded. A job with a
434
+ persisted attempt is skipped until `oats schedule reconcile <id>` (an
435
+ unknown `lastRun` alone does not block it; see below), which adopts only an attributable
435
436
  receipt (a spawn job's instance, named for its minute, or the instance a
436
437
  command's answer named). When nothing is attributable, check the roster and
437
438
  the host by hand, then `reconcile <id> --clear` records `launch-failed` and
@@ -448,13 +449,30 @@ is `! schedule-unresolved: …`; in `--json` it is a `problems[]` item:
448
449
  scheduledFor, startedAt, ageSeconds, holdsSlot, exited, error, remedy, message }
449
450
  ```
450
451
 
451
- `holdsSlot` says whether the job counts against `maxConcurrent`. `remedy` is
452
- `oats schedule reconcile <id>`, with `--clear` for a command or operation
453
- whose effects no named home proves (check the roster and the host by hand
454
- first), and with `--dir <scope>` for another deployment. A warning never
455
- changes doctor's exit status. Workspace command kinds come from the last
456
- saved automations snapshot, without a refresh or an account lookup. Unresolved
457
- workspace state is reported even if its definition is no longer available.
452
+ `holdsSlot` says whether the job counts against `maxConcurrent`. For a local
453
+ schedule whose saved state supports reconciliation, `remedy` names
454
+ `oats schedule reconcile <id>`, with `--clear` for unproven command/operation
455
+ effects (check the roster and host by hand first), and `--dir <scope>` for
456
+ another deployment. Invalid or unsupported saved inputs instead receive a
457
+ warning to preserve state and inspect effects with the deployment owner.
458
+ A warning never changes doctor's exit status.
459
+
460
+ Workspace guidance uses only validated local settings and the saved automation
461
+ snapshot. A known opt-out, missing saved definition, different assigned host or
462
+ absent trust explains why retained-state reconciliation is currently unavailable.
463
+ Missing saved data does not prove remote deletion. Invalid/unreadable inputs
464
+ are reported as unverifiable; even statically eligible placement is **not**
465
+ verified current authorization, because doctor does not check the owner account,
466
+ refresh discovery or access the network. No unconditional executable workspace
467
+ reconcile remedy is printed. Preserve retained state and inspect effects with
468
+ the deployment owner: this diagnostic correction does not add a way to clear
469
+ workspace attempts outside current placement, and that recovery remains
470
+ unsupported. Do not re-enable or retrust a job merely to clear its state.
471
+
472
+ Only a persisted `attempt` blocks that job pending reconciliation. An unknown
473
+ `lastRun` without an attempt is a last observation that an eligible tick may
474
+ re-observe; doctor does not promise that a tick will clear it or launch again.
475
+ Both cases retain their reported age, error and slot facts.
458
476
 
459
477
  Whether an `unknown` job keeps its host slot depends on what is still running:
460
478