akm-cli 0.8.7 → 0.8.14

package/dist/integrations/agent/builders.js

@@ -12,88 +12,21 @@
  * Adding a new platform: implement `AgentCommandBuilder`, add to
  * `BUILTIN_BUILDERS`. Nothing else changes.
  */
-import { UsageError } from "../../core/errors";
-import { resolveModel } from "./model-aliases";
-// ── Validation helpers ────────────────────────────────────────────────────────
-/**
- * Guard against values that start with `--`, which would be mis-interpreted as
- * CLI flags by the spawned process when used as flag values (model, systemPrompt).
- * Bun.spawn uses array argv so there is no shell injection, but a `--`-prefixed
- * value passed as the argument to `--model` or `--system-prompt` can still
- * confuse the CLI parser of the target process.
- */
-function assertNotFlag(value, field) {
-    if (value?.trimStart().startsWith("--")) {
-        throw new UsageError(`${field} must not start with "--": ${JSON.stringify(value.slice(0, 60))}`, "INVALID_FLAG_VALUE");
-    }
-}
-// ── Tool normalization ────────────────────────────────────────────────────────
-/**
- * Normalize a toolPolicy value to a comma-separated string suitable for a
- * CLI flag. Structured policy objects are JSON-serialized.
- */
-function normalizeTools(tools) {
-    if (typeof tools === "string")
-        return tools;
-    if (Array.isArray(tools))
-        return tools.join(",");
-    return JSON.stringify(tools);
-}
+import { claudeBuilder } from "../harnesses/claude/agent-builder.js";
+import { opencodeBuilder } from "../harnesses/opencode/agent-builder.js";
+// Types + shared validation helpers live in the leaf module `builder-shared.ts`
+// so per-harness builders (harnesses/claude/agent-builder.ts) can depend on them
+// without importing this file back — avoiding an init-order cycle through
+// BUILTIN_BUILDERS (#563). Re-exported here so existing `agent/builders` import
+// sites keep working.
+import { assertNotFlag } from "./builder-shared.js";
+import { resolveModel } from "./model-aliases.js";
+export { assertNotFlag, normalizeTools } from "./builder-shared.js";
 // ── Platform builders ─────────────────────────────────────────────────────────
-/**
- * OpenCode builder.
- * Command shape: opencode run [--system-prompt "..."] [--model <m>] "<prompt>"
- *
- * Tool policy is omitted — opencode manages tool access through its own agent
- * config files, not via CLI flags.
- */
-const opencodeBuilder = {
-    platform: "opencode",
-    build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
-        const args = [...profile.args]; // starts with ["run"]
-        if (req.systemPrompt) {
-            args.push("--system-prompt", req.systemPrompt);
-        }
-        if (req.model) {
-            const resolved = resolveModel(req.model, "opencode", profile.modelAliases);
-            args.push("--model", resolved);
-        }
-        args.push("--");
-        args.push(req.prompt);
-        return { argv: [profile.bin, ...args] };
-    },
-};
-/**
- * Claude Code builder.
- * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
- *
- * --print switches Claude Code to non-interactive captured output mode.
- */
-const claudeBuilder = {
-    platform: "claude",
-    build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
-        const args = [...profile.args];
-        if (req.systemPrompt) {
-            args.push("--system-prompt", req.systemPrompt);
-        }
-        if (req.model) {
-            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
-            args.push("--model", resolved);
-        }
-        if (req.tools) {
-            args.push("--allowedTools", normalizeTools(req.tools));
-        }
-        // --print = non-interactive, outputs to stdout — required for captured mode
-        args.push("--print");
-        args.push("--");
-        args.push(req.prompt);
-        return { argv: [profile.bin, ...args] };
-    },
-};
+// The OpenCode builder was migrated to its harness directory in #564
+// (`harnesses/opencode/agent-builder.ts`) and the Claude Code builder in #563
+// (`harnesses/claude/agent-builder.ts`). Both are imported back into
+// BUILTIN_BUILDERS below so platform routing is unchanged.
 /**
  * Default builder — used for custom profiles and any platform without a
  * dedicated builder. Passes systemPrompt and model via the same flags as

package/dist/integrations/agent/config.js

@@ -1,9 +1,10 @@
 // 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 { ConfigError } from "../../core/errors";
-import { warn } from "../../core/warn";
-import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
+import { VALID_HARNESS_IDS } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
 /**
  * Default hard timeout for an agent CLI (60s — matches the value used in
  * `docs/configuration.md`).
@@ -141,7 +142,8 @@ export function parseAgentProfilesMapV2(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const out = {};
-    const VALID_PLATFORMS = ["opencode", "claude", "opencode-sdk"];
+    // Derives from the canonical harness-id source of truth (#565).
+    const VALID_PLATFORMS = VALID_HARNESS_IDS;
     for (const [name, raw] of Object.entries(value)) {
         if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
             warn(`[akm] Ignoring profiles.agent["${name}"]: expected an object.`);

package/dist/integrations/agent/detect.js

@@ -15,7 +15,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { listResolvedAgentProfiles } from "./config";
+import { listResolvedAgentProfiles } from "./config.js";
 /**
  * Default PATH lookup. Walks `process.env.PATH` and returns the first
  * existing executable file. Returns `undefined` when the bin is not on

package/dist/integrations/agent/index.js

@@ -1,11 +1,26 @@
 // 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/.
-export { getCommandBuilder } from "./builders";
-export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config";
-export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect";
-export { listBuiltinModelAliases, resolveModel } from "./model-aliases";
-export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
-export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, stripJsonFences, } from "./prompts";
-export { runAgentSdk } from "./sdk-runner";
-export { runAgent } from "./spawn";
+/**
+ * Internal entry point for the `agent` integration. CLI-only project — no
+ * public exports map. Other akm modules import from this barrel for the
+ * sake of grouping imports.
+ *
+ * Surface:
+ *   • Types: AgentProfile, AgentConfig, AgentRunResult, AgentFailureReason.
+ *   • Profiles: getBuiltinAgentProfile, listBuiltinAgentProfiles, BUILTIN_AGENT_PROFILE_NAMES.
+ *   • Config: parseAgentConfig, resolveProfileFromConfig, requireAgentProfile, listResolvedAgentProfiles, listAgentProfileNames.
+ *   • Spawn: runAgent. Builders: getCommandBuilder, AgentCommandBuilder, AgentDispatchRequest — platform-specific argv construction.
+ *   • Detection: detectAgentCliProfiles, pickDefaultAgentProfile, defaultWhich.
+ */
+// The OpenCode SDK runner moved to its harness directory in #564
+// (`harnesses/opencode-sdk/`). Re-exported here so existing `agent/index`
+// import sites keep working.
+export { runAgentSdk } from "../harnesses/opencode-sdk/index.js";
+export { getCommandBuilder } from "./builders.js";
+export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config.js";
+export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
+export { listBuiltinModelAliases, resolveModel } from "./model-aliases.js";
+export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
+export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, stripJsonFences, } from "./prompts.js";
+export { runAgent } from "./spawn.js";

package/dist/integrations/agent/prompts.js

@@ -25,8 +25,8 @@
  * `frontmatter` is optional — the proposal queue parses it from `content`
  * during validation. We carry it through if the agent supplies it.
  */
-import { TYPE_DIRS } from "../../core/asset-spec";
-import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
  * the agent can produce content that passes proposal validation. Kept tiny:
@@ -42,7 +42,6 @@ const TYPE_HINTS = {
     workflow: "workflow assets are markdown describing a multi-step process. Include `# <Title>` and ordered `## Step N` sections.",
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
     env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>` (the safe path — values never reach stdout/your context); do NOT run `akm env export` and read its output, as that prints values. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
-    vault: "vault assets are DEPRECATED (use env). They store environment variables (KEY=VALUE pairs); comments use `#`. Never echo secret values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
 };
 function hintForType(type) {

package/dist/integrations/agent/runner.js

@@ -1,8 +1,27 @@
 // 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 { ConfigError } from "../../core/errors";
-import { warn } from "../../core/warn";
+import { ConfigError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+// ── RunnerSpec capability predicates (H1) ───────────────────────────────────
+// The `RunnerSpec` union is dispatched ad-hoc across the improve slice. These
+// predicates co-locate the capability questions with the union definition so
+// callers stop hand-inlining `kind !== "llm"` (which couples the call site to
+// the exact shape of the union). They are typed as TypeScript type guards so
+// narrowing flows through to the `connection` / `profile` accessors.
+/** The in-tree LLM HTTP runner (`chatCompletion`); has no filesystem access. */
+export function runnerIsLlm(runner) {
+    return runner.kind === "llm";
+}
+/**
+ * Whether this runner can honour the file-write contract. Agent CLI + OpenCode
+ * SDK runners both have filesystem access; the direct LLM HTTP runner does NOT
+ * (see `src/llm/call-ai.ts`). Equivalent to `!runnerIsLlm(runner)` but names
+ * the capability the callers actually care about.
+ */
+export function runnerSupportsFileWrite(runner) {
+    return runner.kind !== "llm";
+}
 function resolveEffectiveMode(entry, profileName, config) {
     if (entry.mode)
         return entry.mode;
@@ -205,4 +224,4 @@ export function getStalenessDetectionThresholdDays(config) {
 }
 // Re-export `isProcessEnabled` from feature-gate.ts so callers that previously
 // imported it from runner.ts continue to work.
-export { isProcessEnabled } from "../../llm/feature-gate";
+export { isProcessEnabled } from "../../llm/feature-gate.js";

package/dist/integrations/agent/spawn.js

@@ -17,8 +17,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { getCommandBuilder } from "./builders";
-import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
+import { spawn as runtimeSpawn } from "../../runtime.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).
@@ -103,12 +104,10 @@ function pathCandidatesForCurrentPlatform(home) {
 function resolveSpawnFn(options) {
     if (options.spawn)
         return options.spawn;
-    // Pull from globalThis so tests that swap it out at module level are honoured.
-    const bun = globalThis.Bun;
-    if (!bun?.spawn) {
-        throw new Error("Bun.spawn is unavailable; pass options.spawn for non-Bun environments.");
-    }
-    return bun.spawn.bind(bun);
+    // 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:
@@ -169,7 +168,7 @@ async function readStream(stream, opts) {
  *
  * Failure modes (see {@link AgentFailureReason}):
  *
- *   • `spawn_failed`  — `Bun.spawn` threw synchronously.
+ *   • `spawn_failed`  — the spawn call threw synchronously.
  *   • `timeout`       — exceeded the resolved timeout.
  *   • `non_zero_exit` — child exited with a non-zero code.
  *   • `parse_error`   — `parseOutput === "json"` and stdout was not JSON.
@@ -233,7 +232,7 @@ export async function runAgent(profile, prompt, options = {}) {
         };
     }
     // Hard timeout. We prefer SIGTERM, then SIGKILL if SIGTERM is ignored,
-    // but Bun.spawn only exposes a single .kill() — one signal is enough
+    // but the subprocess only exposes a single .kill() — one signal is enough
     // for the structured-failure contract.
     //
     // BUG-M3: only flag `timedOut` when the child has not already exited. A

package/dist/integrations/harnesses/claude/agent-builder.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/.
+/**
+ * Claude Code agent command builder (migrated from `agent/builders.ts`, #563).
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * argv the `claude` CLI expects. This is the Claude-specific slice of the
+ * builder strategy; the shared infrastructure (`AgentCommandBuilder`,
+ * `getCommandBuilder`, the OpenCode/default builders, flag/tool helpers) stays
+ * 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).
+ */
+import { assertNotFlag, normalizeTools } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.js";
+/**
+ * Claude Code builder.
+ * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
+ *
+ * --print switches Claude Code to non-interactive captured output mode.
+ */
+export const claudeBuilder = {
+    platform: "claude",
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
+            args.push("--model", resolved);
+        }
+        if (req.tools) {
+            args.push("--allowedTools", normalizeTools(req.tools));
+        }
+        // --print = non-interactive, outputs to stdout — required for captured mode
+        args.push("--print");
+        args.push("--");
+        args.push(req.prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};

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

@@ -0,0 +1,70 @@
+// 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 LLM-config importer (migrated from `setup/harness-config-import.ts`,
+ * #563).
+ *
+ * Detects a Claude Code installation (filesystem only, no network) and reads
+ * its config to extract LLM connection details. API key VALUES are never
+ * stored — only the env var name that holds them. The pluggable registry
+ * (`HARNESS_CONFIG_IMPORTERS`) and the OpenCode importer stay in
+ * `setup/harness-config-import.ts`, which imports this importer back.
+ *
+ * Behaviour-preserving relocation.
+ */
+import fs from "node:fs";
+import path from "node:path";
+function homeDir() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? "";
+}
+/**
+ * Imports LLM config from a Claude Code installation.
+ *
+ * Claude Code stores settings in `~/.claude/settings.json` or `~/.claude.json`.
+ * The model field may appear at the root or under `env.ANTHROPIC_MODEL`.
+ * The API key is always `ANTHROPIC_API_KEY`.
+ */
+export const claudeCodeImporter = {
+    harnessName: "Claude Code",
+    detect() {
+        const home = homeDir();
+        // Claude Code is installed if the ~/.claude/ directory exists
+        return fs.existsSync(path.join(home, ".claude"));
+    },
+    importConfig() {
+        const home = homeDir();
+        // Try ~/.claude/settings.json, then ~/.claude.json
+        const candidates = [path.join(home, ".claude", "settings.json"), path.join(home, ".claude.json")];
+        for (const filePath of candidates) {
+            try {
+                if (!fs.existsSync(filePath))
+                    continue;
+                const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+                // Claude Code settings: model may be at root or nested under env
+                const envBlock = raw.env;
+                const model = typeof raw.model === "string"
+                    ? raw.model
+                    : typeof envBlock?.ANTHROPIC_MODEL === "string"
+                        ? String(envBlock.ANTHROPIC_MODEL)
+                        : undefined;
+                return {
+                    harnessName: "Claude Code",
+                    provider: "anthropic",
+                    model: model ?? "claude-sonnet-4-5",
+                    apiKeyEnvVar: "ANTHROPIC_API_KEY",
+                };
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        // ~/.claude exists but no readable settings — still return basic Anthropic config
+        return {
+            harnessName: "Claude Code",
+            provider: "anthropic",
+            model: "claude-sonnet-4-5",
+            apiKeyEnvVar: "ANTHROPIC_API_KEY",
+        };
+    },
+};

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

@@ -0,0 +1,64 @@
+// 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 { BaseHarness } from "../types.js";
+export { claudeBuilder } from "./agent-builder.js";
+export { claudeCodeImporter } from "./config-import.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.
+ *
+ * Canonical id is `'claude'`; `'claude-code'` is the runtime/session-log
+ * identity and is registered as an alias so both directions round-trip.
+ */
+export class ClaudeHarness extends BaseHarness {
+    id = "claude";
+    displayName = "Claude Code";
+    aliases = ["claude-code"];
+    runtimeId = "claude-code";
+    // Home-relative config dir scanned by `akm setup` (#567). Claude Code has a
+    // session-log provider, so offering it as a stash source is functional.
+    setupDetectionDir = ".claude";
+    capabilities = caps({
+        sessionLogs: true,
+        agentDispatch: true,
+        detection: true,
+        configImport: true,
+        runtimeIdentity: true,
+        v1Migration: true,
+    });
+}

package/dist/integrations/{session-logs/providers/claude-code.js → harnesses/claude/session-log.js}

@@ -4,8 +4,20 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { extractInlineRefMentions } from "../inline-refs";
-const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
+/**
+ * Root directory holding Claude Code's per-project JSONL session logs.
+ *
+ * Resolved per call (not memoized at module load) so the `AKM_CLAUDE_PROJECTS_DIR`
+ * override can be set after import. The override exists so tests — and the
+ * isolated-storage sandbox — can point the scan at an empty fixture directory
+ * instead of the real `~/.claude/projects`, which on an actively-used machine
+ * holds many large session files and would make `akm health` (which scans it
+ * synchronously) slow and non-hermetic.
+ */
+function claudeProjectsDir() {
+    return process.env.AKM_CLAUDE_PROJECTS_DIR ?? path.join(os.homedir(), ".claude", "projects");
+}
 /**
  * Parse a single Claude Code JSONL event into a normalized {@link SessionEvent}.
  * Returns `undefined` for events that don't carry textual content (file
@@ -75,14 +87,29 @@ function parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs) {
         filePath,
     };
 }
+/**
+ * Claude Code native session-log reader.
+ *
+ * id-normalization note (#563): the canonical harness id is `'claude'`, but
+ * the provider's `name` — which is STAMPED onto every {@link SessionEvent} /
+ * {@link SessionRef} (`harness: this.name`), used as the extracted-session
+ * dedup key, and embedded in `session:<harness>:<id>` proposal refs — stays
+ * `'claude-code'` (the harness runtimeId). Changing it would silently break
+ * round-tripping of already-persisted session-tracking rows and refs. Registry
+ * lookups normalize `'claude-code'` → `'claude'` via the #562 bridge
+ * (`getHarness`), and the `--type` flag accepts both, so the canonical id and
+ * the persisted runtime string coexist without drift.
+ */
 export class ClaudeCodeProvider {
+    // Runtime identity (NOT the canonical id) — see class doc. Equals
+    // HARNESS_BY_ID.get("claude").runtimeId.
     name = "claude-code";
     isAvailable() {
-        return fs.existsSync(CLAUDE_PROJECTS_DIR);
+        return fs.existsSync(claudeProjectsDir());
     }
     *readEvents(input) {
         try {
-            for (const jsonlPath of this.#walkJsonl(CLAUDE_PROJECTS_DIR)) {
+            for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {
                 const stat = fs.statSync(jsonlPath);
                 if (stat.mtimeMs < input.sinceMs)
                     continue;
@@ -113,7 +140,7 @@ export class ClaudeCodeProvider {
         }
     }
     listSessions(input = {}) {
-        const root = input.location ?? CLAUDE_PROJECTS_DIR;
+        const root = input.location ?? claudeProjectsDir();
         const sinceMs = input.sinceMs ?? 0;
         const summaries = [];
         try {