@awebai/oats 0.67.1 → 0.68.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -93,11 +93,13 @@ and the rules its tests pin.
93
93
  | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
94
94
  | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
95
95
  | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
96
- | `materialize.mjs` | copying modules into a home and composing it; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
96
+ | `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
97
+ | `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
98
+ | `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
97
99
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
98
100
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
99
101
  | `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`, `inspect --soul --instructions` and `--composed-skills` (its `inScratch` reads the scratch home before it is removed, so the two flags share one materialization) |
100
- | `instance-naming.mjs` | the suggested instance name of `spawn --preview --suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself; driven by `core.mjs` `spawnBody`, after the preview's harness checks, where a suggested name is then placed as `--name` would place it. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
102
+ | `instance-naming.mjs` | the suggested instance name of `spawn --suggest-name` (a preview's or an apply's) and of `oats instance suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself. Two drivers in `core.mjs`, both reusing it unchanged: `spawnBody`, after the spawn's harness checks, where a suggested name is then placed as `--name` would place it (a preview's call within its preflight budget, an apply's within its own 20 s); and `suggestSpawnName`, for a spawn elsewhere, which resolves the launch configuration and executable the way a spawn here would but places nothing and passes a `taken` that is always false. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
101
103
  | `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
102
104
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
103
105
  | `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
@@ -112,7 +114,7 @@ and the rules its tests pin.
112
114
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
113
115
  | `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 |
114
116
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through |
115
- | `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 |
117
+ | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
116
118
  | `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
117
119
  | `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 per home by `oats retire` and `oats instance stop --apply` (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
118
120
  | `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, an exact mode, a failed removal reported, a sync) keeps its own code |
@@ -139,6 +141,43 @@ and the rules its tests pin.
139
141
  | `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
140
142
  | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings, and the plan `oats update` runs with its line that the Desktop goes first ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
141
143
 
144
+ An upgrade records a hook's in-flight marker before spawning it. A resumed
145
+ unknown outcome is durably recorded as uncertain before any retry work,
146
+ because the provider may already have changed host state even when no success
147
+ was recorded. Success or uncertainty makes the act forward-only. Only a
148
+ non-zero result observed and recorded in the same invocation, with no prior
149
+ success or uncertainty, permits rollback of composed bytes. An uncertain hook
150
+ is retried idempotently; a later refusal cannot turn that recovery into a
151
+ rollback.
152
+
153
+ Start and upgrade share the `.oats-start.lock` path through exclusive
154
+ acquisition: start uses `mkdir`, while upgrade creates a regular file with
155
+ `wx`. Both treat `EEXIST` as held. Upgrade takes the lifecycle claim before
156
+ reclaiming an interrupted upgrade's regular-file mutex, including an empty
157
+ file left by a killed opener, and never reclaims a directory. Start never
158
+ reclaims this path. Upgrade releases it only after persisting its final
159
+ invocation receipt.
160
+
161
+ Upgrade compares the home with its independent spawn baseline before it
162
+ changes anything there. A dirty home retains the entire baseline byte for
163
+ byte, so older kernels also recover its edits at retire. A clean home updates
164
+ only `homeFingerprint`; work fingerprints, digest versions, exclusions and
165
+ runtime authority remain as recorded. `retirementHomeChanged` and
166
+ `rebaseUpgradeRetirementBaseline` use retirement's existing comparison and
167
+ exclusions, without changing recovery or copy semantics.
168
+
169
+ The fingerprint helpers accept call-scoped `transientHomePaths`: exact
170
+ relative paths, no globs, each an existing regular file. Upgrade projects out
171
+ only `.oats-start.lock`. This is not a permanent exclusion: a later retire
172
+ hashes any leftover mutex as changed home bytes. The completed receipt is
173
+ published before the success event. A same-key retry deduplicates the event
174
+ and removes staging, without repeating adoption or composition.
175
+
176
+ Baseline replacement uses the existing atomic private-file writer. The
177
+ exclusive-create option still refuses an existing baseline. An interrupted replacement leaves a complete
178
+ old or new baseline, preserving the independent session authority required
179
+ to resume forward recovery.
180
+
142
181
  The schedule registry stores explicit concurrency caps, leaving the schedule
143
182
  cap absent for its effective default of five. `readRegistry()` is a pure,
144
183
  bounded atomic-file snapshot: it takes no lock and writes nothing, projecting
@@ -15,7 +15,7 @@ For each soul, OATS resolves zero or one implementation per slot:
15
15
  | --- | --- | --- |
16
16
  | `knowledge` | [knowledge](layers.md#the-knowledge-contract) | `oats.okf` |
17
17
  | `messaging` | [communication](layers.md#the-communication-contract) | `oats.aweb` |
18
- | `tasks` | [tasks](layers.md#the-tasks-contract) | `oats.jira`, `oats.linear` |
18
+ | `tasks` | [tasks](layers.md#the-tasks-contract) | `oats.aweb-tasks`, `oats.jira`, `oats.linear` |
19
19
 
20
20
  A capability becomes an integration by declaring exactly one `layer` in its
21
21
  manifest. Capabilities without `layer` compose additively.
@@ -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.2.1
44
- oats.aweb: v1.30.0
43
+ oats.okf: v5.3.0
44
+ oats.aweb: v1.31.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -57,7 +57,8 @@ tasks:
57
57
  # souls/support-triager/soul.yaml: opt out of one slot, replace another
58
58
  knowledge: none # empties the slot
59
59
  capabilities:
60
- oats.jira: { from: package } # its manifest says layer: tasks, so it replaces the default
60
+ oats.linear: off # removes the tasks default...
61
+ oats.jira: { from: package } # ...so this one fills the slot (two would be E_SLOT_CONFLICT)
61
62
  ```
62
63
 
63
64
  - A soul's slot key is either `none` or that slot's payload (settings for the
@@ -80,6 +81,7 @@ operations in full.
80
81
  | --- | --- | --- | --- |
81
82
  | `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` for Git-backed consultation, `git` and `gh` for proposal/review PRs; ordinary kernel/harness selection, no provider harvest-runtime setting | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
82
83
  | `messaging` | `oats.aweb` | the `aw` CLI at 1.36.33 or later; for channel delivery, `@awebai/pi` in pi or the `aweb-channel` plugin in Claude Code; host-only `root`, `roots` and `residents` in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
84
+ | `tasks` | `oats.aweb-tasks` | the `aw` CLI at 1.36.33 or later, and `oats.aweb` as the soul's messaging: tasks act as the instance's own oats.aweb identity in its default team; nothing in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
83
85
  | `tasks` | `oats.jira` | `acli`, authenticated to the Jira site; `site` and `project` in the soul's `tasks:` payload or `settings.oats.jira` | [awebai/oats-jira](https://github.com/awebai/oats-jira) |
84
86
  | `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
85
87
 
@@ -91,6 +93,16 @@ operations in full.
91
93
  soul-only `knowledge: { harvest: off }` forbids harvest while retaining
92
94
  consultation. No host switch or automatic transcript/retire capture remains;
93
95
  `knowledge-maintainer` reviews the resulting Git PRs.
96
+ - **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
97
+ tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
98
+ identity in its default team. **An existing workspace opts in** by pinning
99
+ `oats.aweb: v1.31.0` (or later), adding
100
+ `tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
101
+ `oats sync`. Only new spawns get it. A soul that names its own tasks
102
+ provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
103
+ fails with `E_SLOT_CONFLICT`: to keep its own, it adds
104
+ `oats.aweb-tasks: off` to its `capabilities:`. A soul opts out of tasks
105
+ entirely with `tasks: none`.
94
106
  - **`oats.aweb`** mints a messaging identity for each instance at spawn and
95
107
  removes it at retire, contributes the aweb messaging skills, and wires the
96
108
  channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
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.2.1** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.3.0** (OATS **>=0.49.0**). 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 |
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
25
25
  ```yaml
26
26
  # oats-workspace.yaml (excerpt)
27
27
  packages:
28
- oats.okf: v5.2.1
28
+ oats.okf: v5.3.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,15 +50,18 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. For 5.2.1, OATS >=0.49.0 remains required:
53
+ just editing a version line. For 5.3.0, OATS >=0.49.0 remains required:
54
54
  that kernel first supports the public source-event lookup after retirement.
55
55
 
56
- **Upgrade:** pin `oats.okf: v5.2.1` and run `oats sync`. Only new spawns get
56
+ **Upgrade:** pin `oats.okf: v5.3.0` and run `oats sync`. Only new spawns get
57
57
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
58
  homes keep their copied provider even after a session restart. Deployments
59
59
  whose briefings never mentioned harvesting now get knowledge proposals at
60
- eligible checkpoints; souls not ready for this must declare
60
+ the harvest checkpoints; souls not ready for this must declare
61
61
  `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
62
+ From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the checkpoint
63
+ line in `log.md`, drops the available-memory gate, and has the proposer name
64
+ each harvester (`--name`, below).
62
65
 
63
66
  ### Bindings document
64
67
 
@@ -170,13 +173,19 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
170
173
  means no harvest, and `unknown` or an error means stop and report, never
171
174
  infer permission or edit the record. Working instances never write
172
175
  accepted knowledge themselves.
173
- 2. **Propose only at a finished task or PR hand-over.** First update state,
174
- log and relevant notes. Apply `knowledge-theory` and search accepted
175
- knowledge (`oats okf search`, then `cat`): already accepted with nothing
176
- to add means no proposal. Most checkpoints propose nothing. Make at most
177
- **one proposal for that completed unit of work**; handing over its PR and
178
- closing the same task are not two opportunities. Never launch per commit,
179
- per decision, per review round or merely because a PR opened.
176
+ 2. **Propose at each harvest checkpoint.** The checkpoints are a PR handed
177
+ over for review and a finished task. In a long-lived role whose task
178
+ never finishes (a maintainer, an expert holding an area, a support desk),
179
+ they also include a feature ready, a release or deploy shipped, and a
180
+ direction decision taken with the human. A commit, a review round, a new
181
+ head of the same PR and each decision made while working are not
182
+ checkpoints: those are captured in `notes/`, and the next checkpoint
183
+ carries them. First update state, log and relevant notes. Apply
184
+ `knowledge-theory` and search accepted knowledge (`oats okf search`, then
185
+ `cat`): already accepted with nothing to add means no proposal. Make **one
186
+ proposal per checkpoint, carrying only what no earlier proposal carried**,
187
+ and record every checkpoint in `log.md`, either with its proposal and
188
+ harvester or with `nothing to propose` and the reason.
180
189
 
181
190
  Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
182
191
  home: What (one claim per concept), Why, Evidence (observations, dates,
@@ -187,22 +196,25 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
187
196
  nodes; a lesson for a node the soul only reads is named in one line in its
188
197
  hand-back for that node's owner.
189
198
 
190
- **Before spawning:** one harvester at a time per instance. Record its
191
- returned name and proposal in log.md, and do not spawn another while
192
- `oats status` still lists the last one. Check available memory immediately
193
- before spawning: on Linux, `free -g` must show at least 8 GB available;
194
- elsewhere use the host's documented check. If availability cannot be
195
- established, is below the floor, or the host is under memory pressure,
196
- defer. These are instructions, not a scheduler or a memory reservation.
197
- Keep deferred proposals/notes and record the reason and waiting claims in
198
- STATE.md, log.md and the hand-back. Reconsider at a natural task boundary,
199
- never by polling, sleeping or stopping other instances to make room.
200
-
201
- From instance home, preview and then apply the skill's command when the
202
- gates permit it:
199
+ **Before spawning:** one harvester at a time per instance. Do not spawn
200
+ another while `oats status` still lists the last one: keep the proposal
201
+ pending in STATE.md and log.md, add the next checkpoint's claims to it,
202
+ and launch it at that checkpoint once the last harvester is gone. Never
203
+ poll, sleep or stop other instances to make room. (5.3.0 removed the
204
+ 5.2.x available-memory gate.)
205
+
206
+ **The proposer names its harvester.** For each new proposal,
207
+ **okf-propose** prints a fresh name: up to 21 characters of the source
208
+ instance's name, a dash, a random UUID without dashes, and `-harvester`,
209
+ 64 characters at most (the kernel's and aweb's alias limit). The proposer
210
+ records it with the proposal in log.md before the preview, checks that
211
+ `oats status` doesn't list it, and uses it unchanged in both the preview and
212
+ the apply. Never leave the name to the kernel's numbered default: a retired
213
+ harvester's messaging alias can stay occupied with no instance listed, and
214
+ a numbered name can land on it.
203
215
 
204
216
  ```sh
205
- oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
217
+ oats spawn oats.okf/knowledge-harvester --name <harvester-name> --task-file <proposal> --relation unrelated
206
218
  ```
207
219
 
208
220
  Never combine `--relation unrelated` with `--relative-to`, or override
@@ -214,7 +226,12 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
214
226
  evidence before capture, so do not dispose of it before capture.
215
227
  Missing source authority never permits inventing it.
216
228
 
217
- A refused or uncertain spawn is reported, not retried in a loop. If the
229
+ A refused or uncertain spawn is reported, not retried in a loop. On
230
+ `E_INSTANCE_NAME_TAKEN`, the proposer stops and reports the name and the
231
+ refusal: no `--purpose`, no counter, no new UUID in a retry. A messaging
232
+ identity failure (for example a stale certificate on the alias) is
233
+ reported to the operator; the proposer never removes certificates or
234
+ renames around it. If the
218
235
  last harvester is still listed at hand-back, name it and the claims still
219
236
  waiting; do not wait for it or spawn around it. A harvester retained after
220
237
  a publication failure stays listed and holds back later proposals. Once
package/docs/layers.md CHANGED
@@ -46,8 +46,8 @@ not proof that an agent is enrolled. The official provider is `oats.aweb`.
46
46
  ### The tasks contract
47
47
 
48
48
  The tasks capability owns assignment, claims, status, blockers and handoff.
49
- `oats.jira` and `oats.linear` are the official providers. Messaging is
50
- conversation, not task state.
49
+ The official providers are `oats.aweb-tasks` (from the `oats.aweb` package),
50
+ `oats.jira` and `oats.linear`. Messaging is conversation, not task state.
51
51
 
52
52
  ## What the kernel does not own
53
53
 
@@ -9,10 +9,10 @@ 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.13.5` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.30.0` | `oats.aweb` (messaging) | |
15
- | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.14.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.31.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
+ | `oats.engineering` | `v1.13.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` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -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.2.1`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.3.0`); `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.2.1 # bare version → the official catalog
47
+ oats.okf: v5.3.0 # 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.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.3.0`, `5.3.0`, `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.2.1` or `oats-framework/v1.13.5`) and the payload path. An id
54
+ convention (`v5.3.0` or `oats-framework/v1.14.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.13.5
78
- oats.okf: v5.2.1
79
- oats.aweb: v1.30.0
77
+ oats.framework: v1.14.1
78
+ oats.okf: v5.3.0
79
+ oats.aweb: v1.31.0
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.2.1 ✓ (@ 72e989b9)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.3.0 ✓ (@ 79befeaf)
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.30.0 # a catalog version
137
+ oats package add oats.aweb v1.31.0 # 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.2.1",
164
- "commit": "72e989b926e8ac1b7b912785beff396d1fc41cbb",
163
+ "version": "5.3.0",
164
+ "commit": "79befeaf98e04a5a46896ddad8ac3333ee90bce3",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.5", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.3.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.14.1", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.5`
362
- resolves to tag `oats-framework/v1.13.5`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.14.1`
362
+ resolves to tag `oats-framework/v1.14.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.