@trygocode/notify 0.1.6 → 0.3.1

package/dist/src/on_stop.js

@@ -25,10 +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 {
@@ -36,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
@@ -70,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 {
@@ -97,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,
@@ -109,18 +380,63 @@ 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 };
         }
-        const payload = { kind: "finished", source };
-        if (repo?.repo_label)
-            payload.project = repo.repo_label;
+        // Client fast-path cross-source dedup (T-N2 / PRD §2.2): before the plain
+        // 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
+        // never throws, and on any doubt it returns "send" (the server is the
+        // authoritative coalescer — guardrail §3). Scoped to the plain-send path so
+        // the auto-push git flow above is never skipped.
+        const dedupCheck = opts.dedupCheck ?? checkDedupLock;
+        let decision = "send";
+        try {
+            decision = await dedupCheck({
+                repoKey: repo?.repo_key,
+                kind: sendKind,
+                source,
+                windowMs: opts.dedupWindowMs,
+                home: opts.home,
+            });
+        }
+        catch {
+            decision = "send"; // defence in depth — never let dedup block the send
+        }
+        if (decision === "suppress") {
+            await logLine(`dedup fast-path → suppressed duplicate ${sendKind} (source: ${source}, settings: ${resolved.source})`);
+            return { mode: "deduped", settingsSource: resolved.source, repo };
+        }
+        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/rule-content.js

@@ -19,7 +19,10 @@
 /**
  * Build the §5.5 rule/skill Markdown for one client. The body is byte-identical
  * across clients except for the frontmatter and the named hook mechanism, so the
- * anti-double-ping guidance stays in lockstep.
+ * anti-double-ping guidance stays in lockstep. The launch/offload guidance
+ * ({@link buildLaunchGuidance}, PRD §4.4) is appended verbatim — also client-
+ * agnostic — so a single `gocode-notify setup` wires notify + launch guidance
+ * together into the same rule/skill file.
  */
 export function buildRuleContent({ frontmatter, hookDescription }) {
     return `${frontmatter}
@@ -47,6 +50,54 @@ done". Then call it once, at that moment, with a clear \`title\`/\`body\`.
 If \`gocode_notify_status\` reports no credentials, tell the user to run
 \`npx @trygocode/notify login\` and pair from the GoCode app's "Connect a coding
 agent" screen. Do not retry more than twice.
+
+${buildLaunchGuidance()}`;
+}
+/**
+ * Build the launch/offload guidance section (PRD §4.4) shipped into the SAME
+ * rule/skill file as the notify guidance above. It teaches the desktop agent
+ * *when* and *how* to hand a large task off to the user's GoCode server via the
+ * `gocode_launch_autopilot` MCP tool: the trigger phrases that mean "offload",
+ * a one-paragraph what-it-does the agent can relay, and the hard guardrails —
+ * the most important being **fresh server agent, no local file access — pass a
+ * self-contained task** (the server loop is a brand-new agent with NO access to
+ * the IDE's open/unsaved files).
+ *
+ * This is client-agnostic prose (no frontmatter, no hook mention), so it stays
+ * byte-identical across Cursor and Claude — keeping the launch guidance in
+ * lockstep exactly like the notify body. Exported as the new `rule-content.ts`
+ * surface the per-runtime writers ({@link buildRuleContent}) compose in.
+ */
+export function buildLaunchGuidance() {
+    return `## Offload a big task to your GoCode server (gocode_launch_autopilot)
+
+You ALSO have a \`gocode_launch_autopilot\` MCP tool that hands a LARGE,
+multi-step coding task off to the user's own GoCode server, where it runs as an
+autonomous Autopilot loop. The user can close this IDE and shut their laptop; the
+loop keeps running server-side in their isolated sandbox, shows up in the GoCode
+phone app, and their phone is pinged when it finishes or needs them.
+
+## When to offload (trigger phrases)
+
+Reach for \`gocode_launch_autopilot\` ONLY when the user EXPLICITLY asks to run
+the work elsewhere / in the background / after they step away — e.g. "run this on
+the server", "do this overnight", "hand this off", "I'm closing my laptop, keep
+going", "offload this", "kick this off on GoCode", "fire an Autopilot loop for
+this".
+
+## Offload guardrails
+
+- **Only on an explicit ask.** Never silently move a task off this local session —
+  a normal task you can do right here STAYS here.
+- **Big tasks only.** Offload is for long, multi-step builds, not quick edits.
+- **Fresh server agent, no local file access — pass a self-contained task.** The
+  server loop is a BRAND-NEW agent with NO access to this IDE's open files or
+  unsaved/uncommitted state. Give it a complete, self-contained task description
+  (and a repo) it can act on from a clean checkout. If the task depends on local
+  uncommitted work, tell the user to commit/push first, then hand it off.
+- **After launching, stop.** Relay the loop id + that they can watch it in the
+  GoCode phone app + that they'll be pinged when it's done — then STOP. Don't keep
+  "working" locally on a task that is now running on the server.
 `;
 }
 /**

package/dist/src/send.js

@@ -12,7 +12,7 @@
 // separate tasks; this stays self-contained and dependency-free.
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { DEFAULT_SERVER, gocodeDir, readCredentials, } from "./creds.js";
+import { builtinDefaultServer, gocodeDir, readCredentials, } from "./creds.js";
 /** Canonical notification kinds accepted by `/notify/send` (PRD §3.2). */
 export const NOTIFY_KINDS = [
     "finished",
@@ -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,11 +52,15 @@ 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;
     }
+    // Boolean field — only included when explicitly true so a normal send keeps
+    // its minimal body (and the server's `autopilot` default of false applies).
+    if (payload.autopilot === true)
+        body.autopilot = true;
     return body;
 }
 /**
@@ -99,7 +110,7 @@ export async function send(payload, opts = {}) {
     if (!creds) {
         return failure("not paired — run `gocode-notify login` first", opts);
     }
-    const server = normalizeServer(opts.server ?? creds.server ?? DEFAULT_SERVER);
+    const server = normalizeServer(opts.server ?? creds.server ?? builtinDefaultServer());
     const url = `${server}/api/v1/notify/send`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);

package/dist/src/setup.js

@@ -85,9 +85,29 @@ export async function setup(opts = {}) {
     // ── Step 3: write configs for each DETECTED runtime ───────────────────────
     // Undetected runtimes are skipped silently (PRD §5.2) — only what's installed
     // gets configured.
+    //
+    // OPT-OUT: GOCODE_NOTIFY_SKIP_RUNTIMES is a comma-separated, case-insensitive
+    // list of runtime names to NOT configure even when detected (e.g.
+    // "Claude Code"). Use case: a user who runs Claude Code *inside* Cursor only
+    // wants Cursor's hooks — installing Claude's identical stop/notify hooks too
+    // would fire a SECOND, duplicate push for every turn. This is opt-in by env,
+    // so default behaviour (configure all detected runtimes) is unchanged for
+    // everyone who doesn't set it.
+    const skipRuntimes = new Set((process.env.GOCODE_NOTIFY_SKIP_RUNTIMES ?? "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0));
     const writeConfig = opts.writeConfig ?? defaultConfigWriter;
     const configs = [];
     for (const runtime of detected.filter((r) => r.detected)) {
+        if (skipRuntimes.has(runtime.name.toLowerCase())) {
+            steps.push({
+                step: `config:${runtime.name}`,
+                ok: true,
+                detail: "skipped (GOCODE_NOTIFY_SKIP_RUNTIMES)",
+            });
+            continue;
+        }
         const result = await writeConfig(runtime, pathOpts);
         configs.push(result);
         steps.push({

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.1.3";
+export const VERSION = "0.3.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trygocode/notify",
-  "version": "0.1.6",
+  "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",