windows-development-sandbox 1.7.0 → 1.9.0

package/dist/shared/pty/output-filter.js

@@ -8,13 +8,19 @@ const KEPT_OSC = (body) => {
 };
 /** Longest OSC kept (a title or a link); anything longer is dropped whole. */
 const MAX_KEPT_STRING = 4096;
+/** Longest clipboard write kept (about 750 KB of text); anything longer is dropped whole. */
+const MAX_CLIPBOARD_STRING = 1024 * 1024;
+/** A clipboard write (OSC 52: selection, then base64): never a read ("?"), which would send the clipboard back. */
+const CLIPBOARD_WRITE = /^0{0,2}52;[cpqs0-7]{0,8};[A-Za-z0-9+/=]*$/;
 /**
  * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
- * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
+ * terminal: clipboard writes (OSC 52, unless clipboardWrites) and reads, terminal macros (ConEmu's OSC 9), DCS / APC /
+ * PM / SOS, and their C1 forms.
  * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
  * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
  */
 export class OutputFilter {
+    options;
     /**
      * text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc /
      * stringC2: a possible terminator inside one.
@@ -22,8 +28,20 @@ export class OutputFilter {
     state = 'text';
     /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
     body = null;
+    maxString;
+    constructor(options = {}) {
+        this.options = options;
+        this.maxString = options.clipboardWrites ? MAX_CLIPBOARD_STRING : MAX_KEPT_STRING;
+    }
+    /** An OSC that may pass: a short title, link, progress or mark, or (when allowed) a clipboard write. */
+    kept(body) {
+        if (this.options.clipboardWrites && CLIPBOARD_WRITE.test(body))
+            return true;
+        return body.length <= MAX_KEPT_STRING && KEPT_OSC(body);
+    }
     push(chunk) {
-        const out = Buffer.allocUnsafe(chunk.length + MAX_KEPT_STRING + 8);
+        // At most: the string carried over from the last chunk, this chunk, and an OSC prefix and terminator.
+        const out = Buffer.allocUnsafe(chunk.length + (this.body?.length ?? 0) + 8);
         let n = 0;
         const put = (...bytes) => {
             for (const b of bytes)
@@ -45,7 +63,7 @@ export class OutputFilter {
         };
         const endString = (terminator) => {
             const body = this.body && Buffer.from(this.body).toString('latin1');
-            if (body !== null && KEPT_OSC(body)) {
+            if (body !== null && this.kept(body)) {
                 put(0x1b, 0x5d);
                 out.write(body, n, 'latin1');
                 n += body.length;
@@ -55,7 +73,7 @@ export class OutputFilter {
             this.state = 'text';
         };
         const collect = (b) => {
-            if (this.body && this.body.push(b) > MAX_KEPT_STRING)
+            if (this.body && this.body.push(b) > this.maxString)
                 this.body = null;
         };
         for (const b of chunk) {

package/dist/shared/pty/terminal.d.ts

@@ -22,6 +22,9 @@ export declare function fixWindowsKeys(chunk: Buffer): Buffer;
  * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
  * the detach key. Restores the terminal before resolving.
  */
-export declare function runTerminalClient(socket: net.Socket, token: string, options?: {
+export declare function runTerminalClient(socket: net.Socket, token: string, 
+/** clipboardWrites: the agent's "copy" (OSC 52) reaches the clipboard; see OutputFilterOptions. */
+options?: {
     detachKey?: number;
+    clipboardWrites?: boolean;
 }): Promise<ClientResult>;

package/dist/shared/pty/terminal.js

@@ -20,7 +20,9 @@ export function fixWindowsKeys(chunk) {
  * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
  * the detach key. Restores the terminal before resolving.
  */
-export function runTerminalClient(socket, token, options = {}) {
+export function runTerminalClient(socket, token, 
+/** clipboardWrites: the agent's "copy" (OSC 52) reaches the clipboard; see OutputFilterOptions. */
+options = {}) {
     const stdin = process.stdin;
     const stdout = process.stdout;
     // getWindowSize asks the console every time; columns/rows only change when Node noticed a resize.
@@ -33,7 +35,7 @@ export function runTerminalClient(socket, token, options = {}) {
     return new Promise((resolve) => {
         let done = false;
         const reader = new FrameReader();
-        const filter = new OutputFilter();
+        const filter = new OutputFilter({ clipboardWrites: options.clipboardWrites });
         let sent = size();
         let resizeTimer;
         // Set once raw mode is on (below); finish() may run before that.

package/dist/shared/system.d.ts

@@ -15,6 +15,7 @@ export declare const SYSTEM: {
     readonly shutdown: () => string;
     readonly dism: () => string;
     readonly msiexec: () => string;
+    readonly sc: () => string;
     /** The .NET Framework C# compiler that ships with Windows (C# 5). */
     readonly csc: () => string;
 };

package/dist/shared/system.js

@@ -21,6 +21,7 @@ export const SYSTEM = {
     shutdown: () => system32('shutdown.exe'),
     dism: () => system32('Dism.exe'),
     msiexec: () => system32('msiexec.exe'),
+    sc: () => system32('sc.exe'),
     /** The .NET Framework C# compiler that ships with Windows (C# 5). */
     csc: () => path.join(systemRoot(), 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe'),
 };

package/dist/shared/vpn/download.d.ts

@@ -11,3 +11,19 @@ export declare const OPENVPN_MSI: {
     };
     readonly base: "https://swupdate.openvpn.org/community/releases/";
 };
+/**
+ * WireGuard for Windows (brings wireguard.exe and wg.exe). Hashes computed from the files on download.wireguard.com
+ * (https); both files carry a valid WireGuard LLC signature.
+ */
+export declare const WIREGUARD_MSI: {
+    readonly version: "1.1.1";
+    readonly x64: {
+        readonly file: "wireguard-amd64-1.1.1.msi";
+        readonly sha256: "7bfed60ad61b785c914b38b61555a975488e1d3ec472dbfb2fcdf498fca75242";
+    };
+    readonly arm64: {
+        readonly file: "wireguard-arm64-1.1.1.msi";
+        readonly sha256: "8336335c738d4aff040fa9d11b752da65a80b6f41d3262d6ba5e82f97ebd1bd4";
+    };
+    readonly base: "https://download.wireguard.com/windows-client/";
+};

package/dist/shared/vpn/download.js

@@ -12,3 +12,19 @@ export const OPENVPN_MSI = {
     },
     base: 'https://swupdate.openvpn.org/community/releases/',
 };
+/**
+ * WireGuard for Windows (brings wireguard.exe and wg.exe). Hashes computed from the files on download.wireguard.com
+ * (https); both files carry a valid WireGuard LLC signature.
+ */
+export const WIREGUARD_MSI = {
+    version: '1.1.1',
+    x64: {
+        file: 'wireguard-amd64-1.1.1.msi',
+        sha256: '7bfed60ad61b785c914b38b61555a975488e1d3ec472dbfb2fcdf498fca75242',
+    },
+    arm64: {
+        file: 'wireguard-arm64-1.1.1.msi',
+        sha256: '8336335c738d4aff040fa9d11b752da65a80b6f41d3262d6ba5e82f97ebd1bd4',
+    },
+    base: 'https://download.wireguard.com/windows-client/',
+};

package/dist/shared/vpn/wireguard.d.ts

@@ -0,0 +1,51 @@
+export declare const MAX_WIREGUARD_BYTES: number;
+/** Keys that run a program, change the routes or write the config back. Refused with a clear reason. */
+export declare const WIREGUARD_PROGRAM_KEYS: readonly ["preup", "postup", "predown", "postdown", "table", "saveconfig"];
+export interface WireguardPeer {
+    readonly publicKey: string;
+    readonly presharedKey?: string;
+    readonly allowedIps: readonly string[];
+    readonly endpointHost: string;
+    readonly endpointPort: number;
+    readonly keepalive?: number;
+}
+/** A checked config. Holds secrets (privateKey, presharedKey): never log it or write it to session.json. */
+export interface WireguardConfig {
+    readonly privateKey: string;
+    readonly addresses: readonly string[];
+    readonly dns: readonly string[];
+    readonly mtu?: number;
+    readonly listenPort?: number;
+    readonly peers: readonly WireguardPeer[];
+}
+export type WireguardReport = {
+    readonly ok: true;
+    readonly config: WireguardConfig;
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/** Where the tunnel connects (the kill switch allows these, over udp). */
+export interface WireguardEndpoint {
+    readonly host: string;
+    readonly port: number;
+}
+/**
+ * Checks a config. `ok: false` lists the problems (no values in them); `ok: true` gives the checked settings. It needs
+ * one [Interface] with a PrivateKey and an IPv4 Address, and at least one [Peer] with PublicKey, AllowedIPs and an
+ * Endpoint that is a name or an IPv4 address (the kill switch rules are IPv4).
+ */
+export declare function inspectWireguard(text: string): WireguardReport;
+/** The checked config; throws, saying why (never with a key), when it is not safe. `what` names the file. */
+export declare function assertSafeWireguard(text: string, what: string): WireguardConfig;
+/** The config as text, written from the checked values. `endpointIps` puts an address in a peer's place. */
+export declare function renderWireguard(config: WireguardConfig, endpointIps?: Readonly<Record<number, string>>): string;
+export declare function wireguardEndpoints(config: WireguardConfig): WireguardEndpoint[];
+/** The tunnel's own IPv4 address (what the kill switch lets through once the tunnel is up). */
+export declare function wireguardTunnelAddress(config: WireguardConfig): string;
+/** True when some peer sends all IPv4 traffic through the tunnel (AllowedIPs 0.0.0.0/0). */
+export declare function routesEverything(config: WireguardConfig): boolean;
+/** Whether `sc query` output says the tunnel service is running. */
+export declare function serviceRunning(scOutput: string): boolean;
+/** Whether `wg show <tunnel> latest-handshakes` says a peer has completed a handshake (a time that is not 0). */
+export declare function handshakeDone(wgOutput: string): boolean;

package/dist/shared/vpn/wireguard.js

@@ -0,0 +1,227 @@
+// A WireGuard config (.conf) is untrusted data: it comes from a file you were given, and WireGuard for Windows runs the
+// programs of PreUp/PostUp/PreDown/PostDown with administrator rights. Only the settings on a short list are accepted;
+// anything else is refused by name, and the config that is handed on is written again from the checked values, never
+// copied. Problem messages name keys and lines, never values (the private and preshared keys are secrets). Also answers
+// where the tunnel connects and which address it has, which the kill switch needs. Pure: no files, no network.
+import net from 'node:net';
+export const MAX_WIREGUARD_BYTES = 16 * 1024;
+const MAX_LINES = 300;
+const MAX_PEERS = 16;
+/** Keys that run a program, change the routes or write the config back. Refused with a clear reason. */
+export const WIREGUARD_PROGRAM_KEYS = ['preup', 'postup', 'predown', 'postdown', 'table', 'saveconfig'];
+const INTERFACE_KEYS = new Set(['privatekey', 'address', 'dns', 'mtu', 'listenport']);
+const PEER_KEYS = new Set(['publickey', 'presharedkey', 'allowedips', 'endpoint', 'persistentkeepalive']);
+/** Keys that may be given more than once (their values are joined). */
+const LIST_KEYS = new Set(['address', 'dns', 'allowedips']);
+const KEY = /^[A-Za-z0-9+/]{43}=$/;
+const HOST = /^(?:\d{1,3}(?:\.\d{1,3}){3}|[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?)$/;
+function validCidr(text) {
+    const [addr, prefix, ...rest] = text.split('/');
+    if (rest.length > 0 || !addr)
+        return false;
+    const version = net.isIP(addr);
+    if (version === 0)
+        return false;
+    if (prefix === undefined)
+        return true;
+    if (!/^\d{1,3}$/.test(prefix))
+        return false;
+    return Number(prefix) <= (version === 4 ? 32 : 128);
+}
+const inRange = (text, low, high) => {
+    if (!/^\d{1,5}$/.test(text))
+        return null;
+    const n = Number(text);
+    return n >= low && n <= high ? n : null;
+};
+const splitList = (text) => text
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+/**
+ * Checks a config. `ok: false` lists the problems (no values in them); `ok: true` gives the checked settings. It needs
+ * one [Interface] with a PrivateKey and an IPv4 Address, and at least one [Peer] with PublicKey, AllowedIPs and an
+ * Endpoint that is a name or an IPv4 address (the kill switch rules are IPv4).
+ */
+export function inspectWireguard(text) {
+    const problems = [];
+    const refuse = (message) => {
+        if (problems.length < 20 && !problems.includes(message))
+            problems.push(message);
+    };
+    if (Buffer.byteLength(text, 'utf8') > MAX_WIREGUARD_BYTES)
+        return { ok: false, problems: ['the file is too big'] };
+    if (text.includes('\0'))
+        return { ok: false, problems: ['the file is not text'] };
+    const lines = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).split(/\r?\n/);
+    if (lines.length > MAX_LINES)
+        return { ok: false, problems: ['the file has too many lines'] };
+    const sections = [];
+    let current = null;
+    lines.forEach((raw, i) => {
+        const at = 'line ' + (i + 1) + ': ';
+        const line = raw.replace(/#.*$/, '').trim();
+        if (!line)
+            return;
+        const header = /^\[([A-Za-z]{1,20})\]$/.exec(line);
+        if (header) {
+            const name = header[1].toLowerCase();
+            if (name !== 'interface' && name !== 'peer') {
+                current = null;
+                return refuse(at + '[' + name + '] is not allowed');
+            }
+            current = { kind: name, values: new Map() };
+            sections.push(current);
+            return;
+        }
+        const pair = /^([A-Za-z]{1,40})\s*=\s*(.*)$/.exec(line);
+        if (!pair)
+            return refuse(at + 'not a "Key = value" line');
+        const key = pair[1].toLowerCase();
+        if (WIREGUARD_PROGRAM_KEYS.includes(key))
+            return refuse(at + pair[1] + ' runs a program or changes how the tunnel is routed or saved');
+        if (!current)
+            return refuse(at + pair[1] + ' is outside a section');
+        if (!(current.kind === 'interface' ? INTERFACE_KEYS : PEER_KEYS).has(key))
+            return refuse(at + pair[1] + ' is not on the list of settings that are safe to accept');
+        const seen = current.values.get(key);
+        if (seen && !LIST_KEYS.has(key))
+            return refuse(at + pair[1] + ' is given twice');
+        current.values.set(key, [...(seen ?? []), pair[2].trim()]);
+    });
+    const one = (s, key) => s.values.get(key)?.[0];
+    const joined = (s, key) => (s.values.get(key) ?? []).flatMap(splitList);
+    const interfaces = sections.filter((s) => s.kind === 'interface');
+    const peers = sections.filter((s) => s.kind === 'peer');
+    if (interfaces.length !== 1)
+        refuse('it needs exactly one [Interface] section');
+    if (peers.length === 0)
+        refuse('it has no [Peer] section');
+    if (peers.length > MAX_PEERS)
+        refuse('it has too many [Peer] sections');
+    if (problems.length)
+        return { ok: false, problems };
+    const face = interfaces[0];
+    const privateKey = one(face, 'privatekey');
+    if (!privateKey)
+        refuse('[Interface] has no PrivateKey');
+    else if (!KEY.test(privateKey))
+        refuse('PrivateKey is not a WireGuard key (44 characters of base64)');
+    const addresses = joined(face, 'address');
+    if (addresses.length === 0 || !addresses.every(validCidr))
+        refuse('[Interface] needs valid Address values');
+    else if (!addresses.some((a) => net.isIPv4(a.split('/')[0])))
+        refuse('Address needs an IPv4 address (the kill switch works on IPv4)');
+    const dns = joined(face, 'dns');
+    if (!dns.every((d) => net.isIP(d) !== 0))
+        refuse('DNS may only list IP addresses');
+    const mtuText = one(face, 'mtu');
+    const mtu = mtuText === undefined ? undefined : inRange(mtuText, 576, 1500);
+    if (mtuText !== undefined && mtu === null)
+        refuse('MTU must be a number from 576 to 1500');
+    const portText = one(face, 'listenport');
+    const listenPort = portText === undefined ? undefined : inRange(portText, 1, 65535);
+    if (portText !== undefined && listenPort === null)
+        refuse('ListenPort must be a number from 1 to 65535');
+    const checked = [];
+    peers.forEach((p, n) => {
+        const who = '[Peer] ' + (n + 1) + ': ';
+        const publicKey = one(p, 'publickey');
+        if (!publicKey || !KEY.test(publicKey))
+            return refuse(who + 'PublicKey is missing or not a WireGuard key');
+        const preshared = one(p, 'presharedkey');
+        if (preshared !== undefined && !KEY.test(preshared))
+            return refuse(who + 'PresharedKey is not a WireGuard key');
+        const allowed = joined(p, 'allowedips');
+        if (allowed.length === 0 || !allowed.every(validCidr))
+            return refuse(who + 'AllowedIPs is missing or invalid');
+        const endpoint = one(p, 'endpoint');
+        const m = endpoint ? /^([^:[\]]+):(\d{1,5})$/.exec(endpoint) : null;
+        if (!m || !HOST.test(m[1]) || inRange(m[2], 1, 65535) === null)
+            return refuse(who + 'Endpoint must be host:port with a name or an IPv4 address');
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(m[1]) && !net.isIPv4(m[1]))
+            return refuse(who + 'Endpoint is not a valid address');
+        const keepText = one(p, 'persistentkeepalive');
+        let keepalive;
+        if (keepText !== undefined && keepText.toLowerCase() !== 'off') {
+            const k = inRange(keepText, 0, 65535);
+            if (k === null)
+                return refuse(who + 'PersistentKeepalive must be a number or off');
+            keepalive = k;
+        }
+        checked.push({
+            publicKey,
+            ...(preshared ? { presharedKey: preshared } : {}),
+            allowedIps: allowed,
+            endpointHost: m[1],
+            endpointPort: Number(m[2]),
+            ...(keepalive !== undefined ? { keepalive } : {}),
+        });
+    });
+    if (problems.length || !privateKey)
+        return { ok: false, problems };
+    return {
+        ok: true,
+        config: {
+            privateKey,
+            addresses,
+            dns,
+            ...(typeof mtu === 'number' ? { mtu } : {}),
+            ...(typeof listenPort === 'number' ? { listenPort } : {}),
+            peers: checked,
+        },
+    };
+}
+/** The checked config; throws, saying why (never with a key), when it is not safe. `what` names the file. */
+export function assertSafeWireguard(text, what) {
+    const report = inspectWireguard(text);
+    if (report.ok)
+        return report.config;
+    throw new Error(what +
+        ' was refused because it could run programs or is not a plain WireGuard config:\n  - ' +
+        report.problems.slice(0, 5).join('\n  - '));
+}
+/** The config as text, written from the checked values. `endpointIps` puts an address in a peer's place. */
+export function renderWireguard(config, endpointIps = {}) {
+    const out = ['[Interface]', 'PrivateKey = ' + config.privateKey, 'Address = ' + config.addresses.join(', ')];
+    if (config.dns.length)
+        out.push('DNS = ' + config.dns.join(', '));
+    if (config.mtu !== undefined)
+        out.push('MTU = ' + config.mtu);
+    if (config.listenPort !== undefined)
+        out.push('ListenPort = ' + config.listenPort);
+    config.peers.forEach((p, i) => {
+        out.push('', '[Peer]', 'PublicKey = ' + p.publicKey);
+        if (p.presharedKey)
+            out.push('PresharedKey = ' + p.presharedKey);
+        out.push('AllowedIPs = ' + p.allowedIps.join(', '), 'Endpoint = ' + (endpointIps[i] ?? p.endpointHost) + ':' + p.endpointPort);
+        if (p.keepalive !== undefined)
+            out.push('PersistentKeepalive = ' + p.keepalive);
+    });
+    return out.join('\r\n') + '\r\n';
+}
+export function wireguardEndpoints(config) {
+    return config.peers.map((p) => ({ host: p.endpointHost, port: p.endpointPort }));
+}
+/** The tunnel's own IPv4 address (what the kill switch lets through once the tunnel is up). */
+export function wireguardTunnelAddress(config) {
+    const found = config.addresses.map((a) => a.split('/')[0]).find((a) => net.isIPv4(a));
+    if (!found)
+        throw new Error('the config has no IPv4 address');
+    return found;
+}
+/** True when some peer sends all IPv4 traffic through the tunnel (AllowedIPs 0.0.0.0/0). */
+export function routesEverything(config) {
+    return config.peers.some((p) => p.allowedIps.some((a) => a === '0.0.0.0/0'));
+}
+/** Whether `sc query` output says the tunnel service is running. */
+export function serviceRunning(scOutput) {
+    return /STATE\s*:\s*\d+\s+RUNNING/i.test(scOutput);
+}
+/** Whether `wg show <tunnel> latest-handshakes` says a peer has completed a handshake (a time that is not 0). */
+export function handshakeDone(wgOutput) {
+    return wgOutput.split(/\r?\n/).some((line) => {
+        const t = /\s(\d+)\s*$/.exec(line);
+        return t !== null && Number(t[1]) > 0;
+    });
+}

package/dist/sync/sync-cycle.js

@@ -1,15 +1,15 @@
 import path from 'node:path';
 import { assertNoLinks } from '../core/util/index.js';
 import { hostClaudeDir, PluginShare } from '../host/profile/index.js';
-import { storageOf } from '../host/storage/index.js';
+import { hostDataFolder, hostDataRoot, storageOf } from '../host/storage/index.js';
 import { hostClaudeMemDir, syncClaudeMem } from './claude-mem.js';
 import { readSyncState, writeSyncState } from './sync-state.js';
 import { syncHistoryIn, syncHistoryOut } from './history.js';
-const guestClaude = (dataPath) => path.join(dataPath, 'state', 'claude');
-const guestMem = (dataPath) => path.join(dataPath, 'state', 'claude-mem');
+const guestClaude = (dataPath) => path.join(hostDataFolder(dataPath, 'state'), 'claude');
+const guestMem = (dataPath) => path.join(hostDataFolder(dataPath, 'state'), 'claude-mem');
 /** Sync paths for the sandbox side, after checking nothing on the way there is a link planted by the sandbox. */
 const toPaths = (state, dataPath) => {
-    assertNoLinks(dataPath, guestClaude(dataPath));
+    assertNoLinks(hostDataRoot(dataPath), guestClaude(dataPath));
     return {
         hostClaudeDir: state.hostClaudeDir,
         guestClaudeDir: guestClaude(dataPath),
@@ -38,7 +38,7 @@ export function syncProjectIn(dataPath, project) {
         : 0;
 }
 const memSync = (dataPath, state, direction) => {
-    assertNoLinks(dataPath, guestMem(dataPath));
+    assertNoLinks(hostDataRoot(dataPath), guestMem(dataPath));
     return syncClaudeMem(hostClaudeMemDir(), guestMem(dataPath), state, direction);
 };
 /** Before launch: finish syncing the previous run out, then bring this PC's history (and claude-mem) in. */

package/dist/sync/watcher.d.ts

@@ -22,12 +22,25 @@ export declare class Watcher {
     private awake;
     private views;
     private stops;
+    private watchdogTimer;
+    private watchdog;
+    private watchdogBusy;
+    private lastCpu;
+    private lastHostLog;
     constructor(dataPath: string, resume?: WatcherResume);
     /** Runs until the sandbox has closed and the final sync is done (or the end deadline passed). */
     run(): Promise<void>;
+    /** Contained storage of this data set (only when a mounted image is on record), else null. */
+    private contained;
+    /** The mounted image stays mounted until the sandbox is gone: this watcher holds it. */
+    private holdContained;
+    /** The sandbox is gone and the last sync done: let go of the image, which dismounts it when nothing else holds it. */
+    private releaseContained;
     private note;
     /** Everything that runs alongside the sandbox, in this order. */
     private start;
+    /** One watchdog sample: this PC's memory and CPU; asks the sandbox to slow down while the PC is low. Never throws. */
+    private watchHost;
     /** The repo guard, then history and (at the end) claude-mem back to this PC. */
     private sync;
     /** The running sessions and their conversations, for the next launch (resume.sessions). */

package/dist/sync/watcher.js

@@ -7,24 +7,29 @@ import { writeFileAtomic } from '../shared/io/index.js';
 import { refuseInSelfTest } from '../host/test-guard.js';
 import { errMsg, sleep } from '../core/util/index.js';
 import { RepoGuardStore } from '../host/guard/index.js';
-import { isSandboxRunning, spawnDetached } from '../host/sandbox/index.js';
+import { isSandboxRunning, realContainedDeps, spawnDetached } from '../host/sandbox/index.js';
 import { readActiveViews, WorkspaceView } from '../host/workspace-view/index.js';
 import { readForwards, sandboxAddress, startPortForwards } from '../host/network/index.js';
 import { AuditCollector, readAuditSettings } from '../host/audit/collect.js';
 import { readMarkedProjects, saveDataSize, watchAndMark } from '../host/guard/index.js';
 import { sizeWithin } from '../core/disk.js';
-import { autoRestartAllowed, causeSince, KeepAwake, LifeRecord, saveCrashReport, SessionLedger, } from '../host/life/index.js';
+import { autoRestartAllowed, causeSince, appendHostMemory, cpuPercentBetween, KeepAwake, LifeRecord, readHostMemoryAsync, readLoadSettings, REQUEST_SECONDS, WATCHDOG_START, watchdogStep, saveCrashReport, SessionLedger, } from '../host/life/index.js';
 import { SandboxChannel } from '../host/channel/index.js';
 import { ProjectRegistry } from '../host/projects/registry.js';
-import { storageOf } from '../host/storage/index.js';
+import { ContainedStorage, setNameOf, storageOf } from '../host/storage/index.js';
 import { clearSecrets } from '../host/secrets/index.js';
 import { endSharing, sharingDeps } from '../host/sharing/index.js';
 import { PACKAGE_ROOT } from '../core/package-info.js';
 import { syncBack } from './sync-cycle.js';
+import os from 'node:os';
 const WATCH_INTERVAL_MS = 60 * 1000;
 /** The first sync waits this long: the sandbox is still booting. */
 const FIRST_SYNC_MS = 30000;
 const AUDIT_FLUSH_MS = 10000;
+/** How often this PC's memory and CPU are sampled (the sample runs asynchronously: it never holds anything up). */
+const WATCHDOG_MS = 10000;
+/** The host memory log gets a line this often, and at every sample while the PC is low. */
+const HOST_LOG_EVERY_MS = 60000;
 /** After the sandbox closed: a moment for its last writes to land before the final sync. */
 const SETTLE_MS = 3000;
 /** The longest the watcher may take after the sandbox closed (final syncs) before it stops anyway. */
@@ -79,6 +84,11 @@ export class Watcher {
     awake = null;
     views = [];
     stops = [];
+    watchdogTimer = null;
+    watchdog = WATCHDOG_START;
+    watchdogBusy = false;
+    lastCpu = os.cpus();
+    lastHostLog = 0;
     constructor(dataPath, resume = { restartAfterCrash: false }) {
         this.dataPath = dataPath;
         this.resume = resume;
@@ -95,6 +105,7 @@ export class Watcher {
         fs.mkdirSync(path.dirname(watcherLog(this.dataPath)), { recursive: true });
         writeFileAtomic(watcherPidFile(this.dataPath), String(process.pid));
         this.start();
+        this.holdContained();
         try {
             await sleep(FIRST_SYNC_MS);
             while (isSandboxRunning()) {
@@ -116,10 +127,44 @@ export class Watcher {
         }
         finally {
             this.stop();
+            await this.releaseContained();
         }
         // After stop(): its pid file is gone, so the sandbox started again gets a watcher of its own.
         this.restartAfterCrash();
     }
+    /** Contained storage of this data set (only when a mounted image is on record), else null. */
+    contained() {
+        try {
+            const storage = new ContainedStorage(realContainedDeps(this.storageRoot, 64), setNameOf(this.dataPath));
+            return storage.isRecorded() ? storage : null;
+        }
+        catch {
+            // Not a name contained storage can use: there is none.
+            return null;
+        }
+    }
+    /** The mounted image stays mounted until the sandbox is gone: this watcher holds it. */
+    holdContained() {
+        try {
+            this.contained()?.hold({ id: 'watcher', pid: process.pid });
+        }
+        catch (e) {
+            this.note('contained storage: could not record the watcher: ' + errMsg(e));
+        }
+    }
+    /** The sandbox is gone and the last sync done: let go of the image, which dismounts it when nothing else holds it. */
+    async releaseContained() {
+        try {
+            const result = await this.contained()?.release('watcher');
+            if (result)
+                this.note(result.dismounted
+                    ? 'contained storage dismounted'
+                    : 'contained storage stays mounted: ' + (result.note ?? ''));
+        }
+        catch (e) {
+            this.note('contained storage: ' + errMsg(e));
+        }
+    }
     note(message) {
         try {
             fs.appendFileSync(watcherLog(this.dataPath), new Date().toISOString() + ' ' + message + '\n');
@@ -162,9 +207,51 @@ export class Watcher {
             }
         });
         this.stops = [...viewStops, stopForwards, stopMarking];
+        // Memory and CPU of this PC: when low, the sandbox is asked to slow its builds down (host/life/watchdog.ts).
+        this.watchdogTimer = setInterval(() => void this.watchHost(), WATCHDOG_MS);
+        this.watchdogTimer.unref();
         // sandbox.keepAwake, and the life record that tells the next launch how this run ended (host/life).
         this.awake = this.life.read()?.keepAwake ? KeepAwake.start(process.pid, storageRoot) : null;
     }
+    /** One watchdog sample: this PC's memory and CPU; asks the sandbox to slow down while the PC is low. Never throws. */
+    async watchHost() {
+        if (this.watchdogBusy)
+            return;
+        this.watchdogBusy = true;
+        try {
+            const settings = readLoadSettings(this.storageRoot, this.dataPath);
+            const memory = await readHostMemoryAsync(this.storageRoot);
+            const cpus = os.cpus();
+            const cpuPercent = cpuPercentBetween(this.lastCpu, cpus);
+            this.lastCpu = cpus;
+            const nowMs = Date.now();
+            const step = watchdogStep(this.watchdog, {
+                memory,
+                cpuPercent,
+                intervalSeconds: WATCHDOG_MS / 1000,
+                nowMs,
+                reserveHostMb: settings.reserveHostMb,
+                profile: settings.profile,
+            });
+            this.watchdog = step.state;
+            if (memory && (step.state.low || nowMs - this.lastHostLog >= HOST_LOG_EVERY_MS)) {
+                this.lastHostLog = nowMs;
+                appendHostMemory(path.join(this.storageRoot, 'logs', 'host-memory-' + path.basename(this.dataPath) + '.log'), memory, cpuPercent);
+            }
+            if (step.changed)
+                this.note(step.state.low
+                    ? 'this PC is low (' + step.reason + '): asking the sandbox to slow its builds down'
+                    : 'this PC has recovered: no longer asking the sandbox to slow down');
+            if (step.send)
+                new SandboxChannel(this.dataPath).pressure(step.reason, REQUEST_SECONDS);
+        }
+        catch (e) {
+            this.note('host watchdog: ' + errMsg(e));
+        }
+        finally {
+            this.watchdogBusy = false;
+        }
+    }
     /** The repo guard, then history and (at the end) claude-mem back to this PC. */
     sync(final) {
         try {
@@ -235,6 +322,8 @@ export class Watcher {
     /** Stops what start() started, syncs the filtered workspaces a last time and records the data folder's size. */
     stop() {
         this.awake?.stop();
+        if (this.watchdogTimer)
+            clearInterval(this.watchdogTimer);
         this.stops.forEach((stop) => stop());
         if (this.auditTimer)
             clearInterval(this.auditTimer);