windows-development-sandbox 1.10.0 → 1.11.3

package/dist/host/github/deliver.d.ts

@@ -0,0 +1,13 @@
+import type { BootWant } from '../../core/local-config/index.js';
+import type { Config } from '../../core/types.js';
+import { GithubToken } from './token.js';
+/** github.shareToken is on and git access is "full" for every project this sandbox boots with. */
+export declare function githubTokenAllowed(config: Config, others?: readonly BootWant[]): boolean;
+export interface GithubDelivery {
+    /** The token for the one-shot secrets file, when it is handed over. */
+    readonly token?: string;
+    /** What to tell you about it (never the token). */
+    readonly notes: readonly string[];
+}
+/** What this launch hands over. Never throws: a token that cannot be read is a note, and the launch goes on. */
+export declare function prepareGithubToken(config: Config, storageRoot: string, store?: GithubToken, others?: readonly BootWant[]): GithubDelivery;

package/dist/host/github/deliver.js

@@ -0,0 +1,51 @@
+import { GithubToken } from './token.js';
+/** The first project (the launch's own, then the others at boot) whose git access is not "full", or null. */
+function stricterProject(config, others) {
+    if (config.provisioning.git.access !== 'full')
+        return { name: '', access: config.provisioning.git.access };
+    const other = others.find((o) => o.config.provisioning.git.access !== 'full');
+    return other ? { name: other.name, access: other.config.provisioning.git.access } : null;
+}
+/** github.shareToken is on and git access is "full" for every project this sandbox boots with. */
+export function githubTokenAllowed(config, others = []) {
+    return config.github.shareToken && stricterProject(config, others) === null;
+}
+/** What this launch hands over. Never throws: a token that cannot be read is a note, and the launch goes on. */
+export function prepareGithubToken(config, storageRoot, store, others = []) {
+    if (!config.github.shareToken)
+        return { notes: [] };
+    const stricter = stricterProject(config, others);
+    if (stricter)
+        return {
+            notes: [
+                'github.shareToken is on, but git access is "' +
+                    stricter.access +
+                    '"' +
+                    (stricter.name ? ' for ' + stricter.name + ' (also in this sandbox)' : ' in this sandbox') +
+                    ', so your GitHub token was not handed over (it needs provisioning.git.access "full").',
+            ],
+        };
+    const tokens = store ?? new GithubToken(storageRoot);
+    let token;
+    try {
+        token = tokens.read();
+    }
+    catch {
+        // The reason may come from DPAPI or a damaged file; a fixed text is enough (and can never hold the token).
+        return {
+            notes: [
+                'Your saved GitHub token could not be read (only the Windows user that saved it can), so it was not handed over. Save it again: sandbox github login',
+            ],
+        };
+    }
+    if (!token)
+        return {
+            notes: ['github.shareToken is on, but no GitHub token is saved. Save one: sandbox github login'],
+        };
+    return {
+        token,
+        notes: [
+            'Your GitHub token is handed to this sandbox (github.shareToken): the agent can read it and use it for whatever it allows.',
+        ],
+    };
+}

package/dist/host/github/index.d.ts

@@ -0,0 +1,2 @@
+export { GithubToken, checkGithubToken, type TokenState } from './token.js';
+export { githubTokenAllowed, prepareGithubToken, type GithubDelivery } from './deliver.js';

package/dist/host/github/index.js

@@ -0,0 +1,3 @@
+// The GitHub token for sandboxes: its encrypted store and whether a launch hands it over.
+export { GithubToken, checkGithubToken } from './token.js';
+export { githubTokenAllowed, prepareGithubToken } from './deliver.js';

package/dist/host/github/token.d.ts

@@ -0,0 +1,21 @@
+import { type GithubTokenKind } from '../../shared/github/index.js';
+import { SecretStore } from '../secrets/index.js';
+/** What the status may say about the token: never its value. */
+export type TokenState = 'none' | 'saved' | 'unreadable';
+/** The token's kind, or a refusal that says what to do (the message never holds what was typed). */
+export declare function checkGithubToken(token: string): GithubTokenKind;
+export declare class GithubToken {
+    private readonly storageRoot;
+    private readonly secrets;
+    constructor(storageRoot: string, secrets?: SecretStore);
+    private file;
+    /** Checks, encrypts and saves the token (replacing an earlier one). Returns its kind. */
+    save(token: string): GithubTokenKind;
+    /** The token, decrypted. Only the launch calls this; throws when this Windows user cannot open it. */
+    read(): string | null;
+    /** Whether a token is saved and can be decrypted by this Windows user (the value is never returned). */
+    state(): TokenState;
+    savedAt(): string | null;
+    kind(): GithubTokenKind | null;
+    remove(): boolean;
+}

package/dist/host/github/token.js

@@ -0,0 +1,74 @@
+// The GitHub token you saved for sandboxes (github.shareToken), kept encrypted with Windows DPAPI in host-only storage
+// (<storage>\github\token.json). It is read only when a sandbox starts, to hand to the sandbox in a one-shot file, and
+// is never printed, logged or returned to a surface: they only learn its state, kind and when it was saved.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+import { GITHUB_TOKEN_KINDS, GithubTokenSchema, githubTokenKind, githubTokenProblem, } from '../../shared/github/index.js';
+import { fail } from '../../core/util/index.js';
+import { SecretStore } from '../secrets/index.js';
+const SavedSchema = z.object({
+    savedAt: z.string().max(64),
+    kind: z.enum(GITHUB_TOKEN_KINDS),
+    sealed: z.string().max(10000),
+});
+/** The token's kind, or a refusal that says what to do (the message never holds what was typed). */
+export function checkGithubToken(token) {
+    const problem = githubTokenProblem(token);
+    if (problem)
+        fail(problem.message, problem.fix);
+    return githubTokenKind(token) ?? fail('That is not a GitHub personal access token.', 'Run: sandbox github login');
+}
+export class GithubToken {
+    storageRoot;
+    secrets;
+    constructor(storageRoot, secrets = SecretStore.standard()) {
+        this.storageRoot = storageRoot;
+        this.secrets = secrets;
+    }
+    file() {
+        return new JsonFile(SavedSchema, path.join(this.storageRoot, 'github', 'token.json'));
+    }
+    /** Checks, encrypts and saves the token (replacing an earlier one). Returns its kind. */
+    save(token) {
+        const kind = checkGithubToken(token);
+        this.file().write({ savedAt: new Date().toISOString(), kind, sealed: this.secrets.sealJson({ token }) });
+        return kind;
+    }
+    /** The token, decrypted. Only the launch calls this; throws when this Windows user cannot open it. */
+    read() {
+        const saved = this.file().read();
+        if (!saved)
+            return null;
+        const value = this.secrets.openJson(saved.sealed);
+        const token = GithubTokenSchema.safeParse(value?.token);
+        if (!token.success)
+            fail('The saved GitHub token is damaged.', 'Save it again with: sandbox github login');
+        return token.data;
+    }
+    /** Whether a token is saved and can be decrypted by this Windows user (the value is never returned). */
+    state() {
+        if (!this.file().read())
+            return 'none';
+        try {
+            return this.read() ? 'saved' : 'none';
+        }
+        catch {
+            return 'unreadable';
+        }
+    }
+    savedAt() {
+        return this.file().read()?.savedAt ?? null;
+    }
+    kind() {
+        return this.file().read()?.kind ?? null;
+    }
+    remove() {
+        const file = this.file().file;
+        if (!fs.existsSync(file))
+            return false;
+        fs.rmSync(file, { force: true });
+        return true;
+    }
+}

package/dist/host/launch/generate.js

@@ -9,6 +9,7 @@ import { dirExists, ensureDir, fail, writeJson } from '../../core/util/index.js'
 import { engineFor } from '../engines/index.js';
 import { capturePersonalization, stageClaudeProfile } from '../profile/index.js';
 import { clearSecrets, writeSecrets } from '../secrets/index.js';
+import { githubTokenAllowed } from '../github/index.js';
 import { folderAttachment } from '../storage/providers/index.js';
 import { assertTestWritable } from '../test-guard.js';
 import { writeLoadSettings } from '../life/watchdog.js';
@@ -20,7 +21,7 @@ import { guestSession, logonEnv } from './session-file.js';
 import { copyRuntime, stageGitIdentity, stageHooks } from './stage.js';
 import { decideProjectToolchains } from './toolchains.js';
 import { buildLaunchPlan } from './launch-plan.js';
-import { decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+import { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentNote, resolveMemoryMb } from './wsb-file.js';
 const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
 /** Moves the staged copy of this PC's Claude login out of the launch folder; its text goes in the one-shot file. */
 function takeStagedCredentials(launchPath) {
@@ -59,7 +60,9 @@ opened) {
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
     const commitAvailableMb = o.commitAvailableMb ?? null;
-    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    const askedMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    // Never more than this PC can keep in RAM for it, whatever was asked.
+    const memoryMb = cappedMemoryMb(askedMb, config.sandbox, Math.floor(os.totalmem() / 1048576));
     const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
     // Whatever must stay secret goes in a one-shot file in the data folder, never into the launch folder (the sandbox
@@ -104,6 +107,8 @@ opened) {
         ...(claudeCredentials ? { claudeCredentials } : {}),
         ...(o.vpn?.credentials ? { vpn: o.vpn.credentials } : {}),
         ...(o.vpn?.wireguardConfig ? { wireguardConfig: o.vpn.wireguardConfig } : {}),
+        // Checked again on the configs the sandbox boots with: never when a project in it has git access below "full".
+        ...(o.githubToken && githubTokenAllowed(config, others) ? { githubToken: o.githubToken } : {}),
     });
     fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
@@ -127,9 +132,10 @@ opened) {
         launchId,
         sessionPath,
         memoryMb,
-        memoryNote: config.sandbox.memoryMb === 'auto'
-            ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
-            : null,
+        memoryNote: residentNote(askedMb, memoryMb) ??
+            (config.sandbox.memoryMb === 'auto'
+                ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
+                : null),
         bootConfig: config,
         widened: wide.widened,
         mappings,

package/dist/host/launch/index.d.ts

@@ -1,7 +1,7 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from './wsb-file.js';
 export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
 export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot, type BootProjects } from './boot-projects.js';

package/dist/host/launch/index.js

@@ -1,7 +1,7 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { cappedMemoryMb, decideMemory, GUEST, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from './wsb-file.js';
 export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
 export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot } from './boot-projects.js';

package/dist/host/launch/session-file.js

@@ -5,7 +5,6 @@ import { resolveToolchains } from '../../core/detect/index.js';
 import { hubName, PROJECTS_GUEST, substDrives } from '../../shared/paths/index.js';
 import { hostClaudeDir } from '../profile/index.js';
 import { databaseCatalog } from './database-plan.js';
-import { agentMemoryLimitMb } from './wsb-file.js';
 import { effectiveCpuLimit } from '../../shared/memory/index.js';
 import { loadProfileOf } from './risk-notes.js';
 /** What was found on this PC to copy instead of download. */
@@ -65,7 +64,7 @@ export function guestSession(o, parts) {
         cpuLimitPercent: effectiveCpuLimit(config.sandbox.cpuLimit, loadProfileOf(config)),
         loadProfile: loadProfileOf(config),
         pageFileMb: config.sandbox.pageFileMb,
-        agentMemoryLimitMb: agentMemoryLimitMb(parts.memoryMb, config.sandbox.agentMemoryHeadroomMb),
+        agentBackstop: config.sandbox.agentMemoryHeadroomMb,
         pressureResponse: config.sandbox.pressureResponse,
         apps: config.apps,
         auditProcesses: config.audit.enabled && config.audit.processes,

package/dist/host/launch/wsb-file.d.ts

@@ -6,7 +6,7 @@ export declare const GUEST: {
     readonly mirror: "C:\\Mirror";
 };
 type SandboxSettings = Config['sandbox'];
-export type MemoryLimit = 'free' | 'share' | 'max' | 'commit';
+export type MemoryLimit = 'free' | 'share' | 'max' | 'commit' | 'resident';
 export interface MemoryDecision {
     readonly mb: number;
     /** What set the size. */
@@ -17,18 +17,22 @@ export interface MemoryDecision {
     readonly freeMb: number;
     readonly commitAvailableMb: number | null;
 }
+/**
+ * The most memory this PC can keep in RAM for the sandbox (pure): its RAM minus max(reserveHostMb, 25 %), and 2 GB
+ * more with vGPU. Windows Sandbox's memory is this PC's memory taken as needed; beyond what the PC can keep resident it
+ * is paged to this PC's disk while the sandbox pages to its own, and that is what can freeze the whole PC.
+ */
+export declare function residentCapMb(sandbox: SandboxSettings, totalMb: number): number;
+/** A fixed memoryMb above what this PC can keep resident is lowered to that (never below 4 GB). */
+export declare function cappedMemoryMb(memoryMb: number, sandbox: SandboxSettings, totalMb: number): number;
+/** The launch note when a fixed memoryMb was lowered. */
+export declare function residentNote(asked: number, given: number): string | null;
 /**
  * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
  * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
  * never more than that minus the reserve either.
  */
 export declare function decideMemory(sandbox: SandboxSettings, freeMb: number, totalMb: number, commitAvailableMb: number | null): MemoryDecision;
-/**
- * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
- * ("auto" =
- * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
- */
-export declare function agentMemoryLimitMb(memoryMb: number, headroom: SandboxSettings['agentMemoryHeadroomMb']): number | null;
 /** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
 export declare function memoryNote(decision: MemoryDecision): string | null;
 /** "auto": see decideMemory. commitAvailableMb: from HostTools memory-status (omitted = not checked). */

package/dist/host/launch/wsb-file.js

@@ -11,6 +11,34 @@ export const GUEST = {
 const MB = 1048576;
 const MIN_AUTO_MEMORY_MB = 4096;
 const roundDown = (mb) => Math.floor(mb / 1024) * 1024;
+/** GPU-PV (vGPU) needs room of its own on this PC: memory the graphics driver pins for the sandbox. */
+const VGPU_RESERVE_MB = 2048;
+/**
+ * The most memory this PC can keep in RAM for the sandbox (pure): its RAM minus max(reserveHostMb, 25 %), and 2 GB
+ * more with vGPU. Windows Sandbox's memory is this PC's memory taken as needed; beyond what the PC can keep resident it
+ * is paged to this PC's disk while the sandbox pages to its own, and that is what can freeze the whole PC.
+ */
+export function residentCapMb(sandbox, totalMb) {
+    const keep = Math.max(sandbox.reserveHostMb, Math.floor(totalMb / 4)) + (sandbox.vGpu ? VGPU_RESERVE_MB : 0);
+    return roundDown(totalMb - keep);
+}
+/** A fixed memoryMb above what this PC can keep resident is lowered to that (never below 4 GB). */
+export function cappedMemoryMb(memoryMb, sandbox, totalMb) {
+    const cap = residentCapMb(sandbox, totalMb);
+    return cap >= MIN_AUTO_MEMORY_MB && memoryMb > cap ? cap : memoryMb;
+}
+/** The launch note when a fixed memoryMb was lowered. */
+export function residentNote(asked, given) {
+    if (given >= asked)
+        return null;
+    return ('sandbox.memoryMb asks for ' +
+        asked +
+        ' MB; this PC can keep ' +
+        given +
+        ' MB in RAM for the sandbox (its RAM minus what it needs itself), so the sandbox gets ' +
+        given +
+        " MB. More would be paged to this PC's disk, which can freeze the whole PC.");
+}
 /**
  * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
  * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
@@ -25,22 +53,12 @@ export function decideMemory(sandbox, freeMb, totalMb, commitAvailableMb) {
         ['share', shareMb],
         ['free', byFree],
         ['commit', byCommit],
+        ['resident', residentCapMb(sandbox, totalMb)],
     ];
     const lowest = candidates.reduce((a, b) => (b[1] < a[1] ? b : a));
-    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree));
+    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree, residentCapMb(sandbox, totalMb)));
     return { mb: roundDown(lowest[1]), limitedBy: lowest[0], withoutCommitMb: withoutCommit, freeMb, commitAvailableMb };
 }
-/**
- * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
- * ("auto" =
- * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
- */
-export function agentMemoryLimitMb(memoryMb, headroom) {
-    if (headroom === 'none')
-        return null;
-    const keep = headroom === 'auto' ? Math.max(2048, Math.floor(memoryMb / 10)) : headroom;
-    return Math.max(Math.floor(memoryMb / 2), memoryMb - keep);
-}
 /** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
 export function memoryNote(decision) {
     if (decision.limitedBy !== 'commit' || decision.withoutCommitMb - decision.mb < 2048)

package/dist/host/life/watchdog.d.ts

@@ -3,6 +3,8 @@ import { type HostThresholds, type LoadProfile } from '../../shared/memory/index
 import { type HostMemory } from './host-memory.js';
 export interface WatchdogState {
     readonly low: boolean;
+    /** Nearly out of memory: the request asks for the governor's last step. */
+    readonly severe: boolean;
     readonly calm: number;
     /** Seconds the CPU has been above the limit. */
     readonly cpuHighSeconds: number;
@@ -31,6 +33,8 @@ export interface WatchdogStep {
     readonly send: boolean;
     /** Why the PC is low (plain words), empty when it is not. */
     readonly reason: string;
+    /** Nearly out of memory: builds go to the governor's last step. */
+    readonly severe: boolean;
     /** The state changed (the log says so). */
     readonly changed: boolean;
 }
@@ -40,6 +44,11 @@ export interface WatchdogStep {
  * `scale` widens the limits (1.25 = the level it must climb back above).
  */
 export declare function lowReason(memory: HostMemory, reserveHostMb: number, t: HostThresholds, scale: number): string;
+/**
+ * Nearly out of memory on this PC: under 1.5 GB of RAM free, or commit within max(2 GB, 4 %) of its limit. Then the
+ * sandbox's builds go to the governor's last step at once (one compiler at a time, 15 % CPU) until it passes.
+ */
+export declare function severeHost(memory: HostMemory): boolean;
 /** One watchdog step. Hysteresis: low starts at the limits and ends above 1.25 times them for calmSamples samples. */
 export declare function watchdogStep(prev: WatchdogState, input: WatchdogInput): WatchdogStep;
 /** Total CPU use between two os.cpus() readings (percent). */

package/dist/host/life/watchdog.js

@@ -5,6 +5,7 @@ import { HOST_THRESHOLDS } from '../../shared/memory/index.js';
 import { hostMemoryLine } from './host-memory.js';
 export const WATCHDOG_START = {
     low: false,
+    severe: false,
     calm: 0,
     cpuHighSeconds: 0,
     diskHighSeconds: 0,
@@ -27,6 +28,17 @@ export function lowReason(memory, reserveHostMb, t, scale) {
         return 'only ' + memory.commitAvailableMb + ' MB of memory (RAM plus paging file) is left on this PC';
     return '';
 }
+/**
+ * Nearly out of memory on this PC: under 1.5 GB of RAM free, or commit within max(2 GB, 4 %) of its limit. Then the
+ * sandbox's builds go to the governor's last step at once (one compiler at a time, 15 % CPU) until it passes.
+ */
+export function severeHost(memory) {
+    return (memory.availableMb < SEVERE_AVAILABLE_MB ||
+        memory.commitAvailableMb < Math.max(SEVERE_COMMIT_MB, (memory.commitLimitMb * SEVERE_COMMIT_PERCENT) / 100));
+}
+const SEVERE_AVAILABLE_MB = 1536;
+const SEVERE_COMMIT_MB = 2048;
+const SEVERE_COMMIT_PERCENT = 4;
 /** One watchdog step. Hysteresis: low starts at the limits and ends above 1.25 times them for calmSamples samples. */
 export function watchdogStep(prev, input) {
     const t = HOST_THRESHOLDS[input.profile];
@@ -54,10 +66,13 @@ export function watchdogStep(prev, input) {
             calm = 0;
         }
     }
-    const send = low && input.nowMs - prev.lastSentAt >= RESEND_MS;
+    const severe = low && input.memory !== null && severeHost(input.memory);
+    // Getting severe is sent at once; otherwise the request is repeated every RESEND_MS while the PC stays low.
+    const send = low && (input.nowMs - prev.lastSentAt >= RESEND_MS || (severe && !prev.severe));
     return {
         state: {
             low,
+            severe,
             calm,
             cpuHighSeconds: cpuHigh,
             diskHighSeconds: diskHigh,
@@ -65,6 +80,7 @@ export function watchdogStep(prev, input) {
         },
         send,
         reason: reason || (low ? 'this PC is still low' : ''),
+        severe,
         changed: low !== prev.low,
     };
 }

package/dist/host/sandbox/tasklist.d.ts

@@ -7,6 +7,12 @@ export interface TasklistRunners {
 export declare function useTasklistRunners(replacement?: TasklistRunners): void;
 /** While set, a synchronous read returns this copy (undefined: none yet, run tasklist). Null removes it. */
 export declare function useTasklistCache(read: (() => string | undefined) | null): void;
+/**
+ * For a long-running server (the web UI): questions within `freshMs` of the last run share its list; an older one
+ * (up to `staleMs`) is still answered from it while a new list is fetched in the background, so no request waits for
+ * tasklist. Nothing runs while nobody asks. Returns the function that stops it.
+ */
+export declare function keepTasklistFresh(freshMs?: number, staleMs?: number): () => void;
 /** The process list now: the cached copy when the menu keeps one, else a run of tasklist the caller waits for. */
 export declare function readTasklist(): string;
 /** The process list from a run of tasklist that does not block the program (the menu's background refresh). */

package/dist/host/sandbox/tasklist.js

@@ -37,6 +37,43 @@ export function useTasklistRunners(replacement = REAL_RUNNERS) {
 export function useTasklistCache(read) {
     cache = read;
 }
+/**
+ * For a long-running server (the web UI): questions within `freshMs` of the last run share its list; an older one
+ * (up to `staleMs`) is still answered from it while a new list is fetched in the background, so no request waits for
+ * tasklist. Nothing runs while nobody asks. Returns the function that stops it.
+ */
+export function keepTasklistFresh(freshMs = 2000, staleMs = 15000) {
+    let copy;
+    let at = 0;
+    let fetching = false;
+    const refresh = () => {
+        if (fetching)
+            return;
+        fetching = true;
+        void runners
+            .async()
+            .then((list) => {
+            copy = list;
+            at = Date.now();
+        })
+            .finally(() => {
+            fetching = false;
+        });
+    };
+    useTasklistCache(() => {
+        const age = Date.now() - at;
+        if (copy !== undefined && age < freshMs)
+            return copy;
+        if (copy !== undefined && age < staleMs) {
+            refresh();
+            return copy;
+        }
+        copy = runners.sync();
+        at = Date.now();
+        return copy;
+    });
+    return () => useTasklistCache(null);
+}
 /** The process list now: the cached copy when the menu keeps one, else a run of tasklist the caller waits for. */
 export function readTasklist() {
     return cache?.() ?? runners.sync();

package/dist/host/secrets/launch-secrets.d.ts

@@ -4,7 +4,8 @@ import type { GuestRequest } from '../../core/types.js';
 export declare function writeSecrets(dataPath: string, id: string, secrets: SecretsFile): string | null;
 /**
  * Removes whatever one-shot files are left (the sandbox did not start, or did not get to read them) and, from older
- * versions, a login copy in a launch folder. Called before a launch writes new ones and when the sandbox stops.
+ * versions, a login copy in a launch folder. Called before a launch writes new ones, and when a launch fails before
+ * its sandbox starts.
  */
 export declare function clearSecrets(storageRoot: string, dataPath: string): number;
 /**

package/dist/host/secrets/launch-secrets.js

@@ -12,7 +12,8 @@ export function writeSecrets(dataPath, id, secrets) {
         !Object.keys(secrets.projectHarnessEnvironment ?? {}).length &&
         !secrets.claudeCredentials &&
         !secrets.vpn &&
-        !secrets.wireguardConfig;
+        !secrets.wireguardConfig &&
+        !secrets.githubToken;
     if (empty)
         return null;
     const run = new RunDir(dataPath);
@@ -23,7 +24,8 @@ export function writeSecrets(dataPath, id, secrets) {
 }
 /**
  * Removes whatever one-shot files are left (the sandbox did not start, or did not get to read them) and, from older
- * versions, a login copy in a launch folder. Called before a launch writes new ones and when the sandbox stops.
+ * versions, a login copy in a launch folder. Called before a launch writes new ones, and when a launch fails before
+ * its sandbox starts.
  */
 export function clearSecrets(storageRoot, dataPath) {
     let removed = 0;

package/dist/host/vpn/status.js

@@ -17,8 +17,16 @@ export function vpnLine(status, hostIp = null) {
     if (!status)
         return { level: 'warn', text: 'The sandbox has not reported on the VPN.' };
     const message = safeText(status.message).slice(0, 300);
+    const leaky = status.killSwitch && status.killSwitchHeld === false;
     if (status.state === 'up') {
         const same = hostIp !== null && status.publicIp === hostIp;
+        if (!same && leaky)
+            return {
+                level: 'warn',
+                text: 'VPN up' +
+                    (status.publicIp ? ', the sandbox appears as ' + safeText(status.publicIp) : '') +
+                    ', but the kill switch did not hold: if the tunnel drops, traffic goes out through your normal connection.',
+            };
         return same
             ? {
                 level: 'bad',
@@ -40,9 +48,11 @@ export function vpnLine(status, hostIp = null) {
             level: 'bad',
             text: 'VPN failed: ' +
                 message +
-                (status.killSwitch
-                    ? ' The kill switch is on, so the sandbox has no internet.'
-                    : ' The kill switch is off, so the sandbox uses your normal connection.'),
+                (leaky
+                    ? ' The kill switch did not hold, so the sandbox is ONLINE through your normal connection, without the VPN.'
+                    : status.killSwitch
+                        ? ' The kill switch is on, so the sandbox has no internet.'
+                        : ' The kill switch is off, so the sandbox uses your normal connection.'),
         };
     return { level: 'warn', text: 'VPN ' + status.state + (message ? ': ' + message : '') };
 }

package/dist/host/web/backend.d.ts

@@ -1,5 +1,5 @@
 import type { Endpoint } from '../../shared/pty/index.js';
-import type { NewSessionRequest, WebInfo, WebSession } from '../../shared/web/index.js';
+import type { WebInfo, WebSession } from '../../shared/web/index.js';
 export interface WebBackend {
     info(): Promise<WebInfo>;
     /** Sessions as the browser may see them: never an attach token or address. */
@@ -9,6 +9,4 @@ export interface WebBackend {
      * running session, the sandbox is not shared with this user, or it has no address on this PC's sandbox network.
      */
     endpoint(sessionId: string): Endpoint | null;
-    /** Starts an agent in a project of the running sandbox and waits until it runs. */
-    create(request: NewSessionRequest): Promise<WebSession>;
 }

package/dist/host/web/index.d.ts

@@ -4,7 +4,8 @@ export { openBrowser, openIssuePage } from './browser.js';
 export { TerminalBridge } from './bridge.js';
 export { WebControl, type WebStatus } from './control.js';
 export { WebRunner } from './runner.js';
+export { LiveHub, type LiveListener } from './live.js';
 export { RpcSession } from './rpc.js';
-export { WebServer, CONTENT_SECURITY_POLICY, RPC_PATH, type WebServerOptions } from './server.js';
+export { WebServer, CONTENT_SECURITY_POLICY, IDLE_EXIT_MS, RPC_PATH, type WebServerOptions } from './server.js';
 export { StaticFiles } from './static-files.js';
 export { WebStore, WebStateSchema, type WebState } from './state.js';

package/dist/host/web/index.js

@@ -3,7 +3,8 @@ export { openBrowser, openIssuePage } from './browser.js';
 export { TerminalBridge } from './bridge.js';
 export { WebControl } from './control.js';
 export { WebRunner } from './runner.js';
+export { LiveHub } from './live.js';
 export { RpcSession } from './rpc.js';
-export { WebServer, CONTENT_SECURITY_POLICY, RPC_PATH } from './server.js';
+export { WebServer, CONTENT_SECURITY_POLICY, IDLE_EXIT_MS, RPC_PATH } from './server.js';
 export { StaticFiles } from './static-files.js';
 export { WebStore, WebStateSchema } from './state.js';

package/dist/host/web/live.d.ts

@@ -0,0 +1,23 @@
+import type { RpcHost } from '../../app/kernel/index.js';
+export type LiveListener = (event: {
+    readonly output: unknown;
+} | {
+    readonly error: unknown;
+}) => void;
+export declare class LiveHub {
+    private readonly host;
+    private readonly polls;
+    constructor(host: RpcHost);
+    /** How many polls run (for tests and the idle check). */
+    get size(): number;
+    /**
+     * Starts listening; the listener gets the current answer (at once when one is known) and every change. Returns the
+     * function that stops listening.
+     */
+    watch(query: string, input: unknown, listener: LiveListener): () => void;
+    /** Something changed (an operation ran): every query reads again now, at its own pace. */
+    poke(): void;
+    private schedule;
+    private isLive;
+    private read;
+}