@awebai/oats 0.41.1 → 0.42.0

package/lib/instance-lifecycle.mjs

@@ -10,7 +10,8 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, stopInstanceSession } from "./core.mjs";
+import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
+import { groupedByOwner } from "./retire-output.mjs";
 import { observeInstanceGit } from "./instance-git.mjs";
 import { appendEvent } from "./instance-events.mjs";
 import { oatsError } from "./errors.mjs";
@@ -164,6 +165,8 @@ function writeFileSyncAtomic(path, value) {
   writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
 }
 
+/** How many declared roots a retire plan's recovery note lists before `, and N more`. */
+const PLAN_NOT_COPIED_CAP = 16;
 /** Facts for Remove (retire): what retirement would touch, with the design's
  *  defaults (retain worktree and branch; never touch a PR). `oats retire`
  *  itself applies them: plain retire re-homes the worktree; --discard-worktree
@@ -181,6 +184,12 @@ export function planRetire(ctx, root, name, { home } = {}) {
     pullRequest: "unknown" /* forge facts are the ADE's (P1); the kernel never claims 'no PR' */ };
   const defaults = { retainWorktree: meta.work === "worktree", deleteBranch: false, stopChildren: true, retainChildren: true };
   const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home)];
+  // What retire would preserve and where, read from the spawn baseline and the
+  // work mode: nothing is hashed, and the plan revision does not depend on it.
+  // The declared roots are listed as written, capped so one note stays short.
+  const recovery = retirementRecoveryFacts(me.home);
+  const declared = recovery.disposableHome.slice(0, PLAN_NOT_COPIED_CAP);
+  const notCopied = declared.length ? `; not copied: ${groupedByOwner(declared, "root")}${recovery.disposableHome.length > declared.length ? `, and ${recovery.disposableHome.length - declared.length} more` : ""}` : "";
   appendEvent(me.home, { kind: "retire-planned", data: { planRevision: planRevision(safety), children: kids.length, dirty: facts.work.observed ? facts.work.changed + facts.work.untracked : null } }, { workspaceOnly: true });
   return { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
     notes: [
@@ -190,5 +199,7 @@ export function planRetire(ctx, root, name, { home } = {}) {
       ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
       ...(target.session.note ? [target.session.established ? `session absent: ${target.session.note}; nothing needs quiescing` : `session not observably absent: ${target.session.note}; retire refuses until it is stopped`] : []),
       "pull request state is unknown to the kernel; the ADE reports it when a forge connection exists",
+      `recovery: the home is copied to ${recovery.recoveryRoot} before the home is removed, when it changed since spawn${notCopied}`,
+      ...(meta.work === "worktree" ? ["recovery: uncommitted worktree state is copied there too"] : meta.work === "directory" ? ["recovery: work/ is copied there when it is not empty"] : []),
     ] };
 }

package/lib/launch-preference.mjs

@@ -78,6 +78,15 @@ export function harnessUnavailable({ harness, from, at, why }) {
   return fail("E_HARNESS_UNAVAILABLE", `${harness} is not installed on this machine (${why}); ${source} chose it — ${fix}`, { harness, from, at: at ?? null, fix });
 }
 
+/** What a person can do about a harness its pane would not find. */
+export const PANE_PATH_FIX = "declare the executable's absolute path in the launch configuration (executable), set PATH in the launch configuration (env), or start the OATS tmux server from your own shell (tmux -L oats new-session -d -s <session> -n hq), so that it has your PATH";
+/** E_HARNESS_UNAVAILABLE for a harness looked up where its pane looks it up (the session's or the
+ *  server's PATH, or a launch configuration's): `why` names that source and what went wrong, never
+ *  the PATH's contents. Never a fallback to this process's PATH or to another harness. */
+export function harnessNotOnPanePath({ harness, from, at, why }) {
+  return fail("E_HARNESS_UNAVAILABLE", `${harness} is not available to its pane: ${why}, and a pane looks its harness up there; ${PANE_PATH_FIX}`, { harness, from, at: at ?? null, fix: PANE_PATH_FIX });
+}
+
 /** The closed `Launch` report: `{declared, effective: {harness, model, launchConfig}, from, at, problem}`. */
 export function launchReport({ declared = null, harness, model = null, launchConfig = null, from, at = null, problem = null }) {
   return { declared: declared ? { harness: declared.harness, model: declared.model ?? null } : null, effective: { harness, model: model || null, launchConfig: launchConfig || null }, from, at: at ?? null, problem };

package/lib/login-environment.mjs

@@ -0,0 +1,212 @@
+// The user's login environment, read when the kernel creates the OATS tmux server (awebai/oats#616).
+//
+// A tmux server keeps the environment of the process that starts it, and every pane on it inherits
+// that. When the kernel starts the server it gives it what the user's own login shell sets up (the
+// PATH a version manager activates, an agent socket an rc file exports), read as data, never the
+// creator's ambient environment: the creator may be an agent instance, whose identity, credentials
+// and harness variables must not become the server's. docs/execution-targets.md owns the rule.
+//
+// Whose: only a creator whose HOME is the user's home directory in the password database is taken
+// to run in the user's session, and only for it is the login shell run. A process that redirected
+// HOME (a sandbox, a test fixture) is not: its reading fails, and its caller takes the fallback. The
+// test seam (a fake shell) is honoured only there, never in the user's own session.
+//
+// How: the login shell from the password database (os.userInfo().shell, never the creator's SHELL),
+// one of bash, zsh or fish, runs `-l -i -c '<node> -e <emitter> <nonce>'`, started from a fixed seed
+// in the OS user's home directory. The emitter writes JSON.stringify(process.env) to its stdout as
+// one frame: a start and an end delimiter that each carry a random nonce, made for this reading only,
+// and begin and end with a line break, which valid JSON never holds unescaped. Exactly one complete,
+// ordered frame for that nonce is the answer; whatever the shell's start-up prints around it (rc
+// chatter, prompts, text shaped like assignments or like JSON, a frame with another nonce) is
+// discarded, and its stderr is not read. The nonce separates the answer from accidental chatter; it
+// does not authenticate anything against the user's own start-up files, which can also redirect the
+// shell's stdout away (then there is no answer). Not a descriptor of its own: bash 5.3, started -l -i, marks
+// the descriptors it inherits from 3 to 19 close-on-exec, so a pipe there never reaches the emitter,
+// and no shell is relied on to leave any descriptor but stdout to the command it runs. No value goes
+// into argv (the nonce is not one), a file, a log or a diagnostic. The answer is accepted only whole: exit status 0, at most
+// 1 MiB, one JSON object whose values are all strings, plain identifiers as names, HOME and PATH
+// present. The functions bash exports (`BASH_FUNC_<name>%%`, a stock profile's `export -f`) are code,
+// not environment: they are dropped from the answer, never carried. Nothing in it is evaluated.
+//
+// Bounded: the shell runs in its own process group. The deadline (5 s) ends the read even when a
+// descendant still holds the shell's stdout after the shell exited; then that group, and only that
+// group, gets SIGKILL (never the shell's own pid, which is reaped by then). A descendant that made
+// its own session or group (a daemon) is outside it, and group cleanup does not promise to end it.
+//
+// Imports nothing but node's own modules: the kernel stays dependency-free.
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { accessSync, constants as fsConstants, realpathSync } from "node:fs";
+import { userInfo } from "node:os";
+import { basename, resolve } from "node:path";
+import { signalGroup } from "./process-group.mjs";
+
+/** The session variables the seed carries: what lets the user's setup reach their agent socket and
+ *  display. Per name, the first source where the name is present (an empty value counts) is used. */
+export const LOGIN_SESSION_ENV = ["SSH_AUTH_SOCK", "DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS"];
+/** The shells whose `-l -i -c` and single quotes this relies on. Any other is an acquisition failure. */
+export const LOGIN_SHELLS = ["bash", "zsh", "fish"];
+export const LOGIN_CAPTURE_TIMEOUT_MS = 5000;
+export const LOGIN_CAPTURE_MAX_BYTES = 1024 * 1024;
+const SEED_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PLATFORM_READ_TIMEOUT_MS = 2000;
+// The frame's delimiters, each `\n<marker><nonce>\n`; the emitter receives the nonce as its one
+// argument (process.argv[1]).
+const BEGIN = "OATS-LOGIN-ENVIRONMENT-BEGIN-", END = "OATS-LOGIN-ENVIRONMENT-END-";
+// Loops until every byte is written: stdout is a blocking pipe in the emitter.
+const EMITTER = `const f=require("fs"),n=process.argv[1],b=Buffer.from("\\n${BEGIN}"+n+"\\n"+JSON.stringify(process.env)+"\\n${END}"+n+"\\n");for(let o=0;o<b.length;)o+=f.writeSync(1,b,o)`;
+const BASH_FUNCTION = /^BASH_FUNC_.+%%$/;
+/** One single-quoted word for `shell`: POSIX's `'…'\\''…'` for bash and zsh; fish's own form, where a
+ *  backslash and a quote inside single quotes are escaped with a backslash. */
+const quoteFor = (shell) => basename(shell) === "fish"
+  ? (s) => `'${String(s).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`
+  : (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const samePath = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+
+/**
+ * Read the login environment. `creatorEnv`: the creating process's environment (its locale names,
+ * and its session variables when it is not an instance). `instance`: whether the creator is an
+ * instance; then `recorded` is the global environment of the server its home records, as the strict
+ * reader read it (null when it could not be read). `shell` replaces the password database's shell, a
+ * test seam honoured only for a creator outside the user's session (its HOME is not the password
+ * database's), where it also makes the platform's tools the creator's (its PATH's). → `{ env, notes }` (env as the shell's environment ended up, unfiltered) or
+ * `{ failure, notes }`: why, in words that hold no value. `notes`: what a person should know even on
+ * success (a platform session that could not be read), also without values; a caller reports them
+ * only with a successful capture, so a failure is one line.
+ */
+export function captureLoginEnvironment({ creatorEnv = process.env, instance = false, recorded = null, shell: seam, timeoutMs = LOGIN_CAPTURE_TIMEOUT_MS } = {}) {
+  const notes = [];
+  let user;
+  try { user = userInfo(); } catch { return { failure: "your user has no password database entry", notes }; }
+  // Only a creator in the user's session (its HOME is the user's home directory) has a login shell run
+  // for it; a test seam is never honoured there.
+  const ownSession = typeof creatorEnv.HOME === "string" && creatorEnv.HOME !== "" && samePath(creatorEnv.HOME, user.homedir);
+  if (!ownSession && !seam) return { failure: "this process's HOME is not your home directory, so it does not run in your login session", notes };
+  const shell = ownSession ? user.shell : seam;
+  if (!shell) return { failure: "your user has no login shell in the password database", notes };
+  if (!LOGIN_SHELLS.includes(basename(shell))) return { failure: `your login shell (${basename(shell)}) is not bash, zsh or fish`, notes };
+  // Nothing is read for a shell that cannot run (the user session included).
+  try { accessSync(shell, fsConstants.X_OK); } catch (e) { return { failure: `your login shell could not be started (${e.code || "error"})`, notes }; }
+  const seed = { HOME: user.homedir, USER: user.username, LOGNAME: user.username, SHELL: user.shell ?? shell, PATH: SEED_PATH, TERM: "dumb" };
+  for (const name of ["LANG", "LC_ALL", "LC_CTYPE"]) if (creatorEnv[name] !== undefined) seed[name] = creatorEnv[name];
+  Object.assign(seed, sessionVariables({ creatorEnv, instance, recorded, notes, user, toolPath: ownSession ? SEED_PATH : creatorEnv.PATH }));
+  const sq = quoteFor(shell);
+  const nonce = randomBytes(16).toString("hex");
+  const r = spawnSync(shell, ["-l", "-i", "-c", `${sq(process.execPath)} -e ${sq(EMITTER)} ${nonce}`], {
+    cwd: user.homedir, env: seed, stdio: ["ignore", "pipe", "ignore"],
+    timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: LOGIN_CAPTURE_MAX_BYTES, detached: true, windowsHide: true,
+  });
+  // The deadline or the size limit ended it: whatever of its group is left (a descendant holding the
+  // shell's stdout, a shell still in its rc) is killed. Only this group, only then: the shell itself
+  // was reaped before spawnSync returned, so its bare pid is never signalled.
+  if (r.error?.code === "ETIMEDOUT" || r.error?.code === "ENOBUFS" || r.signal) signalGroup(r, "SIGKILL");
+  if (r.error?.code === "ETIMEDOUT") return { failure: `your login shell did not answer within ${Math.round(timeoutMs / 1000)} s`, notes };
+  if (r.error?.code === "ENOBUFS") return { failure: "its answer was larger than 1 MiB", notes };
+  if (r.error) return { failure: `your login shell could not be started (${r.error.code || "error"})`, notes };
+  if (r.signal) return { failure: `your login shell was ended by ${r.signal}`, notes };
+  if (r.status !== 0) return { failure: `your login shell exited with status ${r.status}`, notes };
+  const printed = r.stdout;
+  if (printed?.length > LOGIN_CAPTURE_MAX_BYTES) return { failure: "its answer was larger than 1 MiB", notes };
+  // Exactly one start and one end delimiter of this nonce, in that order; anything else is no answer
+  // or an ambiguous one, never a part of it taken as the whole.
+  const begin = Buffer.from(`\n${BEGIN}${nonce}\n`), end = Buffer.from(`\n${END}${nonce}\n`);
+  const from = printed ? printed.indexOf(begin) : -1, to = printed ? printed.indexOf(end) : -1;
+  if (from < 0 && to < 0) return { failure: "your login shell gave no answer", notes };
+  if (from < 0 || to < from + begin.length || printed.indexOf(begin, from + 1) >= 0 || printed.indexOf(end, to + 1) >= 0) return { failure: "its answer was not exactly one complete frame", notes };
+  const data = printed.subarray(from + begin.length, to);
+  let env;
+  try { env = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data)); } catch { return { failure: "its answer was not one complete JSON object", notes }; }
+  if (!env || typeof env !== "object" || Array.isArray(env)) return { failure: "its answer was not one complete JSON object", notes };
+  // Functions bash exports are code every bash in a pane would import: dropped, never carried.
+  for (const name of Object.keys(env)) if (BASH_FUNCTION.test(name)) delete env[name];
+  const names = Object.keys(env);
+  if (names.some((name) => typeof env[name] !== "string")) return { failure: "its answer held a value that is not text", notes };
+  if (names.some((name) => !NAME.test(name))) return { failure: "its answer held a name that is not a plain identifier", notes };
+  for (const name of ["HOME", "PATH"]) if (!Object.hasOwn(env, name)) return { failure: `its answer had no ${name}`, notes };
+  return { env: Object.assign(Object.create(null), env), notes };
+}
+
+/** The seed's session variables, per name from the first source that has it: (a) the creator, only
+ *  when it is not an instance; (b) for an instance, the recorded server's global environment; (c)
+ *  the platform's user session, read as data. */
+function sessionVariables({ creatorEnv, instance, recorded, notes, user, toolPath }) {
+  const out = {}, missing = [];
+  for (const name of LOGIN_SESSION_ENV) {
+    if (!instance && creatorEnv[name] !== undefined) out[name] = creatorEnv[name];
+    else if (instance && recorded && Object.hasOwn(recorded, name)) out[name] = recorded[name];
+    else missing.push(name);
+  }
+  if (!missing.length) return out;
+  const platform = platformSession(missing, user, toolPath);
+  if (platform.failure) notes.push(`could not read the user session's environment (${platform.failure}); ${missing.join(", ")} came only from your login shell`);
+  for (const name of missing) if (Object.hasOwn(platform.env, name)) out[name] = platform.env[name];
+  return out;
+}
+
+/** The user session's variables of `names`: `systemctl --user show-environment` on Linux,
+ *  `launchctl getenv NAME` on macOS, each bounded, never through a shell. The tool is looked up on
+ *  `toolPath` (the seed's PATH; under the test seam, the creator's) and runs with an environment of
+ *  the OS user's own (HOME, USER, LOGNAME and, on Linux, the user's runtime directory, where
+ *  systemctl finds the user bus), never the creator's. A failed or unavailable read, a timeout or a
+ *  missing tool leave every name absent. → `{ env, failure? }` */
+function platformSession(names, user, toolPath = SEED_PATH) {
+  const toolEnv = { HOME: user.homedir, USER: user.username, LOGNAME: user.username, PATH: toolPath ?? SEED_PATH, ...(process.platform === "linux" && user.uid >= 0 ? { XDG_RUNTIME_DIR: `/run/user/${user.uid}` } : {}) };
+  const run = (file, args) => spawnSync(file, args, { env: toolEnv, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: PLATFORM_READ_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: LOGIN_CAPTURE_MAX_BYTES, windowsHide: true });
+  const why = (r, tool) => r.error ? (r.error.code === "ENOENT" ? `${tool} was not found` : r.error.code === "ETIMEDOUT" ? `${tool} timed out` : `${tool} failed (${r.error.code})`) : r.status !== 0 ? `${tool} exited with status ${r.status ?? r.signal}` : null;
+  if (process.platform === "linux") {
+    const r = run("systemctl", ["--user", "show-environment"]);
+    const failure = why(r, "systemctl --user show-environment");
+    return failure ? { env: {}, failure } : { env: parseSystemdEnvironment(r.stdout, names) };
+  }
+  if (process.platform === "darwin") {
+    const env = {};
+    for (const name of names) {
+      const r = run("launchctl", ["getenv", name]);
+      const failure = why(r, "launchctl getenv");
+      if (failure) return { env, failure };
+      const value = r.stdout.replace(/\n$/, "");
+      if (value !== "") env[name] = value; // empty output: absent
+    }
+    return { env };
+  }
+  return { env: {} };
+}
+
+/**
+ * `systemctl --user show-environment` read as data: lines `NAME=value`. A value systemd printed in
+ * its `$'…'` C-escaped form (\a \b \e \f \n \r \t \v \\ \' \" \ooo \xHH) is decoded, as bytes, then as
+ * UTF-8; one that cannot be decoded leaves its name absent. Only the names asked for are kept.
+ */
+export function parseSystemdEnvironment(text, names = LOGIN_SESSION_ENV) {
+  const env = {};
+  for (const line of String(text).split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const name = line.slice(0, eq), raw = line.slice(eq + 1);
+    if (!names.includes(name)) continue;
+    if (!raw.startsWith("$'")) { env[name] = raw; continue; }
+    const value = decodeCEscaped(raw);
+    if (value !== null) env[name] = value;
+  }
+  return env;
+}
+const SIMPLE_ESCAPES = { a: 7, b: 8, e: 27, f: 12, n: 10, r: 13, t: 9, v: 11, "\\": 92, "'": 39, "\"": 34 };
+function decodeCEscaped(raw) {
+  if (!raw.endsWith("'") || raw.length < 3) return null;
+  const body = raw.slice(2, -1);
+  const bytes = [];
+  for (let i = 0; i < body.length; i++) {
+    const c = String.fromCodePoint(body.codePointAt(i));
+    if (c === "'") return null; // an unescaped quote cannot be inside
+    if (c !== "\\") { bytes.push(...Buffer.from(c, "utf8")); i += c.length - 1; continue; }
+    const next = body[i + 1];
+    if (next !== undefined && Object.hasOwn(SIMPLE_ESCAPES, next)) { bytes.push(SIMPLE_ESCAPES[next]); i += 1; continue; }
+    const oct = /^[0-7]{3}/.exec(body.slice(i + 1, i + 4));
+    if (oct && parseInt(oct[0], 8) < 256) { bytes.push(parseInt(oct[0], 8)); i += 3; continue; }
+    const hex = /^x([0-9A-Fa-f]{2})/.exec(body.slice(i + 1, i + 4));
+    if (hex) { bytes.push(parseInt(hex[1], 16)); i += 3; continue; }
+    return null;
+  }
+  try { return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(bytes)); } catch { return null; }
+}

package/lib/retire-output.mjs

@@ -0,0 +1,50 @@
+/** What `oats retire` says about the work it preserved. One function renders
+ *  the lines for the local and the remote path of bin/oats.mjs, from the
+ *  receipt's `workRecovery` (lib/core.mjs, retireInstance). A receipt from an
+ *  older kernel, or a stored one, may carry `workRecoveries[]` instead: one
+ *  block is printed per entry. Dependency-free. */
+
+export const formatBytes = (n) => n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(1)} GiB`;
+
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** `a, b (owner); c (other)`: the `key` of each row, grouped by its owner; owners sorted, rows in their order. */
+export function groupedByOwner(rows, key) {
+  const groups = new Map();
+  for (const row of rows) groups.set(row.owner, [...(groups.get(row.owner) || []), row[key]]);
+  return [...groups].sort(([a], [b]) => byCodeUnit(String(a), String(b))).map(([owner, names]) => `${names.join(", ")}${owner ? ` (${owner})` : ""}`).join("; ");
+}
+
+/** `{ paths: [{ path, bytes }], bytes }` as one line: the first 8 with their size, then the total. */
+function sizedPathsLine(label, part) {
+  if (!part?.paths?.length) return [];
+  const shown = part.paths.slice(0, 8).map((p) => `${p.path} (${formatBytes(p.bytes)})`);
+  const more = part.paths.length > 8 ? `, and ${part.paths.length - 8} more` : "";
+  return [`  ${label}: ${shown.join(", ")}${more} — ${formatBytes(part.bytes)} in total`];
+}
+
+/** The recoveries a retire receipt names: every entry of a historical `workRecoveries[]`, else its one `workRecovery`. */
+export function receiptRecoveries(receipt) {
+  if (Array.isArray(receipt?.workRecoveries) && receipt.workRecoveries.length) return receipt.workRecoveries;
+  return receipt?.workRecovery ? [receipt.workRecovery] : [];
+}
+
+/** The lines `oats retire` prints for what a receipt preserved; `host` (the
+ *  remote path) names where. Per recovery: the classes, the path with its
+ *  size, then, when they apply, what was copied from the home, the copied
+ *  outputs, the home entries left out by a capability's declaration (names and
+ *  owners only) and which parts were copied again under after-hooks/. */
+export function workRecoveryLines(receipt, { host } = {}) {
+  const lines = [];
+  for (const recovery of receiptRecoveries(receipt)) {
+    lines.push(`Work that was not committed has been preserved${host ? ` on ${host}` : ""}: ${(recovery.classes || []).join(", ")}`);
+    lines.push(`  ${recovery.path}${typeof recovery.bytes === "number" ? ` (${formatBytes(recovery.bytes)})` : ""}`);
+    lines.push(...sizedPathsLine("copied from the home", recovery.home));
+    lines.push(...sizedPathsLine("copied outputs", recovery.outputs));
+    const notCopied = Array.isArray(recovery.notCopied) ? recovery.notCopied.filter((row) => typeof row?.path === "string") : [];
+    if (notCopied.length) lines.push(`  not copied: ${groupedByOwner(notCopied, "path")}`);
+    const again = [recovery.afterHooks?.home === true && "home", recovery.afterHooks?.work === true && "work"].filter(Boolean);
+    if (again.length) lines.push(`  after the retire hooks: ${again.join(" and ")} copied again under after-hooks/`);
+  }
+  return lines;
+}

package/lib/tree-copy.mjs

@@ -21,14 +21,16 @@ import { oatsError } from "./errors.mjs";
  * - deterministic traversal (sorted entries), so two copies of one tree hash
  *   identically;
  * - symlinks are recreated VERBATIM — never followed, never rewritten — because
- *   the bytes about to be hashed must be the bytes the author wrote;
+ *   the bytes about to be hashed must be the bytes the author wrote. The target
+ *   is read and written as bytes: read as text, a target that is not valid
+ *   UTF-8 would be recreated as another one;
  * - FIFOs, sockets and device nodes are rejected fail-closed: they are not
  *   distributable content, and copying them has no defined meaning here;
  * - directory modes are applied AFTER their children, so a read-only source
  *   directory cannot block writing its own contents. */
 export function copyTreeSafe(src, dest) {
   const st = lstatSync(src);
-  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src), dest); return; }
+  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src, "buffer"), dest); return; }
   if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
   if (!st.isDirectory()) {
     throw oatsError("invalid-source", `${src} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",