[xxwtiancai]

HUMAN:

Problem: Launching a child workspace on an unborn HEAD fails with an unhandled HTTP 500 error.

Fix: Resolves the default base ref first, falling back to shared workspace on unborn HEADs while keeping explicit ref errors strict.

Verification: Verified against live server regression: child launch succeeds with HTTP 201 and isolation: "shared" without fake commits.

---

AGENT:

Why

A normal parent conversation in an empty workspace initializes Git without making a commit. Creating a child with the default worktree isolation then failed with HTTP 500: the worktree planner accepted the repository, but git worktree add ... HEAD cannot branch from an unborn HEAD. Explicit isolation: shared avoided the failure, so only the default path was broken. Fixes #6186.

Summary

• _plan_conversation_worktree now resolves the worktree start point at plan time and, for the default base="default_branch", verifies it resolves to a commit (git rev-parse --verify --quiet <ref>^{commit}). Exit code 1 — the unborn HEAD of a repository initialized without a commit — produces no plan, so conversation creation uses the existing shared-workspace fallback and the response reports isolation: "shared". Any other git failure still propagates, so other Git errors are not silently treated as an empty repository.
• Explicit base="head" / base="ref" keep their current error semantics; a missing explicitly requested ref remains an error.
• The plan now carries the selected ref (not a re-resolution at creation time, and not a resolved hash), so git worktree add preserves remote branch tracking configuration on the new branch.
• Updated the isolation field descriptions in StartChildConversationRequest and the start_child_conversation tool to say "git repository with a usable base commit". The TypeScript client's generated schema intentionally stays untouched here — it is generated from the pinned released Agent Server image and is refreshed by the post-release version-bump workflow.

Issue Number

Fixes #6186

How to Test

uv run --frozen pytest \
  tests/cross/test_remote_conversation_live_server.py::test_child_launch_in_fresh_workspace_preserves_unborn_repository \
  "tests/agent_server/test_conversation_service.py::TestConversationServiceStartConversation" \
  tests/agent_server/test_parent_child_conversations.py \
  tests/tools/child_conversation -q

New coverage (the live-server test and the unborn-HEAD planner test both fail with the original GitCommandError: git worktree add ... HEAD / HTTP 500 before the change and pass after):

• test_child_launch_in_fresh_workspace_preserves_unborn_repository (real HTTP server): fresh parent → .git exists with unborn HEAD → default child launch returns 201 with isolation: "shared" and the parent link; no initial commit is invented and the pre-existing file plus unborn repository survive child launch and cleanup.
• Planner unit tests: unborn HEAD with no remote/main/master → no plan; a usable remote default branch on an unborn local repo → plan with start_point == "origin/<default>" (worktree isolation retained); explicit base="head" on an unborn repo → plan still produced and _create_conversation_worktree still raises (current semantics preserved).

Full files pass after the change: tests/agent_server/test_conversation_service.py (141), tests/cross/test_remote_conversation_live_server.py (34 passed, 1 skipped), tests/agent_server/test_parent_child_conversations.py + tests/tools/child_conversation (31). Pre-commit (ruff, pycodestyle, pyright, import rules) passes on all changed files.

Video/Screenshots

Non-visual bug; reproduction notes instead of media:

• Before the change, the live-server test fails with the issue's original symptom: POST /api/conversations/{id}/children → HTTP 500 from git worktree add -b openhands/<child-id> ... HEAD (fatal: invalid reference: HEAD).
• After the change, the same workflow returns 201 with isolation: "shared".

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore