dev-loops 0.1.0

package/scripts/README.md

@@ -0,0 +1,1007 @@
+# Shared script area
+
+This directory is reserved for deterministic workflow entrypoints.
+
+Scripts here should prefer:
+
+1. native `gh ... watch` support when it matches the exact wait condition,
+2. shared package helpers for pure parsing and state logic,
+3. stable machine-readable JSON output for skills and async workflows.
+
+In this source-loaded workspace repo, root scripts may consume shared package helpers through a thin local adapter rather than a published package import path so the checkout remains runnable without an install step.
+
+## Authority note
+
+For the script surfaces documented here:
+- code, tests, and the helper entrypoints themselves are authoritative for shipped runtime behavior
+- this README summarizes those contracts for operators and maintainers; if behavior changes, update the code/tests and then sync this document
+- use the more specific state-graph and contract docs under `docs/` when a helper family has a narrower machine-readable contract that this README is summarizing
+
+## Scripts
+
+### `scripts/docs/validate-links.mjs`
+
+Validate repo-owned markdown relative links for the shipped docs / skills / agent surface.
+
+Usage:
+- `node scripts/docs/validate-links.mjs`
+
+Optional:
+- `--root <path>` — override the repo root to scan (used by deterministic tests and local dry-runs against another checkout)
+
+Contract:
+- scans these markdown sources only: `README.md`, `PLAN.md`, `AGENTS.md`, `scripts/README.md`, `extension/README.md`, `docs/**/*.md` (excluding `docs/archive/**`), `skills/**/*.md`, and `agents/**/*.md`
+- validates inline relative markdown links after resolving them from the containing file
+- strips any `#fragment` before checking the filesystem
+- treats existing files and directories as valid targets
+- ignores external URLs, `mailto:`, fragment-only links, image links, and links inside fenced code blocks
+- supports a checked-in narrow ignore list through repo-root `.linkcheckignore` for intentional symbolic placeholder targets (for example `docs/phases/phase-x.md`)
+- prints actionable broken-link output with source file, line, raw target, resolved path, and a suggestion only when one clear candidate exists
+
+Failure behavior:
+- exits `0` when all validated links resolve
+- exits `1` when one or more broken links are found
+- exits non-zero (other than `1`) for usage/runtime failures
+
+### `scripts/github/capture-review-threads.mjs`
+
+Capture and normalize PR review-thread JSON.
+
+Supported inputs:
+- `--input <path>`
+- stdin JSON
+- live GitHub capture with `--repo <owner/name> --pr <number>`
+
+Optional:
+- `--output <path>` writes the same success JSON emitted on stdout
+
+Success output shape:
+- `{ "ok": true, "source": { ... }, "summary": { ... }, "threads": [...], "comments": [...] }`
+- normalized `comments[]` preserve both the GraphQL comment node id (`id`) and the REST-safe numeric review-comment id (`databaseId`) when available
+- normalized `threads[]` include `commentDatabaseIds` and `actionableCommentDatabaseIds` so follow-up helpers can pair `--comment-id` and `--thread-id` from the same fresh snapshot
+- when `--output` is used, success output also includes `"outputPath"`
+
+Failure behavior:
+- malformed arguments, invalid JSON, and `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+- live capture is only allowed when both `--repo` and `--pr` are present
+
+### `scripts/github/create-draft-pr.mjs`
+
+Thin wrapper around `gh pr create` for draft-first PR creation.
+
+Usage:
+- `node scripts/github/create-draft-pr.mjs [gh pr create args...]`
+- `node <resolved-skill-scripts>/github/create-draft-pr.mjs [gh pr create args...]`
+
+Contract:
+- injects exactly one `--draft` when the caller did not already supply it
+- rejects `--ready` before invoking `gh`; use `gh pr ready` later after draft-gate approval
+- forwards every other argument to `gh pr create` unchanged and in order
+- preserves the underlying `gh pr create` stdout, stderr, and exit code without wrapping success output
+- stays intentionally narrow: this is the prevention layer for draft-first creation, while `scripts/github/reconcile-draft-gate.mjs` remains the separate recovery path for already-open non-draft PRs
+
+Failure behavior:
+- wrapper-owned validation failures emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- when `gh pr create` itself exits non-zero, this wrapper preserves the original stdout/stderr and propagates the same exit code
+
+### `scripts/github/request-copilot-review.mjs`
+
+Request Copilot review on a PR and verify the request deterministically.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--force-rerequest-review` — bypass the round cap when new commits exist since the last Copilot review. Refused with `no_changes_since_last_review` when the PR head has not changed since the last review. No-op when the round cap has not been reached. Normal requests now automatically re-open at round cap when the head changed, all prior feedback is resolved, and current GitHub CI is green.
+
+Contract:
+- checks `requested_reviewers` first so an existing Copilot request is detected without mutating PR state again
+- requests Copilot via `gh pr edit <pr> --repo <owner/name> --add-reviewer @copilot`
+- is suitable both for the first request after ready-for-review and for later explicit re-requests after follow-up fix commits land on the PR head
+- enforces a round cap (default: 5, configurable via `maxCopilotRounds` in settings); clean round-cap PRs with new commits, resolved threads, and green current GitHub CI automatically re-open for a normal re-request, while `--force-rerequest-review` remains the operator override for other new-commit cases
+- should be paired with a fresh unresolved-thread check after Copilot posts again; requesting review alone does not complete the loop
+- verifies the result through `gh api repos/<owner>/<name>/pulls/<pr>/requested_reviewers`
+- does **not** rely on `gh pr view --json reviewRequests`, which can be incomplete for Copilot reviewer state
+- normalizes known repository/tooling limitations into a machine-readable `unavailable` result instead of forcing callers to parse ad hoc stderr
+
+Success output shape:
+- `{ "ok": true, "status": "requested"|"already-requested"|"unavailable"|"suppressed_same_head_clean"|"blocked_by_copilot_comment"|"round_cap_reached"|"no_changes_since_last_review"|"suppressed_draft", "repo": "owner/name", "pr": 17, "reviewer": "Copilot", ... }`
+- `unavailable` also includes a `detail` string with the normalized GitHub/CLI limitation
+- `round_cap_reached` includes `completedRounds` and `maxRounds` fields
+- `no_changes_since_last_review` is returned by `--force-rerequest-review` when the PR head SHA has not changed since the last Copilot review
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/detect-linked-issue-pr.mjs`
+
+Detect whether an issue already has an open linked PR in the same repository.
+
+Required:
+- `--repo <owner/name>`
+- `--issue <number>`
+
+Contract:
+- queries issue timeline linked-PR events (`CONNECTED_EVENT`, `CROSS_REFERENCED_EVENT`)
+- pages through timeline items until `hasNextPage=false`
+- keeps only open linked PRs in the same repository (`repository.nameWithOwner === <repo>`)
+- also tracks closed-unmerged (state=`CLOSED`) same-repo linked PRs separately
+- chooses deterministically when multiple candidates remain:
+  1. prefer `CONNECTED_EVENT` candidates over `CROSS_REFERENCED_EVENT`
+  2. then choose newest linked-event `createdAt`
+  3. then stable fallback by PR number/url
+- returns a machine-readable selection payload for skills/workflows; callers should not re-implement query/pagination/tie-break logic in markdown policy text
+
+Success output shape:
+- when `hasOpenLinkedPr: true`: `{ "ok": true, "repo": "owner/name", "issue": 85, "hasOpenLinkedPr": true, "prNumber": 90, "prUrl": "...", "selection": { "eventType": "...", "eventCreatedAt": "..." } }`
+- when `hasOpenLinkedPr: false`: `{ "ok": true, "repo": "owner/name", "issue": 85, "hasOpenLinkedPr": false, "prNumber": null, "prUrl": null, "hasPriorClosedUnmergedPr": true|false, "priorClosedUnmergedPrNumber": 149|null, "priorClosedUnmergedPrUrl": "..."|null }`
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/resolve-tracker-local-spec.mjs`
+
+Resolve the canonical spec bundle for tracker-backed local implementation from one
+GitHub issue reference. This is the bounded GitHub-backed path for tracker-backed
+local spec resolution; it does not create or read `docs/phases/phase-<n>.md`.
+
+Allowed inputs:
+- `--repo <owner/name>` with `--issue <number>`
+- `--issue-url <github issue url>`
+
+Contract:
+- deterministically resolves exactly one repo slug + issue number pair
+- reads the GitHub issue via `gh issue view <number> --repo <owner/name> --json number,title,body,url,state`
+- treats the issue as canonical for tracker-backed local sessions
+- always reports `localPhaseDocAllowed: false` so callers do not silently maintain a duplicate local phase doc for the same session
+- leaves full tracker-sync policy to higher-level callers; this helper's bounded responsibility is spec resolution only
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/name", "issue": 85, "issueUrl": "...", "state": "OPEN"|"CLOSED", "title": "...", "body": "...", "canonicalSpecSource": "tracker_issue", "localImplementationMode": "tracker_backed", "localPhaseDocAllowed": false, "stateSync": "tracker_issue_is_canonical" }`
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- unexpected `gh` failures and malformed `gh` JSON emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/manage-sub-issues.mjs`
+
+Deterministic helper for reading, linking, ordering, and verifying GitHub sub-issue trees.
+Use this for epic/umbrella issue decomposition. See [Sub-Issue Tree Contract](../docs/sub-issue-tree-contract.md) for the full workflow.
+
+Commands:
+- `list` — list sub-issues of a parent issue in tree order
+- `add` — attach a child issue to a parent as a real GitHub sub-issue
+- `reorder` — set the execution order of sub-issues (highest priority first)
+- `verify` — verify that the current sub-issue tree matches an expected set (and optionally order)
+
+Required for all commands:
+- `--repo <owner/name>`
+- `--issue <number>` (parent issue)
+
+`add` adds: `--child <number>`
+`reorder` adds: `--order <n1,n2,...>` (comma-separated issue numbers in desired execution order)
+`verify` adds: `--expected <n1,n2,...>` and optional `--ordered` flag
+
+Contract:
+- `add` resolves the child issue's internal GitHub id before calling the sub-issues REST endpoint
+- `reorder` first lists current sub-issues to validate all specified numbers are already in the tree, then issues sequential priority-update API calls
+- `verify` is read-only and exits 0 for mismatch-only results; `"verified": false` is a machine-readable signal, not a process failure. Argument errors and unexpected `gh`/runtime failures still exit non-zero
+- do not re-implement sub-issue management ad hoc or bypass this helper
+
+Success output shapes:
+- `list`: `{ "ok": true, "repo": "owner/name", "issue": N, "command": "list", "subIssues": [{ "number": M, "title": "...", "state": "...", "id": ID }, ...] }`
+- `add`: `{ "ok": true, "repo": "owner/name", "issue": N, "command": "add", "child": M }`
+- `reorder`: `{ "ok": true, "repo": "owner/name", "issue": N, "command": "reorder", "order": [n1, n2, ...] }`
+- `verify`: `{ "ok": true, ..., "command": "verify", "verified": true|false, "expected": [...], "actual": [...], "missing": [...], "unexpected": [...] }` (plus `"orderMismatch": true` when `--ordered` and only the order differs)
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+- argument errors also include `"usage"` in the error payload
+
+### `scripts/refine/verify.mjs`
+
+Verify epic-tree refinement structure and contracts in one pass.
+
+Usage:
+- `node scripts/refine/verify.mjs --issue <number> [--repo <owner/name>] [--json]`
+- `node scripts/refine/verify.mjs --input <path> [--json]`
+
+Contract:
+- runs four deterministic checkers:
+  - `prose-linkage-detector` (forbidden prose parent/child/dependency markers + missing API links)
+  - `scope-boundary-cross-checker` (mutual-exclusion gaps + duplicate sibling ownership)
+  - `refinement-completeness-checker` (AC/DoD/non-goals/matrix presence)
+  - `tree-integrity-validator` (parent links, orphan detection, cycles, max depth 3)
+- online mode (`--issue`) walks GitHub sub-issues API from the root issue
+- offline mode (`--input`) validates a local refinement tree JSON snapshot
+- default output is human-readable text; `--json` emits machine-readable output for CI
+
+Failure behavior:
+- checker findings are process-failing (`exit 1`) because verification did not pass
+- malformed arguments and runtime errors emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/stage-reviewer-draft.mjs`
+
+Stage a pending reviewer-side draft review from a merged deterministic review package.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+- `--review-file <path>`
+
+Optional:
+- `--local-state-output <path>` writes/merges deterministic draft-review metadata for later
+  `detect-reviewer-loop-state.mjs --local-state` use
+
+Contract:
+- reads a merged reviewer result JSON file (for example output derived from `mergeReviewerResults`)
+- builds a deterministic pending-review payload pinned to the review package `headSha`
+- posts the pending review to `repos/<owner>/<name>/pulls/<pr>/reviews` without an `event` field so GitHub keeps it pending
+- returns the draft review id/url/commit sha
+- optionally writes bounded local reviewer-loop metadata including `draftReviewPosted`, `draftReviewId`, `draftReviewUrl`, `draftReviewCommitSha`, and `draftReviewNotificationStatus`
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/name", "pr": 17, "reviewId": 456, "reviewUrl": "...", "reviewState": "PENDING", "commitSha": "abc123", "localStatePath": "..."|null }`
+
+Failure behavior:
+- malformed arguments, invalid review JSON, missing `headSha`, unexpected `gh` failures, and malformed review-create responses emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/reply-resolve-review-thread.mjs`
+
+Reply to a PR review comment and resolve the associated review thread deterministically.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+- `--comment-id <number>`
+- `--thread-id <node-id>`
+- `--body-file <path>`
+
+Contract:
+- reads the reply body from a file so shell quoting does not become part of the workflow logic
+- validates the live PR thread snapshot before mutating GitHub so `--comment-id` and `--thread-id` must refer to the same thread on the target PR
+- posts the reply to `repos/<owner>/<name>/pulls/<pr>/comments/<comment-id>/replies`
+- resolves the thread with the GraphQL `resolveReviewThread` mutation
+- fails if the thread does not report resolved after the mutation
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/name", "pr": 17, "commentId": 123, "threadId": "...", "replyId": 456, "replyUrl": "...", "resolved": true }`
+
+Failure behavior:
+- malformed arguments, empty body files, missing threads, missing comments, comment/thread mismatches, unexpected `gh` failures, and unsuccessful resolve responses emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/reply-resolve-review-threads.mjs`
+
+Reply to all matching unresolved review threads on one PR and optionally resolve them with one bounded note.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--author <login>` (default `Copilot`)
+- exactly one message source: `--message <text>` or stdin
+- `--resolve`
+
+Contract:
+- captures one authoritative review-thread snapshot via `capture-review-threads.mjs`
+- filters to unresolved threads containing at least one comment by the selected author
+- chooses the newest matching author-authored comment in each matched thread as the REST reply target
+- processes matched threads sequentially in deterministic snapshot order
+- reuses the shared single-thread reply/resolve primitives instead of duplicating GitHub mutation logic
+- with `--resolve`, re-captures the review-thread snapshot at the end and fails closed if any targeted thread remains unresolved
+- zero-match runs are deterministic no-ops with success JSON
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/name", "pr": 17, "author": "Copilot", "resolve": true|false, "matchedThreadCount": 2, "repliedThreadCount": 2, "resolvedThreadCount": 2, "skippedThreadCount": 1, "results": [{ "threadId": "...", "commentId": 123, "replyId": 456, "replyUrl": "...", "resolved": true }] }`
+
+Failure behavior:
+- malformed arguments, empty/conflicting message input, malformed thread snapshots, unexpected `gh` failures, reply failures, resolve failures, and failed post-resolve verification emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+- when partial progress exists, stderr JSON also includes `partialProgress`
+
+For new GitHub mutation helpers in this repo, do not stop at fixture-only confidence when a real PR is available and mutation is authorized. Run a bounded real-PR smoke check before depending on the helper inside a longer async review/fix loop.
+
+### `scripts/github/probe-copilot-review.mjs`
+
+Watch for fresh Copilot-authored review activity on a PR.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--poll-interval-ms <positive-integer>` (default `60000`, i.e. 1 minute)
+- `--timeout-ms <non-negative-integer>` (default `1800000`, i.e. 30 minutes)
+
+Contract:
+- captures a baseline snapshot, then performs a bounded number of follow-up polls
+- returns `changed` for any fresh Copilot-authored review-thread comments, PR review summaries, or PR issue comments that were not present in the baseline snapshot
+- ignores fresh non-Copilot review activity across those same surfaces
+- `--timeout-ms 0` performs a single immediate recheck and returns `idle` if unchanged
+
+Success output shape:
+- `{ "ok": true, "status": "changed"|"timeout"|"idle", "repo": "owner/name", "pr": 17, "attempts": 1, "newComments": [...], "newReviews": [...], "newIssueComments": [...] }`
+
+Failure behavior:
+- malformed arguments and `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/detect-initial-copilot-pr-state.mjs`
+
+Detect the post-assignment issue-to-linked-PR seam for Copilot handoff.
+
+Required:
+- `--repo <owner/name>`
+- `--issue <number>`
+
+Contract:
+- uses `scripts/github/detect-linked-issue-pr.mjs` as the authoritative linked-PR selector
+- returns exactly one deterministic state:
+  - `no_linked_pr`
+  - `prior_linked_pr_closed_unmerged`
+  - `copilot_session_active`
+  - `waiting_for_initial_copilot_implementation`
+  - `linked_pr_ready_for_followup`
+- uses `scripts/loop/detect-copilot-session-activity.mjs` on the linked PR head branch for Copilot-authored draft PRs
+- while `activity=active`, emits `copilot_session_active` regardless of commit/file-count heuristics
+- approval-gated `action_required` Copilot/Actions runs are treated as observational (non-active) for this bootstrap seam
+- for non-bootstrap linked PRs, falls back to the existing substantive PR heuristics when session activity is `idle` or `concluded`
+- if the session-activity check itself fails, the helper fails closed instead of pretending session state was unavailable
+- classifies `prior_linked_pr_closed_unmerged` when there is no open linked PR but a same-repo linked PR was previously closed without merging; this is a terminal non-wait state requiring human reconciliation
+- classifies `waiting_for_initial_copilot_implementation` only for the bounded bootstrap-only draft shape:
+  - open same-repo linked PR
+  - draft
+  - Copilot-authored (`Copilot`, `copilot-swe-agent`, `app/copilot-swe-agent`, or `copilot-swe-agent[bot]`)
+  - exactly 1 commit
+  - sole commit headline exactly `Initial plan`
+  - exactly 0 changed files
+- fails closed with explicit error output when required PR facts cannot be fetched
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/name", "issue": 59, "state": "...", "prNumber": 79|null, "prUrl": "..."|null, "headBranch": "..."|null, "authorLogin": "Copilot"|null, "isDraft": true|false|null, "changedFiles": 0|null, "commitCount": 1|null, "soleCommitHeadline": "Initial plan"|null, "sessionActivity": "active"|"concluded"|"idle"|null, "sessionRunId": 123|null, "sessionRunName": "..."|null, "sessionRunStatus": "..."|null, "sessionRunConclusion": string|null, "sessionRunCreatedAt": "..."|null, "sessionConfidence": "high"|null }`
+
+### `scripts/loop/run-conductor-cycle.mjs`
+
+Poll all open PRs, detect gate state, and emit an ordered action queue.
+
+Output `actions[]` entries include:
+- `requiresSubagent`
+- `requiresApproval`
+- `handoffContract` with:
+  - `ownership`
+  - `stopBoundary`
+  - `resumePolicy`
+
+The handoff contract is recorded on each action so parent, child, and resume
+actions can share one explicit stop/resume boundary.
+
+Contract values:
+- `ownership`: `subagent`, `parent`, `human`, or `terminal`
+- `stopBoundary`: `subagent_exit`, `watch_boundary`, `approval_boundary`,
+  `merge_boundary`, `conflict_boundary`, or `terminal_boundary`
+- `resumePolicy`: `resume_after_subagent_exit`,
+  `resume_after_state_refresh`, `resume_after_human_approval`,
+  `resume_after_merge_authorization`, `manual_attention`, or `none`
+
+`run-conductor-cycle.mjs` emits the contract-boundary values above. The parser
+also accepts `PR_CHECKPOINT` values when reading recorded artifacts so older
+recorded handoff notes can still be validated fail-closed.
+
+### `scripts/loop/conductor-monitor.mjs`
+
+Aggregate the current Copilot-loop status for every open PR in one repository.
+
+Required:
+- `--repo <owner/name>`
+
+Optional:
+- `--auto-resume` — inspect documented pi-subagents async/session artifacts on disk, detect orphaned open PR follow-up runs, and emit deterministic resume plans without executing `subagent({ action: "resume" })`
+
+Contract:
+- lists all open PRs via `gh pr list --state open --limit 1000` to avoid GitHub CLI default truncation
+- reuses `detect-copilot-loop-state.mjs` logic for each PR instead of inventing a second state classifier
+- reports one queue-level summary with per-PR loop state, next action, and whether human follow-up is needed now
+- reports `queue_complete` when the open-PR queue is empty
+- keeps the current implementation human-in-the-loop; fully autonomous monitor ownership is a follow-up slice
+- when `--auto-resume` is present, scans documented async evidence sources only:
+  - pi-subagents async run dirs under `<tmpdir>/pi-subagents-*/async-subagent-runs/<runId>/`
+    (`status.json`, `events.jsonl`, `output-<n>.log`)
+  - pi-subagents async result artifacts under
+    `<tmpdir>/pi-subagents-*/async-subagent-results/`
+  - persisted session/subagent artifacts under the Pi sessions tree (for example
+    `~/.pi/agent/sessions/.../subagent-artifacts/*_dev-loop_*_meta.json` and
+    `~/.pi/agent/sessions/.../subagent-artifacts/*_dev-loop_*_output.md`
+    plus matching `run-<n>/session.jsonl` files)
+- ignores non-`dev-loop` agents, other repositories, merged PRs, and any exited run superseded by a newer matching `running` or `queued` run
+- matches exited runs to open PRs only by PR number parsed from artifact text; branch names, issue numbers, or worktree paths alone are never sufficient identity
+- fail-closes to `needsManualAttention` when PR identity, artifact state, or resume inputs are missing, contradictory, or ambiguous
+- `--auto-resume` remains single-shot only; it does not poll, sleep, watch, or execute the resume itself
+
+Success output shape:
+- default:
+  - `{ "ok": true, "repo": "owner/name", "checkedAt": "...", "prCount": 2, "queueStatus": "queue_complete"|"monitoring"|"attention_needed", "needsAttentionCount": 0, "summary": { "waiting": 0, "needsAttention": 0, "blocked": 0, "done": 0 }, "prs": [...] }`
+- with `--auto-resume`:
+  - adds
+    `{ "autoResumeRequested": true, "orphanedPrCount": 1, "resumePlanCount": 1, "manualAttentionCount": 0, "resumePlans": [...], "needsManualAttention": [...] }`
+
+`resumePlans[]` fields:
+- `pr`
+- `runId`
+- `runState` (`completed` | `failed` | `paused`)
+- `artifactPath`
+- `sessionPath` when known
+- `parsedArtifactState`
+- `parsedLoopState`
+- `livePrState`
+- `resumeAction`
+- `handoffContract`
+- `recordedHandoffContract` when the artifact explicitly records one
+- `resumeMessage`
+- `resumeCommandPreview`
+- `staleWorktree`
+
+If a recorded handoff contract is present, it must include explicit
+`Handoff ownership`, `Stop boundary`, and `Resume policy` lines. The monitor
+fails closed when those fields are partial, invalid, or conflict with the
+live-derived resume plan.
+
+`needsManualAttention[]` fields:
+- `pr` when known
+- `runId` when known
+- `reason`
+- `evidence`
+- `suggestedNextStep`
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/detect-copilot-session-activity.mjs`
+
+Detect deterministic Copilot workflow session activity on a branch.
+
+Required:
+- `--repo <owner/name>`
+- `--branch <name>`
+
+Optional:
+- `--limit <positive-integer>` (default `20`)
+
+Contract:
+- uses `gh run list --branch <branch>` as the primary signal
+- pattern-matches known Copilot run names (`Copilot coding for issue`, `Addressing comment on PR`, `Addressing review on PR`)
+- classifies activity as:
+  - `active` when a matching run is currently in progress
+  - `concluded` when the most recent matching run is completed
+  - `concluded` (non-blocking observational) when a matching run is approval-gated in `action_required`; the payload still preserves the raw `runStatus` / `runConclusion` strings for debugging
+  - `idle` when no matching runs are found
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/copilot-pr-handoff.mjs`
+
+Thin high-level helper for the common Copilot PR follow-up handoff path.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--watch-status <changed|timeout|idle>` — refresh deterministic state after a prior watcher observation; this readback mode never requests review again
+
+Contract:
+- this helper is the source of truth for normal request/re-request/watch routing on Copilot PR follow-up
+- emits deterministic `action` + `nextAction` + `reviewRequestStatus` and a helper-owned `requestWatchContract` envelope for status interpretation
+- enters watch only when request state is confirmed (`requested` or `already-requested`) and emits exact `watchArgs` + `watchTimeoutPolicy`
+- watch refresh (`--watch-status`) is observational-only; rely on refreshed `loopDisposition` + `terminal` to decide whether to continue or stop
+- explicit stop/blocked routing is machine-readable via `action: "stop"` plus `requestWatchContract.stopState`
+- when `PI_SUBAGENT_RUN_ID` is set to a non-empty value, the helper enforces one-runner-per-PR ownership and returns `runnerOwnership` details when a conflicting or displaced run must stop
+
+Success output shape:
+- `{ "ok": true, "action": "watch"|"fix"|"stop", "state": "...", "allowedTransitions": [...], "nextAction": "...", "snapshot": {...}, "reviewRequestStatus"?: "...", "watchStatus"?: "...", "autoRerequestEligible": true|false, "sameHeadCleanConverged": true|false, "loopDisposition": "...", "terminal": true|false, "requestWatchContract": { "action": "...", "nextAction": "...", "requestStatus": "requested"|"already-requested"|"unavailable"|"failed"|"none", "routingState": "copilot_request_confirmed_waiting"|"ready_state_needs_copilot_request"|"draft_reset_requires_ready_state_reentry"|"non_ready_state", "watchEntryConfirmed": true|false, "watchArgs": { ... }|null, "stopState"?: "unavailable"|"blocked"|"draft_requires_ready_state_reentry"|"no_automatic_next_step" }, "watchTimeoutPolicy"?: { "classification": "external_healthy_wait", "minimumTimeoutMs": 1800000, "defaultTimeoutMs": 1800000 }, "watchArgs"?: { ... } }`
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/pr-runner-coordination.mjs`
+
+Durable one-runner-per-PR coordination helper.
+
+Subcommands:
+- `status` — inspect current ownership record for one PR
+- `claim` — claim ownership when no active runner exists; otherwise fail closed with machine-readable conflict details
+- `takeover` — explicit replacement path that records prior/new run ids
+- `assert` — verify the current run still owns the PR; `--require-existing` fails closed when async pre-merge ownership proof is missing
+- `release` — clear ownership when the active run is done
+
+State path:
+- `.pi/runner-coordination/<owner>/<repo>/pr-<number>.json`
+- this is local coordination state under `.pi/`; keep it uncommitted like other repo-local runtime artifacts
+
+Integration notes:
+- `copilot-pr-handoff.mjs` uses this surface for async run ownership checks
+- `detect-checkpoint-evidence.mjs` uses strict ownership assertion before async merge-time gate evaluation
+
+### `scripts/loop/run-watch-cycle.mjs`
+
+Deterministic handoff → watch helper for one Copilot wait-cycle boundary.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--probe-only` — use a single immediate recheck (`timeoutMs: 0`) for explicit status probes only
+
+Contract:
+- runs `copilot-pr-handoff.mjs` first and preserves its current state / next action / watch args
+- when handoff stays in watch mode, checks Copilot session activity on the PR head branch via `detect-copilot-session-activity.mjs`
+- when activity is `active`, blocks on `gh run watch <run-id>` and then continues with the same emitted persistent watch budget instead of silently degrading to a zero-timeout probe
+- when handoff returns `action: "watch"`, runs `probe-copilot-review.mjs` with the emitted `watchArgs`; zero-timeout probes are reserved for explicit `--probe-only` status checks
+- treats `waiting_for_copilot_review` as a persistence boundary, not a completion boundary
+- for explicit async loop entry/continuation, `cycleDisposition: "pending"` with `terminal: false` means stay attached and run another watch boundary rather than exiting as clean success
+- after a follow-up fix / reply-resolve / re-request path returns to `waiting_for_copilot_review`, resume this helper again instead of treating the re-request handoff as completion
+- handoff-only behavior must be explicitly requested; do not silently reinterpret async loop entry as one-step transition behavior
+- preserves the shared Copilot-loop `loopDisposition` contract from the handoff/state-machine output (`pending`, `unresolved_feedback`, `clean_converged`, `blocked`, `action_required`, `done`)
+- exposes the helper's coarser wait-cycle summary separately as `cycleDisposition`
+- reports `cycleDisposition: "pending"` for quiet watch results (`timeout` or explicit probe `idle`) instead of pretending the loop concluded cleanly
+- reserves zero-timeout `idle` probes for explicit status/reattach checks; normal async waiting should use the emitted non-zero watch timeout
+- returns `cycleDisposition: "needs_followup"` when fresh Copilot activity appears or handoff already routed directly to `fix`
+- returns `cycleDisposition: "terminal"` only when handoff routed to `stop`
+
+Success output shape:
+- `{ "ok": true, "handoffAction": "watch"|"fix"|"stop", "state": "...", "allowedTransitions": [...], "nextAction": "...", "snapshot": {...}, "reviewRequestStatus"?: "...", "watchArgs"?: { ... }, "watchTimeoutPolicy"?: { "classification": "external_healthy_wait", "minimumTimeoutMs": 1800000, "defaultTimeoutMs": 1800000 }, "watchStatus"?: "changed"|"timeout"|"idle", "watch"?: { ... }, "loopDisposition": "pending"|"unresolved_feedback"|"clean_converged"|"blocked"|"action_required"|"done", "cycleDisposition": "pending"|"needs_followup"|"terminal", "terminal": true|false }`
+
+Failure behavior:
+- malformed arguments and unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/detect-copilot-loop-state.mjs`
+
+Deterministic Copilot-loop state detector. Captures current loop state from observable PR/GitHub
+facts and interprets the snapshot into one explicit current state, allowed next transitions, and
+a recommended next action. This script is the orchestration authority for the async Copilot
+review/fix loop; see [Copilot Loop State Graph](../docs/copilot-loop-state-graph.md) for the full state-graph design.
+
+Two modes:
+
+- **Auto-detect**: `--repo <owner/name> --pr <number>`
+  Fetches PR state, Copilot review request status, review threads, and CI checks from GitHub,
+  builds a snapshot, and interprets it. PR CI/check normalization is owned by
+  [Copilot CI Status Contract](../skills/docs/copilot-ci-status-contract.md).
+
+- **Snapshot interpretation**: `--input <path>`
+  Reads a pre-built snapshot JSON and interprets it without any `gh` calls. Use this mode when
+  the caller has already gathered facts — for example, to incorporate the `status` field from a
+  prior `scripts/github/request-copilot-review.mjs` run, which can report `unavailable` or
+  `failed` statuses that are not observable from static GitHub state alone.
+
+Optional (auto-detect mode only):
+- `--steering-state-file <path>`
+  Overlay the detected state with the current persisted steering contract state.
+  The detector stays read-only: it does not promote queued steering or write the
+  steering file. This is available only in `--repo/--pr` mode; snapshot `--input`
+  mode does not accept steering files because repo/pr target identity cannot be
+  proven from the snapshot alone.
+- `--review-request-status <requested|already-requested|unavailable|none|failed>`
+  Override the Copilot review-request status with a known prior result. Skips the
+  `requested_reviewers` API call and injects the provided value directly into the snapshot.
+  Use when the caller already ran `request-copilot-review.mjs` and wants to inject its output
+  status without re-probing the reviewers endpoint.
+
+Snapshot schema (`--input` mode or `snapshot` field in success output):
+- `prExists` {boolean} — whether a PR was found
+- `prNumber` {number|null} — PR number if prExists, otherwise null
+- `prDraft` {boolean} — whether the PR is in draft state
+- `prMerged` {boolean} — whether the PR has been merged
+- `prClosed` {boolean} — whether the PR was closed without merge; merged PRs set `prMerged=true` instead of reusing `prClosed`
+- `copilotReviewRequestStatus` {"requested"|"already-requested"|"unavailable"|"none"|"failed"} — current known Copilot review-request state
+- `copilotReviewPresent` {boolean} — whether at least one Copilot review exists on the PR
+- `copilotReviewOnCurrentHead` {boolean} — whether a submitted (non-PENDING) Copilot review exists for the current head commit
+- `unresolvedThreadCount` {number} — total unresolved review-thread count
+- `actionableThreadCount` {number} — unresolved threads with non-bot actionable comments
+- `copilotReviewRoundCount` {number} — completed Copilot review rounds observed on the PR
+- `ciStatus` {"success"|"failure"|"pending"|"none"} — contract-owned current-head CI/check rollup
+  from [Copilot CI Status Contract](../skills/docs/copilot-ci-status-contract.md); `none` means no usable readiness signal yet
+- `agentFixStatus` {"applied"|null} — agent-provided: "applied" when code has been fixed
+
+Success output shape:
+- `{ "ok": true, "snapshot": { ... }, "state": "...", "allowedTransitions": [...], "nextAction": "...", "autoRerequestEligible": true|false, "sameHeadCleanConverged": true|false, "loopDisposition": "...", "terminal": true|false }`
+- `state` is one of the stable state names defined in [Copilot Loop State Graph](../docs/copilot-loop-state-graph.md)
+- `allowedTransitions` is the list of states reachable from `state`
+- `nextAction` is a human-readable recommended next step
+- `autoRerequestEligible` is `true` only when a meaningful remediation event has made automatic re-request valid again
+- `sameHeadCleanConverged` is `true` when the current head has clean convergence (a submitted Copilot review, zero unresolved and actionable threads, and CI not blocked), suppressing automatic same-head re-request
+- `loopDisposition` is the high-level refreshed classification: `pending`, `unresolved_feedback`, `clean_converged`, `blocked`, `action_required`, or `done`
+- `terminal` is `true` only for clean-converged, blocked, or done states; watcher timeout/idle must be treated as non-terminal until a refreshed detector output proves `terminal=true`
+
+Failure behavior:
+- Malformed arguments, unexpected `gh` failures, and review-thread detection failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+Key behavioral guarantees:
+- When `unresolvedThreadCount > 0`, the state is always in the fix/reply-resolve family — never `waiting_for_copilot_review` or any wait state
+- When `copilotReviewRequestStatus` is `unavailable` or `failed`, the state is a terminal stop/report state with no allowed transitions
+- When `agentFixStatus` is `"applied"` and unresolved threads exist, the state is `already_fixed_needs_reply_resolve`, and `allowedTransitions` includes only `ready_to_rerequest_review`
+- When the current head has clean convergence (a submitted Copilot review, zero unresolved and actionable threads, and CI not blocked), automatic same-head re-request is suppressed until a meaningful remediation event occurs
+- If review-thread state cannot be determined during auto-detect, the script fails closed instead of assuming zero unresolved threads
+- When `--steering-state-file` is provided, steering is surfaced as a read-only overlay;
+  queued steering promotion/persistence is owned explicitly by `steer-loop.mjs promote`
+
+### `scripts/github/upsert-checkpoint-verdict.mjs`
+
+Creates or updates the visible gate-review PR comment for one `gate + headSha` pair.
+Use this at the `draft_gate` / `pre_approval_gate` boundaries so same-head reruns
+remain idempotent: the helper updates an existing same-head marker in place when
+correction is needed and suppresses duplicate reposts when the visible comment
+already matches the requested contract fields. The rendered visible comment uses compact readable labels (`Gate review`, `Reviewed head SHA`, `Verdict`, `Findings summary`, `Next action`). When a gate pass needed corrective changes before reaching `clean`, pass a truthful `--findings-summary` that briefly states the gap, the change, and why the current head is now acceptable instead of defaulting to `no issues found`. Verbose multiline `--findings-summary` input is compacted before posting so visible gate comments keep validation reporting bounded: raw passing output is omitted, command/count/CI signals are preferred, and any failure excerpt uses a deterministic retained-prefix limit plus a short truncation marker suffix when needed.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+- `--gate <draft_gate|pre_approval_gate>`
+- `--head-sha <sha>` — full current head SHA or a hexadecimal prefix of it; the helper canonicalizes to the full current head before comparing/updating visible markers
+- `--verdict <clean|findings_present|blocked>`
+- `--findings-summary <text>`
+- `--next-action <text>`
+
+Optional:
+- `--local-validation-head-sha <sha>` — reuse the bounded `crediblyGreen` exception when GitHub created zero current-head suites/statuses and local verification already passed for that exact head
+- `--force --force-reason <text>` — narrow operator-authorized CI override for the helper-local gate-entry refusal only; `--force-reason` is required with `--force`, `--force-reason` without `--force` is rejected, and the reason text is whitespace-normalized for machine-readable output
+
+Success output shape:
+- standard path: `{ "ok": true, "action": "created"|"updated"|"noop", "repo": "owner/repo", "pr": 17, "gate": "draft_gate", "headSha": "abc1234", "currentHeadSha": "abc1234", "commentId": 101, "commentUrl": "https://github.com/owner/repo/pull/17#issuecomment-101" }`
+- forced CI-override path: the same shape plus `{ "forced": true, "forceReason": "CI failed due to transient infrastructure", "forceBypass": "ci_blocked_needs_user_decision" }`
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- contradictory head-SHA requests or unexpected `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+- gate upserts still fail closed when `detect-pr-gate-coordination-state.mjs` reports that the requested gate action is illegal for the current head
+- when that refusal is specifically `lifecycleState=blocked_needs_user_decision` plus current-head `ciStatus="failure"`, the unforced error now points operators to `--force --force-reason` as the explicit CI-only escape hatch
+- `--force` does **not** bypass stale-head protection, non-draft `draft_gate` refusal, unresolved-feedback / unsettled-review `pre_approval_gate` refusal, merge-conflict handling, or closed/merged PR protection
+
+Use `--force` only after the user explicitly authorizes ignoring the current-head CI failure for this one gate-comment upsert. Prefer the normal paths first: green current-head CI, `--local-validation-head-sha` for the bounded `crediblyGreen` case, or the draft-gate policy knob from issue #351 when the desired behavior is a durable draft-gate policy rather than a one-off override.
+
+### `scripts/loop/run-refinement-audit.mjs`
+
+Runs one deterministic bounded refinement audit over explicit repo paths and emits one machine-readable planning artifact.
+Use this before refiner fan-out when a local phase or GitHub issue would benefit from scoped slop-risk discovery.
+
+Required:
+- exactly one of:
+  - `--paths <comma-separated path list>`
+  - `--paths-file <file>`
+
+Optional:
+- `--root <path>` — override the repo root (defaults to `git rev-parse --show-toplevel`)
+- `--max-lines <n>` — oversized-file threshold (default `1000`)
+- `--duplicate-window-lines <n>` — duplicate-block window size (default `4`)
+- `--branch-threshold <n>` — branching-hotspot threshold (default `25` control-flow tokens)
+- `--thin-wrapper-max-lines <n>` — thin-wrapper threshold (default `40`)
+- `--output <path>` — writes the same success JSON emitted on stdout
+
+Success output shape:
+- `{ "ok": true, "repoRoot": "/repo", "paths": ["AGENTS.md"], "auditedFiles": [...], "findings": [...], "highestValueFollowUpCandidates": [...], "scopeBoundary": { "mode": "bounded_paths_only", "fullRepoScan": false } }`
+- `auditedFiles[]` reports per-file line count, branch-token count, duplicate-block match count, thin-wrapper classification, and deterministic skip notes for binary/unreadable files
+- `findings[]` uses bounded heuristic ids: `oversized_file`, `duplicate_block_candidate`, `branching_hotspot`, `thin_wrapper_candidate`
+- `highestValueFollowUpCandidates[]` is the concise planning handoff surface for refiner fan-out/fan-in; findings are planning inputs, not auto-authorized rewrites
+
+Failure behavior:
+- malformed arguments, blank paths, invalid thresholds, unreadable `--paths-file` input, or zero auditable files after tracked-file expansion emit `{ "ok": false, "error": "...", ... }` on stderr and exit non-zero
+- findings do **not** fail the process; findings return exit `0`
+- `--paths*` is required; the helper never silently scans the whole repo
+
+### `scripts/loop/detect-pr-gate-coordination-state.mjs`
+
+Fetches the live PR facts needed to answer which gate/transition is legal next for a pull request. It combines the shared Copilot loop-state machine with visible `draft_gate` / `pre_approval_gate` evidence, GitHub `mergeStateStatus`, and local `git -c core.quotepath=false status --porcelain=v1 -z --untracked-files=no` conflict detection, then emits one explicit gate boundary, allowed/forbidden next actions, and a single recommended next step. Use this before entering `pre_approval_gate` and when deciding whether a ready PR should request Copilot review, keep waiting, stay in feedback resolution, or stop for conflict resolution.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/repo", "pr": 266, "currentHeadSha": "...", "mergeStateStatus": string|null, "conflictFiles": ["path"]|[], "lifecycleState": string, "loopDisposition": string, "gateBoundary": string, "draftGate": { ... }, "preApprovalGate": { ... }, "draftGateAlreadySatisfied": true, "allowedNextActions": [ ... ], "forbiddenActions": [ ... ], "nextAction": string, "reason": "..." }`
+- `draftGate` / `preApprovalGate` report both latest visible evidence (`visible`, `headSha`, `verdict`, `findingsSummary`, `nextAction`) and whether the evidence is current-head + contract-complete (`currentHead`, `contractComplete`, `currentHeadClean`)
+- `mergeStateStatus` preserves the current GitHub `gh pr view` signal in helper output even when the PR is not in the conflict boundary; `DIRTY` and explicit `CONFLICTING` inputs are treated as conflict-required states
+- `conflictFiles` lists unmerged local paths from `git -c core.quotepath=false status --porcelain=v1 -z --untracked-files=no` when local conflict reconciliation is already in progress
+- when `mergeStateStatus` is conflicted or `conflictFiles` is non-empty, the evaluator emits `gateBoundary=conflict_resolution`, `nextAction=resolve_merge_conflicts`, and forbids gate/approval/merge progression until reconciliation completes
+- `draftGateAlreadySatisfied` — true when the draft→ready transition was already recorded (non-draft + clean evidence exists); callers must skip draft gate when this is true
+- `forbiddenActions` includes `run_pre_approval_gate` whenever the post-draft review cycle has not yet settled for the current head, and conflicted PRs keep it forbidden until reconciliation is complete
+- non-draft PRs do not need visible `draft_gate` evidence to progress through post-draft review or `pre_approval_gate`; `draftGateAlreadySatisfied` is informational only, and downstream legality comes from `gateBoundary`, `allowedNextActions`, and `forbiddenActions`
+- if the PR head changes while gate/conflict facts are loading, the helper still fails closed rather than evaluating mixed-head evidence
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- `gh` failures and malformed `gh` JSON emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/github/detect-checkpoint-evidence.mjs`
+
+Fetches the live PR head SHA plus visible PR issue comments, then summarizes the
+latest valid `draft_gate` and `pre_approval_gate` checkpoint verdict comments.
+Use this when a fresh session needs authoritative visible gate evidence for the
+current head before running `gh pr ready` or declaring final-approval readiness.
+When `PI_SUBAGENT_RUN_ID` is set to a non-empty value, it also enforces async runner ownership before reading GitHub facts, so stale/displaced runs fail closed before merge.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Success output shape:
+- `{ "ok": true, "repo": "owner/repo", "pr": 17, "currentHeadSha": "abc1234", "draftGate": { ... }, "preApprovalGate": { ... }, "draftGateMarker": { ... }, "preApprovalGateMarker": { ... } }`
+- each gate summary includes `visible`, `headSha`, `verdict`, `findingsSummary`, `nextAction`, `commentId`, `commentUrl`, and `updatedAt`
+- when no valid visible comment exists for a gate, its summary is emitted with `visible=false` and the other fields set to `null`
+- each marker summary includes `visible`, `headSha`, `verdict`, `findingsSummary`, `nextAction`, `contractComplete`, `commentId`, `commentUrl`, and `updatedAt`
+- marker summaries track the newest visible marker for the current head (`gate + currentHeadSha`) even if contract fields are partial, enabling same-head rerun idempotency without posting duplicate visible markers
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- `gh` failures and malformed `gh` JSON emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/detect-tracker-pr-state.mjs`
+
+Deterministic tracker-first story-to-PR state detector. Interprets a pre-built
+tracker/PR lifecycle snapshot into one explicit current state, allowed next
+transitions, a recommended next action, and the canonical reverse-sync action.
+This helper is intentionally snapshot-only: tracker-adapter lookups and live
+GitHub discovery remain outside this CLI.
+
+Required:
+- `--input <path>`
+
+Snapshot schema (`--input` JSON):
+- `trackerItemExists` {boolean} — whether a tracker work item was found
+- `trackerItemId` {string|null} — tracker item identifier if present
+- `prExists` {boolean} — whether a PR exists for the tracker item
+- `prNumber` {number|null} — PR number if known; `prNumber` with `prExists=false` is contradictory and blocked
+- `prDraft` {boolean} — whether the PR is still draft
+- `prMerged` {boolean} — whether the PR has been merged
+- `prClosed` {boolean} — whether the PR is closed on GitHub (merged PRs are also closed); `pr_closed_unmerged` is derived from `prClosed && !prMerged`
+
+Unlike the Copilot/reviewer loop snapshots, this tracker snapshot uses `prClosed` for the raw GitHub closed state. Merged PRs therefore set both `prMerged=true` and `prClosed=true`, while `pr_closed_unmerged` is derived from `prClosed && !prMerged`.
+
+This snapshot surface is intentionally limited to tracker identity plus PR lifecycle facts. It does not encode tracker-native workflow readiness/blocking/done state; higher-level callers must combine tracker-owned state separately when deciding whether opening a PR is appropriate.
+
+Success output shape:
+- `{ "ok": true, "snapshot": { ... }, "state": "...", "allowedTransitions": [...], "nextAction": "...", "reverseSyncAction": "..." }`
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "...", "usage": "..." }`
+  on stderr and exit non-zero
+- unreadable input files, invalid JSON, and invalid snapshot objects emit
+  `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/detect-reviewer-loop-state.mjs`
+
+Deterministic reviewer-loop state detector. Captures reviewer-side PR loop state from observable
+GitHub facts plus optional local reviewer-loop metadata and interprets that snapshot into one
+explicit current state, allowed next transitions, and a recommended next action. See
+[Reviewer Loop State Graph](../docs/reviewer-loop-state-graph.md) for the full reviewer-loop state graph and contracts.
+
+Two modes:
+
+- **Auto-detect**: `--repo <owner/name> --pr <number>`
+  Fetches PR/open-head state, review-request status, and pending/submitted review surfaces from
+  GitHub and interprets them into deterministic reviewer-loop state. When `--reviewer-login` is
+  omitted, this uses aggregate all-reviewer scope for the PR.
+
+- **Snapshot interpretation**: `--input <path>`
+  Reads a pre-built snapshot JSON and interprets it without any `gh` calls.
+
+Optional (auto-detect mode only):
+- `--reviewer-login <login>`
+  Scope review-request and review-surface detection to a single reviewer identity. Success output
+  snapshots include `reviewerScope` (`"all_reviewers"` or `"single_reviewer"`) plus
+  `reviewerLogin` (`string|null`) so callers can tell whether the detector used aggregate or
+  single-reviewer scope.
+- `--review-requested <true|false>`
+  Override review-request detection with a known prior result.
+- `--local-state <path>`
+  Inject local reviewer-loop metadata (planning/run/merge/draft-notification status) used for
+  deterministic planning/running/merge-ready and draft lifecycle transitions.
+
+Success output shape:
+- `{ "ok": true, "snapshot": { ... }, "state": "...", "allowedTransitions": [...], "nextAction": "..." }`
+- reviewer snapshots preserve the latest submitted review metadata via `submittedReviewPresent`, `submittedReviewCommitSha`, and `submittedReviewState`
+- together those fields let read-only inspection UIs distinguish submitted-verdict handoff boundaries from active reviewer-pass states
+
+Failure behavior:
+- malformed arguments, unexpected `gh` failures, and invalid input/local-state JSON emit
+  `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/outer-loop.mjs`
+
+Thin deterministic outer-loop wrapper for the Copilot PR remediation path. It combines
+the existing Copilot and reviewer inner-loop detectors into one machine-readable outer
+action so bounded external waits remain owned by the same remediation family instead of
+looking like terminal run endpoints.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--reviewer-login <login>`
+- `--checkpoint-dir <path>`
+- `--copilot-input <path>`
+- `--reviewer-input <path>`
+
+Reviewer-scope contract:
+- omitting `--reviewer-login` means aggregate all-reviewer scope for the PR
+- providing `--reviewer-login` means single-reviewer scope for that login
+- `--reviewer-input` cannot be combined with `--reviewer-login`
+
+Contract:
+- auto-detect mode calls both inner detectors, interprets their current states, and emits one
+  outer action: `continue_wait`, `reenter_copilot_loop`, `reenter_reviewer_loop`, `stop`, or `done`
+- treats draft PRs as a re-entry point into owned draft-stage follow-up rather than a terminal stop
+- treats `waiting_for_copilot_review`, `waiting_for_ci`, and reviewer `submitted_review`
+  as outer-loop-owned `continue_wait` states at explicit external/handoff boundaries
+- preserves compatibility for reviewer `waiting_for_author_followup` and `waiting_for_re_request`
+  as legacy named external-wait boundaries
+- when the next step needs local execution or mutation and the checkout is dirty or detached, preserves the loop-family handoff and marks `conductorRouting.handoffEnvelope.requiresLocalIsolation=true` so callers can continue from an isolated checkout/worktree instead of treating the boundary as terminal
+- for PR-local re-entry actions, verifies local branch/HEAD identity against the active PR head;
+  when an isolation-managed handoff is already in effect, it enriches the handoff with `headRefName` / `headRefOid` for the target PR head instead of failing the handoff on the parent checkout's expected mismatch
+- otherwise stops with `unsafe_local_branch_mismatch_requires_reconcile` or
+  `unsafe_local_head_mismatch_requires_reconcile` when checkout identity is not aligned
+- when that PR-local identity gate trips, the emitted `conductorRouting` result is also fail-closed
+  to a stop outcome with no handoff entrypoint, so consumers cannot keep following a stale handoff envelope
+- persists bounded checkpoint state to `tmp/copilot-loop/<owner>/<repo>/pr-<n>/outer-loop-state.json` for
+  async continuation and false-positive wakeup detection
+- emits an additive `conductorRouting` field with the conductor-owned routing outcome, derived
+  outer action, stop reason when relevant, and any machine-readable handoff envelope
+- supports snapshot-input mode for deterministic gh-free testing
+
+Success output shape:
+- `{ "ok": true, "outerAction": "...", "copilotState": "...", "reviewerState": "...", "reviewerScope": { "mode": "all_reviewers"|"single_reviewer", "reviewerLogin": "..."|null }, "reason"?: "...", "branchIdentity"?: { ... }, "conductorRouting": { "routingOutcome": "...", "outerAction": "...", "stopReason": null|"...", "handoffEnvelope": { ... } }, "checkpoint": { ... } }`
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- unexpected `gh` or `git` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/inspect-run.mjs`
+
+Read-only inspection entrypoint for one explicit Copilot PR outer-loop target.
+It composes current inner-loop facts into one JSON snapshot without attaching to
+an active worker or mutating local/runtime state.
+
+Required:
+- `--repo <owner/name>`
+- `--pr <number>`
+
+Optional:
+- `--steering-state-file <path>`
+- `--reviewer-login <login>` — narrows live reviewer detection to one reviewer identity; when omitted, inspection uses aggregate all-reviewer scope for the PR
+- `--copilot-input <path>`
+- `--reviewer-input <path>` — cannot be combined with `--reviewer-login`
+
+Contract:
+- is strictly read-only: it does not write checkpoints, mutate GitHub state, or create local artifacts
+- returns a stable top-level inspection shape with target identity, derived `runId`, authoritative `outerState`, conditional top-level `allowedTransitions`, compatibility `outerAction`, active family state,
+  status class, trust/source semantics, evidence, markers, and best-effort drill-down layers
+- only derives top-level `outerState` / `allowedTransitions` / `outerAction` / `activeFamilyState` / `statusClass` when inspection has a complete current inner-loop picture, whether from live detectors and/or caller-supplied snapshot inputs
+- when inspection falls back to checkpoint-only data or mixed live + checkpoint evidence, checkpoint-backed drill-down layers and checkpoint evidence paths remain available as advisory context while the top-level state stays `"unknown"`
+- reports not-found or unavailable targets as structured success output with `statusClass: "unknown"`
+  rather than by throwing a synthetic blocked-run error
+- looks for checkpoints at the repo-qualified default path `tmp/copilot-loop/<owner>/<repo>/pr-<n>/outer-loop-state.json`
+- during transition, may read the legacy default path `tmp/copilot-loop/pr-<n>/outer-loop-state.json` only when the checkpoint file's embedded `repo` and `pr` match the explicit target
+- surfaces steering as a best-effort drill-down layer when `--steering-state-file` is provided,
+  including latest acknowledgement plus queued/effective stop summaries for the current run,
+  without exposing full steering history/detail or raw steering-file locator paths
+- when live GitHub PR facts are available, surfaces a deterministic `loopIterations` summary for the
+  remote Copilot review/fix loop (completed rounds, pending round indicator, Copilot review comments,
+  current resolved/unresolved review-thread counts, and fix commits after feedback)
+- keeps `loopIterations` unavailable in snapshot-only / non-live inspection paths instead of
+  inventing local phase-loop iteration semantics
+- rejects mismatched steering-state files from the targeted repo/pr instead of projecting their state onto the inspected run
+
+Success output shape:
+- `{ "ok": true, "schemaVersion": 1, "target": { "repo": "...", "pr": 17 }, "runId": "pr-17", "inspectedAt": "...", "activeStateFamily": "copilot-pr-outer-loop", "outerState": "...", "allowedTransitions"?: [...], "outerAction": "...", "activeFamilyState": "...", "statusClass": "...", "needsAttention": false, "sourceMode": "...", "trust": "...", "evidence": { ... }, "markers": { ... }, "loopIterations": { "available": true|false, ... }, "layers": { "reviewer": { "currentState": "...", "scope": { "mode": "all_reviewers"|"single_reviewer", "reviewerLogin": "..."|null }, ... }, ... } }`
+
+Failure behavior:
+- malformed arguments emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+- unexpected runtime failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
+
+### `scripts/loop/inspect-run-viewer.mjs`
+
+Owned read-only local/operator inspection dashboard layered on `inspect-run`.
+`inspect-run` remains authoritative for inspection/status state; the viewer owns local inbox discovery and read-only presentation/prioritization.
+
+Primary local lifecycle UX now lives in the Pi extension under:
+- `/dev-loops inspect open [--repo <owner/name>]`
+- `/dev-loops inspect resume [--repo <owner/name>]`
+- `/dev-loops inspect status [--repo <owner/name>]`
+- `/dev-loops inspect stop [--repo <owner/name>]`
+- `/dev-loops inspect restart [--repo <owner/name>]`
+
+The extension-managed seam stores one narrow repo-local managed-instance record at:
+- `.pi/ui-servers/inspect-run-viewer.json`
+
+Ownership split for this slice:
+- extension owns lifecycle UX, URL discovery, liveness checks, reattach logic, stop/restart, and best-effort browser opening
+- when a repo-scoped command reuses an inbox-first managed viewer, the surfaced URL may include `?scope=<owner/name>` to pre-scope the inbox without replacing the managed instance
+- viewer script still owns HTTP server behavior, rendering, inbox/query behavior, and snapshot loading
+
+Optional:
+- `--repo <owner/name>` (repo-scope the inbox; otherwise the viewer starts in inbox-first mode)
+- `--host <host>` (default: `127.0.0.1`; non-loopback binds require `--allow-non-localhost`)
+- `--port <port>` (default: `4311`)
+- `--allow-non-localhost` (explicit opt-in for non-loopback binds such as `0.0.0.0` or LAN IPs)
+- `--restart` (manual/debug convenience only; requires `lsof` / POSIX support and sends `SIGTERM` to every listener already bound to that port)
+- `--steering-state-file <path>` (pass-through to `inspect-run`)
+- `--reviewer-login <login>` (pass-through to `inspect-run`)
+- `--copilot-input <path>` (pass-through to `inspect-run`)
+- `--reviewer-input <path>` (pass-through to `inspect-run`; cannot be combined with `--reviewer-login`)
+
+Contract:
+- current-slice posture: kept/promoted as an explicitly owned local/operator inspection dashboard (not a second public workflow entrypoint)
+- read-only: no GitHub mutations, no checkpoint writes, no steering writes, no worker attachment
+- ownership boundary: `inspect-run` owns authoritative inspection/status state; viewer owns local inbox discovery plus read-only operator presentation/prioritization
+- extension-managed lifecycle remains loopback-first and local-only; no remote/public hosting support
+- the script fallback still requires explicit `--allow-non-localhost` opt-in for non-loopback binds; do not expose inspection state on the network by default
+- GitHub-first launch boundary: repo scope is optional and PR selection happens through the viewer URL/query state, not a CLI `--pr` flag
+- uses one adapter module (`scripts/loop/_inspect-run-viewer-adapter.mjs`) to load the normalized inspection snapshot
+- adapter is the only viewer integration seam that calls the existing `inspect-run` contract in this source-loaded workspace
+- serves two explicit read-only endpoints:
+  - `/` → operator-facing HTML with an assigned-PR inbox shell and, when a PR is selected via URL or sidebar, the Mermaid-first graph plus current-PR-state banner and supporting textual summary/evidence
+  - `/snapshot.json` → the full authoritative inspection snapshot JSON for the currently selected PR/query target
+- HTML includes a visible link to `/snapshot.json` so machine-readable state no longer depends on an inline full-snapshot dump in the page itself
+- `/snapshot.json` returns `application/json; charset=utf-8` on success and deterministic JSON error output with non-2xx status when snapshot loading throws or yields no snapshot
+- unsupported paths return deterministic `404` without loading a snapshot (even for unsupported methods on unknown paths); `/favicon.ico` returns deterministic `204`; unsupported methods on supported routes return `405 Allow: GET`
+- both primary endpoints send `Cache-Control: no-store` to match the manual-reload workflow
+- the script-local `--restart` flag remains a manual/debug fallback only; the extension-managed path must not depend on killing unknown listeners
+- manual reload only (`window.location.reload()`); no polling/watch/timeout/control semantics
+
+Local manual verification path:
+1. Preferred extension-managed path:
+   - `/dev-loops inspect open`
+   - `/dev-loops inspect status`
+   - `/dev-loops inspect resume`
+   - `/dev-loops inspect stop`
+2. Script fallback for manual/debug verification:
+   - `node scripts/loop/inspect-run-viewer.mjs`
+   - `node scripts/loop/inspect-run-viewer.mjs --repo <owner/name>`
+3. Open the printed/resolved URL in a local browser and verify the human-oriented `/` page
+4. Select a PR via the sidebar or by adding `?repo=<owner/name>&pr=<number>` to the viewer URL
+5. Open `/snapshot.json` for that selected/query-targeted PR and verify it returns the matching full inspection snapshot JSON
+6. Use browser refresh or the reload button for point-in-time re-inspection
+
+Local WebKit/Playwright smoke path:
+1. Install the Safari/WebKit browser runtime once:
+   - `npx playwright install webkit`
+2. Run the viewer smoke suite:
+   - `npm run test:playwright:viewer`
+3. Review screenshots/traces under `test-results/` and the HTML report under `playwright-report/ui-smoke/inspect-run-viewer/`
+4. Optionally hit `/favicon.ico` or an unsupported path to confirm those paths stay deterministic and do not perform snapshot rendering
+5. For deterministic/local test mode, pass `--copilot-input` and `--reviewer-input` fixtures to viewer; these are forwarded to `inspect-run`
+
+### `scripts/loop/steer-loop.mjs`
+
+Mid-flight operator steering CLI for active dev loops.
+
+Subcommands:
+- `submit` — submit a steering directive to a specific run
+- `promote` — explicitly promote queued steering for a specific run at a known loop state
+- `status` — inspect the current steering state for a run
+
+Contract:
+- persists steering state to a JSON file (default: `.pi/steering/<owner>/<repo>/pr-<n>.json` for operator-facing `--repo/--pr` mode; `.pi/steering/<run-id>.json` for low-level `--run-id` mode)
+- operator-facing `submit` resolves one explicit `repo` + `pr` target through the read-only
+  inspection surface and derives `runId: pr-<number>` from that target while persisting repo-qualified target metadata alongside the steering state
+- explicit queued-steering promotion/persistence belongs to `promote`; detector-shaped helpers stay read-only
+- operator-facing `submit` is intentionally limited to `stop_at_next_safe_gate`; other directive
+  kinds remain low-level/internal and are rejected on the external submit path
+- operator-facing `submit` fails closed when inspection is partial, checkpoint-only, unavailable,
+  stale, or conflicting
+- low-level/testing mode may still accept injected loop-state inputs for deterministic tests
+- returns deterministic acknowledgement/result payloads for `submit` and deterministic state
+  readback for `status`
+- rejected operator-facing submits leave any trusted durable steering file unchanged; when the
+  persisted file is malformed or target-mismatched, the response may include a fresh synthetic
+  target-scoped `steeringState` for deterministic readback without trusting broken persisted data
+
+Success output shape:
+- `submit`: `{ "ok": true, "acknowledgement": { ... }, "result": { ... }, "steeringState": { ... } }`
+- `promote`: `{ "ok": true, "promotedCount": <n>, "promoted": [ ... ], "steeringState": { ... } }`
+- `status`: `{ "ok": true, "status": { ... } }`
+
+Failure behavior:
+- argument/usage errors emit `{ "ok": false, "error": "...", "usage": "..." }` on stderr and exit non-zero
+- runtime failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero