pi-daddy 0.47.1 → 0.48.1

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.1",
+  "version": "0.48.1",
   "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/executors/herdr-cli.ts

@@ -97,7 +97,10 @@ export async function probeHerdr(options: { exec?: HerdrExec; timeoutMs?: number
     return await Promise.race<HerdrProbe>([
       exec(["tab", "list"]).then((reply) => {
         const parsed = parseReply(reply);
-        return parsed.error ? { ok: false, error: parsed.error } : { ok: true };
+        if (parsed.error) return { ok: false, error: parsed.error };
+        if (reply.code !== 0 || !Array.isArray(parsed.result?.tabs))
+          return { ok: false, error: "Herdr tab list failed or returned an unsupported response" };
+        return { ok: true };
       }),
       new Promise<HerdrProbe>((settle) => {
         timer = setTimeout(() => settle({ ok: false, error: `probe timed out after ${timeoutMs}ms` }), timeoutMs);

package/src/executors/herdr-qualification.ts

@@ -1,31 +1,24 @@
-/** Measured transport matrix. Reachability alone never qualifies a backend or changes execution location. */
+/** Check the live CLI contract; product release numbers are not compatibility boundaries. */
 import { defaultExec, type HerdrExec, type HerdrProbe } from "./herdr-cli.ts";
-export const QUALIFIED_HERDR_VERSION = "0.8.2";
-export const QUALIFIED_HERDR_PROTOCOL = 20;
+
 export async function qualifyHerdr(probe: HerdrProbe, exec: HerdrExec = defaultExec): Promise<HerdrProbe> {
   if (!probe.ok) return probe;
   try {
     if (process.platform !== "linux" || process.arch !== "x64") throw Error("Herdr owned execution requires Linux x64");
-    const [client, server] = await Promise.all([exec(["--version"]), exec(["status", "server"])]);
-    if (client.code !== 0 || client.stdout.trim() !== "herdr " + QUALIFIED_HERDR_VERSION)
-      throw Error("Herdr client version is not qualified");
-    const fields = Object.fromEntries(
-      server.stdout
-        .trim()
-        .split("\n")
-        .map((line) => {
-          const at = line.indexOf(":");
-          return [line.slice(0, at).trim(), line.slice(at + 1).trim()];
-        }),
-    );
+    const reply = await exec(["status", "server", "--json"]);
+    if (reply.code !== 0)
+      throw Error("Herdr live server status failed: " + (reply.stderr.trim() || reply.stdout.trim()));
+    const status = JSON.parse(reply.stdout);
+    if (!status || status.status !== "running" || status.running !== true) throw Error("Herdr server is not running");
+    // Our tab/pane CLI commands use the private protocol. Endpoint compatibility alone is insufficient.
+    if (!Number.isSafeInteger(status.protocol) || status.protocol < 1 || status.compatible !== true)
+      throw Error("Herdr client/server CLI protocol is incompatible or unavailable");
+    // Legacy servers do not advertise an endpoint generation. Respect an explicit modern incompatibility.
     if (
-      server.code !== 0 ||
-      fields.status !== "running" ||
-      fields.version !== QUALIFIED_HERDR_VERSION ||
-      fields.protocol !== String(QUALIFIED_HERDR_PROTOCOL) ||
-      fields.compatible !== "yes"
+      (status.endpoint_compatible !== undefined || status.capabilities?.endpoint_protocol_generation !== undefined) &&
+      status.endpoint_compatible !== true
     )
-      throw Error("Herdr server version/protocol is not qualified");
+      throw Error("Herdr client/server endpoint is incompatible or unavailable");
     return { ...probe, qualified: true };
   } catch (error) {
     return { ...probe, qualified: false, qualificationReason: String(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/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 => ({

package/src/governance/retention-contract.ts

@@ -31,7 +31,7 @@ export const RETENTION_SCHEMA = freeze({
   $schema: "https://json-schema.org/draft/2020-12/schema",
   $id: "https://pi-daddy.local/contracts/execution-retention/v2/manifest.schema.json",
   ...closed({
-    version: literal("2.0"),
+    version: { enum: ["2.0", "2.1"] },
     archiveId: uuid,
     identity: closed({
       executionId: string(),
@@ -54,7 +54,7 @@ export const RETENTION_SCHEMA = freeze({
       branchLeafId: nullable(string(128)),
     }),
     nativeSession: closed({
-      source: { enum: [null, "herdr-id", "herdr-path", "pi-session-file", "pi-session-manager"] },
+      source: { enum: [null, "herdr-id", "herdr-path", "pi-session-file", "pi-session-manager", "pi-captured-final"] },
       status: { enum: ["missing", "verified", "invalid", "changed", "truncated", "unsupported"] },
       sessionId: nullable(uuid),
       sessionPath: nullable(string(4096)),
@@ -101,6 +101,10 @@ export const RETENTION_SCHEMA = freeze({
     acceptance: literal("not-assessed"),
   }),
   allOf: [
+    {
+      if: { properties: { version: literal("2.0") } },
+      then: { properties: { nativeSession: { properties: { source: { not: literal("pi-captured-final") } } } } },
+    },
     {
       if: { properties: { state: literal("running") } },
       then: { properties: { outcome: literal(null) } },
@@ -162,7 +166,7 @@ export function buildExecutionRetentionManifest(value: unknown): ExecutionRetent
     }
   };
   inspect(value, 0);
-  if (!validator.Check(value)) throw new TypeError("invalid execution-retention 2.0 manifest");
+  if (!validator.Check(value)) throw new TypeError("invalid execution-retention 2.x manifest");
   const m = JSON.parse(JSON.stringify(value)) as ExecutionRetentionManifest;
   if (
     m.native.sessionId !== m.nativeSession.sessionId ||
@@ -178,7 +182,8 @@ export function buildExecutionRetentionManifest(value: unknown): ExecutionRetent
   }
   if (
     m.nativeSession.branchState === "observed" &&
-    (m.nativeSession.source !== "pi-session-manager" || m.nativeSession.status !== "verified")
+    (!["pi-session-manager", "pi-captured-final"].includes(m.nativeSession.source ?? "") ||
+      m.nativeSession.status !== "verified")
   )
     throw new TypeError("unverified active native branch");
   if (

package/src/kernel/auto-mode.ts

@@ -19,6 +19,7 @@ export interface AutoModeRef {
 }
 export interface AutoModeReader {
   readonly reference: AutoModeRef;
+  readonly operations?: import("./dispatch-operation.ts").OperationAccess;
   read(): Promise<AutoModeSnapshot>;
   /** Linearization point: only a current ON answer admits new work. No approval is banked. */
   admit(signal?: AbortSignal): Promise<boolean>;

package/src/kernel/chain.ts

@@ -152,6 +152,7 @@ export function composeStepTask(template: string, previous: string | undefined):
 
 /** One chain step as `runOneDelegation` takes it: the operator's spec with its task composed. */
 export interface ChainStep {
+  operation_id?: string;
   definitionId?: string;
   task: string;
   agent?: string;