@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.
- package/bin/oats.mjs +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- 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.
|
|
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.
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
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
|
|
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
|
|
572
|
-
| every
|
|
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 |
|
|
575
|
-
|
|
|
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
|
-
|
|
579
|
-
|
|
580
|
-
`
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
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
|
|
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.
|
|
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
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
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
|
|
766
|
-
|
|
767
|
-
|
|
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
|
|
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`.
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
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
|
|
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.
|
|
966
|
-
|
|
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.
|
|
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
|
|
1047
|
-
|
|
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
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
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
|
|
1057
|
-
git -C
|
|
1058
|
-
git -C
|
|
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
|
-
|
|
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.
|
|
1082
|
-
|
|
1083
|
-
|
|
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
|
|