@unbrained/pm-cli 2026.8.10 → 2026.8.12

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/command-types.d.ts

@@ -29,6 +29,8 @@ export interface GlobalOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Include the machine-readable row selector and TOON encoding contract. */
+    outputRowContract?: boolean;
     /** Filesystem path used for path resolution. */
     path?: string;
     /** Value that configures or reports no extensions for this contract. */

package/dist/core/shared/command-types.js

@@ -1,5 +1,5 @@
 
-!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]="ff47df0c-93db-5e20-be4e-48a2aedfeebf")}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]="044af354-3047-5fd4-ae65-458a259dedca")}catch(e){}}();
 export {};
 //# sourceMappingURL=command-types.js.map
-//# debugId=ff47df0c-93db-5e20-be4e-48a2aedfeebf
+//# debugId=044af354-3047-5fd4-ae65-458a259dedca

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

@@ -11,6 +11,11 @@ export interface PmCliErrorRecoveryPayload {
     attempted_command?: string;
     /** Value that configures or reports normalized args for this contract. */
     normalized_args?: string[];
+    /** Positional tokens paired with their parser roles for unambiguous recovery. */
+    parsed_positionals?: Array<{
+        role: string;
+        value: string;
+    }>;
     /** Value that configures or reports provided fields for this contract. */
     provided_fields?: string[];
     /** Value that configures or reports missing for this contract. */
@@ -19,6 +24,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]="62fb0ba7-643f-5b33-870b-df875559610a")}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=62fb0ba7-643f-5b33-870b-df875559610a

package/dist/core/store/item-metadata-cache.d.ts

@@ -83,7 +83,7 @@ export interface ListCacheOptions {
     includeBody?: boolean;
     /** When false, heavy collection fields (comments/notes/learnings/files/tests/ test_runs/docs) are neither loaded from nor written to the separate collections cache, and are absent from the returned metadata. Light-only callers (`pm list` compact, stats, deps, activity, calendar, close) skip the large collections cache entirely. Defaults to true so any caller that does read those fields stays correct. */
     includeCollections?: boolean;
-    /** Force canonical item enumeration and stat validation even when a fresh derived index is available. Validation, repair, migration, and equivalence tests use this correctness path. */
+    /** Force canonical item enumeration and authoritative file reads even when stat-matched cache tiers or a fresh derived index are available. Validation, repair, migration, and equivalence tests use this correctness path. */
     forceSourceScan?: boolean;
     /** Minimum item count required before the directory-signature derived-index fast path is used. Defaults to 500 so small workspaces preserve per-file external-edit detection; tests and specialized SDK hosts may lower it explicitly. */
     derivedIndexMinimumItems?: number;

package/dist/core/store/item-metadata-cache.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for the item metadata cache.
  */
 
-!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]="8ed70856-9cba-599d-8b53-21a981af1f40")}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]="58d1ab81-16b6-5c93-ade4-ba189ea48c9b")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -257,7 +257,8 @@ async function loadBodyCache(pmRoot, contextFingerprint) {
     };
     const cachePath = getBodyCachePath(pmRoot);
     const active = await loadEnvelopeMemoized(cachePath, parse);
-    return contextFingerprint && active?.context_fingerprint !== contextFingerprint
+    return contextFingerprint &&
+        active?.context_fingerprint !== contextFingerprint
         ? await loadEnvelopeMemoized(getContextCachePath(cachePath, contextFingerprint), parse)
         : active;
 }
@@ -274,7 +275,8 @@ async function loadCollectionsCache(pmRoot, contextFingerprint) {
     };
     const cachePath = getCollectionsCachePath(pmRoot);
     const active = await loadEnvelopeMemoized(cachePath, parse);
-    return contextFingerprint && active?.context_fingerprint !== contextFingerprint
+    return contextFingerprint &&
+        active?.context_fingerprint !== contextFingerprint
         ? await loadEnvelopeMemoized(getContextCachePath(cachePath, contextFingerprint), parse)
         : active;
 }
@@ -518,12 +520,16 @@ async function readCachedDocumentParts(filePath, relativePath, context) {
     const itemFormat = getItemFormatFromPath(filePath);
     await dispatchCachedDocumentReadHooks(filePath, context.warnings, context.dispatchReadHooks);
     const cachedEntry = context.previousEntries[relativePath];
-    const metadataCached = cachedEntry !== undefined &&
+    const metadataCached = !context.forceSourceRead &&
+        cachedEntry !== undefined &&
         statMatches(cachedEntry, mtimeMs, ctimeMs, size);
     const cachedBody = context.previousBodies[relativePath];
-    const bodyCached = cachedBody !== undefined && statMatches(cachedBody, mtimeMs, ctimeMs, size);
+    const bodyCached = !context.forceSourceRead &&
+        cachedBody !== undefined &&
+        statMatches(cachedBody, mtimeMs, ctimeMs, size);
     const cachedCollections = context.previousCollections[relativePath];
-    const collectionsCached = cachedCollections !== undefined &&
+    const collectionsCached = !context.forceSourceRead &&
+        cachedCollections !== undefined &&
         statMatches(cachedCollections, mtimeMs, ctimeMs, size);
     const needRead = !metadataCached ||
         (context.includeBody && !bodyCached) ||
@@ -1028,6 +1034,7 @@ export async function listAllDocumentCandidatesCached(pmRoot, preferredFormat, t
         extensionFieldNames,
         includeBody,
         includeCollections,
+        forceSourceRead: options.forceSourceScan === true,
         dispatchReadHooks,
         previousEntries,
         previousBodies,
@@ -1107,4 +1114,4 @@ export async function listAllDocumentsCachedLight(pmRoot, preferredFormat, typeT
     }));
 }
 //# sourceMappingURL=item-metadata-cache.js.map
-//# debugId=8ed70856-9cba-599d-8b53-21a981af1f40
+//# debugId=58d1ab81-16b6-5c93-ade4-ba189ea48c9b

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;