@awebai/oats 0.22.19 → 0.23.1

package/lib/schedule.mjs

@@ -24,7 +24,7 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
-import { ensureRoot, findAgent, findCapabilityAgent, findInstanceHomes, teamAgentRoots, configChain, spawnInstance, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
+import { RESERVED_LAUNCH_ENV, ensureRoot, findAgent, findCapabilityAgent, findInstanceHomes, teamAgentRoots, configChain, spawnInstance, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
 export const SCHEDULE_API = 1;
@@ -355,7 +355,17 @@ function launchCommand(ws, def, io) {
   let envelope, timedOut = false, raw = "";
   if (io?.command) envelope = io.command({ cwd: def.cwd, argv });
   else {
-    const env = { ...process.env }; delete env.OATS_INSTANCE; delete env.OATS_INSTANCE_HOME; delete env.PI_AGENT_INSTANCE; delete env.PI_AGENT_HOME;
+    const env = { ...process.env };
+    // A schedule may be ticked/run-now from inside an unrelated instance.
+    // Dispatch belongs to the job's cwd/explicit selectors, never that
+    // caller's frozen capability snapshot (including legacy OATS_HOME).
+    // Keep host configuration such as OATS_HOME_DIR and credentials intact.
+    for (const key of [...RESERVED_LAUNCH_ENV,
+      "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
+      "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
+      "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
+      "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
+    ]) delete env[key];
     const r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: def.cwd, encoding: "utf8", timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env });
     timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal === "SIGTERM");
     raw = String(r.stdout || "");

package/package-catalog.json

@@ -2,7 +2,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.6.1",
+      "ref": "v2.0.0",
       "path": "oats-package"
     },
     "oats.aweb": {
@@ -29,6 +29,11 @@
       "url": "https://github.com/awebai/oats-dev.git",
       "ref": "v1.0.0",
       "path": "oats-package"
+    },
+    "oats.knowledge-theory": {
+      "url": "https://github.com/awebai/oats.git",
+      "ref": "v0.23.0",
+      "path": "oats-package"
     }
   },
   "capabilities": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.19",
+  "version": "0.23.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",
@@ -15,7 +15,7 @@
   "type": "module",
   "scripts": {
     "test": "node scripts/run-tests.mjs",
-    "check": "node --check lib/core.mjs && node --check lib/packages.mjs && node --check bin/oats.mjs",
+    "check": "node scripts/check-package-dry-runs.mjs --syntax-only",
     "check:pi": "node --experimental-strip-types --check packages/pi/extension/index.ts",
     "validate": "node scripts/validate-project.mjs",
     "validate:okf": "node scripts/validate-okf.mjs",

package/packages/record/README.md

@@ -209,3 +209,22 @@ into an orphaned inode until it restarts.
 
 - Deletion via tombstone is eventual: an offline replica retains bytes until
   it reconnects. The SOT says this plainly; so do we.
+
+## Per-home source authority
+
+`capture --home <dir>` defaults to the kernel's independent managed-launch
+record-location history, retained beside the home under `.oats-native-record/`.
+It does not re-resolve old `fromEnv` references using the capturing process.
+Missing history (legacy/standalone), pending launches, and missing historical
+roots fail closed instead of certifying empty observer storage. Runtime switches
+and resumed starts retain earlier roots. A managed scaffold with no starts has
+an empty managed-launch inventory; executing a saved recipe by hand is not a
+managed start.
+
+For a deliberately observer-time inventory, explicitly pass `--current-roots`.
+The JSON labels this `sourceRoots: "current-env"`, rather than `"launch-history"`;
+completion then applies only to the chosen current inventory, not historical
+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.

package/packages/record/bin/capture.mjs

@@ -14,7 +14,7 @@
 
 import { watch } from "node:fs";
 import { homedir, hostname } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import process from "node:process";
 
 import { RecordStore } from "../lib/store.mjs";
@@ -53,6 +53,7 @@ const BOOL_FLAGS = new Set([
   "sessions-only",
   "aw-only",
   "no-index",
+  "current-roots",
 ]);
 
 const USAGE = `capture — land sessions and aw client logs in the turn record.
@@ -65,10 +66,21 @@ const USAGE = `capture — land sessions and aw client logs in the turn record.
   capture --status             show store/stream summary, capture nothing
   capture --home <dir>         capture the sessions that ran inside <dir> (an
                                OATS instance home) and print them as JSON:
-                               thread, stream, turn count, first/last turn id.
-                               Tombstoned turns are never a boundary. Codex
-                               keeps a day's rollouts in one directory, so the
-                               pass captures that day; the list is filtered.
+                               thread, stream, turn count, first/last turn id;
+                               status, complete, skipped, held, incomplete,
+                               failed, ignored (explicit privacy exclusions).
+                               Only complete:true confirms a performed pass
+                               with no holds, incomplete tails, unattributed
+                               sources or errors. Lock skips/holds exit 0 but
+                               report complete:false; failures exit 1.
+                               Only attributed files are captured, even in
+                               shared directories. Unattributed non-ignored
+                               sources conservatively block completion.
+                               Tombstoned turns are never a boundary.
+  capture --current-roots --home <dir>
+                               explicit observer-time inventory for standalone
+                               or legacy sources lacking launch history. Not a
+                               certificate of all historical source locations.
   capture --install-hint       print the Claude Code hook snippet
   capture --help               this text
   capture --quiet              suppress per-pass progress
@@ -188,8 +200,9 @@ function withCaptureLock(fn) {
     // Never quiet: a stale lock after a killed pass needs the operator, and
     // the line says exactly what to check and what to remove.
     const line = `capture: another pass holds ${root}: ${lock.held.recovery}; skipping this pass`;
-    if (lock.held.liveness === "alive") log(line); else console.error(line);
-    return { appended: 0, skipped: true };
+    if (args.home) { if (!quiet || lock.held.liveness !== "alive") console.error(line); }
+    else if (lock.held.liveness === "alive") log(line); else console.error(line);
+    return { appended: 0, skipped: true, lock: lock.held };
   }
   try {
     return fn();
@@ -217,7 +230,7 @@ function pass() {
   if (!args["aw-only"]) {
     for (const r of captureAllSessions(store, { owner, ignore })) {
       out.appended += r.appended;
-      const extras = [r.ignored ? `${r.ignored} ignored` : "", r.held ? `${r.held} held` : ""]
+      const extras = [r.ignored ? `${r.ignored} ignored` : "", r.held ? `${r.held} held` : "", r.incomplete ? `${r.incomplete} incomplete` : ""]
         .filter(Boolean)
         .join(", ");
       log(
@@ -300,52 +313,85 @@ if (args.status) {
 // exists for programs.
 if (args.home) {
   warnOnStrangerOwner();
-  const ignore = loadIgnoreOrExit(root);
   const unattributed = [];
-  const found = sessionsForHome(args.home, { onUnattributed: (source, path) => unattributed.push({ source, path }) });
+  let found = [];
   const sessions = [];
-  const dirs = new Map(); // one capture pass per (format, directory)
-  for (const s of found) dirs.set(`${s.source}\0${dirname(s.path)}`, { format: s.source, dir: dirname(s.path) });
-  let appended = 0;
-  const homePass = withCaptureLock(() => {
-    let n = 0;
-    for (const { format, dir } of dirs.values()) {
-      n += captureSessions(store, { owner, roots: [dir], format, ignore }).appended;
+  const outcome = { appended: 0, skipped: false, held: 0, incomplete: 0, failed: 0, ignored: 0 };
+  const issues = [];
+  let error;
+  try {
+    // Unlike background passes, --home always answers JSON, including errors.
+    // Do not exit from inside the lock callback: its finally owns release.
+    const ignore = loadIgnore(root);
+    found = sessionsForHome(args.home, {
+      ignore,
+      ...(args["current-roots"] ? { fallback: "current-env" } : {}),
+      onIgnored: () => outcome.ignored++,
+      onUnattributed: (source, path) => unattributed.push({ source, path }),
+    });
+    const formats = new Map(); // exact files, not their shared directories
+    for (const s of found) {
+      if (!formats.has(s.source)) formats.set(s.source, []);
+      formats.get(s.source).push(s);
     }
-    if (!args["no-index"]) { // same as pass(): an earlier append-only pass may have left unindexed turns
-      const index = new RecordIndex(store);
-      try {
-        index.update();
-      } finally {
-        index.close();
+    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.
+    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));
+      if (!turns.length) continue; // ignored by rule, nothing capturable yet, or all hidden
+      sessions.push({
+        thread: s.thread,
+        source: s.source,
+        sessionId: s.sessionId,
+        path: s.path,
+        cwd: s.cwd,
+        stream,
+        turns: turns.length,
+        firstTurnId: turns[0].id,
+        lastTurnId: turns[turns.length - 1].id,
+        lastTs: turns[turns.length - 1].ts,
+      });
     }
-    return { appended: n };
-  });
-  appended = homePass.appended;
-  // A tombstoned turn is hidden everywhere; a boundary naming one would be
-  // refused by recall, so boundaries come from the visible turns only.
-  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));
-    if (!turns.length) continue; // ignored by rule, nothing capturable yet, or all hidden
-    sessions.push({
-      thread: s.thread,
-      source: s.source,
-      sessionId: s.sessionId,
-      path: s.path,
-      cwd: s.cwd,
-      stream,
-      turns: turns.length,
-      firstTurnId: turns[0].id,
-      lastTurnId: turns[turns.length - 1].id,
-      lastTs: turns[turns.length - 1].ts,
-    });
+  } catch (err) {
+    error = err.message || String(err);
+    console.error(`capture pass failed: ${error}`);
+    outcome.failed++;
+    // captureSessions can throw after appending part of a directory. Do not
+    // claim zero (or a complete count) for a partially performed failed pass.
+    outcome.appended = null;
+    process.exitCode = 1;
   }
-  console.log(JSON.stringify({ home: args.home, owner, appended, sessions, ...(unattributed.length ? { unattributed } : {}) }, null, 2));
-  process.exit(process.exitCode ?? 0); // nonzero when the lock release had to be reported
-}
+  if (process.exitCode && !outcome.failed) {
+    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";
+  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));
+  // Let stdout drain naturally, including large session-boundary receipts.
+} else {
 
 warnOnStrangerOwner();
 try {
@@ -383,3 +429,5 @@ if (args.watch) {
   }
   setInterval(schedule, 15 * 60 * 1000); // reconcile even if events were missed
 }
+
+}

package/packages/record/bin/recall.mjs

@@ -43,12 +43,13 @@ const store = new RecordStore(root, {});
 let index;
 const getIndex = () => (index ??= new RecordIndex(store));
 
+async function main() {
 try {
   if (args.reindex) {
     const index = getIndex();
     index.rebuild();
     console.log(JSON.stringify(index.counts()));
-    process.exit(0);
+    return;
   }
 
   if (args.show) {
@@ -58,21 +59,21 @@ try {
     const turn = resolveTurn(store, index, args.show, byId);
     if (!turn) {
       console.error(`no turn ${args.show}`);
-      process.exit(1);
+      process.exitCode = 1; return;
     }
     // Tombstoned turns are hidden from tool output, id lookup included.
     if (store.hiddenIds(byId).has(args.show)) {
       console.error(`turn ${args.show} is tombstoned`);
-      process.exit(1);
+      process.exitCode = 1; return;
     }
     console.log(JSON.stringify(turn, null, 2));
-    process.exit(0);
+    return;
   }
 
   const query = args._.join(" ").trim();
   if (!query && !args.thread) {
     console.error("usage: recall [--kind k] [--thread t] [--from f] [--role r] [--limit n] <query>");
-    process.exit(2);
+    process.exitCode = 2; return;
   }
 
   // Thread turns straight from the journal, in capture SEQUENCE: the order a
@@ -100,12 +101,12 @@ try {
     let end = turns.length;
     if (args.after) {
       const i = ids.indexOf(args.after);
-      if (i < 0) { console.error(`--after: no turn ${args.after} in thread ${args.thread}`); process.exit(1); }
+      if (i < 0) { console.error(`--after: no turn ${args.after} in thread ${args.thread}`); process.exitCode = 1; return; }
       start = i + 1;
     }
     if (args.until) {
       const i = ids.indexOf(args.until);
-      if (i < 0) { console.error(`--until: no turn ${args.until} in thread ${args.thread}`); process.exit(1); }
+      if (i < 0) { console.error(`--until: no turn ${args.until} in thread ${args.thread}`); process.exitCode = 1; return; }
       end = i + 1;
     }
     const cap = args.limit ? Number(args.limit) : Infinity;
@@ -123,7 +124,7 @@ try {
       return full;
     });
     console.log(JSON.stringify({ thread: args.thread, total: turns.length, from: start, to: stop, remaining: end - stop, turns: out }, null, 2));
-    process.exit(0);
+    return;
   }
 
   const index = getIndex();
@@ -150,15 +151,15 @@ try {
 
   if (rows.length === 0 && args.json) {
     console.log("[]");
-    process.exit(0);
+    return;
   }
   if (rows.length === 0) {
     console.error("no matches");
-    process.exit(1);
+    process.exitCode = 1; return;
   }
   if (args.json) {
     console.log(JSON.stringify(rows, null, 2));
-    process.exit(0);
+    return;
   }
   for (const r of rows) {
     const where = r.loc ? ` @${r.loc}` : "";
@@ -170,3 +171,8 @@ try {
 } finally {
   index?.close();
 }
+
+}
+// Natural process termination drains piped stdout; process.exit after a JSON
+// write truncates large recall windows even though it reports exit status 0.
+await main();

package/packages/record/bin/record-native-start.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The environment/argv stays in this process, never in the custody receipt.
+import { recordNativeStart } from "../lib/native-history.mjs";
+try {
+  const [home, id, runtime, args] = process.argv.slice(2);
+  recordNativeStart(home, id, runtime, JSON.parse(args));
+} catch {
+  // Native paths can contain user-chosen data; never echo argv or env on errors.
+  console.error("native record location receipt failed; launch refused and pending custody retained");
+  process.exitCode = 1;
+}

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

@@ -20,12 +20,14 @@
 // ignore.mjs) are skipped before being opened: no turn, no offset entry —
 // un-ignoring a file later makes the next pass capture it normally.
 
-import { closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
+import { isUtf8 } from "node:buffer";
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 import { finishTurn } from "./canonical.mjs";
 import { jsonlLines, SESSION_FORMATS } from "./formats.mjs";
 import { loadIgnore } from "./ignore.mjs";
+import { assertIdentity, digest, identity, readRange, verifySnapshot } from "./session-snapshot.mjs";
 
 export const SESSION_STREAM_SOURCE = "cc";
 
@@ -49,7 +51,7 @@ export function scanTranscript(bytes) {
     if (text === null) continue;
     try {
       const d = JSON.parse(text);
-      if (typeof d.timestamp === "string") ts = d.timestamp;
+      if (typeof d?.timestamp === "string") ts = d.timestamp;
     } catch {
       /* verbatim content; nothing to extract */
     }
@@ -83,8 +85,11 @@ function offsetsPath(store) {
 function loadOffsets(store) {
   try {
     return JSON.parse(readFileSync(offsetsPath(store), "utf8"));
-  } catch {
-    return {};
+  } catch (err) {
+    // This cache is derived, so malformed JSON can be rebuilt. An I/O
+    // failure is different: never hide an unreadable cache as missing.
+    if (err.code === "ENOENT" || err instanceof SyntaxError) return {};
+    throw err;
   }
 }
 
@@ -102,7 +107,7 @@ function readFrom(path, start, size) {
     let done = 0;
     while (done < buf.length) {
       const n = readSync(fd, buf, done, buf.length - done, start + done);
-      if (n === 0) break;
+      if (n === 0) throw new Error(`short read of session/journal source: ${path}`);
       done += n;
     }
     return buf.subarray(0, done);
@@ -119,8 +124,9 @@ function lastJournalLine(store, streamId) {
   let size;
   try {
     size = statSync(path).size;
-  } catch {
-    return 0;
+  } catch (err) {
+    if (err.code === "ENOENT") return 0;
+    throw err;
   }
   let window = 64 * 1024;
   while (true) {
@@ -152,12 +158,12 @@ function lastJournalLine(store, streamId) {
 // Honest limit: an in-place REWRITE of already-captured lines is not
 // detected (only growth is; a shrink triggers a rescan via the size
 // check in the caller). Transcript writers are append-only in practice.
-function offsetFromJournal(store, streamId, sourcePath) {
+function offsetFromJournal(store, streamId, sourcePath, final, sourceBytes) {
   const turns = store.readStream(streamId);
   if (turns.length === 0) return { bytes: 0, line: 0, lastTs: "" };
   const last = turns[turns.length - 1];
   const lastLine = last.provenance?.origin?.line ?? 0;
-  const bytes = readFileSync(sourcePath);
+  const bytes = sourceBytes ?? readFileSync(sourcePath);
   let line = 0;
   let offset = 0;
   while (line < lastLine && offset < bytes.length) {
@@ -166,6 +172,7 @@ function offsetFromJournal(store, streamId, sourcePath) {
     line++;
     offset = nl + 1;
   }
+  if (final && line < lastLine) throw new Error(`session source is shorter than its captured journal: ${sourcePath}`);
   return { bytes: offset, line, lastTs: last.ts ?? "" };
 }
 
@@ -173,7 +180,14 @@ function offsetFromJournal(store, streamId, sourcePath) {
 // of every session file under `roots`. Unstamped leading lines are held
 // until the file shows its first timestamp (then they carry it forward),
 // so every turn is stamped and ts stays a pure function of the source.
-export function captureSessions(store, { owner, roots, format = "cc", ignore = null }) {
+// `files` accepts discovery entries (including their attribution snapshot) or
+// explicit paths for callers not making home-attribution claims. It pins a set,
+// rather than rescanning directories
+// and silently losing disappeared sources (or sweeping in other homes).
+// `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.
+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}`);
   const ign = ignore ?? loadIgnore(store.root);
@@ -183,21 +197,35 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
   let unchanged = 0;
   let held = 0;
   let ignored = 0;
+  let incomplete = 0;
+  const issues = []; // source metadata only, never native record contents
   const streams = new Set();
 
-  for (const path of fmt.listFiles(roots)) {
+  for (const file of files ?? fmt.listFiles(roots)) {
+    const path = typeof file === "string" ? file : file.path;
+    const expected = typeof file === "string" ? null : file.snapshot;
     sessions++;
     const sessionId = fmt.sessionId(path);
-    if (ign.ignores(path, [basename(path), sessionId])) {
+    if (ign.ignores(path, [basename(path), sessionId, ...(fmt.ignoreKeys?.(path) ?? [])])) {
       ignored++;
       continue; // never opened: nothing stored, nothing remembered
     }
-    let stat;
+    const fd = openSync(path, "r");
     try {
-      stat = statSync(path);
-    } catch {
-      continue; // vanished between listing and stat; next pass catches it
+    const stat = fstatSync(fd);
+    const snapshot = identity(stat);
+    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 ? readRange(fd, 0, stat.size, path) : 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 (sourceBytes) verifySnapshot(fd, path, snapshot);
+    };
+    verifySource();
     const streamId = `${owner}~${fmt.source}.${sessionId}`;
     // Keyed by stream, not by source path: the same source captured under
     // two owners must not share offset state (owner is part of the stream).
@@ -210,31 +238,44 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     // saved offsets for appends that landed in an unlinked inode (skipping
     // would lose lines — this happened during the live migration). The
     // journal is the truth; before appending anything, any disagreement
-    // rebuilds the offset from it (checked only when the source grew:
-    // an unchanged file appends nothing, so its cache cannot mislead).
-    if (state && stat.size > state.bytes && state.line !== lastJournalLine(store, streamId)) {
+    // rebuilds the offset from it. Background passes check on growth;
+    // final passes also verify unchanged files before confirming capture.
+    if (state && (final || stat.size > state.bytes) && state.line !== lastJournalLine(store, streamId)) {
       state = null;
     }
-    if (!state) state = offsetFromJournal(store, streamId, path);
+    if (!state) state = offsetFromJournal(store, streamId, path, final, sourceBytes);
     if (stat.size <= state.bytes) {
       unchanged++;
       offsets[offKey] = state;
+      verifySource();
       continue;
     }
 
-    const chunk = readFrom(path, state.bytes, stat.size);
+    const chunk = sourceBytes ? sourceBytes.subarray(state.bytes) : readRange(fd, state.bytes, stat.size, path);
     // Phase 1: collect the COMPLETE lines of the chunk with their stamps.
     const lines = [];
     let scanned = 0;
-    for (const { text } of jsonlLines(chunk)) {
-      if (text === null) break; // over-string-limit line: retry later
-      const lineBytes = Buffer.byteLength(text, "utf8") + 1;
-      if (scanned + lineBytes > chunk.length) break; // no trailing newline yet
+    let reason;
+    while (scanned < chunk.length) {
+      const nl = chunk.indexOf(10, scanned);
+      if (nl === -1) { reason = "torn-tail"; break; }
+      const bytes = chunk.subarray(scanned, nl);
+      // Decoding replacement characters would change both the verbatim line
+      // and its byte offset, possibly treating a later fragment as a record.
+      if (!isUtf8(bytes)) { reason = "invalid-utf8"; break; }
+      let text;
+      try { text = bytes.toString("utf8"); }
+      catch (err) {
+        if (err.code !== "ERR_STRING_TOO_LONG") throw err;
+        reason = "oversized-line";
+        break;
+      }
+      const lineBytes = nl - scanned + 1;
       let ts = "";
       if (text.trim() !== "") {
         try {
           const d = JSON.parse(text);
-          if (typeof d.timestamp === "string") ts = d.timestamp;
+          if (typeof d?.timestamp === "string") ts = d.timestamp;
         } catch {
           /* unparseable native line: captured verbatim below */
         }
@@ -242,6 +283,10 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
       lines.push({ text, ts, bytes: lineBytes });
       scanned += lineBytes;
     }
+    if (reason) {
+      incomplete++;
+      issues.push({ source: fmt.source, path, reason, offset: state.bytes + scanned });
+    }
     // Phase 2: every turn needs a stamp. Leading lines before the file's
     // first stamp carry it backward (deterministic: the file's first
     // stamp is invariant however capture is scheduled); if the file has
@@ -250,11 +295,16 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     if (!lastTs) {
       const first = lines.find((l) => l.ts);
       if (!first) {
-        if (lines.length > 0) held++;
+        if (lines.length > 0) {
+          held++;
+          issues.push({ source: fmt.source, path, reason: "unstamped", offset: state.bytes });
+        }
+        verifySource();
         continue; // do not advance; retry when a stamp exists
       }
       lastTs = first.ts;
     }
+    verifySource(); // parsing/recovery may take time; still no journal write yet
     // Turns flush to the journal in bounded batches, so memory stays flat
     // however large the backlog (a first capture of a huge transcript is
     // one file's worth of NEW lines). A crash between flushes cannot
@@ -295,6 +345,8 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     // re-appends duplicate turn lines — logically deduped by id, but
     // wasted append-only bytes).
     if (grew) saveOffsets(store, offsets);
+    verifySource();
+    } finally { closeSync(fd); }
   }
   saveOffsets(store, offsets);
   return {
@@ -303,6 +355,9 @@ export function captureSessions(store, { owner, roots, format = "cc", ignore = n
     unchanged,
     held,
     ignored,
+    incomplete,
+    complete: held === 0 && incomplete === 0,
+    issues,
     streams: streams.size,
     stream: `${owner}~${fmt.source}.*`,
   };