@trygocode/notify 0.1.0

package/dist/src/mcp.js

@@ -0,0 +1,215 @@
+// 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
+//
+// 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`
+// 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";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { VERSION } from "./version.js";
+import { resolveServerUrl } from "./creds.js";
+import { send, isNotifyKind, NOTIFY_KINDS, } from "./send.js";
+import { gatherStatus } from "./status.js";
+/** Server identity advertised in the MCP `initialize` handshake. */
+export const SERVER_NAME = "gocode-notify";
+/**
+ * Public website for this MCP server, surfaced in the MCP `initialize`
+ * handshake (`Implementation.websiteUrl`, SEP-973). Clients that support it
+ * (MCP Inspector today; more clients over time) link the server to its docs.
+ */
+export const SERVER_WEBSITE_URL = "https://github.com/joseph-lewis/gocode-notify";
+/**
+ * Icons advertised in the MCP handshake (`Implementation.icons`, SEP-973) so
+ * clients can show the GoCode mark next to this server in their UI. Served from
+ * the public repo's `assets/` over GitHub's raw CDN so there's nothing to host.
+ *
+ * NOTE: as of 2026, Cursor does not yet RENDER custom MCP server icons (it uses
+ * hardcoded marks for a few popular servers), so this stays invisible there for
+ * now — but it already shows in MCP Inspector and other spec-compliant clients,
+ * and will light up in Cursor automatically once it adds rendering. Cheap +
+ * future-proof; no behaviour depends on it.
+ */
+export const SERVER_ICONS = [
+    {
+        src: "https://raw.githubusercontent.com/joseph-lewis/gocode-notify/main/assets/icon-128.png",
+        mimeType: "image/png",
+        sizes: ["128x128"],
+    },
+    {
+        src: "https://raw.githubusercontent.com/joseph-lewis/gocode-notify/main/assets/icon.svg",
+        mimeType: "image/svg+xml",
+        sizes: ["any"],
+    },
+];
+/** 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";
+/**
+ * The two 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.
+ */
+export const TOOLS = [
+    {
+        name: NOTIFY_TOOL,
+        description: "Send a push notification to the user's phone via the GoCode app. Call " +
+            "this ONLY when the user has EXPLICITLY asked to be pinged when something " +
+            "finishes (e.g. \"text me when the build is done\"). Routine end-of-turn " +
+            "notifications are delivered automatically by client hooks — do NOT call " +
+            "this for those, or the user gets double-pinged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: [...NOTIFY_KINDS],
+                    description: 'Notification kind. Defaults to "finished".',
+                },
+                title: {
+                    type: "string",
+                    description: "Short notification title (required).",
+                },
+                body: { type: "string", description: "Optional longer body text." },
+                project: {
+                    type: "string",
+                    description: "Optional project name shown for context.",
+                },
+            },
+            required: ["title"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: STATUS_TOOL,
+        description: "Report whether GoCode credentials are present and the notify server is " +
+            "reachable. Use this to self-diagnose: if it reports NOT paired, tell the " +
+            "user to run `gocode-notify login`.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+];
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/**
+ * Handle a `gocode_notify` tool call. Validates `title` (required) and `kind`
+ * (defaults to `finished`, must be a canonical kind), then funnels through the
+ * shared internal {@link send}. Unlike the fire-and-forget hook path, an
+ * on-demand agent ping does NOT queue to the offline outbox — a stale push
+ * surfacing later would confuse the user; instead a failure is reported back so
+ * the agent can tell the user to re-pair.
+ */
+export async function handleNotify(args, deps = {}) {
+    const a = args ?? {};
+    const title = typeof a.title === "string" ? a.title.trim() : "";
+    if (title === "") {
+        return errorResult("gocode_notify: `title` is required.");
+    }
+    const kind = a.kind === undefined ? "finished" : a.kind;
+    if (!isNotifyKind(kind)) {
+        return errorResult(`gocode_notify: invalid kind "${String(a.kind)}" (expected one of: ${NOTIFY_KINDS.join(", ")}).`);
+    }
+    const payload = { kind, title, source: "mcp" };
+    if (typeof a.body === "string" && a.body !== "")
+        payload.body = a.body;
+    if (typeof a.project === "string" && a.project !== "")
+        payload.project = a.project;
+    const server = await resolveServerUrl(deps.serverFlag, deps);
+    const sendOpts = {
+        home: deps.home,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        server,
+    };
+    const result = await send(payload, sendOpts);
+    if (result.ok) {
+        const where = typeof result.sent === "number"
+            ? ` (delivered to ${result.sent} device${result.sent === 1 ? "" : "s"})`
+            : "";
+        return textResult(`Sent ${payload.kind} notification "${title}"${where}.`);
+    }
+    return errorResult(`Could not send notification: ${result.error}. ` +
+        "If this machine is not paired, ask the user to run `gocode-notify login`.");
+}
+/**
+ * Handle a `gocode_notify_status` tool call (no args). Returns a short report of
+ * credential presence + server reachability so the agent can self-diagnose.
+ * `isError` is set when not paired OR unreachable, so the agent surfaces the
+ * problem rather than silently assuming notifications will arrive.
+ */
+export async function handleStatus(deps = {}) {
+    const report = await gatherStatus({
+        home: deps.home,
+        serverFlag: deps.serverFlag,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+    });
+    const c = report.credentials;
+    const lines = [];
+    if (c.present)
+        lines.push(`Credentials: paired as ${c.user_id} (${c.label}).`);
+    else if (c.error)
+        lines.push(`Credentials: unreadable — ${c.error}.`);
+    else
+        lines.push("Credentials: NOT paired — run `gocode-notify login`.");
+    lines.push(`Server: ${report.server.url} — ${report.server.reachable ? "reachable" : "unreachable"} (${report.server.detail}).`);
+    const ok = c.present && report.server.reachable;
+    return { content: [{ type: "text", text: lines.join("\n") }], isError: !ok };
+}
+/**
+ * Build the MCP {@link Server} with the two 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.
+ */
+export function createMcpServer(deps = {}) {
+    const server = new Server({
+        name: SERVER_NAME,
+        version: VERSION,
+        // SEP-973 server metadata: icons + website for client UIs that support it
+        // (MCP Inspector now; more clients over time). Ignored by clients that
+        // don't read them.
+        icons: [...SERVER_ICONS],
+        websiteUrl: SERVER_WEBSITE_URL,
+    }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...TOOLS] }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        if (name === NOTIFY_TOOL) {
+            return handleNotify(args, deps);
+        }
+        if (name === STATUS_TOOL) {
+            return handleStatus(deps);
+        }
+        return errorResult(`Unknown tool: ${name}`);
+    });
+    return server;
+}
+/**
+ * Run the MCP server over stdio until the client disconnects (stdin EOF). The
+ * returned promise resolves only once the connection closes, so the CLI bin
+ * stays alive for the lifetime of the session instead of exiting immediately
+ * after the handshake.
+ */
+export async function serveStdio(deps = {}) {
+    const server = createMcpServer(deps);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    await new Promise((resolve) => {
+        server.onclose = () => resolve();
+    });
+}

package/dist/src/outbox.js

@@ -0,0 +1,150 @@
+// Offline outbox for gocode-notify (PRD §4.4).
+//
+// When a `send` cannot reach the server, the notification is enqueued to
+// `~/.gocode/outbox/` and flushed opportunistically on the next `send`.
+// The contract (PRD §4.4) is deliberately SIMPLE and best-effort:
+//   - Cap the queue at {@link MAX_OUTBOX_ENTRIES}; when full, drop the OLDEST.
+//   - A missed "done" ping is acceptable; a blocked agent is not — so every
+//     operation here is best-effort and never throws for routine I/O issues.
+//
+// Each queued notification is one JSON file named with a zero-padded, strictly
+// increasing sequence so that lexicographic filename order === enqueue order.
+// That makes "oldest" unambiguous for both drop-oldest and flush ordering
+// without needing a wall-clock that could collide or run backwards.
+//
+// Zero runtime deps — only Node built-ins, to match the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gocodeDir } from "./creds.js";
+/** Maximum notifications retained in the outbox; older ones are dropped. */
+export const MAX_OUTBOX_ENTRIES = 100;
+/** Width of the zero-padded sequence in entry filenames (sortable to 1e12-1). */
+const SEQ_WIDTH = 12;
+/** Only files matching this are treated as outbox entries. */
+const ENTRY_RE = /^(\d{12})\.json$/;
+/** Absolute path to the `~/.gocode/outbox/` directory. */
+export function outboxDir(opts) {
+    return path.join(gocodeDir(opts), "outbox");
+}
+/** Pad a sequence number to a fixed, lexicographically-sortable width. */
+function seqToName(seq) {
+    return `${String(seq).padStart(SEQ_WIDTH, "0")}.json`;
+}
+/**
+ * List entry filenames in enqueue order (oldest first). Returns [] when the
+ * outbox dir is absent. Non-entry files are ignored.
+ */
+export async function listOutbox(opts) {
+    let names;
+    try {
+        names = await fs.readdir(outboxDir(opts));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    return names.filter((n) => ENTRY_RE.test(n)).sort();
+}
+/** Parse the numeric sequence out of an entry filename. */
+function seqOf(name) {
+    const m = ENTRY_RE.exec(name);
+    return m ? Number(m[1]) : 0;
+}
+/**
+ * Append `payload` to the outbox. Enforces the cap by dropping the OLDEST
+ * entries first, then writes the new entry with the next sequence. Best-effort:
+ * routine I/O failures are swallowed (a queued ping must never block the agent).
+ * Returns the entry filename on success, or null if it could not be written.
+ */
+export async function enqueue(payload, opts = {}) {
+    const max = opts.max ?? MAX_OUTBOX_ENTRIES;
+    const dir = outboxDir(opts);
+    try {
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        const existing = await listOutbox(opts);
+        // Drop oldest until there's room for one more (cap includes the new entry).
+        let entries = existing;
+        while (entries.length >= max && entries.length > 0) {
+            const oldest = entries[0];
+            await fs.rm(path.join(dir, oldest), { force: true });
+            entries = entries.slice(1);
+        }
+        // If the cap is 0 (or less), we drop everything and keep nothing.
+        if (max <= 0)
+            return null;
+        const nextSeq = entries.length > 0 ? seqOf(entries[entries.length - 1]) + 1 : 0;
+        const name = seqToName(nextSeq);
+        const entry = {
+            payload,
+            enqueued_at: opts.timestamp ? opts.timestamp() : new Date().toISOString(),
+        };
+        await fs.writeFile(path.join(dir, name), JSON.stringify(entry, null, 2) + "\n");
+        return name;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read and parse one entry file; returns null if missing or malformed. */
+async function readEntry(dir, name) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(dir, name), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && parsed.payload && typeof parsed.payload === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through — malformed entry.
+    }
+    return null;
+}
+/**
+ * Flush queued notifications oldest-first via `sender`. Each successfully sent
+ * entry is removed. On the FIRST delivery failure we stop and leave the rest
+ * queued — the server is presumably still unreachable, so hammering it (and
+ * delaying the caller) buys nothing. A malformed/unreadable entry is dropped
+ * (it can never succeed). Best-effort and never throws for routine I/O.
+ */
+export async function flush(sender, opts) {
+    const dir = outboxDir(opts);
+    let names;
+    try {
+        names = await listOutbox(opts);
+    }
+    catch {
+        return { sent: 0, remaining: 0 };
+    }
+    let sent = 0;
+    let index = 0;
+    for (; index < names.length; index++) {
+        const name = names[index];
+        const entry = await readEntry(dir, name);
+        if (!entry) {
+            // Unrecoverable entry — discard it so it never wedges the queue.
+            await fs.rm(path.join(dir, name), { force: true }).catch(() => { });
+            continue;
+        }
+        let result;
+        try {
+            result = await sender(entry.payload);
+        }
+        catch {
+            // Treat a throwing sender as a delivery failure: stop, keep the rest.
+            break;
+        }
+        if (!result.ok)
+            break;
+        await fs.rm(path.join(dir, name), { force: true }).catch(() => { });
+        sent++;
+    }
+    const remaining = (await listOutbox(opts).catch(() => [])).length;
+    return { sent, remaining };
+}

package/dist/src/push.js

@@ -0,0 +1,278 @@
+// `gocode-notify push-on-stop` — the dev-machine (P1) auto-push git flow (PRD §2.1).
+//
+// SCOPE OF THIS MODULE (T-C3): the GIT FLOW itself — steps 2–9 of PRD §2.1 —
+// driven entirely through an INJECTED git runner so it is unit-testable with a
+// fake `git` and a stubbed `send` (zero real subprocesses, zero network):
+//
+//   gate-off no-op · not-a-repo no-op · branch resolution + protected-branch
+//   guard · clean-tree no-op · compose commit message · commit (-F tempfile) ·
+//   fast-forward push (NEVER --force) · non-FF rejection → error notification ·
+//   success → ONE `finished` notification. ALL paths resolve and map to exit 0.
+//
+// What this module deliberately does NOT do (kept out of scope on purpose):
+//   • Settings RESOLUTION / 60s cache / network round-trip (PRD §2.1 step 1) —
+//     that is `config.ts` (T-C5). `pushOnStop` takes ALREADY-RESOLVED, merged
+//     settings as input; when none are supplied it fails SAFE (auto-push OFF).
+//   • The `on-stop` dispatcher + Cursor/Claude hook rewire (PRD §2.2) — that is
+//     T-C6. This module is the standalone, independently-callable git flow it
+//     will delegate to.
+//
+// Zero runtime deps — Node built-ins only (child_process / fs / os), matching the
+// package's zero-dependency rule. Git is invoked via the injectable runner whose
+// default shells out with `child_process.spawn`.
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { composeCommitMessage, parseNumstat, } from "./commit_message.js";
+import { appendLog, send } from "./send.js";
+/** Branches we refuse to auto-push to unless `allow_protected` is explicitly on (PRD §0.5). */
+export const PROTECTED_BRANCHES = new Set(["main", "master"]);
+/**
+ * Default git runner: spawn `git <args>` in `cwd`, capture stdout/stderr, and
+ * resolve with the exit code. NEVER rejects — a spawn error (e.g. git missing)
+ * resolves to a non-zero code so the flow can treat it as "not a repo / no git"
+ * rather than throwing and risking a non-zero process exit.
+ */
+export function makeGitRunner(cwd) {
+    return (args) => new Promise((resolve) => {
+        const child = spawn("git", [...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (c) => (stdout += c));
+        child.stderr.on("data", (c) => (stderr += c));
+        child.on("error", (err) => resolve({ code: 127, stdout, stderr: stderr || String(err) }));
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+/** A ready-to-use default runner bound to the current working directory. */
+export const defaultGitRunner = makeGitRunner(process.cwd());
+/** Default temp-file writer for `git commit -F` (handles multi-line bodies safely). */
+async function defaultWriteCommitFile(message) {
+    // A per-invocation random suffix avoids collisions between concurrent hooks.
+    const name = `gocode-notify-commit-${process.pid}-${randomSuffix()}.txt`;
+    const file = path.join(os.tmpdir(), name);
+    await fs.writeFile(file, message, "utf8");
+    return file;
+}
+async function defaultRemoveCommitFile(file) {
+    await fs.rm(file, { force: true }).catch(() => { });
+}
+/** Small dependency-free random hex suffix (avoids importing crypto for this). */
+function randomSuffix() {
+    return Math.trunc(Date.now() % 0xffffff).toString(16) + process.hrtime.bigint().toString(16).slice(-6);
+}
+/** True when the push branch is one we must not auto-push to without an explicit opt-in. */
+export function isProtectedBranch(branch) {
+    return PROTECTED_BRANCHES.has(branch.trim());
+}
+/** Trim a settings string to a usable value, or undefined if empty/absent. */
+function cleanBranch(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const t = value.trim();
+    return t === "" ? undefined : t;
+}
+/**
+ * Resolve the effective push branch (PRD §2.4):
+ *   1. per-repo override `auto_push.branch`, else
+ *   2. global `auto_push.default_branch`, else
+ *   3. the current checked-out branch.
+ * A CONFIGURED branch (1 or 2) that does not exist locally falls back to the
+ * current branch (never auto-created) and the fallback is noted in `detail`.
+ */
+async function resolveBranch(git, autoPush) {
+    const current = (await git(["rev-parse", "--abbrev-ref", "HEAD"])).stdout.trim();
+    const configured = cleanBranch(autoPush.branch) ?? cleanBranch(autoPush.default_branch);
+    if (!configured)
+        return { branch: current };
+    if (configured === current)
+        return { branch: current };
+    const exists = (await git(["rev-parse", "--verify", "--quiet", `refs/heads/${configured}`])).code === 0;
+    if (exists)
+        return { branch: configured };
+    return {
+        branch: current,
+        note: `configured branch "${configured}" not found locally — used current branch "${current}"`,
+    };
+}
+/** First line of a commit message (the subject), trimmed. */
+function subjectOf(message) {
+    const first = message.split("\n", 1)[0] ?? "";
+    return first.trim();
+}
+/**
+ * Run the dev-machine auto-push flow (PRD §2.1 steps 2–9). Best-effort and total:
+ * it NEVER throws and NEVER rejects — every branch returns a {@link PushResult},
+ * and the caller maps any result to process exit 0 so a slow/failed push can never
+ * block the agent's turn (PRD §0.5 "Never block the agent").
+ */
+export async function pushOnStop(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const git = opts.git ?? makeGitRunner(cwd);
+    const compose = opts.compose ?? composeCommitMessage;
+    const writeCommitFile = opts.writeCommitFile ?? defaultWriteCommitFile;
+    const removeCommitFile = opts.removeCommitFile ?? defaultRemoveCommitFile;
+    const source = opts.source ?? "unknown";
+    const settings = opts.settings ?? {};
+    const autoPush = settings.auto_push ?? {};
+    const logLine = async (line) => {
+        try {
+            if (opts.log)
+                await opts.log(line);
+            else
+                await appendLog(`PUSH: ${line}`, { home: opts.home, timestamp: opts.timestamp });
+        }
+        catch {
+            // logging must never be the thing that blocks the flow
+        }
+    };
+    const sendImpl = opts.sendImpl ??
+        ((payload) => send(payload, {
+            home: opts.home,
+            server: opts.server,
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: opts.timeoutMs,
+            timestamp: opts.timestamp,
+        }));
+    try {
+        // ── Step 2: gate. Fail-safe: anything other than an explicit `true` is OFF. ──
+        if (autoPush.enabled !== true) {
+            await logLine("auto-push disabled for this repo — no-op");
+            return { outcome: "disabled" };
+        }
+        // ── Step 3: verify git repo. `true\n` on stdout + code 0 means inside a work tree. ──
+        const inside = await git(["rev-parse", "--is-inside-work-tree"]);
+        if (inside.code !== 0 || inside.stdout.trim() !== "true") {
+            await logLine("not inside a git work tree (or git unavailable) — no-op");
+            return { outcome: "not-a-repo" };
+        }
+        // ── Step 4: resolve branch + protected-branch guard (BEFORE staging). ──
+        const { branch, note: branchNote } = await resolveBranch(git, autoPush);
+        if (branchNote)
+            await logLine(branchNote);
+        if (isProtectedBranch(branch) && autoPush.allow_protected !== true) {
+            await logLine(`skipped: "${branch}" is protected and allow_protected is off`);
+            return {
+                outcome: "protected-branch-skipped",
+                branch,
+                detail: branchNote,
+            };
+        }
+        const remote = cleanBranch(autoPush.remote) ?? "origin";
+        // ── --dry-run: report the resolved target, perform NO git writes, NO send. ──
+        if (opts.dryRun) {
+            await logLine(`dry-run: would push to ${remote} ${branch}`);
+            return { outcome: "dry-run", branch, detail: branchNote };
+        }
+        // ── Step 5: stage everything, then check for a clean tree. ──
+        await git(["add", "-A"]);
+        const numstat = await git(["diff", "--staged", "--numstat"]);
+        const files = parseNumstat(numstat.stdout);
+        if (files.length === 0) {
+            await logLine("clean tree (nothing staged) — no commit, no notification");
+            return { outcome: "clean-tree", branch, detail: branchNote };
+        }
+        // ── Step 6: compose the commit message (AI with deterministic fallback). ──
+        const mode = settings.commit_message?.mode ?? "auto";
+        let stagedDiff = "";
+        let statSummary = "";
+        if (mode !== "deterministic") {
+            stagedDiff = (await git(["diff", "--staged"])).stdout;
+            statSummary = (await git(["diff", "--staged", "--stat"])).stdout;
+        }
+        const composed = await compose({
+            files,
+            stagedDiff,
+            statSummary,
+            branch,
+            source,
+            settings: settings.commit_message,
+        });
+        // ── Step 7: commit via `-F <tempfile>` (safe multi-line / quotes). ──
+        const commitArgs = ["commit", "-F"];
+        const file = await writeCommitFile(composed.message);
+        try {
+            const args = [...commitArgs, file];
+            if (autoPush.skip_git_hooks === true)
+                args.push("--no-verify");
+            const committed = await git(args);
+            if (committed.code !== 0) {
+                await logLine(`git commit failed (code ${committed.code}): ${committed.stderr.trim()}`);
+                return {
+                    outcome: "commit-failed",
+                    branch,
+                    message: composed.message,
+                    generator: composed.generator,
+                    detail: committed.stderr.trim() || "commit failed",
+                };
+            }
+        }
+        finally {
+            await removeCommitFile(file).catch(() => { });
+        }
+        const sha = (await git(["rev-parse", "--short", "HEAD"])).stdout.trim() || undefined;
+        // ── Step 8: fast-forward push. NEVER --force. ──
+        const pushed = await git(["push", remote, branch]);
+        if (pushed.code !== 0) {
+            // Non-FF rejection (or any push failure): notify + exit 0. Never force.
+            await logLine(`push rejected (code ${pushed.code}): ${pushed.stderr.trim()}`);
+            const errorBody = isNonFastForward(pushed.stderr)
+                ? "auto-push rejected (remote moved); pull + retry"
+                : `auto-push failed: ${firstLine(pushed.stderr) || "git push error"}`;
+            const res = await sendImpl({
+                kind: "error",
+                title: "GoCode auto-push failed",
+                body: errorBody,
+                source,
+                project: opts.project,
+                dedupe_key: opts.dedupeKey,
+            });
+            return {
+                outcome: "push-rejected",
+                branch,
+                sha,
+                message: composed.message,
+                generator: composed.generator,
+                notified: res.ok,
+                detail: errorBody,
+            };
+        }
+        // ── Step 9: success → ONE finished notification carrying the commit summary. ──
+        const subject = subjectOf(composed.message);
+        const where = sha ? `${branch} @ ${sha}` : branch;
+        const res = await sendImpl({
+            kind: "finished",
+            title: `Auto-pushed to ${branch}`,
+            body: `${subject} — ${where}`,
+            source,
+            project: opts.project,
+            dedupe_key: opts.dedupeKey,
+        });
+        await logLine(`pushed ${files.length} file(s) to ${remote} ${where} (${composed.generator})`);
+        return {
+            outcome: "pushed",
+            branch,
+            sha,
+            message: composed.message,
+            generator: composed.generator,
+            notified: res.ok,
+            detail: branchNote,
+        };
+    }
+    catch (err) {
+        // Defence in depth: the flow must never throw. Any unexpected error degrades
+        // to a logged no-op so the hook's turn is never blocked (PRD §0.5).
+        await logLine(`unexpected error — treated as no-op: ${err instanceof Error ? err.message : String(err)}`);
+        return { outcome: "disabled", detail: "unexpected error" };
+    }
+}
+/** True when git's push stderr signals a non-fast-forward / rejected push. */
+export function isNonFastForward(stderr) {
+    return /\b(non-fast-forward|rejected|fetch first|tip of your current branch is behind)\b/i.test(stderr);
+}
+function firstLine(text) {
+    return (text.split("\n").find((l) => l.trim() !== "") ?? "").trim();
+}