@unbrained/pm-cli 2026.6.5 → 2026.6.6

package/dist/core/history/history-diff.d.ts

@@ -0,0 +1,47 @@
+import type { HistoryEntry } from "../../types/index.js";
+export interface HistoryFieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+export interface HistoryDiffValueEntry {
+    /** 1-based position in the FULL stream (fullEntries index + 1). */
+    index: number;
+    ts: string;
+    op: string;
+    author: string;
+    /** Number of JSON-patch operations in this entry (entry.patch.length). */
+    patch_ops: number;
+    /** Unique field names touched by this entry, sorted by localeCompare. */
+    changed_fields: string[];
+    /** Per-field before/after values, sorted by field name (localeCompare). */
+    changes: HistoryFieldChange[];
+}
+/**
+ * Map a JSON-Patch path string to a human-readable changed-field name.
+ *
+ * Rules (in priority order):
+ *  - "/body" or "/body/…"                      → "body"
+ *  - "/metadata/…" or "/front_matter/…"
+ *      with a first segment                     → that decoded segment (e.g. "status")
+ *      without a first segment (bare prefix)    → "metadata"
+ *  - "/" (root pointer, empty segment after strip) → "root"
+ *  - anything else                               → decoded first path segment
+ */
+export declare function patchPathToChangedField(path: string): string;
+/**
+ * Replay a full history entry stream and produce enriched diff entries with
+ * per-field before/after values.
+ *
+ * @param fullEntries   The complete ordered history chain to replay.
+ * @param options.windowStartIndex  0-based index into fullEntries at which the
+ *   DISPLAYED window begins. Entries before this index are still replayed (so
+ *   state is accurate) but are not emitted. Defaults to 0.
+ * @param options.field  When supplied, only entries that changed this field are
+ *   emitted, and each emitted entry's `changes` and `changed_fields` are
+ *   restricted to that single field.
+ */
+export declare function computeHistoryDiff(fullEntries: HistoryEntry[], options?: {
+    windowStartIndex?: number;
+    field?: string;
+}): HistoryDiffValueEntry[];

package/dist/core/history/history-diff.js

@@ -0,0 +1,152 @@
+
+!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]="2b77be38-f27c-5a56-86de-9625777f7211")}catch(e){}}();
+import { cloneEmptyReplayDocument, tryApplyReplayPatch } from "./replay.js";
+// ---------------------------------------------------------------------------
+// JSON-Pointer helpers (ported from src/cli/commands/history.ts so the
+// orchestrator can replace the private copy there with an import from here).
+// ---------------------------------------------------------------------------
+function decodeJsonPointerSegment(segment) {
+    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+/**
+ * Map a JSON-Patch path string to a human-readable changed-field name.
+ *
+ * Rules (in priority order):
+ *  - "/body" or "/body/…"                      → "body"
+ *  - "/metadata/…" or "/front_matter/…"
+ *      with a first segment                     → that decoded segment (e.g. "status")
+ *      without a first segment (bare prefix)    → "metadata"
+ *  - "/" (root pointer, empty segment after strip) → "root"
+ *  - anything else                               → decoded first path segment
+ */
+export function patchPathToChangedField(path) {
+    if (path === "/body" || path.startsWith("/body/"))
+        return "body";
+    if (path === "/metadata" ||
+        path.startsWith("/metadata/") ||
+        path === "/front_matter" ||
+        path.startsWith("/front_matter/")) {
+        const segment = path.replace(/^\/(?:metadata|front_matter)\/?/, "").split("/")[0];
+        if (!segment)
+            return "metadata";
+        return decodeJsonPointerSegment(segment);
+    }
+    const segment = path.replace(/^\//, "").split("/")[0];
+    return segment ? decodeJsonPointerSegment(segment) : "root";
+}
+// ---------------------------------------------------------------------------
+// Field-value reader
+// ---------------------------------------------------------------------------
+/**
+ * Extract the before/after value for a logical field from a replay document.
+ *
+ * - "body"     → doc.body
+ * - "metadata" → doc.metadata (the whole object, for a bare /metadata replace)
+ * - "root"     → the whole document (for a bare "/" patch op)
+ * - other      → doc.metadata[field] (may be undefined when the field was absent)
+ */
+function readFieldValue(doc, field) {
+    if (field === "body")
+        return doc.body;
+    if (field === "metadata")
+        return doc.metadata;
+    if (field === "root")
+        return doc;
+    return doc.metadata[field];
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Replay a full history entry stream and produce enriched diff entries with
+ * per-field before/after values.
+ *
+ * @param fullEntries   The complete ordered history chain to replay.
+ * @param options.windowStartIndex  0-based index into fullEntries at which the
+ *   DISPLAYED window begins. Entries before this index are still replayed (so
+ *   state is accurate) but are not emitted. Defaults to 0.
+ * @param options.field  When supplied, only entries that changed this field are
+ *   emitted, and each emitted entry's `changes` and `changed_fields` are
+ *   restricted to that single field.
+ */
+export function computeHistoryDiff(fullEntries, options) {
+    const windowStartIndex = options?.windowStartIndex ?? 0;
+    const fieldFilter = options?.field;
+    if (fullEntries.length === 0 || windowStartIndex >= fullEntries.length) {
+        return [];
+    }
+    let current = cloneEmptyReplayDocument();
+    const result = [];
+    for (let p = 0; p < fullEntries.length; p += 1) {
+        const entry = fullEntries[p];
+        // Capture before state.
+        const beforeDoc = current;
+        // Attempt to apply patch.
+        const applied = tryApplyReplayPatch(current, entry.patch);
+        let afterDoc;
+        if (applied.ok) {
+            afterDoc = applied.document;
+            current = afterDoc;
+        }
+        else {
+            // Patch failed — use before state as after (cannot trust partial result).
+            // Do NOT advance current; keep prior replay state.
+            afterDoc = beforeDoc;
+        }
+        // Collect changed field names from patch paths (and from: paths for move/copy).
+        const changedFieldSet = new Set();
+        for (const patchOp of entry.patch) {
+            changedFieldSet.add(patchPathToChangedField(patchOp.path));
+            if (patchOp.from !== undefined) {
+                changedFieldSet.add(patchPathToChangedField(patchOp.from));
+            }
+        }
+        const sortedFields = [...changedFieldSet].sort((a, b) => a.localeCompare(b));
+        // Only emit entries in the display window.
+        if (p >= windowStartIndex) {
+            // Apply field filter: skip this entry entirely if it doesn't touch the
+            // requested field; otherwise narrow down to only that field.
+            if (fieldFilter !== undefined) {
+                if (!changedFieldSet.has(fieldFilter)) {
+                    // This entry does not touch the requested field — skip it.
+                    continue;
+                }
+                // Emit only the filtered field.
+                const change = {
+                    field: fieldFilter,
+                    before: readFieldValue(beforeDoc, fieldFilter),
+                    after: readFieldValue(afterDoc, fieldFilter),
+                };
+                result.push({
+                    index: p + 1,
+                    ts: entry.ts,
+                    op: entry.op,
+                    author: entry.author,
+                    patch_ops: entry.patch.length,
+                    changed_fields: [fieldFilter],
+                    changes: [change],
+                });
+            }
+            else {
+                // Emit all changed fields.
+                const changes = sortedFields.map((field) => ({
+                    field,
+                    before: readFieldValue(beforeDoc, field),
+                    after: readFieldValue(afterDoc, field),
+                }));
+                result.push({
+                    index: p + 1,
+                    ts: entry.ts,
+                    op: entry.op,
+                    author: entry.author,
+                    patch_ops: entry.patch.length,
+                    changed_fields: sortedFields,
+                    changes,
+                });
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=history-diff.js.map
+//# debugId=2b77be38-f27c-5a56-86de-9625777f7211

package/dist/core/history/history-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-diff.js","sources":["core/history/history-diff.ts"],"sourceRoot":"/","sourcesContent":["import { cloneEmptyReplayDocument, tryApplyReplayPatch, type ReplayDocument } from \"./replay.js\";\nimport type { HistoryEntry } from \"../../types/index.js\";\n\nexport interface HistoryFieldChange {\n  field: string;\n  // before and after are the raw field values captured by replaying the history chain.\n  // `undefined` is intentional: it signals that the field was absent in the document at\n  // that point (e.g. after a JSON-Patch `remove` op). JSON serialization will omit\n  // undefined values, which correctly communicates \"field did not exist\".\n  before: unknown;\n  after: unknown;\n}\n\nexport interface HistoryDiffValueEntry {\n  /** 1-based position in the FULL stream (fullEntries index + 1). */\n  index: number;\n  ts: string;\n  op: string;\n  author: string;\n  /** Number of JSON-patch operations in this entry (entry.patch.length). */\n  patch_ops: number;\n  /** Unique field names touched by this entry, sorted by localeCompare. */\n  changed_fields: string[];\n  /** Per-field before/after values, sorted by field name (localeCompare). */\n  changes: HistoryFieldChange[];\n}\n\n// ---------------------------------------------------------------------------\n// JSON-Pointer helpers (ported from src/cli/commands/history.ts so the\n// orchestrator can replace the private copy there with an import from here).\n// ---------------------------------------------------------------------------\n\nfunction decodeJsonPointerSegment(segment: string): string {\n  return segment.replaceAll(\"~1\", \"/\").replaceAll(\"~0\", \"~\");\n}\n\n/**\n * Map a JSON-Patch path string to a human-readable changed-field name.\n *\n * Rules (in priority order):\n *  - \"/body\" or \"/body/…\"                      → \"body\"\n *  - \"/metadata/…\" or \"/front_matter/…\"\n *      with a first segment                     → that decoded segment (e.g. \"status\")\n *      without a first segment (bare prefix)    → \"metadata\"\n *  - \"/\" (root pointer, empty segment after strip) → \"root\"\n *  - anything else                               → decoded first path segment\n */\nexport function patchPathToChangedField(path: string): string {\n  if (path === \"/body\" || path.startsWith(\"/body/\")) return \"body\";\n  if (\n    path === \"/metadata\" ||\n    path.startsWith(\"/metadata/\") ||\n    path === \"/front_matter\" ||\n    path.startsWith(\"/front_matter/\")\n  ) {\n    const segment = path.replace(/^\\/(?:metadata|front_matter)\\/?/, \"\").split(\"/\")[0];\n    if (!segment) return \"metadata\";\n    return decodeJsonPointerSegment(segment);\n  }\n  const segment = path.replace(/^\\//, \"\").split(\"/\")[0];\n  return segment ? decodeJsonPointerSegment(segment) : \"root\";\n}\n\n// ---------------------------------------------------------------------------\n// Field-value reader\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the before/after value for a logical field from a replay document.\n *\n * - \"body\"     → doc.body\n * - \"metadata\" → doc.metadata (the whole object, for a bare /metadata replace)\n * - \"root\"     → the whole document (for a bare \"/\" patch op)\n * - other      → doc.metadata[field] (may be undefined when the field was absent)\n */\nfunction readFieldValue(doc: ReplayDocument, field: string): unknown {\n  if (field === \"body\") return doc.body;\n  if (field === \"metadata\") return doc.metadata;\n  if (field === \"root\") return doc;\n  return doc.metadata[field];\n}\n\n// ---------------------------------------------------------------------------\n// Main export\n// ---------------------------------------------------------------------------\n\n/**\n * Replay a full history entry stream and produce enriched diff entries with\n * per-field before/after values.\n *\n * @param fullEntries   The complete ordered history chain to replay.\n * @param options.windowStartIndex  0-based index into fullEntries at which the\n *   DISPLAYED window begins. Entries before this index are still replayed (so\n *   state is accurate) but are not emitted. Defaults to 0.\n * @param options.field  When supplied, only entries that changed this field are\n *   emitted, and each emitted entry's `changes` and `changed_fields` are\n *   restricted to that single field.\n */\nexport function computeHistoryDiff(\n  fullEntries: HistoryEntry[],\n  options?: { windowStartIndex?: number; field?: string },\n): HistoryDiffValueEntry[] {\n  const windowStartIndex = options?.windowStartIndex ?? 0;\n  const fieldFilter = options?.field;\n\n  if (fullEntries.length === 0 || windowStartIndex >= fullEntries.length) {\n    return [];\n  }\n\n  let current = cloneEmptyReplayDocument();\n  const result: HistoryDiffValueEntry[] = [];\n\n  for (let p = 0; p < fullEntries.length; p += 1) {\n    const entry = fullEntries[p];\n\n    // Capture before state.\n    const beforeDoc = current;\n\n    // Attempt to apply patch.\n    const applied = tryApplyReplayPatch(current, entry.patch);\n    let afterDoc: ReplayDocument;\n    if (applied.ok) {\n      afterDoc = applied.document;\n      current = afterDoc;\n    } else {\n      // Patch failed — use before state as after (cannot trust partial result).\n      // Do NOT advance current; keep prior replay state.\n      afterDoc = beforeDoc;\n    }\n\n    // Collect changed field names from patch paths (and from: paths for move/copy).\n    const changedFieldSet = new Set<string>();\n    for (const patchOp of entry.patch) {\n      changedFieldSet.add(patchPathToChangedField(patchOp.path));\n      if (patchOp.from !== undefined) {\n        changedFieldSet.add(patchPathToChangedField(patchOp.from));\n      }\n    }\n    const sortedFields = [...changedFieldSet].sort((a, b) => a.localeCompare(b));\n\n    // Only emit entries in the display window.\n    if (p >= windowStartIndex) {\n      // Apply field filter: skip this entry entirely if it doesn't touch the\n      // requested field; otherwise narrow down to only that field.\n      if (fieldFilter !== undefined) {\n        if (!changedFieldSet.has(fieldFilter)) {\n          // This entry does not touch the requested field — skip it.\n          continue;\n        }\n        // Emit only the filtered field.\n        const change: HistoryFieldChange = {\n          field: fieldFilter,\n          before: readFieldValue(beforeDoc, fieldFilter),\n          after: readFieldValue(afterDoc, fieldFilter),\n        };\n        result.push({\n          index: p + 1,\n          ts: entry.ts,\n          op: entry.op,\n          author: entry.author,\n          patch_ops: entry.patch.length,\n          changed_fields: [fieldFilter],\n          changes: [change],\n        });\n      } else {\n        // Emit all changed fields.\n        const changes: HistoryFieldChange[] = sortedFields.map((field) => ({\n          field,\n          before: readFieldValue(beforeDoc, field),\n          after: readFieldValue(afterDoc, field),\n        }));\n        result.push({\n          index: p + 1,\n          ts: entry.ts,\n          op: entry.op,\n          author: entry.author,\n          patch_ops: entry.patch.length,\n          changed_fields: sortedFields,\n          changes,\n        });\n      }\n    }\n  }\n\n  return result;\n}\n"],"names":[],"mappings":"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","debugId":"2b77be38-f27c-5a56-86de-9625777f7211"}

package/dist/core/history/history-storage-stats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure aggregate metrics for history streams (JSONL files).
+ * No filesystem access — callers read raw stream contents and pass them in.
+ * This module has no Node imports; Buffer is available as a global.
+ */
+export interface HistoryStreamStat {
+    id: string;
+    bytes: number;
+    lines: number;
+    oldest_ts: string | null;
+    newest_ts: string | null;
+}
+export interface HistoryStorageEntryRef {
+    id: string;
+    ts: string;
+}
+export interface HistoryStorageStats {
+    total_streams: number;
+    total_lines: number;
+    total_bytes: number;
+    largest_by_bytes: HistoryStreamStat[];
+    deepest_by_lines: HistoryStreamStat[];
+    oldest_entry: HistoryStorageEntryRef | null;
+    newest_entry: HistoryStorageEntryRef | null;
+}
+export declare function computeHistoryStorageStats(streams: Array<{
+    id: string;
+    raw: string;
+}>, options?: {
+    topN?: number;
+}): HistoryStorageStats;

package/dist/core/history/history-storage-stats.js

@@ -0,0 +1,101 @@
+/**
+ * Pure aggregate metrics for history streams (JSONL files).
+ * No filesystem access — callers read raw stream contents and pass them in.
+ * This module has no Node imports; Buffer is available as a global.
+ */
+
+!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]="006b5d42-0ff6-57af-a598-4ca069ec316e")}catch(e){}}();
+function parseStreamStat(id, raw) {
+    const bytes = Buffer.byteLength(raw, "utf8");
+    let lines = 0;
+    let oldestTs = null;
+    let newestTs = null;
+    let oldestMs = Number.POSITIVE_INFINITY;
+    let newestMs = Number.NEGATIVE_INFINITY;
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const trimmed = rawLine.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        lines += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            !("ts" in parsed) ||
+            typeof parsed["ts"] !== "string") {
+            continue;
+        }
+        const ts = parsed["ts"];
+        const ms = Date.parse(ts);
+        if (Number.isNaN(ms)) {
+            continue;
+        }
+        if (ms < oldestMs || (ms === oldestMs && oldestTs !== null && ts < oldestTs)) {
+            oldestMs = ms;
+            oldestTs = ts;
+        }
+        if (ms > newestMs || (ms === newestMs && newestTs !== null && ts > newestTs)) {
+            newestMs = ms;
+            newestTs = ts;
+        }
+    }
+    return { id, bytes, lines, oldest_ts: oldestTs, newest_ts: newestTs };
+}
+export function computeHistoryStorageStats(streams, options) {
+    const rawTopN = options?.topN ?? 5;
+    const topN = Math.max(0, Math.floor(rawTopN));
+    const stats = streams.map(({ id, raw }) => parseStreamStat(id, raw));
+    let totalLines = 0;
+    let totalBytes = 0;
+    let oldestEntry = null;
+    let newestEntry = null;
+    let globalOldestMs = Number.POSITIVE_INFINITY;
+    let globalNewestMs = Number.NEGATIVE_INFINITY;
+    for (const stat of stats) {
+        totalLines += stat.lines;
+        totalBytes += stat.bytes;
+        if (stat.oldest_ts !== null) {
+            const ms = Date.parse(stat.oldest_ts);
+            if (ms < globalOldestMs ||
+                (ms === globalOldestMs && oldestEntry !== null && stat.id < oldestEntry.id)) {
+                globalOldestMs = ms;
+                oldestEntry = { id: stat.id, ts: stat.oldest_ts };
+            }
+        }
+        if (stat.newest_ts !== null) {
+            const ms = Date.parse(stat.newest_ts);
+            if (ms > globalNewestMs ||
+                (ms === globalNewestMs && newestEntry !== null && stat.id < newestEntry.id)) {
+                globalNewestMs = ms;
+                newestEntry = { id: stat.id, ts: stat.newest_ts };
+            }
+        }
+    }
+    const largestByBytes = topN === 0
+        ? []
+        : [...stats]
+            .sort((a, b) => b.bytes - a.bytes || a.id.localeCompare(b.id))
+            .slice(0, topN);
+    const deepestByLines = topN === 0
+        ? []
+        : [...stats]
+            .sort((a, b) => b.lines - a.lines || a.id.localeCompare(b.id))
+            .slice(0, topN);
+    return {
+        total_streams: streams.length,
+        total_lines: totalLines,
+        total_bytes: totalBytes,
+        largest_by_bytes: largestByBytes,
+        deepest_by_lines: deepestByLines,
+        oldest_entry: oldestEntry,
+        newest_entry: newestEntry,
+    };
+}
+//# sourceMappingURL=history-storage-stats.js.map
+//# debugId=006b5d42-0ff6-57af-a598-4ca069ec316e

package/dist/core/history/history-storage-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-storage-stats.js","sources":["core/history/history-storage-stats.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Pure aggregate metrics for history streams (JSONL files).\n * No filesystem access — callers read raw stream contents and pass them in.\n * This module has no Node imports; Buffer is available as a global.\n */\n\nexport interface HistoryStreamStat {\n  id: string;\n  bytes: number;\n  lines: number; // non-empty JSONL entry count\n  oldest_ts: string | null; // min parseable ts in this stream, else null\n  newest_ts: string | null; // max parseable ts in this stream, else null\n}\n\nexport interface HistoryStorageEntryRef {\n  id: string;\n  ts: string;\n}\n\nexport interface HistoryStorageStats {\n  total_streams: number;\n  total_lines: number;\n  total_bytes: number;\n  largest_by_bytes: HistoryStreamStat[]; // top-N desc by bytes, tie-break id asc\n  deepest_by_lines: HistoryStreamStat[]; // top-N desc by lines, tie-break id asc\n  oldest_entry: HistoryStorageEntryRef | null; // global min ts across all streams\n  newest_entry: HistoryStorageEntryRef | null; // global max ts across all streams\n}\n\nfunction parseStreamStat(id: string, raw: string): HistoryStreamStat {\n  const bytes = Buffer.byteLength(raw, \"utf8\");\n\n  let lines = 0;\n  let oldestTs: string | null = null;\n  let newestTs: string | null = null;\n  let oldestMs = Number.POSITIVE_INFINITY;\n  let newestMs = Number.NEGATIVE_INFINITY;\n\n  for (const rawLine of raw.split(/\\r?\\n/)) {\n    const trimmed = rawLine.trim();\n    if (trimmed === \"\") {\n      continue;\n    }\n    lines += 1;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n\n    if (\n      parsed === null ||\n      typeof parsed !== \"object\" ||\n      !(\"ts\" in (parsed as object)) ||\n      typeof (parsed as Record<string, unknown>)[\"ts\"] !== \"string\"\n    ) {\n      continue;\n    }\n\n    const ts = (parsed as Record<string, unknown>)[\"ts\"] as string;\n    const ms = Date.parse(ts);\n    if (Number.isNaN(ms)) {\n      continue;\n    }\n\n    if (ms < oldestMs || (ms === oldestMs && oldestTs !== null && ts < oldestTs)) {\n      oldestMs = ms;\n      oldestTs = ts;\n    }\n    if (ms > newestMs || (ms === newestMs && newestTs !== null && ts > newestTs)) {\n      newestMs = ms;\n      newestTs = ts;\n    }\n  }\n\n  return { id, bytes, lines, oldest_ts: oldestTs, newest_ts: newestTs };\n}\n\nexport function computeHistoryStorageStats(\n  streams: Array<{ id: string; raw: string }>,\n  options?: { topN?: number },\n): HistoryStorageStats {\n  const rawTopN = options?.topN ?? 5;\n  const topN = Math.max(0, Math.floor(rawTopN));\n\n  const stats: HistoryStreamStat[] = streams.map(({ id, raw }) => parseStreamStat(id, raw));\n\n  let totalLines = 0;\n  let totalBytes = 0;\n  let oldestEntry: HistoryStorageEntryRef | null = null;\n  let newestEntry: HistoryStorageEntryRef | null = null;\n  let globalOldestMs = Number.POSITIVE_INFINITY;\n  let globalNewestMs = Number.NEGATIVE_INFINITY;\n\n  for (const stat of stats) {\n    totalLines += stat.lines;\n    totalBytes += stat.bytes;\n\n    if (stat.oldest_ts !== null) {\n      const ms = Date.parse(stat.oldest_ts);\n      if (\n        ms < globalOldestMs ||\n        (ms === globalOldestMs && oldestEntry !== null && stat.id < oldestEntry.id)\n      ) {\n        globalOldestMs = ms;\n        oldestEntry = { id: stat.id, ts: stat.oldest_ts };\n      }\n    }\n\n    if (stat.newest_ts !== null) {\n      const ms = Date.parse(stat.newest_ts);\n      if (\n        ms > globalNewestMs ||\n        (ms === globalNewestMs && newestEntry !== null && stat.id < newestEntry.id)\n      ) {\n        globalNewestMs = ms;\n        newestEntry = { id: stat.id, ts: stat.newest_ts };\n      }\n    }\n  }\n\n  const largestByBytes =\n    topN === 0\n      ? []\n      : [...stats]\n          .sort((a, b) => b.bytes - a.bytes || a.id.localeCompare(b.id))\n          .slice(0, topN);\n\n  const deepestByLines =\n    topN === 0\n      ? []\n      : [...stats]\n          .sort((a, b) => b.lines - a.lines || a.id.localeCompare(b.id))\n          .slice(0, topN);\n\n  return {\n    total_streams: streams.length,\n    total_lines: totalLines,\n    total_bytes: totalBytes,\n    largest_by_bytes: largestByBytes,\n    deepest_by_lines: deepestByLines,\n    oldest_entry: oldestEntry,\n    newest_entry: newestEntry,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"006b5d42-0ff6-57af-a598-4ca069ec316e"}

package/dist/core/lock/lock-gc.d.ts

@@ -0,0 +1,46 @@
+/**
+ * lock-gc.ts — Stale lock file garbage collector.
+ *
+ * Safety-first policy: if a lock file cannot be read or parsed, it is RETAINED
+ * rather than deleted. We only remove locks whose staleness can be conclusively
+ * determined from the lock's own embedded `ttl_seconds` field.
+ *
+ * Staleness formula: (now_ms - Date.parse(created_at)) > ttl_seconds * 1000
+ * Zero ttl means any lock older than 0 ms is stale. Negative ttl means always stale.
+ */
+export interface StaleLockScanEntry {
+    /** e.g. "pm-abc1.lock" */
+    file: string;
+    /** parsed id, or null if unparseable */
+    id: string | null;
+    owner: string | null;
+    created_at: string | null;
+    ttl_seconds: number | null;
+    /** floor((now - created_at)/1000), null if unparseable */
+    age_seconds: number | null;
+    /** true only when classified expired */
+    stale: boolean;
+    reason: "expired" | "active" | "unparseable";
+}
+export interface LockGcHooks {
+    onRead?: (lockPath: string) => Promise<string[]> | string[];
+    onWrite?: (lockPath: string) => Promise<string[]> | string[];
+}
+export interface LockGcOptions {
+    dryRun: boolean;
+    /** epoch ms; defaults to Date.now() — injectable for deterministic tests */
+    now?: number;
+    hooks?: LockGcHooks;
+}
+export interface LockGcResult {
+    /** number of *.lock files examined */
+    scanned: number;
+    /** relative paths like "locks/pm-abc1.lock" (removed, or would-remove under dryRun) */
+    removed: string[];
+    /** relative paths retained (active OR unparseable — never delete what we can't reason about) */
+    retained: string[];
+    warnings: string[];
+    /** one per scanned *.lock file, sorted by file name asc */
+    entries: StaleLockScanEntry[];
+}
+export declare function runLockGc(pmRoot: string, options: LockGcOptions): Promise<LockGcResult>;

package/dist/core/lock/lock-gc.js

@@ -0,0 +1,194 @@
+/**
+ * lock-gc.ts — Stale lock file garbage collector.
+ *
+ * Safety-first policy: if a lock file cannot be read or parsed, it is RETAINED
+ * rather than deleted. We only remove locks whose staleness can be conclusively
+ * determined from the lock's own embedded `ttl_seconds` field.
+ *
+ * Staleness formula: (now_ms - Date.parse(created_at)) > ttl_seconds * 1000
+ * Zero ttl means any lock older than 0 ms is stale. Negative ttl means always stale.
+ */
+
+!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]="1a412027-5c73-58d4-b696-4a909dde88a8")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+function parseLock(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const candidate = parsed;
+    const { id, owner, created_at, ttl_seconds } = candidate;
+    if (typeof id !== "string" ||
+        typeof owner !== "string" ||
+        typeof created_at !== "string" ||
+        typeof ttl_seconds !== "number" ||
+        !Number.isFinite(ttl_seconds)) {
+        return null;
+    }
+    return { id, owner, created_at, ttl_seconds };
+}
+function isErrno(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+export async function runLockGc(pmRoot, options) {
+    const { dryRun, hooks } = options;
+    const nowMs = options.now ?? Date.now();
+    const locksDir = path.join(pmRoot, "locks");
+    const result = {
+        scanned: 0,
+        removed: [],
+        retained: [],
+        warnings: [],
+        entries: [],
+    };
+    let dirEntries;
+    try {
+        const raw = await fs.readdir(locksDir);
+        dirEntries = raw.filter((f) => f.endsWith(".lock")).sort();
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return result;
+        }
+        throw error;
+    }
+    for (const file of dirEntries) {
+        result.scanned += 1;
+        const absPath = path.join(locksDir, file);
+        const relPath = `locks/${file}`;
+        // --- onRead hook ---
+        if (hooks?.onRead) {
+            const hookWarnings = await hooks.onRead(absPath);
+            result.warnings.push(...hookWarnings);
+        }
+        // --- read file ---
+        let raw;
+        try {
+            raw = await fs.readFile(absPath, "utf8");
+        }
+        catch (readError) {
+            if (isErrno(readError, "ENOENT")) {
+                // Disappeared between readdir and readFile — treat as a ghost; skip quietly.
+                result.scanned -= 1;
+                continue;
+            }
+            result.warnings.push(`lock_unreadable:${file}`);
+            result.retained.push(relPath);
+            result.entries.push({
+                file,
+                id: null,
+                owner: null,
+                created_at: null,
+                ttl_seconds: null,
+                age_seconds: null,
+                stale: false,
+                reason: "unparseable",
+            });
+            continue;
+        }
+        // --- parse ---
+        const lock = parseLock(raw);
+        if (lock === null) {
+            result.warnings.push(`lock_unparseable:${file}`);
+            result.retained.push(relPath);
+            result.entries.push({
+                file,
+                id: null,
+                owner: null,
+                created_at: null,
+                ttl_seconds: null,
+                age_seconds: null,
+                stale: false,
+                reason: "unparseable",
+            });
+            continue;
+        }
+        // --- validate timestamp ---
+        const createdAtMs = Date.parse(lock.created_at);
+        if (!Number.isFinite(createdAtMs)) {
+            result.warnings.push(`lock_invalid_timestamp:${file}`);
+            result.retained.push(relPath);
+            result.entries.push({
+                file,
+                id: lock.id,
+                owner: lock.owner,
+                created_at: lock.created_at,
+                ttl_seconds: lock.ttl_seconds,
+                age_seconds: null,
+                stale: false,
+                reason: "unparseable",
+            });
+            continue;
+        }
+        const ageMs = nowMs - createdAtMs;
+        const age_seconds = Math.floor(ageMs / 1000);
+        const stale = ageMs > lock.ttl_seconds * 1000;
+        if (!stale) {
+            result.retained.push(relPath);
+            result.entries.push({
+                file,
+                id: lock.id,
+                owner: lock.owner,
+                created_at: lock.created_at,
+                ttl_seconds: lock.ttl_seconds,
+                age_seconds,
+                stale: false,
+                reason: "active",
+            });
+            continue;
+        }
+        // --- stale: remove or preview ---
+        if (!dryRun) {
+            try {
+                await fs.unlink(absPath);
+            }
+            catch (unlinkError) {
+                if (!isErrno(unlinkError, "ENOENT")) {
+                    result.warnings.push(`lock_remove_failed:${file}`);
+                    result.retained.push(relPath);
+                    result.entries.push({
+                        file,
+                        id: lock.id,
+                        owner: lock.owner,
+                        created_at: lock.created_at,
+                        ttl_seconds: lock.ttl_seconds,
+                        age_seconds,
+                        stale: true,
+                        reason: "expired",
+                    });
+                    continue;
+                }
+                // ENOENT on unlink = already gone (race); treat as removed
+            }
+            // onWrite hook after successful removal
+            if (hooks?.onWrite) {
+                const hookWarnings = await hooks.onWrite(absPath);
+                result.warnings.push(...hookWarnings);
+            }
+        }
+        result.removed.push(relPath);
+        result.entries.push({
+            file,
+            id: lock.id,
+            owner: lock.owner,
+            created_at: lock.created_at,
+            ttl_seconds: lock.ttl_seconds,
+            age_seconds,
+            stale: true,
+            reason: "expired",
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=lock-gc.js.map
+//# debugId=1a412027-5c73-58d4-b696-4a909dde88a8

package/dist/core/lock/lock-gc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-gc.js","sources":["core/lock/lock-gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * lock-gc.ts — Stale lock file garbage collector.\n *\n * Safety-first policy: if a lock file cannot be read or parsed, it is RETAINED\n * rather than deleted. We only remove locks whose staleness can be conclusively\n * determined from the lock's own embedded `ttl_seconds` field.\n *\n * Staleness formula: (now_ms - Date.parse(created_at)) > ttl_seconds * 1000\n * Zero ttl means any lock older than 0 ms is stale. Negative ttl means always stale.\n */\n\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\nexport interface StaleLockScanEntry {\n  /** e.g. \"pm-abc1.lock\" */\n  file: string;\n  /** parsed id, or null if unparseable */\n  id: string | null;\n  owner: string | null;\n  created_at: string | null;\n  ttl_seconds: number | null;\n  /** floor((now - created_at)/1000), null if unparseable */\n  age_seconds: number | null;\n  /** true only when classified expired */\n  stale: boolean;\n  reason: \"expired\" | \"active\" | \"unparseable\";\n}\n\nexport interface LockGcHooks {\n  onRead?: (lockPath: string) => Promise<string[]> | string[];\n  onWrite?: (lockPath: string) => Promise<string[]> | string[];\n}\n\nexport interface LockGcOptions {\n  dryRun: boolean;\n  /** epoch ms; defaults to Date.now() — injectable for deterministic tests */\n  now?: number;\n  hooks?: LockGcHooks;\n}\n\nexport interface LockGcResult {\n  /** number of *.lock files examined */\n  scanned: number;\n  /** relative paths like \"locks/pm-abc1.lock\" (removed, or would-remove under dryRun) */\n  removed: string[];\n  /** relative paths retained (active OR unparseable — never delete what we can't reason about) */\n  retained: string[];\n  warnings: string[];\n  /** one per scanned *.lock file, sorted by file name asc */\n  entries: StaleLockScanEntry[];\n}\n\ninterface ParsedLock {\n  id: string;\n  owner: string;\n  created_at: string;\n  ttl_seconds: number;\n}\n\nfunction parseLock(raw: string): ParsedLock | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw) as unknown;\n  } catch {\n    return null;\n  }\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    return null;\n  }\n  const candidate = parsed as Record<string, unknown>;\n  const { id, owner, created_at, ttl_seconds } = candidate;\n  if (\n    typeof id !== \"string\" ||\n    typeof owner !== \"string\" ||\n    typeof created_at !== \"string\" ||\n    typeof ttl_seconds !== \"number\" ||\n    !Number.isFinite(ttl_seconds)\n  ) {\n    return null;\n  }\n  return { id, owner, created_at, ttl_seconds };\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\nexport async function runLockGc(pmRoot: string, options: LockGcOptions): Promise<LockGcResult> {\n  const { dryRun, hooks } = options;\n  const nowMs = options.now ?? Date.now();\n  const locksDir = path.join(pmRoot, \"locks\");\n\n  const result: LockGcResult = {\n    scanned: 0,\n    removed: [],\n    retained: [],\n    warnings: [],\n    entries: [],\n  };\n\n  let dirEntries: string[];\n  try {\n    const raw = await fs.readdir(locksDir);\n    dirEntries = raw.filter((f) => f.endsWith(\".lock\")).sort();\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return result;\n    }\n    throw error;\n  }\n\n  for (const file of dirEntries) {\n    result.scanned += 1;\n    const absPath = path.join(locksDir, file);\n    const relPath = `locks/${file}`;\n\n    // --- onRead hook ---\n    if (hooks?.onRead) {\n      const hookWarnings = await hooks.onRead(absPath);\n      result.warnings.push(...hookWarnings);\n    }\n\n    // --- read file ---\n    let raw: string;\n    try {\n      raw = await fs.readFile(absPath, \"utf8\");\n    } catch (readError: unknown) {\n      if (isErrno(readError, \"ENOENT\")) {\n        // Disappeared between readdir and readFile — treat as a ghost; skip quietly.\n        result.scanned -= 1;\n        continue;\n      }\n      result.warnings.push(`lock_unreadable:${file}`);\n      result.retained.push(relPath);\n      result.entries.push({\n        file,\n        id: null,\n        owner: null,\n        created_at: null,\n        ttl_seconds: null,\n        age_seconds: null,\n        stale: false,\n        reason: \"unparseable\",\n      });\n      continue;\n    }\n\n    // --- parse ---\n    const lock = parseLock(raw);\n    if (lock === null) {\n      result.warnings.push(`lock_unparseable:${file}`);\n      result.retained.push(relPath);\n      result.entries.push({\n        file,\n        id: null,\n        owner: null,\n        created_at: null,\n        ttl_seconds: null,\n        age_seconds: null,\n        stale: false,\n        reason: \"unparseable\",\n      });\n      continue;\n    }\n\n    // --- validate timestamp ---\n    const createdAtMs = Date.parse(lock.created_at);\n    if (!Number.isFinite(createdAtMs)) {\n      result.warnings.push(`lock_invalid_timestamp:${file}`);\n      result.retained.push(relPath);\n      result.entries.push({\n        file,\n        id: lock.id,\n        owner: lock.owner,\n        created_at: lock.created_at,\n        ttl_seconds: lock.ttl_seconds,\n        age_seconds: null,\n        stale: false,\n        reason: \"unparseable\",\n      });\n      continue;\n    }\n\n    const ageMs = nowMs - createdAtMs;\n    const age_seconds = Math.floor(ageMs / 1000);\n    const stale = ageMs > lock.ttl_seconds * 1000;\n\n    if (!stale) {\n      result.retained.push(relPath);\n      result.entries.push({\n        file,\n        id: lock.id,\n        owner: lock.owner,\n        created_at: lock.created_at,\n        ttl_seconds: lock.ttl_seconds,\n        age_seconds,\n        stale: false,\n        reason: \"active\",\n      });\n      continue;\n    }\n\n    // --- stale: remove or preview ---\n    if (!dryRun) {\n      try {\n        await fs.unlink(absPath);\n      } catch (unlinkError: unknown) {\n        if (!isErrno(unlinkError, \"ENOENT\")) {\n          result.warnings.push(`lock_remove_failed:${file}`);\n          result.retained.push(relPath);\n          result.entries.push({\n            file,\n            id: lock.id,\n            owner: lock.owner,\n            created_at: lock.created_at,\n            ttl_seconds: lock.ttl_seconds,\n            age_seconds,\n            stale: true,\n            reason: \"expired\",\n          });\n          continue;\n        }\n        // ENOENT on unlink = already gone (race); treat as removed\n      }\n      // onWrite hook after successful removal\n      if (hooks?.onWrite) {\n        const hookWarnings = await hooks.onWrite(absPath);\n        result.warnings.push(...hookWarnings);\n      }\n    }\n\n    result.removed.push(relPath);\n    result.entries.push({\n      file,\n      id: lock.id,\n      owner: lock.owner,\n      created_at: lock.created_at,\n      ttl_seconds: lock.ttl_seconds,\n      age_seconds,\n      stale: true,\n      reason: \"expired\",\n    });\n  }\n\n  return result;\n}\n"],"names":[],"mappings":"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","debugId":"1a412027-5c73-58d4-b696-4a909dde88a8"}

package/dist/core/shared/serial-queue.d.ts

@@ -0,0 +1,12 @@
+export interface SerialQueue {
+    /**
+     * Schedule `task` to run after every previously-enqueued task has settled.
+     * Returns a promise for this task's result (or rejection) so callers can
+     * await individual outcomes. A rejected task never wedges the queue: later
+     * tasks still run in order.
+     */
+    enqueue<T>(task: () => Promise<T> | T): Promise<T>;
+    /** Resolves once the queue has fully drained (no pending tasks remain). */
+    idle(): Promise<void>;
+}
+export declare function createSerialQueue(): SerialQueue;