@awebai/oats 0.34.3 → 0.35.0

package/lib/core.mjs

@@ -54,7 +54,8 @@ async function materializePreparedDefault(prepared, home) { const m = await impo
 // (manifest, settings, origin, trust; no skills/inject since the copies are not
 // there yet) and REBUILT after materialize against what actually landed. Static
 // import: instance-resolution.mjs does not depend on core.mjs (no cycle).
-import { toCapabilityRows } from "./instance-resolution.mjs";
+import { cloneRemoteFor, toCapabilityRows } from "./instance-resolution.mjs";
+import { GIT_FETCH_TIMEOUT_MS, GIT_TIMEOUT_MS, gitEnv } from "./remote.mjs";
 import { loadLocal } from "./workspace.mjs";
 import { parseConfigData } from "./config-data.mjs";
 import { renderInstructionText } from "./instruction-composition.mjs";
@@ -3056,7 +3057,7 @@ function* spawnBody(root, agent, o = {}) {
   // K6: everything a spawn decides is decided by here — and nothing has been
   // touched. Branch/base for a worktree are named now (not after mkdir) so the
   // preview and the apply agree on them; `o.baseRef` selects the start point.
-  let plannedBranch = null, plannedBase = null;
+  let plannedBranch = null, plannedBase = null, observedBase = null;
   if (work === "worktree") {
     plannedBranch = o.branch || `agents/${instance}`;
     // Validity is Git's own rule (check-ref-format), not a stricter charset:
@@ -3065,10 +3066,17 @@ function* spawnBody(root, agent, o = {}) {
     try { execFileSync("git", ["check-ref-format", "--branch", plannedBranch], { stdio: ["ignore", "pipe", "pipe"] }); }
     catch { throw oatsError("E_BAD_ARGS", `branch ${JSON.stringify(plannedBranch)} is not a valid branch name`); }
     if (shInTry(repoAbs, `git rev-parse --verify --quiet ${shq("refs/heads/" + plannedBranch)}`) !== undefined) throw oatsError("E_BRANCH_EXISTS", `branch ${plannedBranch} already exists in ${repoAbs}; choose another name or reuse it deliberately`);
-    const baseRef = o.baseRef || "HEAD";
-    const baseOid = shInTry(repoAbs, `git rev-parse --verify --quiet ${shq(baseRef + "^{commit}")}`);
-    if (baseOid === undefined) throw oatsError("E_BASE_UNKNOWN", `base ${JSON.stringify(baseRef)} does not resolve to a commit in ${repoAbs}`);
-    plannedBase = { ref: baseRef, oid: baseOid };
+    // Without --base, a clone of the soul's repository branches from the commit this spawn observed it at
+    // (the one the resolution, and so the decision, binds), never from what the clone has checked out: a
+    // clone is often a human's checkout or a shared reference, far behind (awebai/oats#445).
+    observedBase = o.baseRef ? null : observedSoulBase(o.prepared, repoAbs);
+    if (observedBase) plannedBase = { ref: observedBase.key, oid: observedBase.oid };
+    else {
+      const baseRef = o.baseRef || "HEAD";
+      const baseOid = shInTry(repoAbs, `git rev-parse --verify --quiet ${shq(baseRef + "^{commit}")}`);
+      if (baseOid === undefined) throw oatsError("E_BASE_UNKNOWN", `base ${JSON.stringify(baseRef)} does not resolve to a commit in ${repoAbs}`);
+      plannedBase = { ref: baseRef, oid: baseOid };
+    }
   }
   // The decision a confirmation binds: placement AND what would actually
   // launch (inherited defaults re-resolved at apply must not drift silently).
@@ -3132,6 +3140,9 @@ function* spawnBody(root, agent, o = {}) {
     const fresh = buildDecision();
     if (fresh.revision !== o.expectDecision) throw Object.assign(oatsError("E_DECISION_STALE", `the previewed decision changed (${o.expectDecision} → ${fresh.revision}): ${fresh.instance}${plannedBase ? ` from ${plannedBase.ref}@${plannedBase.oid.slice(0, 12)}` : ""}; preview again`), { decision: fresh });
   }
+  // The observed base must be in the clone before anything is placed; a commit that cannot be fetched
+  // refuses the spawn, never falling back to the clone's own branch.
+  if (observedBase) fetchObservedBase(repoAbs, observedBase);
   // Backend PRESENCE is a prerequisite, checked before anything is placed (M1):
   // an absent tmux binary must fail with nothing created, never after a
   // populated home exists.
@@ -3668,7 +3679,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const moduleSkills = (materializeOutcome?.skills || []).map((row) => ({ name: row.name, source: `module:${row.module}`, from: join(home, row.from) }));
     const meta = {
       agent: agent.name, kind: agent.kind || "persistent", instance, home, soulDir: homeSoulTarget,
-      repo: repoAbs, work, branch, harness, model: model || undefined, modelFrom: modelFromOf(launchSelection.modelSource, { at: "spawn" }) ?? undefined,
+      repo: repoAbs, work, branch, ...(plannedBase ? { base: plannedBase } : {}), harness, model: model || undefined, modelFrom: modelFromOf(launchSelection.modelSource, { at: "spawn" }) ?? undefined,
       // Feature launch-preference: the layer that decided this launch, and the soul's own preference then.
       launchFrom: launchChoice.from, launchAt: launchChoice.at, launchDeclared: launchChoice.declared,
       ...(yolo !== undefined ? { yolo } : {}),
@@ -4108,6 +4119,36 @@ function sessionDirectoryGuard(home) {
   return check;
 }
 
+/** The commit a worktree spawn of a workspace soul observed its repository at, when `repoAbs` is a clone of
+ *  that repository: { key, oid, remote } (the clone's remote that names it), else null (a package soul, or a
+ *  --repo that is not a clone of the soul's repository: the clone's HEAD stays the base). */
+function observedSoulBase(prepared, repoAbs) {
+  const entry = prepared?.soulEntry;
+  if (!entry || typeof entry.package === "string" || typeof entry.repoKey !== "string") return null;
+  const oid = entry.memberCommit ?? entry.commit;
+  if (typeof oid !== "string" || !/^[0-9a-f]{40,64}$/.test(oid)) return null;
+  const remote = cloneRemoteFor(repoAbs, entry.repoKey);
+  return remote ? { key: entry.repoKey, oid, remote } : null;
+}
+
+/** Make the observed base present in the clone: fetched by id from the remote that names the soul's
+ *  repository, never prompting (remote.mjs's git environment), and touching no branch, remote-tracking ref,
+ *  FETCH_HEAD or work tree of the clone. */
+function fetchObservedBase(repoAbs, { key, oid, remote }) {
+  const env = gitEnv();
+  const present = () => spawnSync("git", ["-C", repoAbs, "cat-file", "-e", `${oid}^{commit}`], { stdio: "ignore", env, timeout: GIT_TIMEOUT_MS }).status === 0;
+  if (present()) return;
+  const r = spawnSync("git", ["-C", repoAbs, "fetch", "--quiet", "--no-tags", "--no-write-fetch-head", "--no-recurse-submodules", "--end-of-options", remote, oid],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env, timeout: GIT_FETCH_TIMEOUT_MS });
+  if (r.status === 0 && present()) return;
+  const lines = String(r.stderr || "").split("\n").map((l) => l.trim()).filter(Boolean);
+  const why = r.error?.code === "ETIMEDOUT" ? "timeout" : (lines.find((l) => /^(fatal|error):/.test(l)) ?? lines[0] ?? `git fetch exited ${r.status ?? r.signal}`);
+  // A server that only serves advertised refs (protocol v0 without allowAnySHA1InWant) refuses a commit its
+  // branches have moved past, and the fetch by hand fails the same way: --base is then the way on.
+  throw Object.assign(oatsError("E_REMOTE_UNREADABLE", `cannot fetch commit ${oid.slice(0, 12)} of ${key} into the clone ${repoAbs} from its remote ${remote} (${why}); the instance branch starts at the commit this spawn observed, never at the clone's own branch — fetch it (git -C ${shq(repoAbs)} fetch --end-of-options ${shq(remote)} ${oid}) or name a start point with --base; nothing was created`),
+    { details: { repo: repoAbs, repoKey: key, commit: oid, remote } });
+}
+
 /** A failed spawn's compare-and-delete of the branch it created at `oid`: `git update-ref -d` refuses
  *  atomically if the tip moved (something was committed there), and the branch is then kept. `run`
  *  answers { ok, out, status, err }. → what is still owed, as messages ([] when the branch is gone). */
@@ -4121,7 +4162,7 @@ function deleteBranchAsCreated(run, repoAbs, branch, oid) {
 }
 /** Retain the home and its cleanup receipt when spawn compensation or retirement
  * cannot finish. Keeping the original credentials makes cleanup retryable. */
-function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason, directoryPreservation = false, directoryHome = realPathOrNearest(home) }) {
+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) }) {
   const marker = {
       // `reason` is optional and DEFAULTS to the spawn wording, so every existing
       // caller is byte-identical; only a caller that supplies one differs. The
@@ -4141,7 +4182,7 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
         // instance.json may be only the pre-hook stub, which records neither.
         ...(typeof soulDir === "string" && soulDir ? { soulDir } : {}),
         ...(typeof soulId === "string" && soulId ? { soulId } : {}),
-        outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit], ...(directoryPreservation ? { directory: true } : {}) },
+        outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit], ...(directoryPreservation ? { directory: true } : {}), ...(orphanedWork ? { orphanedWork: true } : {}) },
         capabilityRuntime: (resolvedCfg.capabilities || []).map((cap) => ({
           id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings, settingsOrigins: cap.settingsOrigins ?? {},
           hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
@@ -4212,7 +4253,11 @@ function usableCleanupDescriptor(marker) {
   if (c.capabilityMeta !== undefined && !isPlainObject(c.capabilityMeta)) return false;
   const directoryDebt = c.outstanding?.directory === true && c.work === "directory";
   if (c.outstanding?.directory !== undefined && !directoryDebt) return false;
-  if (!Array.isArray(c.capabilityRuntime) || (!c.capabilityRuntime.length && !directoryDebt)) return false;
+  // A worktree directory whose git admin entry is gone (awebai/oats#444) is debt too: the retry proves it
+  // cleared when the directory is no longer there or has its admin entry back.
+  const orphanDebt = c.outstanding?.orphanedWork === true && c.work === "worktree";
+  if (c.outstanding?.orphanedWork !== undefined && !orphanDebt) return false;
+  if (!Array.isArray(c.capabilityRuntime) || (!c.capabilityRuntime.length && !directoryDebt && !orphanDebt)) return false;
   if (!c.capabilityRuntime.every((cap) => isPlainObject(cap) && nonEmptyString(cap.id))) return false;
   if (!isPlainObject(c.outstanding) || !Array.isArray(c.outstanding.hooks) || !Array.isArray(c.outstanding.git)) return false;
   if (!c.outstanding.hooks.every(nonEmptyString)) return false;
@@ -4224,7 +4269,7 @@ function usableCleanupDescriptor(marker) {
   // obligation of zero. Directory preservation is also real debt: the retry's
   // independent-authority inspection and verified snapshots must succeed even
   // when no capability has a retire hook. It is never a Git/shared-work escape.
-  if (!c.outstanding.hooks.length && !c.outstanding.git.length && !directoryDebt) return false;
+  if (!c.outstanding.hooks.length && !c.outstanding.git.length && !directoryDebt && !orphanDebt) return false;
   // The retry must be ABLE to rerun what it must prove: an outstanding hook whose
   // capability is not in the set could never run, so the quarantine would never
   // clear — and the home would be unremovable without --force.
@@ -4301,6 +4346,21 @@ function worktreeRef(work) {
   try { branch = execFileSync("git", ["-C", work, "symbolic-ref", "--quiet", "--short", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim() || null; } catch { branch = null; }
   return { branch, oid };
 }
+/** A worktree directory whose git admin entry is gone: no `.git`, an unreadable one, or a gitfile naming an
+ *  admin directory that no longer exists. Read from the gitfile, not asked of git, which would walk up into
+ *  whatever repository encloses the home. A `.git` directory is a repository of its own, not this case. */
+function worktreeAdminMissing(work) {
+  const dotGit = join(work, ".git");
+  let stat;
+  try { stat = lstatSync(dotGit); } catch { return true; }
+  if (stat.isDirectory()) return false;
+  if (!stat.isFile()) return true;
+  let text;
+  try { text = readFileSync(dotGit, "utf8"); } catch { return true; }
+  const m = /^gitdir:\s*(.+?)\s*$/m.exec(text);
+  if (!m) return true;
+  return !existsSync(join(resolve(work, m[1]), "HEAD"));
+}
 function worktreeStatus(repo) {
   try {
     return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
@@ -5172,7 +5232,7 @@ export function startInstanceSession(home, o = {}) {
   }
 }
 
-function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directory = false } = {}) {
+function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directory = false, orphanedWork = false } = {}) {
   if (directory) assertDirectoryRoots(home);
   const classes = [];
   let baseline;
@@ -5213,7 +5273,7 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directo
     .update(fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true }))
     .update("\0").update(directory ? (directoryFingerprint || "missing") : isWorktree && existsSync(work) ? worktreeStatus(work) : "")
     .digest("hex");
-  return { classes: [...new Set(classes)], home, work, directory, directoryFingerprint, stateFingerprint, branchExists: branchCommits !== null, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
+  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, directoryFingerprint, stateFingerprint, branchExists: branchCommits !== null, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
 }
 
 function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
@@ -5418,9 +5478,11 @@ function preserveRetirementWork(observation, meta, instance) {
     // snapshot, not another copy of an otherwise disposable clean worktree.
     // In-progress Git operations retain the full standalone recovery even
     // when porcelain status has no changed paths.
-    let homeOnly = observation.classes.length === 1 && observation.classes[0] === "changed instance-home bytes"
-      && meta.work === "worktree" && existsSync(observation.work);
-    if (homeOnly) {
+    // An orphaned work directory (no git admin entry) stays where it is, never moved or removed, and git
+    // cannot read it: only the home is snapshotted.
+    let homeOnly = observation.orphanedWork === true || (observation.classes.length === 1 && observation.classes[0] === "changed instance-home bytes"
+      && meta.work === "worktree" && existsSync(observation.work));
+    if (homeOnly && !observation.orphanedWork) {
       const gitDir = execFileSync("git", ["-C", observation.work, "rev-parse", "--absolute-git-dir"], { encoding: "utf8", maxBuffer: GIT_MAX_BUFFER }).trim();
       homeOnly = !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
     }
@@ -5724,10 +5786,20 @@ export function retireInstance(root, name, o = {}) {
   if (self && (!o.keepDir || herdrHome)) {
     return scheduleDeferredSelfRetirement(root, found, name, o, session);
   }
+  // A worktree directory whose git admin entry is gone cannot be inspected, moved or removed through git, and
+  // what it holds may exist nowhere else: it is never removed. Without --force the hooks still run and it is
+  // an incomplete item; --force (which removes the home it sits in) refuses before anything runs.
+  const orphanedWork = meta.work === "worktree" && existsSync(workPath) && worktreeAdminMissing(workPath);
+  if (orphanedWork && o.force) {
+    throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the work directory ${workPath} has no git admin entry in ${meta.repo ?? "its repository"}, so retiring the home would delete it with whatever it holds; move it out or delete it by hand, then retire again; nothing was run or removed`);
+  }
+  const orphanItem = orphanedWork ? `git worktree ${workPath}: its admin entry is missing; the directory is kept — move it out or delete it by hand, then retire again` : null;
+  const inspectableWorktree = isWorktree && !orphanedWork;
   // First inspection is non-destructive. Only after it succeeds may OATS quiesce
   // the managed harness; recovery copying never races a live managed Pi.
+  const owesWorktree = !!quarantine && (quarantine.cleanup.outstanding?.git || []).includes("worktree");
   const branchDeletion = { delete: !!(o.deleteBranch || quarantine), repo: meta.repo, branch: meta.branch };
-  const initialObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
+  const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { branchDeletion, directory, orphanedWork });
   // Harness identity is destructive authority. The mutable child metadata may
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
@@ -5773,7 +5845,7 @@ export function retireInstance(root, name, o = {}) {
       if (!/no server running|failed to connect|can't find session|no sessions/i.test(detail)) throw oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${detail || "tmux inspection failed"}`);
     }
   }
-  const stableObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
+  const stableObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { branchDeletion, directory, orphanedWork });
   const workRecoveries = [];
   if (stableObservation.classes.length) workRecoveries.push(preserveRetirementWork(stableObservation, meta, name));
   let workRecovery = workRecoveries.at(-1);
@@ -5821,11 +5893,38 @@ export function retireInstance(root, name, o = {}) {
         ordinaryIncomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
       }
     }
+    if (orphanItem) ordinaryIncomplete.push(orphanItem);
+  }
+  // A quarantine retry's outcome apart from Git: what the hooks it reran left undone, and what they owed and
+  // did not run. Known before the worktree step, which waits for it.
+  const retryFailures = [];
+  if (quarantine) {
+    for (const f of hookResults?.failures || []) retryFailures.push(`retire hook ${f.capability}: ${f.message}`);
+    for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
+      if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
+        retryFailures.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""}`);
+      }
+    }
+    // The decisive check: not "did anything fail" but "did the work that was
+    // outstanding actually happen". A retry that resolves zero capabilities —
+    // because the descriptor named none, or config drifted since the spawn —
+    // otherwise reports a clean sweep it never performed, and the home and its
+    // credential go with it (reviewer-dd03a98).
+    const ran = new Set(hookResults?.order || []);
+    for (const capId of quarantine.cleanup.outstanding?.hooks || []) {
+      if (ran.has(capId)) continue;
+      const cap = (meta.capabilityRuntime || []).find((c) => c.id === capId);
+      retryFailures.push(cap && !cap.hooks?.retire
+        ? `${capId}: declares no retire hook, so OATS cannot verify or undo what its failed spawn hook may have created — clean up by hand, then remove the home with \`oats retire ${name} --force\``
+        : `retire hook ${capId}: did not run on this retry, so the cleanup it owed is unverified`);
+    }
+    if (!hookResults) retryFailures.push("retire hooks could not be rerun (cleanup descriptor lost its context repo)");
+    if (orphanItem) retryFailures.push(orphanItem);
   }
 
   // Hooks are allowed to mutate the inspected tree, so inspect again after
   // them and preserve a separately verified post-hook snapshot when needed.
-  const finalObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
+  const finalObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { branchDeletion, directory, orphanedWork });
   if (finalObservation.classes.length && finalObservation.stateFingerprint !== stableObservation.stateFingerprint) {
     workRecoveries.push(preserveRetirementWork(finalObservation, meta, name));
     workRecovery = workRecoveries.at(-1);
@@ -5890,14 +5989,23 @@ export function retireInstance(root, name, o = {}) {
   // recorded in the receipt. `discardWorktree` restores removal; branch
   // deletion uses the VERIFIED current ref of the worktree, never the
   // spawn-time recorded name. A failed move keeps the home (fail closed).
+  // The worktree step runs only once nothing else is outstanding (awebai/oats#444): a hook that did not finish
+  // may need the worktree, and its retry needs the home, the worktree and its admin entry exactly as they
+  // were. --force removes the home regardless, so the step runs first and no admin entry is left dangling.
+  // A failed spawn's quarantine that owes the worktree removes it; any other retire retains it unless
+  // --discard-worktree or --delete-branch. An orphaned work directory is never touched.
+  const outstandingBeforeWorktree = quarantine ? retryFailures : ordinaryIncomplete;
+  const worktreeStep = isWorktree && !!meta.repo && !orphanedWork;
+  const worktreeDeferred = worktreeStep && existsSync(workPath) && outstandingBeforeWorktree.length > 0 && !o.force;
+  const keptForRetry = worktreeDeferred ? `git worktree ${workPath}: kept for the retry; outstanding: ${outstandingBeforeWorktree.join("; ")}` : null;
   let retention = null;
-  if (isWorktree && meta.repo) {
+  if (worktreeStep && !worktreeDeferred) {
     const ref = existsSync(workPath) ? (() => { try { return worktreeRef(workPath); } catch { return { branch: null, oid: null }; } })() : { branch: meta.branch ?? null, oid: null };
     const verifiedBranch = ref.branch;
     // A branch cannot be deleted while a worktree has it checked out, so
     // --delete-branch implies discarding the worktree (which is what every
     // caller of it meant: clean up everything). Plain retire retains.
-    if (o.discardWorktree || o.deleteBranch || quarantine) {
+    if (o.discardWorktree || o.deleteBranch || owesWorktree) {
       shTry(`git -C ${shq(meta.repo)} worktree remove --force ${shq(workPath)}`);
       shTry(`git -C ${shq(meta.repo)} worktree prune`);
       retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
@@ -5947,6 +6055,7 @@ export function retireInstance(root, name, o = {}) {
   // spawn rollback uses. Two copies of this logic is how a previous divergence
   // happened (see quarantineInstanceHome), so there is still exactly one.
   if (!quarantine && !self && ordinaryIncomplete.length) {
+    if (keptForRetry) ordinaryIncomplete.push(keptForRetry);
     const outstandingHooks = new Set();
     for (const f of hookResults?.failures || []) outstandingHooks.add(f.capability);
     for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
@@ -5960,12 +6069,14 @@ export function retireInstance(root, name, o = {}) {
       repoAbs: meta.repo, work: meta.work, branch: meta.branch,
       resolvedCfg: { capabilities: meta.capabilityRuntime || [] },
       hookMeta: meta.capabilityMeta || {}, compensationMeta: hookResults?.meta || {},
-      reason: "retire hook reported incomplete cleanup",
+      orphanedWork: !!orphanedWork,
+      reason: outstandingHooks.size ? "retire hook reported incomplete cleanup" : "the work directory has no git admin entry",
     });
     stillIncomplete = ordinaryIncomplete;
   }
   if (quarantine) {
-    const failures = (hookResults?.failures || []).map((f) => `retire hook ${f.capability}: ${f.message}`);
+    const failures = [...retryFailures];
+    if (keptForRetry) failures.push(keptForRetry);
     // The quarantine may exist BECAUSE Git cleanup failed, so a retry has to
     // redo those steps and verify them — not just rerun hooks. A branch is never
     // deleted here: only --delete-branch deletes one (the verified branch, above).
@@ -5974,14 +6085,18 @@ export function retireInstance(root, name, o = {}) {
         try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
         catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
       };
-      const wtCanonical = realPathOrNearest(workPath);
-      gitProbe(["git", "-C", meta.repo, "worktree", "remove", "--force", workPath]);
-      gitProbe(["git", "-C", meta.repo, "worktree", "prune"]);
-      const wtProbe = gitProbe(["git", "-C", meta.repo, "worktree", "list", "--porcelain", "-z"]);
-      if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
-      else {
-        const registered = wtProbe.out.split("\0").filter((f) => f.startsWith("worktree ")).map((f) => f.slice("worktree ".length));
-        if (registered.includes(wtCanonical)) failures.push(`git worktree ${wtCanonical}: still registered`);
+      // A worktree this retry removed (the step above ran) must be verified gone; one it retained or kept for
+      // the next retry stays registered by design.
+      if (retention?.worktree === "removed") {
+        const wtCanonical = realPathOrNearest(workPath);
+        gitProbe(["git", "-C", meta.repo, "worktree", "remove", "--force", workPath]);
+        gitProbe(["git", "-C", meta.repo, "worktree", "prune"]);
+        const wtProbe = gitProbe(["git", "-C", meta.repo, "worktree", "list", "--porcelain", "-z"]);
+        if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
+        else {
+          const registered = wtProbe.out.split("\0").filter((f) => f.startsWith("worktree ")).map((f) => f.slice("worktree ".length));
+          if (registered.includes(wtCanonical)) failures.push(`git worktree ${wtCanonical}: still registered`);
+        }
       }
       // The branch is a debt only when the failed spawn's rollback still owes its deletion, or when the
       // operator asked for it (--delete-branch); then it must be verified gone, and a branch kept is said.
@@ -6004,30 +6119,11 @@ export function retireInstance(root, name, o = {}) {
           : `git branch ${meta.branch}: kept; the failed spawn created it; pass --delete-branch to delete it`);
       }
     }
-    for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
-      if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
-        failures.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""}`);
-      }
-    }
-    // The decisive check: not "did anything fail" but "did the work that was
-    // outstanding actually happen". A retry that resolves zero capabilities —
-    // because the descriptor named none, or config drifted since the spawn —
-    // otherwise reports a clean sweep it never performed, and the home and its
-    // credential go with it (reviewer-dd03a98).
-    const ran = new Set(hookResults?.order || []);
     // Git debt is proven by the verification block above, which only runs for a
     // worktree in a known repo. If it could not run, the debt stands.
     if (quarantine.cleanup.outstanding?.git?.length && !(meta.work === "worktree" && meta.repo)) {
       failures.push(`git ${quarantine.cleanup.outstanding.git.join(", ")}: not re-verified on this retry, so the cleanup they owed is unverified`);
     }
-    for (const capId of quarantine.cleanup.outstanding?.hooks || []) {
-      if (ran.has(capId)) continue;
-      const cap = (meta.capabilityRuntime || []).find((c) => c.id === capId);
-      failures.push(cap && !cap.hooks?.retire
-        ? `${capId}: declares no retire hook, so OATS cannot verify or undo what its failed spawn hook may have created — clean up by hand, then remove the home with \`oats retire ${name} --force\``
-        : `retire hook ${capId}: did not run on this retry, so the cleanup it owed is unverified`);
-    }
-    if (!hookResults) failures.push("retire hooks could not be rerun (cleanup descriptor lost its context repo)");
     if (failures.length) {
       stillIncomplete = failures;
       try {
@@ -6053,7 +6149,7 @@ export function retireInstance(root, name, o = {}) {
     rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
   }
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, retention, worktreeRemoved: isWorktree && retention?.worktree !== "retained", branchDeleted: !!(retention?.branchDeleted), removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
+  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, retention, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: !!(retention?.branchDeleted), removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
     const w = [...(hookResults?.warnings || [])];
     if (isCapturedHome(meta) && !quarantine) {
       // A captured home retires through the workspace path; its captured retire hooks do not

package/lib/instance-resolution.mjs

@@ -339,22 +339,36 @@ function canonicalCloneKey(written) {
   return s;
 }
 
-/** The remote urls a clone carries (any remote, not only origin), parsed to their
- *  repo keys. Not a git repo → null. */
-function cloneRemoteKeys(path) {
+/** The remotes a clone carries (any remote, not only origin), each with its url parsed
+ *  to a repo key: [{ name, key }]. Not a git repo → null. */
+function cloneRemotes(path) {
   const git = (argv) => spawnSync("git", ["-C", path, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
   const inside = git(["rev-parse", "--git-dir"]);
   if (inside.status !== 0) return null;
-  const cfg = git(["config", "--get-regexp", "^remote\\..*\\.url$"]);
-  const keys = [];
+  // -z: each entry is `<key>\n<value>\0`, so a value holding a newline cannot read as another entry.
+  const cfg = git(["config", "-z", "--get-regexp", "^remote\\..*\\.url$"]);
+  const remotes = [];
   if (cfg.status === 0) {
-    for (const line of cfg.stdout.split("\n")) {
-      const url = line.replace(/^\S+\s+/, "").trim();
+    for (const entry of cfg.stdout.split("\0")) {
+      const nl = entry.indexOf("\n");
+      if (nl < 0) continue;
+      const key = entry.slice(0, nl), url = entry.slice(nl + 1).trim();
       if (!url) continue;
-      try { keys.push(parseRepoRef(url).key); } catch { keys.push(`?/${url}`); }
+      const name = key.slice("remote.".length, -".url".length);
+      try { remotes.push({ name, key: parseRepoRef(url).key }); } catch { remotes.push({ name, key: `?/${url}` }); }
     }
   }
-  return keys;
+  return remotes;
+}
+
+/** The remote urls a clone carries, parsed to their repo keys. Not a git repo → null. */
+function cloneRemoteKeys(path) {
+  return cloneRemotes(path)?.map((r) => r.key) ?? null;
+}
+
+/** The name of the clone's remote whose url names `key`, or null (no such remote, or not a git repo). */
+export function cloneRemoteFor(path, key) {
+  return (cloneRemotes(path) || []).find((r) => sameRepoKey(r.key, key))?.name ?? null;
 }
 
 /** Two repo keys name the same repository. Hosted keys compare literally; `local/<abs>`

package/lib/remote.mjs

@@ -293,7 +293,9 @@ export function sshCommand() {
   return sshCommandCache;
 }
 
-function gitEnv() {
+/** The environment every git child of the kernel that may reach a remote runs under: it never prompts (no
+ *  terminal prompt, askpass refused, ssh in BatchMode) and never fetches a missing object on its own. */
+export function gitEnv() {
   return {
     ...process.env,
     GIT_TERMINAL_PROMPT: "0",

package/package-catalog.json

@@ -3,7 +3,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v4.0.7",
+      "ref": "v4.1.0",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

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

package/packages/record/README.md

@@ -249,3 +249,58 @@ source custody. The library alternative is `sessionsForHome(home, { roots })`:
 unspecified formats are excluded, and missing supplied roots fail. Synthetic
 standalone tests must choose one of these explicitly, not masquerade as a
 managed native launch. Background capture without `--home` is unchanged.
+
+## One session file: `capture --file`
+
+```text
+capture --file <path> --format cc|pi|codex --home <instance home> [--owner <name>] [--json]
+```
+
+Captures ONE session file, for example an archived session that the
+`--home` sweep can no longer find, exactly as `--home` capture of that
+instance would capture it. It runs under the capture lock, as a final pass,
+with the ignore rules applied. The stream is `<owner>~<source>.<session id>`,
+the same identity `--home` capture writes. So the same session captured
+either way, or again with `--file`, appends nothing.
+
+- **The owner is explicit.** It is `--owner` or `TURN_RECORD_OWNER`; the
+  hostname is never assumed. `--home` must be an OATS instance home (an
+  `instance.json` naming an instance). It is recorded in the receipt, not
+  checked against the file's recorded cwd.
+- **The format is stated, never sniffed.** The file must carry that format's
+  session header somewhere in it:
+  - `cc`: a record with a `cwd`, and no other format's session header anywhere
+    in the file (a cc transcript never holds one);
+  - `pi`: the `session` record;
+  - `codex`: `session_meta`.
+- **The session id comes from the file name**, as for live capture: the cc
+  basename, the part of a pi name after its last `_`, or a codex name's
+  trailing uuid. A renamed file lands in another stream.
+- **One regular file, read once.** It is opened with `O_NOFOLLOW` and
+  `O_NONBLOCK` and fstat'ed. A symlink, FIFO, socket, device or directory is
+  refused. The bytes read from that descriptor are the ones captured and
+  hashed.
+
+`--json` prints the receipt:
+`{home, owner, file, format, instance, thread, stream, sessionId, turns,
+firstTurnId, lastTurnId, appended, skipped, held, incomplete, failed, ignored,
+status, complete, sha256, issues?}`. `sha256` is of the bytes captured;
+`issues` (`[{source, path, reason, offset}]`, present when the result is
+incomplete or held) says why. As for
+`--home`, `complete` is true only with no hold, no incomplete tail and no
+failure. A lock skip, a hold (no timestamp yet) and an incomplete tail (torn
+or invalid UTF-8) exit 0 with `complete: false`. Without `--json`, the output
+is one line.
+
+Anything that binds nothing is an error,
+`{status: "failed", complete: false, code, error}`:
+
+| code | exit | when |
+|---|---|---|
+| `E_USAGE` | 2 | a missing or invalid flag, a non-instance `--home`, no explicit owner, a second `--file`, another mode |
+| `E_FILE_UNREADABLE` | 1 | the file cannot be opened or read |
+| `E_NOT_REGULAR_FILE` | 1 | a symlink, FIFO, socket, device or directory |
+| `E_IGNORED` | 1 | a capture ignore rule excludes the file; nothing was opened, read or written |
+| `E_NO_TURNS` | 1 | no records: an empty file, or only blank lines |
+| `E_FORMAT` | 1 | records, but no session header of the stated format; the message names the format whose header it does carry |
+| `E_CAPTURE_FAILED` | 1 | the pass failed (`appended: null`: part of the file may be in the record) |