Approval or plan revision is stuck

Use this when a run exists and the worker has already reached a human gate.

The expected request-changes loop is:

plan node blocked
  -> reviewer requests changes
  -> run stays blocked but becomes claimable again
  -> worker receives workflow.approval_decision
  -> plan revision runs in plan mode with no write/shell tools
  -> revised plan reopens review
  -> reviewer approves
  -> implementation continues

1. Confirm The Run Is Actually Waiting On A Gate

Open run detail and check:

• the current node is a plan or approval gate;
• the gate has reviewer tags or explicit reviewers;
• at least one current team member matches the required reviewer tag;
• the run status is blocked or queued, not failed or canceled;
• the gate row shows the latest decision and approver when one exists.

If no reviewer tag resolves to a team member, fix team membership and sync the .viewport source again. Viewport should reject policy sync for empty reviewer tags before a new run starts.

2. If Request Changes Was Clicked

After request changes:

• the inbox item should resolve as changes requested;
• the run should return to queued/claimable state;
• the plan node should stay blocked;
• the worker should receive a runtime command with decision=request_changes;
• the revised plan should reopen the plan review item.

Restart the same paired worker if it is not running:

vpd worker start --mode persistent --transport polling

Do not start a second persistent worker for the same workspace. If you suspect a stale lock, run:

vpd worker stop
vpd worker start --mode persistent --transport polling

3. If A Revised Plan Does Not Appear

Check run detail for the blocked plan node:

• latest worker claim or lease status;
• runtime command delivery;
• plan node output after the revision attempt;
• failure or denial code on the node;
• usage/cost on the revision attempt, when the adapter reports it.

Common causes:

• the worker is offline or paired to the wrong workspace;
• the selected adapter cannot run the plan revision;
• local model credentials are missing;
• the run lost its active claim before the worker fetched commands;
• the platform denied the worker claim after the request-changes decision.

Run:

vpd worker doctor --json

Then move to Runner won't claim work if the doctor shows a claim or capability problem.

4. Safety Invariants

Plan revisions should stay constrained:

• execution mode is plan;
• write and shell tools are not allowed;
• the run remains blocked until the revised plan is approved;
• implementation nodes do not run after request changes;
• plan body redaction must not replace the visible revised plan text for an authorized reviewer.

If any of those are false, treat it as a product bug and include the support packet below.

What To Send Support

Send only sanitized evidence:

• run id and current node key;
• plan id;
• reviewer tag or approver name shown in the UI;
• the exact decision clicked: approve, request changes, or reject;
• vpd worker doctor --json output with tokens removed;
• screenshots of the run detail gate row and revised-plan area;
• denial code or worker error if shown.

Do not send raw model prompts, private repo content, provider tokens, lease tokens, pairing codes, worker private keys, or bootstrap tokens unless your team has explicitly approved that data sharing.