@awebai/oats 0.34.3 → 0.35.0

package/bin/oats.mjs

@@ -2256,6 +2256,8 @@ async function spawnCmd() {
     if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
     if (e?.code === "E_CHILD_SPAWNS_DISABLED") { bail(e.code, e.message, { parent: e.parent, policy: e.policy }); throw e; }
     if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
+    // The observed base could not be fetched into the clone: the clone, the repository and the commit travel along.
+    if (e?.code === "E_REMOTE_UNREADABLE" && e.details?.commit) { bail(e.code, e.message, e.details); throw e; }
     // K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
     if (e?.code === "E_DECISION_STALE") { bail(e.code, e.message, { decision: e.decision }); throw e; }
     if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
@@ -2283,7 +2285,7 @@ async function spawnCmd() {
     // Desktop CLI API v1 spawn result — a FIXED shape (see docs/desktop-cli-api.md).
     jsonOk({
       instance: r.instance, agent: r.agent, home: r.home, work: r.work,
-      branch: r.branch || null, launched: r.launched, warnings: r.warnings || [],
+      branch: r.branch || null, base: r.base ?? null, launched: r.launched, warnings: r.warnings || [],
       ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
       tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
       model: r.model || null, parent: r.parentInstance || null,
@@ -2299,6 +2301,7 @@ async function spawnCmd() {
   }
   console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
   console.log(`  home:   ${shortPath(r.home)}`);
+  if (r.base) console.log(`  base:   ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
   if (wakeSchedule) console.log(`  wake:   schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
   if (wakeScheduleError) console.error(`  wake:   NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
   if (!r.launched) console.log(`  launch: oats session start --home ${shellQuote(r.home)}`);
@@ -3056,7 +3059,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3775,6 +3778,9 @@ The turn record (core — every conversation captured, searchable, replicated):
   oats capture [--watch|--status]            land Claude Code/pi/codex sessions and aw
       [--owner <name>] [--root <dir>]       client logs in the record; reconciliation
                                             is the capture
+  oats capture --file <path> --format cc|pi|codex --home <instance home> [--json]
+                                            one session file (an archived session),
+                                            captured as --home capture would
   oats recall [--kind k] [--thread t]        search the whole record — mail, chat,
       [--from f] [--show id] <query>        sessions — with exact turn provenance
   oats setup [--owner <name>] [--dry-run]    install capture hooks + background watcher

package/docs/desktop-cli-api.md

@@ -38,7 +38,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
              "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
              "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
              "team-model-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
-             "preview-composed-from","observe-max-age","spawn-preview-max-age","capability-show"],
+             "preview-composed-from","observe-max-age","spawn-preview-max-age","capability-show","capture-file"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
  "capabilityShowApi":1}
@@ -99,6 +99,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `observe-max-age` | `--max-age <s>` on the read verbs and their `observation` block ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)) | |
 | `spawn-preview-max-age` | `--max-age <s>` on `spawn --preview` and its `observation` block ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311), [The preview](#the-preview)) | |
 | `capability-show` | `oats capabilities show <name>` and its `--file` form, OATS 0.34.0 ([`oats capabilities show`](#oats-capabilities-show)) | `capabilityShowApi: 1` |
+| `capture-file` | `oats capture --file <path> --format cc\|pi\|codex --home <instance home> [--json]`: one session file captured as `--home` capture would, with a receipt bound to its bytes, OATS 0.35.0 (the capture USAGE and packages/record/README.md) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -723,7 +724,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.7","ref":"v4.0.7"}}],
+              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.1.0","ref":"v4.1.0"}}],
  "declaredPackages":["oats.framework","oats.okf"],"unsynced":["oats.framework"],"stale":[],
  "external":[{"source":"git:github.com/oss/experts@3c606e09…","soul":"security-reviewer"}],
  "problems":[],"warnings":[],
@@ -782,8 +783,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.7","kind":"package","package":"oats.okf",
-    "version":"4.0.7","repoKey":"github.com/awebai/oats-okf","commit":"e460b29a…","teams":null,"defaultTeam":null,"private":false,
+   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.1.0","kind":"package","package":"oats.okf",
+    "version":"4.1.0","repoKey":"github.com/awebai/oats-okf","commit":"e331a996…","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 +873,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.7",
- "commit":"e460b29a…","path":"oats-package/capabilities/oats-okf",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.1.0",
+ "commit":"e331a996…","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 +900,7 @@ nothing reads a working clone.
 **The `--file` answer:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e460b29a…",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e331a996…",
  "file":{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787,"text":"---\nname: okf-instance-knowledge\n…","binary":false,"truncated":false}}
 ```
 
@@ -1394,13 +1395,13 @@ it to a temporary copy (`soulFetched: true`).
  "settingsOrigins":{"nw-tools":{},"oats.okf":{"/owns":{"kind":"soul","at":"soul.yaml#/knowledge"}}},
  "spawnPreviewApi":2,"preview":true,"agent":"rm","kind":"persistent","instance":"rm-api","home":"/w/agents/rm/instances/rm-api",
  "repo":"/w/agents-repo","work":"worktree","subject":{"soul":"rm","agentsRoot":null,"dir":"/w"},
- "decision":{"instance":"rm-api","home":"/w/agents/rm/instances/rm-api","branch":"agents/rm-api","base":{"ref":"HEAD","oid":"66566512…"},
+ "decision":{"instance":"rm-api","home":"/w/agents/rm/instances/rm-api","branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},
              "effective":{"repo":"/w/agents-repo","work":"worktree","harness":"pi","model":null,"launchConfig":null,"yolo":null,"backend":"tmux",
                           "childSpawns":true,"relation":null,"providers":{"nw-tools":{},"oats.okf":{"owns":"rm"}}},
              "resolution":"abacbdb5a7975098d77007c8","revision":"c557d8ec9a272ba1c1739dc3"},
  "preflight":{"status":"complete","budgetMs":20000,"elapsedMs":53},"backendStatus":{"name":"tmux","installed":true,"started":false},
  "harness":"pi","model":null,"modelSource":"native default","launchConfig":null,"backend":"tmux",
- "branch":"agents/rm-api","base":{"ref":"HEAD","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
+ "branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
  "executable":"/usr/local/bin/pi",
  "capabilities":[{"name":"nw-tools","origin":"member:github.com/nw/agents@66566512…"},{"name":"oats.okf","origin":"package:oats.okf@2.1.3"}],
@@ -1415,8 +1416,11 @@ it to a temporary copy (`soulFetched: true`).
   else `null`) are canonical: never derive paths.
 - `repo`: `--repo`, else the `clones:` entry, else `<deployment>/<member>`.
 - `branch` defaults to `agents/<instance>` (`--branch` overrides); `base` is
-  `--base` (default `HEAD`) resolved to `oid`. `E_BRANCH_EXISTS` and
-  `E_BASE_UNKNOWN` refuse preview and apply alike.
+  `--base` resolved to `oid`. Without `--base`, when `repo` is a clone of the
+  soul's repository, `base` is `{ref: <repo key>, oid: <the commit the spawn
+  observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
+  cannot be); otherwise `HEAD`. `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN` refuse
+  preview and apply alike.
 - `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
 
 **Launch.**
@@ -1534,7 +1538,8 @@ with `--expect-decision` records the key and decision in `instance.json`.
 **Result** (`oats spawn <soul> … --json`):
 
 ```json
-{"instance":"rm-api","agent":"rm","home":"/w/agents/rm/instances/rm-api","work":"worktree","branch":"agents/rm-api","launched":true,"warnings":[],
+{"instance":"rm-api","agent":"rm","home":"/w/agents/rm/instances/rm-api","work":"worktree","branch":"agents/rm-api",
+ "base":{"ref":"github.com/nw/agents","oid":"66566512…"},"launched":true,"warnings":[],
  "tmux":{"session":"oats-agents","window":"rm-api"},"backend":"tmux","repo":"/w/agents-repo","harness":"pi","model":null,"parent":null,"sibling":null,"relation":null,
  "spawnOrigin":"operator","attach":"tmux attach -t oats-agents","decision":{"instance":"rm-api","revision":"c557d8ec9a272ba1c1739dc3"},"replayed":false,
  "wake":{"requested":false,"saved":null,"error":null},"launchConfig":null,
@@ -1544,7 +1549,8 @@ with `--expect-decision` records the key and decision in `instance.json`.
 
 (`decision` is abridged: it is the full bound decision.)
 
-- Always present: `instance, agent, home, work, branch, launched, warnings
+- Always present: `instance, agent, home, work, branch, base ({ref, oid}
+  the new branch started at; `null` without one), launched, warnings
   (array), tmux ({session, window} | null), backend ("tmux"), repo, harness,
   model, parent,
   sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
@@ -1608,7 +1614,8 @@ workspace-model fields (feature `instance-modules`):
 
 ```json
 {"agent":"rm","kind":"persistent","instance":"rm-api","home":"/w/agents/rm/instances/rm-api","soulDir":"/w/agents/rm/souls/66566512168e",
- "repo":"/w/agents-repo","work":"worktree","branch":"agents/rm-api","harness":"pi","modelFrom":"harness-default","spawnOrigin":"operator",
+ "repo":"/w/agents-repo","work":"worktree","branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},
+ "harness":"pi","modelFrom":"harness-default","spawnOrigin":"operator",
  "policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
  "modules":{"oats.okf":{"from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
                         "commit":"ab897841…","digest":"sha256-9a0e…","materializedAt":"2026-09-28T10:08:01.100Z"}},
@@ -1635,6 +1642,8 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
   the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
   `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
   `<home>/.agents/skills/<cap>/<skill>/`).
+- `base` (a worktree instance): `{ref, oid}`, the commit its branch started
+  at, as the spawn result states it (see Placement under the spawn preview).
 - `providers.<cap>`: the merged payload (`{}` when none).
 - `workspace`: `{key, name, deployment, commit, resolution, standalone, soul,
   layers}`. `name` is recorded, and every hook, command and operation of the
@@ -2023,8 +2032,15 @@ A first retire prints the **raw receipt**, not an envelope:
 
 - `retention`: `{worktree: "retained" | "removed" | "absent", movedTo?,
   branch, detachedAt?, recordedBranch, branchDeleted?,
-  branchDeletionSkipped?: {expected, actual, reason}}`, or `null` for a
-  non-worktree mode.
+  branchDeletionSkipped?: {expected, actual, reason}}`, or `null` when no
+  worktree step ran: a non-worktree mode, or a worktree kept for the retry.
+  A retire whose hooks left cleanup outstanding keeps the worktree exactly as
+  it was (with `worktreeRemoved: false`) and says why in `rollbackIncomplete`
+  (`git worktree <path>: kept for the retry; outstanding: …`); the retry does
+  the step once nothing else is outstanding. A work directory whose git admin
+  entry is gone is never touched: it is an incomplete item (`git worktree
+  <path>: its admin entry is missing; …`), and `--force` refuses it with
+  `E_WORK_PRESERVATION_FAILED`.
 - `--discard-worktree` removes the worktree. `--delete-branch` deletes the
   worktree's verified branch (re-verified at deletion time) and implies
   discarding; a mismatch deletes nothing and reports

package/docs/integrations.md

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

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.7
+  oats.okf: v4.1.0
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:

package/docs/official-catalog.md

@@ -10,7 +10,7 @@ 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.7` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.okf` | `v4.1.0` | `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` | |
@@ -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.7`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.1.0`); `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.7                                    # bare version → the official catalog
+  oats.okf: v4.1.0                                    # 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.7`, `4.0.7`, `1.0.0-rc.1`): the id is looked up in
+- **Bare version** (`v4.1.0`, `4.1.0`, `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.7` or `oats-framework/v1.4.1`) and the payload path. An id
+  convention (`v4.1.0` 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,7 +75,7 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.4.1
-  oats.okf: v4.0.7
+  oats.okf: v4.1.0
   oats.aweb: v1.17.7
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -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.7 ✓ (@ e460b29a)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.1.0 ✓ (@ e331a996)
 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
@@ -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.7",
-      "commit": "e460b29aaf23db5728d7c64f7b5fb63f5014546b",
+      "version": "4.1.0",
+      "commit": "e331a9969d10aabddaa5824991f1846c7dedb388",
       "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.7", "path": "oats-package" },
+    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.0", "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.4.md

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

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

@@ -0,0 +1,53 @@
+# OATS 0.35.0
+
+## Added
+
+- **oats.okf 4.1.0** (catalog and workspace pin, and the bundled mirrors):
+  `oats okf harvest --once`, a one-shot reviewed harvest of one seat from an
+  explicit record set (awebai/oats-okf#37). A seat that moved (classic to v2)
+  or was spawned with harvest off had no way to get its notes into the
+  knowledge base. The operator now runs, from the deployment:
+
+  ```sh
+  oats okf harvest --once --home <seat home> --records <manifest> --soul <its soul> [--override-opt-out]
+  ```
+
+  - The manifest lists note files, each with its sha256, in the seat's home
+    or a listed archive directory. Each file is checked against the bytes
+    used, with no symlinks, directories or globbing. A bad entry refuses
+    everything before anything is stored.
+  - The harvester judges and opens a PR that the knowledge-maintainer
+    reviews, as for every harvest. It writes only to the soul's own nodes.
+  - Nothing is registered: no schedule and no capture. Rerunning the same
+    command continues a large set run by run (each run says how many inputs
+    remain), or answers `already-delivered`.
+  - A soul's opt-out is refused unless `--override-opt-out`, which the PR
+    records. The host's harvest switch does not apply.
+  - Archived session records come in a later oats.okf, through `oats capture
+    --file` (below).
+
+- **`oats capture --file <path> --format cc|pi|codex --home <instance home> [--json]`**
+  (feature `capture-file`). It captures one session file, such as an
+  archived session the `--home` sweep can no longer find, exactly as
+  `--home` capture of that instance would. It is for oats.okf's one-shot
+  reviewed harvest of archived sessions (awebai/oats-okf#37).
+  - The owner is explicit (`--owner` or `TURN_RECORD_OWNER`, never the
+    hostname), and `--home` must be an instance home.
+  - The stream identity is the one `--home` capture writes, so capturing the
+    same session either way, or again, appends nothing.
+  - The format is stated and checked against the file's session header,
+    never sniffed.
+  - Only one regular file is read, once, from its descriptor: a symlink,
+    FIFO or directory is refused.
+  - The receipt binds to the bytes: `{thread, firstTurnId, lastTurnId,
+    turns, ignored, sha256, ...}`.
+  - An outcome that binds nothing is an error code: `E_IGNORED`,
+    `E_NO_TURNS`, `E_FORMAT`, `E_NOT_REGULAR_FILE`, `E_FILE_UNREADABLE`,
+    `E_USAGE`, and `E_CAPTURE_FAILED` for a pass that failed (`appended:
+    null`). See packages/record/README.md.
+
+## Changed
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.36.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.35.0 together: the
+  Desktop 0.34.x refuses a 0.35 CLI.

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

package/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.7
+  oats.okf: v4.1.0
   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