@namzu/sandbox 14.0.0 → 16.0.0

package/dist/backends/firecracker/transport.js

@@ -52,11 +52,12 @@
  * socket to be silently severed by a resume), which makes the
  * transport resume-survivable by construction.
  */
+import { randomUUID } from 'node:crypto';
 import net from 'node:net';
 import tls from 'node:tls';
 import { OperationDeadline, OperationDeadlineExpired } from '../readiness.js';
 import { REMOTE_EXECUTION_PROTOCOL_VERSION, RemoteCancellationUnknownError, RemoteExecutionController, RemoteProtocolError, } from '../remote-execution-controller.js';
-import { ExecResultAccumulator, parseExecLine, } from './protocol.js';
+import { ExecResultAccumulator, MIN_STREAM_HEARTBEAT_MS, READ_FILE_STREAM_FEATURE, STREAM_HEARTBEAT_MAX_ECHO_FACTOR, STREAM_HEARTBEAT_MISS_LIMIT, WRITE_FILE_PARTS_FEATURE, parseExecLine, } from './protocol.js';
 const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_CONNECT_RETRY_BUDGET_MS = 30_000;
 const DEFAULT_CONNECT_RETRY_INTERVAL_MS = 100;
@@ -88,6 +89,40 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
  * implemented by this transport.
  */
 export const TCP_PREAUTH_FRAME_LIMIT_BYTES = 8 * 1024 * 1024;
+/**
+ * The guest agent's default ceiling on ANY frame, pre-auth or not —
+ * mirrors `agent.cjs`'s `MAX_FRAME_BYTES` (`NAMZU_AGENT_MAX_FRAME_BYTES`,
+ * default 256 MiB). It is the budget the `unix`/`vsock`/`mtls` arms are
+ * bounded by, since none of them runs a credential gate and so none of
+ * them ever pays the smaller pre-auth price.
+ */
+export const GUEST_FRAME_LIMIT_BYTES = 256 * 1024 * 1024;
+/** Default {@link VsockTransportOptions.maxWriteFileBytes} — 1 GiB. */
+export const DEFAULT_MAX_WRITE_FILE_BYTES = 1024 * 1024 * 1024;
+/**
+ * Idle time before the kernel sends its first TCP keepalive probe on a
+ * `tcp`-arm connection, host side. 15 s, matching the Kubernetes backend's
+ * default heartbeat interval, so the two bounds do not disagree about how
+ * long a silent connection is allowed to look healthy.
+ */
+export const TCP_KEEPALIVE_INITIAL_DELAY_MS = 15_000;
+/**
+ * Slack subtracted from a frame budget when sizing a part, over and above
+ * the envelope this transport measures exactly. The guest's own accounting
+ * is of the framed payload, and a deployment is free to configure a
+ * slightly different ceiling than the default this side assumes; a
+ * kilobyte of headroom costs one part in a thousand and removes a whole
+ * class of off-by-a-few refusals.
+ */
+const WRITE_FILE_PART_HEADROOM_BYTES = 1024;
+/**
+ * How long the best-effort removal of an abandoned part file may take.
+ * Bounded separately from the connect retry budget because it runs AFTER
+ * the caller's write has already failed — often because the peer is gone —
+ * and a caller waiting on a rejection should not wait out a retry budget
+ * for a cleanup whose failure it is never told about.
+ */
+const WRITE_FILE_DISCARD_TIMEOUT_MS = 5_000;
 /**
  * Thrown when a `tcp`-handle request's framed envelope (op + body +
  * token) would exceed {@link TCP_PREAUTH_FRAME_LIMIT_BYTES}. Named so a
@@ -100,6 +135,81 @@ export class AgentPreauthFrameTooLargeError extends Error {
         this.name = 'AgentPreauthFrameTooLargeError';
     }
 }
+/**
+ * Thrown when a `writeFile` body exceeds
+ * {@link VsockTransportOptions.maxWriteFileBytes}. Distinct from
+ * {@link AgentPreauthFrameTooLargeError}: that one says the WIRE cannot
+ * carry this in one frame (and, since the part protocol, only ever fires
+ * when the guest cannot carry it in several either), this one says the
+ * HOST was configured not to send a body this large at all.
+ */
+export class AgentWriteFileTooLargeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentWriteFileTooLargeError';
+    }
+}
+/**
+ * Thrown when a read this transport cannot serve on the old whole-file op
+ * is asked of a guest that does not advertise
+ * {@link READ_FILE_STREAM_FEATURE} — a ranged `readFile`, or any
+ * `readFileStream`.
+ *
+ * A refusal rather than a fallback, and that is the whole point of the
+ * class: an agent that predates the feature IGNORES `offset`/`length` and
+ * answers with the WHOLE file, so silently taking the old path would hand
+ * a caller the entire file where it asked for a slice — a wrong answer
+ * dressed as a degraded one. Named so a host can tell "rebuild the guest
+ * image" apart from "that file is not there".
+ */
+export class AgentReadFileStreamUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentReadFileStreamUnsupportedError';
+    }
+}
+/**
+ * How many bytes of a `read-file-stream` may sit decoded on this side
+ * while the consumer is slow, before the socket is paused.
+ *
+ * The bound exists because an `AsyncIterable` consumer pulls: without it a
+ * fast guest would fill the host's heap with exactly the whole file this
+ * op exists to avoid materialising. One chunk is the guest's own
+ * `NAMZU_AGENT_READ_FILE_STREAM_CHUNK_BYTES` (256 KiB by default), so this
+ * is a few chunks in flight and nothing like a file. A deployment that
+ * raises that variable raises the number of BYTES held here, not the
+ * number of chunks: this is a byte bound, so it keeps holding.
+ *
+ * Deliberately not derived from the guest's value. The guest is a
+ * different process on a different release train, this side has to bound
+ * its own heap before it has asked the guest anything, and a host that
+ * trusted a guest-supplied chunk size for its own bound would have no
+ * bound at all.
+ */
+const READ_FILE_STREAM_HIGH_WATER_BYTES = 4 * 1024 * 1024;
+/**
+ * Thrown — as the rejection of a session terminal's `exited` — when the
+ * attachment ended and the program did not.
+ *
+ * `exited` may not RESOLVE here: a resolved `exited` says the program is
+ * over, and reporting `exitCode: -1` for a shell that is still running in
+ * the pod is exactly the confusion this whole feature exists to remove. The
+ * offset is carried because it is what the next attach resumes from.
+ */
+export class AgentSessionDetachedError extends Error {
+    nextOffset;
+    name = 'AgentSessionDetachedError';
+    constructor(nextOffset, message, options) {
+        super(message, options);
+        this.nextOffset = nextOffset;
+    }
+}
+export class AgentDialFailedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'AgentDialFailedError';
+    }
+}
 /** Exact guest wire version accepted by this Firecracker transport. */
 export const FIRECRACKER_AGENT_PROTOCOL_VERSION = REMOTE_EXECUTION_PROTOCOL_VERSION;
 /** Framing: 8 hex digits of payload byte length, then `\n`, then payload. */
@@ -109,18 +219,38 @@ function frame(payload) {
     const header = Buffer.from(`${body.length.toString(16).padStart(LENGTH_PREFIX_HEX, '0')}\n`, 'ascii');
     return Buffer.concat([header, body]);
 }
+/**
+ * A growable accumulator that frees the buffer it grew past a threshold.
+ * Sized once so both numbers are stated where they are read.
+ */
+const FRAME_BUFFER_INITIAL_BYTES = 64 * 1024;
+const FRAME_BUFFER_RETAIN_BYTES = 1024 * 1024;
 /**
  * Incremental frame reader. Feed it socket chunks; it yields complete
  * payloads. A zero-length frame is the exec stream terminator and is
  * surfaced as an empty string so the caller can stop.
+ *
+ * It accumulates into ONE buffer it grows geometrically, with a read
+ * cursor, rather than re-`concat`ing every arriving chunk onto a fresh
+ * allocation. The distinction only matters for a large frame, where it is
+ * the difference between linear and quadratic: a `read-file` reply for a
+ * 64 MiB file arrives as ~1400 socket chunks, and copying everything
+ * received so far onto each one of them spent half a minute of memcpy on
+ * a reply the socket delivered in under a second. Identical framing,
+ * identical errors, identical `bufferedBytes` — only the copying changes.
  */
 class FrameReader {
     buf = Buffer.alloc(0);
+    /** First byte not yet handed out as part of a frame. */
+    start = 0;
+    /** One past the last byte received. */
+    end = 0;
     push(chunk) {
-        this.buf = this.buf.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.buf, chunk]);
+        this.append(chunk);
         const out = [];
         for (;;) {
-            const nl = this.buf.indexOf(0x0a); // '\n'
+            const view = this.buf.subarray(this.start, this.end);
+            const nl = view.indexOf(0x0a); // '\n'
             if (nl < 0 || nl < LENGTH_PREFIX_HEX) {
                 // Need at least the hex header + newline.
                 if (nl >= 0 && nl < LENGTH_PREFIX_HEX) {
@@ -128,7 +258,7 @@ class FrameReader {
                 }
                 break;
             }
-            const header = this.buf.subarray(0, nl).toString('ascii');
+            const header = view.subarray(0, nl).toString('ascii');
             if (!/^[0-9a-fA-F]{8}$/.test(header)) {
                 throw new Error(`vsock transport: invalid frame length header ${JSON.stringify(header)}`);
             }
@@ -137,16 +267,53 @@ class FrameReader {
                 throw new Error(`vsock transport: invalid frame length header ${JSON.stringify(header)}`);
             }
             const start = nl + 1;
-            if (this.buf.length < start + len)
+            if (view.length < start + len)
                 break; // incomplete payload
-            const payload = this.buf.subarray(start, start + len).toString('utf8');
-            this.buf = this.buf.subarray(start + len);
-            out.push(payload);
+            out.push(view.subarray(start, start + len).toString('utf8'));
+            this.consume(start + len);
         }
         return out;
     }
     get bufferedBytes() {
-        return this.buf.length;
+        return this.end - this.start;
+    }
+    /** Copy `chunk` in, growing (and first compacting) only when needed. */
+    append(chunk) {
+        if (chunk.length === 0)
+            return;
+        if (this.buf.length - this.end < chunk.length) {
+            const needed = this.bufferedBytes + chunk.length;
+            if (this.buf.length >= needed) {
+                // Compacting the unread bytes to the front is enough.
+                this.buf.copy(this.buf, 0, this.start, this.end);
+            }
+            else {
+                let capacity = this.buf.length > 0 ? this.buf.length : FRAME_BUFFER_INITIAL_BYTES;
+                // Geometric, so the total copying across a whole reply stays
+                // proportional to its length rather than to its length squared.
+                while (capacity < needed)
+                    capacity *= 2;
+                const grown = Buffer.allocUnsafe(capacity);
+                this.buf.copy(grown, 0, this.start, this.end);
+                this.buf = grown;
+            }
+            this.end = this.bufferedBytes;
+            this.start = 0;
+        }
+        chunk.copy(this.buf, this.end);
+        this.end += chunk.length;
+    }
+    /** Mark `bytes` from the read cursor as consumed. */
+    consume(bytes) {
+        this.start += bytes;
+        if (this.start !== this.end)
+            return;
+        this.start = 0;
+        this.end = 0;
+        // A reply that grew the buffer to hundreds of megabytes should not
+        // keep holding them for the life of a long-lived connection.
+        if (this.buf.length > FRAME_BUFFER_RETAIN_BYTES)
+            this.buf = Buffer.alloc(0);
     }
 }
 /**
@@ -161,7 +328,22 @@ export class VsockAgentTransport {
     connectRetryBudgetMs;
     connectRetryIntervalMs;
     readIdleTimeoutMs;
+    /** Undefined → this transport negotiates no heartbeat at all. */
+    heartbeatMs;
     onDial;
+    onDialAttempt;
+    onGuestReply;
+    maxWriteFileBytes;
+    writeFilePartBytes;
+    /**
+     * What the guest advertised in `healthz`, cached for this handle's
+     * lifetime. A pod does not swap its agent binary while it is running,
+     * so the probe is asked once per transport and only when something
+     * actually depends on a capability — an ordinary write, exec, read or
+     * terminal pays nothing for it.
+     */
+    guestFeatureList;
+    permanentDialFailure;
     executionController;
     constructor(handle, options = {}) {
         this.handle = handle;
@@ -170,7 +352,17 @@ export class VsockAgentTransport {
         this.connectRetryIntervalMs =
             options.connectRetryIntervalMs ?? DEFAULT_CONNECT_RETRY_INTERVAL_MS;
         this.readIdleTimeoutMs = options.readIdleTimeoutMs ?? DEFAULT_READ_IDLE_TIMEOUT_MS;
+        if (options.heartbeatMs !== undefined && options.heartbeatMs > 0) {
+            this.heartbeatMs = Math.floor(options.heartbeatMs);
+        }
         this.onDial = options.onDial;
+        this.onDialAttempt = options.onDialAttempt;
+        this.onGuestReply = options.onGuestReply;
+        this.maxWriteFileBytes = options.maxWriteFileBytes ?? DEFAULT_MAX_WRITE_FILE_BYTES;
+        if (options.writeFilePartBytes !== undefined) {
+            this.writeFilePartBytes = Math.max(1, Math.floor(options.writeFilePartBytes));
+        }
+        this.permanentDialFailure = options.permanentDialFailure;
         const adapter = {
             label: 'framed microVM agent',
             reserve: async (signal) => await this.reserveExecution(signal),
@@ -194,15 +386,22 @@ export class VsockAgentTransport {
      * Dial the agent with the resume-survival retry budget. Resolves a
      * connected, post-handshake socket. Retries connect/handshake
      * failures (ECONNREFUSED while the agent re-listens after a resume,
-     * a dropped CONNECT ack) until the budget is exhausted.
+     * a dropped CONNECT ack) until the budget is exhausted — or until
+     * {@link VsockTransportOptions.permanentDialFailure} says this particular
+     * failure is not one waiting will cure.
      */
     async dial(signal) {
         const deadline = Date.now() + this.connectRetryBudgetMs;
         const dialStartedAt = Date.now();
         let lastErr;
+        let permanent = false;
         for (;;) {
             signal?.throwIfAborted();
             try {
+                // Announced BEFORE the attempt, not after it fails: an attempt
+                // aborted mid-connect never reaches the catch below, and that
+                // is precisely the case a watcher needs to hear about.
+                this.onDialAttempt?.();
                 const socket = await this.connectOnce(signal);
                 this.onDial?.(Date.now() - dialStartedAt);
                 return socket;
@@ -211,12 +410,23 @@ export class VsockAgentTransport {
                 if (signal?.aborted)
                     throw signal.reason;
                 lastErr = err;
+                if (this.permanentDialFailure?.(err) === true) {
+                    permanent = true;
+                    break;
+                }
                 if (Date.now() >= deadline)
                     break;
                 await delay(this.connectRetryIntervalMs, signal);
             }
         }
-        throw new Error(`vsock transport: could not connect to agent within ${this.connectRetryBudgetMs}ms (handle=${describeHandle(this.handle)}): ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`, { cause: lastErr });
+        throw new AgentDialFailedError(
+        // Two wordings, because claiming a 30 s budget was spent on a dial
+        // that gave up in 3 ms is a false statement in an error message.
+        // Both keep the "could not connect to agent" phrase: that is what
+        // callers classifying a dial failure match on.
+        permanent
+            ? `vsock transport: could not connect to agent, and the failure is not one retrying fixes (handle=${describeHandle(this.handle)}): ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+            : `vsock transport: could not connect to agent within ${this.connectRetryBudgetMs}ms (handle=${describeHandle(this.handle)}): ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`, { cause: lastErr });
     }
     connectOnce(signal) {
         const handle = this.handle;
@@ -375,6 +585,13 @@ export class VsockAgentTransport {
     connectOnceTcp(handle, signal) {
         return new Promise((resolve, reject) => {
             const socket = net.connect({ host: handle.host, port: handle.port });
+            // SO_KEEPALIVE on the ROUTED arm only. It proves only that the
+            // peer's kernel answers — the application heartbeat is what proves
+            // its event loop does — but it is what gets a half-open connection
+            // through a middlebox reported at all, and it costs a probe every
+            // {@link TCP_KEEPALIVE_INITIAL_DELAY_MS}. The unix/vsock/mtls arms
+            // are deliberately untouched: those are the Firecracker tier's.
+            socket.setKeepAlive(true, TCP_KEEPALIVE_INITIAL_DELAY_MS);
             let settled = false;
             const fail = (err) => {
                 if (settled)
@@ -428,7 +645,29 @@ export class VsockAgentTransport {
         const size = Buffer.byteLength(payload, 'utf8');
         if (size <= TCP_PREAUTH_FRAME_LIMIT_BYTES)
             return;
-        throw new AgentPreauthFrameTooLargeError(`kubernetes tcp transport: request envelope is ${size} bytes, which exceeds the ${TCP_PREAUTH_FRAME_LIMIT_BYTES}-byte limit the guest agent enforces on an unauthenticated connection's first frame (NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES, default 8 MiB). Every tcp request dials a fresh connection, so this request WOULD be that connection's first frame. Chunking a large body across multiple frames is not implemented; reduce the payload or raise the deployment's NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES.`);
+        throw new AgentPreauthFrameTooLargeError(`kubernetes tcp transport: request envelope is ${size} bytes, which exceeds the ${TCP_PREAUTH_FRAME_LIMIT_BYTES}-byte limit the guest agent enforces on an unauthenticated connection's first frame (NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES, default 8 MiB). Every tcp request dials a fresh connection, so this request WOULD be that connection's first frame. A large \`write-file\` body is split across frames automatically (see \`writeFile\`); every other op has to fit, so reduce the payload or raise the deployment's NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES.`);
+    }
+    /**
+     * Hand one accepted reply to {@link VsockTransportOptions.onGuestReply},
+     * and never let the listener's failure reach the caller.
+     *
+     * The caller's result is already decided by the time this runs — the
+     * reply parsed, the frame accounted for — so a hook that throws must not
+     * turn a successful read into a failed one. Swallowing is the only
+     * behaviour that keeps an optional observer optional.
+     */
+    observeGuestReply(reply) {
+        const observe = this.onGuestReply;
+        if (observe === undefined)
+            return;
+        if (reply === null || typeof reply !== 'object')
+            return;
+        try {
+            observe(reply);
+        }
+        catch {
+            // See above: an observer cannot fail an operation.
+        }
     }
     /**
      * Send one framed request and read one framed JSON reply (file-IO +
@@ -483,6 +722,7 @@ export class VsockAgentTransport {
                 if (first !== undefined) {
                     try {
                         response = JSON.parse(first);
+                        this.observeGuestReply(response);
                         if (reader.bufferedBytes > 0) {
                             finish(new Error('vsock transport: control reply has trailing partial data'));
                             return;
@@ -677,6 +917,22 @@ export class VsockAgentTransport {
                 const actual = res.protocolVersion === undefined ? 'missing' : JSON.stringify(res.protocolVersion);
                 throw new RemoteProtocolError(`Firecracker guest protocol version mismatch: expected ${FIRECRACKER_AGENT_PROTOCOL_VERSION}, received ${actual}. Rebuild the golden image from the same Namzu release.`);
             }
+            // The reply that answers readiness also answers what the guest can
+            // do, so the capability caches are filled here rather than by a
+            // second probe later. What that saves depends on the tier: the
+            // Firecracker backend fences on `waitForReady` after create, so
+            // its first `readFile` costs one connection, while the Kubernetes
+            // backend fences on the pod's ready condition and never calls
+            // this — so its first read of a transport's life pays one extra
+            // dial to ask, and every read after it is back to one.
+            //
+            // AFTER both checks, not before: a reply this method is about to
+            // reject is not a reply to believe about anything else, and a
+            // guest that is not ready is one whose features are not yet known
+            // rather than one that has none.
+            this.guestFeatureList = Array.isArray(res.features)
+                ? res.features.filter((value) => typeof value === 'string')
+                : [];
             return true;
         }
         catch (error) {
@@ -720,25 +976,654 @@ export class VsockAgentTransport {
         }
         throw new Error(`vsock transport: agent did not become ready within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
     }
-    async writeFile(path, content) {
+    /**
+     * Write a whole file into the guest workspace.
+     *
+     * A body that fits one frame goes as it always has: a single
+     * `write-file` envelope carrying the base64 content, one round trip,
+     * byte-for-byte the request this transport has always sent.
+     *
+     * A body that does NOT fit is the case this exists for. On the `tcp`
+     * arm every request dials a fresh connection, so every request is that
+     * connection's first, not-yet-authenticated frame (the credential
+     * rides in the envelope) and is bounded by
+     * {@link TCP_PREAUTH_FRAME_LIMIT_BYTES} — about 5.9 MiB of file
+     * content — on EVERY call, not once. Raising the guest's
+     * `NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES` trades away the pre-auth
+     * budget that ceiling exists to bound, so the fix is on this side:
+     * split the body into parts that each fit, append them to a temporary
+     * SIBLING of the target inside the same workspace jail, and finish
+     * with an atomic `rename` onto the target.
+     *
+     * What that buys, and why the shape is what it is:
+     *
+     *  - **A reader never sees a half-written file.** The target changes
+     *    exactly once, in the final part's `rename`. A sequence that dies
+     *    at part 3 of 9 leaves the target exactly as it was — including
+     *    not existing.
+     *  - **A lost or duplicated part is detected, not written.** Each part
+     *    names the offset it starts at and the guest refuses it unless
+     *    that equals the temp file's current size.
+     *  - **An abandoned sequence cleans up after itself.** An abort or a
+     *    transport failure removes the temp file (best effort — a peer
+     *    that has gone away cannot be asked to) and rejects.
+     *  - **Parts go out sequentially on fresh connections**, which is what
+     *    the offset check assumes and what keeps the guest's pre-auth
+     *    connection pool holding one of this caller's sockets at a time.
+     *
+     * The guest must ADVERTISE the capability (`${WRITE_FILE_PARTS_FEATURE}`
+     * in its `healthz` reply) before a single part is sent. An agent that
+     * predates the part protocol would read a part's `content` as a whole
+     * file; it never receives one, and an oversized body against such a
+     * guest still fails with the named
+     * {@link AgentPreauthFrameTooLargeError} it always did.
+     *
+     * {@link VsockTransportOptions.maxWriteFileBytes} is checked FIRST, on
+     * every body and before anything about the wire is considered: it is a
+     * bound on what a caller may push into a workspace, not a bound on
+     * multi-part writes, so a host that lowers it below the frame budget
+     * gets the cap it asked for rather than none.
+     */
+    async writeFile(path, content, signal) {
+        if (content.length > this.maxWriteFileBytes) {
+            throw new AgentWriteFileTooLargeError(`write-file: a body of ${content.length} bytes exceeds this transport's maxWriteFileBytes of ${this.maxWriteFileBytes}. Raise VsockTransportOptions.maxWriteFileBytes to admit it.`);
+        }
+        const budget = this.singleFrameBudgetBytes();
+        const wholeEnvelopeBytes = this.writeFileEnvelopeBytes({ path, content: '', encoding: 'base64' }, content.length);
+        // The configured part size, when there is one, also decides when a
+        // body is split at all — so that with NO configuration the split
+        // point is exactly the wire's own ceiling and every body that used
+        // to travel in one frame still does.
+        const splitsAnyway = this.writeFilePartBytes !== undefined && content.length > this.writeFilePartBytes;
+        if (wholeEnvelopeBytes <= budget && !splitsAnyway) {
+            await this.writeFileWhole(path, content, signal);
+            return;
+        }
+        if (!(await this.guestSupportsWriteFileParts(signal))) {
+            throw this.oversizedWriteFileError(content.length, wholeEnvelopeBytes, budget);
+        }
+        await this.writeFileInParts(path, content, budget, signal);
+    }
+    /** Today's single-frame write, unchanged — see {@link writeFile}. */
+    async writeFileWhole(path, content, signal) {
         const res = await this.request({
             op: 'write-file',
             body: { path, content: content.toString('base64'), encoding: 'base64' },
-        });
+        }, signal);
         if (!res.ok) {
             throw new Error(res.error ?? 'write-file failed');
         }
     }
-    async readFile(path) {
-        const res = await this.request({
-            op: 'read-file',
-            body: { path, encoding: 'base64' },
+    /**
+     * The frame budget one request has on this handle: the pre-auth
+     * ceiling on the credentialed `tcp` arm, the guest's global frame
+     * ceiling on the host-local arms, which authenticate nothing and so
+     * never pay the smaller price.
+     */
+    singleFrameBudgetBytes() {
+        return this.handle.kind === 'tcp' ? TCP_PREAUTH_FRAME_LIMIT_BYTES : GUEST_FRAME_LIMIT_BYTES;
+    }
+    /**
+     * Exact framed size of a `write-file` envelope whose `content` field
+     * holds `contentBytes` raw bytes base64-encoded — WITHOUT encoding
+     * them, so sizing a 1 GiB body costs nothing and never builds a string
+     * longer than V8 permits.
+     *
+     * Exact rather than approximate because the base64 alphabet contains
+     * no character `JSON.stringify` escapes, so the encoded content
+     * contributes precisely its own length to the envelope and the rest of
+     * the envelope (paths, the token, the part fields) is measured as it
+     * will actually be serialized.
+     */
+    writeFileEnvelopeBytes(body, contentBytes) {
+        const envelope = this.withCredential({ op: 'write-file', body });
+        return Buffer.byteLength(JSON.stringify(envelope), 'utf8') + base64Length(contentBytes);
+    }
+    /**
+     * Ask the guest whether it implements the part protocol. Cached for
+     * the transport's lifetime; a transport failure propagates rather than
+     * reading as "not supported", because answering a broken connection
+     * with a too-large error would name the wrong cause.
+     */
+    async guestSupportsWriteFileParts(signal) {
+        return (await this.guestFeatures(signal)).includes(WRITE_FILE_PARTS_FEATURE);
+    }
+    /**
+     * The capability strings this guest advertises in `healthz`, cached for
+     * this transport's lifetime.
+     *
+     * One list, asked once, for every optional op: the write-file part
+     * protocol and the execution-attach ops both read it, and a second
+     * cache would mean a second probe against a guest that answers both
+     * questions in one reply. A transport FAILURE propagates rather than
+     * reading as "not supported", because answering a broken connection
+     * with a capability refusal would name the wrong cause.
+     */
+    async guestFeatures(signal) {
+        if (this.guestFeatureList !== undefined)
+            return this.guestFeatureList;
+        const reply = await this.request({ op: 'healthz' }, signal);
+        const features = Array.isArray(reply.features)
+            ? reply.features.filter((value) => typeof value === 'string')
+            : [];
+        this.guestFeatureList = features;
+        return features;
+    }
+    /**
+     * Send one framed request and read a STREAM of framed JSON events until
+     * the agent's zero-length terminator, handing each event to `onEvent`.
+     *
+     * The generic half of what {@link executeRaw} does, without any of its
+     * opinions about what the events mean: `executeRaw` owns the exec
+     * NDJSON union and the {@link ExecResultAccumulator}, and this owns
+     * dial, framing, the terminator, the observation bound and the
+     * post-terminator close. Additive — nothing already shipped calls it —
+     * so the Firecracker tier's behaviour is untouched and a later streamed
+     * op reuses it rather than writing a fourth copy of this loop.
+     *
+     * There is deliberately NO read-idle timeout. A stream that exists to
+     * follow a long, quiet command must not be torn down for being quiet;
+     * the whole observation is bounded by `observationTimeoutMs` instead,
+     * exactly as an `execute` stream is.
+     */
+    async streamFramedRequest(req, onEvent, options, signal) {
+        const envelope = this.withCredential(req);
+        const payload = JSON.stringify(envelope);
+        this.assertPreauthBudget(payload);
+        const socket = await this.dial(signal);
+        const observationTimeoutMs = Math.min(MAX_TIMER_DELAY_MS, options.observationTimeoutMs);
+        return await new Promise((resolve, reject) => {
+            const reader = new FrameReader();
+            let settled = false;
+            let terminated = false;
+            let closeTimer;
+            const finish = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(observationTimer);
+                if (closeTimer)
+                    clearTimeout(closeTimer);
+                signal?.removeEventListener('abort', abort);
+                socket.destroy();
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            const abort = () => finish(signalError(signal));
+            const observationTimer = setTimeout(() => finish(new Error(`vsock transport: stream observation exceeded ${observationTimeoutMs}ms`)), observationTimeoutMs);
+            observationTimer.unref();
+            socket.on('data', (chunk) => {
+                let frames;
+                try {
+                    frames = reader.push(chunk);
+                }
+                catch (err) {
+                    finish(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                for (const frameText of frames) {
+                    if (terminated) {
+                        finish(new Error('vsock transport: stream emitted data after its terminator'));
+                        return;
+                    }
+                    if (frameText.length === 0) {
+                        terminated = true;
+                        continue;
+                    }
+                    let event;
+                    try {
+                        event = JSON.parse(frameText);
+                    }
+                    catch (err) {
+                        finish(err instanceof Error ? err : new Error(String(err)));
+                        return;
+                    }
+                    try {
+                        onEvent(event);
+                    }
+                    catch (err) {
+                        finish(err instanceof Error ? err : new Error(String(err)));
+                        return;
+                    }
+                }
+                if (terminated) {
+                    if (reader.bufferedBytes > 0) {
+                        finish(new Error('vsock transport: stream has trailing partial data'));
+                        return;
+                    }
+                    closeTimer = setTimeout(() => finish(new Error('vsock transport: stream peer did not close after terminator')), POST_RESPONSE_CLOSE_TIMEOUT_MS);
+                    closeTimer.unref();
+                }
+            });
+            socket.once('error', (err) => finish(err));
+            socket.once('close', () => {
+                if (terminated)
+                    finish(null);
+                else
+                    finish(new Error('vsock transport: socket closed before stream terminator'));
+            });
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
+            signal?.addEventListener('abort', abort, { once: true });
+            socket.write(frame(payload));
         });
+    }
+    /** The refusal for a body no frame can carry and no guest can take in parts. */
+    oversizedWriteFileError(contentBytes, envelopeBytes, budget) {
+        const missing = `This guest does not advertise the '${WRITE_FILE_PARTS_FEATURE}' healthz feature, so the body cannot be split across frames either; rebuild the guest image from this Namzu release, or reduce the payload.`;
+        if (this.handle.kind === 'tcp') {
+            return new AgentPreauthFrameTooLargeError(`kubernetes tcp transport: a write-file of ${contentBytes} bytes needs a ${envelopeBytes}-byte request envelope, which exceeds the ${TCP_PREAUTH_FRAME_LIMIT_BYTES}-byte limit the guest agent enforces on an unauthenticated connection's first frame (NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES, default 8 MiB). Every tcp request dials a fresh connection, so this request WOULD be that connection's first frame. ${missing} Raising the deployment's NAMZU_AGENT_MAX_PREAUTH_FRAME_BYTES also admits it, at the cost of the pre-auth budget that ceiling bounds.`);
+        }
+        return new Error(`vsock transport: a write-file of ${contentBytes} bytes needs a ${envelopeBytes}-byte request envelope, which exceeds the ${budget}-byte frame ceiling the guest agent enforces (NAMZU_AGENT_MAX_FRAME_BYTES, default 256 MiB). ${missing}`);
+    }
+    /**
+     * Write `content` to `target` as a sequence of parts. See
+     * {@link writeFile} for why this shape.
+     */
+    async writeFileInParts(target, content, budget, signal) {
+        const tempPath = writeFilePartTempPath(target);
+        // Sized against the LARGEST part envelope the sequence will send:
+        // the final one, which carries `renameTo` and the largest offset.
+        // Every earlier part is smaller, so none of them can overrun.
+        const envelopeOverhead = this.writeFileEnvelopeBytes({
+            path: tempPath,
+            content: '',
+            encoding: 'base64',
+            part: { offset: content.length, final: true, renameTo: target },
+        }, 0);
+        const room = budget - envelopeOverhead - WRITE_FILE_PART_HEADROOM_BYTES;
+        const framePartBytes = Math.floor(room / 4) * 3;
+        if (framePartBytes <= 0) {
+            throw new AgentWriteFileTooLargeError(`write-file: the request envelope for a part of '${target}' is ${envelopeOverhead} bytes, leaving no room for content inside the ${budget}-byte frame budget. The path is too long for this transport to write in parts.`);
+        }
+        const partBytes = Math.min(framePartBytes, this.writeFilePartBytes ?? framePartBytes);
+        let offset = 0;
+        try {
+            for (;;) {
+                signal?.throwIfAborted();
+                const end = Math.min(offset + partBytes, content.length);
+                const final = end >= content.length;
+                const res = await this.request({
+                    op: 'write-file',
+                    body: {
+                        path: tempPath,
+                        content: content.subarray(offset, end).toString('base64'),
+                        encoding: 'base64',
+                        part: { offset, final, ...(final ? { renameTo: target } : {}) },
+                    },
+                }, signal);
+                if (!res.ok) {
+                    throw new Error(res.error ?? 'write-file part failed');
+                }
+                offset = end;
+                if (!final)
+                    continue;
+                if (typeof res.sizeBytes === 'number' && res.sizeBytes !== content.length) {
+                    throw new Error(`vsock transport: write-file assembled ${res.sizeBytes} bytes for '${target}', expected ${content.length}`);
+                }
+                return;
+            }
+        }
+        catch (error) {
+            await this.discardWriteFileTemp(tempPath);
+            throw error;
+        }
+    }
+    /**
+     * Remove an abandoned part file. Best effort BY CONTRACT: the reason
+     * the sequence failed is frequently that the guest is unreachable, and
+     * a cleanup that threw would replace the caller's real error — the one
+     * that says why the write failed — with a second one about tidying up.
+     */
+    async discardWriteFileTemp(tempPath) {
+        try {
+            await this.request({
+                op: 'write-file',
+                body: { path: tempPath, content: '', encoding: 'base64', part: { discard: true } },
+            }, AbortSignal.timeout(WRITE_FILE_DISCARD_TIMEOUT_MS));
+        }
+        catch {
+            // Deliberately swallowed; see the doc comment.
+        }
+    }
+    /**
+     * Read a file out of the guest.
+     *
+     * Three shapes, decided by what the guest advertises and what the
+     * caller asked for:
+     *
+     *  - **No options, guest advertises {@link READ_FILE_STREAM_FEATURE}** —
+     *    served by {@link readFileStream} and concatenated here. Neither
+     *    side ever holds the base64 form or the JSON envelope whole, so the
+     *    ~384 MiB ceiling (V8 refuses a string longer than `0x1fffffe8`
+     *    characters, which is what a base64-encoded file of that size
+     *    needs) is gone and the guest's peak stops tracking the file's
+     *    size. The result is still one `Buffer`, because that is what this
+     *    method returns; a caller that must not hold even that iterates
+     *    {@link readFileStream} directly.
+     *  - **No options, guest does not advertise it** — today's single
+     *    whole-file reply, byte for byte, with today's ceiling.
+     *  - **`offset` and `length`** — one ranged `read-file`: a single round
+     *    trip for a single slice, which is the point of asking for one.
+     *    `offset` WITHOUT `length` is an unbounded tail, so it goes through
+     *    the stream instead; the guest refuses an uncapped range on
+     *    `read-file` for exactly that reason.
+     *
+     * A ranged read against a guest that does not advertise the feature is
+     * REFUSED with {@link AgentReadFileStreamUnsupportedError} rather than
+     * downgraded: such an agent ignores `offset`/`length` and answers with
+     * the whole file, which the caller would read as its slice.
+     */
+    async readFile(path, options) {
+        const signal = options?.signal;
+        const { offset, length } = options ?? {};
+        if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0)) {
+            throw new Error('readFile: offset must be a non-negative safe integer');
+        }
+        if (length !== undefined && (!Number.isSafeInteger(length) || length < 0)) {
+            throw new Error('readFile: length must be a non-negative safe integer');
+        }
+        const ranged = offset !== undefined || length !== undefined;
+        if (!(await this.guestSupportsReadFileStream(signal))) {
+            if (ranged) {
+                throw new AgentReadFileStreamUnsupportedError(`read-file: this guest does not advertise the '${READ_FILE_STREAM_FEATURE}' healthz feature, so it would ignore offset/length and answer with the whole file. Rebuild the guest image from this Namzu release, or read the file whole.`);
+            }
+            return await this.readFileWhole(path, signal);
+        }
+        if (length !== undefined) {
+            return await this.readFileRange(path, offset ?? 0, length, signal);
+        }
+        // Copied into ONE buffer sized from the guest's `meta` frame rather
+        // than collected and `Buffer.concat`ed: concat needs every chunk to
+        // still exist when the whole is built, so it costs twice the file at
+        // the moment it finishes — 2.3x measured on a 256 MiB read, against
+        // the 2x this method is held to. Here the peak is the file plus one
+        // chunk. The guest's own `end` frame is checked against what arrived
+        // (see {@link readFileFrames}), so a short stream rejects rather than
+        // handing back a buffer padded with whatever was in the allocation.
+        let out;
+        let at = 0;
+        for await (const chunk of this.readFileFrames(path, options, (meta) => {
+            // The one guest-supplied number this side turns into an
+            // allocation, so it is the one worth bounding. The guest derives
+            // `length` and `sizeBytes` from the same `stat` and never
+            // announces more of a file than the file has, so a `length` past
+            // `sizeBytes` is a guest this host should not be sizing a buffer
+            // from. `allocUnsafe` would refuse the extreme values on its own;
+            // this makes the refusal name what was wrong with the frame.
+            if (!Number.isSafeInteger(meta.sizeBytes) ||
+                meta.sizeBytes < 0 ||
+                !Number.isSafeInteger(meta.length) ||
+                meta.length < 0 ||
+                meta.length > meta.sizeBytes) {
+                throw new Error(`vsock transport: read-file-stream announced ${meta.length} bytes of a ${meta.sizeBytes}-byte file`);
+            }
+            out = Buffer.allocUnsafe(meta.length);
+        })) {
+            if (out === undefined) {
+                throw new Error('vsock transport: read-file-stream sent data before its meta frame');
+            }
+            if (at + chunk.byteLength > out.length) {
+                throw new Error(`vsock transport: read-file-stream delivered more than the ${out.length} bytes it announced`);
+            }
+            chunk.copy(out, at);
+            at += chunk.byteLength;
+        }
+        return out === undefined ? Buffer.alloc(0) : out.subarray(0, at);
+    }
+    /** Today's single whole-file reply, unchanged — see {@link readFile}. */
+    async readFileWhole(path, signal) {
+        const res = await this.request({ op: 'read-file', body: { path, encoding: 'base64' } }, signal);
         if (!res.ok || typeof res.content !== 'string') {
             throw new Error(res.error ?? 'read-file: no content');
         }
         return Buffer.from(res.content, 'base64');
     }
+    /**
+     * One bounded slice, in one round trip.
+     *
+     * The guest's own ceiling on a range (`NAMZU_AGENT_READ_FILE_RANGE_BYTES`,
+     * 1 MiB by default) is not mirrored here and deliberately so: it is the
+     * DEPLOYMENT's number, a host that guessed it would refuse ranges the
+     * guest would have served, and the guest's refusal already names the
+     * variable that raises it.
+     */
+    async readFileRange(path, offset, length, signal) {
+        const res = await this.request({ op: 'read-file', body: { path, encoding: 'base64', offset, length } }, signal);
+        if (!res.ok || typeof res.content !== 'string') {
+            throw new Error(res.error ?? 'read-file: no content');
+        }
+        return Buffer.from(res.content, 'base64');
+    }
+    /**
+     * Read a file as an ordered sequence of chunks, so neither side holds
+     * the whole of it.
+     *
+     * The guest sends `meta`, then `data` frames, then `end`, then the
+     * zero-length terminator — the same terminated-stream shape `execute`
+     * uses. Two bounds keep this side's heap flat while the guest's stays
+     * flat on its own: the socket is PAUSED once
+     * {@link READ_FILE_STREAM_HIGH_WATER_BYTES} of decoded chunks are
+     * waiting for a slow consumer, and the guest itself waits for each
+     * `data` frame to drain before it reads the next one.
+     *
+     * Leaving the loop early — `break`, an exception, an aborted
+     * `options.signal` — destroys the socket in the generator's `finally`,
+     * which is what makes the guest close its fd: it sees the connection go
+     * and releases the descriptor rather than leaking one per abandoned
+     * read.
+     *
+     * Refuses a guest that does not advertise
+     * {@link READ_FILE_STREAM_FEATURE} before dialing, with
+     * {@link AgentReadFileStreamUnsupportedError}.
+     */
+    readFileStream(path, options) {
+        return this.readFileFrames(path, options);
+    }
+    /**
+     * The stream itself. Private, and one argument wider than
+     * {@link readFileStream}: `onMeta` fires once, with the guest's `meta`
+     * frame, before the first chunk is yielded, which is how
+     * {@link readFile} sizes its destination buffer without a second round
+     * trip and without a public parameter nobody outside this class should
+     * pass.
+     */
+    async *readFileFrames(path, options, onMeta) {
+        const signal = options?.signal;
+        signal?.throwIfAborted();
+        if (!(await this.guestSupportsReadFileStream(signal))) {
+            throw new AgentReadFileStreamUnsupportedError(`read-file-stream: this guest does not advertise the '${READ_FILE_STREAM_FEATURE}' healthz feature, so it has no streamed read at all. Rebuild the guest image from this Namzu release, or use readFile for a file small enough to cross the wire in one frame.`);
+        }
+        const body = {
+            path,
+            ...(options?.offset !== undefined ? { offset: options.offset } : {}),
+            ...(options?.length !== undefined ? { length: options.length } : {}),
+        };
+        const payload = JSON.stringify(this.withCredential({ op: 'read-file-stream', body }));
+        this.assertPreauthBudget(payload);
+        const socket = await this.dial(signal);
+        const queue = [];
+        let queuedBytes = 0;
+        let paused = false;
+        let ended = false;
+        let failure;
+        let meta;
+        let received = 0;
+        let declared;
+        let wake;
+        const notify = () => {
+            const resume = wake;
+            wake = undefined;
+            resume?.();
+        };
+        const fail = (error) => {
+            if (failure || ended)
+                return;
+            failure = error;
+            notify();
+        };
+        const idle = new IdleTimer(this.readIdleTimeoutMs, () => fail(new Error(`vsock transport: read-file-stream idle timeout after ${this.readIdleTimeoutMs}ms`)));
+        const reader = new FrameReader();
+        let terminated = false;
+        const onAbort = () => fail(signalError(signal));
+        socket.on('data', (chunk) => {
+            // Once this read has failed — an abort, an idle timeout, a frame
+            // the guest should not have sent — nothing more will be yielded,
+            // so decoding what is still in flight only grows a queue no
+            // consumer will ever pull from.
+            if (failure)
+                return;
+            idle.bump();
+            let frames;
+            try {
+                frames = reader.push(chunk);
+            }
+            catch (err) {
+                fail(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            for (const frameBody of frames) {
+                if (terminated) {
+                    fail(new Error('vsock transport: read-file-stream emitted data after its terminator'));
+                    return;
+                }
+                if (frameBody.length === 0) {
+                    terminated = true;
+                    continue;
+                }
+                let event;
+                try {
+                    event = JSON.parse(frameBody);
+                }
+                catch (err) {
+                    fail(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                if (event.type === 'meta') {
+                    if (meta !== undefined) {
+                        fail(new Error('vsock transport: read-file-stream sent a second meta frame'));
+                        return;
+                    }
+                    meta = { sizeBytes: event.sizeBytes, offset: event.offset, length: event.length };
+                    declared = event.length;
+                    try {
+                        onMeta?.(meta);
+                    }
+                    catch (err) {
+                        fail(err instanceof Error ? err : new Error(String(err)));
+                        return;
+                    }
+                    continue;
+                }
+                if (event.type === 'data') {
+                    if (meta === undefined) {
+                        fail(new Error('vsock transport: read-file-stream sent data before its meta frame'));
+                        return;
+                    }
+                    const bytes = Buffer.from(event.data, 'base64');
+                    received += bytes.byteLength;
+                    queue.push(bytes);
+                    queuedBytes += bytes.byteLength;
+                    if (!paused && queuedBytes >= READ_FILE_STREAM_HIGH_WATER_BYTES) {
+                        paused = true;
+                        socket.pause();
+                        // The idle timer guards a guest that went silent, and
+                        // while WE are the reason it is silent it would be
+                        // measuring the consumer instead. A host draining a
+                        // gigabyte onto slow storage must not have its stream
+                        // torn down for reading carefully.
+                        idle.clear();
+                    }
+                    notify();
+                    continue;
+                }
+                if (event.type === 'end') {
+                    // The guest counts what it sent; this side counts what it
+                    // decoded. A mismatch is a lost or duplicated frame, and a
+                    // truncated file handed back as a whole one is exactly the
+                    // silent corruption a streamed read must not introduce.
+                    if (event.bytesSent !== received) {
+                        fail(new Error(`vsock transport: read-file-stream declared ${event.bytesSent} bytes and delivered ${received}`));
+                        return;
+                    }
+                    if (declared !== undefined && received !== declared) {
+                        fail(new Error(`vsock transport: read-file-stream announced ${declared} bytes and delivered ${received}`));
+                        return;
+                    }
+                    ended = true;
+                    notify();
+                    continue;
+                }
+                fail(new Error(event.error));
+                return;
+            }
+        });
+        socket.once('error', (err) => fail(err));
+        socket.once('close', () => {
+            if (ended || failure) {
+                notify();
+                return;
+            }
+            fail(new Error('vsock transport: read-file-stream socket closed before its end frame'));
+        });
+        if (signal?.aborted)
+            fail(signalError(signal));
+        else
+            signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            socket.write(frame(payload));
+            idle.bump();
+            for (;;) {
+                // Asked BEFORE the queue, not after it: an aborted read that
+                // goes on handing its consumer up to a high-water mark of
+                // already-decoded bytes before surfacing the rejection is not
+                // the prompt refusal `signal` promises. `ended` is the other
+                // way round — a finished stream owes the consumer every byte
+                // that arrived, so the queue drains first.
+                if (failure)
+                    throw failure;
+                const next = queue.shift();
+                if (next !== undefined) {
+                    queuedBytes -= next.byteLength;
+                    if (paused && queuedBytes < READ_FILE_STREAM_HIGH_WATER_BYTES) {
+                        paused = false;
+                        socket.resume();
+                        // Asking for bytes again restarts the clock that
+                        // measures whether they come.
+                        idle.bump();
+                    }
+                    yield next;
+                    continue;
+                }
+                if (ended)
+                    return;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+        }
+        finally {
+            idle.clear();
+            signal?.removeEventListener('abort', onAbort);
+            // Destroyed, never `end()`ed: the guest releases the file
+            // descriptor when the connection goes, and a half-close would
+            // leave it holding one for a read nobody is listening to.
+            socket.destroy();
+        }
+    }
+    /**
+     * Ask the guest whether it implements ranged and streamed reads.
+     * Cached for the transport's lifetime, exactly as
+     * {@link guestSupportsWriteFileParts} is, and for the same reason: a
+     * pod does not swap its agent binary while it is running.
+     */
+    async guestSupportsReadFileStream(signal) {
+        return (await this.guestFeatures(signal)).includes(READ_FILE_STREAM_FEATURE);
+    }
     /**
      * Open a real PTY owned by the in-VM agent.
      *
@@ -749,6 +1634,18 @@ export class VsockAgentTransport {
      * the session and its authenticated WebSocket attachment.
      */
     async openTerminal(options) {
+        return (await this.openSessionTerminal(options)).session;
+    }
+    /**
+     * The same open, handing back the session's own handles as well as the
+     * `TerminalSession` — the offset to come back at, and the detach that
+     * ends the attachment without signalling the program.
+     *
+     * Exactly one code path serves both: a persistent terminal is not a
+     * second kind of terminal, it is the same stream with a different answer
+     * to "what does a closed connection mean".
+     */
+    async openSessionTerminal(options) {
         const request = {
             ...(options.command !== undefined ? { command: options.command } : {}),
             ...(options.args !== undefined ? { args: options.args } : {}),
@@ -756,8 +1653,46 @@ export class VsockAgentTransport {
             ...(options.env !== undefined ? { env: { ...options.env } } : {}),
             cols: options.size.cols,
             rows: options.size.rows,
+            // Additive and optional: an agent that predates it ignores the
+            // field and echoes nothing back, and nothing below arms.
+            ...(this.heartbeatMs !== undefined ? { heartbeatMs: this.heartbeatMs } : {}),
+            // Equally additive, and only ever sent by a caller that checked
+            // the guest advertises `sessions` — see `protocol.ts`.
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            ...(options.persistent !== undefined ? { persistent: options.persistent } : {}),
         };
-        const openPayload = JSON.stringify(this.withCredential({ op: 'terminal', body: request }));
+        return await this.openTerminalStream({ op: 'terminal', body: request }, { detachable: options.persistent === true });
+    }
+    /**
+     * The framed, bidirectional stream behind every terminal this transport
+     * opens — the one the `terminal` op starts, and the one `attach-session`
+     * joins to a terminal that is already running.
+     *
+     * Parameterised rather than copied, because the two differ in exactly two
+     * places and everything else — the dial, the framing, the ready
+     * handshake, the read-idle timer that is cleared once a shell may
+     * legitimately go quiet, the heartbeat, the output buffering before the
+     * first listener, the kill grace — has to behave identically or a
+     * reattached terminal is a second terminal implementation with its own
+     * bugs. The two differences:
+     *
+     *  - **`detachable`.** For a connection-bound terminal a lost stream IS
+     *    the end of the program, and `exited` resolves with `exitCode: -1`
+     *    exactly as it always has. For a session attachment it is not: the
+     *    program is still running in the pod, so `exited` REJECTS with
+     *    {@link AgentSessionDetachedError} rather than reporting an exit that
+     *    did not happen. The rejection is pre-handled here so a caller that
+     *    only reads output cannot take the host process down with an
+     *    unhandled rejection.
+     *  - **the offsets.** A session stream's frames carry their place in the
+     *    guest's retained log, and {@link AgentTerminalStream.nextOffset} is
+     *    what a reattach resumes from. It is never computed from the decoded
+     *    text: a chunk that ends mid-character decodes wider than the bytes
+     *    it replaced.
+     */
+    async openTerminalStream(req, init) {
+        const askedHeartbeatMs = this.heartbeatMs;
+        const openPayload = JSON.stringify(this.withCredential(req));
         this.assertPreauthBudget(openPayload);
         const socket = await this.dial();
         return await new Promise((resolve, reject) => {
@@ -769,23 +1704,40 @@ export class VsockAgentTransport {
             let ready = false;
             let settled = false;
             let killTimer;
+            let readyEvent = { type: 'ready' };
+            let nextOffset;
+            /** Armed only if the guest echoed the interval — see `protocol.ts`. */
+            let liveness;
             let resolveExit;
-            const exited = new Promise((done) => {
+            let rejectExit;
+            const exited = new Promise((done, fail) => {
                 resolveExit = done;
+                rejectExit = fail;
             });
+            // See the header: a detachable stream's `exited` can reject, and
+            // the caller may legitimately never look at it.
+            if (init.detachable)
+                void exited.catch(() => undefined);
             const idle = new IdleTimer(this.readIdleTimeoutMs, () => {
                 finish(new Error(`vsock transport: terminal read idle timeout after ${this.readIdleTimeoutMs}ms`));
             });
-            const finish = (error, exit = { exitCode: -1 }) => {
+            const finish = (error, exit) => {
                 if (settled)
                     return;
                 settled = true;
                 idle.clear();
+                liveness?.stop();
                 if (killTimer)
                     clearTimeout(killTimer);
                 socket.destroy();
                 listeners.clear();
-                resolveExit(exit);
+                if (exit !== undefined)
+                    resolveExit(exit);
+                else if (init.detachable) {
+                    rejectExit(new AgentSessionDetachedError(nextOffset, `vsock transport: this attachment ended without the session's program exiting${error ? `: ${error.message}` : ''}. The program is still the guest's to run; attach again to go on reading it.`, { cause: error ?? undefined }));
+                }
+                else
+                    resolveExit({ exitCode: -1 });
                 if (!ready)
                     reject(error ?? new Error('terminal exited before readiness'));
             };
@@ -830,6 +1782,10 @@ export class VsockAgentTransport {
             socket.on('data', (chunk) => {
                 if (!ready)
                     idle.bump();
+                // Bytes are proof of life, not only a heartbeat and not only a
+                // whole frame: one large frame can take longer to arrive than the
+                // window, and the peer was plainly there while it was arriving.
+                liveness?.bump();
                 let payloads;
                 try {
                     payloads = reader.push(chunk);
@@ -839,6 +1795,11 @@ export class VsockAgentTransport {
                     return;
                 }
                 for (const payload of payloads) {
+                    // The guest ends a session stream with the same zero-length
+                    // terminator every other streamed op uses. Nothing follows it,
+                    // and the close below is what settles this stream.
+                    if (payload.length === 0)
+                        continue;
                     let event;
                     try {
                         event = JSON.parse(payload);
@@ -850,15 +1811,36 @@ export class VsockAgentTransport {
                     if (event.type === 'ready') {
                         if (!ready) {
                             ready = true;
+                            readyEvent = event;
+                            this.observeGuestReply(event);
+                            if (typeof event.nextOffset === 'number')
+                                nextOffset = event.nextOffset;
                             // Once ready, an interactive shell may legitimately sit silent
                             // for hours. Runtime/session TTL owns idle cleanup; a transport
                             // read timer would incorrectly kill a healthy quiet terminal.
+                            // The heartbeat below is what tells that shell from a peer
+                            // that vanished — armed only if the guest echoed an interval.
                             idle.clear();
-                            resolve(session);
+                            const beat = negotiatedHeartbeatMs(askedHeartbeatMs, event.heartbeatMs);
+                            if (beat !== undefined) {
+                                liveness = new StreamLiveness(beat, () => send({ type: 'heartbeat' }), () => finish(new Error(`vsock transport: terminal peer sent nothing for ${beat * STREAM_HEARTBEAT_MISS_LIMIT}ms and is treated as gone`)));
+                            }
+                            resolve({
+                                session,
+                                get ready() {
+                                    return readyEvent;
+                                },
+                                nextOffset: () => nextOffset,
+                                detach: () => finish(new Error('vsock transport: attachment released by the host')),
+                            });
                         }
                         continue;
                     }
+                    if (event.type === 'heartbeat')
+                        continue;
                     if (event.type === 'data') {
+                        if (typeof event.nextOffset === 'number')
+                            nextOffset = event.nextOffset;
                         if (listeners.size === 0) {
                             buffered.push(event.data);
                             bufferedBytes += Buffer.byteLength(event.data);
@@ -873,12 +1855,21 @@ export class VsockAgentTransport {
                         continue;
                     }
                     if (event.type === 'exit') {
+                        if (typeof event.nextOffset === 'number')
+                            nextOffset = event.nextOffset;
                         finish(null, {
                             exitCode: event.exitCode,
                             ...(event.signal !== undefined ? { signal: event.signal } : {}),
                         });
                         return;
                     }
+                    if (event.type === 'detached') {
+                        // The program did not exit: another attachment took the
+                        // session, or this one stopped draining. Either way this
+                        // stream ends and nothing in the guest was signalled.
+                        finish(new Error(`the guest ended this attachment (${event.reason})`));
+                        return;
+                    }
                     finish(new Error(event.error));
                     return;
                 }
@@ -889,6 +1880,24 @@ export class VsockAgentTransport {
             socket.write(frame(openPayload));
         });
     }
+    /**
+     * Join a terminal session that is already running in the guest, replaying
+     * what it printed from `fromOffset` before following it live.
+     *
+     * The guest allows ONE attachment per session and ends the previous one
+     * by name, so two host processes cannot interleave keystrokes into one
+     * shell. Nothing here signals the program: releasing this stream is a
+     * detach, and ending the session is `kill-session`.
+     */
+    async attachSessionTerminal(request) {
+        return await this.openTerminalStream({
+            op: 'attach-session',
+            body: {
+                ...request,
+                ...(this.heartbeatMs !== undefined ? { heartbeatMs: this.heartbeatMs } : {}),
+            },
+        }, { detachable: true });
+    }
     /** Open one TCP stream to a service listening on guest loopback. */
     async openTcpConnection(options) {
         if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65_535) {
@@ -898,7 +1907,13 @@ export class VsockAgentTransport {
         if (host !== '127.0.0.1' && host !== '::1') {
             throw new Error('firecracker TCP connections are restricted to guest loopback');
         }
-        const request = { host, port: options.port };
+        const askedHeartbeatMs = this.heartbeatMs;
+        const request = {
+            host,
+            port: options.port,
+            // Additive and optional, exactly as on `terminal` — see `openTerminal`.
+            ...(askedHeartbeatMs !== undefined ? { heartbeatMs: askedHeartbeatMs } : {}),
+        };
         const openPayload = JSON.stringify(this.withCredential({ op: 'tcp-connect', body: request }));
         this.assertPreauthBudget(openPayload);
         const socket = await this.dial();
@@ -909,6 +1924,8 @@ export class VsockAgentTransport {
             let bufferedBytes = 0;
             let ready = false;
             let settled = false;
+            /** Armed only if the guest echoed the interval — see `protocol.ts`. */
+            let liveness;
             let resolveClosed;
             const closed = new Promise((done) => {
                 resolveClosed = done;
@@ -921,6 +1938,7 @@ export class VsockAgentTransport {
                     return;
                 settled = true;
                 idle.clear();
+                liveness?.stop();
                 socket.destroy();
                 listeners.clear();
                 resolveClosed();
@@ -944,10 +1962,14 @@ export class VsockAgentTransport {
                 },
                 pause() {
                     socket.pause();
+                    // Paused by this caller, so nothing arriving is this caller's
+                    // doing and not the peer's — see `StreamLiveness.suspend`.
+                    liveness?.suspend();
                 },
                 resume() {
                     if (!settled)
                         socket.resume();
+                    liveness?.resume();
                 },
                 onData(listener) {
                     listeners.add(listener);
@@ -972,6 +1994,8 @@ export class VsockAgentTransport {
             socket.on('data', (chunk) => {
                 if (!ready)
                     idle.bump();
+                // Bytes, not frames — see the reader in `openTerminal` above.
+                liveness?.bump();
                 let payloads;
                 try {
                     payloads = reader.push(chunk);
@@ -992,11 +2016,20 @@ export class VsockAgentTransport {
                     if (event.type === 'ready') {
                         if (!ready) {
                             ready = true;
+                            this.observeGuestReply(event);
                             idle.clear();
+                            const beat = negotiatedHeartbeatMs(askedHeartbeatMs, event.heartbeatMs);
+                            if (beat !== undefined) {
+                                liveness = new StreamLiveness(beat, () => {
+                                    send({ type: 'heartbeat' });
+                                }, () => finish(null));
+                            }
                             resolve(connection);
                         }
                         continue;
                     }
+                    if (event.type === 'heartbeat')
+                        continue;
                     if (event.type === 'data') {
                         const bytes = Buffer.from(event.data, 'base64');
                         if (listeners.size === 0) {
@@ -1048,6 +2081,97 @@ class LineReader {
         return r;
     }
 }
+/**
+ * The host half of the negotiated stream heartbeat (`protocol.ts`'s
+ * `StreamHeartbeat`): send one every interval, and give up on a peer that
+ * has sent nothing for {@link STREAM_HEARTBEAT_MISS_LIMIT} of them.
+ *
+ * Constructed only once the guest ECHOED an interval, so a transport that
+ * asked for no heartbeat, or one talking to an agent that predates the
+ * field, never builds one and writes no frame an older peer could not read.
+ *
+ * The watchdog polls at a quarter of the interval rather than at the
+ * interval, so a dead stream is noticed within the three intervals plus at
+ * most one poll tick rather than within four. Both timers are unref'd: a
+ * host process with nothing else to do should exit, not be held open by a
+ * terminal it forgot about.
+ */
+class StreamLiveness {
+    intervalMs;
+    send;
+    onDead;
+    sendTimer;
+    watchTimer;
+    lastSeen = Date.now();
+    watching = true;
+    stopped = false;
+    constructor(intervalMs, send, onDead) {
+        this.intervalMs = intervalMs;
+        this.send = send;
+        this.onDead = onDead;
+        this.sendTimer = setInterval(() => {
+            if (!this.stopped)
+                this.send();
+        }, intervalMs);
+        this.sendTimer.unref?.();
+        this.watchTimer = setInterval(() => this.check(), Math.max(10, Math.floor(intervalMs / 4)));
+        this.watchTimer.unref?.();
+    }
+    /** Any BYTES from the peer count, not just a heartbeat and not a whole frame. */
+    bump() {
+        this.lastSeen = Date.now();
+    }
+    /**
+     * This side has paused reading for backpressure, so silence is its own
+     * doing and the peer's frames are waiting in the kernel. Not counted.
+     */
+    suspend() {
+        this.watching = false;
+    }
+    resume() {
+        if (this.stopped)
+            return;
+        this.watching = true;
+        this.lastSeen = Date.now();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.sendTimer)
+            clearInterval(this.sendTimer);
+        if (this.watchTimer)
+            clearInterval(this.watchTimer);
+        this.sendTimer = undefined;
+        this.watchTimer = undefined;
+    }
+    check() {
+        if (this.stopped || !this.watching)
+            return;
+        if (Date.now() - this.lastSeen < this.intervalMs * STREAM_HEARTBEAT_MISS_LIMIT)
+            return;
+        this.stop();
+        this.onDead();
+    }
+}
+/**
+ * The interval the guest echoed back, or undefined when this side asked for
+ * no heartbeat or the guest did not answer with one. An agent that predates
+ * the field echoes nothing, which is exactly what keeps an older image's
+ * streams behaving as they always did.
+ *
+ * The echo is clamped into `[MIN_STREAM_HEARTBEAT_MS, asked x
+ * STREAM_HEARTBEAT_MAX_ECHO_FACTOR]`, because it is a number from the pod and
+ * this side times its own watchdog with it. A guest that clamps to the same
+ * floor — which is what this repository's agent does — always echoes a value
+ * already inside the band, so nothing about the honest case changes.
+ */
+function negotiatedHeartbeatMs(asked, echoed) {
+    if (asked === undefined)
+        return undefined;
+    if (typeof echoed !== 'number' || !Number.isFinite(echoed) || echoed <= 0)
+        return undefined;
+    const ceiling = Math.max(asked, MIN_STREAM_HEARTBEAT_MS) * STREAM_HEARTBEAT_MAX_ECHO_FACTOR;
+    return Math.min(ceiling, Math.max(MIN_STREAM_HEARTBEAT_MS, Math.floor(echoed)));
+}
 /** Resets a timer on every byte; fires `onIdle` after `ms` of silence. */
 class IdleTimer {
     ms;
@@ -1089,6 +2213,29 @@ function delay(ms, signal) {
         signal?.addEventListener('abort', abort, { once: true });
     });
 }
+/** Length of `n` raw bytes base64-encoded, padding included. Exact. */
+function base64Length(n) {
+    return 4 * Math.ceil(n / 3);
+}
+/**
+ * The temp file a part sequence for `target` writes into: a SIBLING of the
+ * target, so the finishing `rename` is a within-directory rename on one
+ * filesystem (atomic) rather than a cross-device copy, and so the path
+ * passes the guest's workspace jail exactly as the target does.
+ *
+ * Split on `/` rather than through `node:path` because the path is the
+ * GUEST's, which is always POSIX — a host running the orchestrator on
+ * Windows must not rewrite it with backslashes. The target's own basename
+ * rides along, truncated, so an operator who finds one of these knows what
+ * it was becoming; the uuid is what makes two concurrent writers to the
+ * same target use two different temp files.
+ */
+function writeFilePartTempPath(target) {
+    const slash = target.lastIndexOf('/');
+    const dir = slash < 0 ? '' : target.slice(0, slash + 1);
+    const base = (slash < 0 ? target : target.slice(slash + 1)).slice(0, 96);
+    return `${dir}.namzu-write-${randomUUID()}-${base}.part`;
+}
 function signalError(signal) {
     if (signal?.reason instanceof Error)
         return signal.reason;