ccdeck 3.37.1 → 3.38.1

package/src/server/session-enrichment.mjs

@@ -1,7 +1,9 @@
 // What the deck learns about a session that its hooks never say: the model,
-// the token spend, the session's name and recap, and the context it is
-// carrying — each read off the session's transcript (or, for a Codex session's
-// memory files, off its working tree) and sent on as a synthetic event.
+// the token spend, the session's name and recap, what it is doing now, and the
+// context it is carrying — each read off the session's transcript (or, for a
+// Codex session's memory files, off its working tree) and sent on as a
+// synthetic event. And, for a background session, the line Claude Code's own
+// agent view shows, read off its job folder (see claude-jobs.mjs).
 //
 // This lived in src/server/index.mjs, between the log rotation and the Codex
 // rollout reader. pushEvent asks it to look at every live hook event, and it
@@ -18,6 +20,9 @@ import { join } from "node:path";
 import { scanAgentsMdFiles, scanClaudeMdFiles } from "./memory-files.mjs";
 // Claude Code's "※ recap:" line — see session-recap.mjs.
 import { RECAP_MARK } from "./session-recap.mjs";
+// What the session is doing now, folded off the same tail — see
+// session-activity.mjs.
+import { foldActivityLine, newActivityState } from "./session-activity.mjs";
 // The shared transcript cursor every pass below reads through — see
 // transcript-scan.mjs.
 import { copyUsageBucket, hasSpend, mergeUsageByModel, newUsageTotals, scanTranscript } from "./transcript-scan.mjs";
@@ -495,6 +500,60 @@ function onRecapTail(sid, text, path) {
     .catch(() => {});
 }
 
+// ─── Session activity ────────────────────────────────────────────────────
+// What the session is doing now — the line Claude Code's agent view prints
+// beside a working session, by the same rule and with no model call (see
+// session-activity.mjs). Folded off the output watch's tail rather than the
+// transcript cursor: the watch is what reads a file BETWEEN hook events, and
+// between hook events is the whole of when this line changes. The cursor runs
+// off hooks and would hold a sentence the model wrote until the next tool call.
+//
+// The fold is per session and survives across ticks, because one reply's blocks
+// can land on either side of a tick and the sentence has to outrank the call it
+// introduced whichever tick read it. The emit is gated on the text changing, so
+// a reply that is still thinking says nothing.
+const activityBySession = new Map();    // sid -> the fold, see newActivityState
+
+function onActivityTail(sid, text) {
+  if (!sid || !text) return;
+  let st = activityBySession.get(sid);
+  if (!st) { st = newActivityState(); activityBySession.set(sid, st); }
+  const before = st.shown;
+  for (const line of text.split("\n")) foldActivityLine(st, line);
+  if (!st.shown || st.shown === before) return;
+  pushEvent({
+    hook_event_name: "ActivityObserved",
+    session_id: sid,
+    activity: { text: st.shown.text, source: st.shown.source, at: st.shown.at },
+  }, "internal");
+}
+
+/** Everything the output watch's tail feeds, in one tap: the recap and the
+ *  activity line read the same bytes for different questions. */
+function onTranscriptTail(sid, text, path) {
+  onRecapTail(sid, text, path);
+  onActivityTail(sid, text);
+}
+
+// ─── Background job ──────────────────────────────────────────────────────
+// Claude Code's own line for a background session — its state, what it is
+// doing or asking, and what it got done — read from the job folder its agent
+// view reads (see claude-jobs.mjs). Gated on a CHANGE like the recap, and on
+// the words rather than the file's clock: the classifier rewrites `updatedAt`
+// every fifteen seconds of a working turn, mostly to say the same thing. A
+// session with no job emits nothing at all, and a job that goes away (deleted
+// in the agent view) is said once, as null.
+const jobBySession = new Map();         // sid -> signature last sent, "" once gone
+
+function noteJob(sid, job) {
+  const sig = job ? JSON.stringify([job.state, job.detail, job.needs, job.suggestedReply, job.result]) : "";
+  const prev = jobBySession.get(sid);
+  if (prev === sig) return;
+  if (prev === undefined && !job) return;
+  jobBySession.set(sid, sig);
+  pushEvent({ hook_event_name: "JobObserved", session_id: sid, job: job ?? null }, "internal");
+}
+
 // ─── Context enrichment ──────────────────────────────────────────────────
 // Approximation of `/context` since CC doesn't expose its breakdown via
 // hooks. We scan the transcript JSONL for message counts (user / assistant
@@ -626,6 +685,10 @@ function forgetEnrichment(sid) {
   nameBySession.delete(sid);
   // The recap's gate, for the same reason — see noteRecap.
   recapBySession.delete(sid);
+  // And the activity fold and the job's gate: a session heard from again
+  // after this says what it is doing and what its job says afresh.
+  activityBySession.delete(sid);
+  jobBySession.delete(sid);
   nameReads.forget(sid);
   modelReads.forget(sid);
   usageReads.forget(sid);
@@ -641,6 +704,8 @@ function forgetEnrichment(sid) {
 function clearEnrichmentGates() {
   nameBySession.clear();
   recapBySession.clear();
+  activityBySession.clear();
+  jobBySession.clear();
   modelBySession.clear();
   // The read stamps go with them. Clearing only the signatures would leave
   // the next hook event inside MODEL_READ_THROTTLE_MS, so the transcript
@@ -658,5 +723,5 @@ function clearEnrichmentGates() {
 export {
   clearEnrichmentGates, forgetEnrichment, knownModelId, maybeResolveCodexMemory,
   maybeResolveContext, maybeResolveModel, maybeResolveSessionName, maybeResolveUsage,
-  onRecapTail,
+  noteJob, onRecapTail, onTranscriptTail,
 };

package/src/server/session-tracking.mjs

@@ -13,7 +13,10 @@ import { readBody, send } from "./http-io.mjs";
 // What a session is producing between its tool calls — the 16.5% of measured
 // time the hooks cannot see. See output-watch.mjs.
 import { createOutputWatch } from "./output-watch.mjs";
-import { forgetEnrichment, onRecapTail } from "./session-enrichment.mjs";
+// Claude Code's own line for a background session, from its job folder. See
+// claude-jobs.mjs.
+import { createJobWatch } from "./claude-jobs.mjs";
+import { forgetEnrichment, noteJob, onTranscriptTail } from "./session-enrichment.mjs";
 import { forgetCodexSession } from "./codex-enrichment.mjs";
 // event-pipeline.mjs's pushEvent, reached without importing it — see
 // event-sink.mjs.
@@ -96,6 +99,14 @@ const RECAP_WATCH_WINDOW_MS = 12 * 60 * 60_000;
 const RECAP_WATCH_EVERY = 4;
 let outputWatchTicks = 0;
 
+/** The job folders, every other tick: three seconds, well inside the fifteen
+ *  Claude Code itself waits between rewrites of a working job's line. The
+ *  sessions asked about are the resting window's, not the live one's — a
+ *  background job blocked on a question fires no hook for as long as nobody
+ *  answers it, and that is the job whose line matters most. */
+const jobWatch = createJobWatch();
+const JOB_WATCH_EVERY = 2;
+
 /** One tick: stat the recent sessions' transcripts, read only what grew, and
  *  say what landed. Everything expensive about this is guarded inside the watch
  *  — a session that wrote nothing costs one `stat`.
@@ -112,15 +123,23 @@ async function outputWatchOnce() {
   const now = Date.now();
   const cutoff = now - OUTPUT_WATCH_WINDOW_MS;
   const restingCutoff = now - RECAP_WATCH_WINDOW_MS;
-  const withResting = outputWatchTicks++ % RECAP_WATCH_EVERY === 0;
+  const tick = outputWatchTicks++;
+  const withResting = tick % RECAP_WATCH_EVERY === 0;
   const live = new Set();
   const polled = [];
+  const recent = [];
   for (const [sid, at] of sessionTouchedAt) {
     if (at >= cutoff) { live.add(sid); polled.push(sid); }
     else if (withResting && at >= restingCutoff) polled.push(sid);
+    if (at >= restingCutoff) recent.push(sid);
+  }
+  if (recent.length && tick % JOB_WATCH_EVERY === 0) {
+    const jobs = await jobWatch.poll().catch(() => null);
+    if (jobs) for (const sid of recent) noteJob(sid, jobs.get(sid) ?? null);
   }
   if (!polled.length) return;
-  const found = await outputWatch.poll(polled, onRecapTail);
+  // The recap and the activity line, off the same tail — see onTranscriptTail.
+  const found = await outputWatch.poll(polled, onTranscriptTail);
   for (const f of found) {
     if (!live.has(f.sid)) continue;
     pushEvent({

package/src/server/thermal-metrics.mjs

@@ -5,8 +5,9 @@
 // decides how often the machine is asked and when one that has never answered
 // stops being asked (sampleThermal). This file is the asking: readThermal
 // answers once per call, per platform, and nothing here keeps state between two
-// calls. WARN_C and CRIT_C are exported because the history's thermal series
-// fall back to them.
+// calls — the one reading that needs the call before it, Linux throttling, is
+// handed that call's answer back by the sampler. WARN_C and CRIT_C are exported
+// because the history's thermal series fall back to them.
 import { readdir, readFile } from "node:fs/promises";
 import { run } from "./metrics-run.mjs";
 
@@ -31,6 +32,17 @@ import { run } from "./metrics-run.mjs";
 //            bands are the hardware's rather than ones invented here.
 //            /sys/class/thermal/thermal_zone*/ is the coarser fallback.
 //
+//            Throttling comes from the kernel's own count of it, and for years
+//            it was not read at all: this branch answered `throttle: null`
+//            unconditionally, so a Linux machine never drew the row however
+//            hard it was being held back. Measured on an i5-12600H mini PC
+//            whose package sat at 90°C under a load of 41 — the panel showed
+//            the 90 and nothing else, while the kernel had logged 59 hours of
+//            package throttling in 17 days of uptime and was adding six seconds
+//            of it every ten. See readThrottleTime: Intel only, since the
+//            counters come from Intel's thermal-interrupt driver, and no row
+//            on a machine without them.
+//
 //   macOS    No CPU degrees without root, verified: `powermetrics --samplers
 //            smc` answers "powermetrics must be invoked as the superuser", and
 //            `ioreg -c AppleSMC -r -d 1` publishes no temperature key at all to
@@ -260,6 +272,91 @@ export async function readThermalZones(root = "/sys/class/thermal", deps = {}) {
   return [known ?? found.reduce((a, b) => (b.celsius > a.celsius ? b : a))];
 }
 
+/**
+ * How long each CPU package has spent thermally throttled since boot, in
+ * milliseconds, keyed by package — or null on a machine that does not count it.
+ *
+ * Intel's thermal-interrupt driver publishes, per CPU,
+ * `cpuN/thermal_throttle/package_throttle_total_time_ms`: the time the
+ * package's thermal monitor has held the clock down, summed over every event.
+ * Measured on a live machine, ten seconds apart:
+ *
+ *   cpu0   package_throttle_total_time_ms  212885052 → 212890804
+ *   cpu15  package_throttle_total_time_ms  212885101 → 212891179
+ *
+ * Every CPU of a package carries its own copy of the package's count, and the
+ * copies differ by the few events each one saw late — so the package's figure
+ * is the largest of them, which is also the one that survives a CPU going
+ * offline. The `core_*` files beside them are one core's own throttling and are
+ * not read: the CPU row is the package, and a throttle row about one core of it
+ * would be a different reading under the same label.
+ *
+ * Absent on AMD and on every virtual machine, and on a kernel older than 5.12,
+ * which counts events but not their time. A count of events is not a share of
+ * anything, so those machines draw no row rather than a guess.
+ */
+export async function readThrottleTime(root = "/sys/devices/system/cpu", deps = {}) {
+  const dir = deps.readdir ?? readdir;
+  const file = deps.readFile ?? readFile;
+  const read = async path => { try { return String(await file(path, "utf8")).trim(); } catch { return null; } };
+  let cpus;
+  try { cpus = (await dir(root)).filter(n => /^cpu\d+$/.test(n)); } catch { return null; }
+  const held = {};
+  for (const cpu of cpus) {
+    const ms = Number(await read(`${root}/${cpu}/thermal_throttle/package_throttle_total_time_ms`) ?? NaN);
+    if (!Number.isFinite(ms) || ms < 0) continue;
+    const pkg = (await read(`${root}/${cpu}/topology/physical_package_id`)) ?? "0";
+    if (held[pkg] == null || ms > held[pkg]) held[pkg] = ms;
+  }
+  return Object.keys(held).length ? held : null;
+}
+
+/**
+ * The share of the time between two counts that the CPU spent throttled, as
+ * `{ timeHeld }`, or null when there are not two counts to compare.
+ *
+ * A SHARE OF TIME, NOT OF SPEED, and the shape says so rather than borrowing
+ * macOS's `speedLimit`. `pmset` reports how much of the clock the thermal
+ * manager allows; the kernel reports how long the clock was held down, and by
+ * how much it was held is not in the file. Writing 60% of the time as "held to
+ * 40% of full speed" would be a number this module made up.
+ *
+ * The worst package wins, for the reason the hottest sensor does: the question
+ * is whether this machine is being held back, and one package that is answers
+ * it. Any throttling at all is at least 1%, because a few milliseconds of it
+ * round to zero and the panel paints zero as "never held back".
+ *
+ * The kernel adds an event's time when the event ENDS, so one still running at
+ * a sample lands in the next. Events here run 5ms on average and 119ms at the
+ * longest, measured, so that is a sample's worth of lag at most — and the 100
+ * cap is for the one long event that lands whole in a single sample.
+ */
+export function throttleFromTime(prev, next) {
+  if (!prev || !next) return null;
+  const elapsed = next.atMs - prev.atMs;
+  if (!(elapsed > 0)) return null;
+  let worst = null;
+  for (const [pkg, ms] of Object.entries(next.held)) {
+    const before = prev.held[pkg];
+    if (before == null) continue;
+    const share = (Math.max(0, ms - before) / elapsed) * 100;
+    if (worst == null || share > worst) worst = share;
+  }
+  if (worst == null) return null;
+  return { timeHeld: worst > 0 ? Math.min(100, Math.max(1, Math.round(worst))) : 0 };
+}
+
+/**
+ * The share of the CPU the thermal manager took away, whichever way this
+ * platform measures it: the speed `pmset` says is no longer allowed, or the
+ * time the kernel says the clock was held down. The one number the chart, the
+ * strip and the row's bar all draw — mirrored by `heldShare` in machine-live.ts.
+ */
+export function heldShare(throttle) {
+  const held = "timeHeld" in throttle ? throttle.timeHeld : 100 - throttle.speedLimit;
+  return Math.max(0, Math.min(100, held));
+}
+
 /**
  * GPU degrees out of `ioreg -r -k PerformanceStatistics`.
  *
@@ -458,13 +555,25 @@ export function darwinThermal({ gpuC = null, throttle = null, macmon = {} } = {}
  * collapsing them would let a throttle percentage be drawn under a °C heading
  * — the thing the label rule exists to prevent. `swapLabel` earned that rule
  * once already.
+ *
+ * `since` is the reading before this one. Only Linux uses it: its throttle is a
+ * difference between two counts, so the count rides along on the reading as
+ * `throttleCount` and the sampler hands it back on the next call. The first
+ * reading after a start therefore has no throttle yet, the same way `cpu` is
+ * null until two samples exist.
  */
-export async function readThermal(platform = process.platform) {
+export async function readThermal(platform = process.platform, since = null) {
   if (platform === "linux") {
     const sensors = await readHwmon();
     const celsius = pickThermalRows(sensors);
     const rows = celsius.length ? celsius : await readThermalZones();
-    return rows.length ? { celsius: rows, throttle: null } : null;
+    const held = await readThrottleTime();
+    // performance.now rather than Date.now: a clock that NTP steps backwards
+    // between two samples would otherwise divide by a negative ten seconds.
+    const throttleCount = held ? { atMs: performance.now(), held } : null;
+    const throttle = throttleFromTime(since?.throttleCount, throttleCount);
+    if (!rows.length && !throttle) return null;
+    return { celsius: rows, throttle, ...(throttleCount ? { throttleCount } : {}) };
   }
 
   if (platform === "darwin") {

package/src/server/thermal-sampler.mjs

@@ -10,7 +10,7 @@
 // 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";
+import { heldShare, readThermal } from "./thermal-metrics.mjs";
 
 // ---------------------------------------------------------------------------
 // Thermal: how often this machine is asked whether it is getting hot, and when
@@ -60,7 +60,7 @@ function recordThermal(reading, nowMs = Date.now()) {
   // 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);
+    record(`thermal:${THROTTLE_LABEL}`, heldShare(reading.throttle), nowMs);
   }
 }
 
@@ -114,7 +114,9 @@ export async function sampleThermal(deps = {}) {
   const read = deps.read ?? readThermal;
   thermalInFlight = true;
   try {
-    const next = await read();
+    // The last reading goes back in because Linux throttling is the difference
+    // between its count and this one's. See readThermal.
+    const next = await read(process.platform, thermal);
     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
@@ -181,7 +183,11 @@ export function lastThermal() {
 /** 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;
+  if (!thermal) return null;
+  // The raw kernel count is the sampler's, for the next difference, and not a
+  // reading: the route answers what the panel draws.
+  const { throttleCount, ...shown } = thermal;
+  return { ...shown, heldBack: heldBackSoFar() };
 }
 
 /** The ten-second timer, made where startSystemMetrics in system-metrics.mjs