@trygocode/notify 0.2.0 → 0.3.1

package/README.md

@@ -17,6 +17,7 @@ waiting for you**, **errors out**, or when an overnight **loop completes / halts
 - [Auto-push to git (opt-in)](#auto-push-to-git-opt-in)
 - [Settings sync — the `config` command](#settings-sync--the-config-command)
 - [Ralph/Homer opt-in snippet (trigger C)](#ralphhomer-opt-in-snippet-trigger-c)
+- [Notify from any custom script (the minimal one-liner)](#notify-from-any-custom-script-the-minimal-one-liner)
 - [Troubleshooting](#troubleshooting)
 - [Changelog](#changelog)
 - [Develop](#develop)
@@ -125,6 +126,21 @@ The installed rule/skill tells the agent **not** to call the MCP tool for
 done/idle/error pings — those are owned by the deterministic hook (A), so you
 never get double-pinged.
 
+> **Cursor `stop.status` → kind mapping (since 0.3.0).** Cursor's `stop` hook
+> carries a `status` field in its stdin JSON. The `on-stop` dispatcher maps it
+> to the right notification kind automatically:
+>
+> | Cursor `stop.status` | Notification kind | Meaning |
+> |---|---|---|
+> | `completed` | `finished` | Agent turned cleanly (default — same as before 0.3.0) |
+> | `aborted` | `awaiting_input` | Agent yielded back to you — may need your input |
+> | `error` | `error` | Agent hit an error |
+> | absent / unrecognised | `finished` | Back-compatible fallback |
+>
+> Before 0.3.0, Cursor only ever sent `finished` regardless of what the agent
+> did. The status mapping requires no hook re-installation — run
+> `gocode-notify setup --force` once to apply the updated hook command.
+
 > **OpenCode's hook (A)** is a small `session.idle` plugin written to
 > `~/.config/opencode/plugin/gocode-notify.js`; on each `session.idle` event it
 > fire-and-forgets `gocode-notify on-stop --source opencode` (the same
@@ -316,7 +332,7 @@ Valid keys (mirror of the canonical schema):
 
 | Key | Type | Meaning |
 |---|---|---|
-| `kinds.finished` / `kinds.error` / `kinds.awaiting_input` / `kinds.loop_completed` / `kinds.loop_halted` | bool | Per-kind notification toggles |
+| `kinds.finished` / `kinds.error` / `kinds.awaiting_input` / `kinds.loop_completed` / `kinds.loop_halted` / `kinds.ralph_waiting` | bool | Per-kind notification toggles |
 | `min_duration_seconds` | int ≥ 0 | Only notify if the turn ran ≥ N seconds (0 = always) |
 | `quiet_hours.enabled` / `quiet_hours.start` / `quiet_hours.end` / `quiet_hours.tz` | bool / `HH:MM` / `HH:MM` / IANA tz | Do-not-disturb window |
 | `auto_push.enabled` | bool | Master auto-push switch (OFF by default) |
@@ -358,6 +374,41 @@ The ready-to-copy version with comments lives at
 loop scripts. Both lines are fire-and-forget (`|| true` + the CLI's 5s
 self-timeout), so a failed or slow push can never block or fail your loop.
 
+## Notify from any custom script (the minimal one-liner)
+
+Any shell script — a cron job, a `Makefile` target, a post-build hook, or
+someone else's automation — can send a push with a single line, no configuration
+beyond a one-time `gocode-notify login` pairing:
+
+```bash
+gocode-notify send --kind finished --source <name> || true
+```
+
+Replace `<name>` with a short identifier for the script (e.g. `ci`, `build`,
+`deploy`). The `|| true` guard ensures a failed or slow push **never** blocks the
+calling script (the CLI also self-times-out in 5 seconds).
+
+> **Discovery hint:** `gocode-notify status` always prints this line at the
+> bottom of its report so you can copy-paste it even when you don't have the
+> README handy.
+
+**Other useful kinds for custom scripts:**
+
+| Kind | When to use |
+|---|---|
+| `finished` | Script completed cleanly |
+| `error` | Script hit an error |
+| `awaiting_input` | Script paused; a human is needed |
+| `loop_completed` | Long-running loop finished all work |
+| `loop_halted` | Long-running loop stopped; human needed |
+
+Pass `--title "My script"` and `--body "extra detail"` to customise the
+notification text. Use `--project "$(basename "$PWD")"` to badge it with the
+project name on your phone. All flags are optional — only `--kind` is required.
+
+See `snippets/ralph-homer.sh` for the full Ralph/Homer lifecycle pattern
+(completed / halted / stall-edge / resumed).
+
 ## Troubleshooting
 
 **Start here:** `gocode-notify status` prints a one-screen report — whether
@@ -389,6 +440,29 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.3.0
+
+- **New: Cursor `stop.status` → kind mapping (T-CUR1/T-CUR4).** The `on-stop`
+  dispatcher now reads the Cursor `stop` hook's stdin JSON and maps `status` to
+  the right notification kind: `completed→finished`, `aborted→awaiting_input`,
+  `error→error`. Back-compatible: absent/unrecognised status → `finished`.
+  Run `gocode-notify setup --force` to pick up the updated hook command.
+- **New: `ralph_waiting` + `ralph_resumed` kinds (T-C1).** `NOTIFY_KINDS` now
+  includes the Ralph/Homer offline-stall lifecycle kinds. `ralph_waiting` fires
+  once on the stall edge (server drops repeats until a recovery event re-arms
+  it); `ralph_resumed` is a silent control event that resets the stall state
+  machine. See `snippets/ralph-homer.sh` for the edge-trigger pattern.
+- **Kind taxonomy (T-S1).** The server now classifies every kind into push-worthy
+  vs. silent-info buckets: `ralph_question` / `ralph_advanced` are never pushed
+  (Oracle-answerable questions are silent); `ralph_halted` / `ralph_completed` /
+  `ralph_waiting` (edge) are the only loop kinds that reach FCM.
+- **Foreground suppression (T-S2/T-S3).** The server suppresses a push when the
+  app is open on that exact chat (`POST /api/v1/notify/presence` heartbeat, 45s
+  TTL). Different-chat or closed app → push goes out as normal.
+- **Offline/stall debounce (T-S4).** Server-side edge-triggered state machine:
+  a loop retrying every 60s on a quota outage pushes once on stall and stays
+  silent until it recovers and stalls again.
+
 ### 0.2.0
 
 - **New: `launch` / `autopilot` command** — hand a large, multi-step task off to

package/dist/src/cli.js

@@ -21,6 +21,7 @@ import { setup } from "./setup.js";
 import { uninstall } from "./uninstall.js";
 import { cmdConfig } from "./config.js";
 import { onStop } from "./on_stop.js";
+import { gatherDoctor, formatDoctor } from "./doctor.js";
 /** Subcommands the finished CLI will expose (see PRD §4.1). */
 export const COMMANDS = [
     "login",
@@ -28,6 +29,7 @@ export const COMMANDS = [
     "test",
     "setup",
     "status",
+    "doctor",
     "mcp",
     "uninstall",
     "config",
@@ -38,6 +40,43 @@ export const COMMANDS = [
 export const COMMAND_ALIASES = {
     autopilot: "launch",
 };
+/**
+ * Read all available data from `process.stdin` when it is a pipe (not a TTY),
+ * returning the full content as a string. Best-effort: returns an empty string on
+ * any error or if stdin is a TTY (no data to consume). Used by {@link cmdOnStop}
+ * to consume the Cursor `stop` hook's JSON payload (T-CUR1 / PRD §8.5).
+ *
+ * The read is bounded to {@link MAX_STDIN_BYTES} to prevent a misbehaving hook
+ * from blocking with an enormous payload. The function resolves (never rejects)
+ * so it can never block the hook's turn.
+ */
+export const MAX_STDIN_BYTES = 65536; // 64 KiB — far more than any hook JSON
+export async function readStdinIfPipe(stream) {
+    const src = stream ?? process.stdin;
+    // In a TTY / non-pipe context there is nothing to read — return early so we
+    // never block waiting for input on an interactive terminal.
+    if (src.isTTY)
+        return "";
+    return new Promise((resolve) => {
+        const chunks = [];
+        let totalBytes = 0;
+        src.on("data", (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buf.byteLength;
+            if (totalBytes <= MAX_STDIN_BYTES)
+                chunks.push(buf);
+        });
+        src.on("end", () => {
+            try {
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            }
+            catch {
+                resolve("");
+            }
+        });
+        src.on("error", () => resolve(""));
+    });
+}
 export function printHelp() {
     console.log([
         `gocode-notify v${VERSION}`,
@@ -52,6 +91,7 @@ export function printHelp() {
         "  test       Send a canned test push",
         "  setup      Pair + detect runtimes + write configs",
         "  status     Report credentials / server / detected runtimes",
+        "  doctor     Self-diagnostic checklist with exact fix commands",
         "  mcp        Run as an MCP server over stdio",
         "  uninstall  Remove entries this tool added",
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
@@ -324,6 +364,26 @@ export async function cmdStatus(args, deps = {}) {
     }
     return 0;
 }
+/**
+ * Handle `gocode-notify doctor [--server URL]` (PRD §8.6 R10 / T-COV4).
+ * Prints a checklist: (1) paired? (2) server reachable? (3) which runner hooks
+ * installed (Cursor stop / Claude Stop + Notification)? (4) gocode-notify on
+ * PATH for non-login shells? Each ✗ item prints the exact fix command.
+ * Always exits 0 — it is an informational report, not a gate.
+ */
+export async function cmdDoctor(args, deps = {}) {
+    const flags = parseFlags(args);
+    const report = await gatherDoctor({
+        home: deps.home,
+        serverFlag: flagString(flags, "server") ?? deps.serverFlag,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        pathEnv: deps.pathEnv,
+    });
+    for (const line of formatDoctor(report))
+        console.log(line);
+    return 0;
+}
 /** True when a flag is present as a bare boolean or explicit `=true`. */
 function flagBool(flags, name) {
     const v = flags.get(name);
@@ -429,6 +489,17 @@ export async function cmdOnStop(args, deps = {}) {
     const flags = parseFlags(args);
     const agent = isAgentDriven(flags);
     const sink = deps.sink ?? stdoutSink;
+    // Read the hook's stdin JSON (T-CUR1 / PRD §8.5). The Cursor `stop` hook pipes
+    // its event data to the process stdin; we consume it here so on-stop can map
+    // the `status` field to the correct notification kind. Best-effort: errors and
+    // TTY contexts return an empty string (falls back to `finished` in on_stop.ts).
+    //
+    // Injection priority: deps.hookStdin (test stub) > deps.readStdin (test reader)
+    // > real stdin read. An explicit empty string from deps.hookStdin means "no
+    // stdin provided" (do not read from the real process.stdin).
+    const hookStdin = deps.hookStdin !== undefined
+        ? deps.hookStdin
+        : await (deps.readStdin ?? readStdinIfPipe)();
     const server = await resolveServerUrl(flagString(flags, "server"), deps);
     const run = deps.onStopImpl ?? onStop;
     const result = await run({
@@ -441,6 +512,7 @@ export async function cmdOnStop(args, deps = {}) {
         fetchImpl: deps.fetchImpl,
         timeoutMs: deps.timeoutMs,
         timestamp: deps.timestamp,
+        hookStdin,
     });
     const delivered = result.mode === "push"
         ? result.push?.notified === true
@@ -453,7 +525,9 @@ export async function cmdOnStop(args, deps = {}) {
             ? "dry-run: would send finished (auto-push off)"
             : result.mode === "deduped"
                 ? "deduped: another source already notified for this run"
-                : `finished ${delivered ? "delivered" : "not delivered"}`;
+                : result.mode === "autopilot-suppressed"
+                    ? "autopilot-suppressed: an Autopilot loop owns this turn's ping"
+                    : `finished ${delivered ? "delivered" : "not delivered"}`;
     if (agent) {
         sink({ step: "on-stop", ok: true, detail });
     }
@@ -586,6 +660,8 @@ export async function runAsync(argv) {
         return cmdTest(argv.slice(1));
     if (cmd === "status")
         return cmdStatus(argv.slice(1));
+    if (cmd === "doctor")
+        return cmdDoctor(argv.slice(1));
     if (cmd === "setup")
         return cmdSetup(argv.slice(1));
     if (cmd === "mcp")

package/dist/src/doctor.js

@@ -0,0 +1,262 @@
+// `gocode-notify doctor` — self-diagnostic checklist (PRD §8.6 R10 / T-COV4).
+//
+// Prints a human-readable checklist of the installation health so users know
+// immediately what is missing and how to fix it.  Checks (in order):
+//
+//   1. Paired?        credentials exist and are valid.
+//   2. Server reachable?  the bound (or default) server answers.
+//   3. Runner hooks installed?  Claude Code Stop/Notification + Cursor stop.
+//   4. `gocode-notify` on PATH?  resolvable in non-login shells.
+//
+// Every ✗ check prints the EXACT fix command so users never have to guess.
+// Always exits 0 — it is a report, not a gate.
+//
+// The gather / format split mirrors `status.ts`:
+//   `gatherDoctor`  → pure async data collection (injectable deps, fully testable)
+//   `formatDoctor`  → pure sync rendering to string lines
+//   `cmdDoctor`     → thin CLI wire-up in `cli.ts`
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readCredentials, resolveServerUrl } from "./creds.js";
+import { probeServer, DEFAULT_PROBE_TIMEOUT_MS, UNPAIRED_WARNING } from "./status.js";
+// Re-export UNPAIRED_WARNING so existing `from "./doctor.js"` imports keep
+// working after the constant moved to status.ts (T-COV1).
+export { UNPAIRED_WARNING } from "./status.js";
+// ─── Hook markers ──────────────────────────────────────────────────────────
+// We detect our hook entries by looking for these stable tokens in the command
+// strings.  The same tokens are used by claude.ts / cursor.ts for idempotent
+// install / uninstall (kept in sync via the HOOK_SOURCE comments there).
+/** Tokens that identify a gocode-notify Claude Code hook in settings.json. */
+const CLAUDE_HOOK_TOKEN = "--source claude_code";
+/** Token that identifies our Cursor stop hook in hooks.json. */
+const CURSOR_HOOK_TOKEN = "--source cursor";
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function resolveHomeDir(opts) {
+    return opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? "~";
+}
+/** Read a JSON file; returns null on any error (absent, bad JSON, bad perms). */
+async function readJsonFile(p) {
+    try {
+        const raw = await fs.readFile(p, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `cmd` appears on any entry in `pathEnv` (colon-separated). */
+async function commandOnPath(cmd, pathEnv) {
+    if (!pathEnv)
+        return false;
+    const names = process.platform === "win32" ? [cmd, `${cmd}.exe`, `${cmd}.cmd`, `${cmd}.bat`] : [cmd];
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            try {
+                await fs.stat(path.join(dir, name));
+                return true;
+            }
+            catch {
+                // not in this dir — keep looking
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Recursively extract all `command` strings from a Claude/Cursor hooks value.
+ *
+ * Claude settings.json hook events have this shape:
+ *   hooks.Stop = [ { matcher: string, hooks: [ { type: "command", command: string } ] } ]
+ *
+ * Cursor hooks.json stop entries have this shape:
+ *   stop = [ { command: string } ]
+ *
+ * This walks the structure recursively so both formats are handled without
+ * needing a per-runtime parser.
+ */
+function extractCommands(value) {
+    if (!value)
+        return [];
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value)) {
+        const cmds = [];
+        for (const item of value)
+            cmds.push(...extractCommands(item));
+        return cmds;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const cmds = [];
+        // If this object has a `command` string field, it's a hook entry.
+        if (typeof obj.command === "string")
+            cmds.push(obj.command);
+        // Recurse into `hooks` sub-array (Claude Code's two-level nesting).
+        if (obj.hooks)
+            cmds.push(...extractCommands(obj.hooks));
+        return cmds;
+    }
+    return [];
+}
+/** Extract all hook command strings from a hooks event value (array or object). */
+function flattenHookCommands(hooksValue) {
+    return extractCommands(hooksValue);
+}
+// ─── Core gather ────────────────────────────────────────────────────────────
+/**
+ * Collect the full {@link DoctorReport}. Never throws — errors are surfaced as
+ * failing checks with actionable fix commands.
+ */
+export async function gatherDoctor(opts = {}) {
+    const checks = [];
+    const home = resolveHomeDir(opts);
+    // ── 1. Paired? ─────────────────────────────────────────────────────────
+    let pairedOk = false;
+    let pairedDetail = "not paired";
+    try {
+        const creds = await readCredentials({ home: opts.home });
+        if (creds) {
+            pairedOk = true;
+            pairedDetail = `paired as ${creds.user_id} (${creds.label})`;
+        }
+    }
+    catch {
+        pairedDetail = "credentials file unreadable";
+    }
+    checks.push({
+        key: "paired",
+        label: "Paired?",
+        ok: pairedOk,
+        detail: pairedDetail,
+        fixCmd: pairedOk ? undefined : "gocode-notify login",
+    });
+    // ── 2. Server reachable? ───────────────────────────────────────────────
+    const serverUrl = await resolveServerUrl(opts.serverFlag, { home: opts.home });
+    const probe = await probeServer(serverUrl, {
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+    });
+    checks.push({
+        key: "server",
+        label: "Server reachable?",
+        ok: probe.reachable,
+        detail: `${serverUrl} (${probe.detail})`,
+        fixCmd: probe.reachable
+            ? undefined
+            : "# Check your network or run: gocode-notify login --server <url>",
+    });
+    // ── 3a. Claude Code Stop hook ──────────────────────────────────────────
+    const claudeSettingsPath = path.join(home, ".claude", "settings.json");
+    const claudeSettings = await readJsonFile(claudeSettingsPath);
+    const claudeHooks = claudeSettings &&
+        typeof claudeSettings === "object" &&
+        "hooks" in claudeSettings
+        ? claudeSettings.hooks
+        : null;
+    const claudeStopCommands = flattenHookCommands(claudeHooks &&
+        typeof claudeHooks === "object" &&
+        "Stop" in claudeHooks
+        ? claudeHooks.Stop
+        : null);
+    const claudeStopInstalled = claudeStopCommands.some((c) => c.includes(CLAUDE_HOOK_TOKEN));
+    checks.push({
+        key: "hook:claude-stop",
+        label: "Claude Code Stop hook installed?",
+        ok: claudeStopInstalled,
+        detail: claudeStopInstalled
+            ? `found in ${claudeSettingsPath}`
+            : claudeHooks === null
+                ? "~/.claude/settings.json not found or no hooks"
+                : "hook not found",
+        fixCmd: claudeStopInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 3b. Claude Code Notification hook ──────────────────────────────────
+    const claudeNotifyCommands = flattenHookCommands(claudeHooks &&
+        typeof claudeHooks === "object" &&
+        "Notification" in claudeHooks
+        ? claudeHooks.Notification
+        : null);
+    const claudeNotifyInstalled = claudeNotifyCommands.some((c) => c.includes(CLAUDE_HOOK_TOKEN));
+    checks.push({
+        key: "hook:claude-notification",
+        label: "Claude Code Notification hook installed?",
+        ok: claudeNotifyInstalled,
+        detail: claudeNotifyInstalled
+            ? `found in ${claudeSettingsPath}`
+            : "hook not found",
+        fixCmd: claudeNotifyInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 3c. Cursor stop hook ───────────────────────────────────────────────
+    const cursorHooksPath = path.join(home, ".cursor", "hooks.json");
+    const cursorHooks = await readJsonFile(cursorHooksPath);
+    // Pass the stop array directly (not wrapped in an object) so extractCommands
+    // can find the {command: ...} entries inside it.
+    const cursorStopValue = cursorHooks &&
+        typeof cursorHooks === "object" &&
+        "stop" in cursorHooks
+        ? cursorHooks.stop
+        : null;
+    const cursorStopEntries = flattenHookCommands(cursorStopValue);
+    const cursorStopInstalled = cursorStopEntries.some((c) => c.includes(CURSOR_HOOK_TOKEN));
+    checks.push({
+        key: "hook:cursor-stop",
+        label: "Cursor stop hook installed?",
+        ok: cursorStopInstalled,
+        detail: cursorStopInstalled
+            ? `found in ${cursorHooksPath}`
+            : cursorHooks === null
+                ? "~/.cursor/hooks.json not found"
+                : "hook not found",
+        fixCmd: cursorStopInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 4. gocode-notify on PATH? ──────────────────────────────────────────
+    const pathEnv = opts.pathEnv ?? process.env.PATH;
+    const onPath = await commandOnPath("gocode-notify", pathEnv);
+    checks.push({
+        key: "path",
+        label: "gocode-notify on PATH (non-login shells)?",
+        ok: onPath,
+        detail: onPath
+            ? "gocode-notify is resolvable"
+            : "not found on PATH — hooks may fail in non-login shells",
+        fixCmd: onPath
+            ? undefined
+            : "# Add npm global bin to PATH, e.g.:\n  echo 'export PATH=\"$(npm root -g)/../.bin:$PATH\"' >> ~/.bashrc",
+    });
+    return { checks };
+}
+// ─── Formatting ─────────────────────────────────────────────────────────────
+function mark(ok) {
+    return ok ? "✓" : "✗";
+}
+// UNPAIRED_WARNING is defined in status.ts and re-exported above (T-COV1).
+/**
+ * Render a {@link DoctorReport} as human-readable lines. Each failing check
+ * includes the exact fix command. Always friendly — never emits an error tone
+ * for passing checks.
+ */
+export function formatDoctor(report) {
+    const lines = ["gocode-notify doctor", ""];
+    for (const check of report.checks) {
+        lines.push(`${mark(check.ok)} ${check.label}`);
+        lines.push(`    ${check.detail}`);
+        if (!check.ok && check.fixCmd) {
+            lines.push(`    Fix: ${check.fixCmd}`);
+        }
+        lines.push("");
+    }
+    // Surface the unpaired warning loudly (T-COV1 requirement: "surface ⚠️ loop
+    // completion pushes will NOT reach your phone" when not paired).
+    const pairedCheck = report.checks.find((c) => c.key === "paired");
+    if (pairedCheck && !pairedCheck.ok) {
+        lines.push(UNPAIRED_WARNING);
+        lines.push("");
+    }
+    const allOk = report.checks.every((c) => c.ok);
+    lines.push(allOk ? "All checks passed." : "Some checks failed — see fix commands above.");
+    return lines;
+}

package/dist/src/on_stop.js

@@ -25,11 +25,58 @@
 // injectable so the dispatcher is unit-testable with zero network / git / fs.
 //
 // Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
 import { resolveNotifySettings } from "./config.js";
 import { deriveRepoIdentity } from "./repo_key.js";
 import { pushOnStop, } from "./push.js";
 import { appendLog, send } from "./send.js";
 import { checkDedupLock } from "./dedup_lock.js";
+/**
+ * Parse the Cursor `stop` hook stdin JSON and extract the `status` field.
+ * Best-effort: returns `undefined` on absent/empty/unparseable input or when the
+ * `status` field is missing, so the caller falls back to `finished` gracefully.
+ * Never throws.
+ */
+export function parseCursorStopStatus(stdin) {
+    if (!stdin || stdin.trim() === "")
+        return undefined;
+    try {
+        const parsed = JSON.parse(stdin);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "status" in parsed &&
+            typeof parsed.status === "string") {
+            const s = parsed.status;
+            if (s === "completed" || s === "aborted" || s === "error")
+                return s;
+        }
+    }
+    catch {
+        // Unparseable stdin → fall back to `finished` (back-compat)
+    }
+    return undefined;
+}
+/**
+ * Map a Cursor `stop` status to the appropriate {@link NotifyKind} (T-CUR1 / PRD §8.5):
+ *   - `completed`  → `finished`          (agent turned cleanly)
+ *   - `aborted`    → `awaiting_input`     (agent yielded back to the human)
+ *   - `error`      → `error`              (agent hit an error)
+ *   - `undefined`  → `finished`           (back-compat: absent/unrecognised)
+ */
+export function cursorStopStatusToKind(status) {
+    switch (status) {
+        case "completed":
+            return "finished";
+        case "aborted":
+            return "awaiting_input";
+        case "error":
+            return "error";
+        default:
+            return "finished"; // back-compat: absent/unrecognised → finished
+    }
+}
 /** Slice the merged settings down to what the push flow consumes. */
 function toPushSettings(settings) {
     return {
@@ -37,6 +84,214 @@ function toPushSettings(settings) {
         commit_message: settings.commit_message,
     };
 }
+/**
+ * Resolve the `project` label for a per-turn ping (T-N4 / PRD §3.4). Prefers the
+ * derived repo identity's `repo_label`; when that is blank — the repo-derive
+ * threw (so `repo` is undefined) or a non-git cwd produced an empty label — falls
+ * back to the cwd basename so the phone ALWAYS shows SOMETHING ("better-than-
+ * nothing"). Returns `undefined` only when even the basename is empty (e.g. cwd
+ * is the filesystem root), so the caller still omits the field gracefully.
+ */
+export function projectLabel(repo, cwd) {
+    const label = repo?.repo_label?.trim();
+    if (label)
+        return label;
+    // Fall back to the cwd basename — but SKIP tool/config dot-dirs. The stop hook
+    // can run with a cwd inside `.cursor` (or `.git`, `.vscode`, …), whose basename
+    // would otherwise become the project name and render as "Cursor · .cursor"
+    // (the IDE name shown twice). Walk up past any leading-dot segment to the first
+    // real project folder so the label is the actual repo dir, not its tooling dir.
+    let dir = path.resolve(cwd);
+    for (let i = 0; i < 6; i++) {
+        const base = path.basename(dir).trim();
+        if (!base)
+            break; // reached filesystem root
+        if (!base.startsWith("."))
+            return base; // first non-dot folder wins
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // no more parents
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Derive the SAME stable `external_chat_id` that `@trygocode/sync` assigns to a
+ * synced transcript, so a per-turn notification can deep-link straight to that
+ * chat on tap. MUST stay byte-identical to gocode-sync's `deriveExternalChatId`:
+ * sha256 of `source\0(lower workspace)\0(session)`, first 32 hex chars.
+ *
+ * We re-derive (rather than import gocode-sync) because notify is a separate
+ * zero-dep package; the hash is tiny and pinned by a parity test.
+ */
+export function deriveIdeChatId(input) {
+    const basis = [
+        input.source.toLowerCase().trim(),
+        input.workspacePath.toLowerCase().trim(),
+        input.ideSessionId.trim(),
+    ].join("\u0000");
+    return createHash("sha256").update(basis).digest("hex").slice(0, 32);
+}
+/**
+ * Best-effort: from the Cursor/Claude stop-hook stdin JSON + cwd, compute the
+ * synced chat's `external_chat_id` so the notification deep-links to it. Returns
+ * undefined when the payload lacks a stable session id (then the push falls back
+ * to Home, exactly as before). Never throws.
+ *
+ * Session id resolution mirrors the capture adapters:
+ *   - Cursor: `conversation_id` / `conversationId`, else the `transcript_path`
+ *     filename (minus `.jsonl`).
+ *   - Claude: `session_id` / `sessionId`, else the `transcript_path` filename.
+ * Workspace mirrors capture: payload workspace/cwd, else the hook cwd.
+ */
+export function ideChatIdFromHookStdin(source, cwd, hookStdin) {
+    if (!hookStdin || hookStdin.trim() === "")
+        return undefined;
+    let p;
+    try {
+        const parsed = JSON.parse(hookStdin);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        p = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    const str = (...vals) => {
+        for (const v of vals)
+            if (typeof v === "string" && v.trim() !== "")
+                return v;
+        return undefined;
+    };
+    const transcriptPath = str(p.transcript_path, p.transcriptPath);
+    const sessionFromPath = transcriptPath
+        ? path.basename(transcriptPath).replace(/\.jsonl$/i, "") || undefined
+        : undefined;
+    const ideSessionId = str(p.conversation_id, p.conversationId, p.session_id, p.sessionId, sessionFromPath);
+    if (!ideSessionId)
+        return undefined;
+    const workspacePath = str(p.workspace_path, Array.isArray(p.workspaceRoots) ? p.workspaceRoots[0] : undefined, p.cwd, cwd);
+    if (!workspacePath)
+        return undefined;
+    // The capture side stores `source: "cursor" | "claude_code"`; the hook passes
+    // `--source cursor|claude_code`, so they already match. Normalise just in case.
+    const normSource = source === "claude" ? "claude_code" : source;
+    return deriveIdeChatId({
+        source: normSource,
+        workspacePath: path.resolve(workspacePath),
+        ideSessionId,
+    });
+}
+/**
+ * Best-effort: derive a short chat title from the transcript named in the hook
+ * stdin, mirroring gocode-sync's `deriveTitleFromMessages` (first user message's
+ * first meaningful line). Used to name WHICH chat finished in the push body.
+ * Reads at most the first ~64KB of the JSONL (titles come from the first user
+ * turn). Returns undefined on any problem — never throws.
+ */
+export async function chatTitleFromHookStdin(hookStdin) {
+    if (!hookStdin || hookStdin.trim() === "")
+        return undefined;
+    let transcriptPath;
+    try {
+        const p = JSON.parse(hookStdin);
+        const v = p.transcript_path ?? p.transcriptPath;
+        if (typeof v === "string" && v.trim() !== "")
+            transcriptPath = v;
+    }
+    catch {
+        return undefined;
+    }
+    if (!transcriptPath)
+        return undefined;
+    let raw;
+    try {
+        raw = await fs.readFile(transcriptPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        // role: top-level `role` (Cursor) or nested `message.role` / `type` (Claude).
+        const nested = rec.message && typeof rec.message === "object"
+            ? rec.message
+            : undefined;
+        const role = String(rec.role ?? nested?.role ?? rec.type ?? "");
+        if (role !== "user" && role !== "human")
+            continue;
+        // content: string or block array, inline or nested.
+        let content = "";
+        const src = rec.content ?? rec.text ?? nested?.content;
+        if (typeof src === "string")
+            content = src;
+        else if (Array.isArray(src)) {
+            for (const b of src) {
+                if (typeof b === "string")
+                    content += b + "\n";
+                else if (b && typeof b === "object" && typeof b.text === "string")
+                    content += String(b.text) + "\n";
+            }
+        }
+        // Strip the harness `<user_query>` / `<timestamp>` plumbing so the title is
+        // the human's words (mirrors gocode-sync's sanitizer, minimal form).
+        content = content
+            .replace(/<timestamp(?:\s[^>]*)?>[\s\S]*?<\/timestamp>/gi, "")
+            .replace(/<image_files(?:\s[^>]*)?>[\s\S]*?<\/image_files>/gi, "")
+            .replace(/\[Image\](?!\()\s*/g, "")
+            .replace(/<\/?user_query(?:\s[^>]*)?>/gi, "");
+        const firstLine = content
+            .split("\n")
+            .map((l) => l.trim())
+            .find((l) => l !== "");
+        if (!firstLine)
+            continue;
+        let title = firstLine.replace(/^[#>\-*+\s]+/, "").replace(/[*_`]+/g, "").trim();
+        if (title === "")
+            continue;
+        if (title.length > 80)
+            title = title.slice(0, 79).trimEnd() + "…";
+        return title;
+    }
+    return undefined;
+}
+/**
+ * Env var an Autopilot (Ralph/Homer) loop exports to mark that IT owns the
+ * current turn's notification (T-N7 / PRD §3.2). When truthy, {@link onStop}
+ * suppresses its per-turn ping entirely: the loop sends its OWN
+ * `loop_completed`/`loop_halted` Autopilot ping (`_loop_inner.sh
+ * push_notify_local`), so any stop-hook-driven `finished`/`push` ping for the
+ * same turn would be a duplicate of it.
+ *
+ * Defensive by design: today a Ralph `claude-tmux` iteration runs `claude` in its
+ * own tmux pane (Claude Code has no `Stop` hook here) and is NOT a Cursor turn, so
+ * the only per-turn hook (`cursor stop`) never fires for a loop — no double-fire
+ * exists to suppress. This gate is the READING half of the contract (the loop
+ * script exports the marker, T-N5) so that if a future loop arrangement DOES trip
+ * a stop hook, the duplicate is gated off at the source.
+ */
+export const AUTOPILOT_OWNS_TURN_ENV = "GOCODE_AUTOPILOT_OWNS_TURN";
+/**
+ * True when {@link AUTOPILOT_OWNS_TURN_ENV} is set to a truthy value. Treats the
+ * usual falsy strings (`""`, `0`, `false`, `no`, `off`, any case) as not-owned so
+ * an accidental empty/`0` export never silently eats every per-turn ping.
+ */
+export function autopilotOwnsTurn(env = process.env) {
+    const raw = env[AUTOPILOT_OWNS_TURN_ENV];
+    if (raw == null)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
 /**
  * The end-of-turn dispatcher (PRD §2.2). Resolves settings, then either delegates
  * to the auto-push flow (which sends its own notification) OR fires the plain
@@ -71,6 +326,21 @@ export async function onStop(opts = {}) {
             timestamp: opts.timestamp,
         }));
     try {
+        // ── Step 0: Autopilot-owns-turn gate (T-N7 / PRD §3.2). ──
+        // When an Autopilot loop has marked that it owns this turn, it sends its OWN
+        // loop_completed/loop_halted Autopilot ping, so ANY per-turn stop-hook ping
+        // here (plain `finished` OR the auto-push notification) would be a duplicate.
+        // Suppress entirely — no send, no git push — before doing any other work.
+        // Best-effort + safe: gated behind an explicit truthy env marker only, so a
+        // normal hand-driven turn (no marker) is never affected.
+        if (autopilotOwnsTurn(opts.env)) {
+            await logLine(`autopilot owns turn (${AUTOPILOT_OWNS_TURN_ENV}) → suppressed per-turn ${source} ping (loop ping is authoritative)`);
+            return {
+                mode: "autopilot-suppressed",
+                settingsSource: "default",
+                detail: "autopilot loop owns the turn — per-turn ping suppressed",
+            };
+        }
         // ── Step 1: derive repo identity (never throws — local fallback on failure). ──
         let repo;
         try {
@@ -98,7 +368,7 @@ export async function onStop(opts = {}) {
                 settings: toPushSettings(settings),
                 source,
                 cwd,
-                project: repo?.repo_label,
+                project: projectLabel(repo, cwd),
                 dedupeKey: opts.dedupeKey,
                 dryRun: opts.dryRun,
                 server: opts.server,
@@ -110,13 +380,21 @@ export async function onStop(opts = {}) {
             await logLine(`auto-push path → ${push.outcome} (source: ${source}, settings: ${resolved.source})`);
             return { mode: "push", settingsSource: resolved.source, push, repo, detail: push.detail };
         }
-        // ── Step 3b: auto-push off → the plain `finished` notification (legacy flow). ──
+        // ── Step 3b: auto-push off → the plain notification (legacy flow). ──
+        // Derive the notification kind from the Cursor stop hook's stdin JSON (T-CUR1
+        // / PRD §8.5). The status maps:
+        //   completed  → finished          (agent turned cleanly)
+        //   aborted    → awaiting_input    (agent yielded back to the human)
+        //   error      → error             (agent hit an error)
+        //   absent     → finished          (back-compat: no stdin or unrecognised status)
+        const hookStatus = parseCursorStopStatus(opts.hookStdin);
+        const sendKind = cursorStopStatusToKind(hookStatus);
         if (opts.dryRun) {
-            await logLine(`dry-run: would send finished (auto-push off, source: ${source}, settings: ${resolved.source})`);
+            await logLine(`dry-run: would send ${sendKind} (auto-push off, source: ${source}, settings: ${resolved.source})`);
             return { mode: "dry-run-send", settingsSource: resolved.source, repo };
         }
         // Client fast-path cross-source dedup (T-N2 / PRD §2.2): before the plain
-        // `finished` send, consult a short-TTL lock keyed by repo+kind+minute-bucket.
+        // send, consult a short-TTL lock keyed by repo+kind+minute-bucket.
         // If another source (e.g. the Cursor `stop` hook vs this Claude `Stop` hook)
         // already claimed the bucket within the window, skip OUR local send — the
         // first arrival's notification stands. Best-effort + fail-open: the check
@@ -128,7 +406,7 @@ export async function onStop(opts = {}) {
         try {
             decision = await dedupCheck({
                 repoKey: repo?.repo_key,
-                kind: "finished",
+                kind: sendKind,
                 source,
                 windowMs: opts.dedupWindowMs,
                 home: opts.home,
@@ -138,16 +416,27 @@ export async function onStop(opts = {}) {
             decision = "send"; // defence in depth — never let dedup block the send
         }
         if (decision === "suppress") {
-            await logLine(`dedup fast-path → suppressed duplicate finished (source: ${source}, settings: ${resolved.source})`);
+            await logLine(`dedup fast-path → suppressed duplicate ${sendKind} (source: ${source}, settings: ${resolved.source})`);
             return { mode: "deduped", settingsSource: resolved.source, repo };
         }
-        const payload = { kind: "finished", source };
-        if (repo?.repo_label)
-            payload.project = repo.repo_label;
+        const payload = { kind: sendKind, source };
+        const project = projectLabel(repo, cwd);
+        if (project)
+            payload.project = project;
         if (opts.dedupeKey)
             payload.dedupe_key = opts.dedupeKey;
+        // Deep-link target: the synced chat's id (so tapping the push opens the
+        // chat, not just Home). Best-effort — omitted when the hook payload has no
+        // stable session id (push then falls back to Home, as before).
+        const ideChatId = ideChatIdFromHookStdin(source, cwd, opts.hookStdin);
+        if (ideChatId)
+            payload.ide_chat_id = ideChatId;
+        // Name WHICH chat finished in the body (best-effort; omitted if unreadable).
+        const chatTitle = await chatTitleFromHookStdin(opts.hookStdin);
+        if (chatTitle)
+            payload.chat = chatTitle;
         const sent = await sendImpl(payload);
-        await logLine(`send path → finished ${sent.ok ? "delivered" : "failed"} (source: ${source}, settings: ${resolved.source})`);
+        await logLine(`send path → ${sendKind} ${sent.ok ? "delivered" : "failed"} (source: ${source}, settings: ${resolved.source})`);
         return { mode: "send", settingsSource: resolved.source, send: sent, repo };
     }
     catch (err) {

package/dist/src/send.js

@@ -20,6 +20,13 @@ export const NOTIFY_KINDS = [
     "awaiting_input",
     "loop_completed",
     "loop_halted",
+    // Ralph/Homer lifecycle kinds (PRD §4 — Notify Human-Gating PRD 2026-06-08).
+    // ralph_waiting: offline/quota stall edge — pushed once on the stall edge;
+    //   server drops repeats until a resumed/completed/halted re-arms the edge.
+    // ralph_resumed: stall recovered, loop running again — NEVER pushed (silent
+    //   control event that resets the server-side stall state machine to ARMED).
+    "ralph_waiting",
+    "ralph_resumed",
 ];
 /** True when `value` is one of the canonical {@link NOTIFY_KINDS}. */
 export function isNotifyKind(value) {
@@ -45,7 +52,7 @@ function normalizeServer(url) {
 /** Build the JSON body, dropping any undefined/empty optional fields. */
 function buildBody(payload) {
     const body = { kind: payload.kind };
-    for (const field of ["title", "body", "source", "project", "dedupe_key"]) {
+    for (const field of ["title", "body", "source", "project", "dedupe_key", "ide_chat_id", "chat"]) {
         const v = payload[field];
         if (typeof v === "string" && v !== "")
             body[field] = v;

package/dist/src/status.js

@@ -84,6 +84,18 @@ export async function gatherStatus(opts = {}) {
 function mark(ok) {
     return ok ? "✓" : "✗";
 }
+/**
+ * One-liner hint appended at the bottom of {@link formatStatus}.
+ * Kept as an exported constant so tests can match against the exact text.
+ */
+export const STATUS_ONELINER_HINT = "To notify from your own script, add: gocode-notify send --kind finished --source <name> || true";
+/**
+ * Warning surfaced when credentials are absent (T-COV1: make the silent no-op LOUD).
+ * Defined here so both `status` and `doctor` can use the same text without a
+ * circular import (doctor.ts already imports from status.ts).
+ * Exported so tests can match against the exact text.
+ */
+export const UNPAIRED_WARNING = "⚠️  loop completion pushes will NOT reach your phone — run `gocode-notify login`";
 /** Render a {@link StatusReport} as human-readable lines (one per element). */
 export function formatStatus(report) {
     const lines = ["gocode-notify status", ""];
@@ -98,6 +110,11 @@ export function formatStatus(report) {
         lines.push(`${mark(false)} Credentials: not paired — run \`gocode-notify login\``);
     }
     lines.push(`    path: ${c.path}`);
+    // T-COV1: Surface the loud unpaired warning so loop scripts that check
+    // `gocode-notify status` never silently miss that pushes are disabled.
+    if (!c.present) {
+        lines.push("", UNPAIRED_WARNING);
+    }
     lines.push(`${mark(report.server.reachable)} Server: ${report.server.url} (${report.server.detail})`);
     lines.push("", "Runtimes:");
     for (const r of report.runtimes) {
@@ -109,6 +126,7 @@ export function formatStatus(report) {
         lines.push(`  ${mark(true)} ${r.name}: detected (${cfg})`);
         lines.push(`      config: ${r.configPath}`);
     }
+    lines.push("", STATUS_ONELINER_HINT);
     return lines;
 }
 /**

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Single source of truth for the CLI version. Keep in sync with package.json.
-export const VERSION = "0.2.0";
+export const VERSION = "0.3.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trygocode/notify",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Free phone notifications for any coding agent (Cursor, Claude Code, OpenCode, Ralph/Homer) via the GoCode app.",
   "license": "MIT",
   "type": "module",

package/snippets/ralph-homer.sh

@@ -1,21 +1,341 @@
 # gocode-notify — Ralph/Homer loop opt-in snippet  (PRD §5.6, trigger C)
 #
 # OPT-IN. This snippet is NOT auto-injected by `gocode-notify setup`; the
-# installer never edits your loop scripts without consent. Paste these two
-# lines into the completion/halt path of any loop you control (this repo's
-# `ralph`/`homer` skills, Geoffrey Huntley's `while :; do … done` one-liner,
-# or your own driver) to get a phone push when the loop finishes or halts.
+# installer never edits your loop scripts without consent. Paste the relevant
+# stanzas into the completion/halt/stall paths of any loop you control (this
+# repo's `ralph`/`homer` skills, Geoffrey Huntley's `while :; do … done`
+# one-liner, or your own driver) to get phone pushes for the right events.
 #
 # Prereq: you've already paired this machine once with
 #   npx @trygocode/notify@latest login --code <CODE>
 # (get <CODE> from the GoCode app → "Connect a coding agent").
 #
-# Both lines are fire-and-forget: the `|| true` guarantees a failed/slow push
+# All calls are fire-and-forget: the `|| true` guarantees a failed/slow push
 # can never block or fail your loop (the CLI also self-times-out in 5s).
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# KIND CONTRACT (PRD §4 "Notify Human-Gating")
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# The *kind* is the contract. The GoCode server classifies every kind into
+# exactly one push-worthiness bucket. Callers only need to emit the RIGHT kind;
+# the server handles foreground-suppression, stall-dedup, and FCM delivery.
+#
+#  Kind                 Push-worthy?  When to emit
+#  ─────────────────    ────────────  ────────────────────────────────────────
+#  loop_completed       ✅  YES       Loop finished all work cleanly.
+#  ralph_completed      ✅  YES       Ralph-specific alias for loop_completed.
+#  loop_halted          ✅  YES       Loop paused — a HUMAN is needed.
+#  ralph_halted         ✅  YES       Ralph-specific alias for loop_halted.
+#                                     Covers: user_blocking question, max
+#                                     consecutive failures.
+#  ralph_synth_question ✅  YES       Setup question raised BEFORE the loop
+#                                     starts — genuinely needs a human.
+#  ralph_waiting        ✅  EDGE ONLY Offline / quota stall. Emit ONLY on the
+#                                     stall EDGE (first failure). Server drops
+#                                     repeats until a resumed/completed/halted
+#                                     re-arms the edge. See pattern below.
+#  ralph_resumed        🔕  NO push   Stall recovered; loop running again.
+#                                     Silent control event: its only effect is
+#                                     to reset the server-side stall state
+#                                     machine back to ARMED so the NEXT genuine
+#                                     stall edge will push again.
+#  ralph_question       🔕  NO push   In-loop question the Oracle answers
+#                                     autonomously. Server logs it for the
+#                                     dashboard but NEVER sends to FCM. Do NOT
+#                                     emit this on oracle-answerable paths.
+#  ralph_advanced       🔕  NO push   Queue advanced to next PRD (info only).
+#  finished             ✅  YES       Generic agent-finished (non-loop hooks).
+#  awaiting_input       ✅  YES       Generic agent needs the human (non-loop).
+#  error                ✅  YES       Generic agent hit an error.
+#
+# Rule: only emit push-worthy kinds on the paths where a HUMAN is genuinely
+# needed. Oracle-answerable questions and routine loop events must be silent.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 1 — Loop completion (all work done cleanly)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Use loop_completed (or ralph_completed for Ralph-specific loops).
+gocode-notify send --kind loop_completed --source ralph \
+  --project "$(basename "$PWD")" || true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 2 — Loop halt (a HUMAN is needed — user_blocking / max-failures)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Emit ralph_halted ONLY when the loop is genuinely paused awaiting human action:
+#   - A user_blocking question was raised (the Oracle cannot answer it).
+#   - The loop hit max consecutive failures and stopped.
+#
+# Do NOT emit ralph_halted for oracle-answerable (blocking) questions — the
+# Oracle handles those autonomously; emitting halted would be a false alarm.
+
+gocode-notify send --kind ralph_halted --source ralph \
+  --project "$(basename "$PWD")" \
+  --title "Ralph halted — needs you" || true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 3 — Offline / quota stall (edge-triggered, NOT every retry)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# A loop that polls every ~60s on a network/quota outage must push ONCE when
+# it first stalls, stay SILENT while still stalled, and push AGAIN only after
+# it recovers and then stalls again. Never spam on every retry.
+#
+# Caller-side responsibility: only fire ralph_waiting on the EDGE (first stall),
+# not on every subsequent retry. The server also deduplicates repeats as a
+# defense-in-depth backstop.
+#
+# Shell pattern (adapt to your loop's retry logic):
+
+_stall_notified=0   # reset to 0 at loop start or after recovery
+
+# Inside your retry / offline-backoff loop:
+if [[ "$_stall_notified" -eq 0 ]]; then
+  # First time we're stalled — notify on the edge.
+  gocode-notify send --kind ralph_waiting --source ralph \
+    --project "$(basename "$PWD")" \
+    --title "Ralph waiting — offline or quota" || true
+  _stall_notified=1
+fi
+sleep 60
+
+# When the endpoint recovers — emit ralph_resumed to reset the server edge state.
+# This re-arms the next genuine stall edge so it will push again.
+# Then reset the caller-side flag.
+_stall_notified=0
+gocode-notify send --kind ralph_resumed --source ralph \
+  --project "$(basename "$PWD")" || true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 4 — Oracle-answerable question (SILENT — do NOT push)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# When the loop raises a question that the Oracle will answer autonomously
+# (a normal "blocking" question, not "user_blocking"), emit NOTHING. The
+# Oracle will handle it and the loop will continue with no human in the picture.
+#
+# Previously: some loops emitted `ralph_question` here. DO NOT do this —
+# ralph_question is classified as a non-push info kind server-side (it is
+# logged for the dashboard but never sent to FCM), and the caller should stop
+# emitting it entirely on oracle-answerable paths to minimize noise.
+#
+# Summary:
+#   user_blocking halt  → push (ralph_halted)
+#   oracle-answerable   → push NOTHING (or at most ralph_question, which is
+#                         server-side demoted to a silent info event)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 5 — Crash-safe terminal notify via trap (PRD §8.6)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Problem: a loop killed by an unexpected signal (SIGTERM, SIGKILL, SIGINT),
+# an unhandled error, or a shell `exit` on a non-zero status will terminate
+# WITHOUT ever reaching the explicit halt/completed path — so the user's phone
+# is never notified, leaving them unaware the loop stopped.
+#
+# Solution: register a bash `trap` at the TOP of your loop script that fires a
+# best-effort `loop_halted` push on ANY unexpected exit.  The `|| true` guard
+# ensures the trap itself can never cause a secondary failure.
+#
+# HOW IT WORKS
+# ─────────────
+# 1. Set _LOOP_EXITED=0 at the top of your script (before the main loop).
+# 2. At every NORMAL exit path (completed / halted / stall) flip the flag to 1
+#    BEFORE sending the final push, so the trap knows a push already went out.
+# 3. The trap only fires a push when _LOOP_EXITED == 0 (i.e. the script reached
+#    the EXIT signal without a controlled terminal notification).
+#
+# SIGNALS COVERED
+# ────────────────
+# Bash's EXIT pseudo-signal fires on:
+#   • Normal exit (fall-through past the last line)     ← covered by flag
+#   • `exit N` from any point in the script             ← covered by flag
+#   • SIGTERM (graceful kill, e.g. `kill <pid>`)        ← ✅ caught
+#   • SIGINT  (Ctrl-C / terminal close)                 ← ✅ caught
+#   • Unhandled ERR (set -e + unset command)            ← ✅ caught
+#
+# NOTE: SIGKILL (kill -9) cannot be trapped by any process — that's a kernel
+# hard-kill.  Nothing can be done for SIGKILL; document this for your users.
+#
+# ─── PASTE THIS BLOCK AT THE TOP OF YOUR LOOP SCRIPT ────────────────────────
+
+# 1. Flag: 0 = no terminal push has gone out yet; 1 = push already sent.
+_LOOP_EXITED=0
+
+# 2. Crash-safe trap — fires on EXIT (normal fall-through, `exit N`, SIGTERM,
+#    SIGINT, unhandled ERR).  Sends loop_halted if no controlled push went out.
+_loop_crash_trap() {
+  if [[ "${_LOOP_EXITED:-0}" -eq 0 ]]; then
+    # Unexpected exit — best-effort push, never block.
+    gocode-notify send --kind loop_halted --source ralph \
+      --project "$(basename "$PWD")" \
+      --title "Loop exited unexpectedly — check logs" || true
+  fi
+}
+trap '_loop_crash_trap' EXIT
 
-# --- At loop completion (the loop finished all work cleanly) -----------------
-gocode-notify send --kind loop_completed --source ralph --project "$(basename "$PWD")" || true
+# ─── END OF TOP-OF-SCRIPT BLOCK ──────────────────────────────────────────────
 
-# --- At loop halt (paused_max_failures / awaiting_human / question raised) ---
-gocode-notify send --kind loop_halted --source ralph --project "$(basename "$PWD")" \
+# ─── AT EACH NORMAL TERMINAL EXIT PATH, set the flag THEN send the push ──────
+
+# Example — loop completed cleanly:
+_LOOP_EXITED=1
+gocode-notify send --kind loop_completed --source ralph \
+  --project "$(basename "$PWD")" || true
+
+# Example — loop halted (user_blocking / max-failures):
+_LOOP_EXITED=1
+gocode-notify send --kind ralph_halted --source ralph \
+  --project "$(basename "$PWD")" \
   --title "Ralph halted — needs you" || true
+
+# Example — explicit clean exit (no push needed, but mark so trap is silent):
+_LOOP_EXITED=1
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MINIMAL COPY-PASTE (drop-in for any loop script)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Add these 6 lines to the top of your script and the trap handles the rest:
+#
+#   _LOOP_EXITED=0
+#   _loop_crash_trap() {
+#     [[ "${_LOOP_EXITED:-0}" -eq 0 ]] && \
+#       gocode-notify send --kind loop_halted --source ralph \
+#         --project "$(basename "$PWD")" \
+#         --title "Loop exited unexpectedly — check logs" || true
+#   }
+#   trap '_loop_crash_trap' EXIT
+#
+# Then at every terminal exit path, set _LOOP_EXITED=1 before the final push.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PATTERN 6 — `terminal_halt` helper (PRD §8.7 R12)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# PROBLEM this solves:
+#   When a loop has many exit paths (task-complete, user_blocking halt,
+#   max-consecutive-failures, stall, explicit stop) each one must:
+#     1. Set _LOOP_EXITED=1       (so the crash trap stays silent)
+#     2. Send the right push kind
+#     3. Break out of the main loop
+#   Duplicating those 3 steps at every exit point is error-prone — it is easy
+#   to add a new `break` or `exit` path and forget the push.
+#
+# SOLUTION — one-call `terminal_halt <kind> <detail>`:
+#   Centralise the 3 steps in a single helper.  Every exit path calls the
+#   helper; the push is guaranteed by construction.
+#
+# TERMINAL KINDS — the three categories an exit can belong to:
+#
+#   ┌──────────────────────┬────────────────────────────────────────────────┐
+#   │ Kind                 │ When to use                                    │
+#   ├──────────────────────┼────────────────────────────────────────────────┤
+#   │ loop_halted          │ Loop stopped; a HUMAN is needed.               │
+#   │   (ralph_halted)     │ • user_blocking question raised                │
+#   │                      │ • max consecutive failures reached             │
+#   │                      │ • explicit operator stop (.homer/STOP file)    │
+#   ├──────────────────────┼────────────────────────────────────────────────┤
+#   │ loop_completed       │ Loop finished all work cleanly — all tasks     │
+#   │   (ralph_completed)  │ checked off or tracker fully satisfied.        │
+#   ├──────────────────────┼────────────────────────────────────────────────┤
+#   │ ralph_waiting        │ Loop cannot proceed right now (offline /       │
+#   │                      │ quota stall) — emit on the EDGE only (first    │
+#   │                      │ stall). Use PATTERN 3's _stall_notified guard  │
+#   │                      │ before calling terminal_halt with this kind.   │
+#   └──────────────────────┴────────────────────────────────────────────────┘
+#
+# SIGNATURE:
+#   terminal_halt <kind> <detail>
+#
+#   <kind>    — one of the terminal kinds above (loop_halted, loop_completed,
+#               ralph_halted, ralph_completed, ralph_waiting, …)
+#   <detail>  — short human-readable description that becomes --title / body text
+#               on the push notification.  Keep it under 80 chars.
+#
+# HOW TO USE — paste the function definition at the top of your loop script
+# (right after the _LOOP_EXITED + trap block), then call `terminal_halt` at
+# every exit point instead of inline _LOOP_EXITED=1 + gocode-notify + break.
+#
+# ─── PASTE THIS FUNCTION DEFINITION AT THE TOP OF YOUR LOOP SCRIPT ───────────
+
+terminal_halt() {
+  # terminal_halt <kind> <detail>
+  # Marks the loop as exiting (silences crash trap), sends the push, then
+  # breaks out of the enclosing loop.  Safe to call from inside `while`/`for`.
+  local _th_kind="${1:-loop_halted}"
+  local _th_detail="${2:-Loop exited}"
+  _LOOP_EXITED=1
+  gocode-notify send --kind "$_th_kind" --source ralph \
+    --project "$(basename "$PWD")" \
+    --title "$_th_detail" || true
+  # `break` exits the innermost loop.  If you call terminal_halt from a nested
+  # function inside the main loop, use `return` + then call `break` in the
+  # caller, or replace this with `exit 0` for a top-level script.
+  break
+}
+
+# ─── END OF FUNCTION DEFINITION ──────────────────────────────────────────────
+
+# ─── USAGE EXAMPLES — replace the inline _LOOP_EXITED=1 + send + break ───────
+
+# Example — loop completed cleanly:
+#   terminal_halt loop_completed "All tasks finished"
+
+# Example — loop halted (user_blocking question):
+#   terminal_halt ralph_halted "User action required — see .homer/questions/"
+
+# Example — loop halted (max consecutive failures):
+#   terminal_halt ralph_halted "Max consecutive failures reached — check logs"
+
+# Example — stall edge (wrap in the _stall_notified guard from PATTERN 3):
+#   if [[ "$_stall_notified" -eq 0 ]]; then
+#     terminal_halt ralph_waiting "Offline / quota stall — retrying when ready"
+#     # NOTE: terminal_halt breaks the loop here.  For a stall you may prefer
+#     # to stay in the loop and retry — in that case emit ralph_waiting inline
+#     # (PATTERN 3) and do NOT call terminal_halt (which would exit the loop).
+#   fi
+
+# ─── COMPLETE BOILERPLATE (combine PATTERN 5 + PATTERN 6) ────────────────────
+#
+# Minimal drop-in for a new loop script — covers crash-safe trap + terminal_halt:
+#
+#   _LOOP_EXITED=0
+#
+#   _loop_crash_trap() {
+#     [[ "${_LOOP_EXITED:-0}" -eq 0 ]] && \
+#       gocode-notify send --kind loop_halted --source ralph \
+#         --project "$(basename "$PWD")" \
+#         --title "Loop exited unexpectedly — check logs" || true
+#   }
+#   trap '_loop_crash_trap' EXIT
+#
+#   terminal_halt() {
+#     local _th_kind="${1:-loop_halted}"
+#     local _th_detail="${2:-Loop exited}"
+#     _LOOP_EXITED=1
+#     gocode-notify send --kind "$_th_kind" --source ralph \
+#       --project "$(basename "$PWD")" \
+#       --title "$_th_detail" || true
+#     break
+#   }
+#
+#   # Main loop
+#   while true; do
+#     # ... your loop body ...
+#
+#     if all_tasks_done; then
+#       terminal_halt loop_completed "All tasks finished"
+#     fi
+#     if user_blocking_halt; then
+#       terminal_halt ralph_halted "User action required"
+#     fi
+#     if max_failures_exceeded; then
+#       terminal_halt ralph_halted "Max consecutive failures reached"
+#     fi
+#   done
+#
+# Any path that exits without calling terminal_halt is caught by the trap.
+# Any path that calls terminal_halt gets exactly one push, then breaks cleanly.