A hand edit stops the agents until they've read it

[HamptonMakes]

The problem

Everywhere else in the concurrency machinery, a stale agent write gets merged past whatever landed in between. POST /operations transforms its ranges through the intervening versions and applies anyway; PUT /content just asks for a fresh base_revision. That's the right behavior for agent-vs-agent races — two agents editing different paragraphs shouldn't block each other.

It's the wrong behavior when the intervening edit came from a person. Someone who opens the editor and changes the words by hand is the highest-authority input the document gets, and today an agent that never saw those words can silently undo them — rewriting the paragraph they just fixed, restoring the sentence they just cut. Worse, the existing 409 says only "Stale revision. Expected 7, got 5", so the obvious next move is to re-send the same body with base_revision: 7 and wipe the edit.

What this does

A human version is now a fence, not a merge input. If one landed after this credential last read the plan, every agent write is refused — no rebase, no partial apply — with the person's own diff attached:

{
  "error": "Blocked: Sam edited this plan by hand (an edit, now at v7) and you last read v5. A person's direct edit outranks an agent's — it is not something to merge past. Read the current content, keep their changes, fold your own work in around them, then write again.",
  "code": "human_edit_pending",
  "current_revision": 7, "last_human_revision": 7, "last_seen_revision": 5,
  "human_edits": [{ "revision": 7, "editor": "Sam", "edited_at": "…",
                    "change_summary": "Legal cleared the earlier date",
                    "diff": "-Ship behind a flag in Q4.\n+Ship behind a flag in Q3 — legal signed off…" }],
  "resolve": "GET /api/v1/plans/:id/snapshot to pull the current content…"
}

An agent told only "you are stale" re-derives. An agent shown the words a person chose can keep them. Every unseen human edit is listed with its diff, newest-first under a 12KB budget so the freshest human intent always survives truncation.

Why a read receipt and not base_revision

base_revision is an assertion the caller supplies. Tracking reads is what makes "have you seen this?" a question the server can answer: GET /plans/:id and /snapshot now write a CoPlan::PlanRead — highest revision fetched, keyed per credential, monotonic. Only a real fetch lifts the fence. There's a spec pinning exactly the bypass this closes (is not satisfied by bumping base_revision to the number in the error).

A credential that has never read the plan sits behind the fence too (last_seen_revision: 0 → "you have never read this plan"). Writing wholesale content to a document you've never opened is the blind-overwrite case, and reading first is step one of the documented workflow anyway.

Receipts are per credential, not per person — an agent minting a fresh token per run starts empty and must read. Two agents on separate tokens don't clear the fence for each other.

Scope

Guarded at all four agent write paths: PUT /content, POST /operations (before any rebase machinery runs), session create (so an agent can't accumulate ops against content it never saw), and session commit (a person may edit while the session is open). Web-UI human editing is untouched — human-vs-human already has its conflict screen. Agent-vs-agent staleness keeps the OT rebase it has today.

Checkbox ticks count: Plans::ToggleCheckbox writes a real human version, and a tick is a person saying something about the plan's state. Cost is one cheap re-read.

Reviewer notes

• The 34 broken specs were the feature working. The plan factory builds revision 1 as a human version, so every agent-write spec was writing over an unread human edit. They now read first via agent_has_read (spec/support/agent_read_helpers.rb).
• Separately, the OT-rebase specs in sessions_spec.rb were creating their intervening versions as "human" while testing agent-vs-agent merging. Those are now local_agent — which is what they always meant, and the change makes the specs test what their names claim.
• The guard's happy path is one aggregate over the version index (maximum(:revision)), no rows loaded. Only a genuine block pays to fetch versions, and it selects around content_markdown (MEDIUMTEXT per row) since only the diff is needed.
• /agent-instructions gains a "When a person has edited by hand" section — the response tells agents to keep the human's text and raise a comment rather than overwrite a decision someone made deliberately.
• New PlanRead model gets an ActiveAdmin page, per AGENTS.md, so "why is my agent blocked?" is answerable without a console.

Testing

Full suite green: 1791 examples, 0 failures (including system specs). 17 new specs in spec/requests/api/v1/human_edit_guard_spec.rb cover the fence, the no-bypass property, receipt behavior, and the agent-vs-agent path staying lenient. rubocop clean.

Migration adds coplan_plan_reads (engine + host copy).

Not included

The plan page shows nothing about a hand edit currently fencing agents. Easy to add a header marker if that's wanted.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aa11a16ed9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".