akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

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

@@ -0,0 +1,147 @@
+// 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/.
+/**
+ * Amazon Q Developer CLI agent command builder (P2, plan §"The adapter
+ * contract" step 2 / §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `q` CLI expects. Per the capability matrix the headless
+ * invocation is:
+ *
+ *   q chat --no-interactive --trust-all-tools "<prompt>"
+ *
+ * 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
+ * unit rows remain the durable resume source of truth regardless (plan
+ * §"Session, MCP, and identity across harnesses").
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **subcommand** — headless dispatch is the `chat` subcommand. The builder
+ *   prepends `chat` itself (mirroring the codex builder's `exec` handling); a
+ *   user profile that already pins `chat` as its first arg is not doubled.
+ * - **prompt** — the trailing positional `[INPUT]` argument of `q chat`,
+ *   preceded by the `--` end-of-options separator (mirroring the
+ *   claude/codex/pi builders) so a prompt whose text begins with `-`/`--` can
+ *   never be parsed as flags. `--no-interactive` makes Q print the response
+ *   and exit instead of opening the REPL.
+ * - **systemPrompt** — `q chat` has no system-prompt flag (persona/context
+ *   comes from Q's own agent config files), so the system prompt is folded
+ *   into the positional payload ahead of the task prompt, separated by a
+ *   blank line. `assertNotFlag` still guards it.
+ * - **schema** — the matrix places Q in the NO-structured-output tier
+ *   ("via prompt+validate": *(none documented)* — there is no `--json` or
+ *   `--output-format` to ask for). The JSON Schema is therefore passed
+ *   through the prompt: a directive matching the engine's wording
+ *   (`step-work.ts` `buildUnitPrompt`) is appended to the payload.
+ *   Stdout stays plain text; `./result-extractor.ts` strips terminal framing
+ *   and the engine's shared embedded-JSON parse + retry-until-valid loop does
+ *   the rest. No schema temp file is written — that seam is codex-only
+ *   (`--output-schema`); inventing a flag here would produce a silently
+ *   broken command.
+ * - **tools** — a string/array tool policy maps to Q's documented
+ *   `--trust-tools=<t1,t2>` allowlist flag (equals-joined, per `q chat
+ *   --help`). With no policy at all, headless runs need autonomy, so
+ *   `--trust-all-tools` is emitted per the matrix. A *structured* policy
+ *   object is NOT expressible as Q flags; it is deliberately dropped without
+ *   falling back to `--trust-all-tools` (never silently widen a restriction)
+ *   — Q then refuses untrusted tool actions in non-interactive mode, which is
+ *   the conservative failure mode.
+ * - **effort** — stays unconsumed (reserved; the shared request contract's
+ *   "no builder consumes it yet" note stays true).
+ *
+ * Registered: `amazonqBuilder` is `AmazonqHarness.agentBuilder`
+ * (`./index.ts`), one of the ten harnesses `HARNESS_REGISTRY` constructs
+ * (`harnesses/index.ts`); `agent/builders.ts` derives `BUILTIN_BUILDERS` from
+ * that registry, so this builder is reachable under the `"amazonq"` platform
+ * name without any further wiring. The registry-side capability entry —
+ * pattern `local-runner`, structuredOutput `none` — is declared alongside it
+ * (`./index.ts`).
+ */
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
+/** Canonical harness/platform id used for model-alias resolution. */
+export const AMAZONQ_PLATFORM = "amazonq";
+/**
+ * Split a tool policy into individual tool names for `--trust-tools`.
+ * Strings are comma-separated lists; arrays are taken as-is. Structured
+ * policy objects return `undefined` (not expressible as Q flags — see
+ * module doc).
+ */
+function toolPolicyEntries(tools) {
+    if (typeof tools === "string") {
+        return tools
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(tools)) {
+        return tools.map((t) => t.trim()).filter(Boolean);
+    }
+    return undefined;
+}
+/**
+ * Assemble the positional prompt payload: optional system prompt, the task
+ * prompt, and — when a schema is requested — the same schema directive the
+ * workflow engine's prompt assembly uses, so both dispatch paths speak one
+ * dialect.
+ */
+function buildPromptPayload(req) {
+    const sections = [];
+    if (req.systemPrompt)
+        sections.push(req.systemPrompt);
+    sections.push(req.prompt);
+    if (req.schema) {
+        sections.push(`Respond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`);
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Amazon Q Developer CLI builder.
+ * Command shape:
+ *   q chat --no-interactive (--trust-all-tools | --trust-tools=<t1,t2>)
+ *          [--model <m>] -- "<systemPrompt?\n\nprompt\n\nschema directive?>"
+ */
+export const amazonqBuilder = {
+    platform: AMAZONQ_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        // Built-in q profiles would ship `args: []`; headless dispatch is the
+        // `chat` subcommand. Don't double it when a user profile already pins it.
+        const extra = profile.args[0] === "chat" ? profile.args.slice(1) : [...profile.args];
+        const args = ["chat", ...extra];
+        // Print the response and exit — required for captured dispatch.
+        args.push("--no-interactive");
+        if (req.tools) {
+            // Structured policy objects (entries === undefined) emit NO trust
+            // flags: dropping a restriction must never widen to --trust-all-tools.
+            const entries = toolPolicyEntries(req.tools);
+            if (entries !== undefined) {
+                for (const tool of entries) {
+                    assertNotFlag(tool, "tools entry");
+                }
+                // Q's documented allowlist form is equals-joined and comma-separated
+                // (`--trust-tools=fs_read,fs_write`); an empty list trusts no tools.
+                args.push(`--trust-tools=${entries.join(",")}`);
+            }
+        }
+        else {
+            // Headless default per the capability matrix: units must run without
+            // interactive tool-approval prompts.
+            args.push("--trust-all-tools");
+        }
+        if (req.model) {
+            const resolved = resolveDispatchModel(req, profile, AMAZONQ_PLATFORM);
+            args.push("--model", resolved);
+        }
+        // No system-prompt / schema flags exist on `q chat` — both travel in the
+        // positional payload, after the end-of-options separator.
+        args.push("--");
+        args.push(buildPromptPayload(req));
+        return { argv: [profile.bin, ...args] };
+    },
+};

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

@@ -0,0 +1,45 @@
+// 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/.
+/**
+ * Amazon Q Developer CLI harness (P2 integration, plan §"The adapter
+ * contract").
+ *
+ * Per-harness barrel gathering the Amazon Q integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (amazonqBuilder)
+ *   - result extractor      → ./result-extractor.ts (amazonqResultExtractor)
+ *
+ * It also defines {@link AmazonqHarness}, the {@link AkmHarness} descriptor
+ * 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 { amazonqBuilder } from "./agent-builder.js";
+import { amazonqResultExtractor } from "./result-extractor.js";
+export { AMAZONQ_PLATFORM, amazonqBuilder } from "./agent-builder.js";
+export { amazonqResultExtractor, stripTerminalFraming } from "./result-extractor.js";
+/**
+ * Amazon Q Developer CLI (`q`).
+ *
+ * Canonical id is `'amazonq'`; no alias or distinct runtime identity.
+ */
+export class AmazonqHarness extends BaseHarness {
+    id = "amazonq";
+    displayName = "Amazon Q Developer CLI";
+    aliases = [];
+    agentBuilder = amazonqBuilder;
+    resultExtractor = amazonqResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns `q chat` locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // No documented structured output: akm injects the schema into the prompt
+    // and extracts embedded JSON from plain-text stdout.
+    structuredOutput = "none";
+    // No `identityEnv`: the matrix lists Q's identity markers as uncertain, and
+    // Q stamps no session var onto child processes.
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

package/dist/integrations/harnesses/amazonq/result-extractor.js

@@ -0,0 +1,48 @@
+// 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/.
+const ESC = "\u001B";
+const BEL = "\u0007";
+/**
+ * Matches ANSI CSI sequences (colors, cursor movement, erase-line) and OSC
+ * sequences (title, hyperlink) terminated by BEL or ST. Built via the RegExp
+ * constructor so the control characters live in named string constants
+ * instead of regex-literal escapes.
+ */
+const ANSI_SEQUENCE = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]` + `|${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "g");
+/**
+ * Resolve carriage-return overwrites within one physical line: a terminal
+ * would redraw from column 0 at each `\r`, so only the segment after the last
+ * `\r` survives (spinner frames like "⠋ Thinking..." disappear exactly as
+ * they do on screen). A trailing bare `\r` (CRLF line endings) is handled by
+ * splitting on `\r?\n` before this runs.
+ */
+function resolveCarriageReturns(line) {
+    const lastCr = line.lastIndexOf("\r");
+    return lastCr === -1 ? line : line.slice(lastCr + 1);
+}
+/** Strip terminal framing from raw captured stdout. See module doc, rule 1. */
+export function stripTerminalFraming(raw) {
+    const lines = raw.split(/\r?\n/).map((line) => resolveCarriageReturns(line).replace(ANSI_SEQUENCE, ""));
+    // Drop Q's "> " response marker from the first non-empty line only — deeper
+    // occurrences may be legitimate content (markdown blockquotes).
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim().length === 0)
+            continue;
+        if (line.startsWith("> "))
+            lines[i] = line.slice(2);
+        break;
+    }
+    return lines.join("\n").trim();
+}
+/**
+ * Normalize a raw Amazon Q run result into `{ text, sessionId? }`.
+ * See the module doc for the rules.
+ */
+export const amazonqResultExtractor = (result) => {
+    const sessionId = result.sessionId;
+    // Rule 2: a pre-parsed whole-stdout JSON *string* is the answer itself.
+    const text = typeof result.parsed === "string" ? result.parsed.trim() : stripTerminalFraming(result.stdout);
+    return { text, ...(sessionId ? { sessionId } : {}) };
+};

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

@@ -11,15 +11,48 @@
  * in `agent/builders.ts`, which imports this builder back into
  * `BUILTIN_BUILDERS`.
  *
- * Behaviour-preserving relocation: the produced argv is byte-identical to the
- * pre-migration `claudeBuilder`. The builder's `platform` stays `'claude'` (the
- * canonical harness id).
+ * ## Structured output (Codex round-3 finding A)
+ *
+ * The headless `claude -p` (`--print`) CLI has NO native output-SCHEMA flag
+ * (unlike Codex's `--output-schema <file>`). Its documented structured path is
+ * `--output-format json`, which wraps the run in a RESULT ENVELOPE
+ * (`{"type":"result","result":"<final answer>","session_id":"…", …}`) — the
+ * "native-json" tier, NOT "native-schema". (The registry's earlier
+ * `native-schema` claim described Claude Code's IN-HARNESS `Workflow`/`agent()`
+ * tool-input-schema path, which is a different execution surface than the
+ * agentBuilder dispatch akm's local-runner uses; the descriptor is aligned to
+ * `native-json` to match this builder honestly.)
+ *
+ * So for a schema-bearing unit this builder emits `--output-format json` and
+ * appends the SAME schema directive the engine's prompt assembly uses
+ * (`step-work.ts` `buildUnitPrompt`) so a direct (non-workflow) dispatch is
+ * self-sufficient — matching the copilot/gemini native-json builders. The
+ * result envelope is unwrapped by `./result-extractor.ts`, and the engine's
+ * shared `runStructured` retry-until-valid loop still validates the extracted
+ * text against the node schema (constrained/hinted output is trusted but
+ * verified). Without a schema the argv is byte-identical to the pre-fix shape.
+ *
+ * The builder's `platform` stays `'claude'` (the canonical harness id).
  */
-import { assertNotFlag, normalizeTools } from "../../agent/builder-shared.js";
-import { resolveModel } from "../../agent/model-aliases.js";
+import { assertNotFlag, normalizeTools, resolveDispatchModel, } from "../../agent/builder-shared.js";
+/**
+ * Assemble the positional prompt: the task prompt and — when a schema is
+ * requested — the same schema directive the workflow engine's prompt assembly
+ * uses (`step-work.ts` `buildUnitPrompt`), so both dispatch paths speak one
+ * dialect. Claude Code takes the system prompt as a `--system-prompt` FLAG (it
+ * has one, unlike copilot/gemini), so only the schema directive is folded in
+ * here.
+ */
+function buildPromptPayload(req) {
+    if (!req.schema)
+        return req.prompt;
+    return `${req.prompt}\n\nRespond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`;
+}
 /**
  * Claude Code builder.
- * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
+ * Command shape:
+ *   claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>]
+ *          [--output-format json] --print -- "<prompt (+ schema directive)>"
  *
  * --print switches Claude Code to non-interactive captured output mode.
  */
@@ -33,16 +66,21 @@ export const claudeBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, "claude", profile.modelAliases, profile.globalModelAliases);
+            const resolved = resolveDispatchModel(req, profile, "claude");
             args.push("--model", resolved);
         }
         if (req.tools) {
             args.push("--allowedTools", normalizeTools(req.tools));
         }
+        if (req.schema) {
+            // Structured unit: request the documented JSON result envelope so
+            // `./result-extractor.ts` can pull the final answer + session id.
+            args.push("--output-format", "json");
+        }
         // --print = non-interactive, outputs to stdout — required for captured mode
         args.push("--print");
         args.push("--");
-        args.push(req.prompt);
+        args.push(buildPromptPayload(req));
         return { argv: [profile.bin, ...args] };
     },
 };

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,45 +1,15 @@
 // 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/.
-/**
- * Claude Code harness (#563).
- *
- * This is the per-harness barrel that gathers the Claude Code integration
- * surfaces that were previously scattered across the codebase:
- *   - session-log reader     → ./session-log.ts   (ClaudeCodeProvider)
- *   - agent command builder  → ./agent-builder.ts (claudeBuilder)
- *   - config importer        → ./config-import.ts (claudeCodeImporter)
- *
- * It also defines {@link ClaudeHarness}, the {@link AkmHarness} descriptor that
- * `HARNESS_REGISTRY` registers.
- *
- * ## id normalization bridge ('claude' vs 'claude-code')
- *
- * The canonical, persisted id is `'claude'` (used by the agent runner, agent
- * profiles, the Zod config schema and `--type` resolution after normalization).
- * `'claude-code'` is the historical RUNTIME identity — the string stamped on
- * session-log events/refs, the extracted-session dedup key, and the value
- * `resolveAgentIdentity` reports. It is registered as an `alias` and exposed as
- * `runtimeId` so BOTH directions round-trip via `normalizeHarnessId()` /
- * `denormalizeRuntimeIdentity()`. Existing persisted configs and session logs
- * that say `'claude-code'` keep working unchanged.
- */
+import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 import { claudeBuilder } from "./agent-builder.js";
+import { claudeResultExtractor } from "./result-extractor.js";
+import { ClaudeCodeProvider } from "./session-log.js";
 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,
-        v1Migration: false,
-        ...c,
-    };
-}
 /**
  * Claude Code.
  *
@@ -55,12 +25,31 @@ export class ClaudeHarness extends BaseHarness {
     // session-log provider, so offering it as a stash source is functional.
     setupDetectionDir = ".claude";
     agentBuilder = claudeBuilder;
+    resultExtractor = claudeResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // Claude Code is the in-harness pattern: the orchestrating session itself
+    // drives units via the `akm workflow` gate spine (`claude -p` headless
+    // dispatch also exists via `agentBuilder`, but the pattern classification
+    // follows the matrix row).
+    pattern = "in-harness";
+    // Structured output tier for the AGENT-DISPATCH (`claude -p`) path akm's
+    // local runner uses (Codex round-3 finding A). The headless CLI has NO
+    // output-schema flag — its documented structured path is `--output-format
+    // json`, a RESULT ENVELOPE akm parses (`./result-extractor.ts`) and then
+    // validates against the node schema ⇒ the "native-json" tier. (Claude Code's
+    // in-harness `Workflow`/`agent()` tool-input-schema path IS native-schema,
+    // but that is a different surface than the dispatch builder — the descriptor
+    // is aligned to what the builder honestly does.)
+    structuredOutput = "native-json";
+    // 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"];
+    sessionLogProvider = () => new ClaudeCodeProvider();
     capabilities = caps({
         sessionLogs: true,
         agentDispatch: true,
         detection: true,
         configImport: true,
         runtimeIdentity: true,
-        v1Migration: true,
     });
 }

package/dist/integrations/harnesses/claude/result-extractor.js

@@ -0,0 +1,52 @@
+// 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/.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** JSON.parse that returns undefined instead of throwing. */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is this parsed object Claude Code's `--output-format json` RESULT ENVELOPE
+ * (rather than a bare JSON answer a schema unit produced without the flag)? A
+ * genuine envelope declares `type: "result"`, or carries the two envelope-only
+ * fields together (a string `result` AND a `session_id`). A bare structured
+ * answer — `{"result":"ok"}` — carries neither marker, so it is passed through
+ * raw and the engine's schema validator sees the whole object.
+ */
+function isResultEnvelope(value) {
+    if (value.type === "result")
+        return true;
+    return typeof value.result === "string" && asNonEmptyString(value.session_id) !== undefined;
+}
+/**
+ * Normalize a raw claude run result into `{ text, sessionId? }`. See the module
+ * doc for the two stdout shapes (JSON result envelope vs plain text).
+ */
+export const claudeResultExtractor = (result) => {
+    const fallbackSessionId = result.sessionId;
+    const raw = result.stdout;
+    const trimmed = raw.trim();
+    // Only attempt an envelope parse when stdout looks like a single JSON object
+    // (`--output-format json`). A plain-text run is passed through UNCHANGED
+    // (untrimmed) so schemaless dispatch stays byte-identical to today.
+    if (trimmed.startsWith("{")) {
+        const whole = result.parsed !== undefined ? result.parsed : tryParseJson(trimmed);
+        if (isRecord(whole) && isResultEnvelope(whole)) {
+            const text = typeof whole.result === "string" ? whole.result : trimmed;
+            const sessionId = asNonEmptyString(whole.session_id) ?? fallbackSessionId;
+            return { text, ...(sessionId ? { sessionId } : {}) };
+        }
+    }
+    return { text: raw, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+};

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,22 +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());
-    }
-    /**
-     * Directory holding Claude Code's per-project session JSONL files
-     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
-     * when the directory does not exist on this machine. See {@link
-     * SessionLogHarness.watchRoots}.
-     */
-    watchRoots() {
-        const dir = claudeProjectsDir();
-        return fs.existsSync(dir) ? [dir] : [];
+    availabilityRoot() {
+        return claudeProjectsDir();
     }
     *readEvents(input) {
         try {
@@ -124,25 +115,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 +130,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 +183,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 +264,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");
     }
 }