@akagilnc/pi-workflow-roles 0.1.5941 → 0.1.5949

package/src/diarist-contracts.ts

@@ -31,10 +31,10 @@ export type DiaristOutput =
       readonly ticketNumber?: number | null;
       /**
        * Dialogue bounds: one entry per session volume, each with one or more ranges.
-       * Empty / absent = lawful empty selection (no dialogue this turn).
+       * Empty / null / absent = lawful empty selection (no dialogue this turn).
        * Malformed endpoints → accept hook reasks (`reask-not-explode`).
        */
-      readonly sessions?: readonly TicketProvenanceSession[];
+      readonly sessions?: readonly TicketProvenanceSession[] | null;
       /** Per-ticket dialogue bounds for a single multi-ticket summons (#1107). */
       readonly ticketSessions?: readonly {
         readonly ticketNumber: number;
@@ -65,13 +65,13 @@ export function validateRecordedDiaristOutput(value: unknown): DiaristOutput {
 
 /**
  * Project sessions from a completed diarist payload.
- * Absent key → empty (lawful). Present but unusable → undefined (caller reasks).
+ * Null / absent key → empty (lawful). Non-null but unusable → undefined (caller reasks).
  */
 export function projectDiaristSessions(
   value: unknown,
 ): readonly TicketProvenanceSession[] | undefined {
   const raw = (value as { sessions?: unknown } | null)?.sessions;
-  if (raw === undefined) return [];
+  if (raw == null) return [];
   return projectTicketProvenanceSessions(raw);
 }
 
@@ -115,15 +115,17 @@ export const diaristOutputSchema = withTerminatingOutputDeclarations(
       ticketNumber: Type.Optional(
         Type.Unknown({
           description:
-            "本庭对象票号（正整数）或 null/省略＝真无票；下游走 typed 键；认不出用 status=escalate，不洗成无录。机械层不重判。",
+            "仅有本庭对象时填票号（正整数）；没有就填 null＝真无票；下游走 typed 键；认不出用 status=escalate，不洗成无录。机械层不重判。",
         }),
       ),
       reason: Type.Unknown({
-        description: "status 为 escalate 时：上呈的原因",
+        description: "仅 status 为 escalate 时填上呈的原因；没有就填 null",
       }),
-      sessions: Type.Optional(Type.Unknown({ description: DIARIST_SESSIONS_DESCRIPTION })),
+      sessions: Type.Optional(Type.Unknown({
+        description: `仅单票庭时填对话边界；没有就填 null。${DIARIST_SESSIONS_DESCRIPTION}`,
+      })),
       ticketSessions: Type.Unknown({
-        description: `多票庭逐票对话边界；每票含 ticketNumber（本条边界所归票号，正整数）与 sessions（${DIARIST_SESSIONS_DESCRIPTION}）。一次交卷各票各自分录。与单票 sessions 二选一。`,
+        description: `仅多票庭时填逐票对话边界；没有就填 null。每票含 ticketNumber（本条边界所归票号，正整数）与 sessions（${DIARIST_SESSIONS_DESCRIPTION}）。一次交卷各票各自分录。`,
       }),
     }),
   ),

package/src/doctor-contracts.ts

@@ -72,7 +72,7 @@ const doctorSubmissionObject = Type.Object({
       `逐条资产观察与处方，原样留存。一条可含 targetKey、targetKind（${DOCTOR_TARGET_KINDS.join(" | ")}）、observation、evidenceIds、disposition（${DOCTOR_DISPOSITIONS.join(" | ")}）、assetEvidence（targetKey、targetKind、evidenceId）、guardrails（reproducibleFailure、owningSeamOrInvariant、deletionOrSimplificationSuffices，各项可含 answer、evidenceIds、explanation）、prescription（kind 为 ${DOCTOR_PRESCRIPTION_KINDS.join(" | ")}，另可写 recommendation、necessityExplanation）、lastRealBite（kind 为 ${DOCTOR_BITE_KINDS.join(" | ")}，另可写 targetKey、evidenceId、eligibleEvidenceIds）。不要求任何处方或可复用 finding；缺可复用资产或 bounded-bite 证据只排除对应资产处方。机器不核验。`,
   }),
   reason: Type.Unknown({
-    description: "证据不足以支撑如实证词的原因；仅 refused 时用。",
+    description: "仅 refused 时填证据不足以支撑如实证词的原因；没有就填 null",
   }),
   missingEvidence: Type.Unknown({
     description: "如实证词所需而尚缺的证据，原样留存（如每项 need、targetKeys）。",

package/src/package-contracts/fixer-output.ts

@@ -34,7 +34,7 @@ const fixerOutputObject = Type.Object({
   diffItems: diffItemsField,
   testEvidence: Type.Unknown({
     description:
-      "测试证据条；diff 含测试改动时提交；机器不核验。可写 contract（测试改动所证明的契约）、minimumNecessaryCost（测试改动的一行最小必要成本）、measuredDuration（聚焦验证实测时长）。",
+      "仅 diff 含测试改动时填测试证据条；没有就填 null。机器不核验。可写 contract（测试改动所证明的契约）、minimumNecessaryCost（测试改动的一行最小必要成本）、measuredDuration（聚焦验证实测时长）。",
   }),
 });
 

package/src/package-contracts/gatekeeper-output.ts

@@ -19,10 +19,10 @@ export const gatekeeperDecisionSchema = openToolObject(
       description: "dispatch | pass",
     }),
     officer: Type.Unknown({
-      description: "status 为 dispatch 时为 inspector | notary",
+      description: "仅 status 为 dispatch 时填 inspector | notary；没有就填 null",
     }),
     findings: Type.Unknown({
-      description: "status 为 pass 时可选 string[] findings",
+      description: "仅 status 为 pass 时填 string[] findings；没有就填 null",
     }),
   }),
 );

package/src/package-contracts/navigator-output.ts

@@ -19,7 +19,7 @@ export const NAVIGATOR_OUTPUT_TOOL_NAME = "ak_navigator_output";
  */
 export const navigatorAdviceFields = {
   prose: Type.Unknown({
-    description: "单条散文建议。无状态分叉时使用；原样呈现。",
+    description: "仅无状态分叉时填单条散文建议；没有就填 null。原样呈现。",
   }),
   byStatus: Type.Unknown({
     description:
@@ -28,7 +28,7 @@ export const navigatorAdviceFields = {
   }),
   byRole: Type.Unknown({
     description:
-      "整张路线表：键为衙门角色，值为该衙门 status → 建议。直接入口不给角色时使用。",
+      "仅直接入口不给角色时填整张路线表（键为衙门角色，值为该衙门 status → 建议）；没有就填 null",
   }),
 } as const;
 

package/src/package-contracts/reviewer-output.ts

@@ -8,7 +8,7 @@ import { withTerminatingOutputDeclarations } from "./terminating-infrastructure.
 export const REVIEWER_OUTPUT_TOOL_NAME = "ak_reviewer_output";
 
 const REVIEWER_AMENDMENTS_DESCRIPTION =
-  "已运行 lens 的 amendments 承载 candidates、逐条处置与 verdict 的完整报告（非仅 verdict 行）；显式单轴时另一轴可省略（completeness / correctness）。hard-stop／usage error 为 refused 时，已产出报告仍照录对应 lens 字段。" as const;
+  "已运行 lens 的 amendments 承载 candidates、逐条处置与 verdict 的完整报告（非仅 verdict 行）；各轴（completeness / correctness）仅有已产出报告时填报告；没有就填 null。hard-stop／usage error 为 refused 时，已产出报告仍照录对应 lens 字段。" as const;
 // #1134: `status` alone is the trajectory field (#917 §6 two normal lens verdicts →
 // completed; hard-stop / usage error → refused); its words ride the description.
 // amendments/diagnostic are LLM/human-read narrative content returned as

package/src/package-contracts/terminating-infrastructure.ts

@@ -2,8 +2,9 @@
  * Package-owned shared infrastructure-failure declaration for every primary
  * packaged-role output tool (#541 / #1214 A2).
  *
- * One module owns the typed `infrastructureFailure.diagnostic` declaration
- * composed into each output tool's schema. The field is part of the role's
+ * One module owns the infrastructureFailure declaration composed into each
+ * output tool's schema. Name and semantic description only — no object type, so
+ * a null fill is not a shape rejection (#1134). The field is part of the role's
  * original receipt: ledger records it as-is. Declaration alone does not abort
  * the host (#1214 A2). True host/lifecycle failure still fails honestly on its
  * own channel.
@@ -12,34 +13,11 @@ import { Type, type TSchema } from "typebox";
 
 export const INFRASTRUCTURE_FAILURE_DECLARATION_KEY =
   "infrastructureFailure" as const;
-export const INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY = "diagnostic" as const;
 
-/**
- * Shared declaration fragment for model guidance (#541 / #676 C / ADR 0057).
- * Nested field declarations + descriptions only — host must not pure-shape-reject
- * the envelope (仓内 CLAUDE.md 开篇). No required/minLength/type host gates on
- * the declaration fragment.
- */
-const infrastructureFailureNested = Type.Object(
-  {
-    [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.Unknown({
-      description: "基础设施失败诊断字符串。",
-    }),
-  },
-  {
-    additionalProperties: true,
-    description: "仅基础设施真实失败时出现。",
-  },
-);
-// Open nested required so host cannot pure-shape-reject the declaration fragment.
-(infrastructureFailureNested as unknown as { required: string[] }).required = [];
-
-const infrastructureFailureDeclarationSchema = Type.Object(
-  {
-    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: infrastructureFailureNested,
-  },
-  { additionalProperties: true },
-);
+/** Name + semantic description. diagnostic's meaning lives in the description. */
+const infrastructureFailureField = Type.Unknown({
+  description: "仅基础设施真实失败时填 {diagnostic}；没有就填 null",
+});
 
 /**
  * Compose declarations shared by terminating output tools: infrastructure failure,
@@ -62,7 +40,7 @@ export function withTerminatingOutputDeclarations<
         ? {
             ticketNumber: Type.Unknown({
               description:
-                "可选本票号。尚未绑定时由角色在既有回执中申报（正整数、数字串或前导 #N；归位只读本字段）。",
+                "仅尚未绑定时填本票号（正整数、数字串或前导 #N；归位只读本字段）；没有就填 null",
             }),
           }
         : {}
@@ -72,15 +50,12 @@ export function withTerminatingOutputDeclarations<
         ? {
             summary: Type.Unknown({
               description:
-                "本席自行填写的一两句、20–50 字结论摘要。可选；不因缺失或超长拒收、截断或代填。",
+                "仅本席有结论时填一两句、20–50 字结论摘要；没有就填 null。不因缺失或超长拒收、截断或代填。",
             }),
           }
         : {}
     ),
-    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]:
-      infrastructureFailureDeclarationSchema.properties[
-        INFRASTRUCTURE_FAILURE_DECLARATION_KEY
-      ],
+    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: infrastructureFailureField,
   };
   const object = Type.Object(properties, { additionalProperties: true });
   const incoming = (schema as { required?: unknown }).required;

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

@@ -973,7 +973,8 @@ async function runOmittedLensBatch(
 
 /**
  * One same-parent lookup. Seat branches still build their own summons.
- * A found child resumes that child; no prior run returns undefined so the caller mints.
+ * A found child resumes that child. No prior run, explicit new, or a typed
+ * session-id-missing resume (失败照记，记完再起新) returns undefined so the caller mints.
  */
 function resumeSameParentInstructionSeat(input: {
   readonly env: InstructionSeatRunEnv;

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

@@ -130,7 +130,7 @@ export type SameTicketSummonsMaterials = {
   readonly sourceRun?: NotarySourceRunLocator;
 };
 
-const WRITER_LOCK_FILE = "writer.lock";
+export const WRITER_LOCK_FILE = "writer.lock";
 
 export async function writeRoleRunState(
   runDirectory: string,

package/src/public-cli/seat-ticket-binding.ts

@@ -1,29 +1,51 @@
 /**
- * Shared same-parent resume seam for gate / officer seats (#635 / #637 / #747 / #987).
- *
- * Lookup uses the parent run path; a typed ticket narrows same-ticket gate
- * re-summons, never creates an issue identity. Callers can also use explicit
- * `ak-role resume <runId>`. Lookup/resume failures propagate (失败诚实) — never wash into
- * a fresh mint. Returns undefined when the caller declared an explicit fresh
- * summons (`ak-role new`) or when no prior run exists; both mint new.
- * freshSummons is required so no seat can drift back into its own skip branch.
+ * Shared same-parent resume seam for gate / officer seats (#635 / #637 / #747 / #987 / #1253).
+ * Contract is on tryResumeSameTicketSeatRun.
  */
+import { join } from "node:path";
+
 import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
 import {
+  autopsyWriterLock,
   findLatestRunForSeatTicket,
+  resolveLiveRunDirectoryPath,
+  WRITER_LOCK_FILE,
   type RoleRunRecord,
   type SameTicketSummonsMaterials,
 } from "./run-lifecycle.ts";
 
+const SESSION_ID_MISSING = "session-id-missing";
+
+function resumedSessionIdMissing(result: unknown, runId: string): boolean {
+  if (typeof result !== "object" || result === null) return false;
+  const terminal = (result as { terminal?: unknown }).terminal;
+  if (typeof terminal !== "object" || terminal === null) return false;
+  if ((terminal as { runId?: unknown }).runId !== runId) return false;
+  const outcome = (terminal as { roleOutcome?: unknown }).roleOutcome;
+  if (typeof outcome !== "object" || outcome === null) return false;
+  if ((outcome as { kind?: unknown }).kind !== "failure") return false;
+  const facts = (outcome as { decisiveFacts?: unknown }).decisiveFacts;
+  if (typeof facts !== "object" || facts === null) return false;
+  return (facts as { errorCode?: unknown }).errorCode === SESSION_ID_MISSING;
+}
+
+/** Live or unverifiable holder: same fail-closed verdict as lease acquire. */
+async function writerLockBlocksFreshSummons(runDirectory: string): Promise<boolean> {
+  const autopsy = await autopsyWriterLock(join(runDirectory, WRITER_LOCK_FILE));
+  return autopsy.verdict === "alive" || autopsy.verdict === "unknown";
+}
+
 /**
- * Sole same-seat → resume decision by parent run path (#637 / #724 / #747 / #987).
+ * Sole same-seat → resume decision by parent run path (#637 / #724 / #747 / #987 / #1253).
  * A supplied typed ticket only narrows the prior-run search. When a prior run is
  * found, resume carries this summons' materials and the located runDirectory so
- * load does not re-walk every book for the bare runId (#1195). Lookup/resume
- * failures propagate (失败诚实) — never wash into a fresh mint. Returns undefined
- * when the caller declared an explicit fresh summons (`ak-role new`), the parent
- * path is blank, or no prior run exists; those mint new. freshSummons is
- * required so no seat can drift back into its own skip branch.
+ * load does not re-walk every book for the bare runId (#1195). Typed
+ * session-id-missing is already recorded on that run (失败照记，记完再起新);
+ * return undefined so the caller mints once. Resume runs first; this seam does
+ * not look up a session id. A held or unverifiable writer lock, and every other
+ * result, returns as-is. Also returns undefined for explicit `ak-role new`, a
+ * blank parent path, or no prior run. freshSummons is required so no seat can
+ * drift back into its own skip branch.
  */
 export async function tryResumeSameTicketSeatRun<T>(input: {
   readonly home: string;
@@ -41,13 +63,18 @@ export async function tryResumeSameTicketSeatRun<T>(input: {
 }): Promise<T | undefined> {
   if (input.freshSummons === true) return undefined;
   if (input.parentRunPath.trim() === "") return undefined;
+  const bookKey = resolveBookKeyFromGit(input.projectRoot);
   const previous = await findLatestRunForSeatTicket({
     home: input.home,
-    bookKey: resolveBookKeyFromGit(input.projectRoot),
+    bookKey,
     role: input.role,
     parentRunPath: input.parentRunPath,
     ...(input.ticketNumber === undefined ? {} : { ticketNumber: input.ticketNumber }),
   });
   if (previous === undefined) return undefined;
-  return await input.resume(previous.runId, input.summons, previous.runDirectory);
+  const resumed = await input.resume(previous.runId, input.summons, previous.runDirectory);
+  if (!resumedSessionIdMissing(resumed, previous.runId)) return resumed;
+  const live = await resolveLiveRunDirectoryPath(previous.runDirectory, input.home, bookKey);
+  if (live !== undefined && await writerLockBlocksFreshSummons(live)) return resumed;
+  return undefined;
 }

package/src/review-submission.ts

@@ -27,7 +27,7 @@ const reviewNarrativeFields = {
   reason: Type.Optional(Type.Unknown({ description: "上呈理由" })),
   violations: Type.Optional(Type.Unknown({ description: "违规条目" })),
   conflicts: Type.Optional(Type.Unknown({ description: "待决冲突" })),
-  fix: Type.Optional(Type.Unknown({ description: "continue 时的补救说明；可写 summary 摘要，其余内容原样留存" })),
+  fix: Type.Optional(Type.Unknown({ description: "仅 continue 时填补救说明（可写 summary 摘要，其余内容原样留存）；没有就填 null" })),
   classes: Type.Optional(Type.Unknown({ description: "已裁决 finding 类；可说明 name、owner、boundary、disposition，原样留存" })),
   note: Type.Optional(Type.Unknown({ description: "裁决附注" })),
   evidence: Type.Optional(Type.Unknown({ description: "留存证据" })),