@awebai/oats 0.48.0 → 0.49.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 (41) hide show
  1. package/bin/oats.mjs +226 -14
  2. package/docs/capabilities.md +256 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +6 -0
  5. package/docs/desktop-cli-api.md +368 -31
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +17 -2
  8. package/docs/implementation.md +62 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +2 -2
  12. package/docs/packages.md +8 -8
  13. package/docs/release-notes/v0.49.0.md +770 -0
  14. package/docs/schedules.md +62 -39
  15. package/docs/servers.md +7 -0
  16. package/docs/souls-and-instances.md +381 -53
  17. package/docs/workspaces.md +2 -2
  18. package/injects/work-checkout.md +17 -11
  19. package/injects/work-worktree.md +19 -13
  20. package/lib/capability-contract.mjs +100 -11
  21. package/lib/capability-show.mjs +5 -2
  22. package/lib/core.mjs +1109 -321
  23. package/lib/instance-events.mjs +6 -3
  24. package/lib/instance-git.mjs +11 -5
  25. package/lib/instance-inspect.mjs +14 -3
  26. package/lib/instance-lifecycle.mjs +106 -16
  27. package/lib/instance-resolution.mjs +15 -3
  28. package/lib/launch-prompt-policy.mjs +17 -3
  29. package/lib/packages.mjs +1 -0
  30. package/lib/real-path.mjs +27 -0
  31. package/lib/resolve.mjs +4 -4
  32. package/lib/retire-output.mjs +6 -1
  33. package/lib/schedule.mjs +1 -0
  34. package/lib/servers.mjs +32 -6
  35. package/lib/tree-copy.mjs +18 -7
  36. package/lib/triggers.mjs +201 -65
  37. package/lib/workspace.mjs +20 -5
  38. package/lib/worktree-hooks.mjs +392 -0
  39. package/lib/worktree.mjs +655 -0
  40. package/package-catalog.json +1 -1
  41. package/package.json +1 -1
@@ -94,15 +94,49 @@ A self-contained package has an `oats.json`:
94
94
  slot.
95
95
  - `skills` entries can be skill directories or roots containing skills.
96
96
  - `inject` is optional instance instruction Markdown.
97
- - The hooks are `spawn`, `launch` and `retire`. A hook is a
97
+ - The hooks are `spawn`, `launch`, `retire` and `worktree`
98
+ ([The worktree event](#the-worktree-event)). A hook is a
98
99
  command string, or `{ command, required }`. `required: true` is valid **only
99
- on `spawn`**: the hook's failure then fails the spawn and rolls it back,
100
+ on `spawn` and `worktree`**: a required spawn hook's failure fails the spawn
101
+ and rolls it back,
100
102
  instead of producing an instance whose capability never configured itself —
101
103
  an aweb identity that could not be minted leaves an agent believing it can be
102
- woken by mail. Every other hook stays best-effort and only warns, so advisory
104
+ woken by mail. A required `worktree` hook's failure fails the spawn the same
105
+ way, or removes the tree `oats worktree add` made. Every other hook stays
106
+ best-effort and only warns, so advisory
103
107
  work never becomes a spawn blocker. `launch` and `retire` cannot be
104
108
  required: they run outside a spawn transaction, so there is no moment to
105
109
  enforce them. A `soul-scaffold` hook is tolerated and ignored.
110
+ - An **event this kernel does not run** (a newer kernel's) is accepted from
111
+ 0.49.0 on, so a capability that adopts a new event keeps composing on an
112
+ older host. Declared as a command string, `{ command }` or
113
+ `{ command, required: false }`, it is ignored and never runs, and the
114
+ capability carries the warning `hook-event-unsupported`: `capability <id>
115
+ declares hook "<event>", which this kernel does not run`. Declared
116
+ `required: true`, it is refused (`declares unsupported hook`), because
117
+ skipping a hook its author declared essential would fail open. The
118
+ tolerance covers the event's name only: its declaration is checked as for a
119
+ known event (a non-empty command, no unknown keys, a boolean `required`, a
120
+ script inside the capability), and a malformed one is refused. It helps
121
+ from 0.49.0 on only: a kernel before 0.49.0 refuses every unknown event, so
122
+ a capability that must load there declares only the events it runs.
123
+ - The warning is `{code: "hook-event-unsupported", capability, path,
124
+ message}`. It appears in `oats sync` and `oats workspace status`, `oats
125
+ capabilities show`, `oats inspect`, `oats readiness` and `oats doctor` (in
126
+ their `warnings`), and as its message in the `warnings` strings of `oats
127
+ spawn --preview` and `oats spawn` (clipped to fit their receipt), in JSON and in text
128
+ ([desktop-cli-api.md](desktop-cli-api.md#capability-warnings-hook-event-unsupported-oats-0490)).
129
+ `path` names the manifest that was read, in one of two forms, never an
130
+ absolute host path:
131
+
132
+ | Read from | `path` | Commands |
133
+ |---|---|---|
134
+ | the workspace (a member's or a package's manifest) | `<repoKey>:<dir>/oats.json#/hooks/<event>`, or `package:<id>:<dir>/oats.json#/hooks/<event>`; `<dir>` relative to the repository | sync, workspace status, capabilities show, inspect and readiness `--soul`, doctor, spawn |
135
+ | an instance home's module copy | `.oats/modules/<name>/oats.json#/hooks/<event>`, relative to the home | inspect and readiness `--home` |
136
+
137
+ Doctor without `--soul` reads every member and locked package capability
138
+ from this machine's cache only. What the cache cannot answer is reported as
139
+ unchecked (`hook-events-unchecked` in its information), never as no warning.
106
140
  - A capability declaring a **required** spawn hook should declare a `retire` hook
107
141
  too. Without one, OATS has no way to undo what the spawn hook did and no way to
108
142
  know whether it did anything, so a failure quarantines the home rather than
@@ -118,7 +152,8 @@ A self-contained package has an `oats.json`:
118
152
  `oats status` reports it as retained state rather than a live instance, and
119
153
  `oats retire <instance>` retries the cleanup — re-running the retire hooks and
120
154
  the worktree removal, verifying both, and verifying (never deleting) the
121
- branch: no retire deletes a branch. While the branch the failed spawn created
155
+ branch: no retire deletes a branch, with one exception, a spawn killed while
156
+ its `worktree` hooks ran (below). While the branch the failed spawn created
122
157
  is still there, the retry stays incomplete with the item `the branch the
123
158
  failed spawn created is left: OATS does not delete it. Inspect it and delete
124
159
  it with Git if it is not wanted, then retry`. The item names no branch: the
@@ -147,6 +182,60 @@ A self-contained package has an `oats.json`:
147
182
  success, and every Git step it records must be re-run and verified. A retry that resolves no
148
183
  capabilities — a hand-edited descriptor, or config drift since the spawn — is an
149
184
  incomplete cleanup, not a clean one, and the home stays.
185
+ - **A spawn in progress** (0.49.0). A `work: worktree` spawn that fires
186
+ [`worktree` hooks](#the-worktree-event) writes the same marker just before
187
+ the first of them, so a parent killed while they run (SIGKILL included)
188
+ leaves a home `oats retire` can clean up. Its `outstanding` holds the retire
189
+ hooks of the capabilities whose spawn hooks ran, plus the Git steps
190
+ `worktree` and `branch`. It adds an optional top-level `inProgress: { pid,
191
+ processStart, startedAt, branch, baseOid, hookPgid?, hookStart? }`: the
192
+ spawning process, identified by its pid and start time, the branch the spawn
193
+ created and the commit it created it at, and the process group of the hook
194
+ running. The spawn removes the marker once its final `instance.json` and
195
+ baseline are written; a failure's compensation replaces it in one rename.
196
+ Such a marker satisfies every rule above, so a reader that does not know
197
+ `inProgress` reads it as a quarantine. While the spawning process is
198
+ verifiably alive (its pid runs with the recorded start time):
199
+ - `oats status` gives the home's row `spawnInProgress: true` and no
200
+ `rollbackIncomplete`;
201
+ - `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--force` included;
202
+ - `oats session start` refuses it as any quarantined home
203
+ (`E_INSTANCE_RETIRING`).
204
+
205
+ Whether the process exists is the operating system's answer (`kill -0`:
206
+ "no such process" is gone, another user's process exists), the same on
207
+ every host. Only then is its start time read: from `/proc`, or with `ps`
208
+ (in a fixed `LC_ALL=C`, `TZ=UTC` environment) where there is no `/proc`,
209
+ as on macOS. A start that cannot be read is never taken to mean the process is
210
+ gone, nor shown as alive: `oats status` shows the quarantine
211
+ (`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
212
+ refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
213
+ check by hand. Once that check shows the spawn is gone, `oats retire
214
+ <instance> --force` retires the home and keeps the branch
215
+ (`spawnCompensation.reason`, `forcedIncomplete`).
216
+
217
+ Once that process is gone (killed with SIGKILL, or its rollback cut
218
+ short), `oats retire` finishes the spawn's own compensation, in order:
219
+ 1. it ends the hook process group the spawn left, only when the group's
220
+ leader runs with its recorded start time. A group whose leader has
221
+ exited is not signalled, and a warning names it;
222
+ 2. it runs the owed retire hooks;
223
+ 3. it removes the worktree and verifies the removal;
224
+ 4. only then, it deletes `inProgress.branch` with an atomic
225
+ compare-and-delete at `inProgress.baseOid` (`git update-ref -d
226
+ refs/heads/<b> <baseOid>`).
227
+
228
+ This is the one exception to "no retire deletes a branch": a branch still
229
+ at the commit it was created at holds no work. Retire does not delete it,
230
+ and falls back to the "branch left" item above naming the branch (the home
231
+ is retained), when its tip moved, when it is checked out in any worktree,
232
+ or when its ref cannot be read. Every other quarantine keeps its branch.
233
+ The retire result's `branchDeleted` means exactly "retire's own
234
+ `--delete-branch`" (refused, so always `false`), not whether a branch was
235
+ deleted. This step is reported in the additive `spawnCompensation`, the one
236
+ place a retire's branch deletion is reported: `{ branch, branchDeleted:
237
+ true }`, or `{ branch, branchDeleted: false, reason }`, present only when
238
+ the step was reached.
150
239
  - Because some cleanups can never succeed (a capability offering no way to undo its
151
240
  own setup, a permanently unreachable remote), **`--force` also overrides
152
241
  retention**: the home is removed, and everything still outstanding is printed as
@@ -210,17 +299,35 @@ A self-contained package has an `oats.json`:
210
299
  `home`, the roots are recorded at spawn. The other work modes do not use
211
300
  them.
212
301
 
302
+ A root is read the way spawn records it: a backslash reads as `/`, one
303
+ leading `./` and one trailing `/` are dropped (`./build/` is `build`).
304
+ What is left must be a relative path with no empty, `.` or `..` segment
305
+ (`build`, `node_modules/.cache`). Refused: an empty string, an absolute
306
+ path (`/x`, `\x`, or a Windows one such as `C:/x`, on every host),
307
+ `../x`, `a/../b`, `a//b`, `a/./b`, `.`. Two entries of one manifest that
308
+ overlap, the same root or one inside the other (`build` and `./build/`,
309
+ `a` and `a/b`), are refused too.
310
+
311
+ Spawn alone can see two more cases, and refuses the spawn with
312
+ `E_CAPABILITY_BROKEN` and rolls it back: a declared root that is a
313
+ symlink in the work (also one whose target is missing), and roots of
314
+ different capabilities that overlap. `oats spawn --json` reports these,
315
+ as other spawn failures, as `E_SPAWN_FAILED` with the same message.
316
+
213
317
  A malformed `retirement` is refused wherever the manifest is read: member
214
318
  discovery (`E_WORKSPACE_SCHEMA`), package manifests (`E_PACKAGE_MANIFEST`)
215
319
  and the kernel loader refuse the same manifest, with a JSON pointer:
216
320
  `/retirement` (no `disposable` map, or a key other than `disposable`,
217
321
  `home` and `work`), `/retirement/disposable/<scope>` (not an array of
218
- strings) or `/retirement/disposable/home/<i>` (an entry outside the
219
- grammar):
322
+ strings), `/retirement/disposable/home/<i>` (an entry outside the
323
+ grammar) or `/retirement/disposable/work/<i>` (a root outside the grammar,
324
+ or one that overlaps an earlier entry):
220
325
 
221
326
  ```text
222
327
  capability <id> manifest retirement.disposable.home entry "<value>" must name one hidden top-level home entry (".name", or ".prefix-*")
223
328
  capability <id> manifest retirement.disposable.home entry "<value>" covers a kernel-owned home entry
329
+ capability <id> manifest retirement.disposable.work entry "<value>" must be a relative path under work/ with no empty, "." or ".." segment
330
+ capability <id> manifest retirement.disposable.work entry "<value>" overlaps entry "<earlier>": the same root, or one inside the other
224
331
  ```
225
332
 
226
333
  This kernel reads the field. What retire does with the entries is in
@@ -441,7 +548,8 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
441
548
  `OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
442
549
  `OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
443
550
  preview (only a preview-aware hook does, below); on a real run
444
- `OATS_LAUNCH_PREVIEW` is not set.
551
+ `OATS_LAUNCH_PREVIEW` is not set. A worktree hook also gets the tree
552
+ variables of [The worktree event](#the-worktree-event).
445
553
 
446
554
  A dispatched command (`oats <namespace> <command>`, from an instance home or
447
555
  from the deployment directory) receives:
@@ -483,7 +591,8 @@ a home with none recorded gives `{}`. A final JSON line may return `meta`,
483
591
  `brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
484
592
  launch hook's preview answer may add `volatileEnv` (below). A **spawn or
485
593
  launch hook** may also return an `env` object for the launched process;
486
- returning `env` from a retire hook is an explicit contract error.
594
+ returning `env` from a retire or [worktree](#the-worktree-event) hook is an
595
+ explicit contract error.
487
596
 
488
597
  A **launch hook** runs at every start and restart of a home for each provider
489
598
  recorded at spawn (under its recorded settings). Its `launch` arguments and
@@ -615,6 +724,145 @@ Spawn order is by capability name; retirement reverses successful
615
724
  spawn order. Hooks run from the instance's own copy
616
725
  (`<home>/.oats/modules/<cap>/`).
617
726
 
727
+ ### The worktree event
728
+
729
+ `OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
730
+ kernel has just created: install dependencies, link environment files, pin
731
+ a toolchain. The kernel runs only the hooks of the instance's own
732
+ capabilities; it runs no code from the repository.
733
+
734
+ **When it fires.** Once for each tree the kernel creates:
735
+
736
+ - `./work` of a `work: worktree` spawn, after the spawn hooks succeed and
737
+ inside the spawn's transaction;
738
+ - each extra tree `oats worktree add` makes
739
+ ([extra trees](souls-and-instances.md#extra-trees)).
740
+
741
+ It never fires for a `checkout`, `attached`, `workspace` or `directory`
742
+ `./work`, for a tree made with raw Git, or at start, restart, resume or
743
+ retire. `oats worktree remove` fires no hook. An `add` that finds its tree
744
+ already made (same clone, branch and base) runs no hook again.
745
+
746
+ **How it runs.** Hooks run in capability-name order, from the module copy,
747
+ like every hook. Other events keep their own behaviour (120 s, buffered,
748
+ cwd the home); this one differs:
749
+
750
+ - **cwd is the new tree.** `OATS_TREE` names it too.
751
+ - stdin is `/dev/null`, with no terminal.
752
+ - The hook is started detached, in its own process group, so a timeout or an
753
+ interrupt ends the whole group.
754
+ - stdout and stderr go to `<home>/.oats/logs/worktree-<purpose>-<cap>.log`
755
+ (`worktree-work-<cap>.log` for `./work`), created 0600 and truncated on each
756
+ run. On `oats worktree add` they are also copied to the kernel's stderr,
757
+ never its stdout: `--json` prints only the envelope. A caller that closes
758
+ its end of stderr or stdout (a tool shell killed, Desktop gone) only stops
759
+ the copy: the hooks and the add run to their end, and the log is whole. The log holds whatever
760
+ the hook printed, so its content never enters any JSON answer, receipt,
761
+ record, marker or instance event: they carry the log's path only. The
762
+ `warning` of the hook's last JSON line is the one piece of its output that
763
+ may surface.
764
+ - The timeout is 30 minutes, fixed. At the timeout the kernel sends the group
765
+ SIGTERM, then SIGKILL after a short grace.
766
+ - The result is the exit status. Of the last stdout line's JSON only
767
+ `warning` is read. Returning `env` is a contract error
768
+ (`E_HOOK_ENVIRONMENT_CONTRACT`), as at retire; `meta`, `brief` and `launch`
769
+ are ignored.
770
+ - A non-required hook that fails or times out is a warning; the tree is kept.
771
+ A required one (`{ command, required: true }`) fails closed:
772
+ - at spawn, it fails the spawn through the required-hook rollback above
773
+ (retire hooks compensate in reverse, the worktree-mode Git state is
774
+ removed and verified, and the home is deleted, or kept as a quarantine).
775
+ The hook's log was in that home: once it is deleted, the answer names
776
+ no log path (each `details.hooks` entry's `log` is `null`) and says to run
777
+ the setup with `oats worktree add` in an existing instance to see its
778
+ output; a quarantined home keeps its logs, and the answer names them;
779
+ - at `oats worktree add`, the tree is removed. The branch is deleted only
780
+ when that `add` created it, no worktree has it checked out, and it is
781
+ still where `add` created it.
782
+
783
+ Both exit nonzero, naming the capability and its log. `oats worktree add`
784
+ refuses with `E_REQUIRED_HOOK_FAILED` (`E_HOOK_ENVIRONMENT_CONTRACT` for an
785
+ `env` answer); `oats spawn` fails as for a required spawn hook.
786
+ - A hook that removes or moves the tree fails the check that follows the
787
+ hooks: a failure when any hook is required, else a warning.
788
+ - SIGINT, SIGTERM or SIGHUP to the kernel while the hooks run ends the running
789
+ hook's group, rolls back as for a required failure, and exits 128 + the
790
+ signal number with `E_INTERRUPTED`. A parent killed with SIGKILL leaves a
791
+ record the next command completes: the `creating` tree record for `add`
792
+ (the next `oats worktree add` or `remove` of that purpose rolls it back), or
793
+ the spawn's [in-progress marker](#manifest) for a spawn (`oats retire`).
794
+ That recovery signals the hook process group the killed parent left only
795
+ while the group's leader runs with its recorded start time. A group whose
796
+ leader has exited is never signalled, because its id may already belong to
797
+ another group. The recovery reports it in a warning, and any leftover
798
+ processes are ended by hand. A group that still has members while its
799
+ leader's start cannot be read (where `ps` fails) is not signalled either,
800
+ and the recovery does not go on past it: the leader may still be that hook,
801
+ or that git step. `add`, `remove` and `oats retire` refuse with
802
+ `E_LIFECYCLE_BUSY` and keep the record, naming the group, its recorded
803
+ start and the way out: check the group by hand and, if it is that hook or
804
+ git step, end it (`kill -TERM -- -<pgid>`) and retry. If it is not, remove
805
+ the record named in the message (for `add` and `remove`), or run `oats retire
806
+ <instance> --force`, which then keeps the branch.
807
+
808
+ **Leave the tree clean.** `oats worktree remove` refuses a tree with
809
+ uncommitted changes (`E_WORKTREE_DIRTY`). So a hook should leave the tree
810
+ clean: an install that does not rewrite the lockfile (`npm ci`, `yarn install
811
+ --immutable`, not a plain `npm install`), and outputs that are gitignored. A
812
+ hook that has to change tracked files says so in its capability's brief.
813
+
814
+ **Environment.** The standard hook variables above, and:
815
+
816
+ | Variable | Value |
817
+ |---|---|
818
+ | `OATS_TREE` | the absolute canonical path of the new tree |
819
+ | `OATS_TREE_CLONE` | the absolute path of the clone the tree was added from |
820
+ | `OATS_TREE_REMOTE` | the clone's `origin` URL, without credentials (below) |
821
+ | `OATS_TREE_MEMBER` | the member repository key, or empty (below) |
822
+ | `OATS_BRANCH` | the branch the tree was created on |
823
+ | `OATS_TREE_BASE` | the base as given: `--base`, or the spawn's planned base ref |
824
+ | `OATS_TREE_BASE_OID` | the commit the tree's HEAD is at when the hook starts |
825
+ | `OATS_PURPOSE` | the `--purpose`; empty for `./work` |
826
+ | `OATS_TREE_ORIGIN` | `spawn` or `add` |
827
+
828
+ `OATS_TREE_MEMBER` is never inferred over the network:
829
+
830
+ - `oats worktree add --repo <key>`: that key;
831
+ - `oats worktree add` without `--repo`: the soul's member key, when the
832
+ clone's local remotes name that repository;
833
+ - `oats worktree add --repo <path>`: empty;
834
+ - a spawn: the soul's member key, when the clone is a clone of the soul's
835
+ repository; else empty.
836
+
837
+ `OATS_TREE_REMOTE` never carries a credential. For a URL-style remote
838
+ (`scheme://userinfo@host/...`), the whole userinfo (`user:password@` or
839
+ `token@`) is dropped; for an scp-style remote (`user@host:path`), the `user@`
840
+ is dropped. `https://user:tok@host/org/r.git` becomes
841
+ `https://host/org/r.git`, and `git@host:org/r.git` becomes `host:org/r.git`.
842
+ The kernel records, prints, logs and passes on only this form: the hook
843
+ environment, the tree record, the instance event and the receipt.
844
+
845
+ **The environment is inherited.** As for every hook, the hook runs with the
846
+ environment of whoever ran the command; inside an instance session that is
847
+ the session's own. The kernel adds no credentials. A hook that needs a
848
+ registry token or a deploy key gets it from that environment, or from its
849
+ own configuration.
850
+
851
+ **Adoption.** A kernel before 0.49.0 refuses a manifest that declares
852
+ `hooks.worktree`, and with it the whole capability. In order:
853
+
854
+ 1. Upgrade the kernel on **every host that composes the capability**.
855
+ 2. Only then declare `hooks.worktree`, with `compatibility.oats:
856
+ ">=0.49.0"`, so an older host refuses with `E_CAPABILITY_INCOMPATIBLE`
857
+ naming the release, not with a schema error.
858
+ 3. The blast radius is every soul that composes the capability, on every host
859
+ below the release: one capability can stop every developer soul of a
860
+ workspace from spawning, as in lfx-oats-workspace#22, where one capability
861
+ took down every developer soul.
862
+ 4. To limit it, put the hook in a small capability composed only by the souls
863
+ that need the setup.
864
+ 5. Declare it `required` when the tree is unusable without the setup.
865
+
618
866
  ## Official packages
619
867
 
620
868
  The official packages and the capabilities and souls each carries are listed
@@ -24,7 +24,7 @@
24
24
  "OptionalHook": {
25
25
  "oneOf":[
26
26
  {"type":"string"},
27
- {"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"const":false,"description":"Only the existing spawn hook may be required."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
27
+ {"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"const":false,"description":"Only the spawn and worktree hooks may be required."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
28
28
  ]
29
29
  }
30
30
  },
@@ -259,9 +259,17 @@
259
259
  ]
260
260
  },
261
261
  "retire": {"$ref":"#/$defs/OptionalHook"},
262
- "launch": {"$ref":"#/$defs/OptionalHook"}
262
+ "launch": {"$ref":"#/$defs/OptionalHook"},
263
+ "worktree": {
264
+ "description": "Runs once in each tree the kernel creates: ./work of a work: worktree spawn (after the spawn hooks) and each `oats worktree add`. Its cwd is the new tree; see docs/capabilities.md, The worktree event.",
265
+ "oneOf":[
266
+ {"type":"string"},
267
+ {"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"type":"boolean","description":"When true, a failure or timeout fails the spawn, or removes the tree `oats worktree add` made."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
268
+ ]
269
+ }
263
270
  },
264
- "additionalProperties": false
271
+ "additionalProperties": {"$ref":"#/$defs/OptionalHook"},
272
+ "description": "Lifecycle events to commands. An event this kernel does not run (a newer kernel's) is accepted with a warning and ignored, unless it is declared required: that is refused. Kernels before 0.49.0 refuse every unknown event."
265
273
  },
266
274
  "settings": {
267
275
  "type": "object",
@@ -320,10 +328,15 @@
320
328
  },
321
329
  "work": {
322
330
  "type": "array",
323
- "description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made.",
331
+ "description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made. A backslash reads as /, one leading ./ and one trailing / are dropped, and what is left must be a relative path with no empty, . or .. segment; an absolute path (/x, C:/x) is refused. Two entries of one manifest that overlap (the same root, or one inside the other) are refused; spawn also refuses roots of different capabilities that overlap, and a root that is a symlink in the work.",
324
332
  "items": {
325
333
  "type": "string",
326
- "minLength": 1
334
+ "minLength": 1,
335
+ "pattern": "^(?:\\.[/\\\\])?(?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+(?:[/\\\\](?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+)*[/\\\\]?$",
336
+ "not": {
337
+ "description": "A Windows absolute path is refused on every host.",
338
+ "pattern": "^[A-Za-z]:[/\\\\]"
339
+ }
327
340
  }
328
341
  }
329
342
  },
@@ -101,6 +101,12 @@ default. A home not yet created uses its resolved existing directory ancestor
101
101
  plus its intended suffix; launch checks the created home's identity again.
102
102
  No existing home is enabled automatically. Removing an entry disables consent
103
103
  for future launches.
104
+ On a case-insensitive filesystem (the macOS default) one home has several
105
+ letter-case spellings, and a key in any of them is valid. A key spelled exactly
106
+ as the home is launched decides. Otherwise the single key naming the same
107
+ directory decides, and `consentSource` points at that key. Several keys naming
108
+ it in different case, with none spelled exactly, decide nothing: no consent.
109
+ Consent never reaches another directory.
104
110
 
105
111
  The sole confirmation covered is Claude's development-channel prompt for
106
112
  `plugin:aweb-channel@awebai-marketplace`. The provider's `claudeChannelMode`