chainlesschain 0.162.158 → 0.162.160

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);

package/src/lib/agent-sandbox.js

@@ -215,11 +215,79 @@ function executeBubblewrapShell(command, sandbox, options, hostCwd, policy) {
   };
 }
 
+/**
+ * The run's TRUE isolation level (gap-analysis 2026-07-11 P0 "OS 级沙箱"):
+ *  - "os-sandbox"  : bubblewrap — kernel namespaces confine the child
+ *  - "container"   : docker — container boundary confines the child
+ *  - "policy-only" : no sandbox — permission rules/shell policy are advisory
+ *                    for already-spawned subprocesses
+ * Surfaced in the headless init event and sandboxSummary so a caller can see
+ * what actually confines tool subprocesses instead of assuming.
+ */
+export function isolationLevel(sandbox) {
+  if (!sandbox) return "policy-only";
+  if (sandbox.engine === "bubblewrap") return "os-sandbox";
+  if (sandbox.engine === "docker") return "container";
+  return "policy-only";
+}
+
+/**
+ * Probe whether the configured sandbox ENGINE is actually runnable on this
+ * host (binary present + responds to a version query). Cheap: one spawnSync
+ * with a short timeout; no container is started.
+ * @returns {{available:boolean, reason:string|null}}
+ */
+export function probeSandboxAvailability(sandbox, deps = _deps) {
+  if (!sandbox) return { available: true, reason: null };
+  const probeArgs =
+    sandbox.engine === "bubblewrap"
+      ? ["bwrap", ["--version"]]
+      : ["docker", ["version", "--format", "{{.Server.Version}}"]];
+  const result = deps.spawnSync(probeArgs[0], probeArgs[1], {
+    encoding: "utf8",
+    timeout: 10000,
+    windowsHide: true,
+  });
+  if (result.error) {
+    return {
+      available: false,
+      reason:
+        result.error.code === "ENOENT"
+          ? `${probeArgs[0]} is not installed`
+          : result.error.message,
+    };
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    return {
+      available: false,
+      reason: `${probeArgs[0]} probe exited ${result.status}: ${(result.stderr || "").trim().slice(0, 200)}`,
+    };
+  }
+  return { available: true, reason: null };
+}
+
+/**
+ * Strict mode (`sandbox.failIfUnavailable: true` in settings): refuse to
+ * START the agent when the configured sandbox engine is unavailable, instead
+ * of silently degrading per command. Throws with an actionable message; a
+ * no-op when the flag is unset or the sandbox is fine.
+ */
+export function assertSandboxAvailable(sandbox, deps = _deps) {
+  if (!sandbox || sandbox.policy?.failIfUnavailable !== true) return;
+  const probe = probeSandboxAvailability(sandbox, deps);
+  if (!probe.available) {
+    throw new Error(
+      `sandbox.failIfUnavailable: ${sandbox.engine} sandbox is unavailable (${probe.reason}) — refusing to start. Install/start ${sandbox.engine === "bubblewrap" ? "bubblewrap" : "Docker"}, or unset failIfUnavailable to allow per-command degradation.`,
+    );
+  }
+}
+
 export function sandboxSummary(sandbox) {
   if (!sandbox) return null;
   return {
     engine: sandbox.engine,
     image: sandbox.image,
+    isolationLevel: isolationLevel(sandbox),
     network: sandbox.network ? "enabled" : "disabled",
     workspace: "read-write",
     policy: {

package/src/lib/agents.js

@@ -8,10 +8,13 @@
  * `review/security.md` is the agent `review:security`.
  *
  * Frontmatter (all optional):
- *   name          override the filename-derived name
- *   description   one-line summary (when to use this agent)
- *   tools         allow-list — comma string or YAML array; omit = inherit all
- *   model         model override for runs of this agent
+ *   name             override the filename-derived name
+ *   description      one-line summary (when to use this agent)
+ *   tools            allow-list — comma string or YAML array; omit = inherit all
+ *   disallowedTools  deny-list — removed from whatever the allow-list resolves to
+ *   model            model override for runs of this agent
+ *   maxTurns         per-run iteration cap for this agent (positive integer)
+ *   isolation        "worktree" → run in a fresh git worktree (gap 2026-07-11)
  *
  * Project scope shadows personal on a name clash. Discovery + parse are pure
  * (inject fs/path/home) so the whole thing is unit-testable.
@@ -132,13 +135,18 @@ export function parseAgentFile(file, scope, opts = {}) {
     return null;
   }
   const { data, body } = parseFrontmatter(content);
+  const maxTurns = Number(data.maxTurns);
   return {
     file,
     scope,
     name: data.name || null, // resolved against the path in discoverAgents
     description: data.description || "",
     tools: normalizeTools(data.tools),
+    disallowedTools: normalizeTools(data.disallowedTools),
     model: data.model || null,
+    maxTurns:
+      Number.isFinite(maxTurns) && maxTurns > 0 ? Math.floor(maxTurns) : null,
+    isolation: data.isolation === "worktree" ? "worktree" : null,
     systemPrompt: body || "",
   };
 }

package/src/lib/api-key-helper.js

@@ -0,0 +1,62 @@
+/**
+ * `llm.apiKeyHelper` (gap-analysis 2026-07-11 P0 "依赖安装与凭据"): fetch the
+ * LLM API key from an external command instead of storing it in plaintext
+ * config.json. Point it at your OS credential store, e.g.:
+ *
+ *   Windows :  "powershell -NoProfile -Command \"...CredentialManager...\""
+ *   macOS   :  "security find-generic-password -s cc-llm -w"
+ *   Linux   :  "secret-tool lookup service cc-llm"
+ *
+ * Resolution precedence stays: --api-key > CC_API_KEY > config llm.apiKey >
+ * llm.apiKeyHelper. The helper's stdout (trimmed) is the key; a failing or
+ * empty helper resolves null so the run fails with the provider's own
+ * missing-key error (never a silent fallback — see the no-silent-substitution
+ * rule). Cached per process (5 min) so multi-call runs don't re-spawn it.
+ */
+
+import { execSync } from "node:child_process";
+
+const TTL_MS = 5 * 60 * 1000;
+const _cache = new Map(); // helper command → { key, at }
+let _warnedFailure = false;
+
+/**
+ * @param {string} helperCmd  shell command printing the key on stdout
+ * @param {{exec?:Function, now?:()=>number, writeErr?:(s:string)=>void}} [opts]
+ * @returns {string|null}
+ */
+export function resolveApiKeyFromHelper(helperCmd, opts = {}) {
+  const cmd = typeof helperCmd === "string" ? helperCmd.trim() : "";
+  if (!cmd) return null;
+  const now = opts.now || Date.now;
+  const hit = _cache.get(cmd);
+  if (hit && now() - hit.at < TTL_MS) return hit.key;
+  const exec = opts.exec || execSync;
+  try {
+    const out = exec(cmd, {
+      encoding: "utf-8",
+      timeout: 10000,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const key = String(out || "").trim();
+    if (!key) return null;
+    _cache.set(cmd, { key, at: now() });
+    return key;
+  } catch (err) {
+    // Warn once per process, then stay quiet — the provider's missing-key
+    // error is the actionable surface.
+    if (!_warnedFailure) {
+      _warnedFailure = true;
+      const writeErr = opts.writeErr || ((s) => process.stderr.write(s));
+      writeErr(`[api-key-helper] llm.apiKeyHelper failed: ${err.message}\n`);
+    }
+    return null;
+  }
+}
+
+/** Test seam: drop the per-process cache + warn-once latch. */
+export function clearApiKeyHelperCache() {
+  _cache.clear();
+  _warnedFailure = false;
+}

package/src/lib/background-agent-supervisor.js

@@ -8,6 +8,7 @@ import {
   readdirSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { randomBytes } from "node:crypto";
@@ -61,12 +62,57 @@ export function logPath(id) {
   return join(backgroundAgentsDir(), `${safeId(id)}.log`);
 }
 
+const TERMINAL_STATUSES = new Set(["completed", "failed", "stopped", "lost"]);
+
 export function writeBackgroundAgentState(state) {
   const target = statePath(state.id);
+  // Field-aware merge against the freshest on-disk state. The state file has
+  // multiple concurrent read-modify-write writers (launcher, worker heartbeat/
+  // turn/finalize, rename/pin/stop from other processes) with last-writer-wins
+  // semantics — a writer holding a stale snapshot used to clobber a terminal
+  // status back to "running" (phantom session, real exit code lost) or roll a
+  // fresh rename back to the old title. Two invariants restore convergence:
+  //   1. a terminal status wins over a racing "running" snapshot — there is no
+  //      legitimate same-id terminal→running transition (resume mints a NEW
+  //      id, and the worker's own writeHeartbeat already refuses to resurrect);
+  //   2. the newest rename/pin (by renamedAt/pinnedAt) wins regardless of
+  //      which writer's snapshot carries it.
+  // The read happens immediately before the atomic rename, shrinking the
+  // clobber window from "any caller's RMW span" to microseconds; rename/pin
+  // additionally verify-and-retry on top of this.
+  let next = state;
+  const current = readBackgroundAgentState(state.id);
+  if (current) {
+    if (TERMINAL_STATUSES.has(current.status) && next.status === "running") {
+      next = {
+        ...next,
+        status: current.status,
+        endedAt: current.endedAt ?? next.endedAt ?? null,
+        exitCode: current.exitCode ?? next.exitCode ?? null,
+        ...(current.signal !== undefined ? { signal: current.signal } : {}),
+        ...(current.error !== undefined ? { error: current.error } : {}),
+        ...(current.lostReason !== undefined
+          ? { lostReason: current.lostReason }
+          : {}),
+        ...(current.stoppedByUser !== undefined
+          ? { stoppedByUser: current.stoppedByUser }
+          : {}),
+        // terminal sessions have no live phase or transport endpoint
+        phase: null,
+        transport: null,
+      };
+    }
+    if (Number(current.renamedAt || 0) > Number(next.renamedAt || 0)) {
+      next = { ...next, title: current.title, renamedAt: current.renamedAt };
+    }
+    if (Number(current.pinnedAt || 0) > Number(next.pinnedAt || 0)) {
+      next = { ...next, pinned: current.pinned, pinnedAt: current.pinnedAt };
+    }
+  }
   const tmp = `${target}.${process.pid}.tmp`;
-  writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
   renameSync(tmp, target);
-  return state;
+  return next;
 }
 
 export function readBackgroundAgentState(id) {
@@ -177,6 +223,66 @@ export function renameBackgroundAgent(id, title, options = {}) {
   return next;
 }
 
+/**
+ * Remove a background agent's RECORD (state file + log) — `cc daemon rm`
+ * (gap-analysis 2026-07-11 P0 "后台 Agent Supervisor" 补 rm 动词). Terminal
+ * sessions (completed/failed/stopped/lost) remove directly; a still-running
+ * one is refused unless `force`, which stops it first. The underlying JSONL
+ * conversation session is NOT touched — that's `cc session delete`.
+ */
+export function removeBackgroundAgent(id, options = {}) {
+  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+    now: options.now,
+    heartbeatStaleMs: options.heartbeatStaleMs,
+  });
+  if (!state) throw new Error(`Background agent not found: ${id}`);
+  if (state.status === "running") {
+    if (options.force !== true) {
+      throw new Error(
+        `${id} is still running — stop it first (cc daemon stop ${id}) or pass --force`,
+      );
+    }
+    try {
+      stopBackgroundAgent(id);
+    } catch {
+      /* best-effort — the record removal below is the point of rm --force */
+    }
+  }
+  rmSync(statePath(id), { force: true });
+  if (options.keepLog !== true) {
+    rmSync(logPath(id), { force: true });
+  }
+  return { id, removed: true, status: state.status };
+}
+
+/**
+ * Pin/unpin a session for the dashboard (`cc daemon view`) — pinned sessions
+ * sort first inside their group. Same read-modify-write + verify-retry dance
+ * as rename: the worker's periodic state merges can clobber a write that
+ * lands inside its read→write window.
+ */
+export function setBackgroundAgentPinned(id, pinned, options = {}) {
+  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+    now: options.now,
+    heartbeatStaleMs: options.heartbeatStaleMs,
+  });
+  if (!state) throw new Error(`Background agent not found: ${id}`);
+  const value = pinned === true;
+  const pinnedAt = typeof options.now === "number" ? options.now : Date.now();
+  let next = { ...state, pinned: value, pinnedAt };
+  for (let attempt = 0; attempt < 4; attempt++) {
+    writeBackgroundAgentState(next);
+    sleepSyncMs(15);
+    const current = readBackgroundAgentState(id) || next;
+    if (current.pinned === value) {
+      return { ...current, pinned: value, pinnedAt };
+    }
+    next = { ...current, pinned: value, pinnedAt };
+  }
+  writeBackgroundAgentState(next);
+  return next;
+}
+
 /**
  * Build the follow-up argv template for interactive attach turns: the launch
  * argv minus every token that carried the FIRST turn's prompt (positional
@@ -258,6 +364,33 @@ export function resumeBackgroundAgent(id, prompt, options = {}) {
   });
 }
 
+/**
+ * Fail fast on an unusable cwd. Without this, spawn() surfaces a bad cwd as
+ * an ASYNC 'error' event on the detached child — which nothing listened to
+ * (uncaught exception with no context) — and the pre-written state/job files
+ * stayed behind as a phantom "running" session. Deleted, file-replaced, and
+ * unmounted paths all land here with one clear message.
+ */
+function assertUsableCwd(cwd) {
+  let reason = null;
+  if (!cwd) {
+    reason = "no working directory given";
+  } else if (!existsSync(cwd)) {
+    reason = "directory does not exist (deleted or unmounted?)";
+  } else {
+    try {
+      if (!statSync(cwd).isDirectory()) reason = "path is not a directory";
+    } catch (err) {
+      reason = `directory is not accessible (${err.code || err.message})`;
+    }
+  }
+  if (reason) {
+    throw new Error(
+      `Cannot launch background agent: cwd "${cwd ?? ""}" — ${reason}`,
+    );
+  }
+}
+
 export function launchBackgroundAgent({
   argv,
   cwd,
@@ -266,6 +399,7 @@ export function launchBackgroundAgent({
   cliEntry,
   followUpArgv,
 }) {
+  assertUsableCwd(cwd);
   const id = createBackgroundAgentId();
   const dir = backgroundAgentsDir();
   const jobFile = join(dir, `${id}.job.${process.pid}.json`);
@@ -317,6 +451,28 @@ export function launchBackgroundAgent({
     rmSync(statePath(id), { force: true });
     throw error;
   }
+  // Async spawn failures (EPERM, cwd raced away between the check and the
+  // spawn, …) arrive as an 'error' event on the detached child. Reap them
+  // into the state file instead of leaving a phantom "running" session and
+  // an uncaught exception.
+  if (typeof child.on === "function") {
+    child.on("error", (error) => {
+      try {
+        rmSync(jobFile, { force: true });
+        const current = readBackgroundAgentState(id);
+        if (current && current.status === "running") {
+          writeBackgroundAgentState({
+            ...current,
+            status: "failed",
+            endedAt: Date.now(),
+            lostReason: `spawn-error: ${error.code || error.message}`,
+          });
+        }
+      } catch {
+        /* best-effort */
+      }
+    });
+  }
   child.unref();
   const current = readBackgroundAgentState(id) || state;
   const withPid = {