@akagilnc/pi-workflow-roles 0.1.5303 → 0.1.5312

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.5303",
+  "version": "0.1.5312",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/acp-host/description.ts

@@ -4,13 +4,10 @@
  * optional seat-profile soul — is data here; the lifecycle in role-turn-host.ts
  * stays one copy (#732).
  */
-import { join } from "node:path";
-
+import type { HostIdentityDescription } from "../host-descriptions.ts";
 import type { SeatProfileSoul } from "./seat-profile-soul.ts";
 
-export type AcpHostDescription = Readonly<{
-  /** Binary path segments relative to the operator home. */
-  binaryFromHome: readonly string[];
+export type AcpHostDescription = HostIdentityDescription & Readonly<{
   argv: Readonly<{
     prefix: readonly string[];
     suffix: readonly string[];
@@ -26,8 +23,6 @@ export type AcpHostDescription = Readonly<{
    *   `provider:model` (hermes).
    */
   modelPassing: "argv" | "set_model";
-  /** Durable ACP binding filename written beside the session principal. */
-  sessionBindingFile: string;
   /**
    * When set, the production factory ensures a seat profile whose SOUL.md is a
    * symlink to the packaged role soul, and prefixes argv with `flag <name>`.
@@ -36,11 +31,6 @@ export type AcpHostDescription = Readonly<{
   seatProfileSoul?: SeatProfileSoul;
 }>;
 
-/** Absolute agent binary for one operator home. */
-export function resolveAcpBinary(description: AcpHostDescription, operatorHome: string): string {
-  return join(operatorHome, ...description.binaryFromHome);
-}
-
 /** Stdio argv: optional profile flag, thinking flag, prefix, model, suffix. */
 export function acpStdioArgs(
   description: AcpHostDescription,

package/src/acp-host/production-host.ts

@@ -9,11 +9,12 @@
 import { randomUUID } from "node:crypto";
 
 import type { DurablePrincipalAuthority, RoleTurnHost, RoleTurnRequest } from "../host-contracts.ts";
+import { resolveHostBinary } from "../host-descriptions.ts";
 import { prepareRoleEnvelope } from "../role-envelope.ts";
 import type { RoleRuntimeDependencies } from "../role-runtime.ts";
 import { createRoleRuntimeDependencies } from "../role-runtime-dependencies.ts";
 import { createSessionIdentityAuthority } from "../session-identity.ts";
-import { acpStdioArgs, resolveAcpBinary, type AcpHostDescription } from "./description.ts";
+import { acpStdioArgs, type AcpHostDescription } from "./description.ts";
 import {
   connectAcpStdio,
   createAcpRoleTurnHost,
@@ -74,7 +75,7 @@ export function createProductionAcpRoleTurnHost(options: ProductionAcpHostOption
           role: request.activation.role,
         });
       return connectAcpStdio({
-        binary: resolveAcpBinary(description, request.home),
+        binary: resolveHostBinary(description, request.home),
         args: acpStdioArgs(
           description,
           request.model,

package/src/acp-host/role-turn-host.ts

@@ -2,11 +2,13 @@ import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 
-import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import type { RoleTurnHost, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
 import {
   createSerializedRoleTurnHost,
   driveExternalRoleTurnRounds,
+  externalHostFailure as failure,
   raceAgainstHostAbort,
+  withExternalHostCleanupFailure,
 } from "../external-host-turn-loop.ts";
 
 import {
@@ -19,6 +21,7 @@ import {
 } from "../package-contracts/navigator-output.ts";
 import {
   renderSystemPromptOverride,
+  resolveBoundHostSessionId,
   type PreparedRoleTurn,
   type SessionIdentityAuthority,
 } from "../prepared-role-turn.ts";
@@ -96,41 +99,6 @@ export type AcpRoleTurnHostConfig = Readonly<{
   prepare(request: RoleTurnRequest): Promise<PreparedRoleTurn>;
 }>;
 
-function failure(
-  cause: "activation" | "session" | "output",
-  name: string,
-  code: string,
-  details?: Readonly<Record<string, unknown>>,
-  diagnostic?: string,
-): RoleTurnResult {
-  return {
-    code: null,
-    stderr: "",
-    timedOut: false,
-    knownFailure: {
-      cause,
-      identity: { name, code },
-      ...(diagnostic === undefined ? {} : { diagnostic }),
-      ...(details === undefined ? {} : { details }),
-    },
-  };
-}
-
-/** Success→dispose failure; existing failure keeps primary cause + cleanup detail. */
-function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
-  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
-  if (outcome.knownFailure === undefined) {
-    return failure("session", "AcpDisposeFailure", "dispose-failed", { cleanupError: message }, message);
-  }
-  return {
-    ...outcome,
-    knownFailure: {
-      ...outcome.knownFailure,
-      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
-    },
-  };
-}
-
 type RpcReply = { readonly id?: unknown; readonly method?: unknown; readonly params?: unknown; readonly result?: unknown; readonly error?: unknown };
 
 function acpError(code: string, message: string, cause?: unknown): Error & { readonly code: string } {
@@ -259,7 +227,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
     let sessionOpened = false;
     let accepted = false;
     const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
-    // Mutable so dispose failure can outrank a clean turn (headless withCleanupFailure face).
+    // Mutable so dispose failure can outrank a clean turn.
     let outcome: RoleTurnResult = failure("session", "AcpNoOutcome", "no-outcome");
     try {
       if (prepared.mcpServers.length === 0) {
@@ -324,10 +292,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
         };
         let sessionReady = true;
         if (request.continuation.kind === "resume") {
-          const explicitHostSessionId = request.continuation.hostSessionId;
-          const boundSessionId = explicitHostSessionId !== undefined && explicitHostSessionId !== ""
-            ? explicitHostSessionId
-            : await config.sessionIdentity.load(request.principal);
+          const boundSessionId = await resolveBoundHostSessionId(request, config.sessionIdentity);
           if (boundSessionId !== undefined && boundSessionId !== "") {
             sessionId = boundSessionId;
             sessionId = await loadSession(boundSessionId);
@@ -446,7 +411,7 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
       try {
         await prepared.dispose?.();
       } catch (cleanupError) {
-        outcome = withCleanupFailure(outcome, cleanupError);
+        outcome = withExternalHostCleanupFailure(outcome, cleanupError, "AcpDisposeFailure");
       }
     }
     return outcome;

package/src/analyst-ledger.ts

@@ -319,7 +319,7 @@ function admitFrameSpanFromRows(rows: readonly LedgerSessionRow[]): {
   }
   return {
     models,
-    frameSpan: { startedAt: span.startedAt, endedAt: span.endedAt },
+    frameSpan: { startedAt: span.startedAt, endedAt: span.endedAt, wallMs: endedMs - startedMs },
     partialFirstFrameAt: { status: "present", at: span.startedAt },
     partialLastFrameAt: { status: "present", at: span.endedAt },
   };
@@ -329,6 +329,8 @@ function admitFrameSpanFromRows(rows: readonly LedgerSessionRow[]): {
 export type AnalystRunFrameSpan = {
   readonly startedAt: string;
   readonly endedAt: string;
+  /** Validated wall clock, computed once when the session span is admitted. */
+  readonly wallMs: number;
 };
 
 /**
@@ -371,6 +373,23 @@ export type AnalystReadableRunFacts = {
   readonly gateCycles: readonly AnalystGateCycleRound[];
 };
 
+/** Total wall clock for exactly the readable runs supplied by the caller. */
+export function sumAnalystRunWallMs(runs: readonly AnalystReadableRunFacts[]): number {
+  let total = 0;
+  for (const run of runs) total += run.frameSpan.wallMs;
+  return total;
+}
+
+/** Shared identity order for readable legs and their page/metric projections. */
+export function compareAnalystLegs(
+  a: Pick<AnalystReadableRunFacts, "book" | "role" | "runId">,
+  b: Pick<AnalystReadableRunFacts, "book" | "role" | "runId">,
+): number {
+  if (a.book !== b.book) return a.book.localeCompare(b.book);
+  if (a.role !== b.role) return a.role.localeCompare(b.role);
+  return a.runId.localeCompare(b.runId);
+}
+
 export type AnalystScopedRunScan = {
   /** Readable in-scope runs with retained typed facts (A2). */
   readonly runs: readonly AnalystReadableRunFacts[];

package/src/analyst-metric-families/acceptance-success-rework.ts

@@ -9,7 +9,7 @@
  * - success rate den = success-eligible accepted legs (no-receipt out; planned out)
  * - planned = plan-duty acceptance; never success numerator or denominator
  */
-import type { AnalystReadableRunFacts, AnalystRunTerminalFace } from "../analyst-ledger.ts";
+import { compareAnalystLegs, sumAnalystRunWallMs, type AnalystReadableRunFacts, type AnalystRunTerminalFace } from "../analyst-ledger.ts";
 import { medianNumber } from "../analyst-median.ts";
 import type { AnalystMetricFamilyModule } from "../analyst-metric-family.ts";
 import { packagedAnalystTerminal } from "../packaged-role-registry.ts";
@@ -99,10 +99,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function wallMsFromSpan(span: { readonly startedAt: string; readonly endedAt: string }): number {
-  return Date.parse(span.endedAt) - Date.parse(span.startedAt);
-}
-
 /** Locate collector groups array: receipt.groups or top-level groups. */
 function findCollectorGroups(body: Record<string, unknown>): unknown {
   if (Array.isArray(body.groups)) return body.groups;
@@ -235,7 +231,7 @@ function projectLegs(runs: readonly AnalystReadableRunFacts[]): AnalystAcceptanc
       book: run.book,
       role: run.role,
       startedAt: run.frameSpan.startedAt,
-      wallMs: wallMsFromSpan(run.frameSpan),
+      wallMs: run.frameSpan.wallMs,
       terminalLabel: mapped.terminalLabel,
       accepted: mapped.accepted,
       success: mapped.success,
@@ -247,11 +243,7 @@ function projectLegs(runs: readonly AnalystReadableRunFacts[]): AnalystAcceptanc
   }
 
   // Stable page order: book, role, runId (match A1 leg sort).
-  return legs.sort((a, b) => {
-    if (a.book !== b.book) return a.book.localeCompare(b.book);
-    if (a.role !== b.role) return a.role.localeCompare(b.role);
-    return a.runId.localeCompare(b.runId);
-  });
+  return legs.sort(compareAnalystLegs);
 }
 
 function aggregateByRole(legs: readonly AnalystAcceptanceLeg[]): AnalystRoleAcceptanceStats[] {
@@ -302,12 +294,10 @@ function aggregateByRole(legs: readonly AnalystAcceptanceLeg[]): AnalystRoleAcce
   });
 }
 
-function reworkLens(legs: readonly AnalystAcceptanceLeg[]): AnalystReworkLens {
+function reworkLens(legs: readonly AnalystAcceptanceLeg[], totalWallMs: number): AnalystReworkLens {
   let reworkWallMs = 0;
-  let totalWallMs = 0;
   let reworkLegCount = 0;
   for (const leg of legs) {
-    totalWallMs += leg.wallMs;
     if (leg.rework) {
       reworkWallMs += leg.wallMs;
       reworkLegCount += 1;
@@ -331,7 +321,7 @@ export function buildAcceptanceSuccessReworkSection(
     kind: "analyst-acceptance-success-rework",
     legs,
     byRole: aggregateByRole(legs),
-    rework: reworkLens(legs),
+    rework: reworkLens(legs, sumAnalystRunWallMs(runs)),
   };
 }
 

package/src/analyst-metric-families/b2-frame-buckets-actions.ts

@@ -16,7 +16,7 @@
  */
 import type { SessionToolInterval } from "../ledger-session-read.ts";
 import { medianNumber } from "../analyst-median.ts";
-import type { AnalystReadableRunFacts } from "../analyst-ledger.ts";
+import { compareAnalystLegs, type AnalystReadableRunFacts } from "../analyst-ledger.ts";
 import type { AnalystMetricFamilyModule } from "../analyst-metric-family.ts";
 
 export type AnalystB2ToolAction = {
@@ -221,7 +221,7 @@ export function computeAnalystB2RunMetrics(
 ): AnalystB2RunMetrics {
   const frameStartMs = timestampMs(facts.frameSpan.startedAt);
   const frameEndMs = timestampMs(facts.frameSpan.endedAt);
-  const wallMs = Math.max(0, frameEndMs - frameStartMs);
+  const wallMs = facts.frameSpan.wallMs;
 
   // Single frame-bounded core: clip → union once → bucket/complement/actions.
   const tools = clipToolsToFrame(closedTools(facts.toolIntervals), frameStartMs, frameEndMs);
@@ -258,11 +258,7 @@ const b2FrameBucketsActionsFamily: AnalystMetricFamilyModule = {
     if (input.runs.length === 0) return undefined;
     const runs = [...input.runs]
       .map(computeAnalystB2RunMetrics)
-      .sort((a, b) => {
-        if (a.book !== b.book) return a.book.localeCompare(b.book);
-        if (a.role !== b.role) return a.role.localeCompare(b.role);
-        return a.runId.localeCompare(b.runId);
-      });
+      .sort(compareAnalystLegs);
     const section: AnalystB2FrameBucketsActionsSection = {
       kind: "analyst-b2-frame-buckets-actions",
       runs,

package/src/analyst-metric-families/gate-cycles.ts

@@ -9,7 +9,7 @@ import type {
   AnalystGateCycleOrigin,
   AnalystGateCycleRound,
 } from "../analyst-gate-cycles-read.ts";
-import type { AnalystReadableRunFacts } from "../analyst-ledger.ts";
+import { compareAnalystLegs, type AnalystReadableRunFacts } from "../analyst-ledger.ts";
 import type { AnalystMetricFamilyModule } from "../analyst-metric-family.ts";
 
 export type AnalystGateCyclesRoundRow = {
@@ -73,12 +73,6 @@ function projectLeg(facts: AnalystReadableRunFacts): AnalystGateCyclesLeg {
   };
 }
 
-function compareLegs(a: AnalystGateCyclesLeg, b: AnalystGateCyclesLeg): number {
-  if (a.book !== b.book) return a.book.localeCompare(b.book);
-  if (a.role !== b.role) return a.role.localeCompare(b.role);
-  return a.runId.localeCompare(b.runId);
-}
-
 type OfficerAccum = {
   rounds: number;
   bounceCount: number;
@@ -132,7 +126,7 @@ const gateCyclesFamily: AnalystMetricFamilyModule = {
   id: "gate-cycles",
   contribute(input) {
     if (input.runs.length === 0) return undefined;
-    const legs = input.runs.map(projectLeg).sort(compareLegs);
+    const legs = input.runs.map(projectLeg).sort(compareAnalystLegs);
     const section: AnalystGateCyclesSection = {
       kind: "analyst-gate-cycles",
       legs,

package/src/analyst-metric-families/leg-wall-clock.ts

@@ -6,7 +6,7 @@
  * Registers by file drop under analyst-metric-families/ (A2 discovery).
  */
 import { medianNumber } from "../analyst-median.ts";
-import type { AnalystReadableRunFacts } from "../analyst-ledger.ts";
+import { compareAnalystLegs, sumAnalystRunWallMs, type AnalystReadableRunFacts } from "../analyst-ledger.ts";
 import type { AnalystMetricFamilyModule } from "../analyst-metric-family.ts";
 
 /** One readable leg's session-frame wall clock (first usable → last usable). */
@@ -31,19 +31,12 @@ export type AnalystLegWallClockSection = {
   readonly totalElapsedMs: number;
 };
 
-function frameSpanWallMs(span: {
-  readonly startedAt: string;
-  readonly endedAt: string;
-}): number {
-  return Date.parse(span.endedAt) - Date.parse(span.startedAt);
-}
-
 function projectEntry(facts: AnalystReadableRunFacts): AnalystLegWallClockEntry {
   return {
     runId: facts.runId,
     book: facts.book,
     role: facts.role,
-    wallMs: frameSpanWallMs(facts.frameSpan),
+    wallMs: facts.frameSpan.wallMs,
   };
 }
 
@@ -52,9 +45,7 @@ function compareRankingDesc(
   b: AnalystLegWallClockEntry,
 ): number {
   if (b.wallMs !== a.wallMs) return b.wallMs - a.wallMs;
-  if (a.book !== b.book) return a.book.localeCompare(b.book);
-  if (a.role !== b.role) return a.role.localeCompare(b.role);
-  return a.runId.localeCompare(b.runId);
+  return compareAnalystLegs(a, b);
 }
 
 /** Discovered by analyst-metric-families loader (default export). */
@@ -74,14 +65,11 @@ const legWallClockFamily: AnalystMetricFamilyModule = {
       return undefined;
     }
 
-    let totalElapsedMs = 0;
-    for (const wallMs of walls) totalElapsedMs += wallMs;
-
     const section: AnalystLegWallClockSection = {
       kind: "analyst-leg-wall-clock",
       ranking,
       medianWallMs,
-      totalElapsedMs,
+      totalElapsedMs: sumAnalystRunWallMs(input.runs),
     };
     return { legWallClock: section };
   },

package/src/analyst-metric-families/round-timeline.ts

@@ -70,10 +70,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function wallMsFromSpan(startedAt: string, endedAt: string): number {
-  return Date.parse(endedAt) - Date.parse(startedAt);
-}
-
 function readClassCount(body: Record<string, unknown>): number | undefined {
   if (!isRecord(body.outcome)) return undefined;
   if (!isRecord(body.outcome.decisiveFacts)) return undefined;
@@ -113,7 +109,7 @@ function projectRunRow(facts: AnalystReadableRunFacts): AnalystRoundTimelineRunR
     role: facts.role,
     startedAt,
     endedAt,
-    wallMs: wallMsFromSpan(startedAt, endedAt),
+    wallMs: facts.frameSpan.wallMs,
     terminal: projectTerminal(facts),
   };
 }

package/src/analyst-model-groups.ts

@@ -11,7 +11,7 @@
 import { buildAcceptanceSuccessReworkSection } from "./analyst-metric-families/acceptance-success-rework.ts";
 import type { AnalystReadableRunFacts } from "./analyst-ledger.ts";
 import { medianNumber } from "./analyst-median.ts";
-import type { AnalystUnreadableRun } from "./analyst-page.ts";
+import { sortUnreadable, type AnalystUnreadableRun } from "./analyst-page.ts";
 
 /** One raw model group with rates over legs in that group. */
 export type AnalystModelGroupRow = {
@@ -74,15 +74,6 @@ function displayNameFor(
   return aliased === undefined ? rawGroupKey : aliased;
 }
 
-function sortUnreadable(
-  unreadable: readonly AnalystUnreadableRun[],
-): AnalystUnreadableRun[] {
-  return [...unreadable].sort((a, b) => {
-    if (a.book !== b.book) return a.book.localeCompare(b.book);
-    return a.runId.localeCompare(b.runId);
-  });
-}
-
 /**
  * Legs with no usable session model identity cannot join any model group.
  * Reuse the typed unreadable path (locatable missing-source) — not an empty-key group.

package/src/analyst-page.ts

@@ -15,7 +15,7 @@ import {
   ensureRealDirectoryTree,
   physicalPathIdentity,
 } from "./activation-ledger-topology.ts";
-import type { AnalystReadableRunFacts } from "./analyst-ledger.ts";
+import { compareAnalystLegs, sumAnalystRunWallMs, type AnalystReadableRunFacts } from "./analyst-ledger.ts";
 import { loadAnalystIssueMetricFamilies } from "./analyst-metric-families.ts";
 import { composeAnalystMetricFamilySections } from "./analyst-metric-family.ts";
 
@@ -187,14 +187,10 @@ export function analystIssuePageAddressFromPage(
 }
 
 function sortLegs(legs: readonly AnalystLegEntry[]): AnalystLegEntry[] {
-  return [...legs].sort((a, b) => {
-    if (a.book !== b.book) return a.book.localeCompare(b.book);
-    if (a.role !== b.role) return a.role.localeCompare(b.role);
-    return a.runId.localeCompare(b.runId);
-  });
+  return [...legs].sort(compareAnalystLegs);
 }
 
-function sortUnreadable(
+export function sortUnreadable(
   unreadable: readonly AnalystUnreadableRun[],
 ): AnalystUnreadableRun[] {
   return [...unreadable].sort((a, b) => {
@@ -260,13 +256,6 @@ export function computeAnalystMsPerKLines(
   };
 }
 
-function frameSpanWallMs(span: {
-  readonly startedAt: string;
-  readonly endedAt: string;
-}): number {
-  return Date.parse(span.endedAt) - Date.parse(span.startedAt);
-}
-
 /**
  * Σ readable wall clocks + max end-frame across ALL runs (C1 efficiency / index).
  * Unreadable runs never enter totalElapsedMs; their available lastFrameAt still
@@ -279,10 +268,9 @@ export function summarizeAnalystRunEfficiency(
   readonly totalElapsedMs: number;
   readonly lastActivityAt: AnalystOptionalTimestamp;
 } {
-  let totalElapsedMs = 0;
+  const totalElapsedMs = sumAnalystRunWallMs(runs);
   let latestEndedAt: string | undefined;
   for (const run of runs) {
-    totalElapsedMs += frameSpanWallMs(run.frameSpan);
     const endedAt = run.frameSpan.endedAt;
     if (latestEndedAt === undefined || endedAt > latestEndedAt) {
       latestEndedAt = endedAt;

package/src/external-host-turn-loop.ts

@@ -9,25 +9,11 @@ import type {
   RoleTurnRequest,
   RoleTurnResult,
 } from "./host-contracts.ts";
+import type { PreparedRoleTurn } from "./prepared-role-turn.ts";
 
 export const EXTERNAL_ROLE_TURN_ROUND_LIMIT = 8 as const;
 
-export type ExternalPreparedTurn = Readonly<{
-  readonly prompt: string;
-  readonly abortSignal?: AbortSignal;
-  closeRound(): Promise<
-    | { readonly accepted: true }
-    | {
-      readonly accepted: false;
-      readonly retry: {
-        readonly code: string;
-        readonly toolCallIds: readonly string[];
-        readonly message: string;
-      };
-    }
-    | { readonly accepted: false; readonly failure: RoleTurnKnownFailure }
-  >;
-}>;
+export type ExternalPreparedTurn = Pick<PreparedRoleTurn, "prompt" | "abortSignal" | "closeRound">;
 
 export type ExternalHostRoundOutcome =
   | { readonly status: "delivered"; readonly stderr?: string }
@@ -96,6 +82,40 @@ export function raceAgainstHostAbort<T>(
   });
 }
 
+export function externalHostFailure(
+  cause: NonNullable<RoleTurnKnownFailure["cause"]>,
+  name: string,
+  code: string,
+  details?: Readonly<Record<string, unknown>>,
+  diagnostic?: string,
+): RoleTurnResult {
+  return asFailure({
+    cause,
+    identity: { name, code },
+    ...(diagnostic === undefined ? {} : { diagnostic }),
+    ...(details === undefined ? {} : { details }),
+  });
+}
+
+/** A dispose failure replaces success; a primary failure retains its cause. */
+export function withExternalHostCleanupFailure(
+  outcome: RoleTurnResult,
+  cleanupError: unknown,
+  name: string,
+): RoleTurnResult {
+  const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+  if (outcome.knownFailure === undefined) {
+    return externalHostFailure("session", name, "dispose-failed", { cleanupError: message }, message);
+  }
+  return {
+    ...outcome,
+    knownFailure: {
+      ...outcome.knownFailure,
+      details: { ...(outcome.knownFailure.details ?? {}), cleanupError: message },
+    },
+  };
+}
+
 function asFailure(knownFailure: RoleTurnKnownFailure, stderr = ""): RoleTurnResult {
   return { code: null, stderr, timedOut: false, knownFailure };
 }

package/src/headless-host/description.ts

@@ -4,17 +4,10 @@
  * Claude print-mode and codex exec differ enough that #752 host-specific
  * assembly lives here as sibling helpers — not a third unified abstraction.
  */
-import { join } from "node:path";
-
-type HeadlessHostBase = Readonly<{
-  /** Binary path segments relative to the operator home. */
-  binaryFromHome: readonly string[];
-  /** Durable session-id binding filename beside the session principal. */
-  sessionBindingFile: string;
-}>;
+import type { HostIdentityDescription } from "../host-descriptions.ts";
 
 /** Claude Code print-mode (#645). */
-export type ClaudePrintHostDescription = HeadlessHostBase & Readonly<{
+export type ClaudePrintHostDescription = HostIdentityDescription & Readonly<{
   protocol: "claude-print";
   /**
    * Host-native print-mode flags that never change per turn (no prompt).
@@ -48,7 +41,7 @@ export type ClaudePrintHostDescription = HeadlessHostBase & Readonly<{
  * Protocol differences (JSONL, resume subcommand, schema file, `-c` MCP) stay
  * in codex-specific helpers — description only carries identity + binary path.
  */
-export type CodexExecHostDescription = HeadlessHostBase & Readonly<{
+export type CodexExecHostDescription = HostIdentityDescription & Readonly<{
   protocol: "codex-exec";
 }>;
 
@@ -66,14 +59,6 @@ export function isCodexExecDescription(
   return description.protocol === "codex-exec";
 }
 
-/** Absolute agent binary for one operator home. */
-export function resolveHeadlessBinary(
-  description: HeadlessHostDescription,
-  operatorHome: string,
-): string {
-  return join(operatorHome, ...description.binaryFromHome);
-}
-
 /**
  * Build one Claude print-mode argv for a single process turn.
  * Shape: `<promptFlag> <fixedArgs…> <system/schema/mcp/model/effort/session…>`.

package/src/headless-host/production-host.ts

@@ -12,10 +12,11 @@
 import { randomUUID } from "node:crypto";
 
 import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import { resolveHostBinary } from "../host-descriptions.ts";
 import { createRoleRuntimeDependencies } from "../role-runtime-dependencies.ts";
 import { prepareRoleEnvelope } from "../role-envelope.ts";
 import { createSessionIdentityAuthority } from "../session-identity.ts";
-import { resolveHeadlessBinary, type HeadlessHostDescription } from "./description.ts";
+import type { HeadlessHostDescription } from "./description.ts";
 import { createHeadlessRoleTurnHost } from "./role-turn-host.ts";
 
 export type ProductionHeadlessHostOptions = Readonly<{
@@ -46,7 +47,7 @@ export function createProductionHeadlessRoleTurnHost(
       description,
       hostName,
       sessionIdentity,
-      binary: resolveHeadlessBinary(description, operatorHome),
+      binary: resolveHostBinary(description, operatorHome),
       env: {
         ...process.env,
         AK_PACKAGE_ROOT: packageRoot,