@testchimp/cli 0.1.69 → 0.1.71

package/dist/chimphands/agentBranch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ChimpHands CI git: base branch (parent) vs agent branch (testchimp-* only).
+ */
+export declare const BASE_BRANCH_PREFIX = "Base branch: ";
+/** @deprecated Legacy platform line; still parsed for in-flight sessions. */
+export declare const LEGACY_WORKING_BRANCH_PREFIX = "Working branch: ";
+export declare function isAgentBranchName(branch: string): boolean;
+export declare function parseBaseBranchFromPrompt(prompt: string): string | undefined;
+export declare function resolveSessionBaseBranch(prompt: string | undefined, envBaseBranch?: string): string | undefined;
+export declare function buildAgentBranchName(sessionId: string): string;
+type GitRunResult = {
+    code: number;
+    out: string;
+    err: string;
+};
+export declare function runGit(args: string[], env?: NodeJS.ProcessEnv): Promise<GitRunResult>;
+export type EnsureAgentBranchOptions = {
+    sessionId: string;
+    baseBranch?: string;
+    /** Agent branch already reported for this session (bootstrap). */
+    existingAgentBranch?: string;
+};
+export type EnsureAgentBranchResult = {
+    agentBranch: string;
+    baseBranch?: string;
+    created: boolean;
+};
+/**
+ * Ensures the runner is on a published testchimp-* agent branch.
+ * When checked out on the user's base branch, creates testchimp-chimphands-<session> from it.
+ */
+export declare function ensureAgentSessionBranch(opts: EnsureAgentBranchOptions): Promise<EnsureAgentBranchResult>;
+export type EnsurePullRequestOptions = {
+    agentBranch: string;
+    baseBranch: string;
+    title?: string;
+    body?: string;
+};
+/** Opens a PR from agent branch → base branch when none exists. Returns PR URL if created/found. */
+export declare function ensurePullRequest(opts: EnsurePullRequestOptions): Promise<string | undefined>;
+export declare function isPrOnlyMode(): boolean;
+export {};

package/dist/chimphands/agentBranch.js

@@ -0,0 +1,174 @@
+/**
+ * ChimpHands CI git: base branch (parent) vs agent branch (testchimp-* only).
+ */
+import { spawn } from "node:child_process";
+export const BASE_BRANCH_PREFIX = "Base branch: ";
+/** @deprecated Legacy platform line; still parsed for in-flight sessions. */
+export const LEGACY_WORKING_BRANCH_PREFIX = "Working branch: ";
+const BASE_BRANCH_LINE = /^(?:Base branch|Working branch):\s*(.+)$/im;
+const AGENT_BRANCH_PREFIX = /^testchimp-/i;
+export function isAgentBranchName(branch) {
+    return AGENT_BRANCH_PREFIX.test(branch.trim());
+}
+export function parseBaseBranchFromPrompt(prompt) {
+    if (!prompt?.trim())
+        return undefined;
+    let last;
+    for (const line of prompt.split("\n")) {
+        const m = line.match(BASE_BRANCH_LINE);
+        if (!m?.[1])
+            continue;
+        const candidate = m[1].trim();
+        if (candidate)
+            last = candidate;
+    }
+    return last;
+}
+export function resolveSessionBaseBranch(prompt, envBaseBranch) {
+    const fromPrompt = prompt ? parseBaseBranchFromPrompt(prompt) : undefined;
+    if (fromPrompt)
+        return fromPrompt;
+    const fromEnv = envBaseBranch?.trim();
+    return fromEnv || undefined;
+}
+export function buildAgentBranchName(sessionId) {
+    const slug = sessionId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 10).toLowerCase() || "session";
+    return `testchimp-chimphands-${slug}`;
+}
+export function runGit(args, env) {
+    return 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 }));
+    });
+}
+async function currentBranch() {
+    const r = await runGit(["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (r.code !== 0)
+        return undefined;
+    const b = r.out.trim();
+    return b && b !== "HEAD" ? b : undefined;
+}
+async function isDirtyWorktree() {
+    const r = await runGit(["status", "--porcelain"]);
+    return r.code === 0 && !!r.out.trim();
+}
+/**
+ * Ensures the runner is on a published testchimp-* agent branch.
+ * When checked out on the user's base branch, creates testchimp-chimphands-<session> from it.
+ */
+export async function ensureAgentSessionBranch(opts) {
+    const baseBranch = opts.baseBranch?.trim() || undefined;
+    const existing = opts.existingAgentBranch?.trim();
+    if (existing && isAgentBranchName(existing)) {
+        await checkoutLocalBranch(existing);
+        return { agentBranch: existing, baseBranch, created: false };
+    }
+    const current = await currentBranch();
+    if (current && isAgentBranchName(current)) {
+        return { agentBranch: current, baseBranch, created: false };
+    }
+    const agentBranch = buildAgentBranchName(opts.sessionId);
+    const create = await runGit(["checkout", "-b", agentBranch]);
+    if (create.code !== 0) {
+        throw new Error(`git checkout -b ${agentBranch} failed: ${create.err || create.out || "unknown"}`);
+    }
+    const push = await runGit(["push", "-u", "origin", "HEAD"]);
+    if (push.code !== 0) {
+        throw new Error(`git push failed for new agent branch: ${push.err || push.out || "unknown"}`);
+    }
+    console.error(`ChimpHands created agent branch ${agentBranch}` +
+        (baseBranch ? ` from base ${baseBranch}` : ""));
+    return { agentBranch, baseBranch, created: true };
+}
+async function checkoutLocalBranch(branch) {
+    const r = await runGit(["checkout", branch]);
+    if (r.code !== 0) {
+        throw new Error(`git checkout ${branch} failed: ${r.err || r.out || "unknown"}`);
+    }
+}
+/** Opens a PR from agent branch → base branch when none exists. Returns PR URL if created/found. */
+export async function ensurePullRequest(opts) {
+    const agentBranch = opts.agentBranch.trim();
+    const baseBranch = opts.baseBranch.trim();
+    if (!agentBranch || !baseBranch || agentBranch === baseBranch)
+        return undefined;
+    const list = await runGh([
+        "pr",
+        "list",
+        "--head",
+        agentBranch,
+        "--base",
+        baseBranch,
+        "--state",
+        "open",
+        "--json",
+        "url",
+        "--jq",
+        ".[0].url",
+    ]);
+    if (list.code === 0 && list.out.trim()) {
+        return list.out.trim();
+    }
+    const dirty = await isDirtyWorktree();
+    if (dirty) {
+        return undefined;
+    }
+    const headAhead = await runGit(["rev-list", "--count", `${baseBranch}..${agentBranch}`]);
+    const aheadCount = Number.parseInt(headAhead.out.trim(), 10);
+    if (headAhead.code !== 0 || !Number.isFinite(aheadCount) || aheadCount <= 0) {
+        return undefined;
+    }
+    const title = opts.title?.trim() || `ChimpHands: ${agentBranch}`;
+    const body = opts.body?.trim() ||
+        `Automated changes from ChimpHands session on branch \`${agentBranch}\`.\n\nMerge target: \`${baseBranch}\`.`;
+    const create = await runGh([
+        "pr",
+        "create",
+        "--base",
+        baseBranch,
+        "--head",
+        agentBranch,
+        "--title",
+        title,
+        "--body",
+        body,
+    ]);
+    if (create.code !== 0) {
+        console.error(`ChimpHands gh pr create failed: ${create.err || create.out}`);
+        return undefined;
+    }
+    const url = (create.out || create.err).trim().match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/)?.[0];
+    return url;
+}
+function runGh(args) {
+    return new Promise((resolve) => {
+        const child = spawn("gh", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            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 }));
+    });
+}
+export function isPrOnlyMode() {
+    const v = (process.env.CHIMPHANDS_PR_ONLY || "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}

package/dist/chimphands/agentBranch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/chimphands/agentBranch.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { buildAgentBranchName, isAgentBranchName, parseBaseBranchFromPrompt, resolveSessionBaseBranch, } from "./agentBranch.js";
+describe("agentBranch", () => {
+    it("isAgentBranchName accepts testchimp- only", () => {
+        assert.equal(isAgentBranchName("testchimp-foo"), true);
+        assert.equal(isAgentBranchName("chimphands-foo"), false);
+        assert.equal(isAgentBranchName("feature/foo"), false);
+    });
+    it("parseBaseBranchFromPrompt reads Base and legacy Working lines", () => {
+        assert.equal(parseBaseBranchFromPrompt("run qa\nBase branch: dashboard"), "dashboard");
+        assert.equal(parseBaseBranchFromPrompt("Working branch: main"), "main");
+        assert.equal(parseBaseBranchFromPrompt("run qa only"), undefined);
+    });
+    it("resolveSessionBaseBranch prefers prompt over env", () => {
+        assert.equal(resolveSessionBaseBranch("Base branch: a", "b"), "a");
+        assert.equal(resolveSessionBaseBranch(undefined, "b"), "b");
+    });
+    it("buildAgentBranchName uses testchimp prefix", () => {
+        assert.match(buildAgentBranchName("01ARZ3NDEKTSV4RRFFQ69G5FAV"), /^testchimp-chimphands-/);
+    });
+});

package/dist/chimphands/run.js

@@ -14,6 +14,7 @@ import { getBackendUrl, requireApiKey } from "../core/client.js";
 import { isChimphandsLlmRetryEnabled, startLlmRetryProxy } from "./llmRetryProxy.js";
 import { midTurnSteeringKey, releaseUnansweredMidTurnMessages, } from "./midTurnSteering.js";
 import { runSteeringSidecarReply } from "./steeringSidecar.js";
+import { ensureAgentSessionBranch, ensurePullRequest, isAgentBranchName, isPrOnlyMode, resolveSessionBaseBranch, runGit, } from "./agentBranch.js";
 const ROLE_ASSISTANT = "CHIMPHANDS_MESSAGE_ROLE_ASSISTANT";
 const ROLE_TOOL = "CHIMPHANDS_MESSAGE_ROLE_TOOL";
 const ROLE_REASONING = "CHIMPHANDS_MESSAGE_ROLE_REASONING";
@@ -24,8 +25,10 @@ const STATUS_IDLE = "CHIMPHANDS_SESSION_STATUS_IDLE";
 const STATUS_FAILED = "CHIMPHANDS_SESSION_STATUS_FAILED";
 const OPENCODE_AGENT_ID = "chimphands";
 const MID_TURN_DELIVERED_STATUS = "Answering your question while the current step continues…";
-/** Coalesce live token fanout (~6–10 posts/s/session) while UI is attached. */
-const STREAM_POST_MIN_INTERVAL_MS = 150;
+/** Coalesce live token fanout (~30fps) on tunnel WS / HTTP fallback while UI is attached. */
+const STREAM_FANOUT_MIN_INTERVAL_MS = 33;
+/** Set for the active ChimpHands session (PR base branch + callbacks). */
+let activeSessionGitContext = null;
 function isStreamFanoutRole(role) {
     return role === ROLE_ASSISTANT || role === ROLE_TOOL || role === ROLE_REASONING;
 }
@@ -66,18 +69,24 @@ const CHIMPHANDS_AGENT_PROMPT = `You are ChimpHands, TestChimp's coding agent. Y
 - 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).
 
+## Paths (mandatory)
+- Process cwd **is** the git worktree root. On GitHub Actions that is \`$GITHUB_WORKSPACE\`, which looks like \`/home/runner/work/<repo>/<repo>\` — the repeated folder name is the normal Actions layout, **not** a nested second checkout.
+- User \`ref:\` paths are **repo-relative to cwd** (e.g. \`ref: ui/plans/foo.md\` → open \`ui/plans/foo.md\` from cwd). Never prepend the repository name. Never open or create \`<repo>/<repo>/…\` under cwd. Never treat \`/home/runner/work\` (the parent of the twin) as the worktree root.
+- If a tool returns an absolute path under cwd, relativize with the worktree root before reusing it. Do **not** strip a leading \`/\` and re-join under cwd — that nests the workspace path inside itself.
+
 ## Repo changes (mandatory)
-- NEVER commit or push directly to the default branch (main/master).
-- 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. When \`CHIMPHANDS_UI_ATTACHED\` is \`false\` (no browser watching live), **commit and push before ending every turn** so the user can review async via PR / Files changed. The host also commits any remaining dirty worktree after each turn and before idle teardown.
-- Branch names MUST start with \`testchimp-\` or \`chimphands-\`.
-- When creating a NEW working branch: create it, then IMMEDIATELY publish it with
+- NEVER commit or push directly to the default branch (main/master) or to a user **base branch** (the \`Base branch:\` line in the prompt is the parent to branch *from*, not where you commit).
+- This conversation uses ONE **agent branch** (\`testchimp-*\` only) and ONE pull request targeting the base branch. Reuse them for all follow-up work in this chat.
+- If bootstrap lists an agent branch (\`testchimp-*\`), checkout that branch and push additional commits there — update the same PR.
+- Only create a NEW agent branch/PR when (a) no \`testchimp-*\` 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 agent branch after meaningful edit batches. When \`CHIMPHANDS_UI_ATTACHED\` is \`false\` (no browser watching live), **commit and push before ending every turn** so the user can review async via PR / Files changed. The host also commits any remaining dirty worktree after each turn and before idle teardown.
+- Branch names for commits and PRs MUST start with \`testchimp-\` (never \`chimphands-*\` or the base branch name).
+- When the prompt includes \`Base branch: <name>\`: the workflow may already have that branch checked out (\`CHIMPHANDS_WORK_BRANCH\`). Create \`git checkout -b testchimp-<scope>\` from it, push, then work only on the \`testchimp-*\` branch. Open PRs with \`gh pr create --base <base-branch> --head <testchimp-branch>\`.
+- When creating a NEW agent 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>]\`
+  \`testchimp chimphands report-branch --branch <testchimp-branch> [--pr-url <url>]\`
 - Tell the user which branch you are on and include the PR URL when available.
 - **GitHub auth expiry (self-fix):** Job-start App installation tokens expire after ~1 hour. On \`git push\` / \`gh\` auth failures (401/403 / Authentication failed / write access not granted), run \`testchimp chimphands refresh-git-auth\` then retry — **never** ask the user to paste or reconnect a GitHub token in chat. See skill \`references/chimphands-faq.md\`.
 
@@ -119,6 +128,9 @@ export async function reportWorkingBranch(opts) {
     if (!branch) {
         throw new Error("branch is required");
     }
+    if (!isAgentBranchName(branch)) {
+        throw new Error("branch must start with testchimp- (agent feature branch, not the base branch)");
+    }
     const body = {
         sessionId: opts.sessionId.trim(),
         workingBranch: branch,
@@ -155,23 +167,42 @@ async function postJson(backend, apiKey, path, body) {
         clearTimeout(timer);
     }
 }
-/** Serializes agent event posts so streaming chunks fan out in order. */
+/** Serializes durable agent event posts; live mid-turn tokens prefer the agent tunnel WS. */
 class AgentEventPoster {
     backend;
     apiKey;
     sessionId;
     chain = Promise.resolve();
-    lastStreamPostAt = 0;
+    lastLiveFanoutAt = 0;
     /** When false, liveStream tokens are dropped; completed events still persist. */
     uiAttached = false;
+    /**
+     * Prefer agent tunnel WS for live tokens. Returns true when the frame was queued on an open socket.
+     * Set by {@link startTunnelWorker} once the runtime tunnel is connected.
+     */
+    sendUiMessage = null;
     ephemeralFailLogAt = 0;
     ephemeralFailCount = 0;
+    /** Latest pending live snapshot per messageId (coalesce-to-latest). */
+    pendingLive = new Map();
+    liveFlushTimer = null;
+    liveFlushInFlight = false;
     constructor(backend, apiKey, sessionId) {
         this.backend = backend;
         this.apiKey = apiKey;
         this.sessionId = sessionId;
     }
     enqueue(role, content, opts) {
+        const streamRole = isStreamFanoutRole(role);
+        const live = !!opts?.liveStream && !opts?.durable;
+        // Mid-turn tokens: coalesce + WS (HTTP fallback). Never hit the durable chain.
+        if (live && streamRole) {
+            if (!this.uiAttached) {
+                return Promise.resolve();
+            }
+            this.enqueueLive(role, content, opts);
+            return Promise.resolve();
+        }
         const body = {
             sessionId: this.sessionId,
             role,
@@ -189,48 +220,95 @@ class AgentEventPoster {
             body.pullRequestUrl = opts.pullRequestUrl;
         if (opts?.toolExecution)
             body.toolExecution = protoJsonToolExecution(opts.toolExecution);
-        const streamRole = isStreamFanoutRole(role);
         this.chain = this.chain.then(async () => {
-            const live = !!opts?.liveStream && !opts?.durable;
-            // Mid-turn tokens never hit PG. Async / detached: drop. Attached: ephemeral only.
-            if (live && !this.uiAttached) {
-                return;
+            await postJson(this.backend, this.apiKey, "/api/chimphands/post_agent_event", body);
+        });
+        return this.chain;
+    }
+    enqueueLive(role, content, opts) {
+        const key = (opts?.messageId || "").trim() || `${role}:default`;
+        this.pendingLive.set(key, { role, content: String(content || "").slice(0, 20000), opts });
+        this.scheduleLiveFlush();
+    }
+    scheduleLiveFlush() {
+        if (this.liveFlushInFlight || this.liveFlushTimer)
+            return;
+        const wait = Math.max(0, STREAM_FANOUT_MIN_INTERVAL_MS - (Date.now() - this.lastLiveFanoutAt));
+        this.liveFlushTimer = setTimeout(() => {
+            this.liveFlushTimer = null;
+            void this.flushLivePending();
+        }, wait);
+    }
+    async flushLivePending() {
+        if (this.liveFlushInFlight)
+            return;
+        if (this.pendingLive.size === 0)
+            return;
+        if (!this.uiAttached) {
+            this.pendingLive.clear();
+            return;
+        }
+        this.liveFlushInFlight = true;
+        try {
+            const batch = [...this.pendingLive.values()];
+            this.pendingLive.clear();
+            this.lastLiveFanoutAt = Date.now();
+            for (const item of batch) {
+                await this.deliverLive(item.role, item.content, item.opts);
             }
-            if (opts?.throttle || (streamRole && live)) {
-                const now = Date.now();
-                const wait = STREAM_POST_MIN_INTERVAL_MS - (now - this.lastStreamPostAt);
-                if (wait > 0)
-                    await sleep(wait);
-                this.lastStreamPostAt = Date.now();
-            }
-            const tryEphemeral = live && streamRole && this.uiAttached;
-            if (tryEphemeral) {
-                const eph = {
-                    sessionId: this.sessionId,
-                    role,
-                    content: body.content,
-                };
-                if (opts?.messageId)
-                    eph.messageId = opts.messageId;
-                if (opts?.opencodeSessionId)
-                    eph.opencodeSessionId = opts.opencodeSessionId;
-                if (opts?.toolExecution)
-                    eph.toolExecution = protoJsonToolExecution(opts.toolExecution);
-                try {
-                    await postJson(this.backend, this.apiKey, "/api/chimphands/post_ephemeral_agent_event", eph);
+        }
+        finally {
+            this.liveFlushInFlight = false;
+            if (this.pendingLive.size > 0 && this.uiAttached) {
+                this.scheduleLiveFlush();
+            }
+        }
+    }
+    async deliverLive(role, content, opts) {
+        const frame = {
+            type: "ui_message",
+            sessionId: this.sessionId,
+            role,
+            content,
+        };
+        if (opts?.messageId)
+            frame.messageId = opts.messageId;
+        if (opts?.toolExecution)
+            frame.toolExecution = protoJsonToolExecution(opts.toolExecution);
+        if (this.sendUiMessage) {
+            try {
+                if (this.sendUiMessage(frame)) {
                     this.ephemeralFailCount = 0;
+                    return;
                 }
-                catch (err) {
-                    const detail = err instanceof Error ? err.message : String(err);
-                    this.logEphemeralIssue(`ephemeral post failed — not persisting liveStream: ${detail}`);
-                }
-                return;
             }
-            await postJson(this.backend, this.apiKey, "/api/chimphands/post_agent_event", body);
-        });
-        return this.chain;
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                this.logEphemeralIssue(`tunnel ui_message send failed — falling back to HTTP: ${detail}`);
+            }
+        }
+        // HTTP ephemeral fallback when tunnel is down / unavailable.
+        const eph = {
+            sessionId: this.sessionId,
+            role,
+            content,
+        };
+        if (opts?.messageId)
+            eph.messageId = opts.messageId;
+        if (opts?.opencodeSessionId)
+            eph.opencodeSessionId = opts.opencodeSessionId;
+        if (opts?.toolExecution)
+            eph.toolExecution = protoJsonToolExecution(opts.toolExecution);
+        try {
+            await postJson(this.backend, this.apiKey, "/api/chimphands/post_ephemeral_agent_event", eph);
+            this.ephemeralFailCount = 0;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            this.logEphemeralIssue(`ephemeral post failed — not persisting liveStream: ${detail}`);
+        }
     }
-    /** Avoid flooding GHA logs when ephemeral 500s every ~150ms. */
+    /** Avoid flooding GHA logs when live fanout fails repeatedly. */
     logEphemeralIssue(message) {
         this.ephemeralFailCount += 1;
         const now = Date.now();
@@ -247,7 +325,11 @@ class AgentEventPoster {
         });
     }
     flush() {
-        return this.chain;
+        if (this.liveFlushTimer) {
+            clearTimeout(this.liveFlushTimer);
+            this.liveFlushTimer = null;
+        }
+        return this.flushLivePending().then(() => this.chain);
     }
     reportWorkingBranch(branch, pullRequestUrl) {
         this.chain = this.chain.then(async () => {
@@ -966,10 +1048,13 @@ function isAssistantEchoOfSentPrompt(assistant, ...sentPrompts) {
     }
     return false;
 }
-function wrapPromptWithContext(conversationSummary, userPrompt, isNewOpencodeSession, workingBranch, pullRequestUrl) {
+function wrapPromptWithContext(conversationSummary, userPrompt, isNewOpencodeSession, workingBranch, pullRequestUrl, baseBranch) {
     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.", "");
+    if (baseBranch?.trim()) {
+        parts.push("## Base branch (parent — do NOT commit here)", `Base branch: \`${baseBranch.trim()}\``, "Create a `testchimp-*` branch from this parent before any file edits. PRs must target this base branch.", "");
+    }
+    if (workingBranch?.trim() && isAgentBranchName(workingBranch)) {
+        parts.push("## Conversation agent branch (reuse for this thread)", `Branch: \`${workingBranch.trim()}\``, pullRequestUrl?.trim() ? `PR: ${pullRequestUrl.trim()}` : "", "Checkout this testchimp-* branch, commit and push here. Do NOT open a new PR unless the one above was merged/closed.", "");
     }
     const task = normalizeUserMessage(userPrompt);
     // Do NOT inject "Interactive turn reminder" into the user prompt — it is already in
@@ -992,7 +1077,7 @@ function detectWorkingBranchFromToolOutput(output) {
     const prMatch = text.match(/https:\/\/github\.com\/[^\s)\]]+\/pull\/\d+/);
     // 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 pushMatch = text.match(/push\s+(?:--set-upstream\s+|-u\s+)?origin\s+((?:testchimp-)[^\s'"\[\]]+)/i);
     const branch = pushMatch?.[1]?.replace(/[`'"\[\]]/g, "");
     return {
         branch,
@@ -1487,12 +1572,36 @@ function runOpencode(prompt, model, childEnv, opencodeSessionId, callbacks, atta
         });
     });
 }
-function normalizeWorktreeRelativePath(filePath) {
-    let p = String(filePath || "").trim().replace(/\\/g, "/");
+function normalizeWorktreeRelativePath(filePath, worktreeRoot = process.cwd()) {
+    const rootResolved = path.resolve(worktreeRoot);
+    const rawInput = String(filePath || "").trim();
+    if (!rawInput || rawInput.includes("\0")) {
+        throw new Error("invalid path");
+    }
+    // Absolute path under the worktree → repo-relative (never strip "/" then re-join).
+    if (path.isAbsolute(rawInput)) {
+        const abs = path.resolve(rawInput);
+        if (abs === rootResolved) {
+            throw new Error("invalid path");
+        }
+        if (abs.startsWith(rootResolved + path.sep)) {
+            return path.relative(rootResolved, abs).split(path.sep).join("/");
+        }
+    }
+    let p = rawInput.replace(/\\/g, "/");
     while (p.startsWith("/"))
         p = p.slice(1);
-    if (!p || p.includes("\0")) {
-        throw new Error("invalid path");
+    // GHA workspace is /home/runner/work/<repo>/<repo>. Strip twin prefixes that agents/OpenCode
+    // sometimes emit as if relative to /home/runner/work.
+    const base = path.basename(rootResolved);
+    const parentBase = path.basename(path.dirname(rootResolved));
+    if (base && base === parentBase) {
+        const twin = `${base}/${base}/`;
+        const gha = `home/runner/work/${base}/${base}/`;
+        if (p.startsWith(gha))
+            p = p.slice(gha.length);
+        else if (p.startsWith(twin))
+            p = p.slice(twin.length);
     }
     const segments = [];
     for (const part of p.split("/")) {
@@ -1844,9 +1953,16 @@ export async function runChimphands(opts) {
         const prIsNew = !!prUrl?.trim() && prUrl.trim() !== pullRequestUrl;
         if (workingBranch === normalizedBranch && !prIsNew)
             return;
+        if (!isAgentBranchName(normalizedBranch))
+            return;
         workingBranch = normalizedBranch;
         if (prUrl?.trim())
             pullRequestUrl = prUrl.trim();
+        if (activeSessionGitContext) {
+            activeSessionGitContext.agentBranch = normalizedBranch;
+            if (pullRequestUrl)
+                activeSessionGitContext.pullRequestUrl = pullRequestUrl;
+        }
         if (branchIsNew || prIsNew) {
             poster.reportWorkingBranch(normalizedBranch, nextPr);
         }
@@ -2082,11 +2198,16 @@ export async function runChimphands(opts) {
         void pollPendingUserMessages();
     }, 1500);
     if (runtimeId && attachUrl) {
-        stopTunnel = startTunnelWorker(backend, apiKey, runtimeId, attachUrl, sessionId, {
+        const tunnel = startTunnelWorker(backend, apiKey, runtimeId, attachUrl, sessionId, {
             onUserFileEdit: handleUserFileEdit,
             onCancelTurn: handleCancelTurn,
             onUserMessage: enqueueUserMessage,
         });
+        poster.sendUiMessage = (frame) => tunnel.sendUiMessage(frame);
+        stopTunnel = () => {
+            poster.sendUiMessage = null;
+            tunnel.stop();
+        };
     }
     const shutdownRuntime = async () => {
         sessionActive = false;
@@ -2113,6 +2234,7 @@ export async function runChimphands(opts) {
                 status: "CHIMPHANDS_RUNTIME_STATUS_TERMINATED",
             }).catch(() => { });
         }
+        activeSessionGitContext = null;
     };
     try {
         poster.fireAndForget(ROLE_STATUS, "Agent ready", { status: STATUS_RUNNING });
@@ -2134,6 +2256,32 @@ export async function runChimphands(opts) {
                 undefined;
             enqueueUserMessage({ id: id || undefined, content });
         }
+        let sessionBaseBranch = resolveSessionBaseBranch(prompt, process.env.CHIMPHANDS_WORK_BRANCH);
+        activeSessionGitContext = {
+            baseBranch: sessionBaseBranch,
+            agentBranch: workingBranch && isAgentBranchName(workingBranch) ? workingBranch : undefined,
+            pullRequestUrl,
+            onPullRequest: (url) => {
+                if (workingBranch)
+                    noteWorkingBranch(workingBranch, url);
+            },
+        };
+        try {
+            const branchSetup = await ensureAgentSessionBranch({
+                sessionId,
+                baseBranch: sessionBaseBranch,
+                existingAgentBranch: workingBranch && isAgentBranchName(workingBranch) ? workingBranch : undefined,
+            });
+            sessionBaseBranch = branchSetup.baseBranch || sessionBaseBranch;
+            activeSessionGitContext.baseBranch = sessionBaseBranch;
+            activeSessionGitContext.agentBranch = branchSetup.agentBranch;
+            if (!workingBranch || workingBranch !== branchSetup.agentBranch) {
+                noteWorkingBranch(branchSetup.agentBranch);
+            }
+        }
+        catch (err) {
+            console.error(`ChimpHands ensure agent branch failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
         const waitForNextPrompt = () => new Promise((resolve) => {
             let lastPollAt = 0;
             let settled = false;
@@ -2189,7 +2337,7 @@ export async function runChimphands(opts) {
             flushPendingMidTurnInject();
             let useOpencodeSessionId = opencodeSessionId;
             let isNewOpencodeSession = !useOpencodeSessionId;
-            let effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, isNewOpencodeSession, workingBranch, pullRequestUrl);
+            let effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, isNewOpencodeSession, workingBranch, pullRequestUrl, sessionBaseBranch);
             const turnPostEvent = (role, content, opts) => postEventForTurn(prompt, effectivePrompt, role, content, opts);
             // Visible in chat (not filtered as routine). OpenCode may not emit text until a
             // part completes — without this the UI looks empty while the turn is running.
@@ -2213,7 +2361,7 @@ export async function runChimphands(opts) {
                 console.error(`ChimpHands OpenCode session ${useOpencodeSessionId} missing on runner; starting fresh thread.`);
                 opencodeSessionId = undefined;
                 isNewOpencodeSession = true;
-                effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, true, workingBranch, pullRequestUrl);
+                effectivePrompt = wrapPromptWithContext(conversationSummary, prompt, true, workingBranch, pullRequestUrl, sessionBaseBranch);
                 result = await runOpencode(effectivePrompt, opencodeModel, childEnv, undefined, {
                     onSessionId: (id) => {
                         opencodeSessionId = id;
@@ -2350,23 +2498,9 @@ function startRuntimeHeartbeat(backend, apiKey, runtimeId, onUiAttached) {
         stopped = true;
     };
 }
-/** Commit+push dirty worktree on the session branch before idle/teardown (no default-branch writes). */
+/** Commit+push dirty worktree on the session agent branch before idle/teardown. */
 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 }));
-    });
+    const run = (args, env) => runGit(args, env);
     try {
         const branch = await run(["rev-parse", "--abbrev-ref", "HEAD"]);
         if (branch.code !== 0) {
@@ -2375,11 +2509,14 @@ async function commitAndPushDirtyWorktree(message) {
             return { ok: false, error };
         }
         const current = branch.out.trim();
-        if (!current || current === "HEAD" || /^(main|master)$/i.test(current)) {
-            const error = `refusing branch "${current || "(unknown)"}"`;
+        if (!current || current === "HEAD" || !isAgentBranchName(current)) {
+            const error = `refusing non-agent branch "${current || "(unknown)"}" (expected testchimp-*)`;
             console.error(`ChimpHands skip commit-before-idle: ${error}`);
             return { ok: false, error };
         }
+        if (activeSessionGitContext) {
+            activeSessionGitContext.agentBranch = current;
+        }
         const status = await run(["status", "--porcelain"]);
         if (status.code !== 0) {
             const error = status.err || status.out || "git status failed";
@@ -2434,6 +2571,22 @@ async function commitAndPushDirtyWorktree(message) {
             }
         }
         console.error(`ChimpHands committed and pushed dirty worktree on ${current} before shutdown`);
+        const ctx = activeSessionGitContext;
+        if (ctx &&
+            isPrOnlyMode() &&
+            !ctx.pullRequestUrl &&
+            ctx.baseBranch &&
+            isAgentBranchName(current)) {
+            const prUrl = await ensurePullRequest({
+                agentBranch: current,
+                baseBranch: ctx.baseBranch,
+            });
+            if (prUrl) {
+                ctx.pullRequestUrl = prUrl;
+                ctx.onPullRequest?.(prUrl);
+                console.error(`ChimpHands opened PR: ${prUrl}`);
+            }
+        }
         return { ok: true };
     }
     catch (err) {
@@ -2482,6 +2635,18 @@ function startTunnelWorker(backend, apiKey, runtimeId, attachUrl, sessionId, han
             reconnectTimer = null;
         }
     };
+    const sendUiMessage = (frame) => {
+        const socket = ws;
+        if (!socket || socket.readyState !== 1)
+            return false;
+        try {
+            socket.send(JSON.stringify(frame));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
     const handleHttpRequest = async (socket, req) => {
         if (!req.requestId || socket.readyState !== 1)
             return;
@@ -2661,18 +2826,21 @@ function startTunnelWorker(backend, apiKey, runtimeId, attachUrl, sessionId, han
         });
     };
     void connect();
-    return () => {
-        stopped = true;
-        clearReconnect();
-        if (ws) {
-            try {
-                ws.close();
-            }
-            catch {
-                // ignore
+    return {
+        sendUiMessage,
+        stop: () => {
+            stopped = true;
+            clearReconnect();
+            if (ws) {
+                try {
+                    ws.close();
+                }
+                catch {
+                    // ignore
+                }
+                ws = null;
             }
-            ws = null;
-        }
+        },
     };
 }
 /** Runtime-aware entry: register + attach to local OpenCode server (Phase 1+). */

package/dist/cli/program.js

@@ -1607,7 +1607,7 @@ export function buildCliProgram() {
     chimphands
         .command("report-branch")
         .description("Report the conversation working branch (and optional PR URL) to TestChimp")
-        .requiredOption("--branch <name>", "Feature branch name (testchimp-* or chimphands-*)")
+        .requiredOption("--branch <name>", "Agent feature branch name (testchimp-* only)")
         .option("--pr-url <url>", "Open pull request URL")
         .option("--session-id <id>", "ChimpHands session id (or SESSION_ID env)")
         .action(async (opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test dist/chimphands/llmRetryProxy.test.js dist/chimphands/midTurnSteering.test.js dist/chimphands/steeringSidecar.test.js",
+    "test": "npm run build && node --test dist/chimphands/llmRetryProxy.test.js dist/chimphands/midTurnSteering.test.js dist/chimphands/steeringSidecar.test.js dist/chimphands/agentBranch.test.js",
     "watch": "tsc --watch",
     "start": "node dist/bin/testchimp.js",
     "prepublishOnly": "npm run build"