@neuralis/brain-core 0.3.1 → 0.4.0

package/dist/src/git/sourceGitControl.js

@@ -6,7 +6,10 @@
  * a `.git` stat pre-gate, a FRESH `GitRunner` per cache miss (never reuse — the
  * `#assertRepoInsideSource` memoised-rejection trap), a short TTL cache, and
  * fail-soft `null` on any git problem so a slow/broken repo never blocks the list
- * or panel path.
+ * or panel path — save ONE: a paired device that refuses the spawn
+ * (`GitDeviceUnavailableError`) is thrown by every panel reader for the route
+ * to name, never folded into a clean repo's empty answer (the list-path
+ * summary never spawns on a device, so it never meets one).
  *
  * THREE readers, each with its own cost/scope:
  *   - `getSourceGitStatus`  — the WHOLE-repo change-set (staged / unstaged /
@@ -31,7 +34,7 @@
  * listing and the watcher expansion — consume the discovered set WITHOUT ever
  * passing the route validation ladder. A symlinked child pointing at a foreign
  * repo would therefore (1) leak the foreign repo's existence + branch in the
- * listing and (2) plant a host-side chokidar watcher on a foreign `.git`. So
+ * listing and (2) plant a host-side file watcher on a foreign `.git`. So
  * every candidate child must pass `realpath(child)` containment under
  * `realpath(sourceRoot)` BEFORE inclusion — at DISCOVERY itself, not only in
  * the route ladder — and the `containsRepos` probe applies the SAME predicate
@@ -44,7 +47,8 @@
 import { opendir, readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { hasFeature } from '@neuralis/package-system/access';
-import { GitRunner, GitOutputLimitError, EMPTY_TREE_SHA, } from './GitRunner.js';
+import { childPlace, placeKey, placePath, readDeviceHeadBranch, readDeviceSmallFile, toGitPlace, } from './gitPlace.js';
+import { GitRunner, GitDeviceUnavailableError, GitOutputLimitError, EMPTY_TREE_SHA, } from './GitRunner.js';
 import { xyCode } from './sourceGitStatus.js';
 import { resolvePermissions } from '../domain/permissionResolver.js';
 import { getBrainConfigNumber } from '../config/env.js';
@@ -74,18 +78,18 @@ const GIT_DISCOVERY_MAX_REPOS = 25;
  * demand; a repo too slow to answer within the cap fails soft to `null` (empty
  * panel), never blocking the request.
  */
-const GIT_CONTROL_STATUS_TIMEOUT_MS = 5000;
+const GIT_CONTROL_STATUS_TIMEOUT_MS = 15000;
 /**
  * Inactivity cap for the HEAVY on-demand readers — the per-file diff, the
  * commit DAG, and blob content at a rev (`show`) — so a 2 MB diff or a
- * 2000-commit log on a slow volume doesn't die at the 5 s status cap. NOTE:
- * both this and simple-git's `timeout:{block}` are INACTIVITY timers — they
- * reset on every output chunk, capping SILENCE, not wall-clock. A
- * continuously-STREAMING pathological command trips neither; that is stopped
- * by the engine's output accumulation bound (`GIT_MAX_OUTPUT_BYTES` in
- * `GitRunner.#spawnGit`, MINOR-6).
+ * 2000-commit log on a slow volume doesn't die at the status cap. NOTE:
+ * locally this is an INACTIVITY timer — it resets on every output chunk,
+ * capping SILENCE, not wall-clock (on a device the broker's timer is
+ * wall-clock). A continuously-STREAMING pathological command never trips it;
+ * that is stopped by the engine's output accumulation bound
+ * (`GIT_MAX_OUTPUT_BYTES`, on both transports, MINOR-6).
  */
-const GIT_CONTROL_HEAVY_TIMEOUT_MS = 15000;
+const GIT_CONTROL_HEAVY_TIMEOUT_MS = 60000;
 /** Max blob bytes `getSourceGitShow` serves — matches the route's 2 MB UI diff cap. */
 const GIT_SHOW_MAX_BLOB_BYTES = 2 * 1024 * 1024;
 const statusCache = new Map();
@@ -96,6 +100,23 @@ const summaryCache = new Map();
 // is shared by the summary's containsRepos/repoNames derivation, the route, and
 // the watcher expansion.
 const discoveryCache = new Map();
+/**
+ * A device that could not run a read (offline, devices off, the owner's
+ * "others" level, its ceiling) is a REFUSAL the route names — never the empty
+ * answer of a clean repo. Every other read failure stays fail-soft.
+ */
+function rethrowDeviceRefusal(error) {
+    if (error instanceof GitDeviceUnavailableError)
+        throw error;
+}
+/**
+ * The cache key of a read that SPAWNS git: on a device the caller's class
+ * rides it, so the owner's answer is never served to another member, whom
+ * the device judges again at every spawn (its per-folder "others" level).
+ */
+function spawnKey(place) {
+    return place.device && place.device.owner !== true ? `${placeKey(place)}\0other` : placeKey(place);
+}
 async function withCache(cache, key, ttlMs, compute) {
     const now = Date.now();
     const hit = cache.get(key);
@@ -105,16 +126,65 @@ async function withCache(cache, key, ttlMs, compute) {
     cache.set(key, { result, expiresAt: now + ttlMs });
     return result;
 }
-/** True when the source root has its OWN `.git` (dir OR linked-worktree file). */
-async function hasDotGit(resolvedRoot) {
+/** True when the source root has its OWN `.git` (dir OR linked-worktree file) — on its own machine. */
+async function hasDotGit(place) {
+    const at = placePath(place).join(place.root, '.git');
     try {
-        await stat(path.join(resolvedRoot, '.git'));
+        if (place.device)
+            return (await place.device.transport.stat(at)) !== null;
+        await stat(at);
         return true;
     }
     catch {
         return false;
     }
 }
+/**
+ * The device half of the depth-1 scan. The device's listing never names a
+ * symlink (the transport filters them), so every candidate child is a real
+ * directory under the root — containment holds by construction, with no
+ * `realpath` this process could not run there. A `.git` found by `stat` is
+ * admitted only when the child's own listing shows it as a real entry: `stat`
+ * follows links (inside the device's ceiling), the listing does not, so a
+ * symlinked `.git` onto a foreign repo drops exactly as the local `realpath`
+ * tail drops it. Cost: one listing of the root, one `stat` per examined child
+ * directory, one listing per find (≤ `limit`), at most 8 RPCs in flight.
+ */
+async function scanDeviceDepth1RepoChildren(place, limit, maxDirents) {
+    const seat = place.device;
+    if (!seat)
+        return [];
+    const p = placePath(place);
+    let entries;
+    try {
+        entries = await seat.transport.list(place.root);
+    }
+    catch {
+        return [];
+    }
+    const queue = entries.slice(0, maxDirents).filter((e) => e.isDirectory).map((e) => e.name);
+    const workers = Math.min(8, queue.length);
+    const found = [];
+    const worker = async () => {
+        for (let name = queue.shift(); name !== undefined && found.length < limit; name = queue.shift()) {
+            const child = p.join(place.root, name);
+            try {
+                if ((await seat.transport.stat(p.join(child, '.git'))) === null)
+                    continue;
+                const inner = await seat.transport.list(child);
+                if (!inner.some((e) => e.name === '.git'))
+                    continue; // a symlinked `.git` — never admitted
+            }
+            catch {
+                continue;
+            }
+            if (found.length < limit)
+                found.push({ rel: name, name, root: child, place: childPlace(place, name) });
+        }
+    };
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    return found;
+}
 /**
  * The ONE bounded depth-1 scan the discovery and the `containsRepos` probe
  * share (E1). STREAMING `fs.opendir` iteration — never a full `readdir`
@@ -133,7 +203,7 @@ async function hasDotGit(resolvedRoot) {
  *      containment too: step 3 STAT-FOLLOWS the `.git` entry itself, so a
  *      contained child whose `.git` is a SYMLINK onto a foreign repo would
  *      otherwise pass — re-opening exactly the exposure this filter closes
- *      (foreign chokidar watch, foreign listing/history). A regular `.git`
+ *      (foreign file watch, foreign listing/history). A regular `.git`
  *      dir or linked-worktree FILE realpaths inside the child (NIT-4's
  *      `.git`-file children stay admitted); only an escaping link drops.
  *      Residual (G2.5): a `.git` FILE whose `gitdir:` line points outside —
@@ -142,7 +212,11 @@ async function hasDotGit(resolvedRoot) {
  * Fail-soft throughout: an unreadable root yields `[]`, a mid-stream error
  * yields the entries found so far — a broken volume never breaks the caller.
  */
-async function scanDepth1RepoChildren(resolvedRoot, limit) {
+async function scanDepth1RepoChildren(place, limit) {
+    const maxDirents = getBrainConfigNumber('brainGitDiscoveryMaxDirents', undefined, GIT_DISCOVERY_MAX_DIRENTS);
+    if (place.device)
+        return scanDeviceDepth1RepoChildren(place, limit, maxDirents);
+    const resolvedRoot = place.root;
     let realRoot;
     try {
         realRoot = await realpath(resolvedRoot);
@@ -164,7 +238,7 @@ async function scanDepth1RepoChildren(resolvedRoot, limit) {
         // Breaking out of for-await invokes the iterator's return() → the Dir
         // handle closes itself; no manual close (a second close would throw).
         for await (const dirent of dir) {
-            if (examined >= getBrainConfigNumber('brainGitDiscoveryMaxDirents', undefined, GIT_DISCOVERY_MAX_DIRENTS))
+            if (examined >= maxDirents)
                 break;
             examined += 1;
             if (!dirent.isDirectory() && !dirent.isSymbolicLink())
@@ -179,7 +253,7 @@ async function scanDepth1RepoChildren(resolvedRoot, limit) {
             }
             if (real !== realRoot && !real.startsWith(rootPrefix))
                 continue; // MAJOR-A
-            if (!(await hasDotGit(child)))
+            if (!(await hasDotGit({ root: child })))
                 continue;
             // Step 4 (MAJOR-A tail): contain the `.git` TARGET as well — hasDotGit
             // stat-followed it, so a symlinked `.git` onto a foreign repo passed.
@@ -192,7 +266,7 @@ async function scanDepth1RepoChildren(resolvedRoot, limit) {
             catch {
                 continue; // raced away between the stat and the realpath — fail-soft skip
             }
-            found.push({ rel: dirent.name, name: dirent.name, root: child });
+            found.push({ rel: dirent.name, name: dirent.name, root: child, place: { root: child } });
             if (found.length >= limit)
                 break;
         }
@@ -217,18 +291,19 @@ async function scanDepth1RepoChildren(resolvedRoot, limit) {
  * `invalidateSourceGitCache(sourceRoot)` / `invalidateSourceGitDiscovery`
  * drop the entry.
  */
-export function discoverSourceRepoRoots(resolvedRoot) {
-    return withCache(discoveryCache, resolvedRoot, GIT_DISCOVERY_CACHE_TTL_MS, () => computeRepoRootsUncached(resolvedRoot));
+export function discoverSourceRepoRoots(target) {
+    const place = toGitPlace(target);
+    return withCache(discoveryCache, placeKey(place), GIT_DISCOVERY_CACHE_TTL_MS, () => computeRepoRootsUncached(place));
 }
-async function computeRepoRootsUncached(resolvedRoot) {
-    if (await hasDotGit(resolvedRoot)) {
-        return [{ rel: '', name: (await repoNameFromOrigin(resolvedRoot)) ?? repoNameFromRoot(resolvedRoot) ?? '', root: resolvedRoot }];
+async function computeRepoRootsUncached(place) {
+    if (await hasDotGit(place)) {
+        return [{ rel: '', name: (await repoNameFromOrigin(place)) ?? repoNameFromRoot(place) ?? '', root: place.root, place }];
     }
-    const found = await scanDepth1RepoChildren(resolvedRoot, getBrainConfigNumber('brainGitDiscoveryMaxRepos', undefined, GIT_DISCOVERY_MAX_REPOS));
+    const found = await scanDepth1RepoChildren(place, getBrainConfigNumber('brainGitDiscoveryMaxRepos', undefined, GIT_DISCOVERY_MAX_REPOS));
     // `name` is the DISPLAY name (origin basename, else the dir), the summary's order;
     // `rel` stays the dir and is the only one a path gate may read. The cap grabs the
     // FIRST ≤25 in dirent order; the REPORT is name-sorted (codepoint, locale-free).
-    const named = await Promise.all(found.map(async (r) => ({ ...r, name: (await repoNameFromOrigin(r.root)) ?? r.name })));
+    const named = await Promise.all(found.map(async (r) => ({ ...r, name: (await repoNameFromOrigin(r.place)) ?? r.name })));
     return named.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 /**
@@ -265,23 +340,31 @@ export function filterVisibleRepoNames(repoNames, permissions, source, createdBy
  * origin (fall back to the dir basename), the config is unreadable (a linked
  * worktree's `.git` is a FILE, no sibling config), or parsing yields nothing.
  */
-export async function repoNameFromOrigin(resolvedRoot) {
-    const configPath = path.join(resolvedRoot, '.git', 'config');
+export async function repoNameFromOrigin(target) {
+    const place = toGitPlace(target);
+    const configPath = placePath(place).join(place.root, '.git', 'config');
     let text;
-    try {
-        // Bound the READ, not a post-read slice: a project member can write the
-        // shared source's `.git/config`, and this runs on the summary hot path — a
-        // pathologically large config must never force a full-file allocation on a
-        // co-member's uncached summary. `.git/config` is normally a few hundred
-        // bytes; anything past 256 KB is not a real config → skip (basename fallback).
-        const info = await stat(configPath);
-        if (info.size > 256 * 1024)
+    if (place.device) {
+        const read = await readDeviceSmallFile(place.device, configPath, 256 * 1024);
+        if (read === null)
             return undefined;
-        text = await readFile(configPath, 'utf8');
-    }
-    catch {
-        return undefined;
-    }
+        text = read;
+    }
+    else
+        try {
+            // Bound the READ, not a post-read slice: a project member can write the
+            // shared source's `.git/config`, and this runs on the summary hot path — a
+            // pathologically large config must never force a full-file allocation on a
+            // co-member's uncached summary. `.git/config` is normally a few hundred
+            // bytes; anything past 256 KB is not a real config → skip (basename fallback).
+            const info = await stat(configPath);
+            if (info.size > 256 * 1024)
+                return undefined;
+            text = await readFile(configPath, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
     let inOrigin = false;
     for (const raw of text.split('\n')) {
         const line = raw.trim();
@@ -313,17 +396,18 @@ export async function repoNameFromOrigin(resolvedRoot) {
  * user action (panel open / repo select), NEVER on the `fs_list` hot path (use
  * `getSourceGitSummary` there).
  */
-export function getSourceGitStatus(resolvedRoot, gitBin) {
-    return withCache(statusCache, resolvedRoot, GIT_CONTROL_CACHE_TTL_MS, () => computeStatusUncached(resolvedRoot, gitBin));
+export function getSourceGitStatus(target, gitBin) {
+    const place = toGitPlace(target);
+    return withCache(statusCache, spawnKey(place), GIT_CONTROL_CACHE_TTL_MS, () => computeStatusUncached(place, gitBin));
 }
-async function computeStatusUncached(resolvedRoot, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+async function computeStatusUncached(place, gitBin) {
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         // Fresh runner per miss — NEVER cache a runner (memoised-rejection trap).
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitPanelTimeoutMs', undefined, GIT_CONTROL_STATUS_TIMEOUT_MS),
         });
@@ -384,7 +468,8 @@ async function computeStatusUncached(resolvedRoot, gitBin) {
             untracked,
         };
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         // GitNotARepoError / GitOutsideSourceError / GitTimeoutError / any → fail-soft.
         return null;
     }
@@ -409,13 +494,14 @@ async function computeStatusUncached(resolvedRoot, gitBin) {
  * yields an empty primary diff but is NOT untracked, so it correctly stays blank
  * (never fabricated as fully-added).
  */
-export async function getSourceGitDiff(resolvedRoot, repoRelPath, target, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+export async function getSourceGitDiff(at, repoRelPath, target, gitBin) {
+    const place = toGitPlace(at);
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitHeavyTimeoutMs', undefined, GIT_CONTROL_HEAVY_TIMEOUT_MS),
         });
@@ -445,6 +531,7 @@ export async function getSourceGitDiff(resolvedRoot, repoRelPath, target, gitBin
         return { ok: true, diff: primary };
     }
     catch (error) {
+        rethrowDeviceRefusal(error);
         if (error instanceof GitOutputLimitError)
             return { ok: false, code: 'too_large' };
         // GitNotARepoError / GitOutsideSourceError / GitArgumentError / GitTimeoutError / GitApplyError → fail-soft.
@@ -493,13 +580,14 @@ async function withNumstat(runner, files, from, to) {
         return { ...f, added: n.added, removed: n.removed, ...(n.binary ? { binary: true } : {}) };
     });
 }
-export async function getSourceGitCommitFiles(resolvedRoot, sha, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+export async function getSourceGitCommitFiles(target, sha, gitBin) {
+    const place = toGitPlace(target);
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitHeavyTimeoutMs', undefined, GIT_CONTROL_HEAVY_TIMEOUT_MS),
         });
@@ -512,7 +600,8 @@ export async function getSourceGitCommitFiles(resolvedRoot, sha, gitBin) {
         const files = await runner.commitFiles(sha, { hasParent });
         return await withNumstat(runner, files, hasParent ? `${sha}^` : EMPTY_TREE_SHA, sha);
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         // Unknown sha / GitNotARepoError / GitTimeoutError / GitOutputLimitError / any → fail-soft.
         return null;
     }
@@ -533,13 +622,14 @@ export async function getSourceGitCommitFiles(resolvedRoot, sha, gitBin) {
  *   - non-repo / unborn HEAD / timeout / any git error → `null`.
  * ON DEMAND, UNcached, fresh runner, heavy timeout.
  */
-export async function getSourceGitOutgoing(resolvedRoot, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+export async function getSourceGitOutgoing(target, gitBin) {
+    const place = toGitPlace(target);
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitHeavyTimeoutMs', undefined, GIT_CONTROL_HEAVY_TIMEOUT_MS),
         });
@@ -556,17 +646,19 @@ export async function getSourceGitOutgoing(resolvedRoot, gitBin) {
         const files = await withNumstat(runner, await runner.treeDiffFiles(resolved.baseSha, resolved.headSha), resolved.baseSha, resolved.headSha);
         return { baseSha: resolved.baseSha, headSha: resolved.headSha, files };
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         return null;
     }
 }
-export async function getSourceGitLogStats(resolvedRoot, opts, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+export async function getSourceGitLogStats(target, opts, gitBin) {
+    const place = toGitPlace(target);
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitHeavyTimeoutMs', undefined, GIT_CONTROL_HEAVY_TIMEOUT_MS),
         });
@@ -579,7 +671,8 @@ export async function getSourceGitLogStats(resolvedRoot, opts, gitBin) {
         const outgoing = await runner.outgoingShas();
         return { byCommit, ...(outgoing ? { outgoing } : {}) };
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         // Includes an older git rejecting `--diff-merges` — fail-soft to no stats.
         return null;
     }
@@ -599,13 +692,14 @@ export async function getSourceGitLogStats(resolvedRoot, opts, gitBin) {
  * log rather than a separate route so the graph's page fetch and its
  * decorations can never disagree about the ref state they were read under.
  */
-export async function getSourceGitLog(resolvedRoot, opts, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+export async function getSourceGitLog(target, opts, gitBin) {
+    const place = toGitPlace(target);
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitHeavyTimeoutMs', undefined, GIT_CONTROL_HEAVY_TIMEOUT_MS),
         });
@@ -618,7 +712,8 @@ export async function getSourceGitLog(resolvedRoot, opts, gitBin) {
         const outgoing = await runner.outgoingShas();
         return { commits, ...(outgoing ? { outgoing } : {}) };
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         return null;
     }
 }
@@ -637,13 +732,14 @@ export async function getSourceGitLog(resolvedRoot, opts, gitBin) {
  * `null` (fail-soft) for a non-git source, a path missing at the rev, a
  * timeout, or any git error.
  */
-export async function getSourceGitShow(resolvedRoot, repoRelPath, rev, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+export async function getSourceGitShow(target, repoRelPath, rev, gitBin) {
+    const place = toGitPlace(target);
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitHeavyTimeoutMs', undefined, GIT_CONTROL_HEAVY_TIMEOUT_MS),
         });
@@ -663,7 +759,8 @@ export async function getSourceGitShow(resolvedRoot, repoRelPath, rev, gitBin) {
             return { ok: false, code: 'binary' };
         return { ok: true, content, path: repoRelPath, rev };
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         // GitNotARepoError / GitOutsideSourceError / GitArgumentError / GitTimeoutError /
         // GitApplyError (path missing at the rev) / GitOutputLimitError → fail-soft.
         return null;
@@ -675,7 +772,13 @@ export async function getSourceGitShow(resolvedRoot, repoRelPath, rev, gitBin) {
  * The `.git/HEAD` badge watcher (G2.2) calls this the instant an EXTERNAL git
  * op fires so the next panel/list read recomputes from the live repo instead
  * of serving up to `GIT_CONTROL_CACHE_TTL_MS` of stale state. The caches key
- * on the resolved root (see `withCache`), so a keyed delete is exact — and
+ * on the resolved root (see `withCache`; the two that spawn on a device —
+ * status and branches — also on the caller's class, `spawnKey`, and both are
+ * dropped; the summary stays on the root because on a device it is FILE reads
+ * of `.git/HEAD` + `.git/config`, the same answer for every caller, and the
+ * discovery is the raw repo-root SET every consumer filters per caller through
+ * `filterVisibleRepoNames` — a spawn added to either moves it to `spawnKey`),
+ * so a keyed delete is exact — and
  * that keying is what keeps the watcher's existing call correct for NESTED
  * roots (E1): a nested-root invalidation drops that repo's own summary/status
  * entries, while the discovery/probe entries (keyed by the SOURCE root) are
@@ -683,11 +786,14 @@ export async function getSourceGitShow(resolvedRoot, repoRelPath, rev, gitBin) {
  * that DO change the set (source config mutation) invalidate at the source
  * root, which sweeps discovery too via `invalidateSourceGitDiscovery`.
  */
-export function invalidateSourceGitCache(resolvedRoot) {
-    statusCache.delete(resolvedRoot);
-    branchCache.delete(resolvedRoot);
-    summaryCache.delete(resolvedRoot);
-    invalidateSourceGitDiscovery(resolvedRoot);
+export function invalidateSourceGitCache(target) {
+    const key = placeKey(target);
+    for (const spawned of [key, `${key}\0other`]) {
+        statusCache.delete(spawned);
+        branchCache.delete(spawned);
+    }
+    summaryCache.delete(key);
+    discoveryCache.delete(key);
 }
 /**
  * Source-root-keyed drop of ONLY the E1 nested-checkout discovery entry (the
@@ -696,7 +802,7 @@ export function invalidateSourceGitCache(resolvedRoot) {
  * without also flushing the source's summary/status caches.
  */
 export function invalidateSourceGitDiscovery(sourceRoot) {
-    discoveryCache.delete(sourceRoot);
+    discoveryCache.delete(placeKey(sourceRoot));
 }
 /**
  * The local branch list for the branch-switcher. On demand, TTL-cached per root.
@@ -704,18 +810,19 @@ export function invalidateSourceGitDiscovery(sourceRoot) {
  * `getSourceGitSummary` (enumerates every local branch) — the switcher fetches it
  * on demand, never the list path.
  */
-export function getSourceBranches(resolvedRoot, gitBin) {
-    return withCache(branchCache, resolvedRoot, GIT_CONTROL_CACHE_TTL_MS, () => computeBranchesUncached(resolvedRoot, gitBin));
+export function getSourceBranches(target, gitBin) {
+    const place = toGitPlace(target);
+    return withCache(branchCache, spawnKey(place), GIT_CONTROL_CACHE_TTL_MS, () => computeBranchesUncached(place, gitBin));
 }
-async function computeBranchesUncached(resolvedRoot, gitBin) {
-    if (!(await hasDotGit(resolvedRoot)))
+async function computeBranchesUncached(place, gitBin) {
+    if (!(await hasDotGit(place)))
         return null;
     let runner;
     try {
         // MINOR-9: the branch list carries the SAME 5 s cap as status — it was the
         // one panel reader built with NO timeout.
         runner = await GitRunner.create({
-            containerRoot: resolvedRoot,
+            root: place,
             gitBin,
             timeoutMs: getBrainConfigNumber('brainGitPanelTimeoutMs', undefined, GIT_CONTROL_STATUS_TIMEOUT_MS),
         });
@@ -726,7 +833,8 @@ async function computeBranchesUncached(resolvedRoot, gitBin) {
     try {
         return await runner.branchList();
     }
-    catch {
+    catch (error) {
+        rethrowDeviceRefusal(error);
         return null;
     }
 }
@@ -736,8 +844,9 @@ async function computeBranchesUncached(resolvedRoot, gitBin) {
  * `undefined` when the basename is empty (a source rooted at `/`), so the
  * `repoName` field is omitted rather than stamped as `''`.
  */
-export function repoNameFromRoot(resolvedRoot) {
-    const name = path.basename(resolvedRoot);
+export function repoNameFromRoot(target) {
+    const place = toGitPlace(target);
+    const name = placePath(place).basename(place.root);
     return name.length > 0 ? name : undefined;
 }
 /**
@@ -758,28 +867,35 @@ export function repoNameFromRoot(resolvedRoot) {
  * `repoNames` is the RAW set — consumers MUST `filterVisibleRepoNames` before
  * stamping (per-file name-visibility). Root-repos never pay the scan.
  */
-export function getSourceGitSummary(resolvedRoot, gitBin) {
-    return withCache(summaryCache, resolvedRoot, GIT_CONTROL_CACHE_TTL_MS, () => computeSummaryUncached(resolvedRoot, gitBin));
+export function getSourceGitSummary(target, gitBin) {
+    const place = toGitPlace(target);
+    return withCache(summaryCache, placeKey(place), GIT_CONTROL_CACHE_TTL_MS, () => computeSummaryUncached(place, gitBin));
 }
-async function computeSummaryUncached(resolvedRoot, gitBin) {
-    if (!(await hasDotGit(resolvedRoot))) {
+async function computeSummaryUncached(place, gitBin) {
+    if (!(await hasDotGit(place))) {
         // E1/F2 — the ONLY new hot-path cost (MAJOR-4b budget): the shared 30 s
         // `discoverSourceRepoRoots` (streaming opendir ≤500 + ≤25 realpath-contained
         // finds; cache shared with the route + watcher so no double scan), fail-soft
         // to []. ZERO git spawn. A non-containing source pays the same dirent walk a
         // short-circuit probe would; a containing source pays ≤25 bounded stats.
-        const nested = (await discoverSourceRepoRoots(resolvedRoot)).filter((r) => r.rel !== '');
+        const nested = (await discoverSourceRepoRoots(place)).filter((r) => r.rel !== '');
         return nested.length > 0
             ? { isRepo: false, containsRepos: true, repoNames: nested.map((r) => r.rel) }
             : { isRepo: false };
     }
     // F2: the REAL repo name = the origin basename (mount-independent), falling
     // back to the checkout-dir basename for a no-remote repo / linked worktree.
-    const repoName = (await repoNameFromOrigin(resolvedRoot)) ?? repoNameFromRoot(resolvedRoot);
+    const repoName = (await repoNameFromOrigin(place)) ?? repoNameFromRoot(place);
     const named = repoName ? { repoName } : {};
+    if (place.device) {
+        // The list path never spawns on a device (the caller may not run programs
+        // there): the branch is read from `.git/HEAD` as a file.
+        const branch = await readDeviceHeadBranch(place.device, place.root, placePath(place));
+        return { isRepo: true, ...named, ...(branch ? { branch } : {}) };
+    }
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolvedRoot, gitBin });
+        runner = await GitRunner.create({ root: place, gitBin });
     }
     catch {
         // `.git` exists but the runner could not be built — still a repo, no branch.
@@ -802,12 +918,12 @@ async function computeSummaryUncached(resolvedRoot, gitBin) {
  * owner gains write via `byRole`/`byUser`). PURE (no git I/O) → O(1)/source, safe on
  * the hot list path. Deny-by-default: false unless BOTH planes allow.
  *
- *   canWrite = caller HAS `drive.write` (the file-level FEATURE, same predicate as
+ *   canWrite = caller HAS `files.write` (the file-level FEATURE, same predicate as
  *              the route `denyIfNoWrite`)  ∧  the caller's RESOLVED uri-policy
  *              `write` on the source ROOT `<slug>://` is allowed.
  */
 export function resolveGitCanWrite(permissions, source, createdBy, caller) {
-    if (!hasFeature({ grantedFeatures: caller.grantedFeatures ?? [] }, 'drive.write'))
+    if (!hasFeature({ grantedFeatures: caller.grantedFeatures ?? [] }, 'files.write'))
         return false;
     return (resolvePermissions(permissions, `${source}://`, {
         userId: caller.userId,
@@ -825,7 +941,7 @@ export function resolveGitCanWrite(permissions, source, createdBy, caller) {
  * ROOT `<slug>://`, exactly what the remote-op route gates on
  * (`resolveGitSource({capability:'exec'})`). Drives whether the panel enables
  * the fetch/pull/push popover vs the "grant exec" affordance. Unlike canWrite it
- * does NOT gate the `drive.write` FEATURE (the route + the panel's canWrite
+ * does NOT gate the `files.write` FEATURE (the route + the panel's canWrite
  * trigger gate that separately) — it reflects ONLY the exec policy so the
  * affordance is precise. PURE (no git I/O). Deny-by-default: `exec:false`
  * baseline out of the box.