@akagilnc/pi-workflow-roles 0.1.5365 → 0.1.5368

package/src/public-cli/post-admission.ts

@@ -18,7 +18,7 @@ import {
   type SameTicketSummonsMaterials,
 } from "./run-lifecycle.ts";
 import { CliUsageError } from "./cli-errors.ts";
-import type { RoleTurnRequestProjectionOptions } from "./turn-request.ts";
+import { projectPublicTurnAxes, type RoleTurnRequestProjectionOptions } from "./turn-request.ts";
 import {
   bindAdmittedTicketNumber,
   buildInstructionTransportPrompt,
@@ -119,6 +119,7 @@ import {
   persistReturnedRunState,
   runWithAutoResumeLoop,
   TurnDispatchedFailure,
+  writeHardenedArtifactFile,
 } from "./auto-resume.ts";
 
 function projectRelocatedTurnIdentity(
@@ -268,11 +269,10 @@ async function recordBestEffortPostDispatchDiagnostic<A extends AdmittedRoleInvo
   } catch (appendError) {
     try {
       const artifactsDir = await ensureRealArtifactsDirectory(admitted.runDirectory);
-      await writeFile(
-        join(artifactsDir, `post-admission-diagnostic-${randomUUID()}.json`),
-        `${JSON.stringify({ version: 1, ...payload }, null, 2)}\n`,
-        { encoding: "utf8", flag: "wx" },
-      );
+      await writeHardenedArtifactFile(artifactsDir, "post-admission-diagnostic", {
+        version: 1,
+        ...payload,
+      });
     } catch (artifactError) {
       retentionFailure =
         `post-dispatch diagnostic durable retention failed on both channels (best-effort continue): dossier=${describeErrorIdentity(appendError)}; artifact=${describeErrorIdentity(artifactError)}`;
@@ -1318,13 +1318,8 @@ export function resumeTurnRequestProjectionOptions(
     prompt = "";
   }
   return {
-    packageRoot: env.packageRoot,
-    home: env.home,
+    ...projectPublicTurnAxes(env),
     ...(env.host === undefined ? {} : { host: env.host }),
-    agentDir: env.agentDir,
-    ...(env.model === undefined ? {} : { model: env.model }),
-    ...pickEngineAxis(env),
-    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
     ...(env.correlationId === undefined && admitted.correlationId === undefined
       ? {}
       : { correlationId: env.correlationId ?? admitted.correlationId }),
@@ -1345,13 +1340,8 @@ export function roleTurnOptions(
 ): RoleTurnRequestProjectionOptions {
   const correlationId = env.correlationId ?? admitted.correlationId;
   return {
-    packageRoot: env.packageRoot,
-    home: env.home,
+    ...projectPublicTurnAxes(env),
     ...(env.host === undefined ? {} : { host: env.host }),
-    agentDir: env.agentDir,
-    ...(env.model === undefined ? {} : { model: env.model }),
-    ...pickEngineAxis(env),
-    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
     ...(correlationId === undefined || correlationId.trim() === ""
       ? {}
       : { correlationId }),
@@ -1383,6 +1373,66 @@ async function dispatchAfterWriterLease<T>(input: {
   }
 }
 
+/**
+ * One auto-resume dispatch: deferred run-state persist settles on the same
+ * path for station-child and ordinary in-call retries. The caller owns how
+ * the turn request is built and which correlation id the env carries.
+ */
+async function runSettledAutoResumeLoop<
+  A extends AdmittedRoleInvocation,
+  T extends TerminalResult,
+  P,
+>(input: {
+  admitted: A;
+  env: PostAdmissionEnv;
+  io: CliIo;
+  adapters: PostAdmissionAdapters<A, T>;
+  effectiveEngine?: string;
+  dispatchEnv?: PostAdmissionEnv;
+  buildInitialPayload: () => P;
+  buildResumePayload: () => P;
+  toRequest: (payload: P) => Promise<RoleTurnRequest>;
+}): Promise<{ exitCode: number; admitted?: A; terminal?: T }> {
+  const adapters = withOnceSuccessfulBeforeDispatch(input.adapters);
+  const dispatchEnv = input.dispatchEnv ?? input.env;
+  return runWithAutoResumeLoop({
+    admitted: input.admitted,
+    principalAuthority: input.env.principalAuthority,
+    io: input.io,
+    sessionAppender: input.env.sessionAppender,
+    autoResumeLimit: input.env.autoResumeLimit,
+    ...(input.env.signal === undefined ? {} : { signal: input.env.signal }),
+    buildInitialPayload: input.buildInitialPayload,
+    buildResumePayload: input.buildResumePayload,
+    dispatch: async (payload, lease, _isFirst, attemptIo) =>
+      dispatchAfterWriterLease({
+        ...(lease === undefined ? {} : { lease }),
+        build: () => input.toRequest(payload),
+        dispatch: async (request) => {
+          const result = await dispatchPostAdmissionTurn({
+            admitted: input.admitted,
+            env: dispatchEnv,
+            io: attemptIo,
+            request,
+            ...(lease === undefined ? {} : { lease }),
+            adapters,
+            persistRunState: false,
+            ...(input.effectiveEngine === undefined
+              ? {}
+              : { effectiveEngine: input.effectiveEngine }),
+          });
+          return settleDeferredPersist(
+            input.admitted,
+            input.env.principalAuthority,
+            adapters,
+            attemptIo,
+            result,
+          );
+        },
+      }),
+  });
+}
+
 function isAlreadyFrozenSummonsAttachment(
   runDirectory: string,
   attachmentPath: string,
@@ -1601,7 +1651,6 @@ export async function runPostAdmissionSeatResume<
   try {
     if (env.stationChild === true) {
       let firstTurn: RoleTurnRequest | undefined;
-      const stationAdapters = withOnceSuccessfulBeforeDispatch(adapters);
       type StationChildAttempt = { readonly resumeTurn: boolean };
       // One public call → one detour scope across in-place auto-resume dispatches.
       const invocationScopeId = mintEngineDetourInvocationScope({
@@ -1609,68 +1658,42 @@ export async function runPostAdmissionSeatResume<
           ? {}
           : { effectiveEngine: input.effectiveEngine }),
       });
-      return await runWithAutoResumeLoop({
+      return await runSettledAutoResumeLoop({
         admitted: loaded.admitted,
-        principalAuthority: env.principalAuthority,
+        env,
         io: input.io,
-        sessionAppender: env.sessionAppender,
-        autoResumeLimit: env.autoResumeLimit,
-        ...(env.signal === undefined ? {} : { signal: env.signal }),
+        adapters,
+        ...(input.effectiveEngine === undefined
+          ? {}
+          : { effectiveEngine: input.effectiveEngine }),
         buildInitialPayload: (): StationChildAttempt => ({ resumeTurn: false }),
         buildResumePayload: (): StationChildAttempt => ({ resumeTurn: true }),
-        // Same as public manual resume: prior-court sealed acceptance is not a
-        // redispatch brake (#833). New-court station-child turns still auto-resume.
-        dispatch: async (payload, lease, _isFirst, attemptIo) =>
-          dispatchAfterWriterLease({
-            ...(lease === undefined ? {} : { lease }),
-            build: async () => {
-              // #840 r8 判词 class 2: this call-local retry must keep this
-              // court's frozen summons / 交卷 body / attachments verbatim
-              // (same object as firstTurn) and project only the minimal
-              // host-needed resume trigger — never engine handbook material,
-              // which would replace a 审核循环 same-ticket continuation with a bare outsourcing
-              // 「重新读」 envelope (#755 contract, resumeTurnRequestProjectionOptions
-              // above). RESUME_TRANSPORT_ENVELOPE is the same package-owned,
-              // non-semantic trigger that projection already uses for a
-              // same-ticket summons carrying no instruction/attachments.
-              if (payload.resumeTurn && firstTurn !== undefined) {
-                return {
-                  ...firstTurn,
-                  continuation: {
-                    kind: "resume",
-                    prompt: RESUME_TRANSPORT_ENVELOPE,
-                  },
-                };
-              }
-              const turnRequest = withEngineDetourInvocationScope(
-                await buildRequestAfterLease(),
-                invocationScopeId,
-              );
-              firstTurn = turnRequest;
-              return turnRequest;
-            },
-            dispatch: async (turnRequest) => {
-              const result = await dispatchPostAdmissionTurn({
-                admitted: loaded.admitted,
-                env,
-                io: attemptIo,
-                request: turnRequest,
-                ...(lease === undefined ? {} : { lease }),
-                adapters: stationAdapters,
-                persistRunState: false,
-                ...(input.effectiveEngine === undefined
-                  ? {}
-                  : { effectiveEngine: input.effectiveEngine }),
-              });
-              return settleDeferredPersist(
-                loaded.admitted,
-                env.principalAuthority,
-                stationAdapters,
-                attemptIo,
-                result,
-              );
-            },
-          }),
+        toRequest: async (payload) => {
+          // #840 r8 判词 class 2: this call-local retry must keep this
+          // court's frozen summons / 交卷 body / attachments verbatim
+          // (same object as firstTurn) and project only the minimal
+          // host-needed resume trigger — never engine handbook material,
+          // which would replace a 审核循环 same-ticket continuation with a bare outsourcing
+          // 「重新读」 envelope (#755 contract, resumeTurnRequestProjectionOptions
+          // above). RESUME_TRANSPORT_ENVELOPE is the same package-owned,
+          // non-semantic trigger that projection already uses for a
+          // same-ticket summons carrying no instruction/attachments.
+          if (payload.resumeTurn && firstTurn !== undefined) {
+            return {
+              ...firstTurn,
+              continuation: {
+                kind: "resume",
+                prompt: RESUME_TRANSPORT_ENVELOPE,
+              },
+            };
+          }
+          const turnRequest = withEngineDetourInvocationScope(
+            await buildRequestAfterLease(),
+            invocationScopeId,
+          );
+          firstTurn = turnRequest;
+          return turnRequest;
+        },
       });
     }
     const resumed = await runPostAdmissionManualResume({
@@ -1873,7 +1896,6 @@ export async function runPostAdmissionResumable<
   terminal?: T;
 }> {
   const { admitted, env, io, buildInitialRequest, buildResumeRequest, effectiveEngine } = input;
-  const adapters = withOnceSuccessfulBeforeDispatch(input.adapters);
 
   // One public call → one detour scope across in-place auto-resume dispatches.
   const invocationScopeId = mintEngineDetourInvocationScope({
@@ -1884,32 +1906,20 @@ export async function runPostAdmissionResumable<
   const buildScopedResume = (): RoleTurnRequest =>
     withEngineDetourInvocationScope(buildResumeRequest(), invocationScopeId);
 
-  return runWithAutoResumeLoop({
+  return runSettledAutoResumeLoop({
     admitted,
-    principalAuthority: env.principalAuthority,
+    env,
     io,
-    sessionAppender: env.sessionAppender,
-    autoResumeLimit: env.autoResumeLimit,
-    ...(env.signal === undefined ? {} : { signal: env.signal }),
+    adapters: input.adapters,
+    ...(effectiveEngine === undefined ? {} : { effectiveEngine }),
+    // Ordinary in-call retry keeps the admitted correlation when one was stored.
+    dispatchEnv: {
+      ...env,
+      ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
+    },
     buildInitialPayload: buildScopedInitial,
     buildResumePayload: buildScopedResume,
-    dispatch: async (request, lease, _isFirst, attemptIo) => {
-      const result = await dispatchPostAdmissionTurn({
-        admitted,
-        env: {
-          ...env,
-          ...(admitted.correlationId === undefined ? {} : { correlationId: admitted.correlationId }),
-        },
-        io: attemptIo,
-        request,
-        ...(lease === undefined ? {} : { lease }),
-        adapters,
-        persistRunState: false,
-        // #600: every attempt (initial + auto-resume) writes seat engine when present.
-        ...(effectiveEngine === undefined ? {} : { effectiveEngine }),
-      });
-      return settleDeferredPersist(admitted, env.principalAuthority, adapters, attemptIo, result);
-    },
+    toRequest: async (request) => request,
   });
 }
 

package/src/public-cli/role-seat-runtime.ts

@@ -0,0 +1,72 @@
+/**
+ * One seat-runtime assembly for the public CLI and nested summons.
+ * Order is host selection, the caller's argv parse, the missing-model fact,
+ * then host-facing provider projection. Callers own how a missing model is shown.
+ */
+import { pickEngineAxis } from "../package-resources/engine-material.ts";
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import {
+  resolvedSeatWithModel,
+  type EffectiveSeat,
+  type SeatModelConfig,
+} from "./config.ts";
+import {
+  loadHostProvidersTable,
+  projectHostFacingProvider,
+} from "./host-providers.ts";
+import {
+  composeRoleTurnHostAdapters,
+  selectRoleTurnHost,
+  type NamedRoleTurnHostAdapter,
+  type RoleTurnHostResolutionInput,
+} from "./role-turn-host-resolution.ts";
+import type { PublicCallableRole } from "./registry.ts";
+
+export type OpenedRoleSeatRuntime =
+  | { readonly ok: false }
+  | {
+      readonly ok: true;
+      readonly roleTurnHost: RoleTurnHost;
+      readonly hostAdapters: readonly NamedRoleTurnHostAdapter[];
+      readonly model?: SeatModelConfig;
+      readonly engine?: string;
+      readonly engineModel?: string;
+      readonly host: string;
+    };
+
+export function openRoleSeatRuntime(input: {
+  readonly resolution: RoleTurnHostResolutionInput;
+  readonly principalAuthority: DurablePrincipalAuthority;
+  readonly role: PublicCallableRole;
+  readonly seat: EffectiveSeat;
+  readonly home: string;
+  readonly afterHost?: () => void;
+  /** Already host-facing. A second projection would rename the provider again. */
+  readonly hostFacingModel?: SeatModelConfig;
+}): OpenedRoleSeatRuntime {
+  const hostAdapters = composeRoleTurnHostAdapters(
+    input.resolution,
+    input.principalAuthority,
+  );
+  const roleTurnHost = selectRoleTurnHost(hostAdapters, {
+    role: input.role,
+    seat: input.seat,
+  });
+  input.afterHost?.();
+  const seatWithModel = resolvedSeatWithModel(input.seat);
+  if (seatWithModel === undefined) return { ok: false };
+  const projected = input.hostFacingModel ?? projectHostFacingProvider(
+    seatWithModel.selection,
+    seatWithModel.host,
+    loadHostProvidersTable(input.home),
+    input.home,
+  );
+  return {
+    ok: true,
+    roleTurnHost,
+    hostAdapters,
+    ...(projected === undefined ? {} : { model: projected }),
+    ...pickEngineAxis(seatWithModel),
+    host: seatWithModel.host,
+  };
+}

package/src/public-cli/run-lifecycle.ts

@@ -49,6 +49,7 @@ import {
   type PackagedRole,
 } from "../packaged-role-registry.ts";
 import {
+  admittedReviewerBaseFault,
   recordEffectiveInvocationModel,
   requireAuthorityRef,
   isReviewerLens,
@@ -1586,25 +1587,7 @@ function seatLoadedResult<R extends AdmittedRoleInvocation>(
 export async function peekRoleRunRole(
   home: string,
   runId: string,
-): Promise<
-  | "judge"
-  | "coder"
-  | "fixer"
-  | "collector"
-  | "doctor"
-  | "reviewer"
-  | "merger"
-  | "notary"
-  | "countersign"
-  | "gleaner-left"
-  | "inspector"
-  | "gatekeeper"
-  | "navigator"
-  | "auditor"
-  | "diarist"
-  | "secretariat"
-  | undefined
-> {
+): Promise<PackagedRole | undefined> {
   const runDirectory = await findRunDirectoryById(home, runId);
   if (runDirectory === undefined) return undefined;
   const run = await readRoleRunIdentity(runDirectory);
@@ -1725,14 +1708,12 @@ function admitResumedRole(loaded: {
     }
     case "review-basis": {
       const rawBase = fields.baseRevision;
-      if (rawBase === undefined || rawBase.trim() === "") {
-        throw new CliUsageError(
-          `role run admitted reviewer base revision is missing: ${runId}`,
-        );
-      }
-      if (/\s/.test(rawBase) || rawBase.startsWith("-")) {
+      const baseFault = admittedReviewerBaseFault(rawBase);
+      if (baseFault !== undefined || rawBase === undefined) {
         throw new CliUsageError(
-          `role run admitted reviewer base revision is damaged: ${runId}`,
+          baseFault === "damaged"
+            ? `role run admitted reviewer base revision is damaged: ${runId}`
+            : `role run admitted reviewer base revision is missing: ${runId}`,
         );
       }
       const lens = fields.lens;

package/src/public-cli/terminal.ts

@@ -7,6 +7,7 @@
  */
 import type { NoReceiptLifecycleFacts } from "../receipt-delivery-policy.ts";
 import type { ControlledFailureCause } from "../host-contracts.ts";
+import type { PackagedRole } from "../packaged-role-registry.ts";
 
 export type { ControlledFailureCause } from "../host-contracts.ts";
 
@@ -22,23 +23,7 @@ export type TerminalArtifactRef = {
 };
 
 /** Public callable roles that currently produce Terminal outcomes. */
-export type TerminalRoleName =
-  | "judge"
-  | "coder"
-  | "fixer"
-  | "collector"
-  | "doctor"
-  | "reviewer"
-  | "merger"
-  | "notary"
-  | "countersign"
-  | "gleaner-left"
-  | "inspector"
-  | "gatekeeper"
-  | "navigator"
-  | "auditor"
-  | "diarist"
-  | "secretariat";
+export type TerminalRoleName = PackagedRole;
 
 export type NoReceiptTerminalOutcome = NoReceiptLifecycleFacts & {
   kind: "no_receipt";

package/src/public-cli/turn-request.ts

@@ -27,6 +27,32 @@ export type ResumeModelConfig = {
   readonly thinking?: PublicThinkingLevel;
 };
 
+/**
+ * Env axes shared by every public turn projection.
+ * Callers add correlation, continuation, host, and station-only fields.
+ */
+export function projectPublicTurnAxes(env: {
+  readonly packageRoot: string;
+  readonly home: string;
+  readonly agentDir: string;
+  readonly model?: SeatModelConfig;
+  readonly engine?: string;
+  readonly engineModel?: string;
+  readonly timeoutMs?: number;
+}): Pick<
+  RoleTurnRequestProjectionOptions,
+  "packageRoot" | "home" | "agentDir" | "model" | "engine" | "engineModel" | "timeoutMs"
+> {
+  return {
+    packageRoot: env.packageRoot,
+    home: env.home,
+    agentDir: env.agentDir,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...pickEngineAxis(env),
+    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+  };
+}
+
 export type RoleTurnRequestProjectionOptions = {
   packageRoot: string;
   home: string;

package/src/public-role-summons.ts

@@ -25,7 +25,6 @@ import type {
 } from "./host-contracts.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
 import type { HostSelectionFailure, NamedRoleTurnHostAdapter } from "./public-cli/role-turn-host-resolution.ts";
-import { pickEngineAxis } from "./package-resources/engine-material.ts";
 
 /** Env published by the parent activation so nested summons never re-derive root. */
 export const AK_ROLE_PACKAGE_ROOT_ENV = "AK_ROLE_PACKAGE_ROOT" as const;
@@ -210,18 +209,6 @@ async function resolveSummonHome(options: PublicSummonRequest): Promise<string>
   return packageMachineHome();
 }
 
-/** Seat axes only — no parent-env fallback (#675 / #617 DK-3 / #883). */
-function projectSeatEngine(seat: EffectiveSeat): {
-  engine?: string;
-  engineModel?: string;
-} {
-  return pickEngineAxis(seat);
-}
-
-function projectSeatHost(seat: EffectiveSeat): { host?: string } {
-  return seat.host === undefined ? {} : { host: seat.host };
-}
-
 function hostSelectionFailureFromUnknown(error: unknown): HostSelectionFailure | undefined {
   if (typeof error !== "object" || error === null) return undefined;
   if ((error as { name?: unknown }).name !== "HostSelectionError") return undefined;
@@ -273,18 +260,17 @@ async function createSummonEnv(
   const [
     { piDurablePrincipalAuthority },
     { appendPiSessionCustomEntry },
-    { resolveRoleTurnHost },
-    { missingResolvedSeatModelMessage, resolvedSeatWithModel },
+    { openRoleSeatRuntime },
+    { missingResolvedSeatModelMessage },
   ] = await Promise.all([
     import("./pi/durable-principal.ts"),
     import("./pi/role-turn-host.ts"),
-    import("./public-cli/role-turn-host-resolution.ts"),
+    import("./public-cli/role-seat-runtime.ts"),
     import("./public-cli/config.ts"),
   ]);
   const principalAuthority = options.principalAuthority ?? piDurablePrincipalAuthority;
-  // Host first → argv (afterHost) → missing-model → provider projection (#617/#178/#840).
-  const roleTurnHost = resolveRoleTurnHost(
-    {
+  const opened = openRoleSeatRuntime({
+    resolution: {
       packageRoot: options.packageRoot,
       ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
       ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
@@ -293,29 +279,19 @@ async function createSummonEnv(
         : { extraPiArgs: options.extraPiArgs }),
       ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     },
-    { role: options.role, seat: options.seat, principalAuthority },
-  );
-  afterHost?.();
-  const seatWithModel = resolvedSeatWithModel(options.seat);
-  if (seatWithModel === undefined) {
+    principalAuthority,
+    role: options.role,
+    seat: options.seat,
+    home: options.home,
+    ...(afterHost === undefined ? {} : { afterHost }),
+    ...(options.hostFacingModel === undefined ? {} : { hostFacingModel: options.hostFacingModel }),
+  });
+  if (!opened.ok) {
     return {
       ok: false,
       missingModelMessage: missingResolvedSeatModelMessage(options.role),
     };
   }
-  const hostName = seatWithModel.host ?? "pi";
-  let hostFacingSelection: RoleTurnModelConfig | undefined = options.hostFacingModel;
-  if (hostFacingSelection === undefined) {
-    const { loadHostProvidersTable, projectHostFacingProvider } = await import(
-      "./public-cli/host-providers.ts"
-    );
-    hostFacingSelection = projectHostFacingProvider(
-      seatWithModel.selection,
-      hostName,
-      loadHostProvidersTable(options.home),
-      options.home,
-    );
-  }
   return {
     ok: true,
     env: {
@@ -324,12 +300,13 @@ async function createSummonEnv(
       agentDir: options.agentDir,
       sessionAppender: appendPiSessionCustomEntry,
       packageRoot: options.packageRoot,
-      roleTurnHost,
+      roleTurnHost: opened.roleTurnHost,
       cwd: options.cwd,
       credentials: options.credentials,
-      ...(hostFacingSelection === undefined ? {} : { model: hostFacingSelection }),
-      ...projectSeatEngine(seatWithModel),
-      ...projectSeatHost(seatWithModel),
+      ...(opened.model === undefined ? {} : { model: opened.model }),
+      ...(opened.engine === undefined ? {} : { engine: opened.engine }),
+      ...(opened.engineModel === undefined ? {} : { engineModel: opened.engineModel }),
+      host: opened.host,
       ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     },
   };
@@ -344,16 +321,14 @@ export async function summonPublicRole(
 ): Promise<PublicSummonResult> {
   const packageRoot = resolveSummonsPackageRoot(options.packageRoot);
   const home = await resolveSummonHome(options);
-  const agentDir =
-    options.agentDir
-    ?? process.env.PI_CODING_AGENT_DIR
-    ?? join(home, ".pi", "agent");
   const {
     loadCredentialProviders,
     loadPublicCliConfig,
     resolveEffectiveSeat,
+    resolvePublicAgentDir,
     validatePublicCliConfigAxes,
   } = await import("./public-cli/config.ts");
+  const agentDir = resolvePublicAgentDir(options.agentDir, home);
   const credentials =
     options.credentials ?? (await loadCredentialProviders(agentDir));
   const config = await loadPublicCliConfig(home);

package/src/role-run-placement.ts

@@ -107,6 +107,11 @@ export function roleRunArtifactsDirectory(runDirectory: string): string {
   return join(runDirectory, "artifacts");
 }
 
+/** Canonical unbound placement: a run directory under `<book>/unbound/runs/`. */
+export function isUnboundRunDirectory(runDirectory: string): boolean {
+  return runDirectory.replaceAll("\\", "/").includes("/unbound/runs/");
+}
+
 /** The placement seam owns creation for both new runs and resumed legacy runs. */
 export function ensureRoleRunDirectory(
   ledgerHome: string,