How to read this page
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. Every entry below is a failure that has actually occurred on this project, not a hypothetical. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
They share a shape worth naming: each one looked like success. That is what made them expensive. A failure that announces itself costs you a minute; a failure that reports a clean exit costs you the afternoon you spend looking somewhere else.
Every commit in a worktree passes, and nothing is being checked
Symptom: a hand-made worktree commits cleanly every time, including changes that should fail the type gate or the commit-message rules.
Cause: git's hooks path points at a directory that is not tracked, so a worktree created by hand does not have it. Git then runs no hooks, silently — there is no warning for a hooks directory that does not exist.
Fix: copy that directory into the worktree before the first commit, and check for the directory itself afterwards rather than trusting a command's exit status.
A merge reported success and the branch did not move
Symptom: the merge output looked normal, the push afterwards said everything was already up to date, and the work is not on the main branch.
Cause: the merge was piped through another command. A shell pipeline exits with the status of its LAST command, so a merge that failed — on index-lock contention, or on a conflict — is masked by the exit status of whatever it was piped into.
Here is that happening, captured on 2026-09-14. The same merge, run twice, against the same two branches:
$ git merge seat/docsfirstrun/alpha CONFLICT (add/add): Merge conflict in apps/site/scripts/redirects-target.test.mjs Automatic merge failed; fix conflicts and then commit the result. $ echo $? 1 $ git merge seat/docsfirstrun/alpha 2>&1 | tail -1 Automatic merge failed; fix conflicts and then commit the result. $ echo $? 0
The failure text is printed both times. Only the exit status changes — and the exit status is the half a script reads. Any wrapper that tests the pipeline's status concludes the merge succeeded, and the push that follows reports that everything is already up to date, because from its point of view it is.
Fix: never pipe a merge. Use a wrapper that waits for the lock, retries only that specific failure class, and refuses to report success unless the remote branch actually moved. Verifying the branch moved is the part that cannot be fooled.
Uncommitted work has vanished
Symptom: edits that were definitely made are gone, and nothing was committed.
Cause: usually a command that relocates or discards changes across the whole tree — a rebase with automatic stashing, a hard reset, a bare stash — run by a process that did not know another agent had work in flight. The stash stack is shared by every worktree in the repository.
Fix, and prevention: check the stash list before assuming the work is gone — an automatic stash that failed to reapply leaves an entry behind. Keep a periodic snapshot of every worktree's dirty state so recovery does not depend on remembering. And avoid the tree-wide commands entirely in a repository other agents are working in.
An agent's tools stop answering after the app restarts
Symptom: an agent session that was working now fails every MCP call, usually as a refused connection.
Cause: the MCP server binds a fresh port and mints a fresh token on every boot. A session that was already running holds the previous ones, and nothing in the protocol tells it they changed.
Fix: re-establish the session's connection so it re-reads the endpoint file. Retrying the same call cannot succeed.
The CLI says the endpoint descriptor "cannot be trusted" and exits 3
Symptom: Orcyx is running, you can see it, and every orcyx command — including status — refuses with exit 3, saying the descriptor at <app data>/orcyx/mcp-endpoint.json has no pid.
Cause: the app that is running was built before the descriptor gained its pid and version fields, so it wrote the older two-key form. Verified on this machine on 2026-09-14: the live file's keys were exactly "token" and "url" — no pid, no version, no written_at.
Unverifiable is not the same as stale
These are two different verdicts and only one of them means something is wrong with your app:
| Verdict | What it means | Fix |
|---|---|---|
| unverifiable | The descriptor is in the older format, so it carries nothing the CLI can check a running process against. The app may be perfectly alive — the file simply cannot prove it. | Rebuild and restart Orcyx. The new binary rewrites the file in the current format on its next bind. |
| stale | The descriptor IS in the current format, and the pid it names is not a live process. An app wrote this file and then died. | Start Orcyx. The descriptor is rewritten when its MCP server binds. |
Reporting the first as the second would be the lie that costs you the most time: it would send you looking for a crashed app that never crashed. Refusing to answer at all — rather than assuming the app is fine because a file exists — is the whole point of the pid.
Exit 3 here is the CLI working correctly. Until the app is rebuilt and restarted, expect it from every command that needs the app, and do not read it as a broken install.
An agent reports being signed out while other panes are signed in
Symptom: one surface reports an expired session; other agent panes in the same workspace are working normally.
Cause: the surfaces do not all read the same credential store. A pane can be authenticated through its own configuration while a headless surface falls back to the default login for the user account.
Fix: sign in on the surface that is actually failing, rather than assuming a working pane proves the credential is good everywhere.
A first launch is blocked by the operating system
Not a fault. The builds are not yet signed by the operating system. See the install page for the exact prompts and the right way through them — which includes verifying the checksum, because that is the check the missing signature would otherwise have done for you.
- Install — the per-OS prompts and the checksum commands.
Memory pressure warnings on Windows
A very high memory figure on Windows usually reflects the system commit charge rather than physical memory exhaustion, and a Linux subsystem left with an unbounded memory allocation is the common contributor. Cap it in the subsystem's configuration before treating it as an application leak.