@unbrained/pm-cli 2026.9.4 → 2026.9.6

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

@@ -267,6 +267,15 @@ interface ContextAgendaSummary {
     scheduled: number;
 }
 interface ContextSummary {
+    /** Population counters honor item filters and parent scope, never output limits. */
+    scope?: "matching_items";
+    /** Counts for the bounded focus selection, separate from the matching population. */
+    returned_focus?: {
+        active_items: number;
+        in_progress: number;
+        open: number;
+        blocked: number;
+    };
     active_items: number;
     in_progress: number;
     open: number;

package/dist/sdk/query/context.js

@@ -4,9 +4,10 @@
  * Implements the pm context command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="56205e5f-fc26-59ab-abdf-45bdcaf1c263")}catch(e){}}();
-import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
-import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
+!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]="4f8e82a2-f4ea-5ecb-8ef5-3ca795cdeda5")}catch(e){}}();
+import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, resolveItemTypeRegistry, } from "../runtime-primitives.js";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { collectDependencyBlockedIds, resolveItemBlockers, resolveItemExecutionRole, computeActionabilityReport, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
 import { parseIntegerLimit } from "./parsers.js";
 import { runCalendar, } from "./calendar.js";
@@ -1201,7 +1202,6 @@ function buildUnpaginatedContextListOptions(baseListOptions, extra) {
     };
 }
 async function loadContextCorpus(global, runtime) {
-    const needsAllItems = contextNeedsAllItems(runtime.sectionsIncluded);
     // One full-corpus scan serves every consumer: runList always reads all item
     // files before filtering, so deriving the non-terminal subset in memory is
     // free and keeps terminal blocker targets available for the shared
@@ -1211,9 +1211,7 @@ async function loadContextCorpus(global, runtime) {
     }), global);
     const fullCorpus = listed.items;
     let listedItemMetadata = fullCorpus.filter((item) => !isTerminalStatus(item.status, runtime.statusRegistry));
-    let allItems = needsAllItems || runtime.parentScope !== undefined
-        ? fullCorpus
-        : listedItemMetadata;
+    let allItems = fullCorpus;
     const subtreeIds = resolveContextSubtreeIds(runtime.parentScope, fullCorpus);
     if (subtreeIds) {
         listedItemMetadata = listedItemMetadata.filter((item) => subtreeIds.has(item.id.trim().toLowerCase()));
@@ -1231,7 +1229,14 @@ function resolveContextSubtreeIds(parentScope, fullCorpus) {
     }
     return subtree.ids;
 }
-async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpus, blockedIds, statusRegistry, sectionsIncluded, limit, now, author, cursor, cursorFingerprint, useBoundedPage, pmRoot, tokenBudget, claimFocus) {
+/** Classify strategic and human-directed context through the shared execution rules. */
+function collectHighLevelContextIds(activeItems, fullCorpus, statusRegistry, typeRegistry) {
+    const containers = new Set(computeActionabilityReport(activeItems, fullCorpus, statusRegistry, typeRegistry)
+        .containers.map((entry) => entry.item.id));
+    return new Set(activeItems.filter((item) => HIGH_LEVEL_TYPES.has(item.type) || containers.has(item.id) ||
+        resolveItemExecutionRole(item.type, typeRegistry) !== "agent").map((item) => item.id));
+}
+async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpus, blockedIds, statusRegistry, sectionsIncluded, limit, now, author, cursor, cursorFingerprint, useBoundedPage, pmRoot, tokenBudget, claimFocus, typeRegistry) {
     const structural = [...listedItemMetadata].sort((left, right) => compareCriticalItems(left, right, statusRegistry));
     const usage = await readContextUsageAffinity({
         pmRoot,
@@ -1293,12 +1298,13 @@ async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpu
             .map((blocker) => blocker.id);
         return focus;
     };
+    const highLevelIds = collectHighLevelContextIds(activeItems, fullCorpus, statusRegistry, typeRegistry);
     const highLevel = activeItems
-        .filter((item) => HIGH_LEVEL_TYPES.has(item.type))
+        .filter((item) => highLevelIds.has(item.id))
         .slice(0, useBoundedPage ? focusPage.length : limit)
         .map(projectFocusItem);
     const lowLevel = activeItems
-        .filter((item) => !HIGH_LEVEL_TYPES.has(item.type))
+        .filter((item) => !highLevelIds.has(item.id))
         .slice(0, useBoundedPage ? focusPage.length : limit)
         .map(projectFocusItem);
     const blockedFallbackUsed = rankedActiveItems.length === 0;
@@ -1409,12 +1415,16 @@ async function buildOptionalContextSections(params) {
         tests: has("tests") ? buildTestHealth(focusGroups.activeItems) : undefined,
     };
 }
-function buildContextSummaryExtras(needsAllItems, allItems, statusRegistry) {
-    if (!needsAllItems) {
-        return {};
-    }
+function buildContextSummaryExtras(allItems, statusRegistry, blockedIds) {
     const canceledStatus = normalizeStatusInput("canceled", statusRegistry);
+    const activeItems = allItems.filter((item) => statusRegistry.active_statuses.has(normalizeStatusForRegistry(item.status, statusRegistry)));
+    const inProgress = countContextStatus(activeItems, statusRegistry.in_progress_status, statusRegistry);
     return {
+        scope: "matching_items",
+        active_items: activeItems.length,
+        open: activeItems.length - inProgress,
+        in_progress: inProgress,
+        blocked: allItems.filter((item) => blockedIds.has(item.id.trim().toLowerCase())).length,
         total_items: allItems.length,
         closed: allItems.filter((item) => isClosedStatus(item.status, statusRegistry)).length,
         canceled: allItems.filter((item) => normalizeStatusForRegistry(item.status, statusRegistry) ===
@@ -1595,7 +1605,7 @@ export async function runContext(options, global) {
     // Single shared edge-aware blocked classification (GH-578): resolved against
     // the full corpus so terminal blocker targets count as satisfied at every depth.
     const blockedIds = collectDependencyBlockedIds(corpus.fullCorpus, runtime.statusRegistry);
-    const focusGroups = await resolveContextFocusGroups(corpus.listedItemMetadata, corpus.allItems, corpus.fullCorpus, blockedIds, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit, nowIso(), author, options.after, buildContextCursorFingerprint(options), shouldPageContextFocus(options, corpus.fullCorpus.length), pmRoot, runtime.tokenBudget, claimFocus);
+    const focusGroups = await resolveContextFocusGroups(corpus.listedItemMetadata, corpus.allItems, corpus.fullCorpus, blockedIds, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit, nowIso(), author, options.after, buildContextCursorFingerprint(options), shouldPageContextFocus(options, corpus.fullCorpus.length), pmRoot, runtime.tokenBudget, claimFocus, resolveItemTypeRegistry(runtime.settings, getActiveExtensionRegistrations()));
     const agendaContext = await buildContextAgenda(global, runtime, corpus.subtreeIds, new Set([
         ...focusGroups.highLevel,
         ...focusGroups.lowLevel,
@@ -1618,7 +1628,7 @@ export async function runContext(options, global) {
         now: agendaContext.agenda.now,
         global,
     });
-    const summaryExtras = buildContextSummaryExtras(contextNeedsAllItems(runtime.sectionsIncluded), corpus.allItems, runtime.statusRegistry);
+    const summaryExtras = buildContextSummaryExtras(corpus.allItems, runtime.statusRegistry, blockedIds);
     const result = {
         output_default: "toon",
         now: agendaContext.agenda.now,
@@ -1649,10 +1659,12 @@ export async function runContext(options, global) {
                 {}),
         },
         summary: {
-            active_items: focusGroups.activeItems.length,
-            in_progress: inProgressCount,
-            open: openCount,
-            blocked: focusGroups.blockedItems.length,
+            returned_focus: {
+                active_items: focusGroups.activeItems.length,
+                in_progress: inProgressCount,
+                open: openCount,
+                blocked: focusGroups.blockedItems.length,
+            },
             blocked_fallback_used: focusGroups.blockedFallbackUsed,
             high_level: focusGroups.highLevel.length,
             low_level: focusGroups.lowLevel.length,
@@ -1688,4 +1700,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=56205e5f-fc26-59ab-abdf-45bdcaf1c263
+//# debugId=4f8e82a2-f4ea-5ecb-8ef5-3ca795cdeda5

package/dist/sdk/query/duplicate-candidates.d.ts

@@ -0,0 +1,7 @@
+import type { PreparedSimilarityText } from "../similarity-scoring.js";
+/** Declared safety bound applies to retained pairs, never silently to recall. */
+export declare const MAX_DUPLICATE_CANDIDATE_PAIRS = 1000000;
+/** Generate every potentially qualifying pair once, with an explicit exhaustive oracle. */
+export declare function collectDuplicateCandidatePairs(items: readonly {
+    prepared: PreparedSimilarityText;
+}[], maxPairs?: number, threshold?: number, exhaustive?: boolean): Set<string>;

package/dist/sdk/query/duplicate-candidates.js

@@ -0,0 +1,71 @@
+/**
+ * @module sdk/query/duplicate-candidates
+ *
+ * Lossless prefix filtering for Jaccard joins. A globally ordered prefix of
+ * length n-ceil(threshold*n)+1 must intersect the corresponding prefix of
+ * every qualifying set. Exact titles and issue codes remain independent
+ * signals, including titles with no word tokens.
+ */
+
+!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]="d425cf45-5b62-5613-a5ce-78da6b0e201b")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+/** Declared safety bound applies to retained pairs, never silently to recall. */
+export const MAX_DUPLICATE_CANDIDATE_PAIRS = 1_000_000;
+/** Generate every potentially qualifying pair once, with an explicit exhaustive oracle. */
+export function collectDuplicateCandidatePairs(items, maxPairs = MAX_DUPLICATE_CANDIDATE_PAIRS, threshold = 0.8, exhaustive = false) {
+    const candidates = new Set();
+    /** Deduplicate a candidate pair and refuse before publishing an over-budget result. */
+    const add = (left, right) => {
+        candidates.add(`${left}:${right}`);
+        if (candidates.size > maxPairs) {
+            throw new PmCliError(`Duplicate sweep exceeded ${maxPairs} candidate pairs; narrow it with statuses or since.`, EXIT_CODE.CONFLICT, { code: "duplicate_sweep_cost_limit", required: "Narrow the duplicate query or increase its similarity threshold. No partial result was returned." });
+        }
+    };
+    if (exhaustive || threshold === 0) {
+        for (let right = 0; right < items.length; right += 1) {
+            for (let left = 0; left < right; left += 1)
+                add(left, right);
+        }
+        return candidates;
+    }
+    const frequencies = new Map();
+    for (const { prepared } of items) {
+        for (const token of prepared.tokens)
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    }
+    const exact = new Map();
+    const codes = new Map();
+    const prefixes = new Map();
+    for (const [right, { prepared }] of items.entries()) {
+        const tokens = [...prepared.tokens].sort((left, other) => frequencies.get(left) - frequencies.get(other) || left.localeCompare(other));
+        // An epsilon expands rather than shrinks the prefix at floating boundaries.
+        const prefixLength = tokens.length - Math.ceil(threshold * tokens.length - 1e-12) + 1;
+        const signals = [
+            { index: exact, keys: [prepared.normalized], lengthFilter: false },
+            { index: codes, keys: threshold <= 0.99 ? prepared.issueCodes : [], lengthFilter: false },
+            { index: prefixes, keys: tokens.length === 0 ? [""] : tokens.slice(0, prefixLength), lengthFilter: true },
+        ];
+        for (const signal of signals) {
+            appendPostingCandidates(items, right, signal, threshold, add);
+        }
+    }
+    return candidates;
+}
+/** Join one exact/code/prefix posting list, applying the Jaccard length bound only to tokens. */
+function appendPostingCandidates(items, right, signal, threshold, add) {
+    const rightLength = items[right].prepared.tokens.length;
+    for (const key of signal.keys) {
+        const posting = signal.index.get(key) ?? [];
+        for (const left of posting) {
+            const leftLength = items[left].prepared.tokens.length;
+            if (signal.lengthFilter && Math.min(leftLength, rightLength) / Math.max(leftLength, rightLength) + 1e-12 < threshold)
+                continue;
+            add(left, right);
+        }
+        posting.push(right);
+        signal.index.set(key, posting);
+    }
+}
+//# sourceMappingURL=duplicate-candidates.js.map
+//# debugId=d425cf45-5b62-5613-a5ce-78da6b0e201b

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

@@ -52,8 +52,8 @@ export interface GetResult {
     schedule?: Partial<ItemScheduleContext>;
     /** True when the item was reconstructed from immutable history. */
     reconstructed?: true;
-    /** One-based history version represented by a reconstructed read. */
-    as_of_version?: number;
+    /** Durable version, or null when legacy compaction lost the numeric mapping. */
+    as_of_version?: number | null;
     /** Timestamp of the last history entry included in a reconstructed read. */
     as_of_timestamp?: string;
     /** Value that configures or reports tree for this contract. */

package/dist/sdk/query/get.js

@@ -4,7 +4,7 @@
  * Implements the SDK-owned item query shared by every surface.
  */
 
-!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]="ff82974e-a48d-5d18-893f-fb618e378795")}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]="88732a1d-ae5a-5dfb-93d6-9659cb6f05c3")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
@@ -310,6 +310,7 @@ function shouldIncludeGetField(params) {
     }
     return depth !== "brief";
 }
+/** Derive claim evidence from the selected physical history prefix, excluding future claims. */
 async function resolveGetClaimState(context, includeClaimState) {
     if (!includeClaimState) {
         return undefined;
@@ -317,7 +318,7 @@ async function resolveGetClaimState(context, includeClaimState) {
     const historyPath = getHistoryPath(context.pmRoot, context.locatedId);
     const history = await readHistoryEntries(historyPath, context.locatedId);
     return resolveClaimStateContext(context.metadata.assignee, context.historical
-        ? history.slice(0, context.historical.as_of_version)
+        ? history.slice(0, context.historical.target.historyIndex + 1)
         : history);
 }
 function attachGetLinked(result, context, fields, includeLinked) {
@@ -336,14 +337,14 @@ function attachGetLinked(result, context, fields, includeLinked) {
         docs: includeLinkedDocs ? (context.metadata.docs ?? []) : [],
     };
 }
-async function buildGetChildrenRollup(context, includeChildren, includeEmpty, includeSample) {
+/** Enumerate hierarchy metadata only when the caller explicitly requested a child rollup. */
+async function buildGetChildrenRollup(context, includeChildren) {
     if (!includeChildren) {
         return undefined;
     }
     const statusRegistry = resolveRuntimeStatusRegistry(context.settings.schema);
     const corpus = await listAllItemMetadataLight(context.pmRoot, context.settings.item_format, context.typeToFolder, undefined, context.settings.schema);
-    const rollup = buildItemChildrenRollup(context.locatedId, corpus, statusRegistry, includeSample ? undefined : 0);
-    return rollup.count > 0 || includeEmpty ? rollup : undefined;
+    return buildItemChildrenRollup(context.locatedId, corpus, statusRegistry);
 }
 function attachGetSchedule(result, context, fields, includeSchedule) {
     if (!includeSchedule) {
@@ -394,7 +395,7 @@ export async function runGet(id, global, options = {}) {
     const includeChildren = context.historical === undefined &&
         (projection.fieldProjection
             ? fieldsIncludeRoot(projection.fields, "children")
-            : projection.depth !== "brief" &&
+            : projection.depth === "deep" &&
                 shouldAutoIncludeGetChildren(context.metadata.type));
     const includeSchedule = projection.fieldProjection
         ? fieldsIncludeRoot(projection.fields, "schedule")
@@ -413,7 +414,7 @@ export async function runGet(id, global, options = {}) {
         result.claim_state = claimState;
     }
     attachGetSchedule(result, context, projection.fields, includeSchedule);
-    const children = await buildGetChildrenRollup(context, includeChildren, projection.fieldProjection, projection.fieldProjection || projection.depth === "deep");
+    const children = await buildGetChildrenRollup(context, includeChildren);
     if (children !== undefined) {
         result.children = children;
     }
@@ -447,4 +448,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=ff82974e-a48d-5d18-893f-fb618e378795
+//# debugId=88732a1d-ae5a-5dfb-93d6-9659cb6f05c3

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

@@ -32,6 +32,8 @@ export interface HistoryCommandOptions {
 export interface HistoryDiffEntry {
     /** Value that configures or reports index for this contract. */
     index: number;
+    /** Durable version address after compaction; null for unmapped legacy checkpoints. */
+    version?: number | null;
     /** Value that configures or reports ts for this contract. */
     ts: string;
     /** Value that configures or reports op for this contract. */
@@ -74,6 +76,15 @@ export interface HistoryResult {
     verification?: HistoryVerificationResult;
     /** Constant-size provenance completeness metrics. */
     provenance_summary?: HistoryProvenanceSummary;
+    /** Present after compaction; row indices remain physical stream positions. */
+    version_addressing?: {
+        /** Add to a physical one-based index; null when the original mapping is lost. */
+        offset: number | null;
+        /** Earliest reconstructable original version, or null for legacy checkpoints. */
+        first_version: number | null;
+        /** Latest addressable version, including maintenance audit events. */
+        last_version: number | null;
+    };
 }
 /** Implements run history for the public runtime surface of this module. */
 export declare function runHistory(id: string, options: HistoryCommandOptions, global: GlobalOptions): Promise<HistoryResult>;

package/dist/sdk/query/history.js

@@ -4,8 +4,9 @@
  * Implements the pm history 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]="314adea1-6837-5eeb-abc3-57337a495221")}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]="13e944b0-f049-55e5-8ff8-6335ce888b65")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { historyVersionOffset } from "../../core/history/version-address.js";
 import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } from "../runtime-primitives.js";
 import { readHistoryEntries, verifyHistoryEntries, } from "../history-read.js";
 export { readHistoryEntries } from "../history-read.js";
@@ -18,8 +19,9 @@ function limitEntries(values, limit) {
         return values;
     return values.slice(Math.max(0, values.length - limit));
 }
-function buildDiffEntries(entries, startIndex) {
-    return entries.map((entry, index) => {
+/** Summarize patch fields with physical indices and separately mapped durable versions. */
+function buildDiffEntries(entries, addressing) {
+    return entries.map(({ entry, version }) => {
         const changedFields = new Set();
         const patch = normalizeReplayPatchOps(entry.patch);
         for (const op of patch) {
@@ -29,7 +31,8 @@ function buildDiffEntries(entries, startIndex) {
             }
         }
         return {
-            index: startIndex + index + 1,
+            index: version,
+            ...(addressing ? { version: addressing.offset === null ? null : addressing.offset + version } : {}),
             ts: entry.ts,
             op: entry.op,
             author: entry.author,
@@ -38,6 +41,17 @@ function buildDiffEntries(entries, startIndex) {
         };
     });
 }
+/** Describe the checkpoint mapping without changing physical diagnostic indices. */
+function buildVersionAddressing(history) {
+    if (history[0]?.op !== "history_compact_baseline")
+        return undefined;
+    const offset = historyVersionOffset(history, true);
+    return {
+        offset,
+        first_version: offset === null ? null : offset + 1,
+        last_version: offset === null ? null : offset + history.length,
+    };
+}
 async function resolveHistoryReadTarget(id, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await assertInitializedTracker(pmRoot);
@@ -71,6 +85,7 @@ export async function runHistory(id, options, global) {
     const limit = parseLimit(options.limit);
     const { historyPath, located, resolvedId, settings } = await resolveHistoryReadTarget(id, global);
     const fullHistory = await readHistoryEntries(historyPath, resolvedId);
+    const addressing = buildVersionAddressing(fullHistory);
     const vocabulary = settings.agent_identity.identity_vocabulary;
     const provenanceDimensions = resolveHistoryProvenanceDimensions(settings.agent_identity.harness_signals);
     const matchesProvenance = compileHistoryProvenanceMatcher({
@@ -78,19 +93,18 @@ export async function runHistory(id, options, global) {
         agentInstance: options.agentInstance,
         provenance: options.provenanceFilter,
     }, vocabulary, provenanceDimensions);
-    const filteredHistory = fullHistory
-        .map((entry, index) => ({ entry, version: index + 1 }))
+    const filteredHistory = indexHistoryEntries(fullHistory)
         .filter(({ entry }) => matchesProvenance(entry));
     const selectedHistory = limitEntries(filteredHistory, limit);
     const history = selectedHistory.map(({ entry }) => entry);
     const compact = options.compact === true;
     const compactHistory = compact
-        ? buildDiffEntries(history, Math.max(0, fullHistory.length - history.length))
+        ? buildDiffEntries(selectedHistory, addressing)
         : undefined;
     const provenanceHistory = options.provenance === true
-        ? selectedHistory.map(({ entry, version }) => projectHistoryProvenance(entry, vocabulary, {
+        ? selectedHistory.map(({ entry, durableVersion }) => projectHistoryProvenance(entry, vocabulary, {
             itemId: resolvedId,
-            version,
+            version: durableVersion,
         }))
         : undefined;
     const projectionMode = options.provenance === true ? "provenance" : compact ? "compact" : "full";
@@ -115,6 +129,7 @@ export async function runHistory(id, options, global) {
         omission_receipt: resolveModePairedOutputOmissionReceipt("history", projectionMode),
         count: history.length,
         limit: limit ?? null,
+        version_addressing: addressing,
         ...(options.provenanceSummary === true
             ? {
                 provenance_summary: summarizeHistoryProvenance(filteredHistory.map(({ entry }) => entry), vocabulary, provenanceDimensions),
@@ -159,5 +174,14 @@ export async function runHistory(id, options, global) {
     }
     return result;
 }
+/** Attach physical and durable coordinates before filtering or limiting the stream. */
+function indexHistoryEntries(history) {
+    const offset = historyVersionOffset(history, true);
+    return history.map((entry, index) => ({
+        entry,
+        version: index + 1,
+        durableVersion: offset === null ? undefined : offset + index + 1,
+    }));
+}
 //# sourceMappingURL=history.js.map
-//# debugId=314adea1-6837-5eeb-abc3-57337a495221
+//# debugId=13e944b0-f049-55e5-8ff8-6335ce888b65

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

@@ -10,6 +10,7 @@
  */
 import { type ActionableEntry } from "../actionability.js";
 import { type GlobalOptions } from "../runtime-primitives.js";
+import type { ItemTypeRegistry } from "../../core/item/type-registry.js";
 import type { ItemStatus } from "../../types/index.js";
 import { type ContextFocusItem, type ContextRankingSummary, type ContextPackingSummary } from "./context.js";
 /** Supported values accepted by the next output contract. */
@@ -48,6 +49,10 @@ export interface NextOptions {
     tokenBudget?: string | number;
     /** Include human-gated Decision items in the claimable ready queue. */
     includeDecisions?: boolean;
+    /** Opt into gate-shaped leaf work; blockers and ownership restrictions still apply. */
+    includeGates?: boolean;
+    /** Opt into containers with unfinished descendants; blockers and ownership restrictions still apply. */
+    includeContainers?: boolean;
     /** Internal caller override used to align claim-next ranking with --author. */
     callerAuthor?: string;
     [key: string]: unknown;
@@ -95,6 +100,7 @@ interface NextSummary {
     candidates: number;
     containers: number;
     decision_needed: number;
+    gate_needed?: number;
     held_by_others: number;
 }
 /** Documents the `pm next` result payload exchanged by command, SDK, and package integrations. */
@@ -109,6 +115,10 @@ export interface NextResult {
     ready: NextActionableItem[];
     /** Human-gated decisions kept visible without dispatching them to agents. */
     decision_needed: NextActionableItem[];
+    /** Outcome gates held out of autonomous dispatch. */
+    gate_needed?: NextActionableItem[];
+    /** Containers with unfinished descendants, retained as readable worklists. */
+    containers?: NextActionableItem[];
     /** Value that configures or reports blocked for this contract. */
     blocked: NextActionableItem[];
     /** Value that configures or reports held by others for this contract. */
@@ -132,6 +142,8 @@ export interface NextResult {
         blocked_limit: number;
         ready_only: boolean;
         include_decisions: boolean;
+        include_gates?: boolean;
+        include_containers?: boolean;
         token_budget: number;
     };
     /** Value that configures or reports suggestions for this contract. */
@@ -146,6 +158,8 @@ export interface NextResult {
     truncation?: {
         decision_needed_total?: number;
         held_by_others_total?: number;
+        gate_needed_total?: number;
+        containers_total?: number;
     };
 }
 /** Resolves the effective `pm next` output format from the command `--format` flag and the global `--json` switch, rejecting the contradictory `--json --format markdown|toon` combination. Defaults to `toon`. */
@@ -163,7 +177,7 @@ export declare const _testOnlyNextCommand: {
     resolveNextCallerAuthor: (options: NextOptions, settingsAuthor: string) => string;
 };
 /** Separates human-gated decisions from autonomous agent work unless the caller explicitly opts into decision claims. */
-export declare function partitionDecisionEntries(ready: ActionableEntry[], includeDecisions: boolean): {
+export declare function partitionDecisionEntries(ready: ActionableEntry[], includeDecisions: boolean, typeRegistry?: ItemTypeRegistry): {
     agent: ActionableEntry[];
     decisions: ActionableEntry[];
 };