@awebai/oats 0.40.1 → 0.41.0

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

@@ -0,0 +1,120 @@
+# OATS 0.40.2
+
+## Added
+
+- **Unconfirmed spawn and operation failures carry structural evidence**
+  ([#548](https://github.com/awebai/oats/issues/548)). Incomplete keyed spawns
+  and failed spawn compensation set `error.details.unconfirmed: true`; the
+  operation wrapper promotes a provider's literal true marker while retaining
+  its complete envelope. Completed compensation stays unmarked. Existing
+  text fallbacks and scheduler slot/reconcile behavior remain during this
+  additive migration; older copied providers are not upgraded by this change.
+
+## Fixed
+
+- **Schedule registry reads are lock-free and do not mutate state**
+  ([#579](https://github.com/awebai/oats/issues/579)). Status and other readers
+  use coherent atomic-file snapshots, including during registry writes. Legacy
+  cap migration is projected in memory and persisted only by locked mutations,
+  with a one-slot restoration notice on stderr. Invalid stored schedule caps
+  now refuse instead of silently increasing capacity; explicit CLI cap options
+  can repair them. Old hand-set and implicit ones cannot be distinguished, nor
+  can current kernels identify a one reintroduced by an older writer sharing
+  the registry; stop mixed-version writes and explicitly set the desired cap.
+  Shared directory locks wait through transient owner publication/removal within
+  their retry deadline without stealing locks.
+- **OATS Desktop: "Needs input" shows on a remote instance, and a withheld
+  note reads as the reason.** Desktop hid every remote claim: a remote roster
+  row carries no `runtimeState`, and Desktop read "not reported" as "not
+  running" (#582). An unreported state no longer hides the claim; a row
+  reported stopped, unreachable or unsupported, or one whose server did not
+  answer, still shows none. When a claim's note holds a link or text such as
+  `token: …`, Desktop does not show it. The row's description, the terminal
+  tab's title and the hover card now show the reason in words, such as "Asked
+  you a question", where they showed "[Detail withheld]" (#584). The activity
+  view still marks such a note as withheld, and `oats status` prints it in
+  full.
+- **A remote instance's "needs input" reaches the roster**
+  ([#582](https://github.com/awebai/oats/issues/582)). `oats server roster`
+  built a remote row from a fixed list of facts and dropped the host's
+  `waitingOnYou`. A row now carries it when, and only when, the host's kernel
+  reports it: a row from a host before 0.40.0, and a saved route the host did
+  not list, have no such key, so "not reported" stays distinct from `null`
+  ("no claim"). The value passes the kernel's read rule again on this side;
+  anything that is not a claim is `null`. See
+  [the remote roster](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json).
+- **"Needs input" in a deployment addressed through a symlink**
+  ([#583](https://github.com/awebai/oats/issues/583)). A home there has two
+  spellings: `oats status --dir <symlink>` addressed it lexically, while a
+  started or restarted session carries the real path. Event rows are keyed by
+  the home, so the session's claims never showed on status, a restart did not
+  void a claim written under the other spelling, and a clear through one
+  spelling found nothing. Rows are now stored and matched under the home's
+  real path, whichever spelling a writer or reader uses, and both spellings
+  use one workspace log, the deployment's own `.agents/events`. Answers keep
+  the spelling they were asked in: the `home` in `oats instance events --json`
+  (the top-level field and each row's) and in the `oats instance waiting` and
+  `oats instance attention` answers is the home as the caller addressed it.
+  Deployments not reached through a symlink see no change.
+
+  Rows an earlier kernel wrote under the lexical spelling are not rewritten
+  and not matched: after the upgrade they are foreign, counted in
+  `integrity.foreignRows`. In a symlinked deployment that means:
+  - a claim that was live under the lexical spelling (a session that was
+    spawned and never restarted) stops showing. It shows again only when it
+    is made anew: at the agent's next permission prompt, question or
+    `oats instance attention`. A restart starts a new session with no claim;
+  - a claim that stayed set because its restart was recorded under the real
+    path is gone, not stuck;
+  - the rows a started or restarted session wrote under the real path are
+    read now. They cannot show a stale claim: such a session wrote its clears
+    and its session boundaries under the real path too.
+- **oats.core 2.4.1: the Claude Code emitter no longer speaks for another
+  instance** ([#584](https://github.com/awebai/oats/issues/584)). Its hook
+  script took the home from `$OATS_INSTANCE_HOME`. A Claude process that
+  loaded one home's `.claude/settings.json` while carrying another instance's
+  environment (a nested `claude -p`, a `claude -p` started with its working
+  directory in another home, a pane that inherited the variables) set and
+  cleared that other instance's claim, and its `Stop` and `SessionEnd` clears
+  could erase a real one. The launch hook now writes the home's real path
+  into each hook command, and the script acts only when `$OATS_INSTANCE_HOME`
+  names that home, through any spelling; otherwise it does nothing. Ships in
+  oats.framework 1.6.1 (compatibility unchanged; catalog and workspace pin
+  `oats-framework/v1.6.1`): a workspace's `oats.framework: v1.6.1` resolves
+  to that tag through the official catalog, and a workspace pinned to v1.6.0
+  keeps oats.core 2.4.0 until it moves the pin and syncs. A home picks it up
+  at its next spawn. See [capabilities](../capabilities.md).
+- **A waiting row whose time is not a date is no claim**
+  ([#584](https://github.com/awebai/oats/issues/584)). The reader validated a
+  stored claim's producer, reason and message but passed its time through.
+  And `oats help` lists `[--dir <d>]` for `oats instance waiting`.
+- **Catchable scheduler-supervisor shutdown cleans up its owned child group**
+  ([#580](https://github.com/awebai/oats/issues/580)). SIGINT, SIGTERM and SIGHUP
+  enter the existing bounded TERM/KILL cleanup once, preserving observed child
+  exit evidence and treating interrupted envelopes as unconfirmed. The group
+  is checked when its leader exits and never signalled again after it is seen
+  empty, reducing but not eliminating process-group ID reuse races. Escaped
+  sessions and unrecoverable supervisor deaths such as SIGKILL/OOM remain
+  outside that cleanup guarantee; no receipt means no proven child exit, so
+  the unknown attempt and host slot remain pending reconciliation.
+- **Workspace schedule opt-outs and named trust accept 100-character IDs**
+  ([#581](https://github.com/awebai/oats/issues/581)). Host configuration now
+  accepts the full schedule name limit in `schedules.disabled` and
+  `automations.trust`, so enabling/disabling and trusting schedules with
+  41–100-character IDs works through the CLI and workspace placement checks.
+  Trigger definitions and `triggers.disabled` retain their 40-character limit;
+  member syntax, allowed characters and uniqueness rules are unchanged.
+
+## Changed
+
+- **Session input restores single-paste, single-Enter terminal semantics**
+  ([#562](https://github.com/awebai/oats/issues/562)). Corrects 0.39.4's
+  screen-derived extra Enters and `enter-not-taken` refusal after successful
+  terminal commands. Pre-Enter settling remains, with a shared monotonic
+  2-second observation budget; at most two read-only post-Enter looks share
+  1 second. Each probe and sleep is limited by its remaining budget.
+  `submitted: true` reports terminal-operation success; `verified` reports
+  display change only, and false never authorizes retry. Neither proves model
+  acceptance, pending draft state or absence of effects. Command errors and
+  authority checks are unchanged; busy-pane submission, exactly-once delivery
+  and generic-error retry uncertainty are not solved by this correction.

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

@@ -0,0 +1,238 @@
+# OATS 0.41.0
+
+## Changed
+
+- **The framework workspace has a separate maintainer soul.** The new
+  `oats-maintainer` soul is the OATS maintainer: direction, the roadmap,
+  architecture coherence, routing work to experts, review, merge and releases.
+  It composes `oats.maintainer` and carries the OATS-only `/oats-pr-review` and
+  `/git-tag-release` skills. `oats-expert` stays an expert, the generalist that
+  leads cross-area work, coordinates the domain experts and reports to
+  `oats-maintainer`. The other souls send direction, contract decisions and
+  merges to `oats-maintainer`, and read its knowledge node
+  (`oats/oats-maintainer`, which holds what the `oats-expert` node held).
+  - The `oats` knowledge store's main must declare the `oats-maintainer`
+    node before this reaches a deployment: souls that read or own it fail
+    their knowledge check with `E_CONFIG unresolved node:
+    oats/oats-maintainer` against a base without it.
+  - Operators: `oats sync`, then spawn `oats-maintainer` for maintainer work.
+    Running instances keep what they were spawned with.
+- **Desktop terminals keep text readable (#602).** Desktop terminals now keep
+  text at a contrast of at least 4.5:1 with its background, so coloured text written for
+  another palette (a grey meant for a dark terminal, shown in White) stays
+  readable. The built-in palettes' colours on the terminal background are
+  unchanged; text on a coloured background may be drawn lighter or darker than
+  the program asked.
+- **Desktop can match this computer's theme (#602).** A fourth theme choice,
+  **This computer**, shows Desktop's chrome and every terminal in the theme of
+  the computer that runs Desktop. On an Omarchy computer that is the current
+  Omarchy theme, followed when it changes, with no restart. Elsewhere it is
+  Dark or White by the system's appearance. Text colours taken from the host
+  are adjusted where needed to stay at least 4.5:1 on Desktop's surfaces; a
+  terminal's 16 colours are the host's own. If the host's theme cannot be
+  read, Desktop shows Dark or White and says so. A theme you chose does not
+  change: choose **Theme: This computer** in the command palette, or cycle to
+  it with the theme button.
+  - On an Omarchy computer Desktop reads the theme's colours file at start and
+    each time a window gets focus, whichever theme is chosen. It opens the file
+    without blocking and reads it only if it is a regular file, so a colours
+    file replaced by a named pipe, for example, cannot hang it (#612).
+  - On Linux, This computer is the default: a Desktop where no theme was ever
+    chosen starts in This computer (the computer's Omarchy theme, or the
+    system's light or dark appearance where there is none) instead of White.
+    That includes an existing install where the theme was never changed. If
+    you chose White at any time, it stays White. Choose another theme with the
+    theme button or the palette, and it stays. On other platforms the default
+    is still White.
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.42.0`**, so it runs against
+  this release's kernel; the Desktop 0.40.x refuses a 0.41 CLI.
+- **Desktop's Remove has one choice, the worktree.** Remove no longer offers
+  to delete a branch: retirement leaves branches to the operator, and the
+  kernel refuses the flag. The dialog's one choice is **Also delete the
+  worktree**, and it says "Remove never deletes a branch." A home left by a
+  failed spawn that still owes its branch stays incomplete while that branch
+  exists, and Remove can no longer complete it: check the branch and delete it
+  with Git, then remove the home again.
+- **New sessions run on an OATS-owned tmux server (#602).** The server is
+  `tmux -L oats`, so tools that restyle the default tmux server no longer
+  reach agent terminals. Running instances stay where they are. Plain
+  `tmux ls` and `tmux attach` no longer show new sessions: use `oats session
+  attach` or the `attach:` line that spawn prints. An existing instance moves
+  only when its window is recreated: a start after its window is gone or its
+  tmux server cannot be reached now opens on the OATS server instead of the
+  recorded socket. To move one deliberately, stop it, close its window and
+  start it: see
+  [Existing instances](../execution-targets.md#existing-instances).
+  - Operators: after upgrading, and after a reboot, start the `oats` server
+    from your own shell before anything else does: `tmux -L oats new-session
+    -d -s <session> -n hq` (`<session>` is the deployment's session name,
+    `oats-agents` by default). A tmux server keeps the environment of whoever
+    starts it: without this step the first Desktop-run or scheduled spawn
+    decides the ambient environment of later panes, and a spawn or start run
+    from inside an instance whose own tmux server cannot be read is refused
+    ([the environment of the server and its panes](../execution-targets.md#the-servers-start-environment)).
+  - Nothing of an instance's environment reaches a server or a pane through
+    the calls that create an agents' session or window: an instance creates
+    the session with a reduced copy of the environment of the server its
+    home records (a variable whose value holds a `$`, a line break or a
+    character tmux prints encoded is not carried), and a window with only
+    `PATH` and the locale names tmux's client needs
+    (`LANG`, `LC_ALL`, `LC_CTYPE`), which tmux does not hand on. Every
+    creator's environment goes without the names the kernel sets
+    (`OATS_INSTANCE`, `OATS_ROOT`, `PI_AGENTS_ROOT`, launch references and
+    the others the docs list). A server that already runs keeps the
+    environment it has: OATS does not certify where that came from.
+  - On each agent window it creates, OATS resets `window-style`,
+    `window-active-style` and `cursor-colour` to `default`, and removes
+    `COLORFGBG` from the pane, so the pane shows the colours of the terminal
+    that views it. It does not reset `pane-colours`: a palette set in your
+    tmux configuration still reaches agent panes
+    ([what OATS sets](../execution-targets.md#the-oats-tmux-server)).
+  - OATS sets nothing server-global on any server when it creates a session
+    or a window. `window-size latest` and `aggressive-resize on`, which it
+    used to set globally on the server it created its session on, are now set
+    on the windows it creates.
+  - The spawn result's `attach` is `tmux -S <socket> attach -t <session>` for
+    a launched spawn and `oats session attach --home <home>` for
+    `--no-launch`; a routed spawn (`--server`) prints `oats session attach
+    --server <id> --instance <instance>`. The JSON shapes are unchanged.
+  - The kernel no longer exports `launchEnvTmuxFlags` (it had no consumer).
+
+## Upgrade
+
+**Retirement no longer deletes branches.** What to do:
+
+- **`oats retire --delete-branch` is refused** with `E_BAD_ARGS` before
+  anything happens: no child or session is stopped, no hook runs, nothing is
+  written. Retire without it; the branch is left in the repository. Inspect it
+  there and delete it with Git if it is no longer wanted. Scripts that pass the
+  flag must drop it. A self-retire an older OATS recorded with the flag is
+  completed with the branch and the worktree left, and its `retired` event says
+  so.
+- **A home a failed spawn left that still owes its branch** stays incomplete
+  while that branch exists, with the item `the branch the failed spawn created
+  is left: OATS does not delete it. Inspect it and delete it with Git if it is
+  not wanted, then retry`. The item names no branch; the CLI prints it on the
+  next line (the receipt's `retention.recordedBranch`, or the `branch` in the
+  retained home's `instance.json` when the worktree step did not run). While
+  Git cannot show the branch gone, the item is `git branch <b>: could not
+  verify whether it still exists (…)`. Delete the branch with Git, then retire
+  again.
+- **A worktree whose branch has no commit yet:** `oats retire
+  --discard-worktree`, or a retire that has work to copy, on such a worktree
+  refuses with `E_WORK_INSPECTION_FAILED` and removes nothing. Make a commit,
+  switch the worktree to a branch that has one, or remove the worktree with
+  Git; then retire again.
+- **A worktree Git refuses to read without your own `safe.directory`**
+  (typically one owned by another user) now refuses a retire that has work to
+  preserve or that removes the worktree, with `E_WORK_INSPECTION_FAILED`. A
+  plain retire of such a worktree with nothing to preserve retains it under a
+  `detached-unknown` name, without its branch in the receipt. Retire as the
+  owner, or with Git's ownership check satisfied for that path.
+
+## Fixed
+
+- **A retire keeps what only the worktree has.** The recovery a retire writes
+  of a worktree is proven against the commit the worktree has checked out, and
+  is checked out at that commit on the worktree's own branch (detached, when
+  the branch's name is not one OATS carries). A clean worktree whose HEAD is
+  detached at a commit no ref of the repository reaches is preserved in a
+  recovery before `--discard-worktree` removes it, also when a retire hook made
+  that commit. HEAD is read again immediately before the worktree is removed:
+  if it moved since the retire's last inspection, the worktree is not removed
+  and the retire stops with `E_WORK_PRESERVATION_FAILED`; the home and the
+  worktree are kept, and so is any recovery the retire wrote.
+- **A stopped instance's harness mark is readable in Solarized (#602).** In
+  the Desktop's roster, the harness mark of a stopped instance was drawn at
+  4.0:1 in Solarized, under the 4.5:1 the rest of the app keeps. It is now
+  4.7:1. The mark's block is slightly lighter in White and Solarized and
+  slightly darker in Dark.
+- **Review threads reach an agent whose session is not on the default tmux
+  server (#602).** Sending a pull request's review threads to an agent's
+  terminal from the Desktop now uses the tmux socket the instance records, as
+  the Desktop's terminals do. Before, the paste always went to the default tmux
+  server: for an instance that records another socket it answered that the
+  paste failed, or it could go into a window of the same name on the default
+  server. An instance that records no socket is pasted to as before.
+- **The Desktop names a retire refused at inspection.** When `oats retire`
+  refused a local instance with `E_WORK_INSPECTION_FAILED`, the Remove dialog
+  said "The lifecycle CLI is unavailable.", although the CLI had answered. It
+  now says: "Retirement was refused: the instance's home or work could not be
+  inspected. The home is kept; its session may already have been stopped, and
+  earlier retirement steps may have run." The outcome is still reported as
+  unknown, because the kernel can refuse after it stopped the children and the
+  session and ran the retire hooks. For an instance on a server the same
+  sentence replaces that headline, above the host's own message in Details.
+  For a local refusal the CLI's own message, which names the path and the
+  remedy, is in Details too (next entry). Part of
+  [#601](https://github.com/awebai/oats/issues/601).
+- **The Desktop shows the kernel's own message when a local Stop or Remove
+  fails.** The dialog said only its own sentence for the error code; the
+  message the CLI answered with was dropped. It is now in the dialog's
+  **Details**, as the code and the message, under that sentence, as it already
+  was for an instance on a server. It is shown only when the installed CLI
+  answered with an error and the Desktop has a sentence for its code: a
+  timeout, an unreadable answer or an unknown code shows none. Closes
+  [#601](https://github.com/awebai/oats/issues/601).
+- **The Desktop shows a kernel or host message as one plain line.** In the
+  Details of a refusal (Stop and Remove, the Git panel, Activity, readiness),
+  line feeds, the Unicode line and paragraph separators and tabs are collapsed
+  into single spaces. The C1 control characters, the bidirectional embedding,
+  override and isolate characters, the zero-width space, the word joiner, the
+  byte order mark and tag characters are each replaced by U+FFFD, the
+  replacement character. A message that holds a carriage return, DEL or
+  another ASCII control character other than tab and line feed (a message
+  with Windows line endings, for example), or that looks like a credential,
+  is withheld whole as `[Detail withheld]`, as before. A long message is cut
+  at 2048 characters. For readiness, the message is no longer in the "Couldn't
+  refresh" line's tooltip, which keeps the Desktop's sentence and the error
+  code; it stays in Details. In the Git panel a failed read's message, which
+  could span several lines, is now one line.
+- **A tmux server started from the Desktop gets your environment, not the
+  Desktop's (#602).** A tmux server started from the Desktop (by a spawn or a
+  start, or by opening a terminal) no longer carries the Desktop's own runtime
+  settings. They made Electron programs started from an agent's pane run as
+  Node, and on the AppImage they pointed library and data paths into the
+  Desktop's mount, which exists only while that Desktop runs. Every program
+  the Desktop starts (the `oats` CLI, `tmux`, `gh`, the login shell that
+  resolves `PATH`) now gets your environment without them. One change in a
+  diagnostic: `probePath` in the backend's `GET /api/cli` answer no longer
+  lists the AppImage's own entries. A tmux server that was already running
+  keeps the environment it was started with (#616). Known limits are in the
+  Desktop README.
+- **The Desktop builds a view's failure placeholder as text.** A tab whose
+  view fails to load or to mount shows the same words, built without markup.
+- **`oats retire` no longer refuses a launched instance only because its
+  tmux socket file is missing.** After a reboot that cleared tmux's socket
+  directory, tmux answers `error connecting to <socket> (No such file or
+  directory)` for the socket the instance's session was recorded on, and
+  retire refused with `E_RUNTIME_QUIESCE_FAILED`. Retire now goes on when the
+  recorded server cannot be reached because its socket file is missing and no
+  process on the host works in the instance's home (any process whose working
+  directory is in the home, not only the harness). A tmux server keeps running
+  when its socket file is removed, so when a process still works in the home,
+  or the process scan (`lsof`) cannot run or does not complete, retire refuses
+  as before and the message says which. Such a server recreates its socket
+  when its process is sent `SIGUSR1`. The check needs `lsof`: on a host
+  without it, a retire whose recorded socket file is missing is still refused,
+  and the message says that `lsof` is missing; install it, then retire. The
+  scan counts only when `lsof` completed: one that was cut off (a timeout, too
+  much output, a signal) is no longer read as "no process", here, for a home
+  without its session receipt and for a home opened in Herdr; those retires
+  are refused. So is one whose listing names no process at all, which a
+  completed scan never prints. A window that is still running, or a server
+  that cannot be read for another reason, is refused as before.
+  [#620](https://github.com/awebai/oats/issues/620).
+
+## Removed
+
+- **Three unused routes of the Desktop's local server.**
+  `GET /api/session/<instance>` (a capture of the instance's terminal),
+  `POST /api/keys/<instance>` (keys or a paste typed into it) and
+  `POST /api/interrupt/<instance>` (Ctrl-C) are gone. Nothing in the Desktop
+  used them: its terminals attach to the instance's session directly. They
+  ran `tmux` without the socket an instance records, so for an instance on
+  its own tmux server they would have reached another one. Each path now
+  answers as any unknown route does (`404`, `not found`).
+  `GET /api/chat/<instance>` is unchanged. Closes
+  [#609](https://github.com/awebai/oats/issues/609).

package/docs/schedules.md

@@ -86,8 +86,19 @@ jobs) sets it so that its command jobs can be told apart.
   sends SIGTERM to the child's process group, allows two seconds for cleanup,
   then sends SIGKILL if the group remains. It observes the direct child's exit
   before returning; inherited output pipes cannot hold the tick indefinitely.
-  A timeout leaves effects unconfirmed even if the child printed an envelope.
-  Spawn previews use the same bounded runner.
+  SIGINT, SIGTERM or SIGHUP received by the supervisor enters that same cleanup
+  once; repeated signals do not bypass it. A timeout or interrupted supervisor
+  leaves effects unconfirmed even if the child printed an envelope. Spawn
+  previews use the same bounded runner.
+
+  Cleanup covers the owned process group. A descendant that creates its own
+  session can escape it; inherited pipes are bounded but that escaped process
+  is not terminated by this group cleanup. The supervisor checks the group when
+  the leader exits and never signals it after observing it empty. This reduces
+  the group-ID reuse window; it does not eliminate PID reuse races. SIGKILL,
+  OOM and other unrecoverable supervisor deaths cannot run JavaScript handlers:
+  cleanup is not guaranteed then. Without a private supervisor receipt, the
+  scheduler keeps the unknown attempt and its slot until reconciliation.
 - **wake** `{…, home, message}` — every due minute inspects the instance at
   `home`. Running: `message` is delivered once as terminal input (bracketed
   paste plus Enter), never an interrupt. Not running: the home is started with
@@ -273,9 +284,12 @@ add` / `oats schedule add` definitions need no trust.
 
 **Opting out on one host.** `oats trigger disable <member>/<id>` writes
 `triggers.disabled`, and `oats schedule disable <member>/<id>` writes
-`schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. A
-workspace definition is never edited or removed from the CLI (`update` and
-`remove` answer `E_AUTOMATION_WORKSPACE`): change the file in Git.
+`schedules.disabled`, in `oats-local.yaml`; `enable` removes the entry. The
+schedule part of a qualified ID accepts up to 100 characters in both
+`schedules.disabled` and named `automations.trust` entries. Trigger definitions
+and `triggers.disabled` keep their 40-character limit; the shared trust list
+does not widen trigger IDs. A workspace definition is never edited or removed
+from the CLI (`update` and `remove` answer `E_AUTOMATION_WORKSPACE`): change the file in Git.
 
 **Refresh.**
 
@@ -329,12 +343,27 @@ current choices. Invalid values fail with `E_BAD_ARGS` before registration or
 timer changes. `host status` reports the effective `maxConcurrent` and
 `triggersMaxConcurrent` (`null` when uncapped).
 
-The registry stores explicit choices only. On the first registry read after
-upgrade, a legacy stored `maxConcurrent: 1` without the new choice marker is
-migrated to the default under the registry lock; other explicit values survive.
-If you need a cap of one, run `oats schedule host install --max-concurrent 1`
-after upgrading. That explicit choice survives later reads and reinstalls.
-Set these values through the CLI; do not edit the registry by hand.
+The registry stores explicit choices only. Reading status or the registry takes
+no registry lock and creates or rewrites no files or directories. A reader
+interprets a pre-migration stored `maxConcurrent: 1` as the default of five in
+memory. Registration, unregistration and cap updates persist that migration
+once, under the registry lock, even if the workspace membership is unchanged.
+Other explicit values and the independent trigger cap survive.
+
+A pre-migration hand-set one is indistinguishable from the old implicit one;
+both follow that compatibility choice. When a write migrates one to the default,
+it prints a notice on stderr with `oats schedule host install --max-concurrent 1`
+to restore one if needed. Pure reads stay silent and JSON stdout is unchanged.
+A later explicit one survives writes by current kernels. Older binaries sharing
+the registry can write one back while preserving `capsVersion: 2`; there is no
+provenance to distinguish that from a new explicit one. Stop mixed-version
+writes and explicitly set the desired cap with the supported CLI.
+
+A present invalid `maxConcurrent` is `E_SCHEDULE_INVALID`, not a fallback to
+five. Correct it with `oats schedule host install --max-concurrent N` (or
+`--max-concurrent default`) from the deployment, or with `--dir <deployment>`.
+An absent value still means five. Set caps through the CLI; do not edit the
+registry by hand.
 
 `oats schedule list --json` answers:
 

package/docs/servers.md

@@ -277,7 +277,10 @@ with `--server`; the remote default applies. `session attach --print` shows
 the ssh command without running it. A server without the `session` commands
 (before 0.22.2) is refused with the tmux command to attach there directly,
 naming the session and window its roster records for the instance (else
-`pi-agents`, that kernel's default).
+`pi-agents`, that kernel's default), and the tmux socket when the roster
+records one. The remote command is one quoted word either way: `ssh -t
+<host> 'tmux attach -t <target>'`, or `ssh -t <host> 'tmux -S <socket>
+attach -t <target>'`.
 
 ## The roster and harvest
 
@@ -298,7 +301,9 @@ 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`
-(an older host, or a saved route the host no longer lists). A removed or edited registration keeps
+(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
 its group from the saved routes. State is pulled on every call within
 `--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
 not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.

package/docs/souls-and-instances.md

@@ -443,6 +443,18 @@ cannot run, retire refuses with
 `E_RUNTIME_ENDPOINT_UNKNOWN`, even with `--force`: stop that session yourself,
 then retire again. `oats retire <instance> --plan` says which case applies.
 
+With a receipt, if the recorded window is still running, or its tmux server
+cannot be read, retire refuses with `E_RUNTIME_QUIESCE_FAILED` and keeps the
+home. When the recorded server cannot be reached because its socket file is
+missing (after a reboot), retire proceeds only when no process on this host
+works in the home (any process whose working directory is in the home, not
+only the harness); a tmux server that lost its socket file still runs, and
+recreates the socket when its process is sent `SIGUSR1`. That check needs
+`lsof`: on a host without it, a retire whose recorded socket file is missing
+is refused, and the message says that `lsof` is missing; install it, then
+retire. A scan that does not complete (a timeout, for example) refuses the
+same way, also for a home without its receipt.
+
 `oats retire <instance> --self` lets an instance retire itself when the human
 or briefing says it is done. A live harness cannot give a stable final
 inspection of its own work, so the calling process inspects, runs, and removes
@@ -461,17 +473,31 @@ When a retire hook reports incomplete cleanup, the home is quarantined before
 any worktree step: the worktree, its git admin entry and the branch stay
 exactly as they were, so the retry can reach the hook and the work it needs.
 The retry does the worktree step only once nothing else is outstanding:
-retain by default, remove with `--discard-worktree` or `--delete-branch`.
+retain by default, remove with `--discard-worktree`.
 `--force` removes the home regardless, so it does the worktree step first. A
 work directory whose git admin entry is gone is never removed: the hooks still
 run, the home is kept, and `--force` refuses it until you move the directory
 out or delete it by hand.
 
-Retire never deletes a branch unless you pass `--delete-branch`, and then
-only the verified branch: not on a quarantine, its retry or `--force`. A
-spawn that fails deletes the branch it created only while the branch's tip
-is still where the spawn created it. If something was committed there, the
-branch is kept and the failure says so.
+Retire never deletes a branch: not a plain retire, `--discard-worktree`, a
+quarantine, its retry or `--force`. `--delete-branch` is refused with
+`E_BAD_ARGS` before anything happens. The branch stays in the repository:
+inspect it there, and delete it with Git if it is no longer wanted. A spawn
+that fails deletes the branch it created only while the branch's tip is
+still where the spawn created it. If something was committed there, the
+branch is kept and the failure says so; the quarantine's retry stays
+incomplete until the branch is deleted with Git.
+
+Before it removes a worktree (`--discard-worktree`, or a failed spawn's
+quarantine that owes it), a retire preserves a commit that only the worktree
+reaches (HEAD detached at a commit no ref of the repository reaches) in a
+recovery, and reads HEAD again immediately before the removal: if HEAD moved
+since the retire's last inspection, the worktree is not removed and the
+retire stops with `E_WORK_PRESERVATION_FAILED`; the home and the worktree are
+kept, and so is any recovery the retire wrote. A worktree whose branch has no
+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.
 
 ## Work modes
 

package/docs/workspaces.md

@@ -54,7 +54,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.6.0                   # bare version → resolves through the official catalog
+  oats.framework: v1.6.1                   # bare version → resolves through the official catalog
   oats.okf: v4.1.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package