@awebai/oats 0.42.0 → 0.43.0

package/docs/release-notes/v0.42.1.md

@@ -0,0 +1,110 @@
+# OATS 0.42.1
+
+## Changed
+
+- **Remote roster rows carry the local row's work, repository, branch,
+  model-from, soul and module drift facts**
+  ([#675](https://github.com/awebai/oats/issues/675)). A remote instance
+  row (`oats server roster --json`, and the Desktop's remote roster) now
+  relays `work`, `repo`, `branch`, `modelFrom`, `soul` and `modules` from
+  the host's own `oats status --json` row, with the same names and meaning
+  as on a local row. `soul` and `modules` are the host's own drift
+  observation, relayed as it answered; nothing is recomputed on this side,
+  and `repo` is the host's path. Each is always present, `null` from a host
+  that doesn't report it (an older host, a fact it never recorded, or a saved
+  route the host no longer lists). See
+  [the remote roster](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json).
+
+- **The `worktree` and `checkout` briefings allow extra trees, and give the
+  command** ([#674](https://github.com/awebai/oats/issues/674)). Both
+  briefings forbade extra Git worktrees: `worktree` said "Don't create extra
+  worktrees; `work/` is your one tree", and `checkout` said to ask for a
+  worktree-mode instance for work that needs its own branch. That
+  contradicted the shipped `oats.engineering` package, whose developer
+  briefing and `/worktrees` skill say "your work-mode briefing has the
+  command", with `.work-<purpose>` in the home as the default place. No
+  briefing gave that command. The case that needs it is a developer whose
+  one task touches several repositories of the deployment.
+
+  Both briefings now carry the same short paragraph. An extra tree is created
+  in the home, from any clone of the deployment (`oats-local.yaml` `clones:`,
+  or `<deployment>/<repo>`), from the remote's current state:
+
+  ```bash
+  git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+  git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+  git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+  ```
+
+  The fetch runs inside the new tree, which has its own `FETCH_HEAD`, so
+  creating it moves none of the clone's refs. The paragraph also covers
+  branch names (the repository's rules, else `agents/<instance>-<purpose>`;
+  never `-C` or `-B`), pushing a tree without an upstream
+  (`git push origin HEAD:<remote-branch>`), and closing: merge each tree into
+  the PR branch or push it and name it in the hand-back, then
+  `git -C <clone> worktree remove`. `git switch` needs Git 2.23 or later.
+
+  `worktree` mode now says never to work in a shared checkout (the main
+  checkout, or any clone others use), and that changes happen in `work/` or
+  in the extra trees. It drops "Parallel work means your human spawns
+  another instance". `checkout` mode now says that work needing its own
+  branch goes in an extra tree, not in `work/`. The `workspace`, `directory`
+  and `attached` briefings do not change, and there is no new `oats`
+  command. The instance-boundary block every instance receives said repository
+  work happens in `work/` "and only there"; it now says "there, or in the
+  extra trees your mode block grants, and nowhere else", so the two blocks
+  no longer disagree. Instances spawned before the upgrade keep the briefing
+  they were spawned with. See
+  [souls and instances](../souls-and-instances.md#extra-trees).
+
+- **Retire protects extra trees in the home**
+  ([#674](https://github.com/awebai/oats/issues/674)). An extra tree is a
+  top-level `.work-*` entry of the home that Git confirms is a linked
+  worktree of some repository. Before, retire treated it as home bytes: it
+  copied it to recovery and removed it with the home, leaving the
+  repository's admin entry behind. Now, in every work mode:
+
+  - A verified extra tree is not copied to recovery. `workRecovery.notCopied`
+    lists it with `owner: "kernel:extra-worktree"`. A `.work-*` entry that
+    does not verify (a plain directory, a symbolic link, a full clone), or
+    that belongs to a repository inside the home, is copied as before.
+  - When the home is removed, the retire handles each tree after its hooks
+    and before the `work/` worktree step. A clean tree (empty status,
+    ignored and untracked files included; no operation in progress; HEAD
+    reached by a ref of its repository, not only by the tree's own) is
+    removed with `git worktree remove` and pruned. Its branch is kept. Any
+    other tree is moved, as `work/` is retained, to
+    `<deployment>/.agents/worktrees/<repo>/<branch>`.
+  - A locked tree refuses the retire with `E_WORK_PRESERVATION_FAILED`
+    before anything runs: no session is stopped and no retire hook runs. A
+    move or removal Git refuses refuses it after the hooks. Either way the
+    home is kept. `--force` does not bypass it, and `--discard-worktree` does
+    not apply to extra trees.
+  - With `--keep-dir`, or when the home is kept for a retry, the trees stay
+    where they are.
+
+  `oats retire <instance> --plan` adds `facts.extraWorktrees` (`[{path, repo,
+  branch, detachedAt, disposition, movedTo, reason}]`, empty when there are
+  none) and one `notes` string per tree. The trees are part of
+  `planRevision`: a tree created, removed, dirtied or cleaned between the plan
+  and the apply refuses the apply with `E_PLAN_STALE`. The retire receipt adds
+  `extraWorktrees` (the plan's row plus `outcome`), present when a tree was
+  handled. The `worktree-removed` and `worktree-retained` events for an extra
+  tree carry `extra: true` and its `path`. All keys are additive. See
+  [souls and instances](../souls-and-instances.md#extra-trees-at-retire) and
+  [the CLI API](../desktop-cli-api.md#retire).
+
+## Fixed
+
+- **The context panel shows the soul and teams of an instance on a server**
+  ([#675](https://github.com/awebai/oats/issues/675)). The Soul tab and the
+  Messaging & Teams list were empty for an instance on a registered server.
+  They now read through the server by the instance's home, as the soul page
+  does, and say "Reading from <server>…" while they wait. The Soul tab's
+  header shows the soul's description from the server's roster. The Work
+  card, the "model from" line and the "older build" chip show the facts the
+  server relays. When a part can't be shown, it says why and what to update:
+  this computer's OATS when it can't route the read or doesn't relay the
+  facts, the server's OATS when it lacks the feature or doesn't report them.
+  A server's other refusals show its code and message, as the rest of the
+  panel does.

package/docs/release-notes/v0.43.0.md

@@ -0,0 +1,93 @@
+# OATS 0.43.0
+
+## Added
+
+- **A one-line summary for every schedule and trigger** (feature
+  `automation-descriptions`). One rule covers every kind and level. A
+  `description` is one line of 1 to 200 characters with no control characters
+  (no `\p{Cc}`, U+2028 or U+2029). Before this, only local schedules could
+  carry one.
+  - **Local triggers take `description`.** Out of the rule it is refused as
+    `E_TRIGGER_INVALID {field: "description"}`. `oats trigger list` and `show`
+    used to send `null` for every local trigger; they now show it.
+  - **Package trigger templates may carry `definition.description`.** It is
+    validated like any trigger's. `oats trigger add --from` copies it, and
+    `--description=<text>` overrides it. A workspace trigger made `from:` a
+    template shows its file header's description, or the template's when the
+    header has none. A kernel before 0.43.0 refuses the key, so a package
+    whose template sets it needs `compatibility.oats: ">=0.43.0"`.
+  - **`--description=<text>` on `oats schedule add` and `oats trigger add`**
+    sets the description, or overrides the one in the spec. `--description=`
+    with an empty value leaves it out. With `--workspace`, the description goes
+    to the file header, never into the body.
+  - **Change only the description:**
+
+    ```sh
+    oats schedule update <id> --description=<text>   # without --file/--spec-json
+    oats trigger update <id> --description=<text>
+    ```
+
+    `--description=` clears it. Both work on local schedules and triggers
+    only; a workspace one is changed in Git (`E_AUTOMATION_WORKSPACE`). A
+    schedule's description may change while the job runs or has an unresolved
+    attempt, and the update runs under the same locks as any other. A
+    trigger's fired and pending events are untouched. `oats trigger update`
+    takes no other flag for now (`E_BAD_ARGS`): a full trigger update is still
+    a remove and an add. `oats schedule … --server <id>` with `--description`
+    needs the destination to advertise `automation-descriptions`
+    (`E_REMOTE_INCOMPATIBLE` otherwise).
+
+  The Desktop gates its summary writes on the feature. See
+  [schedules](../schedules.md#kinds) and the
+  [Desktop CLI API](../desktop-cli-api.md#automations-shared-rows).
+
+### Desktop
+
+- **Schedules and Triggers show each item's summary.** A row shows the item's
+  name beside its origin tag (`local`, or the member), in place of
+  `local/<id>`, and its summary under it. Without a summary, the row shows the
+  first non-empty line of the task or wake message in muted italics, titled "No
+  summary set — first line of the prompt". A command or operation row without
+  one shows "No summary": the Desktop never makes a label from argv.
+- **A detail page shows everything an item does**
+  ([#545](https://github.com/awebai/oats/issues/545)). The title is the name,
+  with the qualified id under it, and then the summary or "No summary".
+  - **What it sends, in full:** a spawn's or trigger's task; a wake's whole
+    message and the home it wakes (before, a wake said "No prompt"); a
+    command's argv exactly as written, one argument per chip, and its working
+    directory; an operation and the home it runs in.
+  - **Spawns** also shows a spawn schedule's purpose (never shown before),
+    harness and model, launch configuration, permissions, session backend, and
+    the spawn's own recurring wake.
+  - **Run state** shows a schedule that is running and since when. It also
+    shows a run whose state is unknown and since when, with its exit facts,
+    whether it still holds a host slot, *Check run state* and the
+    `oats schedule reconcile <id> [--clear]` command to paste. A held job lock
+    no longer hides an unknown run. It also shows a wake waiting to be delivered.
+  - **An Invalid or Unreadable item** gets a card with its code, field and
+    message. Before, they appeared only in a tag's tooltip.
+  - **Comes from** adds the package template an item was made from (package,
+    version, commit) and a local item's created and updated times.
+- **Set a summary from the Desktop** (needs a CLI with
+  `automation-descriptions`). The schedule form has an optional **Summary**
+  field. **Edit summary** sets or clears the summary of any local schedule
+  (command ones included) or local trigger, from the detail page or the row
+  menu; it runs `oats <kind> update <id> --description=<text>`. The text is
+  saved as typed, and an empty value removes it. A workspace item's summary is
+  its file's `description:` in Git. With an older CLI, the Desktop shows the
+  summaries it reports and the form keeps a stored summary unchanged.
+
+## Changed
+
+- **A workspace file header whose `description` breaks the rule is a warning,
+  not a refusal.** Before, a non-string header description stopped the entry
+  (`E_AUTOMATION_SCHEMA`), and any other value was accepted unchecked. Now the
+  entry still loads and runs, with `description: null`, and the snapshot
+  reports an `E_AUTOMATION_SCHEMA` problem at `<path>#/description`:
+  "description: one line of 1 to 200 characters without control characters —
+  shorten it or remove it; the automation keeps running without one". A label
+  never stops a job. `oats trigger|schedule add --workspace` refuses an
+  out-of-rule description before it writes the file.
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.44.0`**, so it runs against
+  this release's kernel; the Desktop 0.42.x refuses a 0.43 CLI. Upgrade the
+  Desktop and the CLI together.

package/docs/schedules.md

@@ -52,14 +52,21 @@ both are evaluated by the croner library. Schedule IDs use lowercase letters,
 digits and dashes, from 1 to 100 characters. Spawn schedules with a long ID
 need an explicit shorter `purpose` to fit the instance-name limit below.
 
-Any kind may carry `description`: what the job is for, in words, for the
-people reading `oats schedule list`, `show` and the Desktop. It is one line of
-1 to 200 characters with no control characters (no CR, LF, TAB or any other
-C0 or C1 character, nor a Unicode line or paragraph separator); anything else
-is `E_SCHEDULE_INVALID` with `field: "description"`. It is stored as given and
-is informational only: it never reaches a run's argv, environment, task or
-reconcile. A capability that registers jobs (knowledge harvest's `run-source`
-jobs) sets it so that its command jobs can be told apart.
+Every schedule and trigger, of any kind, may carry `description`: what it is
+for, in words, for the people reading `oats schedule list`, `oats trigger
+list`, `show` and the Desktop. It is one line of 1 to 200 characters with no
+control characters (no CR, LF, TAB or any other C0 or C1 character, nor a
+Unicode line or paragraph separator). A local schedule or trigger that breaks
+the rule is refused, `E_SCHEDULE_INVALID` or `E_TRIGGER_INVALID` with `field:
+"description"`; a workspace file's header that breaks it is only a warning
+(see [the header](#workspace-triggers-and-schedules)). It is stored as given
+and is informational only: it never reaches a run's argv, environment, task,
+template or reconcile. A capability that registers jobs (knowledge harvest's
+`run-source` jobs) sets it so that its command jobs can be told apart. Set it
+in the definition or with `--description=<text>` on `add`; change only it with
+`update <id> --description=<text>` (see [Commands](#commands)). Local triggers
+take it from OATS 0.43.0 (feature `automation-descriptions`); an older kernel
+refuses the key on a trigger.
 
 - **spawn** `{…, agent, agentsRoot?, repo?, backend?, purpose?, task,
   launchConfig?, harness?, model?, yolo?, wake?}` — every due minute launches
@@ -131,6 +138,7 @@ when the timer cannot reach it.
 
 ```json
 { "id": "okf-harvest-review", "enabled": true, "kind": "trigger",
+  "description": "Review every harvest PR on the knowledge base",
   "on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
           "events": ["opened", "reopened", "ready_for_review"],
           "labels": ["okf-harvest"], "base": "main", "poll": "2m" },
@@ -178,15 +186,19 @@ when the timer cannot reach it.
   harness, and is recorded in `instance.json.trigger`.
 
 ```sh
-oats trigger add --file trigger.json                 # or:
-oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>]
+oats trigger add --file trigger.json [--description=<text>]   # or:
+oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
+oats trigger update <id> --description=<text>   # the description only; --description= clears it
 oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
 oats trigger test <id>      # dry run: gh credentials, repo permissions, the soul, what WOULD fire
 oats trigger status [<id>]  # last poll, next due, pending and fired events, live vs max, last error
 ```
 
 All take `--dir` and `--json` (`triggerApi: 1`). `remove` leaves the instances
-it spawned running. `oats schedule list` does not list triggers but counts
+it spawned running. `update` changes only a local trigger's description (any
+other flag is `E_BAD_ARGS`: a full trigger update is a remove and an add); it
+sets `updatedAt` and leaves the trigger's fired and pending events as they
+are. A workspace trigger is changed in Git (`E_AUTOMATION_WORKSPACE`). `oats schedule list` does not list triggers but counts
 them (`triggers: { count, command: "oats trigger list" }`, and a line in text
 mode). Errors: `E_TRIGGER_INVALID { field }`, `E_TRIGGER_EXISTS`,
 `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_BAD_ARGS`.
@@ -196,8 +208,10 @@ in `oats-package.json`, each file `{ parameters: { <name>: { path, required?,
 default?, description? } }, definition }`. `oats trigger add --from
 <package>:<id>` reads it at the locked commit, and `--set <name>=<value>`
 fills a parameter at its dotted `path` (a list value is comma-separated; a
-missing required one is `E_BAD_ARGS { missing }`). See
-[packages.md](packages.md#trigger-templates).
+missing required one is `E_BAD_ARGS { missing }`). A template's `definition`
+may carry `description` (validated like any trigger's): `add --from` copies
+it, and `--description=<text>` overrides it (`--description=` leaves it out).
+See [packages.md](packages.md#trigger-templates).
 
 ## Workspace triggers and schedules
 
@@ -246,6 +260,15 @@ owner: github.com/ana
   `runsOn` and `owner`, and optionally `id`, `description` and `enabled`. A
   candidate of the wrong kind (a schedule in `oats-triggers/`) or without one
   is an `E_AUTOMATION_SCHEMA` problem, never silently skipped.
+- **The description** follows the [one rule](#kinds), but a header that
+  breaks it does not stop the job: the entry still loads and runs as if it
+  had none (`description: null`), and the snapshot reports an `E_AUTOMATION_SCHEMA`
+  problem at `<path>#/description` ("description: one line of 1 to 200
+  characters without control characters — shorten it or remove it; the
+  automation keeps running without one"). A trigger made `from:` a package
+  template shows the header's description, else the template's. It lives in
+  the header only: `add --workspace` writes the flag's (else the spec's) there,
+  never into the body.
 - **The id** is `id:`, else the filename stem. The same id twice in one member
   for one kind is `E_AUTOMATION_DUPLICATE`, naming both paths; the second file
   is not listed. Schedule IDs allow 1 to 100 lowercase letters, digits and dashes; trigger
@@ -312,8 +335,9 @@ check the placement and everything else on this host.
 ## Commands
 
 ```sh
-oats schedule add <id> --file spec.json [--dir <deployment>] [--json]
-oats schedule update <id> --file spec.json
+oats schedule add <id> --file spec.json [--description=<text>] [--dir <deployment>] [--json]
+oats schedule update <id> --file spec.json [--description=<text>]
+oats schedule update <id> --description=<text>   # the description only; --description= clears it
 oats schedule list | show <id> | enable <id> | disable <id> | remove <id> [--force]
 oats schedule run <id> [--force]  # now, under the same lock and bound
 oats schedule test <id>           # dry run: where it runs, whether its soul resolves, when it is next due
@@ -326,6 +350,16 @@ oats schedule host status | uninstall
 oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --wake-file spec.json
 ```
 
+`--description=<text>` sets the spec's `description`, or overrides it;
+`--description=` (empty) removes it. Take the `=` form: it is the one that
+carries an empty value, or one that starts with `-`. With `--file` or
+`--spec-json`, `update` replaces the whole definition as before (one without a
+description drops it). Without them, `update <id> --description=<text>`
+changes only the description of a local schedule, under the same locks, and
+is allowed while the job runs or has an unresolved attempt. With `--server`,
+the destination must advertise `automation-descriptions`
+(`E_REMOTE_INCOMPATIBLE` otherwise, before anything is forwarded).
+
 `<id>` is `local/<id>` (or the bare id) or `<member>/<id>`. `host uninstall`
 unregisters the deployment and removes the timer once none is registered.
 Every `oats schedule` subcommand takes `--server <id>` instead of `--dir` to

package/docs/servers.md

@@ -300,7 +300,10 @@ before 0.36.0, `null` when it reports none or the probe failed), the remote soul
 the host's own facts from its `status --json`: `identity`,
 `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
 `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
-`relativeTo` and `spawnOrigin`. A fact the host does not supply is `null`
+`relativeTo`, `spawnOrigin`, and (0.42.1) `work`, `repo`, `branch`,
+`modelFrom`, `soul` and `modules`: the local row's facts, with `soul` and
+`modules` the host's own drift observation, never recomputed here, and
+`repo` a path on the host. A fact the host does not supply is `null`
 (an older host, or a saved route the host no longer lists). A row also
 carries `waitingOnYou` (needs input) when the host's kernel reports it, and
 only then: an older host's row has no such key. A removed or edited registration keeps

package/docs/souls-and-instances.md

@@ -809,6 +809,76 @@ commit yet cannot be read that way: a retire that would remove it, or that
 has work of it to copy, refuses with `E_WORK_INSPECTION_FAILED` and removes
 nothing.
 
+#### Extra trees at retire
+
+An instance can hold [extra trees](#extra-trees) in its home beside `work/`.
+Retire handles them itself, so the home removal never deletes their work.
+
+An **extra tree** is a top-level entry of the home named `.work-*` that is a
+real directory (not a symbolic link), whose `.git` is a regular file, and that
+Git confirms is a registered linked worktree of some repository: its Git
+directory differs from its common directory, its top level is the entry
+itself, and that repository's `git worktree list` names it. Its repository is
+the first entry of that list (the main worktree, or the bare repository).
+Anything named `.work-*` that does not verify (a plain directory, an orphaned
+`.git` file, a symbolic link, a nested full clone), or that is a worktree of a
+repository inside the home itself, is ordinary home bytes, and the home's
+recovery copies it as before (with that repository). This holds in every work mode,
+`directory` included.
+
+A verified extra tree is not part of the home's recovery bytes: it does not
+count as changed instance-home bytes, it is not copied, and the recovery's
+`notCopied` lists it as `{scope: "home", path: ".work-<purpose>", owner:
+"kernel:extra-worktree"}`.
+
+The extra-tree step runs only when the home is going to be removed: not with
+`--keep-dir`, and not when the retire keeps the home for a retry. That is the
+condition of the `work/` worktree step (nothing outstanding, or `--force`).
+It runs after the retire hooks and before the `work/` step, so a refusal
+leaves `work/` untouched. For each tree:
+
+- **A clean tree is removed.** Clean means that `git status`, ignored and
+  untracked files included, is empty; no merge, rebase, cherry-pick, revert,
+  bisect or sequencer operation is in progress; and its HEAD commit is
+  reached by a ref of its repository (the tree's own HEAD, reflog and
+  `refs/worktree/` refs do not count: they go with its admin entry). The retire runs `git worktree remove` (without
+  `--force`) and `git worktree prune`, and verifies that the tree is gone from
+  `git worktree list`. Every Git command of this step runs helper-free (no
+  fsmonitor, hooks or external diff the repository's configuration names). Its branch is never deleted: a commit on the branch that
+  was not pushed stays in the clone, on that branch.
+- **Any other tree is re-homed**, as `work/` is by default: `git worktree
+  move` to `<deployment>/.agents/worktrees/<repo>/<leaf>`, where `<leaf>` is
+  the branch name with characters outside `A-Za-z0-9._-` replaced by `-`, or
+  `detached-<12 hex>` when HEAD is detached. A target that exists gets `-2`,
+  `-3`, and so on. A tree whose HEAD cannot be read is re-homed too.
+- **A tree the retire cannot handle refuses it.** A locked tree (`git worktree
+  lock`) refuses before anything runs: a retire that would remove the home
+  finds the lock in its first inspection, before the session is stopped and
+  before any retire hook, and stops with "nothing was run or removed". A lock
+  that appears while the hooks run is refused at the step, before any tree is
+  touched. A move or a removal that Git refuses (a tree with submodules, for
+  example), or a removal that cannot be verified, refuses at the step, after
+  the hooks. Each refusal is `E_WORK_PRESERVATION_FAILED` naming the tree,
+  and the home is kept. At the step, trees already handled in that pass stay
+  handled, and the message says what was done. `--force` does not bypass it:
+  it forces past hook cleanup, not past local work.
+
+`--discard-worktree` applies to `work/` only: a tree that is not clean is
+always re-homed. The retire writes one workspace event per handled tree
+(`worktree-removed` or `worktree-retained`, with `extra: true` and the tree's
+`path`), and its summary prints one line per tree: removed, or re-homed to
+the new path.
+
+`oats retire <instance> --plan` lists the trees and what the retire would do
+with each, and they are part of the plan's revision: a tree created, removed,
+dirtied or cleaned between the plan and a guarded apply, or a new target for
+it, refuses the apply with `E_PLAN_STALE` before anything runs. The retire
+checks the trees again at the step itself and refuses with `E_PLAN_STALE`,
+keeping the home, rather than move or remove a tree in a way the plan did
+not say. The retire hooks have run by then, and no tree was moved or
+removed. The fields are in
+[the CLI API](desktop-cli-api.md#retire).
+
 ## Work modes
 
 A work mode decides what `./work` points at and what discipline the agent must
@@ -824,7 +894,8 @@ instructions state first (`injects/instance-boundary.md`):
   target another one deliberately).
 - `<instance-home>/work` — the repository or workspace view — is where
   repository reading, editing, building, testing, git and commits happen, to the
-  extent the mode below permits.
+  extent the mode below permits. In `worktree` and `checkout` mode, the
+  instance's [extra trees](#extra-trees) in the home serve the same purpose.
 - The home has no soul link: the composed `AGENTS.md` already carries the
   soul's instructions, and `instance.json` `soulDir` records the (read-only,
   per-commit) soul directory every hook and dispatched command receives as
@@ -863,10 +934,12 @@ Use this for agents that will edit code or docs independently.
 Rules:
 
 - Build, test, and commit from `work/`, on your own branch.
-- Never run git from the repo's main checkout — it resolves to the wrong branch
-  and skips review.
-- Do not create extra worktrees. Ask for another instance if parallel work is
-  needed.
+- Never work in a shared checkout (the repo's main checkout, or any clone
+  others use): do not edit, commit or switch branches there. Against a clone,
+  run only `git worktree add` and `git worktree remove`, as in
+  [extra trees](#extra-trees).
+- Everything you change happens in `work/` or in your extra trees.
+- Leave your branch and the worktree list clean when your task closes.
 
 ### `checkout` — shared current branch
 
@@ -880,7 +953,10 @@ Rules:
 
 - Stay on the currently checked-out branch.
 - Do not switch branches unless explicitly asked.
-- Avoid destructive git operations unless the human explicitly asks.
+- No destructive git operations (`reset --hard`, rebase, force-push, checkout
+  of another branch) unless the human explicitly asks.
+- Work that needs its own branch goes in an [extra tree](#extra-trees), not
+  in `work/`.
 
 ### `attached` — another instance's tree
 
@@ -935,6 +1011,50 @@ Rules:
 
 The instance records no branch: the workspace is not a Git tree.
 
+### Extra trees
+
+An instance in `worktree` or `checkout` mode can create extra trees: linked
+Git worktrees in its home, beside `work/`. It does so when the work needs
+another branch, or another repository of the deployment (one task that
+touches several repositories). The `worktree` and `checkout` briefings give
+the command; the `workspace`, `directory` and `attached` briefings do not.
+There is no `oats` command for it.
+
+`<clone>` is any clone of the deployment (`oats-local.yaml` `clones:`, or
+`<deployment>/<repo>`), `origin` is its remote for that repository, and
+`<base>` is the remote branch the work starts from (the branch itself, to
+rework an existing one):
+
+```bash
+git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+```
+
+- The tree starts from the remote's current state, never from a local branch
+  of the clone, which may be stale.
+- Creating it moves none of the clone's refs. The fetch runs inside the new
+  linked tree, which has its own `FETCH_HEAD`, and `--refmap=` keeps it from
+  updating remote-tracking refs. The clone's `FETCH_HEAD`, branches and work
+  tree are not touched, so creation does not race with others who use the
+  clone. The fetched objects go to the repository's shared object store.
+- `git switch` needs Git 2.23 or later.
+- `<branch>` follows the repository's own naming rules, else
+  `agents/<instance>-<purpose>`. If that branch already exists in the clone,
+  `switch -c` refuses: use `<instance>/<branch>`. Never `-C` or `-B`, which
+  reset a branch someone else may own.
+- The tree has no upstream. Push with `git push origin HEAD:<remote-branch>`
+  (`<base>` when reworking an existing branch). A push does update the
+  clone's `refs/remotes/origin/<remote-branch>`, as any push does.
+- Before the task closes, merge each extra tree into the PR branch, or push
+  its branch and name it in the hand-back; then
+  `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
+
+`$OATS_INSTANCE_HOME` is set in every harness session OATS launches (Claude
+Code, Codex, pi), not only in hooks. Retirement removes a clean extra tree
+and re-homes one that holds work, but the briefing tells the agent not to
+rely on it: see [extra trees at retire](#extra-trees-at-retire).
+
 ## Agents root
 
 Instance homes live under the deployment's agents root,

package/injects/instance-boundary.md

@@ -26,9 +26,10 @@ root, and not the work tree. Anything that says "your home" means this directory
 **`<instance-home>/work` is your repository or workspace view** — whatever your
 work mode grants you of the code.
 
-- **Repository work happens there and only there**: reading, editing, building,
-  testing, git and commits, on repository content. Never from the main checkout
-  or from your home root.
+- **Repository work happens there, or in the extra trees your mode block
+  grants, and nowhere else**: reading, editing, building, testing, git and
+  commits, on repository content. Never from the main checkout or from your
+  home root, beyond what your mode block names.
 - **What your mode permits is the mode block's call**, immediately below. Some
   modes are read-only, some share a tree with others, and that block is the
   authority on which operations are yours to perform.

package/injects/work-checkout.md

@@ -7,6 +7,28 @@ in the same tree as the human and possibly other agents.
   explicitly asked.**
 - No destructive git operations (reset --hard, rebase, force-push, checkout
   of another branch) without an explicit human instruction.
-- This mode fits integrator/coordinator/advisory roles operating on the
-  repo's *current state*; if your task needs its own branch, ask your human
-  for a worktree-mode instance instead.
+- Work that needs its own branch goes in an extra tree, not in `work/`.
+
+### Extra trees
+
+When the work needs another branch, or another repository of this deployment,
+create an extra tree in your home. `<clone>` is any clone of this deployment
+(`oats-local.yaml` `clones:`, or `<deployment>/<repo>`); `origin` is its remote
+for that repository; `<base>` is the remote branch the work starts from (the
+branch itself, when you rework an existing one):
+
+    git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+
+- This starts from the remote's current state and moves none of the clone's
+  refs. Never start from a local branch of the clone, which may be stale.
+- Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
+  If it already exists in that clone, `switch -c` refuses: use `<instance>/<branch>`.
+  Never `-C`/`-B`, which reset a branch someone else may own.
+- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
+  (`<base>` when you rework an existing branch).
+- Before your task closes, merge each extra tree into your PR branch, or push its
+  branch and name it in your hand-back; then
+  `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
+  Retirement keeps a tree that still holds uncommitted work, but don't rely on it.

package/injects/work-worktree.md

@@ -3,11 +3,34 @@
 Your `./work` is a **git worktree on your own branch** — a full checkout that is
 yours alone: build, test and commit there, on your branch.
 
-- **Never run git from the repo's main checkout**: it resolves to the wrong
-  branch and skips review. If unsure, `pwd`.
-- Everything you change happens in `work/` — **including your own soul** when
-  it lives in this repo: soul edits are branch changes, reviewed and merged
-  like code.
-- Don't create extra worktrees; `work/` is your one tree. Parallel work means
-  your human spawns another instance.
+- **Never work in a shared checkout** (the repo's main checkout, or any clone
+  others use): don't edit, commit or switch branches there. Against a clone you
+  run only `worktree add`/`remove` below. If unsure, `pwd`.
+- Everything you change happens in `work/` or your extra trees — **including your
+  own soul** when it lives in this repo: soul edits are branch changes, reviewed
+  and merged like code.
 - Leave your branch and the worktree list clean when your task closes.
+
+### Extra trees
+
+When the work needs another branch, or another repository of this deployment,
+create an extra tree in your home. `<clone>` is any clone of this deployment
+(`oats-local.yaml` `clones:`, or `<deployment>/<repo>`); `origin` is its remote
+for that repository; `<base>` is the remote branch the work starts from (the
+branch itself, when you rework an existing one):
+
+    git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
+    git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
+
+- This starts from the remote's current state and moves none of the clone's
+  refs. Never start from a local branch of the clone, which may be stale.
+- Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
+  If it already exists in that clone, `switch -c` refuses: use `<instance>/<branch>`.
+  Never `-C`/`-B`, which reset a branch someone else may own.
+- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
+  (`<base>` when you rework an existing branch).
+- Before your task closes, merge each extra tree into your PR branch, or push its
+  branch and name it in your hand-back; then
+  `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
+  Retirement keeps a tree that still holds uncommitted work, but don't rely on it.