Status Line¶

What a badge is telling you¶

The emoji is the label; the dot is the state. The leading emoji says what the badge is about and never changes; the tinted ● after it says how that thing is doing.

[🏥●] [AX●C●] [🔒72%●7] [📚●] [N:OPEN P:AUTO] [🧠●] ███░░░░░ 47% [📋8-9] 08:20

Each badge belongs to a feature, and a feature you have switched off contributes no badge at all — see Composing What Runs.

The badges are clickable¶

Clicking a badge opens the thing it describes. Two kinds of target: a page, which reuses the browser tab you already have open, and a popup over your pane, dismissed with any key.

The clock is deliberately inert. Every action is read-only — a stray click cannot restart, toggle or write anything.

Two absences that are good news¶

[LSL●] appears only when session logging for this pane is unhealthy — no badge means it is fine. [L:n] and [D:n] (local executions, prompt downgrades) are hidden at zero.

The gauge is the odd one out¶

The context gauge has no brackets and no emoji — it carries a tinted background instead, which is what separates it. It describes the agent in this pane, not the system.

A pane that has just started shows the gauge's zero position — an empty trough at 0% — until its agent first reports. That is a new session, not a fault. A gauge that is absent altogether means the agent has no readable context store at all, which is a different thing and looks different.

Colours¶

Red is reserved. Knowledge-pipeline staleness fades through a green ramp rather than going red, so "getting old" and "actually broken" never look the same.

How it gets rendered¶

status-right invokes a small CommonJS fast-path reader that serves a per-pane pre-rendered cache in roughly 60 ms, and only spawns the full renderer when that cache is stale. The full renderer pulls live state from the health coordinator on :3034 — the single source of truth — and every coordinator-derived badge shares one memoized probe per render, so a bar with eight badges still makes one call.

That two-stage design is why the bar can update every five seconds without the cost showing up anywhere.

Reading state¶

Every badge follows the same convention: a fixed emoji identifying the subject, then a glyph carrying the state. Where the state is purely a severity it is a tinted dot on a shared four-colour scale, so you learn one scale rather than one vocabulary per badge.

Session activity uses a graduated green ramp rather than a binary, which is how an idle session is distinguishable from an active one without a second glyph.

The context gauge¶

The gauge shows how full the conversation in this pane is — not a system metric, and not shared between panes. It is deliberately the only segment without brackets or a leading emoji, using a tinted background as its delimiter instead, so it reads as a different kind of thing at a glance.

Why some badges are missing¶

Several segments are hidden in their healthy or zero state, on the principle that a bar full of "everything is fine" is harder to scan than one that only speaks up when it has something to say:

Clicking a badge¶

tmux can make a span of the status line a mouse target, so each field is wrapped in a range carrying its own tag; a click reports that tag to a binding, which hands it to a small dispatcher. The clock carries no range, which is why it does nothing.

Pages reuse a tab. A status line is clicked often, so opening a new tab each time would bury the browser in duplicates. The dispatcher looks for a tab already showing the dashboard and navigates that one to the route you asked for — which is also how the sub-tab gets selected. A tab already on the target is focused without reloading, so scroll position and filters survive.

Only the top-level tabs are routes and therefore addressable this way. The nested tabs inside Token Usage and Performance are component state, not URLs, so a click lands on the page and not on the inner tab.

Popups answer the question the badge raises. A two-cell badge can say that something is wrong but never what, so the three fields whose subject has no page of its own open a report instead.

The network badge answers where your traffic actually goes — which is not obvious from [N:OPEN P:ON], and changes with the network:

The semantic badge explains its own colour. recent-real-traffic is the healthy case — the coordinator saw genuine traffic succeed and skipped its probe — which reads like a fault until something says so:

The gauge popup gives the context in tokens against the real window, and explains why it reads higher than the raw percentage: Claude Code reserves ~16.5% of the window for auto-compaction, and the gauge measures against the usable remainder:

When the bar itself is wrong¶

The status line is a reader. A grey or stale health badge means the thing it reads from has stopped, not that the services it describes have — check the coordinator first.

A project missing from the session list means that project has no session monitor running, which is different from its monitor being unhealthy. And a stale bar after a code change is usually a long-lived tmux session still executing an older binary; check what is actually on disk before chasing the rendering.

Changing it¶

The bar is configured per project and rendered by a shared script, so a change affects every agent's session. Because sessions can override global tmux settings, read the live environment of the running session rather than the config file when a setting appears not to apply.

Real-time visual indicators of system health and development activity rendered via the unified tmux status bar. All coding agents (Claude, CoPilot, etc.) are wrapped in tmux sessions; status-right invokes status-line-fast.cjs, a CommonJS fast-path reader that serves a per-pane pre-rendered cache (~60 ms) and spawns the full combined-status-line.js (CSL) renderer only when the cache is stale. The renderer pulls live state from the health coordinator at :3034 (Phase 33 single source of truth, replacing the retired host-side health-verifier daemon and .health/verification-status.json file). All coordinator-derived badges share a single memoized probe per render — see Architecture → Shared coordinator probe.

Reading the Status Line¶

Example Display¶

[🏥●] [RA●C●] [🔒77% ⚙️IMP] [📚●] [N:VPN P:ON] ███░░░░░  42% [📋18-19] 18:34

The current pane's project is rendered with an underline (#[underscore]…#[nounderscore]) so each parallel tmux window highlights its own project.

Component Breakdown¶

The context gauge is the one segment with no […] brackets and no leading emoji: it carries a tinted background instead, which delimits it on its own.

Complete Glyph Reference¶

Every badge follows one rule: the emoji is the label, the dot is the state.

The leading emoji (🏥 🔒 📚 🧠) says what the badge is about and never changes. The glyph after it says how that thing is doing, and when the answer is purely a severity it is a tinted ● on a shared four-colour scale:

Some states are not severities, and those keep a pictogram, because a dot scale can only say how bad — never what happened:

System Health Indicators¶

The badge is derived live from the coordinator at :3034/health/state. There is no longer a host-side health-verifier daemon; the badge reflects the coordinator's rollup of probed services, database checks, and container healthcheck.

Session Activity Indicators¶

Sessions use a graduated green ramp based on time since last activity. All sessions are always displayed — sleeping sessions show as a grey dot, never hidden. Sessions are only removed when the agent process exits.

The "time since last activity" signal is the newest timestamped record in the project's Claude .jsonl transcript — i.e. the time of the last prompt boundary.

A long-running agent turn (one prompt that takes 25 minutes) writes nothing to the transcript while it's in flight, so a project actively being worked on by an agent looks idle by timestamp alone. To capture that, a heartbeat promotion rule overrides the transcript-derived band: if the project's ETM heartbeat (state.lsl[*].lastBeat) is fresh (< 5 min) and there is genuine recent content activity, a non-Active band is promoted to Active. The heartbeat alone is not sufficient — it also fires after laptop wake — which is why the second condition exists. The promotion also handles non-Claude sessions (OpenCode / Copilot) whose transcriptPath is not a real file.

Visual progression: one glyph, five shades — the dot darkens through green as the signal ages, then drops to grey once the session has been idle over a day. Unicode has only one green circle emoji, so the ramp is a 1-cell ● tinted with tmux colours rather than an emoji sequence.

● Active → ● Cooling → ● Fading → ● Inactive → ● Sleeping
(colour41 → colour34 → colour28 → colour22 → colour238)
   <5min      5-30min     30m-6hr     6-24hr       >24hr

Network & Proxy Indicators¶

Two ASCII-only badges reflect the network environment detected by the coordinator every 15 seconds. They avoid emoji to prevent cell-width issues in tmux.

Routing & Execution Indicators¶

Two ASCII-only counters describing what the LLM proxy did with the traffic it was given. Both are read from the coordinator, which polls rapid-llm-proxy (:12435) on its own cheap GETs — /api/llm/classifier/stats and /api/llm/execution/stats — every coordinator tick. Neither costs a model call.

Both count since the proxy started. A proxy restart resets them at the source, so the one non-monotonic transition you will see is the number going down; that is a restart, not a bug.

Neither badge ever colours the bar. A classifier that has downgraded nothing and a machine that has run nothing locally are both ordinary states, usually meaning "no eligible traffic" — a badge that turned the line yellow on an absence would cry wolf every quiet hour.

# 1. Is the proxy counting at all?
curl -s localhost:12435/api/llm/execution/stats
#    {"sinceBootMs":49358423,"completions":353,"local":0}

# 2. Did the coordinator read it? (last_poll present = real zero, not no-data)
curl -s localhost:3034/health/state | python3 -c \
  "import sys,json; print(json.load(sys.stdin)['execution'])"

# 3. Why did nothing offload? The proxy names the reason itself.
curl -s 'localhost:12435/api/llm/routing/resolve?job=fg-chat/opencode&complexity=small' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['route']['offloadSkipped'])"
#    no offload target for network=public
#    (targets: qwen-local[corporate/fg+bg], qwen-laptop[public/fg] (off))

Knowledge Pipeline Indicators¶

The badge reflects the freshness of the observation → digest → insight pipeline (the obs_api service backed by km-core GraphKMStore at .data/knowledge-graph/; the legacy .observations/observations.db SQLite store was archived 2026-06-05 under Phase 44 Plan 18). Verdict is driven by observation freshness only — digest and insight cadences are intentionally slower and don't gate the badge. Source: state.knowledge_pipeline at the coordinator's /health/state (populated by pollKnowledgePipeline, which calls obs_api's /api/consolidation/status).

Idle suppression is applied via CombinedStatusLine.isUserActive(), which checks state.lsl for any session whose lastBeat is within 5 min. When no session is heartbeating, the freshness-derived icons collapse to a single grey ● (idle, colour238). True error states (disabled, unknown, unreachable) are NOT suppressed.

Tooltip details (visible in the verbose status output) include observation/digest/insight ages, totals, and any in-flight consolidation.

LSL Health Indicators¶

Whether an enhanced-transcript-monitor (ETM) is actually watching this pane's project. Hidden entirely when healthy — the badge only appears when there is something to say.

Context Window Gauge¶

How full the current pane's agent conversation is. It used to exist only inside Claude's own statusline, so only one of the four agents had it; it now lives in the tmux bar, where opencode, copilot and pi panes get the same reading.

███░░░░░  42%

A bright fill over a duller background of the same hue — the fill reads as a watermark against a tinted trough. Thresholds are the ones the old Claude meter used:

██░░░░░░  31%   ████░░░░  55%   █████░░░  71%   ███████░  93%

The zero position, and the absence¶

A pane whose agent has not reported yet renders the gauge's zero position — an empty trough at 0%, in the calm band:

░░░░░░░░   0%

That window is real: on a fresh session the agent has not drawn its own status line yet, so the bridge file the gauge reads does not exist. It used to render as a 13-cell blank, which on screen is a black hole in the bar — indistinguishable from a fault, and it lasted until the first command.

The principle behind that blank is kept, because it is right: a gauge reading 0% and a gauge that cannot see its source must not look the same. It was being applied to the wrong case. A brand-new session is not a gauge that cannot see its source; it is a gauge whose source has nothing to report yet, and one tick later the agent reports exactly this — 0%.

The distinction survives where it is still real. hasContextReader() separates the two reasons there might be no number:

The second is structural — no next tick is going to change it — so it stays absent.

Where the number comes from, per agent. All four are exact on-disk sources — none is estimated:

Which Claude session the gauge reads. The bridge file is keyed on Claude Code's own session id, so the renderers have to know which session owns the pane before they can read anything. That id is recorded by scripts/claude-statusline.cjs, the shim Claude Code runs as its status line — the one place that sees the session id (handed to it on stdin) and the tmux session together. It writes $TMPDIR/claude-tmux-session-<tmux-session-name>.json on every render, and both renderers look the pane up there first.

The key is the tmux session name, not the pane: tmux runs status-right in the server rather than in a pane, so the renderers never receive TMUX_PANE — what the format string passes them is #{session_name} as TMUX_SESSION_NAME. It is also the right granularity, since status-right is drawn once per tmux session and these agent launches are one tmux session apiece.

Without a record the renderers fall back to their older project-keyed lookups — the newest-beating coordinator LSL entry in the full render, the single transcript path per project in the fast path's sidecar. Those name a project, not a session, so on a project that has hosted more than one they can name the wrong one, and the per-pane tie-break meant to disambiguate them never fires (coordinator entries take their pane from the ETM heartbeat, and ETMs are project singletons carrying only the launcher's pane, so tmuxPane is null in practice). The symptom was a first-turn session rendering the context of the session the user had just closed until its own ETM registered and out-beat the old one's remaining heartbeats — measured at 66%, which is exactly what the previous session's bridge file normalises to while the fresh one said 13%. The fallback is kept for panes with no record: an unwrapped claude, or the tick before the first render.

Records expire after 24 h. That is not a freshness requirement — a live session rewrites its record on every render, but an idle one may not render for hours and must keep its mapping. It bounds the one case where the name alone is ambiguous: tmux session names embed the launcher pid, and pids come round again after a reboot.

Reclaiming the temp files. Three families accumulate in the system temp directory, one per session, and until recently nothing removed them: claude-ctx-<sessionId>.json, GSD's claude-ctx-<sessionId>-warned.json companion, and the claude-tmux-session-<name>.json records above. scripts/claude-ctx-sweeper.mjs deletes them once they pass CLAUDE_CTX_RETENTION_DAYS (default 2), and is run from the agent launch path in bin/coding — backgrounded, and rate-limited via --if-older-than so a burst of launches sweeps once rather than once each. It never throws and always exits 0: a launch must not be able to fail over housekeeping.

It keys on the temp file's own mtime, not on the session transcript's. The transcript is the tempting signal and the wrong one — transcript mtimes are bulk-touched, and one session was observed with a transcript modified minutes ago whose ctx file had not moved in three days. These files are written only by the render loop, so their mtime means exactly "when this session last drew its status line". Reclaiming one wrongly costs a blank gauge in that pane until its next render, which rewrites the file.

Only those three prefixes are matched, and only with a .json extension. The temp directory is shared with the OS and with the rest of this repo (vkb-server.pid, kgbench-needles-*, the copilot KB stash), so a wildcard sweep there would be a footgun.

Windows also gets a scheduled task. macOS purges /var/folders and Linux ships systemd-tmpfiles for /tmp, so on those the launch-time sweep plus the OS is enough. Windows reclaims %TEMP% never, so install.sh offers an hourly Scheduled Task (\coding\claude-ctx-sweeper, installed by scripts/install-claude-ctx-sweeper-schtasks.sh, removed by uninstall.sh). It is the only system-scope change the sweeper makes on any platform, and declining it loses nothing but the sweeps that would have happened while no agent was running.

Absent, not zero. When a store cannot be read — an agent with no session for this project, a missing database, an unreadable file — the gauge renders nothing at all. A gauge showing 0% and a gauge that cannot see its source must not look the same.

Per-pane, not per-project. CODING_AGENT is part of the render-cache key (cache-<project>-<agent>-w<width>.txt), so a claude pane and an opencode pane on the same project at the same width cannot share a cached line and show each other's reading. When a pane borrows a sibling's cache because it has none of its own, the gauge is blanked first — a width-identical run of spaces — because that value belongs to a different session.

Coordinator Health Endpoint¶

The statusline pulls all health-related signals live from the coordinator. Inspect raw state with:

curl -fs http://localhost:3034/health/state | jq .

Phase 33 retired the .logs/statusline-health-status.txt rollup and the .health/verification-status.json file; do not write or read those paths in new code.

Transcript Discovery Auto-Heal¶

The ETM (enhanced-transcript-monitor.js) detects broken transcript discovery — monitor running but unable to locate its project's transcript JSONL.

• Detection: ETM heartbeat reports transcriptPath: null while uptime exceeds the discovery grace period
• Remediation: ETM exits with non-zero status; the launcher / supervisor restarts it
• Display: Project rolls up as degraded, surfaces as a bold amber ● (ALARM_DOTS.WARN) in the sessions block
• Path encoding: Claude Code replaces both / and _ with - (e.g. /_work/ → --work-)

Clickable Fields¶

Every field except the clock is a mouse target. The chain is: a range marker in the rendered string → a tmux key binding → a dispatcher script.

Ranges¶

lib/statusline/clickable.cjs wraps each field in #[range=user|TAG] … #[norange]. tmux reports TAG in #{mouse_status_range} when the span is clicked. Ranges emitted from a #(...) command are honoured — range parsing happens at draw time, on the final expanded string — so the fields work despite the bar being produced by a script.

Tagging happens in one pass at the join, driven by a rule table keyed on each field's leading badge glyph, rather than at the ~30 push sites. The context gauge and the UKB counter are the exceptions: the gauge has no fixed leading glyph, and the UKB counter opens with the same [🧠 as the proxy badge, so both are tagged where they are pushed.

Two constraints that are easy to violate silently:

• TAG is capped at 15 bytes. tmux drops a longer range with no error anywhere — the field simply stops responding. Project tags are therefore p: plus a possibly-truncated project name, resolved by prefix against the coordinator's project list.
• Tags must be lowercase. The fast path re-applies the underline and repaints lifecycle icons by matching UPPERCASE abbreviations, guarded by lookaround on both sides so that an abbreviation only matches as a whole token — no uppercase letter immediately before or after it. An uppercase letter inside a range tag would sit in those guards' blind spot and could be rewritten as if it were a project bubble.

Range markers cost zero cells: visibleCellWidth() strips #[...] before counting, so the padding maths is unchanged and the right-edge residue bug stays shut.

Binding¶

Key tables are server-wide — there is no per-session binding — so MouseDown1Status is rebound once during session setup and must preserve the default window behaviour explicitly:

bind -n MouseDown1Status \
  if-shell -F '#{==:#{mouse_status_range},window}' \
    'switch-client -t =' \
    'run-shell -b "<repo>/bin/statusline-click #{mouse_status_range} #{pane_id}"'

set-option does not expand formats in a value, so the tag cannot be stashed in a user option and read back; run-shell does expand them, which is why the tag travels as an argument. The pane id travels with it because display-popup reached from a shell has no client context of its own.

Dispatcher¶

bin/statusline-click maps a tag to an action. Every action is read-only, because a status line is glanced at far more often than it is deliberately clicked.

Two things do not reach the dispatcher and have to be recovered:

• The pane's environment. run-shell executes in the tmux server's environment, so CODING_AGENT / TMUX_SESSION_NAME are unset however they were exported at launch. They are read back from the session name plus .data/agent-sessions/<session>.json — the same record the context gauge already uses, so this cannot drift from what the bar displays.
• Silence. run-shell renders any stdout in a view the user must dismiss with ESC, and AppleScript prints its handler's return value. Both stdout and stderr are discarded, or a successful click interrupts the session it was meant to serve.

Tab reuse¶

Pages are opened through AppleScript rather than open, matching an existing tab by URL prefix — the origin for dashboards, the full URL for a repository. A matching tab is navigated to the requested route (this is what selects the sub-tab); a tab already on the target is focused without reloading, preserving scroll position and filters. Any scripting failure falls through to a plain open, so a refused automation prompt still gets the page.

Only top-level routes are addressable. Nested tabs inside Token Usage and Performance are component state with no URL, so deep-linking them would require adding URL state to the dashboard.

When a click does nothing¶

Architecture¶

6-Layer Health System¶

The StatusLineHealthMonitor (Layer 4) aggregates health from all other layers and outputs to the Combined Status Line display.

Tmux-Based Rendering¶

All coding agents are wrapped in tmux sessions via scripts/tmux-session-wrapper.sh. The wrapper:

• Creates a tmux session named coding-{agent}-{PID}
• Configures status-right to invoke status-line-fast.cjs (CJS fast-path cache reader, ~60ms)
• Handles nesting guard (reuses existing tmux if already inside one)
• Propagates environment variables (CODING_REPO, SESSION_ID, etc.)
• Enables mouse forwarding for terminal interaction

This replaces the previous approach of using agent-specific status bar APIs (e.g., Claude's statusLine config), providing a unified rendering target that works identically for all agents.

Cache Fast-Path¶

status-line-fast.cjs is the primary entry point invoked by tmux status-right. It's a CommonJS reader (no ESM module-load penalty under load) that serves the per-pane pre-rendered cache in ~60 ms:

• Cache file: .logs/combined-status-line-cache-<project>-w<paneWidth>.txt (one per (project, pane-width) tuple — width key prevents cross-pane contamination)
• Cache TTL: 60 s in fast.cjs (a separate 30 s TTL inside CSL itself when CSL re-enters via its own cache check)
• Fresh (<60 s): serves immediately, optionally patches lifecycle icons against current transcript mtimes, triggers background refresh if cache >20 s old or transcript activity is newer than cache
• Stale or missing: spawns the full combined-status-line.js synchronously
• Critical detail: fast.cjs calls child.stdin.end() immediately after spawning CSL. CSL's readStdinInput() (used by getRedirectStatus()) iterates over process.stdin and would otherwise hang the full 8 s SYS:TIMEOUT window waiting for EOF on any pane whose TRANSCRIPT_SOURCE_PROJECT falls outside the coding repo.
• combined-status-line-wrapper.js is retained as a backup but is no longer the primary path.

Shared coordinator probe¶

Every render needs seven different slices of state from the health coordinator (knowledge_pipeline, proxy, network, classifier, execution, services rollup + generated_at staleness, lsl_by_project). Each was previously a separate synchronous probe via execSync('curl …'); that many identical localhost HTTP calls per render added up to ~3 s under load and tripped the 8 s SYS:TIMEOUT during tmux refresh bursts.

The renderer now exposes a single getCoordinatorState() method memoized on the CombinedStatusLine instance (one instance per render):

• Uses native fetch instead of execSync(curl) to skip subprocess-spawn overhead
• 1.5 s per-attempt budget with one retry (150 ms gap)
• All seven getXxxStatus() methods await the shared result; one HTTP call serves the whole render — including getClassifierStatus() and getExecutionStatus(), so the [D:] and [L:] counters cost no extra request
• A single transient slow response no longer cascades every coordinator-derived badge (🏥 LSL 📚 🧠 [N:] [P:] [D:] [L:]) to its unreachable state simultaneously

Right-edge stability (cell-width consistency)¶

The recurring trailing-digit residue at the right edge (07:538, 12:411, 07:158) traces to disagreement between the script's visibleCellWidth(), tmux's wcwidth, and the rendered font glyph. The fix is to only emit codepoints where all three measurements agree:

• Warning and error states are ● (U+25CF), which is unambiguously ONE cell in both tmux and the terminal — so they contribute no width disagreement at all. This supersedes two earlier rounds: ⚠️ (U+26A0 + U+FE0F, EAW=Ambiguous) was replaced by 🟡 (U+1F7E1, EAW=Wide) because promoting ⚠️ to 2 cells via a VS16 lookahead in visibleCellWidth() matched the font glyph but disagreed with tmux's wcwidth (which doesn't honour VS16 for Ambiguous codepoints in non-CJK locales), leaving 1 cell of the previous render exposed on every transition. 🟡 in turn became a bold ●. The SYS:TIMEOUT / SYS:ERR fallback markers now use the same dot; the VS16 lookahead stays in visibleCellWidth() because emoji remain in the labels (🏥🔒📚🧠📋).
• Padding is leading-spaces only to TMUX_PANE_WIDTH (or 200 if unset). Trailing characters get stripped by tmux's #(shell-cmd) substitution, so any trailing terminator (NBSP, space, etc.) doesn't survive the round-trip.
• The earlier NBSP-terminator + 220-codepoint approach has been retired in favour of correct per-codepoint cell counting.

Status Line Update Flow¶

Cache fast-path (normal operation):

1. tmux status-interval: status-right fires every 5 s → status-line-fast.cjs
2. Cache check: read .logs/combined-status-line-cache-<project>-w<paneWidth>.txt
3. Fresh (<30 s): pass through to tmux (with lifecycle-icon patching against current transcript mtimes), trigger background refresh if cache age >10 s or any tracked transcript is newer than cache
4. Stale or missing: spawn combined-status-line.js synchronously and child.stdin.end() immediately so CSL's readStdinInput() doesn't hang waiting for EOF

Full refresh:

1. Shared coordinator probe: a single memoized fetch(:3034/health/state) per render (with one retry @ 1.5 s) feeds five getXxxStatus() methods — replaces the previous pattern of 5 independent execSync(curl) calls per render
2. Per-project activity age: read the newest timestamped record in each lsl[*].transcriptPath (bounded tail read, NOT the file mtime) → bucket into the ramp (bright → mid → dark → very dark green → grey). A fresh ETM heartbeat (< 5 min) plus genuine content activity promotes a non-Active band to 🟢 (captures long-running agent turns and non-Claude sessions).
3. Constraint compliance: separate call to constraint-monitor API (port 3031)
4. Render: assemble parts, pad to paneWidth cells via leftPadToStableCellWidth() using VS16-aware visibleCellWidth() — see Right-edge stability above
5. Cache write: save to .logs/combined-status-line-cache-<project>-w<paneWidth>.txt
6. Failure logging: any 8 s SYS:TIMEOUT or fast.cjs spawn failure appends a JSON record to .logs/csl-failures.jsonl with per-step timings so future Claude sessions can see which sub-step blocked

Caching¶

Spawn Storm Prevention¶

The supervision architecture includes guards to prevent runaway process spawning:

Service Lifecycle States¶

State Transitions¶

Health States (for [🏥...] indicator): - Coordinator reachable + 0 critical issues → Healthy (green ●, STATE_DOTS.OK) - Coordinator reachable + ≥1 service degraded / GCM warning → Warning (amber ●, STATE_DOTS.WARN) - Coordinator reachable + critical failure (downed service, unhealthy DB, container probe fail) → Critical (red ●, STATE_DOTS.CRIT) - Coordinator generated_at >3 min old → Stale (⏰) - Coordinator unreachable → Offline (grey ●, colour238)

Session States (graduated cooling scheme): - Driven by the newest timestamped record in transcriptPath (not its mtime), bucketed: colour41 (<5 m) → colour34 (<30 m) → colour28 (<6 h) → colour22 (<24 h) → colour238 (≥24 h) - Heartbeat-promotion override: if lsl[*].lastBeat is < 5 min, any non-🟢 band is overridden to 🟢. Captures long-running agent turns (one prompt that takes >5 min) and non-Claude sessions whose transcriptPath is not a real file - Sessions only removed when the project's ETM stops heartbeating, never hidden while alive

Session Discovery¶

Discovery Methods¶

1. Running Monitor Detection: Checks ps aux for running enhanced-transcript-monitor.js processes
2. Agent Process Detection: Scans for claude, copilot, and opencode processes via ps -eo pid,comm and resolves project from working directory via lsof
3. Registry-based Discovery: Uses Global LSL Registry for registered sessions
4. Dynamic Discovery: Scans Claude transcript directories for unregistered sessions
5. Health File Validation: Uses centralized health files from .health/ directory

Key Behavior¶

• Sessions with a running agent process use age capped at monitor uptime (graduated cooling from session start)
• Sessions with running transcript monitors but no active agent use transcript-based activity icons
• Sessions are only removed when the agent process has exited — never hidden
• The Global Process Supervisor automatically restarts dead monitors within 30 seconds

Multi-Agent Support¶

New agents can be added to the detection loop in statusline-health-monitor.js → getRunningAgentSessions().

Smart Abbreviation Engine¶

Project names are automatically abbreviated:

Algorithm Handles: - Single words: First letter (coding → C) - Hyphenated words: First letter of each part (curriculum-alignment → CA) - Camel case: Capital letters (projectManagement → PM)

Configuration¶

Status Line Configuration¶

The renderer reads a small set of environment variables and the coordinator endpoint; legacy config/status-line-config.json health_source / lsl_registry keys are no longer consulted.

Tmux codepoint-widths¶

Every Unicode-10+ emoji the statusline can emit needs an explicit width override in tmux because tmux's bundled wcwidth table predates Unicode 10 and silently treats new codepoints as width=1, even when they are East-Asian-Width Wide. Each disagreement leaks one cell of the previous render through to the right edge, producing the recurring trailing-digit residue (07:538, 08:054, 16:3175). Add this to ~/.tmux.conf:

set -g codepoint-widths "U+26A0=2,U+FE0F=0,U+1F7E0=2,U+1F7E1=2,U+1F7E2=2,U+1F7E4=2,U+1F9E0=2,U+1F9EE=2,U+1F976=2"

After editing, run tmux source-file ~/.tmux.conf. New tmux sessions inherit it immediately. The full mapping:

node --input-type=module -e "
import fs from 'node:fs';
const code = fs.readFileSync('scripts/combined-status-line.js','utf8').split('\n')
  .map(l => l.replace(/\/\/.*\$/, ''))
  .filter(l => { const t = l.trim(); return t && !t.startsWith('*') && !t.startsWith('/*'); })
  .filter(l => !l.includes('lines.push'));   // verbose tooltip is plain text, not the bar
const seen = new Set();
for (const l of code) for (const ch of [...l]) {
  const cp = ch.codePointAt(0);
  if (cp > 0x2190) seen.add(ch + '  U+' + cp.toString(16).toUpperCase());
}
console.log([...seen].sort().join('\n'));
"

Why fix in tmux, not the script. Several earlier attempts modified visibleCellWidth() in scripts/combined-status-line.js to compensate for the disagreement and introduced new disagreements each time. The script's count is correct for the codepoints it currently handles — the issue is downstream in tmux's wcwidth table, fixable only via codepoint-widths. Do not touch the script's width math. If a new Ambiguous emoji enters the statusline repertoire and residue returns, probe its tmux-vs-terminal width with the snippet in Troubleshooting → Right-edge residue and append it to the override.

Retired lifecycle emojis. 🌲 (Unicode 6, OK), 🫒 (U+1FAD2, Unicode 13), and 🪨 (U+1FAA8, Unicode 13) used to sit in the cooling/fading/dormant tiers. The Unicode-13 codepoints were too new for tmux's wcwidth table to know about even with codepoint-widths overrides (tmux 3.4 silently ignores codepoints it can't normalize). They were first replaced by the coloured circles (🟠/🟤) on stable Geometric-Shapes-Ext blocks, and those in turn by the tinted ● ramp described above — which sidesteps the whole class of problem, since U+25CF needs no codepoint-widths entry to begin with.

Terminal Title Broadcasting¶

How It Works¶

Every 15 seconds, the statusline-health-monitor broadcasts status to all Claude session terminals via ANSI escape codes:

Terminal Tab: "C● | UT● CA●"
              ↑          ↑
        Current     Other active sessions
        project     (all sessions shown)

Terminal Compatibility¶

Troubleshooting¶

Trailing junk after the clock (15:322, 07:407)?¶

A leftover cell from the previous, wider frame. tmux does not clear status-right cells when the content shrinks, so the renderer left-pads every line to a constant cell count. Residue means that count stopped being constant.

It is almost never an emoji-width problem. That is the intuitive theory and it has been wrong every time it was tested — tmux's own per-codepoint width agrees with visibleCellWidth() for every glyph in use. Measure before assuming:

# tmux's OWN width for a glyph — prompt-free pane, read cursor_x
tmux new-session -d -s wp -x 80 -y 5 "printf '%s' '●'; sleep 20"; sleep 0.6
tmux display-message -p -t wp '#{cursor_x}'    # 1 for ●, 2 for emoji

The real cause is a width the renderer could not reserve correctly. Check the invariant directly — for each live cache, pane_width − rendered_width must equal the width of status-left:

ls -t .logs/combined-status-line-cache-*-w*.txt | head -3
# reserve == 0 means status-right was padded to the FULL pane width,
# so status-left + status-right overruns the row.

If the reserve is 0, the renderer never received TMUX_SESSION_NAME (it derives the reserve from the session name's length). Read the environment of a live process, not the config — sessions override the global status-right with their own command, so ~/.tmux.conf can look correct while the running command is missing the variable:

PID=$(/bin/ps ax -o pid,command | grep -E "combined-status-line" | grep -v grep | awk 'NR==1{print $1}')
/bin/ps -E -p "$PID" -o command= | tr ' ' '\n' | grep '^TMUX_'

Sessions get the correct command from scripts/tmux-session-wrapper.sh. Already-running sessions keep whatever they were created with, so after changing it either restart them or re-apply with tmux set-option -t <session> status-right ….

Status bar completely blank?¶

# Check cache file freshness
ls -la .logs/combined-status-line-cache.txt

# Test fast-path directly (should complete in <100ms)
time node scripts/status-line-fast.cjs

# Force full refresh
node scripts/combined-status-line.js

# Check for process spawn storm (should be <80 Node processes)
ps aux | grep node | wc -l

# If >100 processes, kill the coordinator and let GPS restart cleanly
ps aux | grep global-service-coordinator | grep -v grep

Status line not updating?¶

# Check the coordinator (Phase 33 SoT)
curl -fs http://localhost:3034/health/state | jq '.generated_at, .lsl_by_project'

# Trigger an explicit one-shot verifier run (writes a verify_run signal to coordinator)
node scripts/health-verifier.js verify

# Force a fresh render (clears the per-project cache)
rm -f .logs/combined-status-line-cache-*.txt
node scripts/combined-status-line.js

Note: there is no longer a host-side health-verifier daemon. verify, status, and report are the only supported subcommands; start was removed in plan 33-04 when the coordinator at :3034 took over lifecycle. If you still see a monitoring:health-verifier STOPPED line on the dashboard, your supervisord config is pre-Phase-33 — the program block was retired alongside browser-access.

Wrong project showing as active?¶

# Check LSL registry
cat .lsl/global-registry.json | jq '.'

# Verify activity timestamps
cat .lsl/global-registry.json | jq '.sessions[] | {project, last_activity}'

Session not showing that should be?¶

# Check if agent process is detected (claude, copilot, opencode)
ps -eo pid,comm | awk '/claude$|copilot$|opencode$/ {print}'

# Check if the agent's cwd resolves to the right project
lsof -p <PID> 2>/dev/null | grep cwd

# Check if transcript monitor is running for that project
ps aux | grep enhanced-transcript-monitor | grep PROJECT_NAME

# Sessions show if: agent process running OR transcript monitor running

Right edge shows residual chars (e.g. 12:411, 13:0656)?¶

The persistent fix is set -g codepoint-widths "..." in ~/.tmux.conf — see Tmux codepoint-widths for the full mapping. Verify yours matches:

# Verify the override is loaded (should print 9 codepoints, all =2 or =0)
tmux show-options -g codepoint-widths

# If it's missing entirely, add the line from the docs and reload:
tmux source-file ~/.tmux.conf

If the override is present and residue still appears, a new emoji has entered the statusline repertoire whose width tmux doesn't know about. Probe its tmux-vs-terminal width with the snippet below — if truncate(1) returns the emoji itself (rather than empty), tmux is counting 1 cell and needs a U+XXXX=2 entry appended:

emoji_vs=$(node -e "process.stdout.write(String.fromCodePoint(0xXXXX) + String.fromCodePoint(0xFE0F) + 'XYZ')")
tmux set-environment -g TT "$emoji_vs"
for n in 1 2 3 4; do
  out=$(tmux display-message -p "#{=$n:TT}")
  printf "truncate(%d) = %q\n" "$n" "$out"
done

Do not modify scripts/combined-status-line.js's visibleCellWidth() to compensate — multiple past attempts (2026-05-09, 10, 12) introduced new disagreements. The script's count is correct for its repertoire; the fix is always in tmux config.

You can also verify the legacy script-side mitigations are still in place (they're defense-in-depth, not load-bearing now):

# Wrapper preserves trailing whitespace (must NOT do .trim())
grep -n 'rstrip\|trim()' scripts/combined-status-line-wrapper.js

# Producer pads to TMUX_PANE_WIDTH (or 200) via leftPadToStableCellWidth
grep -n 'leftPadToStableCellWidth' scripts/combined-status-line.js

# Cache file isn't truncated mid-codepoint
xxd .logs/combined-status-line-cache-coding-w*.txt | tail -1

Key Files¶

Core System:

Retired (do not write/read):

Configuration: