@akagilnc/pi-workflow-roles 0.1.1751

package/src/activation-ledger.ts

@@ -0,0 +1,240 @@
+import {
+  constants,
+  closeSync,
+  fstatSync,
+  openSync,
+  writeSync,
+} from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import type { ActivationSessionPointer } from "./activation-ledger-session.ts";
+import {
+  ActivationLedgerError,
+  activationWaitingLedgerPath,
+  assertLedgerFileInsideHome,
+  ensureRealDirectoryTree,
+  errorText,
+} from "./activation-ledger-topology.ts";
+
+/** Private open flags: O_NOFOLLOW closes the lstat→open TOCTOU window. */
+const ACTIVATION_LEDGER_APPEND_OPEN_FLAGS =
+  constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW;
+
+export {
+  ActivationGitRepositoryRequiredError,
+  resolveBookKeyFromGit,
+} from "./activation-ledger-git.ts";
+export {
+  ActivationSessionFileMissingError,
+  durableSessionPointer,
+  type ActivationSessionManager,
+  type ActivationSessionPointer,
+} from "./activation-ledger-session.ts";
+export {
+  ActivationLedgerError,
+  activationBookDirectory,
+  activationWaitingLedgerPath,
+  resolveActivationLedgerHome,
+} from "./activation-ledger-topology.ts";
+
+/** Caller-preassigned correlation id, or an explicit absent identity (never empty string). */
+export type ActivationCorrelationIdentity =
+  | { readonly kind: "caller"; readonly id: string }
+  | { readonly kind: "absent" };
+
+export const ACCEPTED_ACTIVATION_EVENT = "accepted-activation" as const;
+
+/**
+ * Package-owned index-only top-level keys for accepted-activation facts (ADR 0049).
+ * Sole machine key contract: projection and tests consume this descriptor — not prose markers.
+ */
+export const ACCEPTED_ACTIVATION_FACT_KEYS = Object.freeze([
+  "event",
+  "role",
+  "observedAt",
+  "bookKey",
+  "session",
+  "correlation",
+] as const);
+
+export type AcceptedActivationFactKey = (typeof ACCEPTED_ACTIVATION_FACT_KEYS)[number];
+
+/**
+ * Closed activation fact: index fields only (ADR 0049).
+ * No prompt, transcript, argv, excerpt, or other content.
+ */
+export type AcceptedActivationFact = {
+  readonly event: typeof ACCEPTED_ACTIVATION_EVENT;
+  readonly role: string;
+  readonly observedAt: string;
+  readonly bookKey: string;
+  readonly session: ActivationSessionPointer;
+  readonly correlation: ActivationCorrelationIdentity;
+};
+
+// Keys tuple ↔ fact type must stay exact (compile fail on drift; no second field list).
+type ExactKeyMatch<T, K extends PropertyKey> =
+  Exclude<keyof T, K> | Exclude<K, keyof T> extends never ? true : never;
+const _acceptedActivationFactKeysMatch: ExactKeyMatch<
+  AcceptedActivationFact,
+  AcceptedActivationFactKey
+> = true;
+void _acceptedActivationFactKeysMatch;
+
+/** Trusted typed inputs for building the closed fact (canonical fact minus event discriminant). */
+export type AcceptedActivationFactInput = Omit<AcceptedActivationFact, "event">;
+
+/**
+ * Host correlation channel (not a CLI flag): a non-blank AK_CORRELATION_ID carries
+ * the caller id verbatim; missing/blank/whitespace-only yields the typed absent identity.
+ */
+export function correlationIdentityFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ActivationCorrelationIdentity {
+  const raw = env.AK_CORRELATION_ID;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return { kind: "caller", id: raw };
+  }
+  return { kind: "absent" };
+}
+
+/**
+ * Descriptor-driven top-level pick: only ACCEPTED_ACTIVATION_FACT_KEYS leave this boundary.
+ * Nested session/correlation are rebuilt closed before the pick (ADR 0049 zero-content by construction).
+ */
+function projectAcceptedActivationFact(
+  input: AcceptedActivationFactInput,
+): AcceptedActivationFact {
+  const closed: AcceptedActivationFact = {
+    event: ACCEPTED_ACTIVATION_EVENT,
+    role: input.role,
+    observedAt: input.observedAt,
+    bookKey: input.bookKey,
+    session: { kind: "session-file", path: input.session.path },
+    correlation: input.correlation.kind === "caller"
+      ? { kind: "caller", id: input.correlation.id }
+      : { kind: "absent" },
+  };
+  // Descriptor is the sole top-level emission contract (typed pick; no content keys).
+  return Object.fromEntries(
+    ACCEPTED_ACTIVATION_FACT_KEYS.map((key) => [key, closed[key]]),
+  ) as AcceptedActivationFact;
+}
+
+/** Construct the closed fact from trusted typed inputs only (descriptor projection — no content keys). */
+export function buildAcceptedActivationFact(input: AcceptedActivationFactInput): AcceptedActivationFact {
+  return projectAcceptedActivationFact(input);
+}
+
+/** Serialize only the closed index fields (descriptor projection — no content keys). */
+export function serializeAcceptedActivationFact(fact: AcceptedActivationFact): string {
+  return `${JSON.stringify(projectAcceptedActivationFact(fact))}\n`;
+}
+
+/**
+ * Bare O_APPEND write of one complete line under an absolute ledger home.
+ * Private helper: production-bound to writeSync; owns open/write/close honesty only.
+ * Close failure cannot mask open/write; simultaneous close is nested evidence.
+ */
+function appendActivationLedgerLine(
+  ledgerPath: string,
+  line: Uint8Array,
+  options: { ledgerHome: string },
+): void {
+  if (!isAbsolute(options.ledgerHome)) {
+    throw new ActivationLedgerError(
+      `activation ledger home must be absolute: ${options.ledgerHome}`,
+    );
+  }
+  const resolvedLedger = resolve(ledgerPath);
+  const resolvedHome = resolve(options.ledgerHome);
+  const parent = dirname(resolvedLedger);
+  ensureRealDirectoryTree(resolvedHome, parent);
+  assertLedgerFileInsideHome(resolvedLedger, resolvedHome);
+
+  const bytes = Buffer.isBuffer(line) ? line : Buffer.from(line);
+  let ledgerFd: number | undefined;
+  let primaryFailure: unknown;
+  try {
+    try {
+      ledgerFd = openSync(resolvedLedger, ACTIVATION_LEDGER_APPEND_OPEN_FLAGS, 0o644);
+    } catch (error) {
+      // Native ELOOP/filesystem cause retained; no errno dispatch.
+      throw new ActivationLedgerError(
+        `activation ledger failed to open ledger file (${resolvedLedger}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+
+    let opened: ReturnType<typeof fstatSync>;
+    try {
+      opened = fstatSync(ledgerFd);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `activation ledger failed to fstat ledger file (${resolvedLedger}): ${errorText(error)}`,
+        { cause: error },
+      );
+    }
+    if (!opened.isFile()) {
+      throw new ActivationLedgerError(
+        `activation ledger is not a regular file: ${resolvedLedger}`,
+      );
+    }
+
+    const written = writeSync(ledgerFd, bytes, 0, bytes.length, null);
+    if (written !== bytes.length) {
+      throw new ActivationLedgerError(
+        `activation ledger short write: wrote ${written} of ${bytes.length} bytes to ${resolvedLedger}`,
+      );
+    }
+  } catch (error) {
+    primaryFailure = error;
+  }
+
+  if (ledgerFd !== undefined) {
+    try {
+      closeSync(ledgerFd);
+    } catch (closeFailure) {
+      if (primaryFailure !== undefined) {
+        throw new AggregateError(
+          [primaryFailure, closeFailure],
+          "activation ledger operation and close failed",
+          { cause: primaryFailure },
+        );
+      }
+      throw closeFailure;
+    }
+  }
+
+  if (primaryFailure !== undefined) throw primaryFailure;
+}
+
+/**
+ * Append one complete JSONL record with one O_APPEND write of the full record.
+ * Shared-ledger contract: concurrent successful append-only producers cannot
+ * overwrite one another. A short write is an honest infrastructure failure
+ * (ADR 0049) — no non-append rollback/truncate. Close failure cannot mask the
+ * primary write cause; simultaneous close evidence is retained.
+ */
+export function appendAcceptedActivationFact(
+  ledgerPath: string,
+  fact: AcceptedActivationFact,
+  options: { ledgerHome: string },
+): void {
+  appendActivationLedgerLine(
+    ledgerPath,
+    Buffer.from(serializeAcceptedActivationFact(fact), "utf8"),
+    { ledgerHome: options.ledgerHome },
+  );
+}
+
+export function appendAcceptedActivationToBook(options: {
+  ledgerHome: string;
+  fact: AcceptedActivationFact;
+}): void {
+  appendAcceptedActivationFact(
+    activationWaitingLedgerPath(options.ledgerHome, options.fact.bookKey),
+    options.fact,
+    { ledgerHome: options.ledgerHome },
+  );
+}

package/src/activation-reconciliation.ts

@@ -0,0 +1,163 @@
+import type { AcceptedActivationFact } from "./activation-ledger.ts";
+
+/** Event category for pre-dispatch stub facts (#11 producer contract). */
+export const DISPATCH_STUB_EVENT = "dispatch-stub" as const;
+
+/**
+ * Non-content dispatch pointer. Carries process identity or an opaque ref —
+ * never prompt/argv/content bytes (ADR 0049).
+ */
+export type DispatchPointer =
+  | { readonly kind: "process"; readonly pid: number }
+  | { readonly kind: "opaque"; readonly ref: string };
+
+/**
+ * Minimum typed dispatch stub the #11 producer supplies before ignition.
+ * Index-only: correlation, book, time, event category, non-content pointer.
+ */
+export type DispatchStubFact = {
+  readonly event: typeof DISPATCH_STUB_EVENT;
+  readonly observedAt: string;
+  readonly bookKey: string;
+  readonly dispatch: DispatchPointer;
+  readonly correlation: { readonly kind: "caller"; readonly id: string };
+};
+
+/** Trusted typed inputs for building the closed dispatch stub (fact minus event discriminant). */
+export type DispatchStubFactInput = Omit<DispatchStubFact, "event">;
+
+/**
+ * Construct the closed dispatch stub from trusted typed inputs only.
+ * Nested dispatch/correlation are rebuilt closed (ADR 0049 zero-content by construction).
+ */
+export function buildDispatchStubFact(input: DispatchStubFactInput): DispatchStubFact {
+  return {
+    event: DISPATCH_STUB_EVENT,
+    observedAt: input.observedAt,
+    bookKey: input.bookKey,
+    dispatch: input.dispatch.kind === "process"
+      ? { kind: "process", pid: input.dispatch.pid }
+      : { kind: "opaque", ref: input.dispatch.ref },
+    correlation: { kind: "caller", id: input.correlation.id },
+  };
+}
+
+/**
+ * Truthful process liveness supplied by the consumer.
+ * Reconciliation never probes, kills, or retries processes (D1a / #78).
+ */
+export type ProcessLivenessFact =
+  | { readonly state: "alive" }
+  | { readonly state: "terminated" };
+
+/**
+ * One reconciliation subject as an exclusive complete union (four outcomes only):
+ * - activation present → activation required; dispatch/process optional
+ * - activation absent → dispatch + truthful process required; activation prohibited
+ * No session-file existence oracle (ADR 0047). Untyped JS still hits runtime TypeError.
+ */
+export type ReconciliationSubject =
+  | {
+      readonly activation: AcceptedActivationFact;
+      readonly dispatch?: DispatchStubFact;
+      readonly process?: ProcessLivenessFact;
+    }
+  | {
+      readonly activation?: undefined;
+      readonly dispatch: DispatchStubFact;
+      readonly process: ProcessLivenessFact;
+    };
+
+/**
+ * Exactly four typed outcomes (D1a):
+ * - matched — dispatch stub and matching accepted-activation fact
+ * - pending — dispatch present, no activation, process still alive
+ * - ghost — dispatch present, no activation, process terminated
+ * - activation-without-dispatch — activation fact with no matching stub
+ */
+export type ReconciliationOutcome =
+  | {
+      readonly kind: "matched";
+      readonly correlationId: string;
+      readonly bookKey: string;
+    }
+  | {
+      readonly kind: "pending";
+      readonly correlationId: string;
+      readonly bookKey: string;
+    }
+  | {
+      readonly kind: "ghost";
+      readonly correlationId: string;
+      readonly bookKey: string;
+    }
+  | {
+      readonly kind: "activation-without-dispatch";
+      readonly correlationId: string | undefined;
+      readonly bookKey: string;
+    };
+
+function callerCorrelationId(
+  correlation: AcceptedActivationFact["correlation"] | DispatchStubFact["correlation"],
+): string | undefined {
+  return correlation.kind === "caller" ? correlation.id : undefined;
+}
+
+function dispatchMatchesActivation(
+  dispatch: DispatchStubFact,
+  activation: AcceptedActivationFact,
+): boolean {
+  const activationId = callerCorrelationId(activation.correlation);
+  return (
+    activationId !== undefined
+    && activationId === dispatch.correlation.id
+    && activation.bookKey === dispatch.bookKey
+  );
+}
+
+/**
+ * Reconcile one invocation's typed dispatch/activation facts against truthful
+ * process liveness. Pure: never kills, never retries, never reads session files.
+ */
+export function reconcileInvocation(subject: ReconciliationSubject): ReconciliationOutcome {
+  const { dispatch, activation, process } = subject;
+
+  if (activation !== undefined) {
+    if (dispatch !== undefined && dispatchMatchesActivation(dispatch, activation)) {
+      return {
+        kind: "matched",
+        correlationId: dispatch.correlation.id,
+        bookKey: dispatch.bookKey,
+      };
+    }
+    return {
+      kind: "activation-without-dispatch",
+      correlationId: callerCorrelationId(activation.correlation),
+      bookKey: activation.bookKey,
+    };
+  }
+
+  if (dispatch !== undefined) {
+    if (process === undefined) {
+      throw new TypeError(
+        "reconcileInvocation requires process liveness when activation is absent",
+      );
+    }
+    if (process.state === "alive") {
+      return {
+        kind: "pending",
+        correlationId: dispatch.correlation.id,
+        bookKey: dispatch.bookKey,
+      };
+    }
+    return {
+      kind: "ghost",
+      correlationId: dispatch.correlation.id,
+      bookKey: dispatch.bookKey,
+    };
+  }
+
+  throw new TypeError(
+    "reconcileInvocation requires a dispatch stub and/or an accepted-activation fact",
+  );
+}

package/src/activation-trace.ts

@@ -0,0 +1,38 @@
+import { Type, type Static } from "typebox";
+
+const causeSchema = Type.Object({
+  identity: Type.String({ minLength: 1 }),
+  name: Type.String({ minLength: 1 }),
+  message: Type.String(),
+  evidenceId: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+export const activationTraceRecordSchema = Type.Object({
+  role: Type.String({ minLength: 1 }),
+  stageId: Type.String({ pattern: "^[a-z][a-z0-9-]*$" }),
+  status: Type.Literal("failed"),
+  timestamp: Type.String({ format: "date-time" }),
+  cause: causeSchema,
+}, { additionalProperties: false });
+
+export type ActivationTraceRecord = Static<typeof activationTraceRecordSchema>;
+export type ActivationTraceWriter = (record: ActivationTraceRecord) => void;
+
+let activationCauseEvidence = 0;
+const retainedActivationCauses = new Map<string, unknown>();
+export function namedActivationCause(error: unknown): { identity: string; name: string; message: string; evidenceId: string } {
+  const evidenceId = `activation-cause-${++activationCauseEvidence}`;
+  retainedActivationCauses.set(evidenceId, error);
+  if (error instanceof Error) {
+    const code = (error as Error & { code?: unknown }).code;
+    const name = error.name || "Error";
+    return { identity: typeof code === "string" && code.length > 0 ? code : name, name, message: error.message, evidenceId };
+  }
+  let message: string;
+  try {
+    message = typeof error === "string" ? error : JSON.stringify(error) ?? String(error);
+    return { identity: "UnknownThrownCause", name: "UnknownThrownCause", message, evidenceId };
+  } catch {
+    return { identity: "UnknownThrownCause", name: "UnknownThrownCause", message: String(error), evidenceId };
+  }
+}

package/src/audit-escalation.ts

@@ -0,0 +1,177 @@
+import type { Usage } from "@earendil-works/pi-ai";
+
+import type {
+  ComplianceAuditIncomplete,
+  ComplianceDecision,
+} from "./compliance-transport.ts";
+
+export const AUDIT_ESCALATION_KIND = "audit_escalation" as const;
+
+// Live Navigator settlement may consume only the projection produced by this
+// owner. Its private WeakSet cannot be authored by role output; persisted/
+// replayed records are re-authenticated by the retained audit evidence binder.
+const AUDIT_ESCALATION_LIVE_REGISTRY = new WeakSet<object>();
+
+/**
+ * Escalation delivery face.
+ * `kind` / `conflicts` / `auditDecisionGate` are audit-owned fields.
+ * Role-delivered fields ride beside them as open content (ADR 0055) — including
+ * a role `decisionGate` when present. The index signature tells that truth so
+ * callers never need a cast to retain role output.
+ */
+export type AuditEscalationResult = {
+  readonly kind: typeof AUDIT_ESCALATION_KIND;
+  /** Raw audit-owned conflicts field, when the auditor supplied one. */
+  readonly conflicts?: unknown;
+  /** Raw audit-owned gate field, when the auditor supplied one. */
+  readonly auditDecisionGate?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type AuditEscalationToolResult = {
+  content: [{ type: "text"; text: string }];
+  details: AuditEscalationResult;
+  terminate: true;
+  usage?: Usage;
+};
+
+export type AuditIncompleteToolResult = {
+  content: [{ type: "text"; text: string }];
+  details: ComplianceAuditIncomplete;
+  terminate: true;
+  usage?: Usage;
+};
+
+/**
+ * Build the escalation delivery face.
+ * Role-delivered fields ride under the escalation discriminator (ADR 0055).
+ * `kind` always wins so the discriminator cannot be laundered.
+ * `conflicts` and `auditDecisionGate`, when present, always come from the
+ * audit (why we escalated and its gate). Raw ancillary values are not repaired.
+ * A role `decisionGate`, when present, stays at its own key via spread and is
+ * never overwritten (not folded, not dropped, not swapped into the audit home).
+ */
+export function buildAuditEscalationResult(
+  decision: Extract<ComplianceDecision, { status: "escalate" }>,
+  deliveredOutput?: unknown,
+): AuditEscalationResult {
+  const auditOwned: Record<string, unknown> = {
+    kind: AUDIT_ESCALATION_KIND,
+  };
+  if (Object.hasOwn(decision, "conflicts")) {
+    auditOwned.conflicts = decision.conflicts;
+  }
+  if (Object.hasOwn(decision, "decisionGate")) {
+    auditOwned.auditDecisionGate = decision.decisionGate;
+  }
+  const deliveredFields =
+    deliveredOutput !== undefined &&
+    deliveredOutput !== null &&
+    typeof deliveredOutput === "object" &&
+    !Array.isArray(deliveredOutput)
+      ? { ...(deliveredOutput as Record<string, unknown>) }
+      : {};
+  // Role output cannot fill an absent audit-owned field.
+  delete deliveredFields.conflicts;
+  delete deliveredFields.auditDecisionGate;
+  const result = {
+    ...deliveredFields,
+    ...auditOwned,
+  } as AuditEscalationResult;
+  AUDIT_ESCALATION_LIVE_REGISTRY.add(result);
+  return result;
+}
+
+/** True only for the audit-owned live projection, never for role-shaped data. */
+export function isAuditEscalationProjection(
+  value: unknown,
+): value is AuditEscalationResult {
+  if (!isAuditEscalationResult(value)) return false;
+  return AUDIT_ESCALATION_LIVE_REGISTRY.has(value);
+}
+
+function humanDecisionText(result: AuditEscalationResult): string {
+  const lines = ["Human decision required: compliance audit escalation."];
+  if (Array.isArray(result.conflicts)) {
+    lines.push("Conflicts:", ...result.conflicts.map((conflict) => `- ${conflict}`));
+  }
+  const gate = result.auditDecisionGate;
+  if (gate !== null && typeof gate === "object" && !Array.isArray(gate)) {
+    const record = gate as Record<string, unknown>;
+    if (typeof record.question === "string") lines.push(`Question: ${record.question}`);
+    if (Array.isArray(record.options)) {
+      lines.push("Options:", ...record.options.map((option) => `- ${option}`));
+    }
+  }
+  return lines.join("\n");
+}
+
+export function projectAuditEscalation(
+  decision: Extract<ComplianceDecision, { status: "escalate" }>,
+  deliveredOutput?: unknown,
+): AuditEscalationToolResult {
+  const details = buildAuditEscalationResult(decision, deliveredOutput);
+  return {
+    content: [{ type: "text", text: humanDecisionText(details) }],
+    details,
+    terminate: true,
+    ...(decision.usage === undefined ? {} : { usage: decision.usage }),
+  };
+}
+
+export function projectAuditIncomplete(
+  decision: ComplianceAuditIncomplete,
+): AuditIncompleteToolResult {
+  return {
+    content: [{ type: "text", text: "Compliance audit incomplete; no role receipt was formed." }],
+    details: decision,
+    terminate: true,
+    ...(decision.usage === undefined ? {} : { usage: decision.usage }),
+  };
+}
+
+/**
+ * Discriminator-only recognition (ADR 0040). Shape of conflicts/options/gate
+ * is not a reject gate — element types and cardinality are delivery content.
+ */
+export function isAuditEscalationResult(
+  value: unknown,
+): value is AuditEscalationResult {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return (value as Record<string, unknown>).kind === AUDIT_ESCALATION_KIND;
+}
+
+export type ComplianceDecisionHandlers<T> = {
+  pass: (usage: Usage | undefined) => T | PromiseLike<T>;
+  revise: (violations: readonly unknown[]) => T | PromiseLike<T>;
+  escalate: (result: AuditEscalationToolResult) => T | PromiseLike<T>;
+  auditIncomplete?: (result: AuditIncompleteToolResult) => T | PromiseLike<T>;
+};
+
+/**
+ * Dispose a parsed audit decision without repeating status handling in roles.
+ * Role output already delivered is preserved on the escalate face (ADR 0055).
+ */
+export async function disposeComplianceDecision<T>(
+  decision: ComplianceDecision,
+  handlers: ComplianceDecisionHandlers<T>,
+  deliveredOutput?: unknown,
+): Promise<Awaited<T>> {
+  switch (decision.status) {
+    case "pass":
+      return await handlers.pass(decision.usage);
+    case "revise":
+      return await handlers.revise(decision.violations);
+    case "escalate":
+      return await handlers.escalate(
+        projectAuditEscalation(decision, deliveredOutput),
+      );
+    case "audit-incomplete":
+      if (handlers.auditIncomplete === undefined) {
+        throw new Error("Compliance audit-incomplete handler is unavailable");
+      }
+      return await handlers.auditIncomplete(projectAuditIncomplete(decision));
+  }
+}

package/src/auditor-dossier-tool.ts

@@ -0,0 +1,48 @@
+import { dirname, join, resolve } from "node:path";
+
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier" as const;
+
+export type AuditorDossierLocation = {
+  readonly runDirectory: string;
+  readonly admittedRequest: string;
+  readonly parentSessionCandidate: string;
+  readonly attachments: string;
+  readonly artifacts: string;
+};
+
+/** Resolve the exact run binding already carried by the parent record session. */
+export function auditorRunDirectory(context: ExtensionContext): string | undefined {
+  const sessionFile = context.sessionManager?.getSessionFile?.();
+  return sessionFile === undefined ? undefined : resolve(dirname(dirname(sessionFile)));
+}
+
+/** The one shared, run-bound dossier locator exposed to every auditor seat. */
+export function createAuditorDossierTool(runDirectory: string | undefined) {
+  return {
+    name: AUDITOR_DOSSIER_TOOL_NAME,
+    description: "Locate this auditor's bound run dossier and its evidence entry points.",
+    parameters: Type.Object({}, { additionalProperties: false }),
+    async execute(_id: string, _params: unknown): Promise<AgentToolResult<AuditorDossierLocation | undefined>> {
+      if (runDirectory === undefined) {
+        return {
+          content: [{ type: "text", text: "This auditor has no run-bound dossier record." }],
+          details: undefined,
+        };
+      }
+      const details: AuditorDossierLocation = {
+        runDirectory,
+        admittedRequest: join(runDirectory, "admitted-request.json"),
+        parentSessionCandidate: join(runDirectory, "session", "session.jsonl"),
+        attachments: join(runDirectory, "attachments"),
+        artifacts: join(runDirectory, "artifacts"),
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(details) }],
+        details,
+      };
+    },
+  };
+}

package/src/auditor-soul.ts

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+/** Active auditor seats. Fixer LLM auditor retired by #242; souls/fixer-auditor.md retained on disk for possible re-enable. */
+export const AUDITOR_SOUL_ROLES = [
+  "judge",
+  "reviewer",
+  "doctor",
+] as const;
+
+export type AuditorSoulRole = (typeof AUDITOR_SOUL_ROLES)[number];
+
+const auditorSoulPaths: Readonly<Record<AuditorSoulRole, string>> = Object.freeze({
+  judge: fileURLToPath(new URL("../souls/judge-auditor.md", import.meta.url)),
+  reviewer: fileURLToPath(
+    new URL("../souls/reviewer-auditor.md", import.meta.url),
+  ),
+  doctor: fileURLToPath(new URL("../souls/doctor-auditor.md", import.meta.url)),
+});
+
+/** Load one complete auditor Soul afresh for each audit invocation. */
+export async function loadAuditorSoul(role: AuditorSoulRole): Promise<string> {
+  const soul = await readFile(auditorSoulPaths[role], "utf8");
+  if (soul.trim().length === 0) {
+    throw new Error(`The ${role} auditor Soul is blank`);
+  }
+  return soul;
+}