@awebai/oats 0.40.2 → 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,
@@ -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 || []) {
@@ -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
@@ -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)
 

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

package/docs/desktop-cli-api.md

@@ -1631,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"}}}
@@ -1642,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).
@@ -1658,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.
@@ -2185,7 +2197,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
   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,
@@ -2198,6 +2211,14 @@ 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.
@@ -2442,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:
@@ -2458,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`
@@ -2468,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.
@@ -2562,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. |