windows-development-sandbox 1.23.2 → 1.25.0

package/dist/runtime/netproxy.js

@@ -25697,7 +25697,7 @@ var ToolchainsSchema = external_exports.strictObject({
   }),
   unreal: external_exports.strictObject({
     enabled: enabled(
-      "Unreal Engine development: Visual Studio Community 2022 with the C++ game workload (MSVC, a Windows 11 SDK, .NET Framework targeting packs, Unreal integration and the Epic Games Launcher) and the DirectX End-User Runtime. A real installer: it runs every boot (~10 GB on the sandbox disk). The engine itself comes from the Epic Games Launcher or its source.",
+      "Unreal Engine development: Visual Studio Community 2022 with the C++ game workload (MSVC, a Windows 11 SDK, .NET Framework targeting packs, Unreal integration and the Epic Games Launcher) and the DirectX End-User Runtime. Visual Studio is installed once and kept on the data disk (~6.5 GB); later boots put it back in seconds. The engine itself comes from the Epic Games Launcher or its source.",
       "a .uproject or .uplugin"
     ),
     acceptLicense: external_exports.boolean().describe(
@@ -25706,11 +25706,8 @@ var ToolchainsSchema = external_exports.strictObject({
     components: StringsSchema.describe(
       'More Visual Studio workload or component IDs to add, e.g. ["Microsoft.VisualStudio.Component.VC.Llvm.Clang"].'
     ),
-    keepInstallFiles: external_exports.boolean().describe(
-      "Keep an offline copy of the Visual Studio install files in tools\\visualstudio (~10 GB, made once), so later boots install without downloading them again. Skipped while that disk has too little room."
-    ),
-    visualStudio: external_exports.enum(["full", "autosdk"]).describe(
-      `"full": install Visual Studio Community (the engine finds it through the Setup API; ~10 GB, redone every boot). "autosdk" (experimental): skip Visual Studio and build an Unreal AutoSDK tree from the portable MSVC in tools\\unreal\\autosdk (kept between sandboxes); UnrealBuildTool finds MSVC through AutoSDK, but the editor's Visual Studio integration is not available. Needs toolchains.msvc (turned on for you).`
+    visualStudio: external_exports.enum(["full", "buildtools"]).describe(
+      '"full": Visual Studio Community with the C++ game workload (the IDE, its debugger and Unreal integration). "buildtools": only the Visual Studio Build Tools (MSVC, the Windows SDK and the .NET Framework parts UnrealBuildTool needs; no IDE). Either is installed once and kept on the data disk (tools\\visualstudio\\persist, ~6.5 GB for Community); later boots put it back in seconds.'
     ),
     persistEngines: external_exports.boolean().describe(
       "Engines the Epic Games Launcher installs go to tools\\unreal\\engines (kept between sandboxes, 40-60 GB each) and are registered with the launcher again every boot. Off: they go on the sandbox disk and are lost when it closes. Engines installed on this PC can be mapped instead (pcInstalls.unrealEngines)."

package/dist/runtime/tool.js

@@ -26070,7 +26070,7 @@ var ToolchainsSchema = external_exports.strictObject({
   }),
   unreal: external_exports.strictObject({
     enabled: enabled(
-      "Unreal Engine development: Visual Studio Community 2022 with the C++ game workload (MSVC, a Windows 11 SDK, .NET Framework targeting packs, Unreal integration and the Epic Games Launcher) and the DirectX End-User Runtime. A real installer: it runs every boot (~10 GB on the sandbox disk). The engine itself comes from the Epic Games Launcher or its source.",
+      "Unreal Engine development: Visual Studio Community 2022 with the C++ game workload (MSVC, a Windows 11 SDK, .NET Framework targeting packs, Unreal integration and the Epic Games Launcher) and the DirectX End-User Runtime. Visual Studio is installed once and kept on the data disk (~6.5 GB); later boots put it back in seconds. The engine itself comes from the Epic Games Launcher or its source.",
       "a .uproject or .uplugin"
     ),
     acceptLicense: external_exports.boolean().describe(
@@ -26079,11 +26079,8 @@ var ToolchainsSchema = external_exports.strictObject({
     components: StringsSchema.describe(
       'More Visual Studio workload or component IDs to add, e.g. ["Microsoft.VisualStudio.Component.VC.Llvm.Clang"].'
     ),
-    keepInstallFiles: external_exports.boolean().describe(
-      "Keep an offline copy of the Visual Studio install files in tools\\visualstudio (~10 GB, made once), so later boots install without downloading them again. Skipped while that disk has too little room."
-    ),
-    visualStudio: external_exports.enum(["full", "autosdk"]).describe(
-      `"full": install Visual Studio Community (the engine finds it through the Setup API; ~10 GB, redone every boot). "autosdk" (experimental): skip Visual Studio and build an Unreal AutoSDK tree from the portable MSVC in tools\\unreal\\autosdk (kept between sandboxes); UnrealBuildTool finds MSVC through AutoSDK, but the editor's Visual Studio integration is not available. Needs toolchains.msvc (turned on for you).`
+    visualStudio: external_exports.enum(["full", "buildtools"]).describe(
+      '"full": Visual Studio Community with the C++ game workload (the IDE, its debugger and Unreal integration). "buildtools": only the Visual Studio Build Tools (MSVC, the Windows SDK and the .NET Framework parts UnrealBuildTool needs; no IDE). Either is installed once and kept on the data disk (tools\\visualstudio\\persist, ~6.5 GB for Community); later boots put it back in seconds.'
     ),
     persistEngines: external_exports.boolean().describe(
       "Engines the Epic Games Launcher installs go to tools\\unreal\\engines (kept between sandboxes, 40-60 GB each) and are registered with the launcher again every boot. Off: they go on the sandbox disk and are lost when it closes. Engines installed on this PC can be mapped instead (pcInstalls.unrealEngines)."
@@ -28127,19 +28124,33 @@ var run = new RunDir(dataDir);
 
 // src/guest/runtime/process.ts
 import { spawn as spawn2, spawnSync } from "node:child_process";
+var outputSink = null;
+var captureOutput = () => outputSink?.capturing() ?? false;
+function logOutput(text) {
+  for (const line of text.split(/\r?\n/)) if (line.trim()) outputSink?.line(line.trimEnd());
+}
+var CAPTURE_BYTES = 64 * 1024 * 1024;
+function scriptErrors(errors) {
+  if (!errors) return;
+  if (captureOutput()) logOutput(errors);
+  else process.stderr.write(errors + "\n");
+}
 function execOutput(file2, args2, options = {}) {
   const result = spawnSync(file2, args2, { encoding: "utf8", windowsHide: true, ...options });
   return result.status === 0 ? String(result.stdout ?? "").trim() : "";
 }
 function runScript(name2, args2 = []) {
+  const capture = captureOutput();
   const result = spawnSync(SYSTEM.powershell(), scriptArgs(name2, args2), {
-    stdio: ["inherit", "inherit", "pipe"],
+    stdio: ["inherit", capture ? "pipe" : "inherit", "pipe"],
     encoding: "utf8",
-    windowsHide: true
+    windowsHide: true,
+    ...capture ? { maxBuffer: CAPTURE_BYTES } : {}
   });
+  if (capture) logOutput(String(result.stdout ?? ""));
   if (result.error) throw result.error;
   const errors = String(result.stderr ?? "").trim();
-  if (errors) process.stderr.write(errors + "\n");
+  scriptErrors(errors);
   if (result.status !== 0)
     throw new Error(name2 + " failed with exit code " + result.status + (errors ? ": " + errors.slice(0, 400) : ""));
 }
@@ -28250,36 +28261,45 @@ import path17 from "node:path";
 import fs11 from "node:fs";
 import path12 from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
+
+// src/guest/runtime/log-line.ts
+var ESCAPES = /\x1b\[[0-9;?]{0,32}[A-Za-z]/g;
+function plainText(text) {
+  return text.replace(ESCAPES, "");
+}
+function fileLines(message, at = /* @__PURE__ */ new Date(), task) {
+  const stamp = at.toISOString() + " " + (task ? "[" + task + "] " : "");
+  return plainText(message).split(/\r?\n/).filter((line) => line.trim() !== "").map((line) => stamp + line.trimEnd());
+}
+
+// src/guest/runtime/log.ts
 fs11.mkdirSync(logsDir, { recursive: true });
 var logFile = path12.join(
   logsDir,
   (process.env.AGENT_LOG_PREFIX ?? "guest") + "-" + (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-") + ".log"
 );
 var context = new AsyncLocalStorage();
-function fileLine(message, at = /* @__PURE__ */ new Date()) {
-  return at.toISOString() + " " + message;
-}
-var append = (line) => {
+var sink = null;
+var append = (message, ctx) => {
   try {
-    fs11.appendFileSync(logFile, fileLine(line) + "\n");
+    const lines = fileLines(message, /* @__PURE__ */ new Date(), ctx?.task);
+    if (lines.length) fs11.appendFileSync(logFile, lines.join("\n") + "\n");
   } catch {
   }
 };
-var tagged = (message, ctx) => {
-  const prefix = ctx?.prefix?.();
-  return prefix ? prefix + " | " + message : message;
-};
 function log(message) {
   const ctx = context.getStore();
-  const line = tagged(message, ctx);
-  if (!ctx?.quiet) console.log(line);
-  append(line);
+  append(message, ctx);
+  if (ctx?.quiet) return;
+  if (sink) sink.line(message, ctx?.stage);
+  else console.log(message);
 }
 function warn(message) {
   const ctx = context.getStore();
-  const line = tagged(message, ctx);
-  if (!ctx?.quiet) console.warn("\x1B[33mWARNING: " + line + "\x1B[0m");
-  append("WARNING: " + line);
+  append("WARNING: " + message, ctx);
+  if (ctx?.quiet) return;
+  if (sink) sink.warning(message);
+  else console.warn("\x1B[33mWARNING: " + message + "\x1B[0m");
 }
 
 // src/guest/toolchains/signature.ts

package/dist/runtime/view.js

@@ -6176,7 +6176,7 @@ function runTerminalClient(socket, token, options = {}) {
     socket.on("close", () => finish({ reason: "closed" }));
     socket.on("error", () => finish({ reason: "closed" }));
     const [c, r] = size();
-    stdout.write("\x1B[2J\x1B[3J\x1B[H");
+    stdout.write("\x1B[2J\x1B[H");
     socket.write(helloFrame(token, c, r));
     if (stdin.isTTY) stdin.setRawMode(true);
     vtInput = enableVtInput();
@@ -26273,7 +26273,7 @@ var ToolchainsSchema = external_exports.strictObject({
   }),
   unreal: external_exports.strictObject({
     enabled: enabled(
-      "Unreal Engine development: Visual Studio Community 2022 with the C++ game workload (MSVC, a Windows 11 SDK, .NET Framework targeting packs, Unreal integration and the Epic Games Launcher) and the DirectX End-User Runtime. A real installer: it runs every boot (~10 GB on the sandbox disk). The engine itself comes from the Epic Games Launcher or its source.",
+      "Unreal Engine development: Visual Studio Community 2022 with the C++ game workload (MSVC, a Windows 11 SDK, .NET Framework targeting packs, Unreal integration and the Epic Games Launcher) and the DirectX End-User Runtime. Visual Studio is installed once and kept on the data disk (~6.5 GB); later boots put it back in seconds. The engine itself comes from the Epic Games Launcher or its source.",
       "a .uproject or .uplugin"
     ),
     acceptLicense: external_exports.boolean().describe(
@@ -26282,11 +26282,8 @@ var ToolchainsSchema = external_exports.strictObject({
     components: StringsSchema.describe(
       'More Visual Studio workload or component IDs to add, e.g. ["Microsoft.VisualStudio.Component.VC.Llvm.Clang"].'
     ),
-    keepInstallFiles: external_exports.boolean().describe(
-      "Keep an offline copy of the Visual Studio install files in tools\\visualstudio (~10 GB, made once), so later boots install without downloading them again. Skipped while that disk has too little room."
-    ),
-    visualStudio: external_exports.enum(["full", "autosdk"]).describe(
-      `"full": install Visual Studio Community (the engine finds it through the Setup API; ~10 GB, redone every boot). "autosdk" (experimental): skip Visual Studio and build an Unreal AutoSDK tree from the portable MSVC in tools\\unreal\\autosdk (kept between sandboxes); UnrealBuildTool finds MSVC through AutoSDK, but the editor's Visual Studio integration is not available. Needs toolchains.msvc (turned on for you).`
+    visualStudio: external_exports.enum(["full", "buildtools"]).describe(
+      '"full": Visual Studio Community with the C++ game workload (the IDE, its debugger and Unreal integration). "buildtools": only the Visual Studio Build Tools (MSVC, the Windows SDK and the .NET Framework parts UnrealBuildTool needs; no IDE). Either is installed once and kept on the data disk (tools\\visualstudio\\persist, ~6.5 GB for Community); later boots put it back in seconds.'
     ),
     persistEngines: external_exports.boolean().describe(
       "Engines the Epic Games Launcher installs go to tools\\unreal\\engines (kept between sandboxes, 40-60 GB each) and are registered with the launcher again every boot. Off: they go on the sandbox disk and are lost when it closes. Engines installed on this PC can be mapped instead (pcInstalls.unrealEngines)."

package/dist/selftest/agent-paths.test.js

@@ -6,7 +6,7 @@ import { DEFAULTS, mergeConfig, validateConfig } from '../core/config/index.js';
 import { isWin } from '../core/util/index.js';
 import { SYSTEM } from '../shared/system.js';
 import { agentCommand, agentShims, bootResetPaths, isCopyableDatabaseFile, isDatabaseFile, localStateEntries, shimText, } from '../guest/agents/agent-files.js';
-import { appendMissing, expandVars, installedToolPaths, isGitUsrBin, isMsvcToolsDir, isPinnedNodeDir, msvcBeforeGitUsr, parseRegPath, pathKey, planPath, rebuildPath, splitPath, } from '../guest/setup/path-plan.js';
+import { appendMissing, expandVars, installedToolPaths, isGitUsrBin, isMsvcToolsDir, isPinnedNodeDir, msvcBeforeGitUsr, parseRegPath, pathKey, planPath, rebuildPath, sessionPath, splitPath, } from '../guest/setup/path-plan.js';
 import { withReloadEnvironment } from '../host/tools/index.js';
 import { HarnessSchema } from '../core/schema/index.js';
 export const agentPathsSuite = {
@@ -64,6 +64,22 @@ export const agentPathsSuite = {
         const exists = (f) => present.has(pathKey(f));
         t.equal(planPath({ entries: ['C:\\A\\;c:\\b', 'C:\\a', 'C:\\missing;"C:\\C\\D"', '', 'c:/B'], exists }), ['C:\\A\\', 'c:\\b', 'C:\\C\\D'], 'ordered, no duplicates (case, slash, quotes), no missing folders');
         t.equal(planPath({ entries: ['C:\\a;C:\\nvm\\v24.1.0'], exists, drop: (f) => isPinnedNodeDir(f, 'C:\\NVM') }), ['C:\\a'], 'a pinned node version is never machine-wide');
+        const agentPath = sessionPath({
+            commands: 'C:\\nvm\\bin',
+            prepend: ['C:\\AgentData\\tools\\bin', 'C:\\AgentData\\tools\\nvm', 'C:\\nvm\\nodejs'],
+            base: ['C:\\Windows\\system32', 'c:\\NVM\\bin\\'],
+            append: ['C:\\AgentData\\tools\\agents\\codex'],
+        });
+        t.equal(agentPath, [
+            'C:\\nvm\\bin',
+            'C:\\AgentData\\tools\\bin',
+            'C:\\AgentData\\tools\\nvm',
+            'C:\\nvm\\nodejs',
+            'C:\\Windows\\system32',
+            'C:\\AgentData\\tools\\agents\\codex',
+        ], "the sandbox's agent shims come first, before nvm's node folder (an npm -g codex there) and the agent's own folder");
+        t.equal(planPath({ entries: [agentPath.join(';')], exists: () => true })[0], 'C:\\nvm\\bin', 'and stay first on the machine PATH that terminal tabs get');
+        t.equal(rebuildPath({ machine: agentPath.join(';'), user: 'C:\\nvm\\nodejs', process: '', env: {} }).split(';')[0], 'C:\\nvm\\bin', 'a new shell keeps them first');
         t.check(isPinnedNodeDir('C:\\nvm\\v24.1.0\\', 'C:\\nvm') && !isPinnedNodeDir('C:\\nvm', 'C:\\nvm'), 'only versions are pinned');
         t.equal(pathKey('C:\\'), 'c:\\', 'a drive root keeps its slash');
         t.equal(splitPath(' "C:\\a" ;; C:\\b;'), ['C:\\a', 'C:\\b'], 'splitting drops empty parts and quotes');

package/dist/selftest/agent-settings.test.js

@@ -30,14 +30,45 @@ export const agentSettingsSuite = {
         t.section('codex config.toml');
         const old = '# Set by the sandbox: x\nsandbox_mode = "danger-full-access"\n\n[tui]\nscreen_reader_detection_done = true\n\n[windows]\nsandbox = "elevated"\n';
         const owned = codexConfigOwned(old, CODEX);
-        t.check(!owned.includes('sandbox_mode') && !owned.includes('Set by the sandbox') && !owned.includes('sandbox = '), 'the old sandbox_mode lines and [windows] sandbox are removed', owned);
-        t.check(owned.includes('mcp_oauth_credentials_store = "file"') &&
-            owned.includes('[tui]\nscreen_reader_detection_done = true\n') &&
-            owned.includes('[windows]'), 'MCP logins go to a file; every other line stays', owned);
+        const marker = owned.split('\n')[0];
+        t.check(marker.startsWith('# Set by the sandbox'), 'the marked lines start the file', owned);
+        t.equal(owned, marker +
+            '\nsandbox_mode = "danger-full-access"\napproval_policy = "never"\n\nmcp_oauth_credentials_store = "file"\n\n' +
+            '[tui]\nscreen_reader_detection_done = true\n\n[windows]\n', 'sandbox_mode and approval_policy are written above the first table (the old marked lines replaced), MCP logins go to a file, [windows] sandbox is removed for "off", every other line stays');
         t.equal(codexConfigOwned(owned, CODEX), owned, 'running it again changes nothing');
+        t.equal(codexConfigOwned(owned, { ...CODEX, sandboxMode: 'workspace-write', approvalPolicy: 'on-request' }), owned
+            .replace('"danger-full-access"', '"workspace-write"')
+            .replace('approval_policy = "never"', 'approval_policy = "on-request"'), 'changed settings replace the marked lines in place');
+        const tuned = codexConfigOwned('', { ...CODEX, model: 'gpt-5', reasoningEffort: 'high', mcpLoginsInFile: false });
+        t.equal(tuned.split('\n').slice(1), [
+            'sandbox_mode = "danger-full-access"',
+            'approval_policy = "never"',
+            'model = "gpt-5"',
+            'model_reasoning_effort = "high"',
+            '',
+        ], 'model and reasoning effort are written when set (an empty file gets only the marked lines)');
+        t.equal(codexConfigOwned(tuned, { ...CODEX, mcpLoginsInFile: false }), tuned.replace('model = "gpt-5"\nmodel_reasoning_effort = "high"\n', ''), 'and removed again when cleared');
+        const mine = 'approval_policy = "on-request"\n\n[windows]\nsandbox = "elevated"\n';
+        const respected = codexConfigOwned(mine, { ...CODEX, mcpLoginsInFile: false });
+        t.check(respected.includes('sandbox_mode = "danger-full-access"') &&
+            respected.includes('approval_policy = "on-request"') &&
+            !respected.includes('approval_policy = "never"') &&
+            !respected.includes('sandbox = "elevated"'), "a user's own unmarked line is kept and not written again", respected);
+        t.equal(codexConfigOwned(respected, { ...CODEX, mcpLoginsInFile: false }), respected, 'stable with it too');
+        const crlf = old.replace(/\n/g, '\r\n');
+        const ownedCrlf = codexConfigOwned(crlf, CODEX);
+        t.equal(ownedCrlf, owned.replace(/\n/g, '\r\n'), 'a CRLF file is edited the same way and keeps CRLF');
+        t.equal(codexConfigOwned(ownedCrlf, CODEX), ownedCrlf, 'running it again on CRLF changes nothing');
+        const byHand = '# agent-sandbox: Windows Sandbox already contains Codex; its own command sandbox is off.\n' +
+            'sandbox_mode = "danger-full-access"\napproval_policy = "never"\nmcp_oauth_credentials_store = "file"\n\n' +
+            '[tui]\nscreen_reader_detection_done = true\n\n[projects.\'c:\\x\']\ntrust_level = "trusted"\n';
+        const adopted = codexConfigOwned(byHand, CODEX);
+        t.equal(adopted, marker +
+            '\nsandbox_mode = "danger-full-access"\napproval_policy = "never"\n\nmcp_oauth_credentials_store = "file"\n\n' +
+            '[tui]\nscreen_reader_detection_done = true\n\n[projects.\'c:\\x\']\ntrust_level = "trusted"\n', 'lines under the hand-made "# agent-sandbox:" marker count as the sandbox\'s and are replaced');
+        t.equal(codexConfigOwned(adopted, CODEX), adopted, 'and stay stable after that');
         t.includes(codexConfigOwned(old, { ...CODEX, windowsSandbox: 'unelevated' }), '[windows]\nsandbox = "unelevated"', 'a Windows sandbox mode is written when asked for');
         t.includes(codexConfigOwned('mcp_oauth_credentials_store = "keyring"\n', CODEX), 'mcp_oauth_credentials_store = "keyring"', "a user's own mcp_oauth_credentials_store is kept");
-        t.equal(codexConfigOwned('', { ...CODEX, mcpLoginsInFile: false }), '', 'an empty file stays empty when nothing is owned');
         t.section('Anthropic key pattern');
         const body = 'a'.repeat(60);
         t.check(ANTHROPIC_KEY_PATTERN.test('sk-ant-usr01-' + body) && ANTHROPIC_KEY_PATTERN.test('sk-ant-api03-' + body), 'sk-ant-api03- and sk-ant-usr01- keys are accepted');

package/dist/selftest/boot-console.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './support/suite.js';
+export declare const bootConsoleSuite: Suite;

package/dist/selftest/boot-console.test.js

@@ -0,0 +1,291 @@
+// The boot's console (docs/design/parallel-boot.md, "Console output"): a fixture of runner events played into the
+// progress view, read back as the exact plain output (logs, CI, dry runs) and as live frames (a terminal), colours
+// stripped. Also the log file's line format. Pure: a fake clock and a fake screen, no terminal.
+import { plainText, fileLines } from '../guest/runtime/log-line.js';
+import { CONSOLE_GLYPHS, ProgressView, readyLines, RICH_GLYPHS, stepsDetail, wrap, } from '../guest/boot/progress-view.js';
+const STAGES = [
+    { stage: 1, name: 'Network and session host' },
+    { stage: 2, name: 'Pre-provision hooks and desktop' },
+    { stage: 3, name: 'Developer tools' },
+    { stage: 4, name: 'Agent: claude' },
+];
+const TASKS = [
+    { id: 'ptyhost', stage: 1, title: 'Session host' },
+    { id: 'network', stage: 1, title: 'Private-network blocking' },
+    { id: 'desktop', stage: 2, title: 'Personalisation' },
+    { id: 'toolchains', stage: 3, title: 'Developer tools', critical: true },
+    { id: 'dbCommands', stage: 3, title: 'Tool commands' },
+    { id: 'agent', stage: 4, title: 'Agent install', critical: true },
+];
+const task = (id) => TASKS.find((t) => t.id === id);
+const done = (id, ms) => ({ id, title: task(id).title, state: 'done', ms });
+const play = (live, columns = 80) => {
+    let now = 0;
+    let written = '';
+    let taken = 0;
+    const view = new ProgressView(STAGES, TASKS, {
+        live,
+        glyphs: live ? RICH_GLYPHS : CONSOLE_GLYPHS,
+        now: () => now,
+        screen: { write: (text) => void (written += text), columns: () => columns },
+    });
+    return {
+        view,
+        out: () => written,
+        take: () => {
+            const part = written.slice(taken);
+            taken = written.length;
+            return part;
+        },
+        at: (ms) => {
+            now = ms;
+        },
+    };
+};
+/** The happy boot: overlapping tasks, lines from several stages, a warning, a soft failure, the summary. */
+const happyBoot = (p) => {
+    const v = p.view;
+    v.start('Agent sandbox · demo · claude · C:\\Work\\demo');
+    v.line('Service sign-ins: none', undefined);
+    v.started(task('ptyhost'));
+    v.started(task('desktop'));
+    v.started(task('dbCommands'));
+    v.line('Desktop personalisation applied from this PC.', 2);
+    p.at(300);
+    v.finished(task('ptyhost'), done('ptyhost', 300));
+    v.started(task('network'));
+    p.at(1200);
+    v.finished(task('desktop'), done('desktop', 1200));
+    v.line('LAN blocked in the guest firewall.', 1);
+    v.warning('gh: the GitHub login was kept in Credential Manager. Log in again with: gh auth login --web');
+    p.at(1300);
+    v.finished(task('dbCommands'), { ...done('dbCommands', 1300), state: 'failed', error: 'disk full' });
+    v.warning('Tool commands failed (continuing): disk full');
+    p.at(4600);
+    v.finished(task('network'), done('network', 4300));
+    v.started(task('toolchains'));
+    v.detail('toolchains', stepsDetail(['Node', 'Python', 'Rust', 'Go', 'Java'], 5, 13));
+    v.line('Installing the Visual C++ runtime ...', 3);
+    p.at(13600);
+    v.finished(task('toolchains'), done('toolchains', 9000));
+    v.started(task('agent'));
+    v.line('claude already cached in persistent storage.', 4);
+    p.at(15400);
+    v.finished(task('agent'), done('agent', 1800));
+    v.summary(['git: 2.43.0.windows.1', 'node: 24.22.0 (from this PC, switch with nvm use)', 'vc++ runtime: installed']);
+    v.notice('If Claude asks you to sign in, do it once; the login is saved in persistent storage.');
+    v.release({
+        ms: 15400,
+        outcomes: [done('ptyhost', 300), done('network', 4300), done('toolchains', 9000), done('agent', 1800)],
+        background: ['Visual Studio', 'Unreal'],
+        logPath: 'C:\\AgentData\\logs\\guest.log',
+    });
+};
+const PLAIN_HAPPY = [
+    'Agent sandbox · demo · claude · C:\\Work\\demo',
+    '',
+    'Service sign-ins: none',
+    '[1/4] Network and session host           4.6s',
+    '      LAN blocked in the guest firewall.',
+    '[2/4] Pre-provision hooks and desktop    1.2s',
+    '      Desktop personalisation applied from this PC.',
+    '[3/4] Developer tools                   13.6s',
+    '      Installing the Visual C++ runtime ...',
+    '[4/4] Agent: claude                      1.8s',
+    '      claude already cached in persistent storage.',
+    '',
+    'Warnings',
+    '  ! gh: the GitHub login was kept in Credential Manager. Log in again with: gh auth login --web',
+    '  ! Tool commands failed (continuing): disk full',
+    '',
+    'Tools',
+    '  git           2.43.0.windows.1',
+    '  node          24.22.0 (from this PC, switch with nvm use)',
+    '  vc++ runtime  installed',
+    '',
+    'If Claude asks you to sign in, do it once; the login is saved in persistent storage.',
+    '',
+    'Ready in 15.4s (slowest: Developer tools 9.0s, Private-network blocking 4.3s, Agent install 1.8s)',
+    'Still installing in the background: Visual Studio, Unreal (a few minutes; it does not hold you up)',
+    'Log: C:\\AgentData\\logs\\guest.log',
+    '',
+].join('\n');
+export const bootConsoleSuite = {
+    name: 'boot-console',
+    title: "the boot's console: plain ordered output, live stage rows, warnings, tool summary, log file lines",
+    run: (t) => {
+        t.section('plain output (logs, CI, dry runs)');
+        {
+            const p = play(false);
+            happyBoot(p);
+            t.equal(p.out().split('\n'), PLAIN_HAPPY.split('\n'), 'a boot prints its stages in order, each once finished');
+            t.check(!p.out().includes('\x1b'), 'plain output has no colour or cursor codes');
+        }
+        {
+            // Stage 1 finishes last: stages 2 and 3 wait for it, then all three come out in order.
+            const p = play(false);
+            const v = p.view;
+            v.start('header');
+            p.take();
+            v.started(task('ptyhost'));
+            v.started(task('desktop'));
+            v.finished(task('desktop'), done('desktop', 0));
+            const early = p.take();
+            v.finished(task('ptyhost'), done('ptyhost', 0));
+            v.started(task('network'));
+            v.finished(task('network'), done('network', 0));
+            t.check(early === '' && /^\[1\/4\][^\n]*\n\[2\/4\]/.test(p.take()), 'a finished stage waits until the stages before it are printed', early);
+        }
+        {
+            const p = play(false);
+            const v = p.view;
+            v.start('header');
+            v.started(task('ptyhost'));
+            v.finished(task('ptyhost'), done('ptyhost', 100));
+            v.started(task('network'));
+            v.finished(task('network'), done('network', 100));
+            v.started(task('desktop'));
+            v.finished(task('desktop'), done('desktop', 100));
+            v.started(task('dbCommands'));
+            v.started(task('toolchains'));
+            p.at(2000);
+            v.finished(task('toolchains'), { ...done('toolchains', 2000), state: 'failed', error: 'no network' });
+            v.finished(task('dbCommands'), done('dbCommands', 2000));
+            v.finished(task('agent'), { ...done('agent', 0), state: 'skipped', error: 'Developer tools failed' });
+            p.take();
+            v.release(null);
+            t.equal(p.out().split('\n').slice(4, 8), [
+                '[3/4] Developer tools                    2.0s  FAILED',
+                '      x Developer tools failed: no network',
+                '[4/4] Agent: claude                    skipped',
+                '      - Agent install skipped (Developer tools failed)',
+            ], 'a critical failure marks its stage FAILED and says why; what comes after it is skipped');
+        }
+        {
+            const p = play(false);
+            p.view.start('header');
+            p.view.started(task('ptyhost'));
+            p.view.line('half way', 1);
+            p.take();
+            p.view.release(null);
+            t.equal(p.take().split('\n'), ['[1/4] Network and session host           0.0s  not finished', '      half way', ''], 'when the boot fails, a stage that had started is printed with what it logged');
+        }
+        t.section('live frames (a terminal)');
+        {
+            const p = play(true);
+            const v = p.view;
+            v.start('Agent sandbox · demo · claude · C:\\Work\\demo');
+            t.equal(v.frame(false), [
+                '  · 1  Network and session host                 waiting',
+                '  · 2  Pre-provision hooks and desktop          waiting',
+                '  · 3  Developer tools                          waiting',
+                '  · 4  Agent: claude                            waiting',
+            ], 'before any task: every stage waits');
+            v.started(task('ptyhost'));
+            v.started(task('desktop'));
+            v.started(task('dbCommands'));
+            p.at(300);
+            v.finished(task('ptyhost'), done('ptyhost', 300));
+            v.started(task('network'));
+            p.at(1200);
+            v.finished(task('desktop'), done('desktop', 1200));
+            v.finished(task('dbCommands'), done('dbCommands', 1200));
+            v.started(task('toolchains'));
+            v.detail('toolchains', stepsDetail(['Node', 'Python', 'Rust', 'Go', 'Java'], 5, 13));
+            v.warning('gh: the GitHub login was kept in Credential Manager. Log in again with: gh auth login --web');
+            p.at(12340);
+            t.equal(v.frame(false), [
+                // 12340 ms: the spinner's fifth frame.
+                '  ⠼ 1  Network and session host          12.3s  Private-network blocking',
+                '  ✓ 2  Pre-provision hooks and desktop    1.2s',
+                '  ⠼ 3  Developer tools                   12.3s  Node, Python, Rust +2 (5/13)',
+                '  · 4  Agent: claude                            waiting',
+                '',
+                '  ! gh: the GitHub login was kept in Credential Manager. Log in again with: gh…',
+            ], 'while tasks run: their stage spins and names them (the toolchain steps), done stages show their time');
+            t.check(v.frame(false).every((l) => l.length <= 79) && plainText(v.frame().join('\n')) === v.frame(false).join('\n'), 'every row fits in the terminal (one column spare); the colours are only colours');
+            const narrow = play(true, 53);
+            narrow.view.started(task('toolchains'));
+            narrow.view.detail('toolchains', stepsDetail(['Node', 'Python'], 1, 9));
+            t.equal(narrow.view.frame(false)[2], '  ⠋ 3  Developer tools                    0.0s  Nod…', 'a narrow terminal cuts the row, not wraps it');
+            p.take();
+            v.tick();
+            const redraw = p.take();
+            // The first frame (at start) had the 4 rows; this one has the rows, a blank line and the warning.
+            t.check(redraw.startsWith('\r\x1b[4A') && redraw.endsWith('\x1b[J') && redraw.split('\n').length === 7, 'a redraw moves up over the block it drew last and draws the new one in place', JSON.stringify(redraw.slice(0, 40)));
+            v.tick();
+            t.check(p.take() === '', 'nothing is drawn when nothing changed');
+            const before = v.capturing;
+            let inside = true;
+            const printed = v.aside(() => {
+                inside = v.capturing;
+                v.line('Hook [pre-agent]: 90-games.cmd', 2);
+                return 7;
+            });
+            const asideText = p.take();
+            t.check(printed === 7 &&
+                asideText.startsWith('\r\x1b[6A\x1b[J') &&
+                asideText.includes('Hook [pre-agent]: 90-games.cmd\n') &&
+                asideText.endsWith('\x1b[J'), 'a hook gets the terminal: the block steps aside, the hook prints, the block comes back below it', JSON.stringify(asideText.slice(0, 60)));
+            t.check(before && !inside && v.capturing, "programs' output goes to the log while the block owns the terminal, not while a hook has it");
+            v.finished(task('network'), done('network', 12040));
+            v.finished(task('toolchains'), done('toolchains', 11140));
+            v.started(task('agent'));
+            p.at(14000);
+            v.finished(task('agent'), done('agent', 1660));
+            v.summary(['git: 2.43.0.windows.1', 'PROTECTION MISSING: the LAN firewall is off']);
+            p.take();
+            v.release({
+                ms: 14000,
+                outcomes: [done('network', 12040), done('toolchains', 11140), done('agent', 1660)],
+                background: [],
+                logPath: 'C:\\AgentData\\logs\\guest.log',
+            });
+            const final = p.take();
+            t.equal(plainText(final).replace(/\r/g, '').split('\n'), [
+                '  ✓ 1  Network and session host          12.3s',
+                '  ✓ 2  Pre-provision hooks and desktop    1.2s',
+                '  ✓ 3  Developer tools                   12.3s',
+                '  ✓ 4  Agent: claude                      1.7s',
+                '',
+                'Warnings',
+                '  ! gh: the GitHub login was kept in Credential Manager. Log in again with: gh',
+                '    auth login --web',
+                '',
+                'Tools',
+                '  git                 2.43.0.windows.1',
+                '  PROTECTION MISSING  the LAN firewall is off',
+                '',
+                'Ready in 14.0s (slowest: Private-network blocking 12.0s, Developer tools 11.1s, Agent install 1.7s)',
+                'Log: C:\\AgentData\\logs\\guest.log',
+                '',
+            ], 'when ready: the block stays as a still list, then the warnings in full, the tools and the ready line');
+            t.check(final.startsWith('\r\x1b[') && final.endsWith('\x1b[?25h') && !v.capturing, 'release erases the live block, shows the cursor again and gives the console back');
+            v.line('late line', 3);
+            v.warning('late warning');
+            v.tick();
+            t.check(p.take() === '', 'nothing prints after the release (the first session owns the console)');
+        }
+        {
+            const p = play(true);
+            p.view.start('x');
+            p.view.started(task('ptyhost'));
+            p.view.line('an info line', 1);
+            t.check(!plainText(p.out()).includes('an info line') && p.view.capturing, 'live: info lines go to the log file only, and programs hand their output to the log');
+        }
+        t.section('pieces');
+        t.equal(stepsDetail([], 0, 0), 'Developer tools', 'no step running yet: the stage says what it does');
+        t.equal(readyLines({ ms: 900, outcomes: [done('ptyhost', 900)], background: ['A', 'B', 'C', 'D', 'E'], logPath: 'l' }), [
+            'Ready in 0.9s',
+            'Still installing in the background: A, B, C and 2 more (a few minutes; it does not hold you up)',
+        ], 'the ready line names no task under a second; a long background list is shortened');
+        t.equal(wrap('aa bb cc dd', 5), ['aa bb', 'cc dd'], 'wrap breaks between words');
+        t.equal(wrap('abcdefghij k', 4), ['abcd', 'efgh', 'ij k'], 'wrap cuts a word longer than the width');
+        t.section('log file lines');
+        const at = new Date(Date.UTC(2026, 10, 4, 2, 7, 5, 9));
+        t.equal(fileLines('hello', at), ['2026-11-04T02:07:05.009Z hello'], 'a file line starts with a zero-padded UTC time');
+        t.equal(fileLines('\n\x1b[36m[1/9] Network\x1b[0m\r\nsecond  ', at, 'Developer tools'), ['2026-11-04T02:07:05.009Z [Developer tools] [1/9] Network', '2026-11-04T02:07:05.009Z [Developer tools] second'], 'colours are stripped, each line gets its own time and task, blank lines are dropped');
+        t.equal(fileLines('\n \n', at), [], 'a blank message writes nothing');
+        t.equal(plainText('\x1b[2K\x1b[?25l\x1b[1;33mx\x1b[0m'), 'x', 'cursor and colour codes are removed');
+    },
+};

package/dist/selftest/boot-runner.test.js

@@ -1,6 +1,6 @@
 // The parallel boot (docs/design/parallel-boot.md): the task runner, the pools, the boot graph and the toolchain
 // scheduler's download phase and background split. Fake tasks and deferred promises only: no machine state.
-import { BootRunner, bootSummary, checkGraph } from '../guest/boot/runner.js';
+import { BootRunner, checkGraph, duration } from '../guest/boot/runner.js';
 import { BOOT_TASKS, STAGES, stageTitle } from '../guest/boot/graph.js';
 import { backgroundNames, mergeParts, runSplit } from '../guest/toolchains/split.js';
 import { StepScheduler } from '../guest/toolchains/step-scheduler.js';
@@ -31,13 +31,19 @@ const def = (id, after = [], more = {}) => ({
 const fixture = () => {
     const lines = [];
     const warnings = [];
+    const events = [];
     const contexts = [];
     return {
         lines,
         warnings,
+        events,
         contexts,
         options: (extra = {}) => ({
-            say: (line) => void lines.push(line),
+            trace: (line) => void lines.push(line),
+            observer: {
+                started: (task) => void events.push('started ' + task.id),
+                finished: (task, outcome) => void events.push('finished ' + task.id + ' ' + outcome.state),
+            },
             warn: (line) => void warnings.push(line),
             now: () => Date.now(),
             dryRun: false,
@@ -243,7 +249,7 @@ export const bootRunnerSuite = {
             const quietBefore = f.contexts.map((c) => c.quiet).join(',');
             await runner.run('background');
             t.check(before === 'a' && quietBefore === 'false' && ran.join(',') === 'a,bg' && f.contexts[1]?.quiet === true, 'a background task starts only on run("background"), in a quiet (file-only) log context', before + ' / ' + quietBefore);
-            t.check(!f.lines.some((l) => l.includes('BG: started')), 'background tasks print no progress lines');
+            t.check(!f.events.some((e) => e.includes(' bg')) && f.events.join(',') === 'started a,finished a done', 'the progress view hears only the foreground tasks (the background ones are file-only)', f.events.join(','));
         }
         t.section('runner: graph checks');
         t.check(throws(() => checkGraph([def('a', ['b']), def('b', ['a'])])).includes('circle'), 'a cycle is refused');
@@ -347,16 +353,8 @@ export const bootRunnerSuite = {
                 [1, 2, 3, 4, 5, 6, 7, 8, 9].every((n) => stageTitle(n).length > 0) &&
                 stageTitle(4, { vpnServer: 'x' }).includes('x') &&
                 stageTitle(4) === 'VPN (off)', 'there are nine stage titles, the VPN one names the server or says off');
-            const summary = bootSummary(31800, [
-                { id: 'a', title: 'Headroom', state: 'done', ms: 28100 },
-                { id: 'b', title: 'Developer tools', state: 'done', ms: 7000 },
-                { id: 'c', title: 'Skipped one', state: 'skipped', ms: 0 },
-            ], ['Visual Studio'], 'guest.log');
-            t.check(summary.startsWith('Boot ready in 31.8s.') &&
-                summary.includes('Headroom 28.1s') &&
-                !summary.includes('Skipped one') &&
-                summary.includes('In the background: Visual Studio'), 'the boot summary names the time, the slowest tasks and the background work', summary);
         }
+        t.equal([duration(0), duration(4630), duration(59949), duration(60000), duration(422400)], ['0.0s', '4.6s', '59.9s', '1m00s', '7m02s'], 'durations: tenths of a second under a minute, then minutes and seconds');
         t.section('toolchain scheduler');
         {
             const events = [];