@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/src/ai/providers/pi-native/result-builder.js

@@ -32,6 +32,24 @@ export function usageFromMessages(messages = []) {
   return usage;
 }
 
+/**
+ * Pi initializes failed assistant messages with an all-zero usage object before
+ * any provider telemetry arrives. A successful response makes those zeros
+ * measured; a failed response is measured only when real usage is non-zero.
+ * @param {Array<any>} [messages]
+ */
+export function hasMeasuredUsage(messages = []) {
+  return messages.some((message) => {
+    if (message?.role !== "assistant" || !message.usage) return false;
+    if (message.stopReason !== "error" && message.stopReason !== "aborted") return true;
+    const usage = message.usage;
+    return [usage.input, usage.output, usage.cacheRead, usage.cacheWrite, usage.totalTokens,
+      usage.cost?.input, usage.cost?.output, usage.cost?.cacheRead,
+      usage.cost?.cacheWrite, usage.cost?.total]
+      .some((value) => Number.isFinite(Number(value)) && Number(value) > 0);
+  });
+}
+
 /**
  * Add what this run's subagents spent to the run's own usage.
  *
@@ -70,7 +88,7 @@ export function withSubagentUsage(usage, delegated, estimatedCost) {
  * requests in the run: the last assistant usage is the same provider-counted
  * value Pi's compaction logic trusts, so it can decrease after compaction.
  * @param {any} assistantMessage
- * @returns {{input: number, output: number, cacheRead: number, cacheCreation: number, total: number}|null}
+ * @returns {{input: number, output: number, cacheRead: number, cacheCreation: number, total: number, costUsd: number}|null}
  */
 export function contextUsageFromAssistantMessage(assistantMessage) {
   if (assistantMessage?.role !== "assistant" || !assistantMessage.usage) return null;
@@ -83,6 +101,7 @@ export function contextUsageFromAssistantMessage(assistantMessage) {
     cacheRead: Number(assistantMessage.usage.cacheRead) || 0,
     cacheCreation: Number(assistantMessage.usage.cacheWrite) || 0,
     total,
+    costUsd: Number(assistantMessage.usage.cost?.total) || 0,
   };
 }
 
@@ -118,14 +137,14 @@ export function emitUsageCostEvents({
   externalAbort,
 }) {
   if (usage.cacheRead > 0) {
-    onEvent({ type: "cache_hit", sdk: resolved.sdk, model: reference, tokens: usage.cacheRead, source: "prompt_cache" });
+    onEvent({ type: "cache_hit", sdk: "pi", model: reference, tokens: usage.cacheRead, source: "prompt_cache" });
   }
   if (usage.cacheWrite > 0) {
-    onEvent({ type: "cache_miss", sdk: resolved.sdk, model: reference, tokens: usage.cacheWrite, source: "prompt_cache" });
+    onEvent({ type: "cache_miss", sdk: "pi", model: reference, tokens: usage.cacheWrite, source: "prompt_cache" });
   }
   onEvent({
     type: "cost_accumulated",
-    sdk: resolved.sdk,
+    sdk: "pi",
     model: reference,
     cumulativeUsd: Number(usage.cost) || Number(estimatedCost) || 0,
     tokens: {
@@ -137,7 +156,7 @@ export function emitUsageCostEvents({
   });
   onEvent({
     type: "provider_request_completed",
-    sdk: resolved.sdk,
+    sdk: "pi",
     model: reference,
     runtime: "pi",
     timestamp: Date.now(),
@@ -167,9 +186,9 @@ export function abortedResult({ resolved, options, events, runtimeWarnings, star
     usage: {},
     durationMs: Date.now() - start,
     numTurns: 0,
-    model: resolved?.reference || resolved?.model || null,
+    model: resolved?.reference || (resolved?.provider && resolved?.model ? `${resolved.provider}:${resolved.model}` : null),
     effort: options.effort || null,
-    sdk: resolved?.sdk || "pi",
+    sdk: "pi",
     cancelled: true,
     error: null,
     failureKind: null,
@@ -211,6 +230,8 @@ export function buildSuccessResult(params) {
     runtimeWarnings,
     capabilitiesUsed,
     structuredResult,
+    usageMeasured = true,
+    effectiveEffort,
   } = params;
   return {
     text: finalText,
@@ -219,16 +240,17 @@ export function buildSuccessResult(params) {
     usage: {
       input_tokens: usage.input || null,
       output_tokens: usage.output || null,
-      cache_read_tokens: usage.cacheRead || null,
-      cache_creation_tokens: usage.cacheWrite || null,
-      cache_write_tokens: usage.cacheWrite || null,
+      cache_read_tokens: usageMeasured ? usage.cacheRead : null,
+      cache_creation_tokens: usageMeasured ? usage.cacheWrite : null,
+      cache_write_tokens: usageMeasured ? usage.cacheWrite : null,
       cost_usd: usage.cost || estimatedCost,
     },
     durationMs: Date.now() - start,
     numTurns: turnCount || runAssistantCount,
-    model: resolved.reference || `pi:${resolved.provider}:${resolved.model}`,
+    model: resolved.reference || `${resolved.provider}:${resolved.model}`,
     effort: options.effort || null,
-    sdk: resolved.sdk,
+    effectiveEffort: effectiveEffort || null,
+    sdk: "pi",
     cancelled: externalAbort,
     error: errorMessage,
     errorDetails,
@@ -266,6 +288,7 @@ export function buildErrorResult(params) {
     runtimeWarnings,
     isRetryable,
     piTransport,
+    effectiveEffort,
   } = params;
   return {
     text: assistantTexts.join("") || null,
@@ -273,9 +296,10 @@ export function buildErrorResult(params) {
     usage: {},
     durationMs: Date.now() - start,
     numTurns: turnCount,
-    model: resolved?.reference || resolved?.model || null,
+    model: resolved?.reference || (resolved?.provider && resolved?.model ? `${resolved.provider}:${resolved.model}` : null),
     effort: options.effort || null,
-    sdk: resolved?.sdk || "pi",
+    effectiveEffort: effectiveEffort || null,
+    sdk: "pi",
     cancelled: externalAbort,
     error: externalAbort ? null : errorMessage,
     errorDetails: externalAbort ? null : {

package/src/ai/providers/pi-native/session-lifecycle.js

@@ -10,12 +10,15 @@
 // createSessionLiveness primitives so the await-free spans are enforced by
 // construction rather than by inline sequencing.
 
-import { InMemorySessionRepo, JsonlSessionRepo } from "@earendil-works/pi-agent-core";
+import { JsonlSessionRepo, MemorySessionRepo, laneConfig, laneState, operationMeta, operationResult, operationState } from "@earendil-works/pi-agent-core";
+import { validRecoveryProjection } from "./terminal-recovery.js";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { open } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { access, open, readdir, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { createSessionRegistry } from "../../runtime/sessions.js";
 import { createSessionLiveness } from "../../runtime/session-liveness.js";
+import { buildPiSessionContext, createPiSessionAdapter, PI_CONTEXT } from "./harness-adapter.js";
 
 async function syncPath(path) {
   const handle = await open(path, "r");
@@ -27,6 +30,7 @@ async function syncPath(path) {
 }
 
 async function syncDurableTranscript(entry) {
+  if (entry.recoveryPending) throw new Error("Pi terminal recovery is pending");
   if (!entry.durable) return;
   const path = entry.metadata?.path;
   if (typeof path !== "string" || !path) {
@@ -40,31 +44,61 @@ async function syncDurableTranscript(entry) {
 }
 
 async function invalidateNativeSession(entry) {
-  await entry.repo.delete(entry.metadata);
   if (entry.durable) {
     const path = entry.metadata?.path;
     if (typeof path !== "string" || !path) {
       throw new Error("Durable Pi session metadata is missing its JSONL path");
     }
+    // Explicit invalidation is idempotent. A preceding failed sync may have
+    // observed that the transcript was already removed outside this process.
+    try {
+      await access(path);
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+  await entry.repo.delete(entry.metadata, PI_CONTEXT);
+  if (entry.durable) {
+    const path = entry.metadata.path;
     // Make the unlink durable before the registry forgets the busy marker.
     await syncPath(dirname(path));
   }
 }
 
+/**
+ * Release a Pi session handle and remove its repository record as independent
+ * best-effort operations. A close failure must not prevent deletion of a fresh
+ * or otherwise poisoned transcript.
+ * @param {any} session
+ * @param {any} repo
+ * @param {any} [knownMetadata]
+ */
+async function closeAndDeleteSession(session, repo, knownMetadata) {
+  let metadata = knownMetadata;
+  if (!metadata) {
+    try { metadata = await session.getMetadata(); } catch { /* best-effort */ }
+  }
+  try { await session.close(); } catch { /* best-effort */ }
+  if (metadata) {
+    try { await repo.delete(metadata, PI_CONTEXT); } catch { /* best-effort */ }
+  }
+}
+
 // Live pi-native sessions, keyed by provider session id. Entries are
-// { session, metadata, repo, durable, busy } — identical shape and lifecycle
-// policy to the (now-retired) pi-sdk bridge: in-memory transcripts are freed
-// when the registry evicts them; durable (jsonl) transcripts survive eviction
-// so a later resume can reopen them from disk. Registering here gives
+// { metadata, repo, durable, busy }. Pi 0.85 sessions are closed after every
+// turn so their repository record can be reopened safely; the registry owns
+// only liveness and metadata. In-memory transcripts are freed when the registry
+// evicts them; durable (jsonl) transcripts survive eviction. Registering here gives
 // runtime.disposeSession / disposeProviderSession + idle-TTL eviction the same
 // reach over native pi sessions that the legacy bridge had.
-const nativeSessionRepo = new InMemorySessionRepo();
+const nativeSessionRepo = new MemorySessionRepo();
 const nativeSessions = createSessionRegistry({
-  isBusy: (entry) => entry.busy === true,
+  isBusy: (entry) => entry.busy === true || entry.recoveryPending === true,
   onSync: syncDurableTranscript,
   onEvict: async (entry, reason) => {
-    // Ordinary disposal/TTL only drops the live handle so durable sessions can
-    // reopen after restart. Explicit invalidation means the host rejected the
+    // Ordinary disposal/TTL only drops registry metadata so durable sessions
+    // can reopen later. Explicit invalidation means the host rejected the
     // turn before canonical history commit; that poisoned transcript must be
     // deleted too or it could silently reappear on the next stable-id resume.
     if (reason === "invalidated") {
@@ -75,7 +109,7 @@ const nativeSessions = createSessionRegistry({
       return;
     }
     if (entry.durable) return;
-    await entry.repo.delete(entry.metadata);
+    await entry.repo.delete(entry.metadata, PI_CONTEXT);
   },
 });
 const liveness = createSessionLiveness(nativeSessions);
@@ -88,7 +122,7 @@ export function resolveDurableNativeSessionRepo(piSessionsRoot) {
   let repo = durableNativeSessionRepos.get(root);
   if (!repo) {
     repo = new JsonlSessionRepo({
-      fs: new NodeExecutionEnv({ cwd: process.cwd() }),
+      fileSystem: new NodeExecutionEnv({ cwd: process.cwd() }),
       sessionsRoot: root,
     });
     durableNativeSessionRepos.set(root, repo);
@@ -97,11 +131,13 @@ export function resolveDurableNativeSessionRepo(piSessionsRoot) {
 }
 
 /**
- * Permanently retire every durable Pi transcript with this exact logical id.
- * This is intentionally stronger than live-session invalidation: history
- * rotation and retention can retire an epoch after its registry entry was
- * already evicted or after a process restart. Absence is success; any cleanup
- * or verification uncertainty rejects so canonical history remains reachable.
+ * Retire every currently materialized durable Pi transcript with this exact
+ * logical id. This is intentionally stronger than live-session invalidation:
+ * history rotation and retention can retire an epoch after its registry entry
+ * was already evicted or after a process restart. When an active old run later
+ * recreates its pathname, its post-runtime caller retries this operation. The
+ * canonical epoch has already rotated, so that old id is never resumable in the
+ * interim. Absence is success; cleanup or verification uncertainty rejects.
  */
 export async function retireDurableNativeSession(providerSessionId, piSessionsRoot) {
   if (!isSafeSessionId(providerSessionId)) {
@@ -111,29 +147,87 @@ export async function retireDurableNativeSession(providerSessionId, piSessionsRo
     throw new TypeError("piSessionsRoot must be a non-empty path");
   }
 
-  // First guarantee this process cannot keep writing through a stale handle.
+  // First guarantee this process cannot resume through a stale registry entry.
+  // A host cancellation can rotate canonical history while the provider is
+  // still unwinding an open Pi session. The Pi repo deliberately refuses to
+  // delete an open session, so detach the registry and unlink its current file.
+  // Pi appends by pathname and can recreate a headerless orphan if the old run
+  // writes later; the raw exact-name sweep below removes those files on the
+  // post-runtime retry. The rotated canonical epoch never refers to this id.
+  const liveEntry = nativeSessions.get(providerSessionId);
+  const providerStillUnwinding = liveEntry?.busy === true;
   // Other processes are serialized by the history coordinator and must pass
   // the same cold-refresh barrier before their next turn.
   await nativeSessions.refresh(providerSessionId);
 
   const repo = resolveDurableNativeSessionRepo(piSessionsRoot);
   if (!repo) throw new Error("Durable Pi session repository is unavailable");
-  const matches = (await repo.list()).filter((entry) => entry?.id === providerSessionId);
+  const matches = (await repo.list(undefined, PI_CONTEXT)).filter((entry) => entry?.id === providerSessionId);
   const changedDirectories = new Set();
   for (const metadata of matches) {
     if (typeof metadata?.path !== "string" || !metadata.path) {
       throw new Error(`Durable Pi session ${providerSessionId} has invalid metadata`);
     }
-    await repo.delete(metadata);
+    if (providerStillUnwinding) {
+      try {
+        await unlink(metadata.path);
+      } catch (error) {
+        if (error?.code !== "ENOENT") throw error;
+      }
+    } else {
+      await repo.delete(metadata, PI_CONTEXT);
+    }
     changedDirectories.add(dirname(metadata.path));
   }
+  // A prior active-session unlink can be followed by Pi recreating the same
+  // pathname with a transaction line but no header. JsonlSessionRepo.list()
+  // intentionally ignores that invalid file, so scan only Pi's fixed
+  // root/directory/filename layout to make the later retirement retry reclaim
+  // it. Safe ids are single filename components and symlink directories/files
+  // are ignored.
+  for (const path of await exactDurableSessionFiles(piSessionsRoot, providerSessionId)) {
+    try {
+      await unlink(path);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    changedDirectories.add(dirname(path));
+  }
   for (const directory of changedDirectories) await syncPath(directory);
   if (changedDirectories.size > 0) await syncPath(resolve(piSessionsRoot));
 
-  const remaining = (await repo.list()).filter((entry) => entry?.id === providerSessionId);
-  if (remaining.length > 0) {
+  const remaining = (await repo.list(undefined, PI_CONTEXT)).filter((entry) => entry?.id === providerSessionId);
+  const remainingPaths = await exactDurableSessionFiles(piSessionsRoot, providerSessionId);
+  if (!providerStillUnwinding && (remaining.length > 0 || remainingPaths.length > 0)) {
     throw new Error(`Durable Pi session ${providerSessionId} could not be retired completely`);
   }
+  // An active Pi write can race the final exact-name check after the sweep.
+  // Canonical history is already preparing a fresh epoch, so the retired id is
+  // unreachable; the harness retries retirement when that old run returns.
+}
+
+async function exactDurableSessionFiles(piSessionsRoot, providerSessionId) {
+  const root = resolve(piSessionsRoot);
+  const suffix = `_${encodeURIComponent(providerSessionId)}.jsonl`;
+  let rootEntries;
+  try {
+    rootEntries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const paths = [];
+  for (const directory of rootEntries) {
+    if (!directory.isDirectory()) continue;
+    const directoryPath = join(root, directory.name);
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(suffix)) {
+        paths.push(join(directoryPath, entry.name));
+      }
+    }
+  }
+  return paths;
 }
 
 // Defense in depth (R4): create-on-miss passes the caller-controlled session id
@@ -158,10 +252,9 @@ function isSafeSessionId(id) {
 
 async function reopenDurableNativeSession(repo, sessionId) {
   try {
-    const metadata = (await repo.list()).find((entry) => entry?.id === sessionId);
+    const metadata = (await repo.list(undefined, PI_CONTEXT)).find((entry) => entry?.id === sessionId);
     if (!metadata) return null;
-    const session = await repo.open(metadata);
-    return { session, metadata, repo, durable: true, busy: false };
+    return { metadata, repo, durable: true, busy: false };
   } catch {
     return null;
   }
@@ -185,9 +278,9 @@ function sessionUnavailableResult({
     usage: {},
     durationMs: Date.now() - start,
     numTurns: 0,
-    model: resolved?.reference || resolved?.model || null,
+    model: resolved?.reference || (resolved?.provider && resolved?.model ? `${resolved.provider}:${resolved.model}` : null),
     effort: options.effort || null,
-    sdk: resolved?.sdk || "pi",
+    sdk: "pi",
     cancelled: false,
     error: errorMessage,
     failureKind,
@@ -290,11 +383,14 @@ export async function resolveSession(runState, {
         } else {
           // Reserved the id with a busy placeholder BEFORE the create await so a
           // second concurrent first turn observes busy and returns session_busy.
-          // The keep-alive success path (reservation.commit with busy:false)
-          // overwrites this placeholder on success; the drop/abort/catch paths
-          // release it. Keyed by requestedSessionId === providerSessionId.
+          // The keep-alive success path overwrites this placeholder with an
+          // entry that remains busy until its harness closes; drop/abort/catch
+          // paths release it. Keyed by requestedSessionId === providerSessionId.
           runState.reservation = reservation;
-          runState.session = await durableRepo.create({ id: providerSessionId, cwd: cwd || process.cwd() });
+          runState.session = createPiSessionAdapter(await durableRepo.create(
+            { id: providerSessionId, cwd: cwd || process.cwd() },
+            PI_CONTEXT,
+          ));
           runState.createdOnMiss = true;
         }
       } else {
@@ -322,7 +418,7 @@ export async function resolveSession(runState, {
       // (F4) safe. Do not introduce any await in this span or the TOCTOU window
       // reopens. `claim` re-reads the same registry entry and sets busy in one
       // await-free step; a busy entry loses and returns session_busy.
-      const claimed = liveness.claim(requestedSessionId);
+      const claimed = entry.recoveryPending ? { ok: /** @type {const} */ (false), reason: "busy" } : liveness.claim(requestedSessionId);
       if (!claimed.ok) {
         // claim() can lose two ways: "busy" (the entry adopted above is
         // mid-turn) or "missing" (no live entry). "missing" is UNREACHABLE on
@@ -353,14 +449,30 @@ export async function resolveSession(runState, {
         };
       }
       runState.sessionEntry = claimed.entry;
-      runState.session = claimed.entry.session;
+      delete claimed.entry.recovery;
+      try {
+        runState.session = createPiSessionAdapter(await claimed.entry.repo.open(
+          claimed.entry.metadata,
+          PI_CONTEXT,
+        ));
+      } catch (error) {
+        // The claim made this registry entry busy. An open failure means the
+        // entry cannot be driven, so remove its liveness record before
+        // propagating; otherwise every later resume retries the same broken
+        // entry forever. Preserve the durable transcript for a later cold
+        // reopen/recovery attempt.
+        liveness.release(requestedSessionId);
+        runState.sessionEntry = null;
+        throw error;
+      }
     }
   } else {
-    // Fresh runs persist into the durable jsonl repo when piSessionsRoot is
-    // set, so a kept-alive session can be reopened from disk after the live
-    // entry is evicted; otherwise the in-memory repo is used.
-    runState.session = await (durableRepo || nativeSessionRepo)
-      .create({ id: providerSessionId, cwd: cwd || process.cwd() });
+    // Attribution may equal a live primary's id on a stateless retry/backup.
+    // A private ephemeral repo prevents both create collisions and cleanup of
+    // that primary's transcript. Only keep-alive calls use a shared repository.
+    if (options.sessionKeepAlive !== true) runState.ephemeralSessionRepo = new MemorySessionRepo();
+    runState.session = createPiSessionAdapter(await (runState.ephemeralSessionRepo || durableRepo || nativeSessionRepo)
+      .create({ id: providerSessionId, cwd: cwd || process.cwd() }, PI_CONTEXT));
   }
   return { done: false };
 }
@@ -379,7 +491,10 @@ export async function discardUncommittedSession(runState, { durableRepo }) {
   // transcript was appended yet (prompt never ran), so the live session is
   // already at its pre-turn leaf and needs no rollback.
   if (runState.session && !runState.sessionEntry) {
-    try { await (durableRepo || nativeSessionRepo).delete(await runState.session.getMetadata()); } catch { /* best-effort */ }
+    await closeAndDeleteSession(
+      runState.session,
+      runState.ephemeralSessionRepo || durableRepo || nativeSessionRepo,
+    );
   }
   // Drop the create-on-miss BUSY reservation too, else the busy placeholder
   // leaks and every future resume of this conversation's stable id returns
@@ -407,7 +522,7 @@ export async function commitSession(runState, {
   onEvent,
 }) {
   const { session, sessionEntry, baselineLeafId, reservation } = runState;
-  if (options.sessionKeepAlive === true && !externalAbort && !errorMessage) {
+  if (options.sessionKeepAlive === true && ((!externalAbort && !errorMessage) || runState.retainRecoveryTail)) {
     try {
       if (sessionEntry) {
         // Resumed run: the harness appended this run's turns onto the live
@@ -419,17 +534,19 @@ export async function commitSession(runState, {
       } else {
         const metadata = await session.getMetadata();
         const entry = {
-          session,
           metadata,
           repo: durableRepo || nativeSessionRepo,
           durable: !!durableRepo,
-          busy: false,
+          busy: true,
         };
         // A create-on-miss reservation is overwritten by its commit (same id);
         // a plain fresh keep-alive run registers directly.
         if (reservation) reservation.commit(entry);
         else nativeSessions.set(providerSessionId, entry, { idleTimeoutMs: sessionTtlMs });
+        runState.registeredSessionEntry = entry;
       }
+      const retained = runState.sessionEntry || runState.registeredSessionEntry;
+      if (runState.retainRecoveryTail && retained) retained.recoveryPending = !!externalAbort || !!errorMessage;
     } catch (err) {
       // Session persistence must never fail the run; drop the (now
       // inconsistent) session instead of resuming from a broken transcript.
@@ -442,7 +559,7 @@ export async function commitSession(runState, {
       if (requestedSessionId) nativeSessions.delete(requestedSessionId);
       const broken = sessionEntry;
       if (broken) {
-        try { await broken.repo.delete(broken.metadata); } catch { /* best-effort */ }
+        await closeAndDeleteSession(session, broken.repo, broken.metadata);
       }
     }
   } else if (sessionEntry) {
@@ -463,9 +580,7 @@ export async function commitSession(runState, {
     // (the success keep-alive path overwrites it with the finalized entry, so
     // it is only this drop branch that must clean it up).
     if (reservation) reservation.release();
-    try {
-      await (durableRepo || nativeSessionRepo).delete(await session.getMetadata());
-    } catch { /* best-effort */ }
+    await closeAndDeleteSession(session, runState.ephemeralSessionRepo || durableRepo || nativeSessionRepo);
   }
 }
 
@@ -486,8 +601,9 @@ export async function rollbackAbortedTurn(runState, { requestedSessionId, provid
     }
     nativeSessions.delete(requestedSessionId);
   } else {
-    nativeSessions.delete(providerSessionId);
-    try { await (durableRepo || nativeSessionRepo).delete(await session.getMetadata()); } catch { /* best-effort */ }
+    // A stateless call never registered this id; it may belong to the primary.
+    if (!runState.ephemeralSessionRepo) nativeSessions.delete(providerSessionId);
+    await closeAndDeleteSession(session, runState.ephemeralSessionRepo || durableRepo || nativeSessionRepo);
   }
 }
 
@@ -495,7 +611,8 @@ export async function rollbackAbortedTurn(runState, { requestedSessionId, provid
  * Outer-catch session cleanup: drop a just-created fresh durable session, drop a
  * create-on-miss reservation placeholder, and roll a resumed session back to its
  * pre-turn leaf for host/runtime-side throws that landed after the harness
- * already mutated the live session.
+ * already mutated the live session. Resumed handles are always closed here so
+ * setup failures before a harness is returned cannot leave the repo wedged.
  * @param {any} runState
  * @param {{durableRepo: any}} params
  */
@@ -509,7 +626,7 @@ export async function cleanupSessionOnThrow(runState, { durableRepo }) {
   // resumed user session here would be data loss) and never when the throw
   // preceded session create.
   if (session && !sessionEntry) {
-    try { await (durableRepo || nativeSessionRepo).delete(await session.getMetadata()); } catch { /* best-effort */ }
+    await closeAndDeleteSession(session, runState.ephemeralSessionRepo || durableRepo || nativeSessionRepo);
   }
   // Drop a create-on-miss BUSY placeholder (R8) left in the registry by a throw
   // during/after the reservation — including a throw inside the create await
@@ -522,8 +639,89 @@ export async function cleanupSessionOnThrow(runState, { durableRepo }) {
   // harness already mutated the live session. Mirrors the success-path
   // rollback: move the live session back to the pre-turn leaf so the failed
   // turn never leaks into a later resume. Gated on `sessionEntry &&
-  // baselineLeafId` so it only fires for resumes that captured a baseline.
-  if (sessionEntry && baselineLeafId) {
-    try { await session.moveTo(baselineLeafId); } catch { /* best-effort */ }
+  // baselineLeafId` so rollback only fires for resumes that captured a baseline.
+  // Closing is independently gated on the resumed session existing: a failure
+  // may land before the baseline was readable, but that handle must still be
+  // released without deleting the user-owned transcript.
+  if (sessionEntry && session) {
+    if (baselineLeafId) {
+      try { await session.moveTo(baselineLeafId); } catch { /* best-effort */ }
+    }
+    try { await session.close(); } catch { /* best-effort */ }
+  }
+}
+
+/** Capture only after close; pending entries cannot be driven by another turn. */
+export async function captureSessionRecovery(runState, { options, providerSessionId, modelKey, model, pending }) {
+  const entry = runState.sessionEntry || runState.registeredSessionEntry;
+  if (!entry?.durable) return undefined;
+  try {
+    if (!Array.isArray(runState.recoveryInputIds)) throw new Error("Pi session recovery input identities are unavailable");
+    const tipId = await runState.session.getLeafId();
+    if (typeof tipId !== "string" || !tipId) throw new Error("Pi session recovery tip is unavailable");
+    const ancestry = createHash("sha256").update(JSON.stringify(await runState.session.getEntries())).digest("hex");
+    await runState.session.close();
+    const receipt = { runId: options.sessionRecovery.runId, revision: options.sessionRecovery.revision, providerSessionId, modelKey, tipId };
+    entry.recovery = { receipt: { ...receipt }, model: { ...model, input: [...model.input] }, ancestry, operationId: runState.recoveryOperationId, baselineTipId: runState.recoveryBaselineTipId, inputIds: runState.recoveryInputIds };
+    entry.recoveryPending = pending || !!options.abortSignal?.aborted;
+    return receipt;
+  } catch (error) {
+    // The run's outer catch performs legacy rollback/close or fresh deletion.
+    // Release provisional recovery state first so failed capture cannot strand
+    // an entry as busy without a receipt that could settle it.
+    entry.recoveryPending = false;
+    delete entry.recovery;
+    throw error;
+  }
+}
+
+/** Read-only settlement: never drive an operation or append host-authored prose. */
+export async function recoverDurableNativeSession(receipt, context) {
+  const entry = nativeSessions.get(receipt?.providerSessionId);
+  const proof = entry?.recovery;
+  if (!entry?.durable || entry.busy || !proof
+    || !["runId", "revision", "providerSessionId", "modelKey", "tipId"].every((key) => receipt[key] === proof.receipt[key])
+    || !Array.isArray(context?.appliedInputIds)
+    || proof.inputIds.some((id) => typeof id !== "string")
+    || JSON.stringify([...proof.inputIds].sort()) !== JSON.stringify([...context.appliedInputIds].sort())) return false;
+  entry.busy = true;
+  let raw;
+  try {
+    const matches = (await entry.repo.list(undefined, PI_CONTEXT)).filter((record) => record.id === receipt.providerSessionId);
+    if (matches.length !== 1 || matches[0].path !== entry.metadata.path) return false;
+    raw = await entry.repo.open(matches[0], PI_CONTEXT);
+    const branch = await raw.branch("main", PI_CONTEXT);
+    if (!branch || await branch.getTipId(PI_CONTEXT) !== receipt.tipId) return false;
+    const state = (await raw.getValue(laneState("main"), PI_CONTEXT))?.value;
+    const config = (await raw.getValue(laneConfig("main"), PI_CONTEXT))?.value;
+    const terminal = (await raw.getValue(operationResult(proof.operationId), PI_CONTEXT))?.value;
+    const meta = (await raw.getValue(operationMeta(proof.operationId), PI_CONTEXT))?.value;
+    if (!state || state.currentOperationId !== null || state.lastOperationId !== proof.operationId || state.inbox.length !== 0
+      || config?.model.provider !== proof.model.provider || config?.model.modelId !== proof.model.id
+      || !terminal || !["completed", "failed", "aborted"].includes(terminal.status) || terminal.tipId !== receipt.tipId
+      || meta !== undefined || terminal.kind !== "run" || terminal.fromTipId !== proof.baselineTipId
+      || await raw.getValue(operationState(proof.operationId), PI_CONTEXT)) return false;
+    const entries = await branch.findEntries({ order: "oldestFirst" }, PI_CONTEXT);
+    if (createHash("sha256").update(JSON.stringify(entries)).digest("hex") !== proof.ancestry) return false;
+    const baseline = proof.baselineTipId === null ? -1 : entries.findIndex((item) => item.id === proof.baselineTipId);
+    if (proof.baselineTipId !== null && baseline < 0) return false;
+    const tail = entries.slice(baseline + 1);
+    if (tail[0]?.type !== "message" || tail[0].message.role !== "user"
+      || tail.filter((item) => item.type === "message" && item.message.role === "user").length !== 1 + proof.inputIds.length) return false;
+    if (!validRecoveryProjection(buildPiSessionContext(entries), proof.model)) return false;
+    await raw.close(PI_CONTEXT);
+    raw = undefined;
+    // Pending is cleared only after persistence is certain. Bypass the ordinary
+    // sync guard while keeping the public busy reservation throughout the fsync.
+    await syncPath(entry.metadata.path);
+    await syncPath(dirname(entry.metadata.path));
+    entry.recoveryPending = false;
+    delete entry.recovery;
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try { await raw?.close(PI_CONTEXT); } catch { /* already failed closed */ }
+    entry.busy = false;
   }
 }