@awebai/oats 0.39.4 → 0.40.2

package/lib/core.mjs

@@ -32,6 +32,7 @@ import {
   chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { accessSync, constants as fsConstants } from "node:fs";
 import { recordLocalInput } from "./local-inputs.mjs";
 import { createHash, randomUUID } from "node:crypto";
@@ -40,7 +41,7 @@ import { initializeNativeHistory, prepareNativeStart } from "../packages/record/
 import { noteRuntimeName } from "./deprecation.mjs";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
-import { appendEvent } from "./instance-events.mjs";
+import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
 import { killGroup } from "./process-group.mjs";
 
 import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
@@ -204,7 +205,7 @@ function shIn(cwd, cmdline, timeout = 45000) {
   return execSync(cmdline, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout }).trim();
 }
 function shInTry(cwd, cmdline, timeout) { try { return shIn(cwd, cmdline, timeout); } catch { return undefined; } }
-function shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
+export function shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 export function slug(s) {
   const r = String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return r || "agent";
@@ -2008,7 +2009,7 @@ export const RELATIONS = ["child", "sibling", "parent", "unrelated"];
 /** Verify the harness packages that ACTIVE capabilities require for `harness`.
  *
  * Each comes from a declared harness-package requirement, so the capability has
- * stated the dependency and the user has consented to install it (`oats install`).
+ * stated the dependency. Installing it remains the operator's responsibility.
  * We verify PRESENCE and record provenance; we deliberately do NOT resolve the
  * extension's entry file. pi owns that resolution — its manifest supports globs
  * and exclusions, packages without a `pi` manifest use conventional directories,
@@ -2050,8 +2051,16 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
       const status = harnessPackageStatus(harness, spec, probeEnv, probeOpts);
       const mgr = HARNESS_PACKAGE_MANAGERS[harness];
       const stepList = mgr?.steps ? mgr.steps(spec, raw, probeOpts) : [mgr?.argv(spec, raw, probeOpts) || []];
-      const direct = stepList.filter((a) => a.length).map((a) => a.join(" ")).join(" && ");
-      const remedy = `run \`oats install --accept-requirement ${harness}:${harnessPackageIdentity(harness, spec)} --dir ${contextDir}\`${direct ? ` (or \`${direct}\` directly)` : ""}`;
+      // Keep the remedy in the same resource directory and selected wrapper as
+      // the probe; quote argv, never turn a path or package selector into shell code.
+      // Pi expands ~ against the launch HOME; relative selectors are anchored
+      // to the probe cwd before the remedy changes to contextDir.
+      const piResourceDir = harness === "pi" ? piAgentDir(probeEnv).replace(/^~(?=$|\/)/, () => probeEnv.HOME || homedir()) : undefined;
+      const resourceEnv = harness === "pi" ? `PI_CODING_AGENT_DIR=${shq(resolve(piResourceDir))} `
+        : harness === "claude" && probeEnv.CLAUDE_CONFIG_DIR ? `CLAUDE_CONFIG_DIR=${shq(resolve(probeEnv.CLAUDE_CONFIG_DIR))} ` : "";
+      const direct = stepList.filter((a) => a.length).map((a) => resourceEnv + [bin || a[0], ...a.slice(1)].map(shq).join(" ")).join(" && ");
+      const remedy = direct ? `ask the operator to run \`cd ${shq(contextDir)} && ${direct}\` with the selected harness's environment; OATS does not install packages during spawn or restart`
+        : `ask the operator to install it with the selected harness's package manager`;
       // `ifInstalled: true`: the row constrains a package that may be absent
       // (an ambient extension must honour a contract IF it is there); absence
       // satisfies it. Without the flag, absence fails as before.
@@ -2659,6 +2668,12 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
   }
   return step.value;
 }
+/** The producer sets this only when dispatched effects or their compensation
+ * cannot be confirmed. A diagnostic's wording or home path is not evidence. */
+function unconfirmedSpawn(error) {
+  error.details = { ...error.details, unconfirmed: true };
+  return error;
+}
 function* spawnBody(root, agent, o = {}) {
   if (!o.prepared) throw localMissingForSpawn(agent);
   const deliver = (r) => r;
@@ -2747,7 +2762,7 @@ function* spawnBody(root, agent, o = {}) {
       // Completion custody: the home exists from the first metadata write, but
       // the launch/lineage/events that make it a finished spawn may not have
       // happened (crash in the interval). Say which, never replay a half-spawn.
-      if (prior.spawnCompleted !== true) throw 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 });
+      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 }));
       return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null } };
     }
   }
@@ -3209,7 +3224,7 @@ function* spawnBody(root, agent, o = {}) {
   // name taken (M1). Nothing of a classic home exists at this point either.
   const rollbackEmptyOrPreparedHome = (e) => {
     try { rmSync(home, { recursive: true, force: true }); }
-    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; }
+    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; unconfirmedSpawn(e); }
     return e;
   };
   // Workspace model: copy every resolved capability WHOLE into the new home
@@ -3377,9 +3392,10 @@ function* spawnBody(root, agent, o = {}) {
   if (incomplete.length) {
     // Nothing outside the home exists yet (no worktree, no hooks, no window), so
     // removing the scaffold is the whole rollback.
-    let removal = "";
-    try { rmSync(home, { recursive: true, force: true }); } catch (e) { removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
-    throw oatsError("E_COMPOSITION_INCOMPLETE", `the instance composition did not materialize completely:\n${incomplete.map((m) => `  ${m}`).join("\n")}${removal}`);
+    let removal = "", removalFailed = false;
+    try { rmSync(home, { recursive: true, force: true }); } catch (e) { removalFailed = true; removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
+    const error = oatsError("E_COMPOSITION_INCOMPLETE", `the instance composition did not materialize completely:\n${incomplete.map((m) => `  ${m}`).join("\n")}${removal}`);
+    throw removalFailed ? unconfirmedSpawn(error) : error;
   }
 
   // Work tree.
@@ -3424,7 +3440,8 @@ function* spawnBody(root, agent, o = {}) {
       }
       try { rmSync(home, { recursive: true, force: true }); } catch (e2) { incomplete.push(`instance home ${home}: ${e2.message}`); }
       const note = incomplete.length ? ` — rollback INCOMPLETE — clean up manually: ${incomplete.join("; ")}` : "";
-      throw new Error(`git worktree add/canonicalization failed: ${original}${note}`);
+      const error = new Error(`git worktree add/canonicalization failed: ${original}${note}`);
+      throw incomplete.length ? unconfirmedSpawn(error) : error;
     }
   } else if (work === "directory") {
     // An owned execution directory, not a link to the source or a fake Git repo.
@@ -3520,11 +3537,11 @@ function* spawnBody(root, agent, o = {}) {
           outstandingGit.add("worktree");
           if (branch) outstandingGit.add("branch");
         }
-        return quarantineInstanceHome({
+        return { unconfirmed: true, note: quarantineInstanceHome({
           home, instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId, incomplete, failed, outstandingHooks, outstandingGit,
           repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
           launched: true, tmux: spawnTmux, directoryHome: homeReal, recordRetirementBaseline: true,
-        });
+        }) };
       }
     }
     // Once hooks ran, directory execution may already hold authored results.
@@ -3546,7 +3563,7 @@ function* spawnBody(root, agent, o = {}) {
         launched: false, directoryPreservation: true, directoryHome: homeReal,
         recordRetirementBaseline: true,
       });
-      return `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}`;
+      return { unconfirmed: true, note: `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}` };
     };
     const preserveDirectory = () => {
       if (work !== "directory") return;
@@ -3630,7 +3647,7 @@ function* spawnBody(root, agent, o = {}) {
       if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
       note = incomplete.length ? ` — rollback INCOMPLETE, clean up manually: ${incomplete.join("; ")}` : " — spawn rolled back";
     }
-    return `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}`;
+    return { unconfirmed: incomplete.length > 0, note: `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}` };
   };
 
   try {
@@ -3849,8 +3866,15 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     }
     return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
   } catch (error) {
-    const note = compensateSpawn();
-    error.message += note;
+    try {
+      const compensation = compensateSpawn();
+      error.message += compensation.note;
+      if (compensation.unconfirmed) unconfirmedSpawn(error);
+    } catch (cleanupError) {
+      // An interrupted compensation pass cannot establish that effects ended.
+      error.message += ` — rollback INCOMPLETE: cleanup could not be completed: ${cleanupError.message}`;
+      unconfirmedSpawn(error);
+    }
     throw error;
   }
 }
@@ -3948,7 +3972,18 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           ...(meta.home !== undefined && meta.home !== home ? { recordedHome: meta.home } : {}),
           ...(meta.instance !== undefined && meta.instance !== e.name ? { recordedInstance: meta.instance } : {}),
         };
-        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, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+        // Feature waiting-on-you: a producer's live claim that the instance is
+        // blocked on a human, read only for a running row (one bounded read of
+        // its home log); null otherwise, and null means unknown. `running` is
+        // the window's presence, which a crashed harness's fallback shell or a
+        // retained dead pane keeps: a row with a claim is shown only when its
+        // session is observed running a harness, as session inspect reports it.
+        let waitingOnYou = liveness.running === true ? liveWaiting(home) : null;
+        if (waitingOnYou) {
+          try { const s = instanceSessionTarget(home); if (!s.target || !harnessRunning(inspectSessionTarget(s.target))) waitingOnYou = null; }
+          catch { waitingOnYou = null; }
+        }
+        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 } : {}) };
 
       });
   };
@@ -4324,6 +4359,12 @@ const GIT_MAX_BUFFER = 512 * 1024 * 1024;
  *  otherwise every stop or event write would read as "changed home bytes". */
 const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json"]);
 const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
+/** Harness project settings in the home are configuration, not work: the
+ *  home's `.claude/` is harness layout the kernel already shapes (the skills
+ *  alias), and capabilities keep their own entries current in its
+ *  settings.json at every launch. A retirement fingerprint ignores exactly
+ *  that path, home-relative. */
+const HARNESS_HOME_SETTINGS = new Set([join(".claude", "settings.json")]);
 function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false, instanceHome = false } = {}) {
   const hash = createHash("sha256");
   const rootStat = lstatSync(root);
@@ -4338,6 +4379,7 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
     for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       if ((!rel && excludeRoot.has(e.name)) || (instanceHome && !rel && (KERNEL_HOME_RECEIPTS.has(e.name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(e.name)))) || (excludeGitMetadata && e.name === ".git")) continue;
       const childRel = rel ? join(rel, e.name) : e.name;
+      if (instanceHome && HARNESS_HOME_SETTINGS.has(childRel)) continue;
       const path = join(dir, e.name);
       const st = lstatSync(path);
       hash.update(childRel); hash.update("\0"); hash.update(String(st.mode & 0o7777)); hash.update("\0");
@@ -4565,12 +4607,18 @@ function instanceSessionTarget(home) {
 }
 
 export function inspectInstanceSession(home) {
-  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped" };
+  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", waitingOnYou: null };
   const s = instanceSessionTarget(home);
-  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched" };
-  try { return { home: s.home, ...inspectSessionTarget(s.target) }; }
+  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", waitingOnYou: null };
+  let observed;
+  try { observed = inspectSessionTarget(s.target); }
   catch (e) { throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`); }
+  // Feature waiting-on-you: beside `state`, whose enum is unchanged.
+  return { home: s.home, ...observed, waitingOnYou: harnessRunning(observed) ? liveWaiting(s.home) : null };
 }
+/** Whether an observed session runs a harness: present, and neither a
+ *  fallback shell nor a dead pane. Only such a session can be waiting on a human. */
+function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
 
 /** K3: quiesce one instance's session and RETAIN everything else — home,
  *  worktree, transcript, launch configuration — so `restart` can bring it back.
@@ -5125,6 +5173,9 @@ export function startInstanceSession(home, o = {}) {
       // Reconcile even an exited target: the independent baseline may
       // already name it while metadata still names the old allocation.
       const meta = readMeta();
+      // The adopted start's session boundary, at its launch time, completed
+      // in whichever log the interrupted start did not record it.
+      recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: pending.launch?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: "recovered" });
       const done = record(meta, { ...pending, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
       if (st.present && st.state !== "shell") {
         if (o.restart) { rmSync(pendingPath, { force: true }); }
@@ -5305,6 +5356,10 @@ export function startInstanceSession(home, o = {}) {
       catch (e) { throw launchFailure(e); }
     }
     target = { backend: "tmux", session, window, socket: resolve(socket) };
+    // The session exists: its boundary (lib/instance-events.mjs) is recorded
+    // now, before the metadata, so a start whose metadata write fails still
+    // voids the claims of the session it replaced; its adoption only completes a log it missed.
+    recordStartBoundary(realHome, { startId: id, startedAt, harness: launchPlan?.harness || harness, backend: "tmux", launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: o.restart ? "restart" : "start" });
     // Keep launch evidence until the command exits or the target disappears.
     // A transient child (for example the native-start recorder) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.

package/lib/dir-lock.mjs

@@ -10,9 +10,9 @@ function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) {
 const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
 /** A mkdir lock that is never reclaimed by another process: an existing
- *  lock whose owner is unreadable or dead is refused with the directory to
- *  remove, because the gap between mkdir and owner.json belongs to a live
- *  acquirer and a dead-owner reclaim races every other acquirer. The
+ *  lock whose owner is unreadable or dead is refused after bounded waiting,
+ *  with the directory to remove, because the gap between mkdir and owner.json
+ *  belongs to a live acquirer and a dead-owner reclaim races every other acquirer. The
  *  holder removes its own lock in finally and on SIGINT/SIGTERM. A lock still
  *  held after `retryMs` is refused with `busy(why)`, the caller's own error. */
 export function withDirLock(dir, what, fn, { retryMs = 0, busy } = {}) {
@@ -23,7 +23,10 @@ export function withDirLock(dir, what, fn, { retryMs = 0, busy } = {}) {
     catch (e) {
       if (e.code !== "EEXIST") throw e;
       let owner; try { owner = JSON.parse(readFileSync(join(dir, "owner.json"), "utf8")); } catch { owner = undefined; }
-      if (owner?.pid && pidAlive(owner.pid) && Date.now() < deadline) { pause(50); continue; }
+      // Missing/unreadable owners also occur between mkdir and publication,
+      // and while the holder removes its directory. Wait without touching it.
+      const remaining = deadline - Date.now();
+      if (remaining > 0) { pause(Math.min(50, remaining)); continue; }
       throw busy(!owner ? "its owner is not readable yet or the file is missing" : pidAlive(owner.pid) ? `pid ${owner.pid} holds it` : `its owner pid ${owner.pid} is gone`);
     }
   }