@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2652-next.adb6682

package/README.md

@@ -4,30 +4,14 @@ Packaged workflow roles for [Pi](https://pi.dev): `judge`, `fixer`, `coder`, `re
 
 ## Install
 
-Install through Pi so the CLI and runtime come from the same package copy, and add Pi's private npm bin to `PATH` once:
+Install through Pi so the CLI and runtime come from the same package copy, and add Pi’s private npm bin to `PATH` once:
 
 ```bash
 pi install npm:@akagilnc/pi-workflow-roles
 export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 ```
 
-Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; seat and Gate-officer configuration lives under Reading results below.
-
-### Test channel (`next`)
-
-Family / dogfood installs use the same package under dist-tag `next`, on a dedicated `HOME` so the test surface never shares AK config, ledger, book, or `PI_CODING_AGENT_DIR` with the host install. Do not mount or copy host credentials into the test home; do not use a book/worktree as a stand-in for install isolation. No second global npm.
-
-```bash
-export HOME=/path/to/test-home          # dedicated test HOME
-export PI_CODING_AGENT_DIR="$HOME/.pi/agent"
-export PATH="$PI_CODING_AGENT_DIR/npm/node_modules/.bin:$PATH"
-```
-
-- **First install of next**: `pi install npm:@akagilnc/pi-workflow-roles@next` → `ak-role roles` runs; installed version looks like `0.1.<count>-next.<shortsha>`.
-- **Advance to a newer next**: `pi update npm:@akagilnc/pi-workflow-roles@next` → `<shortsha>` becomes the new CI `head_sha` prefix (7 chars).
-- **Same-version reinstall / restore**: rerun the first-install command → idempotent; version unchanged (stamp path that only moves the dist-tag when the version is already on the registry).
-
-Publish routing (Actions, not local stamp): successful `ci` push on `main` → `latest`; successful `ci` push on an allowlisted non-main branch (see `.github/workflows/ci.yml` `push.branches`) → `next`. PR completions and failed CI never publish.
+Update with `pi update npm:@akagilnc/pi-workflow-roles`—never a second global `npm install -g`. Inspect with `ak-role roles` and `ak-role help <role>`; set per-seat model defaults with `ak-role config set <seat> <provider/model[:thinking]>` (callable seats plus automatic `gatekeeper` / `inspector` / `navigator`); clear a Gate officer override with `ak-role config unset <gatekeeper|inspector|notary>`; set or clear a persistent labor engine (callable roles) with `ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`.
 
 ## Reading results
 
@@ -39,11 +23,13 @@ ak-role judge --attach ./plan.md "Review this plan." > result.txt
 
 Exit status reports lifecycle honesty, not business success: every lawful typed result (including `audit_escalation`) exits zero; a failure without a lawful result exits nonzero, and its Terminal carries the Error Artifact ref and original cause instead of a fabricated receipt.
 
-`ak-role resume <runId> [message]` reopens that run's exact Pi session. Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same session continues to a terminal. The optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); omit it to use the package resume envelope. Whether to resume is the caller's decision: the command does not require a typed HTTP 429 or a `resumable` state. Unknown run IDs and missing session principals are rejected. Collector, Doctor, and Notary remain one-shot. The model resolves from the **current seat configuration**; pass `--model` explicitly when identity matters (#552 ruling).
+`ak-role resume <runId> [message]` reopens that run's exact Pi session. Standard chain after a role `escalate`s: take the owner ruling and feed it back with `ak-role resume <runId> "<ruling>"` so the same session continues to a terminal. The optional `message` after `runId` is passed through unchanged as the continuation prompt (opaque: not parsed as flags); omit it to use the package resume envelope. Whether to resume is the caller's decision: the command does not require a typed HTTP 429 or a `resumable` state. Unknown run IDs and missing session principals are rejected. Collector, Doctor, and Notary remain one-shot. The package never auto-switches providers; override the model for one run with the global flags.
 
 Judge, coder, fixer, reviewer, and merger also retry a non-lawful LLM call in place (same `runId` and session) up to `autoResumeLimit` times. Unset defaults to 2; `ak-role config set-auto-resume-limit <N>` writes the ceiling (`0` disables). Lawful typed terminals (`accepted`, `audit_escalation`, `no_receipt`) stop immediately. Manual `ak-role resume` stays available.
 
-Seat and Gate-officer configuration:
+Global overrides work before the opaque message segment: `ak-role --model <provider/model[:thinking]> resume <runId>` or `ak-role resume --model <provider/model[:thinking]> <runId>`.
+
+Every run also prepares Navigator advice in the same Terminal. Configure seats like this:
 
 ```bash
 ak-role config set judge <provider/model[:thinking]>
@@ -59,46 +45,63 @@ ak-role config unset-engine judge
 ak-role config set-auto-resume-limit 3
 ```
 
-For Gate officers (`gatekeeper` / `inspector` / `notary`) resolution is officer pin → province (`gatekeeper`) pin → inherit parent session; an explicit selection that fails is loud and does not fall back. Configuration usage and refusal text are owned by `ak-role config` / `ak-role help config`.
+`config set` stores the seat model default. For Gate officers (`gatekeeper` / `inspector` / `notary`) resolution is officer pin → province (`gatekeeper`) pin → inherit parent session; an explicit selection that fails is loud and does not fall back. `config unset` clears only those officer overrides. `config set-engine` / `unset-engine` store or clear the persistent labor-engine name on callable roles (same seats as `--engine`; navigator refused — no independent activation). `config set-auto-resume-limit` stores the single-call auto-resume ceiling. Usage and refusal text are owned by `ak-role config` / `ak-role help config`.
+
+Receipts are typed, so callers compose roles without parsing prose; ordering and stopping stay caller-owned. Programmatic consumers derive contracts from the exported schemas in `src/package-contracts/`, not from this guide.
 
-Receipts are typed, so callers compose roles without parsing prose; ordering and stopping stay caller-owned ([ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)). Programmatic consumers derive contracts from the exported schemas in `src/package-contracts/`, not from this guide.
+### Gate submission gate
 
-Gate submission gate: on completing-side submissions the package may spawn the Gate province before the run settles (`gatekeeper` dispatching `inspector` or `notary`); bounce means rewrite-and-resubmit in that same session, not role failure; `planned` / `refused` / `unfinished` skip the province; read gate history from the typed gate section of the receipt, never from session prose. Pointers: [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md), [ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md). A labor-engine detour that fails to spawn, exits nonzero, or produces no usable output stops the run through the existing infrastructure-failure path with the original cause visible ([ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)).
+On completing-side submissions the package may spawn the Gate province before the run settles: `gatekeeper` reads the subject and dispatches an officer (`inspector` or `notary`); existing auditor hooks stay where already wired. The gate runs inside the submission session; bounce means rewrite-and-resubmit in that same session — not role failure; the final receipt is the post-gate product. `planned` / `refused` / `unfinished` skip the province. Pointers only: [ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md), [ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md). Gate history is projected into the typed TerminalResult: an optional gate section lists the seats that actually sat, each dispatch round (officer, optional reason verbatim), and each officer report (seat, status, findings). Absent when no gate ran. Do not scrape session prose for gate status — read the typed section.
+
+When a labor-engine detour process fails to spawn, exits nonzero, or produces no usable output, the role run stops through the existing infrastructure-failure path with the original cause visible. The seat does not continue the labor or produce a typed Receipt. Caller cancellation continues to propagate unchanged. See [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md).
 
 ## Call the roles
 
-The examples below are usage sketches; option identity, aliases, requiredness, and mode faces are owned by `ak-role help <command>`, not by a second flag contract here.
+Public option identity, aliases, requiredness, and mode faces live in the generated [Public CLI options](#public-cli-options-generated) table and in `ak-role help <command>` — both project the same typed source. The examples below are usage sketches, not a second flag contract. An instruction is optional for judge, collector, and doctor; notary admits no caller prompt or attachment; analyst is deterministic (see help). Required nonblank for coder, fixer, reviewer, and merger.
 
 ```bash
-# judge — adjudicate the supplied materials
+# judge — adjudicate the supplied materials; infers its burden, no burden flag
 ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
 
-# coder — first implementation
+# coder — first implementation; phase defaults to apply, or pass plan
 ak-role coder plan "Propose the first implementation plan."
 ak-role coder apply --attach ./plan.md "Implement the approved slice."
+# apply binds the package-owned TDD method; do not bind a home Skill as a substitute
 
-# reviewer — fixed-target two-axis review; completed ≠ approved, read the findings
-ak-role reviewer --base main "Review the branch."
+# reviewer — fixed-target two-axis review (Standards + Spec)
+ak-role reviewer --base main "Review the branch against the governing issue and repository authority."
+# --base is required and pins the fixed point; Reviewer does not accept --attach
+# completed ≠ approved — read the findings in the Terminal
 
-# collector — GitHub PR review evidence; one-shot
+# collector — GitHub PR review evidence; github.com only, needs gh auth; one-shot
 ak-role collector --pr 42 --repo owner/repository
+# repo defaults from origin; --repo owner/repo overrides
 
-# fixer — repair the assigned findings
+# fixer — repair the assigned findings; phase defaults to apply, or pass plan
 ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
+# --prerequisites is a JSON array of {id, requirement}; malformed grammar exits 2
+# apply/resume mount the package-owned diagnosis and TDD methods from the install; neither is forced into the prompt
 
 # doctor — diagnose one retained case; one-shot
 ak-role doctor --issue 115 "Diagnose this retained case."
+# --runs must stay project-relative: .ak-roles/books/<book>/issues/<n>/runs matching --issue
 
-# merger — resolve one merge already in conflict (start it with Git's ort first)
+# merger — resolve one merge already in conflict (start it first with Git’s ort)
 ak-role merger --project /path/to/worktree "Reconcile the active merge."
+# hands new intent/authority questions back instead of inventing authority
 
-# notary — document-fidelity check on one retained source run; one-shot
+# notary — document-fidelity check on one retained source run; zero prompt/attachment; one-shot
 ak-role notary --source-run <runId@role|path>
 
-# analyst — deterministic metrics; bare call = whole book
+# analyst — deterministic metrics over the book (cwd git common-dir); bare = whole book
 ak-role analyst
+ak-role analyst --ticket <N>
+ak-role analyst sweep --attach ./payload.md
+ak-role analyst --cohort \
+  --group-a-label A --group-a-issues 1,2 \
+  --group-b-label B --group-b-issues 3,4
 
-# after escalate: feed the owner ruling into the same session (standard chain)
+# after escalate: feed the owner ruling into the same session (standard chain; see resume under Reading results)
 ak-role resume <runId> "<ruling>"
 ```
 
@@ -110,8 +113,95 @@ Roles are named after Tang/Song offices; the full roster and naming rule live in
 
 Enable fast tier with `echo "fast_mode = on" > ~/.pi-codex-fast`; disable it with `echo "fast_mode = off" > ~/.pi-codex-fast` (or delete the file). The change takes effect on the next request without a restart. Fast tier costs more than the default tier.
 
-## Normative pointers
-
-- Command usage and refusal text: `ak-role help <command>`, `ak-role help config` (sole authority).
-- Decisions and rationale: `docs/adr/` (composition ADR 0010, public CLI face ADR 0052, submission gates ADR 0066/0067/0070/0072, labor engines ADR 0069/0071, among others; not exhaustive).
-- Glossary: [CONTEXT.md](CONTEXT.md). Programmatic contracts: `src/package-contracts/` exports.
+<!-- BEGIN GENERATED: public-cli-options -->
+## Public CLI options (generated)
+
+Generated from `src/public-cli/option-definitions.ts`. Prefer `ak-role help <command>`. Do not hand-edit this section.
+
+### `global`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--model` | — | `provider/model` | no | no | option | — | Override the effective seat model for this invocation (before or after the command). |
+| `--thinking` | — | `level` | no | no | option | — | Override thinking level: off\|minimal\|low\|medium\|high\|xhigh\|max. |
+| `--engine` | — | `name` | no | no | option | — | Optional labor engine for this invocation (owner pool-directive name; packaged notes attached when present; any role). |
+| `--help` | `-h` | — | no | no | option | — | Show public CLI help and exit. |
+
+### `judge`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
+
+### `coder`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `plan\|apply` | `plan`, `apply` | — | no | no | positional | phases=plan\|apply; default=apply | Optional phase token before the instruction; defaults to apply. |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
+
+### `fixer`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `plan\|apply` | `plan`, `apply` | — | no | no | positional | phases=plan\|apply; default=apply | Optional phase token before the instruction; defaults to apply. |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
+| `--prerequisites` | — | `path` | no | no | option | — | JSON array of {id, requirement} prerequisite objects. |
+
+### `reviewer`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--base` | — | `revision` | yes | no | option | — | Required fixed-point revision for the pinned review target. |
+| `--authority-ref` | — | `ref` | no | yes | option | — | Durable authority reference/URL (repeatable; refs only, not inline prose). |
+
+### `collector`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
+| `--pr` | — | `number` | yes | no | option | — | Required positive GitHub pull request number. |
+| `--repo` | — | `owner/repo` | no | no | option | — | GitHub owner/repo override (defaults from origin when github.com). |
+| `--request-manifest` | — | `path` | no | no | option | — | Optional request manifest JSON path ({requests:[{id,body}]}). |
+
+### `doctor`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
+| `--issue` | — | `number` | yes | no | option | — | Required positive issue number for the retained case. |
+| `--runs` | — | `path` | no | no | option | — | Optional project-relative .ak-roles/books/<book>/issues/<n>/runs override matching --issue. |
+
+### `merger`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | no | no | option | — | Project root with one ordinary in-progress merge (defaults to cwd). |
+| `--attach` | — | `path` | no | yes | option | — | Attach a regular file; frozen at admission (repeatable). |
+
+### `notary`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | no | no | option | — | Project root for ledger identity (defaults to process cwd). |
+| `--source-run` | — | `runId@role\|path` | yes | no | option | — | Required source run locator (runId@role under the book home, or path to that run directory). Zero prompt/attachment projection. |
+
+### `analyst`
+
+| Spelling | Aliases | Value | Required | Repeatable | Form | Modes/Phases | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `sweep` | — | — | no | no | positional | modes=sweep | Optional sweep mode token (at most once; no other positionals). |
+| `--ticket` | — | `number` | no | no | option | modes=issue | Ticket/issue number; live filter by invocation.ticketNumber inside the cwd book (git common-dir). Bare call = whole book. No library-index bootstrap. |
+| `--attach` | — | `path` | when:sweep | yes | option | modes=sweep; max=sweep:1 | Sweep-mode attachment path; required exactly once in sweep; payload is the attachment body. |
+| `--cohort` | — | — | no | no | option | modes=cohort | Select cohort mode. |
+| `--group-a-label` | — | `label` | when:cohort | no | option | modes=cohort | Cohort group A label (required in cohort mode). |
+| `--group-a-issues` | — | `N\|book:N[,...]` | when:cohort | no | option | modes=cohort | Cohort group A issues: bare N joins cwd book; book:N selects another book; escape a literal comma/backslash in a book key as \, / \\ (required in cohort mode). |
+| `--group-b-label` | — | `label` | when:cohort | no | option | modes=cohort | Cohort group B label (required in cohort mode). |
+| `--group-b-issues` | — | `N\|book:N[,...]` | when:cohort | no | option | modes=cohort | Cohort group B issues: bare N joins cwd book; book:N selects another book; escape a literal comma/backslash in a book key as \, / \\ (required in cohort mode). |
+<!-- END GENERATED: public-cli-options -->

package/README.zh-CN.md

@@ -11,23 +11,7 @@ pi install npm:@akagilnc/pi-workflow-roles
 export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
 ```
 
-更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；席位与官席配置见下方「读结果」。
-
-### 测试通道（`next`）
-
-家族／dogfood 安装面复用同一包，经 dist-tag `next` 取得；测试面自有 `HOME`，其下的 AK config／ledger／book 与 `PI_CODING_AGENT_DIR` 一并独立，不与宿主已装包共享。测试面不挂载、不复制宿主凭据；不以 book／worktree 冒充安装隔离。不装第二份全局 npm。
-
-```bash
-export HOME=/path/to/test-home          # 测试面自有 HOME
-export PI_CODING_AGENT_DIR="$HOME/.pi/agent"
-export PATH="$PI_CODING_AGENT_DIR/npm/node_modules/.bin:$PATH"
-```
-
-- **首次装 next**：`pi install npm:@akagilnc/pi-workflow-roles@next` → `ak-role roles` 可跑；装到的版本形如 `0.1.<count>-next.<shortsha>`。
-- **推进到新 next**：`pi update npm:@akagilnc/pi-workflow-roles@next` → 版本号里的 `<shortsha>` 变为新 CI `head_sha` 的前 7 位。
-- **同版本重装／恢复**：重跑首次安装命令 → 幂等，版本不变（对应 stamp「版本已在 registry 则只移 dist-tag」路径）。
-
-发布路由（Actions 真入口，非本地 stamp）：`ci` 在 `main` 上成功 push → `latest`；`ci` 在 allowlist 非 main 分支上成功 push（见 `.github/workflows/ci.yml` 的 `push.branches`）→ `next`。PR completion 与失败 CI 不发布。
+更新用 `pi update npm:@akagilnc/pi-workflow-roles`——勿另起全局 `npm install -g`。查看能力：`ak-role roles`、`ak-role help <role>`；设席位模型默认：`ak-role config set <seat> <provider/model[:thinking]>`（可调用席位，以及自动出席的 `gatekeeper`／`inspector`／`navigator`）；清除门下省官钉：`ak-role config unset <gatekeeper|inspector|notary>`；设或清持久劳务引擎（可调用角色）：`ak-role config set-engine <seat> <name>` / `ak-role config unset-engine <seat>`。
 
 ## 读结果
 
@@ -39,11 +23,13 @@ ak-role judge --attach ./plan.md "Review this plan." > result.txt
 
 退出码报的是生命周期诚实，不是业务成败：一切合法 typed 终态（含 `audit_escalation`）退出零；无合法终态的失败退出非零，其 Terminal 携带 Error Artifact 引用与原始原因，不伪造回执。
 
-`ak-role resume <runId> [message]` 重开该次运行的同一 Pi session。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 session，角色继续走到终局。`runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略则用包自带 resume envelope。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。通进司、太医署、符宝郎仍为一次性，无 resume。模型解析自**现行席位配置**；在乎身份的续跑显式带 `--model` 钉住（#552 裁定口径）。
+`ak-role resume <runId> [message]` 重开该次运行的同一 Pi session。角色 `escalate`（直通御前）后拿到 owner 裁定，标准续跑是 `ak-role resume <runId> "<裁定>"`——把裁定喂回同一 session，角色继续走到终局。`runId` 后可选的 `message` 原样作为续跑 prompt（opaque：不进全局旗标语法）；省略则用包自带 resume envelope。要不要续跑由调用者决定：不再要求 typed HTTP 429，也不要求 `resumable` 状态。未知 run ID、session 主体不在则拒绝。通进司、太医署、符宝郎仍为一次性，无 resume。包绝不自动换 provider；临时换模型用全局旗标。
 
 大理寺、将作监、修内司、御史台、校书郎在单次调用内对非 lawful LLM 终态原地续跑（同一 `runId` 与 session），次数上限为 `autoResumeLimit`。缺键默认 2；`ak-role config set-auto-resume-limit <N>` 写入（`0` 关闭自动续）。lawful typed 终态（`accepted` / `audit_escalation` / `no_receipt`）立即停止。手动 `ak-role resume` 仍可用。
 
-席位与官席配置：
+全局覆盖须在 opaque message 段之前：`ak-role --model <provider/model[:thinking]> resume <runId>` 或 `ak-role resume --model <provider/model[:thinking]> <runId>`。
+
+每次运行游奕使自动出席，建议随同一 Terminal 给出。配置：
 
 ```bash
 ak-role config set judge <provider/model[:thinking]>
@@ -59,46 +45,63 @@ ak-role config unset-engine judge
 ak-role config set-auto-resume-limit 3
 ```
 
-门下省官席解析顺序：官自钉 → 省钉（`gatekeeper`）→ 继承父 session；显式指定失败响亮、不回退。配置用法与拒绝文案以 `ak-role config`／`ak-role help config` 为准。
+`config set` 存席位模型默认。门下省官席（`gatekeeper`／`inspector`／`notary`）解析顺序：官自钉 → 省钉（`gatekeeper`）→ 继承父 session；显式指定失败响亮、不回退。`config unset` 只清这三官的覆盖。`config set-engine`／`unset-engine` 在可调用角色上写入或清除持久劳务引擎名（与 `--engine` 同轴；拒收 navigator——无独立 activation）。`config set-auto-resume-limit` 写入单次调用自动续跑上限。用法与拒绝文案以 `ak-role config`／`ak-role help config` 为准。
+
+回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者。编程消费者从 `src/package-contracts/` 导出推导契约，不从本文。
 
-回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。编程消费者从 `src/package-contracts/` 导出推导契约，不从本文。
+### 门下省交卷闸
 
-门下省交卷闸：完成侧交卷时包可在本局结算前起省（`gatekeeper` 派 `inspector`／`notary`），封驳＝当场重写重交，不是角色失败；`planned`／`refused`／`unfinished` 不调省；闸史读回执 typed gate 段，勿刮 session 散文。指针：[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)。劳务引擎绕行失败沿既有基础设施故障路径停止、真因可见（[ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)）。
+完成侧交卷时，包可能在本局结算前起门下省：`gatekeeper` 读受审物并派官（`inspector` 给事中或 `notary` 符宝郎）；既有审刑院挂钩仍在原位。闸在交卷 session 内运行；封驳＝当场重写重交，不是角色失败；最终回执即过闸产物。`planned`／`refused`／`unfinished` 不调省。指针：[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md)、[ADR 0072](docs/adr/0072-menxia-pre-pr-submission-hooks.md)。闸史已投影进 typed 回执：可选 gate 段列出实际在场席位、每轮派官（officer 与逐字 reason）与各官报告（席位/判决/findings）；无闸调用时该段缺席。勿刮 session 散文当闸状态——读 typed 段。
+
+劳务引擎绕行进程无法启动、非零退出或未产生可用输出时，角色运行沿既有基础设施失败路径立即停止并保留可见真因；座席不继续顶班，也不产出 typed 回执。调用方 cancel 仍原样传播。见 [ADR 0071](docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)。
 
 ## 调用百官
 
-下例只是用法速写；option 身份、别名、必填性与 mode 面以 `ak-role help <command>` 为准，不另立第二份旗标合同。
+公开 option 身份、别名、必填性与 mode 面以生成区 [公开 CLI 选项（生成）](#公开-cli-选项生成) 与 `ak-role help <command>` 为准——二者同源。下例只是用法速写，不是第二份旗标合同。指令对大理寺、通进司、太医署可省略；符宝郎零 prompt／附件；太史为确定性命令（见 help）。对将作监、修内司、御史台、校书郎必须非空。
 
 ```bash
-# 大理寺——审断所供材料
+# 大理寺——审断所供材料；自行推断举证责任，无 burden 旗标
 ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
 
-# 将作监——营造新作
+# 将作监——营造新作；phase 默认 apply，或显式 plan
 ak-role coder plan "Propose the first implementation plan."
 ak-role coder apply --attach ./plan.md "Implement the approved slice."
+# apply 强制包内 TDD 方法；勿绑 home Skill 顶替
 
-# 御史台——固定目标双轴察举；completed ≠ 准行，findings 在 Terminal 里
+# 御史台——固定目标双轴察举（Standards + Spec）
 ak-role reviewer --base main "Review the branch."
+# --base 为必填并钉住 fixed point；御史台不接受 --attach
+# completed ≠ 准行——findings 在 Terminal 里
 
-# 通进司——GitHub PR 收证；一次性
+# 通进司——GitHub PR 收证；仅 github.com，需 gh 已认证；一次性
 ak-role collector --pr 42 --repo owner/repository
+ak-role collector --pr 42 --request-manifest ./requests.json
+# 无配置时仅观察；可选 request manifest 为 {requests:[{id,body}]}；repo 默认取 origin
 
-# 修内司——缮修所指 findings
+# 修内司——缮修所指 findings；phase 默认 apply，或显式 plan
 ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
+# --prerequisites 为 {id, requirement} JSON 数组；语法畸形退出 2
 
 # 太医署——单案诊断；一次性
 ak-role doctor --issue 115 "Diagnose this retained case."
+# --runs 须为项目相对的 .ak-roles/books/<book>/issues/<n>/runs 且匹配 --issue
 
-# 校书郎——调和已在冲突的 merge（先用 Git ort 起动）
+# 校书郎——雠校一个已在冲突的 merge（先用 Git ort 起动）
 ak-role merger --project /path/to/worktree "Reconcile the active merge."
+# 遇新意图/权限问题交回调用者，不捏造 authority
 
-# 符宝郎——文书核验一份留存 source run；一次性
+# 符宝郎——对一份留存 source run 做文书核验；零 prompt／附件；一次性
 ak-role notary --source-run <runId@role|path>
 
-# 太史——确定性指标；裸调＝整簿
+# 太史——确定性指标（cwd 候簿＝git common-dir）；裸调＝整簿
 ak-role analyst
+ak-role analyst --ticket <N>
+ak-role analyst sweep --attach ./payload.md
+ak-role analyst --cohort \
+  --group-a-label A --group-a-issues 1,2 \
+  --group-b-label B --group-b-issues 3,4
 
-# escalate 后：把 owner 裁定喂回同一 session（标准链）
+# escalate 后：把 owner 裁定喂回同一 session（标准链；细则见上方「读结果」resume 段）
 ak-role resume <runId> "<裁定>"
 ```
 
@@ -130,14 +133,13 @@ ak-role resume <runId> "<裁定>"
 | analyst | **太史** | 司天台分析席：只读司天记录、出高阶指标；确定性机制，非 LLM，可单独调用 | 已建（[ADR 0068](docs/adr/0068-taishi-analysis-seat-reads-records-writes-sibling-home.md)；机器面键 `analyst`，[#445](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/445) 拼音清零） |
 | — | **司天台** | 记候簿——只打点、只指针，不分析不执法 | **一期不是角色**（[ADR 0047](docs/adr/0047-sitian-phase-one-mechanism-not-role.md)：零 LLM 双面对账）；分析席已由太史承担；机器面键 `archivist`（[#445](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/445)） |
 | gleaner-left | **左拾遗** | 合并前以无锚定冷眼审全幅合并候选，只上弹章、不封驳不裁决（风闻） | soul 已落＋[ADR 0067](docs/adr/0067-menxia-province-founding-jishizhong-fubaolang.md) 修正案；机器席位待建 |
-| marshal | **尚书省** | 审→判→修 质量收敛环的省部级驱动角色：调用方递票号与 baseline，尚书省驱动御史台/大理寺/修内司滚到收敛（converged 唯庭可判）或 escalate 上呈，交回 typed 报告；不弹、不判、不修，只让链条转到收敛 | 已定名（#145）；席位待落地（#146） |
 | — | **兰台** | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建 |
 | — | **考功司** | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，需要时另立票 |
 | — | **主簿** | 合并后勾稽销案：核实确已合上、清理残留、报到达 | 未建 |
 
 **merge 按钮归调用者**，没有任何角色握不可逆权限：通进司把收证这件苦活做完并报收集终态，人（或 AI）自己判断、自己点，点完想调主簿就调、不调也可以。
 
-上表**不规定调用顺序**——组合、顺序、重复次数归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。御史台／大理寺／审刑院是**职责分立的类比，不是必经链**；审刑院也并非只跟在大理寺之后，大理寺、御史台、太医署各自都有一次。门下省交卷闸是完成侧挂钩，不是调用者必经编排链。省部级角色的内部组合属于其单次调用的内政，公开 CLI 语义零变化——外部调用者仍一次启动其选中的一个角色，跨 CLI 调用的顺序、重复与停止仍全归外部调用者。
+上表**不规定调用顺序**——组合、顺序、重复次数归调用者（[ADR 0010](docs/adr/0010-callers-own-role-composition-and-repetition.md)）。御史台／大理寺／审刑院是**职责分立的类比，不是必经链**；审刑院也并非只跟在大理寺之后，大理寺、御史台、太医署各自都有一次。门下省交卷闸是完成侧挂钩，不是调用者必经编排链。
 
 `拾遗补阙` 成对留档，待将来出现第二个进言席再启用。
 
@@ -145,8 +147,95 @@ ak-role resume <runId> "<裁定>"
 
 开启：`echo "fast_mode = on" > ~/.pi-codex-fast`；关闭：`echo "fast_mode = off" > ~/.pi-codex-fast`（或删文件）。修改后无需重启，下一个请求即生效。Fast 档价格高于默认档。
 
-## 规范指针
-
-- 命令用法与拒绝文案：`ak-role help <command>`、`ak-role help config`（唯一权威）。
-- 决策与法理：`docs/adr/`（组合与顺序 ADR 0010、公开 CLI 面 ADR 0052、交卷闸 ADR 0066/0067/0070/0072、劳务引擎 ADR 0069/0071 等，未尽举）。
-- 术语表：[CONTEXT.md](CONTEXT.md)。编程契约：`src/package-contracts/` 导出。
+<!-- BEGIN GENERATED: public-cli-options -->
+## 公开 CLI 选项（生成）
+
+本表由 `src/public-cli/option-definitions.ts` 生成；以 `ak-role help <command>` 为准。勿手改本区。
+
+### `global`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--model` | — | `provider/model` | 否 | 否 | option | — | 覆盖本调用有效席位模型（可置于子命令前或后）。 |
+| `--thinking` | — | `level` | 否 | 否 | option | — | 覆盖 thinking 档位：off\|minimal\|low\|medium\|high\|xhigh\|max。 |
+| `--engine` | — | `name` | 否 | 否 | option | — | 本调用可选劳动引擎（池令名字；有包内调法笔记则附卷；全部角色可用）。 |
+| `--help` | `-h` | — | 否 | 否 | option | — | 显示公开 CLI 帮助并退出。 |
+
+### `judge`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
+
+### `coder`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `plan\|apply` | `plan`, `apply` | — | 否 | 否 | positional | phases=plan\|apply; default=apply | 指令前可选 phase 词元；默认 apply。 |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
+
+### `fixer`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `plan\|apply` | `plan`, `apply` | — | 否 | 否 | positional | phases=plan\|apply; default=apply | 指令前可选 phase 词元；默认 apply。 |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
+| `--prerequisites` | — | `path` | 否 | 否 | option | — | {id, requirement} 前置条件 JSON 数组路径。 |
+
+### `reviewer`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--base` | — | `revision` | 是 | 否 | option | — | 必填；钉住审查目标的 fixed-point revision。 |
+| `--authority-ref` | — | `ref` | 否 | 是 | option | — | 持久 authority 引用/URL（可重复；仅 ref，非内联散文）。 |
+
+### `collector`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
+| `--pr` | — | `number` | 是 | 否 | option | — | 必填；正整数 GitHub PR 号。 |
+| `--repo` | — | `owner/repo` | 否 | 否 | option | — | GitHub owner/repo 覆盖（默认取 github.com origin）。 |
+| `--request-manifest` | — | `path` | 否 | 否 | option | — | 可选 request manifest JSON 路径（{requests:[{id,body}]}）。 |
+
+### `doctor`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
+| `--issue` | — | `number` | 是 | 否 | option | — | 必填；留存病例的正整数 issue 号。 |
+| `--runs` | — | `path` | 否 | 否 | option | — | 可选项目相对 .ak-roles/books/<book>/issues/<n>/runs 覆盖，且须匹配 --issue。 |
+
+### `merger`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 已有进行中 ordinary merge 的项目根（默认 cwd）。 |
+| `--attach` | — | `path` | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |
+
+### `notary`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `--project` | — | `path` | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 |
+| `--source-run` | — | `runId@role\|path` | 是 | 否 | option | — | 必填源 run 定位符（簿内 runId@role，或该 run 目录路径）。零 prompt/附件投影。 |
+
+### `analyst`
+
+| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `sweep` | — | — | 否 | 否 | positional | modes=sweep | 可选 sweep 模式词元（至多一次；不得夹带其他 positional）。 |
+| `--ticket` | — | `number` | 否 | 否 | option | modes=issue | 票号；在 cwd 候簿（git common-dir）内按 invocation.ticketNumber 现取现算。裸调用=整簿。不依赖 library-index 自举。 |
+| `--attach` | — | `path` | 条件:sweep | 是 | option | modes=sweep; max=sweep:1 | sweep 模式附件路径；sweep 必填且恰一次；载荷为附件正文。 |
+| `--cohort` | — | — | 否 | 否 | option | modes=cohort | 选择 cohort 模式。 |
+| `--group-a-label` | — | `label` | 条件:cohort | 否 | option | modes=cohort | cohort A 组标签（cohort 模式必填）。 |
+| `--group-a-issues` | — | `N\|book:N[,...]` | 条件:cohort | 否 | option | modes=cohort | cohort A 组 issue：裸 N 归属 cwd 簿；book:N 显式跨簿；簿键中的逗号/反斜杠用 \, / \\ 转义（cohort 模式必填）。 |
+| `--group-b-label` | — | `label` | 条件:cohort | 否 | option | modes=cohort | cohort B 组标签（cohort 模式必填）。 |
+| `--group-b-issues` | — | `N\|book:N[,...]` | 条件:cohort | 否 | option | modes=cohort | cohort B 组 issue：裸 N 归属 cwd 簿；book:N 显式跨簿；簿键中的逗号/反斜杠用 \, / \\ 转义（cohort 模式必填）。 |
+<!-- END GENERATED: public-cli-options -->

package/dist/activation-ledger-topology.js

@@ -16,7 +16,7 @@ class ActivationLedgerError extends Error {
     this.name = "ActivationLedgerError";
   }
 }
-function resolveActivationLedgerHome(home = homedir) {
+function resolveActivationLedgerHome(home = () => process.env.HOME ?? homedir()) {
   const processHome = home();
   if (typeof processHome !== "string" || processHome.length === 0 || !isAbsolute(processHome)) {
     throw new ActivationLedgerError(

package/dist/archivist-record-entry.js

@@ -1,11 +1,8 @@
 import { createHash } from "node:crypto";
-import { existsSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, resolve, join, relative, sep } from "node:path";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
-import {
-  roleRunSessionCoordinates
-} from "./archivist-role-run-coordinates.js";
 import {
   ActivationLedgerError,
   activationBookDirectory,
@@ -15,26 +12,49 @@ import {
   physicallyContainedIn,
   resolveActivationLedgerHome
 } from "./activation-ledger-topology.js";
-const { findMostRecentSession } = await import(new URL("./core/session-manager.js", import.meta.resolve("@earendil-works/pi-coding-agent")).href);
+const CURRENT_SESSION_LEDGER = "current-session.json";
+function readCurrentSession(sessionDir) {
+  const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
+  try {
+    const value = JSON.parse(readFileSync(ledger, "utf8"));
+    if (typeof value !== "object" || value === null || typeof value.sessionFile !== "string" || value.sessionFile.length === 0) {
+      throw new Error("sessionFile is missing");
+    }
+    return value.sessionFile;
+  } catch (error) {
+    throw new ActivationLedgerError(
+      `archivist current-session ledger is unavailable or invalid (${ledger}): ${errorText(error)}`,
+      { cause: error }
+    );
+  }
+}
+function writeCurrentSession(sessionDir, sessionFile) {
+  const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
+  try {
+    writeFileSync(ledger, `${JSON.stringify({ sessionFile })}
+`, { flag: "wx" });
+  } catch (error) {
+    throw new ActivationLedgerError(
+      `archivist current-session ledger cannot be created (${ledger}): ${errorText(error)}`,
+      { cause: error }
+    );
+  }
+}
 const WORKER_SUBMISSION_GATE_KIND = "worker-submission-gate";
-function assertRecentFinalFileUnderLedgerHome(ledgerHome, sessionDir, recentFile) {
-  const absoluteHome = resolve(ledgerHome);
+function assertRecentFinalFileUnderSessionDir(sessionDir, recentFile) {
   const absoluteSessionDir = resolve(sessionDir);
   const absoluteFile = resolve(recentFile);
-  const relToHome = relative(absoluteHome, absoluteSessionDir);
-  const segments = relToHome.split(sep);
-  if (relToHome === "" || isAbsolute(relToHome) || relToHome === ".." || relToHome.startsWith(`..${sep}`) || segments[0] !== "books" || segments[1] === void 0 || segments[1] === "" || segments[1] === "." || segments[1] === "..") {
+  if (absoluteFile !== absoluteSessionDir && !pathContainedIn(absoluteSessionDir, absoluteFile)) {
     throw new ActivationLedgerError(
-      `archivist record sessionDir must be under a ledger book (${ledgerHome}): ${sessionDir}`
+      `archivist record session must be under the authorized nest (${sessionDir}): ${recentFile}`
     );
   }
-  const bookRoot = join(absoluteHome, "books", segments[1]);
-  let realBookRoot;
+  let realSessionDir;
   try {
-    realBookRoot = realpathSync(bookRoot);
+    realSessionDir = realpathSync(absoluteSessionDir);
   } catch (error) {
     throw new ActivationLedgerError(
-      `activation ledger book is not resolvable (${bookRoot}): ${errorText(error)}`,
+      `archivist record sessionDir is not resolvable (${absoluteSessionDir}): ${errorText(error)}`,
       { cause: error }
     );
   }
@@ -47,9 +67,9 @@ function assertRecentFinalFileUnderLedgerHome(ledgerHome, sessionDir, recentFile
       { cause: error }
     );
   }
-  if (realFile !== realBookRoot && !pathContainedIn(realBookRoot, realFile)) {
+  if (realFile !== realSessionDir && !pathContainedIn(realSessionDir, realFile)) {
     throw new ActivationLedgerError(
-      `archivist record session must be under the ledger book (${bookRoot}): ${recentFile}`
+      `archivist record session must be under the authorized nest (${sessionDir}): ${recentFile}`
     );
   }
 }
@@ -74,14 +94,13 @@ function createRecordSession(options) {
     sessionDir = physicallyContainedIn(ledgerHome, parentResolved) ? join(dirname(parentResolved), options.kind) : join(activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)), options.kind);
     parentSession = parentFile;
   }
+  const nestAlreadyExists = existsSync(sessionDir);
   ensureRealDirectoryTree(ledgerHome, sessionDir);
   const mayResumeSameNest = options.subject !== void 0 || options.kind === WORKER_SUBMISSION_GATE_KIND;
-  if (mayResumeSameNest) {
-    const recentFile = findMostRecentSession(sessionDir, cwd);
-    if (recentFile !== null) {
-      assertRecentFinalFileUnderLedgerHome(ledgerHome, sessionDir, recentFile);
-      return SessionManager.open(recentFile, sessionDir, cwd);
-    }
+  if (mayResumeSameNest && nestAlreadyExists) {
+    const recentFile = readCurrentSession(sessionDir);
+    assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+    return SessionManager.open(recentFile, sessionDir, cwd);
   }
   const session = SessionManager.create(
     cwd,
@@ -98,11 +117,13 @@ function createRecordSession(options) {
         session.setSessionFile(file);
       }
     }
+    if (mayResumeSameNest && file !== void 0) {
+      writeCurrentSession(sessionDir, file);
+    }
   }
   return session;
 }
 export {
   WORKER_SUBMISSION_GATE_KIND,
-  createRecordSession,
-  roleRunSessionCoordinates
+  createRecordSession
 };

package/dist/auditor-dossier-tool.js

@@ -4,7 +4,9 @@ export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier";
 /** Resolve the exact run binding already carried by the parent record session. */
 export function auditorRunDirectory(context) {
     const sessionFile = context.sessionManager?.getSessionFile?.();
-    return sessionFile === undefined ? undefined : resolve(dirname(dirname(sessionFile)));
+    if (sessionFile !== undefined)
+        return resolve(dirname(dirname(sessionFile)));
+    return undefined;
 }
 /** The one shared, run-bound dossier locator exposed to every auditor seat. */
 export function createAuditorDossierTool(runDirectory) {