Make PR bundle history recovery explicit and validation offline

[pelikhan]

Summary

Replace the live-base fetch from #68717, reverted by #68795, without restoring unrestricted automatic history downloads in shallow monorepos.

• Discover the trusted base tip using exact-ref, metadata-only git ls-remote --refs --exit-code against the target checkout's origin. Validate the returned ref/SHA and pin the SHA; never fetch objects solely to establish this optional validation baseline.
• Import local bundles using git bundle unbundle. Bundle import, prerequisite checks, optional ancestry/tree inspection, and the push handler's bundle diff/history checks deny Git transports with GIT_ALLOW_PROTOCOL="" plus GIT_NO_LAZY_FETCH=1. Protocol denial also protects Git versions that ignore lazy-fetch suppression.
• Retain conservative PR-head validation when trusted metadata or sufficient local history is unavailable. Preserve protected-file, transient-history, octopus-merge, patch-size, and expanded-content checks; missing required content fails rather than bypassing validation. Agent metadata and workflow-start SHAs do not establish trusted base provenance.
• Replace automatic prerequisite fetch/deepen/unshallow escalation and separate handler recovery paths with explicit per-handler authorization. Missing prerequisites produce actionable provisioning/opt-in errors with fixed diagnostics rather than raw credential-bearing output.
• Keep recovery credentials separate from baseline discovery: opted-in push recovery uses the validated PR head remote and scoped head credentials, including fork-only prerequisites, then restores target credentials. Create-handler recovery uses the checkout's origin.

Configuration and compatibility

Both settings independently default to false, accept only literal booleans, and belong to the applicable handler—not the global safe-outputs object:

safe-outputs:
  create-pull-request:
    allow-full-history-fetch: true
  push-to-pull-request-branch:
    allow-full-history-fetch: true

Prefer provisioning required objects during authenticated checkout. If prerequisites are missing, the error explains that approach and how to enable recovery under the applicable handler.

Opting in permits unbounded downloads, including --unshallow and fetch-by-SHA. Exact SHAs, commit-depth limits, and blob filters are not byte bounds. The opt-in never enables object fetching for optional baseline discovery.

Shallow checkouts remain supported when the necessary objects are present. Partial clones can fail offline when required trees/blobs are missing, even if prerequisite commits exist. Conservative fallback can reject otherwise valid base merges rather than exclude unverified history. This is not a network-free handler: ordinary PR-head fetch/push and existing signed-push recovery remain outside this focused policy.

The JS handlers, TypeScript configuration, Go parsing/runtime serialization, workflow schema, reference documentation, and tests are updated together. ADR-68806 documents the decision, alternatives, credential separation, and compatibility tradeoffs; its status remains Proposed, pending maintainer acceptance.

Current branch and validation

Merged main through 1707e20ece0fe899f193963905ec594bcc0700a1 and pushed merge commit 94b9d572d6af9756299bb1347558c3bb5763e404. No merge conflicts; all 344 workflows recompiled successfully.

• Earlier focused validation: 661 tests passed across seven JS suites with --testTimeout=20000. Coverage includes real shallow/partial repositories, offline import and optional-baseline inspection, missing prerequisites, metadata/authentication fallback, filtering-unsupported servers, fork-only recovery, literal opt-in, credential restoration, and protection checks.
• Focused Go schema/config tests passed for defaults, handler isolation, runtime serialization, and rejection of global/string/expression values. Build, JS typecheck, pinned formatting, and whitespace checks also passed in the preceding review-fix batch.
• Latest make agent-report-progress: regular Go lint, JavaScript lint, schema checks, and impacted Go tests passed. Impacted JS tests reported 801 passed and one timeout across 11 suites. JavaScript lint has non-blocking warnings.

Remaining local gate limitations

The final progress gate is not fully green:

• Custom Go lint reports the existing parser lengths: parseCreatePullRequestsConfig at 109 lines and parsePushToPullRequestBranchConfig at 164 lines, against a 60-line limit.
• The existing real-Git test creating 150 commits exceeded the gate's default 10-second timeout. A targeted rerun passed with the established local 20-second timeout. No test assertion, configured timeout, lint rule, or gate was changed or disabled.

The earlier pinned-dependency installation blocker is resolved. No production bandwidth measurements or bandwidth-bound claims are made. No workflow runs were manually triggered; this PR has not been merged and auto-merge has not been enabled.

---

Changeset

• Type: patch
• Description: Make pull request bundle history recovery explicit and keep bundle validation offline unless full-history fetching is enabled for the applicable safe-output handler.

Generated by 📋 Changeset Generator for #68806 · codex · gpt56 · 22.2 AIC · ⌖ 27.6 AIC · ⊞ 15.7K · ◷

---

---

✨ PR Review Safe Output Test - Run 38644688115

💥 [THE END] — Illustrated by Smoke Claude · claude · sonnet46 · 63 AIC · ⌖ 8.94 AIC · ⊞ 881 · ◷
_{Comment /smoke-claude to run again}

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check. See the comment below for the result and any generated ADR draft.

Commit pushed: d050619

🏗️ ADR gate enforced by Design Decision Gate 🏗️

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

Test Quality Sentinel

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Test Quality Sentinel · haiku45 · 5.37 AIC · ⌖ 6.97 AIC · ◇ 2.44 AIC · ⊞ 8.2K · ◷

🧪 Test quality analysis by Test Quality Sentinel

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

🔎 Code quality review by PR Code Quality Reviewer

[github-actions]

✅ Ponytail Reviewer completed successfully!

Ponytail Reviewer

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated from Ponytail Reviewer · gpt56 · 12.8 AIC · ⌖ 5.23 AIC · ⊞ 14.2K · ◷

Generated by Ponytail Reviewer for #68806

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

[github-actions]

🏗️ Design Decision Gate — ADR Required

This PR makes significant changes to core business logic (121 new lines across pkg/ and other business-logic paths, above the 100-line threshold) but does not have a linked Architecture Decision Record (ADR).

📄 Draft ADR committed: docs/adr/68806-explicit-offline-bundle-history-recovery.md — review and complete it before merging.

🔒 This PR cannot merge until an ADR is linked in the PR body.

📋 What to do next

1. Review the draft ADR committed to your branch — it was generated from the PR diff and description
2. Complete the missing sections — add context the AI couldn't infer, refine the decision rationale, and list the real alternatives you considered (the draft lists three inferred from the diff: bounded automatic recovery, a single global flag, and requiring deep checkouts)
3. Commit the finalized ADR to docs/adr/ on your branch
4. Reference the ADR in this PR body by adding a line such as:

   ADR: ADR-68806: Make PR bundle history recovery explicit and validate bundles offline

Once an ADR is linked in the PR body, this gate will re-run and verify the implementation matches the decision.

🔍 Evidence used

• 17 changed files, 121 additions in default business-logic directories (pkg/), above the default threshold of 100
• No .design-gate.yml present — default configuration applied
• No ADR link or ADR section found in the PR body; no ADR for PR 68806 under docs/adr/
• Decision inferred from pkg/workflow/create_pull_request.go, pkg/workflow/push_to_pull_request_branch.go, pkg/workflow/safe_outputs_handler_registry_pull_requests.go, pkg/parser/schemas/main_workflow_schema.json, and the actions/setup/js/ bundle/git helper changes (git ls-remote --refs --exit-code, git bundle unbundle under GIT_ALLOW_PROTOCOL="", per-handler allow-full-history-fetch)

❓ Why ADRs Matter

"AI made me procrastinate on key design decisions. Because refactoring was cheap, I could always say 'I'll deal with this later.' Deferring decisions corroded my ability to think clearly."

ADRs create a searchable, permanent record of why the codebase looks the way it does. Future contributors (and your future self) will thank you.

📋 Michael Nygard ADR Format Reference

An ADR must contain these four sections to be considered complete:

• Context — What is the problem? What forces are at play?
• Decision — What did you decide? Why?
• Alternatives Considered — What else could have been done?
• Consequences — What are the trade-offs (positive and negative)?

All ADRs are stored in docs/adr/ as Markdown files numbered by PR number.

🏗️ ADR gate enforced by Design Decision Gate 🏗️ · pi · opus50 · 44.5 AIC · ⌖ 51.6 AIC · ⊞ 1.9K · ◷
_{Comment /review to run again}

[github-actions]

Comment Memory

Peek at saved memory (pr-code-quality-reviewer)

reviewed_at: 2026-10-14T19:46:33Z
review_event: REQUEST_CHANGES
top_themes:
  - bundle prerequisite recovery uses wrong remote for fork PRs
files_reviewed:
  - actions/setup/js/git_helpers.cjs
  - actions/setup/js/push_to_pull_request_branch.cjs
  - actions/setup/js/create_pull_request.cjs
  - pkg/workflow/create_pull_request.go
  - pkg/workflow/push_to_pull_request_branch.go
comment_count: 1

Note

This comment is managed by comment memory.

Expand the saved memory block to view or edit the persistent context for this thread.
Edit only the text inside the backtick fences; workflow metadata and the footer are regenerated automatically.

Learn more about comment memory

🔮 The oracle has spoken through Smoke Codex · ◷
_{Comment /smoke-codex to run again}

[github-actions]

Request changes

The new allow-full-history-fetch recovery path is still tied to origin, so fork-backed PR updates can't actually recover when the missing prerequisite commits live only on the configured head repository.

The blocking theme

• Fork / cross-repo correctness: push_to_pull_request_branch already knows which remote and credentials are valid for the PR head, but the recovery helper unconditionally fetches from origin. That makes the new opt-in incomplete for one of the most failure-prone PR topologies.

The inline comment points at the exact spot that needs the remote/auth context threaded through.

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt54 · 104.7 AIC · ⌖ 7.67 AIC · ⊞ 21.3K
_{Comment /review to run again}

[github-actions]

Skills-Based Review 🧠

Applied /codebase-design and /diagnosing-bugs on this offline bundle-transport hardening PR. No blocking issues found — approving.

📋 Key Themes & Highlights

Verification performed

• Traced ensureFullHistoryForBundle, importLocalBundle, offlineGitOptions, and resolveTrustedBaseTip end-to-end across git_helpers.cjs, create_pull_request.cjs, and push_to_pull_request_branch.cjs.
• Confirmed the new allow-full-history-fetch config is handler-scoped (not global), defaults to false, and is rejected by the JSON schema when passed as a string/expression (schema validation runs before Go config parsing, so a non-boolean value never silently falls through).
• Ran go test ./pkg/workflow/... -run TestAllowFullHistoryFetch and go test ./pkg/parser/... -run TestMainWorkflowSchema_AllowFullHistoryFetch — all pass.
• JS vitest suites could not be executed in this sandbox (npm registry blocked by self-signed cert, matching the PR body's noted dependency-restoration limitation); reviewed the new bundle_transport.integration.test.cjs and updated git_helpers.test.cjs/push_to_pull_request_branch.test.cjs assertions by inspection instead — they correctly assert zero fetch calls, pack-file stability, and no credential leakage in thrown errors.

Positive highlights

• ✅ Clear separation of concerns: offlineGitOptions() centralizes the transport-denial guard (GIT_ALLOW_PROTOCOL="" + GIT_NO_LAZY_FETCH=1 + GIT_TERMINAL_PROMPT=0), used consistently across bundle inspection/import call sites.
• ✅ resolveTrustedBaseTip validates the ref format before touching the network, requires an exact single-line ls-remote match, and swallows diagnostic output so stderr from a failed/unauthenticated remote never reaches core.warning (verified against the synthetic-credential integration test).
• ✅ Error messages are fixed, actionable strings (pointing at allow-full-history-fetch) rather than raw git stderr, matching the PR's stated goal of avoiding credential-bearing diagnostics.
• ✅ Go/JS config field naming (allow-full-history-fetch → AllowFullHistoryFetch → allow_full_history_fetch) is consistent end-to-end and mirrors the existing allow-workflows pattern.
• ✅ Removing ~240 lines of nested retry/recovery branching from both PR handlers in favor of a single importLocalBundle helper is a solid simplification that should make this code much easier to reason about going forward.

Minor observations (non-blocking)

• deepenOptions.baseRef is still documented in the ensureFullHistoryForBundle JSDoc as "kept for existing callers" but is no longer read anywhere in the function body — worth removing from the signature/callers in a later cleanup pass once all call sites are confirmed migrated.
• Could not independently execute the new JS test suites in this sandbox due to npm registry restrictions; relying on the PR's reported "592 passing tests" claim and static review of the test logic.

@copilot please address the review comments above.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet50 · 152.2 AIC · ⌖ 16.7 AIC · ⊞ 10.4K
_{Comment /matt to run again}

[Copilot]

🔵 Needs a closer look

Security-sensitive Git provenance and transport changes need human sign-off while pinned JavaScript validation gates remain incomplete.

0 open findings

What changed in this PR

Updates gh-aw’s PR safe-output handlers to keep bundle validation offline and require explicit permission for history recovery, following the earlier base-tip fetch change and revert.

Changes:

• Resolve trusted base tips through metadata-only remote lookup.
• Import and inspect bundles offline; make prerequisite downloads opt-in per handler.
• Add configuration validation, documentation, and regression coverage.

File	Description
pkg/​workflow/​safe_outputs_handler_registry_pull_requests.go	Serializes handler-specific recovery flags.
pkg/​workflow/​push_to_pull_request_branch.go	Parses the push handler’s recovery option.
pkg/​workflow/​create_pull_request.go	Defines the create handler’s recovery option.
pkg/​workflow/​compiler_safe_outputs_config_targets_test.go	Tests defaults, isolation, and serialization.
pkg/​parser/​schemas/​main_workflow_schema.json	Adds literal-boolean recovery settings.
pkg/​parser/​schema_safe_outputs_target_test.go	Tests accepted values and invalid configuration.
docs/​src/​content/​docs/​reference/​safe-outputs.md	Introduces the recovery option.
docs/​src/​content/​docs/​reference/​safe-outputs-pull-requests.md	Explains offline validation and recovery risks.
actions/​setup/​js/​types/​handler-factory.d.ts	Types the runtime recovery flag.
actions/​setup/​js/​push_to_pull_request_branch.test.cjs	Updates push-handler regression tests.
actions/​setup/​js/​push_to_pull_request_branch.cjs	Uses metadata lookup and offline bundle validation.
actions/​setup/​js/​git_helpers.test.cjs	Updates prerequisite and no-fetch tests.
actions/​setup/​js/​git_helpers.cjs	Adds offline import and explicit history recovery.
actions/​setup/​js/​create_pull_request.test.cjs	Updates create-handler recovery tests.
actions/​setup/​js/​create_pull_request.cjs	Imports bundles locally with opt-in recovery.
actions/​setup/​js/​create_pull_request_bundle_integration.test.cjs	Adapts integration checks to local import.
actions/​setup/​js/​bundle_transport.integration.test.cjs	Adds real-Git transport and recovery coverage.

🧠 Review effort: Max

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[pelikhan]

In response to the ADR gate result: I reviewed and completed the generated ADR, including the change/revert history, credential boundaries, alternatives, and tradeoffs. The finalized proposal is linked in the PR description.

[pelikhan]

In response to the Test Quality Sentinel result: this status notice requests no concrete code change, so no separate implementation change is needed. The fork-recovery fix has focused helper, handler, credential, and real-Git regression coverage; I did not treat reported_no_action as proof of validation.

[pelikhan]

In response to the code quality review result: accepted the associated fork-recovery finding. Both unshallow and fetch-by-SHA now use the validated PR head remote with scoped head credentials, while trusted base discovery remains target-origin metadata-only.

[pelikhan]

In response to the Ponytail Reviewer result: no code change is needed for this status-only notice. The actionable fork-recovery and ADR findings were addressed separately, without treating the no-action result as evidence of completion.

[pelikhan]

In response to the skills-based review: accepted the cleanup observation and removed the obsolete baseRef option documentation and unused test arguments. The fork-recovery update preserves handler-scoped literal opt-in and offline checks, with focused JavaScript validation completed locally.

[pelikhan]

In response to the ADR requirement: completed ADR-68806 with concrete context, recovery authorization and credential isolation, real alternatives, and operational tradeoffs. The ADR is linked in the PR description and remains a proposal pending maintainer acceptance.

[pelikhan]

In response to the saved review memory: addressed inline finding 4275548211 by using the validated PR head remote and scoped head credentials for explicit history recovery, with fork-only prerequisite and credential-restoration regressions. The managed memory block itself was left unchanged.

[gh-aw-bot]

@copilot address the following outstanding work in one pass:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes.
2. Review (actions/setup/js/git_helpers.cjs:617): This recovery path still hardcodes origin, so allow-full-history-fetch: true will never recover fork-backed PR bundles whose prerequisite commits only exist on the configured head repository. - Make PR bundle history recovery explicit and validation offline #68806 (comment)

Push the necessary fixes, reply to each listed review thread and resolve it when addressed. Ignore feedback already answered or resolved. Use the pr-finisher skill and stop when only human review or CI remains; do not trigger CI.

Sous-chef head: d050619
Sous-chef work: 0db59d096010174328ed2d08a1e451af7287c3487bae15c48914b87d9e789d02
Sous-chef state: 41227a0252b97fc81ca2fb483ddda24ba1ee10776b993ae8f9f3a11e8d612d49

Generated by 👨‍🍳 PR Sous Chef · pi · haiku45 · 3.9 AIC · ⌖ 7.56 AIC · ⊞ 1.1K · ◷
_{Comment /souschef to run again}

[Copilot]

🔵 Needs a closer look

Credential-sensitive Git changes and the incomplete validation gate require final maintainer review.

2 open findings

• Mark default recovery behavior change as a major breaking release · New
• Update documentation for offline import and opt-in prerequisite recovery · New

🧠 Review effort: Max

[Copilot]

Changed the changeset to major and added breaking-change migration guidance. The opt-in authorizes potentially unbounded prerequisite recovery; local bundle import and validation remain offline. Commit: b61d266.

[Copilot]

Updated the workflow steps to describe offline git bundle unbundle, default failure/provisioning or handler-specific recovery opt-in, and the requirement that necessary bundle objects be available when the base advances. Commit: b61d266.

[gh-aw-bot]

@copilot address the following outstanding work in one pass:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes.
2. Review (docs/adr/68806-explicit-offline-bundle-history-recovery.md:5): 👍 The Deciders field is a great addition to the ADR metadata — helps reviewers understand who is accountable for accepting this decision. Consider adding a Reviewers field as well for tracking. - Make PR bundle history recovery explicit and validation offline #68806 (comment)
3. Review (docs/adr/68806-explicit-offline-bundle-history-recovery.md:14): The decision to use GIT_ALLOW_PROTOCOL="" together with GIT_NO_LAZY_FETCH=1 is a solid defense-in-depth approach. It would be worth explicitly documenting the minimum Git version for GIT_NO_LAZY_FETCH support so operators know when they can rely on it alone. - Make PR bundle history recovery explicit and validation offline #68806 (comment)
4. Review (.changeset/patch-explicit-bundle-history-recovery.md:5): This changes existing workflows' default behavior: both PR handlers previously downloaded missing bundle prerequisites automatically, but now fail unless objects are provisioned or allow-full-history-fetch: true is configured. The release policy in .github/skills/developer-release/SKILL.md treats default-behavior changes as breaking; .changeset/major-logs-default-storage-budget.md:2–10 provides a similar opt-in-download precedent. Mark this changeset major and include a breaking-change notice with migration guidance. Clarify that the opt-in authorizes prerequisite recovery, while local... - Make PR bundle history recovery explicit and validation offline #68806 (comment)
5. Review (docs/src/content/docs/reference/safe-outputs-pull-requests.md:444): The earlier "How it works" section still says missing prerequisites are fetched automatically using git fetch <bundle-file> (line 147), and presents base-branch advancement as harmless (line 150). That contradicts the new default: import uses offline git bundle unbundle, and missing prerequisites fail unless recovery is explicitly enabled. Update step 2 to describe offline import and per-handler opt-in, and qualify the advancement note with the requirement that necessary bundle objects be available. - Make PR bundle history recovery explicit and validation offline #68806 (comment)

Push the necessary fixes, reply to each listed review thread and resolve it when addressed. Ignore feedback already answered or resolved. Use the pr-finisher skill and stop when only human review or CI remains; do not trigger CI.

Sous-chef head: 42c5cb7
Sous-chef work: 0d94dbe6157062062a935ec4a4ee641c5786eb325c733837207b62975867721a 596aafea22e26b5c8b8b254d0dda18bdd8ed48fa607cc64ce23e942ac3e1886f 91f6eb82d03263ecf121fdd44c8d12a2e2d95b0933b01f755db750f6bf45ffa3 be012f5c2c3aceb76bd2e189fe2afbc2709db39783b898a37ff5b19ebf064abd
Sous-chef state: cff7ed573d1eddb153f89e00da736d1a8cff1d47e8b0352c6a7f22f8a1ad3153

Generated by 👨‍🍳 PR Sous Chef · pi · haiku45 · 7.99 AIC · ⌖ 12 AIC · ⊞ 1.1K · ◷
_{Comment /souschef to run again}

[pelikhan]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review thread.

[Copilot]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the s...

The two findings linked from review 5525670339 are already addressed in commit b61d266: the changeset is major with migration guidance, and the pull-request reference describes offline bundle import and per-handler prerequisite recovery. I verified both in the current branch; no further changes are needed for this review.

[pelikhan]

@copilot merge main and recompile

[gh-aw-bot]

@copilot address the following outstanding work in one pass:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes.
2. Fix failing check copilot (FAILURE): https://github.com/github/gh-aw/actions/runs/38780590169/job/116579463145.
3. Fix failing check github-advanced-security (FAILURE): https://github.com/github/gh-aw/actions/runs/38779672022/job/116576302000.
4. Fix failing check JS Tests (shard 2/4) (FAILURE): https://github.com/github/gh-aw/actions/runs/38779671749/job/116576510541.

Push the necessary fixes, reply to each listed review thread and resolve it when addressed. Ignore feedback already answered or resolved. Use the pr-finisher skill and stop when only human review or CI remains; do not trigger CI.

Sous-chef head: f8c36e8
Sous-chef work: 01f76bdb322c55c0f3013020f731f2745bb49d9eecf76a9d3f4327bb7c04d52f 043185828d65a534dd8b2b6b4d00e0d47bf21a2940d3f277c0ed15da7f668648 960a6fe297781e0f1e1c8c03fa3740110735e1332e99a040b5aa7b1b6d14a3f2
Sous-chef state: 882e4ca569f670b37f14d4ba285016e00c8440766995473206b97a2e90fef3f9

Generated by 👨‍🍳 PR Sous Chef · pi · haiku45 · 3.79 AIC · ⌖ 10.3 AIC · ⊞ 1.1K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot address the following outstanding work in one pass:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes....

Fixed the transport-integrity test fixtures to match offline bundle import; the affected suites and 634 impacted JS tests now pass. Pinned gopls to v0.23.0, which installs with Go 1.26.9, addressing the setup failures. Commit: a83cbb3.

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.92.1