@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/public-cli/invocation.js

@@ -0,0 +1,2225 @@
+/**
+ * Public Invocation request admission: optional opaque instruction, frozen
+ * Attachments, project default/override (ADR 0052 / #106).
+ */
+import { execFileSync } from "node:child_process";
+import { lstat, mkdir, readFile, realpath, writeFile, } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
+import { activationBookDirectory, ensureRealDirectoryTree, homeFromRunDirectory, pathContainedIn, resolveActivationLedgerHome, } from "../activation-ledger-topology.js";
+import { resolveBookKeyFromGit } from "../activation-ledger-git.js";
+import { readRunTicketNumber } from "../run-ticket-number.js";
+import { loadDoctorCase, } from "../doctor-evidence.js";
+import { COLLECTOR_FIXED_KICKOFF, emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
+import { FixerPacketValidationError, parseFixerPrerequisites, } from "../package-contracts/fixer-packet.js";
+import { createProductionMergerGitState } from "../merger-git-state.js";
+import { validateMergerInput, } from "../merger-contracts.js";
+import { sha256Hex } from "../sha256.js";
+import { uuidv7 } from "../uuidv7.js";
+import { NOTARY_FIXED_KICKOFF, } from "../notary-contracts.js";
+import { NotarySourceRunError, resolveNotarySourceRunLocator, } from "../notary-source-run.js";
+import { appendEngineSessionMaterial, } from "../package-resources/engine-material.js";
+import { CliUsageError } from "./cli-errors.js";
+import { REJECTED_PUBLIC_SPELLINGS, createTypedOptionConsumer, evaluateAnalystModeOptionContract, optionsForOwner, resolveAnalystMode, } from "./option-definitions.js";
+/** Issue principal + derive ledger placement through the injected authority only. */
+export function issueAdmissionPlacement(authority, request) {
+    const principal = authority.issue(request);
+    const { sessionDirectory, sessionFile } = authority.decode(principal);
+    const runDirectory = join(sessionDirectory, "..");
+    const ledgerHome = resolveActivationLedgerHome(request.home);
+    const bookKey = resolveBookKeyFromGit(request.cwd);
+    return {
+        principal,
+        sessionDirectory,
+        sessionFile,
+        runDirectory,
+        ledgerHome,
+        bookKey,
+    };
+}
+/**
+ * Unique admitted-request.json persistence projection: top-level sessionDirectory/sessionFile
+ * (base wire shape). Memory Admitted keeps only the opaque principal — never dual-carry.
+ */
+async function writeAdmittedRequestPersistence(admittedRequestPath, body, coordinates) {
+    const { principal: _omitPrincipal, ...rest } = body;
+    const projection = {
+        ...rest,
+        sessionDirectory: coordinates.sessionDirectory,
+        sessionFile: coordinates.sessionFile,
+    };
+    await writeFile(admittedRequestPath, `${JSON.stringify(projection, null, 2)}\n`, "utf8");
+}
+/** Project effective model onto ledger fields; absent thinking stays absent. */
+function effectiveModelLedgerFields(model) {
+    if (model === undefined)
+        return {};
+    return {
+        provider: model.provider,
+        model: model.model,
+        ...(model.thinking === undefined ? {} : { thinking: model.thinking }),
+    };
+}
+export { homeFromRunDirectory };
+/**
+ * Persist one `invocation.json` identity page 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
+ * only when supplied) are written onto the same page.
+ */
+async function writeRoleInvocationLedger(source, role, effectiveModel) {
+    const identity = {
+        role,
+        runId: source.runId,
+        bookKey: source.bookKey,
+        projectRoot: source.projectRoot,
+        runDirectory: source.runDirectory,
+        sessionDirectory: source.sessionDirectory,
+        sessionFile: source.sessionFile,
+        ...(source.correlationId === undefined ? {} : { correlationId: source.correlationId }),
+        ...(source.ticketNumber === undefined ? {} : { ticketNumber: source.ticketNumber }),
+        ...effectiveModelLedgerFields(effectiveModel),
+    };
+    await writeFile(join(source.runDirectory, "invocation.json"), `${JSON.stringify(identity, null, 2)}\n`, "utf8");
+}
+/**
+ * Merge the effective launch model / engine / host onto the existing invocation
+ * identity page (resume / temporary override path — same field shape as admission).
+ * Bare model clears any prior thinking key so absence stays honest.
+ *
+ * Engine axis (#617 Scope 1): `string` writes, `null` deletes (authoritative seat
+ * projection when the live table has no engine), `undefined` preserves any existing
+ * key for non-authoritative partial updates.
+ * Host stays write-if-present (`string` only).
+ */
+export async function recordEffectiveInvocationModel(runDirectory, model, engine, host) {
+    const ledgerPath = join(runDirectory, "invocation.json");
+    const current = JSON.parse(await readFile(ledgerPath, "utf8"));
+    const next = { ...current };
+    if (model !== undefined) {
+        next.provider = model.provider;
+        next.model = model.model;
+        if (model.thinking === undefined) {
+            delete next.thinking;
+        }
+        else {
+            next.thinking = model.thinking;
+        }
+    }
+    if (engine === null) {
+        delete next.engine;
+    }
+    else if (engine !== undefined) {
+        next.engine = engine;
+    }
+    if (host !== undefined) {
+        next.host = host;
+    }
+    await writeFile(ledgerPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}
+/** Merge observed launch-time fields into the single existing invocation.json identity page. */
+async function mergeInvocationIdentityPage(runDirectory, fields) {
+    const ledgerPath = join(runDirectory, "invocation.json");
+    const current = JSON.parse(await readFile(ledgerPath, "utf8"));
+    await writeFile(ledgerPath, `${JSON.stringify({
+        ...current,
+        ...fields,
+    }, null, 2)}\n`, "utf8");
+}
+/**
+ * Bind a post-admission resolved ticketNumber onto the in-memory admitted
+ * object and both durable pages (invocation.json + admitted-request.json).
+ * Used by seat LLM ticket binding when admission was unbound
+ * (#635 / #582 diarist-resolves-ticket-llm-layer). Never clears an existing binding.
+ */
+export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
+    if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1) {
+        throw new Error(`bindAdmittedTicketNumber requires a safe positive integer, got ${String(ticketNumber)}`);
+    }
+    if (admitted.ticketResolution === "true-unbound") {
+        throw new Error("bindAdmittedTicketNumber refuses to replace durable true-unbound ticket resolution");
+    }
+    if (admitted.ticketNumber !== undefined) {
+        if (admitted.ticketNumber === ticketNumber)
+            return;
+        throw new Error(`bindAdmittedTicketNumber refuses to replace existing ticket #${admitted.ticketNumber} with #${ticketNumber}`);
+    }
+    admitted.ticketNumber = ticketNumber;
+    await mergeInvocationIdentityPage(admitted.runDirectory, { ticketNumber });
+    const admittedPath = admitted.admittedRequestPath;
+    const current = JSON.parse(await readFile(admittedPath, "utf8"));
+    await writeFile(admittedPath, `${JSON.stringify({ ...current, ticketNumber }, null, 2)}\n`, "utf8");
+}
+/**
+ * Persist seat LLM true-unbound conclusion onto in-memory admitted + both durable
+ * pages so later auto-resume attempts and manual resume never re-enter hermes (#635).
+ */
+export async function recordTrueUnboundTicketResolution(admitted) {
+    if (admitted.ticketNumber !== undefined) {
+        throw new Error(`recordTrueUnboundTicketResolution refuses to overwrite ticket #${admitted.ticketNumber}`);
+    }
+    if (admitted.ticketResolution === "true-unbound")
+        return;
+    admitted.ticketResolution =
+        "true-unbound";
+    await mergeInvocationIdentityPage(admitted.runDirectory, {
+        ticketResolution: "true-unbound",
+    });
+    const admittedPath = admitted.admittedRequestPath;
+    const current = JSON.parse(await readFile(admittedPath, "utf8"));
+    await writeFile(admittedPath, `${JSON.stringify({ ...current, ticketResolution: "true-unbound" }, null, 2)}\n`, "utf8");
+}
+/** Add the identity returned by the production Pi launch seam to its existing ledger page. */
+export async function recordLaunchedPiIdentity(runDirectory, identity) {
+    await mergeInvocationIdentityPage(runDirectory, {
+        piExecutable: identity.executable,
+        piVersion: identity.version,
+    });
+}
+/** Read the package root that is about to serve this public run (observed values only). */
+export async function observeLaunchedRolePackageIdentity(packageRoot, selectedRoleEntry) {
+    const rolePackageRoot = packageRoot;
+    const raw = JSON.parse(await readFile(join(rolePackageRoot, "package.json"), "utf8"));
+    if (typeof raw.version !== "string" || raw.version.trim() === "") {
+        throw new Error(`role package.json at ${rolePackageRoot} does not declare a nonblank version`);
+    }
+    return {
+        roleEntry: selectedRoleEntry,
+        rolePackageRoot,
+        rolePackageVersion: raw.version,
+        entryMode: "public-cli",
+    };
+}
+/** Add the role-package identity resolved at the public launch seam to its existing ledger page. */
+export async function recordLaunchedRolePackageIdentity(runDirectory, identity) {
+    await mergeInvocationIdentityPage(runDirectory, {
+        roleEntry: identity.roleEntry,
+        rolePackageRoot: identity.rolePackageRoot,
+        rolePackageVersion: identity.rolePackageVersion,
+        entryMode: identity.entryMode,
+    });
+}
+/** Positive ticket number for analyst query-scope face (and shared integer parse). */
+export function parsePositiveTicketNumber(raw, flag) {
+    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;
+}
+/** 共享解析体：同形 owner 的 argv → instruction/attachments/project。 */
+function parseInstructionArgv(args, owner) {
+    const attachmentPaths = [];
+    let project;
+    let subject;
+    let sourceRun;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions(owner);
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "attach") {
+                attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "subject") {
+                const raw = typeof taken.value === "string" ? taken.value.trim() : "";
+                if (raw !== "judge" && raw !== "doctor") {
+                    throw new CliUsageError(`auditor --subject must be judge|doctor, got ${taken.value ?? "(missing)"}`);
+                }
+                subject = raw;
+                continue;
+            }
+            if (taken.def.id === "source-run") {
+                const raw = typeof taken.value === "string" ? taken.value.trim() : "";
+                if (raw === "") {
+                    throw new CliUsageError("auditor --source-run requires a run locator");
+                }
+                sourceRun = raw;
+                continue;
+            }
+            throw new CliUsageError(`unknown ${owner} option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown ${owner} option: ${token}`);
+        }
+        positional.push(token);
+    }
+    options.assertRequired();
+    return {
+        instruction: positional.join(" "),
+        attachmentPaths,
+        ...(project === undefined ? {} : { project }),
+        ...(subject === undefined ? {} : { subject }),
+        ...(sourceRun === undefined ? {} : { sourceRun }),
+    };
+}
+/** Honest activation-class failure while deriving the active-merge envelope. */
+export class MergerEnvelopeDerivationError extends Error {
+    code = "merger-envelope-derivation";
+    /** Typed cause for #107 classifyPostAdmissionFailure (isTypedActivationError). */
+    knownCause = "activation";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "MergerEnvelopeDerivationError";
+    }
+}
+/** Reject missing/blank path values so empty overrides cannot silently degrade. */
+function requireOptionPath(flag, value) {
+    if (value === undefined || value.trim() === "") {
+        throw new CliUsageError(flag === "--base"
+            ? `${flag} requires a nonempty revision`
+            : `${flag} requires a path`);
+    }
+    return value;
+}
+/** True when token is a retained rejected spelling for the owner (#342). */
+function isRejectedPublicSpelling(owner, token) {
+    for (const entry of REJECTED_PUBLIC_SPELLINGS) {
+        if (entry.owner !== owner)
+            continue;
+        for (const spelling of entry.spellings) {
+            if (token === spelling || token.startsWith(`${spelling}=`))
+                return true;
+        }
+    }
+    return false;
+}
+/** Role option definitions — sole spelling source for the matching parser. */
+function roleOptions(owner) {
+    return optionsForOwner(owner);
+}
+/**
+ * Public --authority-ref admission grammar (refs-only).
+ * Unique owner for fresh argv and durable resume restore — no string-only parallel.
+ * Accepts durable reference tokens as-is; rejects blank and inline Spec prose
+ * (whitespace-bearing sentences). Does not fetch, normalize, or judge content.
+ */
+export function requireAuthorityRef(value) {
+    if (value === undefined || value.trim() === "") {
+        throw new CliUsageError("--authority-ref requires a nonempty durable reference");
+    }
+    // Spec prose sentences contain whitespace; durable public refs are single tokens.
+    if (/\s/.test(value)) {
+        throw new CliUsageError("--authority-ref requires a durable reference, not inline Spec prose");
+    }
+    return value;
+}
+/**
+ * Parse Judge-specific argv after the `judge` token.
+ * Spellings from PUBLIC_OPTION_TABLE.judge; rejects burden family (#342).
+ */
+export function parseJudgeArgv(args) {
+    // Judge owns burden inference — rejected spellings checked per-token.
+    // `--` ends flag parsing: everything after is opaque instruction.
+    const dd = args.indexOf("--");
+    const preDd = dd === -1 ? args : args.slice(0, dd);
+    for (const token of preDd) {
+        if (isRejectedPublicSpelling("judge", token)) {
+            throw new CliUsageError("judge does not accept a public burden selector; Judge infers its own burden");
+        }
+    }
+    return parseInstructionArgv(args, "judge");
+}
+export function parseCountersignArgv(args) {
+    return parseInstructionArgv(args, "countersign");
+}
+export function parseInspectorArgv(args) {
+    return parseInstructionArgv(args, "inspector");
+}
+export function parseGatekeeperArgv(args) {
+    return parseInstructionArgv(args, "gatekeeper");
+}
+export function parseNavigatorArgv(args) {
+    return parseInstructionArgv(args, "navigator");
+}
+export function parseAuditorArgv(args) {
+    return parseInstructionArgv(args, "auditor");
+}
+export function parseEvidenceChildArgv(args) {
+    return parseInstructionArgv(args, "evidence-child");
+}
+export function parseDiaristArgv(args) {
+    return parseInstructionArgv(args, "diarist");
+}
+/**
+ * Parse Coder-specific argv after the `coder` token.
+ * Phase defaults to apply; spellings from PUBLIC_OPTION_TABLE.coder (#342).
+ */
+export function parseCoderArgv(args) {
+    const attachmentPaths = [];
+    let project;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("coder");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "attach") {
+                attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            throw new CliUsageError(`unknown coder option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown coder option: ${token}`);
+        }
+        positional.push(token);
+    }
+    // Phase aliases + default come solely from the typed coder phase row (#342).
+    const phase = options.consumeLeadingPhase(positional);
+    options.assertRequired();
+    return {
+        phase,
+        instruction: positional.join(" "),
+        attachmentPaths,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+/**
+ * Parse Fixer-specific argv after the `fixer` token.
+ * Phase defaults to apply; spellings from PUBLIC_OPTION_TABLE.fixer (#342).
+ */
+export function parseFixerArgv(args) {
+    const attachmentPaths = [];
+    let project;
+    let prerequisitesPath;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("fixer");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "attach") {
+                attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "prerequisites") {
+                prerequisitesPath = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            throw new CliUsageError(`unknown fixer option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown fixer option: ${token}`);
+        }
+        positional.push(token);
+    }
+    // Phase aliases + default come solely from the typed fixer phase row (#342).
+    const phase = options.consumeLeadingPhase(positional);
+    options.assertRequired();
+    return {
+        phase,
+        instruction: positional.join(" "),
+        attachmentPaths,
+        ...(prerequisitesPath === undefined ? {} : { prerequisitesPath }),
+        ...(project === undefined ? {} : { project }),
+    };
+}
+async function freezeRegularFileAttachment(sourcePath, destinationDir, index) {
+    const absolute = isAbsolute(sourcePath) ? sourcePath : resolve(sourcePath);
+    let st;
+    try {
+        st = await lstat(absolute);
+    }
+    catch (error) {
+        throw new CliUsageError(`attachment is not a readable regular file: ${sourcePath}`, { cause: error });
+    }
+    if (!st.isFile() || st.isSymbolicLink()) {
+        throw new CliUsageError(`attachment must be a regular file (not a directory or symlink): ${sourcePath}`);
+    }
+    const bytes = await readFile(absolute);
+    const name = `${String(index).padStart(2, "0")}-${basename(absolute)}`;
+    const frozenPath = join(destinationDir, name);
+    await writeFile(frozenPath, bytes);
+    return {
+        attachment: {
+            provenancePath: absolute,
+            frozenPath,
+            byteLength: bytes.byteLength,
+            sha256: sha256Hex(bytes),
+            mediaKind: "regular-file",
+        },
+        body: bytes,
+    };
+}
+/** Freeze attachments only — ticket binding is the shared LLM seat path (#635). */
+async function freezeAttachments(attachmentPaths, attachmentsDirectory) {
+    const attachments = [];
+    for (let i = 0; i < attachmentPaths.length; i += 1) {
+        const frozen = await freezeRegularFileAttachment(attachmentPaths[i], attachmentsDirectory, i);
+        attachments.push(frozen.attachment);
+    }
+    return attachments;
+}
+/**
+ * Freeze summons attachments into an already-retained run (#637 same-ticket resume).
+ * Writes under attachments/summons-<key>/ so prior freeze names stay intact.
+ * Manual resume never calls this — birth attachments keep their original semantics.
+ */
+export async function freezeAttachmentsIntoRun(attachmentPaths, runDirectory, summonsKey = `s-${Date.now().toString(36)}`) {
+    if (attachmentPaths.length === 0)
+        return [];
+    const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(runDirectory));
+    const attachmentsDirectory = join(runDirectory, "attachments", summonsKey);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    return freezeAttachments(attachmentPaths, attachmentsDirectory);
+}
+function ticketAdmissionFields(ticketNumber) {
+    return ticketNumber === undefined ? {} : { ticketNumber };
+}
+/**
+ * Shared instruction-seat admission for Judge and Inspector: project check,
+ * principal/placement issue, attachment freeze, admitted-request and invocation
+ * ledger write. CorrelationId is projected only when supplied (Inspector).
+ * Ticket binding is post-admission via shared seat LLM path (#635).
+ */
+async function admitStandardMaterialInvocation(role, options) {
+    // Empty project override must not reach resolve("") → cwd (silent default).
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role,
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    const correlationFields = options.correlationId === undefined
+        ? {}
+        : { correlationId: options.correlationId };
+    const instruction = options.instruction;
+    const instructionEmpty = instruction.trim() === "";
+    const admitted = {
+        role,
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        ...correlationFields,
+        instruction,
+        instructionEmpty,
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role,
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        ...correlationFields,
+    };
+}
+/**
+ * Atomically admit a Judge Role run: freeze Attachments, persist the request,
+ * and reserve session placement under the #78 ledger book.
+ */
+export async function admitJudgeInvocation(options) {
+    return admitStandardMaterialInvocation("judge", options);
+}
+/**
+ * Admit a direct Inspector (察院) run: freeze attachments, persist the request,
+ * and reserve session placement. Same instruction-seat face as Judge (#568).
+ */
+export async function admitInspectorInvocation(options) {
+    return admitStandardMaterialInvocation("inspector", options);
+}
+/**
+ * Admit a direct Gatekeeper (门下省) run (#639): freeze attachments, persist
+ * the request, reserve session placement — same instruction-seat face.
+ */
+export async function admitGatekeeperInvocation(options) {
+    return admitStandardMaterialInvocation("gatekeeper", options);
+}
+/**
+ * Admit a direct Navigator (游奕使) run (#639): freeze attachments, persist
+ * the request, reserve session placement — same instruction-seat face.
+ */
+export async function admitNavigatorInvocation(options) {
+    return admitStandardMaterialInvocation("navigator", options);
+}
+/** Admit a public 审刑院 run (#675). */
+export async function admitAuditorInvocation(options) {
+    return admitStandardMaterialInvocation("auditor", options);
+}
+/** Admit a public evidence-child run (#675). */
+export async function admitEvidenceChildInvocation(options) {
+    return admitStandardMaterialInvocation("evidence-child", options);
+}
+/**
+ * Admit a direct Diarist (起居郎) run (#708): freeze attachments, persist the
+ * request, reserve session placement — same instruction-seat face.
+ */
+export async function admitDiaristInvocation(options) {
+    return admitStandardMaterialInvocation("diarist", options);
+}
+/** Shared prompt transport for instruction-seat roles (judge/countersign/inspector). */
+export function buildInstructionTransportPrompt(admitted, engineMaterial) {
+    const lines = [admitted.instructionEmpty ? "" : admitted.instruction];
+    if (admitted.attachments.length > 0) {
+        lines.push("");
+        lines.push("已受理附件（冻结快照路径）：");
+        for (const attachment of admitted.attachments) {
+            lines.push(`- ${attachment.frozenPath}`);
+        }
+    }
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+/** Build the Pi prompt transport for an admitted Judge request. */
+export function buildJudgeTransportPrompt(admitted, engineMaterial) {
+    return buildInstructionTransportPrompt(admitted, engineMaterial);
+}
+export function buildInspectorTransportPrompt(admitted, engineMaterial) {
+    return buildInstructionTransportPrompt(admitted, engineMaterial);
+}
+/**
+ * Atomically admit a Countersign Role run: freeze Attachments, persist the
+ * request, write the invocation ledger (#572 / ADR 0074).
+ */
+export async function admitCountersignInvocation(options) {
+    // Same shared freeze/coordinate body as judge but role: "countersign" so
+    // the ledger and session coordinates use the correct role from the start.
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "countersign",
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    // Ticket binding is LLM-only post-admission (#635); admission stays unbound.
+    const instruction = options.instruction;
+    const instructionEmpty = instruction.trim() === "";
+    const admitted = {
+        role: "countersign",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        ...(options.correlationId === undefined ? {} : { correlationId: options.correlationId }),
+        instruction,
+        instructionEmpty,
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "countersign",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        ...(options.correlationId === undefined ? {} : { correlationId: options.correlationId }),
+    };
+}
+/** Build the Pi prompt transport for an admitted Countersign request. */
+export function buildCountersignTransportPrompt(admitted, engineMaterial) {
+    return buildInstructionTransportPrompt(admitted, engineMaterial);
+}
+/** Load admitted-request.json written at admission (Navigator work-context seam). */
+export async function loadAdmittedJudgeRequest(runDirectory) {
+    try {
+        const raw = JSON.parse(await readFile(join(runDirectory, "admitted-request.json"), "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return undefined;
+        const record = raw;
+        if (record.role !== "judge")
+            return undefined;
+        if (typeof record.instruction !== "string")
+            return undefined;
+        if (typeof record.instructionEmpty !== "boolean")
+            return undefined;
+        if (!Array.isArray(record.attachments))
+            return undefined;
+        return {
+            instruction: record.instruction,
+            instructionEmpty: record.instructionEmpty,
+            attachments: record.attachments,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function ensureRunArtifactsDir(runDirectory) {
+    const dir = join(runDirectory, "artifacts");
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Admit a Coder Role run on the common Invocation request.
+ * Nonblank task remains authoritative: blank instruction is a structural reject.
+ * Phase (default apply / explicit plan) is frozen into the admitted request.
+ */
+export async function admitCoderInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    const instruction = options.instruction;
+    if (instruction.trim() === "") {
+        throw new CliUsageError("coder requires a nonblank task instruction");
+    }
+    if (options.phase !== "plan" && options.phase !== "apply") {
+        throw new CliUsageError("coder phase must be plan or apply");
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "coder",
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    const taskPath = join(runDirectory, "task.md");
+    await writeFile(taskPath, instruction, "utf8");
+    const admitted = {
+        role: "coder",
+        phase: options.phase,
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty: false,
+        taskPath,
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "coder",
+        phase: options.phase,
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty: false,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        taskPath,
+    };
+}
+/**
+ * Build the Pi prompt transport for an admitted Coder request.
+ * Task bytes already live at taskPath for --ak-coder-task; the prompt carries
+ * the same instruction plus frozen Attachment paths.
+ */
+export function buildCoderTransportPrompt(admitted, engineMaterial) {
+    const lines = [admitted.instruction];
+    if (admitted.attachments.length > 0) {
+        lines.push("");
+        lines.push("已受理附件（冻结快照路径）：");
+        for (const attachment of admitted.attachments) {
+            lines.push(`- ${attachment.frozenPath}`);
+        }
+    }
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+/**
+ * Admit a Fixer Role run on the common Invocation request plus optional prerequisites.
+ * Nonblank instruction remains authoritative. Phase defaults to apply at parse time.
+ * Prerequisite grammar is structural; unmet/insufficient prerequisites stay Fixer judgments.
+ */
+export async function admitFixerInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    const instruction = options.instruction;
+    if (instruction.trim() === "") {
+        throw new CliUsageError("fixer requires a nonblank repair instruction");
+    }
+    if (options.phase !== "plan" && options.phase !== "apply") {
+        throw new CliUsageError("fixer phase must be plan or apply");
+    }
+    // Validate/read prerequisites before freezing request materials.
+    let prerequisites = Object.freeze([]);
+    let prerequisitesSource;
+    if (options.prerequisitesPath !== undefined) {
+        const absolutePrereq = isAbsolute(options.prerequisitesPath)
+            ? options.prerequisitesPath
+            : resolve(options.prerequisitesPath);
+        try {
+            prerequisitesSource = await readFile(absolutePrereq, "utf8");
+        }
+        catch (error) {
+            throw new CliUsageError(`fixer prerequisites path is unreadable: ${options.prerequisitesPath}`, { cause: error });
+        }
+        try {
+            prerequisites = parseFixerPrerequisites(prerequisitesSource);
+        }
+        catch (error) {
+            if (error instanceof FixerPacketValidationError) {
+                throw new CliUsageError(error.message, { cause: error });
+            }
+            throw error;
+        }
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "fixer",
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    let prerequisitesPath;
+    if (prerequisitesSource !== undefined) {
+        prerequisitesPath = join(runDirectory, "prerequisites.json");
+        await writeFile(prerequisitesPath, `${JSON.stringify(prerequisites, null, 2)}\n`, "utf8");
+    }
+    const packetPath = join(runDirectory, "fix-packet.md");
+    await writeFile(packetPath, instruction, "utf8");
+    const admitted = {
+        role: "fixer",
+        phase: options.phase,
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty: false,
+        packetPath,
+        ...(prerequisitesPath === undefined ? {} : { prerequisitesPath }),
+        prerequisites: prerequisites.map((entry) => ({
+            id: entry.id,
+            requirement: entry.requirement,
+        })),
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "fixer",
+        phase: options.phase,
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty: false,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        packetPath,
+        ...(prerequisitesPath === undefined ? {} : { prerequisitesPath }),
+        prerequisites,
+    };
+}
+/**
+ * Build the Pi prompt transport for an admitted Fixer request.
+ * Instruction bytes live at packetPath; prerequisites at optional path.
+ * Diagnosis method is available via package --skill, not forced into this prompt.
+ */
+export function buildFixerTransportPrompt(admitted, engineMaterial) {
+    const lines = [admitted.instruction];
+    if (admitted.attachments.length > 0) {
+        lines.push("");
+        lines.push("已受理附件（冻结快照路径）：");
+        for (const attachment of admitted.attachments) {
+            lines.push(`- ${attachment.frozenPath}`);
+        }
+    }
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+function parsePositivePrOption(raw) {
+    if (raw === undefined || raw.trim() === "")
+        throw new CliUsageError("--pr requires a positive pull request number");
+    try {
+        return parseCollectorPrNumber(raw);
+    }
+    catch (error) {
+        throw new CliUsageError(error instanceof Error ? error.message : String(error), { cause: error });
+    }
+}
+function parseRepoOption(raw) {
+    if (raw === undefined || raw.trim() === "")
+        throw new CliUsageError("--repo requires owner/repo");
+    return raw;
+}
+export function parseCollectorArgv(args) {
+    // Spellings from PUBLIC_OPTION_TABLE.collector (#342).
+    const attachmentPaths = [];
+    let project;
+    let repo;
+    let prNumber;
+    let requestManifestPath;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("collector");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "attach") {
+                attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "pr") {
+                prNumber = parsePositivePrOption(taken.value);
+                continue;
+            }
+            if (taken.def.id === "repo") {
+                repo = parseRepoOption(taken.value);
+                continue;
+            }
+            if (taken.def.id === "request-manifest") {
+                requestManifestPath = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            throw new CliUsageError(`unknown collector option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown collector option: ${token}`);
+        }
+        positional.push(token);
+    }
+    // Unconditional required (e.g. --pr) from typed table via shared consumer (#342).
+    options.assertRequired();
+    return {
+        prNumber: prNumber,
+        instruction: positional.join(" "),
+        attachmentPaths,
+        ...(project === undefined ? {} : { project }),
+        ...(repo === undefined ? {} : { repo }),
+        ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+    };
+}
+/**
+ * Resolve owner/repo from the project's `origin` remote (github.com only).
+ * Supports https and SSH GitHub URL shapes; never scrapes instruction prose.
+ */
+export function resolveGitHubRemoteRepository(projectRoot) {
+    let remoteUrl;
+    try {
+        remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+    }
+    catch (error) {
+        throw new CliUsageError("collector requires a github.com origin remote or an explicit --repo owner/repo", { cause: error });
+    }
+    if (remoteUrl.length === 0) {
+        throw new CliUsageError("collector requires a github.com origin remote or an explicit --repo owner/repo");
+    }
+    const ownerRepo = ownerRepoFromGitHubRemoteUrl(remoteUrl);
+    if (ownerRepo === undefined) {
+        throw new CliUsageError(`collector origin remote must be a github.com owner/repo URL, got ${remoteUrl}`);
+    }
+    try {
+        return parseCollectorRepository(ownerRepo);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliUsageError(detail, { cause: error });
+    }
+}
+function ownerRepoFromGitHubRemoteUrl(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    // git@github.com:owner/repo.git — exact owner/repo identity only.
+    const scp = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i.exec(trimmed);
+    if (scp) {
+        return `${scp[1]}/${stripGitSuffix(scp[2])}`;
+    }
+    // ssh://git@github.com/owner/repo(.git) — exact owner/repo identity only.
+    const ssh = /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(trimmed);
+    if (ssh) {
+        return `${ssh[1]}/${stripGitSuffix(ssh[2])}`;
+    }
+    // https://github.com/owner/repo(.git) and git://github.com/... — exact two-segment path.
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!/^github\.com$/i.test(parsed.hostname))
+        return undefined;
+    // Non-identity URL material (query/hash/extra path) is not a repository remote.
+    if (parsed.search !== "" || parsed.hash !== "")
+        return undefined;
+    const parts = parsed.pathname.split("/").filter((p) => p.length > 0);
+    if (parts.length !== 2)
+        return undefined;
+    return `${parts[0]}/${stripGitSuffix(parts[1])}`;
+}
+function stripGitSuffix(name) {
+    return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+}
+/**
+ * Admit a Collector Role run: assemble the retained leg manifest from typed
+ * declarations, resolve repository identity, and place the session under #78.
+ * Does not preflight PR/author existence against GitHub.
+ */
+export async function admitCollectorInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    let prNumber;
+    try {
+        prNumber = parseCollectorPrNumber(options.prNumber);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliUsageError(detail, { cause: error });
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    let repository;
+    if (options.repo !== undefined) {
+        try {
+            repository = parseCollectorRepository(options.repo);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new CliUsageError(detail, { cause: error });
+        }
+    }
+    else {
+        repository = resolveGitHubRemoteRepository(projectRoot);
+    }
+    // Validate optional request-manifest before freezing request materials.
+    let manifest = emptyCollectorManifest();
+    let manifestCanonicalJson;
+    if (options.requestManifestPath !== undefined) {
+        try {
+            manifest = await loadCollectorManifest(options.requestManifestPath);
+            manifestCanonicalJson = manifest.canonicalJson;
+        }
+        catch (error) {
+            throw new CliUsageError(error instanceof Error ? error.message : String(error), { cause: error });
+        }
+    }
+    const manifestDigest = manifest.digest;
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "collector",
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths ?? [], attachmentsDirectory);
+    let requestManifestPath;
+    if (manifestCanonicalJson !== undefined) {
+        requestManifestPath = join(runDirectory, "request-manifest.json");
+        await writeFile(requestManifestPath, manifestCanonicalJson, "utf8");
+    }
+    const instruction = options.instruction ?? "";
+    const instructionEmpty = instruction.trim() === "";
+    const admitted = {
+        role: "collector",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty,
+        prNumber,
+        repository: repository.canonical,
+        repositoryDisplay: repository.display,
+        ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+        manifestDigest,
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "collector",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        prNumber,
+        repository,
+        ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
+        manifestDigest,
+    };
+}
+/**
+ * Collector always consumes the fixed packaged kickoff (one-shot observation).
+ * Optional public instruction is retained only in the admitted request.
+ */
+export function buildCollectorTransportPrompt(_admitted, engineMaterial) {
+    // Exact historical fixed kickoff bytes (one-shot observation).
+    return appendEngineSessionMaterial([COLLECTOR_FIXED_KICKOFF], engineMaterial).join("\n");
+}
+/** 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). */
+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) {
+    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);
+}
+/**
+ * Parse Doctor-specific argv after the `doctor` token.
+ * Requires --issue; optional confined --runs override; common --attach/--project.
+ */
+export function parseDoctorArgv(args) {
+    // Spellings from PUBLIC_OPTION_TABLE.doctor (#342).
+    const attachmentPaths = [];
+    let project;
+    let issueRaw;
+    let runs;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("doctor");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "issue") {
+                if (taken.value === undefined || taken.value.trim() === "") {
+                    throw new CliUsageError("doctor --issue requires a positive integer");
+                }
+                issueRaw = taken.value;
+                continue;
+            }
+            if (taken.def.id === "runs") {
+                if (taken.value === undefined || taken.value.trim() === "") {
+                    throw new CliUsageError("doctor --runs requires a path");
+                }
+                runs = taken.value;
+                continue;
+            }
+            if (taken.def.id === "attach") {
+                attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            throw new CliUsageError(`unknown doctor option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown doctor option: ${token}`);
+        }
+        positional.push(token);
+    }
+    // Unconditional required (e.g. --issue) from typed table via shared consumer (#342).
+    options.assertRequired();
+    const issueNumber = parseDoctorIssueNumber(issueRaw);
+    if (runs !== undefined && runs.trim() === "") {
+        throw new CliUsageError("doctor --runs requires a path");
+    }
+    return {
+        issueNumber,
+        instruction: positional.join(" "),
+        attachmentPaths,
+        ...(project === undefined ? {} : { project }),
+        ...(runs === undefined ? {} : { runs }),
+    };
+}
+/**
+ * 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.
+ */
+export async function resolveDoctorCaseRunsPath(options) {
+    const ledgerHome = resolveActivationLedgerHome(options.home);
+    const defaultRuns = join(activationBookDirectory(ledgerHome, options.bookKey), "issues", String(options.issueNumber), "runs");
+    if (options.runs === undefined) {
+        return defaultRuns;
+    }
+    const raw = options.runs.trim();
+    if (raw === "") {
+        throw new CliUsageError("doctor --runs requires a path");
+    }
+    // Project-relative only — absolute overrides would bypass confinement.
+    if (isAbsolute(raw)) {
+        throw new CliUsageError("doctor --runs must be a project-relative path");
+    }
+    const resolved = resolve(options.projectRoot, raw);
+    if (resolved !== options.projectRoot &&
+        !pathContainedIn(options.projectRoot, resolved)) {
+        throw new CliUsageError("doctor --runs escapes the project root");
+    }
+    let real;
+    try {
+        real = await realpath(resolved);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliUsageError(`doctor --runs is not a readable retained runs root: ${detail}`, { cause: error });
+    }
+    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>/issues/<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;
+}
+/**
+ * Admit a Doctor Role run: resolve Issue → retained runs root via #78 (or a
+ * confined override), construct the structurally exact case identity through
+ * loadDoctorCase, and place the Doctor session under the book runs lane.
+ * Does not copy session content into a second store.
+ */
+export async function admitDoctorInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    if (!Number.isInteger(options.issueNumber) ||
+        options.issueNumber < 1 ||
+        !DOCTOR_ISSUE_NUMBER_PATTERN.test(String(options.issueNumber))) {
+        throw new CliUsageError(`doctor --issue must be a positive integer, got ${options.issueNumber}`);
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "doctor",
+        home: options.home,
+    });
+    let caseRunsPath;
+    try {
+        caseRunsPath = await resolveDoctorCaseRunsPath({
+            home: options.home,
+            projectRoot,
+            bookKey,
+            issueNumber: options.issueNumber,
+            ...(options.runs === undefined ? {} : { runs: options.runs }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliUsageError(detail, { cause: error });
+    }
+    // Default #78 locator may not exist yet — ensure the empty runs root so
+    // loadDoctorCase can form an empty case and Doctor's refusal owns insufficiency.
+    if (options.runs === undefined) {
+        ensureRealDirectoryTree(ledgerHome, caseRunsPath);
+    }
+    let caseIdentity;
+    try {
+        const patient = await loadDoctorCase(caseRunsPath);
+        if (patient.identity.issueNumber !== options.issueNumber) {
+            throw new CliUsageError(`doctor case issue ${patient.identity.issueNumber} does not match --issue ${options.issueNumber}`);
+        }
+        caseIdentity = patient.identity;
+        caseRunsPath = await realpath(caseRunsPath);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliUsageError(`doctor case could not be constructed from retained evidence: ${detail}`, { cause: error });
+    }
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths ?? [], attachmentsDirectory);
+    const instruction = options.instruction ?? "";
+    const instructionEmpty = instruction.trim() === "";
+    const admitted = {
+        role: "doctor",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty,
+        issueNumber: options.issueNumber,
+        caseRunsPath,
+        caseIdentity,
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "doctor",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        issueNumber: options.issueNumber,
+        caseRunsPath,
+        caseIdentity,
+    };
+}
+/** Build the Pi prompt transport for an admitted Doctor request. */
+export function buildDoctorTransportPrompt(admitted, engineMaterial) {
+    const lines = [admitted.instructionEmpty ? "" : admitted.instruction];
+    if (admitted.attachments.length > 0) {
+        lines.push("");
+        lines.push("已受理附件（冻结快照路径）：");
+        for (const attachment of admitted.attachments) {
+            lines.push(`- ${attachment.frozenPath}`);
+        }
+    }
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+/**
+ * Parse Notary-specific argv after the `notary` token.
+ * Input contract = zero prompt, zero attachment projection (#448 / #276).
+ */
+export function parseNotaryArgv(args) {
+    let project;
+    let sourceRun;
+    const tokens = [...args];
+    const definitions = roleOptions("notary");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            if (tokens.length > 0) {
+                throw new CliUsageError("notary rejects caller prompt/instruction; only --source-run locator is admitted");
+            }
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "source-run") {
+                if (taken.value === undefined || taken.value.trim() === "") {
+                    throw new CliUsageError("notary --source-run requires a run locator");
+                }
+                sourceRun = taken.value;
+                continue;
+            }
+            throw new CliUsageError(`unknown notary option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown notary option: ${token}`);
+        }
+        throw new CliUsageError("notary rejects caller prompt/instruction; only --source-run locator is admitted");
+    }
+    options.assertRequired();
+    if (sourceRun === undefined || sourceRun.trim() === "") {
+        throw new CliUsageError("notary --source-run requires a run locator");
+    }
+    return {
+        sourceRun,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+export async function admitNotaryInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    let sourceRun;
+    try {
+        sourceRun = await resolveNotarySourceRunLocator({
+            projectRoot,
+            sourceRun: options.sourceRun,
+            home: options.home,
+        });
+    }
+    catch (error) {
+        if (error instanceof NotarySourceRunError) {
+            throw new CliUsageError(error.message, { cause: error });
+        }
+        throw error;
+    }
+    const runId = options.createRunId?.() ?? uuidv7();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "notary",
+        home: options.home,
+    });
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    const ticketFields = ticketAdmissionFields(await readRunTicketNumber(sourceRun.runDirectory));
+    const admitted = {
+        role: "notary",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction: "",
+        instructionEmpty: true,
+        attachments: [],
+        sourceRunPath: sourceRun.runDirectory,
+        sourceRun,
+        ...ticketFields,
+        ...(options.correlationId === undefined
+            ? {}
+            : { correlationId: options.correlationId }),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "notary",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction: "",
+        instructionEmpty: true,
+        attachments: [],
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        sourceRunPath: sourceRun.runDirectory,
+        sourceRun,
+        ...ticketFields,
+        ...(options.correlationId === undefined
+            ? {}
+            : { correlationId: options.correlationId }),
+    };
+}
+/** Package-owned fixed kickoff only — never caller instruction/attachments.
+ * Ticket rides admitted → activation → agent-start typed bound (not free-text kickoff). */
+export function buildNotaryTransportPrompt(_admitted, engineMaterial) {
+    return appendEngineSessionMaterial([NOTARY_FIXED_KICKOFF], engineMaterial).join("\n");
+}
+/**
+ * Parse Reviewer-specific argv after the `reviewer` token.
+ * Public flags: --project, required --base, optional repeatable --authority-ref.
+ * Reviewer gathers its own evidence; users submit neither attachments nor capability packets.
+ * Caller instruction remains scope/procedure provenance — not Spec authority.
+ */
+/**
+ * Parse Gleaner-Left argv after the `gleaner-left` token.
+ * Public flags: --project, required --base. No --attach / ticket face (unanchored self-fetch).
+ * Instruction may be empty; callers must not pass directional instruction.
+ */
+export function parseGleanerLeftArgv(args) {
+    let project;
+    let baseRevision;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("gleaner-left");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "base") {
+                baseRevision = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            throw new CliUsageError(`unknown gleaner-left option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown gleaner-left option: ${token}`);
+        }
+        positional.push(token);
+    }
+    options.assertRequired();
+    return {
+        instruction: positional.join(" "),
+        baseRevision: baseRevision,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+/**
+ * Admit a Gleaner-Left Role run on the fixed comparison base.
+ * Empty instruction is the lawful path; no attachment/ticket admission face.
+ */
+export async function admitGleanerLeftInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    if (options.baseRevision.trim() === "") {
+        throw new CliUsageError("--base requires a nonempty revision");
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "gleaner-left",
+        home: options.home,
+    });
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    const instruction = options.instruction;
+    const instructionEmpty = instruction.trim() === "";
+    const admitted = {
+        role: "gleaner-left",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty,
+        baseRevision: options.baseRevision,
+        attachments: [],
+        ...(options.correlationId === undefined
+            ? {}
+            : { correlationId: options.correlationId }),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "gleaner-left",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty,
+        attachments: [],
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        baseRevision: options.baseRevision,
+        ...(options.correlationId === undefined
+            ? {}
+            : { correlationId: options.correlationId }),
+    };
+}
+/** Bound comparison base is a typed fact, not a directional instruction. */
+export function buildGleanerLeftTransportPrompt(admitted, engineMaterial) {
+    const lines = [
+        `左拾遗案已受理。比较基线：${admitted.baseRevision}`,
+    ];
+    if (!admitted.instructionEmpty) {
+        lines.push("", admitted.instruction);
+    }
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+export function parseReviewerArgv(args) {
+    // Spellings from PUBLIC_OPTION_TABLE.reviewer (#342). No --attach face.
+    const attachmentPaths = [];
+    const authorityRefs = [];
+    let project;
+    let baseRevision;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("reviewer");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "base") {
+                baseRevision = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            if (taken.def.id === "authority-ref") {
+                authorityRefs.push(requireAuthorityRef(taken.value));
+                continue;
+            }
+            throw new CliUsageError(`unknown reviewer option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown reviewer option: ${token}`);
+        }
+        positional.push(token);
+    }
+    // Unconditional required (e.g. --base) from typed table via shared consumer (#342).
+    options.assertRequired();
+    return {
+        instruction: positional.join(" "),
+        attachmentPaths,
+        baseRevision: baseRevision,
+        authorityRefs,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+/**
+ * Admit a Reviewer Role run on the fixed base only.
+ * Caller instruction is optional provenance; Reviewer acquires issue/authority independently.
+ * Optional authorityRefs are frozen as durable references only — not Spec prose.
+ */
+export async function admitReviewerInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    if (options.baseRevision.trim() === "") {
+        throw new CliUsageError("--base requires a nonempty revision");
+    }
+    const authorityRefs = Object.freeze((options.authorityRefs ?? []).map((ref) => requireAuthorityRef(ref)));
+    const projectRoot = resolve(options.project ?? options.cwd);
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "reviewer",
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    // Public parse already rejects attachments; keep freeze loop for structural symmetry.
+    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    const instruction = options.instruction;
+    const instructionEmpty = instruction.trim() === "";
+    const admitted = {
+        role: "reviewer",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty,
+        baseRevision: options.baseRevision,
+        authorityRefs: [...authorityRefs],
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "reviewer",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        baseRevision: options.baseRevision,
+        authorityRefs,
+    };
+}
+/**
+ * Build the Pi prompt transport for an admitted Reviewer request.
+ * Semantic input is fixed base only — caller instruction stays provenance on disk.
+ * Optional engine material follows the same dual-path coordinates as Judge (#376/#378).
+ */
+export function buildReviewerTransportPrompt(admitted, engineMaterial) {
+    const lines = [
+        `本次审查的固定基点：${admitted.baseRevision}`,
+    ];
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+/**
+ * Parse Merger-specific argv after the `merger` token.
+ * Spellings from PUBLIC_OPTION_TABLE.merger; internal packet fields rejected (#342).
+ */
+export function parseMergerArgv(args) {
+    const attachmentPaths = [];
+    let project;
+    const positional = [];
+    const tokens = [...args];
+    const definitions = roleOptions("merger");
+    const options = createTypedOptionConsumer(definitions);
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            positional.push(...tokens);
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.id === "attach") {
+                attachmentPaths.push(requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "project") {
+                project = requireOptionPath(taken.def.canonical, taken.value);
+                continue;
+            }
+            throw new CliUsageError(`unknown merger option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        // Rejected public spellings (#342) plus other internal packet field faces.
+        if (isRejectedPublicSpelling("merger", token) ||
+            token === "--targetObjectId" ||
+            token.startsWith("--targetObjectId=") ||
+            token === "--sourceObjectId" ||
+            token.startsWith("--sourceObjectId=") ||
+            token === "--expectedConflictPaths" ||
+            token.startsWith("--expectedConflictPaths=") ||
+            token === "--resolutionScope" ||
+            token.startsWith("--resolutionScope=")) {
+            throw new CliUsageError("merger does not accept public packet fields; the adapter derives the active-merge envelope");
+        }
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown merger option: ${token}`);
+        }
+        positional.push(token);
+    }
+    options.assertRequired();
+    return {
+        instruction: positional.join(" "),
+        attachmentPaths,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+function mergerMaterialFromUtf8(text) {
+    const bytes = Buffer.from(text, "utf8");
+    return Object.freeze({
+        bytesBase64: bytes.toString("base64"),
+        sha256: sha256Hex(bytes),
+    });
+}
+/**
+ * Derive the mechanical Merger envelope from an already-active ordinary merge.
+ * Uses the production Git seam (HEAD, sole MERGE_HEAD, AUTO_MERGE, unmerged set).
+ * Failures are activation-class facts — not CLI semantic guesses.
+ */
+export async function deriveMergerEnvelopeFromActiveMerge(projectRoot, gitState = createProductionMergerGitState(projectRoot)) {
+    let state;
+    try {
+        state = await gitState.activeMerge();
+    }
+    catch (error) {
+        const message = error instanceof Error && error.message.trim() !== ""
+            ? error.message
+            : "Assigned repository does not have one ordinary in-progress merge";
+        throw new MergerEnvelopeDerivationError(message, { cause: error });
+    }
+    if (state.unmergedPaths.length === 0) {
+        throw new MergerEnvelopeDerivationError("Assigned repository does not have one ordinary in-progress merge with a complete conflict set");
+    }
+    const expectedConflictPaths = Object.freeze([...state.unmergedPaths]);
+    // Scope is derived as the complete conflict set; the role may not broaden it.
+    const resolutionScope = Object.freeze([...state.unmergedPaths]);
+    return Object.freeze({
+        targetObjectId: state.targetObjectId,
+        sourceObjectId: state.sourceObjectId,
+        automaticMergeTreeId: state.automaticMergeTreeId,
+        expectedConflictPaths,
+        resolutionScope,
+    });
+}
+/**
+ * Admit a Merger Role run on the common Invocation request.
+ * Mechanical envelope (parents, AUTO_MERGE, conflicts, scope) is derived from
+ * the active merge — callers never supply public packet fields for those facts.
+ */
+export async function admitMergerInvocation(options) {
+    if (options.project !== undefined) {
+        requireOptionPath("--project", options.project);
+    }
+    const instruction = options.instruction;
+    if (instruction.trim() === "") {
+        throw new CliUsageError("merger requires a nonblank task instruction");
+    }
+    const projectRoot = resolve(options.project ?? options.cwd);
+    // Derive mechanical envelope before placing a run identity so no-merge/drift
+    // fails honestly without orphan ledger rows or guessed packet fields.
+    const derived = await deriveMergerEnvelopeFromActiveMerge(projectRoot, options.gitState ?? createProductionMergerGitState(projectRoot));
+    const runId = (options.createRunId ?? uuidv7)();
+    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: projectRoot,
+        runId,
+        role: "merger",
+        home: options.home,
+    });
+    const attachmentsDirectory = join(runDirectory, "attachments");
+    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    // Intent materials seed primary-source investigation; the method owns the work.
+    const targetIntent = mergerMaterialFromUtf8(`Investigate primary sources for target parent ${derived.targetObjectId}. Do not invent intent.`);
+    const sourceIntent = mergerMaterialFromUtf8(`Investigate primary sources for source parent ${derived.sourceObjectId}. Do not invent intent.`);
+    const taskMaterial = mergerMaterialFromUtf8(instruction);
+    const authorityMaterial = mergerMaterialFromUtf8(instruction);
+    // Validate merger envelope before placing admitted identity.
+    const mergerInput = validateMergerInput({
+        version: 1,
+        attemptId: runId,
+        targetObjectId: derived.targetObjectId,
+        sourceObjectId: derived.sourceObjectId,
+        materials: {
+            task: taskMaterial,
+            authority: authorityMaterial,
+            targetIntent,
+            sourceIntent,
+        },
+        expectedConflictPaths: [...derived.expectedConflictPaths],
+        resolutionScope: [...derived.resolutionScope],
+        // Authorized checks remain available on the assignment; default none.
+        authorizedChecks: [],
+    });
+    const mergerInputPath = join(runDirectory, "merger-input.json");
+    await writeFile(mergerInputPath, `${JSON.stringify(mergerInput, null, 2)}\n`, "utf8");
+    const admitted = {
+        role: "merger",
+        runId,
+        bookKey,
+        projectRoot,
+        runDirectory,
+        principal,
+        instruction,
+        instructionEmpty: false,
+        mergerInputPath,
+        derived: {
+            targetObjectId: derived.targetObjectId,
+            sourceObjectId: derived.sourceObjectId,
+            automaticMergeTreeId: derived.automaticMergeTreeId,
+            expectedConflictPaths: [...derived.expectedConflictPaths],
+            resolutionScope: [...derived.resolutionScope],
+        },
+        attachments: attachments.map((a) => ({
+            provenancePath: a.provenancePath,
+            frozenPath: a.frozenPath,
+            byteLength: a.byteLength,
+            sha256: a.sha256,
+            mediaKind: a.mediaKind,
+        })),
+    };
+    const admittedRequestPath = join(runDirectory, "admitted-request.json");
+    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+        sessionDirectory,
+        sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    return {
+        role: "merger",
+        runId,
+        bookKey,
+        projectRoot,
+        instruction,
+        instructionEmpty: false,
+        attachments,
+        runDirectory,
+        principal,
+        admittedRequestPath,
+        mergerInputPath,
+        derived: admitted.derived,
+    };
+}
+/**
+ * Build the Pi prompt transport for an admitted Merger request.
+ * Every invocation forces package merge-only method expansion before conflict work.
+ */
+export function buildMergerTransportPrompt(admitted, engineMaterial) {
+    const lines = [
+        `/skill:resolving-merge-conflicts ${admitted.instruction}`,
+    ];
+    if (admitted.attachments.length > 0) {
+        lines.push("");
+        lines.push("已受理附件（冻结快照路径）：");
+        for (const attachment of admitted.attachments) {
+            lines.push(`- ${attachment.frozenPath}`);
+        }
+    }
+    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+}
+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).
+ * `flag` names the actual argv face in diagnostics (cohort group lists reuse this).
+ */
+export function parseAnalystTicketNumber(raw, flag = "--ticket") {
+    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;
+}
+/**
+ * Parse one cohort issue token: bare positive integer or `book:N`.
+ * Book keys may contain ":" (e.g. synthetic `root:<path>`) — split on the last
+ * colon only when the RHS is a positive integer token.
+ */
+export function parseAnalystCohortIssueToken(raw, flag) {
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        throw new CliUsageError(`${flag} requires a comma-separated list of N or book:N`);
+    }
+    const sep = trimmed.lastIndexOf(":");
+    if (sep > 0) {
+        const rhs = trimmed.slice(sep + 1);
+        if (ANALYST_TICKET_NUMBER_PATTERN.test(rhs)) {
+            const bookKey = trimmed.slice(0, sep);
+            if (bookKey.trim() === "") {
+                throw new CliUsageError(`${flag} book:N requires a non-empty book key, got ${raw}`);
+            }
+            return {
+                kind: "book-qualified",
+                bookKey,
+                issueNumber: parseAnalystTicketNumber(rhs, flag),
+            };
+        }
+    }
+    return {
+        kind: "bare",
+        issueNumber: parseAnalystTicketNumber(trimmed, flag),
+    };
+}
+/**
+ * Sole cohort list grammar (#412): split on unescaped commas. `\,` is a literal
+ * comma and `\\` a literal backslash — both round-trip, so any directory-name
+ * book key (ADR 0048) is expressible. Any other `\x` stays literally `\x`, so
+ * pre-existing unescaped input never changes meaning. Colons remain owned by
+ * the token's lastIndexOf(':') rule.
+ */
+function splitAnalystCohortIssueListParts(raw) {
+    const parts = [];
+    let current = "";
+    let escaped = false;
+    for (const ch of raw) {
+        if (escaped) {
+            current += ch === "," || ch === "\\" ? ch : `\\${ch}`;
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === ",") {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(escaped ? `${current}\\` : current);
+    return parts;
+}
+function parseAnalystCohortIssueTokenList(raw, flag) {
+    const trimmed = raw.trim();
+    if (trimmed === "") {
+        throw new CliUsageError(`${flag} requires a comma-separated list of N or book:N`);
+    }
+    const parts = splitAnalystCohortIssueListParts(trimmed).map((part) => part.trim());
+    if (parts.some((part) => part === "")) {
+        throw new CliUsageError(`${flag} requires a comma-separated list of N or book:N`);
+    }
+    return parts.map((part) => parseAnalystCohortIssueToken(part, flag));
+}
+function requireOptionValue(flag, value, what) {
+    if (value === undefined || value.trim() === "") {
+        throw new CliUsageError(`${flag} requires ${what}`);
+    }
+    return value;
+}
+/**
+ * Parse analyst-specific argv after the `analyst` token (#336/#337/#338).
+ * Spellings + mode relation contracts from PUBLIC_OPTION_TABLE.analyst / ANALYST_* (#342).
+ * Mode exclusion, conditional requiredness, cardinality, and at-least-one are
+ * table-driven — do not restate them as parallel handwritten branches here.
+ * Unconditional required:true also goes through the shared consumer.
+ */
+export function parseAnalystArgv(args) {
+    const valueLists = new Map();
+    const tokens = [...args];
+    const definitions = roleOptions("analyst");
+    // Shared typed consumer: dashed + positional take, repeatable, required (#342).
+    const options = createTypedOptionConsumer(definitions);
+    const pushValue = (id, value) => {
+        const existing = valueLists.get(id);
+        if (existing === undefined)
+            valueLists.set(id, [value]);
+        else
+            existing.push(value);
+    };
+    while (tokens.length > 0) {
+        if (tokens[0] === "--") {
+            tokens.shift();
+            if (tokens.length > 0) {
+                throw new CliUsageError(`unexpected analyst argument: ${tokens[0]}`);
+            }
+            break;
+        }
+        const taken = options.takeDashed(tokens);
+        if (taken !== undefined) {
+            if (taken.def.valueMetavar === null) {
+                pushValue(taken.def.id, "");
+                continue;
+            }
+            if (taken.def.id === "ticket") {
+                if (taken.value === undefined || taken.value.trim() === "") {
+                    throw new CliUsageError("analyst --ticket requires a positive integer");
+                }
+                pushValue("ticket", taken.value);
+                continue;
+            }
+            if (taken.def.id === "attach") {
+                pushValue("attach", requireOptionPath(taken.def.canonical, taken.value));
+                continue;
+            }
+            if (taken.def.id === "group-a-label" || taken.def.id === "group-b-label") {
+                pushValue(taken.def.id, requireOptionValue(taken.def.canonical, taken.value, "a label"));
+                continue;
+            }
+            if (taken.def.id === "group-a-issues" || taken.def.id === "group-b-issues") {
+                pushValue(taken.def.id, requireOptionValue(taken.def.canonical, taken.value, "a comma-separated list of N or book:N"));
+                continue;
+            }
+            throw new CliUsageError(`unknown analyst option: ${taken.def.canonical}`);
+        }
+        const token = tokens.shift();
+        // #399: deleted --project-root; disabled --model-groups public face.
+        if (isRejectedPublicSpelling("analyst", token)) {
+            if (token === "--project-root" || token.startsWith("--project-root=")) {
+                throw new CliUsageError("analyst no longer accepts --project-root (deleted); use bare call for whole book or --ticket N (cwd git common-dir selects the book)");
+            }
+            if (token === "--model-groups" || token.startsWith("--model-groups=")) {
+                throw new CliUsageError("analyst --model-groups public CLI face is disabled; input face is being redesigned for multi-issue comparison (see follow-up ticket)");
+            }
+            throw new CliUsageError(`unknown analyst option: ${token}`);
+        }
+        if (token.startsWith("-") && token !== "-") {
+            throw new CliUsageError(`unknown analyst option: ${token}`);
+        }
+        // Positional selectors (e.g. sweep) via shared typed consumer — not a parallel list.
+        const positional = options.takePositional(token);
+        if (positional !== undefined) {
+            pushValue(positional.id, "");
+            continue;
+        }
+        throw new CliUsageError(`unexpected analyst argument: ${token}`);
+    }
+    const counts = new Map();
+    for (const [id, values] of valueLists) {
+        counts.set(id, values.length);
+    }
+    options.assertRequired();
+    const mode = resolveAnalystMode(new Set(counts.keys()));
+    const verdict = evaluateAnalystModeOptionContract(mode, counts);
+    if (!verdict.ok) {
+        throw new CliUsageError(verdict.message);
+    }
+    if (mode === "cohort") {
+        const groupALabel = valueLists.get("group-a-label")[0];
+        const groupAIssuesRaw = valueLists.get("group-a-issues")[0];
+        const groupBLabel = valueLists.get("group-b-label")[0];
+        const groupBIssuesRaw = valueLists.get("group-b-issues")[0];
+        return {
+            query: "cohort",
+            groups: [
+                {
+                    groupLabel: groupALabel,
+                    issues: parseAnalystCohortIssueTokenList(groupAIssuesRaw, "--group-a-issues"),
+                },
+                {
+                    groupLabel: groupBLabel,
+                    issues: parseAnalystCohortIssueTokenList(groupBIssuesRaw, "--group-b-issues"),
+                },
+            ],
+        };
+    }
+    if (mode === "sweep") {
+        return {
+            query: "sweep",
+            attachmentPaths: valueLists.get("attach") ?? [],
+        };
+    }
+    const ticketRaw = valueLists.get("ticket")?.[0];
+    return {
+        query: "issue",
+        ...(ticketRaw === undefined
+            ? {}
+            : { ticket: parseAnalystTicketNumber(ticketRaw) }),
+    };
+}