@awebai/oats 0.49.0 → 0.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/core.mjs CHANGED
@@ -45,11 +45,12 @@ import { createHash, randomUUID } from "node:crypto";
45
45
  import { fileURLToPath } from "node:url";
46
46
  import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
47
47
  import { noteRuntimeName } from "./deprecation.mjs";
48
- import { attachSessionTarget } from "./session-viewer.mjs";
48
+ import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
49
49
  import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
50
50
  import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
51
51
  import { killGroup } from "./process-group.mjs";
52
52
  import { interruptExitStatus, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
53
+ import { CLAIM_WAIT_MS, acquireClaim, releaseClaim, removeGoneClaim } from "./claim.mjs";
53
54
  import { captureLoginEnvironment } from "./login-environment.mjs";
54
55
 
55
56
  import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
@@ -126,6 +127,11 @@ export function legacyLocalAgents(root) {
126
127
  return { code: "legacy-local-agents", dirs, instances,
127
128
  message: `${instances.length} instance home${instances.length === 1 ? "" : "s"} under local-agents/ ${instances.length === 1 ? "is" : "are"} from OATS 0.25 and ${instances.length === 1 ? "is" : "are"} not managed by this kernel; retire ${instances.length === 1 ? "it" : "them"} with the 0.25 kernel or delete the directory once ${instances.length === 1 ? "it is" : "they are"} stopped${instances.length ? ` (${instances.join(", ")})` : ""}` };
128
129
  }
130
+ /** The instances directories under the agents root `root`: `<root>/<agent>/instances`, one per
131
+ * agent directory, whether or not it exists. */
132
+ export function instancesDirs(root) {
133
+ return subdirs(root).map((agent) => join(root, agent, "instances"));
134
+ }
129
135
  /** The instance homes under the agents root `root` (a directory <root>/<agent>/instances/<name>
130
136
  * whose instance.json records that name) that other users on the machine can read or enter (any
131
137
  * group or other permission bit): one `home-readable` problem naming them, with the exact chmod,
@@ -583,7 +589,7 @@ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME
583
589
  "OATS_TEST_LOGIN_SHELL",
584
590
  // The test seams of #796, the same: a worktree hook's fixed timeout, the fetch timeout of
585
591
  // `oats worktree add` (lib/worktree-hooks.mjs, lib/worktree.mjs), and the `ps` path of a
586
- // process's start time on a host with procfs (lib/worktree-hooks.mjs processStart).
592
+ // process's start time on a host with procfs, and the `ps` it runs (lib/worktree-hooks.mjs processStart).
587
593
  "OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS"]);
588
594
  export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
589
595
  const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
@@ -1966,12 +1972,22 @@ export function explicitInstanceName(name) {
1966
1972
  return name;
1967
1973
  }
1968
1974
 
1969
- function tmuxAlive(session) { return !!shTry(`tmux has-session -t ${shq(session)} 2>/dev/null && echo yes`); }
1970
1975
  /** The window names of `session` on the user's DEFAULT tmux server: only for a home that records no
1971
1976
  * socket (listInstances). OATS creates nothing there: new sessions live on the OATS server below. */
1972
- export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
1973
- if (!tmuxAlive(session)) return [];
1974
- return (shTry(`tmux list-windows -t ${shq(session)} -F '#{window_name}'`) || "").split("\n").filter(Boolean);
1977
+ export function tmuxWindows(session = DEFAULT_TMUX_SESSION) { return defaultTmuxWindows(session).windows; }
1978
+ /** tmuxWindows' read, keeping a missing socket file apart (#624): `{ windows }`, with `missingSocket`
1979
+ * (tmux's words) when the default server's socket file is missing. Any other failure reads as no
1980
+ * session. `has-session` first, as ever: it is the read-only probe a caller may expect for a home
1981
+ * that records no socket, and it words a missing socket file as list-windows does. */
1982
+ function defaultTmuxWindows(session) {
1983
+ const run = (args) => execFileSync("tmux", args, { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
1984
+ try {
1985
+ run(["has-session", "-t", session]);
1986
+ return { windows: run(["list-windows", "-t", session, "-F", "#{window_name}"]).split("\n").filter(Boolean) };
1987
+ } catch (e) {
1988
+ // Either read: the socket file can go between the two.
1989
+ return tmuxServerAbsence(e) === "missing-socket" ? { windows: [], missingSocket: tmuxFailure(e, "tmux failed") } : { windows: [] };
1990
+ }
1975
1991
  }
1976
1992
 
1977
1993
  // ---------- the OATS tmux server ----------
@@ -2003,8 +2019,11 @@ const exitedByItself = (e) => Number.isInteger(e?.status) && e.signal == null &&
2003
2019
  /** What the OATS server holds, as `list-sessions` answers: whether it runs, its socket (any session
2004
2020
  * names it), and whether a session named exactly `session` is there. No server and no such session
2005
2021
  * are the only answers that mean absent, and "no server" is read only from a call that exited by
2006
- * itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence. */
2007
- function oatsTmuxSessionSocket(session, io) {
2022
+ * itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence.
2023
+ * A missing socket file is absence only when `missingSocket(detail)` (a session start's check of its
2024
+ * home, missingSocketUnestablished) answers null; its reason refuses the start (#624). Without it, as
2025
+ * today. */
2026
+ function oatsTmuxSessionSocket(session, io, missingSocket) {
2008
2027
  let listed;
2009
2028
  try { listed = tmuxOatsServer(["list-sessions", "-F", "#{session_name}\t#{socket_path}"], io); }
2010
2029
  catch (e) {
@@ -2012,7 +2031,10 @@ function oatsTmuxSessionSocket(session, io) {
2012
2031
  // A tmux that could not be run at all is the one failure a person can act on: say so.
2013
2032
  if (e?.code === "ENOENT") throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: tmux was not found through this process's PATH. Run this command with a PATH that holds tmux`);
2014
2033
  if (!exitedByItself(e)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: tmux list-sessions did not exit by itself (${typeof e?.code === "string" ? e.code : e?.signal || "no exit status"})`);
2015
- if (tmuxServerLost(e)) return { server: null, present: false };
2034
+ const absence = tmuxServerAbsence(e);
2035
+ const why = absence === "missing-socket" && missingSocket ? missingSocket(tmuxFailure(e, "tmux list-sessions failed")) : null;
2036
+ if (why) throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether the OATS tmux server for session ${session} is running, so nothing was started: ${why}`);
2037
+ if (absence) return { server: null, present: false };
2016
2038
  throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: ${tmuxFailure(e, "tmux list-sessions failed")}`);
2017
2039
  }
2018
2040
  let server = null, present = false;
@@ -2280,10 +2302,10 @@ function oatsWindowEnvironment() {
2280
2302
  * again there when that server has gone. undefined when this process has no tmux to run: the
2281
2303
  * caller's backend check refuses that.
2282
2304
  */
2283
- function planOatsTmuxSession(session, io, { preview = false } = {}) {
2305
+ function planOatsTmuxSession(session, io, { preview = false, missingSocket } = {}) {
2284
2306
  if (!io?.exec && !which("tmux")) return undefined;
2285
2307
  let server, present;
2286
- try { ({ server, present } = oatsTmuxSessionSocket(session, io)); }
2308
+ try { ({ server, present } = oatsTmuxSessionSocket(session, io, missingSocket)); }
2287
2309
  catch (e) { if (preview) return undefined; throw e; } // a preview reports, it does not refuse on a read
2288
2310
  if (present || preview) return { server, present };
2289
2311
  return { server, present, env: oatsSessionEnvironment(session, io, { startsServer: !server }), startsServer: !server };
@@ -2359,10 +2381,12 @@ function launchLookup(configEnv, env, pane, configName, cwd) {
2359
2381
  * second lookup. tmux starts a server once: the first successful creator determines its initial
2360
2382
  * environment, and nothing here changes a running server's. E_RUNTIME_ENDPOINT_UNKNOWN when the
2361
2383
  * server cannot be read or names no socket, when this caller may not create the session, or when
2362
- * its own PATH names no tmux to create it with (creatorTmux).
2384
+ * its own PATH names no tmux to create it with (creatorTmux). `missingSocket` is a session start's
2385
+ * check of its home when the server's socket file is missing (oatsTmuxSessionSocket): with a reason,
2386
+ * E_SESSION_UNKNOWN and no server is created at that path.
2363
2387
  */
2364
- export function ensureOatsTmuxSession(session, hq, io, plan) {
2365
- let { server: socket, present } = oatsTmuxSessionSocket(session, io);
2388
+ export function ensureOatsTmuxSession(session, hq, io, plan, missingSocket) {
2389
+ let { server: socket, present } = oatsTmuxSessionSocket(session, io, missingSocket);
2366
2390
  if (!present) {
2367
2391
  // The executable is chosen here, where the creation is about to run, and nowhere earlier: a
2368
2392
  // session that exists needs none, so nothing is refused for it.
@@ -2375,7 +2399,7 @@ export function ensureOatsTmuxSession(session, hq, io, plan) {
2375
2399
  try { created = (io?.exec || execFileSync)(tmux, ["-u", ...address, "new-session", "-d", "-s", session, "-n", "hq", "-c", hq, "-P", "-F", "#{socket_path}\t#{window_id}"], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], env }).trim(); }
2376
2400
  catch (e) {
2377
2401
  if (oatsCoded(e)) throw e;
2378
- const again = oatsTmuxSessionSocket(session, io);
2402
+ const again = oatsTmuxSessionSocket(session, io, missingSocket);
2379
2403
  if (!again.present) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not create tmux session ${session} on the OATS tmux server: ${tmuxFailure(e, "tmux new-session failed")}`);
2380
2404
  socket = again.server;
2381
2405
  }
@@ -4377,7 +4401,9 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4377
4401
  relativeTo: relation ? relativeTo : undefined,
4378
4402
  spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
4379
4403
  policy: { childSpawns: ownChildPolicy },
4380
- ...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo, number: o.triggerEvent.number, subject: o.triggerEvent.subject ?? null, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile } } : {}),
4404
+ ...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo ?? null, number: o.triggerEvent.number ?? null, subject: o.triggerEvent.subject ?? null, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile,
4405
+ // A capability source's event carries its declared fields (a pull request's never does).
4406
+ ...(o.triggerEvent.fields && typeof o.triggerEvent.fields === "object" ? { fields: o.triggerEvent.fields } : {}) } } : {}),
4381
4407
  // K6c: a decision-bound spawn records what bound it, so a retry with the
4382
4408
  // same key replays this receipt instead of spawning again.
4383
4409
  // The FULL bound decision (placement + effective), exactly as the fence
@@ -4614,26 +4640,42 @@ export function servedIdentityLine(identity) {
4614
4640
  return `alias ${identity.alias || "?"} on ${identity.team || "?"}`;
4615
4641
  }
4616
4642
  /** The window names of `session` on the tmux server at `socket`: `{ windows }`, empty when the server
4617
- * or the session is gone; `{ error }` when the server could not be read. */
4643
+ * or the session is gone, with `missingSocket` (tmux's words) when the socket file is missing, which
4644
+ * alone does not say the server is gone (#624); `{ error }` when the server could not be read. */
4618
4645
  function recordedTmuxWindows(socket, session) {
4619
4646
  try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean) }; }
4620
4647
  catch (e) {
4621
- if (tmuxServerLost(e) || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
4648
+ const absence = tmuxServerAbsence(e);
4649
+ if (absence === "missing-socket") return { windows: [], missingSocket: tmuxFailure(e, "tmux list-windows failed") };
4650
+ if (absence || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
4622
4651
  return { error: String(e.stderr ?? e.message ?? "").trim() || "tmux list-windows failed" };
4623
4652
  }
4624
4653
  }
4625
- /** A status row's liveness from its session's windows: unknown (not false) when the server could not be read. */
4626
- function tmuxLiveness({ windows, error }, window) {
4627
- return error ? { running: null, runtimeState: "unreachable", runtimeError: error } : { running: windows.includes(window) };
4654
+ /** A status row's liveness from its session's windows: unknown (not false) when the server could not
4655
+ * be read, and, for a row whose server holds its endpoint (`endpoint`), when its socket file is
4656
+ * missing while a process works in the home or the scan (`scanHome()`, processesInHome's answer for
4657
+ * it) cannot tell (#624). */
4658
+ function tmuxLiveness({ windows, error, missingSocket }, window, scanHome, endpoint) {
4659
+ if (error) return { running: null, runtimeState: "unreachable", runtimeError: error };
4660
+ const running = windows.includes(window);
4661
+ const why = !running && missingSocket && endpoint ? missingSocketUnestablished(missingSocket, scanHome()) : null;
4662
+ return why ? { running: null, runtimeState: "unreachable", runtimeError: why } : { running };
4628
4663
  }
4629
- export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
4664
+ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
4630
4665
  // Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
4631
4666
  // socket, never the ambient $TMUX server, once per socket and session per call, so status costs no
4632
4667
  // more child processes as homes grow. A home without a recorded socket reads the default server.
4668
+ // A row whose socket file is missing is checked against one process scan of the host, made the
4669
+ // first time a row needs it and shared by every row (`io` reaches it: processesInHome).
4670
+ let hostScan;
4671
+ const scanOf = (home) => () => {
4672
+ hostScan ??= hostProcesses(io);
4673
+ return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
4674
+ };
4633
4675
  const tmuxByEndpoint = new Map();
4634
4676
  const windowsOf = (session, socket) => {
4635
4677
  const key = JSON.stringify([socket ?? null, session]);
4636
- if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : { windows: tmuxWindows(session) });
4678
+ if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : defaultTmuxWindows(session));
4637
4679
  return tmuxByEndpoint.get(key);
4638
4680
  };
4639
4681
  const readInstancesOf = (agentDir) => {
@@ -4677,7 +4719,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
4677
4719
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
4678
4720
  const liveness = recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)))
4679
4721
  ? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
4680
- : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name);
4722
+ : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
4723
+ // A home that records no socket and no launch (--no-launch) reads the default server only
4724
+ // by default: that server's missing socket says nothing about it, and stays "not running".
4725
+ !!meta.tmux?.socket || meta.launched === true);
4681
4726
  const identity = servedIdentityOf(meta);
4682
4727
  // Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
4683
4728
  // else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
@@ -5084,7 +5129,15 @@ function retirementStateRoot(home) {
5084
5129
  // Independent of the bytes it authenticates, but colocated with the agent's
5085
5130
  // already instance-owned storage rather than the source repository or user
5086
5131
  // config home. Retiring <instances>/<name> never removes this sibling.
5087
- return join(dirname(home), ".oats-retirement");
5132
+ return instancesRetirementRoot(dirname(home));
5133
+ }
5134
+ /** The retirement state of the homes in the instances directory `instances`. */
5135
+ function instancesRetirementRoot(instances) {
5136
+ return join(instances, ".oats-retirement");
5137
+ }
5138
+ /** Where retire writes the recovery copies of the homes in the instances directory `instances`. */
5139
+ export function retirementRecoveryRoot(instances) {
5140
+ return join(instancesRetirementRoot(instances), "recovery");
5088
5141
  }
5089
5142
 
5090
5143
  /** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
@@ -5648,16 +5701,38 @@ function extraWorktreesOf(home) {
5648
5701
  }
5649
5702
  return trees;
5650
5703
  }
5704
+ /** Where retire re-homes the worktrees it retains, one directory per repository under it. */
5705
+ export function retainedWorktreesRoot(workspace) {
5706
+ return join(workspace, ".agents", "worktrees");
5707
+ }
5708
+ /** The longest retained-worktree leaf before its `-N` suffix, in bytes (awebai/oats#821). The
5709
+ * leaf is one path component, so it must fit NAME_MAX (255 on the usual filesystems). 16 bytes
5710
+ * are kept as a margin, as the test fixtures keep: nothing appends to the leaf's name today
5711
+ * (`git worktree move` renames to the path it is given, which does not exist, and adds nothing),
5712
+ * so the margin is headroom only. 8 more are kept for the `-N` suffix (`-` and up to seven
5713
+ * digits). A leaf is then at most 231 bytes, and at most 239 with its suffix. */
5714
+ export const RETAINED_LEAF_MAX = 255 - 16 - 8;
5651
5715
  /** Where a retired worktree is re-homed: `<workspace>/.agents/worktrees/<repoName>/<leaf>`,
5652
- * the leaf being the branch, else `detached-<commit>`; when that exists (or
5653
- * `taken` holds it), `<leaf>-2`, `-3`, … The one naming rule of work/ and of
5654
- * the extra trees. Creates nothing. */
5716
+ * the leaf being the branch, else `detached-<commit>`, with every run of characters outside
5717
+ * `[A-Za-z0-9._-]` made `-`; when that exists (or `taken` holds it), `<leaf>-2`, `-3`, … A leaf
5718
+ * over RETAINED_LEAF_MAX is cut to fit, its trailing `-` trimmed, and followed by `-` and 6 hex
5719
+ * of the SHA-256 of the full branch name: deterministic, readable, and one per branch. The
5720
+ * character class keeps the leaf ASCII, so its length in characters is its length in bytes;
5721
+ * widen the class and the bound must measure bytes. The one naming rule of work/ and of the
5722
+ * extra trees, the plan's `movedTo` and the apply's alike. Creates nothing. */
5655
5723
  function retainedWorktreeDest(workspace, repo, branch, commit, taken = new Set()) {
5656
5724
  const repoName = basename(realPathOrNearest(repo)).replace(/\.git$/, "") || "repo";
5657
- const leaf = (branch ?? `detached-${(commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
5658
- const retainedRoot = join(workspace, ".agents", "worktrees", repoName);
5659
- let dest = join(retainedRoot, leaf);
5660
- for (let n = 2; existsSync(dest) || taken.has(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
5725
+ const name = branch ?? `detached-${(commit || "unknown").slice(0, 12)}`;
5726
+ const flat = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
5727
+ const hash = () => createHash("sha256").update(name, "utf8").digest("hex").slice(0, 6);
5728
+ /** The leaf in `room` bytes: as it is when it fits, else cut and hashed. */
5729
+ const fit = (room) => flat.length <= room ? flat : `${flat.slice(0, room - 7).replace(/-+$/, "")}-${hash()}`;
5730
+ const retainedRoot = join(retainedWorktreesRoot(workspace), repoName);
5731
+ let dest = join(retainedRoot, fit(RETAINED_LEAF_MAX));
5732
+ // The 8 bytes kept for `-N` hold `-2` to `-9999999`; a longer suffix takes its extra bytes from
5733
+ // the leaf's readable part, never its hash, so a leaf with its suffix never passes
5734
+ // RETAINED_LEAF_MAX + 8.
5735
+ for (let n = 2; existsSync(dest) || taken.has(dest); n++) dest = join(retainedRoot, `${fit(Math.min(RETAINED_LEAF_MAX, RETAINED_LEAF_MAX + 7 - String(n).length))}-${n}`);
5661
5736
  taken.add(dest);
5662
5737
  return dest;
5663
5738
  }
@@ -5712,7 +5787,7 @@ function retirementBaselineValid(baseline, home) {
5712
5787
  * as not copied (none without a valid baseline). */
5713
5788
  export function retirementRecoveryFacts(home) {
5714
5789
  const baseline = readJsonOrUndefined(findRetirementBaseline(home));
5715
- return { recoveryRoot: join(retirementStateRoot(home), "recovery"), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
5790
+ return { recoveryRoot: retirementRecoveryRoot(dirname(home)), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
5716
5791
  }
5717
5792
  function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
5718
5793
  if (mode === "directory") assertDirectoryRoots(home);
@@ -5852,21 +5927,104 @@ export function inspectInstanceSession(home) {
5852
5927
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
5853
5928
  function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
5854
5929
 
5855
- /** K3: quiesce one instance's session and RETAIN everything else — home,
5856
- * worktree, transcript, launch configuration — so `restart` can bring it back.
5857
- * Exactly restart's stop half under the same independent endpoint authority
5858
- * (`instanceSessionTarget`), bounded and never escalated: a harness still
5859
- * there after the grace is reported still running, nothing is killed harder.
5860
- * A no-launch or already-idle instance is a no-op that says so. */
5861
- function tmuxServerLost(e) { return /no server running on |(?:error connecting to|failed to connect to) .*(?:No such file or directory|Connection refused)/i.test(String(e.stderr ?? e.message ?? "")); }
5930
+ /** How a failed tmux call reads the server it addressed (#624). "gone": no server listens on the
5931
+ * socket (`no server running on`, or a refused connection), which is definitive. "missing-socket":
5932
+ * the socket file is not there (`No such file or directory`). After a reboot the server is gone,
5933
+ * but a tmux server outlives its removed socket file, so that alone establishes nothing: a caller
5934
+ * concludes stopped from it only when no process works in the home (missingSocketUnestablished).
5935
+ * null: anything else. */
5936
+ function tmuxServerAbsence(e) {
5937
+ const text = String(e?.stderr ?? e?.message ?? "");
5938
+ if (/no server running on |(?:error connecting to|failed to connect to) .*Connection refused/i.test(text)) return "gone";
5939
+ if (/(?:error connecting to|failed to connect to) .*No such file or directory/i.test(text)) return "missing-socket";
5940
+ return null;
5941
+ }
5942
+ function tmuxServerLost(e) { return tmuxServerAbsence(e) !== null; }
5943
+ /** tmux's own way back for a server that lost its socket file (tmux(1), `-S`). Named, never performed. */
5944
+ const TMUX_SOCKET_REMEDY = "tmux recreates a removed socket file when its server process receives SIGUSR1";
5945
+ /** Processes as a refusal names them: pid and program, at most five, then how many more. */
5946
+ function namedProcesses(processes) {
5947
+ return `${processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${processes.length > 5 ? `, and ${processes.length - 5} more` : ""}`;
5948
+ }
5949
+ /** A missing socket file (`detail`, tmux's words) checked against `scan`, processesInHome's answer
5950
+ * for the home (#624): null when it ran and found no process there, so the server is taken as gone,
5951
+ * as after a reboot; otherwise why the state is not established. Any process working in the home
5952
+ * counts, a person's shell included: the words name it, so the person can act on it. */
5953
+ function missingSocketUnestablished(detail, scan) {
5954
+ if (!scan.ok) return `${detail}; whether a process still works in this home could not be established (${scan.error})`;
5955
+ if (scan.processes.length) return `${detail}; a process still works in this home (${namedProcesses(scan.processes)}), so its tmux server may still be running without its socket file: ${TMUX_SOCKET_REMEDY}`;
5956
+ return null;
5957
+ }
5958
+ /** Whether this host's /proc can be read: Linux, and this process's own `cwd` link resolves. */
5959
+ function procReadable() {
5960
+ if (process.platform !== "linux") return { ok: false, error: "this host has no /proc to read (it is not Linux)" };
5961
+ try { readlinkSync("/proc/self/cwd"); return { ok: true }; }
5962
+ catch (e) { return { ok: false, error: `/proc/self/cwd cannot be read (${e.code || e.message})` }; }
5963
+ }
5964
+ /** Which process scan this host offers, checked cheaply and without scanning (doctor reports it):
5965
+ * /proc on Linux, else lsof when it is on PATH. → { mechanism: "proc" | "lsof" } | { mechanism: null, error } */
5966
+ export function processScanAvailability() {
5967
+ const proc = procReadable();
5968
+ if (proc.ok) return { mechanism: "proc" };
5969
+ if (process.env.PATH !== undefined && lookupOnPath("lsof", process.env.PATH)) return { mechanism: "lsof" };
5970
+ return { mechanism: null, error: `${proc.error}, and lsof is not on PATH` };
5971
+ }
5972
+ /** Doctor's information line when this host has no process scan (`availability`, from
5973
+ * processScanAvailability); none when it has one. */
5974
+ export function processScanInformation(availability = processScanAvailability()) {
5975
+ if (availability.mechanism) return [];
5976
+ return [`process-scan-unavailable: ${availability.error}; retire refuses where it must rule out a live process in an instance home (a home without its session receipt, a missing recorded tmux socket, a Herdr home), and session start/stop refuse when a recorded tmux socket is missing; install lsof`];
5977
+ }
5862
5978
  /**
5863
- * The live processes (other than this one and its children) whose working
5864
- * directory is inside `home`: `lsof -a -d cwd` over the host, one call.
5865
- * → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan
5866
- * could not run, did not complete or listed no process: a caller must treat
5867
- * that as unknown, never as none).
5979
+ * Every live process on the host (other than this one and its direct children) with its working
5980
+ * directory, from one scan: /proc on Linux (`io.procRoot` names another root), else one `lsof -a -d
5981
+ * cwd` listing; an injected `io.exec` stands in for the host's commands, so it is lsof's. Each cwd
5982
+ * is kept in its on-disk spelling (canonicalHomePath); one the kernel reports deleted (`<path>
5983
+ * (deleted)`) is kept as both spellings. A process this user may not inspect (another user's, or a
5984
+ * non-dumpable one) is not seen by either mechanism.
5985
+ * → { ok: true, processes: [{pid, command, cwds}] } | { ok: false, error }
5868
5986
  */
5869
- export function processesInHome(home, io) {
5987
+ function hostProcesses(io) {
5988
+ const rows = typeof io?.procRoot === "string" ? procRows(io.procRoot)
5989
+ : !io?.exec && procReadable().ok ? procRows("/proc")
5990
+ : lsofRows(io);
5991
+ if (!rows.ok) return rows;
5992
+ const processes = [];
5993
+ for (const { pid, ppid, command, cwd } of rows.rows) {
5994
+ if (!pid || pid === process.pid || ppid === process.pid || typeof cwd !== "string") continue;
5995
+ const spellings = cwd.endsWith(" (deleted)") ? [cwd, cwd.slice(0, -" (deleted)".length)] : [cwd];
5996
+ processes.push({ pid, command: command ?? "?", cwds: spellings.map((p) => canonicalHomePath(p)) });
5997
+ }
5998
+ return { ok: true, processes };
5999
+ }
6000
+ /** The processes of a hostProcesses listing that work in `home`, compared in its on-disk spelling. */
6001
+ function processesWorkingIn(processes, home) {
6002
+ const realHome = canonicalHomePath(home);
6003
+ return processes.filter((p) => p.cwds.some((cwd) => cwd === realHome || cwd.startsWith(`${realHome}/`))).map(({ pid, command }) => ({ pid, command }));
6004
+ }
6005
+ /** /proc read as a scan: each numeric entry's `cwd` link, `comm` and `stat` (its ppid is the second
6006
+ * field after the last `)`, which ends the command). A pid that cannot be read (it ended meanwhile,
6007
+ * this user may not inspect it, or any other failure on that one pid) is not seen. A root that
6008
+ * cannot be listed, or one that lists no readable process, is a failed scan, never an empty one. */
6009
+ function procRows(root) {
6010
+ let names;
6011
+ try { names = readdirSync(root); }
6012
+ catch (e) { return { ok: false, error: `${root} cannot be read (${e.code || e.message})` }; }
6013
+ const rows = [];
6014
+ for (const name of names) {
6015
+ if (!/^\d+$/.test(name)) continue;
6016
+ try {
6017
+ const cwd = readlinkSync(join(root, name, "cwd"));
6018
+ const command = readFileSync(join(root, name, "comm"), "utf8").replace(/\n$/, "");
6019
+ const stat = readFileSync(join(root, name, "stat"), "utf8");
6020
+ rows.push({ pid: Number(name), ppid: Number(stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[1]), command, cwd });
6021
+ } catch { /* not seen */ }
6022
+ }
6023
+ // A real /proc always lists at least this process.
6024
+ if (!rows.length) return { ok: false, error: `${root} listed no process` };
6025
+ return { ok: true, rows };
6026
+ }
6027
+ function lsofRows(io) {
5870
6028
  let out;
5871
6029
  try { out = (io?.exec || execFileSync)("lsof", ["-a", "-d", "cwd", "-F", "pRcn", "-w"], { encoding: "utf8", timeout: 20000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); }
5872
6030
  catch (e) {
@@ -5877,7 +6035,7 @@ export function processesInHome(home, io) {
5877
6035
  // listing.
5878
6036
  const completed = e?.status === 1 && e.signal == null && e.code === undefined;
5879
6037
  if (completed && typeof e.stdout === "string") out = e.stdout;
5880
- else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH"
6038
+ else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH; install lsof"
5881
6039
  : e?.code === "ETIMEDOUT" ? "lsof timed out"
5882
6040
  : e?.code === "ENOBUFS" ? "lsof printed more output than the scan reads"
5883
6041
  : e?.signal ? `lsof was ended by ${e.signal}`
@@ -5885,21 +6043,27 @@ export function processesInHome(home, io) {
5885
6043
  }
5886
6044
  // A listing holds at least one process (lsof and its caller are always in it), whichever exit it came with.
5887
6045
  if (!/^p\d+$/m.test(String(out))) return { ok: false, error: "lsof listed no process" };
5888
- // lsof reports each cwd in its on-disk spelling: the home is compared in it too.
5889
- const realHome = canonicalHomePath(home);
5890
- const processes = [];
6046
+ const rows = [];
5891
6047
  let cur = {};
5892
6048
  for (const line of String(out).split("\n")) {
5893
6049
  const tag = line[0], value = line.slice(1);
5894
- if (tag === "p") cur = { pid: Number(value) };
6050
+ if (tag === "p") { cur = { pid: Number(value) }; rows.push(cur); }
5895
6051
  else if (tag === "R") cur.ppid = Number(value);
5896
6052
  else if (tag === "c") cur.command = value;
5897
- else if (tag === "n" && cur.pid && cur.pid !== process.pid && cur.ppid !== process.pid) {
5898
- const cwd = canonicalHomePath(value);
5899
- if (cwd === realHome || cwd.startsWith(`${realHome}/`)) processes.push({ pid: cur.pid, command: cur.command ?? "?" });
5900
- }
6053
+ else if (tag === "n") cur.cwd = value;
5901
6054
  }
5902
- return { ok: true, processes };
6055
+ return { ok: true, rows };
6056
+ }
6057
+ /**
6058
+ * The live processes (other than this one and its direct children) whose working directory is
6059
+ * inside `home`, from one scan of the host (hostProcesses: /proc on Linux, else lsof). A pid and a
6060
+ * program name, never an argument list.
6061
+ * → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan could not run, did
6062
+ * not complete or listed no process: a caller must treat that as unknown, never as none).
6063
+ */
6064
+ export function processesInHome(home, io) {
6065
+ const scan = hostProcesses(io);
6066
+ return scan.ok ? { ok: true, processes: processesWorkingIn(scan.processes, home) } : scan;
5903
6067
  }
5904
6068
 
5905
6069
  /**
@@ -5920,7 +6084,7 @@ export function observeSessionWithoutReceipt(home, meta, io) {
5920
6084
  if (!recorded.absent) return recorded;
5921
6085
  const scan = processesInHome(home, io);
5922
6086
  if (!scan.ok) return { absent: false, backend: recorded.backend, note: `could not scan for a process working in this home (${scan.error})` };
5923
- if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${scan.processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${scan.processes.length > 5 ? `, and ${scan.processes.length - 5} more` : ""}); stop it, then retire` };
6087
+ if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${namedProcesses(scan.processes)}); stop it, then retire` };
5924
6088
  return recorded;
5925
6089
  }
5926
6090
  function recordedSessionAbsence(home, meta, io) {
@@ -5943,6 +6107,13 @@ function recordedSessionAbsence(home, meta, io) {
5943
6107
  if (inHome) return { absent: false, backend: "tmux", note: `a tmux pane (${inHome[0]}:${inHome[1]}) on ${tmux.socket} works in this home` };
5944
6108
  return { absent: true, backend: "tmux", note: `no session receipt (a home from before 0.25.9); the recorded window ${where} is gone` };
5945
6109
  }
6110
+ /** K3: quiesce one instance's session and RETAIN everything else — home,
6111
+ * worktree, transcript, launch configuration — so `restart` can bring it back.
6112
+ * Exactly restart's stop half under the same independent endpoint authority
6113
+ * (`instanceSessionTarget`), bounded and never escalated: a harness still
6114
+ * there after the grace is reported still running, nothing is killed harder.
6115
+ * A no-launch or already-idle instance is a no-op that says so. A missing socket
6116
+ * file is idle only when no process works in the home (#624). */
5946
6117
  export function stopInstanceSession(home, o = {}) {
5947
6118
  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
5948
6119
  if (o.graceMs !== undefined && (!Number.isSafeInteger(o.graceMs) || o.graceMs < 1 || o.graceMs > 300000)) throw oatsError("E_BAD_ARGS", "stop grace must be 1-300000 ms");
@@ -5952,7 +6123,12 @@ export function stopInstanceSession(home, o = {}) {
5952
6123
  if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
5953
6124
  let before;
5954
6125
  try { before = inspectSessionTarget(s.target); }
5955
- catch (e) { if (tmuxServerLost(e)) before = { present: false, state: "stopped" }; else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${e.message}`); }
6126
+ catch (e) {
6127
+ const absence = tmuxServerAbsence(e);
6128
+ const why = absence === "missing-socket" ? missingSocketUnestablished(tmuxFailure(e, e.message), processesInHome(realHome, o.io)) : null;
6129
+ if (absence && !why) before = { present: false, state: "stopped" };
6130
+ else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${why ?? e.message}`);
6131
+ }
5956
6132
  if (!before.present || before.state === "shell" || before.state === "stopped") return { home: s.home, backend: s.target.backend, stopped: false, alreadyIdle: true, state: before.state, receipt: null };
5957
6133
  const receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, kill: o.io?.kill, sleep: o.io?.sleep });
5958
6134
  writeJsonAtomic(join(realHome, ".oats-stop.json"), { instance: basename(realHome), at: new Date().toISOString(), stop: receipt, retained: ["home", "work", "transcript", "launch"] });
@@ -5972,10 +6148,11 @@ function stopRecordedChildren(children) {
5972
6148
  });
5973
6149
  }
5974
6150
 
5975
- export async function attachInstanceSession(home) {
6151
+ export async function attachInstanceSession(home, { detachKey } = {}) {
6152
+ if (detachKey !== undefined) requireDetachKey(detachKey);
5976
6153
  const s = instanceSessionTarget(home);
5977
6154
  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
5978
- return attachSessionTarget(s.target);
6155
+ return attachSessionTarget(s.target, { detachKey });
5979
6156
  }
5980
6157
 
5981
6158
  export function inputInstanceSession(home, text) {
@@ -6359,7 +6536,16 @@ export function startInstanceSession(home, o = {}) {
6359
6536
  // spawned records no modules, and there is no scope configuration left to
6360
6537
  // re-resolve it against. Retire still works on it.
6361
6538
  if (!isWorkspaceHome(readMeta())) throw preWorkspaceHome(realHome, "nothing was started");
6362
- const lostTmuxServer = tmuxServerLost;
6539
+ // A missing socket file is a stopped server only when no process works in this home (#624): its
6540
+ // check, for a recorded session and for the OATS server lookup. A failed read of a recorded session
6541
+ // is `{ stopped: true }` when its server is gone (or its socket file is missing and that check
6542
+ // passes), else `{ stopped: false, why }`: the check's reason, or null for another failure.
6543
+ const missingSocket = (detail) => missingSocketUnestablished(detail, processesInHome(realHome, rawIo));
6544
+ const lostServer = (e) => {
6545
+ const absence = tmuxServerAbsence(e);
6546
+ const why = absence === "missing-socket" ? missingSocket(tmuxFailure(e, e.message)) : null;
6547
+ return absence && !why ? { stopped: true } : { stopped: false, why };
6548
+ };
6363
6549
  const launchFailure = (error) => {
6364
6550
  // execFileSync errors embed argv (including capability environment) in
6365
6551
  // message; backend stderr can echo it too. Neither belongs in the API.
@@ -6435,8 +6621,9 @@ export function startInstanceSession(home, o = {}) {
6435
6621
  checkRoots();
6436
6622
  try { st = inspectSessionTarget(pending.target, o.io); }
6437
6623
  catch (e) {
6438
- if (lostTmuxServer(e)) st = { present: false, state: "stopped" };
6439
- else throw oatsError("E_SESSION_UNKNOWN", `an earlier start of ${basename(realHome)} recorded a session (tmux ${pending.target.session}:${pending.target.window} on ${pending.target.socket}) that cannot be observed now: ${String(e.stderr ?? e.message ?? "").trim() || e.message}; the receipt ${pendingPath} is kept and nothing was started`);
6624
+ const lost = lostServer(e);
6625
+ if (lost.stopped) st = { present: false, state: "stopped" };
6626
+ else throw oatsError("E_SESSION_UNKNOWN", `an earlier start of ${basename(realHome)} recorded a session (tmux ${pending.target.session}:${pending.target.window} on ${pending.target.socket}) that cannot be observed now: ${lost.why ?? (String(e.stderr ?? e.message ?? "").trim() || e.message)}; the receipt ${pendingPath} is kept and nothing was started`);
6440
6627
  }
6441
6628
  // A launch may still consist entirely of shells (startup files, a
6442
6629
  // shell-script harness). Only its own completion marker proves this
@@ -6512,18 +6699,19 @@ export function startInstanceSession(home, o = {}) {
6512
6699
  const planSession = receipt.target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
6513
6700
  let sessionPlanRead;
6514
6701
  const sessionPlan = () => {
6515
- if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io) }; } catch (e) { sessionPlanRead = { error: e }; } }
6702
+ if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io, { missingSocket }) }; } catch (e) { sessionPlanRead = { error: e }; } }
6516
6703
  if (sessionPlanRead.error) throw sessionPlanRead.error;
6517
6704
  return sessionPlanRead.plan;
6518
6705
  };
6519
6706
  // The recorded target, observed once: by the plan's lookup, which must know whether the pane will
6520
- // be reused before it chooses where to look, or by the gate below. A lost server is a stopped one;
6521
- // any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does not decide it.
6707
+ // be reused before it chooses where to look, or by the gate below. A lost server is a stopped one
6708
+ // (lostServer); any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does
6709
+ // not decide it.
6522
6710
  let recordedRead;
6523
6711
  const recordedState = () => {
6524
6712
  if (!recordedRead) {
6525
6713
  try { recordedRead = { state: receipt.target ? inspectSessionTarget(receipt.target, o.io) : { present: false, state: "not-launched" } }; }
6526
- catch (e) { recordedRead = lostTmuxServer(e) ? { state: { present: false, state: "stopped" } } : { error: e }; }
6714
+ catch (e) { const lost = lostServer(e); recordedRead = lost.stopped ? { state: { present: false, state: "stopped" } } : { error: lost.why ? new Error(lost.why) : e }; }
6527
6715
  }
6528
6716
  return recordedRead;
6529
6717
  };
@@ -6553,7 +6741,7 @@ export function startInstanceSession(home, o = {}) {
6553
6741
  const recorded = recordedState();
6554
6742
  if (reusable(recorded.state)) return panePath(receipt.target.socket, receipt.target.session, o.io, realHome);
6555
6743
  if (recorded.error) return undefined; // the gate refuses below; the lookup does not decide it
6556
- const preview = planOatsTmuxSession(planSession, o.io, { preview: true });
6744
+ const preview = planOatsTmuxSession(planSession, o.io, { preview: true, missingSocket });
6557
6745
  if (!preview || preview.server) return expectedPanePath(preview, planSession, o.io, realHome);
6558
6746
  try { return expectedPanePath(sessionPlan(), planSession, o.io, realHome); } catch (e) { if (oatsCoded(e)) return undefined; throw e; }
6559
6747
  };
@@ -6662,7 +6850,12 @@ export function startInstanceSession(home, o = {}) {
6662
6850
  writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
6663
6851
  appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
6664
6852
  if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
6665
- try { state = inspectSessionTarget(target, o.io); } catch (e) { if (lostTmuxServer(e)) state = { present: false, state: "stopped" }; else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
6853
+ try { state = inspectSessionTarget(target, o.io); }
6854
+ catch (e) {
6855
+ const lost = lostServer(e);
6856
+ if (lost.stopped) state = { present: false, state: "stopped" };
6857
+ else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}, so nothing was started: ${lost.why ?? (String(e.stderr ?? e.message ?? "").trim() || e.message)}`);
6858
+ }
6666
6859
  if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
6667
6860
  }
6668
6861
  // The kernel that launches the harness is the one the agent's plain `oats` runs.
@@ -6710,7 +6903,7 @@ export function startInstanceSession(home, o = {}) {
6710
6903
  // A replacement window (never launched, recorded window gone, recorded server gone) is created
6711
6904
  // on the OATS server, wherever the home was recorded: one socket from here to the record.
6712
6905
  const recordedSocket = socket ? resolve(socket) : null;
6713
- socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan);
6906
+ socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan, missingSocket);
6714
6907
  if (lookAgain(() => panePath(socket, session, o.io, realHome))) { planExtra.launch = launchPlan.recipe; windowCmd = windowCommand(); }
6715
6908
  let names;
6716
6909
  try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
@@ -7237,7 +7430,7 @@ function mirrorTopLevel(source, dest) {
7237
7430
  for (const e of entriesAsBytes(source)) if (!e.name.equals(GIT_NAME)) copyTreeSafe(joinBytes(source, e.name), joinBytes(dest, e.name));
7238
7431
  }
7239
7432
 
7240
- const RECOVERABLE_GIT_ADMIN = [
7433
+ export const RECOVERABLE_GIT_ADMIN = [
7241
7434
  "MERGE_HEAD", "MERGE_MSG", "AUTO_MERGE", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD",
7242
7435
  "BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
7243
7436
  ];
@@ -7738,7 +7931,9 @@ function homeOnlyRecovery(observation, meta) {
7738
7931
  * (tree-copy.mjs), and a read-only one (a Go module cache, 0555) keeps
7739
7932
  * rmSync from unlinking what is in it: each directory is made u+rwx first,
7740
7933
  * before it is read (an unreadable one could not be listed), symbolic links
7741
- * are never followed, and then the tree is removed. Never throws: a cleanup
7934
+ * are never followed, and then the tree is removed. Names are listed and
7935
+ * joined as bytes, as the copier writes them, so a directory whose name is
7936
+ * not UTF-8 is reached too (#827). Never throws: a cleanup
7742
7937
  * must not replace the error that made it (#659). → null when the staging is
7743
7938
  * gone, else the clause a refusal adds to name what is left. */
7744
7939
  function removeStaging(staging) {
@@ -7748,9 +7943,9 @@ function removeStaging(staging) {
7748
7943
  const st = lstatSync(dir);
7749
7944
  if (!st.isDirectory()) return;
7750
7945
  if ((st.mode & 0o700) !== 0o700) chmodSync(dir, (st.mode & 0o7777) | 0o700);
7751
- names = readdirSync(dir);
7946
+ names = entriesAsBytes(dir).map((e) => e.name);
7752
7947
  } catch { return; }
7753
- for (const name of names) open(join(dir, name));
7948
+ for (const name of names) open(joinBytes(dir, name));
7754
7949
  };
7755
7950
  try { open(staging); rmSync(staging, { recursive: true, force: true }); } catch { /* named below */ }
7756
7951
  try { lstatSync(staging); } catch (e) { if (e?.code === "ENOENT") return null; }
@@ -7764,7 +7959,7 @@ function removeStaging(staging) {
7764
7959
  * will add to. → { receipt, manifest }: the receipt retire reports, and
7765
7960
  * recovery.json as written. */
7766
7961
  function writeRetirementRecovery(observation, meta, instance, phase) {
7767
- const recoveryRoot = join(retirementStateRoot(observation.home), "recovery");
7962
+ const recoveryRoot = retirementRecoveryRoot(dirname(observation.home));
7768
7963
  mkdirSync(recoveryRoot, { recursive: true });
7769
7964
  if (observation.directory && realpathSync(recoveryRoot) !== join(realpathSync(dirname(observation.home)), ".oats-retirement", "recovery")) {
7770
7965
  throw oatsError("E_WORK_PRESERVATION_FAILED", "directory recovery storage was redirected; retain the source home rather than copying into an unowned or disposable location");
@@ -7984,7 +8179,9 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
7984
8179
  } catch { /* the marker alone then shows RETIRING; status names its age */ }
7985
8180
  });
7986
8181
  child.unref();
7987
- writeFileSync(marker, JSON.stringify(intent, null, 2) + "\n");
8182
+ // The marker names its completion (pid and start time; the start is null when it cannot be read):
8183
+ // while that process lives, any other retire of this home is refused (refusePendingCompletion).
8184
+ writeFileSync(marker, JSON.stringify({ ...intent, completionPid: child.pid, completionStart: processStartToken(child.pid) }, null, 2) + "\n");
7988
8185
  return {
7989
8186
  retired: name, agent: found.agent.name, deferred: true, pendingMarker: marker,
7990
8187
  resultPath, logPath, completesInSec: delaySec, completionPid: child.pid,
@@ -8006,6 +8203,9 @@ const OBSOLETE_DELETE_BRANCH_SENTENCE = "this self-retire was requested with --d
8006
8203
  /** The one internal option that says the retirement completes such an intent.
8007
8204
  * A symbol, so no caller can set it from parsed arguments or JSON. */
8008
8205
  const OBSOLETE_DELETE_BRANCH = Symbol("an older self-retire intent with --delete-branch");
8206
+ /** The one internal option that says the retirement is a deferred self-retire's completion
8207
+ * (completeDeferredRetirement). A symbol, so no caller can set it from parsed arguments or JSON. */
8208
+ const COMPLETES_DEFERRED = Symbol("the completion of a deferred self-retire");
8009
8209
  export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
8010
8210
 
8011
8211
  export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
@@ -8037,6 +8237,10 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
8037
8237
  ...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
8038
8238
  ...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
8039
8239
  ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
8240
+ // The retire that scheduled this completion may still hold the home's claim, about to write
8241
+ // the marker and return: it is waited for, so the two are ordered by the claim and never by
8242
+ // which process is faster.
8243
+ [COMPLETES_DEFERRED]: true,
8040
8244
  });
8041
8245
  } catch (e) {
8042
8246
  record({ ok: false, error: { code: e.code, message: e.message }, ...(e.details?.childrenStopped ? { childrenStopped: e.details.childrenStopped } : {}), ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
@@ -8066,30 +8270,153 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
8066
8270
  * (awebai/oats#693): the CLI cleans that home's wake schedules. A symbol, so
8067
8271
  * the printed and JSON receipt, and a recorded one, do not carry it. */
8068
8272
  export const RETIRE_SELECTED_HOME = Symbol("oats.retireSelectedHome");
8069
- export function retireInstance(root, name, o = {}) {
8070
- if (o.deleteBranch) throw oatsError("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
8071
- const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
8072
- // self-retire: the caller IS the instance. Without --keep-dir the whole
8073
- // retirement is deferred to a detached external completion (below); with
8074
- // --keep-dir the old in-process path runs and kills the window LAST.
8075
- const self = o.self === true;
8076
- // Names are unique per agent dir only: two agents can own an instance of
8077
- // the same name (dev --purpose foo-1 and agent dev-foo). Retirement is
8078
- // destructive, so a name that resolves to several homes is refused unless
8079
- // the caller says which home (--home), and a home is accepted only when it
8080
- // is one of that name's homes under this root.
8273
+ /** An option of retireInstance: a function it calls once it holds the home's claim, has resolved
8274
+ * the home again and has found no pending self-retire, before it reads anything else. What the
8275
+ * function throws is the retire's answer, and nothing was done; what it returns, `{ children?,
8276
+ * plannedExtraWorktrees? }`, sets those two options. `oats retire` reads here what the retire
8277
+ * acts on, so that it is the state the retire starts from, never one another retire changed
8278
+ * afterwards: a guarded apply its plan, once, refusing a revision that is not the one shown
8279
+ * (E_PLAN_STALE); a plain or `--self` retire its recorded children. Against a retire in flight
8280
+ * the answer is that it is running, and neither is read. A symbol, so no caller can set it from
8281
+ * parsed arguments or JSON. */
8282
+ export const RETIRE_UNDER_CLAIM = Symbol("oats.retireUnderClaim");
8283
+ /** How many times a retire starts over because the name resolved to another home once it held the
8284
+ * claim of the first (that one removed, a same-named home of another agent made, in between). */
8285
+ const RETIRE_CLAIM_RESTARTS = 2;
8286
+
8287
+ /** The claim file of a retire of `home`: `<instances>/.oats-retirement/claims/<name>.lock`. Beside
8288
+ * the homes, never inside one: a home's bytes are what its retire observes, copies and removes. */
8289
+ function retireClaimPath(home) {
8290
+ return join(instancesRetirementRoot(dirname(home)), "claims", `${basename(home)}.lock`);
8291
+ }
8292
+
8293
+ /** The refusals of a retire of `name` (home `home`) that cannot take its claim `lock`, as
8294
+ * lib/claim.mjs asks for them. All E_LIFECYCLE_BUSY, one line, saying that nothing was done;
8295
+ * `details.lock` is the file that names the holder. */
8296
+ function retireClaimRefusals(name, home, lock) {
8297
+ const refuse = (message, details) => Object.assign(oatsError("E_LIFECYCLE_BUSY", message), { details: { instance: name, home, ...details } });
8298
+ return {
8299
+ busy: (holder, unknown, at = lock) => {
8300
+ const details = { lock: at, pid: holder?.pid ?? null, since: holder?.at ?? null };
8301
+ return unknown
8302
+ ? refuse(`whether the retire of ${name} that holds ${at} (pid ${holder?.pid ?? "?"}, recorded start ${holder?.processStart ?? "none"}) still runs cannot be read (${unknown}); nothing was done — check that pid by hand, and if it is not an oats retire, remove ${at}, then retry`, { ...details, unknown })
8303
+ : refuse(`a retire of ${name} is already running (pid ${holder?.pid ?? "?"}, since ${holder?.at ?? "?"}); nothing was done — wait for it to finish`, details);
8304
+ },
8305
+ ownStartUnreadable: (reason, at) => refuse(`this process's start time cannot be read (${reason}), so oats retire cannot hold ${at} verifiably; nothing was done`, { lock: at }),
8306
+ unreadableClaim: (at) => refuse(`${at} is not a readable claim; inspect it and remove it if no oats retire holds it; nothing was done`, { lock: at }),
8307
+ };
8308
+ }
8309
+
8310
+ /** The homes `name` resolves to under `root`, and the one a retire acts on. Names are unique per
8311
+ * agent dir only: two agents can own an instance of the same name (dev --purpose foo-1 and agent
8312
+ * dev-foo). Retirement is destructive, so a name that resolves to several homes is refused unless
8313
+ * the caller says which home (--home), and a home is accepted only when it is one of that name's
8314
+ * homes under this root. */
8315
+ function resolveRetireHome(root, name, o) {
8081
8316
  const matches = findInstanceHomes(root, name);
8082
8317
  if (!matches.length) throw oatsError("E_SESSION_UNKNOWN", `no instance named "${name}"`);
8083
8318
  const sameHome = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
8084
- let found;
8085
8319
  if (o.home) {
8086
- found = matches.find((m) => sameHome(m.home, o.home));
8320
+ const found = matches.find((m) => sameHome(m.home, o.home));
8087
8321
  if (!found) throw oatsError("E_HOME_MISMATCH", `instance "${name}" has no home at ${o.home} under this agents root (its home${matches.length === 1 ? " is" : "s are"} ${matches.map((m) => m.home).join(", ")})`);
8088
- } else if (matches.length > 1) {
8322
+ return found;
8323
+ }
8324
+ if (matches.length > 1) {
8089
8325
  throw oatsError("E_AMBIGUOUS_INSTANCE", `"${name}" names ${matches.length} instances under this agents root (${matches.map((m) => `${m.agent.name}: ${m.home}`).join("; ")}); retire with --home <path> to say which`);
8090
- } else {
8091
- found = matches[0];
8092
8326
  }
8327
+ return matches[0];
8328
+ }
8329
+
8330
+ /** `name` has no home under `root`: remove a retire claim of that name whose holder is gone, in
8331
+ * each instances directory the lookup searches (a retire killed after it removed the home and
8332
+ * before it released). One whose holder is alive, unknown or unreadable is left as it is. `name`
8333
+ * is the caller's: no path is built from one outside the instance-name grammar. */
8334
+ function removeAbandonedRetireClaims(root, name) {
8335
+ if (typeof name !== "string" || !INSTANCE_NAME_RE.test(name)) return;
8336
+ const dirs = new Set([...listAgents(root).map((a) => a._dir), ...capabilityAgentDirs(root).map((c) => c.dir)]);
8337
+ for (const dir of dirs) {
8338
+ const home = join(dir, "instances", name);
8339
+ const lock = retireClaimPath(home);
8340
+ // Whatever stops the removal, the answer is the same: there is no such instance.
8341
+ try { removeGoneClaim(lock, { ...retireClaimRefusals(name, home, lock), waitMs: 0 }); } catch { /* left as it is */ }
8342
+ }
8343
+ }
8344
+
8345
+ /** A deferred self-retire is scheduled for `home` and its completion has not started: every other
8346
+ * retire of the home is refused while that completion lives. The pending marker
8347
+ * (scheduleDeferredSelfRetirement) names it. Nothing refuses when there is no marker, when the
8348
+ * completion left its outcome (it failed: this retire retries it), when the marker names no
8349
+ * completion (an older kernel wrote it), when this process is that completion, or when that
8350
+ * process is gone (it died: this retire does what it owed). */
8351
+ function refusePendingCompletion(name, home) {
8352
+ const marker = retirePendingMarkerPath(home);
8353
+ if (!existsSync(marker) || existsSync(deferredRetireResultPath(home))) return;
8354
+ const pending = readJsonOrUndefined(marker);
8355
+ const pid = pending?.completionPid;
8356
+ if (!Number.isSafeInteger(pid) || pid === process.pid) return;
8357
+ const live = processLiveness({ pid, processStart: pending.completionStart });
8358
+ if (live.state === "gone") return;
8359
+ const start = typeof pending.completionStart === "string" ? pending.completionStart : "none";
8360
+ const details = { instance: name, home, lock: marker, pid, since: pending.requestedAt ?? null };
8361
+ if (live.state === "alive") throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `a retire of ${name} is already scheduled (its completion, pid ${pid}, requested at ${pending.requestedAt ?? "?"}); nothing was done — wait for it to finish`), { details });
8362
+ throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `whether the completion of the scheduled retire of ${name} that ${marker} names (pid ${pid}, recorded start ${start}) still runs cannot be read (${live.reason}); nothing was done — check that pid by hand, and if it is not an oats retire, remove ${marker}, then retry`), { details: { ...details, unknown: live.reason } });
8363
+ }
8364
+
8365
+ /** Retire one instance. One retire of a home at a time (awebai/oats#863): the home's claim
8366
+ * (retireClaimPath; lib/claim.mjs) is taken as soon as the home is resolved, before anything the
8367
+ * retire acts on is read, and held until this returns or throws. Any other retire of that home
8368
+ * is refused at once (E_LIFECYCLE_BUSY) before it stops, copies or runs anything; `--force` does
8369
+ * not bypass it. A claim left by a killed retire is taken over. Every apply path runs this
8370
+ * function: the CLI, the deferred completion, and `--server` on the host. Synchronous. */
8371
+ export function retireInstance(root, name, o = {}) {
8372
+ if (o.deleteBranch) throw oatsError("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
8373
+ let found;
8374
+ try { found = resolveRetireHome(root, name, o); }
8375
+ catch (e) {
8376
+ if (e.code === "E_SESSION_UNKNOWN") removeAbandonedRetireClaims(root, name);
8377
+ throw e;
8378
+ }
8379
+ for (let restarts = 0; ; restarts++) {
8380
+ const lock = retireClaimPath(found.home);
8381
+ const refusals = retireClaimRefusals(name, found.home, lock);
8382
+ // The retirement root as retire makes it for its recovery copies; the claims are private.
8383
+ mkdirSync(instancesRetirementRoot(dirname(found.home)), { recursive: true });
8384
+ mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
8385
+ // No waiting: a live holder is refused at once. Only a deferred completion waits, for the
8386
+ // retire that scheduled it to return.
8387
+ const me = acquireClaim(lock, { ...refusals, waitMs: o[COMPLETES_DEFERRED] ? CLAIM_WAIT_MS : 0 });
8388
+ try {
8389
+ // Resolved again under the claim: another retire may have removed the home between the
8390
+ // first resolution and the claim. Gone is what a retire of a retired instance answers.
8391
+ const now = resolveRetireHome(root, name, o);
8392
+ if (retireClaimPath(now.home) !== lock) {
8393
+ // The name is another home's now, whose claim this does not hold: start over on that one.
8394
+ if (restarts >= RETIRE_CLAIM_RESTARTS) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `the home of ${name} changed while its claim was being taken (it is now ${now.home}); nothing was done — retry`), { details: { instance: name, home: now.home, lock: retireClaimPath(now.home) } });
8395
+ found = now;
8396
+ continue;
8397
+ }
8398
+ // Every retire that runs here, in this process: a `--self` that only schedules answers that
8399
+ // one is already scheduled (scheduleDeferredSelfRetirement).
8400
+ if (o.self !== true || o.keepDir) refusePendingCompletion(name, now.home);
8401
+ // What the caller confirms once nobody else can be retiring this home (a guarded apply reads
8402
+ // its plan and checks the revision): after the two answers above, before the retire reads
8403
+ // anything of the home. What it returns of the plan binds the retire.
8404
+ const confirmed = o[RETIRE_UNDER_CLAIM]?.();
8405
+ const bound = confirmed ? { ...o, ...(confirmed.children ? { children: confirmed.children } : {}), ...(confirmed.plannedExtraWorktrees ? { plannedExtraWorktrees: confirmed.plannedExtraWorktrees } : {}) } : o;
8406
+ return retireClaimed(root, name, bound, now);
8407
+ } finally {
8408
+ releaseClaim(lock, me);
8409
+ }
8410
+ }
8411
+ }
8412
+
8413
+ /** The retire of the home `found`, under its claim (retireInstance). */
8414
+ function retireClaimed(root, name, o, found) {
8415
+ const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
8416
+ // self-retire: the caller IS the instance. Without --keep-dir the whole
8417
+ // retirement is deferred to a detached external completion (below); with
8418
+ // --keep-dir the old in-process path runs and kills the window LAST.
8419
+ const self = o.self === true;
8093
8420
  const metaPath = join(found.home, "instance.json");
8094
8421
  // A QUARANTINED home (spawn failed after a required hook and compensation did
8095
8422
  // not finish) has no instance.json — it never got that far. Its marker carries
@@ -8287,15 +8614,14 @@ export function retireInstance(root, name, o = {}) {
8287
8614
  } catch (e) {
8288
8615
  const detail = String(e.stderr ?? e.message ?? "").trim();
8289
8616
  const unestablished = (why) => oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${why}`);
8290
- if (!/no server running|failed to connect|can't find session|no sessions/i.test(detail)) {
8291
- if (!tmuxServerLost(e)) throw unestablished(detail || "tmux inspection failed");
8292
- // A server that cannot be reached, typically because its socket file is missing (a reboot clears
8293
- // tmux's socket directory). A server outlives its socket file, so that alone does not say the
8294
- // window is gone: it is taken as gone only when no process works in the home, as for a home
8295
- // without its receipt.
8296
- const scan = processesInHome(found.home);
8297
- if (!scan.ok) throw unestablished(`${detail}; whether a process still works in this home could not be established (${scan.error})`);
8298
- if (scan.processes.length) throw unestablished(`${detail}; a process still works in this home (${scan.processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${scan.processes.length > 5 ? `, and ${scan.processes.length - 5} more` : ""})`);
8617
+ if (!/no server running|can't find session|no sessions/i.test(detail)) {
8618
+ const absence = tmuxServerAbsence(e);
8619
+ if (!absence) throw unestablished(detail || "tmux inspection failed");
8620
+ // A missing socket file, in any tmux's words (a reboot clears tmux's socket directory). A server
8621
+ // outlives its socket file, so that alone does not say the window is gone: it is taken as gone
8622
+ // only when no process works in the home, as for a home without its receipt (#624).
8623
+ const why = absence === "missing-socket" ? missingSocketUnestablished(detail, processesInHome(found.home)) : null;
8624
+ if (why) throw unestablished(why);
8299
8625
  }
8300
8626
  }
8301
8627
  sessionStopped = true;