feat: add guarded draft PR handoff and CI snapshots

CHANGELOG.md

@@ -19,6 +19,13 @@ Notable changes to the Swarm plugin. Format follows
   agent) as settled, instead of refusing cleanup until its tab is focused.
 
 ### Added
+- Opt-in `publish-pr <slot>` harvest verb (`g`, then slot in the pane) pushes
+  the audited commit and creates/reuses its exact GitHub draft PR. Existing
+  `publish` remains push-only. Optional SHA-bound validation JSON or Browser
+  QA results contribute only typed check names/statuses to a new draft.
+- `pr-status <slot>` (`c`, then slot) reads PR/CI state with explicit no-checks,
+  unknown, failure, and local/remote head-drift reporting. No automatic merge,
+  force push, or existing PR-body rewrite is performed.
 - `npm run doctor` checks Node, Git, and the selected Herdr binary without
   creating plugin state or contacting a running session; incompatible versions
   include an explicit `HERDR_BIN_PATH` remedy.

CONCEPTS.md

@@ -61,6 +61,19 @@ forge. Publish deliberately introduces no new terminal state — once the forge
 merge lands and base updates, the ordinary preview detection (ancestry or
 squash containment) settles the Slot.
 
+### Draft PR handoff
+An opt-in extension of Publish that creates a draft GitHub pull request for
+the exact repository, slot branch, and recorded base branch, or reuses that
+same PR. Supplied validation is bound to the published commit, not inferred
+from an agent's completion state. Reuse preserves the existing PR body; it
+does not replace earlier evidence or turn a review-ready PR back into a draft.
+
+### CI snapshot
+A read of GitHub's checks for the PR's current head, reported alongside the
+local slot head so callers can identify drift. Empty checks mean not run.
+Passing checks are observations, not approval to merge or proof that all
+required checks exist.
+
 ### Locus
 Where a merge physically executes. Two cases, and the distinction is
 load-bearing: when the base branch is not checked out anywhere, the merge runs

README.md

@@ -115,6 +115,8 @@ add your own, see below):
      base updates, the next re-preview auto-detects it (ancestry for merge
      commits, tree containment for squashes) and the slot proceeds to archive.
      Scriptable as `harvest-step.sh publish <slot>`.
+     For the optional GitHub draft handoff, use `g` then a slot digit or
+     `publish-pr <slot>`; `c` then a digit reads its current CI status.
    - *Archive* — after merge/skip, the worktree is removed (branch kept).
      Recursive ignored-file inventory is byte-safe and requires the exact
      digest-bound, one-use approval before ignored data can be removed. The
@@ -265,6 +267,33 @@ command = "structupath.swarm.fanout"
 description = "swarm fan-out"
 ```
 
+## GitHub draft PR handoff
+
+Swarm 0.4 adds two opt-in harvest verbs and pane shortcuts:
+
+- `bash scripts/harvest-step.sh publish-pr 1` (pane: `g`, then slot) performs
+  the existing audited-commit push, then creates a **draft** GitHub PR or reuses
+  the exact matching PR. `publish` and the `p` shortcut still only push.
+- `bash scripts/harvest-step.sh pr-status 1` (pane: `c`, then slot) reads the
+  PR state and current CI summary; it never merges, pushes, or edits GitHub.
+
+Install and authenticate `gh` first. The selected
+`HERDR_SWARM_PUBLISH_REMOTE` (default `origin`) must have exactly one fetch and
+push URL pointing to the same GitHub.com repository. Fork handoffs and GitHub
+Enterprise hosts are outside this first release. The PR base is the run's
+recorded base branch; the head is the slot's existing `swarm/<run>/<slot>` branch.
+
+Supply `HERDR_SWARM_VALIDATION_FILE=/absolute/path/result.json` to include a
+SHA-bound validation summary. It accepts either the explicit checks format or a
+Browser QA `result.json`. Without it, the draft says validation was **not run**.
+Swarm does not execute validation commands or authenticate supplied evidence.
+PR bodies contain only run/slot identifiers, commit SHAs, and whitelisted check
+names/statuses; task text, logs, screenshots, browser URLs, and local paths are
+not copied.
+
+See [GitHub handoff contract and recovery](docs/github-handoff.md) for the file
+schema, Console integration output, and failure handling.
+
 ## Presets
 
 Each slot runs the argv of a named preset. Config file:

bin/renderer-harvest.mjs

@@ -180,6 +180,13 @@ export function renderHarvest(model, cols = 80) {
 			);
 			lines.push(`${ESC}[2m [1-9]slot  [Esc]cancel${ESC}[0m`);
 			break;
+		case "github-pick":
+			lines.push(ph.operation === "publish-pr"
+				? " GITHUB DRAFT: push a slot and create/reuse its exact matching PR?"
+				: " GITHUB CI: inspect which slot's PR? (read-only)");
+			lines.push(" Validation comes from HERDR_SWARM_VALIDATION_FILE; absent means not run.");
+			lines.push(`${ESC}[2m [1-9]slot  [Esc]cancel${ESC}[0m`);
+			break;
 		default: {
 			// Any row still carrying a journal wedges every merge (sequencer_scan
 			// / the merge verb's own refusal), so the escape hatch has to be
@@ -190,6 +197,7 @@ export function renderHarvest(model, cols = 80) {
 					j ? `  a:abort stale merge (slot ${j.slot})` : ""
 				}  q:quit${ESC}[0m`,
 			);
+			lines.push(`${ESC}[2m g:draft GitHub PR  c:read GitHub CI${ESC}[0m`);
 		}
 	}
 	return lines.join("\n");
@@ -663,6 +671,32 @@ export class HarvestRenderer {
 					this.paint();
 				}
 				break;
+			case "github-pick":
+				if (ch >= "1" && ch <= "9") {
+					const slot = Number(ch);
+					this.phase = { name: "list" };
+					if (!this.rows.some((row) => row.slot === slot)) {
+						this.banner = `no slot ${slot} in this run`;
+						this.paint();
+						break;
+					}
+					const result = await this.step(ph.operation, [slot]);
+					if (result.code !== 0) this.banner = this.lastErrLine(result);
+					else {
+						try {
+							const key = ph.operation === "publish-pr" ? "pull_request" : "ci_status";
+							const value = JSON.parse(result.out[key]?.[0]?.[0]);
+							this.banner = ph.operation === "publish-pr"
+								? `${value.reused ? "reused" : "draft created"}: ${value.url}${value.reused ? " (existing body preserved)" : ""}`
+								: `CI ${value.status}${value.matches_local_head === false ? " (remote head differs from local)" : ""}${value.url ? `: ${value.url}` : ""}`;
+						} catch { this.banner = "GitHub response was malformed; inspect the PR before retrying."; }
+					}
+					this.paint();
+				} else if (ch === "b" || ch === "\x1b") {
+					this.phase = { name: "list" };
+					this.paint();
+				}
+				break;
 			case "ignored":
 				if (ch === "y" || ch === "Y") {
 					const slot = ph.slot;
@@ -686,6 +720,9 @@ export class HarvestRenderer {
 				else if (ch === "p") {
 					this.phase = { name: "publish-pick" };
 					this.paint();
+				} else if (ch === "g" || ch === "c") {
+					this.phase = { name: "github-pick", operation: ch === "g" ? "publish-pr" : "pr-status" };
+					this.paint();
 				} else if (ch === "r") {
 					this.banner = "";
 					await this.reload();

docs/github-handoff.md

@@ -0,0 +1,125 @@
+# GitHub draft handoff contract
+
+Swarm 0.4 adds optional GitHub handoff to the existing harvest commands. The
+five manifest actions remain unchanged; these are new `harvest-step.sh` verbs.
+
+## Commands and authorization
+
+From a configured Swarm run:
+
+```sh
+# Push committed slot work, then create/reuse its exact matching draft PR.
+HERDR_SWARM_VALIDATION_FILE=/absolute/path/result.json \
+  bash scripts/harvest-step.sh publish-pr 1
+
+# Read the PR's current head and CI state.
+bash scripts/harvest-step.sh pr-status 1
+```
+
+The harvest pane exposes `g`, then a slot digit, for draft handoff and `c`, then
+a slot digit, for CI status. Selecting the slot in the draft prompt authorizes
+the push/PR creation. `p` and `publish` retain their existing push-only behavior.
+Scripts use the same workspace/repository context as other harvest verbs.
+
+Requirements: Node >=20, Git, authenticated `gh` with access to the destination,
+and an active Swarm run with owned slot resources. `HERDR_SWARM_PUBLISH_REMOTE`
+defaults to `origin`. It must name a Git remote with exactly one fetch and push
+URL identifying the same GitHub.com repository (ordinary HTTPS or SSH, without
+embedded credentials). Fork destinations, multiple push URLs, and Enterprise
+hosts are not supported yet. No remote/auth/CI configuration is changed.
+
+The PR base is the manifest's recorded base branch. The head is the slot branch.
+The existing ownership, fork ancestry, non-empty-work, and non-force-push guards
+remain active. Uncommitted work is excluded with the existing warning. The
+prepared SHA must still match before publishing; the push uses that audited SHA
+and destination URL, then verifies the PR head. No automatic merge occurs.
+
+## Explicit validation evidence
+
+`HERDR_SWARM_VALIDATION_FILE` is optional. Omitting it reports `not_run`, never
+success. This file is read only for `publish-pr`; `pr-status` does not read it.
+Swarm executes no validation commands. It accepts a regular JSON file of at most
+1 MiB in either format below. Symlinks and special files are refused; the byte
+limit applies to the actual read, including a file growing while read.
+
+```json
+{
+  "schema_version": 1,
+  "head_sha": "0123456789012345678901234567890123456789",
+  "checks": [
+    { "name": "unit-tests", "status": "not_run" },
+    { "name": "typecheck", "status": "pending" }
+  ]
+}
+```
+
+Replace the example SHA with the actual tested slot commit. `head_sha` must
+equal the prepared published SHA. Supply 1–30 checks with unique names matching
+`[a-z][a-z0-9_-]{0,47}`. Statuses are `passed`, `failed`, `pending`, or `not_run`.
+Check names are explicitly public labels; keep them free of secrets. Additional
+fields such as raw command output are never copied to the PR.
+
+Browser QA's `result.json` is accepted directly when it has `schemaVersion: 1`,
+`kind: "herdr-browser-qa"`, a matching `git.commit`, and explicitly false
+`git.dirty` and `git.changedDuringRun`. Its summary fields must be nonnegative
+integers, and `scenario.policy.failOnConsoleError`, `failOnPageError`, and
+`failOnFailedRequest` must all be explicitly true. The summary requires
+1–4 viewports and matching pass/fail totals. Typed per-run steps and telemetry
+must agree with the summary counts. A passing `browser-qa` check additionally
+requires every viewport run and step to pass, at least one successful assertion,
+passed cleanup, no recorded errors or incomplete telemetry, and zero console
+errors, page errors, failed requests, or unresolved requests.
+Other valid reports become `failed`. Raw runs, URLs, paths, and screenshots are
+not published. Browser QA observations do not prove the served application was
+built from the recorded commit.
+
+Both formats are caller-supplied observations, not authenticated attestations.
+Failed or pending checks can be attached to a draft; Swarm does not mislabel them
+or treat them as approval.
+
+## Retry and existing PRs
+
+Discovery requires exact repository/head/base identity and excludes fork PRs.
+One matching open PR is reused whether draft or already marked ready for review.
+Existing title/body/state is preserved. Consequently, `validation_attached` is
+false on reuse: the existing body may describe an earlier SHA and must not be
+treated as fresh evidence. The caller can review/update it manually on GitHub.
+Closed/merged matches or ambiguous/truncated discovery refuse handoff.
+
+Evidence, CLI access, and remote-format failures occur before the push. A push
+failure never creates a PR. A PR API failure can occur **after** publication;
+the existing manifest `published` receipt records the pushed SHA, and the branch
+remains on the remote. Retry the same verb. If creation succeeded but its response
+was lost, Swarm searches again and reuses the exact PR instead of duplicating it.
+If GitHub's head differs from the audited SHA, handoff refuses success and leaves
+the published branch/PR for inspection; it never force-pushes a correction.
+
+## Machine-readable output
+
+All commands retain the `key<TAB>value` stdout protocol and human errors on stderr.
+Preparation drift uses exit 30; handoff/precondition failures use exit 36.
+Existing ownership/manifest refusal codes continue to apply. A failed create may
+still emit the earlier successful `published` record; check the process exit code.
+
+Successful `publish-pr` emits the existing `published` record followed by:
+
+```text
+pull_request<TAB>{"schema_version":1,"repository":"owner/repo","number":7,"url":"https://github.com/owner/repo/pull/7","state":"OPEN","draft":true,"head_sha":"...","base":"main","branch":"swarm/run/slot","reused":false,"validation_attached":true,"validation":{"source":"supplied","head_sha":"...","checks":[{"name":"unit-tests","status":"passed"}]}}
+```
+
+Validation sources are `none`, `supplied`, or `browser_qa`.
+
+`pr-status` emits `ci_status` with schema version, repository, number, URL, PR
+state/draft status, `head_sha`, `local_head_sha`, `matches_local_head`, `status`,
+and `check_count`. No matching PR emits only schema version, repository,
+`local_head_sha`, and `status: "no_pr"`.
+
+CI status values are `passed`, `failed`, `pending`, `not_run`, and `unknown`.
+Empty checks and otherwise successful sets containing skipped/neutral checks
+are `not_run`; unrecognized responses are `unknown`.
+A remote/local mismatch leaves the remote CI status intact and sets
+`matches_local_head: false`; callers must display that mismatch. Passing checks
+do not establish branch-protection completeness or authorize a merge.
+
+CI inspection makes only GitHub reads, with no fetch/push/PR edits. As with other
+harvest verbs, it takes the local run lock while resolving and verifying context.

docs/readiness.md

@@ -1,6 +1,6 @@
 # Swarm readiness
 
-The plugin remains version 0.3.0; fixes on this branch are recorded under
+The plugin targets version 0.4.0; changes on this branch are recorded under
 Unreleased in the changelog. The manifest still requires Herdr >=0.7.4.
 
 ## Repeatable validation
@@ -49,5 +49,6 @@ push, default user session, or production repository was used by the smoke run.
    setup-hook failure currently warns and still starts the agent.
 3. Keep conflict resolution review-first. The resolver-agent document in
    `docs/plans/` describes future work, not a shipped feature.
-4. Treat `publish` as a branch push for forge review, not automatic PR creation
-   or merging. The orchestrator remains responsible for the final review.
+4. Use `publish-pr` for an explicit draft GitHub handoff with SHA-bound supplied
+   evidence, and `pr-status` for a current CI snapshot. Ordinary `publish` still
+   only pushes. The orchestrator remains responsible for the final review.

herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "structupath.swarm"
 name = "Swarm"
-version = "0.3.0"
+version = "0.4.0"
 min_herdr_version = "0.7.4"
 description = "Worktree-per-agent fan-out, per-slot change visibility, and review-first harvest for parallel coding agents"
 platforms = ["macos", "linux"]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-swarm",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": true,
   "type": "module",
   "engines": { "node": ">=20" },

scripts/doctor.sh

@@ -36,5 +36,10 @@ else
 fi
 
 echo 'Agent prerequisites: check your selected preset binaries and authentication before fan-out.'
+if command -v gh >/dev/null 2>&1; then
+	echo 'Optional GitHub handoff: gh is installed; publish-pr/pr-status also require repository access.'
+else
+	echo 'Optional GitHub handoff: install gh for publish-pr/pr-status (ordinary publish does not need it).'
+fi
 echo 'This checks local prerequisites only; it does not exercise a Herdr session or start agents.'
 exit "$failed"

scripts/harvest-step.sh

@@ -11,7 +11,7 @@
 # Verbs: preview <slot> | commit-wip <slot> | snapshot <slot> |
 #        discard <slot> | skip <slot> | merge <slot> <expected-base-sha> |
 #        resume [complete <slot>] | archive <slot> | abort-merge <slot> |
-#        publish <slot>
+#        publish <slot> | publish-pr <slot> | pr-status <slot>
 #
 # Output protocol: machine-readable "key<TAB>value…" lines on stdout, human
 # messages on stderr, typed exit codes (HS_EC_*) so the renderer branches on
@@ -68,6 +68,8 @@ VERB="${1-}"
 }
 shift
 
+case "$VERB" in publish-pr | pr-status) clear_git_routing_env ;; esac
+
 # --- Run + slot context ------------------------------------------------------
 
 # Internal field separator is ASCII unit separator (\x1f), NOT tab: tab is
@@ -694,6 +696,7 @@ do_resume() {
 do_publish() {
 	read_slot "$1" || return $?
 	local remote="${HERDR_SWARM_PUBLISH_REMOTE:-origin}" tip out patch
+	local expected="${2-}" destination="${3:-${HERDR_SWARM_PUBLISH_REMOTE:-origin}}"
 	if ! git -C "$REPO_ROOT" remote get-url "$remote" >/dev/null 2>&1; then
 		echo "herdr-swarm: remote '$remote' is not configured in this repository — add it, or point HERDR_SWARM_PUBLISH_REMOTE at the remote to publish to." >&2
 		return "$HS_EC_REFUSED"
@@ -706,6 +709,10 @@ do_publish() {
 		echo "herdr-swarm: slot $1 has no commits past the fork point — nothing to publish." >&2
 		return "$HS_EC_REFUSED"
 	fi
+	if [ -n "$expected" ] && [ "$tip" != "$expected" ]; then
+		echo "herdr-swarm: slot head moved after PR/evidence preparation — re-run publish-pr." >&2
+		return "$HS_EC_DRIFT"
+	fi
 	# The branch must still contain the recorded fork point: a rewritten slot
 	# branch (reset onto foreign history) would otherwise publish commits this
 	# run never audited. Same authority prune uses — ancestry, not bookkeeping.
@@ -727,7 +734,7 @@ do_publish() {
 	if [ -n "${HERDR_SWARM_TEST_PAUSE_BEFORE_PUBLISH:-}" ]; then
 		sleep "$HERDR_SWARM_TEST_PAUSE_BEFORE_PUBLISH"
 	fi
-	if ! out="$(git -C "$REPO_ROOT" push "$remote" "$tip:refs/heads/$SLOT_BRANCH" 2>&1)"; then
+	if ! out="$(git -C "$REPO_ROOT" push "$destination" "$tip:refs/heads/$SLOT_BRANCH" 2>&1)"; then
 		printf '%s\n' "$out" >&2
 		echo "herdr-swarm: publish of slot $1 to '$remote' was rejected — nothing was force-pushed; resolve the refusal above and retry." >&2
 		return "$HS_EC_REFUSED"
@@ -740,6 +747,21 @@ do_publish() {
 	printf 'published\t%s\t%s\t%s\n' "$1" "$remote" "$tip"
 }
 
+do_publish_pr() {
+	read_slot "$1" || return $?
+	local plan expected destination
+	plan="$(node "$PLUGIN_ROOT/scripts/pr-handoff.mjs" prepare "$REPO_ROOT" "$RUN_ID" "$1" "$SLOT_BRANCH" "$BASE_BRANCH" "$FORK_SHA")" || return "$HS_EC_REFUSED"
+	expected="$(printf '%s' "$plan" | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).sha));')" || return 1
+	destination="$(printf '%s' "$plan" | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).push_url));')" || return 1
+	do_publish "$1" "$expected" "$destination" || return $?
+	printf '%s' "$plan" | node "$PLUGIN_ROOT/scripts/pr-handoff.mjs" handoff
+}
+
+do_pr_status() {
+	read_slot "$1" || return $?
+	node "$PLUGIN_ROOT/scripts/pr-handoff.mjs" status "$REPO_ROOT" "$RUN_ID" "$1" "$SLOT_BRANCH" "$BASE_BRANCH" "$FORK_SHA"
+}
+
 do_archive() {
 	read_slot "$1" || return $?
 	case "$SLOT_STATUS" in
@@ -975,6 +997,14 @@ publish)
 	require_slot_arg "${1-}" || exit 1
 	do_publish "$1"
 	;;
+publish-pr)
+	require_slot_arg "${1-}" || exit 1
+	do_publish_pr "$1"
+	;;
+pr-status)
+	require_slot_arg "${1-}" || exit 1
+	do_pr_status "$1"
+	;;
 *)
 	echo "herdr-swarm: unknown harvest verb '$VERB'" >&2
 	exit 1