@akagilnc/pi-workflow-roles 0.1.6111 → 0.1.6123

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +3 -3
  2. package/README.zh-CN.md +3 -3
  3. package/dist/acp-host/production-host.js +442 -279
  4. package/dist/engine-detour-usage.js +2 -1
  5. package/dist/gatekeeper-role.js +3 -15
  6. package/dist/headless-host/production-host.js +427 -264
  7. package/dist/migrate-book-topology.js +42 -22
  8. package/dist/notary-source-run.js +8 -8
  9. package/dist/package-contracts/fixer-output.js +3 -0
  10. package/dist/public-cli/auto-resume.js +3 -3
  11. package/dist/public-cli/cli.js +38 -32
  12. package/dist/public-cli/instruction-seat-run.js +52 -13
  13. package/dist/public-cli/invocation.js +22 -12
  14. package/dist/public-cli/main.js +398 -237
  15. package/dist/public-cli/option-definitions.js +22 -21
  16. package/dist/public-cli/run-lifecycle.js +27 -26
  17. package/dist/public-cli/seat-ticket-binding.js +2 -1
  18. package/dist/public-cli/settlement.js +33 -8
  19. package/dist/public-cli/terminal.js +13 -3
  20. package/dist/public-role-summons.js +1 -7
  21. package/dist/role-run-placement.js +1 -1
  22. package/dist/run-dossier-files.js +4 -2
  23. package/dist/submission-gate.js +3 -3
  24. package/dist/submission-ledger.js +29 -3
  25. package/dist/ticket-address.js +77 -0
  26. package/dist/ticket-progress.js +90 -14
  27. package/package.json +1 -1
  28. package/src/engine-detour-usage.ts +2 -1
  29. package/src/gatekeeper-role.ts +5 -18
  30. package/src/notary-source-run.ts +8 -8
  31. package/src/package-contracts/fixer-output.ts +4 -0
  32. package/src/public-cli/auto-resume.ts +4 -3
  33. package/src/public-cli/cli.ts +53 -32
  34. package/src/public-cli/instruction-seat-run.ts +55 -11
  35. package/src/public-cli/invocation.ts +31 -16
  36. package/src/public-cli/option-definitions.ts +22 -21
  37. package/src/public-cli/run-lifecycle.ts +31 -31
  38. package/src/public-cli/seat-ticket-binding.ts +2 -1
  39. package/src/public-cli/settlement.ts +43 -7
  40. package/src/public-cli/terminal.ts +33 -14
  41. package/src/public-role-summons.ts +3 -15
  42. package/src/role-run-placement.ts +1 -1
  43. package/src/run-dossier-files.ts +5 -2
  44. package/src/submission-gate.ts +3 -2
  45. package/src/submission-ledger.ts +32 -2
  46. package/src/ticket-address.ts +91 -0
  47. package/src/ticket-progress.ts +113 -15
@@ -46,8 +46,8 @@ import {
46
46
  appendCallerFileFlagPaths,
47
47
  buildInstructionTransportPrompt,
48
48
  materializeCountersignInvocation,
49
+ persistAdmittedAuditedLeg,
49
50
  persistAdmittedAuditedSubmissionToolCallId,
50
- persistAdmittedSourceRunPath,
51
51
  readAdmittedAuditedSubmissionToolCallId,
52
52
  recordAdmittedCorrelation,
53
53
  recordChildDiaristRun,
@@ -85,6 +85,7 @@ import {
85
85
  ledgerReadScope,
86
86
  presentStructuralRejection,
87
87
  readBoundSessionEntries,
88
+ retainPackageFault,
88
89
  trySettlePublicSeat,
89
90
  type SettlementCourtScope,
90
91
  } from "./settlement.ts";
@@ -106,6 +107,7 @@ import {
106
107
  latestPayloadEscalated,
107
108
  type CountersignRunEnv,
108
109
  } from "./countersign-run.ts";
110
+ import { readAuditedRound } from "../ticket-progress.ts";
109
111
  import { errorText } from "../unknown-value.ts";
110
112
 
111
113
  export type InstructionSeatRunEnv = PostAdmissionEnv & Pick<
@@ -803,6 +805,30 @@ async function runOmittedLensBatch(
803
805
  return { exitCode: failed ? 1 : 0, terminal };
804
806
  }
805
807
 
808
+ /**
809
+ * #1200: every officer admission that names an audited leg — gate summons and
810
+ * a caller's own `--source-run`, first mint and re-summons alike — pins
811
+ *「审 谁#轮」before the officer runs, in the same page write as the source
812
+ * path when this admission is the one that records it. A row that cannot be
813
+ * read keeps its cause on the officer run; the officer still runs and its rows
814
+ * carry no `for`.
815
+ */
816
+ async function pinAuditedLegAtAdmission(
817
+ officerRunDirectory: string,
818
+ auditedRunDirectory: string,
819
+ io: CliIo,
820
+ source?: { readonly sourceRunPath: string; readonly auditorSubject?: "judge" | "doctor" | undefined },
821
+ ): Promise<void> {
822
+ const { for: auditedRound, fault } = readAuditedRound(auditedRunDirectory);
823
+ persistAdmittedAuditedLeg(officerRunDirectory, { for: auditedRound, ...source });
824
+ if (fault === undefined) return;
825
+ await retainPackageFault({
826
+ runDirectory: officerRunDirectory,
827
+ diagnostic: fault,
828
+ stderr: (text) => io.stderr(text),
829
+ });
830
+ }
831
+
806
832
  /**
807
833
  * One same-parent lookup. Seat branches still build their own summons.
808
834
  * A found child resumes that child. No prior run, explicit new, or a typed
@@ -839,6 +865,7 @@ function resumeSameParentInstructionSeat(input: {
839
865
  },
840
866
  input.env,
841
867
  input.io,
868
+ input.parentRunPath,
842
869
  );
843
870
  },
844
871
  });
@@ -945,7 +972,9 @@ async function runCountersignBody(
945
972
  );
946
973
  await markRunAdmitted(admitted, env.principalAuthority);
947
974
  if (gateParentRunPath !== undefined) {
948
- await persistAdmittedSourceRunPath(admitted, gateParentRunPath);
975
+ await pinAuditedLegAtAdmission(admitted.runDirectory, gateParentRunPath, io, {
976
+ sourceRunPath: gateParentRunPath,
977
+ });
949
978
  admitted = { ...admitted, sourceRunPath: gateParentRunPath };
950
979
  }
951
980
  // #1208 C1 / #1166 J11: one shared initial-prompt seam (incl. file flags).
@@ -1169,12 +1198,22 @@ export async function runPublicInstructionSeat(
1169
1198
  }
1170
1199
 
1171
1200
  if (instructionSourceRunPath !== undefined) {
1172
- await persistAdmittedSourceRunPath(admitted, instructionSourceRunPath);
1201
+ await pinAuditedLegAtAdmission(admitted.runDirectory, instructionSourceRunPath, io, {
1202
+ sourceRunPath: instructionSourceRunPath,
1203
+ });
1173
1204
  admitted = { ...admitted, sourceRunPath: instructionSourceRunPath } as AdmittedRoleInvocation;
1174
- }
1175
- if (record.sameParent === "subject-source" && auditorSource !== undefined) {
1176
- await persistAdmittedSourceRunPath(admitted, auditorSource, auditorSubject);
1205
+ } else if (record.sameParent === "subject-source" && auditorSource !== undefined) {
1206
+ await pinAuditedLegAtAdmission(admitted.runDirectory, auditorSource, io, {
1207
+ sourceRunPath: auditorSource,
1208
+ auditorSubject,
1209
+ });
1177
1210
  admitted = { ...admitted, sourceRunPath: auditorSource } as AdmittedRoleInvocation;
1211
+ } else {
1212
+ // The admission itself already recorded the source (source-locator seats).
1213
+ const auditedRunDirectory = admittedSourceRunPath(admitted);
1214
+ if (auditedRunDirectory !== undefined) {
1215
+ await pinAuditedLegAtAdmission(admitted.runDirectory, auditedRunDirectory, io);
1216
+ }
1178
1217
  }
1179
1218
  // #1208 C2: same helper as resume — inherit the audited source's known ticket.
1180
1219
  admitted = await inheritKnownTicketFromSource(admitted, env.principalAuthority);
@@ -1249,6 +1288,8 @@ export async function runPublicInstructionSeatResume(
1249
1288
  request: PublicResumeRequest,
1250
1289
  env: InstructionSeatRunEnv,
1251
1290
  io: CliIo,
1291
+ /** #1200: the audited leg a same-parent re-summons names; absent on every other resume. */
1292
+ resummonedFor?: string,
1252
1293
  ): Promise<SeatRunResult> {
1253
1294
  let selectedRequest = request;
1254
1295
  const resume = async () => {
@@ -1286,6 +1327,12 @@ export async function runPublicInstructionSeatResume(
1286
1327
  return { ...loaded, admitted };
1287
1328
  },
1288
1329
  buildTurnRequest: async (admitted, effective) => {
1330
+ // #1200: the turn is built once this leg has taken the summons — inside
1331
+ // its writer lease wherever the resume holds one — and before the host
1332
+ // turn. A summons the lease refuses never gets here and pins nothing.
1333
+ if (resummonedFor !== undefined) {
1334
+ await pinAuditedLegAtAdmission(admitted.runDirectory, resummonedFor, io);
1335
+ }
1289
1336
  const summonsPrepared = await prepareSummonsResumeMaterials(admitted.runDirectory, effective.summons);
1290
1337
  const projection = resumeTurnRequestProjectionOptions(
1291
1338
  admitted, effective, env, summonsPrepared,
@@ -1790,8 +1837,7 @@ async function auditSubmittedRole(
1790
1837
  const pass = chain.passes.at(-1);
1791
1838
  const officerTerminal = pass?.terminal;
1792
1839
  const officerRunDirectory = pass?.runDirectory;
1793
- const officerRunId = pass?.runId
1794
- ?? (officerRunDirectory === undefined ? undefined : runIdFromRunDirectory(officerRunDirectory));
1840
+ const officerRunId = pass?.runId;
1795
1841
  if (officerTerminal !== undefined && officerRunId !== undefined) {
1796
1842
  // #1214 F1: present audited original and officer scene separately.
1797
1843
  await presentAuditedOriginalVolume(turn, io);
@@ -1840,9 +1886,7 @@ async function auditSubmittedRole(
1840
1886
  if (chain.status === "escalate") {
1841
1887
  const escalation = chain.passes.at(-1);
1842
1888
  const escalatedRunDirectory = escalation?.runDirectory;
1843
- const escalatedRunId = escalation?.runId
1844
- ?? (escalatedRunDirectory === undefined
1845
- ? undefined : runIdFromRunDirectory(escalatedRunDirectory));
1889
+ const escalatedRunId = escalation?.runId;
1846
1890
  if (escalatedRunId === undefined) {
1847
1891
  return incompleteAuditWithoutOfficerVolume(
1848
1892
  turn,
@@ -478,29 +478,44 @@ async function mergeInvocationIdentityPage(
478
478
  }
479
479
 
480
480
  /**
481
- * Persist parent --source-run path onto the admitted section for officer resume lookup (#747).
482
- * Reuses the existing notary sourceRunPath key; does not invent a new field name.
481
+ * What this officer audits, on its admitted section in one page write.
482
+ * `for` (#1200) is the audited leg's「席#轮」at this admission: a new value
483
+ * replaces the old one, none clears it. `sourceRunPath` (#747) is the parent
484
+ * --source-run path kept for officer resume lookup, given only by the admission
485
+ * that first records it; it reuses the existing notary key and is never replaced.
483
486
  */
484
- export async function persistAdmittedSourceRunPath(
485
- admitted: AdmittedRoleInvocation,
486
- sourceRunPath: string,
487
- auditorSubject?: "judge" | "doctor",
488
- ): Promise<void> {
489
- if (sourceRunPath.trim() === "") {
490
- throw new Error("persistAdmittedSourceRunPath requires a non-empty sourceRunPath");
487
+ export function persistAdmittedAuditedLeg(
488
+ runDirectory: string,
489
+ audited: {
490
+ readonly for: string | undefined;
491
+ readonly sourceRunPath?: string;
492
+ readonly auditorSubject?: "judge" | "doctor" | undefined;
493
+ },
494
+ ): void {
495
+ const { sourceRunPath, auditorSubject } = audited;
496
+ if (sourceRunPath !== undefined && sourceRunPath.trim() === "") {
497
+ throw new Error("persistAdmittedAuditedLeg requires a non-empty sourceRunPath");
491
498
  }
492
- updateSectionSync(admitted.runDirectory, "admitted", (current) => {
493
- if (typeof current.sourceRunPath === "string" && current.sourceRunPath !== sourceRunPath) {
499
+ updateSectionSync(runDirectory, "admitted", (current) => {
500
+ if (
501
+ sourceRunPath !== undefined
502
+ && typeof current.sourceRunPath === "string"
503
+ && current.sourceRunPath !== sourceRunPath
504
+ ) {
494
505
  throw new Error(
495
- `persistAdmittedSourceRunPath refuses to replace ${current.sourceRunPath} with ${sourceRunPath}`,
506
+ `persistAdmittedAuditedLeg refuses to replace ${current.sourceRunPath} with ${sourceRunPath}`,
496
507
  );
497
508
  }
498
- const sameSubject = auditorSubject === undefined || current.auditorSubject === auditorSubject;
499
- if (current.sourceRunPath === sourceRunPath && sameSubject) return undefined;
509
+ const unchanged = current.for === audited.for
510
+ && (sourceRunPath === undefined || current.sourceRunPath === sourceRunPath)
511
+ && (auditorSubject === undefined || current.auditorSubject === auditorSubject);
512
+ if (unchanged) return undefined;
513
+ const { for: _replaced, ...rest } = current;
500
514
  return {
501
- ...current,
502
- sourceRunPath,
515
+ ...rest,
516
+ ...(sourceRunPath === undefined ? {} : { sourceRunPath }),
503
517
  ...(auditorSubject === undefined ? {} : { auditorSubject }),
518
+ ...(audited.for === undefined ? {} : { for: audited.for }),
504
519
  };
505
520
  });
506
521
  }
@@ -434,7 +434,7 @@ const AUDITOR_OPTIONS = [
434
434
  owner: "auditor",
435
435
  canonical: "--source-run",
436
436
  aliases: [],
437
- valueMetavar: "runId@role|path",
437
+ valueMetavar: "ticket:seat#round|path",
438
438
  required: true,
439
439
  repeatable: false,
440
440
  form: "option",
@@ -620,13 +620,13 @@ const NOTARY_OPTIONS = [
620
620
  owner: "notary",
621
621
  canonical: "--source-run",
622
622
  aliases: [],
623
- valueMetavar: "runId@role|path",
623
+ valueMetavar: "ticket:seat#round|path",
624
624
  required: true,
625
625
  repeatable: false,
626
626
  form: "option",
627
627
  description: {
628
- en: "Required source run locator (runId@role under the book home, or path to that run directory). Binds the audited identity; review dialogue is the fixed Notary dispatch (verdict stays in the ledger). Missing-ticket and unreadable-status reasks keep their existing diagnostic text.",
629
- zh: "必填源 run 定位符(簿内 runId@role,或该 run 目录路径)。绑定受审身份;审稿对话为符宝郎固定派单文(判词留在卷宗自行读取)。缺票号与读不出 status 的重交仍递既有诊断原文。",
628
+ en: "Required source run locator (<ticket>:<seat>#<round> as written on the ticket's progress row, or path to that run directory). Binds the audited identity; review dialogue is the fixed Notary dispatch (verdict stays in the ledger). Missing-ticket and unreadable-status reasks keep their existing diagnostic text.",
629
+ zh: "必填源 run 定位符(<票号>:<席>#<轮>,轮照进度行上的写法;或该 run 目录路径)。绑定受审身份;审稿对话为符宝郎固定派单文(判词留在卷宗自行读取)。缺票号与读不出 status 的重交仍递既有诊断原文。",
630
630
  },
631
631
  },
632
632
  ] as const satisfies readonly PublicOptionDefinition[];
@@ -639,13 +639,13 @@ const INSPECTOR_OPTIONS = [
639
639
  owner: "inspector",
640
640
  canonical: "--source-run",
641
641
  aliases: [],
642
- valueMetavar: "runId@role|path",
642
+ valueMetavar: "ticket:seat#round|path",
643
643
  required: false,
644
644
  repeatable: false,
645
645
  form: "option",
646
646
  description: {
647
- en: "Optional audited source-run locator (runId@role or path). Gate summons always supply it; identity rides startup materials.",
648
- zh: "可选被审腿定位符(runId@role 或路径)。闸传召必带;身份在启动材料里。",
647
+ en: "Optional audited source-run locator (<ticket>:<seat>#<round> or path). Gate summons always supply it; identity rides startup materials.",
648
+ zh: "可选被审腿定位符(<票号>:<席>#<轮> 或路径)。闸传召必带;身份在启动材料里。",
649
649
  },
650
650
  },
651
651
  ] as const satisfies readonly PublicOptionDefinition[];
@@ -1241,10 +1241,10 @@ const ROLE_COMMAND_HELP = {
1241
1241
  auditor: {
1242
1242
  command: "auditor",
1243
1243
  summary: "Direct Auditor (审刑院) compliance audit: converged, continue, or escalate.",
1244
- usage: ["ak-role auditor --subject <judge|doctor> --source-run <runId@role|path> [options] [instruction]"],
1244
+ usage: ["ak-role auditor --subject <judge|doctor> --source-run <ticket:seat#round|path> [options] [instruction]"],
1245
1245
  examples: [
1246
- 'ak-role auditor --subject judge --source-run 01abc…@judge --attach ./dossier "审:本 run 是否合规。"',
1247
- 'ak-role auditor --subject doctor --source-run 01abc…@doctor "审:太医候选是否合规。"',
1246
+ 'ak-role auditor --subject judge --source-run 1201:judge#2 --attach ./dossier "审:本 run 是否合规。"',
1247
+ 'ak-role auditor --subject doctor --source-run 1201:doctor#1 "审:太医候选是否合规。"',
1248
1248
  ],
1249
1249
  },
1250
1250
  diarist: {
@@ -1270,10 +1270,10 @@ const ROLE_COMMAND_HELP = {
1270
1270
  command: "notary",
1271
1271
  summary:
1272
1272
  "Direct Notary summons; duties: souls/notary.md. Review uses fixed dispatch — binds --source-run identity; does not accept caller review prompt; verdict stays in the ledger. Missing-ticket (#1171) and unreadable-status reasks deliver their existing diagnostic text on the same seat, not the review sentence.",
1273
- usage: ["ak-role notary --source-run <runId@role|path> [options]"],
1273
+ usage: ["ak-role notary --source-run <ticket:seat#round|path> [options]"],
1274
1274
  examples: [
1275
- "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@judge",
1276
- "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@countersign",
1275
+ "ak-role notary --source-run 1201:judge#2",
1276
+ "ak-role notary --source-run 1201:countersign#1",
1277
1277
  ],
1278
1278
  },
1279
1279
  analyst: {
@@ -1332,14 +1332,15 @@ const SUPPORT_COMMAND_HELP = {
1332
1332
  resume: {
1333
1333
  command: "resume",
1334
1334
  summary:
1335
- "Resume a role run under the live seat table (model/host/engine); session principal must still exist. Every callable seat accepts the optional caller message and passes it through unchanged as the continuation prompt. Notary new/direct review calls use only --source-run plus the fixed review dispatch (no caller review prompt); public manual resume still passes the caller message. Global --model/--thinking/--host/--engine must be placed before <runId> (either before `resume` or between `resume` and <runId>); the one argv after <runId> is the opaque message, not a flag position (#471).",
1336
- usage: ["ak-role resume <runId> [message]"],
1335
+ "Resume one leg of a ticket under the live seat table (model/host/engine); session principal must still exist. The address is the ticket number and the seat: by default the seat's most recently active leg under that ticket; <seat>#<round> (round as written on the ticket's progress row, reviewer rounds carry the lens suffix) names the leg that filed that round. A leg that has reported no ticket is not in this address. Every callable seat accepts the optional caller message and passes it through unchanged as the continuation prompt. Notary new/direct review calls use only --source-run plus the fixed review dispatch (no caller review prompt); public manual resume still passes the caller message. Global --model/--thinking/--host/--engine must be placed before <ticket> (either before `resume` or between `resume` and <ticket>); the one argv after <seat> is the opaque message, not a flag position (#471).",
1336
+ usage: ["ak-role resume <ticket> <seat>[#<round>] [message]"],
1337
1337
  examples: [
1338
- "ak-role resume 01abc…",
1339
- "ak-role resume 01abc… \"owner ruling\"",
1340
- "ak-role --host grok-build resume 01abc…",
1341
- "ak-role --engine agy resume 01abc…",
1342
- "ak-role resume --model xai/grok-4.5 01abc… \"owner ruling\"",
1338
+ "ak-role resume 1201 judge",
1339
+ "ak-role resume 1201 judge \"owner ruling\"",
1340
+ "ak-role resume 1201 'reviewer#2.correctness'",
1341
+ "ak-role --host grok-build resume 1201 fixer",
1342
+ "ak-role --engine agy resume 1201 fixer",
1343
+ "ak-role resume --model xai/grok-4.5 1201 notary \"owner ruling\"",
1343
1344
  ],
1344
1345
  },
1345
1346
  new: {
@@ -1349,7 +1350,7 @@ const SUPPORT_COMMAND_HELP = {
1349
1350
  usage: ["ak-role new <role> [options] …"],
1350
1351
  examples: [
1351
1352
  'ak-role new countersign --attach ./ticket.md "裁:本票 #708 是否足以开工。"',
1352
- "ak-role new notary --source-run 01abc…@countersign",
1353
+ "ak-role new notary --source-run 1201:countersign#1",
1353
1354
  "ak-role --host grok-build new inspector --attach ./change.patch",
1354
1355
  ],
1355
1356
  },
@@ -86,16 +86,15 @@ export type RoleRunRecord = {
86
86
  readonly phase?: CoderPhase | FixerPhase;
87
87
  };
88
88
 
89
- /** Public manual resume request after the unique CLI parser owns runId + optional message. */
89
+ /** Resume request for one located leg: the public address (ticket + seat) or an internal re-summons. */
90
90
  export type PublicResumeRequest = {
91
91
  readonly runId: string;
92
92
  /**
93
- * When already known (gate pass / same-ticket locator), load this directory
94
- * instead of re-resolving runId across every book (#1195).
95
- * Explicit public `ak-role resume <runId>` leaves this unset.
93
+ * When already known (public ticket address / gate pass / same-ticket locator),
94
+ * load this directory instead of re-resolving runId across every book (#1195).
96
95
  */
97
96
  readonly runDirectory?: string;
98
- /** Present when the caller supplied the post-runId argv (including empty string). */
97
+ /** Present when the caller supplied the message argv (including empty string). */
99
98
  readonly message?: string;
100
99
  /**
101
100
  * Same-ticket re-summons materials (#637). Present only when a public seat
@@ -860,7 +859,7 @@ export async function findRunDirectoryById(
860
859
  const parsed = parseRunLeaf(basename(knownRunDirectory));
861
860
  if (parsed === undefined || parsed.runId !== runId) {
862
861
  throw new CliUsageError(
863
- `run directory does not match run id ${runId}: ${knownRunDirectory}`,
862
+ `run directory is not the expected role run: ${knownRunDirectory}`,
864
863
  );
865
864
  }
866
865
  return knownRunDirectory;
@@ -941,7 +940,7 @@ async function runHasFormedSessionPrincipal(runDirectory: string): Promise<boole
941
940
  * parent run path (officer / gate seats, #747 / #987), narrowed to a supplied
942
941
  * typed ticket for same-ticket gate re-summons. runId is UUIDv7 — lexicographic
943
942
  * max is latest among runs that formed a session principal. No parallel index;
944
- * callers can use explicit `ak-role resume <runId>`.
943
+ * callers address a leg explicitly with `ak-role resume <ticket> <seat>`.
945
944
  * Only a truly missing book directory means no history; damage/permission errors propagate.
946
945
  */
947
946
  export async function findLatestRunIdForSeatTicket(input: {
@@ -1068,19 +1067,20 @@ async function loadResumableRunRecord(
1068
1067
  readonly admittedFields: LoadedAdmittedRequestFields;
1069
1068
  }> {
1070
1069
  const runDirectory = await findRunDirectoryById(home, runId, undefined, undefined, knownRunDirectory);
1070
+ // Diagnostics name the leg by its directory; the run id is not a caller-facing identity (#1201).
1071
1071
  if (runDirectory === undefined) {
1072
- throw new CliUsageError(`unknown role run id: ${runId}`);
1072
+ throw new CliUsageError(`unknown role run: no run directory found under ${home}`);
1073
1073
  }
1074
1074
  const disk = await readRoleRunStateDisk(runDirectory);
1075
1075
  if (disk === undefined) {
1076
- throw new CliUsageError(`unknown role run id: ${runId}`);
1076
+ throw new CliUsageError(`role run has no readable state: ${runDirectory}`);
1077
1077
  }
1078
1078
  // #416 / #1091: removed terminal/resumable and local session-file gates.
1079
1079
  // The load seam locates the run and recovers identity; host CLI answers continuation.
1080
1080
  // One authority.decode of the uninterpreted wire yields both principal and record.
1081
1081
  const materialized = materializeRoleRunFromDisk(disk, authority);
1082
1082
  if (materialized === undefined) {
1083
- throw new CliUsageError(`unknown role run id: ${runId}`);
1083
+ throw new CliUsageError(`role run has no readable state: ${runDirectory}`);
1084
1084
  }
1085
1085
  const { run, principal } = materialized;
1086
1086
  // Reconstruct admitted identity from durable run record + the admitted section.
@@ -1249,7 +1249,7 @@ async function loadResumableRunRecord(
1249
1249
  // Preserve unique --authority-ref grammar failures; do not collapse to unreadable.
1250
1250
  if (error instanceof CliUsageError) throw error;
1251
1251
  throw new CliUsageError(
1252
- `role run admitted request is unreadable: ${runId}`,
1252
+ `role run admitted request is unreadable: ${run.runDirectory}`,
1253
1253
  { cause: error },
1254
1254
  );
1255
1255
  }
@@ -1280,7 +1280,7 @@ async function loadResumableRunRecord(
1280
1280
  }
1281
1281
  if (!isEnoent(error)) {
1282
1282
  throw new CliUsageError(
1283
- `role run invocation identity is unreadable: ${runId}`,
1283
+ `role run invocation identity is unreadable: ${run.runDirectory}`,
1284
1284
  { cause: error },
1285
1285
  );
1286
1286
  }
@@ -1408,7 +1408,7 @@ function admitResumedRole(loaded: {
1408
1408
  readonly admittedFields: LoadedAdmittedRequestFields;
1409
1409
  }): AdmittedRoleInvocation {
1410
1410
  const role = loaded.run.role;
1411
- const runId = loaded.run.runId;
1411
+ const leg = loaded.run.runDirectory;
1412
1412
  const record = packagedRoleMetadata(role);
1413
1413
  if (record === undefined) {
1414
1414
  throw new CliUsageError(`unknown role: ${role}`);
@@ -1446,10 +1446,10 @@ function admitResumedRole(loaded: {
1446
1446
  return admitted;
1447
1447
  }
1448
1448
  case "worker-task": {
1449
- const phase = resumedWorkerPhase(fields.phase ?? loaded.run.phase, record.phases, role, runId);
1449
+ const phase = resumedWorkerPhase(fields.phase ?? loaded.run.phase, record.phases, role, leg);
1450
1450
  if (fields.instruction.trim() === "") {
1451
1451
  throw new CliUsageError(
1452
- `role run admitted coder task is blank: ${runId}`,
1452
+ `role run admitted coder task is blank: ${leg}`,
1453
1453
  );
1454
1454
  }
1455
1455
  const admitted: AdmittedCoderInvocation = {
@@ -1461,10 +1461,10 @@ function admitResumedRole(loaded: {
1461
1461
  return admitted;
1462
1462
  }
1463
1463
  case "worker-packet": {
1464
- const phase = resumedWorkerPhase(fields.phase ?? loaded.run.phase, record.phases, role, runId);
1464
+ const phase = resumedWorkerPhase(fields.phase ?? loaded.run.phase, record.phases, role, leg);
1465
1465
  if (fields.instruction.trim() === "") {
1466
1466
  throw new CliUsageError(
1467
- `role run admitted fixer instruction is blank: ${runId}`,
1467
+ `role run admitted fixer instruction is blank: ${leg}`,
1468
1468
  );
1469
1469
  }
1470
1470
  const admitted: AdmittedFixerInvocation = {
@@ -1484,20 +1484,20 @@ function admitResumedRole(loaded: {
1484
1484
  if (baseFault !== undefined || rawBase === undefined) {
1485
1485
  throw new CliUsageError(
1486
1486
  baseFault === "damaged"
1487
- ? `role run admitted reviewer base revision is damaged: ${runId}`
1488
- : `role run admitted reviewer base revision is missing: ${runId}`,
1487
+ ? `role run admitted reviewer base revision is damaged: ${leg}`
1488
+ : `role run admitted reviewer base revision is missing: ${leg}`,
1489
1489
  );
1490
1490
  }
1491
1491
  const lens = fields.lens;
1492
1492
  if (!isReviewerLens(lens)) {
1493
1493
  throw new CliUsageError(
1494
- `role run admitted reviewer lens is missing: ${runId}`,
1494
+ `role run admitted reviewer lens is missing: ${leg}`,
1495
1495
  );
1496
1496
  }
1497
1497
  const authorityRefs = Object.freeze([...(fields.authorityRefs ?? [])]);
1498
1498
  if (authorityRefs.length === 0) {
1499
1499
  throw new CliUsageError(
1500
- `role run admitted reviewer authority refs are missing: ${runId}`,
1500
+ `role run admitted reviewer authority refs are missing: ${leg}`,
1501
1501
  );
1502
1502
  }
1503
1503
  const admitted: AdmittedReviewerInvocation = {
@@ -1513,7 +1513,7 @@ function admitResumedRole(loaded: {
1513
1513
  const baseRevision = fields.baseRevision;
1514
1514
  if (baseRevision === undefined || baseRevision.trim() === "") {
1515
1515
  throw new CliUsageError(
1516
- `role run admitted gleaner-left base revision is missing: ${runId}`,
1516
+ `role run admitted gleaner-left base revision is missing: ${leg}`,
1517
1517
  );
1518
1518
  }
1519
1519
  const admitted: AdmittedGleanerLeftInvocation = {
@@ -1527,18 +1527,18 @@ function admitResumedRole(loaded: {
1527
1527
  const mergerInputPath = fields.mergerInputPath;
1528
1528
  if (mergerInputPath === undefined) {
1529
1529
  throw new CliUsageError(
1530
- `role run admitted merger input path is missing: ${runId}`,
1530
+ `role run admitted merger input path is missing: ${leg}`,
1531
1531
  );
1532
1532
  }
1533
1533
  const derived = fields.derived;
1534
1534
  if (derived === undefined) {
1535
1535
  throw new CliUsageError(
1536
- `role run admitted merger envelope is missing: ${runId}`,
1536
+ `role run admitted merger envelope is missing: ${leg}`,
1537
1537
  );
1538
1538
  }
1539
1539
  if (fields.instruction.trim() === "") {
1540
1540
  throw new CliUsageError(
1541
- `role run admitted merger task is blank: ${runId}`,
1541
+ `role run admitted merger task is blank: ${leg}`,
1542
1542
  );
1543
1543
  }
1544
1544
  const admitted: AdmittedMergerInvocation = {
@@ -1554,7 +1554,7 @@ function admitResumedRole(loaded: {
1554
1554
  const { prNumber, repository, repositoryDisplay } = fields;
1555
1555
  if (repository === undefined || repositoryDisplay === undefined) {
1556
1556
  throw new CliUsageError(
1557
- `role run admitted collector repository identity is missing: ${runId}`,
1557
+ `role run admitted collector repository identity is missing: ${leg}`,
1558
1558
  );
1559
1559
  }
1560
1560
  let parsedRepository;
@@ -1566,7 +1566,7 @@ function admitResumedRole(loaded: {
1566
1566
  }
1567
1567
  if (parsedRepository.canonical !== repository) {
1568
1568
  throw new CliUsageError(
1569
- `role run admitted collector repository does not match its canonical form: ${runId}`,
1569
+ `role run admitted collector repository does not match its canonical form: ${leg}`,
1570
1570
  );
1571
1571
  }
1572
1572
  const admitted: AdmittedCollectorInvocation = {
@@ -1589,7 +1589,7 @@ function admitResumedRole(loaded: {
1589
1589
  caseIdentity === undefined
1590
1590
  ) {
1591
1591
  throw new CliUsageError(
1592
- `role run admitted doctor case identity is missing: ${runId}`,
1592
+ `role run admitted doctor case identity is missing: ${leg}`,
1593
1593
  );
1594
1594
  }
1595
1595
  const admitted: AdmittedDoctorInvocation = {
@@ -1605,7 +1605,7 @@ function admitResumedRole(loaded: {
1605
1605
  const { sourceRunPath, sourceRun } = fields;
1606
1606
  if (sourceRunPath === undefined || sourceRun === undefined) {
1607
1607
  throw new CliUsageError(
1608
- `role run admitted notary source-run locator is missing: ${runId}`,
1608
+ `role run admitted notary source-run locator is missing: ${leg}`,
1609
1609
  );
1610
1610
  }
1611
1611
  const admitted: AdmittedNotaryInvocation = {
@@ -1624,12 +1624,12 @@ function resumedWorkerPhase(
1624
1624
  phase: string | undefined,
1625
1625
  phases: readonly (string | null)[],
1626
1626
  role: string,
1627
- runId: string,
1627
+ leg: string,
1628
1628
  ): "plan" | "apply" {
1629
1629
  if (phase === "plan" || phase === "apply") {
1630
1630
  if (phases.some((item) => item === phase)) {
1631
1631
  return phase;
1632
1632
  }
1633
1633
  }
1634
- throw new CliUsageError(`role run admitted ${role} phase is missing: ${runId}`);
1634
+ throw new CliUsageError(`role run admitted ${role} phase is missing: ${leg}`);
1635
1635
  }
@@ -20,7 +20,8 @@ function resumedSessionIdMissing(result: unknown, runId: string): boolean {
20
20
  if (typeof result !== "object" || result === null) return false;
21
21
  const terminal = (result as { terminal?: unknown }).terminal;
22
22
  if (typeof terminal !== "object" || terminal === null) return false;
23
- if ((terminal as { runId?: unknown }).runId !== runId) return false;
23
+ // The failure belongs to the resumed leg, not to another seat presented in its place.
24
+ if ((result as { admitted?: { runId?: unknown } }).admitted?.runId !== runId) return false;
24
25
  const outcome = (terminal as { roleOutcome?: unknown }).roleOutcome;
25
26
  if (typeof outcome !== "object" || outcome === null) return false;
26
27
  if ((outcome as { kind?: unknown }).kind !== "failure") return false;
@@ -4,10 +4,11 @@
4
4
  * Controlled failures and audit human decisions settle here without washing causes.
5
5
  */
6
6
  import { randomUUID } from "node:crypto";
7
- import { dirname, join } from "node:path";
7
+ import { basename, join } from "node:path";
8
8
  import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
9
9
 
10
- import { sessionFileOf } from "../role-run-placement.ts";
10
+ import { sessionFileOf, subjectDirectoryOfRun } from "../role-run-placement.ts";
11
+ import { parseTicketNumber } from "../run-ticket-number.ts";
11
12
 
12
13
  import { sitianReport, type RecordPointer } from "../sitian-facade.ts";
13
14
  import {
@@ -186,8 +187,34 @@ type SealedLedgerSettle = {
186
187
  readonly outcome: Extract<TerminalRoleOutcome, { kind: "accepted" | "audit_escalation" }>;
187
188
  /** Tool-call identity of the latest this-settle terminal row (#1171 F2-R8). */
188
189
  readonly submissionToolCallId?: string;
190
+ /** Progress rows written for this settle's accepted submissions (#1201). */
191
+ readonly filed: readonly FiledReceipt[];
189
192
  };
190
193
 
194
+ /** Receipt reference and round as the progress row carries them. */
195
+ type FiledReceipt = { readonly receipt: string; readonly round?: string };
196
+
197
+ /**
198
+ * #1201 public identity of a leg's terminal: the ticket it is filed under and
199
+ * the receipts this settle accepted. Row references resolve under the leg's
200
+ * subject directory as it stands now; a leg that has reported no ticket names
201
+ * no ticket and no round.
202
+ */
203
+ export function filedIdentity(
204
+ runDirectory: string,
205
+ filed: readonly FiledReceipt[] = [],
206
+ ): Pick<TerminalResult, "ticket" | "receipts"> {
207
+ const subjectDirectory = subjectDirectoryOfRun(runDirectory);
208
+ if (subjectDirectory === undefined) return {};
209
+ const ticket = parseTicketNumber(basename(subjectDirectory));
210
+ return {
211
+ ...(ticket === undefined ? {} : { ticket }),
212
+ ...(filed.length === 0 ? {} : {
213
+ receipts: filed.map((row) => ({ ...row, receipt: join(subjectDirectory, row.receipt) })),
214
+ }),
215
+ };
216
+ }
217
+
191
218
  function roleOutcomeFromRows(
192
219
  role: TerminalRoleName,
193
220
  rows: readonly {
@@ -197,6 +224,8 @@ function roleOutcomeFromRows(
197
224
  readonly auditReceipt?: unknown;
198
225
  readonly auditOfficer?: unknown;
199
226
  readonly toolCallId?: string;
227
+ readonly receipt?: string;
228
+ readonly round?: string;
200
229
  }[],
201
230
  ): SealedLedgerSettle | undefined {
202
231
  const mine = rows.filter((row) => row.role === role);
@@ -215,8 +244,13 @@ function roleOutcomeFromRows(
215
244
  typeof latest.toolCallId === "string" && latest.toolCallId.length > 0
216
245
  ? latest.toolCallId
217
246
  : undefined;
218
- const belonging =
219
- submissionToolCallId === undefined ? {} : { submissionToolCallId };
247
+ const filed = mine.flatMap((row): FiledReceipt[] => row.receipt === undefined
248
+ ? []
249
+ : [{ receipt: row.receipt, ...(row.round === undefined ? {} : { round: row.round }) }]);
250
+ const belonging = {
251
+ ...(submissionToolCallId === undefined ? {} : { submissionToolCallId }),
252
+ filed,
253
+ };
220
254
  if (latest.kind === "audit-escalation") {
221
255
  return {
222
256
  outcome: {
@@ -468,7 +502,7 @@ async function settleNoReceiptTerminal(
468
502
  scope,
469
503
  ),
470
504
  artifacts: [],
471
- runId: admitted.runId,
505
+ ...filedIdentity(admitted.runDirectory),
472
506
  }, coordinates.sessionDirectory, detourUsageContext(admitted, scope));
473
507
  }
474
508
 
@@ -1449,6 +1483,7 @@ async function settleSealedSeat(
1449
1483
  settled.outcome,
1450
1484
  scope,
1451
1485
  settled.submissionToolCallId,
1486
+ settled.filed,
1452
1487
  );
1453
1488
  }
1454
1489
 
@@ -1459,6 +1494,7 @@ async function finishLawfulSeat(
1459
1494
  roleOutcome: TerminalRoleOutcome,
1460
1495
  scope: SettlementCourtScope | undefined,
1461
1496
  submissionToolCallId?: string,
1497
+ filed?: readonly FiledReceipt[],
1462
1498
  ): Promise<TerminalResult> {
1463
1499
  const artifacts = scope?.previewOnly === true
1464
1500
  ? []
@@ -1467,7 +1503,7 @@ async function finishLawfulSeat(
1467
1503
  roleOutcome,
1468
1504
  navigator: isNavigatorSeat(admitted.role) ? NAVIGATOR_SEAT_OWN_FACT : extractNavigatorFact(entries),
1469
1505
  artifacts,
1470
- runId: admitted.runId,
1506
+ ...filedIdentity(admitted.runDirectory, filed),
1471
1507
  ...(submissionToolCallId === undefined || submissionToolCallId.length === 0
1472
1508
  ? {}
1473
1509
  : { submissionToolCallId }),
@@ -1714,7 +1750,7 @@ export async function settleFailureTerminalResult(
1714
1750
  decisiveFacts,
1715
1751
  };
1716
1752
  return attachEngineDetourToolUsage(
1717
- { roleOutcome, navigator, artifacts, runId: admitted.runId },
1753
+ { roleOutcome, navigator, artifacts, ...filedIdentity(admitted.runDirectory) },
1718
1754
  sessionDirectory,
1719
1755
  detourUsageContext(admitted, options),
1720
1756
  );