@awebai/oats 0.34.4 → 0.35.0

package/bin/oats.mjs

@@ -3059,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)`);
@@ -3778,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}}
 ```
 

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.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": {

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

package/package-catalog.json

@@ -3,7 +3,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v4.0.7",
+      "ref": "v4.1.0",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

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

@@ -249,3 +249,58 @@ source custody. The library alternative is `sessionsForHome(home, { roots })`:
 unspecified formats are excluded, and missing supplied roots fail. Synthetic
 standalone tests must choose one of these explicitly, not masquerade as a
 managed native launch. Background capture without `--home` is unchanged.
+
+## One session file: `capture --file`
+
+```text
+capture --file <path> --format cc|pi|codex --home <instance home> [--owner <name>] [--json]
+```
+
+Captures ONE session file, for example an archived session that the
+`--home` sweep can no longer find, exactly as `--home` capture of that
+instance would capture it. It runs under the capture lock, as a final pass,
+with the ignore rules applied. The stream is `<owner>~<source>.<session id>`,
+the same identity `--home` capture writes. So the same session captured
+either way, or again with `--file`, appends nothing.
+
+- **The owner is explicit.** It is `--owner` or `TURN_RECORD_OWNER`; the
+  hostname is never assumed. `--home` must be an OATS instance home (an
+  `instance.json` naming an instance). It is recorded in the receipt, not
+  checked against the file's recorded cwd.
+- **The format is stated, never sniffed.** The file must carry that format's
+  session header somewhere in it:
+  - `cc`: a record with a `cwd`, and no other format's session header anywhere
+    in the file (a cc transcript never holds one);
+  - `pi`: the `session` record;
+  - `codex`: `session_meta`.
+- **The session id comes from the file name**, as for live capture: the cc
+  basename, the part of a pi name after its last `_`, or a codex name's
+  trailing uuid. A renamed file lands in another stream.
+- **One regular file, read once.** It is opened with `O_NOFOLLOW` and
+  `O_NONBLOCK` and fstat'ed. A symlink, FIFO, socket, device or directory is
+  refused. The bytes read from that descriptor are the ones captured and
+  hashed.
+
+`--json` prints the receipt:
+`{home, owner, file, format, instance, thread, stream, sessionId, turns,
+firstTurnId, lastTurnId, appended, skipped, held, incomplete, failed, ignored,
+status, complete, sha256, issues?}`. `sha256` is of the bytes captured;
+`issues` (`[{source, path, reason, offset}]`, present when the result is
+incomplete or held) says why. As for
+`--home`, `complete` is true only with no hold, no incomplete tail and no
+failure. A lock skip, a hold (no timestamp yet) and an incomplete tail (torn
+or invalid UTF-8) exit 0 with `complete: false`. Without `--json`, the output
+is one line.
+
+Anything that binds nothing is an error,
+`{status: "failed", complete: false, code, error}`:
+
+| code | exit | when |
+|---|---|---|
+| `E_USAGE` | 2 | a missing or invalid flag, a non-instance `--home`, no explicit owner, a second `--file`, another mode |
+| `E_FILE_UNREADABLE` | 1 | the file cannot be opened or read |
+| `E_NOT_REGULAR_FILE` | 1 | a symlink, FIFO, socket, device or directory |
+| `E_IGNORED` | 1 | a capture ignore rule excludes the file; nothing was opened, read or written |
+| `E_NO_TURNS` | 1 | no records: an empty file, or only blank lines |
+| `E_FORMAT` | 1 | records, but no session header of the stated format; the message names the format whose header it does carry |
+| `E_CAPTURE_FAILED` | 1 | the pass failed (`appended: null`: part of the file may be in the record) |

package/packages/record/bin/capture.mjs

@@ -12,15 +12,17 @@
 // accounts) whose sources are never captured — see lib/ignore.mjs.
 // Reconciliation is the capture; hooks and watch only decide when to run it.
 
-import { watch } from "node:fs";
+import { closeSync, constants, fstatSync, openSync, readFileSync, watch } from "node:fs";
 import { homedir, hostname } from "node:os";
-import { join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import process from "node:process";
 
 import { RecordStore } from "../lib/store.mjs";
 import { captureAllSessions, captureSessions } from "../lib/capture-cc.mjs";
 import { sessionsForHome } from "../lib/sessions-for-home.mjs";
-import { SESSION_FORMATS } from "../lib/formats.mjs";
+import { jsonlLines, SESSION_FORMATS } from "../lib/formats.mjs";
+import { cwdOfLine } from "../lib/sessions-for-home.mjs";
+import { digest, readRange } from "../lib/session-snapshot.mjs";
 import { captureAwLogs, defaultCommLogDir } from "../lib/capture-aw.mjs";
 import { RecordIndex } from "../lib/index-db.mjs";
 import { IgnoreError, ignoreFilePath, loadIgnore } from "../lib/ignore.mjs";
@@ -43,7 +45,7 @@ function loadIgnoreOrExit(recordRoot) {
 // hostname-derived owner, which forked the whole record into a second owner
 // namespace: 571 duplicate journals from one typo. Parsing must refuse what
 // it does not understand before anything can be written.
-const VALUE_FLAGS = new Set(["root", "owner", "home"]);
+const VALUE_FLAGS = new Set(["root", "owner", "home", "file", "format"]);
 const BOOL_FLAGS = new Set([
   "watch",
   "status",
@@ -54,6 +56,7 @@ const BOOL_FLAGS = new Set([
   "aw-only",
   "no-index",
   "current-roots",
+  "json",
 ]);
 
 const USAGE = `capture — land sessions and aw client logs in the turn record.
@@ -81,6 +84,29 @@ const USAGE = `capture — land sessions and aw client logs in the turn record.
                                explicit observer-time inventory for standalone
                                or legacy sources lacking launch history. Not a
                                certificate of all historical source locations.
+  capture --file <path> --format cc|pi|codex --home <dir> [--json]
+                               capture ONE session file (an archived session,
+                               say) as the --home capture of <dir> would: under
+                               the capture lock, as a final pass, ignore rules
+                               applied. <dir> must be an OATS instance home and
+                               the owner explicit (--owner or TURN_RECORD_OWNER;
+                               never the hostname). The format is never sniffed.
+                               The file must be a regular file (no symlink, FIFO
+                               or directory); it is read once. The session id
+                               comes from the file NAME, as for live capture: a
+                               renamed file lands in another stream. Again with
+                               the same file and owner appends nothing.
+                               --json prints {thread, stream, firstTurnId,
+                               lastTurnId, turns, appended, ignored, sha256 (of
+                               the bytes captured), status, complete, ...};
+                               without it, one line. Lock skips, holds and
+                               incomplete tails exit 0 with complete:false.
+                               Errors print {status:"failed", complete:false,
+                               code, error}: E_USAGE (exit 2); E_FILE_UNREADABLE,
+                               E_NOT_REGULAR_FILE, E_IGNORED (an ignore rule
+                               excludes it; nothing read), E_NO_TURNS (no
+                               records), E_FORMAT (no session header of that
+                               format) and E_CAPTURE_FAILED (exit 1).
   capture --install-hint       print the Claude Code hook snippet
   capture --help               this text
   capture --quiet              suppress per-pass progress
@@ -106,6 +132,7 @@ function parseArgs(argv) {
     if (VALUE_FLAGS.has(name)) {
       const value = argv[++i];
       if (value === undefined) throw new UsageError(`${a} needs a value`);
+      if (name === "file" && args.file !== undefined) throw new UsageError("one --file per call");
       args[name] = value;
     } else if (BOOL_FLAGS.has(name)) {
       args[name] = true;
@@ -121,6 +148,11 @@ try {
   args = parseArgs(process.argv.slice(2));
 } catch (err) {
   if (!(err instanceof UsageError)) throw err;
+  // --file --json answers JSON even for a usage error: it is for programs.
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify({ status: "failed", complete: false, code: "E_USAGE", error: err.message }, null, 2));
+    process.exit(2);
+  }
   console.error(`capture: ${err.message}\n\n${USAGE}`);
   process.exit(2);
 }
@@ -279,6 +311,171 @@ function pass() {
   });
 }
 
+/** A final capture of exact files, one batch per format, under the lock: counts into `outcome`, issues into
+ *  `issues`, then the index unless --no-index. → withCaptureLock's answer (`outcome`, or a skip). */
+function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, issues) {
+  return withCaptureLock(() => {
+    for (const [format, files] of batches) {
+      const r = captureSessions(recordStore, { owner: recordOwner, files, format, ignore, final: true });
+      outcome.appended += r.appended;
+      outcome.held += r.held;
+      outcome.incomplete += r.incomplete;
+      outcome.ignored += r.ignored;
+      issues.push(...r.issues);
+    }
+    if (!args["no-index"]) { // an earlier append-only pass may have left unindexed turns
+      const index = new RecordIndex(recordStore);
+      try {
+        index.update();
+      } finally {
+        index.close();
+      }
+    }
+    return outcome;
+  });
+}
+
+/** A stream's turns that no tombstone hides. A tombstoned turn is hidden everywhere; a boundary naming one
+ *  would be refused by recall, so boundaries come from the visible turns only. */
+function visibleTurns(recordStore, stream, claims = recordStore.tombstoneClaims()) {
+  return recordStore.readStream(stream).filter((t) => !recordStore.claimHides(claims, t));
+}
+
+/** The outcome vocabulary: complete only with no failure, skip, hold or incomplete tail (and, for --home, no
+ *  unattributed source). */
+function statusOf(outcome, unattributed = 0) {
+  return outcome.failed ? "failed" : outcome.skipped ? "skipped" : outcome.held ? "held" : outcome.incomplete || unattributed ? "incomplete" : "complete";
+}
+
+// capture --file: ONE session file the operator attributes to an instance home (an archived session the
+// --home sweep can no longer find), captured exactly as --home capture would capture it: same stream
+// identity, same lock, final, ignore rules applied. The file is opened once and read from that descriptor;
+// the receipt's sha256 is of the bytes captured. Every outcome that binds nothing is an error code.
+const SESSION_HEADER = { cc: "a record with a cwd", pi: "a session record with a cwd", codex: "a session_meta record with a payload cwd" };
+const HEADER_HINT = { cc: "a cc record with a cwd", pi: "a pi session header", codex: "a codex session_meta header" };
+// pi and codex headers are specific; any record with a cwd reads as cc, so cc is named last.
+const HEADER_ORDER = ["pi", "codex", "cc"];
+
+/** Whether the headers `found` in a file make it a `stated` session. pi and codex need their header. cc needs a
+ *  record with a cwd and NO other format's session header anywhere in the file: a cc transcript never holds
+ *  one, so a single one is decisive (pi's session record carries a top-level cwd too). */
+function isFormat(found, stated) {
+  return stated === "cc" ? found.has("cc") && !found.has("pi") && !found.has("codex") : found.has(stated);
+}
+
+/** Records (non-blank lines, an undecodable one included) and the formats whose session header a COMPLETE
+ *  line carries. A pi or codex file is settled at its header; a cc file is judged whole. A line its writer
+ *  never terminated is no header. */
+function sessionHeaders(bytes, stated) {
+  let records = 0;
+  const found = new Set();
+  const terminated = bytes.length > 0 && bytes[bytes.length - 1] === 10;
+  const take = (text, complete) => {
+    if (text === null || text.trim() !== "") records++;
+    if (complete && text !== null) for (const source of HEADER_ORDER) if (cwdOfLine(source, text) !== undefined) found.add(source);
+  };
+  let pending;
+  for (const { text } of jsonlLines(bytes)) {
+    if (pending !== undefined) take(pending, true);
+    if (stated !== "cc" && found.has(stated)) return { records, found };
+    pending = text;
+  }
+  if (pending !== undefined) take(pending, terminated);
+  return { records, found };
+}
+
+function fileKind(stat) {
+  return stat.isDirectory() ? "a directory" : stat.isFIFO() ? "a FIFO" : stat.isSocket() ? "a socket" : stat.isCharacterDevice() || stat.isBlockDevice() ? "a device" : "not a regular file";
+}
+
+/** → the exit status. */
+function fileCapture() {
+  const json = Boolean(args.json);
+  const fail = (code, error, extra = {}) => {
+    if (json) console.log(JSON.stringify({ ...extra, status: "failed", complete: false, code, error }, null, 2));
+    else console.error(`capture --file: ${code}: ${error}`);
+    return code === "E_USAGE" ? 2 : 1;
+  };
+  if (args.file === undefined) return fail("E_USAGE", args.format !== undefined ? "--format needs --file" : "--json needs --file");
+  for (const mode of ["watch", "status", "install-hint", "sessions-only", "aw-only", "current-roots"]) {
+    if (args[mode]) return fail("E_USAGE", `--file does not combine with --${mode}`);
+  }
+  if (args.home === undefined) return fail("E_USAGE", "--file needs --home <instance home>: the instance the session belongs to");
+  let instance;
+  try {
+    const meta = JSON.parse(readFileSync(join(args.home, "instance.json"), "utf8"));
+    if (typeof meta?.instance === "string" && meta.instance) instance = meta.instance;
+  } catch { /* not an instance home: said below */ }
+  if (!instance) return fail("E_USAGE", `--home ${args.home} is not an instance home (no instance.json naming an instance)`);
+  const fileOwner = args.owner ?? process.env.TURN_RECORD_OWNER;
+  if (!fileOwner) return fail("E_USAGE", "--file needs an explicit owner: --owner <name> or TURN_RECORD_OWNER (the hostname is never assumed)");
+  if (args.format === undefined) return fail("E_USAGE", "--file needs --format cc|pi|codex (the format is never guessed)");
+  if (!Object.hasOwn(SESSION_FORMATS, args.format)) return fail("E_USAGE", `--format must be cc, pi or codex, not ${JSON.stringify(args.format)}`);
+  const fmt = SESSION_FORMATS[args.format];
+  // Absolute, as every other capture caller passes: path ignore rules, the offsets key and the receipt all
+  // read the path, and a relative spelling would slip past a path rule.
+  const path = resolve(args.file);
+  const where = { home: args.home, owner: fileOwner, file: path, format: args.format };
+
+  let ignore;
+  try { ignore = loadIgnore(root); } catch (err) { return fail("E_CAPTURE_FAILED", err.message, where); }
+  const sessionId = fmt.sessionId(path);
+  // Before the open, on the path and its keys, as every capture checks: an ignored file is never read.
+  if (ignore.ignores(path, [basename(path), sessionId, ...(fmt.ignoreKeys?.(path) ?? [])])) {
+    return fail("E_IGNORED", `a capture ignore rule (${ignoreFilePath(root)}) excludes ${path}; nothing was read`, where);
+  }
+  let fd;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (err) {
+    if (err.code === "ELOOP" || err.code === "EMLINK") return fail("E_NOT_REGULAR_FILE", `${path} is a symbolic link; pass the file it names`, where);
+    return fail("E_FILE_UNREADABLE", `cannot open ${path}: ${err.message}`, where);
+  }
+  let stat, bytes;
+  try {
+    stat = fstatSync(fd);
+    if (!stat.isFile()) return fail("E_NOT_REGULAR_FILE", `${path} is ${fileKind(stat)}, not a regular file`, where);
+    bytes = readRange(fd, 0, stat.size, path);
+  } catch (err) {
+    return fail("E_FILE_UNREADABLE", `cannot read ${path}: ${err.message}`, where);
+  } finally { closeSync(fd); }
+
+  const { records, found } = sessionHeaders(bytes, args.format);
+  if (!records) return fail("E_NO_TURNS", `${path} has no records${bytes.length ? " (only blank lines)" : " (it is empty)"}`, where);
+  if (!isFormat(found, args.format)) {
+    const other = HEADER_ORDER.find((f) => f !== args.format && isFormat(found, f));
+    return fail("E_FORMAT", other
+      ? `${path} is not a ${args.format} session: it has ${HEADER_HINT[other]}; pass --format ${other}`
+      : `${path} has no ${args.format} session header (${SESSION_HEADER[args.format]})`, where);
+  }
+
+  const sha256 = digest(bytes);
+  const fileStore = new RecordStore(root, { owner: fileOwner });
+  const outcome = { appended: 0, skipped: false, held: 0, incomplete: 0, failed: 0, ignored: 0 };
+  const issues = [];
+  try {
+    Object.assign(outcome, captureUnderLock(fileStore, fileOwner, [[args.format, [{ path, pinned: { bytes, stat } }]]], ignore, outcome, issues));
+  } catch (err) {
+    // A failed pass may have appended part of the file: never claim a count for it.
+    return fail("E_CAPTURE_FAILED", err.message || String(err), { ...where, sha256, appended: null });
+  }
+  if (process.exitCode) return fail("E_CAPTURE_FAILED", "capture lock release failed; see stderr for recovery", { ...where, sha256 });
+
+  const stream = `${fileOwner}~${fmt.source}.${sessionId}`;
+  const turns = visibleTurns(fileStore, stream);
+  const status = statusOf(outcome);
+  const { lock: _lock, ...counts } = outcome;
+  const receipt = {
+    ...where, instance, thread: `${fmt.source}:session:${sessionId}`, stream, sessionId,
+    turns: turns.length, firstTurnId: turns[0]?.id ?? null, lastTurnId: turns.at(-1)?.id ?? null,
+    ...counts, status, complete: status === "complete", sha256, ...(issues.length ? { issues } : {}),
+  };
+  if (json) console.log(JSON.stringify(receipt, null, 2));
+  else console.log(`capture --file: ${status}, ${receipt.turns} turns (${outcome.appended} new) in ${stream}, sha256 ${sha256}`);
+  return 0;
+}
+
+if (args.file !== undefined || args.format !== undefined || args.json) process.exit(fileCapture());
+
 if (args["install-hint"]) {
   const self = new URL(import.meta.url).pathname;
   console.log(`Add to Claude Code settings.json to capture on session stop/end:
@@ -337,31 +534,11 @@ if (args.home) {
       if (!formats.has(s.source)) formats.set(s.source, []);
       formats.get(s.source).push(s);
     }
-    Object.assign(outcome, withCaptureLock(() => {
-      for (const [format, files] of formats) {
-        const r = captureSessions(store, { owner, files, format, ignore, final: true });
-        outcome.appended += r.appended;
-        outcome.held += r.held;
-        outcome.incomplete += r.incomplete;
-        outcome.ignored += r.ignored;
-        issues.push(...r.issues);
-      }
-      if (!args["no-index"]) { // an earlier append-only pass may have left unindexed turns
-        const index = new RecordIndex(store);
-        try {
-          index.update();
-        } finally {
-          index.close();
-        }
-      }
-      return outcome;
-    }));
-    // A tombstoned turn is hidden everywhere; a boundary naming one would be
-    // refused by recall, so boundaries come from the visible turns only.
+    Object.assign(outcome, captureUnderLock(store, owner, formats, ignore, outcome, issues));
     const claims = store.tombstoneClaims();
     for (const s of found) {
       const stream = `${owner}~${s.source}.${s.sessionId}`;
-      const turns = store.readStream(stream).filter((t) => !store.claimHides(claims, t));
+      const turns = visibleTurns(store, stream, claims);
       if (!turns.length) continue; // ignored by rule, nothing capturable yet, or all hidden
       sessions.push({
         thread: s.thread,
@@ -389,7 +566,7 @@ if (args.home) {
     outcome.failed++;
     error = "capture lock release failed; see stderr for recovery";
   }
-  const status = outcome.failed ? "failed" : outcome.skipped ? "skipped" : outcome.held ? "held" : outcome.incomplete || unattributed.length ? "incomplete" : "complete";
+  const status = statusOf(outcome, unattributed.length);
   console.log(JSON.stringify({ home: args.home, owner, ...outcome, status, complete: status === "complete", sessions, sourceRoots: args["current-roots"] ? "current-env" : "launch-history",
     ...(error ? { error } : {}), ...(issues.length ? { issues } : {}), ...(unattributed.length ? { unattributed } : {}),
   }, null, 2));

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

@@ -189,6 +189,10 @@ function offsetFromJournal(store, streamId, sourcePath, final, sourceBytes) {
 // `final` also verifies unchanged offsets against journals and checks source
 // stability through the pass. The caller must quiesce writers for retirement;
 // a performed pass is a snapshot, not a promise about future writes.
+//
+// A file given as `{ path, pinned: { bytes, stat } }` is PINNED: its caller opened it once and read these bytes from
+// that descriptor (`capture --file`). It is captured from them as a final pass, never opened again, so the
+// turns are exactly those bytes; `path` keys its offsets as for any other file.
 export function captureSessions(store, { owner, roots, files, format = "cc", ignore = null, final = false }) {
   const fmt = SESSION_FORMATS[format];
   if (!fmt) throw new Error(`unknown session format ${format}`);
@@ -205,6 +209,7 @@ export function captureSessions(store, { owner, roots, files, format = "cc", ign
 
   for (const file of files ?? fmt.listFiles(roots)) {
     const path = typeof file === "string" ? file : file.path;
+    const pinned = typeof file === "string" ? null : file.pinned ?? null;
     const expected = typeof file === "string" ? null : file.snapshot;
     const capturedPi = typeof file === "string" ? undefined : file.capturedPi ?? expected?.capturedPi;
     if (capturedPi && (fmt.source !== "pi" || (expected?.capturedPi && !isDeepStrictEqual(capturedPi, expected.capturedPi)))) throw new Error("protected capture proof/format differs from discovery");
@@ -215,20 +220,21 @@ export function captureSessions(store, { owner, roots, files, format = "cc", ign
       ignored++;
       continue; // never opened: nothing stored, nothing remembered
     }
-    const fd = openSync(path, capturedPi ? constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK : "r");
+    const fd = pinned ? null : openSync(path, capturedPi ? constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK : "r");
     try {
     if (capturedPi) assertProtectedDescriptor(fd, path, capturedPi);
-    const stat = fstatSync(fd);
+    const stat = pinned ? pinned.stat : fstatSync(fd);
     const snapshot = { ...identity(stat), ...(capturedPi ? { capturedPi } : {}) };
     if (expected) assertIdentity(stat, expected, path); // BEFORE reading bytes
     // Final home capture stages a descriptor-pinned snapshot. All attribution
     // and stability checks precede the first append, never a post-write alarm.
-    const sourceBytes = final || expected || capturedPi ? readRange(fd, 0, stat.size, path, capturedPi) : undefined;
+    const sourceBytes = pinned ? pinned.bytes : final || expected || capturedPi ? readRange(fd, 0, stat.size, path, capturedPi) : undefined;
     if (expected && digest(sourceBytes.subarray(0, expected.size)) !== expected.hash) {
       throw new Error(`session source content changed since attribution: ${path}`);
     }
     if (sourceBytes) snapshot.hash = digest(sourceBytes);
     const verifySource = () => {
+      if (pinned) return; // the bytes are the source: nothing is read from the path again
       guardCapturedPath(path, capturedPi);
       if (sourceBytes) verifySnapshot(fd, path, snapshot);
     };
@@ -354,7 +360,7 @@ export function captureSessions(store, { owner, roots, files, format = "cc", ign
     // wasted append-only bytes).
     if (grew) saveOffsets(store, offsets);
     verifySource();
-    } finally { closeSync(fd); }
+    } finally { if (fd !== null) closeSync(fd); }
   }
   saveOffsets(store, offsets);
   return {

package/packages/record/lib/sessions-for-home.mjs

@@ -58,7 +58,9 @@ function* wholeLines(fd, bound, path, capturedPi) {
   // Never attribute a source using a line its writer has not terminated.
 }
 
-function cwdOfLine(source, line) {
+/** The cwd a native line carries as its format's session header (cc: any record's `cwd`; pi: the `session`
+ *  record; codex: `session_meta`), else undefined. */
+export function cwdOfLine(source, line) {
   if (line === null || !line.trim()) return undefined;
   let d;
   try {

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