pi-fovea 0.2.0 → 0.3.1

package/README.md

@@ -4,10 +4,10 @@
 
 **A foveated repo-mapping extension for [Pi](https://github.com/earendil-works/pi-coding-agent)**
 
-_Survey, focus, dwell, impact — a budget-capped field of view instead of a folder dump._
+_See the whole repo on every prompt, sharp where you work and cheap everywhere else._
 
 <p>
-  <img src="https://raw.githubusercontent.com/monotykamary/pi-fovea/main/media/cover.svg" alt="pi-fovea: a code graph seen through a fovea — hot at the center, collapsed at the rim" width="1100">
+  <img src="https://raw.githubusercontent.com/monotykamary/pi-fovea/main/media/cover.svg" alt="pi-fovea: a code graph seen through a fovea, hot at the center and collapsed at the rim" width="1100">
 </p>
 
 [![npm version](https://img.shields.io/npm/v/pi-fovea?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/pi-fovea)
@@ -17,35 +17,23 @@ _Survey, focus, dwell, impact — a budget-capped field of view instead of a fol
 
 </div>
 
----
+pi-fovea hands the model a map of your repo on every prompt. The repo compiles once into a code graph across languages, where symbols, files, and route anchors join into one network. Each question becomes an interest vector that diffuses over the graph as heat. The renderer converts the field into a token-capped view: full signatures near your task, one-liners a hop away, a skeleton of the rest.
 
-Large models have small context. pi-fovea turns a repository into a **heat field** over a cross-language code graph — symbols, files, route anchors — and hands the model exactly `maxTokens` of it at a time, sharp where you look and whole-picture-but-cheap everywhere else. After every edit it silently re-syncs, and only speaks up when the change didn't stay local.
+After each assistant turn the map re-syncs incrementally. Detection reads content hashes instead of tool events, so edits made by pi's edit/write tools, a fabric_exec inner `pi.edit`, a bash heredoc, a subagent, or an editor save outside the session all land identically. A clean turn stays silent. A turn that moves route anchors or warms files you have not looked at says so.
 
-## Why Fovea?
+## What the model gets
 
-|     | Capability | What it unlocks |
-| :-: | ---------- | --------------- |
-| 🔭 | **Survey** | `fovea_sketch` renders the whole repo as a low-acuity silhouette — feature anchors and basins by mass, never raw file lists. |
-| 🎯 | **Focus** | `fovea_focus` centers on a symbol, route, or env key: hot nodes as signatures, warm nodes as one-liners, periphery collapsed. |
-| ⏱️ | **Dwell** | `fovea_dwell` diffuses longer and returns only the delta. Chebyshev vectors are cached — a new timescale is coefficient recombination, not a re-walk. |
-| 🌡️ | **Impact** | `fovea_impact` predicts the co-change cascade across languages — what a file, symbol, or PR base warms up. |
-| 🩸 | **Turn sync** | After every edit turn the graph re-syncs for free. Anchor shifts and unwatched warmings surface as red flags; stable turns stay silent. |
-| 🪙 | **Token truth** | Budgets are hard caps, not hopes: the renderer fits a monotonic prefix and never exceeds `maxTokens`. |
+| Command | Ask | Answer |
+|---|---|---|
+| `fovea_sketch` | where is everything? | the repo as a silhouette, with feature anchors and inferred regions ranked by mass |
+| `fovea_focus` | what is this? | centered on a symbol, route path, or env key: hot nodes as signatures, neighbors as one-liners |
+| `fovea_dwell` | what else? | diffuses the field one step further and returns the delta |
+| `fovea_impact` | what does this touch? | warms everything a file, symbol, or PR base reaches across languages |
 
-## How it works
-
-The repo compiles to a typed graph whose edges carry **conductance**: imports are bridges, calls are solid, and shared literals — route paths, env keys — are the cross-language welds, weighted by specificity. Your interest is a heat source `s`; the map the model receives is the heat kernel run for time `t` over the graph Laplacian:
-
-```text
-v(t) = e^{−tL} · s
-```
-
-- **sketch** — large `t`, hub + anchor seeds: the whole repo in one blurry-but-valid silhouette.
-- **focus** — small `t`, your query as the seed: the fovea on exactly that feature.
-- **dwell** — `t` ×2 per call; only newly-luminous nodes are returned.
-- **impact** — changed files as the seed; warmth = predicted blast radius.
+Two slash commands on top:
 
-Lineage: spectral-graph heat kernels (SGWT evaluated by shared Chebyshev recurrence), progressive image coding (budget as bitrate over significance-sorted coefficients), foveated rendering. Nanobridge: aider's PageRank repo map is the fixed-timescale special case.
+- `/fovea status` for graph stats and sync state
+- `/fovea settings` for an overlay in your TUI, styled after pi-fabric's `/fabric settings`
 
 ## Install
 
@@ -73,34 +61,28 @@ pi install /absolute/path/to/pi-fovea
 
 </details>
 
-Then, in any repo session, the model gets the four `fovea_*` tools; you get:
-
-- `/fovea status` — graph stats, sync on/off
-- `/fovea settings` — an overlay built from the same SettingsList idiom as pi-fabric's `/fabric settings`
-
-### CLI
-
-The same ops, stateless and pipe-friendly — for agent shells, CI, and `llmc`-style uses:
+There is also a package for any agent shell or CI:
 
 ```sh
 fovea sketch /path/to/repo 900
 fovea focus /path/to/repo "/v1/messages" 800
 fovea impact /path/to/repo --base main 1200
+fovea rules /path/to/repo
 fovea status /path/to/repo
 ```
 
-(`fovea` bins to `cli.ts` via `tsx`; install `tsx` globally or use `pnpm fovea` from a checkout.)
+`fovea` runs `cli.ts` via `tsx`. Install `tsx` globally, or use `pnpm fovea` from a checkout.
 
-## Turn-sync (default on)
+## Turn sync
 
-After every assistant turn, fovea re-syncs the graph — guaranteed incremental by content hash — no edits means zero work. The verdict:
+Turn sync is on by default. After every assistant turn the graph is re-synced against your edits: unchanged files cost nothing because every parsed fact sits behind its content hash. The verdict is **green** or **red**:
 
-- **green** → silent in the model's context (a UI toast only if `sync.ackClean` is on).
-- **red** → a capped custom message: route anchors that appeared/disappeared, plus files the edit cascade warmed that the model hasn't focused yet.
+- **green**: silence in the model's context. A clean-toast shows only if you enable `sync.ackClean`.
+- **red**: a capped custom message naming route anchors that appeared or disappeared, plus files warmed by the edit cascade that the model has not focused on yet.
 
-The first sync establishes the baseline; the first drift after it calibrates the warm neighborhood rather than alarming, so a steady feature cone doesn't page the model every edit.
+The first sync seeds the baseline. The first drift after it calibrates the warm neighborhood, so a steady feature cone stays quiet. Sub sequent drift turns red.
 
-Opt out per-repo or globally: `/fovea settings` → "Turn sync → false", or
+Turn it off per repo or globally: `/fovea settings` → Turn sync, or
 
 ```sh
 FOVEA_TURN_SYNC=off pi
@@ -108,33 +90,42 @@ FOVEA_TURN_SYNC=off pi
 
 ## Configuration
 
-Global `~/.pi/agent/fovea.json`; project override `<repo>/.pi/fovea.json` when trusted — the same two-scope model as pi-fabric's `fabric.json`.
+Global settings live in `~/.pi/agent/fovea.json`. A trusted repo-level override sits in `<repo>/.pi/fovea.json`. Two scopes, the same model pi-fabric uses with `fabric.json`.
 
 | Key | Default | Meaning |
 | --- | :-----: | ------- |
 | `sync.enabled` | `true` | the turn-sync loop |
-| `sync.budget` | `1024` | tokens for the red model-visible report |
-| `sync.ackClean` | `false` | toast on clean structural turns (no model tokens either way) |
-| `sync.warmFileThreshold` | `2` | newly-warm undisclosed files that justify red |
-| `tools.defaultBudget` | `2000` | fallback maxTokens for fovea_* tool calls |
+| `sync.budget` | `1024` | token cap for the red report seen by the model |
+| `sync.ackClean` | `false` | toast after clean structural turns |
+| `sync.warmFileThreshold` | `2` | warmed files unseen by the model that justify turning red |
+| `tools.defaultBudget` | `2000` | fallback maxTokens for the fovea_* tools |
 
-## Repo rule packs
+## How routes are found
 
-The built-in pack catches route declarations by **port shape**, not framework name — five shapes cover almost the whole ecosystem:
+Route anchors come from port shapes, and five shapes cover almost the whole ecosystem:
 
 | Port shape | Examples |
 |---|---|
-| `recv.verb("path", handlers…)` | express, koa, fastify, hono, gin, echo, chi, net/http (any quotes, incl. TS template literals and Python f-strings) |
-| verb-annotation + optional class prefix | NestJS `@Controller + @Get`, Flask/FastAPI decorators, Spring `@RequestMapping + @GetMapping` |
+| `recv.verb("path", handlers…)` | express, koa, fastify, hono, gin, echo, chi, net/http |
+| annotation + optional class prefix | NestJS `@Controller + @Get`, Flask and FastAPI decorators, Spring `@RequestMapping + @GetMapping` |
 | verb embedded in the path | Go 1.22 `mux.HandleFunc("GET /x", h)` |
 | verb as first string argument | chi `r.Method("GET", path, h)`, aiohttp `router.add_route("GET", path, h)` |
 | receiver-less DSL macros | Rails `routes.rb`, Phoenix `router.ex`, Django `path()`, Ktor `routing { get("/x") {} }` |
 
-File-convention routers never write a route string at all — those anchors are derived from **file paths** (Next.js App Router `app/**/route.ts` + `page.tsx`, Pages Router `pages/api/**`, SvelteKit `+server.ts` / `+page.svelte`, Nuxt `server/api/**.get.ts`, Astro endpoints), with verbs pulled from exported handler names or file-name suffixes.
+File-convention routers declare paths nowhere in code. Next.js App Router, Pages Router, SvelteKit, Nuxt, and Astro anchors therefore derive from file paths, with the verb read off exported handler names or filename suffixes.
+
+### Discovery mode
 
-**Known blind spots** (deliberate, logged in `src/core/anchors.ts`): Rust proc-macro attribute routers (actix `#[get("/x")]`, rocket) — ast-grep patterns can't parameterize attribute paths; frameworks with constructor-assigned prefixes (Flask Blueprint, FastAPI `APIRouter(prefix=…)`, chi `Mount`, Express `Router` mounts) — variable binding tracking is out of band; `scope`/`namespace` nesting in Phoenix/Rails/Django `include()` — prefixes across blocks aren't composed; tRPC/GraphQL/gRPC — no path token exists to anchor on.
+When a repo writes routes in a shape fovea has never seen, the literal pass harvests every call shape and promotes statistically solid ones into implicit rules. Discovered anchors carry half the conductance of declared ones and appear with a `△` sigil. Turn sync reports their churn without letting an unconfirmed hypothesis turn the verdict red. A hub upgrades to first-class the moment a known rule matches any of its sites.
+
+```sh
+fovea anchors <root> --discovered   # the △ hypothesis hubs only
+fovea rules <root>                  # promoted rules with evidence
+fovea rules <root> --sigs           # every path-touching signature, by precision
+fovea rules <root> --adopt          # persist promotions into .fovea/rules.json
+```
 
-Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-ins:
+`.fovea/rules.json` pins community or project rules in the repo:
 
 ```json
 {
@@ -144,23 +135,43 @@ Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-i
 }
 ```
 
-Changing the rules file invalidates **only** the anchor extraction cache — green-node reuse one level up.
+A rule may declare `prefixPattern` so a class-level prefix like `@Controller('api/airports')` composes with per-method paths. Changing the rules file invalidates the anchor extraction cache alone; parsed facts above it carry over.
+
+**Blind spots**, logged in `src/core/anchors.ts`: Rust proc-macro attributes (actix `#[get("/x")]`), constructor-assigned prefixes (Flask Blueprint, FastAPI `APIRouter(prefix=…)`, chi `Mount`, Express `Router` mounts), `scope` and `namespace` nesting in Phoenix, Rails, or Django `include()`, and tRPC/GraphQL/gRPC (no path token exists to anchor on).
+
+## How it works
+
+The repo compiles to a typed graph. Your question is a source vector $s$ over its nodes, and the field the model receives is the heat kernel at time $t$ over the Laplacian $L$:
+
+$$
+v(t) = e^{-tL} \cdot s \quad \text{with} \quad L = I - D^{-1/2} W D^{-1/2}
+$$
+
+The four tools are the same operator at four timescales: sketch at $t=16$ with hub and anchor seeds, focus at $t=4$ with your query as seed, dwell doubling $t$ per call with a disclosed-set delta, and impact using the changed files as seed.
+
+The kernel is evaluated with a Chebyshev expansion. Rescale $M = L - I$ so the spectrum sits in $[-1,1]$; then with $T_k$ the Chebyshev polynomials and $I_k$ the modified Bessel functions:
+
+$$
+e^{-tL} = e^{-t} \left[ I_0(t) T_0(M) + 2 \sum_{k\ge 1} (-1)^k I_k(t) T_k(M) \right]
+$$
+
+The vectors $T_k(M) s$ are cached in the session. A new timescale costs coefficient recombination, never a second graph walk.
+
+Discovery asks how often the argument at one slot of one call shape carries a route path, and promotes the shape past a Jeffreys-smoothed posterior:
 
-A rule may additionally declare `prefixPattern` (e.g. NestJS `@Controller('api/airports')`) so per-method paths like `@Get('search')` compose into the full router-visible anchor `GET /api/airports/search` — see `ts-http-decorator*` in `src/core/anchors.ts`.
+$$
+\hat{p} = \frac{\mathrm{pathN} + \frac{1}{2}}{\mathrm{n} + 1} \ge 0.55 \quad \text{with} \quad \mathrm{n} \ge 4 \text{ sites and} \ge 2 \text{ files}
+$$
 
-## How the graph is joined
+Measured against eight cloned projects, corpus junk sits below $\hat{p} \approx 0.27$ and real route shapes above $\hat{p} \approx 0.75$. The cutoff stays mid-cliff regardless of repo size.
 
-- **imports / contains / inherits / tests** — outline-derived; call edges specificity-tiered, with language builtins and log/test entry points warded off
-- **literal joins** — route paths, env keys, OpenAPI operation paths; document-frequency-gated cliques so rare literals bridge strongly and ubiquitous ones don't become gravity wells
-- **co-change** — mined from recent git history (Jaccard-tilted, per-file capped, cached by HEAD), so files that commute together warm each other even without a static edge
-- **feature hubs** — route declarations and every client call of the same normalized path collapse to ONE anchor node: where client, server, and spec meet
-- **basins** — where there are no routes at all (CLIs, kernels), sketch infers implicit features as conductance-cut regions around triangle-dense seeds
+Lineage: spectral-graph wavelets evaluated by shared Chebyshev recurrence, progressive image coding where the budget is a bitrate over significance-ordered coefficients, and foveated rendering. Aider's PageRank repo map is the fixed-timescale special case of this field. The full walkthrough of conductance tiers, specificity bridges, hub gravity, and basins lives in [docs/heat-diffusion.md](docs/heat-diffusion.md).
 
-## Language matrix
+## Languages
 
-Full symbol + call extraction: **TypeScript/TSX · JavaScript · Python · Go · Rust**.
-Outline-based symbols with heuristic naming: **Elixir · Ruby · C · C++ · Java · Kotlin · Lua · PHP · Swift · Scala · Haskell · Bash**.
-Config joins through literals: **YAML · JSON · TOML · env · Markdown · OpenAPI**.
+Full symbol and call extraction: **TypeScript, TSX, JavaScript, Python, Go, and Rust**.
+Outline-based symbols: **Elixir, Ruby, C, C++, Java, Kotlin, Lua, PHP, Swift, Scala, Haskell, and Bash**.
+Config joins through literals: **YAML, JSON, TOML, env, Markdown, and OpenAPI**.
 
 ## Development
 
@@ -170,6 +181,6 @@ pnpm run check        # typecheck + full vitest suite
 pnpm run bench        # rate–distortion bench against ../pi-fabric
 ```
 
-pi loads the extension straight from `src/` via jiti — **there is no build step**. Per-repo caches live in `$TMPDIR` (content sha1 per file; only dirty files re-run ast-grep). Bump `CACHE_VERSION` in `src/core/build.ts` when extractor semantics change.
+pi loads the extension straight from `src/` via jiti; there is no build step. Per-repo caches live in `$TMPDIR` behind per-file content sha1 hashes, and only dirty files re-run ast-grep. Bump `CACHE_VERSION` in `src/core/build.ts` whenever extractor semantics change.
 
 [MIT](LICENSE).

package/cli.ts

@@ -6,12 +6,16 @@
 //   fovea dwell [root] [factor] [budget]     (deepens the in-process focus)
 //   fovea impact [root] [--files a,b] [--symbols x,y] [--base ref] [--no-uncommitted] [budget]
 //   fovea anchors [root] [filter]             (every feature anchor, sorted)
+//   fovea rules [root]                        (tier-3 discovered shape hypotheses)
 //
 // The CLI is stateless across invocations (dwell needs a prior focus in the
 // same process — combine ops inside pi, where sessions persist); stdout is
 // the rendered field, nothing else, so it composes with head/grep/$().
 
+import { statSync } from "node:fs";
 import { ensureState, sketch, focus, dwell, impact } from "./src/core/ops.js";
+import { aggregateFiles, posterior, promote } from "./src/core/discover.js";
+import { DEFAULT_PACK } from "./src/core/anchors.js";
 
 const [, , cmd = "status", ...argv] = process.argv;
 
@@ -37,9 +41,15 @@ const numAt = (i: number): number | undefined => {
   return Number.isFinite(n) && n > 0 ? n : undefined;
 };
 // Root is the first positional that names a path; everything else is arg data.
+// Existing directories count as paths even when bare ("next", "kernel").
 const rootAt = (i: number): string => {
   const p = pos[i];
-  return p !== undefined && (p.includes("/") || p === ".") ? p : ".";
+  if (p === undefined) return ".";
+  if (p.includes("/") || p === ".") return p;
+  try {
+    if (statSync(p).isDirectory()) return p;
+  } catch { /* not a path */ }
+  return ".";
 };
 
 try {
@@ -76,10 +86,49 @@ try {
     const root = rootAt(0);
     const filter = pos.find((p) => p !== root);
     const rows = ensureState(root).graph.anchors
-      .map((a) => `${a.kind}\t${a.id}\t${a.file}:${a.line}`)
-      .filter((r) => !filter || r.includes(filter))
+      .map((a) => `${a.implicit ? "△" : " "}\t${a.kind}\t${a.id}\t${a.file}:${a.line}`)
+      .filter((r) => (!filter || r.includes(filter)) && (!flags.has("discovered") || r.startsWith("△")))
       .sort();
     out = rows.join("\n");
+  } else if (cmd === "rules") {
+    const root = rootAt(0);
+    const st = ensureState(root);
+    const sigs = aggregateFiles(Object.fromEntries(Object.entries(st.facts).map(([k, v]) => [k, v.sigs])));
+    const promoted = promote(sigs, DEFAULT_PACK);
+    if (flags.has("adopt") && promoted.length) {
+      const { mkdirSync, writeFileSync, readFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      mkdirSync(join(root, ".fovea"), { recursive: true });
+      const rulesFile = join(root, ".fovea", "rules.json");
+      let existing = { rules: [] as unknown[] };
+      try { existing = JSON.parse(readFileSync(rulesFile, "utf8")); } catch { /* new */ }
+      const stamp = promoted.map((r) => ({
+        id: r.id.slice("implicit:".length),
+        langs: r.langs,
+        pattern: r.patterns[0],
+        methods: r.methods,
+        kind: r.kind,
+      }));
+      existing.rules = [...existing.rules, ...stamp];
+      writeFileSync(rulesFile, JSON.stringify(existing, null, 2) + "\n");
+      out = `wrote ${stamp.length} discovered rule(s) to .fovea/rules.json`;
+    } else if (flags.has("sigs")) {
+      out = sigs.filter((s) => s.pathN > 0)
+        .sort((a, b) => posterior(b.pathN, b.n) - posterior(a.pathN, a.n))
+        .map((s) => `${posterior(s.pathN, s.n).toFixed(2)}  ${s.pathN}/${s.n} across ${s.files} files  ${s.key}`)
+        .join("\n");
+    } else if (!promoted.length) {
+      out = "(no unknown shape passes the promotion floor — tier-1/2 coverage is doing fine)";
+    } else {
+      out = promoted.map((r) => JSON.stringify({
+        id: r.id.slice("implicit:".length),
+        langs: r.langs,
+        pattern: r.patterns[0],
+        methods: r.methods.replace(/\(\?i\)/, ""),
+        kind: r.kind,
+        _evidence: `p̂=${r.evidence.posterior.toFixed(2)} (${r.evidence.pathN}/${r.evidence.n} sites, ${r.evidence.files} files)`,
+      })).join("\n");
+    }
   } else {
     console.error(`unknown command: ${cmd}`);
     process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/src/core/anchors.ts

@@ -26,7 +26,8 @@ import type { Anchor } from "./types.js";
 export interface AnchorRule {
   id: string;
   langs: string[];
-  pattern: string;
+  /** Single ast-grep pattern; tier-3 synthesized rules use `patterns` instead. */
+  pattern?: string;
   methods: string; // regex tested against the captured method metavar
   kind: string;
   /**
@@ -39,6 +40,10 @@ export interface AnchorRule {
   verbFrom?: string;
   /** Idiom writes paths mount-relative (Django `path("users/")`): root them. */
   mountRoot?: boolean;
+  /** Synthesized tier-3 rules ship as variant lists (exact arity + trailing $$$H). */
+  patterns?: string[];
+  /** Discovered rules: half hub gravity until a real join upgrades them. */
+  implicit?: boolean;
 }
 
 const HTTP_VERB_RE = /^(?i:get|post|put|delete|patch|head|options)$/;
@@ -59,12 +64,19 @@ const PLACEHOLDER_ONLY = /^(:[A-Za-z_]\w*|\{[A-Za-z_]\w*\}|\[[A-Za-z_]\w*\])$/;
 // Method names that are mounts, not verbs: Django urls, Rails match/root,
 // Spring's umbrella RequestMapping. They anchor as ANY so the hub exists
 // without pretending a verb was declared.
-const NON_VERB_METHODS = new Set(["PATH", "RE_PATH", "URL", "MATCH", "ROOT", "REQUESTMAPPING", "REDIRECT", "RESOURCES"]);
+// Method names that mount a target rather than declare a verb. fetch(url)
+// and redirect targets both resolve to GET; Django urlconfs and Rails mounts
+// accept any verb.
+const METHOD_ALIASES: Record<string, string> = {
+  PATH: "ANY", RE_PATH: "ANY", URL: "ANY", MATCH: "ANY", ROOT: "ANY",
+  REQUESTMAPPING: "ANY", RESOURCES: "ANY", FORWARD: "ANY",
+  FETCH: "GET", REDIRECT: "GET", RESPONDREDIRECT: "GET", REDIRECT_TO: "GET",
+};
 
 const deriveVerb = (method: string): string => {
   let up = method.toUpperCase();
   if (up.endsWith("MAPPING")) up = up.slice(0, -"MAPPING".length); // Spring GetMapping → GET
-  return NON_VERB_METHODS.has(up) ? "ANY" : up;
+  return METHOD_ALIASES[up] ?? up;
 };
 
 export const DEFAULT_PACK: AnchorRule[] = [
@@ -199,6 +211,24 @@ export const DEFAULT_PACK: AnchorRule[] = [
     methods: "^add_url_rule$",
     kind: "route",
   },
+  {
+    // Client fetch with no receiver: fetch("/api/x"). Precision-audited by
+    // discovery (~93% path precision in the next.js clone corpus).
+    id: "fetch-bare",
+    langs: ["TypeScript", "Tsx", "JavaScript"],
+    pattern: "$M($P, $$$H)",  // trailing $$$H absorbs the options bag; zero-arg tail matches fetch("/x") too
+    methods: "^fetch$",
+    kind: "route",
+  },
+  {
+    // Response-side route linkage: ktor respondRedirect("/myfiles") references
+    // an existing route without declaring it. Discovery found it at p̂≈0.81.
+    id: "ktor-respond-redirect",
+    langs: ["Kotlin"],
+    pattern: "$R.$M($P, $$$H)",
+    methods: "^respondRedirect$",
+    kind: "route",
+  },
   {
     id: "rust-router-chain",
     langs: ["Rust"],
@@ -238,7 +268,8 @@ export const extractAnchors = (
           if (p !== undefined && !prefixes.has(pm.file)) prefixes.set(pm.file, unquote(p));
         }
       }
-      for (const m of patternRun(rule.pattern, lang, langFiles, cwd)) {
+      const matchSets = patternRunAll(rule.patterns ?? [rule.pattern!], lang, langFiles, cwd);
+      for (const m of matchSets) {
         const method = m.single.M;
         const pathLike = m.single.P;
         if (!method || !pathLike || !methodRe.test(method)) continue;
@@ -273,6 +304,7 @@ export const extractAnchors = (
           nodeId: enclosing ?? `file:${m.file}`,
           file: m.file,
           line: m.line,
+          ...(rule.implicit ? { implicit: true } : {}),
         });
       }
     }

package/src/core/build.ts

@@ -8,10 +8,11 @@ import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from
 import { tmpdir } from "node:os";
 import { basename, dirname, join as joinPath, posix } from "node:path";
 import { spawnSync } from "node:child_process";
-import { LANG_BY_EXT, isBinaryExt, isConfigFile } from "./astgrep.js";
+import { LANG_BY_EXT, isBinaryExt, isConfigFile, langOf } from "./astgrep.js";
 import { extractCalls, extractImports, extractLiterals, extractSymbols, isTestFile } from "./extract.js";
 import { buildJoinIndex } from "./join.js";
 import { extractAnchors, extractFileRoutes, loadRepoRules } from "./anchors.js";
+import { aggregateFiles, harvestFile, promote, type FileSigs, type SynthesizedRule } from "./discover.js";
 import type { CallSite, Edge, Graph, ImportSite, LiteralSite, NodeRec, SymbolRec } from "./types.js";
 import type { AnchorDraft } from "./anchors.js";
 import { coChangePairs } from "./cochange.js";
@@ -23,9 +24,13 @@ export interface FileFacts {
   calls: CallSite[];
   literals: LiteralSite[];
   anchors: AnchorDraft[];
+  // Tier-3 discovery: per-file histogram of call-shape signatures
+  // (sig -> [totalSites, pathSites]); aggregated repo-wide at load to promote
+  // statistically significant unknown shapes into implicit half-weight rules.
+  sigs?: FileSigs;
 }
 
-const CACHE_VERSION = 5; // bump when extractor semantics change
+const CACHE_VERSION = 6; // bump when extractor semantics change
 const IGNORE_DIRS = new Set([".git", "node_modules", "dist", "vendor", ".venv", "venv", "target", "coverage", ".next", "build", "__pycache__", ".pi", ".pi-fovea", "deps", "_build", ".tox", "Pods"]);
 const MAX_FILES = 24000;
 // Generated dependency manifests are enormous and carry no first-class routes.
@@ -103,8 +108,12 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
   } catch {
     cached = undefined;
   }
-  const { pack: anchorPack, fileRoutes, sha: rulesSha } = loadRepoRules(root);
-  const rulesChanged = cached !== undefined && cached.rulesSha !== rulesSha;
+  const { pack: basePack, fileRoutes, sha: baseRulesSha } = loadRepoRules(root);
+  const anchorPack = [...basePack];
+  // Implicit rules promote AFTER the first fact pass: their evidence lives in
+  // freshly harvested sigs, so the pack can only be finalized once facts exist.
+  let implicitRules: SynthesizedRule[] = [];
+  let rulesSha = baseRulesSha;
   if (cached && (cached.version !== CACHE_VERSION || cached.root !== root)) cached = undefined;
   const facts: Record<string, FileFacts> = {};
   const dirty: string[] = [];
@@ -133,12 +142,31 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
     putByFile(extractImports(code, root), (f, v) => f.imports.push(v));
     putByFile(extractCalls(code, root), (f, v) => f.calls.push(v));
     putByFile(extractLiterals(dirty, root), (f, v) => f.literals.push(v));
+    // Tier-3 harvest: regex histogram of call-shape signatures per file. Cheap
+    // (line scan, no ast-grep) and cached alongside the other facts.
+    for (const f of code) {
+      const lang = langOf(f);
+      if (!lang) continue;
+      let text = "";
+      try { text = readFileSync(joinPath(root, f), "utf8"); } catch { continue; }
+      const sigs = harvestFile(lang, text);
+      if (Object.keys(sigs).length) facts[f]!.sigs = sigs;
+    }
+  }
+  // Tier-3: promote harvested signatures into implicit rules BEFORE anchors
+  // run, and fold their ids into the rules hash so a promotion change rebuilds
+  // anchors exactly like a rules.json edit would.
+  implicitRules = promote(aggregateFiles(Object.fromEntries(Object.entries(facts).map(([k, v]) => [k, v.sigs]))), anchorPack);
+  if (implicitRules.length) {
+    anchorPack.push(...implicitRules);
+    rulesSha = createHash("sha1").update(baseRulesSha).update(JSON.stringify(implicitRules.map((r) => r.id).sort())).digest("hex");
   }
+  const rulesChangedFinal = cached !== undefined && cached.rulesSha !== rulesSha;
   // Anchors need enclosing-symbol resolution. Symbols, imports, calls and
   // literals are rules-independent — when only the rule pack changed, re-run
   // anchor extraction over every code file against cached symbols and keep
   // every other fact (green-node reuse one level up).
-  const anchorTargets = rulesChanged
+  const anchorTargets = rulesChangedFinal
     ? files.filter((f) => !isConfigFile(f))
     : dirty.filter((f) => !isConfigFile(f));
   if (anchorTargets.length) {
@@ -151,7 +179,7 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
     const symsByFile = new Map<string, SymbolRec[]>();
     for (const rel of anchorTargets) {
       symsByFile.set(rel, facts[rel]?.symbols.length ? facts[rel]!.symbols : (cached?.facts[rel]?.symbols ?? []));
-      if (rulesChanged) facts[rel] && (facts[rel]!.anchors = []);
+      if (rulesChangedFinal) facts[rel] && (facts[rel]!.anchors = []);
     }
     const enclosingId = (file: string, line: number): string | undefined => {
       const syms = symsByFile.get(file) ?? [];
@@ -391,13 +419,18 @@ export const assembleGraph = (root: string, files: string[], facts: Record<strin
   for (const [label, sites] of draftsByLabel) {
     const first = sites[0]!;
     const filesOf = [...new Set(sites.map((s) => s.file))];
-    anchors.push({ id: label, kind: first.kind, label: sites.length > 1 ? `${label} · ${sites.length} sites` : label, nodeId: first.nodeId, file: first.file, line: first.line });
+    // A hub is implicit only when EVERY site came from a discovered rule — a
+    // match by any real rule upgrades it back to first-class instantly.
+    const hubImplicit = sites.every((s) => s.implicit === true);
+    anchors.push({ id: label, kind: first.kind, label: sites.length > 1 ? `${label} · ${sites.length} sites` : label, nodeId: first.nodeId, file: first.file, line: first.line, ...(hubImplicit ? { implicit: true } : {}) });
     const idx = addNode(nodes, seen, {
       id: `anchor:${label}`, name: label, kind: "anchor", file: first.file, line: first.line,
-      sig: sites.length > 1 ? `${label} (${sites.length} sites)` : label, lang: "anchor",
+      sig: `${hubImplicit ? "(△ discovered) " : ""}${sites.length > 1 ? `${label} (${sites.length} sites)` : label}`, lang: "anchor",
     });
     (byFile.get(first.file) ?? byFile.set(first.file, []).get(first.file)!).push(idx);
-    const w = 1 / Math.sqrt(sites.length);
+    // Tier-3 hubs prove themselves at half conductance; a later literal join
+    // against a first-class hub can still warm them via the channel edges.
+    const w = (hubImplicit ? 0.5 : 1) / Math.sqrt(sites.length);
     for (const s of sites) {
       const handler = seen.get(s.nodeId) ?? fileIdx.get(s.file)!;
       pushEdge(idx, handler, "anchors", w);

package/src/core/discover.ts

@@ -0,0 +1,188 @@
+// Tier-3: autonomy for route extraction. The static pack catches known port
+// shapes; this module watches the literal channel for shapes the pack does NOT
+// declare, promotes statistically significant ones into synthesized "implicit"
+// rules at half hub gravity, and lets confirmatory joins against real hubs
+// upgrade them to full first-class weight.
+//
+// The promotion statistic is a per-argument conditional: given the string arg
+// at position i of call-shape (lang·shape·callee), how often does it classify
+// as a path? A Jeffreys-smoothed posterior with global floors decides — not raw
+// frequency, under which chaff like `assertEquals(...)` dwarfs every real shape.
+//
+// Corpus audit (8 repos, 183 sigs n≥4): junk bands sit below p̂≈0.27, real
+// shapes above p̂≈0.75 — the 0.55 line is a cliff, not a gradient.
+//
+// Harvest is line-regex over source text — no ast-grep pass needed. Per file we
+// store a compact signature histogram (sig -> [sites, pathSites]); promotions
+// aggregate across ALL files of the repo, so a dependency update or a style
+// drift can only flip a marginal signature when its repo-wide evidence moves.
+
+import { classifyLiteral } from "./join.js";
+
+export type Shape = "recv" | "bare" | "dec";
+
+// Compacted per-file histogram: sigKey -> [totalSites, pathSites]
+export type FileSigs = Record<string, [number, number]>;
+
+const QUOTED = /^[rbfuRBFU]{0,3}(["'`])([\s\S]*)\1$/;
+const unquote = (s: string): string | undefined => {
+  const m = QUOTED.exec(s.trim());
+  return m ? m[2] : undefined;
+};
+
+// Line-local call scan: grabs the callee shape (recv chain, bare, decorator)
+// and the raw arg list of every `X(...)` on the line. Multi-line calls still
+// land because route strings overwhelmingly sit on the call's first line.
+const CALL_LINE_RE = /(?<at>@)?(?<recv>(?:[A-Za-z_$][\w$]*\.)+)?(?<method>[A-Za-z_$][\w$]*)\s*\((?<args>[^()]*)\)/g;
+const STRING_RE = /([rbfuRBFU]{0,3})(["'`])((?:\\.|(?!\2)[^\\])*)\2/g;
+
+// Callees that are noise even at 100% precision (env/fs access, string ctors,
+// module loading — dynamic import()/require() hits the path channel but the
+// import edge already covers it, an anchor would double-count the site).
+const CALLEE_DENY = new Set([
+  "join", "resolve", "dirname", "basename", "expand_path",
+  "readFile", "readFileSync", "existsSync", "open", "load", "loads",
+  "import", "require",
+  // String predicates: membership tests hit the path column at high rate but
+  // never refer to routes. (Distinguishing cause from noise is callee-semantic.)
+  "startsWith", "endsWith", "contains", "includes", "equals", "equalsIgnoreCase",
+  "matches", "matchesPattern", "useParams", "matchPath",
+]);
+
+export const harvestFile = (lang: string, text: string): FileSigs => {
+  const sigs: FileSigs = {};
+  for (const line of text.split("\n")) {
+    if (!line.includes("(") || !(line.includes('"') || line.includes("'") || line.includes("`"))) continue;
+    CALL_LINE_RE.lastIndex = 0;
+    let c: RegExpExecArray | null;
+    while ((c = CALL_LINE_RE.exec(line))) {
+      const method = c.groups?.method;
+      if (!method || CALLEE_DENY.has(method)) continue;
+      const shape: Shape = c.groups?.at ? "dec" : c.groups?.recv ? "recv" : "bare";
+      const argsText = c.groups?.args ?? "";
+      if (!argsText) continue;
+      // True argument index of each string literal (split tolerantly on commas).
+      const args = argsText.split(",");
+      let idx = 0;
+      for (const raw of args) {
+        STRING_RE.lastIndex = 0;
+        const sm = STRING_RE.exec(raw);
+        const idxNow = idx++;
+        if (!sm) continue;
+        const lit = sm[3];
+        if (lit === undefined || lit === "") continue;
+        const key = `${lang}|${shape}|${method}|${idxNow}`;
+        const rec = sigs[key] ?? [0, 0];
+        rec[0]++;
+        if (classifyLiteral(lit) === "path") rec[1]++;
+        sigs[key] = rec;
+      }
+    }
+  }
+  return sigs;
+};
+
+export interface SigStats {
+  key: string;
+  lang: string;
+  shape: Shape;
+  callee: string;
+  argIdx: number;
+  n: number;
+  pathN: number;
+  files: number;
+}
+
+export const aggregateFiles = (perFile: Record<string, FileSigs | undefined>): SigStats[] => {
+  const agg = new Map<string, SigStats>();
+  for (const sigs of Object.values(perFile)) {
+    if (!sigs) continue;
+    for (const [key, [n, p]] of Object.entries(sigs)) {
+      const stat = agg.get(key);
+      if (stat) {
+        stat.n += n;
+        stat.pathN += p;
+        stat.files++;
+      } else {
+        const [lang, shape, callee, argIdx] = key.split("|");
+        agg.set(key, { key, lang: lang!, shape: shape as Shape, callee: callee!, argIdx: Number(argIdx), n, pathN: p, files: 1 });
+      }
+    }
+  }
+  return [...agg.values()];
+};
+
+/** Jeffreys-ish posterior: p̂ = (pathN + .5) / (n + 1). */
+export const posterior = (pathN: number, n: number): number => (pathN + 0.5) / (n + 1);
+
+export const MIN_SITES = 4;
+export const MIN_FILES = 2;
+export const MIN_POSTERIOR = 0.55;
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Pattern synthesis per shape and arg position: dummy metavars for the slots
+// the corpus says are not the path, $P at the proven position. Two variants
+// per site — exact arity and with a trailing $$$H absorb — because some
+// dialects only match with explicit tail holes (Python `$X, $P, $$$H`).
+export interface SynthesizedRule {
+  id: string;
+  langs: string[];
+  patterns: string[];   // patternRunAll variants
+  methods: string;
+  kind: string;
+  implicit: true;
+  evidence: { n: number; pathN: number; files: number; posterior: number };
+}
+
+export const synthesize = (s: SigStats): SynthesizedRule | undefined => {
+  const slots: string[] = [];
+  for (let i = 0; i <= s.argIdx; i++) slots.push(i === s.argIdx ? "$P" : `$X${i}`);
+  const inner = slots.join(", ");
+  let variants: string[];
+  switch (s.shape) {
+    case "recv": variants = [`$R.$M(${inner})`, `$R.$M(${inner}, $$$H)`]; break;
+    case "bare": variants = [`$M(${inner})`, `$M(${inner}, $$$H)`]; break;
+    case "dec":  variants = [`@$M(${inner})`, `@$M(${inner}, $$$H)`]; break;
+  }
+  return {
+    id: `implicit:${s.lang.toLowerCase()}:${s.shape}:${s.callee}:${s.argIdx}`,
+    langs: [s.lang],
+    patterns: variants,
+    methods: `^(?i:${escapeRe(s.callee)})$`,
+    kind: "route",
+    implicit: true,
+    evidence: { n: s.n, pathN: s.pathN, files: s.files, posterior: posterior(s.pathN, s.n) },
+  };
+};
+
+// Shape-shape compatibility: a discovery is only NEW when no existing rule
+// already binds the callee with a compatible pattern shape in that language.
+// e.g. Java's @GetMapping is in the pack, so java:dec:GetMapping promotes nothing.
+const shapeCompatPatterns: Record<Shape, RegExp> = {
+  recv: /^\$R\.\$M\(/,
+  bare: /^\$M[(\s]/,
+  dec: /^@\$(R\.)?M\(/,
+};
+
+const isCovered = (sig: SigStats, pack: Array<{ langs: string[]; methods: string; pattern?: string; patterns?: string[] }>): boolean => {
+  const mre = (methods: string, callee: string): boolean => new RegExp(methods.replace(/^\^\(\?i\)/, "^(?i:")).test(callee);
+  return pack.some((r) => {
+    if (!r.langs.includes(sig.lang)) return false;
+    if (!mre(r.methods, sig.callee)) return false;
+    const pats = r.patterns ?? (r.pattern ? [r.pattern] : []);
+    return pats.some((p) => shapeCompatPatterns[sig.shape].test(p));
+  });
+};
+
+export const promote = (sigs: SigStats[], pack: Array<{ id: string; langs: string[]; methods: string; pattern?: string; patterns?: string[] }> = []): SynthesizedRule[] => {
+  const out: SynthesizedRule[] = [];
+  for (const s of sigs) {
+    if (s.n < MIN_SITES || s.files < MIN_FILES) continue;
+    if (posterior(s.pathN, s.n) < MIN_POSTERIOR) continue;
+    if (isCovered(s, pack)) continue;
+    const r = synthesize(s);
+    if (r) out.push(r);
+  }
+  return out;
+};

package/src/core/join.ts

@@ -14,7 +14,7 @@ export interface LitOccurrence { node: number; line: number; file: string; }
 
 export interface JoinEdge { a: number; b: number; w: number; }
 
-const PLACEHOLDER_SEGMENT = /^(?::[^/]+|\{[^}/]*\}|\$\{[^}/]*\}|<[^/>]+>|\*+)$/;
+const PLACEHOLDER_SEGMENT = /^(?::[^/]+|\{[^}/]*\}|\$\{[^}/]*\}|\$[A-Za-z_]\w*|<[^/>]+>|\*+)$/; // $x = Kotlin template shorthand
 const WORD_RE = /^[A-Za-z][\w$.\-]{6,63}$/;
 const URLISH_RE = /^(?:https?|wss?):\/\/[^/]+/;
 

package/src/core/sync.ts

@@ -1,8 +1,10 @@
 // Turn-sync: the default-on feedback loop the extension was built around.
 // After each assistant turn, if the repo's facts version drifted ANY edit
-// re-syncs, regardless of whether it came through pi's edit/write tools or
-// a shell heredoc — the verdict is green (UI-only) or red (model-visible,
-// budget-capped):
+// re-syncs, regardless of the mutation path — pi's edit/write tools, a
+// fabric_exec inner pi.edit, a bash heredoc, a subagent run, or an editor
+// save outside the session all land the same way, because drift is measured
+// by diffing the baseline's content hashes against the current facts instead
+// of trusting tool events or git.
 //
 //   red  = route anchors appeared/vanished   (structural feature churn)
 //       OR warm undisclosed files >= warmFileThreshold  (unseen blast radius)
@@ -11,13 +13,17 @@
 // The first sync of a session only establishes the baseline (never red).
 // Baselines reset on /new and /fork alongside fovea sessions.
 
-import { ensureState, impact, uncommittedFiles } from "./ops.js";
+import { ensureState, impact } from "./ops.js";
 import type { RepoState } from "./ops.js";
 import { getSession } from "./session.js";
 
 interface SyncBaseline {
   version: string;
   anchors: Set<string>;
+  /** file -> content sha1 at baseline. Diffing this against the current facts
+   * yields the exact changed-file set for any mutation path — no dependence
+   * on which tool executed the write, nor on git. */
+  shas: Map<string, string>;
   /** Steady-state warmth recorded on the most recent sync. undefined = "the
    * first drift after baseline calibrates the neighborhood instead of
    * escalating" — a file list appears after that calibration sync. */
@@ -29,7 +35,8 @@ const baselines = new Map<string, SyncBaseline>();
 export const resetSyncBaselines = (): void => baselines.clear();
 
 export interface SyncParams {
-  /** Files the turn is known to have touched. Empty + drift => git fallback. */
+  /** Optional drift hints (e.g. files touched by pi's edit/write tools this
+   * turn). Unioned into the warmth seeds; never the source of truth. */
   files?: string[];
   budget: number;
   warmFileThreshold: number;
@@ -48,6 +55,7 @@ export interface SyncOutcome {
 const snapshot = (state: RepoState): SyncBaseline => ({
   version: state.version,
   anchors: new Set(state.graph.anchors.map((a) => a.id)),
+  shas: new Map(Object.entries(state.facts).map(([f, x]) => [f, x.sha1])),
 });
 
 export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOutcome => {
@@ -64,10 +72,14 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
     };
   }
 
-  // Version drifted: measure what moved.
-  const current = new Set(state.graph.anchors.map((a) => a.id));
-  const added = [...current].filter((id) => !prev.anchors.has(id));
-  const removed = [...prev.anchors].filter((id) => !current.has(id));
+  // Version drifted: measure what moved. Implicit (tier-3 discovered) hubs
+  // churn is reported but NEVER escalates alone — hypotheses with no first-class
+  // backing don't get to wake the model with a red verdict.
+  const current = new Map(state.graph.anchors.map((a) => [a.id, a.implicit === true]));
+  const currentIds = new Set(current.keys());
+  const added = [...currentIds].filter((id) => !prev.anchors.has(id));
+  const removed = [...prev.anchors].filter((id) => !currentIds.has(id));
+  const newlyImplicit = added.filter((id) => current.get(id));
 
   const session = getSession(root);
   const disclosedFiles = new Set<string>();
@@ -76,8 +88,15 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
     if (at >= 0) disclosedFiles.add(id.slice(at + 1));
   }
 
-  let files = (params.files ?? []).filter((f) => state.graph.byFile.has(f));
-  if (!files.length) files = uncommittedFiles(root).filter((f) => state.graph.byFile.has(f));
+  // Exact change set: facts whose content hash moved since the baseline.
+  // Deleted files can't warm anything (absent from the graph) but ride along
+  // in details for observability.
+  const hinted = (params.files ?? []).filter((f) => state.graph.byFile.has(f));
+  const changed = Object.keys(state.facts).filter(
+    (f) => prev.shas.get(f) !== state.facts[f]!.sha1 && state.graph.byFile.has(f),
+  );
+  const deleted = [...prev.shas.keys()].filter((f) => !(f in state.facts));
+  const files = [...new Set([...hinted, ...changed])];
 
   let warmNow: Set<string> = new Set();
   let warmNew: string[] = [];
@@ -92,17 +111,18 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
 
   baselines.set(root, { ...snapshot(state), warmed: warmNow });
 
-  const red = added.length + removed.length > 0 || warmNew.length >= Math.max(1, params.warmFileThreshold);
+  const red = (added.length - newlyImplicit.length) + removed.length > 0 || warmNew.length >= Math.max(1, params.warmFileThreshold);
   if (!red) {
     return {
       structural: true, red: false, tokens: 0,
-      details: { version: state.version, anchorsDelta: added.length - removed.length, warmNew: warmNew.length },
+      details: { version: state.version, anchorsDelta: added.length - removed.length, warmNew: warmNew.length, deletedFiles: deleted },
     };
   }
 
   const lines: string[] = [];
   lines.push(`fovea sync · v ${state.version} · edit cascade did not stay local`);
-  for (const id of added.slice(0, 12)) lines.push(`  ⚑=new ${id}`);
+  for (const id of added.filter((a) => !newlyImplicit.includes(a)).slice(0, 12)) lines.push(`  ⚑=new ${id}`);
+  for (const id of newlyImplicit.slice(0, 6)) lines.push(`  △ newly discovered hub ${id}`);
   for (const id of removed.slice(0, 12)) lines.push(`  ⚑-removed ${id}`);
   if (warmNew.length) {
     lines.push(`  newly warm undisclosed files (revisit with fovea_focus):`);
@@ -111,6 +131,6 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
   const text = lines.join("\n");
   return {
     structural: true, red: true, text, tokens: Math.ceil(text.length / 4),
-    details: { version: state.version, added, removed, warmNew },
+    details: { version: state.version, added, removed, warmNew, deletedFiles: deleted },
   };
 };

package/src/core/types.ts

@@ -48,6 +48,7 @@ export interface Anchor {
   nodeId: string;    // handler symbol node id, or enclosing node
   file: string;
   line: number;
+  implicit?: boolean; // tier-3 discovered shape: half hub gravity, shown with △
 }
 
 export interface Graph {

package/src/index.ts

@@ -38,11 +38,11 @@ export default function fovea(pi: ExtensionAPI) {
     }
   });
 
-  // Turn-sync loop. Edits discovered via the files touched by tool calls in
-  // the turn's results; the graph drifts only when content actually changed,
-  // so pure conversation turns exit early at zero cost.
-  // Per-turn mutation accumulator. tool_execution_start carries typed args,
-  // so edit/write paths are tracked without parsing completed tool messages.
+  // Turn-sync loop. The tracker below is a hint accumulator only: pi's
+  // edit/write tool starts give the warmth pass a head start, but sync relies
+  // on content-hash drift, so identical detection covers fabric_exec inner
+  // pi.edit calls, bash mutations, subagents, and out-of-band editor saves.
+  // Pure conversation turns exit at zero cost through the version fast path.
   let turnFiles: string[] = [];
   pi.on("turn_start", () => {
     turnFiles = [];