@awebai/oats 0.49.0 → 0.51.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.
@@ -346,8 +346,9 @@ positive whole number of milliseconds replaces the fixed 30-minute timeout of
346
346
  tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
347
347
  10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
348
348
  the kernel read a process's start time with `ps`, as on a host without
349
- `/proc` (macOS), on a host that has it. A launch configuration cannot set
350
- any of them. Do not set them in a deployment.
349
+ `/proc` (macOS), on a host that has it; an absolute path instead runs that
350
+ file as `ps`, directly and in the same fixed environment; any other value
351
+ reads no start at all. A launch configuration cannot set any of them. Do not set them in a deployment.
351
352
 
352
353
  **An instance creates an agents' session or window without its own
353
354
  environment.** Nothing of an instance's environment reaches a server or a
@@ -486,12 +487,33 @@ tmux -L oats kill-server # replace it: ends EVERY sessio
486
487
  - `-L oats` reaches the server of the environment you type it in
487
488
  (`TMUX_TMPDIR`). For the server an instance is on, use the socket from its
488
489
  row in `oats status --json`: `tmux -S <socket> …`.
489
- - A tmux server whose socket file is missing or does not answer reads as not
490
- reachable, which is not proof that it exited: status, start and stop read
491
- that state as stopped
492
- ([#624](https://github.com/awebai/oats/issues/624)). That is an existing
493
- limit of every tmux server OATS uses, not of the `oats` server in
494
- particular.
490
+ - <a id="missing-socket"></a>A tmux server whose socket file is missing
491
+ (`error connecting to <socket> (No such file or directory)`) is not proof
492
+ that it exited: a server outlives its removed socket file (a
493
+ temporary-files cleaner, a removed socket directory), and tmux gives the
494
+ same words after a reboot, when the server is gone. So OATS reads it as
495
+ stopped only when no process works in the instance's home
496
+ ([the process scan](souls-and-instances.md#the-process-scan)): the row is
497
+ not running and a start creates the window again, as after a reboot. When
498
+ a process works there, or the scan cannot run, the state is not
499
+ established: `oats status` shows the row `running: null` with
500
+ `runtimeState: "unreachable"` and a `runtimeError` that names the
501
+ processes (pid and program, at most five) or the scan's error;
502
+ `oats session start` and `restart` refuse with `E_SESSION_UNKNOWN` and
503
+ create no server at that path; `oats instance stop` refuses with
504
+ `E_SESSION_UNAVAILABLE`, never "already idle". tmux recreates a removed
505
+ socket file when its server process receives `SIGUSR1`
506
+ (`kill -USR1 <pid of that tmux server>`); OATS names that and never sends
507
+ it. Any process working in the
508
+ home counts, a shell left in that directory included, as for retire: the
509
+ message names its pid and program, so end it or leave the directory. A
510
+ socket file no server listens on (`no server running on <socket>`) is
511
+ definitive: stopped, with no scan
512
+ ([#624](https://github.com/awebai/oats/issues/624)). This holds for every
513
+ tmux server OATS reads, not only the `oats` server, and for a home that
514
+ records no socket and reads your default server. A home that records
515
+ neither a socket nor a launch (`--no-launch`) reads as not running
516
+ whatever works in it.
495
517
 
496
518
  <a id="existing-instances"></a>
497
519
  #### Existing instances
@@ -582,6 +604,8 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
582
604
  pane is reused in place. A missing window, or one whose tmux server cannot
583
605
  be reached, is created again on the OATS tmux server, and the start warns when that is
584
606
  not the server the home recorded ([Existing instances](#existing-instances)).
607
+ A server whose socket file is missing counts as gone only when no process
608
+ works in the home ([missing socket file](#missing-socket)).
585
609
  - A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
586
610
  starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
587
611
  is refused (`E_INSTANCE_RETIRING`).
@@ -743,7 +767,10 @@ children and uncommitted work, with a `planRevision`. `--apply --plan-revision
743
767
  <rev> --idempotency-key <key>` stops the instance and its recorded children
744
768
  first (`--no-recursive` stops only the instance), with the same bounded
745
769
  SIGTERM. Restart the instance later with `oats session start` or
746
- `oats session restart`.
770
+ `oats session restart`. An instance whose recorded tmux socket file is
771
+ missing while a process works in its home, or the process scan cannot run,
772
+ is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
773
+ stopped ([missing socket file](#missing-socket)).
747
774
 
748
775
  ### Inspect, input and attach
749
776
 
@@ -751,6 +778,7 @@ SIGTERM. Restart the instance later with `oats session start` or
751
778
  oats session inspect --home /abs/home --json
752
779
  oats session input --home /abs/home --text-file message.txt --json
753
780
  oats session attach --home /abs/home
781
+ oats session attach --home /abs/home --detach-key 'C-\'
754
782
  ```
755
783
 
756
784
  - **inspect** reports `backend`, `present` and `state`: `unknown` for a live
@@ -800,6 +828,89 @@ oats session attach --home /abs/home
800
828
  session linked to the agent's window alone.
801
829
  Closing the viewer leaves the agent running.
802
830
 
831
+ **Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
832
+ every key goes to the agent, the tmux prefix included. Close the terminal.
833
+ With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
834
+ `session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
835
+ viewer's client. The agent's window and every other viewer are untouched.
836
+ The key is taken from the agent's input: the agent never receives it while
837
+ this viewer is attached. A keyed viewer reads a tmux key table of its own,
838
+ named as its temporary session and removed with it, so the key is bound
839
+ for that viewer alone. Check the feature in `oats version --json` before
840
+ passing the flag: a kernel without it ignores the flag and opens a viewer
841
+ with no exit.
842
+
843
+ The key is one of these, spelled exactly (case-sensitive):
844
+
845
+ ```
846
+ key = control / meta / function
847
+ control = "C-" ( "a"-"g" / "j"-"l" / "n"-"z" / "\" / "]" / "^" / "_" )
848
+ meta = "M-" ( "a"-"z" / "0"-"9" )
849
+ function = [ "C-" / "M-" / "S-" ] "F" ( "1" … "12" )
850
+ ```
851
+
852
+ Anything else is `E_BAD_ARGS`, before any tmux or ssh call: a missing
853
+ value, a plain character, `C-i` and `C-m` (Tab and Enter on tmux before
854
+ 3.5), `C-h` (the byte, 0x08, that many terminals send for Ctrl+Backspace
855
+ and some for Backspace, so the name is not one key everywhere), `C-[`
856
+ (Escape), `M-[`, `M-]`, `M-\`, `M-O` and the other ESC + C1 introducers (a
857
+ terminal reply can arrive as that key), `Any`, mouse key names, two keys,
858
+ upper case, and anything with a space, `;` or a control character. The
859
+ kernel does not judge whether a harness reads the key: that is the
860
+ caller's choice.
861
+
862
+ **While the pane is scrolled back.** The viewer's wheel and drag bindings
863
+ put the pane in tmux's copy mode, and there copy mode's key table is read
864
+ before the viewer's. A detach key that copy mode binds acts in copy mode
865
+ and does not detach; it detaches once the mode is left (`q`, or scrolling
866
+ back to the bottom). The grammar does not exclude those keys. The
867
+ copy-mode tables are the tmux server's, shared by every session and
868
+ changed by the operator's `~/.tmux.conf`, so no grammar can promise a key
869
+ is free there, and the kernel never binds a detach key in a table other
870
+ sessions read. With tmux's default tables (3.7c), 35 of the 111 keys are
871
+ taken in emacs or vi copy mode (for example `C-e`, `C-c`, `M-w`, `C-u`);
872
+ `C-\` and `F12` are bound in neither and detach from copy mode. Detaching
873
+ while scrolled back leaves the agent's pane in copy mode for the next
874
+ viewer, as closing a viewer mid-scroll does.
875
+
876
+ **The suggested key is `C-\`**, written `--detach-key 'C-\'` (quoted: an
877
+ unquoted trailing backslash continues the line). The kernel fixes no key.
878
+ What was checked:
879
+
880
+ - It has no default binding in Claude Code 2.1.288 (which refuses to let
881
+ a user bind it: "terminal quit signal"), Codex CLI 0.160.0 or pi 1.0.2.
882
+ It is unbound in bash 5.3 (`bind -p`) and in zsh's and fish's documented
883
+ defaults. It is the default detach key of dtach and abduco.
884
+ - A viewer with this key gives up: in a fallback shell, the tty's QUIT (no
885
+ SIGQUIT from the keyboard); in vim and nvim, the `C-\ C-n` prefix; in
886
+ nano, Replace (also on `M-r`).
887
+ - On a layout where `\` needs AltGr, use `F12`: it has no default binding
888
+ in the same three harnesses, bash, nvim or less. Some terminals and
889
+ laptops keep F12 for themselves.
890
+ - `C-]`, `C-_`, `C-g`, `C-t` and `C-b` are each bound by all three
891
+ harnesses.
892
+
893
+ **Exit status.**
894
+
895
+ | How the command ended | Status |
896
+ |---|---|
897
+ | Left by the detach key (the agent keeps running) | 20 |
898
+ | The viewer ended without the key: the agent's window ended, or `oats` itself was stopped by SIGHUP, SIGTERM or SIGINT and closed the viewer | 0 |
899
+ | A refusal (bad arguments, not launched, session gone), or tmux failing under the viewer (its server exited) | 1 |
900
+
901
+ 20 is answered only when the key's own binding ran, and only by a kernel
902
+ with the feature. No status an existing caller sees changes meaning. 20 is
903
+ nonzero, so `set -e`, an `&&` chain and tmux's `remain-on-exit failed`
904
+ treat a leave by the key as a failure. The routed form (`--server`) relays
905
+ these statuses and adds ssh's own 255 ([servers.md](servers.md#run-there)).
906
+
907
+ With `--detach-key`, `oats` handles SIGQUIT. `C-\` is also the terminal's
908
+ QUIT character: pressed before the viewer has the terminal, or again once
909
+ the viewer has given it back, it would otherwise end `oats` with status 131
910
+ and leave the viewer's session and key table on the tmux server. A QUIT
911
+ that arrives before the key was used stops the attach, with status 1;
912
+ after a leave by the key it changes nothing, and the status is 20.
913
+
803
914
  ### Attachments
804
915
 
805
916
  `oats session upload --file <local> --home <abs>` copies a file into
@@ -58,16 +58,20 @@ published to npm. Its developer docs are in
58
58
  | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
59
59
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
60
60
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
61
+ | `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 |
62
+ | `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 |
61
63
  | `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 |
62
64
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
63
65
  | `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 |
64
66
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
65
67
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
68
+ | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`) and by `oats retire` per home (`core.mjs`, `retireInstance`) |
66
69
  | `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL |
67
70
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
68
71
  | `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)) |
69
72
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
70
73
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
74
+ | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
71
75
  | `servers.mjs` | routing commands to a registered server |
72
76
  | `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
73
77
  | `launch-prompt-completion.mjs` | pure, qualified post-answer completion reporting using a finite bottom input/footer table and 21 question markers; never an input matcher |
@@ -384,6 +388,13 @@ and acts on every existing session through its recorded socket
384
388
  `list-windows`, `new-window` (a window id) and `set-option`.
385
389
  - A server a test starts is killed by its socket, never by name and never
386
390
  with a bare `tmux kill-server`.
391
+ - A test that needs a terminal (an attached tmux client, a key press) runs
392
+ the command in a pane of a second private server and types at that pane
393
+ with `send-keys`; the pane's shell records the exit status
394
+ (`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
395
+ bytes a terminal sends (`send-keys -l`). A pane program that must show the
396
+ keys it reads puts its terminal in raw mode first: in cooked mode a control
397
+ byte is a signal or an edit, not input.
387
398
 
388
399
  Nor does a test depend on where or how the suite runs:
389
400
 
@@ -408,7 +419,8 @@ A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
408
419
  unit, a live operator tmux server and Apple git, run from inside an instance
409
420
  home. A pull request that could not be run there says so in its hand-over. The
410
421
  suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
411
- with `require`), git ≥ 2.45, lsof and tmux (awebai/oats#783). The
422
+ with `require`), git ≥ 2.45, tmux, and lsof where `/proc` cannot be read
423
+ (awebai/oats#783, #625). The
412
424
  helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
413
425
  shared fixture (`v2Deployment`) applies all of it, so a suite built on it
414
426
  inherits it (awebai/oats#816):
@@ -438,13 +450,21 @@ inherits it (awebai/oats#816):
438
450
  no host service manager is reachable at all.
439
451
  - **No leftover processes.** The fixture's cleanup fails when a process still
440
452
  works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
441
- `processesInHome` (lsof). It catches a hook's or a CLI's grandchild that
453
+ `processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
442
454
  outlived the test, once its parent has exited. The scan leaves out its caller
443
455
  and the caller's direct children, so a test's own forgotten child is not
444
456
  found here: that is the test's bug to fix. A process still exiting gets 2 s.
445
457
  Nothing is killed, the base is removed, and the failure names each pid and
446
458
  command. A test that leaves a process running on purpose (a group the kernel
447
- must not signal) ends it itself before that check, on failure too: node:test
448
- runs `t.after` hooks in the order they were added, so its own hook added
449
- after `t.after(fx.cleanup)` runs too late (`test/worktree-event.test.mjs`
450
- ends them inside its cleanup hook, ahead of `fx.cleanup`).
459
+ must not signal) ends it itself before that check, on failure too, through
460
+ `fx.beforeCleanup(fn)`: the cleanup runs those synchronous functions first,
461
+ in order, and still runs when one throws. Never end it with a later `t.after`: node:test
462
+ runs `t.after` hooks in the order they were added, so a hook added after the
463
+ fixture's runs after the check (`test/worktree-event.test.mjs`).
464
+ - **Cleanup even when a test fails.** Pass the test context,
465
+ `v2Deployment({ t })`: the fixture registers its own cleanup with
466
+ `t.after` when it is created, so a test that throws, rejects or times out
467
+ still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
468
+ and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
469
+ `t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
470
+ built removes its base itself.
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.0.0
44
- oats.aweb: v1.21.1
43
+ oats.okf: v5.0.1
44
+ oats.aweb: v1.24.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.0**. Provider implementation and
9
+ This is the operator guide for **oats.okf 5.0.1**. Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
23
23
  ```yaml
24
24
  # oats-workspace.yaml (excerpt)
25
25
  packages:
26
- oats.okf: v5.0.0
26
+ oats.okf: v5.0.1
27
27
  defaults:
28
28
  knowledge: { oats.okf: { from: package } }
29
29
  stores:
@@ -105,7 +105,8 @@ explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
105
105
  5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
106
106
  removed keys still refuse and name the fix. The harvester has no provider
107
107
  runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
108
- selection and retires after its handoff.
108
+ selection and retires after successful handoff or nothing promotable. A
109
+ publication failure retains its live home; see [the flow](#the-flow).
109
110
 
110
111
  ## The soul's okf.json
111
112
 
@@ -165,10 +166,22 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
165
166
  notes, edits only owned nodes in its own Git checkout, validates the
166
167
  **whole base**, and creates a normal `okf-harvest`-labelled PR with v2
167
168
  provenance. Proposal text is data written with the native file tool into
168
- commit-message/PR-body files, never shell command text. It reports the PR
169
- and retires rather than waiting for acceptance. If source authority is
170
- unavailable it stops and reports; a consistent instance/soul pair alone
171
- does not prove proposer authorship.
169
+ commit-message/PR-body files, never shell command text. A publication ref
170
+ is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
171
+ name in it; Git validates the full ref and the push must create a new
172
+ ref, never update or adopt an existing one. Source identity stays in
173
+ commit text and PR provenance. After all PRs are open (or nothing is
174
+ promotable), it hands over and retires rather than waiting for acceptance.
175
+ If source authority is unavailable it stops and reports; a consistent
176
+ instance/soul pair alone does not prove proposer authorship.
177
+ **On any publication failure it does not retire:** it keeps the live home,
178
+ clone/any commit, exact error and commit/PR text locations, and notifies
179
+ the source through existing messaging when reachable. Missing or failed
180
+ messaging does not hide the original error or permit retirement. Existing
181
+ attention may expose the blocked home where supported. No automatic
182
+ retries, new recipient or maintainer preflight; a maintainer exists only
183
+ for a labelled PR. A gh error can leave remote effects, so partial or
184
+ uncertain publication is not completion or permission to clean up.
172
185
  4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
173
186
  Human-accepted decisions are not silently superseded; the review path
174
187
  keeps its human gate. A PR is not accepted knowledge until merged.
@@ -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.8.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.0.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.23.2` | `oats.aweb` (messaging) | |
12
+ | `oats.framework` | `oats-framework/v1.9.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.24.1` | `oats.aweb` (messaging) | |
15
15
  | `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.0.0`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.0.1`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.0.0 # bare version → the official catalog
47
+ oats.okf: v5.0.1 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.0.0`, `5.0.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.0.1`, `5.0.1`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.0.0` or `oats-framework/v1.8.0`) and the payload path. An id
54
+ convention (`v5.0.1` or `oats-framework/v1.9.1`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.8.0
78
- oats.okf: v5.0.0
79
- oats.aweb: v1.23.2
77
+ oats.framework: v1.9.1
78
+ oats.okf: v5.0.1
79
+ oats.aweb: v1.24.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.0 ✓ (@ 12db7749)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.1 ✓ (@ 96b28d5c)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.23.2 # a catalog version
137
+ oats package add oats.aweb v1.24.1 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.0.0",
164
- "commit": "12db77492d92154099e7f1aad60a98b1d47f6631",
163
+ "version": "5.0.1",
164
+ "commit": "96b28d5cd4f01e48ed50d8e999e8715749a99e87",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -290,6 +290,20 @@ overrides it; a workspace trigger made `from:` it shows its file header's
290
290
  description, else the template's. A kernel before 0.43.0 refuses the key, so
291
291
  a package whose template sets it needs `compatibility.oats: ">=0.43.0"`.
292
292
 
293
+ A template may name a capability's trigger source (feature
294
+ `trigger-sources`): its
295
+ `definition.on` is `{ source: "<capability>:<source>", params?, events,
296
+ poll? }`, and a parameter's `path` may point into `on.params` (for example
297
+ `on.params.prefix`). `add --from` checks what it means against the soul it
298
+ spawns, as for any capability-source trigger
299
+ ([schedules.md](schedules.md#capability-sources)). A package does **not**
300
+ raise `compatibility.oats` for such a template: a template is read only by
301
+ `add --from`, so a kernel without feature `trigger-sources` refuses that one
302
+ `add --from` (`E_TRIGGER_INVALID` on `on.source`, or on `on.params` when the
303
+ template sets it), reports a workspace trigger made from it as a problem of
304
+ its snapshot, and uses the package's capabilities and souls as before. A
305
+ floor would refuse them all on every older host.
306
+
293
307
  ## Compatibility floors
294
308
 
295
309
  A soul may state floors on package versions — constraints, not sources:
@@ -338,12 +352,12 @@ A soul that names one of the package's capabilities with
338
352
  {
339
353
  "policy": "docs/official-catalog.md",
340
354
  "packages": {
341
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.0", "path": "oats-package" },
342
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.8.0", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.1", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.1", "path": "oats-package" }
343
357
  }
344
358
  }
345
359
  ```
346
360
 
347
- `ref` carries the tag convention: a workspace's `oats.framework: v1.8.0`
348
- resolves to tag `oats-framework/v1.8.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.9.1`
362
+ resolves to tag `oats-framework/v1.9.1`. Resolving through the catalog never
349
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -216,3 +216,44 @@ re-checks a published inventory against the source and its origin; it attests
216
216
  what the remote advertised when queried, so released tags must never move.
217
217
  `--generate --source <clone>` captures a working tree for development and
218
218
  always records `release.status: pending`.
219
+
220
+ ## Releasing `oats.framework`
221
+
222
+ The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
223
+ `oats.support`, `oats.knowledge-theory`) is not published by `release.yml` or
224
+ by this lane. A deployment takes it from this repository at the tag
225
+ `oats-framework/v<version>`, through the catalog ref or its workspace pin. A
226
+ skill changed under `oats-package/` therefore reaches deployments only when
227
+ that tag moves, whatever kernel version carried the change.
228
+
229
+ **A kernel release whose pull requests touched `oats-package/` ships a
230
+ framework release with it.** To see whether one is owed:
231
+
232
+ ```bash
233
+ git diff --stat "$(git describe --tags --abbrev=0 --match 'oats-framework/v*' origin/main)" origin/main -- oats-package
234
+ ```
235
+
236
+ When the diff is not empty:
237
+
238
+ 1. **The framework prep PR.** Bump `version` in the `oats.json` of each
239
+ changed capability and in `oats-package/oats-package.json`, and add the
240
+ release-notes entry. Read the skill lines added since the last tag: a
241
+ command or behaviour that an older kernel the capability still admits does
242
+ not have names the version it starts in. Guidance text alone does not
243
+ raise a capability's `compatibility.oats`.
244
+ 2. **The tag.** After the PR merges, put the annotated tag
245
+ `oats-framework/v<version>` on its merge commit and push it. No workflow
246
+ runs on this tag.
247
+ 3. **The pin**, in the kernel release-prep PR: `package-catalog.json`
248
+ (`ref`), `oats-workspace.yaml`, and the version literals in
249
+ `docs/official-catalog.md`, `docs/packages.md`, `docs/workspaces.md`,
250
+ `skills/oats-getting-started/SKILL.md` and
251
+ `test/release-packaging.test.mjs`. The pin does not ride the first PR:
252
+ the tag needs the bumped manifest on `main` first, and CI reads the
253
+ catalog's ref from the remote. Two tests in
254
+ `test/hook-events-forward-tolerant.test.mjs` sync a deployment that takes
255
+ the official catalog's packages, so the pin's CI fails with
256
+ `E_REMOTE_UNREADABLE` until the tag is pushed. (The clean-room smoke does
257
+ not read it: it tags its own copy of `oats-package/`.) A green CI proves
258
+ that the tag exists, not which commit it names: the pin's reviewer
259
+ confirms on the remote that it names the first PR's merge commit.