@cullumco/cadence 0.1.0 → 0.1.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "cadence",
       "displayName": "Cadence",
-      "description": "Agents that read the room: embodied state, cadence dials, and conservative finish-line guardrails for Claude Code.",
+      "description": "Agents that read the room: embodied state, cadence dials, and conservative finish-line guardrails for Claude Code. macOS-only alpha.",
       "source": {
         "source": "npm",
         "package": "@cullumco/cadence"
@@ -21,7 +21,7 @@
         "agents",
         "claude-code"
       ],
-      "homepage": "https://github.com/cullumco/cadence",
+      "homepage": "https://cullumco.github.io/cadence/",
       "repository": "https://github.com/cullumco/cadence",
       "license": "MIT"
     }

package/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "cadence",
   "displayName": "Cadence",
-  "version": "0.1.0",
-  "description": "Ambient context for Claude Code: embodied signals, cadence dials, and finish-line guardrails.",
+  "version": "0.1.2",
+  "description": "Ambient context for Claude Code: embodied signals, cadence dials, and finish-line guardrails. macOS-only alpha.",
   "author": {
     "name": "Cullum&Co",
     "url": "https://cullum.co"
   },
-  "homepage": "https://github.com/cullumco/cadence",
+  "homepage": "https://cullumco.github.io/cadence/",
   "repository": "https://github.com/cullumco/cadence",
   "license": "MIT",
   "keywords": [

package/README.md

@@ -9,6 +9,9 @@ listening to, what you told it, how you want it to respond — into every prompt
 then asks Claude to *read your prompt through that lens*. The agent stops being
 deaf to the room.
 
+**macOS-only (alpha).** Most signals read the Mac around you; other platforms
+degrade to self-report + dials + time/git.
+
 A [Cullum&Co](https://cullum.co) project.
 
 ## What it does
@@ -34,14 +37,38 @@ It doesn't constrain the agent or rewrite your prompt — it gives the model the
 context your words are missing, and a lens for reading them. The lens always
 defers to what you actually typed.
 
+## Same prompt, different room
+
+> "how should I structure the retry logic?"
+
+**Without Cadence** — every prompt reads the same. You get the survey: four
+options, a trade-off table, and a closing "Would you like me to implement one
+of these?"
+
+**With Cadence, shipping cadence** — hardcore at 3 commits/hr, state set to
+`"ship mode"` → `{ pace=fast posture=decisive proactivity=act-freely }`. You
+get the call, made: exponential backoff with jitter, three attempts, here's
+the diff, tests pass.
+
+**With Cadence, thinking cadence** — ambient music, state set to
+`"thinking through tradeoffs"` → `{ pace=deliberate posture=exploratory }`.
+You get the options laid out patiently, trade-offs actually explored, no
+pressure to pick one yet.
+
+Same words. The room around them changed, and the agent finally saw it.
+
 ## How it works
 
 **Signals → dials → a reframe lens.**
 
 1. **Signals** — what Cadence can sense right now:
    - **ambient** — time of day, day of week, weather (opt-in), battery, machine
-     uptime/load, dark mode, displays, wifi. Mostly zero-setup, cross-platform.
-     The one signal that's always there: `context: friday afternoon, rainy`.
+     uptime/load, dark mode, displays, wifi, Focus/DND. Mostly zero-setup;
+     time/day work everywhere, the Mac-context probes are macOS. The one signal
+     that's always there: `context: friday afternoon, rainy, focus on`.
+     (Focus detection reads the DND database directly, so it needs your
+     terminal to have Full Disk Access — `cadence signals` tells you if it
+     doesn't.)
    - **git** — commits this hour, dirty files, mid-merge/rebase, read from the
      project you're in: `git: 6 dirty, mid-conflict`. Cross-platform.
    - **activity** — prompt length and minutes since your last prompt, read from
@@ -69,9 +96,11 @@ express.
 
 ## Requirements
 
-- **macOS** (the now-playing reader uses AppleScript against Spotify.app /
-  Music.app). The self-report and dials work everywhere; only the music signal
-  is macOS-only.
+- **macOS.** Cadence is mac-only for the alpha: music (AppleScript
+  now-playing), battery, dark mode, displays, wifi, and Focus/DND all read the
+  Mac around you. On other platforms it still runs — self-report, dials,
+  time/day, and git work anywhere, the rest degrade silently — but the product
+  is built for the Mac.
 - **Node 20+**
 - Claude Code for the alpha adapter
 
@@ -114,8 +143,14 @@ cadence state "two beers, shipping"   # set self-reported state (expires in 4h)
 cadence state                         # print current self-report
 cadence clear                         # clear it
 cadence test                          # preview exactly what the hook would inject
+cadence signals                       # every signal — live value, or why it's absent
 ```
 
+`cadence signals` is the legibility view: it never goes silent. Every signal
+Cadence knows how to read is listed with its live value, or the exact reason
+it's absent — opt-in not taken, below a render threshold, missing permission
+(Focus needs Full Disk Access), or platform-gated.
+
 From inside Claude Code, the plugin skill gives the same self-report path:
 
 ```text
@@ -184,17 +219,26 @@ the gate to run on every push to `main`.
 
 See [`BACKLOG.md`](BACKLOG.md). Highlights:
 
-- **More signals** — stronger `git` nudges, calendar density, wifi/place.
-  Git is the highest-value one: it moves the dials from *what you said* to *what
-  you're actually doing*.
+- **Git nudges** — the highest-value next step: built but dormant, they move
+  the dials from *what you said* to *what you're actually doing*.
+- **More signals** — candidates on the bench:
+  - **calendar density** — a meeting in 20 minutes should read as `pace=fast,
+    posture=decisive`; a clear afternoon as room to explore.
+  - **typing tempo** — prompt rhythm beyond length: rapid-fire short prompts vs.
+    one long considered one.
+  - **focused app** — what's frontmost next to the terminal (docs? a profiler?
+    Slack?).
+  - **scheduled Focus** — manual Focus detection ships now; scheduled/geofenced
+    Focus needs schedule math against `ModeConfigurations.json`.
 - **After-the-fact injection** — refine the cadence mid-task (`PostToolUse`),
   building on the conservative finish-line `Stop` guard that now ships.
 - **Opt-in flavor providers** — horoscope, moon phase, for those who want them.
 
 ## Caveats
 
-- **macOS-only music.** The now-playing reader is AppleScript. Other platforms
-  get self-report + dials, just no music vibe.
+- **macOS-only.** The alpha targets the Mac: music, battery, dark mode,
+  displays, wifi, and Focus are all macOS probes. Other platforms get
+  self-report + dials + time/git; everything else degrades silently.
 - **Spotify's Web API is not used** and not needed — Spotify deprecated audio
   features for new apps (2024) and gated dev-mode behind Premium (2026). Cadence
   reads what's playing at the OS level instead.

package/dist/cadence.js

@@ -96,6 +96,7 @@ export function deriveCadence(state) {
     // Candidate nudges, deliberately dormant until we've watched real output:
     //   conflicted → proactivity low (verify, don't barrel)
     //   commitsLastHour >= 3 → pace high (flow state)
+    //   ambient focus on → proactivity high (heads-down = fewer check-ins)
     // See BACKLOG: turn these on once the flavor proves trustworthy.
     void git;
     // ── activity → pace (returning from a break = slow back down) ─────────────

package/dist/cli.js

@@ -8,6 +8,7 @@ import { getAmbientSignal } from "./providers/ambient.js";
 import { getGitSignal } from "./providers/git.js";
 import { deriveCadence, buildReframe, loadOverrides, applyOverrides, resolveDialLevel, DIALS, DIAL_WORDS, } from "./cadence.js";
 import { render } from "./inject.js";
+import { renderSignalsTable } from "./signals-view.js";
 const CADENCE_DIR = join(homedir(), ".cadence");
 const STATE_FILE = join(CADENCE_DIR, "state.txt");
 const CONFIG_FILE = join(CADENCE_DIR, "config.json");
@@ -32,7 +33,9 @@ async function cmdClear() {
     await writeFile(STATE_FILE, "", "utf-8");
     console.log("  state cleared");
 }
-async function cmdTest() {
+// Collects live signals and renders the exact block the hook would inject,
+// or null when there's nothing to say. Shared by `test` and the bare command.
+async function buildPreview() {
     const signals = [];
     const [music, report, ambient, git, overrides] = await Promise.all([
         getMusicSignal().catch(() => null),
@@ -49,14 +52,33 @@ async function cmdTest() {
         signals.push(ambient);
     if (git)
         signals.push(git);
-    if (signals.length === 0 && Object.keys(overrides).length === 0) {
-        console.log('  (no signals — play something, set: cadence state "...", or pin a dial: cadence set pace fast)');
-        return;
-    }
+    if (signals.length === 0 && Object.keys(overrides).length === 0)
+        return null;
     const state = { signals, capturedAt: Date.now() };
     const { cadence, pinned } = applyOverrides(deriveCadence(state), overrides);
     const reframe = buildReframe(cadence);
-    console.log("\n" + render({ ...state, cadence, pinned, reframe }) + "\n");
+    return render({ ...state, cadence, pinned, reframe });
+}
+async function cmdTest() {
+    const block = await buildPreview();
+    if (!block) {
+        console.log('  (no signals — play something, set: cadence state "...", or pin a dial: cadence set pace fast)');
+        return;
+    }
+    console.log("\n" + block + "\n");
+}
+// The legibility view: every signal Cadence can read — live value, or the
+// reason it's absent. Unlike `test`, this never goes silent.
+async function cmdSignals() {
+    const [music, report, ambient, git] = await Promise.all([
+        getMusicSignal().catch(() => null),
+        getSelfReportSignal().catch(() => null),
+        getAmbientSignal(new Date()).catch(() => null),
+        getGitSignal(process.cwd()).catch(() => null),
+    ]);
+    console.log("\n" +
+        renderSignalsTable({ music, report, ambient, git, now: Date.now(), platform: process.platform }) +
+        "\n");
 }
 const LEVELS = ["low", "medium", "high"];
 async function cmdSet(args) {
@@ -150,14 +172,119 @@ async function cmdLocation(args) {
     await writeFile(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf-8");
     console.log(`  location set${nameParts.length ? ` (${nameParts.join(" ")})` : ""} — weather is now on`);
 }
+// Has the user ever told Cadence anything? (Signals like time-of-day always
+// exist, so "fresh install" is detected by absence of user INPUT, not signals.)
+async function hasUserInput() {
+    const [state, config] = await Promise.all([
+        readFile(STATE_FILE, "utf-8").catch(() => ""),
+        readFile(CONFIG_FILE, "utf-8").catch(() => "{}"),
+    ]);
+    let cfg = {};
+    try {
+        cfg = JSON.parse(config);
+    }
+    catch {
+        // unreadable config = no input
+    }
+    return state.trim().length > 0 || Object.keys(cfg).length > 0;
+}
+const INPUTS_FOOTER = `  where you can input:
+    cadence state "..."              how you are right now (4h TTL)
+    cadence set <dial> <level>       pin a dial: ${DIALS.join(", ")}
+    cadence set-location <lat> <lon> opt into weather
+    cadence start                    interactive setup
+    cadence help                     everything else`;
+// Bare \`cadence\`: live status + where to input — not a help dump.
+async function cmdRoot() {
+    if (!(await hasUserInput())) {
+        console.log("\n  cadence — agents that read the room");
+        console.log("  It hasn't heard from you yet. Fastest start:\n");
+        console.log('    cadence start              guided setup (~30s)');
+        console.log('    cadence state "ship mode"  or just say how you are\n');
+        return;
+    }
+    const block = await buildPreview();
+    if (block) {
+        console.log("\n" + block + "\n");
+    }
+    else {
+        console.log("\n  (no signals right now)\n");
+    }
+    console.log(INPUTS_FOOTER + "\n");
+}
+// Guided first run: three prompts, every one skippable, nothing destructive.
+async function cmdStart() {
+    if (!process.stdin.isTTY) {
+        console.log('  cadence start is interactive — run it in a terminal, or use: cadence state "..."');
+        return;
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("\n  cadence — agents that read the room");
+        console.log("  Three questions. Enter skips any of them; everything can be changed later.\n");
+        // 1 ── self-reported state: the highest-leverage input
+        const state = (await rl.question('  1/3  How are you right now? (e.g. "two beers, ship mode")\n       > ')).trim();
+        if (state) {
+            await mkdir(CADENCE_DIR, { recursive: true });
+            await writeFile(STATE_FILE, state, "utf-8");
+            console.log('       ✓ set — expires after 4h; update anytime: cadence state "..."\n');
+        }
+        else {
+            console.log('       skipped — later: cadence state "..."\n');
+        }
+        // 2 ── dial pins: overrides, so only offered, never pushed
+        console.log(`  2/3  Pin any dials? Pins override inference until unset.`);
+        console.log(`       dials: ${DIALS.join(", ")} — levels: low|medium|high`);
+        for (;;) {
+            const ans = (await rl.question('       pin (e.g. "pace high", enter to continue) > ')).trim();
+            if (!ans)
+                break;
+            const [dial, value] = ans.split(/\s+/);
+            if (!dial || !value || !DIALS.includes(dial)) {
+                console.log(`       format: <dial> <level>, dials: ${DIALS.join(", ")}`);
+                continue;
+            }
+            const d = dial;
+            const level = resolveDialLevel(d, value);
+            if (!level) {
+                console.log(`       "${value}" isn't valid for ${dial} — use low|medium|high`);
+                continue;
+            }
+            await cmdSet([dial, value]);
+        }
+        console.log();
+        // 3 ── weather: explicitly opt-in, mirrors cmdLocation's no-silent-geo rule
+        const loc = (await rl.question("  3/3  Weather? Give a location, or enter to leave it off.\n       lat lon [name] (e.g. 40.71 -74.01 NYC) > ")).trim();
+        if (loc) {
+            await cmdLocation(loc.split(/\s+/));
+        }
+        else {
+            console.log("       skipped — weather stays off until: cadence set-location <lat> <lon>");
+        }
+        console.log("\n  Done. Here's exactly what the hook injects right now:");
+        await cmdTest();
+    }
+    catch {
+        // Ctrl+D / Ctrl+C mid-wizard: every step saves as it goes, so an early
+        // exit just means "stop asking" — never an error, never a rollback.
+        console.log("\n  setup ended early — anything you answered is saved\n");
+    }
+    finally {
+        rl.close();
+    }
+}
 const HELP = `
   cadence — agents that read the room
 
   daily:
+    cadence                     live status + where to input
+    cadence start               guided setup (state, dials, weather — all skippable)
     cadence state "..."         set self-reported state (e.g. "two beers, ship mode")
     cadence state               print current self-reported state
     cadence clear               clear self-reported state
     cadence test                preview what the hook would inject right now
+    cadence signals             every signal — live value, or why it's absent
 
   dials (your determination — pinned dials override inference):
     cadence dials               show the mixing board and what's pinned
@@ -172,12 +299,16 @@ const HELP = `
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     switch (cmd) {
+        case "start":
+            return cmdStart();
         case "state":
             return cmdState(rest);
         case "clear":
             return cmdClear();
         case "test":
             return cmdTest();
+        case "signals":
+            return cmdSignals();
         case "set":
             return cmdSet(rest);
         case "unset":
@@ -187,6 +318,7 @@ async function main() {
         case "set-location":
             return cmdLocation(rest);
         case undefined:
+            return cmdRoot(); // live status + inputs, not the help dump
         case "help":
         case "--help":
         case "-h":

package/dist/debug.js

@@ -0,0 +1,17 @@
+/* ─────────────────────────────────────────────────────────────────────────
+ * CADENCE_DEBUG=1 surfaces swallowed provider errors on stderr.
+ *
+ * Providers are fail-silent by contract: a broken signal must degrade to
+ * "no signal," never break the hook. But fail-silent code can mask a
+ * 100%-reproducible bug (see: the AppleScript that never compiled). This
+ * is the escape hatch — stderr only, never stdout, because stdout is the
+ * hook protocol channel Claude Code parses.
+ *
+ *   CADENCE_DEBUG=1 node bin/cadence test
+ * ───────────────────────────────────────────────────────────────────────── */
+const DEBUG = process.env["CADENCE_DEBUG"] === "1" || process.env["CADENCE_DEBUG"] === "true";
+export function debug(scope, msg) {
+    if (!DEBUG)
+        return;
+    process.stderr.write(`[cadence:${scope}] ${msg}\n`);
+}

package/dist/hook.js

@@ -6,6 +6,7 @@ import { getGitSignal } from "./providers/git.js";
 import { getActivitySignal } from "./providers/activity.js";
 import { deriveCadence, buildReframe, loadOverrides, applyOverrides } from "./cadence.js";
 import { render } from "./inject.js";
+import { debug } from "./debug.js";
 const TOTAL_BUDGET_MS = 1500;
 // Claude Code alpha adapter: collect portable Cadence signals, derive the core
 // cadence state, then deliver it through UserPromptSubmit.additionalContext.
@@ -53,7 +54,10 @@ async function main() {
     const [signals, overrides] = await Promise.all([
         Promise.race([
             collectSignals(projectDir, prompt),
-            new Promise((resolve) => setTimeout(() => resolve([]), TOTAL_BUDGET_MS)),
+            new Promise((resolve) => setTimeout(() => {
+                debug("hook", `signal collection exceeded ${TOTAL_BUDGET_MS}ms budget — injecting without signals`);
+                resolve([]);
+            }, TOTAL_BUDGET_MS)),
         ]),
         loadOverrides(),
     ]);

package/dist/inject.js

@@ -51,6 +51,7 @@ function renderAmbient(a) {
         a.onBattery === true
             ? `unplugged${a.batteryPct != null ? ` ${a.batteryPct}%` : ""}`
             : null,
+        a.focus === true ? "focus on" : null,
         a.darkMode === true ? "dark mode" : null,
         a.displays != null && a.displays > 1 ? `${a.displays} displays` : null,
         a.network ? `on ${quote(a.network)}` : null,

package/dist/providers/ambient.js

@@ -22,6 +22,7 @@ function sh(cmd, ms = 500) {
  * "Put the vibes back into engineering": this is the atmosphere layer.
  * ───────────────────────────────────────────────────────────────────────── */
 const CONFIG_FILE = join(homedir(), ".cadence", "config.json");
+const DND_ASSERTIONS = join(homedir(), "Library", "DoNotDisturb", "DB", "Assertions.json");
 const WEATHER_TIMEOUT_MS = 900;
 const DAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
 function partOfDay(hour) {
@@ -62,19 +63,44 @@ function getVitals() {
     const load1 = loadavg()[0] ?? 0;
     return { uptimeHours, loadHigh: load1 / cores > 0.8 };
 }
+// Focus / DND — tri-state, read straight from the private donotdisturbd DB
+// (~1ms, no subprocess). Exported for the darwin smoke test.
+//   true      → a Focus mode is asserted (manually toggled on this device)
+//   false     → file read OK, no assertion records → focus is off
+//   undefined → unreadable: terminal lacks Full Disk Access (TCC denies the
+//               read silently — hook subprocesses never get a prompt), file
+//               moved, or shape changed → "unavailable", never "off"
+// Known gap: SCHEDULED/geofenced Focus writes no assertion record (detecting
+// it needs ModeConfigurations.json schedule math — backlogged).
+export async function getFocus() {
+    if (process.platform !== "darwin")
+        return undefined;
+    try {
+        const raw = await readFile(DND_ASSERTIONS, "utf-8");
+        const json = JSON.parse(raw);
+        const records = json.data?.[0]?.storeAssertionRecords;
+        return Array.isArray(records) && records.length > 0;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ── mac context: best-effort shell-outs, all flavor (no dial nudges) ─────────
 async function getMacContext() {
     if (process.platform !== "darwin")
         return {};
-    const [dark, ssid, displays] = await Promise.all([
+    const [dark, ssid, displays, focus] = await Promise.all([
         sh("defaults read -g AppleInterfaceStyle"), // "Dark", or error (=light)
         sh("ipconfig getsummary en0 | awk -F ' SSID : ' '/ SSID : / {print $2}'", 700),
         // fast display count via AppleScript (~100ms) — NOT system_profiler (1-3s)
         sh(`osascript -e 'tell application "System Events" to count of desktops'`, 700),
+        getFocus(),
     ]);
     const ctx = {};
-    if (dark != null)
-        ctx.darkMode = /dark/i.test(dark);
+    // `defaults read` exits non-zero when the key is unset — which is exactly
+    // what light mode looks like. So error/null ⇒ light, not unknown.
+    ctx.darkMode = dark != null && /dark/i.test(dark);
+    ctx.focus = focus;
     if (ssid)
         ctx.network = ssid.split("\n")[0]?.trim() || undefined;
     const n = displays ? Number(displays) : NaN;

package/dist/providers/music.js

@@ -1,8 +1,9 @@
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { tagsToVibe } from "../vibe.js";
+import { debug } from "../debug.js";
 /* ─────────────────────────────────────────────────────────────────────────
  * Music = identity + vibe. No Spotify Web API, no auth, no Premium.
  *
@@ -17,36 +18,66 @@ const CACHE_FILE = join(homedir(), ".cadence", "vibe-cache.json");
 const MB_TIMEOUT_MS = 1000;
 const MAX_TAGS = 4;
 const UA = "cadence/0.1 (https://github.com/cullumco/cadence)";
-// `application "X" is running` does NOT launch X — safe to probe.
-const SCRIPT = `
-on tryApp(appName)
-  if application appName is running then
-    tell application appName
-      if player state is playing then
-        return appName & "|||" & (name of current track) & "|||" & (artist of current track)
-      end if
-    end tell
-  end if
-  return ""
-end tryApp
-set r to tryApp("Spotify")
-if r is "" then set r to tryApp("Music")
-return r
+// Spotify first (matches historical priority), then Apple Music.
+const PLAYERS = ["Spotify", "Music"];
+/* The app name MUST be a literal inside the script: AppleScript resolves
+ * terms like `player state` against the target app's scripting dictionary
+ * at COMPILE time, so `tell application someVariable` is a guaranteed
+ * syntax error (-2741). One script per player, built from a template.
+ * Exported for the compile-check regression test. */
+export function playerScript(app) {
+    return `
+if application "${app}" is running then
+  tell application "${app}"
+    if player state is playing then
+      return (name of current track) & "|||" & (artist of current track)
+    end if
+  end tell
+end if
+return ""
 `;
-function osascript(script) {
+}
+/* Compiling `tell application "Spotify"` makes macOS locate the app — on a
+ * machine where it isn't installed that can pop a "Where is Spotify?"
+ * picker, from a background hook. pgrep the process list first so we only
+ * ever compile scripts for players that are actually running. */
+function isRunning(app) {
     return new Promise((resolve) => {
-        const child = exec(`osascript -e ${JSON.stringify(script)}`, { timeout: 800 }, (err, stdout) => resolve(err ? "" : stdout.trim()));
-        child.on("error", () => resolve(""));
+        const child = execFile("pgrep", ["-qx", app], { timeout: 500 }, (err) => resolve(!err));
+        child.on("error", () => resolve(false));
+    });
+}
+/* execFile, not exec: the script must reach osascript byte-for-byte as one
+ * argv entry. Routing it through a shell means a quoting layer (where `\n`
+ * inside double quotes stays a literal backslash-n — instant -2740). */
+export function osascript(script) {
+    return new Promise((resolve) => {
+        const child = execFile("osascript", ["-e", script], { timeout: 800 }, (err, stdout, stderr) => {
+            if (err)
+                debug("music", `osascript failed: ${stderr.trim() || err.message}`);
+            resolve(err ? "" : stdout.trim());
+        });
+        child.on("error", (e) => {
+            debug("music", `osascript spawn failed: ${e.message}`);
+            resolve("");
+        });
     });
 }
 async function getNowPlaying() {
-    const out = await osascript(SCRIPT);
-    if (!out)
-        return null;
-    const [player, track, artist] = out.split("|||");
-    if (!track || !artist)
-        return null;
-    return { track, artist, player: player ?? "" };
+    for (const player of PLAYERS) {
+        if (!(await isRunning(player))) {
+            debug("music", `${player} not running`);
+            continue;
+        }
+        const out = await osascript(playerScript(player));
+        if (!out)
+            continue; // running but paused/stopped (or script error, logged above)
+        const [track, artist] = out.split("|||");
+        if (!track || !artist)
+            continue;
+        return { track, artist, player };
+    }
+    return null;
 }
 async function loadCache() {
     try {
@@ -92,7 +123,8 @@ async function fetchTags(artist) {
             .slice(0, MAX_TAGS);
         return cleaned.length ? cleaned : null;
     }
-    catch {
+    catch (e) {
+        debug("music", `musicbrainz lookup failed for "${artist}": ${e instanceof Error ? e.message : String(e)}`);
         return null;
     }
     finally {

package/dist/providers/selfreport.js

@@ -2,7 +2,7 @@ import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const STATE_FILE = join(homedir(), ".cadence", "state.txt");
-const STALE_AFTER_MS = 4 * 60 * 60 * 1000;
+export const STALE_AFTER_MS = 4 * 60 * 60 * 1000;
 export async function getSelfReportSignal() {
     try {
         const [text, info] = await Promise.all([readFile(STATE_FILE, "utf-8"), stat(STATE_FILE)]);

package/dist/session-start.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { getMusicSignal } from "./providers/music.js";
+import { getSelfReportSignal } from "./providers/selfreport.js";
+import { loadOverrides } from "./cadence.js";
+import { debug } from "./debug.js";
+/* ─────────────────────────────────────────────────────────────────────────
+ * Claude Code SessionStart adapter: one short, human-facing line when a
+ * session opens — is Cadence live, what does it currently see, and where
+ * do you input state. Discoverability, not context: the per-prompt
+ * UserPromptSubmit hook owns what the MODEL sees; this line is for YOU
+ * (delivered via `systemMessage`, which Claude Code shows to the user).
+ *
+ * Fires on "startup" only (see hooks/hooks.json matcher) — not on resume
+ * or clear — so it reads as a greeting, not a nag.
+ * ───────────────────────────────────────────────────────────────────────── */
+const BUDGET_MS = 700;
+// The voice of the product's first impression. Return null to stay silent.
+// Default policy: always one line on startup — say what's seen when there
+// are signals, point at the inputs when there's nothing yet.
+export function composeHint(info) {
+    if (info.firstRun) {
+        return 'cadence: on, but it hasn\'t heard from you — try `cadence start` (or just `cadence state "deep work"`)';
+    }
+    const seen = [];
+    if (info.selfReport)
+        seen.push(`state "${info.selfReport}"`);
+    if (info.nowPlaying)
+        seen.push(`${info.nowPlaying.player}: ${info.nowPlaying.artist}`);
+    if (info.pinned.length)
+        seen.push(`pinned ${info.pinned.join(", ")}`);
+    if (seen.length === 0) {
+        return 'cadence: live, no signals right now — `cadence state "..."` to give it one';
+    }
+    return `cadence: live — ${seen.join(" · ")}  (inputs: cadence state | dials)`;
+}
+async function collectInfo() {
+    // Race music against the budget — MusicBrainz on a brand-new artist can
+    // be slow, and a session greeting must never delay the session.
+    const [report, overrides, music] = await Promise.all([
+        getSelfReportSignal().catch(() => null),
+        loadOverrides(),
+        Promise.race([
+            getMusicSignal().catch(() => null),
+            new Promise((resolve) => setTimeout(() => resolve(null), BUDGET_MS)),
+        ]),
+    ]);
+    const pinned = Object.keys(overrides);
+    return {
+        selfReport: report?.text ?? null,
+        pinned,
+        nowPlaying: music?.artist ? { artist: music.artist, player: music.player ?? "music" } : null,
+        firstRun: !report && pinned.length === 0,
+    };
+}
+async function main() {
+    const hint = composeHint(await collectInfo());
+    if (!hint)
+        process.exit(0); // same contract as the prompt hook: silent when empty
+    process.stdout.write(JSON.stringify({ systemMessage: hint }));
+}
+main().catch((err) => {
+    debug("session-start", err instanceof Error ? err.message : String(err));
+    process.exit(0); // greeting must never break a session
+});

package/dist/signals-view.js

@@ -0,0 +1,103 @@
+import { STALE_AFTER_MS } from "./providers/selfreport.js";
+const LABEL_W = 12; // sub-row label column
+const VALUE_W = 18; // value column, before a "(hidden: …)" note
+function row(label, value, note) {
+    const v = note ? `${value.padEnd(VALUE_W)} ${note}` : value;
+    return `    ${label.padEnd(LABEL_W)}${v}`;
+}
+function top(label, value) {
+    return `  ${label.padEnd(LABEL_W + 2)}${value}`;
+}
+function ttlLeft(setAt, now) {
+    const rem = Math.max(0, STALE_AFTER_MS - (now - setAt));
+    const h = Math.floor(rem / 3_600_000);
+    const m = Math.floor((rem % 3_600_000) / 60_000);
+    return h > 0 ? `${h}h${String(m).padStart(2, "0")}m left` : `${m}m left`;
+}
+function ambientRows(a, platform) {
+    if (!a)
+        return [top("ambient", "— unavailable")];
+    const mac = platform === "darwin";
+    const macNote = "— macOS only";
+    const lines = ["  ambient"];
+    lines.push(row("time", `${a.partOfDay} (${a.dayOfWeek})`));
+    lines.push(row("weather", a.weather ?? "— off (run: cadence set-location <lat> <lon>)"));
+    lines.push(!mac
+        ? row("battery", macNote)
+        : a.onBattery == null
+            ? row("battery", "— unavailable")
+            : a.onBattery
+                ? row("battery", `unplugged${a.batteryPct != null ? `, ${a.batteryPct}%` : ""}`)
+                : row("battery", `plugged in${a.batteryPct != null ? `, ${a.batteryPct}%` : ""}`, "(hidden: only shows unplugged)"));
+    lines.push(!mac
+        ? row("dark mode", macNote)
+        : a.darkMode == null
+            ? row("dark mode", "— unavailable")
+            : a.darkMode
+                ? row("dark mode", "on")
+                : row("dark mode", "off", "(hidden: only shows on)"));
+    lines.push(!mac
+        ? row("displays", macNote)
+        : a.displays == null
+            ? row("displays", "— unavailable")
+            : a.displays > 1
+                ? row("displays", String(a.displays))
+                : row("displays", String(a.displays), "(hidden: only shows >1)"));
+    lines.push(!mac
+        ? row("wifi", macNote)
+        : a.network
+            ? row("wifi", JSON.stringify(a.network))
+            : row("wifi", "— unavailable"));
+    lines.push(a.uptimeHours == null
+        ? row("uptime", "— unavailable")
+        : a.uptimeHours >= 12
+            ? row("uptime", `${a.uptimeHours}h`)
+            : row("uptime", `${a.uptimeHours}h`, "(hidden: only shows ≥12h)"));
+    lines.push(a.loadHigh
+        ? row("load", "high (machine busy)")
+        : row("load", "normal", "(hidden: only shows high)"));
+    lines.push(!mac
+        ? row("focus", macNote)
+        : a.focus == null
+            ? row("focus", "— unavailable (terminal needs Full Disk Access)")
+            : a.focus
+                ? row("focus", "on")
+                : row("focus", "off", "(hidden: only shows on)"));
+    return lines;
+}
+function musicRows(m) {
+    if (!m?.track)
+        return [top("music", "— nothing playing")];
+    const lines = ["  music"];
+    lines.push(row("track", `${JSON.stringify(m.track)}${m.artist ? ` — ${m.artist}` : ""}${m.player ? ` (${m.player})` : ""}`));
+    lines.push(m.vibe ? row("vibe", m.vibe) : row("vibe", "— no tags yet (looked up once per artist)"));
+    return lines;
+}
+function reportRow(r, now) {
+    if (!r)
+        return top("self_report", '— none set (run: cadence state "...")');
+    const text = r.text.length > 44 ? `${r.text.slice(0, 43)}…` : r.text;
+    return top("self_report", `${JSON.stringify(text)} (${ttlLeft(r.setAt, now)})`);
+}
+function gitRow(g) {
+    if (!g)
+        return top("git", "— not a git repo (signal is per-directory)");
+    const parts = [
+        g.commitsLastHour > 0
+            ? `${g.commitsLastHour} commit${g.commitsLastHour === 1 ? "" : "s"}/hr`
+            : null,
+        g.filesDirty > 0 ? `${g.filesDirty} dirty` : "clean tree",
+        g.minSinceLastCommit != null ? `last commit ${g.minSinceLastCommit}m ago` : null,
+        g.conflicted ? "mid-conflict" : null,
+    ].filter(Boolean);
+    return top("git", parts.join(", "));
+}
+export function renderSignalsTable(raw) {
+    return [
+        ...ambientRows(raw.ambient, raw.platform),
+        ...musicRows(raw.music),
+        reportRow(raw.report, raw.now),
+        gitRow(raw.git),
+        top("activity", "— session-only (the hook injects it per-prompt)"),
+    ].join("\n");
+}

package/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/session-start.js\""
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "matcher": "",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@cullumco/cadence",
-  "version": "0.1.0",
-  "description": "Agents that read the room. Ambient context, cadence dials, and finish-line guardrails for Claude Code.",
+  "version": "0.1.2",
+  "description": "Agents that read the room. Ambient context, cadence dials, and finish-line guardrails for Claude Code. macOS-only alpha.",
   "type": "module",
   "bin": {
     "cadence": "bin/cadence"
   },
-  "homepage": "https://github.com/cullumco/cadence",
+  "homepage": "https://cullumco.github.io/cadence/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cullumco/cadence.git"