@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/core/history/replay.js

@@ -4,8 +4,9 @@
  * 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]="ce8dfbdf-8471-5843-8179-5608140330e1")}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]="b0230e20-93c4-531c-9cc1-85f85c1def7a")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
+import { findHistoryIdentityDiscontinuities } from "./identity.js";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
 import { toItemRecord } from "../item/item-record.js";
@@ -190,13 +191,12 @@ function assertHistoryEntryIntegrity(entry, index) {
         throw new TypeError(`${integrityError}:entry_${index + 1}`);
     }
 }
-/** 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. */
 /** Verify a chain and report the explicit or auto-detected item hash epoch. */
 export function verifyHistoryChainWithVersion(entries) {
     let replay = cloneEmptyReplayDocument();
     let detectedVersion;
     let authoritativeExplicitVersion;
-    const errors = [];
+    const errors = findHistoryIdentityDiscontinuities(entries).map((finding) => `verify_failed:duplicate_create:entry_${finding.repeated_create_index}:prior_${finding.prior_genesis_index}`);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
         const explicitVersion = entry.item_hash_version;
@@ -437,4 +437,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=ce8dfbdf-8471-5843-8179-5608140330e1
+//# debugId=b0230e20-93c4-531c-9cc1-85f85c1def7a

package/dist/core/history/version-address.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module core/history/version-address
+ * Stable ordinal addressing for streams whose retained prefix is a checkpoint.
+ */
+import type { HistoryEntry } from "../../types/index.js";
+/**
+ * Return the number added to physical one-based positions to obtain durable
+ * version addresses. Legacy checkpoints cannot prove their original ordinal;
+ * refusing them prevents silently selecting a different historical state.
+ */
+export declare function historyVersionOffset(history: readonly HistoryEntry[], allowUnknown: true): number | null;
+/** Resolve a required durable offset, refusing ambiguous legacy checkpoints. */
+export declare function historyVersionOffset(history: readonly HistoryEntry[], allowUnknown?: false): number;

package/dist/core/history/version-address.js

@@ -0,0 +1,33 @@
+
+!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]="7ad4e6c0-7545-51cb-9af7-4ba1ad4c4758")}catch(e){}}();
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+/** Resolve the checkpoint offset with an explicit opt-in for unknown legacy addresses. */
+export function historyVersionOffset(history, allowUnknown = false) {
+    const first = history[0];
+    if (first?.op !== "history_compact_baseline")
+        return 0;
+    const receipt = first.context?.history_compaction;
+    const offset = typeof receipt === "object" &&
+        receipt !== null &&
+        "version_offset" in receipt
+        ? receipt.version_offset
+        : undefined;
+    if (typeof offset === "number" &&
+        Number.isSafeInteger(offset) &&
+        offset >= 0 &&
+        Number.isSafeInteger(offset + history.length)) {
+        return offset;
+    }
+    if (allowUnknown)
+        return null;
+    throw new PmCliError("This compacted stream has no trustworthy version offset; numeric history addresses are unavailable.", EXIT_CODE.USAGE, {
+        code: "history_version_mapping_unavailable",
+        required: "Use a retained timestamp or recover the pre-compaction stream from version control.",
+        nextSteps: [
+            "Run pm history <id> --full to inspect the retained timestamps and checkpoint evidence.",
+        ],
+    });
+}
+//# sourceMappingURL=version-address.js.map
+//# debugId=7ad4e6c0-7545-51cb-9af7-4ba1ad4c4758

package/dist/core/item/actionability.d.ts

@@ -1,5 +1,8 @@
 import type { RuntimeStatusRegistry } from "../schema/runtime-schema.js";
 import type { ItemMetadata, ItemStatus } from "../../types/index.js";
+import { type ItemTypeRegistry } from "./type-registry.js";
+/** Resolve dispatch semantics once for SDK callers, honoring custom and extension type aliases before built-in defaults. */
+export declare function resolveItemExecutionRole(type: string, registry?: ItemTypeRegistry): "agent" | "human" | "gate";
 /** Built-in ordering kinds that must remain reachable by blocker resolution. */
 export declare const ACTIONABILITY_ORDERING_KINDS: readonly string[];
 /** Collects the blocker item ids declared by an item: the legacy scalar `blocked_by` field plus every `blocked_by` dependency edge. Ids are trimmed, de-duplicated, and returned in stable lexicographic order. This is the single source of truth for "what must close before this item can proceed", shared by `pm next` readiness classification and the close-time auto-unblock sweep. */
@@ -54,11 +57,28 @@ export interface ActionabilityReport {
     ready: ActionableEntry[];
     /** Active leaves with at least one open blocker — waiting to become ready. */
     blocked: ActionableEntry[];
+    /** Active containers with unresolved descendants, including their blocker evidence. */
+    containers: ActionableEntry[];
+    /** Unblocked leaf work that requires a human decision. */
+    decisions: ActionableEntry[];
+    /** Unblocked leaf outcome gates held out of automatic dispatch. */
+    gates: ActionableEntry[];
     /** Active candidates considered before the leaf/blocker split. */
     active_count: number;
     /** Active candidates skipped because they still have open descendants. */
     container_count: number;
 }
+/** Explicit dispatch opt-ins; dependency and lifecycle blocking always remain enforced. */
+export interface ActionabilitySelectionOptions {
+    /** Include human decision work in the executable selection. */
+    includeDecisions?: boolean;
+    /** Include outcome gates in the executable selection. */
+    includeGates?: boolean;
+    /** Include containers whose descendants are still unfinished. */
+    includeContainers?: boolean;
+}
+/** Select dispatch candidates from a classified report while retaining held-out worklists. Ownership and ranking remain caller responsibilities. */
+export declare function selectActionableEntries(report: ActionabilityReport, statusRegistry: RuntimeStatusRegistry, options?: ActionabilitySelectionOptions, typeRegistry?: ItemTypeRegistry): Pick<ActionabilityReport, "ready" | "decisions" | "gates">;
 /**
  * Partitions a candidate set into ready vs blocked leaf work using the corpus to
  * resolve blockers, descendants, and downstream dependents.
@@ -70,4 +90,4 @@ export interface ActionabilityReport {
  * blockers and the non-terminal items it would unblock. Returned lists preserve
  * the candidate order so the caller can apply its own ranking.
  */
-export declare function computeActionabilityReport(candidates: ItemMetadata[], corpus: ItemMetadata[], statusRegistry: RuntimeStatusRegistry): ActionabilityReport;
+export declare function computeActionabilityReport(candidates: ItemMetadata[], corpus: ItemMetadata[], statusRegistry: RuntimeStatusRegistry, typeRegistry?: ItemTypeRegistry): ActionabilityReport;

package/dist/core/item/actionability.js

@@ -10,9 +10,15 @@
  * `blocked_by` resolution a single source of truth.
  */
 
-!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]="0605f770-d868-5fe9-a186-45f00d2e93b4")}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]="7d98ca40-57e8-5afe-8e9d-b694da0130d1")}catch(e){}}();
 import { isTerminalStatus, normalizeStatusForRegistry } from "./status.js";
+import { BUILTIN_ITEM_EXECUTION_ROLES, resolveTypeDefinition } from "./type-registry.js";
 import { isExternalDependencyReference, isExternalDependencySourceKind, } from "./dependency-reference.js";
+/** Resolve dispatch semantics once for SDK callers, honoring custom and extension type aliases before built-in defaults. */
+export function resolveItemExecutionRole(type, registry) {
+    const definition = registry === undefined ? undefined : resolveTypeDefinition(type, registry);
+    return definition?.execution_role ?? BUILTIN_ITEM_EXECUTION_ROLES[type.trim().toLowerCase()] ?? "agent";
+}
 /** Dependency kind that marks "this item is blocked by the referenced item". */
 const BLOCKED_BY_DEPENDENCY_KIND = "blocked_by";
 /** Reverse dependency kind that marks "this item blocks the referenced item". */
@@ -177,6 +183,24 @@ export function collectDependencyBlockedIds(corpus, statusRegistry) {
     }
     return blocked;
 }
+/** Select dispatch candidates from a classified report while retaining held-out worklists. Ownership and ranking remain caller responsibilities. */
+export function selectActionableEntries(report, statusRegistry, options = {}, typeRegistry) {
+    const candidates = [...report.ready, ...report.decisions, ...report.gates];
+    if (options.includeContainers === true) {
+        candidates.push(...report.containers.filter((entry) => entry.open_blockers.length === 0 && !statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(entry.item.status, statusRegistry))));
+    }
+    const selected = { ready: [], decisions: [], gates: [] };
+    for (const entry of candidates) {
+        const role = resolveItemExecutionRole(entry.item.type, typeRegistry);
+        if (role === "human" && options.includeDecisions !== true)
+            selected.decisions.push(entry);
+        else if (role === "gate" && options.includeGates !== true)
+            selected.gates.push(entry);
+        else
+            selected.ready.push(entry);
+    }
+    return selected;
+}
 /** Resolves the registry's active status set, falling back to just the canonical open status when a custom schema declares none — the same safety net `pm context` applies so the report never misclassifies every item as inactive. */
 function resolveActiveStatusSet(statusRegistry) {
     /* c8 ignore start -- fallback applies only to custom schemas that intentionally define zero active statuses */
@@ -242,7 +266,7 @@ function indexCorpus(corpus) {
  * blockers and the non-terminal items it would unblock. Returned lists preserve
  * the candidate order so the caller can apply its own ranking.
  */
-export function computeActionabilityReport(candidates, corpus, statusRegistry) {
+export function computeActionabilityReport(candidates, corpus, statusRegistry, typeRegistry) {
     const { itemsById, childrenByParent, blockedByReverse, blockerIdsByItem } = indexCorpus(corpus);
     const activeStatuses = new Set([
         ...resolveActiveStatusSet(statusRegistry),
@@ -255,16 +279,14 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
         .map((entry) => normalizeItemId(entry.id)));
     const ready = [];
     const blocked = [];
+    const containers = [];
+    const decisions = [];
+    const gates = [];
     let activeCount = 0;
-    let containerCount = 0;
     for (const item of candidates) {
         if (!activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)))
             continue;
         activeCount += 1;
-        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
-            containerCount += 1;
-            continue;
-        }
         const openBlockers = resolveItemBlockersWithIndex(item, itemsById, statusRegistry, blockerIdsByItem).filter((blocker) => !blocker.resolved);
         const unblocks = (blockedByReverse.get(normalizeItemId(item.id)) ?? [])
             .filter((dependentId) => nonTerminalIds.has(normalizeItemId(dependentId)))
@@ -274,9 +296,19 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
             open_blockers: openBlockers,
             unblocks,
         };
+        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
+            containers.push(entry);
+            continue;
+        }
         const lifecycleBlocked = statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(item.status, statusRegistry));
         if (openBlockers.length === 0 && !lifecycleBlocked) {
-            ready.push(entry);
+            const role = resolveItemExecutionRole(item.type, typeRegistry);
+            if (role === "human")
+                decisions.push(entry);
+            else if (role === "gate")
+                gates.push(entry);
+            else
+                ready.push(entry);
         }
         else {
             blocked.push(entry);
@@ -285,9 +317,12 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
     return {
         ready,
         blocked,
+        containers,
+        decisions,
+        gates,
         active_count: activeCount,
-        container_count: containerCount,
+        container_count: containers.length,
     };
 }
 //# sourceMappingURL=actionability.js.map
-//# debugId=0605f770-d868-5fe9-a186-45f00d2e93b4
+//# debugId=7d98ca40-57e8-5afe-8e9d-b694da0130d1

package/dist/core/item/id.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Id.
  */
 
-!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]="6b3f1585-ab12-57ca-80eb-d3cebc384c52")}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]="04f02467-a4ee-5616-9fbf-3df1141efccf")}catch(e){}}();
 import crypto from "node:crypto";
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
@@ -60,11 +60,13 @@ function randomToken(length) {
     }
     return token;
 }
+/** Reserve an identity when either a live item path or its retained history exists. */
 async function idExists(pmRoot, id, typeToFolder) {
     const checks = [...new Set(Object.values(typeToFolder))].flatMap((folder) => [
         path.join(pmRoot, folder, `${id}.md`),
         path.join(pmRoot, folder, `${id}.toon`),
     ]);
+    checks.push(path.join(pmRoot, "history", `${id}.jsonl`));
     return (await Promise.all(checks.map((target) => pathExists(target)))).some(Boolean);
 }
 /** Bounds accepted for the configurable random id token length (`ids.token_length`). */
@@ -95,8 +97,10 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     while (tokenLength <= maxTokenLength) {
         for (let i = 0; i < 32; i += 1) {
             const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;
-            if (options.probeExisting === false ||
-                !(await idExists(pmRoot, id, options.typeToFolder ?? TYPE_TO_FOLDER))) {
+            const occupied = await (options.probeExisting === false
+                ? pathExists(path.join(pmRoot, "history", `${id}.jsonl`))
+                : idExists(pmRoot, id, options.typeToFolder ?? TYPE_TO_FOLDER));
+            if (!occupied) {
                 return id;
             }
             attempts += 1;
@@ -106,4 +110,4 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     throw new Error(`Unable to generate unique id after ${attempts} attempts`);
 }
 //# sourceMappingURL=id.js.map
-//# debugId=6b3f1585-ab12-57ca-80eb-d3cebc384c52
+//# debugId=04f02467-a4ee-5616-9fbf-3df1141efccf

package/dist/core/item/item-type-definition.d.ts

@@ -38,6 +38,8 @@ export interface NormalizeItemTypeDefinitionOptions {
     /** How to resolve a raw policy `command` value (defaults to {@link keepPolicyCommand}). */
     resolvePolicyCommand?: ResolvePolicyCommand;
 }
+/** Validate an execution role before a settings or extension definition enters scheduling. Unknown values fail instead of silently enabling dispatch. */
+export declare function parseItemExecutionRole(value: unknown): ItemTypeDefinition["execution_role"];
 /**
  * Normalize a full {@link ItemTypeDefinition}, returning null when the name is blank.
  *

package/dist/core/item/item-type-definition.js

@@ -15,7 +15,7 @@
  */
 /** Dedupe + sort a string list: trim, drop blanks, unique, locale-sorted. */
 
-!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]="815165a9-27a7-5933-adae-c7e55330c8e4")}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]="f02cb2e7-2d5f-5cc8-8a60-18db78b50da0")}catch(e){}}();
 export function normalizeItemTypeStringList(values) {
     return [
         ...new Set((values ?? [])
@@ -85,6 +85,12 @@ function optionalNonEmptyString(value) {
     const normalized = value?.trim();
     return normalized && normalized.length > 0 ? normalized : undefined;
 }
+/** Validate an execution role before a settings or extension definition enters scheduling. Unknown values fail instead of silently enabling dispatch. */
+export function parseItemExecutionRole(value) {
+    if (value === undefined || value === "agent" || value === "human" || value === "gate")
+        return value;
+    throw new Error("Item type execution_role must be agent, human, or gate.");
+}
 /**
  * Normalize a full {@link ItemTypeDefinition}, returning null when the name is blank.
  *
@@ -113,6 +119,7 @@ export function normalizeItemTypeDefinition(definition, options = {}) {
         name,
         description: optionalNonEmptyString(definition.description),
         default_status: optionalNonEmptyString(definition.default_status),
+        ...(definition.execution_role === undefined ? {} : { execution_role: parseItemExecutionRole(definition.execution_role) }),
         folder: optionalNonEmptyString(definition.folder),
         aliases: aliases.length > 0 ? aliases : undefined,
         required_create_fields: normalizeOptionalStringList(definition.required_create_fields, hasRequiredCreateFields),
@@ -124,4 +131,4 @@ export function normalizeItemTypeDefinition(definition, options = {}) {
     };
 }
 //# sourceMappingURL=item-type-definition.js.map
-//# debugId=815165a9-27a7-5933-adae-c7e55330c8e4
+//# debugId=f02cb2e7-2d5f-5cc8-8a60-18db78b50da0

package/dist/core/item/type-registry.d.ts

@@ -1,5 +1,7 @@
 import type { ExtensionRegistrationRegistry } from "../extensions/loader.js";
-import type { ItemTypeCommandOptionPolicy, ItemTypeOptionDefinition, PmSettings } from "../../types/index.js";
+import type { ItemTypeCommandOptionPolicy, ItemTypeDefinition, ItemTypeOptionDefinition, PmSettings } from "../../types/index.js";
+/** Default dispatch roles for built-in types whose work requires human input or outcome verification. Custom definitions can override these through the same registry. */
+export declare const BUILTIN_ITEM_EXECUTION_ROLES: Readonly<Record<string, "human" | "gate">>;
 /** Fallback required create fields used when callers do not provide an override. */
 export declare const DEFAULT_REQUIRED_CREATE_FIELDS: readonly ["title", "description", "status", "priority", "tags", "body", "deadline", "estimatedMinutes", "acceptanceCriteria", "author", "message", "assignee"];
 /** Fallback required create repeatables used when callers do not provide an override. */
@@ -31,6 +33,8 @@ export interface ResolvedItemTypeDefinition {
     aliases: string[];
     /** Optional per-type status applied at create time when `--status` is omitted. */
     default_status?: string;
+    /** Effective dispatch role; absent legacy definitions are resolved through the built-in defaults. */
+    execution_role?: ItemTypeDefinition["execution_role"];
     /** Value that configures or reports required create fields for this contract. */
     required_create_fields: string[];
     /** Value that configures or reports required create repeatables for this contract. */

package/dist/core/item/type-registry.js

@@ -4,11 +4,13 @@
  * Defines item parsing, formatting, and lifecycle helpers for Type Registry.
  */
 
-!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]="88b2ed4e-b5fd-5014-abf1-c163db033abf")}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]="506efdc7-b04e-5023-ab59-57ede87558f9")}catch(e){}}();
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
 import { ITEM_TYPE_VALUES } from "../../types/index.js";
-import { normalizeItemTypeDefinition as normalizeSharedItemTypeDefinition, normalizeItemTypeStringList, strictPolicyCommand, } from "./item-type-definition.js";
+import { normalizeItemTypeDefinition as normalizeSharedItemTypeDefinition, normalizeItemTypeStringList, strictPolicyCommand, parseItemExecutionRole, } from "./item-type-definition.js";
+/** Default dispatch roles for built-in types whose work requires human input or outcome verification. Custom definitions can override these through the same registry. */
+export const BUILTIN_ITEM_EXECUTION_ROLES = Object.freeze({ decision: "human", milestone: "gate" });
 /** Fallback required create fields used when callers do not provide an override. */
 export const DEFAULT_REQUIRED_CREATE_FIELDS = [
     "title",
@@ -421,6 +423,7 @@ function coerceTypeDefinitionFromUnknown(raw) {
         name,
         description,
         default_status: defaultStatus,
+        execution_role: parseItemExecutionRole(record.execution_role),
         folder,
         aliases: readStringArray(record, "aliases"),
         required_create_fields: readStringArray(record, "required_create_fields"),
@@ -462,6 +465,7 @@ function buildResolvedTypeDefinition(normalizedDefinition, existing) {
         toDefaultFolder(keepName));
     const resolvedDefinition = {
         name: keepName,
+        execution_role: normalizedDefinition.execution_role,
         folder,
         aliases: normalizeItemTypeStringList([
             ...(existing?.aliases ?? []),
@@ -488,7 +492,7 @@ function applyTypeDefinitions(source, target) {
         }
         const lowerName = normalizedDefinition.name.toLowerCase();
         const existing = target.get(lowerName);
-        target.set(lowerName, buildResolvedTypeDefinition(normalizedDefinition, existing));
+        target.set(lowerName, buildResolvedTypeDefinition({ ...normalizedDefinition, execution_role: normalizedDefinition.execution_role ?? existing?.execution_role }, existing));
     }
 }
 function collectExtensionTypeDefinitions(registrations) {
@@ -516,6 +520,7 @@ export function resolveItemTypeRegistry(settings, extensionRegistrations = null)
     for (const builtin of ITEM_TYPE_VALUES) {
         byLowerName.set(builtin.toLowerCase(), {
             name: builtin,
+            execution_role: BUILTIN_ITEM_EXECUTION_ROLES[builtin.toLowerCase()] ?? "agent",
             folder: TYPE_TO_FOLDER[builtin],
             aliases: [],
             required_create_fields: [...DEFAULT_REQUIRED_CREATE_FIELDS],
@@ -708,4 +713,4 @@ export function validateTypeOptions(typeName, rawTypeOptions, registry) {
     };
 }
 //# sourceMappingURL=type-registry.js.map
-//# debugId=88b2ed4e-b5fd-5014-abf1-c163db033abf
+//# debugId=506efdc7-b04e-5023-ab59-57ede87558f9

package/dist/core/output/mutation-projection.js

@@ -19,7 +19,7 @@
  * MCP server, and returns the original reference unchanged when nothing is compacted.
  */
 
-!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]="a3e0573a-01fd-54fb-a568-51c5287b696c")}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]="d6a389b0-7a14-56e7-ac2c-17fcdecc7b29")}catch(e){}}();
 const CHANGED_FIELDS_KEY = "changed_fields";
 const CHANGED_FIELD_COUNT_KEY = "changed_field_count";
 const ROWS_KEY = "rows";
@@ -115,6 +115,7 @@ function projectIdOnlyResult(result) {
         }
         : { id };
 }
+/** Project a recognized item mutation to identity and change counts while preserving warnings and executable recovery. */
 function projectCompactMutationEnvelope(result) {
     if (!isPlainObject(result) || !isPlainObject(result.item))
         return null;
@@ -137,10 +138,15 @@ function projectCompactMutationEnvelope(result) {
             : {}),
         changed_field_count: changedFields.length,
     };
+    appendCompactMutationEvidence(result, result.item, compact);
+    return compact;
+}
+/** Keep lifecycle context, warnings, and executable recovery alongside the compact identity. */
+function appendCompactMutationEvidence(result, item, compact) {
     const closeReason = typeof result.close_reason === "string"
         ? result.close_reason
-        : typeof result.item.close_reason === "string"
-            ? result.item.close_reason
+        : typeof item.close_reason === "string"
+            ? item.close_reason
             : undefined;
     if (closeReason !== undefined)
         compact.close_reason = closeReason;
@@ -149,7 +155,8 @@ function projectCompactMutationEnvelope(result) {
         compact.recurrence = recurrence;
     if (Array.isArray(result.warnings) && result.warnings.length > 0)
         compact.warnings = result.warnings;
-    return compact;
+    if (isPlainObject(result.recovery))
+        compact.recovery = result.recovery;
 }
 function compactUpdateManyRows(envelope) {
     const rows = isUpdateManyMutationEnvelope(envelope)
@@ -208,4 +215,4 @@ export function projectMutationResult(result, options = {}) {
     return changed ? projected : result;
 }
 //# sourceMappingURL=mutation-projection.js.map
-//# debugId=a3e0573a-01fd-54fb-a568-51c5287b696c
+//# debugId=d6a389b0-7a14-56e7-ac2c-17fcdecc7b29

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

@@ -53,6 +53,14 @@ export interface PmCliErrorRecoveryPayload {
 export interface PmCliErrorContext {
     /** Value that configures or reports code for this contract. */
     code?: string;
+    /** Item whose document could not be decoded or parsed. */
+    item_id?: string;
+    /** Exact filesystem path of the unreadable item document. */
+    item_path?: string;
+    /** Original document size before decoding or parsing. */
+    byte_length?: number;
+    /** Whether the original item document contained no bytes. */
+    empty?: boolean;
     /** Stable failure class within the operation-specific error code. */
     reason?: string;
     /** Metadata field responsible for a validation failure, when known. */

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]="922e2e27-1499-5466-98e4-322d0d742e40")}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]="9ab4b378-900c-5a2a-9237-b1d8d4f2ae13")}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=922e2e27-1499-5466-98e4-322d0d742e40
+//# debugId=9ab4b378-900c-5a2a-9237-b1d8d4f2ae13

package/dist/core/store/item-metadata-query-index.js

@@ -4,13 +4,13 @@
  * Maintains a rebuildable SQLite projection for bounded metadata queries.
  */
 
-!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]="97cfeab2-8e3f-5b70-9f64-10494158d141")}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]="530ad63f-f7c5-52c9-9f81-a74b1cd4c36e")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 const QUERY_INDEX_FILENAME = "metadata-query-index.sqlite";
-const QUERY_INDEX_VERSION = "4";
+const QUERY_INDEX_VERSION = "5";
 function loadDatabaseSync(loadModule) {
     try {
         const loaded = loadModule(["node", "sqlite"].join(":"));
@@ -102,6 +102,7 @@ function writeMetadata(database, key, value) {
         .prepare("INSERT INTO metadata(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
         .run(key, value);
 }
+/** Upsert authoritative metadata and replace dependent search, key and linked-file rows in the caller transaction. */
 function insertRow(database, row) {
     const metadata = row.metadata;
     database
@@ -128,10 +129,12 @@ function insertRow(database, row) {
     database
         .prepare("DELETE FROM item_linked_files WHERE item_id = ?")
         .run(metadata.id);
-    database.prepare("DELETE FROM item_search WHERE id = ?").run(metadata.id);
+    // FTS UNINDEXED columns cannot provide identity lookup. Share the items rowid
+    // so both rebuilding and incremental maintenance use a single indexed row.
+    database.prepare("DELETE FROM item_search WHERE rowid = (SELECT rowid FROM items WHERE id = ?)").run(metadata.id);
     database
-        .prepare("INSERT INTO item_search(id, title, description, tags) VALUES (?, ?, ?, ?)")
-        .run(metadata.id, metadata.title, metadata.description, metadata.tags.join(" "));
+        .prepare("INSERT INTO item_search(rowid, id, title, description, tags) SELECT rowid, ?, ?, ?, ? FROM items WHERE id = ?")
+        .run(metadata.id, metadata.title, metadata.description, metadata.tags.join(" "), metadata.id);
     const insertMetadataKey = database.prepare("INSERT INTO item_metadata_keys(item_id, key) VALUES (?, ?)");
     for (const key of Object.keys(metadata)) {
         insertMetadataKey.run(metadata.id, key);
@@ -203,13 +206,13 @@ export async function updateItemMetadataQueryIndex(options) {
         }
         database.exec("BEGIN IMMEDIATE");
         const deleteByPath = database.prepare("DELETE FROM items WHERE relative_path = ?");
-        const findIdByPath = database.prepare("SELECT id FROM items WHERE relative_path = ?");
-        const deleteSearchById = database.prepare("DELETE FROM item_search WHERE id = ?");
+        const findRowidByPath = database.prepare("SELECT rowid FROM items WHERE relative_path = ?");
+        const deleteSearchByRowid = database.prepare("DELETE FROM item_search WHERE rowid = ?");
         for (const relativePath of options.deletedRelativePaths ?? []) {
-            const deleted = findIdByPath.get(relativePath);
+            const deleted = findRowidByPath.get(relativePath);
             deleteByPath.run(relativePath);
             if (deleted)
-                deleteSearchById.run(deleted.id);
+                deleteSearchByRowid.run(deleted.rowid);
         }
         if (options.row)
             insertRow(database, options.row);
@@ -470,4 +473,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=item-metadata-query-index.js.map
-//# debugId=97cfeab2-8e3f-5b70-9f64-10494158d141
+//# debugId=530ad63f-f7c5-52c9-9f81-a74b1cd4c36e

package/dist/core/store/item-metadata-read-work.d.ts

@@ -0,0 +1,19 @@
+/** Logical metadata work, independent of output projection and cache hit rate. */
+export interface ItemMetadataReadWork {
+    /** Completed full, light, or body-bearing item-store enumeration calls. */
+    enumeration_calls: number;
+    /** Metadata rows returned by those calls, counting repeated enumeration. */
+    metadata_rows: number;
+}
+/** Record completed enumeration in each enclosing measurement, without retaining item data. */
+export declare function recordItemMetadataEnumeration(rowCount: number): void;
+/**
+ * Measure an awaited operation without changing its result or failure semantics.
+ * Concurrent roots remain isolated; nested measurements also contribute to their
+ * parents. The returned snapshot excludes work completed after the operation.
+ * Counters cover filesystem item-store enumeration APIs, not arbitrary host I/O.
+ */
+export declare function measureItemMetadataReadWork<T>(operation: () => T | Promise<T>): Promise<{
+    result: T;
+    work: Readonly<ItemMetadataReadWork>;
+}>;

package/dist/core/store/item-metadata-read-work.js

@@ -0,0 +1,44 @@
+/**
+ * @module core/store/item-metadata-read-work
+ *
+ * Measures successful filesystem metadata enumerations within one async SDK
+ * operation. Cache hits count too: materializing a cached corpus is still work.
+ */
+
+!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]="1cd39e2f-41c7-5005-925d-d4539cda15d3")}catch(e){}}();
+import { AsyncLocalStorage } from "node:async_hooks";
+import { channel } from "node:diagnostics_channel";
+const observers = new AsyncLocalStorage();
+const enumerations = channel("@unbrained/pm-cli/item-metadata-enumeration/v1");
+/** Record completed enumeration in each enclosing measurement, without retaining item data. */
+export function recordItemMetadataEnumeration(rowCount) {
+    enumerations.publish(rowCount);
+}
+/**
+ * Measure an awaited operation without changing its result or failure semantics.
+ * Concurrent roots remain isolated; nested measurements also contribute to their
+ * parents. The returned snapshot excludes work completed after the operation.
+ * Counters cover filesystem item-store enumeration APIs, not arbitrary host I/O.
+ */
+export async function measureItemMetadataReadWork(operation) {
+    const work = { enumeration_calls: 0, metadata_rows: 0 };
+    // A named channel crosses the published query/bundled runtime boundary;
+    // async membership prevents concurrent roots from counting each other's work.
+    /** Count notifications only while this measurement belongs to the active async scope. */
+    const observe = (message) => {
+        if (observers.getStore()?.includes(work)) {
+            work.enumeration_calls += 1;
+            work.metadata_rows += message;
+        }
+    };
+    enumerations.subscribe(observe);
+    try {
+        const result = await observers.run([...(observers.getStore() ?? []), work], operation);
+        return { result, work: { ...work } };
+    }
+    finally {
+        enumerations.unsubscribe(observe);
+    }
+}
+//# sourceMappingURL=item-metadata-read-work.js.map
+//# debugId=1cd39e2f-41c7-5005-925d-d4539cda15d3

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

@@ -25,6 +25,20 @@ export declare function readLocatedItem(item: LocatedItem, options?: {
     raw: string;
     document: ItemDocument;
 }>;
+/**
+ * Read once and retain a recoverable parse failure beside its exact text snapshot.
+ * Filesystem and merge-conflict errors still throw; callers must explicitly
+ * reconstruct an invalid document before performing any mutation.
+ */
+export declare function readLocatedItemSnapshot(item: LocatedItem, options?: Parameters<typeof readLocatedItem>[1]): Promise<{
+    raw: string;
+    document: ItemDocument;
+    error: null;
+} | {
+    raw: string;
+    document: null;
+    error: PmCliError;
+}>;
 /** Implements list all item metadata for the public runtime surface of this module. */
 export declare function listAllItemMetadata(pmRoot: string, preferredFormat?: ItemFormat, typeToFolder?: Record<string, string>, warnings?: string[], schema?: RuntimeSchemaSettings): Promise<ItemMetadata[]>;
 /**