@unbrained/pm-cli 2026.7.19 → 2026.7.20

package/dist/sdk/stats.d.ts

@@ -30,7 +30,7 @@ export interface StatsResult {
     };
     /** Schema type that determines the shape and validation rules for this value. */
     by_type: Record<ItemType, number>;
-    /** Lifecycle state reported for bythe record. */
+    /** Item counts grouped by lifecycle status. */
     by_status: Record<ItemStatus, number>;
     /** Present only with --metadata-coverage: per-field coverage overall and by type. */
     metadata_coverage?: MetadataCoverageReport;

package/dist/sdk/stats.js

@@ -4,7 +4,7 @@
  * Implements the pm stats 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]="3abba5c6-fe9b-55de-bafb-3f3c604df10c")}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]="afed0a81-eee3-5a32-9ebb-79f6f64301c5")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -148,4 +148,4 @@ export async function runStats(global, options = {}) {
     };
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=3abba5c6-fe9b-55de-bafb-3f3c604df10c
+//# debugId=afed0a81-eee3-5a32-9ebb-79f6f64301c5

package/dist/sdk/stats.js.map

@@ -1 +1 @@
-{"version":3,"file":"stats.js","sources":["sdk/stats.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/stats\n *\n * Implements the pm stats command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport {\n  getActiveExtensionRegistrations,\n  runActiveOnReadHooks,\n} from \"../core/extensions/index.js\";\nimport {\n  computeContentFieldUtilization,\n  type ContentFieldUtilizationReport,\n} from \"../core/governance/content-fields.js\";\nimport {\n  computeMetadataCoverage,\n  groupItemsByDimension,\n  lifecycleClassifierFromStatusRegistry,\n  type GroupedBreakdown,\n  type MetadataCoverageReport,\n} from \"../core/governance/metadata-coverage.js\";\nimport { pathExists, readFileIfExists } from \"../core/fs/fs-utils.js\";\nimport { enforceHistoryStreamPolicyForItems } from \"../core/history/history-stream-policy.js\";\nimport {\n  computeHistoryStorageStats,\n  type HistoryStorageStats,\n} from \"../core/history/history-storage-stats.js\";\nimport { resolveItemTypeRegistry } from \"../core/item/type-registry.js\";\nimport { resolveRuntimeStatusRegistry } from \"../core/schema/runtime-schema.js\";\nimport { EXIT_CODE } from \"../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../core/shared/command-types.js\";\nimport { PmCliError } from \"../core/shared/errors.js\";\nimport { nowIso } from \"../core/shared/time.js\";\nimport {\n  listAllItemMetadataLight,\n  listAllItemMetadataWithBody,\n} from \"../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../core/store/paths.js\";\nimport { readSettings } from \"../core/store/settings.js\";\nimport type { ItemStatus, ItemType } from \"../types/index.js\";\n\n/** Documents the stats command options payload exchanged by command, SDK, and package integrations. */\nexport interface StatsCommandOptions {\n  /** Include aggregate per-stream history storage metrics (sizes, depth, oldest/newest). */\n  storage?: boolean;\n  /** Include metadata coverage percentages (AC, estimates, resolution, tags, parent) overall and by type. */\n  metadataCoverage?: boolean;\n  /** Include a lifecycle-bucketed breakdown grouped by assignee. */\n  byAssignee?: boolean;\n  /** Include a lifecycle-bucketed breakdown grouped by tag (optionally filtered by --tag-prefix). */\n  byTag?: boolean;\n  /** Include a lifecycle-bucketed breakdown grouped by priority. */\n  byPriority?: boolean;\n  /** With --by-tag: only consider tags starting with this prefix (e.g. \"domain:\"). */\n  tagPrefix?: string;\n  /** Include a content-field utilization breakdown (notes/learnings/files/docs/tests/comments/deps/body usage rates). */\n  fieldUtilization?: boolean;\n}\n\n/** Documents the stats result payload exchanged by command, SDK, and package integrations. */\nexport interface StatsResult {\n  /** Value that configures or reports totals for this contract. */\n  totals: {\n    items: number;\n    history_streams: number;\n    history_entries: number;\n  };\n  /** Schema type that determines the shape and validation rules for this value. */\n  by_type: Record<ItemType, number>;\n  /** Lifecycle state reported for bythe record. */\n  by_status: Record<ItemStatus, number>;\n  /** Present only with --metadata-coverage: per-field coverage overall and by type. */\n  metadata_coverage?: MetadataCoverageReport;\n  /** Present only with --by-assignee/--by-tag/--by-priority: lifecycle-bucketed group breakdowns. */\n  breakdowns?: {\n    assignee?: GroupedBreakdown;\n    tag?: GroupedBreakdown;\n    priority?: GroupedBreakdown;\n  };\n  /** Present only with --storage: aggregate history-stream metrics for compaction/planning. */\n  storage?: HistoryStorageStats;\n  /** Present only with --field-utilization: content-field utilization rates across all items. */\n  field_utilization?: ContentFieldUtilizationReport;\n  /** ISO 8601 timestamp recording when generated occurred. */\n  generated_at: string;\n}\n\nfunction zeroByType(itemTypes: string[]): Record<ItemType, number> {\n  return itemTypes.reduce(\n    (acc, value) => {\n      acc[value] = 0;\n      return acc;\n    },\n    {} as Record<ItemType, number>,\n  );\n}\n\nfunction zeroByStatus(statuses: string[]): Record<ItemStatus, number> {\n  return statuses.reduce(\n    (acc, value) => {\n      acc[value] = 0;\n      return acc;\n    },\n    {} as Record<ItemStatus, number>,\n  );\n}\n\nfunction countNonEmptyLines(raw: string): number {\n  if (raw.trim().length === 0) {\n    return 0;\n  }\n  return raw.split(/\\r?\\n/u).filter((line) => line.trim().length > 0).length;\n}\n\nasync function readHistoryStreamContents(\n  pmRoot: string,\n): Promise<Array<{ id: string; raw: string }>> {\n  const historyDir = path.join(pmRoot, \"history\");\n  if (!(await pathExists(historyDir))) {\n    return [];\n  }\n\n  await runActiveOnReadHooks({\n    path: historyDir,\n    scope: \"project\",\n  });\n  const historyFiles = (await fs.readdir(historyDir))\n    .filter((entry) => entry.endsWith(\".jsonl\"))\n    .sort((a, b) => a.localeCompare(b));\n\n  const streams: Array<{ id: string; raw: string }> = [];\n  for (const file of historyFiles) {\n    const historyPath = path.join(historyDir, file);\n    const raw = await readFileIfExists(historyPath);\n    if (raw === null) {\n      continue;\n    }\n    await runActiveOnReadHooks({\n      path: historyPath,\n      scope: \"project\",\n    });\n    streams.push({ id: file.slice(0, -\".jsonl\".length), raw });\n  }\n\n  return streams;\n}\n\n/** Public contract for test only, shared by SDK and presentation-layer consumers. */\nexport const _testOnly = {\n  zeroByType,\n  zeroByStatus,\n  countNonEmptyLines,\n  readHistoryStreamContents,\n};\n\n/** Implements run stats for the public runtime surface of this module. */\nexport async function runStats(\n  global: GlobalOptions,\n  options: StatsCommandOptions = {},\n): Promise<StatsResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(\n    settings,\n    getActiveExtensionRegistrations(),\n  );\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  // Field utilization needs the heavy collections (notes/learnings/files/docs/\n  // tests/comments/deps) AND the body, which the light reader drops — so when it\n  // is requested we read the WithBody rows and use them for every section.\n  const items = options.fieldUtilization\n    ? await listAllItemMetadataWithBody(\n        pmRoot,\n        settings.item_format,\n        typeRegistry.type_to_folder,\n        undefined,\n        settings.schema,\n      )\n    : await listAllItemMetadataLight(\n        pmRoot,\n        settings.item_format,\n        typeRegistry.type_to_folder,\n        undefined,\n        settings.schema,\n      );\n  await enforceHistoryStreamPolicyForItems({\n    pmRoot,\n    settings,\n    itemIds: items.map((item) => item.id),\n    commandLabel: \"stats\",\n  });\n\n  const byType = zeroByType(typeRegistry.types);\n  const byStatus = zeroByStatus(\n    statusRegistry.definitions.map((definition) => definition.id),\n  );\n  // zeroByType/zeroByStatus pre-seed a bucket for every registry type/status, and\n  // the light item-metadata reader drops any item whose type/status falls outside\n  // the active registry (parse rejects them) — so every item's bucket is already\n  // present here and no on-the-fly initialization is reachable.\n  for (const item of items) {\n    byType[item.type] += 1;\n    byStatus[item.status] += 1;\n  }\n\n  const streams = await readHistoryStreamContents(pmRoot);\n  let historyEntries = 0;\n  for (const stream of streams) {\n    historyEntries += countNonEmptyLines(stream.raw);\n  }\n  const storage = options.storage\n    ? computeHistoryStorageStats(streams)\n    : undefined;\n\n  const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);\n  const metadataCoverage = options.metadataCoverage\n    ? computeMetadataCoverage(items, classifier)\n    : undefined;\n  const breakdowns: NonNullable<StatsResult[\"breakdowns\"]> = {};\n  if (options.byAssignee) {\n    breakdowns.assignee = groupItemsByDimension(items, \"assignee\", classifier);\n  }\n  if (options.byTag) {\n    breakdowns.tag = groupItemsByDimension(items, \"tag\", classifier, {\n      tagPrefix: options.tagPrefix,\n    });\n  }\n  if (options.byPriority) {\n    breakdowns.priority = groupItemsByDimension(items, \"priority\", classifier);\n  }\n  const hasBreakdowns = Object.keys(breakdowns).length > 0;\n  const fieldUtilization = options.fieldUtilization\n    ? computeContentFieldUtilization(items)\n    : undefined;\n\n  return {\n    totals: {\n      items: items.length,\n      history_streams: streams.length,\n      history_entries: historyEntries,\n    },\n    by_type: byType,\n    by_status: byStatus,\n    ...(metadataCoverage ? { metadata_coverage: metadataCoverage } : {}),\n    ...(hasBreakdowns ? { breakdowns } : {}),\n    ...(storage ? { storage } : {}),\n    ...(fieldUtilization ? { field_utilization: fieldUtilization } : {}),\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"3abba5c6-fe9b-55de-bafb-3f3c604df10c"}
+{"version":3,"file":"stats.js","sources":["sdk/stats.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/stats\n *\n * Implements the pm stats command surface and its agent-facing runtime behavior.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport {\n  getActiveExtensionRegistrations,\n  runActiveOnReadHooks,\n} from \"../core/extensions/index.js\";\nimport {\n  computeContentFieldUtilization,\n  type ContentFieldUtilizationReport,\n} from \"../core/governance/content-fields.js\";\nimport {\n  computeMetadataCoverage,\n  groupItemsByDimension,\n  lifecycleClassifierFromStatusRegistry,\n  type GroupedBreakdown,\n  type MetadataCoverageReport,\n} from \"../core/governance/metadata-coverage.js\";\nimport { pathExists, readFileIfExists } from \"../core/fs/fs-utils.js\";\nimport { enforceHistoryStreamPolicyForItems } from \"../core/history/history-stream-policy.js\";\nimport {\n  computeHistoryStorageStats,\n  type HistoryStorageStats,\n} from \"../core/history/history-storage-stats.js\";\nimport { resolveItemTypeRegistry } from \"../core/item/type-registry.js\";\nimport { resolveRuntimeStatusRegistry } from \"../core/schema/runtime-schema.js\";\nimport { EXIT_CODE } from \"../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../core/shared/command-types.js\";\nimport { PmCliError } from \"../core/shared/errors.js\";\nimport { nowIso } from \"../core/shared/time.js\";\nimport {\n  listAllItemMetadataLight,\n  listAllItemMetadataWithBody,\n} from \"../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../core/store/paths.js\";\nimport { readSettings } from \"../core/store/settings.js\";\nimport type { ItemStatus, ItemType } from \"../types/index.js\";\n\n/** Documents the stats command options payload exchanged by command, SDK, and package integrations. */\nexport interface StatsCommandOptions {\n  /** Include aggregate per-stream history storage metrics (sizes, depth, oldest/newest). */\n  storage?: boolean;\n  /** Include metadata coverage percentages (AC, estimates, resolution, tags, parent) overall and by type. */\n  metadataCoverage?: boolean;\n  /** Include a lifecycle-bucketed breakdown grouped by assignee. */\n  byAssignee?: boolean;\n  /** Include a lifecycle-bucketed breakdown grouped by tag (optionally filtered by --tag-prefix). */\n  byTag?: boolean;\n  /** Include a lifecycle-bucketed breakdown grouped by priority. */\n  byPriority?: boolean;\n  /** With --by-tag: only consider tags starting with this prefix (e.g. \"domain:\"). */\n  tagPrefix?: string;\n  /** Include a content-field utilization breakdown (notes/learnings/files/docs/tests/comments/deps/body usage rates). */\n  fieldUtilization?: boolean;\n}\n\n/** Documents the stats result payload exchanged by command, SDK, and package integrations. */\nexport interface StatsResult {\n  /** Value that configures or reports totals for this contract. */\n  totals: {\n    items: number;\n    history_streams: number;\n    history_entries: number;\n  };\n  /** Schema type that determines the shape and validation rules for this value. */\n  by_type: Record<ItemType, number>;\n  /** Item counts grouped by lifecycle status. */\n  by_status: Record<ItemStatus, number>;\n  /** Present only with --metadata-coverage: per-field coverage overall and by type. */\n  metadata_coverage?: MetadataCoverageReport;\n  /** Present only with --by-assignee/--by-tag/--by-priority: lifecycle-bucketed group breakdowns. */\n  breakdowns?: {\n    assignee?: GroupedBreakdown;\n    tag?: GroupedBreakdown;\n    priority?: GroupedBreakdown;\n  };\n  /** Present only with --storage: aggregate history-stream metrics for compaction/planning. */\n  storage?: HistoryStorageStats;\n  /** Present only with --field-utilization: content-field utilization rates across all items. */\n  field_utilization?: ContentFieldUtilizationReport;\n  /** ISO 8601 timestamp recording when generated occurred. */\n  generated_at: string;\n}\n\nfunction zeroByType(itemTypes: string[]): Record<ItemType, number> {\n  return itemTypes.reduce(\n    (acc, value) => {\n      acc[value] = 0;\n      return acc;\n    },\n    {} as Record<ItemType, number>,\n  );\n}\n\nfunction zeroByStatus(statuses: string[]): Record<ItemStatus, number> {\n  return statuses.reduce(\n    (acc, value) => {\n      acc[value] = 0;\n      return acc;\n    },\n    {} as Record<ItemStatus, number>,\n  );\n}\n\nfunction countNonEmptyLines(raw: string): number {\n  if (raw.trim().length === 0) {\n    return 0;\n  }\n  return raw.split(/\\r?\\n/u).filter((line) => line.trim().length > 0).length;\n}\n\nasync function readHistoryStreamContents(\n  pmRoot: string,\n): Promise<Array<{ id: string; raw: string }>> {\n  const historyDir = path.join(pmRoot, \"history\");\n  if (!(await pathExists(historyDir))) {\n    return [];\n  }\n\n  await runActiveOnReadHooks({\n    path: historyDir,\n    scope: \"project\",\n  });\n  const historyFiles = (await fs.readdir(historyDir))\n    .filter((entry) => entry.endsWith(\".jsonl\"))\n    .sort((a, b) => a.localeCompare(b));\n\n  const streams: Array<{ id: string; raw: string }> = [];\n  for (const file of historyFiles) {\n    const historyPath = path.join(historyDir, file);\n    const raw = await readFileIfExists(historyPath);\n    if (raw === null) {\n      continue;\n    }\n    await runActiveOnReadHooks({\n      path: historyPath,\n      scope: \"project\",\n    });\n    streams.push({ id: file.slice(0, -\".jsonl\".length), raw });\n  }\n\n  return streams;\n}\n\n/** Public contract for test only, shared by SDK and presentation-layer consumers. */\nexport const _testOnly = {\n  zeroByType,\n  zeroByStatus,\n  countNonEmptyLines,\n  readHistoryStreamContents,\n};\n\n/** Implements run stats for the public runtime surface of this module. */\nexport async function runStats(\n  global: GlobalOptions,\n  options: StatsCommandOptions = {},\n): Promise<StatsResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(\n    settings,\n    getActiveExtensionRegistrations(),\n  );\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  // Field utilization needs the heavy collections (notes/learnings/files/docs/\n  // tests/comments/deps) AND the body, which the light reader drops — so when it\n  // is requested we read the WithBody rows and use them for every section.\n  const items = options.fieldUtilization\n    ? await listAllItemMetadataWithBody(\n        pmRoot,\n        settings.item_format,\n        typeRegistry.type_to_folder,\n        undefined,\n        settings.schema,\n      )\n    : await listAllItemMetadataLight(\n        pmRoot,\n        settings.item_format,\n        typeRegistry.type_to_folder,\n        undefined,\n        settings.schema,\n      );\n  await enforceHistoryStreamPolicyForItems({\n    pmRoot,\n    settings,\n    itemIds: items.map((item) => item.id),\n    commandLabel: \"stats\",\n  });\n\n  const byType = zeroByType(typeRegistry.types);\n  const byStatus = zeroByStatus(\n    statusRegistry.definitions.map((definition) => definition.id),\n  );\n  // zeroByType/zeroByStatus pre-seed a bucket for every registry type/status, and\n  // the light item-metadata reader drops any item whose type/status falls outside\n  // the active registry (parse rejects them) — so every item's bucket is already\n  // present here and no on-the-fly initialization is reachable.\n  for (const item of items) {\n    byType[item.type] += 1;\n    byStatus[item.status] += 1;\n  }\n\n  const streams = await readHistoryStreamContents(pmRoot);\n  let historyEntries = 0;\n  for (const stream of streams) {\n    historyEntries += countNonEmptyLines(stream.raw);\n  }\n  const storage = options.storage\n    ? computeHistoryStorageStats(streams)\n    : undefined;\n\n  const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);\n  const metadataCoverage = options.metadataCoverage\n    ? computeMetadataCoverage(items, classifier)\n    : undefined;\n  const breakdowns: NonNullable<StatsResult[\"breakdowns\"]> = {};\n  if (options.byAssignee) {\n    breakdowns.assignee = groupItemsByDimension(items, \"assignee\", classifier);\n  }\n  if (options.byTag) {\n    breakdowns.tag = groupItemsByDimension(items, \"tag\", classifier, {\n      tagPrefix: options.tagPrefix,\n    });\n  }\n  if (options.byPriority) {\n    breakdowns.priority = groupItemsByDimension(items, \"priority\", classifier);\n  }\n  const hasBreakdowns = Object.keys(breakdowns).length > 0;\n  const fieldUtilization = options.fieldUtilization\n    ? computeContentFieldUtilization(items)\n    : undefined;\n\n  return {\n    totals: {\n      items: items.length,\n      history_streams: streams.length,\n      history_entries: historyEntries,\n    },\n    by_type: byType,\n    by_status: byStatus,\n    ...(metadataCoverage ? { metadata_coverage: metadataCoverage } : {}),\n    ...(hasBreakdowns ? { breakdowns } : {}),\n    ...(storage ? { storage } : {}),\n    ...(fieldUtilization ? { field_utilization: fieldUtilization } : {}),\n    generated_at: nowIso(),\n  };\n}\n"],"names":[],"mappings":"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","debugId":"afed0a81-eee3-5a32-9ebb-79f6f64301c5"}

package/dist/sdk/workspace-transaction-gc.d.ts

@@ -0,0 +1,46 @@
+/** Documents one journal-sweep decision row surfaced by the transaction GC. */
+export interface WorkspaceTransactionGcEntry {
+    /** Relative path like "transactions/sdk/<transactionId>.json". */
+    file: string;
+    /** Journal status read from the receipt, or null when unreadable. */
+    status: string | null;
+    /** Age in seconds derived from the journal's updatedAt, or null when unparseable. */
+    age_seconds: number | null;
+    /** Whether the journal was (or would be) pruned. */
+    stale: boolean;
+    /** Why the journal was retained, when it was. */
+    reason?: "active" | "fresh" | "unparseable";
+}
+/** Extension hooks mirroring the checkpoint GC so reads/writes stay observable. */
+export interface WorkspaceTransactionGcHooks {
+    /** Invoked before reading each journal file. */
+    onRead?: (absolutePath: string) => Promise<string[]>;
+    /** Invoked after removing each journal file. */
+    onWrite?: (absolutePath: string) => Promise<string[]>;
+}
+/** Documents the transaction GC options payload exchanged by command, SDK, and package integrations. */
+export interface WorkspaceTransactionGcOptions {
+    /** Preview prune decisions without deleting any journal. */
+    dryRun: boolean;
+    /** Prune terminal journals older than this many days. Negative values are clamped to zero; a non-finite value disables pruning entirely so bad input never deletes recovery receipts. */
+    retentionDays: number;
+    /** Clock override for deterministic tests (milliseconds since epoch). */
+    now?: number;
+    /** Extension observability hooks. */
+    hooks?: WorkspaceTransactionGcHooks;
+}
+/** Documents the transaction GC result payload exchanged by command, SDK, and package integrations. */
+export interface WorkspaceTransactionGcResult {
+    /** Number of journal files scanned. */
+    scanned: number;
+    /** Relative paths of pruned journals. */
+    removed: string[];
+    /** Relative paths of retained journals. */
+    retained: string[];
+    /** Non-fatal sweep warnings. */
+    warnings: string[];
+    /** One decision row per scanned journal. */
+    entries: WorkspaceTransactionGcEntry[];
+}
+/** Sweep `transactions/sdk/` and prune terminal workspace-transaction journals older than the retention window. One decision row is reported per journal so `pm gc` output stays auditable. */
+export declare function runWorkspaceTransactionGc(pmRoot: string, options: WorkspaceTransactionGcOptions): Promise<WorkspaceTransactionGcResult>;

package/dist/sdk/workspace-transaction-gc.js

@@ -0,0 +1,155 @@
+/**
+ * @module sdk/workspace-transaction-gc
+ *
+ * Age-based garbage collector for the durable SDK workspace-transaction
+ * journals written by `commitWorkspaceTransaction` under
+ * `transactions/sdk/<transactionId>.json`. Only terminal journals (status
+ * `committed` or `compensated`) older than the configured retention are
+ * pruned; in-flight journals (`applying`/`compensating`) are crash-recovery
+ * state and are always retained, as are journals whose status or timestamp
+ * cannot be read (safety-first, mirroring the checkpoint and stale-lock
+ * sweeps). Transaction steps are contract-idempotent, so pruning a terminal
+ * receipt only costs the ability to short-circuit an identical replay — it
+ * never breaks correctness.
+ */
+
+!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]="b27c5042-bbfb-5427-a76b-084acd5e06de")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+const TERMINAL_JOURNAL_STATUSES = new Set(["committed", "compensated"]);
+function isErrno(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+function readJournalStatusAndTimestamp(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { status: null, updatedAt: null };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { status: null, updatedAt: null };
+    }
+    const record = parsed;
+    return {
+        status: typeof record.status === "string" ? record.status : null,
+        updatedAt: typeof record.updatedAt === "string" ? record.updatedAt : null,
+    };
+}
+function classifyWorkspaceTransactionJournal(file, status, updatedAt, nowMs, retentionMs) {
+    const updatedAtMs = updatedAt === null ? Number.NaN : Date.parse(updatedAt);
+    if (status === null || !Number.isFinite(updatedAtMs)) {
+        return {
+            entry: {
+                file,
+                status,
+                age_seconds: null,
+                stale: false,
+                reason: "unparseable",
+            },
+            remove: false,
+        };
+    }
+    const ageMs = nowMs - updatedAtMs;
+    if (!TERMINAL_JOURNAL_STATUSES.has(status)) {
+        return {
+            entry: {
+                file,
+                status,
+                age_seconds: Math.floor(ageMs / 1000),
+                stale: false,
+                reason: "active",
+            },
+            remove: false,
+        };
+    }
+    // A non-finite retentionMs makes this comparison false, disabling pruning
+    // rather than risking deletion under bad input.
+    if (!(ageMs > retentionMs)) {
+        return {
+            entry: {
+                file,
+                status,
+                age_seconds: Math.floor(ageMs / 1000),
+                stale: false,
+                reason: "fresh",
+            },
+            remove: false,
+        };
+    }
+    return {
+        entry: {
+            file,
+            status,
+            age_seconds: Math.floor(ageMs / 1000),
+            stale: true,
+        },
+        remove: true,
+    };
+}
+async function processWorkspaceTransactionJournal(absolutePath, relativePath, fileName, options) {
+    const warnings = options.hooks?.onRead
+        ? await options.hooks.onRead(absolutePath)
+        : [];
+    const journal = readJournalStatusAndTimestamp(await fs.readFile(absolutePath, "utf8"));
+    const decision = classifyWorkspaceTransactionJournal(relativePath, journal.status, journal.updatedAt, options.nowMs, options.retentionMs);
+    if (decision.entry.reason === "unparseable") {
+        warnings.push(`transaction_journal_unparseable:${fileName}`);
+    }
+    if (decision.remove && !options.dryRun) {
+        await fs.rm(absolutePath, { force: true });
+        if (options.hooks?.onWrite) {
+            warnings.push(...(await options.hooks.onWrite(absolutePath)));
+        }
+    }
+    return { decision, warnings };
+}
+/** Sweep `transactions/sdk/` and prune terminal workspace-transaction journals older than the retention window. One decision row is reported per journal so `pm gc` output stays auditable. */
+export async function runWorkspaceTransactionGc(pmRoot, options) {
+    const { dryRun, hooks } = options;
+    const nowMs = options.now ?? Date.now();
+    const retentionMs = Math.max(0, options.retentionDays) * MILLISECONDS_PER_DAY;
+    const journalsDir = path.join(pmRoot, "transactions", "sdk");
+    const result = {
+        scanned: 0,
+        removed: [],
+        retained: [],
+        warnings: [],
+        entries: [],
+    };
+    let files;
+    try {
+        files = (await fs.readdir(journalsDir))
+            .filter((file) => file.endsWith(".json"))
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return result;
+        }
+        throw error;
+    }
+    for (const file of files) {
+        const absPath = path.join(journalsDir, file);
+        const relPath = `transactions/sdk/${file}`;
+        const fileResult = await processWorkspaceTransactionJournal(absPath, relPath, file, { dryRun, hooks, nowMs, retentionMs });
+        result.warnings.push(...fileResult.warnings);
+        result.scanned += 1;
+        const { decision } = fileResult;
+        if (!decision.remove) {
+            result.retained.push(relPath);
+            result.entries.push(decision.entry);
+            continue;
+        }
+        result.removed.push(relPath);
+        result.entries.push(decision.entry);
+    }
+    return result;
+}
+//# sourceMappingURL=workspace-transaction-gc.js.map
+//# debugId=b27c5042-bbfb-5427-a76b-084acd5e06de

package/dist/sdk/workspace-transaction-gc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-transaction-gc.js","sources":["sdk/workspace-transaction-gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/workspace-transaction-gc\n *\n * Age-based garbage collector for the durable SDK workspace-transaction\n * journals written by `commitWorkspaceTransaction` under\n * `transactions/sdk/<transactionId>.json`. Only terminal journals (status\n * `committed` or `compensated`) older than the configured retention are\n * pruned; in-flight journals (`applying`/`compensating`) are crash-recovery\n * state and are always retained, as are journals whose status or timestamp\n * cannot be read (safety-first, mirroring the checkpoint and stale-lock\n * sweeps). Transaction steps are contract-idempotent, so pruning a terminal\n * receipt only costs the ability to short-circuit an identical replay — it\n * never breaks correctness.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\nconst MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;\nconst TERMINAL_JOURNAL_STATUSES = new Set([\"committed\", \"compensated\"]);\n\n/** Documents one journal-sweep decision row surfaced by the transaction GC. */\nexport interface WorkspaceTransactionGcEntry {\n  /** Relative path like \"transactions/sdk/<transactionId>.json\". */\n  file: string;\n  /** Journal status read from the receipt, or null when unreadable. */\n  status: string | null;\n  /** Age in seconds derived from the journal's updatedAt, or null when unparseable. */\n  age_seconds: number | null;\n  /** Whether the journal was (or would be) pruned. */\n  stale: boolean;\n  /** Why the journal was retained, when it was. */\n  reason?: \"active\" | \"fresh\" | \"unparseable\";\n}\n\n/** Extension hooks mirroring the checkpoint GC so reads/writes stay observable. */\nexport interface WorkspaceTransactionGcHooks {\n  /** Invoked before reading each journal file. */\n  onRead?: (absolutePath: string) => Promise<string[]>;\n  /** Invoked after removing each journal file. */\n  onWrite?: (absolutePath: string) => Promise<string[]>;\n}\n\n/** Documents the transaction GC options payload exchanged by command, SDK, and package integrations. */\nexport interface WorkspaceTransactionGcOptions {\n  /** Preview prune decisions without deleting any journal. */\n  dryRun: boolean;\n  /** Prune terminal journals older than this many days. Negative values are clamped to zero; a non-finite value disables pruning entirely so bad input never deletes recovery receipts. */\n  retentionDays: number;\n  /** Clock override for deterministic tests (milliseconds since epoch). */\n  now?: number;\n  /** Extension observability hooks. */\n  hooks?: WorkspaceTransactionGcHooks;\n}\n\n/** Documents the transaction GC result payload exchanged by command, SDK, and package integrations. */\nexport interface WorkspaceTransactionGcResult {\n  /** Number of journal files scanned. */\n  scanned: number;\n  /** Relative paths of pruned journals. */\n  removed: string[];\n  /** Relative paths of retained journals. */\n  retained: string[];\n  /** Non-fatal sweep warnings. */\n  warnings: string[];\n  /** One decision row per scanned journal. */\n  entries: WorkspaceTransactionGcEntry[];\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"code\" in error &&\n    (error as { code?: string }).code === code\n  );\n}\n\nfunction readJournalStatusAndTimestamp(raw: string): {\n  status: string | null;\n  updatedAt: string | null;\n} {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw) as unknown;\n  } catch {\n    return { status: null, updatedAt: null };\n  }\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    return { status: null, updatedAt: null };\n  }\n  const record = parsed as Record<string, unknown>;\n  return {\n    status: typeof record.status === \"string\" ? record.status : null,\n    updatedAt: typeof record.updatedAt === \"string\" ? record.updatedAt : null,\n  };\n}\n\ninterface WorkspaceTransactionGcDecision {\n  /** Auditable decision row emitted for the journal. */\n  entry: WorkspaceTransactionGcEntry;\n  /** Whether the journal is old and terminal enough to remove. */\n  remove: boolean;\n}\n\ninterface WorkspaceTransactionGcFileResult {\n  /** Decision for the scanned journal. */\n  decision: WorkspaceTransactionGcDecision;\n  /** Extension and parse warnings accumulated while processing the file. */\n  warnings: string[];\n}\n\nfunction classifyWorkspaceTransactionJournal(\n  file: string,\n  status: string | null,\n  updatedAt: string | null,\n  nowMs: number,\n  retentionMs: number,\n): WorkspaceTransactionGcDecision {\n  const updatedAtMs = updatedAt === null ? Number.NaN : Date.parse(updatedAt);\n  if (status === null || !Number.isFinite(updatedAtMs)) {\n    return {\n      entry: {\n        file,\n        status,\n        age_seconds: null,\n        stale: false,\n        reason: \"unparseable\",\n      },\n      remove: false,\n    };\n  }\n  const ageMs = nowMs - updatedAtMs;\n  if (!TERMINAL_JOURNAL_STATUSES.has(status)) {\n    return {\n      entry: {\n        file,\n        status,\n        age_seconds: Math.floor(ageMs / 1000),\n        stale: false,\n        reason: \"active\",\n      },\n      remove: false,\n    };\n  }\n  // A non-finite retentionMs makes this comparison false, disabling pruning\n  // rather than risking deletion under bad input.\n  if (!(ageMs > retentionMs)) {\n    return {\n      entry: {\n        file,\n        status,\n        age_seconds: Math.floor(ageMs / 1000),\n        stale: false,\n        reason: \"fresh\",\n      },\n      remove: false,\n    };\n  }\n  return {\n    entry: {\n      file,\n      status,\n      age_seconds: Math.floor(ageMs / 1000),\n      stale: true,\n    },\n    remove: true,\n  };\n}\n\nasync function processWorkspaceTransactionJournal(\n  absolutePath: string,\n  relativePath: string,\n  fileName: string,\n  options: {\n    dryRun: boolean;\n    hooks: WorkspaceTransactionGcHooks | undefined;\n    nowMs: number;\n    retentionMs: number;\n  },\n): Promise<WorkspaceTransactionGcFileResult> {\n  const warnings = options.hooks?.onRead\n    ? await options.hooks.onRead(absolutePath)\n    : [];\n  const journal = readJournalStatusAndTimestamp(\n    await fs.readFile(absolutePath, \"utf8\"),\n  );\n  const decision = classifyWorkspaceTransactionJournal(\n    relativePath,\n    journal.status,\n    journal.updatedAt,\n    options.nowMs,\n    options.retentionMs,\n  );\n  if (decision.entry.reason === \"unparseable\") {\n    warnings.push(`transaction_journal_unparseable:${fileName}`);\n  }\n  if (decision.remove && !options.dryRun) {\n    await fs.rm(absolutePath, { force: true });\n    if (options.hooks?.onWrite) {\n      warnings.push(...(await options.hooks.onWrite(absolutePath)));\n    }\n  }\n  return { decision, warnings };\n}\n\n/** Sweep `transactions/sdk/` and prune terminal workspace-transaction journals older than the retention window. One decision row is reported per journal so `pm gc` output stays auditable. */\nexport async function runWorkspaceTransactionGc(\n  pmRoot: string,\n  options: WorkspaceTransactionGcOptions,\n): Promise<WorkspaceTransactionGcResult> {\n  const { dryRun, hooks } = options;\n  const nowMs = options.now ?? Date.now();\n  const retentionMs = Math.max(0, options.retentionDays) * MILLISECONDS_PER_DAY;\n  const journalsDir = path.join(pmRoot, \"transactions\", \"sdk\");\n  const result: WorkspaceTransactionGcResult = {\n    scanned: 0,\n    removed: [],\n    retained: [],\n    warnings: [],\n    entries: [],\n  };\n\n  let files: string[];\n  try {\n    files = (await fs.readdir(journalsDir))\n      .filter((file) => file.endsWith(\".json\"))\n      .sort((left, right) => left.localeCompare(right));\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return result;\n    }\n    throw error;\n  }\n\n  for (const file of files) {\n    const absPath = path.join(journalsDir, file);\n    const relPath = `transactions/sdk/${file}`;\n    const fileResult = await processWorkspaceTransactionJournal(\n      absPath,\n      relPath,\n      file,\n      { dryRun, hooks, nowMs, retentionMs },\n    );\n    result.warnings.push(...fileResult.warnings);\n    result.scanned += 1;\n    const { decision } = fileResult;\n    if (!decision.remove) {\n      result.retained.push(relPath);\n      result.entries.push(decision.entry);\n      continue;\n    }\n    result.removed.push(relPath);\n    result.entries.push(decision.entry);\n  }\n  return result;\n}\n"],"names":[],"mappings":"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","debugId":"b27c5042-bbfb-5427-a76b-084acd5e06de"}

package/dist/sdk/workspace.d.ts

@@ -2,6 +2,18 @@
 export declare const PM_GITIGNORE_START = "# pm-cli:runtime-cache:start";
 /** Closing marker for the init-owned ignore block. */
 export declare const PM_GITIGNORE_END = "# pm-cli:runtime-cache:end";
+/** Default workspace-relative tracker root used when no custom root is resolved. */
+export declare const PM_GITIGNORE_DEFAULT_TRACKER_ROOT = ".agents/pm";
+/**
+ * Tracker-relative directories that hold per-clone runtime state (caches,
+ * search indexes, locks, crash-recovery receipts). They must never be
+ * committed: they churn on every command and conflict on every concurrent
+ * branch merge. `transactions/` (SDK workspace-transaction journals) and
+ * `checkpoints/` (bulk-mutation rollback receipts) are per-branch recovery
+ * state with their own GC (`pm gc --scope transactions|checkpoints`), so
+ * keeping them untracked is the recorded merge-safety disposition.
+ */
+export declare const PM_GITIGNORE_RUNTIME_DIRECTORIES: readonly ["runtime/", "search/", "locks/", "transactions/", "checkpoints/"];
 /** Result of reconciling the init-owned repository ignore block. */
 export interface EnsurePmGitignoreResult {
     /** Absolute path to the reconciled file. */
@@ -9,7 +21,19 @@ export interface EnsurePmGitignoreResult {
     /** Whether the file content changed. */
     changed: boolean;
 }
-/** Return the canonical pm ignore block, primarily for documentation and tests. */
-export declare function getPmGitignoreBlock(): string;
-/** Idempotently create or replace the fenced pm cache block in a workspace `.gitignore`. */
-export declare function ensurePmGitignore(workspaceRoot: string): Promise<EnsurePmGitignoreResult>;
+/** Return whether a relative path escapes its owning root, without rejecting valid names such as `..pm`. */
+export declare function isPathOutsideRoot(relativePath: string): boolean;
+/** Return the canonical pm ignore block rendered for the given workspace-relative tracker root (defaults to `.agents/pm`), primarily for documentation and tests. */
+export declare function getPmGitignoreBlock(trackerRelativeRoot?: string): string;
+/**
+ * Idempotently create or replace the fenced pm cache block in a workspace
+ * `.gitignore`. When `pmRoot` is provided the ignored runtime directories are
+ * rendered under the resolved workspace-relative tracker root, so custom-root
+ * workspaces (`--pm-path`/`PM_PATH`) stop committing runtime caches (GH-598).
+ * A tracker root outside the workspace needs no ignore rules here, so the
+ * file is left untouched.
+ */
+export declare function ensurePmGitignore(workspaceRoot: string, options?: {
+    /** Absolute tracker root; rendered relative to the workspace root. */
+    pmRoot?: string;
+}): Promise<EnsurePmGitignoreResult>;

package/dist/sdk/workspace.js

@@ -4,27 +4,73 @@
  * Maintains repository-scaffold contracts shared by the public SDK and CLI.
  */
 
-!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]="5b3e660c-f869-5a00-8082-1f0d240c74bf")}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]="2ebcdfcf-c29b-50d6-940d-299d7699059a")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 /** Opening marker for the init-owned ignore block. */
 export const PM_GITIGNORE_START = "# pm-cli:runtime-cache:start";
 /** Closing marker for the init-owned ignore block. */
 export const PM_GITIGNORE_END = "# pm-cli:runtime-cache:end";
-const PM_GITIGNORE_BLOCK = [
-    PM_GITIGNORE_START,
-    ".agents/pm/runtime/",
-    ".agents/pm/search/",
-    ".agents/pm/locks/",
-    PM_GITIGNORE_END,
-].join("\n");
-/** Return the canonical pm ignore block, primarily for documentation and tests. */
-export function getPmGitignoreBlock() {
-    return PM_GITIGNORE_BLOCK;
+/** Default workspace-relative tracker root used when no custom root is resolved. */
+export const PM_GITIGNORE_DEFAULT_TRACKER_ROOT = ".agents/pm";
+/**
+ * Tracker-relative directories that hold per-clone runtime state (caches,
+ * search indexes, locks, crash-recovery receipts). They must never be
+ * committed: they churn on every command and conflict on every concurrent
+ * branch merge. `transactions/` (SDK workspace-transaction journals) and
+ * `checkpoints/` (bulk-mutation rollback receipts) are per-branch recovery
+ * state with their own GC (`pm gc --scope transactions|checkpoints`), so
+ * keeping them untracked is the recorded merge-safety disposition.
+ */
+export const PM_GITIGNORE_RUNTIME_DIRECTORIES = [
+    "runtime/",
+    "search/",
+    "locks/",
+    "transactions/",
+    "checkpoints/",
+];
+function normalizeTrackerRelativeRoot(trackerRelativeRoot) {
+    return trackerRelativeRoot
+        .replaceAll("\\", "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\/+$/, "");
+}
+/** Return whether a relative path escapes its owning root, without rejecting valid names such as `..pm`. */
+export function isPathOutsideRoot(relativePath) {
+    const normalized = relativePath.replaceAll("\\", "/");
+    return (path.isAbsolute(relativePath) ||
+        normalized === ".." ||
+        normalized.startsWith("../"));
 }
-/** Idempotently create or replace the fenced pm cache block in a workspace `.gitignore`. */
-export async function ensurePmGitignore(workspaceRoot) {
+/** Return the canonical pm ignore block rendered for the given workspace-relative tracker root (defaults to `.agents/pm`), primarily for documentation and tests. */
+export function getPmGitignoreBlock(trackerRelativeRoot = PM_GITIGNORE_DEFAULT_TRACKER_ROOT) {
+    const root = normalizeTrackerRelativeRoot(trackerRelativeRoot);
+    return [
+        PM_GITIGNORE_START,
+        ...PM_GITIGNORE_RUNTIME_DIRECTORIES.map((directory) => `${root}/${directory}`),
+        PM_GITIGNORE_END,
+    ].join("\n");
+}
+/**
+ * Idempotently create or replace the fenced pm cache block in a workspace
+ * `.gitignore`. When `pmRoot` is provided the ignored runtime directories are
+ * rendered under the resolved workspace-relative tracker root, so custom-root
+ * workspaces (`--pm-path`/`PM_PATH`) stop committing runtime caches (GH-598).
+ * A tracker root outside the workspace needs no ignore rules here, so the
+ * file is left untouched.
+ */
+export async function ensurePmGitignore(workspaceRoot, options = {}) {
     const gitignorePath = path.join(workspaceRoot, ".gitignore");
+    let trackerRelativeRoot = PM_GITIGNORE_DEFAULT_TRACKER_ROOT;
+    if (options.pmRoot !== undefined) {
+        const relative = normalizeTrackerRelativeRoot(path.relative(path.resolve(workspaceRoot), path.resolve(options.pmRoot)));
+        if (isPathOutsideRoot(relative)) {
+            return { path: gitignorePath, changed: false };
+        }
+        if (relative.length > 0) {
+            trackerRelativeRoot = relative;
+        }
+    }
     let current = "";
     try {
         current = await readFile(gitignorePath, "utf8");
@@ -40,7 +86,7 @@ export async function ensurePmGitignore(workspaceRoot) {
         ? `${current.slice(0, start)}${current.slice(end + PM_GITIGNORE_END.length)}`
         : current;
     const prefix = withoutManagedBlock.trimEnd();
-    const next = `${prefix.length > 0 ? `${prefix}\n\n` : ""}${PM_GITIGNORE_BLOCK}\n`;
+    const next = `${prefix.length > 0 ? `${prefix}\n\n` : ""}${getPmGitignoreBlock(trackerRelativeRoot)}\n`;
     if (next === current) {
         return { path: gitignorePath, changed: false };
     }
@@ -48,4 +94,4 @@ export async function ensurePmGitignore(workspaceRoot) {
     return { path: gitignorePath, changed: true };
 }
 //# sourceMappingURL=workspace.js.map
-//# debugId=5b3e660c-f869-5a00-8082-1f0d240c74bf
+//# debugId=2ebcdfcf-c29b-50d6-940d-299d7699059a

package/dist/sdk/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sources":["sdk/workspace.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/workspace\n *\n * Maintains repository-scaffold contracts shared by the public SDK and CLI.\n */\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\n/** Opening marker for the init-owned ignore block. */\nexport const PM_GITIGNORE_START = \"# pm-cli:runtime-cache:start\";\n/** Closing marker for the init-owned ignore block. */\nexport const PM_GITIGNORE_END = \"# pm-cli:runtime-cache:end\";\n\nconst PM_GITIGNORE_BLOCK = [\n  PM_GITIGNORE_START,\n  \".agents/pm/runtime/\",\n  \".agents/pm/search/\",\n  \".agents/pm/locks/\",\n  PM_GITIGNORE_END,\n].join(\"\\n\");\n\n/** Result of reconciling the init-owned repository ignore block. */\nexport interface EnsurePmGitignoreResult {\n  /** Absolute path to the reconciled file. */\n  path: string;\n  /** Whether the file content changed. */\n  changed: boolean;\n}\n\n/** Return the canonical pm ignore block, primarily for documentation and tests. */\nexport function getPmGitignoreBlock(): string {\n  return PM_GITIGNORE_BLOCK;\n}\n\n/** Idempotently create or replace the fenced pm cache block in a workspace `.gitignore`. */\nexport async function ensurePmGitignore(\n  workspaceRoot: string,\n): Promise<EnsurePmGitignoreResult> {\n  const gitignorePath = path.join(workspaceRoot, \".gitignore\");\n  let current = \"\";\n  try {\n    current = await readFile(gitignorePath, \"utf8\");\n  } catch (error: unknown) {\n    if (!(error instanceof Error && \"code\" in error && error.code === \"ENOENT\")) {\n      throw error;\n    }\n  }\n  const start = current.indexOf(PM_GITIGNORE_START);\n  const end = current.indexOf(PM_GITIGNORE_END);\n  const withoutManagedBlock =\n    start >= 0 && end >= start\n      ? `${current.slice(0, start)}${current.slice(end + PM_GITIGNORE_END.length)}`\n      : current;\n  const prefix = withoutManagedBlock.trimEnd();\n  const next = `${prefix.length > 0 ? `${prefix}\\n\\n` : \"\"}${PM_GITIGNORE_BLOCK}\\n`;\n  if (next === current) {\n    return { path: gitignorePath, changed: false };\n  }\n  await writeFile(gitignorePath, next, \"utf8\");\n  return { path: gitignorePath, changed: true };\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,sDAAsD;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;AACjE,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAE7D,MAAM,kBAAkB,GAAG;IACzB,kBAAkB;IAClB,qBAAqB;IACrB,oBAAoB;IACpB,mBAAmB;IACnB,gBAAgB;CACjB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAUb,mFAAmF;AACnF,MAAM,UAAU,mBAAmB;IACjC,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,aAAqB;IAErB,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC7D,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC5E,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9C,MAAM,mBAAmB,GACvB,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,KAAK;QACxB,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,gBAAgB,CAAC,MAAM,CAAC,EAAE;QAC7E,CAAC,CAAC,OAAO,CAAC;IACd,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,kBAAkB,IAAI,CAAC;IAClF,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACjD,CAAC;IACD,MAAM,SAAS,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAChD,CAAC","debugId":"5b3e660c-f869-5a00-8082-1f0d240c74bf"}
+{"version":3,"file":"workspace.js","sources":["sdk/workspace.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/workspace\n *\n * Maintains repository-scaffold contracts shared by the public SDK and CLI.\n */\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\n/** Opening marker for the init-owned ignore block. */\nexport const PM_GITIGNORE_START = \"# pm-cli:runtime-cache:start\";\n/** Closing marker for the init-owned ignore block. */\nexport const PM_GITIGNORE_END = \"# pm-cli:runtime-cache:end\";\n\n/** Default workspace-relative tracker root used when no custom root is resolved. */\nexport const PM_GITIGNORE_DEFAULT_TRACKER_ROOT = \".agents/pm\";\n\n/**\n * Tracker-relative directories that hold per-clone runtime state (caches,\n * search indexes, locks, crash-recovery receipts). They must never be\n * committed: they churn on every command and conflict on every concurrent\n * branch merge. `transactions/` (SDK workspace-transaction journals) and\n * `checkpoints/` (bulk-mutation rollback receipts) are per-branch recovery\n * state with their own GC (`pm gc --scope transactions|checkpoints`), so\n * keeping them untracked is the recorded merge-safety disposition.\n */\nexport const PM_GITIGNORE_RUNTIME_DIRECTORIES = [\n  \"runtime/\",\n  \"search/\",\n  \"locks/\",\n  \"transactions/\",\n  \"checkpoints/\",\n] as const;\n\n/** Result of reconciling the init-owned repository ignore block. */\nexport interface EnsurePmGitignoreResult {\n  /** Absolute path to the reconciled file. */\n  path: string;\n  /** Whether the file content changed. */\n  changed: boolean;\n}\n\nfunction normalizeTrackerRelativeRoot(trackerRelativeRoot: string): string {\n  return trackerRelativeRoot\n    .replaceAll(\"\\\\\", \"/\")\n    .replace(/^\\.\\/+/, \"\")\n    .replace(/\\/+$/, \"\");\n}\n\n/** Return whether a relative path escapes its owning root, without rejecting valid names such as `..pm`. */\nexport function isPathOutsideRoot(relativePath: string): boolean {\n  const normalized = relativePath.replaceAll(\"\\\\\", \"/\");\n  return (\n    path.isAbsolute(relativePath) ||\n    normalized === \"..\" ||\n    normalized.startsWith(\"../\")\n  );\n}\n\n/** Return the canonical pm ignore block rendered for the given workspace-relative tracker root (defaults to `.agents/pm`), primarily for documentation and tests. */\nexport function getPmGitignoreBlock(\n  trackerRelativeRoot: string = PM_GITIGNORE_DEFAULT_TRACKER_ROOT,\n): string {\n  const root = normalizeTrackerRelativeRoot(trackerRelativeRoot);\n  return [\n    PM_GITIGNORE_START,\n    ...PM_GITIGNORE_RUNTIME_DIRECTORIES.map(\n      (directory) => `${root}/${directory}`,\n    ),\n    PM_GITIGNORE_END,\n  ].join(\"\\n\");\n}\n\n/**\n * Idempotently create or replace the fenced pm cache block in a workspace\n * `.gitignore`. When `pmRoot` is provided the ignored runtime directories are\n * rendered under the resolved workspace-relative tracker root, so custom-root\n * workspaces (`--pm-path`/`PM_PATH`) stop committing runtime caches (GH-598).\n * A tracker root outside the workspace needs no ignore rules here, so the\n * file is left untouched.\n */\nexport async function ensurePmGitignore(\n  workspaceRoot: string,\n  options: {\n    /** Absolute tracker root; rendered relative to the workspace root. */\n    pmRoot?: string;\n  } = {},\n): Promise<EnsurePmGitignoreResult> {\n  const gitignorePath = path.join(workspaceRoot, \".gitignore\");\n  let trackerRelativeRoot = PM_GITIGNORE_DEFAULT_TRACKER_ROOT;\n  if (options.pmRoot !== undefined) {\n    const relative = normalizeTrackerRelativeRoot(\n      path.relative(path.resolve(workspaceRoot), path.resolve(options.pmRoot)),\n    );\n    if (isPathOutsideRoot(relative)) {\n      return { path: gitignorePath, changed: false };\n    }\n    if (relative.length > 0) {\n      trackerRelativeRoot = relative;\n    }\n  }\n  let current = \"\";\n  try {\n    current = await readFile(gitignorePath, \"utf8\");\n  } catch (error: unknown) {\n    if (\n      !(error instanceof Error && \"code\" in error && error.code === \"ENOENT\")\n    ) {\n      throw error;\n    }\n  }\n  const start = current.indexOf(PM_GITIGNORE_START);\n  const end = current.indexOf(PM_GITIGNORE_END);\n  const withoutManagedBlock =\n    start >= 0 && end >= start\n      ? `${current.slice(0, start)}${current.slice(end + PM_GITIGNORE_END.length)}`\n      : current;\n  const prefix = withoutManagedBlock.trimEnd();\n  const next = `${prefix.length > 0 ? `${prefix}\\n\\n` : \"\"}${getPmGitignoreBlock(trackerRelativeRoot)}\\n`;\n  if (next === current) {\n    return { path: gitignorePath, changed: false };\n  }\n  await writeFile(gitignorePath, next, \"utf8\");\n  return { path: gitignorePath, changed: true };\n}\n"],"names":[],"mappings":"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","debugId":"2ebcdfcf-c29b-50d6-940d-299d7699059a"}

package/dist/types.d.ts

@@ -447,17 +447,17 @@ export interface RuntimeFieldDefinition {
 }
 /** Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations. */
 export interface RuntimeWorkflowDefinition {
-    /** Lifecycle state reported for draftthe record. */
+    /** Configured status id representing the draft lifecycle state. */
     draft_status?: string;
-    /** Lifecycle state reported for openthe record. */
+    /** Configured status id representing the open lifecycle state. */
     open_status?: string;
-    /** Lifecycle state reported for in progressthe record. */
+    /** Configured status id representing the in-progress lifecycle state. */
     in_progress_status?: string;
-    /** Lifecycle state reported for blockedthe record. */
+    /** Configured status id representing the blocked lifecycle state. */
     blocked_status?: string;
-    /** Lifecycle state reported for closethe record. */
+    /** Configured status id representing the closed lifecycle state. */
     close_status?: string;
-    /** Lifecycle state reported for canceledthe record. */
+    /** Configured status id representing the canceled lifecycle state. */
     canceled_status?: string;
 }
 /** Documents the runtime schema file config payload exchanged by command, SDK, and package integrations. */
@@ -903,6 +903,10 @@ export interface PmSettings {
     version: number;
     /** Value that configures or reports id prefix for this contract. */
     id_prefix: string;
+    /** Item id allocation policy: `token_length` is the number of random base36 characters appended to `id_prefix` when minting ids (4–12). Longer tokens shrink cross-branch collision odds for concurrent multi-agent workflows: 4 chars ≈ 1.68M ids (~1% birthday-collision at ~184 items), 6 chars ≈ 2.18B (~1% at ~6.6k items), 8 chars ≈ 2.8T (~1% at ~238k items). */
+    ids: {
+        token_length: number;
+    };
     /** Value that configures or reports author default for this contract. */
     author_default: string;
     /** Value that configures or reports item format for this contract. */
@@ -913,7 +917,7 @@ export interface PmSettings {
         /** Bounded wait budget (milliseconds) for acquiring a contended item lock before surfacing lock_conflict. 0 disables waiting (fail-fast). Overridable per invocation via PM_LOCK_WAIT_MS. */
         wait_ms: number;
     };
-    /** Retention policy for bulk-mutation rollback checkpoints written by `update-many`/`close-many`. `pm gc --scope checkpoints` prunes checkpoint files older than `retention_days`; checkpoints with an unparseable `created_at` are retained (safety-first, mirroring the stale-lock sweep). */
+    /** Retention policy for local crash-recovery receipts: bulk-mutation rollback checkpoints written by `update-many`/`close-many` AND terminal SDK workspace-transaction journals under `transactions/sdk/`. `pm gc --scope checkpoints` prunes checkpoint files older than `retention_days`; `pm gc --scope transactions` prunes committed/compensated journals older than the same window. Unparseable receipts and in-flight journals are always retained (safety-first, mirroring the stale-lock sweep). */
     checkpoints: {
         retention_days: number;
     };

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]="24e69ccc-1d29-57b3-95a8-73e2501548f0")}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]="0ac15454-83a5-5908-b602-2f84dcec66c0")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -231,4 +231,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=24e69ccc-1d29-57b3-95a8-73e2501548f0
+//# debugId=0ac15454-83a5-5908-b602-2f84dcec66c0