@akagilnc/pi-workflow-roles 0.1.3565 → 0.1.3572

package/src/pi/role-turn-host.ts

@@ -146,6 +146,14 @@ function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
       return ["--ak-role", "gatekeeper"];
     case "navigator":
       return ["--ak-role", "navigator"];
+    case "diarist":
+      return [
+        "--ak-role",
+        "diarist",
+        ...(activation.sourcesPath === undefined
+          ? []
+          : ["--ak-diarist-sources", activation.sourcesPath]),
+      ];
     default: {
       const _exhaustive: never = activation;
       return _exhaustive;

package/src/public-cli/cli.ts

@@ -51,6 +51,7 @@ import {
   parseCoderArgv,
   parseCollectorArgv,
   parseCountersignArgv,
+  parseDiaristArgv,
   parseGleanerLeftArgv,
   parseDoctorArgv,
   parseFixerArgv,
@@ -78,6 +79,7 @@ import { runPublicCoder, runPublicCoderResume } from "./coder-run.ts";
 import { runPublicInstructionSeat, runPublicInstructionSeatResume } from "./instruction-seat-run.ts";
 import { runPublicCollector, runPublicCollectorResume } from "./collector-run.ts";
 import { runPublicCountersign, runPublicCountersignResume } from "./countersign-run.ts";
+import { runPublicDiarist, runPublicDiaristResume } from "./diarist-run.ts";
 import { runPublicGleanerLeft, runPublicGleanerLeftResume } from "./gleaner-left-run.ts";
 import { runPublicDoctor, runPublicDoctorResume } from "./doctor-run.ts";
 import { runPublicFixer, runPublicFixerResume } from "./fixer-run.ts";
@@ -126,6 +128,7 @@ const RESUME_SEAT_DISPATCH: Record<
   inspector: { seat: "inspector", run: runPublicInspectorResume },
   gatekeeper: { seat: "gatekeeper", run: runPublicInstructionSeatResume },
   navigator: { seat: "navigator", run: runPublicInstructionSeatResume },
+  diarist: { seat: "diarist", run: runPublicDiaristResume },
 };
 import {
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
@@ -168,6 +171,7 @@ export const PUBLIC_ROLE_ARGV = {
   reviewer: { parse: parseReviewerArgv, options: optionsForOwner("reviewer") },
   gatekeeper: { parse: parseGatekeeperArgv, options: optionsForOwner("gatekeeper") },
   navigator: { parse: parseNavigatorArgv, options: optionsForOwner("navigator") },
+  diarist: { parse: parseDiaristArgv, options: optionsForOwner("diarist") },
   /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
   analyst: { parse: parseAnalystArgv, options: optionsForOwner("analyst") },
 } as const;
@@ -1311,6 +1315,31 @@ export async function runAkRole(
       };
     }
 
+    // Diarist public run path (#708): 起居郎 is summoned like any other seat.
+    if (parsed.command === "diarist") {
+      const agentDir = resolveAgentDir(env, home);
+      const cwd = env.cwd ?? process.cwd();
+      const config = await loadAndValidateConfig(home, env.packageRoot);
+      const credentials =
+        env.credentials ?? (await loadCredentialProviders(agentDir));
+      const seat = resolveEffectiveSeat(
+        config,
+        "diarist",
+        credentials,
+        invocationFromParsed(parsed),
+      );
+      const result = await runPublicDiarist(
+        parsed.args,
+        createRoleEnvironment(env, { role: "diarist", home, agentDir, cwd, credentials, seat, config }),
+        io,
+        PUBLIC_ROLE_ARGV.diarist.parse,
+      );
+      return {
+        exitCode: result.exitCode,
+        ...(result.terminal === undefined ? {} : { terminal: result.terminal }),
+      };
+    }
+
     // Coder public run path with package-owned TDD method (#109).
     if (parsed.command === "coder") {
       const agentDir = resolveAgentDir(env, home);

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

@@ -1,20 +1,11 @@
 /**
- * Public Countersign Role run: admit ticket materials → diarist pipeline step →
- * shared post-admission coordinator → settle Terminal result
- * (#572 / ADR 0074 / ADR 0075). #599: manual resume continues the exact session.
- * Diarist is a prior station on the court pipeline, not a countersign call.
- * Unbound admission resolves ticket via shared seat LLM bind (#635) before the diary station.
+ * Public Countersign Role run: admit ticket materials → shared post-admission
+ * coordinator → settle Terminal result (#572 / ADR 0074). #599: manual resume
+ * continues the exact session. Unbound admission resolves its ticket via the
+ * shared seat LLM bind (#635). Who runs 起居郎, and when, is the caller's
+ * composition (ADR 0010 / ADR 0075 `no-call-rule`) — not this seat's business.
  */
 import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contracts.ts";
-import {
-  createDiaristIssueFaceFetcher,
-  DiaristIssueSourceError,
-  resolveDiaristGithubOrigin,
-  runDiarist,
-  type DiaristIssueFace,
-  type DiaristRunResult,
-} from "../diarist.ts";
-import { appendIssueSourceFailureDiagnostic } from "../ticket-provenance.ts";
 import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
 import { CliUsageError } from "./cli-errors.ts";
 import {
@@ -29,7 +20,6 @@ import {
   ticketNumberFromProbe,
   tryResumeSameTicketSeatRun,
 } from "./seat-ticket-binding.ts";
-import { tryHomeFromAkRolesPath } from "../activation-ledger-topology.ts";
 import {
   prepareSummonsResumeMaterials,
   runPostAdmissionOneShot,
@@ -194,7 +184,6 @@ export async function runPublicCountersign(
           turnRequest,
           buildCountersignTurnRequest(admitted, turnProjection),
         );
-        await runCountersignDiaristStation(admitted, env);
       },
     }),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
@@ -222,10 +211,9 @@ function countersignAdapters(options?: {
 
 /**
  * Resume a previously admitted Countersign run (#599 / DK-3 / #637).
- * Restores role/ticket/session identity. Every court re-entry runs the diarist
- * station first (ADR 0075 refresh-every-court). Same-ticket summons deliver this
- * turn's instruction + frozen attachments on the resume prompt; manual resume
- * keeps package-envelope / caller-message semantics and birth attachments.
+ * Restores role/ticket/session identity. Same-ticket summons deliver this turn's
+ * instruction + frozen attachments on the resume prompt; manual resume keeps
+ * package-envelope / caller-message semantics and birth attachments.
  */
 export async function runPublicCountersignResume(
   request: PublicResumeRequest,
@@ -261,115 +249,7 @@ export async function runPublicCountersignResume(
         ),
       );
     },
-    adapters: countersignAdapters({
-      beforeDispatch: async (admitted) => {
-        await runCountersignDiaristStation(admitted, env);
-      },
-    }),
+    adapters: countersignAdapters(),
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
-
-/**
- * Court-pipeline prior station: refresh ticket-provenance before countersign turn.
- * Caller-invisible — collector failures append durable volume diagnostics and the
- * station continues; issue-source / ADR source-read / watermark honesty failures
- * leave typed durable diagnostics and propagate (失败诚实).
- * Missing ticketNumber (true-unbound after pre-court resolution) skips the station
- * — no diary is minted for a true-unbound run.
- *
- * Issue body/comments come from the shared GitHub seam only. Attachments stay
- * attachments — never merged and mislabeled as issue-body-comment.
- * Bound ticket never silently degrades to “no issue face”.
- */
-export async function runCountersignDiaristStation(
-  admitted: AdmittedCountersignInvocation,
-  env: Pick<CountersignRunEnv, "cwd" | "packageRoot">,
-): Promise<DiaristRunResult | undefined> {
-  if (admitted.ticketNumber === undefined) return undefined;
-
-  const issueFace = await loadBoundIssueFace(admitted);
-  const home = tryHomeFromAkRolesPath(admitted.runDirectory);
-
-  const result = await runDiarist({
-    ticketNumber: admitted.ticketNumber,
-    cwd: admitted.projectRoot,
-    ...(home === undefined ? {} : { home }),
-    issueFace,
-    sessionCwds: [admitted.projectRoot, env.cwd],
-    ...(env.packageRoot === undefined ? {} : { packageRoot: env.packageRoot }),
-  });
-  return result;
-}
-
-/**
- * Acquire issue face for a bound ticket. Failures are typed + durable on the
- * ticket-provenance volume, then propagated — never washed into empty face.
- */
-function persistIssueSourceFailure(
-  admitted: AdmittedCountersignInvocation,
-  ticketNumber: number,
-  error: DiaristIssueSourceError,
-): never {
-  const home = tryHomeFromAkRolesPath(admitted.runDirectory);
-  appendIssueSourceFailureDiagnostic({
-    ticketNumber,
-    cwd: admitted.projectRoot,
-    ...(home === undefined ? {} : { home }),
-    cause: error.message,
-    reason: error.reason,
-  });
-  throw error;
-}
-
-async function loadBoundIssueFace(
-  admitted: AdmittedCountersignInvocation,
-): Promise<DiaristIssueFace> {
-  const ticketNumber = admitted.ticketNumber;
-  if (ticketNumber === undefined) {
-    throw new Error("loadBoundIssueFace requires a bound ticketNumber");
-  }
-
-  const origin = resolveDiaristGithubOrigin(admitted.projectRoot);
-  if (origin === undefined) {
-    persistIssueSourceFailure(
-      admitted,
-      ticketNumber,
-      new DiaristIssueSourceError(
-        "origin-unresolved",
-        `bound ticket #${ticketNumber} issue face requires a resolvable github.com origin remote`,
-      ),
-    );
-  }
-
-  const fetcher = createDiaristIssueFaceFetcher();
-  let face: DiaristIssueFace | undefined;
-  try {
-    face = await fetcher({
-      owner: origin.owner,
-      repo: origin.repo,
-      ticketNumber,
-    });
-  } catch (error) {
-    const typed =
-      error instanceof DiaristIssueSourceError
-        ? error
-        : new DiaristIssueSourceError(
-            "issue-unavailable",
-            `issue face fetch failed for ${origin.owner}/${origin.repo}#${ticketNumber}`,
-            { cause: error },
-          );
-    persistIssueSourceFailure(admitted, ticketNumber, typed);
-  }
-  if (face === undefined) {
-    persistIssueSourceFailure(
-      admitted,
-      ticketNumber,
-      new DiaristIssueSourceError(
-        "issue-unavailable",
-        `issue face unavailable for ${origin.owner}/${origin.repo}#${ticketNumber}`,
-      ),
-    );
-  }
-  return face;
-}

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

@@ -0,0 +1,312 @@
+/**
+ * Public Diarist (起居郎) Role run — #708 / ADR 0075 `diarist-is-role`.
+ * Same admit → post-admission → settle shape as the other instruction seats.
+ * Semantic collection is the role's own turn; this seat only freezes the
+ * mechanical source catalog the turn selects from (`diarist-collector-is-own-turn`).
+ * Who calls it and in what order is the caller's business (ADR 0010 `no-call-rule`).
+ */
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contracts.ts";
+import {
+  loadDiaristIssueFace,
+  prepareDiaristSourceCatalog,
+  serializeDiaristSourceCatalog,
+} from "../diarist.ts";
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import {
+  admitDiaristInvocation,
+  buildInstructionTransportPrompt,
+  type AdmittedDiaristInvocation,
+  type ParseDiaristArgvResult,
+} from "./invocation.ts";
+import {
+  applyInstructionTicketProbe,
+  probeInstructionTicket,
+  ticketNumberFromProbe,
+  tryResumeSameTicketSeatRun,
+} from "./seat-ticket-binding.ts";
+import {
+  prepareSummonsResumeMaterials,
+  runPostAdmissionOneShot,
+  runPostAdmissionSeatResume,
+  resumeTurnRequestProjectionOptions,
+  type PostAdmissionAdapters,
+  type PostAdmissionEnv,
+} from "./post-admission.ts";
+import {
+  loadResumableDiaristRun,
+  markRunAdmitted,
+  readRoleRunIdentity,
+  type PublicResumeRequest,
+  type SameTicketSummonsMaterials,
+} from "./run-lifecycle.ts";
+import {
+  presentStructuralRejection,
+  trySettleDiaristTerminalResult,
+} 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 DiaristRunEnv = PostAdmissionEnv & {
+  principalAuthority: DurablePrincipalAuthority;
+  createRunId?: () => string;
+};
+
+/** Frozen catalog filename inside the run dossier (durable material, not argv). */
+const DIARIST_SOURCE_CATALOG_FILE = "diarist-sources.json" as const;
+
+/** Neutral path identifier only (ADR 0073) — catalog bytes stay on disk. */
+function withDiaristCatalogPath(
+  prompt: string,
+  sourcesPath: string | undefined,
+): string {
+  if (sourcesPath === undefined || sourcesPath.trim() === "") return prompt;
+  return `${prompt}\n\n已冻结来源文件（路径）：\n- ${sourcesPath}`;
+}
+
+/** Project admitted invocation onto the host-neutral turn request. */
+export function buildDiaristTurnRequest(
+  admitted: AdmittedDiaristInvocation,
+  options: RoleTurnRequestProjectionOptions,
+  sourcesPath?: string,
+): RoleTurnRequest {
+  const continuation =
+    sourcesPath === undefined
+      ? options.continuation
+      : {
+          ...options.continuation,
+          prompt: withDiaristCatalogPath(options.continuation.prompt, sourcesPath),
+        };
+  return projectRoleTurnRequest(
+    admitted,
+    {
+      activation: {
+        role: "diarist" as const,
+        ...(sourcesPath === undefined ? {} : { sourcesPath }),
+      },
+    },
+    { ...options, continuation },
+  );
+}
+
+/**
+ * Mechanical source enumeration for a bound summons: establish the per-ticket
+ * volume, freeze this turn's candidate catalog into the run dossier.
+ * A true-unbound summons has no ticket, so no diary is minted — undefined.
+ *
+ * A run that has not settled yet (crash-resume, open-court continuation) keeps
+ * the catalog its candidateIndexes were minted against — re-enumerating there
+ * would rebind the role's indexes to bytes it never saw. Only a settled run
+ * re-enumerates on the next same-ticket summons (ADR 0075 增量).
+ */
+async function freezeDiaristSourceCatalog(
+  admitted: AdmittedDiaristInvocation,
+  env: Pick<DiaristRunEnv, "cwd" | "home">,
+): Promise<string | undefined> {
+  if (admitted.ticketNumber === undefined) return undefined;
+  const path = join(admitted.runDirectory, DIARIST_SOURCE_CATALOG_FILE);
+  if (existsSync(path)) {
+    const identity = await readRoleRunIdentity(admitted.runDirectory);
+    if (identity !== undefined && identity.state !== "terminal") return path;
+  }
+  const issueFace = await loadDiaristIssueFace({
+    ticketNumber: admitted.ticketNumber,
+    projectRoot: admitted.projectRoot,
+    home: env.home,
+  });
+  const catalog = await prepareDiaristSourceCatalog({
+    ticketNumber: admitted.ticketNumber,
+    cwd: admitted.projectRoot,
+    home: env.home,
+    issueFace,
+    sessionCwds: [admitted.projectRoot, env.cwd],
+  });
+  await writeFile(path, serializeDiaristSourceCatalog(catalog), "utf8");
+  return path;
+}
+
+function diaristAdapters(options?: {
+  beforeDispatch?: (
+    admitted: AdmittedDiaristInvocation,
+  ) => void | Promise<void>;
+}): PostAdmissionAdapters<AdmittedDiaristInvocation> {
+  return {
+    trySettle: (admitted, authority, scope) =>
+      trySettleDiaristTerminalResult(admitted, authority, scope),
+    shouldPresentSettled: () => true,
+    ...(options?.beforeDispatch === undefined
+      ? {}
+      : { beforeDispatch: options.beforeDispatch }),
+  };
+}
+
+export async function runPublicDiarist(
+  argv: readonly string[],
+  env: DiaristRunEnv,
+  io: CliIo,
+  parseDiaristArgv: (args: readonly string[]) => ParseDiaristArgvResult,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedDiaristInvocation;
+  terminal?: TerminalResult;
+}> {
+  let parsed: ParseDiaristArgvResult;
+  try {
+    parsed = parseDiaristArgv(argv);
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  // #637: same ticket → resume this seat's prior run with this summons' materials.
+  // Probe captures DiaristTicketResolutionError so admit+beforeDispatch can settle
+  // controlled failure (bare pre-admit throw skips terminal settlement).
+  const projectRoot = parsed.project ?? env.cwd;
+  const ticketProbe = await probeInstructionTicket(
+    parsed.instruction,
+    projectRoot,
+    env,
+  );
+  const probedTicketNumber = ticketNumberFromProbe(ticketProbe);
+  if (probedTicketNumber !== undefined) {
+    const summons: SameTicketSummonsMaterials = {
+      instruction: parsed.instruction,
+      instructionEmpty: parsed.instruction.trim() === "",
+      attachmentPaths: parsed.attachmentPaths,
+    };
+    const resumed = await tryResumeSameTicketSeatRun({
+      home: env.home,
+      projectRoot,
+      role: "diarist",
+      ticketNumber: probedTicketNumber,
+      freshSummons: env.freshSummons,
+      summons,
+      resume: (runId, materials) =>
+        runPublicDiaristResume(
+          { runId, ...(materials === undefined ? {} : { summons: materials }) },
+          env,
+          io,
+        ),
+    });
+    if (resumed !== undefined) return resumed;
+  }
+
+  let admitted: AdmittedDiaristInvocation;
+  try {
+    admitted = await admitDiaristInvocation({
+      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 }),
+    });
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  await markRunAdmitted(admitted, env.principalAuthority);
+
+  const turnProjection: RoleTurnRequestProjectionOptions = {
+    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,
+        }),
+      ),
+    },
+  };
+  // Mutable shell: ticket bind + catalog freeze re-project activation before executeTurn.
+  const turnRequest = buildDiaristTurnRequest(admitted, turnProjection);
+
+  return await runPostAdmissionOneShot({
+    admitted,
+    env,
+    io,
+    request: turnRequest,
+    adapters: diaristAdapters({
+      beforeDispatch: async (admittedSeat) => {
+        await applyInstructionTicketProbe(admittedSeat, ticketProbe);
+        const sourcesPath = await freezeDiaristSourceCatalog(admittedSeat, env);
+        Object.assign(
+          turnRequest,
+          buildDiaristTurnRequest(admittedSeat, turnProjection, sourcesPath),
+        );
+      },
+    }),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}
+
+/**
+ * Resume a previously admitted Diarist run (#708 / ADR 0079 同票传召 = resume).
+ * A re-entry into a settled run re-enumerates fresh sources; the offered
+ * watermark keeps the pass incremental so already-seen blocks are not
+ * re-offered. An unfinished run keeps its frozen catalog (see freeze above).
+ */
+export async function runPublicDiaristResume(
+  request: PublicResumeRequest,
+  env: DiaristRunEnv,
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedDiaristInvocation;
+  terminal?: TerminalResult;
+}> {
+  return await runPostAdmissionSeatResume({
+    request,
+    env,
+    io,
+    load: (effective) =>
+      loadResumableDiaristRun(env.home, effective.runId, env.principalAuthority),
+    buildTurnRequest: async (admitted, effective) => {
+      const summonsPrepared = await prepareSummonsResumeMaterials(
+        admitted.runDirectory,
+        effective.summons,
+      );
+      const sourcesPath = await freezeDiaristSourceCatalog(admitted, env);
+      return buildDiaristTurnRequest(
+        admitted,
+        resumeTurnRequestProjectionOptions(
+          admitted,
+          effective,
+          env,
+          summonsPrepared,
+        ),
+        sourcesPath,
+      );
+    },
+    adapters: diaristAdapters(),
+    ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+  });
+}

package/src/public-cli/invocation.ts

@@ -151,6 +151,10 @@ export type AdmittedNavigatorInvocation = AdmittedRoleInvocationBase & {
   readonly role: "navigator";
 };
 
+export type AdmittedDiaristInvocation = AdmittedRoleInvocationBase & {
+  readonly role: "diarist";
+};
+
 export type CoderPhase = "plan" | "apply";
 
 export type AdmittedCoderInvocation = AdmittedRoleInvocationBase & {
@@ -234,6 +238,7 @@ export type AdmittedRoleInvocation =
   | AdmittedInspectorInvocation
   | AdmittedGatekeeperInvocation
   | AdmittedNavigatorInvocation
+  | AdmittedDiaristInvocation
   | AdmittedCoderInvocation
   | AdmittedFixerInvocation
   | AdmittedCollectorInvocation
@@ -586,6 +591,7 @@ export type ParseCountersignArgvResult = ParseInstructionArgvResult;
 export type ParseInspectorArgvResult = ParseInstructionArgvResult;
 export type ParseGatekeeperArgvResult = ParseInstructionArgvResult;
 export type ParseNavigatorArgvResult = ParseInstructionArgvResult;
+export type ParseDiaristArgvResult = ParseInstructionArgvResult;
 
 /** Positive ticket number for analyst query-scope face (and shared integer parse). */
 export function parsePositiveTicketNumber(
@@ -606,7 +612,7 @@ export function parsePositiveTicketNumber(
 /** 共享解析体：同形 owner 的 argv → instruction/attachments/project。 */
 function parseInstructionArgv(
   args: readonly string[],
-  owner: "judge" | "countersign" | "inspector" | "gatekeeper" | "navigator",
+  owner: "judge" | "countersign" | "inspector" | "gatekeeper" | "navigator" | "diarist",
 ): ParseInstructionArgvResult {
   const attachmentPaths: string[] = [];
   let project: string | undefined;
@@ -846,6 +852,10 @@ export function parseNavigatorArgv(args: readonly string[]): ParseNavigatorArgvR
   return parseInstructionArgv(args, "navigator");
 }
 
+export function parseDiaristArgv(args: readonly string[]): ParseDiaristArgvResult {
+  return parseInstructionArgv(args, "diarist");
+}
+
 /**
  * Parse Coder-specific argv after the `coder` token.
  * Phase defaults to apply; spellings from PUBLIC_OPTION_TABLE.coder (#342).
@@ -1045,6 +1055,7 @@ export type AdmitInspectorInvocationOptions = AdmitJudgeInvocationOptions & {
 
 export type AdmitGatekeeperInvocationOptions = AdmitInspectorInvocationOptions;
 export type AdmitNavigatorInvocationOptions = AdmitInspectorInvocationOptions;
+export type AdmitDiaristInvocationOptions = AdmitInspectorInvocationOptions;
 
 /**
  * Shared instruction-seat admission for Judge and Inspector: project check,
@@ -1053,7 +1064,7 @@ export type AdmitNavigatorInvocationOptions = AdmitInspectorInvocationOptions;
  * Ticket binding is post-admission via shared seat LLM path (#635).
  */
 async function admitStandardMaterialInvocation<
-  R extends "judge" | "inspector" | "gatekeeper" | "navigator",
+  R extends "judge" | "inspector" | "gatekeeper" | "navigator" | "diarist",
 >(
   role: R,
   options: AdmitJudgeInvocationOptions & { correlationId?: string },
@@ -1173,6 +1184,16 @@ export async function admitNavigatorInvocation(
   return admitStandardMaterialInvocation("navigator", options);
 }
 
+/**
+ * Admit a direct Diarist (起居郎) run (#708): freeze attachments, persist the
+ * request, reserve session placement — same instruction-seat face.
+ */
+export async function admitDiaristInvocation(
+  options: AdmitDiaristInvocationOptions,
+): Promise<AdmittedDiaristInvocation> {
+  return admitStandardMaterialInvocation("diarist", options);
+}
+
 /** Shared prompt transport for instruction-seat roles (judge/countersign/inspector). */
 export function buildInstructionTransportPrompt(
   admitted: { instruction: string; instructionEmpty: boolean; attachments: readonly { frozenPath: string }[] },

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

@@ -34,6 +34,7 @@ export type OptionOwner =
   | "inspector"
   | "gatekeeper"
   | "navigator"
+  | "diarist"
   | "analyst";
 
 /**
@@ -427,6 +428,11 @@ const COUNTERSIGN_OPTIONS = [
   bindOwner("countersign", SHARED_ATTACH_SEMANTICS),
 ] as const satisfies readonly PublicOptionDefinition[];
 
+const DIARIST_OPTIONS = [
+  bindOwner("diarist", SHARED_PROJECT_SEMANTICS),
+  bindOwner("diarist", SHARED_ATTACH_SEMANTICS),
+] as const satisfies readonly PublicOptionDefinition[];
+
 const CODER_OPTIONS = [
   {
     id: "phase",
@@ -784,6 +790,7 @@ export const PUBLIC_OPTION_TABLE = {
   inspector: INSPECTOR_OPTIONS,
   gatekeeper: GATEKEEPER_OPTIONS,
   navigator: NAVIGATOR_OPTIONS,
+  diarist: DIARIST_OPTIONS,
   analyst: ANALYST_OPTIONS,
 } as const satisfies Record<OptionOwner, readonly PublicOptionDefinition[]>;
 
@@ -804,6 +811,7 @@ export const PUBLIC_ROLE_OPTION_OWNERS = [
   "inspector",
   "gatekeeper",
   "navigator",
+  "diarist",
   "analyst",
 ] as const satisfies readonly PublicRoleOptionOwner[];
 
@@ -1201,6 +1209,16 @@ const ROLE_COMMAND_HELP = {
       'ak-role navigator "刚完成 coder apply 收敛，下一步？"',
     ],
   },
+  diarist: {
+    command: "diarist",
+    summary:
+      "Direct Diarist (起居郎) pass: gather and organize this case's decision basis into its 起居录.",
+    usage: ["ak-role diarist [options] [instruction]"],
+    examples: [
+      'ak-role diarist "整理 #708 的本案依据。"',
+      'ak-role diarist --attach ./design.md "补录本轮设计修订。"',
+    ],
+  },
   notary: {
     command: "notary",
     summary: "Direct Notary document check (quote fidelity + ticket alignment); zero prompt/attachment.",