ccdeck 3.29.11 → 3.31.0

package/src/server/thermal-sampler.mjs

@@ -0,0 +1,204 @@
+// The Machine panel's thermal section: the sampler that asks this machine
+// whether it is getting hot, every ten seconds, and stops asking one that has
+// never answered.
+//
+// Moved out of system-metrics.mjs unchanged. What is asked, and how each
+// platform's answer is read, is thermal-metrics.mjs, which keeps no state; the
+// minute ring the readings are recorded into is metrics-history.mjs.
+// system-metrics.mjs starts and stops this section (startThermalTimer,
+// stopThermal), draws the thermal chart with the bands of lastThermal, puts
+// thermalSnapshot on /api/system, and re-exports sampleThermal and
+// THROTTLE_LABEL, which is where the suite reaches them.
+import { pointsOf, record } from "./metrics-history.mjs";
+import { readThermal } from "./thermal-metrics.mjs";
+
+// ---------------------------------------------------------------------------
+// Thermal: how often this machine is asked whether it is getting hot, and when
+// one that has never answered stops being asked. What is asked, and why those
+// sources on each platform, is thermal-metrics.mjs.
+
+/** How often the thermal reading is refreshed. Heat moves on the scale of
+ *  seconds, and the two platforms that cost a subprocess to ask cost 51ms
+ *  (`ioreg`) and rather less (`pmset`), measured. Linux costs a file read. */
+const THERMAL_INTERVAL_MS = 10_000;
+
+/**
+ * How many consecutive empty readings before this machine is left alone.
+ *
+ * The reason is Windows, where MSAcpi_ThermalZoneTemperature is absent on a
+ * large share of desktops: without this, every one of those machines would pay
+ * a `Get-CimInstance` child every ten seconds, forever, to render a section it
+ * can never render. Three rather than one because a single failure can be a
+ * hiccup — a timeout, a machine mid-wake — and giving up on a hiccup would lose
+ * a reading the machine does have.
+ *
+ * Not persisted. A restart asks again, which is what should happen after the
+ * user installs a driver or changes a firmware setting.
+ */
+const THERMAL_GIVE_UP = 3;
+
+let thermal = null;
+let thermalTimer = null;
+let thermalInFlight = false;
+/** Consecutive readings that came back with nothing. See THERMAL_GIVE_UP. */
+let thermalMisses = 0;
+/** Whether this machine has EVER answered. See sampleThermal. */
+let thermalEverAnswered = false;
+
+/**
+ * The thermal reading, whose series are not known until the machine answers.
+ *
+ * Keyed by the row's own label rather than by position, because the rows are
+ * not the same on every platform and a machine can start reporting a sensor it
+ * was not reporting before — a GPU driver loads, a laptop is docked. A series
+ * that appears late simply has no points before it appeared, which is the truth
+ * and draws correctly.
+ */
+function recordThermal(reading, nowMs = Date.now()) {
+  if (!reading) return;
+  for (const r of reading.celsius ?? []) record(`thermal:${r.label}`, r.celsius, nowMs);
+  // Stored as the share TAKEN AWAY, the same way the panel draws it, so the
+  // chart and the row cannot disagree about which direction is bad.
+  if (reading.throttle) {
+    record(`thermal:${THROTTLE_LABEL}`, Math.max(0, 100 - reading.throttle.speedLimit), nowMs);
+  }
+}
+
+/** The one thermal row that is not degrees. Named once so the recorder, the
+ *  route and the panel cannot drift apart on the spelling. */
+export const THROTTLE_LABEL = "Throttling";
+
+/**
+ * Whether this machine has been held back AT ALL since the deck started, and
+ * when it last was.
+ *
+ * The row reports the current sample, and on a desktop that current sample is
+ * `0%` essentially always — measured here: ninety seconds of AES-NI on twelve
+ * cores never moved `CPU_Speed_Limit` off 100. Which is the truth, and which
+ * reads as "this readout does not work" the second time somebody looks at it.
+ * It was reported that way twice.
+ *
+ * So the note under the row gets to say the other thing. Nothing new is
+ * sampled for it: the minute buckets already hold the peak of every minute, and
+ * this is a scan of what is already there. A machine that has never been
+ * throttled says so; one that was at lunchtime says when.
+ */
+function heldBackSoFar() {
+  const key = `thermal:${THROTTLE_LABEL}`;
+  let peak = 0;
+  let lastMs = 0;
+  for (const { t, v } of pointsOf(key)) {
+    if (v <= 0) continue;
+    if (v > peak) peak = v;
+    lastMs = t;
+  }
+  return peak > 0 ? { peak, lastMs } : null;
+}
+
+/**
+ * One reading at a time, and a machine that cannot answer is asked three times
+ * rather than for the life of the process.
+ *
+ * `deps.read` is a seam rather than a convenience: the rule this function
+ * exists for only fires on a machine that answers with nothing, and the machine
+ * this was written on answers with something, so there is no other way to run
+ * the branch that matters.
+ */
+export async function sampleThermal(deps = {}) {
+  if (thermalInFlight) return;
+  // Giving up is only ever for a machine that has NEVER answered — the Windows
+  // desktop with no MSAcpi class, which would otherwise pay a PowerShell child
+  // every ten seconds for the life of the process. A machine that answered once
+  // has a sensor, and it keeps being asked however long the silence runs.
+  if (!thermalEverAnswered && thermalMisses >= THERMAL_GIVE_UP) return;
+  const read = deps.read ?? readThermal;
+  thermalInFlight = true;
+  try {
+    const next = await read();
+    if (next) { thermal = next; thermalMisses = 0; thermalEverAnswered = true; recordThermal(next); }
+    else if (++thermalMisses >= THERMAL_GIVE_UP) {
+      // DROP THE LAST READING. It used to be kept, and that is a number from
+      // four minutes ago printed as though it were now — the one thing this
+      // whole section refuses. A GPU driver unloads, a laptop is docked, a
+      // sensor goes away: the honest answer is that the section stops being
+      // drawn, not that it freezes.
+      thermal = null;
+      // But keep ASKING on a machine that has answered before. The cost
+      // argument for giving up was only ever about a machine that can never
+      // answer — a Windows desktop with no MSAcpi class paying a PowerShell
+      // child every ten seconds forever. One that answered has a sensor, and a
+      // silence is a gap rather than an absence.
+      if (!thermalEverAnswered && thermalTimer) {
+        clearInterval(thermalTimer);
+        thermalTimer = null;
+      }
+      // The one machine where "nothing" is worth doing something about: an
+      // Apple Silicon Mac has sensors and no way to read them, and the tool
+      // that can is a 746 KB signed binary this deck can fetch. Started HERE
+      // rather than at boot on purpose — the boot was just taught not to wait
+      // for an install (#742) and nothing waits for this one either. One
+      // attempt per process, and only after the give-up, so a machine that
+      // does have a sensor never downloads anything. See macmon.mjs.
+      if (!thermalEverAnswered && process.platform === "darwin") fetchMacmon(deps);
+    }
+  } catch { thermalMisses++; }
+  finally { thermalInFlight = false; }
+}
+
+/**
+ * Fetch macmon, then ask again — floating, on purpose.
+ *
+ * Not awaited by sampleThermal, which is itself not awaited by anything: this
+ * is a download that may take a minute on a slow line, and the panel it serves
+ * is optional. When it lands, the give-up above has already stopped the timer,
+ * so the retry has to be made here rather than waited for.
+ */
+function fetchMacmon(deps = {}) {
+  const boot = deps.bootstrap ?? (async () => (await import("./macmon.mjs")).bootstrapMacmon());
+  Promise.resolve(boot()).then(r => {
+    if (!r?.ok) return;
+    // A sensor exists after all. Clear the give-up and let the timer run again,
+    // which is what turns a downloaded binary into a section on screen without
+    // the user restarting anything.
+    thermalMisses = 0;
+    if (!thermalTimer) {
+      thermalTimer = setInterval(() => { sampleThermal(deps); }, THERMAL_INTERVAL_MS);
+      // Unref'd like the one startThermalTimer creates: a poll for an optional
+      // panel must not be the reason a process refuses to exit.
+      thermalTimer.unref?.();
+    }
+    sampleThermal(deps);
+  }).catch(() => {});
+}
+
+/** The last reading, or null while there is none — before the first answer,
+ *  and once a silence has dropped it. The thermal chart's bands come from it
+ *  (thermalSeries in system-metrics.mjs). */
+export function lastThermal() {
+  return thermal;
+}
+
+/** The thermal row /api/system answers: the last reading, with whether the
+ *  machine has been held back since the deck started, or null without one. */
+export function thermalSnapshot() {
+  return thermal ? { ...thermal, heldBack: heldBackSoFar() } : null;
+}
+
+/** The ten-second timer, made where startSystemMetrics in system-metrics.mjs
+ *  makes the others and unref'd like them. Once a give-up has stopped it,
+ *  fetchMacmon is what makes it again. */
+export function startThermalTimer() {
+  thermalTimer = setInterval(sampleThermal, THERMAL_INTERVAL_MS);
+  thermalTimer.unref?.();
+}
+
+/** Stop the timer and forget the reading, the misses and whether this machine
+ *  ever answered — this section's half of stopSystemMetrics in
+ *  system-metrics.mjs, and there for the same reason (#798). */
+export function stopThermal() {
+  if (thermalTimer) clearInterval(thermalTimer);
+  thermalTimer = null;
+  thermal = null;
+  thermalMisses = 0;
+  thermalEverAnswered = false;
+}

package/src/server/token-redact.mjs

@@ -0,0 +1,123 @@
+// The deck's own token, taken back out of an event before anything stores it
+// (#366).
+//
+// This lived in src/server/index.mjs, just above pushEvent, which calls it
+// before anything else sees an event. It reads nothing but HOOK_TOKEN, so it
+// moved to a leaf of its own; the walk is unchanged.
+import { HOOK_TOKEN } from "./request-gates.mjs";
+
+// What a redacted occurrence of the deck's token is replaced with. A visible
+// marker rather than an empty string, because the reader of a mangled Bash
+// output deserves to know the deck did it and why, and because the UI renders
+// payload strings verbatim — a silent hole would look like a truncated tool
+// response and get debugged as one.
+const TOKEN_REDACTED = "[redacted: ccdeck token]";
+
+/**
+ * Take the deck's own token back out of an event, before anything stores it.
+ *
+ * #366 made HOOK_TOKEN the one credential separating "may read" from "may
+ * mutate", and there is a path that copies it into a store needing no
+ * credential to read. `POST /api/event` is deliberately open — hook/hook.js is
+ * installed outside this package, into the user's ~/.claude, so requiring a
+ * credential there would silence every session whose hook predates that change
+ * — while `GET /api/events`, `GET /events` and events.jsonl are all readable
+ * without one. So an agent session that merely LOOKS at the discovery file puts
+ * the token into the ring buffer, and that is not an exotic act: `cat
+ * ~/.claude/agent-dag/<pid>.json`, a `Read` of it, or a plain `grep -r
+ * ~/.claude` all do it, and CC records both the tool input and the tool
+ * response. From the buffer it is served to exactly the two callers #366 was
+ * written for — the other local UID and the sandboxed subprocess — neither of
+ * which can open the discovery file itself but both of which reach the API. For
+ * them this turned "cannot mutate" back into "can mutate", the token read out
+ * of the event log being the whole of the new gate. What keeps those two out of
+ * the discovery file itself — a mode bit on Unix, the profile directory's ACL
+ * on Windows, where the chmod is a no-op — is spelled out at presentsDeckToken.
+ *
+ * Why pushEvent calls this and not handleEventIngest, which is where the
+ * report first put it. Events reach the buffer through more than one door:
+ * handleEventIngest is the hook's, emitCodexEvent is the Codex rollout
+ * watcher's — those events never pass through an HTTP handler at all —
+ * replayLog is the boot replay's, `/api/clear` pushes its own marker, and six
+ * enrichment sites push synthetic events off the back of a transcript read.
+ * Redacting at the ingest handler covers one of those and leaves the next route
+ * somebody adds uncovered. pushEvent is the one point every event passes
+ * through exactly once, so the check is written once and cannot be forgotten.
+ *
+ * Why a walk over the string values rather than
+ * `JSON.stringify(payload).includes(token)`, which is the obvious one-liner.
+ * Measured rather than assumed, on 4.7k real payloads out of a 21MB
+ * events.jsonl (mean 5KB serialized): the walk costs 1.3–3.6 µs per event and
+ * serialize-then-search costs 14–48 µs, the same order as the JSON.parse the
+ * ingest path already pays for the body. Serializing here would also defeat the
+ * deliberate optimization in pushEvent, which skips serializing ENTIRELY when
+ * nothing is subscribed and nothing is being logged — a headless deck, and the
+ * boot replay of a log that only rotates at 50MB. The walk allocates nothing at
+ * all until it finds something.
+ *
+ * Iterative rather than recursive on purpose. The payload arrives from
+ * JSON.parse of a body capped at 5MB, which is free to nest as deeply as it
+ * likes, and a recursive scan would be a new way to overflow the stack inside
+ * the request listener — where nothing catches it.
+ *
+ * Scope is the token and nothing else in the discovery file. pid, port,
+ * workspace, the log path and startedAt are not credentials — /api/health
+ * already answers with the workspace path — and redacting the workspace would
+ * mangle the `cwd` of every honest event the deck draws.
+ *
+ * What this does NOT catch, stated plainly so nobody mistakes it for more. A
+ * token split across two string fields, or across two events, survives — but
+ * every substring search has that shape, and the halves are individually
+ * worthless: secretEquals is byte-exact, so a partial token authenticates
+ * nothing. Case is not folded for the same reason; HOOK_TOKEN is lowercase hex
+ * and an uppercased copy would not authenticate either.
+ *
+ * And this is not a new oracle. A caller who can POST here and read
+ * /api/events can post a guess and watch whether it comes back redacted, which
+ * tells them precisely what `x-ccdeck-token: <guess>` on any protected route
+ * already tells them — against 256 bits with no structure to search.
+ *
+ * Returns the payload, because a top-level JSON string is a legal body for
+ * `POST /api/event` and a primitive cannot be redacted in place.
+ */
+function redactDeckToken(raw) {
+  // HOOK_TOKEN is request-gates.mjs's, and an import is bound before this
+  // module's body runs, so it is set long before the first event arrives.
+  const token = HOOK_TOKEN;
+  if (typeof raw === "string") return raw.includes(token) ? raw.replaceAll(token, TOKEN_REDACTED) : raw;
+  if (raw === null || typeof raw !== "object") return raw;
+
+  const stack = [raw];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    // Arrays and objects are walked separately because an indexed loop over an
+    // array is markedly cheaper than `for…in` over one, and this runs on every
+    // event: a single PostToolUse response can be an array of thousands.
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) {
+        const v = node[i];
+        if (typeof v === "string") {
+          if (v.includes(token)) node[i] = v.replaceAll(token, TOKEN_REDACTED);
+        } else if (v !== null && typeof v === "object") stack.push(v);
+      }
+    } else {
+      // `for…in` is safe on these: they come from JSON.parse or from an object
+      // literal in the server's own code, so the prototype chain is
+      // Object.prototype, which has nothing enumerable. A `"__proto__"` key in
+      // the posted JSON becomes an OWN data property — JSON.parse does not run
+      // the setter — so it both enumerates here and takes the assignment below
+      // as an ordinary write, leaving the prototype alone.
+      for (const k in node) {
+        const v = node[k];
+        if (typeof v === "string") {
+          if (v.includes(token)) node[k] = v.replaceAll(token, TOKEN_REDACTED);
+        } else if (v !== null && typeof v === "object") stack.push(v);
+      }
+    }
+  }
+  return raw;
+}
+
+// What pushEvent calls. Listed rather than marked at the declaration, so the
+// declaration reads as it did where it came from.
+export { redactDeckToken };

package/src/server/transcript-gate.mjs

@@ -0,0 +1,107 @@
+// Which transcript paths the deck will open at all: the gate pushEvent asks
+// before any enrichment pass reads the `transcript_path` a hook payload names,
+// and the once-per-path note on stderr when it refuses one.
+//
+// This lived at the end of src/server/transcript-scan.mjs, and nothing in the
+// scanner ever called it. event-pipeline.mjs asks it once, at the one door a
+// caller-chosen path comes through, and only then hands the path to the
+// passes that scan it. The bodies are unchanged, and index.mjs still
+// re-exports isClaudeTranscriptPath.
+import { resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { claudeConfigDir } from "./claude-dir.mjs";
+import { PRODUCT } from "./brand.mjs";
+// Whether this platform's filesystem folds case — the one answer every
+// server-side path comparison gives. See foldsCase in log-election.mjs.
+import { foldsCase } from "./log-election.mjs";
+
+// ─── Which paths the deck will follow at all ─────────────────────────────
+// `payload.transcript_path` is a string in the body of `POST /api/event`, and
+// that route is a deliberate OPEN_MUTATION: no token, no Origin, nothing. Until
+// #674 the deck took whatever it said and opened it. The bounds on the read
+// (MAX_SCAN_CHUNK in jsonl-chunks.mjs, MAX_SCAN_BYTES_PER_PASS in
+// transcript-scan.mjs) make that survivable; this makes it uninteresting, and
+// the two are worth having together for different reasons.
+//
+// WHY VALIDATE AT ALL WHEN THE READ IS ALREADY BOUNDED. Because the caller here
+// is not a web page — `isTrustedMutation` refuses `Sec-Fetch-Site: cross-site`
+// before any of this — it is a local process: the sandboxed subprocess with
+// loopback egress that the comment above `isAuthorizedMutation` already names,
+// or another UID on a shared box. Against that caller a ceiling only sets the
+// price per request; it does not take the lever away. What takes it away is
+// that there is no file it can name. Claude Code writes transcripts in exactly
+// one place, `<config dir>/projects/…`, and every legitimate `transcript_path`
+// the deck has ever seen is one of those — so the set of things worth opening
+// is knowable in advance, and checking membership costs one string comparison
+// against a syscall that used to cost the size of the file.
+//
+// WHAT IS LEFT AFTERWARDS, stated plainly: a caller who can WRITE inside that
+// directory can still point the deck at a file of its choosing. That caller is
+// this user's own processes — and this user's own processes can read
+// `<config dir>/agent-dag/*.json`, which is where HOOK_TOKEN lives at mode
+// 0600, so they hold the credential already. The gate reduces the
+// credential-free adversary to the one who was never credential-free. That is
+// the whole of what it claims, and those ceilings on the read are what carries
+// the rest.
+//
+// WHY NOT realpath. A symlink planted inside the projects directory would
+// defeat the containment test — but planting one needs write access to that
+// directory, which is the case above where the caller already holds the token.
+// It would also cost a syscall on every hook event, on a path that runs for
+// every event of every live session.
+//
+// WHY TWO ROOTS. CLAUDE_CONFIG_DIR replaces ~/.claude wholesale, and the deck
+// reads the variable from its OWN environment while the path is written by
+// whatever `claude` process the hook fired in. Those normally agree — the deck
+// installs its hook into the directory it resolves, so a session whose events
+// arrive here is a session reading that same directory — but a deck launched
+// from a desktop shortcut that never sourced the shell rc is a real way for
+// them to disagree in one direction. Accepting the default location as well
+// costs nothing (it is a directory only this user writes either way) and
+// removes half of that failure mode. The other half is why the refusal is
+// logged rather than silent.
+function claudeTranscriptRoots() {
+  // Resolved per call, like every other claudeConfigDir() reader in src/server,
+  // so nothing captures the answer from an environment that has moved.
+  const roots = [resolve(claudeConfigDir(), "projects")];
+  const byDefault = resolve(homedir(), ".claude", "projects");
+  if (!roots.includes(byDefault)) roots.push(byDefault);
+  return roots;
+}
+
+/** Is `p` a Claude Code transcript, in a directory Claude Code writes them?
+ *
+ *  Containment is compared on the RESOLVED path with a trailing separator, so
+ *  `…/projects-of-mine/x.jsonl` is not inside `…/projects` and `..` cannot
+ *  climb out of it. The comparison is case-insensitive on Windows and macOS,
+ *  whose default filesystems are, because the two halves come from two
+ *  processes and only one of them chose the casing. */
+export function isClaudeTranscriptPath(p, roots = claudeTranscriptRoots()) {
+  if (!p || typeof p !== "string") return false;
+  if (!/\.jsonl$/i.test(p)) return false;      // the only extension CC writes
+  const fold = foldsCase();
+  const full = fold ? resolve(p).toLowerCase() : resolve(p);
+  for (const root of roots) {
+    const prefix = (fold ? root.toLowerCase() : root) + sep;
+    if (full.startsWith(prefix) && full.length > prefix.length) return true;
+  }
+  return false;
+}
+
+// Refusals are logged once per path and the set is capped, because the point of
+// the log is a misconfigured deck saying so on stderr — one line naming the
+// path and where transcripts are expected — and a caller posting a fresh path
+// per request must not turn that into a second unbounded accumulation.
+const refusedTranscriptPaths = new Set();
+const MAX_REFUSED_TRANSCRIPT_PATHS = 64;
+
+function noteRefusedTranscript(p) {
+  if (refusedTranscriptPaths.has(p)) return;
+  if (refusedTranscriptPaths.size >= MAX_REFUSED_TRANSCRIPT_PATHS) return;
+  refusedTranscriptPaths.add(p);
+  console.warn(`${PRODUCT}: not reading transcript_path outside ${claudeTranscriptRoots().join(" or ")}: ${p}`);
+}
+
+// What event-pipeline.mjs calls besides isClaudeTranscriptPath above. Listed
+// rather than marked, so the declaration reads as it did where it came from.
+export { noteRefusedTranscript };