• Merge-readiness is never merge authorization — except

  posture:stack-land

  . Under

  target

  and

  stack-ready

  , this skill never merges as part of babysitting; only selecting/handing off

  posture:stack-land

  (or a later explicit user request that selects it) authorizes

  gh stack merge

  for the bottom-most open settled prefix endpoint.
• Draft PRs are opt-in. Never review or babysit a draft merely because managed-stack traversal reaches it; a draft is eligible only when a human explicitly named that draft (a direct user invocation resolving to it counts) or explicitly included drafts in scope. A calling skill's automatic handoff is neither — when an auto-invocation resolves to a draft, report the draft status and stop instead of arming a watch, unless the invocation carries an explicit user watch-mode token.
• Managed means positively confirmed membership. A managed stack exists for this workflow only when a fresh probe proves the target belongs to it and emits

  manager_status == "confirmed"

  . Repository-level stack availability, a manual base/head dependency, or a failed/uncertain probe is not a managed stack.
• One semantic writer lane. Keep one active PR target and one watcher. Manager-owned mechanical propagation may update confirmed dependents, but review/CI fixes on another layer require explicit stack-wide semantic scope and proceed downstack-to-upstack, never concurrently.

needs-human

target

stack-ready

stack-land

• an in-progress reaction on the PR — an 👀 (eyes) is how several review bots, Codex among them, announce a review is underway;
• an interim comment — a "reviewing…" / "in progress" note (CodeRabbit, Greptile, and others post these);
• a reviewer that reviewed an earlier head but not the current one — a re-review is expected on the new commit.

review_signal_seen_on_head

review_in_progress

merge-ready

stack-ready

stack-land

target

target

stack-ready

stack-land

gh stack merge <bottom-most-open-settled-PR> --yes --squash

gh stack sync

gh pr merge

git rebase

git push --force

AskUserQuestion

ToolSearch

select:AskUserQuestion

request_user_input

ask_question

agy

ask_user

ce-resolve-pr-feedback

ce-debug

Skill

needs-human

Never wait for a full CI run before addressing review comments. A comment fix pushes a new commit that re-triggers CI anyway, so handling comments while CI is still running collapses the two timelines instead of serializing them. Handle comments first; if that pass pushed, the old CI failure is against a dead SHA — skip it and let the new run start.

The same rule applies to an in-progress review. Act on the feedback a reviewer has already posted rather than waiting for its 👀/"reviewing" signal to clear — the in-progress signal gates only the "looks ready" call (Step 3), never the work. Waiting for a review to finish before resolving the comments it already left serializes exactly the way waiting for CI would.

gh

gh repo view

gh

git remote get-url origin

gitlab.*

bitbucket.*

gh

gh

gh pr view --json isDraft

snapshot --start-invocation

pr_is_draft

gh stack view --json

pr_chain.manager_status == "absent"

"absent"

"probe-error"

gh stack checkout

manager_status == "confirmed"

probe-error

target

stack-ready

stack-ready

stack-land

target

stack-ready

stack-ready

mode:pipeline

posture:stack-ready

posture:stack-land

stack-ready

stack-land

--continue-invocation

--invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS"

--session-started-at

--invocation-started-at

--continue-dead-time-seconds <prior layer's 

>

posture:

needs-human

manager_status == "confirmed"

ce-resolve-pr-feedback

ce-debug

HEAD

gh pr view <ref> --json headRefName,headRefOid,isCrossRepository

git branch --show-current

headRefName

gh pr checkout <ref>

maintainerCanModify

references/watch-loop.md

/ce-babysit-pr <url>

target

posture:stack-ready

posture:stack-land

$ce-babysit-pr <url> [posture:…]

• Self-sustaining in-session watch (default). Start a cheap deterministic background change-detector —

  pr-snapshot watch

  (Step 2 has the invocation) — which polls the PR with no agent tokens and prints a single wake sentinel only when there's work to inspect or a stop condition. Then stay in this session and wait for that sentinel, using whatever background-and-wake capability your harness exposes. You need exactly one capability: run a background process and be woken when it emits a line, without ending your turn — reach for whatever your harness gives you (examples, not a fixed list: Claude Code's background

  Bash

  + a

  Monitor

  /wait, Cursor's

  Shell

  background +

  notify_on_output

  , Grok's

  get_command_or_subagent_output

  ,

  ScheduleWakeup

  under

  /loop

  ). On each wake, run one tick (Step 2's ordering invariant), persist, then go back to waiting (Step 5). The detector only flags that something changed — every tick's judgment (resolve comments, debug CI, decide merge-ready) is agent reasoning plus a sub-skill call, so re-enter this agent each wake; do not collapse the loop into a shell script that greps and acts on its own (

  pr-snapshot watch

  loops internally, which makes that substitution tempting — it cannot do the reasoning the tick requires). Staying in-session keeps everything decided in this conversation — declined nits, a reviewer judged wrong, your mid-run steering — and spends reasoning only when something actually changed. Continue until a Step 3 stop condition. Describe the capability and use your own tool for it — do not ask the user to type a slash command; a skill drives tool calls, not keystrokes.
• Checkpoint (the honest floor). Only when the harness genuinely exposes no background-and-wake capability (some sandboxed GUI apps): run exactly one tick, persist, report, and print the exact re-run command. Monitoring is paused — say so plainly. Never fake a loop with a foreground

  sleep

  (Claude Code blocks it) or by "just continuing" (nothing wakes the next tick).
• Pipeline (

  mode:pipeline

  , set by an orchestrator like

  lfg

  ) — run bounded synchronous ticks in-line: the orchestrator is the scheduler, so loop ticks yourself (snapshot → act → re-snapshot) until the pipeline stop (Step 3), then return. Fully non-interactive. See "Pipeline mode" below for the deltas — a different stop condition, native residual surfacing, and a structured return — and read

  references/watch-loop.md

  for its bound.

scheduler_create --durable

<harness-cli> exec '<host-rendered resume invocation>'

1. Delegates run non-interactively. Invoke

   ce-resolve-pr-feedback mode:pipeline

   for comments and

   ce-debug mode:pipeline

   for CI; collect their structured results (fixes + residuals). Never ask the user anything.
2. Bounded stop, not merge-ready. Exit when no actionable backlog remains AND either CI is clean (

   all_checks_ok

   — every check terminal, none failing, and at least one observed), GitHub reports a known clean merge state (

   mergeability_certain

   and

   merge_state_status == "CLEAN"

   ), and

   base_ref_blocker

   ,

   stack_blocker

   , and

   branch_currency_blocker

   are null → success, or a fix/round/time budget is hit → return with residuals. Report success only when those exact gates hold. A terminal-but-red check that

   ce-debug

   marked dispatched but left failing (

   diagnosed-no-fix

   /

   needs-human

   →

   has_failing_checks

   stays true), a racing, pending, or unproven current-base identity, unknown or non-clean merge state, manager-stale/unknown target, an open/claimed/parked current currency item, or an empty

   statusCheckRollup

   right after PR creation (

   checks_present

   false — Actions hasn't created check-runs yet, not that CI passed) is a residual, not a pass. Never wait for the merge-ready settle window or human approval (interactive-only). Under

   posture:stack-land

   , when those gates hold, execute Step 3's stack-land land step before treating the layer as pipeline success or advancing; a just-landed MERGED outcome continues the pipeline on the next open non-draft needing work rather than ending the invocation.
3. Native residual surfacing + structured return. Needs-human review threads stay open (the resolver posts

   decision_context

   there). Anything with no thread home — CI you could not fix after budget, a

   needs-human

   from

   ce-debug

   — goes into one run-report PR comment (a point-in-time narrative), never a PR-body section. Return a structured result:

   { status, checks_terminal, fixes_applied, residuals: [...] }

   .

/loop

SKILL_DIR

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)"; [ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && chmod 700 "$SCRATCH_ROOT" || { echo "unsafe scratch root: $SCRATCH_ROOT" >&2; exit 1; };
STATE_DIR="$SCRATCH_ROOT/ce-babysit-pr/<host>-<owner>-<repo>-<N>";
(umask 077; mkdir -p "$STATE_DIR") || exit 1; chmod 700 "$STATE_DIR" || exit 1;
PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; };
"$PY" "$SKILL_DIR/scripts/pr-snapshot" snapshot --pr <N> --repo <[host/]owner/repo> --state-dir "$STATE_DIR" --start-invocation --invocation-budget-seconds <seconds>

28800

invocation_elapsed_seconds

invocation_id

invocation_started_at

invocation_budget_seconds

RUN_INVOCATION_ID

RUN_STARTED_AT

RUN_BUDGET_SECONDS

invocation_elapsed_seconds <= 60

--continue-invocation

--start-invocation

snapshot

reviewThreads(first:N)

pageInfo

hasNextPage == false

pr-snapshot watch

BABYSIT_WAKE {reason,url,...}

actionable

feedback-candidate

terminal

blocked-external

blocked-external-drained

blocked-failing

base-ref-blocked

stack-blocked

needs-human

merge-ready

max-runtime

stop-signal

invocation-superseded

feedback-candidate

SKILL_DIR="<absolute path of this skill's directory>"; SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)"; [ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && chmod 700 "$SCRATCH_ROOT" || { echo "unsafe scratch root: $SCRATCH_ROOT" >&2; exit 1; }; STATE_DIR="$SCRATCH_ROOT/ce-babysit-pr/<host>-<owner>-<repo>-<N>"; (umask 077; mkdir -p "$STATE_DIR") || exit 1; chmod 700 "$STATE_DIR" || exit 1; RUN_INVOCATION_ID="<invocation_id>"; RUN_STARTED_AT="<invocation_started_at>"; RUN_BUDGET_SECONDS="<invocation_budget_seconds>";
PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; };
"$PY" "$SKILL_DIR/scripts/pr-snapshot" watch --pr <N> --repo <[host/]owner/repo> --state-dir "$STATE_DIR" --interval 150 --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS"

watch_generation

invocation-superseded

last_change_at

invocation_started_at

invocation_budget_seconds

--settle-seconds

--blocked-external-drain-seconds

--settle-seconds

merge-ready

--blocked-external-drain-seconds

SKILL_DIR

STATE_DIR

mark

$SKILL_DIR

<host>

STATE_DIR

gh repo view --json url

mark

<owner>-<repo>-<N>

owner/repo#N

state.json

github.com

--repo <host>/<owner>/<repo>

[HOST/]OWNER/REPO

pr-snapshot

gh pr view

github.com

branch_currency

attention

pr_state

mergeable

merge_state_status

base

base_ref_blocker

host_branch_update_capability

branch_currency_blocker

review_decision

head_sha

head_changed

quiet_seconds

invocation_elapsed_seconds

invocation_remaining_seconds

persisted_state_age_seconds

checks_awaiting_approval

blocked_external

blocked_external_first_seen_at

blocked_external_review_last_activity_at

blocked_external_review_quiet_seconds

blocked_external_review_moved_this_tick

pr_chain

trajectory

check_recur_max

recurring_checks

unresolved_trend

new_threads_this_tick

stream_alternations

heads_since_progress

base.historical_oid

baseRefOid

base.oid

baseRef.target.oid

base.graphql_oid

potentialMergeCommit

base.identity == "current"

race

mergeability-pending

probe-error

mergeability_certain

DIRTY

CONFLICTING

potentialMergeCommit

pr_chain

manager_status

confirmed|absent|probe-error

relationship_status

dependent|independent|probe-error

actionable.comments

ce-resolve

mark

mark

RUN_INVOCATION_ID

RUN_STARTED_AT

RUN_BUDGET_SECONDS

references/watch-loop.md

trajectory

check_recur_max >= 2

stream_alternations >= 3

unresolved_trend

new_threads_this_tick > 0

heads_since_progress >= 2

ce-debug

ce-resolve-pr-feedback

needs-human

references/watch-loop.md

1. Terminal check first. If

   pr_state

   is

   MERGED

   or

   CLOSED

   , stop and report — the loop is done — except when this run just completed an authorized

   stack-land

   merge on that PR: treat that MERGED outcome as a managed-stack layer transition (see Step 3's stack-land land step), not a run-level Terminal stop.
2. Capture the head SHA now (

   git rev-parse HEAD

   or the snapshot's

   head_sha

   ) so you can tell later whether the comment pass pushed.

gh stack view --json

gh stack push

github/gh-stack#216

1. Feedback before CI. If the attention set has either unresolved threads or non-thread feedback candidates (

   counts.threads > 0

   or

   counts.comments > 0

   ), invoke

   ce-resolve-pr-feedback

   once, passing the resolved PR ref — the base

   [HOST/]OWNER/REPO#N

   or the full PR URL from the snapshot's

   url

   (so a fork→upstream PR resolves against the upstream base, not the fork checkout's

   origin

   , which would query the wrong PR namespace) — in full mode with

   mode:pipeline

   (non-interactive: it parks any

   needs-human

   on the thread and returns it as a structured residual instead of pausing on a blocking user question, which would stall the autonomous watch — the same reason Step 2 step 5 invokes

   ce-debug mode:pipeline

   ); it re-fetches and judges all feedback — inline threads, review bodies, and top-level comments — and is idempotent on empty. The

   actionable.comments

   field contains the top-level/review-body candidates the resolver would otherwise not know the loop cares about — a Changes-Requested review body or a bare top-level "please rename X" with no inline thread must still trigger a pass. When the review trigger above is crossed (rising backlog, new-item arrivals, or a repeating cluster), pass the

   trajectory

   so it can judge a treadmill / wrong-approach nitpick cluster and return one approach-level

   needs-human

   instead of fixing forever — and, when the recurring items are valid and share one root and fix, request a bounded-class assessment so it consolidates the equivalent sites this PR touched into a single fix rather than dripping one per head (

   references/watch-loop.md

   , Non-convergence). One resolve pass per tick — never fan out multiple. When it returns, record what it left unresolved so the loop stops re-dispatching it (re-set the vars inline — shell state does not persist between calls): for each

   needs-human

   thread,

   mark --thread <ID> --disposition needs-human

   . Then reconcile the comments you passed — a top-level comment / review body never drops out of the fetch on its own, and

   ce-resolve

   may silently drop boilerplate, status noise, or other non-actionable feedback after applying agent judgment. So mark every comment you passed as

   dispatched

   (

   mark --comment <ID> --disposition dispatched

   ), except those

   ce-resolve

   returned as

   needs-human

   (mark those

   --disposition needs-human

   ). Marking only the ones it explicitly handled would leave silently-dropped candidates in the attention set forever, so

   counts.comments

   would never reach 0 and the loop would never settle:

SKILL_DIR="<absolute path of this skill's directory>"; SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)"; [ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && chmod 700 "$SCRATCH_ROOT" || { echo "unsafe scratch root: $SCRATCH_ROOT" >&2; exit 1; }; STATE_DIR="$SCRATCH_ROOT/ce-babysit-pr/<host>-<owner>-<repo>-<N>"; (umask 077; mkdir -p "$STATE_DIR") || exit 1; chmod 700 "$STATE_DIR" || exit 1;
PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; };
"$PY" "$SKILL_DIR/scripts/pr-snapshot" mark --pr <N> --repo <[host/]owner/repo> --state-dir "$STATE_DIR" --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS" --thread <ID> --disposition needs-human
"$PY" "$SKILL_DIR/scripts/pr-snapshot" mark --state-dir "$STATE_DIR" --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS" --comment <ID> --disposition dispatched
"$PY" "$SKILL_DIR/scripts/pr-snapshot" mark --state-dir "$STATE_DIR" --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS" --comment <ID> --disposition needs-human --acted-edit-id <edit_id-from-the-snapshot's-actionable.comments-item>

--pr

--repo

mark

mark --disposition open

--acted-edit-id

edit_id

actionable.comments[].edit_id

fixed-differently

declined

not-addressing

fixed

• Flaky/infra (known-flaky job, infrastructure/timeout signal) → extract the run ID and the full base repo including host from the failing check's

  details_url

  (

  https://<host>/<owner>/<repo>/actions/runs/<run-id>/…

  ) and

  gh run rerun <run-id> --failed -R <host>/<owner>/<repo>

  . Passing the run ID is load-bearing unattended: omitting it drops

  gh run rerun

  to an interactive run-picker menu that blocks

  mode:pipeline

  . Passing the host-qualified

  -R <host>/<owner>/<repo>

  is load-bearing for fork→upstream and GitHub Enterprise PRs: the run lives in the base repo on its own host, so a bare

  -R <owner/repo>

  (or no

  -R

  ) targets the fork or the default

  github.com

  and 404s. On plain github.com the host segment is optional but harmless.
• Real test/build failure → invoke

  ce-debug mode:pipeline

  once, seeded with the failing jobs and their log tails — and, when the CI trigger above is crossed, the

  trajectory

  (

  recurring_checks

  ,

  check_recur_max

  ,

  heads_since_progress

  ) so it can judge oscillation vs ordinary progress. Its structured return

  status

  is exactly one of

  fixed-and-pushed

  ,

  flaky-infra

  ,

  diagnosed-no-fix

  , or

  needs-human

  (this must stay identical to what

  ce-debug

  returns in pipeline mode — do not invent

  infra-retry

  /

  stale

  ). Handle each:

  fixed-and-pushed

  → mark the check dispatched and re-snapshot;

  flaky-infra

  → treat as a rerun;

  diagnosed-no-fix

  and

  needs-human

  → surface as a residual, the check stays red — never forced. A

  needs-human

  here can be an emergent trade-off (two failures that can't both be fixed without a divergent change) — park the CI stream on it, don't re-dispatch. Then record each check you acted on so it is not re-dispatched at this head (re-set the vars inline):

SKILL_DIR="<absolute path of this skill's directory>"; SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)"; [ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && chmod 700 "$SCRATCH_ROOT" || { echo "unsafe scratch root: $SCRATCH_ROOT" >&2; exit 1; }; STATE_DIR="$SCRATCH_ROOT/ce-babysit-pr/<host>-<owner>-<repo>-<N>"; (umask 077; mkdir -p "$STATE_DIR") || exit 1; chmod 700 "$STATE_DIR" || exit 1;
PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; };
"$PY" "$SKILL_DIR/scripts/pr-snapshot" mark --state-dir "$STATE_DIR" --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS" --check "<key>"

branch_currency

UNKNOWN

base_ref_blocker

probe-error

normal-base

• Inspection and claim lifecycle. If

  attention == "inspect"

  , first preview the current conflict and compute its semantic conflict fingerprint. Compare it with

  parked_semantic_fingerprints

  , then mark the exact item with

  --currency-inspected-fingerprint <fingerprint>

  . Unchanged evidence stays parked; changed evidence retires the old park and reopens the item. Do not claim before that inspection clears. For

  attention == "claim"

  , and only while fixed budget remains, atomically mark the exact item before any external mutation or local merge starts:
  bash

  SKILL_DIR="<absolute path of this skill's directory>"; STATE_DIR="/tmp/compound-engineering-<effective-uid>/ce-babysit-pr/<host>-<owner>-<repo>-<N>"; RUN_INVOCATION_ID="<invocation_id>"; RUN_STARTED_AT="<invocation_started_at>"; RUN_BUDGET_SECONDS="<invocation_budget_seconds>";
  PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; };
  "$PY" "$SKILL_DIR/scripts/pr-snapshot" mark --state-dir "$STATE_DIR" --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS" --currency-key <currency_key> --currency-disposition claimed

  A re-entry into

  claimed

  is reconciliation-only: inspect remote and local evidence, never directly resubmit. Record exactly one of

  --currency-outcome mutation-observed

  ,

  --currency-outcome proven-no-mutation

  , or

  --currency-outcome ambiguous

  . Exactly one retry is possible only after conclusive no-mutation proof and the engine's backoff; an ambiguous result never retries or resubmits. Confirm or park with

  --currency-disposition confirmed|needs-human

  against that same

  --currency-key

  and invocation tuple. A stale invocation, exhausted budget/

  max-runtime

  , or head/base movement between claim and mutation rejects or invalidates the action before it writes.

• BEHIND

  : host-owned update only. Proceed only for

  route == "normal-base"

  with

  host_branch_update_capability == true

  ;

  false

  /denied or

  unknown

  is a

  needs-human

  path, never inferred from Git or direct-push authority. After claim, immediately revalidate that remote head and base OIDs still equal the observation. Invoke the host update operation once through GitHub's

  PUT /repos/{owner}/{repo}/pulls/{number}/update-branch

  endpoint with

  expected_head_sha

  set to the claimed observation's head SHA; never use an update helper that cannot transmit that precondition. Treat an HTTP 422 head mismatch as a stale claim: re-snapshot and reconcile without resubmitting. Host acceptance is

  mutation-observed

  , not completion. Confirm the exact claimed observation only after a fresh snapshot and ancestry evidence prove the resulting head contains its observed base OID and no unrelated head/base movement or different current currency evidence invalidates that proof. The claimed item's own

  branch_currency_blocker

  remains until confirmation and need not be null beforehand. A moved head alone is not proof.

• DIRTY

  : exact-base local repair only.

  host_branch_update_capability

  is irrelevant and does not imply push access. Separately prove, without mutating, ordinary direct-push authority to the exact head ref; unknown or denied authority is

  needs-human

  . Require a verified clean PR-head checkout at the observed head, fetch the exact observed base OID, and run a non-mutating merge preview. The semantic conflict fingerprint is the sorted conflicted paths plus their stage blob identities; it excludes the base OID so unrelated later base movement cannot disguise the same conflict. A resolution is mechanical only with positive intent evidence and no reasonable alternative behavior. Two plausible resolutions, a material behavior or user-intent choice, unbounded scope, stale OIDs, incomplete evidence, or missing authority means abort safely and park with

  --currency-disposition needs-human --semantic-conflict-fingerprint <fingerprint>

  , plus concise competing options, tradeoffs, and a lean.
• Apply and confirm a mechanical

  DIRTY

  repair. Claim and revalidate the exact head/base OIDs and clean checkout again, merge that exact base OID, and mark

  --currency-outcome mutation-observed

  as soon as the local merge starts. Resolve only the previewed mechanical conflict, validate proportionally, and use a normal push to the exact head ref. Never rebase or force-push. An interrupted local merge must be reconciled to its validated commit or aborted safely before parking; never layer a second attempt over it. Confirm only when remote evidence proves the head equals or contains the validated merge commit, a fresh snapshot clears the currency gate, and no unrelated movement invalidated the claim. Remote head movement alone is not proof or confirmation.
• Managed stack or probe uncertainty. With

  manager_status == "confirmed"

  , manager currency outranks ordinary state: pre-existing target staleness becomes

  stack-sync-needed

  , never this route; Step 7 alone owns post-push manager maintenance. With a manager or relationship

  probe-error

  , continue review/CI but perform no branch-currency mutation or ready declaration until classification succeeds.

1. After an authorized target-head push in a confirmed managed stack, preserve the upstack before resuming the watch. This is manager-owned maintenance implicitly authorized by babysitting a managed layer, not permission for arbitrary history edits. Retain the delegate-reported pushed SHA, re-run read-only

   gh stack view --json

   , and require that it still identifies the target PR on the current local branch. Require a clean worktree, fetch the target branch from its tracking remote, and verify both the target's local head and remote-tracking tip still equal that pushed SHA; a moved target becomes an upstack residual, never something this step rebases or overwrites. From the fresh manager order, select the first open dependent branch immediately above the target. If there is none, no cascade is needed. If any precondition fails, leave an upstack residual without importing, checking out, or guessing at the stack. Otherwise run

   gh stack rebase "<first-dependent-branch>" --upstack --no-trunk --remote <tracking-remote>

   , verify the target local head is still unchanged at the pushed SHA, then run

   gh stack push --remote <tracking-remote>

   only — never raw

   git push --force

   . Starting at the first dependent excludes the target from the cascading rebase;

   --no-trunk

   confines the operation to inter-branch propagation and avoids a stale local trunk. After push success or rejection, fetch and re-probe: verify the target still equals the delegate-reported pushed SHA (already checked above); for every open dependent in the baseline, compare local and remote-tracking heads to the recorded pre-push OIDs and expected post-rebase tips — do not treat the target's intentional post-push OID change as divergence. Do not assume all-or-none. Treat already-updated dependent remotes as observed progress; name the first rejected or divergent dependent layer and return a precise recoverable upstack residual (retry from that layer after the cause is fixed). Never claim stack readiness until manager order, ancestry, review, and CI are re-proven on every current head. If the rebase conflicts, immediately run

   gh stack rebase --abort

   and surface a

   needs-human

   /stack-sync residual — do not decide conflict semantics in another PR layer. If the target moved or a lease rejects unexpected remote state, do not retry with raw force; surface the residual. This route never applies to a manual dependency chain, and the delegated target fixers never perform it.
2. After any mutation, re-snapshot at the start of the next tick, passing the same

   --invocation-id "$RUN_INVOCATION_ID" --session-started-at "$RUN_STARTED_AT" --invocation-budget-seconds "$RUN_BUDGET_SECONDS"

   — the head SHA and CI universe have changed, but the invocation-wide budget has not. Do not run a second

   snapshot

   mid-tick to re-derive CI; that is what caused stale-SHA confusion.

ce-resolve-pr-feedback

ce-debug

gh stack push

target

stack-ready

gh stack merge <N> --yes --squash

needs-human

stack-land

ce-resolve-pr-feedback

ce-debug

stack-land

needs-human

ce-debug

needs-human

gh stack

stack-land

ce-resolve

ce-debug

mode:pipeline

all_checks_ok

mergeability_certain

merge_state_status == "CLEAN"

base_ref_blocker

stack_blocker

branch_currency_blocker

blocked-external-drained

blocked-external

needs-human

blocked-failing

stack-sync-needed

stack-land

stack-ready

target

needs-human

manager_status == "confirmed"

stack-land

stack-land

gh stack merge <PR>

references/stack-commands.md

gh stack merge <that-PR> --yes --squash

gh stack sync --remote <tracking-remote>

pr_state

gh stack merge

mode:pipeline

MERGED

MERGED

--continue-invocation

MERGED

CLOSED

gh pr merge

mode:pipeline

posture:stack-land

MERGED

• Terminal — PR

  MERGED

  or

  CLOSED

  , except when this run just completed an authorized

  stack-land

  merge on that PR: that MERGED outcome is a layer transition (see stack-land land step above), not a run-level Terminal stop.
• Looks merge-ready (settled) — GitHub itself reports it mergeable:

  mergeability_certain

  ,

  mergeable == "MERGEABLE"

  , and

  merge_state_status == "CLEAN"

  (this defers required-check and required-review policy to GitHub after the merge computation is bound to the independently proven current base and current head),

  base_ref_blocker == null

  ,

  checks_terminal

  is true (nothing still running), there is zero actionable backlog —

  counts.threads == 0

  and

  counts.comments == 0

  (no unresolved inline threads and no un-acted top-level/review-body feedback) — and

  open_needs_human == 0

  (a thread or comment you deferred for a human decision means it is not ready — surface it, do not call it merge-ready), and

  branch_currency_blocker == null

  (no open, claimed, or parked base-movement item), and

  quiet_seconds

  has reached the settle threshold and either the review-still-expected guard below is clear (no in-progress review signal, and any expected reviewer has reviewed the current head) or its only uncleared condition is an incomplete lifecycle that the bounded stale protocol below says must stop (at 15 quiet minutes without concrete slower prior-round timing, or at the 30-minute terminal ceiling after an evidence-based extension). "Mergeable against current base" does not mean the PR head contains the latest base commit:

  BEHIND

  ,

  DIRTY

  , branch-protection requirements, or an explicitly selected always-current policy may require maintenance, while ordinary base movement with GitHub reporting

  CLEAN

  does not. Chain state further qualifies that result: a managed target requires

  target_needs_rebase == false

  ; call it "ready as the next PR in the stack", never independently ready, and list stale upstack entries separately. In a manual dependency chain, call it "ready relative to its parent" and name any open parent that must land first. Base identity

  race

  ,

  mergeability-pending

  , or

  probe-error

  , chain

  probe-error

  , or unknown managed freshness blocks readiness only until a fresh observation proves the result. The settle threshold is the script's 300s default; the only thing that ever widens it is the re-arm after a rejected

  merge-ready

  wake (the wake protocol below) — never pre-widen the initial arm, review bots or not. The settle window is a cooling-off signal — evidence the PR stopped moving, not a guarantee no further review is coming. Before you report it ready, reflect on PR-description freshness (the final checkpoint). A watch full of incremental commits — fixes, new behavior, resolved feedback, a base-into-head merge — routinely leaves the original PR description describing a PR that no longer exists. If what the PR now does has materially drifted from its description (new/removed behavior, a changed approach, resolved caveats), refresh it autonomously: invoke

  ce-commit-push-pr

  in description-update mode, non-interactively (

  mode:pipeline

  — it rewrites and applies via

  gh pr edit

  directly, no preview prompt). Do not ask — a current description is part of leaving a PR merge-ready, and updating it is one of

  ce-commit-push-pr

  's own functions. If the description still reflects the change, leave it untouched. Report an independent PR as "looks ready — your call to merge," never "safe to merge." For a confirmed managed stack, apply the transition paragraph above before treating this layer stop as the whole run's stop. In checkpoint mode you cannot enforce elapsed time between manual re-runs, so if it is otherwise clean but

  quiet_seconds

  is under the threshold, say "green now, re-run in ~5 min to confirm it stayed quiet before merging."
• Blocked on external CI approval, after draining review —

  checks_awaiting_approval > 0

  with no actionable backlog means a workflow is awaiting a base-repo maintainer's approval to run (GitHub's fork-PR security gate). Neither you nor the loop can trigger it; never auto-approve the run. CI is blocked, but review may still move independently, so the first

  blocked_external

  observation is not an interactive stop:
  • Interactive self-sustaining watch: without asking, inspect the current-head review lifecycle and re-arm at the normal active cadence (

    --interval 150

    ) with

    --blocked-external-drain-seconds 300

    when no incomplete lifecycle has been observed, or

    --blocked-external-drain-seconds 900

    when a reviewer is present/in progress, disappeared without a done signal, or reviewed an earlier head. The helper persists a narrow head-scoped clock: new or edited external feedback, review submission/signal movement, or a new head resets it; an unchanged approval gate, the loop's own replies, check/base/stack movement, and disposition-only bookkeeping do not. Incoming feedback still wakes ahead of the gate — resolve it immediately, then re-arm the drain on the new evidence. If approval clears, return to the ordinary CI watch.
  • Drain expiry:

    blocked-external-drained

    is the decision wake. At 900 quiet seconds, concrete prior current-head timing from the same reviewer may justify one re-arm with

    --blocked-external-drain-seconds 1800

    ; it may never shorten the 900-second floor or extend beyond 1800 on a merely missing completion marker. With no incomplete lifecycle, 300 seconds is terminal. Only an explicit user request to keep watching the approval gate for a longer stated duration overrides these defaults, and it remains capped by this invocation's original budget.
  • Handback: once the selected drain expires with the gate still present, stop without asking another question. Report that all observed feedback was handled, how long the current head was review-quiet, that CI never ran because maintainer approval is still required, and give the host-rendered resume invocation. A later notification or explicit re-invocation starts the next bounded watch.
  • Pipeline / unattended: do not drain, ask, or spin — return a

    blocked-external

    residual with the run URL and terminate. Its bounded orchestrator contract explicitly does not wait on human review or approval.
  • Checkpoint: process the current tick, report the gate, state that monitoring is paused, and give the resume invocation; it cannot enforce elapsed drain time itself.
• Budget exhausted — active

  invocation_elapsed_seconds

  reaches the fixed invocation budget (default 8h of active watch time, or the duration the user selected at entry), or raw wall-clock reaches the 3-calendar-day backstop, a round-count cap the user set, or the user aborts. The

  max-runtime

  wake names which ceiling fired via

  max_runtime_ceiling

  (

  active-budget

  or

  backstop

  ). Watch re-arms and confirmed-managed-stack layer transitions must match the original ID, start, and budget; they can neither reset nor extend the cap and preserve accumulated dead time. The deadline's final refresh may still report

  terminal

  or an already-settled

  merge-ready

  ; both stop immediately and start no new work. Otherwise

  max-runtime

  outranks actionable/residual work so no additional agent round begins. On

  max-runtime

  , report the emitted

  invocation_elapsed_seconds

  and budget, never

  persisted_state_age_seconds

  , and do not automatically mint another invocation. This is the blunt cost floor beneath the trajectory-driven non-convergence stop above — it catches a runaway that never trips the convergence trigger, not the normal way a stuck PR ends. A bounded invocation hands control back; only a later explicit user/orchestrator invocation starts another budget.