@awebai/oats 0.47.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 (44) hide show
  1. package/bin/oats.mjs +293 -41
  2. package/docs/capabilities.md +264 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +7 -1
  5. package/docs/desktop-cli-api.md +439 -40
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +19 -1
  8. package/docs/implementation.md +81 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +6 -5
  12. package/docs/packages.md +14 -14
  13. package/docs/release-notes/v0.48.0.md +106 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/schedules.md +62 -39
  16. package/docs/servers.md +7 -0
  17. package/docs/souls-and-instances.md +395 -52
  18. package/docs/workspaces.md +18 -3
  19. package/injects/work-checkout.md +17 -11
  20. package/injects/work-worktree.md +19 -13
  21. package/lib/capability-contract.mjs +100 -11
  22. package/lib/capability-show.mjs +5 -2
  23. package/lib/core.mjs +1147 -319
  24. package/lib/instance-events.mjs +6 -3
  25. package/lib/instance-git.mjs +11 -5
  26. package/lib/instance-inspect.mjs +14 -3
  27. package/lib/instance-lifecycle.mjs +106 -16
  28. package/lib/instance-resolution.mjs +15 -3
  29. package/lib/launch-prompt-policy.mjs +17 -3
  30. package/lib/packages.mjs +1 -0
  31. package/lib/real-path.mjs +27 -0
  32. package/lib/resolve.mjs +4 -4
  33. package/lib/retire-output.mjs +6 -1
  34. package/lib/schedule.mjs +1 -0
  35. package/lib/servers.mjs +32 -6
  36. package/lib/teams-verbs.mjs +40 -9
  37. package/lib/tree-copy.mjs +18 -7
  38. package/lib/triggers.mjs +201 -65
  39. package/lib/workspace.mjs +20 -5
  40. package/lib/worktree-hooks.mjs +392 -0
  41. package/lib/worktree.mjs +655 -0
  42. package/package-catalog.json +12 -5
  43. package/package.json +1 -1
  44. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -147,7 +147,10 @@ homes, logs, notes, branches and messaging identities are local.
147
147
  ### `instance.json`: provenance is recorded, not declared
148
148
 
149
149
  Besides the instance's identity, repository, branch, lineage, launch recipe and
150
- composed skills and instructions, a spawn records:
150
+ composed skills and instructions, a spawn records provenance. The following is a
151
+ **historical 4.x-spawned home**, not the settings to use for new oats.okf 5.0
152
+ spawns: its version and provider payload remain recorded after a pin changes.
153
+ For current settings and the respawn/cleanup sequence, see [knowledge.md](knowledge.md).
151
154
 
152
155
  ```json
153
156
  {
@@ -431,6 +434,13 @@ takes a final capture of notes and the session record into durable custody; an
431
434
  incomplete capture keeps the home for a retry. Retirement never waits for a
432
435
  model or GitHub: processing continues after the home is gone.
433
436
 
437
+ Recorded children (the instances whose recorded parent chain reaches this
438
+ one) are stopped first, never escalated, and kept: their homes stay. If one is
439
+ still running after the grace, or its stop cannot be established, retire
440
+ refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
441
+ bypass it. This holds for plain, guarded and `--self` retires alike
442
+ ([desktop-cli-api.md](desktop-cli-api.md)).
443
+
434
444
  Before any retire hook runs, retire preserves the instance's uncommitted and
435
445
  unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
436
446
  the summary. One retire writes at most one recovery directory. A worktree
@@ -438,7 +448,14 @@ recovery is a standalone clone that carries the
438
448
  repository's local exclude rules (`info/exclude`, a configured
439
449
  `core.excludesFile`), its `info/attributes` and the settings that change what
440
450
  status reports (`core.fileMode`, `core.ignoreCase`, …), so its Git status
441
- matches the source's. A recovery that
451
+ matches the source's. Its files are the worktree's, entry for entry: each top
452
+ level of the clone (the worktree's, and each nested repository's) is made the
453
+ source's, so a tracked entry the source deleted or renamed is not left in the
454
+ copy. The copy's verification compares every entry's bytes, leaving out only
455
+ the worktree's own `.git` and those of the nested repositories the copy
456
+ rebuilds from a clone; any other entry named `.git` (a dangling link, or the
457
+ Git directory of a repository inside a nested one, carried as files) is
458
+ compared like any other. A recovery that
442
459
  cannot be verified refuses with `E_WORK_PRESERVATION_FAILED` and keeps the
443
460
  home. **`--force` does not skip work preservation.** It forces only past a
444
461
  missing or unusable cleanup marker and past incomplete hook cleanup
@@ -464,7 +481,10 @@ rewrite a file that was already modified, and the row stays the same. In
464
481
  directory mode the work state is the bytes of `work/`, with the permission
465
482
  bits of each entry and of `work/` itself. In worktree mode it
466
483
  is what a work copy of the worktree holds, each file read where the copy
467
- reads it:
484
+ reads it. The copier reads the paths Git prints for it (the Git directory,
485
+ the common directory, `core.excludesFile`, the top level) exactly as Git
486
+ prints them, white space included, and a worktree's `.git` file as Git
487
+ parses it, so it copies the files Git reads:
468
488
 
469
489
  - its Git status, the ref its HEAD is on and the commit, and, when the copy
470
490
  is made detached, the branch the repository's own HEAD is on;
@@ -499,6 +519,50 @@ equality:
499
519
  repository or deletes a branch, and a commit of the worktree that no ref
500
520
  reaches is preserved before the worktree is removed.
501
521
 
522
+ **How the retire runs Git.** Every Git command the retire runs on the work,
523
+ its repository, a repository under the work and a recovery clone is run
524
+ from argv, without a shell, with `--no-optional-locks` and
525
+ `GIT_OPTIONAL_LOCKS=0`, so a `git status` never refreshes, and so never
526
+ rewrites, the index it inspects. It also runs with `-c core.fsmonitor=false`,
527
+ `-c core.hooksPath=/dev/null` and `-c diff.external=`, so no fsmonitor, hook
528
+ or external diff that the repository's own configuration names runs, and
529
+ with `GIT_NO_LAZY_FETCH=1`: an object the repository lacks (a promisor
530
+ repository's) is a read that fails, never a fetch through the remote, remote
531
+ helper, ssh command or credential helper its configuration names. That
532
+ protection needs Git 2.44 or later; an older Git ignores the variable, so it
533
+ gets none, and nothing else changes. The
534
+ caller's repository-local Git variables are not passed: Git's own list
535
+ (`git rev-parse --local-env-vars`: `GIT_DIR`, `GIT_WORK_TREE`,
536
+ `GIT_INDEX_FILE`, `GIT_COMMON_DIR`, the object directories, `GIT_CONFIG`,
537
+ `GIT_CONFIG_PARAMETERS` and the others), and `GIT_CONFIG_COUNT` with its
538
+ `GIT_CONFIG_KEY_<n>` and `GIT_CONFIG_VALUE_<n>` pairs. A read that names
539
+ its own index (the index the copy carries) keeps it. The operator's global
540
+ and system configuration are still read: the spawn baseline was taken under
541
+ them, and without them a status can read differently (a global
542
+ `core.excludesFile`, `core.autocrlf`, a filter), which would add a copy
543
+ attempt to every existing instance's retire. They are the operator's own;
544
+ what the retire guards against is configuration the retired agent could
545
+ write. One limit remains: a filter driver that the repository's own
546
+ configuration names and its `.gitattributes` select can still run during
547
+ `git status`. Turning it off would change what status reports.
548
+
549
+ **A worktree whose top level is another directory.** A worktree's
550
+ per-worktree configuration can set `core.worktree` to a directory other
551
+ than `<home>/work`. Git's status then describes that other directory, while
552
+ the retire reads, copies and removes `<home>/work`. So before any status is
553
+ trusted, in each of its three inspections, the retire checks that Git's top
554
+ level for `work/` (`git rev-parse --show-toplevel`) is `<home>/work`. The
555
+ two are compared in their on-disk spelling: a path reached through a
556
+ symbolic link, or spelled in another letter case on a case-insensitive
557
+ filesystem, is the same path. Any other top level, or one that cannot be
558
+ read, refuses with `E_WORK_INSPECTION_FAILED`, naming both paths. The first
559
+ inspection runs before the session is stopped and before any retire hook:
560
+ nothing was stopped, run or removed. At the inspection before the hooks the
561
+ refusal says that no retire hook has run and nothing was deleted, and
562
+ whether the session has been stopped. After the hooks it says that they
563
+ have run, that the home, its work and the pre-hook recovery (if any) are
564
+ kept, and whether the session has been stopped.
565
+
502
566
  The permission bits of the home directory and of the worktree directory
503
567
  themselves are not compared: their copies are made in directories the copier
504
568
  creates, which do not carry them.
@@ -506,11 +570,14 @@ creates, which do not carry them.
506
570
  Every part of that state is compared as its bytes, never as decoded text. A
507
571
  ref name, a path in the index or in the status, a file name or the target of
508
572
  a symbolic link need not be valid UTF-8, and two states that differ only in
509
- such bytes are two states. This is what the proof compares, not what a copy
510
- can hold: a recovery cannot hold a file whose name is not valid UTF-8. A
511
- copy of a home or a worktree that has one fails, and the retire refuses with
512
- nothing lost. A clean worktree that has one, with only the home to preserve,
513
- needs no work copy and retires.
573
+ such bytes are two states. The copier carries names as bytes too: a file of
574
+ the home or of the work whose name is not valid UTF-8 is copied under that
575
+ name, and the retire goes on. Where a name is shown (a receipt's `paths`, a
576
+ message), it is text, with replacement characters for such bytes. One limit
577
+ stays: Git is run on a nested repository by its path, and a path that is not
578
+ valid UTF-8 cannot be given to it, so a nested repository whose own path holds
579
+ such a name refuses the copy with `E_WORK_PRESERVATION_FAILED`, with nothing
580
+ removed; rename that directory, then retire again.
514
581
 
515
582
  A worktree's tags, stash, exclude rules and settings are kept by the
516
583
  repository it belongs to. They are part of the state because a work copy
@@ -532,7 +599,8 @@ file or a link that leads to one is a repository: one made by `git init` or
532
599
  a clone, a submodule, or a linked worktree of another repository placed in
533
600
  the work. One whose `.git` is a dangling symbolic link, or could not be
534
601
  tested, is not read as a repository and counts all the same: the copy
535
- carries such a link as a link, and no comparison reads it. A repository's
602
+ carries such a link as a link, and the copy's verification holds it as one. A
603
+ repository's
536
604
  state is not compared:
537
605
  the retire hooks run between the two copies and can change it in ways no read
538
606
  of its state covers (its configuration, its objects, what a clone of it is
@@ -561,19 +629,41 @@ holds of each kind:
561
629
 
562
630
  | Of the nested repository | The copy holds |
563
631
  |---|---|
564
- | the branch `HEAD` is on | the branch and its commits |
565
- | every other branch | its commits, without the branch name: `git fsck --unreachable` in the copy lists them |
632
+ | `HEAD` | on the same branch, or detached at the same commit when the source's is detached (or on a ref that is not a branch, or on a branch whose name is not UTF-8) |
633
+ | every local branch | the branch under its name, at its commit |
634
+ | the reflogs of `HEAD` and of each branch | branch and `HEAD` reflogs are carried, with every commit they name |
566
635
  | tags | the tags and what they name |
567
- | the stash | its latest entry and the stash's log; the commits of older entries are not there |
568
- | remote-tracking refs, notes, any other namespace | nothing beyond what a branch or a tag reaches |
636
+ | the stash | every entry the stash's log names, and the log |
637
+ | the index | the index, with every blob its entries and its resolve-undo records name |
638
+ | its local configuration | only the status settings (`core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`, `core.symlinks`, `core.autocrlf`, `core.eol`); remotes, `branch.*` upstreams, `user.*` and everything else are dropped |
639
+ | remote-tracking refs, notes, any other namespace | nothing beyond what a branch, a tag or a log reaches |
569
640
  | a repository inside it | its files, its Git directory included, as plain files |
570
641
 
571
- A commit the copy holds without a name is lost to `git gc` in the copy.
572
- `git fsck --unreachable` in the copy lists such commits, and
573
- `git branch <name> <commit>` there gives one a name again. What the copier
574
- cannot carry at all (a file whose name is not valid UTF-8, an entry that is
575
- not a file, a directory or a symbolic link) refuses the copy, here as
576
- anywhere.
642
+ The local configuration is dropped on purpose: a recovery must be inert to
643
+ inspect. A repository's configuration can name programs Git runs
644
+ (`core.hooksPath`, `core.fsmonitor`, `include.path`, a credential helper, a
645
+ diff, textconv or filter driver), which would run when an operator later runs
646
+ Git in the recovery. Set by hand in the recovery only what you trust.
647
+
648
+ **Every object the copy's Git metadata names is in it.** For the worktree's
649
+ copy and for each nested repository's alike, the copier collects what the
650
+ Git metadata it carries names: every commit the stash's log names (the new
651
+ id of each entry, as `git log -g refs/stash` shows them), for a nested
652
+ repository the commit of each of its local branches (its own `refs/heads`,
653
+ including a branch its configuration hides from a clone) and every commit
654
+ its `HEAD` and branch reflogs name, and every blob
655
+ the copied index's entries and resolve-undo records name (a gitlink names
656
+ another repository's commit and is left out). It asks which of them the
657
+ copy lacks, fetches the missing commits from the source by id and copies
658
+ the missing blobs by content (a staged blob or a resolved conflict's side
659
+ can be in no commit), then checks the whole set again. An object the
660
+ source cannot supply (a partial clone that lacks it: the retire never
661
+ fetches from a promisor remote) refuses the copy with
662
+ `E_WORK_PRESERVATION_FAILED`, naming it. So `git stash show stash@{2}` and
663
+ `git checkout -m <path>` work in the copy as in the source. What the copier
664
+ cannot carry at all (an entry that is not a file, a directory or a symbolic
665
+ link, or a nested repository whose path is not valid UTF-8) refuses the copy,
666
+ here as anywhere.
577
667
 
578
668
  **A worktree that cannot be proven unchanged.** Two things make a worktree
579
669
  not provable:
@@ -609,7 +699,18 @@ Every refusal of the copy made before the hooks, whatever its cause, ends by
609
699
  saying what the retire has done by then: no retire hook has run, no recovery
610
700
  was written and nothing was deleted, the instance is not retired, its home
611
701
  and work are kept, and its session has been stopped, or this retire stopped
612
- no session. A refusal after the hooks does not say that.
702
+ no session. A refusal of the recovery after the hooks (the copy of what they
703
+ moved, or the one recovery of a home that had nothing to preserve before
704
+ them) ends the same way: the retire hooks have run; the home, its work and
705
+ the pre-hook recovery (if any) are kept; and its session has been stopped, or
706
+ this retire stopped no session.
707
+
708
+ A copy that fails removes what it staged, so the refusal carries the copy's
709
+ own cause. The copy gives each directory its source's mode, so a read-only
710
+ directory in the work (a Go module cache, for example) is copied read-only;
711
+ the cleanup makes every staged directory writable before it removes them, and
712
+ never replaces the original error. A staging directory that still cannot be
713
+ removed is named in the refusal, to be removed by hand.
613
714
 
614
715
  A snapshot that holds the home only (the work had nothing to preserve
615
716
  before the hooks) has no work copy to stand for it. It gets the work under
@@ -629,7 +730,11 @@ A worktree whose `git status` fails refuses the retire with
629
730
  `E_WORK_INSPECTION_FAILED` at the first inspection: no recovery was written,
630
731
  nothing was deleted, and the retire has not stopped the instance's session.
631
732
  A directory in place of `info/exclude`, or of the file `core.excludesFile`
632
- names, is such a case: Git itself refuses to use it. Any other read of the
733
+ names, is such a case: Git itself refuses to use it. So is an untracked or
734
+ ignored path that the comparison with a spawn baseline of 0.49.0 or later
735
+ cannot read, such as an ignored directory with an entry under it that has
736
+ no permission: the message names the path and the reason, and says that
737
+ nothing was stopped, run or removed. Any other read of the
633
738
  state that fails does not refuse here: it makes the worktree not provable,
634
739
  as described above.
635
740
 
@@ -703,10 +808,34 @@ spawn baseline, which decides whether the home has anything to preserve at
703
808
  all. When a hook moved only the work, the recovery holds them as of the
704
809
  pre-hook snapshot. The retire's own events are written to the workspace log
705
810
  (`<deployment>/.agents/events/`), never to the home's. A home copy is
706
- verified against the digest the baseline uses, which passes over those
707
- records: an inherited limit, not an exact verification of the whole home.
708
- A work copy's verification passes over every entry named `.git`: a dangling
709
- `.git` symbolic link under the worktree is copied as a link and not verified.
811
+ verified against its source, in the same run, with the digest a spawn
812
+ baseline is written with (below), which passes over those records and over
813
+ the kernel's own fields of `instance.json`: it is not an exact verification
814
+ of the whole home.
815
+
816
+ **What the spawn baseline compares.** Whether the home, and a worktree's
817
+ untracked and ignored files, have anything to preserve is decided against
818
+ two digests the spawn baseline stores: one of the home (without `work/`, the
819
+ provider-owned entries declared at spawn, the kernel's records above, and
820
+ the fields the kernel writes into `instance.json` after spawn), and one of
821
+ the worktree's untracked and ignored paths outside the roots a capability
822
+ declared disposable. A spawn by 0.49.0 or later records `digestVersion: 2`
823
+ in the baseline, and its digests order entries by the bytes of their names,
824
+ so no locale changes them; they hold the length of every name, file and link
825
+ target, so two different trees never give the same digest; and they take the
826
+ untracked and ignored paths from Git's status as bytes and test each without
827
+ following a link, so a file whose name is not valid UTF-8 is read by its own
828
+ name, and a symbolic link is compared by its target whether or not that
829
+ target exists. A baseline written before 0.49.0 keeps the old digests until
830
+ the instance is respawned, and a retire compares it with them exactly as
831
+ before. Those order names by the locale, so a retire under another locale
832
+ than the spawn's can read an unchanged home as changed, which adds a copy
833
+ attempt; they hold no lengths; and they read an untracked or ignored path
834
+ that is a dangling symbolic link, or whose name is not valid UTF-8, as
835
+ missing whatever it holds, so a change to such a path alone is not
836
+ preserved. A baseline whose `digestVersion` this kernel does not know is
837
+ compared with nothing: the home and the untracked and ignored files count as
838
+ changed.
710
839
 
711
840
  Each part under `after-hooks/` is whole and verified, not a delta, and it is
712
841
  verified before the worktree step and before the home is removed.
@@ -753,8 +882,20 @@ exist under "not copied", by name, with the declaring capability. The
753
882
  declaration is recorded at spawn: a home spawned before its capability
754
883
  declared them gains no exclusion from a package update, and is copied whole.
755
884
 
756
- Retire stops the harness through the home's session receipt. A home spawned
757
- before 0.25.9 has none. It retires only when its session is observably gone:
885
+ Retire stops the harness through the home's session receipt, kept beside the
886
+ home in the instances directory's `.oats-retirement/baselines/` and keyed by
887
+ the home's path as it is on disk: on a case-insensitive filesystem (the macOS
888
+ default) every letter-case spelling of the path finds it. First address the
889
+ home exactly as `oats status` prints it: a deployment directory moved since the
890
+ spawn looks for the receipt elsewhere. So does a letter-case spelling other
891
+ than the spawn's for a home spawned before 0.49.0, whose receipt is keyed by
892
+ the spawn's spelling and found from that spelling (or from the on-disk one,
893
+ when the two are the same). A home can also be without
894
+ its receipt because it was spawned before 0.25.9, it was copied, the
895
+ `.oats-retirement` beside it was removed, or its creation did not finish;
896
+ `session inspect`, `start` and `restart` then refuse with
897
+ `E_RUNTIME_ENDPOINT_UNKNOWN` naming the receipt path they looked for. Such a
898
+ home retires only when its session is observably gone:
758
899
  instance.json records no launch, or the recorded tmux server is not running,
759
900
  or the recorded window is gone and no pane on that server works in the home;
760
901
  and, always, no live process on this host works in the home (a harness
@@ -821,6 +962,45 @@ commit yet cannot be read that way: a retire that would remove it, or that
821
962
  has work of it to copy, refuses with `E_WORK_INSPECTION_FAILED` and removes
822
963
  nothing.
823
964
 
965
+ The `work/` step runs helper-free, as the extra-tree step does (no
966
+ fsmonitor, hooks, external diff or lazy fetch that the repository's
967
+ configuration names, and none of the caller's Git environment). It names the repository by its
968
+ common Git directory, read once from the repository the instance was spawned
969
+ from. That covers the default re-home (`git worktree move`), the removal
970
+ (`git worktree remove --force` and `git worktree prune`) and a quarantine
971
+ retry's checks. A removal is verified: nothing is left at `work/`, and the
972
+ repository's `git worktree list` does not name it. A removal that did not
973
+ happen, or that cannot be shown to have happened, refuses with
974
+ `E_WORK_PRESERVATION_FAILED` and keeps the home, `--force` included. That
975
+ includes a removal Git refuses (a locked worktree, for example): such a worktree is no longer deleted with the home, and no
976
+ admin entry is left behind. The refusal says what was done: the retire hooks
977
+ have run, the home is kept with any recovery the retire wrote, and whether
978
+ the session has been stopped. One exception: when nothing is at `work/`
979
+ (no entry at all: a dangling symbolic link is an entry) and the repository
980
+ cannot be read, the worktree is recorded `absent`, never `removed`. A
981
+ quarantine retry then keeps `could not verify removal` as an incomplete
982
+ item, which only `--force` clears, as the operator's explicit override.
983
+
984
+ A plain retire re-homes `work/` (see the extra trees below for where).
985
+ Attached children that use this home's `work/` as their own (their
986
+ `instance.json` says `work: "attached"` and their `work` is a link to
987
+ `<home>/work`, directly or through an alias of it given as `--work-dir`)
988
+ would be left with a dangling link. The retire finds them before it moves
989
+ the worktree, and repoints a child only if its link is still the one it
990
+ found. Each one this retire
991
+ stopped as a recorded child is repointed to the retained worktree: a new link
992
+ is renamed over the old one, so the link is never missing. This is the last
993
+ step before the home is removed, once the worktree is at its new path and
994
+ nothing is left at `work/`, and it also runs when the home is then kept for a
995
+ retry. A relink that fails is a warning in the summary and the receipt's
996
+ `warnings`, with the command to repoint the link by hand; the retire is not
997
+ undone. A child that is not attached, whose link leads elsewhere, or that this
998
+ retire did not stop is not touched. With `--discard-worktree` the worktree is
999
+ removed and an attached child's link dangles. The retire plan names the
1000
+ attached children in one note that covers both cases. Only the link changes:
1001
+ the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1002
+ still name the old path.
1003
+
824
1004
  #### Extra trees at retire
825
1005
 
826
1006
  An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
@@ -856,7 +1036,8 @@ leaves `work/` untouched. For each tree:
856
1036
  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
857
1037
  `--force`) and `git worktree prune`, and verifies that the tree is gone from
858
1038
  `git worktree list`. Every Git command of this step runs helper-free (no
859
- fsmonitor, hooks or external diff the repository's configuration names). Its branch is never deleted: a commit on the branch that
1039
+ fsmonitor, hooks, external diff or lazy fetch the repository's configuration names),
1040
+ as the `work/` step's do. Its branch is never deleted: a commit on the branch that
860
1041
  was not pushed stays in the clone, on that branch.
861
1042
  - **Any other tree is re-homed**, as `work/` is by default: `git worktree
862
1043
  move` to `<deployment>/.agents/worktrees/<repo>/<leaf>`, where `<leaf>` is
@@ -891,6 +1072,64 @@ not say. The retire hooks have run by then, and no tree was moved or
891
1072
  removed. The fields are in
892
1073
  [the CLI API](desktop-cli-api.md#retire).
893
1074
 
1075
+ #### After a retire: inspect, restore, dispose
1076
+
1077
+ A retire can leave two things behind outside the removed home: a recovery
1078
+ copy and a retained worktree. Nothing in OATS removes either; each stays
1079
+ until you remove it. What follows are facts to decide with, not a judgement
1080
+ that anything is safe to delete. The uncommitted and untracked bytes in a
1081
+ recovery are in no commit: a retained worktree or the source may still hold
1082
+ them, or the recovery may be the only copy, so inspect them before you
1083
+ remove it.
1084
+
1085
+ **Recovery copies** are at
1086
+ `<instances>/.oats-retirement/recovery/<instance>-<random>/`, beside the
1087
+ homes of the agent the instance belonged to. The retire summary prints the
1088
+ path, the receipt names it as `workRecovery.path`, and the `retired` event
1089
+ in the workspace log keeps it as `data.workRecovery`, so `oats instance
1090
+ events <instance>` still shows it after the home is gone. Its
1091
+ `recovery.json` says what it holds:
1092
+
1093
+ - `phase`: `"complete"` once the check after the retire hooks concluded;
1094
+ `"before-hooks"` when the retire stopped before that, which still leaves a
1095
+ complete, verified snapshot of the state before the hooks.
1096
+ - `classes`: what was preserved (`changed instance-home bytes`, `untracked
1097
+ or ignored worktree bytes`, `directory work bytes`, …).
1098
+ - `afterHooks`: `{home, work}`, present when the hooks changed something
1099
+ and `after-hooks/` holds a second copy of that part.
1100
+ - `home`, `outputs` and `notCopied`: the home entries copied, the untracked
1101
+ or ignored outputs copied, and the declared entries left out.
1102
+
1103
+ To inspect one, read `recovery.json`, then the parts. `repo/` is a
1104
+ standalone clone of a worktree instance's repository with its uncommitted
1105
+ state in place: `git -C <recovery>/repo status`, `git -C <recovery>/repo
1106
+ log`, `git -C <recovery>/repo stash list`. `work/` is a directory
1107
+ instance's work, `home/` the copied home (notes, `STATE.md`, …), and
1108
+ `after-hooks/` the parts as the retire hooks left them.
1109
+
1110
+ To restore from one, take what you need back into the source repository or
1111
+ wherever it belongs. Commits: fetch the branch from the recovery's clone
1112
+ under a new name, so that nothing in the source repository is overwritten:
1113
+ `git -C <source repository> fetch <recovery>/repo <branch>:refs/heads/<new
1114
+ branch>`. Uncommitted files: copy them back, or commit them in the
1115
+ recovery's clone first and fetch that branch (the recovery then no longer
1116
+ holds the state exactly as it was taken). Home files: copy them from
1117
+ `home/`.
1118
+
1119
+ To dispose of one, once its contents are settled elsewhere, remove the
1120
+ directory by hand. A copy keeps the modes of what it copied, so a read-only
1121
+ directory from the work is read-only there too: `chmod -R u+w <recovery>`,
1122
+ then `rm -rf <recovery>`.
1123
+
1124
+ **Retained worktrees** are at `<deployment>/.agents/worktrees/<repo>/<leaf>`
1125
+ (see [extra trees at retire](#extra-trees-at-retire) for the leaf). They are
1126
+ ordinary linked worktrees of the source repository, with their uncommitted
1127
+ state intact: `git -C <source repository> worktree list` lists them. Once
1128
+ the branch is merged or pushed and nothing uncommitted in the tree is still
1129
+ wanted, `git -C <source repository> worktree remove <path>` removes it; Git
1130
+ refuses a tree with uncommitted changes unless you pass `--force`. Its
1131
+ branch stays in the repository either way.
1132
+
894
1133
  ## Work modes
895
1134
 
896
1135
  A work mode decides what `./work` points at and what discipline the agent must
@@ -941,15 +1180,23 @@ a `--repo` that is not a clone of the soul's repository starts at its `HEAD`.
941
1180
  The spawn result and `instance.json` record the start point as
942
1181
  `base: {ref, oid}`.
943
1182
 
1183
+ After the spawn hooks succeed, the spawn fires the
1184
+ [`worktree` event](capabilities.md#the-worktree-event) for `work/`: the
1185
+ `worktree` hook of each capability the soul composes runs once, with `work/`
1186
+ as its cwd, inside the spawn's transaction. A required one that fails rolls
1187
+ the spawn back. The spawn result and the `spawned` event carry their receipt
1188
+ as `worktreeHooks`. A spawn whose capabilities declare no such hook runs no
1189
+ setup. No other work mode fires the event.
1190
+
944
1191
  Use this for agents that will edit code or docs independently.
945
1192
 
946
1193
  Rules:
947
1194
 
948
1195
  - Build, test, and commit from `work/`, on your own branch.
949
1196
  - Never work in a shared checkout (the repo's main checkout, or any clone
950
- others use): do not edit, commit or switch branches there. Against a clone,
951
- run only `git worktree add` and `git worktree remove`, as in
952
- [extra trees](#extra-trees).
1197
+ others use): do not edit, commit or switch branches there. A clone is
1198
+ touched only through `oats worktree add` and `oats worktree remove`
1199
+ ([extra trees](#extra-trees)).
953
1200
  - Everything you change happens in `work/` or in your extra trees.
954
1201
  - Leave your branch and the worktree list clean when your task closes.
955
1202
 
@@ -979,7 +1226,10 @@ service agents such as reviewers.
979
1226
 
980
1227
  Attached agents are guests: never switch branches or rewrite history, touch
981
1228
  only what the briefing names, keep commits small and attributable. Retiring
982
- an attached instance never removes the shared tree. The packaged
1229
+ an attached instance never removes the shared tree. When its owner retires
1230
+ and the tree is re-homed, the attached instance's `work` link is repointed to
1231
+ the tree's new path ([retire](#retire)); its AGENTS.md and TASK.md still name
1232
+ the old one. The packaged
983
1233
  `work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
984
1234
 
985
1235
  ### `directory` — independent execution
@@ -1028,44 +1278,137 @@ The instance records no branch: the workspace is not a Git tree.
1028
1278
  An instance in `worktree` or `checkout` mode can create extra trees: linked
1029
1279
  Git worktrees in its home, beside `work/`. It does so when the work needs
1030
1280
  another branch, or another repository of the deployment (one task that
1031
- touches several repositories). The `worktree` and `checkout` briefings give
1032
- the command; the `workspace`, `directory` and `attached` briefings do not.
1033
- There is no `oats` command for it.
1281
+ touches several repositories). The `worktree` and `checkout` briefings teach
1282
+ it; the `workspace`, `directory` and `attached` briefings do not.
1034
1283
 
1035
- `<clone>` is any clone of the deployment (`oats-local.yaml` `clones:`, or
1036
- `<deployment>/<repo>`), `origin` is its remote for that repository, and
1037
- `<base>` is the remote branch the work starts from (the branch itself, to
1038
- rework an existing one):
1284
+ ```text
1285
+ oats worktree add --purpose <p> --branch <b> --base <remote-branch>
1286
+ [--repo <member key|clone path>] [--preview] [--json]
1287
+ oats worktree remove --purpose <p> [--json]
1288
+ ```
1289
+
1290
+ Both run from an instance home: the home `$OATS_INSTANCE_HOME` (or
1291
+ `$OATS_HOME`) names, else the home that encloses the working directory.
1292
+ `--dir`, `--home` and `--server` are refused (`E_BAD_ARGS`). The tree is
1293
+ `<home>/.work-<p>`.
1294
+
1295
+ **Arguments.** Each is checked before anything is written; a value that
1296
+ starts with `-` is refused (`E_BAD_ARGS`), because Git would read it as an
1297
+ option.
1298
+
1299
+ - `--purpose`: a slug, as an instance name (lowercase letters, digits and
1300
+ `-`, at most 64 characters).
1301
+ - `--branch`: a valid branch name that does not exist in the clone
1302
+ (`E_BRANCH_EXISTS`, with the remedy `<instance>/<branch>`). It follows the
1303
+ repository's own naming rules, else `agents/<instance>-<purpose>`. `add`
1304
+ never resets a branch: there is no `-C` or `-B`.
1305
+ - `--base`: the remote branch the work starts from (the branch itself, to
1306
+ rework an existing one).
1307
+ - `--repo`: the instance's repository by default. A member key is looked up
1308
+ as a spawn looks up a clone (`oats-local.yaml` `clones:`, then
1309
+ `<deployment>/<member name>`; `E_CLONE_MISSING` when there is none). A path
1310
+ (absolute, or starting with `.` or `~`) is used as given. It must be a
1311
+ clone, not a linked worktree (`E_CLONE_MISMATCH`), and have an `origin`
1312
+ remote (`E_CLONE_MISMATCH`). Not a Git repository: `E_CLONE_MISSING`.
1313
+
1314
+ **What `add` does.** It writes a record, `<home>/.oats/trees/<p>.json`, in
1315
+ state `creating`, with its own pid and start time. Then it runs, as argument
1316
+ vectors with no shell:
1039
1317
 
1040
1318
  ```bash
1041
- git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
1042
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
1043
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
1319
+ git -C <clone> worktree add --detach <home>/.work-<p>
1320
+ git -C <home>/.work-<p> fetch --refmap= origin <base>
1321
+ git -C <home>/.work-<p> switch -c <branch> <the fetched commit>
1044
1322
  ```
1045
1323
 
1046
1324
  - The tree starts from the remote's current state, never from a local branch
1047
- of the clone, which may be stale.
1325
+ of the clone, which may be stale. A fetch that fails is
1326
+ `E_REMOTE_UNREADABLE`; a HEAD that is not the fetched commit is
1327
+ `E_BASE_UNKNOWN`; any other Git step that fails is `E_GIT_FAILED`, with
1328
+ Git's message. Either way the tree is removed.
1048
1329
  - Creating it moves none of the clone's refs. The fetch runs inside the new
1049
1330
  linked tree, which has its own `FETCH_HEAD`, and `--refmap=` keeps it from
1050
1331
  updating remote-tracking refs. The clone's `FETCH_HEAD`, branches and work
1051
1332
  tree are not touched, so creation does not race with others who use the
1052
1333
  clone. The fetched objects go to the repository's shared object store.
1334
+ - Then it fires the [`worktree` event](capabilities.md#the-worktree-event):
1335
+ the `worktree` hook of each capability the instance composes, with the
1336
+ tree as cwd. Their output goes to stderr and to
1337
+ `<home>/.oats/logs/worktree-<p>-<cap>.log`. This may take minutes; an
1338
+ instance without such a capability runs no setup.
1339
+ - Last, it marks the record `ready` (with the base commit and the hooks'
1340
+ receipt) and appends a `worktree-added` instance event.
1341
+
1342
+ The answer (`--json`: one envelope on stdout) is the receipt: `purpose`,
1343
+ `path`, `clone`, `remote`, `member`, `branch`, `base`, `baseOid`, `state`,
1344
+ `hooks` (`[{capability, ok, required, log, exitCode, …}]`), `record`,
1345
+ `resumed` and `warnings`. `--preview` resolves the clone, path, branch, base
1346
+ and hooks, and fetches and writes nothing.
1347
+
1348
+ **Running it again.**
1349
+
1350
+ | Found | Result |
1351
+ |---|---|
1352
+ | a `ready` record with the same clone, branch and base | nothing is run; the recorded receipt, `resumed: true` |
1353
+ | a `ready` record that differs | `E_PLACEMENT_TAKEN`, naming the fields that differ |
1354
+ | `.work-<p>` with no record (made with raw Git), or a file or symbolic link there | `E_PLACEMENT_TAKEN`; use another purpose, or `git worktree remove` that tree |
1355
+ | a `creating` record whose process still runs | `E_LIFECYCLE_BUSY` |
1356
+ | a `creating` record whose process is gone | the interrupted add is rolled back first, then the add runs fresh |
1357
+
1358
+ A process is "still running" when its pid runs with the recorded start
1359
+ time. It counts as gone only when its pid does not run (the operating
1360
+ system says no such process: `kill -0` fails with ESRCH), or runs with another
1361
+ start. When the start cannot be read (for example where `ps` fails), the
1362
+ process is never taken for gone. `add` and `remove` refuse with
1363
+ `E_LIFECYCLE_BUSY`, naming the pid and the exact file to remove by hand once
1364
+ you have checked it: the record `.oats/trees/<p>.json`, or the claim
1365
+ `.oats/trees/<p>.lock`. The same holds for a hook or git step the killed
1366
+ command left running: when its leader's start cannot be read, it is not
1367
+ signalled, nothing is rolled back, and the refusal names its process group
1368
+ and the way out (`kill -TERM -- -<pgid>` once checked, then retry). An `add` that is interrupted (SIGINT, SIGTERM, SIGHUP) while its hooks
1369
+ run ends the running hook, rolls back and exits 128 + the signal number
1370
+ (`E_INTERRUPTED`); one killed outright leaves the `creating` record for the
1371
+ next `add` or `remove`. A killed `add` can simply be run again. A required
1372
+ hook that fails removes the tree (`E_REQUIRED_HOOK_FAILED`). It deletes the
1373
+ branch only when that `add` created it, no worktree has it checked out, and
1374
+ it still points where `add` created it. Otherwise the branch is kept, and
1375
+ the answer names it with the reason. Two commands on one purpose never act
1376
+ at once: each holds the purpose's claim, `.oats/trees/<p>.lock`, while it
1377
+ reads and changes the record. The claim is not held while the hooks run.
1378
+ A claim left by a command that was killed is taken over by the next one,
1379
+ once its holder (pid and start time) is verified gone. Any git step the
1380
+ killed command left running is ended first, so it cannot finish late on
1381
+ the new tree. A quarantined
1382
+ home or one being retired is refused (`E_INSTANCE_RETIRING`).
1383
+
1384
+ **`remove`** runs `git worktree remove` (without `--force`) and `git worktree
1385
+ prune` on a tree `add` recorded, then drops the record. It keeps the branch
1386
+ and fires no hook. Git refuses a tree with uncommitted or untracked work:
1387
+ that is `E_WORKTREE_DIRTY`, with Git's message, and the record is kept;
1388
+ commit and push the work, or discard it, then run `remove` again. A purpose
1389
+ with no record is `E_BAD_ARGS`: remove a tree made another way with
1390
+ `git worktree remove`. Any other refusal is `E_WORK_PRESERVATION_FAILED`,
1391
+ and nothing is removed. On a `creating` record whose process is gone, `remove`
1392
+ completes the rollback instead. Its answer then says whether the branch was
1393
+ kept (`branchKept`, `branchKeptReason`).
1394
+
1395
+ **Working in the tree.**
1396
+
1053
1397
  - `git switch` needs Git 2.23 or later.
1054
- - `<branch>` follows the repository's own naming rules, else
1055
- `agents/<instance>-<purpose>`. If that branch already exists in the clone,
1056
- `switch -c` refuses: use `<instance>/<branch>`. Never `-C` or `-B`, which
1057
- reset a branch someone else may own.
1058
1398
  - The tree has no upstream. Push with `git push origin HEAD:<remote-branch>`
1059
1399
  (`<base>` when reworking an existing branch). A push does update the
1060
1400
  clone's `refs/remotes/origin/<remote-branch>`, as any push does.
1061
1401
  - Before the task closes, merge each extra tree into the PR branch, or push
1062
- its branch and name it in the hand-back; then
1063
- `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
1402
+ its branch and name it in the hand-back; then `oats worktree remove
1403
+ --purpose <p>`.
1064
1404
 
1065
1405
  `$OATS_INSTANCE_HOME` is set in every harness session OATS launches (Claude
1066
- Code, Codex, pi), not only in hooks. Retirement removes a clean extra tree
1067
- and re-homes one that holds work, but the briefing tells the agent not to
1068
- rely on it: see [extra trees at retire](#extra-trees-at-retire).
1406
+ Code, Codex, pi), not only in hooks. A tree `add` made is an ordinary extra
1407
+ tree to retirement, like one made with raw Git: retirement removes a clean
1408
+ extra tree and re-homes one that holds work, but the briefing tells the agent
1409
+ not to rely on it: see [extra trees at retire](#extra-trees-at-retire). The
1410
+ tree records and hook logs under `<home>/.oats/` are kernel receipts: they
1411
+ never count as changed instance-home bytes at retire.
1069
1412
 
1070
1413
  ## Agents root
1071
1414