pi-fovea 0.13.2 → 0.13.4

package/README.md

@@ -185,8 +185,10 @@ update names the changed files, the route deltas, and the newly relevant files.
 It lists the causal channels behind each link: calls, imports, shared literals,
 tests, or co-change history. By default it also embeds the refreshed focus
 context of the top drift target (push). With `sync.pushFocus` off, the update
-ends with a suggested focus probe for the next call (pull). Clean turns stay
-silent. Enable `sync.ackClean` if you want an ack for those. Set `sync.mode` to
+ends with a suggested focus probe for the next call (pull). Switching
+branches re-baselines silently instead of steering: a `git checkout`
+re-materializes the worktree, but the branch diff is not authored drift —
+commits, pulls, and rebases still report. Clean turns stay silent. Enable `sync.ackClean` if you want an ack for those. Set `sync.mode` to
 `"hidden"` to keep red sync context working behind the scenes without rendering it
 in the transcript, or to `"disabled"` to turn continuous sync off.
 
@@ -208,7 +210,10 @@ FOVEA_TURN_SYNC=off pi
 
 Global settings live in `~/.pi/agent/fovea.json`. A trusted repo-level override
 sits in `<repo>/.pi/fovea.json`. These are the same two scopes pi-fabric uses
-with `fabric.json`.
+with `fabric.json`. In `/fovea settings`, the configured external-editor key
+(`Ctrl+G` by default) switches both the displayed values and save destination
+between project overrides and global defaults. A project override can remain
+effective while its global default is being edited.
 
 | Key | Default | Meaning |
 | --- | :-----: | ------- |

package/dist/cli.mjs

@@ -306,6 +306,11 @@ var gitHead = async (root) => {
   const head = out?.trim();
   return head ? head : void 0;
 };
+var gitReflogAction = async (root) => {
+  const out = await gitOut(root, ["reflog", "-1", "--format=%gs"]);
+  const line = out?.trim();
+  return line ? line : void 0;
+};
 var gitPrefixes = /* @__PURE__ */ new Map();
 var gitPrefix = async (root) => {
   if (gitPrefixes.has(root)) {
@@ -2926,6 +2931,7 @@ var refreshState = async (state, hints = [], force = false) => {
   let files = state.files;
   const changed = [];
   const deleted = [];
+  let checkout = false;
   const hinted = [.../* @__PURE__ */ new Set([...filterSupported(hints, routeRes), ...hints.filter((h) => store.facts.has(h))])];
   changed.push(...hinted);
   if (state.gitKind === "git") {
@@ -2933,6 +2939,9 @@ var refreshState = async (state, hints = [], force = false) => {
     if (probe) {
       const headMoved = probe.head !== state.head;
       state.head = probe.head;
+      if (headMoved) {
+        checkout = (await gitReflogAction(state.root))?.startsWith("checkout:") ?? false;
+      }
       const needsList = probe.relist || probe.changes.some((c) => c.path.endsWith("/"));
       if (needsList) {
         files = await listFiles(state.root, routeRes);
@@ -2991,6 +3000,7 @@ var refreshState = async (state, hints = [], force = false) => {
     return state;
   }
   const fresh = await assembleState(state.root, files, store, report, state.gitKind, state.head, state.dirty);
+  if (checkout) fresh.checkout = true;
   states.set(state.root, fresh);
   return fresh;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "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/skills/pi-fovea/SKILL.md

@@ -45,6 +45,6 @@ The same engine runs headlessly as the `fovea` binary (repo root scan, plus JSON
 
 ## Settings
 
-Use `/fovea status` for loaded version and index coverage, `/fovea reset` for fresh state, `/fovea reload` after updates, and `/fovea settings` for configuration. Files live under `~/.pi/agent/fovea.json` or trusted `.pi/fovea.json`. `tools.grepMode` controls the grep integration: `"augment"` (default) keeps native grep semantics and appends a Fovea graph section to symbol-query results — including `pi.grep` calls inside fabric_exec — `"replace"` keeps the legacy bare-query takeover, `"off"` is native only.
+Use `/fovea status` for loaded version and index coverage, `/fovea reset` for fresh state, `/fovea reload` after updates, and `/fovea settings` for configuration. Files live under `~/.pi/agent/fovea.json` or trusted `.pi/fovea.json`; the external-editor key (`Ctrl+G` by default) switches the displayed and saved layer between global defaults and project overrides. `tools.grepMode` controls the grep integration: `"augment"` (default) keeps native grep semantics and appends a Fovea graph section to symbol-query results — including `pi.grep` calls inside fabric_exec — `"replace"` keeps the legacy bare-query takeover, `"off"` is native only.
 
 Budget overflow is not a dead end: any `… more results collapsed or outside budget` footer names a tmp artifact (`/tmp/pi-fovea-<op>-<hash>.txt`) holding the FULL list — read or grep that file for the remainder. Reach for `fovea_dwell` when you want a wider neighborhood, not just more of the same list.

package/src/core/config.ts

@@ -155,9 +155,12 @@ const readConfigFile = (file: string): Record<string, unknown> => {
   }
 };
 
-export const loadFoveaConfig = (scopes: FoveaConfigScopes): FoveaConfig => {
+const resolveFoveaConfig = (
+  scopes: FoveaConfigScopes,
+  includeProject: boolean,
+): FoveaConfig => {
   let config = applyPartial(DEFAULT_FOVEA_CONFIG, readConfigFile(globalFoveaConfigPath(scopes.agentDir)));
-  if (scopes.projectTrusted) {
+  if (includeProject) {
     config = applyPartial(config, readConfigFile(projectFoveaConfigPath(scopes.cwd)));
   }
   // Environment override mirrors pi-fabric's PI_* precedence over stored values.
@@ -166,6 +169,19 @@ export const loadFoveaConfig = (scopes: FoveaConfigScopes): FoveaConfig => {
   return config;
 };
 
+export const loadFoveaConfigForScope = (
+  scopes: FoveaConfigScopes,
+  scope: FoveaConfigScope,
+): FoveaConfig => {
+  if (scope === "project" && !scopes.projectTrusted) {
+    throw new Error("Cannot load project Fovea configuration for an untrusted project");
+  }
+  return resolveFoveaConfig(scopes, scope === "project");
+};
+
+export const loadFoveaConfig = (scopes: FoveaConfigScopes): FoveaConfig =>
+  resolveFoveaConfig(scopes, scopes.projectTrusted);
+
 const mergeDeep = (existing: Record<string, unknown>, partial: Record<string, unknown>): Record<string, unknown> => {
   const out = { ...existing };
   for (const [key, value] of Object.entries(partial)) {

package/src/core/git.ts

@@ -41,6 +41,18 @@ export const gitHead = async (root: string): Promise<string | undefined> => {
   return head ? head : undefined;
 };
 
+/**
+ * Subject of the most recent HEAD reflog entry, e.g. "checkout: moving from
+ * main to feature". Tells branch switches (re-baseline quietly) apart from
+ * commits/pulls/rebases (foreign drift worth reporting). Undefined when the
+ * reflog is unavailable or disabled — callers fall back to the loud path.
+ */
+export const gitReflogAction = async (root: string): Promise<string | undefined> => {
+  const out = await gitOut(root, ["reflog", "-1", "--format=%gs"]);
+  const line = out?.trim();
+  return line ? line : undefined;
+};
+
 export interface WorktreeChange {
   /** X+Y status columns, e.g. " M", "??", "D ". */
   code: string;

package/src/core/ops.ts

@@ -19,7 +19,7 @@ import {
   type FactStore,
   type FileFacts,
 } from "./build.js";
-import { gitProbe, prFiles, uncommittedFiles } from "./git.js";
+import { gitProbe, gitReflogAction, prFiles, uncommittedFiles } from "./git.js";
 import { ROOT_CACHE_LIMIT, envInt, yieldToLoop } from "./asyncutil.js";
 import { loadRepoRules } from "./anchors.js";
 import { buildCsr, chebyshevVectors, chooseOrder, heatField, type Csr } from "./heat.js";
@@ -62,6 +62,12 @@ export interface RepoState {
    * porcelain-clean with unmoved HEAD would otherwise keep serving its dirty
    * facts until the next edit. */
   dirty: Set<string>;
+  /** Set when this generation materialized from a `git checkout` (HEAD moved
+   * with reflog action "checkout:…"): sync re-baselines silently instead of
+   * cascading over the branch diff. Lives exactly one generation — the next
+   * fact-moving refresh builds a fresh state without it, so the quiet path
+   * cannot hide authored drift. */
+  checkout?: boolean;
   /** Past joint-edit affinity (raw conductance + last joint commit). History
    * is NOT structure: impact re-seeds these partners at recency-decayed
    * strength whenever a change lands, so old co-work cools like any heat. */
@@ -194,6 +200,12 @@ const refreshState = async (state: RepoState, hints: string[] = [], force = fals
   let files = state.files;
   const changed: string[] = [];
   const deleted: string[] = [];
+  // A checkout re-materializes the worktree from another ref; flag the
+  // rebuilt generation so sync re-baselines quietly. Only a HEAD move whose
+  // latest reflog action is "checkout:…" qualifies — pulls/rebases merge
+  // foreign work and keep the loud drift path, and reflog-less repos stay
+  // conservative (undefined -> false).
+  let checkout = false;
   const hinted = [...new Set([...filterSupported(hints, routeRes), ...hints.filter((h) => store.facts.has(h))])];
   changed.push(...hinted);
 
@@ -202,6 +214,9 @@ const refreshState = async (state: RepoState, hints: string[] = [], force = fals
     if (probe) {
       const headMoved = probe.head !== state.head;
       state.head = probe.head;
+      if (headMoved) {
+        checkout = (await gitReflogAction(state.root))?.startsWith("checkout:") ?? false;
+      }
       // Untracked directories appear collapsed ("dir/") in porcelain; adds
       // inside them only surface through a relist. Relist moments are rare.
       const needsList = probe.relist || probe.changes.some((c) => c.path.endsWith("/"));
@@ -274,6 +289,7 @@ const refreshState = async (state: RepoState, hints: string[] = [], force = fals
     return state;
   }
   const fresh = await assembleState(state.root, files, store, report, state.gitKind, state.head, state.dirty);
+  if (checkout) fresh.checkout = true;
   states.set(state.root, fresh);
   return fresh;
 };

package/src/core/sync.ts

@@ -163,6 +163,9 @@ export const warmSync = async (root: string, params: WarmParams, state?: RepoSta
     const cur = state ?? (await ensureState(root, { hints: params.files ?? [], force: false }));
     const prev = getBaseline(root);
     if (!prev || prev.version === cur.version) return;
+    // A checkout generation re-baselines silently in sync: no cascade to
+    // prepare, and precomputing one over the branch diff would be waste.
+    if (cur.checkout) return;
     const files = semanticDrift(cur, prev);
     if (!files.length) return;
     const key = filesKey(files);
@@ -294,6 +297,19 @@ export const sync = async (
     };
   }
 
+  // Branch-switch re-baseline. A checkout moves HEAD and re-materializes the
+  // worktree without authored edits; cascading over the branch diff would
+  // fire a loud, useless steer on every switch, so the baseline just follows
+  // the ref (details.baseline keeps the hooks' ack-clean notify silent too).
+  // Heat memory belongs to the old ref's field and does not cross over.
+  if (state.checkout) {
+    setBaseline(root, await snapshot(state));
+    return {
+      structural: true, red: false, tokens: 0,
+      details: { version: state.version, checkout: true, baseline: "established", anchors: state.graph.anchors.length },
+    };
+  }
+
   // 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.

package/src/ui/settings.ts

@@ -3,7 +3,7 @@
 // SelectList submenus, dotted-id coercion) so both extensions feel like one
 // settings surface. Persistence: fovea.json under the pi agent dir, with a
 // project override beneath pi's configured project resource directory; the
-// external-editor keybinding toggles which scope the next change saves to.
+// external-editor keybinding switches the configuration layer being viewed and saved.
 
 import {
   CONFIG_DIR_NAME,
@@ -29,6 +29,7 @@ import {
 import {
   buildPartialFromId,
   loadFoveaConfig,
+  loadFoveaConfigForScope,
   SYNC_MODES,
   saveFoveaConfig,
   type FoveaConfig,
@@ -133,15 +134,20 @@ export interface FoveaSettingsComponentOptions {
   initialSaveScope?: FoveaConfigScope;
   projectScopeAvailable?: boolean;
   onSaveScopeChange?: (scope: FoveaConfigScope) => void;
+  itemsForSaveScope?: (scope: FoveaConfigScope) => SettingItem[];
 }
 
 export class FoveaSettingsComponent extends Container {
-  readonly settingsList: SettingsList;
+  settingsList: SettingsList;
   private readonly theme: Theme;
   private readonly keybindings: Pick<KeybindingsManager, "matches" | "getKeys"> | undefined;
   private readonly saveScopeText: Text;
+  private readonly settingsListContainer: Container;
   private readonly projectScopeAvailable: boolean;
+  private readonly onChange: (id: string, newValue: string) => void;
+  private readonly onCancel: () => void;
   private readonly onSaveScopeChange: (scope: FoveaConfigScope) => void;
+  private readonly itemsForSaveScope: ((scope: FoveaConfigScope) => SettingItem[]) | undefined;
   private saveScope: FoveaConfigScope;
 
   constructor(
@@ -158,16 +164,19 @@ export class FoveaSettingsComponent extends Container {
     this.saveScope = options.initialSaveScope === "global" || !this.projectScopeAvailable
       ? "global"
       : "project";
+    this.onChange = onChange;
+    this.onCancel = onCancel;
     this.onSaveScopeChange = options.onSaveScopeChange ?? (() => {});
+    this.itemsForSaveScope = options.itemsForSaveScope;
     this.addChild(new DynamicBorder((text) => theme.fg("border", text)));
     this.saveScopeText = new Text("", 1, 0);
     this.updateSaveScopeText();
     this.addChild(this.saveScopeText);
     this.addChild(new Spacer(1));
-    this.settingsList = new SettingsList(items, 10, settingsListTheme(theme), onChange, onCancel, {
-      enableSearch: true,
-    });
-    this.addChild(this.settingsList);
+    this.settingsListContainer = new Container();
+    this.settingsList = this.createSettingsList(items);
+    this.settingsListContainer.addChild(this.settingsList);
+    this.addChild(this.settingsListContainer);
     this.addChild(new DynamicBorder((text) => theme.fg("border", text)));
   }
 
@@ -177,6 +186,12 @@ export class FoveaSettingsComponent extends Container {
       this.saveScope = this.saveScope === "project" ? "global" : "project";
       this.updateSaveScopeText();
       this.onSaveScopeChange(this.saveScope);
+      const nextItems = this.itemsForSaveScope?.(this.saveScope);
+      if (nextItems) {
+        this.settingsListContainer.clear();
+        this.settingsList = this.createSettingsList(nextItems);
+        this.settingsListContainer.addChild(this.settingsList);
+      }
       return;
     }
     this.settingsList.handleInput(data);
@@ -187,17 +202,32 @@ export class FoveaSettingsComponent extends Container {
     this.updateSaveScopeText();
   }
 
+  private createSettingsList(items: SettingItem[]): SettingsList {
+    return new SettingsList(
+      items,
+      10,
+      settingsListTheme(this.theme),
+      this.onChange,
+      this.onCancel,
+      { enableSearch: true },
+    );
+  }
+
   private updateSaveScopeText(): void {
     const destination = this.saveScope === "project"
-      ? `Project (${CONFIG_DIR_NAME}/fovea.json)`
-      : `Global (~/${CONFIG_DIR_NAME}/agent/fovea.json)`;
+      ? `Project overrides (${CONFIG_DIR_NAME}/fovea.json)`
+      : `Global defaults (~/${CONFIG_DIR_NAME}/agent/fovea.json)`;
     const keys = this.keybindings?.getKeys("app.editor.external") ?? [];
     const shortcut = keys.map(formatKey).join("/");
-    const hint = this.projectScopeAvailable
-      ? shortcut ? ` · ${shortcut} toggles save scope` : " · scope toggle key unavailable"
-      : " · project scope unavailable for untrusted projects";
+    const hint = !this.projectScopeAvailable
+      ? " · project scope unavailable for untrusted projects"
+      : !shortcut
+        ? " · scope switch key unavailable"
+        : this.saveScope === "global"
+          ? ` · ${shortcut} switches scope · project overrides may remain active here`
+          : ` · ${shortcut} switches scope`;
     this.saveScopeText.setText(
-      this.theme.fg("muted", "Save scope: ") +
+      this.theme.fg("muted", "Editing: ") +
       this.theme.fg("accent", destination) +
       this.theme.fg("dim", hint),
     );
@@ -299,7 +329,7 @@ export const openFoveaSettings = async (
     projectTrusted: context.isProjectTrusted(),
   };
   let saveScope: FoveaConfigScope = scopes.projectTrusted ? "project" : "global";
-  let config = loadFoveaConfig(scopes);
+  let config = loadFoveaConfigForScope(scopes, saveScope);
   const initialGrepRegistration = config.tools.grepMode === "replace";
   let dirty = false;
 
@@ -313,16 +343,19 @@ export const openFoveaSettings = async (
       );
       return;
     }
-    config = applyPartialLocal(config, id, value);
+    config = loadFoveaConfigForScope(scopes, saveScope);
     dirty = true;
     deps.onConfigApplied?.();
   };
 
   await context.ui.custom<void>((tui, theme, keybindings, done) => {
-    const items = buildItems(theme, config);
+    const itemsForScope = (scope: FoveaConfigScope): SettingItem[] => {
+      config = loadFoveaConfigForScope(scopes, scope);
+      return buildItems(theme, config);
+    };
     return new FoveaSettingsComponent(
       theme,
-      items,
+      itemsForScope(saveScope),
       (id, newValue) => apply(id, coerceValue(id, newValue, config)),
       () => done(),
       {
@@ -333,27 +366,16 @@ export const openFoveaSettings = async (
           saveScope = scope;
           tui.requestRender();
         },
+        itemsForSaveScope: itemsForScope,
       },
     );
   });
 
   if (dirty) context.ui.notify("Fovea settings saved.", "info");
-  return { grepRegistrationChanged: (config.tools.grepMode === "replace") !== initialGrepRegistration };
-};
-
-// Local in-place merge so subsequent edits in the same overlay start from the
-// already-saved value (config is reloaded from disk on open).
-const applyPartialLocal = (config: FoveaConfig, id: string, value: unknown): FoveaConfig => {
-  const next: FoveaConfig = {
-    sync: { ...config.sync },
-    tools: { ...config.tools },
+  const effectiveConfig = loadFoveaConfig(scopes);
+  return {
+    grepRegistrationChanged:
+      (effectiveConfig.tools.grepMode === "replace") !== initialGrepRegistration,
   };
-  const segments = id.split(".");
-  let target: Record<string, unknown> = next as unknown as Record<string, unknown>;
-  for (let i = 0; i < segments.length - 1; i++) {
-    target = target[segments[i]!] as Record<string, unknown>;
-  }
-  target[segments[segments.length - 1]!] = value;
-  return next;
 };