@trygocode/notify 0.1.6 → 0.2.0

package/README.md

@@ -13,10 +13,12 @@ waiting for you**, **errors out**, or when an overnight **loop completes / halts
 - [Install — two equally-supported paths](#install--two-equally-supported-paths)
 - [Pairing — step by step](#pairing--step-by-step)
 - [The three triggers](#the-three-triggers)
+- [Hand off to your server — `launch` / `autopilot`](#hand-off-to-your-server--launch--autopilot)
 - [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)
 - [Troubleshooting](#troubleshooting)
+- [Changelog](#changelog)
 - [Develop](#develop)
 - [Layout](#layout)
 
@@ -105,6 +107,12 @@ saved in `~/.gocode/credentials` → the built-in default
 (`https://oh.jeltechsolutions.com`). You only need `--server` for a self-hosted
 or staging GoCode server.
 
+**Redistributing under your own server.** The built-in default is not baked in
+as a fixed author box — set `GOCODE_DEFAULT_SERVER` to point fresh, unpaired
+installs at your OWN GoCode server without patching the source or having every
+user pass `--server`/`GOCODE_SERVER`. It only changes the *fallback* default;
+already-paired machines keep the server in their `~/.gocode/credentials`.
+
 ## The three triggers
 
 | Trigger | Mechanism | Fires when |
@@ -133,6 +141,75 @@ never get double-pinged.
 > `setup`/`setup --force`. `send` and `test` remain callable on their own for
 > scripts and power users.
 
+## Hand off to your server — `launch` / `autopilot`
+
+> **New in 0.2.0.** Notify can now do more than ping your phone — it can **hand a
+> big task off to your GoCode server** to run as an autonomous Autopilot loop.
+> Close your laptop; the work keeps going server-side in your isolated sandbox,
+> shows up in the GoCode phone app like any other Autopilot run, and your phone
+> buzzes when it's done (or needs you).
+
+This is the opposite direction of the three notify triggers above: instead of
+*your local agent pinging your phone*, `launch` *starts a fresh server-side
+build* from an explicit, self-contained task. It reuses the **same `gck_`
+pairing** — no new login. It reads **no conversation content** (only the task
+string you hand it), so it ships in this base package (see the trust note below).
+
+### CLI
+
+```bash
+# Start a loop from a plain task (server synthesizes a PRD, then builds):
+gocode-notify launch "Refactor the auth module to use sessions, add tests" \
+  --repo owner/repo
+
+# alias:
+gocode-notify autopilot "Add a CSV export endpoint with tests" --repo owner/repo
+
+# Or hand it a pre-written checkbox PRD instead of a task string:
+gocode-notify launch --prd-file ./my-prd.md --repo owner/repo
+```
+
+| Flag | Meaning |
+|---|---|
+| `<task>` (positional) | Plain-language task the server loop builds. Mutually exclusive with `--prd-file`. |
+| `--prd-file <path>` | A pre-written checkbox PRD (base64-encoded and sent as `prd_markdown`). |
+| `--repo owner/repo` | Optional repo context for synthesis / the loop's target. |
+| `--branch <suffix>` | Optional branch suffix the loop pushes to. |
+| `--model "Profile"` | Optional LLM-profile name override. |
+| `--runner-kind <kind>` | Optional runner override (default `openhands-conversation`). |
+| `--server <URL>` | Same server-resolution precedence as every other command. |
+| `--agent-driven` | Emit one machine-readable JSON step line (for installers/agents). |
+
+On success it prints the **loop id**, a **deep link** that opens the run in the
+app, and a "running on your GoCode server — close your laptop; your phone will
+buzz when it's done" line, then exits `0`. Unlike the fire-and-forget
+`send`/`on-stop` hooks, `launch` is an **explicit interactive action**: it
+reports real failures (not paired / unreachable / 4xx) with a clear message and a
+**non-zero exit**, and it does **not** queue to the offline outbox (a stale
+launch surfacing hours later could duplicate work).
+
+### MCP tool
+
+Your desktop agent (Cursor / Claude Code / OpenCode) can fire a remote loop
+mid-session via the third MCP tool, **`gocode_launch_autopilot`**
+(`{ task (required), repo?, branch? }`). Its description tells the agent to call
+it **only when you explicitly ask to offload / run in the background / overnight**
+— never for a normal task it can do right there. On success it relays the loop id
++ deep link; on failure it returns an actionable re-pair hint.
+
+> **Heads-up the rule states:** the server loop is a **fresh agent with no access
+> to your IDE's open/unsaved files** — so the task must be **self-contained** and
+> point at a repo the server can build from a clean checkout. If the work depends
+> on local uncommitted state, commit/push first, then hand it off.
+
+### Trust boundary
+
+`launch` reads **only the explicit task string** (and optional repo/branch) you
+hand it — it does **not** read or upload your IDE conversation transcript, and it
+touches only `~/.gocode/credentials` (the `gck_` key it already uses for notify).
+It POSTs to **your own configurable GoCode server**. So the base package's "never
+reads your conversation content" promise still holds.
+
 ## Auto-push to git (opt-in)
 
 GoCode Notify can **auto-commit and push your work after every agent turn** —
@@ -310,6 +387,33 @@ For the device/secret/publish/deploy steps that are **not** part of this package
 npm publish, real-device E2E), see
 [`docs/GOCODE_NOTIFY_MANUAL_STEPS.md`](../../docs/GOCODE_NOTIFY_MANUAL_STEPS.md).
 
+## Changelog
+
+### 0.2.0
+
+- **New: `launch` / `autopilot` command** — hand a large, multi-step task off to
+  your GoCode server to run as an autonomous Autopilot loop. Reuses the existing
+  `gck_` pairing; prints a loop id + app deep link; explicit failures exit
+  non-zero (no offline queueing). See
+  [Hand off to your server](#hand-off-to-your-server--launch--autopilot).
+- **New: `gocode_launch_autopilot` MCP tool** — the third tool on the stdio MCP
+  server, so a desktop agent can fire a remote loop mid-session (explicit offload
+  only). The installed Cursor rule / Claude skill / OpenCode snippet teach the
+  agent *when* to offload and that the server loop is a fresh, self-contained
+  agent with no access to local files.
+- **App monitoring** — IDE-launched loops are discovered by the phone app
+  (`GET /api/v1/ralph/active`), badged "Launched from <IDE>", and deep-link from
+  the completion/halt push into the run — full parity with app-launched loops.
+- **Fix:** `--version` now reports the real package version. `src/version.ts` had
+  drifted (published `0.1.6` reported `0.1.3`); it is now kept in lockstep with
+  `package.json`, and the publish workflow refuses to ship a mismatch.
+
+### 0.1.x
+
+- Phone notifications for any coding agent via three triggers (runtime hook, MCP
+  tool, loop snippet), opt-in auto-push to git with an AI-written commit message,
+  and server-synced settings.
+
 ## Develop
 
 ```bash
@@ -331,7 +435,8 @@ Zero runtime dependencies beyond the MCP SDK (Node built-in `fetch`/`fs`/
 | `src/cli.ts` | `gocode-notify` bin entrypoint + command dispatcher (incl. `on-stop`, `config`) |
 | `src/setup.ts` | Installer orchestration (pair → detect → write configs) |
 | `src/claude.ts` / `src/cursor.ts` / `src/opencode.ts` | Per-client config writers (hooks + MCP + rule/skill); hooks call the `on-stop` dispatcher. OpenCode uses a `session.idle` plugin instead of a hooks file |
-| `src/send.ts` / `src/login.ts` / `src/mcp.ts` | Core send, pairing, and MCP server |
+| `src/send.ts` / `src/login.ts` / `src/mcp.ts` | Core send, pairing, and MCP server (incl. `gocode_launch_autopilot`) |
+| `src/launch.ts` | Shared `launch()` core behind the `launch`/`autopilot` command + the MCP tool |
 | `src/push.ts` | Auto-push flow behind the `on-stop` dispatcher — git add/commit/push, FF-only |
 | `src/commit_message.ts` | AI commit-message resolution chain + deterministic fallback |
 | `src/config.ts` | `config get\|set\|pull` — the dev-machine settings editor (server-synced) |

package/dist/src/cli.js

@@ -6,10 +6,12 @@
 // later milestones. For now the entrypoint resolves help/version and reports
 // not-yet-implemented for the known commands so the bin is wired and testable.
 import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { VERSION } from "./version.js";
 import { login } from "./login.js";
 import { resolveServerUrl } from "./creds.js";
+import { launch } from "./launch.js";
 import { send, isNotifyKind, NOTIFY_KINDS, } from "./send.js";
 import { enqueue, flush } from "./outbox.js";
 import { gatherStatus, formatStatus, formatStatusSteps } from "./status.js";
@@ -30,7 +32,12 @@ export const COMMANDS = [
     "uninstall",
     "config",
     "on-stop",
+    "launch",
 ];
+/** Aliases that route to a canonical command in {@link runAsync}. */
+export const COMMAND_ALIASES = {
+    autopilot: "launch",
+};
 export function printHelp() {
     console.log([
         `gocode-notify v${VERSION}`,
@@ -49,6 +56,7 @@ export function printHelp() {
         "  uninstall  Remove entries this tool added",
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
         "  on-stop    End-of-turn dispatcher (auto-push or finished ping)",
+        "  launch     Hand a big task off to your GoCode server (alias: autopilot)",
         "",
         "  -h, --help       Show this help",
         "  -v, --version    Print the version",
@@ -89,6 +97,30 @@ function flagString(flags, name) {
     const v = flags.get(name);
     return typeof v === "string" ? v : undefined;
 }
+/**
+ * Collect the bare positional arguments from an argv slice, mirroring the exact
+ * value-consumption logic of {@link parseFlags} so a positional is never confused
+ * with a flag's value. A `--flag value` pair consumes `value`; a `--flag=value`
+ * or a trailing/boolean `--flag` consumes nothing. Everything left over (an arg
+ * not starting with `--` and not eaten as a flag value) is a positional. Used by
+ * `launch`, whose task string is positional (PRD §4.2).
+ */
+export function collectPositionals(argv) {
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            if (arg.indexOf("=") !== -1)
+                continue;
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--"))
+                i++;
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return positionals;
+}
 /** Handle `gocode-notify login [--code N] [--label "..."] [--server URL] [--agent-driven]`. */
 export async function cmdLogin(args, deps = {}) {
     const flags = parseFlags(args);
@@ -183,6 +215,10 @@ export async function cmdSend(args, deps = {}) {
     const dedupeKey = flagString(flags, "dedupe-key");
     if (dedupeKey)
         payload.dedupe_key = dedupeKey;
+    // --autopilot forces the "Autopilot" tray badge on (loop kinds are badged
+    // automatically server-side; this is for an explicit non-loop Autopilot send).
+    if (flagBool(flags, "autopilot"))
+        payload.autopilot = true;
     const server = await resolveServerUrl(flagString(flags, "server"), deps);
     const sendOpts = {
         home: deps.home,
@@ -415,7 +451,9 @@ export async function cmdOnStop(args, deps = {}) {
         ? `auto-push: ${result.push?.outcome ?? "unknown"}${delivered ? " (notified)" : ""}`
         : result.mode === "dry-run-send"
             ? "dry-run: would send finished (auto-push off)"
-            : `finished ${delivered ? "delivered" : "not delivered"}`;
+            : result.mode === "deduped"
+                ? "deduped: another source already notified for this run"
+                : `finished ${delivered ? "delivered" : "not delivered"}`;
     if (agent) {
         sink({ step: "on-stop", ok: true, detail });
     }
@@ -425,6 +463,96 @@ export async function cmdOnStop(args, deps = {}) {
     // PRD §0.5 / §4.4: a stop hook must NEVER block the turn — always exit 0.
     return 0;
 }
+/**
+ * Handle `gocode-notify launch "<task>" [--repo owner/repo] [--branch suffix]
+ * [--prd-file path.md] [--model "Profile"] [--runner-kind K] [--server URL]
+ * [--agent-driven]` (alias `autopilot`). Hands a big, multi-step task off to the
+ * user's GoCode server to run as an autonomous Autopilot loop (PRD §4.2).
+ *
+ * The positional task string maps to `message`; `--prd-file` reads a file and
+ * sends it as `prd_markdown` instead — the two are mutually exclusive (a usage
+ * error → exit 2, before any network). Unlike the fire-and-forget `send`/`on-stop`
+ * hooks, `launch` is an explicit, interactive action: it reports real failures
+ * with a NON-zero exit (like `test`) and never queues to the offline outbox.
+ */
+export async function cmdLaunch(args, deps = {}) {
+    const flags = parseFlags(args);
+    const agent = isAgentDriven(flags);
+    const sink = deps.sink ?? stdoutSink;
+    const fail = (detail, code) => {
+        if (agent)
+            sink({ step: "launch", ok: false, detail });
+        else
+            console.error(`gocode-notify launch: ${detail}`);
+        return code;
+    };
+    // Drop the `--agent-driven` boolean from positionals so it is never mistaken
+    // for the task string; everything else not consumed as a flag value is a task.
+    const positionals = collectPositionals(args);
+    const task = positionals.length > 0 ? positionals.join(" ") : undefined;
+    const prdFile = flagString(flags, "prd-file");
+    // Exactly-one-of the two task sources — caught locally before any network so
+    // the user gets a clear usage error (the server enforces the same rule, 422).
+    if (task !== undefined && prdFile !== undefined) {
+        return fail("provide either a task string OR --prd-file, not both", 2);
+    }
+    if (task === undefined && prdFile === undefined) {
+        return fail('a task is required: gocode-notify launch "<task>" (or --prd-file <path>)', 2);
+    }
+    const input = {};
+    if (prdFile !== undefined) {
+        try {
+            input.prdMarkdown = await readFile(prdFile, "utf8");
+        }
+        catch (err) {
+            return fail(`could not read --prd-file ${prdFile}: ${err instanceof Error ? err.message : String(err)}`, 2);
+        }
+        input.prdFilename = prdFile.split("/").pop() || prdFile;
+    }
+    else {
+        input.message = task;
+    }
+    const repo = flagString(flags, "repo");
+    if (repo)
+        input.selectedRepository = repo;
+    const branch = flagString(flags, "branch");
+    if (branch)
+        input.branchSuffix = branch;
+    const model = flagString(flags, "model");
+    if (model)
+        input.modelOverride = model;
+    const runnerKind = flagString(flags, "runner-kind");
+    if (runnerKind)
+        input.runnerKind = runnerKind;
+    const launchFn = deps.launchImpl ?? launch;
+    const result = await launchFn(input, {
+        home: deps.home,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        timestamp: deps.timestamp,
+        env: deps.env,
+        serverFlag: flagString(flags, "server"),
+    });
+    if (!result.ok) {
+        // launch()'s error strings are already actionable (re-pair hint, status, etc.).
+        return fail(result.error ?? "launch failed", 1);
+    }
+    const loop = result.loop_id ?? "(id pending)";
+    const link = result.deep_link;
+    const tail = "Running on your GoCode server — close your laptop; your phone will buzz when it's done.";
+    if (agent) {
+        const where = link ? ` (${link})` : "";
+        sink({ step: "launch", ok: true, detail: `launched loop ${loop}${where}` });
+    }
+    else {
+        console.log(`✓ Autopilot launched on your GoCode server.`);
+        console.log(`  Loop: ${loop}`);
+        if (link)
+            console.log(`  Open: ${link}`);
+        console.log(`  ${tail}`);
+    }
+    return 0;
+}
 /** Synchronous dispatcher: help/version/unknown + not-yet-implemented commands. */
 export function run(argv) {
     const cmd = argv[0];
@@ -468,6 +596,8 @@ export async function runAsync(argv) {
         return cmdConfig(argv.slice(1));
     if (cmd === "on-stop")
         return cmdOnStop(argv.slice(1));
+    if (cmd === "launch" || cmd === "autopilot")
+        return cmdLaunch(argv.slice(1));
     return run(argv);
 }
 /**

package/dist/src/creds.js

@@ -7,12 +7,41 @@
 // Server-URL precedence (PRD §4.2, the acceptance criterion for this task):
 //   --server flag  >  GOCODE_SERVER env  >  credentials file  >  built-in default
 //
+// The "built-in default" itself is configurable at distribution/build time via
+// GOCODE_DEFAULT_SERVER (PRD §6/§7 — "never hardcode the author's box for the
+// world's installs"): an open-source redistribution can point new, unpaired
+// installs at its OWN GoCode server without patching this source literal.
+//
 // Zero runtime deps — only Node built-ins, to match the package's zero-dep rule.
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-/** Built-in default server, used when nothing else resolves a URL. */
+/**
+ * Compiled-in fallback server, used ONLY when neither the caller, the env, the
+ * credentials file, nor the GOCODE_DEFAULT_SERVER distribution override resolves
+ * a URL. Open-source forks set GOCODE_DEFAULT_SERVER (see {@link builtinDefaultServer})
+ * rather than editing this literal, so no fork is forced to ship the author's box.
+ */
 export const DEFAULT_SERVER = "https://oh.jeltechsolutions.com";
+/**
+ * Env var that overrides the built-in default server at distribution/build time.
+ * Distinct from `GOCODE_SERVER` (a per-run user override that outranks the
+ * credentials file): `GOCODE_DEFAULT_SERVER` only sets the *fallback* a fresh,
+ * unpaired install resolves to, so a redistribution can rebrand the default
+ * target without touching paired users' `~/.gocode/credentials`.
+ */
+export const DEFAULT_SERVER_ENV = "GOCODE_DEFAULT_SERVER";
+/**
+ * The effective built-in default: the `GOCODE_DEFAULT_SERVER` distribution
+ * override when it is set to a non-empty value, else the compiled-in
+ * {@link DEFAULT_SERVER} literal. Read live (not cached at import) so a
+ * redistribution/build/CI can set it without re-importing the module, and so
+ * tests can exercise the override. The result is trimmed + trailing-slash-stripped.
+ */
+export function builtinDefaultServer() {
+    const override = firstNonEmpty(process.env[DEFAULT_SERVER_ENV]);
+    return normalizeServer(override ?? DEFAULT_SERVER);
+}
 /**
  * Resolve the home directory. Prefers an explicit override, then `$HOME`
  * (so tests can point at a temp dir via the env), then `os.homedir()`.
@@ -129,9 +158,9 @@ export async function writeConfig(config, opts) {
  * The result is trimmed and has trailing slashes stripped.
  */
 export function resolveServer(sources) {
-    const chosen = firstNonEmpty(sources.flag, sources.env, sources.creds?.server, sources.default ?? DEFAULT_SERVER);
+    const chosen = firstNonEmpty(sources.flag, sources.env, sources.creds?.server, sources.default ?? builtinDefaultServer());
     // The default is always non-empty, so `chosen` is defined here.
-    return normalizeServer(chosen ?? DEFAULT_SERVER);
+    return normalizeServer(chosen ?? builtinDefaultServer());
 }
 /**
  * Convenience wrapper: resolve the server URL using the `--server` flag, the

package/dist/src/launch.js

@@ -0,0 +1,218 @@
+// Internal launch() — the single code path every desktop trigger (CLI / MCP)
+// funnels through to POST `/api/v1/notify/launch`, which starts a server-side
+// Autopilot loop for the `gck_` key's bound user (Remote Autopilot Launch PRD
+// §4.1). It mirrors `send()` as the shared core (PRD §4 "all three funnel
+// through the same internal launch()").
+//
+// Contract (PRD §4.2 / §4.3 "launch is explicit, not fire-and-forget"):
+//   - Reads the `gck_` key from `~/.gocode/credentials` (same path as `send()`).
+//   - Resolves the server URL with full precedence (flag → env → creds →
+//     default) via `resolveServerUrl`.
+//   - Auto-detects the IDE label (best-effort, label only, falls back to "ide").
+//   - POSTs the task/PRD; on success returns the 202 projection
+//     `{ ok, loop_id?, project_id?, conversation_id?, prd_title?, origin?,
+//     deep_link? }`; on any failure returns `{ ok: false, error }`.
+//   - NEVER throws / rejects — always resolves to a {@link LaunchResult}. The
+//     CLI/MCP layer decides the exit code / how to relay it (unlike `send`,
+//     launch reports real failures with a non-zero exit, but the *core* still
+//     returns a result rather than throwing).
+//   - Does NOT queue to the offline outbox — a stale launch surfacing hours
+//     later would be surprising and could duplicate work (PRD §4.2).
+//
+// Failures are appended to `~/.gocode/notify.log` (the same trail `send` uses).
+// Zero runtime deps — Node built-ins only, matching the package rule.
+import { builtinDefaultServer, readCredentials, resolveServerUrl, } from "./creds.js";
+import { appendLog } from "./send.js";
+/** The launch endpoint path on the notify router (PRD §3.2). */
+export const LAUNCH_PATH = "/api/v1/notify/launch";
+/**
+ * Default request timeout. Longer than `send`'s 5s hard cap because the server
+ * may run a PRD-synthesis turn before spawning the loop (PRD §3.2 step 5). Still
+ * bounded so a wedged server can never hang the desktop agent indefinitely.
+ */
+export const DEFAULT_LAUNCH_TIMEOUT_MS = 30_000;
+/**
+ * Canonical IDE labels the server understands (PRD §3.2). The label is sanitized
+ * + capped server-side; this is just the best-effort client classification.
+ */
+export const IDE_LABEL_FALLBACK = "ide";
+function errMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Strip trailing slashes so `${server}${path}` is always clean. */
+function normalizeServer(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+/** True when `env` has any key beginning with `prefix` (case-sensitive). */
+function hasEnvPrefix(env, prefix) {
+    for (const key of Object.keys(env)) {
+        if (key.startsWith(prefix) && env[key] !== undefined && env[key] !== "") {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Best-effort classify the IDE the agent runs in from its environment (PRD
+ * §4.1). Cursor exports `CURSOR_*`, Claude Code `CLAUDECODE`/`CLAUDE_*`, OpenCode
+ * `OPENCODE_*`. Returns one of the canonical labels (`cursor` / `claude_code` /
+ * `opencode`) or {@link IDE_LABEL_FALLBACK} when none is recognised. Never throws.
+ */
+export function detectIdeLabel(env = process.env) {
+    // Claude Code sets CLAUDECODE=1 plus assorted CLAUDE_* vars.
+    if (env.CLAUDECODE || hasEnvPrefix(env, "CLAUDE_CODE") || hasEnvPrefix(env, "CLAUDE")) {
+        return "claude_code";
+    }
+    if (hasEnvPrefix(env, "CURSOR"))
+        return "cursor";
+    if (hasEnvPrefix(env, "OPENCODE"))
+        return "opencode";
+    return IDE_LABEL_FALLBACK;
+}
+/**
+ * Build the JSON request body for `/notify/launch`. Exactly one of `message` /
+ * `prd_markdown` is included; `prd_markdown` is base64-encoded from the raw
+ * input. Optional fields are dropped when unset. The server forces `origin`
+ * itself (its schema is `extra="forbid"`), so we never send it — including it
+ * would be rejected with a 422.
+ */
+function buildBody(input, ide) {
+    const body = {};
+    if (input.message && input.message.trim() !== "") {
+        body.message = input.message;
+    }
+    else if (input.prdMarkdown && input.prdMarkdown !== "") {
+        body.prd_markdown = Buffer.from(input.prdMarkdown, "utf8").toString("base64");
+    }
+    const optional = [
+        ["prdFilename", "prd_filename"],
+        ["selectedRepository", "selected_repository"],
+        ["branchSuffix", "branch_suffix"],
+        ["runnerKind", "runner_kind"],
+        ["modelOverride", "model_override"],
+    ];
+    for (const [from, to] of optional) {
+        const v = input[from];
+        if (typeof v === "string" && v.trim() !== "")
+            body[to] = v;
+    }
+    if (ide && ide.trim() !== "")
+        body.ide = ide;
+    return body;
+}
+async function failure(reason, opts, extra = {}) {
+    await appendLog(`LAUNCH FAIL: ${reason}`, opts);
+    return { ok: false, error: reason, ...extra };
+}
+/** Pull a readable reason out of a FastAPI error body (`{detail: ...}`). */
+function extractDetail(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const detail = parsed.detail;
+    if (typeof detail === "string")
+        return detail;
+    if (detail && typeof detail === "object") {
+        const reason = detail.reason;
+        const text = detail.detail;
+        const parts = [reason, text].filter((p) => typeof p === "string");
+        if (parts.length)
+            return parts.join(": ");
+        try {
+            return JSON.stringify(detail);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Launch a server-side Autopilot loop. Resolves (never rejects) to a
+ * {@link LaunchResult}. The caller is responsible for exit code / messaging.
+ */
+export async function launch(input, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_LAUNCH_TIMEOUT_MS;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const env = opts.env ?? process.env;
+    // Local exactly-one-of guard — gives the CLI/MCP a clear error before any
+    // network round-trip (the server enforces the same rule with a 422).
+    const hasMessage = !!(input.message && input.message.trim() !== "");
+    const hasPrd = !!(input.prdMarkdown && input.prdMarkdown !== "");
+    if (hasMessage === hasPrd) {
+        const reason = hasMessage
+            ? "provide either a task message OR a PRD, not both"
+            : "a task message or PRD is required";
+        return failure(reason, opts);
+    }
+    let creds;
+    try {
+        creds = await readCredentials(opts);
+    }
+    catch (err) {
+        return failure(`credentials unreadable: ${errMessage(err)}`, opts);
+    }
+    if (!creds) {
+        return failure("not paired — run `gocode-notify login` first", opts);
+    }
+    const server = normalizeServer(opts.server ?? (await resolveServerUrl(opts.serverFlag, opts)) ?? builtinDefaultServer());
+    const url = `${server}${LAUNCH_PATH}`;
+    const ide = input.ide && input.ide.trim() !== "" ? input.ide.trim() : detectIdeLabel(env);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${creds.api_key}`,
+            },
+            body: JSON.stringify(buildBody(input, ide)),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            let detail;
+            try {
+                detail = extractDetail(await res.json());
+            }
+            catch {
+                // Non-JSON / empty error body — fall back to the bare status.
+            }
+            const suffix = detail ? `: ${detail}` : "";
+            return failure(`server responded ${res.status}${suffix}`, opts, {
+                status: res.status,
+            });
+        }
+        let parsed = {};
+        try {
+            parsed = (await res.json());
+        }
+        catch {
+            // A 2xx with an unparseable body still counts as launched, but we have no
+            // ids to relay — surface that rather than pretending we got the projection.
+            return { ok: true, status: res.status, ide };
+        }
+        const str = (k) => typeof parsed[k] === "string" ? parsed[k] : undefined;
+        return {
+            ok: true,
+            status: res.status,
+            loop_id: str("loop_id"),
+            project_id: str("project_id"),
+            conversation_id: str("conversation_id"),
+            prd_title: str("prd_title"),
+            origin: str("origin"),
+            deep_link: str("deep_link"),
+            ide,
+        };
+    }
+    catch (err) {
+        const reason = controller.signal.aborted
+            ? `timeout after ${timeoutMs}ms`
+            : `request failed: ${errMessage(err)}`;
+        return failure(reason, opts);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/mcp.js

@@ -1,13 +1,15 @@
 // gocode-notify MCP server mode (`gocode-notify mcp`) — PRD §4.3.
 //
-// A minimal stdio MCP server exposing EXACTLY two tools (keep it tiny — more
-// tools = more agent confusion):
-//   - gocode_notify         → on-demand push (thin wrapper over internal send())
-//   - gocode_notify_status  → creds-present + server-reachable self-diagnosis
+// A minimal stdio MCP server exposing THREE tools (keep it tiny + the
+// descriptions sharp — more tools = more agent confusion):
+//   - gocode_notify           → on-demand push (thin wrapper over internal send())
+//   - gocode_notify_status    → creds-present + server-reachable self-diagnosis
+//   - gocode_launch_autopilot → hand a BIG task off to the user's GoCode server
+//                               to run as a server-side Autopilot loop (launch())
 //
-// Both handlers funnel through the SAME internals as the CLI (`send()` /
-// `gatherStatus()`), so behaviour is identical across every trigger (hook /
-// loop / MCP / CLI). We use the official MCP TypeScript SDK low-level `Server`
+// All handlers funnel through the SAME internals as the CLI (`send()` /
+// `gatherStatus()` / `launch()`), so behaviour is identical across every trigger
+// (hook / loop / MCP / CLI). We use the official MCP TypeScript SDK low-level `Server`
 // with raw JSON-Schema tool definitions — no zod in our OWN code — so the
 // package's direct dependency stays just `@modelcontextprotocol/sdk`.
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -17,17 +19,21 @@ import { VERSION } from "./version.js";
 import { resolveServerUrl } from "./creds.js";
 import { send, isNotifyKind, NOTIFY_KINDS, } from "./send.js";
 import { gatherStatus } from "./status.js";
+import { launch } from "./launch.js";
 /** Server identity advertised in the MCP `initialize` handshake. */
 export const SERVER_NAME = "gocode-notify";
 /** Tool name an agent calls to send an on-demand push. */
 export const NOTIFY_TOOL = "gocode_notify";
 /** Tool name an agent calls to self-diagnose pairing/reachability. */
 export const STATUS_TOOL = "gocode_notify_status";
+/** Tool name an agent calls to offload a big task to the user's server. */
+export const LAUNCH_TOOL = "gocode_launch_autopilot";
 /**
- * The two tools this server exposes (PRD §4.3). Declared as a plain constant so
+ * The three tools this server exposes (PRD §4.3). Declared as a plain constant so
  * the handshake smoke test can assert the exact shape without spinning the
  * transport. `gocode_notify`'s schema mirrors the documented args
- * `{ kind?, title, body?, project? }`; only `title` is required.
+ * `{ kind?, title, body?, project? }` (only `title` is required);
+ * `gocode_launch_autopilot`'s schema is `{ task(req), repo?, branch? }`.
  */
 export const TOOLS = [
     {
@@ -70,6 +76,38 @@ export const TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: LAUNCH_TOOL,
+        description: "Hand a LARGE, multi-step coding task off to the user's GoCode server to run " +
+            "as an autonomous Autopilot loop — so it keeps running after the user closes " +
+            "their laptop, and their phone is notified when it's done. Call this ONLY " +
+            "when the user EXPLICITLY asks to offload/hand-off work to their server or to " +
+            "run something in the background / overnight / after they close their machine " +
+            '(e.g. "run this on the server", "do this overnight", "hand this off so I ' +
+            'can shut down"). Do NOT call it for normal tasks you can do right here — ' +
+            "those stay in this IDE session. The server loop is a FRESH agent with NO " +
+            "access to this IDE's open files / unsaved state, so pass a self-contained " +
+            "task description (and a repo) it can act on from a clean checkout.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "Plain-language task for the server loop to build. Required.",
+                },
+                repo: {
+                    type: "string",
+                    description: "Optional owner/repo context for the loop.",
+                },
+                branch: {
+                    type: "string",
+                    description: "Optional branch suffix the loop pushes to.",
+                },
+            },
+            required: ["task"],
+            additionalProperties: false,
+        },
+    },
 ];
 function textResult(text) {
     return { content: [{ type: "text", text }] };
@@ -143,7 +181,49 @@ export async function handleStatus(deps = {}) {
     return { content: [{ type: "text", text: lines.join("\n") }], isError: !ok };
 }
 /**
- * Build the MCP {@link Server} with the two tools registered. Pure (does not
+ * Handle a `gocode_launch_autopilot` tool call. Validates `task` (required,
+ * non-empty), then funnels through the shared internal {@link launch} — the SAME
+ * code path as the CLI `launch` command — to start a server-side Autopilot loop
+ * for the `gck_` key's bound user. The `origin: ide-launch` + detected `ide`
+ * label are set inside `launch()`/server-side, so the agent never smuggles them.
+ * Like the notify tool, it does NOT queue offline — a remote launch is explicit
+ * and must report real failures back so the agent can re-pair / retry.
+ */
+export async function handleLaunch(args, deps = {}) {
+    const a = args ?? {};
+    const task = typeof a.task === "string" ? a.task.trim() : "";
+    if (task === "") {
+        return errorResult("gocode_launch_autopilot: `task` is required.");
+    }
+    const input = { message: task };
+    if (typeof a.repo === "string" && a.repo.trim() !== "") {
+        input.selectedRepository = a.repo.trim();
+    }
+    if (typeof a.branch === "string" && a.branch.trim() !== "") {
+        input.branchSuffix = a.branch.trim();
+    }
+    const result = await launch(input, {
+        home: deps.home,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        serverFlag: deps.serverFlag,
+    });
+    if (!result.ok) {
+        return errorResult(`Could not launch Autopilot loop: ${result.error}. ` +
+            "If this machine is not paired, ask the user to run `gocode-notify login`.");
+    }
+    const loop = result.loop_id ?? "(id pending)";
+    const lines = [
+        `Autopilot launched on your GoCode server (loop ${loop}).`,
+    ];
+    if (result.deep_link)
+        lines.push(`Open in the app: ${result.deep_link}`);
+    lines.push("It's running on your server — you can close your laptop; your phone will " +
+        "buzz when it's done or needs you.");
+    return textResult(lines.join("\n"));
+}
+/**
+ * Build the MCP {@link Server} with the three tools registered. Pure (does not
  * touch the network or connect a transport) so the handshake smoke test can
  * drive it over an in-memory transport.
  */
@@ -158,6 +238,9 @@ export function createMcpServer(deps = {}) {
         if (name === STATUS_TOOL) {
             return handleStatus(deps);
         }
+        if (name === LAUNCH_TOOL) {
+            return handleLaunch(args, deps);
+        }
         return errorResult(`Unknown tool: ${name}`);
     });
     return server;

package/dist/src/on_stop.js

@@ -29,6 +29,7 @@ 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";
 /** Slice the merged settings down to what the push flow consumes. */
 function toPushSettings(settings) {
     return {
@@ -114,6 +115,32 @@ export async function onStop(opts = {}) {
             await logLine(`dry-run: would send finished (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.
+        // 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: "finished",
+                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 finished (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;

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",
@@ -50,6 +50,10 @@ function buildBody(payload) {
         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 +103,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/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.2.0";

package/package.json

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