@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
@@ -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
+ }
@@ -16,26 +16,28 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSyn
16
16
  import { basename, dirname, join, relative, sep } from "node:path";
17
17
  import { resolveHostDossierLandingPath } from "./host-session-record.js";
18
18
  import { runDirectoryFromHostContext } from "./host-contracts.js";
19
- import { receiptStatus } from "./packaged-role-registry.js";
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
- import { isRecord } from "./unknown-value.js";
26
+ import { errorText, isRecord } from "./unknown-value.js";
24
27
  const CURRENT_FILENAME = "current.jsonl";
25
28
  const RECEIPTS_DIRNAME = "receipts";
26
29
  const LEG_PROGRESS_FILENAME = "progress.jsonl";
27
30
  /**
28
- * Append-only progress JSONL — same posture as run-dossier row files:
29
- * sole Sitian decoder keeps reachable rows; malformed lines leave diagnostics
30
- * on stderr and do not abort seal/relocate.
31
+ * Append-only progress JSONL through the sole Sitian decoder: reachable rows
32
+ * plus one diagnostic per malformed line.
31
33
  */
32
- function parseProgressText(text, pathForDiagnostic) {
34
+ function decodeProgressFile(path) {
35
+ if (!existsSync(path))
36
+ return { lines: [], malformed: [] };
37
+ const text = readFileSync(path, "utf8");
33
38
  if (text.trim() === "")
34
- return [];
39
+ return { lines: [], malformed: [] };
35
40
  const { records, diagnostics } = parseSitianRecordText(text);
36
- for (const diagnostic of diagnostics) {
37
- process.stderr.write(`[ticket-progress] ${pathForDiagnostic} has malformed row(s); keeps reachable rows and retains the diagnostic: line ${diagnostic.line}: ${diagnostic.error}\n`);
38
- }
39
41
  const lines = [];
40
42
  for (const record of records) {
41
43
  const parsed = record;
@@ -45,12 +47,21 @@ function parseProgressText(text, pathForDiagnostic) {
45
47
  continue;
46
48
  lines.push(parsed);
47
49
  }
48
- return lines;
50
+ return {
51
+ lines,
52
+ malformed: diagnostics.map((diagnostic) => `line ${diagnostic.line}: ${diagnostic.error}`),
53
+ };
49
54
  }
55
+ /**
56
+ * Same posture as run-dossier row files: malformed lines leave diagnostics on
57
+ * stderr and do not abort seal/relocate.
58
+ */
50
59
  function readProgressFile(path) {
51
- if (!existsSync(path))
52
- return [];
53
- return parseProgressText(readFileSync(path, "utf8"), path);
60
+ const { lines, malformed } = decodeProgressFile(path);
61
+ for (const diagnostic of malformed) {
62
+ process.stderr.write(`[ticket-progress] ${path} has malformed row(s); keeps reachable rows and retains the diagnostic: ${diagnostic}\n`);
63
+ }
64
+ return lines;
54
65
  }
55
66
  /**
56
67
  * Read progress rows under a subject.
@@ -125,6 +136,41 @@ function statusAndSummaryFromPayload(payload) {
125
136
  ...(summary === undefined ? {} : { summary }),
126
137
  };
127
138
  }
139
+ /**
140
+ * #1200「审 谁#轮」as the ticket has it now: the audited leg's latest row. Read
141
+ * at the officer's admission, before the officer runs. An audited leg with no
142
+ * round yet (unbound, or no accepted receipt) has none. A progress file that
143
+ * cannot be read or has malformed rows has none either and returns the cause
144
+ * for the caller to retain — the officer still runs.
145
+ */
146
+ export function readAuditedRound(auditedRunDirectory) {
147
+ try {
148
+ const subjectDirectory = subjectDirectoryOfRun(auditedRunDirectory);
149
+ if (subjectDirectory === undefined)
150
+ return {};
151
+ const path = join(subjectDirectory, CURRENT_FILENAME);
152
+ const { lines, malformed } = decodeProgressFile(path);
153
+ if (malformed.length > 0) {
154
+ throw new Error(`${path} has malformed row(s): ${malformed.join("; ")}`);
155
+ }
156
+ const receipts = `runs/${basename(auditedRunDirectory)}/`;
157
+ const latest = lines.filter((line) => line.receipt.startsWith(receipts)).at(-1);
158
+ return latest === undefined ? {} : { for: `${latest.seat}#${latest.round}` };
159
+ }
160
+ catch (error) {
161
+ return { fault: `audited round unavailable for ${auditedRunDirectory}: ${errorText(error)}` };
162
+ }
163
+ }
164
+ /**
165
+ * The row's `for`: gate officers copy the admission pin; the fixer's receipt
166
+ * reports its own (copied when it is a string, never checked). No other seat has one.
167
+ */
168
+ function forOfSealedRow(runDirectory, seat, payload) {
169
+ const reported = packagedGateStageLabel(seat) !== undefined
170
+ ? readPageSync(runDirectory, "admitted")?.for
171
+ : seat === "fixer" && isRecord(payload) ? payload.for : undefined;
172
+ return typeof reported === "string" ? reported : undefined;
173
+ }
128
174
  /** Worktree HEAD at seal. On failure head is empty and fault carries the true cause. */
129
175
  export function captureWorktreeHead(projectRoot) {
130
176
  try {
@@ -159,6 +205,30 @@ export function captureWorktreeHead(projectRoot) {
159
205
  return { head: "", fault: `git rev-parse HEAD threw cwd=${projectRoot}: ${message}` };
160
206
  }
161
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
+ }
162
232
  function progressSessionAbsolute(runDirectory, context) {
163
233
  const host = typeof context.host === "string" ? context.host.trim() : "";
164
234
  const sessionDirectory = sessionDirectoryOf(runDirectory);
@@ -193,6 +263,7 @@ export function landTicketProgressForSealedSubmission(input) {
193
263
  role: input.role,
194
264
  accepted: input.accepted,
195
265
  sealHead: input.sealHead,
266
+ call: input.call,
196
267
  ...(input.lens === undefined ? {} : { lens: input.lens }),
197
268
  sessionFile: progressSessionAbsolute(runDirectory, input.context),
198
269
  instruction: typeof input.context.summonsInstruction === "string"
@@ -239,11 +310,13 @@ export function landTicketProgress(input) {
239
310
  ? ""
240
311
  : relative(subjectDirectory, input.sessionFile).split(sep).join("/");
241
312
  const { status, summary } = statusAndSummaryFromPayload(input.accepted);
313
+ const reviewed = forOfSealedRow(runDirectory, input.role, input.accepted);
242
314
  const instruction = input.instruction;
243
315
  const line = {
244
316
  at: new Date().toISOString(),
245
317
  seat: input.role,
246
318
  round,
319
+ ...(reviewed === undefined ? {} : { for: reviewed }),
247
320
  instruction,
248
321
  head: input.sealHead.head,
249
322
  ...(status === undefined ? {} : { status }),
@@ -253,6 +326,7 @@ export function landTicketProgress(input) {
253
326
  };
254
327
  mkdirSync(dirname(progressPath), { recursive: true });
255
328
  appendFileSync(progressPath, `${JSON.stringify(line)}\n`, "utf8");
329
+ carryProgressRow(runDirectory, line, input.call);
256
330
  // HEAD capture fault: keep the raw cause on stderr. Do not invent a second
257
331
  // dossier custom-frame channel beside post-admission's existing retain path.
258
332
  if (input.sealHead.fault !== undefined) {
@@ -312,4 +386,6 @@ export function relocateTicketProgressForLeg(input) {
312
386
  appendFileSync(newCurrent, `${movedLines.map((line) => JSON.stringify(line)).join("\n")}\n`, "utf8");
313
387
  // Append succeeded — drop staging. Failure above leaves progress.jsonl in place.
314
388
  rmSync(stagedPath, { force: true });
389
+ for (const moved of movedLines)
390
+ carryProgressRow(input.runDirectory, moved);
315
391
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akagilnc/pi-workflow-roles",
3
- "version": "0.1.6111",
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));
@@ -31,6 +31,9 @@ const fixerOutputObject = Type.Object({
31
31
  description:
32
32
  "各类 class 结算,原样留存。每类写 name、shape(错误形状一句)。按代码形状认的类写 search(实际跑的搜索命令,原样)、hits(命令输出的每个命中一行 { where: path:line, outcome: 已修 | 不同类:理由 });按情形认的类写 cases(每种前序经历一行 { case: 对象先经历了什么, entry: 从真实入口怎么走到它, before: 修前结果, after: 修后结果 })。删并类写 files(本票起点到 HEAD 的 git diff --name-status 里每个文件一行 { file, hits: 该类在此文件的命中 path:line 列表,没有为空, outcome: 已修 | 无:比对了哪几处、为什么不算 | 未修:理由 })。完成项的 disposition 为 completed,可写 commitSha。拒绝项的 disposition 为 refused,可写 remainingScope、blocker。",
33
33
  }),
34
+ for: Type.Unknown({
35
+ description: "修的是哪份判词:<席>#<轮>,如 judge#5,原样落到进度行;没有就填 null。",
36
+ }),
34
37
  diffItems: diffItemsField,
35
38
  testEvidence: Type.Unknown({
36
39
  description:
@@ -58,6 +61,7 @@ export type FixerOutput = {
58
61
  readonly blocker?: unknown;
59
62
  readonly reason?: unknown;
60
63
  readonly classResults?: unknown;
64
+ readonly for?: unknown;
61
65
  readonly testEvidence?: unknown;
62
66
  readonly diffItems?: unknown;
63
67
  };
@@ -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,