@akagilnc/pi-workflow-roles 0.1.4035 → 0.1.4193

package/src/role-runtime.ts

@@ -2,6 +2,8 @@ import { readFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import {
   ExplicitInternalActivationError,
+  isOfficerReviewSeat,
+  runDirectoryFromHostContext,
   type HostContext,
   type HostToolResult,
   type RoleEnvelopeHost,
@@ -36,7 +38,13 @@ import {
   writeToolExecutionObservationRecord,
   type ToolExecutionObservationWriter,
 } from "./tool-execution-observation.ts";
-import { ENGINE_DETOUR_TOOL_NAME } from "./engine-detour.ts";
+import {
+  ENGINE_DETOUR_TOOL_NAME,
+  ENGINE_MODEL_FLAG_NAME,
+  resolveEngineModel,
+  resolveEngineName,
+} from "./engine-detour.ts";
+import { engineSessionMaterialFromOptions } from "./package-resources/engine-material.ts";
 import { registerEngineDetourTool } from "./engine-detour-tool.ts";
 import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, RECEIPT_DELIVERY_PROMPT } from "./receipt-delivery-policy.ts";
 import type { AnyCanonicalSkillBinding } from "./canonical-skill-binding.ts";
@@ -71,7 +79,7 @@ import {
   INSPECTOR_TOOL_SPEC,
   type InspectorRuntimeDependencies,
 } from "./inspector-role.ts";
-import { INSPECTOR_ACCEPTED_TEXT } from "./inspector-contracts.ts";
+import { INSPECTOR_ACCEPTED_TEXT, INSPECTOR_SOURCE_RUN_FLAG } from "./inspector-contracts.ts";
 import {
   DIARIST_TOOL_SPEC,
   type DiaristRuntimeDependencies,
@@ -414,7 +422,7 @@ export type { MergerRoleDependencies } from "./merger-role.ts";
 
 type WorkerArmable = {
   activate(context?: HostContext): Promise<void>;
-  armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }): void;
+  armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }): void;
 };
 
 type ActivationRuntime = {
@@ -566,6 +574,8 @@ type NavigatorAttendanceDependency = Omit<NavigatorAttendance, "knownRoutePlaybo
   Partial<Pick<NavigatorAttendance, "knownRoutePlaybookReadFailure">>;
 
 export type RoleRuntimeDependencies = {
+  /** Package root for packaged engine-note resolution (#879). */
+  packageRoot?: string;
   loadJudgeSoul(): Promise<string>;
   loadFixerSoul?(): Promise<string>;
   loadFixPacket?(path: string): Promise<string>;
@@ -898,14 +908,14 @@ function readDiaristTicketAssertion(
 }
 
 /** Run coordinates + optional pre-bound ticket from durable pages (#779). */
-function readDiaristRunCoordinates(): {
+function readDiaristRunCoordinates(ctx: HostContext): {
   readonly runDirectory: string;
   readonly projectRoot: string;
   readonly home: string;
   readonly boundTicketNumber?: number;
 } {
-  const runDirectory = process.env.AK_ROLE_RUN_DIR;
-  if (typeof runDirectory !== "string" || runDirectory.trim() === "") {
+  const runDirectory = runDirectoryFromHostContext(ctx);
+  if (runDirectory === undefined) {
     throw new Error("diarist accept requires AK_ROLE_RUN_DIR");
   }
   const admittedPath = join(runDirectory, "admitted-request.json");
@@ -948,13 +958,13 @@ export function createDiaristRoleRuntime(
       tool: DIARIST_TOOL_SPEC,
       acceptedText: DIARIST_ACCEPTED_TEXT,
       soulTag: "diarist",
-      beforeAccept: async ({ parameters }) => {
+      beforeAccept: async ({ parameters, ctx }) => {
         const submitted =
           parameters !== null && typeof parameters === "object" && !Array.isArray(parameters)
             ? (parameters as Record<string, unknown>)
             : undefined;
         const assertion = readDiaristTicketAssertion(submitted);
-        const coords = readDiaristRunCoordinates();
+        const coords = readDiaristRunCoordinates(ctx);
         // #836 7.3: pre-bound ticket is material for the LLM, not an override.
         const ticketNumber = assertion.kind === "ticket" ? assertion.ticketNumber : undefined;
         if (ticketNumber !== undefined) {
@@ -964,6 +974,7 @@ export function createDiaristRoleRuntime(
           await commitDiaristEntries({
             ticketNumber,
             cwd: coords.projectRoot,
+            sessionParent: join(coords.runDirectory, "session", "session.jsonl"),
             home: coords.home,
             entries: projectDiaristEntries(parameters),
           });
@@ -1020,6 +1031,8 @@ export function createCountersignRoleRuntime(
             ...(signal === undefined ? {} : { signal }),
             hostActions,
             toolCallId,
+            // #879: this-turn typed payload — identity-bound at submit site.
+            submission: parameters,
           });
         }
       : undefined;
@@ -1057,6 +1070,10 @@ export function createRoleRuntimeExtension(
     for (const flag of NOTARY_TRANSPORT_FLAGS) {
       roleHost.registerFlag(flag.name, flag.definition);
     }
+    roleHost.registerFlag(
+      INSPECTOR_SOURCE_RUN_FLAG.name,
+      INSPECTOR_SOURCE_RUN_FLAG.definition,
+    );
     for (const flag of GLEANER_LEFT_TRANSPORT_FLAGS) {
       roleHost.registerFlag(flag.name, flag.definition);
     }
@@ -1066,6 +1083,13 @@ export function createRoleRuntimeExtension(
     }
     // Station-child identity (#840): omit navigator attendance. One flag.
     roleHost.registerFlag(STATION_CHILD_FLAG.name, STATION_CHILD_FLAG.definition);
+    // Register model only. Pi never sets ak-engine — resolveEngineName must
+    // fall through to child-process env. An empty default would block that.
+    roleHost.registerFlag(ENGINE_MODEL_FLAG_NAME, {
+      description: "本次劳务引擎模型",
+      type: "string",
+      default: "",
+    });
 
     let admitted = false;
     let selectedRole: string | undefined;
@@ -1079,6 +1103,8 @@ export function createRoleRuntimeExtension(
     let pendingNavigatorPresentation: { event: import("./navigator-attendance.ts").NavigatorEvent; report: import("./navigator-attendance.ts").NavigatorReport } | undefined;
     let pendingNavigatorSettlement: Promise<void> | undefined;
     let navigatorWorkContext: NavigatorWorkContext | undefined;
+    let navigatorSessionParent: string | undefined;
+    let navigatorCwd: string | undefined;
     /** toolCallId → fact+evidence; one-shot projected onto durable tool_result (#475). */
     const pendingInfrastructureFailures = new Map<string, PendingInfrastructureFailure>();
     // Envelope-owned execute→tool_result bridge for submission non-pass (ADR 0018 / #525).
@@ -1134,18 +1160,19 @@ export function createRoleRuntimeExtension(
         void Promise.resolve(attendance.dispose()).then(
           undefined,
           (error) => {
+            const diagnostic = error instanceof Error ? error.message : String(error);
             try {
               sitianReport({
                 level: "event",
                 kind: "navigator-dispose-failure",
-                payload: {
-                  diagnostic: error instanceof Error ? error.message : String(error),
-                },
+                cwd: navigatorCwd,
+                sessionParent: navigatorSessionParent,
+                payload: { diagnostic },
                 source: "role-runtime",
               });
             } catch (recordError) {
               envelopeHost.appendEntry?.("ak-navigator-dispose-failure", {
-                diagnostic: error instanceof Error ? error.message : String(error),
+                diagnostic,
                 recordFailure: recordError instanceof Error ? recordError.message : String(recordError),
               });
             }
@@ -1163,6 +1190,7 @@ export function createRoleRuntimeExtension(
       settleNavigatorProjection,
     );
     roleHost.on("input", (event) => {
+      const text = event.text;
       const role = roleHost.getFlag(ROLE_FLAG.name);
       if (role !== undefined && !admitted) return { action: "handled" as const };
       // Reviewer: recover original request; Pi argv may already carry native form.
@@ -1175,14 +1203,19 @@ export function createRoleRuntimeExtension(
         reviewerOriginalRequest =
           roleHost.capabilities?.skillOriginalRequest?.(
             activeReviewerParent.skillBinding.name,
-            event.text,
-          ) ?? event.text;
-        return { action: "continue" as const };
+            text,
+          ) ?? text;
+        return text === event.text
+          ? { action: "continue" as const }
+          : { action: "transform" as const, text };
       }
-      return { action: "continue" as const };
+      return text === event.text
+        ? { action: "continue" as const }
+        : { action: "transform" as const, text };
     });
     roleHost.on("before_agent_start", async (event, ctx) => {
       const role = roleHost.getFlag(ROLE_FLAG.name);
+      const prompt = event.prompt;
       if (role === undefined) return;
       if (!admitted || selectedRole !== role) {
         failInfrastructure(new ActivationBarrierError(role), ctx);
@@ -1207,7 +1240,7 @@ export function createRoleRuntimeExtension(
           // output payload (#836 targets the latter): the human's own raw
           // prompt bytes, copied verbatim into Navigator's work context when
           // nothing else has supplied a subject yet.
-          const subject = event.prompt.trim();
+          const subject = prompt.trim();
           if (subject !== "") {
             const root = subjectPath(ctx.sessionManager.getSessionDir(), ctx.cwd);
             const subjectProvenance = "user_prompt" satisfies NavigatorSubjectProvenance;
@@ -1231,7 +1264,7 @@ export function createRoleRuntimeExtension(
         if (!reviewerExpansionCaptured) {
           if (reviewerOriginalRequest !== undefined) {
             activeReviewerParent.skillBinding.captureExpansion(
-              roleHost.capabilities?.skillExpansion(event.prompt),
+              roleHost.capabilities?.skillExpansion(prompt),
               reviewerOriginalRequest,
             );
           }
@@ -1255,6 +1288,54 @@ export function createRoleRuntimeExtension(
         };
       }
     });
+    // #879: engine coordinates ride readingMaterial only when station-child
+    // officer dialogue replaced the ordinary transport prompt (no double fold).
+    roleHost.on("before_agent_start", () => {
+      const role = selectedRole ?? roleHost.getFlag(ROLE_FLAG.name);
+      if (typeof role !== "string" || !isOfficerReviewSeat(role)) return;
+      if (roleHost.getFlag(STATION_CHILD_FLAG.name) !== true) return;
+      const engine = resolveEngineName((name) => roleHost.getFlag(name));
+      if (engine === undefined || dependencies.packageRoot === undefined) return;
+      const engineModel = resolveEngineModel((name) => roleHost.getFlag(name));
+      const material = engineSessionMaterialFromOptions({
+        engine,
+        ...(engineModel === undefined ? {} : { engineModel }),
+        packageRoot: dependencies.packageRoot,
+      });
+      if (material === undefined) return;
+      return {
+        readingMaterial: {
+          kind: "engine-session-material" as const,
+          name: material.name,
+          ...(material.model === undefined ? {} : { model: material.model }),
+          ...(material.materialPath === undefined ? {} : { materialPath: material.materialPath }),
+        },
+      };
+    });
+    roleHost.on("before_agent_start", () => {
+      const path = roleHost.getFlag(INSPECTOR_SOURCE_RUN_FLAG.name);
+      if (typeof path !== "string" || path.trim() === "") return;
+      return {
+        readingMaterial: {
+          kind: "inspector-parent-binding" as const,
+          sourceRunPath: path,
+        },
+      };
+    });
+    // #879: single shared owner of station-child 0081 case-dossier → readingMaterial fold.
+    // post-admission freezes under run/attachments/case-dossier/; this handler alone
+    // projects it onto the existing agent-start materials face (Pi + envelope collect).
+    // Role modules must not re-read the freeze (ADR 0018 lifecycle; no duplicate fold).
+    roleHost.on("before_agent_start", async (_event, ctx) => {
+      const runDir = runDirectoryFromHostContext(ctx);
+      if (runDir === undefined) return;
+      const { loadCaseDossierReadingMaterial } = await import(
+        "./public-cli/case-dossier-delivery.ts"
+      );
+      const caseDossier = await loadCaseDossierReadingMaterial(runDir);
+      if (caseDossier === undefined) return;
+      return { readingMaterial: caseDossier };
+    });
     roleHost.on("tool_result", async (event) => {
       const role = selectedRole;
       if (role === undefined) return;
@@ -1341,7 +1422,7 @@ export function createRoleRuntimeExtension(
           display: false,
         }, { triggerTurn: true, deliverAs: "followUp" });
       } else if (receiptDelivery.nextAction() === "no-receipt" && !noReceiptRecorded) {
-        const runPointer = process.env.AK_ROLE_RUN_DIR;
+        const runPointer = runDirectoryFromHostContext(ctx);
         if (runPointer !== undefined) {
           noReceiptRecorded = true;
           const facts = receiptDelivery.facts({ runPointer, attemptPointer: `current:${runPointer}` });
@@ -1750,8 +1831,8 @@ export function createRoleRuntimeExtension(
       provider: string,
       ctx: HostContext,
     ): Promise<void> => {
-      const runDir = process.env.AK_ROLE_RUN_DIR;
-      if (typeof runDir !== "string" || runDir.trim() === "") return;
+      const runDir = runDirectoryFromHostContext(ctx);
+      if (runDir === undefined) return;
       try {
         await recordTypedProviderHttpStatus(runDir, { httpStatus: status, provider });
       } catch (error) {
@@ -1785,10 +1866,9 @@ export function createRoleRuntimeExtension(
         const underlying = priorFetch;
         globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
           const response = await underlying(input, init);
-          const runDir = process.env.AK_ROLE_RUN_DIR;
+          const runDir = runDirectoryFromHostContext(ctx);
           if (
-            typeof runDir === "string"
-            && runDir.trim() !== ""
+            runDir !== undefined
             && typeof response?.status === "number"
             && (response.status < 200 || response.status >= 300)
           ) {
@@ -1887,6 +1967,8 @@ export function createRoleRuntimeExtension(
           && entry.role !== "navigator"
           && !isStationChild
         ) {
+          navigatorSessionParent = ctx.sessionManager.getSessionFile();
+          navigatorCwd = ctx.cwd;
           let work: NavigatorWorkContext;
           let contextError: unknown;
           if (dependencies.loadNavigatorWorkContext === undefined) {

package/src/run-terminal-artifacts.ts

@@ -9,6 +9,8 @@
 import { readdir, readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
+import { roleRunArtifactsDirectory } from "./role-run-placement.ts";
+
 export const RUN_TERMINAL_ARTIFACT_FILES = [
   "report.json",
   "error.json",
@@ -191,7 +193,7 @@ function presentUniqueFallbackBoundToRun(
 export async function readRunTerminalArtifact(
   runDirectory: string,
 ): Promise<RunTerminalArtifactRead> {
-  const artifactsDir = join(runDirectory, "artifacts");
+  const artifactsDir = roleRunArtifactsDirectory(runDirectory);
   for (const file of RUN_TERMINAL_ARTIFACT_FILES) {
     const path = join(artifactsDir, file);
     const read = await readTerminalArtifactAtPath(path, file);

package/src/run-ticket-number.ts

@@ -1,11 +1,17 @@
 /**
  * Typed ticketNumber reader for a retained run's durable pages.
- * admitted-request.json first, invocation.json fallback. Missing page (ENOENT)
- * → try next / undefined; damage and non-ENOENT IO failures propagate.
+ * Board pages first (admitted-request, then invocation); migration derivation
+ * page last so worktree-derived placement stays readable without forging a
+ * board assertion. Missing page (ENOENT) → try next / undefined; damage and
+ * non-ENOENT IO failures propagate.
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+/** Sole on-disk page for worktree-basename ticket derivation (#865). */
+export const MIGRATION_TICKET_DERIVATION_PAGE =
+  "migration-ticket-derivation.json" as const;
+
 function isEnoent(error: unknown): boolean {
   return (
     error instanceof Error &&
@@ -14,40 +20,94 @@ function isEnoent(error: unknown): boolean {
   );
 }
 
-function ticketFromRecord(record: Record<string, unknown>): number | undefined {
-  const ticketNumber = record.ticketNumber;
-  if (
-    typeof ticketNumber === "number" &&
-    Number.isSafeInteger(ticketNumber) &&
-    ticketNumber >= 1
-  ) {
-    return ticketNumber;
+/** Sole safe-positive ticket invariant (bind / admission / placement / readers). */
+export function isSafePositiveTicketNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+
+/** Loud reject for non-safe-positive ticket numbers before placement or bind. */
+export function requireSafePositiveTicketNumber(
+  ticketNumber: number,
+  context = "ticketNumber",
+): number {
+  if (!isSafePositiveTicketNumber(ticketNumber)) {
+    throw new Error(
+      `${context} requires a safe positive integer, got ${String(ticketNumber)}`,
+    );
   }
-  return undefined;
+  return ticketNumber;
 }
 
-async function readPageTicketNumber(
-  runDirectory: string,
-  page: "admitted-request.json" | "invocation.json",
-): Promise<number | undefined> {
+function ticketFromRecord(record: Record<string, unknown>): number | undefined {
+  return isSafePositiveTicketNumber(record.ticketNumber)
+    ? record.ticketNumber
+    : undefined;
+}
+
+async function readJsonObject(
+  path: string,
+): Promise<Record<string, unknown> | undefined> {
   try {
-    const raw = JSON.parse(await readFile(join(runDirectory, page), "utf8")) as unknown;
+    const raw: unknown = JSON.parse(await readFile(path, "utf8"));
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
       return undefined;
     }
-    return ticketFromRecord(raw as Record<string, unknown>);
+    return raw as Record<string, unknown>;
   } catch (error) {
     if (isEnoent(error)) return undefined;
     throw error;
   }
 }
 
-/** Sole reader of ticketNumber from a retained run's admitted then invocation pages. */
+async function readBoardPageTicketNumber(
+  runDirectory: string,
+  page: "admitted-request.json" | "invocation.json",
+): Promise<number | undefined> {
+  const record = await readJsonObject(join(runDirectory, page));
+  if (record === undefined) return undefined;
+  return ticketFromRecord(record);
+}
+
+/**
+ * Board-only ticketNumber (admitted → invocation). Placement attribution and
+ * any caller that must ignore derivation pages use this sole projection.
+ */
+export async function readBoardTicketNumber(
+  runDirectory: string,
+): Promise<number | undefined> {
+  return (
+    (await readBoardPageTicketNumber(runDirectory, "admitted-request.json")) ??
+    (await readBoardPageTicketNumber(runDirectory, "invocation.json"))
+  );
+}
+
+/**
+ * Worktree-derivation ticket only — never a board assertion. Callers that must
+ * distinguish board vs derived use this; effective readers use readRunTicketNumber.
+ */
+export async function readMigrationDerivedTicketNumber(
+  runDirectory: string,
+): Promise<number | undefined> {
+  const record = await readJsonObject(
+    join(runDirectory, MIGRATION_TICKET_DERIVATION_PAGE),
+  );
+  if (record === undefined) return undefined;
+  if (record.derivation !== "worktree-path-basename") return undefined;
+  return ticketFromRecord(record);
+}
+
+/**
+ * Display / historical-placement ticketNumber for a retained run:
+ * board admitted → board invocation → migration derivation.
+ * Derivation is last so board wins. Callers that mint, resume, inherit, or
+ * otherwise write ticket identity must use readBoardTicketNumber instead —
+ * derived placement is never a board assertion.
+ */
 export async function readRunTicketNumber(
   runDirectory: string,
 ): Promise<number | undefined> {
   return (
-    (await readPageTicketNumber(runDirectory, "admitted-request.json")) ??
-    (await readPageTicketNumber(runDirectory, "invocation.json"))
+    (await readBoardTicketNumber(runDirectory)) ??
+    (await readMigrationDerivedTicketNumber(runDirectory))
   );
 }

package/src/sitian-appender.ts

@@ -11,7 +11,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 
 import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
@@ -204,14 +204,6 @@ export function resolveSitianVolumeCategory(kind: string): string {
   return kind;
 }
 
-function safeBookKey(cwd: string): string {
-  try {
-    return resolveBookKeyFromGit(cwd);
-  } catch {
-    return basename(resolve(cwd)) || "default";
-  }
-}
-
 type SitianRecordPath = {
   readonly sessionDir: string;
   readonly recordFile: string;
@@ -223,30 +215,35 @@ export function resolveSitianRecordPathInLedger(
   input: SitianRecordInput,
   ledgerHome: string,
 ): SitianRecordPath {
-  const cwd = input.cwd ?? process.cwd();
   const category = resolveSitianVolumeCategory(input.kind);
+  const ticketNumber = category === "ticket-provenance"
+    ? typeof input.subject === "string" && /^[1-9][0-9]*$/.test(input.subject)
+      ? input.subject
+      : typeof input.subject === "object"
+        && typeof input.subject.ticketNumber === "number"
+        && Number.isSafeInteger(input.subject.ticketNumber)
+        && input.subject.ticketNumber > 0
+        ? String(input.subject.ticketNumber)
+        : undefined
+    : undefined;
 
   let sessionDir: string;
-
-  if (input.sessionParent !== undefined && input.sessionParent.length > 0 && physicallyContainedIn(ledgerHome, input.sessionParent)) {
-    sessionDir = join(dirname(input.sessionParent), category);
+  if (ticketNumber !== undefined) {
+    // docs/dossier-topology.md: ticket dir holds records.jsonl + 起居录.md directly.
+    const bookDir = activationBookDirectory(
+      ledgerHome,
+      resolveBookKeyFromGit(input.cwd ?? process.cwd()),
+    );
+    sessionDir = join(bookDir, ticketNumber);
   } else {
-    const bookKey = safeBookKey(cwd);
-    const bookDir = activationBookDirectory(ledgerHome, bookKey);
-    if (input.subject !== undefined) {
-      let subjectStr: string;
-      if (typeof input.subject === "string") {
-        subjectStr = input.subject;
-      } else if (typeof input.subject.runId === "string" && input.subject.runId.length > 0) {
-        subjectStr = input.subject.runId;
-      } else {
-        subjectStr = JSON.stringify(input.subject);
-      }
-      const digest = createHash("sha256").update(subjectStr).digest("hex").slice(0, 32);
-      sessionDir = join(bookDir, category, digest);
-    } else {
-      sessionDir = join(bookDir, category);
+    if (
+      input.sessionParent === undefined
+      || input.sessionParent.length === 0
+      || !physicallyContainedIn(ledgerHome, input.sessionParent)
+    ) {
+      throw new Error("Sitian record ownership requires a parent session inside the ledger home");
     }
+    sessionDir = join(dirname(input.sessionParent), category);
   }
 
   const recordFile = join(sessionDir, "records.jsonl");