pi-fovea 0.26.0 → 0.28.0

package/README.md

@@ -150,101 +150,97 @@ npm i -g pi-fovea      # or: bun add -g pi-fovea, bun add -g pi-fovea
 
 From a checkout, `bun run fovea` runs the live source via `tsx`, and `bun run build:cli` rebuilds `dist/cli.mjs` (the `prepack` hook keeps the published bundle in sync).
 
-## Large workspaces and startup
-
-Indexing runs in the background at `session_start`. Your first prompt never
-waits for ast-grep, hashing, or graph assembly. A cold sync hook reports the
-progress. Later calls reuse the same shared build.
-
-A non-Git umbrella directory treats each nested `.git` directory or worktree
-marker as a closed project boundary — until you work in it. The first edit
-hint (or observed drift) inside a nested clone enrolls it into the umbrella
-graph from then on: progressive disclosure, one project at a time, persisted
-with the fact cache so restarts restore your working set. The same rule covers
-submodules and embedded checkouts in Git roots: their contents join the graph
-as `<submodule>/<path>` the first time something inside changes — porcelain
-reports inner drift collapsed to the boundary, which enrolls it automatically —
-and a removed project un-enrolls without leaving orphan facts. Enrollment expands
-index coverage only: with the default session-local sync scope, a sibling project
-can join the umbrella graph and cache without steering conversations that never
-entered it. Every fovea_* tool still accepts a `root` for a full, immediate map
-of one project. `FOVEA_MAX_FILES` caps the merged listing either way.
-Cold runs stay bounded through streamed JSONL cache I/O, 64-file extraction
-batches, adaptive ast-grep chunk splitting, and a two-root resident LRU. The
-limits accept environment overrides:
+## Many projects, one conversation
+
+Your Pi cwd can be a parent folder, a launcher, or unrelated to the work.
+Successful native/Fabric `pi.*` reads, edits, writes, and searches automatically
+select their containing project. Discovery walks bounded ancestors—not siblings
+or the whole filesystem—and accepts only successful structured/literal access.
+Startup and idle hooks do not index an otherwise-unselected launch directory.
+
+**32 observed roots; two hot graphs.** The recency ring refreshes on access.
+Project 33 retires the least recently used root instead of failing. Canonical
+symlink aliases share identity; linked worktrees stay independent. Each root has
+its own heat, attention, semantic baseline, and provenance. Retirement is an
+explicit observation gap, never a clean verdict. Re-entry baselines anew.
+
+```ts
+await pi.read({ path: "/projects/service/src/handler.ts", offset: 1, limit: 40 });
+// Access alone enrolls the project; an unrooted call still answers about cwd.
+await extensions.fovea_focus({ root: "/projects/service", query: "src/handler.ts", maxTokens: 1024 });
+// An explicit root selects any exact directory, including umbrella scopes.
+await extensions.fovea_focus({ root: "../other", query: "entry", maxTokens: 512 });
+```
+
+- Omitted analysis roots use the session cwd's own project—the nearest `.git` or
+  manifest, else the cwd itself—never the last selected project, so an unrooted
+  call cannot answer about a sibling repository. Contour keeps the recency ring
+  as a fallback for a coordinator cwd, where a review needs a Git worktree.
+  Explicit `root` resolves against **the tool context's cwd**, not process cwd
+  or the previous root. Parallel coordinators should supply it. Native paths
+  remain cwd-relative; neither Fovea nor Contour changes cwd. Results carry
+  `details.root`, `observedRoots`, `workspace` (capacity/retirements), and
+  `agentOrigin`.
+- Enrollment happens after success, not before permission checks. Failed or
+  blocked calls enroll nothing. Automatic discovery excludes broad/system,
+  private, dependency, and generated locations. It does not parse arbitrary
+  programs or trust output text. Literal shell cwd forms are supported; opaque
+  programs and remote filesystems need explicit coordination.
+- Indexing expands a successful path to a project scope. This is **not a sandbox
+  or a project-trust grant**. `.pi/fovea.json` is honored only for the exact
+  canonical trusted `ctx.cwd`; parent/sibling trust does not propagate. Existing
+  declarative `.fovea/rules.json` extraction rules are unchanged. Hosts with
+  finer-grained analysis permissions must enforce them separately.
+- The first access is a new observation boundary. A first write may already be
+  included in it; Fovea does not invent its prior delta or authorship. Contour
+  still compares that project's patch with Git. Subsequent focus calls do not
+  consume pending drift. Focus/file-seeded impact establishes attention before
+  opaque shell edits; hintless changes in enrolled roots remain detectable.
+- Native augment grep follows the physical owner of its actual search path,
+  never an unrelated active graph. No-path native grep still searches cwd.
+  Legacy replace-mode bare graph queries use the cwd project; native options and
+  fallbacks retain cwd semantics.
+- Sync spends one shared context allowance on relevant messages, including root
+  labels and retirement notices—not an equal slice for every quiet root. Cold
+  unchanged Git roots do not rebuild graphs, and cold probes stay off the
+  blocking before-agent hook. Numerical paging retains logical focus/attention.
+- Branch-local bounded root snapshots survive compaction, reload, resume, fork,
+  and tree navigation. Semantic baselines and trust are not restored. `/fovea
+  reset` clears the ring; `/fovea status` reports the ring, capacity, and the manual default. The CLI
+  stays stateless. Fovea and Contour exchange session-qualified target hints,
+  not heat, source content, trust, or mutation authorship.
+
+### Bounded indexing
+
+Explicit umbrella graphs retain progressive nested-repository/submodule
+boundaries: projects join that graph as their contents are worked in, subject to
+`FOVEA_MAX_FILES`. Automatic project selection does not create an umbrella graph
+just because unrelated projects share a parent directory. Cold extraction keeps
+streamed JSONL caches, 64-file batches, adaptive ast-grep chunk splitting, and
+bounded I/O/process concurrency.
 
 | Variable | Default | Meaning |
 | --- | :---: | --- |
+| `FOVEA_MAX_ROOTS` | `32` | observed recency ring, clamped to 1–32 |
+| `FOVEA_CACHE_ROOTS` | `2` | hot graph/fact/vector cache residency, separate from observation |
 | `FOVEA_MAX_FILES` | `8000` | maximum indexed files in one graph |
 | `FOVEA_MAX_FILE_BYTES` | `1048576` | maximum bytes extracted from one source file |
-| `FOVEA_MAX_ROOTS` | `2` | observed execution roots and resident graph, fact, session, sync, and root-metadata caches |
-| `FOVEA_SPAWN_CONCURRENCY` | `3` | concurrent ast-grep/git child processes (ast-grep parallelizes parsing inside each process; values above ~4 rarely help) |
-| `FOVEA_MEMORY_HALF_LIFE_HOURS` | `48` | wall-clock half-life of the per-node sync memory (charged cascade warmth) |
+| `FOVEA_SPAWN_CONCURRENCY` | `3` | concurrent ast-grep/Git subprocesses |
 | `FOVEA_IO_CONCURRENCY` | `32` | concurrent file stat/read operations |
-| `FOVEA_GIT_UNTRACKED_CACHE` | enabled | set to `0` to disable the native Git untracked-directory cache requested by freshness probes |
+| `FOVEA_MEMORY_HALF_LIFE_HOURS` | `48` | wall-clock half-life of charged cascade memory |
+| `FOVEA_GIT_UNTRACKED_CACHE` | enabled | set `0` to disable Git's native untracked-directory cache |
 | `FOVEA_MAX_SUBMODULE_DEPTH` | `4` | recursion cap for nested submodules |
 
-Freshness probes still consult Git on every call; there is no new time-based shortcut. One porcelain-v2 status supplies both HEAD and changes, with a legacy fallback. At a verified worktree root, Fovea requests Git's native untracked-directory cache and omits the redundant dot pathspec that prevents its use. Subroots and Git environment overrides keep their explicit path scope. This can update Git index metadata, but does not change Git configuration files. Set `FOVEA_GIT_UNTRACKED_CACHE=0` to opt out; `GIT_OPTIONAL_LOCKS=0` can also prevent cache updates. Dirty files, new directories, ignore changes, and repository-boundary changes still go through freshness checks.
-
-Files over the size cap keep their place in the model's view of the repo.
-Failed extractions do the same. You find both in `/fovea status` and in tool
-details.
-
-## Explicit project/worktree continuity (Rakazo)
-
-The extension's existing four graph tools are the headless binding API; no new
-host event or trust flag is required:
-
-```ts
-await extensions.fovea_focus({ root: "../project-b", query: "src/handler.ts", maxTokens: 1024 });
-// Baseline is ready before this resolves (unless target sync is disabled).
-// Native tools still use the host cwd: use absolute paths or cwd-relative paths.
-await pi.edit({ path: "../project-b/src/handler.ts", old: "before", new: "after" });
-await extensions.fovea_dwell({ maxTokens: 512 }); // last bound root
-```
+Root-discovery metadata is coalesced and TTL-cached; it never certifies source
+freshness. Git status/content hashes and bounded manifest/boundary sweeps remain
+the drift oracle, including dirty-to-clean reverts. Local Git analysis disables
+fsmonitor and remote/lazy fetching. Native untracked caching can still update
+Git **index metadata**, not Git configuration; opt out with
+`FOVEA_GIT_UNTRACKED_CACHE=0` or `GIT_OPTIONAL_LOCKS=0`.
 
-- `root` resolves against **the tool context's cwd**, not process cwd or the last
-  binding. Real paths unify symlink aliases; linked Git worktrees remain distinct
-  even when they share HEAD and a common Git directory. Roots are exact directory
-  scopes, not automatically promoted to Git toplevels.
-- Cwd is the startup/fallback observation target. After a graph call binds a root,
-  hooks inspect only the bound set. Bind each project you want observed; an
-  alternate binding does not keep an otherwise-unselected umbrella cwd active.
-  Calls without `root` use the last binding. Parallel coordinators should always
-  supply `root`; enrollment is serialized in invocation order. Results include
-  canonical `details.root` and sorted `details.observedRoots`.
-- A first binding establishes that target's semantic baseline before edits can
-  follow. Subsequent focus calls do not consume pending drift. Before-prompt and
-  post-turn sync compare every bound target, including hintless shell/Fabric/editor
-  changes. Attention remains target-local: focus a file/symbol or use
-  `fovea_impact({ root, files: ["src/file.ts"], includeUncommitted: false })` before
-  a headless mutation to enter its scope. Ordinary path events never enroll a new
-  root; they route to the most specific enrolled physical owner.
-- Native read/edit/write/search paths **do not change cwd**. Augment-mode grep
-  attaches only the graph of the enrolled owner of its actual cwd-relative or
-  absolute search path. No-path native grep still searches cwd; it never appends
-  an unrelated alternate graph. In legacy replace mode, bare graph queries and
-  their miss fallback use the bound root; explicit native options retain cwd
-  semantics. Each target's grep mode is checked independently.
-- Binding is an explicit request to index a directory, **not a sandbox or a trust
-  grant**. Rakazo must authorize tool arguments itself. `.pi/fovea.json` is loaded
-  only when that exact canonical target equals `ctx.cwd` and the context is
-  trusted. Parent/sibling trust never authorizes it; alternate targets use global
-  defaults. To honor a target's project config, run it in its own trusted Pi
-  context. Config cache keys include trust and agent directory. Existing
-  target-local declarative `.fovea/rules.json` extraction rules are unchanged.
-- All roots share one per-hook `sync.budget` allowance from the session cwd's
-  effective config, divided evenly and capped again by each target's budget;
-  root labels count toward that allowance. Hidden targets remain hidden (a mixed
-  pre-prompt aggregate is hidden). Graph calls keep their individual `maxTokens`.
-  Enrollment is capped by `FOVEA_MAX_ROOTS` (default 2); excess roots fail before
-  indexing rather than silently losing a baseline. Set this before startup for
-  larger coordinated runs.
-- `/fovea status` reports the bound root and observed count. `/fovea reset`,
-  shutdown, new/resume/fork/reload clear bindings and conversation baselines;
-  reusable content facts remain cached. Rebind after session replacement.
-  The standalone CLI remains stateless; these continuity semantics belong to
-  the Pi extension lifecycle.
+Oversized files and failed extractions remain visible coverage gaps in status
+and tool details. See the [full workspace contract and shared API](docs/workspace.md)
+for boundaries, persistence, scheduling, and remaining limitations.
 
 ## Turn sync
 
@@ -537,7 +533,8 @@ Exact contract topology: **Protocol Buffers (`.proto`) and GraphQL (`.graphql`,
 
 ```sh
 bun install
-bun run check        # typecheck + full vitest suite + knip
+bun run check:fast   # typecheck + tests your working tree affects
+bun run test:smoke   # curated scan-to-render floor, seconds
 bun run bench        # rate–distortion and refresh bench against ../pi-fabric
 bun run bench tests/fixtures/mini  # self-contained smoke run
 ```
@@ -560,7 +557,7 @@ disk-warm target builds are single samples; three-sample refresh p95s are only
 smoke diagnostics. The outline gets no more tokens than Fovea actually used.
 `fidelity@16k` measures disclosed node IDs against a finite larger Fovea response,
 **not independently labeled relevance**. Timing results are informational, never
-a flaky CI gate; deterministic equivalence tests run in `bun run check`.
+a flaky CI gate; deterministic equivalence tests run in the change-scoped selection (`bun run test:changed`).
 The bench clears the target's disposable facts cache to measure cold loading,
 but edits only temporary fixture copies.
 

package/dist/cli.mjs

@@ -21,7 +21,8 @@ var envInt = (name, dflt, min, max) => {
 };
 var SPAWN_CONCURRENCY = envInt("FOVEA_SPAWN_CONCURRENCY", 3, 1, 32);
 var IO_CONCURRENCY = envInt("FOVEA_IO_CONCURRENCY", 32, 4, 512);
-var ROOT_CACHE_LIMIT = envInt("FOVEA_MAX_ROOTS", 2, 1, 32);
+var OBSERVED_ROOT_LIMIT = envInt("FOVEA_MAX_ROOTS", 32, 1, 32);
+var ROOT_CACHE_LIMIT = envInt("FOVEA_CACHE_ROOTS", 2, 1, 32);
 var mapLimit = async (items, limit, fn) => {
   const out = new Array(items.length);
   let next = 0;
@@ -73,8 +74,10 @@ var gitOut = async (root, args, opts = {}) => spawnGate.run(
   () => new Promise((resolve5) => {
     execFile(
       "git",
-      ["-C", root, ...args],
+      ["-c", "core.fsmonitor=false", "-C", root, ...args],
       {
+        // Local analysis must not run repository hooks or lazily fetch objects.
+        env: { ...process.env, GIT_NO_LAZY_FETCH: "1", GIT_ALLOW_PROTOCOL: "", GIT_TERMINAL_PROMPT: "0" },
         encoding: "utf8",
         timeout: opts.timeout ?? GIT_TIMEOUT,
         maxBuffer: opts.maxBuffer ?? 64 * 1024 * 1024
@@ -112,7 +115,7 @@ var gitPrefix = async (root) => {
   const prefix = out.trim().replace(/\\/g, "/");
   gitPrefixes.delete(root);
   gitPrefixes.set(root, prefix);
-  while (gitPrefixes.size > ROOT_CACHE_LIMIT) gitPrefixes.delete(gitPrefixes.keys().next().value);
+  while (gitPrefixes.size > OBSERVED_ROOT_LIMIT) gitPrefixes.delete(gitPrefixes.keys().next().value);
   return prefix;
 };
 var gitRelativePath = (path, prefix) => {
@@ -855,7 +858,7 @@ var getSession = (root) => {
     tkKey: ""
   };
   sessions.set(root, s);
-  while (sessions.size > ROOT_CACHE_LIMIT) {
+  while (sessions.size > OBSERVED_ROOT_LIMIT) {
     const oldest = sessions.keys().next().value;
     sessions.delete(oldest);
   }
@@ -876,6 +879,10 @@ var syncScopeForPath = (root, input) => {
 var observeSessionPaths = (root, paths) => {
   const session = getSession(root);
   for (const path of paths) {
+    if (path === ".") {
+      session.syncScopes.add(".");
+      continue;
+    }
     const scope = syncScopeForPath(root, path);
     if (scope) session.syncScopes.add(scope);
   }
@@ -892,6 +899,13 @@ var clearSessionFocus = (session) => {
   session.tk = [];
   session.tkKey = "";
 };
+var retainSessionVectors = (root) => {
+  const others = [...sessions.values()].reverse().filter((s) => s.root !== root && s.tk.length);
+  for (const session of others.slice(Math.max(0, ROOT_CACHE_LIMIT - 1))) {
+    session.tk = [];
+    session.tkKey = "";
+  }
+};
 
 // src/core/basins.ts
 var MAX_BASINS = 12;
@@ -5500,6 +5514,7 @@ var focus = async (root, query, budget, options = {}, ensured) => {
   }
   session.generation = state.generation;
   if (session.tkKey !== key) {
+    retainSessionVectors(root);
     session.tk = chebyshevVectors(state.csr, seedVector(g.nodes.length, seeds), chooseOrder(session.t));
     session.tkKey = key;
   }
@@ -5544,7 +5559,7 @@ var dwell = async (root, factor, budget) => {
   const g = state.graph;
   const session = getSession(root);
   const B = clampBudget(budget, 512);
-  if (session.seeds.length && (session.generation !== state.generation || session.tk[0]?.length !== g.nodes.length)) {
+  if (session.seeds.length && (session.generation !== state.generation || session.tk.length > 0 && session.tk[0]?.length !== g.nodes.length)) {
     const previousGeneration = session.generation || "unknown";
     clearSessionFocus(session);
     const text = `fovea dwell: focus expired because the graph changed (${previousGeneration} \u2192 ${state.generation}). Call fovea_focus again; no stale vector was applied.`;
@@ -5558,6 +5573,11 @@ var dwell = async (root, factor, budget) => {
     const text = "fovea dwell: no focus yet. Call fovea_focus with a symbol, feature id, route, or file first; dwell then deepens that field.";
     return { text, tokens: tokenEstimate(text), details: { seeds: 0, ...extractionDetails(state) } };
   }
+  if (!session.tk.length) {
+    retainSessionVectors(root);
+    session.tk = chebyshevVectors(state.csr, seedVector(g.nodes.length, session.seeds), chooseOrder(session.t));
+    session.tkKey = session.focusKey;
+  }
   const from = session.t;
   const to = Math.min(64, from * Math.max(1.2, factor ?? 2));
   session.t = to;

package/docs/workspace.md

@@ -0,0 +1,35 @@
+# Roaming workspaces
+
+The conversation is a coordinator. A project root is an independent observation domain, not the agent's process directory and not a common-ancestor graph joining unrelated repositories. Each domain keeps its own heat, attention, semantic baseline, and provenance. Contour's HEAD/index comparisons are also root-local; diffusion never crosses projects merely because they share a parent directory.
+
+## Enrollment and boundaries
+
+Successful `read`, `edit`, `write`, `grep`, `find`, and `ls` results provide structured paths. Literal shell cwd hints (`cwd`, `cd <literal> && …`, or `git -C <literal> …`) also qualify after success. Fabric's inner `pi.*` calls replay the native permission/result lifecycle and follow the same rule. We do not evaluate shell programs, inspect output text, expand variables/globs/substitutions, follow remote namespaces, or parse arbitrary `fabric_exec` source.
+
+Discovery resolves physical paths and walks at most 64 ancestors. The nearest Git marker (directory or worktree `.git` file) wins; otherwise a recognized manifest, or the containing directory of a supported source file, is the conservative fallback. It does not enumerate sibling projects, run Git, or load project configuration. Lookups are coalesced and held in a 256-entry, one-second metadata cache. System-wide/home/private/dependency/generated paths are excluded from automatic discovery. This cache is **not** a source-freshness oracle.
+
+Indexing expands the accessed file's scope to its containing project. Enrollment is not a sandbox, per-file ACL enforcement, or a project-configuration trust grant. A permission denial must happen before the underlying operation; failed or blocked results do not enroll anything. Hosts requiring finer-than-project analysis authorization must enforce it separately. Analysis Git commands disable fsmonitor, lazy fetching, and all transport protocols; missing local objects fail visibly instead of invoking repository-configured helpers or fetching. Explicit graph-tool roots remain available for intentional directory/umbrella scopes; Contour requires a Git worktree.
+
+Native relative paths still resolve from Pi's tool-context cwd. Neither extension calls `process.chdir()`. An omitted manual root is the session cwd's own project — nearest Git marker or manifest, else the cwd itself — never the most recently observed root: Fovea stops at that cwd scope (an umbrella/coordinator directory is the subject, with nested repositories closed until access enrolls them), while Contour falls back to the recency ring because a review needs a Git worktree. Parallel callers should provide an explicit root. Canonical aliases share identity, but linked worktrees remain distinct. An explicitly selected narrow Fovea directory is not widened by later path activity it already owns.
+
+## Bounded continuity
+
+- `FOVEA_MAX_ROOTS`: 32 by default, clamped to 1–32. The recency ring refreshes on use; admitting root 33 retires the least recently used root rather than throwing.
+- `FOVEA_CACHE_ROOTS`: 2 by default, independently controls heavy graph/fact/vector cache residency. Root-local semantic fingerprints and attention outlive numerical paging. A dwell reconstructs vectors for retained focus instead of silently forgetting it.
+- `CONTOUR_MAX_ROOTS`: the same default/cap of 32. Immutable reports have separate bounded retention from the two hot graph generations.
+
+Retirement clears root-local session/sync state and invalidates its lease. Old asynchronous work cannot publish a root result or steer after retirement/session replacement. Re-entry creates a new observation boundary. It does **not** certify the inactive interval. A first successful write can already be part of the new baseline: Fovea must not invent a prior delta or current-session authorship; Contour can still compare the patch with Git.
+
+Branch-local custom entries retain only bounded root metadata. Compaction writes a fresh snapshot; reload/resume/fork/tree navigation restore the selected branch's roots, not stale semantic baselines, trust, or origin attribution. Reset explicitly clears the ring. Startup with no retained roots and idle coordinator hooks do not scan the launch directory.
+
+Unchanged cold Git roots are checked without rebuilding their graphs; dirty-to-clean reverts still count. Cold probes are deferred off the blocking before-agent hook to the post-turn backstop. Non-Git manifests and explicit umbrella boundaries need periodic bounded sweeps. Shared sync context is spent on relevant messages, not divided by the number of unrelated quiet roots. Root labels and retirement notices count toward that budget.
+
+Contour alternates recently accessed projects with a round-robin backstop, one root per scan. A 5-second scheduling tick is not a 5-second per-repository guarantee at 32 roots. Explicit checkpoints stop/abort speculative work, re-pin the requested repository's HEAD/index/worktree, and report root and agent origin separately. No discovery pass discloses findings or restarts an agent. `CONTOUR_BACKGROUND=0` leaves selection and explicit reviews available without polling.
+
+## Lightweight shared API
+
+`pi-fovea/workspace` exports `ExecutionRoots`, `ProjectDiscovery`, `canonicalPath`, `accessedPaths`, `WORKSPACE_ACCESS_EVENT`, `peerWorkspaceRoot`, `latestWorkspaceEntry`, `OBSERVED_ROOT_LIMIT`, and `envInt`. It imports no parser/graph/analysis engine, runs no Git, and does no filesystem work at module load.
+
+Fovea and Contour publish version-1 hints on `WORKSPACE_ACCESS_EVENT` through Pi's local event bus: `{ version: 1, source: "fovea" | "contour", root, sessionId }`. Only matching nonempty session IDs and the other extension's source are accepted. Peer selections are not rebroadcast. This carries target metadata, not source content, heat, trust, or mutation authorship; processes and remote hosts need their own explicit coordination.
+
+Executable coverage: `tests/roots.test.ts`, `tests/roaming.test.ts`, `tests/extension.test.ts`, and Contour's `tests/workspaces.test.ts` / `tests/startup.test.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",
@@ -35,11 +35,13 @@
   },
   "exports": {
     "./ops": "./src/core/ops.ts",
-    "./substrate": "./src/substrate.ts"
+    "./substrate": "./src/substrate.ts",
+    "./workspace": "./src/workspace.ts"
   },
   "files": [
     "src",
     "docs/substrate.md",
+    "docs/workspace.md",
     "cli.ts",
     "dist",
     "skills",
@@ -55,7 +57,6 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
     "bench": "tsx scripts/bench.ts",
     "corpus:coverage": "bun scripts/coverage-corpus.mjs",
     "corpus:performance": "bun scripts/performance-corpus.mjs",
@@ -63,7 +64,11 @@
     "prepack": "bun run build:cli",
     "fovea": "tsx cli.ts",
     "lint:dead": "knip",
-    "check": "bun run typecheck && bun run test && bun run lint:dead"
+    "check:fast": "bun run typecheck && bun run test:changed",
+    "test:changed": "node scripts/test-affected.mjs",
+    "test:affected": "node scripts/test-affected.mjs --base $PI_TEST_BASE",
+    "test:related": "vitest related",
+    "test:smoke": "vitest run tests/config.test.ts tests/settings.test.ts tests/substrate.test.ts tests/scan.test.ts tests/extract.test.ts tests/join.test.ts tests/heat.test.ts tests/nuclei.test.ts tests/render.test.ts"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.85.1",

package/skills/pi-fovea/SKILL.md

@@ -25,21 +25,27 @@ All four accept `maxTokens` (256–16000). Budget is roughly 4 chars per token.
 
 ## Multiple projects/worktrees
 
-Use an explicit graph-tool `root` before editing an alternate authorized project.
-Roots resolve relative to `ctx.cwd`; symlink aliases share identity, linked Git
-worktrees do not. The first call establishes its sync baseline before returning.
-Graph results expose `details.root` and `details.observedRoots`; omitted roots use
-the last binding. Bind every target to observe; after binding, hooks stop using
-an unselected umbrella cwd. Parallel calls should specify roots explicitly.
-
-Native paths remain cwd-relative: use absolute paths or `../project/file` for
-edits and grep. Augment grep follows its actual search path's enrolled owner,
-not the active graph binding. Focus or file-seeded impact establishes attention
-for headless shell edits; path events alone never enroll siblings. Alternate
-roots do not inherit cwd project-config trust. Shared sync context and observed
-roots are bounded (`FOVEA_MAX_ROOTS`, default 2; excess enrollment errors).
-Reset/reload/session replacement clears bindings, not reusable extraction facts.
-See README's “Explicit project/worktree continuity (Rakazo)” for the full contract.
+Successful native/Fabric `pi.*` path access automatically selects the containing
+project, including disjoint repositories outside cwd. A neutral launch directory
+is not implicitly indexed. Omitted analysis roots use the session cwd's own
+project (nearest `.git` or manifest, else the cwd), never the most recent
+selection; parallel callers should specify `root` explicitly. Explicit Fovea roots remain
+exact directory scopes, resolved relative to `ctx.cwd`. Symlink aliases unify;
+linked Git worktrees do not. Results expose root, origin, and workspace details.
+
+Native tool paths still resolve from cwd: use absolute paths or `../project/file`.
+Augment grep follows its actual search path, not an unrelated active binding.
+Failed/blocked accesses, output text, arbitrary programs, and remote namespaces
+do not enroll projects. Focus or file-seeded impact establishes attention before
+opaque shell edits. Alternate projects do not inherit cwd project-config trust.
+
+The default 32-root recency ring retires its least recently used root on overflow.
+`FOVEA_MAX_ROOTS` can lower that cap; `FOVEA_CACHE_ROOTS` independently defaults to
+two hot graphs. Retirement is an observation gap. First access/re-entry establishes
+a new baseline; a first write cannot be retrospectively attributed or diffed.
+Branch-local roots survive compaction/reload/resume, but old baselines do not.
+Reset clears the ring. Contour shares session-qualified target hints when loaded.
+See README's “Many projects, one conversation” and `docs/workspace.md`.
 
 ## Turn sync
 

package/src/core/asyncutil.ts

@@ -18,8 +18,10 @@ export const envInt = (name: string, dflt: number, min: number, max: number): nu
 export const SPAWN_CONCURRENCY = envInt("FOVEA_SPAWN_CONCURRENCY", 3, 1, 32);
 /** Max concurrent file reads/stats. */
 export const IO_CONCURRENCY = envInt("FOVEA_IO_CONCURRENCY", 32, 4, 512);
-/** Heavy per-root caches share one retention budget. */
-export const ROOT_CACHE_LIMIT = envInt("FOVEA_MAX_ROOTS", 2, 1, 32);
+/** Bounded observation ring; independent of heavyweight graph residency. */
+export const OBSERVED_ROOT_LIMIT = envInt("FOVEA_MAX_ROOTS", 32, 1, 32);
+/** Heavy graphs, fact stores, and numerical vectors remain a small hot cache. */
+export const ROOT_CACHE_LIMIT = envInt("FOVEA_CACHE_ROOTS", 2, 1, 32);
 
 /** Run fn over items with a global concurrency cap, preserving input order. */
 export const mapLimit = async <T, R>(

package/src/core/git.ts

@@ -5,7 +5,7 @@
 import { execFile } from "node:child_process";
 import { posix, join } from "node:path";
 import { stat } from "node:fs/promises";
-import { ROOT_CACHE_LIMIT, spawnGate } from "./asyncutil.js";
+import { OBSERVED_ROOT_LIMIT, spawnGate } from "./asyncutil.js";
 
 const GIT_TIMEOUT = 15_000;
 
@@ -20,8 +20,10 @@ export const gitOut = async (
       new Promise<string | undefined>((resolve) => {
         execFile(
           "git",
-          ["-C", root, ...args],
+          ["-c", "core.fsmonitor=false", "-C", root, ...args],
           {
+            // Local analysis must not run repository hooks or lazily fetch objects.
+            env: { ...process.env, GIT_NO_LAZY_FETCH: "1", GIT_ALLOW_PROTOCOL: "", GIT_TERMINAL_PROMPT: "0" },
             encoding: "utf8",
             timeout: opts.timeout ?? GIT_TIMEOUT,
             maxBuffer: opts.maxBuffer ?? 64 * 1024 * 1024,
@@ -89,7 +91,7 @@ export const gitPrefix = async (root: string): Promise<string | undefined> => {
   const prefix = out.trim().replace(/\\/g, "/");
   gitPrefixes.delete(root);
   gitPrefixes.set(root, prefix);
-  while (gitPrefixes.size > ROOT_CACHE_LIMIT) gitPrefixes.delete(gitPrefixes.keys().next().value!);
+  while (gitPrefixes.size > OBSERVED_ROOT_LIMIT) gitPrefixes.delete(gitPrefixes.keys().next().value!);
   return prefix;
 };
 

package/src/core/ops.ts

@@ -9,7 +9,7 @@ import { join, posix } from "node:path";
 import { diffHunks, prFiles, uncommittedFiles } from "./git.js";
 import { chebyshevVectors, chooseOrder, extendChebyshevVectors, forwardHeat, heatField } from "./heat.js";
 import { formatNodeLocation, revealFoveated, revealGroups, tokenEstimate, type GroupLine, type RevealedNode } from "./render.js";
-import { clearSessionFocus, FOCUS_T0, getSession, observeSessionPaths } from "./session.js";
+import { clearSessionFocus, FOCUS_T0, getSession, observeSessionPaths, retainSessionVectors } from "./session.js";
 import { detectBasins } from "./basins.js";
 import { classifyLiteral, normalizeLiteral } from "./join.js";
 import { isTestFile } from "./extract.js";
@@ -610,6 +610,7 @@ export const focus = async (
   }
   session.generation = state.generation;
   if (session.tkKey !== key) {
+    retainSessionVectors(root);
     session.tk = chebyshevVectors(state.csr, seedVector(g.nodes.length, seeds), chooseOrder(session.t));
     session.tkKey = key;
   }
@@ -657,7 +658,7 @@ export const dwell = async (root: string, factor?: number, budget?: number): Pro
   const g = state.graph;
   const session = getSession(root);
   const B = clampBudget(budget, 512);
-  if (session.seeds.length && (session.generation !== state.generation || session.tk[0]?.length !== g.nodes.length)) {
+  if (session.seeds.length && (session.generation !== state.generation || (session.tk.length > 0 && session.tk[0]?.length !== g.nodes.length))) {
     const previousGeneration = session.generation || "unknown";
     clearSessionFocus(session);
     const text = `fovea dwell: focus expired because the graph changed (${previousGeneration} → ${state.generation}). Call fovea_focus again; no stale vector was applied.`;
@@ -671,6 +672,11 @@ export const dwell = async (root: string, factor?: number, budget?: number): Pro
     const text = "fovea dwell: no focus yet. Call fovea_focus with a symbol, feature id, route, or file first; dwell then deepens that field.";
     return { text, tokens: tokenEstimate(text), details: { seeds: 0, ...extractionDetails(state) } };
   }
+  if (!session.tk.length) {
+    retainSessionVectors(root);
+    session.tk = chebyshevVectors(state.csr, seedVector(g.nodes.length, session.seeds), chooseOrder(session.t));
+    session.tkKey = session.focusKey;
+  }
   const from = session.t;
   const to = Math.min(64, from * Math.max(1.2, factor ?? 2));
   session.t = to;