@awebai/oats 0.40.1 → 0.40.2

package/bin/oats.mjs

@@ -490,7 +490,7 @@ function finishOperation({ r, bail, address, provider, op, argFlags, cwd, home,
   // (a partial receipt such as result.instance of something it launched
   // before failing, and any details it gave) travels in error.details so a
   // scheduler can keep an unconfirmed outcome and reconcile that target.
-  if (!envelope.ok) bail(envelope.error?.code || "E_OPERATION_FAILED", `${address}: ${envelope.error?.message || "failed"}`, { exit: r.status, envelope, ...(reportsRetainedEffectsText(envelope.error?.message) ? { unconfirmed: true } : {}) });
+  if (!envelope.ok) bail(envelope.error?.code || "E_OPERATION_FAILED", `${address}: ${envelope.error?.message || "failed"}`, { exit: r.status, envelope, ...(envelope.error?.details?.unconfirmed === true || reportsRetainedEffectsText(envelope.error?.message) ? { unconfirmed: true } : {}) });
   if (r.status !== 0) bail("E_OPERATION_RESULT", `${address} (${provider.capability} ${op.command}) answered ok but exited ${r.status}; the receipt is not trusted and its effects are unconfirmed${stderr ? `: ${stderr.slice(0, 400)}` : ""}`, observed(envelope));
   const result = envelope.result && typeof envelope.result === "object" ? envelope.result : {};
   if (op.kind === "view") {
@@ -2413,8 +2413,8 @@ async function spawnCmd() {
     if (e?.code === "E_PLACEMENT_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
     if (e?.code === "E_INSTANCE_NAME_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home ?? null, ...(e.session ? { session: e.session } : {}) }); throw e; }
     if (e?.code === "E_INSTANCE_NAME_INVALID") { bail(e.code, e.message, e.details); throw e; }
-    if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { instance: e.instance, home: e.home, launched: e.launched }); throw e; }
-    bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e); throw e;
+    if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { ...e.details, instance: e.instance, home: e.home, launched: e.launched }); throw e; }
+    bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e;
   }
   // The instance exists from here on: a failed wake save is reported beside
   // the full receipt, never hidden, and never causes a second spawn.
@@ -3818,7 +3818,7 @@ else if (cmd === "session") await sessionCmd();
 else if (cmd === "schedule") await scheduleCmd();
 else if (cmd === "trigger") await triggerCmd();
 else if (cmd === "automations") await automationsCmd();
-else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e); throw e; } }
+else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e; } }
 else if (cmd === "retire") retireCmd();
 else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
 else if (cmd === "experimental") await experimentalCmd();
@@ -4062,7 +4062,7 @@ Usage:
                                              typed lifecycle events (spawned, launched, stopped,
                                              restarted, retired, worktree-retained…) written by
                                              the action that made them true; nothing inferred
-  oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--json]
+  oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json]
                                              a producer's claim that the instance needs input
                                              from a human; appended only on change; display only
   oats instance attention [--message <text>] [--clear] [--json]
@@ -4135,7 +4135,7 @@ Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspa
   // Same two renderings as every other typed failure: one envelope on stdout in
   // --json mode, one `oats: <message>` line on stderr otherwise. The message
   // already names the offending file — the readers re-raise it with one.
-  if (JSON_MODE) jsonFail(e.code, e.message);
+  if (JSON_MODE) jsonFail(e.code, e.message, e.details?.unconfirmed === true ? e.details : undefined);
   die(e.message);
 } finally {
   // The command's read session: every `git cat-file --batch` child ends before the process does.

package/docs/capabilities.md

@@ -544,6 +544,18 @@ runs `bin/claude-waiting.sh` from the home's module copy, which calls
 | `PostToolUseFailure` | `*` | clear, unless a subagent made the call |
 | `UserPromptSubmit`, `Stop`, `SessionEnd` | none | clear, not debounced (a turn boundary) |
 
+**One home per settings file.** The launch hook bakes the home it writes the
+settings for into every command, as its real path (oats.core 2.4.1). The
+script acts only when the session's `$OATS_INSTANCE_HOME` names that same
+home, through any spelling (a symlinked deployment resolves to the same
+path). A Claude process that loads one home's settings 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) does nothing at all: no CLI call and no marker write, for either
+home. Before 2.4.1 it set and cleared the claim of the home its environment
+named, and its `Stop` and `SessionEnd` clears could erase that instance's
+real claim.
+
 Claude Code shows an AskUserQuestion through its permission dialog, so that
 dialog's own `permission_prompt` follows the question's set: the script keeps
 the current reason in its marker, and a permission prompt never relabels an
@@ -597,7 +609,8 @@ clears it.
   after the hook began, the worst case is about 4 s, well under Claude's 5 s
   hook timeout.
 - **Debounce.** The script keeps private state outside the home, in a file
-  per home: `<dir>/<first 16 hex of sha256(home)>.claude`, where `<dir>`
+  per home: `<dir>/<first 16 hex of sha256(home)>.claude` (the home's real
+  path, so each spelling of a home has the same file), where `<dir>`
   is per user: `$XDG_RUNTIME_DIR/oats-waiting` when that is set and
   absolute, else `$TMPDIR/oats-waiting-<uid>` when `TMPDIR` is absolute,
   else `/tmp/oats-waiting-<uid>`. The spawn and launch
@@ -715,6 +728,11 @@ again" permission rules there.
 - A `Stop` or `UserPromptSubmit` always clears, even one the main thread
   produces while a subagent's prompt is open (a background subagent's
   completion is submitted as a prompt).
+- The one-home rule separates homes, not two sessions of one home: a second
+  Claude process started inside the same home with that home's own
+  `$OATS_INSTANCE_HOME` (a `claude -p` the agent runs there) still matches,
+  so its `Stop` and `SessionEnd` clears can erase the home's own live
+  `oats.core` claim ([#557](https://github.com/awebai/oats/issues/557)).
 - A Claude instance spawned before the upgrade gets the emitter only when
   it is respawned. Its launch hook comes from its recorded module copy.
 
@@ -752,7 +770,22 @@ with no provider or a home operation without `--home`
 The provider must exit 0 with exactly one JSON envelope on stdout. Otherwise
 the outcome is **unconfirmed**: `E_OPERATION_TIMEOUT` (after 240 s) or
 `E_OPERATION_RESULT`, with `error.details { unconfirmed: true, exit, envelope?, stderr? }`.
-A provider's own `ok: false` is relayed with its code. A schedule of kind
+A provider's own `ok: false` is relayed with its code and full envelope. When
+the provider sets `error.details.unconfirmed: true` (the boolean), the operation
+wrapper also sets its outer `error.details.unconfirmed: true`. Providers should
+set that marker when dispatched effects or their compensation cannot be
+confirmed, and preserve it through wrappers. Producers should leave ordinary
+refusals and fully compensated failures unmarked: naming a home or retained
+evidence is not itself uncertainty. The operation wrapper and scheduler still
+apply their existing message-based compatibility checks during this additive
+migration, including for copied providers in older homes; their text-based
+false positives are not removed by this change.
+
+The kernel marks incomplete keyed spawns (`E_SPAWN_INCOMPLETE`) and spawn
+failures whose rollback cannot finish with the same field, through the CLI.
+A completed rollback remains an unmarked failure. This adds structural evidence;
+it does not remove text fallbacks or change scheduler slot and retry rules.
+A schedule of kind
 `operation` runs the same command ([schedules.md](schedules.md)). The JSON
 shapes are in [desktop-cli-api.md](desktop-cli-api.md#inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260).
 

package/docs/desktop-cli-api.md

@@ -543,7 +543,10 @@ oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--
   home operation without `--home`), `E_CAPABILITY_REQUIRES`, `E_BAD_ARGS`
   (undeclared or missing `--arg`), `E_CAPABILITY_BROKEN`. A provider's `ok:
   false` is relayed with its code and `details: {exit, envelope,
-  unconfirmed?}`. `E_OPERATION_TIMEOUT` (240 s) and `E_OPERATION_RESULT` are
+  unconfirmed?}`. A literal provider `error.details.unconfirmed: true` is
+  promoted to the outer details while its full envelope stays nested. Existing
+  retained-effect text checks remain for compatibility during migration.
+  `E_OPERATION_TIMEOUT` (240 s) and `E_OPERATION_RESULT` are
   unconfirmed outcomes: `details: {exit, signal, unconfirmed: true,
   envelope?, stderr?, cleanup?}`.
 
@@ -1617,7 +1620,7 @@ with `--expect-decision` records the key and decision in `instance.json`.
   `E_IDEMPOTENCY_CONFLICT {instance, home}`.
 - `spawnCompleted` is `false` until launch, lineage and events are done; a
   retry of an unfinished spawn is `E_SPAWN_INCOMPLETE {instance, home,
-  launched}` (recover through the session surface).
+  launched, unconfirmed: true}` (recover through the session surface).
 - The key lives in the home. Mint it on the first confirmation and keep it
   for that intent's retries.
 - `wake: {requested, saved, error}` is recorded and replayed; `saved: null`
@@ -1686,11 +1689,17 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 | `E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN` | see above | |
 | `E_DECISION_STALE` | `{decision}` | |
 | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
-| `E_SPAWN_INCOMPLETE` | `{instance, home, launched}` | |
+| `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}` | |
 | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
 | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
 | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
-| `E_SPAWN_FAILED` | | anything else |
+| `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
+
+Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
+keyed spawn is incomplete (`E_SPAWN_INCOMPLETE`) or compensation cannot confirm
+cleanup. The keyed-spawn details retain `instance`, `home` and `launched`.
+Confirmed completed compensation does not set this marker. This is an additive
+producer migration; existing text-based compatibility checks remain.
 
 ## `instance.json` and the roster
 
@@ -1922,6 +1931,15 @@ route target:
   `relativeTo` and `spawnOrigin` are always present, `null` when the host
   does not supply them (a host before 0.31, a fact it never recorded, or a
   saved route the host no longer lists). Nothing is derived on this side.
+- **`waitingOnYou`** (0.40.2, [Waiting on you](#waiting-on-you)) is on a row
+  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. Absent means
+  "not reported", which is not `null` ("no claim"). When present it is `null`
+  or `{since, producer, reason, message}`, passed through the kernel's read
+  rule again on this side: a value that is not a claim (no valid `since` or
+  `producer`) is `null`, and an unknown `reason` or an invalid `message` is
+  `null` inside a claim that still counts. As on a local row, the host
+  reports a claim only for a running instance.
 - **`addressable`** (0.31): `true` for every row the host reports. Routed
   session and lifecycle commands reach it by `--home`, or by name when the
   name is unique on the host ([addressing](servers.md#run-there); a shared
@@ -2160,7 +2178,9 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
 
 - **Sources.** `home` is `<home>/.oats-events.jsonl`; `workspace` is
   `<deployment>/.agents/events/<agent>--<instance>.jsonl` (it survives the
-  home). Each is `{path, status: "ok" | "absent" | "refused" | "tail",
+  home). The deployment is the one the home's spawn recorded, when that
+  directory really holds the home at `agents/<agent>/instances/<instance>`;
+  otherwise it is the fourth ancestor of the home as it was addressed. Each is `{path, status: "ok" | "absent" | "refused" | "tail",
   bytes}`. Only a regular file is opened (no symlinks, same device and inode
   after open), and at most its last 4 MiB is read (`"tail"`).
 - **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
@@ -2182,12 +2202,35 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
   `null` for old rows); the top-level `incarnation` is the current home's (or
   `null`). Earlier incarnations are returned as this address's history.
 - **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`).
+  A home has one address in storage, its real path (since 0.40.2): rows are
+  written and matched under it, whatever spelling a writer or reader used (a
+  deployment reached through a symlink, a symlinked agents root). The answer
+  keeps the spelling it was asked in: the top-level `home` and every
+  returned row's `home` are the home as the caller addressed it (`--home`,
+  or the home found under `--dir`), the same string a status row carries.
   Rows for another address are dropped and counted in
   `integrity.foreignRows`; torn or invalid lines are counted in
   `integrity.unreadableRows`. A row present in both logs is returned once;
   identical rows repeated within one log (a set, a clear and the same set in
   one millisecond) are all returned, as many as the log holding the most
   copies has.
+- **Rows from before 0.40.2**, in a deployment addressed through a symlink
+  only. A stored `home` is never rewritten, and never matched under another
+  spelling. A row an earlier kernel wrote under the lexical spelling (a
+  spawn's rows, and the claims of a session that was spawned and never
+  restarted) is foreign after the upgrade, and counted in
+  `integrity.foreignRows`. What that means for a claim:
+  - A claim that was live under the lexical spelling stops showing. Nothing
+    brings that row back: the claim shows again only when a producer makes it
+    anew (the next permission prompt or question, the agent's next
+    `oats instance attention`). A restart starts a new session with no
+    claim, as always.
+  - A claim that stayed set because the restart that should have voided it
+    was recorded under the real path (#583) is gone.
+  - The rows a started or restarted session wrote under the real path, which
+    `oats status --dir <symlink>` could not see, are read now. They cannot
+    surface a stale claim: such a session wrote its clears and its session
+    boundaries under the real path too, so that history is complete.
 - **Window.** `count` is the rows after `--since`; `returned` the window
   (`--limit`, default 200, 1–2000); `truncated` means rows were cut or a
   source was a tail. `lastEvent` is `{kind, at, producer, incarnation}` of
@@ -2251,14 +2294,17 @@ oats instance attention [--message <text>] [--clear] --json
   message (a hand-edited log) reads as `null`, and the claim still counts.
   A stored `reason` outside `permission`, `question`, `attention` reads as
   `null` too, and a row whose `producer` is neither `kernel` nor a valid
-  producer id is no claim at all.
+  producer id, or whose `at` is not a date, is no claim at all.
 - **Idempotent.** The verb reads the producer's live claim first and appends
   only on a change: a `set` whose reason or message differs from the live
   positive claim appends (`changed: true`), an identical one does not; a
   `clear` appends only over a live positive claim. The answer is
   `{eventsApi, instance, home, producer, changed, waitingOnYou}`, where
   `waitingOnYou` is that producer's resulting claim (`null` when it holds
-  none). Concurrent writers append whole lines; the latest row decides.
+  none) and `home` is the home as the caller addressed it (`--home`,
+  `$OATS_INSTANCE_HOME` or the enclosing home); the row is stored under the
+  real path, so a set and a clear through different spellings of one home
+  meet. Concurrent writers append whole lines; the latest row decides.
   Each log is judged on its own, and success means both took the row: a
   write either log refused is `E_EVENTS_FAILED` naming it, and the next call
   (a retry) appends again to repair it.
@@ -2461,6 +2507,42 @@ stderr, not envelopes.
 
 ## Sessions and launch configurations
 
+### Input
+
+```text
+oats session input --home <abs> [--text-file <path>] --json
+```
+
+Input bytes come from stdin or the named file. The existing version-1 success
+answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
+present: true, state, paneId, submitted: true, verified}}`. Session input runs
+on the execution host, including when the wake broker invokes it there;
+`--server` is not supported for input. The adapter sends one literal
+bracketed paste and one Enter after the existing input/authority/target checks.
+
+`submitted` means terminal-operation success, **not model acceptance or
+processing**. `verified` is display observation only: `true` means a bounded
+look changed, possibly because of unrelated output or a dialog; `false` means
+unchanged, unreadable or exhausted observation. False never authorizes retry
+and is not proof of a pending draft or absence of effects. No `reason` is
+emitted; the `enter-not-taken` result from 0.39.4 is removed.
+
+Read-only settling before Enter shares one monotonic 2-second budget starting
+when paste returns; up to two post-Enter looks share a 1-second budget. Probe
+timeouts and sleeps use the remaining budget. Observation failures produce
+`verified: false`, not input errors or extra keys. The original paste/key
+command timeouts and `E_SESSION_INPUT_FAILED` errors remain; the observation
+budgets do not bound those commands, failed buffer cleanup or OS scheduling.
+No busy-pane submission or exactly-once guarantee is provided. Generic command
+errors can still be uncertain after partial effects.
+
+The Desktop terminal's authorized PTY writes are a separate stream; they do not
+consume this `verified` field. The Pi bridge does not interpret this result.
+Scheduler wake still records a nonthrowing input operation as delivered without
+adding acceptance/history fields. Actual broker acknowledgement and retry
+policy require their own consumer qualification; this result is not a native
+harness receipt. See [execution targets](execution-targets.md).
+
 ### Start and restart
 
 ```text

package/docs/execution-targets.md

@@ -143,35 +143,36 @@ oats session attach --home /abs/home
   live claim that the instance needs input from a human, `{since, producer,
   reason, message}`, or `null`; it is non-null only for a running harness
   (docs/desktop-cli-api.md, "Waiting on you").
-- **input** submits UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
-  NUL) followed by Enter, as a bracketed paste. The text is never run by a
-  shell. A fallback shell, a stopped session or a split
-  tmux window is refused. The text is pasted once. Enter waits for the pane to
-  settle (two identical captures, at least about 200 ms, longer for a larger
-  paste, at most 2 s), and is judged by whether it changed the bottom 15 lines
-  of the pane. The comparison is of bytes only, and the pane's text is never
-  interpreted. Trailing spaces are ignored. When the pane was seen to change
-  size (a resize, or a second client attaching), a reflow of the same content
-  is not a change either: each side's content must already be on the other
-  side's screen or in its history, so content that appeared or disappeared
-  still counts. An Enter that changed nothing was swallowed, and is resent
-  after a backoff, at most 3 Enters in total. The answer adds:
-  - `submitted: true, verified: true`: an Enter was taken.
-  - `submitted: false, verified: true, reason: "enter-not-taken"`: none of the
-    3 Enters changed the pane. The text stays in the agent's input box; it is
-    not pasted again.
-  - `submitted: true, verified: false`: a capture failed, so no further Enter
-    was sent and the last one was not judged. As before, this means the
-    terminal accepted the keys. When the pane cannot be read before the first
-    resend, exactly one Enter was sent.
-
-  `submitted` never means the agent processed the text. A pane that changes
-  for another reason after Enter (a spinner, a clock, a human typing) reads as
-  taken. A harness that shows no visible reaction to Enter receives up to two
-  extra Enters; real harnesses (claude, codex, pi) redraw on submit. A call takes at most about 4 s plus its tmux calls. A failed paste or
-  key send is `E_SESSION_INPUT_FAILED`, with no retry. Wake schedules and
-  messaging capabilities use this command ([schedules.md](schedules.md)); a
-  wake schedule records any answer as delivered.
+- **input** sends UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
+  NUL) as exactly one bracketed paste followed by exactly one Enter. The text
+  is never run by a shell. Existing endpoint authority, fallback-shell,
+  stopped-session and split-window checks still refuse before input.
+
+  Before Enter, a size-based floor (200 ms plus 3 ms per KiB) and read-only
+  settling polls share one **monotonic 2-second observation budget**, starting
+  immediately after the paste command returns, before buffer cleanup. Sleeps
+  and capture timeouts are clipped to the remaining budget; a failed capture
+  or exhausted budget ends settling and proceeds to the single Enter. After
+  Enter, at most two read-only looks share a separate 1-second observation
+  budget. These deadlines do not bound the original paste/key commands, buffer
+  cleanup or OS scheduling. They authorize no further keys.
+
+  Successful terminal commands return `submitted: true` and `verified`, with
+  no `reason`. `verified: true` means only that the bounded display comparison
+  saw a changed look; `false` means unchanged, unreadable or exhausted
+  observation. The comparison retains its whitespace and resize/reflow
+  handling. Display movement can be unrelated output, a spinner or a dialog;
+  an unchanged display is not proof that no effects occurred or that a draft
+  is pending. **Neither value authorizes retry or proves model acceptance.**
+
+  A failed paste or key command remains `E_SESSION_INPUT_FAILED`; an
+  observational failure does not turn successful terminal operations into a
+  refusal. Command errors may themselves be uncertain after partial effects.
+  This transport offers no exactly-once guarantee and does not guarantee that
+  a busy pane accepts the input. Wake schedules retain their existing rule:
+  any nonthrowing input answer is recorded as delivered, meaning terminal
+  operations, not model processing. Broker delivery/ack policy and harness
+  acceptance evidence remain separate contracts.
 - **attach** is interactive and takes no `--json`. It opens a temporary tmux
   session linked to the agent's window alone.
   Closing the viewer leaves the agent running.

package/docs/implementation.md

@@ -65,11 +65,54 @@ published to npm. Its developer docs are in
 | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
 
 The schedule registry stores explicit concurrency caps, leaving the schedule
-cap absent for its effective default of five. Reads migrate legacy stored one
-to absent once, under `registry.lock`, and record `capsVersion: 2`. Registration
-and cap updates use that same short lock; later explicit one stays explicit.
-`readRegistry()` returns stored choices; scheduling and status apply the default
-without writing it back. The trigger cap is independent and absent means no cap.
+cap absent for its effective default of five. `readRegistry()` is a pure,
+bounded atomic-file snapshot: it takes no lock and writes nothing, projecting
+legacy implicit one to absent and `capsVersion: 2` only in memory. Its no-follow
+regular-file descriptor accepts an atomic rename between stat and open, so it
+returns a complete old or new snapshot; other bounded readers retain their
+identity check. Invalid present schedule or trigger caps are refused.
+Registration, unregistration and cap updates reread under `registry.lock` and
+compare against the raw snapshot, so even unchanged membership persists the
+migration. A successful write removing legacy one emits a stderr notice naming
+the one-slot restoration command. `writeRegistry()` remains a raw atomic writer;
+read-modify-write callers must supply the lock and reread. Later explicit one
+stays explicit, including one reintroduced by an older writer: the stored
+marker cannot distinguish its provenance. The trigger cap stays independent.
+
+The shared mkdir lock retries every occupied-directory window within the
+caller's retry deadline, including owner-file publication and removal. It never
+removes a contender's lock or steals from a live, dead or unreadable owner;
+persistent contention ends in the caller's existing busy error.
+
+Spawn compensation returns its diagnostic and a structural uncertainty flag;
+only an incomplete result marks the original error's `details.unconfirmed`.
+CLI wrappers preserve that field, and the operation runner promotes a provider's
+literal true marker while retaining the nested envelope. Message-based consumers
+remain during the additive producer migration; do not replace stage evidence
+with a substring check or infer uncertainty from a retained home alone.
+
+The schedule child supervisor installs SIGINT/SIGTERM/SIGHUP handlers before
+launch and removes them on settlement. All catchable shutdown signals share
+its idempotent TERM/KILL path; the first stop cause is retained. The private
+receipt records interruption independently of both the first stop cause and
+the direct child's observed exit, so a signal during overflow cleanup still
+keeps an otherwise valid envelope unconfirmed. Group probes
+start at leader exit; an observed-empty group is permanently excluded from
+later probes/signals. Polling cannot eliminate the gap before observation or
+prove away PID reuse. Escaped sessions are outside the owned group, and
+SIGKILL/OOM or unrecoverable supervisor death cannot be cleaned up by handlers;
+a missing receipt supplies no child-exit evidence and cannot release a slot.
+
+Session input keeps terminal operations separate from display observation.
+The pre-Enter budget starts at paste completion, before best-effort buffer
+cleanup; post-Enter observation starts after the single key command returns.
+Both use a monotonic clock, clip sleeps and read-only capture subprocess
+budgets, and stop observing on failure or exhaustion. Capture subprocesses use
+SIGKILL on timeout so an ignored TERM cannot extend a probe; terminal command
+timeouts/errors are unchanged. Screen comparison can set only the observational
+`verified` boolean, never send another key or report terminal failure. Tests
+use inert command runners and clocks; they do not qualify broker delivery or
+harness acceptance.
 
 The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
 a provider. Provider behaviour lives in capabilities; the kernel supplies

package/docs/oats-local.schema.json

@@ -99,7 +99,7 @@
         "disabled": {
           "description": "Workspace schedules this host does not run, by qualified id <member>/<id>, without a commit (`oats schedule disable <member>/<id>` writes it). Local schedules are enabled and disabled in oats-schedules.json.",
           "type": "array", "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" }
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,100}$" }
         }
       }
     },
@@ -111,7 +111,7 @@
           "description": "The workspace triggers and schedules this host agrees to run, by qualified id <member>/<id>, or \"*\" for every one the workspace places on this host (0.30). A workspace automation runs only when its runsOn is host.name, its owner is this host's gh account AND trust admits it; absent or empty, none runs. A host fact: the committed workspace file refuses it. Local triggers and schedules need no trust.",
           "oneOf": [
             { "const": "*" },
-            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" } }
+            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,100}$" } }
           ]
         }
       }

package/docs/official-catalog.md

@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.6.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.framework` | `oats-framework/v1.6.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.21.1` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.8.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.1.1` or `oats-framework/v1.6.0`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.6.1`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.6.0
+  oats.framework: v1.6.1
   oats.okf: v4.1.1
   oats.aweb: v1.21.1
 teams:
@@ -333,11 +333,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.6.0", "path": "oats-package" }
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.6.1", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.6.0`
-resolves to tag `oats-framework/v1.6.0`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.6.1`
+resolves to tag `oats-framework/v1.6.1`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.

package/docs/release-lane.md

@@ -47,8 +47,8 @@ override; report the risk you accepted). It never touches the checkout it
 runs from: it exports the SHA into a detached worktree under the system
 temporary directory (recorded in `MANIFEST.json`, `--export <dir>` overrides)
 and runs every build step there. The bumped manifests exist only in that
-export; the version-bump commit to `main` remains the workflow's job, or a
-manual PR.
+export; the version-bump commit reaches `main` through the pull request the
+workflow opens (or a manual one), merged by a maintainer.
 
 `publish-npm` and `release-github` print their plan and refuse without
 `--yes`. `tag` creates the local tag without `--yes` but pushes only with
@@ -117,8 +117,12 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
   runs `release.yml`, whose steps are idempotent: it skips the live npm
   versions, re-uploads the same assets, and attaches the attestations. That
   later pass is the way to add provenance; nothing is republished.
-- **The version-bump PR.** The workflow's final step; open it by hand if the
-  workflow does not run.
+- **The version-bump PR.** The workflow's final step opens it and stops: the
+  run never merges into `main`. A maintainer reviews that the diff is the
+  version lines only and merges it. The PR is opened with the workflow token,
+  so no checks run on it by themselves; close and reopen it to run them, and
+  do not read missing checks as green. Open the PR by hand if the workflow
+  does not run.
 - **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
   host; the lane says so and `stage` lists what is missing.
 

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.