@ricsam/r5d-worker 0.0.171 → 0.0.173

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.171",
+  "version": "0.0.173",
   "type": "commonjs"
 }

package/dist/mjs/internal-r5dctl.cjs

@@ -20605,7 +20605,7 @@ function resolveEntrypointPath(entrypoint) {
   }
 }
 function getR5dctlVersion() {
-  if (true) return "0.0.171";
+  if (true) return "0.0.173";
   const entrypoint = process.argv[1] ? resolveEntrypointPath(process.argv[1]) : null;
   let current = entrypoint ? import_node_path2.default.dirname(entrypoint) : process.cwd();
   for (let index = 0; index < 12; index += 1) {

package/dist/mjs/main.mjs

@@ -7,7 +7,7 @@ import { startManagerRpc } from "./runtime/releases/rpc-main.mjs";
 import { ManagerRpcConfig } from "./runtime/releases/rpc-protocol.mjs";
 const args = process.argv.slice(2);
 if (args.includes("--version")) {
-  console.log(`r5d-worker ${true ? "0.0.171" : "development"}`);
+  console.log(`r5d-worker ${true ? "0.0.173" : "development"}`);
 } else if (!args.length || args.includes("--help")) {
   console.log(
     "Usage: r5d-worker start --label <label> [--root <dir>] [--base-url <url>] [--token <worker-token>]\n       r5d-worker executor /absolute/private/config.json\n       r5d-worker manager /absolute/private/config.json\n\nRun independently supervised durable runtime services. Provision configuration with r5dinfra."
@@ -15,7 +15,7 @@ if (args.includes("--version")) {
 } else if (args[0] === "start") {
   const runtime = await startPersonalWorker(
     parsePersonalWorkerOptions(args.slice(1)),
-    true ? "0.0.171" : "development"
+    true ? "0.0.173" : "development"
   );
   console.log(`Worker connected: ${runtime.resourceId}`);
   let closing = false;

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.171",
+  "version": "0.0.173",
   "type": "module"
 }

package/dist/mjs/personal/client.mjs

@@ -3,6 +3,7 @@ import os from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { promises as fs, openSync, closeSync } from "node:fs";
 import { Database } from "bun:sqlite";
+import { z } from "zod";
 import { canonicalJson } from "@ricsam/r5d-api/runtime-protocol";
 import { privateDirectory, readPrivateJson } from "../runtime/storage.mjs";
 import { openPersonalWorkerRuntime, PersonalWorkerGrant } from "./runtime.mjs";
@@ -10,12 +11,14 @@ import { installCliUpdate } from "../cli-update.mjs";
 import { WorkspaceError } from "../runtime/workspace/contracts.mjs";
 import { PersonalActionScheduler } from "./action-scheduler.mjs";
 import { resolvePersonalCliEntrypoint } from "./cli-entrypoint.mjs";
+import { startTerminalStream } from "./terminal-stream.mjs";
+import { TERMINAL_STREAM_CAPABILITY } from "./terminal-stream-protocol.mjs";
 class PersonalResponseError extends Error {
-  constructor(code, status, rejectedBeforeAdmission) {
+  constructor(code, status, rejectedBeforeAdmission2) {
     super(`Personal worker request failed (${status})`);
     this.code = code;
     this.status = status;
-    this.rejectedBeforeAdmission = rejectedBeforeAdmission;
+    this.rejectedBeforeAdmission = rejectedBeforeAdmission2;
   }
   code;
   status;
@@ -62,6 +65,8 @@ function safeError(error) {
   const value = error.code;
   return typeof value === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(value) ? value : "personal_operation_unknown";
 }
+const rejectedBeforeAdmission = (error) => error?.rejectedBeforeAdmission === true;
+const CliUpdateRequest = z.object({ kind: z.literal("update-clis"), userId: z.string(), command: z.object({ version: z.string() }).passthrough() }).passthrough();
 async function startPersonalWorker(options, version) {
   const key = createHash("sha256").update(canonicalJson([options.baseUrl, options.label])).digest("hex").slice(0, 32), root = path.join(options.root, "personal", key);
   privateDirectory(root);
@@ -103,7 +108,7 @@ async function startPersonalWorker(options, version) {
     platform: process.platform,
     arch: process.arch,
     hostname: os.hostname(),
-    capabilities: { updateClis: true, durableWorkspace: true, outerWorkspace: true, fileWalk: true, fileSearch: true }
+    capabilities: { updateClis: true, durableWorkspace: true, outerWorkspace: true, fileWalk: true, fileSearch: true, [TERMINAL_STREAM_CAPABILITY]: true }
   });
   const grant = PersonalWorkerGrant.parse(
     await request("/api/personal/resources/register", { kind: "worker", ...identity, label: options.label, metadata: metadata() })
@@ -152,10 +157,11 @@ async function startPersonalWorker(options, version) {
     if (!previous || state === "pending") {
       if (!previous) ledger.query("INSERT INTO actions VALUES(?,?,'pending',NULL)").run(input.id, input.requestHash);
       try {
-        if (input.request.kind === "update-clis") {
-          const command = input.request.command;
-          if (input.request.userId !== grant.userId || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(command.version))
+        if (input.request?.kind === "update-clis") {
+          const update = CliUpdateRequest.safeParse(input.request);
+          if (!update.success || update.data.userId !== grant.userId || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(update.data.command.version))
             throw new Error("Invalid CLI update");
+          const command = update.data.command;
           if (previous) throw new Error("Inspect interrupted CLI installation before retrying");
           result = await installCliUpdate({
             workerPackageSpec: `@ricsam/r5d-worker@${command.version}`,
@@ -166,8 +172,8 @@ async function startPersonalWorker(options, version) {
         } else result = await runtime.dispatch(input.request);
         state = "completed";
       } catch (error) {
-        state = error.rejectedBeforeAdmission === true ? "rejected" : "unknown";
-        result = { error: safeError(error), ...error.rejectedBeforeAdmission === true ? { rejectedBeforeAdmission: true } : {} };
+        state = rejectedBeforeAdmission(error) ? "rejected" : "unknown";
+        result = { error: safeError(error), ...rejectedBeforeAdmission(error) ? { rejectedBeforeAdmission: true } : {} };
       }
       ledger.query("UPDATE actions SET state=?,result=? WHERE id=?").run(state, canonicalJson(result), input.id);
     }
@@ -177,6 +183,10 @@ async function startPersonalWorker(options, version) {
     process.stderr.write(`[r5d-worker] ${safeError(error)}; retaining original action for reconnect
 `);
   });
+  const streamUrl = new URL(`${endpoint}/stream`, options.baseUrl);
+  streamUrl.protocol = streamUrl.protocol === "http:" ? "ws:" : "wss:";
+  streamUrl.searchParams.set("instanceId", identity.instanceId);
+  const terminalStream = startTerminalStream({ url: streamUrl.toString(), credential: options.credential, version, runtime });
   const loop = (async () => {
     while (!stopped) {
       try {
@@ -200,6 +210,7 @@ async function startPersonalWorker(options, version) {
     root,
     async close() {
       stopped = true;
+      await terminalStream.close();
       await loop;
       await scheduler.drain();
       await runtime.close();

package/dist/mjs/personal/runtime.mjs

@@ -375,7 +375,7 @@ exec ${quote(executable)} ${quote(cli)} "$@"
         if (command.method === "search") return authority.searchFiles(identity, WorkspaceSearch.parse(command));
       }
       if (request.kind === "terminal") {
-        await authority.ensureHydrated(identity);
+        if (command.method === "open" || command.method === "start") await authority.ensureHydrated(identity);
         if (command.method === "open" || command.method === "start") {
           const argv = command.method === "open" ? ["/bin/bash", "--noprofile", "--norc", ...command.command ? ["-c", command.command] : []] : ["/bin/sh", "-c", command.command];
           return {
@@ -472,12 +472,23 @@ exec ${quote(executable)} ${quote(cli)} "$@"
       }
       throw new WorkspaceError("invalid_request", "Unsupported personal workspace operation");
     }
+    async function subscribeTerminal(input, handlers) {
+      await approve(Workbench.parse(input.workbench));
+      const identity = { userId: grant.userId, sessionId: RuntimeId.parse(input.sessionId) };
+      return authority.subscribe(identity, { ...identity, operationId: RuntimeId.parse(input.operationId), fence: current.workerFence }, input.offset, handlers);
+    }
+    async function terminalInput(input) {
+      const identity = { userId: grant.userId, sessionId: RuntimeId.parse(input.sessionId) };
+      return authority.streamInput(identity, { ...identity, operationId: RuntimeId.parse(input.operationId), fence: current.workerFence }, input.data, input.resize);
+    }
     return {
       grant,
       renew,
       dispatch,
       authority,
       synchronize,
+      subscribeTerminal,
+      terminalInput,
       async close() {
         closing = true;
         clearInterval(publicationTimer);

package/dist/mjs/personal/terminal-stream-protocol.mjs

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
+const TERMINAL_STREAM_CAPABILITY = "terminal-stream-v1";
+const STREAM_INPUT_MAX_CHARS = 1e5;
+const STREAM_HEARTBEAT_MS = 25e3;
+const Size = z.object({ cols: z.number().int().min(1).max(1e3), rows: z.number().int().min(1).max(1e3) }).strict();
+const Input = z.string().max(STREAM_INPUT_MAX_CHARS).refine((s) => !s.includes("\0"), "NUL is not allowed");
+const StreamWorkbench = z.object({
+  id: z.string().min(1).max(200),
+  repositoryId: z.string().min(1).max(200),
+  branch: z.string().min(1).max(400),
+  sessionId: RuntimeId,
+  rootProfile: z.enum(["account", "project"]).default("project"),
+  namespace: z.string().max(100).optional(),
+  projectName: z.string().max(100).optional(),
+  baseCommitHash: z.string().max(64).optional()
+}).strict();
+const ServerToWorkerFrame = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("attach"),
+    streamId: RuntimeId,
+    sessionId: RuntimeId,
+    operationId: RuntimeId,
+    offset: z.number().int().nonnegative(),
+    workbench: StreamWorkbench
+  }).strict(),
+  z.object({ type: z.literal("input"), streamId: RuntimeId, data: Input.optional(), resize: Size.optional() }).strict(),
+  z.object({ type: z.literal("detach"), streamId: RuntimeId }).strict(),
+  z.object({ type: z.literal("ping") }).strict()
+]);
+const WorkerToServerFrame = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("hello"), version: z.string().max(100), capabilities: z.array(z.string().max(100)).max(32) }).strict(),
+  z.object({ type: z.literal("attached"), streamId: RuntimeId, offset: z.number().int().nonnegative() }).strict(),
+  z.object({ type: z.literal("output"), streamId: RuntimeId, offset: z.number().int().nonnegative(), base64: z.string().max(2e5) }).strict(),
+  z.object({ type: z.literal("exit"), streamId: RuntimeId, exitCode: z.number().int().nullable(), signal: z.string().max(40).nullable() }).strict(),
+  z.object({ type: z.literal("error"), streamId: RuntimeId, code: z.string().regex(/^[a-zA-Z0-9_-]{1,100}$/) }).strict(),
+  z.object({ type: z.literal("detached"), streamId: RuntimeId, code: z.string().regex(/^[a-zA-Z0-9_-]{1,100}$/).optional() }).strict(),
+  z.object({ type: z.literal("pong") }).strict()
+]);
+const BrowserToServerFrame = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("input"), data: Input }).strict(),
+  z.object({ type: z.literal("resize"), cols: Size.shape.cols, rows: Size.shape.rows }).strict(),
+  z.object({ type: z.literal("ping") }).strict(),
+  z.object({ type: z.literal("pong") }).strict()
+]);
+function completeUtf8Prefix(bytes) {
+  let count = bytes.length;
+  let start = count - 1;
+  while (start >= 0 && (bytes[start] & 192) === 128) start--;
+  if (start >= 0) {
+    const lead = bytes[start];
+    const width = lead >= 240 ? 4 : lead >= 224 ? 3 : lead >= 192 ? 2 : 1;
+    if (count - start < width) count = start;
+  }
+  return count;
+}
+export {
+  BrowserToServerFrame,
+  STREAM_HEARTBEAT_MS,
+  STREAM_INPUT_MAX_CHARS,
+  ServerToWorkerFrame,
+  StreamWorkbench,
+  TERMINAL_STREAM_CAPABILITY,
+  WorkerToServerFrame,
+  completeUtf8Prefix
+};

package/dist/mjs/personal/terminal-stream.mjs

@@ -0,0 +1,161 @@
+import {
+  completeUtf8Prefix,
+  ServerToWorkerFrame,
+  TERMINAL_STREAM_CAPABILITY
+} from "./terminal-stream-protocol.mjs";
+const DEFAULT_BACKOFF_MS = [1e3, 2e3, 5e3, 1e4, 2e4];
+const safeCode = (error) => {
+  const value = error?.code;
+  return typeof value === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(value) ? value : "terminal_stream_failed";
+};
+function startTerminalStream(options) {
+  const Socket = WebSocket;
+  const connect = options.connect ?? ((url, headers) => new Socket(url, { headers }));
+  const log = options.log ?? ((line) => process.stderr.write(`[r5d-worker] ${line}
+`));
+  const backoff = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+  let socket;
+  let stopped = false;
+  let attempt = 0;
+  let timer;
+  const streams = /* @__PURE__ */ new Map();
+  const send = (ws, frame) => {
+    try {
+      ws.send(JSON.stringify(frame));
+    } catch {
+    }
+  };
+  async function attach(ws, frame) {
+    const stream = { sessionId: frame.sessionId, operationId: frame.operationId, close: () => {
+    }, pending: Buffer.alloc(0), closed: false };
+    try {
+      const subscription = await options.runtime.subscribeTerminal(
+        { sessionId: frame.sessionId, workbench: frame.workbench, operationId: frame.operationId, offset: frame.offset },
+        {
+          frame: (event) => {
+            if (stream.closed) return;
+            if (event.event === "output") {
+              const bytes = Buffer.concat([stream.pending, Buffer.from(event.base64, "base64")]);
+              const count = completeUtf8Prefix(bytes);
+              stream.pending = bytes.subarray(count);
+              if (count) send(ws, { type: "output", streamId: frame.streamId, offset: event.offset - stream.pending.length, base64: bytes.subarray(0, count).toString("base64") });
+              return;
+            }
+            if (stream.pending.length) {
+              send(ws, { type: "output", streamId: frame.streamId, offset: event.receipt.stdoutBytes, base64: stream.pending.toString("base64") });
+              stream.pending = Buffer.alloc(0);
+            }
+            send(ws, { type: "exit", streamId: frame.streamId, exitCode: event.receipt.exitCode, signal: event.receipt.signal });
+          },
+          close: (error) => {
+            if (stream.closed) return;
+            stream.closed = true;
+            streams.delete(frame.streamId);
+            send(ws, { type: "detached", streamId: frame.streamId, ...error ? { code: error.code } : {} });
+          }
+        }
+      );
+      stream.close = () => {
+        if (stream.closed) return;
+        stream.closed = true;
+        streams.delete(frame.streamId);
+        subscription.close();
+      };
+      if (stream.closed) {
+        subscription.close();
+        return null;
+      }
+      send(ws, { type: "attached", streamId: frame.streamId, offset: subscription.offset });
+      return stream;
+    } catch (error) {
+      streams.delete(frame.streamId);
+      send(ws, { type: "error", streamId: frame.streamId, code: safeCode(error) });
+      return null;
+    }
+  }
+  async function handle(ws, text) {
+    const parsed = ServerToWorkerFrame.safeParse(JSON.parse(text));
+    if (!parsed.success) return;
+    const frame = parsed.data;
+    if (frame.type === "ping") return send(ws, { type: "pong" });
+    if (frame.type === "attach") {
+      if (streams.has(frame.streamId)) return;
+      streams.set(frame.streamId, attach(ws, frame));
+      return;
+    }
+    const pending = streams.get(frame.streamId);
+    if (frame.type === "detach") {
+      if (!pending) return;
+      const stream2 = await pending;
+      stream2?.close();
+      send(ws, { type: "detached", streamId: frame.streamId });
+      return;
+    }
+    if (!pending) return send(ws, { type: "error", streamId: frame.streamId, code: "stream_not_attached" });
+    const stream = await pending;
+    if (!stream || stream.closed) return send(ws, { type: "error", streamId: frame.streamId, code: "stream_not_attached" });
+    try {
+      await options.runtime.terminalInput({
+        sessionId: stream.sessionId,
+        operationId: stream.operationId,
+        ...frame.data !== void 0 ? { data: frame.data } : {},
+        ...frame.resize ? { resize: frame.resize } : {}
+      });
+    } catch (error) {
+      send(ws, { type: "error", streamId: frame.streamId, code: safeCode(error) });
+    }
+  }
+  function open() {
+    if (stopped) return;
+    let ws;
+    try {
+      ws = connect(options.url, { authorization: `Bearer ${options.credential}` });
+    } catch (error) {
+      log(`terminal stream unavailable: ${safeCode(error)}`);
+      schedule();
+      return;
+    }
+    socket = ws;
+    ws.onopen = () => {
+      attempt = 0;
+      send(ws, { type: "hello", version: options.version, capabilities: [TERMINAL_STREAM_CAPABILITY] });
+    };
+    ws.onmessage = (event) => {
+      void handle(ws, String(event.data)).catch((error) => log(`terminal stream frame failed: ${safeCode(error)}`));
+    };
+    ws.onerror = () => {
+    };
+    ws.onclose = () => {
+      if (socket !== ws) return;
+      socket = void 0;
+      for (const pending of streams.values()) void pending.then((stream) => stream?.close());
+      streams.clear();
+      schedule();
+    };
+  }
+  function schedule() {
+    if (stopped) return;
+    const delay = backoff[Math.min(attempt, backoff.length - 1)];
+    attempt++;
+    timer = setTimeout(open, delay);
+    timer.unref?.();
+  }
+  open();
+  return {
+    async close() {
+      stopped = true;
+      clearTimeout(timer);
+      const current = socket;
+      socket = void 0;
+      for (const pending of streams.values()) void pending.then((stream) => stream?.close());
+      streams.clear();
+      try {
+        current?.close(1e3, "worker stopping");
+      } catch {
+      }
+    }
+  };
+}
+export {
+  startTerminalStream
+};

package/dist/mjs/runtime/client.mjs

@@ -12,7 +12,7 @@ class HostExecutorClient {
   constructor(config) {
     this.config = AdapterConfig.parse(config);
   }
-  request(command) {
+  frame(command) {
     const stat = lstatSync(this.config.socketPath);
     if (!stat.isSocket() || stat.uid !== process.getuid?.() || stat.mode & 63) throw new ExecutorError("insecure_socket");
     const request = JSON.stringify({
@@ -23,6 +23,59 @@ class HostExecutorClient {
       command
     }) + "\n";
     if (Buffer.byteLength(request) > MAX_FRAME_BYTES) throw new ExecutorError("request_too_large");
+    return request;
+  }
+  /** Keeps its socket open: the admission reply resolves the promise, then every
+   * newline-delimited frame reaches `handlers.frame` until either side closes. */
+  subscribe(run, offset, handlers) {
+    const request = this.frame({ method: "subscribe", run, offset });
+    return new Promise((resolve, reject) => {
+      const socket = createConnection(this.config.socketPath);
+      let buffer = Buffer.alloc(0);
+      let admitted = false;
+      let closed = false;
+      const finish = (error) => {
+        if (closed) return;
+        closed = true;
+        socket.destroy();
+        if (!admitted) reject(error ?? new ExecutorError("transport_outcome_unknown"));
+        else handlers.close(error);
+      };
+      socket.setTimeout(this.config.timeoutMs, () => {
+        if (!admitted) finish(new ExecutorError("transport_outcome_unknown"));
+      });
+      socket.once("connect", () => socket.write(request));
+      socket.on("error", () => finish(new ExecutorError("transport_outcome_unknown")));
+      socket.once("close", () => finish(admitted ? void 0 : new ExecutorError("transport_outcome_unknown")));
+      socket.on("data", (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        if (buffer.length > MAX_FRAME_BYTES) return finish(new ExecutorError("invalid_response"));
+        for (; ; ) {
+          const newline = buffer.indexOf(10);
+          if (newline < 0) return;
+          const line = buffer.subarray(0, newline).toString("utf8");
+          buffer = buffer.subarray(newline + 1);
+          let parsed;
+          try {
+            parsed = JSON.parse(line);
+          } catch {
+            return finish(new ExecutorError("invalid_response"));
+          }
+          if (!admitted) {
+            if (parsed.ok !== true || !parsed.result) return finish(new ExecutorError(parsed.error?.code ?? "invalid_response"));
+            admitted = true;
+            socket.setTimeout(0);
+            resolve({ ...parsed.result, close: () => finish() });
+            continue;
+          }
+          if (parsed.event !== "output" && parsed.event !== "exit") return finish(new ExecutorError("invalid_response"));
+          handlers.frame(parsed);
+        }
+      });
+    });
+  }
+  request(command) {
+    const request = this.frame(command);
     return new Promise((resolve, reject) => {
       const socket = createConnection(this.config.socketPath);
       let buffer = Buffer.alloc(0);
@@ -89,6 +142,10 @@ class HostExecutorClient {
   cancel(run, actionId) {
     return this.request({ method: "cancel", run, actionId });
   }
+  /** Live PTY input without a durable action: nothing to replay, nothing to poison. */
+  input(run, data, resize) {
+    return this.request({ method: "input", run, ...data !== void 0 ? { data } : {}, ...resize ? { resize } : {} });
+  }
 }
 export {
   HostExecutorClient

package/dist/mjs/runtime/daemon.mjs

@@ -55,14 +55,37 @@ async function startHostExecutor(input) {
         socket.end(JSON.stringify({ ok: false, error: { code: "invalid_request" } }) + "\n");
         return;
       }
-      const authorityHint = request?.command?.method === "authority";
+      const method = request?.command?.method;
+      const authorityHint = method === "authority";
       if (pending >= 72 || pending >= 64 && !authorityHint) {
         socket.end(JSON.stringify({ ok: false, error: { code: "ipc_busy" } }) + "\n");
         return;
       }
       pending++;
-      void executor.handle(request).then(
-        (result) => socket.end(JSON.stringify({ ok: true, result }) + "\n"),
+      let sink;
+      let ready;
+      if (method === "subscribe") {
+        socket.setTimeout(0);
+        sink = {
+          ready: new Promise((resolve) => {
+            ready = resolve;
+          }),
+          send: (frame) => new Promise((resolve, reject) => {
+            if (socket.destroyed || socket.writableEnded) return reject(new ExecutorError("stream_closed"));
+            if (socket.write(JSON.stringify(frame) + "\n")) resolve();
+            else socket.once("drain", resolve);
+          }),
+          end: () => socket.end()
+        };
+        const bound = sink;
+        socket.once("close", () => executor.unsubscribe(bound));
+      }
+      void executor.handle(request, sink).then(
+        (result) => {
+          if (!sink) return socket.end(JSON.stringify({ ok: true, result }) + "\n");
+          socket.write(JSON.stringify({ ok: true, result }) + "\n");
+          ready();
+        },
         (error) => socket.end(
           JSON.stringify({
             ok: false,

package/dist/mjs/runtime/executor.mjs

@@ -16,6 +16,8 @@ import {
   ExecutorError,
   ExecutorRequest,
   EXECUTOR_CAPABILITY,
+  EXECUTOR_STREAM_CAPABILITY,
+  STREAM_CHUNK_BYTES,
   ShellPayload
 } from "./protocol.mjs";
 import { ExecutorStore, privateDirectory } from "./storage.mjs";
@@ -39,7 +41,7 @@ class HostExecutor {
       releaseId: this.config.releaseId,
       role: "executor",
       protocol: { min: 1, max: 1 },
-      capabilities: [EXECUTOR_CAPABILITY, ...nativePty ? ["host-pty-v1"] : []]
+      capabilities: [EXECUTOR_CAPABILITY, EXECUTOR_STREAM_CAPABILITY, ...nativePty ? ["host-pty-v1"] : []]
     };
     this.leaseTimer = setInterval(() => {
       const authority = this.authority();
@@ -58,6 +60,7 @@ class HostExecutor {
   adapters;
   hello;
   active = /* @__PURE__ */ new Map();
+  subscribers = /* @__PURE__ */ new Map();
   leaseTimer;
   closing = false;
   poisoned = false;
@@ -65,11 +68,13 @@ class HostExecutor {
   /** Authority is synchronous and authenticated; never queue lease renewal behind a blocked OS write.
    * Resource commands retain one ordered admission/action boundary. Commands already admitted may
    * complete after promotion; queued commands and yielded admission hashes must recheck the fence.
+   * The live terminal channel (subscribe, input) carries no durable action and
+   * never waits behind that boundary: a keystroke is not queued behind a spawn.
    */
-  handle(input) {
+  handle(input, sink) {
     try {
       const request = ExecutorRequest.parse(input);
-      if (request.command.method === "authority") return this.dispatch(request);
+      if (["authority", "subscribe", "input"].includes(request.command.method)) return this.dispatch(request, sink);
     } catch (error) {
       return Promise.reject(error);
     }
@@ -78,6 +83,49 @@ class HostExecutor {
     });
     return task;
   }
+  /** Drops a subscription whose transport closed. Idempotent. */
+  unsubscribe(sink) {
+    const subscriber = this.subscribers.get(sink);
+    if (!subscriber) return;
+    subscriber.closed = true;
+    this.subscribers.delete(sink);
+  }
+  notify(operationId) {
+    for (const subscriber of this.subscribers.values()) if (subscriber.operationId === operationId) void this.pump(subscriber);
+  }
+  async pump(subscriber) {
+    subscriber.dirty = true;
+    if (subscriber.pumping) return;
+    subscriber.pumping = true;
+    try {
+      await subscriber.sink.ready;
+      while (subscriber.dirty && !subscriber.closed) {
+        subscriber.dirty = false;
+        for (; ; ) {
+          const receipt = this.active.get(subscriber.operationId)?.receipt ?? this.store.get(subscriber.operationId);
+          if (!receipt) throw new ExecutorError("run_not_found");
+          if (subscriber.offset < receipt.stdoutBytes) {
+            const chunk = this.store.read(subscriber.operationId, "stdout", subscriber.offset, receipt.stdoutBytes, STREAM_CHUNK_BYTES);
+            subscriber.offset = chunk.nextOffset;
+            await subscriber.sink.send({ event: "output", offset: subscriber.offset, base64: chunk.base64 });
+            if (subscriber.closed) return;
+            continue;
+          }
+          if (!this.active.has(subscriber.operationId) || ["completed", "cancelled", "unknown"].includes(receipt.state)) {
+            await subscriber.sink.send({ event: "exit", receipt: { ...receipt } });
+            this.unsubscribe(subscriber.sink);
+            subscriber.sink.end();
+          }
+          break;
+        }
+      }
+    } catch {
+      this.unsubscribe(subscriber.sink);
+      subscriber.sink.end();
+    } finally {
+      subscriber.pumping = false;
+    }
+  }
   authenticate(request) {
     const grant = this.adapters.find(request.auth.principalId);
     const principal = this.config.principals.find((p) => p.id === request.auth.principalId) ?? grant?.principal;
@@ -120,7 +168,7 @@ class HostExecutor {
     if (!run || run.userId !== identity.userId || run.sessionId !== (identity.sessionId ?? null)) throw new ExecutorError("run_not_found");
     return run;
   }
-  async dispatch(input) {
+  async dispatch(input, sink) {
     if (this.closing) throw new ExecutorError("executor_unavailable");
     const request = ExecutorRequest.parse(input);
     const principal = this.authenticate(request);
@@ -315,6 +363,24 @@ class HostExecutor {
         stdout: this.store.read(receipt.operationId, "stdout", command.stdoutOffset, receipt.stdoutBytes, command.maxBytes),
         stderr: this.store.read(receipt.operationId, "stderr", command.stderrOffset, receipt.stderrBytes, command.maxBytes)
       };
+    if (command.method === "subscribe") {
+      if (!sink) throw new ExecutorError("invalid_request");
+      if (!receipt.pty) throw new ExecutorError("not_a_pty");
+      if (command.offset > receipt.stdoutBytes) throw new ExecutorError("invalid_offset");
+      const subscriber = { operationId: receipt.operationId, offset: command.offset, sink, pumping: false, dirty: false, closed: false };
+      this.subscribers.set(sink, subscriber);
+      void this.pump(subscriber);
+      return { receipt: { ...receipt }, offset: command.offset };
+    }
+    if (command.method === "input") {
+      const live = this.active.get(receipt.operationId);
+      if (!live || live.finishing) throw new ExecutorError(receipt.state === "unknown" ? "outcome_unknown" : "run_not_running");
+      if (!live.pty) throw new ExecutorError("not_a_pty");
+      if (receipt.stdinClosed) throw new ExecutorError("stdin_closed");
+      if (command.data !== void 0) await live.pty.write(command.data);
+      if (command.resize) await live.pty.resize(command.resize.cols, command.resize.rows);
+      return { ok: true };
+    }
     const actionHash = tokenHash(
       canonicalJson({
         method: command.method,
@@ -388,6 +454,7 @@ class HostExecutor {
       this.store.append(run.receipt.operationId, stream, data);
       run.receipt[stream === "stdout" ? "stdoutBytes" : "stderrBytes"] += data.length;
       this.store.put(run.receipt);
+      if (stream === "stdout") this.notify(run.receipt.operationId);
     } catch {
       this.poisoned = true;
       void this.finish(run, true, "output_persistence_failed").catch(() => {
@@ -419,6 +486,7 @@ class HostExecutor {
       if (cleanupFailed) run.receipt.reason = "process_cleanup_uncertain";
       this.store.put(run.receipt);
       this.active.delete(run.receipt.operationId);
+      this.notify(run.receipt.operationId);
       if (cleanupFailed) throw new ExecutorError("process_cleanup_uncertain");
     })();
     return run.finishing;
@@ -426,6 +494,10 @@ class HostExecutor {
   async close() {
     this.closing = true;
     clearInterval(this.leaseTimer);
+    for (const [sink] of this.subscribers) {
+      this.unsubscribe(sink);
+      sink.end();
+    }
     await this.serial;
     await Promise.allSettled([...this.active.values()].map((run) => this.finish(run, true, "executor_shutdown")));
     this.store.close();