# Wait / watch procedure

Use this procedure for the internal `wait_watch` route after loading the validated
handoff envelope and public routing contract. Resolve command paths using the
package root selected by `dev-loop`. The links identify policy owners; do not preload the full
follow-up, gate or retrospective procedures just to wait.

## Enter the wait

Use the envelope's artifact identity, `nextAction`, `stopRules`, and timeout policy.
The outer wait only observes, refreshes and re-attaches. It never mutates PR, repo,
board or checkpoint state. This read-only route is ownership-exempt and may wait
on work owned by someone else.

Follow the public entrypoint's outer-loop checkpoint reattachment procedure. Use
the checkpoint as context for a fresh detector, never as permission to act on a
stale head. Report the concrete reconciliation problem if facts conflict or a
required helper is unavailable.

| Current boundary | Command / action |
| --- | --- |
| Initial Copilot implementation, no follow-up-ready PR | `node <dev-loops-package-root>/cli/index.mjs loop watch-initial --repo <owner/name> --issue <N>`; preserve the bootstrap budget (its `--timeout <seconds>` accepts `0` or at least `3600`) and exceptions in `FACADE-BOOTSTRAP-WATCH-ROUTE` and its adjacent rules in the public contract. `timed_out` with `outcome: "pending"` means the budget is not exhausted: run `reissue` unchanged per `GATE-EXEC-BOUNDED-WAIT-CAP`. |
| Current PR | Refresh with `node <dev-loops-package-root>/cli/index.mjs loop loop-state --repo <owner/name> --pr <N>` (add `--lightweight` for a light-dispatched PR so the round cap composes correctly). If the refreshed state remains waiting and preflight below is satisfied, use `node <dev-loops-package-root>/cli/index.mjs loop watch-cycle --repo <owner/name> --pr <N> --concise`. |
| Pending/absent CI | The cycle routes to the provider-agnostic CI watcher. The direct equivalent is `node <dev-loops-package-root>/cli/index.mjs loop watch-ci --repo <owner/name> --pr <N> --timeout <remaining-budget-seconds>`. Failed CI needs follow-up, not more waiting. |

Before invoking handoff/watch-cycle, route a newly actionable state through the
fresh-envelope sequence below. If the snapshot reports `mergeStateStatus=BEHIND`
or `DIRTY`, `mergeable=CONFLICTING`, or a new review request is needed, that state
is a transition, not a wait: resolve the fresh envelope and load its destination
`requiredReads` — which pull in the follow-up and operations preflight — before
acting. Do not direct-load those procedures ahead of the envelope. A `DIRTY`/`CONFLICTING` base never enters a CI or review wait
(`FACADE-NEVER-CI-WAIT-WHILE-DIRTY`): the handoff integrates the base or fails
closed first. Preserve ownership, worktree, and authorization checks;
if an authorized route cannot be established, stop for reconciliation. The
handoff owns base-integration and request decisions; obey its stop result. Enter
a review watcher only when it returns
`action: "watch"` and `requestWatchContract.watchEntryConfirmed=true`. The cycle
helper performs this check; do not reconstruct request eligibility or turn a
suppressed/unavailable request into a wait. New-head re-request, green posture,
and round-cap policy remain owned by `COPILOT-FOLLOWUP-REREQUEST-AFTER-PUSH`,
`COPILOT-FOLLOWUP-REREQUEST-GREEN-GATE`, `COPILOT-FOLLOWUP-REQUEST-BRANCHING`, and
`COPILOT-FOLLOWUP-ROUND-CAP` in the [follow-up skill](../copilot-pr-followup/SKILL.md).
The watch result does not independently authorize a fix, gate, ready transition,
or merge.

## Observe, refresh, re-enter

After a watch settles:

1. Refresh authoritative state with `node <dev-loops-package-root>/cli/index.mjs loop loop-state --repo <owner/name> --pr <N>`.
   For `timeout`/`idle`, use `node <dev-loops-package-root>/cli/index.mjs loop handoff --repo <owner/name> --pr <N> --watch-status <status>`
   for the existing timeout refresh. For a light-dispatched PR, pass `--lightweight`
   on these round-cap-consuming refreshes (`loop-state`, `handoff`) so the composed
   lightweight cap is enforced. Bootstrap
   waits re-resolve the issue and its linked PR. Use command `--jq`/`--silent`
   fields or concise output; no inline JSON interpreters.
2. Run `node <dev-loops-package-root>/cli/index.mjs loop startup --pr <N>` (or `--issue <N>` for bootstrap), preserving
   the active run's intent/settings and watch outcome. Build the fresh
   envelope with `node <dev-loops-package-root>/cli/index.mjs loop build-envelope --input <startup-output.json>`;
   validate it before consuming it. A failed resolver or invalid envelope stops
   execution. Keep the same canonical artifact; reuse a newly resolved linked PR.
3. Load the fresh envelope's ordered `requiredReads` before executing its
   `nextAction`. A destination route restores its own ownership, isolation, gate,
   and retrospective requirements. Never enter fixing or approval from the old
   watch envelope. `stop`/`needs_reconcile` remain terminal decision boundaries.
4. For feedback, follow the fresh destination's current-thread capture and fixer
   procedure. Unresolved feedback is not completion.

Preserve the existing [timeout policy](copilot-loop-operations.md#timeout-and-watch-policy):
each review watch boundary has a 30-minute maximum budget; a refresh still showing
`waiting_for_copilot_review` after that budget expires stops with
`watch timeout — PR #<N> needs manual attention`. Do not evade the exhausted
boundary by starting another cycle. An extension requires existing user/conductor
authorization. Quiet observations before exhaustion are healthy waits, not
blockers. The initial-implementation seam retains its separate one-hour budget
and public-contract quiet/activity exceptions. Use explicit bounded timeouts on
direct probes; zero-timeout probes are only for requested one-shot status checks.
The cycle helper supplies its bounded policy internally; do not pass it unsupported
flags such as `--probe-only` or `--poll-interval-ms`. Flag support is command-specific:
`watch-ci` supports `--poll-interval-ms`; `watch-cycle` does not.

The watch-route CLIs accept no local-validation evidence input; a normal refresh
cannot activate the zero-suite `crediblyGreen` exception. Never infer green from
missing CI. A detector result of `none` follows the existing CI wait/reconciliation
policy.

Wait only through the deterministic tools in `COPILOT-FOLLOWUP-WAIT-TOOLS`.
Helper-owned polling is expected; do not create shell sleep/poll loops, detached
watchers, or transcript-tailing automation.

<!-- pi-only -->
Under Pi, a bounded child exits on external wait when `cycleDisposition` is
`pending` and `terminal` is `false`; the main session re-dispatches the same target
when feasible. Carry the checkpoint and watch outcome, and report the pending
boundary accurately rather than declaring completion.
<!-- /pi-only -->

Under Claude Code, the dev-loop coordinator continues pending non-terminal waits in the same agent,
using the fresh envelope on each re-entry, until the requested stop boundary or
budget is reached. Do not exit just to have a parent re-dispatch the watch loop.

Before reporting merge-ready or stopping at the human approval checkpoint, you must complete the pre_approval_gate procedure and verify that a visible clean checkpoint verdict comment exists on the PR for the current head SHA. Do not stop or report completion without this evidence.

## Cross-references

- [Public dev-loop contract](public-dev-loop-contract.md)
- [Follow-up procedure](../copilot-pr-followup/SKILL.md#step-6-async-watch-behavior)
- [Operations reference](copilot-loop-operations.md)
