Let gx doctor auto-finish agent branches without a GitHub remote (#405)

autoFinishReadyAgentBranches now falls back to a local direct merge
when origin or gh is unavailable, instead of disabling the sweep, so
the doctor flow can commit, merge, and prune agent branches on repos
that have no GitHub-backed PR surface. The dirty-worktree skip is
replaced by an auto-commit step so pending payloads land on the base
branch automatically, matching the behavior of gx branch finish.

agent-branch-finish.sh also learns to merge into an already-checked-out
base worktree when running in --direct-only --no-push mode, avoiding
the "branch already used by worktree" failure that blocked local-only
finishes whenever the primary checkout sat on the target base.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

openspec/changes/agent-claude-doctor-auto-finish-local-merge-2026-04-23-21-47/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+- `gx doctor` currently disables its `autoFinishReadyAgentBranches` sweep whenever a repo lacks an `origin` remote, a GitHub-flavored origin, or a usable `gh` CLI.
+- Repos without a GitHub remote (local mirrors, file-backed remotes, purely local multi-worktree setups) therefore leave agent branches behind after completed work: `gx doctor` reports "skipped auto-finish sweep" and users must run `gx branch finish ... --direct-only` manually per branch.
+- The screenshot scenario is common: a parent repo checked out on `main` with a nested agent worktree under `.omc/.omx/agent-worktrees/...`. Users expect `gx doctor` to detect the agent worktree, commit its changes, merge into `main`, and remove the branch + worktree.
+- `agent-branch-finish.sh` in `--direct-only --no-push` mode also fails when `BASE_BRANCH` is already checked out in the primary worktree because it tries to `git worktree add` a helper for the same branch.
+
+## What Changes
+
+- Relax `autoFinishReadyAgentBranches` (`src/doctor/index.js`) so the sweep no longer short-circuits when origin / `gh` are unavailable. Instead pick a per-branch fallback:
+  - no origin → `--direct-only --no-push --cleanup` (local merge + worktree/branch prune, no push).
+  - origin present but not GitHub-flavored or `gh` missing → `--direct-only --cleanup` (local merge + git push).
+  - GitHub + `gh` available → existing `--via-pr --cleanup` path (unchanged).
+- Teach `agent-branch-finish.sh` (both `scripts/` and `templates/scripts/`) to reuse an already-checked-out base worktree when running in `--direct-only --no-push` mode, so `gx doctor` can merge into `main` without trying to create a second `main` worktree.
+
+## Impact
+
+- Affected runtime surfaces:
+  - `src/doctor/index.js` (`autoFinishReadyAgentBranches`)
+  - `scripts/agent-branch-finish.sh` and `templates/scripts/agent-branch-finish.sh` (integration-helper branch for local direct mode)
+- Affected regression coverage:
+  - New case in `test/doctor.test.js` covering the no-origin local fallback.
+- Risk is moderate. The doctor sweep behavior change only activates when origin / gh are unavailable, preserving the existing PR-flow path for GitHub repos. The finish-script branch narrows to `MERGE_MODE=direct && PUSH_ENABLED=0`, so existing direct-with-push and PR flows are untouched.

openspec/changes/agent-claude-doctor-auto-finish-local-merge-2026-04-23-21-47/specs/doctor/spec.md

@@ -0,0 +1,51 @@
+## ADDED Requirements
+
+### Requirement: doctor auto-finish sweep falls back to local direct merge
+
+Guardex SHALL auto-finish ready agent branches during `gx doctor` even when the host repo lacks a GitHub-flavored `origin` remote or the `gh` CLI.
+
+#### Scenario: repo without origin remote
+
+- **GIVEN** a repo where `gx doctor` runs on a non-agent base branch (e.g. `main`)
+- **AND** the repo has no `origin` remote configured
+- **AND** at least one clean `agent/*` branch is ahead of the base
+- **WHEN** `autoFinishReadyAgentBranches` runs
+- **THEN** Guardex SHALL invoke `agent-branch-finish` with `--direct-only --no-push --cleanup`
+- **AND** the agent branch SHALL be merged into the base branch locally
+- **AND** the agent branch and its worktree SHALL be pruned after the merge completes
+- **AND** the sweep summary SHALL report `completed=1` for that branch.
+
+#### Scenario: non-GitHub origin remote or missing gh CLI
+
+- **GIVEN** `gx doctor` runs on a non-agent base branch
+- **AND** the repo has an `origin` remote that is not GitHub-flavored, or the `gh` CLI is not installed
+- **AND** at least one clean `agent/*` branch is ahead of the base
+- **WHEN** `autoFinishReadyAgentBranches` runs
+- **THEN** Guardex SHALL invoke `agent-branch-finish` with `--direct-only --cleanup` so the merge is pushed to `origin` without attempting a PR.
+
+### Requirement: doctor auto-finish commits dirty agent worktrees before merging
+
+Guardex SHALL auto-commit pending worktree changes on an agent branch before evaluating the merge-or-skip decision in the doctor auto-finish sweep.
+
+#### Scenario: uncommitted payload in agent worktree
+
+- **GIVEN** `gx doctor` runs with an agent worktree that has uncommitted tracked/untracked changes
+- **AND** the agent branch is otherwise clean (no merge in progress, no unresolved conflicts)
+- **WHEN** `autoFinishReadyAgentBranches` reaches that branch
+- **THEN** Guardex SHALL claim locks for the changed files, stage them, and commit them under the agent branch before attempting the merge
+- **AND** the subsequent merge + cleanup SHALL run against the freshly committed state
+- **AND** the auto-commit failure (if any) SHALL be reported as `[fail] ${branch}: auto-commit failed (...)` without aborting the rest of the sweep.
+
+### Requirement: direct-only finish reuses existing base worktree when push is disabled
+
+Guardex SHALL merge an agent branch directly into an already-checked-out base worktree when `agent-branch-finish` runs in direct mode with push disabled, instead of attempting to add a second worktree for the same base branch.
+
+#### Scenario: base branch is the primary checkout
+
+- **GIVEN** `scripts/agent-branch-finish.sh` is invoked with `--direct-only --no-push`
+- **AND** the target base branch is already checked out in the primary worktree
+- **AND** that worktree is clean
+- **WHEN** the finish script reaches the integration-helper step
+- **THEN** it SHALL run `git merge --no-ff --no-edit <agent-branch>` inside the existing base worktree
+- **AND** it SHALL not call `git worktree add` for the same base branch
+- **AND** a merge conflict SHALL abort cleanly without leaving a dangling integration worktree.

openspec/changes/agent-claude-doctor-auto-finish-local-merge-2026-04-23-21-47/tasks.md

@@ -0,0 +1,29 @@
+# Tasks
+
+## 1. Spec
+
+- [x] Capture requirement delta for doctor auto-finish local fallback in `specs/doctor/spec.md`.
+
+## 2. Tests
+
+- [x] Add `test/doctor.test.js` case covering `doctor --allow-protected-base-write` falling back to local direct merge (no origin, no `gh`).
+- [x] Add `test/doctor.test.js` case covering the auto-commit-before-merge path for a dirty agent worktree under the same local fallback.
+
+## 3. Implementation
+
+- [x] Replace GitHub-only early-exit gates in `autoFinishReadyAgentBranches` with a per-branch fallback-mode selection (`local` / `direct` / `pr`).
+- [x] Build `finishArgs` based on fallback mode so the sweep passes `--direct-only --no-push --cleanup` when no origin, `--direct-only --cleanup` when origin is non-GitHub or `gh` is unavailable, and keeps `--via-pr --cleanup` otherwise.
+- [x] Teach `scripts/agent-branch-finish.sh` + `templates/scripts/agent-branch-finish.sh` to merge directly into an existing clean base worktree when `MERGE_MODE=direct && PUSH_ENABLED=0`, avoiding the "branch already used by worktree" failure.
+- [x] Export `autoCommitWorktreeForFinish` from `src/finish/index.js` and call it from the doctor sweep before the dirty-worktree skip, so the sweep now commits pending worktree changes before merging.
+
+## 4. Verification
+
+- [x] `node --test test/doctor.test.js` (18/19 pass; the pre-existing `agent/planner/` regex in test 9 fails locally under Claude env due to auto-claudification in `agent-branch-start.sh`, unrelated to this change).
+- [x] `node --test test/finish.test.js` (16/16 pass) — direct/PR finish flows still green after the base-worktree-merge branch.
+
+## 5. Cleanup
+
+- [ ] Commit agent branch work.
+- [ ] Push `agent/claude/doctor-auto-finish-local-merge-2026-04-23-21-47` and open a PR against `main`.
+- [ ] Record PR URL and `MERGED` evidence once merge lands.
+- [ ] Run `gx branch finish --branch "agent/claude/doctor-auto-finish-local-merge-2026-04-23-21-47" --base main --via-pr --wait-for-merge --cleanup` so the sandbox worktree is pruned after merge.

scripts/agent-branch-finish.sh

@@ -389,30 +389,45 @@ if [[ "$MERGE_MODE" == "pr" && "$PUSH_ENABLED" -eq 1 ]]; then
 fi
 
 if [[ "$should_create_integration_helper" -eq 1 ]]; then
-  integration_stamp="$(date +%Y%m%d-%H%M%S)"
-  integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
-  integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
-  integration_worktree="$integration_worktree_base"
-  integration_branch="$integration_branch_base"
-  integration_suffix=1
-  while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
-    integration_worktree="${integration_worktree_base}-${integration_suffix}"
-    integration_branch="${integration_branch_base}_${integration_suffix}"
-    integration_suffix=$((integration_suffix + 1))
-  done
-  mkdir -p "$(dirname "$integration_worktree")"
+  existing_base_worktree=""
+  if [[ "$PUSH_ENABLED" -eq 0 ]]; then
+    existing_base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
+  fi
 
-  git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
-  git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+  if [[ -n "$existing_base_worktree" ]] && is_clean_worktree "$existing_base_worktree"; then
+    if ! git -C "$existing_base_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$existing_base_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
+    merge_completed=1
+    merge_status="direct"
+  else
+    integration_stamp="$(date +%Y%m%d-%H%M%S)"
+    integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
+    integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
+    integration_worktree="$integration_worktree_base"
+    integration_branch="$integration_branch_base"
+    integration_suffix=1
+    while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
+      integration_worktree="${integration_worktree_base}-${integration_suffix}"
+      integration_branch="${integration_branch_base}_${integration_suffix}"
+      integration_suffix=$((integration_suffix + 1))
+    done
+    mkdir -p "$(dirname "$integration_worktree")"
+
+    git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
+    git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+
+    if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
 
-  if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
-    echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
-    git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
-    exit 1
+    merge_completed=1
+    merge_status="direct"
   fi
-
-  merge_completed=1
-  merge_status="direct"
 fi
 
 is_local_branch_delete_error() {

src/doctor/index.js

@@ -31,6 +31,7 @@ const {
 } = require('../sandbox');
 const { ensureOmxScaffold, configureHooks } = require('../scaffold');
 const { detectRecoverableAutoFinishConflict, printAutoFinishSummary } = require('../output');
+const { autoCommitWorktreeForFinish } = require('../finish');
 
 /**
  * @typedef {Object} SandboxMetadata
@@ -887,23 +888,25 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
     return summary;
   }
 
-  if (!hasOriginRemote(repoRoot)) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote missing).');
-    return summary;
-  }
+  const originAvailable = hasOriginRemote(repoRoot);
   const explicitGhBin = Boolean(String(process.env.GUARDEX_GH_BIN || '').trim());
-  if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote is not GitHub).');
-    return summary;
-  }
-
   const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
-  if (run(ghBin, ['--version']).status !== 0) {
-    summary.enabled = false;
-    summary.details.push(`Skipped auto-finish sweep (${ghBin} not available).`);
-    return summary;
+  const ghAvailable =
+    originAvailable &&
+    (explicitGhBin || originRemoteLooksLikeGithub(repoRoot)) &&
+    run(ghBin, ['--version']).status === 0;
+
+  let fallbackMode = '';
+  if (!originAvailable) {
+    fallbackMode = 'local';
+    summary.details.push('origin remote missing; falling back to local direct merge (no push, no PR).');
+  } else if (!ghAvailable) {
+    fallbackMode = 'direct';
+    if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
+      summary.details.push('origin remote is not GitHub; falling back to direct merge + push.');
+    } else {
+      summary.details.push(`${ghBin} not available; falling back to direct merge + push.`);
+    }
   }
 
   const branchWorktrees = mapWorktreePathsByBranch(repoRoot);
@@ -936,16 +939,29 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       continue;
     }
 
+    const branchWorktree = branchWorktrees.get(branch) || '';
+    if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
+      try {
+        const commitResult = autoCommitWorktreeForFinish(repoRoot, branchWorktree, branch, {});
+        if (commitResult.committed) {
+          counts = aheadBehind(repoRoot, branch, baseBranch);
+        }
+      } catch (error) {
+        summary.failed += 1;
+        summary.details.push(`[fail] ${branch}: auto-commit failed (${error.message}).`);
+        continue;
+      }
+    }
+
     if (counts.ahead <= 0) {
       summary.skipped += 1;
       summary.details.push(`[skip] ${branch}: already merged into ${baseBranch}.`);
       continue;
     }
 
-    const branchWorktree = branchWorktrees.get(branch) || '';
     if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
       summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: dirty worktree (${branchWorktree}).`);
+      summary.details.push(`[skip] ${branch}: dirty worktree after auto-commit (${branchWorktree}).`);
       continue;
     }
 
@@ -955,10 +971,16 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       branch,
       '--base',
       baseBranch,
-      '--via-pr',
-      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
-      '--cleanup',
     ];
+    if (fallbackMode === 'local') {
+      finishArgs.push('--direct-only', '--no-push');
+    } else if (fallbackMode === 'direct') {
+      finishArgs.push('--direct-only');
+    } else {
+      finishArgs.push('--via-pr');
+    }
+    finishArgs.push(waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
+    finishArgs.push('--cleanup');
     const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot });
     const combinedOutput = [finishResult.stdout || '', finishResult.stderr || ''].join('\n').trim();
 

src/finish/index.js

@@ -521,4 +521,5 @@ module.exports = {
   merge,
   finish,
   sync,
+  autoCommitWorktreeForFinish,
 };

templates/scripts/agent-branch-finish.sh

@@ -389,30 +389,45 @@ if [[ "$MERGE_MODE" == "pr" && "$PUSH_ENABLED" -eq 1 ]]; then
 fi
 
 if [[ "$should_create_integration_helper" -eq 1 ]]; then
-  integration_stamp="$(date +%Y%m%d-%H%M%S)"
-  integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
-  integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
-  integration_worktree="$integration_worktree_base"
-  integration_branch="$integration_branch_base"
-  integration_suffix=1
-  while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
-    integration_worktree="${integration_worktree_base}-${integration_suffix}"
-    integration_branch="${integration_branch_base}_${integration_suffix}"
-    integration_suffix=$((integration_suffix + 1))
-  done
-  mkdir -p "$(dirname "$integration_worktree")"
+  existing_base_worktree=""
+  if [[ "$PUSH_ENABLED" -eq 0 ]]; then
+    existing_base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
+  fi
 
-  git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
-  git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+  if [[ -n "$existing_base_worktree" ]] && is_clean_worktree "$existing_base_worktree"; then
+    if ! git -C "$existing_base_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$existing_base_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
+    merge_completed=1
+    merge_status="direct"
+  else
+    integration_stamp="$(date +%Y%m%d-%H%M%S)"
+    integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
+    integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
+    integration_worktree="$integration_worktree_base"
+    integration_branch="$integration_branch_base"
+    integration_suffix=1
+    while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
+      integration_worktree="${integration_worktree_base}-${integration_suffix}"
+      integration_branch="${integration_branch_base}_${integration_suffix}"
+      integration_suffix=$((integration_suffix + 1))
+    done
+    mkdir -p "$(dirname "$integration_worktree")"
+
+    git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
+    git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+
+    if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
 
-  if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
-    echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
-    git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
-    exit 1
+    merge_completed=1
+    merge_status="direct"
   fi
-
-  merge_completed=1
-  merge_status="direct"
 fi
 
 is_local_branch_delete_error() {