kandev/docs/specs/tasks/system-design/plan-write-consistency.md

status, system, requirements, created, owners

status	system	requirements	created	owners
current	tasks	REQ-TASKS-PLAN-WRITE-CONSISTENCY-001 REQ-TASKS-PLAN-WRITE-CONSISTENCY-002 REQ-TASKS-PLAN-WRITE-CONSISTENCY-003 REQ-TASKS-PLAN-WRITE-CONSISTENCY-004 REQ-TASKS-PLAN-WRITE-CONSISTENCY-005	2026-08-31	kandev

Task plan write consistency System Design

Purpose and boundaries

This design closes the window between a plan read and its commit. It does not change the truncation thresholds, the response shape of a non-truncating write, or the missing-task boundary owned by docs/specs/tasks/system-design/plan-write-lifecycle.md.

Requirement mapping

Ids below abbreviate REQ-TASKS-PLAN-WRITE-CONSISTENCY-00N.

Requirement	Design section
001	Chosen mechanism; Where the decision moves
002	Chosen mechanism; Retiring lock keys; Scope of the critical section; Existing behavior that must change
003	Scope of the critical section
004	Response contract
005	Scope of the critical section; Retiring lock keys; Failure and recovery

Current state

• Agent path: internal/mcp/handlers.handleCreateTaskPlan and handleUpdateTaskPlan call evaluatePlanWriteGuard, then PlanService.CreatePlan / UpdatePlan with ForceNewRevision from the guard.
• Browser path: internal/task/handlers.wsCreateTaskPlan and wsUpdateTaskPlan call the same methods and never set ForceNewRevision.

Before one agent update commits, plan state is read at least four times outside any transaction: evaluatePlanWriteGuard reads GetPlan and the revision history, UpdatePlan reads GetTaskPlan for its existence check, and upsertPlan reads GetTaskPlan and GetLatestTaskPlanRevision again. All use the read-only pool, opened by internal/db.OpenSQLiteReader with four connections, while the commit happens later in WritePlanRevision on the single-connection writer pool. SetMaxOpenConns(1) serializes commits against each other but not a reader against a commit, so read(A), read(B), commit(B), commit(A) is unprevented.

WritePlanRevision already computes max(revision_number) + 1 in its transaction. The coalesce target and truncation decision are not safe.

Chosen mechanism

Serialize the whole read, decide, commit sequence per task inside PlanService, and evaluate truncation inside that critical section.

PlanService gains a per-task lock keyed by task ID, held across the state reads, the truncation decision, the coalesce decision, the WritePlanRevision call and the following re-read. Because every plan writer already funnels through PlanService, taking the lock in the four public entry points, CreatePlan, UpdatePlan, RevertPlan and DeletePlan, covers every path that writes a revision or reads plan state to decide one; "Scope of the critical section" gives the boundary and explains why the shared upsertPlan helper is not the acquisition point. Keying by task ID satisfies AC-TASKS-PLAN-WRITE-CONSISTENCY-002.6: a write for one task never waits on another's lock.

PlanService.MarkImplementationStarted is the one exported method that mutates a task_plans row and is deliberately left outside the lock rather than overlooked: a single atomic statement that reads no plan state and writes no revision, so it can neither observe nor invalidate a decision made inside the section. It shares one column with upsertPlanHead's ON CONFLICT clause, task_plans.updated_at, and writes it only on the first mark. The overlap is immaterial: no criterion constrains the HEAD row's updated_at, and canCoalesce reads the revision's UpdatedAt on task_plan_revisions, a different table.

Retiring lock keys

Task identifiers are unbounded over a process lifetime, so entries must be removed. Neither keyed-mutex precedent removes them: parentMutex in internal/task/service/handoff_service.go and keyedMutex in internal/plugins/service.go, the latter because its plugin id keyspace is "small and long-lived". Task ids are neither, so neither may be copied without retirement.

Retirement has one silent failure mode. Delete an entry whenever its mutex is released and a goroutine holding the old pointer locks that instance while a later arrival locks a fresh one for the same task: two writers, no error, the race back.

The protocol that avoids it: one outer mutex guards the map, and each entry holds its per-task mutex plus a count of goroutines holding or waiting for it. Acquire takes the outer mutex, finds or creates the entry, increments the count, releases it, then locks the entry mutex. Release unlocks the entry mutex, takes the outer mutex, decrements the count, deletes the entry only at zero, and releases the outer mutex. Because the count is incremented before the outer mutex is released, no entry can be deleted while a goroutine is still on its way to it.

Any implementation keeping both properties is acceptable: the count is mutated only under the map guard, and deletion happens only at zero under it.

Within the section the reads see the state the write will commit against: no other in-process writer can commit while the lock is held.

That rests on a second property the whole mechanism depends on: a read issued on the read-only pool inside the lock must observe a commit made moments earlier on the writer pool. It holds because the database runs in WAL mode, where a read transaction takes its snapshot when it begins and sees everything committed before it started. _cache=shared does not provide it; it only governs page-cache sharing.

This is easy to lose: every plan and MCP test helper passes one handle as both writer and reader and cannot observe it, so AC-TASKS-PLAN-WRITE-CONSISTENCY-002.10 requires it over genuinely split pools. See "Test strategy".

Sound only within one process, which the requirements state as an exclusion.

Where the decision moves

Truncation is decided in internal/mcp/handlers today, above the service, so a lock inside the service cannot cover it. The decision moves into the write path and the caller selects it rather than performing it:

• The write request carries a flag meaning "evaluate truncation for this write". The agent path sets it. The browser path does not, which is AC-TASKS-PLAN-WRITE-CONSISTENCY-003.2 and 003.4.
• The write result carries what the caller needs to render a warning; PlanWriteResult below names the fields.
• The MCP handler keeps ownership of the warning string. planTruncationWarning stays in internal/mcp/handlers with its "revision 0 means unknown" convention. An unknown number does not prove that history contains the replaced content. Therefore, that warning does not claim preservation or recovery. Its signature changes because it measures the code points itself today, but the handler no longer holds the replaced content, which exists only inside the critical section. It takes the counts instead, (replacedRunes, newRunes, priorRevisionNumber int), and the measurement moves into the service, onto the content the write replaced.
• The detector moves with the decision. planTruncationDetected and its thresholds planTruncationMinPriorChars and planTruncationMaxRetainRatio are in internal/mcp/handlers today, and internal/task/service cannot import them: mcp/handlers imports task/service and no reverse import exists, so reusing them where the replaced content lives would be a cycle. They move to internal/task/service, keeping the single source of truth the thresholds exclusion assumes; no copy stays behind. evaluatePlanWriteGuard and planWriteGuardResult become dead and are deleted rather than kept as a thin flag-setter: their two callers set the request flag and read the result.
• The handler performs no plan or revision read after the service call. Rendering from a re-read would put the race back into the one path the warning exists to make trustworthy; returning the full prior content would copy a 40k character plan on every truncating write.
• The renderer assumes newRunes < replacedRunes and replacedRunes > 0, today pinned on its only caller invoking it after planTruncationDetected returned true. That carries: the handler renders only when the result's truncation flag is set, and the service sets it only where the comparison already holds.

ForceNewRevision remains for callers that force an append for their own reasons; the in-section truncation decision also forces one (AC-TASKS-PLAN-WRITE-CONSISTENCY-001.5).

Concretely: CreatePlanRequest and UpdatePlanRequest each gain one bool beside ForceNewRevision, and CreatePlan and UpdatePlan return a result struct rather than *models.TaskPlan.

type PlanWriteResult struct {
	Plan                *models.TaskPlan
	TruncationDetected  bool
	ReplacedRunes       int
	NewRunes            int
	PriorRevisionNumber int // 0 means not established
}

The two browser call sites read .Plan and are otherwise unchanged. This keeps AC-TASKS-PLAN-WRITE-CONSISTENCY-004.1 and 003.2 true.

Scope of the critical section

The lock is acquired in the four public entry points, CreatePlan, UpdatePlan, RevertPlan and DeletePlan, in each case after identifier validation and authorization and before that method's own first plan-state read.

For RevertPlan that first read is the target-revision fetch, not the HEAD read after it. mergeRevisionInTx rewrites a revision row's title and content in place when it is the coalesce target, so the latest revision is mutable, not immutable history: a revert fetching that target outside the lock can commit content a concurrent coalescing write already replaced. upsertPlan does not acquire it; it becomes a helper whose documented contract is that its caller already holds the task's plan write lock. That is what lets UpdatePlan put its existence check in the same section as the write it guards.

The acquisition point is named because the obvious alternative fails. UpdatePlan reaches upsertPlan, so locking in both takes a non-reentrant per-task mutex twice on one path: every update self-deadlocks, permanently for that task, stranding the refcount. AC-TASKS-PLAN-WRITE-CONSISTENCY-005.5 states the invariant: the section is entered once per call path, so no method that acquires may call another that acquires.

Authorization runs before acquisition, next to identifier validation. It is a task lookup wired to AuthorizeTaskAccess, so it performs I/O and there is no reason to hold a task's write lock across it; this is also today's order.

The section ends after the post-write re-read, not at WritePlanRevision's return. upsertPlan and RevertPlan both re-read HEAD once the write has committed, and in upsertPlan that re-read, not the in-memory value the write was assembled from, is what the method returns. Released at the commit, that read could observe a queued write's commit instead and hand the caller another write's content as the outcome of its own, which AC-TASKS-PLAN-WRITE-CONSISTENCY-002.5 forbids in the same response 004.2 pairs with the truncation counts. It is kept rather than replaced by the in-memory value because it also carries the persisted HEAD identity when the pre-write read failed. See "Existing behavior that must change".

DeletePlan is in that list deliberately. Moving UpdatePlan's existence check inside the section is only worth doing if the deleter participates: an unlocked delete can still commit between an in-lock check and the write it guards, so moving the check alone changes nothing. DeletePlan writes no revision, so it is not a plan write under the requirements' Terminology, but it mutates state every plan write reads. AC-TASKS-PLAN-WRITE-CONSISTENCY-002.12 states the ordering this buys.

With the deleter inside, UpdatePlan's existence check can move in too. It currently reads GetTaskPlan before delegating to upsertPlan, which reads it again; the redundant second read should collapse into one taken under the lock. Collapsing it changes what a failed read must do, which "Existing behavior that must change" settles.

The two reads it collapses serve opposite contracts and the surviving read keeps both. CreatePlan tolerates an absent HEAD and appends (AC-TASKS-PLAN-WRITE-CONSISTENCY-001.8, 002.11); UpdatePlan must fail on one (002.12) rather than recreate a plan a concurrent delete removed. The requirement is therefore caller-supplied, not inferred from the read: upsertPlan takes a requireExistingHead argument, set by UpdatePlan and clear on the CreatePlan path, and returns ErrTaskPlanNotFound when it is set and the read returned absent. unknown is not absent and never triggers it, per 001.6. The same flag marks the update path, so the HEAD-row title and author fallbacks stay gated to it and CreatePlan's defaults are unchanged (004.1). The 001.9 preserve flags are not gated to it: they are computed on both paths, because a create over an existing plan can omit a title too. Any equivalent shape is acceptable, including hoisting the read into the entry points and passing the tri-state down; a single tolerant read with no branch is not.

Serializing the delete does not close the loss path behind it. DeletePlan removes only the HEAD row and leaves the revisions. A create that follows finds no HEAD, emits no warning (AC-TASKS-PLAN-WRITE-CONSISTENCY-001.8), and under today's coalesce rules can still merge into a surviving revision, overwriting pre-delete content sequentially rather than by a race. 002.11 closes it by requiring an append whenever the task has no HEAD at commit time.

The event publishes at the end of upsertPlan and RevertPlan should not hold the lock: they call the event bus, which widens the section for no correctness benefit.

That is a restructuring, not a comment. The post-write re-read and both publishes sit at the end of upsertPlan while the lock is owned by CreatePlan and UpdatePlan, so the release point is unreachable from the acquisition point. A defer release() in the entry point, which the panic rule in "Failure and recovery" pushes toward, holds the lock across both publishes; releasing inside upsertPlan instead lets that defer run a second time, decrementing the refcount twice and deleting an entry another goroutine waits on, the failure "Retiring lock keys" exists to prevent.

upsertPlan stops publishing: it returns the saved plan plus the events its caller is to emit, and the entry point acquires, calls it, releases, then publishes them in today's order, plan event before revision event. Release is idempotent, so a deferred release can coexist with an explicit one. Any implementation is acceptable that holds three properties: one refcount decrement per acquisition, release on every exit path including a panic, and no event published under the lock.

DeletePlan has no post-write re-read, so that boundary does not locate its section end: it ends when the delete commits, and its TaskPlanDeleted publish moves outside under the same rule.

Existing behavior that must change

Five things in PlanService are not merely relocated by this design. Each is wrong, or becomes wrong, against the contract, and none is discoverable above.

resolveCoalesceWindow maps a negative configured window to defaultCoalesceWindow, five minutes, so canCoalesce's s.coalesceWindow <= 0 guard never sees a negative value and a negative window coalesces normally today, while 002.8 requires zero or negative to append every write. The negative branch must stop substituting the default: preserve the value or clamp it to zero, either of which reaches the guard. Only an absent configuration falls back to five minutes. Without this an implementer believes 002.8 holds.

upsertPlan must append when the task has no HEAD at commit time, per 002.11. Today the coalesce decision consults only the latest revision, so revisions surviving a delete remain eligible merge targets.

The collapsed reads must stop aborting the write. This is the largest of the five and becomes visible only once the collapse happens. Two reads become one, twice over: upsertPlan's GetTaskPlan with the guard's GetPlan, and upsertPlan's GetLatestTaskPlanRevision with the guard's revision lookup. Each pair returns the same state. But their halves have opposite failure contracts: the guard's reads are tolerant, a failure forces an append and the write proceeds, which is what makes 001.6 and 001.7 true, while upsertPlan's return the error and the write dies.

The merged reads take the tolerant contract:

• A failed HEAD read forces an append, emits no warning, and completes the write (001.6). Truncation cannot be evaluated without the replaced content, and appending stops a later write coalescing into an unknown prior revision.
• A failed latest-revision read forces an append and completes the write; when truncation was detected the warning is still emitted without a revision number (001.7). The rule is deliberately unconditioned on the truncation flag: after the collapse one call serves both paths, and appending is always safe, so 001.7 becomes an instance of the rule rather than an exception.

Both rules outrank the coalesce rules for that write, and 005.1 states the precedence: its merge clause is conditioned on the task having a HEAD and on the write having read it successfully, so a failed read falls to 001.6 and an absent HEAD to 002.11, both appending. Coalesce behavior is unchanged for every write whose reads succeeded.

One consequence of that tolerance is not obvious. A failed HEAD read is not "this task has no HEAD", and upsertPlan cannot tell them apart today: both arrive nil. They must be distinguished as found, absent or unknown, because that value decides four things besides truncation: the event type, the HEAD identity, UpdatePlan's title and author fallbacks, and UpdatePlan's existence gate. Under unknown the write emits the plan updated event rather than the created one; a spurious create asserts something false about a task's history. It supplies no HEAD identity, which is safe as long as the re-read succeeds: upsertPlanHead fills an empty ID and a zero CreatedAt with a fresh UUID and now in Go, unconditionally, on the caller's own struct, before the statement runs, and its ON CONFLICT(task_id) DO UPDATE clause then writes neither column, so an existing row keeps its real ones and the caller receives those from the in-section re-read. The fabricated pair survives only in memory, which is what makes a failed re-read a special case in "Failure and recovery". An implementer reusing the nil result for unknown ships a write that succeeds, persists correctly and emits the wrong event type.

The metadata fallbacks are the least obvious and the most damaging to get wrong. UpdatePlan takes title and created_by from the HEAD row whenever the request omits them, and both callers may legitimately omit a title. Under unknown those fallbacks have nothing to read and today's defaults take over: upsertPlan substitutes the literal Plan and the author is re-resolved, so a transient read failure would silently rename the user's plan and rewrite its author, on a write 001.6 requires to succeed. The write must instead leave the stored title and created_by as they are: the values it could not read are the values it must not replace.

Making the ON CONFLICT assignments conditional on the value being empty does not achieve that, because nothing empty reaches the statement. Three substitution sites exist, two on this path: upsertPlan replaces an empty title with Plan and resolveAuthor resolves the author before the repository is called, then upsertPlanHead substitutes both again. Emptiness is observable only at the top of upsertPlan, so preservation is captured there and carried down as an explicit signal: upsertPlan computes one preserve flag per column from the HEAD read being unknown and the request field being empty, before its own substitution runs, and passes both flags through WritePlanRevision to upsertPlanHead. Neither substitution changes; they still supply the insert branch's defaults. The flags bind into the update branch alone, title = CASE WHEN ? THEN task_plans.title ELSE excluded.title END and likewise for created_by, so a task with no HEAD row still inserts the default while an existing row keeps its stored value. Only content and updated_at are written unconditionally. After the upsert, the same transaction reads the stored title and author. The repository returns these values in the HEAD object. It also uses the stored title in the new revision. Thus, a later revert cannot apply a fallback title.

Two consequences. WritePlanRevision is on the exported PlanRepository interface, so this changes it and every implementation; "Where the decision moves" counts them. And all four production entry points default CreatedBy before PlanService is entered, agent on MCP and user on the browser, so only the title half can fire in production today. 001.9 is a service-boundary contract and its author half is tested there, not through a handler.

RevertPlan must stop aborting on its own HEAD read, taken after the target-revision fetch and whose error it currently returns. A revert writes a revision, so it is a plan write under the requirements' Terminology and 001.6 governs it unchanged: an unreadable HEAD forces an append, emits no warning, and the revert completes. This read is not half of either collapsed pair, which is why it survives a fix aimed only at those.

CreatePlan must validate its identifier before acquiring. The empty-task-id check lives inside upsertPlan today and CreatePlan reaches it only through that helper, so acquiring in the entry point would lock on the empty string and only then reject the request, serializing every malformed request against every other, which 005.4 forbids. The check moves up; the other three already validate first.

Alternatives considered

Move truncation detection and the force-append decision inside WritePlanRevision's transaction. Robust across processes, because the decision is made from state read inside the write transaction. Rejected because it puts an agent-facing presentation heuristic (the 2000 character floor, the retain ratio, code point counting) into the SQLite repository, and because the coalesce decision would have to move there too or a second window stays open. Its WritePlanRevision change no longer separates the two: the chosen mechanism changes that method as well.

Return the written revision number and derive the preceding revision as written - 1. Rejected as insufficient rather than wrong. It repairs 001.2 in the warning path, where the write is always an append so written - 1 really is the preceding revision. It does not repair 001.1, 001.3 or any of 002, whose decisions are still made from state read before the commit. It closes one symptom, not the race.

Response contract

No change for a write that emits no warning, satisfying AC-TASKS-PLAN-WRITE-CONSISTENCY-004.1. planWriteResponse still embeds *dto.TaskPlanDTO and dto.TaskPlanDTO is untouched, so the browser plan editor is unaffected. A truncating agent write still adds plan_write_warning and, when established, prior_revision_number.

Failure and recovery

• Current plan content unreadable, or the preceding revision number unestablished: append and complete the write, with no warning in the first case and, in the second, a warning without a revision number when truncation was detected (001.6, 001.7). Revision numbers start at 1, so 0 still means unknown. Both rules, and why the append is unconditioned on truncation, are in "Existing behavior that must change"; neither is today's upsertPlan behavior, which aborts.
• Post-write re-read fails, or succeeds reporting no row, after the write has committed: report the success (AC-TASKS-PLAN-WRITE-CONSISTENCY-005.8). Both reach the service as a nil plan, and a task deleted after the commit cascades the HEAD row away, so it is real. The transaction is durable and cannot be rolled back, so the service returns the plan it assembled in memory, from the request's content plus whatever HEAD identity it holds, and publishes the events it would otherwise have published. Returning the error or ErrTaskPlanNotFound instead, which is what upsertPlan does today, tells the caller a committed write failed and sends an agent into the retry-or-rewrite-from-memory behaviour the warning exists to prevent. When the pre-write HEAD read was itself unknown the service has no identity to report: the struct it handed the repository carries only the fabricated pair "Existing behavior that must change" describes. It clears both before returning, so the caller reads the identity as unknown rather than as a row that does not exist. The repository has already resolved the stored title and author in the write transaction. The fallback result and its event can report that metadata as authoritative. (005.8). This path cannot tell the insert branch apart, so it clears unconditionally. RevertPlan is governed by the same rule and needs no substitute: it returns the revision it wrote, whose id, number and timestamps insertNewRevisionInTx populated in place before the commit, and publishes with the same cleared identity.
• Task deleted between validation and commit: unchanged. The foreign key violation classifies to ErrTaskNotFound and the transaction rolls back, per plan-write-lifecycle.md.
• A write that fails must release the lock, including on a panic, so 005.3 holds. Release must not depend on the happy path and must run the full protocol above: skipping the refcount decrement leaks an entry permanently, the bound "Retiring lock keys" exists to hold.
• Identifier validation and authorization run before the lock is taken, so an empty identifier is never a lock key, such requests do not serialize against each other (005.4), and no write lock is held across an authorization lookup.
• Only the per-task plan write lock is held inside the section (005.5); nothing in it may acquire a second.
• A caller whose context is cancelled while queued is not released early (005.7). A plain sync.Mutex is not context-aware and stays that way: the section is one set of reads plus one short transaction, so the wait is already bounded. The write acquires in its turn, fails when it reaches its write transaction, and releases normally, which 005.3 covers. Its reads before that transaction run on a context decoupled from the caller's, context.WithoutCancel, so cancellation cannot divert the write into 001.6's unreadable-HEAD path and make it succeed. 001.6 fires on a genuine read failure only.

Test strategy

The seam is the repository, not the service: Handlers.planService is a concrete *service.PlanService, and internal/mcp/handlers/task_plan_guard_test.go already builds handlers over a wrapped repository (newMCPPlanTestHandlersWithFailingRevisionLookup wraps sqlite.Repository and injects failures through it). The concurrency test required by AC-TASKS-PLAN-WRITE-CONSISTENCY-001.3 and 002.1 through 002.3 uses that wrapper to block a chosen call, so the interleaving is forced rather than raced.

It cannot be written as "block A inside the section, then commit B for the same task": under this design B cannot commit while A holds the lock, which is the property being tested. B is observed to queue instead, and the assertions are about the state each write decided against:

1. Seed a plan large enough to cross the 2000 character floor.
2. Start write A, a truncating agent write, and block it inside the section at a wrapped repository call, after it has read plan state.
3. Start write B for the same task from the other path. Observe that B has not committed: it is queued on the same per-task lock.
4. Release A and let it commit, then let B proceed to its own commit.
5. Assert that A's counts describe the content A replaced and the revision it names holds that content; that B's decisions were made against the state A committed, not what B could have read before queuing; and that HEAD equals the latest revision.

Step 3 must go through a write path: committing B through the repository directly would bypass the lock, exercise a writer class the requirements exclude, and pass unchanged against an implementation with no serialization.

The pool split matters twice. Existing helpers build the repository with sqlite.NewWithDB(sqlxDB, sqlxDB, nil), one handle as both writer and reader, and nothing under internal/task/ or internal/mcp/ opens OpenSQLiteReader today. That is why the interleaving must be forced rather than left to pool timing, and why AC-TASKS-PLAN-WRITE-CONSISTENCY-002.10 needs its own test over one file with a real OpenSQLite writer and a real OpenSQLiteReader reader: without it this design's read-after-write visibility is asserted by prose alone.

One existing test must be rewired rather than left to pass. TestMCPPlanTruncationGuard_RevisionLookupFailureOmitsRevisionNumber is 001.7's only coverage and injects into ListTaskPlanRevisions, the call the collapse removes; left alone it passes while exercising nothing. Its seam moves to GetLatestTaskPlanRevision. Any test asserting a write aborts on a HEAD read failure has its expectation inverted: rewire it, do not delete or weaken it. Tests calling evaluatePlanWriteGuard directly move to the service result.

Additional coverage: a write for one task commits while a write for another is held inside the section (002.6); boundaries at exactly 2000 replaced characters and exactly half retained (001.4); a case whose byte and code point lengths differ (001.1); browser path emits no warning and keeps its response shape (003.2); revert appends and does not warn (003.3); a write failing inside the section is followed by a successful write to the same task (005.3); a same-author repeat inside the coalesce window adds no revision while one outside it appends (005.1); a negative configured window appends every write (002.8); a delete followed by a same-author create inside the window appends rather than merging into a surviving revision (002.11); a delete forced to interleave with a write is ordered (002.12); a queued write whose context is cancelled fails and does not block the next write to that task (005.7); a failed HEAD read appends, emits no warning, completes the write and emits the plan updated event rather than the created one (001.6); a failed latest-revision read appends and completes the write where truncation was not detected; a revert whose own HEAD read fails appends, emits no warning and completes; a write that omits a title and whose HEAD read fails leaves the stored title and created_by unchanged rather than substituting Plan; a post-write re-read that fails, and one that reports no row, each returning success with the revision durable and no plan identity rather than the pair upsertPlanHead generated in memory, once through a create or update and once through a revert; an unknown-HEAD update that verifies the stored title in HEAD, the new revision, the write result, and a later revert; a divergent HEAD and latest revision that verifies the warning names no unverified revision; an environment-gated PostgreSQL case for the metadata-preservation branches; a queued cancellation that observes the waiter registration before it cancels the caller; an update whose HEAD read returns absent fails rather than recreating the plan, while one whose HEAD read is unknown proceeds; and a revert to the latest revision forced to interleave with a same-author coalescing write commits the target content, not the content that write merged in.

Implementation note: starting state

The parent card calls a related change "already implemented and merged". It is not merged: the work sits only on feature/plan-truncation-guar-qd5, which has been rebuilt and extended since, so identify it by subject rather than by commit id. On origin/main evaluatePlanWriteGuard still calls PlanService.ListRevisions, there is no GetLatestRevision, and the false ListRevisions doc comment remains. It touches task_plan_guard.go and plan_service.go, which this work also touches: confirm its merge state and rebase rather than reimplement.