@awebai/oats 0.34.3 → 0.34.4

package/bin/oats.mjs

@@ -2256,6 +2256,8 @@ async function spawnCmd() {
     if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
     if (e?.code === "E_CHILD_SPAWNS_DISABLED") { bail(e.code, e.message, { parent: e.parent, policy: e.policy }); throw e; }
     if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
+    // The observed base could not be fetched into the clone: the clone, the repository and the commit travel along.
+    if (e?.code === "E_REMOTE_UNREADABLE" && e.details?.commit) { bail(e.code, e.message, e.details); throw e; }
     // K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
     if (e?.code === "E_DECISION_STALE") { bail(e.code, e.message, { decision: e.decision }); throw e; }
     if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
@@ -2283,7 +2285,7 @@ async function spawnCmd() {
     // Desktop CLI API v1 spawn result — a FIXED shape (see docs/desktop-cli-api.md).
     jsonOk({
       instance: r.instance, agent: r.agent, home: r.home, work: r.work,
-      branch: r.branch || null, launched: r.launched, warnings: r.warnings || [],
+      branch: r.branch || null, base: r.base ?? null, launched: r.launched, warnings: r.warnings || [],
       ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
       tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
       model: r.model || null, parent: r.parentInstance || null,
@@ -2299,6 +2301,7 @@ async function spawnCmd() {
   }
   console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
   console.log(`  home:   ${shortPath(r.home)}`);
+  if (r.base) console.log(`  base:   ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
   if (wakeSchedule) console.log(`  wake:   schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
   if (wakeScheduleError) console.error(`  wake:   NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
   if (!r.launched) console.log(`  launch: oats session start --home ${shellQuote(r.home)}`);

package/docs/desktop-cli-api.md

@@ -1394,13 +1394,13 @@ it to a temporary copy (`soulFetched: true`).
  "settingsOrigins":{"nw-tools":{},"oats.okf":{"/owns":{"kind":"soul","at":"soul.yaml#/knowledge"}}},
  "spawnPreviewApi":2,"preview":true,"agent":"rm","kind":"persistent","instance":"rm-api","home":"/w/agents/rm/instances/rm-api",
  "repo":"/w/agents-repo","work":"worktree","subject":{"soul":"rm","agentsRoot":null,"dir":"/w"},
- "decision":{"instance":"rm-api","home":"/w/agents/rm/instances/rm-api","branch":"agents/rm-api","base":{"ref":"HEAD","oid":"66566512…"},
+ "decision":{"instance":"rm-api","home":"/w/agents/rm/instances/rm-api","branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},
              "effective":{"repo":"/w/agents-repo","work":"worktree","harness":"pi","model":null,"launchConfig":null,"yolo":null,"backend":"tmux",
                           "childSpawns":true,"relation":null,"providers":{"nw-tools":{},"oats.okf":{"owns":"rm"}}},
              "resolution":"abacbdb5a7975098d77007c8","revision":"c557d8ec9a272ba1c1739dc3"},
  "preflight":{"status":"complete","budgetMs":20000,"elapsedMs":53},"backendStatus":{"name":"tmux","installed":true,"started":false},
  "harness":"pi","model":null,"modelSource":"native default","launchConfig":null,"backend":"tmux",
- "branch":"agents/rm-api","base":{"ref":"HEAD","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
+ "branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
  "executable":"/usr/local/bin/pi",
  "capabilities":[{"name":"nw-tools","origin":"member:github.com/nw/agents@66566512…"},{"name":"oats.okf","origin":"package:oats.okf@2.1.3"}],
@@ -1415,8 +1415,11 @@ it to a temporary copy (`soulFetched: true`).
   else `null`) are canonical: never derive paths.
 - `repo`: `--repo`, else the `clones:` entry, else `<deployment>/<member>`.
 - `branch` defaults to `agents/<instance>` (`--branch` overrides); `base` is
-  `--base` (default `HEAD`) resolved to `oid`. `E_BRANCH_EXISTS` and
-  `E_BASE_UNKNOWN` refuse preview and apply alike.
+  `--base` resolved to `oid`. Without `--base`, when `repo` is a clone of the
+  soul's repository, `base` is `{ref: <repo key>, oid: <the commit the spawn
+  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
+  cannot be); otherwise `HEAD`. `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN` refuse
+  preview and apply alike.
 - `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
 
 **Launch.**
@@ -1534,7 +1537,8 @@ with `--expect-decision` records the key and decision in `instance.json`.
 **Result** (`oats spawn <soul> … --json`):
 
 ```json
-{"instance":"rm-api","agent":"rm","home":"/w/agents/rm/instances/rm-api","work":"worktree","branch":"agents/rm-api","launched":true,"warnings":[],
+{"instance":"rm-api","agent":"rm","home":"/w/agents/rm/instances/rm-api","work":"worktree","branch":"agents/rm-api",
+ "base":{"ref":"github.com/nw/agents","oid":"66566512…"},"launched":true,"warnings":[],
  "tmux":{"session":"oats-agents","window":"rm-api"},"backend":"tmux","repo":"/w/agents-repo","harness":"pi","model":null,"parent":null,"sibling":null,"relation":null,
  "spawnOrigin":"operator","attach":"tmux attach -t oats-agents","decision":{"instance":"rm-api","revision":"c557d8ec9a272ba1c1739dc3"},"replayed":false,
  "wake":{"requested":false,"saved":null,"error":null},"launchConfig":null,
@@ -1544,7 +1548,8 @@ with `--expect-decision` records the key and decision in `instance.json`.
 
 (`decision` is abridged: it is the full bound decision.)
 
-- Always present: `instance, agent, home, work, branch, launched, warnings
+- Always present: `instance, agent, home, work, branch, base ({ref, oid}
+  the new branch started at; `null` without one), launched, warnings
   (array), tmux ({session, window} | null), backend ("tmux"), repo, harness,
   model, parent,
   sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
@@ -1608,7 +1613,8 @@ workspace-model fields (feature `instance-modules`):
 
 ```json
 {"agent":"rm","kind":"persistent","instance":"rm-api","home":"/w/agents/rm/instances/rm-api","soulDir":"/w/agents/rm/souls/66566512168e",
- "repo":"/w/agents-repo","work":"worktree","branch":"agents/rm-api","harness":"pi","modelFrom":"harness-default","spawnOrigin":"operator",
+ "repo":"/w/agents-repo","work":"worktree","branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},
+ "harness":"pi","modelFrom":"harness-default","spawnOrigin":"operator",
  "policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
  "modules":{"oats.okf":{"from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
                         "commit":"ab897841…","digest":"sha256-9a0e…","materializedAt":"2026-09-28T10:08:01.100Z"}},
@@ -1635,6 +1641,8 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
   the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
   `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
   `<home>/.agents/skills/<cap>/<skill>/`).
+- `base` (a worktree instance): `{ref, oid}`, the commit its branch started
+  at, as the spawn result states it (see Placement under the spawn preview).
 - `providers.<cap>`: the merged payload (`{}` when none).
 - `workspace`: `{key, name, deployment, commit, resolution, standalone, soul,
   layers}`. `name` is recorded, and every hook, command and operation of the
@@ -2023,8 +2031,15 @@ A first retire prints the **raw receipt**, not an envelope:
 
 - `retention`: `{worktree: "retained" | "removed" | "absent", movedTo?,
   branch, detachedAt?, recordedBranch, branchDeleted?,
-  branchDeletionSkipped?: {expected, actual, reason}}`, or `null` for a
-  non-worktree mode.
+  branchDeletionSkipped?: {expected, actual, reason}}`, or `null` when no
+  worktree step ran: a non-worktree mode, or a worktree kept for the retry.
+  A retire whose hooks left cleanup outstanding keeps the worktree exactly as
+  it was (with `worktreeRemoved: false`) and says why in `rollbackIncomplete`
+  (`git worktree <path>: kept for the retry; outstanding: …`); the retry does
+  the step once nothing else is outstanding. A work directory whose git admin
+  entry is gone is never touched: it is an incomplete item (`git worktree
+  <path>: its admin entry is missing; …`), and `--force` refuses it with
+  `E_WORK_PRESERVATION_FAILED`.
 - `--discard-worktree` removes the worktree. `--delete-branch` deletes the
   worktree's verified branch (re-verified at deletion time) and implies
   discarding; a mismatch deletes nothing and reports

package/docs/release-notes/v0.34.4.md

@@ -0,0 +1,51 @@
+# OATS 0.34.4
+
+## Fixed
+
+- **A worktree spawn branches from the member commit it observed, not from
+  the clone's stale local branch** (awebai/oats#445). When a member clone
+  (`clones:`, the convention path or `--repo`) was a human's checkout or a
+  shared reference, `oats spawn` cut the instance branch from whatever that
+  clone had checked out, often far behind the head the spawn had just
+  resolved the soul at, and nobody was told. Now:
+  - the branch starts at the commit the spawn observed for its decision. The
+    spawn fetches that commit by id into the clone, from the remote that names
+    the soul's repository;
+  - the clone's own branches, remote-tracking refs and work tree are never
+    moved;
+  - a commit that cannot be fetched refuses the spawn with
+    `E_REMOTE_UNREADABLE`, naming the clone and the commit. Nothing is created
+    and nothing falls back to the clone's branch;
+  - the spawn result states the start point: `base: <oid> (observed head of
+    <repo>)` in text and `base: {ref, oid}` in `--json`. `instance.json`
+    records it too.
+
+  `--base <ref>` still names an explicit start point in the clone, and a
+  `--repo` that is not a clone of the soul's repository still starts at its
+  `HEAD`.
+
+- **A retire whose hook reports incomplete cleanup leaves the worktree as it
+  was** (awebai/oats#444). The worktree used to be moved or removed before
+  the home was quarantined, so its git admin entry could be gone by the time
+  the retry needed it. The retry's work inspection then failed, and the hook
+  that asked to be retried could never run again. Now:
+  - the home is quarantined before any worktree step: the worktree, its admin
+    entry and the branch stay exactly as they were. `retire --json` reports
+    `retention: null` and `worktreeRemoved: false`, and `rollbackIncomplete`
+    says `git worktree <path>: kept for the retry; outstanding: …`;
+  - the retry does the worktree step only once nothing else is outstanding:
+    retain by default, remove with `--discard-worktree` or `--delete-branch`.
+    Only a failed spawn's quarantine that owes the worktree removes it;
+  - `--force` removes the home regardless, so it does the worktree step first
+    and leaves no admin entry pointing into a removed home;
+  - a work directory whose admin entry is gone is reported as incomplete, the
+    hooks still run, and the directory is never removed. `--force` refuses it
+    (`E_WORK_PRESERVATION_FAILED`) until you move it out or delete it by hand.
+    Upgrade before forcing: an older kernel's `--force` still removes such
+    a directory along with the home.
+
+- **The spawn's fetch of its base reads remote names safely** (follow-up to
+  #445): the remote is passed after `--end-of-options`, so a remote whose
+  name reads like an option is never taken as one, and remote urls are read
+  NUL-separated (`git config -z`), so a newline in one url cannot forge
+  another remote.

package/docs/souls-and-instances.md

@@ -432,6 +432,16 @@ retained home (plus the usual quarantine marker when hooks reported incomplete
 cleanup), shows in `oats status` and the Desktop as a failed deferred
 retirement, and is retried and cleared with `oats retire <instance>`.
 
+When a retire hook reports incomplete cleanup, the home is quarantined before
+any worktree step: the worktree, its git admin entry and the branch stay
+exactly as they were, so the retry can reach the hook and the work it needs.
+The retry does the worktree step only once nothing else is outstanding:
+retain by default, remove with `--discard-worktree` or `--delete-branch`.
+`--force` removes the home regardless, so it does the worktree step first. A
+work directory whose git admin entry is gone is never removed: the hooks still
+run, the home is kept, and `--force` refuses it until you move the directory
+out or delete it by hand.
+
 Retire never deletes a branch unless you pass `--delete-branch`, and then
 only the verified branch: not on a quarantine, its retry or `--force`. A
 spawn that fails deletes the branch it created only while the branch's tip
@@ -472,6 +482,21 @@ as `--repo`, then `oats-local.yaml` `clones:`, then `<deployment>/<member name>`
 (`E_CLONE_MISSING` / `E_CLONE_MISMATCH` otherwise — see
 [configuration.md](configuration.md)).
 
+The branch starts at the commit of the soul's repository that the spawn
+observed (the one it resolved the soul at), not at what the clone has checked
+out: the clone may be a human's checkout or a shared reference, far behind.
+The spawn fetches that commit by id into the clone from the remote that names
+the repository, and never moves the clone's own branches, remote-tracking refs
+or work tree. A commit that cannot be fetched refuses the spawn
+(`E_REMOTE_UNREADABLE`, naming the clone and the commit); it never falls back
+to the clone's branch. The fetch never prompts (ssh runs in BatchMode, askpass
+is refused). A server that serves only its advertised refs (protocol v0 without
+`allowAnySHA1InWant`) refuses a commit its branches have moved past; `--base`
+is then the way on. `--base <ref>` names another start point in the clone;
+a `--repo` that is not a clone of the soul's repository starts at its `HEAD`.
+The spawn result and `instance.json` record the start point as
+`base: {ref, oid}`.
+
 Use this for agents that will edit code or docs independently.
 
 Rules:

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.json

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