@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/public-cli/invocation.ts

@@ -27,9 +27,9 @@ import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
 import {
   ensureRoleRunDirectory,
   ensureRoleRunPlacement,
+  formatRunLeaf,
   isUnboundRunDirectory,
   listBookRunDirectories,
-  roleRunArtifactsDirectory,
   roleRunPlacement,
   type RoleRunSubject,
 } from "../role-run-placement.ts";
@@ -51,6 +51,7 @@ import {
 } from "../packaged-role-registry.ts";
 import {
   isSafePositiveTicketNumber,
+  parseTicketNumber,
   readBoardTicketNumber,
   requireSafePositiveTicketNumber,
 } from "../run-ticket-number.ts";
@@ -58,6 +59,7 @@ import {
   rewriteRunDirectoryPathFields,
   rewriteRunDirectoryPathValue,
 } from "../role-run-relocation.ts";
+import { readPageSync, renderCurrentSync, updateSectionSync, writeSectionSync } from "../run-dossier.ts";
 import {
   loadDoctorCase,
 } from "../doctor-evidence.ts";
@@ -135,7 +137,6 @@ export type AdmittedRoleInvocationBase = {
   readonly runDirectory: string;
   /** Host-issued opaque durable principal (coordinates only via authority.decode). */
   readonly principal: DurablePrincipal;
-  readonly admittedRequestPath: string;
   /**
    * Optional opaque invocation correlation restored from a prior admitted page
    * (ADR 0049 host channel). Admission does not mint ticket-binding ids.
@@ -316,7 +317,6 @@ export type AdmissionPlacement = {
   readonly sessionDirectory: string;
   readonly sessionFile: string;
   readonly runDirectory: string;
-  readonly artifactsDirectory: string;
   readonly attachmentsDirectory: string;
   readonly ledgerHome: string;
   readonly bookKey: string;
@@ -354,25 +354,20 @@ export function issueAdmissionPlacement(
 }
 
 /**
- * Unique admitted-request.json persistence projection: top-level sessionDirectory/sessionFile
+ * Unique `admitted` section projection of current.json: top-level sessionDirectory/sessionFile
  * (base wire shape). Memory Admitted keeps only the opaque principal — never dual-carry.
  */
-async function writeAdmittedRequestPersistence(
-  admittedRequestPath: string,
+function writeAdmittedRequestPersistence(
+  runDirectory: string,
   body: Record<string, unknown>,
   coordinates: { readonly sessionDirectory: string; readonly sessionFile: string },
-): Promise<void> {
+): void {
   const { principal: _omitPrincipal, ...rest } = body;
-  const projection = {
+  writeSectionSync(runDirectory, "admitted", {
     ...rest,
     sessionDirectory: coordinates.sessionDirectory,
     sessionFile: coordinates.sessionFile,
-  };
-  await writeFile(
-    admittedRequestPath,
-    `${JSON.stringify(projection, null, 2)}\n`,
-    "utf8",
-  );
+  });
 }
 
 /**
@@ -401,7 +396,7 @@ function effectiveModelLedgerFields(
 export { homeFromRunDirectory };
 
 /**
- * Persist one `invocation.json` identity page for the public run.
+ * Persist the `invocation` identity section of current.json for the public run.
  * Admission is the sole source for every field; this is the only identity
  * projection and callers never provide an independent ledger shape.
  * When an effective model is known at admission, provider/model (and thinking
@@ -424,11 +419,7 @@ async function writeRoleInvocationLedger(
     ...(source.ticketNumber === undefined ? {} : { ticketNumber: source.ticketNumber }),
     ...effectiveModelLedgerFields(effectiveModel),
   };
-  await writeFile(
-    join(source.runDirectory, "invocation.json"),
-    `${JSON.stringify(identity, null, 2)}\n`,
-    "utf8",
-  );
+  writeSectionSync(source.runDirectory, "invocation", identity);
 }
 
 /**
@@ -448,7 +439,7 @@ export async function recordEffectiveInvocationModel(
   host?: string,
   engineModel?: string | null,
 ): Promise<void> {
-  await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => {
+  updateSectionSync(runDirectory, "invocation", (current) => {
     const next: Record<string, unknown> = { ...current };
     if (model !== undefined) {
       next.provider = model.provider;
@@ -476,33 +467,19 @@ export async function recordEffectiveInvocationModel(
   });
 }
 
-/**
- * Read one durable JSON object, let the caller keep its field rules, and write
- * the page back. `undefined` means the caller decided not to change the page.
- */
-async function updateDurableJsonPage(
-  path: string,
-  update: (current: Record<string, unknown>) => Record<string, unknown> | undefined,
-): Promise<void> {
-  const current = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
-  const next = update(current);
-  if (next === undefined) return;
-  await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
-}
-
-/** Merge observed launch-time fields into the single existing invocation.json identity page. */
+/** Merge observed launch-time fields into the single existing invocation section of current.json. */
 async function mergeInvocationIdentityPage(
   runDirectory: string,
   fields: Record<string, unknown>,
 ): Promise<void> {
-  await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => ({
+  updateSectionSync(runDirectory, "invocation", (current) => ({
     ...current,
     ...fields,
   }));
 }
 
 /**
- * Persist parent --source-run path onto admitted-request for officer resume lookup (#747).
+ * Persist parent --source-run path onto the admitted section for officer resume lookup (#747).
  * Reuses the existing notary sourceRunPath key; does not invent a new field name.
  */
 export async function persistAdmittedSourceRunPath(
@@ -513,7 +490,7 @@ export async function persistAdmittedSourceRunPath(
   if (sourceRunPath.trim() === "") {
     throw new Error("persistAdmittedSourceRunPath requires a non-empty sourceRunPath");
   }
-  await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+  updateSectionSync(admitted.runDirectory, "admitted", (current) => {
     if (typeof current.sourceRunPath === "string" && current.sourceRunPath !== sourceRunPath) {
       throw new Error(
         `persistAdmittedSourceRunPath refuses to replace ${current.sourceRunPath} with ${sourceRunPath}`,
@@ -531,7 +508,7 @@ export async function persistAdmittedSourceRunPath(
 
 /**
  * Bind a post-admission resolved ticketNumber onto the in-memory admitted
- * object and both durable pages (invocation.json + admitted-request.json).
+ * object and both durable sections (invocation + admitted).
  * A later typed role receipt replaces an earlier assertion (#1025).
  */
 export async function bindAdmittedTicketNumber(
@@ -549,7 +526,7 @@ export async function recordAdmittedCorrelation(
   correlationId: string,
 ): Promise<void> {
   let correlationIds: string[] = [];
-  await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+  updateSectionSync(admitted.runDirectory, "admitted", (current) => {
     const prior = [
       ...(Array.isArray(current.correlationIds)
         ? current.correlationIds.filter((value): value is string =>
@@ -596,11 +573,10 @@ export async function relocateAdmittedRunToTicket(
   const principal = authority.seal(target);
 
   if (admitted.role !== "diarist") {
-    const parentPage = JSON.parse(await readFile(admitted.admittedRequestPath, "utf8")) as Record<string, unknown>;
-    const childRunIds = parentPage.childDiaristRunIds;
+    const childRunIds = readPageSync(oldRunDirectory, "admitted")?.childDiaristRunIds;
     for (const childRunId of Array.isArray(childRunIds) ? childRunIds : []) {
       if (typeof childRunId !== "string") continue;
-      const childDirectory = join(dirname(oldRunDirectory), `${childRunId}@diarist`);
+      const childDirectory = join(dirname(oldRunDirectory), formatRunLeaf(childRunId, "diarist"));
       // A child that already filed under a ticket keeps its own assertion.
       if (!existsSync(childDirectory)) continue;
       const childTarget = roleRunPlacement(ledgerHome, {
@@ -614,6 +590,16 @@ export async function relocateAdmittedRunToTicket(
       await rehomeUnboundTicketProvenance(childDirectory, admitted.ticketNumber, admitted.projectRoot, homeFromRunDirectory(oldRunDirectory));
       ensureRoleRunDirectory(ledgerHome, dirname(childTarget.runDirectory));
       await rename(childDirectory, childTarget.runDirectory);
+      // Finished child legs will not settle again; refresh derived host.original
+      // after the rename commit. A derived render fault must not undo or block
+      // the committed placement (#1161 L1) — note and keep the true cause.
+      try {
+        renderCurrentSync(childTarget.runDirectory);
+      } catch (error) {
+        process.stderr.write(
+          `[invocation] current.json render refused after child relocate; placement kept: ${childTarget.runDirectory}: ${errorText(error)}\n`,
+        );
+      }
     }
   }
 
@@ -627,8 +613,9 @@ export async function relocateAdmittedRunToTicket(
   // Persisted paths are resolved from typed run identity on read.
   await rename(oldRunDirectory, target.runDirectory);
 
-  // rename moved the open lock inode with the directory. Transfer cleanup
-  // ownership immediately after the commit.
+  // rename moved the open lock inode with the directory. Transfer cleanup and
+  // admitted path ownership immediately after the commit — before any derived
+  // render that may refuse (#1161 L1 / BASE order).
   heldLease?.relocate(target.runDirectory);
 
   const admittedRecord = admitted as unknown as Record<string, unknown>;
@@ -636,7 +623,6 @@ export async function relocateAdmittedRunToTicket(
     admittedRecord,
     [
       "runDirectory",
-      "admittedRequestPath",
       "taskPath",
       "packetPath",
       "prerequisitesPath",
@@ -655,6 +641,11 @@ export async function relocateAdmittedRunToTicket(
   }
   (admitted as { principal: DurablePrincipal }).principal = principal;
 
+  // current.json projects host.original from this run directory. Ownership is
+  // already transferred; a refuse still carries the true cause to the caller
+  // (#1161 L1) without leaving the leg under the unbound path.
+  renderCurrentSync(target.runDirectory);
+
   return { oldRunDirectory, newRunDirectory: target.runDirectory };
 }
 
@@ -663,7 +654,7 @@ export async function recordChildDiaristRun(
   parent: AdmittedRoleInvocation,
   childRunId: string,
 ): Promise<void> {
-  await updateDurableJsonPage(parent.admittedRequestPath, (page) => {
+  updateSectionSync(parent.runDirectory, "admitted", (page) => {
     const existing = Array.isArray(page.childDiaristRunIds)
       ? page.childDiaristRunIds.filter((runId): runId is string => typeof runId === "string")
       : [];
@@ -685,9 +676,8 @@ export async function bindTicketNumberOnRunDirectory(
     ticketNumber,
     "bindTicketNumberOnRunDirectory",
   );
-  const admittedPath = join(runDirectory, "admitted-request.json");
   let unchanged = false;
-  await updateDurableJsonPage(admittedPath, (admitted) => {
+  updateSectionSync(runDirectory, "admitted", (admitted) => {
     if (admitted.ticketNumber === ticketNumber) {
       unchanged = true;
       return undefined;
@@ -710,7 +700,7 @@ export async function recordLaunchedPiIdentity(
 }
 
 /**
- * Observed role-package launch provenance written onto the same invocation.json page.
+ * Observed role-package launch provenance written onto the same state.jsonl invocation row.
  * Values are field observations from the public CLI activation seam — never fixed schema markers.
  */
 export type LaunchedRolePackageIdentity = {
@@ -759,20 +749,22 @@ export async function recordLaunchedRolePackageIdentity(
   });
 }
 
+/** Trim, then the shared ticket spelling. Callers keep their own diagnostic text. */
+function rejectUnlessTicketNumber(raw: string, message: string): number {
+  const parsed = parseTicketNumber(raw.trim());
+  if (parsed === undefined) throw new CliUsageError(message);
+  return parsed;
+}
+
 /** Positive ticket number for analyst query-scope face (and shared integer parse). */
 export function parsePositiveTicketNumber(
   raw: string,
   flag: string,
 ): number {
-  const trimmed = raw.trim();
-  if (!ANALYST_TICKET_NUMBER_PATTERN.test(trimmed)) {
-    throw new CliUsageError(`${flag} must be a positive integer, got ${raw}`);
-  }
-  const value = Number(trimmed);
-  if (!Number.isSafeInteger(value) || value < 1) {
-    throw new CliUsageError(`${flag} must be a positive integer, got ${raw}`);
-  }
-  return value;
+  return rejectUnlessTicketNumber(
+    raw,
+    `${flag} must be a positive integer, got ${raw}`,
+  );
 }
 
 /**
@@ -1299,10 +1291,16 @@ async function freezeRegularFileAttachment(
 
 /** Freeze attachments only — ticket binding is the shared LLM seat path (#635). */
 async function freezeAttachments(
+  ledgerHome: string,
   attachmentPaths: readonly string[],
   attachmentsDirectory: string,
 ): Promise<readonly FrozenAttachment[]> {
   const attachments: FrozenAttachment[] = [];
+  // attachments/ appears only when something is frozen; created through the
+  // ledger's symlink-rejecting tree walk, never a plain mkdir.
+  if (attachmentPaths.length > 0) {
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+  }
   for (let i = 0; i < attachmentPaths.length; i += 1) {
     const frozen = await freezeRegularFileAttachment(
       attachmentPaths[i]!,
@@ -1328,7 +1326,7 @@ export async function freezeAttachmentsIntoRun(
   const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(runDirectory));
   const attachmentsDirectory = join(runDirectory, "attachments", summonsKey);
   ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
-  return freezeAttachments(attachmentPaths, attachmentsDirectory);
+  return freezeAttachments(ledgerHome, attachmentPaths, attachmentsDirectory);
 }
 
 /** Freeze prepared bytes and metadata through one path for birth or retained runs. */
@@ -1650,7 +1648,10 @@ export async function admitPublicRole(
           }
           let caseIdentity: DoctorCaseIdentity;
           try {
-            const patient = await loadDoctorCase(caseRunsPath);
+            const patient = await loadDoctorCase(
+              caseRunsPath,
+              parsed.runs === undefined ? undefined : placed.projectRoot,
+            );
             if (patient.identity.issueNumber !== issueNumber) {
               throw new CliUsageError(
                 `doctor case issue ${patient.identity.issueNumber} does not match --issue ${issueNumber}`,
@@ -1666,7 +1667,7 @@ export async function admitPublicRole(
               { cause: error },
             );
           }
-          frozenAttachments = await freezeAttachments(attachmentPaths, placed.attachmentsDirectory);
+          frozenAttachments = await freezeAttachments(placed.ledgerHome, attachmentPaths, placed.attachmentsDirectory);
           return {
             issueNumber,
             caseRunsPath,
@@ -1825,7 +1826,7 @@ export type AdmitJudgeInvocationOptions = {
   /** Injectable clock/id for tests. */
   createRunId?: () => string;
   principalAuthority: DurablePrincipalAuthority;
-  /** Effective model for this invocation — written onto invocation.json. */
+  /** Effective model for this invocation — written onto the state.jsonl invocation row. */
   model?: InvocationEffectiveModel;
   /** Typed ticket already on this summons (起居录 / parent board). Never parsed from prose. */
   assertedTicketNumber?: number;
@@ -1897,7 +1898,7 @@ async function placeRoleAdmission(options: {
   });
   const attachments = options.freezeAttachments === false
     ? []
-    : await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    : await freezeAttachments(ledgerHome, options.attachmentPaths, attachmentsDirectory);
   return {
     runId,
     bookKey,
@@ -1947,9 +1948,8 @@ async function persistPlacedAdmission(
   },
   placed: PlacedRoleAdmission,
   model: InvocationEffectiveModel | undefined,
-): Promise<string> {
-  const admittedRequestPath = join(placed.runDirectory, "admitted-request.json");
-  await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+): Promise<void> {
+  writeAdmittedRequestPersistence(placed.runDirectory, admitted, {
     sessionDirectory: placed.sessionDirectory,
     sessionFile: placed.sessionFile,
   });
@@ -1962,12 +1962,11 @@ async function persistPlacedAdmission(
     admitted.role,
     model,
   );
-  return admittedRequestPath;
 }
 
 /**
  * Shared admission: project check, placement, attachment freeze,
- * admitted-request and invocation ledger write.
+ * admitted and invocation section write.
  * Countersign passes deferPersistence so same-ticket lookup can reserve coordinates
  * before materializeCountersignInvocation writes the page.
  * Seats whose extra facts are known before placement pass them as admittedFields.
@@ -1981,7 +1980,7 @@ async function admitStandardMaterialInvocation<
 >(
   role: R,
   options: AdmitInspectorInvocationOptions & {
-    /** Reserve coordinates; skip freeze, placement disk, and admitted-request write. */
+    /** Reserve coordinates; skip freeze, placement disk, and admitted section write. */
     readonly deferPersistence?: boolean;
     /** Skip attachment freeze. Gleaner-left admits no caller attachments. */
     readonly freezeAttachments?: boolean;
@@ -2032,9 +2031,7 @@ async function admitStandardMaterialInvocation<
     attachments: persistedAttachmentRefs(placed.attachments),
     ...placed.ticketFields,
   };
-  const admittedRequestPath = defer
-    ? join(placed.runDirectory, "admitted-request.json")
-    : await persistPlacedAdmission(admitted, placed, options.model);
+  if (!defer) await persistPlacedAdmission(admitted, placed, options.model);
   return {
     role,
     runId: placed.runId,
@@ -2045,7 +2042,6 @@ async function admitStandardMaterialInvocation<
     attachments: placed.attachments,
     runDirectory: placed.runDirectory,
     principal: placed.principal,
-    admittedRequestPath,
     ...correlationFields,
     ...placed.ticketFields,
     ...admittedFields,
@@ -2138,7 +2134,7 @@ export type AdmitCountersignInvocationOptions = {
   /** Injectable clock/id for tests. */
   createRunId?: () => string;
   principalAuthority: DurablePrincipalAuthority;
-  /** Effective model for this invocation — written onto invocation.json. */
+  /** Effective model for this invocation — written onto the state.jsonl invocation row. */
   model?: InvocationEffectiveModel;
   correlationId?: string;
   /** Same-ticket lookup may select an existing run before a new run is persisted. */
@@ -2168,10 +2164,6 @@ export async function materializeCountersignInvocation(
   });
   const placement = placed;
   (admitted as { runDirectory: string }).runDirectory = placement.runDirectory;
-  (admitted as { admittedRequestPath: string }).admittedRequestPath = join(
-    placement.runDirectory,
-    "admitted-request.json",
-  );
   (admitted as { principal: DurablePrincipal }).principal = placement.principal;
   const ticketFields = ticketAdmissionFields(options.ticketNumber);
   if (ticketFields.ticketNumber !== undefined) {
@@ -2182,7 +2174,7 @@ export async function materializeCountersignInvocation(
     admitted.runDirectory,
   );
   (admitted as { attachments: readonly FrozenAttachment[] }).attachments = attachments;
-  await writeAdmittedRequestPersistence(admitted.admittedRequestPath, admitted, {
+  writeAdmittedRequestPersistence(admitted.runDirectory, admitted, {
     sessionDirectory: placement.sessionDirectory,
     sessionFile: placement.sessionFile,
   });
@@ -2193,7 +2185,7 @@ export async function materializeCountersignInvocation(
   );
 }
 
-/** Load admitted-request.json written at admission (Navigator work-context seam). */
+/** Load the admitted section written at admission (Navigator work-context seam). */
 export async function loadAdmittedJudgeRequest(
   runDirectory: string,
 ): Promise<{
@@ -2202,11 +2194,8 @@ export async function loadAdmittedJudgeRequest(
   attachments: readonly FrozenAttachment[];
 } | undefined> {
   try {
-    const raw = JSON.parse(
-      await readFile(join(runDirectory, "admitted-request.json"), "utf8"),
-    ) as unknown;
-    if (!isRecord(raw)) return undefined;
-    const record = raw;
+    const record = readPageSync(runDirectory, "admitted");
+    if (record === undefined) return undefined;
     if (!packagedPublicInstructionSubject(record.role)) return undefined;
     if (typeof record.instruction !== "string") return undefined;
     if (typeof record.instructionEmpty !== "boolean") return undefined;
@@ -2221,14 +2210,6 @@ export async function loadAdmittedJudgeRequest(
   }
 }
 
-export async function ensureRunArtifactsDir(runDirectory: string): Promise<string> {
-  const directory = roleRunArtifactsDirectory(runDirectory);
-  return ensureRoleRunDirectory(
-    resolveActivationLedgerHome(homeFromRunDirectory(runDirectory)),
-    directory,
-  );
-}
-
 export type AdmitFixerInvocationOptions = {
   home: string;
   principalAuthority: DurablePrincipalAuthority;
@@ -2240,7 +2221,7 @@ export type AdmitFixerInvocationOptions = {
   prerequisitesPath?: string;
   project?: string;
   createRunId?: () => string;
-  /** Effective model for this invocation — written onto invocation.json. */
+  /** Effective model for this invocation — written onto the state.jsonl invocation row. */
   model?: InvocationEffectiveModel;
   /** Typed ticket already on this summons. Placement uses it; code does not infer one. */
   assertedTicketNumber?: number;
@@ -2311,32 +2292,21 @@ function isGitRemoteMissing(error: unknown): boolean {
   return status === 2;
 }
 
-/** Positive Issue number grammar shared with Doctor case path identity. */
-const DOCTOR_ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/;
-
-/** Match retained Doctor case runs roots (ADR 0017 / loadDoctorCase). */
-/** Canonical Doctor case: `<book>/<ticket>/runs`. Legacy `issues/<n>/runs` is read-only compat. */
-const DOCTOR_CASE_RUNS_PATH_PATTERN =
-  /\/\.ak-roles\/books\/[^/]+\/(?:issues\/)?([1-9]\d*)\/runs$/;
-
 /**
  * Parse a positive Issue number for public Doctor admission.
  * Leading zeros and non-integers are structural rejects.
  */
 export function parseDoctorIssueNumber(raw: string): number {
-  const trimmed = raw.trim();
-  if (!DOCTOR_ISSUE_NUMBER_PATTERN.test(trimmed)) {
-    throw new CliUsageError(
-      `doctor --issue must be a positive integer, got ${raw}`,
-    );
-  }
-  return Number(trimmed);
+  return rejectUnlessTicketNumber(
+    raw,
+    `doctor --issue must be a positive integer, got ${raw}`,
+  );
 }
 
 /**
  * Resolve the retained Doctor case runs root from Issue identity.
- * Default is the #78 book locator; optional --runs must stay project-confined
- * and match Doctor case grammar for the same issue number.
+ * Default is the #78 book locator; optional --runs must stay project-confined.
+ * loadDoctorCase owns retained-root grammar at IO; admission matches its case identity.
  */
 export async function resolveDoctorCaseRunsPath(options: {
   home: string;
@@ -2388,18 +2358,6 @@ export async function resolveDoctorCaseRunsPath(options: {
     );
   }
 
-  const normalized = real.split(sep).join("/");
-  const match = normalized.match(DOCTOR_CASE_RUNS_PATH_PATTERN);
-  if (!match) {
-    throw new CliUsageError(
-      "doctor --runs must be an .ak-roles/books/<book>/<n>/runs directory",
-    );
-  }
-  if (Number(match[1]) !== options.issueNumber) {
-    throw new CliUsageError(
-      `doctor --runs issue ${match[1]} does not match --issue ${options.issueNumber}`,
-    );
-  }
   return real;
 }
 
@@ -2418,7 +2376,7 @@ export type AdmitReviewerInvocationOptions = {
   project?: string;
   createRunId?: () => string;
   correlationId?: string;
-  /** Effective model for this invocation — written onto invocation.json. */
+  /** Effective model for this invocation — written onto the state.jsonl invocation row. */
   model?: InvocationEffectiveModel;
   /** Typed ticket already on this summons. Placement uses it; code does not infer one. */
   assertedTicketNumber?: number;
@@ -2471,14 +2429,12 @@ export type AdmitMergerInvocationOptions = {
   attachmentPaths: readonly string[];
   project?: string;
   createRunId?: () => string;
-  /** Effective model for this invocation — written onto invocation.json. */
+  /** Effective model for this invocation — written onto the state.jsonl invocation row. */
   model?: InvocationEffectiveModel;
   /** Typed ticket already on this summons. Placement uses it; code does not infer one. */
   assertedTicketNumber?: number;
 };
 
-const ANALYST_TICKET_NUMBER_PATTERN = /^[1-9]\d*$/;
-
 /**
  * Parse a positive ticket / issue number for public analyst admission.
  * Leading zeros and non-integers are structural rejects (same face as #176).
@@ -2488,20 +2444,10 @@ export function parseAnalystTicketNumber(
   raw: string,
   flag: string = "--ticket",
 ): number {
-  const trimmed = raw.trim();
-  if (!ANALYST_TICKET_NUMBER_PATTERN.test(trimmed)) {
-    throw new CliUsageError(
-      `analyst ${flag} must be a positive integer, got ${raw}`,
-    );
-  }
-  const value = Number(trimmed);
-  // Digit-only strings beyond MAX_SAFE_INTEGER round or become Infinity — reject.
-  if (!Number.isSafeInteger(value) || value < 1) {
-    throw new CliUsageError(
-      `analyst ${flag} must be a positive integer, got ${raw}`,
-    );
-  }
-  return value;
+  return rejectUnlessTicketNumber(
+    raw,
+    `analyst ${flag} must be a positive integer, got ${raw}`,
+  );
 }
 
 /**
@@ -2535,7 +2481,7 @@ export function parseAnalystCohortIssueToken(
   const sep = trimmed.lastIndexOf(":");
   if (sep > 0) {
     const rhs = trimmed.slice(sep + 1);
-    if (ANALYST_TICKET_NUMBER_PATTERN.test(rhs)) {
+    if (parseTicketNumber(rhs) !== undefined) {
       const bookKey = trimmed.slice(0, sep);
       if (bookKey.trim() === "") {
         throw new CliUsageError(