@awebai/oats 0.34.2 → 0.34.3

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}}
 ```
 
@@ -2028,7 +2028,11 @@ A first retire prints the **raw receipt**, not an envelope:
 - `--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/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,12 @@ 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>`.
 
+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

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

@@ -3395,11 +3395,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 +3572,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
@@ -4114,6 +4108,17 @@ function sessionDirectoryGuard(home) {
   return check;
 }
 
+/** 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) }) {
@@ -5938,7 +5943,6 @@ 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.
@@ -5963,9 +5967,8 @@ export function retireInstance(root, name, o = {}) {
   if (quarantine) {
     const failures = (hookResults?.failures || []).map((f) => `retire hook ${f.capability}: ${f.message}`);
     // 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"] }) }; }
@@ -5980,14 +5983,25 @@ export function retireInstance(root, name, o = {}) {
         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;
+      // 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`);
       }
     }
     for (const [capId, m] of Object.entries(hookResults?.meta || {})) {
@@ -6039,7 +6053,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?.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/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.3",
   "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 } }