@testchimp/cli 0.1.43 → 0.1.45

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

@@ -19,7 +19,14 @@ const STATUS_IDLE = "CHIMPHANDS_SESSION_STATUS_IDLE";
 const STATUS_FAILED = "CHIMPHANDS_SESSION_STATUS_FAILED";
 const OPENCODE_AGENT_ID = "chimphands";
 const STREAM_POST_MIN_INTERVAL_MS = 60;
-const CHIMPHANDS_AGENT_PROMPT = `You are ChimpHands, TestChimp's cloud coding agent running in GitHub Actions.
+const CHIMPHANDS_AGENT_PROMPT = `You are ChimpHands, TestChimp's coding agent. You run on GitHub Actions, but this chat is an **interactive** conversation with the user in the TestChimp UI — same expectations as Cursor/Claude Code locally.
+
+## Interactive session (mandatory — default)
+- Default mode is **interactive**. Ask clarifying questions, seek plan approval, and wait for the user's reply — just as you would in Cursor.
+- \`GITHUB_ACTIONS\`, \`CLOUD_AGENT\`, and "running in CI" mean **where** you execute (runner + \`TESTCHIMP_EXECUTION_SOURCE\`). They do **NOT** mean skip questions, invent defaults, or auto-approve.
+- Only treat the run as non-interactive when the **user prompt** literally includes \`--mode=non-interactive\` (or \`mode=non-interactive\`), or the resolved skill policy explicitly sets \`allow-execute-without-approval\`.
+- When you need clarification (e.g. import plans/tests, env strategy, CI choices) or plan approval: write the questions / plan summary as assistant text, then **stop this turn**. Do not invent answers or continue into Execute. The host will wait for the next chat message and revive you.
+- Prefer a short numbered list of concrete questions over a long monologue. One decision gate at a time when possible (especially \`/testchimp project init\` Phase 1).
 
 ## Repo changes (mandatory)
 - NEVER commit or push directly to the default branch (main/master).
@@ -27,14 +34,17 @@ const CHIMPHANDS_AGENT_PROMPT = `You are ChimpHands, TestChimp's cloud coding ag
 - 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\`).
 - Branch names MUST start with \`testchimp-\` or \`chimphands-\`.
-- After creating a branch or opening a PR, IMMEDIATELY run:
+- 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 —
+  do not report a branch that only exists locally (that causes GitHub 404).
+- After the branch is on the remote (and after opening a PR), IMMEDIATELY run:
   \`testchimp chimphands report-branch --branch <name> [--pr-url <url>]\`
 - Tell the user which branch you are on and include the PR URL when available.
 
 ## TestChimp workflows (/testchimp …)
 - Load and follow the \`testchimp\` skill under \`.agents/skills/testchimp/SKILL.md\`.
 - For any /testchimp command: use TestChimp MCP tools (preferred) or \`testchimp\` CLI — never invent API results.
-- Follow plan → explicit user approval → execute. Do not skip MCP calls or claim done without tool evidence.
+- Follow plan → explicit user approval → execute (interactive default). Do not skip MCP calls or claim done without tool evidence.
 - Export \`TESTCHIMP_EXECUTION_SOURCE=CLOUD_AGENT\` before Playwright/Mobilewright runs.
 
 ## Honesty
@@ -251,12 +261,21 @@ function isMissingOpencodeSessionError(message) {
         m.includes("unknown session") ||
         m.includes("invalid session"));
 }
+function isNonInteractivePrompt(userPrompt) {
+    return /(?:^|\s)--mode\s*=?\s*non-interactive\b|mode\s*=\s*non-interactive\b/i.test(userPrompt);
+}
+function isTestchimpWorkflowPrompt(userPrompt) {
+    return /(?:^|\s)\/?testchimp\b/i.test(userPrompt.trim());
+}
 function wrapPromptWithContext(conversationSummary, userPrompt, isNewOpencodeSession, workingBranch, pullRequestUrl) {
     const parts = [];
     if (workingBranch?.trim()) {
         parts.push("## Conversation working branch (reuse for this thread)", `Branch: \`${workingBranch.trim()}\``, pullRequestUrl?.trim() ? `PR: ${pullRequestUrl.trim()}` : "", "Checkout this branch, commit and push here. Do NOT open a new PR unless the one above was merged/closed.", "");
     }
     const task = normalizeUserMessage(userPrompt);
+    if (isTestchimpWorkflowPrompt(task) && !isNonInteractivePrompt(task)) {
+        parts.push("## Interactive turn reminder", "This is an interactive ChimpHands chat (not autonomous CI). Ask clarifying questions / seek plan approval, then end the turn and wait — do not invent defaults or Execute until the user replies. Only `--mode=non-interactive` skips that pause.", "");
+    }
     if (isNewOpencodeSession && conversationSummary.trim()) {
         parts.push(`Conversation so far:\n${conversationSummary.trim()}`, "", `Current task:\n${task}`);
         return parts.filter(Boolean).join("\n");
@@ -272,10 +291,10 @@ function detectWorkingBranchFromToolOutput(output) {
     if (!text)
         return {};
     const prMatch = text.match(/https:\/\/github\.com\/[^\s)\]]+\/pull\/\d+/);
-    const checkoutMatch = text.match(/checkout\s+-b\s+((?:testchimp-|chimphands-)[^\s'"]+)/i);
+    // Only auto-detect after a successful push to origin — local checkout -b alone would
+    // report a branch URL that 404s until the remote ref exists.
     const pushMatch = text.match(/push\s+(?:--set-upstream\s+|-u\s+)?origin\s+((?:testchimp-|chimphands-)[^\s'"]+)/i);
-    const branchMatch = text.match(/branch['":\s]+((?:testchimp-|chimphands-)[^\s'"]+)/i);
-    const branch = (checkoutMatch?.[1] || pushMatch?.[1] || branchMatch?.[1])?.replace(/[`'"]/g, "");
+    const branch = pushMatch?.[1]?.replace(/[`'"]/g, "");
     return {
         branch,
         pullRequestUrl: prMatch?.[0],
@@ -351,16 +370,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,
@@ -577,6 +599,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,
     });
@@ -591,6 +615,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;
@@ -598,10 +646,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)
@@ -624,6 +699,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) {
@@ -687,67 +763,64 @@ 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 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", {
@@ -757,43 +830,317 @@ 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}`);
+        if (!stopped)
+            setTimeout(tick, 15_000);
+    };
+    void tick();
+    return () => {
+        stopped = true;
+    };
+}
+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));
+        };
+        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) {
+                        send({
+                            type: "http_response_chunk",
+                            requestId,
+                            bodyBase64: Buffer.from(value).toString("base64"),
+                        });
+                    }
+                }
+            }
+            else {
+                const buf = Buffer.from(await upstream.arrayBuffer());
+                if (buf.length) {
+                    send({
+                        type: "http_response_chunk",
+                        requestId,
+                        bodyBase64: buf.toString("base64"),
+                    });
+                }
+            }
+            send({ type: "http_response_end", requestId });
+        }
+        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}`);
+        });
+        socket.on("message", (data) => {
+            if (stopped)
+                return;
             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,
-                });
+                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 (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);
+            catch (err) {
+                console.error(`ChimpHands tunnel frame error: ${err instanceof Error ? err.message : String(err)}`);
             }
-            process.exit(result.code || 1);
+        });
+        socket.on("close", () => {
+            ws = null;
+            if (stopped)
+                return;
+            console.error(`ChimpHands agent tunnel WS closed; 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;
         }
-        postEvent(ROLE_STATUS, "Waiting for user input", { status: STATUS_WAITING_USER });
-        lastUserActivity = Date.now();
-        idle = false;
-        prompt = (await waitForNextPrompt()) || "";
+    };
+}
+/** 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.43",
+  "version": "0.1.45",
   "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": [