@akagilnc/pi-workflow-roles 0.1.2296 → 0.1.2306

package/src/public-cli/one-shot-dispatch.ts

@@ -0,0 +1,300 @@
+/**
+ * Shared one-shot public Role dispatch seam (Doctor-isomorphic path).
+ * Post-admission lifecycle — mark admitted → writer lease → running → spawn →
+ * settle/fail → terminal → release — lives here once. Role runners supply only
+ * activation args and settlement adapters (ADR 0018 / #448).
+ */
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { applyEngineChildEnv } from "../engine-detour.ts";
+import {
+  runExplicitInternalActivation,
+  type ExplicitInternalKnownFailure,
+  type ExplicitInternalPiRunner,
+  type ExplicitInternalPiResult,
+} from "./explicit-internal.ts";
+import type { CredentialProviders, SeatModelConfig } from "./config.ts";
+import {
+  missingCredentialPreDispatchFailure,
+  postRunMissingCredentialFailure,
+} from "./public-run-credentials.ts";
+import {
+  acquireRunWriterLease,
+  clearTypedProviderHttpObservation,
+  markRunAdmitted,
+  markRunRunning,
+  markRunTerminal,
+  RunWriterLeaseHeldError,
+  type RunWriterLease,
+} from "./run-lifecycle.ts";
+import {
+  classifyPostAdmissionFailure,
+  exitCodeForTerminalOutcome,
+  formatTerminalResult,
+  inspectJudgeSession,
+  presentFailureTerminal,
+  presentStructuralRejection,
+  resolveAuditedRunnerKnownFailure,
+  explicitInternalKnownFailureClassificationInput,
+  settleFailureTerminalResult,
+} from "./settlement.ts";
+import type { CliIo } from "./cli-io.ts";
+import type { AdmittedRoleInvocation } from "./invocation.ts";
+import type { TerminalResult } from "./terminal.ts";
+
+export type OneShotRunEnv = {
+  home: string;
+  agentDir: string;
+  packageRoot: string;
+  cwd: string;
+  correlationId?: string;
+  piRunner?: ExplicitInternalPiRunner;
+  model?: SeatModelConfig;
+  engine?: string;
+  credentials?: CredentialProviders;
+  timeoutMs?: number;
+};
+
+/**
+ * Role-specific settlement hooks. Lifecycle coordination stays in this module.
+ * - Doctor: present only lawful typed outcomes; optional compliance-audit secondary.
+ * - Notary: present any settled terminal (accepted + residual incomplete).
+ */
+export type OneShotSettlementAdapters<A extends AdmittedRoleInvocation> = {
+  trySettle: (admitted: A) => Promise<TerminalResult | undefined>;
+  /** Default true. Doctor sets false-filter via predicate. */
+  shouldPresentSettled?: (terminal: TerminalResult) => boolean;
+  trySettleSecondary?: (admitted: A) => Promise<TerminalResult | undefined>;
+};
+
+async function presentControlledFailure<A extends AdmittedRoleInvocation>(
+  admitted: A,
+  failureInput: {
+    timedOut: boolean;
+    code: number | null;
+    stderr: string;
+    thrown?: unknown;
+    knownFailure?: ExplicitInternalKnownFailure;
+  },
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted: A;
+  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 }),
+  });
+
+  // One-shot roles do 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,
+  };
+}
+
+function presentSecondaryTerminal(terminal: TerminalResult, io: CliIo): void {
+  if (terminal.roleOutcome.kind === "failure") {
+    presentFailureTerminal(terminal, io);
+  } else {
+    io.stdout(formatTerminalResult(terminal));
+  }
+}
+
+async function dispatchAdmittedOneShotRole<A extends AdmittedRoleInvocation>(input: {
+  admitted: A;
+  env: OneShotRunEnv;
+  io: CliIo;
+  extraArgs: string[];
+  lease: RunWriterLease;
+  effectiveEngine?: string;
+  adapters: OneShotSettlementAdapters<A>;
+}): Promise<{
+  exitCode: number;
+  admitted: A;
+  terminal?: TerminalResult;
+}> {
+  const { admitted, env, io, extraArgs, lease, effectiveEngine, adapters } = input;
+  const shouldPresent =
+    adapters.shouldPresentSettled ?? ((_terminal: TerminalResult) => true);
+  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 settled: TerminalResult | undefined;
+    try {
+      settled = await adapters.trySettle(admitted);
+    } catch (error) {
+      return await presentControlledFailure(
+        admitted,
+        {
+          timedOut: false,
+          code: result.code,
+          stderr: result.stderr,
+          thrown: error,
+        },
+        io,
+      );
+    }
+    if (settled !== undefined && shouldPresent(settled)) {
+      await markRunTerminal(admitted.runDirectory).catch(() => undefined);
+      io.stdout(formatTerminalResult(settled));
+      return {
+        exitCode: exitCodeForTerminalOutcome(settled.roleOutcome),
+        admitted,
+        terminal: settled,
+      };
+    }
+
+    if (adapters.trySettleSecondary !== undefined) {
+      const secondary = await adapters.trySettleSecondary(admitted);
+      if (secondary !== undefined) {
+        await markRunTerminal(admitted.runDirectory).catch(() => undefined);
+        presentSecondaryTerminal(secondary, io);
+        return {
+          exitCode: exitCodeForTerminalOutcome(secondary.roleOutcome),
+          admitted,
+          terminal: secondary,
+        };
+      }
+    }
+
+    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();
+  }
+}
+
+/**
+ * Shared post-admission one-shot path: durable admitted mark, writer lease,
+ * then Doctor-isomorphic dispatch. Role runners call this after role-specific admit.
+ */
+export async function runAdmittedOneShotRole<A extends AdmittedRoleInvocation>(input: {
+  admitted: A;
+  env: OneShotRunEnv;
+  io: CliIo;
+  extraArgs: string[];
+  adapters: OneShotSettlementAdapters<A>;
+  effectiveEngine?: string;
+}): Promise<{
+  exitCode: number;
+  admitted: A;
+  terminal?: TerminalResult;
+}> {
+  const { admitted, env, io, extraArgs, adapters, effectiveEngine } = input;
+  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, admitted };
+    }
+    throw error;
+  }
+
+  return await dispatchAdmittedOneShotRole({
+    admitted,
+    env,
+    io,
+    extraArgs,
+    lease,
+    adapters,
+    ...(effectiveEngine === undefined ? {} : { effectiveEngine }),
+  });
+}

package/src/public-cli/option-definitions.ts

@@ -28,6 +28,7 @@ export type OptionOwner =
   | "collector"
   | "doctor"
   | "merger"
+  | "notary"
   | "analyst";
 
 /**
@@ -537,6 +538,24 @@ const DOCTOR_OPTIONS = [
   },
 ] as const satisfies readonly PublicOptionDefinition[];
 
+const NOTARY_OPTIONS = [
+  bindOwner("notary", SHARED_PROJECT_SEMANTICS),
+  {
+    id: "source-run",
+    owner: "notary",
+    canonical: "--source-run",
+    aliases: [],
+    valueMetavar: "runId@role|path",
+    required: true,
+    repeatable: false,
+    form: "option",
+    description: {
+      en: "Required source run locator (runId@role under the book home, or path to that run directory). Zero prompt/attachment projection.",
+      zh: "必填源 run 定位符（簿内 runId@role，或该 run 目录路径）。零 prompt/附件投影。",
+    },
+  },
+] as const satisfies readonly PublicOptionDefinition[];
+
 const MERGER_OPTIONS = [
   // Merger project face differs: requires an in-progress ordinary merge root.
   {
@@ -701,6 +720,7 @@ export const PUBLIC_OPTION_TABLE = {
   collector: COLLECTOR_OPTIONS,
   doctor: DOCTOR_OPTIONS,
   merger: MERGER_OPTIONS,
+  notary: NOTARY_OPTIONS,
   analyst: ANALYST_OPTIONS,
 } as const satisfies Record<OptionOwner, readonly PublicOptionDefinition[]>;
 
@@ -715,6 +735,7 @@ export const PUBLIC_ROLE_OPTION_OWNERS = [
   "collector",
   "doctor",
   "merger",
+  "notary",
   "analyst",
 ] as const satisfies readonly PublicRoleOptionOwner[];
 
@@ -1068,6 +1089,14 @@ const ROLE_COMMAND_HELP = {
       'ak-role merger --project /path/to/worktree "Reconcile the active merge."',
     ],
   },
+  notary: {
+    command: "notary",
+    summary: "Direct Notary document check (quote fidelity + ticket alignment); zero prompt/attachment.",
+    usage: ["ak-role notary --source-run <runId@role|path> [options]"],
+    examples: [
+      "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@judge",
+    ],
+  },
   analyst: {
     command: "analyst",
     summary: "Deterministic analysis seat (issue / sweep / cohort).",

package/src/public-cli/registry.ts

@@ -86,6 +86,10 @@ const STARTUP_CANDIDATES: Record<PublicConfigurableSeat, readonly ModelRef[]> =
     { provider: "openai-codex", model: "gpt-5.6-luna", thinking: "high" },
     { provider: "xai", model: "grok-4.5", thinking: "high" },
   ],
+  notary: [
+    { provider: "openai-codex", model: "gpt-5.6-luna", thinking: "high" },
+    { provider: "xai", model: "grok-4.5", thinking: "high" },
+  ],
   navigator: [
     { provider: "openai-codex", model: "gpt-5.6-luna", thinking: "medium" },
     { provider: "xai", model: "grok-4.5", thinking: "high" },

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

@@ -67,7 +67,8 @@ export type RoleRunRecord = {
     | "collector"
     | "doctor"
     | "reviewer"
-    | "merger";
+    | "merger"
+    | "notary";
   readonly state: RoleRunState;
   readonly bookKey: string;
   readonly projectRoot: string;
@@ -161,7 +162,8 @@ export async function readRoleRunState(
       record.role !== "collector" &&
       record.role !== "doctor" &&
       record.role !== "reviewer" &&
-      record.role !== "merger"
+      record.role !== "merger" &&
+      record.role !== "notary"
     ) {
       return undefined;
     }
@@ -995,6 +997,7 @@ export async function peekRoleRunRole(
   | "doctor"
   | "reviewer"
   | "merger"
+  | "notary"
   | undefined
 > {
   const runDirectory = await findRunDirectoryById(home, runId);

package/src/public-cli/settlement.ts

@@ -74,6 +74,12 @@ import {
   validateMergerOutput,
   type MergerOutput,
 } from "../merger-contracts.ts";
+import {
+  NOTARY_OUTPUT_TOOL_NAME,
+  notaryDecisiveFacts,
+  validateRecordedNotaryOutput,
+  type NotaryOutput,
+} from "../notary-contracts.ts";
 import {
   observePackagedMethodSkillInvocation,
   type ObservedPackagedMethodSkillInvocation,
@@ -98,6 +104,7 @@ import {
   type AdmittedFixerInvocation,
   type AdmittedJudgeInvocation,
   type AdmittedMergerInvocation,
+  type AdmittedNotaryInvocation,
   type AdmittedReviewerInvocation,
   type AdmittedRoleInvocation,
 } from "./invocation.ts";
@@ -3206,6 +3213,100 @@ export async function trySettleDoctorTerminalResult(
   return settleLawfulDoctorTerminalResult(admitted);
 }
 
+/** Lawful Notary accepted outcome (pass/bounce/incomplete-with-reason). */
+export type LawfulNotaryRoleOutcome = {
+  kind: "accepted";
+  role: "notary";
+  status: string;
+  decisiveFacts: Readonly<Record<string, unknown>>;
+};
+
+export function extractNotaryRoleOutcome(
+  entries: readonly SessionEntry[],
+): { outcome: LawfulNotaryRoleOutcome; output: NotaryOutput } | undefined {
+  if (!isReceiptSettlementBindingClear(entries)) return undefined;
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (entry?.type !== "message") continue;
+    const message = entry.message;
+    if (message?.role !== "toolResult") continue;
+    if (message.toolName !== NOTARY_OUTPUT_TOOL_NAME) continue;
+    if (!isAcceptedPackagedRoleTerminalResult(message)) continue;
+    try {
+      const output = validateRecordedNotaryOutput(message.details);
+      const outcome: LawfulNotaryRoleOutcome = {
+        kind: "accepted",
+        role: "notary",
+        status: String(output.status),
+        decisiveFacts: notaryDecisiveFacts(output),
+      };
+      return { output, outcome };
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+async function settleLawfulNotaryTerminalResult(
+  admitted: AdmittedNotaryInvocation,
+): Promise<TerminalResult | undefined> {
+  const entries = await readLawfulSettlementEntries(admitted);
+  if (entries === undefined) return undefined;
+  const extracted = extractNotaryRoleOutcome(entries);
+  if (extracted === undefined) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+      const message = entries[index]?.message;
+      if (message?.role !== "toolResult") continue;
+      const residual = boundErroredToolCandidate(
+        entries,
+        index,
+        message,
+        NOTARY_OUTPUT_TOOL_NAME,
+      );
+      if (residual === undefined) continue;
+      return {
+        roleOutcome: buildResidualIncompleteTerminalOutcome({
+          role: "notary",
+          candidate: residual.candidate,
+          diagnostic: residual.diagnostic,
+        }),
+        navigator: extractNavigatorFact(entries),
+        artifacts: [],
+        runId: admitted.runId,
+      };
+    }
+    return undefined;
+  }
+  const navigator = extractNavigatorFact(entries);
+  return {
+    roleOutcome: extracted.outcome,
+    navigator,
+    artifacts: [],
+    runId: admitted.runId,
+  };
+}
+
+/** Settle a lawful Notary Terminal from the admitted session. */
+export async function settleNotaryTerminalResult(
+  admitted: AdmittedNotaryInvocation,
+): Promise<TerminalResult> {
+  const settled = await settleLawfulNotaryTerminalResult(admitted);
+  if (settled === undefined) {
+    throw new Error(
+      "Notary Role run completed without a lawful typed terminal result",
+    );
+  }
+  return settled;
+}
+
+/** Try to settle a lawful Notary Terminal; undefined only for genuine absence. */
+export async function trySettleNotaryTerminalResult(
+  admitted: AdmittedNotaryInvocation,
+): Promise<TerminalResult | undefined> {
+  return settleLawfulNotaryTerminalResult(admitted);
+}
+
 /** Try to settle a lawful Coder Terminal; undefined only for genuine absence. */
 export async function trySettleCoderTerminalResult(
   admitted: AdmittedCoderInvocation,

package/src/public-cli/terminal.ts

@@ -38,11 +38,12 @@ export type TerminalRoleName =
   | "collector"
   | "doctor"
   | "reviewer"
-  | "merger";
+  | "merger"
+  | "notary";
 
 export type ResidualIncompleteTerminalOutcome = {
   kind: "incomplete";
-  role: "merger" | "collector";
+  role: "merger" | "collector" | "notary";
   status: "incomplete";
   decision: "no-usable-result";
   candidate: unknown;
@@ -130,7 +131,7 @@ export function exitCodeForTerminalOutcome(
 }
 
 export function buildResidualIncompleteTerminalOutcome(input: {
-  role: "merger" | "collector";
+  role: "merger" | "collector" | "notary";
   candidate: unknown;
   diagnostic: string;
 }): ResidualIncompleteTerminalOutcome {

package/src/role-runtime.ts

@@ -45,6 +45,7 @@ import {
 } from "./collector-role.ts";
 import type { ComplianceDecision } from "./compliance-transport.ts";
 import { createDoctorRoleRuntime } from "./doctor-role.ts";
+import { createNotaryRoleRuntime } from "./notary-role.ts";
 import { decorateSettlementWithNavigation, formatNavigatorReport, NAVIGATOR_EVENT_TYPE, navigatorSubjectKey, navigatorUnavailableError, subjectPath, type NavigatorAttendance, type NavigatorEvent, type NavigatorPhase, type NavigatorReport, type NavigatorSettlement, type NavigatorSubjectProvenance, type NavigatorWorkContext } from "./navigator-attendance.ts";
 import {
   buildNavigatorInfrastructureFailureFact,
@@ -377,6 +378,7 @@ type ActivationRuntime = {
   bindReviewerParent(activation: ReviewerActivation): void;
   collector: { activate(context: ExtensionContext, event: { reason: string }): Promise<void> };
   doctor: { activate(): Promise<void> };
+  notary: { activate(): Promise<void> };
   merger(): Promise<void>;
 };
 
@@ -413,6 +415,7 @@ function activationStage(role: PackagedRole, runtime: ActivationRuntime): { id:
     } };
     case "collector": return { id: "load-and-install", run: async () => runtime.collector.activate(runtime.context, runtime.event) };
     case "doctor": return { id: "load-and-install", run: async () => runtime.doctor.activate() };
+    case "notary": return { id: "load-and-install", run: async () => runtime.notary.activate() };
     case "merger": return { id: "prepare-git-and-install", run: async () => runtime.merger() };
   }
 }
@@ -494,6 +497,8 @@ export type RoleRuntimeDependencies = {
   loadCollectorSoul?(): Promise<string>;
   createCollectorTransport?(): CollectorGitHubTransport;
   loadDoctorSoul?(): Promise<string>;
+  loadNotarySoul?(): Promise<string>;
+  loadNotarySourceRun?(path: string): Promise<import("./notary-contracts.ts").NotarySourceRunLocator>;
   loadDoctorCase?(path: string): Promise<import("./doctor-contracts.ts").DoctorCase>;
   loadMergerSoul?(): Promise<string>;
   loadMergerInput?(path: string): Promise<unknown>;
@@ -982,6 +987,16 @@ export function createRoleRuntimeExtension(
       async loadCase(path) { if (!dependencies.loadDoctorCase) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.loadDoctorCase(path); },
       async auditCompliance(options) { if (!dependencies.auditDoctorCompliance) throw new Error("Doctor runtime dependencies are not configured"); return dependencies.auditDoctorCompliance(options); },
     }, hostActions);
+    const notary = createNotaryRoleRuntime(pi, {
+      async loadSoul() {
+        if (!dependencies.loadNotarySoul) throw new Error("Notary runtime dependencies are not configured");
+        return dependencies.loadNotarySoul();
+      },
+      async loadSourceRunLocator(path) {
+        if (!dependencies.loadNotarySourceRun) throw new Error("Notary runtime dependencies are not configured");
+        return dependencies.loadNotarySourceRun(path);
+      },
+    }, hostActions);
     let sessionMergerGitState = dependencies.mergerGitState;
     const merger = createMergerRoleRuntime(pi, {
       async loadSoul() { if (!dependencies.loadMergerSoul) throw new Error("Merger runtime dependencies are not configured"); return dependencies.loadMergerSoul(); },
@@ -1133,6 +1148,7 @@ export function createRoleRuntimeExtension(
         },
         collector,
         doctor,
+        notary,
         merger: async () => {
           if (dependencies.mergerGitState === undefined) {
             sessionMergerGitState = dependencies.createMergerGitState?.(ctx.cwd);

package/src/session-opening-materials.ts

@@ -46,6 +46,7 @@ export const MAIN_ROLE_SESSION_MATERIALS = {
   collector: ["CLAUDE.md", "souls/collector.md"],
   doctor: ["CLAUDE.md", "souls/doctor.md"],
   merger: ["CLAUDE.md", "souls/merger.md"],
+  notary: ["CLAUDE.md", "souls/notary.md"],
   navigator: ["CLAUDE.md", "souls/navigator.md"],
 } as const;