@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/omp/rpc/utility.ts

@@ -0,0 +1,300 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared short-lived `omp` utility process for global registry/auth queries
+ * (get_available_models, get_login_providers, get_state). These commands do
+ * not belong to any user session, so they run against a single lazily-started
+ * RPC process that is killed after ~300s of inactivity. Access is serialized:
+ * the omp RPC loop handles one command at a time anyway, and serialization
+ * lets lazy start/idle-kill stay race-free.
+ *
+ * Real user sessions must use lib/rpc-manager.ts instead — this process runs
+ * with --no-session and its agent state is throwaway.
+ *
+ * Faithful port of omp-web/lib/omp/rpc-utility.ts.
+ */
+
+import { homedir } from 'os';
+import { RpcProcess } from '@/server/lib/omp/rpc/process';
+import { RELOAD_PLUGINS_TIMEOUT_MS } from '@/server/lib/omp/rpc/constants';
+
+// Extensions stay ENABLED: they can register models and login providers, and
+// omitting them made the web UI's model/provider lists disagree with the CLI's.
+//
+// Skills stay ENABLED too. `--no-skills` made `get_available_commands` omit
+// every `skill:<name>` entry (measured: 45 commands without, 52 with), so the
+// composer's `/` popup could not offer the skills omp happily executes — and
+// Kabmo's own disk scan missed provider roots omp reads (`~/.agents/skills`).
+// Cost is nil: the ready frame lands at the same ~420ms either way.
+const UTILITY_EXTRA_ARGS = ['--no-session', '--no-lsp'];
+const READY_TIMEOUT_MS = 60_000;
+// Longer than the 60s models-cache TTL on purpose: with idle-kill == TTL every
+// pause past a minute paid a cold multi-second respawn on top of the stale
+// cache. Cost of the longer window is one idle omp process.
+const IDLE_KILL_MS = 300_000;
+const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+
+/** Minimal mirror of omp's Model — only the fields the models/auth routes
+ * read. Everything else passes through opaque. */
+export interface OmpModel {
+  id: string;
+  name: string;
+  provider: string;
+  api?: string;
+  reasoning?: boolean;
+  thinking?: {
+    mode?: string;
+    efforts?: string[];
+    defaultLevel?: string;
+    effortMap?: Record<string, string>;
+  };
+  input?: string[];
+  contextWindow?: number | null;
+  maxTokens?: number | null;
+  cost?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+}
+
+/** Entry of the get_login_providers response (modes/rpc/rpc-types.ts). */
+export interface OmpLoginProvider {
+  id: string;
+  name: string;
+  available: boolean;
+  authenticated: boolean;
+}
+
+interface UtilityRpcState {
+  proc: RpcProcess | null;
+  idleTimer: NodeJS.Timeout | null;
+  queue: Promise<void>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompUtilityRpcStates: Map<string, UtilityRpcState> | undefined;
+}
+
+/**
+ * Utility processes are pooled PER WORKING DIRECTORY, because a cwd is not just
+ * a spawn detail: omp resolves project-scope config from it. `.omp/commands`,
+ * `.omp/skills`, `.claude`, `.agents` and `AGENTS.md` in a workspace are only
+ * discovered by a child started in that workspace (measured: a child in $HOME
+ * reported 7 skill entries and one `file` command; the same child in a repo
+ * reported 9 and the repo's own command). One process per cwd keeps the global
+ * registry queries (`get_available_models`, `get_login_providers`) on the
+ * cheap home-scoped child while letting a workspace-scoped read see its own
+ * project config. Each pool entry is idle-killed on its own timer.
+ */
+function getState(cwd: string): UtilityRpcState {
+  if (!globalThis.__ompUtilityRpcStates) {
+    globalThis.__ompUtilityRpcStates = new Map();
+    // Dispose every pooled process on server shutdown so none outlives the
+    // server. Idempotent and safe to call any time.
+    const cleanup = () => disposeUtilityRpc();
+    process.once('exit', cleanup);
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+  }
+  const states = globalThis.__ompUtilityRpcStates;
+  let state = states.get(cwd);
+  if (!state) {
+    state = { proc: null, idleTimer: null, queue: Promise.resolve() };
+    states.set(cwd, state);
+  }
+  return state;
+}
+
+/**
+ * Tear down the shared utility omp processes immediately (skip the idle
+ * timers). Safe to call any time — it just clears any pending idle kill and
+ * disposes the live children.
+ */
+export function disposeUtilityRpc(): void {
+  const states = globalThis.__ompUtilityRpcStates;
+  if (!states) return;
+  for (const state of states.values()) {
+    if (state.idleTimer) {
+      clearTimeout(state.idleTimer);
+      state.idleTimer = null;
+    }
+    const proc = state.proc;
+    state.proc = null;
+    if (proc) void proc.dispose();
+  }
+  states.clear();
+}
+
+/**
+ * Ask every pooled utility child to re-read its skill/command roots.
+ *
+ * These children answer `get_available_commands` for the composer's `/` popup
+ * and the settings panes, and they are pooled for up to {@link IDLE_KILL_MS},
+ * so without this a skill written now stays invisible in the popup for minutes
+ * after every session has already picked it up. Only a LIVE process is asked —
+ * a pooled entry with no child has nothing cached and will discover the current
+ * files on its next lazy start.
+ *
+ * Serialized on each pool's own queue like every other command, so it can never
+ * interleave with a `get_available_commands` in flight. Best-effort per cwd.
+ */
+export async function reloadUtilityProcesses(): Promise<void> {
+  const states = globalThis.__ompUtilityRpcStates;
+  if (!states || states.size === 0) return;
+  await Promise.all(
+    [...states.entries()].map(async ([cwd, state]) => {
+      const proc = state.proc;
+      if (!proc || !proc.isAlive) return;
+      try {
+        await runUtilityCommand({ type: 'prompt', message: '/reload-plugins' }, RELOAD_PLUGINS_TIMEOUT_MS, cwd);
+      } catch (error) {
+        console.error(`Failed to reload plugins for pooled utility process (${cwd}):`, error);
+      }
+    }),
+  );
+}
+
+/**
+ * Recycle every pooled utility child: dispose the live process and let the next
+ * command spawn a fresh one from the current binary.
+ *
+ * A pooled child is spawned once and then answers registry queries for up to
+ * {@link IDLE_KILL_MS} — so after `omp update` replaces the binary, the provider
+ * list, the model list and the composer's `/` popup keep being served by the
+ * OLD build until the idle kill happens to fire. Disposing is enough to fix
+ * that: the pool's whole contract is lazy start, so "no child" is a normal
+ * state and the next `get_login_providers` boots the new binary.
+ *
+ * Serialized on each pool's own queue, so a command already in flight finishes
+ * on the child it started on rather than being killed mid-response. Returns how
+ * many live children were recycled (an idle-killed pool entry has nothing to
+ * dispose).
+ */
+export async function restartUtilityProcesses(): Promise<number> {
+  const states = globalThis.__ompUtilityRpcStates;
+  if (!states || states.size === 0) return 0;
+  let recycled = 0;
+  await Promise.all(
+    [...states.values()].map(async (state) => {
+      const run = state.queue.then(async () => {
+        if (state.idleTimer) {
+          clearTimeout(state.idleTimer);
+          state.idleTimer = null;
+        }
+        const proc = state.proc;
+        state.proc = null;
+        if (!proc) return;
+        recycled += 1;
+        await proc.dispose();
+      });
+      state.queue = run.then(
+        () => undefined,
+        () => undefined,
+      );
+      await run;
+    }),
+  );
+  return recycled;
+}
+
+function scheduleIdleKill(state: UtilityRpcState): void {
+  if (state.idleTimer) clearTimeout(state.idleTimer);
+  state.idleTimer = setTimeout(() => {
+    state.idleTimer = null;
+    const proc = state.proc;
+    state.proc = null;
+    if (proc) void proc.dispose();
+  }, IDLE_KILL_MS);
+  state.idleTimer.unref?.();
+}
+
+async function startProcess(state: UtilityRpcState, cwd: string): Promise<RpcProcess> {
+  const proc = new RpcProcess({
+    cwd,
+    extraArgs: UTILITY_EXTRA_ARGS,
+    onExit: () => {
+      if (state.proc === proc) state.proc = null;
+    },
+  });
+  try {
+    const ready = await proc.waitReady(READY_TIMEOUT_MS);
+    await proc.negotiateProtocol(ready);
+  } catch (error) {
+    void proc.dispose();
+    throw error;
+  }
+  return proc;
+}
+
+/** Run one RPC command on the shared utility process (lazy start, serialized,
+ * idle-killed). Rejections from earlier commands never poison the queue.
+ * `cwd` scopes discovery to a workspace; omitted, the child runs in $HOME. */
+export function runUtilityCommand<T = unknown>(
+  command: { type: string; [key: string]: unknown },
+  timeoutMs: number = DEFAULT_COMMAND_TIMEOUT_MS,
+  cwd: string = homedir(),
+): Promise<T> {
+  const state = getState(cwd);
+  const run = state.queue.then(async () => {
+    if (state.idleTimer) {
+      clearTimeout(state.idleTimer);
+      state.idleTimer = null;
+    }
+    try {
+      if (!state.proc || !state.proc.isAlive) {
+        state.proc = await startProcess(state, cwd);
+      }
+      return await state.proc.sendCommand<T>(command, timeoutMs);
+    } finally {
+      scheduleIdleKill(state);
+    }
+  });
+  state.queue = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+/** Run one RPC command on a dedicated throwaway process. Used where the shared
+ * process must not be reused — e.g. a connectivity test that points
+ * PI_CODING_AGENT_DIR at a temp dir via `env`.
+ *
+ * `signal` (optional) aborts the whole lifecycle: a not-yet-ready child is
+ * disposed immediately and a pending command is rejected. Callers with a
+ * Request should pass `request.signal` so a disconnected client does not keep
+ * a 60s registry spawn running. */
+export async function runIsolatedUtilityCommand<T = unknown>(
+  command: { type: string; [key: string]: unknown },
+  options: { env?: Record<string, string>; cwd?: string; timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<T> {
+  const proc = new RpcProcess({
+    cwd: options.cwd ?? homedir(),
+    extraArgs: UTILITY_EXTRA_ARGS,
+    env: options.env,
+  });
+  const signal = options.signal;
+  const onAbort = () => { void proc.dispose(); };
+  if (signal) {
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+  try {
+    const ready = await proc.waitReady(READY_TIMEOUT_MS);
+    await proc.negotiateProtocol(ready);
+    return await proc.sendCommand<T>(command, options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+  } catch (error) {
+    if (signal?.aborted) {
+      throw new Error('Request aborted');
+    }
+    throw error;
+  } finally {
+    if (signal) signal.removeEventListener('abort', onAbort);
+    // Await the child's exit (not fire-and-forget): callers like a config test
+    // remove their throwaway temp dir right after this resolves, and on
+    // Windows a still-exiting child holding handles on that dir makes rmSync
+    // fail (EBUSY, only suppressed by force: true).
+    await proc.dispose();
+  }
+}

package/src/server/lib/omp/rpc/web-state.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Folds omp's `get_state` payload into Kabmo's WebSessionState while
+ * reconciling the wrapper's own running flags against it. The reconciliation is
+ * the point: `isStreaming` alone cannot tell a finished turn from one that is
+ * between tool calls, so a session with dispatched-but-unstarted work or an
+ * unexpired continuation grace window stays "running".
+ *
+ * Split from the session wrapper (which satisfies WebStateHost structurally) so
+ * rpc-manager.ts stays under the repo's per-file size ceiling.
+ */
+
+import type { RpcSessionState, WebSessionState } from '@/server/lib/omp/rpc/constants';
+
+/** Wrapper state the reconciliation reads and writes. */
+export interface WebStateHost {
+  streaming: boolean;
+  compacting: boolean;
+  promptRunning: boolean;
+  promptDispatchPendingCount: number;
+  awaitingAgentStart: boolean;
+  awaitingAgentStartDeadline: number;
+  continuationGraceUntil: number;
+  bashRunning: boolean;
+  fastModeEnabled: boolean;
+  isRunning(): boolean;
+  /** Persist the identity omp reports, when the payload carries one. */
+  adoptSessionIdentity(state: RpcSessionState): void;
+}
+
+export function buildWebState(host: WebStateHost, state: RpcSessionState): WebSessionState {
+  host.streaming = state.isStreaming;
+  host.compacting = state.isCompacting;
+  host.adoptSessionIdentity(state);
+
+  const awaitingExpired = !host.awaitingAgentStart || Date.now() >= host.awaitingAgentStartDeadline;
+  const hasPendingWork =
+    host.promptDispatchPendingCount > 0 ||
+    (host.awaitingAgentStart && !awaitingExpired);
+
+  if (
+    state.isStreaming === false &&
+    state.isCompacting === false &&
+    !hasPendingWork &&
+    Date.now() >= host.continuationGraceUntil
+  ) {
+    host.promptRunning = false;
+    host.awaitingAgentStart = false;
+    host.awaitingAgentStartDeadline = 0;
+  }
+
+  return {
+    sessionId: state.sessionId,
+    sessionFile: state.sessionFile ?? '',
+    sessionName: state.sessionName,
+    isStreaming: state.isStreaming,
+    isPromptRunning: host.promptRunning,
+    isBashRunning: host.bashRunning,
+    isCompacting: state.isCompacting,
+    autoCompactionEnabled: state.autoCompactionEnabled,
+    autoRetryEnabled: state.autoRetryEnabled,
+    interruptMode: state.interruptMode,
+    steeringMode: state.steeringMode,
+    followUpMode: state.followUpMode,
+    model: state.model
+      ? {
+          id: state.model.id,
+          provider: state.model.provider,
+          name: state.model.name,
+          reasoning: state.model.reasoning,
+          thinking: state.model.thinking ? { efforts: state.model.thinking.efforts } : undefined,
+        }
+      : undefined,
+    messageCount: state.messageCount,
+    queuedMessageCount: state.queuedMessageCount,
+    contextUsage: state.contextUsage ?? null,
+    systemPrompt: state.systemPrompt?.join('\n\n') ?? '',
+    thinkingLevel: state.thinkingLevel ?? 'off',
+    fastModeEnabled: state.fastModeEnabled ?? state.fastMode ?? host.fastModeEnabled,
+    fastModeActive: state.fastModeActive,
+    tokensPerSecond: state.tokensPerSecond ?? null,
+    todoPhases: state.todoPhases ?? [],
+  };
+}

package/src/server/lib/omp/session/artifacts.server.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reading the raw stream behind an `artifact://<id>` reference.
+ *
+ * omp spills a long tool result to `<sessionDir>/<sessionId>/<id>.<kind>.log`
+ * and leaves only a truncated body in the transcript. Nothing in Kabmo
+ * read it, so 65 real results (the longest in the corpus) stopped at the 768
+ * bytes the transcript kept.
+ *
+ * The id and kind reach this module from a session transcript — a document the
+ * Kabmo reads, not one it wrote — so the guards ARE the test: a crafted id
+ * must not escape the session directory, and an unknown kind must not be
+ * probed. The session dir is redirected through `PI_CODING_AGENT_DIR`, the same
+ * seam the blob tests use.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { ARTIFACT_KINDS, isArtifactKind, readArtifact } from '@/server/lib/omp/session/artifacts.server';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+
+const SESSION_ID = '01a0cc50-fd62-7417-899c-e24ff8c8608c';
+let agentDir = '';
+let sessionDir = '';
+
+beforeAll(async () => {
+  agentDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'omp-artifact-test-'));
+  process.env.PI_CODING_AGENT_DIR = agentDir;
+  const sessionsDir = path.join(agentDir, 'sessions');
+  const cwdDir = path.join(sessionsDir, '-tmp-project');
+  await fsp.mkdir(cwdDir, { recursive: true });
+  const sessionFile = path.join(cwdDir, `2026-01-01T00-00-00-000Z_${SESSION_ID}.jsonl`);
+  // A real session file: the locator reads its header line for the id.
+  await fsp.writeFile(
+    sessionFile,
+    `${JSON.stringify({ type: 'session', version: 3, id: SESSION_ID, timestamp: '2026-01-01T00:00:00.000Z', cwd: '/tmp/project' })}\n`,
+  );
+  // omp's sibling dir is the session file's full basename without `.jsonl`
+  // (verified on a real install: `…Z_<uuid>/420.bash.log`), not the bare uuid.
+  sessionDir = path.join(cwdDir, `2026-01-01T00-00-00-000Z_${SESSION_ID}`);
+  await fsp.mkdir(sessionDir, { recursive: true });
+  await fsp.writeFile(path.join(sessionDir, '420.bash.log'), 'full build log\nsecond line\n');
+  await fsp.writeFile(path.join(sessionDir, '213.eval.log'), 'eval output\n');
+  await fsp.writeFile(path.join(sessionDir, '420.read.log'), 'read output\n');
+  clearSessionFileCaches();
+});
+
+afterAll(async () => {
+  delete process.env.PI_CODING_AGENT_DIR;
+  clearSessionFileCaches();
+  await fsp.rm(agentDir, { recursive: true, force: true });
+});
+
+describe('isArtifactKind', () => {
+  test('accepts every kind omp writes', () => {
+    for (const kind of ARTIFACT_KINDS) expect(isArtifactKind(kind)).toBe(true);
+  });
+
+  test('refuses anything else', () => {
+    expect(isArtifactKind('passwd')).toBe(false);
+    expect(isArtifactKind('')).toBe(false);
+  });
+});
+
+describe('readArtifact', () => {
+  test('reads the stream omp spilled for the id', async () => {
+    const artifact = await readArtifact(SESSION_ID, '420', 'bash');
+    expect(artifact?.text).toBe('full build log\nsecond line\n');
+    expect(artifact?.kind).toBe('bash');
+    expect(artifact?.truncated).toBe(false);
+  });
+
+  test('probes kinds when the caller does not know which produced it', async () => {
+    expect((await readArtifact(SESSION_ID, '213'))?.text).toBe('eval output\n');
+  });
+
+  test('distinguishes two artifacts that share an id', async () => {
+    expect((await readArtifact(SESSION_ID, '420', 'bash'))?.kind).toBe('bash');
+    expect((await readArtifact(SESSION_ID, '420', 'read'))?.kind).toBe('read');
+  });
+
+  test('returns null for an id that was never written', async () => {
+    expect(await readArtifact(SESSION_ID, '999', 'bash')).toBeNull();
+  });
+
+  test('returns null for an unknown session', async () => {
+    expect(await readArtifact('no-such-session', '420')).toBeNull();
+  });
+
+  test('refuses a path-traversal id before touching the filesystem', async () => {
+    expect(await readArtifact(SESSION_ID, '../../../../etc/passwd')).toBeNull();
+    expect(await readArtifact(SESSION_ID, '420/../../x')).toBeNull();
+  });
+
+  test('refuses a kind outside the table', async () => {
+    // Falls back to probing the real kinds rather than opening `420.passwd.log`.
+    const artifact = await readArtifact(SESSION_ID, '420', 'passwd');
+    expect(artifact?.kind).toBe('bash');
+  });
+});
+
+describe('readArtifact size cap', () => {
+  test('keeps the tail and reports the cut when the file is too large', async () => {
+    const big = `${'x'.repeat(4 * 1024 * 1024 + 64)}TAIL`;
+    await fsp.writeFile(path.join(sessionDir, '77.bash.log'), big);
+    const artifact = await readArtifact(SESSION_ID, '77', 'bash');
+    expect(artifact?.truncated).toBe(true);
+    expect(artifact?.size).toBe(Buffer.byteLength(big));
+    expect(artifact?.text.endsWith('TAIL')).toBe(true);
+  });
+});

package/src/server/lib/omp/session/artifacts.server.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The raw output behind an `artifact://<id>` reference.
+ *
+ * When a tool result is too long to keep inline omp spills the whole stream to
+ * a file beside the session and leaves a `columnTruncated.artifactId` in the
+ * result's `details.meta` — measured over 5,441 real results, 1% (65) carry one,
+ * and they are exactly the outputs a reader most wants whole: a `bash` build
+ * log, an `eval` that printed a table, a `read` of a long file. The Kabmo
+ * served none of it, so those results were truncated at 768 bytes with no way
+ * to see the rest.
+ *
+ * The layout is omp's own, verified against a real install:
+ *   <sessionsDir>/<cwd-dir>/<sessionFile>.jsonl        the transcript
+ *   <sessionsDir>/<cwd-dir>/<sessionId>/<id>.<kind>.log the spilled stream
+ * `kind` is the tool's own (`bash`, `bash-original`, `eval`, `read`, `async`),
+ * and the id is numeric.
+ *
+ * Every guard here is a path boundary: the id must be digits, the kind must be
+ * one of omp's own, and the resolved path must still sit inside the session's
+ * directory. omp wrote these files, but the id and kind reach this module from
+ * a session transcript, which is a document Kabmo reads rather than one
+ * it wrote.
+ */
+
+import * as fsp from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+import { siblingDirForSession } from '@/server/lib/omp/subagent/history/paths';
+
+/** omp's own artifact kinds, from the filenames it writes. */
+export const ARTIFACT_KINDS = ['bash', 'bash-original', 'eval', 'read', 'async'] as const;
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+
+/** A numeric artifact id; anything else never reaches a path join. */
+const ARTIFACT_ID_RE = /^\d+$/;
+
+/** Cap on what the route will read, so a pathological log cannot be slurped whole. */
+const MAX_ARTIFACT_BYTES = 4 * 1024 * 1024;
+
+export interface ArtifactText {
+  text: string;
+  /** True when the file was longer than `MAX_ARTIFACT_BYTES` and the tail was kept. */
+  truncated: boolean;
+  /** Total file size in bytes, so a caller can say how much was elided. */
+  size: number;
+  /** The kind the artifact was found under. */
+  kind: ArtifactKind;
+}
+
+/** True when `kind` is one omp actually writes. */
+export function isArtifactKind(kind: string): kind is ArtifactKind {
+  return (ARTIFACT_KINDS as readonly string[]).includes(kind);
+}
+
+/**
+ * Read one spilled tool output, or null when the session, the id or the file
+ * cannot be resolved.
+ *
+ * The kind is probed rather than required: a caller reading a transcript sees
+ * `artifactId` without the kind that produced it, and a session can hold an
+ * `eval` and a `bash` artifact under the same id (they are numbered per tool).
+ * The caller may pass the kind it knows; otherwise the first match in
+ * `ARTIFACT_KINDS` order wins.
+ */
+export async function readArtifact(
+  sessionId: string,
+  artifactId: string,
+  kind?: string,
+): Promise<ArtifactText | null> {
+  if (!ARTIFACT_ID_RE.test(artifactId)) return null;
+
+  const sessionFile = await findSessionFileById(sessionId);
+  if (!sessionFile) return null;
+  const dir = siblingDirForSession(sessionFile);
+  if (!existsSync(dir)) return null;
+
+  const candidates = kind && isArtifactKind(kind) ? [kind] : [...ARTIFACT_KINDS];
+  for (const candidate of candidates) {
+    const filePath = path.join(dir, `${artifactId}.${candidate}.log`);
+    // Boundary check: the id is digits and the kind is from the table, but the
+    // resolved path is what actually reaches the filesystem.
+    if (!filePath.startsWith(`${dir}${path.sep}`)) continue;
+    const stat = await fsp.stat(filePath).catch(() => null);
+    if (!stat?.isFile()) continue;
+
+    if (stat.size <= MAX_ARTIFACT_BYTES) {
+      return { text: await fsp.readFile(filePath, 'utf8'), truncated: false, size: stat.size, kind: candidate };
+    }
+    // Too big to serve whole: keep the tail, which is where a log's answer is.
+    const handle = await fsp.open(filePath, 'r');
+    try {
+      const buffer = Buffer.alloc(MAX_ARTIFACT_BYTES);
+      await handle.read(buffer, 0, MAX_ARTIFACT_BYTES, stat.size - MAX_ARTIFACT_BYTES);
+      return { text: buffer.toString('utf8'), truncated: true, size: stat.size, kind: candidate };
+    } finally {
+      await handle.close();
+    }
+  }
+  return null;
+}