toolroll 0.9.65 → 0.9.68

package/dist/invoke.js

@@ -29,19 +29,16 @@ import { witnessedRunner } from "./process-custody.js";
 import { underStopWatch } from "./task-control.js";
 import { childDatabaseEnv, isolatedChildDatabase, removeChildDatabase as removeAgentDatabase } from "./child-database.js";
 import { RunSignInError, noToolsArgs, prepareRunTools } from "./project-tools.js";
-import { mkdirSync, readFileSync, realpathSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { poolRootOf } from "./worktree.js";
 import { BRIDGE_DIR } from "./agent-fence.js";
-import { agentFence, CheckoutBindingError, trustedWorktreeBinding, checkoutGitEnv, HARDENED_GIT_ARGS, codexFenceArgv, fenceGrants, fencedGitEnv, linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced, NO_GRANTS, runFolders, taskBoundary } from "./agent-fence.js";
+import { agentFence, buildCacheEnv, buildCacheFolder, grantFolder, writeAllowlist, WRITES_DEFAULT, CheckoutBindingError, trustedWorktreeBinding, checkoutGitEnv, HARDENED_GIT_ARGS, codexFenceArgv, fenceGrants, fencedGitEnv, linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced, NO_GRANTS, runFolders, taskBoundary } from "./agent-fence.js";
 import { proxyEnv, providerOnlyNetwork, startEgressProxy } from "./egress.js";
 import { bridgeFits, startEgressBridge } from "./egress-bridge.js";
 import { claudeConfigDir, claudeDefaults, codexDefaults, codexHomeDir, isolatedCodexHome } from "./provider-home.js";
 import { billingOf, claudeBillingFrom, seenBilling } from "./spend.js";
-/** The claude binary name — kept for the legacy quota rows and tests that
- * describe history; new code carries a resolved AgentSpec instead. */
-export const PROVIDER_BINARY = "claude";
 /** "Within seconds": how soon a silent failed run must end for its stderr to
  * be read for the sign-in signal. */
 const AUTH_EARLY_EXIT_MS = 30_000;
@@ -64,6 +61,11 @@ function claudeSettingsAuthProblem(configDir) {
     catch (error) {
         if (error.code === "ENOENT")
             return null;
+        // A sandbox around the plane (a project check's fence, say) may hide the file while the CLI still signs in from its
+        // keychain. Isolated builds never load it, and a login that needed it fails within seconds and is reported as one.
+        const code = error.code;
+        if (code === "EPERM" || code === "EACCES")
+            return null;
         return "Can't read your Claude settings.json to check sign-in. Restore access to that file and try again. Isolated builds do not load it.";
     }
     let settings;
@@ -239,7 +241,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // re-supply survives resolveChildEnv's chat-key strip); in
     // "subscription" mode the key is STRIPPED from the child so the CLI's
     // own login is used — its key is retained, just not handed over.
-    const { runner, clock: _clock, versionProbe: _probe, keyHome, timeoutMs: _hardTimeout, idleTimeoutMs: _idleTimeout, stdin: _callerStdin, accumulateUsage: _accumulateUsage, liveInput: _liveInput, acpCheck: _acpCheck, network: launchNetwork, ...runOptions } = options;
+    const { runner, clock: _clock, versionProbe: _probe, keyHome, timeoutMs: _hardTimeout, idleTimeoutMs: _idleTimeout, stdin: _callerStdin, accumulateUsage: _accumulateUsage, liveInput: _liveInput, acpCheck: _acpCheck, network: launchNetwork, writes: launchWrites, ...runOptions } = options;
     // The live setting is read STRICTLY (atomic authority closure): a
     // present mode file that says neither word is a value-shaped refusal
     // before any stamp or process — never the subscription default a
@@ -300,12 +302,21 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // The project's tools (v80): exactly its MCP servers, and none of the
     // operator's global or a repository's own, served by this launch's broker
     // (tool-broker.ts), which alone holds their secrets. A review keeps its isolation.
+    // Set once the fence is known: a fenced build's servers never start outside a fence.
+    let serverMustBeFenced = false;
+    // What the build writes (its checkout, its project's caches): a tool server never runs from there, nor reads it at all.
+    const serverUntrusted = workspace === null ? [] : toolUntrusted(store, workspace, keyHome);
     const launchTools = invocation.phase === "review" ? null : await runTools(store, runId, spec, options.keyHome, clock, invocation.readOnlyTools, invocation.researchWithheld, containment, {
         env: { ...process.env, ...(runOptions.env ?? {}) },
         omitEnv: [...(runOptions.omitEnv ?? []), ...ALL_CREDENTIAL_ENV],
         pass: childDatabaseEnv(isolatedDb.file),
-        ...(workspace === null ? {} : { cwd: workspace }),
+        // A tool server starts in a folder the build can't write, and never runs the build's own bytes (arc 2).
+        cwd: keyHome ?? homedir(),
+        untrusted: serverUntrusted,
         wrap: () => serverFence,
+        // A fenced build's tool servers start only in a fence too, unless an instance operator allowed unconfined agents.
+        unwrapped: () => serverMustBeFenced && !store.unfencedAgentsAllowed()
+            ? "This machine can't confine the tool's server (no macOS sandbox, no working bubblewrap), so it was not started." : null,
     });
     if (launchTools !== null && "refused" in launchTools) {
         removeAgentDatabase(isolatedDb.dir);
@@ -333,7 +344,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // tool servers outside its command sandbox, so its own launch folder is
     // fenced too; Claude reads its config from there, inside the sandbox.
     const ownTools = tools?.privateDir === undefined ? null : realpathSync(tools.privateDir);
-    const fenceOf = invocation.phase === "review" ? { fence: [], fileTools: [], grants: NO_GRANTS, gitPaths: [], problem: undefined } : runFence(store, runId, spec.provider, options.keyHome, codexHarness ? null : ownTools);
+    const fenceOf = invocation.phase === "review" ? { fence: [], fileTools: [], grants: NO_GRANTS, gitPaths: [], cache: undefined, problem: undefined } : runFence(store, runId, spec.provider, options.keyHome, codexHarness ? null : ownTools, launchWrites ?? WRITES_DEFAULT);
     if (fenceOf.problem !== undefined) {
         tools?.cleanup();
         codexHome?.cleanup();
@@ -372,12 +383,16 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
     // A tool server the broker starts is fenced by what this platform supports, whatever the provider: Codex's own
     // profile fences only its agent's commands, and the broker starts servers outside it.
     if (fence.length > 0) {
-        // A tool server keeps its own reach (it holds its tool's secrets, not the agent's code): never the agent's network.
-        const serverGrants = () => { const { network: _agentOnly, ...rest } = grants; return rest; };
+        // A tool server keeps its own reach (it holds its tool's secrets, not the agent's code): never the agent's network,
+        // nor its write allowlist (a server keeps its own state where it always has).
+        const serverGrants = () => { const { network: _agentOnly, writes: _agentWrites, ...rest } = grants; return rest; };
+        // Nor read what the build wrote: however its arguments are spelled, no byte of the checkout or caches can load.
+        const serverDenies = [...fence, ...serverUntrusted.filter(path => existsSync(path)).map(path => realpathSync(path))];
         if (macosFenceAvailable())
-            serverFence = (file, args) => macosFenced(file, args, fence, serverGrants());
+            serverFence = (file, args) => macosFenced(file, args, serverDenies, serverGrants());
         else if (linuxFenceAvailable())
-            serverFence = (file, args) => linuxFenced(file, args, fence, serverGrants());
+            serverFence = (file, args) => linuxFenced(file, args, serverDenies, serverGrants());
+        serverMustBeFenced = true;
     }
     // No silent fallback (arc 1): a build this machine can't confine at the OS — Claude reduced to its own file-tool
     // rules, Gemini to nothing — doesn't start unless the instance operator allowed unconfined agents here. An injected
@@ -457,6 +472,10 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
         ...(egress === null || !("policy" in network) ? {} : proxyEnv(egress, network.policy.loopback)),
         // Its own temp folder, where its tools' sockets may live (the only one its fence admits besides its checkout).
         ...(runTemp === null ? {} : { TMPDIR: runTemp, TMP: runTemp, TEMP: runTemp }),
+        // Claude's own working folder goes there too (it is otherwise the shared /tmp/claude-<uid>).
+        ...(runTemp === null || spec.provider !== "claude" ? {} : { CLAUDE_CODE_TMPDIR: runTemp }),
+        // A workspace build's package managers keep their caches in its project's own folder (arc 2).
+        ...(fenceOf.cache === undefined || grants.writes === undefined ? {} : buildCacheEnv(fenceOf.cache)),
         // This key is deliberately last: no caller may point an agent back at
         // the live control database through a generic RunOptions override.
         ...childDatabaseEnv(isolatedDb.file),
@@ -906,7 +925,7 @@ function linkedFor(store, worktree) {
 /** The paths this run's agent may not reach: the state folder around the live database (but not its own worktree),
  * ~/.toolroll (or its older name), its task boundary and other launches' private folders; what the fence gives back
  * (FenceGrants); and what only Claude's file tools refuse. */
-function runFence(store, runId, provider, keyHome, ownTools) {
+function runFence(store, runId, provider, keyHome, ownTools, writes = WRITES_DEFAULT) {
     try {
         // A plane always has a database file; an in-memory store (a test) has nothing to fence.
         const databaseFile = store.databaseFile();
@@ -921,22 +940,128 @@ function runFence(store, runId, provider, keyHome, ownTools) {
         const binding = worktree === null || row === null ? null : trustedWorktreeBinding(row.repo, worktree, poolRoots);
         const boundary = worktree === null ? null : taskBoundary({ worktree, provider, ...home, binding });
         const folders = runFolders(ownTools);
+        // A build with a checkout writes only its workspace unless its approval said anywhere (arc 2): its checkout and
+        // Git data, its launch folder, its project's caches and the provider state its CLI must write.
+        const allowed = worktree === null || row === null || writes !== "workspace" ? null
+            : writeAllowlist({ provider, home: keyHome ?? homedir(), worktree, binding, launchFolder: ownTools, cache: buildCacheFolder(row.repo, keyHome ?? homedir()) });
+        const fence = agentFence({ databaseFile, worktree, ...home, boundary, binding, runFolders: folders, extra: allowed?.deny ?? [] });
+        const grants = fenceGrants({ databaseFile, worktree, boundary, runFolders: folders, linked: linkedFor(store, worktree), binding, ...home, poolRoots });
         return {
-            fence: agentFence({ databaseFile, worktree, ...home, boundary, binding, runFolders: folders }),
+            fence,
             fileTools: boundary?.fileTools ?? [],
             // The shared install is granted only as the plane linked it: this checkout's project and stamped setup.
             // Every plane checkout pool is denied around this one: the plane's own beside the database, and the one this
             // checkout was recorded in (a --pool elsewhere), so another project's worktree, present at launch, is out of reach. Native wrappers also cover later creations.
-            grants: fenceGrants({ databaseFile, worktree, boundary, runFolders: folders, linked: linkedFor(store, worktree), binding, ...home,
-                poolRoots }),
+            grants: allowed === null ? grants : { ...grants, writes: allowed.writes, readOnly: [...new Set([...grants.readOnly, ...allowed.readOnly])].sort() },
             // The checkout's own Git data, which a private /tmp gives back beside the checkout (agent-fence.ts linuxFenced).
             gitPaths: binding === null ? [] : [binding.gitdir, join(binding.main, ".git")],
+            ...(allowed === null || row === null ? {} : { cache: buildCacheFolder(row.repo, keyHome ?? homedir()) }),
         };
     }
     catch (error) {
         return { fence: [], fileTools: [], grants: NO_GRANTS, problem: error instanceof CheckoutBindingError ? error.message : "The build fence could not be prepared." };
     }
 }
+/**
+ * A build's setup and check commands, run in its fence (arc 2): the same denies as its agent's (Toolroll's state,
+ * credentials, other projects and runs), its write allowlist when its approval sealed one (its checkout and Git data,
+ * its project's caches, and a temp folder of the command's own), and its package managers pointed at those caches.
+ * Their network stays as it was. A machine without an OS fence runs them as before; a fence that can't be prepared
+ * (a checkout whose binding no longer proves) runs nothing.
+ */
+export function fencedCommands(store, runId, writes, inner, available = () => macosFenceAvailable() || linuxFenceAvailable()) {
+    // An injected runner (tests) starts no real command, as an injected agent starts no real agent (invokeAgent).
+    if (inner !== runCommand)
+        return inner;
+    return async (file, args, options) => {
+        // As a build itself: where nothing can confine them, they run only when an instance operator allowed unconfined agents.
+        if (!available()) {
+            if (store.unfencedAgentsAllowed())
+                return inner(file, args, options);
+            return { code: 1, stdout: "", stderr: "This machine can't confine the build's commands (no macOS sandbox, no working bubblewrap), so they didn't run. Install bubblewrap, or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`.\n", timedOut: false, notFound: false };
+        }
+        const own = realpathSync(mkdtempSync(join(tmpdir(), "so-cmd-")));
+        try {
+            const temp = join(own, "tmp");
+            mkdirSync(temp, { mode: 0o700 });
+            const fenced = runFence(store, runId, "command", undefined, own, writes);
+            if (fenced.problem !== undefined)
+                return { code: 1, stdout: "", stderr: `${fenced.problem}\n`, timedOut: false, notFound: false };
+            if (fenced.fence.length === 0)
+                return inner(file, args, options);
+            // A self-hosted check's own database (child-database.ts) is the command's to write too.
+            const database = options?.env?.["TOOLROLL_DB"];
+            const checkData = database === undefined || fenced.grants.writes === undefined ? null : grantFolder(dirname(database), false);
+            const grants = checkData === null ? fenced.grants : { ...fenced.grants, writes: { ...fenced.grants.writes, subpaths: [...fenced.grants.writes.subpaths, checkData] } };
+            return await inner(file, args, {
+                ...options,
+                fence: fenced.fence,
+                fenceGrants: grants,
+                env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp, ...(fenced.cache === undefined || fenced.grants.writes === undefined ? {} : buildCacheEnv(fenced.cache)) },
+            });
+        }
+        finally {
+            rmSync(own, { recursive: true, force: true });
+        }
+    };
+}
+/**
+ * A project's checks run in a checkout of a result's commit made for them (result-follow-ups.ts, batch-checks.ts), in
+ * the same fence as a build's commands: Toolroll's state, credentials, other projects and runs denied; under the
+ * project's writes setting, only that checkout, its Git data, its own temp folder, the project's caches and its check
+ * database writable. Where nothing can confine them, they run only when an instance operator allowed unconfined agents.
+ */
+export function fencedCheckoutCommands(store, repo, checkout, inner, available = () => macosFenceAvailable() || linuxFenceAvailable()) {
+    if (inner !== runCommand)
+        return inner;
+    return async (file, args, options) => {
+        if (!available()) {
+            if (store.unfencedAgentsAllowed())
+                return inner(file, args, options);
+            return { code: 1, stdout: "", stderr: "This machine can't confine the project's checks (no macOS sandbox, no working bubblewrap), so they didn't run. Install bubblewrap, or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`.\n", timedOut: false, notFound: false };
+        }
+        const databaseFile = store.databaseFile();
+        if (databaseFile === null)
+            return inner(file, args, options);
+        const own = realpathSync(mkdtempSync(join(tmpdir(), "so-cmd-")));
+        try {
+            const temp = join(own, "tmp");
+            mkdirSync(temp, { mode: 0o700 });
+            let binding;
+            try {
+                binding = trustedWorktreeBinding(repo, checkout);
+            }
+            catch {
+                return { code: 1, stdout: "", stderr: "The check's checkout couldn't be bound to its project, so nothing ran.\n", timedOut: false, notFound: false };
+            }
+            const poolRoots = [join(dirname(databaseFile), "worktrees"), ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
+            const boundary = taskBoundary({ worktree: checkout, provider: "command", binding });
+            const folders = runFolders(own);
+            const cache = buildCacheFolder(repo);
+            const allowed = store.projectWrites(repo) !== "workspace" ? null : writeAllowlist({ provider: "command", home: homedir(), worktree: checkout, binding, launchFolder: own, cache });
+            const database = options?.env?.["TOOLROLL_DB"];
+            const checkData = allowed === null || database === undefined ? null : grantFolder(dirname(database), false);
+            const base = fenceGrants({ databaseFile, worktree: checkout, boundary, runFolders: folders, linked: linkedFor(store, checkout), binding, poolRoots });
+            const grants = allowed === null ? base
+                : { ...base, readOnly: [...new Set([...base.readOnly, ...allowed.readOnly])].sort(), writes: { ...allowed.writes, subpaths: [...allowed.writes.subpaths, ...(checkData === null ? [] : [checkData])] } };
+            return await inner(file, args, {
+                ...options,
+                fence: agentFence({ databaseFile, worktree: checkout, boundary, binding, runFolders: folders, extra: allowed?.deny ?? [] }),
+                fenceGrants: grants,
+                env: { ...(options?.env ?? {}), TMPDIR: temp, TMP: temp, TEMP: temp, ...(allowed === null ? {} : buildCacheEnv(cache)) },
+            });
+        }
+        finally {
+            rmSync(own, { recursive: true, force: true });
+        }
+    };
+}
+/** What a build writes that a tool server must never run from: its checkout and its project's caches. A checkout with
+ * no record never gets this far: its fence refuses the launch (runFence) before any tool server can start. */
+function toolUntrusted(store, workspace, keyHome) {
+    const row = store.getWorktree(workspace);
+    return [workspace, ...(row === null ? [] : [buildCacheFolder(row.repo, keyHome ?? homedir())])];
+}
 /** The operator's own model choices a build routed with no model keeps (provider-home.ts). */
 function inheritedDefaults(provider, env, home) {
     if (provider === "claude")

package/dist/is-record.d.ts

@@ -0,0 +1,2 @@
+/** A plain object: not null, not an array. */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/is-record.js

@@ -0,0 +1,2 @@
+/** A plain object: not null, not an array. */
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/lead-doors.d.ts

@@ -1,5 +1,5 @@
 import { type SharedActionOptions } from './chat-actions.js';
-import { type CoordinatorProposal, type LeadProposal, type Store } from "./store.js";
+import { type LeadProposal, type Store } from "./store.js";
 import type { VerifiedApprover } from "./principal.js";
 import { type TeamChatProviderResolver } from './team-chat-authorization.js';
 export type ProposalKind = LeadProposal["kind"];
@@ -78,7 +78,3 @@ export declare function dismissLeadProposal(store: Store, who: VerifiedApprover,
  */
 export declare function confirmCoordinatorProposal(store: Store, who: VerifiedApprover, proposalId: number, now: Date, options: DoorOptions): DoorOutcome;
 export declare function dismissCoordinatorProposal(store: Store, who: VerifiedApprover, proposalId: number, now: Date): boolean;
-/** Which door renders a coordinator proposal for this reader: the repo must be admitted. */
-export declare function coordinatorProposalVisible(who: {
-    repos: readonly string[];
-}, proposal: CoordinatorProposal): boolean;

package/dist/lead-doors.js

@@ -260,10 +260,6 @@ export function dismissCoordinatorProposal(store, who, proposalId, now) {
         return store.casCoordinatorProposal(proposalId, "pending", "dismissed", who.name, null, now);
     });
 }
-/** Which door renders a coordinator proposal for this reader: the repo must be admitted. */
-export function coordinatorProposalVisible(who, proposal) {
-    return who.repos.includes(proposal.repo);
-}
 /**
  * The shared executor: one kind, one payload, the operator's own act
  * through the primitive that owns it. Module-private (v3 review, finding

package/dist/lead-tools.js

@@ -1,5 +1,4 @@
 import { sweepLine, sweepTable } from "./lead-sweep.js";
-import { TEXT_LIMITS } from "./text-limits.js";
 import { connectionsOf, oneClickOf } from "./mcp-connect.js";
 import { checkLevelFromWords, isCheckLevel } from "./check-levels.js";
 import { policyParts } from "./policy.js";
@@ -39,9 +38,9 @@ import { CHAT_TASK_ACTIONS, chatTaskRun, chatTaskStamp, isChatTaskAction } from
 import { Buffer } from "node:buffer";
 import { LEAD_ASK_OTHER } from "./store.js";
 import { hasDisguisedText, hasForbiddenControls } from "./decision.js";
-import { readVerifiedArtifact, readVerifiedReport, scanForSecrets } from "./evidence.js";
+import { readVerifiedArtifact, scanForSecrets } from "./evidence.js";
 import { parseAcceptanceCriteria } from "./scope.js";
-import { diagnoseTaskDispatch, withDispatchDiagnoses } from "./dispatch.js";
+import { diagnoseTaskDispatch } from "./dispatch.js";
 import { agentChoicesFor, routeOfTask, INSTALLATION_SCOPE } from "./agentconfig.js";
 import { isNewModel, modelWords, priceWords, runtimeStates, seenModels } from "./model-catalog.js";
 import { agentsSummary, chosenWords, PHASES, postureWords, routeProblems, sameSpec, sizeSourceWords, sizeWords, specWords } from "./phase-routing.js";
@@ -55,7 +54,7 @@ import { planInChat } from "./chat-decide.js";
 import { flowDecisionAt } from "./telegram-flow.js";
 import { flowPersonOf } from "./flow-send.js";
 import { flowInsights } from "./flow-insights.js";
-import { describeTrigger, FLOW_TRIGGER_KINDS, triggerConfigOf } from "./flow-triggers.js";
+import { describeTrigger, triggerConfigOf } from "./flow-triggers.js";
 export const LEAD_MAX_PROPOSALS_PER_TURN = 5;
 export { reportSummaryFor } from "./report-summary.js";
 import { reportSummaryFor } from "./report-summary.js";
@@ -63,8 +62,6 @@ import { labelOf, nameOf, summaryOf, zonesOf } from "./subagent-admin.js";
 import { SUBAGENT_TEMPLATES, withSection } from "./subagents.js";
 import { callOutcome, callWords, defaultRule, ruleWords } from "./subagent-tools.js";
 import { deskOf, routinesOf } from "./subagent-desk.js";
-import { KITS } from "./kits.js";
-import { STARTER_IDS } from "./flow-starters.js";
 import { undoFor, weekOf, weekWords } from "./subagent-week.js";
 import { PERSON_ID, personEntry, teamRoomOf } from "./lead-people.js";
 import { aboutYouOf, checkAboutYouLine } from "./lead-about.js";

package/dist/live-detail.d.ts

@@ -10,7 +10,6 @@ export type LiveDetailSetting = {
 };
 /** Whether this project's live conversations show commands. Unknown or absent is off. */
 export declare function liveCommandsShown(store: Store, repo: string | null): boolean;
-export declare function liveDetailSetting(store: Store, repo: string): LiveDetailSetting | null;
 /** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
 export declare function setLiveCommands(store: Store, change: {
     repo: string;

package/dist/live-detail.js

@@ -26,12 +26,6 @@ export function liveCommandsShown(store, repo) {
         return false;
     }
 }
-export function liveDetailSetting(store, repo) {
-    const row = store.handle.prepare("SELECT repo, commands, updated_by, updated_at FROM live_detail_setting WHERE repo = ?").get(repo);
-    if (row === undefined)
-        return null;
-    return { repo: String(row["repo"]), commands: Number(row["commands"]) === 1, updatedBy: String(row["updated_by"]), updatedAt: String(row["updated_at"]) };
-}
 /** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
 export function setLiveCommands(store, change, now) {
     store.transact(() => {

package/dist/live-terminal.d.ts

@@ -6,8 +6,6 @@ export declare const MAX_LIVE_TERMINALS = 8;
 export declare const MAX_KEPT_TERMINALS = 16;
 /** At most this many pages attached to one session (a desktop, a phone, a spare tab or two). */
 export declare const MAX_VIEWERS = 4;
-/** Raw output kept per session for a page that attaches later. */
-export declare const SCROLLBACK_BYTES: number;
 /** After SIGHUP, the terminal's processes have this long before SIGKILL. */
 export declare const CLOSE_GRACE_MS = 2000;
 /** Typed input not yet read by the program, per terminal: past this, more is refused until it reads. */
@@ -54,15 +52,24 @@ export declare const ttyName: (path: unknown) => string | null;
 export declare function pendingInputOf(pty: unknown): number;
 /** node-pty, if this install has it (an optional dependency with prebuilt binaries); null when it doesn't load. */
 export declare function loadPtySpawn(): PtySpawn | null;
-/** Raw output, oldest dropped first, never more than `cap` bytes. */
-export declare class Scrollback {
-    private readonly cap;
-    private chunks;
-    private size;
-    constructor(cap?: number);
-    push(chunk: Buffer): void;
-    bytes(): Buffer;
-    get length(): number;
+/** How many lines above the screen a terminal keeps for a page that attaches later. */
+export declare const SCREEN_SCROLLBACK_LINES = 5000;
+/**
+ * The terminal as a page would see it now: every byte the program writes is parsed by a headless xterm here, so a page
+ * that attaches later gets the screen, its scrollback and its modes (the alternate screen of a full-screen program, the
+ * cursor, colours, bracketed paste, mouse reporting) — never a replay of raw output cut at an arbitrary byte, which
+ * could split an escape sequence or redraw a full-screen program garbled.
+ */
+export declare class ScreenMirror {
+    private readonly lines;
+    private readonly terminal;
+    private readonly serializer;
+    constructor(cols: number, rows: number, lines?: number);
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    /** The screen as of this call (after everything written before it), handed to `done` once parsed. */
+    snapshot(done: (screen: string) => void): void;
+    dispose(): void;
 }
 /** One attached page. The host never waits on it. */
 export type TerminalViewer = {
@@ -138,7 +145,8 @@ export type TerminalHostOptions = {
     /** Start, close and remove, for the event log (never input or output). */
     record?: (event: "start" | "close" | "remove" | "exit", session: TerminalSummary) => void;
     maxSessions?: number;
-    scrollbackBytes?: number;
+    /** Lines above the screen a terminal keeps for a page that attaches later (SCREEN_SCROLLBACK_LINES). */
+    scrollbackLines?: number;
     closeGraceMs?: number;
     ledger?: TerminalLedger;
     /** The process table (tests stand a failing one in); null when it can't be read. */
@@ -175,7 +183,10 @@ export declare class TerminalHost {
         cols: number;
         rows: number;
     }, admit?: () => string | null): Promise<TerminalSummary>;
-    /** Attach a page: it gets the scrollback, then `hello`, then live output. Returns its detach. */
+    /**
+     * Attach a page: it gets the screen as it is now (ScreenMirror), then `hello`, then live output — what the program
+     * writes meanwhile is held and sent after the screen, in order. Returns its detach.
+     */
     attach(id: string, viewer: TerminalViewer): () => void;
     /** How many pages are attached now. */
     viewerCount(id: string): number;

package/dist/live-terminal.js

@@ -13,14 +13,13 @@ import { existsSync, mkdirSync, readlinkSync, realpathSync, statSync } from "nod
 import { delimiter, isAbsolute, join } from "node:path";
 import { codingEnvironment } from "./coding-provider.js";
 import { teardownGit, refusal } from "./teardown-git.js";
+import { sleep } from "./sleep.js";
 export const TERMINAL_PROGRAMS = ["claude", "codex", "shell"];
 /** At most this many running sessions per console, and this many kept at all (ended ones count until removed). */
 export const MAX_LIVE_TERMINALS = 8;
 export const MAX_KEPT_TERMINALS = 16;
 /** At most this many pages attached to one session (a desktop, a phone, a spare tab or two). */
 export const MAX_VIEWERS = 4;
-/** Raw output kept per session for a page that attaches later. */
-export const SCROLLBACK_BYTES = 1024 * 1024;
 /** After SIGHUP, the terminal's processes have this long before SIGKILL. */
 export const CLOSE_GRACE_MS = 2_000;
 /** Typed input not yet read by the program, per terminal: past this, more is refused until it reads. */
@@ -70,37 +69,45 @@ export function loadPtySpawn() {
         return null;
     }
 }
-/** Raw output, oldest dropped first, never more than `cap` bytes. */
-export class Scrollback {
-    cap;
-    chunks = [];
-    size = 0;
-    constructor(cap = SCROLLBACK_BYTES) {
-        this.cap = cap;
-    }
-    push(chunk) {
-        if (chunk.length >= this.cap) {
-            this.chunks = [chunk.subarray(chunk.length - this.cap)];
-            this.size = this.cap;
-            return;
-        }
-        this.chunks.push(chunk);
-        this.size += chunk.length;
-        while (this.size > this.cap) {
-            const first = this.chunks[0];
-            const over = this.size - this.cap;
-            if (first.length <= over) {
-                this.chunks.shift();
-                this.size -= first.length;
-            }
-            else {
-                this.chunks[0] = first.subarray(over);
-                this.size -= over;
-            }
+/** How many lines above the screen a terminal keeps for a page that attaches later. */
+export const SCREEN_SCROLLBACK_LINES = 5000;
+const require = createRequire(import.meta.url);
+/**
+ * The terminal as a page would see it now: every byte the program writes is parsed by a headless xterm here, so a page
+ * that attaches later gets the screen, its scrollback and its modes (the alternate screen of a full-screen program, the
+ * cursor, colours, bracketed paste, mouse reporting) — never a replay of raw output cut at an arbitrary byte, which
+ * could split an escape sequence or redraw a full-screen program garbled.
+ */
+export class ScreenMirror {
+    lines;
+    terminal;
+    serializer;
+    constructor(cols, rows, lines = SCREEN_SCROLLBACK_LINES) {
+        this.lines = lines;
+        const { Terminal } = require("@xterm/headless");
+        const { SerializeAddon } = require("@xterm/addon-serialize");
+        this.terminal = new Terminal({ cols, rows, scrollback: lines, allowProposedApi: true });
+        this.serializer = new SerializeAddon();
+        this.terminal.loadAddon(this.serializer);
+    }
+    write(data) { this.terminal.write(data); }
+    resize(cols, rows) { try {
+        this.terminal.resize(cols, rows);
+    }
+    catch { /* sizes are clamped before this */ } }
+    /** The screen as of this call (after everything written before it), handed to `done` once parsed. */
+    snapshot(done) {
+        this.terminal.write("", () => { let screen = ""; try {
+            screen = this.serializer.serialize({ scrollback: this.lines });
         }
+        catch {
+            screen = "";
+        } done(screen); });
+    }
+    dispose() { try {
+        this.terminal.dispose();
     }
-    bytes() { return Buffer.concat(this.chunks, this.size); }
-    get length() { return this.size; }
+    catch { /* already */ } }
 }
 const NO_LEDGER = { reserve() { }, running() { }, release() { }, forget() { } };
 export class TerminalError extends Error {
@@ -237,7 +244,7 @@ export class TerminalHost {
             }
             let resolveExited;
             const session = { id, owner, generation, repo, program, branch, worktree, startedAt: this.clock().toISOString(), endedAt: null, exit: null, endedBy: null, cleanup: null,
-                pty, leader: pty.pid, tty: pty.tty, known: new Map(), exitedAt: null, worktreeReal: realpathSync(worktree), startedMs: Date.now(), residentsOnly: false, residentsSeen: new Map(), cols, rows, scrollback: new Scrollback(this.options.scrollbackBytes), viewers: new Set(), closing: null,
+                pty, leader: pty.pid, tty: pty.tty, known: new Map(), exitedAt: null, worktreeReal: realpathSync(worktree), startedMs: Date.now(), residentsOnly: false, residentsSeen: new Map(), cols, rows, screen: new ScreenMirror(cols, rows, this.options.scrollbackLines), viewers: new Set(), closing: null,
                 exited: new Promise(resolve => { resolveExited = resolve; }) };
             this.sessions.set(id, session);
             this.ledger.running(id);
@@ -246,7 +253,7 @@ export class TerminalHost {
             pty.onData(data => {
                 this.noteSoon();
                 const chunk = Buffer.from(data, "utf8");
-                session.scrollback.push(chunk);
+                session.screen.write(data);
                 for (const viewer of session.viewers) {
                     try {
                         viewer.output(chunk);
@@ -280,21 +287,50 @@ export class TerminalHost {
                 this.ledger.release(id, null);
         }
     }
-    /** Attach a page: it gets the scrollback, then `hello`, then live output. Returns its detach. */
+    /**
+     * Attach a page: it gets the screen as it is now (ScreenMirror), then `hello`, then live output — what the program
+     * writes meanwhile is held and sent after the screen, in order. Returns its detach.
+     */
     attach(id, viewer) {
         const session = this.sessions.get(id);
         if (session === undefined)
             throw new TerminalError("No such terminal.");
         if (session.viewers.size >= MAX_VIEWERS)
             throw new TerminalError(`This terminal is open in ${MAX_VIEWERS} places already. Close one of them.`);
-        const replay = session.scrollback.bytes();
-        if (replay.length > 0)
-            viewer.output(replay);
-        viewer.control({ t: "hello", cols: session.cols, rows: session.rows, program: session.program, ended: session.endedAt !== null });
-        if (session.exit !== null)
-            viewer.control({ t: "exit", code: session.exit.code, signal: session.exit.signal });
-        session.viewers.add(viewer);
-        return () => { session.viewers.delete(viewer); };
+        const held = [];
+        let live = false;
+        const gate = {
+            output: data => { if (live)
+                viewer.output(data);
+            else
+                held.push({ output: data }); },
+            control: message => { if (live)
+                viewer.control(message);
+            else
+                held.push({ control: message }); },
+        };
+        session.viewers.add(gate);
+        session.screen.snapshot(screen => {
+            if (!session.viewers.has(gate))
+                return;
+            try {
+                if (screen !== "")
+                    viewer.output(Buffer.from(screen, "utf8"));
+                viewer.control({ t: "hello", cols: session.cols, rows: session.rows, program: session.program, ended: session.endedAt !== null });
+                if (session.exit !== null && !held.some(one => "control" in one && one.control.t === "exit"))
+                    viewer.control({ t: "exit", code: session.exit.code, signal: session.exit.signal });
+                for (const one of held) {
+                    if ("output" in one)
+                        viewer.output(one.output);
+                    else
+                        viewer.control(one.control);
+                }
+            }
+            catch { /* the viewer's own close handles it */ }
+            held.length = 0;
+            live = true;
+        });
+        return () => { session.viewers.delete(gate); };
     }
     /** How many pages are attached now. */
     viewerCount(id) { return this.sessions.get(id)?.viewers.size ?? 0; }
@@ -319,6 +355,7 @@ export class TerminalHost {
             session.pty.resize(session.cols, session.rows);
         }
         catch { /* it exited between */ }
+        session.screen.resize(session.cols, session.rows);
     }
     noteTimer = null;
     /** Activity (output, typing) usually means a command started: note processes shortly after, at most every 250 ms. */
@@ -368,7 +405,7 @@ export class TerminalHost {
     }
     async sweep(session) {
         const grace = this.options.closeGraceMs ?? CLOSE_GRACE_MS;
-        const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+        const pause = sleep;
         const leaderGone = () => session.pty === null;
         let readable = true;
         const members = () => {
@@ -487,6 +524,7 @@ export class TerminalHost {
             catch { /* gone */ }
         }
         session.viewers.clear();
+        session.screen.dispose();
         const result = await (this.options.git ?? teardownGit())(session.repo, ["worktree", "remove", "--force", "--", session.worktree]);
         this.options.record?.("remove", this.summary(session));
         if (result.code !== 0 && existsSync(session.worktree)) {

package/dist/live.d.ts

@@ -16,7 +16,6 @@
 import { type KeyState, type LiveActivityKind, type LiveRecord, type LiveRecorderOptions } from "./live-records.js";
 export declare const LIVE_LINE_CAP: number;
 export declare const LIVE_FILE_CAP: number;
-export declare const LIVE_CAP_MARKER = "[the live view stopped at its size cap \u2014 the run record continues]";
 export declare const LIVE_REDACTED_LINE = "[a credential-shaped line was redacted]";
 /** Finalized runs keep their live file this long for the final drain. */
 export declare const LIVE_RETAIN_MS: number;

package/dist/live.js

@@ -16,10 +16,9 @@
 import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { scanForSecrets } from "./evidence.js";
-import { createLiveRecorder, LIVE_CAP_WORDS, parseLiveRecords, redactLiveLines, projectLiveText, serializeLiveRecord } from "./live-records.js";
+import { createLiveRecorder, parseLiveRecords, redactLiveLines, projectLiveText, serializeLiveRecord } from "./live-records.js";
 export const LIVE_LINE_CAP = 2 * 1024;
 export const LIVE_FILE_CAP = 4 * 1024 * 1024;
-export const LIVE_CAP_MARKER = LIVE_CAP_WORDS;
 export const LIVE_REDACTED_LINE = "[a credential-shaped line was redacted]";
 /** Finalized runs keep their live file this long for the final drain. */
 export const LIVE_RETAIN_MS = 24 * 60 * 60 * 1000;