@runuai/host 0.9.14 → 0.9.42

package/lib/host-logs.ts

@@ -0,0 +1,962 @@
+/**
+ * Bounded remote reader for the host service's own logs (ADR-100).
+ *
+ * The manager is deliberately connection-generation scoped. `stop(opId)` is
+ * the wire-visible operator action and emits a `stopped` terminal frame;
+ * `stopAll()` is generation teardown and synchronously detaches timers and
+ * process listeners, signals children, and initiates file-handle closes
+ * without calling emitters that belong to the dead generation.
+ */
+
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
+
+import {
+  isHostOpId,
+  MAX_HOST_LOG_CHUNK_BYTES,
+  MAX_HOST_LOG_CHUNK_LINES,
+  MAX_HOST_LOG_LINE_BYTES,
+  MAX_HOST_LOG_LINES,
+  MAX_REMOTE_HOST_MESSAGE_BYTES,
+  type HostLogsChunkFrame,
+  type HostLogsEndFrame,
+} from "../src/protocol";
+import { serviceLogPath } from "../src/paths";
+import { scrubHostString } from "./obs";
+
+export const DEFAULT_HOST_LOG_LINES = 200;
+export const MAX_HOST_LOG_STREAMS = 4;
+export const MAX_HOST_LOG_PENDING_LINES = 1_000;
+export const MAX_HOST_LOG_PENDING_BYTES = 256 * 1_024;
+export const DEFAULT_HOST_LOG_POLL_MS = 250;
+
+const FILE_READ_BLOCK_BYTES = 64 * 1_024;
+const MAX_FILE_BYTES_PER_POLL = 1024 * 1024;
+// Enough for 1,000 maximum-size lines plus headroom for CRLF. This keeps a
+// malicious unterminated log from turning an initial tail into an unbounded
+// read. If the boundary lands inside a line, that fragment is discarded.
+const MAX_INITIAL_TAIL_SCAN_BYTES = 8 * 1024 * 1024;
+const TRUNCATION_MARKER = "…[truncated]";
+const EMIT_RETRY_MS = 25;
+
+export type HostLogsFrame = HostLogsChunkFrame | HostLogsEndFrame;
+export type HostLogsEmit = (frame: HostLogsFrame) => boolean | void;
+
+export class HostLogStartError extends Error {
+  readonly code: "invalid_op_id" | "duplicate_op" | "too_many_streams";
+
+  constructor(
+    code: HostLogStartError["code"],
+    message: string,
+  ) {
+    super(message);
+    this.name = "HostLogStartError";
+    this.code = code;
+  }
+}
+
+export interface HostLogFileStat {
+  size: number;
+  dev: number | bigint;
+  ino: number | bigint;
+  isFile(): boolean;
+}
+
+export interface HostLogFileHandle {
+  stat(): Promise<HostLogFileStat>;
+  read(
+    buffer: Buffer,
+    offset: number,
+    length: number,
+    position: number,
+  ): Promise<{ bytesRead: number }>;
+  close(): Promise<void>;
+}
+
+export interface HostLogFs {
+  open(path: string): Promise<HostLogFileHandle>;
+  stat(path: string): Promise<HostLogFileStat>;
+}
+
+export interface HostLogReadable {
+  setEncoding?(encoding: BufferEncoding): unknown;
+  on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+  off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+  destroy?(): unknown;
+}
+
+export interface HostLogChild {
+  stdout: HostLogReadable;
+  stderr: HostLogReadable;
+  on(event: "error", listener: (error: Error) => void): unknown;
+  on(event: "close", listener: (code: number | null) => void): unknown;
+  off(event: "error", listener: (error: Error) => void): unknown;
+  off(event: "close", listener: (code: number | null) => void): unknown;
+  kill(signal?: NodeJS.Signals): boolean;
+}
+
+export interface HostLogSpawnOptions {
+  stdio: ["ignore", "pipe", "pipe"];
+  shell: false;
+}
+
+export type HostLogSpawn = (
+  command: string,
+  args: readonly string[],
+  options: HostLogSpawnOptions,
+) => HostLogChild;
+
+export interface HostLogTimers {
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(timer: unknown): void;
+}
+
+export interface HostLogManagerOptions {
+  platform?: NodeJS.Platform;
+  logPath?: string;
+  fs?: HostLogFs;
+  spawn?: HostLogSpawn;
+  timers?: HostLogTimers;
+  pollMs?: number;
+}
+
+interface PendingLine {
+  value: string;
+  bytes: number;
+}
+
+interface BaseStream {
+  readonly opId: string;
+  readonly emit: HostLogsEmit;
+  readonly follow: boolean;
+  active: boolean;
+  pending: PendingLine[];
+  pendingBytes: number;
+  dropped: number;
+  flushTimer: unknown | null;
+  terminal: HostLogsEndFrame | null;
+  accumulator: BoundedLineAccumulator;
+  cleanupSource(): void;
+}
+
+interface FileStream extends BaseStream {
+  kind: "file";
+  handle: HostLogFileHandle | null;
+  identity: string | null;
+  position: number;
+  pollTimer: unknown | null;
+  polling: boolean;
+}
+
+interface JournalStream extends BaseStream {
+  kind: "journal";
+  child: HostLogChild | null;
+  stderr: BoundedText;
+  onStdoutData: (chunk: Buffer | string) => void;
+  onStderrData: (chunk: Buffer | string) => void;
+  onError: (error: Error) => void;
+  onClose: (code: number | null) => void;
+}
+
+type ActiveStream = FileStream | JournalStream;
+
+const defaultFs: HostLogFs = {
+  open: async (path) =>
+    (await open(
+      path,
+      constants.O_RDONLY | constants.O_NOFOLLOW,
+    )) as HostLogFileHandle,
+  // The host log is an exact service-owned file. Never follow a replacement
+  // symlink and accidentally relay an unrelated host file to the cloud.
+  stat: async (path) => (await lstat(path)) as HostLogFileStat,
+};
+
+const defaultSpawn: HostLogSpawn = (command, args, options) =>
+  spawn(command, [...args], options) as unknown as HostLogChild;
+
+const defaultTimers: HostLogTimers = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>),
+};
+
+function unrefTimer(timer: unknown): void {
+  if (
+    typeof timer === "object" &&
+    timer !== null &&
+    "unref" in timer &&
+    typeof (timer as { unref?: unknown }).unref === "function"
+  ) {
+    (timer as { unref(): void }).unref();
+  }
+}
+
+function normalizeTailLines(lines: number | undefined): number {
+  if (lines === undefined || !Number.isFinite(lines)) {
+    return DEFAULT_HOST_LOG_LINES;
+  }
+  return Math.max(1, Math.min(MAX_HOST_LOG_LINES, Math.trunc(lines)));
+}
+
+function safeUtf8Prefix(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  const bytes = Buffer.from(value, "utf8");
+  let end = Math.min(maxBytes, bytes.length);
+  while (end > 0) {
+    const prefix = bytes.subarray(0, end).toString("utf8");
+    if (!prefix.endsWith("�")) return prefix;
+    end -= 1;
+  }
+  return "";
+}
+
+function truncateUtf8(
+  value: string,
+  maxBytes: number,
+  marker = TRUNCATION_MARKER,
+): string {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
+  const markerBytes = Buffer.byteLength(marker, "utf8");
+  if (markerBytes >= maxBytes) return safeUtf8Prefix(marker, maxBytes);
+  return `${safeUtf8Prefix(value, maxBytes - markerBytes)}${marker}`;
+}
+
+function boundedErrorMessage(error: unknown, prefix: string): string {
+  const detail = error instanceof Error ? error.message : String(error);
+  const scrubbed = scrubHostString(`${prefix}: ${detail || "unknown error"}`);
+  return truncateUtf8(scrubbed, MAX_REMOTE_HOST_MESSAGE_BYTES);
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return undefined;
+  }
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" ? code : undefined;
+}
+
+function fileIdentity(value: HostLogFileStat): string {
+  return `${String(value.dev)}:${String(value.ino)}`;
+}
+
+function validRegularFile(value: HostLogFileStat): boolean {
+  return (
+    Number.isSafeInteger(value.size) && value.size >= 0 && value.isFile()
+  );
+}
+
+/** A line decoder whose retained raw partial can never exceed 4 KiB. */
+class BoundedLineAccumulator {
+  private decoder = new StringDecoder("utf8");
+  private partial = "";
+  private partialBytes = 0;
+  private truncated = false;
+
+  constructor(private readonly onLine: (line: string) => void) {}
+
+  push(chunk: Buffer | string): void {
+    const text = typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+    let cursor = 0;
+    for (;;) {
+      const newline = text.indexOf("\n", cursor);
+      if (newline === -1) {
+        this.append(text.slice(cursor));
+        return;
+      }
+      this.append(text.slice(cursor, newline));
+      this.finishLine();
+      cursor = newline + 1;
+    }
+  }
+
+  end(emitPartial: boolean): void {
+    const last = this.decoder.end();
+    if (last) this.push(last);
+    if (emitPartial && (this.partialBytes > 0 || this.truncated)) {
+      this.finishLine();
+    }
+  }
+
+  reset(): void {
+    this.decoder = new StringDecoder("utf8");
+    this.partial = "";
+    this.partialBytes = 0;
+    this.truncated = false;
+  }
+
+  private append(value: string): void {
+    if (!value || this.truncated) return;
+    const available = MAX_HOST_LOG_LINE_BYTES - this.partialBytes;
+    if (available <= 0) {
+      this.truncated = true;
+      return;
+    }
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes <= available) {
+      this.partial += value;
+      this.partialBytes += bytes;
+      return;
+    }
+    const prefix = safeUtf8Prefix(value, available);
+    this.partial += prefix;
+    this.partialBytes += Buffer.byteLength(prefix, "utf8");
+    this.truncated = true;
+  }
+
+  private finishLine(): void {
+    let raw = this.partial;
+    if (raw.endsWith("\r")) raw = raw.slice(0, -1);
+    let line = scrubHostString(raw);
+    if (this.truncated) {
+      line = truncateUtf8(`${line}${TRUNCATION_MARKER}`, MAX_HOST_LOG_LINE_BYTES);
+    } else {
+      line = truncateUtf8(line, MAX_HOST_LOG_LINE_BYTES);
+    }
+    this.onLine(line);
+    this.partial = "";
+    this.partialBytes = 0;
+    this.truncated = false;
+  }
+}
+
+/** Small stderr collector for an eventual bounded, scrubbed error message. */
+class BoundedText {
+  private value = "";
+  private bytes = 0;
+  private truncated = false;
+
+  push(chunk: Buffer | string): void {
+    if (this.truncated) return;
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    const limit = MAX_REMOTE_HOST_MESSAGE_BYTES * 4;
+    const available = limit - this.bytes;
+    if (available <= 0) {
+      this.truncated = true;
+      return;
+    }
+    const prefix = safeUtf8Prefix(text, available);
+    this.value += prefix;
+    this.bytes += Buffer.byteLength(prefix, "utf8");
+    if (prefix !== text) this.truncated = true;
+  }
+
+  read(): string {
+    return this.truncated ? `${this.value}${TRUNCATION_MARKER}` : this.value;
+  }
+}
+
+export class HostLogManager {
+  private readonly platform: NodeJS.Platform;
+  private readonly logPath: string;
+  private readonly fs: HostLogFs;
+  private readonly spawn: HostLogSpawn;
+  private readonly timers: HostLogTimers;
+  private readonly pollMs: number;
+  private readonly streams = new Map<string, ActiveStream>();
+
+  constructor(options: HostLogManagerOptions = {}) {
+    this.platform = options.platform ?? process.platform;
+    this.logPath = options.logPath ?? serviceLogPath();
+    this.fs = options.fs ?? defaultFs;
+    this.spawn = options.spawn ?? defaultSpawn;
+    this.timers = options.timers ?? defaultTimers;
+    this.pollMs = options.pollMs ?? DEFAULT_HOST_LOG_POLL_MS;
+    if (!Number.isSafeInteger(this.pollMs) || this.pollMs <= 0) {
+      throw new Error("host log poll interval is invalid");
+    }
+  }
+
+  get activeCount(): number {
+    return this.streams.size;
+  }
+
+  start(
+    opId: string,
+    lines: number | undefined,
+    follow: boolean,
+    emit: HostLogsEmit,
+  ): void {
+    if (!isHostOpId(opId)) {
+      throw new HostLogStartError("invalid_op_id", "invalid host log operation id");
+    }
+    if (this.streams.has(opId)) {
+      throw new HostLogStartError(
+        "duplicate_op",
+        "host log operation is already active",
+      );
+    }
+    if (this.streams.size >= MAX_HOST_LOG_STREAMS) {
+      throw new HostLogStartError(
+        "too_many_streams",
+        "too many host log streams are active",
+      );
+    }
+
+    const count = normalizeTailLines(lines);
+    if (this.platform === "linux") {
+      this.startJournal(opId, count, follow === true, emit);
+      return;
+    }
+    if (this.platform === "darwin" || this.platform === "win32") {
+      this.startFile(opId, count, follow === true, emit);
+      return;
+    }
+
+    const stream = this.newBaseStream(opId, follow === true, emit) as FileStream;
+    stream.kind = "file";
+    stream.handle = null;
+    stream.identity = null;
+    stream.position = 0;
+    stream.pollTimer = null;
+    stream.polling = false;
+    stream.cleanupSource = () => {};
+    this.streams.set(opId, stream);
+    this.requestEnd(
+      stream,
+      "error",
+      `host logs are unsupported on platform ${this.platform}`,
+    );
+  }
+
+  /** Explicit operator stop. Pending chunks are discarded before the end. */
+  stop(opId: string): boolean {
+    const stream = this.streams.get(opId);
+    if (!stream) return false;
+    this.teardown(stream, true);
+    return true;
+  }
+
+  /**
+   * Connection-generation teardown. No end frames are emitted. Every timer
+   * and listener is detached, every journal child is signalled, and every
+   * file close is initiated before this method returns.
+   */
+  stopAll(): void {
+    for (const stream of [...this.streams.values()]) {
+      this.teardown(stream, false);
+    }
+  }
+
+  private newBaseStream(
+    opId: string,
+    follow: boolean,
+    emit: HostLogsEmit,
+  ): BaseStream {
+    const stream = {
+      opId,
+      emit,
+      follow,
+      active: true,
+      pending: [],
+      pendingBytes: 0,
+      dropped: 0,
+      flushTimer: null,
+      terminal: null,
+      accumulator: undefined as unknown as BoundedLineAccumulator,
+      cleanupSource: () => {},
+    } satisfies BaseStream;
+    stream.accumulator = new BoundedLineAccumulator((line) =>
+      this.enqueue(stream, line),
+    );
+    return stream;
+  }
+
+  private startFile(
+    opId: string,
+    lines: number,
+    follow: boolean,
+    emit: HostLogsEmit,
+  ): void {
+    const stream = this.newBaseStream(opId, follow, emit) as FileStream;
+    stream.kind = "file";
+    stream.handle = null;
+    stream.identity = null;
+    stream.position = 0;
+    stream.pollTimer = null;
+    stream.polling = false;
+    stream.cleanupSource = () => {
+      if (stream.pollTimer !== null) {
+        this.timers.clearTimeout(stream.pollTimer);
+        stream.pollTimer = null;
+      }
+      const handle = stream.handle;
+      stream.handle = null;
+      if (handle) void handle.close().catch(() => {});
+    };
+    this.streams.set(opId, stream);
+    void this.initializeFile(stream, lines);
+  }
+
+  private async initializeFile(stream: FileStream, lines: number): Promise<void> {
+    try {
+      const pathStat = await this.fs.stat(this.logPath);
+      if (!validRegularFile(pathStat)) {
+        throw new Error("host log is not a regular file");
+      }
+      if (!stream.active) return;
+      const handle = await this.fs.open(this.logPath);
+      if (!stream.active) {
+        void handle.close().catch(() => {});
+        return;
+      }
+      stream.handle = handle;
+      const current = await handle.stat();
+      if (!validRegularFile(current)) {
+        throw new Error("host log is not a regular file");
+      }
+      if (fileIdentity(current) !== fileIdentity(pathStat)) {
+        throw new Error("host log changed while it was being opened");
+      }
+      if (!stream.active) return;
+      stream.identity = fileIdentity(current);
+      stream.position = current.size;
+      const initial = await this.readInitialTail(handle, current.size, lines);
+      if (!stream.active) return;
+      for (const line of initial.complete) stream.accumulator.push(`${line}\n`);
+      if (initial.partial !== null) stream.accumulator.push(initial.partial);
+
+      if (!stream.follow) {
+        stream.accumulator.end(true);
+        this.requestEnd(stream, "complete");
+        return;
+      }
+      this.schedulePoll(stream, this.pollMs);
+    } catch (error) {
+      if (stream.active) {
+        this.requestEnd(
+          stream,
+          "error",
+          boundedErrorMessage(error, "could not read host log"),
+        );
+      }
+    }
+  }
+
+  private async readInitialTail(
+    handle: HostLogFileHandle,
+    size: number,
+    lines: number,
+  ): Promise<{ complete: string[]; partial: string | null }> {
+    if (size === 0) return { complete: [], partial: null };
+    const length = Math.min(size, MAX_INITIAL_TAIL_SCAN_BYTES);
+    const start = size - length;
+    const buffer = Buffer.allocUnsafe(length);
+    let read = 0;
+    while (read < length) {
+      const result = await handle.read(
+        buffer,
+        read,
+        Math.min(FILE_READ_BLOCK_BYTES, length - read),
+        start + read,
+      );
+      if (result.bytesRead <= 0) break;
+      read += result.bytesRead;
+    }
+    let bytes = buffer.subarray(0, read);
+    if (start > 0) {
+      const newline = bytes.indexOf(0x0a);
+      if (newline === -1) {
+        // The scan window is one giant line. Retain only its bounded suffix
+        // and make the loss explicit; never fabricate it as a full line.
+        const suffixBytes = Math.max(0, MAX_HOST_LOG_LINE_BYTES - 32);
+        bytes = Buffer.concat([
+          Buffer.from(`${TRUNCATION_MARKER} `),
+          bytes.subarray(Math.max(0, bytes.length - suffixBytes)),
+        ]);
+      } else {
+        bytes = bytes.subarray(newline + 1);
+      }
+    }
+    if (bytes.length === 0) return { complete: [], partial: null };
+
+    // Select the last N lines while the bytes are still compact. Splitting the
+    // entire scan window first would let an 8 MiB file of only newlines create
+    // millions of array entries despite the 1,000-line wire limit.
+    const terminalNewline = bytes.at(-1) === 0x0a;
+    let separatorCount = 0;
+    let selectedStart = 0;
+    for (
+      let index = bytes.length - (terminalNewline ? 2 : 1);
+      index >= 0;
+      index -= 1
+    ) {
+      if (bytes[index] !== 0x0a) continue;
+      separatorCount += 1;
+      if (separatorCount === lines) {
+        selectedStart = index + 1;
+        break;
+      }
+    }
+    bytes = bytes.subarray(selectedStart);
+    const text = bytes.toString("utf8");
+    const terminated = text.endsWith("\n");
+    const physical = text.split("\n");
+    if (terminated) physical.pop();
+    const selected = physical.slice(-lines);
+    if (!terminated && selected.length > 0) {
+      return {
+        complete: selected.slice(0, -1),
+        partial: selected.at(-1) ?? null,
+      };
+    }
+    return { complete: selected, partial: null };
+  }
+
+  private schedulePoll(stream: FileStream, delayMs: number): void {
+    if (!stream.active || stream.terminal || stream.pollTimer !== null) return;
+    stream.pollTimer = this.timers.setTimeout(() => {
+      stream.pollTimer = null;
+      void this.pollFile(stream);
+    }, delayMs);
+    unrefTimer(stream.pollTimer);
+  }
+
+  private async pollFile(stream: FileStream): Promise<void> {
+    if (!stream.active || stream.polling) return;
+    stream.polling = true;
+    let catchUp = false;
+    try {
+      const handle = stream.handle;
+      if (!handle) throw new Error("host log file is not open");
+      const current = await handle.stat();
+      if (!validRegularFile(current)) {
+        throw new Error("host log is not a regular file");
+      }
+      if (!stream.active) return;
+      if (current.size < stream.position) {
+        // copytruncate: an old partial must never be joined to the new file.
+        stream.position = 0;
+        stream.accumulator.reset();
+      }
+      catchUp = await this.readFileAppend(
+        stream,
+        handle,
+        current.size,
+        MAX_FILE_BYTES_PER_POLL,
+      );
+      if (!stream.active) return;
+
+      let pathStat: HostLogFileStat | null = null;
+      try {
+        pathStat = await this.fs.stat(this.logPath);
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") throw error;
+      }
+      if (!stream.active) return;
+      if (pathStat && fileIdentity(pathStat) !== stream.identity) {
+        await this.rotateFile(stream, pathStat);
+        catchUp = true;
+      }
+    } catch (error) {
+      if (stream.active) {
+        this.requestEnd(
+          stream,
+          "error",
+          boundedErrorMessage(error, "host log follow failed"),
+        );
+      }
+    } finally {
+      stream.polling = false;
+      if (stream.active && !stream.terminal) {
+        this.schedulePoll(stream, catchUp ? 0 : this.pollMs);
+      }
+    }
+  }
+
+  /** Returns true while bytes remain so catch-up continues without poll delay. */
+  private async readFileAppend(
+    stream: FileStream,
+    handle: HostLogFileHandle,
+    targetSize: number,
+    maxBytes: number,
+  ): Promise<boolean> {
+    const cappedTarget = Math.min(targetSize, stream.position + maxBytes);
+    const buffer = Buffer.allocUnsafe(FILE_READ_BLOCK_BYTES);
+    while (stream.active && stream.position < cappedTarget) {
+      const wanted = Math.min(buffer.length, cappedTarget - stream.position);
+      const result = await handle.read(buffer, 0, wanted, stream.position);
+      if (result.bytesRead <= 0) break;
+      stream.position += result.bytesRead;
+      stream.accumulator.push(buffer.subarray(0, result.bytesRead));
+    }
+    return stream.position < targetSize;
+  }
+
+  private async rotateFile(
+    stream: FileStream,
+    expected: HostLogFileStat,
+  ): Promise<void> {
+    const previous = stream.handle;
+    stream.handle = null;
+    if (previous) await previous.close().catch(() => {});
+    stream.accumulator.reset();
+    const replacement = await this.fs.open(this.logPath);
+    if (!stream.active) {
+      void replacement.close().catch(() => {});
+      return;
+    }
+    const replacementStat = await replacement.stat();
+    if (!validRegularFile(replacementStat)) {
+      void replacement.close().catch(() => {});
+      throw new Error("replacement host log is not a regular file");
+    }
+    if (fileIdentity(replacementStat) !== fileIdentity(expected)) {
+      void replacement.close().catch(() => {});
+      throw new Error("replacement host log changed while it was being opened");
+    }
+    stream.handle = replacement;
+    stream.identity = fileIdentity(replacementStat);
+    stream.position = 0;
+    await this.readFileAppend(
+      stream,
+      replacement,
+      replacementStat.size,
+      MAX_FILE_BYTES_PER_POLL,
+    );
+  }
+
+  private startJournal(
+    opId: string,
+    lines: number,
+    follow: boolean,
+    emit: HostLogsEmit,
+  ): void {
+    const stream = this.newBaseStream(opId, follow, emit) as JournalStream;
+    stream.kind = "journal";
+    stream.child = null;
+    stream.stderr = new BoundedText();
+    stream.onStdoutData = (chunk) => {
+      if (stream.active) stream.accumulator.push(chunk);
+    };
+    stream.onStderrData = (chunk) => {
+      if (stream.active) stream.stderr.push(chunk);
+    };
+    stream.onError = (error) => {
+      if (!stream.active) return;
+      this.requestEnd(
+        stream,
+        "error",
+        boundedErrorMessage(error, "journalctl failed"),
+      );
+    };
+    stream.onClose = (code) => {
+      if (!stream.active) return;
+      // The process has already exited. Detach without signalling it again;
+      // requestEnd's generic source cleanup then becomes a no-op.
+      this.detachJournal(stream, false);
+      stream.accumulator.end(!follow);
+      if (code === 0 && !follow) {
+        this.requestEnd(stream, "complete");
+        return;
+      }
+      const stderr = stream.stderr.read().trim();
+      const detail = follow
+        ? `journalctl exited while following${code === null ? "" : ` (code ${code})`}`
+        : `journalctl exited${code === null ? "" : ` with code ${code}`}`;
+      this.requestEnd(
+        stream,
+        "error",
+        boundedErrorMessage(stderr || "no diagnostic output", detail),
+      );
+    };
+    stream.cleanupSource = () => this.detachJournal(stream, true);
+    this.streams.set(opId, stream);
+
+    try {
+      const args = [
+        "--user",
+        "-u",
+        "uai-host",
+        "--no-pager",
+        "-o",
+        "cat",
+        "-n",
+        String(lines),
+      ];
+      if (follow) args.push("-f");
+      const child = this.spawn("/usr/bin/journalctl", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+      });
+      if (!stream.active) {
+        child.kill("SIGTERM");
+        return;
+      }
+      stream.child = child;
+      child.stdout.setEncoding?.("utf8");
+      child.stderr.setEncoding?.("utf8");
+      child.stdout.on("data", stream.onStdoutData);
+      child.stderr.on("data", stream.onStderrData);
+      child.on("error", stream.onError);
+      child.on("close", stream.onClose);
+    } catch (error) {
+      this.requestEnd(
+        stream,
+        "error",
+        boundedErrorMessage(error, "could not start journalctl"),
+      );
+    }
+  }
+
+  private detachJournal(stream: JournalStream, terminate: boolean): void {
+    const child = stream.child;
+    stream.child = null;
+    if (!child) return;
+    child.stdout.off("data", stream.onStdoutData);
+    child.stderr.off("data", stream.onStderrData);
+    child.off("error", stream.onError);
+    child.off("close", stream.onClose);
+    if (terminate) {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // Best effort: listeners are already detached and cannot resurrect it.
+      }
+      child.stdout.destroy?.();
+      child.stderr.destroy?.();
+    }
+  }
+
+  private enqueue(stream: BaseStream, value: string): void {
+    if (!stream.active) return;
+    // BoundedLineAccumulator scrubbed and line-bounded this before it crossed
+    // into the outbound buffer.
+    const bytes = Buffer.byteLength(value, "utf8");
+    stream.pending.push({ value, bytes });
+    stream.pendingBytes += bytes;
+    while (
+      stream.pending.length > MAX_HOST_LOG_PENDING_LINES ||
+      stream.pendingBytes > MAX_HOST_LOG_PENDING_BYTES
+    ) {
+      const removed = stream.pending.shift();
+      if (!removed) break;
+      stream.pendingBytes -= removed.bytes;
+      stream.dropped = Math.min(Number.MAX_SAFE_INTEGER, stream.dropped + 1);
+    }
+    this.scheduleFlush(stream, 0);
+  }
+
+  private scheduleFlush(stream: BaseStream, delayMs: number): void {
+    if (!stream.active || stream.flushTimer !== null) return;
+    stream.flushTimer = this.timers.setTimeout(() => {
+      stream.flushTimer = null;
+      this.flush(stream);
+    }, delayMs);
+    unrefTimer(stream.flushTimer);
+  }
+
+  private flush(stream: BaseStream): void {
+    if (!stream.active) return;
+    if (stream.pending.length === 0) {
+      if (stream.terminal) this.emitTerminal(stream);
+      return;
+    }
+
+    const lines: string[] = [];
+    let bytes = 0;
+    for (const pending of stream.pending) {
+      if (lines.length >= MAX_HOST_LOG_CHUNK_LINES) break;
+      if (lines.length > 0 && bytes + pending.bytes > MAX_HOST_LOG_CHUNK_BYTES) {
+        break;
+      }
+      // A single line is <=4 KiB, so it always fits an empty 64 KiB chunk.
+      lines.push(pending.value);
+      bytes += pending.bytes;
+    }
+    const frame: HostLogsChunkFrame = {
+      kind: "host.logs.chunk",
+      opId: stream.opId,
+      lines,
+      ...(stream.dropped > 0 ? { dropped: stream.dropped } : {}),
+    };
+
+    let accepted: boolean | void;
+    try {
+      accepted = stream.emit(frame);
+    } catch {
+      this.teardown(stream, false);
+      return;
+    }
+    if (accepted === false) {
+      this.scheduleFlush(stream, EMIT_RETRY_MS);
+      return;
+    }
+
+    for (let index = 0; index < lines.length; index += 1) {
+      const removed = stream.pending.shift();
+      if (removed) stream.pendingBytes -= removed.bytes;
+    }
+    stream.dropped = 0;
+    if (stream.pending.length > 0 || stream.terminal) {
+      this.scheduleFlush(stream, 0);
+    }
+  }
+
+  private requestEnd(
+    stream: BaseStream,
+    reason: "complete" | "error",
+    message?: string,
+  ): void {
+    if (!stream.active || stream.terminal) return;
+    stream.cleanupSource();
+    stream.terminal =
+      reason === "error"
+        ? {
+            kind: "host.logs.end",
+            opId: stream.opId,
+            reason,
+            message: truncateUtf8(
+              scrubHostString(message || "host log operation failed"),
+              MAX_REMOTE_HOST_MESSAGE_BYTES,
+            ),
+          }
+        : { kind: "host.logs.end", opId: stream.opId, reason };
+    this.scheduleFlush(stream, 0);
+  }
+
+  private emitTerminal(stream: BaseStream): void {
+    const terminal = stream.terminal;
+    if (!terminal || !stream.active) return;
+    this.streams.delete(stream.opId);
+    stream.active = false;
+    stream.terminal = null;
+    try {
+      stream.emit(terminal);
+    } catch {
+      // The connection generation is already gone; cleanup is complete.
+    }
+  }
+
+  private teardown(stream: BaseStream, emitStopped: boolean): void {
+    if (!stream.active) return;
+    stream.active = false;
+    this.streams.delete(stream.opId);
+    if (stream.flushTimer !== null) {
+      this.timers.clearTimeout(stream.flushTimer);
+      stream.flushTimer = null;
+    }
+    stream.cleanupSource();
+    stream.pending.length = 0;
+    stream.pendingBytes = 0;
+    stream.dropped = 0;
+    stream.terminal = null;
+    if (emitStopped) {
+      try {
+        stream.emit({
+          kind: "host.logs.end",
+          opId: stream.opId,
+          reason: "stopped",
+        });
+      } catch {
+        // Explicit stop is still complete even if its generation disappeared.
+      }
+    }
+  }
+}
+
+export function createHostLogManager(
+  options: HostLogManagerOptions = {},
+): HostLogManager {
+  return new HostLogManager(options);
+}