@awebai/oats 0.48.0 → 0.50.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.
Files changed (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. package/skills/oats-getting-started/SKILL.md +1 -1
package/lib/core.mjs CHANGED
@@ -28,6 +28,7 @@
28
28
  * (attached as soul default is for service agents — spawn must supply workDir)
29
29
  */
30
30
  import { effectiveLaunchPromptPolicy } from "./launch-prompt-policy.mjs";
31
+ import { canonicalHomePath, realPathOrNearest } from "./real-path.mjs";
31
32
  import { createLaunchPromptController } from "./launch-prompts.mjs";
32
33
  import { retainLaunchPromptFrame } from "./launch-prompt-evidence.mjs";
33
34
  import { qualifyLaunchPromptFixtures } from "./launch-prompt-fixtures.mjs";
@@ -48,6 +49,7 @@ import { attachSessionTarget } from "./session-viewer.mjs";
48
49
  import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
49
50
  import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
50
51
  import { killGroup } from "./process-group.mjs";
52
+ import { interruptExitStatus, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
51
53
  import { captureLoginEnvironment } from "./login-environment.mjs";
52
54
 
53
55
  import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
@@ -61,21 +63,22 @@ async function materializePreparedDefault(prepared, home) { const m = await impo
61
63
  // (manifest, settings, origin, trust; no skills/inject since the copies are not
62
64
  // there yet) and REBUILT after materialize against what actually landed. Static
63
65
  // import: instance-resolution.mjs does not depend on core.mjs (no cycle).
64
- import { cloneRemoteFor, toCapabilityRows } from "./instance-resolution.mjs";
66
+ import { cloneRemoteFor, resolutionContractWarnings, toCapabilityRows, verifyMemberClone } from "./instance-resolution.mjs";
65
67
  import { GIT_FETCH_TIMEOUT_MS, GIT_TIMEOUT_MS, gitEnv } from "./remote.mjs";
66
68
  import { loadLocal } from "./workspace.mjs";
67
69
  import { parseConfigData } from "./config-data.mjs";
68
70
  import { renderInstructionText } from "./instruction-composition.mjs";
69
- import { APPROVED_HOOKS, PORTABLE_ENV_NAME_RE, CORE_LAUNCH_ENV, PROCESS_BOOTSTRAP_ENV, PROCESS_BOOTSTRAP_PREFIXES, manifestContractProblems, disposableHomeRootProblem, disposableHomeRootMatches } from "./capability-contract.mjs";
71
+ import { APPROVED_HOOKS, PORTABLE_ENV_NAME_RE, CORE_LAUNCH_ENV, PROCESS_BOOTSTRAP_ENV, PROCESS_BOOTSTRAP_PREFIXES, manifestContractProblems, disposableHomeRootProblem, disposableHomeRootMatches, contractWarningMessages, locatedContractWarnings } from "./capability-contract.mjs";
70
72
  import { validateBindingInterface } from "./provider-binding.mjs";
71
73
  /** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home),
72
74
  * the exact digest a copied path is compared with (exported so a test holds it to the copier),
75
+ * a worktree's byte digest and the Git directories it leaves out (exported so a test holds them to exact paths),
73
76
  * and the receipts the stored digest passes over in a home (exported so a test holds the manifest grammar to refusing each of them). */
74
- export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS };
77
+ export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS, storedTreeDigest, worktreeBytes, worktreeGitPaths };
75
78
 
76
79
  import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
77
80
  import { readPortableBytes } from "./bounded-read.mjs";
78
- import { copyTreeSafe } from "./tree-copy.mjs";
81
+ import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes } from "./tree-copy.mjs";
79
82
  import { assertSameWorktreeHead, gitRead, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
80
83
  /** The package and capability id grammar (namespaced, lowercase): an id names a
81
84
  * directory (a home's module copy), so no path spelling fits it. */
@@ -123,6 +126,11 @@ export function legacyLocalAgents(root) {
123
126
  return { code: "legacy-local-agents", dirs, instances,
124
127
  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(", ")})` : ""}` };
125
128
  }
129
+ /** The instances directories under the agents root `root`: `<root>/<agent>/instances`, one per
130
+ * agent directory, whether or not it exists. */
131
+ export function instancesDirs(root) {
132
+ return subdirs(root).map((agent) => join(root, agent, "instances"));
133
+ }
126
134
  /** The instance homes under the agents root `root` (a directory <root>/<agent>/instances/<name>
127
135
  * whose instance.json records that name) that other users on the machine can read or enter (any
128
136
  * group or other permission bit): one `home-readable` problem naming them, with the exact chmod,
@@ -186,6 +194,11 @@ export const PACKAGED_SKILLS_DIR = join(PKG_ROOT, "skills");
186
194
  // ---------- shell helpers ----------
187
195
  function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
188
196
  function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
197
+ /** The branch spawn records for an attached or checkout instance (#641): the
198
+ * name HEAD carries as headName reads it, or null when HEAD is detached or
199
+ * names a ref OATS carries no branch name for. Never the word "HEAD". A HEAD
200
+ * that cannot be read (not a Git tree) records none, as before. */
201
+ function recordedHeadBranch(dir) { try { return headName(dir).branch; } catch { return undefined; } }
189
202
  /** A native PROBE (a harness binary asked about its catalogue or packages) under
190
203
  * a preview: bounded by what is left of the shared preflight budget, run in its
191
204
  * own process group and group-killed on timeout. Cheap lookups (`command -v`)
@@ -415,18 +428,6 @@ export function findRoot(cwd = process.cwd()) {
415
428
  d = parent;
416
429
  }
417
430
  }
418
- /** realpath of `p`, or — when `p` does not exist yet — the realpath of its
419
- * nearest existing ancestor with the remaining segments re-appended. Any path
420
- * decision about WHERE something will be created has to go through this: a
421
- * lexical path says nothing about the destination once a symlink sits anywhere
422
- * along it. */
423
- function realPathOrNearest(p) {
424
- try { return realpathSync(p); } catch { /* not created yet — resolve what exists */ }
425
- let d = resolve(p); const tail = [];
426
- while (!existsSync(d) && dirname(d) !== d) { tail.unshift(basename(d)); d = dirname(d); }
427
- try { return join(realpathSync(d), ...tail); } catch { return resolve(p); }
428
- }
429
-
430
431
  /** Is there a Git marker (`.git` dir or worktree pointer file) at or above `dir`?
431
432
  * Filesystem-only: it answers "does Git own this location" even when the git
432
433
  * binary is missing, refuses the repo (dubious ownership), or cannot read its
@@ -489,10 +490,12 @@ export function canonicalDeploymentPath(p) {
489
490
  // Git reports CANONICAL paths, so every comparison and every relative()
490
491
  // below must be realpath-based: on macOS a temp/agents root reached through
491
492
  // /var while Git reports /private/var would otherwise look "outside" the
492
- // work tree and silently skip canonicalization. The agents dir itself may
493
- // not exist yet (local-only scopes), so resolve the nearest existing
493
+ // work tree and silently skip canonicalization. So would a root given in
494
+ // another letter case on a case-insensitive filesystem: Git's paths are in
495
+ // their on-disk spelling, and so are both sides here. The agents dir itself
496
+ // may not exist yet (local-only scopes), so resolve the nearest existing
494
497
  // ancestor and re-append the remainder.
495
- const realOf = realPathOrNearest;
498
+ const realOf = canonicalHomePath;
496
499
  const same = (a, b) => realOf(a) === realOf(b);
497
500
  // Linked or main? `--git-dir` equals `--git-common-dir` in the MAIN worktree
498
501
  // and points at <common>/worktrees/<name> in a linked one. This settles it
@@ -582,7 +585,11 @@ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
582
585
  * its reference aliases: a configuration may not name them. */
583
586
  export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_SETTINGS_ORIGINS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT",
584
587
  // The test seam that replaces the login shell (lib/login-environment.mjs): never a launch's to set.
585
- "OATS_TEST_LOGIN_SHELL"]);
588
+ "OATS_TEST_LOGIN_SHELL",
589
+ // The test seams of #796, the same: a worktree hook's fixed timeout, the fetch timeout of
590
+ // `oats worktree add` (lib/worktree-hooks.mjs, lib/worktree.mjs), and the `ps` path of a
591
+ // process's start time on a host with procfs (lib/worktree-hooks.mjs processStart).
592
+ "OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS"]);
586
593
  export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
587
594
  const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
588
595
  export function validateLaunchConfig(name, entry, where) {
@@ -725,6 +732,14 @@ function manifestHookCommands(manifest) {
725
732
 
726
733
  const PACKAGED_INJECTS_DIR = join(PKG_ROOT, "injects");
727
734
 
735
+ /** A replayed spawn's contract warnings (contractWarningMessages), from the home's module copies in
736
+ * module-name order; none when they cannot be read (the replay answers what it can, as before). */
737
+ function replayedContractWarnings(home) {
738
+ let manifests;
739
+ try { manifests = typeof home === "string" ? capabilityManifests(home) : {}; } catch { return []; }
740
+ return contractWarningMessages(Object.keys(manifests).sort().flatMap((name) => locatedContractWarnings(manifests[name], `.oats/modules/${name}/oats.json`)));
741
+ }
742
+
728
743
  function validateCapabilityManifest(m, mf) {
729
744
  const id = m.capability;
730
745
  if (!id) throw new Error(`capability manifest needs "capability": ${mf}`);
@@ -1072,7 +1087,7 @@ function plannedCapabilityRows(resolution) {
1072
1087
  * `node <abs script> <args>`, exactly as `manifestHookCommands` renders a classic
1073
1088
  * capability. The script must exist inside the module's copy under
1074
1089
  * <home>/.oats/modules/<cap>/ — a path escaping it is a manifest defect. Only
1075
- * the events the kernel approves (soul-scaffold, spawn, retire, launch) are kept. */
1090
+ * the events the kernel approves (soul-scaffold, spawn, retire, launch, worktree) are kept. */
1076
1091
  function materializedHookCommands(row, home) {
1077
1092
  const out = {};
1078
1093
  const moduleDir = row.dir || join(home, ".oats", "modules", row.id);
@@ -1389,7 +1404,8 @@ export const HARNESS_PACKAGE_MANAGERS = {
1389
1404
  let rows;
1390
1405
  try { rows = JSON.parse(out); } catch { return []; }
1391
1406
  if (!Array.isArray(rows)) return [];
1392
- const target = opts.context ? realPathOrNearest(opts.context) : undefined;
1407
+ // Claude reports projectPath in its on-disk spelling: the context is compared in it too.
1408
+ const target = opts.context ? canonicalHomePath(opts.context) : undefined;
1393
1409
  return rows
1394
1410
  .filter((r) => r && typeof r.id === "string")
1395
1411
  // A user-scope install applies everywhere. A project/local install
@@ -1397,7 +1413,7 @@ export const HARNESS_PACKAGE_MANAGERS = {
1397
1413
  .filter((r) => {
1398
1414
  if (r.scope === "user") return true;
1399
1415
  if (!r.projectPath || !target) return false;
1400
- const owner = realPathOrNearest(r.projectPath);
1416
+ const owner = canonicalHomePath(r.projectPath);
1401
1417
  return target === owner || target.startsWith(owner + sep);
1402
1418
  })
1403
1419
  // verifiedPresent is the "this harness confirms presence without naming a
@@ -1629,6 +1645,39 @@ function withoutAmbientLaunchPreview(env) {
1629
1645
  const { OATS_LAUNCH_PREVIEW: _ambient, ...rest } = env;
1630
1646
  return rest;
1631
1647
  }
1648
+ /** The environment one capability's lifecycle hook runs with: the invoker's own
1649
+ * (inherited, as for every hook; the kernel adds no credentials), plus the
1650
+ * standard OATS_* variables (docs/capabilities.md, Commands and hooks) and the
1651
+ * caller's `extraEnv`. One builder for every event, so the `worktree` runner
1652
+ * (lib/worktree-hooks.mjs) hands its hooks exactly what every other hook gets. */
1653
+ export function lifecycleHookEnv(event, cap, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
1654
+ return {
1655
+ // OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
1656
+ // inherited: a real start's hook must not read an ambient one as a preview.
1657
+ ...withoutAmbientLaunchPreview(process.env),
1658
+ // OATS_INSTANCE_HOME is the runtime-neutral contract name for the
1659
+ // instance home (absolute). OATS_HOME predates it and stays as a
1660
+ // compatibility alias: shipped capability hooks read it
1661
+ // (the official oats.aweb and oats.okf packages) and are versioned
1662
+ // independently of this kernel. Neither is OATS_HOME_DIR, which is
1663
+ // the package STORE root — do not conflate them.
1664
+ OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
1665
+ OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
1666
+ OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
1667
+ ...teamEnv(resolved),
1668
+ ...extraEnv,
1669
+ // Hooks also run through direct core callers (not only bin/oats).
1670
+ // Author this from the running kernel, never PATH, ambient env or
1671
+ // a caller's extraEnv: those may point at a different executable.
1672
+ OATS_CLI_BIN: kernelBin(),
1673
+ OATS_SETTINGS: JSON.stringify(cap.settings || {}),
1674
+ // Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
1675
+ // manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
1676
+ // soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
1677
+ OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
1678
+ OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
1679
+ };
1680
+ }
1632
1681
  export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
1633
1682
  const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [], volatileEnv: {} };
1634
1683
  // OATS_SOUL is set for EVERY hook: a caller that does not name the soul (launch,
@@ -1650,32 +1699,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
1650
1699
  try {
1651
1700
  const stdout = execSync(cmd, {
1652
1701
  cwd: home, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000,
1653
- env: {
1654
- // OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
1655
- // inherited: a real start's hook must not read an ambient one as a preview.
1656
- ...withoutAmbientLaunchPreview(process.env),
1657
- // OATS_INSTANCE_HOME is the runtime-neutral contract name for the
1658
- // instance home (absolute). OATS_HOME predates it and stays as a
1659
- // compatibility alias: shipped capability hooks read it
1660
- // (the official oats.aweb and oats.okf packages) and are versioned
1661
- // independently of this kernel. Neither is OATS_HOME_DIR, which is
1662
- // the package STORE root — do not conflate them.
1663
- OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
1664
- OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
1665
- OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
1666
- ...teamEnv(resolved),
1667
- ...extraEnv,
1668
- // Hooks also run through direct core callers (not only bin/oats).
1669
- // Author this from the running kernel, never PATH, ambient env or
1670
- // a caller's extraEnv: those may point at a different executable.
1671
- OATS_CLI_BIN: kernelBin(),
1672
- OATS_SETTINGS: JSON.stringify(cap.settings || {}),
1673
- // Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
1674
- // manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
1675
- // soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
1676
- OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
1677
- OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
1678
- },
1702
+ env: lifecycleHookEnv(event, cap, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta, extraEnv }),
1679
1703
  }).trim();
1680
1704
  const lastLine = stdout.split("\n").filter(Boolean).pop() || "{}";
1681
1705
  let o = {};
@@ -1947,12 +1971,22 @@ export function explicitInstanceName(name) {
1947
1971
  return name;
1948
1972
  }
1949
1973
 
1950
- function tmuxAlive(session) { return !!shTry(`tmux has-session -t ${shq(session)} 2>/dev/null && echo yes`); }
1951
1974
  /** The window names of `session` on the user's DEFAULT tmux server: only for a home that records no
1952
1975
  * socket (listInstances). OATS creates nothing there: new sessions live on the OATS server below. */
1953
- export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
1954
- if (!tmuxAlive(session)) return [];
1955
- return (shTry(`tmux list-windows -t ${shq(session)} -F '#{window_name}'`) || "").split("\n").filter(Boolean);
1976
+ export function tmuxWindows(session = DEFAULT_TMUX_SESSION) { return defaultTmuxWindows(session).windows; }
1977
+ /** tmuxWindows' read, keeping a missing socket file apart (#624): `{ windows }`, with `missingSocket`
1978
+ * (tmux's words) when the default server's socket file is missing. Any other failure reads as no
1979
+ * session. `has-session` first, as ever: it is the read-only probe a caller may expect for a home
1980
+ * that records no socket, and it words a missing socket file as list-windows does. */
1981
+ function defaultTmuxWindows(session) {
1982
+ const run = (args) => execFileSync("tmux", args, { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
1983
+ try {
1984
+ run(["has-session", "-t", session]);
1985
+ return { windows: run(["list-windows", "-t", session, "-F", "#{window_name}"]).split("\n").filter(Boolean) };
1986
+ } catch (e) {
1987
+ // Either read: the socket file can go between the two.
1988
+ return tmuxServerAbsence(e) === "missing-socket" ? { windows: [], missingSocket: tmuxFailure(e, "tmux failed") } : { windows: [] };
1989
+ }
1956
1990
  }
1957
1991
 
1958
1992
  // ---------- the OATS tmux server ----------
@@ -1984,8 +2018,11 @@ const exitedByItself = (e) => Number.isInteger(e?.status) && e.signal == null &&
1984
2018
  /** What the OATS server holds, as `list-sessions` answers: whether it runs, its socket (any session
1985
2019
  * names it), and whether a session named exactly `session` is there. No server and no such session
1986
2020
  * are the only answers that mean absent, and "no server" is read only from a call that exited by
1987
- * itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence. */
1988
- function oatsTmuxSessionSocket(session, io) {
2021
+ * itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence.
2022
+ * A missing socket file is absence only when `missingSocket(detail)` (a session start's check of its
2023
+ * home, missingSocketUnestablished) answers null; its reason refuses the start (#624). Without it, as
2024
+ * today. */
2025
+ function oatsTmuxSessionSocket(session, io, missingSocket) {
1989
2026
  let listed;
1990
2027
  try { listed = tmuxOatsServer(["list-sessions", "-F", "#{session_name}\t#{socket_path}"], io); }
1991
2028
  catch (e) {
@@ -1993,7 +2030,10 @@ function oatsTmuxSessionSocket(session, io) {
1993
2030
  // A tmux that could not be run at all is the one failure a person can act on: say so.
1994
2031
  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`);
1995
2032
  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"})`);
1996
- if (tmuxServerLost(e)) return { server: null, present: false };
2033
+ const absence = tmuxServerAbsence(e);
2034
+ const why = absence === "missing-socket" && missingSocket ? missingSocket(tmuxFailure(e, "tmux list-sessions failed")) : null;
2035
+ if (why) throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether the OATS tmux server for session ${session} is running, so nothing was started: ${why}`);
2036
+ if (absence) return { server: null, present: false };
1997
2037
  throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: ${tmuxFailure(e, "tmux list-sessions failed")}`);
1998
2038
  }
1999
2039
  let server = null, present = false;
@@ -2021,7 +2061,9 @@ const KERNEL_ENV_NAMES = new Set([...RESERVED_LAUNCH_ENV, "COLORFGBG", "TMUX", "
2021
2061
  "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK", "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME",
2022
2062
  "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT", "OATS_TRIGGER_EVENT_FILE",
2023
2063
  "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_TEAMS", "OATS_TEAMS_SOURCE",
2024
- "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_WORKSPACE_NAME", "OATS_WORKSPACE_KEY"]);
2064
+ "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_WORKSPACE_NAME", "OATS_WORKSPACE_KEY",
2065
+ // A worktree hook's tree (#796): never inherited by what such a hook starts.
2066
+ "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN"]);
2025
2067
  function withoutKernelEnvironment(source) {
2026
2068
  const env = { ...source };
2027
2069
  for (const name of Object.keys(env)) {
@@ -2259,10 +2301,10 @@ function oatsWindowEnvironment() {
2259
2301
  * again there when that server has gone. undefined when this process has no tmux to run: the
2260
2302
  * caller's backend check refuses that.
2261
2303
  */
2262
- function planOatsTmuxSession(session, io, { preview = false } = {}) {
2304
+ function planOatsTmuxSession(session, io, { preview = false, missingSocket } = {}) {
2263
2305
  if (!io?.exec && !which("tmux")) return undefined;
2264
2306
  let server, present;
2265
- try { ({ server, present } = oatsTmuxSessionSocket(session, io)); }
2307
+ try { ({ server, present } = oatsTmuxSessionSocket(session, io, missingSocket)); }
2266
2308
  catch (e) { if (preview) return undefined; throw e; } // a preview reports, it does not refuse on a read
2267
2309
  if (present || preview) return { server, present };
2268
2310
  return { server, present, env: oatsSessionEnvironment(session, io, { startsServer: !server }), startsServer: !server };
@@ -2338,10 +2380,12 @@ function launchLookup(configEnv, env, pane, configName, cwd) {
2338
2380
  * second lookup. tmux starts a server once: the first successful creator determines its initial
2339
2381
  * environment, and nothing here changes a running server's. E_RUNTIME_ENDPOINT_UNKNOWN when the
2340
2382
  * server cannot be read or names no socket, when this caller may not create the session, or when
2341
- * its own PATH names no tmux to create it with (creatorTmux).
2383
+ * its own PATH names no tmux to create it with (creatorTmux). `missingSocket` is a session start's
2384
+ * check of its home when the server's socket file is missing (oatsTmuxSessionSocket): with a reason,
2385
+ * E_SESSION_UNKNOWN and no server is created at that path.
2342
2386
  */
2343
- export function ensureOatsTmuxSession(session, hq, io, plan) {
2344
- let { server: socket, present } = oatsTmuxSessionSocket(session, io);
2387
+ export function ensureOatsTmuxSession(session, hq, io, plan, missingSocket) {
2388
+ let { server: socket, present } = oatsTmuxSessionSocket(session, io, missingSocket);
2345
2389
  if (!present) {
2346
2390
  // The executable is chosen here, where the creation is about to run, and nowhere earlier: a
2347
2391
  // session that exists needs none, so nothing is refused for it.
@@ -2354,7 +2398,7 @@ export function ensureOatsTmuxSession(session, hq, io, plan) {
2354
2398
  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(); }
2355
2399
  catch (e) {
2356
2400
  if (oatsCoded(e)) throw e;
2357
- const again = oatsTmuxSessionSocket(session, io);
2401
+ const again = oatsTmuxSessionSocket(session, io, missingSocket);
2358
2402
  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")}`);
2359
2403
  socket = again.server;
2360
2404
  }
@@ -2924,7 +2968,8 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
2924
2968
  if (harness === "claude") {
2925
2969
  cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- ${shq(TASK_PROMPT.claude)}`;
2926
2970
  } else if (harness === "codex") {
2927
- const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
2971
+ // Codex compares the key with its own working directory, in its on-disk spelling.
2972
+ const codexTrust = `projects={${JSON.stringify(canonicalHomePath(home))}={trust_level="trusted"}}`;
2928
2973
  // Codex may run tool commands outside the session's process (its shared app-server daemon),
2929
2974
  // so the env the prefix below gives the session is also set for them. A reference's value
2930
2975
  // never goes on argv, and PATH is the execution's (CODEX_TOOL_PATH: the shim first).
@@ -3275,7 +3320,9 @@ function* spawnBody(root, agent, o = {}) {
3275
3320
  // happened (crash in the interval). Say which, never replay a half-spawn.
3276
3321
  if (["blocked", "incomplete"].includes(prior.launchPrompts?.status)) throw retainedPromptError(prior.home, prior.instance, prior.launchPromptTarget ?? prior.tmux, prior.parentLineageCommitted === true, prior.launchPrompts);
3277
3322
  if (prior.spawnCompleted !== true) throw unconfirmedSpawn(Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false }));
3278
- return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null } };
3323
+ // The receipt's warnings that are facts of the composition (a hook event this kernel ignores),
3324
+ // from the home's module copies: nothing runs again, and the captured composition is unchanged.
3325
+ return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null }, warnings: replayedContractWarnings(prior.home) };
3279
3326
  }
3280
3327
  }
3281
3328
 
@@ -3669,18 +3716,22 @@ function* spawnBody(root, agent, o = {}) {
3669
3716
  // Addendum 5: where each leaf of `settings.<cap>` came from (JSON pointer → { kind, at }):
3670
3717
  // manifest-default | workspace | soul | host | spawn, the last layer that set it.
3671
3718
  const preparedSettingsOrigins = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloadOrigins?.[m.name] ?? {})]));
3719
+ // The preview's warnings are strings: the launch-prompt notice, then what a module declares and this kernel ignores.
3720
+ const previewWarnings = [...(promptOptedIn(launchPromptAnswers) ? [LAUNCH_PROMPT_UPDATE_WARNING] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution))];
3672
3721
  const preparedSettings = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})]));
3673
3722
  return deliver({
3674
3723
  // Team model v2: the soul's teams here (unmapped rows included) and its default — the choice a
3675
3724
  // Desktop offers before anything is minted; joining any but the default is the provider's explicit act.
3676
3725
  ...{ modules: o.prepared.preview ?? null, teams: structuredClone(o.prepared.resolution.teams ?? []), defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null), resolution: o.prepared.resolution.revision, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true, providers: preparedProviders, settings: preparedSettings, settingsOrigins: preparedSettingsOrigins },
3677
- spawnPreviewApi: 2, preview: true, launchPromptAnswers, ...(promptOptedIn(launchPromptAnswers) ? { warnings: [LAUNCH_PROMPT_UPDATE_WARNING] } : {}), agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
3726
+ spawnPreviewApi: 2, preview: true, launchPromptAnswers, ...(previewWarnings.length ? { warnings: previewWarnings } : {}), agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
3678
3727
  subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
3679
3728
  decision, preflight,
3680
3729
  backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
3681
3730
  harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, launchConfigDefault: launchConfig?.harnessDefault === true, yolo, backend,
3682
3731
  launch: launchReport({ declared: launchChoice.declared, harness, model, launchConfig: launchConfig?.name, from: launchChoice.from, at: launchChoice.at }),
3683
3732
  branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
3733
+ // #796: the `worktree` hooks a worktree-mode spawn would fire, in the order they run; null in other modes.
3734
+ worktreeHooks: work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities).map((h) => ({ capability: h.id, required: h.required })) : null,
3684
3735
  relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
3685
3736
  policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities,
3686
3737
  skills: [...expectedResources.filter((r) => r.type === "skill-tree" && !r.deferred).flatMap((r) => r.entries || []), ...preparedSkills], task: task || null,
@@ -3977,7 +4028,7 @@ function* spawnBody(root, agent, o = {}) {
3977
4028
  // The tree belongs to its owner — retire never removes it (work/ is a symlink).
3978
4029
  if (!o.workDir || !existsSync(o.workDir)) { rmSync(home, { recursive: true, force: true }); throw new Error(`attached mode needs workDir (got: ${o.workDir})`); }
3979
4030
  symlinkSync(resolve(o.workDir), join(home, "work"));
3980
- branch = shTry(`git -C ${shq(o.workDir)} rev-parse --abbrev-ref HEAD`);
4031
+ branch = recordedHeadBranch(o.workDir);
3981
4032
  } else if (work === "workspace") {
3982
4033
  // Cross-repo coordinator: ./work is the deployment boundary (the directory
3983
4034
  // holding oats-local.yaml, prepared.deployment), not a repo — member repos are
@@ -3991,10 +4042,11 @@ function* spawnBody(root, agent, o = {}) {
3991
4042
  branch = undefined; // no repo identity: the workspace is not a git tree
3992
4043
  } else {
3993
4044
  symlinkSync(repoAbs, join(home, "work"));
3994
- branch = shTry(`git -C ${shq(repoAbs)} rev-parse --abbrev-ref HEAD`);
4045
+ branch = recordedHeadBranch(repoAbs);
3995
4046
  }
3996
4047
 
3997
- const warnings = promptOptedIn(launchPromptAnswers) ? [LAUNCH_PROMPT_UPDATE_WARNING] : [];
4048
+ // What the composed modules declare and this kernel ignores (an unknown hook event), as the preview said.
4049
+ const warnings = [...(promptOptedIn(launchPromptAnswers) ? [LAUNCH_PROMPT_UPDATE_WARNING] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared?.resolution))];
3998
4050
 
3999
4051
  // Establish directory ownership while these are still the kernel's own roots.
4000
4052
  // A hook may replace either path; it must never mint authority for that target.
@@ -4049,6 +4101,32 @@ function* spawnBody(root, agent, o = {}) {
4049
4101
  throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message})`);
4050
4102
  }
4051
4103
  };
4104
+ // #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
4105
+ // in-progress marker that covers a parent killed while they run.
4106
+ const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];
4107
+ let worktreeRun = null, treeGuard = null, inProgressMarker = false;
4108
+ const writeSpawnInProgressMarker = (hook) => {
4109
+ const retireOwed = new Set((hookRes.order || []).filter((id) => resolvedCfg.capabilities.find((c) => c.id === id)?.hooks?.retire));
4110
+ writeQuarantineMarker(home, buildQuarantineMarker({
4111
+ instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId,
4112
+ incomplete: ["the spawn is running its worktree hooks; until its process is gone this home is a spawn in progress"],
4113
+ failed: [{ capability: "oats.kernel", event: "worktree" }],
4114
+ outstandingHooks: retireOwed, outstandingGit: new Set(branch ? ["worktree", "branch"] : ["worktree"]),
4115
+ repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {}, launched: false, tmux: { session, window: instance },
4116
+ reason: "spawn interrupted while its worktree hooks ran",
4117
+ }), { inProgress: { ...selfIdentity(), startedAt: inProgressStartedAt, branch, baseOid: plannedBase.oid, ...hook } });
4118
+ if (!inProgressMarker) {
4119
+ inProgressMarker = true;
4120
+ writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: { session, window: instance } });
4121
+ }
4122
+ };
4123
+ const inProgressStartedAt = new Date().toISOString();
4124
+ // The spawn's commit point for the marker: the final instance.json and baseline are written.
4125
+ const clearSpawnInProgressMarker = () => {
4126
+ if (!inProgressMarker) return;
4127
+ rmSync(join(home, ".oats-rollback-incomplete.json"), { force: true });
4128
+ inProgressMarker = false;
4129
+ };
4052
4130
  let promptDispatched = false, promptTarget, promptResult, promptStartId;
4053
4131
  let windowMayExist = false;
4054
4132
  let spawnTmux;
@@ -4203,8 +4281,58 @@ function* spawnBody(root, agent, o = {}) {
4203
4281
  if (requiredFailures.length) {
4204
4282
  const detail = requiredFailures.map((f) => ` ${f.capability} ${f.event} ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
4205
4283
  const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
4206
- throw oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration`);
4284
+ // The spawn hooks that ran, in the worktree receipt's shape. A spawn hook keeps no log (`log: null`),
4285
+ // and nothing of its output is carried here.
4286
+ const hooks = (hookRes.order || []).map((id) => {
4287
+ const f = (hookRes.failures || []).find((x) => x.capability === id);
4288
+ const cap = resolvedCfg.capabilities.find((c) => c.id === id);
4289
+ return { capability: id, ok: !f, required: (cap?.requiredHooks || []).includes("spawn") || f?.contract === "environment", log: null, ...(f?.contract ? { contract: f.contract } : {}) };
4290
+ });
4291
+ throw Object.assign(oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration`), { details: { hooks } });
4207
4292
  }
4293
+ // #796: the `worktree` event, once, for the ./work this spawn created, after the spawn hooks
4294
+ // succeeded and inside this transaction (lib/worktree-hooks.mjs says how it runs). A killed
4295
+ // parent is recovered by `oats retire` from the in-progress marker written before the first hook.
4296
+ if (treeHooks.length) {
4297
+ const tree = worktreeCanonical || realpathSync(join(home, "work"));
4298
+ const cloneReal = realPathOrNearest(repoAbs);
4299
+ // The marker names this process by pid and start; one whose start cannot be read could not be told
4300
+ // apart from a dead one after a kill, so the spawn does not run its worktree hooks without it.
4301
+ if (!processStartToken(process.pid)) throw oatsError("E_SPAWN_FAILED", `this process's start time cannot be read, so a spawn killed while its worktree hooks ran could not be recovered safely; no worktree hook ran`);
4302
+ writeSpawnInProgressMarker({});
4303
+ treeGuard = signalGuard();
4304
+ const treeEnv = {
4305
+ OATS_TREE: tree, OATS_TREE_CLONE: cloneReal, OATS_TREE_REMOTE: originRemoteOf(cloneReal),
4306
+ OATS_TREE_MEMBER: o.prepared?.soulEntry?.repoKey && cloneOfMember(cloneReal, o.prepared.soulEntry.repoKey) ? o.prepared.soulEntry.repoKey : "",
4307
+ OATS_BRANCH: branch, OATS_TREE_BASE: plannedBase.ref, OATS_TREE_BASE_OID: plannedBase.oid, OATS_PURPOSE: "", OATS_TREE_ORIGIN: "spawn",
4308
+ };
4309
+ worktreeRun = yield () => runWorktreeHooks(treeHooks, {
4310
+ envFor: (cap) => lifecycleHookEnv("worktree", cap, { home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs, workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg, priorMeta: hookRes.meta || {}, extraEnv: treeEnv }),
4311
+ cwd: tree, home, purpose: "", guard: treeGuard,
4312
+ onStart: ({ pgid, hookStart }) => writeSpawnInProgressMarker({ hookPgid: pgid, hookStart }),
4313
+ });
4314
+ warnings.push(...worktreeRun.warnings);
4315
+ if (worktreeRun.interrupted) {
4316
+ throw Object.assign(oatsError("E_INTERRUPTED", `the spawn was interrupted by ${worktreeRun.interrupted} while its worktree hooks ran; the running hook's process group was ended`),
4317
+ { exitStatus: interruptExitStatus(worktreeRun.interrupted), details: { signal: worktreeRun.interrupted, hooks: worktreeRun.receipt } });
4318
+ }
4319
+ // A hook may itself remove or move the tree: the tree must still be this worktree.
4320
+ if (!treeStillThere(tree)) {
4321
+ const msg = `the tree ${tree} is no longer there (or no longer this worktree) after the worktree hooks ran`;
4322
+ if (treeHooks.some((h) => h.required)) worktreeRun.failures.push({ capability: "oats.kernel", event: "worktree", message: msg, required: true });
4323
+ else warnings.push(msg);
4324
+ }
4325
+ const logOf = (id) => worktreeRun.receipt.find((r) => r.capability === id)?.log;
4326
+ for (const f of worktreeRun.failures.filter((x) => !x.required)) warnings.push(`${f.capability} worktree hook failed (continuing): ${f.message}${logOf(f.capability) ? ` (log: ${logOf(f.capability)})` : ""}`);
4327
+ const treeFailures = worktreeRun.failures.filter((x) => x.required);
4328
+ if (treeFailures.length) {
4329
+ requiredFailures.push(...treeFailures);
4330
+ // The logs are in the home, which the rollback may remove: where they are is said after it (below).
4331
+ const detail = treeFailures.map((f) => ` ${f.capability} worktree ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
4332
+ throw Object.assign(oatsError(treeFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED", `a capability could not set up the new worktree:\n${detail}`), { details: { hooks: worktreeRun.receipt } });
4333
+ }
4334
+ }
4335
+ treeGuard?.restore();
4208
4336
  // Hooks have finished, but no TASK, launch recipe, successful scaffold, or
4209
4337
  // backend operation may be published until the owned roots are revalidated.
4210
4338
  if (work === "directory") assertDirectoryRoots(home, homeReal);
@@ -4216,15 +4344,18 @@ function* spawnBody(root, agent, o = {}) {
4216
4344
  }
4217
4345
  }
4218
4346
  const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
4347
+ // A checkout or attached tree may be on no branch OATS can name (#641): a detached HEAD. With a
4348
+ // branch the text is as it always was; only a missing one is said another way.
4349
+ const noBranch = "no branch that OATS can name, e.g. a detached HEAD";
4219
4350
  const workDesc = work === "worktree"
4220
4351
  ? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
4221
4352
  : work === "attached"
4222
- ? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
4353
+ ? `ATTACHED to another instance's work tree (${o.workDir}, ${branch ? `branch ${branch}` : noBranch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
4223
4354
  : work === "directory"
4224
4355
  ? `an instance-owned execution directory — not a Git worktree or a link to ${repoAbs}; that path supplies configuration only`
4225
4356
  : work === "workspace"
4226
4357
  ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
4227
- : `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
4358
+ : `a symlink to the ${repoAbs} checkout — you share it; ${branch ? `work on the currently checked-out branch (${branch})` : `work on what is checked out (${noBranch})`} and do not switch branches without being asked`;
4228
4359
  writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
4229
4360
 
4230
4361
  You are instance "${instance}" of agent "${agent.name}".
@@ -4269,7 +4400,9 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4269
4400
  relativeTo: relation ? relativeTo : undefined,
4270
4401
  spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
4271
4402
  policy: { childSpawns: ownChildPolicy },
4272
- ...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo, number: o.triggerEvent.number, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile } } : {}),
4403
+ ...(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,
4404
+ // A capability source's event carries its declared fields (a pull request's never does).
4405
+ ...(o.triggerEvent.fields && typeof o.triggerEvent.fields === "object" ? { fields: o.triggerEvent.fields } : {}) } } : {}),
4273
4406
  // K6c: a decision-bound spawn records what bound it, so a retry with the
4274
4407
  // same key replays this receipt instead of spawning again.
4275
4408
  // The FULL bound decision (placement + effective), exactly as the fence
@@ -4380,6 +4513,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4380
4513
  // the managed harness can write. No child-home transition follows launch.
4381
4514
  writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
4382
4515
  writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
4516
+ clearSpawnInProgressMarker();
4383
4517
  // Wrap the command so the window drops into an interactive shell when the
4384
4518
  // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
4385
4519
  const windowCmd = paneCommand(executionCommand);
@@ -4415,20 +4549,21 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4415
4549
  meta.launched = false;
4416
4550
  writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
4417
4551
  writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
4552
+ clearSpawnInProgressMarker();
4418
4553
  }
4419
4554
 
4420
4555
  // Ordinary launches and scaffolds commit here; opted-in launches already
4421
4556
  // committed before dispatch so retained prompt failures keep their lineage.
4422
4557
  commitParentLineage();
4423
4558
 
4424
- appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, harness, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes) } });
4559
+ appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, harness, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}) } });
4425
4560
  if (launch) appendEvent(home, { kind: "launched", data: { harness, backend, launchConfig: launchConfig?.name ?? null } });
4426
4561
  if (o.idempotencyKey !== undefined) {
4427
4562
  // Only now is the spawn a finished receipt a same-key retry may replay.
4428
4563
  meta.spawnCompleted = true;
4429
4564
  writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n"); // a kernel-owned field: the baseline fingerprint ignores it
4430
4565
  }
4431
- return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
4566
+ return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
4432
4567
  } catch (error) {
4433
4568
  if (promptDispatched) {
4434
4569
  // Once opted-in launch dispatch occurred, uncertainty retains all effects.
@@ -4465,6 +4600,20 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
4465
4600
  // An interrupted compensation pass cannot establish that effects ended.
4466
4601
  error.message += ` — rollback INCOMPLETE: cleanup could not be completed: ${cleanupError.message}`;
4467
4602
  unconfirmedSpawn(error);
4603
+ } finally {
4604
+ // Interrupts were held through the rollback of a spawn that ran worktree hooks (#796).
4605
+ treeGuard?.restore();
4606
+ }
4607
+ // #796: the worktree hooks' logs are in the home. A rollback that removed it removed them: no
4608
+ // answer names a path that is gone (each entry's `log` is null); a retained home keeps them.
4609
+ if (worktreeRun && error?.details?.hooks === worktreeRun.receipt) {
4610
+ if (existsSync(home)) {
4611
+ const logs = error.details.hooks.map((h) => h.log).filter(Boolean);
4612
+ if (logs.length) error.message += `; the worktree hooks' logs are kept in the retained home: ${logs.join(", ")}`;
4613
+ } else {
4614
+ error.details = { ...error.details, hooks: error.details.hooks.map((h) => ({ ...h, log: null })) };
4615
+ error.message += "; the worktree hooks' output was logged in the instance home, which the rollback removed: run the setup in an existing instance with `oats worktree add` to see it";
4616
+ }
4468
4617
  }
4469
4618
  throw error;
4470
4619
  }
@@ -4490,26 +4639,42 @@ export function servedIdentityLine(identity) {
4490
4639
  return `alias ${identity.alias || "?"} on ${identity.team || "?"}`;
4491
4640
  }
4492
4641
  /** The window names of `session` on the tmux server at `socket`: `{ windows }`, empty when the server
4493
- * or the session is gone; `{ error }` when the server could not be read. */
4642
+ * or the session is gone, with `missingSocket` (tmux's words) when the socket file is missing, which
4643
+ * alone does not say the server is gone (#624); `{ error }` when the server could not be read. */
4494
4644
  function recordedTmuxWindows(socket, session) {
4495
4645
  try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean) }; }
4496
4646
  catch (e) {
4497
- if (tmuxServerLost(e) || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
4647
+ const absence = tmuxServerAbsence(e);
4648
+ if (absence === "missing-socket") return { windows: [], missingSocket: tmuxFailure(e, "tmux list-windows failed") };
4649
+ if (absence || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
4498
4650
  return { error: String(e.stderr ?? e.message ?? "").trim() || "tmux list-windows failed" };
4499
4651
  }
4500
4652
  }
4501
- /** A status row's liveness from its session's windows: unknown (not false) when the server could not be read. */
4502
- function tmuxLiveness({ windows, error }, window) {
4503
- return error ? { running: null, runtimeState: "unreachable", runtimeError: error } : { running: windows.includes(window) };
4653
+ /** A status row's liveness from its session's windows: unknown (not false) when the server could not
4654
+ * be read, and, for a row whose server holds its endpoint (`endpoint`), when its socket file is
4655
+ * missing while a process works in the home or the scan (`scanHome()`, processesInHome's answer for
4656
+ * it) cannot tell (#624). */
4657
+ function tmuxLiveness({ windows, error, missingSocket }, window, scanHome, endpoint) {
4658
+ if (error) return { running: null, runtimeState: "unreachable", runtimeError: error };
4659
+ const running = windows.includes(window);
4660
+ const why = !running && missingSocket && endpoint ? missingSocketUnestablished(missingSocket, scanHome()) : null;
4661
+ return why ? { running: null, runtimeState: "unreachable", runtimeError: why } : { running };
4504
4662
  }
4505
- export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
4663
+ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
4506
4664
  // Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
4507
4665
  // socket, never the ambient $TMUX server, once per socket and session per call, so status costs no
4508
4666
  // more child processes as homes grow. A home without a recorded socket reads the default server.
4667
+ // A row whose socket file is missing is checked against one process scan of the host, made the
4668
+ // first time a row needs it and shared by every row (`io` reaches it: processesInHome).
4669
+ let hostScan;
4670
+ const scanOf = (home) => () => {
4671
+ hostScan ??= hostProcesses(io);
4672
+ return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
4673
+ };
4509
4674
  const tmuxByEndpoint = new Map();
4510
4675
  const windowsOf = (session, socket) => {
4511
4676
  const key = JSON.stringify([socket ?? null, session]);
4512
- if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : { windows: tmuxWindows(session) });
4677
+ if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : defaultTmuxWindows(session));
4513
4678
  return tmuxByEndpoint.get(key);
4514
4679
  };
4515
4680
  const readInstancesOf = (agentDir) => {
@@ -4529,10 +4694,17 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
4529
4694
  // is preserved state awaiting cleanup, and must read that way.
4530
4695
  const fallback = directoryRollbackPath(home);
4531
4696
  const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
4532
- let rollbackIncomplete;
4697
+ let rollbackIncomplete, spawnInProgress;
4533
4698
  if (existsSync(quarantine)) {
4534
4699
  try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
4535
4700
  catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
4701
+ // #796: a spawn still running its worktree hooks keeps a marker that names it
4702
+ // (`inProgress`). While that process is verifiably alive the home is a spawn in
4703
+ // progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
4704
+ // start cannot be read is not shown in progress either: on a host that never reads it, the
4705
+ // row would say "setting up" forever. It reads as the quarantine (its `inProgress` names
4706
+ // the pid), and retire, which never takes it for gone, refuses it with the way out.
4707
+ if (rollbackIncomplete?.inProgress && processLiveness(rollbackIncomplete.inProgress).state === "alive") { rollbackIncomplete = undefined; spawnInProgress = true; }
4536
4708
  }
4537
4709
  // A self-retire that has been requested but not completed: the home is
4538
4710
  // owed a retirement, not live work. Read-only here — completion is the
@@ -4544,9 +4716,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
4544
4716
  catch { retirePending = { reason: "retire pending" }; }
4545
4717
  }
4546
4718
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
4547
- const liveness = recordsHerdr(meta, readJsonOrUndefined(retirementBaselinePath(home)))
4719
+ const liveness = recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)))
4548
4720
  ? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
4549
- : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name);
4721
+ : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
4722
+ // A home that records no socket and no launch (--no-launch) reads the default server only
4723
+ // by default: that server's missing socket says nothing about it, and stays "not running".
4724
+ !!meta.tmux?.socket || meta.launched === true);
4550
4725
  const identity = servedIdentityOf(meta);
4551
4726
  // Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
4552
4727
  // else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
@@ -4574,7 +4749,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
4574
4749
  try { const s = instanceSessionTarget(home); if (!s.target || !harnessRunning(inspectSessionTarget(s.target))) waitingOnYou = null; }
4575
4750
  catch { waitingOnYou = null; }
4576
4751
  }
4577
- return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
4752
+ return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}) };
4578
4753
 
4579
4754
  });
4580
4755
  };
@@ -4738,12 +4913,12 @@ function directoryIdentity(path) {
4738
4913
  // lock creation or backend observation. A metadata mode edit cannot disable it.
4739
4914
  function sessionDirectoryGuard(home) {
4740
4915
  let baseline;
4741
- try { baseline = JSON.parse(readFileSync(retirementBaselinePath(home), "utf8")); }
4916
+ try { baseline = JSON.parse(readFileSync(findRetirementBaseline(home), "utf8")); }
4742
4917
  catch (e) { if (e.code === "ENOENT") return () => {}; throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", "independent session receipt is unreadable"); }
4743
4918
  const expected = join(realPathOrNearest(dirname(home)), basename(home));
4744
4919
  const check = () => {
4745
4920
  if (baseline.directoryWork === true) {
4746
- if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== expected) throw oatsError("E_WORK_INSPECTION_FAILED", "invalid independent directory home authority");
4921
+ if (baseline.version !== RETIRE_BASELINE_VERSION || !receiptRecordsHome(baseline, receiptHomeIdentity(home))) throw oatsError("E_WORK_INSPECTION_FAILED", "invalid independent directory home authority");
4747
4922
  assertDirectoryRoots(home, expected);
4748
4923
  for (const [name, path] of [["home", home], ["work", join(home, "work")]]) {
4749
4924
  const actual = directoryIdentity(path), recorded = baseline.directoryRoots?.[name];
@@ -4789,6 +4964,12 @@ function fetchObservedBase(repoAbs, { key, oid, remote }) {
4789
4964
  { details: { repo: repoAbs, repoKey: key, commit: oid, remote } });
4790
4965
  }
4791
4966
 
4967
+ /** Whether `clone` is a clone of the member `key`, read from its local remotes only (never the network):
4968
+ * OATS_TREE_MEMBER names a member only when this holds. */
4969
+ export function cloneOfMember(clone, key) {
4970
+ try { verifyMemberClone(clone, key); return true; } catch { return false; }
4971
+ }
4972
+
4792
4973
  /** A failed spawn's compare-and-delete of the branch it created at `oid`: `git update-ref -d` refuses
4793
4974
  * atomically if the tip moved (something was committed there), and the branch is then kept. `run`
4794
4975
  * answers { ok, out, status, err }. → what is still owed, as messages ([] when the branch is gone). */
@@ -4802,8 +4983,11 @@ function deleteBranchAsCreated(run, repoAbs, branch, oid) {
4802
4983
  }
4803
4984
  /** Retain the home and its cleanup receipt when spawn compensation or retirement
4804
4985
  * cannot finish. Keeping the original credentials makes cleanup retryable. */
4805
- function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason, directoryPreservation = false, orphanedWork = false, directoryHome = realPathOrNearest(home) }) {
4806
- const marker = {
4986
+ /** The quarantine marker (`.oats-rollback-incomplete.json`) a rollback that cannot finish leaves:
4987
+ * the cleanup descriptor a retry consumes (usableCleanupDescriptor). One builder for the
4988
+ * rollback below and for a spawn's in-progress marker (#796), which adds `inProgress`. */
4989
+ function buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, reason, directoryPreservation = false, orphanedWork = false }) {
4990
+ return {
4807
4991
  // `reason` is optional and DEFAULTS to the spawn wording, so every existing
4808
4992
  // caller is byte-identical; only a caller that supplies one differs. The
4809
4993
  // quarantine shape is now reached from two events and a fixed "spawn"
@@ -4833,12 +5017,20 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
4833
5017
  },
4834
5018
  createdAt: new Date().toISOString(),
4835
5019
  };
5020
+ }
5021
+ /** Write a quarantine marker by rename, so a marker that replaces another (a spawn's
5022
+ * compensation over its in-progress marker) never leaves two files or a moment with none.
5023
+ * `extra` adds top-level fields (`inProgress`). */
5024
+ function writeQuarantineMarker(home, marker, extra = {}, mode) {
5025
+ writeJsonAtomic(join(home, ".oats-rollback-incomplete.json"), { ...marker, ...extra }, mode);
5026
+ }
5027
+ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason, directoryPreservation = false, orphanedWork = false, directoryHome = realPathOrNearest(home) }) {
5028
+ const marker = buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, reason, directoryPreservation, orphanedWork });
4836
5029
  try {
4837
- const path = join(home, ".oats-rollback-incomplete.json");
4838
5030
  if (work === "directory") {
4839
5031
  assertDirectoryHome(home, directoryHome);
4840
- writeJsonAtomic(path, marker, 0o600);
4841
- } else writeFileSync(path, JSON.stringify(marker, null, 2) + "\n");
5032
+ writeQuarantineMarker(home, marker, {}, 0o600);
5033
+ } else writeQuarantineMarker(home, marker);
4842
5034
  } catch {
4843
5035
  if (work === "directory") {
4844
5036
  // Never write through a substituted home (even its metadata paths).
@@ -4918,21 +5110,87 @@ function usableCleanupDescriptor(marker) {
4918
5110
  return true;
4919
5111
  }
4920
5112
 
5113
+ // The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
5114
+ // also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
4921
5115
  const RETIRE_BASELINE_VERSION = 2;
5116
+ /** The version of the stored digests a spawn baseline is written with (fingerprintTrees,
5117
+ * generatedWorkDigest); a baseline without `digestVersion` holds the legacy ones, 1. */
5118
+ const BASELINE_DIGEST_VERSION = 2;
5119
+ /** The version of a baseline's stored digests (`homeFingerprint`, `generatedWorkFingerprint`):
5120
+ * 1 when it has no `digestVersion` (or there is no baseline), 2 when it says 2, and undefined for
5121
+ * any other value, which no digest this kernel takes matches. It is never inferred. */
5122
+ function baselineDigestVersion(baseline) {
5123
+ if (!baseline || !Object.hasOwn(baseline, "digestVersion")) return 1;
5124
+ return baseline.digestVersion === BASELINE_DIGEST_VERSION ? BASELINE_DIGEST_VERSION : undefined;
5125
+ }
4922
5126
 
4923
5127
  function retirementStateRoot(home) {
4924
5128
  // Independent of the bytes it authenticates, but colocated with the agent's
4925
5129
  // already instance-owned storage rather than the source repository or user
4926
5130
  // config home. Retiring <instances>/<name> never removes this sibling.
4927
- return join(dirname(home), ".oats-retirement");
5131
+ return instancesRetirementRoot(dirname(home));
5132
+ }
5133
+ /** The retirement state of the homes in the instances directory `instances`. */
5134
+ function instancesRetirementRoot(instances) {
5135
+ return join(instances, ".oats-retirement");
5136
+ }
5137
+ /** Where retire writes the recovery copies of the homes in the instances directory `instances`. */
5138
+ export function retirementRecoveryRoot(instances) {
5139
+ return join(instancesRetirementRoot(instances), "recovery");
5140
+ }
5141
+
5142
+ /** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
5143
+ * is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
5144
+ * exchanged for a symlink is not the home it points at). */
5145
+ function receiptHomeIdentity(home) {
5146
+ let st;
5147
+ try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
5148
+ return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
4928
5149
  }
4929
5150
 
4930
- function retirementKey(home) {
4931
- return createHash("sha256").update(join(realPathOrNearest(dirname(home)), basename(home))).digest("hex");
5151
+ /** Whether a receipt's recorded home is this home, whatever spelling either was written in.
5152
+ * `current` is the home as the caller resolves it for the comparison. */
5153
+ function receiptRecordsHome(baseline, current) {
5154
+ return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
4932
5155
  }
4933
5156
 
5157
+ function retirementBaselineFile(identity) {
5158
+ return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
5159
+ }
5160
+
5161
+ /** Where a spawn writes a home's receipt: keyed by its canonical identity. */
4934
5162
  function retirementBaselinePath(home) {
4935
- return join(retirementStateRoot(home), "baselines", `${retirementKey(home)}.json`);
5163
+ return retirementBaselineFile(receiptHomeIdentity(home));
5164
+ }
5165
+
5166
+ /** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
5167
+ * spelling, which on a case-insensitive filesystem need not be the on-disk one. */
5168
+ function legacyRetirementBaselinePath(home) {
5169
+ return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
5170
+ }
5171
+
5172
+ /** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
5173
+ * under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
5174
+ * legacy key is used where it is, never moved, copied or rewritten elsewhere.
5175
+ *
5176
+ * Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
5177
+ * spelling when that is S: a third spelling of such a home misses it (address the home as
5178
+ * `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
5179
+ * leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
5180
+ * home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
5181
+ * spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
5182
+ * spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
5183
+ * instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
5184
+ * endpoint, where session control already targets the right session. Retire finds the home
5185
+ * fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
5186
+ * directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
5187
+ * file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
5188
+ * incarnation's. */
5189
+ function findRetirementBaseline(home) {
5190
+ const canonical = retirementBaselinePath(home);
5191
+ if (existsSync(canonical)) return canonical;
5192
+ const legacy = legacyRetirementBaselinePath(home);
5193
+ return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
4936
5194
  }
4937
5195
 
4938
5196
  /** git's output for a large tree (status with untracked and ignored files,
@@ -4944,6 +5202,53 @@ function retirementBaselinePath(home) {
4944
5202
  * loudly, and streaming is deliberately not attempted in this change. */
4945
5203
  const GIT_MAX_BUFFER = 512 * 1024 * 1024;
4946
5204
 
5205
+ /** How the retire runs Git on the instance's work, its repository, a
5206
+ * repository under the work and a recovery clone (awebai/oats#662, #679):
5207
+ * argv only, no shell; optional locks off (`--no-optional-locks` and
5208
+ * GIT_OPTIONAL_LOCKS=0), so a status never refreshes, and so never rewrites,
5209
+ * the index it inspects; no helper that a repository's own configuration
5210
+ * names can run (fsmonitor, hooks, an external diff), nor any command a
5211
+ * fetch would run (GIT_NO_LAZY_FETCH=1: an object a promisor repository
5212
+ * lacks is a failed read, never fetched through a remote, helper, ssh
5213
+ * command or credential helper its configuration names; Git before 2.44
5214
+ * ignores the variable); and nothing of the caller's environment redirects
5215
+ * what is read. Git's own list of
5216
+ * repository-local variables (`git rev-parse --local-env-vars`: GIT_DIR,
5217
+ * GIT_WORK_TREE, GIT_INDEX_FILE, GIT_COMMON_DIR, the object directories,
5218
+ * GIT_CONFIG and GIT_CONFIG_PARAMETERS, …) and the GIT_CONFIG_KEY_<n> and
5219
+ * GIT_CONFIG_VALUE_<n> pairs are left out. `env` adds variables after that:
5220
+ * a read that names its own GIT_INDEX_FILE keeps it.
5221
+ * The operator's global and system configuration stay read, unlike
5222
+ * lib/instance-git.mjs's READ_ONLY_GIT with gitEnv(): the spawn baseline was
5223
+ * taken under them, and without them a status reads differently (a global
5224
+ * core.excludesFile, core.autocrlf, a filter), which would add a copy
5225
+ * attempt to every existing instance's retire. These flags leave a status as
5226
+ * it was. They are the operator's own; what the retire guards against is
5227
+ * configuration the retired agent could write.
5228
+ * Known limit: a filter driver that the repository's configuration names and
5229
+ * its .gitattributes select can still run during `git status`; turning it
5230
+ * off would change what status reports. */
5231
+ const RETIRE_GIT_FLAGS = ["--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "diff.external="];
5232
+ const RETIRE_GIT_DROPPED_ENV = new Set(["GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE", "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS", "GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR"]);
5233
+ function retireGitEnv(env) {
5234
+ const out = {};
5235
+ for (const [key, value] of Object.entries(process.env)) {
5236
+ if (!RETIRE_GIT_DROPPED_ENV.has(key) && !/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key)) out[key] = value;
5237
+ }
5238
+ return { ...out, GIT_OPTIONAL_LOCKS: "0", GIT_NO_LAZY_FETCH: "1", ...env };
5239
+ }
5240
+ /** One retire Git command in `repo` (`-C`; null for none, as for a clone) →
5241
+ * its stdout (a Buffer, or text with `encoding`); throws what execFileSync
5242
+ * throws. */
5243
+ function retireGit(repo, args, { env, input, encoding } = {}) {
5244
+ return execFileSync("git", [...RETIRE_GIT_FLAGS, ...(repo === null ? [] : ["-C", repo]), ...args],
5245
+ { stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, encoding, maxBuffer: GIT_MAX_BUFFER, shell: false, env: retireGitEnv(env) });
5246
+ }
5247
+ /** retireGit that never throws → spawnSync's result, for a caller that reads the exit status. */
5248
+ function retireGitProbe(repo, args, { encoding } = {}) {
5249
+ return spawnSync("git", [...RETIRE_GIT_FLAGS, "-C", repo, ...args], { stdio: ["ignore", "pipe", "pipe"], encoding, maxBuffer: GIT_MAX_BUFFER, shell: false, env: retireGitEnv() });
5250
+ }
5251
+
4947
5252
  /** Kernel-owned receipts the kernel itself appends to a home after the spawn
4948
5253
  * baseline (events log, stop/restart receipts). They are evidence about the
4949
5254
  * instance, not the instance's work, so the stored digest a spawn baseline is
@@ -4962,12 +5267,19 @@ const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oat
4962
5267
  * settings.json at every launch. The stored digest passes over exactly that
4963
5268
  * path, home-relative; the exact digest holds it, as the home copy does. */
4964
5269
  const HARNESS_HOME_SETTINGS = new Set([join(".claude", "settings.json")]);
5270
+ /** Kernel state written under `.oats/` after the spawn baseline (#796): the extra
5271
+ * trees' records (`oats worktree add|remove`) and the `worktree` hooks' logs.
5272
+ * Receipts, not work: the stored digest passes over them as it does over the
5273
+ * kernel's top-level receipts; the exact digest and the home copy hold them.
5274
+ * They live under `.oats`, which a capability may not declare as its own. */
5275
+ const KERNEL_HOME_STATE_DIRS = new Set([join(".oats", "trees"), join(".oats", "logs")]);
4965
5276
  /** The refusal for an entry that is not a file, a directory or a symbolic link
4966
5277
  * (a socket, a FIFO, a device): it has no bytes to read or to copy. One
4967
5278
  * sentence for every caller of fingerprintTree, at spawn and at retire, so it
4968
5279
  * names neither. It does not say "remove": the entry may be a live endpoint. */
4969
5280
  const unsupportedEntry = (path) => oatsError("E_WORK_INSPECTION_FAILED", `${path} has an unsupported filesystem type: it is not a file, a directory or a symbolic link, so it cannot be read or copied. Safely stop the process or resource that owns it, or move the entry elsewhere, before retrying`);
4970
5281
  const PATH_SEPARATOR_BYTES = Buffer.from(sep);
5282
+ const GIT_NAME = Buffer.from(".git");
4971
5283
  /** The digests of a tree, from one walk that reads each file once → { stored,
4972
5284
  * exact }; each only when asked for (`stored` by default).
4973
5285
  *
@@ -4975,29 +5287,39 @@ const PATH_SEPARATOR_BYTES = Buffer.from(sep);
4975
5287
  * permission bits, its kind, and a file's bytes or a link's target. Entry
4976
5288
  * names and link targets are read and hashed as bytes, never as decoded
4977
5289
  * text: two trees that differ only in bytes that are not UTF-8 have two
4978
- * digests, and an entry with such a name is read, not missed. This is about
4979
- * what a digest tells apart. It does not make such a tree copyable:
4980
- * copyTreeSafe reads entry names as text and cannot carry a file name that
4981
- * is not UTF-8.
5290
+ * digests, and an entry with such a name is read, not missed. copyTreeSafe
5291
+ * reads, joins and writes names as bytes too, so such an entry is copied.
5292
+ * `root` is a path, as text or as bytes.
4982
5293
  *
4983
5294
  * A name's text (its bytes decoded as UTF-8, the way readdirSync decodes
4984
5295
  * them: replacement characters for bytes that are not UTF-8, a byte order
4985
- * mark kept) is used only to order the entries and to test membership: the
4986
- * names a digest passes over and `instance.json`, as they have always been
4987
- * tested. Both digests pass over what a copy does not carry: `excludeRoot`
4988
- * and, with `excludeGitMetadata`, `.git`. Only the stored digest also passes
4989
- * over the kernel's receipts and the harness settings of a home.
5296
+ * mark kept) is used only to test membership: the names a digest passes over
5297
+ * and `instance.json`, as they have always been tested, and to order the
5298
+ * entries for the legacy stored digest. Both digests pass over what a copy
5299
+ * does not carry: `excludeRoot`, names at the top level tested as text, and
5300
+ * `excludePaths`, exact paths under the root as bytes (a list of Buffers):
5301
+ * an entry is passed over only where its whole path is one of them, whatever
5302
+ * its kind, never by its name alone. Only the stored digest also passes over
5303
+ * the kernel's receipts and the harness settings of a home.
4990
5304
  *
4991
- * `stored` is the digest a spawn baseline holds, written by this kernel or
4992
- * by an older one, so it never changes: its framing (each field followed by
4993
- * NUL, no lengths), its order, and a home's `instance.json` without the
4994
- * fields the kernel writes after spawn (kernelNeutralInstanceJson). For a
4995
- * tree whose names and link targets are all valid UTF-8 it is what it was
4996
- * when they were read as text: hashing a text hashes its UTF-8, which is
4997
- * those bytes. It is what is compared with a baseline. Without lengths it
4998
- * reads alike a file whose bytes spell the entry that follows it and those
4999
- * two entries, and the neutral form reads alike two `instance.json` files
5000
- * that parse to the same value.
5305
+ * `stored` is the digest a spawn baseline holds and is compared with, in the
5306
+ * version `digestVersion` names (the baseline's own: baselineDigestVersion).
5307
+ * Both versions hold a home's `instance.json` without the fields the kernel
5308
+ * writes after spawn (kernelNeutralInstanceJson), so they read alike two
5309
+ * `instance.json` files that parse to the same value.
5310
+ * - 1, the legacy digest: what a baseline without `digestVersion` holds,
5311
+ * written by a kernel before 0.49.0. It never changes: its framing (each
5312
+ * field followed by NUL, no lengths) and its order (the names as text,
5313
+ * compared by localeCompare, so it depends on the locale). For a tree whose
5314
+ * names and link targets are all valid UTF-8 it is what it was when they
5315
+ * were read as text: hashing a text hashes its UTF-8, which is those bytes.
5316
+ * Without lengths it reads alike a file whose bytes spell the entry that
5317
+ * follows it and those two entries.
5318
+ * - 2 (BASELINE_DIGEST_VERSION), what a spawn writes now: the framing of the
5319
+ * exact digest below, and the entries ordered by the bytes of their names,
5320
+ * which no locale changes. Two trees it does not read alike are two
5321
+ * trees, but for the receipts, the harness settings and the neutral form
5322
+ * of `instance.json` it passes over.
5001
5323
  *
5002
5324
  * `exact` is for every comparison of a tree with itself later, or with its
5003
5325
  * copy: whether the retire hooks left it as it was. It is kept nowhere. It
@@ -5007,7 +5329,11 @@ const PATH_SEPARATOR_BYTES = Buffer.from(sep);
5007
5329
  * path, its mode, its kind and its content, where the path and the content
5008
5330
  * carry their length and the mode and the kind end in NUL, so the stream can
5009
5331
  * be read back into its entries in one way only, and a tree is the set of
5010
- * its entries. A home's `instance.json` goes in as the bytes it has.
5332
+ * its entries. A home's `instance.json` goes in as the bytes it has. It
5333
+ * follows the walk's order: the legacy digest's when the walk takes that
5334
+ * one too, the order of the bytes otherwise. An exact digest is compared
5335
+ * only with one taken with the same options (an inspection's, with the
5336
+ * same baseline), so the two are taken in one order.
5011
5337
  *
5012
5338
  * The root's own permission bits, which are no entry of the walk, are in
5013
5339
  * the exact digest: a path the recovery copier copies is compared with its
@@ -5016,69 +5342,90 @@ const PATH_SEPARATOR_BYTES = Buffer.from(sep);
5016
5342
  * its copy is made inside a directory the copier creates, so the root's bits
5017
5343
  * are no part of what it carries, and the root is compared through its
5018
5344
  * children alone. The stored digest never holds the root's bits. */
5019
- function fingerprintTrees(root, { excludeRoot = new Set(), excludeGitMetadata = false, instanceHome = false, stored = true, exact = false, children = false } = {}) {
5020
- const s = stored ? createHash("sha256") : null, x = exact ? createHash("sha256") : null;
5021
- const digests = () => ({ stored: s ? `sha256:${s.digest("hex")}` : undefined, exact: x ? `sha256:${x.digest("hex")}` : undefined });
5022
- /** A field of the exact digest whose length is not fixed: its length, NUL, its bytes. */
5023
- const sized = (bytes) => { x.update(String(bytes.length)); x.update("\0"); x.update(bytes); };
5345
+ function fingerprintTrees(root, { excludeRoot = new Set(), excludePaths = [], instanceHome = false, stored = true, digestVersion = 1, exact = false, children = false } = {}) {
5346
+ if (stored && digestVersion !== 1 && digestVersion !== BASELINE_DIGEST_VERSION) throw new Error(`no stored digest of version ${digestVersion}`);
5347
+ const legacy = stored && digestVersion === 1;
5348
+ const excluded = new Set(excludePaths.map((path) => path.toString("hex")));
5349
+ // The stored digest: `s` when it is the legacy one, `v` when it is version 2.
5350
+ const s = legacy ? createHash("sha256") : null, v = stored && !legacy ? createHash("sha256") : null, x = exact ? createHash("sha256") : null;
5351
+ const digests = () => ({ stored: s || v ? `sha256:${(s || v).digest("hex")}` : undefined, exact: x ? `sha256:${x.digest("hex")}` : undefined });
5352
+ /** A field whose length is not fixed, in the exact digest or in version 2: its length, NUL, its bytes. */
5353
+ const sizedIn = (hash, bytes) => { hash.update(String(bytes.length)); hash.update("\0"); hash.update(bytes); };
5354
+ const sized = (bytes) => sizedIn(x, bytes);
5024
5355
  const rootStat = lstatSync(root);
5025
5356
  if (!rootStat.isDirectory()) {
5026
5357
  const mode = String(rootStat.mode & 0o7777);
5027
5358
  s?.update(mode); s?.update("\0");
5359
+ v?.update("entry\0"); v?.update(mode); v?.update("\0");
5028
5360
  x?.update("entry\0"); x?.update(mode); x?.update("\0");
5029
- if (rootStat.isSymbolicLink()) { const target = readlinkSync(root, "buffer"); s?.update("link\0"); s?.update(target); if (x) { x.update("link\0"); sized(target); } }
5030
- else if (rootStat.isFile()) { const bytes = readFileSync(root); s?.update("file\0"); s?.update(bytes); if (x) { x.update("file\0"); sized(bytes); } }
5031
- else throw unsupportedEntry(root);
5361
+ if (rootStat.isSymbolicLink()) { const target = readlinkSync(root, "buffer"); s?.update("link\0"); s?.update(target); if (v) { v.update("link\0"); sizedIn(v, target); } if (x) { x.update("link\0"); sized(target); } }
5362
+ else if (rootStat.isFile()) { const bytes = readFileSync(root); s?.update("file\0"); s?.update(bytes); if (v) { v.update("file\0"); sizedIn(v, bytes); } if (x) { x.update("file\0"); sized(bytes); } }
5363
+ else throw unsupportedEntry(String(root));
5032
5364
  return digests();
5033
5365
  }
5366
+ v?.update("tree\0");
5034
5367
  x?.update(children ? "tree\0" : `tree with its mode\0${rootStat.mode & 0o7777}\0`);
5035
5368
  // `dir` and `rel` are bytes: the directory, and its path under the root
5036
5369
  // (empty at the root). `relText` is `rel` as text, for the name tests.
5037
- // `outer` is the stored hash, or null inside an entry it passes over.
5038
- const walk = (dir, rel, relText, outer) => {
5039
- // The order is the one it has always been: the names as text, compared
5040
- // by localeCompare, on the listing as readdirSync returns it. The sort is
5041
- // stable and the listing is the same whether its names come as text or
5042
- // as bytes, so a tree whose names are all valid UTF-8 is walked in the
5043
- // order it always was. Names that decode alike (two that are not UTF-8,
5044
- // or one and a name that really holds the replacement character) keep
5045
- // the listing's order. Where that order is not fixed, two reads of one
5046
- // directory can differ, which adds a copy attempt; two different trees
5047
- // cannot read alike for it, because the bytes of every name are hashed.
5048
- const entries = readdirSync(dir, { encoding: "buffer" }).map((bytes) => ({ bytes, name: bytes.toString("utf8") }));
5049
- entries.sort((a, b) => a.name.localeCompare(b.name));
5370
+ // `storedOn` is false inside an entry the stored digest passes over.
5371
+ const walk = (dir, rel, relText, storedOn) => {
5372
+ // The legacy order is the one it has always been: the names as text,
5373
+ // compared by localeCompare, on the listing as readdirSync returns it.
5374
+ // The sort is stable and the listing is the same whether its names come
5375
+ // as text or as bytes, so a tree whose names are all valid UTF-8 is
5376
+ // walked in the order it always was. Names that decode alike (two that
5377
+ // are not UTF-8, or one and a name that really holds the replacement
5378
+ // character) keep the listing's order. Where that order is not fixed, two
5379
+ // reads of one directory can differ, which adds a copy attempt; two
5380
+ // different trees cannot read alike for it, because the bytes of every
5381
+ // name are hashed. Every other walk is in the order of the names' bytes
5382
+ // (entriesAsBytes), which is fixed.
5383
+ const entries = legacy
5384
+ ? readdirSync(dir, { encoding: "buffer" }).map((bytes) => ({ bytes, name: bytes.toString("utf8") })).sort((a, b) => a.name.localeCompare(b.name))
5385
+ : entriesAsBytes(dir).map((e) => ({ bytes: e.name, name: e.name.toString("utf8") }));
5050
5386
  for (const { bytes: nameBytes, name } of entries) {
5051
- if ((!relText && excludeRoot.has(name)) || (excludeGitMetadata && name === ".git")) continue;
5387
+ const childRel = rel.length ? Buffer.concat([rel, PATH_SEPARATOR_BYTES, nameBytes]) : nameBytes;
5388
+ if ((!relText && excludeRoot.has(name)) || (excluded.size && excluded.has(childRel.toString("hex")))) continue;
5052
5389
  const childRelText = relText ? join(relText, name) : name;
5053
- const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText));
5390
+ const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText) || KERNEL_HOME_STATE_DIRS.has(childRelText));
5054
5391
  if (storedPassesOver && !x) continue;
5055
- const s = storedPassesOver ? null : outer;
5056
- const childRel = rel.length ? Buffer.concat([rel, PATH_SEPARATOR_BYTES, nameBytes]) : nameBytes;
5392
+ const on = storedOn && !storedPassesOver;
5393
+ const s = on ? outerS : null, v = on ? outerV : null;
5057
5394
  const path = Buffer.concat([dir, PATH_SEPARATOR_BYTES, nameBytes]);
5058
5395
  const st = lstatSync(path);
5059
5396
  const mode = String(st.mode & 0o7777);
5060
5397
  s?.update(childRel); s?.update("\0"); s?.update(mode); s?.update("\0");
5398
+ if (v) { sizedIn(v, childRel); v.update(mode); v.update("\0"); }
5061
5399
  if (x) { sized(childRel); x.update(mode); x.update("\0"); }
5062
5400
  if (st.isSymbolicLink()) {
5063
5401
  const target = readlinkSync(path, "buffer");
5064
5402
  s?.update("link\0"); s?.update(target); s?.update("\0");
5403
+ if (v) { v.update("link\0"); sizedIn(v, target); }
5065
5404
  if (x) { x.update("link\0"); sized(target); }
5066
5405
  } else if (st.isFile()) {
5067
5406
  const bytes = readFileSync(path);
5068
5407
  // Kernel-field neutrality applies ONLY when the tree IS an instance home, and only to the
5069
5408
  // stored digest; a work tree's instance.json is the agent's bytes.
5070
- s?.update("file\0"); s?.update(instanceHome && !relText && name === "instance.json" ? kernelNeutralInstanceJson(bytes) : bytes); s?.update("\0");
5409
+ const storedBytes = s || v ? (instanceHome && !relText && name === "instance.json" ? kernelNeutralInstanceJson(bytes) : bytes) : undefined;
5410
+ s?.update("file\0"); s?.update(storedBytes); s?.update("\0");
5411
+ if (v) { v.update("file\0"); sizedIn(v, storedBytes); }
5071
5412
  if (x) { x.update("file\0"); sized(bytes); }
5072
- } else if (st.isDirectory()) { s?.update("dir\0"); x?.update("dir\0"); walk(path, childRel, childRelText, s); }
5073
- else throw unsupportedEntry(join(root, childRelText));
5413
+ } else if (st.isDirectory()) { s?.update("dir\0"); v?.update("dir\0"); x?.update("dir\0"); walk(path, childRel, childRelText, on); }
5414
+ else throw unsupportedEntry(join(String(root), childRelText));
5074
5415
  }
5075
5416
  };
5076
- walk(Buffer.from(root), Buffer.alloc(0), "", s);
5417
+ const outerS = s, outerV = v;
5418
+ walk(Buffer.from(root), Buffer.alloc(0), "", true);
5077
5419
  return digests();
5078
5420
  }
5079
- /** The stored digest of a tree (fingerprintTrees): what a spawn baseline holds and is compared with. */
5421
+ /** The legacy stored digest of a tree (fingerprintTrees, version 1): what a spawn baseline without
5422
+ * `digestVersion` holds and is compared with. */
5080
5423
  function fingerprintTree(root, options = {}) {
5081
- return fingerprintTrees(root, { ...options, stored: true, exact: false }).stored;
5424
+ return fingerprintTrees(root, { ...options, stored: true, digestVersion: 1, exact: false }).stored;
5425
+ }
5426
+ /** The stored digest of a tree in `digestVersion` (fingerprintTrees): 1, the legacy one, or 2. */
5427
+ function storedTreeDigest(root, digestVersion, options = {}) {
5428
+ return fingerprintTrees(root, { ...options, stored: true, digestVersion, exact: false }).stored;
5082
5429
  }
5083
5430
  /** The exact digest of a tree (fingerprintTrees): what a tree is compared with itself later, or with its copy. */
5084
5431
  function exactTreeDigest(root, options = {}) {
@@ -5090,7 +5437,10 @@ const directoryBytes = (work) => exactTreeDigest(work);
5090
5437
 
5091
5438
  /** A worktree directory whose git admin entry is gone: no `.git`, an unreadable one, or a gitfile naming an
5092
5439
  * admin directory that no longer exists. Read from the gitfile, not asked of git, which would walk up into
5093
- * whatever repository encloses the home. A `.git` directory is a repository of its own, not this case. */
5440
+ * whatever repository encloses the home. A `.git` directory is a repository of its own, not this case.
5441
+ * The gitfile is parsed as Git parses it (setup.c, read_gitfile_gently): the file starts with `gitdir: `,
5442
+ * and the path is the rest of it with its trailing run of line feeds and carriage returns removed, white
5443
+ * space kept (awebai/oats#647). A file Git would not read as a gitfile names no admin entry. */
5094
5444
  function worktreeAdminMissing(work) {
5095
5445
  const dotGit = join(work, ".git");
5096
5446
  let stat;
@@ -5099,9 +5449,10 @@ function worktreeAdminMissing(work) {
5099
5449
  if (!stat.isFile()) return true;
5100
5450
  let text;
5101
5451
  try { text = readFileSync(dotGit, "utf8"); } catch { return true; }
5102
- const m = /^gitdir:\s*(.+?)\s*$/m.exec(text);
5103
- if (!m) return true;
5104
- return !existsSync(join(resolve(work, m[1]), "HEAD"));
5452
+ if (!text.startsWith("gitdir: ")) return true;
5453
+ const path = text.slice("gitdir: ".length).replace(/[\r\n]+$/, "");
5454
+ if (!path) return true;
5455
+ return !existsSync(join(resolve(work, path), "HEAD"));
5105
5456
  }
5106
5457
  /** A repository's status as Git printed it, as bytes. A path that is not
5107
5458
  * UTF-8 is in there as it is: the work state compares these bytes
@@ -5109,7 +5460,7 @@ function worktreeAdminMissing(work) {
5109
5460
  * a `git status` that fails is. */
5110
5461
  function worktreeStatusBytes(repo) {
5111
5462
  try {
5112
- return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
5463
+ return retireGit(repo, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"]);
5113
5464
  } catch (e) {
5114
5465
  throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect instance worktree: ${String(e.stderr ?? e.message ?? "").trim() || "git status failed"}`);
5115
5466
  }
@@ -5152,6 +5503,48 @@ function assertStatusAgrees(source, recovered, what, repo) {
5152
5503
  throw Object.assign(new Error(`${what}${shown ? `: ${shown}${more}` : ""}`), { statusDisagreement: { repo, ...diff } });
5153
5504
  }
5154
5505
 
5506
+ /** The digest of a worktree's untracked (`??`) and ignored (`!!`) paths, outside the disposable
5507
+ * roots, that a spawn baseline stores as `generatedWorkFingerprint`, in the baseline's digest
5508
+ * version (baselineDigestVersion) → the digest, or undefined for a version this kernel does not
5509
+ * take. `statusBytes` is the worktree's status as bytes (worktreeStatusBytes). */
5510
+ function generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposableRoots = []) {
5511
+ if (digestVersion === 1) return generatedWorkFingerprint(work, statusBytes.toString("utf8"), disposableRoots);
5512
+ if (digestVersion === BASELINE_DIGEST_VERSION) return generatedWorkDigest(work, statusBytes, disposableRoots);
5513
+ return undefined;
5514
+ }
5515
+ /** Version 2 of generatedWorkFingerprint. The paths are the status's bytes (untrackedOrIgnoredPaths),
5516
+ * so a name that is not UTF-8 is read by its own name, and they are in the order of those bytes. A
5517
+ * path is hashed as its length and its bytes, then, by lstat (a link is never followed): `missing`
5518
+ * for one that is not there, else its stored digest of version 2 (a link is its target's bytes,
5519
+ * whether or not the target exists). A trailing `/` (an ignored directory's row) is hashed with the
5520
+ * path but not used to read it, so a link in its place is read as the link. A disposable root owns
5521
+ * a path that is it or under it, compared as bytes, as the legacy digest compares it as text.
5522
+ * A path that cannot be tested (lstat fails otherwise than for an entry that is not there) or read
5523
+ * (an entry under it without permission, for example) is no path the digest can prove anything
5524
+ * of: it throws E_WORK_INSPECTION_FAILED, `could not inspect <path>: <reason>`, the path as text. */
5525
+ function generatedWorkDigest(work, statusBytes, disposableRoots = []) {
5526
+ const roots = disposableRoots.map((root) => [Buffer.from(root), Buffer.from(`${root}${sep}`)]);
5527
+ const owned = (path) => roots.some(([root, under]) => path.equals(root) || (path.length >= under.length && path.subarray(0, under.length).equals(under)));
5528
+ const paths = untrackedOrIgnoredPaths(statusBytes).filter((path) => !owned(path)).sort(Buffer.compare);
5529
+ const hash = createHash("sha256");
5530
+ for (const rel of paths) {
5531
+ hash.update(String(rel.length)); hash.update("\0"); hash.update(rel);
5532
+ const path = joinBytes(work, rel.length > 1 && rel[rel.length - 1] === 0x2f ? rel.subarray(0, -1) : rel);
5533
+ const uninspectable = (e) => (e?.code === "E_WORK_INSPECTION_FAILED" ? e : oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path.toString()}: ${e.message}`));
5534
+ try { lstatSync(path); }
5535
+ catch (e) {
5536
+ if (e?.code !== "ENOENT" && e?.code !== "ENOTDIR") throw uninspectable(e);
5537
+ hash.update("missing\0"); continue;
5538
+ }
5539
+ let digest;
5540
+ try { digest = storedTreeDigest(path, BASELINE_DIGEST_VERSION); }
5541
+ catch (e) { throw uninspectable(e); }
5542
+ hash.update(digest); hash.update("\0");
5543
+ }
5544
+ return `sha256:${hash.digest("hex")}`;
5545
+ }
5546
+ /** The legacy generatedWorkFingerprint (digest version 1), for a baseline without `digestVersion`.
5547
+ * It never changes: the decoded status's paths, tested with existsSync, which follows a link. */
5155
5548
  function generatedWorkFingerprint(work, status, disposableRoots = []) {
5156
5549
  const owned = (path) => disposableRoots.some((root) => path === root || path.startsWith(`${root}${sep}`));
5157
5550
  const paths = status.split("\0").filter(Boolean)
@@ -5173,12 +5566,15 @@ function retirementDisposableRoots(work, capabilities) {
5173
5566
  ];
5174
5567
  const roots = [];
5175
5568
  for (const receipt of receipts) {
5176
- if (typeof receipt.root !== "string" || !receipt.root || isAbsolute(receipt.root)) throw new Error(`retirement disposable root from ${receipt.owner} must be relative`);
5569
+ // The manifest check (capability-contract.mjs, disposableWorkRootProblem) refuses
5570
+ // the first two before a spawn gets here; they stay for a copy read without it.
5571
+ if (typeof receipt.root !== "string" || !receipt.root || isAbsolute(receipt.root)) throw oatsError("E_CAPABILITY_BROKEN", `retirement disposable root from ${receipt.owner} must be relative`);
5177
5572
  const normalized = receipt.root.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
5178
- if (!normalized || normalized.split("/").some((part) => !part || part === "." || part === "..")) throw new Error(`unsafe retirement disposable root from ${receipt.owner}: ${receipt.root}`);
5573
+ if (!normalized || normalized.split("/").some((part) => !part || part === "." || part === "..")) throw oatsError("E_CAPABILITY_BROKEN", `unsafe retirement disposable root from ${receipt.owner}: ${receipt.root}`);
5179
5574
  const path = join(work, normalized);
5180
- if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error(`retirement disposable root from ${receipt.owner} is a symlink: ${normalized}`);
5181
- if (roots.some((r) => normalized === r.root || normalized.startsWith(`${r.root}/`) || r.root.startsWith(`${normalized}/`))) throw new Error(`overlapping retirement disposable roots: ${normalized}`);
5575
+ // lstat, never existsSync: a link whose target is missing is a link all the same.
5576
+ if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) throw oatsError("E_CAPABILITY_BROKEN", `retirement disposable root from ${receipt.owner} is a symlink: ${normalized}`);
5577
+ if (roots.some((r) => normalized === r.root || normalized.startsWith(`${r.root}/`) || r.root.startsWith(`${normalized}/`))) throw oatsError("E_CAPABILITY_BROKEN", `overlapping retirement disposable roots: ${normalized}`);
5182
5578
  roots.push({ owner: receipt.owner, root: normalized });
5183
5579
  }
5184
5580
  return roots;
@@ -5279,8 +5675,9 @@ function extraWorktreesOf(home) {
5279
5675
  const trees = [];
5280
5676
  let names;
5281
5677
  try { names = readdirSync(home); } catch { return trees; }
5282
- const realHome = realPathOrNearest(home);
5283
- const inHome = (p) => { const rel = relative(realHome, realPathOrNearest(p)); return rel === "" || !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)); };
5678
+ // Git reports paths in their on-disk spelling: the home and each tree are compared in it too.
5679
+ const realHome = canonicalHomePath(home);
5680
+ const inHome = (p) => { const rel = relative(realHome, canonicalHomePath(p)); return rel === "" || !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)); };
5284
5681
  for (const name of names.sort(byCodeUnit)) {
5285
5682
  if (!name.startsWith(".work-")) continue;
5286
5683
  const path = join(home, name);
@@ -5291,28 +5688,50 @@ function extraWorktreesOf(home) {
5291
5688
  if (!dirs.ok) continue;
5292
5689
  const [gitDir, commonDir, toplevel] = dirs.out.split("\n");
5293
5690
  if (!gitDir || !commonDir || !toplevel || realPathOrNearest(gitDir) === realPathOrNearest(commonDir)) continue;
5294
- const real = realPathOrNearest(path);
5691
+ const real = canonicalHomePath(path);
5295
5692
  // A repository inside the home goes with the home: its trees are home bytes.
5296
- if (realPathOrNearest(toplevel) !== real || inHome(commonDir)) continue;
5693
+ if (canonicalHomePath(toplevel) !== real || inHome(commonDir)) continue;
5297
5694
  const list = gitRead(path, ["worktree", "list", "--porcelain", "-z"]);
5298
5695
  if (!list.ok) continue;
5299
5696
  const records = parseWorktreeList(list.out);
5300
- const self = records.find((r) => realPathOrNearest(r.worktree) === real);
5697
+ const self = records.find((r) => canonicalHomePath(r.worktree) === real);
5301
5698
  if (!records.length || !self) continue;
5302
5699
  trees.push({ name, path, repo: records[0].worktree, gitDir, commonDir: realPathOrNearest(commonDir), locked: self.locked });
5303
5700
  }
5304
5701
  return trees;
5305
5702
  }
5703
+ /** Where retire re-homes the worktrees it retains, one directory per repository under it. */
5704
+ export function retainedWorktreesRoot(workspace) {
5705
+ return join(workspace, ".agents", "worktrees");
5706
+ }
5707
+ /** The longest retained-worktree leaf before its `-N` suffix, in bytes (awebai/oats#821). The
5708
+ * leaf is one path component, so it must fit NAME_MAX (255 on the usual filesystems). 16 bytes
5709
+ * are kept as a margin, as the test fixtures keep: nothing appends to the leaf's name today
5710
+ * (`git worktree move` renames to the path it is given, which does not exist, and adds nothing),
5711
+ * so the margin is headroom only. 8 more are kept for the `-N` suffix (`-` and up to seven
5712
+ * digits). A leaf is then at most 231 bytes, and at most 239 with its suffix. */
5713
+ export const RETAINED_LEAF_MAX = 255 - 16 - 8;
5306
5714
  /** Where a retired worktree is re-homed: `<workspace>/.agents/worktrees/<repoName>/<leaf>`,
5307
- * the leaf being the branch, else `detached-<commit>`; when that exists (or
5308
- * `taken` holds it), `<leaf>-2`, `-3`, … The one naming rule of work/ and of
5309
- * the extra trees. Creates nothing. */
5715
+ * the leaf being the branch, else `detached-<commit>`, with every run of characters outside
5716
+ * `[A-Za-z0-9._-]` made `-`; when that exists (or `taken` holds it), `<leaf>-2`, `-3`, … A leaf
5717
+ * over RETAINED_LEAF_MAX is cut to fit, its trailing `-` trimmed, and followed by `-` and 6 hex
5718
+ * of the SHA-256 of the full branch name: deterministic, readable, and one per branch. The
5719
+ * character class keeps the leaf ASCII, so its length in characters is its length in bytes;
5720
+ * widen the class and the bound must measure bytes. The one naming rule of work/ and of the
5721
+ * extra trees, the plan's `movedTo` and the apply's alike. Creates nothing. */
5310
5722
  function retainedWorktreeDest(workspace, repo, branch, commit, taken = new Set()) {
5311
5723
  const repoName = basename(realPathOrNearest(repo)).replace(/\.git$/, "") || "repo";
5312
- const leaf = (branch ?? `detached-${(commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
5313
- const retainedRoot = join(workspace, ".agents", "worktrees", repoName);
5314
- let dest = join(retainedRoot, leaf);
5315
- for (let n = 2; existsSync(dest) || taken.has(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
5724
+ const name = branch ?? `detached-${(commit || "unknown").slice(0, 12)}`;
5725
+ const flat = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
5726
+ const hash = () => createHash("sha256").update(name, "utf8").digest("hex").slice(0, 6);
5727
+ /** The leaf in `room` bytes: as it is when it fits, else cut and hashed. */
5728
+ const fit = (room) => flat.length <= room ? flat : `${flat.slice(0, room - 7).replace(/-+$/, "")}-${hash()}`;
5729
+ const retainedRoot = join(retainedWorktreesRoot(workspace), repoName);
5730
+ let dest = join(retainedRoot, fit(RETAINED_LEAF_MAX));
5731
+ // The 8 bytes kept for `-N` hold `-2` to `-9999999`; a longer suffix takes its extra bytes from
5732
+ // the leaf's readable part, never its hash, so a leaf with its suffix never passes
5733
+ // RETAINED_LEAF_MAX + 8.
5734
+ 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}`);
5316
5735
  taken.add(dest);
5317
5736
  return dest;
5318
5737
  }
@@ -5360,30 +5779,31 @@ function unionNotCopied(...lists) {
5360
5779
  return [...byPath.values()].sort((a, b) => byCodeUnit(a.path, b.path));
5361
5780
  }
5362
5781
  function retirementBaselineValid(baseline, home) {
5363
- return baseline?.version === RETIRE_BASELINE_VERSION && baseline.home === realPathOrNearest(home);
5782
+ return baseline?.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home));
5364
5783
  }
5365
5784
  /** What a retire plan may say about recovery without hashing anything: where a
5366
5785
  * recovery would be written, and the home entries the spawn baseline declares
5367
5786
  * as not copied (none without a valid baseline). */
5368
5787
  export function retirementRecoveryFacts(home) {
5369
- const baseline = readJsonOrUndefined(retirementBaselinePath(home));
5370
- return { recoveryRoot: join(retirementStateRoot(home), "recovery"), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
5788
+ const baseline = readJsonOrUndefined(findRetirementBaseline(home));
5789
+ return { recoveryRoot: retirementRecoveryRoot(dirname(home)), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
5371
5790
  }
5372
5791
  function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
5373
5792
  if (mode === "directory") assertDirectoryRoots(home);
5374
5793
  const isWorktree = mode === "worktree";
5375
- const status = isWorktree && existsSync(work) ? worktreeStatus(work) : "";
5794
+ const statusBytes = isWorktree && existsSync(work) ? worktreeStatusBytes(work) : Buffer.alloc(0);
5376
5795
  const disposableReceipts = isWorktree ? retirementDisposableRoots(work, capabilities) : [];
5377
5796
  const disposableHome = retirementDisposableHome(capabilities);
5378
5797
  const baseline = {
5379
5798
  version: RETIRE_BASELINE_VERSION,
5799
+ digestVersion: BASELINE_DIGEST_VERSION,
5380
5800
  ...(incarnationId ? { incarnationId, executionBinding } : {}),
5381
5801
  ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
5382
- home: realPathOrNearest(home),
5383
- homeFingerprint: fingerprintTree(home, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, instanceHome: true }),
5802
+ home: canonicalHomePath(home),
5803
+ homeFingerprint: storedTreeDigest(home, BASELINE_DIGEST_VERSION, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, instanceHome: true }),
5384
5804
  disposableReceipts,
5385
5805
  disposableHome,
5386
- generatedWorkFingerprint: isWorktree ? generatedWorkFingerprint(work, status, disposableReceipts.map((r) => r.root)) : undefined,
5806
+ generatedWorkFingerprint: isWorktree ? generatedWorkDigest(work, statusBytes, disposableReceipts.map((r) => r.root)) : undefined,
5387
5807
  runtime: {
5388
5808
  launched: runtime?.launched === true,
5389
5809
  ...(runtime?.tmux ? { tmux: { session: runtime.tmux.session, window: runtime.tmux.window, ...(runtime.tmux.socket ? { socket: resolve(runtime.tmux.socket) } : {}) } } : {}),
@@ -5394,17 +5814,24 @@ function writeRetirementBaseline(home, work, mode, capabilities, runtime, { excl
5394
5814
  writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600, ...(exclusive ? { flag: "wx" } : {}) });
5395
5815
  }
5396
5816
 
5817
+ /** The repositories a recovery rebuilds from a clone, under a worktree at
5818
+ * any depth → their paths, as bytes: each directory (never a link to one)
5819
+ * whose `.git` stat finds, a link to one followed. Names are read as bytes,
5820
+ * so a directory whose name is not UTF-8 is found, not missed. The walk does
5821
+ * not go into a repository it found: no path is under another, and a
5822
+ * repository inside one is no root of its own (it comes along as its
5823
+ * parent's plain files, its `.git` included: repositoriesUnder's `inner`). */
5397
5824
  function nestedGitRoots(root) {
5398
5825
  const out = [];
5399
5826
  const walk = (dir) => {
5400
- for (const e of readdirSync(dir, { withFileTypes: true })) {
5401
- if (!e.isDirectory() || e.isSymbolicLink?.()) continue;
5402
- const path = join(dir, e.name);
5403
- if (existsSync(join(path, ".git"))) { out.push(path); continue; }
5827
+ for (const e of entriesAsBytes(dir)) {
5828
+ if (!e.isDirectory() || e.isSymbolicLink()) continue;
5829
+ const path = joinBytes(dir, e.name);
5830
+ if (existsSync(joinBytes(path, GIT_NAME))) { out.push(path); continue; }
5404
5831
  walk(path);
5405
5832
  }
5406
5833
  };
5407
- walk(root);
5834
+ walk(pathBytes(root));
5408
5835
  return out;
5409
5836
  }
5410
5837
 
@@ -5416,7 +5843,7 @@ function nestedGitRoots(root) {
5416
5843
  * whether it could be shown gone. */
5417
5844
  function recordedBranchExists(repo, branch) {
5418
5845
  if (!repo || !branch) return true;
5419
- const r = spawnSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
5846
+ const r = retireGitProbe(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
5420
5847
  return !r.error && r.status === 0;
5421
5848
  }
5422
5849
 
@@ -5431,7 +5858,7 @@ function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path,
5431
5858
  /** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
5432
5859
  * missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
5433
5860
  function refuseHerdrHome(home) {
5434
- if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(retirementBaselinePath(home)))) throw herdrInstanceRemoved(basename(home));
5861
+ if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(findRetirementBaseline(home)))) throw herdrInstanceRemoved(basename(home));
5435
5862
  }
5436
5863
 
5437
5864
  function runtimeAuthorityOf(baseline) {
@@ -5456,10 +5883,13 @@ function launchStateAgrees(meta, authority) {
5456
5883
  ["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
5457
5884
  }
5458
5885
 
5459
- /** The refusal for a home whose session receipt file does not exist where its path says it is. The
5460
- * receipt is keyed by the home's path, so a different spelling of that path looks elsewhere. */
5461
- function missingSessionReceipt(home, receiptPath) {
5462
- return oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `no session receipt for ${home} at ${receiptPath}. First address the home exactly as \`oats status\` prints it (a different spelling — letter case, a moved deployment directory — looks for the receipt elsewhere). Otherwise the home was copied, the .oats-retirement beside it was removed, or its creation did not finish: stop its session yourself if one runs, then \`oats retire ${basename(home)} --plan\` and \`oats retire ${basename(home)}\` (work is preserved), and respawn.`);
5886
+ /** The refusal for a home whose session receipt is at neither key its path gives (findRetirementBaseline):
5887
+ * the canonical one, and the one an earlier kernel used for this spelling when that differs. The
5888
+ * receipt is keyed by the home's path, so a moved deployment looks elsewhere. */
5889
+ function missingSessionReceipt(home) {
5890
+ const canonical = retirementBaselinePath(home), legacy = legacyRetirementBaselinePath(home);
5891
+ const where = legacy === canonical ? canonical : `${canonical} (nor at ${legacy}, where a kernel before 0.49.0 kept it for this spelling)`;
5892
+ return oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `no session receipt for ${home} at ${where}. First address the home exactly as \`oats status\` prints it (a deployment directory moved since spawn looks for the receipt elsewhere, and so does a letter-case spelling other than the spawn's, for a home spawned before 0.49.0). Otherwise the home was copied, the .oats-retirement beside it was removed, or its creation did not finish: stop its session yourself if one runs, then \`oats retire ${basename(home)} --plan\` and \`oats retire ${basename(home)}\` (work is preserved), and respawn.`);
5463
5893
  }
5464
5894
 
5465
5895
  /** Session control uses the independent endpoint receipt. */
@@ -5467,16 +5897,16 @@ function instanceSessionTarget(home) {
5467
5897
  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
5468
5898
  home = realPathOrNearest(home);
5469
5899
  refuseHerdrHome(home);
5470
- const receiptPath = retirementBaselinePath(home);
5900
+ const receiptPath = findRetirementBaseline(home);
5471
5901
  let baseline, meta;
5472
5902
  try {
5473
5903
  baseline = JSON.parse(readFileSync(receiptPath, "utf8"));
5474
5904
  meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
5475
5905
  } catch (e) {
5476
- if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home, receiptPath);
5906
+ if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home);
5477
5907
  throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`);
5478
5908
  }
5479
- const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
5909
+ const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
5480
5910
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
5481
5911
  if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
5482
5912
  return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined };
@@ -5496,21 +5926,104 @@ export function inspectInstanceSession(home) {
5496
5926
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
5497
5927
  function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
5498
5928
 
5499
- /** K3: quiesce one instance's session and RETAIN everything else — home,
5500
- * worktree, transcript, launch configuration — so `restart` can bring it back.
5501
- * Exactly restart's stop half under the same independent endpoint authority
5502
- * (`instanceSessionTarget`), bounded and never escalated: a harness still
5503
- * there after the grace is reported still running, nothing is killed harder.
5504
- * A no-launch or already-idle instance is a no-op that says so. */
5505
- 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 ?? "")); }
5929
+ /** How a failed tmux call reads the server it addressed (#624). "gone": no server listens on the
5930
+ * socket (`no server running on`, or a refused connection), which is definitive. "missing-socket":
5931
+ * the socket file is not there (`No such file or directory`). After a reboot the server is gone,
5932
+ * but a tmux server outlives its removed socket file, so that alone establishes nothing: a caller
5933
+ * concludes stopped from it only when no process works in the home (missingSocketUnestablished).
5934
+ * null: anything else. */
5935
+ function tmuxServerAbsence(e) {
5936
+ const text = String(e?.stderr ?? e?.message ?? "");
5937
+ if (/no server running on |(?:error connecting to|failed to connect to) .*Connection refused/i.test(text)) return "gone";
5938
+ if (/(?:error connecting to|failed to connect to) .*No such file or directory/i.test(text)) return "missing-socket";
5939
+ return null;
5940
+ }
5941
+ function tmuxServerLost(e) { return tmuxServerAbsence(e) !== null; }
5942
+ /** tmux's own way back for a server that lost its socket file (tmux(1), `-S`). Named, never performed. */
5943
+ const TMUX_SOCKET_REMEDY = "tmux recreates a removed socket file when its server process receives SIGUSR1";
5944
+ /** Processes as a refusal names them: pid and program, at most five, then how many more. */
5945
+ function namedProcesses(processes) {
5946
+ return `${processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${processes.length > 5 ? `, and ${processes.length - 5} more` : ""}`;
5947
+ }
5948
+ /** A missing socket file (`detail`, tmux's words) checked against `scan`, processesInHome's answer
5949
+ * for the home (#624): null when it ran and found no process there, so the server is taken as gone,
5950
+ * as after a reboot; otherwise why the state is not established. Any process working in the home
5951
+ * counts, a person's shell included: the words name it, so the person can act on it. */
5952
+ function missingSocketUnestablished(detail, scan) {
5953
+ if (!scan.ok) return `${detail}; whether a process still works in this home could not be established (${scan.error})`;
5954
+ 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}`;
5955
+ return null;
5956
+ }
5957
+ /** Whether this host's /proc can be read: Linux, and this process's own `cwd` link resolves. */
5958
+ function procReadable() {
5959
+ if (process.platform !== "linux") return { ok: false, error: "this host has no /proc to read (it is not Linux)" };
5960
+ try { readlinkSync("/proc/self/cwd"); return { ok: true }; }
5961
+ catch (e) { return { ok: false, error: `/proc/self/cwd cannot be read (${e.code || e.message})` }; }
5962
+ }
5963
+ /** Which process scan this host offers, checked cheaply and without scanning (doctor reports it):
5964
+ * /proc on Linux, else lsof when it is on PATH. → { mechanism: "proc" | "lsof" } | { mechanism: null, error } */
5965
+ export function processScanAvailability() {
5966
+ const proc = procReadable();
5967
+ if (proc.ok) return { mechanism: "proc" };
5968
+ if (process.env.PATH !== undefined && lookupOnPath("lsof", process.env.PATH)) return { mechanism: "lsof" };
5969
+ return { mechanism: null, error: `${proc.error}, and lsof is not on PATH` };
5970
+ }
5971
+ /** Doctor's information line when this host has no process scan (`availability`, from
5972
+ * processScanAvailability); none when it has one. */
5973
+ export function processScanInformation(availability = processScanAvailability()) {
5974
+ if (availability.mechanism) return [];
5975
+ 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`];
5976
+ }
5506
5977
  /**
5507
- * The live processes (other than this one and its children) whose working
5508
- * directory is inside `home`: `lsof -a -d cwd` over the host, one call.
5509
- * → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan
5510
- * could not run, did not complete or listed no process: a caller must treat
5511
- * that as unknown, never as none).
5978
+ * Every live process on the host (other than this one and its direct children) with its working
5979
+ * directory, from one scan: /proc on Linux (`io.procRoot` names another root), else one `lsof -a -d
5980
+ * cwd` listing; an injected `io.exec` stands in for the host's commands, so it is lsof's. Each cwd
5981
+ * is kept in its on-disk spelling (canonicalHomePath); one the kernel reports deleted (`<path>
5982
+ * (deleted)`) is kept as both spellings. A process this user may not inspect (another user's, or a
5983
+ * non-dumpable one) is not seen by either mechanism.
5984
+ * → { ok: true, processes: [{pid, command, cwds}] } | { ok: false, error }
5512
5985
  */
5513
- export function processesInHome(home, io) {
5986
+ function hostProcesses(io) {
5987
+ const rows = typeof io?.procRoot === "string" ? procRows(io.procRoot)
5988
+ : !io?.exec && procReadable().ok ? procRows("/proc")
5989
+ : lsofRows(io);
5990
+ if (!rows.ok) return rows;
5991
+ const processes = [];
5992
+ for (const { pid, ppid, command, cwd } of rows.rows) {
5993
+ if (!pid || pid === process.pid || ppid === process.pid || typeof cwd !== "string") continue;
5994
+ const spellings = cwd.endsWith(" (deleted)") ? [cwd, cwd.slice(0, -" (deleted)".length)] : [cwd];
5995
+ processes.push({ pid, command: command ?? "?", cwds: spellings.map((p) => canonicalHomePath(p)) });
5996
+ }
5997
+ return { ok: true, processes };
5998
+ }
5999
+ /** The processes of a hostProcesses listing that work in `home`, compared in its on-disk spelling. */
6000
+ function processesWorkingIn(processes, home) {
6001
+ const realHome = canonicalHomePath(home);
6002
+ return processes.filter((p) => p.cwds.some((cwd) => cwd === realHome || cwd.startsWith(`${realHome}/`))).map(({ pid, command }) => ({ pid, command }));
6003
+ }
6004
+ /** /proc read as a scan: each numeric entry's `cwd` link, `comm` and `stat` (its ppid is the second
6005
+ * field after the last `)`, which ends the command). A pid that cannot be read (it ended meanwhile,
6006
+ * this user may not inspect it, or any other failure on that one pid) is not seen. A root that
6007
+ * cannot be listed, or one that lists no readable process, is a failed scan, never an empty one. */
6008
+ function procRows(root) {
6009
+ let names;
6010
+ try { names = readdirSync(root); }
6011
+ catch (e) { return { ok: false, error: `${root} cannot be read (${e.code || e.message})` }; }
6012
+ const rows = [];
6013
+ for (const name of names) {
6014
+ if (!/^\d+$/.test(name)) continue;
6015
+ try {
6016
+ const cwd = readlinkSync(join(root, name, "cwd"));
6017
+ const command = readFileSync(join(root, name, "comm"), "utf8").replace(/\n$/, "");
6018
+ const stat = readFileSync(join(root, name, "stat"), "utf8");
6019
+ rows.push({ pid: Number(name), ppid: Number(stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[1]), command, cwd });
6020
+ } catch { /* not seen */ }
6021
+ }
6022
+ // A real /proc always lists at least this process.
6023
+ if (!rows.length) return { ok: false, error: `${root} listed no process` };
6024
+ return { ok: true, rows };
6025
+ }
6026
+ function lsofRows(io) {
5514
6027
  let out;
5515
6028
  try { out = (io?.exec || execFileSync)("lsof", ["-a", "-d", "cwd", "-F", "pRcn", "-w"], { encoding: "utf8", timeout: 20000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); }
5516
6029
  catch (e) {
@@ -5521,7 +6034,7 @@ export function processesInHome(home, io) {
5521
6034
  // listing.
5522
6035
  const completed = e?.status === 1 && e.signal == null && e.code === undefined;
5523
6036
  if (completed && typeof e.stdout === "string") out = e.stdout;
5524
- else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH"
6037
+ else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH; install lsof"
5525
6038
  : e?.code === "ETIMEDOUT" ? "lsof timed out"
5526
6039
  : e?.code === "ENOBUFS" ? "lsof printed more output than the scan reads"
5527
6040
  : e?.signal ? `lsof was ended by ${e.signal}`
@@ -5529,20 +6042,27 @@ export function processesInHome(home, io) {
5529
6042
  }
5530
6043
  // A listing holds at least one process (lsof and its caller are always in it), whichever exit it came with.
5531
6044
  if (!/^p\d+$/m.test(String(out))) return { ok: false, error: "lsof listed no process" };
5532
- const realHome = realPathOrNearest(home);
5533
- const processes = [];
6045
+ const rows = [];
5534
6046
  let cur = {};
5535
6047
  for (const line of String(out).split("\n")) {
5536
6048
  const tag = line[0], value = line.slice(1);
5537
- if (tag === "p") cur = { pid: Number(value) };
6049
+ if (tag === "p") { cur = { pid: Number(value) }; rows.push(cur); }
5538
6050
  else if (tag === "R") cur.ppid = Number(value);
5539
6051
  else if (tag === "c") cur.command = value;
5540
- else if (tag === "n" && cur.pid && cur.pid !== process.pid && cur.ppid !== process.pid) {
5541
- const cwd = realPathOrNearest(value);
5542
- if (cwd === realHome || cwd.startsWith(`${realHome}/`)) processes.push({ pid: cur.pid, command: cur.command ?? "?" });
5543
- }
6052
+ else if (tag === "n") cur.cwd = value;
5544
6053
  }
5545
- return { ok: true, processes };
6054
+ return { ok: true, rows };
6055
+ }
6056
+ /**
6057
+ * The live processes (other than this one and its direct children) whose working directory is
6058
+ * inside `home`, from one scan of the host (hostProcesses: /proc on Linux, else lsof). A pid and a
6059
+ * program name, never an argument list.
6060
+ * → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan could not run, did
6061
+ * not complete or listed no process: a caller must treat that as unknown, never as none).
6062
+ */
6063
+ export function processesInHome(home, io) {
6064
+ const scan = hostProcesses(io);
6065
+ return scan.ok ? { ok: true, processes: processesWorkingIn(scan.processes, home) } : scan;
5546
6066
  }
5547
6067
 
5548
6068
  /**
@@ -5563,7 +6083,7 @@ export function observeSessionWithoutReceipt(home, meta, io) {
5563
6083
  if (!recorded.absent) return recorded;
5564
6084
  const scan = processesInHome(home, io);
5565
6085
  if (!scan.ok) return { absent: false, backend: recorded.backend, note: `could not scan for a process working in this home (${scan.error})` };
5566
- 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` };
6086
+ if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${namedProcesses(scan.processes)}); stop it, then retire` };
5567
6087
  return recorded;
5568
6088
  }
5569
6089
  function recordedSessionAbsence(home, meta, io) {
@@ -5580,11 +6100,19 @@ function recordedSessionAbsence(home, meta, io) {
5580
6100
  return { absent: false, backend: "tmux", note: `tmux could not list ${tmux.socket}: ${String(e.stderr ?? e.message ?? "").trim() || "tmux failed"}` };
5581
6101
  }
5582
6102
  if (rows.some(([s, w]) => s === tmux.session && w === tmux.window)) return { absent: false, backend: "tmux", note: `the recorded window ${where} is still present` };
5583
- const realHome = realPathOrNearest(home);
5584
- const inHome = rows.find(([, , cwd]) => { const p = cwd ? realPathOrNearest(cwd) : ""; return p === realHome || p.startsWith(`${realHome}/`); });
6103
+ // tmux reports each pane's cwd in its on-disk spelling: the home is compared in it too.
6104
+ const realHome = canonicalHomePath(home);
6105
+ const inHome = rows.find(([, , cwd]) => { const p = cwd ? canonicalHomePath(cwd) : ""; return p === realHome || p.startsWith(`${realHome}/`); });
5585
6106
  if (inHome) return { absent: false, backend: "tmux", note: `a tmux pane (${inHome[0]}:${inHome[1]}) on ${tmux.socket} works in this home` };
5586
6107
  return { absent: true, backend: "tmux", note: `no session receipt (a home from before 0.25.9); the recorded window ${where} is gone` };
5587
6108
  }
6109
+ /** K3: quiesce one instance's session and RETAIN everything else — home,
6110
+ * worktree, transcript, launch configuration — so `restart` can bring it back.
6111
+ * Exactly restart's stop half under the same independent endpoint authority
6112
+ * (`instanceSessionTarget`), bounded and never escalated: a harness still
6113
+ * there after the grace is reported still running, nothing is killed harder.
6114
+ * A no-launch or already-idle instance is a no-op that says so. A missing socket
6115
+ * file is idle only when no process works in the home (#624). */
5588
6116
  export function stopInstanceSession(home, o = {}) {
5589
6117
  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
5590
6118
  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");
@@ -5594,7 +6122,12 @@ export function stopInstanceSession(home, o = {}) {
5594
6122
  if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
5595
6123
  let before;
5596
6124
  try { before = inspectSessionTarget(s.target); }
5597
- 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}`); }
6125
+ catch (e) {
6126
+ const absence = tmuxServerAbsence(e);
6127
+ const why = absence === "missing-socket" ? missingSocketUnestablished(tmuxFailure(e, e.message), processesInHome(realHome, o.io)) : null;
6128
+ if (absence && !why) before = { present: false, state: "stopped" };
6129
+ else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${why ?? e.message}`);
6130
+ }
5598
6131
  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 };
5599
6132
  const receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, kill: o.io?.kill, sleep: o.io?.sleep });
5600
6133
  writeJsonAtomic(join(realHome, ".oats-stop.json"), { instance: basename(realHome), at: new Date().toISOString(), stop: receipt, retained: ["home", "work", "transcript", "launch"] });
@@ -6001,7 +6534,16 @@ export function startInstanceSession(home, o = {}) {
6001
6534
  // spawned records no modules, and there is no scope configuration left to
6002
6535
  // re-resolve it against. Retire still works on it.
6003
6536
  if (!isWorkspaceHome(readMeta())) throw preWorkspaceHome(realHome, "nothing was started");
6004
- const lostTmuxServer = tmuxServerLost;
6537
+ // A missing socket file is a stopped server only when no process works in this home (#624): its
6538
+ // check, for a recorded session and for the OATS server lookup. A failed read of a recorded session
6539
+ // is `{ stopped: true }` when its server is gone (or its socket file is missing and that check
6540
+ // passes), else `{ stopped: false, why }`: the check's reason, or null for another failure.
6541
+ const missingSocket = (detail) => missingSocketUnestablished(detail, processesInHome(realHome, rawIo));
6542
+ const lostServer = (e) => {
6543
+ const absence = tmuxServerAbsence(e);
6544
+ const why = absence === "missing-socket" ? missingSocket(tmuxFailure(e, e.message)) : null;
6545
+ return absence && !why ? { stopped: true } : { stopped: false, why };
6546
+ };
6005
6547
  const launchFailure = (error) => {
6006
6548
  // execFileSync errors embed argv (including capability environment) in
6007
6549
  // message; backend stderr can echo it too. Neither belongs in the API.
@@ -6014,13 +6556,13 @@ export function startInstanceSession(home, o = {}) {
6014
6556
  // pending receipt exists for.
6015
6557
  const record = (meta, { id, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom, launchFrom, launchAt, launchDeclared, launchPrompts, launchPromptTarget }, clearPending = true) => {
6016
6558
  checkRoots();
6017
- const baselinePath = retirementBaselinePath(realHome);
6559
+ const baselinePath = findRetirementBaseline(realHome);
6018
6560
  let baseline;
6019
6561
  try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) {
6020
- if (e.code === "ENOENT") throw missingSessionReceipt(realHome, baselinePath);
6562
+ if (e.code === "ENOENT") throw missingSessionReceipt(realHome);
6021
6563
  throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`);
6022
6564
  }
6023
- if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== realHome || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
6565
+ if (baseline.version !== RETIRE_BASELINE_VERSION || !receiptRecordsHome(baseline, canonicalHomePath(realHome)) || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
6024
6566
  baseline.runtime = { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
6025
6567
  writeJsonAtomic(baselinePath, baseline, 0o600);
6026
6568
  if (o.io?.failBeforeMetadataWrite && reused !== "adopted") throw new Error("injected metadata write failure"); // the write after THIS start's allocation
@@ -6077,8 +6619,9 @@ export function startInstanceSession(home, o = {}) {
6077
6619
  checkRoots();
6078
6620
  try { st = inspectSessionTarget(pending.target, o.io); }
6079
6621
  catch (e) {
6080
- if (lostTmuxServer(e)) st = { present: false, state: "stopped" };
6081
- 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`);
6622
+ const lost = lostServer(e);
6623
+ if (lost.stopped) st = { present: false, state: "stopped" };
6624
+ 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`);
6082
6625
  }
6083
6626
  // A launch may still consist entirely of shells (startup files, a
6084
6627
  // shell-script harness). Only its own completion marker proves this
@@ -6154,18 +6697,19 @@ export function startInstanceSession(home, o = {}) {
6154
6697
  const planSession = receipt.target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
6155
6698
  let sessionPlanRead;
6156
6699
  const sessionPlan = () => {
6157
- if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io) }; } catch (e) { sessionPlanRead = { error: e }; } }
6700
+ if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io, { missingSocket }) }; } catch (e) { sessionPlanRead = { error: e }; } }
6158
6701
  if (sessionPlanRead.error) throw sessionPlanRead.error;
6159
6702
  return sessionPlanRead.plan;
6160
6703
  };
6161
6704
  // The recorded target, observed once: by the plan's lookup, which must know whether the pane will
6162
- // be reused before it chooses where to look, or by the gate below. A lost server is a stopped one;
6163
- // any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does not decide it.
6705
+ // be reused before it chooses where to look, or by the gate below. A lost server is a stopped one
6706
+ // (lostServer); any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does
6707
+ // not decide it.
6164
6708
  let recordedRead;
6165
6709
  const recordedState = () => {
6166
6710
  if (!recordedRead) {
6167
6711
  try { recordedRead = { state: receipt.target ? inspectSessionTarget(receipt.target, o.io) : { present: false, state: "not-launched" } }; }
6168
- catch (e) { recordedRead = lostTmuxServer(e) ? { state: { present: false, state: "stopped" } } : { error: e }; }
6712
+ catch (e) { const lost = lostServer(e); recordedRead = lost.stopped ? { state: { present: false, state: "stopped" } } : { error: lost.why ? new Error(lost.why) : e }; }
6169
6713
  }
6170
6714
  return recordedRead;
6171
6715
  };
@@ -6195,7 +6739,7 @@ export function startInstanceSession(home, o = {}) {
6195
6739
  const recorded = recordedState();
6196
6740
  if (reusable(recorded.state)) return panePath(receipt.target.socket, receipt.target.session, o.io, realHome);
6197
6741
  if (recorded.error) return undefined; // the gate refuses below; the lookup does not decide it
6198
- const preview = planOatsTmuxSession(planSession, o.io, { preview: true });
6742
+ const preview = planOatsTmuxSession(planSession, o.io, { preview: true, missingSocket });
6199
6743
  if (!preview || preview.server) return expectedPanePath(preview, planSession, o.io, realHome);
6200
6744
  try { return expectedPanePath(sessionPlan(), planSession, o.io, realHome); } catch (e) { if (oatsCoded(e)) return undefined; throw e; }
6201
6745
  };
@@ -6304,7 +6848,12 @@ export function startInstanceSession(home, o = {}) {
6304
6848
  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);
6305
6849
  appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
6306
6850
  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")}`);
6307
- 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}`); }
6851
+ try { state = inspectSessionTarget(target, o.io); }
6852
+ catch (e) {
6853
+ const lost = lostServer(e);
6854
+ if (lost.stopped) state = { present: false, state: "stopped" };
6855
+ 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)}`);
6856
+ }
6308
6857
  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`);
6309
6858
  }
6310
6859
  // The kernel that launches the harness is the one the agent's plain `oats` runs.
@@ -6352,7 +6901,7 @@ export function startInstanceSession(home, o = {}) {
6352
6901
  // A replacement window (never launched, recorded window gone, recorded server gone) is created
6353
6902
  // on the OATS server, wherever the home was recorded: one socket from here to the record.
6354
6903
  const recordedSocket = socket ? resolve(socket) : null;
6355
- socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan);
6904
+ socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan, missingSocket);
6356
6905
  if (lookAgain(() => panePath(socket, session, o.io, realHome))) { planExtra.launch = launchPlan.recipe; windowCmd = windowCommand(); }
6357
6906
  let names;
6358
6907
  try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
@@ -6431,7 +6980,7 @@ export function startInstanceSession(home, o = {}) {
6431
6980
  * decision: not provable. */
6432
6981
  function inspectGit(repo, args, { absent = false, env } = {}) {
6433
6982
  try {
6434
- return execFileSync("git", ["-C", repo, ...args], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, ...(env ? { env: { ...process.env, ...env } } : {}) }).toString("latin1");
6983
+ return retireGit(repo, args, { env }).toString("latin1");
6435
6984
  } catch (e) {
6436
6985
  const detail = String(e.stderr ?? "").trim();
6437
6986
  if (absent && e.status === 1 && !detail) return null;
@@ -6453,23 +7002,20 @@ function inspectedEntryExists(path) {
6453
7002
  /** How the recovery copier resolves what it reads from a repository, read by
6454
7003
  * the copier and by the comparison alike (repositoryGitState), so that the
6455
7004
  * comparison holds the files the copy carries, found where the copy finds
6456
- * them. Git's answer decoded as UTF-8 and trimmed of white space at both
6457
- * ends: a path that ends in white space is read without it, which Git itself
6458
- * does not do. That is the copier's own reading, kept as it is; a copy of
6459
- * the file Git reads would be a change to the copier.
7005
+ * them. Git's answer decoded as UTF-8, exactly as Git printed it but for the
7006
+ * one line feed that ends it: a path that begins or ends in white space is
7007
+ * the path Git reads, so the copier reads the file Git reads
7008
+ * (awebai/oats#647).
6460
7009
  * A worktree whose `core.worktree` (per-worktree configuration) names a
6461
- * directory other than `<home>/work` is outside what the retire is
6462
- * specified for: Git's status then describes that other directory while
6463
- * the retire reads, copies and removes `<home>/work`. copierExcludesFile
6464
- * resolves the excludes base the copier's way for it all the same; no test
6465
- * pins it. */
6466
- const copierGitText = (repo, args) => execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
7010
+ * directory other than `<home>/work` never gets here: each inspection
7011
+ * refuses it first (assertWorktreeTopLevel, awebai/oats#648). */
7012
+ const copierGitText = (repo, args) => retireGit(repo, args, { encoding: "utf8" }).replace(/\n$/, "");
6467
7013
  /** The Git directory the copier copies the index and the operation entries from. */
6468
7014
  const copierGitDir = (repo) => copierGitText(repo, ["rev-parse", "--absolute-git-dir"]);
6469
7015
  /** The common directory the copier reads info/exclude, info/attributes and the stash's log from. */
6470
7016
  const copierCommonDir = (repo) => copierGitText(repo, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
6471
7017
  /** The file the copier reads for core.excludesFile; null when it reads none:
6472
- * the value is unset, cannot be read, or is only white space. */
7018
+ * the value is unset, empty or cannot be read. */
6473
7019
  function copierExcludesFile(repo) {
6474
7020
  let value = "";
6475
7021
  try { value = copierGitText(repo, ["config", "--path", "--get", "core.excludesFile"]); } catch { /* unset: Git's default applies to both repositories alike */ }
@@ -6585,9 +7131,8 @@ function repositoryGitState(repo, { status, cloneSource } = {}) {
6585
7131
  status: (status ?? worktreeStatusBytes(repo)).toString("latin1"),
6586
7132
  head: head.ref === null ? null : head.ref.toString("latin1"),
6587
7133
  commit: valueOf("rev-parse", "--verify", "--quiet", "HEAD"),
6588
- // The index the copier copies (copierGitDir), read as an index: Git's
6589
- // own, at a path that differs from it only in white space, is not what
6590
- // the copy carries. One that is not there lists nothing.
7134
+ // The index the copier copies (copierGitDir), named explicitly
7135
+ // (GIT_INDEX_FILE), read as an index. One that is not there lists nothing.
6591
7136
  index: inspectGit(repo, ["ls-files", "-s", "-v", "-z"], { env: { GIT_INDEX_FILE: join(copierGit, "index") } }),
6592
7137
  resolveUndo: inspectGit(repo, ["ls-files", "--resolve-undo", "-z"], { env: { GIT_INDEX_FILE: join(copierGit, "index") } }),
6593
7138
  indexMode: modeOf(join(copierGit, "index")),
@@ -6610,10 +7155,11 @@ function repositoryGitState(repo, { status, cloneSource } = {}) {
6610
7155
  * nestedGitRoots, and (`inner`) the repositories inside those. A recovery
6611
7156
  * rebuilds a nested repository from a clone; one inside it comes along as
6612
7157
  * plain files, its Git directory included, which the copy's verification
6613
- * leaves out and which no read-only Git command can describe whole.
7158
+ * holds as bytes (worktreeGitPaths) and which no read-only Git command can
7159
+ * describe whole.
6614
7160
  * A directory whose `.git` cannot be tested (inspectedEntryExists throws),
6615
7161
  * or is a dangling symbolic link (a link `stat` cannot follow, which the
6616
- * copy carries as a link and the digests pass over by its name), is listed
7162
+ * copy carries as a link and the copy's verification holds), is listed
6617
7163
  * as { path, unknown: true }: it is not taken for a directory without a
6618
7164
  * repository, and not for a repository either. So every directory with a
6619
7165
  * `.git` entry of any kind is listed: a directory, a file, a link to
@@ -6625,17 +7171,19 @@ function repositoriesUnder(work) {
6625
7171
  try { lstatSync(path); return true; }
6626
7172
  catch (e) {
6627
7173
  if (e.code === "ENOENT") return false;
6628
- throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path}: ${e.message}`);
7174
+ throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path.toString()}: ${e.message}`);
6629
7175
  }
6630
7176
  };
7177
+ // Names are read as bytes (`path` is a Buffer), so a directory whose name
7178
+ // is not UTF-8 is walked like any other.
6631
7179
  const walk = (dir, inner) => {
6632
- for (const e of readdirSync(dir, { withFileTypes: true })) {
6633
- if (!e.isDirectory() || e.isSymbolicLink?.() || e.name === ".git") continue;
6634
- const path = join(dir, e.name);
7180
+ for (const e of entriesAsBytes(dir)) {
7181
+ if (!e.isDirectory() || e.isSymbolicLink() || e.name.equals(GIT_NAME)) continue;
7182
+ const path = joinBytes(dir, e.name);
6635
7183
  let repository = false;
6636
7184
  try {
6637
- repository = inspectedEntryExists(join(path, ".git"));
6638
- if (!repository && entryIsThere(join(path, ".git"))) out.push({ path, unknown: true });
7185
+ repository = inspectedEntryExists(joinBytes(path, GIT_NAME));
7186
+ if (!repository && entryIsThere(joinBytes(path, GIT_NAME))) out.push({ path, unknown: true });
6639
7187
  } catch (e) {
6640
7188
  if (e?.code !== "E_WORK_INSPECTION_FAILED") throw e;
6641
7189
  out.push({ path, unknown: true });
@@ -6644,7 +7192,7 @@ function repositoriesUnder(work) {
6644
7192
  walk(path, inner || repository);
6645
7193
  }
6646
7194
  };
6647
- walk(work, false);
7195
+ walk(pathBytes(work), false);
6648
7196
  return out;
6649
7197
  }
6650
7198
  /** The work state of a worktree instance, without the bytes of its files: the
@@ -6655,12 +7203,28 @@ function repositoriesUnder(work) {
6655
7203
  function worktreeGitState(work, status, cloneSource) { // `status`: the worktree's status bytes
6656
7204
  return JSON.stringify({ worktree: repositoryGitState(work, { status, cloneSource }) });
6657
7205
  }
6658
- /** The bytes of a worktree, Git metadata left out, as their exact digest: what a work copy is verified
6659
- * with, and what proves that the hooks left the files as they were. One full read. Kept nowhere. */
6660
- const worktreeBytes = (work) => exactTreeDigest(work, { excludeRoot: new Set([".git"]), excludeGitMetadata: true, children: true });
7206
+ /** The `.git` entries a worktree's bytes leave out, as paths under it in
7207
+ * bytes: the worktree's own, and that of each repository the copier rebuilds
7208
+ * from a clone (nestedGitRoots, materializeNestedRepositories). Exact paths,
7209
+ * never a name: any other entry named `.git` is bytes like any other
7210
+ * (awebai/oats#663), such as a dangling `.git` link, or the `.git` of a
7211
+ * repository inside a nested one, which the copy carries as plain files.
7212
+ * Read from the source and used for the source and its copy alike: a
7213
+ * rebuilt `.git` is a directory in the copy where the source's can be a
7214
+ * file, and the path covers both. */
7215
+ function worktreeGitPaths(work) {
7216
+ const under = pathBytes(work).length + PATH_SEPARATOR_BYTES.length;
7217
+ return [GIT_NAME, ...nestedGitRoots(work).map((root) => joinBytes(root.subarray(under), GIT_NAME))];
7218
+ }
7219
+ /** The bytes of a worktree, its Git directories (`gitPaths`, worktreeGitPaths of
7220
+ * the source) left out, as their exact digest: what a work copy is verified
7221
+ * with, and what proves that the hooks left the files as they were. One full
7222
+ * read. Kept nowhere. */
7223
+ const worktreeBytes = (work, gitPaths = worktreeGitPaths(work)) => exactTreeDigest(work, { excludePaths: gitPaths, children: true });
6661
7224
  /** The byte part of an observed worktree's work state, read at most once per
6662
- * observation and kept on it; undefined where the observation saw no
6663
- * worktree. An inspection never reads it. The retire reads it before it
7225
+ * observation and kept on it with the Git directories it leaves out
7226
+ * (`workGitPaths`, for the copy's verification); undefined where the
7227
+ * observation saw no worktree. An inspection never reads it. The retire reads it before it
6664
7228
  * writes the pre-hook recovery, the copy's verification uses it (so a pass
6665
7229
  * that copies the work costs no extra read), and so does the proof that the
6666
7230
  * retire hooks left the work as it was (movedByHooks). */
@@ -6668,7 +7232,11 @@ function observedWorkBytes(observation) {
6668
7232
  if (observation.worktree && observation.workBytes === undefined) {
6669
7233
  // A read that fails is an inspection that failed, with its code: where the
6670
7234
  // retire reads before it writes, nothing else gives the failure one.
6671
- try { observation.workBytes = worktreeBytes(observation.work); }
7235
+ try {
7236
+ const gitPaths = worktreeGitPaths(observation.work);
7237
+ observation.workBytes = worktreeBytes(observation.work, gitPaths);
7238
+ observation.workGitPaths = gitPaths;
7239
+ }
6672
7240
  catch (e) {
6673
7241
  if (e?.code === "E_WORK_INSPECTION_FAILED") throw e;
6674
7242
  throw oatsError("E_WORK_INSPECTION_FAILED", `could not read the worktree at ${observation.work}: ${e.message}`);
@@ -6680,8 +7248,8 @@ function observedWorkBytes(observation) {
6680
7248
  * one after → { home, work }. Nothing when the later observation has nothing
6681
7249
  * to preserve. The home moved when its exact digest did: that is its bytes,
6682
7250
  * `instance.json` as it is. (The stored digest, which a baseline is compared
6683
- * with, leaves the kernel's own fields of that file out and frames entries
6684
- * without lengths; it reads alike some homes that differ.)
7251
+ * with, leaves the kernel's own fields of that file out and passes over the
7252
+ * kernel's receipts, so it reads alike some homes that differ.)
6685
7253
  * The work moved unless it is proven unchanged: a directory by its bytes
6686
7254
  * (its exact digest); a worktree by its Git state and, only when that is
6687
7255
  * equal, by its bytes. A status text or a class list alone proves nothing: a
@@ -6698,11 +7266,30 @@ function movedByHooks(before, after) {
6698
7266
  return { home, work };
6699
7267
  }
6700
7268
 
6701
- function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, orphanedWork = false } = {}) {
7269
+ /** The check made before a worktree's status is trusted (awebai/oats#648):
7270
+ * Git's top level for the worktree at `work` is `work` itself, both in
7271
+ * their canonical spelling (canonicalHomePath, so a path reached through a
7272
+ * link, or spelled in another letter case on a case-insensitive
7273
+ * filesystem, is the same path). A per-worktree `core.worktree` can name
7274
+ * another directory: Git's status then describes that one, while the
7275
+ * retire reads, copies and removes `work`. That, and a top level that
7276
+ * cannot be read, throws E_WORK_INSPECTION_FAILED with `disclosure` (what
7277
+ * the retire has and has not done by then) as its last sentence. */
7278
+ function assertWorktreeTopLevel(work, disclosure) {
7279
+ const refuse = (why) => oatsError("E_WORK_INSPECTION_FAILED", `${why}, so its Git status describes another directory than the one the retire reads, copies and removes.${disclosure ? ` ${disclosure}.` : ""}`);
7280
+ let top;
7281
+ try { top = retireGit(work, ["rev-parse", "--show-toplevel"]).toString("utf8").replace(/\n$/, ""); }
7282
+ catch (e) { throw refuse(`could not read the top level of the worktree at ${work} (${String(e.stderr ?? e.message ?? "").trim() || "git rev-parse failed"})`); }
7283
+ if (!top || canonicalHomePath(top) !== canonicalHomePath(work)) {
7284
+ throw refuse(`Git reads the worktree at ${work} as the directory ${top || "(none)"} (its core.worktree names another directory)`);
7285
+ }
7286
+ }
7287
+
7288
+ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, orphanedWork = false, disclosure } = {}) {
6702
7289
  if (directory) assertDirectoryRoots(home);
6703
7290
  const classes = [];
6704
7291
  let baseline;
6705
- const path = retirementBaselinePath(home);
7292
+ const path = findRetirementBaseline(home);
6706
7293
  try {
6707
7294
  if (existsSync(path)) baseline = JSON.parse(readFileSync(path, "utf8"));
6708
7295
  } catch (e) {
@@ -6718,12 +7305,15 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
6718
7305
  // One walk of the home, two digests: the stored one for the comparison with
6719
7306
  // the baseline, which must not see the kernel's own fields of instance.json,
6720
7307
  // and the exact one for the comparison after the hooks, which must see
6721
- // every byte.
7308
+ // every byte. The stored one is in the baseline's digest version; a
7309
+ // version this kernel does not take matches nothing, and the walk is then
7310
+ // the one version 2 takes, for the exact digest alone.
7311
+ const digestVersion = baselineDigestVersion(baseline);
6722
7312
  let homeDigests;
6723
- const fingerprintHome = () => (homeDigests ??= fingerprintTrees(home, { excludeRoot: homeExclusions.excludeRoot, instanceHome: true, exact: true, children: true })).stored;
7313
+ const fingerprintHome = () => (homeDigests ??= fingerprintTrees(home, { excludeRoot: homeExclusions.excludeRoot, instanceHome: true, digestVersion: digestVersion ?? BASELINE_DIGEST_VERSION, exact: true, children: true })).stored;
6724
7314
  if (!baselineValid) {
6725
7315
  classes.push("unknown instance-home provenance");
6726
- } else if (baseline.homeFingerprint !== fingerprintHome()) {
7316
+ } else if (digestVersion === undefined || baseline.homeFingerprint !== fingerprintHome()) {
6727
7317
  classes.push("changed instance-home bytes");
6728
7318
  }
6729
7319
  // A mutable mode must not turn owned directory bytes into an excluded shared
@@ -6740,6 +7330,8 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
6740
7330
  // For a quarantine retry whose worktree is gone, whether the recorded branch
6741
7331
  // is still there to copy. Every other retire takes it to be there.
6742
7332
  const branchExists = !directory && recordedBranch && !existsSync(work) ? recordedBranchExists(recordedBranch.repo, recordedBranch.branch) : true;
7333
+ // Before anything of the worktree is read: its status describes it, not another directory.
7334
+ if (!directory && isWorktree && existsSync(work)) assertWorktreeTopLevel(work, disclosure);
6743
7335
  // A retire that will remove the worktree asks whether a ref that outlives it
6744
7336
  // reaches its commit. `head` is kept for the check before the removal.
6745
7337
  const unreached = worktreeRemoval?.removes && worktreeRemoval.repo && !directory && isWorktree && existsSync(work) ? worktreeCommitUnreached(worktreeRemoval.repo, work) : undefined;
@@ -6747,14 +7339,23 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
6747
7339
  const worktree = isWorktree && existsSync(work);
6748
7340
  let gitState = "", workProvable = true;
6749
7341
  if (worktree) {
6750
- // Read once, as bytes. The bytes go into the Git state; the rows, the
6751
- // classes and the comparison with the spawn baseline read them as text.
7342
+ // Read once, as bytes. The bytes go into the Git state and into the
7343
+ // comparison with the spawn baseline (its legacy digest reads them as
7344
+ // text); the rows and the classes read them as text.
6752
7345
  const statusBytes = worktreeStatusBytes(work);
6753
7346
  const status = statusBytes.toString("utf8");
6754
7347
  const rows = status.split("\0").filter(Boolean);
6755
7348
  if (rows.some((row) => !row.startsWith("?? ") && !row.startsWith("!! "))) classes.push("tracked or index worktree state");
6756
7349
  const disposableRoots = baseline?.disposableReceipts?.map((r) => r.root) || [];
6757
- if (!baseline || baseline.generatedWorkFingerprint !== generatedWorkFingerprint(work, status, disposableRoots)) classes.push("untracked or ignored worktree bytes");
7350
+ // A path the digest cannot inspect refuses, with what this retire has
7351
+ // and has not done by now, as the other refusals of an inspection do.
7352
+ let generated;
7353
+ try { generated = baseline && digestVersion !== undefined ? generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposableRoots) : undefined; }
7354
+ catch (e) {
7355
+ if (e?.code !== "E_WORK_INSPECTION_FAILED") throw e;
7356
+ throw oatsError(e.code, `${e.message}.${disclosure ? ` ${disclosure}.` : ""}`);
7357
+ }
7358
+ if (generated === undefined || baseline.generatedWorkFingerprint !== generated) classes.push("untracked or ignored worktree bytes");
6758
7359
  const found = repositoriesUnder(work);
6759
7360
  if (found.some((r) => !r.unknown)) classes.push("nested repository state");
6760
7361
  // The one place where a read of the Git state that fails is decided. It
@@ -6805,15 +7406,29 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
6805
7406
  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, extraTrees, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
6806
7407
  }
6807
7408
 
7409
+ /** Copy the entries of `src` into `dest` (created), names as bytes, except
7410
+ * the top-level names in `excludeRoot`, tested as text the way the digests
7411
+ * test them (fingerprintTrees). */
6808
7412
  function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
6809
7413
  mkdirSync(dest, { recursive: true });
6810
- for (const e of readdirSync(src, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
6811
- if (excludeRoot.has(e.name)) continue;
6812
- copyTreeSafe(join(src, e.name), join(dest, e.name));
7414
+ for (const e of entriesAsBytes(src)) {
7415
+ if (excludeRoot.has(e.name.toString("utf8"))) continue;
7416
+ copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name));
6813
7417
  }
6814
7418
  }
7419
+ /** Make the top level of `dest`, a fresh clone, the top level of `source`,
7420
+ * names as bytes: every entry of `dest` but its `.git` is removed, then
7421
+ * every entry of `source` but its `.git` is copied (copyTreeSafe). A mirror,
7422
+ * not an overlay: a tracked top-level entry the source deleted or renamed is
7423
+ * not left in the copy as the clone checked it out (awebai/oats#656). The
7424
+ * `.git` of `dest` is never touched: the copy's Git state is restored
7425
+ * separately (restoreStandaloneGitState). */
7426
+ function mirrorTopLevel(source, dest) {
7427
+ for (const e of entriesAsBytes(dest)) if (!e.name.equals(GIT_NAME)) rmSync(joinBytes(dest, e.name), { recursive: true, force: true });
7428
+ for (const e of entriesAsBytes(source)) if (!e.name.equals(GIT_NAME)) copyTreeSafe(joinBytes(source, e.name), joinBytes(dest, e.name));
7429
+ }
6815
7430
 
6816
- const RECOVERABLE_GIT_ADMIN = [
7431
+ export const RECOVERABLE_GIT_ADMIN = [
6817
7432
  "MERGE_HEAD", "MERGE_MSG", "AUTO_MERGE", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD",
6818
7433
  "BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
6819
7434
  ];
@@ -6860,7 +7475,7 @@ function copiedGitPathDigest(entry, at) {
6860
7475
  * `cat-file --batch-check` process. */
6861
7476
  export function missingGitObjects(repo, oids) {
6862
7477
  if (!oids.length) return [];
6863
- const out = execFileSync("git", ["-C", repo, "cat-file", "--batch-check=%(objectname) %(objecttype)"], { input: oids.join("\n") + "\n", encoding: "utf8", maxBuffer: GIT_MAX_BUFFER });
7478
+ const out = retireGit(repo, ["cat-file", "--batch-check=%(objectname) %(objecttype)"], { input: oids.join("\n") + "\n", encoding: "utf8" });
6864
7479
  const missing = [];
6865
7480
  for (const line of out.split("\n")) {
6866
7481
  if (!line.endsWith(" missing")) continue;
@@ -6869,31 +7484,95 @@ export function missingGitObjects(repo, oids) {
6869
7484
  return missing;
6870
7485
  }
6871
7486
 
7487
+ /** A fetch into a recovery clone from the repository it copies. Protocol
7488
+ * version 2, whatever the user's configuration says: its upload-pack serves
7489
+ * an object id the source has although no ref advertises it, which is how
7490
+ * the copier fetches a detached HEAD and the commits only a log names. A
7491
+ * client setting; it runs nothing. */
7492
+ function copierFetch(recovered, source, refspecs, { input } = {}) {
7493
+ retireGit(recovered, ["-c", "protocol.version=2", "fetch", "--quiet", "--no-tags", source, ...refspecs], input === undefined ? {} : { input });
7494
+ }
7495
+
7496
+ /** The commits a reflog file names: the new object id of each entry, which is
7497
+ * what `git log -g` shows for it, the zero id left out. A file that is not
7498
+ * there names none. Read from the copy of the file, so that what is proven
7499
+ * is what the copy carries. */
7500
+ function reflogCommits(file) {
7501
+ if (!existsSync(file)) return [];
7502
+ const out = [];
7503
+ for (const line of readFileSync(file, "latin1").split("\n")) {
7504
+ const m = /^[0-9a-f]{40}(?:[0-9a-f]{24})? ([0-9a-f]{40}(?:[0-9a-f]{24})?) /.exec(line);
7505
+ if (m && !/^0+$/.test(m[1])) out.push(m[1]);
7506
+ }
7507
+ return out;
7508
+ }
7509
+
7510
+ /** The blobs an index listing names (`git ls-files --stage -z` or
7511
+ * `--resolve-undo -z`): rows `<mode> <oid> <stage>\t<path>`. Gitlink rows
7512
+ * (mode 160000) name commits of nested repositories, which
7513
+ * materializeNestedRepositories restores; they and the zero id are never
7514
+ * blobs here. */
7515
+ function indexBlobs(rows) {
7516
+ const out = [];
7517
+ for (const row of rows.toString("latin1").split("\0")) {
7518
+ const m = /^(\d+) ([0-9a-f]+) \d\t/.exec(row);
7519
+ if (m && m[1] !== "160000" && !/^0+$/.test(m[2])) out.push(m[2]);
7520
+ }
7521
+ return out;
7522
+ }
7523
+
7524
+ /** The one step that makes a recovery copy hold every object the Git
7525
+ * metadata it carries names (awebai/oats#654, #655, #657): measure, repair,
7526
+ * re-measure. One `cat-file --batch-check` asks which of the named objects
7527
+ * the copy lacks; the missing commits are fetched from `source` by id (one
7528
+ * fetch, with everything they reach), the missing blobs, which can be in no
7529
+ * commit (staged content, a resolved conflict's sides), are copied by
7530
+ * content (`cat-file blob` → `hash-object -w`); then the whole set is
7531
+ * checked again. A fetch or a read that fails is not the failure itself:
7532
+ * whatever is still missing after the repair is, named by its id, and the
7533
+ * copy is refused (E_WORK_PRESERVATION_FAILED). That covers an object the
7534
+ * source itself lacks, which GIT_NO_LAZY_FETCH keeps the copier from
7535
+ * fetching from a promisor remote. */
7536
+ function carryNamedObjects(source, recovered, { commits = [], blobs = [] }) {
7537
+ const named = [...new Set([...commits, ...blobs])];
7538
+ if (!named.length) return;
7539
+ const missing = new Set(missingGitObjects(recovered, named));
7540
+ const fetch = [...new Set(commits)].filter((oid) => missing.has(oid));
7541
+ if (fetch.length) {
7542
+ try { copierFetch(recovered, source, ["--stdin"], { input: fetch.join("\n") + "\n" }); }
7543
+ catch { /* the re-measure names what the fetch did not bring */ }
7544
+ }
7545
+ for (const oid of new Set(blobs)) {
7546
+ if (!missing.has(oid)) continue;
7547
+ let blob;
7548
+ try { blob = retireGit(source, ["cat-file", "blob", oid]); }
7549
+ catch { continue; /* the re-measure names it */ }
7550
+ const restored = retireGit(recovered, ["hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" }).trim();
7551
+ if (restored !== oid) throw new Error(`recovered Git object ${restored} did not match source ${oid}`);
7552
+ }
7553
+ const stillMissing = missingGitObjects(recovered, named);
7554
+ if (stillMissing.length) {
7555
+ const more = stillMissing.length > 3 ? ` and ${stillMissing.length - 3} more` : "";
7556
+ throw new Error(`the recovery lacks ${stillMissing.length} Git object(s) that its copied Git metadata names, and ${source} could not supply them: ${stillMissing.slice(0, 3).join(", ")}${more}`);
7557
+ }
7558
+ }
7559
+
6872
7560
  function restoreStandaloneGitState(sourceWork, recoveredRepo) {
6873
7561
  const sourceGit = copierGitDir(sourceWork);
6874
7562
  const recoveredGit = join(recoveredRepo, ".git");
6875
- const indexRows = execFileSync("git", ["-C", sourceWork, "ls-files", "--stage", "-z"], { maxBuffer: GIT_MAX_BUFFER });
6876
- // The staged blobs the recovered index will point at. The clone already
6877
- // holds every blob reachable from a commit; only content that is staged but
6878
- // never committed is missing, so ask once which objects the recovered
6879
- // repository lacks (one process for the whole index) and copy only those.
6880
- // Copying every row cost two Git processes per index entry: a clean 9,500
6881
- // file tree took ~19,000 launches and looked like a hang. Gitlink rows
6882
- // (mode 160000) name commits of nested repositories, which
6883
- // materializeNestedRepositories restores; they are never blobs here.
6884
- const staged = new Set();
6885
- for (const row of indexRows.toString("utf8").split("\0").filter(Boolean)) {
6886
- const match = row.match(/^(\d+) ([0-9a-f]+) \d+\t/);
6887
- if (!match || match[1] === "160000") continue;
6888
- staged.add(match[2]);
6889
- }
6890
- for (const oid of missingGitObjects(recoveredRepo, [...staged])) {
6891
- const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", oid], { maxBuffer: GIT_MAX_BUFFER });
6892
- const restored = execFileSync("git", ["-C", recoveredRepo, "hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
6893
- if (restored !== oid) throw new Error(`recovered Git object ${restored} did not match source ${oid}`);
6894
- }
6895
- const stillMissing = missingGitObjects(recoveredRepo, [...staged]);
6896
- if (stillMissing.length) throw new Error(`recovered repository lacks ${stillMissing.length} staged object(s) after restore: ${stillMissing.slice(0, 3).join(", ")}`);
7563
+ // The blobs the copied index names, read from the index file the copier
7564
+ // copies (awebai/oats#647), not from Git's own idea of the index: its
7565
+ // staged entries and its resolve-undo records (awebai/oats#655). The clone
7566
+ // already holds every blob reachable from a commit; carryNamedObjects asks
7567
+ // once which the copy lacks and copies only those. Copying every row cost
7568
+ // two Git processes per index entry: a clean 9,500 file tree took ~19,000
7569
+ // launches and looked like a hang.
7570
+ const index = { env: { GIT_INDEX_FILE: join(sourceGit, "index") } };
7571
+ const blobs = [
7572
+ ...indexBlobs(retireGit(sourceWork, ["ls-files", "--stage", "-z"], index)),
7573
+ ...indexBlobs(retireGit(sourceWork, ["ls-files", "--resolve-undo", "-z"], index)),
7574
+ ];
7575
+ carryNamedObjects(sourceWork, recoveredRepo, { blobs });
6897
7576
  // The index is the selection's one exception (COPIED_GIT_PATHS): copied
6898
7577
  // whole, compared by its entries, resolve-undo records and mode.
6899
7578
  copyFileSync(join(sourceGit, "index"), join(recoveredGit, "index"));
@@ -6940,14 +7619,14 @@ const STATUS_CONFIG = ["core.fileMode", "core.ignoreCase", "core.precomposeUnico
6940
7619
  * carried: [{ kind: "config", key, value } | { kind: "info/attributes", path }]. */
6941
7620
  function carryStatusConfig(sourceWork, recoveredRepo) {
6942
7621
  const get = (repo, key) => {
6943
- try { return execFileSync("git", ["-C", repo, "config", "--get", key], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).replace(/\n$/, ""); }
7622
+ try { return retireGit(repo, ["config", "--get", key], { encoding: "utf8" }).replace(/\n$/, ""); }
6944
7623
  catch (e) { if (e.status === 1) return null; throw e; }
6945
7624
  };
6946
7625
  const carried = [];
6947
7626
  for (const key of STATUS_CONFIG) {
6948
7627
  const value = get(sourceWork, key);
6949
7628
  if (value === get(recoveredRepo, key)) continue;
6950
- execFileSync("git", ["-C", recoveredRepo, "config", "--local", ...(value === null ? ["--unset-all", key] : [key, value])], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
7629
+ retireGit(recoveredRepo, ["config", "--local", ...(value === null ? ["--unset-all", key] : [key, value])]);
6951
7630
  carried.push({ kind: "config", key, value });
6952
7631
  }
6953
7632
  const common = copierCommonDir(sourceWork);
@@ -6961,71 +7640,161 @@ function carryStatusConfig(sourceWork, recoveredRepo) {
6961
7640
  return carried;
6962
7641
  }
6963
7642
 
6964
- function detachRecoveryClone(source, recovered) {
7643
+ /** Make a recovery clone stand on its own: give it the source's stash (the
7644
+ * ref, its log, and every commit the copied log names: awebai/oats#654),
7645
+ * prove it holds those and `commits` (what the caller's carried metadata
7646
+ * names) with carryNamedObjects, then remove the remote it was cloned from. */
7647
+ function detachRecoveryClone(source, recovered, commits = []) {
7648
+ const named = [...commits];
6965
7649
  let stash;
6966
- try { stash = execFileSync("git", ["-C", source, "rev-parse", "--verify", "--quiet", "refs/stash"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER }).trim(); }
7650
+ try { stash = retireGit(source, ["rev-parse", "--verify", "--quiet", "refs/stash"], { encoding: "utf8" }).trim(); }
6967
7651
  catch { stash = undefined; }
6968
7652
  if (stash) {
6969
- execFileSync("git", ["-C", recovered, "fetch", "--quiet", source, "refs/stash:refs/stash"], { maxBuffer: GIT_MAX_BUFFER });
7653
+ copierFetch(recovered, source, ["refs/stash:refs/stash"]);
7654
+ named.push(stash);
6970
7655
  const sourceCommon = copierCommonDir(source);
6971
7656
  const stashLog = copiedGitPath(GIT_STASH_LOG, null, sourceCommon);
6972
7657
  if (existsSync(stashLog)) {
6973
7658
  const recoveredLog = copiedGitPath(GIT_STASH_LOG, null, join(recovered, ".git"));
6974
7659
  mkdirSync(dirname(recoveredLog), { recursive: true });
6975
7660
  copyFileSync(stashLog, recoveredLog);
7661
+ named.push(...reflogCommits(recoveredLog));
6976
7662
  }
6977
7663
  }
6978
- try { execFileSync("git", ["-C", recovered, "remote", "remove", "origin"], { stdio: "ignore" , maxBuffer: GIT_MAX_BUFFER }); } catch { /* no remote is already independent */ }
6979
- }
6980
-
7664
+ carryNamedObjects(source, recovered, { commits: named });
7665
+ try { retireGit(recovered, ["remote", "remove", "origin"]); } catch { /* no remote is already independent */ }
7666
+ }
7667
+
7668
+ /** A path under a Git directory for a ref name read as bytes: a branch name
7669
+ * need not be UTF-8, and the file Git keeps for it is named by its bytes. */
7670
+ const gitPathOf = (dir, ...parts) => Buffer.concat([Buffer.from(`${dir}${sep}`), ...parts]);
7671
+ const parentOf = (path) => path.subarray(0, path.lastIndexOf(sep.charCodeAt(0)));
7672
+
7673
+ /** Give the clone of a nested repository the source's refs where they matter
7674
+ * for recovering work (awebai/oats#657): every local branch under its name at
7675
+ * its commit, HEAD on the source's branch when the source is on one (`name`:
7676
+ * headName) and detached at `head` otherwise, and the source's reflogs of
7677
+ * HEAD and of each branch, copied over the clone's own. The branches are the
7678
+ * source's own `refs/heads`, not the clone's `refs/remotes/origin/*`: those
7679
+ * are only what the source advertises, and its configuration can hide a
7680
+ * branch from a clone (`uploadpack.hideRefs`). A tip the clone lacks is
7681
+ * fetched by id (carryNamedObjects), and the copy's branches are then
7682
+ * checked to be the source's, name and commit, byte for byte. Its local
7683
+ * configuration is not carried beyond the status settings
7684
+ * (carryStatusConfig): a recovery must be inert to inspect, and
7685
+ * configuration can name programs Git runs. → the commits the copied
7686
+ * reflogs name, for carryNamedObjects: a commit only a reflog reaches is not
7687
+ * in the clone until it is fetched. */
7688
+ function carryNestedRefs(source, dest, name, head) {
7689
+ const BRANCHES = ["for-each-ref", "--format=%(objectname)%00%(refname)", "refs/heads/"];
7690
+ const listing = retireGit(source, BRANCHES);
7691
+ const branches = [];
7692
+ for (let at = 0; at < listing.length;) {
7693
+ let end = listing.indexOf(0x0a, at);
7694
+ if (end < 0) end = listing.length;
7695
+ const row = listing.subarray(at, end);
7696
+ at = end + 1;
7697
+ if (!row.length) continue;
7698
+ const nul = row.indexOf(0);
7699
+ branches.push({ oid: row.subarray(0, nul).toString("latin1"), ref: row.subarray(nul + 1) });
7700
+ }
7701
+ carryNamedObjects(source, dest, { commits: branches.map((b) => b.oid) });
7702
+ if (branches.length) {
7703
+ retireGit(dest, ["update-ref", "--stdin"], { input: Buffer.concat(branches.flatMap(({ oid, ref }) => [Buffer.from("update "), ref, Buffer.from(` ${oid}\n`)])) });
7704
+ }
7705
+ if (!retireGit(dest, BRANCHES).equals(listing)) throw new Error(`nested recovery ${dest} does not have the local branches of its source`);
7706
+ if (name.branch !== null) retireGit(dest, ["symbolic-ref", "HEAD", `refs/heads/${name.branch}`]);
7707
+ else retireGit(dest, ["checkout", "--quiet", "--detach", head]);
7708
+ const recovered = retireGit(dest, ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
7709
+ if (recovered !== head) throw new Error(`nested recovery ${dest} is at ${recovered}, not at the commit ${head} its source has checked out`);
7710
+ // The reflogs last, so that nothing above writes to them after the copy.
7711
+ const named = [];
7712
+ const carryLog = (from, to) => {
7713
+ if (existsSync(from)) {
7714
+ mkdirSync(parentOf(to), { recursive: true });
7715
+ copyFileSync(from, to);
7716
+ named.push(...reflogCommits(to));
7717
+ } else rmSync(to, { force: true });
7718
+ };
7719
+ const destGit = join(dest, ".git");
7720
+ carryLog(gitPathOf(copierGitDir(source), Buffer.from("logs/HEAD")), gitPathOf(destGit, Buffer.from("logs/HEAD")));
7721
+ const sourceCommon = copierCommonDir(source);
7722
+ for (const { ref } of branches) carryLog(gitPathOf(sourceCommon, Buffer.from("logs/"), ref), gitPathOf(destGit, Buffer.from("logs/"), ref));
7723
+ return named;
7724
+ }
7725
+
7726
+ /** Rebuild each nested repository (nestedGitRoots) in the copy of a worktree
7727
+ * at `recoveredRepo`, from a clone, and mirror its files into it
7728
+ * (mirrorTopLevel). It runs after the worktree's own mirror, which put every
7729
+ * nested repository's plain files in place; each rebuild replaces one of
7730
+ * them. No root is under another (nestedGitRoots does not go into a
7731
+ * repository), so no mirror here removes a repository rebuilt before it.
7732
+ * Git is run on each repository by its path, which Node passes as UTF-8
7733
+ * text: a repository whose path is not valid UTF-8 cannot be named to Git,
7734
+ * and refuses the copy. */
6981
7735
  function materializeNestedRepositories(sourceWork, recoveredRepo) {
6982
7736
  const excludes = [], statusConfig = [];
6983
- for (const source of nestedGitRoots(sourceWork)) {
7737
+ for (const root of nestedGitRoots(sourceWork)) {
7738
+ const source = root.toString("utf8");
7739
+ if (!Buffer.from(source).equals(root)) throw new Error(`nested repository ${source} has a path that is not valid UTF-8, and Git cannot be run on such a path; rename the directory, then retire again`);
6984
7740
  const rel = relative(sourceWork, source);
6985
7741
  const dest = join(recoveredRepo, rel);
6986
- const head = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
7742
+ const name = headName(source);
7743
+ const head = retireGit(source, ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
6987
7744
  rmSync(dest, { recursive: true, force: true });
6988
- execFileSync("git", ["clone", "--no-local", "--quiet", source, dest], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
6989
- execFileSync("git", ["-C", dest, "checkout", "--quiet", head], { maxBuffer: GIT_MAX_BUFFER });
6990
- detachRecoveryClone(source, dest);
7745
+ retireGit(null, ["clone", "--no-local", "--quiet", source, dest]);
7746
+ detachRecoveryClone(source, dest, carryNestedRefs(source, dest, name, head));
6991
7747
  restoreStandaloneGitState(source, dest);
6992
7748
  for (const c of carryExcludes(source, dest)) excludes.push({ repo: rel, ...c });
6993
7749
  for (const c of carryStatusConfig(source, dest)) statusConfig.push({ repo: rel, ...c });
6994
- for (const e of readdirSync(source, { withFileTypes: true })) {
6995
- if (e.name === ".git") continue;
6996
- const target = join(dest, e.name);
6997
- rmSync(target, { recursive: true, force: true });
6998
- copyTreeSafe(join(source, e.name), target);
6999
- }
7750
+ mirrorTopLevel(source, dest);
7000
7751
  if (existsSync(join(dest, ".git", "objects", "info", "alternates"))) throw new Error(`nested recovery ${rel} depends on object alternates`);
7001
7752
  assertStatusAgrees(source, dest, `nested recovery ${rel} Git state disagreed with source`, rel);
7002
7753
  }
7003
7754
  return { excludes, statusConfig };
7004
7755
  }
7005
7756
 
7006
- /** Bytes a path holds, never following a symlink (a link counts as its own entry). */
7757
+ /** Bytes a path holds, never following a symlink (a link counts as its own
7758
+ * entry). `path` is a string or a Buffer; names under it are read as bytes. */
7007
7759
  function treeBytes(path) {
7008
7760
  let st; try { st = lstatSync(path); } catch { return 0; }
7009
7761
  if (!st.isDirectory()) return st.size;
7010
7762
  let n = 0;
7011
- for (const e of readdirSync(path)) n += treeBytes(join(path, e));
7763
+ for (const name of readdirSync(path, { encoding: "buffer" })) n += treeBytes(joinBytes(path, name));
7012
7764
  return n;
7013
7765
  }
7766
+ /** The paths of the untracked (`??`) and ignored (`!!`) rows of
7767
+ * `git status --porcelain=v1 -z` output, as bytes. */
7768
+ function untrackedOrIgnoredPaths(z) {
7769
+ const out = [];
7770
+ for (let at = 0; at < z.length;) {
7771
+ let end = z.indexOf(0, at);
7772
+ if (end < 0) end = z.length;
7773
+ const row = z.subarray(at, end);
7774
+ at = end + 1;
7775
+ const xy = row.subarray(0, 3).toString("latin1");
7776
+ if (xy === "?? " || xy === "!! ") out.push(row.subarray(3));
7777
+ }
7778
+ return out;
7779
+ }
7014
7780
  /** The outputs a recovery copies beyond committed and tracked state — a worktree's
7015
7781
  * untracked and ignored paths (its status), or a directory's work entries —
7016
7782
  * grouped by top-level entry with their bytes, largest first. There is no
7017
7783
  * disposable declaration on the workspace model, so node_modules/ or build/
7018
7784
  * outputs are copied too: the retire summary names them and what they cost. */
7019
7785
  function preservedOutputs(work, directory) {
7020
- const rows = directory
7021
- ? readdirSync(work)
7022
- : worktreeStatus(work).split("\0").filter((row) => row.startsWith("?? ") || row.startsWith("!! ")).map((row) => row.slice(3));
7786
+ // Paths as bytes, so every one is read by its own name; each group is
7787
+ // named as text, a name that is not UTF-8 with replacement characters.
7788
+ const rows = directory ? readdirSync(work, { encoding: "buffer" }) : untrackedOrIgnoredPaths(worktreeStatusBytes(work));
7789
+ const SLASH = 0x2f;
7023
7790
  const groups = new Map();
7024
7791
  for (const rel of rows) {
7025
- const parts = rel.replace(/\/$/, "").split("/");
7026
- const isDir = parts.length > 1 || rel.endsWith("/") || (directory && lstatSync(join(work, rel)).isDirectory());
7027
- const key = isDir ? `${parts[0]}/` : parts[0];
7028
- groups.set(key, (groups.get(key) || 0) + treeBytes(join(work, rel)));
7792
+ const trailing = rel.length > 0 && rel[rel.length - 1] === SLASH;
7793
+ const slash = rel.indexOf(SLASH);
7794
+ const first = slash < 0 ? rel : rel.subarray(0, slash);
7795
+ const isDir = (slash >= 0 && slash < rel.length - 1) || trailing || (directory && lstatSync(joinBytes(work, rel)).isDirectory());
7796
+ const key = isDir ? `${first.toString("utf8")}/` : first.toString("utf8");
7797
+ groups.set(key, (groups.get(key) || 0) + treeBytes(joinBytes(work, rel)));
7029
7798
  }
7030
7799
  const paths = [...groups].map(([path, bytes]) => ({ path, bytes })).sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
7031
7800
  return { paths, bytes: paths.reduce((n, p) => n + p.bytes, 0) };
@@ -7034,17 +7803,18 @@ function preservedOutputs(work, directory) {
7034
7803
  /** The home part of a recovery at `dest`: everything but work/ and this pass's
7035
7804
  * excluded provider-owned entries (observation.homeExclude), verified against
7036
7805
  * the source with that same set. The copy is hashed whole, so an excluded
7037
- * entry that reached it fails the verification. The stored digest is what
7038
- * is compared: it leaves the kernel's own fields of instance.json out, so a
7039
- * kernel write there between the copy and this check is not a disagreement.
7040
- * That is an inherited limit, and this is not an exact verification of the
7041
- * whole home: the stored digest also passes over the kernel's receipts and
7042
- * the harness settings, reads instance.json through a parse, and frames its
7043
- * entries without lengths. */
7806
+ * entry that reached it fails the verification. Source and copy are compared
7807
+ * in this run, so whatever version the baseline holds, the stored digest of
7808
+ * version 2 is what is compared (fingerprintTrees): its order is the bytes'
7809
+ * and its fields carry their lengths. It leaves the kernel's own fields of
7810
+ * instance.json out, so a kernel write there between the copy and this check
7811
+ * is not a disagreement. That is why this is not an exact verification of
7812
+ * the whole home: the stored digest also passes over the kernel's receipts
7813
+ * and the harness settings, and reads instance.json through a parse. */
7044
7814
  function copyRecoveryHome(observation, dest) {
7045
7815
  const excludeRoot = observation.homeExclude || new Set(["work"]);
7046
7816
  copyRecoveryTree(observation.home, dest, { excludeRoot });
7047
- if (fingerprintTree(observation.home, { excludeRoot, instanceHome: true }) !== fingerprintTree(dest, { instanceHome: true })) {
7817
+ if (storedTreeDigest(observation.home, BASELINE_DIGEST_VERSION, { excludeRoot, instanceHome: true }) !== storedTreeDigest(dest, BASELINE_DIGEST_VERSION, { instanceHome: true })) {
7048
7818
  throw new Error("home recovery verification disagreed with the source");
7049
7819
  }
7050
7820
  }
@@ -7072,11 +7842,11 @@ function copyRecoveryWork(observation, meta, parent) {
7072
7842
  try { ref = existsSync(observation.work) ? worktreeHead(observation.work) : { branch: meta.branch, commit: null }; }
7073
7843
  catch (e) { unreadableHeads.add(e); throw e; }
7074
7844
  if (ref.branch !== meta.branch) branchDrift = { recordedBranch: meta.branch, worktreeBranch: ref.branch, detachedAt: ref.branch === null ? ref.commit : null };
7075
- if (ref.branch !== null) execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", ref.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
7845
+ if (ref.branch !== null) retireGit(null, ["clone", "--no-local", "--quiet", "--branch", ref.branch, meta.repo, recoveredRepo]);
7076
7846
  else {
7077
- execFileSync("git", ["clone", "--no-local", "--quiet", "--no-checkout", meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
7078
- execFileSync("git", ["-C", recoveredRepo, "fetch", "--quiet", observation.work, ref.commit], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
7079
- execFileSync("git", ["-C", recoveredRepo, "checkout", "--quiet", "--detach", ref.commit], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
7847
+ retireGit(null, ["clone", "--no-local", "--quiet", "--no-checkout", meta.repo, recoveredRepo]);
7848
+ copierFetch(recoveredRepo, observation.work, [ref.commit]);
7849
+ retireGit(recoveredRepo, ["checkout", "--quiet", "--detach", ref.commit]);
7080
7850
  }
7081
7851
  const sourceGitContext = existsSync(observation.work) ? observation.work : meta.repo;
7082
7852
  detachRecoveryClone(sourceGitContext, recoveredRepo);
@@ -7084,12 +7854,10 @@ function copyRecoveryWork(observation, meta, parent) {
7084
7854
  restoreStandaloneGitState(observation.work, recoveredRepo);
7085
7855
  excludes = carryExcludes(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
7086
7856
  statusConfig = carryStatusConfig(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
7087
- for (const e of readdirSync(observation.work, { withFileTypes: true })) {
7088
- if (e.name === ".git") continue;
7089
- const dest = join(recoveredRepo, e.name);
7090
- rmSync(dest, { recursive: true, force: true });
7091
- copyTreeSafe(join(observation.work, e.name), dest);
7092
- }
7857
+ // The worktree's top level first, then each nested repository rebuilt
7858
+ // inside it (materializeNestedRepositories): that order is what keeps
7859
+ // a rebuilt repository from being removed by a mirror.
7860
+ mirrorTopLevel(observation.work, recoveredRepo);
7093
7861
  const nested = materializeNestedRepositories(observation.work, recoveredRepo);
7094
7862
  excludes.push(...nested.excludes); statusConfig.push(...nested.statusConfig);
7095
7863
  }
@@ -7099,7 +7867,12 @@ function copyRecoveryWork(observation, meta, parent) {
7099
7867
  // pre-hook recovery was written, or by the proof that the hooks moved
7100
7868
  // nothing, or else here. Either way they are kept as the observation's
7101
7869
  // byte state.
7102
- if ((observation.worktree ? observedWorkBytes(observation) : worktreeBytes(observation.work)) !== worktreeBytes(recoveredRepo)) throw new Error("worktree recovery verification disagreed with the source");
7870
+ // The Git directories the comparison leaves out are the source's
7871
+ // (worktreeGitPaths), read with its bytes, for both sides.
7872
+ let sourceBytes, gitPaths;
7873
+ if (observation.worktree) { sourceBytes = observedWorkBytes(observation); gitPaths = observation.workGitPaths ?? worktreeGitPaths(observation.work); }
7874
+ else { gitPaths = worktreeGitPaths(observation.work); sourceBytes = worktreeBytes(observation.work, gitPaths); }
7875
+ if (sourceBytes !== worktreeBytes(recoveredRepo, gitPaths)) throw new Error("worktree recovery verification disagreed with the source");
7103
7876
  assertStatusAgrees(observation.work, recoveredRepo, "recovered Git index/status disagreed with the source", ".");
7104
7877
  }
7105
7878
  // The proof of the copy: its HEAD is the commit the worktree has checked
@@ -7107,9 +7880,9 @@ function copyRecoveryWork(observation, meta, parent) {
7107
7880
  // same files, so the branch's tip there proves nothing about the copy.
7108
7881
  // With the worktree gone there is no such commit to read, and the copy
7109
7882
  // is the recorded branch as the repository has it.
7110
- const recoveredHead = execFileSync("git", ["-C", recoveredRepo, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
7883
+ const recoveredHead = retireGit(recoveredRepo, ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
7111
7884
  const sourceHead = ref.commit
7112
- ?? execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${ref.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
7885
+ ?? retireGit(meta.repo, ["rev-parse", `refs/heads/${ref.branch}`], { encoding: "utf8" }).trim();
7113
7886
  if (recoveredHead !== sourceHead) throw new Error(ref.commit ? "recovery clone is not at the commit the worktree has checked out" : "recovery clone does not retain the instance branch tip");
7114
7887
  copied = true;
7115
7888
  }
@@ -7128,8 +7901,8 @@ function copyRecoveryWork(observation, meta, parent) {
7128
7901
  * largest first; a directory ends in `/`. What the retire summary names as
7129
7902
  * copied from the home. */
7130
7903
  function preservedHome(recoveredHome) {
7131
- const paths = readdirSync(recoveredHome, { withFileTypes: true })
7132
- .map((e) => ({ path: e.isDirectory() ? `${e.name}/` : e.name, bytes: treeBytes(join(recoveredHome, e.name)) }))
7904
+ const paths = entriesAsBytes(recoveredHome)
7905
+ .map((e) => ({ path: e.isDirectory() ? `${e.name.toString("utf8")}/` : e.name.toString("utf8"), bytes: treeBytes(joinBytes(recoveredHome, e.name)) }))
7133
7906
  .sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
7134
7907
  return { paths, bytes: paths.reduce((n, p) => n + p.bytes, 0) };
7135
7908
  }
@@ -7151,6 +7924,32 @@ function homeOnlyRecovery(observation, meta) {
7151
7924
  return !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
7152
7925
  }
7153
7926
 
7927
+ /** Remove a recovery's staging directory, after a copy that failed or that had
7928
+ * nothing to keep. The copy gives each directory its source's mode
7929
+ * (tree-copy.mjs), and a read-only one (a Go module cache, 0555) keeps
7930
+ * rmSync from unlinking what is in it: each directory is made u+rwx first,
7931
+ * before it is read (an unreadable one could not be listed), symbolic links
7932
+ * are never followed, and then the tree is removed. Names are listed and
7933
+ * joined as bytes, as the copier writes them, so a directory whose name is
7934
+ * not UTF-8 is reached too (#827). Never throws: a cleanup
7935
+ * must not replace the error that made it (#659). → null when the staging is
7936
+ * gone, else the clause a refusal adds to name what is left. */
7937
+ function removeStaging(staging) {
7938
+ const open = (dir) => {
7939
+ let names;
7940
+ try {
7941
+ const st = lstatSync(dir);
7942
+ if (!st.isDirectory()) return;
7943
+ if ((st.mode & 0o700) !== 0o700) chmodSync(dir, (st.mode & 0o7777) | 0o700);
7944
+ names = entriesAsBytes(dir).map((e) => e.name);
7945
+ } catch { return; }
7946
+ for (const name of names) open(joinBytes(dir, name));
7947
+ };
7948
+ try { open(staging); rmSync(staging, { recursive: true, force: true }); } catch { /* named below */ }
7949
+ try { lstatSync(staging); } catch (e) { if (e?.code === "ENOENT") return null; }
7950
+ return `; its partial copy ${staging} could not be removed: remove it by hand`;
7951
+ }
7952
+
7154
7953
  /** Write one verified recovery of an observed home and work: staged beside its
7155
7954
  * final name and renamed into place. `phase` goes into recovery.json:
7156
7955
  * "before-hooks" for the snapshot a retirement takes before its retire hooks
@@ -7158,7 +7957,7 @@ function homeOnlyRecovery(observation, meta) {
7158
7957
  * will add to. → { receipt, manifest }: the receipt retire reports, and
7159
7958
  * recovery.json as written. */
7160
7959
  function writeRetirementRecovery(observation, meta, instance, phase) {
7161
- const recoveryRoot = join(retirementStateRoot(observation.home), "recovery");
7960
+ const recoveryRoot = retirementRecoveryRoot(dirname(observation.home));
7162
7961
  mkdirSync(recoveryRoot, { recursive: true });
7163
7962
  if (observation.directory && realpathSync(recoveryRoot) !== join(realpathSync(dirname(observation.home)), ".oats-retirement", "recovery")) {
7164
7963
  throw oatsError("E_WORK_PRESERVATION_FAILED", "directory recovery storage was redirected; retain the source home rather than copying into an unowned or disposable location");
@@ -7183,10 +7982,10 @@ function writeRetirementRecovery(observation, meta, instance, phase) {
7183
7982
  renameSync(staging, recovery);
7184
7983
  return { receipt: { path: recovery, classes: observation.classes, bytes, home, ...(outputs ? { outputs } : {}), ...(repoCopy ? { repoCopy } : {}), ...(notCopied ? { notCopied } : {}) }, manifest };
7185
7984
  } catch (e) {
7186
- rmSync(staging, { recursive: true, force: true });
7187
- if (unreadableHeads.has(e)) throw e;
7985
+ const left = removeStaging(staging);
7986
+ if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
7188
7987
  const details = e.statusDisagreement ? { home: observation.home, statusDisagreement: e.statusDisagreement } : undefined;
7189
- throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
7988
+ throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
7190
7989
  }
7191
7990
  }
7192
7991
 
@@ -7253,7 +8052,11 @@ function completeRetirementRecovery({ receipt, manifest }, before, after, meta)
7253
8052
  if (occupied()) throw new Error(`${final} already exists`);
7254
8053
  renameSync(staging, final);
7255
8054
  afterHooks = { home: wantHome, work: workCopied };
7256
- } else rmSync(staging, { recursive: true, force: true });
8055
+ } else {
8056
+ const left = removeStaging(staging);
8057
+ staging = undefined;
8058
+ if (left) throw new Error(`nothing was copied after the hooks${left}`);
8059
+ }
7257
8060
  staging = undefined;
7258
8061
  }
7259
8062
  const classes = [...new Set([...receipt.classes, ...after.classes])];
@@ -7266,12 +8069,37 @@ function completeRetirementRecovery({ receipt, manifest }, before, after, meta)
7266
8069
  const { notCopied: _was, ...kept } = receipt;
7267
8070
  return { ...kept, classes, bytes: treeBytes(recovery), ...(notCopied.length ? { notCopied } : {}), ...(afterHooks ? { afterHooks } : {}) };
7268
8071
  } catch (e) {
7269
- if (staging) rmSync(staging, { recursive: true, force: true });
7270
- if (manifestStarted) rmSync(manifestTmp, { force: true });
7271
- if (unreadableHeads.has(e)) throw e;
8072
+ const left = staging ? removeStaging(staging) : null;
8073
+ if (manifestStarted) { try { rmSync(manifestTmp, { force: true }); } catch { /* the original error is the refusal */ } }
8074
+ if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
7272
8075
  const details = e.statusDisagreement ? { home: after.home, statusDisagreement: e.statusDisagreement } : undefined;
7273
- throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
7274
- }
8076
+ throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
8077
+ }
8078
+ }
8079
+
8080
+ /** The `work` link of the instance at `kidHome` when it is attached to
8081
+ * `home`'s work (#718), else null: instance.json says `work: "attached"`, and
8082
+ * its `work` is a symbolic link that leads to `<home>/work`, as written (in
8083
+ * any spelling of the home) or through other links (`--work-dir` given as an
8084
+ * alias of the tree). The latter is seen only while `<home>/work` exists, so a
8085
+ * retire asks before it re-homes the worktree. → the link's target as written:
8086
+ * the evidence a later relink checks is still there. */
8087
+ export function attachedWorkLink(kidHome, home) {
8088
+ if (readJsonOrUndefined(join(kidHome, "instance.json"))?.work !== "attached") return null;
8089
+ const link = join(kidHome, "work");
8090
+ let written;
8091
+ try { written = readlinkSync(link); } catch { return null; }
8092
+ const target = resolve(kidHome, written);
8093
+ if (target === join(resolve(home), "work")) return written;
8094
+ try { if (basename(target) === "work" && realpathSync(dirname(target)) === realpathSync(home)) return written; } catch { /* below */ }
8095
+ try { return realpathSync(link) === realpathSync(join(home, "work")) ? written : null; } catch { return null; }
8096
+ }
8097
+ /** Point an attached instance's `work` link at `to`, atomically: a new link
8098
+ * beside it is renamed over the old one, so the link is never missing. */
8099
+ function relinkAttachedWork(kidHome, to) {
8100
+ const tmp = join(kidHome, `.work.relink-${process.pid}`);
8101
+ try { rmSync(tmp, { force: true }); symlinkSync(to, tmp); renameSync(tmp, join(kidHome, "work")); }
8102
+ catch (e) { try { rmSync(tmp, { force: true }); } catch { /* the first error is the one reported */ } throw e; }
7275
8103
  }
7276
8104
 
7277
8105
  /** Marker a self-retiring instance leaves BESIDE its home: the retirement is
@@ -7427,6 +8255,10 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
7427
8255
  return true;
7428
8256
  }
7429
8257
 
8258
+ /** The key of the home a retire selected (a string) on retireInstance's result
8259
+ * (awebai/oats#693): the CLI cleans that home's wake schedules. A symbol, so
8260
+ * the printed and JSON receipt, and a recorded one, do not carry it. */
8261
+ export const RETIRE_SELECTED_HOME = Symbol("oats.retireSelectedHome");
7430
8262
  export function retireInstance(root, name, o = {}) {
7431
8263
  if (o.deleteBranch) throw oatsError("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
7432
8264
  const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
@@ -7460,6 +8292,7 @@ export function retireInstance(root, name, o = {}) {
7460
8292
  const quarantinePath = existsSync(directoryFallbackPath) ? directoryFallbackPath : join(found.home, ".oats-rollback-incomplete.json");
7461
8293
  let quarantine;
7462
8294
  let markerUnusable = false;
8295
+ let rawMarker;
7463
8296
  // A marker means the home is quarantined, WHETHER OR NOT instance.json exists:
7464
8297
  // the post-launch rollback retains a home that already has one, and gating on
7465
8298
  // its absence meant that quarantine was silently ignored — retire took the
@@ -7474,10 +8307,46 @@ export function retireInstance(root, name, o = {}) {
7474
8307
  // against what the retry below consumes (reviewer-45ff039r2).
7475
8308
  try {
7476
8309
  const parsed = JSON.parse(readFileSync(quarantinePath, "utf8"));
8310
+ rawMarker = parsed;
7477
8311
  if (isPlainObject(parsed) && usableCleanupDescriptor(parsed)) quarantine = parsed;
7478
8312
  else markerUnusable = true;
7479
8313
  } catch { markerUnusable = true; }
7480
8314
  }
8315
+ // #796: a marker a spawn wrote before its worktree hooks (`inProgress`). While that spawn's
8316
+ // process is verifiably alive it is a spawn in progress, never a quarantine to retry, --force
8317
+ // included. Once it is gone, the hook group it left is ended when its leader is alive at the
8318
+ // recorded start time; a group whose leader is gone is never signalled, only reported (its id may
8319
+ // be another group's by now). The retry below completes the rollback from the marker like any other.
8320
+ // Whether that process still runs may also be unreadable (no procfs and `ps` failing): that is never
8321
+ // taken for gone. Retire refuses it, naming the recorded pid and start for a check by hand, and the
8322
+ // existing forced path (`--force`) is the way out; a forced retry then keeps the spawn's branch.
8323
+ // The same holds for a hook group with members whose leader's start cannot be read.
8324
+ const spawnGroupWarnings = [];
8325
+ let inProgressUnverified = false;
8326
+ if (isPlainObject(rawMarker?.inProgress)) {
8327
+ const p = rawMarker.inProgress;
8328
+ const live = processLiveness(p);
8329
+ if (live.state === "alive") throw oatsError("E_LIFECYCLE_BUSY", `${name} is still being spawned (pid ${p.pid}, running its worktree hooks since ${p.startedAt ?? "?"}); nothing was retired — wait for the spawn to end, or stop that process, then retire`);
8330
+ if (live.state === "unknown") {
8331
+ if (!o.force) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `${name}: whether its spawn (pid ${p.pid}, recorded start ${p.processStart ?? "none"}, running its worktree hooks since ${p.startedAt ?? "?"}) still runs cannot be read (${live.reason}); nothing was retired — check that pid by hand, and if it is not that spawn, run \`oats retire ${name} --force\``), { details: { pid: p.pid, processStart: p.processStart ?? null, unknown: live.reason, remedy: `oats retire ${name} --force` } });
8332
+ inProgressUnverified = true;
8333
+ spawnGroupWarnings.push(`retired with --force although whether its spawn (pid ${p.pid}) still runs could not be read (${live.reason}); its branch is kept`);
8334
+ }
8335
+ }
8336
+ if (quarantine?.inProgress) {
8337
+ const p = quarantine.inProgress;
8338
+ const ended = terminateRecordedGroup(p);
8339
+ if (ended === "survived") throw oatsError("E_LIFECYCLE_BUSY", `${name}: the worktree hook process group ${p.hookPgid} that an interrupted spawn left could not be ended (it survived SIGKILL); nothing was retired`);
8340
+ if (ended === "unverified") spawnGroupWarnings.push(unverifiedGroupWarning(p.hookPgid));
8341
+ // A group whose leader's start cannot be read may still be that spawn's hook: never signalled,
8342
+ // and refused like an unreadable spawn above, with the same way out.
8343
+ if (ended === "unknown") {
8344
+ const note = unknownGroupNote(p);
8345
+ if (!o.force) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `${name}: the worktree hook ${note}; nothing was retired — check process group ${p.hookPgid} by hand: if it is that hook, end it (kill -TERM -- -${p.hookPgid}) and retire again; if it is not, run \`oats retire ${name} --force\``), { details: { hookPgid: p.hookPgid, hookStart: p.hookStart ?? null, remedy: `oats retire ${name} --force` } });
8346
+ inProgressUnverified = true;
8347
+ spawnGroupWarnings.push(`retired with --force although the worktree ${note}; its branch is kept`);
8348
+ }
8349
+ }
7481
8350
  const liveMeta = existsSync(metaPath) ? JSON.parse(readFileSync(metaPath, "utf8")) : undefined;
7482
8351
  // A quarantined home may carry an instance.json that is NOT the spawn record:
7483
8352
  // module materialization writes a pre-hook stub ({ modules, providers,
@@ -7524,7 +8393,7 @@ export function retireInstance(root, name, o = {}) {
7524
8393
  // (aweb-abep). `--keep-dir` keeps the old in-process path: nothing to inspect.
7525
8394
  // A home opened in Herdr (removed in 0.31.0) has no endpoint OATS can quiesce in-process. A
7526
8395
  // quarantined home's cleanup descriptor overrides the live record's endpoint: either may name it.
7527
- const herdrHome = recordsHerdr(meta, readJsonOrUndefined(retirementBaselinePath(found.home))) || recordsHerdr(liveMeta);
8396
+ const herdrHome = recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(found.home))) || recordsHerdr(liveMeta);
7528
8397
  if (self && (!o.keepDir || herdrHome)) {
7529
8398
  return scheduleDeferredSelfRetirement(root, found, name, o, session);
7530
8399
  }
@@ -7543,7 +8412,7 @@ export function retireInstance(root, name, o = {}) {
7543
8412
  const recordedBranch = quarantine ? { repo: meta.repo, branch: meta.branch } : undefined;
7544
8413
  // Whether this retire removes the worktree, when it gets to that step.
7545
8414
  const worktreeRemoval = { removes: !!(o.discardWorktree || owesWorktree), repo: meta.repo };
7546
- const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
8415
+ const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork, disclosure: "Nothing was stopped, run or removed" });
7547
8416
  // A locked extra tree is known from the home as it is now: Git will neither move nor remove it, so a retire that
7548
8417
  // would remove the home refuses here, before the session is stopped and before any retire hook runs (the hooks
7549
8418
  // revoke identities a kept home would still need). The extra-tree step keeps its own check, for a lock that appears
@@ -7611,20 +8480,23 @@ export function retireInstance(root, name, o = {}) {
7611
8480
  } catch (e) {
7612
8481
  const detail = String(e.stderr ?? e.message ?? "").trim();
7613
8482
  const unestablished = (why) => oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${why}`);
7614
- if (!/no server running|failed to connect|can't find session|no sessions/i.test(detail)) {
7615
- if (!tmuxServerLost(e)) throw unestablished(detail || "tmux inspection failed");
7616
- // A server that cannot be reached, typically because its socket file is missing (a reboot clears
7617
- // tmux's socket directory). A server outlives its socket file, so that alone does not say the
7618
- // window is gone: it is taken as gone only when no process works in the home, as for a home
7619
- // without its receipt.
7620
- const scan = processesInHome(found.home);
7621
- if (!scan.ok) throw unestablished(`${detail}; whether a process still works in this home could not be established (${scan.error})`);
7622
- 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` : ""})`);
8483
+ if (!/no server running|can't find session|no sessions/i.test(detail)) {
8484
+ const absence = tmuxServerAbsence(e);
8485
+ if (!absence) throw unestablished(detail || "tmux inspection failed");
8486
+ // A missing socket file, in any tmux's words (a reboot clears tmux's socket directory). A server
8487
+ // outlives its socket file, so that alone does not say the window is gone: it is taken as gone
8488
+ // only when no process works in the home, as for a home without its receipt (#624).
8489
+ const why = absence === "missing-socket" ? missingSocketUnestablished(detail, processesInHome(found.home)) : null;
8490
+ if (why) throw unestablished(why);
7623
8491
  }
7624
8492
  }
7625
8493
  sessionStopped = true;
7626
8494
  }
7627
- const stableObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
8495
+ // What a refusal before the hooks tells the operator about the retire so far.
8496
+ const soFar = (kept) => `${name} is not retired and ${kept}; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
8497
+ // What a refusal after the hooks tells the operator about the retire so far.
8498
+ const afterHooks = () => `The retire hooks have run; the home, its work and the pre-hook recovery (if any) are kept; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
8499
+ const stableObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork, disclosure: `No retire hook has run and nothing was deleted: ${soFar("its home and work are kept")}` });
7628
8500
  // The bytes of the worktree as they are before the hooks: after the hooks,
7629
8501
  // "the work did not move" is then proven, never taken from a status text.
7630
8502
  // Read before the recovery is written, so that a worktree that cannot be
@@ -7636,8 +8508,6 @@ export function retireInstance(root, name, o = {}) {
7636
8508
  // unchanged is copied again in any case, and with nothing to preserve
7637
8509
  // before the hooks there is nothing to prove: any class after them is
7638
8510
  // preserved.
7639
- // What a refusal before the hooks tells the operator about the retire so far.
7640
- const soFar = (kept) => `${name} is not retired and ${kept}; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
7641
8511
  if (stableObservation.classes.length && stableObservation.workProvable) {
7642
8512
  try { observedWorkBytes(stableObservation); }
7643
8513
  catch (e) {
@@ -7740,10 +8610,17 @@ export function retireInstance(root, name, o = {}) {
7740
8610
  // baseline): it does not have to be a move of the observed state. Either
7741
8611
  // way this finishes, or refuses and keeps the home, before the worktree
7742
8612
  // step and before the home is removed.
7743
- const finalObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
7744
- if (preHookRecovery) workRecovery = completeRetirementRecovery(preHookRecovery, stableObservation, finalObservation, meta);
7745
- else if (finalObservation.classes.length) {
7746
- workRecovery = preserveRetirementWork({ ...finalObservation, notCopied: unionNotCopied(stableObservation.notCopied, finalObservation.notCopied) }, meta, name);
8613
+ // A refusal here says what has and has not happened, as one before the hooks
8614
+ // does: the hooks have run, and what is kept (#659).
8615
+ const finalObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork, disclosure: afterHooks() });
8616
+ try {
8617
+ if (preHookRecovery) workRecovery = completeRetirementRecovery(preHookRecovery, stableObservation, finalObservation, meta);
8618
+ else if (finalObservation.classes.length) {
8619
+ workRecovery = preserveRetirementWork({ ...finalObservation, notCopied: unionNotCopied(stableObservation.notCopied, finalObservation.notCopied) }, meta, name);
8620
+ }
8621
+ } catch (e) {
8622
+ if (!e?.code) throw e;
8623
+ throw Object.assign(oatsError(e.code, `${e.message}. ${afterHooks()}.`, e.provenance), e.details ? { details: e.details } : {});
7747
8624
  }
7748
8625
 
7749
8626
  // Lineage repair: any instance pointing at the retiree (parentInstance from a
@@ -7842,8 +8719,8 @@ export function retireInstance(root, name, o = {}) {
7842
8719
  try {
7843
8720
  git(row, ["worktree", "remove", row.path]);
7844
8721
  git(row, ["worktree", "prune"]);
7845
- const real = realPathOrNearest(row.path);
7846
- if (existsSync(row.path) || parseWorktreeList(git(row, ["worktree", "list", "--porcelain", "-z"])).some((r) => realPathOrNearest(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
8722
+ const real = canonicalHomePath(row.path);
8723
+ if (existsSync(row.path) || parseWorktreeList(git(row, ["worktree", "list", "--porcelain", "-z"])).some((r) => canonicalHomePath(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
7847
8724
  } catch (e) { throw failed(row, "could not be removed, or its removal could not be verified", e); }
7848
8725
  extraWorktrees.push({ ...row, outcome: "removed" });
7849
8726
  appendEvent(found.home, { kind: "worktree-removed", data: { branch: row.branch, extra: true, path: row.path } }, { workspaceOnly: true });
@@ -7858,10 +8735,31 @@ export function retireInstance(root, name, o = {}) {
7858
8735
  }
7859
8736
  if (!extraWorktrees.length) extraWorktrees = undefined;
7860
8737
  }
8738
+ // The attached children this retire stopped whose work is this home's work/
8739
+ // (#718), found while work/ is still here (a link through an alias of the
8740
+ // tree resolves only then), each with its link as written.
8741
+ const attachedKids = (childrenStopped || []).filter((k) => k.ok).map((k) => ({ ...k, link: attachedWorkLink(k.home, found.home) })).filter((k) => k.link !== null);
7861
8742
  const worktreeStep = isWorktree && !!meta.repo && !orphanedWork;
7862
8743
  const worktreeDeferred = worktreeStep && existsSync(workPath) && outstandingBeforeWorktree.length > 0 && !o.force;
7863
8744
  const keptForRetry = worktreeDeferred ? `git worktree ${workPath}: kept for the retry; outstanding: ${outstandingBeforeWorktree.join("; ")}` : null;
7864
8745
  let retention = null;
8746
+ // The repository of work/, by its common Git directory (awebai/oats#679), read once from meta.repo: the
8747
+ // step's commands and the quarantine's verification below run helper-free against it (gitRepoRun,
8748
+ // gitRepoRead), as the extra-tree step's do. A bare repository is named as its Git directory.
8749
+ // → { dir } or { error }.
8750
+ let workRepo;
8751
+ const workRepoGitDir = () => {
8752
+ if (workRepo) return workRepo;
8753
+ const args = ["rev-parse", "--path-format=absolute", "--git-common-dir"];
8754
+ let r = gitRead(meta.repo, args);
8755
+ if (!r.ok) { const asGitDir = gitRepoRead(meta.repo, args); if (asGitDir.ok) r = asGitDir; }
8756
+ const dir = r.ok ? r.out.replace(/\n$/, "") : "";
8757
+ return (workRepo = dir && !dir.includes("\n") ? { dir: realPathOrNearest(dir) } : { error: r.ok ? `git rev-parse printed no single Git directory for ${meta.repo}` : r.err });
8758
+ };
8759
+ // Whether an entry is at the path: lstat, so a dangling link is an entry; one that cannot be tested counts.
8760
+ const entryAt = (path) => { try { lstatSync(path); return true; } catch (e) { return e?.code !== "ENOENT"; } };
8761
+ // A removal that work/ was not there for, from a repository that could not be read: nothing was verified.
8762
+ let removalUnverified;
7865
8763
  if (worktreeStep && !worktreeDeferred) {
7866
8764
  // A HEAD that cannot be read here is recorded as no branch and no commit, and the worktree is retained.
7867
8765
  const ref = existsSync(workPath) ? (() => { try { return worktreeHead(workPath); } catch { return { branch: null, commit: null }; } })() : { branch: meta.branch ?? null, commit: null };
@@ -7877,14 +8775,36 @@ export function retireInstance(root, name, o = {}) {
7877
8775
  catch (e) { throw oatsError("E_WORK_INSPECTION_FAILED", `${e.message}. The worktree was not removed. The home and the worktree are kept, and so is any recovery the retire wrote; retry the retire.`); }
7878
8776
  assertSameWorktreeHead(finalObservation.head, now);
7879
8777
  }
7880
- shTry(`git -C ${shq(meta.repo)} worktree remove --force ${shq(workPath)}`);
7881
- shTry(`git -C ${shq(meta.repo)} worktree prune`);
7882
- retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
8778
+ // The removal is verified as the extra-tree step's is: nothing is at work/ and the repository's
8779
+ // worktree list does not name it. A removal that did not happen, or cannot be shown to have
8780
+ // happened, refuses and keeps the home, --force included. One exception: nothing at work/ and a
8781
+ // repository that cannot be read is recorded as absent, never removed; a quarantine keeps that
8782
+ // as an item its retry could not verify (below).
8783
+ const present = entryAt(workPath);
8784
+ const gitDir = workRepoGitDir();
8785
+ if (gitDir.error && !present) {
8786
+ removalUnverified = gitDir.error;
8787
+ retention = { worktree: "absent", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
8788
+ } else {
8789
+ const real = canonicalHomePath(workPath);
8790
+ try {
8791
+ if (gitDir.error) throw new Error(gitDir.error);
8792
+ if (present) gitRepoRun(gitDir.dir, ["worktree", "remove", "--force", workPath]);
8793
+ gitRepoRun(gitDir.dir, ["worktree", "prune"]);
8794
+ if (entryAt(workPath) || parseWorktreeList(gitRepoRun(gitDir.dir, ["worktree", "list", "--porcelain", "-z"])).some((r) => canonicalHomePath(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
8795
+ } catch (e) {
8796
+ const done = extraWorktrees?.length ? ` Already done in this retire: ${extraWorktrees.map((r) => r.outcome === "removed" ? `${r.path} removed` : `${r.path} re-homed to ${r.movedTo}`).join(", ")}.` : "";
8797
+ throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the worktree at ${workPath} could not be removed, or its removal could not be verified (${String(e?.stderr || e?.message || e || "").trim() || "unknown error"}).${done} The retire hooks have run; the home is kept, and so is any recovery the retire wrote; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}. Check what is left at ${workPath}, then retry the retire.`);
8798
+ }
8799
+ retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
8800
+ }
7883
8801
  } else if (existsSync(workPath)) {
7884
8802
  const dest = retainedWorktreeDest(workspaceOf(root), meta.repo, verifiedBranch, ref.commit);
7885
8803
  mkdirSync(dirname(dest), { recursive: true });
7886
8804
  try {
7887
- execFileSync("git", ["-C", meta.repo, "worktree", "move", workPath, dest], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
8805
+ const gitDir = workRepoGitDir();
8806
+ if (gitDir.error) throw new Error(gitDir.error);
8807
+ gitRepoRun(gitDir.dir, ["worktree", "move", workPath, dest]);
7888
8808
  } catch (e) {
7889
8809
  throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the worktree at ${workPath} could not be re-homed to ${dest} (${String(e.stderr ?? e.message ?? "").trim()}); the home is kept so nothing is lost — resolve and retry, or pass --discard-worktree to remove the worktree instead`);
7890
8810
  }
@@ -7927,29 +8847,31 @@ export function retireInstance(root, name, o = {}) {
7927
8847
  });
7928
8848
  stillIncomplete = ordinaryIncomplete;
7929
8849
  }
8850
+ let branchDeletedByRetry = false, branchKeptReason;
7930
8851
  if (quarantine) {
7931
8852
  const failures = [...retryFailures];
7932
8853
  if (keptForRetry) failures.push(keptForRetry);
7933
8854
  // The quarantine may exist BECAUSE Git cleanup failed, so a retry has to
7934
8855
  // redo those steps and verify them — not just rerun hooks. No retire deletes a branch.
7935
8856
  if (meta.work === "worktree" && meta.repo) {
7936
- const gitProbe = (argv) => {
7937
- try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
7938
- catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
7939
- };
7940
8857
  // A worktree this retry removed (the step above ran) must be verified gone; one it retained or kept for
7941
8858
  // the next retry stays registered by design. The removal is not attempted a second time here: only the
7942
8859
  // worktree step removes, after its check of HEAD, so a worktree it failed to remove is still registered
7943
8860
  // and the next retry goes through that step again.
8861
+ // Its commands run helper-free against the repository's common Git directory (workRepoGitDir).
8862
+ const gitDir = workRepoGitDir();
7944
8863
  if (retention?.worktree === "removed") {
7945
- const wtCanonical = realPathOrNearest(workPath);
7946
- gitProbe(["git", "-C", meta.repo, "worktree", "prune"]);
7947
- const wtProbe = gitProbe(["git", "-C", meta.repo, "worktree", "list", "--porcelain", "-z"]);
7948
- if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
8864
+ const wtCanonical = canonicalHomePath(workPath);
8865
+ let wtProbe;
8866
+ if (gitDir.error) wtProbe = { ok: false, err: gitDir.error };
7949
8867
  else {
7950
- const registered = wtProbe.out.split("\0").filter((f) => f.startsWith("worktree ")).map((f) => f.slice("worktree ".length));
7951
- if (registered.includes(wtCanonical)) failures.push(`git worktree ${wtCanonical}: still registered`);
8868
+ try { gitRepoRun(gitDir.dir, ["worktree", "prune"]); } catch { /* the list below decides */ }
8869
+ wtProbe = gitRepoRead(gitDir.dir, ["worktree", "list", "--porcelain", "-z"]);
7952
8870
  }
8871
+ if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
8872
+ else if (parseWorktreeList(wtProbe.out).some((r) => canonicalHomePath(r.worktree) === wtCanonical)) failures.push(`git worktree ${wtCanonical}: still registered`);
8873
+ } else if (retention?.worktree === "absent" && removalUnverified !== undefined) {
8874
+ failures.push(`git worktree ${realPathOrNearest(workPath)}: could not verify removal (${removalUnverified})`);
7953
8875
  }
7954
8876
  // The branch is a debt only when the failed spawn's rollback still owes its deletion. A retry never
7955
8877
  // deletes it: the debt is cleared only when the branch is shown to be gone. Git's quiet exit 1 is
@@ -7957,8 +8879,38 @@ export function retireInstance(root, name, o = {}) {
7957
8879
  // "could not verify", and the debt stays. The text is never matched: this read can only err
7958
8880
  // toward keeping the debt.
7959
8881
  const owesBranch = (quarantine.cleanup.outstanding?.git || []).includes("branch");
8882
+ // The one exception (#796): a spawn killed while its worktree hooks ran never reached its own
8883
+ // compensation. Its marker carries `inProgress` (its process verified dead above) with the branch
8884
+ // and the commit the spawn created it at. Once the retire hooks ran and the worktree's removal is
8885
+ // verified, the retry finishes that compensation: an atomic compare-and-delete at that commit,
8886
+ // refused when the tip moved, the branch is checked out anywhere, or the ref cannot be read. A
8887
+ // branch still at its creation commit holds no work. Every other quarantine keeps the rule above.
8888
+ const ip = quarantine.inProgress;
8889
+ if (owesBranch && meta.branch && ip && ip.branch === meta.branch && inProgressUnverified) branchKeptReason = "the spawn's process or its hook group could not be verified gone (retired with --force)";
8890
+ else if (owesBranch && meta.branch && ip && ip.branch === meta.branch && /^[0-9a-f]{40,64}$/.test(String(ip.baseOid ?? "")) && retention?.worktree === "removed" && !failures.length) {
8891
+ const ref = `refs/heads/${meta.branch}`;
8892
+ // Retire's Git, bounded and helper-free (retireGit, #809): two reads, then the one write.
8893
+ const tip = retireGitProbe(meta.repo, ["rev-parse", "--verify", "--quiet", "--end-of-options", ref], { encoding: "utf8" });
8894
+ const list = retireGitProbe(meta.repo, ["worktree", "list", "--porcelain", "-z"], { encoding: "utf8" });
8895
+ const listOk = !list.error && list.status === 0;
8896
+ const checkedOut = listOk && list.stdout.split("\0").includes(`branch ${ref}`);
8897
+ if (tip.error || tip.status !== 0 || tip.stderr.length) branchKeptReason = "the branch could not be read";
8898
+ else if (tip.stdout.trim() !== ip.baseOid) branchKeptReason = `its tip moved from ${ip.baseOid.slice(0, 12)}, where the spawn created it`;
8899
+ else if (!listOk) branchKeptReason = "whether it is checked out could not be read";
8900
+ else if (checkedOut) branchKeptReason = "it is checked out in a worktree";
8901
+ else {
8902
+ const del = retireGitProbe(meta.repo, ["update-ref", "-d", ref, ip.baseOid], { encoding: "utf8" });
8903
+ if (del.error || del.status !== 0) branchKeptReason = `git refused to delete it (${String(del.stderr || del.error?.message || "").trim().split("\n")[0] || "update-ref failed"})`;
8904
+ else branchDeletedByRetry = true;
8905
+ }
8906
+ }
7960
8907
  if (owesBranch && meta.branch) {
7961
- const br = spawnSync("git", ["-C", meta.repo, "rev-parse", "--verify", "--quiet", `refs/heads/${meta.branch}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
8908
+ let br;
8909
+ if (gitDir.error) br = { error: new Error(gitDir.error) };
8910
+ else {
8911
+ try { gitRepoRun(gitDir.dir, ["rev-parse", "--verify", "--quiet", `refs/heads/${meta.branch}`]); br = { status: 0, stderr: "" }; }
8912
+ catch (e2) { br = { error: e2.status === undefined || e2.status === null ? e2 : undefined, status: e2.status, stderr: String(e2.stderr ?? "") }; }
8913
+ }
7962
8914
  if (!br.error && br.status === 0) failures.push(FAILED_SPAWN_BRANCH_LEFT);
7963
8915
  else if (br.error || br.status !== 1 || br.stderr.length) failures.push(`git branch ${meta.branch}: could not verify whether it still exists (${String(br.stderr ?? "").trim() || br.error?.message || `rev-parse exit ${br.status}`})`);
7964
8916
  }
@@ -7975,6 +8927,33 @@ export function retireInstance(root, name, o = {}) {
7975
8927
  } catch { /* the quarantine stands regardless */ }
7976
8928
  }
7977
8929
  }
8930
+ // An attached child whose `work` links to this home's work/ would dangle once
8931
+ // the worktree is re-homed (#718): each one this retire stopped is repointed
8932
+ // to the retained worktree, whether or not the home is then removed (the work
8933
+ // has left it either way). It is a write to another instance, so it comes
8934
+ // last, once the move is done and seen done: the worktree is at its new path
8935
+ // and nothing is left at work/. One that fails is a warning; the retire is
8936
+ // not undone. The child's AGENTS.md still names the old path.
8937
+ const relinkWarnings = [];
8938
+ if (retention?.worktree === "retained") {
8939
+ const present = (p) => { try { lstatSync(p); return true; } catch { return false; } };
8940
+ const moved = attachedKids.length > 0 && (() => { try { return lstatSync(retention.movedTo).isDirectory(); } catch { return false; } })() && !present(workPath);
8941
+ for (const kid of attachedKids) {
8942
+ // The attachment as it was found, still: attached, and the same link. One that changed is
8943
+ // someone else's now, and is left as it is.
8944
+ const still = (() => { try { return readJsonOrUndefined(join(kid.home, "instance.json"))?.work === "attached" && readlinkSync(join(kid.home, "work")) === kid.link; } catch { return false; } })();
8945
+ if (!still) {
8946
+ relinkWarnings.push(`${kid.instance}: its attachment changed during the retire, so its work was left as it is now and not repointed to the retained worktree ${retention.movedTo}; inspect ${join(kid.home, "work")}`);
8947
+ continue;
8948
+ }
8949
+ try {
8950
+ if (!moved) throw new Error(`the worktree was not seen at ${retention.movedTo} with nothing left at ${workPath}`);
8951
+ relinkAttachedWork(kid.home, retention.movedTo);
8952
+ } catch (e) {
8953
+ relinkWarnings.push(`${kid.instance}: its work link could not be repointed to the retained worktree ${retention.movedTo} (${e.message}) and still points at ${kid.link}; repoint it by hand: ln -sfn ${shq(retention.movedTo)} ${shq(join(kid.home, "work"))}`);
8954
+ }
8955
+ }
8956
+ }
7978
8957
  // Forcing is the operator overriding the fail-closed default with their eyes
7979
8958
  // open: the home goes, and what remains outstanding is reported rather than
7980
8959
  // swallowed. Without this, a quarantine whose cleanup can never succeed (a
@@ -7993,8 +8972,8 @@ export function retireInstance(root, name, o = {}) {
7993
8972
  rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
7994
8973
  }
7995
8974
 
7996
- const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
7997
- const w = [...(hookResults?.warnings || [])];
8975
+ const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, ...(branchDeletedByRetry || branchKeptReason ? { spawnCompensation: { branch: meta.branch, branchDeleted: branchDeletedByRetry, ...(branchKeptReason ? { reason: branchKeptReason } : {}) } } : {}), removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
8976
+ const w = [...spawnGroupWarnings, ...(hookResults?.warnings || []), ...relinkWarnings];
7998
8977
  if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
7999
8978
  if (isCapturedHome(meta) && !quarantine) {
8000
8979
  // A captured home retires through the workspace path; its captured retire hooks do not
@@ -8005,6 +8984,7 @@ export function retireInstance(root, name, o = {}) {
8005
8984
  } else if (!Array.isArray(meta?.capabilityRuntime) && !quarantine) w.push("this home records no capability hooks (an earlier kernel spawned it): no retire hook ran; any external state its capabilities created is the operator's to clean up");
8006
8985
  return w.length ? w : undefined;
8007
8986
  })() };
8987
+ result[RETIRE_SELECTED_HOME] = found.home;
8008
8988
  if (self) {
8009
8989
  // The caller is the instance: its process lives in the window we are about to
8010
8990
  // kill. Detach the kill so this function can return and the caller can report