@aperant/framework 0.6.2

package/dist/cost/transcript.d.ts

@@ -0,0 +1,50 @@
+/**
+ * cost/transcript.ts — pure parser for Claude Code JSONL session transcripts (C11).
+ *
+ * Claude Code writes one JSON object per line. Assistant turns carry a
+ * `message.usage` block of the shape:
+ *
+ *   {
+ *     "type": "assistant",
+ *     "session_id": "abc123",                  // optional on some lines
+ *     "message": {
+ *       "model": "claude-opus-4-6",
+ *       "usage": {
+ *         "input_tokens": 1234,
+ *         "output_tokens": 567,
+ *         "cache_read_input_tokens": 0,
+ *         "cache_creation_input_tokens": 0
+ *       }
+ *     },
+ *     "timestamp": "2026-04-15T..."
+ *   }
+ *
+ * `parseClaudeCodeTranscript` aggregates per `session_id` and returns one
+ * partial CostEntry per session. The caller (CLI / CostTracker) is expected
+ * to fill in `taskId`, `costUsd`, `providerId`, and any `--model` overrides
+ * before persisting — keeping this module pricing-agnostic and side-effect
+ * free (single readFileSync) so it can be exercised by fixture tests with
+ * zero environmental noise.
+ *
+ * Robustness contract:
+ *   - Missing file → `[]` (caller decides whether to fail).
+ *   - Malformed line → silently skipped (transcripts can be tail-truncated).
+ *   - Lines without `message.usage` → ignored (user/system turns).
+ *   - Sessions without a `session_id` are bucketed under the sentinel
+ *     `"unknown-session"` so they still surface in the aggregate.
+ */
+import type { CostEntry } from './types.js';
+/**
+ * A partial CostEntry as emitted by the transcript parser. `taskId`,
+ * `costUsd`, and `providerId` are filled in by the caller (the `tokens`
+ * command knows the task context; pricing is applied via `calculateCost`).
+ */
+export type ParsedTranscriptEntry = Omit<CostEntry, 'taskId' | 'costUsd' | 'providerId'>;
+/**
+ * Parse a Claude Code JSONL transcript file and aggregate token usage per
+ * session_id. Returns one `ParsedTranscriptEntry` per session.
+ *
+ * Pure: only reads `path` once via readFileSync; no env reads, no cwd.
+ */
+export declare function parseClaudeCodeTranscript(path: string): ParsedTranscriptEntry[];
+//# sourceMappingURL=transcript.d.ts.map

package/dist/cost/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/cost/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC,CAAA;AA4BxF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA6E/E"}

package/dist/cost/transcript.js

@@ -0,0 +1,147 @@
+/**
+ * cost/transcript.ts — pure parser for Claude Code JSONL session transcripts (C11).
+ *
+ * Claude Code writes one JSON object per line. Assistant turns carry a
+ * `message.usage` block of the shape:
+ *
+ *   {
+ *     "type": "assistant",
+ *     "session_id": "abc123",                  // optional on some lines
+ *     "message": {
+ *       "model": "claude-opus-4-6",
+ *       "usage": {
+ *         "input_tokens": 1234,
+ *         "output_tokens": 567,
+ *         "cache_read_input_tokens": 0,
+ *         "cache_creation_input_tokens": 0
+ *       }
+ *     },
+ *     "timestamp": "2026-04-15T..."
+ *   }
+ *
+ * `parseClaudeCodeTranscript` aggregates per `session_id` and returns one
+ * partial CostEntry per session. The caller (CLI / CostTracker) is expected
+ * to fill in `taskId`, `costUsd`, `providerId`, and any `--model` overrides
+ * before persisting — keeping this module pricing-agnostic and side-effect
+ * free (single readFileSync) so it can be exercised by fixture tests with
+ * zero environmental noise.
+ *
+ * Robustness contract:
+ *   - Missing file → `[]` (caller decides whether to fail).
+ *   - Malformed line → silently skipped (transcripts can be tail-truncated).
+ *   - Lines without `message.usage` → ignored (user/system turns).
+ *   - Sessions without a `session_id` are bucketed under the sentinel
+ *     `"unknown-session"` so they still surface in the aggregate.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+function newAccumulator(sessionId, modelId) {
+    return {
+        sessionId,
+        modelId,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        thinkingTokens: 0,
+        firstTimestamp: null,
+        lastTimestamp: null,
+    };
+}
+/**
+ * Parse a Claude Code JSONL transcript file and aggregate token usage per
+ * session_id. Returns one `ParsedTranscriptEntry` per session.
+ *
+ * Pure: only reads `path` once via readFileSync; no env reads, no cwd.
+ */
+export function parseClaudeCodeTranscript(path) {
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const sessions = new Map();
+    for (const line of raw.split('\n')) {
+        if (!line)
+            continue;
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!evt || typeof evt !== 'object')
+            continue;
+        const obj = evt;
+        if (obj.type !== 'assistant')
+            continue;
+        const message = obj.message;
+        if (!message || typeof message !== 'object')
+            continue;
+        const usage = message.usage;
+        if (!usage || typeof usage !== 'object')
+            continue;
+        const sessionId = (typeof obj.session_id === 'string' && obj.session_id) ||
+            (typeof obj.sessionId === 'string' && obj.sessionId) ||
+            'unknown-session';
+        const modelId = (typeof message.model === 'string' && message.model) || 'unknown-model';
+        const timestamp = (typeof obj.timestamp === 'string' && obj.timestamp) ||
+            (typeof obj.t === 'string' && obj.t) ||
+            null;
+        const acc = sessions.get(sessionId) ?? newAccumulator(sessionId, modelId);
+        // Last-seen model wins (sessions rarely switch models mid-flight, but if
+        // they do the most recent is the most representative for pricing).
+        acc.modelId = modelId;
+        acc.inputTokens += toNumber(usage.input_tokens);
+        acc.outputTokens += toNumber(usage.output_tokens);
+        acc.cacheReadTokens += toNumber(usage.cache_read_input_tokens);
+        acc.cacheCreationTokens += toNumber(usage.cache_creation_input_tokens);
+        // Some transcripts include extended-thinking tokens under
+        // `output_tokens_details.thinking_tokens` or top-level; tolerate both.
+        const details = usage.output_tokens_details;
+        acc.thinkingTokens +=
+            toNumber(usage.thinking_tokens) +
+                (details && typeof details === 'object' ? toNumber(details.thinking_tokens) : 0);
+        if (timestamp) {
+            if (!acc.firstTimestamp)
+                acc.firstTimestamp = timestamp;
+            acc.lastTimestamp = timestamp;
+        }
+        sessions.set(sessionId, acc);
+    }
+    const out = [];
+    for (const acc of sessions.values()) {
+        const ts = acc.firstTimestamp ?? acc.lastTimestamp ?? new Date(0).toISOString();
+        out.push({
+            sessionId: acc.sessionId,
+            modelId: acc.modelId,
+            inputTokens: acc.inputTokens,
+            outputTokens: acc.outputTokens,
+            cacheReadTokens: acc.cacheReadTokens,
+            cacheCreationTokens: acc.cacheCreationTokens,
+            thinkingTokens: acc.thinkingTokens,
+            timestamp: ts,
+            durationMs: durationBetween(acc.firstTimestamp, acc.lastTimestamp),
+        });
+    }
+    return out;
+}
+function toNumber(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    return 0;
+}
+function durationBetween(first, last) {
+    if (!first || !last)
+        return 0;
+    const a = Date.parse(first);
+    const b = Date.parse(last);
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return 0;
+    return Math.max(0, b - a);
+}
+//# sourceMappingURL=transcript.js.map

package/dist/cost/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/cost/transcript.ts"],"names":[],"mappings":"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"}

package/dist/cost/transcript.mjs

@@ -0,0 +1,119 @@
+/**
+ * cost/transcript.mjs — runtime-callable Claude Code transcript parser (C11).
+ *
+ * Mirror of cost/transcript.ts kept in .mjs so the CLI dispatcher (uncompiled
+ * .mjs runtime) can import without a TypeScript build step. The TS file is
+ * the type-checked source of truth for library consumers; this file is the
+ * source of truth for the CLI runtime. Algorithms are byte-for-byte identical
+ * so the transcript.test.ts coverage (against the .ts file) doubles as a
+ * regression net for this one — any divergence shows up as either:
+ *   (a) the unit suite passing while CLI integration tests fail, or
+ *   (b) a fixture-aggregation mismatch in tokens-record.test.ts.
+ *
+ * See transcript.ts for the full design notes.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+function toNumber(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    return 0;
+}
+function durationBetween(first, last) {
+    if (!first || !last)
+        return 0;
+    const a = Date.parse(first);
+    const b = Date.parse(last);
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return 0;
+    return Math.max(0, b - a);
+}
+function newAccumulator(sessionId, modelId) {
+    return {
+        sessionId,
+        modelId,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        thinkingTokens: 0,
+        firstTimestamp: null,
+        lastTimestamp: null,
+    };
+}
+/**
+ * Parse a Claude Code JSONL transcript file. Returns one entry per session.
+ * Pure: only reads `path` once via readFileSync; no env reads, no cwd.
+ */
+export function parseClaudeCodeTranscript(path) {
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const sessions = new Map();
+    for (const line of raw.split('\n')) {
+        if (!line)
+            continue;
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!evt || typeof evt !== 'object')
+            continue;
+        if (evt.type !== 'assistant')
+            continue;
+        const message = evt.message;
+        if (!message || typeof message !== 'object')
+            continue;
+        const usage = message.usage;
+        if (!usage || typeof usage !== 'object')
+            continue;
+        const sessionId = (typeof evt.session_id === 'string' && evt.session_id) ||
+            (typeof evt.sessionId === 'string' && evt.sessionId) ||
+            'unknown-session';
+        const modelId = (typeof message.model === 'string' && message.model) || 'unknown-model';
+        const timestamp = (typeof evt.timestamp === 'string' && evt.timestamp) ||
+            (typeof evt.t === 'string' && evt.t) ||
+            null;
+        const acc = sessions.get(sessionId) ?? newAccumulator(sessionId, modelId);
+        acc.modelId = modelId;
+        acc.inputTokens += toNumber(usage.input_tokens);
+        acc.outputTokens += toNumber(usage.output_tokens);
+        acc.cacheReadTokens += toNumber(usage.cache_read_input_tokens);
+        acc.cacheCreationTokens += toNumber(usage.cache_creation_input_tokens);
+        const details = usage.output_tokens_details;
+        acc.thinkingTokens +=
+            toNumber(usage.thinking_tokens) +
+                (details && typeof details === 'object' ? toNumber(details.thinking_tokens) : 0);
+        if (timestamp) {
+            if (!acc.firstTimestamp)
+                acc.firstTimestamp = timestamp;
+            acc.lastTimestamp = timestamp;
+        }
+        sessions.set(sessionId, acc);
+    }
+    const out = [];
+    for (const acc of sessions.values()) {
+        const ts = acc.firstTimestamp ?? acc.lastTimestamp ?? new Date(0).toISOString();
+        out.push({
+            sessionId: acc.sessionId,
+            modelId: acc.modelId,
+            inputTokens: acc.inputTokens,
+            outputTokens: acc.outputTokens,
+            cacheReadTokens: acc.cacheReadTokens,
+            cacheCreationTokens: acc.cacheCreationTokens,
+            thinkingTokens: acc.thinkingTokens,
+            timestamp: ts,
+            durationMs: durationBetween(acc.firstTimestamp, acc.lastTimestamp),
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=transcript.mjs.map

package/dist/cost/transcript.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.mjs","sourceRoot":"","sources":["../../src/cost/transcript.mjs"],"names":[],"mappings":"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"}

package/dist/cost/types.d.ts

@@ -0,0 +1,50 @@
+/** A single cost entry for one session within a task */
+export interface CostEntry {
+    taskId: string;
+    sessionId: string;
+    providerId: string;
+    modelId: string;
+    inputTokens: number;
+    outputTokens: number;
+    thinkingTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    costUsd: number;
+    timestamp: string;
+    durationMs: number;
+}
+/** Aggregated cost summary for all sessions within a task */
+export interface TaskCostSummary {
+    taskId: string;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalThinkingTokens: number;
+    sessionCount: number;
+    totalDurationMs: number;
+    entries: CostEntry[];
+    costPerSession: number;
+}
+/** Provider-level cost comparison for a single task */
+export interface ProviderCostComparison {
+    taskId: string;
+    byProvider: Array<{
+        providerId: string;
+        modelId: string;
+        totalCostUsd: number;
+        totalTokens: number;
+        sessionCount: number;
+    }>;
+}
+/** Cost trend data over a time period */
+export interface CostTrend {
+    dataPoints: Array<{
+        date: string;
+        taskCount: number;
+        totalCostUsd: number;
+        avgCostPerTask: number;
+        tokenTotal: number;
+    }>;
+    periodDays: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cost/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cost/types.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;CACtB;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,KAAK,CAAC;QACjB,UAAU,EAAE,MAAM,CAAA;QAClB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;QACpB,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;KACpB,CAAC,CAAA;CACF;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,YAAY,EAAE,MAAM,CAAA;QACpB,cAAc,EAAE,MAAM,CAAA;QACtB,UAAU,EAAE,MAAM,CAAA;KAClB,CAAC,CAAA;IACF,UAAU,EAAE,MAAM,CAAA;CAClB"}

package/dist/cost/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cost/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cost/types.ts"],"names":[],"mappings":""}

package/dist/helpers/cycle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * detectCycle — Pre-mortem #5 mitigation.
+ *
+ * Given a task graph keyed by `depends_on` edges, determines whether
+ * adding a proposed edge `newEdge.from → newEdge.to` would create a cycle.
+ * Returns the cycle path (as an array of task ids starting at the re-visited
+ * node) or `null` when the graph remains acyclic.
+ *
+ * The graph is read-only. `tasks` maps id → depends_on[] (after parsing).
+ */
+export interface CycleEdge {
+    from: string;
+    to: string;
+}
+/**
+ * Return the first cycle path that would exist if `newEdge` were added,
+ * or `null` if adding the edge keeps the graph acyclic.
+ */
+export declare function detectCycle(dependsOnByTaskId: Map<string, string[]>, newEdge: CycleEdge): string[] | null;
+/**
+ * Return the transitive set of task ids that depend (directly or indirectly)
+ * on `targetId`. Used by `task list --blocked-by`.
+ */
+export declare function collectBlockedBy(dependsOnByTaskId: Map<string, string[]>, targetId: string): string[];
+//# sourceMappingURL=cycle.d.ts.map

package/dist/helpers/cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle.d.ts","sourceRoot":"","sources":["../../src/helpers/cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACV;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACxC,OAAO,EAAE,SAAS,GAChB,MAAM,EAAE,GAAG,IAAI,CA6BjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACxC,QAAQ,EAAE,MAAM,GACd,MAAM,EAAE,CAuBV"}

package/dist/helpers/cycle.js

@@ -0,0 +1,75 @@
+/**
+ * detectCycle — Pre-mortem #5 mitigation.
+ *
+ * Given a task graph keyed by `depends_on` edges, determines whether
+ * adding a proposed edge `newEdge.from → newEdge.to` would create a cycle.
+ * Returns the cycle path (as an array of task ids starting at the re-visited
+ * node) or `null` when the graph remains acyclic.
+ *
+ * The graph is read-only. `tasks` maps id → depends_on[] (after parsing).
+ */
+/**
+ * Return the first cycle path that would exist if `newEdge` were added,
+ * or `null` if adding the edge keeps the graph acyclic.
+ */
+export function detectCycle(dependsOnByTaskId, newEdge) {
+    // Build a working adjacency map that includes the hypothetical edge.
+    const adj = new Map();
+    for (const [id, deps] of dependsOnByTaskId.entries()) {
+        adj.set(id, [...deps]);
+    }
+    const existing = adj.get(newEdge.from) ?? [];
+    if (!existing.includes(newEdge.to)) {
+        adj.set(newEdge.from, [...existing, newEdge.to]);
+    }
+    // DFS from `newEdge.to` — if we can reach `newEdge.from`, the hypothetical
+    // edge closes a cycle.
+    const stack = [{ node: newEdge.to, path: [newEdge.to] }];
+    const visited = new Set();
+    while (stack.length > 0) {
+        const { node, path } = stack.pop();
+        if (node === newEdge.from) {
+            // Found back to origin → close the loop for readability.
+            return [...path, newEdge.from];
+        }
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        const nexts = adj.get(node) ?? [];
+        for (const next of nexts) {
+            stack.push({ node: next, path: [...path, next] });
+        }
+    }
+    return null;
+}
+/**
+ * Return the transitive set of task ids that depend (directly or indirectly)
+ * on `targetId`. Used by `task list --blocked-by`.
+ */
+export function collectBlockedBy(dependsOnByTaskId, targetId) {
+    // Build reverse adjacency: edge `A depends_on B` means A is blocked by B.
+    const reverse = new Map();
+    for (const [id, deps] of dependsOnByTaskId.entries()) {
+        for (const dep of deps) {
+            const arr = reverse.get(dep) ?? [];
+            arr.push(id);
+            reverse.set(dep, arr);
+        }
+    }
+    const visited = new Set();
+    const out = [];
+    const queue = [...(reverse.get(targetId) ?? [])];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        out.push(current);
+        for (const next of reverse.get(current) ?? []) {
+            if (!visited.has(next))
+                queue.push(next);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=cycle.js.map

package/dist/helpers/cycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle.js","sourceRoot":"","sources":["../../src/helpers/cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,MAAM,UAAU,WAAW,CAC1B,iBAAwC,EACxC,OAAkB;IAElB,qEAAqE;IACrE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAA;IACvC,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,EAAE,CAAC;QACtD,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAA;IACvB,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAC5C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACpC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAA;IACjD,CAAC;IAED,2EAA2E;IAC3E,uBAAuB;IACvB,MAAM,KAAK,GAA4C,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACjG,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACnC,IAAI,IAAI,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;YAC3B,yDAAyD;YACzD,OAAO,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;QAC/B,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACjB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;QAClD,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC/B,iBAAwC,EACxC,QAAgB;IAEhB,0EAA0E;IAC1E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAA;IAC3C,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,EAAE,CAAC;QACtD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAA;YAClC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACZ,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QACtB,CAAC;IACF,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,MAAM,KAAK,GAAa,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IAC1D,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAG,CAAA;QAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAQ;QAClC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACpB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACjB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACzC,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,7 @@
+export type { CycleEdge } from './cycle';
+export { collectBlockedBy, detectCycle } from './cycle';
+export type { WithLockOptions } from './lock';
+export { LockTimeoutError, withLock } from './lock';
+export type { ResolvedTaskRef } from './task-ref';
+export { formatTaskRef, resolveTaskRef } from './task-ref';
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACvD,YAAY,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACnD,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/helpers/index.js

@@ -0,0 +1,4 @@
+export { collectBlockedBy, detectCycle } from './cycle';
+export { LockTimeoutError, withLock } from './lock';
+export { formatTaskRef, resolveTaskRef } from './task-ref';
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEnD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/helpers/lock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Lock helper — thin wrapper around `proper-lockfile` providing a
+ * single `withLock(filePath, fn)` entry point used by every shared-state
+ * write in the framework.
+ *
+ * Guarantees:
+ * - Mutual exclusion across processes, including across git worktrees that
+ *   share the same `.aperant/` directory (lock is taken on the target
+ *   file path itself).
+ * - Stale-lock recovery via `proper-lockfile`'s `stale` option (default 5s).
+ * - Structured timeout error emitted to `.aperant/events/` so Pre-mortem #1
+ *   monitoring can catch sustained contention.
+ *
+ * Callers pass the path to the shared JSON/Markdown file (NOT a `.lock`
+ * sidecar). `proper-lockfile` manages the sidecar internally.
+ */
+export interface WithLockOptions {
+    /** Milliseconds before the lock is considered stale. Default 5000. */
+    stale?: number;
+    /** Total retry attempts when the lock is held. Default 20. */
+    retries?: number;
+    /** Base delay between retries in ms. Default 50. */
+    retryDelayMs?: number;
+    /** Maximum retry delay in ms. Default 500. */
+    maxRetryDelayMs?: number;
+    /**
+     * Project root (optional). If provided and the lock times out, a
+     * structured event is written to `{projectRoot}/.aperant/events/`.
+     */
+    projectRoot?: string;
+    /** Override the realpath requirement (for paths that may not exist yet). */
+    realpath?: boolean;
+}
+/**
+ * Acquire an exclusive lock on `filePath`, run `fn`, then release.
+ *
+ * The target file does not need to exist — `proper-lockfile` is configured
+ * with `realpath: false` by default so we can lock paths the caller is
+ * about to create. `fn` is awaited if it returns a promise.
+ */
+export declare function withLock<T>(filePath: string, fn: () => T | Promise<T>, options?: WithLockOptions): Promise<T>;
+export declare class LockTimeoutError extends Error {
+    readonly code = "E_LOCK_TIMEOUT";
+    readonly target: string;
+    readonly cause: Error;
+    constructor(target: string, cause: Error);
+}
+//# sourceMappingURL=lock.d.ts.map

package/dist/helpers/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/helpers/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,eAAe;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAiDZ;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,oBAAmB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;gBACT,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAMxC"}