@capybara-hq/device 0.1.0-rc.17 → 0.1.0-rc.19

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.
Files changed (107) hide show
  1. package/README.md +143 -32
  2. package/dist/activity.d.ts +31 -0
  3. package/dist/activity.js +62 -0
  4. package/dist/api.d.ts +3 -3
  5. package/dist/args.d.ts +25 -4
  6. package/dist/args.js +82 -21
  7. package/dist/cli.js +14 -3
  8. package/dist/client.js +1 -1
  9. package/dist/commands/ceiling.d.ts +3 -2
  10. package/dist/commands/ceiling.js +60 -20
  11. package/dist/commands/keep-awake.d.ts +19 -0
  12. package/dist/commands/keep-awake.js +77 -0
  13. package/dist/commands/login.d.ts +15 -11
  14. package/dist/commands/login.js +75 -49
  15. package/dist/commands/policy.js +16 -10
  16. package/dist/commands/service.d.ts +3 -1
  17. package/dist/commands/service.js +35 -2
  18. package/dist/commands/start.d.ts +18 -3
  19. package/dist/commands/start.js +144 -9
  20. package/dist/commands/status.d.ts +8 -1
  21. package/dist/commands/status.js +59 -7
  22. package/dist/control/client.d.ts +12 -0
  23. package/dist/control/client.js +63 -0
  24. package/dist/control/protocol.d.ts +58 -0
  25. package/dist/control/protocol.js +16 -0
  26. package/dist/control/server.d.ts +28 -0
  27. package/dist/control/server.js +254 -0
  28. package/dist/exec/docker-operations.d.ts +14 -2
  29. package/dist/exec/docker-operations.js +32 -5
  30. package/dist/exec/linux-agent.d.ts +13 -3
  31. package/dist/exec/linux-agent.js +450 -43
  32. package/dist/exec/linux-operation-backend.d.ts +27 -6
  33. package/dist/exec/linux-operation-backend.js +30 -9
  34. package/dist/exec/linux-operation-worker.d.ts +51 -3
  35. package/dist/exec/linux-operation-worker.js +55 -3
  36. package/dist/exec/linux-runtime.d.ts +3 -2
  37. package/dist/exec/linux-runtime.js +4 -2
  38. package/dist/exec/mac-operation-backend.d.ts +12 -2
  39. package/dist/exec/mac-operation-backend.js +19 -10
  40. package/dist/exec/mac-write-policy.d.ts +2 -0
  41. package/dist/exec/mac-write-policy.js +1 -1
  42. package/dist/exec/operation-supervisor.d.ts +6 -0
  43. package/dist/exec/operation-supervisor.js +10 -0
  44. package/dist/exec/operation-types.d.ts +35 -5
  45. package/dist/exec/operation-types.js +73 -23
  46. package/dist/exec/operation-worker.d.ts +80 -1
  47. package/dist/exec/operation-worker.js +197 -14
  48. package/dist/exec/protected-targets.d.ts +16 -0
  49. package/dist/exec/protected-targets.js +53 -0
  50. package/dist/exec/shared.d.ts +7 -3
  51. package/dist/exec/shared.js +7 -5
  52. package/dist/index.d.ts +2 -0
  53. package/dist/index.js +1 -0
  54. package/dist/keep-awake.d.ts +39 -0
  55. package/dist/keep-awake.js +104 -0
  56. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +343 -7
  57. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/resolved-address-guard.js +220 -6
  58. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +17 -0
  59. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +11 -0
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +77 -46
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +206 -83
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +5 -2
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +5 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.d.ts +98 -0
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.js +291 -0
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-linux-runtime-source.js +460 -28
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-native-runtime-source.js +143 -3
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +36 -4
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.js +21 -4
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-runtime-source.js +2 -2
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.d.ts +87 -8
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.js +249 -10
  74. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox.d.ts +11 -22
  75. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
  76. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
  77. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
  78. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
  79. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
  80. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
  81. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
  82. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  83. package/dist/owner-report.d.ts +1 -1
  84. package/dist/owner-report.js +5 -4
  85. package/dist/policy-store.d.ts +2 -1
  86. package/dist/policy-store.js +2 -1
  87. package/dist/policy.d.ts +23 -14
  88. package/dist/policy.js +28 -21
  89. package/dist/runtime-manifest.json +1 -1
  90. package/dist/server-ops.d.ts +33 -5
  91. package/dist/server-ops.js +138 -85
  92. package/dist/service/launchd.d.ts +2 -0
  93. package/dist/service/launchd.js +10 -4
  94. package/dist/service/manager.d.ts +2 -0
  95. package/dist/service/manager.js +16 -2
  96. package/dist/service/systemd.d.ts +2 -0
  97. package/dist/service/systemd.js +8 -2
  98. package/dist/staged-connect.d.ts +10 -1
  99. package/dist/staged-connect.js +25 -3
  100. package/dist/staged-device.d.ts +1 -1
  101. package/dist/staged-device.js +13 -5
  102. package/dist/staged-session.d.ts +1 -1
  103. package/dist/state.d.ts +50 -21
  104. package/dist/state.js +111 -46
  105. package/dist/wake.d.ts +23 -0
  106. package/dist/wake.js +29 -0
  107. package/package.json +2 -2
@@ -0,0 +1,254 @@
1
+ import { chmodSync, lstatSync, statSync, unlinkSync } from "node:fs";
2
+ import { createConnection, createServer } from "node:net";
3
+ import { CONTROL_LINE_MAX_BYTES, CONTROL_OPS, CONTROL_PATH_MAX_BYTES, CONTROL_WRITE_MAX_BYTES, controlSocketPath, } from "./protocol.js";
4
+ /** How long the check for a live socket at the path waits for a connection. */
5
+ const PROBE_TIMEOUT_MS = 1000;
6
+ /** Owner-only peers: a handful of connections is plenty (the desktop app, a `status`). */
7
+ const MAX_CONNECTIONS = 32;
8
+ const mode = (st) => `0${(st.mode & 0o777).toString(8)}`;
9
+ /**
10
+ * Why no control socket can be made for this state directory, from what is visible without
11
+ * binding: a path over {@link CONTROL_PATH_MAX_BYTES}, or a state directory that is missing, not
12
+ * the user's or open to other users (the same owner and mode rule the credential file follows).
13
+ * Undefined when nothing is in the way. `status` uses it to explain a runner that does not answer.
14
+ */
15
+ export function controlUnavailableReason(stateDir) {
16
+ const path = controlSocketPath(stateDir);
17
+ const bytes = Buffer.byteLength(path);
18
+ if (bytes > CONTROL_PATH_MAX_BYTES) {
19
+ return (`the control socket path ${path} is ${bytes} bytes, longer than the ` +
20
+ `${CONTROL_PATH_MAX_BYTES} bytes a unix socket path may have; use a shorter XDG_CONFIG_HOME`);
21
+ }
22
+ let st;
23
+ try {
24
+ st = statSync(stateDir);
25
+ }
26
+ catch (e) {
27
+ return `the state directory ${stateDir} cannot be read (${e.message})`;
28
+ }
29
+ if (!st.isDirectory())
30
+ return `the state directory ${stateDir} is not a directory`;
31
+ const uid = process.getuid?.();
32
+ if (uid !== undefined && st.uid !== uid) {
33
+ return `the state directory ${stateDir} belongs to another user (uid ${st.uid})`;
34
+ }
35
+ if ((st.mode & 0o077) !== 0) {
36
+ return (`the state directory ${stateDir} has mode ${mode(st)}, open to other users; ` +
37
+ `run chmod 700 ${stateDir}`);
38
+ }
39
+ return undefined;
40
+ }
41
+ /** Whether something answers on the socket at `path`: "live", "stale" (nothing listens) or why not. */
42
+ function probe(path) {
43
+ return new Promise((resolve) => {
44
+ const sock = createConnection(path);
45
+ const done = (r) => {
46
+ clearTimeout(timer);
47
+ sock.destroy();
48
+ resolve(r);
49
+ };
50
+ const timer = setTimeout(() => done({ error: "it did not answer in time" }), PROBE_TIMEOUT_MS);
51
+ sock.once("connect", () => done("live"));
52
+ sock.once("error", (e) => done(e.code === "ECONNREFUSED" || e.code === "ENOENT" ? "stale" : { error: e.message }));
53
+ });
54
+ }
55
+ /**
56
+ * Clears the way for a socket at `path`: nothing there, or a stale socket of this user (nothing
57
+ * listens) that is removed. A live socket, a file that is not a socket or one of another user is
58
+ * never touched. Answers why not, or undefined when the path is free.
59
+ */
60
+ async function clearPath(path) {
61
+ let st;
62
+ try {
63
+ st = lstatSync(path);
64
+ }
65
+ catch {
66
+ return undefined;
67
+ }
68
+ if (!st.isSocket())
69
+ return `${path} exists and is not a socket; it was left alone`;
70
+ const uid = process.getuid?.();
71
+ if (uid !== undefined && st.uid !== uid)
72
+ return `${path} belongs to another user`;
73
+ const found = await probe(path);
74
+ if (found === "live")
75
+ return `another capybara-device already answers on ${path}`;
76
+ if (found !== "stale")
77
+ return `${path} cannot be checked (${found.error})`;
78
+ try {
79
+ // only the socket judged stale: a file replaced meanwhile is left alone
80
+ const now = lstatSync(path);
81
+ if (now.ino === st.ino && now.dev === st.dev)
82
+ unlinkSync(path);
83
+ }
84
+ catch {
85
+ // gone already
86
+ }
87
+ return undefined;
88
+ }
89
+ /** Binds `path` with the umask closed to group and others, so the socket is never wider than 0600. */
90
+ function listen(server, path) {
91
+ return new Promise((resolve, reject) => {
92
+ server.once("error", reject);
93
+ // the bind of a unix socket happens inside listen(), synchronously: the umask is restored
94
+ // right after it, never left closed across an await
95
+ const umask = process.umask(0o077);
96
+ try {
97
+ server.listen(path, () => {
98
+ server.off("error", reject);
99
+ resolve();
100
+ });
101
+ }
102
+ finally {
103
+ process.umask(umask);
104
+ }
105
+ });
106
+ }
107
+ /**
108
+ * Starts the control socket at `<stateDir>/control.sock` (mode 0600). Answers `{ unavailable }`
109
+ * with the reason instead when the socket cannot be made safely; the runner keeps serving then.
110
+ */
111
+ export async function startControlServer(opts) {
112
+ const path = controlSocketPath(opts.stateDir);
113
+ const blocked = controlUnavailableReason(opts.stateDir) ?? (await clearPath(path));
114
+ if (blocked !== undefined)
115
+ return { unavailable: blocked };
116
+ const sockets = new Set();
117
+ const subscribers = new Set();
118
+ const send = (sock, line) => {
119
+ if (sock.destroyed || !sock.writable)
120
+ return;
121
+ sock.write(`${JSON.stringify(line)}\n`);
122
+ // a peer that stopped reading (a subscriber above all) never pins memory here
123
+ if (sock.writableLength > CONTROL_WRITE_MAX_BYTES)
124
+ sock.destroy();
125
+ };
126
+ const failure = (id, code, message) => ({
127
+ id,
128
+ ok: false,
129
+ error: { code, message },
130
+ });
131
+ const fail = (sock, id, code, message) => send(sock, failure(id, code, message));
132
+ /** The answer to one request line; a subscribe also adds the connection to the subscribers. */
133
+ const respond = (sock, line) => {
134
+ let req;
135
+ try {
136
+ req = JSON.parse(line);
137
+ }
138
+ catch {
139
+ return failure(0, "bad_request", "The line is not JSON");
140
+ }
141
+ const r = (req !== null && typeof req === "object" ? req : {});
142
+ const id = typeof r.id === "number" && Number.isSafeInteger(r.id) && r.id > 0 ? r.id : 0;
143
+ if (id === 0)
144
+ return failure(0, "bad_request", 'The request needs "id", a positive integer');
145
+ if (typeof r.op !== "string" || !CONTROL_OPS.includes(r.op)) {
146
+ return failure(id, "unknown_op", `Unknown op; one of ${CONTROL_OPS.join(", ")}`);
147
+ }
148
+ const op = r.op;
149
+ try {
150
+ if (op === "status")
151
+ return { id, ok: true, result: opts.status() };
152
+ if (op === "running")
153
+ return { id, ok: true, result: opts.running() };
154
+ if (op === "subscribe") {
155
+ subscribers.add(sock);
156
+ return { id, ok: true, result: opts.status() };
157
+ }
158
+ if (op === "drain")
159
+ opts.drain();
160
+ else
161
+ opts.stop();
162
+ return { id, ok: true, result: null };
163
+ }
164
+ catch (e) {
165
+ return failure(id, "failed", e.message);
166
+ }
167
+ };
168
+ const answer = (sock, line) => send(sock, respond(sock, line));
169
+ const server = createServer((sock) => {
170
+ sockets.add(sock);
171
+ sock.setEncoding("utf8");
172
+ let buf = "";
173
+ let refused = false;
174
+ const overLong = () => {
175
+ refused = true;
176
+ buf = "";
177
+ fail(sock, 0, "bad_request", `A line is longer than ${CONTROL_LINE_MAX_BYTES} bytes`);
178
+ sock.end();
179
+ };
180
+ // one listener per connection: lines are answered in order
181
+ sock.on("data", (chunk) => {
182
+ if (refused)
183
+ return;
184
+ buf += chunk;
185
+ for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
186
+ const line = buf.slice(0, i);
187
+ buf = buf.slice(i + 1);
188
+ if (Buffer.byteLength(line) > CONTROL_LINE_MAX_BYTES)
189
+ return overLong();
190
+ if (line.trim() !== "")
191
+ answer(sock, line);
192
+ }
193
+ if (Buffer.byteLength(buf) > CONTROL_LINE_MAX_BYTES)
194
+ overLong();
195
+ });
196
+ sock.on("error", () => {
197
+ // a peer that went away: nothing to answer
198
+ });
199
+ sock.on("close", () => {
200
+ sockets.delete(sock);
201
+ subscribers.delete(sock);
202
+ });
203
+ });
204
+ server.maxConnections = MAX_CONNECTIONS;
205
+ try {
206
+ await listen(server, path);
207
+ }
208
+ catch (e) {
209
+ const err = e;
210
+ return {
211
+ unavailable: err.code === "EADDRINUSE"
212
+ ? `another capybara-device already answers on ${path}`
213
+ : `cannot listen on ${path} (${err.message})`,
214
+ };
215
+ }
216
+ let bound;
217
+ try {
218
+ chmodSync(path, 0o600);
219
+ bound = lstatSync(path);
220
+ }
221
+ catch (e) {
222
+ await new Promise((r) => server.close(() => r()));
223
+ return { unavailable: `cannot secure ${path} (${e.message})` };
224
+ }
225
+ server.on("error", () => {
226
+ // a failure after listening affects new connections only; the runner keeps serving
227
+ });
228
+ let closed;
229
+ return {
230
+ publish(s) {
231
+ for (const sock of subscribers)
232
+ send(sock, { event: "status", status: s });
233
+ },
234
+ close() {
235
+ closed ??= new Promise((resolve) => {
236
+ for (const sock of sockets)
237
+ sock.destroy();
238
+ server.close(() => {
239
+ try {
240
+ // only the socket this server bound: one another runner bound meanwhile stays
241
+ const now = lstatSync(path);
242
+ if (now.ino === bound.ino && now.dev === bound.dev)
243
+ unlinkSync(path);
244
+ }
245
+ catch {
246
+ // removed already (the listener's close unlinks it)
247
+ }
248
+ resolve();
249
+ });
250
+ });
251
+ return closed;
252
+ },
253
+ };
254
+ }
@@ -1,3 +1,4 @@
1
+ import { networkInterfaces } from "node:os";
1
2
  import { type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
3
  import { type LinuxBackendDependencies, type LocalOperationBackend } from "./linux-operation-backend.js";
3
4
  import { type LinuxAgentTransport } from "./linux-runtime.js";
@@ -11,8 +12,19 @@ export interface OperationContainerHost {
11
12
  release: () => void;
12
13
  }>;
13
14
  }
14
- /** A container command's starting environment: the image's ordinary one, never this host's. */
15
- export declare function containerBaseEnv(full: boolean): Record<string, string>;
15
+ /** The device's files lock inside its container (see the worker's `filesLock`). */
16
+ export declare const CONTAINER_FILES_LOCK = "/dev/shm/capybara-device-files.lock";
17
+ /**
18
+ * A container command's starting environment: the image's ordinary one, never this host's (so an
19
+ * escalated call carries none of the device's variables either).
20
+ */
21
+ export declare function containerBaseEnv(escalated: boolean): Record<string, string>;
22
+ /**
23
+ * This host's own interface addresses (loopback aside, which the container's forwarder closes as a
24
+ * class). A container reaches its host through NAT, so the forwarder in the container closes these
25
+ * explicitly: a service on the host is not reachable at the host's public address either.
26
+ */
27
+ export declare function hostAddresses(interfaces?: ReturnType<typeof networkInterfaces>): string[];
16
28
  /**
17
29
  * Agents in the device's local container: one `docker exec` per operation as the container user,
18
30
  * with the agent's source inline (nothing staged in the container). The container stays held
@@ -1,6 +1,7 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { constants } from "node:fs";
3
3
  import { open, realpath } from "node:fs/promises";
4
+ import { networkInterfaces } from "node:os";
4
5
  import { basename, dirname, join } from "node:path";
5
6
  import { DEFAULT_SANDBOX_ROOTS, SandboxScopeDeniedError, } from "@capybara-hq/plugin-sdk";
6
7
  import { checkLinuxRestrictedGrant, } from "./linux-operation-backend.js";
@@ -13,10 +14,15 @@ import { createCancellationAttempt, } from "./operation-worker.js";
13
14
  import { acquireSealedRuntime, stageRuntimeSource } from "./runtime-source.js";
14
15
  /** The image's interpreter, by absolute path (never looked up through a PATH). */
15
16
  const CONTAINER_PYTHON = "/usr/bin/python3";
17
+ /** The device's files lock inside its container (see the worker's `filesLock`). */
18
+ export const CONTAINER_FILES_LOCK = "/dev/shm/capybara-device-files.lock";
16
19
  const CONTAINER_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
17
- /** A container command's starting environment: the image's ordinary one, never this host's. */
18
- export function containerBaseEnv(full) {
19
- return full
20
+ /**
21
+ * A container command's starting environment: the image's ordinary one, never this host's (so an
22
+ * escalated call carries none of the device's variables either).
23
+ */
24
+ export function containerBaseEnv(escalated) {
25
+ return escalated
20
26
  ? {
21
27
  PATH: CONTAINER_PATH,
22
28
  LANG: "C.UTF-8",
@@ -26,6 +32,19 @@ export function containerBaseEnv(full) {
26
32
  }
27
33
  : { PATH: CONTAINER_PATH, LANG: "C.UTF-8" };
28
34
  }
35
+ /**
36
+ * This host's own interface addresses (loopback aside, which the container's forwarder closes as a
37
+ * class). A container reaches its host through NAT, so the forwarder in the container closes these
38
+ * explicitly: a service on the host is not reachable at the host's public address either.
39
+ */
40
+ export function hostAddresses(interfaces = networkInterfaces()) {
41
+ const out = [];
42
+ for (const entries of Object.values(interfaces))
43
+ for (const entry of entries ?? [])
44
+ if (!entry.internal)
45
+ out.push(entry.address);
46
+ return out;
47
+ }
29
48
  /**
30
49
  * Ends an agent left inside the container after its `docker exec` client died: the exact process
31
50
  * (PID plus start time, checked again before each signal) gets SIGTERM, then SIGKILL, and this
@@ -229,7 +248,7 @@ dependencies = {}) {
229
248
  let probe = await (dependencies.probe ?? (() => probeLinuxRuntime(transport)))();
230
249
  if (probe.restricted !== null && !dependencies.probe) {
231
250
  // the kernel supports it; the bind mounts must keep Landlock's rules as well
232
- const failure = await checkRestrictedRoot(transport, DEFAULT_SANDBOX_ROOTS.tmp, containerBaseEnv(false));
251
+ const failure = await checkRestrictedRoot(transport, DEFAULT_SANDBOX_ROOTS.tmp, containerBaseEnv(false), CONTAINER_FILES_LOCK);
233
252
  if (failure)
234
253
  probe = { restricted: null, reason: failure };
235
254
  }
@@ -244,9 +263,15 @@ dependencies = {}) {
244
263
  const worker = dependencies.startWorker ??
245
264
  linuxOperationWorker({
246
265
  transport,
266
+ // one container per device holds every operation's agent: its private /dev/shm is the
267
+ // device's, and outside every root a restricted grant can name (workspace, tmp, skills)
268
+ filesLock: CONTAINER_FILES_LOCK,
247
269
  baseEnv: containerBaseEnv,
248
270
  acquireRuntime: acquire,
271
+ closedAddresses: () => hostAddresses(),
249
272
  ...(dependencies.allowPrivateProxyTargets ? { allowPrivateProxyTargets: true } : {}),
273
+ ...(dependencies.fakeIpDnsTest ? { fakeIpDnsTest: dependencies.fakeIpDnsTest } : {}),
274
+ ...(dependencies.faultInjection ? { faultInjection: dependencies.faultInjection } : {}),
250
275
  });
251
276
  const startWorker = async (request, signal) => request.kind === "native" &&
252
277
  request.purpose === "preparation" &&
@@ -264,7 +289,9 @@ dependencies = {}) {
264
289
  }, {
265
290
  restricted: unavailableReason === undefined,
266
291
  ...(unavailableReason ? { unavailableReason } : {}),
267
- fullAccess: probe.agentAvailable !== false,
292
+ // the operation's forwarder enforces the open public network on the resolved address
293
+ openPublic: true,
294
+ outsideSandbox: probe.agentAvailable !== false,
268
295
  background: probe.agentAvailable !== false,
269
296
  pending: unavailableReason ?? "Restricted execution in the device container is unavailable",
270
297
  startWorker,
@@ -12,9 +12,19 @@
12
12
  * base64, at most 64 KiB), `native`, `probe`, `reaped`, `refused`, `exit`.
13
13
  *
14
14
  * - restricted exec: pins every granted root once (no-follow, canonical), runs the SDK launcher on
15
- * those descriptors (Landlock rules, the seccomp broker), and for an allowlist gives it exactly
16
- * one endpoint, a loopback proxy owned by this operation that tunnels only the allowlisted names.
17
- * Whatever ends the launcher, the agent then reaps its closed session (exact SID plus start time).
15
+ * those descriptors (Landlock rules, the seccomp broker), and for an allowlist or the open
16
+ * network gives it exactly one endpoint, a loopback proxy owned by this operation: it tunnels
17
+ * only the allowlisted names, or (open) any name and address literal on any port, and dials only
18
+ * resolved addresses the SDK's address-class table calls public (a copy kept equal by a test),
19
+ * never this host's own nor one of the request's extra closed addresses (a local-Docker
20
+ * device's host), re-resolving a fake-IP resolver's answers through encrypted DNS. A command
21
+ * connects to nothing else, not even its own loopback listener. Whatever ends the launcher, the agent then reaps its closed session (exact SID plus
22
+ * start time). Write denies the device resolved for this operation (protected home locations
23
+ * reached through links) go to the launcher and to native work. The agent opens the device's
24
+ * files lock (a private file at the path the device chose, outside every sandbox) and hands its
25
+ * descriptor to the launcher only, so every operation of the device shares one write lock.
26
+ * A restricted native write takes the same lock in this process (shared, from its check to its
27
+ * effect), and the native helper checks each entry it creates again where it landed.
18
28
  * - Full exec: no restricted filters; the command runs as the OS user in a session of its own, and
19
29
  * the agent ends that session (exact SID plus start time) when it exits, is cancelled or times out.
20
30
  * - native: the SDK native helper on pinned descriptors (descriptor-relative, no-follow), in this