pi-daddy 0.28.0 → 0.32.0

package/src/governance/ledger.ts

@@ -0,0 +1,419 @@
+/**
+ * Append-only grant ledger.
+ *
+ * Exists because pi-fabric's persisted execution trace records `args: {}` — it captures *that* a child
+ * ran, not *what it was authorised to do* (docs/probes/pi-fabric-eval probe 5). Without this record
+ * you cannot answer "what was this sub-agent permitted to do?" after the fact, which is the whole
+ * point of a governance layer.
+ *
+ * `denied` is the field that earns the file: an agent repeatedly requesting capabilities it does not
+ * hold is an escalation attempt, and it is invisible without a record.
+ *
+ * PRIVACY: capability ids, counts, and identifiers only. Never prompts, tool arguments, or results.
+ *
+ * ADR-0018 makes the boundary explicit rather than leaving it to be inferred, because a record now carries
+ * something about the child's instructions. **`definitionDigest` is an identifier**: a SHA-256 of an
+ * operator-authored file already committed to a repository, which names a version without reproducing it.
+ * **The task is not recorded, anywhere, ever** — it is assembled by the model from the parent's context and
+ * can carry anything the parent could see, so a ledger holding it would be a secrets sink. That half of
+ * "what was this child told to do?" is out of the ledger by decision, not by omission.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { Capability, ResolveResult } from "../kernel/resolve.ts";
+import type { ExecutorKind } from "../kernel/delegate-types.ts";
+import type { DefinitionDigest } from "../kernel/definitions.ts";
+import { DELEGATE_SUBJECT } from "../kernel/approval.ts";
+import type { ApprovalScope, ApprovalSource } from "../kernel/approval.ts";
+import type { PromptOutcomeKind } from "./approval-prompt.ts";
+import type { CorrelationMetadata } from "../kernel/correlation.ts";
+import type { StructuredRefusal } from "../kernel/refusals.ts";
+// Type-only, so the cycle with ./ledger-events.ts is erased at runtime.
+import type { RuntimeLedgerEvent } from "./ledger-events.ts";
+import { assertExecutionId } from "../kernel/execution-id.ts";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
+
+export const LEDGER_VERSION = 3 as const;
+export const LEDGER_EVENT_KINDS = ["capability_decision", "workspace_lease", "child_lifecycle"] as const;
+export type LedgerEventKind = (typeof LEDGER_EVENT_KINDS)[number];
+export const LEDGER_GATE_OUTCOMES = ["declined", "dismissed", "no-ui", "error"] as const;
+export type LedgerGateOutcome = (typeof LEDGER_GATE_OUTCOMES)[number];
+
+export interface LedgerEventBase {
+  /** Optional only on the legacy-compatible `GrantRecord` public type; every v3 event builder writes it. */
+  ledgerVersion?: typeof LEDGER_VERSION;
+  event?: LedgerEventKind;
+  ts: string;
+  /** Unique execution occurrence. Optional only for legacy, unversioned GrantRecord values. */
+  executionId?: string;
+  /** Explicit execution parent; null means the delegating session is not itself a governed child. */
+  parentExecutionId?: string | null;
+  childId?: string;
+  correlation?: CorrelationMetadata;
+}
+
+export interface GrantRecord extends LedgerEventBase {
+  /**
+   * Present only when a trusted `taskDigest` was supplied — that is what makes a line v3. `buildRecord`
+   * does NOT always emit it, and the comment here used to say it did while the emission site 200 lines
+   * down said the opposite. Two comments asserting contradictory facts about one field is R-28's shape.
+   */
+  event?: "capability_decision";
+  parentId: string;
+  childId: string;
+  depth: number;
+  agentType?: string;
+  requested: Capability[];
+  parentGrant: Capability[];
+  effective: Capability[];
+  denied: Capability[];
+  clipped: Capability[];
+  gatedBlocked: Capability[];
+  /** True when the spawn was refused outright rather than narrowed. */
+  blocked: boolean;
+  /** Present when the spawn was refused, or when resolution failed. */
+  reason?: string;
+  /**
+   * Gated capabilities satisfied for this spawn.
+   *
+   * The ledger used to have ONE flavour of no. It now has three, and they call for different responses:
+   *  - `denied` non-empty            -> an agent asked for more than it holds. ESCALATION ATTEMPT.
+   *  - `humanDenied`                 -> a person was asked and said no. WORKING AS DESIGNED.
+   *  - `gatedBlocked` with no source -> nobody was there to ask. A background run hit a gate; the fix is
+   *                                     an operator pre-approving it, not an incident.
+   */
+  approved?: Capability[];
+  approvalSource?: ApprovalSource;
+  /**
+   * WHERE each approved capability's yes came from — one entry per capability (R-46).
+   *
+   * `approvalSource` above is a single scalar and was written for a set: gate `tool:bash` and `tool:write`,
+   * let a persisted entry cover `bash` while a human clicks *Allow once* for `write`, and the record read
+   * `approved: ["tool:bash","tool:write"], approvalSource: "prompt"` — **asserting a human was asked about
+   * `tool:bash`, which they were not.** The ledger's whole job is answering "did a human authorise this?",
+   * so over-claiming in that direction is the worst available failure.
+   *
+   * The scalar is kept and is now written **only when every approved capability shares one source**, so a
+   * reader of old and new lines alike can trust it; when sources differ it is omitted and this map carries
+   * the truth. Two fields, one of which is a safe summary of the other — not two competing answers.
+   */
+  approvalSources?: Record<Capability, ApprovalSource>;
+  /**
+   * How far each prompted capability's yes reaches (F5). Same shape and same reason as `approvalSources`:
+   * `approvalScope` below is a **derived summary**, emitted only when every prompted capability shares one
+   * scope. This field decides propagation — `inheritApprovals` drops `once` — so a scalar that described
+   * one capability while claiming to describe the set was not merely a reporting defect.
+   */
+  approvalScopes?: Record<Capability, ApprovalScope>;
+  /** Persisted approval expiry, by capability. Session-scoped approvals have no wall-clock expiry. */
+  approvalExpiresAt?: Record<Capability, string>;
+  /** Count bounds where one exists. A consumed `once` approval records `{max:1, remaining:0}`. */
+  approvalUses?: Record<Capability, { max: number; remaining: number }>;
+  /** Present only when the source was a live prompt, and only when one scope covers the whole set. */
+  approvalScope?: ApprovalScope;
+  /** A human was asked and declined. Distinct from `denied`, which is an escalation attempt. */
+  humanDenied?: true;
+  /**
+   * WHY a gate went unsatisfied, when the answer was not a yes.
+   *
+   * `PromptOutcomeKind` has five members and this record kept exactly one of them (`humanDenied`, from
+   * `declined`). So `no-ui`, `dismissed` (a timeout or an abort) and `error` produced **identical** records
+   * — `gatedBlocked` non-empty, no `approvalSource`, `blocked: true` — and the only thing separating them
+   * was free-text `reason`, written for a human at the call site. Given a failed run, *"was there an
+   * operator who timed out, or was there nobody to ask?"* was not answerable from any field, and the fix
+   * for each is different: one is a queue or a longer `PI_DADDY_APPROVAL_TIMEOUT`, the other is an
+   * operator pre-approving.
+   *
+   * The discriminant was already computed and thrown away. ADR-0026 leans on this vocabulary being able to
+   * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
+   *
+   * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
+   * a task could carry. The prompt has five outcomes, but `granted` is deliberately omitted from the
+   * four-member ledger enum because the approval source/scope fields already record a yes.
+   */
+  gateOutcome?: LedgerGateOutcome;
+  /**
+   * WHICH operator-authored instructions this child was given (ADR-0018).
+   *
+   * Identifies, never reproduces: matching digests prove two children ran the same text, and a digest that
+   * no longer matches the file proves the definition changed since. **It says nothing about whether those
+   * instructions were correct or whether the child obeyed them** — it identifies text, it does not evaluate
+   * it. Absent for a `tools:`-style delegation, which has no definition.
+   */
+  definitionDigest?: DefinitionDigest;
+  /**
+   * WHERE this child ran — ADR-0031.
+   *
+   * **Required rather than optional**, which is unusual in this record and deliberate. Before ADR-0031 the
+   * executor was a variable an operator set, so "which one ran?" was answerable from configuration after the
+   * fact. It is now decided by a **runtime probe** at session start, so nothing outside the record preserves
+   * the answer — and the two paths do not produce the same argv, because the herdr plan withholds `--print`
+   * (`delegationContext.interactive`). A trail that cannot say where a child ran cannot be read back
+   * reliably, and reading it back is the only reason it exists.
+   *
+   * Written on refusals too, including the tripwire's: the honest value there is the executor the session
+   * *would* have used, because a refused spawn has no executor of its own.
+   */
+  executor: ExecutorKind;
+  /**
+   * The child whose OUTPUT composed this child's task — ADR-0033.
+   *
+   * **Optional, unlike `executor`, and the asymmetry is deliberate.** A non-chained spawn has no prior author, and
+   * an empty string would assert one. Present only on chain steps after the first.
+   *
+   * Why it is recorded at all: a chain makes step N's task the output of a governed child, and ADR-0033's chosen
+   * handoff is *framing* rather than enforcement. So "who wrote this instruction?" is exactly the question that
+   * decision makes worth asking, and it is unanswerable from any other field — `agentType` names the definition,
+   * `definitionDigest` names its instructions, and neither says where the TASK came from.
+   */
+  taskFrom?: string;
+  /** Unique occurrence whose output composed this task; taskFrom remains the readable logical position. */
+  taskFromExecutionId?: string;
+  /** Trusted SHA-256 of the exact task; task text remains forbidden (ADR-0034). */
+  taskDigest?: string;
+  /** Stable machine-readable refusal accompanying `reason`. */
+  refusal?: StructuredRefusal;
+}
+
+export interface LedgerOptions {
+  /** Path to the JSONL file. Parent directories are created on demand. */
+  path: string;
+  /**
+   * When true, a ledger write failure throws instead of being swallowed.
+   *
+   * Default is `true` and that is deliberate: for a security control, an unrecorded grant should fail
+   * closed. Set false only where the ledger is advisory.
+   */
+  strict?: boolean;
+  /**
+   * Called when a NON-strict append failed. Required in spirit rather than in types: a caller that opts
+   * out of failing closed still has to say something, or the ledger silently develops holes.
+   */
+  onFailure?: (error: unknown) => void;
+}
+
+export function buildRecord(args: {
+  /** Required whenever taskDigest makes this an explicit v3 event. */
+  executionId?: string;
+  /** Required (including explicit null) whenever taskDigest makes this an explicit v3 event. */
+  parentExecutionId?: string | null;
+  parentId: string;
+  childId: string;
+  depth: number;
+  agentType?: string;
+  requested: Capability[];
+  parentGrant: Capability[];
+  result: ResolveResult;
+  blocked: boolean;
+  reason?: string;
+  approved?: Capability[];
+  approvalSources?: Record<Capability, ApprovalSource>;
+  approvalScopes?: Record<Capability, ApprovalScope>;
+  approvalExpiresAt?: Record<Capability, string>;
+  approvalUses?: Record<Capability, { max: number; remaining: number }>;
+  humanDenied?: boolean;
+  gateOutcome?: PromptOutcomeKind;
+  definitionDigest?: DefinitionDigest;
+  /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
+  executor: ExecutorKind;
+  /** The logical child whose output composed this task (ADR-0033). */
+  taskFrom?: string;
+  /** The unique occurrence whose output composed this task. */
+  taskFromExecutionId?: string;
+  taskDigest?: string;
+  correlation?: CorrelationMetadata;
+  refusal?: StructuredRefusal;
+  now: Date;
+}): GrantRecord {
+  if (args.taskDigest !== undefined) {
+    if (!/^[a-f0-9]{64}$/i.test(args.taskDigest)) throw new TypeError("taskDigest must be a SHA-256 hex digest");
+    assertExecutionId(args.executionId);
+    if (args.parentExecutionId !== null) assertExecutionId(args.parentExecutionId, "parentExecutionId");
+    if (args.parentExecutionId === args.executionId) throw new TypeError("an execution cannot be its own parent");
+    if (args.taskFromExecutionId !== undefined) assertExecutionId(args.taskFromExecutionId, "taskFromExecutionId");
+  }
+  if (args.definitionDigest && !/^[a-f0-9]{64}$/i.test(args.definitionDigest.sha256)) {
+    throw new TypeError("definitionDigest.sha256 must be a SHA-256 hex digest");
+  }
+  // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
+  // than accepting it, so a call site cannot supply one that disagrees with the map beside it.
+  const sources = args.approvalSources ?? {};
+  const distinct = [...new Set(Object.values(sources))];
+  const scopes = args.approvalScopes ?? {};
+  const distinctScopes = [...new Set(Object.values(scopes))];
+  const record: GrantRecord = {
+    // A trusted task digest is what distinguishes a v3 capability event from the legacy construction API.
+    // Production delegation always supplies it; old TypeScript callers remain able to append legacy lines.
+    ...(args.taskDigest !== undefined
+      ? {
+          ledgerVersion: LEDGER_VERSION,
+          event: "capability_decision" as const,
+          executionId: args.executionId,
+          parentExecutionId: args.parentExecutionId,
+        }
+      : {}),
+    ts: args.now.toISOString(),
+    parentId: args.parentId,
+    childId: args.childId,
+    depth: args.depth,
+    agentType: args.agentType,
+    executor: args.executor,
+    ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
+    ...(args.taskFromExecutionId ? { taskFromExecutionId: args.taskFromExecutionId } : {}),
+    ...(args.taskDigest !== undefined ? { taskDigest: args.taskDigest } : {}),
+    ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+    ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
+    requested: args.requested,
+    parentGrant: args.parentGrant,
+    effective: args.result.effective,
+    denied: args.result.denied,
+    clipped: args.result.clipped,
+    gatedBlocked: args.result.gatedBlocked,
+    blocked: args.blocked,
+    reason: args.reason,
+    ...(args.approved && args.approved.length > 0 ? { approved: args.approved } : {}),
+    ...(distinct.length === 1 ? { approvalSource: distinct[0] } : {}),
+    ...(Object.keys(sources).length > 0 ? { approvalSources: sources } : {}),
+    ...(distinctScopes.length === 1 ? { approvalScope: distinctScopes[0] } : {}),
+    ...(Object.keys(scopes).length > 0 ? { approvalScopes: scopes } : {}),
+    ...(args.approvalExpiresAt && Object.keys(args.approvalExpiresAt).length > 0
+      ? { approvalExpiresAt: args.approvalExpiresAt }
+      : {}),
+    ...(args.approvalUses && Object.keys(args.approvalUses).length > 0 ? { approvalUses: args.approvalUses } : {}),
+    ...(args.humanDenied ? { humanDenied: true } : {}),
+    // Written whenever a gate was reached and not satisfied by a yes. `granted` is omitted deliberately —
+    // an approved spawn already says so through `approvalSources`, and a field that appears on every record
+    // stops being a signal.
+    ...(args.gateOutcome && args.gateOutcome !== "granted" ? { gateOutcome: args.gateOutcome } : {}),
+    ...(args.definitionDigest ? { definitionDigest: args.definitionDigest } : {}),
+  };
+  if (args.taskDigest !== undefined) assertLedgerV3Wire(record);
+  return record;
+}
+
+// R-49: the lock moved to `src/governance/file-lock.ts` so the approvals store could use the SAME one rather than
+// grow a second copy. Re-exported because `./ledger` is a published subpath and these were part of it.
+export { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from "./file-lock.ts";
+
+// The reading half, split out under the file-size guard and re-exported so `./ledger` is unchanged for
+// anyone importing it. See `ledger-report.ts` for why the seam is where it is.
+export { verifyLedger, type LedgerReport } from "./ledger-report.ts";
+
+/**
+ * Serialise appends across processes.
+ *
+ * **Why the ledger needs it.** For most of this package's life cardinality was bounded to one by `delegate`
+ * being blocking, so there was never a second writer. Fan-out removes that: `ENV_LEDGER` propagates to
+ * children, so a subtree can have many processes appending to one file.
+ *
+ * A ledger write that cannot take the lock **fails the delegation closed** — see `appendRecord`'s `strict`
+ * — because a child running with granted capabilities and no audit line is what the ledger exists to
+ * prevent. That is the opposite of what the approvals store does with the same lock, and deliberately so.
+ */
+/** The envelope kind for a governance event. Every LedgerEventKind maps; an unknown event shape is a `fact`. */
+export function recordKindForEvent(event: { event?: string }): RecordKind {
+  switch (event.event) {
+    case "capability_decision":
+      return "capability";
+    case "child_lifecycle":
+      return "lifecycle";
+    case "workspace_lease":
+      return "lease";
+    case "check_receipt": // retired kind, still imported from pre-format ledgers
+      return "check";
+    case "workflow_fact": // retired kind, still imported from pre-format ledgers
+      return "fact";
+    default:
+      return "capability"; // legacy unversioned GrantRecord values are capability decisions
+  }
+}
+
+export async function appendLedgerEvent(
+  options: LedgerOptions,
+  event: RuntimeLedgerEvent | GrantRecord,
+): Promise<void> {
+  // Serialise first: a value JSON cannot represent is a caller TypeError before any filesystem effect, exactly
+  // as the pre-envelope writer behaved (a directory or lock must not appear for an event that cannot be written).
+  JSON.stringify(event);
+  try {
+    // ADR-0076 PR 3d: every event rides in the shared record envelope; the event stays the body unchanged.
+    // The envelope `at` is the writer's clock; the body keeps its own `ts`. An event with a malformed `ts` is a
+    // corrupt BODY the report names, not a damaged envelope that stops the read.
+    await appendEnvelopeRecord(options.path, recordKindForEvent(event), event);
+  } catch (error) {
+    if (options.strict ?? true) {
+      // A damaged ledger is a refusal with a stable code, not a generic write failure (operator decision).
+      if (error instanceof GovernanceRefusal) throw error;
+      throw new Error(`grant ledger write failed (failing closed): ${String(error)}`);
+    }
+    // A non-strict append is a deliberate choice not to fail closed. It is NOT a choice to be silent:
+    // a silent safe-mode is as confusing as a silent unsafe one, so the caller is always told.
+    options.onFailure?.(error);
+  }
+}
+
+export async function appendRecord(options: LedgerOptions, record: GrantRecord): Promise<void> {
+  return appendLedgerEvent(options, record);
+}
+
+/** True when this record shows an agent asking for more than it holds. */
+export function isEscalationAttempt(record: GrantRecord): boolean {
+  return record.denied.length > 0;
+}
+
+export {
+  CHILD_LIFECYCLE_STATES,
+  CHILD_PROCESS_SIGNALS,
+  WORKSPACE_ACCESSES,
+  WORKSPACE_LEASE_OUTCOMES,
+  WORKSPACE_RECOVERY_VALUES,
+  buildChildLifecycleEvent,
+  buildWorkspaceLeaseEvent,
+  type CapabilityDecisionEvent,
+  type ChildLifecycleEvent,
+  type ChildLifecycleState,
+  type ChildProcessSignal,
+  type RuntimeLedgerEvent,
+  type WorkspaceAccess,
+  type WorkspaceLeaseEvent,
+  type WorkspaceLeaseOutcome,
+  type WorkspaceRecovery,
+} from "./ledger-events.ts";
+
+import { appendRecord as appendEnvelopeRecord, type RecordKind } from "./record.ts";
+import { GovernanceRefusal } from "../kernel/refusals.ts";
+
+/**
+ * One-time import of a pre-format ledger (`.pi/grants.jsonl` written before ADR-0076 PR 3d) into a record
+ * envelope file. Each intact line becomes one record with an `imported` marker naming the source and line;
+ * the source is never modified. Import stops at the first unparsable source line and reports it, so a torn
+ * legacy tail is visible rather than silently dropped. Returns what happened; a target that already exists
+ * is left alone (`skipped: "target-exists"`).
+ */
+export async function importLegacyLedger(
+  sourcePath: string,
+  targetPath: string,
+): Promise<{ imported: number; stoppedAt: number | null; skipped: "target-exists" | "source-missing" | null }> {
+  const { existsSync } = await import("node:fs");
+  const { readFile } = await import("node:fs/promises");
+  if (existsSync(targetPath)) return { imported: 0, stoppedAt: null, skipped: "target-exists" };
+  if (!existsSync(sourcePath)) return { imported: 0, stoppedAt: null, skipped: "source-missing" };
+  const lines = (await readFile(sourcePath, "utf8")).split("\n");
+  let imported = 0;
+  for (const [index, raw] of lines.entries()) {
+    if (raw.trim().length === 0) continue;
+    let event: { event?: string; ts?: string };
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
+      event = parsed as { event?: string; ts?: string };
+    } catch {
+      return { imported, stoppedAt: index + 1, skipped: null };
+    }
+    await appendEnvelopeRecord(targetPath, recordKindForEvent(event), event, {
+      imported: { path: sourcePath, line: index + 1 },
+    });
+    imported += 1;
+  }
+  return { imported, stoppedAt: null, skipped: null };
+}

package/src/governance/native-session.ts

@@ -0,0 +1,264 @@
+import { constants } from "node:fs";
+import { open, lstat, realpath } from "node:fs/promises";
+import { isAbsolute, relative, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { parseRetentionJson } from "./retention-json.ts";
+import { ENV_NATIVE_SESSION_ROOT } from "../kernel/env-names.ts";
+export { ENV_NATIVE_SESSION_ROOT } from "../kernel/env-names.ts";
+
+export const MAX_NATIVE_SESSION_BYTES = 1024 * 1024;
+export type NativeSessionSource = "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager";
+export interface NativeSessionObservation {
+  source: NativeSessionSource | null;
+  status: "missing" | "verified" | "invalid" | "changed" | "truncated" | "unsupported";
+  sessionId: string | null;
+  sessionPath: string | null;
+  parentSessionPath: string | null;
+  branchLeafId: string | null;
+  branchState: "unknown" | "observed";
+  lastPersistedEntryId: string | null;
+  sha256: string | null;
+  reason: string | null;
+}
+export interface NativeSessionCapture {
+  observation: NativeSessionObservation;
+  bytes?: Buffer;
+  fileIdentity?: { device: string; inode: string };
+}
+/** Read-only methods of pi 0.84.2's public SessionManager; no runtime/session creation or model work. */
+export interface NativeSessionManager {
+  getSessionFile(): string | undefined;
+  getSessionId(): string;
+  getLeafId(): string | null;
+}
+export const missingNativeSession = (): NativeSessionObservation => ({
+  source: null,
+  status: "missing",
+  sessionId: null,
+  sessionPath: null,
+  parentSessionPath: null,
+  branchLeafId: null,
+  branchState: "unknown",
+  lastPersistedEntryId: null,
+  sha256: null,
+  reason: "native-session-unavailable",
+});
+const id = (x: unknown): x is string => typeof x === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(x);
+const uuid = (x: unknown): x is string =>
+  typeof x === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(x);
+const obj = (x: unknown): x is Record<string, unknown> => x !== null && typeof x === "object" && !Array.isArray(x);
+const filePath = (x: unknown): x is string =>
+  typeof x === "string" && x.length <= 4096 && isAbsolute(x) && !x.includes("\0");
+
+/** Parse the retained native v3 bytes, never load/migrate/rewrite a session via SessionManager.open(). */
+export function parseNativeSessionBytes(
+  bytes: Uint8Array,
+  input: {
+    source: NativeSessionSource;
+    path: string;
+    expectedSessionId?: string;
+    truncated?: boolean;
+    liveLeaf?: { sessionId: string; leafId: string | null };
+  },
+): NativeSessionCapture {
+  const observation = { ...missingNativeSession(), source: input.source, sessionPath: input.path };
+  const result: NativeSessionCapture = { observation };
+  const fail = (status: NativeSessionObservation["status"], reason: string) => {
+    observation.status = status;
+    observation.reason = reason;
+    observation.branchLeafId = null;
+    observation.branchState = "unknown";
+    return result;
+  };
+  if (bytes.length > MAX_NATIVE_SESSION_BYTES) return fail("truncated", "native-session-size-limit");
+  const raw = Buffer.from(bytes),
+    newline = raw.indexOf(10);
+  let header: unknown;
+  try {
+    header = parseRetentionJson(
+      new TextDecoder("utf-8", { fatal: true }).decode(raw.subarray(0, newline < 0 ? raw.length : newline)),
+      MAX_NATIVE_SESSION_BYTES,
+    );
+  } catch {
+    return fail("invalid", "native-session-header-invalid");
+  }
+  if (
+    !obj(header) ||
+    header.type !== "session" ||
+    header.version !== 3 ||
+    !uuid(header.id) ||
+    !filePath(header.cwd) ||
+    typeof header.timestamp !== "string" ||
+    !Number.isFinite(Date.parse(header.timestamp)) ||
+    (header.parentSession !== undefined && !filePath(header.parentSession))
+  )
+    return fail("invalid", "native-session-header-invalid");
+  if (input.expectedSessionId !== undefined && header.id !== input.expectedSessionId)
+    return fail("changed", "native-session-id-changed");
+  // Only validated session headers admit transcript bytes; arbitrary files are never archived here.
+  result.bytes = Buffer.from(bytes);
+  observation.sessionId = header.id;
+  observation.parentSessionPath = (header.parentSession as string | undefined) ?? null;
+  observation.sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (input.truncated || raw.at(-1) !== 10) return fail("truncated", "native-session-incomplete-bytes");
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(raw);
+  } catch {
+    return fail("invalid", "native-session-utf8-invalid");
+  }
+  const lines = text.split("\n");
+  const ids = new Set<string>();
+  if (lines.length > 10002) return fail("invalid", "native-session-entry-limit");
+  for (const line of lines.slice(1, -1)) {
+    let entry: unknown;
+    try {
+      entry = parseRetentionJson(line, MAX_NATIVE_SESSION_BYTES);
+    } catch {
+      return fail("invalid", "native-session-entry-invalid");
+    }
+    if (
+      !obj(entry) ||
+      typeof entry.type !== "string" ||
+      entry.type === "session" ||
+      !id(entry.id) ||
+      ids.has(entry.id) ||
+      !(entry.parentId === null || (id(entry.parentId) && ids.has(entry.parentId))) ||
+      typeof entry.timestamp !== "string" ||
+      !Number.isFinite(Date.parse(entry.timestamp))
+    )
+      return fail("invalid", "native-session-parent-link-invalid");
+    ids.add(entry.id);
+    observation.lastPersistedEntryId = entry.id;
+  }
+  if (input.liveLeaf) {
+    if (input.liveLeaf.sessionId !== header.id || (input.liveLeaf.leafId !== null && !ids.has(input.liveLeaf.leafId))) {
+      return fail("changed", "native-session-live-leaf-mismatch");
+    }
+    observation.branchLeafId = input.liveLeaf.leafId;
+    observation.branchState = "observed";
+  }
+  observation.status = "verified";
+  observation.reason = observation.branchState === "unknown" ? "active-branch-unknown" : null;
+  return result;
+}
+
+/** Private allowlisted files only, bounded non-following descriptor reads, no scan of session/auth dirs. */
+export async function readNativeSession(input: {
+  path: string;
+  source: NativeSessionSource;
+  expectedSessionId?: string;
+  allowedRoot?: string;
+  manager?: NativeSessionManager;
+  expectedFile?: { device: string; inode: string };
+}): Promise<NativeSessionCapture> {
+  const gap = (status: NativeSessionObservation["status"], reason: string): NativeSessionCapture => ({
+    observation: {
+      ...missingNativeSession(),
+      source: input.source,
+      status,
+      reason,
+      sessionPath: filePath(input.path) ? input.path : null,
+    },
+  });
+  const root = input.allowedRoot ?? process.env[ENV_NATIVE_SESSION_ROOT];
+  if (!filePath(input.path) || !input.path.endsWith(".jsonl") || !root || !filePath(root))
+    return gap("unsupported", "native-session-private-root-required");
+  const within = (base: string, candidate: string) => {
+    const p = relative(base, candidate);
+    return p !== "" && p !== ".." && !p.startsWith(`..${sep}`) && !isAbsolute(p);
+  };
+  if (!within(root, input.path)) return gap("unsupported", "native-session-outside-private-root");
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    const canonicalRoot = await realpath(root),
+      canonicalFile = await realpath(input.path);
+    const rootStat = await lstat(canonicalRoot);
+    if (
+      !rootStat.isDirectory() ||
+      (rootStat.mode & 0o077) !== 0 ||
+      (typeof process.getuid === "function" && rootStat.uid !== process.getuid())
+    )
+      return gap("unsupported", "native-session-root-not-private");
+    if (!within(canonicalRoot, canonicalFile) || (await lstat(input.path)).isSymbolicLink())
+      return gap("unsupported", "native-session-path-alias");
+    handle = await open(input.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = await handle.stat();
+    if (
+      !before.isFile() ||
+      before.nlink !== 1 ||
+      (typeof process.getuid === "function" && before.uid !== process.getuid())
+    ) {
+      return gap("unsupported", "native-session-not-private-regular-file");
+    }
+    const fileIdentity = { device: String(before.dev), inode: String(before.ino) };
+    if (
+      input.expectedFile &&
+      (input.expectedFile.device !== fileIdentity.device || input.expectedFile.inode !== fileIdentity.inode)
+    )
+      return gap("changed", "native-session-file-replaced");
+    const live = input.manager
+      ? {
+          sessionId: input.manager.getSessionId(),
+          leafId: input.manager.getLeafId(),
+          path: input.manager.getSessionFile(),
+        }
+      : undefined;
+    if (live && live.path !== input.path) return gap("changed", "native-session-manager-path-changed");
+    const bytes = Buffer.alloc(Math.min(before.size, MAX_NATIVE_SESSION_BYTES));
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+      if (!read.bytesRead) break;
+      offset += read.bytesRead;
+    }
+    const after = await handle.stat(),
+      location = await lstat(input.path);
+    if (
+      before.dev !== location.dev ||
+      before.ino !== location.ino ||
+      before.size !== after.size ||
+      before.mtimeMs !== after.mtimeMs ||
+      before.ctimeMs !== after.ctimeMs ||
+      location.isSymbolicLink() ||
+      after.size !== location.size
+    )
+      return gap("changed", "native-session-file-changed");
+    if (
+      live &&
+      (input.manager!.getSessionId() !== live.sessionId ||
+        input.manager!.getLeafId() !== live.leafId ||
+        input.manager!.getSessionFile() !== live.path)
+    ) {
+      return gap("changed", "native-session-live-state-changed");
+    }
+    return {
+      ...parseNativeSessionBytes(bytes.subarray(0, offset), {
+        ...input,
+        liveLeaf: live,
+        truncated: before.size > MAX_NATIVE_SESSION_BYTES || offset !== before.size,
+      }),
+      fileIdentity,
+    };
+  } catch (error) {
+    return gap(
+      (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "invalid",
+      "native-session-read-failed",
+    );
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+/** Herdr 0.8.2 protocol 20 AgentInfo.agent_session; never scrape terminal text, PID or names. */
+export function herdrSessionReference(
+  value: unknown,
+  expectedPane: string,
+): { source: "herdr-id" | "herdr-path"; value: string } | null {
+  if (!obj(value) || value.pane_id !== expectedPane || value.agent !== "pi" || !obj(value.agent_session)) return null;
+  const s = value.agent_session;
+  if (s.agent !== "pi" || typeof s.source !== "string" || s.source.length > 128) return null;
+  if (s.kind === "id" && uuid(s.value)) return { source: "herdr-id", value: s.value };
+  if (s.kind === "path" && filePath(s.value)) return { source: "herdr-path", value: s.value };
+  return null;
+}