@awebai/oats 0.48.0 → 0.50.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 (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. 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
  {
@@ -445,7 +448,14 @@ recovery is a standalone clone that carries the
445
448
  repository's local exclude rules (`info/exclude`, a configured
446
449
  `core.excludesFile`), its `info/attributes` and the settings that change what
447
450
  status reports (`core.fileMode`, `core.ignoreCase`, …), so its Git status
448
- 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
449
459
  cannot be verified refuses with `E_WORK_PRESERVATION_FAILED` and keeps the
450
460
  home. **`--force` does not skip work preservation.** It forces only past a
451
461
  missing or unusable cleanup marker and past incomplete hook cleanup
@@ -471,7 +481,10 @@ rewrite a file that was already modified, and the row stays the same. In
471
481
  directory mode the work state is the bytes of `work/`, with the permission
472
482
  bits of each entry and of `work/` itself. In worktree mode it
473
483
  is what a work copy of the worktree holds, each file read where the copy
474
- 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:
475
488
 
476
489
  - its Git status, the ref its HEAD is on and the commit, and, when the copy
477
490
  is made detached, the branch the repository's own HEAD is on;
@@ -506,6 +519,50 @@ equality:
506
519
  repository or deletes a branch, and a commit of the worktree that no ref
507
520
  reaches is preserved before the worktree is removed.
508
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
+
509
566
  The permission bits of the home directory and of the worktree directory
510
567
  themselves are not compared: their copies are made in directories the copier
511
568
  creates, which do not carry them.
@@ -513,11 +570,14 @@ creates, which do not carry them.
513
570
  Every part of that state is compared as its bytes, never as decoded text. A
514
571
  ref name, a path in the index or in the status, a file name or the target of
515
572
  a symbolic link need not be valid UTF-8, and two states that differ only in
516
- such bytes are two states. This is what the proof compares, not what a copy
517
- can hold: a recovery cannot hold a file whose name is not valid UTF-8. A
518
- copy of a home or a worktree that has one fails, and the retire refuses with
519
- nothing lost. A clean worktree that has one, with only the home to preserve,
520
- 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.
521
581
 
522
582
  A worktree's tags, stash, exclude rules and settings are kept by the
523
583
  repository it belongs to. They are part of the state because a work copy
@@ -539,7 +599,8 @@ file or a link that leads to one is a repository: one made by `git init` or
539
599
  a clone, a submodule, or a linked worktree of another repository placed in
540
600
  the work. One whose `.git` is a dangling symbolic link, or could not be
541
601
  tested, is not read as a repository and counts all the same: the copy
542
- 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
543
604
  state is not compared:
544
605
  the retire hooks run between the two copies and can change it in ways no read
545
606
  of its state covers (its configuration, its objects, what a clone of it is
@@ -568,19 +629,41 @@ holds of each kind:
568
629
 
569
630
  | Of the nested repository | The copy holds |
570
631
  |---|---|
571
- | the branch `HEAD` is on | the branch and its commits |
572
- | 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 |
573
635
  | tags | the tags and what they name |
574
- | the stash | its latest entry and the stash's log; the commits of older entries are not there |
575
- | 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 |
576
640
  | a repository inside it | its files, its Git directory included, as plain files |
577
641
 
578
- A commit the copy holds without a name is lost to `git gc` in the copy.
579
- `git fsck --unreachable` in the copy lists such commits, and
580
- `git branch <name> <commit>` there gives one a name again. What the copier
581
- cannot carry at all (a file whose name is not valid UTF-8, an entry that is
582
- not a file, a directory or a symbolic link) refuses the copy, here as
583
- 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.
584
667
 
585
668
  **A worktree that cannot be proven unchanged.** Two things make a worktree
586
669
  not provable:
@@ -616,7 +699,18 @@ Every refusal of the copy made before the hooks, whatever its cause, ends by
616
699
  saying what the retire has done by then: no retire hook has run, no recovery
617
700
  was written and nothing was deleted, the instance is not retired, its home
618
701
  and work are kept, and its session has been stopped, or this retire stopped
619
- 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.
620
714
 
621
715
  A snapshot that holds the home only (the work had nothing to preserve
622
716
  before the hooks) has no work copy to stand for it. It gets the work under
@@ -636,7 +730,11 @@ A worktree whose `git status` fails refuses the retire with
636
730
  `E_WORK_INSPECTION_FAILED` at the first inspection: no recovery was written,
637
731
  nothing was deleted, and the retire has not stopped the instance's session.
638
732
  A directory in place of `info/exclude`, or of the file `core.excludesFile`
639
- 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
640
738
  state that fails does not refuse here: it makes the worktree not provable,
641
739
  as described above.
642
740
 
@@ -710,10 +808,34 @@ spawn baseline, which decides whether the home has anything to preserve at
710
808
  all. When a hook moved only the work, the recovery holds them as of the
711
809
  pre-hook snapshot. The retire's own events are written to the workspace log
712
810
  (`<deployment>/.agents/events/`), never to the home's. A home copy is
713
- verified against the digest the baseline uses, which passes over those
714
- records: an inherited limit, not an exact verification of the whole home.
715
- A work copy's verification passes over every entry named `.git`: a dangling
716
- `.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.
717
839
 
718
840
  Each part under `after-hooks/` is whole and verified, not a delta, and it is
719
841
  verified before the worktree step and before the home is removed.
@@ -762,9 +884,13 @@ declared them gains no exclusion from a package update, and is copied whole.
762
884
 
763
885
  Retire stops the harness through the home's session receipt, kept beside the
764
886
  home in the instances directory's `.oats-retirement/baselines/` and keyed by
765
- the home's path. First address the home exactly as `oats status` prints it: a
766
- different spelling of its path (letter case, a deployment directory moved
767
- since the spawn) looks for the receipt elsewhere. A home can also be without
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
768
894
  its receipt because it was spawned before 0.25.9, it was copied, the
769
895
  `.oats-retirement` beside it was removed, or its creation did not finish;
770
896
  `session inspect`, `start` and `restart` then refuse with
@@ -775,8 +901,8 @@ or the recorded window is gone and no pane on that server works in the home;
775
901
  and, always, no live process on this host works in the home (a harness
776
902
  started by hand elsewhere counts). Retire then runs its hooks and preserves
777
903
  its work as usual. If the recorded window is still there, a pane or a process
778
- works in the home (the refusal names its pid), or the process scan (`lsof`)
779
- cannot run, retire refuses with
904
+ works in the home (the refusal names its pid), or the
905
+ [process scan](#the-process-scan) cannot run, retire refuses with
780
906
  `E_RUNTIME_ENDPOINT_UNKNOWN`, even with `--force`: stop that session yourself,
781
907
  then retire again. `oats retire <instance> --plan` says which case applies.
782
908
 
@@ -786,11 +912,28 @@ home. When the recorded server cannot be reached because its socket file is
786
912
  missing (after a reboot), retire proceeds only when no process on this host
787
913
  works in the home (any process whose working directory is in the home, not
788
914
  only the harness); a tmux server that lost its socket file still runs, and
789
- recreates the socket when its process is sent `SIGUSR1`. That check needs
790
- `lsof`: on a host without it, a retire whose recorded socket file is missing
791
- is refused, and the message says that `lsof` is missing; install it, then
792
- retire. A scan that does not complete (a timeout, for example) refuses the
793
- same way, also for a home without its receipt.
915
+ recreates the socket when its process is sent `SIGUSR1`. A
916
+ [process scan](#the-process-scan) that cannot run or does not complete (a
917
+ timeout, for example) refuses the same way, also for a home without its
918
+ receipt. Status, start and stop apply the same rule to a missing socket file
919
+ ([Sessions](execution-targets.md#missing-socket)).
920
+
921
+ <a id="the-process-scan"></a>
922
+ **The process scan.** "No process works in the home" comes from one scan of
923
+ the host's processes and their working directories. On Linux it reads
924
+ `/proc` (each process's `cwd` link, `comm` and `stat`); elsewhere (macOS) it
925
+ runs `lsof`. A Linux host whose `/proc/self/cwd` cannot be read uses `lsof`
926
+ too. On a host with neither, `oats doctor` says so in a
927
+ `process-scan-unavailable` information line, and retire refuses where it must
928
+ rule out a live process (a home without its session receipt, a missing
929
+ recorded tmux socket, a Herdr home), as do session start and stop when a
930
+ recorded tmux socket is missing: install `lsof`. The scan sees only the
931
+ processes this user may inspect: a process of another user, or a
932
+ non-dumpable one of the same user (such as `ssh-agent`), is not seen by
933
+ either mechanism, so one of those working in the home does not stop a
934
+ retire. Refusing whenever such a process exists would refuse on every host
935
+ (root daemons, `ssh-agent`). The harness OATS launches runs as the user and
936
+ can be inspected, and it is the process the scan exists to find.
794
937
 
795
938
  `oats retire <instance> --self` lets an instance retire itself when the human
796
939
  or briefing says it is done. A live harness cannot give a stable final
@@ -836,6 +979,45 @@ commit yet cannot be read that way: a retire that would remove it, or that
836
979
  has work of it to copy, refuses with `E_WORK_INSPECTION_FAILED` and removes
837
980
  nothing.
838
981
 
982
+ The `work/` step runs helper-free, as the extra-tree step does (no
983
+ fsmonitor, hooks, external diff or lazy fetch that the repository's
984
+ configuration names, and none of the caller's Git environment). It names the repository by its
985
+ common Git directory, read once from the repository the instance was spawned
986
+ from. That covers the default re-home (`git worktree move`), the removal
987
+ (`git worktree remove --force` and `git worktree prune`) and a quarantine
988
+ retry's checks. A removal is verified: nothing is left at `work/`, and the
989
+ repository's `git worktree list` does not name it. A removal that did not
990
+ happen, or that cannot be shown to have happened, refuses with
991
+ `E_WORK_PRESERVATION_FAILED` and keeps the home, `--force` included. That
992
+ includes a removal Git refuses (a locked worktree, for example): such a worktree is no longer deleted with the home, and no
993
+ admin entry is left behind. The refusal says what was done: the retire hooks
994
+ have run, the home is kept with any recovery the retire wrote, and whether
995
+ the session has been stopped. One exception: when nothing is at `work/`
996
+ (no entry at all: a dangling symbolic link is an entry) and the repository
997
+ cannot be read, the worktree is recorded `absent`, never `removed`. A
998
+ quarantine retry then keeps `could not verify removal` as an incomplete
999
+ item, which only `--force` clears, as the operator's explicit override.
1000
+
1001
+ A plain retire re-homes `work/` (see the extra trees below for where).
1002
+ Attached children that use this home's `work/` as their own (their
1003
+ `instance.json` says `work: "attached"` and their `work` is a link to
1004
+ `<home>/work`, directly or through an alias of it given as `--work-dir`)
1005
+ would be left with a dangling link. The retire finds them before it moves
1006
+ the worktree, and repoints a child only if its link is still the one it
1007
+ found. Each one this retire
1008
+ stopped as a recorded child is repointed to the retained worktree: a new link
1009
+ is renamed over the old one, so the link is never missing. This is the last
1010
+ step before the home is removed, once the worktree is at its new path and
1011
+ nothing is left at `work/`, and it also runs when the home is then kept for a
1012
+ retry. A relink that fails is a warning in the summary and the receipt's
1013
+ `warnings`, with the command to repoint the link by hand; the retire is not
1014
+ undone. A child that is not attached, whose link leads elsewhere, or that this
1015
+ retire did not stop is not touched. With `--discard-worktree` the worktree is
1016
+ removed and an attached child's link dangles. The retire plan names the
1017
+ attached children in one note that covers both cases. Only the link changes:
1018
+ the child's `instance.json` is not rewritten, and its AGENTS.md and TASK.md
1019
+ still name the old path.
1020
+
839
1021
  #### Extra trees at retire
840
1022
 
841
1023
  An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
@@ -871,13 +1053,23 @@ leaves `work/` untouched. For each tree:
871
1053
  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
872
1054
  `--force`) and `git worktree prune`, and verifies that the tree is gone from
873
1055
  `git worktree list`. Every Git command of this step runs helper-free (no
874
- fsmonitor, hooks or external diff the repository's configuration names). Its branch is never deleted: a commit on the branch that
1056
+ fsmonitor, hooks, external diff or lazy fetch the repository's configuration names),
1057
+ as the `work/` step's do. Its branch is never deleted: a commit on the branch that
875
1058
  was not pushed stays in the clone, on that branch.
876
1059
  - **Any other tree is re-homed**, as `work/` is by default: `git worktree
877
1060
  move` to `<deployment>/.agents/worktrees/<repo>/<leaf>`, where `<leaf>` is
878
1061
  the branch name with characters outside `A-Za-z0-9._-` replaced by `-`, or
879
1062
  `detached-<12 hex>` when HEAD is detached. A target that exists gets `-2`,
880
1063
  `-3`, and so on. A tree whose HEAD cannot be read is re-homed too.
1064
+ `work/` is re-homed under the same rule.
1065
+
1066
+ The leaf is one path component, so it is bounded: at most 231 bytes before
1067
+ its `-N` (NAME_MAX, 255, less a 16-byte margin and 8 bytes kept for `-N`;
1068
+ the leaf is ASCII, so bytes are characters). A leaf that fits is the
1069
+ flattened branch as it is. A longer one, from a long branch, is cut to 224
1070
+ bytes, its trailing `-` trimmed, and followed by `-` and the first 6 hex of
1071
+ the SHA-256 of the full branch name, so two branches that share a long
1072
+ prefix get different leaves. The plan's `movedTo` is the same name.
881
1073
  - **A tree the retire cannot handle refuses it.** A locked tree (`git worktree
882
1074
  lock`) refuses before anything runs: a retire that would remove the home
883
1075
  finds the lock in its first inspection, before the session is stopped and
@@ -906,6 +1098,100 @@ not say. The retire hooks have run by then, and no tree was moved or
906
1098
  removed. The fields are in
907
1099
  [the CLI API](desktop-cli-api.md#retire).
908
1100
 
1101
+ #### After a retire: inspect, restore, dispose
1102
+
1103
+ A retire can leave two things behind outside the removed home: a recovery
1104
+ copy and a retained worktree. Nothing in OATS removes either; each stays
1105
+ until you remove it. What follows are facts to decide with, not a judgement
1106
+ that anything is safe to delete. The uncommitted and untracked bytes in a
1107
+ recovery are in no commit: a retained worktree or the source may still hold
1108
+ them, or the recovery may be the only copy, so inspect them before you
1109
+ remove it.
1110
+
1111
+ `oats doctor` lists them all. It prints one `retained-recovery:` line per
1112
+ recovery copy in each instances directory of the deployment, and one
1113
+ `retained-worktree:` line per retained worktree. Each kind starts with a line
1114
+ that gives its total. At most 50 items follow, then `… and N more`. The lines
1115
+ are also in `oats doctor --json`, in `information[]`. They are read-only: doctor
1116
+ runs Git without helpers or optional locks, refreshes no index and follows no
1117
+ link. A fact doctor can't read is said on its line.
1118
+
1119
+ - A recovery line gives the path, the instance, `phase` and `classes` from
1120
+ `recovery.json`, the size, and whether `after-hooks/` is there. A recovery
1121
+ whose `recovery.json` is missing or unreadable is listed and says so, with
1122
+ the instance taken from the directory's name. A dot-named entry is the
1123
+ staging of a copy that a retire could not remove (`unfinished copy`).
1124
+ - A retained worktree line gives the path, the repository, the branch (or
1125
+ `detached at <commit>`), and `clean` or `not clean; uncommitted: <classes>`
1126
+ (staged or unstaged changes, conflicts, untracked or ignored files, an
1127
+ operation in progress). Doctor doesn't ask Git for the status of a
1128
+ repository whose configuration names a content filter (`filter.<driver>.clean`
1129
+ or `.process`), because the status would run it: the line says `clean:
1130
+ unknown` and names the filter. The status never enters a submodule: it
1131
+ compares only the commit each one is at. A tree with a submodule is then
1132
+ `clean: unknown (submodule work trees not read)`, or `not clean` when the
1133
+ rest of it is, with `submodule work trees not read` after it. An entry that isn't a registered worktree is listed and
1134
+ says why.
1135
+ - Both end with the reachability fact for the HEAD commit. It is checked in the
1136
+ source repository against every ref but the tree's own branch:
1137
+ `commits: all reachable from <ref>`, `commits: <n> not reachable from any
1138
+ other ref`, `commits: HEAD <commit> is not in the source repository`, or
1139
+ `commits: unknown (<why>)`. For a recovery, the HEAD is that of its `repo/`
1140
+ clone, and the source repository is the one its copied home's
1141
+ `instance.json` records. That path is only a hint: it is used only when it
1142
+ is a Git repository's top level. A recovery with no `repo/` says `commits:
1143
+ no repository copy`. When a retained worktree of the same repository is on
1144
+ the recovery's branch, the recovery line names it: the uncommitted bytes
1145
+ may be in both.
1146
+
1147
+ **Recovery copies** are at
1148
+ `<instances>/.oats-retirement/recovery/<instance>-<random>/`, beside the
1149
+ homes of the agent the instance belonged to. The retire summary prints the
1150
+ path, the receipt names it as `workRecovery.path`, and the `retired` event
1151
+ in the workspace log keeps it as `data.workRecovery`, so `oats instance
1152
+ events <instance>` still shows it after the home is gone. Its
1153
+ `recovery.json` says what it holds:
1154
+
1155
+ - `phase`: `"complete"` once the check after the retire hooks concluded;
1156
+ `"before-hooks"` when the retire stopped before that, which still leaves a
1157
+ complete, verified snapshot of the state before the hooks.
1158
+ - `classes`: what was preserved (`changed instance-home bytes`, `untracked
1159
+ or ignored worktree bytes`, `directory work bytes`, …).
1160
+ - `afterHooks`: `{home, work}`, present when the hooks changed something
1161
+ and `after-hooks/` holds a second copy of that part.
1162
+ - `home`, `outputs` and `notCopied`: the home entries copied, the untracked
1163
+ or ignored outputs copied, and the declared entries left out.
1164
+
1165
+ To inspect one, read `recovery.json`, then the parts. `repo/` is a
1166
+ standalone clone of a worktree instance's repository with its uncommitted
1167
+ state in place: `git -C <recovery>/repo status`, `git -C <recovery>/repo
1168
+ log`, `git -C <recovery>/repo stash list`. `work/` is a directory
1169
+ instance's work, `home/` the copied home (notes, `STATE.md`, …), and
1170
+ `after-hooks/` the parts as the retire hooks left them.
1171
+
1172
+ To restore from one, take what you need back into the source repository or
1173
+ wherever it belongs. Commits: fetch the branch from the recovery's clone
1174
+ under a new name, so that nothing in the source repository is overwritten:
1175
+ `git -C <source repository> fetch <recovery>/repo <branch>:refs/heads/<new
1176
+ branch>`. Uncommitted files: copy them back, or commit them in the
1177
+ recovery's clone first and fetch that branch (the recovery then no longer
1178
+ holds the state exactly as it was taken). Home files: copy them from
1179
+ `home/`.
1180
+
1181
+ To dispose of one, once its contents are settled elsewhere, remove the
1182
+ directory by hand. A copy keeps the modes of what it copied, so a read-only
1183
+ directory from the work is read-only there too: `chmod -R u+w <recovery>`,
1184
+ then `rm -rf <recovery>`.
1185
+
1186
+ **Retained worktrees** are at `<deployment>/.agents/worktrees/<repo>/<leaf>`
1187
+ (see [extra trees at retire](#extra-trees-at-retire) for the leaf). They are
1188
+ ordinary linked worktrees of the source repository, with their uncommitted
1189
+ state intact: `git -C <source repository> worktree list` lists them. Once
1190
+ the branch is merged or pushed and nothing uncommitted in the tree is still
1191
+ wanted, `git -C <source repository> worktree remove <path>` removes it; Git
1192
+ refuses a tree with uncommitted changes unless you pass `--force`. Its
1193
+ branch stays in the repository either way.
1194
+
909
1195
  ## Work modes
910
1196
 
911
1197
  A work mode decides what `./work` points at and what discipline the agent must
@@ -956,15 +1242,23 @@ a `--repo` that is not a clone of the soul's repository starts at its `HEAD`.
956
1242
  The spawn result and `instance.json` record the start point as
957
1243
  `base: {ref, oid}`.
958
1244
 
1245
+ After the spawn hooks succeed, the spawn fires the
1246
+ [`worktree` event](capabilities.md#the-worktree-event) for `work/`: the
1247
+ `worktree` hook of each capability the soul composes runs once, with `work/`
1248
+ as its cwd, inside the spawn's transaction. A required one that fails rolls
1249
+ the spawn back. The spawn result and the `spawned` event carry their receipt
1250
+ as `worktreeHooks`. A spawn whose capabilities declare no such hook runs no
1251
+ setup. No other work mode fires the event.
1252
+
959
1253
  Use this for agents that will edit code or docs independently.
960
1254
 
961
1255
  Rules:
962
1256
 
963
1257
  - Build, test, and commit from `work/`, on your own branch.
964
1258
  - Never work in a shared checkout (the repo's main checkout, or any clone
965
- others use): do not edit, commit or switch branches there. Against a clone,
966
- run only `git worktree add` and `git worktree remove`, as in
967
- [extra trees](#extra-trees).
1259
+ others use): do not edit, commit or switch branches there. A clone is
1260
+ touched only through `oats worktree add` and `oats worktree remove`
1261
+ ([extra trees](#extra-trees)).
968
1262
  - Everything you change happens in `work/` or in your extra trees.
969
1263
  - Leave your branch and the worktree list clean when your task closes.
970
1264
 
@@ -994,7 +1288,10 @@ service agents such as reviewers.
994
1288
 
995
1289
  Attached agents are guests: never switch branches or rewrite history, touch
996
1290
  only what the briefing names, keep commits small and attributable. Retiring
997
- an attached instance never removes the shared tree. The packaged
1291
+ an attached instance never removes the shared tree. When its owner retires
1292
+ and the tree is re-homed, the attached instance's `work` link is repointed to
1293
+ the tree's new path ([retire](#retire)); its AGENTS.md and TASK.md still name
1294
+ the old one. The packaged
998
1295
  `work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
999
1296
 
1000
1297
  ### `directory` — independent execution
@@ -1043,44 +1340,137 @@ The instance records no branch: the workspace is not a Git tree.
1043
1340
  An instance in `worktree` or `checkout` mode can create extra trees: linked
1044
1341
  Git worktrees in its home, beside `work/`. It does so when the work needs
1045
1342
  another branch, or another repository of the deployment (one task that
1046
- touches several repositories). The `worktree` and `checkout` briefings give
1047
- the command; the `workspace`, `directory` and `attached` briefings do not.
1048
- There is no `oats` command for it.
1343
+ touches several repositories). The `worktree` and `checkout` briefings teach
1344
+ it; the `workspace`, `directory` and `attached` briefings do not.
1049
1345
 
1050
- `<clone>` is any clone of the deployment (`oats-local.yaml` `clones:`, or
1051
- `<deployment>/<repo>`), `origin` is its remote for that repository, and
1052
- `<base>` is the remote branch the work starts from (the branch itself, to
1053
- rework an existing one):
1346
+ ```text
1347
+ oats worktree add --purpose <p> --branch <b> --base <remote-branch>
1348
+ [--repo <member key|clone path>] [--preview] [--json]
1349
+ oats worktree remove --purpose <p> [--json]
1350
+ ```
1351
+
1352
+ Both run from an instance home: the home `$OATS_INSTANCE_HOME` (or
1353
+ `$OATS_HOME`) names, else the home that encloses the working directory.
1354
+ `--dir`, `--home` and `--server` are refused (`E_BAD_ARGS`). The tree is
1355
+ `<home>/.work-<p>`.
1356
+
1357
+ **Arguments.** Each is checked before anything is written; a value that
1358
+ starts with `-` is refused (`E_BAD_ARGS`), because Git would read it as an
1359
+ option.
1360
+
1361
+ - `--purpose`: a slug, as an instance name (lowercase letters, digits and
1362
+ `-`, at most 64 characters).
1363
+ - `--branch`: a valid branch name that does not exist in the clone
1364
+ (`E_BRANCH_EXISTS`, with the remedy `<instance>/<branch>`). It follows the
1365
+ repository's own naming rules, else `agents/<instance>-<purpose>`. `add`
1366
+ never resets a branch: there is no `-C` or `-B`.
1367
+ - `--base`: the remote branch the work starts from (the branch itself, to
1368
+ rework an existing one).
1369
+ - `--repo`: the instance's repository by default. A member key is looked up
1370
+ as a spawn looks up a clone (`oats-local.yaml` `clones:`, then
1371
+ `<deployment>/<member name>`; `E_CLONE_MISSING` when there is none). A path
1372
+ (absolute, or starting with `.` or `~`) is used as given. It must be a
1373
+ clone, not a linked worktree (`E_CLONE_MISMATCH`), and have an `origin`
1374
+ remote (`E_CLONE_MISMATCH`). Not a Git repository: `E_CLONE_MISSING`.
1375
+
1376
+ **What `add` does.** It writes a record, `<home>/.oats/trees/<p>.json`, in
1377
+ state `creating`, with its own pid and start time. Then it runs, as argument
1378
+ vectors with no shell:
1054
1379
 
1055
1380
  ```bash
1056
- git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
1057
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
1058
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
1381
+ git -C <clone> worktree add --detach <home>/.work-<p>
1382
+ git -C <home>/.work-<p> fetch --refmap= origin <base>
1383
+ git -C <home>/.work-<p> switch -c <branch> <the fetched commit>
1059
1384
  ```
1060
1385
 
1061
1386
  - The tree starts from the remote's current state, never from a local branch
1062
- of the clone, which may be stale.
1387
+ of the clone, which may be stale. A fetch that fails is
1388
+ `E_REMOTE_UNREADABLE`; a HEAD that is not the fetched commit is
1389
+ `E_BASE_UNKNOWN`; any other Git step that fails is `E_GIT_FAILED`, with
1390
+ Git's message. Either way the tree is removed.
1063
1391
  - Creating it moves none of the clone's refs. The fetch runs inside the new
1064
1392
  linked tree, which has its own `FETCH_HEAD`, and `--refmap=` keeps it from
1065
1393
  updating remote-tracking refs. The clone's `FETCH_HEAD`, branches and work
1066
1394
  tree are not touched, so creation does not race with others who use the
1067
1395
  clone. The fetched objects go to the repository's shared object store.
1396
+ - Then it fires the [`worktree` event](capabilities.md#the-worktree-event):
1397
+ the `worktree` hook of each capability the instance composes, with the
1398
+ tree as cwd. Their output goes to stderr and to
1399
+ `<home>/.oats/logs/worktree-<p>-<cap>.log`. This may take minutes; an
1400
+ instance without such a capability runs no setup.
1401
+ - Last, it marks the record `ready` (with the base commit and the hooks'
1402
+ receipt) and appends a `worktree-added` instance event.
1403
+
1404
+ The answer (`--json`: one envelope on stdout) is the receipt: `purpose`,
1405
+ `path`, `clone`, `remote`, `member`, `branch`, `base`, `baseOid`, `state`,
1406
+ `hooks` (`[{capability, ok, required, log, exitCode, …}]`), `record`,
1407
+ `resumed` and `warnings`. `--preview` resolves the clone, path, branch, base
1408
+ and hooks, and fetches and writes nothing.
1409
+
1410
+ **Running it again.**
1411
+
1412
+ | Found | Result |
1413
+ |---|---|
1414
+ | a `ready` record with the same clone, branch and base | nothing is run; the recorded receipt, `resumed: true` |
1415
+ | a `ready` record that differs | `E_PLACEMENT_TAKEN`, naming the fields that differ |
1416
+ | `.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 |
1417
+ | a `creating` record whose process still runs | `E_LIFECYCLE_BUSY` |
1418
+ | a `creating` record whose process is gone | the interrupted add is rolled back first, then the add runs fresh |
1419
+
1420
+ A process is "still running" when its pid runs with the recorded start
1421
+ time. It counts as gone only when its pid does not run (the operating
1422
+ system says no such process: `kill -0` fails with ESRCH), or runs with another
1423
+ start. When the start cannot be read (for example where `ps` fails), the
1424
+ process is never taken for gone. `add` and `remove` refuse with
1425
+ `E_LIFECYCLE_BUSY`, naming the pid and the exact file to remove by hand once
1426
+ you have checked it: the record `.oats/trees/<p>.json`, or the claim
1427
+ `.oats/trees/<p>.lock`. The same holds for a hook or git step the killed
1428
+ command left running: when its leader's start cannot be read, it is not
1429
+ signalled, nothing is rolled back, and the refusal names its process group
1430
+ and the way out (`kill -TERM -- -<pgid>` once checked, then retry). An `add` that is interrupted (SIGINT, SIGTERM, SIGHUP) while its hooks
1431
+ run ends the running hook, rolls back and exits 128 + the signal number
1432
+ (`E_INTERRUPTED`); one killed outright leaves the `creating` record for the
1433
+ next `add` or `remove`. A killed `add` can simply be run again. A required
1434
+ hook that fails removes the tree (`E_REQUIRED_HOOK_FAILED`). It deletes the
1435
+ branch only when that `add` created it, no worktree has it checked out, and
1436
+ it still points where `add` created it. Otherwise the branch is kept, and
1437
+ the answer names it with the reason. Two commands on one purpose never act
1438
+ at once: each holds the purpose's claim, `.oats/trees/<p>.lock`, while it
1439
+ reads and changes the record. The claim is not held while the hooks run.
1440
+ A claim left by a command that was killed is taken over by the next one,
1441
+ once its holder (pid and start time) is verified gone. Any git step the
1442
+ killed command left running is ended first, so it cannot finish late on
1443
+ the new tree. A quarantined
1444
+ home or one being retired is refused (`E_INSTANCE_RETIRING`).
1445
+
1446
+ **`remove`** runs `git worktree remove` (without `--force`) and `git worktree
1447
+ prune` on a tree `add` recorded, then drops the record. It keeps the branch
1448
+ and fires no hook. Git refuses a tree with uncommitted or untracked work:
1449
+ that is `E_WORKTREE_DIRTY`, with Git's message, and the record is kept;
1450
+ commit and push the work, or discard it, then run `remove` again. A purpose
1451
+ with no record is `E_BAD_ARGS`: remove a tree made another way with
1452
+ `git worktree remove`. Any other refusal is `E_WORK_PRESERVATION_FAILED`,
1453
+ and nothing is removed. On a `creating` record whose process is gone, `remove`
1454
+ completes the rollback instead. Its answer then says whether the branch was
1455
+ kept (`branchKept`, `branchKeptReason`).
1456
+
1457
+ **Working in the tree.**
1458
+
1068
1459
  - `git switch` needs Git 2.23 or later.
1069
- - `<branch>` follows the repository's own naming rules, else
1070
- `agents/<instance>-<purpose>`. If that branch already exists in the clone,
1071
- `switch -c` refuses: use `<instance>/<branch>`. Never `-C` or `-B`, which
1072
- reset a branch someone else may own.
1073
1460
  - The tree has no upstream. Push with `git push origin HEAD:<remote-branch>`
1074
1461
  (`<base>` when reworking an existing branch). A push does update the
1075
1462
  clone's `refs/remotes/origin/<remote-branch>`, as any push does.
1076
1463
  - Before the task closes, merge each extra tree into the PR branch, or push
1077
- its branch and name it in the hand-back; then
1078
- `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
1464
+ its branch and name it in the hand-back; then `oats worktree remove
1465
+ --purpose <p>`.
1079
1466
 
1080
1467
  `$OATS_INSTANCE_HOME` is set in every harness session OATS launches (Claude
1081
- Code, Codex, pi), not only in hooks. Retirement removes a clean extra tree
1082
- and re-homes one that holds work, but the briefing tells the agent not to
1083
- rely on it: see [extra trees at retire](#extra-trees-at-retire).
1468
+ Code, Codex, pi), not only in hooks. A tree `add` made is an ordinary extra
1469
+ tree to retirement, like one made with raw Git: retirement removes a clean
1470
+ extra tree and re-homes one that holds work, but the briefing tells the agent
1471
+ not to rely on it: see [extra trees at retire](#extra-trees-at-retire). The
1472
+ tree records and hook logs under `<home>/.oats/` are kernel receipts: they
1473
+ never count as changed instance-home bytes at retire.
1084
1474
 
1085
1475
  ## Agents root
1086
1476