resolve-handoff

Output — the resolution handoff

The last thing in your final message must be exactly one fenced json code block — the machine-readable handoff, parsed by taking the last json fence in the message. Same discipline as repro-agent:

• Write whatever prose summary you like above it, but the ```json block is the last chunk of the message, with nothing after its closing fence. Do not split the handoff across multiple sections or emit a second data block.
• One exception (author path): you also emit an interim handoff right after opening the PR (Step 3.5) so the workflow can post the PR link to Linear before Step 4 finishes. That is fine — the caller reads the last valid handoff in the session, so this final one supersedes the interim block. The interim block carries pr_url + a provisional outcome; this final block is authoritative.
• Emit it as JSON, never YAML. Include every key below, always, even when a value is empty ("", []).
• mode must be exactly "reviewed_existing_pr", "authored_fix", or "review_remediation" — which entry path you took.
• outcome must be exactly one of the string literals "fixed", "partially_fixed", "not_fixed", "nothing_to_fix", "needs_more_info" — lowercase, no other wording. This is the field the caller reads, so it must match verbatim.

{
  "bug_url": "https://github.com/omnigent-ai/omnigent/issues/1234",
  "mode": "authored_fix",
  "outcome": "fixed",
  "problem_summary": "People see internal catalog IDs in the model picker instead of readable model names.",
  "solution_summary": "The model picker now shows a friendly name for every model.",
  "root_cause": "picker rendered raw catalog IDs because format_label() was never called on the option list",
  "fix_summary": "call format_label() when building picker options in web/src/model/picker.tsx",
  "review_body": "",
  "files_changed": ["web/src/model/picker.tsx"],
  "facets": [
    {"symptom": "picker display", "outcome": "fixed", "test_transition": "test_1234 failed: raw IDs shown → passes: friendly labels"},
    {"symptom": "catalog default", "outcome": "nothing_to_fix", "test_transition": "already_fixed in #3448; skipped"}
  ],
  "tests": {
    "e2e": "",
    "added": ["tests/web/model/test_picker_label.py::test_display_label"]
  },
  "recordings": [
    {"surface": "web", "kind": "before", "path": "recordings/1234/before-picker.webm", "format": "webm",
     "capture_mode": "playwright_ui",
     "caption": "open the model picker → select the catalog → picker shows raw IDs"},
    {"surface": "web", "kind": "after", "path": "recordings/1234/after-picker.mp4", "format": "mp4",
     "capture_mode": "playwright_ui",
     "caption": "open the model picker → select the catalog → picker now shows friendly names"}
  ],
  "recording_unavailable_reason": "",
  "test_audit": "Reused the display-label regression; the same assertions fail on base and pass on head. Browser reproduction evidence is staged in .omnigent/repro-evidence/; workflow upload is pending at <workflow run URL>, artifact resolve-bundle-<run-id>, path repro-evidence/. No additional browser boundary was found.",
  "impact_assessment": {
    "base_sha": "<full target-branch tip SHA>",
    "head_sha": "<full candidate HEAD SHA>",
    "worktree_state": "clean",
    "risks": [
      {
        "files": ["web/src/model/picker.tsx"],
        "behavior": "Changing labels can alter model selection or restoration",
        "consumers": ["model picker", "restored sessions"],
        "invariant": "Selections and restored sessions retain the same model IDs",
        "check": "<exact command exercising selection and session restoration>",
        "result": "passed",
        "evidence": "<retained output reference, tested build and environment>"
      }
    ],
    "uncovered_boundaries": [],
    "not_applicable_reason": ""
  },
  "remaining_work": [],
  "hermetic_check": "test_picker_label re-run with ambient env vars set — still passes",
  "pr_url": "https://github.com/omnigent-ai/omnigent/pull/4200",
  "reviewed_pr_url": "",
  "pushed_branch": "",
  "ci_status": "green (all required checks pass)",
  "polly_review": "clean on <full candidate HEAD SHA>: fixed null-deref; fresh review has no findings",
  "ocr_review": "clean on <full candidate HEAD SHA>: no findings",
  "review_cycle": {
    "head_sha": "<full candidate HEAD SHA>",
    "fingerprint": "<fingerprint from the final review snapshot>",
    "dispositions": [
      {"key": "comment:<id>", "status": "addressed", "reason": "Finding 1: null-deref fixed in <commit>; <test> passes. Finding 2: suggested fallback already exists at <path:line> and is covered by <test>, so not needed."}
    ]
  },
  "ui_preview": "labeled ui-preview on every PR; preview at https://…; posted connect instructions",
  "validation_surface": "server",
  "validation_prompt": "Reproduce and validate a bug fix. Steps: open the model picker in the catalog view… Before this fix, raw catalog IDs were shown. Confirm the fix by checking that friendly labels appear. Report whether each step now behaves correctly.",
  "maintainer_review": "requested review from @PattaraS (issue assignee)",
  "review_fingerprint": "",
  "handled_review_ids": [],
  "last_pushed_sha": "",
  "session_id": "dc59e331-..."
}

Field meanings:

For modes that drive an open PR, fixed also requires the Step 4.3 live gate to pass. Interim and workflow-owned implementation handoffs do not certify PR readiness; name pending publication/review steps in remaining_work.

• bug_url — the bug link, carried through from the recovered handoff.

• mode — reviewed_existing_pr (Step 2A: a candidate PR existed, you reviewed it and kept it as the fix) or authored_fix (Step 2B: you wrote the fix). Use authored_fix when you started from an existing PR but opened your own — for either reason: its approach wasn't viable (2A.5), or its approach was fine but it was an unpushable fork PR that needed a fix so you took it over (Step 4 preamble). In both cases name the reviewed/forked PR in your prose and reviewed_pr_url so the two stay linked. Use review_remediation only when the input supplied review_pr; in that mode preserve the existing PR and branch and address its requested changes directly.

• review_fingerprint / handled_review_ids / last_pushed_sha — populated in review-remediation mode for scanner deduplication and workflow retry recovery; otherwise "", [], and "".

• outcome — overall: fixed (every live facet resolved and proven — by your fix or by the reviewed PR — and the shared impact assessment has no unresolved required checks), partially_fixed, not_fixed (couldn't resolve, or the reviewed PR doesn't fix it), nothing_to_fix (recovered verdict was already_fixed/not_reproduced, or the 2B.1 audit showed main has since fixed it — name the fixing commit and recommend closing the ticket), or needs_more_info (couldn't recover a reliable reproduction, evidence is unsafe, required inputs/authorization are missing, or setup/environment blocks verification). When intended behavior is ambiguous, follow resolve-investigate: a supported proposal with an unresolved design choice is partially_fixed, with the choice in remaining_work. Do not describe it as a proven fix.

• problem_summary / solution_summary — the two user-facing paragraphs shown prominently in the Linear update under What's the problem? and How is it fixed? Write plain, natural English for someone who uses the product but has not read the code. problem_summary describes what the person experiences and why it matters. solution_summary describes the corrected behavior and result. Keep implementation symbols, filenames, commit/merge bookkeeping, test lists, and CI details out of both fields; those belong in the technical fields below. Include both fields even for review mode and no-change outcomes.

• root_cause / fix_summary / files_changed — the cause and the change. These are the technical details shown under Additional notes and used by publication/review fallbacks, so concrete symbols and filenames are welcome. In review mode, describe the reviewed PR's approach and leave files_changed empty (you changed nothing). Distinguish the observed symptom from the supported cause; include sources for historical intent, competing explanations checked, and any proposed policy change. Identify the real configuration path exercised and any substituted components. If the test assumes the suspected cause, retain it as a hypothesis and carry the missing proof into the outcome and remaining_work, following resolve-investigate. State missing evidence plainly; never include credentials. When the incident cause is unverified, start root_cause with that fact. Describe the tested mechanism separately from the hypothesis that it caused the incident; do not claim that incident link elsewhere in the summary. In test_audit, include the governing-definition citation and real configured-path observation requested by resolve-investigate, or the specific missing evidence; do not defer a feasible check merely to finish. Before finalizing test_audit, verify an actual defining-source read and the file, symbol and value for each governing shared definition. If none exists, record the bounded search; a filename or caller reference alone is insufficient. Execute missing feasible reads and keep unresolved definition gaps explicit. Distinguish observed effects from expected downstream behavior: unexercised reconnect or recovery paths remain unverified in every summary field.

• review_body — the PR-facing review text from Step 2A. Fill it in for reviewed_existing_pr, including workflow-owned publication; use "" in other modes. State the verdict and reason first, then separate the proof and any remaining action into short bullets. Do not paste root_cause, fix_summary, ci_status, or polly_review wholesale. The workflow publisher posts this field verbatim before adding the tested commit and marker, so it must stand alone as a useful review. Encode paragraph and bullet breaks as \n within the JSON string.

• facets — per-facet, mirroring the recovered breakdown: each with its own outcome and a test_transition (the fail→pass proof, or why it was skipped).

• tests — selected permanent regression coverage. e2e is the retained e2e path, or "" when none is needed. added keeps its legacy name but lists the other selected checks, including reused unchanged tests or extensions to an existing module. Each entry must be a bare repository-relative path or test node ID that resolves on the committed candidate. Do not append labels such as (reused unchanged), shell commands, or result summaries; put those in test_audit. Before handing off, check the file portion of every reference against the committed tree and use the same node IDs as the executed checks. Do not list artifact-only reproduction paths here. In comment-only review, keep the existing review procedure and do not commit temporary test source. Use test_audit for brief selection reasoning: reused/retained tests, why any new permanent e2e is necessary, and gaps. For reproduction-only evidence, give the run URL/artifact/path or verified persistent local path from 2B.4, plus its retention status; identify pending uploads and unresolved retention.

• recordings — your after-fix clips (kind: "after") and any recovered before-clips, using {surface, kind, path, format, capture_mode, caption}. Point each new clip's path at the inspected MP4 with timed captions burned in using dev/caption_recording.py per dev/recording-lanes.md. If captioning was blocked, retain the usable clip and disclose the blocker in evidence. Follow the recording rules in Step 2B.5 on both author and review runs; in review mode, record the reviewed PR head. Keep recovered before-clips and captions unchanged. Each after-clip's caption lists the actions shown, ending with the corrected behavior. A missing before-clip is not a reason to skip the after-clip. Use [] only for internal/API-only results with no visible user interaction, or when recording is blocked as described above.

• recording_unavailable_reason — leave empty when every expected clip is present. Otherwise explain each missing clip:

  • For internal/API-only results, say there is no visible user interaction and put the written before/after evidence in the PR Demo section.
  • For a recording failure, name the missing tool or the environment problem. Text-only CLI output is not a reason to skip recording.
  • Do not substitute a video of test output or a made-up demonstration. Missing or rejected footage must not block the fix or PR.

• test_audit — required in both author and review modes for reproduction-driven runs. Record the shared repro audit: patch-scope concerns, whether the original test was accepted/repaired/rejected and why, exact before/after revisions and commands, relevant environment/feature gates, behavioral fail→pass evidence, and any blockers. Preserve original evidence when repairing a test. A restored artifact or a green candidate run alone is not an audit.

• impact_assessment — required in every mode. Use the shared impact assessment above. base_sha is the target branch tip used for the comparison; the full diff starts at its merge-base with head_sha. worktree_state records tested dirt and content hashes, not just the final clean status. Each risks entry maps changed files and affected consumers to a preserved invariant, check, result, and evidence. Include required checks that failed or could not run; explain their gaps in uncovered_boundaries. Use empty SHAs/state only when stopping before a candidate can be identified, with not_applicable_reason. Otherwise leave that reason empty unless the inspected diff has no behavioral impact. This narrative does not certify execution or replace test_audit.

• remaining_work — a list of specific unresolved behavior, required checks, or delivery steps for partially_fixed; empty when none remain. Resolved original facets do not hide a regression or an uncovered required boundary.

• hermetic_check — the result of the Step 2B.5 hostile-env re-run when the diff touched env-derived defaults: which added/edited tests you re-ran with ambient vars set and that they still passed. Empty string when not applicable (no such test in the diff).

• pr_url — the PR you opened (author mode), including a draft proposal identified as such in fix_summary. Empty in review mode, when skip_push was set, or if you stopped before opening one.

• reviewed_pr_url — the existing PR you reviewed (review mode), or the fork PR you took over into your own (fork takeover — pr_url is then yours). Empty when you authored from scratch with no upstream PR.

• pushed_branch — the local branch holding the committed fix that you did not push because skip_push was set (author mode). Empty otherwise. A human pushes and opens the PR from it.

• ci_status — the result of the Step 4.2 CI loop (run on both paths now): green when the checks you're responsible for pass, otherwise the failing checks and whether each was diff-caused vs pre-existing/flaky/infra. If a fork PR needed a fix and you took over into your own PR, this reflects your PR's checks. Empty when skip_push was set or you stopped before there was a PR to land.

• polly_review / ocr_review — each reviewer's current-head result, rounds, run/comment links, fixes, and individually justified invalid/not-needed findings (including non-blocking notes). Missing, stale, skipped, failed, or undispatched reviews are explicitly incomplete and block readiness/approval. Empty when the publication mode skips Step 4; that does not mean the PR is ready to merge.

• review_cycle — the Step 4.3 snapshot receipt: head_sha, fingerprint, and dispositions. Include one record per feedback key from the snapshot, with status (addressed, invalid, or not_needed) and a nonempty reason explaining every finding in that document with commit/test/code evidence. Mixed dispositions in one summary belong individually in its reason; use addressed for the document when all its findings are settled. Revalidate after new feedback or a push. The live checker verifies coverage and freshness, not whether the reasoning is correct. Use {} when Step 4 has not run (interim, local-only, or workflow-owned author publication); preserve partial receipts and name missing reviews/findings in remaining_work if the loop is blocked.

• ui_preview — the result of Step 4.1 (run on every PR, not just frontend fixes): the preview URL (verbatim, so the ticket write-back can surface it and a reviewer can omnigent claude -p '<prompt>' --server <url>), or why it failed to deploy (e.g. workspace secrets not configured, or the label couldn't be applied under your identity). Empty when no PR was opened.

• validation_surface — which side the fix runs on, from Step 4.1: server (the preview build carries it; --server <preview> validates it), runner (runs in the runner/host process, so only a local gh pr checkout + --server '' build validates it — the preview's local runner is unfixed), or both (spans both — treat like runner). Judge from files_changed; default server, use both when unsure. Tells the write-back which command to render.

• validation_prompt — the Step 4.4 paste-to-an-agent prompt that reproduces the journey and confirms the fix. Empty when no PR was opened, except for workflow-owned author publication: in that mode no PR exists during the agent session, but this field must retain the deferred prompt for the publisher and Linear write-back.

• maintainer_review — who you requested review from in Step 4.5 (the issue assignee(s)), or why you couldn't (no assignee / assignee is the author, and what you did instead). Empty when no PR was opened.

• session_id — the repro session you consumed, carried through so the chain is traceable.

Directly published author runs and review runs end the same way: the PR you're landing (one you opened, or an existing in-repo PR you reviewed and kept) has a preview, green CI, settled current-head Polly and OCR reviews, a live-validation command, and the maintainer tagged (Step 4) — or a concrete blocker or actual execution deadline has left an explicitly incomplete, resumable handoff. The difference is only how a fix lands (push directly, or — for an unpushable fork PR that needs changes — take over into your own PR carrying the contributor's commits), and that the direct author path opens a PR while the review path adopts an existing one. Workflow-owned author publication ends after the validated body, deferred validation prompt, and final handoff are prepared; the publisher owns the post-publication loop. A direct draft proposal instead ends with the incomplete handoff in resolve-publish; it makes no readiness or independent-review claim. skip_push and needs_more_info runs end earlier, with no PR to land. In every mode, you do not merge.