@unbrained/pm-cli 2026.8.22 → 2026.8.24

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="561c51e0-d7d9-5303-b116-443ad5037943")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8ce8addc-e47e-5bb9-8a94-0959a1a535e9")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -18,10 +18,14 @@ import { NARROW_TOOL_ACTIONS, TOOLS } from "./tool-definitions.js";
 import { normalizeWorkspaceToolArguments, resolveMcpToolAccess, resolveMcpToolSurface, } from "./runtime-capabilities.js";
 import { PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, } from "../sdk/agent-capability-contracts.js";
 import { commitItemMutations } from "../sdk/item-transaction.js";
-import { isRuntimeRecord } from "../sdk/runtime-input.js";
+import { isRuntimeRecord, markMcpMutationTransportInput, } from "../sdk/runtime-input.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
+import { createReproducibleProcessRunner, runWithReproducibleProcessEnvironment, } from "../sdk/reproducibility/process.js";
 import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
 import { resolveAuthor, resolvePmRoot } from "../sdk/runtime-primitives.js";
+function runMcpAction(args) {
+    return runAction(markMcpMutationTransportInput(args));
+}
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
     return fileURLToPath(new URL("../..", import.meta.url));
@@ -96,7 +100,7 @@ function detectUnexpectedTopLevelKeys(toolName, args, toolDeclaredKeys = declare
     return warnings;
 }
 const HANDLERS = {
-    pm_run: (args) => runAction(args),
+    pm_run: (args) => runMcpAction(args),
     pm_mutate: async (args) => {
         const transactionId = readRequiredString(args, "transactionId");
         const controls = parseAtomicMutationControls(args);
@@ -137,7 +141,7 @@ const HANDLERS = {
     },
     ...Object.fromEntries(Object.entries(NARROW_TOOL_ACTIONS).map(([tool, action]) => [
         tool,
-        (args) => runAction({ ...args, action }),
+        (args) => runMcpAction({ ...args, action }),
     ])),
 };
 /** Resolve the pm action a tools/call invocation will dispatch, when knowable. */
@@ -227,17 +231,18 @@ function resultContent(result, warnings, tokenAccounting = false) {
 function errorContent(error) {
     const code = error instanceof PmCliError ? error.exitCode : 1;
     const message = error instanceof Error ? error.message : String(error);
+    const details = error instanceof PmCliError ? error.context : undefined;
     return {
         isError: true,
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ error: message, code }, null, 2),
+                text: JSON.stringify({ error: message, code, details }, null, 2),
             },
         ],
         // Keep `result` present on the error envelope so consumers can read
         // `structuredContent.result` uniformly across success and failure (pm-l40h).
-        structuredContent: { result: null, error: message, code },
+        structuredContent: { result: null, error: message, code, details },
     };
 }
 /** Retain at most 32 own, valid provenance values without cloning unbounded input. */
@@ -351,10 +356,10 @@ async function readWorkspaceResource(uri, params) {
     }
     let value;
     if (uri === "pm://workspace/context") {
-        value = await runAction({ ...args, action: "context", limit: 10 });
+        value = await runMcpAction({ ...args, action: "context", limit: 10 });
     }
     else if (uri === "pm://workspace/claims") {
-        value = await runAction({
+        value = await runMcpAction({
             ...args,
             action: "list",
             status: "in_progress",
@@ -362,7 +367,11 @@ async function readWorkspaceResource(uri, params) {
         });
     }
     else if (uri === "pm://workspace/focus") {
-        value = await runAction({ ...args, action: "focus", subcommand: "show" });
+        value = await runMcpAction({
+            ...args,
+            action: "focus",
+            subcommand: "show",
+        });
     }
     else {
         const guidePath = path.join(cwd, "AGENTS.md");
@@ -403,7 +412,7 @@ function renderWorkflowPrompt(params) {
     };
 }
 /** Implements handle request for the public runtime surface of this module. */
-export async function handleRequest(request) {
+async function handleRequestInReproducibleContext(request) {
     if (!request.id && request.method?.startsWith("notifications/")) {
         return undefined;
     }
@@ -459,19 +468,24 @@ export async function handleRequest(request) {
     }
     throw new PmCliError(`Unsupported MCP method: ${request.method ?? "(missing)"}`, 64);
 }
+/** Dispatch one MCP request under supported process-level reproducibility settings. */
+export async function handleRequest(request) {
+    return runWithReproducibleProcessEnvironment(process.env, () => handleRequestInReproducibleContext(request));
+}
 function writeResponse(id, payload) {
     process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result: payload })}\n`);
 }
 function writeError(id, error) {
     const code = error instanceof PmCliError ? error.exitCode : -32603;
     const message = error instanceof Error ? error.message : String(error);
-    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}\n`);
+    const data = error instanceof PmCliError ? error.context : undefined;
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, data } })}\n`);
 }
 // pm-3puw: parse one JSON-RPC line, dispatch it, and write the response. Kept
 // as a standalone async unit so the stdio loop can enqueue it onto a serial
 // queue (process lines in arrival order) and tests can drive it directly.
 /** Implements process rpc line for the public runtime surface of this module. */
-export async function processRpcLine(line) {
+async function processRpcLineWithHandler(line, requestHandler) {
     if (line.trim().length === 0) {
         return;
     }
@@ -492,7 +506,7 @@ export async function processRpcLine(line) {
     }
     const shouldRespond = Object.prototype.hasOwnProperty.call(request, "id");
     try {
-        const result = await handleRequest(request);
+        const result = await requestHandler(request);
         if (shouldRespond && result !== undefined) {
             writeResponse(request.id, result);
         }
@@ -509,6 +523,10 @@ export async function processRpcLine(line) {
         }
     }
 }
+/** Implements process rpc line for the public runtime surface of this module. */
+export async function processRpcLine(line) {
+    await processRpcLineWithHandler(line, handleRequest);
+}
 /** Implements start mcp server for the public runtime surface of this module. */
 export function startMcpServer() {
     const rl = readline.createInterface({
@@ -520,8 +538,18 @@ export function startMcpServer() {
     // concurrently, so a client that pipelined two mutations on the same item
     // (without awaiting the first response) hit a lock conflict on the second.
     const queue = createSerialQueue();
+    let processLine;
+    try {
+        const runInProcessContext = createReproducibleProcessRunner(process.env);
+        processLine = (line) => runInProcessContext(() => processRpcLineWithHandler(line, handleRequestInReproducibleContext));
+    }
+    catch {
+        // Preserve one typed JSON-RPC error per request when process configuration
+        // is invalid; processRpcLine resolves the same configuration fail-closed.
+        processLine = processRpcLine;
+    }
     rl.on("line", (line) => {
-        void queue.enqueue(() => processRpcLine(line));
+        void queue.enqueue(() => processLine(line));
     });
 }
 // npm bin entries are symlinks (node_modules/.bin/pm-mcp -> dist/mcp/server.js),
@@ -600,7 +628,7 @@ export const _testOnly = {
     get readStringArray() {
         return readRuntimeTestHook("readStringArray");
     },
-    runAction,
+    runAction: runMcpAction,
     get updateManyOptionsFromFlat() {
         return readRuntimeTestHook("updateManyOptionsFromFlat");
     },
@@ -621,4 +649,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=561c51e0-d7d9-5303-b116-443ad5037943
+//# debugId=8ce8addc-e47e-5bb9-8a94-0959a1a535e9

package/dist/sdk/agent/identity-config.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module sdk/agent-identity-config
+ *
+ * Pure and versioned mutation planning for legacy author interpretation. The
+ * public summaries deliberately expose counts and revisions, never alias
+ * spellings, so config discovery is useful without leaking historical names.
+ */
+/** Persisted legacy-author interpretation vocabulary. */
+export interface AgentIdentityVocabulary {
+    /** Monotonic interpretation revision. */
+    version: number;
+    /** Exact legacy author spelling to canonical harness namespace. */
+    aliases: Record<string, string>;
+}
+/** Privacy-safe vocabulary projection used by config get/list/export. */
+export interface AgentIdentityVocabularySummary {
+    /** Current interpretation revision. */
+    version: number;
+    /** Number of exact legacy spellings configured. */
+    alias_count: number;
+}
+/** Supported vocabulary mutations. */
+export type AgentIdentityVocabularyOperation = "add" | "remove" | "clear";
+/** One typed vocabulary mutation and optional residual-coverage census. */
+export interface AgentIdentityVocabularyMutationInput {
+    /** Exact operation applied to the vocabulary. */
+    operation: AgentIdentityVocabularyOperation;
+    /** Exact legacy spelling required by add/remove. */
+    legacy_author?: string;
+    /** Canonical lowercase harness namespace required by add. */
+    canonical_harness?: string;
+    /** Optional bounded author census used only to count still-unmapped values. */
+    observed_authors?: readonly string[];
+}
+/** Privacy-safe dry-run or committed mutation preview. */
+export interface AgentIdentityVocabularyMutationPreview {
+    /** Operation that was evaluated. */
+    operation: AgentIdentityVocabularyOperation;
+    /** Whether persistence would change. */
+    changed: boolean;
+    /** Revision before the operation. */
+    version_before: number;
+    /** Revision after the operation, equal when idempotent. */
+    version_after: number;
+    /** Alias count after the operation. */
+    alias_count: number;
+    /** Unique non-canonical authors not covered after the operation. */
+    residual_author_count: number;
+}
+/** Planned vocabulary plus a privacy-safe result preview. */
+export interface AgentIdentityVocabularyMutationPlan {
+    /** Complete value suitable for settings persistence. */
+    vocabulary: AgentIdentityVocabulary;
+    /** Public mutation result with no alias spellings. */
+    preview: AgentIdentityVocabularyMutationPreview;
+}
+/** Return only the revision and count suitable for config discovery surfaces. */
+export declare function summarizeAgentIdentityVocabulary(vocabulary: AgentIdentityVocabulary | undefined): AgentIdentityVocabularySummary;
+/**
+ * Validate and plan one exact mutation. A real change increments the revision
+ * exactly once; identical adds and absent removes are idempotent.
+ */
+export declare function planAgentIdentityVocabularyMutation(current: AgentIdentityVocabulary | undefined, input: AgentIdentityVocabularyMutationInput): AgentIdentityVocabularyMutationPlan;

package/dist/sdk/agent/identity-config.js

@@ -0,0 +1,107 @@
+/**
+ * @module sdk/agent-identity-config
+ *
+ * Pure and versioned mutation planning for legacy author interpretation. The
+ * public summaries deliberately expose counts and revisions, never alias
+ * spellings, so config discovery is useful without leaking historical names.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="09703f32-9491-5d3a-9f90-f038d9982e17")}catch(e){}}();
+const HARNESS_NAMESPACE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const MAX_AUTHOR_LENGTH = 128;
+const MAX_OBSERVED_AUTHORS = 10_000;
+function requireLegacyAuthor(value) {
+    const author = value?.trim();
+    if (!author || author === "__proto__" || author.length > MAX_AUTHOR_LENGTH) {
+        throw new Error(`A legacy author must contain 1-${MAX_AUTHOR_LENGTH} characters.`);
+    }
+    return author;
+}
+function requireCanonicalHarness(value) {
+    const harness = value?.trim().toLowerCase();
+    if (!harness || !HARNESS_NAMESPACE_PATTERN.test(harness)) {
+        throw new Error("A canonical harness must be a lowercase dash-separated namespace.");
+    }
+    return harness;
+}
+function orderedAliases(aliases) {
+    return Object.fromEntries(Object.entries(aliases).sort(([left], [right]) => left.localeCompare(right)));
+}
+function countResidualAuthors(observed, aliases) {
+    const residual = new Set();
+    for (const raw of (observed ?? []).slice(0, MAX_OBSERVED_AUTHORS)) {
+        const author = raw.trim().slice(0, MAX_AUTHOR_LENGTH);
+        if (author.length === 0 ||
+            author.startsWith("harness:") ||
+            Object.hasOwn(aliases, author)) {
+            continue;
+        }
+        residual.add(author);
+    }
+    return residual.size;
+}
+function applyAddOperation(aliases, input) {
+    const legacyAuthor = requireLegacyAuthor(input.legacy_author);
+    const canonicalHarness = requireCanonicalHarness(input.canonical_harness);
+    if (legacyAuthor === canonicalHarness ||
+        legacyAuthor === `harness:${canonicalHarness}` ||
+        legacyAuthor.startsWith("harness:")) {
+        throw new Error(`The legacy author "${legacyAuthor}" is already canonical and must not be aliased.`);
+    }
+    if (aliases[legacyAuthor] === canonicalHarness)
+        return false;
+    aliases[legacyAuthor] = canonicalHarness;
+    return true;
+}
+function applyVocabularyOperation(aliases, input) {
+    if (input.operation === "add")
+        return applyAddOperation(aliases, input);
+    if (input.operation === "remove") {
+        const legacyAuthor = requireLegacyAuthor(input.legacy_author);
+        if (!Object.hasOwn(aliases, legacyAuthor))
+            return false;
+        delete aliases[legacyAuthor];
+        return true;
+    }
+    if (input.operation === "clear") {
+        const changed = Object.keys(aliases).length > 0;
+        for (const key of Object.keys(aliases))
+            delete aliases[key];
+        return changed;
+    }
+    const exhaustive = input.operation;
+    throw new Error(`Unsupported vocabulary operation: ${String(exhaustive)}`);
+}
+/** Return only the revision and count suitable for config discovery surfaces. */
+export function summarizeAgentIdentityVocabulary(vocabulary) {
+    return {
+        version: vocabulary?.version ?? 1,
+        alias_count: Object.keys(vocabulary?.aliases ?? {}).length,
+    };
+}
+/**
+ * Validate and plan one exact mutation. A real change increments the revision
+ * exactly once; identical adds and absent removes are idempotent.
+ */
+export function planAgentIdentityVocabularyMutation(current, input) {
+    const versionBefore = current?.version ?? 1;
+    const aliases = { ...current?.aliases };
+    const changed = applyVocabularyOperation(aliases, input);
+    const vocabulary = {
+        version: changed ? versionBefore + 1 : versionBefore,
+        aliases: orderedAliases(aliases),
+    };
+    return {
+        vocabulary,
+        preview: {
+            operation: input.operation,
+            changed,
+            version_before: versionBefore,
+            version_after: vocabulary.version,
+            alias_count: Object.keys(vocabulary.aliases).length,
+            residual_author_count: countResidualAuthors(input.observed_authors, vocabulary.aliases),
+        },
+    };
+}
+//# sourceMappingURL=identity-config.js.map
+//# debugId=09703f32-9491-5d3a-9f90-f038d9982e17

package/dist/sdk/agent/refusal-closure-census.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @module sdk/agent/refusal-closure-census
+ *
+ * Joins the complete emitted error vocabulary to every executable refusal
+ * corpus. Missing proof remains an explicit row; no catalog code disappears
+ * merely because it has not yet received a probe.
+ */
+import type { PmErrorCodeContract } from "../error-code-catalog.js";
+import type { PmClosedDomainContract } from "./closed-domain-contracts.js";
+import type { PmGrammarRefusalContract } from "./refusal-corpus-contracts.js";
+/** Evidence family that makes an error code executable. */
+export type PmRefusalEvidenceKind = "owned_state" | "closed_domain" | "grammar";
+/** One complete-catalog closure row. */
+export interface PmRefusalClosureCensusRow {
+    /** Declared machine-readable error code. */
+    code: string;
+    /** Canonical compatibility-group code. */
+    canonical_code: string;
+    /** Whether at least one executable probe reaches the compatibility group. */
+    disposition: "executable" | "uncovered";
+    /** Evidence families contributing executable probes. */
+    evidence_kinds: PmRefusalEvidenceKind[];
+    /** Stable executable probe identities. */
+    probe_ids: string[];
+}
+/** Full emitted-vocabulary refusal closure receipt. */
+export interface PmRefusalClosureCensusReport {
+    /** True only when every catalog code belongs to a probed compatibility group. */
+    ok: boolean;
+    /** Number of emitted codes in the catalog. */
+    catalog_error_code_count: number;
+    /** Number of codes backed by executable evidence. */
+    executable_error_code_count: number;
+    /** Number of codes still lacking executable evidence. */
+    uncovered_error_code_count: number;
+    /** Executable codes divided by all catalog codes. */
+    coverage_fraction: number;
+    /** Number of closed-domain probes joined into the census. */
+    closed_domain_probe_count: number;
+    /** Number of grammar-derived probes joined into the census. */
+    grammar_probe_count: number;
+    /** Stable complete list of codes without executable evidence. */
+    uncovered_error_codes: string[];
+    /** Exactly one row for every catalog code. */
+    rows: PmRefusalClosureCensusRow[];
+}
+/** Reviewed floor of 16 catalog rows; includes one alias across 15 canonical groups. */
+export declare const PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE = 16;
+/** Fifteen canonical compatibility groups that must retain executable evidence. */
+export declare const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE: readonly ["bulk_ids_input_empty", "bulk_ids_input_missing_path", "bulk_ids_input_unreadable", "invalid_argument_value", "missing_lifecycle_target", "missing_required_argument", "projection_options_mutually_exclusive", "tracker_not_initialized", "tracker_root_missing", "tracker_root_not_directory", "tracker_root_unreadable", "unknown_context_intent", "unknown_field_projection", "unknown_option", "unknown_subcommand"];
+/** Ratchet receipt that prevents catalog growth from erasing proven closure. */
+export declare function verifyPmRefusalClosureRatchet(report: PmRefusalClosureCensusReport, baseline?: number): {
+    ok: boolean;
+    baseline: number;
+    actual: number;
+};
+/** Ratchet canonical compatibility-group identities independently from counts. */
+export declare function verifyPmRefusalClosureIdentityRatchet(report: PmRefusalClosureCensusReport, requiredCanonicalCodes?: readonly string[]): {
+    ok: boolean;
+    required_canonical_codes: string[];
+    missing_required_canonical_codes: string[];
+};
+/** Build the complete closure join without silently omitting uncovered codes. */
+export declare function buildPmRefusalClosureCensus(catalog: readonly PmErrorCodeContract[], closedDomains: readonly PmClosedDomainContract[], grammar: readonly PmGrammarRefusalContract[]): PmRefusalClosureCensusReport;
+/** Render the complete census for generated documentation and review evidence. */
+export declare function renderPmRefusalClosureCensusMarkdown(report: PmRefusalClosureCensusReport): string;

package/dist/sdk/agent/refusal-closure-census.js

@@ -0,0 +1,144 @@
+/** Reviewed floor of 16 catalog rows; includes one alias across 15 canonical groups. */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5560aa3a-036e-509c-955c-a09e9bf9df18")}catch(e){}}();
+export const PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE = 16;
+/** Fifteen canonical compatibility groups that must retain executable evidence. */
+export const PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE = Object.freeze([
+    "bulk_ids_input_empty",
+    "bulk_ids_input_missing_path",
+    "bulk_ids_input_unreadable",
+    "invalid_argument_value",
+    "missing_lifecycle_target",
+    "missing_required_argument",
+    "projection_options_mutually_exclusive",
+    "tracker_not_initialized",
+    "tracker_root_missing",
+    "tracker_root_not_directory",
+    "tracker_root_unreadable",
+    "unknown_context_intent",
+    "unknown_field_projection",
+    "unknown_option",
+    "unknown_subcommand",
+]);
+/** Ratchet receipt that prevents catalog growth from erasing proven closure. */
+export function verifyPmRefusalClosureRatchet(report, baseline = PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE) {
+    return {
+        ok: report.executable_error_code_count >= baseline,
+        baseline,
+        actual: report.executable_error_code_count,
+    };
+}
+/** Ratchet canonical compatibility-group identities independently from counts. */
+export function verifyPmRefusalClosureIdentityRatchet(report, requiredCanonicalCodes = PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE) {
+    const executableCanonicalCodes = new Set(report.rows
+        .filter(({ disposition }) => disposition === "executable")
+        .map(({ canonical_code: canonicalCode }) => canonicalCode));
+    const missingRequiredCanonicalCodes = requiredCanonicalCodes.filter((code) => !executableCanonicalCodes.has(code));
+    return {
+        ok: missingRequiredCanonicalCodes.length === 0,
+        required_canonical_codes: [...requiredCanonicalCodes],
+        missing_required_canonical_codes: missingRequiredCanonicalCodes,
+    };
+}
+function evidenceFor(evidence, canonicalCode) {
+    const existing = evidence.get(canonicalCode);
+    if (existing)
+        return existing;
+    const created = {
+        kinds: new Set(),
+        probeIds: new Set(),
+    };
+    evidence.set(canonicalCode, created);
+    return created;
+}
+/** Build the complete closure join without silently omitting uncovered codes. */
+export function buildPmRefusalClosureCensus(catalog, closedDomains, grammar) {
+    const canonicalByCode = new Map(catalog.map((contract) => [
+        contract.code,
+        contract.canonical_code ?? contract.code,
+    ]));
+    const evidence = new Map();
+    let closedDomainProbeCount = 0;
+    let grammarProbeCount = 0;
+    for (const contract of catalog) {
+        const target = evidenceFor(evidence, contract.canonical_code ?? contract.code);
+        for (const state of contract.owned_states ?? []) {
+            target.kinds.add("owned_state");
+            target.probeIds.add(state.probe_id);
+        }
+    }
+    for (const contract of closedDomains) {
+        const canonical = canonicalByCode.get(contract.error_code);
+        if (canonical === undefined)
+            continue;
+        closedDomainProbeCount += 1;
+        const target = evidenceFor(evidence, canonical);
+        target.kinds.add("closed_domain");
+        target.probeIds.add(contract.probe_id);
+    }
+    for (const contract of grammar) {
+        const canonical = canonicalByCode.get(contract.error_code);
+        if (canonical === undefined)
+            continue;
+        grammarProbeCount += 1;
+        const target = evidenceFor(evidence, canonical);
+        target.kinds.add("grammar");
+        target.probeIds.add(contract.probe_id);
+    }
+    const rows = catalog
+        .map((contract) => {
+        const canonicalCode = contract.canonical_code ?? contract.code;
+        const joined = evidence.get(canonicalCode);
+        const probeIds = [...joined.probeIds].sort();
+        return {
+            code: contract.code,
+            canonical_code: canonicalCode,
+            disposition: probeIds.length > 0 ? "executable" : "uncovered",
+            evidence_kinds: [...joined.kinds].sort(),
+            probe_ids: probeIds,
+        };
+    })
+        .sort((left, right) => (left.code < right.code ? -1 : 1));
+    const uncoveredErrorCodes = rows
+        .filter(({ disposition }) => disposition === "uncovered")
+        .map(({ code }) => code);
+    const executableCount = rows.length - uncoveredErrorCodes.length;
+    return {
+        ok: uncoveredErrorCodes.length === 0,
+        catalog_error_code_count: rows.length,
+        executable_error_code_count: executableCount,
+        uncovered_error_code_count: uncoveredErrorCodes.length,
+        coverage_fraction: rows.length === 0 ? 1 : executableCount / rows.length,
+        closed_domain_probe_count: closedDomainProbeCount,
+        grammar_probe_count: grammarProbeCount,
+        uncovered_error_codes: uncoveredErrorCodes,
+        rows,
+    };
+}
+/** Render the complete census for generated documentation and review evidence. */
+export function renderPmRefusalClosureCensusMarkdown(report) {
+    const rows = report.rows.map((row) => `| \`${row.code}\` | \`${row.canonical_code}\` | ${row.disposition} | ${row.evidence_kinds.join(", ") || "none"} | ${row.probe_ids.length} |`);
+    return [
+        "# Generated refusal closure census",
+        "",
+        "Tracker: `pm-f05lsg`.",
+        "",
+        "Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.",
+        "",
+        `- Catalog error codes: ${report.catalog_error_code_count}`,
+        `- Executable error codes: ${report.executable_error_code_count}`,
+        `- Executable-code ratchet floor: ${PM_REFUSAL_CLOSURE_EXECUTABLE_CODE_BASELINE}`,
+        `- Required executable canonical codes: ${PM_REFUSAL_CLOSURE_EXECUTABLE_CANONICAL_CODE_BASELINE.map((code) => `\`${code}\``).join(", ")}`,
+        `- Uncovered error codes: ${report.uncovered_error_code_count}`,
+        `- Coverage fraction: ${report.coverage_fraction.toFixed(6)}`,
+        `- Closed-domain probes: ${report.closed_domain_probe_count}`,
+        `- Grammar probes: ${report.grammar_probe_count}`,
+        "",
+        "| Error code | Canonical code | Disposition | Evidence kinds | Probe count |",
+        "| --- | --- | --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=refusal-closure-census.js.map
+//# debugId=5560aa3a-036e-509c-955c-a09e9bf9df18

package/dist/sdk/agent/refusal-corpus-contracts.d.ts

@@ -0,0 +1,76 @@
+import { type PmCommandPositionalContract } from "../cli-contracts/grammar-contracts.js";
+/** Shared executable shape for a refusal that must not mutate tracker state. */
+export interface PmGrammarRefusalContract {
+    /** Stable probe identity used by ratchets and evidence. */
+    probe_id: string;
+    /** Canonical command path under test. */
+    command: string;
+    /** Exact argv expected to refuse. */
+    refusal_args: readonly string[];
+    /** Exact help argv that must execute successfully after the refusal. */
+    recovery_args: readonly string[];
+    /** Stable problem-envelope code expected from the refusal. */
+    error_code: "invalid_argument_value" | "missing_lifecycle_target" | "missing_required_argument" | "unknown_subcommand";
+}
+/** One required positional omission derived from the grammar declaration. */
+export interface PmRequiredArgumentRefusalContract extends PmGrammarRefusalContract {
+    /** Stable positional name deliberately omitted by the probe. */
+    missing_argument: string;
+    /** Zero-based slot index in the command's declared positional signature. */
+    missing_argument_index: number;
+}
+/** One invalid action probe for a closed positional subcommand family. */
+export interface PmSubcommandRefusalContract extends PmGrammarRefusalContract {
+    /** Invalid action token used to reach the refusal. */
+    rejected_value: string;
+    /** Complete authoritative action domain expected in recovery. */
+    allowed_values: readonly string[];
+}
+/** Runtime evidence for one grammar-derived refusal probe. */
+export interface PmGrammarRefusalObservation {
+    /** Probe identity matching a declared contract. */
+    probe_id: string;
+    /** Machine-readable code emitted by the refusal. */
+    error_code: string;
+    /** Process exit code emitted by the refusal. */
+    exit_code: number;
+    /** Allowed values emitted for a closed action family. */
+    allowed_values: readonly string[];
+    /** Whether the advertised help recovery exited successfully. */
+    recovery_succeeded: boolean;
+    /** Whether any tracker state changed while executing the refusal. */
+    refusal_mutated_state: boolean;
+    /** Repository-relative tracker paths changed by the refusal, when measured. */
+    mutated_paths?: readonly string[];
+}
+/** Stable reason a grammar-derived refusal failed closure. */
+export type PmGrammarRefusalFindingCode = "refusal_allowed_values_mismatch" | "refusal_error_code_mismatch" | "refusal_exit_code_mismatch" | "refusal_mutated_state" | "refusal_probe_missing" | "refusal_recovery_failed" | "unexpected_refusal_probe";
+/** One actionable grammar-derived refusal closure failure. */
+export interface PmGrammarRefusalFinding {
+    /** Stable machine-readable failure category. */
+    code: PmGrammarRefusalFindingCode;
+    /** Probe associated with the finding. */
+    probe_id: string;
+    /** Human-readable failure detail. */
+    detail: string;
+}
+/** Aggregate closure receipt for the grammar-derived refusal corpus. */
+export interface PmGrammarRefusalClosureReport {
+    /** Whether every declared probe refused safely and recovered. */
+    ok: boolean;
+    /** Number of declared probes. */
+    probe_count: number;
+    /** Number of probes without findings. */
+    closed_probe_count: number;
+    /** Stable actionable failures. */
+    findings: PmGrammarRefusalFinding[];
+}
+/**
+ * Return one omission probe for every required slot in the declared grammar.
+ * Earlier positionals receive deterministic, non-mutating placeholder values.
+ */
+export declare function listPmRequiredArgumentRefusalContracts(contracts?: readonly PmCommandPositionalContract[]): PmRequiredArgumentRefusalContract[];
+/** Return one invalid-action probe for every required positional action family. */
+export declare function listPmSubcommandRefusalContracts(contracts?: readonly PmCommandPositionalContract[]): PmSubcommandRefusalContract[];
+/** Score exact code, exit, domain, state-safety, and recovery closure. */
+export declare function scorePmGrammarRefusalClosure(contracts: readonly (PmRequiredArgumentRefusalContract | PmSubcommandRefusalContract)[], observations: readonly PmGrammarRefusalObservation[]): PmGrammarRefusalClosureReport;