mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
fe6c8e387f
* docs: sync prompts/RAG/CLAUDE + bump to 0.11.0 for the run-hardening wave
Documentation + version sweep for everything shipped since 889f3689 (the 0.11.0
wave: MegaTask + #249-#253 run-hardening). Closes the doc drift behind the live
incidents — agents had no branch-behind-master guidance, so a Main PM invented
a bogus "rebase subtask".
Agent guidance (the headline gap):
- main_pm / cell_pm / developer prompts: a task branch is made current at CLAIM;
there is NO rebase/pull/merge verb at the agent layer. Never create a "rebase
subtask" or improvise git surgery; escalate a behind-base branch
(developer: i_am_blocked; PM: escalate_up). "A rebase subtask is always a mistake."
- board prompt: Board has no unblock verb; a blocked task assigned to it is a
mis-assignment -> escalate_to_ceo immediately, never sit on it (respawn loop).
- developer prompt: the shared clone is git-reset on a fresh claim; push/open_pr
target the task branch by name regardless of the current checkout.
- RAG (git-errors, blocked-tools, pr-creation): branch-behind-base, "src refspec
does not match any", and non-fast-forward recovery -> escalate, don't improvise.
CLAUDE.md: 9 shipped behaviors synced (session-limit parking, one-active-work-
session + migration 047, push/PR-by-name + origin ref recovery, fresh-claim
workspace reset, Board never owns a coordination root, verb-runner per-action
INVALID_STATE re-check, note fire-and-forget RAG indexing,
ROBOCO_GATEWAY_HEALTH_ENABLED flag, learnings not broadcast to human roles).
Version 0.10.0 -> 0.11.0: pyproject, roboco/__init__, config.app_version +
agent-image-tag example, panel/package.json, uv.lock, README/deploy examples;
CHANGELOG [Unreleased] cut to [0.11.0] - 2026-06-24.
* docs(site): document session-limit parking + the branch-behind-base operator flow
User-facing docs site updates for the 0.11.0 wave (the run-hardening behaviors
that are operator-visible):
- models/resilience.md: the Claude session-limit (5-hour usage window) parks
and auto-revives like an overload, not just per-request 429s / 5xx overloads.
- troubleshooting/common-issues.md: same session-limit note on the parked-
provider entries; plus a new "task stuck on a branch behind its base" entry —
agents have no rebase verb so they escalate it; the operator rebases from the
panel Git tab (auto-rebase-at-spawn is the roadmap cure).
---------
Co-authored-by: Renn F <rennf93@users.noreply.github.com>
114 lines
5.0 KiB
Markdown
114 lines
5.0 KiB
Markdown
# Git Error Troubleshooting
|
|
|
|
## Missing Git Token
|
|
|
|
**Error:** `Project requires a git token for HTTPS repositories` (also surfaces as `WorkspaceError` during clone)
|
|
|
|
**Cause:** No encrypted GitHub PAT on `projects.git_token_encrypted` for this project.
|
|
|
|
**Fix:**
|
|
|
|
1. Open the project's settings tab in the panel
|
|
2. Paste a GitHub Personal Access Token with `repo` scope
|
|
3. Save — the panel encrypts and stores it; the API never returns the plaintext
|
|
|
|
Notes:
|
|
|
|
- Each project has its own token (no global fallback)
|
|
- Tokens are encrypted at rest with Fernet
|
|
- The token is injected only at the MCP layer (commit / clone / PR ops); `.git/config` is scrubbed post-clone so a leaked PAT from there is not a recovery path
|
|
|
|
## Workspace Not Found
|
|
|
|
**Error:** `Workspace does not exist`
|
|
|
|
**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE` is `false` and no manual clone has run).
|
|
|
|
**Fix:**
|
|
|
|
- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb that touches the workspace will trigger the clone. Just call your next verb (`i_will_work_on`, `commit`, etc.).
|
|
- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the orchestrator logs for a stuck clone.
|
|
|
|
## BRANCH_MISMATCH
|
|
|
|
**Error envelope:** `Workspace is on '<other-branch>' but task requires '<task-branch>'`
|
|
|
|
**Cause:** You're trying to act on task A while your workspace is still on task B's branch.
|
|
|
|
**Fix:** Don't checkout by hand — there is no `roboco_git_checkout` tool. Call the verb on the *intended* task instead:
|
|
|
|
- Devs: `i_will_work_on(task_id)` switches to that task's branch
|
|
- PMs: `i_will_plan(task_id, plan)` switches to that parent task's branch
|
|
- QA: `claim_review(task_id)` switches to the dev's branch under review
|
|
|
|
If your workspace is dirty, the verb returns an envelope telling you to either `commit(...)` first or escalate via `i_am_blocked`.
|
|
|
|
## NO_COMMITS on open_pr
|
|
|
|
**Cause:** No commits on the task yet — the choreographer has nothing to open a PR over.
|
|
|
|
**Fix:** `commit(message=..., files=...)` at least once, then call `open_pr(task_id)` again.
|
|
|
|
## Branch Behind Its Base / master
|
|
|
|
**Symptom:** `roboco_git_status` shows `behind > 0` against the base branch when you go to submit.
|
|
|
|
**Cause:** The base (cell branch or master) advanced after your branch was cut, so your branch is stale.
|
|
|
|
**Fix:** You have no rebase verb — do **not** create a rebase task or improvise with shell git. Bringing the branch current is a platform/PM action. Escalate: devs `i_am_blocked(reason="branch behind base — needs rebase")`; PMs `escalate_up(...)`.
|
|
|
|
## src refspec does not match any (during open_pr)
|
|
|
|
**Error:** `src refspec '<branch>' does not match any`
|
|
|
|
**Cause:** A re-provisioned or shared clone can be missing the local branch ref even though the commits are already on origin.
|
|
|
|
**Fix:** Just call `open_pr(task_id)` again — the gateway recovers the ref from origin, or returns an explicit "unclaim and re-claim to rebuild" instruction. Follow whichever the envelope gives you; don't switch branches by hand.
|
|
|
|
## Updates were rejected / non-fast-forward (on push)
|
|
|
|
**Cause:** Your branch is behind its remote, so the push can't fast-forward.
|
|
|
|
**Fix:** Escalate rather than improvise — devs `i_am_blocked(...)`, PMs `escalate_up(...)`. There is no agent-layer pull/rebase to reconcile it.
|
|
|
|
## NO_PR on pass / fail
|
|
|
|
**Cause:** The PR was never created — usually because `open_pr(task_id)` did not run cleanly.
|
|
|
|
**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)` after fixing whatever blocked the PR opening (see PR Creation Failed, below). QA cannot create the PR.
|
|
|
|
## PR Creation Failed (during open_pr)
|
|
|
|
**Causes:**
|
|
|
|
1. Nothing to push — no commits on the branch
|
|
2. Branch is on the workspace but not pushed yet (rare; the choreographer pushes during `commit`, but a stale workspace can drift)
|
|
3. Project has no git token configured
|
|
4. The GitHub repo doesn't allow PRs from your branch (rare; usually org-level branch protection)
|
|
|
|
**Fix:**
|
|
|
|
- Verify commits exist with `roboco_git_log(project_slug=...)`
|
|
- Verify the project has a git token (Missing Git Token, above)
|
|
- If the task is in a stuck state, `unclaim(task_id)` and re-`claim` to rebuild the branch
|
|
|
|
## FORCE_PUSH_FORBIDDEN
|
|
|
|
**Cause:** Force-push is CEO-only. Anyone else attempting it (typically because their branch diverged) is denied.
|
|
|
|
**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer rebuilds the branch from the parent's HEAD; replay your commits with `commit(...)`.
|
|
|
|
## Merge Conflicts on `complete`
|
|
|
|
**Cause:** The leaf PR conflicts with the parent branch (cell branch or master).
|
|
|
|
**Fix:** This currently surfaces as an error envelope from `complete`. The recovery path:
|
|
|
|
1. PM `unblock(task_id, restore=False)` — frees the task back to the dev
|
|
2. Dev re-claims, the choreographer rebuilds the branch off the latest parent, and they replay their commits
|
|
3. Dev `open_pr` again
|
|
4. QA re-runs `pass` (or `fail` if the rebase changed behaviour)
|
|
5. PM `complete` again
|
|
|
|
We don't expose a "resolve conflicts in place" path at the agent layer — rebuilds via the lifecycle are the recovery.
|