@banzhe/dsh-devcontainer 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/fs.js CHANGED
@@ -1,5 +1,5 @@
1
- import { B as toPosixSlashes, C as presetKindOf, F as isWindowsPath, H as containerOptions, I as joinHostRoot, L as relativeWithinHostRoot, M as hostPathStyle, N as isPathInsideContainer, P as isPosixAbsolute, R as toContainerPath, V as containerOptionFields, c as sbxWorkspaceRootFor, h as callingContainerPreset, i as sandboxHostPathFor, j as containerRemainder, l as repoRegistry, n as bindSbxMount, o as sandboxWorkspacePath, s as sbxSpecFor, t as asSbxSpec, v as fsEscapeRefusalText, y as fsRefusalText, z as toHostPath } from "./sbx-1GsFjQBk.js";
2
- import { n as runContainerCommand, r as resolveContainerTarget, t as containerCliEnv } from "./exec-CKAAz2zz.js";
1
+ import { $ as toHostPath, B as containerOptions, D as fsUnmountedText, E as fsRefusalText, G as containerRemainder, J as isPosixAbsolute, K as hostPathStyle, Q as toContainerPath, S as callingContainerPreset, T as fsEscapeRefusalText, X as joinHostRoot, Y as isWindowsPath, Z as relativeWithinHostRoot, c as sbxMountAttribution, d as liveHostMountRejections, et as toPosixSlashes, f as liveSbxOptions, g as warnOnce, h as repoRegistry, i as sandboxHostPathFor, j as presetKindOf, l as sbxSpecFor, n as bindSbxMount, o as sandboxWorkspacePath, q as isPathInsideContainer, s as sbxExtraMountsOf, t as asSbxSpec, u as sbxWorkspaceRootFor, z as containerOptionFields } from "./sbx-Blgjzzoe.js";
2
+ import { n as runContainerCommand, r as resolveContainerTarget, t as containerCliEnv } from "./exec-Bcojrag9.js";
3
3
  import z from "@deepseek-ai/schemastery";
4
4
  import { dirname, join, posix } from "node:path";
5
5
  import { readFileSync } from "node:fs";
@@ -313,6 +313,22 @@ const spawnContainerChild = (argv, options = {}) => {
313
313
  };
314
314
  };
315
315
  /**
316
+ * The handshake one channel opens with.
317
+ * @param target - the runtime the helper runs in.
318
+ * @returns the `hello` parameters, naming the extra roots only when there are any.
319
+ */
320
+ function handshakeOf(target) {
321
+ const mounts = target.kind === "sbx" ? target.mounts ?? [] : [];
322
+ return mounts.length === 0 ? {
323
+ protocol: 3,
324
+ workspace: target.workspace
325
+ } : {
326
+ protocol: 3,
327
+ workspace: target.workspace,
328
+ mounts
329
+ };
330
+ }
331
+ /**
316
332
  * The argv that runs one program inside the runtime.
317
333
  *
318
334
  * Both drivers take `-i` so the helper keeps its stdio pipe; `sbx` separates its
@@ -479,10 +495,7 @@ var ContainerRpcChannel = class ContainerRpcChannel {
479
495
  const child = spawn(runtimeExecArgv(target, ["node", HELPER_CONTAINER_PATH]));
480
496
  const channel = new ContainerRpcChannel(child, runtimeLabel(target), timeoutMs, options.maxPending ?? DEFAULT_MAX_PENDING);
481
497
  try {
482
- const hello = await channel.request("hello", {
483
- protocol: 3,
484
- workspace: target.workspace
485
- }, { timeoutMs });
498
+ const hello = await channel.request("hello", handshakeOf(target), { timeoutMs });
486
499
  if (hello.protocol !== 3) throw new Error(`devcontainer: the container helper speaks protocol ${hello.protocol}, not 3`);
487
500
  for (const field of [
488
501
  "platform",
@@ -726,21 +739,51 @@ var ContainerRpcChannel = class ContainerRpcChannel {
726
739
  * destroy their connection too. Callers check their own signal before joining.
727
740
  * @module @banzhe/dsh-devcontainer/rpc/pool
728
741
  */
729
- const SEPARATOR = "\0";
730
- /** The pool key of one runtime endpoint. */
742
+ /** The runtime endpoint of one target, without the mounts its helper was handshaken with. */
743
+ function endpointOf(target) {
744
+ return target.kind === "sbx" ? `sbx:${target.sandboxName}` : `docker:${target.containerId}`;
745
+ }
746
+ /** The extra roots a helper is handshaken with, as one comparable token. */
747
+ function mountsOf(target) {
748
+ return target.kind === "sbx" ? JSON.stringify(target.mounts ?? []) : "[]";
749
+ }
750
+ /** The pool key of one runtime endpoint and workspace. */
731
751
  function keyOf(target) {
732
- return `${target.kind === "sbx" ? `sbx:${target.sandboxName}` : `docker:${target.containerId}`}${SEPARATOR}${target.workspace}`;
752
+ return `${endpointOf(target)}\u0000${target.workspace}`;
733
753
  }
734
754
  /**
735
- * Live channels, keyed by runtime endpoint and workspace.
755
+ * Live channels, one per runtime endpoint and workspace.
736
756
  *
737
757
  * A channel that failed is dropped as soon as it settles, so the next call
738
- * handshakes again — that is what makes a restarted container recoverable
739
- * without restarting the session.
758
+ * handshakes again — that is what makes a restarted container recoverable without
759
+ * restarting the session. A caller who needs other extra roots than the live
760
+ * channel carries replaces it in place: one endpoint and one workspace have one
761
+ * helper, so two rows that disagree about those roots cannot evict each other's
762
+ * channel.
763
+ *
764
+ * Every key carries a queue, and each caller's whole `settle` runs on it: closing the
765
+ * old helper takes a moment, and a caller arriving inside that window must not open
766
+ * a second channel beside the one already on its way in. Different keys never wait
767
+ * for each other. A caller that waits behind another also inherits that open's
768
+ * budget rather than its own — the wait is the price of one helper per endpoint.
740
769
  */
741
770
  var ContainerRpcPool = class {
742
771
  channels = /* @__PURE__ */ new Map();
772
+ /** The tail of each key's queue: what the next caller for that key waits on. */
773
+ queues = /* @__PURE__ */ new Map();
743
774
  spawn;
775
+ /** Set by {@link closeAll}: a closed pool neither starts a helper nor hands one out, and a late open is closed on arrival. */
776
+ closed = false;
777
+ /**
778
+ * Whether the pool has been closed.
779
+ *
780
+ * Read through a call on purpose: an `await` in the caller settles what a direct field
781
+ * read was when the call started, which both hides the change and reads as dead code.
782
+ * @returns true once {@link closeAll} has run.
783
+ */
784
+ isClosed() {
785
+ return this.closed;
786
+ }
744
787
  /**
745
788
  * @param spawn - the process starter; the Docker CLI unless a test replaces it.
746
789
  */
@@ -749,50 +792,123 @@ var ContainerRpcPool = class {
749
792
  }
750
793
  /**
751
794
  * The live channel for one container, opened and handshaken on demand.
752
- * @param target - the container and the workspace it should treat as home.
795
+ *
796
+ * A channel already handshaken with these extra roots is reused as it stands; one
797
+ * handshaken with others is closed first and replaced, so a change of
798
+ * `hostMounts` neither leaks the old helper nor needs a second key.
799
+ * @param target - the container, the workspace it should treat as home, and the extra roots to name.
753
800
  * @param options - the per-request budget.
754
801
  * @returns the usable channel.
755
- * @throws Error when the helper cannot be staged or handshaken.
802
+ * @throws Error when the pool has been closed, or when the helper cannot be staged or handshaken.
756
803
  */
757
804
  async channel(target, options) {
758
805
  const key = keyOf(target);
806
+ return await this.enqueue(key, () => this.settle(target, key, options));
807
+ }
808
+ /**
809
+ * Run one task on a key's queue, and hand back its result.
810
+ *
811
+ * The queue moves on whether the task succeeded or not: a helper that could not be
812
+ * opened, a close that failed, must not lock the key for the rest of the session.
813
+ * @param key - the pool key to serialise on.
814
+ * @param task - the work to run when the key is free.
815
+ * @returns the task's result, or its failure.
816
+ */
817
+ async enqueue(key, task) {
818
+ const turn = (this.queues.get(key) ?? Promise.resolve()).then(task, task);
819
+ const tail = turn.then(() => void 0, () => void 0);
820
+ this.queues.set(key, tail);
821
+ tail.then(() => {
822
+ if (this.queues.get(key) === tail) this.queues.delete(key);
823
+ });
824
+ return await turn;
825
+ }
826
+ /**
827
+ * Hand one caller the channel its roots ask for, replacing what is there.
828
+ * @param target - the container, workspace, and extra roots.
829
+ * @param key - the pool key the caller queued on.
830
+ * @param options - the per-request budget.
831
+ * @returns the usable channel.
832
+ * @throws Error when the pool was closed while the caller waited.
833
+ */
834
+ async settle(target, key, options) {
835
+ if (this.isClosed()) throw new Error(CLOSED_TEXT);
836
+ const mounts = mountsOf(target);
759
837
  const cached = this.channels.get(key);
760
838
  if (cached !== void 0) {
761
- const channel = await cached.catch(() => void 0);
762
- if (channel !== void 0 && !channel.isClosed) return channel;
839
+ const channel = await cached.opening.catch(() => void 0);
840
+ if (channel !== void 0 && !channel.isClosed && cached.mounts === mounts) {
841
+ if (this.isClosed()) throw new Error(CLOSED_TEXT);
842
+ return channel;
843
+ }
844
+ if (channel !== void 0 && !channel.isClosed) await channel.close().catch(() => void 0);
763
845
  if (this.channels.get(key) === cached) this.channels.delete(key);
764
846
  }
847
+ if (this.isClosed()) throw new Error(CLOSED_TEXT);
765
848
  const opening = ContainerRpcChannel.open({
766
849
  target,
767
850
  spawn: this.spawn,
768
851
  timeoutMs: options.timeoutMs
769
852
  });
770
- this.channels.set(key, opening);
771
- const forget = () => {
772
- if (this.channels.get(key) === opening) this.channels.delete(key);
853
+ const live = {
854
+ mounts,
855
+ opening
856
+ };
857
+ const channel = await opening;
858
+ if (this.isClosed()) {
859
+ await channel.close().catch(() => void 0);
860
+ throw new Error(CLOSED_TEXT);
861
+ }
862
+ this.channels.set(key, live);
863
+ const release = () => {
864
+ if (this.channels.get(key) === live) this.channels.delete(key);
773
865
  };
774
- opening.then((channel) => {
775
- channel.closedPromise.then(forget);
776
- }, forget).catch(() => {});
777
- return await opening;
866
+ channel.closedPromise.then(release);
867
+ return channel;
778
868
  }
779
869
  /**
780
- * Drop one cached channel without touching the others.
870
+ * Drop the channel of one key, closing it.
871
+ *
872
+ * It runs on the key's queue like any other change, so it cannot interleave with a
873
+ * replacement and leave a channel nobody holds; the close is awaited before the
874
+ * caller continues.
781
875
  * @param target - the container and workspace to forget.
782
876
  */
783
- forget(target) {
784
- this.channels.delete(keyOf(target));
877
+ async forget(target) {
878
+ const key = keyOf(target);
879
+ await this.enqueue(key, () => this.discard(key));
880
+ }
881
+ /**
882
+ * Remove and close whatever one key holds.
883
+ * @param key - the pool key to empty.
884
+ */
885
+ async discard(key) {
886
+ const cached = this.channels.get(key);
887
+ if (cached === void 0) return;
888
+ this.channels.delete(key);
889
+ const channel = await cached.opening.catch(() => void 0);
890
+ if (channel !== void 0 && !channel.isClosed) await channel.close().catch(() => void 0);
785
891
  }
786
- /** Close every channel this pool opened, waiting for each process to settle. */
892
+ /**
893
+ * Close every channel this pool opened, and keep it closed.
894
+ *
895
+ * The queue is drained first, so a replacement that is already closing the helper it
896
+ * replaces finishes here instead of writing a channel into a pool that has stopped
897
+ * looking; the closed flag then covers whatever was still opening.
898
+ */
787
899
  async closeAll() {
788
- const opening = [...this.channels.values()];
900
+ this.closed = true;
901
+ await Promise.all([...this.queues.values()].map((tail) => tail.then(() => void 0, () => void 0)));
902
+ const live = [...this.channels.values()];
789
903
  this.channels.clear();
790
- for (const pending of opening) {
791
- const channel = await pending.catch(() => void 0);
792
- if (channel !== void 0) await channel.close();
904
+ for (const entry of live) {
905
+ const channel = await entry.opening.catch(() => void 0);
906
+ if (channel !== void 0) await channel.close().catch(() => void 0);
793
907
  }
794
908
  }
795
909
  };
910
+ /** The failure a caller reads when it asked a closed pool for a channel. */
911
+ const CLOSED_TEXT = "the container channel pool is closed";
796
912
  //#endregion
797
913
  //#region src/rpc/wire.ts
798
914
  /**
@@ -948,20 +1064,26 @@ const INHERITED_MUTATIONS = [
948
1064
  * The stdio endpoint one resolved runtime offers the helper.
949
1065
  * @param target - the resolved runtime.
950
1066
  * @param workspace - the mount point the helper treats as home.
1067
+ * @param mounts - extra read-only roots the helper may read beside the workspace.
951
1068
  * @returns the channel target the pool keys and the helper is started against.
952
1069
  * @throws Error when the runtime has no stdio endpoint at all.
953
1070
  */
954
- function channelTargetOf(target, workspace) {
1071
+ function channelTargetOf(target, workspace, mounts) {
955
1072
  switch (target.kind) {
956
1073
  case "docker": return {
957
1074
  kind: "docker",
958
1075
  containerId: target.containerId,
959
1076
  workspace
960
1077
  };
961
- case "sbx": return {
1078
+ case "sbx": return mounts.length === 0 ? {
962
1079
  kind: "sbx",
963
1080
  sandboxName: target.sandboxName,
964
1081
  workspace
1082
+ } : {
1083
+ kind: "sbx",
1084
+ sandboxName: target.sandboxName,
1085
+ workspace,
1086
+ mounts
965
1087
  };
966
1088
  case "devcontainer-cli": throw new Error("devcontainer: the Dev Container CLI offers no stdio channel for the filesystem helper");
967
1089
  }
@@ -991,6 +1113,7 @@ function containerMountsOf(spec, workspaceReal) {
991
1113
  if (spec.cli === "sbx") {
992
1114
  const sandbox = sandboxWorkspacePath(spec.hostWorkspaceRoot);
993
1115
  if (sandbox !== void 0 && sandbox !== spec.containerWorkspaceFolder) folders.push(sandbox);
1116
+ for (const mount of sbxExtraMountsOf(spec)) if (!folders.includes(mount.sandbox)) folders.push(mount.sandbox);
994
1117
  }
995
1118
  if (workspaceReal !== void 0 && !folders.includes(workspaceReal)) folders.push(workspaceReal);
996
1119
  return folders;
@@ -1040,7 +1163,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1040
1163
  * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
1041
1164
  * @param opts - optional cwd override and cancellation signal.
1042
1165
  * @returns the stable target.
1043
- * @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this path is outside the repository's mount.
1166
+ * @throws FsError `FS_NOT_FOUND` when the caller is container-bound and this path is outside every mount the session has.
1044
1167
  */
1045
1168
  async resolve(path, opts) {
1046
1169
  const route = await this.route(path, opts?.cwd);
@@ -1051,7 +1174,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1051
1174
  if (opts?.signal !== void 0) next.signal = opts.signal;
1052
1175
  return await super.resolve(mapped.path, next);
1053
1176
  }
1054
- const requested = this.remotePath(path, opts?.cwd, route);
1177
+ const requested = this.remotePath(path, opts?.cwd, route, "absent");
1055
1178
  return await this.withChannel(route.spec, opts?.signal, async (channel) => {
1056
1179
  const answer = await this.request(channel, "fs.resolve", { path: requested }, opts?.signal);
1057
1180
  this.assertInsideMount(answer.targetKey, path, route, channel.handshake.workspaceReal);
@@ -1081,7 +1204,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1081
1204
  processPath(target) {
1082
1205
  const spec = this.repositoryFor(target.displayPath, void 0, this.containerRequirement()?.kind);
1083
1206
  if (spec === void 0 || hostPathStyle(spec.hostWorkspaceRoot) !== "win32") return super.processPath(target);
1084
- return toHostPath(String(target.targetKey), spec);
1207
+ return toHostPath(String(target.targetKey), spec, sbxExtraMountsOf(spec));
1085
1208
  }
1086
1209
  /**
1087
1210
  * Probe a path inside the container without following its final symlink.
@@ -1089,7 +1212,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1089
1212
  * @param opts - `cwd` overrides the base for relative paths.
1090
1213
  * @param signal - aborts the metadata round-trip.
1091
1214
  * @returns metadata only, or undefined when the path is absent.
1092
- * @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this path is outside the repository's mount.
1215
+ * @throws FsError `FS_NOT_FOUND` when the caller is container-bound and this path is outside every mount the session has.
1093
1216
  */
1094
1217
  async lstat(path, opts, signal) {
1095
1218
  const route = await this.route(path, opts?.cwd);
@@ -1099,7 +1222,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1099
1222
  if (mapped.cwd !== void 0) next.cwd = mapped.cwd;
1100
1223
  return await super.lstat(mapped.path, next, signal);
1101
1224
  }
1102
- const requested = this.remotePath(path, opts?.cwd, route);
1225
+ const requested = this.remotePath(path, opts?.cwd, route, "absent");
1103
1226
  return await this.withChannel(route.spec, signal, async (channel) => {
1104
1227
  const info = await this.request(channel, "fs.lstat", { path: requested }, signal);
1105
1228
  return info === null ? void 0 : toFsPathInfo(info);
@@ -1110,13 +1233,13 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1110
1233
  * @param target - the resolved target.
1111
1234
  * @param signal - aborts the metadata round-trip.
1112
1235
  * @returns metadata only, or undefined when the target is absent.
1113
- * @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
1236
+ * @throws FsError `FS_NOT_FOUND` when the caller is container-bound and this target is outside every mount the session has.
1114
1237
  */
1115
1238
  async stat(target, signal) {
1116
1239
  const route = await this.routeTarget(target);
1117
1240
  if (route === void 0) return await super.stat(this.fenced(target), signal);
1118
1241
  return await this.withChannel(route.spec, signal, async (channel) => {
1119
- this.assertTargetInsideMount(target, route, channel);
1242
+ this.assertTargetInsideMount(target, route, channel, "absent");
1120
1243
  const value = await this.request(channel, "fs.stat", { target: wireTargetOf(target) }, signal);
1121
1244
  return value === null ? void 0 : toFsInfo(value);
1122
1245
  });
@@ -1199,13 +1322,13 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1199
1322
  * @param target - the resolved directory target.
1200
1323
  * @param signal - aborts the listing.
1201
1324
  * @returns the direct children with their resolved targets.
1202
- * @throws FsError `FS_PERMISSION_DENIED` when the caller is container-bound and this target is not in a container repository.
1325
+ * @throws FsError `FS_NOT_FOUND` when the caller is container-bound and this target is outside every mount the session has.
1203
1326
  */
1204
1327
  async listDir(target, signal) {
1205
1328
  const route = await this.routeTarget(target);
1206
1329
  if (route === void 0) return await super.listDir(this.fenced(target), signal);
1207
1330
  return await this.withChannel(route.spec, signal, async (channel) => {
1208
- this.assertTargetInsideMount(target, route, channel);
1331
+ this.assertTargetInsideMount(target, route, channel, "absent");
1209
1332
  return (await this.request(channel, "fs.list", { target: wireTargetOf(target) }, signal)).map(toFsDirEntry);
1210
1333
  });
1211
1334
  }
@@ -1315,7 +1438,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1315
1438
  async remoteChannel(spec, signal) {
1316
1439
  signal?.throwIfAborted();
1317
1440
  const runtime = await this.runtimeTarget(spec, signal);
1318
- const target = channelTargetOf(runtime, bindSbxMount(spec, runtime).containerWorkspaceFolder);
1441
+ const target = channelTargetOf(runtime, bindSbxMount(spec, runtime).containerWorkspaceFolder, sbxExtraMountsOf(spec).map((mount) => mount.sandbox));
1319
1442
  const channel = this.containerInternals.channel;
1320
1443
  if (channel !== void 0) return await channel(target);
1321
1444
  return await this.pool.channel(target, { timeoutMs: this.rpcTimeoutMs });
@@ -1424,27 +1547,85 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1424
1547
  forgetContainer(spec) {
1425
1548
  this.containers.delete(this.containerKey(spec));
1426
1549
  }
1550
+ /** Report every mount this row configures that no argv can carry, once per composition. */
1551
+ reportMountRejections() {
1552
+ for (const rejection of liveHostMountRejections(this.ctx)) warnOnce(this.ctx, (text) => {
1553
+ this.ctx.logger.warn(text);
1554
+ }, rejection);
1555
+ }
1427
1556
  /** Probe where the repository's container is, requiring an endpoint the helper can be started in. */
1428
1557
  async probeContainer(spec, signal) {
1429
- const target = await resolveContainerTarget(spec, this.containerInternals.run ?? runContainerCommand, signal);
1558
+ this.reportMountRejections();
1559
+ const target = await resolveContainerTarget(spec, this.containerInternals.run ?? runContainerCommand, signal, (message) => {
1560
+ warnOnce(this.ctx, (text) => {
1561
+ this.ctx.logger.warn(text);
1562
+ }, message);
1563
+ });
1430
1564
  if (target.kind === "devcontainer-cli") throw new FsError("devcontainer: \"" + spec.configPath + "\": the filesystem bridge needs a running Docker container for \"" + spec.hostWorkspaceRoot + "\", but none was found; set \"container\" or \"containerName\", or let the Dev Container CLI start one with \"cli: auto\" and \"ensureUp: true\".", "FS_IO_ERROR");
1431
1565
  return target;
1432
1566
  }
1433
- /** Translate one path for a container-bound call, refusing anything outside the mount. */
1434
- remotePath(path, cwd, route) {
1435
- const base = toContainerPath(cwd ?? this.config.cwd, route.spec);
1436
- const absolute = isWindowsPath(path) || isPosixAbsolute(path) ? toContainerPath(path, route.spec) : posix.resolve(base, toPosixSlashes(path));
1437
- this.assertInsideMount(absolute, path, route);
1567
+ /**
1568
+ * Translate one path for a container-bound call, refusing anything outside the mount.
1569
+ *
1570
+ * Only a metadata probe answers a path outside every mount as absent; a read or a
1571
+ * write names something the sandbox may not have, which stays a refusal.
1572
+ */
1573
+ remotePath(path, cwd, route, outside = "deny") {
1574
+ const mounts = sbxExtraMountsOf(route.spec);
1575
+ const base = toContainerPath(cwd ?? this.config.cwd, route.spec, mounts);
1576
+ const absolute = isWindowsPath(path) || isPosixAbsolute(path) ? toContainerPath(path, route.spec, mounts) : posix.resolve(base, toPosixSlashes(path));
1577
+ this.assertInsideMount(absolute, path, route, void 0, outside);
1438
1578
  return absolute;
1439
1579
  }
1440
- /** Refuse a container path that leaves every spelling of the repository's mount. */
1441
- assertInsideMount(containerPath, displayPath, route, workspaceReal) {
1442
- for (const folder of containerMountsOf(route.spec, workspaceReal)) if (containerRemainder(containerPath, folder) !== void 0) return;
1580
+ /** Whether a container path lies at or under one of the mounts this session may see. */
1581
+ insideMounts(containerPath, route, workspaceReal) {
1582
+ return containerMountsOf(route.spec, workspaceReal).some((folder) => containerRemainder(containerPath, folder) !== void 0);
1583
+ }
1584
+ /** Whether a HOST path lies at or under one of the host directories this session may see. */
1585
+ insideHostRoots(hostPath, route) {
1586
+ return [route.spec.hostWorkspaceRoot, ...sbxExtraMountsOf(route.spec).map((mount) => mount.host)].some((root) => relativeWithinHostRoot(hostPath, root) !== void 0);
1587
+ }
1588
+ /**
1589
+ * Whether the path a call named is one this session could have translated into I/O.
1590
+ *
1591
+ * The distinction the metadata answer turns on: a path this session cannot name at
1592
+ * all is simply absent, while a path it CAN name whose I/O identity ends up outside
1593
+ * the mount is an escape and stays a refusal. Both spellings are read, because a
1594
+ * call may name either; a relative path may still be either, so it counts as
1595
+ * inside and keeps the refusal.
1596
+ * @param displayPath - the path the call named.
1597
+ * @param route - the container route the call runs under.
1598
+ * @param workspaceReal - the workspace as the helper resolved it, when it is known.
1599
+ * @returns true when the named path belongs to some spelling of the mount.
1600
+ */
1601
+ namesMountPath(displayPath, route, workspaceReal) {
1602
+ if (this.insideMounts(displayPath, route, workspaceReal)) return true;
1603
+ if (!isWindowsPath(displayPath) && !isPosixAbsolute(displayPath)) return true;
1604
+ return this.insideHostRoots(displayPath, route);
1605
+ }
1606
+ /**
1607
+ * Answer a container path that leaves every spelling of the repository's mount.
1608
+ *
1609
+ * Two situations look alike here and are not: a path the session cannot see at all,
1610
+ * and a path it can see resolving out of the mount through a symbolic link. The
1611
+ * named path decides which: outside every mount, a `probe` may be answered as the
1612
+ * absence it is, while a named path that is inside still names an escape, and only
1613
+ * a refusal can report that.
1614
+ * @param containerPath - the container path the call would use for I/O.
1615
+ * @param displayPath - the path the call named.
1616
+ * @param route - the container route the call runs under.
1617
+ * @param workspaceReal - the workspace as the helper resolved it, when it is known.
1618
+ * @param outside - how a path outside every mount is answered: refused, or reported absent.
1619
+ * @throws FsError `FS_NOT_FOUND` for an absent probe, `FS_PERMISSION_DENIED` otherwise.
1620
+ */
1621
+ assertInsideMount(containerPath, displayPath, route, workspaceReal, outside = "deny") {
1622
+ if (this.insideMounts(containerPath, route, workspaceReal)) return;
1623
+ if (outside === "absent" && !this.namesMountPath(displayPath, route, workspaceReal)) throw new FsError(fsUnmountedText(displayPath), "FS_NOT_FOUND");
1443
1624
  throw new FsError(fsEscapeRefusalText(displayPath, containerPath, route.preset), "FS_PERMISSION_DENIED");
1444
1625
  }
1445
- /** Refuse an already-resolved target that leaves the repository's mount. */
1446
- assertTargetInsideMount(target, route, channel) {
1447
- this.assertInsideMount(String(target.targetKey), target.displayPath, route, channel.handshake.workspaceReal);
1626
+ /** Fence an already-resolved target against the repository's mount. */
1627
+ assertTargetInsideMount(target, route, channel, outside = "deny") {
1628
+ this.assertInsideMount(String(target.targetKey), target.displayPath, route, channel.handshake.workspaceReal, outside);
1448
1629
  }
1449
1630
  /**
1450
1631
  * Install the target-taking mutations this build's base class may not declare.
@@ -1560,9 +1741,10 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1560
1741
  cwd
1561
1742
  };
1562
1743
  }
1744
+ const mounts = sbxExtraMountsOf(repository);
1563
1745
  return {
1564
- path: toHostPath(path, repository),
1565
- cwd: cwd === void 0 ? void 0 : toHostPath(cwd, repository)
1746
+ path: toHostPath(path, repository, mounts),
1747
+ cwd: cwd === void 0 ? void 0 : toHostPath(cwd, repository, mounts)
1566
1748
  };
1567
1749
  }
1568
1750
  /**
@@ -1600,7 +1782,7 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1600
1782
  const attributed = this.specForSandboxPath(path, adopt);
1601
1783
  if (attributed !== void 0) return attributed;
1602
1784
  const root = sbxWorkspaceRootFor(path, base, void 0);
1603
- return root === void 0 ? void 0 : sbxSpecFor(root, this.options);
1785
+ return root === void 0 ? void 0 : sbxSpecFor(root, liveSbxOptions(this.ctx, this.options), void 0);
1604
1786
  }
1605
1787
  /**
1606
1788
  * The specification a sandbox-spelled path names, reversed onto the host.
@@ -1613,12 +1795,12 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1613
1795
  * declares a container above the directory it spells: `/f/…` cannot claim
1614
1796
  * whatever host path it happens to name, and a sandbox path outside every mount
1615
1797
  * stays refused locally.
1616
- * @param path - the path the call named.
1798
+ * @param path - the path the call named, in either spelling.
1617
1799
  * @param adopt - the calling track's view of a declared specification.
1618
1800
  * @returns the governing specification, or undefined when nothing attributes the path.
1619
1801
  */
1620
1802
  specForSandboxPath(path, adopt) {
1621
- const attributed = sandboxHostPathFor(path);
1803
+ const attributed = sandboxHostPathFor(path) ?? (isWindowsPath(path) || isPosixAbsolute(path) ? sbxMountAttribution(path) : void 0);
1622
1804
  if (attributed === void 0) return void 0;
1623
1805
  const declared = repoRegistry(this.ctx).locate(attributed.host, {
1624
1806
  ...this.options,
@@ -1626,16 +1808,20 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1626
1808
  });
1627
1809
  if (declared !== void 0) return adopt(declared);
1628
1810
  if (attributed.workspaceRoot === void 0) return void 0;
1629
- return sbxSpecFor(attributed.workspaceRoot, this.options);
1811
+ const spec = sbxSpecFor(attributed.workspaceRoot, liveSbxOptions(this.ctx, this.options), void 0);
1812
+ return attributed.sandbox === void 0 ? spec : {
1813
+ ...spec,
1814
+ sandbox: attributed.sandbox
1815
+ };
1630
1816
  }
1631
1817
  /**
1632
1818
  * Whether the fallback repository may claim one path.
1633
1819
  *
1634
- * A container path of that repository, a host path under its root, or a
1635
- * relative path that resolves — against the same base the fallback names —
1636
- * to somewhere inside it. Anything else is a host path the repository does
1637
- * not own: `..` traversal and absolute paths elsewhere on the machine
1638
- * included.
1820
+ * A container path of that repository, a host path under its root, a host path
1821
+ * one of its declared extra mounts covers, or a relative path that resolves —
1822
+ * against the same base the fallback names — to somewhere inside it. Anything
1823
+ * else is a host path the repository does not own: `..` traversal and absolute
1824
+ * paths elsewhere on the machine included.
1639
1825
  * @param path - the path the call named.
1640
1826
  * @param base - the directory relative paths resolve against.
1641
1827
  * @param spec - the fallback repository specification.
@@ -1644,8 +1830,9 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1644
1830
  belongsTo(path, base, spec) {
1645
1831
  if (isPathInsideContainer(path, spec)) return true;
1646
1832
  if (relativeWithinHostRoot(path, spec.hostWorkspaceRoot) !== void 0) return true;
1833
+ if (sbxExtraMountsOf(spec).some((mount) => relativeWithinHostRoot(path, mount.host) !== void 0)) return true;
1647
1834
  if (isWindowsPath(path) || isPosixAbsolute(path)) return false;
1648
- const hostBase = toHostPath(base, spec);
1835
+ const hostBase = toHostPath(base, spec, sbxExtraMountsOf(spec));
1649
1836
  if (!isWindowsPath(hostBase) && !isPosixAbsolute(hostBase)) return true;
1650
1837
  return relativeWithinHostRoot(joinHostRoot(hostBase, path), spec.hostWorkspaceRoot) !== void 0;
1651
1838
  }
@@ -1672,7 +1859,8 @@ var DevcontainerFileSystem = class extends SandboxedFileSystem {
1672
1859
  });
1673
1860
  const root = declared?.hostWorkspaceRoot ?? base;
1674
1861
  if (root === "") return;
1675
- await this.runtimeTarget(sbxSpecFor(root, this.options, declared)).catch(() => {});
1862
+ const spec = sbxSpecFor(root, liveSbxOptions(this.ctx, this.options), declared);
1863
+ await this.runtimeTarget(spec).catch(() => {});
1676
1864
  }
1677
1865
  /**
1678
1866
  * The container requirement governing this call.