@trygocode/notify 0.1.6 → 0.3.1

package/README.md

@@ -13,10 +13,13 @@ 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)
+- [Notify from any custom script (the minimal one-liner)](#notify-from-any-custom-script-the-minimal-one-liner)
 - [Troubleshooting](#troubleshooting)
+- [Changelog](#changelog)
 - [Develop](#develop)
 - [Layout](#layout)
 
@@ -105,6 +108,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 |
@@ -117,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
@@ -133,6 +157,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** —
@@ -239,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) |
@@ -281,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
@@ -310,6 +438,56 @@ 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.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
+  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 +509,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";
@@ -19,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",
@@ -26,11 +29,54 @@ export const COMMANDS = [
     "test",
     "setup",
     "status",
+    "doctor",
     "mcp",
     "uninstall",
     "config",
     "on-stop",
+    "launch",
 ];
+/** Aliases that route to a canonical command in {@link runAsync}. */
+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}`,
@@ -45,10 +91,12 @@ 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)",
         "  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 +137,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 +255,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,
@@ -288,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);
@@ -393,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({
@@ -405,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
@@ -415,7 +523,11 @@ 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"
+                : 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 });
     }
@@ -425,6 +537,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];
@@ -458,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")
@@ -468,6 +672,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