@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/sdk/contracts.js

@@ -4,8 +4,9 @@
  * Exposes command and action contract data without loading SDK runtime code.
  */
 
-!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]="2962656f-386f-59a0-8dc1-411ae382dddb")}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]="65e53d90-6fff-59df-bdfc-0d2387b5a28d")}catch(e){}}();
 export * from "./cli-contracts.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-intent-contracts.js";
 export * from "./error-code-catalog.js";
 export * from "./generated-error-code-catalog.js";
@@ -14,4 +15,4 @@ export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=2962656f-386f-59a0-8dc1-411ae382dddb
+//# debugId=65e53d90-6fff-59df-bdfc-0d2387b5a28d

package/dist/sdk/core.d.ts

@@ -6,6 +6,8 @@
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
-export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputDimension, PmReadOutputLegacyAlias, PmReadOutputOptions, PmReadOutputReceipt, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurface, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionReference, PmReadOutputSessionState, } from "./read-output-session.js";
 export type { ItemDocument, ItemMetadata, ItemStatus, ItemType, PmSettings, } from "../types/index.js";

package/dist/sdk/core.js

@@ -4,10 +4,11 @@
  * Provides the stable item lifecycle client and universal project data types.
  */
 
-!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]="d70db3d9-b094-52fd-8f0f-47eed9f6e7f0")}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]="54d31df7-e708-585d-9fb2-3c5ddfcc6138")}catch(e){}}();
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
-export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 //# sourceMappingURL=core.js.map
-//# debugId=d70db3d9-b094-52fd-8f0f-47eed9f6e7f0
+//# debugId=54d31df7-e708-585d-9fb2-3c5ddfcc6138

package/dist/sdk/environment/host-environment-errors.d.ts

@@ -0,0 +1,27 @@
+import { PmCliError } from "../../core/shared/errors.js";
+/** Optional stable codes used by an existing SDK surface for each fault class. */
+export interface HostEnvironmentFaultCodeOverrides {
+    /** Code used for quota and storage exhaustion. */
+    capacity?: string;
+    /** Code used for access policy and read-only filesystems. */
+    permission?: string;
+    /** Code used for file-descriptor and memory exhaustion. */
+    resource?: string;
+}
+/** Context and compatibility controls for a host-environment boundary. */
+export interface HostEnvironmentBoundaryOptions {
+    /** Existing surface-specific codes that must remain compatible. */
+    codes?: HostEnvironmentFaultCodeOverrides;
+    /** Human explanation of why the operation needs host resources. */
+    why?: string;
+    /** Additional ordered recovery guidance. */
+    nextSteps?: readonly string[];
+    /** Copyable retry command when one is safe. */
+    suggestedRetry?: string;
+}
+/** Return a declared host errno only when it represents recoverable environment state. */
+export declare function classifyHostEnvironmentFault(error: unknown): string | null;
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export declare function translateHostEnvironmentFault(error: unknown, operation: string, options?: HostEnvironmentBoundaryOptions): PmCliError | null;
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export declare function withHostEnvironmentBoundary<T>(operation: string, run: () => Promise<T>, options?: HostEnvironmentBoundaryOptions): Promise<T>;

package/dist/sdk/environment/host-environment-errors.js

@@ -0,0 +1,124 @@
+/**
+ * @module sdk/host-environment-errors
+ *
+ * Classifies host filesystem/resource failures at SDK boundaries without
+ * leaking local paths or swallowing genuine implementation defects.
+ */
+
+!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]="41fec0f3-5cc8-5007-a896-f8d8b83ae4f5")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+const HOST_ENVIRONMENT_FAULTS = new Map([
+    [
+        "EACCES",
+        {
+            summary: "was denied filesystem permission",
+            recovery: "Grant the required filesystem access, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EDQUOT",
+        {
+            summary: "exceeded the filesystem quota",
+            recovery: "Raise or reclaim the filesystem quota, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EMFILE",
+        {
+            summary: "exhausted the process file-descriptor limit",
+            recovery: "Close unused file handles or raise the process limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENFILE",
+        {
+            summary: "exhausted the host file-descriptor limit",
+            recovery: "Free host file descriptors or raise the host limit, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOMEM",
+        {
+            summary: "ran out of available memory",
+            recovery: "Free memory or reduce concurrent work, then retry.",
+            category: "resource",
+        },
+    ],
+    [
+        "ENOSPC",
+        {
+            summary: "ran out of storage space",
+            recovery: "Free storage on the filesystem holding the project, then retry.",
+            category: "capacity",
+        },
+    ],
+    [
+        "EPERM",
+        {
+            summary: "was denied by the host permission policy",
+            recovery: "Grant the required filesystem permission, then retry.",
+            category: "permission",
+        },
+    ],
+    [
+        "EROFS",
+        {
+            summary: "targeted a read-only filesystem",
+            recovery: "Use a writable project filesystem or remount it read-write, then retry.",
+            category: "permission",
+        },
+    ],
+]);
+const OPERATION_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
+const HOST_ENVIRONMENT_FAULT_CODES = {
+    capacity: { code: "host_environment_capacity_fault" },
+    permission: { code: "host_environment_permission_fault" },
+    resource: { code: "host_environment_resource_fault" },
+};
+/** Return a declared host errno only when it represents recoverable environment state. */
+export function classifyHostEnvironmentFault(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return null;
+    const code = error.code;
+    return typeof code === "string" && HOST_ENVIRONMENT_FAULTS.has(code)
+        ? code
+        : null;
+}
+/** Translate one known host fault into a stable path-redacted SDK refusal. */
+export function translateHostEnvironmentFault(error, operation, options = {}) {
+    const errno = classifyHostEnvironmentFault(error);
+    if (errno === null)
+        return null;
+    if (!OPERATION_PATTERN.test(operation)) {
+        throw new PmCliError("Host environment operation labels must be bounded identifiers.", EXIT_CODE.USAGE, { code: "host_environment_operation_invalid", field: "operation" });
+    }
+    const fault = HOST_ENVIRONMENT_FAULTS.get(errno);
+    return new PmCliError(`Host filesystem operation ${operation} ${fault.summary}.`, EXIT_CODE.GENERIC_FAILURE, {
+        code: options.codes?.[fault.category] ??
+            HOST_ENVIRONMENT_FAULT_CODES[fault.category].code,
+        reason: errno,
+        required: fault.recovery,
+        why: options.why ??
+            "The operating system refused a required project filesystem operation.",
+        nextSteps: [fault.recovery, ...(options.nextSteps ?? [])],
+        ...(options.suggestedRetry
+            ? { recovery: { suggested_retry: options.suggestedRetry } }
+            : {}),
+    });
+}
+/** Run one SDK filesystem stage and translate only declared host faults. */
+export async function withHostEnvironmentBoundary(operation, run, options = {}) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw translateHostEnvironmentFault(error, operation, options) ?? error;
+    }
+}
+//# sourceMappingURL=host-environment-errors.js.map
+//# debugId=41fec0f3-5cc8-5007-a896-f8d8b83ae4f5

package/dist/sdk/environment/project-runtime-compatibility.d.ts

@@ -0,0 +1,65 @@
+import { PmCliError } from "../../core/shared/errors.js";
+export { PmCliError };
+/** One discovered project pin that can prove the active executable is stale. */
+export interface ProjectRuntimeVersionPin {
+    /** Exact or minimum date-version extracted from the project declaration. */
+    version: string;
+    /** Redaction-safe origin of the pin. */
+    source: "package.json" | "installed-package" | "package-lock.json" | "pnpm-lock.yaml" | "yarn.lock";
+}
+/** Structured result returned by the read-only compatibility probe. */
+export interface ProjectRuntimeCompatibilityResult {
+    /** Whether the invocation can write with the active runtime. */
+    compatible: boolean;
+    /** Active executable package version. */
+    executing_version: string;
+    /** Highest project pin discovered without exposing local paths. */
+    project_version?: string;
+    /** Origin of the highest project pin. */
+    source?: ProjectRuntimeVersionPin["source"];
+    /** Canonical command selected from the invocation. */
+    command?: string;
+    /** Whether the selected invocation can mutate project state. */
+    mutating: boolean;
+    /** Whether the active executable is older than the strongest project pin. */
+    stale?: boolean;
+    /** Non-blocking diagnostic attached to stale read-only invocations. */
+    warning?: ProjectRuntimeCompatibilityWarning;
+    /** Whether the explicit one-invocation recovery override was accepted. */
+    override_applied: boolean;
+}
+/** Structured, package-manager-neutral warning returned for a stale read. */
+export interface ProjectRuntimeCompatibilityWarning {
+    /** Stable warning code for filtering and automation. */
+    code: "project_runtime_stale_read";
+    /** Active executable package version. */
+    executing_version: string;
+    /** Strongest newer project version pin. */
+    project_version: string;
+    /** Redaction-safe origin of the project pin. */
+    source: ProjectRuntimeVersionPin["source"];
+    /** Concise explanation of the mismatch. */
+    message: string;
+    /** Package-manager-neutral recovery actions. */
+    next_steps: string[];
+}
+/** Compare pm date versions without accepting arbitrary semver-like prose. */
+export declare function comparePmDateVersions(left: string, right: string): number | null;
+/** Discover declared, installed, and lock-resolved versions without network I/O. */
+export declare function discoverProjectRuntimeVersionPins(projectRoot: string): ProjectRuntimeVersionPin[];
+/** Classify mutation-capable invocations while preserving explicit read modes. */
+export declare function isProjectMutatingInvocation(argv: readonly string[]): boolean;
+/** Inspect whether one invocation is compatible with the project's newest pin. */
+export declare function inspectProjectRuntimeCompatibility(options: {
+    executingVersion: string;
+    projectRoot: string;
+    argv: readonly string[];
+    allowStale?: boolean;
+}): ProjectRuntimeCompatibilityResult;
+/** Refuse stale mutations with a stable SDK error and package-neutral recovery. */
+export declare function assertProjectRuntimeCompatibility(options: {
+    executingVersion: string;
+    projectRoot: string;
+    argv: readonly string[];
+    allowStale?: boolean;
+}): ProjectRuntimeCompatibilityResult;

package/dist/sdk/environment/project-runtime-compatibility.js

@@ -0,0 +1,385 @@
+/**
+ * @module sdk/project-runtime-compatibility
+ *
+ * Protects project mutations from an older PATH-resolved pm executable while
+ * leaving diagnosis reads available.
+ */
+
+!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]="962636b0-ed3b-5ad0-ae0c-904435025986")}catch(e){}}();
+import fs from "node:fs";
+import path from "node:path";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+export { PmCliError };
+const PACKAGE_NAME = "@unbrained/pm-cli";
+const MUTATING_COMMANDS = new Set([
+    "append",
+    "claim",
+    "changelog",
+    "close",
+    "close-many",
+    "close-task",
+    "comments",
+    "config",
+    "copy",
+    "create",
+    "dedupe-merge",
+    "delete",
+    "deps",
+    "docs",
+    "extension",
+    "event",
+    "events",
+    "files",
+    "focus",
+    "gc",
+    "history-author-acknowledge",
+    "history-compact",
+    "history-redact",
+    "history-repair",
+    "init",
+    "install",
+    "item",
+    "learnings",
+    "meet",
+    "merge",
+    "normalize",
+    "notes",
+    "package",
+    "packages",
+    "pause-task",
+    "plan",
+    "profile",
+    "reindex",
+    "release",
+    "remind",
+    "restore",
+    "schema",
+    "start-task",
+    "test",
+    "test-all",
+    "test-runs",
+    "test-runs-worker",
+    "telemetry",
+    "templates",
+    "twin",
+    "update",
+    "update-many",
+    "upgrade",
+    "vcs",
+    "workspace",
+]);
+const GLOBAL_VALUE_FLAGS = new Set([
+    "--author",
+    "--output-budget",
+    "--output-format",
+    "--output-include",
+    "--output-limit",
+    "--output-session",
+    "--path",
+    "--pm-path",
+]);
+const VERSION_PATTERN = /\b(\d{4})\.(\d{1,2})\.(\d{1,2})(?:-(\d+))?\b/u;
+/** Return whether an invocation includes one of the exact mutation switches. */
+function hasAnyToken(argv, tokens) {
+    return argv.some((token) => tokens.includes(token.split("=", 1)[0]));
+}
+/** Classify package/extension compatibility aliases from subcommands and legacy flags. */
+function isPackageMutation(argv, positionals) {
+    return ([
+        "activate",
+        "adopt",
+        "adopt-all",
+        "deactivate",
+        "init",
+        "install",
+        "migrate",
+        "reload",
+        "uninstall",
+    ].includes(positionals[0] ?? "") ||
+        hasAnyToken(argv, [
+            "--activate",
+            "--adopt",
+            "--adopt-all",
+            "--deactivate",
+            "--fix-managed-state",
+            "--init",
+            "--install",
+            "--output",
+            "--reload",
+            "--scaffold",
+            "--uninstall",
+        ]));
+}
+const MIXED_COMMAND_CLASSIFIERS = {
+    changelog: (argv, positionals) => {
+        if (positionals[0] === "generate")
+            return !hasAnyToken(argv, ["--check"]);
+        const exportIndex = argv.indexOf("export");
+        return (positionals[0] === "export" &&
+            (hasAnyToken(argv, ["--output"]) ||
+                (exportIndex >= 0 &&
+                    argv[exportIndex + 1] !== undefined &&
+                    !argv[exportIndex + 1].startsWith("-"))));
+    },
+    comments: (argv) => hasAnyToken(argv, ["--add", "--delete", "--edit", "--file", "--stdin"]),
+    config: (_argv, positionals) => (positionals[0] === "project" || positionals[0] === "global"
+        ? positionals[1]
+        : positionals[0]) === "set",
+    deps: () => false,
+    docs: (argv) => hasAnyToken(argv, ["--add", "--add-glob", "--migrate", "--remove"]),
+    duplicates: () => false,
+    events: () => false,
+    extension: isPackageMutation,
+    files: (argv, positionals) => hasAnyToken(argv, ["--add", "--add-glob", "--migrate", "--remove"]) ||
+        (positionals[0] === "discover" && hasAnyToken(argv, ["--apply"])),
+    health: (argv) => !hasAnyToken(argv, ["--check-only", "--no-refresh", "--skip-vectors"]),
+    learnings: (argv) => hasAnyToken(argv, ["--add", "--delete", "--edit", "--file", "--stdin"]),
+    merge: (_argv, positionals) => positionals[0] !== "report",
+    notes: (argv) => hasAnyToken(argv, ["--add", "--delete", "--edit", "--file", "--stdin"]),
+    package: isPackageMutation,
+    packages: isPackageMutation,
+    profile: (_argv, positionals) => positionals[0] === "apply",
+    schema: (argv, positionals) => [
+        "add-field",
+        "add-status",
+        "add-type",
+        "remove-field",
+        "remove-status",
+        "remove-type",
+        "remap-status",
+        "rename-field",
+        "rename-type",
+    ].includes(positionals[0] ?? "") &&
+        !(hasAnyToken(argv, ["--infer"]) && !hasAnyToken(argv, ["--apply"])),
+    telemetry: (_argv, positionals) => positionals.slice(0, 2).some((token) => ["clear", "flush"].includes(token)),
+    templates: (_argv, positionals) => positionals[0] === "save",
+    test: (argv) => hasAnyToken(argv, [
+        "--add",
+        "--add-json",
+        "--background",
+        "--measure",
+        "--remove",
+        "--resume",
+        "--run",
+        "--stop",
+    ]),
+    validate: (argv) => hasAnyToken(argv, ["--auto-fix", "--prune-missing"]),
+    vcs: (_argv, positionals) => ["abandon", "create", "merge", "propose", "ref-create"].includes(positionals[0] ?? ""),
+    workspace: (_argv, positionals) => positionals[0] === "snapshot" &&
+        ["create", "delete", "restore"].includes(positionals[1] ?? ""),
+};
+/** Parse the supported date-version coordinates used by pm releases. */
+function parseDateVersion(value) {
+    const match = value.match(VERSION_PATTERN);
+    return match
+        ? [
+            Number(match[1]),
+            Number(match[2]),
+            Number(match[3]),
+            Number(match[4] ?? 0),
+        ]
+        : null;
+}
+/** Compare pm date versions without accepting arbitrary semver-like prose. */
+export function comparePmDateVersions(left, right) {
+    const leftParts = parseDateVersion(left);
+    const rightParts = parseDateVersion(right);
+    if (!leftParts || !rightParts)
+        return null;
+    for (let index = 0; index < leftParts.length; index += 1) {
+        const delta = leftParts[index] - rightParts[index];
+        if (delta !== 0)
+            return Math.sign(delta);
+    }
+    return 0;
+}
+/** Read one optional JSON object without turning absence or corruption into startup failure. */
+function readJsonRecord(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        return typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract the highest explicit lower-bound pm date version from dependency declarations. */
+function dependencyPin(packageJson) {
+    const versions = [];
+    for (const field of [
+        "dependencies",
+        "devDependencies",
+        "optionalDependencies",
+        "peerDependencies",
+    ]) {
+        const dependencies = packageJson[field];
+        if (typeof dependencies !== "object" || dependencies === null)
+            continue;
+        const value = dependencies[PACKAGE_NAME];
+        const specification = typeof value === "string" ? value.trim() : "";
+        const version = /^[<!]/u.test(specification)
+            ? undefined
+            : specification.match(VERSION_PATTERN)?.[0];
+        if (version)
+            versions.push(version);
+    }
+    return versions.sort((left, right) => comparePmDateVersions(right, left))[0];
+}
+/** Read npm's exact installed package coordinate from package-lock.json. */
+function packageLockPin(projectRoot) {
+    const lock = readJsonRecord(path.join(projectRoot, "package-lock.json"));
+    const packages = lock?.packages;
+    if (typeof packages !== "object" || packages === null)
+        return undefined;
+    const installed = packages["node_modules/@unbrained/pm-cli"];
+    if (typeof installed !== "object" || installed === null)
+        return undefined;
+    const version = installed.version;
+    return typeof version === "string" ? version : undefined;
+}
+/** Read the exact coordinate from the matching text lockfile package block. */
+function textLockPin(projectRoot, file) {
+    try {
+        const lines = fs
+            .readFileSync(path.join(projectRoot, file), "utf8")
+            .split(/\r?\n/u);
+        const packageLineIndex = lines.findIndex((line) => line.includes(PACKAGE_NAME));
+        if (packageLineIndex < 0)
+            return undefined;
+        const packageIndent = lines[packageLineIndex].match(/^\s*/u)[0].length;
+        const entry = [lines[packageLineIndex]];
+        for (let index = packageLineIndex + 1; index < lines.length; index += 1) {
+            const line = lines[index];
+            const trimmed = line.trim();
+            const indent = line.match(/^\s*/u)[0].length;
+            if (trimmed.length > 0 && indent <= packageIndent)
+                break;
+            entry.push(line);
+        }
+        const entrySource = entry.join("\n");
+        const explicitVersion = entrySource.match(/^\s*version(?::\s*|\s+)["']?(\d{4}\.\d{1,2}\.\d{1,2}(?:-\d+)?)/mu)?.[1];
+        return explicitVersion ?? entry[0].match(VERSION_PATTERN)?.[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Discover declared, installed, and lock-resolved versions without network I/O. */
+export function discoverProjectRuntimeVersionPins(projectRoot) {
+    const pins = [];
+    const projectPackage = readJsonRecord(path.join(projectRoot, "package.json"));
+    const declared = projectPackage ? dependencyPin(projectPackage) : undefined;
+    if (declared)
+        pins.push({ version: declared, source: "package.json" });
+    const installedPackage = readJsonRecord(path.join(projectRoot, "node_modules", "@unbrained", "pm-cli", "package.json"));
+    const installedVersion = installedPackage?.version;
+    if (typeof installedVersion === "string" &&
+        parseDateVersion(installedVersion)) {
+        pins.push({ version: installedVersion, source: "installed-package" });
+    }
+    const packageLockVersion = packageLockPin(projectRoot);
+    if (packageLockVersion && parseDateVersion(packageLockVersion)) {
+        pins.push({ version: packageLockVersion, source: "package-lock.json" });
+    }
+    for (const file of ["pnpm-lock.yaml", "yarn.lock"]) {
+        const version = textLockPin(projectRoot, file);
+        if (version)
+            pins.push({ version, source: file });
+    }
+    return pins;
+}
+/** Resolve the first command token and index while preserving global option values. */
+function commandTokenFromArgv(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (GLOBAL_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (!token.startsWith("-"))
+            return { command: token.toLowerCase(), index };
+    }
+    return undefined;
+}
+/** Classify mutation-capable invocations while preserving explicit read modes. */
+export function isProjectMutatingInvocation(argv) {
+    const commandToken = commandTokenFromArgv(argv);
+    if (!commandToken)
+        return false;
+    if (hasAnyToken(argv, ["--help", "-h", "--dry-run"]))
+        return false;
+    const { command, index: commandIndex } = commandToken;
+    const positionals = [];
+    for (let index = commandIndex + 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (GLOBAL_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (!token.startsWith("-"))
+            positionals.push(token.toLowerCase());
+    }
+    const mixedClassifier = MIXED_COMMAND_CLASSIFIERS[command];
+    return mixedClassifier
+        ? mixedClassifier(argv, positionals)
+        : MUTATING_COMMANDS.has(command);
+}
+/** Inspect whether one invocation is compatible with the project's newest pin. */
+export function inspectProjectRuntimeCompatibility(options) {
+    const command = commandTokenFromArgv(options.argv)?.command;
+    const mutating = isProjectMutatingInvocation(options.argv);
+    const pins = discoverProjectRuntimeVersionPins(options.projectRoot)
+        .filter((pin) => comparePmDateVersions(pin.version, options.executingVersion) !== null)
+        .sort((left, right) => comparePmDateVersions(right.version, left.version));
+    const newest = pins[0];
+    const stale = newest !== undefined &&
+        comparePmDateVersions(options.executingVersion, newest.version) === -1;
+    const warning = stale && !mutating
+        ? {
+            code: "project_runtime_stale_read",
+            executing_version: options.executingVersion,
+            project_version: newest.version,
+            source: newest.source,
+            message: "This read is using an older pm runtime than the project requires.",
+            next_steps: [
+                `Run the command through the project's installed ${PACKAGE_NAME} ${newest.version}.`,
+                "Install the project dependencies with its declared package manager if the local executable is missing.",
+            ],
+        }
+        : undefined;
+    return {
+        compatible: !mutating || !stale || options.allowStale === true,
+        executing_version: options.executingVersion,
+        ...(newest
+            ? { project_version: newest.version, source: newest.source }
+            : {}),
+        ...(command ? { command } : {}),
+        mutating,
+        stale,
+        ...(warning ? { warning } : {}),
+        override_applied: stale && mutating && options.allowStale === true,
+    };
+}
+/** Refuse stale mutations with a stable SDK error and package-neutral recovery. */
+export function assertProjectRuntimeCompatibility(options) {
+    const result = inspectProjectRuntimeCompatibility(options);
+    if (result.compatible)
+        return result;
+    throw new PmCliError(`pm ${result.executing_version} cannot mutate a project pinned to newer pm ${result.project_version}.`, EXIT_CODE.CONFLICT, {
+        code: "project_runtime_stale_mutation",
+        reason: result.source,
+        why: "An older runtime can write storage, history, and merge contracts it does not understand.",
+        nextSteps: [
+            `Run this command through the project's installed ${PACKAGE_NAME} ${result.project_version}.`,
+            "For an intentional recovery only, set PM_ALLOW_STALE_CLI=1 for this invocation and record why.",
+            "Read-only commands remain available without an override.",
+        ],
+    });
+}
+//# sourceMappingURL=project-runtime-compatibility.js.map
+//# debugId=962636b0-ed3b-5ad0-ae0c-904435025986