@awebai/oats 0.34.1 → 0.34.3

package/bin/oats.mjs

@@ -30,7 +30,7 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
@@ -583,7 +583,8 @@ function legacyLayoutProblems(root) {
 }
 async function doctorWorkspaceJson(ctx, soulName, ws) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
-  const problems = legacyLayoutProblems(join(dirname(ws.local.path), "agents"));
+  const agentsRoot = join(dirname(ws.local.path), "agents");
+  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean);
   return {
     schemaVersion: 1, workspaceApi: 2, context: ctx,
     workspace: { file: ws.local.path, ref: ws.local.workspace },
@@ -622,7 +623,8 @@ async function doctor(dir) {
   doctorVersionSkew();
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
   printDoctorWorkspace(ws);
-  for (const p of legacyLayoutProblems(join(dirname(ws.local.path), "agents"))) console.log(`\n! ${p.code}: ${p.message}`);
+  const agentsRoot = join(dirname(ws.local.path), "agents");
+  for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
     if (information) console.log(`\nINFO: ${information}`);
@@ -769,11 +771,11 @@ function launchPreview(bail) {
     instance = meta.instance || basename(home);
     if (!(meta.launch && typeof meta.launch === "object") && !selectionGiven) {
       // A home that predates recipes, asked nothing: its frozen command is
-      // described as is. Under a selection the planner refuses it
-      // (E_LAUNCH_LEGACY: re-spawn it from the deployment).
-      let d;
-      try { d = describeLaunchCommand(meta.command); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
-      jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(meta.command), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
+      // described as a start runs it (with its harness's safe task prompt). Under a
+      // selection the planner refuses it (E_LAUNCH_LEGACY: re-spawn it from the deployment).
+      let d, frozen;
+      try { frozen = withSafeTaskPrompt(meta.command, meta.harness); d = describeLaunchCommand(frozen); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
+      jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
       return;
     }
     const agentsRoot = agentsRootOfHome(home);
@@ -2838,14 +2840,20 @@ async function capabilityCommand() {
     if (!hit) return NOT_DISPATCHED;
     // The same team/workspace facts a spawn hook receives (lead decision c3-7).
     const teamCtx = teamEnv(resolvedFromPrepared(hit.prepared, hit.deployment));
-    // No home, so no recorded soul: the soul's per-commit copy is OATS_SOUL when a spawn
-    // already fetched exactly this commit; otherwise the command gets none (never ambient).
-    // The agent directory is the soul entry's own (a package soul's is `<package>--<soul>`), never
-    // the bare name, which a same-named member soul's copy may occupy (as instance-inspect does).
-    const { agentDirOf } = await import("../lib/instance-resolution.mjs");
-    const entry = hit.prepared?.soulEntry;
-    const cachedSoul = entry?.commit ? join(hit.deployment, "agents", agentDirOf(entry), "souls", String(entry.commit).slice(0, 12)) : null;
-    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, { settings: hit.settings, origins: hit.resolution?.payloadOrigins?.[hit.module.name] }, teamCtx, hit.ensureTree, cachedSoul && existsSync(join(cachedSoul, "soul.yaml")) ? realpathSync(cachedSoul) : undefined);
+    // No home, so no recorded soul: OATS_SOUL is the soul's source at the resolved commit, read
+    // as a spawn preview reads it (the per-commit copy a spawn left under the agents root, else a
+    // temporary fetch removed when the command ends). Read only when the command runs (after its
+    // --help). A soul that cannot be read refuses the command: it never runs with OATS_SOUL unset.
+    const soul = async () => {
+      const { previewWorkspaceSoul } = await import("../lib/instance-resolution.mjs");
+      const entry = hit.prepared?.soulEntry;
+      try { const p = await previewWorkspaceSoul(hit.prepared, join(hit.deployment, "agents")); return { dir: p.soulDir, cleanup: p.cleanup }; }
+      catch (e) {
+        throw Object.assign(new Error(`oats ${cmd}: cannot read soul ${flag("soul")} at ${String(entry?.commit ?? "?").slice(0, 12)}, so the command would run without OATS_SOUL; nothing was run: ${e.message}`),
+          { code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_REMOTE_UNREADABLE", details: { soul: flag("soul"), repoKey: entry?.repoKey ?? null, commit: entry?.commit ?? null } });
+      }
+    };
+    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, { settings: hit.settings, origins: hit.resolution?.payloadOrigins?.[hit.module.name] }, teamCtx, hit.ensureTree, soul);
   }
 
   async function dispatch() {
@@ -2917,14 +2925,14 @@ async function capabilityCommand() {
       const live = await liveTeams(instanceHome, homeMeta.meta, { remoteOptions: remoteOptionsFromEnv() });
       teamCtx = homeTeamCtx(live);
     }
-    return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, soulDir);
+    return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, () => ({ dir: soulDir, cleanup: () => {} }));
   }
 
   /** Help / unknown-command / spec validation / exec — shared by every context.
    *  `m` is the manifest (with `capability`; `_dir` may be absent until `ensureDir`
    *  resolves the directory holding the executable — the operator branch fetches
    *  the module tree only when a command is actually going to run). */
-  async function runManifestCommand(m, { settings, origins }, teamCtx, ensureDir, soulDir) {
+  async function runManifestCommand(m, { settings, origins }, teamCtx, ensureDir, soul) {
     const sub = args[1];
     const cmds = Object.keys(m.commands);
     // `oats <ns> --help` and `oats <ns> <cmd> --help` answer from the manifest
@@ -2958,6 +2966,11 @@ async function capabilityCommand() {
     try { abs = capabilityExecutablePath(withDir, script); }
     catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
     if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
+    // The soul the command acts for → { dir, cleanup }: a home's recorded soul directory, or (operator
+    // dispatch) the soul read at its resolved commit, whose temporary copy goes when this process exits.
+    let soulDir;
+    try { const read = await soul(); soulDir = read.dir; process.once("exit", read.cleanup); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
     // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
     // invoking process names some other soul (a coordinator's own), never this one.
     const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;

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
@@ -533,7 +534,12 @@ passed as arguments; no shell is involved.
   - `OATS_SOUL`, the soul directory: a home's recorded one, or for a soul
     (`readiness --soul`, `inspect --soul`) its copy at the resolved commit,
     which the kernel materialises first as a spawn would (0.30; a copy that
-    cannot be made fails readiness under `installed`, producer `soul copy`);
+    cannot be made fails readiness under `installed`, producer `soul copy`).
+    An operator command (`oats <namespace> … --soul <name>` from the
+    deployment) gets the soul's source at the resolved commit too: the copy a
+    spawn left under the agents root, else a temporary copy removed when the
+    command ends. A soul that cannot be read refuses the command; it never
+    runs without `OATS_SOUL`;
   - for a home, `OATS_INSTANCE` and `OATS_INSTANCE_HOME`.
 - `OATS_TEAM_SCOPE` is the deployment directory; `OATS_TEAM_NAME` is always
   empty.

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.5","ref":"v4.0.5"}}],
+              "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.5","kind":"package","package":"oats.okf",
-    "version":"4.0.5","repoKey":"github.com/awebai/oats-okf","commit":"26d8216f…","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.5",
- "commit":"26d8216f…","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":"26d8216f…",
+{"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/execution-targets.md

@@ -13,8 +13,8 @@ home. To run them on another machine, see [servers.md](servers.md).
 | Harness | `--harness` | Launched as |
 |---|---|---|
 | pi | `pi` (the default) | `pi --append-system-prompt <home>/AGENTS.md --approve --name <instance> [--model m] @TASK.md` |
-| Claude Code | `claude` | `claude [--model m] -- "$(cat TASK.md)"` |
-| Codex | `codex` | `codex --cd <home> [--model m] -- "$(cat TASK.md)"` |
+| Claude Code | `claude` | `claude [--model m] -- '@TASK.md'` |
+| Codex | `codex` | `codex --cd <home> [--model m] -- 'Read TASK.md in this directory first: it is your briefing and your task.'` |
 
 Each harness starts in the instance home with its own native settings,
 authentication and skill discovery. The command line also carries the
@@ -166,6 +166,18 @@ and `restart`, opens a new harness conversation on `TASK.md`. The instance
 resumes its work from its own state files, as its knowledge capability
 prescribes.
 
+The task's text never travels on a command line, where any local user could
+read it in the process list:
+
+- pi and Claude Code get `@TASK.md`, which each harness reads as the file.
+- Codex gets a fixed pointer to the file and reads it with a tool.
+- A home whose recorded command still hands over `"$(cat TASK.md)"` starts
+  with its harness's safe prompt instead, and the command is saved that way.
+
+The home is created `0700` and `TASK.md` `0600`. `oats doctor` reports an
+instance home that other users can read (`home-readable`), with the exact
+`chmod`; it never changes a home's mode itself.
+
 ## Permissions (yolo)
 
 Yolo is chosen per launch: `--yolo` / `--no-yolo` on `oats spawn`,

package/docs/implementation.md

@@ -225,7 +225,7 @@ scaling by call count.
 | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs` |
 | `npm run check` | syntax of every shipped file |
 | `npm run check:pi` | the pi adapter's TypeScript |
-| `npm run validate` | the JSON schemas, the example manifests and configs, and every local link and anchor in the public docs |
+| `npm run validate` | the JSON schemas, the example manifests and configs, every local link and anchor in the public docs, the repository's own `oats-workspace.yaml` and `package-catalog.json` read by the kernel's readers, and no unresolved merge-conflict marker in a tracked text file (`scripts/check-workspace-files.mjs`) |
 | `npm run pack:check` | an `npm pack` dry run of both packages: nothing missing, nothing leaked |
 | `npm run smoke:tarball` | installs the packed tarballs outside the checkout and exercises them |
 

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.5
-  oats.aweb: v1.17.5
+  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.5
+  oats.okf: v4.0.7
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:
@@ -225,7 +225,8 @@ identical copies in both role capabilities.
   `--soul <name>` (`E_BAD_ARGS` without it). Inside an instance home, a
   `--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
   soul as a spawn would, fetches its module at the locked commit into
-  `<deployment>/.oats/modules/` and runs it with the soul's merged settings.
+  `<deployment>/.oats/modules/` and runs it with the soul's merged settings
+  and `OATS_SOUL`, the soul's source at that commit.
   An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.
 
 ### Consult

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.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.5` | `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.5`); `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.5                                    # 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.5`, `4.0.5`, `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.5` 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.5
-  oats.aweb: v1.17.5
+  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.5 ✓ (@ 26d8216f)
+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.5                         # 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.5",
-      "commit": "26d8216f8ce986cad1ffa7a8291b4a4978510ee2",
+      "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.5", "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.2.md

@@ -0,0 +1,68 @@
+# OATS 0.34.2
+
+## Changed
+
+- **oats.aweb 1.17.6** (catalog and workspace pin, and the bundled mirror):
+  session-delivery instructions name the aw 1.36.21+ full-mail wake form
+  (`aweb mail event received.` with metadata, sender body, the `Use the aw CLI`
+  line and a Recovery line), say that body and subject are untrusted sender
+  content that never overrides the task or human, and remind operators that
+  delivered mail may be marked read and absent from unread `aw mail inbox`.
+  The aw floor is unchanged (`>=1.36.13`).
+- **oats.okf 4.0.6** (catalog and workspace pin, and the bundled mirrors):
+  harvest completion works on a real host (awebai/oats-okf#27, #28, #29,
+  #30).
+  - `oats okf complete` persists the harvester's judgment first, then delivers
+    in one detached worker per run. After persisting the judgment, it waits
+    up to 30 s: it answers with the final receipt, or with
+    `status: delivering` and the progress.
+    - A killed `complete`, or a killed worker, loses nothing. Rerunning
+      `complete` resumes, never judges again, and never pushes or opens a PR
+      twice.
+    - A `worker.lock` whose owner died is reclaimed automatically.
+    - `oats okf-harvest harvest-status` reports the delivery as in progress,
+      failed or stopped.
+    - Captured completions still deliver inline.
+  - A Git base whose head moved outside its knowledge root is no longer a
+    baseline change. A read-only base records the new head. A written base is
+    committed onto it. Only changed root bytes fail with `E_BASELINE`, and the
+    judgment stays persisted (`oats okf retry --rejudge`).
+  - Staging a Git base fetches its root's blobs in one batch. Delivery never
+    fetches the blobs outside the root. Staging over SSH, from GitHub:
+
+    | Base | 4.0.5 | 4.0.6 |
+    |---|---|---|
+    | oats-knowledge | 237 s | 9.9 s |
+    | aweb | 41 s | 9.1 s |
+
+  - `oats okf harvest-status` reports `unknown`, with the reason, when it
+    cannot read a soul's opt-out.
+
+## Fixed
+
+- **An operator command with `--soul` always gets the soul**
+  (awebai/oats#423). `oats <namespace> … --soul <name>` from the deployment
+  passed `OATS_SOUL` only when a spawn had already fetched that soul at the
+  resolved commit, so `oats okf harvest-status --soul <s>` reported harvest
+  "off" for a soul no spawn had fetched yet. The soul is now read at the
+  resolved commit as a spawn preview reads it: the copy a spawn left, else a
+  temporary copy removed when the command ends. A soul that cannot be read
+  refuses the command; it never runs without `OATS_SOUL`.
+
+- **A task's text no longer appears in the process list** (awebai/oats#427).
+  Claude Code and Codex instances were launched with the whole `TASK.md` as a
+  command-line argument, which any local user can read. Now:
+  - Claude Code gets `@TASK.md` (it reads the file).
+  - Codex gets a fixed instruction to read `TASK.md`.
+  - A home recorded the old way starts with the safe prompt, and its saved
+    command is updated.
+  - New instance homes are created `0700` and `TASK.md` `0600`.
+  - `oats doctor` reports a home other users can read (`home-readable`) with
+    the exact `chmod`. Existing homes are not changed: run that `chmod`.
+
+- **`npm run validate` catches a broken workspace file** (a development
+  check). It reads the repository's own `oats-workspace.yaml` and
+  `package-catalog.json` with the kernel's readers, and fails on an unresolved
+  merge-conflict marker in any tracked text file, naming the file and the
+  line. A conflicted `oats-workspace.yaml` had passed check, validate, pack
+  and smoke. The kernel's YAML and catalog errors now name the line too.

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

@@ -129,7 +129,7 @@ full copy** of every capability the soul resolved to:
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
   .oats/bin/oats → <kernel>/bin/oats.mjs  # the kernel that last launched this home: first on the harness's PATH
   work/                            # worktree, checkout symlink, attached tree, or private directory
-  TASK.md                          # briefing and task
+  TASK.md                          # briefing and task (0600; the home itself is 0700)
   instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
   STATE.md, log.md, notes/         # optional, from the knowledge capability
 ```
@@ -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.5", "commit": "26d8216f…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
-      "commit": "26d8216f…", "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.5
+  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/canonical-json.mjs

@@ -103,6 +103,8 @@ export function canonicalJson(value, options) {
   return chunks.join("");
 }
 
+/** The 1-based line of character `offset` in `text`: where a reader's error points. */
+export function lineAt(text, offset) { return text.slice(0, offset).split("\n").length; }
 /** JSON.parse alone cannot detect duplicate decoded keys. This small JSON
  * decoder preserves that check and budgets; YAML must use it for JSON input,
  * not maintain another permissive JSON reader. Objects have null prototypes. */
@@ -114,7 +116,7 @@ export function parseStrictJson(input, options) {
   }
   const text = decodeUtf8(data);
   let at = 0, entries = 0;
-  const bad = () => { throw oatsError("invalid-declaration", `invalid JSON at character ${at}`); };
+  const bad = () => { throw oatsError("invalid-declaration", `invalid JSON at character ${at}`, { offset: at }); };
   const space = () => { while (at < text.length && /[\x20\t\r\n]/.test(text[at])) at++; };
   const string = () => {
     const start = at++;

package/lib/config-data.mjs

@@ -3,7 +3,7 @@
  * Legacy core readers are unchanged until the explicit consumer migration. */
 import { Composer, CST, Lexer, Parser, isAlias, isMap, isScalar, isSeq } from "yaml";
 import { bytesIntegrity } from "./digest.mjs";
-import { byteView, canonicalJson, dataLimits, decodeUtf8, parseStrictJson } from "./canonical-json.mjs";
+import { byteView, canonicalJson, dataLimits, decodeUtf8, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { oatsError } from "./errors.mjs";
 
 const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
@@ -71,7 +71,9 @@ export function parseConfigData(input, { format = "auto", origin = null, limits:
     }
     if (document.errors.length || document.warnings.length || document.directives.yaml.version !== "1.2") {
       const issue = document.errors[0] ?? document.warnings[0];
-      throw oatsError("invalid-declaration", `invalid portable YAML${issue ? ` (${issue.code})` : " version"}`);
+      const offset = issue?.pos?.[0];
+      const line = Number.isInteger(offset) ? lineAt(source, offset) : undefined;
+      throw oatsError("invalid-declaration", `invalid portable YAML${issue ? ` (${issue.code}${line ? ` at line ${line}` : ""})` : " version"}`);
     }
     const decode = (node, pointer, depth) => {
       mark(pointer, depth, node);

package/lib/core.mjs

@@ -63,7 +63,7 @@ import { validateBindingInterface } from "./provider-binding.mjs";
 /** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home). */
 export { fingerprintTree };
 
-import { canonicalJson, parseStrictJson } from "./canonical-json.mjs";
+import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { readPortableBytes } from "./bounded-read.mjs";
 import { copyTreeSafe } from "./tree-copy.mjs";
 /** The package and capability id grammar (namespaced, lowercase): an id names a
@@ -89,6 +89,10 @@ function capabilityAgentDirs(root) {
   return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".") && !RESERVED.has(e.name) && !existsSync(join(root, e.name, "soul", "soul.yaml")))
     .map((e) => ({ name: e.name, dir: join(root, e.name) }));
 }
+/** The names of the non-hidden directories in `d` ([] when it cannot be read). */
+function subdirs(d) {
+  try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; }
+}
 /** What OATS 0.25 left under <scope>/local-agents/ (and the nested <root>/local-agents|
  *  tmp-agents) for the agents root `root`: one `legacy-local-agents` problem naming the
  *  instance homes there, or null. Names only — nothing there is read, spawned into or
@@ -97,7 +101,6 @@ export function legacyLocalAgents(root) {
   if (!root) return null;
   const bases = [join(dirname(root), LEGACY_LOCAL_AGENTS_DIR), join(root, LEGACY_LOCAL_AGENTS_DIR), join(root, "tmp-agents")];
   const dirs = [], instances = [];
-  const subdirs = (d) => { try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; } };
   for (const base of bases) {
     let st; try { st = lstatSync(base); } catch { continue; }
     if (!st.isDirectory()) continue;
@@ -109,12 +112,32 @@ export function legacyLocalAgents(root) {
   return { code: "legacy-local-agents", dirs, instances,
     message: `${instances.length} instance home${instances.length === 1 ? "" : "s"} under local-agents/ ${instances.length === 1 ? "is" : "are"} from OATS 0.25 and ${instances.length === 1 ? "is" : "are"} not managed by this kernel; retire ${instances.length === 1 ? "it" : "them"} with the 0.25 kernel or delete the directory once ${instances.length === 1 ? "it is" : "they are"} stopped${instances.length ? ` (${instances.join(", ")})` : ""}` };
 }
+/** The instance homes under the agents root `root` (a directory <root>/<agent>/instances/<name>
+ *  whose instance.json records that name) that other users on the machine can read or enter (any
+ *  group or other permission bit): one `home-readable` problem naming them, with the exact chmod,
+ *  or null. A home holds identity keys, TASK.md and transcripts; spawn creates it 0700. Only
+ *  reported: the operator decides. */
+export function readableInstanceHomes(root) {
+  if (!root) return null;
+  const homes = [];
+  for (const agent of subdirs(root)) for (const name of subdirs(join(root, agent, "instances"))) {
+    const home = join(root, agent, "instances", name);
+    try {
+      if (JSON.parse(readFileSync(join(home, "instance.json"), "utf8"))?.instance !== name) continue;
+      if (lstatSync(home).mode & 0o077) homes.push(home);
+    } catch { /* no readable instance.json, or gone meanwhile: not a home */ }
+  }
+  if (!homes.length) return null;
+  homes.sort();
+  const fix = `chmod 700 ${homes.map(shq).join(" ")}`;
+  return { code: "home-readable", homes, fix,
+    message: `${homes.length} instance home${homes.length === 1 ? " can" : "s can"} be read by other users on this machine (${homes.length === 1 ? "it holds" : "they hold"} identity keys, TASK.md and transcripts); fix: ${fix}` };
+}
 /** The captured homes (the 0.24–0.25 captured/portable path, removed in 0.26) under the
  *  agents root `root`: one `legacy-captured-home` problem naming them, or null. They have
  *  no 0.26 runtime (start, inspect and in-home commands refuse them); retire still works. */
 export function legacyCapturedHomes(root) {
   if (!root) return null;
-  const subdirs = (d) => { try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; } };
   const homes = [];
   for (const agent of subdirs(root)) for (const inst of subdirs(join(root, agent, "instances"))) {
     const home = join(root, agent, "instances", inst);
@@ -883,11 +906,21 @@ function readCatalogFile() {
   // catalog belongs to the kernel install.
   const override = !!process.env.OATS_PACKAGE_CATALOG;
   if (!existsSync(file)) { if (override) recordLocalInput(file, null); return empty; }
-  let doc;
   const text = readFileSync(file, "utf8");
   if (override) recordLocalInput(file, text);
+  return parsePackageCatalog(text, file);
+}
+/** A package catalog's text, parsed and checked as the kernel reads it (named `file` in errors):
+ *  { packages, capabilities, file }, both maps null-prototype; invalid-source when it is broken. */
+export function parsePackageCatalog(text, file) {
+  let doc;
   try { doc = JSON.parse(text); }
-  catch (e) { throw oatsError("invalid-source", `broken package catalog ${file}: ${e.message}`); }
+  catch (e) {
+    // JSON.parse does not say where; the kernel's strict reader (same grammar) locates the error.
+    let line;
+    try { parseStrictJson(text, { maxBytes: 64 * 1024 * 1024 }); } catch (s) { if (Number.isInteger(s.provenance?.offset)) line = lineAt(text, s.provenance.offset); }
+    throw oatsError("invalid-source", `broken package catalog ${file}${line ? ` (line ${line})` : ""}: ${e.message}`);
+  }
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw oatsError("invalid-source", `broken package catalog ${file}: root must be a JSON object`);
   const out = { packages: Object.create(null), capabilities: Object.create(null), file };
   const packages = doc.packages;
@@ -2082,6 +2115,12 @@ export function upgradeHomeMeta(meta, home) {
   return { ...rest, ...(runtime !== undefined || meta.harness !== undefined ? { harness: meta.harness ?? runtime } : {}), ...(meta.launch !== undefined ? { launch: upgradeLaunchRecipe(meta.launch) } : {}) };
 }
 const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
+/** The fixed prompt a codex launch starts with: it names the task file, never its text (argv is
+ *  readable by every local user). Codex reads the file with a tool. */
+export const CODEX_TASK_PROMPT = "Read TASK.md in this directory first: it is your briefing and your task.";
+/** The prompt each harness gets, so the task's text never travels in argv: Claude Code inlines an
+ *  `@file` mention; codex is pointed at the file. pi takes `@TASK.md` among its own arguments. */
+const TASK_PROMPT = Object.freeze({ claude: "@TASK.md", codex: CODEX_TASK_PROMPT });
 
 /** The executable a launch uses: a configuration's declared one (a bare name
  *  on PATH; a path against the deployment directory when relative) or the
@@ -2362,7 +2401,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
   }
   let cmdline;
   if (harness === "claude") {
-    cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+    cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- ${shq(TASK_PROMPT.claude)}`;
   } else if (harness === "codex") {
     const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
     // Codex may run tool commands outside the session's process (its shared app-server daemon),
@@ -2370,7 +2409,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
     // never goes on argv, and PATH is the execution's (CODEX_TOOL_PATH: the shim first).
     const toolEnvArgs = env.filter((e) => !e.reference && e.name !== "PATH")
       .map((e) => ` -c ${shq(`shell_environment_policy.set.${e.name}=${JSON.stringify(e.value)}`)}`).join("");
-    cmdline = `${shq(executable)} --cd ${shq(home)} -c check_for_update_on_startup=false${yolo ? " --yolo" : ""}${yolo || trustHome ? ` -c ${shq(codexTrust)}` : ""}${toolEnvArgs}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+    cmdline = `${shq(executable)} --cd ${shq(home)} -c check_for_update_on_startup=false${yolo ? " --yolo" : ""}${yolo || trustHome ? ` -c ${shq(codexTrust)}` : ""}${toolEnvArgs}${model ? ` --model ${shq(model)}` : ""}${tail} -- ${shq(TASK_PROMPT.codex)}`;
   } else {
     // Decision 13: pi starts NORMALLY — its own skill discovery (~/.pi/agent/skills,
     // .agents/skills up the tree, so the instance's copied capability skills are
@@ -2387,7 +2426,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
  * with the home's kernel shim first on PATH (every launch runs through here). */
 function nativeRecordCommand(command, home, harness) {
   const { tokens, binary } = parseLaunchCommand(command);
-  const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
+  const args = tokens.slice(binary + 1).map(t => t.value ?? t.text);
   const id = prepareNativeStart(home, harness);
   const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
   const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(harness)} ${shq(JSON.stringify(args))} && exec ${executionArgv(tokens, binary, harness).join(" ")}`;
@@ -3102,7 +3141,8 @@ function* spawnBody(root, agent, o = {}) {
   // apply of the same decision, or anything else) got here first, and this one
   // has touched nothing.
   mkdirSync(dirname(home), { recursive: true });
-  try { mkdirSync(home); }
+  // 0700: the home holds the instance's identity keys, TASK.md and transcripts.
+  try { mkdirSync(home, { mode: 0o700 }); }
   catch (e) {
     if (e?.code === "EEXIST") throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} already exists at ${home} (a concurrent spawn won the placement); nothing was created by this call`), { instance, home });
     throw e;
@@ -3355,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("; ")}` : "";
@@ -3536,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
@@ -3606,7 +3640,7 @@ You are instance "${instance}" of agent "${agent.name}".
 - Home: ${home}
 - Work tree: ./work — ${workDesc}
 - Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
-${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`);
+${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`, { mode: 0o600 }); // human text: the owner's only
 
     // Launch command. Spawn IS session start: the recipe is persisted in
     // instance.json beside its rendering, which is executed in the instance's
@@ -4074,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) }) {
@@ -4564,8 +4609,18 @@ export function inputInstanceSession(home, text) {
 
 // ---------------------------------------------------------------- session start
 
-/** The exact prompt token spawn renders for claude and codex launches. */
+/** The prompt token of a recorded claude or codex command that hands the harness the task's own
+ *  text in argv, where any local user can read it: `"$(cat TASK.md)"`. It is parsed, and replaced
+ *  when the home starts (withSafeTaskPrompt). */
 const LAUNCH_PROMPT_TOKEN = '"$(cat TASK.md)"';
+/** A recorded command with its harness's safe task prompt: a `"$(cat TASK.md)"` token becomes
+ *  TASK_PROMPT[harness]. Applied when a home starts from its recorded command, which is saved so. */
+export function withSafeTaskPrompt(command, harness) {
+  const { tokens } = parseLaunchCommand(command);
+  if (!tokens.some((t) => t.kind === "prompt")) return command;
+  if (!Object.hasOwn(TASK_PROMPT, harness)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `a ${harness} command never carried the task as "$(cat TASK.md)"; inspect the saved command in instance.json`);
+  return renderLaunchCommand(tokens.map((t) => t.kind === "prompt" ? { kind: "word", value: TASK_PROMPT[harness], quoted: true, text: shq(TASK_PROMPT[harness]) } : t));
+}
 
 /** Tokenize a persisted OATS launch command. The grammar is exactly what
  *  spawn renders: space-separated tokens that are env assignments NAME='v',
@@ -5004,6 +5059,8 @@ export function startInstanceSession(home, o = {}) {
       command = withLaunchModel(command, resolved);
       model = resolved; explicitModelFrom = "start";
     } else parseLaunchCommand(command);
+    // A recorded command starts, and is saved, with its harness's safe task prompt.
+    if (!launchPlan) command = withSafeTaskPrompt(command, harness);
     // References recorded for this home must resolve on this host on every
     // start path, and the source variables go to the pane, not the command.
     const recipeForEnv = launchPlan?.recipe || (meta.launch && typeof meta.launch === "object" ? meta.launch : null);
@@ -5098,7 +5155,7 @@ export function startInstanceSession(home, o = {}) {
     }
     target = { backend: "tmux", session, window, socket: resolve(socket) };
     // Keep launch evidence until the command exits or the target disappears.
-    // A transient child (for example cat TASK.md) is not proof that startup
+    // A transient child (for example the native-start recorder) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.
     try { return { ...record(meta, { id, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false), warnings }; }
     catch (e) {
@@ -5886,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.
@@ -5911,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"] }) }; }
@@ -5928,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 || {})) {
@@ -5987,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/lib/workspace.mjs

@@ -334,8 +334,9 @@ function schemaHint(kind, value) {
   }
   return "";
 }
-/** Parse + validate a declaration file → { value } | { problems }. Never throws. */
-function readDeclaration(kind, bytes, origin, validateOptions) {
+/** Parse + validate a declaration file (`kind` workspace | membership | soul | local) → { value } |
+ *  { problems }. Never throws. The reader `oats sync` uses, exported for the repository's validate. */
+export function readDeclaration(kind, bytes, origin, validateOptions) {
   const decoded = decodeDocument(bytes, origin);
   if (decoded.problems) return decoded;
   const problems = FILE_KINDS[kind].validate(decoded.value, validateOptions);

package/package-catalog.json

@@ -3,12 +3,12 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v4.0.5",
+      "ref": "v4.0.7",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.17.5",
+      "ref": "v1.17.7",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.34.1",
+  "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.5
+  oats.okf: v4.0.7
 defaults:
   capabilities: { oats.core: { from: package } }
   knowledge: { oats.okf: { from: package } }