@imdeadpool/guardex 7.0.41 → 7.1.0

package/README.md

@@ -24,10 +24,11 @@
   <a href="#01--install-in-one-line">Install</a> ·
   <a href="#03--what-it-does">What it does</a> ·
   <a href="#04--daily-workflow">Workflow</a> ·
-  <a href="#05--what-gx-shows-first">gx status</a> ·
-  <a href="#07--commands">Commands</a> ·
-  <a href="#08--v6--v7-migration">Migration</a> ·
-  <a href="#10--companion-tools">Companions</a>
+  <a href="#05--dmux-style-multi-agent-cockpit">Cockpit</a> ·
+  <a href="#06--what-gx-shows-first">gx status</a> ·
+  <a href="#08--commands">Commands</a> ·
+  <a href="#09--v6--v7-migration">Migration</a> ·
+  <a href="#11--companion-tools">Companions</a>
 </p>
 
 ---
@@ -56,6 +57,12 @@ gx setup   # hooks, state, OMX / OpenSpec / caveman wiring — one shot
 > feels rough — especially around **cleanup**, **finish**, **merge**, or
 > **recovery** flows — sorry. We're patching as we find things.
 
+> [!CAUTION]
+> **Recommended default: macOS or Linux with Codex CLI.** OMX is primarily
+> designed and actively tuned for that path. Native Windows and Codex App are
+> not the default experience, may break or behave inconsistently, and currently
+> receive less support.
+
 ---
 
 ## The problem
@@ -135,7 +142,30 @@ gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" \
 
 ---
 
-## `05` &nbsp;What `gx` shows first
+## `05` &nbsp;dmux-style multi-agent cockpit
+
+GitGuardex now has a dmux-style cockpit for starting, inspecting, and
+finishing isolated agent lanes from one terminal workspace. It is not a
+dmux clone: GitGuardex keeps safety as the core and adds orchestration
+on top of isolated worktrees, file locks, protected base branches, and
+PR-only finish.
+
+```bash
+gx cockpit
+gx agents start "fix auth tests" --agent codex --base main --claim test/auth.test.js
+gx agents start "fix auth tests" --panel --codex-accounts 3 --base main
+gx agents start "update setup docs" --agent claude --base main --claim README.md
+gx agents status
+gx agents files --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+gx agents diff --branch agent/claude/update-setup-docs-2026-04-29-21-31
+gx agents finish --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+```
+
+Long-form guide: [docs/agents-cockpit.md](./docs/agents-cockpit.md).
+
+---
+
+## `06` &nbsp;What `gx` shows first
 
 Before you branch, repair, or start agents, run plain `gx`. It gives you
 a one-screen status for the CLI, global helpers, repo safety service,
@@ -170,7 +200,7 @@ the compact layout everywhere.
 
 ---
 
-## `06` &nbsp;How `AGENTS.md` is handled
+## `07` &nbsp;How `AGENTS.md` is handled
 
 > [!IMPORTANT]
 > **GitGuardex never overwrites your guidance.** Only content between
@@ -182,12 +212,13 @@ the compact layout everywhere.
 | --- | --- |
 | `AGENTS.md` **with** markers | Refreshes **only** the managed block. |
 | `AGENTS.md` **without** markers | Appends the managed block to the end. |
-| No `AGENTS.md` | Creates it with the managed block. |
+| No `AGENTS.md` | Creates it with the managed block, then links `CLAUDE.md` to it. |
+| No root `CLAUDE.md` | Creates a `CLAUDE.md` symlink to `AGENTS.md`. |
 | A root `CLAUDE.md` | Leaves it alone. |
 
 ---
 
-## `07` &nbsp;Commands
+## `08` &nbsp;Commands
 
 ### Core
 
@@ -209,6 +240,18 @@ the compact layout everywhere.
 | `gx sync` | Sync current agent branch against base. |
 | `gx release` | Update the GitHub release from README notes. |
 
+### Multi-agent cockpit
+
+| command | does |
+| --- | --- |
+| `gx cockpit` | Create or attach to a repo tmux cockpit session with a status pane. |
+| `gx agents start "<task>" --agent codex` | Start an isolated Codex lane for a task. |
+| `gx agents start "<task>" --agent claude` | Start an isolated Claude Code lane for a task. |
+| `gx agents status` | Show repo agent service status. |
+| `gx agents files --branch <agent/...>` | List files changed by one agent lane. |
+| `gx agents diff --branch <agent/...>` | Show the diff for one agent lane. |
+| `gx agents finish --branch <agent/...>` | Finish one agent session through the existing PR flow. |
+
 ```bash
 gx release  # create/update the current GitHub release from README notes
 ```
@@ -227,7 +270,7 @@ gx protect reset   # back to: dev · main · master
 
 ---
 
-## `08` &nbsp;v6 → v7 migration
+## `09` &nbsp;v6 → v7 migration
 
 Five commands were consolidated into flags. Old names still work and
 print a deprecation notice; they'll be removed in v8.
@@ -245,7 +288,7 @@ print a deprecation notice; they'll be removed in v8.
 
 ---
 
-## `09` &nbsp;Known rough edges
+## `10` &nbsp;Known rough edges
 
 Being honest about where this still has issues:
 
@@ -265,6 +308,44 @@ Being honest about where this still has issues:
 <details open>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.43
+- Budget-friendly CI defaults for gitguardex-managed projects: live
+  workflows drop `push: main`, gate per-PR jobs on `pull_request.draft
+  == false`, add `concurrency: cancel-in-progress`, and split per-runtime
+  matrix coverage into a weekly `ci-full.yml`. CodeQL and Scorecard run
+  on the weekly schedule + `workflow_dispatch` only. Templates under
+  `templates/github/workflows/` carry the same posture so downstream
+  projects inherit it via `gx setup`.
+- New `gx ci-init` subcommand scaffolds `ci.yml`, `ci-full.yml`, `cr.yml`,
+  and a `README.md` budget-posture guide into a target repo's
+  `.github/workflows/` directory. Supports `--target`, `--dry-run`,
+  `--force`, `--no-stage`, and `--json`.
+- New `gx budget` subcommand wraps the new GitHub
+  `/settings/billing/usage` endpoint (the legacy
+  `/settings/billing/actions` endpoint was retired in early 2026) and
+  reports monthly Actions minute spend with warn/critical USD thresholds
+  per `--org` or `--user`.
+- Per-PR label opt-in for `agent/*` lanes: `needs-review` runs AI code
+  review on an otherwise-skipped agent PR; `needs-ci-full` triggers the
+  full cross-runtime matrix without waiting for the weekly schedule.
+- `gx branch finish` runs `scripts/agent-preflight.sh` in the worktree
+  before pushing. Default script auto-detects pnpm/npm, Rust, and Python
+  stacks and refuses the push on verification failure. After pre-flight
+  passes, draft PRs are promoted to ready-for-review so the
+  budget-friendly CI defaults fire once on a known-passing commit.
+
+### v7.0.42
+- Bumped `@imdeadpool/guardex` from `7.0.41` to `7.0.42` so the current
+  `main` payload can publish under a fresh npm version after `7.0.41` reached
+  the registry.
+- Improves the agent-session and cockpit workflow: `gx agents start/status`
+  now share canonical session storage, agent lanes can be previewed, claimed,
+  finished by session, and launched through safer supported-agent metadata,
+  and cockpit can render live session state through tmux-backed panes.
+- Hardens setup and status hygiene by ignoring local `.codex/` state during
+  setup/doctor, avoiding generic OpenSpec dirty-worktree reuse, and pruning
+  stale agent sessions from user-facing status surfaces.
+
 ### v7.0.41
 - Bumped `@imdeadpool/guardex` from `7.0.40` to `7.0.41` so the current
   `main` payload can publish under a fresh npm version after the `v7.0.40`
@@ -316,13 +397,13 @@ Being honest about where this still has issues:
 
 ---
 
-## `10` &nbsp;Companion tools
+## `11` &nbsp;Companion tools
 
 All optional — but if you're running many agents, you probably want them.
 `gx status` auto-detects each one and reports it in the `Global services`
 block.
 
-Install repo skills with `npx skills add recodee/gitguardex`; `npx skills add recodee/` opens the recodee namespace. `gx setup` does not auto-run `npx skills add ...`. If the picker does not show a separate `guardex` skill, that is expected.
+Install repo skills with `npx skills add recodee/gitguardex`; the npm package also ships the root `skills/` catalog so the npx installer can read the GitGuardex skill from the published tarball. `npx skills add recodee/` opens the recodee namespace. `gx setup` does not auto-run `npx skills add ...`. If the picker does not show a separate `guardex` skill, that is expected.
 
 | Tool | What it does | Stars |
 | --- | --- | --- |
@@ -333,7 +414,7 @@ Install repo skills with `npx skills add recodee/gitguardex`; `npx skills add re
 | [**cavekit**](https://github.com/JuliusBrussee/cavekit) — `npx skills add JuliusBrussee/cavekit` | Spec-driven build loop with `spec`, `build`, `check`, `caveman`, `backprop` skills bundled in. | [![stars](https://img.shields.io/github/stars/JuliusBrussee/cavekit?style=social)](https://github.com/JuliusBrussee/cavekit) |
 | [**caveman**](https://github.com/JuliusBrussee/caveman) — `npx skills add JuliusBrussee/caveman` | Ultra-compressed response mode for Claude / Codex. Less output-token churn on long reviews and debug loops. | [![stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=social)](https://github.com/JuliusBrussee/caveman) |
 | [**codex-account-switcher**](https://github.com/recodeecom/codex-account-switcher-cli) — `npm i -g @imdeadpool/codex-account-switcher` | Multi-identity Codex account switcher. Auto-registers accounts on `codex login`; switch with one command. | [![stars](https://img.shields.io/github/stars/recodeecom/codex-account-switcher-cli?style=social)](https://github.com/recodeecom/codex-account-switcher-cli) |
-| [**GitHub CLI (`gh`)**](https://github.com/cli/cli) — see [cli.github.com](https://cli.github.com/) | Required for PR / merge automation. `gx branch finish --via-pr --wait-for-merge` depends on it. | [![stars](https://img.shields.io/github/stars/cli/cli?style=social)](https://github.com/cli/cli) |
+| [**GitHub CLI (`gh`)**](https://github.com/cli/cli) — see [cli.github.com](https://cli.github.com/) | Required for PR / merge automation. `gx branch finish --via-pr --wait-for-merge` depends on it. If `ghx` is on `PATH`, Guardex uses that GitHub CLI cache proxy automatically; set `GUARDEX_GH_BIN=gh` to force direct `gh`. | [![stars](https://img.shields.io/github/stars/cli/cli?style=social)](https://github.com/cli/cli) |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.41",
+  "version": "7.1.0",
   "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,
@@ -18,6 +18,7 @@
     "agent:branch:merge": "bash ./scripts/agent-branch-merge.sh",
     "agent:cleanup": "gx cleanup",
     "agent:hooks:install": "bash ./scripts/install-agent-git-hooks.sh",
+    "guardex:install-global": "bash ./scripts/install-global-hooks.sh",
     "agent:locks:claim": "python3 ./scripts/agent-file-locks.py claim",
     "agent:locks:allow-delete": "python3 ./scripts/agent-file-locks.py allow-delete",
     "agent:locks:release": "python3 ./scripts/agent-file-locks.py release",
@@ -39,6 +40,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "templates",
     "README.md",
     "LICENSE",

package/skills/gitguardex/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: gitguardex
+description: "Repo guardrail check and repair."
+---
+
+Use when repo safety may be broken.
+
+`gx status` -> `gx doctor` -> `gx status --strict`
+
+Bootstrap: `gx setup`
+Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`
+
+When inspecting or verifying, prefer `rtk` compact wrappers if available (`rtk git status`, `rtk grep`, `rtk test <cmd>`). Do not wrap commands whose stdout is parsed by scripts.

package/skills/guardex-merge-skills-to-dev/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: guardex-merge-skills-to-dev
+description: "Use when you need to merge SKILL.md updates from agent branches/worktrees into the local base branch (default: dev) with the multiagent-safety flow."
+---
+
+# GuardeX Merge Skills to dev
+
+Use this skill when you only want to promote Codex skill file updates into the base branch (normally `dev`) without editing the visible base checkout directly.
+
+## What this merges
+
+- `skills/**/SKILL.md`
+- `.codex/skills/**/SKILL.md`
+- `templates/codex/skills/**/SKILL.md`
+
+## Merge runbook (safe path)
+
+1. Resolve the base branch:
+
+```sh
+BASE_BRANCH="$(git config --get multiagent.baseBranch || echo dev)"
+echo "$BASE_BRANCH"
+```
+
+2. Start a dedicated integration sandbox from base:
+
+```sh
+gx branch start "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
+```
+
+3. Enter the sandbox worktree printed by the command above.
+
+4. Pull only skill files from each source agent branch:
+
+```sh
+SOURCE_BRANCH="<agent-branch>"
+git checkout "$SOURCE_BRANCH" -- ':(glob)skills/**/SKILL.md' ':(glob).codex/skills/**/SKILL.md' ':(glob)templates/codex/skills/**/SKILL.md'
+```
+
+5. Verify scope before commit:
+
+```sh
+git status --short
+git diff --name-only
+```
+
+6. Commit and merge back to base using guardex finish flow:
+
+```sh
+git add skills .codex/skills templates/codex/skills
+git commit -m "Merge skill file updates into ${BASE_BRANCH}"
+gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
+```
+
+## Notes
+
+- If a source branch has non-skill changes, this runbook keeps them out of the merge.
+- If merge conflicts occur, resolve only within the skill files, then rerun `gx branch finish`.
+- Do not commit directly on `dev`/`main`; always merge through an agent branch/worktree.

package/skills/gx-act/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gx-act
+description: "Run GitHub Actions workflows locally with nektos/act before pushing, so CI failures are caught on the laptop and the PR can be squash-merged on the first remote run."
+---
+
+# gx-act — local GitHub Actions
+
+Use whenever a change touches code that would trigger CI on GitHub. Run the workflows locally with `act` first; only push the branch when the local run is green, then squash-merge the PR on GitHub.
+
+## When to invoke
+
+- Before `gx pr open` / `gx pr sync` / `gx branch finish --via-pr`.
+- Before re-pushing after a CI failure.
+- When iterating on `.github/workflows/*.yml` itself.
+
+## Install `act`
+
+`act` requires Docker (or Podman). Check the binary:
+
+```sh
+command -v act || echo "act not installed"
+```
+
+Install one way:
+
+```sh
+# Linux/macOS via the upstream installer
+curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b "$HOME/.local/bin"
+
+# macOS via Homebrew
+brew install act
+
+# Arch
+sudo pacman -S act
+
+# Or use the GitHub CLI extension
+gh extension install https://github.com/nektos/gh-act
+```
+
+Upstream: https://github.com/nektos/act
+
+## Quick commands
+
+```sh
+# List jobs the local runner would execute for the push event
+act -l
+
+# Run the default push workflows (what GitHub runs on a normal push)
+act push
+
+# Run a specific event
+act pull_request
+act workflow_dispatch -W .github/workflows/release.yml
+
+# Run a single job
+act -j test
+
+# Pin a runner image (medium is the act default; large matches real GH closer)
+act -P ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Pass secrets / env without committing them
+act -s GITHUB_TOKEN="$GITHUB_TOKEN" --env-file .env.act
+
+# Reuse containers between runs (faster iteration)
+act --reuse
+```
+
+## Workflow (local CI → squash-merge on GitHub)
+
+1. Implement the change in the agent worktree.
+2. `act -l` to confirm which jobs will fire for the event you care about.
+3. `act push` (or the specific event/job) until it is green locally.
+4. `gx branch finish --branch "<agent-branch>" --base main --via-pr --wait-for-merge --cleanup`.
+   - Or `gx pr open` then `gx pr sync --auto-merge --merge-strategy squash` for explicit PR control.
+5. On GitHub: squash-merge once the remote run mirrors the local one.
+
+## Notes
+
+- `act` does not reproduce GitHub-hosted services exactly (no real secrets, different runner image, no concurrency groups). Treat a green `act` run as a strong signal, not a proof — the remote run is still authoritative.
+- Keep `act` config in `.actrc` at the repo root so every agent uses the same runner image.
+- If a workflow uses `GITHUB_TOKEN` for API calls, pass a PAT via `-s GITHUB_TOKEN=...`; do not commit it.
+- Add `.actrc`, `.cache/act`, and any `act`-specific event payloads to `.gitignore` if they appear.

package/src/agents/cleanup-sessions.js

@@ -0,0 +1,126 @@
+const fs = require('node:fs');
+
+const {
+  listAgentSessions,
+  removeAgentSession,
+} = require('./sessions');
+const { branchExists: defaultBranchExists } = require('../git');
+const { TOOL_NAME } = require('../context');
+
+const DEFAULT_STALE_AGE_MINUTES = 24 * 60;
+const TERMINAL_STATUSES = new Set(['finished', 'pr-opened', 'failed']);
+
+function parseTimestamp(value) {
+  if (!value) return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function sessionAgeMinutes(session, nowMs) {
+  const timestamp = parseTimestamp(session.updatedAt) ?? parseTimestamp(session.createdAt);
+  if (timestamp === null) return null;
+  return Math.max(0, Math.floor((nowMs - timestamp) / 60000));
+}
+
+function evaluateSession(session, repoRoot, options) {
+  const reasons = [];
+  const worktreePath = session.worktreePath || '';
+  const branch = session.branch || '';
+
+  if (worktreePath && !options.existsSync(worktreePath)) {
+    reasons.push('missing-worktree');
+  }
+
+  if (branch && !options.branchExists(repoRoot, branch)) {
+    reasons.push('missing-branch');
+  }
+
+  const status = session.status || '';
+  const ageMinutes = sessionAgeMinutes(session, options.nowMs);
+  if (
+    TERMINAL_STATUSES.has(status)
+    && ageMinutes !== null
+    && ageMinutes >= options.staleAgeMinutes
+  ) {
+    reasons.push('terminal-status-old');
+  }
+
+  return {
+    ...session,
+    ageMinutes,
+    reasons,
+    stale: reasons.length > 0,
+  };
+}
+
+function cleanupAgentSessions(repoRoot, rawOptions = {}) {
+  const options = {
+    dryRun: Boolean(rawOptions.dryRun),
+    staleAgeMinutes: rawOptions.staleAgeMinutes ?? DEFAULT_STALE_AGE_MINUTES,
+    nowMs: rawOptions.nowMs ?? Date.now(),
+    existsSync: rawOptions.existsSync || fs.existsSync,
+    branchExists: rawOptions.branchExists || defaultBranchExists,
+  };
+
+  const sessions = listAgentSessions(repoRoot);
+  const candidates = sessions
+    .map((session) => evaluateSession(session, repoRoot, options))
+    .filter((session) => session.stale);
+
+  const removed = [];
+  if (!options.dryRun) {
+    for (const session of candidates) {
+      if (removeAgentSession(repoRoot, session.id)) {
+        removed.push(session.id);
+      }
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    repoRoot,
+    dryRun: options.dryRun,
+    staleAgeMinutes: options.staleAgeMinutes,
+    inspected: sessions.length,
+    candidates,
+    removed,
+  };
+}
+
+function formatSessionLine(session, verb) {
+  const reasonText = session.reasons.join(',');
+  return `- ${verb} ${session.id} status=${session.status || '-'} branch=${session.branch || '-'} ` +
+    `worktree=${session.worktreePath || '-'} reasons=${reasonText}`;
+}
+
+function renderCleanupSessionsResult(result, options = {}) {
+  if (options.json) return `${JSON.stringify(result, null, 2)}\n`;
+
+  const action = result.dryRun ? 'would remove' : 'removed';
+  const lines = [
+    `[${TOOL_NAME}] Agent session cleanup: ${action} ${result.dryRun ? result.candidates.length : result.removed.length} ` +
+      `of ${result.inspected} (${result.repoRoot})`,
+  ];
+
+  if (result.candidates.length === 0) {
+    lines.push('- no stale session metadata found');
+  } else {
+    for (const session of result.candidates) {
+      lines.push(formatSessionLine(session, action));
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function runCleanupSessionsCommand(repoRoot, options = {}) {
+  return renderCleanupSessionsResult(cleanupAgentSessions(repoRoot, options), options);
+}
+
+module.exports = {
+  DEFAULT_STALE_AGE_MINUTES,
+  TERMINAL_STATUSES,
+  cleanupAgentSessions,
+  renderCleanupSessionsResult,
+  runCleanupSessionsCommand,
+};

package/src/agents/finish.js

@@ -0,0 +1,172 @@
+const { TOOL_NAME } = require('../context');
+const finishCommands = require('../finish');
+const {
+  readAgentSession,
+  updateAgentSession,
+  listAgentSessions,
+} = require('./sessions');
+
+function resolveSessionByBranch(repoRoot, branch) {
+  const matches = listAgentSessions(repoRoot).filter((session) => session.branch === branch);
+  if (matches.length === 0) {
+    return null;
+  }
+  if (matches.length > 1) {
+    throw new Error(`Multiple agent sessions found for branch: ${branch}`);
+  }
+  return matches[0];
+}
+
+function resolveAgentSessionForFinish(repoRoot, options) {
+  if (options.sessionId) {
+    const session = readAgentSession(repoRoot, options.sessionId);
+    if (!session) {
+      throw new Error(`Agent session not found: ${options.sessionId}`);
+    }
+    return session;
+  }
+
+  if (options.branch) {
+    const session = resolveSessionByBranch(repoRoot, options.branch);
+    if (!session) {
+      throw new Error(`Agent session not found for branch: ${options.branch}`);
+    }
+    return session;
+  }
+
+  throw new Error('agents finish requires --session <id> or --branch <agent/...>');
+}
+
+function sessionStatusAfterFinish(finishArgs) {
+  const modeIndex = finishArgs.indexOf('--mode');
+  const directMode = finishArgs.includes('--direct-only') || finishArgs[modeIndex + 1] === 'direct';
+  return finishArgs.includes('--no-wait-for-merge') && !directMode ? 'pr-opened' : 'finished';
+}
+
+function cleanupResultAfterFinish(finishArgs, status) {
+  if (status === 'failed') return 'failed';
+  if (finishArgs.includes('--no-cleanup')) return 'skipped';
+  if (finishArgs.includes('--cleanup')) return status === 'finished' ? 'completed' : 'pending';
+  return 'unknown';
+}
+
+function firstMatch(text, patterns) {
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match && match[1]) return match[1].trim();
+  }
+  return '';
+}
+
+function finishOutputText(result, captured = {}) {
+  return [
+    captured.stdout,
+    captured.stderr,
+    result?.stdout,
+    result?.stderr,
+  ].map((value) => String(value || '')).join('\n');
+}
+
+function buildFinishEvidence(session, finishArgs, status, result, captured = {}) {
+  const outputText = finishOutputText(result, captured);
+  const prUrl = firstMatch(outputText, [
+    /\[agent-branch-finish\] (?:Merged PR|PR):\s+(https?:\/\/\S+)/,
+    /\b(https?:\/\/\S+\/pull\/\d+)\b/,
+  ]);
+  const mergeState = status === 'finished' ? 'MERGED' : status === 'pr-opened' ? 'OPEN' : status.toUpperCase();
+  return {
+    schemaVersion: 1,
+    sessionId: session.id || '',
+    branch: session.branch || '',
+    prUrl,
+    mergeState,
+    cleanupResult: cleanupResultAfterFinish(finishArgs, status),
+    status,
+  };
+}
+
+function captureProcessOutput(fn) {
+  let stdout = '';
+  let stderr = '';
+  const originalStdoutWrite = process.stdout.write;
+  const originalStderrWrite = process.stderr.write;
+  process.stdout.write = function captureStdout(chunk, encoding, callback) {
+    stdout += Buffer.isBuffer(chunk) ? chunk.toString(encoding || 'utf8') : String(chunk || '');
+    if (typeof encoding === 'function') encoding();
+    if (typeof callback === 'function') callback();
+    return true;
+  };
+  process.stderr.write = function captureStderr(chunk, encoding, callback) {
+    stderr += Buffer.isBuffer(chunk) ? chunk.toString(encoding || 'utf8') : String(chunk || '');
+    if (typeof encoding === 'function') encoding();
+    if (typeof callback === 'function') callback();
+    return true;
+  };
+  try {
+    return { result: fn(), captured: { stdout, stderr } };
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+}
+
+function finishAgentSession(repoRoot, options, deps = {}) {
+  const finishRunner = deps.finishRunner || finishCommands.finish;
+  const output = deps.output || process.stdout;
+  const session = resolveAgentSessionForFinish(repoRoot, options);
+  const jsonMode = Boolean(options.json);
+
+  if (!session.branch) {
+    throw new Error(`Agent session '${session.id}' has no branch metadata.`);
+  }
+
+  updateAgentSession(repoRoot, session.id, { status: 'finishing' });
+
+  const finishArgs = [
+    '--target',
+    repoRoot,
+    '--branch',
+    session.branch,
+    ...options.finishArgs,
+  ];
+
+  if (!jsonMode) {
+    output.write(`[${TOOL_NAME}] Agent session: ${session.id}\n`);
+    output.write(`[${TOOL_NAME}] Branch: ${session.branch}\n`);
+    output.write(`[${TOOL_NAME}] Worktree: ${session.worktreePath || '(unknown)'}\n`);
+  }
+
+  try {
+    const runnerResult = jsonMode
+      ? captureProcessOutput(() => finishRunner(finishArgs))
+      : { result: finishRunner(finishArgs), captured: {} };
+    const result = runnerResult.result;
+    const status = sessionStatusAfterFinish(finishArgs);
+    const evidence = buildFinishEvidence(session, finishArgs, status, result, runnerResult.captured);
+    updateAgentSession(repoRoot, session.id, {
+      status,
+      pr: { url: evidence.prUrl, state: evidence.mergeState },
+      finishEvidence: evidence,
+    });
+    if (!jsonMode) {
+      output.write(`[${TOOL_NAME}] Finish result: ${status}\n`);
+    }
+    return { session, status, result, finishArgs, evidence };
+  } catch (error) {
+    const evidence = buildFinishEvidence(session, finishArgs, 'failed', null);
+    updateAgentSession(repoRoot, session.id, {
+      status: 'failed',
+      finishEvidence: evidence,
+    });
+    if (!jsonMode) {
+      output.write(`[${TOOL_NAME}] Finish result: failed\n`);
+    }
+    throw error;
+  }
+}
+
+module.exports = {
+  buildFinishEvidence,
+  finishAgentSession,
+  resolveAgentSessionForFinish,
+};