@akagilnc/pi-workflow-roles 0.1.6115 → 0.1.6126

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 (45) 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/description.js +4 -1
  7. package/dist/headless-host/production-host.js +340 -236
  8. package/dist/migrate-book-topology.js +39 -22
  9. package/dist/notary-source-run.js +8 -8
  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 +2 -5
  13. package/dist/public-cli/main.js +310 -208
  14. package/dist/public-cli/option-definitions.js +22 -21
  15. package/dist/public-cli/run-lifecycle.js +27 -26
  16. package/dist/public-cli/seat-ticket-binding.js +2 -1
  17. package/dist/public-cli/settlement.js +33 -8
  18. package/dist/public-cli/terminal.js +13 -3
  19. package/dist/public-role-summons.js +1 -7
  20. package/dist/role-run-placement.js +1 -1
  21. package/dist/run-dossier-files.js +4 -2
  22. package/dist/submission-gate.js +3 -3
  23. package/dist/submission-ledger.js +29 -3
  24. package/dist/ticket-address.js +77 -0
  25. package/dist/ticket-progress.js +31 -0
  26. package/package.json +1 -1
  27. package/src/engine-detour-usage.ts +2 -1
  28. package/src/gatekeeper-role.ts +5 -18
  29. package/src/headless-host/description.ts +4 -1
  30. package/src/notary-source-run.ts +8 -8
  31. package/src/public-cli/auto-resume.ts +4 -3
  32. package/src/public-cli/cli.ts +53 -32
  33. package/src/public-cli/instruction-seat-run.ts +2 -5
  34. package/src/public-cli/option-definitions.ts +22 -21
  35. package/src/public-cli/run-lifecycle.ts +31 -31
  36. package/src/public-cli/seat-ticket-binding.ts +2 -1
  37. package/src/public-cli/settlement.ts +43 -7
  38. package/src/public-cli/terminal.ts +33 -14
  39. package/src/public-role-summons.ts +3 -15
  40. package/src/role-run-placement.ts +1 -1
  41. package/src/run-dossier-files.ts +5 -2
  42. package/src/submission-gate.ts +3 -2
  43. package/src/submission-ledger.ts +32 -2
  44. package/src/ticket-address.ts +91 -0
  45. package/src/ticket-progress.ts +42 -0
@@ -832,7 +832,8 @@ var init_run_dossier_files = __esm({
832
832
  "post-seal-anomaly",
833
833
  "attempt-history",
834
834
  "turn-delivery",
835
- "officer-pointer"
835
+ "officer-pointer",
836
+ "progress"
836
837
  ]);
837
838
  RUN_STATE_KINDS = /* @__PURE__ */ new Set([
838
839
  "invocation",
@@ -10617,6 +10618,9 @@ var init_ticket_progress = __esm({
10617
10618
  init_packaged_role_registry();
10618
10619
  init_role_run_placement();
10619
10620
  init_run_dossier();
10621
+ init_run_dossier_files();
10622
+ init_run_terminal_artifacts();
10623
+ init_sitian_facade();
10620
10624
  init_sitian_reader();
10621
10625
  init_unknown_value();
10622
10626
  }
@@ -10746,6 +10750,17 @@ var init_uuidv7 = __esm({
10746
10750
  }
10747
10751
  });
10748
10752
 
10753
+ // src/ticket-address.ts
10754
+ var init_ticket_address = __esm({
10755
+ "src/ticket-address.ts"() {
10756
+ "use strict";
10757
+ init_cli_errors();
10758
+ init_role_run_placement();
10759
+ init_run_ticket_number();
10760
+ init_ticket_progress();
10761
+ }
10762
+ });
10763
+
10749
10764
  // src/notary-source-run.ts
10750
10765
  var init_notary_source_run = __esm({
10751
10766
  "src/notary-source-run.ts"() {
@@ -10754,6 +10769,7 @@ var init_notary_source_run = __esm({
10754
10769
  init_activation_ledger_topology();
10755
10770
  init_run_lifecycle();
10756
10771
  init_role_run_placement();
10772
+ init_ticket_address();
10757
10773
  }
10758
10774
  });
10759
10775
 
@@ -10935,7 +10951,7 @@ var init_option_definitions = __esm({
10935
10951
  owner: "auditor",
10936
10952
  canonical: "--source-run",
10937
10953
  aliases: [],
10938
- valueMetavar: "runId@role|path",
10954
+ valueMetavar: "ticket:seat#round|path",
10939
10955
  required: true,
10940
10956
  repeatable: false,
10941
10957
  form: "option",
@@ -11113,13 +11129,13 @@ var init_option_definitions = __esm({
11113
11129
  owner: "notary",
11114
11130
  canonical: "--source-run",
11115
11131
  aliases: [],
11116
- valueMetavar: "runId@role|path",
11132
+ valueMetavar: "ticket:seat#round|path",
11117
11133
  required: true,
11118
11134
  repeatable: false,
11119
11135
  form: "option",
11120
11136
  description: {
11121
- 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.",
11122
- zh: "\u5FC5\u586B\u6E90 run \u5B9A\u4F4D\u7B26\uFF08\u7C3F\u5185 runId@role\uFF0C\u6216\u8BE5 run \u76EE\u5F55\u8DEF\u5F84\uFF09\u3002\u7ED1\u5B9A\u53D7\u5BA1\u8EAB\u4EFD\uFF1B\u5BA1\u7A3F\u5BF9\u8BDD\u4E3A\u7B26\u5B9D\u90CE\u56FA\u5B9A\u6D3E\u5355\u6587\uFF08\u5224\u8BCD\u7559\u5728\u5377\u5B97\u81EA\u884C\u8BFB\u53D6\uFF09\u3002\u7F3A\u7968\u53F7\u4E0E\u8BFB\u4E0D\u51FA status \u7684\u91CD\u4EA4\u4ECD\u9012\u65E2\u6709\u8BCA\u65AD\u539F\u6587\u3002"
11137
+ 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.",
11138
+ zh: "\u5FC5\u586B\u6E90 run \u5B9A\u4F4D\u7B26\uFF08<\u7968\u53F7>:<\u5E2D>#<\u8F6E>\uFF0C\u8F6E\u7167\u8FDB\u5EA6\u884C\u4E0A\u7684\u5199\u6CD5\uFF1B\u6216\u8BE5 run \u76EE\u5F55\u8DEF\u5F84\uFF09\u3002\u7ED1\u5B9A\u53D7\u5BA1\u8EAB\u4EFD\uFF1B\u5BA1\u7A3F\u5BF9\u8BDD\u4E3A\u7B26\u5B9D\u90CE\u56FA\u5B9A\u6D3E\u5355\u6587\uFF08\u5224\u8BCD\u7559\u5728\u5377\u5B97\u81EA\u884C\u8BFB\u53D6\uFF09\u3002\u7F3A\u7968\u53F7\u4E0E\u8BFB\u4E0D\u51FA status \u7684\u91CD\u4EA4\u4ECD\u9012\u65E2\u6709\u8BCA\u65AD\u539F\u6587\u3002"
11123
11139
  }
11124
11140
  }
11125
11141
  ];
@@ -11130,13 +11146,13 @@ var init_option_definitions = __esm({
11130
11146
  owner: "inspector",
11131
11147
  canonical: "--source-run",
11132
11148
  aliases: [],
11133
- valueMetavar: "runId@role|path",
11149
+ valueMetavar: "ticket:seat#round|path",
11134
11150
  required: false,
11135
11151
  repeatable: false,
11136
11152
  form: "option",
11137
11153
  description: {
11138
- en: "Optional audited source-run locator (runId@role or path). Gate summons always supply it; identity rides startup materials.",
11139
- zh: "\u53EF\u9009\u88AB\u5BA1\u817F\u5B9A\u4F4D\u7B26\uFF08runId@role \u6216\u8DEF\u5F84\uFF09\u3002\u95F8\u4F20\u53EC\u5FC5\u5E26\uFF1B\u8EAB\u4EFD\u5728\u542F\u52A8\u6750\u6599\u91CC\u3002"
11154
+ en: "Optional audited source-run locator (<ticket>:<seat>#<round> or path). Gate summons always supply it; identity rides startup materials.",
11155
+ zh: "\u53EF\u9009\u88AB\u5BA1\u817F\u5B9A\u4F4D\u7B26\uFF08<\u7968\u53F7>:<\u5E2D>#<\u8F6E> \u6216\u8DEF\u5F84\uFF09\u3002\u95F8\u4F20\u53EC\u5FC5\u5E26\uFF1B\u8EAB\u4EFD\u5728\u542F\u52A8\u6750\u6599\u91CC\u3002"
11140
11156
  }
11141
11157
  }
11142
11158
  ];
@@ -11430,10 +11446,10 @@ var init_option_definitions = __esm({
11430
11446
  auditor: {
11431
11447
  command: "auditor",
11432
11448
  summary: "Direct Auditor (\u5BA1\u5211\u9662) compliance audit: converged, continue, or escalate.",
11433
- usage: ["ak-role auditor --subject <judge|doctor> --source-run <runId@role|path> [options] [instruction]"],
11449
+ usage: ["ak-role auditor --subject <judge|doctor> --source-run <ticket:seat#round|path> [options] [instruction]"],
11434
11450
  examples: [
11435
- 'ak-role auditor --subject judge --source-run 01abc\u2026@judge --attach ./dossier "\u5BA1\uFF1A\u672C run \u662F\u5426\u5408\u89C4\u3002"',
11436
- 'ak-role auditor --subject doctor --source-run 01abc\u2026@doctor "\u5BA1\uFF1A\u592A\u533B\u5019\u9009\u662F\u5426\u5408\u89C4\u3002"'
11451
+ 'ak-role auditor --subject judge --source-run 1201:judge#2 --attach ./dossier "\u5BA1\uFF1A\u672C run \u662F\u5426\u5408\u89C4\u3002"',
11452
+ 'ak-role auditor --subject doctor --source-run 1201:doctor#1 "\u5BA1\uFF1A\u592A\u533B\u5019\u9009\u662F\u5426\u5408\u89C4\u3002"'
11437
11453
  ]
11438
11454
  },
11439
11455
  diarist: {
@@ -11456,10 +11472,10 @@ var init_option_definitions = __esm({
11456
11472
  notary: {
11457
11473
  command: "notary",
11458
11474
  summary: "Direct Notary summons; duties: souls/notary.md. Review uses fixed dispatch \u2014 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.",
11459
- usage: ["ak-role notary --source-run <runId@role|path> [options]"],
11475
+ usage: ["ak-role notary --source-run <ticket:seat#round|path> [options]"],
11460
11476
  examples: [
11461
- "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@judge",
11462
- "ak-role notary --source-run 01a034f1-75bf-71a6-bcf5-d1299145b1a5@countersign"
11477
+ "ak-role notary --source-run 1201:judge#2",
11478
+ "ak-role notary --source-run 1201:countersign#1"
11463
11479
  ]
11464
11480
  },
11465
11481
  analyst: {
@@ -11516,14 +11532,15 @@ var init_option_definitions = __esm({
11516
11532
  },
11517
11533
  resume: {
11518
11534
  command: "resume",
11519
- summary: "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).",
11520
- usage: ["ak-role resume <runId> [message]"],
11535
+ summary: "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).",
11536
+ usage: ["ak-role resume <ticket> <seat>[#<round>] [message]"],
11521
11537
  examples: [
11522
- "ak-role resume 01abc\u2026",
11523
- 'ak-role resume 01abc\u2026 "owner ruling"',
11524
- "ak-role --host grok-build resume 01abc\u2026",
11525
- "ak-role --engine agy resume 01abc\u2026",
11526
- 'ak-role resume --model xai/grok-4.5 01abc\u2026 "owner ruling"'
11538
+ "ak-role resume 1201 judge",
11539
+ 'ak-role resume 1201 judge "owner ruling"',
11540
+ "ak-role resume 1201 'reviewer#2.correctness'",
11541
+ "ak-role --host grok-build resume 1201 fixer",
11542
+ "ak-role --engine agy resume 1201 fixer",
11543
+ 'ak-role resume --model xai/grok-4.5 1201 notary "owner ruling"'
11527
11544
  ]
11528
11545
  },
11529
11546
  new: {
@@ -11532,7 +11549,7 @@ var init_option_definitions = __esm({
11532
11549
  usage: ["ak-role new <role> [options] \u2026"],
11533
11550
  examples: [
11534
11551
  'ak-role new countersign --attach ./ticket.md "\u88C1\uFF1A\u672C\u7968 #708 \u662F\u5426\u8DB3\u4EE5\u5F00\u5DE5\u3002"',
11535
- "ak-role new notary --source-run 01abc\u2026@countersign",
11552
+ "ak-role new notary --source-run 1201:countersign#1",
11536
11553
  "ak-role --host grok-build new inspector --attach ./change.patch"
11537
11554
  ]
11538
11555
  },
@@ -7,8 +7,9 @@ import { dirname, isAbsolute, join, resolve, basename } from "node:path";
7
7
  import { lstat, realpath } from "node:fs/promises";
8
8
  import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
9
9
  import { activationBookDirectory, physicalPathIdentity, resolveActivationLedgerHome, } from "./activation-ledger-topology.js";
10
- import { findRunDirectoryById, resolveLiveRunDirectoryPath, readRoleRunIdentity } from "./public-cli/run-lifecycle.js";
11
- import { formatRunLeaf, parseRunLeaf } from "./role-run-placement.js";
10
+ import { resolveLiveRunDirectoryPath, readRoleRunIdentity } from "./public-cli/run-lifecycle.js";
11
+ import { parseRunLeaf } from "./role-run-placement.js";
12
+ import { locateTicketLeg, parseTicketLegLocator } from "./ticket-address.js";
12
13
  async function readRetainedIdentity(runDirectory) {
13
14
  try {
14
15
  return await readRoleRunIdentity(runDirectory);
@@ -54,8 +55,8 @@ async function requireRunDirectory(candidate, display) {
54
55
  /**
55
56
  * Resolve `--source-run` to a machine-ledger retained run directory and typed identity.
56
57
  * Accepts:
57
- * - bare `<runId>@<role>` under the project's book runs home
58
- * - absolute/relative path that realpath's to that same book runs slot
58
+ * - `<ticket>:<seat>#<round>` — the leg that sealed that progress row (#1201)
59
+ * - absolute/relative path that realpath's to a run under the project's book
59
60
  *
60
61
  * Rejects project-tree projections and any path outside the project's ledger book runs.
61
62
  * Retained state.jsonl run-state must match basename identity and book binding.
@@ -70,10 +71,9 @@ export async function resolveNotarySourceRunLocator(options) {
70
71
  const bookDirectory = activationBookDirectory(ledgerHome, bookKey);
71
72
  const bookRunsRoot = join(bookDirectory, "runs");
72
73
  let candidate;
73
- const bare = parseRunLeaf(raw);
74
- if (bare !== undefined && !raw.includes("/") && !raw.includes("\\")) {
75
- candidate = (await findRunDirectoryById(options.home, bare.runId, bookKey, bare.role))
76
- ?? join(bookRunsRoot, formatRunLeaf(bare.runId, bare.role));
74
+ const address = parseTicketLegLocator(raw);
75
+ if (address !== undefined) {
76
+ candidate = locateTicketLeg(bookDirectory, address);
77
77
  }
78
78
  else {
79
79
  candidate = isAbsolute(raw) ? raw : resolve(options.projectRoot, raw);
@@ -2,7 +2,7 @@ import { AUTO_RESUME_LIMIT, describeErrorIdentity, acquireRunWriterLease, markRu
2
2
  import { parseAutoResumeLimit } from "./config.js";
3
3
  import { processCancelSignalName } from "./process-cancel.js";
4
4
  import { isLawfulTypedTerminalOutcome, formatTerminalResult } from "./terminal.js";
5
- import { attachRecordedSubmissions, presentFailureTerminal, retainPackageFault, } from "./settlement.js";
5
+ import { attachRecordedSubmissions, filedIdentity, presentFailureTerminal, retainPackageFault, } from "./settlement.js";
6
6
  import { serializeThrownValue } from "../serialize-thrown-value.js";
7
7
  import { reportRunRecord } from "../sitian-facade.js";
8
8
  import { errorText } from "../unknown-value.js";
@@ -199,7 +199,7 @@ function dispatchExceptionFailureTerminal(input) {
199
199
  },
200
200
  navigator: { disposition: "no-advice" },
201
201
  artifacts,
202
- runId: input.runId,
202
+ ...filedIdentity(input.runDirectory),
203
203
  autoResumeCount: input.autoResumeAttempts,
204
204
  };
205
205
  }
@@ -317,7 +317,7 @@ export async function runWithAutoResumeLoop(options) {
317
317
  const terminal = stoppedResult === undefined
318
318
  ? await attachDispatchExceptionTerminal(options.admitted, dispatchExceptionFailureTerminal({
319
319
  role: options.admitted.role,
320
- runId: options.admitted.runId,
320
+ runDirectory: options.admitted.runDirectory,
321
321
  causeError: lastThrownError,
322
322
  errorFiles: retainedErrorFiles,
323
323
  autoResumeAttempts,
@@ -23,7 +23,11 @@ import { readSessionDialogue, renderSessionDialogue } from "./dialogue-command.j
23
23
  import { continueParentAfterChild, presentAuditedOriginalOfUnsettledOfficer, runPublicInstructionSeat, runPublicInstructionSeatResume, } from "./instruction-seat-run.js";
24
24
  import { latestPayloadEscalated } from "./countersign-run.js";
25
25
  import { runPublicAnalyst } from "./analyst-run.js";
26
- import { AUTO_RESUME_LIMIT, findRunDirectoryById, peekRoleRunRole, } from "./run-lifecycle.js";
26
+ import { resolveBookKeyFromGit } from "../activation-ledger-git.js";
27
+ import { activationBookDirectory, resolveActivationLedgerHome, } from "../activation-ledger-topology.js";
28
+ import { runIdFromRunDirectory } from "../run-terminal-artifacts.js";
29
+ import { locateTicketLeg, parseAddressTicket, parseSeatRound, } from "../ticket-address.js";
30
+ import { AUTO_RESUME_LIMIT, peekRoleRunRole, } from "./run-lifecycle.js";
27
31
  import { INTERNAL_ROLE_ENTRYPOINT_RELATIVE, PUBLIC_CALLABLE_ROLES, isPublicCallableRole, isPublicCliSupportCommand, isPublicConfigurableSeat, listHelpCapabilities, } from "./registry.js";
28
32
  import { formatCliDiagnostic, formatErrorCauseDetail, presentStructuralRejection, } from "./settlement.js";
29
33
  import { errorText } from "../unknown-value.js";
@@ -205,9 +209,9 @@ function parseArgv(argv) {
205
209
  // Global flags may appear before or after the subcommand
206
210
  // (`ak-role --model x roles` and `ak-role roles --model x`).
207
211
  // Grammar authority: shared typed consumer over PUBLIC_OPTION_TABLE.global.
208
- // #471: after `resume <runId>`, remaining argv is the opaque message segment
209
- // and must not re-enter the global-option consumer — including bare `--`,
210
- // which is a legal opaque message token, not an argv delimiter here.
212
+ // #471 / #1201: after `resume <ticket>`, remaining argv is the seat and the
213
+ // opaque message and must not re-enter the global-option consumer — including
214
+ // bare `--`, which is a legal opaque message token, not an argv delimiter here.
211
215
  while (args.length > 0) {
212
216
  if (positional[0] === "resume" && positional.length >= 2) {
213
217
  positional.push(...args);
@@ -271,22 +275,26 @@ function parseArgv(argv) {
271
275
  };
272
276
  }
273
277
  /**
274
- * Unique public resume request parser (#471).
275
- * One optional argv after runId is the opaque message; no further positionals.
278
+ * Unique public resume address parser (#471 / #1201): ticket, seat (optionally
279
+ * `#<round>`), then one optional opaque message argv; no further positionals.
276
280
  */
277
- const RESUME_USAGE_ERROR = "usage: ak-role resume <runId> [message] (put --model/--thinking/--host/--engine before <runId>; the one argv after <runId> is the opaque message, #471)";
278
- function parseResumeRequest(args) {
279
- const runId = args[0];
280
- if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
281
+ const RESUME_USAGE_ERROR = "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)";
282
+ function parseResumeAddress(args) {
283
+ const [ticketToken, seatToken, ...rest] = args;
284
+ const ticketNumber = ticketToken === undefined ? undefined : parseAddressTicket(ticketToken);
285
+ if (ticketNumber === undefined || seatToken === undefined || rest.length > 1) {
281
286
  throw new CliUsageError(RESUME_USAGE_ERROR);
282
287
  }
283
- if (args.length > 2) {
284
- throw new CliUsageError(RESUME_USAGE_ERROR);
285
- }
286
- if (args.length === 2) {
287
- return { runId, message: args[1] };
288
+ const { seat, round } = parseSeatRound(seatToken);
289
+ if (!isPublicCallableRole(seat) || round === "") {
290
+ throw new CliUsageError(`${RESUME_USAGE_ERROR}; not a callable seat: ${seatToken}`);
288
291
  }
289
- return { runId };
292
+ return {
293
+ ticketNumber,
294
+ seat,
295
+ ...(round === undefined ? {} : { round }),
296
+ ...(rest.length === 0 ? {} : { message: rest[0] }),
297
+ };
290
298
  }
291
299
  function invocationFromParsed(parsed) {
292
300
  if (parsed.model === undefined &&
@@ -391,7 +399,7 @@ function renderHelp() {
391
399
  }
392
400
  lines.push("", "OPTIONS");
393
401
  lines.push(...renderHumanOwnerOptionLines("global"));
394
- lines.push("", "Role options: ak-role help <command>", "Persistent config: ak-role config set <seat> <provider/model[:thinking]> | unset <gatekeeper|inspector|notary>", "Persistent engine (callable roles): ak-role config set-engine <seat> <name> [model] | unset-engine <seat> | set-engine-model <seat> <model> | unset-engine-model <seat>", "Persistent host (callable roles): ak-role config set-host <seat> <name> | unset-host <seat>", "Host providers: ~/.ak-roles/host-providers.json (owner-edited; table > unique host directory > fail)", "Model resolution: --model → persistent seat → officer inherit (#620); still none → error (#178)", "Host resolution: --host → persistent seat host → pi (resume uses the same order; #617)", "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)", "Effective seats: ak-role roles");
402
+ lines.push("", "Role options: ak-role help <command>", "Persistent config: ak-role config set <seat> <provider/model[:thinking]> | unset <gatekeeper|inspector|notary>", "Persistent engine (callable roles): ak-role config set-engine <seat> <name> [model] | unset-engine <seat> | set-engine-model <seat> <model> | unset-engine-model <seat>", "Persistent host (callable roles): ak-role config set-host <seat> <name> | unset-host <seat>", "Host providers: ~/.ak-roles/host-providers.json (owner-edited; table > unique host directory > fail)", "Model resolution: --model → persistent seat → officer inherit (#620); still none → error (#178)", "Host resolution: --host → persistent seat host → pi (resume uses the same order; #617)", "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)", "Effective seats: ak-role roles");
395
403
  return `${lines.join("\n")}\n`;
396
404
  }
397
405
  function renderCommandHelp(command) {
@@ -803,29 +811,27 @@ export async function runAkRole(argv, env) {
803
811
  };
804
812
  env = { ...env, freshSummons: true };
805
813
  }
806
- // Resume reopens an exact Role run (#416): caller decides; session principal
807
- // must still exist. Seat and dispatch follow the durable admitted role.
808
- // #471: unique parser owns {runId, message?}; five role paths only consume it.
814
+ // Resume reopens one leg of a ticket (#416 / #1201): caller decides; session
815
+ // principal must still exist. The address is ticket + seat (+ round); only
816
+ // legs filed under the ticket are in it.
809
817
  if (parsed.command === "resume") {
810
- let resumeRequest = parseResumeRequest(parsed.args);
818
+ const address = parseResumeAddress(parsed.args);
819
+ const runDirectory = locateTicketLeg(activationBookDirectory(resolveActivationLedgerHome(home), resolveBookKeyFromGit(env.cwd ?? process.cwd())), address);
820
+ const resumeRequest = {
821
+ runId: runIdFromRunDirectory(runDirectory),
822
+ runDirectory,
823
+ ...(address.message === undefined ? {} : { message: address.message }),
824
+ };
811
825
  resumeFailureContext = {
812
826
  home,
813
827
  runId: resumeRequest.runId,
828
+ runDirectory,
814
829
  authority: env.principalAuthority ?? piDurablePrincipalAuthority,
815
830
  };
816
- const runDirectory = await findRunDirectoryById(home, resumeRequest.runId);
817
- if (runDirectory !== undefined) {
818
- resumeRequest = { ...resumeRequest, runDirectory };
819
- resumeFailureContext = { ...resumeFailureContext, runDirectory };
820
- }
821
831
  const parts = await loadPublicRoleDispatchParts(env, home);
822
- const resumeRole = await peekRoleRunRole(home, resumeRequest.runId, resumeRequest);
823
- // Missing durable role keeps the judge seat table. The resume entry
824
- // itself is one function; it reads the stored run.
825
- const seatRole = resumeRole ?? "judge";
826
- const seat = resolveEffectiveSeat(parts.config, seatRole, parts.credentials, invocationFromParsed(parsed));
832
+ const seat = resolveEffectiveSeat(parts.config, address.seat, parts.credentials, invocationFromParsed(parsed));
827
833
  const resumeEnv = createRoleEnvironment(env, {
828
- role: seatRole,
834
+ role: address.seat,
829
835
  home,
830
836
  agentDir: parts.agentDir,
831
837
  cwd: parts.cwd,
@@ -1451,8 +1451,7 @@ async function auditSubmittedRole(turn, env, io, resumedOfficer, passedReceipt)
1451
1451
  const pass = chain.passes.at(-1);
1452
1452
  const officerTerminal = pass?.terminal;
1453
1453
  const officerRunDirectory = pass?.runDirectory;
1454
- const officerRunId = pass?.runId
1455
- ?? (officerRunDirectory === undefined ? undefined : runIdFromRunDirectory(officerRunDirectory));
1454
+ const officerRunId = pass?.runId;
1456
1455
  if (officerTerminal !== undefined && officerRunId !== undefined) {
1457
1456
  // #1214 F1: present audited original and officer scene separately.
1458
1457
  await presentAuditedOriginalVolume(turn, io);
@@ -1483,9 +1482,7 @@ async function auditSubmittedRole(turn, env, io, resumedOfficer, passedReceipt)
1483
1482
  if (chain.status === "escalate") {
1484
1483
  const escalation = chain.passes.at(-1);
1485
1484
  const escalatedRunDirectory = escalation?.runDirectory;
1486
- const escalatedRunId = escalation?.runId
1487
- ?? (escalatedRunDirectory === undefined
1488
- ? undefined : runIdFromRunDirectory(escalatedRunDirectory));
1485
+ const escalatedRunId = escalation?.runId;
1489
1486
  if (escalatedRunId === undefined) {
1490
1487
  return incompleteAuditWithoutOfficerVolume(turn, admitted, io, "escalated audit has no resumable run identity");
1491
1488
  }