@rubytech/create-maxy-code 0.1.476 → 0.1.478

package/payload/platform/scripts/cpu-triage-run.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# cpu-triage-run.sh — detached run harness for cpu-triage.sh.
+#
+# WHY THIS EXISTS
+#
+# cpu-triage.sh samples for at least 120 s (300 s by default) because anything
+# shorter than the reconcile cycle produces contradictory readings — see that
+# script's header. Every admin MCP tool completes inside 12 s. So the run has to
+# be detached from the call that starts it, and the caller needs a readiness
+# signal it can poll.
+#
+# THE ORDERING IS THE CONTRACT
+#
+# stdout is redirected to the result file, so that file exists from the FIRST
+# BYTE of output and is half-written for the whole sampling window. It is
+# therefore NOT a readiness signal. The `.status` marker is, and it is written
+# strictly after the measurement process has exited and its output is closed.
+# The completion log line is written after that again — a post-condition, never
+# an intent. A reader that keys on the `.json` existing reports a half-written
+# run as complete, which is the single failure this harness exists to prevent.
+#
+# EXIT CODES
+#   The measurement script's own exit code is recorded in the status marker and
+#   is what callers interpret (0 clean, 1 sustained hot core, 2 precondition
+#   failure). This harness exits 2 only on its own usage errors.
+
+set -uo pipefail
+
+RUN_ID=""
+OUT_DIR=""
+LOG_FILE=""
+SCRIPT=""
+
+usage() {
+  cat >&2 <<USAGE
+usage: cpu-triage-run.sh --run-id ID --out-dir DIR --log FILE [--script PATH]
+                        [-- <cpu-triage.sh args>...]
+
+  --run-id   identifier for this run; names the output files
+  --out-dir  directory receiving cpu-triage-<ID>.json and cpu-triage-<ID>.status
+  --log      brand log to append the op=complete line to
+  --script   measurement script (default: cpu-triage.sh beside this file)
+USAGE
+  exit 2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --run-id)  RUN_ID="${2:-}"; shift 2 ;;
+    --out-dir) OUT_DIR="${2:-}"; shift 2 ;;
+    --log)     LOG_FILE="${2:-}"; shift 2 ;;
+    --script)  SCRIPT="${2:-}"; shift 2 ;;
+    --)        shift; break ;;
+    -h|--help) usage ;;
+    *) echo "cpu-triage-run: unknown argument '$1'" >&2; usage ;;
+  esac
+done
+
+[ -n "$RUN_ID" ] || usage
+[ -n "$OUT_DIR" ] || usage
+[ -n "$LOG_FILE" ] || usage
+
+case "$RUN_ID" in
+  *[!A-Za-z0-9T_-]*) echo "cpu-triage-run: run-id must be [A-Za-z0-9T_-]" >&2; exit 2 ;;
+esac
+
+HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+[ -n "$SCRIPT" ] || SCRIPT="$HERE/cpu-triage.sh"
+
+mkdir -p "$OUT_DIR" || exit 2
+
+RESULT="$OUT_DIR/cpu-triage-$RUN_ID.json"
+STATUS="$OUT_DIR/cpu-triage-$RUN_ID.status"
+
+# Publish a terminal state. EVERY exit path past this point goes through here.
+#
+# The caller has already written its meta file and logged op=start by the time
+# this harness runs, so an exit that publishes nothing leaves the run readable
+# as `running` forever — the no-event blind spot this whole design exists to
+# close. The case that made this concrete: the measurement script shipping
+# without its executable bit. The caller checks the script EXISTS, which passes,
+# and the run then dies here in silence.
+publish() {
+  local code="$1" hot
+  { echo "exit=$code"; [ -n "${2:-}" ] && printf '%s\n' "$2"; } > "$STATUS"
+
+  # Report what is on disk. An absent or unparseable count is `unknown`, never
+  # a fabricated 0 — reporting a clean count for a run that produced no report
+  # is exactly the false-clean this tool exists to prevent.
+  hot=$(grep -o '"sustainedHotCores"[[:space:]]*:[[:space:]]*[0-9]\{1,\}' "$RESULT" 2>/dev/null \
+          | head -1 | grep -o '[0-9]\{1,\}$')
+  [ -n "$hot" ] || hot="unknown"
+
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null
+  printf '%s [cpu-triage] op=complete runId=%s exit=%s sustainedHotCores=%s\n' \
+    "$(date -Is 2>/dev/null || date)" "$RUN_ID" "$code" "$hot" >> "$LOG_FILE"
+}
+
+if [ ! -x "$SCRIPT" ]; then
+  MSG="cpu-triage-run: measurement script not executable: $SCRIPT"
+  echo "$MSG" >&2
+  publish 2 "$MSG"
+  exit 0
+fi
+
+ERR=$(mktemp "${TMPDIR:-/tmp}/cpu-triage-err.XXXXXX") || exit 2
+trap 'rm -f "$ERR"' EXIT INT TERM
+
+# The measurement. stdout streams into the result file for the whole window.
+"$SCRIPT" --json "$@" > "$RESULT" 2> "$ERR"
+CODE=$?
+
+# The result file is closed and the exit code is known. Only now does a
+# readiness signal exist to publish.
+publish "$CODE" "$(cat "$ERR")"
+
+exit 0

package/payload/platform/scripts/cpu-triage.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# cpu-triage.sh — sustained CPU triage for a Maxy Code device.
+#
+# WHY THIS EXISTS, AND WHY IT SAMPLES FOR MINUTES RATHER THAN SECONDS
+#
+# The booking reconcile loop runs on a 120 s cycle and a tick costs roughly
+# 800 ms of network wait plus a garbage-collection burst. Measured on laptop
+# 192.168.88.10 (2026-07-20), the SAME server process over the SAME method read
+# 0.2%, 0.2%, 0.2% in three consecutive 25 s windows and 10.8% in a 20 s window.
+# Every one of those readings was correct. Any sample shorter than the period
+# either lands on a tick or misses it, so spot checks on this platform produce
+# contradictory answers indefinitely. This tool therefore samples across at
+# least one full cycle and reports a DISTRIBUTION (mean, peak, and what share of
+# the window sat above threshold), never a single number.
+#
+# THREE INSTRUMENTS THIS DELIBERATELY DOES NOT USE, EACH HAVING PRODUCED A FALSE
+# CONCLUSION IN THE 2026-07-20 INVESTIGATION:
+#   * `ps %cpu` / `top` %CPU  — LIFETIME averages. A 40-minute-old process read
+#     8.5% against an 8-day-old peer at 0.1%; both were actually 0.2% live. This
+#     nearly shipped as an "85x regression".
+#   * `iostat -c` first line  — a SINCE-BOOT average. Read as live it reported a
+#     machine "42% busy" that was 87% idle at that moment.
+#   * `ns_last_pid` deltas    — counts THREAD creation as well as forks, and was
+#     compared against a single 10 s sample used as a "baseline". Produced a
+#     false 5.6x churn regression. Fork rate here comes from /proc/stat's
+#     `processes` counter, which counts forks only.
+# Everything below is a DELTA over a stated window. No lifetime averages.
+#
+# Aggregate CPU is also avoided as a headline: two hot cores out of twenty
+# average down to ~3% and vanish, which is exactly how a real, operator-visible
+# condition was dismissed as "nothing changed". Per-core is the primary view.
+#
+# Unprivileged by design: the admin assistant runs without sudo, so this uses
+# only /proc and the user's own cgroup tree. `perf` and `bpftrace` need root and
+# are named in the escalation hint rather than invoked.
+#
+# EXIT CODES (gates, for deterministic callers)
+#   0  no core sustained above threshold — nothing to escalate
+#   1  one or more cores sustained above threshold — findings in the report
+#   2  usage error or unmet precondition (nothing measured)
+
+set -uo pipefail
+
+WINDOW=300          # total sampling window, seconds (>= 2 reconcile cycles)
+INTERVAL=10         # sample cadence, seconds
+THRESHOLD=15        # per-core busy % that counts as "hot"
+SUSTAIN=50          # % of samples above THRESHOLD to call a core "sustained"
+TOPN=12             # processes to report
+JSON=0
+CONTROL=""          # optional peer brand known NOT to have the change
+
+usage() {
+  cat >&2 <<USAGE
+usage: cpu-triage.sh [--window S] [--interval S] [--threshold PCT]
+                     [--sustain PCT] [--top N] [--control BRAND] [--json]
+
+  --window     total sampling window in seconds (default 300, min 120)
+  --interval   sample cadence in seconds (default 10)
+  --threshold  per-core busy %% treated as hot (default 15)
+  --sustain    %% of samples above threshold to call it sustained (default 50)
+  --top        processes to report (default 12)
+  --control    a brand on the PREVIOUS build, for like-for-like comparison.
+               The single most valuable input: on 2026-07-20 an un-upgraded
+               peer collapsed a suspected regression into a measurement artifact.
+  --json       emit machine-readable JSON instead of the text report
+USAGE
+  exit 2
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --window)    WINDOW="${2:-}"; shift 2 ;;
+    --interval)  INTERVAL="${2:-}"; shift 2 ;;
+    --threshold) THRESHOLD="${2:-}"; shift 2 ;;
+    --sustain)   SUSTAIN="${2:-}"; shift 2 ;;
+    --top)       TOPN="${2:-}"; shift 2 ;;
+    --control)   CONTROL="${2:-}"; shift 2 ;;
+    --json)      JSON=1; shift ;;
+    -h|--help)   usage ;;
+    *) echo "cpu-triage: unknown argument '$1'" >&2; usage ;;
+  esac
+done
+
+case "$WINDOW$INTERVAL$THRESHOLD$SUSTAIN$TOPN" in *[!0-9]*) usage ;; esac
+[ "$INTERVAL" -ge 1 ] || usage
+if [ "$WINDOW" -lt 120 ]; then
+  echo "cpu-triage: refusing a window under 120s — shorter than the reconcile cycle," >&2
+  echo "            which is what makes spot readings contradict each other." >&2
+  exit 2
+fi
+[ -r /proc/stat ] || { echo "cpu-triage: /proc/stat unreadable — Linux only" >&2; exit 2; }
+
+SAMPLES=$(( WINDOW / INTERVAL ))
+[ "$SAMPLES" -ge 2 ] || { echo "cpu-triage: window/interval must yield >= 2 samples" >&2; exit 2; }
+
+CLK=$(getconf CLK_TCK 2>/dev/null || echo 100)
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/cpu-triage.XXXXXX") || exit 2
+trap 'rm -rf "$TMP"' EXIT INT TERM
+
+CG_BASE="/sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/app.slice"
+
+# ---------------------------------------------------------------------------
+# Sampling. One loop, one cadence, every measure derived from the same instants
+# so per-core, per-process and per-service figures are directly comparable.
+# ---------------------------------------------------------------------------
+snapshot() {
+  local idx="$1"
+  # NOTE: every redirect below MUST be `>>`. Each sample is a fresh awk process,
+  # and awk's `>` truncates the file once per invocation — so `>` silently keeps
+  # only the LAST sample, leaving nothing to diff. That bug shipped into the
+  # first test run and produced an empty per-core report with mean 0%.
+  awk -v idx="$idx" -v out="$TMP" '
+    FILENAME == "/proc/stat" {
+      if ($1 ~ /^cpu[0-9]+$/) {
+        total = 0
+        for (i = 2; i <= NF; i++) total += $i
+        # busy excludes idle (field 5) and iowait (field 6)
+        print idx, $1, total - $5 - $6, total >> (out "/cores.raw")
+      }
+      if ($1 == "processes") print idx, $2 >> (out "/forks.raw")
+      next
+    }
+    # /proc/<pid>/stat — comm may contain spaces and parens; the greedy .*\)
+    # anchors on the LAST close paren, which is the only safe split.
+    {
+      if (match($0, /^[0-9]+ \(.*\) /)) {
+        pid  = $1
+        rest = substr($0, RSTART + RLENGTH)
+        n    = split(rest, f, " ")
+        if (n >= 13) print idx, pid, f[12] + f[13] >> (out "/procs.raw")
+      }
+    }
+  ' /proc/stat /proc/[0-9]*/stat 2>/dev/null
+
+  # Per-service cgroup CPU. Counts CHILD processes, which per-process sampling
+  # attributes nowhere — the original wrangler churn lived entirely in children.
+  #
+  # Read every cpu.stat in ONE awk rather than a shell loop forking per service.
+  # This tool reports fork rate, so its own churn is measurement noise it would
+  # otherwise attribute to the box: the loop form cost ~16 forks per sample.
+  if [ -d "$CG_BASE" ]; then
+    awk -v idx="$idx" '
+      /^usage_usec/ {
+        n = split(FILENAME, p, "/")
+        svc = p[n-1]; sub(/\.service$/, "", svc)
+        print idx, svc, $2
+      }
+    ' "$CG_BASE"/*.service/cpu.stat >> "$TMP/cgroup.raw" 2>/dev/null
+  fi
+}
+
+HOST=$(hostname 2>/dev/null || echo unknown)
+NCPU=$(awk '/^cpu[0-9]+/{n++} END{print n+0}' /proc/stat)
+STARTED=$(date -Is 2>/dev/null || date)
+
+if [ "$JSON" -eq 0 ]; then
+  echo "cpu-triage on $HOST — sampling ${WINDOW}s at ${INTERVAL}s cadence (${SAMPLES} samples, ${NCPU} cores)"
+  echo "this spans at least one 120s reconcile cycle; spot readings on this platform are not reliable"
+  echo
+fi
+
+i=0
+while [ "$i" -lt "$SAMPLES" ]; do
+  snapshot "$i"
+  i=$(( i + 1 ))
+  [ "$i" -lt "$SAMPLES" ] && sleep "$INTERVAL"
+done
+ENDED=$(date -Is 2>/dev/null || date)
+
+[ -s "$TMP/cores.raw" ] || { echo "cpu-triage: no samples captured" >&2; exit 2; }
+
+# ---------------------------------------------------------------------------
+# Analysis — distribution per core, not a single number.
+# ---------------------------------------------------------------------------
+awk -v thr="$THRESHOLD" '
+  { key = $2
+    if (prev_total[key] != "") {
+      dt = $4 - prev_total[key]
+      db = $3 - prev_busy[key]
+      if (dt > 0) {
+        pct = db / dt * 100
+        sum[key] += pct; n[key]++
+        if (pct > peak[key]) peak[key] = pct
+        if (pct > thr) hot[key]++
+      }
+    }
+    prev_total[key] = $4; prev_busy[key] = $3
+  }
+  END {
+    for (k in sum)
+      printf "%s %.2f %.2f %.1f %d\n", k, sum[k]/n[k], peak[k], (hot[k]+0)/n[k]*100, n[k]
+  }
+' "$TMP/cores.raw" | sort -k2 -rn > "$TMP/cores.out"
+
+awk -v clk="$CLK" -v iv="$INTERVAL" '
+  { key = $2
+    if (prev[key] != "") {
+      d = $3 - prev[key]
+      if (d >= 0) {
+        pct = d / (clk * iv) * 100
+        sum[key] += pct; n[key]++
+        if (pct > peak[key]) peak[key] = pct
+      }
+    }
+    prev[key] = $3
+  }
+  END { for (k in sum) if (sum[k]/n[k] >= 0.05) printf "%s %.2f %.2f\n", k, sum[k]/n[k], peak[k] }
+' "$TMP/procs.raw" | sort -k2 -rn > "$TMP/procs.out"
+
+if [ -s "${TMP}/cgroup.raw" ]; then
+  awk -v iv="$INTERVAL" '
+    { key = $2
+      if (prev[key] != "") {
+        d = $3 - prev[key]
+        if (d >= 0) { pct = d / (iv * 1000000) * 100; sum[key] += pct; n[key]++
+                      if (pct > peak[key]) peak[key] = pct }
+      }
+      prev[key] = $3
+    }
+    END { for (k in sum) printf "%s %.2f %.2f\n", k, sum[k]/n[k], peak[k] }
+  ' "$TMP/cgroup.raw" | sort -k2 -rn > "$TMP/cgroup.out"
+fi
+
+FORKS_MIN=$(awk -v iv="$INTERVAL" 'NR==1{f=$2;i=$1} END{ if (NR>1) printf "%.0f", ($2-f)/((($1-i)*iv))*60 }' "$TMP/forks.raw" 2>/dev/null)
+[ -n "$FORKS_MIN" ] || FORKS_MIN=0
+
+HOT_COUNT=$(awk -v s="$SUSTAIN" '$4 >= s {n++} END{print n+0}' "$TMP/cores.out")
+MEAN_CORE=$(awk '{s+=$2; n++} END{ if(n) printf "%.2f", s/n; else print "0" }' "$TMP/cores.out")
+
+resolve() { tr '\0' ' ' < "/proc/$1/cmdline" 2>/dev/null | cut -c1-78 || true; }
+
+# Control lookup, computed once for BOTH report shapes. It previously lived
+# inside the text branch only, which made --control silently inert under
+# --json — dropping the single most valuable input to this measurement from
+# the machine-readable output the agent reads.
+CONTROL_MEAN=""
+if [ -n "$CONTROL" ] && [ -s "${TMP}/cgroup.out" ]; then
+  CONTROL_MEAN=$(awk -v c="$CONTROL" '$1 == c {print $2}' "$TMP/cgroup.out")
+fi
+
+# ---------------------------------------------------------------------------
+# Report
+# ---------------------------------------------------------------------------
+if [ "$JSON" -eq 1 ]; then
+  printf '{\n  "host": %s,\n  "started": %s,\n  "ended": %s,\n' "\"$HOST\"" "\"$STARTED\"" "\"$ENDED\""
+  printf '  "windowSec": %s, "intervalSec": %s, "samples": %s, "cores": %s,\n' "$WINDOW" "$INTERVAL" "$SAMPLES" "$NCPU"
+  printf '  "thresholdPct": %s, "sustainPct": %s,\n' "$THRESHOLD" "$SUSTAIN"
+  printf '  "meanPerCorePct": %s, "sustainedHotCores": %s, "forksPerMin": %s,\n' "$MEAN_CORE" "$HOT_COUNT" "$FORKS_MIN"
+  printf '  "perCore": ['
+  awk '{ printf "%s{\"cpu\":\"%s\",\"meanPct\":%s,\"peakPct\":%s,\"aboveThresholdPct\":%s}", (NR>1?",":""), $1,$2,$3,$4 }' "$TMP/cores.out"
+  printf '],\n  "topProcesses": ['
+  head -n "$TOPN" "$TMP/procs.out" | while read -r pid mean peak; do
+    cl=$(resolve "$pid" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    printf '{"pid":%s,"meanPct":%s,"peakPct":%s,"cmd":"%s"},' "$pid" "$mean" "$peak" "$cl"
+  done | sed 's/,$//'
+  printf '],\n  "perService": ['
+  if [ -s "${TMP}/cgroup.out" ]; then
+    awk '{ printf "%s{\"service\":\"%s\",\"meanPct\":%s,\"peakPct\":%s}", (NR>1?",":""), $1,$2,$3 }' "$TMP/cgroup.out"
+  fi
+  printf '],\n  "control": '
+  if [ -z "$CONTROL" ]; then
+    printf 'null'
+  else
+    cesc=$(printf '%s' "$CONTROL" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    if [ -n "$CONTROL_MEAN" ]; then
+      printf '{"brand":"%s","meanPct":%s,"found":true}' "$cesc" "$CONTROL_MEAN"
+    else
+      printf '{"brand":"%s","found":false}' "$cesc"
+    fi
+  fi
+  printf '\n}\n'
+else
+  echo "PER-CORE over the window (mean / peak / share of window above ${THRESHOLD}%)"
+  echo "  a core is 'sustained' when it exceeds threshold in >= ${SUSTAIN}% of samples"
+  awk -v thr="$THRESHOLD" -v s="$SUSTAIN" '
+    $2 >= 1 || $4 > 0 {
+      flag = ($4 >= s) ? "  <== SUSTAINED" : ""
+      printf "  %-7s mean=%6.2f%%  peak=%6.2f%%  above=%5.1f%% of window%s\n", $1, $2, $3, $4, flag
+    }' "$TMP/cores.out"
+  echo "  ---"
+  printf "  mean per-core %s%%   sustained hot cores: %s of %s   forks %s/min\n\n" "$MEAN_CORE" "$HOT_COUNT" "$NCPU" "$FORKS_MIN"
+
+  echo "TOP PROCESSES by measured delta (100% = one full core; NOT a lifetime average)"
+  head -n "$TOPN" "$TMP/procs.out" | while read -r pid mean peak; do
+    printf "  %6.2f%% mean  %6.2f%% peak  pid=%-8s %s\n" "$mean" "$peak" "$pid" "$(resolve "$pid")"
+  done
+  echo
+
+  if [ -s "${TMP}/cgroup.out" ]; then
+    echo "PER-SERVICE cgroup CPU (child processes included — the platform's true footprint)"
+    tot=$(awk '{s+=$2} END{printf "%.2f", s}' "$TMP/cgroup.out")
+    awk '$2 >= 0.01 { printf "  %-32s mean=%6.2f%%  peak=%6.2f%%\n", $1, $2, $3 }' "$TMP/cgroup.out"
+    printf "  ---\n  all services %s%% of one core (%.2f%% of the %s-core box)\n\n" \
+      "$tot" "$(awk -v t="$tot" -v c="$NCPU" 'BEGIN{print t/c}')" "$NCPU"
+    if [ -n "$CONTROL" ]; then
+      if [ -n "$CONTROL_MEAN" ]; then
+        echo "CONTROL: '$CONTROL' is on the previous build and measured ${CONTROL_MEAN}% of one core."
+        echo "  Compare peers against this, not against their own past readings. A peer that"
+        echo "  did not get the change is worth more than any before/after inference."
+        echo
+      else
+        echo "CONTROL: '$CONTROL' not found among running services — comparison skipped."; echo
+      fi
+    fi
+  fi
+
+  if command -v sar >/dev/null 2>&1; then
+    y=$(date -d yesterday +%d 2>/dev/null)
+    if [ -n "$y" ] && [ -r "/var/log/sysstat/sa$y" ]; then
+      echo "HISTORY — same instrument, yesterday, for like-for-like regression checking"
+      sar -P ALL -f "/var/log/sysstat/sa$y" 2>/dev/null | awk -v thr="$THRESHOLD" '
+        /Average/ && $2 ~ /^[0-9]+$/ { b = 100 - $8; s += b; n++; if (b > thr) h++ }
+        END { if (n) printf "  yesterday: mean per-core %.2f%%   cores above %s%%: %d/%d\n", s/n, thr, h+0, n }'
+      echo
+    fi
+  fi
+
+  if [ "$HOT_COUNT" -gt 0 ]; then
+    echo "VERDICT: ${HOT_COUNT} core(s) sustained above ${THRESHOLD}%. Findings above."
+    echo "  Before calling it a regression, check the desktop stack in the process list."
+    echo "  On 2026-07-20 gnome-shell + gnome-system-monitor + Xorg accounted for ~41% of"
+    echo "  a core, roughly three times the entire four-brand platform, and the System"
+    echo "  Monitor window doing the observing was itself a third of that."
+    echo "  To attribute short-lived process churn, escalate (needs root):"
+    echo "    bpftrace -e 'tracepoint:syscalls:sys_enter_execve { @[comm, str(args->filename)] = count(); }'"
+  else
+    echo "VERDICT: no core sustained above ${THRESHOLD}%."
+  fi
+fi
+
+[ "$HOT_COUNT" -gt 0 ] && exit 1
+exit 0

package/payload/platform/services/claude-session-manager/dist/activity-range.d.ts

@@ -0,0 +1,40 @@
+import type { MeteringDay } from './session-metering.js';
+import { type PricingConfig } from './pricing.js';
+export interface DayRange {
+    from: string;
+    to: string;
+}
+/** The outcome of reading `from`/`to` off a request.
+ *
+ *  `fullRangeFallback` separates the two ways `range` comes back null, which
+ *  are NOT the same event:
+ *
+ *    - false — no range was asked for (the All time preset). Legitimate, and
+ *              the figures are honestly labelled all-time.
+ *    - true  — a range WAS asked for and could not be honoured. This is the
+ *              most misleading state available, because the page then shows
+ *              all-time figures under a bounded heading. */
+export interface ParsedRange {
+    range: DayRange | null;
+    fullRangeFallback: boolean;
+}
+export declare function parseDayRange(from: unknown, to: unknown): ParsedRange;
+export interface RangeSlice {
+    activeMs: number;
+    tokens: number;
+    costGBP: {
+        opus: number;
+        sonnet: number;
+    };
+    /** Days falling inside the range. 0 is a real answer — a quiet month — and is
+     *  what the caller reports as an empty slice. */
+    matchedDays: number;
+}
+/** Sum a session's day rows over an inclusive range. A null range means every
+ *  day.
+ *
+ *  Cost is re-derived from the SUMMED tokens rather than summed from the
+ *  per-day costs, matching how computeMetering derives its own totals — adding
+ *  already-rounded figures compounds their rounding. */
+export declare function sliceMeteringDays(days: MeteringDay[], range: DayRange | null, cfg?: PricingConfig): RangeSlice;
+//# sourceMappingURL=activity-range.d.ts.map

package/payload/platform/services/claude-session-manager/dist/activity-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-range.d.ts","sourceRoot":"","sources":["../src/activity-range.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AAErB,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;;;;;4DAS4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;IACtB,iBAAiB,EAAE,OAAO,CAAA;CAC3B;AAgBD,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,WAAW,CAQrE;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC;qDACiD;IACjD,WAAW,EAAE,MAAM,CAAA;CACpB;AAMD;;;;;wDAKwD;AACxD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EAAE,EACnB,KAAK,EAAE,QAAQ,GAAG,IAAI,EACtB,GAAG,GAAE,aAAsC,GAC1C,UAAU,CAqBZ"}

package/payload/platform/services/claude-session-manager/dist/activity-range.js

@@ -0,0 +1,68 @@
+// Task 1827 — the date range applied to /activity's metering figures.
+//
+// Pure by construction, and separate from activity-rows.ts for the reason that
+// module already states about itself: the arithmetic has to be provable without
+// a Pi, a transcript or a live session.
+//
+// The range is a pair of INCLUSIVE UTC day keys in the same `YYYY-MM-DD` shape
+// as `MeteringDay.date` (see `dayKey`, session-metering.ts). Slicing is
+// therefore a string comparison, and the client sends day keys rather than
+// instants — so the two ends cannot disagree about where a UTC day begins.
+import { defaultPricingConfig, opusCostGBP, sonnetCostGBP, } from './pricing.js';
+/** True for a real calendar day in `YYYY-MM-DD`.
+ *
+ *  Rejects shapes `Date.parse` would silently accept (`2026-6-1`) and days that
+ *  do not exist (`2026-02-30`). Both would otherwise slice against a key no
+ *  MeteringDay can ever carry, producing a silent empty range — the failure
+ *  this whole module is shaped to make impossible. */
+function isDayKey(v) {
+    if (typeof v !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v))
+        return false;
+    const t = Date.parse(`${v}T00:00:00.000Z`);
+    if (!Number.isFinite(t))
+        return false;
+    // Round-trips only if the day exists: Date normalises 2026-02-30 to 2026-03-02.
+    return new Date(t).toISOString().slice(0, 10) === v;
+}
+export function parseDayRange(from, to) {
+    const absent = (v) => v === undefined || v === null || v === '';
+    if (absent(from) && absent(to))
+        return { range: null, fullRangeFallback: false };
+    // Half a range is a rejected range. Inferring the missing end would invent an
+    // operator intent and render figures under a heading nobody chose.
+    if (!isDayKey(from) || !isDayKey(to))
+        return { range: null, fullRangeFallback: true };
+    if (from > to)
+        return { range: null, fullRangeFallback: true };
+    return { range: { from, to }, fullRangeFallback: false };
+}
+function zeroTokens() {
+    return { output: 0, input: 0, cacheWrite: 0, cacheRead: 0 };
+}
+/** Sum a session's day rows over an inclusive range. A null range means every
+ *  day.
+ *
+ *  Cost is re-derived from the SUMMED tokens rather than summed from the
+ *  per-day costs, matching how computeMetering derives its own totals — adding
+ *  already-rounded figures compounds their rounding. */
+export function sliceMeteringDays(days, range, cfg = defaultPricingConfig()) {
+    const inRange = range === null
+        ? days
+        : days.filter((d) => d.date >= range.from && d.date <= range.to);
+    let activeMs = 0;
+    const tokens = zeroTokens();
+    for (const d of inRange) {
+        activeMs += d.activeMs.thinking + d.activeMs.messaging + d.activeMs.toolUse;
+        tokens.output += d.tokens.output;
+        tokens.input += d.tokens.input;
+        tokens.cacheWrite += d.tokens.cacheWrite;
+        tokens.cacheRead += d.tokens.cacheRead;
+    }
+    return {
+        activeMs,
+        tokens: tokens.output + tokens.input + tokens.cacheWrite + tokens.cacheRead,
+        costGBP: { opus: opusCostGBP(tokens, cfg), sonnet: sonnetCostGBP(tokens, cfg) },
+        matchedDays: inRange.length,
+    };
+}
+//# sourceMappingURL=activity-range.js.map

package/payload/platform/services/claude-session-manager/dist/activity-range.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-range.js","sourceRoot":"","sources":["../src/activity-range.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,wCAAwC;AACxC,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,2EAA2E;AAC3E,2EAA2E;AAG3E,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,GAGd,MAAM,cAAc,CAAA;AAsBrB;;;;;sDAKsD;AACtD,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IACzE,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAA;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IACrC,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAA;AACrD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,EAAW;IACtD,MAAM,MAAM,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAA;IACxE,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAA;IAChF,8EAA8E;IAC9E,mEAAmE;IACnE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAA;IACrF,IAAI,IAAI,GAAG,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAA;IAC9D,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAA;AAC1D,CAAC;AAWD,SAAS,UAAU;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;AAC7D,CAAC;AAED;;;;;wDAKwD;AACxD,MAAM,UAAU,iBAAiB,CAC/B,IAAmB,EACnB,KAAsB,EACtB,MAAqB,oBAAoB,EAAE;IAE3C,MAAM,OAAO,GAAG,KAAK,KAAK,IAAI;QAC5B,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,CAAA;IAElE,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAA;QAC3E,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;QAChC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAA;QAC9B,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC,MAAM,CAAC,UAAU,CAAA;QACxC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAA;IACxC,CAAC;IAED,OAAO;QACL,QAAQ;QACR,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS;QAC3E,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;QAC/E,WAAW,EAAE,OAAO,CAAC,MAAM;KAC5B,CAAA;AACH,CAAC"}

package/payload/platform/services/claude-session-manager/dist/activity-rows.d.ts

@@ -1,3 +1,5 @@
+import { type MeteringDay } from './session-metering.js';
+import { type DayRange } from './activity-range.js';
 import type { CensusSession, PtyCensusSnapshot } from './pty-census.js';
 import type { FsWatcher } from './fs-watcher.js';
 import type { Logger } from './pty-census.js';
@@ -24,15 +26,17 @@ export interface ActivityEnriched {
     turnCount: number;
     /** True when the tail parse was clipped, making turnCount a lower bound. */
     capped: boolean;
-    usedTokens: number | null;
 }
-/** The metering half of a row. `costGBP` carries BOTH price assumptions
- *  because that is what MeteringSummary produces; the join picks the arm. */
+/** The metering half of a row.
+ *
+ *  Carries the DAY ROWS, not a pre-summed cost. The range is applied per
+ *  request while the parse is memoised per transcript, so changing the range is
+ *  a filter over data already in hand rather than a re-parse of every live
+ *  transcript on the box (Task 1827). Each day still prices its own tokens under
+ *  BOTH assumptions, because that is what MeteringSummary produces; the join
+ *  picks the arm. */
 export interface ActivityMetering {
-    costGBP: {
-        opus: number;
-        sonnet: number;
-    } | null;
+    days: MeteringDay[] | null;
     error: string | null;
 }
 /** Why a row has no cost. Three distinct facts that would otherwise render as
@@ -76,7 +80,23 @@ export interface ActivityRow {
     rssKb: number | null;
     /** Null when unmeasured. Never 0 to mean idle. See CensusSession.cpuPct. */
     cpuPct: number | null;
-    usedTokens: number | null;
+    /** Active time inside the requested range: thinking + messaging + toolUse
+     *  summed over the range's MeteringDay entries.
+     *
+     *  This is WORKED time. `ageMs` beside it is wall-clock since the first turn
+     *  and is dominated by idle human-wait, which is why the page showed `2d 17h`
+     *  for a session that had done `1h 35m` of work.
+     *
+     *  Null ONLY when metering itself failed. A range containing no days is 0 —
+     *  a measured, genuinely quiet period — and the two must never collapse: the
+     *  page renders a dash for the first and `0h 0m` for the second (Task 1827). */
+    activeMsInRange: number | null;
+    /** Tokens billed inside the range, summed over MeteringDay.tokens.
+     *
+     *  REPLACES `usedTokens`, which was the live context-window snapshot — a
+     *  point-in-time reading that no date range can bound. Same null rule as
+     *  activeMsInRange. */
+    tokensInRange: number | null;
     /** The costGBP arm matching this row's own model, in GBP. Null when the
      *  model is unknown, maps to neither priced family, or metering failed. */
     costGbp: number | null;
@@ -138,6 +158,8 @@ export declare function buildActivityRows(input: {
     metering: Map<string, ActivityMetering>;
     enrichErrors?: Map<string, string>;
     nowMs: number;
+    /** Inclusive UTC day range for the metering figures, or null for every day. */
+    range: DayRange | null;
 }): ActivityRow[];
 /** Fixed-size worker pool. Bounds the metering fan-out: computeMetering is a
  *  FULL JSONL parse per session, so an unbounded Promise.all over a busy box
@@ -163,6 +185,12 @@ export interface CollectActivityDeps {
     nowMs?: number;
     /** Bound on concurrent full-JSONL metering parses. */
     meteringConcurrency?: number;
+    /** Inclusive UTC day range for the metering figures, or null for all time. */
+    range?: DayRange | null;
+    /** True when a range WAS requested and could not be honoured. Carried through
+     *  so the response and the log can both say the page is showing all-time
+     *  figures under a bounded heading. */
+    fullRangeFallback?: boolean;
 }
 export interface ActivityResult {
     rows: ActivityRow[];
@@ -171,6 +199,10 @@ export interface ActivityResult {
         live: number;
         cpuNull: number;
     } | null;
+    /** The range actually applied, echoed so the page can label its own figures
+     *  with what it got rather than with what it asked for. */
+    range: DayRange | null;
+    fullRangeFallback: boolean;
 }
 /** Test seam — the memo is module state, so a suite asserting parse counts
  *  needs to clear it between cases. */