Omniscio

Branch lifecycle (deleting a finished branch, re-cutting a held one)

An agent finishes work on a branch and then has to clean up after itself. Two routes on the local control server do that: /branches/delete retires a branch nothing is using, and /branches/recut rebuilds a held branch on today's master without a checkout. A delete answers "deleted" only after verifying the branch is gone; otherwise it answers "held" and names why.

On this page

What it is

Branch lifecycle covers the two ends of an agent's branch after the work is done:

  • Delete — retire a branch the agent has finished with, once nothing else is using it. The answer is one of two outcomes, never a vague success: deleted (the delete was verified) or held (nothing was deleted, with the reason).
  • Re-cut — recreate a held branch on current master with no checkout, for the cases where the branch has to continue from a fresh base rather than from where it stopped.

Both are agent-facing: they exist so a session can tidy its own branches without a person opening the app, and neither is the same thing as the Work in Flight panel or the periodic worktree sweep.

Where to find it

  • Agents call them on Omniscio's local control server; there is no button in the app for either.
  • The install-wide token is required. A session's own scoped token is refused — a session cannot delete or create branches with its own credential.
  • For a person, the same branches and worktrees are visible and manageable in the Dev Pipeline panel.

How it behaves

  • A held delete says why. A branch is protected, ready to land, already moved, currently checked out, owned by a live session, pinned, mid-rebase, or not preserved — each is a named hold rather than a generic failure, so the caller can tell a temporary refusal from a permanent one.
  • "Was the work already merged?" A delete also answers yes, no or unknown on whether the branch's work is already on the base. "No" on a branch that is not otherwise preserved is the one answer worth stopping for.
  • A delete is verified, not assumed. The route reports deleted only after the branch ref is actually gone; a half-done delete reports as held.
  • A re-cut carries no checkout. It produces a branch at current master without touching an existing working folder, which is what makes it usable while the old branch is still held.
  • One delete at a time per repository. If a delete is already running in a repository, a second one is turned away at once with "busy, try again in 30 seconds" instead of piling more work onto the computer. That includes a delete the caller already gave up on, because a delete keeps running after its caller stops waiting.
  • Rate-limited like the other worktree operations. Both routes share the worktree-operation rate limit, and a caller over it is told to retry shortly rather than being silently dropped.
  • Nothing private is recorded. Branch names, repo paths and session ids never enter telemetry; the delete reports only its outcome, its hold reason and the merged answer.
  • Unlanded branch backup — how work on a branch is preserved before anything is retired.
  • Branch sweep — the periodic sweep that finds and retires stale branches.
  • Dev Pipeline panel — the human view of the branches and worktrees on this machine.

Last verified 2026-11-17