@akagilnc/pi-workflow-roles 0.1.3262 → 0.1.3280

package/src/public-cli/config.ts

@@ -7,10 +7,8 @@ import { dirname, join } from "node:path";
 import { assertLegalEngineName } from "../package-resources/engine-material.ts";
 import { resolveConfiguredProvinceOfficer } from "../institutional-resolution.ts";
 import {
-  AUTOMATIC_CONFIGURABLE_SEATS,
   PUBLIC_CALLABLE_ROLES,
   PUBLIC_CONFIGURABLE_SEATS,
-  isAutomaticConfigurableSeat,
   isPublicCallableRole,
   isPublicConfigurableSeat,
   seatModelOnly,
@@ -87,8 +85,6 @@ export type HostSource = "invocation" | "persistent" | "default";
 
 export type EffectiveSeat = {
   seat: PublicConfigurableSeat;
-  /** True when the seat is automatic (no caller command) rather than caller-selected. */
-  automatic: boolean;
   source: EffectiveSource;
   selection?: SeatModelConfig;
   /** Selected engine name when configured; undefined = no engine (default path). */
@@ -240,7 +236,7 @@ export function setPersistentSeatHost(
  * First engine still requires an existing seat row (model, or residual axes).
  * Clearing engine from an axis-only residual drops the empty row; clearing
  * engine from a model+engine row leaves model-only. Seat type is PublicCallableRole
- * (navigator excluded at the type boundary).
+ * (same as PublicConfigurableSeat; navigator included since #639).
  */
 export function setPersistentSeatEngine(
   config: PublicCliConfig,
@@ -308,8 +304,8 @@ export function setAutoResumeLimit(
 /**
  * Config-parse seam: persistent call axes belong to PUBLIC_CALLABLE_ROLES;
  * engine names need only path-safety syntax (no closed material catalog;
- * #376 / #378 / #391 / ADR 0069). Disk-handwritten automatic-seat axes are
- * rejected. Syntax authority = assertLegalEngineName (no injected duplicate).
+ * #376 / #378 / #391 / ADR 0069). Syntax authority = assertLegalEngineName
+ * (no injected duplicate).
  */
 export function validatePublicCliConfigAxes(
   config: PublicCliConfig,
@@ -317,11 +313,6 @@ export function validatePublicCliConfigAxes(
 ): void {
   for (const seat of Object.keys(config.seats) as PublicConfigurableSeat[]) {
     const row = config.seats[seat];
-    if ((row?.engine !== undefined || row?.host !== undefined) && !isPublicCallableRole(seat)) {
-      throw new Error(
-        `config seat ${seat} cannot persist call axes: no independent activation path; storing would be silently ineffective`,
-      );
-    }
     if (row?.engine === undefined) continue;
     try {
       assertLegalEngineName(row.engine);
@@ -622,13 +613,11 @@ function resolveBaseSeat(
   seat: PublicConfigurableSeat,
   credentials: CredentialProviders,
 ): UnhostedEffectiveSeat {
-  const automatic = isAutomaticConfigurableSeat(seat);
   // #620: subordinate officers consume institutional-resolution authority result.
   if (seat === "notary" || seat === "inspector") {
     const resolved = resolveConfiguredProvinceOfficer(config, seat);
     return {
       seat,
-      automatic,
       source: resolved.source,
       ...(resolved.selection === undefined ? {} : { selection: resolved.selection }),
       engineSource: "unconfigured",
@@ -639,7 +628,6 @@ function resolveBaseSeat(
   if (persistentModel !== undefined) {
     return {
       seat,
-      automatic,
       source: "persistent",
       selection: persistentModel,
       engineSource: "unconfigured",
@@ -649,13 +637,12 @@ function resolveBaseSeat(
   if (startup !== undefined) {
     return {
       seat,
-      automatic,
       source: "startup",
       selection: startup,
       engineSource: "unconfigured",
     };
   }
-  return { seat, automatic, source: "unconfigured", engineSource: "unconfigured" };
+  return { seat, source: "unconfigured", engineSource: "unconfigured" };
 }
 
 export function resolveEffectiveSeat(
@@ -664,7 +651,6 @@ export function resolveEffectiveSeat(
   credentials: CredentialProviders,
   invocation?: InvocationModelOverride,
 ): EffectiveSeat {
-  const automatic = isAutomaticConfigurableSeat(seat);
   const hasModelInvocation =
     invocation !== undefined &&
     (invocation.model !== undefined || invocation.thinking !== undefined);
@@ -679,7 +665,6 @@ export function resolveEffectiveSeat(
         : `${invocation.model}:${invocation.thinking}`;
     modelSeat = {
       seat,
-      automatic,
       source: "invocation",
       selection: parseModelSpec(spec),
       engineSource: "unconfigured",
@@ -689,14 +674,12 @@ export function resolveEffectiveSeat(
     if (base.selection === undefined || invocation.thinking === undefined) {
       modelSeat = {
         seat,
-        automatic,
         source: "unconfigured",
         engineSource: "unconfigured",
       };
     } else {
       modelSeat = {
         seat,
-        automatic,
         source: "invocation",
         selection: { ...base.selection, thinking: invocation.thinking },
         engineSource: "unconfigured",
@@ -717,20 +700,13 @@ export function effectiveSeatConfigurations(
   );
 }
 
-/** Callable roles first (package order), then automatic configurable seats. */
+/** Callable roles in package order. */
 export function listRolesForDisplay(
   config: PublicCliConfig,
   credentials: CredentialProviders,
   invocation?: InvocationModelOverride,
 ): EffectiveSeat[] {
-  const all = effectiveSeatConfigurations(config, credentials, invocation);
-  const callable = PUBLIC_CALLABLE_ROLES.map(
-    (role) => all.find((entry) => entry.seat === role)!,
-  );
-  const automatic = AUTOMATIC_CONFIGURABLE_SEATS.map(
-    (seat) => all.find((entry) => entry.seat === seat)!,
-  );
-  return [...callable, ...automatic];
+  return effectiveSeatConfigurations(config, credentials, invocation);
 }
 
 /**

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

@@ -0,0 +1,147 @@
+/**
+ * Shared instruction-seat run (#639 repair seam): gatekeeper and navigator are
+ * the same admit → turn-request → post-admission → settle shape, parameterized
+ * by seat. Same direction as the settlement one-shot shared skeleton. cli.ts
+ * calls this parameterized module directly; no per-seat wrappers.
+ */
+import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contracts.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import {
+  admitGatekeeperInvocation,
+  admitNavigatorInvocation,
+  buildInstructionTransportPrompt,
+  type AdmittedGatekeeperInvocation,
+  type AdmittedNavigatorInvocation,
+  type ParseInstructionArgvResult,
+} from "./invocation.ts";
+import {
+  runPostAdmissionOneShot,
+  type PostAdmissionEnv,
+} from "./post-admission.ts";
+import {
+  markRunAdmitted,
+} from "./run-lifecycle.ts";
+import {
+  presentStructuralRejection,
+  trySettleGatekeeperTerminalResult,
+  trySettleNavigatorTerminalResult,
+} from "./settlement.ts";
+import type { CliIo } from "./cli-io.ts";
+import type { TerminalResult } from "./terminal.ts";
+import {
+  projectRoleTurnRequest,
+  type RoleTurnRequestProjectionOptions,
+} from "./turn-request.ts";
+
+export type InstructionSeatRole = "gatekeeper" | "navigator";
+
+export type AdmittedInstructionSeatInvocation =
+  | AdmittedGatekeeperInvocation
+  | AdmittedNavigatorInvocation;
+
+export type InstructionSeatRunEnv = PostAdmissionEnv & {
+  principalAuthority: DurablePrincipalAuthority;
+  createRunId?: () => string;
+};
+
+/** Project an admitted instruction-seat invocation onto the host-neutral turn request. */
+export function buildInstructionSeatTurnRequest(
+  admitted: AdmittedInstructionSeatInvocation,
+  options: RoleTurnRequestProjectionOptions,
+): RoleTurnRequest {
+  return projectRoleTurnRequest(
+    admitted,
+    {
+      activation: {
+        role: admitted.role,
+      },
+    },
+    options,
+  );
+}
+
+function instructionSeatAdapters() {
+  return {
+    trySettle: (
+      admitted: AdmittedInstructionSeatInvocation,
+      authority: DurablePrincipalAuthority,
+    ) =>
+      admitted.role === "gatekeeper"
+        ? trySettleGatekeeperTerminalResult(admitted, authority)
+        : trySettleNavigatorTerminalResult(admitted, authority),
+    // Accepted receipts and failure terminals both present via shared path.
+    shouldPresentSettled: () => true,
+  };
+}
+
+export async function runPublicInstructionSeat(
+  argv: readonly string[],
+  env: InstructionSeatRunEnv,
+  io: CliIo,
+  role: InstructionSeatRole,
+  parseArgv: (args: readonly string[]) => ParseInstructionArgvResult,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedInstructionSeatInvocation;
+  terminal?: TerminalResult;
+}> {
+  let admitted: AdmittedInstructionSeatInvocation;
+  try {
+    const parsed = parseArgv(argv);
+    const options = {
+      home: env.home,
+      principalAuthority: env.principalAuthority,
+      cwd: env.cwd,
+      instruction: parsed.instruction,
+      attachmentPaths: parsed.attachmentPaths,
+      ...(parsed.project === undefined ? {} : { project: parsed.project }),
+      ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
+      ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+    };
+    admitted =
+      role === "gatekeeper"
+        ? await admitGatekeeperInvocation(options)
+        : await admitNavigatorInvocation(options);
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  await markRunAdmitted(admitted, env.principalAuthority);
+
+  const turnRequest = buildInstructionSeatTurnRequest(admitted, {
+    packageRoot: env.packageRoot,
+    home: env.home,
+    agentDir: env.agentDir,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.engine === undefined ? {} : { engine: env.engine }),
+    ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+    ...(env.correlationId === undefined || env.correlationId.trim() === ""
+      ? {}
+      : { correlationId: env.correlationId }),
+    continuation: {
+      kind: "initial",
+      prompt: buildInstructionTransportPrompt(
+        admitted,
+        engineSessionMaterialFromOptions({
+          ...(env.engine === undefined ? {} : { engine: env.engine }),
+          packageRoot: env.packageRoot,
+        }),
+      ),
+    },
+  });
+
+  return await runPostAdmissionOneShot({
+    admitted,
+    env,
+    io,
+    request: turnRequest,
+    adapters: instructionSeatAdapters(),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}

package/src/public-cli/invocation.ts

@@ -136,6 +136,14 @@ export type AdmittedInspectorInvocation = AdmittedRoleInvocationBase & {
   readonly role: "inspector";
 };
 
+export type AdmittedGatekeeperInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "gatekeeper";
+};
+
+export type AdmittedNavigatorInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "navigator";
+};
+
 export type CoderPhase = "plan" | "apply";
 
 export type AdmittedCoderInvocation = AdmittedRoleInvocationBase & {
@@ -217,6 +225,8 @@ export type AdmittedRoleInvocation =
   | AdmittedCountersignInvocation
   | AdmittedGleanerLeftInvocation
   | AdmittedInspectorInvocation
+  | AdmittedGatekeeperInvocation
+  | AdmittedNavigatorInvocation
   | AdmittedCoderInvocation
   | AdmittedFixerInvocation
   | AdmittedCollectorInvocation
@@ -535,6 +545,8 @@ export type ParseInstructionArgvResult = {
 export type ParseJudgeArgvResult = ParseInstructionArgvResult;
 export type ParseCountersignArgvResult = ParseInstructionArgvResult;
 export type ParseInspectorArgvResult = ParseInstructionArgvResult;
+export type ParseGatekeeperArgvResult = ParseInstructionArgvResult;
+export type ParseNavigatorArgvResult = ParseInstructionArgvResult;
 
 /** Positive ticket number shared by countersign/notary/analyst faces. */
 export function parsePositiveTicketNumber(
@@ -555,7 +567,7 @@ export function parsePositiveTicketNumber(
 /** 共享解析体：同形 owner 的 argv → instruction/attachments/project。 */
 function parseInstructionArgv(
   args: readonly string[],
-  owner: "judge" | "countersign" | "inspector",
+  owner: "judge" | "countersign" | "inspector" | "gatekeeper" | "navigator",
 ): ParseInstructionArgvResult {
   const attachmentPaths: string[] = [];
   let project: string | undefined;
@@ -799,6 +811,14 @@ export function parseInspectorArgv(args: readonly string[]): ParseInspectorArgvR
   return parseInstructionArgv(args, "inspector");
 }
 
+export function parseGatekeeperArgv(args: readonly string[]): ParseGatekeeperArgvResult {
+  return parseInstructionArgv(args, "gatekeeper");
+}
+
+export function parseNavigatorArgv(args: readonly string[]): ParseNavigatorArgvResult {
+  return parseInstructionArgv(args, "navigator");
+}
+
 /**
  * Parse Coder-specific argv after the `coder` token.
  * Phase defaults to apply; spellings from PUBLIC_OPTION_TABLE.coder (#342).
@@ -988,6 +1008,9 @@ export type AdmitInspectorInvocationOptions = AdmitJudgeInvocationOptions & {
   correlationId?: string;
 };
 
+export type AdmitGatekeeperInvocationOptions = AdmitInspectorInvocationOptions;
+export type AdmitNavigatorInvocationOptions = AdmitInspectorInvocationOptions;
+
 /**
  * Shared instruction-seat admission for Judge and Inspector: project check,
  * principal/placement issue, attachment freeze, ticket extract, admitted-request
@@ -995,7 +1018,7 @@ export type AdmitInspectorInvocationOptions = AdmitJudgeInvocationOptions & {
  * (Inspector). Countersign keeps its own path for ticket-override specialty.
  */
 async function admitStandardMaterialInvocation<
-  R extends "judge" | "inspector",
+  R extends "judge" | "inspector" | "gatekeeper" | "navigator",
 >(
   role: R,
   options: AdmitJudgeInvocationOptions & { correlationId?: string },
@@ -1101,8 +1124,28 @@ export async function admitInspectorInvocation(
   return admitStandardMaterialInvocation("inspector", options);
 }
 
+/**
+ * Admit a direct Gatekeeper (门下省) run (#639): freeze attachments, persist
+ * the request, reserve session placement — same instruction-seat face.
+ */
+export async function admitGatekeeperInvocation(
+  options: AdmitGatekeeperInvocationOptions,
+): Promise<AdmittedGatekeeperInvocation> {
+  return admitStandardMaterialInvocation("gatekeeper", options);
+}
+
+/**
+ * Admit a direct Navigator (游奕使) run (#639): freeze attachments, persist
+ * the request, reserve session placement — same instruction-seat face.
+ */
+export async function admitNavigatorInvocation(
+  options: AdmitNavigatorInvocationOptions,
+): Promise<AdmittedNavigatorInvocation> {
+  return admitStandardMaterialInvocation("navigator", options);
+}
+
 /** Shared prompt transport for instruction-seat roles (judge/countersign/inspector). */
-function buildInstructionTransportPrompt(
+export function buildInstructionTransportPrompt(
   admitted: { instruction: string; instructionEmpty: boolean; attachments: readonly { frozenPath: string }[] },
   engineMaterial?: EngineSessionMaterial,
 ): string {
@@ -1132,6 +1175,7 @@ export function buildInspectorTransportPrompt(
   return buildInstructionTransportPrompt(admitted, engineMaterial);
 }
 
+
 export type AdmitCountersignInvocationOptions = {
   home: string;
   cwd: string;

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

@@ -32,6 +32,8 @@ export type OptionOwner =
   | "notary"
   | "gleaner-left"
   | "inspector"
+  | "gatekeeper"
+  | "navigator"
   | "analyst";
 
 /**
@@ -410,6 +412,16 @@ const INSPECTOR_OPTIONS = [
   bindOwner("inspector", SHARED_ATTACH_SEMANTICS),
 ] as const satisfies readonly PublicOptionDefinition[];
 
+const GATEKEEPER_OPTIONS = [
+  bindOwner("gatekeeper", SHARED_PROJECT_SEMANTICS),
+  bindOwner("gatekeeper", SHARED_ATTACH_SEMANTICS),
+] as const satisfies readonly PublicOptionDefinition[];
+
+const NAVIGATOR_OPTIONS = [
+  bindOwner("navigator", SHARED_PROJECT_SEMANTICS),
+  bindOwner("navigator", SHARED_ATTACH_SEMANTICS),
+] as const satisfies readonly PublicOptionDefinition[];
+
 const COUNTERSIGN_OPTIONS = [
   bindOwner("countersign", SHARED_PROJECT_SEMANTICS),
   bindOwner("countersign", SHARED_ATTACH_SEMANTICS),
@@ -798,6 +810,8 @@ export const PUBLIC_OPTION_TABLE = {
   merger: MERGER_OPTIONS,
   notary: NOTARY_OPTIONS,
   inspector: INSPECTOR_OPTIONS,
+  gatekeeper: GATEKEEPER_OPTIONS,
+  navigator: NAVIGATOR_OPTIONS,
   analyst: ANALYST_OPTIONS,
 } as const satisfies Record<OptionOwner, readonly PublicOptionDefinition[]>;
 
@@ -816,6 +830,8 @@ export const PUBLIC_ROLE_OPTION_OWNERS = [
   "merger",
   "notary",
   "inspector",
+  "gatekeeper",
+  "navigator",
   "analyst",
 ] as const satisfies readonly PublicRoleOptionOwner[];
 
@@ -1089,11 +1105,12 @@ export type PublicCommandHelpFacts = {
 };
 
 /**
- * Top-level public help short note for automatic Navigator attendance.
- * Not a caller command; configure via `ak-role config set navigator …`.
+ * Top-level public help short note for Navigator automatic attendance (#639:
+ * attendance is orthogonal to callability — the direct command face lives on
+ * the role list like every other role).
  */
 export const PUBLIC_NAVIGATOR_HELP_NOTE =
-  "Navigator attends automatically on every run; configure with `ak-role config set navigator <provider/model[:thinking]>` (not a caller command)." as const;
+  "Navigator also attends automatically on every run; that sidecar is unchanged by direct `ak-role navigator` calls." as const;
 
 const TOP_LEVEL_HELP = {
   command: "top",
@@ -1196,6 +1213,22 @@ const ROLE_COMMAND_HELP = {
       'ak-role inspector --attach ./change.patch "Review this material."',
     ],
   },
+  gatekeeper: {
+    command: "gatekeeper",
+    summary: "Direct Gatekeeper (门下省) review: dispatch an officer or pass.",
+    usage: ["ak-role gatekeeper [options] [instruction]"],
+    examples: [
+      'ak-role gatekeeper --attach ./submission.json "审：这批材料该谁审？"',
+    ],
+  },
+  navigator: {
+    command: "navigator",
+    summary: "Direct Navigator (游奕使) route advice: ordered next-role candidates.",
+    usage: ["ak-role navigator [options] [instruction]"],
+    examples: [
+      'ak-role navigator "刚完成 coder apply 收敛，下一步？"',
+    ],
+  },
   notary: {
     command: "notary",
     summary: "Direct Notary document check (quote fidelity + ticket alignment); zero prompt/attachment.",

package/src/public-cli/registry.ts

@@ -16,36 +16,12 @@ export const PUBLIC_CALLABLE_ROLES = PACKAGED_ROLE_REGISTRY.map(
 
 export type PublicCallableRole = (typeof PUBLIC_CALLABLE_ROLES)[number];
 
-/** Automatic attendance seat — configurable, never a caller-selected command. */
-export const AUTOMATIC_NAVIGATOR_SEAT = "navigator" as const;
-
-/** Automatic province seat — configurable model only; never a caller command. */
-export const AUTOMATIC_GATEKEEPER_SEAT = "gatekeeper" as const;
-
-/** Automatic-only configurable seats. Inspector remains automatic-capable via its callable seat. */
-export const AUTOMATIC_CONFIGURABLE_SEATS = [
-  AUTOMATIC_GATEKEEPER_SEAT,
-  AUTOMATIC_NAVIGATOR_SEAT,
-] as const;
-
-export type AutomaticConfigurableSeat =
-  (typeof AUTOMATIC_CONFIGURABLE_SEATS)[number];
-
-export type PublicConfigurableSeat =
-  | PublicCallableRole
-  | AutomaticConfigurableSeat;
+export type PublicConfigurableSeat = PublicCallableRole;
 
 export const PUBLIC_CONFIGURABLE_SEATS = [
   ...PUBLIC_CALLABLE_ROLES,
-  ...AUTOMATIC_CONFIGURABLE_SEATS,
 ] as const satisfies readonly PublicConfigurableSeat[];
 
-export function isAutomaticConfigurableSeat(
-  value: string,
-): value is AutomaticConfigurableSeat {
-  return (AUTOMATIC_CONFIGURABLE_SEATS as readonly string[]).includes(value);
-}
-
 export const PUBLIC_CLI_SUPPORT_COMMANDS = [
   "roles",
   "config",
@@ -127,7 +103,8 @@ const STARTUP_CANDIDATES: Record<PublicConfigurableSeat, readonly ModelRef[]> =
   ],
   // #620: subordinate officers inherit gatekeeper; no package startup model.
   notary: [],
-  // #453/#620: gatekeeper unset inherits audited session (province path only).
+  // #453/#620/#639: gatekeeper callable but no package startup model — caller
+  // configures it or the institutional resolution applies on the province path.
   gatekeeper: [],
   inspector: [],
   navigator: [

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

@@ -84,7 +84,9 @@ export type RoleRunRecord = {
     | "notary"
     | "countersign"
     | "gleaner-left"
-    | "inspector";
+    | "inspector"
+    | "gatekeeper"
+    | "navigator";
   readonly state: RoleRunState;
   readonly bookKey: string;
   readonly projectRoot: string;
@@ -244,7 +246,9 @@ async function readRoleRunStateDisk(
     record.role !== "notary" &&
     record.role !== "countersign" &&
     record.role !== "gleaner-left" &&
-    record.role !== "inspector"
+    record.role !== "inspector" &&
+    record.role !== "gatekeeper" &&
+    record.role !== "navigator"
   ) {
     return undefined;
   }
@@ -1475,6 +1479,8 @@ export async function peekRoleRunRole(
   | "countersign"
   | "gleaner-left"
   | "inspector"
+  | "gatekeeper"
+  | "navigator"
   | undefined
 > {
   const runDirectory = await findRunDirectoryById(home, runId);