@akagilnc/pi-workflow-roles 0.1.3718 → 0.1.3733

package/src/acp-host/seat-profile-soul.ts

@@ -0,0 +1,97 @@
+/**
+ * Seat-scoped host profile soul delivery (#644 / 拍 2).
+ *
+ * Hermes has no per-session systemPrompt channel; identity is the profile's
+ * SOUL.md. Each seat owns `profiles/<namePrefix><role>/`, and SOUL.md is a
+ * symlink to the packaged `souls/<role>.md` (package is the sole soul source).
+ */
+import { constants } from "node:fs";
+import { access, copyFile, lstat, mkdir, readlink, symlink, unlink } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+export type SeatProfileSoul = Readonly<{
+  /** Argv flag selecting the profile (hermes pre-argparse `-p`). */
+  flag: string;
+  /** Profile id = `${namePrefix}${role}` (e.g. `ak-judge`). */
+  namePrefix: string;
+  /** Profile directory root relative to the operator home (`.hermes/profiles`). */
+  profilesRootFromHome: readonly string[];
+  /** Soul filename inside the profile directory. */
+  soulFileName: string;
+}>;
+
+/** Profile id for one seat role. */
+export function seatProfileName(spec: SeatProfileSoul, role: string): string {
+  return `${spec.namePrefix}${role}`;
+}
+
+/** Packaged soul path for one role (`souls/<role>.md`). */
+export function packageRoleSoulPath(packageRoot: string, role: string): string {
+  return join(packageRoot, "souls", `${role}.md`);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure the seat profile directory exists and SOUL.md is a symlink to the
+ * packaged role soul. On first create, copy credential surfaces from the host
+ * root (parent of the profiles root) so the profile can authenticate without
+ * touching the default profile in place. Returns the profile id for argv.
+ */
+export async function ensureSeatProfileSoul(options: {
+  readonly spec: SeatProfileSoul;
+  readonly operatorHome: string;
+  readonly packageRoot: string;
+  readonly role: string;
+}): Promise<string> {
+  const { spec, operatorHome, packageRoot, role } = options;
+  const profileName = seatProfileName(spec, role);
+  const soulTarget = resolve(packageRoleSoulPath(packageRoot, role));
+  if (!(await pathExists(soulTarget))) {
+    throw new Error(`packaged role soul missing: ${soulTarget}`);
+  }
+
+  const profilesRoot = join(operatorHome, ...spec.profilesRootFromHome);
+  const profileDir = join(profilesRoot, profileName);
+  const hostRoot = dirname(profilesRoot);
+  const soulPath = join(profileDir, spec.soulFileName);
+
+  if (!(await pathExists(profileDir))) {
+    await mkdir(profileDir, { recursive: true });
+    // First-create credential bootstrap only. Never rewrite an existing profile's
+    // auth/config; never write into the host root / default profile.
+    for (const name of ["auth.json", ".env", "config.yaml"] as const) {
+      const source = join(hostRoot, name);
+      if (!(await pathExists(source))) continue;
+      await copyFile(source, join(profileDir, name));
+    }
+  } else {
+    await mkdir(profileDir, { recursive: true });
+  }
+
+  const desiredLink = relative(profileDir, soulTarget);
+  let current: string | undefined;
+  try {
+    const st = await lstat(soulPath);
+    if (st.isSymbolicLink()) {
+      current = await readlink(soulPath);
+    }
+  } catch {
+    current = undefined;
+  }
+  if (current === desiredLink || current === soulTarget) {
+    return profileName;
+  }
+  if (await pathExists(soulPath) || current !== undefined) {
+    await unlink(soulPath);
+  }
+  await symlink(desiredLink, soulPath);
+  return profileName;
+}

package/src/auditor-dossier-tool.ts

@@ -3,6 +3,7 @@ import { dirname, join, resolve } from "node:path";
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { HostContext } from "./host-contracts.ts";
+import { readableGateItem } from "./readable-gate-item.ts";
 import { Type } from "typebox";
 
 export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier" as const;
@@ -63,24 +64,35 @@ export function gateSubmissionCandidatePath(runDirectory: string): string {
 }
 
 /**
- * Human-readable materials for gate-officer same-parent resume (#753 / #750).
- * Pointers only — no body embed (ADR 0079/0081); no duty/handbook lines (#755).
+ * Arguments of the latest assistant toolCall leaf — the in-flight 交卷 body.
+ * Transport assembly only: does not interpret field contents (#786).
+ */
+export function readLatestSubmissionArguments(
+  context: GateSubmissionSessionContext,
+): unknown | undefined {
+  const leaf = readLatestToolCallLeaf(context);
+  if (!isRecord(leaf) || !isRecord(leaf.message) || !Array.isArray(leaf.message.content)) {
+    return undefined;
+  }
+  for (const part of leaf.message.content) {
+    if (isRecord(part) && part.type === "toolCall" && "arguments" in part) {
+      return part.arguments;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Verbatim parent-submission body for gate-officer same-parent resume (#786).
  * Three pairs share this face: countersign↔notary, judge↔auditor, worker↔inspector.
- * Code delivers the pointers; it does not judge whether the officer read them.
+ * Code relays bytes; it does not parse, judge, or rewrite the submission.
+ * Symmetric with bounce direction (officer receipt → parent via readableGateItem).
+ * No path/pointer substitute — argv 卷宗指针 stays on the code-summons face (ADR 0079).
  */
 export function buildGateOfficerReviewInstruction(input: {
-  readonly sourceRunDirectory: string;
-  readonly submissionCandidatePath?: string;
+  readonly submission: unknown;
 }): string {
-  const lines = [
-    "本轮父席交卷待审。",
-    `来源 run：${input.sourceRunDirectory}`,
-  ];
-  const candidate = input.submissionCandidatePath?.trim();
-  if (candidate !== undefined && candidate.length > 0) {
-    lines.push(`交卷候选（冻结快照）：${candidate}`);
-  }
-  return lines.join("\n");
+  return readableGateItem(input.submission);
 }
 
 /**

package/src/gatekeeper-role.ts

@@ -4,6 +4,7 @@ import type { HostContext } from "./host-contracts.ts";
 import {
   auditorRunDirectory,
   persistGateSubmissionCandidate,
+  readLatestSubmissionArguments,
 } from "./auditor-dossier-tool.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { GatekeeperDecisionError } from "./submission-errors.ts";
@@ -89,6 +90,11 @@ export type GateOfficerSummon = (
    * conclusion (#753 / #756). Hosted as same-ticket resume instruction.
    */
   reask?: string,
+  /**
+   * In-flight parent 交卷 body (tool-call arguments). Production default relays
+   * it verbatim on same-parent officer resume (#786).
+   */
+  submission?: unknown,
 ) => Promise<PublicSummonResult>;
 
 export type RunGatekeeperOptions = {
@@ -106,6 +112,14 @@ export type RunGatekeeperOptions = {
    * activation path (#675); inject only in offline tracers.
    */
   readonly summonOfficer?: GateOfficerSummon;
+  /**
+   * Offline test injects forwarded through the production default summonGateOfficer
+   * path (same faces as public CLI). Production leaves these unset.
+   */
+  readonly home?: string;
+  readonly packageRoot?: string;
+  readonly roleTurnHost?: import("./host-contracts.ts").RoleTurnHost;
+  readonly createRunId?: () => string;
 };
 
 export type GatekeeperPassHostActions = {
@@ -299,18 +313,16 @@ export async function projectGatekeeperRun(
       },
     };
   }
-  // Pointer-only summons need a resolvable leaf: Grok session.jsonl is header-only
-  // (#617 DK-4); write the in-memory tool-call candidate as a run artifact first (#632).
-  // Candidate path also rides same-parent officer resume as 人读材料 (#753 / #750).
-  const submissionCandidatePath = persistGateSubmissionCandidate(
-    runDirectory,
-    options.context,
-  );
+  // #632: Grok session.jsonl is header-only — freeze the in-memory tool-call leaf
+  // as a run artifact so dossier exploration still resolves. LLM→LLM resume does
+  // not ride this path: submission body goes verbatim on gateReviewInstruction (#786).
+  persistGateSubmissionCandidate(runDirectory, options.context);
+  const submission = readLatestSubmissionArguments(options.context);
   let summoned: PublicSummonResult;
   try {
     const summon =
       options.summonOfficer
-      ?? (async (nextOfficer, sourceRunDirectory, officerSignal, reask) => {
+      ?? (async (nextOfficer, sourceRunDirectory, officerSignal, reask, nextSubmission) => {
         const { summonGateOfficer } = await import("./public-role-summons.ts");
         return summonGateOfficer({
           officer: nextOfficer,
@@ -318,12 +330,20 @@ export async function projectGatekeeperRun(
           cwd: options.context.cwd ?? process.cwd(),
           ...(officerSignal === undefined ? {} : { signal: officerSignal }),
           ...(reask === undefined ? {} : { reask }),
-          ...(submissionCandidatePath === undefined
-            ? {}
-            : { submissionCandidatePath }),
+          ...(nextSubmission === undefined ? {} : { submission: nextSubmission }),
+          ...(options.home === undefined ? {} : { home: options.home }),
+          ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
+          ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+          ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
         });
       });
-    summoned = await summon(officer, runDirectory, options.signal, options.reask);
+    summoned = await summon(
+      officer,
+      runDirectory,
+      options.signal,
+      options.reask,
+      submission,
+    );
   } catch (error) {
     return {
       officer,

package/src/host-descriptions.ts

@@ -24,6 +24,7 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
       suffix: Object.freeze(["stdio"]),
       modelFlag: "--model",
     }),
+    modelPassing: "argv",
     boundResume: "session/load",
     sessionBindingFile: "grok-acp-session.json",
     childEnv: Object.freeze({
@@ -32,6 +33,31 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
       GROK_SUBAGENTS: "0",
     }),
   }),
+  /**
+   * Operator home `~/.hermes`, native session/load resume, `acp` subcommand.
+   * Model arrives as an ACP `session/set_model` RPC with modelId `provider:model`
+   * (seat table provider + model concatenated). Reasoning is the global
+   * `--reasoning` flag before `acp`. Soul is the seat profile SOUL.md symlink
+   * (`hermes -p ak-<role> …`); package `souls/<role>.md` is the sole source.
+   */
+  "hermes": Object.freeze({
+    binaryFromHome: Object.freeze([".local", "bin", "hermes"]),
+    argv: Object.freeze({
+      prefix: Object.freeze(["acp"]),
+      suffix: Object.freeze([]),
+      thinkingFlag: "--reasoning",
+    }),
+    modelPassing: "set_model",
+    boundResume: "session/load",
+    sessionBindingFile: "hermes-acp-session.json",
+    childEnv: Object.freeze({}),
+    seatProfileSoul: Object.freeze({
+      flag: "-p",
+      namePrefix: "ak-",
+      profilesRootFromHome: Object.freeze([".hermes", "profiles"]),
+      soulFileName: "SOUL.md",
+    }),
+  }),
 });
 
 export function lookupHostDescription(host: string): AcpHostDescription | undefined {

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

@@ -51,7 +51,7 @@ export type InspectorRunEnv = PostAdmissionEnv & {
    */
   reviewReask?: string;
   /**
-   * #753/#750 same-parent re-summons: human-readable new-submission pointers.
+   * #786 same-parent re-summons: verbatim parent-submission body.
    * Rides summons.instruction when reviewReask is absent. Fresh mint keeps argv 卷宗指针.
    */
   gateReviewInstruction?: string;
@@ -99,7 +99,7 @@ export async function runPublicInspector(
   // No bare catch→fresh: lookup/resume failures surface; only true absence mints new.
   const projectRoot = parsed.project ?? env.cwd;
   // #747: parentRunPath is the pure 卷宗指针 path only — never reask/materials text.
-  // #753: gate re-ask / new-submission pointers ride summons.instruction on resume.
+  // #753/#786: gate re-ask / verbatim submission body ride summons.instruction on resume.
   const parentRunPath = parentRunPathFromGatePointerInstruction(parsed.instruction);
   if (parentRunPath !== undefined) {
     const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
@@ -129,7 +129,7 @@ export async function runPublicInspector(
     if (resumed !== undefined) return resumed;
     // Reask without a prior same-parent run cannot deliver the plain-language ask
     // on a fresh mint without inventing a second prompt path — fail loud (#753).
-    // gateReviewInstruction alone is resume-only; fresh mint keeps argv 卷宗指针.
+    // gateReviewInstruction (verbatim body) alone is resume-only; fresh mint keeps argv 卷宗指针.
     if (env.reviewReask !== undefined) {
       presentStructuralRejection(
         new CliUsageError(

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

@@ -70,7 +70,7 @@ export type InstructionSeatRunEnv = PostAdmissionEnv & {
    */
   reviewReask?: string;
   /**
-   * #753/#750 same-parent re-summons: human-readable new-submission pointers.
+   * #786 same-parent re-summons: verbatim parent-submission body.
    * Rides summons.instruction when reviewReask is absent. Fresh mint keeps argv instruction.
    */
   gateReviewInstruction?: string;
@@ -294,7 +294,7 @@ export async function runPublicInstructionSeat(
     }
   }
 
-  // #756: auditor reask / new-submission pointers ride summons.instruction on resume.
+  // #756/#786: auditor reask / verbatim submission body ride summons.instruction on resume.
   const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
   const summons: SameTicketSummonsMaterials = {
     ...(resumeInstruction === undefined

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

@@ -53,7 +53,7 @@ export type NotaryRunEnv = PostAdmissionEnv & {
    */
   reviewReask?: string;
   /**
-   * #753/#750 same-parent re-summons: human-readable new-submission pointers.
+   * #786 same-parent re-summons: verbatim parent-submission body.
    * Rides summons.instruction when reviewReask is absent. Fresh mint ignores it.
    */
   gateReviewInstruction?: string;
@@ -120,7 +120,7 @@ export async function runPublicNotary(
     throw error;
   }
   // #747: officer resume key is this parent source-run path (not ticket number).
-  // #753: gate re-ask and new-submission pointers share summons.instruction
+  // #753/#786: gate re-ask and verbatim submission body share summons.instruction
   // (reask wins when both present; no parallel stack).
   {
     const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
@@ -148,7 +148,7 @@ export async function runPublicNotary(
     if (resumed !== undefined) return resumed;
     // Reask without a prior same-parent run cannot deliver the plain-language ask
     // on a fresh mint without inventing a second prompt path — fail loud (#753).
-    // gateReviewInstruction alone is resume-only materials; fresh mint ignores it.
+    // gateReviewInstruction (verbatim body) alone is resume-only; fresh mint ignores it.
     if (env.reviewReask !== undefined) {
       presentStructuralRejection(
         new CliUsageError(

package/src/public-role-summons.ts

@@ -60,12 +60,18 @@ export type PublicSummonRequest = {
    */
   readonly reviewReask?: string;
   /**
-   * #753/#750 same-parent re-summons: human-readable pointer materials for the
-   * new parent submission (source run + optional gate-submission-candidate).
+   * #786 same-parent re-summons: verbatim parent-submission body for the gate officer.
    * Rides summons.instruction when reviewReask is absent. Fresh mint ignores it.
-   * Never folded into argv / parent-run lookup keys.
+   * Never folded into argv / parent-run lookup keys (ADR 0079 卷宗指针 stays pure).
    */
   readonly gateReviewInstruction?: string;
+  /**
+   * Offline test inject — same face as public CLI env.roleTurnHost. Production
+   * summons leave this unset and use the seat-resolved host.
+   */
+  readonly roleTurnHost?: RoleTurnHost;
+  /** Offline test inject for deterministic run ids (same face as public CLI). */
+  readonly createRunId?: () => string;
 };
 
 export type PublicSummonResult = {
@@ -293,10 +299,13 @@ export async function summonPublicRole(
     ...(options.signal === undefined ? {} : { signal: options.signal }),
     // #753: reask rides the existing notary same-ticket resume summons.instruction.
     ...(options.reviewReask === undefined ? {} : { reviewReask: options.reviewReask }),
-    // #753/#750: new-submission pointers on same-parent resume (not conclusion re-ask).
+    // #786: verbatim submission body on same-parent resume (not conclusion re-ask).
     ...(options.gateReviewInstruction === undefined
       ? {}
       : { gateReviewInstruction: options.gateReviewInstruction }),
+    // Offline test injects — same faces as public CLI env (production leaves unset).
+    ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+    ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   };
   const captured = options.io === undefined ? createCapturingIo() : undefined;
   const io = options.io ?? captured!.io;
@@ -412,10 +421,14 @@ export async function summonGateOfficer(options: {
    */
   readonly reask?: string;
   /**
-   * Path of this turn's gate-submission-candidate when written (#632 / #753).
-   * Becomes human-readable resume materials when reask is absent.
+   * In-flight parent 交卷 body (tool-call arguments). Relayed verbatim on resume
+   * when reask is absent (#786). Never a path pointer substitute.
    */
-  readonly submissionCandidatePath?: string;
+  readonly submission?: unknown;
+  /** Offline test inject — forwarded to summonPublicRole. */
+  readonly roleTurnHost?: RoleTurnHost;
+  /** Offline test inject — forwarded to summonPublicRole. */
+  readonly createRunId?: () => string;
 }): Promise<PublicSummonResult> {
   let home = options.home;
   if (home === undefined) {
@@ -423,16 +436,13 @@ export async function summonGateOfficer(options: {
     // Hard path resolve: fail loud — never fall through to packageMachineHome (#604 / #675).
     home = homeFromRunDirectory(options.sourceRunDirectory);
   }
-  // Conclusion re-ask keeps sole ownership of reviewReask. New-submission materials
-  // ride a separate field so first mint never fails the "reask requires prior" gate.
+  // Conclusion re-ask keeps sole ownership of reviewReask. New-submission body
+  // rides a separate field so first mint never fails the "reask requires prior" gate.
   let gateReviewInstruction: string | undefined;
-  if (options.reask === undefined) {
+  if (options.reask === undefined && options.submission !== undefined) {
     const { buildGateOfficerReviewInstruction } = await import("./auditor-dossier-tool.ts");
     gateReviewInstruction = buildGateOfficerReviewInstruction({
-      sourceRunDirectory: options.sourceRunDirectory,
-      ...(options.submissionCandidatePath === undefined
-        ? {}
-        : { submissionCandidatePath: options.submissionCandidatePath }),
+      submission: options.submission,
     });
   }
   const common = {
@@ -445,6 +455,8 @@ export async function summonGateOfficer(options: {
     ...(gateReviewInstruction === undefined
       ? {}
       : { gateReviewInstruction }),
+    ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
+    ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   } as const;
   if (options.officer === "notary") {
     // #753: reask rides summonPublicRole → runPublicNotary summons.instruction