Omniscio documentation
Browse all documentation
  1. Getting Started13
  2. Sessions & Agents115
  3. Inbox & Notifications64
  4. Projects & Tasks95
  5. Automation & Scheduling81
  6. Knowledge & Memory26
  7. AI Features61
  8. Integrations100
  9. Plugins & Marketplace33
  10. Cloud & Teams56
  11. Settings & Customization59
  12. Account & Billing28
  13. Troubleshooting85
  14. CLI & API Reference22
  15. Legal & Policies4
  16. Uncategorised22

Worktree ops (the agent's git paved road)

Worktree ops is the HTTP surface an agent uses for its own session's git work — commit named files, sync, mark ready — so the safety rules are enforced rather than remembered. It deliberately has no push, no PR and no land-to-master.

What it is

Worktree ops is not a screen. It is the capability surface behind the local control server's /worktrees/:id/* routes, the paved road a coding session takes instead of running raw git. It exists so a rule like "stage only the files you named" is a 403 rather than a sentence in a prompt the model may skip.

Where to find it

A session reaches it over the control server at 127.0.0.1:19519: the read GET /worktrees/:id/status (the one route a scoped per-session token may call) plus the mutations POST /worktrees/:id/{commit,sync,ready,adopt,release,gate-hold,reclaim,remove} and POST /worktrees/block. The read-only companion — what workspaces exist, keep one, restore one — is the separate Worktree Ledger surface.

How it behaves

  • Mutations are agent-scoped. A scoped per-session token is refused 401; mutations need the global full-trust token. The route finds your workspace from X-AMC-Source-Session-Id, so you act on your own tree (not_owner otherwise, or an unowned tree is adopted on first write).
  • commit stages only the files you named and hard-refuses a wider staged set, a path escape, node_modules/.git, lockfiles, credential material, and a protected branch.
  • sync rebases onto master but never resolves a conflict for you — a conflicted rebase comes back to you, it does not pick a side.
  • ready refuses to stamp unless a gate receipt covers the exact commit. The receipt says whether the evidence is verified or pre-cutover / inherited-red / human-override; a humanOverride needs a stated reason and is 403 for a scoped token.
  • It deliberately excludes push, open-PR and land-to-master — those are owner-approval and auto-lander territory. A 200 from /remove can still mean removed: false when a preservation floor held the tree.

For agents

  • Route family: src/main/services/cli/cli-server-worktree-ops-routes.ts.
  • The service behind it: src/main/services/worktree/ops/worktree-ops-service.ts.
  • Ownership and slot claiming: src/main/services/worktree/worktree-slot-claim.ts.

Related

Last verified 2026-10-06