@firefunc-agent/runner 0.5.0

package/LICENSE

@@ -0,0 +1,65 @@
+FireFunc Runner — Client Software Licence
+Copyright (c) 2026 FireFunc. All rights reserved.
+
+This licence covers ONLY the `@firefunc/runner` package (the "Runner") — the
+client daemon that runs on your own machine, invokes coding agents you have
+installed and licensed yourself, and connects to the FireFunc service.
+
+It does NOT cover the FireFunc service, its API, its web applications, its
+infrastructure, or any other part of the FireFunc source, all of which remain
+proprietary and are governed by the LICENSE file at the root of the FireFunc
+repository. Nothing here grants any right to that software.
+
+1. GRANT
+
+   You may download, install, and run the Runner, on any number of machines you
+   own or control, free of charge, for the purpose of connecting those machines
+   to the FireFunc service.
+
+   You may run it against a FireFunc account you are authorised to use. No
+   licence key, subscription, or payment is required to run the Runner itself.
+
+2. RESTRICTIONS
+
+   You may not:
+
+   (a) modify the Runner, or create derivative works of it;
+   (b) redistribute it, whether modified or unmodified, including by
+       republishing it to a package registry under any name;
+   (c) reverse engineer, decompile, or disassemble it, except to the extent
+       that applicable law expressly permits despite this restriction;
+   (d) remove or alter this licence, any copyright notice, or any attribution
+       it contains;
+   (e) use it to access, probe, or interfere with the FireFunc service other
+       than as its published interfaces intend.
+
+   Installing the Runner as a dependency of your own project, and running it in
+   your own automation, is normal use and is not redistribution.
+
+3. THIRD-PARTY AGENTS
+
+   The Runner invokes coding agents — Claude Code, OpenAI Codex, Gemini CLI,
+   Cursor CLI and others — that it does not include and does not license to you.
+   You install those yourself and use them under their own terms, billed to your
+   own accounts. FireFunc neither resells nor proxies them.
+
+4. YOUR CODE
+
+   The Runner executes on your machine, against your repositories, using your
+   credentials. FireFunc does not require, and the Runner does not transmit,
+   your source code to the FireFunc service in order to function.
+
+5. NO WARRANTY
+
+   THE RUNNER IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE RUNNER OR ITS USE.
+
+6. TERMINATION
+
+   This licence terminates automatically if you breach section 2. On
+   termination you must stop using the Runner and delete your copies. Sections
+   5 and 6 survive.

package/README.md

@@ -0,0 +1,88 @@
+# firefunc-runner
+
+Run **your own** Claude Code on bugs FireFunc routes to you — and open PRs automatically.
+
+This is the **self-hosted runner** for FireFunc's _Claude Code Channel_ engine. It's a tiny always-on daemon on your machine (laptop, dev box, CI host) that:
+
+1. **long-polls FireFunc** (outbound only — works behind NAT/VPN, no inbound ports),
+2. **claims** a bug FireFunc dispatched to your project,
+3. runs **your local Claude Code** (`claude -p`) in an isolated git worktree off a clean base branch,
+4. opens a **draft PR** and reports the result back.
+
+**Why this and not the cloud Routine?** No ~15/day cap (it uses _your_ Claude subscription's limits), your **code never leaves your machine**, and it has your full local context — running app, AWS creds, `gh`/`git` auth, MCP servers, `CLAUDE.md`.
+
+## Requirements
+
+- Node ≥ 20
+- [Claude Code](https://code.claude.com) installed and signed in (`claude` on your PATH)
+- `git` and the [GitHub CLI](https://cli.github.com) (`gh`) signed in, with push access to the repos
+- A local checkout of each repo FireFunc will fix
+
+## Quick start
+
+```bash
+# Install once (or skip it and use npx, as below).
+npm install -g @firefunc-agent/runner
+
+# 1. In FireFunc: Engines → "Add a machine". Copy the WHOLE command it shows —
+#    it already contains your one-time token (ffr_…) and your API URL.
+
+# 2. On your machine — the copied command looks like this:
+npx @firefunc-agent/runner connect ffr_xxxxx --api https://your-firefunc-host --repos-dir ~/code
+#    (or map a repo exactly: --repo acme/api=/Users/me/code/api)
+
+# 3. Go online:
+npx @firefunc-agent/runner start
+```
+
+`--api` is required: this package has no hard-coded FireFunc host, so it only
+ever talks to the deployment you point it at.
+
+That's it. When your QA files a bug (labeled for FireFunc), it appears here within seconds, gets fixed, and a draft PR shows up — all visible in the FireFunc dashboard.
+
+## Safety
+
+- Works in a throwaway **git worktree** off a clean base — it **never touches your working tree or current branch**.
+- Opens a PR **only when there's a real diff** (no phantom PRs).
+- Pushes a **deterministic branch** with `--force-with-lease`, so a duplicate dispatch converges to one PR.
+- Runs Claude with `--permission-mode acceptEdits` (autonomous file edits) **without** `--dangerously-skip-permissions` (which hangs non-interactive daemons).
+- A per-job timeout (default 20 min) prevents a stuck run from hanging the daemon.
+
+## Commands
+
+| Command                                   | What it does                                                             |
+| ----------------------------------------- | ------------------------------------------------------------------------ |
+| `firefunc-runner connect <token> [flags]` | Save your token + settings (`~/.firefunc-runner/config.json`, mode 0600) |
+| `firefunc-runner start`                   | Start the always-on daemon                                               |
+| `firefunc-runner status`                  | Show the saved config                                                    |
+
+### `connect` flags
+
+| Flag                        | Default          | Meaning                                                        |
+| --------------------------- | ---------------- | -------------------------------------------------------------- |
+| `--api <url>`               | — (**required**) | Your FireFunc API URL — the copied command fills this in       |
+| `--name <name>`             | hostname         | Friendly runner name (shown in the dashboard)                  |
+| `--repos-dir <dir>`         | —                | Base dir; repos are matched by name (`acme/api` → `<dir>/api`) |
+| `--repo <owner/repo=/path>` | —                | Map one repo to an exact checkout (repeatable)                 |
+| `--claude-bin <bin>`        | `claude`         | Claude Code binary                                             |
+
+## Run it as a service
+
+Keep it alive across reboots with launchd (macOS), systemd (Linux), or `pm2`:
+
+```bash
+pm2 start "npx @firefunc-agent/runner start" --name firefunc-runner
+pm2 save
+```
+
+## Licence
+
+`@firefunc-agent/runner` is the **client** half of FireFunc, published so the machines
+that do the work can actually install it. It is free to download and run against
+a FireFunc account you are authorised to use — see [LICENSE](./LICENSE).
+
+The FireFunc service itself (API, workers, dashboard, infrastructure) is
+proprietary and is not distributed here. This package contains only the daemon
+that runs on your machine: it invokes coding agents **you** installed and pay
+for, works on **your** checkouts, and reports results back. Your source code
+does not need to reach FireFunc for any of it to work.

package/dist/api.d.ts

@@ -0,0 +1,64 @@
+export type ClaimedJob = {
+    runId: string;
+    workItemId: string;
+    prompt: string;
+    repo: string | null;
+    branch: string | null;
+    externalId: string | null;
+    title: string | null;
+    type: string;
+    engine?: string | null;
+    model?: string | null;
+    effort?: string | null;
+    permissionMode?: string | null;
+    attachments?: {
+        filename?: string | null;
+        contentType?: string | null;
+        dataB64: string;
+    }[];
+};
+export type RunnerEvent = 'cloning' | 'fixing' | 'pushing' | 'pr_opened' | 'heartbeat' | 'log';
+export type ResultPayload = {
+    status: 'pr_opened';
+    pr: {
+        repo?: string;
+        number?: number;
+        url?: string;
+        branch?: string;
+        summary?: string;
+    };
+} | {
+    status: 'no_pr';
+    error?: string;
+} | {
+    status: 'failed';
+    error: string;
+};
+export declare class RunnerApi {
+    private readonly apiUrl;
+    private readonly token;
+    constructor(apiUrl: string, token: string);
+    private headers;
+    claim(meta: {
+        version: string;
+        hostname: string;
+        platform: string;
+        viewerPort?: number | null;
+        engines?: string[];
+        budget?: Array<{
+            engine: string;
+            planLabel?: string;
+            windows: Array<{
+                window: string;
+                pctUsed: number;
+                resetsAt: string | null;
+            }>;
+        }>;
+    }): Promise<ClaimedJob | null>;
+    repos(): Promise<string[]>;
+    config(): Promise<{
+        maxParallel: number;
+    } | null>;
+    event(runId: string, event: RunnerEvent, detail?: Record<string, unknown>): Promise<void>;
+    result(runId: string, payload: ResultPayload): Promise<void>;
+}

package/dist/api.js

@@ -0,0 +1,76 @@
+export class RunnerApi {
+    apiUrl;
+    token;
+    constructor(apiUrl, token) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        this.apiUrl = apiUrl.replace(/\/+$/, '');
+    }
+    headers() {
+        return { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' };
+    }
+    async claim(meta) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 35_000);
+        try {
+            const res = await fetch(`${this.apiUrl}/channel/claim`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify(meta),
+                signal: ctrl.signal,
+            });
+            if (res.status === 204)
+                return null;
+            if (res.status === 401)
+                throw new Error('runner token rejected (revoked or wrong API URL)');
+            if (!res.ok)
+                throw new Error(`claim failed: ${res.status}`);
+            const body = (await res.json());
+            return body.job ?? null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async repos() {
+        try {
+            const res = await fetch(`${this.apiUrl}/channel/repos`, { headers: this.headers() });
+            if (!res.ok)
+                return [];
+            const body = (await res.json());
+            return Array.isArray(body.repos) ? body.repos : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async config() {
+        try {
+            const res = await fetch(`${this.apiUrl}/channel/config`, { headers: this.headers() });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            return { maxParallel: typeof body.maxParallel === 'number' ? body.maxParallel : 1 };
+        }
+        catch {
+            return null;
+        }
+    }
+    async event(runId, event, detail) {
+        await fetch(`${this.apiUrl}/channel/runs/${runId}/events`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ event, detail }),
+        }).catch(() => { });
+    }
+    async result(runId, payload) {
+        const res = await fetch(`${this.apiUrl}/channel/runs/${runId}/result`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok)
+            throw new Error(`result report failed: ${res.status}`);
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/brief.d.ts

@@ -0,0 +1,2 @@
+import type { RunnerConfig } from './config.js';
+export declare function runBrief(repo: string, cfg: RunnerConfig): Promise<void>;

package/dist/brief.js

@@ -0,0 +1,138 @@
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { exec, execOut } from './exec.js';
+import { resolveRepoPath } from './job.js';
+function out(msg) {
+    process.stdout.write(`${msg}\n`);
+}
+const BRIEF_PROMPT = `You are bootstrapping a CLAUDE.md "runner briefing" for THIS repository.
+
+Context: a headless, unattended FireFunc runner will load this file on every automated fix — no human to guide it, no prior context, a cold boot each time. Claude Code auto-loads a repo-root CLAUDE.md as project instructions, so this file is the runner's complete, always-loaded operating manual.
+
+If a CLAUDE.md already exists at the repo root, only improve it where it is clearly incomplete; otherwise WRITE a new one at the repo root (path: CLAUDE.md). Include, concisely:
+- How to install dependencies and run the app locally (the exact commands).
+- The test / lint / build commands that gate CI — explicitly called out as the signal a fix must keep green, plus "add or adjust a test".
+- A short system map: the main components and the key end-to-end flows.
+- Code conventions a fix must respect (logging, error handling, naming).
+- Hard rules / "tread carefully — prefer human review" paths: auth, payments, DB migrations, CI config (.github/workflows), deploy/terraform, secrets.
+- A "how to make a good autonomous fix" checklist: localize to the smallest correct change, add a test, run the gate locally, keep the diff reviewable (it ships as a draft PR).
+
+CRITICAL: state only what you can VERIFY from the code — read package.json scripts, CI workflows, and the source before asserting a command or convention. Do not hallucinate. Do NOT modify any file other than CLAUDE.md.`;
+export async function runBrief(repo, cfg) {
+    const repoPath = resolveRepoPath(repo, cfg);
+    if (!repoPath) {
+        out(`No local checkout for ${repo}. Map it first: firefunc-runner repo ${repo} <path>`);
+        process.exitCode = 1;
+        return;
+    }
+    const claudeBin = cfg.claudeBin ?? 'claude';
+    const branch = 'claude/firefunc-claude-md';
+    let worktree = null;
+    try {
+        out(`Briefing ${repo} — checking out a throwaway worktree…`);
+        await exec('git', ['-C', repoPath, 'fetch', 'origin', '--quiet'], { timeoutMs: 120_000 });
+        let base = cfg.baseBranch ?? '';
+        if (!base) {
+            const head = await execOut('git', ['-C', repoPath, 'symbolic-ref', 'refs/remotes/origin/HEAD'], repoPath);
+            base = head ? head.replace('refs/remotes/origin/', '') : 'main';
+        }
+        worktree = mkdtempSync(join(tmpdir(), 'firefunc-brief-'));
+        const add = await exec('git', ['-C', repoPath, 'worktree', 'add', '--force', '-B', branch, worktree, `origin/${base}`], { timeoutMs: 120_000 });
+        if (add.code !== 0) {
+            out(`git worktree add failed: ${add.stderr.slice(0, 300)}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (existsSync(join(worktree, 'CLAUDE.md'))) {
+            out('This repo already has a CLAUDE.md — Claude will only fill gaps, if any.');
+        }
+        const runEnv = {
+            ...cfg.claudeEnv,
+            ...(cfg.claudeCodeOAuthToken ? { CLAUDE_CODE_OAUTH_TOKEN: cfg.claudeCodeOAuthToken } : {}),
+            ...(cfg.claudeUseApiKey ? {} : { ANTHROPIC_API_KEY: undefined }),
+        };
+        const model = cfg.model ?? 'opus';
+        const tools = cfg.allowedTools ?? 'Read Edit Write Bash Glob Grep WebFetch WebSearch Task TodoWrite';
+        const isWin = process.platform === 'win32';
+        const args = [
+            '-p',
+            ...(isWin ? [] : [BRIEF_PROMPT]),
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--permission-mode',
+            'bypassPermissions',
+            '--allowedTools',
+            tools,
+            '--model',
+            model,
+        ];
+        out('Running Claude Code to draft the briefing (this can take a few minutes)…');
+        const claude = await exec(claudeBin, args, {
+            cwd: worktree,
+            timeoutMs: (cfg.jobTimeoutMinutes ?? 20) * 60_000,
+            env: runEnv,
+            input: isWin ? BRIEF_PROMPT : undefined,
+            shell: isWin,
+        });
+        if (claude.code === 124) {
+            out('Claude timed out before finishing the briefing.');
+            process.exitCode = 1;
+            return;
+        }
+        await exec('git', ['-C', worktree, 'add', '-A']);
+        const diff = await exec('git', ['-C', worktree, 'diff', '--cached', '--quiet']);
+        if (diff.code === 0) {
+            out('No changes produced — the repo may already be fully briefed.');
+            return;
+        }
+        await exec('git', [
+            '-C',
+            worktree,
+            'commit',
+            '-m',
+            'docs: add CLAUDE.md runner briefing',
+            '--quiet',
+        ]);
+        const push = await exec('git', ['-C', worktree, 'push', '--force-with-lease', 'origin', `${branch}:${branch}`], { timeoutMs: 120_000 });
+        if (push.code !== 0) {
+            out(`git push failed: ${push.stderr.slice(0, 300)}`);
+            process.exitCode = 1;
+            return;
+        }
+        const body = 'Starter CLAUDE.md "runner briefing" drafted by FireFunc so the self-hosted ' +
+            'runner boots every fix with full project context + guardrails.\n\n' +
+            'Review and edit before merging — this file loads on every automated run.';
+        const create = await exec('gh', [
+            'pr',
+            'create',
+            '--draft',
+            '--head',
+            branch,
+            '--base',
+            base,
+            '--title',
+            'docs: add CLAUDE.md runner briefing',
+            '--body',
+            body,
+        ], { cwd: worktree, timeoutMs: 60_000 });
+        let url = create.stdout.trim().split('\n').pop() ?? '';
+        if (create.code !== 0 || !/^https?:\/\//.test(url)) {
+            url = await execOut('gh', ['pr', 'view', branch, '--json', 'url', '--jq', '.url'], worktree);
+        }
+        out(`\nDraft PR opened: ${url || '(open it from GitHub — branch ' + branch + ')'}`);
+        out('Review the CLAUDE.md, edit anything wrong, and merge it. The runner will load it on every fix.');
+    }
+    finally {
+        if (worktree) {
+            await exec('git', ['-C', repoPath, 'worktree', 'remove', '--force', worktree]).catch(() => { });
+            try {
+                rmSync(worktree, { recursive: true, force: true });
+            }
+            catch {
+            }
+        }
+    }
+}
+//# sourceMappingURL=brief.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import { loadConfig, saveConfig, configPath } from './config.js';
+import { startDaemon } from './daemon.js';
+import { runBrief } from './brief.js';
+const HELP = `firefunc-runner — run YOUR local Claude Code on bugs FireFunc routes to you.
+
+Usage:
+  firefunc-runner connect <token> [options]   Save your runner token + settings
+  firefunc-runner repo <owner/repo> <path>    Point a repo at its local checkout
+  firefunc-runner brief <owner/repo>          Draft a CLAUDE.md runner briefing as a draft PR
+  firefunc-runner start                       Start the always-on daemon
+  firefunc-runner status                      Show the saved config
+  firefunc-runner --help
+
+connect options:
+  --api <url>        FireFunc API URL — REQUIRED. Copy the whole connect
+                     command from the Engines screen; it fills this in.
+  --name <name>      Friendly runner name (default: this hostname)
+  --repos-dir <dir>  Base directory where your checkouts live (matched by repo name)
+  --repo <owner/repo=/path>   Map one repo to an exact local checkout (repeatable)
+  --claude-bin <bin> Claude Code binary (default: claude)
+  --claude-oauth-token <tok>  Subscription token from "claude setup-token". Usually NOT
+                     needed — the runner already uses your machine's "claude" login.
+                     Set only if this machine has no interactive Claude login.
+  --use-api-key      Bill pay-as-you-go API credits via ANTHROPIC_API_KEY instead of
+                     your subscription. OFF by default — the runner hides any
+                     ANTHROPIC_API_KEY from claude so it can't silently charge the API.
+
+engine (the runner drives whatever agent CLI each job asks for — Claude Code by
+default; the per-project Engine setting in FireFunc picks one, or set a local
+fallback + each engine's auth here):
+  --engine <id>      Default engine when a job doesn't pin one:
+                     claude_code | codex_cli | gemini_cli | cursor_cli (default claude_code)
+  --codex-bin <bin>  OpenAI Codex binary (default: codex). Uses your "codex login"
+                     (ChatGPT plan); API keys are hidden unless --codex-use-api-key.
+  --codex-use-api-key   Bill OpenAI API credits via OPENAI_API_KEY instead of the ChatGPT plan.
+  --gemini-bin <bin> Gemini CLI binary (default: gemini).
+  --gemini-api-key <key>  Gemini API key (Google AI Studio; free tier ~250/day).
+                     Consumer "Login with Google" was retired for Gemini CLI in June 2026.
+  --cursor-bin <bin> Cursor CLI binary (default: cursor-agent).
+  --cursor-api-key <key>  Cursor User API key (from the Cursor dashboard; bills your Cursor plan).
+  --quiet            Hide the live Claude session feed in this terminal (default: show
+                     it). The feed is local-only and never sent to FireFunc either way.
+  --viewer-port <n>  Port for the local live-session web terminal (default 8787). Open
+                     http://127.0.0.1:<n> to watch Claude work; FireFunc's "Watch live"
+                     button opens it too. Bound to localhost only — never sent to FireFunc.
+  --no-viewer        Don't serve the local live-session web terminal.
+  --max-parallel <n> Run up to N Claude Code sessions AT ONCE (default 1 = serial).
+                     Each runs in its own git worktree + dev-server port. Higher N
+                     = faster throughput, more CPU/RAM, and may hit Claude-Max rate
+                     limits. It's your machine + subscription — set what you like.
+  --dev-server-base-port <n>  Base port for parallel sessions' dev servers (default 3100).
+
+dev-environment (so Claude can REPRODUCE bugs live, not just read code):
+  --env KEY=VALUE    Env var for the fix run, e.g. AWS_PROFILE=app-ro (repeatable)
+  --setup "<cmd>"    Command run in the worktree before Claude, e.g. "npm ci" (repeatable)
+  --bg "<cmd>"       Long-lived command (a dev server) Claude can hit, e.g. "npm run dev" (repeatable)
+  --env-file <path>  A .env copied into the worktree before setup
+  --setup-timeout <min>   Timeout for all setup commands (default: job timeout)
+  --no-auto-install  Skip auto npm/pnpm/yarn install (default: auto-install deps when no --setup given)
+
+Examples:
+  firefunc-runner connect ffr_xxx --repos-dir ~/code
+  firefunc-runner connect ffr_xxx --repo acme/api=/Users/me/code/api
+  firefunc-runner connect ffr_xxx --env AWS_PROFILE=app-ro --setup "npm ci" --bg "npm run dev"
+  firefunc-runner start
+`;
+function parseFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a?.startsWith('--')) {
+            const key = a.slice(2);
+            const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : 'true';
+            (out[key] ??= []).push(val);
+        }
+    }
+    return out;
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (cmd === 'connect') {
+        const token = rest.find((a) => !a.startsWith('--'));
+        if (!token || !token.startsWith('ffr_')) {
+            process.stderr.write('Pass your runner token: firefunc-runner connect ffr_…\n');
+            process.exitCode = 1;
+            return;
+        }
+        const f = parseFlags(rest);
+        const apiUrl = f.api?.[0]?.trim();
+        if (!apiUrl || !/^https?:\/\//.test(apiUrl)) {
+            process.stderr.write('Missing --api.\n' +
+                '  firefunc-runner connect <token> --api https://your-firefunc-host\n\n' +
+                'Copy the whole command from the Engines screen in FireFunc — it fills\n' +
+                'in both the token and the URL for your workspace.\n');
+            process.exitCode = 1;
+            return;
+        }
+        const repos = {};
+        for (const r of f.repo ?? []) {
+            const [k, v] = r.split('=');
+            if (k && v)
+                repos[k] = v;
+        }
+        const claudeEnv = {};
+        for (const e of f.env ?? []) {
+            const i = e.indexOf('=');
+            if (i > 0)
+                claudeEnv[e.slice(0, i)] = e.slice(i + 1);
+        }
+        const cfg = {
+            apiUrl,
+            token,
+            name: f.name?.[0],
+            reposDir: f['repos-dir']?.[0],
+            repos: Object.keys(repos).length ? repos : undefined,
+            claudeBin: f['claude-bin']?.[0],
+            quiet: f.quiet ? true : undefined,
+            viewerPort: f['viewer-port']?.[0] ? Number(f['viewer-port'][0]) : undefined,
+            viewerEnabled: f['no-viewer'] ? false : undefined,
+            maxParallel: f['max-parallel']?.[0] ? Number(f['max-parallel'][0]) : undefined,
+            devServerBasePort: f['dev-server-base-port']?.[0]
+                ? Number(f['dev-server-base-port'][0])
+                : undefined,
+            claudeCodeOAuthToken: f['claude-oauth-token']?.[0],
+            claudeUseApiKey: f['use-api-key'] ? true : undefined,
+            engine: f.engine?.[0],
+            codexBin: f['codex-bin']?.[0],
+            codexUseApiKey: f['codex-use-api-key'] ? true : undefined,
+            geminiBin: f['gemini-bin']?.[0],
+            geminiApiKey: f['gemini-api-key']?.[0],
+            cursorAgentBin: f['cursor-bin']?.[0],
+            cursorApiKey: f['cursor-api-key']?.[0],
+            claudeEnv: Object.keys(claudeEnv).length ? claudeEnv : undefined,
+            setupCommands: f.setup,
+            autoInstall: f['no-auto-install'] ? false : undefined,
+            setupTimeoutMinutes: f['setup-timeout']?.[0] ? Number(f['setup-timeout'][0]) : undefined,
+            envFile: f['env-file']?.[0],
+            backgroundCommands: f.bg,
+        };
+        saveConfig(cfg);
+        process.stdout.write(`Saved to ${configPath()}.\nRun "firefunc-runner start" to go online.\n`);
+        return;
+    }
+    if (cmd === 'repo') {
+        const cfg = loadConfig();
+        if (!cfg) {
+            process.stderr.write('Not connected. Run "firefunc-runner connect <token>" first.\n');
+            process.exitCode = 1;
+            return;
+        }
+        const positional = rest.filter((a) => !a.startsWith('--'));
+        const name = positional[0];
+        const localPath = positional.slice(1).join(' ').trim();
+        if (!name || !name.includes('/') || !localPath) {
+            process.stderr.write('Usage: firefunc-runner repo <owner/repo> <local-path>\n' +
+                'Example: firefunc-runner repo acme/checkout-api "C:\\Users\\me\\checkout-api"\n');
+            process.exitCode = 1;
+            return;
+        }
+        cfg.repos = { ...(cfg.repos ?? {}), [name]: localPath };
+        saveConfig(cfg);
+        process.stdout.write(`Mapped ${name} → ${localPath}\nRestart the runner to apply: firefunc-runner start\n`);
+        return;
+    }
+    if (cmd === 'brief') {
+        const cfg = loadConfig();
+        if (!cfg) {
+            process.stderr.write('Not connected. Run "firefunc-runner connect <token>" first.\n');
+            process.exitCode = 1;
+            return;
+        }
+        const repo = rest.find((a) => !a.startsWith('--'));
+        if (!repo || !repo.includes('/')) {
+            process.stderr.write('Usage: firefunc-runner brief <owner/repo>\n' +
+                'Example: firefunc-runner brief acme/checkout-api\n');
+            process.exitCode = 1;
+            return;
+        }
+        await runBrief(repo, cfg);
+        return;
+    }
+    if (cmd === 'status') {
+        const cfg = loadConfig();
+        if (!cfg) {
+            process.stdout.write('Not connected. Run "firefunc-runner connect <token>".\n');
+            return;
+        }
+        process.stdout.write(`Connected to ${cfg.apiUrl}\n` +
+            `  name:      ${cfg.name ?? '(hostname)'}\n` +
+            `  reposDir:  ${cfg.reposDir ?? '(none)'}\n` +
+            `  repos:     ${cfg.repos ? Object.keys(cfg.repos).join(', ') : '(auto by name)'}\n` +
+            `  engine:    ${cfg.engine ?? 'claude_code'} (default; per-project setting wins)\n` +
+            `  claudeBin: ${cfg.claudeBin ?? 'claude'}\n` +
+            `  codex:     ${cfg.codexBin ?? 'codex'}${cfg.codexUseApiKey ? ' (API billing)' : ' (ChatGPT-plan login)'}\n` +
+            `  gemini:    ${cfg.geminiBin ?? 'gemini'}${cfg.geminiApiKey ? ' (API key set)' : ' (env auth)'}\n` +
+            `  cursor:    ${cfg.cursorAgentBin ?? 'cursor-agent'}${cfg.cursorApiKey ? ' (API key set)' : ' (no key — set --cursor-api-key)'}\n` +
+            `  liveViewer:${cfg.viewerEnabled === false ? ' off' : ` http://127.0.0.1:${cfg.viewerPort ?? 8787} (local only)`}\n` +
+            `  maxParallel:${cfg.maxParallel && cfg.maxParallel > 1 ? ` ${cfg.maxParallel} sessions at once` : ' 1 (serial)'}\n` +
+            `  claudeAuth:${cfg.claudeUseApiKey
+                ? ' ANTHROPIC_API_KEY (API billing — opted in)'
+                : cfg.claudeCodeOAuthToken
+                    ? ' subscription token'
+                    : ' your machine Claude login (subscription; API key hidden)'}\n` +
+            `  env:       ${cfg.claudeEnv ? Object.keys(cfg.claudeEnv).join(', ') : '(none)'}\n` +
+            `  setup:     ${cfg.setupCommands?.length ? cfg.setupCommands.join(' ; ') : '(none)'}\n` +
+            `  autoInstall:${cfg.autoInstall === false ? ' off' : ' on (when no setup)'}\n` +
+            `  background:${cfg.backgroundCommands?.length ? ' ' + cfg.backgroundCommands.join(' ; ') : ' (none)'}\n` +
+            `  envFile:   ${cfg.envFile ?? '(none)'}\n`);
+        return;
+    }
+    if (cmd === 'start') {
+        const cfg = loadConfig();
+        if (!cfg) {
+            process.stderr.write('Not connected. Run "firefunc-runner connect <token>" first.\n');
+            process.exitCode = 1;
+            return;
+        }
+        await startDaemon(cfg);
+        return;
+    }
+    process.stderr.write(`Unknown command "${cmd}".\n\n${HELP}`);
+    process.exitCode = 1;
+}
+void main();
+//# sourceMappingURL=cli.js.map