@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/diarist-ticket-resolution.js

@@ -0,0 +1,177 @@
+/**
+ * 起居郎 pre-court ticket resolution (#582 / diarist-resolves-ticket-llm-layer).
+ * Unbound countersign: LLM typed assertion over accepted instruction, then two
+ * mechanical checks on N (complete decimal number in instruction; live GitHub issue).
+ * Verification failure is controlled failure — never washed to true-unbound.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createGhApiRunner, projectGhIssueBody, } from "./collector-github.js";
+import { ENGINE_DETOUR_STAGED_PROMPT_TOKEN, runEngineDetourOnce, } from "./engine-detour.js";
+export const DIARIST_RESOLVE_TICKET_METHOD_RELATIVE = "resources/diarist-resolve-ticket.md";
+export class DiaristTicketResolutionError extends Error {
+    code = "diarist-ticket-resolution";
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = "DiaristTicketResolutionError";
+        this.reason = reason;
+    }
+}
+export function resolveDiaristResolveTicketMethodPath(packageRoot = fileURLToPath(new URL("..", import.meta.url))) {
+    return join(packageRoot, DIARIST_RESOLVE_TICKET_METHOD_RELATIVE);
+}
+/**
+ * Decision-key exact identity: complete decimal number N appears in instruction.
+ * A longer number's digit substring (e.g. 82 inside #582) is not N.
+ */
+export function instructionContainsTicketNumber(instruction, ticketNumber) {
+    if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1)
+        return false;
+    // Complete number token: not preceded or followed by another digit.
+    return new RegExp(`(?<!\\d)${String(ticketNumber)}(?!\\d)`).test(instruction);
+}
+/** Sole stdout shapes: {assertion:"ticket",ticketNumber:N} | {assertion:"true-unbound"}. */
+export function parseDiaristTicketResolverStdout(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new DiaristTicketResolutionError("empty-stdout", "diarist ticket resolver stdout is empty");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (error) {
+        throw new DiaristTicketResolutionError("unparseable-json", "diarist ticket resolver stdout is not JSON", { cause: error });
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new DiaristTicketResolutionError("not-object", "diarist ticket resolver stdout must be one JSON object");
+    }
+    const record = parsed;
+    if (!Object.prototype.hasOwnProperty.call(record, "assertion")) {
+        throw new DiaristTicketResolutionError("assertion-missing", "diarist ticket resolver stdout missing assertion");
+    }
+    if (record.assertion === "true-unbound")
+        return { kind: "true-unbound" };
+    const n = record.ticketNumber;
+    if (record.assertion === "ticket" &&
+        typeof n === "number" &&
+        Number.isSafeInteger(n) &&
+        n >= 1) {
+        return { kind: "ticket", ticketNumber: n };
+    }
+    throw new DiaristTicketResolutionError("assertion-uninterpretable", "diarist ticket resolver assertion is not ticket|true-unbound with safe ticketNumber");
+}
+const HERMES_RESOLVER_TOOLSET = "context_engine";
+/** Hermes resolver: method bytes + instruction only; empty toolset; staged prompt. */
+export function createHermesDiaristTicketResolver(options = {}) {
+    const methodPath = resolveDiaristResolveTicketMethodPath(options.packageRoot);
+    if (!existsSync(methodPath)) {
+        throw new Error(`diarist resolve-ticket method material missing (${methodPath})`);
+    }
+    const method = readFileSync(methodPath, "utf8");
+    if (method.trim().length === 0) {
+        throw new Error(`diarist resolve-ticket method material is empty (${methodPath})`);
+    }
+    const executable = options.executable ?? "hermes";
+    return async (input) => {
+        const argv = [
+            executable,
+            "chat",
+            "--query-file",
+            ENGINE_DETOUR_STAGED_PROMPT_TOKEN,
+            "-Q",
+            "--no-restore-cwd",
+            "--ignore-rules",
+            "-t",
+            HERMES_RESOLVER_TOOLSET,
+        ];
+        let result;
+        try {
+            result = await runEngineDetourOnce({
+                argv,
+                stagedPrompt: JSON.stringify({ method, instruction: input.instruction }),
+                cwd: options.cwd ?? process.cwd(),
+                ...(options.env === undefined ? {} : { env: options.env }),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+        }
+        catch (error) {
+            throw new DiaristTicketResolutionError("engine-failed", "diarist ticket resolver engine failed to launch", { cause: error });
+        }
+        if (result.code !== 0) {
+            throw new DiaristTicketResolutionError("engine-failed", `diarist ticket resolver engine exited ${result.code}: ${result.stderr.slice(0, 500)}`);
+        }
+        return parseDiaristTicketResolverStdout(result.stdout);
+    };
+}
+/** Live ticket check over shared gh issue-body projection. */
+export function createGhTicketExistenceChecker(options) {
+    const runner = options?.runner ?? createGhApiRunner();
+    return async (input) => {
+        const projected = await projectGhIssueBody(runner, {
+            owner: input.owner,
+            repo: input.repo,
+            ticketNumber: input.ticketNumber,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        if (projected.status === "available")
+            return true;
+        if (projected.status === "unavailable"
+            && projected.reason === "http-non-2xx"
+            && projected.httpStatus === 404) {
+            return false;
+        }
+        if (projected.status === "unavailable" && projected.reason === "pull-request") {
+            throw new DiaristTicketResolutionError("ticket-is-pull-request", `ticket #${input.ticketNumber} resolves to a pull request, not an issue`, { cause: projected });
+        }
+        if (projected.status === "unavailable") {
+            throw new DiaristTicketResolutionError("ticket-unavailable", `ticket verification unavailable for ${input.owner}/${input.repo}#${input.ticketNumber}`, { cause: projected });
+        }
+        throw new DiaristTicketResolutionError("ticket-invalid", `ticket verification returned an invalid issue payload for ${input.owner}/${input.repo}#${input.ticketNumber}`, { cause: projected });
+    };
+}
+/** Mechanical verify after LLM assertion. true-unbound passes; ticket needs both checks. */
+export async function verifyDiaristTicketAssertion(input) {
+    if (input.assertion.kind === "true-unbound")
+        return input.assertion;
+    const n = input.assertion.ticketNumber;
+    if (!instructionContainsTicketNumber(input.instruction, n)) {
+        throw new DiaristTicketResolutionError("number-not-in-instruction", `diarist ticket assertion #${n} complete decimal number does not appear in accepted instruction`);
+    }
+    if (input.origin === undefined) {
+        throw new DiaristTicketResolutionError("origin-unresolved", `diarist ticket assertion #${n} requires a resolvable github.com origin remote`);
+    }
+    let exists;
+    try {
+        exists = await input.checkExistence({
+            owner: input.origin.owner,
+            repo: input.origin.repo,
+            ticketNumber: n,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+    }
+    catch (error) {
+        if (error instanceof DiaristTicketResolutionError)
+            throw error;
+        throw new DiaristTicketResolutionError("ticket-unavailable", `diarist ticket assertion #${n} live verification failed`, { cause: error });
+    }
+    if (!exists) {
+        throw new DiaristTicketResolutionError("ticket-missing", `diarist ticket assertion #${n} does not exist as a live issue on ${input.origin.owner}/${input.origin.repo}`);
+    }
+    return input.assertion;
+}
+export async function resolveDiaristTicketFromInstruction(input) {
+    const assertion = await input.resolver({
+        instruction: input.instruction,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    return verifyDiaristTicketAssertion({
+        assertion,
+        instruction: input.instruction,
+        origin: input.origin,
+        checkExistence: input.checkExistence,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+}

package/dist/diarist.js

@@ -0,0 +1,311 @@
+/**
+ * 起居郎 mechanical halves — ADR 0075 `diarist-is-role` / `diarist-collector-is-own-turn`.
+ * Semantic collection is the diarist role's own LLM turn; this module keeps the
+ * mechanical safeguard band only: source enumeration into a frozen catalog, and
+ * the verbatim reverse-verify → idempotent sitian append → watermark commit.
+ * No lifecycle here (ADR 0018): the seat prepares, the role envelope commits.
+ */
+import { readFileSync } from "node:fs";
+import { extractReferencedAdrPaths } from "./adr-path-refs.js";
+import { createGhApiRunner, createGhCollectorGitHubTransport, projectGhIssueBody, } from "./collector-github.js";
+import { blockToLlmEntry, buildDiaristAnchors, mechanicalSafeguardPipeline, readAdrDecisionKeyBlocks, readCcSessionBlocks, readIssueFaceBlocks, } from "./diarist-mechanical.js";
+import { parseGitHubOriginRemote } from "./reviewer-pinned-git.js";
+import { appendIssueSourceFailureDiagnostic, appendQuoteVerifyFailureDiagnostic, appendTicketProvenanceEntry, ensureTicketProvenanceVolume, readOfferedIdentities, readTicketProvenance, recordOfferedIdentities, resolveTicketProvenanceVolume, ticketProvenanceEntryIdentity, writeTicketProvenanceHumanView, } from "./ticket-provenance.js";
+import { readSitianRecords } from "./sitian-facade.js";
+import { execFileSync } from "node:child_process";
+/** Bound-ticket issue source failure — not a soft degrade to empty face. */
+export class DiaristIssueSourceError extends Error {
+    code = "diarist-issue-source";
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = "DiaristIssueSourceError";
+        this.reason = reason;
+    }
+}
+/**
+ * Production issue-face capability over shared gh execution seams.
+ * Body fetch/parse is sole-owned by projectGhIssueBody; this maps hard disposition
+ * (typed DiaristIssueSourceError) instead of Reviewer Spec soft-undefined.
+ * Comment list failures after body success keep true cause under comments-failed.
+ */
+export function createDiaristIssueFaceFetcher(options) {
+    const runner = options?.runner ?? createGhApiRunner();
+    const transport = options?.transport ?? createGhCollectorGitHubTransport();
+    return async (input) => {
+        const projected = await projectGhIssueBody(runner, input);
+        let body;
+        if (projected.status === "available") {
+            body = projected.body;
+        }
+        else if (projected.status === "unavailable") {
+            if (projected.reason === "pull-request") {
+                throw new DiaristIssueSourceError("issue-is-pull-request", `ticket #${input.ticketNumber} resolves to a pull request, not an issue face`, projected.cause === undefined ? undefined : { cause: projected.cause });
+            }
+            throw new DiaristIssueSourceError("issue-unavailable", `issue face unavailable for ${input.owner}/${input.repo}#${input.ticketNumber}`, projected.cause === undefined ? undefined : { cause: projected.cause });
+        }
+        else if (projected.reason === "not-json") {
+            throw new DiaristIssueSourceError("issue-not-json", `issue face payload is not JSON for ${input.owner}/${input.repo}#${input.ticketNumber}`, projected.cause === undefined ? undefined : { cause: projected.cause });
+        }
+        else if (projected.reason === "not-object") {
+            throw new DiaristIssueSourceError("issue-not-object", `issue face payload must be a JSON object for ${input.owner}/${input.repo}#${input.ticketNumber}`);
+        }
+        else {
+            throw new DiaristIssueSourceError("issue-body-invalid", `issue face body must be string or null for ${input.owner}/${input.repo}#${input.ticketNumber}`);
+        }
+        let listed;
+        try {
+            listed = await transport.listIssueComments({
+                owner: input.owner,
+                repo: input.repo,
+                prNumber: input.ticketNumber,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+        }
+        catch (error) {
+            throw new DiaristIssueSourceError("comments-failed", `issue comments fetch failed for ${input.owner}/${input.repo}#${input.ticketNumber}`, { cause: error });
+        }
+        const bodyUrl = `https://github.com/${input.owner}/${input.repo}/issues/${input.ticketNumber}`;
+        return {
+            body,
+            bodyUrl,
+            comments: listed.items.map((c) => ({
+                id: c.id,
+                body: c.body,
+                createdAt: c.createdAt,
+                htmlUrl: c.htmlUrl,
+            })),
+        };
+    };
+}
+/** github.com owner/repo from project origin remote; undefined when absent/non-github. */
+export function resolveDiaristGithubOrigin(projectRoot) {
+    let remoteUrl;
+    try {
+        remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (remoteUrl.length === 0)
+        return undefined;
+    return parseGitHubOriginRemote(remoteUrl);
+}
+/**
+ * Acquire the issue face for a bound ticket. Failures are typed and durable on
+ * the ticket-provenance volume, then propagated — never washed into empty face.
+ */
+export async function loadDiaristIssueFace(input) {
+    const persistAndThrow = (error) => {
+        appendIssueSourceFailureDiagnostic({
+            ticketNumber: input.ticketNumber,
+            cwd: input.projectRoot,
+            ...(input.home === undefined ? {} : { home: input.home }),
+            cause: error.message,
+            reason: error.reason,
+        });
+        return error;
+    };
+    const origin = resolveDiaristGithubOrigin(input.projectRoot);
+    if (origin === undefined) {
+        throw persistAndThrow(new DiaristIssueSourceError("origin-unresolved", `bound ticket #${input.ticketNumber} issue face requires a resolvable github.com origin remote`));
+    }
+    const fetcher = input.fetcher ?? createDiaristIssueFaceFetcher();
+    try {
+        return await fetcher({
+            owner: origin.owner,
+            repo: origin.repo,
+            ticketNumber: input.ticketNumber,
+        });
+    }
+    catch (error) {
+        throw persistAndThrow(error instanceof DiaristIssueSourceError
+            ? error
+            : new DiaristIssueSourceError("issue-unavailable", `issue face fetch failed for ${origin.owner}/${origin.repo}#${input.ticketNumber}`, { cause: error }));
+    }
+}
+/**
+ * Identities already processed for this ticket:
+ * - volume record identities (selected / verify-fail residue)
+ * - offered watermark (blocks shown to the diarist, selected or not)
+ */
+async function loadSeenEntryIdentities(ticketNumber, cwd, home) {
+    const { recordFile } = resolveTicketProvenanceVolume(ticketNumber, cwd, home);
+    const { records } = await readSitianRecords(recordFile);
+    const seen = new Set();
+    for (const record of records) {
+        if (typeof record.identity === "string" && record.identity.length > 0) {
+            seen.add(record.identity);
+        }
+    }
+    for (const identity of readOfferedIdentities(ticketNumber, cwd, home)) {
+        seen.add(identity);
+    }
+    return seen;
+}
+function blockEntryIdentity(ticketNumber, block) {
+    return ticketProvenanceEntryIdentity({
+        ticketNumber,
+        sourceKind: block.sourceKind,
+        sourceRef: block.sourceRef,
+        transcript: block.transcript,
+    });
+}
+/**
+ * Single typed candidate stream: cc sessions + GitHub issue face/comments/decree + referenced ADRs.
+ * Mechanical layer does not prose-filter for relevance (锚定宪法).
+ * Attachments are never merged in as fake issue-body-comment.
+ */
+function loadSourceBlocks(input) {
+    const cwds = input.sessionCwds ?? [input.cwd];
+    const blocks = [...readCcSessionBlocks({ cwds })];
+    if (input.issueFace !== undefined) {
+        blocks.push(...readIssueFaceBlocks({ face: input.issueFace }));
+        const faceText = [
+            input.issueFace.body,
+            ...input.issueFace.comments.map((c) => c.body),
+        ].join("\n");
+        const adrPaths = extractReferencedAdrPaths(faceText);
+        if (adrPaths.length > 0) {
+            blocks.push(...readAdrDecisionKeyBlocks({
+                cwd: input.cwd,
+                adrPaths,
+            }));
+        }
+    }
+    return blocks;
+}
+/**
+ * Mechanical half A — source enumeration into a frozen catalog.
+ * Establishes the per-ticket volume + human view for every bound run (ADR 0075
+ * `ticket-provenance-file` 每票一份起居录), then offers only blocks whose entry
+ * identity is not already on the volume or the offered watermark (增量幂等).
+ */
+export async function prepareDiaristSourceCatalog(input) {
+    ensureTicketProvenanceVolume(input.ticketNumber, input.cwd, input.home);
+    const volume = await readTicketProvenance(input.ticketNumber, input.cwd, input.home);
+    writeTicketProvenanceHumanView({
+        ticketNumber: input.ticketNumber,
+        cwd: input.cwd,
+        ...(input.home === undefined ? {} : { home: input.home }),
+        entries: volume.entries,
+    });
+    const rawBlocks = loadSourceBlocks(input);
+    // Safeguard only (notify filter + dedupe) — never prose-based exclusion.
+    const safeguarded = mechanicalSafeguardPipeline(rawBlocks);
+    const seen = await loadSeenEntryIdentities(input.ticketNumber, input.cwd, input.home);
+    const fresh = safeguarded.filter((block) => !seen.has(blockEntryIdentity(input.ticketNumber, block)));
+    return {
+        ticketNumber: input.ticketNumber,
+        cwd: input.cwd,
+        ...(input.home === undefined ? {} : { home: input.home }),
+        candidates: fresh.map((block, candidateIndex) => ({ ...block, candidateIndex })),
+    };
+}
+export function serializeDiaristSourceCatalog(catalog) {
+    return JSON.stringify(catalog);
+}
+/** Read a frozen catalog written by the seat. Unreadable/malformed fails loudly. */
+export function loadDiaristSourceCatalog(path) {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`diarist source catalog is not an object (${path})`);
+    }
+    const record = parsed;
+    if (typeof record.ticketNumber !== "number" || typeof record.cwd !== "string") {
+        throw new Error(`diarist source catalog is missing ticket coordinates (${path})`);
+    }
+    if (!Array.isArray(record.candidates)) {
+        throw new Error(`diarist source catalog is missing candidates (${path})`);
+    }
+    return parsed;
+}
+/**
+ * Mechanical half B — commit the diarist turn's selections.
+ * Verbatim reverse-verify → idempotent sitian append → watermark → human view.
+ * Verify failure records a single typed diagnostic and drops that selection; it
+ * never bounces the receipt (第 0 条) and never enters the volume as an entry.
+ */
+export async function commitDiaristSelections(input) {
+    const { ticketNumber, cwd } = input.catalog;
+    const homeOpt = input.catalog.home === undefined ? {} : { home: input.catalog.home };
+    const volumePaths = ensureTicketProvenanceVolume(ticketNumber, cwd, input.catalog.home);
+    const anchors = buildDiaristAnchors({ ticketNumber });
+    // Entry-count baseline: sitian entry identity already makes a repeat of an
+    // already-recorded block a no-op append, so the honest `appended` is what the
+    // volume gained — not how many rows survived verify.
+    const before = await readTicketProvenance(ticketNumber, cwd, input.catalog.home);
+    let acceptedRows = 0;
+    let rejectedQuotes = 0;
+    let unknownCandidate = false;
+    for (const selection of input.selections) {
+        const block = input.catalog.candidates[selection.candidateIndex];
+        if (block === undefined) {
+            unknownCandidate = true;
+            continue;
+        }
+        const projected = blockToLlmEntry(block, {
+            anchors,
+            quotes: selection.quotes,
+            ...(selection.note === undefined ? {} : { note: selection.note }),
+        });
+        if (!projected.ok) {
+            rejectedQuotes += 1;
+            // Single diagnostic expression — never a disguised diary entry.
+            appendQuoteVerifyFailureDiagnostic({
+                ticketNumber,
+                cwd,
+                ...homeOpt,
+                cause: projected.cause,
+            });
+            continue;
+        }
+        appendTicketProvenanceEntry({
+            ticketNumber,
+            cwd,
+            ...homeOpt,
+            entry: projected.entry,
+            source: "diarist",
+        });
+        acceptedRows += 1;
+    }
+    // Watermark advances only after the durable volume writes above, so a crash
+    // mid-commit retries the batch on the next summons. Entry identity and
+    // quote-verify diagnostic identity are stable — retry duplicates neither.
+    const identities = input.catalog.candidates.map((block) => blockEntryIdentity(ticketNumber, block));
+    const alreadyWatermarked = readOfferedIdentities(ticketNumber, cwd, input.catalog.home);
+    const watermarked = identities.filter((identity) => !alreadyWatermarked.has(identity)).length;
+    recordOfferedIdentities({ ticketNumber, cwd, ...homeOpt, identities });
+    // Refresh the human view from the full volume (includes prior summons).
+    const volume = await readTicketProvenance(ticketNumber, cwd, input.catalog.home);
+    const humanViewFile = writeTicketProvenanceHumanView({
+        ticketNumber,
+        cwd,
+        ...homeOpt,
+        entries: volume.entries,
+    });
+    return {
+        ticketNumber,
+        offered: input.catalog.candidates.length,
+        appended: volume.entries.length - before.entries.length,
+        rejectedQuotes,
+        watermarked,
+        volumeRecordFile: volumePaths.recordFile,
+        humanViewFile,
+        collectorStatus: input.catalog.candidates.length === 0
+            ? "skipped-no-fresh"
+            : acceptedRows > 0
+                ? "ok"
+                : input.selections.length === 0
+                    ? "empty-selection"
+                    : "nothing-appended",
+        failureCauses: [
+            ...(unknownCandidate ? ["unknown-candidate"] : []),
+            ...(rejectedQuotes > 0 ? ["quote-verify-rejected"] : []),
+        ],
+    };
+}

package/dist/doctor-auditor.js

@@ -0,0 +1,25 @@
+import { auditorRunDirectory } from "./auditor-dossier-tool.js";
+import { runComplianceAudit, } from "./compliance-transport.js";
+import { readDoctorAuditSubjects, requireAuditMaterials, resolveAuditDossier, } from "./dossier-resolution.js";
+export const DOCTOR_AUDIT_TOOL_NAME = "ak_doctor_audit_decision";
+/**
+ * Doctor compliance via public auditor activation (#675 / ADR 0062 / owner r11).
+ * 审刑院 is an independent role; subject=doctor selects souls/doctor-auditor.md.
+ */
+export function createPiDoctorAuditor() {
+    return async (options) => {
+        const dossier = resolveAuditDossier();
+        requireAuditMaterials(dossier);
+        const subjects = readDoctorAuditSubjects(options.context);
+        requireAuditMaterials(subjects);
+        return runComplianceAudit({
+            subject: "doctor",
+            context: options.context,
+            ...(auditorRunDirectory(options.context) === undefined
+                ? {}
+                : { runDirectory: auditorRunDirectory(options.context) }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.summonAuditor === undefined ? {} : { summonAuditor: options.summonAuditor }),
+        });
+    };
+}

package/dist/doctor-contracts.js

@@ -6,6 +6,7 @@ const DOCTOR_EVIDENCE_TOOL_NAME = "ak_doctor_evidence";
 const DOCTOR_OUTPUT_TOOL_NAME = "ak_doctor_output";
 const DOCTOR_ACCEPTED_TEXT = "\u592A\u533B\u7F72\u56DE\u6267\u5DF2\u63A5\u53D7";
 const DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT = "\u592A\u533B\u7F72\u56DE\u6267\u5DF2\u63A5\u53D7\uFF1B\u5BA1\u8BA1\u65E0\u56DE\u6267";
+const DOCTOR_ACCEPTED_AUDIT_UNREADABLE_TEXT = "\u592A\u533B\u7F72\u56DE\u6267\u5DF2\u63A5\u53D7\uFF1B\u5BA1\u8BA1\u5F62\u72B6\u4E0D\u53EF\u8BFB";
 const DOCTOR_OUTPUT_TOOL_DESCRIPTION = "\u63D0\u4EA4\u552F\u4E00\u7EC8\u5C40\u5355\u6848\u8BC1\u8BCD\uFF1Bcompleted \u5141\u8BB8\u7A7A findings\uFF1Bruntime \u8865\u8BB0\u6D3E\u751F\u6210\u672C\u5165\u56DE\u6267\u3002";
 const DOCTOR_TARGET_KINDS = ["law", "gate", "template", "station", "seat"];
 const nonblank = Type.String({ minLength: 1, pattern: "\\S" });
@@ -184,6 +185,7 @@ function validateDoctorOutput(value, patient, store) {
 }
 export {
   DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT,
+  DOCTOR_ACCEPTED_AUDIT_UNREADABLE_TEXT,
   DOCTOR_ACCEPTED_TEXT,
   DOCTOR_EVIDENCE_TOOL_NAME,
   DOCTOR_OUTPUT_TOOL_DESCRIPTION,

package/dist/doctor-evidence.js

@@ -0,0 +1,142 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { sha256Hex } from "./sha256.js";
+import { AcceptedDetailsContractError, acceptedFacts, isTerminatingToolName, validateAcceptedDetails } from "./package-contracts/terminating-tools.js";
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+async function discoverCaseFiles(root) { const found = []; async function walk(dir, depth) { for (const item of await readdir(dir, { withFileTypes: true })) {
+    const path = resolve(dir, item.name);
+    if (item.isDirectory()) {
+        await walk(path, depth + 1);
+    }
+    else if (item.isFile() && (item.name.endsWith(".jsonl") || (item.name === "stderr.log" && depth === 1)))
+        found.push(path);
+} } await walk(root, 0); return found.sort(); }
+function sourceList(count, sources) { return { count, sources: [...new Set(sources)].sort() }; }
+function accumulate(metric, value, source) { metric.count += value; if (value)
+    metric.sources.push(source); }
+function timestamp(row) { return typeof row.timestamp === "string" && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined; }
+function isMissingPathError(error) { return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"); }
+async function stableRunsIdentity(root) { let cursor = root; while (true) {
+    try {
+        const git = await stat(resolve(cursor, ".git"));
+        if (git.isDirectory() || git.isFile())
+            return relative(cursor, root).split(sep).join("/");
+    }
+    catch (error) {
+        if (!isMissingPathError(error))
+            throw error;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor)
+        return root;
+    cursor = parent;
+} }
+function deriveSession(content, id) {
+    const rows = [];
+    const degradationReasons = [];
+    for (const line of content.split("\n"))
+        if (line.trim()) {
+            try {
+                const row = JSON.parse(line);
+                if (!record(row)) {
+                    degradationReasons.push(`non-object session row in ${id}`);
+                    break;
+                }
+                rows.push(row);
+            }
+            catch (error) {
+                if (error instanceof SyntaxError) {
+                    degradationReasons.push(`malformed JSON tail in ${id}: ${error.message}`);
+                    break;
+                }
+                throw error;
+            }
+        }
+    const started = rows.find((row) => row.type === "session");
+    const startedAt = started && timestamp(started);
+    if (!startedAt)
+        degradationReasons.push(`Pi session header is missing: ${id}`);
+    let accepted, observedCommit, turns = 0, calls = 0, tokens = 0;
+    const statuses = [], commits = [];
+    for (const row of rows) {
+        const message = record(row.message) ? row.message : undefined;
+        if (message?.role === "assistant") {
+            for (const part of Array.isArray(message.content) ? message.content : [])
+                if (record(part) && part.type === "toolCall")
+                    calls++;
+            if (typeof message.responseId === "string") {
+                turns++;
+                const usage = record(message.usage) ? message.usage : undefined;
+                if (usage && typeof usage.output === "number")
+                    tokens += usage.output;
+            }
+        }
+        if (message?.role === "toolResult" && message.isError !== true && typeof message.toolName === "string" && isTerminatingToolName(message.toolName) && record(message.details)) {
+            let details;
+            try {
+                details = validateAcceptedDetails(message.toolName, message.details);
+            }
+            catch (error) { // Contract: README.md#Doctor — non-accepted terminating receipts are expected-negative evidence and are skipped; all other validation failures propagate with their cause.
+                if (error instanceof AcceptedDetailsContractError)
+                    continue;
+                throw error;
+            }
+            accepted = row;
+            const facts = acceptedFacts(message.toolName, details);
+            if (facts.commit && facts.commit !== observedCommit) {
+                commits.push({ source: id, commit: facts.commit });
+                observedCommit = facts.commit;
+            }
+            statuses.length = 0;
+            if (facts.status !== undefined) {
+                statuses.push({ source: id, status: facts.status });
+            }
+            else {
+                statuses.push({ source: id, status: "terminating receipt has no receipt-level status" });
+            }
+        }
+    }
+    const acceptedAt = accepted && timestamp(accepted);
+    const final = acceptedAt ? accepted : rows.at(-1);
+    const endedAt = final && timestamp(final);
+    const wall = startedAt && endedAt ? Date.parse(endedAt) - Date.parse(startedAt) : undefined;
+    if (wall !== undefined && wall < 0)
+        degradationReasons.push(`non-monotonic session timestamps in ${id}`);
+    const degradationReason = degradationReasons.length ? degradationReasons.join("; ") : undefined;
+    const complete = !!acceptedAt && !degradationReason && wall !== undefined && wall >= 0;
+    const session = complete
+        ? { source: id, startedAt: startedAt, endedAt: endedAt, wallMilliseconds: wall, completion: "accepted" }
+        : { source: id, ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}), ...(wall !== undefined && wall >= 0 ? { wallMilliseconds: wall } : {}), completion: "incomplete", ...(degradationReason ? { degradationReason } : {}) };
+    return { session, turns, calls, tokens, statuses, commits };
+}
+/** Read Pi's retained session directory as the sole raw material for one case. */
+export async function loadDoctorCase(runsPath) {
+    const root = await realpath(runsPath);
+    const match = root.split(sep).join("/").match(/\/\.ak-roles\/books\/[^/]+\/issues\/([1-9]\d*)\/runs$/);
+    if (!match)
+        throw new Error("Doctor case must be an .ak-roles/books/<book>/issues/<n>/runs directory");
+    const evidence = [], sessions = [], statuses = [], commits = [];
+    const turns = { count: 0, sources: [] }, calls = { count: 0, sources: [] }, tokens = { count: 0, sources: [] };
+    for (const path of await discoverCaseFiles(root)) {
+        const id = relative(root, path).split(sep).join("/");
+        const bytes = await readFile(path);
+        const content = bytes.toString("utf8");
+        const kind = id.endsWith(".jsonl") ? "session" : "stderr";
+        evidence.push({ id, kind, byteLength: bytes.byteLength, contentLength: content.length, sha256: sha256Hex(bytes), content });
+        if (kind === "stderr")
+            continue;
+        const result = deriveSession(content, id);
+        sessions.push(result.session);
+        statuses.push(...result.statuses);
+        commits.push(...result.commits);
+        accumulate(turns, result.turns, id);
+        accumulate(calls, result.calls, id);
+        accumulate(tokens, result.tokens, id);
+    }
+    const runDirs = (await readdir(root, { withFileTypes: true })).filter((item) => item.isDirectory()).map((item) => item.name).sort();
+    const legs = evidence.filter((entry) => entry.kind === "session").map((entry) => entry.id);
+    const retryDirs = runDirs.filter((name) => /(?:^|[-_])retry(?:[-_]|$)/i.test(name));
+    const rawBytes = evidence.filter((entry) => entry.kind === "session").reduce((sum, entry) => sum + entry.byteLength, 0);
+    const cost = { invocations: sourceList(runDirs.length, runDirs), legs: sourceList(legs.length, legs), modelApiTurns: sourceList(turns.count, turns.sources), outputTokens: sourceList(tokens.count, tokens.sources), toolCalls: sourceList(calls.count, calls.sources), retries: { ...sourceList(retryDirs.length, retryDirs), evidence: "literal run-dir naming" }, statuses, commits, sessions, outputBytes: { ...sourceList(rawBytes, legs), payload: "raw JSONL bytes", providerWireBytes: "unavailable" } };
+    return { version: 1, identity: { issueNumber: Number(match[1]), runsPath: await stableRunsIdentity(root) }, evidence, cost };
+}