pi-taskflow 0.0.12 → 0.0.13

package/README.md

@@ -7,7 +7,7 @@
   <a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/dm/pi-taskflow?style=flat-square&color=6E8BFF&label=downloads" alt="npm downloads"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-43D9AD?style=flat-square" alt="MIT license"></a>
   <a href="#whats-inside"><img src="https://img.shields.io/badge/runtime%20deps-0-43D9AD?style=flat-square" alt="zero runtime dependencies"></a>
-  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-269-6E8BFF?style=flat-square" alt="269 tests"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-371-6E8BFF?style=flat-square" alt="371 tests"></a>
   <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-B692FF?style=flat-square" alt="for the Pi coding agent"></a>
 </p>
 
@@ -61,26 +61,33 @@ It doesn't replace the subagent tool. It gives your subagents a DAG, a memory, a
 
 ## Compared to other Pi extensions
 
-The Pi ecosystem has a healthy crowd of delegation and orchestration extensions — each great at what it's for. Here's an honest map of where `pi-taskflow` sits (verified against each package's latest npm release, June 2026).
+The Pi ecosystem now has **20+ delegation, workflow, and orchestration extensions** — each great at what it's for. Here's an honest map of where `pi-taskflow` sits (verified against each package's latest npm release, June 2026). For the full breakdown — every package, strengths *and* weaknesses — see [`PI-ECOSYSTEM.md`](./PI-ECOSYSTEM.md). For the broader, non-Pi landscape (LangGraph, Temporal, CrewAI, Mastra…) see [`COMPETITORS.md`](./COMPETITORS.md).
 
 | Extension | Model | Custom DSL | DAG | Dynamic fan-out | Cross-session resume | Quality gate | Human approval | Save as command | Zero deps |
 |---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| **pi-taskflow** | **declarative multi-phase taskflows** | **✓** | **✓** | **✓ `map`** | **✓** | **✓** | **✓** | **✓ `/tf:<name>`** | **✓** |
-| [`pi-agents`](https://www.npmjs.com/package/pi-agents) | JSON workflow graph (`spawn`/`fork`/`join`/`loop`) | ✓ | ✓ | ✕ (static `fork`) | ✕ | ✕ | ✕ | ✕ | ✕ (1) |
-| [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) | single / parallel / chain delegation | ✕ | ✕ | ✕ | ✕ | ✕ | clarify only | named workflows | ✕ (3) |
-| [`pi-crew`](https://www.npmjs.com/package/pi-crew) | multi-agent teams + git worktrees + async | partial | ✕ | ✕ | durable state | ✕ | ✕ | ✕ | ✕ (7) |
-| [`pi-orchestrator`](https://www.npmjs.com/package/pi-orchestrator) | fixed plan→build→review→fix→test pipeline | ✕ | fixed | ✕ | ✕ | ✓ verdict | ✓ | ✕ | ✓ |
-| [`pi-pipeline`](https://www.npmjs.com/package/pi-pipeline) | fixed SPEC→PLAN→TASKS→VERIFY | ✕ | dep graph | ✕ | session planning | ✓ | clarify | ✕ | – |
-| [`pi-agent-flow`](https://www.npmjs.com/package/pi-agent-flow) | one-shot parallel specialist `fork` | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | ✕ | – |
+| **pi-taskflow** | **declarative multi-phase taskflows** | **✓** | **✓** | **✓ `map`** | **✓ phase-hash** | **✓** | **✓** | **✓ `/tf:<name>`** | **✓** |
+| [`@pi-agents/orchid`](https://www.npmjs.com/package/@pi-agents/orchid) | opinionated 9-phase pipeline + Ralph loop | fixed | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ (2) |
+| [`pi-crew`](https://www.npmjs.com/package/pi-crew) | role teams + git worktrees + async | partial | ✓ | ✓ | ✓ | ✓ | ✓ | – | ✕ (7) |
+| [`ultimate-pi`](https://www.npmjs.com/package/ultimate-pi) | governed plan→execute→review harness | YAML contracts | ✓ (plan-time) | ✕ | ✓ | ✓ (3-tier) | ✓ | ✓ | ✕ (16) |
+| [`@zhushanwen/pi-workflow`](https://www.npmjs.com/package/@zhushanwen/pi-workflow) | JS scripts (`agent`/`parallel`/`pipeline`) | yes (JS) | ✕ (linear) | ✓ | ✓ | ✕ | ✕ | ✓ (call cache) | ✓ |
+| [`@fiale-plus/pi-rogue-orchestration`](https://www.npmjs.com/package/@fiale-plus/pi-rogue-orchestration) | timer loop + goal resolution | ✕ | ✕ | ✕ | ✓ | ✓ (goal-check) | ✕ | ✕ | ✓ |
+| [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) | single / parallel / chain delegation | ✕ | ✕ | static | – | ✕ | clarify | named workflows | ✕ (3) |
+| [`@gotgenes/pi-subagents`](https://www.npmjs.com/package/@gotgenes/pi-subagents) | Claude-Code-style subagents + worktrees | ✕ | ✕ | ✕ | ✓ (by id) | ✕ | per-agent | ✕ | ✕ (1) |
+| [`pi-pipeline`](https://www.npmjs.com/package/pi-pipeline) | fixed SPEC→PLAN→TASKS→VERIFY | ✕ | fixed | ✕ | session planning | ✓ | clarify | ✕ | ✕ (2) |
+| [`pi-agent-flow`](https://www.npmjs.com/package/pi-agent-flow) | one-shot parallel specialist `fork` | yes | ✕ | ✕ | – | ✕ | ✕ | – | ✕ (2) |
+
+*(Representative slice of the 20+ — see [`PI-ECOSYSTEM.md`](./PI-ECOSYSTEM.md) for all of them, plus `@0xkobold/pi-orchestration`, `@melihmucuk/pi-crew`, `@mediadatafusion/pi-workflow-suite`, `gentle-pi`, `@dreki-gg/pi-subagent`, and more.)*
 
 **How to choose:**
 
-- **`pi-agents`** is the closest cousin — also a JSON graph with isolated agents, budgets, and `fork`/`loop`/`join`. Reach for `pi-taskflow` when you need what its graph doesn't have: **dynamic `map` fan-out over a discovered list**, **cross-session resume** (continue a half-finished run hours later, cached phases skipped), **quality `gate`s** that halt on a verdict, **human `approval`** steps, and **saving the whole pipeline as a `/tf:<name>` command**.
-- **`pi-subagents`** is the right tool for ad-hoc “use reviewer on this diff” delegation and background jobs. `pi-taskflow` is for when those delegations need to become a *repeatable, resumable pipeline*.
-- **`pi-crew`** goes heavier — worktree isolation and durable async teams. If you want lightweight, declarative, and zero-dependency, that's this project.
-- **`pi-orchestrator` / `pi-pipeline`** ship *opinionated, fixed* workflows (plan→build→… / spec-driven). `pi-taskflow` ships an *empty canvas*: you (or the model) declare the graph that fits the job.
+- **`@pi-agents/orchid`** is the most feature-complete orchestrator in the ecosystem (DAG + worktrees + Ralph loop + agent mailbox) — but its DSL is a *fixed* 9-phase pipeline, it carries runtime deps + jiti, and it's beta. Reach for `pi-taskflow` when you want to **define your own graph** (not adopt an opinionated one) with **zero dependencies** and a one-command install.
+- **`pi-crew` / `ultimate-pi`** go heavier — worktree isolation, durable async teams, multi-tier governance. If you want lightweight, declarative, and zero-dependency, that's this project.
+- **`@zhushanwen/pi-workflow`** is the closest in spirit and also zero-dep, but you author workflows as **JavaScript scripts**. `pi-taskflow`'s **declarative JSON DSL** is safer and more auditable, and its **phase-level input-hash resume** is more granular than call-cache dedup.
+- **`@fiale-plus/pi-rogue-orchestration`** has a real **loop-until-done** (a feature `pi-taskflow` doesn't yet have). If your job is "keep going until the goal is met," it's worth a look; `pi-taskflow` is for *structured, branching* pipelines instead.
+- **`pi-subagents` / `@gotgenes/pi-subagents`** are the mature picks for ad-hoc "use reviewer on this diff" delegation and background jobs. `pi-taskflow` is for when those delegations need to become a *repeatable, resumable pipeline*.
+- **`pi-pipeline` / `pi-agent-flow`** ship *opinionated, fixed* flows. `pi-taskflow` ships an *empty canvas*: you (or the model) declare the graph that fits the job.
 
-> The honest one-liner: **nothing else in the ecosystem combines a declarative DAG, `map` fan-out, cross-session resume, gates, approvals, and save-as-command — with zero runtime dependencies.**
+> The honest one-liner: **`pi-taskflow` is the only Pi extension that gives you a declarative, resumable, DAG-shaped subagent pipeline you save as a one-word command — with zero runtime dependencies and context isolation by design.** The known gaps it's closing next: loop-until-done, worktree isolation, and non-blocking background runs (see [`STRATEGY.md`](./STRATEGY.md)).
 
 ## 30-second start
 
@@ -90,6 +97,10 @@ The Pi ecosystem has a healthy crowd of delegation and orchestration extensions
 pi install npm:pi-taskflow
 ```
 
+> **Optional:** run `/tf init` once to map the 18 built-in agents' model roles
+> (`fast`, `strong`, `thinker`, …) to your own models — an interactive picker.
+> Skip it and agents just use Pi's default model. See [Model roles](#model-roles).
+
 **2. Run** — just ask the model in a Pi session:
 
 > *Run a chain: first explore the auth flow, then summarize the findings.*
@@ -218,6 +229,8 @@ No scripting. No `eval`. Just data the runtime executes — safe enough to run L
 | `reduce` | aggregate `from[]` phase outputs into one | `from`, `task` |
 | `approval` | **human-in-the-loop** pause — approve / reject / edit | — |
 | `flow` | run a **saved sub-flow** as one phase (composition) | `use` |
+| `loop` | **iterate a task until done** — re-run a body until a condition, convergence, or a cap | `task`, `until` |
+| `tournament` | **N variants compete**, a judge picks the best (or aggregates) | `task` \| `branches` |
 
 ### Common phase fields
 
@@ -237,6 +250,7 @@ Every phase needs a unique `id` and a `type` (defaults to `agent`). On top of th
 | `final` | Marks the result-bearing phase (else the last phase wins) |
 | `optional` | A failure here does **not** abort the run |
 | `use` / `with` | (`flow`) saved sub-flow name + its args |
+| `cache` | `{ scope, ttl?, fingerprint? }` — cross-run memoization (see below) |
 
 Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8), `agentScope`, and `budget: { maxUSD?, maxTokens? }`.
 
@@ -247,9 +261,73 @@ Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8), `agen
 - **`retry`** — `{ "max": 2, "backoffMs": 500, "factor": 2 }` retries a failing subagent with fixed or exponential backoff; usage is summed and the attempt count shows as `↻N` in the TUI. Transient provider errors (rate-limit / 5xx / timeout) **auto-retry even without an explicit policy**; hard errors don't.
 - **`approval`** — pause for a human (Approve / Reject / Edit). Reject halts the flow; Edit injects the typed note as the phase output for downstream steps. Non-interactive runs auto-approve.
 - **`flow`** — `{ "type": "flow", "use": "deep-research", "with": { "topic": "{item}" } }` runs a saved flow as a phase (recursion is detected and rejected).
+
+### Loop-until-done (`loop`)
+
+Some work is inherently iterative — refine a draft until a reviewer is satisfied, retry-and-improve until tests pass, converge on an answer. A `loop` phase re-runs one task body until a stop condition holds:
+
+```jsonc
+{
+  "id": "refine",
+  "type": "loop",
+  "task": "Improve this draft (iteration {loop.iteration}). Previous attempt:\n{loop.lastOutput}\n\nReturn JSON {\"draft\":\"…\",\"done\":true|false}.",
+  "until": "{steps.refine.json.done} == true",   // the iteration's own output is exposed here
+  "output": "json",
+  "maxIterations": 6,        // default 10, hard cap 100 — the loop ALWAYS terminates
+  "convergence": true        // default: stop early if an iteration's output is identical to the last
+}
+```
+
+- **Body locals** — the task can read `{loop.iteration}` (1-based), `{loop.lastOutput}` (the prior iteration's output), and `{loop.maxIterations}` to build on its own previous work; all three are also available to the `until` condition.
+- **`until`** — evaluated after each iteration with the iteration's output exposed as `{steps.<thisId>.output}` / `.json`. Same operators as `when`. The loop stops the moment it's truthy.
+- **Always terminates.** Four independent stops: `until` truthy, **convergence** (a fixed point — output identical to the previous iteration), **`maxIterations`** (hard-capped at 100), or a **failing iteration** (the phase fails with the partial output preserved). A malformed `until` **stops** the loop rather than spinning forever (fail-safe) and surfaces a warning on the phase.
+- The TUI shows `↻N` with the stop reason (`done` / `converged` / `max` / `failed`); usage is summed across iterations. Like `gate`/`approval`, `loop` is **excluded from `cross-run` cache** (each run must iterate fresh).
+
+### Tournament (`tournament`)
+
+For open-ended work, the best result often comes from generating several candidates and picking the strongest — best-of-N with a judge, in one declarative phase:
+
+```jsonc
+{
+  "id": "headline",
+  "type": "tournament",
+  "task": "Write a punchy headline for this launch post.",
+  "variants": 4,                    // spawn 4 competitors of the SAME task (default 3, max 20)
+  "judge": "Pick the headline with the strongest hook and clearest promise.",
+  "judgeAgent": "reviewer",          // optional; defaults to the phase agent
+  "mode": "best"                     // "best" (default) | "aggregate"
+}
+```
+
+- **Competitors** — either `variants: N` copies of one `task` (diversity comes from model nondeterminism), or distinct `branches: [{task, agent?}, …]` when you want to pit *different approaches* against each other.
+- **Judge** — after the fan-out, one judge agent sees every variant (numbered) plus your `judge` rubric and picks a winner via a `WINNER: <n>` line or `{"winner": n}`. An unreadable verdict **fails open** to variant 1; a failed judge falls back too — the work is never lost.
+- **`mode`** — `best` returns the winning variant **verbatim**; `aggregate` returns the judge's **synthesized** answer combining the strongest parts.
+- **Short-circuits:** if only one competitor survives, it wins with no judge call; if all fail, the phase fails. The TUI shows `⚑ N→#k`; usage sums variants + judge. Like `gate`, it's **excluded from `cross-run` cache**.
 - **`budget`** — a run-wide `{maxUSD, maxTokens}` ceiling; once exceeded, pending phases skip and in-flight fan-out stops spawning, ending the run as `blocked`.
 - **idle watchdog** — a subagent that goes silent for 5 minutes is treated as wedged and killed (SIGTERM → SIGKILL), so one hung child can never freeze the whole flow.
 
+### Cross-run memoization (`cache`)
+
+Every phase is already content-addressed: within a single run's **resume**, a phase whose resolved inputs are unchanged is skipped. `cache` extends that reuse **across independent runs** — if any prior run computed a phase with an identical input hash, its result is reused for **$0.00**.
+
+```jsonc
+{
+  "id": "analyze-auth",
+  "task": "Summarize how the auth module works.",
+  "context": ["src/auth/**/*.ts"],
+  "cache": {
+    "scope": "cross-run",                 // "run-only" (default) | "cross-run" | "off"
+    "ttl": "6h",                          // optional max age before a hit is treated as a miss
+    "fingerprint": ["git:HEAD", "glob:src/auth/**/*.ts"]  // fold world-state into the key
+  }
+}
+```
+
+- **`scope`** — `"run-only"` (default) is exactly the historical behavior (within-run resume only). `"cross-run"` opts the phase into the persistent store. `"off"` disables reuse entirely (even within a run), for debugging.
+- **Freshness is the whole game.** The cache key already includes the prompt, the `over` items, and any `context` files (pre-read into the task). `fingerprint` folds *implicit* inputs into the key so "the world changed" becomes a cache miss: `git:HEAD`, `glob:<pat>` (size+mtime), `glob!:<pat>` (content hash), `file:<path>`, `env:<NAME>`. `ttl` (`30m`/`6h`/`7d`) is a time backstop.
+- **Honest limit:** a subagent that reads a file it didn't declare in `context`/`fingerprint` can still serve a stale `cross-run` hit. That's why the default is `run-only` and why `gate`/`approval` phases are **forbidden** from `cross-run` (they must produce a fresh result each run). Opt in only for phases whose output is a function of declared inputs.
+- Cache lives in `.pi/taskflows/cache/` (gitignored). Clear it with `action: "cache-clear"`. Full rationale: [`docs/rfc-cross-run-memoization.md`](./docs/rfc-cross-run-memoization.md).
+
 ### Gate phases (quality control)
 
 A `gate` runs an agent to review upstream output and can **block the rest of the workflow.** End the gate task by asking for a verdict the runtime can read:
@@ -291,10 +369,10 @@ Saved flows become CLI shortcuts. All commands run in the Pi session:
 | `/tf show <name>` | Print a flow's definition |
 | `/tf runs` | Browse recent run history (interactive TUI) |
 | `/tf resume <runId>` | Continue a paused/failed run — cached phases skip automatically |
-| `/tf init` | Generate default modelRoles config in `~/.pi/agent/settings.json` |
+| `/tf init` | **Interactively map model roles** to your enabled models (writes `~/.pi/agent/settings.json`) |
 | `/tf:<name> [args]` | Shortcut — runs the flow in one tap |
 
-Tool actions (used by the model): `run` (inline `define` or saved `name`), `save`, `resume`, `list`.
+Tool actions (used by the model): `run` (inline `define` or saved `name`), `save`, `resume`, `list`, `init`.
 
 ## Resume across sessions
 
@@ -366,14 +444,57 @@ Each built-in agent's `model` field uses a **role placeholder** (e.g. `{{fast}}`
 | `{{vision}}` | Multimodal — UI work, design reading | MiniMax M3 |
 | `{{reasoner}}` | Cautious reasoning — security, risk | GLM 5.1 |
 
-Without configuration, agents fall back to Pi's default model. To assign specific models:
+Without configuration, agents fall back to Pi's default model. To map roles to real models, run the interactive setup:
 
 ```bash
-# Auto-generate ~/.pi/agent/settings.json with default role mappings
 /tf init
 ```
 
-This writes:
+`/tf init` starts with an **action menu**. First-time users get a 2-option shortcut ("Use recommended defaults" / "Configure each role"). Returning users see the full 5-option menu:
+
+```
+? What do you want to do with model roles?
+  ❯ Use recommended defaults
+    Configure each role
+    Edit one role
+    Show current roles
+    Cancel
+```
+
+The picker shows model **display names** with capability flags and current/recommended markers:
+
+```
+? Model for 'vision' — Multimodal (executor-ui, visual-explorer)
+  Current: openrouter/anthropic/claude-sonnet-4-6
+  Recommended: minimax/MiniMax-M3
+  ───────────────
+  ❯ MiniMax M3 (minimax/MiniMax-M3) · image ✓ · reasoning ✓ · (recommended)
+    Claude Sonnet 4.6 (openrouter/anthropic/...) · image ✓ · reasoning ✓ · (current)
+    GPT-5 (openrouter/openai/gpt-5) · image ✓
+    DeepSeek V4 Flash (openrouter/deepseek/v4-flash)
+    ───────────────
+    Custom (type your own)
+    Keep current
+    Back to action menu
+```
+
+Before saving, a **preview screen** shows the diff of your changes:
+
+```
+? Review changes:
+  fast       openrouter/deepseek/deepseek-v4-flash   (unchanged)
+  strong     openrouter/xiaomi/mimo-v2.5-pro         (unchanged)
+  thinker    openrouter/qwen/qwen3.7-max             (changed ← was: openrouter/deepseek/v4-pro)
+  arbiter    openrouter/qwen/qwen3.7-max             (unchanged)
+  vision     minimax/MiniMax-M3                      (unchanged)
+  reasoner   z-ai/glm-5.1                            (unchanged)
+  ───────────────
+  ❯ Save these changes
+    Edit a role
+    Cancel
+```
+
+Your choices are written to `~/.pi/agent/settings.json`:
 
 ```json
 {
@@ -388,7 +509,7 @@ This writes:
 }
 ```
 
-Edit the values to match your available providers. You can also override individual agents via `subagents.agentOverrides` in the same file:
+Edit the values manually any time, or just re-run `/tf init`. You can also override individual agents via `subagents.agentOverrides` in the same file:
 
 ```json
 {
@@ -402,6 +523,18 @@ Edit the values to match your available providers. You can also override individ
 }
 ```
 
+### Tool path (`action="init"`)
+
+The model can also configure roles via the `taskflow` tool:
+
+| Mode | Behavior |
+|---|---|
+| `mode: "show"` (default) | Read-only report of current `modelRoles`. Never overwrites. |
+| `mode: "apply-defaults"` + `force: true` | Writes `RECOMMENDED_DEFAULTS` to `settings.json`, preserving stale keys. |
+| `mode: "interactive"` | Launches the full action menu + picker flow (requires a UI session). |
+
+> **v0.0.13 deprecation note:** If `mode` is omitted, the tool falls back to v0.0.12 behavior when `modelRoles` is empty (auto-writes defaults) with a `console.warn` deprecation notice. If `modelRoles` already exists, it behaves as `mode: "show"`. This bridge will be removed in v0.0.14.
+
 ### Custom agents
 
 Drop a `.md` file into `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level, commit it) to add your own:
@@ -441,12 +574,12 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 
 <div align="center">
 
-**0 runtime dependencies** · **269 tests** · **7 phase types** · **cross-session resume** · **~4.4k LOC runtime**
+**0 runtime dependencies** · **371 tests** · **10 phase types** · **cross-session resume** · **cross-run memoization** · **~4.9k LOC runtime**
 
 </div>
 
 - **Zero runtime dependencies.** No `dependencies` field — the runtime is built entirely on Node built-ins (`fs` / `path` / `os` / `child_process` / `crypto`). The file lock is `fs.openSync("wx")`, not a third-party library.
-- **269 tests across 11 suites** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, gate verdicts, budget caps, retry/backoff, approval flows, sub-flow composition, callback isolation, and the idle watchdog — plus a live end-to-end test that spawns real subagents.
+- **371 tests across 14 suites** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, cross-run cache freshness (flow/thinking/tools key isolation, fingerprint invalidation, TTL/LRU eviction), gate verdicts, budget caps, retry/backoff, approval flows, loop termination, tournament judging, sub-flow composition, callback isolation, the idle watchdog, model-role init config, and parseModelFromLabel with parenthesized-model-name regression — plus a live end-to-end test that spawns real subagents and a cross-run cache dogfood.
 - **Hardened by design.** Path-traversal defense (lexical + `realpath`), runId validation, HTML/error sanitization, atomic writes, stale-lock stealing via `rename`, and an idle watchdog that kills wedged subagents.
 - **Dogfooded.** Every new feature has to survive the project's own `self-improve` taskflow before it ships.
 
@@ -454,7 +587,7 @@ If this saves you a context window, **drop a ⭐ on [GitHub](https://github.com/
 
 ## Status & limits
 
-**v0.0.11** — full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`), inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
+**v0.0.13** — loop-until-done (`loop` phase: iterate to a condition, convergence, or cap), tournament (best-of-N with a judge), cross-run memoization (content-addressed cache with git/file/glob/env fingerprints and TTL), interactive `/tf init` with role-aware model pickers + diff preview + atomic merge-write, 18 built-in agents with 6 model roles. Full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`). Inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
 
 Known boundaries (tracked, bounded — no surprises mid-flow):
 

package/extensions/cache.ts

@@ -0,0 +1,263 @@
+/**
+ * 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.ts";
+
+// ---------------------------------------------------------------------------
+// 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: string, cwd: string): string {
+	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"],
+				}).trim();
+				return `git:${ref}=${sha}`;
+			} catch {
+				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: string[];
+			try {
+				// fs.globSync (Node >=22) — cwd-relative, returns posix-ish paths.
+				matches = (fs.globSync(pattern, { cwd }) as string[]).slice().sort();
+			} catch {
+				return `${entry}=<glob-error>`;
+			}
+			if (matches.length > FINGERPRINT_MAX_GLOB_MATCHES) {
+				matches = matches.slice(0, FINGERPRINT_MAX_GLOB_MATCHES);
+			}
+			const parts: string[] = [];
+			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: string[] | undefined, cwd: string): string {
+	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);
+}
+
+// ---------------------------------------------------------------------------
+// Cross-run cache store
+// ---------------------------------------------------------------------------
+
+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;
+	/** Provenance for audit / cleanup. */
+	flowName?: string;
+	phaseId?: string;
+	runId?: string;
+}
+
+/** 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: string): boolean {
+	return /^[0-9a-f]{8,64}$/.test(key);
+}
+
+function entryPath(dir: string, key: string): string {
+	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 {
+	private dir: string;
+
+	constructor(cwd: string) {
+		this.dir = cacheDir(cwd);
+	}
+
+	/** Look up a fresh entry. Returns null on miss, malformed key, or TTL expiry. */
+	get(key: string, ttlMs?: number): CacheEntry | null {
+		if (!isValidKey(key)) return null;
+		let entry: CacheEntry;
+		try {
+			const raw = fs.readFileSync(entryPath(this.dir, key), "utf-8");
+			entry = JSON.parse(raw) as CacheEntry;
+		} 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: CacheEntry): void {
+		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(): number {
+		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. */
+	private cleanup(): void {
+		let files: string[];
+		try {
+			files = fs.readdirSync(this.dir).filter((f) => f.endsWith(".json"));
+		} catch {
+			return;
+		}
+		const now = Date.now();
+		const live: Array<{ file: string; createdAt: number }> = [];
+		for (const f of files) {
+			const abs = path.join(this.dir, f);
+			try {
+				const e = JSON.parse(fs.readFileSync(abs, "utf-8")) as CacheEntry;
+				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 */
+				}
+			}
+		}
+	}
+}