@neuralis/brain-core 0.3.1 → 0.4.0

package/dist/src/routes/git.js

@@ -3,7 +3,7 @@
  * "Git Control" sidebar panel, branch-switcher, side-by-side diff, and the
  * in-panel commit graph.
  *
- * READ routes (GET, `drive.read`-gated):
+ * READ routes (GET, `files.read`-gated):
  *   GET /git/status?source=<slug>  — the WHOLE-repo change-set (staged /
  *                                    unstaged / untracked) + current branch +
  *                                    upstream/ahead/behind when an upstream
@@ -75,7 +75,7 @@
  * including the hunk-extracted ones. Without `repo` everything is
  * byte-identical to the single-repo behavior.
  *
- * WRITE routes (POST, additionally `drive.write`-gated — G2.3):
+ * WRITE routes (POST, additionally `files.write`-gated — G2.3):
  *   POST /git/stage    {source, paths?[], hunk?}   — whole-file `add` OR hunk
  *                                                    `apply --cached`.
  *   POST /git/unstage  {source, paths?[], hunk?}   — whole-file `reset -- <p>`
@@ -90,7 +90,7 @@
  *                                                    (plain, non-force — git refuses
  *                                                    if it would overwrite local changes).
  *
- * REMOTE routes (POST, `drive.write` + uri-policy `exec` — G4 keyring-kestrel Slice 2):
+ * REMOTE routes (POST, `files.write` + uri-policy `exec` — G4 keyring-kestrel Slice 2):
  *   POST /git/fetch   {source}   — `git fetch origin` (updates remote-tracking refs).
  *   POST /git/pull    {source}   — `fetch` + `merge --ff-only FETCH_HEAD` (S4: token
  *                                  never rides the working-tree-writing merge).
@@ -114,7 +114,7 @@
  *     composed ONCE in the resolver, threaded into `guardWritePaths` (incl.
  *     hunk-extracted paths) so no gate site can drift (MAJOR-B).
  *   - WRITE is the HUMAN face: the caller's authenticated session IS the consent
- *     (uri-policy `write` + the `drive.write` feature). The agent-approval
+ *     (uri-policy `write` + the `files.write` feature). The agent-approval
  *     `PendingInteraction` ladder is a SEPARATE later increment (G3) — NOT here.
  *     A synthetic/agent sentinel identity is rejected upstream (catch-all boundary).
  *   - Q6 SECURITY FLOOR: before ANY destructive op (discard, branch -D) the SERVER
@@ -133,22 +133,23 @@
  */
 import { realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { resolveUsername } from '@neuralis/package-system/contracts';
+import { resolveUsername, sourcePlane } from '@neuralis/package-system/contracts';
 import { hasFeature } from '@neuralis/package-system/access';
 import { resolvePermissions } from '../domain/permissionResolver.js';
-import { LocalDiskConnector } from '../connectors/LocalDiskConnector.js';
+import { HostConnector } from '../connectors/HostConnector.js';
 import { getSourceGitStatus, getSourceGitLogStats, getSourceBranches, getSourceGitDiff, getSourceGitLog, getSourceGitShow, getSourceGitCommitFiles, getSourceGitOutgoing, getSourceGitSummary, discoverSourceRepoRoots, resolveGitCanWrite, filterVisibleRepoNames, invalidateSourceGitCache, } from '../git/sourceGitControl.js';
 import { countUntrackedAdditions } from '../git/untrackedStats.js';
+import { childPlace } from '../git/gitPlace.js';
 import { getBrainConfigNumber } from '../config/env.js';
-import { GitRunner, GitArgumentError, GitOutsideSourceError, GitUnavailableError, } from '../git/GitRunner.js';
+import { GitRunner, GitArgumentError, GitDeviceUnavailableError, GitOutsideSourceError, GitUnavailableError, } from '../git/GitRunner.js';
 import { resolveGitToken } from '../git/tokenResolve.js';
 import { extractCtx, ensureAccess, getServices, toScopeAccessCtx, publishInAppGitBadge, } from './helpers.js';
 import { assertUriCapability, uriPolicyDeniedResponse, UriPolicyDeniedError, } from './helpers/uriGuard.js';
 export const pattern = 'git/*';
-export const feature = 'drive.read';
+export const feature = 'files.read';
 // The mutating op-class escalates in-handler (`denyIfNoWrite`, and the per-row
 // `canWrite` projection); the module gate only guarantees the read tier.
-export const escalations = ['drive.write'];
+export const escalations = ['files.write'];
 /** Max change-set entries returned across all three buckets (response size cap). */
 const MAX_STATUS_ENTRIES = 1000;
 /**
@@ -197,7 +198,17 @@ const MAX_SUBJECT_LEN = 500;
  *  card shows the message, not a full diff). */
 const MAX_BODY_LEN = 4000;
 export const GET = async (req, raw) => {
-    const state = raw;
+    try {
+        return await dispatchRead(req, raw);
+    }
+    catch (error) {
+        // A device that refused a read is named — never a clean repo's empty answer.
+        if (error instanceof GitDeviceUnavailableError)
+            return gitDeviceUnavailable(error.reason);
+        throw error;
+    }
+};
+async function dispatchRead(req, state) {
     const [sub] = req.path;
     if (sub === 'status')
         return handleGitStatus(req, state);
@@ -218,11 +229,11 @@ export const GET = async (req, raw) => {
     if (sub === 'repos')
         return handleGitRepos(req, state);
     return { status: 404, body: { error: `Unknown git route: ${sub ?? ''}` } };
-};
+}
 /**
  * WRITE routes (G2.3) — the HUMAN face of the git engine. Dispatched on
- * `req.path[0]`. Each handler additionally gates `drive.write` (the file-level
- * `feature` only guarantees `drive.read`) and the uri-policy `write` capability,
+ * `req.path[0]`. Each handler additionally gates `files.write` (the file-level
+ * `feature` only guarantees `files.read`) and the uri-policy `write` capability,
  * auto-snapshots before a destructive op (Q6), and publishes the IN-APP badge
  * with the actor's real identity (N3) on success.
  */
@@ -278,10 +289,11 @@ async function resolveGitSource(req, state, opts = {}) {
     if (!config) {
         return { ok: false, response: { status: 404, body: { error: `Source not found: ${source}` } } };
     }
-    if (config.connection?.kind !== 'local') {
+    const plane = config.connection ? sourcePlane(config.connection.kind, config.connection.config) : 'connector';
+    if (plane !== 'local' && plane !== 'device') {
         return {
             ok: false,
-            response: { status: 400, body: { error: `Source "${config.source}" is not a git-capable local source` } },
+            response: { status: 400, body: { error: `Source "${config.source}" is not a git-capable folder` } },
         };
     }
     // uri-policy gate (defense-in-depth beyond the scope check). `capability` is
@@ -313,13 +325,11 @@ async function resolveGitSource(req, state, opts = {}) {
             return { ok: false, response: uriPolicyDeniedResponse(error) };
         throw error;
     }
-    const root = resolveLocalRootForSource(services, config.source);
-    if (!root) {
-        return {
-            ok: false,
-            response: { status: 400, body: { error: `Source "${config.source}" has no resolvable local checkout root` } },
-        };
-    }
+    const found = await resolveGitPlace(services, state, ctx, config.source);
+    if (!found.ok)
+        return found;
+    const sourcePlace = found.place;
+    const root = sourcePlace.root;
     const base = {
         ok: true,
         source: config.source,
@@ -330,15 +340,75 @@ async function resolveGitSource(req, state, opts = {}) {
         createdBy: config.createdBy,
     };
     if (repo === undefined)
-        return { ...base, root };
+        return { ...base, root, place: sourcePlace };
     // E1 braces — membership + fresh re-check on the nested root. ONE constant
     // 404 for non-member / non-repo / symlink-escape / raced-away children —
     // the response never reveals whether the child exists.
-    const nestedRoot = await resolveNestedRepoRoot(root, repo);
-    if (!nestedRoot) {
+    const nested = await resolveNestedRepoPlace(sourcePlace, repo);
+    if (!nested) {
         return { ok: false, response: { status: 404, body: { error: `Repository not found: ${repo}` } } };
     }
-    return { ...base, root: nestedRoot };
+    return { ...base, root: nested.root, place: nested };
+}
+/**
+ * The place git runs for a source: the in-process folder's root, or a device
+ * folder behind the ONE device gate's `exec` arm (D7′ + the owner's per-host
+ * folders and "others" level, D-L1). Every git call on a device is a program run
+ * there, so the gate answers BEFORE anything spawns: the device's owner holding
+ * `device.own` always; anyone else only with `exec.device` on a device whose
+ * live verdict is `sandboxed` — and even then the broker re-judges at the spawn
+ * (`requireConfinement` + `actor:'other'` against the owner's per-folder
+ * "others" setting). The refusal is the gate's FIXED code and sentence.
+ */
+async function resolveGitPlace(services, state, ctx, source) {
+    const connector = services.infra?.connectors?.resolveBySource?.(source) ?? null;
+    if (!(connector instanceof HostConnector)) {
+        return { ok: false, response: { status: 400, body: { error: `Source "${source}" has no resolvable checkout root` } } };
+    }
+    const device = connector.device;
+    if (device === undefined)
+        return { ok: true, place: { root: connector.root } };
+    const devices = state.ctx.packages.getPackageApi('@neuralis/agent-core')?.devices;
+    const verdict = devices
+        ? await devices.mayRun({ userId: ctx.userId, grantedFeatures: ctx.grantedFeatures ?? [] }, device)
+        : { ok: false, code: 'devices_unavailable', reason: 'The device plane is not available on this server.' };
+    if (!verdict.ok) {
+        return { ok: false, response: { status: 403, body: { ok: false, code: verdict.code, error: verdict.reason } } };
+    }
+    // A device whose plane is down answers its live reason (the listing's own
+    // probe, cached per device) before git is asked — never an empty repo.
+    const probe = await connector.probeConnection();
+    if (!probe.connected)
+        return { ok: false, response: gitDeviceUnavailable(probe.reason ?? 'store_unreachable') };
+    return { ok: true, place: { root: connector.root, device: { transport: connector.transport, owner: verdict.owner } } };
+}
+/**
+ * The E1 braces on a DEVICE folder: membership in the discovered set (which
+ * admitted only real, non-symlinked child directories with a real `.git`, see
+ * `scanDeviceDepth1RepoChildren`) plus a FRESH `.git` stat on the device. A
+ * device answers inside its owner's ceiling and never follows a link out of it;
+ * the child's own `.git` redirect is clamped again by the engine's floor 1b at
+ * the first spawn.
+ */
+async function resolveNestedRepoPlace(sourcePlace, repo) {
+    const seat = sourcePlace.device;
+    if (!seat) {
+        const nestedRoot = await resolveNestedRepoRoot(sourcePlace.root, repo);
+        return nestedRoot ? { root: nestedRoot } : null;
+    }
+    const discovered = await discoverSourceRepoRoots({ root: sourcePlace.root, device: { transport: seat.transport } });
+    if (!discovered.some((entry) => entry.rel === repo))
+        return null;
+    const nested = childPlace(sourcePlace, repo);
+    try {
+        const p = seat.transport.flavour === 'win32' ? path.win32 : path.posix;
+        if ((await seat.transport.stat(p.join(nested.root, '.git'))) === null)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { root: nested.root, device: { transport: seat.transport, owner: seat.owner } };
 }
 /**
  * E1 `repo` syntactic whitelist — ONE path segment (no `/` or `\`), 1–128
@@ -434,24 +504,16 @@ async function hasNestedDotGit(nestedRoot) {
         return false;
     }
 }
-function resolveLocalRootForSource(services, source) {
-    const connector = services.infra?.connectors?.resolveBySource?.(source) ?? null;
-    if (connector instanceof LocalDiskConnector)
-        return connector.root;
-    return null;
-}
 async function handleGitStatus(req, state) {
     const resolved = await resolveGitSource(req, state);
     if (!resolved.ok)
         return resolved.response;
-    const status = await getSourceGitStatus(resolved.root);
-    // Fail-soft: a non-repo / slow / broken checkout yields an empty change-set,
-    // never an error (the source-row indicator already told the UI it is a repo).
+    const status = await getSourceGitStatus(resolved.place);
+    // A non-repo / slow / broken checkout is a typed refusal like /git/outgoing's —
+    // an empty `ok:true` change-set reads as "No changes". The sentence is fixed:
+    // git's stderr carries host paths (invariant 9).
     if (!status) {
-        return {
-            status: 200,
-            body: { ok: true, status: { branch: null, staged: [], unstaged: [], untracked: [] } },
-        };
+        return { status: 200, body: { ok: false, code: 'unavailable', error: 'Git status is unavailable for this folder.' } };
     }
     // Q1 closure: drop per-path read-denied file NAMES from every bucket BEFORE
     // capping (a root-allowed caller must not enumerate a `<sub>/**`-denied path;
@@ -468,12 +530,15 @@ async function handleGitStatus(req, state) {
     // this reads FILES, so counting one the caller may not see would be work done
     // on their behalf on content they are not allowed to know exists.
     // Tracked rows already carry their numbers from `getSourceGitStatus`.
-    const untrackedBudget = getBrainConfigNumber('brainGitUntrackedCountCap', undefined, 200);
+    // A device folder's untracked files carry no number: counting reads every
+    // file over the link (one `stat` + one range read each, ~15 ms per RPC), which
+    // the panel's refresh cannot afford — absent means "no number", never zero.
+    const untrackedBudget = resolved.place.device ? 0 : getBrainConfigNumber('brainGitUntrackedCountCap', undefined, 200);
     if (untrackedBudget > 0 && capped.untracked.length > 0) {
         const targets = capped.untracked.slice(0, untrackedBudget).map((c) => c.path);
         const counts = await countUntrackedAdditions(resolved.root, targets, {
             maxBytes: UNTRACKED_MAX_BYTES,
-            timeoutMs: getBrainConfigNumber('brainGitPanelTimeoutMs', undefined, 5000),
+            timeoutMs: getBrainConfigNumber('brainGitPanelTimeoutMs', undefined, 15000),
         });
         capped.untracked = capped.untracked.map((c) => {
             const n = counts.get(c.path);
@@ -525,7 +590,7 @@ async function handleGitBranch(req, state) {
     const resolved = await resolveGitSource(req, state);
     if (!resolved.ok)
         return resolved.response;
-    const branches = await getSourceBranches(resolved.root);
+    const branches = await getSourceBranches(resolved.place);
     if (!branches) {
         return { status: 200, body: { ok: true, branches: [] } };
     }
@@ -596,7 +661,7 @@ async function handleGitDiff(req, state) {
     // `getSourceGitDiff` passes the repo-relative path straight into
     // `GitRunner.diff`, whose containment floor rejects any escape (→ null →
     // empty diff here).
-    const result = await getSourceGitDiff(resolved.root, rawPath, target);
+    const result = await getSourceGitDiff(resolved.place, rawPath, target);
     if (result && !result.ok) {
         // The engine KILLED the read past its ~4 MB accumulation bound (MINOR-6):
         // there is no leading-hunk prefix to serve, so this is a typed refusal
@@ -651,7 +716,7 @@ async function handleGitShow(req, state) {
     const resolved = await resolveGitSource(req, state, { policyPath: rawPath });
     if (!resolved.ok)
         return resolved.response;
-    const result = await getSourceGitShow(resolved.root, rawPath, rev);
+    const result = await getSourceGitShow(resolved.place, rawPath, rev);
     if (!result) {
         // Fail-soft: non-repo / path missing at the rev / timeout — never an error
         // that leaks path detail.
@@ -695,7 +760,7 @@ async function handleGitLog(req, state) {
     const skip = Number.isFinite(skipRaw) && skipRaw > 0 ? Math.min(skipRaw, MAX_LOG_SKIP) : 0;
     const ref = typeof req.query?.ref === 'string' && req.query.ref ? req.query.ref : undefined;
     // Fail-soft: an empty repo (no commits) / slow / broken checkout → `commits:[]`.
-    const result = await getSourceGitLog(resolved.root, {
+    const result = await getSourceGitLog(resolved.place, {
         maxCount: maxCount + 1,
         ...(skip > 0 ? { skip } : {}),
         ...(ref ? { ref } : {}),
@@ -756,7 +821,7 @@ async function handleGitLogStats(req, state) {
     const skipRaw = typeof req.query?.skip === 'string' ? Number.parseInt(req.query.skip, 10) : NaN;
     const skip = Number.isFinite(skipRaw) && skipRaw > 0 ? Math.min(skipRaw, MAX_LOG_SKIP) : 0;
     const ref = typeof req.query?.ref === 'string' && req.query.ref ? req.query.ref : undefined;
-    const result = await getSourceGitLogStats(resolved.root, {
+    const result = await getSourceGitLogStats(resolved.place, {
         maxCount,
         ...(skip > 0 ? { skip } : {}),
         ...(ref ? { ref } : {}),
@@ -828,7 +893,7 @@ async function handleGitCommitFiles(req, state) {
     const resolved = await resolveGitSource(req, state);
     if (!resolved.ok)
         return resolved.response;
-    const files = await getSourceGitCommitFiles(resolved.root, sha);
+    const files = await getSourceGitCommitFiles(resolved.place, sha);
     if (!files) {
         return { status: 200, body: { ok: false, code: 'unavailable', sha } };
     }
@@ -856,7 +921,7 @@ async function handleGitOutgoing(req, state) {
     const resolved = await resolveGitSource(req, state);
     if (!resolved.ok)
         return resolved.response;
-    const outgoing = await getSourceGitOutgoing(resolved.root);
+    const outgoing = await getSourceGitOutgoing(resolved.place);
     if (!outgoing) {
         // Dialect unification (3b): a DEEP failure (non-repo / unborn HEAD / any git
         // error → `getSourceGitOutgoing` returns null) is a typed refusal, matching
@@ -901,7 +966,7 @@ async function handleGitRepos(req, state) {
     const resolved = await resolveGitSource(req, state, { ignoreRepo: true });
     if (!resolved.ok)
         return resolved.response;
-    const discovered = await discoverSourceRepoRoots(resolved.root);
+    const discovered = await discoverSourceRepoRoots(resolved.place);
     // Q1 closure (m3): per-path READ-gate the NESTED repo DIRS — the exact call
     // the file tree already makes (`filterVisibleRepoNames`, `${source}://<rel>/`).
     // The root-repo `rel:''` row is source-root-gated already (a `${source}:///`
@@ -915,7 +980,7 @@ async function handleGitRepos(req, state) {
     const repos = await Promise.all(visibleRepos.map(async (entry) => {
         // Branch enrichment is the on-demand step split OFF the discovery
         // (MINOR-5); fail-soft — any git problem just omits the branch.
-        const summary = await getSourceGitSummary(entry.root);
+        const summary = await getSourceGitSummary(entry.place);
         return {
             rel: entry.rel,
             name: entry.name,
@@ -932,7 +997,7 @@ async function handleGitRepos(req, state) {
 }
 /**
  * Per-repo write capability for a `/git/repos` row (MAJOR-C tail) — the SAME
- * two-plane gate as `resolveGitCanWrite` (the caller must HOLD `drive.write`
+ * two-plane gate as `resolveGitCanWrite` (the caller must HOLD `files.write`
  * AND the resolved uri-policy `write` must allow), evaluated at the REPO
  * granularity `<slug>://<repo>/`: root-level canWrite is the wrong
  * granularity in both directions — a `<repo>/**` write-deny must flip that
@@ -949,7 +1014,7 @@ function resolveRepoCanWrite(resolved, rel) {
         return false;
     if (rel === '')
         return resolveGitCanWrite(permissions, source, createdBy, ctx);
-    if (!hasFeature({ grantedFeatures: ctx.grantedFeatures }, 'drive.write'))
+    if (!hasFeature({ grantedFeatures: ctx.grantedFeatures }, 'files.write'))
         return false;
     return (resolvePermissions(permissions, `${source}://${rel}/`, {
         userId: ctx.userId,
@@ -965,7 +1030,7 @@ function resolveRepoCanWrite(resolved, rel) {
  * Per-repo REMOTE-op capability (NIT-2) — the uri-policy `exec` capability at
  * the repo granularity `<slug>://[<rel>/]`, exactly what the remote-op route
  * gates on (`resolveGitSource({capability:'exec'})`). Unlike canWrite this does
- * NOT gate `drive.write` (the route gates that separately) — it reflects ONLY
+ * NOT gate `files.write` (the route gates that separately) — it reflects ONLY
  * whether `exec` is granted, so the panel can show a precise "grant exec to
  * enable remote ops" affordance. PURE — no git I/O.
  */
@@ -1035,7 +1100,7 @@ function filterReadableChanges(resolved, rows) {
     });
 }
 // ---------------------------------------------------------------------------
-// WRITE handlers (G2.3) — the HUMAN face; each gates `drive.write` + uri-policy
+// WRITE handlers (G2.3) — the HUMAN face; each gates `files.write` + uri-policy
 // `write`, and returns { ok:true, ... } / a structured error.
 // ---------------------------------------------------------------------------
 async function handleStage(req, state) {
@@ -1062,7 +1127,7 @@ async function handleStage(req, state) {
     }
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1100,7 +1165,7 @@ async function handleUnstage(req, state) {
     }
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1134,7 +1199,7 @@ async function handleDiscard(req, state) {
         return pathDenied;
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1176,7 +1241,7 @@ async function handleCommit(req, state) {
         return resolved.response;
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1209,7 +1274,7 @@ async function handleBranchWrite(req, state) {
         return resolved.response;
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1263,7 +1328,7 @@ async function handleCheckout(req, state) {
         return resolved.response;
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1287,7 +1352,7 @@ async function handleCheckout(req, state) {
  *   - `{kind:'branch', ref:<anchor>, name}` → `git branch <name> <anchor>`
  *     (recreate a deleted branch; NON-force → git 409s on an existing name, never
  *     clobbers a live branch).
- * Gated EXACTLY like the other writes: `drive.write` + uri-policy `write` (root) —
+ * Gated EXACTLY like the other writes: `files.write` + uri-policy `write` (root) —
  * NO new capability, NO exec, NO per-path gate (stash-apply is whole-WT), NO
  * `PendingInteraction` (a human-consent WRITE route). The caller-echoed
  * `ref`/`name` are `#guardRef`-validated at the GitRunner boundary (m4). A
@@ -1318,7 +1383,7 @@ async function handleRestore(req, state) {
         return resolved.response;
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1351,7 +1416,7 @@ const GIT_REMOTE = 'origin';
  * POST /git/fetch | /git/pull | /git/push — the network-reaching git ops
  * (G4 keyring-kestrel Slice 2). The security-heaviest git surface:
  *
- *   1. `drive.write` (feature) + uri-policy `exec` on the SOURCE ROOT
+ *   1. `files.write` (feature) + uri-policy `exec` on the SOURCE ROOT
  *      (`capability:'exec'`) — remote ops are exec-class, deny-by-default
  *      (`exec:false` out of the box → 403 with the D4 grant-exec affordance).
  *   2. Derive the remote HOST server-side from the checkout's `origin` URL
@@ -1382,9 +1447,16 @@ async function handleRemoteOp(req, state, op) {
     });
     if (!resolved.ok)
         return resolved.response;
+    // A paired device's folder: its OWNER runs fetch/pull/push there with their own
+    // git credentials on their own machine — no binding or server token is read,
+    // and nothing of this server's crosses the link. Anyone else is refused: the
+    // only credential on that machine is the owner's, and using it for another
+    // person would be borrowing it.
+    if (resolved.place.device)
+        return handleDeviceRemoteOp(resolved, op);
     let runner;
     try {
-        runner = await GitRunner.create({ containerRoot: resolved.root });
+        runner = await GitRunner.create({ root: resolved.place });
     }
     catch (error) {
         return gitWriteError(error, resolved.root);
@@ -1414,7 +1486,7 @@ async function handleRemoteOp(req, state, op) {
         projectId: ctx.projectId,
         ...(ctx.agentId ? { agentId: ctx.agentId } : {}),
         callerId: '@neuralis/brain-core',
-        callerTrust: 'first-party',
+        callerTrust: 'native',
         ...(ctx.grantedFeatures ? { grantedFeatures: ctx.grantedFeatures } : {}),
     };
     const agentCore = state.ctx.packages.getPackageApi('@neuralis/agent-core', session);
@@ -1455,12 +1527,58 @@ async function handleRemoteOp(req, state, op) {
     catch (error) {
         return gitWriteError(error, resolved.root);
     }
-    invalidateSourceGitCache(resolved.root);
+    invalidateSourceGitCache(resolved.place);
     publishInAppGitBadge(resolved.services, resolved.ctx, resolved.source);
     // fetch/pull re-read status so the UI shows TRUE divergence immediately.
     const body = { ok: true, op, host };
     if (op !== 'push') {
-        const status = await getSourceGitStatus(resolved.root);
+        // The op landed: a status the device can no longer answer only leaves it out.
+        const status = await getSourceGitStatus(resolved.place).catch(() => null);
+        if (status)
+            body.status = capStatus(status);
+    }
+    return { status: 200, body };
+}
+/** fetch / pull / push on a device folder — its owner's own git, on that device. */
+async function handleDeviceRemoteOp(resolved, op) {
+    if (resolved.place.device?.owner !== true) {
+        return {
+            status: 409,
+            body: { ok: false, code: 'git_remote_owner_only', error: "Only the device's owner fetches, pulls and pushes a folder on it — with their own git credentials there." },
+        };
+    }
+    let runner;
+    let host;
+    try {
+        runner = await GitRunner.create({ root: resolved.place });
+        host = await runner.remoteHost(GIT_REMOTE, { push: op === 'push' });
+    }
+    catch (error) {
+        return gitWriteError(error, resolved.root);
+    }
+    if (!host) {
+        return {
+            status: 409,
+            body: { ok: false, code: 'no_https_remote', error: 'This checkout has no HTTPS remote configured (SSH remotes are not supported).' },
+        };
+    }
+    try {
+        if (op === 'fetch')
+            await runner.fetch({ remote: GIT_REMOTE });
+        else if (op === 'push')
+            await runner.push({ remote: GIT_REMOTE });
+        else
+            await runner.pull({ remote: GIT_REMOTE });
+    }
+    catch (error) {
+        return gitWriteError(error, resolved.root);
+    }
+    invalidateSourceGitCache(resolved.place);
+    publishInAppGitBadge(resolved.services, resolved.ctx, resolved.source);
+    const body = { ok: true, op, host };
+    if (op !== 'push') {
+        // The op landed: a status the device can no longer answer only leaves it out.
+        const status = await getSourceGitStatus(resolved.place).catch(() => null);
         if (status)
             body.status = capStatus(status);
     }
@@ -1470,17 +1588,17 @@ async function handleRemoteOp(req, state, op) {
 // WRITE helpers
 // ---------------------------------------------------------------------------
 /**
- * The `drive.write` feature gate for every WRITE route. Checked FIRST (before the
+ * The `files.write` feature gate for every WRITE route. Checked FIRST (before the
  * source is resolved) so a write-lacking caller gets a UNIFORM 403 regardless of
  * whether the source exists — no existence inference. The file-level `feature`
- * export only guarantees `drive.read`; the mutation op-class needs `drive.write`.
+ * export only guarantees `files.read`; the mutation op-class needs `files.write`.
  */
 function denyIfNoWrite(req) {
-    if (hasFeature(req.session, 'drive.write'))
+    if (hasFeature(req.session, 'files.write'))
         return null;
     return {
         status: 403,
-        body: { error: "Forbidden: missing feature 'drive.write'", code: 'feature_denied', feature: 'drive.write' },
+        body: { error: "Forbidden: missing feature 'files.write'", code: 'feature_denied', feature: 'files.write' },
     };
 }
 /**
@@ -1544,7 +1662,7 @@ async function guardWritePaths(resolved, paths) {
  * SOURCE-scoped — an in-source over-refresh is fine.
  */
 function finishWrite(resolved, extra) {
-    invalidateSourceGitCache(resolved.root);
+    invalidateSourceGitCache(resolved.place);
     publishInAppGitBadge(resolved.services, resolved.ctx, resolved.source);
     return { status: 200, body: { ok: true, ...extra } };
 }
@@ -1556,6 +1674,8 @@ function finishWrite(resolved, extra) {
  *     unmerged branch delete, …) → 409 with git's own (repo-relative) message.
  */
 function gitWriteError(error, root) {
+    if (error instanceof GitDeviceUnavailableError)
+        return gitDeviceUnavailable(error.reason);
     if (error instanceof GitArgumentError || error instanceof GitOutsideSourceError) {
         return { status: 400, body: { ok: false, code: error.code, error: scrubHostPath(error.message, root) } };
     }
@@ -1566,6 +1686,15 @@ function gitWriteError(error, root) {
     const message = error instanceof Error ? error.message : 'git operation failed';
     return { status: 409, body: { ok: false, code, error: scrubHostPath(message, root) } };
 }
+/**
+ * git could not run on a paired device — its plane is down (`devices_disabled`,
+ * `runtime_offline`, `broker_outdated`, …) or it refused the spawn
+ * (`others_denied`, …). ONE answer for reads and writes: the fixed code, never
+ * the broker's text.
+ */
+function gitDeviceUnavailable(reason) {
+    return { status: 409, body: { ok: false, code: 'git_device_unavailable', reason, error: `git could not run on the device (${reason})` } };
+}
 /** Replace any leaked container-root prefix in a git message with `<repo>`. */
 function scrubHostPath(message, root) {
     return root ? message.split(root).join('<repo>') : message;