akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/integrations/agent/spawn.js

@@ -18,35 +18,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { spawn as runtimeSpawn } from "../../runtime.js";
+import { runManagedSubprocess, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-/**
- * Kill the process group of `proc` with `signal`, falling back to
- * `proc.kill(signal)` when `proc.pid` is unavailable (e.g. test fakes).
- *
- * Passing a negative PID to `process.kill` targets the entire process
- * group, so opencode's child processes (the .opencode binary, etc.) are
- * reaped alongside the node wrapper. The fallback keeps test fakes working
- * without modification.
- */
-function killGroup(proc, signal) {
-    if (typeof proc.pid === "number") {
-        try {
-            process.kill(-proc.pid, signal);
-            return;
-        }
-        catch {
-            // Process may have already exited; fall through to direct kill.
-        }
-    }
-    try {
-        proc.kill(signal);
-    }
-    catch {
-        /* ignore */
-    }
-}
 const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
 /**
  * Supplement `existingPath` with well-known user binary directories when
@@ -102,14 +76,6 @@ function pathCandidatesForCurrentPlatform(home) {
         "/usr/local/bin",
     ];
 }
-function resolveSpawnFn(options) {
-    if (options.spawn)
-        return options.spawn;
-    // Default to the runtime-boundary spawn, which delegates to the native
-    // subprocess API on each runtime. Tests inject `options.spawn` to avoid
-    // poking real binaries.
-    return runtimeSpawn;
-}
 /**
  * Build the child env. Starts empty and copies through:
  *   • Every name in `profile.envPassthrough`.
@@ -143,80 +109,6 @@ function buildChildEnv(profile, options) {
     }
     return env;
 }
-const STREAM_READ_TIMEOUT = Symbol("stream-read-timeout");
-async function readStream(stream, opts) {
-    if (!stream)
-        return { text: "", timedOut: false };
-    const reader = stream.getReader();
-    const decoder = new TextDecoder();
-    let text = "";
-    if (!opts?.timeoutMs) {
-        try {
-            while (true) {
-                const chunk = await reader.read();
-                if (chunk.done)
-                    break;
-                text += decoder.decode(chunk.value, { stream: true });
-            }
-            text += decoder.decode();
-            return { text, timedOut: false };
-        }
-        catch (error) {
-            return { text, timedOut: false, error };
-        }
-        finally {
-            try {
-                reader.releaseLock();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-    }
-    // Race the stream read against a timeout so a process that is killed via
-    // SIGTERM/SIGKILL but whose pipe endpoints stay open (e.g. background
-    // threads still holding the fd) cannot block the caller indefinitely.
-    // On timeout we return whatever was decoded before the pipe stopped draining.
-    const setTimeoutImpl = opts.setTimeoutFn ?? setTimeout;
-    const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
-    let timer;
-    const timeoutPromise = new Promise((resolve) => {
-        timer = setTimeoutImpl(() => {
-            timer = undefined;
-            resolve(STREAM_READ_TIMEOUT);
-        }, opts.timeoutMs);
-        if (typeof timer !== "number")
-            timer.unref?.();
-    });
-    try {
-        while (true) {
-            const chunk = await Promise.race([reader.read(), timeoutPromise]);
-            if (chunk === STREAM_READ_TIMEOUT) {
-                void reader.cancel().catch(() => { });
-                return { text, timedOut: true };
-            }
-            if (chunk.done)
-                break;
-            text += decoder.decode(chunk.value, { stream: true });
-        }
-        text += decoder.decode();
-        return { text, timedOut: false };
-    }
-    catch (error) {
-        return { text, timedOut: false, error };
-    }
-    finally {
-        if (timer !== undefined) {
-            clearTimeoutImpl(timer);
-        }
-        try {
-            reader.releaseLock();
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
 function streamFailureMessage(profileName, stdout, stderr) {
     const failures = [];
     if (stdout.error)
@@ -300,159 +192,43 @@ export async function runAgent(profile, prompt, options = {}) {
             error: `agent CLI "${profile.name}" not started: caller signal already aborted`,
         };
     }
-    let proc;
-    try {
-        const spawnFn = resolveSpawnFn(options);
-        proc = spawnFn(finalArgv, {
-            stdin: stdioMode === "captured" ? (options.stdin !== undefined ? "pipe" : "ignore") : "inherit",
-            stdout: stdioMode === "captured" ? "pipe" : "inherit",
-            stderr: stdioMode === "captured" ? "pipe" : "inherit",
-            env,
-            ...(options.cwd ? { cwd: options.cwd } : {}),
-            // Spawn in its own process group so killGroup(-pid, signal) reaches all
-            // descendants (e.g. the .opencode binary that opencode's node wrapper forks).
-            // Only applied in captured mode — interactive mode inherits the parent
-            // terminal's process group intentionally.
-            ...(stdioMode === "captured" ? { detached: true } : {}),
-        });
-    }
-    catch (err) {
-        const durationMs = Date.now() - start;
-        return {
-            ok: false,
-            exitCode: null,
-            stdout: "",
-            stderr: "",
-            durationMs,
-            reason: "spawn_failed",
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-    emitSpawnEvent("spawn_start", {
-        profile: profile.name,
-        ...(typeof proc.pid === "number" ? { pid: proc.pid } : {}),
-    });
-    // Hard timeout. We prefer SIGTERM, then SIGKILL if SIGTERM is ignored,
-    // but the subprocess only exposes a single .kill() — one signal is enough
-    // for the structured-failure contract.
+    // Spawn/timeout/abort/capture are owned by the managed-subprocess primitive
+    // (src/core/subprocess.ts): process-GROUP spawn (detached in captured mode),
+    // the SIGTERM→SIGKILL kill ladder on timeout/abort, bounded output capture,
+    // and the optional stdin payload. runAgent keeps its agent-specific surface —
+    // the onEvent observability seam, the failure taxonomy, and JSON parsing.
     //
-    // BUG-M3: only flag `timedOut` when the child has not already exited. A
-    // timer firing in the same microtask as `proc.exited` resolving could
-    // otherwise label a clean exit as a timeout.
-    //
-    // When timeoutMs is null the kill timer is skipped entirely — the task runs
-    // until the process exits naturally. Intended for long-running local-model
-    // tasks where wall-clock time is unpredictable.
-    let timedOut = false;
-    let timer;
-    if (timeoutMs !== null) {
-        timer = setTimeoutImpl(() => {
-            if (!proc || proc.exitCode !== null)
-                return;
-            timedOut = true;
-            killGroup(proc, "SIGTERM");
-            // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
-            const sigkillTimer = setTimeoutImpl(() => {
-                if (!proc || proc.exitCode !== null)
-                    return;
-                killGroup(proc, "SIGKILL");
-            }, 5000);
-            if (typeof sigkillTimer !== "number")
-                sigkillTimer.unref?.();
-        }, timeoutMs);
-    }
-    // Cooperative cancel: same SIGTERM→SIGKILL discipline as the timeout, but
-    // flagged separately so the result carries `reason: "aborted"`.
-    let aborted = false;
-    const abortSignal = options.signal;
-    const onAbort = () => {
-        if (!proc || proc.exitCode !== null)
-            return;
-        aborted = true;
-        killGroup(proc, "SIGTERM");
-        const sigkillTimer = setTimeoutImpl(() => {
-            if (!proc || proc.exitCode !== null)
-                return;
-            killGroup(proc, "SIGKILL");
-        }, 5000);
-        if (typeof sigkillTimer !== "number")
-            sigkillTimer.unref?.();
-    };
-    if (abortSignal) {
-        // A signal that aborted between the pre-spawn check and here is handled
-        // by calling the listener directly.
-        if (abortSignal.aborted)
-            onAbort();
-        else
-            abortSignal.addEventListener("abort", onAbort, { once: true });
-    }
-    // Stream-drain timeout: the overall wall-clock budget plus a 2 s grace
-    // period. When a process is killed via SIGTERM/SIGKILL (from our timeout
-    // handler or from outside) some runtimes keep the pipe write-end open in
-    // background threads, which would cause `Response.text()` to block forever.
-    // Capping stream draining ensures the caller never hangs past the wall
-    // budget regardless of subprocess pipe behaviour.
-    // When there is no kill timer, allow up to 30 s for streams to drain.
-    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
-    const stdoutPromise = stdioMode === "captured"
-        ? readStream(proc.stdout ?? null, {
-            timeoutMs: streamDrainTimeoutMs,
-            setTimeoutFn: setTimeoutImpl,
-            clearTimeoutFn: clearTimeoutImpl,
-        })
-        : Promise.resolve({ text: "", timedOut: false });
-    const stderrPromise = stdioMode === "captured"
-        ? readStream(proc.stderr ?? null, {
-            timeoutMs: streamDrainTimeoutMs,
-            setTimeoutFn: setTimeoutImpl,
-            clearTimeoutFn: clearTimeoutImpl,
-        })
-        : Promise.resolve({ text: "", timedOut: false });
-    // Optional stdin payload (captured mode only).
-    //
-    // BUG-H1: race the stdin write/close against `proc.exited` and the
-    // timeout timer. If the child never drains stdin, an unraced
-    // `await writer.write()` would block forever and prevent `runAgent`
-    // from ever returning.
-    if (options.stdin !== undefined && stdioMode === "captured" && proc.stdin) {
-        const stdinPayload = options.stdin;
-        const stdinStream = proc.stdin;
-        const stdinDone = (async () => {
-            try {
-                const writer = stdinStream.getWriter();
-                const bytes = new TextEncoder().encode(stdinPayload);
-                await writer.write(bytes);
-                await writer.close();
-            }
-            catch {
-                // Best-effort: ignore stdin write failures, the child will get EOF.
-            }
-        })();
-        // Resolve as soon as either the write completes or the child exits.
-        // We don't await the result — only that one of the two has settled —
-        // so a stuck writer cannot keep us pinned past the timeout.
-        await Promise.race([stdinDone, proc.exited.catch(() => undefined)]);
-    }
-    let exitCode = null;
-    try {
-        exitCode = await proc.exited;
-    }
-    catch (err) {
-        if (timer !== undefined)
-            clearTimeoutImpl(timer);
-        abortSignal?.removeEventListener("abort", onAbort);
-        // BUG-H2: drain stream readers before the early return so they don't
-        // surface as unhandled rejections after the function resolves.
-        // The streams already carry a built-in drain timeout so this allSettled
-        // will not block indefinitely.
-        await Promise.allSettled([stdoutPromise, stderrPromise]);
-        const durationMs = Date.now() - start;
-        emitSpawnEvent("spawn_exit", {
-            profile: profile.name,
-            ...(typeof proc.pid === "number" ? { pid: proc.pid } : {}),
-            exitCode: null,
-            status: "spawn_failed",
-        });
+    // `onSpawn` fires spawn_start once the child is live (never for a pre-spawn
+    // abort or a synchronous spawn failure), and captures the proc so spawn_exit
+    // can carry the same pid.
+    let spawnedProc;
+    const result = await runManagedSubprocess(finalArgv, {
+        capture: stdioMode === "captured",
+        env,
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
+        timeoutMs,
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.spawn ? { spawnFn: options.spawn } : {}),
+        setTimeoutFn: setTimeoutImpl,
+        clearTimeoutFn: clearTimeoutImpl,
+        onSpawn: (proc) => {
+            spawnedProc = proc;
+            emitSpawnEvent("spawn_start", {
+                profile: profile.name,
+                ...(typeof proc.pid === "number" ? { pid: proc.pid } : {}),
+            });
+        },
+    });
+    const pidField = spawnedProc && typeof spawnedProc.pid === "number" ? { pid: spawnedProc.pid } : {};
+    const durationMs = Date.now() - start;
+    // Spawn/exit failure. A synchronous spawn throw never reached a live child
+    // (no spawn_start fired, so no spawn_exit either); a rejected proc.exited did
+    // (spawn_start already fired, so it emits a spawn_exit with status spawn_failed).
+    if (result.spawnError) {
+        if (spawnedProc) {
+            emitSpawnEvent("spawn_exit", { profile: profile.name, ...pidField, exitCode: null, status: "spawn_failed" });
+        }
         return {
             ok: false,
             exitCode: null,
@@ -460,21 +236,16 @@ export async function runAgent(profile, prompt, options = {}) {
             stderr: "",
             durationMs,
             reason: "spawn_failed",
-            error: err instanceof Error ? err.message : String(err),
+            error: result.spawnError.message,
         };
     }
-    clearTimeoutImpl(timer);
-    abortSignal?.removeEventListener("abort", onAbort);
+    const { exitCode, timedOut, aborted, stdout, stderr } = result;
     emitSpawnEvent("spawn_exit", {
         profile: profile.name,
-        ...(typeof proc.pid === "number" ? { pid: proc.pid } : {}),
+        ...pidField,
         exitCode,
         status: aborted ? "aborted" : timedOut ? "timeout" : exitCode !== 0 ? "non_zero_exit" : "ok",
     });
-    const [stdoutRead, stderrRead] = await Promise.all([stdoutPromise, stderrPromise]);
-    const stdout = stdoutRead.text;
-    const stderr = stderrRead.text;
-    const durationMs = Date.now() - start;
     if (aborted) {
         return {
             ok: false,
@@ -497,7 +268,7 @@ export async function runAgent(profile, prompt, options = {}) {
             error: `agent CLI "${profile.name}" timed out after ${timeoutMs ?? 0}ms`,
         };
     }
-    const captureFailure = streamFailureMessage(profile.name, stdoutRead, stderrRead);
+    const captureFailure = streamFailureMessage(profile.name, result.stdoutRead, result.stderrRead);
     if (captureFailure) {
         return {
             ok: false,

package/dist/integrations/harnesses/aider/agent-builder.js

@@ -52,7 +52,7 @@
  *   therefore dropped rather than approximated — never silently widened.
  * - **resume/session** — NOT expressible: Aider persists context in
  *   chat-history files (`.aider.chat.history.md`), not session ids, so there
- *   is no flag-shaped `HarnessResumeSupport` to export and the extractor
+ *   is no flag-shaped resume to describe and the extractor
  *   never yields a `sessionId`. akm's `workflow_run_units` remains the
  *   durable source of truth; resume works even against a harness with no
  *   session model (plan §"Session, MCP, and identity across harnesses" —
@@ -62,7 +62,7 @@
  *
  * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
  * follow-up integration task (as is the registry entry declaring
- * `structuredOutput: "none"` and no `resume`). Exported standalone so that
+ * `structuredOutput: "none"`). Exported standalone so that
  * task only adds a registry entry.
  */
 import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";

package/dist/integrations/harnesses/aider/index.js

@@ -12,21 +12,12 @@
  * `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log reader or
  * config importer yet.
  */
+import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 import { aiderBuilder } from "./agent-builder.js";
 import { aiderResultExtractor } from "./result-extractor.js";
 export { AIDER_PLATFORM, aiderBuilder } from "./agent-builder.js";
 export { aiderResultExtractor } from "./result-extractor.js";
-function caps(c) {
-    return {
-        sessionLogs: false,
-        agentDispatch: false,
-        detection: false,
-        configImport: false,
-        runtimeIdentity: false,
-        ...c,
-    };
-}
 /**
  * Aider.
  *
@@ -44,7 +35,7 @@ export class AiderHarness extends BaseHarness {
     // No structured-output mode at all (the matrix's "none — parse output"):
     // akm injects the schema into the prompt and extracts embedded JSON.
     structuredOutput = "none";
-    // No `resume`: Aider persists context in chat-history files
+    // No flag-shaped resume: Aider persists context in chat-history files
     // (`.aider.chat.history.md`), not session ids — the plan's named example of
     // a harness with no session model. akm's `workflow_run_units` remains the
     // durable resume source of truth.

package/dist/integrations/harnesses/amazonq/agent-builder.js

@@ -11,8 +11,7 @@
  *
  *   q chat --no-interactive --trust-all-tools "<prompt>"
  *
- * with `--model <m>` for model selection and `--resume` for resume. Resume is
- * registry-side (`AkmHarness.resume`, {@link AMAZONQ_RESUME_FLAG}) — and NOTE:
+ * with `--model <m>` for model selection and `--resume` for resume — NOTE:
  * unlike every other harness's resume, Q's `--resume` is a bare flag that
  * replays the previous conversation *of the working directory*; it takes no
  * session id. There is nothing to thread from `workflow_run_units` — akm's own
@@ -63,13 +62,6 @@
 import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const AMAZONQ_PLATFORM = "amazonq";
-/**
- * Resume flag per the capability matrix (`--resume`). Exported for the
- * integration task's `AkmHarness.resume` registry entry. Bare flag: Q resumes
- * the previous conversation of the current working directory and takes NO
- * session id value — do not append one after it.
- */
-export const AMAZONQ_RESUME_FLAG = "--resume";
 /**
  * Split a tool policy into individual tool names for `--trust-tools`.
  * Strings are comma-separated lists; arrays are taken as-is. Structured

package/dist/integrations/harnesses/amazonq/index.js

@@ -13,21 +13,12 @@
  * that `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log
  * reader or config importer yet.
  */
+import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
-import { AMAZONQ_RESUME_FLAG, amazonqBuilder } from "./agent-builder.js";
+import { amazonqBuilder } from "./agent-builder.js";
 import { amazonqResultExtractor } from "./result-extractor.js";
-export { AMAZONQ_PLATFORM, AMAZONQ_RESUME_FLAG, amazonqBuilder } from "./agent-builder.js";
+export { AMAZONQ_PLATFORM, amazonqBuilder } from "./agent-builder.js";
 export { amazonqResultExtractor, stripTerminalFraming } from "./result-extractor.js";
-function caps(c) {
-    return {
-        sessionLogs: false,
-        agentDispatch: false,
-        detection: false,
-        configImport: false,
-        runtimeIdentity: false,
-        ...c,
-    };
-}
 /**
  * Amazon Q Developer CLI (`q`).
  *
@@ -45,10 +36,6 @@ export class AmazonqHarness extends BaseHarness {
     // No documented structured output: akm injects the schema into the prompt
     // and extracts embedded JSON from plain-text stdout.
     structuredOutput = "none";
-    // Q's `--resume` is a BARE flag (takesSessionId: false): it replays the
-    // previous conversation of the working directory and takes no session id
-    // (see AMAZONQ_RESUME_FLAG in ./agent-builder.ts).
-    resume = { flag: AMAZONQ_RESUME_FLAG, takesSessionId: false };
     // No `identityEnv`: the matrix lists Q's identity markers as uncertain, and
     // Q stamps no session var onto child processes.
     capabilities = caps({

package/dist/integrations/harnesses/claude/config-import.js

@@ -15,9 +15,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-function homeDir() {
-    return process.env.HOME ?? process.env.USERPROFILE ?? "";
-}
+import { homeDir } from "../shared.js";
 /**
  * Imports LLM config from a Claude Code installation.
  *

package/dist/integrations/harnesses/claude/index.js

@@ -1,6 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 import { claudeBuilder } from "./agent-builder.js";
 import { claudeResultExtractor } from "./result-extractor.js";
@@ -9,16 +10,6 @@ export { claudeBuilder } from "./agent-builder.js";
 export { claudeCodeImporter } from "./config-import.js";
 export { claudeResultExtractor } from "./result-extractor.js";
 export { ClaudeCodeProvider } from "./session-log.js";
-function caps(c) {
-    return {
-        sessionLogs: false,
-        agentDispatch: false,
-        detection: false,
-        configImport: false,
-        runtimeIdentity: false,
-        ...c,
-    };
-}
 /**
  * Claude Code.
  *
@@ -50,8 +41,6 @@ export class ClaudeHarness extends BaseHarness {
     // but that is a different surface than the dispatch builder — the descriptor
     // is aligned to what the builder honestly does.)
     structuredOutput = "native-json";
-    // `claude --resume <sessionId>` replays a previous session in headless mode.
-    resume = { flag: "--resume", takesSessionId: true };
     // Session-id env marker: presence of a concrete session id (not the bare
     // "running under Claude Code" flag) attributes a run to this harness.
     identityEnv = ["CLAUDE_SESSION_ID"];

package/dist/integrations/harnesses/claude/session-log.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
+import { AbstractSessionLogProvider } from "../../session-logs/provider-base.js";
 /**
  * Root directory holding Claude Code's per-project JSONL session logs.
  *
@@ -100,12 +101,12 @@ function parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs) {
  * (`getHarness`), and the `--type` flag accepts both, so the canonical id and
  * the persisted runtime string coexist without drift.
  */
-export class ClaudeCodeProvider {
+export class ClaudeCodeProvider extends AbstractSessionLogProvider {
     // Runtime identity (NOT the canonical id) — see class doc. Equals
     // HARNESS_BY_ID.get("claude").runtimeId.
     name = "claude-code";
-    isAvailable() {
-        return fs.existsSync(claudeProjectsDir());
+    availabilityRoot() {
+        return claudeProjectsDir();
     }
     /**
      * Directory holding Claude Code's per-project session JSONL files
@@ -124,25 +125,13 @@ export class ClaudeCodeProvider {
                 if (stat.mtimeMs < input.sinceMs)
                     continue;
                 const lines = fs.readFileSync(jsonlPath, "utf8").split("\n").filter(Boolean);
-                for (const line of lines) {
-                    try {
-                        const entry = JSON.parse(line);
-                        const text = entry?.message?.content ?? entry?.content ?? "";
-                        if (typeof text !== "string" || text.length < 10)
-                            continue;
-                        yield {
-                            harness: this.name,
-                            text,
-                            ts: typeof entry?.timestamp === "number" ? entry.timestamp : stat.mtimeMs,
-                            sessionId: typeof entry?.session_id === "string" ? entry.session_id : undefined,
-                            role: typeof entry?.role === "string" ? entry.role : "unknown",
-                            filePath: jsonlPath,
-                        };
-                    }
-                    catch {
-                        // skip malformed lines
-                    }
-                }
+                yield* this.logLineEvents({
+                    lines,
+                    filePath: jsonlPath,
+                    fallbackTsMs: stat.mtimeMs,
+                    selectText: (entry) => entry?.message?.content ?? entry?.content ?? "",
+                    selectSessionId: (entry) => entry?.session_id,
+                });
             }
         }
         catch {
@@ -151,39 +140,23 @@ export class ClaudeCodeProvider {
     }
     listSessions(input = {}) {
         const root = input.location ?? claudeProjectsDir();
-        const sinceMs = input.sinceMs ?? 0;
-        const summaries = [];
-        try {
-            for (const jsonlPath of this.#walkJsonl(root)) {
-                let stat;
-                try {
-                    stat = fs.statSync(jsonlPath);
-                }
-                catch {
-                    continue;
-                }
-                if (stat.mtimeMs < sinceMs)
-                    continue;
-                const sessionId = path.basename(jsonlPath, ".jsonl");
-                const projectHint = path.basename(path.dirname(jsonlPath));
+        return this.listSessionsFromFiles({
+            sinceMs: input.sinceMs ?? 0,
+            enumerate: () => this.#walkJsonl(root),
+            summarize: (jsonlPath, stat) => {
                 // Peek first + last non-empty line to derive start/end timestamps and
                 // title. Reading the whole file would be wasteful for listing.
                 const peek = this.#peekJsonl(jsonlPath);
-                summaries.push({
-                    harness: this.name,
-                    sessionId,
+                return this.sessionRef({
+                    sessionId: path.basename(jsonlPath, ".jsonl"),
                     filePath: jsonlPath,
                     startedAt: peek.firstTsMs ?? stat.ctimeMs,
                     endedAt: peek.lastTsMs ?? stat.mtimeMs,
-                    projectHint,
-                    ...(peek.title ? { title: peek.title } : {}),
+                    projectHint: path.basename(path.dirname(jsonlPath)),
+                    title: peek.title,
                 });
-            }
-        }
-        catch {
-            // Root missing or unreadable — return what we have.
-        }
-        return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
+            },
+        });
     }
     readSession(ref) {
         const stat = fs.statSync(ref.filePath);
@@ -220,15 +193,14 @@ export class ClaudeCodeProvider {
             inlineRefs.push(...extractInlineRefMentions(parsed.text, parsed.ts));
         }
         return {
-            ref: {
-                harness: this.name,
+            ref: this.sessionRef({
                 sessionId: ref.sessionId,
                 filePath: ref.filePath,
                 startedAt: firstTsMs ?? stat.ctimeMs,
                 endedAt: lastTsMs ?? stat.mtimeMs,
                 projectHint,
-                ...(title ? { title } : {}),
-            },
+                title,
+            }),
             events,
             inlineRefs,
         };
@@ -302,18 +274,8 @@ export class ClaudeCodeProvider {
         }
         return result;
     }
-    *#walkJsonl(dir) {
-        try {
-            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-                const full = path.join(dir, entry.name);
-                if (entry.isDirectory())
-                    yield* this.#walkJsonl(full);
-                else if (entry.name.endsWith(".jsonl") && entry.name !== "journal.jsonl")
-                    yield full;
-            }
-        }
-        catch {
-            // permission errors etc.
-        }
+    /** Session JSONL files under `dir`, excluding the shared journal file. */
+    #walkJsonl(dir) {
+        return this.walkFiles(dir, (name) => name.endsWith(".jsonl") && name !== "journal.jsonl");
     }
 }