{
  "type": "<event-type>",
  "ticketId": "PROJ-123",
  "ts": "2026-05-05T22:30:00Z",
  "payload": { "...": "event-specific fields" }
}

{ "type": "ticket-ready", "ticketId": "PROJ-123", "ts": "...", "payload": {} }

{
  "type": "pr-comment",
  "ticketId": "PROJ-123",
  "ts": "2026-05-05T22:30:00Z",
  "payload": {
    "prNumber": 123,
    "repoSlug": "owner/repo",
    "commentId": 9876543210,
    "commentKind": "issue|review",
    "author": "chatgpt-codex-connector",
    "createdAt": "2026-05-05T22:29:58Z"
  }
}

{
  "ticketId": "PROJ-123",
  "worktreePath": "/absolute/path/to/worktree",
  "branchName": "feat/...",
  "baseBranch": "main",
  "repoSlug": "owner/repo",
  "prNumber": 123,
  "phase": "setup|watch|teardown",
  "convergenceCommentPosted": false,
  "lastHandledEventTs": null,
  "lastHandledEventType": null
}

ticket_id = $1
event = parse_json($2)
validate_event(event)
require_equal(event.ticketId, ticket_id)
# State load is deferred until after the §5 pre-check guards. For a
# first-time ticket, load_or_create_state writes a default skeleton
# to ~/.claude/workon-event/<TICKET-ID>.json — running it before the
# pre-check would mutate disk on the stale and pre-check-error paths,
# which the contract says write no state. See "Pre-handler steps" above.

# Unknown event types reach this point because §2 validation only enforces
# the per-type payload contract for known types — an unrecognized type
# passes top-level shape validation and falls through to handle_unknown,
# which emits the result: "unknown" line required by §6. A bare
# DISPATCH_TABLE[type] would raise before logging, breaking the contract.
handler = DISPATCH_TABLE.get(event.type, handle_unknown)
dispatched_event = event

# Short-circuit unknown event types BEFORE load_or_create_state. Per §3
# and §7, the "unknown" outcome is a no-state-mutation rejection path —
# but load_or_create_state writes a default skeleton for first-time
# tickets, so falling through to the post-pre-check load below would
# create ~/.claude/workon-event/<TICKET-ID>.json on disk for a typo'd
# event type that was never actually handled. Emit the unknown line and
# exit before any state I/O happens.
if event.type not in DISPATCH_TABLE:
    log_unknown(ticket_id, event.ts, event.type, f"unhandled event type: {event.type}")
    exit 1

if event.type in PR_KEYED_EVENTS:
    # Single gh pr view call returns every field needed for both
    # the routing decision and the rerouted payload synthesis below.
    # See §5 for the full --json list. Any non-zero exit or JSON
    # parse failure from this call is reported as result:
    # "pre-check-error" without writing state, so the dispatcher
    # can safely re-deliver after the underlying problem clears.
    try:
        pr_view = gh_pr_view(event.payload.repoSlug, event.payload.prNumber)
    except GhPrViewError as err:
        log_pre_check_error(event, err)
        exit 1
    if pr_view.state == "MERGED" and event.type != "pr-merged":
        log_rerouted(event, "pr-merged")
        handler = handle_pr_merged
        # mergeCommitSha is optional in §2 and is only sourced from
        # pr_view.mergeCommit.oid when GitHub actually returned a
        # mergeCommit object. PRs whose merge mode does not produce
        # a stable merge commit (and not-yet-merged PRs) get null
        # back; a blind dereference would crash before the handler
        # runs and trip the dispatcher into infinite retries.
        merged_payload = {
            "prNumber": event.payload.prNumber,
            "repoSlug": event.payload.repoSlug,
            "mergedAt": pr_view.mergedAt,
            "mergedBy": pr_view.mergedBy,
        }
        if pr_view.mergeCommit is not None:
            merged_payload["mergeCommitSha"] = pr_view.mergeCommit.oid
        dispatched_event = synthesize_event(
            type      = "pr-merged",
            ticketId  = event.ticketId,
            ts        = event.ts,
            payload   = merged_payload,
        )
    elif pr_view.state == "CLOSED" and event.type != "pr-closed":
        # GitHub is the source of truth: a CLOSED-not-merged PR routes to
        # handle_pr_closed even when the originating event was mislabeled
        # as pr-merged. The merged branch above only fires when GitHub
        # itself reports MERGED, so this elif cannot run for a truly
        # merged PR.
        log_rerouted(event, "pr-closed")
        handler = handle_pr_closed
        dispatched_event = synthesize_event(
            type      = "pr-closed",
            ticketId  = event.ticketId,
            ts        = event.ts,
            payload   = {
                "prNumber": event.payload.prNumber,
                "repoSlug": event.payload.repoSlug,
                "closedAt": pr_view.closedAt,
                # closedBy is intentionally omitted — gh pr view --json does
                # not expose it. See §5 for how downstream handlers fetch
                # closer identity when needed.
            },
        )
    elif pr_view.state == "OPEN" and event.type in ("pr-merged", "pr-closed"):
        # Stale teardown guard. The event claims the PR is merged or closed,
        # but GitHub reports it is still open — this is a delayed,
        # out-of-order, or post-reopen delivery. "GitHub is source of truth"
        # means we must not run destructive teardown (worktree cleanup,
        # state archival) against a live PR. Emit a structured `stale`
        # outcome and exit without dispatching to a handler. State is not
        # written for stale events: lastHandledEvent* must reflect handlers
        # that actually ran.
        log_stale(event, pr_view.state)
        exit 1

# All pre-check guards have passed (validation, ticket-ID consistency,
# pre-check-error, stale). Only now is it safe to touch the state file:
# load_or_create_state may write the default skeleton for a first-time
# ticket, and that disk write must not happen on any rejection path.
state = load_or_create_state(ticket_id)

handler(ticket_id, dispatched_event, state)

state.lastHandledEventTs   = event.ts
state.lastHandledEventType = event.type
save_state(state)
exit 0

DISPATCH_TABLE = {
  "ticket-ready":       handle_ticket_ready,
  "pr-comment":         handle_pr_comment,
  "pr-push":            handle_pr_push,
  "pr-ci-failure":      handle_pr_ci_failure,
  "pr-base-advanced":   handle_pr_base_advanced,
  "pr-merged":          handle_pr_merged,
  "pr-closed":          handle_pr_closed,
  "convergence-check":  handle_convergence_check,
}

PR_KEYED_EVENTS = {
  "pr-comment", "pr-push", "pr-ci-failure",
  "pr-base-advanced", "pr-merged", "pr-closed",
  "convergence-check",
}

handle_ticket_ready(ticket_id, event, state):
    # Real implementation — see "§3.1 ticket-ready handler" section below.
    ticket_ready_handler(ticket_id, event, state)

handle_pr_comment(ticket_id, event, state):
    # Real implementation — see "§4.3 pr-comment handler" section below.
    pr_comment_handler(ticket_id, event, state)

handle_pr_push(ticket_id, event, state):
    log_event("pr-push", ticket_id, event.ts,
              f"stub: pr-push handler not yet implemented (sha={event.payload.sha})")

handle_pr_ci_failure(ticket_id, event, state):
    # Real implementation — see "§4.4 pr-ci-failure handler" section below.
    pr_ci_failure_handler(ticket_id, event, state)

handle_pr_base_advanced(ticket_id, event, state):
    # Real implementation — see "§4.2 pr-base-advanced handler" section below.
    pr_base_advanced_handler(ticket_id, event, state)

handle_pr_merged(ticket_id, event, state):
    # Real implementation — see "§5 Teardown handlers" section below.
    teardown_merged_handler(ticket_id, event, state)

handle_pr_closed(ticket_id, event, state):
    # Real implementation — see "§5 Teardown handlers" section below.
    teardown_closed_handler(ticket_id, event, state)

handle_convergence_check(ticket_id, event, state):
    log_event("convergence-check", ticket_id, event.ts, "stub: convergence handler not yet implemented")

handle_unknown(ticket_id, event, state):
    # log_unknown — NOT log_event — so result is "unknown" per §6,
    # not "stub". Misclassifying as "stub" would tell the dispatcher
    # the unsupported event was successfully handled.
    #
    # In practice the §4 dispatch loop short-circuits unknown event
    # types before load_or_create_state runs, so this body is invoked
    # via the short-circuit's log_unknown call, not through the
    # handler signature above. The signature is preserved for
    # symmetry with the other stubs and for direct test invocation.
    log_unknown(ticket_id, event.ts, event.type, f"unhandled event type: {event.type}")
    exit 1

result:"noop:already-set-up"

ticket_ready_handler(ticket_id, event, state):
    REPO        = event.payload.repoSlug  # passed via event or derived from runner env
    STATE_FILE  = "~/.claude/workon-event/{ticket_id}.json"

    # ── 1. Call helper to determine next step ──
    #
    # bun run src/workflows/workon-event/main.ts setup <ticket-id> <repo> [state-file]
    # Returns JSON: { nextStep, livePrState, liveHasAgenticLabel, noop }
    # nextStep values: transition-in-progress | create-pr | apply-label |
    #                  invite-codex | transition-in-review | complete
    setup_result = shell("""
      bun run src/workflows/workon-event/main.ts setup \
        "$ticket_id" "$REPO" "$STATE_FILE"
    """)

    # ── 2. Idempotency guard ──
    if setup_result.noop == true:
        echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"ticket-ready","eventTs":"'"$event.ts"'","result":"noop:already-set-up","note":"all four responsibilities complete, PR open with agentic label"}'
        return

    # ── 3. Loop through each mandatory responsibility ──
    #
    # After each step, persist the updated flag, then call the helper again
    # to get the next step. Repeat until nextStep="complete". Never stop after
    # only one step — all four are mandatory.
    while setup_result.nextStep != "complete":
        match setup_result.nextStep:

            case "transition-in-progress":
                # Responsibility 1: move ticket to In Progress before any code exists.
                mcp__claude_ai_Linear__save_issue(
                    id=<linear-issue-id-for-ticket_id>,
                    stateId=<in-progress-state-id>
                )
                state.ticketTransitionedToInProgress = true
                persist(state, STATE_FILE)

            case "create-pr":
                # Responsibility 2: implement the ticket and open a draft PR.
                #
                # Read the ticket body via mcp__claude_ai_Linear__get_issue to understand scope.
                # Create branch off main (naming: feat/<slug> or fix/<slug>).
                # Work in GITHUB_WORKSPACE (the runner's checkout root — no sub-worktree
                # for ticket-ready since there is no existing PR).
                # Apply the lean-diff skill throughout: targeted edits, no drive-by
                # reformatting/renaming, no unrequested abstractions.
                # Run quality gates before opening the PR (typecheck, lint, tests).
                #
                # Scope-budget check fires here, before gh pr create:
                #   git fetch origin "$BASE_BRANCH"
                #   read loc_ins loc_del < <(git diff --shortstat "origin/$BASE_BRANCH"...HEAD | grep -oP '\d+(?= insertion)' ; git diff --shortstat ... | grep -oP '\d+(?= deletion)')
                #   LOC=$(( loc_ins + loc_del ))
                #   files=$(git diff --name-only "origin/$BASE_BRANCH"...HEAD | wc -l)
                #   if over_budget(LOC, files, budget): halt (post Linear comment, exit 1)
                #
                # If a previous PR was already in state (closed PR being replaced):
                #   clear post-PR flags before persisting the new number:
                #   state.agenticLabelApplied = false
                #   state.codexReviewInvited = false
                #   state.ticketTransitionedToInReview = false
                gh pr create --draft --title "<title>" --body "<body>" --repo "$REPO"
                state.prNumber = <new-pr-number>
                persist(state, STATE_FILE)

            case "apply-label":
                # Responsibility 2b: label the PR so it's visible to watch loops.
                gh pr edit "$state.prNumber" --add-label agentic --repo "$REPO"
                state.agenticLabelApplied = true
                persist(state, STATE_FILE)

            case "invite-codex":
                # Responsibility 3: invite Codex after label is confirmed.
                gh pr comment "$state.prNumber" --body "@codex review" --repo "$REPO"
                state.codexReviewInvited = true
                persist(state, STATE_FILE)

            case "transition-in-review":
                # Responsibility 4: move ticket to In Review after label+comment confirmed.
                mcp__claude_ai_Linear__save_issue(
                    id=<linear-issue-id-for-ticket_id>,
                    stateId=<in-review-state-id>
                )
                state.ticketTransitionedToInReview = true
                persist(state, STATE_FILE)

        # Re-query helper to get the next step.
        setup_result = shell("""
          bun run src/workflows/workon-event/main.ts setup \
            "$ticket_id" "$REPO" "$STATE_FILE"
        """)

    # ── 4. Finalize ──
    state.phase = "watch"
    persist(state, STATE_FILE)

    echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"ticket-ready","eventTs":"'"$event.ts"'","result":"acted","note":"setup complete, PR #'"$state.prNumber"' opened and handed to Codex"}'

pr_comment_handler(ticket_id, event, state):
    PR   = event.payload.prNumber
    REPO = event.payload.repoSlug
    watermark_iso = state.lastAddressedCommentISO   # null on first run
    watermark_ids = state.lastAddressedCommentIds   # [] on first run

    # ── 1. Fetch all reviewer issue comments on the PR ──
    #
    # --paginate is required; --slurp cannot be combined with --jq
    # (unsupported by gh); use external jq -s 'add // []' to merge pages.
    # Filter to automated-reviewer authors with an anchored, case-insensitive
    # regex covering both supported bots:
    #   codex|chatgpt → Codex      (chatgpt-codex-connector, codex* logins)
    #   coderabbit    → CodeRabbit (coderabbitai, coderabbitai[bot])
    # (CodeRabbit added alongside the original codex|chatgpt filter.)
    #
    # CodeRabbit posts its summary, walkthrough, and status as PR *issue*
    # comments carrying an auto-generated marker — an HTML comment naming
    # `coderabbit.ai` (e.g. `<!-- This is an auto-generated comment: summarize
    # by coderabbit.ai -->`) or a `walkthrough_start` marker. Those are
    # informational, not actionable findings, so they are excluded here:
    # replying to them only adds noise, and CodeRabbit's actionable findings
    # arrive as review (inline) comments fetched in step 2. Codex issue
    # comments carry no such marker and are kept.
    issue_comments = shell("""
      gh api "repos/$REPO/issues/$PR/comments" --paginate \
        | jq -s 'add // [] | [.[] | select(
            (.user.login | test("codex|chatgpt|coderabbit"; "i")) and
            ((.body | test("<!--[^>]*coderabbit\\.ai|walkthrough_start"; "i")) | not)
          )]'
    """)

    # ── 2. Fetch all reviewer review (inline/line-level) comments ──
    #
    # /pulls/$PR/comments returns review comments. Same reviewer-author regex
    # (codex|chatgpt|coderabbit) — this is where CodeRabbit's actionable
    # line-level findings live. Filter replies (in_reply_to_id != null) — only
    # top-level comments are actionable findings; a reply to a prior reply is
    # not an open question for this handler. Note: this endpoint uses
    # snake_case, not camelCase.
    review_comments = shell("""
      gh api "repos/$REPO/pulls/$PR/comments" --paginate \
        | jq -s 'add // [] | [.[] | select(
            (.user.login | test("codex|chatgpt|coderabbit"; "i")) and
            (.in_reply_to_id == null)
          )]'
    """)

    # ── 3. Deduplicate against the watermark ──
    #
    # A comment is already-addressed when:
    #   (a) its createdAt is strictly before watermark_iso, OR
    #   (b) its createdAt equals watermark_iso AND its namespaced key is in
    #       watermark_ids.
    # Namespace: issue comments use "issue:<id>", review comments use "review:<id>".
    # This prevents cross-endpoint ID collisions (GitHub issue IDs and review
    # comment IDs share a numeric space).
    new_issue_comments   = [c for c in issue_comments
                            if not already_addressed(c.id, "issue", c.created_at,
                                                     watermark_iso, watermark_ids)
                            and not c.body.startswith("<!-- workon-event-reply -->")]

    new_review_comments  = [c for c in review_comments
                            if not already_addressed(c.id, "review", c.created_at,
                                                     watermark_iso, watermark_ids)]

    # Merge and sort oldest-first so comments are processed in the order
    # they were written. Both endpoints use independent ordering; a global
    # sort prevents a newer comment from the other stream from being
    # processed before an older one, which would advance the watermark
    # past the older one and drop it permanently.
    all_new = sort_by_created_at(
        [(c, "issue")  for c in new_issue_comments] +
        [(c, "review") for c in new_review_comments]
    )

    if len(all_new) == 0:
        log_event("pr-comment", ticket_id, event.ts,
                  f"no new reviewer comments newer than watermark={watermark_iso}")
        return  # state.lastHandledEvent* written by dispatch loop

    # ── 4. Address each new reviewer comment ──
    #
    # Work in the PR's worktree. The worktree path is in state.worktreePath
    # (set by the setup handler). Verify it exists before starting; if it
    # doesn't, post a Linear escalation comment and exit non-zero so the
    # dispatcher retries.
    if not path_exists(state.worktreePath):
        post_linear_comment(ticket_id,
            f"pr-comment handler: worktree {state.worktreePath} not found. "
            f"PR #{PR} in {REPO}. Manual intervention may be needed.")
        exit 1

    addressed_comments = []  # list of (id, namespace, createdAt) for watermark update

    for (comment, ns) in all_new:
        comment_id  = comment.id          # numeric GitHub ID
        comment_iso = comment.created_at  # ISO-8601

        if ns == "review":
            # For review comments: fetch the thread node ID needed for
            # resolveReviewThread mutation. Use the REST comment ID to
            # look up the GraphQL node ID via the reviews endpoint:
            #   gh api graphql -f query='
            #     query($id: Int!, $repo: String!, $owner: String!) {
            #       repository(owner: $owner, name: $repo) {
            #         pullRequest(number: $id) {
            #           reviewThreads(first: 100) {
            #             nodes {
            #               id
            #               isResolved
            #               comments(first: 1) { nodes { databaseId } }
            #             }
            #           }
            #         }
            #       }
            #     }' -F id=$PR -f repo=<repo-name> -f owner=<owner>
            # Match threads whose first comment's databaseId == comment.id.
            # Store the thread node ID for later resolution.
            thread_id = resolve_thread_id(REPO, PR, comment_id)

        # Read the comment body and decide: fix or explain-and-resolve.
        body = comment.body

        # Bucket the finding — the bar is deliberately strict because review
        # bots get nit-picky as a diff gets clean (mirrors workon §4.3):
        #   fix     — directly related to this PR's change, or genuinely
        #             catastrophic; those two conditions are the whole test.
        #   explain — everything else. Valid but unrelated: acknowledge, cite
        #             the follow-up ticket that carries the real obstacle
        #             (a finding this diff caused still defers, with that fact
        #             stated). Invalid: give the one-line reason so the next
        #             event doesn't relitigate it.

        decision = judge_comment(body)  # "fix" | "explain"

        if decision == "fix":
            apply_fix_in_worktree(state.worktreePath, body)
            # Commit message follows workon §4.3: descriptive when possible,
            # generic fallback.
            commit_message = derive_commit_message(body) or "fix: address reviewer feedback"
            git_commit(state.worktreePath, commit_message)
        else:
            # Post a reply explaining the decision. The reply sentinel
            # "<!-- workon-event-reply -->" must be the FIRST thing in the
            # body so future fetches can exclude it from the reviewer-comment
            # list and prevent self-reply loops.
            reply_body = "<!-- workon-event-reply -->\n" + explanation(body)
            if ns == "review":
                # Reply to a review comment thread:
                gh api "repos/$REPO/pulls/$PR/comments" \
                    --method POST \
                    -f body="$reply_body" \
                    -F in_reply_to=$comment_id
            else:
                # Reply to an issue comment (general PR comment):
                gh api "repos/$REPO/issues/$PR/comments" \
                    --method POST \
                    -f body="$reply_body"

        addressed_comments.append((comment_id, ns, comment_iso))

        # ── 5. Resolve the review thread ──
        #
        # REQUIRED after addressing a review comment, regardless of whether
        # the fix was applied or the comment was replied to. Pushing a commit
        # does NOT auto-resolve GitHub review threads — only calling
        # resolveReviewThread does. Leaving threads open makes addressed
        # findings look like open work to human reviewers.
        if ns == "review" and thread_id is not None:
            gh api graphql -f query='
              mutation($id: ID!) {
                resolveReviewThread(input: {threadId: $id}) {
                  thread { id isResolved }
                }
              }' -F id="$thread_id"

    # ── 6. Single push ──
    #
    # Push all commits accumulated in this handler invocation in one shot.
    # Never push per-comment — each push resets the 30-minute convergence
    # clock and burns a CI run. If there are no new commits (all comments
    # were explain-and-resolve), skip the push.
    if git_has_unpushed_commits(state.worktreePath, state.branchName):
        git push origin HEAD  # from within state.worktreePath

    # ── 7. Advance the watermark ──
    #
    # Boundary-second semantics (see watermark.ts for the full contract):
    #   - Find the max createdAt among addressed_comments.
    #   - If it is newer than watermark_iso → replace lastAddressedCommentIds.
    #   - If it equals watermark_iso → merge (union) the ID sets.
    #   - If it is older → no change (should not happen under normal operation).
    new_iso = max(c.createdAt for c in addressed_comments)
    if watermark_iso is None or new_iso > watermark_iso:
        state.lastAddressedCommentISO = new_iso
        state.lastAddressedCommentIds = [
            f"{ns}:{cid}" for (cid, ns, created) in addressed_comments
            if created == new_iso
        ]
    elif new_iso == watermark_iso:
        new_keys = {f"{ns}:{cid}" for (cid, ns, created) in addressed_comments
                    if created == new_iso}
        state.lastAddressedCommentIds = list(
            set(watermark_ids) | new_keys
        )
    # else: new_iso < watermark_iso → no change

    log_event("pr-comment", ticket_id, event.ts,
              f"addressed {len(addressed_comments)} reviewer comment(s) "
              f"on PR #{PR}; pushed={git_has_unpushed_commits_was_true}")

echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"pr-comment","eventTs":"'"$event_ts"'","result":"acted","note":"'"$summary"'"}'

echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"pr-comment","eventTs":"'"$event_ts"'","result":"noop:nothing-actionable","note":"no new reviewer comments newer than watermark"}'

pr_ci_failure_handler(ticket_id, event, state):
    PR         = event.payload.prNumber
    REPO       = event.payload.repoSlug
    check_id   = event.payload.checkRunId
    check_name = event.payload.checkName
    conclusion = event.payload.conclusion

    # ── 1. Re-read current check state — the event may be stale ──
    #
    # The dispatcher fires this handler when a check turns red, but CI can
    # self-recover (e.g. a transient outage clears, a re-run was manually
    # triggered). Re-fetch the specific run's conclusion before doing any
    # work; if it has since passed, no action is needed.
    #
    # GET /repos/{owner}/{repo}/check-runs/{check_run_id}
    live_run = gh api "repos/$REPO/check-runs/$check_id"
    if live_run.conclusion == "success":
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-ci-failure","eventTs":"' + event.ts + '","result":"noop:check-already-passed","note":"check ' + check_name + ' now passing — no fix needed"}')
        return

    # ── 2. Classify the failure: flaky vs. deterministic ──
    #
    # Flaky signals: `conclusion == "timed_out"`, or the check name matches
    # known infra-noise patterns (e.g. "upload-artifact", "cache", network
    # errors in logs). Also treat a fresh failure on a check that passed on
    # the immediately prior run as a candidate flake.
    #
    # Strategy: rerun once if the failure looks flaky; if it fails again, or
    # if the failure looks deterministic from the start, diagnose and fix.
    #
    # Avoid re-running the same run_id twice in a row — GitHub deduplicates
    # re-run requests on the same check-run within a short window, so a
    # double-rerun emits a 422 and wastes an API call. Guard with
    # state.lastRetriedCheckRunId: if check_id == state.lastRetriedCheckRunId,
    # skip straight to the diagnose-and-fix path. The state field is nil until
    # first set here.

    is_likely_flaky = (conclusion == "timed_out") or looks_infra_noise(live_run.output.text)

    if is_likely_flaky and state.lastRetriedCheckRunId != check_id:
        # Rerun once before diagnosing.
        #
        # `gh run rerun --failed` re-queues only the failed jobs, not the
        # full workflow. Requires `actions:write`. The check-run belongs to a
        # workflow run; extract the workflow run ID from the check-run object.
        #
        # GET /repos/{owner}/{repo}/check-runs/{id} returns
        # check_suite.id — that is the check-suite, not the workflow run.
        # Resolve the workflow run id via:
        #   gh api "repos/$REPO/actions/runs?check_suite_id=<suite_id>"
        #   and pick runs[0].id.
        # Then rerun:
        #   gh run rerun <workflow_run_id> --failed --repo "$REPO"
        suite_id     = live_run.check_suite.id
        runs_page    = gh api "repos/$REPO/actions/runs?check_suite_id=$suite_id"
        workflow_run_id = runs_page.workflow_runs[0].id
        gh run rerun "$workflow_run_id" --failed --repo "$REPO"

        state.lastRetriedCheckRunId = check_id
        # Emit a structured result so the dispatcher knows a rerun was issued
        # and should re-evaluate when the rerun completes.
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-ci-failure","eventTs":"' + event.ts + '","result":"acted","note":"rerun issued for likely-flaky check ' + check_name + ' (run ' + str(workflow_run_id) + '); awaiting outcome"}')
        return  # state.lastHandledEvent* + lastRetriedCheckRunId written by dispatch loop

    # ── 3. Diagnose from failing logs ──
    #
    # Fetch the annotated log for the failed jobs only. This avoids pulling
    # multi-megabyte success logs and focuses the diagnostic context.
    #
    #   gh run view <workflow_run_id> --log-failed --repo "$REPO"
    #
    # The log is streamed to stdout; capture it and scan for the first
    # clearly actionable error region (compile error, lint failure, test
    # assertion, type error). Trim to ≤200 lines of context around the first
    # error — models and readers lose signal past that threshold.
    if state.lastRetriedCheckRunId == check_id:
        # Already retried once; we need the new workflow run id from the
        # re-queued run, but since the re-run produces a new check_run_id,
        # a re-delivery of pr-ci-failure from the dispatcher will carry the
        # new check_id. If we're here with the same check_id post-rerun, the
        # rerun itself failed — use the same run for diagnosis.
        suite_id     = live_run.check_suite.id
        runs_page    = gh api "repos/$REPO/actions/runs?check_suite_id=$suite_id"
        workflow_run_id = runs_page.workflow_runs[0].id
    # else: workflow_run_id was resolved in step 2 for the fresh-fail path

    log_text = gh run view "$workflow_run_id" --log-failed --repo "$REPO"
    failure_summary = extract_first_error_region(log_text, max_lines=200)

    # ── 4. Decide: fixable vs. needs-human ──
    #
    # Fixable in this handler:
    #   - TypeScript type errors in files we own (tsc output, jest type errors)
    #   - Lint rule violations with a clear auto-fix path (eslint, prettier)
    #   - Test failures caused by a deterministic assertion that matches the
    #     current diff (i.e. the test was checking old behavior we changed)
    #   - Missing generated file (e.g. a catalog regeneration step failed
    #     because a source file changed but the generated output wasn't updated)
    #
    # Escalate if:
    #   - The failure is in infrastructure we don't own (third-party service
    #     calls, Docker build environment, external network timeouts on
    #     non-flaky-patterned runs)
    #   - The error message suggests a secret/permission problem
    #   - The failure is in a different PR's check that was grouped into the
    #     same workflow (rare but possible on mono-repo matrix builds)
    #   - We've already attempted and pushed a fix for this exact check_id
    #     in a prior invocation (state.lastFixedCheckRunId == check_id) —
    #     to avoid infinite fix loops, escalate instead of retrying

    unfixable = is_infra_failure(failure_summary) \
                or is_permission_failure(failure_summary) \
                or (state.lastFixedCheckRunId == check_id)

    if unfixable:
        reason = "already-attempted" if state.lastFixedCheckRunId == check_id else failure_summary[:120]
        post_linear_comment(ticket_id,
            f"pr-ci-failure handler: check '{check_name}' failed and cannot be fixed automatically. "
            f"PR #{PR} in {REPO}. Reason: {reason}. Manual intervention needed.")
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-ci-failure","eventTs":"' + event.ts + '","result":"escalated:needs-human","note":"' + reason[:120] + '"}')
        return

    # ── 5. Apply the fix in the worktree ──
    #
    # Verify the worktree is present before touching anything.
    if not path_exists(state.worktreePath):
        post_linear_comment(ticket_id,
            f"pr-ci-failure handler: worktree {state.worktreePath} not found. "
            f"Cannot apply fix for check '{check_name}' on PR #{PR} in {REPO}. "
            f"Manual intervention may be needed.")
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-ci-failure","eventTs":"' + event.ts + '","result":"error","note":"worktree missing: ' + state.worktreePath + '"}')
        exit 1

    # Work inside the worktree. Read the relevant source files identified by
    # the failure_summary, then apply the minimal fix. Commit with a message
    # that names the check so CI and reviewers can trace the commit to the
    # failure.
    apply_fix_in_worktree(state.worktreePath, failure_summary)
    commit_message = f"fix(ci): resolve {check_name} failure"
    git_commit(state.worktreePath, commit_message)

    # ── 6. Single push ──
    #
    # One push per invocation — matches §8's "one push per handler" rule.
    git push origin HEAD  # from within state.worktreePath

    # Record that we pushed a fix for this check_run_id so a subsequent
    # re-delivery of the same event (same check_id, same ts) is treated as
    # already-attempted rather than triggering a second fix attempt.
    state.lastFixedCheckRunId = check_id

    summary = f"applied fix for check '{check_name}' on PR #{PR}; pushed commit"
    print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-ci-failure","eventTs":"' + event.ts + '","result":"acted","note":"' + summary + '"}')

pr_base_advanced_handler(ticket_id, event, state):
    PR          = event.payload.prNumber
    REPO        = event.payload.repoSlug
    BASE_BRANCH = state.baseBranch  # e.g. "main"

    # ── 1. Re-read live merge state — the event may be stale ──
    #
    # `mergeStateStatus` in the event payload is an optional hint from the
    # dispatcher, captured at dispatch time. GitHub's state can change by the
    # time this handler runs (e.g. the conflict was resolved by another push,
    # or the base advanced again). Re-fetch from the API to avoid acting on
    # stale state.
    #
    # The §5 pre-check already called `gh pr view --json ... mergeable,mergeStateStatus`
    # before dispatch; the handler receives a fresh event but not the live view
    # result. Re-issue a targeted call here.
    pr_view = gh pr view "$PR" --repo "$REPO" --json mergeable,mergeStateStatus,headRefOid
    live_mergeable         = pr_view.mergeable           # "MERGEABLE" | "CONFLICTING" | "UNKNOWN"
    live_merge_state       = pr_view.mergeStateStatus    # "CLEAN" | "CONFLICTING" | "UNKNOWN" | ...
    current_head_sha       = pr_view.headRefOid

    # ── 2. Verify the worktree is present ──
    if not path_exists(state.worktreePath):
        post_linear_comment(ticket_id,
            f"pr-base-advanced handler: worktree {state.worktreePath} not found. "
            f"Cannot merge base into PR #{PR} in {REPO}. Manual intervention may be needed.")
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-base-advanced","eventTs":"' + event.ts + '","result":"error","note":"worktree missing: ' + state.worktreePath + '"}')
        exit 1

    # ── 3. Fetch and check if merge is needed ──
    #
    # Always fetch to make sure the local clone sees the latest base tip.
    git fetch origin "$BASE_BRANCH"  # from within state.worktreePath

    # If GitHub reports the PR is already MERGEABLE (no conflict), the base
    # advanced but did not produce a conflict — nothing to resolve. Still
    # confirm the local branch tip matches the remote HEAD to rule out a
    # local-only divergence.
    if live_mergeable == "MERGEABLE" and live_merge_state not in ("CONFLICTING", "UNKNOWN"):
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-base-advanced","eventTs":"' + event.ts + '","result":"noop:no-conflict","note":"base advanced but PR is MERGEABLE; no merge required"}')
        return

    # ── 4. Attempt the merge ──
    #
    # Run `git merge origin/<base>` in the worktree. Capture exit code and
    # stdout/stderr to distinguish clean merge from conflict.
    merge_result = git merge "origin/$BASE_BRANCH"  # from within state.worktreePath

    if merge_result.exit_code == 0:
        # Clean merge — no conflicts. Commit was created by git merge.
        # Push immediately.
        git push origin HEAD  # from within state.worktreePath
        summary = f"merged origin/{BASE_BRANCH} into PR #{PR} cleanly; pushed"
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-base-advanced","eventTs":"' + event.ts + '","result":"acted","note":"' + summary + '"}')
        return

    # ── 5. Conflict detected — attempt mechanical resolution ──
    #
    # Inspect `git status --porcelain` to identify conflicting files.
    # "Mechanical" conflicts are those where:
    #   (a) both sides modified the same file but in non-overlapping regions
    #       and a standard merge driver can produce a deterministic result, OR
    #   (b) one side deleted a file and the other modified it, and the deletion
    #       aligns with the intent of this PR (no heuristic guessing here —
    #       require that the deleted file is NOT in the PR's changed-file set;
    #       if it is, treat it as semantic).
    #
    # For all other conflicts — overlapping edits to the same region, logic
    # contradictions between the PR change and the incoming base change —
    # the handler cannot reliably resolve without semantic understanding of
    # both changes. Escalate rather than produce a broken merge.
    conflicting_files = list_conflicting_files(state.worktreePath)  # git status --porcelain | grep "^UU\|^AA\|^DD"

    # Check if git's standard 3-way merge left clean markers (no remaining
    # conflict markers in files). Some merge drivers resolve automatically
    # without producing conflict markers even on overlapping hunks.
    if has_no_conflict_markers(state.worktreePath, conflicting_files):
        # All conflicts were resolved by the merge driver automatically.
        git add -A  # from within state.worktreePath
        commit_message = f"chore: merge origin/{BASE_BRANCH} into branch (no conflicts)"
        git_commit(state.worktreePath, commit_message)
        git push origin HEAD
        summary = f"merged origin/{BASE_BRANCH} into PR #{PR} (auto-resolved); pushed"
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-base-advanced","eventTs":"' + event.ts + '","result":"acted","note":"' + summary + '"}')
        return

    # Attempt to resolve mechanical (non-semantic) conflicts:
    #   - files where both sides changed non-overlapping sections
    #     (conflict markers only exist in distinct regions — resolve by
    #     accepting both sides' changes in order: ours then theirs)
    #   - files where this PR did not touch the conflicting region at all
    #     (safe to accept "theirs" for that region)
    resolved, unresolvable = attempt_mechanical_resolution(state.worktreePath, conflicting_files)

    if len(unresolvable) > 0:
        # ── 6. Semantic conflict — escalate ──
        #
        # Abort the merge so the worktree is left clean (no partial merge
        # state). `git merge --abort` restores the pre-merge state. Then
        # verify compilation/tests still pass on the unmerged branch — the
        # worktree must remain in a shippable state so human intervention
        # can pick up where we left off.
        git merge --abort  # from within state.worktreePath

        conflict_list = ", ".join(unresolvable[:5])  # cap at 5 for readability
        if len(unresolvable) > 5:
            conflict_list += f" … and {len(unresolvable) - 5} more"

        post_linear_comment(ticket_id,
            f"pr-base-advanced handler: base branch '{BASE_BRANCH}' advanced into a semantic conflict "
            f"on PR #{PR} in {REPO}. Conflicting files require manual resolution: {conflict_list}. "
            f"The merge was aborted; the PR branch is untouched. Please resolve and push.")
        print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-base-advanced","eventTs":"' + event.ts + '","result":"escalated:needs-human","note":"semantic conflict in ' + str(len(unresolvable)) + ' file(s): ' + conflict_list + '"}')
        return

    # ── 7. Push resolved merge ──
    #
    # All conflicts were resolved mechanically. Stage, commit, push.
    git add -A  # from within state.worktreePath
    commit_message = f"chore: merge origin/{BASE_BRANCH} (resolve conflicts)"
    git_commit(state.worktreePath, commit_message)
    git push origin HEAD

    summary = f"merged origin/{BASE_BRANCH} into PR #{PR}; resolved {len(resolved)} conflict(s); pushed"
    print('{"skill":"workon-event","ticketId":"' + ticket_id + '","eventType":"pr-base-advanced","eventTs":"' + event.ts + '","result":"acted","note":"' + summary + '"}')

teardown_merged_handler(ticket_id, event, state):
    PR   = event.payload.prNumber
    REPO = event.payload.repoSlug

    # At-most-once guard (phase=teardown is set BEFORE the Linear write).
    teardown_state = normalizeTeardownState(state.teardown)
    if isTeardownComplete(teardown_state):
        echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"pr-merged","eventTs":"'"$event.ts"'","result":"noop:already-torn-down","note":"teardown already complete"}'
        return

    # Persist teardown phase first — at-most-once guard for the Linear comment.
    state.teardown = createTeardownMarker()
    state.phase    = "teardown"
    persist(state, STATE_FILE)

    # Post merge confirmation to Linear if not already posted.
    if shouldPostFinalComment(state.teardown):
        # Post a one-line note. Only post if convergence comment was not already sent
        # to avoid redundant messages — but convergenceCommentPosted is advisory only;
        # always post on merge so the ticket has a clear terminal marker.
        mcp__claude_ai_Linear__save_comment(
            issueId = <linear-issue-id-for-ticket_id>,
            body    = f"PR #{PR} merged into {REPO}."
        )
        state.teardown.finalCommentPosted = true
        persist(state, STATE_FILE)

    echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"pr-merged","eventTs":"'"$event.ts"'","result":"acted","note":"teardown complete; merge comment posted to Linear"}'

teardown_closed_handler(ticket_id, event, state):
    PR   = event.payload.prNumber
    REPO = event.payload.repoSlug

    # At-most-once guard.
    teardown_state = normalizeTeardownState(state.teardown)
    if isTeardownComplete(teardown_state):
        echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"pr-closed","eventTs":"'"$event.ts"'","result":"noop:already-torn-down","note":"teardown already complete"}'
        return

    # Persist teardown phase first.
    state.teardown = createTeardownMarker()
    state.phase    = "teardown"
    persist(state, STATE_FILE)

    # Post closed-without-merge note to Linear.
    if shouldPostFinalComment(state.teardown):
        mcp__claude_ai_Linear__save_comment(
            issueId = <linear-issue-id-for-ticket_id>,
            body    = f"PR #{PR} closed without merging ({REPO})."
        )
        state.teardown.finalCommentPosted = true
        persist(state, STATE_FILE)

    echo '{"skill":"workon-event","ticketId":"'"$ticket_id"'","eventType":"pr-closed","eventTs":"'"$event.ts"'","result":"acted","note":"teardown complete; closed-without-merge note posted to Linear"}'

# Inputs: REPO and PR from event.payload
gh pr view "$PR" --repo "$REPO" \
  --json state,mergeable,mergeStateStatus,mergedAt,mergedBy,mergeCommit,closedAt

{ "skill": "workon-event", "ticketId": "PROJ-123", "eventType": "pr-comment", "eventTs": "2026-05-05T22:30:00Z", "result": "stub", "note": "..." }