@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/dist/core/history/replay.js

@@ -4,13 +4,13 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!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]="c8668470-7e57-5dee-8e41-298e7c697b77")}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]="a1283470-00c7-5e91-8676-e1c1a667537f")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
 import { toItemRecord } from "../item/item-record.js";
 import { orderObject, sha256Hex, stableStringify, } from "../shared/serialization.js";
-import { hashDocument } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentForVersion, } from "./history.js";
 /** Public contract for empty replay document, shared by SDK and presentation-layer consumers. */
 export const EMPTY_REPLAY_DOCUMENT = {
     metadata: {},
@@ -21,11 +21,11 @@ export function cloneEmptyReplayDocument() {
     return structuredClone(EMPTY_REPLAY_DOCUMENT);
 }
 /** Implements replay hash for the public runtime surface of this module. */
-export function replayHash(document) {
+export function replayHash(document, version = CURRENT_HISTORY_ITEM_HASH_VERSION) {
     if (Object.keys(document.metadata).length === 0 ||
         Array.isArray(document.metadata.tags)) {
         try {
-            return hashDocument(replayToItemDocument(document));
+            return hashDocumentForVersion(replayToItemDocument(document), version);
         }
         catch {
             // Fall through when another malformed legacy field cannot be canonicalized.
@@ -124,14 +124,20 @@ export function tryApplyReplayPatch(current, patch) {
     }
 }
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
-export function verifyHistoryChain(entries) {
+/** Verify a chain and report the explicit or auto-detected item hash epoch. */
+export function verifyHistoryChainWithVersion(entries) {
     let replay = cloneEmptyReplayDocument();
+    let detectedVersion;
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        if (replayHash(replay) !== entry.before_hash) {
+        const explicitVersion = entry.item_hash_version;
+        if (explicitVersion !== undefined &&
+            !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(explicitVersion)) {
             return {
                 ok: false,
-                errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],
+                errors: [
+                    `verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`,
+                ],
             };
         }
         const applied = tryApplyReplayPatch(replay, entry.patch);
@@ -141,15 +147,38 @@ export function verifyHistoryChain(entries) {
                 errors: [`verify_failed:patch_apply_failed:entry_${index + 1}`],
             };
         }
-        replay = applied.document;
-        if (replayHash(replay) !== entry.after_hash) {
+        const candidates = explicitVersion === undefined
+            ? [CURRENT_HISTORY_ITEM_HASH_VERSION, 1]
+            : [explicitVersion];
+        const beforeMatches = candidates.filter((version) => replayHash(replay, version) === entry.before_hash);
+        if (beforeMatches.length === 0) {
+            return {
+                ok: false,
+                errors: [`verify_failed:before_hash_mismatch:entry_${index + 1}`],
+            };
+        }
+        const version = beforeMatches.find((candidate) => replayHash(applied.document, candidate) === entry.after_hash);
+        if (version === undefined) {
             return {
                 ok: false,
                 errors: [`verify_failed:after_hash_mismatch:entry_${index + 1}`],
             };
         }
+        replay = applied.document;
+        detectedVersion = version;
     }
-    return { ok: true, errors: [] };
+    return {
+        ok: true,
+        errors: [],
+        ...(detectedVersion === undefined
+            ? {}
+            : { item_hash_version: detectedVersion }),
+    };
+}
+/** Deterministically verify a history chain while preserving the legacy result shape. */
+export function verifyHistoryChain(entries) {
+    const result = verifyHistoryChainWithVersion(entries);
+    return { ok: result.ok, errors: result.errors };
 }
 function tryApplySingleOp(document, op) {
     try {
@@ -192,6 +221,11 @@ export function lenientApplyReplayPatch(current, patch) {
 }
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
 export function reanchorHistoryEntries(entries) {
+    const unsupportedIndex = entries.findIndex((entry) => entry.item_hash_version !== undefined &&
+        !SUPPORTED_HISTORY_ITEM_HASH_VERSIONS.includes(entry.item_hash_version));
+    if (unsupportedIndex >= 0) {
+        throw new TypeError(`unsupported_item_hash_version:${String(entries[unsupportedIndex]?.item_hash_version)}:entry_${unsupportedIndex + 1}`);
+    }
     let replay = cloneEmptyReplayDocument();
     const rewritten = [];
     const details = [];
@@ -201,7 +235,7 @@ export function reanchorHistoryEntries(entries) {
     let skippedOps = 0;
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const beforeHash = replayHash(replay);
+        const beforeHash = replayHash(replay, CURRENT_HISTORY_ITEM_HASH_VERSION);
         const strict = tryApplyReplayPatch(replay, entry.patch);
         let next;
         let outPatch;
@@ -223,7 +257,7 @@ export function reanchorHistoryEntries(entries) {
             skippedOps += entrySkipped;
             entriesPatchRepaired += 1;
         }
-        const afterHash = replayHash(next);
+        const afterHash = replayHash(next, CURRENT_HISTORY_ITEM_HASH_VERSION);
         const rehashed = beforeHash !== entry.before_hash || afterHash !== entry.after_hash;
         if (rehashed) {
             entriesRehashed += 1;
@@ -233,6 +267,7 @@ export function reanchorHistoryEntries(entries) {
             patch: outPatch,
             before_hash: beforeHash,
             after_hash: afterHash,
+            item_hash_version: CURRENT_HISTORY_ITEM_HASH_VERSION,
         });
         details.push({
             index: index + 1,
@@ -261,4 +296,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=c8668470-7e57-5dee-8e41-298e7c697b77
+//# debugId=a1283470-00c7-5e91-8676-e1c1a667537f

package/dist/core/lock/lock-gc.js

@@ -9,7 +9,8 @@
  * Zero ttl means any lock older than 0 ms is stale. Negative ttl means always stale.
  */
 
-!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]="a026943f-1a46-526b-bfaa-435025c65c2a")}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]="79f9ccbd-48d1-5eb3-82ae-3dd62427041c")}catch(e){}}();
+import { isFileMissingError } from "../fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 function parseLock(raw) {
@@ -34,12 +35,6 @@ function parseLock(raw) {
     }
     return { id, owner, created_at, ttl_seconds };
 }
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 /** Pure classification of one lock file's raw content against `nowMs`. This is the single staleness/parse policy shared by `pm gc --scope locks` (which acts on it) and the `pm health` locks check (which only reports it). */
 export function classifyLockContent(file, raw, nowMs) {
     const lock = parseLock(raw);
@@ -108,7 +103,7 @@ export async function scanLockHealth(pmRoot, now) {
         dirEntries = rawDir.filter((f) => f.endsWith(".lock")).sort();
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return scan;
         }
         throw error;
@@ -119,7 +114,7 @@ export async function scanLockHealth(pmRoot, now) {
             raw = await fs.readFile(path.join(locksDir, file), "utf8");
         }
         catch (readError) {
-            if (isErrno(readError, "ENOENT")) {
+            if (isFileMissingError(readError)) {
                 // Disappeared between readdir and readFile — treat as a ghost; skip quietly.
                 continue;
             }
@@ -159,7 +154,7 @@ export async function runLockGc(pmRoot, options) {
         dirEntries = raw.filter((f) => f.endsWith(".lock")).sort();
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return result;
         }
         throw error;
@@ -179,7 +174,7 @@ export async function runLockGc(pmRoot, options) {
             raw = await fs.readFile(absPath, "utf8");
         }
         catch (readError) {
-            if (isErrno(readError, "ENOENT")) {
+            if (isFileMissingError(readError)) {
                 // Disappeared between readdir and readFile — treat as a ghost; skip quietly.
                 result.scanned -= 1;
                 continue;
@@ -223,7 +218,7 @@ export async function runLockGc(pmRoot, options) {
                 await fs.unlink(absPath);
             }
             catch (unlinkError) {
-                if (!isErrno(unlinkError, "ENOENT")) {
+                if (!isFileMissingError(unlinkError)) {
                     result.warnings.push(`lock_remove_failed:${file}`);
                     result.retained.push(relPath);
                     result.entries.push(classified.entry);
@@ -243,4 +238,4 @@ export async function runLockGc(pmRoot, options) {
     return result;
 }
 //# sourceMappingURL=lock-gc.js.map
-//# debugId=a026943f-1a46-526b-bfaa-435025c65c2a
+//# debugId=79f9ccbd-48d1-5eb3-82ae-3dd62427041c

package/dist/core/lock/lock.js

@@ -4,7 +4,8 @@
  * Coordinates tracker lock ownership and cleanup for Lock.
  */
 
-!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]="c638b65d-148a-5b42-8f24-d6fa9d5ac7d3")}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]="a9ad8a9f-de6e-5bce-8685-844f1129d5fb")}catch(e){}}();
+import { isFileMissingError } from "../fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -70,7 +71,7 @@ async function readLockInfo(lockPath) {
         return parseLockInfo(raw);
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return {
                 info: null,
                 warnings: [],
@@ -294,7 +295,7 @@ async function removeExpiredStaleCleanupGate(gatePath) {
         }
     }
     catch (error) {
-        return isErrno(error, "ENOENT");
+        return isFileMissingError(error);
     }
     const owner = await readStaleCleanupGateOwner(gatePath);
     if (owner !== null &&
@@ -446,4 +447,4 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
     }
 }
 //# sourceMappingURL=lock.js.map
-//# debugId=c638b65d-148a-5b42-8f24-d6fa9d5ac7d3
+//# debugId=a9ad8a9f-de6e-5bce-8685-844f1129d5fb

package/dist/core/output/output.d.ts

@@ -24,6 +24,8 @@ export interface OutputOptions {
     outputFormat?: "toon" | "json";
     /** Caller-carried cross-call budget and served-item state. */
     outputSession?: string;
+    /** Include machine-readable row location and row-encoding metadata. */
+    outputRowContract?: boolean;
     /** Fallback output format used when callers do not provide an override. */
     defaultOutputFormat?: "toon" | "json";
     /** Value that configures or reports command for this contract. */

package/dist/core/output/output.js

@@ -4,7 +4,7 @@
  * Formats compact human and machine output for Output.
  */
 
-!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]="b52d2756-f640-5f53-981f-05fa23fa1718")}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]="5aaf8b90-5b95-5102-9ea4-b877c696d593")}catch(e){}}();
 import { getActiveCommandContext, runActiveCommandOverride, runActiveRendererOverride, runActiveServiceOverrideSync, setActiveCommandResult, } from "../extensions/index.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { isHostOutputSuppressed } from "./output-control.js";
@@ -12,6 +12,7 @@ import { projectMutationResult } from "./mutation-projection.js";
 import { attachReadOutputContracts } from "../../sdk/context-intent-contracts.js";
 import { attachOutputTokenAccounting } from "../../sdk/output-token-accounting.js";
 import { resolveReadOutputEncoding } from "../../sdk/read-output-contracts.js";
+import { encode as encodeToon } from "@toon-format/toon";
 const DECLARED_PROCESS_EXIT_CODES = new Set(Object.values(EXIT_CODE));
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
 let streamErrorHandlersInstalled = false;
@@ -114,6 +115,44 @@ function renderScalar(value) {
         return "null";
     return JSON.stringify(value);
 }
+function isToonPrimitive(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+function tabularObjectArray(value) {
+    if (value.length === 0 || !value.every(isPlainObject))
+        return false;
+    const keys = Object.keys(value[0]);
+    return (keys.length > 0 &&
+        value.every((entry) => Object.keys(entry).length === keys.length &&
+            keys.every((key) => Object.hasOwn(entry, key) && isToonPrimitive(entry[key]))));
+}
+function indentToon(encoded, depth) {
+    const indent = "  ".repeat(depth);
+    return encoded
+        .split("\n")
+        .map((line) => `${indent}${line}`)
+        .join("\n");
+}
+/** Render one object field while preserving nested and tabular TOON structure. */
+function renderToonObjectEntry(key, entry, depth) {
+    const indent = "  ".repeat(depth);
+    if (!isPlainObject(entry) && !Array.isArray(entry)) {
+        return `${indent}${key}: ${renderScalar(entry)}`;
+    }
+    if (Array.isArray(entry) && entry.length === 0) {
+        return `${indent}${key}: []`;
+    }
+    if (Array.isArray(entry) && tabularObjectArray(entry)) {
+        return indentToon(encodeToon({ [key]: entry }), depth);
+    }
+    if (isPlainObject(entry) && Object.keys(entry).length === 0) {
+        return `${indent}${key}: {}`;
+    }
+    return `${indent}${key}:\n${renderToonValue(entry, depth + 1)}`;
+}
 function compactToonValue(value) {
     if (value === null || value === undefined) {
         return undefined;
@@ -147,6 +186,9 @@ function renderToonValue(value, depth) {
     if (Array.isArray(value)) {
         if (value.length === 0)
             return "[]";
+        if (tabularObjectArray(value)) {
+            return indentToon(encodeToon(value), depth);
+        }
         return value
             .map((entry) => {
             if (!isPlainObject(entry) && !Array.isArray(entry)) {
@@ -167,18 +209,7 @@ function renderToonValue(value, depth) {
         if (entries.length === 0)
             return "{}";
         return entries
-            .map(([key, entry]) => {
-            if (!isPlainObject(entry) && !Array.isArray(entry)) {
-                return `${indent}${key}: ${renderScalar(entry)}`;
-            }
-            if (Array.isArray(entry) && entry.length === 0) {
-                return `${indent}${key}: []`;
-            }
-            if (isPlainObject(entry) && Object.keys(entry).length === 0) {
-                return `${indent}${key}: {}`;
-            }
-            return `${indent}${key}:\n${renderToonValue(entry, depth + 1)}`;
-        })
+            .map(([key, entry]) => renderToonObjectEntry(key, entry, depth))
             .join("\n");
     }
     return `${indent}${renderScalar(value)}`;
@@ -335,6 +366,7 @@ function formatEffectiveOutput(effectiveResult, nativeOutput, options) {
             ["outputBudget", options.outputBudget],
             ["outputFormat", options.outputFormat],
             ["outputSession", options.outputSession],
+            ["outputRowContract", options.outputRowContract],
         ].filter((entry) => entry[1] !== undefined)),
     };
     const format = resolveReadOutputEncoding(command ?? "", commandOptions) ??
@@ -424,4 +456,4 @@ export const outputTestOnly = {
     renderToonValue,
 };
 //# sourceMappingURL=output.js.map
-//# debugId=b52d2756-f640-5f53-981f-05fa23fa1718
+//# debugId=5aaf8b90-5b95-5102-9ea4-b877c696d593

package/dist/core/search/vector-stores.js

@@ -1,10 +1,10 @@
 
-!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]="7bac9506-dcad-5e52-848b-3e2631d4936c")}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]="98c8d03c-bdde-5ac4-b80d-395d885f7442")}catch(e){}}();
 import { mkdir, readFile, stat, unlink } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { executeSearchJsonRequest, normalizeSearchHttpTimeoutMs, resolveSearchHttpFetcher, } from "./http-client.js";
 import { isFiniteNumberArray, toErrorMessage, toNonEmptyString, trimTrailingSlashes, } from "../shared/primitives.js";
-import { writeFileAtomic } from "../fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
 const DEFAULT_COLLECTION = "pm_items";
 const COLLECTION_SANITIZE_PATTERN = /[^a-zA-Z0-9_-]/g;
 const MAX_COLLECTION_NAME_LENGTH = 128;
@@ -200,11 +200,6 @@ function getLanceDbLocalTableKey(storePath, table) {
 function getLanceDbSnapshotPath(storePath, table) {
     return join(resolve(storePath), LANCE_DB_LOCAL_SNAPSHOT_DIR, `${table}.json`);
 }
-function isNodeErrorWithCode(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        error.code === code);
-}
 function normalizeSnapshotRecord(entry, index, snapshotPath) {
     const id = toNonEmptyString(entry.id);
     if (!id) {
@@ -261,7 +256,7 @@ async function readLanceDbSnapshotStats(snapshotPath) {
         return { mtimeMs: stats.mtimeMs, size: stats.size };
     }
     catch (error) {
-        if (!isNodeErrorWithCode(error, "ENOENT")) {
+        if (!isFileMissingError(error)) {
             throw error;
         }
         return null;
@@ -306,7 +301,7 @@ async function loadLanceDbLocalTable(storePath, table) {
         loaded = parseLanceDbSnapshot(snapshotPath, table, raw);
     }
     catch (error) {
-        if (!isNodeErrorWithCode(error, "ENOENT")) {
+        if (!isFileMissingError(error)) {
             throw error;
         }
     }
@@ -331,7 +326,7 @@ async function removeSnapshotFile(snapshotPath) {
         await unlink(snapshotPath);
     }
     catch (error) {
-        if (!isNodeErrorWithCode(error, "ENOENT")) {
+        if (!isFileMissingError(error)) {
             throw new Error(`LanceDB local snapshot delete failed at '${snapshotPath}': ${toErrorMessage(error)}`);
         }
     }
@@ -667,4 +662,4 @@ export async function executeVectorReset(store, knownIds = [], options = {}, vec
     return await executeVectorDelete(store, idsToDelete, options);
 }
 //# sourceMappingURL=vector-stores.js.map
-//# debugId=7bac9506-dcad-5e52-848b-3e2631d4936c
+//# debugId=98c8d03c-bdde-5ac4-b80d-395d885f7442

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. */

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]="df6f6758-f972-5bf4-aaa8-b16dd9a247f3")}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=df6f6758-f972-5bf4-aaa8-b16dd9a247f3
+//# 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]="8b8c705a-8d80-576f-8642-f6f686cdbed9")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -12,7 +12,7 @@ import { getActiveExtensionRegistrations, hasActiveOnReadHooks, runActiveOnReadH
 import { collectRegisteredItemFieldNames } from "../extensions/item-fields.js";
 import { parseItemDocument } from "../item/item-format.js";
 import { evictOldestMemoEntries } from "../shared/memo.js";
-import { writeFileAtomic } from "../fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../fs/fs-utils.js";
 import { acquireLock } from "../lock/lock.js";
 import { ITEM_FILE_EXTENSIONS, getItemFormatFromPath } from "./paths.js";
 import { rebuildItemMetadataQueryIndex, removeItemMetadataQueryIndex, updateItemMetadataQueryIndex, } from "./item-metadata-query-index.js";
@@ -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;
 }
@@ -440,7 +442,7 @@ async function readItemDirectoryFiles(pmRoot, folder, warnings) {
         if (typeof error === "object" &&
             error !== null &&
             "code" in error &&
-            error.code !== "ENOENT") {
+            !isFileMissingError(error)) {
             appendWarning(warnings, `item_list_directory_read_failed:${folder}`);
         }
         return { folder, dirPath, files: [] };
@@ -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=8b8c705a-8d80-576f-8642-f6f686cdbed9

package/dist/core/telemetry/runtime.d.ts

@@ -171,6 +171,10 @@ declare function sanitizeValue(value: unknown, keyHint?: string, captureLevel?:
 declare function sanitizeCommandArgs(args: string[], captureLevel?: Exclude<TelemetryCaptureLevel, "minimal">): string[];
 declare function normalizeCaptureLevel(value: string | undefined): TelemetryCaptureLevel;
 declare function parseBooleanTrueLike(value: string | undefined): boolean;
+/** Resolve the background event and OTLP request timeout within the flush-lock safety envelope. */
+declare function resolveTelemetryHttpTimeoutMs(): number;
+/** POST a JSON payload with one total timeout that covers DNS, connection, TLS, and response completion. */
+declare function postTelemetryJson(endpoint: string, headers: Record<string, string>, body: string): Promise<number>;
 declare function normalizePmVersion(value: string | undefined): string;
 declare function normalizeTelemetryErrorCode(value: string | undefined): string | undefined;
 declare function normalizeTelemetryExitCode(exitCode: number | undefined, ok: boolean): number;
@@ -335,11 +339,13 @@ export declare const _testOnly: {
     looksLikeEmailToken: typeof looksLikeEmailToken;
     otelSpansQueuePath: typeof otelSpansQueuePath;
     parseBooleanTrueLike: typeof parseBooleanTrueLike;
+    postTelemetryJson: typeof postTelemetryJson;
     parsePendingOtelSpanLines: typeof parsePendingOtelSpanLines;
     prunePendingOtelSpans: typeof prunePendingOtelSpans;
     reconcilePendingOtelSpansAfterFlush: typeof reconcilePendingOtelSpansAfterFlush;
     retentionCutoffMs: typeof retentionCutoffMs;
     resolveOtelTracesEndpoint: typeof resolveOtelTracesEndpoint;
+    resolveTelemetryHttpTimeoutMs: typeof resolveTelemetryHttpTimeoutMs;
     rewritePendingOtelSpans: typeof rewritePendingOtelSpans;
     normalizeForHash: typeof normalizeForHash;
     normalizeCaptureLevel: typeof normalizeCaptureLevel;