@awebai/oats 0.34.2 → 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/capabilities.md

@@ -104,7 +104,8 @@ A self-contained package has an `oats.json`:
   permanent external residue. It is marked `.oats-rollback-incomplete.json`, so
   `oats status` reports it as retained state rather than a live instance, and
   `oats retire <instance>` retries the cleanup — re-running the retire hooks and
-  the rollback-owned Git steps, and verifying both. A retry that still cannot
+  the worktree removal, verifying both, and verifying (never deleting) the
+  branch: a branch is deleted only with `--delete-branch`. A retry that still cannot
   finish keeps the home again, names what is outstanding, and exits nonzero.
 - The **escape hatch is `oats retire <instance> --force`**, for a home OATS cannot
   identify at all: no `instance.json` and no **usable** cleanup descriptor. Usable

package/docs/desktop-cli-api.md

@@ -723,7 +723,7 @@ Read-only (it writes no lock):
              "souls":["rm"],"capabilities":["nw-house-style"],"publishes":null,"url":"https://github.com/nw/agents/tree/66566512…",
              "membershipFile":{"path":"oats-membership.yaml","url":"https://github.com/nw/agents/blob/66566512…/oats-membership.yaml"}}],
  "packages":[{"id":"oats.okf","version":"3.0.0","source":"catalog:oats.okf","commit":"ab897841…","integrity":"sha256-bada35…",
-              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.0.6","ref":"v4.0.6"}}],
+              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.0.7","ref":"v4.0.7"}}],
  "declaredPackages":["oats.framework","oats.okf"],"unsynced":["oats.framework"],"stale":[],
  "external":[{"source":"git:github.com/oss/experts@3c606e09…","soul":"security-reviewer"}],
  "problems":[],"warnings":[],
@@ -782,8 +782,8 @@ packages' capabilities and souls, sorted by name, then origin. Both carry
     "defaultTeam":{"label":"mine","team":"mine:ana.aweb.ai","from":"deployment"},
     "private":false,"path":"souls/writer","work":"directory","description":"Drafts campaigns.","harness":"pi","model":null,"harnessFrom":"kernel-default",
     "file":{"path":"souls/writer/soul.yaml","url":null},"spawnable":true,"problem":null},
-   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.0.6","kind":"package","package":"oats.okf",
-    "version":"4.0.6","repoKey":"github.com/awebai/oats-okf","commit":"2a62df8e…","teams":null,"defaultTeam":null,"private":false,
+   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.0.7","kind":"package","package":"oats.okf",
+    "version":"4.0.7","repoKey":"github.com/awebai/oats-okf","commit":"e460b29a…","teams":null,"defaultTeam":null,"private":false,
     "path":"oats-package/souls/knowledge-maintainer","work":"directory","description":"Reviews harvested knowledge.","harness":"pi","model":null,
     "harnessFrom":"kernel-default","file":{"path":"oats-package/souls/knowledge-maintainer/soul.yaml","url":null},
     "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/souls/teams/…)"}}],
@@ -872,8 +872,8 @@ nothing reads a working clone.
 **The show:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.0.6",
- "commit":"2a62df8e…","path":"oats-package/capabilities/oats-okf",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.0.7",
+ "commit":"e460b29a…","path":"oats-package/capabilities/oats-okf",
  "inject":{"path":"injects/okf.md","bytes":2422,"text":"## Knowledge: OKF\n\nYou have two kinds of knowledge. …","binary":false,"truncated":false},
  "skills":[{"name":"okf-consultation","path":"skills/okf-consultation","description":"Consulting your soul's knowledge with the `oats okf` CLI: …",
             "files":[{"path":"skills/okf-consultation/SKILL.md","bytes":6947},{"path":"skills/okf-consultation/references/consult.md","bytes":4465}],
@@ -899,7 +899,7 @@ nothing reads a working clone.
 **The `--file` answer:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"2a62df8e…",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e460b29a…",
  "file":{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787,"text":"---\nname: okf-instance-knowledge\n…","binary":false,"truncated":false}}
 ```
 
@@ -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,12 +2031,23 @@ 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
-  `branchDeletionSkipped`.
+  `branchDeletionSkipped`. Without `--delete-branch` no retire deletes a
+  branch, a retried or `--force`d quarantine included. A failed spawn's
+  quarantine that still owes the branch the spawn created stays incomplete
+  (`git branch <b>: kept; the failed spawn created it; pass --delete-branch to
+  delete it`).
 - `workRecovery` (or `workRecoveries[]`): `{path, classes, bytes, outputs?,
   repoCopy?}`; `outputs: {paths: [{path, bytes}], bytes}` names what was
   copied beyond tracked state, largest first.

package/docs/integrations.md

@@ -40,8 +40,8 @@ arrives from.
 ```yaml
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
-  oats.okf: v4.0.6
-  oats.aweb: v1.17.6
+  oats.okf: v4.0.7
+  oats.aweb: v1.17.7
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults:

package/docs/knowledge.md

@@ -26,7 +26,7 @@ The workspace pins the package and fills the slot for every soul by default:
 ```yaml
 # oats-workspace.yaml (excerpt)
 packages:
-  oats.okf: v4.0.6
+  oats.okf: v4.0.7
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:

package/docs/official-catalog.md

@@ -10,8 +10,8 @@ or workspace membership alone does not make a package official.
 | package | release | capabilities | package souls |
 |---|---|---|---|
 | `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
-| `oats.okf` | `v4.0.6` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.6` | `oats.aweb` (messaging) | |
+| `oats.okf` | `v4.0.7` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.aweb` | `v1.17.7` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -27,7 +27,7 @@ no lock and adds nothing to an existing workspace.
 ## Find and use packages
 
 - A workspace pins an official package by **bare version** in its
-  `packages:` map (`oats.okf: v4.0.6`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.0.7`); `oats sync` resolves it through the
   catalog to an exact commit, fetches it, verifies its integrity and locks it.
   A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
   not join a team or adopt the publisher's workspace. See

package/docs/packages.md

@@ -44,14 +44,14 @@ whole organisation:
 
 ```yaml
 packages:
-  oats.okf: v4.0.6                                    # bare version → the official catalog
+  oats.okf: v4.0.7                                    # bare version → the official catalog
   acme.tools: git:github.com/acme/tools@v0.4.0        # direct ref: git:<repo>@<tag or full OID>
 ```
 
-- **Bare version** (`v4.0.6`, `4.0.6`, `1.0.0-rc.1`): the id is looked up in
+- **Bare version** (`v4.0.7`, `4.0.7`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.0.6` or `oats-framework/v1.4.1`) and the payload path. An id
+  convention (`v4.0.7` or `oats-framework/v1.4.1`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -75,8 +75,8 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.4.1
-  oats.okf: v4.0.6
-  oats.aweb: v1.17.6
+  oats.okf: v4.0.7
+  oats.aweb: v1.17.7
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
 $ oats sync
 workspace  acme  (github.com/acme/agents @ 3f2a9c1e)
 members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   billing ✗ (no-backlink)
-packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.0.6 ✓ (@ 2a62df8e)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.0.7 ✓ (@ e460b29a)
 changed    acme.tools  — → 0.4.0 (@ 47f4b816)
 souls      9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
 teams      platform (shared) · this deployment's: oats teams
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.17.6                         # a catalog version
+oats package add oats.aweb v1.17.7                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
       "source": "catalog:oats.okf",
       "url": "https://github.com/awebai/oats-okf.git",
       "path": "oats-package",
-      "version": "4.0.6",
-      "commit": "2a62df8eb247b58b3d89b2ce38d84c49c2d8ae23",
+      "version": "4.0.7",
+      "commit": "e460b29aaf23db5728d7c64f7b5fb63f5014546b",
       "integrity": "sha256-…",
       "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
     },
@@ -331,7 +331,7 @@ A soul that names one of the package's capabilities with
 {
   "policy": "docs/official-catalog.md",
   "packages": {
-    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.6", "path": "oats-package" },
+    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.7", "path": "oats-package" },
     "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.1", "path": "oats-package" }
   }
 }

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

@@ -0,0 +1,48 @@
+# OATS 0.34.3
+
+## Changed
+
+- **oats.okf 4.0.7** (catalog and workspace pin, and the bundled mirrors):
+  `oats okf complete` records acceptance of an amended and merged harvest PR
+  (awebai/oats-okf#32). After the knowledge-maintainer's `amend+merge`, the
+  after-merge `complete --run <id>` failed with `E_BASELINE`, and the receipt
+  stayed `delivered`. Now:
+  - a merged PR is settled by its merge before any baseline check, and the
+    receipt records `mergeCommit`;
+  - when the PR was merged at a head the maintainer amended, an `okf-review`
+    verdict (`merge` or `amend+merge`) must name that head and the PR URL. It
+    must come from a repository member, or from the account that merged the
+    PR (which covers a maintainer on a GitHub App token);
+  - without such a verdict, `complete` fails with `E_PR` and says what to do.
+    Merged inputs are never rejudged.
+
+- **oats.aweb 1.17.7** (catalog and workspace pin, and the bundled mirror):
+  native retire retries are idempotent after a successful default-workspace
+  self-delete. The provider records a local completion marker, so if another
+  retire hook keeps the home and the kernel retries, oats.aweb does not call
+  `aw workspace delete` again with the already-revoked certificate.
+
+## Fixed
+
+- **Retire no longer deletes a branch you did not ask it to delete**
+  (awebai/oats#436, data safety). When a retire hook reported incomplete
+  cleanup, the home was quarantined, and the retry (or `oats retire --force`)
+  ran `git branch -D` on the instance's branch even without
+  `--delete-branch`, taking any unpushed commits with it. Now:
+  - only `--delete-branch` deletes a branch, the verified one;
+  - a quarantine and its retry never do;
+  - a failed spawn deletes its own new branch only while the branch's tip is
+    still where the spawn created it (`git update-ref -d` with that commit),
+    and otherwise keeps it and says so.
+
+- **A capture that is killed no longer blocks every later capture**
+  (awebai/oats#437). A capture pass killed mid-pass (a hook timeout, or
+  okf's 60 s bound) left the record root's capture lock behind, and every
+  later `oats capture` skipped. Retires that needed a final capture then
+  failed. Now:
+  - the next pass reclaims a lock whose recorded owner is dead on this host,
+    under a guard, and says so on stderr;
+  - a live or unknown owner, an initializing lock and another host's lock
+    are never touched;
+  - locks written by earlier kernels, which do not record the host, count as
+    this host's, so a stale lock already on disk clears on the next pass.

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

@@ -152,8 +152,8 @@ composed skills and instructions, a spawn records:
       "commit": "3f2a9c1e…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.118Z"
     },
     "oats.okf": {
-      "from": { "kind": "package", "package": "oats.okf", "version": "4.0.6", "commit": "2a62df8e…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
-      "commit": "2a62df8e…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
+      "from": { "kind": "package", "package": "oats.okf", "version": "4.0.7", "commit": "e460b29a…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
+      "commit": "e460b29a…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
     }
   },
   "providers": {
@@ -432,6 +432,22 @@ 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
+is still where the spawn created it. If something was committed there, the
+branch is kept and the failure says so.
+
 ## Work modes
 
 A work mode decides what `./work` points at and what discipline the agent must
@@ -466,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/docs/workspaces.md

@@ -55,7 +55,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.4.1                   # bare version → resolves through the official catalog
-  oats.okf: v4.0.6
+  oats.okf: v4.0.7
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # SHARED teams: the same provider team for everyone

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.
@@ -3395,11 +3406,7 @@ function* spawnBody(root, agent, o = {}) {
         const list = run(["git", "-C", repoAbs, "worktree", "list", "--porcelain", "-z"]);
         if (!list.ok) incomplete.push(`git worktree ${wt}: could not verify removal (${list.err || "worktree list failed"})`);
         else incomplete.push(`git worktree ${wt}: could not verify removal (canonical path unavailable after add)`);
-        const del = run(["git", "-C", repoAbs, "branch", "-D", branch]);
-        if (!del.ok) incomplete.push(`git branch ${branch}: deletion failed (${del.err || `exit ${del.status}`})`);
-        const ref = run(["git", "-C", repoAbs, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
-        if (ref.ok) incomplete.push(`git branch ${branch}: still exists`);
-        else if (ref.status !== 1 || ref.err) incomplete.push(`git branch ${branch}: could not verify deletion (${ref.err || `exit ${ref.status}`})`);
+        incomplete.push(...deleteBranchAsCreated(run, repoAbs, branch, plannedBase.oid));
       }
       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("; ")}` : "";
@@ -3576,10 +3583,8 @@ function* spawnBody(root, agent, o = {}) {
         if (worktreeCanonical && registered.includes(worktreeCanonical)) { incomplete.push(`git worktree ${worktreeCanonical}: still registered`); outstandingGit.add("worktree"); }
       }
       if (branch) {
-        probe(["git", "-C", repoAbs, "branch", "-D", branch]);
-        const brProbe = probe(["git", "-C", repoAbs, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
-        if (brProbe.ok) { incomplete.push(`git branch ${branch}: still exists`); outstandingGit.add("branch"); }
-        else if (brProbe.status !== 1 || brProbe.err) { incomplete.push(`git branch ${branch}: could not verify deletion (${brProbe.err || `rev-parse exit ${brProbe.status}`})`); outstandingGit.add("branch"); }
+        const branchDebt = deleteBranchAsCreated(probe, repoAbs, branch, plannedBase.oid);
+        if (branchDebt.length) { incomplete.push(...branchDebt); outstandingGit.add("branch"); }
       }
     }
     // Any attempted spawn hook may have created state before a later hook (or
@@ -3674,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 } : {}),
@@ -4114,9 +4119,50 @@ 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). */
+function deleteBranchAsCreated(run, repoAbs, branch, oid) {
+  const del = run(["git", "-C", repoAbs, "update-ref", "-d", `refs/heads/${branch}`, oid]);
+  const ref = run(["git", "-C", repoAbs, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+  if (ref.ok && ref.out.trim() !== oid) return [`git branch ${branch}: kept; its tip moved from ${oid.slice(0, 12)}, where this spawn created it`];
+  if (ref.ok) return [`git branch ${branch}: still exists${del.ok ? "" : ` (deletion failed: ${del.err || `exit ${del.status}`})`}`];
+  if (ref.status !== 1 || ref.err) return [`git branch ${branch}: could not verify deletion (${ref.err || `exit ${ref.status}`})`];
+  return [];
+}
 /** 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
@@ -4136,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,
@@ -4207,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;
@@ -4219,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.
@@ -4296,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 });
@@ -5167,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;
@@ -5208,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() } = {}) {
@@ -5413,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)));
     }
@@ -5719,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.
@@ -5768,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);
@@ -5816,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);
@@ -5885,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 };
@@ -5938,11 +6051,11 @@ export function retireInstance(root, name, o = {}) {
   // Otherwise the home — and the credentials in it — must survive again, or the
   // retry becomes the deletion the quarantine was preventing.
   let stillIncomplete;
-  let quarantineBranchDeleted = false;
   // Ordinary path: quarantine instead of deleting, using the SAME writer the
   // 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 || {})) {
@@ -5956,64 +6069,61 @@ 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. The branch is
-    // rollback-owned (spawn created it), so it is deleted here without needing
-    // the normal-retire --delete-branch flag, and any failure keeps the home.
+    // 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).
     if (meta.work === "worktree" && meta.repo) {
       const gitProbe = (argv) => {
         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`);
-      }
-      if (meta.branch) {
-        gitProbe(["git", "-C", meta.repo, "branch", "-D", meta.branch]);
-        const br = gitProbe(["git", "-C", meta.repo, "rev-parse", "--verify", "--quiet", `refs/heads/${meta.branch}`]);
-        if (br.ok) failures.push(`git branch ${meta.branch}: still exists`);
-        else if (br.status !== 1 || br.err) failures.push(`git branch ${meta.branch}: could not verify deletion (${br.err || `rev-parse exit ${br.status}`})`);
-        // Verified gone: the result must say so, or --json misreports the very
-        // cleanup this path just performed.
-        else quarantineBranchDeleted = true;
+      // 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`);
+        }
       }
-    }
-    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 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.
+      // --delete-branch: the branch the documented path deleted (the verified one) must be gone. A failed
+      // spawn's quarantine that owes its recorded branch keeps it unless that branch was the one deleted.
+      const verify = (branch) => {
+        const br = gitProbe(["git", "-C", meta.repo, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+        if (br.ok) return "exists";
+        if (br.status !== 1 || br.err) { failures.push(`git branch ${branch}: could not verify whether it still exists (${br.err || `rev-parse exit ${br.status}`})`); return "unknown"; }
+        return "gone";
+      };
+      const deleted = retention?.branchDeleted;
+      if (deleted && verify(deleted) === "exists") failures.push(`git branch ${deleted}: still exists`);
+      const owesBranch = (quarantine.cleanup.outstanding?.git || []).includes("branch");
+      if (owesBranch && meta.branch && meta.branch !== deleted && verify(meta.branch) === "exists") {
+        // Without a home left to retry from (--force), or when --delete-branch verified another branch, the
+        // recorded branch is the operator's to delete by hand.
+        failures.push(o.force || o.deleteBranch
+          ? `git branch ${meta.branch}: kept; the failed spawn created it; delete it with git branch -D ${meta.branch} if unwanted`
+          : `git branch ${meta.branch}: kept; the failed spawn created it; pass --delete-branch to delete it`);
       }
     }
-    // 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 {
@@ -6039,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) || quarantineBranchDeleted, 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,12 +3,12 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v4.0.6",
+      "ref": "v4.0.7",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.17.6",
+      "ref": "v1.17.7",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.34.2",
+  "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",

package/packages/record/README.md

@@ -197,6 +197,27 @@ Journal writes fsync; note that on macOS `fsync(2)` does not guarantee media
 durability (that would need `F_FULLFSYNC`, which Node's fs API does not
 expose) — the guarantee is OS-crash-level, not power-loss-level.
 
+**One capture pass at a time.** A pass takes the record root's
+`.capture.lock` directory, whose `owner.json` records the pid, a nonce, the
+start time and the host. A pass that finds the lock held skips (the next
+pass catches up). A pass that is killed (a hook or caller timeout) runs no
+cleanup, so the next pass reclaims a lock whose recorded owner is dead on
+this host:
+
+- Reclaimers are serialized by a guard, `.capture.lock.reclaim`, taken by
+  exclusive create. Under it the record is read again and removed only if it
+  still belongs to that dead owner.
+- A live or unknowable owner, an owner-less (initializing) lock and another
+  host's lock are never touched.
+- A guard left by a reclaimer that died is never removed. It is named, with
+  the exact recovery.
+- Records that name no host predate host recording and live under this
+  user's home, so they count as this host's: a dead owner's lock is
+  reclaimed too. On a home shared across machines (NFS, or a synced
+  directory), such a record may belong to another host, whose pid means
+  nothing here; check that no capture runs on the other machines before the
+  first pass after upgrading.
+
 ## Upgrading
 
 The derived index self-heals across schema changes by wiping and

package/packages/record/bin/capture.mjs

@@ -183,6 +183,9 @@ function withCaptureLock(fn) {
   let lock;
   try {
     lock = acquireCaptureLock(root);
+    // Said by the pass that removed it, never quiet, whether or not it then took the lock: a pass that
+    // died holding the lock is worth knowing about.
+    if (lock.reclaimed) console.error(`capture: reclaimed ${lock.path} from pid ${lock.reclaimed.pid}, which died (started ${lock.reclaimed.startedAt || "?"})`);
   } catch (err) {
     if (err.lockCleanup) {
       const c = err.lockCleanup;

package/packages/record/lib/capture-lock.mjs

@@ -4,18 +4,33 @@
 // and the next pass catches up, since reconciliation is idempotent.
 //
 // The lock is a DIRECTORY: mkdir is atomic and a directory is never
-// observable half-created. The owner record (pid, start time) is written
-// inside it after the mkdir. Nothing here ever steals a lock: any existing
-// lock, live, dead, unknowable or still initializing, refuses the pass and
-// names the holder and the operator recovery. A stale lock after a killed
-// pass is removed by the operator once the pid is verified gone; the
-// message says exactly that. (A reclaim protocol was reviewed and rejected:
-// rename is not compare-and-swap, and stealing from a stalled live
-// initializer under memory pressure is the failure we are preventing.)
-import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+// observable half-created. The owner record (pid, nonce, start time, host)
+// is written inside it after the mkdir. A live, unknowable or still
+// initializing (owner-less) lock refuses the pass and names the holder and
+// the operator recovery; it is never stolen.
+//
+// A lock whose recorded owner is DEAD on this host is reclaimed (a capture
+// killed mid-pass by a hook or caller timeout runs no finally). Records
+// without host predate host recording and live under this user's home, so
+// they count as this host's (RECLAIM_HOSTLESS_RECORDS). Reclaimers
+// are serialized by a guard, `<lock>.reclaim` (exclusive create): under it
+// the owner record is read again and the lock removed only while it is still
+// that dead owner's, so a reclaimer cannot remove a lock a live pass took
+// meanwhile. A guard whose holder died is never removed (that would race
+// exactly as removing the lock does); it is named with its recovery.
+// Acquire never waits: it reclaims once or skips, and the next pass catches up.
+// There is no signal handler: a pass is synchronous, so a JS handler would
+// only run after the whole pass (turning a caller's timeout kill into a full
+// pass), and SIGKILL cannot be handled; the reclaim is the recovery.
+import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
+import { hostname } from "node:os";
 import { join } from "node:path";
 
+/** Whether an owner record that names no host is reclaimed when its pid is dead here: yes. Records without
+ *  host predate host recording and live under this user's home, so they are this host's. */
+export const RECLAIM_HOSTLESS_RECORDS = true;
+
 export function captureLockPath(root) { return join(root, ".capture.lock"); }
 
 /** "alive" | "dead" | "unknown" for an owner pid ("unknown" = exists but not signalable). */
@@ -24,8 +39,38 @@ export function holderLiveness(pid) {
   try { process.kill(pid, 0); return "alive"; } catch (e) { return e.code === "EPERM" ? "unknown" : "dead"; }
 }
 
-function readOwner(dir) {
-  try { return JSON.parse(readFileSync(join(dir, "owner.json"), "utf8")); } catch { return undefined; }
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } };
+const readOwner = (dir) => readJson(join(dir, "owner.json"));
+
+/** Whether `owner` is a record of this host whose process is dead: the only lock this module reclaims. */
+function deadHere(owner, { host, liveness, reclaimHostless }) {
+  if (!owner || !Number.isInteger(owner.pid)) return false;
+  const here = owner.host === undefined ? reclaimHostless : owner.host === host;
+  return here && liveness(owner.pid) === "dead";
+}
+
+/** Remove the lock `dir` held by the dead `owner`, serialized by the guard `<dir>.reclaim`. → { removed }
+ *  (true only when THIS call removed it; otherwise it is left for the next pass), or { abandoned: { guard,
+ *  pid } } when a reclaimer died holding the guard. */
+function reclaimDeadLock(dir, owner, me, opts) {
+  const guard = `${dir}.reclaim`;
+  try { writeFileSync(guard, JSON.stringify(me), { flag: "wx", mode: 0o600 }); }
+  catch (e) {
+    if (e.code !== "EEXIST") return { removed: false };
+    const g = readJson(guard);
+    return g && deadHere(g, opts) ? { abandoned: { guard, pid: g.pid } } : { removed: false };
+  }
+  const same = (o) => o && o.pid === owner.pid && o.nonce === owner.nonce && o.startedAt === owner.startedAt;
+  let removed = false;
+  try {
+    const now = readOwner(dir);
+    if (same(now) && deadHere(now, opts)) {
+      rmSync(dir, { recursive: true, force: true });
+      removed = !existsSync(dir) || !same(readOwner(dir));
+    }
+  } catch { /* the next pass */ }
+  finally { if (readJson(guard)?.nonce === me.nonce) { try { unlinkSync(guard); } catch { /* gone */ } } }
+  return { removed };
 }
 
 /** Single-quote shell escaping: safe to paste whatever the path contains. */
@@ -40,9 +85,13 @@ export function recoveryInstruction(dir, owner, liveness) {
   return `${dir} is held by ${who}; if that process is gone (ps -p ${owner.pid}), remove the lock with: ${remove}  and rerun`;
 }
 
-/** Try to take the root's capture lock. Returns { path, release } when
- *  taken, or { path, held: { pid, startedAt, liveness, recovery } } when any
- *  lock exists. Never removes a lock it did not create.
+/** Try to take the root's capture lock. Returns { path, release, reclaimed? }
+ *  when taken, or { path, held: { pid, startedAt, liveness, recovery, guard? },
+ *  reclaimed? } when a lock is held. A lock it did not create is removed only
+ *  when its recorded owner is dead on this host, under the reclaim guard (the
+ *  header); `reclaimed: { pid, startedAt }` says THIS call removed it (whether
+ *  or not it then won the lock), and `held.guard` names a guard a dead
+ *  reclaimer left. Every other lock is left alone.
  *
  *  Two failure points are reported rather than left behind. If the owner
  *  record cannot be written after THIS call created the directory (a full
@@ -59,22 +108,39 @@ export function recoveryInstruction(dir, owner, liveness) {
  *  The owner record carries a per-acquisition nonce, so a release kept from
  *  an earlier acquisition cannot erase a later one by the same pid (an
  *  operator recovery followed by a new pass in the same long-lived process).
- *  That is ownership checking; no lock is ever reclaimed.
  *
  *  `io` exists for fault injection in tests only. */
-export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness, io = {} } = {}) {
+export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness, host = hostname(), reclaimHostless = RECLAIM_HOSTLESS_RECORDS, io = {} } = {}) {
   const fs = { writeFileSync, rmSync, openSync, closeSync, lstatSync, ...io };
   const dir = captureLockPath(root);
+  const nonce = randomBytes(8).toString("hex");
   mkdirSync(root, { recursive: true }); // the store creates the root lazily; the lock may come first
-  try {
-    mkdirSync(dir);
-  } catch (e) {
-    if (e.code !== "EEXIST") throw e;
-    const owner = readOwner(dir);
-    const live = owner ? (owner.pid === pid ? "alive" : liveness(owner.pid)) : "unknown";
-    return { path: dir, held: { pid: owner?.pid, startedAt: owner?.startedAt, liveness: live, recovery: recoveryInstruction(dir, owner, live) } };
+  let reclaimed;
+  for (let attempt = 0; ; attempt++) {
+    try { mkdirSync(dir); break; }
+    catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      const owner = readOwner(dir);
+      const opts = { host, liveness, reclaimHostless };
+      if (attempt === 0 && owner?.pid !== pid && deadHere(owner, opts)) {
+        const r = reclaimDeadLock(dir, owner, { pid, nonce, host }, opts);
+        if (r.abandoned) {
+          const { guard, pid: reclaimer } = r.abandoned;
+          return { path: dir, held: { pid: owner.pid, startedAt: owner.startedAt, liveness: "dead", guard,
+            recovery: `${guard} was left by pid ${reclaimer}, which died while reclaiming ${dir}; once no capture process is running (pgrep -f capture.mjs), remove both with: rm -- ${shellQuote(guard)}; rm -r -- ${shellQuote(dir)}  and rerun` } };
+        }
+        // Gone, whoever removed it (another reclaimer may have): try the lock once more.
+        if (r.removed) reclaimed = { pid: owner.pid, startedAt: owner.startedAt };
+        if (r.removed || !existsSync(dir)) continue;
+      }
+      const now = readOwner(dir);
+      // Gone between the mkdir and this read (a release or a reclaim): try once more. A directory that
+      // exists without a record is initializing or mid-removal, and is reported so.
+      if (!now && attempt === 0 && !existsSync(dir)) continue;
+      const live = now ? (now.pid === pid ? "alive" : liveness(now.pid)) : "unknown";
+      return { path: dir, ...(reclaimed ? { reclaimed } : {}), held: { pid: now?.pid, startedAt: now?.startedAt, liveness: live, recovery: recoveryInstruction(dir, now, live) } };
+    }
   }
-  const nonce = randomBytes(8).toString("hex");
   let directoryFd, identity;
   try {
     // Keep the directory alive until initialization or its cleanup finishes.
@@ -82,7 +148,7 @@ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, li
     // a record-less replacement look like the directory we created.
     directoryFd = fs.openSync(dir, "r");
     identity = fstatSync(directoryFd);
-    fs.writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, nonce, startedAt: new Date(now()).toISOString() }));
+    fs.writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, nonce, startedAt: new Date(now()).toISOString(), host }));
   } catch (err) {
     // Ownership was proven by the mkdir, not by the moment of cleanup: the
     // directory is removed only if it is still ours (same inode) and holds
@@ -109,6 +175,7 @@ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, li
   }
   return {
     path: dir,
+    ...(reclaimed ? { reclaimed } : {}),
     release: () => {
       if (!existsSync(dir)) return { released: false, reason: "gone" };
       const cur = readOwner(dir);

package/skills/oats-getting-started/SKILL.md

@@ -61,7 +61,7 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.4.1                # bare versions resolve through the official catalog
-  oats.okf: v4.0.6
+  oats.okf: v4.0.7
 defaults:
   capabilities: { oats.core: { from: package } }
   knowledge: { oats.okf: { from: package } }