chainlesschain 0.162.158 → 0.162.160

package/src/harness/jsonl-session-store.js

@@ -14,6 +14,12 @@ import {
 import { join, basename, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { getHomeDir } from "../lib/paths.js";
+import {
+  computeEventHash,
+  latestChainHash,
+  verifyTranscriptText,
+  TRANSCRIPT_CHAIN_STATUS,
+} from "./transcript-integrity.js";
 
 function getSessionsDir() {
   const dir = join(getHomeDir(), "sessions");
@@ -54,11 +60,66 @@ export function appendTokenUsage(sessionId, usage) {
   appendEvent(sessionId, "token_usage", usage || {});
 }
 
+// Chain-tail cache: hash of the last chained record per session, so appends
+// stay O(1) instead of re-reading the file. Keyed per process — two processes
+// appending the SAME session concurrently could fork the chain (verify would
+// then flag it), but the store has always assumed a single writer per session.
+const _chainTailCache = new Map();
+
+function _resolveChainTail(sessionId, filePath) {
+  if (!existsSync(filePath)) {
+    // Missing file self-heals a stale cache entry (file deleted externally,
+    // or a test tearing down the sessions dir between cases).
+    _chainTailCache.set(sessionId, null);
+    return null;
+  }
+  const cached = _chainTailCache.get(sessionId);
+  if (cached !== undefined) return cached;
+  const tail = latestChainHash(readFileSync(filePath, "utf-8"));
+  _chainTailCache.set(sessionId, tail);
+  return tail;
+}
+
 export function appendEvent(sessionId, type, data) {
-  const line = JSON.stringify({ type, timestamp: Date.now(), data }) + "\n";
-  appendFileSync(sessionPath(sessionId), line, "utf-8");
+  const filePath = sessionPath(sessionId);
+  const prevHash = _resolveChainTail(sessionId, filePath);
+  const core = { type, timestamp: Date.now(), data };
+  const hash = computeEventHash(prevHash, core);
+  const line = JSON.stringify({ ...core, prevHash, hash }) + "\n";
+  appendFileSync(filePath, line, "utf-8");
+  _chainTailCache.set(sessionId, hash);
+}
+
+/**
+ * Verify a session transcript's hash chain (tamper-evidence).
+ * Statuses: verified | partial (legacy prefix + valid chain) | legacy
+ * (pre-chaining transcript) | tampered | empty — plus not-found / invalid-id.
+ */
+export function verifySession(sessionId) {
+  if (isUnsafeSessionId(sessionId)) {
+    return { sessionId, status: "invalid-id", reason: "invalid session id" };
+  }
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) {
+    return { sessionId, status: "not-found", reason: "session file not found" };
+  }
+  return {
+    sessionId,
+    ...verifyTranscriptText(readFileSync(filePath, "utf-8")),
+  };
+}
+
+export function verifyAllSessions(options = {}) {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(".jsonl"))
+    .slice(0, options.limit || 1000)
+    .map((file) => verifySession(basename(file, ".jsonl")));
 }
 
+export { TRANSCRIPT_CHAIN_STATUS };
+
 export function startSession(sessionId, meta = {}) {
   const id =
     sessionId ||
@@ -85,6 +146,25 @@ export function appendToolCall(sessionId, toolName, args) {
   appendEvent(sessionId, "tool_call", { tool: toolName, args });
 }
 
+/**
+ * Compact tool-call record for usage attribution (用量归因): tool name +
+ * error flag (+ an optional skill hint for `run_skill`) — deliberately NOT
+ * the args, which can carry whole file bodies (write_file content) and would
+ * bloat the transcript. Written at tool-result time by the agent drivers so
+ * `cc session usage --by tool|mcp` and `cc insights` can aggregate tool use
+ * for any persisted session.
+ */
+export function appendToolCallCompact(
+  sessionId,
+  { tool, isError, skill } = {},
+) {
+  appendEvent(sessionId, "tool_call", {
+    tool: tool || "?",
+    is_error: Boolean(isError),
+    ...(skill ? { skill: String(skill) } : {}),
+  });
+}
+
 export function appendToolResult(sessionId, toolName, result) {
   appendEvent(sessionId, "tool_result", { tool: toolName, result });
 }
@@ -191,10 +271,17 @@ export function listJsonlSessions(options = {}) {
       const messageCount = events.filter(
         (e) => e.type === "user_message" || e.type === "assistant_message",
       ).length;
+      // cc session rename appends session_rename events; the LAST one wins.
+      let renamedTitle = null;
+      for (const e of events) {
+        if (e.type === "session_rename" && e.data?.title) {
+          renamedTitle = e.data.title;
+        }
+      }
 
       return {
         id,
-        title: startEvent?.data?.title || "Untitled",
+        title: renamedTitle || startEvent?.data?.title || "Untitled",
         provider: startEvent?.data?.provider || "",
         model: startEvent?.data?.model || "",
         message_count: messageCount,
@@ -216,6 +303,68 @@ export function listJsonlSessions(options = {}) {
   return files;
 }
 
+/**
+ * Rename a session (gap-analysis 2026-07-11 P1 "命名会话"): appends a
+ * `session_rename` event so the hash chain stays intact (no rewrite). The
+ * LAST rename wins when listing/showing.
+ */
+export function renameSession(sessionId, title) {
+  if (!sessionExists(sessionId)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  const normalized = String(title || "").trim();
+  if (!normalized) throw new Error("A non-empty title is required");
+  appendEvent(sessionId, "session_rename", { title: normalized.slice(0, 200) });
+  return { id: sessionId, title: normalized.slice(0, 200) };
+}
+
+/**
+ * Prune old sessions (gap-analysis 2026-07-11 P1 "保留期限"): delete session
+ * transcripts whose LAST activity is older than `olderThanDays`, always
+ * keeping the newest `keep` (default 10) regardless of age. Dry-run returns
+ * the same shape without deleting.
+ */
+export function pruneJsonlSessions(options = {}) {
+  const olderThanDays = Number(options.olderThanDays);
+  if (!Number.isFinite(olderThanDays) || olderThanDays < 0) {
+    throw new Error(
+      "prune requires --older-than <days> (a non-negative number)",
+    );
+  }
+  const keep = Number.isFinite(Number(options.keep))
+    ? Math.max(0, Math.floor(Number(options.keep)))
+    : 10;
+  const now = typeof options.now === "number" ? options.now : Date.now();
+  const cutoff = now - olderThanDays * 24 * 60 * 60 * 1000;
+  // listJsonlSessions sorts by last activity DESC — the first `keep` entries
+  // survive unconditionally.
+  const all = listJsonlSessions({ limit: 100000 });
+  const candidates = all.slice(keep).filter((s) => {
+    const last = Date.parse(s.updated_at || s.created_at || "");
+    return Number.isFinite(last) && last < cutoff;
+  });
+  const deleted = [];
+  for (const s of candidates) {
+    if (options.dryRun === true) {
+      deleted.push(s.id);
+      continue;
+    }
+    try {
+      rmSync(sessionPath(s.id), { force: true });
+      _chainTailCache.delete(s.id);
+      deleted.push(s.id);
+    } catch {
+      /* per-file failures never abort the sweep */
+    }
+  }
+  return {
+    scanned: all.length,
+    kept: all.length - deleted.length,
+    deleted,
+    dryRun: options.dryRun === true,
+  };
+}
+
 export function forkSession(sourceId) {
   const events = readEvents(sourceId);
   if (events.length === 0) return null;

package/src/harness/mcp-client.js

@@ -1051,6 +1051,17 @@ export class MCPClient extends EventEmitter {
 
     // Server notification
     if (msg.method) {
+      // tools/resources list_changed (gap 2026-07-11 MCP 生命周期): refetch
+      // the changed list so entry.tools/entry.resources stay live —
+      // `listTools()`, `/mcp` status and callTool routing all see the update.
+      // (The LLM tool array of an in-flight turn is deliberately NOT mutated:
+      // tool-search's prompt-cache stability depends on an append-only,
+      // stable-prefix tool list.)
+      if (msg.method === "notifications/tools/list_changed") {
+        this._refreshServerList(serverName, "tools");
+      } else if (msg.method === "notifications/resources/list_changed") {
+        this._refreshServerList(serverName, "resources");
+      }
       this.emit("notification", {
         server: serverName,
         method: msg.method,
@@ -1059,6 +1070,45 @@ export class MCPClient extends EventEmitter {
     }
   }
 
+  /**
+   * Re-fetch a server's tools / resources list after a `*_list_changed`
+   * notification. Coalesced per server+kind: a burst of notifications folds
+   * into the in-flight refetch plus at most one trailing pass. Best-effort —
+   * a failed refetch keeps the previous list and waits for the next
+   * notification. Emits "tools-changed" / "resources-changed" on update.
+   */
+  async _refreshServerList(serverName, kind) {
+    const entry = this.servers.get(serverName);
+    if (!entry) return;
+    const flags = (entry._listRefresh = entry._listRefresh || {});
+    if (flags[`${kind}Running`]) {
+      flags[`${kind}Dirty`] = true;
+      return;
+    }
+    flags[`${kind}Running`] = true;
+    try {
+      do {
+        flags[`${kind}Dirty`] = false;
+        try {
+          const method = kind === "tools" ? "tools/list" : "resources/list";
+          const result = await this._sendRequest(serverName, method, {});
+          const list =
+            (kind === "tools" ? result?.tools : result?.resources) || [];
+          entry[kind] = list;
+          if (kind === "tools") entry.toolsError = null;
+          this.emit(`${kind}-changed`, {
+            server: serverName,
+            count: list.length,
+          });
+        } catch {
+          break; // keep the previous list; the next notification retries
+        }
+      } while (flags[`${kind}Dirty`]);
+    } finally {
+      flags[`${kind}Running`] = false;
+    }
+  }
+
   /**
    * Answer a server-initiated JSON-RPC request. `roots/list` returns the
    * session's workspace roots (we advertise the roots capability); `ping`

package/src/harness/session-index.js

@@ -0,0 +1,295 @@
+/**
+ * Session index (gap-2026-07-11 P2#14) — a SQLite index over the append-only
+ * JSONL session store.
+ *
+ * The JSONL files stay the source of truth (append-only, hash-chained,
+ * tamper-evident — see jsonl-session-store.js + transcript-integrity.js). But
+ * listing/searching them means reading and parsing every file on every call,
+ * which does not scale past a few hundred sessions. This index gives O(1) list
+ * ordering and indexed content search, and stays in sync incrementally by
+ * file mtime+size so a resume/fork/search/verify is cheap.
+ *
+ * The index is a derived cache: it can be deleted and fully rebuilt from the
+ * JSONL at any time (`syncIndex({ force: true })`). Nothing authoritative lives
+ * only here.
+ *
+ * `Database` is injected via `_deps` so tests run against an in-memory SQLite
+ * without touching the user's home dir.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  readFileSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+import { createRequire } from "node:module";
+import { getHomeDir } from "../lib/paths.js";
+import { readEvents, toIsoSafe } from "./jsonl-session-store.js";
+import { latestChainHash } from "./transcript-integrity.js";
+
+const requireCjs = createRequire(import.meta.url);
+
+// Lazy so importing this module never forces the native addon to load (matters
+// for fast CLI paths and for environments where better-sqlite3 is unavailable).
+export const _deps = {
+  Database: null,
+  loadDatabase() {
+    if (!_deps.Database) {
+      _deps.Database = requireCjs("better-sqlite3");
+    }
+    return _deps.Database;
+  },
+};
+
+function sessionsDir() {
+  return join(getHomeDir(), "sessions");
+}
+
+function indexPath() {
+  const dir = getHomeDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, "session-index.db");
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id            TEXT PRIMARY KEY,
+  title         TEXT,
+  provider      TEXT,
+  model         TEXT,
+  message_count INTEGER,
+  event_count   INTEGER,
+  created_at    TEXT,
+  updated_at    TEXT,
+  last_ts       INTEGER,
+  chain_hash    TEXT,
+  mtime_ms      INTEGER,
+  size_bytes    INTEGER
+);
+CREATE TABLE IF NOT EXISTS session_content (
+  id   TEXT PRIMARY KEY,
+  text TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_last_ts ON sessions(last_ts DESC);
+`;
+
+/**
+ * Open (and migrate) the index database. Caller owns closing it. Pass
+ * `{ file: ":memory:" }` for tests.
+ */
+export function openIndex({ file } = {}) {
+  const Database = _deps.loadDatabase();
+  const db = new Database(file || indexPath());
+  db.pragma("journal_mode = WAL");
+  db.exec(SCHEMA);
+  return db;
+}
+
+/** Max characters of concatenated message content indexed per session. */
+const CONTENT_CAP = 200_000;
+
+function summarizeEvents(id, events) {
+  const startEvent = events.find((e) => e.type === "session_start");
+  const lastEvent = events[events.length - 1];
+  const messageCount = events.filter(
+    (e) => e.type === "user_message" || e.type === "assistant_message",
+  ).length;
+  const parts = [];
+  let used = 0;
+  for (const e of events) {
+    if (e.type !== "user_message" && e.type !== "assistant_message") continue;
+    const c = e.data?.content;
+    const s = typeof c === "string" ? c : c == null ? "" : JSON.stringify(c);
+    if (!s) continue;
+    parts.push(s);
+    used += s.length;
+    if (used >= CONTENT_CAP) break;
+  }
+  return {
+    id,
+    title: startEvent?.data?.title || "Untitled",
+    provider: startEvent?.data?.provider || "",
+    model: startEvent?.data?.model || "",
+    message_count: messageCount,
+    event_count: events.length,
+    created_at: toIsoSafe(startEvent?.timestamp),
+    updated_at: toIsoSafe(lastEvent?.timestamp),
+    last_ts: lastEvent?.timestamp || 0,
+    content: parts.join("\n").slice(0, CONTENT_CAP),
+  };
+}
+
+const UPSERT_SESSION = `
+INSERT INTO sessions
+  (id,title,provider,model,message_count,event_count,created_at,updated_at,last_ts,chain_hash,mtime_ms,size_bytes)
+VALUES (@id,@title,@provider,@model,@message_count,@event_count,@created_at,@updated_at,@last_ts,@chain_hash,@mtime_ms,@size_bytes)
+ON CONFLICT(id) DO UPDATE SET
+  title=@title, provider=@provider, model=@model, message_count=@message_count,
+  event_count=@event_count, created_at=@created_at, updated_at=@updated_at,
+  last_ts=@last_ts, chain_hash=@chain_hash, mtime_ms=@mtime_ms, size_bytes=@size_bytes
+`;
+
+/**
+ * Index (or re-index) a single session from its JSONL into `db`.
+ * @returns {boolean} true if a row was written.
+ */
+export function indexOneSession(db, id, { mtimeMs = 0, sizeBytes = 0 } = {}) {
+  const events = readEvents(id);
+  if (events.length === 0) return false;
+  const s = summarizeEvents(id, events);
+  const filePath = join(sessionsDir(), `${id}.jsonl`);
+  let chainHash = "";
+  try {
+    chainHash = latestChainHash(readFileSync(filePath, "utf-8")) || "";
+  } catch {
+    /* chain hash is best-effort */
+  }
+  db.prepare(UPSERT_SESSION).run({
+    id: s.id,
+    title: s.title,
+    provider: s.provider,
+    model: s.model,
+    message_count: s.message_count,
+    event_count: s.event_count,
+    created_at: s.created_at,
+    updated_at: s.updated_at,
+    last_ts: s.last_ts,
+    chain_hash: chainHash,
+    mtime_ms: Math.floor(mtimeMs),
+    size_bytes: sizeBytes,
+  });
+  db.prepare(
+    "INSERT INTO session_content (id,text) VALUES (?,?) ON CONFLICT(id) DO UPDATE SET text=excluded.text",
+  ).run(s.id, s.content);
+  return true;
+}
+
+/**
+ * Incrementally sync the index with the sessions dir. A session is re-indexed
+ * only when its file mtime or size changed since last time (or `force`).
+ * Deleted JSONL files have their index rows removed.
+ * @returns {{ scanned, updated, removed, total }}
+ */
+export function syncIndex(db, { force = false } = {}) {
+  const dir = sessionsDir();
+  let scanned = 0;
+  let updated = 0;
+  let removed = 0;
+  const seen = new Set();
+
+  if (existsSync(dir)) {
+    const known = new Map(
+      db
+        .prepare("SELECT id, mtime_ms, size_bytes FROM sessions")
+        .all()
+        .map((r) => [r.id, r]),
+    );
+    const files = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    const tx = db.transaction((entries) => {
+      for (const { id, mtimeMs, size } of entries) {
+        seen.add(id);
+        scanned++;
+        const prev = known.get(id);
+        if (
+          !force &&
+          prev &&
+          prev.mtime_ms === Math.floor(mtimeMs) &&
+          prev.size_bytes === size
+        ) {
+          continue; // unchanged
+        }
+        if (indexOneSession(db, id, { mtimeMs, sizeBytes: size })) updated++;
+      }
+    });
+    const entries = [];
+    for (const f of files) {
+      const id = basename(f, ".jsonl");
+      let st;
+      try {
+        st = statSync(join(dir, f));
+      } catch {
+        continue;
+      }
+      entries.push({ id, mtimeMs: st.mtimeMs, size: st.size });
+    }
+    tx(entries);
+
+    // Drop rows whose JSONL no longer exists.
+    for (const id of known.keys()) {
+      if (!seen.has(id)) {
+        db.prepare("DELETE FROM sessions WHERE id=?").run(id);
+        db.prepare("DELETE FROM session_content WHERE id=?").run(id);
+        removed++;
+      }
+    }
+  }
+
+  const total = db.prepare("SELECT COUNT(*) c FROM sessions").get().c;
+  return { scanned, updated, removed, total };
+}
+
+const LIST_COLUMNS =
+  "id,title,provider,model,message_count,event_count,created_at,updated_at";
+
+/** List indexed sessions, newest activity first. */
+export function listSessions(db, { limit = 20 } = {}) {
+  return db
+    .prepare(
+      `SELECT ${LIST_COLUMNS} FROM sessions ORDER BY last_ts DESC, event_count DESC LIMIT ?`,
+    )
+    .all(Math.max(1, limit | 0));
+}
+
+/**
+ * Full-text-ish search over session titles and message content (LIKE). Returns
+ * matched sessions with a short snippet around the first hit.
+ */
+export function searchSessions(db, query, { limit = 20 } = {}) {
+  const q = String(query || "").trim();
+  if (!q) return [];
+  const like = `%${q.replace(/[%_]/g, (m) => "\\" + m)}%`;
+  const rows = db
+    .prepare(
+      `SELECT s.${LIST_COLUMNS.split(",").join(", s.")}, c.text AS _text
+       FROM sessions s LEFT JOIN session_content c ON c.id = s.id
+       WHERE s.title LIKE ? ESCAPE '\\' OR c.text LIKE ? ESCAPE '\\'
+       ORDER BY s.last_ts DESC LIMIT ?`,
+    )
+    .all(like, like, Math.max(1, limit | 0));
+  const needle = q.toLowerCase();
+  return rows.map((r) => {
+    const text = r._text || "";
+    const at = text.toLowerCase().indexOf(needle);
+    const snippet =
+      at >= 0
+        ? text
+            .slice(Math.max(0, at - 40), at + q.length + 40)
+            .replace(/\s+/g, " ")
+            .trim()
+        : "";
+    const { _text, ...rest } = r;
+    return { ...rest, snippet };
+  });
+}
+
+/** One indexed session row, or null. */
+export function getIndexedSession(db, id) {
+  return db.prepare(`SELECT * FROM sessions WHERE id=?`).get(id) || null;
+}
+
+/** Index-wide counters for `cc doctor` / `cc session index --stats`. */
+export function indexStats(db) {
+  const row = db
+    .prepare(
+      "SELECT COUNT(*) sessions, COALESCE(SUM(message_count),0) messages, COALESCE(SUM(event_count),0) events FROM sessions",
+    )
+    .get();
+  return {
+    sessions: row.sessions,
+    messages: row.messages,
+    events: row.events,
+  };
+}

package/src/harness/session-mirror.js

@@ -0,0 +1,142 @@
+/**
+ * Session mirror (gap-2026-07-11 P2#14) — a pluggable off-box copy of the JSONL
+ * session store for cross-device / cloud-runner / team scenarios.
+ *
+ * The mirror is one-way derived from the local JSONL (which stays the source of
+ * truth): `push(id)` copies a session's bytes out, `pull(id)` fetches them back,
+ * `list()` enumerates what the remote holds. Encryption and access control are
+ * the driver's concern (configured independently), so a driver may wrap bytes
+ * before they leave the box.
+ *
+ * Drivers implement a tiny interface `{ push(id, bytes), pull(id), list() }`.
+ * Two are built in:
+ *   - `fs`   : mirror to a local/mounted directory (reference impl; also the
+ *              test target). Covers NFS/SMB-mounted shares for free.
+ *   - `http` : PUT/GET/list against a self-hosted API mirror (injectable fetch).
+ * S3 / WebDAV / Redis are additional drivers that plug in behind the same
+ * factory; they need real endpoints so they are configured, not bundled.
+ *
+ * Pure/DI: filesystem and fetch go through injected deps so the factory and the
+ * fs driver are unit-testable without network or a real home dir.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+import { isUnsafeSessionId } from "./jsonl-session-store.js";
+
+/**
+ * Build a mirror driver from config. `config.kind` selects the driver:
+ *   { kind: "fs",   dir: "/mnt/backup/sessions" }
+ *   { kind: "http", baseUrl: "https://mirror.local", token: "…" }
+ * Returns null when no mirror is configured (kind falsy / "none").
+ */
+export function createMirror(config = {}, deps = {}) {
+  const kind = String(config.kind || config.type || "none").toLowerCase();
+  if (!kind || kind === "none") return null;
+  if (kind === "fs" || kind === "dir" || kind === "directory") {
+    return createFsMirror(config, deps);
+  }
+  if (kind === "http" || kind === "api") {
+    return createHttpMirror(config, deps);
+  }
+  throw new Error(
+    `unknown session mirror kind "${kind}" (use fs | http, or wire an s3/webdav/redis driver)`,
+  );
+}
+
+/** Directory mirror — the reference driver. */
+export function createFsMirror(config = {}, deps = {}) {
+  const dir = config.dir || config.path;
+  if (!dir) throw new Error("fs mirror requires a `dir`");
+  const _existsSync = deps.existsSync || existsSync;
+  const _mkdirSync = deps.mkdirSync || mkdirSync;
+  const _readFileSync = deps.readFileSync || readFileSync;
+  const _writeFileSync = deps.writeFileSync || writeFileSync;
+  const _readdirSync = deps.readdirSync || readdirSync;
+
+  const ensure = () => {
+    if (!_existsSync(dir)) _mkdirSync(dir, { recursive: true });
+    return dir;
+  };
+  const fileFor = (id) => {
+    if (isUnsafeSessionId(id)) throw new Error(`unsafe session id: ${id}`);
+    return join(dir, `${id}.jsonl`);
+  };
+
+  return {
+    kind: "fs",
+    target: dir,
+    async push(id, bytes) {
+      ensure();
+      _writeFileSync(fileFor(id), bytes, "utf-8");
+      return { id, bytes: Buffer.byteLength(bytes) };
+    },
+    async pull(id) {
+      const f = fileFor(id);
+      if (!_existsSync(f)) return null;
+      return _readFileSync(f, "utf-8");
+    },
+    async list() {
+      if (!_existsSync(dir)) return [];
+      return _readdirSync(dir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((f) => basename(f, ".jsonl"));
+    },
+  };
+}
+
+/** HTTP mirror — PUT/GET/list against a self-hosted API. `fetch` injectable. */
+export function createHttpMirror(config = {}, deps = {}) {
+  const baseUrl = String(config.baseUrl || config.url || "").replace(
+    /\/+$/,
+    "",
+  );
+  if (!baseUrl) throw new Error("http mirror requires a `baseUrl`");
+  const token = config.token || null;
+  const doFetch = deps.fetch || ((...a) => globalThis.fetch(...a));
+  const headers = (extra = {}) => ({
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...extra,
+  });
+  const guard = (id) => {
+    if (isUnsafeSessionId(id)) throw new Error(`unsafe session id: ${id}`);
+    return encodeURIComponent(id);
+  };
+
+  return {
+    kind: "http",
+    target: baseUrl,
+    async push(id, bytes) {
+      const res = await doFetch(`${baseUrl}/sessions/${guard(id)}`, {
+        method: "PUT",
+        headers: headers({ "Content-Type": "application/x-ndjson" }),
+        body: bytes,
+      });
+      if (!res.ok) throw new Error(`mirror PUT ${id} → HTTP ${res.status}`);
+      return { id, bytes: Buffer.byteLength(bytes) };
+    },
+    async pull(id) {
+      const res = await doFetch(`${baseUrl}/sessions/${guard(id)}`, {
+        headers: headers(),
+      });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`mirror GET ${id} → HTTP ${res.status}`);
+      return res.text();
+    },
+    async list() {
+      const res = await doFetch(`${baseUrl}/sessions`, { headers: headers() });
+      if (!res.ok) throw new Error(`mirror list → HTTP ${res.status}`);
+      const data = await res.json();
+      const ids = Array.isArray(data) ? data : data?.sessions || [];
+      return ids
+        .map((x) => (typeof x === "string" ? x : x?.id))
+        .filter(Boolean);
+    },
+  };
+}