@akagilnc/pi-workflow-roles 0.1.2026 → 0.1.2041

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2026",
+  "version": "0.1.2041",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/compliance-transport.ts

@@ -7,6 +7,7 @@ import {
 } from "./evidence-child-executor.ts";
 import { createAuditorDossierTool } from "./auditor-dossier-tool.ts";
 import type { DossierObservation } from "./dossier-resolution.ts";
+import { withPackageOwnedToolIdleSuspended } from "./package-owned-tool-idle.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 
 export type ComplianceCompletion = AuditorCompletion;
@@ -116,24 +117,28 @@ export type RunComplianceAuditOptions = {
 };
 
 export async function runComplianceAudit(options: RunComplianceAuditOptions): Promise<ComplianceDecision> {
-  const prompt = options.serializedInput ?? AUDITOR_DOSSIER_PROMPT;
-  const receipt = await executeAuditorChild({
-    tool: options.tool,
-    dossierTool: createAuditorDossierTool(options.runDirectory),
-    systemPrompt: options.systemPrompt,
-    prompt,
-    roleLabel: options.roleLabel,
-    context: options.context,
-    retainResponse: (response) => retainComplianceResponse(options.context, response),
-    ...(options.runCompletion === undefined ? {} : { runCompletion: options.runCompletion }),
-    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  // #339: only the real compliance-audit await leaves the outer package-owned
+  // idle owner. Pre/post-audit work stays under the single outer backstop.
+  return withPackageOwnedToolIdleSuspended(async () => {
+    const prompt = options.serializedInput ?? AUDITOR_DOSSIER_PROMPT;
+    const receipt = await executeAuditorChild({
+      tool: options.tool,
+      dossierTool: createAuditorDossierTool(options.runDirectory),
+      systemPrompt: options.systemPrompt,
+      prompt,
+      roleLabel: options.roleLabel,
+      context: options.context,
+      retainResponse: (response) => retainComplianceResponse(options.context, response),
+      ...(options.runCompletion === undefined ? {} : { runCompletion: options.runCompletion }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (receipt.noReceiptLifecycle !== undefined) {
+      return {
+        status: "no-receipt",
+        ...receipt.noReceiptLifecycle,
+        ...(receipt.response.usage === undefined ? {} : { usage: receipt.response.usage }),
+      };
+    }
+    return readComplianceCandidate(receipt.decision, receipt.response.usage);
   });
-  if (receipt.noReceiptLifecycle !== undefined) {
-    return {
-      status: "no-receipt",
-      ...receipt.noReceiptLifecycle,
-      ...(receipt.response.usage === undefined ? {} : { usage: receipt.response.usage }),
-    };
-  }
-  return readComplianceCandidate(receipt.decision, receipt.response.usage);
 }

package/src/evidence-child-executor.ts

@@ -381,6 +381,10 @@ export async function createInheritedRuntime(options: InheritedRuntimeOptions):
     };
 
   runtime.registerNativeProvider(provider);
+  // registerNativeProvider fires a background refresh; await it so child
+  // AgentSession.prompt sees configured auth without racing void refresh
+  // (mock timers / slow CI otherwise stall before the compliance stream).
+  await runtime.refresh({ allowNetwork: false });
   return state;
 }
 

package/src/package-owned-tool-idle.ts

@@ -5,12 +5,18 @@
  * Real producing onUpdate resets; final resolve/reject clears; timeout throws so
  * Pi settles the current call as an LLM-visible isError tool result. No retry,
  * role failure, process termination, signal abort, config, or Pi built-in coverage.
+ *
+ * #339: do not name-exempt whole terminating tools. Outer idle stays armed for
+ * pre/post-audit work. Only the real compliance-audit await suspends this single
+ * layer (ADR 0059 owns that interval); resume re-arms the same outer backstop.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 
 import {
   DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   createStreamIdleGuard,
+  type StreamIdleGuard,
 } from "./stream-idle-guard.ts";
 import { isProducingToolUpdate } from "./tool-execution-observation.ts";
 
@@ -19,6 +25,17 @@ export const PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE = "AK_PACKAGE_OWNED_TOOL_IDLE_
 
 const WRAPPED = Symbol.for("ak.packageOwnedToolIdleWrapped");
 
+type PackageOwnedToolIdleSuspension = {
+  suspend(): void;
+  resume(): void;
+};
+
+/**
+ * Active outer package-owned execute idle, if any. Nested tool executes install
+ * their own store; compliance audit only suspends the store visible at await time.
+ */
+const packageOwnedToolIdleScope = new AsyncLocalStorage<PackageOwnedToolIdleSuspension>();
+
 export class PackageOwnedToolIdleTimeoutError extends Error {
   readonly code = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE;
   readonly idleTimeoutMs = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS;
@@ -52,6 +69,24 @@ function isPackageOwnedToolActivityUpdate(partialResult: unknown): boolean {
   return true;
 }
 
+/**
+ * #339: suspend the active package-owned execute idle for one real compliance
+ * audit await. Single-layer only — production has one runComplianceAudit seam.
+ * No-op outside a wrapped package-owned execute. No second timeout or retry.
+ */
+export async function withPackageOwnedToolIdleSuspended<T>(
+  run: () => Promise<T>,
+): Promise<T> {
+  const scope = packageOwnedToolIdleScope.getStore();
+  if (scope === undefined) return run();
+  scope.suspend();
+  try {
+    return await run();
+  } finally {
+    scope.resume();
+  }
+}
+
 /**
  * Single shared execute wrapper for package-owned tool definitions.
  * Idempotent: wrapping twice returns the same protected definition.
@@ -72,7 +107,8 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
     const onUpdate = args[3] as ((partialResult: unknown) => void) | undefined;
     return new Promise((resolve, reject) => {
       let settled = false;
-      const idle = createStreamIdleGuard({
+      let suspended = false;
+      let idle: StreamIdleGuard = createStreamIdleGuard({
         idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
       });
 
@@ -88,6 +124,25 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
       };
       idle.signal.addEventListener("abort", onIdle, { once: true });
 
+      const suspension: PackageOwnedToolIdleSuspension = {
+        suspend(): void {
+          if (settled || suspended) return;
+          suspended = true;
+          // ADR 0059 owns the audit interval — drop this layer until audit returns.
+          idle.signal.removeEventListener("abort", onIdle);
+          idle.dispose();
+        },
+        resume(): void {
+          if (settled || !suspended) return;
+          suspended = false;
+          // Fresh single-layer silence window for post-audit work (e.g. cleanup).
+          idle = createStreamIdleGuard({
+            idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
+          });
+          idle.signal.addEventListener("abort", onIdle, { once: true });
+        },
+      };
+
       const guardedOnUpdate = onUpdate === undefined
         ? undefined
         : (partialResult: unknown) => {
@@ -101,12 +156,14 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
       callArgs[2] = signal;
       callArgs[3] = guardedOnUpdate;
 
-      void Promise.resolve()
-        .then(() => originalExecute(...callArgs))
-        .then(
-          (result) => settle(() => resolve(result)),
-          (error: unknown) => settle(() => reject(error)),
-        );
+      void packageOwnedToolIdleScope.run(suspension, async () => {
+        try {
+          const result = await originalExecute(...callArgs);
+          settle(() => resolve(result));
+        } catch (error) {
+          settle(() => reject(error));
+        }
+      });
     });
   };
   (wrappedExecute as { [WRAPPED]?: boolean })[WRAPPED] = true;

package/src/public-cli/cli.ts

@@ -34,6 +34,14 @@ import {
   parseReviewerArgv,
   parseTaishiArgv,
 } from "./invocation.ts";
+import {
+  createTypedOptionConsumer,
+  optionsForOwner,
+  projectOwnerOptions,
+  renderOwnerOptionHelpLines,
+  type PublicOptionDefinition,
+  type TypedOptionConsumer,
+} from "./option-definitions.ts";
 import { runPublicCoder, runPublicCoderResume } from "./coder-run.ts";
 import { runPublicCollector } from "./collector-run.ts";
 import { runPublicDoctor } from "./doctor-run.ts";
@@ -64,21 +72,25 @@ export { CliUsageError } from "./cli-errors.ts";
 export type { CliIo } from "./cli-io.ts";
 
 /**
- * Sole production map: public role command → argv parser.
- * cli handlers consume this table; no parallel set.
+ * Sole production map: public role command → argv parser + option definitions.
+ * cli handlers and help consume this table; no parallel spelling set (#342).
  */
 export const PUBLIC_ROLE_ARGV = {
-  judge: { parse: parseJudgeArgv },
-  coder: { parse: parseCoderArgv },
-  fixer: { parse: parseFixerArgv },
-  collector: { parse: parseCollectorArgv },
-  doctor: { parse: parseDoctorArgv },
-  merger: { parse: parseMergerArgv },
-  reviewer: { parse: parseReviewerArgv },
+  judge: { parse: parseJudgeArgv, options: optionsForOwner("judge") },
+  coder: { parse: parseCoderArgv, options: optionsForOwner("coder") },
+  fixer: { parse: parseFixerArgv, options: optionsForOwner("fixer") },
+  collector: { parse: parseCollectorArgv, options: optionsForOwner("collector") },
+  doctor: { parse: parseDoctorArgv, options: optionsForOwner("doctor") },
+  merger: { parse: parseMergerArgv, options: optionsForOwner("merger") },
+  reviewer: { parse: parseReviewerArgv, options: optionsForOwner("reviewer") },
   /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
-  taishi: { parse: parseTaishiArgv },
+  taishi: { parse: parseTaishiArgv, options: optionsForOwner("taishi") },
 } as const;
 
+/** Global public options — same typed table as role rows (#342). */
+export const PUBLIC_GLOBAL_OPTIONS: readonly PublicOptionDefinition[] =
+  optionsForOwner("global");
+
 type TakenPublicGlobalFlag =
   | { flag: "help"; consume: 1 }
   | { flag: "model"; consume: 1 | 2; value: string | undefined }
@@ -86,43 +98,33 @@ type TakenPublicGlobalFlag =
 
 /**
  * If `argv[index]` is a public global flag, describe its span and payload.
- * Sole global-flag grammar for parseArgv.
+ * Spellings + repeatable come solely from PUBLIC_OPTION_TABLE.global via the
+ * shared typed consumer (#342).
  */
 function takePublicGlobalFlag(
   argv: readonly string[],
   index: number,
+  options: TypedOptionConsumer,
 ): TakenPublicGlobalFlag | undefined {
-  const token = argv[index];
-  if (token === undefined) return undefined;
-  if (token === "--help" || token === "-h") {
-    return { flag: "help", consume: 1 };
-  }
-  if (token === "--model") {
-    const value = argv[index + 1];
-    if (value === undefined) {
-      return { flag: "model", consume: 1, value: undefined };
-    }
-    return { flag: "model", consume: 2, value };
+  const tokens = argv.slice(index);
+  const taken = options.takeDashed(tokens as string[]);
+  if (taken === undefined) return undefined;
+  const consumed = argv.length - index - tokens.length;
+  if (taken.def.id === "help") {
+    return { flag: "help", consume: consumed as 1 };
   }
-  if (token.startsWith("--model=")) {
+  if (taken.def.id === "model") {
     return {
       flag: "model",
-      consume: 1,
-      value: token.slice("--model=".length),
+      consume: consumed as 1 | 2,
+      value: taken.value,
     };
   }
-  if (token === "--thinking") {
-    const raw = argv[index + 1];
-    if (raw === undefined) {
-      return { flag: "thinking", consume: 1, raw: undefined };
-    }
-    return { flag: "thinking", consume: 2, raw };
-  }
-  if (token.startsWith("--thinking=")) {
+  if (taken.def.id === "thinking") {
     return {
       flag: "thinking",
-      consume: 1,
-      raw: token.slice("--thinking=".length),
+      consume: consumed as 1 | 2,
+      raw: taken.value,
     };
   }
   return undefined;
@@ -231,17 +233,18 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
   let thinking: PublicThinkingLevel | undefined;
   let help = false;
   const positional: string[] = [];
+  const globalOptions = createTypedOptionConsumer(PUBLIC_GLOBAL_OPTIONS);
 
   // Global flags may appear before or after the subcommand
   // (`ak-role --model x roles` and `ak-role roles --model x`).
-  // Grammar authority: takePublicGlobalFlag above.
+  // Grammar authority: shared typed consumer over PUBLIC_OPTION_TABLE.global.
   while (args.length > 0) {
     if (args[0] === "--") {
       args.shift();
       positional.push(...args);
       break;
     }
-    const taken = takePublicGlobalFlag(args, 0);
+    const taken = takePublicGlobalFlag(args, 0, globalOptions);
     if (taken !== undefined) {
       if (taken.flag === "help") {
         help = true;
@@ -292,9 +295,31 @@ export function helpDocument() {
     executable: "ak-role",
     capabilities: listHelpCapabilities(),
     internalEntrypoint: INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
+    /** #342 structured global options from the sole option table. */
+    globalOptions: projectOwnerOptions("global"),
   };
 }
 
+/** Structured help facts for one public command/role (#342). */
+export function helpDocumentForCommand(command: string) {
+  if (command === "global") {
+    return {
+      command: "global" as const,
+      kind: "global" as const,
+      options: projectOwnerOptions("global"),
+    };
+  }
+  if (command in PUBLIC_ROLE_ARGV) {
+    const owner = command as keyof typeof PUBLIC_ROLE_ARGV;
+    return {
+      command: owner,
+      kind: owner === "taishi" ? ("deterministic" as const) : ("role" as const),
+      options: projectOwnerOptions(owner),
+    };
+  }
+  return undefined;
+}
+
 function renderHelp(): string {
   const doc = helpDocument();
   const lines: string[] = [
@@ -324,15 +349,43 @@ function renderHelp(): string {
       lines.push(`  ${cap.name}`);
     }
   }
+  lines.push("", "Global options:");
+  lines.push(...renderOwnerOptionHelpLines("global"));
   lines.push(
     "",
-    "Global options: --model provider/model --thinking level",
+    "Role options: ak-role help <command>",
     "Persistent config: ak-role config set <seat> <provider/model:thinking>",
     "Effective seats: ak-role roles",
   );
   return `${lines.join("\n")}\n`;
 }
 
+function renderCommandHelp(command: string): string | undefined {
+  const caps = listHelpCapabilities();
+  const match = caps.find((cap) => cap.name === command);
+  if (match === undefined) return undefined;
+  const lines: string[] = [];
+  if (match.kind === "support") {
+    lines.push(`command\t${match.name}\tkind\tsupport`);
+  } else if (match.kind === "deterministic") {
+    lines.push(`command\t${match.name}\tkind\tdeterministic`);
+  } else {
+    lines.push(
+      `command\t${match.name}\tkind\trole\tphases\t${match.phases
+        .map((p) => (p === null ? "none" : p))
+        .join(",")}\tdefault\t${match.defaultPhase ?? "none"}`,
+    );
+  }
+  if (command in PUBLIC_ROLE_ARGV) {
+    lines.push(
+      ...renderOwnerOptionHelpLines(
+        command as keyof typeof PUBLIC_ROLE_ARGV,
+      ),
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 function renderRoles(seats: readonly EffectiveSeat[]): string {
   const lines: string[] = ["seat\tkind\tsource\tmodel"];
   for (const seat of seats) {
@@ -430,25 +483,14 @@ export async function runAkRole(
       parsed.command === undefined ||
       parsed.command === "help"
     ) {
-      // Layered help: `help <topic>` still derives from the same typed registry.
+      // Layered help: `help <topic>` derives from the typed registry + option table (#342).
       if (parsed.command === "help" && parsed.args[0] !== undefined) {
         const topic = parsed.args[0];
-        const caps = listHelpCapabilities();
-        const match = caps.find((cap) => cap.name === topic);
-        if (match === undefined) {
+        const rendered = renderCommandHelp(topic);
+        if (rendered === undefined) {
           throw new CliUsageError(`unknown help topic: ${topic}`);
         }
-        if (match.kind === "support") {
-          io.stdout(`command\t${match.name}\tkind\tsupport\n`);
-        } else if (match.kind === "deterministic") {
-          io.stdout(`command\t${match.name}\tkind\tdeterministic\n`);
-        } else {
-          io.stdout(
-            `command\t${match.name}\tkind\trole\tphases\t${match.phases
-              .map((p) => (p === null ? "none" : p))
-              .join(",")}\tdefault\t${match.defaultPhase ?? "none"}\n`,
-          );
-        }
+        io.stdout(rendered);
         return { exitCode: 0 };
       }
       io.stdout(renderHelp());