@akagilnc/pi-workflow-roles 0.1.3902 → 0.1.3936

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

@@ -29,7 +29,6 @@ import {
   buildResumeContinuationPrompt,
   type PublicResumeRequest,
 } from "./run-lifecycle.ts";
-import { clearReviewerDispatchRejection } from "./reviewer-dispatch-rejection.ts";
 import {
   presentStructuralRejection,
   readEngineDetourInfrastructureFailure,
@@ -84,7 +83,6 @@ function reviewerAdapters(
   methodMaterial?: PackagedMethodSkillMaterial,
 ): PostAdmissionAdapters<AdmittedReviewerInvocation> {
   return {
-    beforeDispatch: (admitted) => clearReviewerDispatchRejection(admitted.runDirectory),
     trySettle: (admitted, authority, scope) =>
       methodMaterial === undefined
         ? Promise.resolve(undefined)

package/src/public-cli/role-turn-host-resolution.ts

@@ -0,0 +1,122 @@
+/**
+ * One host-adapter table and one seat-keyed selection (#617 / ADR 0082).
+ * Public CLI composition root and nested public summons share this seam —
+ * the selected parent adapter is never a child-host override.
+ */
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import { packagedExternalHostNames } from "../host-descriptions.ts";
+import { createPiRoleTurnHost } from "../pi/role-turn-host.ts";
+import type { EffectiveSeat } from "./config.ts";
+import {
+  observeLaunchedRolePackageIdentity,
+  recordLaunchedPiIdentity,
+  recordLaunchedRolePackageIdentity,
+} from "./invocation.ts";
+import { createLazyProductionExternalHost } from "./load-production-external-host.ts";
+import type { PublicCallableRole } from "./registry.ts";
+
+export type HostSelectionFailure = {
+  readonly kind: "host-unregistered" | "host-model-mismatch";
+  readonly host: string;
+  readonly seat: PublicCallableRole;
+  readonly model: string;
+  readonly registeredHosts: readonly string[];
+};
+
+export function formatHostSelectionFailure(failure: HostSelectionFailure): string {
+  return `${failure.kind}: ${failure.host}; seat=${failure.seat}; model=${failure.model}; registered: ${failure.registeredHosts.join(", ")}`;
+}
+
+export type NamedRoleTurnHostAdapter = {
+  readonly name: string;
+  readonly create: (input: { role: PublicCallableRole; model: EffectiveSeat["selection"] }) =>
+    | { readonly ok: true; readonly host: RoleTurnHost }
+    | { readonly ok: false };
+};
+
+export class HostSelectionError extends Error {
+  constructor(readonly failure: HostSelectionFailure) {
+    super(formatHostSelectionFailure(failure));
+    this.name = "HostSelectionError";
+  }
+}
+
+export type RoleTurnHostResolutionInput = {
+  /** Pi-adapter inject (tests). Not a selected-host override. */
+  readonly roleTurnHost?: RoleTurnHost;
+  /** Composition-root adapter table. When omitted, pi + packaged externals. */
+  readonly hostAdapters?: readonly NamedRoleTurnHostAdapter[];
+  readonly packageRoot: string;
+  readonly extraPiArgs?: readonly string[];
+  readonly timeoutMs?: number;
+};
+
+export function composeRoleTurnHostAdapters(
+  env: RoleTurnHostResolutionInput,
+  principalAuthority: DurablePrincipalAuthority,
+): readonly NamedRoleTurnHostAdapter[] {
+  const piHost = env.roleTurnHost ?? createPiRoleTurnHost({
+    packageRoot: env.packageRoot,
+    principalAuthority,
+    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+    recordLaunchedPiIdentity,
+    recordLaunchedRolePackageIdentity,
+    observeLaunchedRolePackageIdentity,
+  });
+  return env.hostAdapters ?? [
+    { name: "pi", create: () => ({ ok: true as const, host: piHost }) },
+    ...packagedExternalHostNames().map((name) => ({
+      name,
+      create: () => ({
+        ok: true as const,
+        host: createLazyProductionExternalHost({
+          packageRoot: env.packageRoot,
+          hostName: name,
+          principalAuthority,
+        }),
+      }),
+    })),
+  ];
+}
+
+export function selectRoleTurnHost(
+  adapters: readonly NamedRoleTurnHostAdapter[],
+  options: {
+    role: PublicCallableRole;
+    seat: EffectiveSeat;
+  },
+): RoleTurnHost {
+  const hostName = options.seat.host;
+  const adapter = adapters.find((candidate) => candidate.name === hostName);
+  const model = options.seat.selection === undefined
+    ? "unconfigured"
+    : `${options.seat.selection.provider}/${options.seat.selection.model}`;
+  const registeredHosts = adapters.map(({ name }) => name);
+  if (adapter === undefined) {
+    throw new HostSelectionError(
+      { kind: "host-unregistered", host: hostName, seat: options.role, model, registeredHosts },
+    );
+  }
+  const selected = adapter.create({ role: options.role, model: options.seat.selection });
+  if (!selected.ok) {
+    throw new HostSelectionError(
+      { kind: "host-model-mismatch", host: hostName, seat: options.role, model, registeredHosts },
+    );
+  }
+  return selected.host;
+}
+
+export function resolveRoleTurnHost(
+  env: RoleTurnHostResolutionInput,
+  options: {
+    role: PublicCallableRole;
+    seat: EffectiveSeat;
+    principalAuthority: DurablePrincipalAuthority;
+  },
+): RoleTurnHost {
+  return selectRoleTurnHost(
+    composeRoleTurnHostAdapters(env, options.principalAuthority),
+    { role: options.role, seat: options.seat },
+  );
+}

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

@@ -571,14 +571,19 @@ export async function markRunAdmitted(
 }
 
 /**
- * Shared dispatch execution seam: record the effective launch model (initial or
- * resume override) and the authoritative seat engine/host onto invocation.json,
- * then transition to running.
+ * Shared dispatch execution seam: transition to running, then record the
+ * effective launch model (initial or resume override) and the authoritative
+ * seat engine/host onto invocation.json.
  * Role runners must not coordinate lifecycle ledger writes themselves.
  * Engine axis is authoritative here (#617): present string is written; omit/undefined
  * clears any prior engine key so unset-engine + resume does not keep a stale value.
  * (Non-authoritative partial updates still use recordEffectiveInvocationModel directly
  * with `engine: undefined` to preserve.)
+ * Host-page write is deliberately the last step (#840 r9 判词 class 2): this
+ * function is not atomic, and a caller retrying after it throws must not see
+ * the new host already committed while the run-state transition itself never
+ * completed — the run-state write happens first, so any failure past that
+ * point still leaves the prior invocation host in place for the retry.
  */
 export async function markRunRunning(
   runDirectory: string,
@@ -586,13 +591,6 @@ export async function markRunRunning(
   effectiveEngine?: string,
   effectiveHost?: string,
 ): Promise<void> {
-  await recordEffectiveInvocationModel(
-    runDirectory,
-    effectiveModel,
-    // Authoritative seat projection: absent engine ⇒ null (delete).
-    effectiveEngine === undefined ? null : effectiveEngine,
-    effectiveHost,
-  );
   const current = await readRoleRunStateDisk(runDirectory);
   if (current === undefined) {
     throw new Error("cannot mark running: run state missing");
@@ -611,6 +609,13 @@ export async function markRunRunning(
     ...(current.phase === undefined ? {} : { phase: current.phase }),
     ...(current.currentCourt === undefined ? {} : { currentCourt: current.currentCourt }),
   });
+  await recordEffectiveInvocationModel(
+    runDirectory,
+    effectiveModel,
+    // Authoritative seat projection: absent engine ⇒ null (delete).
+    effectiveEngine === undefined ? null : effectiveEngine,
+    effectiveHost,
+  );
 }
 
 /** @deprecated #416: 429-only resumable marker; kept for historical runs. */

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

@@ -31,6 +31,8 @@ export type RoleTurnRequestProjectionOptions = {
   continuation: RoleTurnRequest["continuation"];
   /** #833 resume-with-message court attempt. */
   courtAttemptId?: string;
+  /** Station child role run (#840): omit automatic navigator attendance. */
+  stationChild?: boolean;
 };
 
 export type AdmittedTurnInvocation = {
@@ -74,5 +76,6 @@ export function projectRoleTurnRequest(
     ...(options.courtAttemptId === undefined || options.courtAttemptId.length === 0
       ? {}
       : { courtAttemptId: options.courtAttemptId }),
+    ...(options.stationChild === undefined ? {} : { stationChild: options.stationChild }),
   };
 }

package/src/public-role-summons.ts

@@ -16,6 +16,7 @@ import type { CliIo } from "./public-cli/cli-io.ts";
 import type { CredentialProviders, EffectiveSeat } from "./public-cli/config.ts";
 import type { PublicCallableRole } from "./public-cli/registry.ts";
 import type { RoleTurnHost } from "./host-contracts.ts";
+import type { HostSelectionFailure, NamedRoleTurnHostAdapter } from "./public-cli/role-turn-host-resolution.ts";
 import type { TerminalResult } from "./public-cli/terminal.ts";
 
 /** Env published by the parent activation so nested summons never re-derive root. */
@@ -29,7 +30,8 @@ export type PublicSummonRole =
   | "navigator"
   | "gatekeeper"
   | "judge"
-  | "doctor";
+  | "doctor"
+  | "diarist";
 
 export type PublicSummonRequest = {
   readonly role: PublicSummonRole;
@@ -66,12 +68,19 @@ export type PublicSummonRequest = {
    */
   readonly gateReviewInstruction?: string;
   /**
-   * Offline test inject — same face as public CLI env.roleTurnHost. Production
-   * summons leave this unset and use the seat-resolved host.
+   * Pi-adapter inject (tests). Used only as the `pi` row when composing the
+   * adapter table — never as an override of the child seat's selected host.
    */
   readonly roleTurnHost?: RoleTurnHost;
+  /**
+   * Composition-root adapter table (tests / parent CLI env). Child seat selects
+   * from this table. Production leaves unset and composes the default table.
+   */
+  readonly hostAdapters?: readonly NamedRoleTurnHostAdapter[];
   /** Offline test inject for deterministic run ids (same face as public CLI). */
   readonly createRunId?: () => string;
+  /** Typed ticket number handoff for diarist child run (#840). */
+  readonly boundTicketNumber?: number;
 };
 
 export type PublicSummonResult = {
@@ -81,6 +90,8 @@ export type PublicSummonResult = {
   readonly runDirectory?: string;
   /** Offline diagnostics from nested CLI (structural rejection text). */
   readonly stderr?: string;
+  /** Admitted role invocation from nested run. */
+  readonly admitted?: import("./public-cli/invocation.ts").AdmittedRoleInvocation;
 };
 
 function createCapturingIo(): { io: CliIo; stderrText(): string } {
@@ -167,6 +178,13 @@ 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;
+  const failure = (error as { failure?: HostSelectionFailure }).failure;
+  return failure;
+}
+
 async function createSummonEnv(options: {
   readonly role: PublicCallableRole;
   readonly home: string;
@@ -176,59 +194,30 @@ async function createSummonEnv(options: {
   readonly credentials: CredentialProviders;
   readonly seat: EffectiveSeat;
   readonly extraPiArgs?: readonly string[];
+  readonly roleTurnHost?: RoleTurnHost;
+  readonly hostAdapters?: readonly NamedRoleTurnHostAdapter[];
 }) {
-  const [{ piDurablePrincipalAuthority }, { appendPiSessionCustomEntry, createPiRoleTurnHost }] =
+  const [{ piDurablePrincipalAuthority }, { appendPiSessionCustomEntry }, { resolveRoleTurnHost }] =
     await Promise.all([
       import("./pi/durable-principal.ts"),
       import("./pi/role-turn-host.ts"),
+      import("./public-cli/role-turn-host-resolution.ts"),
     ]);
   const principalAuthority = piDurablePrincipalAuthority;
-  // package root is request-scoped only — never leave process.env residue (#675).
-  const piRecords = {
-    async recordLaunchedPiIdentity(runDirectory: string, identity: unknown) {
-      const { recordLaunchedPiIdentity } = await import("./public-cli/invocation.ts");
-      return recordLaunchedPiIdentity(runDirectory, identity as never);
-    },
-    async recordLaunchedRolePackageIdentity(runDirectory: string, identity: unknown) {
-      const { recordLaunchedRolePackageIdentity } = await import("./public-cli/invocation.ts");
-      return recordLaunchedRolePackageIdentity(runDirectory, identity as never);
-    },
-    async observeLaunchedRolePackageIdentity(root: string, roleEntry: string) {
-      const { observeLaunchedRolePackageIdentity } = await import("./public-cli/invocation.ts");
-      return observeLaunchedRolePackageIdentity(root, roleEntry);
+  // Same host axis table as public CLI (#617 DK-3 / #675 / #840): child seat
+  // selects; injected roleTurnHost is the pi adapter only.
+  const roleTurnHost = resolveRoleTurnHost(
+    {
+      packageRoot: options.packageRoot,
+      ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+      ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
+      ...(options.extraPiArgs === undefined || options.extraPiArgs.length === 0
+        ? {}
+        : { extraPiArgs: options.extraPiArgs }),
     },
-  } as const;
-  const piHost = createPiRoleTurnHost({
-    packageRoot: options.packageRoot,
-    principalAuthority,
-    ...(options.extraPiArgs === undefined || options.extraPiArgs.length === 0
-      ? {}
-      : { extraPiArgs: options.extraPiArgs }),
-    ...piRecords,
-  });
-  // Same host axis table as public CLI (#617 DK-3 / #675 / #729): seat.host is
-  // a description-table key; pi stays the in-process default adapter.
+    { role: options.role, seat: options.seat, principalAuthority },
+  );
   const hostName = options.seat.host ?? "pi";
-  let roleTurnHost = piHost;
-  if (hostName !== "pi") {
-    const { lookupHostFamily } = await import("./host-descriptions.ts");
-    const { createLazyProductionExternalHost } = await import(
-      "./public-cli/load-production-external-host.ts"
-    );
-    // #729 / #645: description tables are the sole host authority — family
-    // dispatch (ACP vs headless) is data-driven. Unregistered keys fail closed.
-    if (lookupHostFamily(hostName) === undefined) {
-      throw new Error(
-        `public role summons host unregistered: host=${hostName} seat=${options.role}`,
-      );
-    }
-    // Same lazy external host face as public CLI (#820) — one builder, two callers.
-    roleTurnHost = createLazyProductionExternalHost({
-      packageRoot: options.packageRoot,
-      hostName,
-      principalAuthority,
-    });
-  }
   // #788: host is registered above; only then project host-facing provider.
   const { loadHostProvidersTable, projectHostFacingProvider } = await import(
     "./public-cli/host-providers.ts"
@@ -281,8 +270,9 @@ export async function summonPublicRole(
   // Nested summons resolve host on the officer seat only (flag>seat>default pi).
   // Parent run host is not an override channel (#821 / ADR 0082 host-flag-two-channels).
   const seat = resolveEffectiveSeat(config, options.role, credentials);
-  const env = {
-    ...(await createSummonEnv({
+  let summonEnv;
+  try {
+    summonEnv = await createSummonEnv({
       role: options.role,
       home,
       agentDir,
@@ -291,7 +281,21 @@ export async function summonPublicRole(
       credentials,
       seat,
       ...(options.extraPiArgs === undefined ? {} : { extraPiArgs: options.extraPiArgs }),
-    })),
+      ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+      ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
+    });
+  } catch (error) {
+    const failure = hostSelectionFailureFromUnknown(error);
+    if (failure !== undefined) {
+      const { formatHostSelectionFailure } = await import("./public-cli/role-turn-host-resolution.ts");
+      return { exitCode: 1, stderr: formatHostSelectionFailure(failure) };
+    }
+    throw error;
+  }
+  const env = {
+    ...summonEnv,
+    // Station child role run (#840): omit automatic navigator attendance.
+    stationChild: true,
     // Host config passthrough only — same face as public CLI (#422 / #675).
     ...(config.autoResumeLimit === undefined
       ? {}
@@ -304,8 +308,10 @@ export async function summonPublicRole(
     ...(options.gateReviewInstruction === undefined
       ? {}
       : { gateReviewInstruction: options.gateReviewInstruction }),
-    // Offline test injects — same faces as public CLI env (production leaves unset).
-    ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+    ...(options.boundTicketNumber === undefined
+      ? {}
+      : { boundTicketNumber: options.boundTicketNumber }),
+    // createRunId is the only remaining env overlay — host is seat-selected above.
     ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   };
   const captured = options.io === undefined ? createCapturingIo() : undefined;
@@ -391,6 +397,14 @@ export async function summonPublicRole(
       result = await runPublicDoctor(options.argv, env, io, parseDoctorArgv);
       break;
     }
+    case "diarist": {
+      const [{ runPublicDiarist }, { parseDiaristArgv }] = await Promise.all([
+        import("./public-cli/diarist-run.ts"),
+        import("./public-cli/invocation.ts"),
+      ]);
+      result = await runPublicDiarist(options.argv, env, io, parseDiaristArgv);
+      break;
+    }
   }
 
   const stderr = captured?.stderrText();
@@ -398,6 +412,7 @@ export async function summonPublicRole(
   return {
     exitCode: result.exitCode,
     ...(result.terminal === undefined ? {} : { terminal: result.terminal }),
+    ...(result.admitted === undefined ? {} : { admitted: result.admitted as import("./public-cli/invocation.ts").AdmittedRoleInvocation }),
     ...(typeof runDirectory === "string" && runDirectory.trim() !== ""
       ? { runDirectory }
       : {}),
@@ -426,8 +441,9 @@ export async function summonGateOfficer(options: {
    * when reask is absent (#786). Never a path pointer substitute.
    */
   readonly submission?: unknown;
-  /** Offline test inject — forwarded to summonPublicRole. */
+  /** Pi-adapter inject — forwarded to summonPublicRole (not a parent-host override). */
   readonly roleTurnHost?: RoleTurnHost;
+  readonly hostAdapters?: readonly NamedRoleTurnHostAdapter[];
   /** Offline test inject — forwarded to summonPublicRole. */
   readonly createRunId?: () => string;
 }): Promise<PublicSummonResult> {
@@ -459,6 +475,7 @@ export async function summonGateOfficer(options: {
       ? {}
       : { gateReviewInstruction }),
     ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+    ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
     ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   } as const;
   if (options.officer === "notary") {

package/src/role-activation-flags.ts

@@ -10,6 +10,9 @@ import { packagedRoleInputFlag, packagedRolePhaseFlag } from "./packaged-role-re
 export function projectActivationFlags(request: RoleTurnRequest): Map<string, boolean | string> {
   const activation = request.activation;
   const flags = new Map<string, boolean | string>([["ak-role", activation.role]]);
+  if (request.stationChild === true) {
+    flags.set("ak-station-child", true);
+  }
   const inputFlag = packagedRoleInputFlag(activation.role);
   const phaseFlag = packagedRolePhaseFlag(activation.role);
   if ("phase" in activation && phaseFlag !== undefined) flags.set(phaseFlag, activation.phase);

package/src/role-runtime.ts

@@ -175,6 +175,14 @@ const GLEANER_LEFT_TRANSPORT_FLAGS = Object.freeze([
   }),
 ] as const);
 
+export const STATION_CHILD_FLAG = Object.freeze({
+  name: "ak-station-child",
+  definition: Object.freeze({
+    description: "Station-child role run (omit automatic navigator attendance; #840)",
+    type: "boolean" as const,
+  }),
+} as const);
+
 /**
  * Decode private transport flags into frozen admitted inputs.
  * Envelope-owned; necessary JSON decode only (public --authority-ref owns grammar).
@@ -1152,6 +1160,8 @@ export function createRoleRuntimeExtension(
     for (const flag of COLLECTOR_TRANSPORT_FLAGS) {
       roleHost.registerFlag(flag.name, flag.definition);
     }
+    // Station-child identity (#840): omit navigator attendance. One flag.
+    roleHost.registerFlag(STATION_CHILD_FLAG.name, STATION_CHILD_FLAG.definition);
 
     let admitted = false;
     let selectedRole: string | undefined;
@@ -2003,13 +2013,15 @@ export function createRoleRuntimeExtension(
         const ledgerHome = resolveActivationLedgerHomeForPath(sessionFile);
         const session = durableSessionPointer(ctx.sessionManager);
 
-        // Same public activation face for every role (#675 / owner 09-06): no nested-env
-        // skip, no work-role whitelist. Attendance attaches when the envelope supplies it.
+        // Station children (court diarist, inner-gate summons) omit navigator sidecar (#840).
+        // Top-level public entry legs still attend automatically.
         // Navigator seat never re-attaches itself — prepare turns already ARE the navigator
         // public activation (prevents summonPublicRole navigator ↔ attendance recursion).
+        const isStationChild = roleHost.getFlag(STATION_CHILD_FLAG.name) === true;
         if (
           dependencies.createNavigatorAttendance !== undefined
           && entry.role !== "navigator"
+          && !isStationChild
         ) {
           let work: NavigatorWorkContext;
           let contextError: unknown;

package/src/session-identity.ts

@@ -2,6 +2,11 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import type { DurablePrincipal, DurablePrincipalAuthority } from "./host-contracts.ts";
+import {
+  DEFAULT_ROLE_TURN_HOST,
+  lookupHeadlessHostDescription,
+  lookupHostDescription,
+} from "./host-descriptions.ts";
 import type { SessionIdentityAuthority } from "./prepared-role-turn.ts";
 
 /** Durable session binding stored beside the host-owned session principal. */
@@ -36,3 +41,32 @@ export function createSessionIdentityAuthority(
     },
   };
 }
+
+/**
+ * Host-aware resumable-session probe (#840 P1). The shared auto-resume loop
+ * (public-cli/auto-resume.ts) asks one question — "can this principal's turn
+ * still be resumed" — without itself knowing which concrete host executed it.
+ * Pi's own session.jsonl transcript (DurablePrincipalAuthority#isAvailable)
+ * answers that only for the pi host; ACP and headless hosts persist their
+ * resumable native session id under their own session-identity binding file
+ * instead (#729 / #731 / #645) and never write session.jsonl, so the plain
+ * pi check always reports them unavailable after one attempt. One lookup per
+ * registered host family — no per-host-name branch, no per-seat whitelist.
+ */
+export function resolveHostAwareSessionAvailability(
+  host: string | undefined,
+  principalAuthority: DurablePrincipalAuthority,
+): (principal: DurablePrincipal) => Promise<boolean> {
+  if (host === undefined || host === DEFAULT_ROLE_TURN_HOST) {
+    return (principal) => principalAuthority.isAvailable(principal);
+  }
+  const description = lookupHostDescription(host) ?? lookupHeadlessHostDescription(host);
+  if (description === undefined) {
+    // Host selection already fails closed on an unregistered name (#510) long
+    // before a turn dispatches; mirror the same fail-closed default here
+    // rather than guessing at pi's binding for a name pi does not own.
+    return () => Promise.resolve(false);
+  }
+  const sessionIdentity = createSessionIdentityAuthority(principalAuthority, description.sessionBindingFile);
+  return async (principal) => (await sessionIdentity.load(principal)) !== undefined;
+}