@unbrained/pm-cli 2026.8.21 → 2026.8.23

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

@@ -5,6 +5,7 @@ import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js"
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import type { ItemMetadata, ItemStatus } from "../../types/index.js";
 import type { SharedItemFilterOptions } from "./item-filter-options.js";
+import { type HierarchyRelationIndexes } from "../graph/hierarchy-integrity.js";
 import { type ListCommandName, type ListProjectionMode } from "./projection-contracts.js";
 export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, type ListCommandName, type ListProjectionMode, } from "./projection-contracts.js";
 /** Documents the list options payload exchanged by command, SDK, and package integrations. */
@@ -236,10 +237,10 @@ declare function normalizeProjectionField(field: string): string;
 declare function parseSortField(raw: string | undefined): ListSortField | undefined;
 declare function parseSortOrder(raw: string | undefined): ListSortOrder | undefined;
 declare function parseAssigneeFilter(raw: string | undefined): "assigned" | "unassigned" | undefined;
-declare function applyFilters(items: ListedItem[], status: ItemStatus[] | undefined, options: ListOptions, typeRegistry: ItemTypeRegistry, statusRegistry: RuntimeStatusRegistry, runtimeFieldFilters: Record<string, unknown>): ListedItem[];
+declare function applyFilters(items: ListedItem[], status: ItemStatus[] | undefined, options: ListOptions, typeRegistry: ItemTypeRegistry, statusRegistry: RuntimeStatusRegistry, runtimeFieldFilters: Record<string, unknown>, parentsByChild?: HierarchyRelationIndexes["parents_by_child"]): ListedItem[];
 declare function trimNonEmpty(value: string | undefined): string | undefined;
-declare function withTreeMetadata(item: ListedItem, depth: number, childCount: number): ListTreeItem;
-declare function orderItemsAsTree(sortedItems: ListedItem[], parentRoot: string | undefined, maxDepth: number | undefined): ListedItem[];
+declare function withTreeMetadata(item: ListedItem, depth: number, childCount: number, parentId?: string): ListTreeItem;
+declare function orderItemsAsTree(sortedItems: ListedItem[], parentRoot: string | undefined, maxDepth: number | undefined, hierarchyIndexes?: HierarchyRelationIndexes, completeItems?: readonly ListedItem[]): ListedItem[];
 declare function compareNullableString(left: string | null, right: string | null): number;
 declare function compareNullableTimestamp(left: string | null, right: string | null): number;
 declare function compareBySortField(left: ListedItem, right: ListedItem, field: ListSortField): number;

package/dist/sdk/query/list.js

@@ -4,7 +4,7 @@
  * Implements the pm list 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]="361f891a-5f10-529c-8161-dc5193c7e12a")}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]="93e8c187-e198-50fc-bf2c-7dae2ea42219")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
@@ -27,6 +27,8 @@ import { queryItemMetadataIndex } from "../../core/store/item-metadata-query-ind
 import { resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { LIST_FILTER_FLAG_CONTRACTS } from "../cli-contracts/flag-contracts.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { collectHierarchyRelations, indexHierarchyRelations, } from "../graph/hierarchy-integrity.js";
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, selectCursorSemanticOptions, } from "../pagination.js";
 import { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, listListProjectionFields, } from "./projection-contracts.js";
 export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, } from "./projection-contracts.js";
@@ -640,7 +642,9 @@ function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
         parentFilter: options.parent?.trim(),
         treeEnabled: options.tree === true,
         sprintFilter: parseStringFilterSet(options.sprint, { label: "--sprint" }),
-        releaseFilter: parseStringFilterSet(options.release, { label: "--release" }),
+        releaseFilter: parseStringFilterSet(options.release, {
+            label: "--release",
+        }),
         missingMetadataFilters,
         missingMetadataActive: hasMissingMetadataFilter(missingMetadataFilters),
         lifecycleClassifier: lifecycleClassifierFromStatusRegistry(statusRegistry),
@@ -648,12 +652,6 @@ function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
         contentFiltersActive: hasContentFieldFilter(contentFieldFilters),
     };
 }
-function matchesListScalarFilters(item, filters, statusRegistry) {
-    return (matchesListIdentityFilters(item, filters, statusRegistry) &&
-        matchesListDateFilters(item, filters) &&
-        matchesListAssigneeFilterSet(item, filters) &&
-        matchesListScopeFilters(item, filters));
-}
 function matchesListIdentityFilters(item, filters, statusRegistry) {
     if (filters.idsFilter && !filters.idsFilter.has(item.id))
         return false;
@@ -681,10 +679,17 @@ function matchesListAssigneeFilterSet(item, filters) {
     return (filters.assigneeFilter === undefined ||
         (item.assignee !== undefined && filters.assigneeFilter.has(item.assignee)));
 }
-function matchesListScopeFilters(item, filters) {
+function matchesListScopeFilters(item, filters, parentsByChild) {
+    const scalarParent = item.parent?.trim().toLowerCase();
+    const logicalParentIds = [
+        ...new Set([
+            ...(parentsByChild?.get(item.id.trim().toLowerCase()) ?? []),
+            ...(scalarParent ? [scalarParent] : []),
+        ]),
+    ];
     if (filters.parentFilter !== undefined &&
         !filters.treeEnabled &&
-        item.parent !== filters.parentFilter)
+        !logicalParentIds.includes(filters.parentFilter.trim().toLowerCase()))
         return false;
     if (filters.sprintFilter !== undefined &&
         (item.sprint === undefined || !filters.sprintFilter.has(item.sprint)))
@@ -692,8 +697,11 @@ function matchesListScopeFilters(item, filters) {
     return (filters.releaseFilter === undefined ||
         (item.release !== undefined && filters.releaseFilter.has(item.release)));
 }
-function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters) {
-    if (!matchesListScalarFilters(item, filters, statusRegistry)) {
+function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters, parentsByChild) {
+    if (!matchesListIdentityFilters(item, filters, statusRegistry) ||
+        !matchesListDateFilters(item, filters) ||
+        !matchesListAssigneeFilterSet(item, filters) ||
+        !matchesListScopeFilters(item, filters, parentsByChild)) {
         return false;
     }
     if (filters.missingMetadataActive &&
@@ -709,9 +717,9 @@ function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters
     }
     return true;
 }
-function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters) {
+function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters, parentsByChild) {
     const filters = resolveListFilterSet(status, options, typeRegistry, statusRegistry);
-    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters));
+    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters, parentsByChild));
 }
 function trimNonEmpty(value) {
     if (typeof value !== "string") {
@@ -720,10 +728,12 @@ function trimNonEmpty(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-function withTreeMetadata(item, depth, childCount) {
+function withTreeMetadata(item, depth, childCount, parentId) {
     const itemRecord = toItemRecord(item);
     const title = typeof itemRecord.title === "string" ? itemRecord.title : "";
-    const parent = trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ?? null;
+    const parent = parentId ??
+        trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ??
+        null;
     return {
         ...item,
         tree_depth: depth,
@@ -732,47 +742,73 @@ function withTreeMetadata(item, depth, childCount) {
         tree_title: `${"  ".repeat(depth)}${title}`,
     };
 }
-function orderItemsAsTree(sortedItems, parentRoot, maxDepth) {
+function buildListTreeIndexes(sortedItems, hierarchyIndexes) {
     const byId = new Map();
     const childrenByParent = new Map();
     for (const item of sortedItems) {
-        byId.set(item.id, item);
-        const parentId = trimNonEmpty(item.parent);
-        if (!parentId) {
-            continue;
-        }
-        const bucket = childrenByParent.get(parentId);
-        if (bucket) {
-            bucket.push(item);
-        }
-        else {
-            childrenByParent.set(parentId, [item]);
+        const itemId = item.id.trim().toLowerCase();
+        byId.set(itemId, item);
+        const parentIds = hierarchyIndexes
+            ? (hierarchyIndexes.parents_by_child.get(itemId) ?? [])
+            : [trimNonEmpty(item.parent)?.toLowerCase()].filter((value) => value !== undefined);
+        for (const parentId of parentIds) {
+            const children = childrenByParent.get(parentId) ?? [];
+            children.push(item);
+            childrenByParent.set(parentId, children);
         }
     }
-    const roots = parentRoot
-        ? [...(childrenByParent.get(parentRoot) ?? [])]
+    return { byId, childrenByParent };
+}
+function resolveListTreeRoots(sortedItems, parentRoot, byId, childrenByParent, hierarchyIndexes) {
+    return parentRoot
+        ? [...(childrenByParent.get(parentRoot.toLowerCase()) ?? [])]
         : sortedItems.filter((item) => {
-            const parentId = trimNonEmpty(item.parent);
-            return !parentId || !byId.has(parentId);
+            const parentIds = hierarchyIndexes
+                ? (hierarchyIndexes.parents_by_child.get(item.id.trim().toLowerCase()) ?? [])
+                : [trimNonEmpty(item.parent)?.toLowerCase()].filter((value) => value !== undefined);
+            return parentIds.every((parentId) => !byId.has(parentId));
         });
+}
+function orderItemsAsTree(sortedItems, parentRoot, maxDepth, hierarchyIndexes, completeItems = sortedItems) {
+    const { byId, childrenByParent } = buildListTreeIndexes(sortedItems, hierarchyIndexes);
+    const roots = resolveListTreeRoots(sortedItems, parentRoot, byId, childrenByParent, hierarchyIndexes);
     const ordered = [];
     const visited = new Set();
-    const pushNode = (node, depth) => {
-        if (visited.has(node.id)) {
-            return;
-        }
-        visited.add(node.id);
-        const children = childrenByParent.get(node.id) ?? [];
-        ordered.push(withTreeMetadata(node, depth, children.length));
-        if (maxDepth !== undefined && depth >= maxDepth) {
-            return;
+    const canonicalIdByLowercase = new Map(completeItems.map((item) => [item.id.trim().toLowerCase(), item.id.trim()]));
+    const pending = [...roots].reverse().map((node) => ({
+        node,
+        depth: 0,
+        parentId: parentRoot === undefined
+            ? undefined
+            : (canonicalIdByLowercase.get(parentRoot.trim().toLowerCase()) ??
+                parentRoot.trim()),
+    }));
+    while (pending.length > 0) {
+        const { node, depth, parentId } = pending.pop();
+        const nodeId = node.id.trim().toLowerCase();
+        if (visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const children = childrenByParent.get(nodeId) ?? [];
+        ordered.push(withTreeMetadata(node, depth, children.length, parentId));
+        if (maxDepth !== undefined && depth >= maxDepth)
+            continue;
+        for (const child of [...children].reverse()) {
+            pending.push({
+                node: child,
+                depth: depth + 1,
+                parentId: canonicalIdByLowercase.get(nodeId),
+            });
         }
-        for (const child of children) {
-            pushNode(child, depth + 1);
+    }
+    if (parentRoot === undefined && maxDepth === undefined) {
+        for (const item of sortedItems) {
+            const itemId = item.id.trim().toLowerCase();
+            if (visited.has(itemId))
+                continue;
+            visited.add(itemId);
+            ordered.push(withTreeMetadata(item, 0, childrenByParent.get(itemId)?.length ?? 0));
         }
-    };
-    for (const root of roots) {
-        pushNode(root, 0);
     }
     return ordered;
 }
@@ -1136,8 +1172,12 @@ export async function runList(status, options, global) {
     let page = indexedPage;
     if (!page) {
         const items = await loadListItems(options, runtime, listWarnings);
+        const needsHierarchyIndexes = ordering.treeEnabled || trimNonEmpty(options.parent) !== undefined;
+        const hierarchyIndexes = needsHierarchyIndexes
+            ? indexHierarchyRelations(collectHierarchyRelations(items, resolveWorkspaceRelationshipKindRegistry()))
+            : undefined;
         appendUnknownTagWarning(items, options.tag, listWarnings);
-        const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters);
+        const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters, hierarchyIndexes?.parents_by_child);
         // Edge-aware blocked selection (GH-578): classify against the complete
         // loaded corpus so terminal blocker targets count as satisfied, then narrow
         // the already-filtered rows to the shared blocked set.
@@ -1149,7 +1189,7 @@ export async function runList(status, options, global) {
             : filtered;
         const sorted = sortItems(scoped, ordering.sortField, ordering.sortOrder, runtime.statusRegistry);
         const ordered = ordering.treeEnabled
-            ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth)
+            ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth, hierarchyIndexes, items)
             : sorted;
         page = pageAndProjectListItems(ordered, options, runtime.projection, ordering.treeEnabled, buildListCursorFingerprint(statusSelection.filtersStatus, options, ordering));
     }
@@ -1241,4 +1281,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=361f891a-5f10-529c-8161-dc5193c7e12a
+//# debugId=93e8c187-e198-50fc-bf2c-7dae2ea42219

package/dist/sdk/read-output-budget.d.ts

@@ -5,6 +5,27 @@
  * read-output contract without expanding its public declaration module.
  */
 import type { PmReadOutputReceipt } from "./read-output-contracts.js";
+/** Input to the deterministic finite-retry recommendation contract. */
+export interface PmReadOutputRecoveryBudgetInput {
+    /** Ceiling that already bound and truncated the response. */
+    effective_budget_tokens: number;
+    /** Measured cost of the useful result before row compaction. */
+    measured_result_tokens: number;
+}
+/** Executable next-budget recommendation shared by CLI, SDK, and MCP. */
+export interface PmReadOutputRecoveryBudget {
+    /** Rounded finite retry ceiling, or the only truthful safe fallback. */
+    output_budget: number | "unbounded";
+    /** Ratio to the binding request, absent when finite arithmetic is unsafe. */
+    recovery_budget_multiplier: number | null;
+    /** Stable algorithm revision for consumers and fixtures. */
+    rule_version: "v1";
+}
+/**
+ * Recommend a retry that is strictly larger than both the binding request and
+ * the pre-compaction result, with a 25% envelope margin rounded to 100 tokens.
+ */
+export declare function resolveReadOutputRecoveryBudget(input: PmReadOutputRecoveryBudgetInput): PmReadOutputRecoveryBudget;
 /** Estimate the conservative token cost of a JSON-shaped result. */
 export declare function estimateReadOutputTokens(result: unknown): number;
 /** Update a receipt to the fixed-point estimate of the result containing it. */

package/dist/sdk/read-output-budget.js

@@ -1,8 +1,45 @@
 
-!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]="737ac274-c165-5d1a-8b8e-cb5d57a81c46")}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]="02a0bd0c-6ab0-5193-807b-00394a4712b7")}catch(e){}}();
 import { countReadOutputRows, readOutputBudgetCollections, } from "./read-output-rows.js";
 const MAX_ESTIMATE_ITERATIONS = 8;
 const MAX_COMPACTION_ITERATIONS = 64;
+const RECOVERY_MARGIN_NUMERATOR = 5;
+const RECOVERY_MARGIN_DENOMINATOR = 4;
+const RECOVERY_ROUNDING_TOKENS = 100;
+/**
+ * Recommend a retry that is strictly larger than both the binding request and
+ * the pre-compaction result, with a 25% envelope margin rounded to 100 tokens.
+ */
+export function resolveReadOutputRecoveryBudget(input) {
+    const binding = Math.trunc(input.effective_budget_tokens);
+    const measured = Math.trunc(input.measured_result_tokens);
+    if (!Number.isSafeInteger(binding) ||
+        binding <= 0 ||
+        !Number.isSafeInteger(measured) ||
+        measured <= 0) {
+        return {
+            output_budget: "unbounded",
+            recovery_budget_multiplier: null,
+            rule_version: "v1",
+        };
+    }
+    const baseline = Math.max(binding + 1, measured);
+    const withMargin = Math.ceil((baseline * RECOVERY_MARGIN_NUMERATOR) / RECOVERY_MARGIN_DENOMINATOR);
+    const rounded = Math.ceil(withMargin / RECOVERY_ROUNDING_TOKENS) *
+        RECOVERY_ROUNDING_TOKENS;
+    if (!Number.isSafeInteger(rounded)) {
+        return {
+            output_budget: "unbounded",
+            recovery_budget_multiplier: null,
+            rule_version: "v1",
+        };
+    }
+    return {
+        output_budget: rounded,
+        recovery_budget_multiplier: rounded / binding,
+        rule_version: "v1",
+    };
+}
 /** Estimate the conservative token cost of a JSON-shaped result. */
 export function estimateReadOutputTokens(result) {
     return Math.ceil(Buffer.byteLength(JSON.stringify(result), "utf8") / 4);
@@ -96,4 +133,4 @@ export function compactReadOutputToBudget(result, receipt, budget, minimumRowsBy
     return compacted;
 }
 //# sourceMappingURL=read-output-budget.js.map
-//# debugId=737ac274-c165-5d1a-8b8e-cb5d57a81c46
+//# debugId=02a0bd0c-6ab0-5193-807b-00394a4712b7

package/dist/sdk/read-output-contracts.d.ts

@@ -1,3 +1,5 @@
+export { resolveReadOutputRecoveryBudget } from "./read-output-budget.js";
+export type { PmReadOutputRecoveryBudget, PmReadOutputRecoveryBudgetInput, } from "./read-output-budget.js";
 export { decodeReadOutputContinuationCursor, encodeReadOutputContinuationCursor, } from "./read-output/continuation.js";
 import { type PmReadOutputSessionReceipt, type PmReadOutputSessionState } from "./read-output-session.js";
 /** Stable output dimensions shared by every read surface. */
@@ -5,7 +7,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-catalog", "package-manage", "comments-audit", "assurance"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "duplicates", "package-catalog", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -81,6 +83,8 @@ export interface PmResolvedReadOutputDimensions {
     cost?: PmResolvedReadOutputDimension<number | "unbounded">;
     /** Requested static encoding or a retained legacy streaming behavior. */
     encoding?: PmResolvedReadOutputDimension<"json" | "toon" | "stream">;
+    /** Canonical CLI options observed on the invocation. */
+    canonical_options_used?: string[];
     /** Compatibility flags observed on the invocation. */
     legacy_aliases_used: string[];
     /** One-line migration instructions for observed compatibility flags. */
@@ -102,6 +106,8 @@ export interface PmReadOutputReceipt {
     budget_tokens?: number;
     /** Deterministic precedence used during resolution. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
+    /** Canonical CLI options observed on the invocation. */
+    canonical_options_used?: string[];
     /** Compatibility options observed on the invocation. */
     legacy_aliases_used: string[];
     /** One-line migration instructions for compatibility options. */
@@ -138,7 +144,7 @@ export interface PmReadOutputTruncationDisclosure {
     /** Whether at least one declared row collection can be resumed within the budget. */
     continuation_available: boolean;
     /** Maximum next-page useful-result budget relative to the current budget. */
-    recovery_budget_multiplier: 1;
+    recovery_budget_multiplier: number | null;
     /** Bounded continuation instructions for every compacted declared row path. */
     continuations: PmReadOutputContinuation[];
     /** Executable recovery instruction for retrieving the complete result. */
@@ -156,10 +162,10 @@ export interface PmReadOutputTruncationDisclosure {
     } | {
         cli: string;
         sdk: {
-            outputBudget: number;
+            outputBudget: number | "unbounded";
         };
         mcp: {
-            outputBudget: number;
+            outputBudget: number | "unbounded";
         };
     };
 }