@akagilnc/pi-workflow-roles 0.1.4035 → 0.1.4193

package/src/public-cli/settlement.ts

@@ -15,6 +15,7 @@ import { readSitianRecords, resolveSitianRecordPath, sitianReport } from "../sit
 
 import {
   hasFreshAttemptSubmission,
+  readAttemptScopedSubmissionRows,
   readRecordedSubmissionRows,
   readRecordedSubmissions,
 } from "../submission-ledger.ts";
@@ -125,6 +126,7 @@ import type {
   DurablePrincipalAuthority,
   DurablePrincipalCoordinates,
 } from "../host-contracts.ts";
+import { roleRunArtifactsDirectory } from "../role-run-placement.ts";
 import {
   ensureRunArtifactsDir,
   homeFromRunDirectory,
@@ -161,9 +163,10 @@ export type SettlementCourtScope = {
 function ledgerReadScope(
   admitted: Pick<AdmittedRoleInvocation, "runDirectory">,
   scope?: SettlementCourtScope,
-): { home: string; attemptId?: string } {
+): { home: string; sessionParent: string; attemptId?: string } {
   return {
     home: sealedLedgerHome(admitted),
+    sessionParent: join(admitted.runDirectory, "session", "session.jsonl"),
     ...(scope?.courtAttemptId === undefined || scope.courtAttemptId.length === 0
       ? {}
       : { attemptId: scope.courtAttemptId }),
@@ -198,6 +201,22 @@ async function sealedLedgerOutcome(
   role: TerminalRoleName,
   scope?: SettlementCourtScope,
 ): Promise<Extract<TerminalRoleOutcome, { kind: "accepted" | "audit_escalation" }> | undefined> {
+  const home = sealedLedgerHome(admitted);
+  // #879: when court scope is present, roleOutcome is this-court original only —
+  // never last-wins over an undivided historical array, and never falls back to
+  // full-run history when this court sealed zero rows. #836 presentation of full
+  // history stays on attachRecordedSubmissions / terminal.submissions (run-scoped).
+  if (scope?.courtAttemptId !== undefined && scope.courtAttemptId.length > 0) {
+    const thisCourt = await readAttemptScopedSubmissionRows(
+      admitted.projectRoot,
+      admitted.runId,
+      scope.courtAttemptId,
+      home,
+    );
+    // Scope present + zero this-court rows → no this-court outcome (not run history).
+    return roleOutcomeFromRows(role, thisCourt);
+  }
+  // No court scope: keep run-scoped ledger face (#836).
   const rows = await readRecordedSubmissionRows(
     admitted.projectRoot,
     admitted.runId,
@@ -225,7 +244,7 @@ export async function attemptProducedFreshSubmission(
     admitted.projectRoot,
     admitted.runId,
     scope.courtAttemptId,
-    sealedLedgerHome(admitted),
+    ledgerReadScope(admitted, scope),
   );
 }
 
@@ -247,12 +266,14 @@ export function withSubmissions<T extends TerminalResult>(
 ): T {
   if (submissions.length === 0) return terminal;
   const roleOutcome = terminal.roleOutcome;
-  // Full ledger sequence always wins the role-result block (#881): do not keep a
-  // narrower pre-filtered payloads array when attach brings the complete set.
+  // #879 keeps an already scoped this-court result; #881 full run history is
+  // presented independently on terminal.submissions. Only fill a missing result payload.
   const withPayloads =
-    roleOutcome.kind === "accepted" || roleOutcome.kind === "audit_escalation" || roleOutcome.kind === "failure"
-      ? { ...roleOutcome, payloads: submissions }
-      : roleOutcome;
+    roleOutcome.kind === "accepted" || roleOutcome.kind === "audit_escalation"
+      ? { ...roleOutcome, payloads: (roleOutcome.payloads ?? []).length > 0 ? roleOutcome.payloads : submissions }
+      : roleOutcome.kind === "failure"
+        ? { ...roleOutcome, payloads: roleOutcome.payloads ?? submissions }
+        : roleOutcome;
   return { ...terminal, roleOutcome: withPayloads, submissions };
 }
 
@@ -262,7 +283,14 @@ export async function attachRecordedSubmissions<T extends TerminalResult>(
   terminal: T,
   scope?: SettlementCourtScope,
 ): Promise<T> {
-  return withSubmissions(terminal, await recordedSubmissionPayloads(admitted, scope));
+  // #836 / #879: submissions presentation is always run-scoped history. Do not
+  // pass courtAttemptId here — roleOutcome already carries this-court payloads
+  // from sealedLedgerOutcome when scoped; withSubmissions keeps them.
+  void scope;
+  return withSubmissions(
+    terminal,
+    await recordedSubmissionPayloads(admitted, undefined),
+  );
 }
 
 /**
@@ -3818,7 +3846,7 @@ function uniqueFailureFallbackDirs(
 async function resolveFailureArtifactsBase(
   runDirectory: string,
 ): Promise<{ baseDir: string; attempt?: PublicationAttempt }> {
-  const artifactsDir = join(runDirectory, "artifacts");
+  const artifactsDir = roleRunArtifactsDirectory(runDirectory);
   try {
     await ensureRunArtifactsDir(runDirectory);
     return { baseDir: artifactsDir };
@@ -3910,7 +3938,7 @@ export async function publishFailureArtifacts(
   // Prefer conventional names; unique fallback dirs keep colliding fixed paths
   // from stranding the original failure outside settlement. Include the ledger
   // runs/ parent so a locked run directory (EACCES) cannot exhaust durability.
-  const underArtifacts = baseDir === join(admitted.runDirectory, "artifacts");
+  const underArtifacts = baseDir === roleRunArtifactsDirectory(admitted.runDirectory);
   const uniqueFallbackDirs = uniqueFailureFallbackDirs(
     admitted.runDirectory,
     baseDir,

package/src/public-role-summons.ts

@@ -62,6 +62,12 @@ export type PublicSummonRequest = {
    * summons.instruction. Never folded into argv / parent-run lookup keys.
    */
   readonly reviewReask?: string;
+  /**
+   * #879 same-parent (and first-mint) gate summons: verbatim parent-submission body.
+   * Rides summons.instruction / first-mint prompt when reviewReask is absent.
+   * Never folded into argv / parent-run lookup keys (binding pointer stays pure).
+   */
+  readonly gateReviewInstruction?: string;
   /**
    * Pi-adapter inject (tests). Used only as the `pi` row when composing the
    * adapter table — never as an override of the child seat's selected host.
@@ -302,6 +308,10 @@ 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 }),
+    // #879: verbatim submission body on officer dialogue content channel.
+    ...(options.gateReviewInstruction === undefined
+      ? {}
+      : { gateReviewInstruction: options.gateReviewInstruction }),
     ...(options.boundTicketNumber === undefined
       ? {}
       : { boundTicketNumber: options.boundTicketNumber }),
@@ -430,6 +440,12 @@ export async function summonGateOfficer(options: {
    * Never concatenated into argv (inspector parentRunPath is the pure 卷宗指针).
    */
   readonly reask?: string;
+  /**
+   * In-flight parent 交卷 body (tool-call arguments). Relayed verbatim as officer
+   * dialogue content when reask is absent (#879). Binding pointer stays on
+   * --source-run / 卷宗指针 argv — never a content substitute.
+   */
+  readonly submission?: unknown;
   /** Pi-adapter inject — forwarded to summonPublicRole (not a parent-host override). */
   readonly roleTurnHost?: RoleTurnHost;
   readonly hostAdapters?: readonly NamedRoleTurnHostAdapter[];
@@ -444,8 +460,13 @@ export async function summonGateOfficer(options: {
   }
   // Officer host is seat-owned only (#821). Parent invocation.json.host stays a
   // hostTransition consumer in post-admission — not an officer override channel.
-  // #836: officers get the whole parent run directory pointer; code does not
-  // inject a picked toolCall leaf as the resume instruction.
+  // #879: binding pointer = parent run directory; dialogue content = submission body.
+  // Conclusion re-ask keeps sole ownership of reviewReask when present.
+  let gateReviewInstruction: string | undefined;
+  if (options.reask === undefined && options.submission !== undefined) {
+    const { readableGateItem } = await import("./readable-gate-item.ts");
+    gateReviewInstruction = readableGateItem(options.submission);
+  }
   const common = {
     cwd: options.cwd,
     ...(home === undefined ? {} : { home }),
@@ -453,13 +474,16 @@ export async function summonGateOfficer(options: {
     ...(options.io === undefined ? {} : { io: options.io }),
     ...(options.signal === undefined ? {} : { signal: options.signal }),
     ...(options.reask === undefined ? {} : { reviewReask: options.reask }),
+    ...(gateReviewInstruction === undefined
+      ? {}
+      : { gateReviewInstruction }),
     ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
     ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
     ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   } as const;
   if (options.officer === "notary") {
-    // #753: reask rides summonPublicRole → runPublicNotary summons.instruction
-    // (same resume seam as ordinary same-parent re-summons — no parallel stack).
+    // #753/#879: reask or verbatim body rides summons.instruction / first-mint prompt.
+    // Binding stays --source-run (never folded into content).
     return summonPublicRole({
       role: "notary",
       argv: ["--source-run", options.sourceRunDirectory, "--project", options.cwd],
@@ -468,7 +492,7 @@ export async function summonGateOfficer(options: {
   }
   if (options.officer === "auditor") {
     // #756: judge compliance path — same queue law as notary/inspector.
-    // #836: auditor kickoff is path pointer (同察院), not「本 run 卷宗已就绪」.
+    // Binding pointer on argv; dialogue content rides gateReviewInstruction.
     return summonPublicRole({
       role: "auditor",
       argv: [
@@ -481,8 +505,8 @@ export async function summonGateOfficer(options: {
       ...common,
     });
   }
-  // Inspector: argv stays pure 卷宗指针 (#747 parentRunPath); reask rides env only.
-  // #836 resume 请重读 is added on the resume projection face, not here.
+  // Inspector: argv stays pure 卷宗指针 (#747 parentRunPath lookup key).
+  // Content (body/reask) rides env → summons.instruction / first-mint prompt.
   return summonPublicRole({
     role: "inspector",
     argv: [`卷宗指针：${options.sourceRunDirectory}`],

package/src/role-envelope.ts

@@ -172,6 +172,8 @@ export async function prepareRoleEnvelope(options: {
     cwd: request.cwd,
     mode: "print",
     model: request.model === undefined ? undefined : { provider: request.model.provider },
+    runDirectory: request.runDirectory,
+    ...(request.courtAttemptId === undefined ? {} : { courtAttemptId: request.courtAttemptId }),
     sessionManager: {
       getLeafEntry: () => sessionEntries.at(-1) as ReturnType<HostContext["sessionManager"]["getLeafEntry"]>,
       getLeafId: () => runId,
@@ -239,6 +241,7 @@ export async function prepareRoleEnvelope(options: {
           bindSubmissionNonPass: options.hostActions.bindSubmissionNonPass,
         },
         toolCallId: options.toolCallId,
+        ...(options.submission === undefined ? {} : { submission: options.submission }),
       });
     },
     on(...registration: HostEventRegistration) {
@@ -527,22 +530,8 @@ export async function prepareRoleEnvelope(options: {
   const relay = fileURLToPath(new URL("./mcp-relay.mjs", import.meta.url));
   await listen(server, options.socketPath);
   let disposed = false;
-  // Tools execute in this process (relay is protocol-only). Mirror Pi's child-env
-  // AK_ROLE_RUN_DIR / AK_ROLE_COURT_ATTEMPT injection onto the parent so ledger
-  // identity sees the same signals. Engine axis is request-scoped via RoleHost
-  // flag — never process.env (#818 P1). Run-dir may wait
-  // until prepare succeeds. Dispose restores including unset.
-  let priorAkRoleRunDir: string | undefined;
-  let priorAkRoleCourtAttempt: string | undefined;
-  let runDirInjected = false;
-  const restoreAkRoleRunEnv = (): void => {
-    if (!runDirInjected) return;
-    runDirInjected = false;
-    if (priorAkRoleRunDir === undefined) delete process.env.AK_ROLE_RUN_DIR;
-    else process.env.AK_ROLE_RUN_DIR = priorAkRoleRunDir;
-    if (priorAkRoleCourtAttempt === undefined) delete process.env.AK_ROLE_COURT_ATTEMPT;
-    else process.env.AK_ROLE_COURT_ATTEMPT = priorAkRoleCourtAttempt;
-  };
+  // Per-turn run/court identity lives on HostContext (request-scoped). Engine
+  // axis is already a RoleHost flag — never process.env (#818 P1 / #879).
   const dispose = async (): Promise<void> => {
     if (disposed) return;
     disposed = true;
@@ -552,11 +541,6 @@ export async function prepareRoleEnvelope(options: {
     } catch (error) {
       cleanupFailures.push(error);
     }
-    try {
-      restoreAkRoleRunEnv();
-    } catch (error) {
-      cleanupFailures.push(error);
-    }
     try {
       const closeAll = (server as unknown as { closeAllConnections?: () => void }).closeAllConnections;
       if (typeof closeAll === "function") closeAll.call(server);
@@ -640,6 +624,8 @@ export async function prepareRoleEnvelope(options: {
     }
     // Method notes only here — role before_agent_start injects soul once.
     // Preloading session materials duplicated soul under the role tag (#632).
+    // #879: case-dossier owner reads runDirectory from this turn's HostContext.
+
     const methodPrompt = (await Promise.all(request.methods.map(({ path }) => readFile(path, "utf8")))).join("\n\n");
     const promptResults = await emit("before_agent_start", {
       prompt,
@@ -652,8 +638,8 @@ export async function prepareRoleEnvelope(options: {
       return [value.systemPrompt];
     });
     const systemPromptBody = systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : methodPrompt;
-    // Typed reading materials from agent-start handlers (machine face; independent of prompt bytes).
-    // Folded into the provider-visible systemPrompt by the adapter at the send boundary.
+    // Typed reading materials from agent-start handlers (incl. single shared
+    // case-dossier owner). Folded into provider-visible systemPrompt at send.
     const readingMaterials: unknown[] = [];
     for (const value of promptResults) {
       if (typeof value !== "object" || value === null) continue;
@@ -662,13 +648,6 @@ export async function prepareRoleEnvelope(options: {
       if (material !== undefined) readingMaterials.push(material);
     }
 
-    priorAkRoleRunDir = process.env.AK_ROLE_RUN_DIR;
-    priorAkRoleCourtAttempt = process.env.AK_ROLE_COURT_ATTEMPT;
-    process.env.AK_ROLE_RUN_DIR = request.runDirectory;
-    if (request.courtAttemptId === undefined) delete process.env.AK_ROLE_COURT_ATTEMPT;
-    else process.env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
-    runDirInjected = true;
-
     const terminating = tools.get(terminatingToolName);
     if (terminating === undefined) {
       throw new Error(`terminating tool not registered after activation: ${terminatingToolName}`);

package/src/role-run-placement.ts

@@ -0,0 +1,128 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  activationBookDirectory,
+  ensureRealDirectoryTree,
+} from "./activation-ledger-topology.ts";
+import { requireSafePositiveTicketNumber } from "./run-ticket-number.ts";
+
+export type RoleRunSubject =
+  | { readonly ticketNumber: number }
+  | { readonly unbound: true };
+
+export type RoleRunPlacement = {
+  readonly runDirectory: string;
+  readonly sessionDirectory: string;
+  readonly sessionFile: string;
+  readonly artifactsDirectory: string;
+  readonly attachmentsDirectory: string;
+};
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+/**
+ * Sole book-level run directory walk: flat legacy `runs/` plus each
+ * `subject/runs/` child (ticket / unbound). One authority for read-side
+ * enumeration under a book directory — findRunDirectoryById, analyst scan,
+ * and ticket trajectory must not hardcode a second subject-tree walk.
+ */
+export async function listBookRunDirectories(bookDir: string): Promise<string[]> {
+  const out: string[] = [];
+  const seen = new Set<string>();
+
+  const collect = async (runsDir: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(runsDir, { withFileTypes: true });
+    } catch (error) {
+      if (isMissingPathError(error)) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const runDir = join(runsDir, entry.name);
+      if (seen.has(runDir)) continue;
+      seen.add(runDir);
+      out.push(runDir);
+    }
+  };
+
+  await collect(join(bookDir, "runs"));
+
+  let subjects;
+  try {
+    subjects = await readdir(bookDir, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingPathError(error)) return out.sort();
+    throw error;
+  }
+  for (const subject of subjects) {
+    if (!subject.isDirectory() || subject.name === "runs") continue;
+    await collect(join(bookDir, subject.name, "runs"));
+  }
+  return out.sort();
+}
+
+/** The single authority for every path belonging to an admitted role run. */
+export function roleRunPlacement(
+  ledgerHome: string,
+  input: {
+    readonly bookKey: string;
+    readonly subject: RoleRunSubject;
+    readonly runId: string;
+    readonly role: string;
+  },
+): RoleRunPlacement {
+  const subjectDirectory = "ticketNumber" in input.subject
+    ? String(requireSafePositiveTicketNumber(
+        input.subject.ticketNumber,
+        "roleRunPlacement subject.ticketNumber",
+      ))
+    : "unbound";
+  const runDirectory = join(
+    activationBookDirectory(ledgerHome, input.bookKey),
+    subjectDirectory,
+    "runs",
+    `${input.runId}@${input.role}`,
+  );
+  const sessionDirectory = join(runDirectory, "session");
+  return {
+    runDirectory,
+    sessionDirectory,
+    sessionFile: join(sessionDirectory, "session.jsonl"),
+    artifactsDirectory: roleRunArtifactsDirectory(runDirectory),
+    attachmentsDirectory: join(runDirectory, "attachments"),
+  };
+}
+
+/** The single artifacts subpath definition for new and resumed role runs. */
+export function roleRunArtifactsDirectory(runDirectory: string): string {
+  return join(runDirectory, "artifacts");
+}
+
+/** The placement seam owns creation for both new runs and resumed legacy runs. */
+export function ensureRoleRunDirectory(
+  ledgerHome: string,
+  directory: string,
+): string {
+  return ensureRealDirectoryTree(ledgerHome, directory);
+}
+
+export function ensureRoleRunPlacement(
+  ledgerHome: string,
+  placement: RoleRunPlacement,
+): void {
+  for (const directory of [
+    placement.sessionDirectory,
+    placement.attachmentsDirectory,
+  ]) {
+    ensureRoleRunDirectory(ledgerHome, directory);
+  }
+}