@neuralis/brain-core 0.3.2 → 0.4.0

package/dist/src/routes/sources.js

@@ -18,9 +18,13 @@
  *   POST   /sources/reset                    — reset sync state (cancels active job)
  *   GET    /sources/sync-status              — job status (?source= single, else all visible)
  *   POST   /sources/enabled                  — light enable/disable toggle (W3K)
- *   GET    /sources/browse                   — browse filesystem directories (sources.mount;
- *                                              protected zones + the fs root need
- *                                              sources.privileged)
+ *   GET    /sources/browse                   — one level of folders: on this server
+ *                                              (sources.mount; protected zones + the
+ *                                              fs root need sources.privileged; in
+ *                                              Docker under /mounts), or with
+ *                                              ?device= on the caller's OWN device
+ *                                              (device.own; empty path = the
+ *                                              folders it allows this host)
  *   GET    /sources/health                   — get sources health
  *
  * Sync-shaped POSTs return 202 + a SyncQueueJobSnapshot: the run executes on
@@ -28,19 +32,27 @@
  * froze the host on repo-sized sources).
  */
 import { existsSync } from 'node:fs';
-import { isAbsolute, resolve as resolvePath } from 'node:path';
-import { canAccessScope, isHostPlaneKind, isSourceScope } from '@neuralis/package-system/contracts';
-import { hasFeature, BUILTIN_ROLE_PRIORITY } from '@neuralis/package-system/access';
+import { dirname as dirnameOf, isAbsolute, resolve as resolvePath } from 'node:path';
+import { HOST_SOURCE_KIND, canAccessScope, isConnectorPlaneExecKind, isSourceScope, sourcePlane } from '@neuralis/package-system/contracts';
+// `isOwnerOrAdminEffective` gates the code-LOAD surface (`packageFolders`): the
+// ordinal, never a role name — the Sources panel hides the field with the SAME call.
+import { hasFeature, isOwnerOrAdminEffective } from '@neuralis/package-system/access';
 import { assertImmutablePolicyFloorsPreserved, CallerPolicyFloorError, containsPolicyFloorMarker, ImmutablePolicyFloorError, } from '@neuralis/package-system/policies';
-import { protectedRootPaths, seedExcludedMachineWrittenGlobs } from '@neuralis/package-system/paths';
-import { resolveLocalRoot, LocalDiskConnector } from '../connectors/LocalDiskConnector.js';
+import { hostPathFlavour, isFilesystemRoot, isPathInside, protectedRootPaths, seedExcludedMachineWrittenGlobs } from '@neuralis/package-system/paths';
+import { NEURALIS_TREE_ANCHOR, resolveLocalRoot, resolvedLocalRootOrNull } from '../connectors/inProcessTransport.js';
+import { SOURCE_ANCHOR_UNRESOLVABLE, admitSourceRoot, unlessAnchorUnresolvable } from '../usecases/admitSourceRoot.js';
+import { HostConnector } from '../connectors/HostConnector.js';
+import { listAttachableDevices } from '../usecases/listAttachableDevices.js';
+import { browseDeviceFolders, browseServerFolders } from '../usecases/browseSourceFolders.js';
 import { filterVisibleRepoNames, getSourceGitSummary, resolveGitCanWrite, resolveGitCanExec } from '../git/sourceGitControl.js';
+import { probePlaceOf } from '../git/gitPlace.js';
 import { matchDeclaredSource, isOwnDataZoneDeclaration } from '../services/declaredSources.js';
 import { platformRegistries } from '../wiring.js';
-import { resolveSourceDescription } from '../domain/sourceConfig.js';
+import { resolveSourceDescription, validatePackageFolders, sourceScopeOrigin } from '../domain/sourceConfig.js';
 import { extractCtx, ensureAccess, getServices, toPublicSourceConfig, toScopeAccessCtx, isPermissions, normalizePermissions, isSyncConfig } from './helpers.js';
 import { EmbeddingScopeLimitError } from '../sync/SyncJobQueue.js';
 import { canReadUri } from '../domain/access/uriReadable.js';
+import { NATIVE_LOCAL_EDIT_REFUSAL, NATIVE_LOCAL_REFUSAL, attachableNatively, fencedEditWidens, nativeLocalFenceApplies, nativeLocalPlacement, nativeLocalRootRefused } from '../domain/access/nativeLocalFence.js';
 import { listScopeDocumentUris, estimateScopedReembed } from '../usecases/vector/estimate.js';
 import { embeddingEnabled, resolveActiveEmbeddingShape } from '../config/env.js';
 import { parsePurgeSelector, purgeSourceSelection } from '../usecases/purgeExcludedPoints.js';
@@ -48,7 +60,7 @@ export const pattern = 'sources/*';
 export const feature = 'files.read';
 // The module gate is the read tier (listing a source is member-visible); every
 // mutating / enumerating arm escalates in-handler through `hasRouteFeature`.
-// A host-plane (paired-device) source is attached by its owner under
+// A device-plane (paired-device) source is attached by its owner under
 // `device.own`, which agent-core's device gate answers — not a gate here.
 export const escalations = [
     'sources.mount',
@@ -73,6 +85,11 @@ export const GET = async (req, raw) => {
     if (sub === 'sync-status') {
         return handleSyncStatus(req, state);
     }
+    if (sub === 'devices') {
+        const ctx = extractCtx(req);
+        await ensureAccess(ctx, state);
+        return { status: 200, body: await listAttachableDevices(state.ctx.packages, ctx.userId) };
+    }
     if (sub === 'health') {
         const ctx = extractCtx(req);
         await ensureAccess(ctx, state);
@@ -100,17 +117,18 @@ export const GET = async (req, raw) => {
     // against the declared sources (unspoofable slug+kind+resolved-root) so the
     // Sources panel can group rows by their owning package; user mounts → null.
     const infra = await state.infraFactory.getInfra(ctx.projectId);
-    const matchCtx = { projectRoot: infra?.projectRoot ?? '', appRoot: state.ctx.platform.runtimeStack().appRoot };
+    const matchCtx = { projectRoot: infra?.projectRoot ?? '', appRoot: state.ctx.platform.runtimeStack().appRoot, isDocker: state.ctx.platform.runtimeStack().isDocker };
     const declsByPkg = state.ctx.platform.packageSourceDeclarations();
     const dataSyncExclude = seedExcludedMachineWrittenGlobs(state.ctx.platform.machineWrittenPaths());
     // The projection reads every row's config from the listing already in hand,
     // so the per-row root-read check costs no config fetch.
-    const protectedRoots = buildProtectedRoots(state.ctx.platform.runtimeStack());
+    const stack = state.ctx.platform.runtimeStack();
+    const protectedRoots = buildProtectedRoots(stack);
     const configCache = new Map(allConfigs.map((c) => [c.source, c]));
     // Source-level git indicator (G2.1 / spellbound-heron) — the CONFIG-panel half
     // of the two summary builders (the TREE half is `FilesystemService.list`;
     // MAJOR-1 — BOTH must be enriched). CHEAP + bounded O(1)/source: for each
-    // git-backed LOCAL source, resolve its connector root and stamp
+    // git-backed `host` folder (this server's or a device's — read without a spawn), resolve its root and stamp
     // `git = { isRepo, repoName, branch }` from `getSourceGitSummary` (a `.git` stat + an
     // O(1) `.git/HEAD` branch read, TTL-cached — never the whole-repo status).
     // Runs on `allConfigs` AFTER `listSourceConfigs`'s scope filter (leak-safe).
@@ -122,7 +140,7 @@ export const GET = async (req, raw) => {
         const origin = matched?.originPackage ?? null;
         const git = await resolveSourceGit(config, infra, ctx);
         const readable = await rootReadable(infra, ctx, config.source, configCache);
-        const view = await sourceConfigView(req.session, config, infra?.projectRoot ?? '', protectedRoots, readable, deviceAttachVerdict(state, ctx, config.connection), !config.sync && matched && isOwnDataZoneDeclaration(matched.originPackage, matched.decl, state.ctx.selfId) ? dataSyncExclude : undefined);
+        const view = await sourceConfigView(req.session, config, infra?.projectRoot ?? '', stack.isDocker, protectedRoots, readable, deviceAttachVerdict(state, ctx, config.connection), !config.sync && matched && isOwnDataZoneDeclaration(matched.originPackage, matched.decl, state.ctx.selfId) ? dataSyncExclude : undefined);
         return {
             ...toPublicSourceConfig(config, view),
             // DERIVED, never persisted — the same chain the `<runtime_stack>`
@@ -140,7 +158,7 @@ export const GET = async (req, raw) => {
             origin_package: origin,
             orphan: !metadata, embedding_enabled: embeddingEnabled(),
             canMaintain: hasRouteFeature(req.session, 'sources.mount') && hasRouteFeature(req.session, 'sources.sync')
-                && canAccessScope(config.scope, access, 'write') && readable,
+                && canAccessScope(config.scope, access, 'write', sourceScopeOrigin(config.connection)) && readable,
             orphan_hint: metadata ? null : `Package contributing kind "${config.connection.kind}" is missing — remove the source or reinstall the package.`,
             ...(git ? { git } : {}),
         };
@@ -149,8 +167,8 @@ export const GET = async (req, raw) => {
 };
 /**
  * Resolve the source-row git indicator for `GET /sources` (G2.1). Returns
- * `{ isRepo: true, repoName?, branch? }` for a git-backed LOCAL source — or,
- * E1 (MAJOR-C), `{ isRepo: false, containsRepos: true }` for a LOCAL source
+ * `{ isRepo: true, repoName?, branch? }` for a git-backed `host` folder — or,
+ * E1 (MAJOR-C), `{ isRepo: false, containsRepos: true }` for a folder
  * whose NON-repo root contains nested depth-1 checkouts (the drop condition is
  * `isRepo || containsRepos`; without the widening the field never reaches the
  * client and the multi-repo picker is dead-on-arrival). `undefined` for
@@ -162,12 +180,12 @@ export const GET = async (req, raw) => {
  * never a host path. Fail-soft: any git problem yields `undefined`.
  */
 async function resolveSourceGit(config, infra, ctx) {
-    if (config.connection?.kind !== 'local')
+    if (!config.connection || sourcePlane(config.connection.kind ?? '', config.connection.config) === 'connector')
         return undefined;
     const connector = infra?.connectors?.resolveBySource?.(config.source) ?? null;
-    if (!(connector instanceof LocalDiskConnector))
+    if (!(connector instanceof HostConnector))
         return undefined;
-    const summary = await getSourceGitSummary(connector.root);
+    const summary = await getSourceGitSummary(probePlaceOf(connector));
     if (!summary)
         return undefined;
     if (!summary.isRepo) {
@@ -219,7 +237,7 @@ export const POST = async (req, raw) => {
         }
         const { bridge, infra } = await getServices(state, ctx.projectId);
         const config = await bridge.getSourceConfig(ctx, source, toScopeAccessCtx(ctx));
-        if (!config || !canAccessScope(config.scope, toScopeAccessCtx(ctx), 'write')) {
+        if (!config || !canAccessScope(config.scope, toScopeAccessCtx(ctx), 'write', sourceScopeOrigin(config.connection))) {
             return { status: 404, body: { error: 'Source not found.' } };
         }
         try {
@@ -265,6 +283,14 @@ async function handleKindsList(state) {
         packageId: m.packageId,
         trust: m.packageTrust,
         capabilities: [...m.capabilities].sort(),
+        // Can a shell run in this kind's sources at all — the `host` kind's own
+        // planes (the S1 uri-policy shell, the device's broker) or a connector that
+        // declares `exec`? The kernel's two plane predicates answer; the form offers
+        // the Exec policy bit exactly then. `execRequires` (the entry features) is
+        // information for its tooltip, never a reason to hide the bit — an owner may
+        // set `exec` for members who hold them.
+        shell: sourcePlane(m.kind) !== 'connector' || isConnectorPlaneExecKind(m.kind, m.capabilities),
+        ...(m.execRequires?.length ? { execRequires: [...m.execRequires] } : {}),
         runtimeGated: m.runtimeGated,
         urlScheme: m.uri?.suggestedScheme ?? m.kind,
         configSchema: m.configSchema,
@@ -334,6 +360,7 @@ async function withEffectiveDescription(config, state, ctx, session) {
     const matched = matchDeclaredSource(config, state.ctx.platform.packageSourceDeclarations(), {
         projectRoot: infra?.projectRoot ?? '',
         appRoot: state.ctx.platform.runtimeStack().appRoot,
+        isDocker: state.ctx.platform.runtimeStack().isDocker,
     });
     return {
         ...toPublicSourceConfig(config, await publicViewFor(session, ctx, config, state, infra)),
@@ -357,7 +384,7 @@ async function handleSourcesCreate(req, state, preflight = false) {
     const description = body?.description;
     // `null` = absent. A read-then-resend caller (the manage-sources skill's jq
     // projection) legitimately round-trips a field the listing never carried.
-    const recognizesPackages = body?.recognizesPackages ?? undefined;
+    const packageFolders = body?.packageFolders ?? undefined;
     if (!source)
         return { status: 400, body: { error: 'Missing source' } };
     if (description !== undefined && typeof description !== 'string') {
@@ -382,13 +409,13 @@ async function handleSourcesCreate(req, state, preflight = false) {
             },
         };
     }
-    // R2b — `recognizesPackages` is a code-LOAD surface (it turns a source into a
-    // WASM-package source). Mirror the PATCH gate: boolean, owner/admin-effective,
-    // local-kind only. Validated here BEFORE the access check so a malformed value
-    // is a 400 regardless of role.
-    if (recognizesPackages !== undefined && typeof recognizesPackages !== 'boolean') {
-        return { status: 400, body: { error: 'recognizesPackages must be a boolean if provided' } };
-    }
+    // R2b — `packageFolders` is a code-LOAD surface (it turns folders of a source
+    // into package sources). Mirror the PATCH gate: source-relative folders,
+    // owner/admin-effective, folder kind only. Validated here BEFORE the access
+    // check so a malformed value is a 400 regardless of role.
+    const packageFoldersError = packageFolders === undefined ? undefined : validatePackageFolders(packageFolders, connection)[0];
+    if (packageFoldersError)
+        return { status: 400, body: { error: packageFoldersError } };
     await ensureAccess(ctx, state);
     // A source on the caller's OWN paired device: its owner with `device.own`
     // satisfies the whole attach stack (`sources.mount` included). On the host
@@ -397,12 +424,20 @@ async function handleSourcesCreate(req, state, preflight = false) {
     if (!ownDevice.allowed && !hasRouteFeature(req.session, 'sources.mount')) {
         return { status: 403, body: { error: 'Creating sources requires sources.mount.' } };
     }
-    if (recognizesPackages !== undefined && !isOwnerOrAdminEffective(req.session)) {
-        return { status: 403, body: { error: 'Setting recognizesPackages requires an owner/admin-effective role.' } };
-    }
-    if (recognizesPackages === true && connection.kind !== 'local') {
-        return { status: 400, body: { error: 'recognizesPackages may only be true for local-kind sources.' } };
+    if (packageFolders !== undefined && !isOwnerOrAdminEffective(req.session)) {
+        return { status: 403, body: { error: 'Setting packageFolders requires an owner/admin-effective role.' } };
     }
+    // The root PAIR is derived HERE, before any gate, so every gate below judges
+    // the pair that will be stored and mounted on either plane.
+    const paired = admitSourceRoot({
+        connection: connection,
+        stack: state.ctx.platform.runtimeStack(),
+        mayHandSet: hasRouteFeature(req.session, PRIVILEGED_MOUNT_FEATURE),
+        audit: state.ctx.hostPorts?.audit,
+    });
+    if ('status' in paired)
+        return paired;
+    const pairedConnection = paired.connection;
     // fenced-courtyard (HEALTH1 B3) — privileged-root ADD gate. `sources.mount`
     // attaches ordinary sources, but attaching a source rooted IN, OVER, or AT a
     // protected host zone (App Zone, the Neuralis tree, the whole host) requires
@@ -413,46 +448,62 @@ async function handleSourcesCreate(req, state, preflight = false) {
     // `..` / trailing-slash / a Docker free-root attach with no suggestion). The
     // requested root is resolved with `resolveLocalRoot` — the SAME canonicaliser
     // the connector uses — so the gate sees exactly what will be mounted.
-    // The HOST plane is decided BEFORE the root-sensitive container gate below:
+    // The DEVICE plane is decided BEFORE the root-sensitive container gate below:
     // the device's owner with `device.own`, nobody else, with no root-string
     // inspection and no `protectedRoots.length` precondition (fail closed even
     // when the runtime stack is unavailable; a sub-directory is gated like `/`).
-    // The container-plane arm is kind-AGNOSTIC (see `missingAttachFeature`).
-    const missingForAttach = await missingAttachFeature(req.session, connection, buildProtectedRoots(state.ctx.platform.runtimeStack()), async (root) => resolveLocalRoot({ configured: root, projectRoot: (await state.infraFactory.getInfra(projectId)).projectRoot ?? '', source }).resolvedRoot, ownDevice);
+    // The local-plane arm is kind-AGNOSTIC (see `missingAttachFeature`).
+    const missingForAttach = await missingAttachFeature(req.session, pairedConnection, buildProtectedRoots(state.ctx.platform.runtimeStack()), async (root, hostRoot) => resolveLocalRoot({
+        configured: root, hostRoot, projectRoot: (await state.infraFactory.getInfra(projectId)).projectRoot ?? '',
+        isDocker: state.ctx.platform.runtimeStack().isDocker, source,
+    }).resolvedRoot, ownDevice);
     if (missingForAttach) {
         return {
             status: 403,
             body: {
                 error: missingForAttach.plane === 'device'
                     ? "Only the device's owner may attach a source on it."
-                    : missingForAttach.plane === 'host'
-                        ? `Attaching a host-plane source requires the ${missingForAttach.feature} feature.`
+                    : missingForAttach.plane === 'owner'
+                        ? `Attaching a source on your device requires the ${missingForAttach.feature} feature.`
                         : `Attaching a source rooted in a protected host zone requires the ${missingForAttach.feature} feature.`,
             },
         };
     }
+    const fencedAttach = await nativeFenceRefusal(state, projectId, source, pairedConnection);
+    if (fencedAttach)
+        return fencedAttach;
     const bridge = await resolveBridge(state, projectId);
     const scope = { userId: ctx.userId, projectId };
     const existing = await bridge.getSourceConfig(scope, source, toScopeAccessCtx(ctx));
     if (existing)
         return { status: 409, body: { error: `Source already exists: ${source}` } };
-    const normalizedPerms = normalizePermissions(permissions);
+    const normalizedPerms = normalizePermissions(permissions, { rolePriorities: ctx.rolePriorities });
     const normalizedConnection = {
-        kind: connection.kind,
-        config: (connection.config ?? {}),
+        kind: pairedConnection.kind,
+        config: (pairedConnection.config ?? {}),
     };
     const kindMetadata = platformRegistries(state.ctx.platform).sourceKinds.get(normalizedConnection.kind);
     if (!kindMetadata)
         return { status: 400, body: { error: `Unknown source kind "${normalizedConnection.kind}"` } };
-    const sourceScope = resolveRequestedSourceScope(requestedScope, kindMetadata.defaultScope, ctx);
-    const allowedScopes = kindMetadata.allowedScopes ?? (kindMetadata.scopeSelectable ? ['project', 'user', 'agent'] : [kindMetadata.defaultScope]);
+    // A device folder defaults to the attaching owner's USER scope and is never
+    // agent-scoped: `files.read` is a member default, so a project-scoped folder on
+    // somebody's machine is readable project-wide the moment it exists — the owner
+    // widens it on purpose, never by omission.
+    const onDevice = sourcePlane(normalizedConnection.kind, normalizedConnection.config) === 'device';
+    const sourceScope = resolveRequestedSourceScope(requestedScope, onDevice ? 'user' : kindMetadata.defaultScope, ctx);
+    if (!sourceScope) {
+        return { status: 400, body: { code: 'invalid_scope', error: 'scope is "project", "user" or "agent", or an object with one of those kinds' } };
+    }
+    const allowedScopes = onDevice
+        ? DEVICE_FOLDER_SCOPES
+        : kindMetadata.allowedScopes ?? (kindMetadata.scopeSelectable ? ['project', 'user', 'agent'] : [kindMetadata.defaultScope]);
     if (!kindMetadata.scopeSelectable && sourceScope.kind !== kindMetadata.defaultScope) {
         return { status: 400, body: { error: `Kind "${kindMetadata.kind}" is project-scope only.` } };
     }
     if (!allowedScopes.includes(sourceScope.kind)) {
         return { status: 400, body: { error: `Scope "${sourceScope.kind}" is not allowed for kind "${kindMetadata.kind}".` } };
     }
-    if (!canAccessScope(sourceScope, toScopeAccessCtx(ctx), 'write')) {
+    if (!canAccessScope(sourceScope, toScopeAccessCtx(ctx), 'write', sourceScopeOrigin(normalizedConnection))) {
         return { status: 403, body: { error: 'Forbidden for requested source scope' } };
     }
     // Multi-operation callers need every conditional feature refusal before an
@@ -470,8 +521,9 @@ async function handleSourcesCreate(req, state, preflight = false) {
             caller: toSyncCaller(ctx),
             ...(description !== undefined ? { description: description } : {}),
             ...(sync && isSyncConfig(sync) ? { sync: sync } : {}),
-            ...(recognizesPackages !== undefined ? { recognizesPackages: recognizesPackages } : {}),
+            ...(packageFolders !== undefined ? { packageFolders: packageFolders } : {}),
         });
+        paired.auditHandSet?.(ctx.userId, projectId, config.source);
         const infra = await state.infraFactory.getInfra(projectId);
         return { status: 201, body: toPublicSourceConfig(config, await publicViewFor(req.session, ctx, config, state, infra)) };
     }
@@ -488,23 +540,6 @@ async function handleSourcesCreate(req, state, preflight = false) {
 function hasRouteFeature(session, featureId) {
     return hasFeature(session, featureId);
 }
-/**
- * Owner/admin-STRENGTH check (R2), keyed on the ordinal, never on a role NAME
- * (D-A). The built-in anchors are `owner 1 · admin 2 · manager 10 · member 20 ·
- * viewer 30` (lower = stronger, `SessionContext.priority`) and a custom role
- * declares its own number in 1..99 — so the admin ANCHOR is the threshold, and
- * a custom role at priority 1 or 2 passes exactly like the built-ins. A
- * wildcard feature grant (`'*'`) is owner-effective too, resolved through the
- * ONE kernel `hasFeature`. Used to gate code-LOAD surfaces like
- * `recognizesPackages`.
- */
-function isOwnerOrAdminEffective(session) {
-    const s = session;
-    const priority = typeof s?.priority === 'number' ? s.priority : undefined;
-    if (priority !== undefined && priority <= BUILTIN_ROLE_PRIORITY.admin)
-        return true;
-    return hasRouteFeature(session, '*');
-}
 // ---------------------------------------------------------------------------
 // fenced-courtyard (HEALTH1 B3) — the per-discoverable-source access table.
 //
@@ -523,6 +558,24 @@ function isOwnerOrAdminEffective(session) {
 // ---------------------------------------------------------------------------
 /** Feature required to SEE/ADD a high-blast-radius host zone (C8 — no grant below the admin tier). */
 const PRIVILEGED_MOUNT_FEATURE = 'sources.privileged';
+/**
+ * The DEVICE plane (a folder whose stored config names a `device` — a paired
+ * device, outside the container) has ONE attach rule: the device's owner, holding `device.own`,
+ * attaches or edits a source on it, and nobody else does. agent-core's device
+ * gate (`devices.mayAttach`) answers both halves; brain-core keeps no device-plane
+ * feature of its own. `sources.mount` is a MANAGER default and never reaches a
+ * device: a non-owner is refused whatever the role grants, so a manager cannot
+ * attach someone's machine at `/` and get read/write over it through `fs_*`.
+ * That device's own allowlist (`neuralis device grant`) still bounds what the
+ * owner's source can reach.
+ *
+ * The plane is the kernel's `sourcePlane` (`@neuralis/package-system/contracts`)
+ * over the STORED connection — imported, never re-declared. Two copies of a plane
+ * predicate is how the attach gate and the terminal gate drift apart while both
+ * look correct in isolation.
+ */
+/** The scopes a device folder may be attached at — never `agent` (see `handleSourcesCreate`). */
+const DEVICE_FOLDER_SCOPES = ['user', 'project'];
 /**
  * Build the filter-free protected-root table from the runtime stack. App Zone,
  * the Neuralis source tree, and the whole host (`/`) all require
@@ -539,16 +592,22 @@ export function buildProtectedRoots(stack) {
 }
 /**
  * Containment in BOTH directions, canonical paths. Fires when the requested
- * root IS, is UNDER, or is an ANCESTOR of a protected root — except `/`, which
- * matches only an exact whole-host request (it is everyone's ancestor).
+ * root IS, is UNDER, or is an ANCESTOR of a protected root — except a
+ * filesystem root (`/`, a Windows drive root), which matches only a whole-host
+ * request (it is everyone's ancestor): `/`, or any drive root (`D:\`).
+ *
+ * The comparison runs in the path flavour of the zone itself: a protected root
+ * is a canonical host path, so a drive-letter or UNC form IS a Windows host —
+ * backslashes, drive roots and case-insensitive names.
  */
 function rootMatches(requested, protectedRoot, mode = 'containment') {
-    if (protectedRoot === '/')
-        return requested === '/';
-    if (requested === protectedRoot)
-        return true;
-    if (requested.startsWith(`${protectedRoot}/`))
-        return true; // requested is under the zone (subpath attach)
+    const p = hostPathFlavour(protectedRoot);
+    if (isFilesystemRoot(protectedRoot))
+        return isFilesystemRoot(requested);
+    if (!p.isAbsolute(requested))
+        return false;
+    if (isPathInside(protectedRoot, requested, p))
+        return true; // IS the zone, or under it (subpath attach)
     // The ANCESTOR arm belongs to ATTACH, not to enumeration. Attaching `/home`
     // hands over everything below it, so exposing a zone from above is the same
     // act; LISTING `/home` one level deep does not, and the browse handler drops
@@ -558,7 +617,7 @@ function rootMatches(requested, protectedRoot, mode = 'containment') {
     // opens at `/`, so the first click would deny with no route downward. The
     // zone itself stays protected: `is-or-under` still fires on it, and the
     // handler filters protected CHILDREN out of the listing it returns.
-    if (mode === 'containment' && protectedRoot.startsWith(`${requested}/`))
+    if (mode === 'containment' && isPathInside(requested, protectedRoot, p))
         return true;
     return false;
 }
@@ -586,40 +645,41 @@ export function requiredFeaturesForRoot(root, protectedRoots, kind, mode = 'cont
  * the listing projection, so "you see the path you could attach" cannot drift
  * from what attaching requires.
  *
- * - Host plane: the DEVICE's owner holding `device.own` (`ownDevice`,
+ * - Device plane: the DEVICE's owner holding `device.own` (`ownDevice`,
  *   agent-core's device gate) and nobody else — a non-owner is refused as
  *   `device`, an owner without `device.own` is told the feature it lacks; no
  *   root inspection and no runtime-stack precondition (fail closed).
- * - Container plane, kind-AGNOSTIC: any kind whose config carries a string
- *   `root` — `local`, and every root-bearing kind a package registers later —
+ * - Local plane, kind-AGNOSTIC: any kind whose config carries a string
+ *   `root` — the in-process folder, and every root-bearing kind a package registers later —
  *   resolves through `resolveRoot` (the connector's own canonicaliser) and hits
  *   the SAME containment table. Scoping this to one kind is how a newly
  *   registered root-bearing kind walks straight past the gate.
  */
 async function missingAttachFeature(session, connection, protectedRoots, resolveRoot, ownDevice) {
-    if (isHostPlaneKind(connection.kind)) {
+    if (sourcePlane(connection.kind, connection.config) === 'device') {
         if (ownDevice.allowed)
             return null;
-        return { feature: 'device.own', plane: ownDevice.owner ? 'host' : 'device' };
+        return { feature: 'device.own', plane: ownDevice.owner ? 'owner' : 'device' };
     }
     if (protectedRoots.length === 0)
         return null;
-    const root = connection.config?.root;
+    const { root, hostRoot } = (connection.config ?? {});
     if (typeof root !== 'string' || root.length === 0)
         return null;
-    const required = requiredFeaturesForRoot(await resolveRoot(root), protectedRoots, 'add');
+    // Only the in-process folder reads the pair; another root-bearing kind is judged on `root`.
+    const required = requiredFeaturesForRoot(await resolveRoot(root, connection.kind === HOST_SOURCE_KIND ? hostRoot : undefined), protectedRoots, 'add');
     const feature = required.find((f) => !hasRouteFeature(session, f));
     return feature ? { feature, plane: 'zone' } : null;
 }
 /**
  * Ask agent-core's ONE device gate (`devices.mayAttach`) about the device a
- * host-plane connection names. brain-core reads `config.device` as an opaque
+ * device-plane connection names. brain-core reads `config.device` as an opaque
  * string and knows no device semantics; no agent-core, no device or a
  * non-host kind ⇒ `{ allowed: false, owner: false }` (fail closed).
  */
 function deviceAttachVerdict(state, ctx, connection) {
     const denied = { allowed: false, owner: false };
-    if (!isHostPlaneKind(connection.kind))
+    if (sourcePlane(connection.kind, connection.config) !== 'device')
         return denied;
     const device = connection.config?.device;
     if (typeof device !== 'string' || !device)
@@ -629,11 +689,110 @@ function deviceAttachVerdict(state, ctx, connection) {
         projectId: ctx.projectId,
         ...(ctx.agentId ? { agentId: ctx.agentId } : {}),
         callerId: '@neuralis/brain-core',
-        callerTrust: 'first-party',
-        grantedFeatures: ctx.grantedFeatures,
+        callerTrust: 'native',
+        grantedFeatures: [...ctx.grantedFeatures],
     };
     const agentCore = state.ctx.packages?.getPackageApi('@neuralis/agent-core', session);
-    return agentCore?.devices?.mayAttach({ userId: ctx.userId, grantedFeatures: ctx.grantedFeatures }, device) ?? denied;
+    return agentCore?.devices?.mayAttach({ userId: ctx.userId, grantedFeatures: [...ctx.grantedFeatures] }, device) ?? denied;
+}
+/** The 403 text of a refused edit — one wording for the route PATCH and the cross-package writer. */
+function editRefusalMessage(missing) {
+    return missing.plane === 'device'
+        ? "Only the device's owner may edit a source on it."
+        : missing.plane === 'owner'
+            ? `Editing a source on your device requires the ${missing.feature} feature.`
+            : `Editing a source rooted in a protected host zone requires the ${missing.feature} feature.`;
+}
+/**
+ * The edit gates of a source PATCH, in order — ONE ladder for every
+ * source-config writer (the route PATCH, `POST policies/uri`, a widening
+ * `POST sources/enabled`, and the cross-package writer `sourceEditFence`), so
+ * none can skip a rung:
+ * the source's scope (another member's user/agent source needs
+ * `files.writeOthers`), the immutable `floor:true` rows (409 when dropped or
+ * altered), and what attaching it needs (`missingAttachFeature`: a device folder
+ * is its owner's alone, a protected-zone root needs `sources.privileged`).
+ * The refusal the caller answers, or null.
+ */
+export async function sourceEditRefusal(state, editor, existing, nextPermissions, ownDevice = deviceAttachVerdict(state, editor, existing.connection)) {
+    const grants = { grantedFeatures: [...editor.grantedFeatures] };
+    if (!canAccessScope(existing.scope, { userId: editor.userId, ...(editor.agentId ? { agentId: editor.agentId } : {}), grantedFeatures: grants.grantedFeatures }, 'write', sourceScopeOrigin(existing.connection))) {
+        return { status: 403, body: { error: 'Forbidden for source scope' } };
+    }
+    try {
+        assertImmutablePolicyFloorsPreserved(existing.permissions, nextPermissions);
+    }
+    catch (err) {
+        if (err instanceof ImmutablePolicyFloorError)
+            return { status: 409, body: { code: err.code, error: err.message } };
+        throw err;
+    }
+    // PATCH cannot change `connection` (its `device` included — a transport flip is
+    // a delete and a re-attach, never an edit), but it CAN widen an existing device-plane
+    // source's permissions (read → write). Editing one therefore needs what
+    // attaching one does — the device's owner with `device.own` — otherwise a
+    // plain-`sources.mount` manager could escalate a read-only host source in place.
+    // Same rule for the local plane: a PATCH can widen permissions (read →
+    // write) on a source already rooted in a protected zone, so editing one
+    // requires the same grants attaching one does — for EVERY root-bearing kind,
+    // not just the folder kind.
+    const stack = state.ctx.platform.runtimeStack();
+    const editJudged = await unlessAnchorUnresolvable(missingAttachFeature(grants, existing.connection, buildProtectedRoots(stack), async (root, hostRoot) => resolveLocalRoot({
+        configured: root, hostRoot, projectRoot: (await state.infraFactory.getInfra(editor.projectId)).projectRoot ?? '',
+        isDocker: stack.isDocker, source: existing.source,
+    }).resolvedRoot, ownDevice));
+    // An anchored folder this plane cannot open is never edited (fail closed, nothing written).
+    if (!editJudged)
+        return { status: 400, body: SOURCE_ANCHOR_UNRESOLVABLE };
+    return editJudged.value ? { status: 403, body: { error: editRefusalMessage(editJudged.value) } } : null;
+}
+/**
+ * The native folder fence for an attach or an edit (`domain/access/nativeLocalFence.ts`):
+ * the 403 a fenced root answers, or null. Judged on the root as the connector
+ * resolves it; a device folder or another kind ⇒ never this gate's.
+ */
+export async function nativeFenceRefusal(state, projectId, source, connection) {
+    if (sourcePlane(connection.kind, connection.config) !== 'local')
+        return null;
+    const stack = state.ctx.platform.runtimeStack();
+    if (!nativeLocalFenceApplies(stack))
+        return null;
+    const projectRoot = (await state.infraFactory.getInfra(projectId)).projectRoot ?? '';
+    const { root, hostRoot } = (connection.config ?? {});
+    const refused = await nativeLocalRootRefused({
+        stack,
+        connection,
+        resolvedRoot: resolveLocalRoot({ configured: typeof root === 'string' ? root : '', hostRoot, projectRoot, isDocker: stack.isDocker, source }).resolvedRoot,
+        projectRoot,
+        privilegedRoots: buildProtectedRoots(stack).map((p) => p.root),
+    });
+    return refused ? { status: 403, body: NATIVE_LOCAL_REFUSAL } : null;
+}
+/**
+ * The route PATCH's edit gates on the cross-package write (`upsertSourceConfig`):
+ * the SAME `sourceEditRefusal` ladder (scope, immutable floors, device owner,
+ * protected zone) with the route's codes and texts, then the native fence, which
+ * refuses only an edit that widens a fenced source; an unjudgeable shape is refused.
+ */
+export function sourceEditFence(state) {
+    return async (caller, existing, next) => {
+        const refused = await sourceEditRefusal(state, caller, existing, next.permissions);
+        if (refused)
+            return { status: refused.status, error: refused.body.error, ...(refused.body.code ? { code: refused.body.code } : {}) };
+        if (!(await nativeFenceRefusal(state, caller.projectId, existing.source, existing.connection)))
+            return null;
+        let widens = true;
+        try {
+            widens = fencedEditWidens(existing, {
+                permissions: next.permissions,
+                ...(next.sync ? { sync: next.sync } : {}),
+            });
+        }
+        catch {
+            widens = true;
+        }
+        return widens ? { status: 403, error: NATIVE_LOCAL_EDIT_REFUSAL.error } : null;
+    };
 }
 /**
  * May this caller READ the source's root — the same per-uri read predicate the
@@ -653,21 +812,31 @@ async function rootReadable(infra, ctx, source, configCache) {
  * nothing; the raw last-sync error goes to a `sources.sync` holder, the tier
  * `sources/sync-status` answers to. A feature, never a role name.
  */
-async function sourceConfigView(session, config, projectRoot, protectedRoots, readable, ownDevice, defaultSyncExclude) {
+async function sourceConfigView(session, config, projectRoot, isDocker, protectedRoots, readable, ownDevice, defaultSyncExclude) {
+    const resolve = (root, hostRoot) => resolveLocalRoot({ configured: root, hostRoot, projectRoot, isDocker, source: config.source }).resolvedRoot;
+    // A stored anchor this plane cannot open is a folder nobody may attach here
+    // (and it opens nowhere) — never an error that empties the whole listing.
     const mayAttach = (ownDevice.allowed || hasRouteFeature(session, 'sources.mount'))
-        && await missingAttachFeature(session, config.connection, protectedRoots, (root) => resolveLocalRoot({ configured: root, projectRoot, source: config.source }).resolvedRoot, ownDevice) === null;
+        && (await unlessAnchorUnresolvable(missingAttachFeature(session, config.connection, protectedRoots, resolve, ownDevice)))?.value === null;
+    // The folder THIS plane opens — natively the pair's machine half, never the container spelling.
+    const { root, hostRoot } = config.connection.config ?? {};
+    const inProcess = sourcePlane(config.connection.kind, config.connection.config) === 'local';
+    const rootEffective = inProcess && typeof root === 'string' && root
+        ? resolvedLocalRootOrNull({ configured: root, hostRoot, projectRoot, isDocker, source: config.source }) ?? undefined
+        : undefined;
     return { mayReadPaths: mayAttach || readable, maySeeSyncErrors: hasRouteFeature(session, 'sources.sync'),
-        ...(defaultSyncExclude ? { defaultSyncExclude } : {}) };
+        ...(defaultSyncExclude ? { defaultSyncExclude } : {}), ...(rootEffective ? { rootEffective } : {}) };
 }
 /** `sourceConfigView` for a single-row answer (single GET, mutation echoes). */
 async function publicViewFor(session, ctx, config, state, infra) {
     const readable = await rootReadable(infra, ctx, config.source, new Map([[config.source, config]]));
+    const stack = state.ctx.platform.runtimeStack();
     const matched = !config.sync ? matchDeclaredSource(config, state.ctx.platform.packageSourceDeclarations(), {
-        projectRoot: infra?.projectRoot ?? '', appRoot: state.ctx.platform.runtimeStack().appRoot,
+        projectRoot: infra?.projectRoot ?? '', appRoot: stack.appRoot, isDocker: stack.isDocker,
     }) : null;
     const defaults = matched && isOwnDataZoneDeclaration(matched.originPackage, matched.decl, state.ctx.selfId)
         ? seedExcludedMachineWrittenGlobs(state.ctx.platform.machineWrittenPaths()) : undefined;
-    return sourceConfigView(session, config, infra?.projectRoot ?? '', buildProtectedRoots(state.ctx.platform.runtimeStack()), readable, deviceAttachVerdict(state, ctx, config.connection), defaults);
+    return sourceConfigView(session, config, infra?.projectRoot ?? '', stack.isDocker, buildProtectedRoots(stack), readable, deviceAttachVerdict(state, ctx, config.connection), defaults);
 }
 function filterSourceForList(config, ctx, requestedScope, includeObserved) {
     if (requestedScope && config.scope.kind !== requestedScope)
@@ -677,10 +846,21 @@ function filterSourceForList(config, ctx, requestedScope, includeObserved) {
         return false;
     return true;
 }
+/**
+ * The create body's `scope`: a kind name, or an object. A complete object is taken as
+ * written (a foreign `userId` then meets the write `canAccessScope`); an object naming
+ * only a valid `kind` gets the caller's ids, like the name; any other object or name is
+ * `null` (400 `invalid_scope`) — never silently the kind default. Absent = the default.
+ */
 function resolveRequestedSourceScope(raw, defaultScope, ctx) {
     if (isSourceScope(raw))
         return raw;
-    const requested = raw === 'project' || raw === 'user' || raw === 'agent' ? raw : defaultScope;
+    const named = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw.kind : raw;
+    if (raw && typeof raw === 'object' && named !== 'project' && named !== 'user' && named !== 'agent')
+        return null;
+    if (typeof raw === 'string' && raw !== 'project' && raw !== 'user' && raw !== 'agent')
+        return null;
+    const requested = named === 'project' || named === 'user' || named === 'agent' ? named : defaultScope;
     if (requested === 'user')
         return { kind: 'user', userId: ctx.userId };
     if (requested === 'agent')
@@ -700,7 +880,7 @@ async function handleSourcesUpdate(req, state) {
     const description = body?.description;
     // `null` = absent. A read-then-resend caller (the manage-sources skill's jq
     // projection) legitimately round-trips a field the listing never carried.
-    const recognizesPackages = body?.recognizesPackages ?? undefined;
+    const packageFolders = body?.packageFolders ?? undefined;
     if (!source)
         return { status: 400, body: { error: 'Missing source' } };
     if (description !== undefined && typeof description !== 'string') {
@@ -713,15 +893,15 @@ async function handleSourcesUpdate(req, state) {
     if (enabledRaw !== undefined && typeof enabledRaw !== 'boolean' && enabledRaw !== 'auto') {
         return { status: 400, body: { error: 'enabled must be boolean or "auto" if provided' } };
     }
-    if (recognizesPackages !== undefined && typeof recognizesPackages !== 'boolean') {
-        return { status: 400, body: { error: 'recognizesPackages must be a boolean if provided' } };
+    if (packageFolders !== undefined && !Array.isArray(packageFolders)) {
+        return { status: 400, body: { error: 'packageFolders must be an array of folder paths if provided' } };
     }
     await ensureAccess(ctx, state);
-    // R2 (architect MINOR-2) — flagging a source `recognizesPackages` creates a
-    // code-LOAD surface, so the WRITE is owner/admin-effective only, even though
-    // other source fields are sources.mount. Deny-by-default.
-    if (recognizesPackages !== undefined && !isOwnerOrAdminEffective(req.session)) {
-        return { status: 403, body: { error: 'Setting recognizesPackages requires an owner/admin-effective role.' } };
+    // R2 (architect MINOR-2) — a `packageFolders` entry creates a code-LOAD
+    // surface, so the WRITE is owner/admin-effective only, even though other
+    // source fields are sources.mount. Deny-by-default.
+    if (packageFolders !== undefined && !isOwnerOrAdminEffective(req.session)) {
+        return { status: 403, body: { error: 'Setting packageFolders requires an owner/admin-effective role.' } };
     }
     const bridge = await resolveBridge(state, projectId);
     const scope = { userId: ctx.userId, projectId };
@@ -732,43 +912,23 @@ async function handleSourcesUpdate(req, state) {
     if (!ownDevice.allowed && !hasRouteFeature(req.session, 'sources.mount')) {
         return { status: 403, body: { error: 'Updating sources requires sources.mount.' } };
     }
-    if (!canAccessScope(existing.scope, toScopeAccessCtx(ctx), 'write')) {
-        return { status: 403, body: { error: 'Forbidden for source scope' } };
+    const refused = await sourceEditRefusal(state, ctx, existing, permissions, ownDevice);
+    if (refused)
+        return refused;
+    const packageFoldersError = packageFolders === undefined ? undefined : validatePackageFolders(packageFolders, existing.connection)[0];
+    if (packageFoldersError)
+        return { status: 400, body: { error: packageFoldersError } };
+    const normalizedPerms = normalizePermissions(permissions, { rolePriorities: ctx.rolePriorities, existing: existing.permissions });
+    // A source the native fence refuses (it predates the fence) may still be
+    // narrowed — disabled, a right dropped, described — never widened.
+    if (await nativeFenceRefusal(state, projectId, source, existing.connection) && fencedEditWidens(existing, {
+        permissions: normalizedPerms, clearSync,
+        ...(sync ? { sync } : {}),
+        ...(enabledRaw !== undefined ? { enabled: enabledRaw } : {}),
+        ...(packageFolders !== undefined ? { packageFolders: packageFolders } : {}),
+    })) {
+        return { status: 403, body: NATIVE_LOCAL_EDIT_REFUSAL };
     }
-    try {
-        assertImmutablePolicyFloorsPreserved(existing.permissions, permissions);
-    }
-    catch (err) {
-        if (err instanceof ImmutablePolicyFloorError) {
-            return { status: 409, body: { code: err.code, error: err.message } };
-        }
-        throw err;
-    }
-    if (recognizesPackages === true && existing.connection.kind !== 'local') {
-        return { status: 400, body: { error: 'recognizesPackages may only be true for local-kind sources.' } };
-    }
-    // PATCH cannot change `connection`, but it CAN widen an existing host-plane
-    // source's permissions (read → write). Editing one therefore needs what
-    // attaching one does — the device's owner with `device.own` — otherwise a
-    // plain-`sources.mount` manager could escalate a read-only host source in place.
-    // Same rule for the container plane: a PATCH can widen permissions (read →
-    // write) on a source already rooted in a protected zone, so editing one
-    // requires the same grants attaching one does — for EVERY root-bearing kind,
-    // not just `local`.
-    const missingForEdit = await missingAttachFeature(req.session, existing.connection, buildProtectedRoots(state.ctx.platform.runtimeStack()), async (root) => resolveLocalRoot({ configured: root, projectRoot: (await state.infraFactory.getInfra(projectId)).projectRoot ?? '', source }).resolvedRoot, ownDevice);
-    if (missingForEdit) {
-        return {
-            status: 403,
-            body: {
-                error: missingForEdit.plane === 'device'
-                    ? "Only the device's owner may edit a source on it."
-                    : missingForEdit.plane === 'host'
-                        ? `Editing a host-plane source requires the ${missingForEdit.feature} feature.`
-                        : `Editing a source rooted in a protected host zone requires the ${missingForEdit.feature} feature.`,
-            },
-        };
-    }
-    const normalizedPerms = normalizePermissions(permissions);
     try {
         const updated = await bridge.updateSourceConfig(scope, {
             agentId,
@@ -778,7 +938,7 @@ async function handleSourcesUpdate(req, state) {
             ...(sync ? { sync } : {}),
             ...(clearSync ? { clearSync: true } : {}),
             ...(enabledRaw !== undefined ? { enabled: enabledRaw } : {}),
-            ...(recognizesPackages !== undefined ? { recognizesPackages: recognizesPackages } : {}),
+            ...(packageFolders !== undefined ? { packageFolders: packageFolders } : {}),
         });
         const infra = await state.infraFactory.getInfra(projectId);
         return { status: 200, body: toPublicSourceConfig(updated, await publicViewFor(req.session, ctx, updated, state, infra)) };
@@ -816,9 +976,20 @@ async function handleSourcesEnabled(req, state) {
     }
     if (!existing)
         return { status: 404, body: { error: `Source not found: ${source}` } };
-    if (!canAccessScope(existing.scope, toScopeAccessCtx(ctx), 'write')) {
+    if (!canAccessScope(existing.scope, toScopeAccessCtx(ctx), 'write', sourceScopeOrigin(existing.connection))) {
         return { status: 403, body: { error: 'Forbidden for source scope' } };
     }
+    // Turning a source ON widens its reach, so it runs the edit ladder (a device
+    // folder is its owner's alone, a protected zone needs its feature). Turning it
+    // off narrows and stays the `sources.mount` holder's.
+    if (fencedEditWidens(existing, { enabled })) {
+        const refused = await sourceEditRefusal(state, ctx, existing, existing.permissions);
+        if (refused)
+            return refused;
+        if (await nativeFenceRefusal(state, ctx.projectId, source, existing.connection)) {
+            return { status: 403, body: NATIVE_LOCAL_EDIT_REFUSAL };
+        }
+    }
     try {
         const updated = await bridge.setSourceEnabled(scope, { source, enabled });
         const infra = await state.infraFactory.getInfra(ctx.projectId);
@@ -841,7 +1012,7 @@ async function handleSourcesDelete(slug, req, state) {
     }
     if (!match)
         return { status: 404, body: { error: `Source not found: ${slug}` } };
-    if (!canAccessScope(match.scope, toScopeAccessCtx(ctx), 'write')) {
+    if (!canAccessScope(match.scope, toScopeAccessCtx(ctx), 'write', sourceScopeOrigin(match.connection))) {
         return { status: 403, body: { error: 'Forbidden for source scope' } };
     }
     const purgeRaw = req.query?.purge;
@@ -897,7 +1068,9 @@ async function handleSourcesSync(req, state) {
     if (!config.sync) {
         return { status: 400, body: { error: `Source "${config.source}" has no sync configuration. Add one before triggering a sync.` } };
     }
-    const job = await bridge.triggerSourceSync(scope, { agentId, source, caller: toSyncCaller(ctx) });
+    // `confirmEmpty` lets ONE full pass tombstone a source whose root now holds nothing.
+    const confirmEmpty = body?.confirmEmpty === true;
+    const job = await bridge.triggerSourceSync(scope, { agentId, source, caller: toSyncCaller(ctx), ...(confirmEmpty ? { confirmEmpty } : {}) });
     return { status: 202, body: job };
 }
 /**
@@ -1139,20 +1312,16 @@ async function handleSourcesReset(req, state) {
  * suggested kind + config.
  *
  * Suggested kinds today:
- *   - `app`      — `{neuralisHome}/app/` (admin-only zone; per W3I the
- *                  admin package will register a dedicated SourceKind in
- *                  a follow-up commit; until then we suggest the path
- *                  with `kind: 'local'` so the existing add-source flow
- *                  works).
+ *   - `app`      — `{neuralisHome}/app/` (admin-only zone), suggested as a
+ *                  `host` source.
  *   - `neuralis` — the downloaded Neuralis tree
  *                  (`/home/<user>/projects/Neuralis` on host installs,
- *                  `os://repo` mount inside Docker). Same caveat: full
- *                  registration happens later; today we surface the path
- *                  with `kind: 'local'`.
+ *                  `os://repo` mount inside Docker), suggested as a `host`
+ *                  source.
  *   - `projects` — the per-project zone next door (`{neuralisHome}/projects`).
  *
  * Already-attached paths are filtered out by comparing each suggestion's
- * resolved root against the persisted source configs' `connection.config.root`.
+ * root against every persisted source's root as THIS plane resolves it.
  */
 async function handleSourcesDiscoverable(req, state) {
     const ctx = extractCtx(req);
@@ -1172,11 +1341,17 @@ async function handleSourcesDiscoverable(req, state) {
     const scope = { userId: ctx.userId, projectId: ctx.projectId };
     const access = toScopeAccessCtx(ctx);
     const existing = await bridge.listSourceConfigs(scope, access);
+    // Compared on the root THIS plane opens, so a natively attached folder (stored
+    // under its container spelling) is not offered again.
+    const attachedProjectRoot = (await state.infraFactory.getInfra(ctx.projectId)).projectRoot ?? '';
     const attachedRoots = new Set();
     for (const config of existing) {
         const root = config.connection?.config?.root?.trim();
-        if (root)
-            attachedRoots.add(root);
+        const attached = root
+            ? resolvedLocalRootOrNull({ configured: root, hostRoot: config.connection.config.hostRoot, projectRoot: attachedProjectRoot, isDocker: stack.isDocker, source: config.source })
+            : null;
+        if (attached !== null)
+            attachedRoots.add(attached);
     }
     const suggestions = [];
     // Declarative `seed:'discoverable'` sources (modular-brewing-sutherland) —
@@ -1210,7 +1385,7 @@ async function handleSourcesDiscoverable(req, state) {
                     ...(def ? { suggestedAccess: { read: !!def.read, write: !!def.write, exec: !!def.exec } } : {}),
                     ...(decl.visibility?.seeRequires?.length ? { seeRequires: decl.visibility.seeRequires } : {}),
                 };
-                if (decl.kind === 'local') {
+                if (decl.kind === HOST_SOURCE_KIND) {
                     let resolvedRoot = null;
                     let hostRoot;
                     if (decl.root === '${appRoot}') {
@@ -1263,10 +1438,16 @@ async function handleSourcesDiscoverable(req, state) {
         // shape `neuralis-operations` prescribes), and the whole-tree proposal
         // stays available for source work but says what it exposes and pre-fills a
         // `.env*` read-deny.
+        //
+        // A native host has no overlay and no container: its packaged operator
+        // skills sit in its OWN tree (`stack.neuralisTree`, the Neuralis tree the
+        // privileged-root table names there), so the skills proposal is rooted
+        // there — the whole-tree proposal stays the overlay's.
         const neuralisMount = stack.osMounts.find((m) => m.key === 'neuralis');
         const neuralisRoot = neuralisMount?.containerPath ?? null;
-        if (neuralisRoot) {
-            const skillsRoot = resolvePath(neuralisRoot, 'skills');
+        const skillsTree = neuralisRoot ?? (stack.isDocker ? null : stack.neuralisTree);
+        if (skillsTree) {
+            const skillsRoot = resolvePath(skillsTree, 'skills');
             // Guarded: an overlay rooted somewhere without a `skills/` folder must
             // not advertise a directory that is not there — silent-zero-index is the
             // exact trap this suggestion exists to remove.
@@ -1275,12 +1456,13 @@ async function handleSourcesDiscoverable(req, state) {
                     id: 'discover:neuralis-skills',
                     label: 'Neuralis Skills',
                     description: "The deployment's own operator skills (`neuralis/skills/`). Each SKILL.md folder is a discovered source package, so the operator-command vocabulary reaches an agent's context by itself.",
-                    suggestedKind: 'local',
+                    suggestedKind: HOST_SOURCE_KIND,
                     suggestedScheme: 'neuralis-skills',
-                    suggestedConfig: {
-                        root: skillsRoot,
-                        ...(neuralisMount?.hostPath ? { hostRoot: resolvePath(neuralisMount.hostPath, 'skills') } : {}),
-                    },
+                    // The LOGICAL root — the tree's `skills/` on whichever plane opens the
+                    // source (the overlay in Docker, the host's own tree natively) — so the
+                    // attach survives a move between the two; the machine half derives
+                    // from the overlay's mount at bind time.
+                    suggestedConfig: { root: `${NEURALIS_TREE_ANCHOR}skills` },
                     root: skillsRoot,
                     icon: 'BookOpen',
                     suggestedScope: 'user',
@@ -1299,20 +1481,17 @@ async function handleSourcesDiscoverable(req, state) {
                     // trigger, which rides the contract rather than the form's old
                     // hard-coded literal.
                     suggestedSync: { trigger: 'manual' },
-                    note: 'Owner-only. Mounted via `pnpm neuralis:mount add … --neuralis`.',
+                    note: neuralisRoot ? 'Owner-only. Mounted via `pnpm neuralis:mount add … --neuralis`.' : "Owner-only. This install's own packaged skills (read-only).",
                 });
             }
-            if (!attachedRoots.has(neuralisRoot)) {
+            if (neuralisRoot && !attachedRoots.has(neuralisRoot)) {
                 suggestions.push({
                     id: 'discover:neuralis',
                     label: 'Neuralis Tree',
                     description: "The deployment's own `neuralis/` folder, live from the host (scripts/, skills/, src/, config). Holds `.env` — attach it only for source work; prefer Neuralis Skills to give an agent the operator commands.",
-                    suggestedKind: 'local',
+                    suggestedKind: HOST_SOURCE_KIND,
                     suggestedScheme: 'neuralis',
-                    suggestedConfig: {
-                        root: neuralisRoot,
-                        ...(neuralisMount?.hostPath ? { hostRoot: neuralisMount.hostPath } : {}),
-                    },
+                    suggestedConfig: { root: NEURALIS_TREE_ANCHOR },
                     root: neuralisRoot,
                     icon: 'GitBranch',
                     // Privileged host zone — default to USER scope so it is not shared
@@ -1355,7 +1534,7 @@ async function handleSourcesDiscoverable(req, state) {
                 id: 'discover:projects',
                 label: 'Projects Zone',
                 description: '`{neuralisHome}/projects/` — sibling of the active project workspace.',
-                suggestedKind: 'local',
+                suggestedKind: HOST_SOURCE_KIND,
                 suggestedScheme: 'local',
                 suggestedConfig: {
                     root: stack.projectsRoot,
@@ -1365,22 +1544,30 @@ async function handleSourcesDiscoverable(req, state) {
                 icon: 'FolderTree',
             });
         }
-        // Full host — only in native (non-Docker) mode, where `/` IS the host root
-        // and is directly readable. In Docker the host is invisible unless bound
-        // (`pnpm neuralis:mount add / --slug host`), which then surfaces via the
-        // generic mount loop below. Opt-in, gated by `sources.privileged` (no
-        // grant below the `admin` tier), attach READ-ONLY by default
-        // (suggestedAccess) — the whole-host blast radius warrants deny-by-default;
-        // the attacher narrows the uri-policy (or widens write) before use.
-        if (!stack.isDocker && !attachedRoots.has('/')) {
+        // Full host — only in native (non-Docker) mode, where the filesystem root IS
+        // the host root and is directly readable: `/`, on Windows each drive root a
+        // zone lives on (`C:\` — `/` there means "the current drive"). In Docker
+        // the host is invisible unless bound (`pnpm neuralis:mount add / --slug
+        // host`), which then surfaces via the generic mount loop below. Opt-in,
+        // gated by `sources.privileged` (no grant below the `admin` tier), attach
+        // READ-ONLY by default (suggestedAccess) — the whole-host blast radius
+        // warrants deny-by-default; the attacher narrows the uri-policy (or widens
+        // write) before use. The roots are the privileged table's own whole-host rows.
+        const hostRoots = stack.isDocker ? [] : protectedRootPaths(stack).filter(isFilesystemRoot);
+        for (const root of hostRoots) {
+            if (attachedRoots.has(root))
+                continue;
+            const drive = /^([A-Za-z]):/.exec(root)?.[1]?.toLowerCase();
+            if (root !== '/' && !drive)
+                continue; // a UNC share root is not "the host"
             suggestions.push({
-                id: 'discover:host-root',
-                label: 'Full Host',
-                description: 'The entire host filesystem (`/`). Attach read-only and scope it before use.',
-                suggestedKind: 'local',
-                suggestedScheme: 'host',
-                suggestedConfig: { root: '/' },
-                root: '/',
+                id: drive ? `discover:host-root:${drive}` : 'discover:host-root',
+                label: drive ? `Full Host (${root})` : 'Full Host',
+                description: `The entire host filesystem (\`${root}\`). Attach read-only and scope it before use.`,
+                suggestedKind: HOST_SOURCE_KIND,
+                suggestedScheme: drive ? `host-${drive}` : 'host',
+                suggestedConfig: { root },
+                root,
                 icon: 'HardDrive',
                 // Privileged host zone — default to USER scope (not shared project-wide).
                 suggestedScope: 'user',
@@ -1405,7 +1592,7 @@ async function handleSourcesDiscoverable(req, state) {
                 id: `discover:mount:${mount.key}`,
                 label: mount.key,
                 description: `Host bind \`${mount.hostPath ?? mount.containerPath}\` mounted at \`${mount.containerPath}\`.`,
-                suggestedKind: 'local',
+                suggestedKind: HOST_SOURCE_KIND,
                 suggestedScheme: scheme,
                 suggestedConfig: {
                     root: mount.containerPath,
@@ -1424,7 +1611,12 @@ async function handleSourcesDiscoverable(req, state) {
     // ADD gate in handleSourcesCreate enforces the boundary independently — the
     // client filter is UX only.
     const protectedRoots = buildProtectedRoots(stack);
+    // The native folder fence: without a container no root outside the project
+    // zone and the privileged rows is offered — that folder is the device's path.
+    const fenceProject = nativeLocalFenceApplies(stack) ? (await state.infraFactory.getInfra(ctx.projectId)).projectRoot ?? '' : null;
     const visible = suggestions
+        .filter((s) => fenceProject === null || s.suggestedKind !== HOST_SOURCE_KIND || !s.root
+        || attachableNatively(nativeLocalPlacement(hostPathFlavour(s.root).resolve(s.root), fenceProject && resolvePath(fenceProject), protectedRoots.map((p) => p.root))))
         .map((s) => {
         // Union the authoritative protected-root features with any declaration
         // `visibility.seeRequires` already on the suggestion (defense-in-depth).
@@ -1443,131 +1635,51 @@ async function handleSourcesDiscoverable(req, state) {
     return { status: 200, body: { suggestions: visible } };
 }
 /**
- * `GET /sources/browse?path=…` — one level of directory listing, the step that
- * PRECEDES attaching a source.
- *
- * warded-wren (HOST-OSACC-FB9). This handler used to be the one route in the
- * file that checked nothing: no `ensureAccess`, no in-handler feature, no
- * protected-root table, and a raw `err.message` in the body. The route-level
- * `feature = 'files.read'` is a VIEWER default, so on a native install any
- * signed-in reader could walk the operator's host one level at a time
- * (`?path=/` → `/home` → `/root`), and on win32 enumerate the drive letters.
- *
- * The rule is one sentence: **you may browse exactly what you would be allowed
- * to attach.** The base feature is `sources.mount` — the same gate
- * `handleSourcesCreate` gives the act this one prepares — and per-path the
- * SHARED protected-root table decides, so `/`, the App Zone and the Neuralis
- * tree cost `sources.privileged` here exactly as they do at attach time.
- * `'see'` is the semantically right column; today both columns hold the same
- * feature, so nothing in the suite proves the distinction — it is intent, not
- * enforcement.
+ * `GET /sources/browse?path=…[&device=dev_…]` — one level of folders, the step
+ * that PRECEDES attaching a source: on this server, or on the caller's OWN
+ * paired device. The work lives in `usecases/browseSourceFolders.ts`; this
+ * handler supplies the gates this file owns (the protected-root table, the
+ * native fence, the device attach gate). The rule: **you may browse exactly
+ * what you would be allowed to attach.**
  */
 async function handleSourcesBrowse(req, state) {
     const ctx = extractCtx(req);
+    // Not the security gate — the usecase's gates are. `ensureAccess` buys
+    // uniformity with every sibling handler and the project-override 403 in
+    // `extractCtx`, and it needs a real agent in context.
     await ensureAccess(ctx, state);
-    // Not the security gate — the gates are the feature check below and the
-    // per-path table. `ensureAccess` buys uniformity with every sibling handler
-    // and the project-override 403 in `extractCtx`.
+    const rawPath = typeof req.query?.path === 'string' ? req.query.path : '';
+    const device = typeof req.query?.device === 'string' ? req.query.device : '';
+    if (device) {
+        // The device plane's ONE attach gate, asked BEFORE the `sources.mount`
+        // check: the owner attaches (and so browses) with `device.own` alone.
+        const verdict = deviceAttachVerdict(state, ctx, { kind: HOST_SOURCE_KIND, config: { device } });
+        const session = {
+            userId: ctx.userId, projectId: ctx.projectId, ...(ctx.agentId ? { agentId: ctx.agentId } : {}),
+            callerId: '@neuralis/brain-core', callerTrust: 'native', grantedFeatures: [...ctx.grantedFeatures],
+        };
+        const devices = state.ctx.packages?.getPackageApi('@neuralis/agent-core', session)?.devices;
+        return browseDeviceFolders({ device, rawPath, allowed: verdict.allowed }, devices, { userId: ctx.userId, grantedFeatures: [...ctx.grantedFeatures] });
+    }
     if (!hasRouteFeature(req.session, 'sources.mount')) {
         return { status: 403, body: { error: 'Browsing filesystem paths requires the sources.mount feature.' } };
     }
-    const { readdir, realpath } = await import('node:fs/promises');
-    const { resolve, join, dirname } = await import('node:path');
-    // Container deployments: `/mounts` is the only browsable zone and `path` is
-    // never read, so it is NOT gated on a path the handler ignores. The fail-soft
-    // empty list is deliberate — "no mounts configured yet" is a normal state for
-    // the add-source form, not an error.
-    if (process.env.NEURALIS_DOCKER === 'true') {
-        const mountsRoot = '/mounts';
-        try {
-            const entries = await readdir(mountsRoot, { withFileTypes: true });
-            const dirs = entries.filter((e) => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))
-                .map((e) => ({ name: e.name, path: join(mountsRoot, e.name), type: 'directory' }));
-            return { status: 200, body: { entries: dirs } };
-        }
-        catch {
-            return { status: 200, body: { entries: [] } };
-        }
-    }
-    const rawPath = (req.query?.path ?? '');
-    if (!rawPath)
-        return { status: 400, body: { error: 'Missing path parameter' } };
-    // A NUL byte survives `resolve()` unchanged and would slip past every string
-    // prefix comparison in the table below before `readdir` rejects it.
-    if (rawPath.includes('\0'))
-        return { status: 400, body: { error: BROWSE_UNREADABLE } };
-    // A relative path would resolve against the SERVER process cwd — never what
-    // the caller meant, and it also closes the drive-relative `C:foo` form.
-    if (!isAbsolute(rawPath))
-        return { status: 400, body: { error: 'Path must be absolute' } };
-    // ONE canonical value from here on: the gate, the root test, the readdir and
-    // the child paths all use it. Two resolutions is how a gate ends up judging a
-    // different string than the syscall receives.
-    const canonical = resolve(rawPath);
-    const protectedRoots = buildProtectedRoots(state.ctx.platform.runtimeStack());
-    const denied = missingBrowseFeatures(canonical, protectedRoots, state.ctx.platform.runtimeStack(), req.session, dirname);
-    if (denied.length > 0) {
-        return { status: 403, body: { error: `Browsing this path requires the ${denied[0]} feature.` } };
-    }
-    // `resolve` is purely LEXICAL, so a symlink whose literal path is innocent can
-    // still point at `/` or the App Zone. Re-run the same gate on the real path.
-    let real;
-    try {
-        real = await realpath(canonical);
-    }
-    catch {
-        return { status: 400, body: { error: BROWSE_UNREADABLE } };
-    }
-    if (real !== canonical) {
-        const deniedReal = missingBrowseFeatures(real, protectedRoots, state.ctx.platform.runtimeStack(), req.session, dirname);
-        if (deniedReal.length > 0) {
-            return { status: 403, body: { error: `Browsing this path requires the ${deniedReal[0]} feature.` } };
-        }
-    }
-    // Whole-host discovery by definition — the drive letters ARE the host. The
-    // filesystem-root fixpoint above already required the privileged feature
-    // (`win32.resolve('/')` is `\`, whose dirname is itself), and this second
-    // check keeps that true even if the table below it ever changes.
-    const { platform } = await import('node:os');
-    if (platform() === 'win32' && dirname(real) === real) {
-        if (!hasRouteFeature(req.session, PRIVILEGED_MOUNT_FEATURE)) {
-            return { status: 403, body: { error: `Browsing this path requires the ${PRIVILEGED_MOUNT_FEATURE} feature.` } };
-        }
-        const { stat } = await import('node:fs/promises');
-        const drives = [];
-        for (const letter of 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') {
-            try {
-                await stat(`${letter}:\\`);
-                drives.push({ name: `${letter}:\\`, path: `${letter}:\\`, type: 'directory' });
-            }
-            catch { /* skip */ }
-        }
-        return { status: 200, body: { entries: drives } };
-    }
-    try {
-        const entries = await readdir(real, { withFileTypes: true });
-        const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'))
-            .sort((a, b) => a.name.localeCompare(b.name))
-            .map((e) => ({ name: e.name, path: join(real, e.name), type: 'directory' }))
-            // Hidden-not-locked, the file's own S2 discipline: a child the caller may
-            // not see is simply absent, never a locked row. This is what lets the
-            // gate above match IS-or-UNDER instead of full containment — the parent
-            // stays walkable, the zone inside it does not appear.
-            .filter((e) => requiredFeaturesForRoot(e.path, protectedRoots, 'see', 'is-or-under')
-            .every((f) => hasRouteFeature(req.session, f)));
-        return { status: 200, body: { entries: dirs } };
-    }
-    catch (err) {
-        // Never the raw message: it carries the absolute path and distinguishes
-        // "does not exist" from "cannot be read", which together are an existence
-        // oracle over the host (invariant 9). The operator reads the detail in the
-        // server log; the caller gets one stable sentence for every failure.
-        console.warn('[sources/browse] readdir failed:', err instanceof Error ? err.message : String(err));
-        return { status: 400, body: { error: BROWSE_UNREADABLE } };
-    }
+    // The kernel's runtime stack is the ONE Docker signal; it throws before the
+    // platform facts exist (fail closed).
+    const stack = state.ctx.platform.runtimeStack();
+    const protectedRoots = buildProtectedRoots(stack);
+    return browseServerFolders({ rawPath, isDocker: stack.isDocker === true }, {
+        missingFeatures: (candidate) => missingBrowseFeatures(candidate, protectedRoots, stack, req.session, dirnameOf),
+        childVisible: (child) => requiredFeaturesForRoot(child, protectedRoots, 'see', 'is-or-under').every((f) => hasRouteFeature(req.session, f)),
+        mayBrowseDrives: () => hasRouteFeature(req.session, PRIVILEGED_MOUNT_FEATURE),
+        privilegedFeature: PRIVILEGED_MOUNT_FEATURE,
+        privilegedRoots: protectedRoots.map((p) => p.root),
+        // The native folder fence, the browse half: the project zone and the
+        // privileged rows are browsed as before, an ANCESTOR of the project zone
+        // only on the way down to it, and anything else is the device's path.
+        fenceProject: async () => (nativeLocalFenceApplies(stack) ? (await state.infraFactory.getInfra(ctx.projectId)).projectRoot ?? '' : null),
+    });
 }
-/** One stable sentence for every browse failure — see the catch above. */
-const BROWSE_UNREADABLE = 'That path is not available.';
 /**
  * Features the caller is MISSING to enumerate `candidate`.
  *
@@ -1576,7 +1688,7 @@ const BROWSE_UNREADABLE = 'That path is not available.';
  *      all while the runtime stack is unavailable. `buildProtectedRoots(null)`
  *      returns `[]`, and an empty table means "unrestricted", so without this
  *      the gate is fail-OPEN exactly when the host classification is missing.
- *      The create gate's host-plane arm is written the same way and says so.
+ *      The create gate's device-plane arm is written the same way and says so.
  *   2. the shared protected-root table, matched IS-or-UNDER (see `RootMatchMode`).
  *
  * The root test is the `dirname(p) === p` fixpoint rather than a comparison