@akagilnc/pi-workflow-roles 0.1.2296 → 0.1.2306

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

@@ -1,19 +1,9 @@
 /**
- * Public Doctor Role run: admit Issue → retained case via #78 → explicit
- * Internal activate → settle Terminal result (#113). One-shot; no resume path.
- * Failure settlement reuses the #107 shared owner.
+ * Public Doctor Role run: admit Issue → retained case via #78 → shared one-shot
+ * dispatch → settle Terminal result (#113). Lifecycle is the shared
+ * Doctor-isomorphic seam; this module keeps only Doctor adapters.
  */
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
-import { applyEngineChildEnv } from "../engine-detour.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
-import {
-  runExplicitInternalActivation,
-  type ExplicitInternalKnownFailure,
-  type ExplicitInternalPiRunner,
-  type ExplicitInternalPiResult,
-} from "./explicit-internal.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
   admitDoctorInvocation,
@@ -23,59 +13,28 @@ import {
 } from "./invocation.ts";
 import {
   buildSeatModelCliArgs,
-  type CredentialProviders,
   type SeatModelConfig,
 } from "./config.ts";
 import {
-  missingCredentialPreDispatchFailure,
-  postRunMissingCredentialFailure,
-} from "./public-run-credentials.ts";
+  runAdmittedOneShotRole,
+  type OneShotRunEnv,
+} from "./one-shot-dispatch.ts";
 import {
-  acquireRunWriterLease,
-  clearTypedProviderHttpObservation,
-  markRunAdmitted,
-  markRunRunning,
-  markRunTerminal,
-  RunWriterLeaseHeldError,
-  type RunWriterLease,
-} from "./run-lifecycle.ts";
-import {
-  classifyPostAdmissionFailure,
-  exitCodeForTerminalOutcome,
-  formatTerminalResult,
-  inspectJudgeSession,
-  isLawfulTypedTerminalOutcome,
-  presentFailureTerminal,
   presentStructuralRejection,
-  resolveAuditedRunnerKnownFailure,
-  explicitInternalKnownFailureClassificationInput,
-  settleFailureTerminalResult,
-  trySettleDoctorTerminalResult,
   trySettleComplianceAuditIncompleteTerminalResult,
+  trySettleDoctorTerminalResult,
 } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
-import type {
-  ControlledFailureCause,
-  TerminalResult,
+import {
+  isLawfulTypedTerminalOutcome,
+  type TerminalResult,
 } from "./terminal.ts";
 
-export type DoctorRunEnv = {
-  home: string;
-  agentDir: string;
-  packageRoot: string;
-  cwd: string;
-  correlationId?: string;
-  piRunner?: ExplicitInternalPiRunner;
-  model?: SeatModelConfig;
-  /** Optional labor engine name (config→activation; session material + env signal). */
-  engine?: string;
-  credentials?: CredentialProviders;
+export type DoctorRunEnv = OneShotRunEnv & {
   createRunId?: () => string;
   extraPiArgs?: readonly string[];
-  timeoutMs?: number;
 };
 
-
 /**
  * Build Internal activation extra-args for an admitted Doctor run.
  * Always --no-skills (Doctor forbids every Skill). Session under #78 book.
@@ -115,189 +74,6 @@ export function buildDoctorActivationExtraArgs(
   ];
 }
 
-async function presentControlledFailure(
-  admitted: AdmittedDoctorInvocation,
-  failureInput: {
-    timedOut: boolean;
-    code: number | null;
-    stderr: string;
-    thrown?: unknown;
-    knownFailure?: ExplicitInternalKnownFailure;
-  },
-  io: CliIo,
-): Promise<{
-  exitCode: number;
-  admitted: AdmittedDoctorInvocation;
-  terminal: TerminalResult;
-}> {
-  const hasThrown = Object.hasOwn(failureInput, "thrown");
-  const session =
-    !hasThrown &&
-    !failureInput.timedOut &&
-    failureInput.knownFailure === undefined
-      ? await inspectJudgeSession(admitted.sessionFile)
-      : undefined;
-  const failure = classifyPostAdmissionFailure({
-    timedOut: failureInput.timedOut,
-    code: failureInput.code,
-    stderr: failureInput.stderr,
-    ...(hasThrown ? { thrown: failureInput.thrown } : {}),
-    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
-    ...(session === undefined ? {} : { session }),
-  });
-
-  // Doctor does not support resume — always terminal.
-  await markRunTerminal(admitted.runDirectory).catch(() => undefined);
-
-  const terminal = await settleFailureTerminalResult(admitted, failure);
-  presentFailureTerminal(terminal, io);
-  return {
-    exitCode: exitCodeForTerminalOutcome(terminal.roleOutcome),
-    admitted,
-    terminal,
-  };
-}
-
-async function dispatchAdmittedDoctor(input: {
-  admitted: AdmittedDoctorInvocation;
-  env: DoctorRunEnv;
-  io: CliIo;
-  extraArgs: string[];
-  lease: RunWriterLease;
-  effectiveEngine?: string;
-}): Promise<{
-  exitCode: number;
-  admitted: AdmittedDoctorInvocation;
-  terminal?: TerminalResult;
-}> {
-  const { admitted, env, io, extraArgs, lease, effectiveEngine } = input;
-  try {
-    const missingCredential = missingCredentialPreDispatchFailure(
-      env.model,
-      env.credentials,
-    );
-    if (missingCredential !== undefined) {
-      return await presentControlledFailure(
-        admitted,
-        missingCredential,
-        io,
-      );
-    }
-    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
-    await clearTypedProviderHttpObservation(admitted.runDirectory);
-
-    const childEnv: NodeJS.ProcessEnv = {
-      ...process.env,
-      HOME: env.home,
-      PI_CODING_AGENT_DIR: env.agentDir,
-      AK_ROLE_RUN_DIR: admitted.runDirectory,
-    };
-    applyEngineChildEnv(childEnv, env.engine);
-    if (env.correlationId !== undefined && env.correlationId.trim() !== "") {
-      childEnv.AK_CORRELATION_ID = env.correlationId;
-    }
-
-    let result: ExplicitInternalPiResult;
-    try {
-      result = await runExplicitInternalActivation({
-        packageRoot: env.packageRoot,
-        extraArgs,
-        cwd: admitted.projectRoot,
-        home: env.home,
-        agentDir: env.agentDir,
-        env: childEnv,
-        timeoutMs: env.timeoutMs,
-        ...(env.piRunner === undefined ? {} : { runner: env.piRunner }),
-      });
-    } catch (error) {
-      return await presentControlledFailure(
-        admitted,
-        {
-          timedOut: false,
-          code: null,
-          stderr: "",
-          thrown: error,
-        },
-        io,
-      );
-    }
-
-    try {
-      await writeFile(
-        join(admitted.runDirectory, "stderr.log"),
-        result.stderr,
-        "utf8",
-      );
-    } catch {
-      // continue to lawful / controlled-failure settlement
-    }
-
-    let lawful: TerminalResult | undefined;
-    try {
-      lawful = await trySettleDoctorTerminalResult(admitted);
-    } catch (error) {
-      return await presentControlledFailure(
-        admitted,
-        {
-          timedOut: false,
-          code: result.code,
-          stderr: result.stderr,
-          thrown: error,
-        },
-        io,
-      );
-    }
-    if (lawful !== undefined && isLawfulTypedTerminalOutcome(lawful.roleOutcome)) {
-      await markRunTerminal(admitted.runDirectory).catch(() => undefined);
-      io.stdout(formatTerminalResult(lawful));
-      return {
-        exitCode: exitCodeForTerminalOutcome(lawful.roleOutcome),
-        admitted,
-        terminal: lawful,
-      };
-    }
-
-    const auditIncomplete = await trySettleComplianceAuditIncompleteTerminalResult(admitted);
-    if (auditIncomplete !== undefined) {
-      await markRunTerminal(admitted.runDirectory).catch(() => undefined);
-      if (auditIncomplete.roleOutcome.kind === "failure") {
-        presentFailureTerminal(auditIncomplete, io);
-      } else {
-        io.stdout(formatTerminalResult(auditIncomplete));
-      }
-      return {
-        exitCode: exitCodeForTerminalOutcome(auditIncomplete.roleOutcome),
-        admitted,
-        terminal: auditIncomplete,
-      };
-    }
-
-    const credentialFailure = postRunMissingCredentialFailure(
-      result,
-      env.model,
-      env.credentials,
-    );
-    const knownFailure = await resolveAuditedRunnerKnownFailure({
-      runner: result.knownFailure,
-      sessionFile: admitted.sessionFile,
-      credential: credentialFailure,
-      runDirectory: admitted.runDirectory,
-    });
-    return await presentControlledFailure(
-      admitted,
-      {
-        timedOut: result.timedOut,
-        code: result.code,
-        stderr: result.stderr,
-        ...(knownFailure === undefined ? {} : { knownFailure }),
-      },
-      io,
-    );
-  } finally {
-    await lease.release();
-  }
-}
-
 export async function runPublicDoctor(
   argv: readonly string[],
   env: DoctorRunEnv,
@@ -330,19 +106,6 @@ export async function runPublicDoctor(
     throw error;
   }
 
-  await markRunAdmitted(admitted);
-
-  let lease: RunWriterLease;
-  try {
-    lease = await acquireRunWriterLease(admitted.runDirectory, (diagnostic) => io.stderr(diagnostic));
-  } catch (error) {
-    if (error instanceof RunWriterLeaseHeldError) {
-      presentStructuralRejection(error, io);
-      return { exitCode: 2 };
-    }
-    throw error;
-  }
-
   const extraArgs = buildDoctorActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...(env.model === undefined ? {} : { model: env.model }),
@@ -350,12 +113,17 @@ export async function runPublicDoctor(
     ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
   });
 
-  return await dispatchAdmittedDoctor({
+  return await runAdmittedOneShotRole({
     admitted,
     env,
     io,
     extraArgs,
-    lease,
+    adapters: {
+      trySettle: trySettleDoctorTerminalResult,
+      shouldPresentSettled: (terminal) =>
+        isLawfulTypedTerminalOutcome(terminal.roleOutcome),
+      trySettleSecondary: trySettleComplianceAuditIncompleteTerminalResult,
+    },
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }

package/src/public-cli/invocation.ts

@@ -47,6 +47,14 @@ import {
 } from "../merger-contracts.ts";
 import { sha256Hex } from "../sha256.ts";
 import { uuidv7 } from "../uuidv7.ts";
+import {
+  NOTARY_FIXED_KICKOFF,
+  type NotarySourceRunLocator,
+} from "../notary-contracts.ts";
+import {
+  NotarySourceRunError,
+  resolveNotarySourceRunLocator,
+} from "../notary-source-run.ts";
 import {
   appendEngineSessionMaterial,
   type EngineSessionMaterial,
@@ -143,6 +151,14 @@ export type AdmittedDoctorInvocation = AdmittedRoleInvocationBase & {
   readonly caseIdentity: DoctorCaseIdentity;
 };
 
+export type AdmittedNotaryInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "notary";
+  /** Absolute source run directory passed to internal --ak-notary-source-run. */
+  readonly sourceRunPath: string;
+  /** Typed locator identity bound at admission (self-fetch target). */
+  readonly sourceRun: NotarySourceRunLocator;
+};
+
 export type AdmittedReviewerInvocation = AdmittedRoleInvocationBase & {
   readonly role: "reviewer";
   /** Required fixed base revision for the pinned review target (ADR 0037). */
@@ -177,6 +193,7 @@ export type AdmittedRoleInvocation =
   | AdmittedFixerInvocation
   | AdmittedCollectorInvocation
   | AdmittedDoctorInvocation
+  | AdmittedNotaryInvocation
   | AdmittedReviewerInvocation
   | AdmittedMergerInvocation;
 
@@ -1742,6 +1759,159 @@ export function buildDoctorTransportPrompt(
   return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 
+export type ParseNotaryArgvResult = {
+  readonly sourceRun: string;
+  readonly project?: string;
+};
+
+/**
+ * Parse Notary-specific argv after the `notary` token.
+ * Input contract = zero prompt, zero attachment projection (#448 / #276).
+ */
+export function parseNotaryArgv(args: readonly string[]): ParseNotaryArgvResult {
+  let project: string | undefined;
+  let sourceRun: string | undefined;
+  const tokens = [...args];
+  const definitions = roleOptions("notary");
+  const options = createTypedOptionConsumer(definitions);
+
+  while (tokens.length > 0) {
+    if (tokens[0] === "--") {
+      tokens.shift();
+      if (tokens.length > 0) {
+        throw new CliUsageError(
+          "notary rejects caller prompt/instruction; only --source-run locator is admitted",
+        );
+      }
+      break;
+    }
+    const taken = options.takeDashed(tokens);
+    if (taken !== undefined) {
+      if (taken.def.id === "project") {
+        project = requireOptionPath(taken.def.canonical, taken.value);
+        continue;
+      }
+      if (taken.def.id === "source-run") {
+        if (taken.value === undefined || taken.value.trim() === "") {
+          throw new CliUsageError("notary --source-run requires a run locator");
+        }
+        sourceRun = taken.value;
+        continue;
+      }
+      throw new CliUsageError(`unknown notary option: ${taken.def.canonical}`);
+    }
+    const token = tokens.shift()!;
+    if (token.startsWith("-") && token !== "-") {
+      throw new CliUsageError(`unknown notary option: ${token}`);
+    }
+    throw new CliUsageError(
+      "notary rejects caller prompt/instruction; only --source-run locator is admitted",
+    );
+  }
+
+  options.assertRequired();
+  if (sourceRun === undefined || sourceRun.trim() === "") {
+    throw new CliUsageError("notary --source-run requires a run locator");
+  }
+  return {
+    sourceRun,
+    ...(project === undefined ? {} : { project }),
+  };
+}
+
+export async function admitNotaryInvocation(options: {
+  readonly home: string;
+  readonly cwd: string;
+  readonly sourceRun: string;
+  readonly project?: string;
+  readonly runs?: string;
+  readonly createRunId?: () => string;
+  readonly model?: InvocationEffectiveModel;
+  readonly correlationId?: string;
+}): Promise<AdmittedNotaryInvocation> {
+  if (options.project !== undefined) {
+    requireOptionPath("--project", options.project);
+  }
+  const projectRoot = resolve(options.project ?? options.cwd);
+  let sourceRun: NotarySourceRunLocator;
+  try {
+    sourceRun = await resolveNotarySourceRunLocator({
+      projectRoot,
+      sourceRun: options.sourceRun,
+      home: options.home,
+    });
+  } catch (error) {
+    if (error instanceof NotarySourceRunError) {
+      throw new CliUsageError(error.message, { cause: error });
+    }
+    throw error;
+  }
+
+  const runId = options.createRunId?.() ?? uuidv7();
+  const { ledgerHome, bookKey, runDirectory, sessionDirectory, sessionFile } =
+    roleRunSessionCoordinates({
+      cwd: projectRoot,
+      runId,
+      role: "notary",
+      home: options.home,
+    });
+  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+
+  const admitted = {
+    role: "notary" as const,
+    runId,
+    bookKey,
+    projectRoot,
+    runDirectory,
+    sessionDirectory,
+    sessionFile,
+    instruction: "",
+    instructionEmpty: true,
+    attachments: [] as const,
+    sourceRunPath: sourceRun.runDirectory,
+    sourceRun,
+    ...(options.correlationId === undefined
+      ? {}
+      : { correlationId: options.correlationId }),
+  };
+  const admittedRequestPath = join(runDirectory, "admitted-request.json");
+  await writeFile(
+    admittedRequestPath,
+    `${JSON.stringify(admitted, null, 2)}\n`,
+    "utf8",
+  );
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
+
+  return {
+    role: "notary",
+    runId,
+    bookKey,
+    projectRoot,
+    instruction: "",
+    instructionEmpty: true,
+    attachments: [],
+    runDirectory,
+    sessionDirectory,
+    sessionFile,
+    admittedRequestPath,
+    sourceRunPath: sourceRun.runDirectory,
+    sourceRun,
+    ...(options.correlationId === undefined
+      ? {}
+      : { correlationId: options.correlationId }),
+  };
+}
+
+/** Package-owned fixed kickoff only — never caller instruction/attachments. */
+export function buildNotaryTransportPrompt(
+  _admitted: AdmittedNotaryInvocation,
+  engineMaterial?: EngineSessionMaterial,
+): string {
+  return appendEngineSessionMaterial([NOTARY_FIXED_KICKOFF], engineMaterial).join(
+    "\n",
+  );
+}
+
 /**
  * Parse Reviewer-specific argv after the `reviewer` token.
  * Public flags: --project, required --base, optional repeatable --authority-ref.

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

@@ -0,0 +1,117 @@
+/**
+ * Public Notary Role run: admit source-run locator → shared one-shot dispatch
+ * → settle Terminal result (#448). Zero caller prompt/attachment. Lifecycle is
+ * the shared Doctor-isomorphic seam; this module keeps only Notary adapters.
+ */
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import {
+  admitNotaryInvocation,
+  buildNotaryTransportPrompt,
+  type AdmittedNotaryInvocation,
+  type ParseNotaryArgvResult,
+} from "./invocation.ts";
+import {
+  buildSeatModelCliArgs,
+  type SeatModelConfig,
+} from "./config.ts";
+import {
+  runAdmittedOneShotRole,
+  type OneShotRunEnv,
+} from "./one-shot-dispatch.ts";
+import {
+  presentStructuralRejection,
+  trySettleNotaryTerminalResult,
+} from "./settlement.ts";
+import type { CliIo } from "./cli-io.ts";
+import type { TerminalResult } from "./terminal.ts";
+
+export type NotaryRunEnv = OneShotRunEnv & {
+  createRunId?: () => string;
+  extraPiArgs?: readonly string[];
+};
+
+export function buildNotaryActivationExtraArgs(
+  admitted: AdmittedNotaryInvocation,
+  options: {
+    model?: SeatModelConfig;
+    engine?: string;
+    packageRoot?: string;
+    extraPiArgs?: readonly string[];
+  } = {},
+): string[] {
+  const prompt = buildNotaryTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options),
+  );
+  return [
+    "--no-skills",
+    "--no-prompt-templates",
+    "--no-themes",
+    "--no-context-files",
+    "--session",
+    admitted.sessionFile,
+    "--session-dir",
+    admitted.sessionDirectory,
+    ...(options.extraPiArgs ?? []),
+    "--ak-role",
+    "notary",
+    "--ak-notary-source-run",
+    admitted.sourceRunPath,
+    "--mode",
+    "json",
+    ...buildSeatModelCliArgs(options.model),
+    prompt,
+  ];
+}
+
+export async function runPublicNotary(
+  argv: readonly string[],
+  env: NotaryRunEnv,
+  io: CliIo,
+  parseNotaryArgv: (args: readonly string[]) => ParseNotaryArgvResult,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedNotaryInvocation;
+  terminal?: TerminalResult;
+}> {
+  let admitted: AdmittedNotaryInvocation;
+  try {
+    const parsed = parseNotaryArgv(argv);
+    admitted = await admitNotaryInvocation({
+      home: env.home,
+      cwd: env.cwd,
+      sourceRun: parsed.sourceRun,
+      ...(parsed.project === undefined ? {} : { project: parsed.project }),
+      ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
+      ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+    });
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  const extraArgs = buildNotaryActivationExtraArgs(admitted, {
+    packageRoot: env.packageRoot,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
+    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+  });
+
+  return await runAdmittedOneShotRole({
+    admitted,
+    env,
+    io,
+    extraArgs,
+    adapters: {
+      trySettle: trySettleNotaryTerminalResult,
+      // Accepted receipts and residual incomplete share one present path.
+      shouldPresentSettled: () => true,
+    },
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}