whats-cc-doing 0.2.0__tar.gz

whats_cc_doing-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+.work/
+__pycache__/
+*.pyc
+.venv/
+reports/
+dist/
+.pytest_cache/
+.ruff_cache/
+.ccdoing/
+ccdoing.yaml.bak
+.claude/

whats_cc_doing-0.2.0/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-08-30
+
+Second live-install round: fixed the TUI arrow keys (escape sequences
+were split by buffered stdin reads - raw-fd reads + a pure decoder now;
+j/k work too), renamed the side-by-side web feature to Multi-view
+(`/multi`), added daemonized serving (`ccdoing serve --all --daemon`,
+`serve stop`, `serve status`, pidfile-tracked with restart semantics and
+prominent URLs), a `python -m whats_cc_doing` entry point, a setup-skill
+phase that offers to start the web server, new `/ccdoing:serve` and
+`/ccdoing:help` skills, and a skill-level CLI-vs-plugin version check
+(a stale installed build bit the second live test).
+
+Publish-readiness pass from an independent code review: `serve --daemon`
+forwards the resolved `--config` to its respawned child (it previously
+resolved config from the child's cwd); escalation-tier retry semantics
+are a structured `retryable` flag on ActionResult instead of matching
+detail-string wording (a transient nudge launch failure no longer
+consumes the tier for the whole quiet episode); quiet duration persists
+correctly across ticks; drift bookkeeping keys can no longer collide for
+duplicate type:label signal pairs; concurrent ticks write unique temp
+files; cron/systemd install output quotes spaced paths; sdist excludes
+keep dev files, lockfiles, and the author's local config out of the
+published tarball; README links work on PyPI; the setup skill installs
+the CLI from the plugin root first (works before and after PyPI
+publication).
+
+## [0.1.0] - 2026-08-29
+
+E2E dry-run polish (pre-release): manifests corrected to the nudge-only
+design (no more "resume-first" phrasing anywhere), local-checkout install
+path documented, `init` suggests a masquerade-proof `min_items` for
+json_headline, unambiguous notify dry-run wording, doctor tick labels,
+and relative-path/pgrep-self-match cautions in the skills and example
+config.
+
+First release. Extracted and generalized from a larger private
+project's internal status page, then hardened by a five-agent review
+round (adversarial code review, real-project field test, release audit)
+before ever being published - see BUILD-LOG.md for that story.
+
+### Added
+
+- Persistent notify targets (2026-08-30, from the first live install
+  test): notification URLs now live in `.ccdoing/notify.urls` (one
+  apprise URL per line, `#` comments), read on every tick so
+  cron/systemd watchdogs need no environment plumbing;
+  `$CCDOING_NOTIFY_URLS` overrides the file when set. `ccdoing init`
+  scaffolds the file and suggests `.gitignore` coverage;
+  `test-escalation --tier notify` prints the resolved source, target
+  URLs, and ntfy subscribe links. The setup skill now shows the
+  topic/subscribe link BEFORE any test notification and prints the full
+  nudge message before asking for approval, offers to start
+  not-yet-running services before the verification tick, and offers
+  "browser notifications" as a transport.
+- Browser notifications (2026-08-30): opt-in, pure viewer-side toggle on
+  the status page and the dashboard - fires on verdict transitions
+  (into QUIET/DOWN/STUCK and on recovery to ACTIVE) while a page is
+  open; per-project last-seen state in localStorage, feature-detected
+  (hidden on `file://`).
+- All-projects dashboard (2026-08-30): `ccdoing view` outside a project
+  (or `--dash`) lists every registered project with recent activity -
+  title, colored verdict, "Last signal: X ago", `[stale]` when the
+  generator stopped - with arrow/Enter navigation into any project's
+  live view and back, a live day-range control (`d`, default 4 days),
+  and split panes on wide terminals; `ccdoing serve --all` is the web
+  twin - cards linking to each project's real page at `/p/<name>/`, a
+  client-side "active within N days" filter, and `/multi` (Multi-view) for 2-4
+  status pages side by side. Registered names only; per-project output
+  dirs only; no-store everywhere.
+- Ten passive signal types (git, process, file_mtime, http, log_tail,
+  jsonl_log, claude_session, json_headline, ci, command) with a
+  never-raise contract. `json_headline` (added 2026-08-30, straight from
+  a staleness hit in the original internal version) reads headline metrics from
+  result JSONs by glob pattern - newest full run wins, `min_items` keeps
+  partial saves from masquerading as the battery.
+- Config-drift detection: per-signal `state` (ok / no-match / stale) in
+  status.json and on the page, a `maintenance` summary, `ccdoing doctor
+  --drift` (inventory re-diff + dead-signal report; `--quiet` one-liner
+  wired into the session-start hook), and the `/ccdoing:tune` skill that
+  turns findings into approved config deltas.
+- The harness adapter: semantic classification of Claude Code sessions
+  (WORKING / WAITING_ON / DEAD_WAIT / ABANDONED / IDLE) from on-disk
+  artifacts - timestamps, types, and ids only, never transcript content.
+- ACTIVE / QUIET / DOWN / STUCK verdict with cause attribution;
+  status.json as the machine interface beside the auto-refreshing
+  status.html.
+- Watchdog escalation ladder (log -> notify via apprise -> nudge), with
+  rails enforced in code: cooldown, daily cap, single-flight lock,
+  fenced-untrusted evidence bundles, hostile-session-id rejection.
+  Tier 3 is a nudge, never a resume: one informational cross-session
+  message (user-approved template) into a session that is provably
+  parked on dead work AND provably still running - the session decides;
+  finished sessions sitting open overnight are healthy and left alone.
+  Before any nudge, an idle probe (a pure notify_when_idle
+  subscription, zero cost to the watched session) checks whether the
+  session is simply finished - idle means healthy, stand down, budget
+  untouched.
+  (Redesigned 2026-08-30 from the original resume-first approach after
+  Nick's feedback; the healthchecks.io relay was dropped the same day -
+  the page now self-detects a stopped generator with a stale banner, and
+  systemd Restart=/cron re-entry recover the loop itself.)
+- Page UI (2026-08-30): configurable `title:` (setup picks it; plain
+  "What's CC Doing" fallback), local human-readable times by default
+  (`timezone:` option), ages like "19h 8m", an at-a-glance activity
+  table of primary signals (ACTIVE green / inactive grey, drift-marked)
+  with the full weight-sorted table behind an All-signals expander.
+- Session discovery by recorded working directory (2026-08-30): sessions
+  launched in a parent directory that work on this project are found;
+  session names (/rename), pid-reuse-safe process liveness, and active
+  subagent labels shown from dedicated metadata stores. No todo/progress
+  bars - Claude Code persists no todo store to disk, so none is faked.
+- Terminal + serving story (2026-08-30): `ccdoing view` (ANSI live
+  viewer for ssh/headless, --fresh/--once), `ccdoing serve` (localhost
+  static server, Cache-Control: no-store on every response), and a
+  multi-project registry (`ccdoing projects`, `view --project NAME`).
+- CLI: init (with --write-nudge-message), tick, run, status, view,
+  serve, projects, doctor (--arm-check), test-escalation, install
+  (systemd/cron with absolute paths).
+- Claude Code plugin: setup / status / live skills, SessionStart
+  arm-check hook, self-hosting marketplace manifest.
+- Privacy defaults: process command lines redacted on rendered pages;
+  path-scoped process patterns generated by init.
+- CI: 3.11-3.13 test matrix. (The self-monitoring GitHub Pages
+  workflow was removed 2026-08-30 - a live-published status page makes
+  no sense for installers; a committed example + screenshot replace it.)

whats_cc_doing-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Rotundo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whats_cc_doing-0.2.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.5
+Name: whats-cc-doing
+Version: 0.2.0
+Summary: Passive status page + watchdog for Claude Code sessions: see what Claude is doing from observed side effects (git, processes, task files), detect stalls, and deliver the diagnosis into a provably stuck session as an informational nudge - never a resume or restart.
+Project-URL: Homepage, https://github.com/nickjrotundo/whats-cc-doing
+Project-URL: Repository, https://github.com/nickjrotundo/whats-cc-doing
+Project-URL: Issues, https://github.com/nickjrotundo/whats-cc-doing/issues
+Project-URL: Changelog, https://github.com/nickjrotundo/whats-cc-doing/blob/main/CHANGELOG.md
+Author: Nick Rotundo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,monitoring,status-page,watchdog
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: apprise>=1.7
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# What's CC Doing
+
+[![tests](https://github.com/nickjrotundo/whats-cc-doing/actions/workflows/tests.yml/badge.svg)](https://github.com/nickjrotundo/whats-cc-doing/actions/workflows/tests.yml)
+
+**A passive status page + watchdog for Claude Code sessions. Nothing
+self-reports, so nothing can lie about being alive.**
+
+`ccdoing` regenerates a status page (HTML for you, JSON for agents) from
+*observed side effects* - git commits, the process table, file mtimes,
+Claude Code's own on-disk session artifacts - and renders one verdict:
+
+| Verdict | Meaning |
+|---|---|
+| `ACTIVE` | a primary signal moved inside the window |
+| `QUIET`  | nothing has moved - possibly stalled (with per-signal ages) |
+| `DOWN`   | a health check is failing |
+| `STUCK`  | a session appears parked on dead work - with the evidence attached |
+
+When QUIET persists, an escalation ladder takes over: log, then notify,
+then - if you opt in - a **nudge**: one informational message into a
+session provably parked on dead work, ending with "ignore this if
+you're fine." The watchdog never restarts or resumes anything - only
+the session knows whether it still has work, so the session decides. A
+finished session sitting open overnight is healthy and is left alone.
+
+## Why this exists
+
+A long-running Claude Code subagent was off doing testing, and the TUI
+gave no visual feedback about whether it was working or hung. It *was*
+working - but the only way to see that was activity signals the TUI
+doesn't show: fresh task output files, transcript growth, processes in
+the table. This page began as visual proof of background work; the
+watchdog came later, after a session-level watchdog lapsed at handoff
+and a human manually checking `git log` caught an agent waiting forever
+on a notification that could never arrive.
+
+Two lessons became design decisions: any arming step someone must
+remember will eventually be skipped (so the loop is OS-level
+systemd/cron, re-checked at session start), and self-reported liveness
+is worthless for stuck agents (so nothing here is instrumented or
+subscribed - side effects don't lie). Full origin story:
+[BUILD-LOG.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/BUILD-LOG.md).
+
+## The harness adapter (the interesting part)
+
+The `claude_session` signal classifies every Claude Code session of a
+project semantically, from artifacts Claude Code already writes:
+
+- `WORKING` - transcript actively growing
+- `WAITING_ON` - parked on background task(s) still producing output, or
+  whose output file a process still holds open (legitimate; not flagged)
+- `DEAD_WAIT` - parked on task(s) whose output stopped moving past
+  threshold, with no sign of a live producer -> verdict `STUCK`, with the
+  evidence attached
+- `ABANDONED` - would be DEAD_WAIT, but the session has been inactive
+  past `stuck_max_age_minutes` (default 120) - informational only; a
+  long-dead session is never called STUCK or nudged
+- `IDLE` - nothing pending
+
+`DEAD_WAIT` is evidence-based inference, not proof - the "waiting on a
+notification that can never arrive" case heartbeat monitors structurally
+cannot see. Sessions are matched by where they *work* (their recorded
+working directory), not just where they started, and the page shows
+session names, process liveness, and active subagent labels when
+available - never transcript content. Mechanics and tradeoffs:
+[DESIGN.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/DESIGN.md);
+honest limits (activity is not progress):
+[ANALYSIS.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/ANALYSIS.md).
+
+## Install & use (Claude Code)
+
+Claude Code is the supported way to use this tool:
+
+```
+/plugin marketplace add nickjrotundo/whats-cc-doing
+/plugin install ccdoing@whats-cc-doing
+```
+
+Then run the **setup** skill (`/ccdoing:setup`) in your project: Claude
+inventories it, proposes signals, asks four questions, writes
+`ccdoing.yaml`, installs the watchdog loop, fires a test notification
+so you see the alert channel work *now* rather than at 3am, and - if
+you enable tier 3 - shows you the complete nudge message for approval
+first. Day to day: `/ccdoing:status`, `/ccdoing:serve`, `/ccdoing:live`,
+`/ccdoing:help`.
+
+The CLI underneath - install from PyPI (`uv tool install
+whats-cc-doing`), from the repo (`uv tool install
+git+https://github.com/nickjrotundo/whats-cc-doing`), or from a local
+checkout (`uv pip install /path/to/whats-cc-doing` in a venv):
+
+```
+ccdoing init              # inventory this project, write ccdoing.yaml
+ccdoing tick              # one cycle: collect, render, escalate (cron-safe)
+ccdoing run               # the same, in a loop
+ccdoing status [--fresh]  # print the verdict JSON to stdout
+ccdoing view [--fresh]    # live terminal viewer (ssh/headless friendly)
+ccdoing serve --all --daemon  # background web server for the dashboard (prints link)
+ccdoing serve stop|status # stop the web server / is it running + where
+ccdoing projects          # every registered project + last verdict
+ccdoing doctor            # env/config checks; --drift for config rot
+ccdoing test-escalation --tier log|notify|nudge   # prove the ladder works
+ccdoing install [--mode cron]                      # print install units
+```
+
+The CLI runs without Claude Code (generic signals work on any repo or
+long-running job), but that path is untested and unsupported - you're
+on your own, but feel free to try.
+
+## The escalation ladder
+
+```yaml
+watchdog:
+  escalation:
+    - { after_quiet_minutes: 15, action: log }
+    - { after_quiet_minutes: 30, action: notify }        # apprise -> anywhere
+    - { after_quiet_minutes: 45, action: nudge,
+        cooldown_minutes: 60, max_per_day: 3 }
+```
+
+Notify targets persist in **`.ccdoing/notify.urls`** - one
+[apprise](https://github.com/caronc/apprise) URL per line, read on
+every tick, so a cron/systemd watchdog needs no environment plumbing
+(`$CCDOING_NOTIFY_URLS` overrides it for one-off tests; keep the file
+gitignored - topics and webhooks are effectively secrets). Prefer no
+external service? The status page and dashboard carry an **"enable
+browser notifications"** toggle - viewer-side, fires on verdict
+transitions, works over `ccdoing serve` while a page is open.
+
+Tier 3 is a **nudge, never a resume**: only for a `DEAD_WAIT` session
+whose process is verifiably alive and which a zero-cost [idle
+probe](https://code.claude.com/docs/en/cross-session-messaging) did not
+report idle (idle means finished - the probe stands the watchdog down).
+One courier delivers your pre-approved message into the running
+session, which decides for itself. No `--resume`, no fresh sessions;
+cooldown, daily cap, and refuse-while-running are enforced in code.
+
+Who watches the watchdog? The page itself: it shows a red "generator
+appears down" banner when it misses its own refresh, and systemd
+`Restart=`/cron re-entry are the loop's recovery.
+
+## Outputs
+
+- `reports/status/status.html` - dark, dependency-free, auto-refreshing.
+  Default view is the at-a-glance **activity table** (green ACTIVE /
+  grey inactive per primary signal, drift-marked when misconfigured);
+  full detail sits behind an "All signals" expander.
+- `reports/status/status.json` - **the interface.** Agents and scripts
+  read this; nothing should ever scrape the HTML.
+
+![example status page](https://raw.githubusercontent.com/nickjrotundo/whats-cc-doing/main/docs/status-example.png)
+
+Real files in [examples/](https://github.com/nickjrotundo/whats-cc-doing/tree/main/examples) -
+this repository monitoring itself.
+
+### Viewing the page (headless / remote / WSL2)
+
+1. **`ccdoing serve --all --daemon`** - background server for the
+   all-projects dashboard; prints the localhost URL. `serve stop` /
+   `serve status` manage it; starting again restarts. WSL2: localhost
+   forwarding to the Windows browser usually works, but not always - if
+   it doesn't, open the URL in a Linux browser (e.g. WSLg-launched
+   Chrome).
+2. **`ccdoing view`** - live terminal viewer over ssh (`--fresh` to
+   generate as it views, `--once` for scripts).
+3. **Open the file** - `file://` works fully in Chromium-family
+   browsers - or serve `reports/status/` from your app's own static
+   mount with caching disabled (a cached status page is a lying one).
+
+Many projects on one machine? `init` registers each; `ccdoing projects`
+lists them with last verdicts (`--unregister NAME` to remove); each runs
+its own independent loop - one registry, one viewer, no per-project
+ports. And there is an **all-projects dashboard**, terminal and web:
+
+- **TUI**: `ccdoing view --dash` (the default outside any configured
+  project) - title, colored verdict, "Last signal: 12m ago" per
+  project; arrows + Enter open one, `b` comes back, `d` sets the
+  activity window, `s` splits side-by-side on wide terminals, `[stale]`
+  marks dead generators.
+
+  ![TUI dashboard: all projects with verdicts and last-signal ages](https://raw.githubusercontent.com/nickjrotundo/whats-cc-doing/main/docs/tui-dashboard.png)
+
+  The `s` split mode, three projects at once:
+
+  ![TUI multi-view: three project panes with per-signal states](https://raw.githubusercontent.com/nickjrotundo/whats-cc-doing/main/docs/tui-multiview.png)
+
+- **Web**: `ccdoing serve --all` - card-per-project dashboard with a
+  live "active within N days" filter, click-through to each live status
+  page, and a Multi-view grid of 2-4 pages at `/multi`. Localhost-only
+  by default; every response is `Cache-Control: no-store`.
+
+Privacy note before publishing a page anywhere public: `process`
+signals render command lines, redacted by default (`PID basename
+(+N args)`); the `command` signal's stdout renders too - treat
+`ccdoing.yaml` as config-as-code.
+
+## Keeping the page honest as the project changes
+
+The original internal status page hardcoded two `/tmp` eval-JSON paths
+and went stale the day after shipping. ccdoing is built to notice that
+class of rot: `json_headline` signals use glob patterns + a `min_items`
+shape filter (newest matching file wins); every path-shaped signal
+reports `no-match`/`stale` drift states on the page and in status.json;
+`ccdoing doctor --drift` re-diffs the setup-time inventory (the plugin
+surfaces a one-line notice at session start); and **`/ccdoing:tune`**
+turns findings into config *deltas* for approval - never rewriting
+values you tuned.
+
+## Supported platforms
+
+| Platform | Status |
+|---|---|
+| Linux | supported (developed and tested here) |
+| WSL2 | supported (`systemctl --user` varies - setup verifies, cron fallback) |
+| macOS | best-effort: generic signals work; Claude task outputs may live under `$TMPDIR` rather than `/tmp/claude-*` - set `task_root_glob` on the `claude_session` signal; use cron (no launchd template yet) |
+| Windows (native) | unsupported (`pgrep`, POSIX paths, systemd/cron assumptions) |
+
+## Docs & support
+
+- [DESIGN.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/DESIGN.md) - architecture, harness mechanics, decision log
+- [ANALYSIS.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/ANALYSIS.md) - known gaps, limits, v0.2 roadmap
+- [BUILD-LOG.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/BUILD-LOG.md) - origin story + how this was built (an AI-driven build, documented honestly)
+- [CHANGELOG.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/CHANGELOG.md) - release history
+- Questions/bugs: [GitHub Issues](https://github.com/nickjrotundo/whats-cc-doing/issues)

whats_cc_doing-0.2.0/README.md

@@ -0,0 +1,224 @@
+# What's CC Doing
+
+[![tests](https://github.com/nickjrotundo/whats-cc-doing/actions/workflows/tests.yml/badge.svg)](https://github.com/nickjrotundo/whats-cc-doing/actions/workflows/tests.yml)
+
+**A passive status page + watchdog for Claude Code sessions. Nothing
+self-reports, so nothing can lie about being alive.**
+
+`ccdoing` regenerates a status page (HTML for you, JSON for agents) from
+*observed side effects* - git commits, the process table, file mtimes,
+Claude Code's own on-disk session artifacts - and renders one verdict:
+
+| Verdict | Meaning |
+|---|---|
+| `ACTIVE` | a primary signal moved inside the window |
+| `QUIET`  | nothing has moved - possibly stalled (with per-signal ages) |
+| `DOWN`   | a health check is failing |
+| `STUCK`  | a session appears parked on dead work - with the evidence attached |
+
+When QUIET persists, an escalation ladder takes over: log, then notify,
+then - if you opt in - a **nudge**: one informational message into a
+session provably parked on dead work, ending with "ignore this if
+you're fine." The watchdog never restarts or resumes anything - only
+the session knows whether it still has work, so the session decides. A
+finished session sitting open overnight is healthy and is left alone.
+
+## Why this exists
+
+A long-running Claude Code subagent was off doing testing, and the TUI
+gave no visual feedback about whether it was working or hung. It *was*
+working - but the only way to see that was activity signals the TUI
+doesn't show: fresh task output files, transcript growth, processes in
+the table. This page began as visual proof of background work; the
+watchdog came later, after a session-level watchdog lapsed at handoff
+and a human manually checking `git log` caught an agent waiting forever
+on a notification that could never arrive.
+
+Two lessons became design decisions: any arming step someone must
+remember will eventually be skipped (so the loop is OS-level
+systemd/cron, re-checked at session start), and self-reported liveness
+is worthless for stuck agents (so nothing here is instrumented or
+subscribed - side effects don't lie). Full origin story:
+[BUILD-LOG.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/BUILD-LOG.md).
+
+## The harness adapter (the interesting part)
+
+The `claude_session` signal classifies every Claude Code session of a
+project semantically, from artifacts Claude Code already writes:
+
+- `WORKING` - transcript actively growing
+- `WAITING_ON` - parked on background task(s) still producing output, or
+  whose output file a process still holds open (legitimate; not flagged)
+- `DEAD_WAIT` - parked on task(s) whose output stopped moving past
+  threshold, with no sign of a live producer -> verdict `STUCK`, with the
+  evidence attached
+- `ABANDONED` - would be DEAD_WAIT, but the session has been inactive
+  past `stuck_max_age_minutes` (default 120) - informational only; a
+  long-dead session is never called STUCK or nudged
+- `IDLE` - nothing pending
+
+`DEAD_WAIT` is evidence-based inference, not proof - the "waiting on a
+notification that can never arrive" case heartbeat monitors structurally
+cannot see. Sessions are matched by where they *work* (their recorded
+working directory), not just where they started, and the page shows
+session names, process liveness, and active subagent labels when
+available - never transcript content. Mechanics and tradeoffs:
+[DESIGN.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/DESIGN.md);
+honest limits (activity is not progress):
+[ANALYSIS.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/ANALYSIS.md).
+
+## Install & use (Claude Code)
+
+Claude Code is the supported way to use this tool:
+
+```
+/plugin marketplace add nickjrotundo/whats-cc-doing
+/plugin install ccdoing@whats-cc-doing
+```
+
+Then run the **setup** skill (`/ccdoing:setup`) in your project: Claude
+inventories it, proposes signals, asks four questions, writes
+`ccdoing.yaml`, installs the watchdog loop, fires a test notification
+so you see the alert channel work *now* rather than at 3am, and - if
+you enable tier 3 - shows you the complete nudge message for approval
+first. Day to day: `/ccdoing:status`, `/ccdoing:serve`, `/ccdoing:live`,
+`/ccdoing:help`.
+
+The CLI underneath - install from PyPI (`uv tool install
+whats-cc-doing`), from the repo (`uv tool install
+git+https://github.com/nickjrotundo/whats-cc-doing`), or from a local
+checkout (`uv pip install /path/to/whats-cc-doing` in a venv):
+
+```
+ccdoing init              # inventory this project, write ccdoing.yaml
+ccdoing tick              # one cycle: collect, render, escalate (cron-safe)
+ccdoing run               # the same, in a loop
+ccdoing status [--fresh]  # print the verdict JSON to stdout
+ccdoing view [--fresh]    # live terminal viewer (ssh/headless friendly)
+ccdoing serve --all --daemon  # background web server for the dashboard (prints link)
+ccdoing serve stop|status # stop the web server / is it running + where
+ccdoing projects          # every registered project + last verdict
+ccdoing doctor            # env/config checks; --drift for config rot
+ccdoing test-escalation --tier log|notify|nudge   # prove the ladder works
+ccdoing install [--mode cron]                      # print install units
+```
+
+The CLI runs without Claude Code (generic signals work on any repo or
+long-running job), but that path is untested and unsupported - you're
+on your own, but feel free to try.
+
+## The escalation ladder
+
+```yaml
+watchdog:
+  escalation:
+    - { after_quiet_minutes: 15, action: log }
+    - { after_quiet_minutes: 30, action: notify }        # apprise -> anywhere
+    - { after_quiet_minutes: 45, action: nudge,
+        cooldown_minutes: 60, max_per_day: 3 }
+```
+
+Notify targets persist in **`.ccdoing/notify.urls`** - one
+[apprise](https://github.com/caronc/apprise) URL per line, read on
+every tick, so a cron/systemd watchdog needs no environment plumbing
+(`$CCDOING_NOTIFY_URLS` overrides it for one-off tests; keep the file
+gitignored - topics and webhooks are effectively secrets). Prefer no
+external service? The status page and dashboard carry an **"enable
+browser notifications"** toggle - viewer-side, fires on verdict
+transitions, works over `ccdoing serve` while a page is open.
+
+Tier 3 is a **nudge, never a resume**: only for a `DEAD_WAIT` session
+whose process is verifiably alive and which a zero-cost [idle
+probe](https://code.claude.com/docs/en/cross-session-messaging) did not
+report idle (idle means finished - the probe stands the watchdog down).
+One courier delivers your pre-approved message into the running
+session, which decides for itself. No `--resume`, no fresh sessions;
+cooldown, daily cap, and refuse-while-running are enforced in code.
+
+Who watches the watchdog? The page itself: it shows a red "generator
+appears down" banner when it misses its own refresh, and systemd
+`Restart=`/cron re-entry are the loop's recovery.
+
+## Outputs
+
+- `reports/status/status.html` - dark, dependency-free, auto-refreshing.
+  Default view is the at-a-glance **activity table** (green ACTIVE /
+  grey inactive per primary signal, drift-marked when misconfigured);
+  full detail sits behind an "All signals" expander.
+- `reports/status/status.json` - **the interface.** Agents and scripts
+  read this; nothing should ever scrape the HTML.
+
+![example status page](https://raw.githubusercontent.com/nickjrotundo/whats-cc-doing/main/docs/status-example.png)
+
+Real files in [examples/](https://github.com/nickjrotundo/whats-cc-doing/tree/main/examples) -
+this repository monitoring itself.
+
+### Viewing the page (headless / remote / WSL2)
+
+1. **`ccdoing serve --all --daemon`** - background server for the
+   all-projects dashboard; prints the localhost URL. `serve stop` /
+   `serve status` manage it; starting again restarts. WSL2: localhost
+   forwarding to the Windows browser usually works, but not always - if
+   it doesn't, open the URL in a Linux browser (e.g. WSLg-launched
+   Chrome).
+2. **`ccdoing view`** - live terminal viewer over ssh (`--fresh` to
+   generate as it views, `--once` for scripts).
+3. **Open the file** - `file://` works fully in Chromium-family
+   browsers - or serve `reports/status/` from your app's own static
+   mount with caching disabled (a cached status page is a lying one).
+
+Many projects on one machine? `init` registers each; `ccdoing projects`
+lists them with last verdicts (`--unregister NAME` to remove); each runs
+its own independent loop - one registry, one viewer, no per-project
+ports. And there is an **all-projects dashboard**, terminal and web:
+
+- **TUI**: `ccdoing view --dash` (the default outside any configured
+  project) - title, colored verdict, "Last signal: 12m ago" per
+  project; arrows + Enter open one, `b` comes back, `d` sets the
+  activity window, `s` splits side-by-side on wide terminals, `[stale]`
+  marks dead generators.
+
+  ![TUI dashboard: all projects with verdicts and last-signal ages](https://raw.githubusercontent.com/nickjrotundo/whats-cc-doing/main/docs/tui-dashboard.png)
+
+  The `s` split mode, three projects at once:
+
+  ![TUI multi-view: three project panes with per-signal states](https://raw.githubusercontent.com/nickjrotundo/whats-cc-doing/main/docs/tui-multiview.png)
+
+- **Web**: `ccdoing serve --all` - card-per-project dashboard with a
+  live "active within N days" filter, click-through to each live status
+  page, and a Multi-view grid of 2-4 pages at `/multi`. Localhost-only
+  by default; every response is `Cache-Control: no-store`.
+
+Privacy note before publishing a page anywhere public: `process`
+signals render command lines, redacted by default (`PID basename
+(+N args)`); the `command` signal's stdout renders too - treat
+`ccdoing.yaml` as config-as-code.
+
+## Keeping the page honest as the project changes
+
+The original internal status page hardcoded two `/tmp` eval-JSON paths
+and went stale the day after shipping. ccdoing is built to notice that
+class of rot: `json_headline` signals use glob patterns + a `min_items`
+shape filter (newest matching file wins); every path-shaped signal
+reports `no-match`/`stale` drift states on the page and in status.json;
+`ccdoing doctor --drift` re-diffs the setup-time inventory (the plugin
+surfaces a one-line notice at session start); and **`/ccdoing:tune`**
+turns findings into config *deltas* for approval - never rewriting
+values you tuned.
+
+## Supported platforms
+
+| Platform | Status |
+|---|---|
+| Linux | supported (developed and tested here) |
+| WSL2 | supported (`systemctl --user` varies - setup verifies, cron fallback) |
+| macOS | best-effort: generic signals work; Claude task outputs may live under `$TMPDIR` rather than `/tmp/claude-*` - set `task_root_glob` on the `claude_session` signal; use cron (no launchd template yet) |
+| Windows (native) | unsupported (`pgrep`, POSIX paths, systemd/cron assumptions) |
+
+## Docs & support
+
+- [DESIGN.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/DESIGN.md) - architecture, harness mechanics, decision log
+- [ANALYSIS.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/ANALYSIS.md) - known gaps, limits, v0.2 roadmap
+- [BUILD-LOG.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/BUILD-LOG.md) - origin story + how this was built (an AI-driven build, documented honestly)
+- [CHANGELOG.md](https://github.com/nickjrotundo/whats-cc-doing/blob/main/CHANGELOG.md) - release history
+- Questions/bugs: [GitHub Issues](https://github.com/nickjrotundo/whats-cc-doing/issues)