chainlesschain 0.162.158 → 0.162.159

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);
+    },
+  };
+}

package/src/harness/transcript-integrity.js

@@ -0,0 +1,182 @@
+/**
+ * Transcript integrity — hash-chained JSONL session transcripts.
+ *
+ * Every event appended to a session transcript carries `prevHash` (the hash of
+ * the previous event, or null for the first chained event) and `hash` — a
+ * SHA-256 over the previous hash plus the event's canonical core
+ * (`{type, timestamp, data}`). Editing, deleting, inserting, or reordering any
+ * chained line breaks the chain and is detected by `verifyTranscriptLines`.
+ *
+ * Design constraints:
+ * - Pure module: no fs, no paths — the store layer (jsonl-session-store.js)
+ *   owns file IO so this stays cycle-free and unit-testable in isolation.
+ * - Backward compatible: transcripts written before chaining have no hash
+ *   fields. A fully legacy file verifies as `legacy`; a legacy prefix followed
+ *   by a valid chain is `partial` (chaining starts on the first upgraded
+ *   append). An UNchained record appearing AFTER chained records is flagged as
+ *   tampered — our writer never does that, so it is either a downgrade-write
+ *   or a manual append, both of which the verifier must surface.
+ * - Honest limitation: truncating the file tail (deleting the newest N chained
+ *   lines) is undetectable without an external anchor — the chain is
+ *   self-contained. A half-written LAST line (crash mid-append) is reported as
+ *   `truncatedTail: true` rather than tampered.
+ */
+
+import { createHash } from "node:crypto";
+
+export const TRANSCRIPT_CHAIN_STATUS = Object.freeze({
+  VERIFIED: "verified", // every record chained + chain valid
+  PARTIAL: "partial", // legacy prefix, then a valid chain
+  LEGACY: "legacy", // no chained records at all (pre-chaining transcript)
+  TAMPERED: "tampered", // chain broken: edit / delete / insert / reorder
+  EMPTY: "empty", // no records
+});
+
+/**
+ * Hash one event's canonical core against the previous chain hash.
+ * The core is rebuilt field-by-field (not the raw line) so the hash is
+ * independent of the presence/position of the prevHash/hash fields themselves;
+ * JSON.parse → JSON.stringify preserves the writer's key insertion order for
+ * `data`, so writer and verifier serialize identically.
+ */
+export function computeEventHash(prevHash, core) {
+  const canonical = JSON.stringify({
+    type: core.type,
+    timestamp: core.timestamp,
+    data: core.data,
+  });
+  return createHash("sha256")
+    .update(`${prevHash || "genesis"}\n${canonical}`, "utf-8")
+    .digest("hex");
+}
+
+/**
+ * The hash the NEXT appended event must chain from: the `hash` of the last
+ * parseable line, or null when the file is empty / fully legacy / the last
+ * parseable line is unchained. A trailing half-written line (crash mid-append)
+ * is skipped so the writer chains from the last intact record.
+ */
+export function latestChainHash(text) {
+  const lines = String(text || "").split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    try {
+      const event = JSON.parse(line);
+      return typeof event?.hash === "string" ? event.hash : null;
+    } catch {
+      // half-written tail line — chain from the previous intact record
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Verify a transcript's hash chain.
+ *
+ * @param {string[]} lines raw transcript lines (as split on "\n")
+ * @returns {{
+ *   status: string,            // TRANSCRIPT_CHAIN_STATUS value
+ *   chainedEvents: number,
+ *   legacyEvents: number,
+ *   malformedLines: number,
+ *   truncatedTail: boolean,    // last non-empty line is half-written JSON
+ *   firstInvalidLine: number|null, // 1-based line number of the first break
+ *   reason: string|null,
+ * }}
+ */
+export function verifyTranscriptLines(lines) {
+  const input = Array.isArray(lines) ? lines : [];
+  let lastNonEmpty = -1;
+  for (let i = input.length - 1; i >= 0; i--) {
+    if (input[i] && input[i].trim()) {
+      lastNonEmpty = i;
+      break;
+    }
+  }
+
+  const result = {
+    status: TRANSCRIPT_CHAIN_STATUS.EMPTY,
+    chainedEvents: 0,
+    legacyEvents: 0,
+    malformedLines: 0,
+    truncatedTail: false,
+    firstInvalidLine: null,
+    reason: null,
+  };
+
+  let lastHash = null;
+  let sawChain = false;
+
+  const tampered = (lineNo, reason) => {
+    result.status = TRANSCRIPT_CHAIN_STATUS.TAMPERED;
+    result.firstInvalidLine = lineNo;
+    result.reason = reason;
+    return result;
+  };
+
+  for (let i = 0; i < input.length; i++) {
+    const line = input[i];
+    if (!line || !line.trim()) continue;
+    const lineNo = i + 1;
+
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      result.malformedLines++;
+      if (i === lastNonEmpty) {
+        // Crash mid-append: the newest line is half-written. Not tampering —
+        // report it so callers can surface a warning.
+        result.truncatedTail = true;
+        continue;
+      }
+      if (sawChain) {
+        return tampered(lineNo, "malformed line inside hash chain");
+      }
+      continue; // junk inside the legacy region — validate reports it
+    }
+
+    if (event && typeof event.hash === "string") {
+      const expectedPrev = sawChain ? lastHash : null;
+      if ((event.prevHash ?? null) !== expectedPrev) {
+        return tampered(
+          lineNo,
+          sawChain
+            ? "hash chain linkage broken (record deleted, inserted, or reordered)"
+            : "chain does not start at a genesis record (head records removed)",
+        );
+      }
+      if (computeEventHash(expectedPrev, event) !== event.hash) {
+        return tampered(lineNo, "event content does not match its hash");
+      }
+      sawChain = true;
+      lastHash = event.hash;
+      result.chainedEvents++;
+    } else {
+      if (sawChain) {
+        return tampered(
+          lineNo,
+          "unchained record after hash chain started (manual append or downgrade write)",
+        );
+      }
+      result.legacyEvents++;
+    }
+  }
+
+  if (result.chainedEvents > 0) {
+    result.status =
+      result.legacyEvents > 0
+        ? TRANSCRIPT_CHAIN_STATUS.PARTIAL
+        : TRANSCRIPT_CHAIN_STATUS.VERIFIED;
+  } else if (result.legacyEvents > 0 || result.malformedLines > 0) {
+    result.status = TRANSCRIPT_CHAIN_STATUS.LEGACY;
+  }
+  return result;
+}
+
+/** Convenience wrapper for whole-file text. */
+export function verifyTranscriptText(text) {
+  return verifyTranscriptLines(String(text || "").split("\n"));
+}

package/src/index.js

@@ -159,6 +159,12 @@ import { registerRemoteControlCommand } from "./commands/remote-control.js";
 // Agenda: consumer for agent-scheduled wakeups/crons/monitors (第四阶段 #3)
 import { registerAgendaCommand } from "./commands/agenda.js";
 
+// Routines: named scheduled/triggered agent tasks with run history (gap-2026-07-11 P1#8)
+import { registerRoutineCommand } from "./commands/routine.js";
+
+// Cloud: self-hosted cloud handoff — offload a task to a private runner (gap-2026-07-11 P1#7)
+import { registerCloudCommand } from "./commands/cloud.js";
+
 // Batch: dynamic worktree batch — split a change into parallel units (第四阶段 #4)
 import { registerBatchCommand } from "./commands/batch.js";
 
@@ -597,6 +603,8 @@ export function createProgram(opts = {}) {
 
   // Agenda: fire agent-scheduled wakeups/crons/monitors
   registerAgendaCommand(program);
+  registerRoutineCommand(program);
+  registerCloudCommand(program);
 
   // Batch: dynamic worktree batch
   registerBatchCommand(program);