taskflow-core 0.1.0

package/dist/agents.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Agent discovery and configuration.
+ * Adapted from the pi subagent extension so taskflow shares the same agent
+ * pool (~/.pi/agent/agents/*.md, .pi/agents/*.md) and settings overrides.
+ */
+export type AgentScope = "user" | "project" | "both";
+export interface TaskflowSettings {
+    /** Whether taskflow's package-local built-in agents are available to flows. */
+    builtInAgents: boolean;
+    /** Whether package-local built-ins are copied into the current project's .pi/agents/. */
+    syncBuiltinAgentsToProject: boolean;
+    /** Maximum completed/failed runs to keep. 0 disables cleanup. */
+    maxKeptRuns: number;
+    /** Maximum age (days) for completed/failed runs. 0 disables age cleanup. */
+    maxRunAgeDays: number;
+}
+export declare const DEFAULT_TASKFLOW_SETTINGS: TaskflowSettings;
+export declare function normalizeTaskflowSettings(raw: unknown): TaskflowSettings;
+export declare function shouldLoadBuiltinAgents(settings?: TaskflowSettings): boolean;
+export declare function shouldSyncBuiltinAgentsToProject(settings?: TaskflowSettings): boolean;
+export interface AgentConfig {
+    name: string;
+    description: string;
+    tools?: string[];
+    model?: string;
+    thinking?: string;
+    systemPrompt: string;
+    source: "user" | "project" | "built-in";
+    filePath: string;
+}
+/** @internal */
+export interface AgentDiscoveryResult {
+    agents: AgentConfig[];
+    projectAgentsDir: string | null;
+}
+export declare function discoverAgents(cwd: string, scope: AgentScope, modelRoles?: Record<string, string>, taskflowSettings?: TaskflowSettings): AgentDiscoveryResult;
+export interface SubagentSettings {
+    globalThinking?: string;
+    modelRoles?: Record<string, string>;
+    taskflow: TaskflowSettings;
+}
+/** Read subagent overrides from ~/.pi/agent/settings.json (shared with the subagent extension). */
+export declare function readSubagentSettings(): SubagentSettings;
+/**
+ * Copy the 18 built-in agents from extensions/agents/*.md into the project's
+ * .pi/agents/ directory so Pi's native subagent tool (and any other extension)
+ * can discover them. taskflow's own discoverAgents() already reads from this
+ * directory with lower priority than built-in, so the copy is a no-op for
+ * taskflow phases — it only matters for Pi's native agent discovery.
+ *
+ * Idempotent: only copies agents whose built-in source is newer than the
+ * project copy (or that don't exist yet).
+ */
+export declare function syncBuiltinAgentsToProject(cwd: string): void;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAChC,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;IACvB,yFAAyF;IACzF,0BAA0B,EAAE,OAAO,CAAC;IACpC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;CACtB;AAID,eAAO,MAAM,yBAAyB,EAAE,gBAKvC,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAuBxE;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,GAAE,gBAA4C,GAAG,OAAO,CAEvG;AAED,wBAAgB,gCAAgC,CAAC,QAAQ,GAAE,gBAA4C,GAAG,OAAO,CAEhH;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAyFD,wBAAgB,cAAc,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,gBAAgB,GAAE,gBAA4C,GAC5D,oBAAoB,CAwCtB;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;CAC3B;AAoBD,mGAAmG;AACnG,wBAAgB,oBAAoB,IAAI,gBAAgB,CAavD;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAmC5D"}

package/dist/agents.js

@@ -0,0 +1,265 @@
+/**
+ * Agent discovery and configuration.
+ * Adapted from the pi subagent extension so taskflow shares the same agent
+ * pool (~/.pi/agent/agents/*.md, .pi/agents/*.md) and settings overrides.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "./paths.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import { DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS, writeFileAtomic } from "./store.js";
+export const DEFAULT_TASKFLOW_SETTINGS = {
+    builtInAgents: true,
+    syncBuiltinAgentsToProject: false,
+    maxKeptRuns: DEFAULT_KEPT_RUNS,
+    maxRunAgeDays: DEFAULT_RUN_AGE_DAYS,
+};
+export function normalizeTaskflowSettings(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { ...DEFAULT_TASKFLOW_SETTINGS };
+    }
+    const rec = raw;
+    return {
+        builtInAgents: typeof rec.builtInAgents === "boolean"
+            ? rec.builtInAgents
+            : DEFAULT_TASKFLOW_SETTINGS.builtInAgents,
+        syncBuiltinAgentsToProject: typeof rec.syncBuiltinAgentsToProject === "boolean"
+            ? rec.syncBuiltinAgentsToProject
+            : DEFAULT_TASKFLOW_SETTINGS.syncBuiltinAgentsToProject,
+        maxKeptRuns: typeof rec.maxKeptRuns === "number" && rec.maxKeptRuns >= 0 && Number.isInteger(rec.maxKeptRuns)
+            ? rec.maxKeptRuns
+            : DEFAULT_TASKFLOW_SETTINGS.maxKeptRuns,
+        maxRunAgeDays: typeof rec.maxRunAgeDays === "number" && rec.maxRunAgeDays >= 0 && Number.isInteger(rec.maxRunAgeDays)
+            ? rec.maxRunAgeDays
+            : DEFAULT_TASKFLOW_SETTINGS.maxRunAgeDays,
+    };
+}
+export function shouldLoadBuiltinAgents(settings = DEFAULT_TASKFLOW_SETTINGS) {
+    return settings.builtInAgents;
+}
+export function shouldSyncBuiltinAgentsToProject(settings = DEFAULT_TASKFLOW_SETTINGS) {
+    return settings.builtInAgents && settings.syncBuiltinAgentsToProject;
+}
+function loadAgentsFromDir(dir, source) {
+    const agents = [];
+    if (!fs.existsSync(dir))
+        return agents;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return agents;
+    }
+    for (const entry of entries) {
+        try {
+            if (!entry.name.endsWith(".md"))
+                continue;
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            const filePath = path.join(dir, entry.name);
+            let content;
+            try {
+                content = fs.readFileSync(filePath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const { frontmatter, body } = (() => {
+                try {
+                    return parseFrontmatter(content);
+                }
+                catch {
+                    // A single malformed agent file must not break discovery for every flow.
+                    return { frontmatter: {}, body: "" };
+                }
+            })();
+            if (!frontmatter.name || !frontmatter.description)
+                continue;
+            // frontmatter is YAML-parsed: tools may be a comma-separated string ("a, b")
+            // OR a YAML sequence ([a, b]). Handle both forms; reject other types to
+            // prevent garbage output from malformed YAML (e.g. boolean, number).
+            const rawTools = frontmatter.tools;
+            let tools;
+            if (Array.isArray(rawTools)) {
+                tools = rawTools.map((t) => String(t).trim()).filter(Boolean);
+            }
+            else if (typeof rawTools === "string") {
+                tools = rawTools.split(",").map((t) => t.trim()).filter(Boolean);
+            }
+            else if (rawTools !== undefined && rawTools !== null) {
+                console.warn(`[taskflow] Agent '${String(frontmatter.name)}': 'tools' must be a string or array, got ${typeof rawTools}. Ignoring.`);
+                tools = undefined;
+            }
+            agents.push({
+                name: String(frontmatter.name),
+                description: String(frontmatter.description),
+                tools: tools && tools.length > 0 ? tools : undefined,
+                model: frontmatter.model === undefined ? undefined : String(frontmatter.model),
+                thinking: frontmatter.thinking === undefined ? undefined : String(frontmatter.thinking),
+                systemPrompt: body,
+                source,
+                filePath,
+            });
+        }
+        catch {
+            // Defense-in-depth: a single bad agent file must not break discovery
+            // for the entire flow (e.g. exotic YAML shapes, runtime errors in
+            // field access, symlink races, etc.).
+            continue;
+        }
+    }
+    return agents;
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function findNearestProjectAgentsDir(cwd) {
+    let currentDir = cwd;
+    while (true) {
+        const candidate = path.join(currentDir, ".pi", "agents");
+        if (isDirectory(candidate))
+            return candidate;
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            return null;
+        currentDir = parentDir;
+    }
+}
+export function discoverAgents(cwd, scope, modelRoles, taskflowSettings = DEFAULT_TASKFLOW_SETTINGS) {
+    // Built-in agents ship with the package (extensions/agents/*.md).
+    // PI_TASKFLOW_BUILTIN_AGENTS_DIR is kept as a test hook only; user-facing
+    // enable/disable lives in settings.json under `taskflow.builtInAgents`.
+    const builtInDirEnv = process.env.PI_TASKFLOW_BUILTIN_AGENTS_DIR;
+    const builtInDir = builtInDirEnv ? builtInDirEnv : builtInDirEnv === undefined ? path.resolve(import.meta.dirname, "agents") : "";
+    const builtInAgents = shouldLoadBuiltinAgents(taskflowSettings) && builtInDir ? loadAgentsFromDir(builtInDir, "built-in") : [];
+    const userDir = path.join(getAgentDir(), "agents");
+    const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+    const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+    const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+    // Layer order: built-in → user → project (later layers override earlier)
+    const agentMap = new Map();
+    for (const a of builtInAgents)
+        agentMap.set(a.name, a);
+    if (scope === "both") {
+        for (const a of userAgents)
+            agentMap.set(a.name, a);
+        for (const a of projectAgents)
+            agentMap.set(a.name, a);
+    }
+    else if (scope === "user") {
+        for (const a of userAgents)
+            agentMap.set(a.name, a);
+    }
+    else {
+        for (const a of projectAgents)
+            agentMap.set(a.name, a);
+    }
+    // Resolve {{role}} model references (e.g. {{fast}} → openrouter/deepseek/v4-flash)
+    // Clone before mutating, consistent with the overrides block above.
+    if (modelRoles) {
+        for (const [name, agent] of agentMap.entries()) {
+            const resolved = resolveModelRole(agent.model, modelRoles);
+            if (resolved !== agent.model) {
+                const mutated = { ...agent };
+                mutated.model = resolved;
+                agentMap.set(name, mutated);
+            }
+        }
+    }
+    return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+/**
+ * Resolve `{{roleName}}` model references against a role→model mapping.
+ * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
+ * Returns undefined if the value is not a role reference or the role is unmapped.
+ */
+/**
+ * Resolve `{{roleName}}` model references against a role→model mapping.
+ * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
+ * Returns undefined if the value is not a role reference or the role is unmapped.
+ * @internal
+ */
+function resolveModelRole(model, roles) {
+    if (!model || !roles)
+        return model;
+    const match = model.match(/^\{\{(\w+)\}\}$/);
+    if (!match)
+        return model;
+    return roles[match[1]] ?? undefined;
+}
+/** Read subagent overrides from ~/.pi/agent/settings.json (shared with the subagent extension). */
+export function readSubagentSettings() {
+    try {
+        const settingsPath = path.join(getAgentDir(), "settings.json");
+        if (!fs.existsSync(settingsPath))
+            return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
+        const raw = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        return {
+            globalThinking: raw.subagents?.globalThinking ?? raw.defaultThinkingLevel,
+            modelRoles: raw.modelRoles,
+            taskflow: normalizeTaskflowSettings(raw.taskflow),
+        };
+    }
+    catch {
+        return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
+    }
+}
+/**
+ * Copy the 18 built-in agents from extensions/agents/*.md into the project's
+ * .pi/agents/ directory so Pi's native subagent tool (and any other extension)
+ * can discover them. taskflow's own discoverAgents() already reads from this
+ * directory with lower priority than built-in, so the copy is a no-op for
+ * taskflow phases — it only matters for Pi's native agent discovery.
+ *
+ * Idempotent: only copies agents whose built-in source is newer than the
+ * project copy (or that don't exist yet).
+ */
+export function syncBuiltinAgentsToProject(cwd) {
+    const builtInDir = path.resolve(import.meta.dirname, "agents");
+    if (!fs.existsSync(builtInDir))
+        return;
+    const projectAgentsDir = path.join(cwd, ".pi", "agents");
+    fs.mkdirSync(projectAgentsDir, { recursive: true });
+    let entries;
+    try {
+        entries = fs.readdirSync(builtInDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const src = path.join(builtInDir, entry.name);
+        const dst = path.join(projectAgentsDir, entry.name);
+        let srcMtime = 0;
+        try {
+            srcMtime = fs.statSync(src).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        let dstMtime = 0;
+        try {
+            dstMtime = fs.statSync(dst).mtimeMs;
+        }
+        catch { /* dst doesn't exist yet */ }
+        // Only copy when the source is newer (or the destination is missing).
+        if (srcMtime <= dstMtime)
+            continue;
+        try {
+            const content = fs.readFileSync(src, "utf-8");
+            writeFileAtomic(dst, content);
+        }
+        catch {
+            // Best-effort: a locked file must not block the sync.
+        }
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

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

package/dist/cache.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cross-run memoization: fingerprint resolver + persistent phase-result cache.
+ *
+ * See docs/rfc-cross-run-memoization.md. The cache lets a phase reuse the result
+ * of an identical-input phase from ANY prior run (scope: "cross-run"), for $0.00.
+ * Freshness is guarded by:
+ *   - the existing content-addressed inputHash (declared inputs)
+ *   - optional `fingerprint` entries folded into the key (git/glob/file/env)
+ *   - optional TTL
+ *   - default `run-only` scope (this module is only consulted for cross-run)
+ *
+ * Zero runtime dependencies: Node built-ins only (fs.globSync requires Node >=22,
+ * which the project already targets).
+ */
+import { type PhaseState } from "./store.ts";
+/**
+ * Resolve a phase's `fingerprint` list into a single deterministic string to be
+ * folded into the cache key. Returns "" when there are no entries (so the key is
+ * unchanged for phases that declare no fingerprint).
+ */
+export declare function resolveFingerprint(entries: string[] | undefined, cwd: string): string;
+/** @internal */
+export interface CacheEntry {
+    /** The full cache key (== phase inputHash incl. fingerprint). */
+    key: string;
+    createdAt: number;
+    /** Trimmed phase result surface that downstream phases consume. */
+    output?: string;
+    json?: unknown;
+    model?: string;
+    /** Full PhaseState payload preserved so cross-run reuse is semantically
+     *  equivalent to within-run resume. Storing only output/json would drop
+     *  `gate`, `approval`, `reads`, `loop`, `tournament`, `warnings`, etc.,
+     *  breaking recompute soundness and gate-block detection. */
+    state?: PhaseState;
+    /** Provenance for audit / cleanup. */
+    flowName?: string;
+    phaseId?: string;
+    runId?: string;
+}
+/**
+ * The cross-run cache, scoped to a working directory. Cheap to construct; all IO
+ * is lazy and failure-tolerant (a broken cache must never break a run).
+ */
+export declare class CacheStore {
+    private dir;
+    constructor(cwd: string);
+    /** Look up a fresh entry. Returns null on miss, malformed key, or TTL expiry. */
+    get(key: string, ttlMs?: number): CacheEntry | null;
+    /** Store an entry (best-effort; never throws into the run). */
+    put(entry: CacheEntry): void;
+    /** Remove all cache entries. Returns the number removed. */
+    clear(): number;
+    /** Opportunistic eviction: drop expired/oversized entries. Best-effort. */
+    private cleanup;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAsGlF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrF;AAMD,gBAAgB;AAChB,MAAM,WAAW,UAAU;IAC1B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;iEAG6D;IAC7D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAgBD;;;GAGG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,GAAG,CAAS;gBAER,GAAG,EAAE,MAAM;IAIvB,iFAAiF;IACjF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAgBnD,+DAA+D;IAC/D,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAc5B,4DAA4D;IAC5D,KAAK,IAAI,MAAM;IAmBf,2EAA2E;IAC3E,OAAO,CAAC,OAAO;CAqCf"}

package/dist/cache.js

@@ -0,0 +1,256 @@
+/**
+ * Cross-run memoization: fingerprint resolver + persistent phase-result cache.
+ *
+ * See docs/rfc-cross-run-memoization.md. The cache lets a phase reuse the result
+ * of an identical-input phase from ANY prior run (scope: "cross-run"), for $0.00.
+ * Freshness is guarded by:
+ *   - the existing content-addressed inputHash (declared inputs)
+ *   - optional `fingerprint` entries folded into the key (git/glob/file/env)
+ *   - optional TTL
+ *   - default `run-only` scope (this module is only consulted for cross-run)
+ *
+ * Zero runtime dependencies: Node built-ins only (fs.globSync requires Node >=22,
+ * which the project already targets).
+ */
+import { execFileSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { cacheDir, withLock, writeFileAtomic } from "./store.js";
+// ---------------------------------------------------------------------------
+// Fingerprint resolution
+// ---------------------------------------------------------------------------
+/** Per-file byte cap when content-hashing (mirrors store/context limits). */
+const FINGERPRINT_MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
+/** Cap on glob match count folded into a single fingerprint (defensive). */
+const FINGERPRINT_MAX_GLOB_MATCHES = 5000;
+/**
+ * Resolve a single fingerprint entry to a deterministic string. Never throws:
+ * missing files / non-git repos / unreadable paths resolve to a stable sentinel
+ * so the key stays deterministic (and a later appearance of the resource simply
+ * changes the key → cache miss, which is the safe direction).
+ */
+function resolveOne(entry, cwd) {
+    try {
+        if (entry === "git:HEAD" || entry.startsWith("git:")) {
+            const ref = entry.slice("git:".length) || "HEAD";
+            // Reject refs that could be interpreted as git options (e.g. "--exec=...").
+            // The ref comes from a taskflow definition; refuse flag-like values so a
+            // crafted definition can't smuggle arguments into git.
+            if (ref.startsWith("-"))
+                return `git:${ref}=<invalid-ref>`;
+            try {
+                const sha = execFileSync("git", ["rev-parse", ref], {
+                    cwd,
+                    encoding: "utf-8",
+                    stdio: ["ignore", "pipe", "ignore"],
+                    timeout: 30_000,
+                }).trim();
+                return `git:${ref}=${sha}`;
+            }
+            catch (e) {
+                if (e.code === "ETIMEDOUT") {
+                    return `git:${ref}=<timeout>`;
+                }
+                return `git:${ref}=<no-git>`;
+            }
+        }
+        if (entry.startsWith("glob:") || entry.startsWith("glob!:")) {
+            const contentMode = entry.startsWith("glob!:");
+            const pattern = entry.slice(contentMode ? "glob!:".length : "glob:".length);
+            let matches;
+            try {
+                // fs.globSync (Node >=22) — cwd-relative, returns posix-ish paths.
+                matches = fs.globSync(pattern, { cwd }).slice().sort();
+            }
+            catch {
+                return `${entry}=<glob-error>`;
+            }
+            if (matches.length > FINGERPRINT_MAX_GLOB_MATCHES) {
+                matches = matches.slice(0, FINGERPRINT_MAX_GLOB_MATCHES);
+            }
+            const parts = [];
+            for (const rel of matches) {
+                const abs = path.resolve(cwd, rel);
+                try {
+                    if (contentMode) {
+                        const st = fs.statSync(abs);
+                        if (st.isFile() && st.size <= FINGERPRINT_MAX_FILE_BYTES) {
+                            const buf = fs.readFileSync(abs);
+                            parts.push(`${rel}:${crypto.createHash("sha256").update(buf).digest("hex").slice(0, 16)}`);
+                        }
+                        else {
+                            parts.push(`${rel}:<skip>`);
+                        }
+                    }
+                    else {
+                        const st = fs.statSync(abs);
+                        parts.push(`${rel}:${st.size}:${Math.floor(st.mtimeMs)}`);
+                    }
+                }
+                catch {
+                    parts.push(`${rel}:<stat-error>`);
+                }
+            }
+            const digest = crypto.createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
+            return `${entry}=${digest}`;
+        }
+        if (entry.startsWith("file:")) {
+            const rel = entry.slice("file:".length);
+            const abs = path.resolve(cwd, rel);
+            try {
+                const st = fs.statSync(abs);
+                if (!st.isFile() || st.size > FINGERPRINT_MAX_FILE_BYTES)
+                    return `file:${rel}=<skip>`;
+                const buf = fs.readFileSync(abs);
+                return `file:${rel}=${crypto.createHash("sha256").update(buf).digest("hex").slice(0, 16)}`;
+            }
+            catch {
+                return `file:${rel}=<missing>`;
+            }
+        }
+        if (entry.startsWith("env:")) {
+            const name = entry.slice("env:".length);
+            return `env:${name}=${process.env[name] ?? ""}`;
+        }
+    }
+    catch {
+        // Fall through to sentinel below.
+    }
+    // Unknown prefixes are rejected at validation time; defensively encode.
+    return `${entry}=<unknown>`;
+}
+/**
+ * Resolve a phase's `fingerprint` list into a single deterministic string to be
+ * folded into the cache key. Returns "" when there are no entries (so the key is
+ * unchanged for phases that declare no fingerprint).
+ */
+export function resolveFingerprint(entries, cwd) {
+    if (!entries || entries.length === 0)
+        return "";
+    // Preserve author order (it's part of the declared key) but resolve each.
+    const resolved = entries.map((e) => resolveOne(e, cwd));
+    return crypto.createHash("sha256").update(resolved.join("\u0000")).digest("hex").slice(0, 16);
+}
+/** Keep at most this many cache entries; LRU-ish eviction by createdAt. */
+const DEFAULT_MAX_ENTRIES = 1000;
+/** Drop entries older than this regardless of TTL (hard backstop). */
+const DEFAULT_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1000; // 90 days
+/** A cache key is a 16-hex inputHash; constrain to that to prevent traversal. */
+function isValidKey(key) {
+    return /^[0-9a-f]{8,64}$/.test(key);
+}
+function entryPath(dir, key) {
+    return path.join(dir, `${key}.json`);
+}
+/**
+ * The cross-run cache, scoped to a working directory. Cheap to construct; all IO
+ * is lazy and failure-tolerant (a broken cache must never break a run).
+ */
+export class CacheStore {
+    dir;
+    constructor(cwd) {
+        this.dir = cacheDir(cwd);
+    }
+    /** Look up a fresh entry. Returns null on miss, malformed key, or TTL expiry. */
+    get(key, ttlMs) {
+        if (!isValidKey(key))
+            return null;
+        let entry;
+        try {
+            const raw = fs.readFileSync(entryPath(this.dir, key), "utf-8");
+            entry = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (typeof entry?.createdAt !== "number")
+            return null;
+        const age = Date.now() - entry.createdAt;
+        if (age > DEFAULT_MAX_AGE_MS)
+            return null;
+        if (ttlMs !== undefined && age > ttlMs)
+            return null;
+        return entry;
+    }
+    /** Store an entry (best-effort; never throws into the run). */
+    put(entry) {
+        if (!isValidKey(entry.key))
+            return;
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            const lock = path.join(this.dir, `${entry.key}.json.lock`);
+            withLock(lock, () => {
+                writeFileAtomic(entryPath(this.dir, entry.key), JSON.stringify(entry, null, 2));
+            });
+            this.cleanup();
+        }
+        catch {
+            /* cache write failures are non-fatal */
+        }
+    }
+    /** Remove all cache entries. Returns the number removed. */
+    clear() {
+        let n = 0;
+        try {
+            for (const f of fs.readdirSync(this.dir)) {
+                if (f.endsWith(".json")) {
+                    try {
+                        fs.unlinkSync(path.join(this.dir, f));
+                        n++;
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        }
+        catch {
+            /* no dir → nothing to clear */
+        }
+        return n;
+    }
+    /** Opportunistic eviction: drop expired/oversized entries. Best-effort. */
+    cleanup() {
+        let files;
+        try {
+            files = fs.readdirSync(this.dir).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            return;
+        }
+        const now = Date.now();
+        const live = [];
+        for (const f of files) {
+            const abs = path.join(this.dir, f);
+            try {
+                const e = JSON.parse(fs.readFileSync(abs, "utf-8"));
+                if (typeof e?.createdAt !== "number" || now - e.createdAt > DEFAULT_MAX_AGE_MS) {
+                    fs.unlinkSync(abs);
+                    continue;
+                }
+                live.push({ file: abs, createdAt: e.createdAt });
+            }
+            catch {
+                try {
+                    fs.unlinkSync(abs);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        if (live.length > DEFAULT_MAX_ENTRIES) {
+            live.sort((a, b) => a.createdAt - b.createdAt); // oldest first
+            for (const victim of live.slice(0, live.length - DEFAULT_MAX_ENTRIES)) {
+                try {
+                    fs.unlinkSync(victim.file);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map