@awebai/oats 0.40.1 → 0.41.0

package/bin/oats.mjs

@@ -31,6 +31,7 @@ import {
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
   findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
@@ -490,7 +491,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 +2414,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.
@@ -2458,9 +2459,22 @@ async function spawnCmd() {
   console.log(`  attach: ${r.attach}`);
 }
 
+/** The line naming the branch a FAILED_SPAWN_BRANCH_LEFT item speaks of, on a line of its own: the item names
+ *  none. The receipt's `retention.recordedBranch` when the worktree step ran; otherwise the retained home's
+ *  recorded branch, read here (`local`), or where to read it on the host. Null when no item asks for it. */
+function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
+  if (!items?.includes(FAILED_SPAWN_BRANCH_LEFT)) return null;
+  let name = r.retention?.recordedBranch ?? null;
+  if (!name && local && r.retainedHome) { try { name = JSON.parse(readFileSync(join(r.retainedHome, "instance.json"), "utf8")).branch ?? null; } catch { /* said below */ } }
+  if (name) return `  branch: ${name}`;
+  return r.retainedHome ? `  branch: the "branch" recorded in ${join(r.retainedHome, "instance.json")}${host ? ` on ${host}` : ""}` : null;
+}
+
 function retireCmd() {
   const name = args[1];
-  if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--self] [--discard-worktree] [--delete-branch] [--keep-dir] [--force] [--json]");
+  // Refused before anything else: before --plan, a replay, a plan revision or a recorded child is stopped.
+  if (args.includes("--delete-branch")) return args.includes("--json") ? jsonFail("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED) : die(RETIRE_DELETE_BRANCH_REFUSED);
+  if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]");
   let homeFlag = flag("home");
   if (homeFlag === true) die("--home needs the instance home path");
   if (args.includes("--plan")) {
@@ -2471,7 +2485,7 @@ function retireCmd() {
       const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
       if (args.includes("--json")) { jsonOk(plan); return; }
       console.log(`retire ${name} — plan ${plan.planRevision}`);
-      console.log(`  session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? "detached"}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
+      console.log(`  session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? (plan.facts.work.detached ? "detached" : "a ref OATS carries no branch name for")}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
       console.log(`  defaults: retain worktree ${plan.defaults.retainWorktree}, delete branch ${plan.defaults.deleteBranch}, stop children ${plan.defaults.stopChildren}`);
       for (const n of plan.notes) console.log(`  note: ${n}`);
       return;
@@ -2492,7 +2506,7 @@ function retireCmd() {
   const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
   if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
   if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
-  let replayPath = null, childrenStopped = null, expectedBranch;
+  let replayPath = null, childrenStopped = null;
   if (planRev !== undefined) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
     // Replay first: after a successful retire the home is gone, so the receipt
@@ -2513,10 +2527,9 @@ function retireCmd() {
     }
     const running = childrenStopped.filter((k) => !k.ok);
     if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
-    expectedBranch = fresh.facts.work.observed ? fresh.facts.work.branch : undefined;
   }
   let r;
-  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, deleteBranch: args.includes("--delete-branch"), discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(expectedBranch !== undefined ? { expectedBranch } : {}) }); }
+  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") }); }
   catch (e) { if (!e?.code) throw e; return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message); }
   if (childrenStopped) r.childrenStopped = childrenStopped;
   if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
@@ -2539,6 +2552,8 @@ function retireCmd() {
   if (r.forcedIncomplete) {
     console.error(`Removed ${r.retired} under --force with cleanup INCOMPLETE — this external state was NOT cleaned up and is now yours to remove by hand:`);
     for (const f of r.forcedIncomplete) console.error(`  ${f}`);
+    const branch = failedSpawnBranchLine(r, r.forcedIncomplete, { local: true });
+    if (branch) console.error(branch);
   }
   if (args.includes("--json")) { console.log(JSON.stringify(r, null, 2)); if (r.rollbackIncomplete) process.exit(1); return; }
   // An unsuccessful cleanup retry must NOT read as a completed retirement: the
@@ -2547,10 +2562,12 @@ function retireCmd() {
   if (r.rollbackIncomplete) {
     console.error(`Cleanup for ${r.retired} is INCOMPLETE — the instance home is retained at ${r.retainedHome} because external state may still exist:`);
     for (const f of r.rollbackIncomplete) console.error(`  ${f}`);
+    const branch = failedSpawnBranchLine(r, r.rollbackIncomplete, { local: true });
+    if (branch) console.error(branch);
     console.error(`Fix the cause and re-run \`oats retire ${r.retired}\`; the home holds the state that cleanup needs.`);
     process.exit(1);
   }
-  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}${r.branchDeleted ? ", branch deleted" : ""}`);
+  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
   // Preserving work and not saying so leaves the operator believing it is gone,
   // which is most of the harm of deleting it. Name the classes and the path.
   for (const recovery of r.workRecoveries || (r.workRecovery ? [r.workRecovery] : [])) {
@@ -3673,6 +3690,8 @@ async function serverRouteCmd() {
     }
     rest.push(a);
   }
+  // Refused here too, before anything is sent: a host on an older OATS would still delete the branch.
+  if (cmd === "retire" && rest.includes("--delete-branch")) bail("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
   let routed;
   try { routed = routeCommand(id, cmd, rest); }
   catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
@@ -3694,7 +3713,7 @@ async function serverRouteCmd() {
     console.log(`  remote home: ${r.home}`);
     console.log(`  route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
     for (const w of r.warnings || []) console.log(`  WARNING: ${w}`);
-    console.log(`  attach: ssh -t ${r.target.sshHost} tmux attach -t ${r.tmux?.session || "oats"}`);
+    console.log(`  attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
   } else if (cmd === "retire") {
     // Everything the local retireCmd tells the operator, for a remote home
     // they cannot see: forced-incomplete state now theirs to remove by hand
@@ -3702,6 +3721,8 @@ async function serverRouteCmd() {
     if (r.forcedIncomplete) {
       console.error(`Removed ${r.retired} on ${id} under --force with cleanup INCOMPLETE — this external state was NOT cleaned up and is now yours to remove by hand on ${target.sshHost}:`);
       for (const f of r.forcedIncomplete) console.error(`  ${f}`);
+      const branch = failedSpawnBranchLine(r, r.forcedIncomplete, { host: target.sshHost });
+      if (branch) console.error(branch);
     }
     console.log(`Retired ${r.retired} on ${id}${r.deferred ? " (deferred completion scheduled there)" : ""}${r.rollbackIncomplete ? " — cleanup INCOMPLETE on the server, home retained there" : ""}`);
     for (const recovery of r.workRecoveries || (r.workRecovery ? [r.workRecovery] : [])) {
@@ -3709,7 +3730,13 @@ async function serverRouteCmd() {
       console.log(`  ${recovery.path}${typeof recovery.bytes === "number" ? ` (${formatBytes(recovery.bytes)})` : ""}`);
       for (const line of preservedOutputLines(recovery)) console.log(line);
     }
-    if (r.rollbackIncomplete) { for (const f of r.rollbackIncomplete) console.error(`  ${f}`); console.error(`Fix the cause there and re-run \`oats retire ${r.retired} --server ${id}\`.`); process.exit(1); }
+    if (r.rollbackIncomplete) {
+      for (const f of r.rollbackIncomplete) console.error(`  ${f}`);
+      const branch = failedSpawnBranchLine(r, r.rollbackIncomplete, { host: target.sshHost });
+      if (branch) console.error(branch);
+      console.error(`Fix the cause there and re-run \`oats retire ${r.retired} --server ${id}\`.`);
+      process.exit(1);
+    }
   } else {
     console.log(`oats status — server ${id} (ssh ${r.target.sshHost}, workspace ${r.target.workspace})\n`);
     for (const a of r.agents || []) {
@@ -3818,7 +3845,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();
@@ -3987,7 +4014,7 @@ Usage:
                                             decision binds an apply (--expect-decision <rev>);
                                             --max-age reuses recent heads (preview only)
   oats retire <instance> [--force]           retire an instance (window, hooks,
-      [--self] [--delete-branch]            worktree, home); --self = retire the
+      [--self]                              worktree, home); --self = retire the
       [--keep-dir] [--json]                 CALLING instance: the window dies, then
                                             a detached external retirement runs
   oats inspect [--dir <scope>] [--soul <name>   one authoritative JSON answer for a GUI: souls
@@ -4062,7 +4089,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]
@@ -4084,13 +4111,13 @@ Usage:
                                              with origins (captured homes refuse: the
                                              captured/portable path was removed in 0.26)
   oats retire <instance> --plan [--json]     what Remove would touch, with retention defaults
-  oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--delete-branch]
+  oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree]
                                              with a plan revision: refuses E_PLAN_STALE (fresh plan
                                              attached) if facts moved; a repeated key replays
                                              retire; a worktree is RETAINED (re-homed under
                                              <workspace>/.agents/worktrees/<repo>/<branch>)
-                                             unless discarded; --delete-branch deletes the
-                                             worktree's verified branch and implies discard
+                                             unless discarded; no retire deletes a branch
+                                             (--delete-branch is refused)
   oats root                                  print this package's install root
                                             (adapters resolve the kernel from it)
 
@@ -4135,7 +4162,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

@@ -117,7 +117,15 @@ A self-contained package has an `oats.json`:
   `oats status` reports it as retained state rather than a live instance, and
   `oats retire <instance>` retries the cleanup — re-running the retire hooks and
   the worktree removal, verifying both, and verifying (never deleting) the
-  branch: a branch is deleted only with `--delete-branch`. A retry that still cannot
+  branch: no retire deletes a branch. While the branch the failed spawn created
+  is still there, the retry stays incomplete 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, from the receipt's
+  `retention.recordedBranch` when the worktree step ran, otherwise from the
+  `branch` the retained home's `instance.json` records. While Git cannot show
+  the branch gone (a damaged ref, a failed read), the retry stays incomplete
+  with `git branch <b>: could not verify whether it still exists (…)`. A retry that still cannot
   finish keeps the home again, names what is outstanding, and exits nonzero.
 - The **escape hatch is `oats retire <instance> --force`**, for a home OATS cannot
   identify at all: no `instance.json` and no **usable** cleanup descriptor. Usable
@@ -544,6 +552,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 +617,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 +736,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 +778,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`
@@ -1628,8 +1631,8 @@ with `--expect-decision` records the key and decision in `instance.json`.
 ```json
 {"instance":"rm-api","agent":"rm","home":"/w/agents/rm/instances/rm-api","work":"worktree","branch":"agents/rm-api",
  "base":{"ref":"github.com/nw/agents","oid":"66566512…"},"launched":true,"warnings":[],
- "tmux":{"session":"oats-agents","window":"rm-api"},"backend":"tmux","repo":"/w/agents-repo","harness":"pi","model":null,"parent":null,"sibling":null,"relation":null,
- "spawnOrigin":"operator","attach":"tmux attach -t oats-agents","decision":{"instance":"rm-api","revision":"c557d8ec9a272ba1c1739dc3"},"replayed":false,
+ "tmux":{"session":"oats-agents","window":"rm-api","socket":"/tmp/tmux-1000/oats"},"backend":"tmux","repo":"/w/agents-repo","harness":"pi","model":null,"parent":null,"sibling":null,"relation":null,
+ "spawnOrigin":"operator","attach":"tmux -S /tmp/tmux-1000/oats attach -t oats-agents","decision":{"instance":"rm-api","revision":"c557d8ec9a272ba1c1739dc3"},"replayed":false,
  "wake":{"requested":false,"saved":null,"error":null},"launchConfig":null,
  "launch":{"version":2,"harness":"pi","launchConfig":null,"launchConfigSource":null,"executable":"/usr/local/bin/pi","executableDeclared":null,
            "executableResolvedFrom":"PATH","args":[],"env":{},"model":null,"hooks":{"launch":{},"env":{},"contributions":[]},"prompt":{"kind":"task-file","file":"TASK.md"}}}
@@ -1639,10 +1642,21 @@ with `--expect-decision` records the key and decision in `instance.json`.
 
 - Always present: `instance, agent, home, work, branch, base ({ref, oid}
   the new branch started at; `null` without one), launched, warnings
-  (array), tmux ({session, window} | null), backend ("tmux"), repo, harness,
+  (array), tmux ({session, window, socket?} | null), backend ("tmux"), repo, harness,
   model, parent,
   sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
   launch` (the redacted recipe).
+- `tmux.socket` is the absolute socket of the tmux server the window was
+  created on; a launched spawn has it, a `--no-launch` one does not. It is
+  the OATS tmux server's
+  ([execution-targets.md](execution-targets.md#the-oats-tmux-server)), where
+  earlier kernels recorded the default server's; the shape is unchanged.
+- `attach` is one string, a command for a person to paste, the same in text
+  and JSON. It is `tmux -S <tmux.socket> attach -t <session>` for a
+  launched spawn (earlier kernels: `tmux attach -t <session>`) and `oats session attach
+  --home <home>` for `--no-launch`. A value is single-quoted only when it
+  holds a character outside `A-Za-z0-9_./:-`. It is not a field to parse:
+  read `tmux` for the target.
 - When they apply: `yolo`, `decision` and
   `replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
   `wakeScheduleError` (a requested wake).
@@ -1655,7 +1669,8 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 - A name that is not a slug (lowercase letters and digits, single dashes),
   equals a soul name, or exceeds 64 characters (derived names included, with
   their suffix) is `E_INSTANCE_NAME_INVALID`.
-- A name any soul's `instances/` holds, or a live tmux window carries, is
+- A name any soul's `instances/` holds, or a live window of the target
+  session on the OATS tmux server carries, is
   `E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
   a silent `-2`.
 - The name is part of the decision.
@@ -1686,11 +1701,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 +1943,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,12 +2190,15 @@ 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`,
   `retire-planned`, `retired`, `worktree-retained`, `worktree-removed`,
-  `branch-deleted`, `child-spawn-refused`, `launch-warning` (0.30: a
+  `branch-deleted` (not written since 0.41.0: no retire deletes a branch;
+  older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
   `launch` hook's warning at session start/restart, `data: {message}`),
   `recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
   [Waiting on you](#waiting-on-you)). `producer` is `kernel`, a capability id,
@@ -2178,16 +2211,47 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
   is dated at the receipt's launch time. The boundary is complete per log: a
   log that missed it gets a copy of the same row (same time and data), never
   a second one.
+- `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
+  reason?}`) is written to the workspace log only,
+  `<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
+  home. `reason` is present only when
+  the retire completed a self-retire an older OATS recorded with
+  `--delete-branch` (since 0.41.0: `this self-retire was requested with
+  --delete-branch by an older OATS; retirement no longer deletes branches, so
+  the branch and the worktree were left`).
 - **Incarnation.** Each row carries the writing home's `createdAt` (or
   `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 +2315,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.
@@ -2396,7 +2463,7 @@ Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
 `-2` suffix if taken; `detached-<oid12>` when detached), state intact.
 
 ```text
-oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--delete-branch] [--home <abs>] --json
+oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--home <abs>] --json
 ```
 
 A first retire prints the **raw receipt**, not an envelope:
@@ -2412,8 +2479,7 @@ A first retire prints the **raw receipt**, not an envelope:
 ```
 
 - `retention`: `{worktree: "retained" | "removed" | "absent", movedTo?,
-  branch, detachedAt?, recordedBranch, branchDeleted?,
-  branchDeletionSkipped?: {expected, actual, reason}}`, or `null` when no
+  branch, detachedAt?, recordedBranch}`, or `null` when no
   worktree step ran: a non-worktree mode, or a worktree kept for the retry.
   A retire whose hooks left cleanup outstanding keeps the worktree exactly as
   it was (with `worktreeRemoved: false`) and says why in `rollbackIncomplete`
@@ -2422,14 +2488,30 @@ A first retire prints the **raw receipt**, not an envelope:
   entry is gone is never touched: it is an incomplete item (`git worktree
   <path>: its admin entry is missing; …`), and `--force` refuses it with
   `E_WORK_PRESERVATION_FAILED`.
-- `--discard-worktree` removes the worktree. `--delete-branch` deletes the
-  worktree's verified branch (re-verified at deletion time) and implies
-  discarding; a mismatch deletes nothing and reports
-  `branchDeletionSkipped`. Without `--delete-branch` no retire deletes a
-  branch, a retried or `--force`d quarantine included. A failed spawn's
-  quarantine that still owes the branch the spawn created stays incomplete
-  (`git branch <b>: kept; the failed spawn created it; pass --delete-branch to
-  delete it`).
+- `--discard-worktree` removes the worktree. No retire deletes a branch, a
+  retried or `--force`d quarantine included: `branchDeleted` is always
+  `false`, and `retention.branchDeleted` and `retention.branchDeletionSkipped`
+  are not written. `--delete-branch` is refused with `E_BAD_ARGS` (`oats
+  retire no longer deletes branches: …`) before any effect: before a plan
+  revision is compared and before a recorded child is stopped. A failed
+  spawn's quarantine that still owes the branch the spawn created stays
+  incomplete while the branch is there (`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:
+  `retention.recordedBranch` has it when the worktree step ran, otherwise the
+  retained home's `instance.json` `branch`) or while
+  Git cannot show it gone (`git branch <b>: could not verify whether it still
+  exists (…)`). Such a home cannot be completed from Desktop: the operator
+  deletes the branch with Git and retries, or uses `--force` from the CLI.
+- Before the worktree is removed, HEAD is read again: a HEAD that moved since
+  the retire's last inspection stops it with `E_WORK_PRESERVATION_FAILED`
+  (`the worktree's HEAD changed after it was inspected, so the worktree was
+  not removed. The home and the worktree are kept, and so is any recovery the
+  retire wrote; retry the retire.`), and a HEAD that cannot be read with
+  `E_WORK_INSPECTION_FAILED`. Either may follow earlier effects of the same
+  retire (hooks run, a recovery copied), and neither says that one happened:
+  an error here is not proof that nothing happened, nor that a recovery
+  exists.
 - `workRecovery` (or `workRecoveries[]`): `{path, classes, bytes, outputs?,
   repoCopy?}`; `outputs: {paths: [{path, bytes}], bytes}` names what was
   copied beyond tracked state, largest first.
@@ -2461,6 +2543,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
@@ -2480,6 +2598,12 @@ selection flags. See [the start workflow](desktop-instance-start.md).
   instance's events as a `launch-warning` row, `data: {message}`. They are
   advisory: the start went ahead. Earlier kernels omit the field; read a
   missing `warnings` as `[]`.
+- The kernel adds one warning of its own, in the same array and as
+  the same event: when the start had to create the window again and created
+  it on a tmux server other than the one the home recorded, the line names
+  the instance, the old socket and the new one (each as a JSON string).
+  `target.socket` is then the new socket
+  ([execution-targets.md](execution-targets.md#existing-instances)).
 - A start or restart appends a `launched` event as soon as its session
   exists (0.40, `phase: "start"` or `"restart"`, `startId`), the session
   boundary that voids earlier waiting claims ([Waiting on you](#waiting-on-you)).

package/docs/desktop.md

@@ -79,13 +79,14 @@ login shell once (`$SHELL -ilc`, 3 s timeout) and puts its PATH in front of
 the inherited one, so the CLI probe, every `oats` call, a CLI picked with
 **Choose oats…**, and the tmux server and terminals the Desktop starts all run
 with your shell's PATH. Only PATH is taken from the shell, never the rest of
-its environment. If the shell fails, times out or prints no PATH, the
+its environment. The shell is started with your environment, without what the
+Desktop or its packaging added to its own (on the AppImage, the entries under
+its mount), like every other program the Desktop starts. If the shell fails, times out or prints no PATH, the
 inherited PATH stays: the backend's `/api/cli` reports `pathSource`
 (`login-shell` or `inherited`), `pathError` (why, or `null`) and
 `probePath` (the PATH the probe used), and the reason is logged at startup.
 A tmux server that was already running keeps its own environment; restart it
-(`tmux kill-server`, which ends its sessions) if its sessions should get the
-new PATH.
+if its sessions should get the new PATH, which ends its sessions: `tmux -L oats kill-server` for the OATS tmux server, where instances run, and `tmux kill-server` for your default server, where an instance started by an earlier kernel may still be.
 
 ## Opening a workspace
 
@@ -322,7 +323,7 @@ error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
 | --- | --- |
 | "Compatible oats CLI required" card | No CLI, or a version outside the range the card itself states. Copy the card's install command, or **Choose oats…** to point at the right binary; **Retry** re-probes. Spawn is disabled until a compatible CLI is verified. |
 | Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
-| Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux ls`. |
+| Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
 | Can't select/copy text in a terminal tab | A plain drag copies on release ([Copy from a terminal](#copy-from-a-terminal)). If nothing reaches the clipboard, the program in the pane has the mouse, or your tmux config sets `set-clipboard off`: hold **Option** (macOS) or **Shift** while dragging, then copy (Cmd+C / right-click → Copy). |
 | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
 | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use the workspace switcher → Add workspace to select the right folder. |