pi-daddy 0.47.0 → 0.48.0

package/extensions/run-delegation.ts

@@ -1,3 +1,9 @@
+import {
+  claimDelegationOperation,
+  existingOperationOutcome,
+  finishDelegationOperation,
+} from "./delegation-operations.ts";
+import type { OperationClaim } from "../src/kernel/dispatch-operation.ts";
 import { reconcileDelegationCapacity, reserveDelegationCapacity } from "./session-capacity.ts";
 import type { CapacityReservation } from "../src/kernel/capacity.ts";
 import { assertDefinitionIdentity } from "./definition-describe.ts";
@@ -43,7 +49,8 @@ import {
 } from "./workspace-runtime.ts";
 
 /** What one child was asked to do. The shape both tools accept, per child. */
-interface ChildSpec {
+export interface ChildSpec {
+  operation_id?: string;
   definitionId?: string;
   task: string;
   agent?: string;
@@ -64,7 +71,7 @@ interface ChildSpec {
  * bridged the gap, which is the same "a value that was whatever happened to be in scope" shape the module
  * header lists four defects for.
  */
-interface DelegationToolContext extends ApprovalUIContext {
+export interface DelegationToolContext extends ApprovalUIContext {
   cwd: string;
   model?: { provider: string; id: string };
   modelRegistry: ModelCatalogue;
@@ -242,7 +249,7 @@ export async function planWithApprovals(
  * was refused". `delegate` converts a failure back into a throw to keep its own contract, which matters:
  * `AgentToolResult` has no `isError` field, so a returned error is silently discarded by pi.
  */
-export async function runOneDelegation(
+async function runOneDelegationImplementation(
   session: GrantsSession,
   spec: ChildSpec,
   ids: ExecutionOccurrenceIds,
@@ -265,6 +272,9 @@ export async function runOneDelegation(
    * mistake unspellable.
    */
   options: {
+    operationClaim?: OperationClaim;
+    /** Trusted observation at the actual executor boundary, not a caller/tool parameter. */
+    onExecutorEntry?: () => void;
     /** Trusted reservation made before a chain's upfront gate. */
     capacityReservation?: CapacityReservation;
     /** Exact pair selected during the chain preflight; never reselect after its approval. */
@@ -513,6 +523,8 @@ export async function runOneDelegation(
     executorEntered = true;
     return await executePlannedChild({
       capacityReservation: capacity,
+      operationClaim: options.operationClaim,
+      onExecutorEntry: options.onExecutorEntry,
       session,
       plan,
       agent: spec.agent,
@@ -534,3 +546,46 @@ export async function runOneDelegation(
     );
   }
 }
+
+/** Duplicate references never enter the executor, consume capacity, or become chain input. */
+export async function runOneDelegation(
+  ...args: Parameters<typeof runOneDelegationImplementation>
+): Promise<DelegationOutcome> {
+  const [session, spec, ids, , ctx, signal] = args;
+  const options = args[6] ?? {};
+  const claim = options.operationClaim ?? (await claimDelegationOperation(session, spec, ids, ctx, signal));
+  if (claim?.reused) {
+    options.capacityReservation?.finalize({ state: "not-started", reason: "existing operation reused" });
+    return existingOperationOutcome(claim, session.depth + 1);
+  }
+  let executorEntered = false;
+  try {
+    args[6] = {
+      ...options,
+      operationClaim: claim,
+      onExecutorEntry: () => {
+        executorEntered = true;
+        options.onExecutorEntry?.();
+      },
+    };
+    const result = await runOneDelegationImplementation(...args);
+    if (claim) {
+      try {
+        await finishDelegationOperation(claim, result);
+      } catch (error) {
+        // A post-execution observation failure must not erase the native final or settlement receipt.
+        result.control = "failed";
+        result.reason = [result.reason, `operation status update failed: ${String(error)}`].filter(Boolean).join("; ");
+        result.operation = { ...claim.operation, state: "uncertain", reused: false };
+      }
+    }
+    return result;
+  } catch (error) {
+    if (claim)
+      await claim.finish!(
+        executorEntered ? "uncertain" : "not-started",
+        executorEntered ? undefined : { cleanup: { state: "not-started" } },
+      ).catch(() => undefined);
+    throw error;
+  }
+}

package/extensions/runtime-snapshot.ts

@@ -5,6 +5,7 @@ import { openRuntimeSettlement, settlementHash } from "../src/governance/runtime
 import { reconcileDelegationCapacity } from "./session-capacity.ts";
 import { agentDir } from "../src/kernel/project-paths.ts";
 import type { GrantsSession } from "./session.ts";
+export const OPERATION_STATUS_EVENT = "pi-daddy:operation-status:v1";
 export const RUNTIME_SNAPSHOT_EVENT = "pi-daddy:runtime-snapshot:v1";
 export function registerRuntimeSnapshot(
   pi: ExtensionAPI,
@@ -15,7 +16,7 @@ export function registerRuntimeSnapshot(
   let bound: { sessionId: string; cwd: string; lifecycle: object } | undefined, problem: string | undefined;
   const generation = {};
   let bindSequence = 0;
-  const unsubscribe = pi.events?.on?.(RUNTIME_SNAPSHOT_EVENT, (input: unknown) => {
+  const unsubscribeRuntime = pi.events?.on?.(RUNTIME_SNAPSHOT_EVENT, (input: unknown) => {
     const request = input as {
       version?: number;
       requestId?: string;
@@ -91,6 +92,63 @@ export function registerRuntimeSnapshot(
       }
     })().catch(() => undefined);
   });
+  const unsubscribeOperations = pi.events?.on?.(OPERATION_STATUS_EVENT, (input: unknown) => {
+    const request = input as {
+      version?: number;
+      requestId?: string;
+      sessionId?: string;
+      cwd?: string;
+      operationId?: string;
+      reply?: (value: unknown) => void;
+    };
+    if (
+      request?.version !== 1 ||
+      typeof request.requestId !== "string" ||
+      request.requestId.length > 512 ||
+      typeof request.operationId !== "string" ||
+      typeof request.reply !== "function"
+    )
+      return;
+    if (bound && session.reloadLifecycle.runtimeSnapshotGeneration !== generation) return;
+    void (async () => {
+      const current = bound,
+        lifecycle = session.reloadLifecycle;
+      const envelope = {
+        version: 1,
+        requestId: request.requestId,
+        sessionId: current?.sessionId ?? "",
+        cwd: current?.cwd ?? "",
+        operationId: request.operationId,
+      };
+      if (
+        !current ||
+        current.lifecycle !== lifecycle ||
+        request.sessionId !== current.sessionId ||
+        request.cwd !== current.cwd ||
+        !session.ownerBound ||
+        !session.autoMode?.operations
+      ) {
+        request.reply!({ ...envelope, qualified: false, operation: null, reason: "operation owner is not ready" });
+        return;
+      }
+      try {
+        const operation = await session.autoMode.operations.read(request.operationId!);
+        if (
+          bound !== current ||
+          session.reloadLifecycle !== lifecycle ||
+          lifecycle.runtimeSnapshotGeneration !== generation
+        )
+          throw Error("operation owner changed during read");
+        request.reply!({ ...envelope, qualified: true, operation });
+      } catch (error) {
+        request.reply!({ ...envelope, qualified: false, operation: null, reason: String(error) });
+      }
+    })().catch(() => undefined);
+  });
+  const unsubscribe = () => {
+    unsubscribeRuntime?.();
+    unsubscribeOperations?.();
+  };
   return {
     async bind(ctx) {
       const sequence = ++bindSequence,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",

package/src/executors/child-final.ts

@@ -4,6 +4,7 @@ import { isDeepStrictEqual } from "node:util";
 import { join } from "node:path";
 import { readdir } from "node:fs/promises";
 import { SessionManager, type FileEntry } from "@earendil-works/pi-coding-agent";
+import type { CapturedSessionBranch } from "../governance/native-session.ts";
 import { BoundedReadCleanupError, readBoundedBytes } from "../kernel/bounded-read.ts";
 const MAX_FINAL_BYTES = 4 * 1024 * 1024,
   MAX_LINE_BYTES = 32 * 1024 * 1024,
@@ -13,6 +14,11 @@ const hash = (s: string) => createHash("sha256").update(s, "utf8").digest("hex")
 export type ChildFinal =
   | { state: "complete"; text: string; sessionId: string; messageId: string; leafId: string; sha256: string }
   | { state: "unavailable"; reason: string; diagnosticText?: string };
+const capturedSessions = new WeakMap<ChildFinal, Readonly<CapturedSessionBranch>>();
+/** Only the original in-process final carries this observation; JSON/copies do not recreate it. */
+export function capturedFinalSession(final: ChildFinal): Readonly<CapturedSessionBranch> | undefined {
+  return capturedSessions.get(final);
+}
 export class ChildFinalCapture {
   private decoder = new TextDecoder("utf-8", { fatal: true });
   private buffer = "";
@@ -171,7 +177,7 @@ export class ChildFinalCapture {
         !isDeepStrictEqual(currentUser.message, this.user)
       )
         throw Error("stream final does not match the current persisted branch and turn");
-      return {
+      const complete: ChildFinal = {
         state: "complete",
         text,
         sessionId: this.sessionId,
@@ -179,6 +185,16 @@ export class ChildFinalCapture {
         leafId: manager.getLeafId()!,
         sha256: hash(text),
       };
+      capturedSessions.set(
+        complete,
+        Object.freeze({
+          path,
+          sessionId: this.sessionId,
+          leafId: complete.leafId,
+          sha256: createHash("sha256").update(read.bytes).digest("hex"),
+        }),
+      );
+      return complete;
     } catch (error) {
       if (error instanceof BoundedReadCleanupError) {
         if (!this.onReadCleanup) throw error;

package/src/governance/auto-mode-policy.ts

@@ -1,3 +1,5 @@
+import { createDispatchOperations } from "./dispatch-operations.ts";
+import { connectDispatchOperations } from "./dispatch-operation-client.ts";
 /** Root-owned live Auto authority. Descendants receive read/admit access, never mutation access. */
 import { randomBytes, randomUUID } from "node:crypto";
 import { chmod, unlink } from "node:fs/promises";
@@ -38,6 +40,7 @@ export async function createAutoModeAuthority(initial: {
     source = initial.source,
     revision = 0,
     closed = false;
+  const operations = createDispatchOperations();
   const pending = new Map<string, PendingApproval>();
   const waiters = new Set<() => void>();
   const sockets = new Set<Socket>();
@@ -92,12 +95,14 @@ export async function createAutoModeAuthority(initial: {
     const controller = new AbortController();
     let input = "",
       handled = false,
-      untrack: (() => void) | undefined;
+      untrack: (() => void) | undefined,
+      abandonOperation: (() => void) | undefined;
     socket.on("error", () => {});
     socket.once("close", () => {
       sockets.delete(socket);
       controller.abort();
       untrack?.();
+      abandonOperation?.();
     });
     const reply = (value: unknown) => {
       if (!socket.destroyed) socket.end(JSON.stringify(value) + "\n");
@@ -129,6 +134,21 @@ export async function createAutoModeAuthority(initial: {
         } else if (request.action === "pending" && validPending(request.approval)) {
           socket.setTimeout(0);
           untrack = trackPending(request.approval);
+        } else if (request.action === "operation-claim") {
+          const value = operations.claim(request.request);
+          if (!value.reused) {
+            socket.setTimeout(0);
+            abandonOperation = () => operations.abandoned(value.operation.operationId, value.ticket!);
+            socket.write(JSON.stringify({ ok: true, value }) + "\n");
+          } else reply({ ok: true, value });
+        } else if (request.action === "operation-read") {
+          reply({ ok: true, value: operations.read(request.operationId) });
+        } else if (request.action === "operation-started") {
+          operations.started(request.operationId, request.ticket, request.cwd, request.workspaceId);
+          reply({ ok: true });
+        } else if (request.action === "operation-finish") {
+          operations.finish(request.operationId, request.ticket, request.state, request.runtime);
+          reply({ ok: true });
         } else throw new Error("Unknown Auto policy action");
       } catch (error) {
         reply({ ok: false, error: String(error) });
@@ -153,7 +173,9 @@ export async function createAutoModeAuthority(initial: {
     } catch {}
   };
   process.once("exit", exit);
+  const operationAccess = connectDispatchOperations(reference);
   return {
+    operations: operationAccess,
     reference,
     snapshot,
     read: async () => snapshot(),
@@ -175,6 +197,7 @@ export async function createAutoModeAuthority(initial: {
     close: async () => {
       if (closed) return;
       closed = true;
+      operationAccess.close();
       enabled = false;
       for (const wake of [...waiters]) wake();
       for (const socket of sockets) socket.destroy();
@@ -233,6 +256,7 @@ function request(ref: AutoModeRef, action: "read" | "admit" | "wait", signal?: A
 }
 
 export function connectAutoMode(reference: AutoModeRef): AutoModeReader {
+  const operations = connectDispatchOperations(reference);
   let closed = false;
   const active = new Set<AbortController>();
   const pending = new Set<Socket>();
@@ -252,6 +276,7 @@ export function connectAutoMode(reference: AutoModeRef): AutoModeReader {
   };
   return {
     reference,
+    operations,
     read: async () => {
       const value = (await call("read")) as AutoModeSnapshot;
       if (
@@ -290,6 +315,7 @@ export function connectAutoMode(reference: AutoModeRef): AutoModeReader {
     },
     close: async () => {
       closed = true;
+      operations.close();
       for (const controller of active) controller.abort();
       for (const socket of pending) socket.destroy();
     },

package/src/governance/dispatch-operation-client.ts

@@ -0,0 +1,96 @@
+/** A held claim connection makes caller loss uncertain; another caller never inherits execution. */
+import { createConnection, type Socket } from "node:net";
+import type { AutoModeRef } from "../kernel/auto-mode.ts";
+import type {
+  OperationAccess,
+  OperationClaim,
+  OperationReference,
+  OperationRequest,
+} from "../kernel/dispatch-operation.ts";
+
+export function connectDispatchOperations(reference: AutoModeRef): OperationAccess {
+  const sockets = new Set<Socket>();
+  let closed = false;
+  const request = (
+    action: string,
+    input: object,
+    signal?: AbortSignal,
+    hold = false,
+  ): Promise<{ value: any; socket: Socket }> =>
+    new Promise((resolve, reject) => {
+      if (closed || signal?.aborted) return reject(Error("Operation owner unavailable or request aborted"));
+      const socket = createConnection(reference.socketPath);
+      sockets.add(socket);
+      let output = "",
+        answered = false;
+      const cleanup = () => signal?.removeEventListener("abort", abort);
+      const fail = (error: Error) => {
+        cleanup();
+        socket.destroy();
+        if (!answered) {
+          answered = true;
+          reject(error);
+        }
+      };
+      const abort = () => fail(Error("Operation request aborted"));
+      signal?.addEventListener("abort", abort, { once: true });
+      socket.setEncoding("utf8");
+      socket.setTimeout(2000, () => fail(Error("Operation owner unavailable")));
+      socket.once("error", () => fail(Error("Operation owner unavailable")));
+      socket.once("connect", () => socket.write(JSON.stringify({ ...reference, action, ...input }) + "\n"));
+      socket.once("close", () => {
+        sockets.delete(socket);
+        cleanup();
+        if (!answered) fail(Error("Operation owner disconnected"));
+      });
+      socket.on("data", (chunk) => {
+        if (answered) return;
+        output += chunk;
+        if (output.length > 65536) return fail(Error("Operation response too large"));
+        const end = output.indexOf("\n");
+        if (end < 0) return;
+        try {
+          const reply = JSON.parse(output.slice(0, end));
+          if (reply.ok !== true) throw Error(reply.error ?? "Operation request failed");
+          answered = true;
+          cleanup();
+          socket.setTimeout(0);
+          if (!hold || reply.value?.reused) socket.destroy();
+          resolve({ value: reply.value, socket });
+        } catch (error) {
+          fail(error instanceof Error ? error : Error(String(error)));
+        }
+      });
+    });
+  return {
+    claim: async (input: OperationRequest, signal?: AbortSignal): Promise<OperationClaim> => {
+      const { value, socket } = await request("operation-claim", { request: input }, signal, true);
+      if (value.reused) return { operation: value.operation, reused: true };
+      const update = async (action: string, data: object) => {
+        if (socket.destroyed) throw Error("Operation claim owner disconnected; settlement is uncertain");
+        return request(action, { operationId: input.operationId, ticket: value.ticket, ...data });
+      };
+      return {
+        operation: value.operation,
+        reused: false,
+        started: async (cwd, workspaceId) => {
+          await update("operation-started", { cwd, workspaceId });
+        },
+        finish: async (state, runtime) => {
+          try {
+            await update("operation-finish", { state, runtime });
+            Object.assign(value.operation, (await request("operation-read", { operationId: input.operationId })).value);
+          } finally {
+            socket.destroy();
+          }
+        },
+      };
+    },
+    read: async (operationId: string) =>
+      (await request("operation-read", { operationId })).value as OperationReference | null,
+    close: () => {
+      closed = true;
+      for (const socket of sockets) socket.destroy();
+    },
+  };
+}

package/src/governance/dispatch-operations.ts

@@ -0,0 +1,81 @@
+/** Atomic leader election at the tree owner. No task text, execution permission or cached output. */
+import { randomBytes } from "node:crypto";
+import type { OperationReference, OperationRequest } from "../kernel/dispatch-operation.ts";
+import { validOperationId } from "../kernel/dispatch-operation.ts";
+
+export function createDispatchOperations() {
+  const records = new Map<string, { digest: string; ticket: string; value: OperationReference }>();
+  const copy = (value: OperationReference) => structuredClone(value);
+  const requireTicket = (id: string, ticket: string) => {
+    const row = records.get(id);
+    if (!row || typeof ticket !== "string" || row.ticket !== ticket) throw Error("Operation owner mismatch");
+    return row;
+  };
+  return {
+    claim(request: OperationRequest) {
+      if (
+        !request ||
+        !validOperationId(request.operationId) ||
+        typeof request.requestDigest !== "string" ||
+        !/^[a-f0-9]{64}$/.test(request.requestDigest) ||
+        typeof request.executionId !== "string" ||
+        !request.executionId.startsWith("exec:") ||
+        request.executionId.length > 128 ||
+        typeof request.cwd !== "string" ||
+        !request.cwd.startsWith("/") ||
+        request.cwd.length > 4096 ||
+        !(request.workspaceId === null || typeof request.workspaceId === "string")
+      )
+        throw Error("Invalid dispatch operation request");
+      const old = records.get(request.operationId);
+      if (old) {
+        if (old.digest !== request.requestDigest)
+          throw Error("Operation identity conflict; inspect the original request before choosing a new operation_id");
+        return { reused: true, operation: copy(old.value) };
+      }
+      // Never evict a terminal ID and accidentally permit a mutation to run twice.
+      if (records.size >= 4096) throw Error("Session operation registry is full; no dispatch was admitted");
+      const now = new Date().toISOString(),
+        ticket = randomBytes(24).toString("hex");
+      const value: OperationReference = {
+        operationId: request.operationId,
+        executionId: request.executionId,
+        cwd: request.cwd,
+        workspaceId: request.workspaceId,
+        state: "admitting",
+        startedAt: now,
+        updatedAt: now,
+      };
+      records.set(request.operationId, { digest: request.requestDigest, ticket, value });
+      return { reused: false, operation: copy(value), ticket };
+    },
+    read(id: string) {
+      if (!validOperationId(id)) throw Error("Invalid operation_id");
+      const value = records.get(id)?.value;
+      return value ? copy(value) : null;
+    },
+    started(id: string, ticket: string, cwd: string, workspaceId: string | null) {
+      const row = requireTicket(id, ticket);
+      if (row.value.state !== "admitting") throw Error("Operation is no longer admitting");
+      if (
+        typeof cwd !== "string" ||
+        !cwd.startsWith("/") ||
+        cwd.length > 4096 ||
+        !(workspaceId === null || typeof workspaceId === "string")
+      )
+        throw Error("Invalid operation workspace");
+      row.value = { ...row.value, state: "running", cwd, workspaceId, updatedAt: new Date().toISOString() };
+    },
+    finish(id: string, ticket: string, state: OperationReference["state"], runtime?: OperationReference["runtime"]) {
+      const row = requireTicket(id, ticket);
+      if (!["settled", "not-started", "uncertain"].includes(state)) throw Error("Invalid operation terminal state");
+      if (!["admitting", "running"].includes(row.value.state)) throw Error("Operation already ended");
+      row.value = { ...row.value, state, ...(runtime ? { runtime } : {}), updatedAt: new Date().toISOString() };
+    },
+    abandoned(id: string, ticket: string) {
+      const row = requireTicket(id, ticket);
+      if (["admitting", "running"].includes(row.value.state))
+        row.value = { ...row.value, state: "uncertain", updatedAt: new Date().toISOString() };
+    },
+  };
+}

package/src/governance/execution-retention.ts

@@ -8,6 +8,7 @@ import {
   type NativeSessionObservation,
   type NativeSessionManager,
   type NativeSessionCapture,
+  type CapturedSessionBranch,
 } from "./native-session.ts";
 export {
   buildExecutionRetentionManifest,
@@ -26,7 +27,7 @@ export { ENV_EXECUTION_ARCHIVE } from "../kernel/env-names.ts";
 import { isUnderPiProjectDir } from "../kernel/project-paths.ts";
 
 /** Operator-owned archive boundary; never a model-facing parameter or an authority source. */
-export const RETENTION_VERSION = "2.0";
+export const RETENTION_VERSION = "2.1";
 const LIMIT = 1024 * 1024;
 const MAX_ACTIVE = 32;
 let active = 0;
@@ -49,7 +50,7 @@ export interface RetainedContent {
   bytes: number | null;
 }
 export interface ExecutionRetentionManifest {
-  version: "2.0";
+  version: "2.0" | "2.1";
   archiveId: string;
   identity: RetentionIdentity;
   native: {
@@ -155,9 +156,10 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
   let nativeTask: Promise<void> | undefined;
   let nextNative:
     | {
-        source: "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager";
+        source: "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager" | "pi-captured-final";
         value: string;
         manager?: NativeSessionManager;
+        capturedBranch?: CapturedSessionBranch;
       }
     | undefined;
   let pinnedSessionId: string | undefined;
@@ -236,6 +238,7 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
       source: reference.source,
       value: reference.value,
       ...(reference.manager ? { manager: reference.manager } : {}),
+      ...(reference.capturedBranch ? { capturedBranch: { ...reference.capturedBranch } } : {}),
     };
     if (nativeTask) return;
     nativeTask = Promise.resolve()
@@ -258,6 +261,7 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
                   path: current.value,
                   source: current.source,
                   manager: current.manager,
+                  capturedBranch: current.capturedBranch,
                   expectedSessionId: pinnedSessionId,
                   expectedFile: pinnedFile,
                 });

package/src/governance/ledger-report.ts

@@ -289,6 +289,15 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         events += 1;
         return;
       }
+      if (
+        event.ledgerVersion === 3 &&
+        (event.event === "session_config" || event.event === "cost_gate" || event.event === "episode_outcome")
+      ) {
+        // These facts passed the current v3 schema above. They are history, not capability decisions,
+        // and must not inflate approval, executor, lifecycle or retired-event counters.
+        events += 1;
+        return;
+      }
       if (event.ledgerVersion === 3 && isRetiredLedgerEvent(event)) {
         // Written by 0.30.0 or earlier; counted, never treated as corruption (see RETIRED_LEDGER_EVENT_KINDS).
         retired += 1;

package/src/governance/native-session.ts

@@ -7,7 +7,8 @@ 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 type NativeSessionSource =
+  "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager" | "pi-captured-final";
 export interface NativeSessionObservation {
   source: NativeSessionSource | null;
   status: "missing" | "verified" | "invalid" | "changed" | "truncated" | "unsupported";
@@ -25,6 +26,13 @@ export interface NativeSessionCapture {
   bytes?: Buffer;
   fileIdentity?: { device: string; inode: string };
 }
+/** Byte-bound metadata from the executor's qualified native final, not a locator-derived branch. */
+export interface CapturedSessionBranch {
+  path: string;
+  sessionId: string;
+  leafId: string;
+  sha256: 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;
@@ -59,6 +67,7 @@ export function parseNativeSessionBytes(
     expectedSessionId?: string;
     truncated?: boolean;
     liveLeaf?: { sessionId: string; leafId: string | null };
+    capturedBranch?: CapturedSessionBranch;
   },
 ): NativeSessionCapture {
   const observation = { ...missingNativeSession(), source: input.source, sessionPath: input.path };
@@ -138,6 +147,23 @@ export function parseNativeSessionBytes(
     observation.branchLeafId = input.liveLeaf.leafId;
     observation.branchState = "observed";
   }
+  if (input.source === "pi-captured-final" && !input.capturedBranch)
+    return fail("invalid", "native-session-final-branch-missing");
+  if (input.capturedBranch) {
+    const branch = input.capturedBranch;
+    if (
+      input.source !== "pi-captured-final" ||
+      branch.path !== input.path ||
+      branch.sessionId !== header.id ||
+      branch.sha256 !== observation.sha256 ||
+      !ids.has(branch.leafId) ||
+      (input.liveLeaf && input.liveLeaf.leafId !== branch.leafId)
+    ) {
+      return fail("changed", "native-session-final-branch-mismatch");
+    }
+    observation.branchLeafId = branch.leafId;
+    observation.branchState = "observed";
+  }
   observation.status = "verified";
   observation.reason = observation.branchState === "unknown" ? "active-branch-unknown" : null;
   return result;
@@ -150,6 +176,7 @@ export async function readNativeSession(input: {
   expectedSessionId?: string;
   allowedRoot?: string;
   manager?: NativeSessionManager;
+  capturedBranch?: CapturedSessionBranch;
   expectedFile?: { device: string; inode: string };
 }): Promise<NativeSessionCapture> {
   const gap = (status: NativeSessionObservation["status"], reason: string): NativeSessionCapture => ({