Claude Code Routines Need Output-Branch Contracts, Not Prompted Git Etiquette

Scheduled coding agents are not chat sessions with alarms. They are job runners. Job runners need output contracts.

That is the uncomfortable lesson in a fresh Claude Code issue reporting that scheduled cloud Routines can finish work on a harness-assigned branch such as claude/stoic-fermi-azzeU instead of the canonical branch the agent explicitly created. The reporter runs roughly nine scheduled routines nightly against a private GitHub repo, each starting from a fresh clone of main, each prompt beginning with a specific branch command like git checkout -B claude/elf-<slug>-YYYY-MM-DD, and each expected to merge clean work back to main.

When the bug hits, the commit exists. The work may even be good. But it is stranded on a random session branch, the expected canonical branch is not created, main is not updated, and downstream automation scanning the canonical branch pattern sees nothing. That is worse than an obvious failure. The system did useful work and then failed to publish the artifact where the rest of the workflow was designed to find it.

A prompt cannot outvote the harness forever

The report, issue #69783, was opened June 20 at 20:27:53 UTC. It had little community reaction at research time — one duplicate-detection bot comment and no human pile-on — but the shape of the problem is familiar to anyone who has tried to turn coding agents into unattended automation.

The reporter already tried the obvious prompt-side mitigations. Make git checkout -B the first git action. Explicitly push HEAD to the target ref before merge. Add an end-of-run verification gate that checks the current branch, force-pushes on mismatch, and emits a STRANDED marker if the branch contract failed. Those are good instructions. They reportedly reduce the failure rate. They do not eliminate it.

The suspected reason is the important part: the runtime’s managed commit/push layer may be operating with its own branch state after the model’s prompt-level workflow completes. If true, the agent and the harness are two actors writing to the same repository with different definitions of success. The model thinks it created and pushed the canonical branch. The harness may still publish the final commit to its own session branch. Automation then has to guess where the truth lives.

This is why “just put it in AGENTS.md” is not enough. Repo instructions are useful context. They can teach an agent naming conventions, merge policy, test gates, and review expectations. But branch selection, artifact publication, retry semantics, and final job status are control-plane responsibilities. You can ask the model politely to use a branch name. If the platform has a separate managed output path, the platform has to expose and honor the branch contract too.

Finalization is where agent workflows get dangerous

The report says stranded runs are more common on long or heavy tasks, where the final git steps are most likely to be skipped under budget pressure. That tracks. Many agent workflows put the most important actions at the end: commit, push, merge, open a PR, post a summary, update an issue, notify Slack, or mark a task done. If the finalization phase is best-effort, your workflow can look successful in the transcript while failing as a system.

Human recovery is possible. A developer can scan claude/* branches, inspect diffs, find the commit, cherry-pick it, and update the tracker. Automation cannot safely do that without a stronger contract. It needs a durable pointer: run ID, requested branch, actual branch, commit SHA, merge target, gate outputs, and whether the harness performed a managed push after the agent’s last command. Without that, every orphan branch is a forensic exercise.

Claude Code’s recent release history makes the issue more credible even without broad reaction. Version 2.1.183 included scheduled-task and webhook fixes, including a change so trigger deliveries are classified as task notifications rather than keyboard input and can no longer approve pending actions or set session titles in Auto mode. Other recent issue clusters touch remote routines, subagents, background task state, and session cleanup. This is the surface area where “assistant” turns into “distributed job system,” and distributed job systems do not get to wave away artifact discovery.

For teams using scheduled agents, the mitigation is to treat output as infrastructure. Require every run to emit a manifest outside the model’s prose: session ID, expected branch, actual branch, commit SHA, diff summary, test results, merge status, and artifact URLs. Put a reconciler outside the agent that checks for missing canonical branches and unexpected claude/<adjective>-<noun>-* branches. Alert on orphan branches instead of waiting for a human to notice that yesterday’s nightly routine “succeeded” but shipped nothing.

If your agent platform can produce PRs instead of direct merges, prefer that until branch determinism is proven. If it cannot expose the session branch name or managed-push behavior, assume you need manual recovery. And if you are designing an agent runtime, do not make branch names a prompt convention. Make them a job parameter with an idempotency key, a returned result object, and a clear failure state when the platform cannot publish where requested.

The broader lesson applies beyond Claude Code. Codex, Cursor, Aider, OpenCode, internal agents — all of them are walking toward the same boundary. A coding assistant can improvise. A job runner needs contracts. It needs leases, retries, cancellation semantics, output locations, durable logs, status transitions, and artifact discovery. Otherwise you have cron with a personality and no reliable way to know where the work went.

Branch discipline should not depend on whether the model remembered the last instruction at the end of a long run. The runtime should make the expected output location boring, explicit, and testable. That is what production automation looks like. Less charming, more useful.

Sources: Claude Code issue #69783, Claude Code v2.1.183 release notes, Claude Code subagents documentation, Claude Code issue #61141, Claude Code issue #66968