@unbrained/pm-cli 2026.8.10 → 2026.8.11

package/dist/core/session/session-state.js

@@ -4,12 +4,57 @@
  * Maintains lightweight agent session state for contextual workflows.
  */
 
-!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]="611f01b6-0c72-5ea2-a44f-78877c69706c")}catch(e){}}();
-import { promises as fs } from "node:fs";
+!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]="424b9eb3-6b34-5ab0-a3f5-db61fbca12cf")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { existsSync, promises as fs, readFileSync } from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../fs/fs-utils.js";
 import { getRuntimePath } from "../store/paths.js";
 const SESSION_FILENAME = "session.json";
+function isBoundedNonEmptyString(value, maximum) {
+    return (typeof value === "string" && value.length > 0 && value.length <= maximum);
+}
+function parseSemanticAttribution(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    const validRole = ["implementer", "planner", "release-operator"].includes(String(record.role));
+    const validConfidence = ["high", "medium"].includes(String(record.confidence));
+    const validTopic = isBoundedNonEmptyString(record.topic, 256);
+    const validEvidence = Array.isArray(record.evidence) &&
+        record.evidence.length <= 32 &&
+        record.evidence.every((entry) => typeof entry === "string" && entry.length <= 128);
+    const validActiveItems = Array.isArray(record.active_item_ids) &&
+        record.active_item_ids.length <= 64 &&
+        record.active_item_ids.every((entry) => isBoundedNonEmptyString(entry, 128));
+    const validFocus = record.focused_item_id === undefined ||
+        isBoundedNonEmptyString(record.focused_item_id, 128);
+    if (![
+        validRole,
+        validConfidence,
+        validTopic,
+        validEvidence,
+        validActiveItems,
+        validFocus,
+        record.rule_version === "v2",
+    ].every(Boolean)) {
+        return undefined;
+    }
+    return record;
+}
+function parseSemanticAttributionMap(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value)
+        .slice(0, 128)
+        .flatMap(([key, attribution]) => {
+        const parsed = parseSemanticAttribution(attribution);
+        return parsed && key.length <= 128 ? [[key, parsed]] : [];
+    });
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
 /** Implements get session state path for the public runtime surface of this module. */
 export function getSessionStatePath(pmRoot) {
     return path.join(getRuntimePath(pmRoot), SESSION_FILENAME);
@@ -24,11 +69,20 @@ export async function readSessionState(pmRoot) {
             Array.isArray(parsed)) {
             return {};
         }
-        const focused = parsed.focused_item;
+        const record = parsed;
+        const focused = record.focused_item;
+        const semanticAttribution = parseSemanticAttributionMap(record.semantic_attribution);
         if (typeof focused === "string" && focused.trim().length > 0) {
-            return { focused_item: focused };
+            return {
+                focused_item: focused,
+                ...(semanticAttribution
+                    ? { semantic_attribution: semanticAttribution }
+                    : {}),
+            };
         }
-        return {};
+        return semanticAttribution
+            ? { semantic_attribution: semanticAttribution }
+            : {};
     }
     catch {
         return {};
@@ -39,6 +93,153 @@ async function writeSessionState(pmRoot, state) {
     await fs.mkdir(path.dirname(target), { recursive: true });
     await writeFileAtomic(target, JSON.stringify(state));
 }
+/** Derive a non-secret state key from a claim principal. */
+export function semanticAttributionKey(principal) {
+    const instance = /#([a-f0-9]{24})$/u.exec(principal.trim())?.[1];
+    return (instance ??
+        `author-${createHash("sha256").update(principal).digest("hex").slice(0, 24)}`);
+}
+function normalizedEvidence(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))]
+        .slice(0, 32)
+        .map((value) => value.slice(0, 128));
+}
+function worksetTopic(activeItemIds) {
+    const ids = [...new Set(activeItemIds)].sort((left, right) => left.localeCompare(right));
+    if (ids.length === 1)
+        return ids[0];
+    const complete = `workset:${ids.join("+")}`;
+    if (complete.length <= 256)
+        return complete;
+    const visible = ids.join("+").slice(0, 230);
+    return `workset:${visible}+${createHash("sha256").update(ids.join("\0")).digest("hex").slice(0, 12)}`;
+}
+async function updateSemanticAttribution(pmRoot, key, mutate) {
+    const state = await readSessionState(pmRoot);
+    const attributions = { ...state.semantic_attribution };
+    const next = mutate(attributions[key]);
+    if (next === undefined)
+        delete attributions[key];
+    else
+        attributions[key] = next;
+    const nextState = { ...state };
+    if (Object.keys(attributions).length === 0) {
+        delete nextState.semantic_attribution;
+    }
+    else {
+        nextState.semantic_attribution = attributions;
+    }
+    await writeSessionState(pmRoot, nextState);
+}
+/** Record a successful claim as incremental semantic session evidence. */
+export async function recordClaimedWorkAttribution(params) {
+    const key = semanticAttributionKey(params.principal);
+    await updateSemanticAttribution(params.pmRoot, key, (current) => {
+        const activeItemIds = [
+            ...new Set([...(current?.active_item_ids ?? []), params.itemId]),
+        ]
+            .slice(-64)
+            .sort((left, right) => left.localeCompare(right));
+        const focusedItemId = current?.focused_item_id;
+        return {
+            role: "implementer",
+            topic: focusedItemId ?? worksetTopic(activeItemIds),
+            confidence: focusedItemId ? "high" : "medium",
+            rule_version: "v2",
+            evidence: normalizedEvidence([
+                ...activeItemIds.map((id) => `claim:${id}`),
+                ...(focusedItemId ? [`focus:${focusedItemId}`] : []),
+                ...(params.lineageIds ?? []).map((id) => `lineage:${id}`),
+            ]),
+            active_item_ids: activeItemIds,
+            ...(focusedItemId ? { focused_item_id: focusedItemId } : {}),
+        };
+    });
+}
+/** Remove a released item from incremental semantic session evidence. */
+export async function releaseClaimedWorkAttribution(params) {
+    const key = semanticAttributionKey(params.principal);
+    await updateSemanticAttribution(params.pmRoot, key, (current) => {
+        if (!current)
+            return undefined;
+        const activeItemIds = current.active_item_ids.filter((id) => id !== params.itemId);
+        if (activeItemIds.length === 0 && !current.focused_item_id)
+            return undefined;
+        const focusedItemId = current.focused_item_id;
+        return {
+            ...current,
+            role: "release-operator",
+            topic: focusedItemId ?? worksetTopic(activeItemIds),
+            confidence: focusedItemId ? "high" : "medium",
+            evidence: normalizedEvidence([
+                ...activeItemIds.map((id) => `claim:${id}`),
+                ...(focusedItemId ? [`focus:${focusedItemId}`] : []),
+                `release:${params.itemId}`,
+            ]),
+            active_item_ids: activeItemIds,
+        };
+    });
+}
+/** Set or clear focus as the highest-confidence semantic topic. */
+export async function recordFocusedWorkAttribution(params) {
+    const key = semanticAttributionKey(params.principal);
+    await updateSemanticAttribution(params.pmRoot, key, (current) => {
+        const activeItemIds = current?.active_item_ids ?? [];
+        if (!params.itemId && activeItemIds.length === 0)
+            return undefined;
+        const focusedItemId = params.itemId;
+        return {
+            role: focusedItemId ? "planner" : current.role,
+            topic: focusedItemId ?? worksetTopic(activeItemIds),
+            confidence: focusedItemId ? "high" : "medium",
+            rule_version: "v2",
+            evidence: normalizedEvidence([
+                ...activeItemIds.map((id) => `claim:${id}`),
+                ...(focusedItemId ? [`focus:${focusedItemId}`] : []),
+                ...(params.lineageIds ?? []).map((id) => `lineage:${id}`),
+            ]),
+            active_item_ids: activeItemIds,
+            ...(focusedItemId ? { focused_item_id: focusedItemId } : {}),
+        };
+    });
+}
+function resolveAttributionRoot(cwd, env) {
+    const configured = env.PM_PATH?.trim();
+    if (configured) {
+        const resolved = path.resolve(cwd, configured);
+        if (existsSync(path.join(resolved, "settings.json")))
+            return resolved;
+        const nested = path.join(resolved, ".agents", "pm");
+        if (existsSync(path.join(nested, "settings.json")))
+            return nested;
+    }
+    let cursor = path.resolve(cwd);
+    for (let depth = 0; depth < 32; depth += 1) {
+        const candidate = path.join(cursor, ".agents", "pm");
+        if (existsSync(path.join(candidate, "settings.json")))
+            return candidate;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return undefined;
+}
+/** Read one privacy-bounded inferred attribution without making mutations fail. */
+export function readAgentSemanticAttributionSync(params) {
+    if (!params.key)
+        return undefined;
+    const pmRoot = resolveAttributionRoot(params.cwd, params.env);
+    if (!pmRoot)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(getSessionStatePath(pmRoot), "utf8"));
+        return parseSemanticAttribution(parsed.semantic_attribution?.[params.key]);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Implements get focused item for the public runtime surface of this module. */
 export async function getFocusedItem(pmRoot) {
     const state = await readSessionState(pmRoot);
@@ -57,4 +258,4 @@ export async function clearFocusedItem(pmRoot) {
     await writeSessionState(pmRoot, next);
 }
 //# sourceMappingURL=session-state.js.map
-//# debugId=611f01b6-0c72-5ea2-a44f-78877c69706c
+//# debugId=424b9eb3-6b34-5ab0-a3f5-db61fbca12cf

package/dist/core/shared/author.d.ts

@@ -2,7 +2,7 @@ import { type AgentEpisodeIdentity, type AgentSessionContext } from "./agent-ses
 /** Stable provenance categories recorded beside newly appended history authors. */
 export type AuthorSource = "asserted" | "configured" | "detected" | "unknown";
 /** Stable source categories for model observations recorded in mutation history. */
-export type AgentModelSource = "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+export type AgentModelSource = "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
 /** Stable built-in provenance dimensions understood by the default runtime. */
 export declare const AGENT_PROVENANCE_DIMENSIONS: readonly ["model", "effort", "role", "topic", "version"];
 /** Built-in, bounded local resolver names accepted by harness descriptors. */
@@ -13,6 +13,12 @@ export interface AgentProvenanceObservation {
     value: string;
     /** Signal class that supplied the value. */
     source: AgentModelSource;
+    /** Confidence attached to a semantic inference. */
+    confidence?: "high" | "medium" | "low";
+    /** Versioned inference rule when the value was derived. */
+    rule_version?: "v2";
+    /** Bounded item and lineage references supporting an inference. */
+    evidence?: readonly string[];
 }
 /**
  * Extensible provenance dimensions. A null value explicitly means that the

package/dist/core/shared/author.js

@@ -4,13 +4,14 @@
  * Provides shared primitives and utilities for Author.
  */
 
-!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]="6c075a14-1a65-59c7-a9c6-af348e30f821")}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]="e0ab2d6f-0925-540d-8d24-a7f0687b4bf0")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { resolveAgentSessionContextFromSignals, } from "./agent-session-context.js";
+import { readAgentSemanticAttributionSync, } from "../session/session-state.js";
 /** Stable built-in provenance dimensions understood by the default runtime. */
 export const AGENT_PROVENANCE_DIMENSIONS = [
     "model",
@@ -191,15 +192,6 @@ function firstEnvironmentValue(env, keys) {
     return undefined;
 }
 function provenanceFromArgv(argv, dimension) {
-    const flaggedValue = provenanceFlagValue(argv, dimension);
-    if (flaggedValue !== undefined)
-        return flaggedValue;
-    if (dimension === "topic") {
-        return argv
-            .slice(0, 16)
-            .map((token) => token.trim())
-            .find((token) => /^pm-[a-z0-9][a-z0-9-]{2,63}$/u.test(token));
-    }
     if (dimension === "role") {
         const command = argv
             .slice(0, 8)
@@ -347,7 +339,31 @@ function descriptorMatchesSignals(descriptor, env, labels, clientName) {
     const clientMatch = descriptor.client_names.some((name) => clientName === name || literalSignalMatches(clientName, name));
     return environmentMatch || argvMatch || clientMatch;
 }
-function resolveAgentProvenanceObservation(dimension, signals, env, descriptor, sessionContext) {
+function inferredProvenanceObservation(dimension, semanticAttribution) {
+    if (!semanticAttribution)
+        return undefined;
+    let value;
+    if (dimension === "topic")
+        value = semanticAttribution.topic;
+    if (dimension === "role")
+        value = semanticAttribution.role;
+    if (!value)
+        return undefined;
+    return {
+        value,
+        source: "inferred",
+        confidence: semanticAttribution.confidence,
+        rule_version: semanticAttribution.rule_version,
+        evidence: semanticAttribution.evidence,
+    };
+}
+function firstProvenanceObservation(candidates) {
+    const observed = candidates.find(([value]) => value !== undefined);
+    return observed?.[0]
+        ? { value: observed[0], source: observed[1] }
+        : undefined;
+}
+function resolveAgentProvenanceObservation(dimension, signals, env, descriptor, sessionContext, semanticAttribution) {
     const overrideKey = `PM_AGENT_${dimension.toUpperCase().replaceAll("-", "_")}`;
     const hostResolvedDimensions = new Set([
         ...AGENT_PROVENANCE_DIMENSIONS,
@@ -355,9 +371,11 @@ function resolveAgentProvenanceObservation(dimension, signals, env, descriptor,
     ]);
     let overrideValue;
     let argvValue;
+    let argvFlagValue;
     if (hostResolvedDimensions.has(dimension)) {
         overrideValue = normalizeProvenanceValue(dimension, nonBlank(env[overrideKey])?.slice(0, 256));
-        argvValue = provenanceFromArgv(signals.argv ?? [], dimension);
+        argvFlagValue = normalizeProvenanceValue(dimension, provenanceFlagValue(signals.argv ?? [], dimension));
+        argvValue = normalizeProvenanceValue(dimension, provenanceFromArgv(signals.argv ?? [], dimension));
     }
     const environmentKeysByDimension = {
         ...descriptor?.provenance_environment_keys,
@@ -367,31 +385,33 @@ function resolveAgentProvenanceObservation(dimension, signals, env, descriptor,
         ...signals.client_info?.provenance,
         model: signals.client_info?.model,
     };
-    const values = [
-        overrideValue,
-        boundedProvenanceValue(sessionContext?.provenance, dimension),
-        normalizeProvenanceValue(dimension, firstEnvironmentValue(env, environmentKeysByDimension[dimension])),
-        normalizeProvenanceValue(dimension, boundedProvenanceValue(clientProvenance, dimension)),
-        normalizeProvenanceValue(dimension, boundedProvenanceValue(signals.provenance, dimension)),
-        normalizeProvenanceValue(dimension, argvValue),
-        resolveProvenanceProbe(dimension, signals, env, descriptor),
-    ];
-    const sources = [
-        "override",
-        "session",
-        "environment",
-        "mcp_client",
-        "host",
-        "argv",
-        "probe",
-    ];
-    const candidates = sources.map((source, index) => ({
-        value: values[index],
-        source,
-    }));
-    return candidates.find((candidate) => candidate.value !== undefined);
+    const sessionValue = boundedProvenanceValue(sessionContext?.provenance, dimension);
+    const environmentValue = normalizeProvenanceValue(dimension, firstEnvironmentValue(env, environmentKeysByDimension[dimension]));
+    const clientValue = normalizeProvenanceValue(dimension, boundedProvenanceValue(clientProvenance, dimension));
+    const hostValue = normalizeProvenanceValue(dimension, boundedProvenanceValue(signals.provenance, dimension));
+    const probeValue = resolveProvenanceProbe(dimension, signals, env, descriptor);
+    const observed = firstProvenanceObservation([
+        [overrideValue, "override"],
+        [sessionValue, "session"],
+        [argvFlagValue, "argv"],
+        [environmentValue, "environment"],
+        [clientValue, "mcp_client"],
+        [hostValue, "host"],
+        [probeValue, "probe"],
+    ]);
+    return (observed ??
+        inferredProvenanceObservation(dimension, semanticAttribution) ??
+        (argvValue ? { value: argvValue, source: "argv" } : undefined));
+}
+function resolveAgentInstance(harness, session) {
+    if (!harness || !session)
+        return undefined;
+    return createHash("sha256")
+        .update(`pm-agent-instance:v1\0${harness}\0${session}`)
+        .digest("hex")
+        .slice(0, 24);
 }
-function resolveAgentProvenance(signals, env, descriptor, sessionContext) {
+function resolveAgentProvenance(signals, env, descriptor, sessionContext, semanticAttribution) {
     const descriptorDimensions = Object.keys(descriptor?.provenance_environment_keys ?? {});
     const dimensions = new Set([
         ...AGENT_PROVENANCE_DIMENSIONS,
@@ -403,7 +423,7 @@ function resolveAgentProvenance(signals, env, descriptor, sessionContext) {
     ]);
     const observations = {};
     for (const dimension of dimensions) {
-        const observed = resolveAgentProvenanceObservation(dimension, signals, env, descriptor, sessionContext);
+        const observed = resolveAgentProvenanceObservation(dimension, signals, env, descriptor, sessionContext, semanticAttribution);
         if (observed) {
             observations[dimension] = observed;
         }
@@ -495,18 +515,18 @@ export function detectAgentIdentity(signals) {
     const clientName = effectiveSignals.client_info?.name.trim().toLowerCase() ?? "";
     const descriptor = descriptors.find((candidate) => descriptorMatchesSignals(candidate, env, labels, clientName));
     const sessionContext = resolveAgentSessionContextFromSignals(effectiveSignals, env);
-    const provenance = resolveAgentProvenance(effectiveSignals, env, descriptor, sessionContext);
-    const modelCandidate = provenance.model;
     const session = [
         firstEnvironmentValue(env, descriptor?.session_environment_keys),
         nonBlank(effectiveSignals.client_info?.session)?.slice(0, 256),
     ].find((candidate) => candidate !== undefined);
-    const instance = descriptor?.harness && session
-        ? createHash("sha256")
-            .update(`pm-agent-instance:v1\0${descriptor.harness}\0${session}`)
-            .digest("hex")
-            .slice(0, 24)
-        : undefined;
+    const instance = resolveAgentInstance(descriptor?.harness, session);
+    const semanticAttribution = readAgentSemanticAttributionSync({
+        cwd: effectiveSignals.cwd ?? process.cwd(),
+        env,
+        key: instance,
+    });
+    const provenance = resolveAgentProvenance(effectiveSignals, env, descriptor, sessionContext, semanticAttribution);
+    const modelCandidate = provenance.model;
     const entries = [
         ["harness", descriptor?.harness],
         ["model", modelCandidate?.value],
@@ -693,4 +713,4 @@ export function resolveAuthor(candidate, fallback) {
     return identity.author;
 }
 //# sourceMappingURL=author.js.map
-//# debugId=6c075a14-1a65-59c7-a9c6-af348e30f821
+//# debugId=e0ab2d6f-0925-540d-8d24-a7f0687b4bf0

package/dist/core/shared/errors.d.ts

@@ -19,6 +19,14 @@ export interface PmCliErrorRecoveryPayload {
     missing_required_fields?: string[];
     /** Value that configures or reports suggested flags for this contract. */
     suggested_flags?: string[];
+    /** Complete allowed value set for a refused positional or enum token. */
+    allowed_values?: string[];
+    /** Ranked command paths that accept an option rejected on the attempted path. */
+    candidate_commands?: string[];
+    /** Complete number of accepting command paths before the recovery ceiling. */
+    candidate_commands_total?: number;
+    /** Whether additional accepting command paths were omitted from this payload. */
+    candidate_commands_truncated?: boolean;
     /** Value that configures or reports suggested retry for this contract. */
     suggested_retry?: string;
     /** Elapsed time in milliseconds for retry after. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="31191ce6-fb17-5b76-aa3d-3c3773cd85e0")}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]="df6f6758-f972-5bf4-aaa8-b16dd9a247f3")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=31191ce6-fb17-5b76-aa3d-3c3773cd85e0
+//# debugId=df6f6758-f972-5bf4-aaa8-b16dd9a247f3

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module sdk/agent/refusal-reachability
+ *
+ * Verifies real-entrypoint observations against refusal states declared by the
+ * generated public error-code catalog.
+ */
+import type { PmErrorCodeContract, PmErrorCodeClass } from "../error-code-catalog.js";
+/** One recorded result from driving a real public entrypoint into a refusal. */
+export interface PmRefusalProbeObservation {
+    /** Stable probe identifier from the owning error-code contract. */
+    probe_id: string;
+    /** Public command entrypoint exercised by the probe. */
+    entrypoint: string;
+    /** Machine-readable code observed at the transport boundary. */
+    code: string;
+    /** Semantic exit class observed at the transport boundary. */
+    exit_class: PmErrorCodeClass;
+}
+/** One actionable conformance failure. */
+export interface PmRefusalReachabilityFinding {
+    /** Stable finding kind for automation. */
+    kind: "duplicate_probe" | "missing_probe" | "wrong_entrypoint" | "wrong_error_code" | "wrong_exit_class" | "undeclared_probe";
+    /** Probe whose declaration or observation failed. */
+    probe_id: string;
+    /** Human-readable mismatch summary. */
+    detail: string;
+}
+/** Complete refusal-reachability conformance receipt. */
+export interface PmRefusalReachabilityReport {
+    /** Whether every declaration and observation agreed. */
+    ok: boolean;
+    /** Number of declared probes evaluated. */
+    declared_probe_count: number;
+    /** Number of real-entrypoint observations supplied. */
+    observed_probe_count: number;
+    /** Stable, sorted conformance findings. */
+    findings: PmRefusalReachabilityFinding[];
+}
+/** Compare declared refusal states with real-entrypoint observations. */
+export declare function verifyPmRefusalReachability(catalog: readonly PmErrorCodeContract[], observations: readonly PmRefusalProbeObservation[]): PmRefusalReachabilityReport;

package/dist/sdk/agent/refusal-reachability.js

@@ -0,0 +1,72 @@
+/** Compare declared refusal states with real-entrypoint observations. */
+
+!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]="55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c")}catch(e){}}();
+export function verifyPmRefusalReachability(catalog, observations) {
+    const declarations = catalog.flatMap((contract) => (contract.owned_states ?? []).map((state) => ({ contract, state })));
+    const findings = [];
+    const observationsByProbe = new Map();
+    for (const observation of observations) {
+        if (observationsByProbe.has(observation.probe_id)) {
+            findings.push({
+                kind: "duplicate_probe",
+                probe_id: observation.probe_id,
+                detail: `Observation ${observation.probe_id} was supplied more than once.`,
+            });
+            continue;
+        }
+        observationsByProbe.set(observation.probe_id, observation);
+    }
+    const declaredProbeIds = new Set(declarations.map(({ state }) => state.probe_id));
+    for (const { contract, state } of declarations) {
+        const observation = observationsByProbe.get(state.probe_id);
+        if (!observation) {
+            findings.push({
+                kind: "missing_probe",
+                probe_id: state.probe_id,
+                detail: `No entrypoint observation was recorded for ${contract.code}.`,
+            });
+            continue;
+        }
+        if (observation.code !== contract.code) {
+            findings.push({
+                kind: "wrong_error_code",
+                probe_id: state.probe_id,
+                detail: `Expected ${contract.code}; observed ${observation.code}.`,
+            });
+        }
+        if (observation.exit_class !== state.expected_exit_class) {
+            findings.push({
+                kind: "wrong_exit_class",
+                probe_id: state.probe_id,
+                detail: `Expected ${state.expected_exit_class}; observed ${observation.exit_class}.`,
+            });
+        }
+        if (!state.entrypoints.includes(observation.entrypoint)) {
+            findings.push({
+                kind: "wrong_entrypoint",
+                probe_id: state.probe_id,
+                detail: `Expected one of ${state.entrypoints.join(", ")}; observed ${observation.entrypoint}.`,
+            });
+        }
+    }
+    for (const observation of observations) {
+        if (!declaredProbeIds.has(observation.probe_id)) {
+            findings.push({
+                kind: "undeclared_probe",
+                probe_id: observation.probe_id,
+                detail: `Observation ${observation.probe_id} has no catalog declaration.`,
+            });
+        }
+    }
+    findings.sort((left, right) => left.probe_id !== right.probe_id
+        ? left.probe_id.localeCompare(right.probe_id)
+        : left.kind.localeCompare(right.kind));
+    return {
+        ok: findings.length === 0,
+        declared_probe_count: declarations.length,
+        observed_probe_count: observations.length,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-reachability.js.map
+//# debugId=55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c

package/dist/sdk/agent/subcommand-recovery.d.ts

@@ -0,0 +1,40 @@
+import { PmCliError, type PmCliErrorRecoveryPayload } from "../../core/shared/errors.js";
+/** Catalog-only alias retained for consumers of the former package lifecycle code. */
+export declare const UNKNOWN_SUBCOMMAND_COMPATIBILITY_CODES: readonly [{
+    readonly code: "unknown_lifecycle_action";
+}];
+/** Inputs for constructing a portable unknown-subcommand refusal. */
+export interface UnknownSubcommandErrorOptions {
+    /** Command family path without the rejected token. */
+    command_path: string;
+    /** Rejected positional token. */
+    token: string;
+    /** Complete declared subcommand vocabulary for the family. */
+    allowed: readonly string[];
+    /** Human-readable command family, defaulting to `pm <command_path>`. */
+    display_name?: string;
+    /** Positional token role used in the compatibility message. */
+    token_kind?: "subcommand" | "action" | "path";
+    /** Arguments that follow the rejected token and should survive a retry. */
+    trailing_args?: readonly string[];
+    /** Family-aware retry that takes precedence over edit-distance recovery. */
+    retry_command?: string;
+    /** Compatibility suffix appended after the allowed-value sentence. */
+    message_suffix?: string;
+    /** Additional ranked recovery candidates supplied by the command family. */
+    fallback_candidates?: PmCliErrorRecoveryPayload["fallback_candidates"];
+    /** Transport exit used by non-CLI protocol adapters. */
+    exit_code?: number;
+    /** Additional family-specific examples. */
+    examples?: readonly string[];
+}
+declare function nearestSubcommand(token: string, allowed: readonly string[]): string | undefined;
+declare function renderCommand(tokens: readonly string[]): string;
+/** Build the shared typed refusal used by CLI, SDK, MCP, and packages. */
+export declare function createUnknownSubcommandError(options: UnknownSubcommandErrorOptions): PmCliError;
+/** Test-only access to deterministic nearest-match behavior. */
+export declare const _testOnly: {
+    nearestSubcommand: typeof nearestSubcommand;
+    renderCommand: typeof renderCommand;
+};
+export {};