create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/background-stop.js

@@ -0,0 +1,369 @@
+'use strict';
+
+// WP-3a (design doc docs/background-gate-watchers-bounded-observation-2026-10-26.html §5 R7–R10,
+// §6.4, §8 WP-3): the SERVER half of the operator stop for exactly ONE hook-declared background
+// shell of a local session. The UI button is WP-3b.
+//
+// The operator's click is the decision (R8: report by default, stop on a decision). What this
+// module never does is guess: the target is a process group leader (pid === pgid) that is a
+// STRICT descendant of the session's agent pid AND whose argv carries the ledger entry's declared
+// label in the CLI's own `eval '…'` encoding. Zero or several matches, an identity change between
+// two reads, or a target that is the agent's own group all refuse with nothing signalled.
+//
+// Identity is the triple (pid, pgid, startedAt) — never a process name (R7, P6): pgrep-style
+// matching matches its own observer and would signal a second session's identically-worded shell.
+//
+// Escalation is §6.4's ladder and ONLY the ladder: SIGTERM the group, wait the lifecycle's park
+// grace, re-read, SIGKILL the group if any row of that pgid remains, re-read, report survivors.
+// There is no caller-chosen signal. Nothing here removes the ledger entry (R9: the CLI's next
+// Stop/task notification does that) and nothing retries.
+
+const { execFile } = require('node:child_process');
+const { lifecycleConfigFromEnv } = require('./session-lifecycle');
+const { requesterFromRequest } = require('./restart-ledger');
+
+// §6.5's read, verbatim: one `ps` read carrying the identity triple (lstart = process start time)
+// plus the argv the label is matched against. `-axo` is macOS/BSD; the GNU spelling is the same.
+const PS_STOP_ARGS = Object.freeze(['-axo', 'pid=,ppid=,pgid=,lstart=,command=']);
+const PS_TIMEOUT_MS = 10_000;
+const PS_MAX_BUFFER = 8 * 1024 * 1024;
+
+// The response carries a head, not the whole argv: a Claude Code background shell's command line
+// embeds the entire snapshot preamble and can be tens of kilobytes.
+const ARGV_HEAD_MAX = 200;
+
+// Inside the CLI's `eval '…'` a single quote is encoded as '"'"' (observed in a live argv,
+// §"Measured facts"). The needle deliberately has no closing quote: the ledger label is the
+// command truncated to 160 chars, so the real argv is normally LONGER than the needle.
+const EVAL_QUOTE_ESCAPE = `'"'"'`;
+
+const STOP_BODY_LIMIT_BYTES = 1024;
+const AUDIT_KIND = 'status-background-stopped';
+
+// One stop per (session, task) at a time. Postgres-free and process-free on purpose: the key is
+// only ever held across an awaited resolve + ladder, and it is released in `finally`.
+const inFlightStops = new Set();
+
+// `  44398   51583   44398 Mon Oct 26 17:58:01 2026     /bin/zsh -c source …`
+// lstart is FIVE whitespace-separated tokens; the argv is everything after them, verbatim except
+// for the whitespace run ps uses to align the column. Day-of-month is space-padded by ps
+// ("Mon Oct  6 …"), which is why lstart is token-matched and then normalised rather than sliced.
+const STOP_ROW_RE = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)(?:\s+(.*))?$/;
+
+function parseStopRows(text) {
+  const rows = [];
+  for (const line of String(text == null ? '' : text).split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const match = STOP_ROW_RE.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const ppid = Number(match[2]);
+    const pgid = Number(match[3]);
+    if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(ppid) || !Number.isSafeInteger(pgid)) continue;
+    rows.push({
+      pid,
+      ppid,
+      pgid,
+      startedAt: match[4].trim().replace(/\s+/g, ' '),
+      command: String(match[5] == null ? '' : match[5]).trim(),
+    });
+  }
+  return rows;
+}
+
+// The substring every Claude Code background shell's argv carries: the wrapper's `eval '<command>'`
+// with the command's own single quotes in the shell's close/double/open encoding.
+function evalNeedle(label) {
+  return `eval '${String(label == null ? '' : label).replace(/'/g, EVAL_QUOTE_ESCAPE)}`;
+}
+
+function strictDescendants(byParent, agentPid) {
+  const seen = new Set([agentPid]);
+  const queue = [...(byParent.get(agentPid) || [])];
+  const out = [];
+  while (queue.length) {
+    const pid = queue.shift();
+    // A cyclic or duplicated ppid edge must not turn the walk into an infinite loop.
+    if (seen.has(pid)) continue;
+    seen.add(pid);
+    out.push(pid);
+    queue.push(...(byParent.get(pid) || []));
+  }
+  return out;
+}
+
+// §6.4's candidate/target view of a row — what the 409 and the 200 both carry.
+function candidateOf(row) {
+  return {
+    pid: row.pid,
+    pgid: row.pgid,
+    startedAt: row.startedAt,
+    argvHead: String(row.command || '').slice(0, ARGV_HEAD_MAX),
+  };
+}
+
+// rows → the single group leader that is this session's declared shell, or a typed refusal.
+function resolveBackgroundTarget(rows, { agentPid, label } = {}) {
+  const agent = Number(agentPid);
+  const byPid = new Map();
+  const byParent = new Map();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!Number.isSafeInteger(row && row.pid)) continue;
+    if (!byPid.has(row.pid)) byPid.set(row.pid, row);
+    const kids = byParent.get(row.ppid);
+    if (kids) kids.push(row.pid);
+    else byParent.set(row.ppid, [row.pid]);
+  }
+  // The agent's own group is never a target (R7 refusal): its row when present, the pid itself
+  // otherwise — the CLI is a group leader of its own, so the fallback is the same value.
+  const agentRow = byPid.get(agent);
+  const agentPgid = agentRow ? Number(agentRow.pgid) : agent;
+  const needle = evalNeedle(label);
+
+  const candidates = [];
+  for (const pid of strictDescendants(byParent, agent)) {
+    const row = byPid.get(pid);
+    if (!row) continue;
+    // A group LEADER only: signalling a non-leader would signal whichever group it happened to
+    // be in, i.e. someone else's (a `sleep` under bounded.js leads its own group, E4).
+    if (Number(row.pid) !== Number(row.pgid)) continue;
+    if (!String(row.command || '').includes(needle)) continue;
+    candidates.push(row);
+  }
+  if (!candidates.length) return { error: 'task_process_not_found' };
+  // Refusal outranks ambiguity: a candidate inside the agent's own group means the label matched
+  // something that is not a background task at all, and the agent's group is exactly what park
+  // and the freeze machinery own.
+  if (candidates.some((row) => Number(row.pgid) === agentPgid)) return { error: 'target_is_agent' };
+  if (candidates.length > 1) {
+    return { error: 'ambiguous', candidates: candidates.map(candidateOf).sort((a, b) => a.pid - b.pid) };
+  }
+  return { target: candidateOf(candidates[0]) };
+}
+
+function targetIdentity(target) {
+  return { pid: target.pid, pgid: target.pgid, startedAt: target.startedAt };
+}
+
+// The same triple compared across two reads, or against the chip's `expect`. pid/pgid arrive as
+// JSON numbers or strings depending on the client, so they are compared numerically; startedAt is
+// ps's own text and is compared verbatim.
+function sameIdentity(left, right) {
+  return Number(left && left.pid) === Number(right && right.pid)
+    && Number(left && left.pgid) === Number(right && right.pgid)
+    && String(left && left.startedAt) === String(right && right.startedAt);
+}
+
+function groupMembers(rows, pgid) {
+  return (Array.isArray(rows) ? rows : []).filter((row) => Number(row && row.pgid) === Number(pgid));
+}
+
+// Production sleep. `deps.sleep` is the seam the ladder tests use so no test waits 8 s.
+function defaultSleep(ms) {
+  /* deadline-exempt: the ladder's one-shot TERM grace (parkTermGraceMs), awaited inside a single operator stop request and held at most once per (session, task) by the 423 lock; not a standing recovery timer */
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+// true = the signal was delivered; false = the group was already gone (ESRCH, a success of a
+// kind: nothing to escalate to). Anything else is a real failure the operator must see.
+function signalGroup(kill, pgid, signal) {
+  try {
+    kill(-pgid, signal);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+// §6.4's ladder, in order: resolve, re-resolve and require the SAME identity triple, SIGTERM the
+// group, wait `graceMs`, re-read, SIGKILL the group if any row of that pgid is left, re-read,
+// report survivors. `readRows` / `kill` / `graceMs` / `sleep` are seams (production: defaultReadRows
+// / process.kill / lifecycleConfigFromEnv().parkTermGraceMs / defaultSleep).
+async function stopBackgroundTask({
+  readRows,
+  kill = process.kill,
+  agentPid,
+  label,
+  graceMs,
+  sleep = defaultSleep,
+  expect = null,
+} = {}) {
+  const first = resolveBackgroundTarget(await readRows(), { agentPid, label });
+  if (first.error) return first;
+  // The chip's last view, checked before anything is signalled: a caller naming a different
+  // process than the one we just resolved is looking at a stale row.
+  if (expect && !sameIdentity(expect, first.target)) {
+    return { error: 'identity_changed', expected: expect, observed: targetIdentity(first.target) };
+  }
+  const second = resolveBackgroundTarget(await readRows(), { agentPid, label });
+  if (second.error) return second;
+  if (!sameIdentity(second.target, first.target)) {
+    return { error: 'identity_changed', expected: targetIdentity(first.target), observed: targetIdentity(second.target) };
+  }
+  const target = second.target;
+  const grace = Number.isFinite(Number(graceMs)) ? Number(graceMs) : lifecycleConfigFromEnv().parkTermGraceMs;
+  const signalled = [];
+  let delivered;
+  try {
+    delivered = signalGroup(kill, target.pgid, 'SIGTERM');
+  } catch (error) {
+    return { error: 'signal_failed', message: String((error && error.message) || error), target, signalled };
+  }
+  // ESRCH on TERM: the group left between the read and the signal, so there is nothing to
+  // escalate to — no KILL, no survivors.
+  if (!delivered) return { target, signalled, survivors: [], absent: true };
+  signalled.push('SIGTERM');
+  await sleep(grace);
+  let members = groupMembers(await readRows(), target.pgid);
+  if (members.length) {
+    try {
+      if (signalGroup(kill, target.pgid, 'SIGKILL')) signalled.push('SIGKILL');
+    } catch (error) {
+      return { error: 'signal_failed', message: String((error && error.message) || error), target, signalled };
+    }
+    members = groupMembers(await readRows(), target.pgid);
+  }
+  return {
+    target,
+    signalled,
+    // §6.4's survivor row: `comm` is the basename of the first argv token (`/bin/zsh -c …` → zsh).
+    survivors: members.map((row) => ({
+      pid: row.pid,
+      pgid: row.pgid,
+      comm: (String(row.command || '').trim().split(/\s+/)[0] || '').split('/').pop(),
+    })),
+    absent: false,
+  };
+}
+
+async function defaultReadRows() {
+  const binary = process.platform === 'darwin' ? '/bin/ps' : 'ps';
+  // The CALLBACK contract, deliberately not `promisify(execFile)`: a wrapped `child_process`
+  // (the hermetic test runner preloads exactly such a wrapper) keeps the callback but loses
+  // util.promisify.custom, and promisify then resolves with the raw stdout STRING — `{ stdout }`
+  // is undefined and every read comes back empty.
+  const stdout = await new Promise((resolve, reject) => {
+    execFile(binary, PS_STOP_ARGS, { timeout: PS_TIMEOUT_MS, maxBuffer: PS_MAX_BUFFER }, (error, out) => {
+      if (error) { reject(error); return; }
+      resolve(String(out));
+    });
+  });
+  return parseStopRows(stdout);
+}
+
+function decodeParam(value) {
+  const raw = value == null ? '' : String(value);
+  return decodeURIComponent(raw);
+}
+
+// POST /api/sessions/:id/background/:taskId/stop  (§6.4)
+//
+// deps are lib/api/sessions.js's `_deps`: getSession, sendJsonResponse, readJsonRequestBody,
+// recordSessionDiagnostic. `deps.readRows` / `deps.kill` / `deps.graceMs` / `deps.sleep` are TEST
+// SEAMS only — production passes none of them.
+async function handleStopRequest(req, res, params, deps = {}) {
+  const send = (status, body) => deps.sendJsonResponse(res, status, body);
+  let sessionId = '';
+  let taskId = '';
+  try {
+    sessionId = decodeParam(params && params['1']);
+    taskId = decodeParam(params && params['2']);
+  } catch {
+    /* expected: malformed percent-encoding is the client's error, not a stop decision */
+    return send(400, { error: 'invalid_id' });
+  }
+
+  const session = deps.getSession(sessionId);
+  if (!session) return send(404, { error: 'session_not_found' });
+
+  const entry = session._statusLedger && session._statusLedger.background
+    ? session._statusLedger.background.get(taskId)
+    : undefined;
+  if (!entry) return send(404, { error: 'task_not_declared' });
+  // R4's declared set also carries non-shell work (subagents). Only a shell is a process tree.
+  if (entry.type !== 'shell') return send(409, { error: 'not_a_shell' });
+
+  // server.js's `_lifecycleProcessGroupId` derivation, re-stated here because server.js is frozen
+  // and this route must not reach into it.
+  const agentPid = Number((session.ptyProcess && session.ptyProcess.pid) || session.pid);
+  if (!Number.isSafeInteger(agentPid) || agentPid <= 1) return send(409, { error: 'no_agent_process' });
+
+  // The body is optional (`expect` = the chip's last view). An EMPTY body is the normal click;
+  // a non-empty body that does not parse is a request we could not read, so nothing is signalled.
+  let expect = null;
+  if (deps.readJsonRequestBody) {
+    try {
+      const body = await deps.readJsonRequestBody(req, { limitBytes: STOP_BODY_LIMIT_BYTES });
+      expect = body && typeof body === 'object' && body.expect ? body.expect : null;
+    } catch {
+      /* expected: an unreadable body never defaults to a target */
+      return send(400, { error: 'invalid_body' });
+    }
+  }
+
+  const key = `${sessionId}:${taskId}`;
+  if (inFlightStops.has(key)) return send(423, { error: 'stop_in_progress' });
+  inFlightStops.add(key);
+  try {
+    const result = await stopBackgroundTask({
+      readRows: deps.readRows || defaultReadRows,
+      kill: deps.kill,
+      graceMs: deps.graceMs,
+      sleep: deps.sleep,
+      agentPid,
+      label: entry.label,
+      expect,
+    });
+    const target = result.target || null;
+    // One audit row per DECIDED request (refusals included). Its writer's return value is the
+    // response's auditId (null when the writer coalesced the row); a failure to write it must
+    // never change the outcome the operator is about to see.
+    let auditId = null;
+    try {
+      auditId = deps.recordSessionDiagnostic(sessionId, AUDIT_KIND, {
+        taskId,
+        label: String(entry.label || '').slice(0, 160),
+        pid: target ? target.pid : null,
+        pgid: target ? target.pgid : null,
+        startedAt: target ? target.startedAt : null,
+        signalled: result.signalled || [],
+        survivors: result.survivors || [],
+        error: result.error || null,
+        requester: requesterFromRequest(req),
+      }) ?? null;
+    } catch (err) {
+      console.error(`[background-stop] ${AUDIT_KIND} diagnostic failed:`, err && err.message);
+    }
+
+    if (result.error === 'signal_failed') return send(500, { error: 'signal_failed', message: result.message });
+    if (result.error) {
+      return send(409, {
+        error: result.error,
+        ...(result.candidates ? { candidates: result.candidates } : {}),
+        ...(result.expected !== undefined ? { expected: result.expected, observed: result.observed } : {}),
+      });
+    }
+    return send(200, {
+      ok: true,
+      taskId,
+      target: result.target,
+      signalled: result.signalled,
+      survivors: result.survivors,
+      absent: !!result.absent,
+      auditId,
+    });
+  } finally {
+    inFlightStops.delete(key);
+  }
+}
+
+module.exports = {
+  PS_STOP_ARGS,
+  parseStopRows,
+  evalNeedle,
+  resolveBackgroundTarget,
+  stopBackgroundTask,
+  defaultReadRows,
+  handleStopRequest,
+};

package/template/coding-task-manager/lib/best-of-attempts.js

@@ -114,7 +114,7 @@ function freshAgentArgs(agentType, args, context = {}) {
   return result;
 }
 
-function classifyAttemptRuntime({ live, hasOpenTurn, queue } = {}) {
+function classifyAttemptRuntime({ live, hasOpenTurn, everTurn, queue } = {}) {
   const queueStatus = String(queue?.status || '');
   const queueError = String(queue?.error || '');
   if (!live) {
@@ -125,6 +125,9 @@ function classifyAttemptRuntime({ live, hasOpenTurn, queue } = {}) {
   }
   if (queueStatus === 'paused' && queueError) return { status: 'unavailable', error: queueError };
   if (queue && queueStatus !== 'done') return { status: 'running', error: '' };
+  // A prompt-operand launch (no queue) has no open turn until the agent's first turn arrives; an explicit
+  // everTurn === false means that turn has never been observed, so the attempt is still starting, not ready.
+  if (!queue && !hasOpenTurn && everTurn === false) return { status: 'running', error: '' };
   return { status: hasOpenTurn ? 'running' : 'ready', error: '' };
 }
 

package/template/coding-task-manager/lib/best-of-launch-plan.js

@@ -0,0 +1,52 @@
+'use strict';
+// WP-15 (docs/fleet-origin-main-sync-skill-2026-10-31.html §15.4 R-15.2/R-15.3/R-15.4, §15.5 API):
+// the LAUNCH DECISION for a best-of attempt, as a pure function.
+//
+// It is a module of its own because the decision is the part worth testing and server.js cannot be
+// required from a test (it opens the primary DB). `_launchBestOfAttempt` asks this for `{ mode, args }`
+// BEFORE it prepares the worktree, so a refusal leaves no orphan worktree and no session behind.
+//
+//   mode 'positional'  the prompt rides the launch argv, LAST: `[...freshAgentArgs(...), prompt]`.
+//                      No queue is created for the attempt.
+//   mode 'queue'       the agent has no launch operand (walle); the caller keeps the existing
+//                      `_bestOfQueuePrompt` lane.
+//   mode null          no measured way to start this agent working -> refuse
+//                      (`BEST_OF_AGENT_UNSUPPORTED`, R-15.3).
+//
+// R-15.4: an unsafe prompt (empty, leading `-`, or a single bare word) is refused as
+// `BEST_OF_PROMPT_UNSAFE` with the helper's own message, and never repaired with a `--`.
+
+const { normalizeAgentType, launchPromptMode, launchPromptArgv } = require('./agent-capabilities');
+const { freshAgentArgs } = require('./best-of-attempts');
+
+function typedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * @param {{ agentType?: string, sourceArgs?: string[], prompt?: string, approvalHookToken?: string }} input
+ * @returns {{ mode: 'positional'|'queue', args: string[] }}
+ */
+function bestOfLaunchPlan(input = {}) {
+  const { agentType, sourceArgs, prompt, approvalHookToken = '' } = input || {};
+  const type = normalizeAgentType(agentType) || String(agentType == null ? '' : agentType).toLowerCase();
+  const mode = launchPromptMode(agentType);
+  if (mode === null) {
+    throw typedError('BEST_OF_AGENT_UNSUPPORTED', `Best-of attempts cannot start a ${type || 'unknown'} session: it has no measured way to take its prompt at launch`);
+  }
+  const args = freshAgentArgs(type, sourceArgs, { approvalHookToken });
+  if (mode === 'queue') return { mode, args };
+  let promptArgv;
+  try {
+    promptArgv = launchPromptArgv(agentType, prompt);
+  } catch (error) {
+    throw typedError('BEST_OF_PROMPT_UNSAFE', error.message);
+  }
+  return { mode, args: [...args, ...promptArgv] };
+}
+
+module.exports = {
+  bestOfLaunchPlan,
+};

package/template/coding-task-manager/lib/box-keep-awake.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// WP-1 (docs/box-idle-sleep-remote-typing-freezes-2026-11-01.html §5 D-1..D-5, §6, §9 S-4): the
+// BOX holds its own power assertion so the box Mac stops idle-sleeping while a hub is attached
+// (451 sleeps on 2026-11-01, each freezing remote typing for seconds).
+//
+//   D-1  a darwin CTM that is its machine's REAL install (`isPrimaryInstance()`) and has seen at
+//        least one `hub-bridge-hello` holds exactly one `/usr/bin/caffeinate -s -w <ctm pid>`.
+//   D-2  no hello, no assertion: the hub laptop, a never-paired install, Linux and every other
+//        platform spawn nothing. (Dev instances are excluded by `isPrimaryInstance()` itself —
+//        lib/ctm-boot-lifecycle.js is false under NODE_TEST_CONTEXT / DEV_CTM_PORT, so a test or
+//        dev run can NEVER spawn a real caffeinate.)
+//   D-3  latched for the process lifetime: a hub disconnect does NOT release it (PolyPilot #512 —
+//        a sleeping box cannot accept the hub's re-dial), and there is no timer and no polling.
+//        `-w <pid>` releases it when CTM exits; if the child dies early, the next hello respawns.
+//   D-4  `-s` only (PreventSystemSleep, valid on AC): on battery the Mac idle-sleeps as before.
+//   D-5  kill switch `CTM_BOX_KEEP_AWAKE` — the string '0' disables; default ON in source.
+//
+// Best-effort by construction: nothing here throws into the caller, and every failure is REPORTED
+// as one `[box-keep-awake] …` line (lib/hub-bridge-box.js wraps the call in a try/catch too).
+
+const { spawn: _spawn } = require('node:child_process');
+const { isPrimaryInstance } = require('./ctm-boot-lifecycle');
+
+const CAFFEINATE_PATH = '/usr/bin/caffeinate';
+
+function _defaultDeps() {
+  return {
+    platform: process.platform,
+    env: process.env,
+    pid: process.pid,
+    isPrimaryInstance: () => isPrimaryInstance({ env: process.env }),
+    spawn: _spawn,
+    log: (line) => console.log(line),
+  };
+}
+
+let _deps = _defaultDeps();
+let _child = null; // the live caffeinate ChildProcess, or null
+let _spawnCount = 0; // for status() / tests
+
+/** Tests only. Replaces deps (merged over the defaults); resets state. */
+function configure(deps = {}) {
+  _deps = { ..._defaultDeps(), ...(deps || {}) };
+  _child = null;
+  _spawnCount = 0;
+}
+
+/**
+ * D-1..D-5. Idempotent; called on every hub-bridge-hello. Never throws.
+ *
+ * @returns {{ held: boolean, reason: 'held'|'spawned'|'disabled'|'not-darwin'|'not-primary'|'spawn-failed' }}
+ */
+function noteHubLinked() {
+  if (String(_deps.env.CTM_BOX_KEEP_AWAKE == null ? '' : _deps.env.CTM_BOX_KEEP_AWAKE) === '0') {
+    return { held: false, reason: 'disabled' };
+  }
+  if (_deps.platform !== 'darwin') return { held: false, reason: 'not-darwin' };
+  if (!_deps.isPrimaryInstance()) return { held: false, reason: 'not-primary' };
+  // D-3: a live child is the whole latch — repeated hellos never spawn a second one.
+  if (_child && _child.exitCode === null && !_child.killed) return { held: true, reason: 'held' };
+  try {
+    const child = _deps.spawn(CAFFEINATE_PATH, ['-s', '-w', String(_deps.pid)], { stdio: 'ignore', detached: false });
+    child.on('exit', (code, signal) => {
+      if (_child === child) _child = null; // D-3: the next noteHubLinked() respawns
+      _deps.log(`[box-keep-awake] caffeinate exited code=${code} signal=${signal || ''}`);
+    });
+    child.on('error', (err) => {
+      if (_child === child) _child = null;
+      _deps.log(`[box-keep-awake] caffeinate error: ${err && err.message}`); // REPORT disposition
+    });
+    child.unref(); // never keeps CTM's event loop alive
+    _child = child;
+    _spawnCount += 1;
+    _deps.log(`[box-keep-awake] holding PreventSystemSleep (AC only) via caffeinate pid=${child.pid} for ctm pid=${_deps.pid}`);
+    return { held: true, reason: 'spawned' };
+  } catch (err) {
+    _deps.log(`[box-keep-awake] spawn failed: ${err && err.message}`); // REPORT disposition
+    return { held: false, reason: 'spawn-failed' };
+  }
+}
+
+/** @returns {{ held: boolean, pid: number|null, spawnCount: number }} */
+function status() {
+  const held = !!(_child && _child.exitCode === null && !_child.killed);
+  return { held, pid: held ? _child.pid : null, spawnCount: _spawnCount };
+}
+
+module.exports = { noteHubLinked, status, configure, CAFFEINATE_PATH };

package/template/coding-task-manager/lib/broadcast-reason-stats.js

@@ -0,0 +1,152 @@
+'use strict';
+
+// WP-0 M-2 (docs/hub-local-cpu-memory-burn-2026-10-31.html §3.2 "who calls ~3 per second",
+// §7 M-2): per-reason counters for the session-list broadcast. MEASUREMENT ONLY — this module
+// holds counters and nothing else. It never decides whether to broadcast, never touches the
+// serializer, and adds no cap/timeout/retry/early-exit.
+//
+// Why: after a hub boot the whole session list was serialized 1,951× (2.65 GB) in 666 s
+// (~2.9/s) and no caller recorded why (`broadcastSessionList` took no reason). Q-3 in the design
+// doc is exactly "which callers drive the rate", and it cannot be answered by code reading
+// because ~74 call sites reach the function through `deps.broadcastSessionList(...)` too.
+//
+// Contract (asserted by tests/broadcast-reason-stats.test.js, per reason):
+//   calls       === suppressed + coalesced + flushes
+//   flushes     === serialized + elided
+// where
+//   calls       every invocation of `broadcastSessionList(immediate, { reason })`.
+//   suppressed  the invocation produced no output: restore in progress, or a deferred-restore
+//               depth > 0 (an intermediate broadcast folded into the post-restore flush), or an
+//               internal flush that found restore in progress / no connected client.
+//   coalesced   the invocation rode an already-armed flush instead of producing its own — a
+//               debounced call while the 200 ms timer was armed (or whose timer an immediate
+//               flush pre-empted), or a request folded into the in-flight sliced build.
+//   flushes     a flush reached the send tail (`_doBroadcastSessionList` → `_finishBroadcast`),
+//               attributed to the reason that armed it (or `rerun` for the sliced build's
+//               self-re-run).
+//   serialized  that flush actually handed the payload to the serializer.
+//   elided      that flush was dropped by the serializer's no-change elision.
+//
+// Unknown/missing reason strings count under `unspecified`; the reason-key set is bounded
+// (MAX_REASON_KEYS) and anything past the bound folds into `_other`, so the map is fixed-size
+// and the per-event cost stays O(1).
+//
+// Gated by CTM_PERF_ATTRIBUTION (read through lib/env-flags.js, like every other WP-0 counter):
+// '0' (also 'false'/'no'/'off') records nothing and exposes `{ byReason: {} }`.
+
+const { boolFlag } = require('./env-flags');
+
+const MAX_REASON_KEYS = 128;
+const OTHER_REASON = '_other';
+const UNSPECIFIED_REASON = 'unspecified';
+// `rerun` is the reason the sliced build's own self-re-run is counted under (server.js
+// `_doBroadcastSessionList`'s `.finally`); it is a call AND a flush so the invariant holds.
+const RERUN_REASON = 'rerun';
+
+
+function _newCounts() {
+  return { calls: 0, suppressed: 0, coalesced: 0, flushes: 0, serialized: 0, elided: 0 };
+}
+
+function normalizeReason(reason) {
+  return typeof reason === 'string' && reason.length > 0 ? reason : UNSPECIFIED_REASON;
+}
+
+function createBroadcastReasonStats(options = {}) {
+  const enabled = typeof options.enabled === 'function'
+    ? options.enabled
+    : () => boolFlag('CTM_PERF_ATTRIBUTION', true);
+  const maxKeys = Number.isInteger(options.maxKeys) && options.maxKeys > 1
+    ? options.maxKeys
+    : MAX_REASON_KEYS;
+  // One slot is reserved for `_other` so the total key count can never exceed maxKeys.
+  const namedKeyCap = maxKeys - 1;
+  const byReason = new Map();
+
+  function slot(reason) {
+    const key = normalizeReason(reason);
+    const existing = byReason.get(key);
+    if (existing) return existing;
+    if (byReason.size >= namedKeyCap) {
+      const other = byReason.get(OTHER_REASON);
+      if (other) return other;
+      const folded = _newCounts();
+      byReason.set(OTHER_REASON, folded);
+      return folded;
+    }
+    const fresh = _newCounts();
+    byReason.set(key, fresh);
+    return fresh;
+  }
+
+  function isOn() {
+    return enabled() !== false;
+  }
+
+  function noteCall(reason) {
+    if (!isOn()) return;
+    slot(reason).calls += 1;
+  }
+
+  function noteSuppressed(reason) {
+    if (!isOn()) return;
+    slot(reason).suppressed += 1;
+  }
+
+  function noteCoalesced(reason) {
+    if (!isOn()) return;
+    slot(reason).coalesced += 1;
+  }
+
+  // A flush is one trip through the send tail. `elided` says which way its no-change decision
+  // went; every flush is exactly one of serialized/elided, which is what makes
+  // `flushes === serialized + elided` true by construction.
+  function noteFlush(reason, elided) {
+    if (!isOn()) return;
+    const entry = slot(reason);
+    entry.flushes += 1;
+    if (elided) entry.elided += 1;
+    else entry.serialized += 1;
+  }
+
+  function snapshot() {
+    if (!isOn()) return { byReason: {} };
+    const byReasonOut = {};
+    for (const [key, counts] of byReason) {
+      byReasonOut[key] = {
+        calls: counts.calls,
+        suppressed: counts.suppressed,
+        coalesced: counts.coalesced,
+        flushes: counts.flushes,
+        serialized: counts.serialized,
+        elided: counts.elided,
+      };
+    }
+    return { byReason: byReasonOut };
+  }
+
+  function reset() {
+    byReason.clear();
+  }
+
+  return { noteCall, noteSuppressed, noteCoalesced, noteFlush, snapshot, reset, normalizeReason, isOn };
+}
+
+// Process-wide instance used by server.js. Tests construct their own via the factory so they
+// never depend on import order.
+const _default = createBroadcastReasonStats();
+
+module.exports = {
+  createBroadcastReasonStats,
+  normalizeReason,
+  getBroadcastReasonStats: () => _default.snapshot(),
+  resetBroadcastReasonStats: () => _default.reset(),
+  noteCall: (reason) => _default.noteCall(reason),
+  noteSuppressed: (reason) => _default.noteSuppressed(reason),
+  noteCoalesced: (reason) => _default.noteCoalesced(reason),
+  noteFlush: (reason, elided) => _default.noteFlush(reason, elided),
+  MAX_REASON_KEYS,
+  OTHER_REASON,
+  UNSPECIFIED_REASON,
+  RERUN_REASON,
+};