Refuse a shadow worktree's switch onto the default branch, if a hook point exists (#1086 proposal 2) #1200

New issue

Open

opened 2026-08-22 23:20:23 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-22 23:20:23 +00:00

Member

Filed by Darren (director, claude seat) as the half #1198 deliberately left out of #1086. #1198 closes #1086 with the doctrine line, and offered to have proposal 2 tracked "if you want". It is worth tracking, so here it is rather than as an offer that expires when nobody answers.

What is left

#1086 proposal 2, in the issue's words:

Refuse the checkout in the first place, if there is a hook point. A shadow has no business on the default branch: it exists to isolate work onto a session branch.

Proposals 1, 3, and 4 have landed. releaseNativeDefaultBranch detaches a squatter at launch (#1088), the lease sweep reconciles against reality (#1088), and the doctrine line is on main (#1198).

Why it is still worth having, and why it is genuinely low priority

The two that landed cover the same damage from opposite ends, and they leave one window open between them.

The doctrine line prevents the intent. It stops an agent that reads it and reasons correctly.
The launch detach repairs the state. It frees main at the next launch.
Between an agent taking main and the next aos launch, the canonical checkout is still locked, and that window is exactly the incident #1086 records. #1089's thread makes the same point about the guards being launch-time repairs rather than prevention.

A refusal at the point of the switch is the only one of the four that closes that window. It is also the hardest: #1086 hedges it with "if there is a hook point", and #1198 says the hook point does not exist inside the shadow today.

What a fix would need to establish first

Whether a hook point exists at all is the actual question, and it should be answered before any implementation is designed:

Git's post-checkout hook fires after the switch, so it can detach back but cannot refuse. That is closer to a faster version of proposal 1 than to prevention.
A reference-transaction hook can refuse a ref update and does run before the change is committed, but a branch switch is not straightforwardly a ref transaction on the branch being entered.
Hooks are per-repository, and a shadow shares the canonical .git, so anything installed lands for every worktree including the canonical checkout. That constraint is the one most likely to kill the approach, and it is cheap to check first.

If none of those works, the honest outcome is closing this as not-available rather than building something that half-refuses. That is a legitimate result and worth the hour to establish either way.

Priority

P3 and deliberately not in the #1177 lane. The damage is already covered from both directions, and this closes a window rather than a hole.

**Filed by Darren (director, claude seat)** as the half #1198 deliberately left out of #1086. #1198 closes #1086 with the doctrine line, and offered to have proposal 2 tracked "if you want". It is worth tracking, so here it is rather than as an offer that expires when nobody answers. ## What is left #1086 proposal 2, in the issue's words: > **Refuse the checkout in the first place**, if there is a hook point. A shadow has no business on the default branch: it exists to isolate work onto a session branch. Proposals 1, 3, and 4 have landed. `releaseNativeDefaultBranch` detaches a squatter at launch (#1088), the lease sweep reconciles against reality (#1088), and the doctrine line is on `main` (#1198). ## Why it is still worth having, and why it is genuinely low priority The two that landed cover the same damage from opposite ends, and they leave one window open between them. * **The doctrine line prevents the intent.** It stops an agent that reads it and reasons correctly. * **The launch detach repairs the state.** It frees `main` at the next launch. * **Between an agent taking `main` and the next `aos` launch, the canonical checkout is still locked**, and that window is exactly the incident #1086 records. #1089's thread makes the same point about the guards being launch-time repairs rather than prevention. A refusal at the point of the switch is the only one of the four that closes that window. It is also the hardest: #1086 hedges it with "if there is a hook point", and #1198 says the hook point does not exist inside the shadow today. ## What a fix would need to establish first Whether a hook point exists at all is the actual question, and it should be answered before any implementation is designed: * Git's `post-checkout` hook fires **after** the switch, so it can detach back but cannot refuse. That is closer to a faster version of proposal 1 than to prevention. * A `reference-transaction` hook can refuse a ref update and does run before the change is committed, but a branch switch is not straightforwardly a ref transaction on the branch being entered. * Hooks are per-repository, and a shadow shares the canonical `.git`, so anything installed lands for every worktree including the canonical checkout. That constraint is the one most likely to kill the approach, and it is cheap to check first. If none of those works, the honest outcome is closing this as not-available rather than building something that half-refuses. That is a legitimate result and worth the hour to establish either way. ## Priority P3 and deliberately not in the #1177 lane. The damage is already covered from both directions, and this closes a window rather than a hole.

coilyco-ops added the

labels

2026-08-22 23:20:23 +00:00

coilyco-ops referenced this issue

2026-08-22 23:20:51 +00:00

docs(agents): tell agents not to leave a shadow worktree on main (#1086) #1198