@unbrained/pm-cli 2026.8.9 → 2026.8.11

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/telemetry.js

@@ -4,7 +4,7 @@
  * Implements the pm telemetry 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]="150c6ff7-cfb5-542f-bd3d-3c8088d1086a")}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]="ad3110ca-e85b-5a7e-b0a1-591796c298eb")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
@@ -14,6 +14,7 @@ import { nowIso } from "../core/shared/time.js";
 import { resolveGlobalPmRoot } from "../core/store/paths.js";
 import { readSettings, writeSettings } from "../core/store/settings.js";
 import { flushTelemetryQueueNow } from "../core/telemetry/runtime.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
 const TELEMETRY_STATE_RELATIVE_PATH = path.join("runtime", "telemetry", "state.json");
 const TELEMETRY_RUNTIME_RELATIVE_PATH = path.join("runtime", "telemetry");
@@ -161,8 +162,10 @@ const normalizeTelemetrySubcommand = (value) => {
     }
     // `value` is always a defined string here: an undefined subcommand normalizes
     // to "status" above (a valid value) and never reaches this throw.
-    throw new PmCliError(`Unknown pm telemetry subcommand "${value}". Allowed: ${TELEMETRY_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
-        code: "unknown_subcommand",
+    throw createUnknownSubcommandError({
+        command_path: "telemetry",
+        token: value?.trim() || "<empty>",
+        allowed: TELEMETRY_SUBCOMMANDS,
         examples: [
             "pm telemetry status",
             "pm telemetry flush",
@@ -400,4 +403,4 @@ export async function runTelemetry(options, _global) {
     });
 }
 //# sourceMappingURL=telemetry.js.map
-//# debugId=150c6ff7-cfb5-542f-bd3d-3c8088d1086a
+//# debugId=ad3110ca-e85b-5a7e-b0a1-591796c298eb

package/dist/sdk/traceability/runtime-files-lookup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module sdk/traceability/runtime-files-lookup
+ *
+ * Projects transport-neutral action values into reverse source lookup options.
+ */
+import type { FilesLookupOptions } from "../files.js";
+/** Convert bounded MCP/action values into the public files lookup contract. */
+export declare function runtimeFilesLookupOptions(options: Readonly<Record<string, unknown>>, paths: string[], parseInteger: (value: unknown, label: string) => number | undefined): FilesLookupOptions;

package/dist/sdk/traceability/runtime-files-lookup.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]="c2ef0de1-bc44-5550-862c-f3929334fbef")}catch(e){}}();
+import { parseSourceLineRange } from "./source-traceability.js";
+/** Convert bounded MCP/action values into the public files lookup contract. */
+export function runtimeFilesLookupOptions(options, paths, parseInteger) {
+    let lineRange;
+    if (typeof options.lines === "string") {
+        lineRange = parseSourceLineRange(options.lines);
+    }
+    else if (options.lineRange !== undefined) {
+        if (options.lineRange === null ||
+            typeof options.lineRange !== "object" ||
+            Array.isArray(options.lineRange)) {
+            throw new RangeError("Source line range must be an object with numeric start and end values.");
+        }
+        lineRange = parseSourceLineRange(`${String(Reflect.get(options.lineRange, "start"))}:${String(Reflect.get(options.lineRange, "end"))}`);
+    }
+    return {
+        paths,
+        scope: options.scope === "project" || options.scope === "global"
+            ? options.scope
+            : undefined,
+        limit: parseInteger(options.limit, "files lookup limit"),
+        offset: parseInteger(options.offset, "files lookup offset"),
+        noTruncate: options.noTruncate === true,
+        strictRead: options.strictRead === true,
+        explain: options.explain === true,
+        lineRange,
+        decisionDepth: parseInteger(options.decisionDepth, "files lookup decision depth"),
+    };
+}
+//# sourceMappingURL=runtime-files-lookup.js.map
+//# debugId=c2ef0de1-bc44-5550-862c-f3929334fbef

package/dist/sdk/traceability/source-traceability.d.ts

@@ -0,0 +1,102 @@
+import type { ItemMetadata, LinkedFile } from "../../types/index.js";
+/** Inclusive one-based source range accepted by traceability lookup. */
+export interface SourceLineRange {
+    /** First included source line. */
+    start: number;
+    /** Last included source line. */
+    end: number;
+}
+/** One evidence class supporting a source-to-item association. */
+export interface SourceTraceabilityEvidence {
+    /** Evidence producer. */
+    kind: "linked_file" | "git_commit";
+    /** Linked path or abbreviated commit identifier. */
+    reference: string;
+    /** Number of selected lines attributed to this evidence. */
+    contribution_lines?: number;
+}
+/** Rationale fields projected without arbitrary body or comment content. */
+export interface SourceTraceabilityRationale {
+    /** User or project value statement. */
+    value: string | null;
+    /** Recorded timing rationale. */
+    why_now: string | null;
+    /** Recorded intended or achieved outcome. */
+    outcome: string | null;
+    /** Recorded implementation objective. */
+    objective: string | null;
+}
+/** Shortest typed path from source-owning work to a governing decision. */
+export interface SourceDecisionPath {
+    /** Whether a unique decision path was found under the bound. */
+    status: "found" | "ambiguous" | "not_found";
+    /** Ordered item identifiers, including source work and decision. */
+    nodes: string[];
+    /** Relationship kinds connecting consecutive nodes. */
+    kinds: string[];
+    /** Equally short governing decision candidates. */
+    alternative_decision_ids: string[];
+}
+/** Explainable fields added to one reverse linked-file match. */
+export interface SourceTraceabilityExplanation {
+    /** Higher values sort first within the original scheduling priority. */
+    score: number;
+    /** Selected source lines attributable to commits naming this item. */
+    contribution_lines: number;
+    /** Structured evidence supporting the association. */
+    evidence: SourceTraceabilityEvidence[];
+    /** Project rationale carried by the item. */
+    rationale: SourceTraceabilityRationale;
+    /** Governing decision path under the declared graph bound. */
+    decision_path: SourceDecisionPath;
+    /** Honest ambiguity codes; an empty list means no ambiguity was observed. */
+    ambiguities: string[];
+}
+/** Aggregate line-attribution receipt returned beside explained matches. */
+export interface SourceTraceabilityReceipt {
+    /** Inclusive selected range, or null for path-only explanation. */
+    line_range: SourceLineRange | null;
+    /** Number of distinct blamed commits. */
+    blamed_commit_count: number;
+    /** Number of blamed commits whose message named at least one pm item. */
+    mapped_commit_count: number;
+    /** Number of blamed commits without an item reference. */
+    unmapped_commit_count: number;
+    /** Maximum relationship depth searched for a governing decision. */
+    decision_depth: number;
+}
+interface TraceabilityCandidate {
+    item: ItemMetadata;
+    files: LinkedFile[];
+}
+interface GitAttribution {
+    commitLines: Map<string, number>;
+    commitItems: Map<string, string[]>;
+    available: boolean;
+}
+/** Parse an inclusive `start:end` source-line selector. */
+export declare function parseSourceLineRange(value: string): SourceLineRange;
+declare function parseBlameCommits(output: string): Map<string, number>;
+declare function parseCommitItemReferences(output: string): Map<string, string[]>;
+declare function shortestDecisionPath(itemId: string, corpus: readonly ItemMetadata[], maxDepth: number): SourceDecisionPath;
+declare function mappedBlamedCommits(attribution: GitAttribution): string[];
+/** Enrich reverse linked-file candidates with bounded source rationale. */
+export declare function explainSourceTraceability(params: {
+    workspaceRoot: string;
+    paths: readonly string[];
+    candidates: readonly TraceabilityCandidate[];
+    corpus: readonly ItemMetadata[];
+    lineRange?: SourceLineRange;
+    decisionDepth?: number;
+}): Promise<{
+    explanations: Map<string, SourceTraceabilityExplanation>;
+    receipt: SourceTraceabilityReceipt;
+}>;
+/** Internal parser and traversal seams for deterministic boundary tests. */
+export declare const _testOnlySourceTraceability: {
+    mappedBlamedCommits: typeof mappedBlamedCommits;
+    parseBlameCommits: typeof parseBlameCommits;
+    parseCommitItemReferences: typeof parseCommitItemReferences;
+    shortestDecisionPath: typeof shortestDecisionPath;
+};
+export {};

package/dist/sdk/traceability/source-traceability.js

@@ -0,0 +1,293 @@
+/**
+ * @module sdk/source-traceability
+ *
+ * Composes linked-file evidence, bounded Git line attribution, item rationale,
+ * and typed relationship paths into an explainable source-to-work projection.
+ */
+
+!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]="b8b3f729-be32-5a77-b08f-f616ee068e0f")}catch(e){}}();
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { assembleWorkspaceRelationshipGraph } from "../graph/assembly.js";
+function runGit(workspaceRoot, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", [...args], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            maxBuffer: 4 * 1024 * 1024,
+        }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+    });
+}
+function validateLineRange(range) {
+    if (range &&
+        (!Number.isSafeInteger(range.start) ||
+            !Number.isSafeInteger(range.end) ||
+            range.start < 1 ||
+            range.end < range.start)) {
+        throw new RangeError("Source line range must be inclusive positive integers with end >= start.");
+    }
+}
+/** Parse an inclusive `start:end` source-line selector. */
+export function parseSourceLineRange(value) {
+    const match = /^(\d+):(\d+)$/u.exec(value.trim());
+    const range = match
+        ? { start: Number(match[1]), end: Number(match[2]) }
+        : undefined;
+    validateLineRange(range);
+    if (!range) {
+        throw new RangeError("Source line range must use start:end.");
+    }
+    return range;
+}
+function parseBlameCommits(output) {
+    const lines = new Map();
+    for (const row of output.split("\n")) {
+        const commit = /^([0-9a-f^]{40,64}) \d+ \d+(?: \d+)?$/u.exec(row)?.[1];
+        if (commit)
+            lines.set(commit, (lines.get(commit) ?? 0) + 1);
+    }
+    return lines;
+}
+function parseCommitItemReferences(output) {
+    const fields = output.split("\0");
+    const references = new Map();
+    for (let index = 0; index + 1 < fields.length; index += 2) {
+        const commit = fields[index]?.trim();
+        if (!commit)
+            continue;
+        const ids = [
+            ...new Set(fields[index + 1]?.match(/\bpm-[a-z0-9][a-z0-9-]{2,63}\b/gu) ?? []),
+        ].sort((left, right) => left.localeCompare(right));
+        references.set(commit, ids);
+    }
+    return references;
+}
+async function readGitAttribution(params) {
+    const relativePath = path.relative(params.workspaceRoot, path.resolve(params.workspaceRoot, params.sourcePath));
+    const blame = await runGit(params.workspaceRoot, [
+        "blame",
+        "--line-porcelain",
+        "-L",
+        `${params.lineRange.start},${params.lineRange.end}`,
+        "--",
+        relativePath,
+    ]);
+    const log = await runGit(params.workspaceRoot, [
+        "log",
+        "-n",
+        "256",
+        "--format=%H%x00%B%x00",
+        "--",
+        relativePath,
+    ]);
+    return {
+        commitLines: parseBlameCommits(blame),
+        commitItems: parseCommitItemReferences(log),
+        available: true,
+    };
+}
+function expandDecisionPath(params) {
+    const tail = params.current.nodes.at(-1);
+    const nextDepth = params.current.kinds.length + 1;
+    let foundDepth;
+    for (const edge of params.graph.incidentEdges(tail)) {
+        const outgoing = edge.source === tail;
+        const next = outgoing ? edge.target : edge.source;
+        if ((params.visitedDepth.get(next) ?? Number.POSITIVE_INFINITY) < nextDepth)
+            continue;
+        params.visitedDepth.set(next, nextDepth);
+        const definition = params.graph.registry().require(edge.kind);
+        const nextPath = {
+            nodes: [...params.current.nodes, next],
+            kinds: [
+                ...params.current.kinds,
+                outgoing ? edge.kind : (definition.inverse ?? edge.kind),
+            ],
+        };
+        if (params.details.get(next)?.type?.toLowerCase() === "decision") {
+            foundDepth = nextDepth;
+            params.found.push(nextPath);
+        }
+        else {
+            params.queue.push(nextPath);
+        }
+    }
+    return foundDepth;
+}
+function collectDecisionPaths(params) {
+    const queue = [
+        { nodes: [params.itemId], kinds: [] },
+    ];
+    const visitedDepth = new Map([[params.itemId, 0]]);
+    const found = [];
+    let foundDepth;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = current.kinds.length;
+        if (foundDepth !== undefined && depth >= foundDepth)
+            continue;
+        if (depth >= params.maxDepth)
+            continue;
+        foundDepth =
+            expandDecisionPath({
+                current,
+                graph: params.graph,
+                details: params.details,
+                visitedDepth,
+                queue,
+                found,
+            }) ?? foundDepth;
+    }
+    found.sort((left, right) => left.nodes.join("\0").localeCompare(right.nodes.join("\0")));
+    return found;
+}
+function shortestDecisionPath(itemId, corpus, maxDepth) {
+    const assembly = assembleWorkspaceRelationshipGraph(corpus);
+    if (!assembly.graph.hasNode(itemId)) {
+        return {
+            status: "not_found",
+            nodes: [],
+            kinds: [],
+            alternative_decision_ids: [],
+        };
+    }
+    const found = collectDecisionPaths({
+        itemId,
+        maxDepth,
+        graph: assembly.graph,
+        details: new Map(assembly.details.map((detail) => [detail.id, detail])),
+    });
+    const selected = found[0];
+    if (!selected) {
+        return {
+            status: "not_found",
+            nodes: [],
+            kinds: [],
+            alternative_decision_ids: [],
+        };
+    }
+    const decisionIds = [...new Set(found.map((entry) => entry.nodes.at(-1)))];
+    return {
+        status: decisionIds.length === 1 ? "found" : "ambiguous",
+        nodes: selected.nodes,
+        kinds: selected.kinds,
+        alternative_decision_ids: decisionIds.slice(1),
+    };
+}
+async function resolveGitAttribution(params) {
+    if (!params.lineRange) {
+        return {
+            commitLines: new Map(),
+            commitItems: new Map(),
+            available: true,
+        };
+    }
+    try {
+        return await readGitAttribution({
+            workspaceRoot: params.workspaceRoot,
+            sourcePath: params.paths[0],
+            lineRange: params.lineRange,
+        });
+    }
+    catch {
+        return {
+            commitLines: new Map(),
+            commitItems: new Map(),
+            available: false,
+        };
+    }
+}
+function sourceAmbiguities(params) {
+    const ambiguities = [];
+    if (params.hasLineRange && !params.attributionAvailable) {
+        ambiguities.push("git_attribution_unavailable");
+    }
+    if (params.hasLineRange && params.contributionLines === 0) {
+        ambiguities.push("line_attribution_unmapped");
+    }
+    if (params.decisionStatus === "ambiguous") {
+        ambiguities.push("multiple_governing_decisions");
+    }
+    if (params.decisionStatus === "not_found") {
+        ambiguities.push("governing_decision_not_found");
+    }
+    return ambiguities;
+}
+function mappedBlamedCommits(attribution) {
+    return [...attribution.commitLines.keys()].filter((commit) => (attribution.commitItems.get(commit)?.length ?? 0) > 0);
+}
+/** Enrich reverse linked-file candidates with bounded source rationale. */
+export async function explainSourceTraceability(params) {
+    validateLineRange(params.lineRange);
+    const decisionDepth = params.decisionDepth ?? 8;
+    if (!Number.isSafeInteger(decisionDepth) ||
+        decisionDepth < 1 ||
+        decisionDepth > 32) {
+        throw new RangeError("Decision path depth must be an integer from 1 to 32.");
+    }
+    const attribution = await resolveGitAttribution(params);
+    const mappedCommits = mappedBlamedCommits(attribution);
+    const explanations = new Map();
+    for (const candidate of params.candidates) {
+        const attributedCommits = [...attribution.commitLines.entries()].filter(([commit]) => attribution.commitItems.get(commit)?.includes(candidate.item.id));
+        const contributionLines = attributedCommits.reduce((total, [, lines]) => total + lines, 0);
+        const decisionPath = shortestDecisionPath(candidate.item.id, params.corpus, decisionDepth);
+        const ambiguities = sourceAmbiguities({
+            hasLineRange: params.lineRange !== undefined,
+            attributionAvailable: attribution.available,
+            contributionLines,
+            decisionStatus: decisionPath.status,
+        });
+        explanations.set(candidate.item.id, {
+            score: contributionLines * 100 +
+                candidate.files.length * 10 +
+                Math.max(0, 9 -
+                    Math.floor((Date.now() - Date.parse(candidate.item.updated_at)) /
+                        (30 * 24 * 60 * 60 * 1000))),
+            contribution_lines: contributionLines,
+            evidence: [
+                ...candidate.files.map((file) => ({
+                    kind: "linked_file",
+                    reference: file.path,
+                })),
+                ...attributedCommits.map(([commit, lines]) => ({
+                    kind: "git_commit",
+                    reference: commit.slice(0, 12),
+                    contribution_lines: lines,
+                })),
+            ],
+            rationale: {
+                value: candidate.item.value?.trim() || null,
+                why_now: candidate.item.why_now?.trim() || null,
+                outcome: candidate.item.outcome?.trim() || null,
+                objective: candidate.item.objective?.trim() || null,
+            },
+            decision_path: decisionPath,
+            ambiguities,
+        });
+    }
+    return {
+        explanations,
+        receipt: {
+            line_range: params.lineRange ?? null,
+            blamed_commit_count: attribution.commitLines.size,
+            mapped_commit_count: mappedCommits.length,
+            unmapped_commit_count: attribution.commitLines.size - mappedCommits.length,
+            decision_depth: decisionDepth,
+        },
+    };
+}
+/** Internal parser and traversal seams for deterministic boundary tests. */
+export const _testOnlySourceTraceability = {
+    mappedBlamedCommits,
+    parseBlameCommits,
+    parseCommitItemReferences,
+    shortestDecisionPath,
+};
+//# sourceMappingURL=source-traceability.js.map
+//# debugId=b8b3f729-be32-5a77-b08f-f616ee068e0f

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

@@ -743,7 +743,7 @@ export interface HistoryEntry {
     /** Observed agent model identifier, retained in local history. */
     agent_model?: string;
     /** Bounded signal class that supplied `agent_model`. */
-    agent_model_source?: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+    agent_model_source?: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
     /** Privacy-safe fingerprint distinguishing concurrent harness invocations. */
     agent_instance?: string;
     /** Extensible local-only descriptive agent provenance; null means declared but unavailable. */
@@ -751,7 +751,13 @@ export interface HistoryEntry {
         /** Bounded descriptive value observed for this dimension. */
         value: string;
         /** Bounded signal class that supplied the value. */
-        source: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+        source: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
+        /** Confidence attached to a semantic inference. */
+        confidence?: "high" | "medium" | "low";
+        /** Versioned semantic inference rule. */
+        rule_version?: "v2";
+        /** Bounded item and lineage references supporting the inference. */
+        evidence?: readonly string[];
     } | null>>;
     /** Stable declared episode identity; absent on legacy or undeclared events. */
     agent_episode?: {

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="2a2072c1-f4a7-579e-ac11-4c75758d76d3")}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]="605cf12e-6106-563a-abc0-38d648d4aa43")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -241,4 +241,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=2a2072c1-f4a7-579e-ac11-4c75758d76d3
+//# debugId=605cf12e-6106-563a-abc0-38d648d4aa43

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