@testchimp/cli 0.1.44 → 0.1.46

package/dist/chimphands/run.d.ts

@@ -13,6 +13,14 @@ export declare function reportWorkingBranch(opts: ReportWorkingBranchOptions): P
 type RunOptions = {
     sessionId: string;
     prompt?: string;
+    /** When set, `opencode run --attach` to a local OpenCode server. */
+    attachUrl?: string;
+    /** Registered runtime id (from register_runtime); enables heartbeat + tunnel + complete_runtime. */
+    runtimeId?: string;
 };
 export declare function runChimphands(opts: RunOptions): Promise<void>;
+/** Runtime-aware entry: register + attach to local OpenCode server (Phase 1+). */
+export declare function serveChimphands(opts: RunOptions & {
+    attachUrl: string;
+}): Promise<void>;
 export {};

package/dist/chimphands/run.js

@@ -33,6 +33,7 @@ const CHIMPHANDS_AGENT_PROMPT = `You are ChimpHands, TestChimp's coding agent. Y
 - This conversation uses ONE working branch and ONE pull request. Reuse them for all follow-up work in this chat.
 - If bootstrap lists a working branch, checkout that branch and push additional commits there — update the same PR.
 - Only create a NEW branch/PR when (a) no working branch exists yet for this conversation, or (b) the prior PR was merged/closed (verify with \`gh pr view\`).
+- Commit and push on the session working branch after meaningful edit batches. The host also commits any dirty worktree before idle teardown — keep the branch pushed so the UI can show diffs from GitHub.
 - Branch names MUST start with \`testchimp-\` or \`chimphands-\`.
 - When creating a NEW working branch: create it, then IMMEDIATELY publish it with
   \`git push -u origin <branch>\` BEFORE calling report-branch. Users open the branch URL in the UI —
@@ -370,16 +371,19 @@ function writeOpencodeConfig(backend, apiKey, boot) {
     }, null, 2));
     return model;
 }
-function buildOpencodeArgs(prompt, model, opencodeSessionId) {
+function buildOpencodeArgs(prompt, model, opencodeSessionId, attachUrl) {
     const args = ["run", prompt, "--model", model, "--format", "json", "--agent", OPENCODE_AGENT_ID];
     if (opencodeSessionId?.trim()) {
         args.push("--session", opencodeSessionId.trim());
     }
+    if (attachUrl?.trim()) {
+        args.push("--attach", attachUrl.trim());
+    }
     return args;
 }
-function runOpencode(prompt, model, childEnv, opencodeSessionId, callbacks) {
+function runOpencode(prompt, model, childEnv, opencodeSessionId, callbacks, attachUrl) {
     let activeSessionId = opencodeSessionId?.trim() || undefined;
-    const baseArgs = buildOpencodeArgs(prompt, model, activeSessionId);
+    const baseArgs = buildOpencodeArgs(prompt, model, activeSessionId, attachUrl);
     const child = spawn("opencode", baseArgs, {
         stdio: ["ignore", "pipe", "pipe"],
         env: childEnv,
@@ -596,6 +600,8 @@ export async function runChimphands(opts) {
         throw new Error("session_id is required (pass --session-id or SESSION_ID)");
     }
     const promptInput = (opts.prompt ?? process.env.PROMPT ?? "").trim();
+    const attachUrl = (opts.attachUrl || process.env.OPENCODE_ATTACH_URL || "").trim() || undefined;
+    let runtimeId = (opts.runtimeId || process.env.CHIMPHANDS_RUNTIME_ID || "").trim() || undefined;
     const bootText = await postJson(backend, apiKey, "/api/chimphands/bootstrap", {
         sessionId,
     });
@@ -610,6 +616,30 @@ export async function runChimphands(opts) {
             console.error(`ChimpHands link run failed: ${err instanceof Error ? err.message : String(err)}`);
         });
     }
+    if (!runtimeId && attachUrl) {
+        try {
+            const regText = await postJson(backend, apiKey, "/api/chimphands/register_runtime", {
+                sessionId,
+                location: "CHIMPHANDS_RUNTIME_LOCATION_GITHUB_CI",
+                githubRunId: githubRunId || undefined,
+            });
+            const reg = JSON.parse(regText);
+            runtimeId = reg.runtime?.id || reg.runtimeId || undefined;
+            if (runtimeId) {
+                console.error(`ChimpHands runtime registered: ${runtimeId}`);
+                process.env.CHIMPHANDS_RUNTIME_ID = runtimeId;
+            }
+        }
+        catch (err) {
+            console.error(`ChimpHands register_runtime failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const stopHeartbeat = runtimeId
+        ? startRuntimeHeartbeat(backend, apiKey, runtimeId)
+        : () => { };
+    const stopTunnel = runtimeId && attachUrl
+        ? startTunnelWorker(backend, apiKey, runtimeId, attachUrl)
+        : () => { };
     const userId = bootStr(boot, "chimphands_service_account_user_id", "chimphandsServiceAccountUserId");
     if (userId) {
         process.env.TESTCHIMP_USER_ID = userId;
@@ -617,10 +647,37 @@ export async function runChimphands(opts) {
     mkdirSync(".opencode", { recursive: true });
     const opencodeModel = writeOpencodeConfig(backend, apiKey, boot);
     console.error(`ChimpHands OpenCode model: ${opencodeModel}`);
+    if (attachUrl) {
+        console.error(`ChimpHands OpenCode attach: ${attachUrl}`);
+    }
     let opencodeSessionId = bootStr(boot, "opencode_session_id", "opencodeSessionId") || undefined;
     const conversationSummary = bootStr(boot, "conversation_summary", "conversationSummary");
     let workingBranch = bootStr(boot, "working_branch", "workingBranch") || undefined;
     let pullRequestUrl = bootStr(boot, "pull_request_url", "pullRequestUrl") || undefined;
+    const exportSignedUrl = bootStr(boot, "opencode_export_signed_url", "opencodeExportSignedUrl");
+    if (exportSignedUrl && attachUrl) {
+        try {
+            const importedId = await importOpencodeExportFromUrl(exportSignedUrl);
+            if (importedId) {
+                opencodeSessionId = importedId;
+                console.error(`ChimpHands rehydrated OpenCode session from export: ${importedId}`);
+            }
+        }
+        catch (err) {
+            console.error(`ChimpHands export import failed (continuing): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const snapshotExport = async () => {
+        const sid = opencodeSessionId?.trim();
+        if (!sid)
+            return;
+        try {
+            await putOpencodeExport(backend, apiKey, sessionId, sid);
+        }
+        catch (err) {
+            console.error(`ChimpHands export snapshot failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
     const noteWorkingBranch = (branch, prUrl) => {
         const normalizedBranch = branch.trim();
         if (!normalizedBranch)
@@ -643,6 +700,7 @@ export async function runChimphands(opts) {
     let idle = false;
     let sessionActive = true;
     let lastUserActivity = Date.now();
+    let exitCode;
     const enqueueUserMessage = (msg) => {
         const id = msg.id?.trim();
         if (id) {
@@ -706,67 +764,65 @@ export async function runChimphands(opts) {
         },
         shouldRun: () => sessionActive,
     });
-    poster.fireAndForget(ROLE_STATUS, "Agent ready", { status: STATUS_RUNNING });
-    let prompt = normalizeUserMessage(promptInput || bootStr(boot, "initial_prompt", "initialPrompt"));
-    const pending = boot.pending_user_messages || boot.pendingUserMessages || [];
-    for (const m of pending) {
-        if (m?.content)
-            enqueueUserMessage({ content: m.content });
-    }
-    const waitForNextPrompt = () => new Promise((resolve) => {
-        let lastPollAt = 0;
-        const tick = () => {
-            if (queue.length) {
-                resolve(normalizeUserMessage(queue.shift()));
-                return;
-            }
-            const now = Date.now();
-            if (now - lastPollAt >= 1500) {
-                lastPollAt = now;
-                void pollPendingUserMessages().then(() => {
-                    if (queue.length) {
-                        resolve(normalizeUserMessage(queue.shift()));
-                        return;
-                    }
-                    if (idle || now - lastUserActivity >= idleMs) {
-                        resolve(null);
-                        return;
-                    }
-                    setTimeout(tick, 500);
-                });
-                return;
-            }
-            if (idle || now - lastUserActivity >= idleMs) {
-                resolve(null);
-                return;
-            }
-            setTimeout(tick, 500);
-        };
-        tick();
-    });
-    while (prompt) {
-        let useOpencodeSessionId = opencodeSessionId;
-        let isNewOpencodeSession = !useOpencodeSessionId;
-        let effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, isNewOpencodeSession, workingBranch, pullRequestUrl);
-        let result = await runOpencode(effectivePrompt, opencodeModel, childEnv, useOpencodeSessionId, {
-            onSessionId: (id) => {
-                opencodeSessionId = id;
-                void postJson(backend, apiKey, "/api/chimphands/post_agent_event", {
-                    sessionId,
-                    opencodeSessionId: id,
-                }).catch(() => { });
-            },
-            onWorkingBranch: noteWorkingBranch,
-            postEvent,
+    const shutdownRuntime = async () => {
+        sessionActive = false;
+        stopInbound();
+        stopTunnel();
+        stopHeartbeat();
+        await commitAndPushDirtyWorktree("chimphands: commit before session idle/shutdown");
+        await poster.flush();
+        await snapshotExport();
+        if (runtimeId) {
+            await postJson(backend, apiKey, "/api/chimphands/complete_runtime", {
+                runtimeId,
+                status: "CHIMPHANDS_RUNTIME_STATUS_TERMINATED",
+            }).catch(() => { });
+        }
+    };
+    try {
+        poster.fireAndForget(ROLE_STATUS, "Agent ready", { status: STATUS_RUNNING });
+        let prompt = normalizeUserMessage(promptInput || bootStr(boot, "initial_prompt", "initialPrompt"));
+        const pending = boot.pending_user_messages || boot.pendingUserMessages || [];
+        for (const m of pending) {
+            if (m?.content)
+                enqueueUserMessage({ content: m.content });
+        }
+        const waitForNextPrompt = () => new Promise((resolve) => {
+            let lastPollAt = 0;
+            const tick = () => {
+                if (queue.length) {
+                    resolve(normalizeUserMessage(queue.shift()));
+                    return;
+                }
+                const now = Date.now();
+                if (now - lastPollAt >= 1500) {
+                    lastPollAt = now;
+                    void pollPendingUserMessages().then(() => {
+                        if (queue.length) {
+                            resolve(normalizeUserMessage(queue.shift()));
+                            return;
+                        }
+                        if (idle || now - lastUserActivity >= idleMs) {
+                            resolve(null);
+                            return;
+                        }
+                        setTimeout(tick, 500);
+                    });
+                    return;
+                }
+                if (idle || now - lastUserActivity >= idleMs) {
+                    resolve(null);
+                    return;
+                }
+                setTimeout(tick, 500);
+            };
+            tick();
         });
-        if (result.code !== 0 &&
-            useOpencodeSessionId &&
-            isMissingOpencodeSessionError(result.err || "")) {
-            console.error(`ChimpHands OpenCode session ${useOpencodeSessionId} missing on runner; starting fresh thread.`);
-            opencodeSessionId = undefined;
-            isNewOpencodeSession = true;
-            effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, true, workingBranch, pullRequestUrl);
-            result = await runOpencode(effectivePrompt, opencodeModel, childEnv, undefined, {
+        while (prompt) {
+            let useOpencodeSessionId = opencodeSessionId;
+            let isNewOpencodeSession = !useOpencodeSessionId;
+            let effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, isNewOpencodeSession, workingBranch, pullRequestUrl);
+            let result = await runOpencode(effectivePrompt, opencodeModel, childEnv, useOpencodeSessionId, {
                 onSessionId: (id) => {
                     opencodeSessionId = id;
                     void postJson(backend, apiKey, "/api/chimphands/post_agent_event", {
@@ -776,43 +832,399 @@ export async function runChimphands(opts) {
                 },
                 onWorkingBranch: noteWorkingBranch,
                 postEvent,
+            }, attachUrl);
+            if (result.code !== 0 &&
+                useOpencodeSessionId &&
+                isMissingOpencodeSessionError(result.err || "")) {
+                console.error(`ChimpHands OpenCode session ${useOpencodeSessionId} missing on runner; starting fresh thread.`);
+                opencodeSessionId = undefined;
+                isNewOpencodeSession = true;
+                effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, true, workingBranch, pullRequestUrl);
+                result = await runOpencode(effectivePrompt, opencodeModel, childEnv, undefined, {
+                    onSessionId: (id) => {
+                        opencodeSessionId = id;
+                        void postJson(backend, apiKey, "/api/chimphands/post_agent_event", {
+                            sessionId,
+                            opencodeSessionId: id,
+                        }).catch(() => { });
+                    },
+                    onWorkingBranch: noteWorkingBranch,
+                    postEvent,
+                }, attachUrl);
+            }
+            await poster.flush();
+            if (result.opencodeSessionId) {
+                opencodeSessionId = result.opencodeSessionId;
+            }
+            if (result.code !== 0) {
+                const errMsg = (result.err || "opencode failed").trim() || "opencode failed";
+                console.error(`ChimpHands OpenCode failed: ${errMsg}`);
+                try {
+                    await poster.enqueue(ROLE_STATUS, errMsg, {
+                        status: STATUS_FAILED,
+                        opencodeSessionId,
+                    });
+                    await postJson(backend, apiKey, "/api/chimphands/complete_session", {
+                        sessionId,
+                        status: STATUS_FAILED,
+                        errorMessage: errMsg,
+                        githubRunId: githubRunId || undefined,
+                    });
+                }
+                catch (reportErr) {
+                    const detail = reportErr instanceof Error ? reportErr.message : String(reportErr);
+                    console.error(`ChimpHands failed to report OpenCode error to backend: ${detail}`);
+                    postEvent(ROLE_STATUS, errMsg, { status: STATUS_FAILED });
+                    complete(STATUS_FAILED, errMsg);
+                }
+                exitCode = result.code || 1;
+                break;
+            }
+            postEvent(ROLE_STATUS, "Waiting for user input", { status: STATUS_WAITING_USER });
+            await snapshotExport();
+            lastUserActivity = Date.now();
+            idle = false;
+            prompt = (await waitForNextPrompt()) || "";
+        }
+        if (exitCode == null) {
+            console.error("ChimpHands session idle — no user input before timeout; completing.");
+            complete(STATUS_IDLE);
+        }
+    }
+    finally {
+        await shutdownRuntime();
+    }
+    if (exitCode != null) {
+        process.exit(exitCode);
+    }
+}
+function startRuntimeHeartbeat(backend, apiKey, runtimeId) {
+    let stopped = false;
+    const tick = async () => {
+        if (stopped)
+            return;
+        try {
+            // Do not claim tunnel_connected here — only the tunnel poll loop should.
+            await postJson(backend, apiKey, "/api/chimphands/runtime_heartbeat", {
+                runtimeId,
             });
         }
-        await poster.flush();
-        if (result.opencodeSessionId) {
-            opencodeSessionId = result.opencodeSessionId;
+        catch (err) {
+            console.error(`ChimpHands runtime_heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        if (result.code !== 0) {
-            const errMsg = (result.err || "opencode failed").trim() || "opencode failed";
-            console.error(`ChimpHands OpenCode failed: ${errMsg}`);
-            try {
-                await poster.enqueue(ROLE_STATUS, errMsg, {
-                    status: STATUS_FAILED,
-                    opencodeSessionId,
-                });
-                await postJson(backend, apiKey, "/api/chimphands/complete_session", {
-                    sessionId,
-                    status: STATUS_FAILED,
-                    errorMessage: errMsg,
-                    githubRunId: githubRunId || undefined,
+        if (!stopped)
+            setTimeout(tick, 15_000);
+    };
+    void tick();
+    return () => {
+        stopped = true;
+    };
+}
+/** Commit+push dirty worktree on the session branch before idle/teardown (no default-branch writes). */
+async function commitAndPushDirtyWorktree(message) {
+    const run = (args, env) => new Promise((resolve) => {
+        const child = spawn("git", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: env ? { ...process.env, ...env } : process.env,
+        });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => {
+            out += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            err += d.toString();
+        });
+        child.on("close", (code) => resolve({ code: code ?? 1, out, err }));
+    });
+    try {
+        const branch = await run(["rev-parse", "--abbrev-ref", "HEAD"]);
+        if (branch.code !== 0) {
+            console.error(`ChimpHands git rev-parse failed: ${branch.err || branch.out}`);
+            return;
+        }
+        const current = branch.out.trim();
+        if (!current || current === "HEAD" || /^(main|master)$/i.test(current)) {
+            console.error(`ChimpHands skip commit-before-idle: refusing branch "${current || "(unknown)"}"`);
+            return;
+        }
+        const status = await run(["status", "--porcelain"]);
+        if (status.code !== 0) {
+            console.error(`ChimpHands git status failed: ${status.err || status.out}`);
+            return;
+        }
+        if (!status.out.trim()) {
+            return;
+        }
+        const add = await run(["add", "-A"]);
+        if (add.code !== 0) {
+            console.error(`ChimpHands git add failed: ${add.err || add.out}`);
+            return;
+        }
+        const commitEnv = {
+            GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME || "ChimpHands",
+            GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL || "chimphands@testchimp.io",
+            GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME || "ChimpHands",
+            GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL || "chimphands@testchimp.io",
+        };
+        const commit = await run(["-c", "user.name=ChimpHands", "-c", "user.email=chimphands@testchimp.io", "commit", "-m", message], commitEnv);
+        if (commit.code !== 0) {
+            console.error(`ChimpHands git commit: ${commit.err || commit.out}`);
+            return;
+        }
+        const push = await run(["push", "-u", "origin", "HEAD"]);
+        if (push.code !== 0) {
+            console.error(`ChimpHands git push failed: ${push.err || push.out}`);
+            return;
+        }
+        console.error(`ChimpHands committed and pushed dirty worktree on ${current} before shutdown`);
+    }
+    catch (err) {
+        console.error(`ChimpHands commit-before-idle failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function putOpencodeExport(backend, apiKey, sessionId, opencodeSessionId) {
+    const exported = await new Promise((resolve, reject) => {
+        const child = spawn("opencode", ["export", opencodeSessionId, "--sanitize"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => {
+            out += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            err += d.toString();
+        });
+        child.on("close", (code) => {
+            if (code === 0 && out.trim())
+                resolve(out);
+            else
+                reject(new Error(err.trim() || `opencode export exited ${code}`));
+        });
+    });
+    const exportBase64 = Buffer.from(exported, "utf8").toString("base64");
+    await postJson(backend, apiKey, "/api/chimphands/put_opencode_export", {
+        sessionId,
+        exportBase64,
+    });
+}
+async function importOpencodeExportFromUrl(signedUrl) {
+    const res = await fetch(signedUrl);
+    if (!res.ok) {
+        throw new Error(`download export failed: ${res.status}`);
+    }
+    const text = await res.text();
+    writeFileSync("/tmp/chimphands-opencode-export.json", text, "utf8");
+    return await new Promise((resolve, reject) => {
+        const child = spawn("opencode", ["import", "/tmp/chimphands-opencode-export.json"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => {
+            out += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            err += d.toString();
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(err.trim() || `opencode import exited ${code}`));
+                return;
+            }
+            const match = (out + "\n" + err).match(/ses_[A-Za-z0-9]+/);
+            resolve(match?.[0]);
+        });
+    });
+}
+function startTunnelWorker(backend, apiKey, runtimeId, attachUrl) {
+    let stopped = false;
+    const base = attachUrl.replace(/\/$/, "");
+    let ws = null;
+    let reconnectTimer = null;
+    let backoffMs = 1000;
+    const wsBase = backend.replace(/^http/i, (m) => (m.toLowerCase() === "https" ? "wss" : "ws"));
+    const tunnelUrl = `${wsBase.replace(/\/$/, "")}/api/chimphands/runtimes/${encodeURIComponent(runtimeId)}/tunnel`;
+    const clearReconnect = () => {
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+    };
+    const handleHttpRequest = async (socket, req) => {
+        if (!req.requestId || socket.readyState !== 1)
+            return;
+        const requestId = req.requestId;
+        const target = base + (req.path || "/") + (req.query ? `?${req.query}` : "");
+        const headers = { ...(req.headers || {}) };
+        const init = { method: req.method || "GET", headers };
+        if (req.bodyBase64) {
+            init.body = Buffer.from(req.bodyBase64, "base64");
+        }
+        // Long-running SSE / chat streams — no hard abort under ~5 minutes.
+        const ac = new AbortController();
+        const upstreamTimer = setTimeout(() => ac.abort(), 290_000);
+        init.signal = ac.signal;
+        const send = (obj) => {
+            if (socket.readyState !== 1)
+                return;
+            socket.send(JSON.stringify(obj));
+        };
+        /** Keep each WS text frame small — Tomcat default max is 8KiB; GCLB is happier with modest frames. */
+        const sendBodyChunk = (bytes) => {
+            const MAX = 24 * 1024;
+            for (let offset = 0; offset < bytes.length; offset += MAX) {
+                const slice = bytes.subarray(offset, Math.min(offset + MAX, bytes.length));
+                send({
+                    type: "http_response_chunk",
+                    requestId,
+                    bodyBase64: Buffer.from(slice).toString("base64"),
                 });
             }
-            catch (reportErr) {
-                const detail = reportErr instanceof Error ? reportErr.message : String(reportErr);
-                console.error(`ChimpHands failed to report OpenCode error to backend: ${detail}`);
-                postEvent(ROLE_STATUS, errMsg, { status: STATUS_FAILED });
-                complete(STATUS_FAILED, errMsg);
+        };
+        try {
+            const upstream = await fetch(target, init);
+            const respHeaders = {};
+            upstream.headers.forEach((v, k) => {
+                respHeaders[k] = v;
+            });
+            send({
+                type: "http_response_start",
+                requestId,
+                status: upstream.status,
+                headers: respHeaders,
+            });
+            const body = upstream.body;
+            if (body) {
+                const reader = body.getReader();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value && value.length) {
+                        sendBodyChunk(Buffer.from(value));
+                    }
+                }
+            }
+            else {
+                const buf = Buffer.from(await upstream.arrayBuffer());
+                if (buf.length) {
+                    sendBodyChunk(buf);
+                }
             }
-            process.exit(result.code || 1);
+            send({ type: "http_response_end", requestId });
         }
-        postEvent(ROLE_STATUS, "Waiting for user input", { status: STATUS_WAITING_USER });
-        lastUserActivity = Date.now();
-        idle = false;
-        prompt = (await waitForNextPrompt()) || "";
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            send({
+                type: "http_response",
+                requestId,
+                status: 502,
+                headers: { "Content-Type": "text/plain; charset=utf-8" },
+                bodyBase64: Buffer.from(msg, "utf8").toString("base64"),
+            });
+        }
+        finally {
+            clearTimeout(upstreamTimer);
+        }
+    };
+    const connect = async () => {
+        if (stopped)
+            return;
+        clearReconnect();
+        const { default: WebSocket } = await import("ws");
+        const socket = new WebSocket(tunnelUrl, {
+            headers: { "TestChimp-Api-Key": apiKey },
+            handshakeTimeout: 30_000,
+        });
+        ws = socket;
+        socket.on("open", () => {
+            backoffMs = 1000;
+            console.error(`ChimpHands agent tunnel WS connected: ${tunnelUrl}`);
+            // Application ping keeps LBs from idling out the tunnel (and proves liveness).
+            const ping = () => {
+                if (stopped || socket.readyState !== 1)
+                    return;
+                try {
+                    socket.send(JSON.stringify({ type: "ping" }));
+                }
+                catch {
+                    /* ignore */
+                }
+            };
+            ping();
+            const pingTimer = setInterval(ping, 20_000);
+            socket.once("close", () => clearInterval(pingTimer));
+        });
+        socket.on("message", (data) => {
+            if (stopped)
+                return;
+            try {
+                const text = typeof data === "string" ? data : data.toString("utf8");
+                const frame = JSON.parse(text);
+                if (frame.type === "pong")
+                    return;
+                if (frame.type === "ping") {
+                    socket.send(JSON.stringify({ type: "pong" }));
+                    return;
+                }
+                if (frame.type === "http_request" || frame.requestId) {
+                    void handleHttpRequest(socket, frame);
+                }
+            }
+            catch (err) {
+                console.error(`ChimpHands tunnel frame error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+        socket.on("close", (code, reason) => {
+            ws = null;
+            if (stopped)
+                return;
+            const why = reason?.toString?.() || "";
+            console.error(`ChimpHands agent tunnel WS closed; code=${code} reason=${why || "(none)"} reconnecting in ${backoffMs}ms`);
+            reconnectTimer = setTimeout(() => {
+                void connect();
+            }, backoffMs);
+            backoffMs = Math.min(backoffMs * 2, 30_000);
+        });
+        socket.on("error", (err) => {
+            console.error(`ChimpHands agent tunnel WS error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    void connect();
+    return () => {
+        stopped = true;
+        clearReconnect();
+        if (ws) {
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            ws = null;
+        }
+    };
+}
+/** Runtime-aware entry: register + attach to local OpenCode server (Phase 1+). */
+export async function serveChimphands(opts) {
+    const attachUrl = opts.attachUrl.trim();
+    if (!attachUrl) {
+        throw new Error("--attach URL is required for chimphands serve");
+    }
+    // Wait for OpenCode server readiness.
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(attachUrl.replace(/\/$/, "") + "/");
+            if (res.ok || res.status === 401 || res.status === 404)
+                break;
+        }
+        catch {
+            /* retry */
+        }
+        await sleep(500);
     }
-    sessionActive = false;
-    stopInbound();
-    await poster.flush();
-    console.error("ChimpHands session idle — no user input before timeout; completing.");
-    complete(STATUS_IDLE);
+    await runChimphands({ ...opts, attachUrl });
 }

package/dist/cli/program.js

@@ -1589,12 +1589,14 @@ export function buildCliProgram() {
         .description("Bootstrap session, configure OpenCode, and run the interactive bridge")
         .option("--session-id <id>", "ChimpHands session id (or SESSION_ID env)")
         .option("--prompt <text>", "Initial prompt (or PROMPT env)")
+        .option("--attach <url>", "Attach to OpenCode server (e.g. http://127.0.0.1:4096)")
         .action(async (opts) => {
         const { runChimphands } = await import("../chimphands/run.js");
         try {
             await runChimphands({
                 sessionId: String(opts.sessionId || process.env.SESSION_ID || "").trim(),
                 prompt: opts.prompt != null ? String(opts.prompt) : undefined,
+                attachUrl: opts.attach != null ? String(opts.attach).trim() : undefined,
             });
         }
         catch (e) {
@@ -1603,6 +1605,27 @@ export function buildCliProgram() {
             process.exit(1);
         }
     });
+    chimphands
+        .command("serve")
+        .description("Register ChimpHands Runtime, attach to OpenCode server, run session bridge + UI tunnel")
+        .option("--session-id <id>", "ChimpHands session id (or SESSION_ID env)")
+        .option("--prompt <text>", "Initial prompt (or PROMPT env)")
+        .requiredOption("--attach <url>", "OpenCode server URL (e.g. http://127.0.0.1:4096)")
+        .action(async (opts) => {
+        const { serveChimphands } = await import("../chimphands/run.js");
+        try {
+            await serveChimphands({
+                sessionId: String(opts.sessionId || process.env.SESSION_ID || "").trim(),
+                prompt: opts.prompt != null ? String(opts.prompt) : undefined,
+                attachUrl: String(opts.attach || "").trim(),
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`[testchimp chimphands serve] ${msg}`);
+            process.exit(1);
+        }
+    });
     program.on("--help", () => {
         /* default */
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",
@@ -23,10 +23,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
+    "ws": "^8.21.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
+    "@types/ws": "^8.18.1",
     "typescript": "^6.0.2"
   },
   "keywords": [