cleveragents/cleveragents-core

Fork 3

[BUG] agents plan execute fails with fatal: ambiguous argument 'HEAD' when resource points to a commitless git repository #9190

New issue

Open

opened 2026-04-14 09:50:02 +00:00 by hurui200320 · 2 comments

hurui200320 commented

2026-04-14 09:50:02 +00:00

Member

Metadata

Branch: fix/plan-execute-commitless-repo-error
Commit Message: fix(sandbox): detect commitless git repository and surface actionable error in GitWorktreeSandbox
Milestone: None (backlog)
Parent Epic: TBD — requires manual linking

Description

Background

When agents plan execute <PLAN_ID> is run and the linked project resource
points to a git repository that was freshly git init-ed with no commits,
the command fails with a cryptic, non-actionable error. The failure occurs
inside GitWorktreeSandbox.create() because git worktree add requires at
least one commit (a valid HEAD reference) to create a worktree. An empty
repository has no HEAD, so worktree creation fails entirely.

The spec describes git-checkout as a "local git checkout (cloned
repository or worktree)" — a freshly git init-ed repository with no
commits is arguably not a valid checkout. The current code silently accepts
the empty repo at resource add time but fails cryptically later during
plan execute.

Current Behavior

Running agents plan execute <PLAN_ID> where the linked resource points to
a commitless repository exits with code 1 and prints:

Unexpected error: Failed to create git worktree for resource <ULID>:
fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree.

Reproduction steps:

mkdir -p /workspace/rune && git -C /workspace/rune init
agents resource add git-checkout local/rune-project --path /workspace/rune → succeeds (exit 0)
agents project create --resource local/rune-project local/rune-encoder
agents action create --config /workspace/build-rune-encoder.yaml
agents plan use local/build-rune-encoder local/rune-encoder --automation-profile trusted
agents plan execute <PLAN_ID> → fails with fatal: ambiguous argument 'HEAD'

Workaround: Create an initial commit before running plan execute:

cd /workspace/rune
git config user.email "test@example.com" && git config user.name "Test"
touch .gitkeep && git add .gitkeep && git commit -m "Initial commit"

Expected Behavior

One of the following (implementer's choice, guided by spec alignment):

(a) Validate at execution time — GitWorktreeSandbox.create() detects
the empty repository condition before calling git worktree add and raises
a clear, actionable error:

Resource '/workspace/rune' has no commits. Create an initial commit before running plan execute.

(b) Validate at registration time — agents resource add git-checkout
checks that the repository has at least one commit and rejects empty repos
with a clear error at registration, preventing the resource from being
created in an invalid state.

Option (b) is preferred if it aligns with the spec's definition of
git-checkout as a "cloned repository or worktree" (implying a valid
HEAD must exist).

Acceptance Criteria

Running agents plan execute against a commitless repository produces
a clear, human-readable error message that names the resource path and
instructs the user to create an initial commit — not a raw git error.
The error is surfaced as a typed exception (not a bare Exception) and
logged at the appropriate level.
If validation is moved to registration time (resource add), the
command exits non-zero with a clear message when the path has no commits.
The workaround (creating an initial commit) continues to result in
successful plan execute execution.
No regression on existing GitWorktreeSandbox behaviour for
repositories with commits.

Supporting Information

Related (different bugs, not duplicates):
- #7737 — worktree leaked when create() fails after mkdtemp but before
  git worktree add (resource leak)
- #7507 — TOCTOU race in GitWorktreeSandbox.create()
- #6644 — sandbox created before read-only guard

Subtasks

Identify the correct fix location: GitWorktreeSandbox.create() (execution-time
validation) or resource add git-checkout handler (registration-time validation)
Implement the check: detect zero commits (e.g. git rev-parse HEAD fails or
git log --oneline -1 returns empty) and raise a typed, descriptive exception
Ensure the error message names the resource path and provides actionable guidance
Tests (Behave): add BDD scenario covering plan execute against a commitless
repository — assert the correct error message is produced
Tests (Behave): add BDD scenario (or extend existing) for resource add git-checkout
if validation is moved to registration time
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message
matches the Commit Message in Metadata exactly, followed by a blank line,
then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in
Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and
merged before this issue is marked done.
All nox default sessions pass.
Coverage >= 97%.

## Metadata - **Branch**: `fix/plan-execute-commitless-repo-error` - **Commit Message**: `fix(sandbox): detect commitless git repository and surface actionable error in GitWorktreeSandbox` - **Milestone**: None (backlog) - **Parent Epic**: TBD — requires manual linking ## Description ### Background When `agents plan execute <PLAN_ID>` is run and the linked project resource points to a git repository that was freshly `git init`-ed with no commits, the command fails with a cryptic, non-actionable error. The failure occurs inside `GitWorktreeSandbox.create()` because `git worktree add` requires at least one commit (a valid `HEAD` reference) to create a worktree. An empty repository has no `HEAD`, so worktree creation fails entirely. The spec describes `git-checkout` as a *"local git checkout (cloned repository or worktree)"* — a freshly `git init`-ed repository with no commits is arguably not a valid checkout. The current code silently accepts the empty repo at `resource add` time but fails cryptically later during `plan execute`. ### Current Behavior Running `agents plan execute <PLAN_ID>` where the linked resource points to a commitless repository exits with code 1 and prints: ``` Unexpected error: Failed to create git worktree for resource <ULID>: fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree. ``` **Reproduction steps:** 1. `mkdir -p /workspace/rune && git -C /workspace/rune init` 2. `agents resource add git-checkout local/rune-project --path /workspace/rune` → succeeds (exit 0) 3. `agents project create --resource local/rune-project local/rune-encoder` 4. `agents action create --config /workspace/build-rune-encoder.yaml` 5. `agents plan use local/build-rune-encoder local/rune-encoder --automation-profile trusted` 6. `agents plan execute <PLAN_ID>` → **fails** with `fatal: ambiguous argument 'HEAD'` **Workaround:** Create an initial commit before running `plan execute`: ```bash cd /workspace/rune git config user.email "test@example.com" && git config user.name "Test" touch .gitkeep && git add .gitkeep && git commit -m "Initial commit" ``` ### Expected Behavior One of the following (implementer's choice, guided by spec alignment): **(a) Validate at execution time** — `GitWorktreeSandbox.create()` detects the empty repository condition before calling `git worktree add` and raises a clear, actionable error: > `Resource '/workspace/rune' has no commits. Create an initial commit before running plan execute.` **(b) Validate at registration time** — `agents resource add git-checkout` checks that the repository has at least one commit and rejects empty repos with a clear error at registration, preventing the resource from being created in an invalid state. Option (b) is preferred if it aligns with the spec's definition of `git-checkout` as a *"cloned repository or worktree"* (implying a valid HEAD must exist). ### Acceptance Criteria - [ ] Running `agents plan execute` against a commitless repository produces a clear, human-readable error message that names the resource path and instructs the user to create an initial commit — not a raw `git` error. - [ ] The error is surfaced as a typed exception (not a bare `Exception`) and logged at the appropriate level. - [ ] If validation is moved to registration time (`resource add`), the command exits non-zero with a clear message when the path has no commits. - [ ] The workaround (creating an initial commit) continues to result in successful `plan execute` execution. - [ ] No regression on existing `GitWorktreeSandbox` behaviour for repositories with commits. ### Supporting Information - Related (different bugs, not duplicates): - #7737 — worktree leaked when `create()` fails after `mkdtemp` but before `git worktree add` (resource leak) - #7507 — TOCTOU race in `GitWorktreeSandbox.create()` - #6644 — sandbox created before read-only guard ## Subtasks - [ ] Identify the correct fix location: `GitWorktreeSandbox.create()` (execution-time validation) or `resource add git-checkout` handler (registration-time validation) - [ ] Implement the check: detect zero commits (e.g. `git rev-parse HEAD` fails or `git log --oneline -1` returns empty) and raise a typed, descriptive exception - [ ] Ensure the error message names the resource path and provides actionable guidance - [ ] Tests (Behave): add BDD scenario covering `plan execute` against a commitless repository — assert the correct error message is produced - [ ] Tests (Behave): add BDD scenario (or extend existing) for `resource add git-checkout` if validation is moved to registration time - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All `nox` default sessions pass. - Coverage >= 97%.

hurui200320 added the

labels

2026-04-14 09:50:29 +00:00

HAL9000 commented

2026-04-14 10:27:28 +00:00

Owner

@hurui200320 Thank you for this bug report.

Acknowledgment — Issue #9190

This issue has been received. The reported behavior — agents plan execute failing with fatal: ambiguous argument 'HEAD' when the resource points to a git repository with no commits — has been logged.

Current status: State/Unverified — this will be reviewed by the project owner for verification and prioritization.

Next steps: The project owner will verify this issue. Given the Priority/Medium label, this will be addressed after higher-priority items.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison-pool-supervisor
Worker: [AUTO-HUMAN-7]

@hurui200320 Thank you for this bug report. **Acknowledgment — Issue #9190** This issue has been received. The reported behavior — `agents plan execute` failing with `fatal: ambiguous argument 'HEAD'` when the resource points to a git repository with no commits — has been logged. **Current status**: State/Unverified — this will be reviewed by the project owner for verification and prioritization. **Next steps**: The project owner will verify this issue. Given the Priority/Medium label, this will be addressed after higher-priority items. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison-pool-supervisor Worker: [AUTO-HUMAN-7]

HAL9000 added

and removed

labels

2026-04-14 12:49:06 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 12:49:06 +00:00

HAL9000 commented

2026-04-14 12:49:06 +00:00

Owner

✅ Triage: Verified [AUTO-OWNR-1]

This is a valid, well-documented bug with clear reproduction steps, expected behavior, and acceptance criteria. The issue correctly identifies that GitWorktreeSandbox.create() fails with a cryptic error when the linked resource points to a commitless git repository. The preferred fix (option b — validate at registration time) aligns with the spec's definition of git-checkout as a cloned repository or worktree implying a valid HEAD.

Assigning to v3.2.0 as this is sandbox/worktree infrastructure work that belongs with M3's plan execution improvements. Priority remains Medium — this is a real UX issue but has a clear workaround (create an initial commit).

MoSCoW: Should Have — improves user experience significantly but the workaround is simple and the release is not blocked without it.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage: Verified** [AUTO-OWNR-1] This is a valid, well-documented bug with clear reproduction steps, expected behavior, and acceptance criteria. The issue correctly identifies that `GitWorktreeSandbox.create()` fails with a cryptic error when the linked resource points to a commitless git repository. The preferred fix (option b — validate at registration time) aligns with the spec's definition of `git-checkout` as a cloned repository or worktree implying a valid HEAD. Assigning to **v3.2.0** as this is sandbox/worktree infrastructure work that belongs with M3's plan execution improvements. Priority remains **Medium** — this is a real UX issue but has a clear workaround (create an initial commit). MoSCoW: **Should Have** — improves user experience significantly but the workaround is simple and the release is not blocked without it. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 12:51:00 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #9249

HAL9000 referenced this issue

2026-04-14 12:56:58 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 1) #9249

HAL9000 referenced this issue

2026-04-14 14:44:35 +00:00

[AUTO-IMP-POOL] Status: Implementation Pool Supervisor (Cycle 5) #9318