@akagilnc/pi-workflow-roles 0.1.5357 → 0.1.5368

package/src/public-cli/cli.ts

@@ -4,7 +4,6 @@ import { piDurablePrincipalAuthority } from "../pi/durable-principal.ts";
  * Public ak-role CLI dispatcher (roles / config / layered help / Judge run).
  */
 import { realpath } from "node:fs/promises";
-import { join } from "node:path";
 
 import { packageMachineHome } from "../activation-ledger-topology.ts";
 import {
@@ -26,13 +25,13 @@ import {
   missingResolvedSeatModelMessage,
   parseModelSpec,
   resolveEffectiveSeat,
-  resolvedSeatWithModel,
   savePublicCliConfig,
   setAutoResumeLimit,
   setPersistentSeatConfig,
   setPersistentSeatEngine,
   setPersistentSeatEngineModel,
   setPersistentSeatHost,
+  resolvePublicAgentDir,
   validatePublicCliConfigAxes,
   type CredentialProviders,
   type EffectiveSeat,
@@ -41,7 +40,6 @@ import {
 } from "./config.ts";
 import {
   loadHostProvidersTable,
-  projectHostFacingProvider,
   renderHostProvidersTable,
 } from "./host-providers.ts";
 import { packagedModelParent } from "../packaged-role-registry.ts";
@@ -54,11 +52,10 @@ import {
   type PostAdmissionEnv,
 } from "./post-admission.ts";
 import { appendPiSessionCustomEntry } from "../pi/role-turn-host.ts";
+import { openRoleSeatRuntime } from "./role-seat-runtime.ts";
 import {
-  composeRoleTurnHostAdapters,
   formatHostSelectionFailure,
   HostSelectionError,
-  selectRoleTurnHost,
   type HostSelectionFailure,
   type NamedRoleTurnHostAdapter,
 } from "./role-turn-host-resolution.ts";
@@ -258,54 +255,43 @@ function createRoleEnvironment(
   /** #178: after host selection, before missing-model — structural argv parse once. */
   afterHost?: () => void,
 ) {
-  const role = options.role;
   const extraPiArgs = env.extraPiArgs;
   const timeoutMs = env.timeoutMs;
-
-  // #617/#178/#788/#840: host first, then model; nested child seat selects own host.
-  const hostAdapters = composeRoleTurnHostAdapters(
-    {
+  const opened = openRoleSeatRuntime({
+    resolution: {
       packageRoot: env.packageRoot,
       ...(env.roleTurnHost === undefined ? {} : { roleTurnHost: env.roleTurnHost }),
       ...(env.hostAdapters === undefined ? {} : { hostAdapters: env.hostAdapters }),
       ...(extraPiArgs === undefined ? {} : { extraPiArgs }),
       ...(timeoutMs === undefined ? {} : { timeoutMs }),
     },
-    env.principalAuthority!,
-  );
-  const roleTurnHost = selectRoleTurnHost(hostAdapters, {
-    role,
+    principalAuthority: env.principalAuthority!,
+    role: options.role,
     seat: options.seat,
+    home: options.home,
+    ...(afterHost === undefined ? {} : { afterHost }),
   });
-  // #178: host → argv (afterHost) → missing-model → provider projection.
-  afterHost?.();
-  const seatWithModel = resolvedSeatWithModel(options.seat);
-  if (seatWithModel === undefined) {
+  if (!opened.ok) {
     // Direct CLI has --model; dual remediation is intentional here (#178 / #916).
     throw new CliUsageError(
       missingResolvedSeatModelMessage(options.seat.seat, "invocation-or-config"),
     );
   }
-  const hostFacingSelection = projectHostFacingProvider(
-    seatWithModel.selection,
-    seatWithModel.host,
-    loadHostProvidersTable(options.home),
-    options.home,
-  );
   return {
     home: options.home,
     principalAuthority: env.principalAuthority!,
     agentDir: options.agentDir,
     sessionAppender: appendPiSessionCustomEntry,
     packageRoot: env.packageRoot,
-    roleTurnHost,
-    hostAdapters,
+    roleTurnHost: opened.roleTurnHost,
+    hostAdapters: opened.hostAdapters,
     cwd: options.cwd,
     ...(options.credentials === undefined ? {} : { credentials: options.credentials }),
     ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
-    ...(hostFacingSelection === undefined ? {} : { model: hostFacingSelection }),
-    ...projectSeatEngine(options.seat),
-    ...projectSeatHost(options.seat),
+    ...(opened.model === undefined ? {} : { model: opened.model }),
+    ...(opened.engine === undefined ? {} : { engine: opened.engine }),
+    ...(opened.engineModel === undefined ? {} : { engineModel: opened.engineModel }),
+    host: opened.host,
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
     ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
     ...(options.config?.autoResumeLimit === undefined
@@ -319,6 +305,25 @@ function createRoleEnvironment(
   };
 }
 
+type PublicRoleDispatchParts = {
+  readonly agentDir: string;
+  readonly cwd: string;
+  readonly config: PublicCliConfig;
+  readonly credentials: CredentialProviders;
+};
+
+/** Shared preamble for a new public role command and an explicit resume. */
+async function loadPublicRoleDispatchParts(
+  env: CliEnv,
+  home: string,
+): Promise<PublicRoleDispatchParts> {
+  const agentDir = resolvePublicAgentDir(env.agentDir, home);
+  const cwd = env.cwd ?? process.cwd();
+  const config = await loadAndValidateConfig(home, env.packageRoot);
+  const credentials = env.credentials ?? (await loadCredentialProviders(agentDir));
+  return { agentDir, cwd, config, credentials };
+}
+
 /**
  * #178 single spine: resolve seat → host select → argv parse once → missing-model → run.
  * Keeps host-unregistered ahead of bad argv and missing-model.
@@ -336,15 +341,11 @@ async function dispatchPublicRoleCommand<TParsed>(
     parseOnce: () => TParsed,
   ) => Promise<{ exitCode: number; terminal?: TerminalResult }>,
 ): Promise<CliResult> {
-  const agentDir = resolveAgentDir(env, home);
-  const cwd = env.cwd ?? process.cwd();
-  const config = await loadAndValidateConfig(home, env.packageRoot);
-  const credentials =
-    env.credentials ?? (await loadCredentialProviders(agentDir));
+  const parts = await loadPublicRoleDispatchParts(env, home);
   const seat = resolveEffectiveSeat(
-    config,
+    parts.config,
     role,
-    credentials,
+    parts.credentials,
     invocationFromParsed(parsed),
   );
   let parsedRoleArgv!: TParsed;
@@ -352,7 +353,15 @@ async function dispatchPublicRoleCommand<TParsed>(
     parsed.args,
     createRoleEnvironment(
       env,
-      { role, home, agentDir, cwd, credentials, seat, config },
+      {
+        role,
+        home,
+        agentDir: parts.agentDir,
+        cwd: parts.cwd,
+        credentials: parts.credentials,
+        seat,
+        config: parts.config,
+      },
       () => {
         parsedRoleArgv = parse(parsed.args);
       },
@@ -397,14 +406,6 @@ function resolveHome(env: CliEnv): string {
   return env.home ?? packageMachineHome();
 }
 
-function resolveAgentDir(env: CliEnv, home: string): string {
-  return (
-    env.agentDir ??
-    process.env.PI_CODING_AGENT_DIR ??
-    join(home, ".pi", "agent")
-  );
-}
-
 type ParsedGlobal = {
   command?: string;
   args: string[];
@@ -575,20 +576,6 @@ function requireCallableSeat(
   }
 }
 
-/** Single seat engine axis → run-options projection (#391 E2 / #883). */
-function projectSeatEngine(
-  seat: Readonly<{ engine?: string; engineModel?: string }>,
-): { engine?: string; engineModel?: string } {
-  return pickEngineAxis(seat);
-}
-
-/** Single seat.host → run-options projection (#595 / #617). */
-function projectSeatHost(
-  seat: Readonly<{ host: string }>,
-): { host: string } {
-  return { host: seat.host };
-}
-
 function loadAndValidateConfig(
   home: string,
   packageRoot: string,
@@ -1170,7 +1157,7 @@ export async function runAkRole(
       const config = await loadAndValidateConfig(home, env.packageRoot);
       const credentials =
         env.credentials ??
-        (await loadCredentialProviders(resolveAgentDir(env, home)));
+        (await loadCredentialProviders(resolvePublicAgentDir(env.agentDir, home)));
       const seats = effectiveSeatConfigurations(
         config,
         credentials,
@@ -1219,19 +1206,15 @@ export async function runAkRole(
         runId: resumeRequest.runId,
         authority: env.principalAuthority ?? piDurablePrincipalAuthority,
       };
-      const agentDir = resolveAgentDir(env, home);
-      const cwd = env.cwd ?? process.cwd();
-      const config = await loadAndValidateConfig(home, env.packageRoot);
-      const credentials =
-        env.credentials ?? (await loadCredentialProviders(agentDir));
+      const parts = await loadPublicRoleDispatchParts(env, home);
       const resumeRole = await peekRoleRunRole(home, resumeRequest.runId);
       // Missing durable role keeps the judge seat table. The resume entry
       // itself is one function; it reads the stored run.
       const seatRole = resumeRole ?? "judge";
       const seat = resolveEffectiveSeat(
-        config,
+        parts.config,
         seatRole,
-        credentials,
+        parts.credentials,
         invocationFromParsed(parsed),
       );
       const result = await runPublicInstructionSeatResume(
@@ -1239,11 +1222,11 @@ export async function runAkRole(
         createRoleEnvironment(env, {
           role: seatRole,
           home,
-          agentDir,
-          cwd,
-          credentials,
+          agentDir: parts.agentDir,
+          cwd: parts.cwd,
+          credentials: parts.credentials,
           seat,
-          config,
+          config: parts.config,
         }),
         io,
       );
@@ -1261,9 +1244,20 @@ export async function runAkRole(
         };
         const parentRole = await peekRoleRunRole(home, parentRunId);
         if (parentRole === undefined) break;
-        const parentSeat = resolveEffectiveSeat(config, parentRole, credentials, invocationFromParsed(parsed));
+        const parentSeat = resolveEffectiveSeat(
+          parts.config,
+          parentRole,
+          parts.credentials,
+          invocationFromParsed(parsed),
+        );
         const parentEnv = createRoleEnvironment(env, {
-          role: parentRole, home, agentDir, cwd, credentials, seat: parentSeat, config,
+          role: parentRole,
+          home,
+          agentDir: parts.agentDir,
+          cwd: parts.cwd,
+          credentials: parts.credentials,
+          seat: parentSeat,
+          config: parts.config,
         });
         current = await continueParentAfterChild(parentRunId, current.admitted, parentEnv, io);
       }

package/src/public-cli/config.ts

@@ -835,6 +835,14 @@ export function credentialProvidersFromAuthData(
   };
 }
 
+/**
+ * Public entry agent directory: explicit value, else PI_CODING_AGENT_DIR,
+ * else `<home>/.pi/agent`. CLI and nested summons share this rule.
+ */
+export function resolvePublicAgentDir(explicit: string | undefined, home: string): string {
+  return explicit ?? process.env.PI_CODING_AGENT_DIR ?? join(home, ".pi", "agent");
+}
+
 export async function loadCredentialProviders(
   agentDir: string,
 ): Promise<CredentialProviders> {

package/src/public-cli/instruction-seat-run.ts

@@ -3,7 +3,8 @@
  * Seat differences are composition-root fields. An omitted reviewer lens
  * starts two ordinary single-axis runs here.
  */
-import { dirname, resolve, sep } from "node:path";
+import { dirname, resolve } from "node:path";
+import { isUnboundRunDirectory } from "../role-run-placement.ts";
 import { AUDITOR_DOSSIER_PROMPT } from "../compliance-transport.ts";
 import { bookDirectOfficerRunPointer } from "../archivist-record-pointer.ts";
 import { createPiDoctorAuditor } from "../doctor-auditor.ts";
@@ -24,6 +25,7 @@ import {
   latestQueueStatus,
 } from "../submission-gate.ts";
 import { isSafePositiveTicketNumber, readBoardTicketNumber } from "../run-ticket-number.ts";
+import type { NotarySourceRunLocator } from "../notary-contracts.ts";
 import { NotarySourceRunError, resolveNotarySourceRunLocator } from "../notary-source-run.ts";
 import { engineSessionMaterialFromOptions, pickEngineAxis } from "../package-resources/engine-material.ts";
 import type { PackagedRole } from "../packaged-role-registry.ts";
@@ -33,7 +35,7 @@ import {
   packagedRebindSourceOnResume,
   packagedRoleMetadata,
 } from "../packaged-role-registry.ts";
-import { isAuditorSoulRole, readAuditorResumeBinding } from "../auditor-soul.ts";
+import { readAuditorResumeBinding } from "../auditor-soul.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
   admitPublicRole,
@@ -89,6 +91,7 @@ import {
 } from "./terminal.ts";
 import {
   admittedSeatTurnDetails,
+  projectPublicTurnAxes,
   projectRoleTurnRequest,
   requiredMethodSkills,
   type RoleTurnRequestProjectionOptions,
@@ -455,6 +458,45 @@ async function runOmittedLensBatch(
   return { exitCode: failed ? 1 : 0, terminal };
 }
 
+/**
+ * One same-parent lookup. Seat branches still build their own summons.
+ * A found child resumes that child; no prior run returns undefined so the caller mints.
+ */
+function resumeSameParentInstructionSeat(input: {
+  readonly env: InstructionSeatRunEnv;
+  readonly io: CliIo;
+  readonly projectRoot: string;
+  readonly role: PackagedRole;
+  readonly parentRunPath: string;
+  readonly summons: SameTicketSummonsMaterials;
+  readonly ticketNumber?: number;
+}): Promise<SeatRunResult | undefined> {
+  return tryResumeSameTicketSeatRun({
+    home: input.env.home,
+    projectRoot: input.projectRoot,
+    role: input.role,
+    parentRunPath: input.parentRunPath,
+    ...(input.ticketNumber === undefined ? {} : { ticketNumber: input.ticketNumber }),
+    freshSummons: input.env.freshSummons,
+    summons: input.summons,
+    resume: (runId, materials) => runPublicInstructionSeatResume(
+      { runId, ...(materials === undefined ? {} : { summons: materials }) },
+      input.env,
+      input.io,
+    ),
+  });
+}
+
+/** Re-ask words when the parent supplied them; otherwise the caller's own instruction. */
+function sameParentInstruction(
+  env: InstructionSeatRunEnv,
+  fallback: { readonly instruction: string; readonly instructionEmpty: boolean },
+): { readonly instruction: string; readonly instructionEmpty: boolean } {
+  const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
+  if (resumeInstruction === undefined) return fallback;
+  return { instruction: resumeInstruction, instructionEmpty: false };
+}
+
 /**
  * Countersign on the shared entry: gate parent resume, deferred materialization,
  * then the same one-shot settlement as every other seat.
@@ -470,23 +512,20 @@ async function runCountersignBody(
       : undefined;
   if (gateParentRunPath !== undefined) {
     const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction ?? parsed.instruction ?? "";
-    const resumed = await tryResumeSameTicketSeatRun({
-      home: env.home,
+    const resumed = await resumeSameParentInstructionSeat({
+      env,
+      io,
       projectRoot: resolve(parsed.project ?? env.cwd),
       role: "countersign",
       parentRunPath: gateParentRunPath,
-      ...(isSafePositiveTicketNumber(env.boundTicketNumber) ? { ticketNumber: env.boundTicketNumber } : {}),
-      freshSummons: env.freshSummons,
+      ...(isSafePositiveTicketNumber(env.boundTicketNumber)
+        ? { ticketNumber: env.boundTicketNumber }
+        : {}),
       summons: {
         sourceRunPath: gateParentRunPath,
         instruction: resumeInstruction,
         instructionEmpty: resumeInstruction.trim() === "",
       },
-      resume: (runId, materials) => runPublicInstructionSeatResume(
-        { runId, ...(materials === undefined ? {} : { summons: materials }) },
-        env,
-        io,
-      ),
     });
     if (resumed != null) return resumed;
   }
@@ -521,12 +560,7 @@ async function runCountersignBody(
         admitted = { ...admitted, sourceRunPath: gateParentRunPath };
       }
       const turnProjection: RoleTurnRequestProjectionOptions = {
-        packageRoot: env.packageRoot,
-        home: env.home,
-        agentDir: env.agentDir,
-        ...(env.model === undefined ? {} : { model: env.model }),
-        ...pickEngineAxis(env),
-        ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+        ...projectPublicTurnAxes(env),
         ...(env.correlationId === undefined || env.correlationId.trim() === ""
           ? {}
           : { correlationId: env.correlationId }),
@@ -608,17 +642,18 @@ export async function runPublicInstructionSeat(
   let auditorSubject: "judge" | "doctor" | undefined;
   let auditorSource: string | undefined;
   let auditorTicket: number | undefined;
+  let resolvedNotarySource: NotarySourceRunLocator | undefined;
   if (record.sameParent === "subject-source") {
-    if (!isAuditorSoulRole(parsed.subject)) {
+    if (parsed.subject === undefined) {
       presentStructuralRejection(new CliUsageError("auditor --subject requires judge|doctor"), io);
       return { exitCode: 2 };
     }
     auditorSubject = parsed.subject;
-    const source = typeof parsed.sourceRun === "string" ? parsed.sourceRun.trim() : "";
-    if (source === "") {
+    if (parsed.sourceRun === undefined) {
       presentStructuralRejection(new CliUsageError("auditor --source-run requires a run locator"), io);
       return { exitCode: 2 };
     }
+    const source = parsed.sourceRun;
     try {
       const resolved = await resolveNotarySourceRunLocator({ projectRoot, sourceRun: source, home: env.home });
       auditorSource = resolved.runDirectory;
@@ -629,28 +664,23 @@ export async function runPublicInstructionSeat(
     }
     if (auditorSource === undefined) return { exitCode: 2 };
     const sourceDirectory = auditorSource;
-    const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
     const summons: SameTicketSummonsMaterials = {
-      ...(resumeInstruction === undefined
-        ? { instruction: parsed.instruction ?? "", instructionEmpty: (parsed.instruction ?? "").trim() === "" }
-        : { instruction: resumeInstruction, instructionEmpty: false }),
+      ...sameParentInstruction(env, {
+        instruction: parsed.instruction ?? "",
+        instructionEmpty: (parsed.instruction ?? "").trim() === "",
+      }),
       attachmentPaths: parsed.attachmentPaths ?? [],
     };
     const resumed = await withAuditorSoulEnv({
       subject: auditorSubject,
       sourceRunDirectory: auditorSource,
-      run: () => tryResumeSameTicketSeatRun({
-        home: env.home,
+      run: () => resumeSameParentInstructionSeat({
+        env,
+        io,
         projectRoot,
         role,
         parentRunPath: sourceDirectory,
-        freshSummons: env.freshSummons,
         summons,
-        resume: (runId, materials) => runPublicInstructionSeatResume(
-          { runId, ...(materials === undefined ? {} : { summons: materials }) },
-          env,
-          io,
-        ),
       }),
     });
     if (resumed != null) return resumed;
@@ -659,26 +689,21 @@ export async function runPublicInstructionSeat(
   if (record.sameParent === "gate-pointer") {
     const parentRunPath = parentRunPathFromGatePointerInstruction(parsed.instruction ?? "");
     if (parentRunPath !== undefined) {
-      const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
       const summons: SameTicketSummonsMaterials = {
         sourceRunPath: parentRunPath,
-        ...(resumeInstruction === undefined
-          ? { instruction: parsed.instruction ?? "", instructionEmpty: (parsed.instruction ?? "").trim() === "" }
-          : { instruction: resumeInstruction, instructionEmpty: false }),
+        ...sameParentInstruction(env, {
+          instruction: parsed.instruction ?? "",
+          instructionEmpty: (parsed.instruction ?? "").trim() === "",
+        }),
         attachmentPaths: parsed.attachmentPaths ?? [],
       };
-      const resumed = await tryResumeSameTicketSeatRun({
-        home: env.home,
+      const resumed = await resumeSameParentInstructionSeat({
+        env,
+        io,
         projectRoot,
         role,
         parentRunPath,
-        freshSummons: env.freshSummons,
         summons,
-        resume: (runId, materials) => runPublicInstructionSeatResume(
-          { runId, ...(materials === undefined ? {} : { summons: materials }) },
-          env,
-          io,
-        ),
       });
       if (resumed != null) return resumed;
     }
@@ -703,31 +728,33 @@ export async function runPublicInstructionSeat(
     const summons: SameTicketSummonsMaterials = {
       sourceRunPath: source.runDirectory,
       sourceRun: source,
-      ...(resumeInstruction === undefined ? {} : { instruction: resumeInstruction, instructionEmpty: false }),
+      ...(resumeInstruction === undefined
+        ? {}
+        : { instruction: resumeInstruction, instructionEmpty: false }),
     };
-    const resumed = await tryResumeSameTicketSeatRun({
-      home: env.home,
+    resolvedNotarySource = source;
+    const resumed = await resumeSameParentInstructionSeat({
+      env,
+      io,
       projectRoot,
       role,
       parentRunPath: source.runDirectory,
-      freshSummons: env.freshSummons,
       summons,
-      resume: (runId, materials) => runPublicInstructionSeatResume(
-        { runId, ...(materials === undefined ? {} : { summons: materials }) },
-        env,
-        io,
-      ),
     });
     if (resumed != null) return resumed;
   }
 
   let admitted: AdmittedRoleInvocation;
   try {
+    const admissionOverride = {
+      ...(auditorTicket === undefined ? {} : { assertedTicketNumber: auditorTicket }),
+      ...(resolvedNotarySource === undefined ? {} : { resolvedSourceRun: resolvedNotarySource }),
+    };
     admitted = await admitPublicRole(
       role,
       parsed,
       env,
-      auditorTicket === undefined ? undefined : { assertedTicketNumber: auditorTicket },
+      auditorTicket === undefined && resolvedNotarySource === undefined ? undefined : admissionOverride,
     );
   } catch (error) {
     const rejected = usageExit(error, io);
@@ -764,7 +791,7 @@ export async function runPublicInstructionSeat(
           timedOut: false, code: null, stderr: "", thrown: error,
         }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
       }
-      if (outcome.admitted?.runDirectory.includes(`${sep}unbound${sep}runs${sep}`)) {
+      if (outcome.admitted !== undefined && isUnboundRunDirectory(outcome.admitted.runDirectory)) {
         await recordChildDiaristRun(admitted, outcome.admitted.runId);
       }
       if (outcome.failedWithoutEscalate !== undefined) {