@unbrained/pm-cli 2026.9.3 → 2026.9.5

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

@@ -25,6 +25,15 @@ export interface ProcessIdentity {
 declare function parseLockInfo(raw: string): LockReadResult;
 declare function readLockInfo(lockPath: string, emitReadHook?: boolean): Promise<LockReadResult>;
 declare function isErrno(error: unknown, code: string): boolean;
+/**
+ * Classify exclusive-create failures that prove another lock lifecycle is in
+ * flight. Windows can report `EPERM`, `EACCES`, or `EBUSY` while a just-unlinked
+ * lock is still delete-pending; treating those as fatal makes bounded lock
+ * waiting fail nondeterministically. Existing paths are contention on every
+ * host. A missing or temporarily unstatable Windows path is contention only
+ * when its parent remains writable, preserving genuine permission failures.
+ */
+declare function isLockCreateContention(error: unknown, lockPath: string, platform?: NodeJS.Platform): Promise<boolean>;
 declare function buildLockPayload(id: string, owner: string, ttlSeconds: number, token?: string): LockInfo;
 declare function isStaleLock(info: LockInfo | null, ttlSeconds: number): boolean;
 declare function lockOwnerSuffix(info: LockInfo | null): string;
@@ -57,6 +66,7 @@ export declare const _testOnly: {
     parseLockInfo: typeof parseLockInfo;
     readLockInfo: typeof readLockInfo;
     isErrno: typeof isErrno;
+    isLockCreateContention: typeof isLockCreateContention;
     buildLockPayload: typeof buildLockPayload;
     isStaleLock: typeof isStaleLock;
     lockOwnerSuffix: typeof lockOwnerSuffix;

package/dist/core/lock/lock.js

@@ -4,8 +4,9 @@
  * Coordinates tracker lock ownership and cleanup for Lock.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7352375d-55f2-5751-934e-ba0cd5c358d5")}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]="b21a63b8-9da9-5c7c-b288-3a2dae342bef")}catch(e){}}();
 import { isFileMissingError } from "../fs/fs-utils.js";
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -95,6 +96,43 @@ function isErrno(error, code) {
         "code" in error &&
         error.code === code);
 }
+/**
+ * Classify exclusive-create failures that prove another lock lifecycle is in
+ * flight. Windows can report `EPERM`, `EACCES`, or `EBUSY` while a just-unlinked
+ * lock is still delete-pending; treating those as fatal makes bounded lock
+ * waiting fail nondeterministically. Existing paths are contention on every
+ * host. A missing or temporarily unstatable Windows path is contention only
+ * when its parent remains writable, preserving genuine permission failures.
+ */
+async function isLockCreateContention(error, lockPath, platform = process.platform) {
+    if (isErrno(error, "EEXIST"))
+        return true;
+    if (!isErrno(error, "EPERM") &&
+        !isErrno(error, "EACCES") &&
+        !isErrno(error, "EBUSY")) {
+        return false;
+    }
+    try {
+        await fs.lstat(lockPath);
+        return true;
+    }
+    catch (probeError) {
+        if (platform !== "win32" ||
+            (!isFileMissingError(probeError) &&
+                !isErrno(probeError, "EPERM") &&
+                !isErrno(probeError, "EACCES") &&
+                !isErrno(probeError, "EBUSY"))) {
+            return false;
+        }
+    }
+    try {
+        await fs.access(path.dirname(lockPath), fsConstants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function emitLockWriteHook(lockPath, op) {
     await runActiveOnWriteHooks({
         path: lockPath,
@@ -464,6 +502,7 @@ export const _testOnly = {
     parseLockInfo,
     readLockInfo,
     isErrno,
+    isLockCreateContention,
     buildLockPayload,
     isStaleLock,
     lockOwnerSuffix,
@@ -515,7 +554,7 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
             };
         }
         catch (error) {
-            if (!isErrno(error, "EEXIST")) {
+            if (!(await isLockCreateContention(error, lockPath))) {
                 throw new PmCliError(`Failed to acquire lock for ${id}: ${toErrorMessage(error)}`, EXIT_CODE.GENERIC_FAILURE);
             }
             let lockInfo = await readLockInfo(lockPath);
@@ -549,4 +588,4 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
     }
 }
 //# sourceMappingURL=lock.js.map
-//# debugId=7352375d-55f2-5751-934e-ba0cd5c358d5
+//# debugId=b21a63b8-9da9-5c7c-b288-3a2dae342bef

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

@@ -26,7 +26,7 @@ export interface AgentProvenanceObservation {
  */
 export type AgentProvenance = Readonly<Record<string, AgentProvenanceObservation | null>>;
 /** Bounded reason explaining why one declared provenance dimension was absent. */
-export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_failed" | "resolver_not_configured" | "probes_disabled" | "invalid_value";
+export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_input_missing" | "resolver_failed" | "resolver_not_configured" | "probes_disabled" | "invalid_value";
 /** Machine-readable resolution outcome for one provenance dimension. */
 export interface AgentProvenanceOutcome {
     /** Whether the dimension resolved without retaining private source material. */
@@ -168,6 +168,8 @@ export interface HarnessDetectionSignals {
     cwd?: string;
     /** Home directory override used by embedders and isolated tests. */
     home_dir?: string;
+    /** Explicit harness-owned session file supplied by an embedding host. */
+    session_file?: string;
 }
 /** Built-in agent descriptors evaluated before package and workspace additions. */
 export declare const BUILTIN_HARNESS_SIGNAL_DESCRIPTORS: readonly HarnessSignalDescriptor[];

package/dist/core/shared/author.js

@@ -4,7 +4,7 @@
  * Provides shared primitives and utilities for Author.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cf550961-0040-5e04-9d8d-16e316027e43")}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]="dfbf4eb8-1f02-5880-a70a-0e7ed9b9784a")}catch(e){}}();
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -12,6 +12,7 @@ import os from "node:os";
 import path from "node:path";
 import { resolveAgentSessionContextFromSignals, } from "./agent-session-context.js";
 import { readAgentSemanticAttributionSync, } from "../session/session-state.js";
+import { isFileAbsentError } from "../fs/fs-utils.js";
 /** Stable built-in provenance dimensions understood by the default runtime. */
 export const AGENT_PROVENANCE_DIMENSIONS = [
     "model",
@@ -357,18 +358,83 @@ function parseClaudeProvenanceLine(line) {
     }
     return Object.freeze({ model, version });
 }
-function readClaudeSessionProvenance(dimension, signals, env) {
+/** Classify one candidate without following symlinks or leaking filesystem detail. */
+function claudeTranscriptCandidateStatus(candidate) {
+    try {
+        return fs.lstatSync(candidate).isFile() ? "available" : "missing";
+    }
+    catch (error) {
+        return isFileAbsentError(error) ? "missing" : "failed";
+    }
+}
+/** Resolve a bounded cross-workspace Claude transcript discovery result. */
+function discoverClaudeSessionFile(projectsRoot, session) {
+    let discovered;
+    try {
+        discovered = fs
+            .readdirSync(projectsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .slice(0, 512)
+            .map((entry) => {
+            const candidate = path.join(projectsRoot, entry.name, `${session}.jsonl`);
+            return {
+                candidate,
+                status: claudeTranscriptCandidateStatus(candidate),
+            };
+        });
+    }
+    catch (error) {
+        return { status: isFileAbsentError(error) ? "missing" : "failed" };
+    }
+    const matches = discovered
+        .filter(({ status }) => status === "available")
+        .map(({ candidate }) => candidate);
+    if (matches.length === 0) {
+        return {
+            status: discovered.some(({ status }) => status === "failed")
+                ? "failed"
+                : "missing",
+        };
+    }
+    if (matches.length > 1)
+        return { status: "ambiguous" };
+    return { status: "available", path: matches[0] };
+}
+/** Resolve one Claude transcript by stable session identity without exposing its path. */
+function resolveClaudeSessionFile(signals, env) {
     const session = nonBlank(env.CLAUDE_CODE_SESSION_ID);
-    if (!session || !/^[A-Za-z0-9_-]{1,128}$/u.test(session))
-        return undefined;
+    if (!session || !/^[A-Za-z0-9_-]{1,128}$/u.test(session)) {
+        return { status: "unavailable" };
+    }
     const workspace = path.resolve(signals.cwd ?? process.cwd());
     const encodedWorkspace = workspace.replaceAll(/[^A-Za-z0-9-]/gu, "-");
-    const sessionPath = path.join(signals.home_dir ?? os.homedir(), ".claude", "projects", encodedWorkspace, `${session}.jsonl`);
+    const projectsRoot = path.join(signals.home_dir ?? os.homedir(), ".claude", "projects");
+    const directPath = path.join(projectsRoot, encodedWorkspace, `${session}.jsonl`);
+    const explicitPath = nonBlank(signals.session_file);
+    const suppliedPath = explicitPath && path.basename(explicitPath) === `${session}.jsonl`
+        ? explicitPath
+        : undefined;
+    for (const candidate of [suppliedPath, directPath]) {
+        if (!candidate)
+            continue;
+        const status = claudeTranscriptCandidateStatus(candidate);
+        if (status === "available")
+            return { status, path: candidate };
+        if (status === "failed")
+            return { status };
+    }
+    return discoverClaudeSessionFile(projectsRoot, session);
+}
+function readClaudeSessionProvenance(dimension, signals, env) {
+    const resolution = resolveClaudeSessionFile(signals, env);
+    if (resolution.status !== "available")
+        return undefined;
     try {
-        const file = fs.openSync(sessionPath, "r");
+        const file = fs.openSync(resolution.path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
         try {
             const stats = fs.fstatSync(file);
-            const cacheKey = `${sessionPath}\u0000${stats.size}\u0000${stats.mtimeMs}`;
+            const cacheKey = `${resolution.path}\u0000${stats.size}\u0000${stats.mtimeMs}`;
             const cached = claudeProvenanceSnapshotCache.get(cacheKey);
             if (cached)
                 return cached[dimension];
@@ -553,14 +619,20 @@ function resolveProvenanceProbe(dimension, signals, env, descriptor) {
     }
     return undefined;
 }
-function provenanceResolverHasInput(resolver, descriptor, env) {
+function provenanceResolverHasInput(resolver, descriptor, signals, env) {
     if (resolver === "ai_agent_version") {
         const value = nonBlank(env.AI_AGENT);
-        return (value !== undefined && literalSignalMatches(value, descriptor.harness));
+        return value !== undefined &&
+            literalSignalMatches(value, descriptor.harness)
+            ? "available"
+            : "unavailable";
+    }
+    if (resolver === "codex_session_file") {
+        return nonBlank(env.CODEX_THREAD_ID) !== undefined
+            ? "available"
+            : "unavailable";
     }
-    return resolver === "codex_session_file"
-        ? nonBlank(env.CODEX_THREAD_ID) !== undefined
-        : nonBlank(env.CLAUDE_CODE_SESSION_ID) !== undefined;
+    return resolveClaudeSessionFile(signals, env).status;
 }
 function effectiveHarnessDetectionSignals(signals) {
     if (signals)
@@ -907,7 +979,17 @@ export function detectAgentIdentity(signals) {
     ];
     return Object.fromEntries(entries.filter((entry) => entry[1] !== undefined));
 }
-function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, invalidValue) {
+/** Classify one configured resolver's privacy-safe absence outcome. */
+function provenanceResolverAbsence(resolverInput) {
+    if (resolverInput === "unavailable") {
+        return { status: "unavailable", reason: "harness_unavailable" };
+    }
+    if (resolverInput === "missing") {
+        return { status: "unavailable", reason: "resolver_input_missing" };
+    }
+    return { status: "failed", reason: "resolver_failed" };
+}
+function resolveProvenanceOutcome(dimension, identity, descriptor, signals, env, probesEnabled, invalidValue) {
     const resolver = descriptor?.provenance_resolvers[dimension];
     if (identity.provenance?.[dimension]) {
         return {
@@ -924,14 +1006,20 @@ function resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEn
         };
     }
     if (resolver) {
-        const resolverHasInput = provenanceResolverHasInput(resolver, descriptor, env);
-        const status = resolverHasInput && probesEnabled ? "failed" : "unavailable";
-        const reason = !resolverHasInput
-            ? "harness_unavailable"
-            : probesEnabled
-                ? "resolver_failed"
-                : "probes_disabled";
-        return { status, reason, resolver, rule_version: "v1" };
+        if (!probesEnabled) {
+            return {
+                status: "unavailable",
+                reason: "probes_disabled",
+                resolver,
+                rule_version: "v1",
+            };
+        }
+        const resolverInput = provenanceResolverHasInput(resolver, descriptor, signals, env);
+        return {
+            ...provenanceResolverAbsence(resolverInput),
+            resolver,
+            rule_version: "v1",
+        };
     }
     return {
         status: descriptor?.provenance_unavailable_dimensions.includes(dimension)
@@ -972,7 +1060,7 @@ export function diagnoseAgentIdentity(signals) {
     });
     const outcomes = Object.fromEntries(AGENT_PROVENANCE_DIMENSIONS.map((dimension) => [
         dimension,
-        resolveProvenanceOutcome(dimension, identity, descriptor, env, probesEnabled, dimension === "role" && invalidRoleValue),
+        resolveProvenanceOutcome(dimension, identity, descriptor, effectiveSignals, env, probesEnabled, dimension === "role" && invalidRoleValue),
     ]));
     return { ...identity, provenance_outcomes: outcomes };
 }
@@ -1082,4 +1170,4 @@ export function resolveAuthor(candidate, fallback) {
     return identity.author;
 }
 //# sourceMappingURL=author.js.map
-//# debugId=cf550961-0040-5e04-9d8d-16e316027e43
+//# debugId=dfbf4eb8-1f02-5880-a70a-0e7ed9b9784a

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-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[]>;
 /**

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

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="bffd3114-3e85-58ae-90c7-eea5069cdb89")}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]="c3390c01-c153-5baa-b9bd-07ea8d34828f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -18,6 +18,7 @@ import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "..
 import { resolveItemTypeRegistry } from "../item/type-registry.js";
 import { acquireLock } from "../lock/lock.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
+import { isUtf8 } from "node:buffer";
 import { normalizeItemId, normalizeRawItemId } from "../item/id.js";
 import { acquireItemMetadataDerivedIndexLock, listAllDocumentCandidatesCached, listAllDocumentsCached, listAllDocumentsCachedLight, refreshItemMetadataDerivedIndex, } from "./item-metadata-cache.js";
 import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS } from "./paths.js";
@@ -96,18 +97,55 @@ export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredForma
 }
 /** Implements read located item for the public runtime surface of this module. */
 export async function readLocatedItem(item, options = {}) {
-    const raw = await fs.readFile(item.itemPath, "utf8");
+    const snapshot = await readLocatedItemSnapshot(item, options);
+    if (snapshot.error !== null)
+        throw snapshot.error;
+    return { raw: snapshot.raw, document: snapshot.document };
+}
+/**
+ * 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 async function readLocatedItemSnapshot(item, options = {}) {
+    const bytes = await fs.readFile(item.itemPath);
+    if (!isUtf8(bytes)) {
+        throw new PmCliError("Item contains invalid UTF-8; preserve a binary backup before recovering it.", EXIT_CODE.CONFLICT, { code: "item_document_encoding_invalid", item_id: item.id, item_path: item.itemPath, byte_length: bytes.length, empty: false });
+    }
+    const raw = bytes.toString("utf8");
     await runActiveOnReadHooks({
         path: item.itemPath,
         scope: "project",
     });
-    const document = parseItemDocument(raw, {
-        format: item.item_format,
-        schema: options.schema,
-        extensionFieldNames: resolveActiveExtensionFieldNames(options.extensionFieldNames),
-        onWarning: (warning) => appendWarning(options.warnings, warning),
-    });
-    return { raw, document };
+    let document;
+    try {
+        document = parseItemDocument(raw, {
+            format: item.item_format,
+            schema: options.schema,
+            extensionFieldNames: resolveActiveExtensionFieldNames(options.extensionFieldNames),
+            onWarning: (warning) => appendWarning(options.warnings, warning),
+        });
+    }
+    catch (error) {
+        if (error instanceof PmCliError && error.code === "item_document_invalid") {
+            return {
+                raw,
+                document: null,
+                error: new PmCliError(`Cannot read ${item.id} at ${item.itemPath}${bytes.length === 0 ? " (zero-length file)" : ""}: ${error.message}`, error.exitCode, {
+                    ...error.context,
+                    item_id: item.id,
+                    item_path: item.itemPath,
+                    byte_length: bytes.length,
+                    empty: bytes.length === 0,
+                    nextSteps: [
+                        `Run pm history ${item.id} --full, then pm restore ${item.id} <version> to recover a recorded state.`,
+                    ],
+                }),
+            };
+        }
+        throw error;
+    }
+    return { raw, document, error: null };
 }
 /** Implements list all item metadata for the public runtime surface of this module. */
 export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
@@ -649,4 +687,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=bffd3114-3e85-58ae-90c7-eea5069cdb89
+//# debugId=c3390c01-c153-5baa-b9bd-07ea8d34828f

package/dist/core/store/settings-validator.js

@@ -12,7 +12,7 @@
  * byte-identical to the previous implementation.
  */
 
-!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]="0e135793-d2ed-505b-b73e-6db55218d8af")}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]="c9cac741-16ba-5466-806f-bf8881a2ffa2")}catch(e){}}();
 import { GOVERNANCE_PRESET_VALUES, RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, RUNTIME_STATUS_ROLE_VALUES, RUNTIME_UNKNOWN_FIELD_POLICY_VALUES, } from "../../types.js";
 // Generic over `never` so it is assignable to every `Outcome<T>`.
 const FAIL = { ok: false };
@@ -137,6 +137,7 @@ const itemTypeDefinition = vObject({
     // Per-type create-time default status (config-driven); preserved so inline
     // settings.item_types.definitions behave identically to schema/types.json.
     default_status: vOptional(vString),
+    execution_role: vOptional(vLiteral("agent", "human", "gate")),
     folder: vOptional(vString),
     aliases: vOptional(vArray(vString)),
     required_create_fields: vOptional(vArray(vString)),
@@ -418,4 +419,4 @@ export function validateSettings(raw) {
     return { success: true, data: result.value };
 }
 //# sourceMappingURL=settings-validator.js.map
-//# debugId=0e135793-d2ed-505b-b73e-6db55218d8af
+//# debugId=c9cac741-16ba-5466-806f-bf8881a2ffa2

package/dist/sdk/actionability.d.ts

@@ -7,4 +7,4 @@
  * blocker or ready-work classifications without storage or rendering side
  * effects.
  */
-export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, resolveItemExecutionRole, selectActionableEntries, type ActionabilitySelectionOptions, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";

package/dist/sdk/actionability.js

@@ -8,7 +8,7 @@
  * effects.
  */
 
-!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]="cc271a73-9767-54bb-a142-d4d4569e3c6a")}catch(e){}}();
-export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, } from "../core/item/actionability.js";
+!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]="7d393eb0-d24d-55d2-8e4e-e94805d91784")}catch(e){}}();
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, resolveItemExecutionRole, selectActionableEntries, } from "../core/item/actionability.js";
 //# sourceMappingURL=actionability.js.map
-//# debugId=cc271a73-9767-54bb-a142-d4d4569e3c6a
+//# debugId=7d393eb0-d24d-55d2-8e4e-e94805d91784