@akagilnc/pi-workflow-roles 0.1.6115 → 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 (43) hide show
  1. package/README.md +3 -3
  2. package/README.zh-CN.md +3 -3
  3. package/dist/acp-host/production-host.js +354 -250
  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 +339 -235
  7. package/dist/migrate-book-topology.js +39 -22
  8. package/dist/notary-source-run.js +8 -8
  9. package/dist/public-cli/auto-resume.js +3 -3
  10. package/dist/public-cli/cli.js +38 -32
  11. package/dist/public-cli/instruction-seat-run.js +2 -5
  12. package/dist/public-cli/main.js +310 -208
  13. package/dist/public-cli/option-definitions.js +22 -21
  14. package/dist/public-cli/run-lifecycle.js +27 -26
  15. package/dist/public-cli/seat-ticket-binding.js +2 -1
  16. package/dist/public-cli/settlement.js +33 -8
  17. package/dist/public-cli/terminal.js +13 -3
  18. package/dist/public-role-summons.js +1 -7
  19. package/dist/role-run-placement.js +1 -1
  20. package/dist/run-dossier-files.js +4 -2
  21. package/dist/submission-gate.js +3 -3
  22. package/dist/submission-ledger.js +29 -3
  23. package/dist/ticket-address.js +77 -0
  24. package/dist/ticket-progress.js +31 -0
  25. package/package.json +1 -1
  26. package/src/engine-detour-usage.ts +2 -1
  27. package/src/gatekeeper-role.ts +5 -18
  28. package/src/notary-source-run.ts +8 -8
  29. package/src/public-cli/auto-resume.ts +4 -3
  30. package/src/public-cli/cli.ts +53 -32
  31. package/src/public-cli/instruction-seat-run.ts +2 -5
  32. package/src/public-cli/option-definitions.ts +22 -21
  33. package/src/public-cli/run-lifecycle.ts +31 -31
  34. package/src/public-cli/seat-ticket-binding.ts +2 -1
  35. package/src/public-cli/settlement.ts +43 -7
  36. package/src/public-cli/terminal.ts +33 -14
  37. package/src/public-role-summons.ts +3 -15
  38. package/src/role-run-placement.ts +1 -1
  39. package/src/run-dossier-files.ts +5 -2
  40. package/src/submission-gate.ts +3 -2
  41. package/src/submission-ledger.ts +32 -2
  42. package/src/ticket-address.ts +91 -0
  43. package/src/ticket-progress.ts +42 -0
@@ -0,0 +1,77 @@
1
+ /**
2
+ * #1201 public address: ticket + seat (+ round). One locator shared by
3
+ * `ak-role resume <ticket> <seat>[#<round>]` and
4
+ * `--source-run <ticket>:<seat>#<round>` (ADR 0088).
5
+ *
6
+ * Only legs filed under the ticket are visible here. A leg that has reported no
7
+ * ticket stays in `unbound/` and is not in this address.
8
+ */
9
+ import { existsSync, readdirSync, statSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { CliUsageError } from "./public-cli/cli-errors.js";
12
+ import { parseRunLeaf } from "./role-run-placement.js";
13
+ import { parseTicketNumber } from "./run-ticket-number.js";
14
+ import { readTicketProgressLines } from "./ticket-progress.js";
15
+ /** Bare digits; a quoted leading `#` is accepted. */
16
+ export function parseAddressTicket(token) {
17
+ return parseTicketNumber(token.startsWith("#") ? token.slice(1) : token);
18
+ }
19
+ /** `<seat>` or `<seat>#<round>`. */
20
+ export function parseSeatRound(token) {
21
+ const hash = token.indexOf("#");
22
+ return hash === -1
23
+ ? { seat: token }
24
+ : { seat: token.slice(0, hash), round: token.slice(hash + 1) };
25
+ }
26
+ /** `<ticket>:<seat>#<round>`; undefined when the token is not that spelling. */
27
+ export function parseTicketLegLocator(token) {
28
+ const colon = token.indexOf(":");
29
+ if (colon === -1)
30
+ return undefined;
31
+ const ticketNumber = parseAddressTicket(token.slice(0, colon));
32
+ const { seat, round } = parseSeatRound(token.slice(colon + 1));
33
+ if (ticketNumber === undefined || seat === "" || round === undefined || round === "") {
34
+ return undefined;
35
+ }
36
+ return { ticketNumber, seat, round };
37
+ }
38
+ /**
39
+ * Run directory of the addressed leg under the caller's book directory.
40
+ * With a round: the leg that sealed that progress row (the row's receipt
41
+ * reference names it). Without: the seat's most recently active leg under the
42
+ * ticket, read off the leg directories themselves — rows exist only for accepted
43
+ * receipts, so a leg that has not submitted yet is still found. Activity is the
44
+ * leg directory's mtime: every turn takes and releases the leg's writer lease
45
+ * there. One `runs/` listing and one stat per leg of the seat.
46
+ */
47
+ export function locateTicketLeg(bookDirectory, input) {
48
+ const ticketDirectory = join(bookDirectory, String(input.ticketNumber));
49
+ if (!existsSync(ticketDirectory)) {
50
+ throw new CliUsageError(`ticket ${input.ticketNumber} has no records in this project's book: ${ticketDirectory}`);
51
+ }
52
+ if (input.round !== undefined) {
53
+ const row = readTicketProgressLines(ticketDirectory)
54
+ .find((line) => line.seat === input.seat && line.round === input.round);
55
+ if (row === undefined) {
56
+ throw new CliUsageError(`ticket ${input.ticketNumber} has no progress row ${input.seat}#${input.round}`);
57
+ }
58
+ // `runs/<leg>/receipts/<n>.json`
59
+ return join(ticketDirectory, ...row.receipt.split("/").slice(0, 2));
60
+ }
61
+ const runsDirectory = join(ticketDirectory, "runs");
62
+ let latest;
63
+ for (const entry of existsSync(runsDirectory) ? readdirSync(runsDirectory, { withFileTypes: true }) : []) {
64
+ if (!entry.isDirectory() || parseRunLeaf(entry.name)?.role !== input.seat)
65
+ continue;
66
+ const { mtimeMs } = statSync(join(runsDirectory, entry.name));
67
+ if (latest === undefined
68
+ || mtimeMs > latest.mtimeMs
69
+ || (mtimeMs === latest.mtimeMs && entry.name > latest.leaf)) {
70
+ latest = { leaf: entry.name, mtimeMs };
71
+ }
72
+ }
73
+ if (latest === undefined) {
74
+ throw new CliUsageError(`ticket ${input.ticketNumber} has no ${input.seat} leg`);
75
+ }
76
+ return join(runsDirectory, latest.leaf);
77
+ }
@@ -19,6 +19,9 @@ import { runDirectoryFromHostContext } from "./host-contracts.js";
19
19
  import { packagedGateStageLabel, receiptStatus } from "./packaged-role-registry.js";
20
20
  import { isUnboundRunDirectory, sessionDirectoryOf, sessionFileOf, subjectDirectoryOfRun, } from "./role-run-placement.js";
21
21
  import { readPageSync } from "./run-dossier.js";
22
+ import { PROGRESS_RECORD_KIND } from "./run-dossier-files.js";
23
+ import { runIdFromRunDirectory } from "./run-terminal-artifacts.js";
24
+ import { sitianReport } from "./sitian-facade.js";
22
25
  import { parseSitianRecordText } from "./sitian-reader.js";
23
26
  import { errorText, isRecord } from "./unknown-value.js";
24
27
  const CURRENT_FILENAME = "current.jsonl";
@@ -202,6 +205,30 @@ export function captureWorktreeHead(projectRoot) {
202
205
  return { head: "", fault: `git rev-parse HEAD threw cwd=${projectRoot}: ${message}` };
203
206
  }
204
207
  }
208
+ /**
209
+ * #1201: the row just written rides the leg's submission ledger to the process
210
+ * that prints the terminal — settlement reads round and receipt beside the
211
+ * sealed payload, and never picks rows out of current.jsonl after the turn.
212
+ * A seal names its tool call; a publish (round filled at bind) names the receipt.
213
+ */
214
+ function carryProgressRow(runDirectory, line, call) {
215
+ const runId = runIdFromRunDirectory(runDirectory);
216
+ if (runId === undefined)
217
+ return;
218
+ sitianReport({
219
+ level: "event",
220
+ kind: PROGRESS_RECORD_KIND,
221
+ subject: { runId, ...(call === undefined ? {} : { attemptId: call.attemptId }) },
222
+ payload: {
223
+ type: PROGRESS_RECORD_KIND,
224
+ ...(call === undefined ? {} : { toolCallId: call.toolCallId }),
225
+ receipt: line.receipt,
226
+ round: line.round,
227
+ },
228
+ source: "ticket-progress",
229
+ sessionParent: sessionFileOf(runDirectory),
230
+ });
231
+ }
205
232
  function progressSessionAbsolute(runDirectory, context) {
206
233
  const host = typeof context.host === "string" ? context.host.trim() : "";
207
234
  const sessionDirectory = sessionDirectoryOf(runDirectory);
@@ -236,6 +263,7 @@ export function landTicketProgressForSealedSubmission(input) {
236
263
  role: input.role,
237
264
  accepted: input.accepted,
238
265
  sealHead: input.sealHead,
266
+ call: input.call,
239
267
  ...(input.lens === undefined ? {} : { lens: input.lens }),
240
268
  sessionFile: progressSessionAbsolute(runDirectory, input.context),
241
269
  instruction: typeof input.context.summonsInstruction === "string"
@@ -298,6 +326,7 @@ export function landTicketProgress(input) {
298
326
  };
299
327
  mkdirSync(dirname(progressPath), { recursive: true });
300
328
  appendFileSync(progressPath, `${JSON.stringify(line)}\n`, "utf8");
329
+ carryProgressRow(runDirectory, line, input.call);
301
330
  // HEAD capture fault: keep the raw cause on stderr. Do not invent a second
302
331
  // dossier custom-frame channel beside post-admission's existing retain path.
303
332
  if (input.sealHead.fault !== undefined) {
@@ -357,4 +386,6 @@ export function relocateTicketProgressForLeg(input) {
357
386
  appendFileSync(newCurrent, `${movedLines.map((line) => JSON.stringify(line)).join("\n")}\n`, "utf8");
358
387
  // Append succeeded — drop staging. Failure above leaves progress.jsonl in place.
359
388
  rmSync(stagedPath, { force: true });
389
+ for (const moved of movedLines)
390
+ carryProgressRow(input.runDirectory, moved);
360
391
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akagilnc/pi-workflow-roles",
3
- "version": "0.1.6115",
3
+ "version": "0.1.6123",
4
4
  "description": "Soul-bound workflow roles for Pi",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -43,7 +43,8 @@ export const ENGINE_DETOUR_TOOL_USAGE_FACT_KEY = "engineDetourToolUsage" as cons
43
43
 
44
44
  /**
45
45
  * Run-relative path of the log that holds one detour call's record.
46
- * Openable once the run directory is known from the terminal's run id.
46
+ * Openable once the leg directory is known from the paths the terminal reports
47
+ * (receipt, artifact, or the no-receipt run pointer).
47
48
  * Contains no runId bytes itself (#108 + #537).
48
49
  */
49
50
  export const ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE = RUN_LOG_FILE;
@@ -36,8 +36,8 @@ export type GatekeeperSubject =
36
36
  * Code only reads the conclusion field for queueing. Officer words ride as
37
37
  * `receipt` unchanged — no findings rewrite, no unreadable/unusable label,
38
38
  * no next-step selection for the parent.
39
- * `runId` is the nested officer run id when known (summoned.runDirectory /
40
- * terminal.runId) so callers resume that seat; parent public finals do not
39
+ * `runId` is the nested officer run id when known (from summoned.runDirectory)
40
+ * so callers resume that seat; parent public finals do not
41
41
  * project other-seat tables (#1195).
42
42
  */
43
43
  export type GatekeeperResult =
@@ -215,21 +215,9 @@ function projectOfficerPayloads(
215
215
  return projectOfficerDecision(officer, payloads[payloads.length - 1], fallbackStatus);
216
216
  }
217
217
 
218
- /** Nested officer runId from summoned.runDirectory, else terminal.runId (resume identity). */
218
+ /** Nested officer runId from the summoned leg's run directory (package-internal resume identity). */
219
219
  export function officerRunIdFromSummoned(summoned: PublicSummonResult): string | undefined {
220
- if (typeof summoned.runDirectory === "string" && summoned.runDirectory.trim() !== "") {
221
- const fromDir = runIdFromRunDirectory(summoned.runDirectory);
222
- if (fromDir !== undefined) return fromDir;
223
- }
224
- const terminal = summoned.terminal;
225
- if (
226
- terminal !== undefined
227
- && typeof terminal.runId === "string"
228
- && terminal.runId.trim() !== ""
229
- ) {
230
- return terminal.runId;
231
- }
232
- return undefined;
220
+ return summoned.runDirectory === undefined ? undefined : runIdFromRunDirectory(summoned.runDirectory);
233
221
  }
234
222
 
235
223
  function withOfficerRunId(
@@ -303,8 +291,7 @@ function projectOfficerTerminal(
303
291
  }
304
292
  if (outcome.kind === "accepted") {
305
293
  // Nested / prior incomplete (directionUnsettled) is not a gate pass (ADR 0055).
306
- // Receipt stays this-court or retained; runId comes from the summoned volume
307
- // (public-role-summons already prefers nested terminal.runId when roles differ).
294
+ // Receipt stays this-court or retained; runId comes from the summoned volume.
308
295
  // No parent-side officerPayloads / officerRunId copies (#1195).
309
296
  if (outcome.decisiveFacts?.directionUnsettled === true) {
310
297
  const receipt = thisCourt.length > 0 ? thisCourt[thisCourt.length - 1] : retainedReceipt(outcome);
@@ -13,8 +13,9 @@ import {
13
13
  resolveActivationLedgerHome,
14
14
  } from "./activation-ledger-topology.ts";
15
15
  import type { NotarySourceRunLocator } from "./notary-contracts.ts";
16
- import { findRunDirectoryById, resolveLiveRunDirectoryPath, readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
17
- import { formatRunLeaf, parseRunLeaf } from "./role-run-placement.ts";
16
+ import { resolveLiveRunDirectoryPath, readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
17
+ import { parseRunLeaf } from "./role-run-placement.ts";
18
+ import { locateTicketLeg, parseTicketLegLocator } from "./ticket-address.ts";
18
19
 
19
20
  async function readRetainedIdentity(runDirectory: string) {
20
21
  try {
@@ -70,8 +71,8 @@ async function requireRunDirectory(candidate: string, display: string): Promise<
70
71
  /**
71
72
  * Resolve `--source-run` to a machine-ledger retained run directory and typed identity.
72
73
  * Accepts:
73
- * - bare `<runId>@<role>` under the project's book runs home
74
- * - absolute/relative path that realpath's to that same book runs slot
74
+ * - `<ticket>:<seat>#<round>` — the leg that sealed that progress row (#1201)
75
+ * - absolute/relative path that realpath's to a run under the project's book
75
76
  *
76
77
  * Rejects project-tree projections and any path outside the project's ledger book runs.
77
78
  * Retained state.jsonl run-state must match basename identity and book binding.
@@ -92,10 +93,9 @@ export async function resolveNotarySourceRunLocator(options: {
92
93
  const bookRunsRoot = join(bookDirectory, "runs");
93
94
 
94
95
  let candidate: string;
95
- const bare = parseRunLeaf(raw);
96
- if (bare !== undefined && !raw.includes("/") && !raw.includes("\\")) {
97
- candidate = (await findRunDirectoryById(options.home, bare.runId, bookKey, bare.role))
98
- ?? join(bookRunsRoot, formatRunLeaf(bare.runId, bare.role));
96
+ const address = parseTicketLegLocator(raw);
97
+ if (address !== undefined) {
98
+ candidate = locateTicketLeg(bookDirectory, address);
99
99
  } else {
100
100
  candidate = isAbsolute(raw) ? raw : resolve(options.projectRoot, raw);
101
101
  const identity = parseRunLeaf(basename(candidate));
@@ -29,6 +29,7 @@ import { processCancelSignalName } from "./process-cancel.ts";
29
29
  import { isLawfulTypedTerminalOutcome, formatTerminalResult, type TerminalArtifactRef, type TerminalResult, type TerminalRoleName } from "./terminal.ts";
30
30
  import {
31
31
  attachRecordedSubmissions,
32
+ filedIdentity,
32
33
  presentFailureTerminal,
33
34
  retainPackageFault,
34
35
  } from "./settlement.ts";
@@ -249,7 +250,7 @@ async function attachDispatchExceptionTerminal(
249
250
  */
250
251
  function dispatchExceptionFailureTerminal(input: {
251
252
  role: TerminalRoleName;
252
- runId: string;
253
+ runDirectory: string;
253
254
  causeError: unknown;
254
255
  errorFiles: readonly string[];
255
256
  autoResumeAttempts: number;
@@ -291,7 +292,7 @@ function dispatchExceptionFailureTerminal(input: {
291
292
  },
292
293
  navigator: { disposition: "no-advice" },
293
294
  artifacts,
294
- runId: input.runId,
295
+ ...filedIdentity(input.runDirectory),
295
296
  autoResumeCount: input.autoResumeAttempts,
296
297
  };
297
298
  }
@@ -472,7 +473,7 @@ export async function runWithAutoResumeLoop<
472
473
  options.admitted,
473
474
  dispatchExceptionFailureTerminal({
474
475
  role: options.admitted.role,
475
- runId: options.admitted.runId,
476
+ runDirectory: options.admitted.runDirectory,
476
477
  causeError: lastThrownError,
477
478
  errorFiles: retainedErrorFiles,
478
479
  autoResumeAttempts,
@@ -87,9 +87,20 @@ import {
87
87
  } from "./instruction-seat-run.ts";
88
88
  import { latestPayloadEscalated } from "./countersign-run.ts";
89
89
  import { runPublicAnalyst } from "./analyst-run.ts";
90
+ import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
91
+ import {
92
+ activationBookDirectory,
93
+ resolveActivationLedgerHome,
94
+ } from "../activation-ledger-topology.ts";
95
+ import { runIdFromRunDirectory } from "../run-terminal-artifacts.ts";
96
+ import {
97
+ locateTicketLeg,
98
+ parseAddressTicket,
99
+ parseSeatRound,
100
+ type TicketLegAddress,
101
+ } from "../ticket-address.ts";
90
102
  import {
91
103
  AUTO_RESUME_LIMIT,
92
- findRunDirectoryById,
93
104
  peekRoleRunRole,
94
105
  type PublicResumeRequest,
95
106
  } from "./run-lifecycle.ts";
@@ -441,9 +452,9 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
441
452
  // Global flags may appear before or after the subcommand
442
453
  // (`ak-role --model x roles` and `ak-role roles --model x`).
443
454
  // Grammar authority: shared typed consumer over PUBLIC_OPTION_TABLE.global.
444
- // #471: after `resume <runId>`, remaining argv is the opaque message segment
445
- // and must not re-enter the global-option consumer — including bare `--`,
446
- // which is a legal opaque message token, not an argv delimiter here.
455
+ // #471 / #1201: after `resume <ticket>`, remaining argv is the seat and the
456
+ // opaque message and must not re-enter the global-option consumer — including
457
+ // bare `--`, which is a legal opaque message token, not an argv delimiter here.
447
458
  while (args.length > 0) {
448
459
  if (positional[0] === "resume" && positional.length >= 2) {
449
460
  positional.push(...args);
@@ -507,24 +518,30 @@ function parseArgv(argv: readonly string[]): ParsedGlobal {
507
518
  }
508
519
 
509
520
  /**
510
- * Unique public resume request parser (#471).
511
- * One optional argv after runId is the opaque message; no further positionals.
521
+ * Unique public resume address parser (#471 / #1201): ticket, seat (optionally
522
+ * `#<round>`), then one optional opaque message argv; no further positionals.
512
523
  */
513
524
  const RESUME_USAGE_ERROR =
514
- "usage: ak-role resume <runId> [message] (put --model/--thinking/--host/--engine before <runId>; the one argv after <runId> is the opaque message, #471)";
525
+ "usage: ak-role resume <ticket> <seat>[#<round>] [message] (ticket is the bare number; put --model/--thinking/--host/--engine before <ticket>; the one argv after <seat> is the opaque message)";
515
526
 
516
- function parseResumeRequest(args: readonly string[]): PublicResumeRequest {
517
- const runId = args[0];
518
- if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
519
- throw new CliUsageError(RESUME_USAGE_ERROR);
520
- }
521
- if (args.length > 2) {
527
+ function parseResumeAddress(
528
+ args: readonly string[],
529
+ ): TicketLegAddress & { readonly seat: PublicCallableRole; readonly message?: string } {
530
+ const [ticketToken, seatToken, ...rest] = args;
531
+ const ticketNumber = ticketToken === undefined ? undefined : parseAddressTicket(ticketToken);
532
+ if (ticketNumber === undefined || seatToken === undefined || rest.length > 1) {
522
533
  throw new CliUsageError(RESUME_USAGE_ERROR);
523
534
  }
524
- if (args.length === 2) {
525
- return { runId, message: args[1]! };
535
+ const { seat, round } = parseSeatRound(seatToken);
536
+ if (!isPublicCallableRole(seat) || round === "") {
537
+ throw new CliUsageError(`${RESUME_USAGE_ERROR}; not a callable seat: ${seatToken}`);
526
538
  }
527
- return { runId };
539
+ return {
540
+ ticketNumber,
541
+ seat,
542
+ ...(round === undefined ? {} : { round }),
543
+ ...(rest.length === 0 ? {} : { message: rest[0]! }),
544
+ };
528
545
  }
529
546
 
530
547
  function invocationFromParsed(parsed: ParsedGlobal): InvocationModelOverride | undefined {
@@ -670,7 +687,7 @@ function renderHelp(): string {
670
687
  "Host providers: ~/.ak-roles/host-providers.json (owner-edited; table > unique host directory > fail)",
671
688
  "Model resolution: --model → persistent seat → officer inherit (#620); still none → error (#178)",
672
689
  "Host resolution: --host → persistent seat host → pi (resume uses the same order; #617)",
673
- "Resume flag position: --model/--thinking/--host/--engine go before <runId> (before `resume` or between `resume` and <runId>); the one argv after <runId> is always the opaque message, never a flag (#471)",
690
+ "Resume address: ak-role resume <ticket> <seat>[#<round>] [message]; --model/--thinking/--host/--engine go before <ticket> (before `resume` or between `resume` and <ticket>); the one argv after <seat> is always the opaque message, never a flag (#471)",
674
691
  "Effective seats: ak-role roles",
675
692
  );
676
693
  return `${lines.join("\n")}\n`;
@@ -1186,34 +1203,38 @@ export async function runAkRole(
1186
1203
  env = { ...env, freshSummons: true };
1187
1204
  }
1188
1205
 
1189
- // Resume reopens an exact Role run (#416): caller decides; session principal
1190
- // must still exist. Seat and dispatch follow the durable admitted role.
1191
- // #471: unique parser owns {runId, message?}; five role paths only consume it.
1206
+ // Resume reopens one leg of a ticket (#416 / #1201): caller decides; session
1207
+ // principal must still exist. The address is ticket + seat (+ round); only
1208
+ // legs filed under the ticket are in it.
1192
1209
  if (parsed.command === "resume") {
1193
- let resumeRequest = parseResumeRequest(parsed.args);
1210
+ const address = parseResumeAddress(parsed.args);
1211
+ const runDirectory = locateTicketLeg(
1212
+ activationBookDirectory(
1213
+ resolveActivationLedgerHome(home),
1214
+ resolveBookKeyFromGit(env.cwd ?? process.cwd()),
1215
+ ),
1216
+ address,
1217
+ );
1218
+ const resumeRequest: PublicResumeRequest = {
1219
+ runId: runIdFromRunDirectory(runDirectory)!,
1220
+ runDirectory,
1221
+ ...(address.message === undefined ? {} : { message: address.message }),
1222
+ };
1194
1223
  resumeFailureContext = {
1195
1224
  home,
1196
1225
  runId: resumeRequest.runId,
1226
+ runDirectory,
1197
1227
  authority: env.principalAuthority ?? piDurablePrincipalAuthority,
1198
1228
  };
1199
- const runDirectory = await findRunDirectoryById(home, resumeRequest.runId);
1200
- if (runDirectory !== undefined) {
1201
- resumeRequest = { ...resumeRequest, runDirectory };
1202
- resumeFailureContext = { ...resumeFailureContext, runDirectory };
1203
- }
1204
1229
  const parts = await loadPublicRoleDispatchParts(env, home);
1205
- const resumeRole = await peekRoleRunRole(home, resumeRequest.runId, resumeRequest);
1206
- // Missing durable role keeps the judge seat table. The resume entry
1207
- // itself is one function; it reads the stored run.
1208
- const seatRole = resumeRole ?? "judge";
1209
1230
  const seat = resolveEffectiveSeat(
1210
1231
  parts.config,
1211
- seatRole,
1232
+ address.seat,
1212
1233
  parts.credentials,
1213
1234
  invocationFromParsed(parsed),
1214
1235
  );
1215
1236
  const resumeEnv = createRoleEnvironment(env, {
1216
- role: seatRole,
1237
+ role: address.seat,
1217
1238
  home,
1218
1239
  agentDir: parts.agentDir,
1219
1240
  cwd: parts.cwd,
@@ -1837,8 +1837,7 @@ async function auditSubmittedRole(
1837
1837
  const pass = chain.passes.at(-1);
1838
1838
  const officerTerminal = pass?.terminal;
1839
1839
  const officerRunDirectory = pass?.runDirectory;
1840
- const officerRunId = pass?.runId
1841
- ?? (officerRunDirectory === undefined ? undefined : runIdFromRunDirectory(officerRunDirectory));
1840
+ const officerRunId = pass?.runId;
1842
1841
  if (officerTerminal !== undefined && officerRunId !== undefined) {
1843
1842
  // #1214 F1: present audited original and officer scene separately.
1844
1843
  await presentAuditedOriginalVolume(turn, io);
@@ -1887,9 +1886,7 @@ async function auditSubmittedRole(
1887
1886
  if (chain.status === "escalate") {
1888
1887
  const escalation = chain.passes.at(-1);
1889
1888
  const escalatedRunDirectory = escalation?.runDirectory;
1890
- const escalatedRunId = escalation?.runId
1891
- ?? (escalatedRunDirectory === undefined
1892
- ? undefined : runIdFromRunDirectory(escalatedRunDirectory));
1889
+ const escalatedRunId = escalation?.runId;
1893
1890
  if (escalatedRunId === undefined) {
1894
1891
  return incompleteAuditWithoutOfficerVolume(
1895
1892
  turn,
@@ -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
  },