@unbrained/pm-cli 2026.8.9 → 2026.8.10

package/dist/sdk/merge/receipts.js

@@ -7,7 +7,7 @@
  * value for the coordinator that performed the merge.
  */
 
-!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]="3ccde5c2-f743-52ac-a3fd-9590f720e1b3")}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]="59863597-bf57-5d96-9cba-983443e5b209")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
@@ -31,6 +31,21 @@ async function resolveReceiptDirectory(cwd) {
         return null;
     }
 }
+async function resolveTrackerRootFromItemPath(cwd, itemPath) {
+    let directory = path.dirname(path.resolve(cwd, itemPath));
+    for (let depth = 0; depth < 12; depth += 1) {
+        if (await pathExists(path.join(directory, "settings.json")))
+            return directory;
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return null;
+}
+function durableReceiptDirectory(pmRoot) {
+    return path.join(pmRoot, "merge-receipts");
+}
 function receiptFileName(id) {
     return `${id}.json`;
 }
@@ -47,11 +62,25 @@ export function summarizeMergeReceipt(receipt) {
         conflict_resolution: receipt.conflict_resolution,
         decisions: receipt.decisions.map((decision) => ({
             field: decision.field,
-            retained_hash: sha256Hex(stableStringify(decision.retained)),
-            discarded_hash: sha256Hex(stableStringify(decision.discarded)),
+            retained_hash: isPrehashedValue(decision.retained) ??
+                sha256Hex(stableStringify(decision.retained)),
+            discarded_hash: isPrehashedValue(decision.discarded) ??
+                sha256Hex(stableStringify(decision.discarded)),
         })),
     };
 }
+function isPrehashedValue(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        !("pm_value_hash" in value)) {
+        return undefined;
+    }
+    const hash = value.pm_value_hash;
+    return typeof hash === "string" && /^[a-f0-9]{64}$/u.test(hash)
+        ? hash
+        : undefined;
+}
 /** Persist one item-driver outcome in the clone-local Git directory. */
 export async function writeMergeReceipt(params) {
     const directory = await resolveReceiptDirectory(params.cwd);
@@ -77,18 +106,34 @@ export async function writeMergeReceipt(params) {
         decisions: structuredClone(params.decisions),
         state: "pending",
         created_at: nowIso(),
+        value_availability: "clone_local",
     };
     await ensureDir(directory);
     await writeFileAtomic(path.join(directory, receiptFileName(receipt.id)), `${JSON.stringify(receipt, null, 2)}\n`);
+    const trackerRoot = await resolveTrackerRootFromItemPath(params.cwd, receipt.item_path);
+    if (trackerRoot !== null) {
+        const durableDirectory = durableReceiptDirectory(trackerRoot);
+        const summary = summarizeMergeReceipt(receipt);
+        const durableReceipt = {
+            ...receipt,
+            decisions: summary.decisions.map((decision) => ({
+                field: decision.field,
+                base: null,
+                ours: null,
+                theirs: null,
+                retained: { pm_value_hash: decision.retained_hash },
+                discarded: { pm_value_hash: decision.discarded_hash },
+            })),
+            value_availability: "hash_only",
+        };
+        await ensureDir(durableDirectory);
+        await writeFileAtomic(path.join(durableDirectory, receiptFileName(receipt.id)), `${JSON.stringify(durableReceipt, null, 2)}\n`);
+    }
     return receipt;
 }
-/** Read clone-local receipts with explicit reconciled/lossless classification controls. */
-export async function listMergeReceipts(cwd, options = {}) {
-    const directory = await resolveReceiptDirectory(cwd);
-    if (directory === null || !(await pathExists(directory))) {
+async function readReceiptsFromDirectory(directory, options) {
+    if (!(await pathExists(directory)))
         return [];
-    }
-    const receipts = [];
     let names;
     try {
         names = await readdir(directory);
@@ -96,10 +141,10 @@ export async function listMergeReceipts(cwd, options = {}) {
     catch {
         return [];
     }
+    const receipts = [];
     for (const name of names.sort((left, right) => left.localeCompare(right))) {
-        if (!name.endsWith(".json")) {
+        if (!name.endsWith(".json"))
             continue;
-        }
         try {
             const parsed = JSON.parse(await readFile(path.join(directory, name), "utf8"));
             const normalizedReceipt = {
@@ -109,17 +154,28 @@ export async function listMergeReceipts(cwd, options = {}) {
             if (normalizedReceipt.version === 1 &&
                 (options.includeReconciled || normalizedReceipt.state === "pending") &&
                 (options.includeLossless !== false ||
-                    (Array.isArray(normalizedReceipt.decisions) &&
-                        normalizedReceipt.decisions.length > 0))) {
+                    normalizedReceipt.decisions.length > 0)) {
                 receipts.push(normalizedReceipt);
             }
         }
         catch {
-            // A damaged clone-local receipt is reported by merge report through the
-            // omitted count once a future schema version adds richer diagnostics.
+            // Malformed evidence remains an integrity concern for a future schema.
         }
     }
-    return receipts.sort((left, right) => left.created_at.localeCompare(right.created_at));
+    return receipts;
+}
+/** Read clone-local receipts with explicit reconciled/lossless classification controls. */
+export async function listMergeReceipts(cwd, options = {}) {
+    const directory = await resolveReceiptDirectory(cwd);
+    const local = directory === null
+        ? []
+        : await readReceiptsFromDirectory(directory, options);
+    const trackerRoot = options.pmRoot ?? path.join(cwd, ".agents", "pm");
+    const durable = await readReceiptsFromDirectory(durableReceiptDirectory(trackerRoot), options);
+    const receipts = new Map(durable.map((receipt) => [receipt.id, receipt]));
+    for (const receipt of local)
+        receipts.set(receipt.id, receipt);
+    return [...receipts.values()].sort((left, right) => left.created_at.localeCompare(right.created_at));
 }
 /** Split merge provenance into receipts with discarded values and receipts whose composition was lossless. */
 export function partitionMergeReceipts(receipts) {
@@ -139,6 +195,14 @@ export async function markMergeReceiptReconciled(cwd, receipt) {
         return;
     }
     await writeFileAtomic(path.join(directory, receiptFileName(receipt.id)), `${JSON.stringify({ ...receipt, state: "reconciled", reconciled_at: nowIso() }, null, 2)}\n`);
+    const trackerRoot = await resolveTrackerRootFromItemPath(cwd, receipt.item_path);
+    if (trackerRoot !== null) {
+        const durablePath = path.join(durableReceiptDirectory(trackerRoot), receiptFileName(receipt.id));
+        if (await pathExists(durablePath)) {
+            const durable = JSON.parse(await readFile(durablePath, "utf8"));
+            await writeFileAtomic(durablePath, `${JSON.stringify({ ...durable, state: "reconciled", reconciled_at: nowIso() }, null, 2)}\n`);
+        }
+    }
 }
 /** Report pending or historical clone-local merge decisions. */
 export async function runMergeReceiptReport(options) {
@@ -154,4 +218,4 @@ export async function runMergeReceiptReport(options) {
     };
 }
 //# sourceMappingURL=receipts.js.map
-//# debugId=3ccde5c2-f743-52ac-a3fd-9590f720e1b3
+//# debugId=59863597-bf57-5d96-9cba-983443e5b209

package/dist/sdk/output-projection.js

@@ -4,7 +4,7 @@
  * Declares machine-readable field-group omissions for bounded command results.
  */
 
-!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]="4a108e0e-0dfc-55c4-9f14-7395cfbac456")}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]="630b48a7-aa38-529c-a272-14b7c748101c")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 /** Universal selector for results carrying a {@link ReadRowContract}. */
@@ -283,11 +283,31 @@ function resolveContextReceipt(result) {
 function resolveGetReceipt(result) {
     if (!isRecord(result.item))
         return undefined;
-    const groups = ["children", "claim_state", "linked"].map((name) => ({
+    const item = result.item;
+    const itemGroups = [
+        "comments",
+        "notes",
+        "learnings",
+        "files",
+        "tests",
+        "docs",
+        "reminders",
+        "events",
+    ];
+    const resultGroups = [
+        "body",
+        "children",
+        "claim_state",
+        "linked",
+        "schedule",
+    ];
+    const groups = ["body", ...itemGroups, ...resultGroups.slice(1)].map((name) => ({
         name,
         restore_with: `--fields ${name}`,
     }));
-    return createOutputOmissionReceipt(groups, new Set(groups.flatMap(({ name }) => (result[name] === undefined ? [] : [name]))));
+    return createOutputOmissionReceipt(groups, new Set(groups.flatMap(({ name }) => !Object.hasOwn(itemGroups.includes(name) ? item : result, name)
+        ? []
+        : [name])));
 }
 function resolveListOrSearchReceipt(result) {
     if (!isRecord(result.projection))
@@ -358,4 +378,4 @@ export function attachOutputOmissionReceipt(command, result) {
         : { ...disclosedResult, omission_receipt: receipt };
 }
 //# sourceMappingURL=output-projection.js.map
-//# debugId=4a108e0e-0dfc-55c4-9f14-7395cfbac456
+//# debugId=630b48a7-aa38-529c-a272-14b7c748101c

package/dist/sdk/query/context.d.ts

@@ -362,6 +362,8 @@ export interface ContextResult {
     focus_fields?: string[];
     /** Value that configures or reports warnings for this contract. */
     warnings?: string[];
+    /** Actionable recovery contracts for context signal-store warnings. */
+    warning_details?: ContextSignalStoreReadResult["warning_details"];
     /** Value that configures or reports ranking for this contract. */
     ranking?: ContextRankingSummary;
     /** Token-budget selection and projection accounting for ranked focus rows. */

package/dist/sdk/query/context.js

@@ -4,7 +4,7 @@
  * Implements the pm context command surface and its agent-facing runtime behavior.
  */
 
-!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]="dbcd4e0e-3fa0-5ce9-8bbc-6de05779d729")}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]="161507f0-b1a7-59a6-9a60-d8f09806ed3f")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
 import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
@@ -1412,7 +1412,7 @@ function buildContextSummaryExtras(needsAllItems, allItems, statusRegistry) {
             canceledStatus).length,
     };
 }
-function attachOptionalContextSections(result, sections) {
+function attachOptionalContextSections(result, sections, warningDetails) {
     if (sections.hierarchy)
         result.hierarchy = sections.hierarchy;
     if (sections.activity)
@@ -1433,6 +1433,9 @@ function attachOptionalContextSections(result, sections) {
         result.staleness = sections.staleness;
     if (sections.tests)
         result.tests = sections.tests;
+    if (warningDetails !== undefined && warningDetails.length > 0) {
+        result.warning_details = warningDetails;
+    }
 }
 function applyContextFocusProjection(result, focusFields) {
     if (!focusFields) {
@@ -1642,7 +1645,7 @@ export async function runContext(options, global) {
     };
     result.workspace_memory = selectWorkspaceMemory(workspaceMemory, Math.min(800, Math.floor(runtime.tokenBudget * 0.2)));
     Object.assign(result, await extensionHealthPromise);
-    attachOptionalContextSections(result, sections);
+    attachOptionalContextSections(result, sections, focusGroups.featureStore.warning_details);
     applyContextTagProjection(result, options.noTags === true);
     if (options.explainRanking === true) {
         result.ranking = toContextRankingSummary(focusGroups.ranking, focusGroups.featureStore);
@@ -1656,4 +1659,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=dbcd4e0e-3fa0-5ce9-8bbc-6de05779d729
+//# debugId=161507f0-b1a7-59a6-9a60-d8f09806ed3f

package/dist/sdk/query/light-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { ItemMetadata } from "../../types/index.js";
+/** Read scalar-only metadata using client workspace defaults and custom type folders. */
+export declare function listClientItemMetadataLight(pmRootOverride: string | undefined, cwdOverride: string | undefined): Promise<ItemMetadata[]>;

package/dist/sdk/query/light-metadata.js

@@ -0,0 +1,19 @@
+/**
+ * @module sdk/query/light-metadata
+ *
+ * Resolves workspace settings for the host-bound lightweight metadata reader.
+ */
+
+!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]="6ede8efb-54ec-5b13-a1bf-216b525acc12")}catch(e){}}();
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { listAllItemMetadataLight } from "../../core/store/item-store.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+/** Read scalar-only metadata using client workspace defaults and custom type folders. */
+export async function listClientItemMetadataLight(pmRootOverride, cwdOverride) {
+    const pmRoot = resolvePmRoot(cwdOverride ?? process.cwd(), pmRootOverride);
+    const settings = await readSettings(pmRoot);
+    return listAllItemMetadataLight(pmRoot, settings.item_format, resolveItemTypeRegistry(settings, null).type_to_folder, undefined, settings.schema);
+}
+//# sourceMappingURL=light-metadata.js.map
+//# debugId=6ede8efb-54ec-5b13-a1bf-216b525acc12

package/dist/sdk/runtime.d.ts

@@ -7,6 +7,7 @@ export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignore
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export type { FlagDefinition } from "../core/extensions/loader.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
+import type { ItemMetadata } from "../types/index.js";
 export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract, } from "./workspace-contracts.js";
 import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
@@ -74,7 +75,7 @@ export { EXIT_CODE };
 export { PmCliError } from "../core/shared/errors.js";
 export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
 export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore, } from "./similarity-scoring.js";
-export { listAllItemMetadata, locateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { listAllItemMetadata, listAllItemMetadataLight, locateItem, readLocatedItem, } from "../core/store/item-store.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
 export { runAggregate, type AggregateOptions, type AggregateResult, type AggregateRow, } from "./query/aggregate.js";
@@ -131,6 +132,8 @@ export declare class PmClient {
     private runTyped;
     /** Return the same context snapshot produced by `pm context`. */
     context<Options extends ReadOptions<ContextOptions> = ContextOptions>(options?: Options): ReadPromise<ContextResult, Options>;
+    /** Read every item through the scalar-only metadata cache without materializing heavy collections or bodies. */
+    listAllItemMetadataLight(): Promise<ItemMetadata[]>;
     /** List items with the MCP/agent compact defaults. */
     list<Options extends ReadOptions<ListOptions> = ListOptions>(options?: Options): ReadPromise<ListResult, Options>;
     /** Search items with the MCP/agent compact defaults. */

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="c8f2b88e-1883-5744-868b-3a16f3814813")}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]="70ce3cab-35f0-508b-9348-2f8479495946")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -22,6 +22,7 @@ import { createAsyncReadWriteGate } from "../core/shared/serial-queue.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../core/schema/runtime-schema.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
+import { listClientItemMetadataLight } from "./query/light-metadata.js";
 import { buildWorkspaceExtensionCommandContracts, buildWorkspaceFieldContracts, } from "./workspace-contracts.js";
 import { PM_TOOL_ACTIONS } from "./cli-contracts/enum-contracts.js";
 import { clearWorkspaceContractsCache, memoizeWorkspaceExtensionRegistrations, } from "./workspace-contracts-cache.js";
@@ -99,7 +100,7 @@ export { EXIT_CODE };
 export { PmCliError } from "../core/shared/errors.js";
 export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
 export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, } from "./similarity-scoring.js";
-export { listAllItemMetadata, locateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { listAllItemMetadata, listAllItemMetadataLight, locateItem, readLocatedItem, } from "../core/store/item-store.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
 export { runAggregate, } from "./query/aggregate.js";
@@ -169,6 +170,10 @@ export class PmClient {
     context(options = {}) {
         return this.runTyped("context", { options });
     }
+    /** Read every item through the scalar-only metadata cache without materializing heavy collections or bodies. */
+    listAllItemMetadataLight() {
+        return listClientItemMetadataLight(this.defaults.path, this.defaults.cwd);
+    }
     /** List items with the MCP/agent compact defaults. */
     list(options = {}) {
         return this.runTyped("list", { options });
@@ -1925,4 +1930,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=c8f2b88e-1883-5744-868b-3a16f3814813
+//# debugId=70ce3cab-35f0-508b-9348-2f8479495946

package/dist/sdk/schema-migration.js

@@ -7,7 +7,7 @@
  * guarantees.
  */
 
-!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]="c4b4af3b-6ce6-56f7-9665-9e6b2f3d9630")}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]="7d175791-016d-59b6-a44d-a70371f36751")}catch(e){}}();
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -18,6 +18,7 @@ import { parseFieldsFile, serializeFieldsFile, } from "../core/schema/fields-fil
 import { parseItemTypesFile, serializeItemTypesFile, } from "../core/schema/item-types-file.js";
 import { DEFAULT_RUNTIME_SCHEMA_FILE_PATHS, filePathForSchemaSection, normalizeRuntimeSchemaSettings, } from "../core/schema/runtime-schema.js";
 import { parseStatusDefsFile, serializeStatusDefsFile, } from "../core/schema/status-defs-file.js";
+import { normalizeStatusToken } from "../core/schema/status-token.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
@@ -55,9 +56,6 @@ export function deriveSchemaEvolutionMigrationId(requestInput, migrationScope) {
         .slice(0, 20)}`;
 }
 function normalizedRequest(request) {
-    const normalizeToken = (value) => requiredText(value, "source or target")
-        .toLowerCase()
-        .replaceAll(/[\s-]+/g, "_");
     const normalized = request.kind === "rename-type"
         ? {
             kind: request.kind,
@@ -67,16 +65,16 @@ function normalizedRequest(request) {
         : request.kind === "rename-field"
             ? {
                 kind: request.kind,
-                from: normalizeToken(request.from),
-                to: normalizeToken(request.to),
+                from: normalizeStatusToken(requiredText(request.from, "source")),
+                to: normalizeStatusToken(requiredText(request.to, "target")),
                 ...(request.type === undefined
                     ? {}
                     : { type: requiredText(request.type, "type") }),
             }
             : {
                 kind: request.kind,
-                from: normalizeToken(request.from),
-                to: normalizeToken(request.to),
+                from: normalizeStatusToken(requiredText(request.from, "source")),
+                to: normalizeStatusToken(requiredText(request.to, "target")),
             };
     if (normalized.from.toLowerCase() === normalized.to.toLowerCase()) {
         throw new TypeError("Schema migration source and target must differ");
@@ -857,4 +855,4 @@ export const schemaMigrationTestOnly = {
     validateAndStoreMigrationPlan,
 };
 //# sourceMappingURL=schema-migration.js.map
-//# debugId=c4b4af3b-6ce6-56f7-9665-9e6b2f3d9630
+//# debugId=7d175791-016d-59b6-a44d-a70371f36751

package/dist/sdk/similarity-scoring.d.ts

@@ -1,3 +1,4 @@
+export { jaccardSimilarity } from "../core/shared/text-normalization.js";
 /** Precomputed title signals reused by bounded batch similarity operations. */
 export interface PreparedSimilarityText {
     /** Canonical title used for exact comparison. */
@@ -20,8 +21,6 @@ export declare function normalizeSimilarityText(value: string): string;
 export declare function tokenizeSimilarityText(value: string): string[];
 /** Precompute every deterministic title signal exactly once for repeated comparisons. */
 export declare function prepareSimilarityText(value: string): PreparedSimilarityText;
-/** Measure set overlap between two token collections. */
-export declare function jaccardSimilarity(leftTokens: readonly string[], rightTokens: readonly string[]): number;
 /** Score two titles through the canonical exact, issue-code, and token signals. */
 export declare function scoreItemSimilarity(leftTitle: string, rightTitle: string): ItemSimilarityScore;
 /** Score two precomputed title representations without repeating normalization or tokenization. */

package/dist/sdk/similarity-scoring.js

@@ -5,7 +5,9 @@
  * extension packages without loading tracker query infrastructure.
  */
 
-!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]="64312ac7-5a99-5a21-b99f-2bdef1b54a06")}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]="dff9b113-2b29-5154-afbf-f191f2f556a6")}catch(e){}}();
+import { jaccardSimilarity } from "../core/shared/text-normalization.js";
+export { jaccardSimilarity } from "../core/shared/text-normalization.js";
 const ISSUE_CODE_PATTERN = /\b[a-z][a-z0-9]*-\d+(?:-[a-z0-9]+)*\b/giu;
 /** Normalize title text for exact comparisons and tokenization. */
 export function normalizeSimilarityText(value) {
@@ -30,20 +32,6 @@ export function prepareSimilarityText(value) {
         ],
     };
 }
-/** Measure set overlap between two token collections. */
-export function jaccardSimilarity(leftTokens, rightTokens) {
-    const left = new Set(leftTokens);
-    const right = new Set(rightTokens);
-    const union = new Set([...left, ...right]);
-    if (union.size === 0)
-        return 1;
-    let intersection = 0;
-    for (const token of left) {
-        if (right.has(token))
-            intersection += 1;
-    }
-    return intersection / union.size;
-}
 /** Score two titles through the canonical exact, issue-code, and token signals. */
 export function scoreItemSimilarity(leftTitle, rightTitle) {
     return scorePreparedItemSimilarity(prepareSimilarityText(leftTitle), prepareSimilarityText(rightTitle));
@@ -63,4 +51,4 @@ export function scorePreparedItemSimilarity(left, right) {
     };
 }
 //# sourceMappingURL=similarity-scoring.js.map
-//# debugId=64312ac7-5a99-5a21-b99f-2bdef1b54a06
+//# debugId=dff9b113-2b29-5154-afbf-f191f2f556a6

package/dist/sdk/workspace-snapshot.d.ts

@@ -19,10 +19,14 @@ declare class WorkspaceLockHeartbeat {
     constructor(lockPath: string, owner: string, ttlSeconds: number);
     /** Begin renewing the lock without keeping the process alive on its own. */
     start(): void;
+    /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
+    refreshNow(): Promise<void>;
     /** Fail the restore before activation when lease ownership was lost. */
     assertHealthy(): void;
     /** Stop future renewals and await the last in-flight atomic write. */
     stop(): Promise<void>;
+    /** Serialize renewal attempts and retain the first ownership failure. */
+    private scheduleRenewal;
     /** Atomically refresh only the lock still owned by this process and actor. */
     private renew;
 }

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!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]="cdde844a-a14a-501d-a45b-18cbd1dd9008")}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]="470bb466-4619-5c54-a154-186b7ef4a049")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -55,19 +55,18 @@ class WorkspaceLockHeartbeat {
     }
     /** Begin renewing the lock without keeping the process alive on its own. */
     start() {
+        this.scheduleRenewal();
         this.timer = setInterval(() => {
-            if (this.refresh !== undefined)
-                return;
-            this.refresh = this.renew()
-                .catch((error) => {
-                this.failure = error;
-            })
-                .finally(() => {
-                this.refresh = undefined;
-            });
+            this.scheduleRenewal();
         }, this.intervalMs);
         this.timer.unref();
     }
+    /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
+    async refreshNow() {
+        this.scheduleRenewal();
+        await this.refresh;
+        this.assertHealthy();
+    }
     /** Fail the restore before activation when lease ownership was lost. */
     assertHealthy() {
         if (this.failure !== undefined) {
@@ -83,6 +82,18 @@ class WorkspaceLockHeartbeat {
         await this.refresh;
         this.assertHealthy();
     }
+    /** Serialize renewal attempts and retain the first ownership failure. */
+    scheduleRenewal() {
+        if (this.refresh !== undefined || this.failure !== undefined)
+            return;
+        this.refresh = this.renew()
+            .catch((error) => {
+            this.failure = error;
+        })
+            .finally(() => {
+            this.refresh = undefined;
+        });
+    }
     /** Atomically refresh only the lock still owned by this process and actor. */
     async renew() {
         const parsed = JSON.parse(await readFile(this.lockPath, "utf8"));
@@ -483,6 +494,7 @@ export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, optio
     const releaseWorkspaceLock = await acquireLock(pmRoot, WORKSPACE_WRITER_LOCK_ID, lockTtlSeconds, author, false, false, lockWaitMs);
     const heartbeat = new WorkspaceLockHeartbeat(getLockPath(pmRoot, WORKSPACE_WRITER_LOCK_ID), author, lockTtlSeconds);
     heartbeat.start();
+    await heartbeat.refreshNow();
     let staging;
     let swapStarted = false;
     let heartbeatStopped = false;
@@ -536,6 +548,7 @@ export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, optio
         await swapWorkspaceSnapshotRootWithActivation(staging, pmRoot, backup, DEFAULT_ATOMIC_OPERATIONS, async () => {
             heartbeat.start();
             heartbeatStopped = false;
+            await heartbeat.refreshNow();
         });
         await heartbeat.stop();
         heartbeatStopped = true;
@@ -596,4 +609,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=cdde844a-a14a-501d-a45b-18cbd1dd9008
+//# debugId=470bb466-4619-5c54-a154-186b7ef4a049

package/docs/AGENT_GUIDE.md

@@ -50,7 +50,9 @@ Repeated singular/plural list flags accumulate, so `--tag a --tag b` is equivale
 
 `--tags` REPLACES the whole tag list. To edit tags without restating the full set, prefer `--add-tags <value>` (adds without replacing) and `--remove-tags <value>` (prunes) on `create`/`update`/`update-many` (both repeatable; CSV or JSON-array). `--remove-tags` is `update`/`update-many` only. Also note `--expected`/`--actual` are short aliases for `--expected-result`/`--actual-result` on these commands, matching `pm close`.
 
-`--acceptance-criteria`/`--ac` likewise REPLACES the whole criteria value. Prefer `--add-ac <text>` (appends one criterion; deduped on exact text) and `--remove-ac <text>` (removes one criterion by exact text; unmatched selectors surface a `remove_ac_unmatched` warning) on `update`/`update-many` so concurrent branch edits with disjoint additions merge instead of clobbering. Acceptance criteria use semicolons as storage boundaries, so one criterion cannot itself contain a semicolon.
+`--acceptance-criteria`/`--ac` likewise explicitly REPLACES the whole criteria value and cannot be combined with `--add-ac` or `--remove-ac`. Prefer `--add-ac <text>` (appends one criterion; deduped on exact text) and `--remove-ac <text>` (removes one criterion by exact text) on `update`/`update-many` so concurrent branch edits with disjoint additions merge instead of clobbering. Every removal must match or the complete mutation fails atomically with structured unmatched-selector recovery. Acceptance criteria use semicolons as storage boundaries, so one criterion cannot itself contain a semicolon.
+
+Local dependency targets supplied to `create`, `update`, or `update-many` must already exist. Mark cross-workspace targets with `source_kind=external`; reserve `--allow-unresolved-deps` for deliberate staged imports and retain its structured warning as evidence.
 
 ```bash
 pm update <item-id> --add-tags urgent,backend   # keep existing tags, add two