adv_task_update status:done fails with TASK_DONE_REQUIRES_CHECKPOINT immediately after successful adv_task_checkpoint

[JRedeker]

Summary

adv_task_update status: "done" returns TASK_DONE_REQUIRES_CHECKPOINT even after a successful adv_task_checkpoint mode: "complete" call. The error message and the actual state machine behavior diverge, creating confusion during apply workflow.

Observed (2026-07-21, fixZellijPaneTitles archive)

Sequence for three completed tasks (tk-d6aec1b24ef6, tk-7f15a4265ba3, tk-9c9a7eac113a):

1. adv_task_checkpoint taskId: <id> mode: "complete" verification: "..." → returned {"status":"clean","checkpointRecorded":true,...} (success).
2. adv_task_update taskId: <id> status: "done" → returned:

   error: "Normal task completion must go through adv_task_checkpoint so git checkpoint metadata, touched files, and verification are recorded before the task is marked done."
   code: "TASK_DONE_REQUIRES_CHECKPOINT"
   hint: "Run adv_task_checkpoint with mode:'complete'. Use adv_task_update status:'done' only for explicit poisoned-history recovery..."
   

3. Retried adv_task_update status: "done" shortly after → succeeded.

So the same call shape succeeded on the second attempt, with no intervening checkpoint call. The state machine appears to have a propagation lag between checkpointRecorded: true and the gate that checks it for status: "done".

Expected

• adv_task_update status: "done" immediately after a successful adv_task_checkpoint mode: "complete" should succeed on first attempt.
• If there IS a propagation lag, the error message should say so (e.g. "checkpoint recorded but not yet visible to status gate; retry in Nms").
• The current message ("must go through adv_task_checkpoint") is misleading because the caller DID just call it.

Actual

• First adv_task_update status: "done" after checkpoint fails with misleading error.
• Retry succeeds — but the agent has no signal that retry will work vs whether it needs to do something different.

Distinguishing from related issues

• Cancelled task with stale contract_refs permanently blocks archive (CONTRACT_UNKNOWN_REF) — validator inconsistency + no tool to reconcile #226 covers cancelled tasks with stale contract_refs blocking archive. Different layer (archive gate, not completion state machine).
• Disk-projection recovery defeated by live wedged workflow; add workflow reset tool + diskAuthoritative recovery + fix missing_workflow classification #198 covers disk-projection recovery vs wedged workflows. Different layer (gate state, not task state).

This issue is specifically about the task-completion state machine's checkpoint observation lag.

Suggested investigation

• Look at adv_task_update status-transition validator: where does it read checkpointRecorded? Is it reading from Temporal visibility (which may lag) instead of the just-recorded signal?
• If the read is eventually-consistent, either:
  • Add a short retry-with-backoff inside adv_task_update when the preceding checkpoint call is fresh.
  • Or pass the checkpoint receipt through to the status update call so it can be verified synchronously.

Repro

Any apply workflow that calls adv_task_checkpoint mode: "complete" followed immediately by adv_task_update status: "done" on the same task. The just-archived fixZellijPaneTitles (merge 07fbd4d on advance trunk) is a worked example — all three implementation tasks exhibited this behavior.

Origin

Filed from post-archive reflection on fixZellijPaneTitles (cross-project work driven from toolbox session). Companion ADV follow-up change: relaxStageV2EvidencePolicy in ~/dev/advance (covers a different stage-v2 evidence_policy friction).