Skip to content

feat(preflight): gate agent pushes and PRs on a local preflight receipt - #3580

Merged
Daniel Meppiel (danielmeppiel) merged 9 commits into
mainfrom
danielmeppiel-preflight-gate
Nov 12, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 9 commits into
mainfrom
danielmeppiel-preflight-gate

Conversation

@danielmeppiel

@danielmeppiel Daniel Meppiel (danielmeppiel) commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR

Adds packages/preflight-gate, a repo-local APM package that blocks Copilot agents from pushing or opening PRs until the checks CI will run have passed locally on the exact commit being published. A preToolUse hook denies git push, gh pr create/ready and PR-creation tools without a fresh green receipt; the deny message tells the agent what to run, and agents recovered from it unaided in end-to-end tests. Nothing waits on CI: PRs open ready for review, and CI-only lanes (Windows, macOS, merge queue) still run there.

Fixes #3579

Important

Merging activates the gate for every Copilot CLI and cloud-agent session started at this repo's root, including maintainers'. Plain terminal git push is unaffected. Humans can bypass by launching the CLI with APM_PREFLIGHT_BYPASS=accept-unverified.

Problem (WHY)

Why this matters: verification belongs in a deterministic tool step, not in agent diligence — PROSE: "Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action."

Approach (WHAT)

# Decision
1 One hook, no skill. preToolUse is the only surface that can block before the action; agentStop/postToolUse fire after publishing, permissionRequest is CLI-only. The deny text is the whole agent-facing contract.
2 Cheap by construction. A matcher limits the hook to shell and PR tools; a pure-shell launcher starts Python only when the payload mentions push, gh pr, pulls or a PR mutation (~25 ms otherwise).
3 Never bricks a session. The launcher always exits 0; a crash, missing python3 or syntax error yields empty output (fail-open, CI stays the authority). Only a well-formed deny JSON blocks.
4 Receipt bound to what is published. It records commit SHA, tree, base SHA, bundle hash and per-check results; the gate resolves every pushed source ref and re-checks that origin/main has not moved.
5 Diff-aware, CI-identical checks. Lint/guards always; mapped tests and architecture contracts for code changes; full unit suite and lifecycle smoke for src/. Commands are copied from ci.yml, fingerprinted, and drift fails the run.
6 Throughput first. Light checks across all tiers run concurrently, heavy xdist suites run alone afterwards, and the first failure cancels the rest.

Implementation (HOW)

Path Intent
packages/preflight-gate/apm.yml, README.md Package manifest (default type, hooks only) and human docs: usage, bypass, fingerprint refresh, known limitations.
.apm/hooks/preflight-gate.json preToolUse entry with matcher; bash runs the launcher, powershell is exit 0 (not enforced on native Windows).
.apm/hooks/scripts/gate-launcher.sh Root-resolving, always-exit-0 launcher with the publish-only fast path.
.apm/hooks/scripts/gate.py Parses shell commands per simple command (chains, subshells, bash -c, wrappers, cd/-C/pushd), classifies publish actions, validates the receipt, emits one deny object.
.apm/hooks/scripts/preflight.py, preflight_lib.py Runner: fetch base, select tiers, provision a lock-matched env, two-phase schedule, tree-mutation guard, atomic receipt in the worktree's git dir.
.apm/hooks/scripts/preflight_policy.py Single owner of what runs: tier rules, mirrored CI commands, CI fingerprints, volatile outputs.
packages/preflight-gate/tests/ 354 tests over classification, chaining, receipt states, launcher fail-open, matcher, scheduling, env provisioning, deny wording.
apm.yml, apm.lock.yaml, .github/hooks/** Declares the local dependency, an executables.allow grant pinned to ./packages/preflight-gate#0.1.0, and the deployed copy. Lock diff is only the preflight entries (no unrelated churn).

Architecture

Two processes share one file: a fast gate (Copilot preToolUse hook) that only reads a receipt, and a slow runner (preflight.py) that writes it.

1. Components

flowchart LR
  subgraph Copilot["Copilot CLI / cloud agent"]
    T["tool call: bash, PR tool"]
  end
  subgraph Hook["preToolUse hook (.github/hooks)"]
    M{"matcher: shell or PR tool?"}
    L{"launcher.sh: payload mentions push / gh pr / pulls?"}
    G["gate.py: parse command, validate receipt"]
  end
  subgraph Runner["preflight.py (agent runs it)"]
    S["select tiers from diff"]
    P["policy.py: checks = CI commands"]
    X["two-phase scheduler"]
  end
  RC[("receipt.json in worktree git dir")]
  T --> M
  M -->|"no: view, edit, grep..."| OK1["hook never runs"]
  M -->|yes| L
  L -->|"no: git status, commit..."| OK2["exit 0 in shell, ~25 ms"]
  L -->|yes| G
  G -->|reads| RC
  G -->|"valid"| OK3["no output: tool runs"]
  G -->|"invalid"| D["deny + exact fix command"]
  D -.agent runs.-> S
  S --> P --> X -->|writes| RC
Loading

2. Gate decision (only for publish actions)

Publish actions: git push, gh pr create, gh pr ready, gh api POST/PATCH to /pulls, PR-creation tools, update_pull_request that marks a PR ready. Exempt: git push --dry-run, gh pr create --help.

flowchart TD
  A["publish action"] --> B{"earlier command in same call changes refs?"}
  B -->|yes| D1["deny: run push as its own call"]
  B -->|no| C{"pushing tags, --all, other branch, wildcard?"}
  C -->|yes| D2["deny: push only verified HEAD; tags are a human step"]
  C -->|no| E{"receipt exists, status pass, eligible, auto tiers?"}
  E -->|no| D3["deny: run preflight.py (lists failed checks + logs)"]
  E -->|yes| F{"receipt.head == pushed commit, base unchanged, bundle unchanged, age < 24h?"}
  F -->|no| D4["deny: re-run preflight"]
  F -->|yes| OK["allow (empty output)"]
Loading

Safety properties:

  • Fail-open: the launcher always exits 0, so a crash, missing Python or broken script lets the call through. CI stays the authority.
  • Never auto-approves: the gate never emits "allow"; it only denies.
  • Human bypass: launching the CLI with APM_PREFLIGHT_BYPASS=accept-unverified skips the gate, and each use is logged.

3. What the runner runs, and when

Tiers are selected from git diff against the merge-base with origin/main. Every command is copied from ci.yml or spec-conformance.yml and fingerprinted (see ci.drift in T0).

Tier Selected when the diff touches Checks (CI command mirrored) Typical time (M-series Mac)
T0 anything (always) env.lock-sync (provision venv from uv.lock), ci.drift, bundle.stale, git.merge-conflict, git.diff-check, guard.ascii, guard.uv-lock (if uv.lock changed), lint.ruff, lint.ruff-format, lint.yaml-io, lint.file-length, lint.relpath, lint.pylint-dup (R0801), lint.auth-signals, lint.arch-boundaries, spec.mode-b ruff under 1 s; pylint 160-240 s today, about 20 s after #3582; everything else under 30 s
T1 src/, tests/, scripts/, workflows, any .py file arch.contracts (ratchet contract tests) 90-170 s
src/, tests/unit, scripts/ unit.mapped: changed test files plus tests that import changed modules (xdist above 20 files; falls back to the full suite above 150) seconds to minutes
apm.yml, apm.lock.yaml, packages/, .apm/, .agents/, .github/ (not workflows) apm.self-check (apm audit --ci), apm.lock-snapshots about 10 s
src/apm_cli/, specs, spec tests, pyproject.toml, CONFORMANCE.* spec.orphans, spec.conformance about 8-9 min
contributor dashboard dashboard.node seconds
T2 src/, tests/utils/, pyproject.toml, uv.lock, conftests unit.full (tests/unit tests/test_console.py tests/red_team -n auto) 10-12 min
T3 src/, tests/integration/, tests/utils/, pyproject.toml, uv.lock, sharding script lifecycle.smoke-1/2 (both CI shards), integration.changed about 7 min per shard

Typical wall times by change type:

  • Docs, tooling or package change: T0, plus T1 where it applies; about 3 min.
  • Product source change: T0 through T3; about 30 min today.

Not run locally (CI-only): Windows and macOS lanes, the full integration corpus, merge-queue release validation. The receipt lists them as ci_only_lanes.

4. Scheduling

flowchart LR
  E["env.lock-sync (alone, first)"] --> A["Phase A: all light checks from every tier, 4 at a time"]
  A -->|"all pass"| B["Phase B: heavy xdist suites one at a time (unit.full, lifecycle shards, xdist mapped tests)"]
  A -->|"first failure"| C["cancel running checks, skip Phase B"]
  B --> R[("receipt")]
  C --> R
Loading
  • A lint error ends the run in about 2 s; --keep-going disables fail-fast.
  • Heavy suites never overlap, because each already uses every core.

5. Receipt and test environment

Concern How
What it binds to commit SHA, tree hash, base ref + SHA, bundle hash (all deployed scripts + hook JSON)
Eligibility clean worktree at start and end, --tiers auto, every required check passed, no unexpected file mutations
Location git rev-parse --git-dir/apm-preflight/: per worktree, never committed; logs per check
Test env CI-like: allowlisted env vars only, isolated HOME/XDG, short TMPDIR, USER=runner, UV_NO_SYNC=1, provisioned venv first on PATH
Generated files CONFORMANCE.* and .github/mcp.json restored after the run; any other mutation fails
Mirror gaps git config --global apm.preflight.lockTolerate <pkg> tolerates a missing locked version, recorded as lock_drift

6. Agent recovery loop

Legend: what happens when an agent tries to publish; the alt block is the new recovery loop.

sequenceDiagram
    participant A as Copilot agent
    participant H as preToolUse hook (gate.py)
    participant R as preflight.py
    participant O as origin
    A->>H: git push origin HEAD
    alt no fresh green receipt for this commit and base
        H-->>A: deny + exact runner command
        A->>R: python3 .../preflight.py
        R->>R: select checks from diff, run CI commands, write receipt
        R-->>A: PASS (receipt bound to HEAD + origin/main)
        A->>H: git push origin HEAD
    end
    H-->>A: no output (default permission flow)
    A->>O: push succeeds, PR opens ready for review
Loading

Trade-offs

  • Guardrail, not authority. The receipt is not tamper-proof and CI remains the merge authority; the gate removes diligence lapses, not malice.
  • Mirrored commands vs a shared selector. Policy copies ci.yml commands and fails on fingerprint drift, so every CI edit needs a one-line fingerprint refresh (--print-ci-fingerprints; this PR already absorbed fix(ci): bypass unresolvable Azure apt mirror when installing fish and zsh #3570). A plan shared by CI and preflight is the follow-up in the CI speed-up work.
  • Known gaps, documented in the README: sessions started in a subdirectory (Copilot CLI loads repo hooks only from the starting directory), git aliases, $(...)-constructed commands, git send-pack, and native Windows.
  • Full src/ runs are long locally (~30 min on an M-series Mac, dominated by unit.full, lifecycle smoke and pylint R0801). Pylint drops ~7x once the CI speed-up PR bumps it.
  • No CHANGELOG entry. Maintainer-scope tooling under packages/ and .github/hooks/; cut-release drops it as internal.

Benefits

  1. Unverified agent pushes and PR creations are denied before they reach CI (S1, S3, S5, S18 below).
  2. Agents need no new instructions: with a plain "commit and push" task, the agent recovered in 2 deny round trips and 199 s.
  3. Non-publish tool calls cost ~25 ms (shell) or nothing (non-shell, excluded by matcher); publish checks cost ~210-225 ms.
  4. Docs-only changes verify in ~3 min from a fresh clone; a lint failure stops the run in ~2 s.

Validation

.venv/bin/pytest packages/preflight-gate/tests -q → 354 passed in 76.30s. ruff check / ruff format --check packages/preflight-gate clean. apm audit --ci → [*] All 10 check(s) passed. Second apm install is idempotent.

Note

First CI escape, closed in this PR. The first CI run failed tests/unit/test_triage_advisory.py::test_local_package_snapshots_match_lockfile: the fingerprint refresh updated the deployed file's hash but not the package content_hash in apm.lock.yaml, and preflight did not select that test for packages/ edits (apm audit --ci does not check it). 2fde20fae corrects the hash and adds an apm.lock-snapshots check to the self-check lane, with tests/test_policy.py::test_package_edits_verify_lockfile_snapshot_hashes as the regression trap. The dogfood run below includes it.

Dogfood run of the deployed runner on this branch tip (2fde20fae, clean env, docs/tooling diff → T0+T1, PASS in 221 s):

Runner output from the earlier run on `8cae13c67` (PASS, 189 s wall)
[*] phase A: 16 check(s) concurrently (4 job(s))
  [+] T0 lint.pylint-dup (161.0s)
  [+] T0 lint.arch-boundaries (26.6s)
  [+] T1 arch.contracts (118.0s)
  [+] T1 apm.self-check (6.3s)
  ... 12 more checks under 9s each
  [i] wall time: phase A 161.4s, phase B 0.0s
[!] tolerated lock drift (...): filelock locked 4.2.10, installed 4.2.9
[+] preflight PASS; receipt .../worktrees/danielmeppiel-preflight-gate/apm-preflight/receipt.json

Scenario Evidence

Two rounds of black-box testing drove real copilot -p --trust-folder agents against a sandbox clone with a local bare remote (logs: session artifacts pfg-e2e-logs/, pfg-e2e-logs-r2/).

# Scenario (user promise) Principle(s) Test(s) proving it Type
1 An agent cannot push or open a PR without a green preflight for that exact commit Governed by policy tests/test_gate.py::test_new_commit_after_receipt_is_stale, ::test_base_moved_is_denied; E2E S1, S3, S5, S12 unit, e2e
2 Committing and pushing in one tool call cannot smuggle an unverified commit Governed by policy, Secure by default tests/test_chain.py::test_gate_denies_chained_push_even_with_fresh_receipt (regression-trap for E2E D1); E2E S18 unit, e2e
3 An agent with no preflight instructions recovers from the deny alone DevX E2E S15 (2 round trips, 199 s, ref matched green receipt) e2e
4 Ordinary tool calls are not slowed or blocked DevX tests/test_launcher.py::test_matcher_skips_non_gated_tools, ::test_non_publish_shell_commands_never_start_python; E2E S6 (0 Python starts) unit, e2e
5 A broken hook never bricks an agent session DevX tests/test_launcher.py::test_python_missing_fails_open; E2E S13 (syntax error, missing script, malformed stdin) unit, e2e
6 Tags and other branches cannot ride on a receipt for HEAD Governed by policy tests/test_gate.py::test_tag_pushes_are_denied_even_with_receipt; E2E S11 unit, e2e
7 A fresh clone with no venv provisions itself and goes green DevX, Portability by manifest tests/test_lock_env.py::test_drift_triggers_provisioning_then_passes; fresh-clone verification (provisioned in 19.5 s, PASS in 3m20s) unit, e2e
8 Checks that mutate tracked files cannot yield a green receipt Governed by policy tests/test_runner.py::test_tree_mutation_is_detected unit
9 Editing a local package cannot leave a stale lockfile hash for CI to find Governed by policy tests/test_policy.py::test_package_edits_verify_lockfile_snapshot_hashes (regression-trap for this PR's first CI failure) unit
10 Only an exact, process-level bypass skips the gate Secure by default tests/test_gate.py::test_bypass_requires_exact_value unit

How to test

  • apm install at the repo root → .github/hooks/preflight-gate-preflight-gate.json present and unchanged.
  • Start copilot at the repo root on a new branch, ask it to make a docs edit, commit and push → first push denied with the runner command; after python3 .github/hooks/scripts/preflight-gate/.apm/hooks/scripts/preflight.py passes, the push succeeds.
  • Ask it to run git commit --allow-empty -m x && git push → denied with "run the push/PR command as its own tool call".
  • Ask it to run ls and git status → unaffected.
  • If your package mirror lacks filelock==4.2.10: git config --global apm.preflight.lockTolerate filelock once.

Issue and approved scope

Issue: Fixes #3579

Human scope-approval comment: none separate. #3579 records Daniel Meppiel (@danielmeppiel)'s explicit session direction (local pre-PR verification for autopilot PRs, delivered as a hook in a local APM package, tested end to end with subagents, no waiting on CI before marking ready). It is not presented as a machine-verified apm-scope:v1 comment.

This PR completes #3579. Review contact: Daniel Meppiel (@danielmeppiel).

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

Package suite, audit, dogfood run and two E2E rounds are listed under Validation. The repo's own suites were not run in full for this PR; CI runs them.

Spec conformance (OpenAPM v0.1)

  • Spec edit
  • Manifest edit
  • Test edit
  • CONFORMANCE.{md,json} regenerated
  • N/A -- this PR does not change OpenAPM-observable behaviour.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

Adds packages/preflight-gate, a repo-local APM package with a
diff-aware preflight runner (mirrors the ci.yml PR lanes verbatim,
fingerprint-bound against drift) and a preToolUse hook that denies
git push / gh pr create|ready / PR-creating tools unless a fresh,
green, commit-bound receipt matches the pushed commit. The hook is
the only agent-facing surface: deny reasons are self-sufficient.

Wired into the root apm.yml (dependency + executables.allow grant)
and deployed to .github/hooks/ by apm install.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ance

- Run checks inside a tier on a bounded pool (--jobs, default
  min(4, cpus)); xdist/E2E suites are marked exclusive in the policy
  and run alone. Tiers stay sequential with stop-after-failing-tier;
  logs stay per check and the summary prints in policy order. The
  receipt records parallel, jobs and tier_wall_s.
- Drop the "open the PR as draft" deny guidance; CI-only lanes are a
  neutral README note.
- Engage only for publish actions: a preToolUse matcher limits the
  hook to shell and create-PR tools, and the launcher starts Python
  only for push / gh pr / gh api pulls / create_pull_request payloads
  (pure shell match). Git alias expansion is dropped (documented).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace per-tier waves with a two-phase schedule over all selected
tiers. Phase A runs every non-exclusive check concurrently on the
bounded pool (so arch.contracts overlaps pylint); phase B runs the
exclusive xdist/E2E checks one at a time in tier order. A phase A
failure skips phase B and a failing exclusive check skips the rest,
unless --keep-going. Tiers stay the selection unit: a tier counts as
ran only if all its checks ran. The receipt records phase_wall_s and
skipped_checks instead of tier_wall_s.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- D1: a gated push/PR is only allowed when every preceding segment in the
  same tool call is read-only (cd/pushd/popd/true/echo/printf and git
  status/log/diff/show/fetch/rev-parse/remote -v/branch --show-current/
  config --get); otherwise deny and name the segment.
- D2: the hook command resolves the repo root when the repo-relative
  launcher path does not exist, so sessions in subdirectories are gated;
  user-scope absolute paths keep working.
- D3: command checks run in a CI-like env (allowlisted vars, isolated
  HOME/XDG, USER=runner, short TMPDIR, GIT_EXEC_PATH kept, real uv
  cache/config); env.lock-sync fails
  when the uv env drifts from uv.lock; policy VOLATILE_OUTPUTS
  (CONFORMANCE.*, .github/mcp.json) are restored and recorded as
  restored_outputs instead of failing tree mutation.
- D4/D9: per-cause Fix lines (tags/other-branch/chained/unparseable do not
  say "run preflight"); failed checks list their actual log files.
- D5: gate update_pull_request only when it clears draft / marks ready;
  document git -c alias, $(echo git) push and git send-pack as limits.
- D6: runner exits 1 when the receipt is not gate-eligible.
- D8: `gh pr create --help/-h` is exempt.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
env.lock-sync now runs before phase A and repairs drift in place (on by
default; --no-provision disables): `uv sync --frozen --extra dev`,
falling back to `uv export` + `uv pip sync` through the configured index
and an editable re-install of the project, then re-checks. uv.lock is
never modified.

APM_PREFLIGHT_LOCK_TOLERATE (machine-local, comma list) names packages a
mirror cannot serve at the locked version: provisioning installs the
highest same-major.minor version (or keeps the installed one), the drift
is printed as [!] and recorded as lock_drift, and the receipt stays
gate-eligible. Any other drift still fails.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- env.lock-sync is selected on every run (T0-only included) and
  provisions a missing/drifted env with ci.yml's PYTHON_VERSION; child
  checks always get UV_NO_SYNC=1, UV_FROZEN=1 and the project env's bin/
  first on PATH, so no host tool (e.g. a newer ruff) is ever used and
  callers need not export anything.
- Lock tolerance is also read from machine-local git config
  apm.preflight.lockTolerate (APM_PREFLIGHT_LOCK_TOLERATE wins).
- Fail-fast: the first failing check (or a failed env.lock-sync)
  cancels running Phase A checks by process group and skips the rest;
  receipt records cancelled_checks. --keep-going runs everything.
- Deny polish: chained calls spell out commit / preflight / push alone;
  failed receipts say fix, commit, re-run and list up to 6 failed ids
  with the logs dir; other-branch pushes say push only HEAD.
- spec.conformance runs with APM_NO_DIRECT_FALLBACK=1 so apm skips its
  public release lookup: CI tests the merge commit (latest version) and
  never sees the update banner that breaks JSON-parsing spec tests on a
  branch cut before the latest release. The isolated HOME also marks the
  daily update check as done.
- README: hooks load only from the session's starting directory.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
main #3570 replaced the lifecycle apt install step with scripts/ci-apt-install.sh; preflight does not mirror that step, so only the fingerprint changes. Deployed copy and apm.lock.yaml hash updated without unrelated lock churn.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical gaps allow unverified commits to be published and stale binaries to produce preflight receipts, while incomplete process cleanup can leave children modifying the checkout after cancellation.

7 open issues
What changed in this PR

Adds a repository-local preflight package for #3579, intended to require successful local verification before Copilot agents push commits or publish PRs. CI remains the merge authority.

Changes:

  • Adds a publish hook with receipt validation, recovery instructions, and a human bypass.
  • Introduces diff-aware CI checks, environment provisioning, concurrent scheduling, and commit-bound receipts.
  • Registers and deploys the package, with tests for classification, receipt handling, scheduling, and failure recovery.
File Description
packages/​preflight-gate/​tests/​test_runner.py Tests receipts, eligibility, environment isolation, and tree hygiene.
packages/​preflight-gate/​tests/​test_policy.py Tests tier selection and CI command parity.
packages/​preflight-gate/​tests/​test_lock_env.py Tests dependency drift detection and provisioning.
packages/​preflight-gate/​tests/​test_launcher.py Tests launcher filtering, deployment paths, and fail-open behavior.
packages/​preflight-gate/​tests/​test_gate.py Tests receipt validation, bypass, and worktree isolation.
packages/​preflight-gate/​tests/​test_deny_reason.py Tests actionable denial messages.
packages/​preflight-gate/​tests/​test_concurrency.py Tests scheduling, cancellation, and exclusive checks.
packages/​preflight-gate/​tests/​test_classify.py Tests shell and PR-operation classification.
packages/​preflight-gate/​tests/​test_chain.py Tests publication after chained commands.
packages/​preflight-gate/​tests/​conftest.py Provides isolated Git sandboxes and fake policies.
packages/​preflight-gate/​tests/​.gitignore Excludes temporary test sandboxes.
packages/​preflight-gate/​ruff.toml Inherits lint rules and configures package test exceptions.
packages/​preflight-gate/​README.md Documents usage, checks, bypass, and limitations.
packages/​preflight-gate/​apm.yml Defines the local hook package.
packages/​preflight-gate/​.apm/​hooks/​scripts/​preflight.py Implements check execution and receipt generation.
packages/​preflight-gate/​.apm/​hooks/​scripts/​preflight_policy.py Defines check selection, commands, and CI fingerprints.
packages/​preflight-gate/​.apm/​hooks/​scripts/​gate-launcher.sh Filters candidate publish calls before starting Python.
packages/​preflight-gate/​.apm/​hooks/​preflight-gate.json Declares the hook matcher and launch commands.
apm.yml Adds the dependency and version-pinned hook permission.
apm.lock.yaml Records package ownership, deployment paths, and hashes.
.github/​hooks/​scripts/​preflight-gate/​.apm/​hooks/​scripts/​preflight.py Deploys the local verification runner.
.github/​hooks/​scripts/​preflight-gate/​.apm/​hooks/​scripts/​preflight_policy.py Deploys the check-selection policy.
.github/​hooks/​scripts/​preflight-gate/​.apm/​hooks/​scripts/​gate-launcher.sh Deploys the publish-call launcher.
.github/​hooks/​preflight-gate-preflight-gate.json Activates the repository-level Copilot hook.

Review effort: Balanced

Comment on lines +16 to +25
case "$payload" in
*create_pull_request*|*push*) publish=1 ;;
*update_pull_request*)
case "$payload" in *draft*|*ready*|*Ready*) publish=1 ;; esac ;;
*'gh '*|*'gh\t'*)
case "$payload" in
*'pr '*|*'pr\t'*|*'pr"'*|*pulls*|*createPullRequest*|*markPullRequestReadyForReview*)
publish=1 ;;
esac ;;
esac

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: the launcher now checks the push, update-tool and gh publish patterns in independent case blocks, so a tool name in an argument can no longer mask gh pr create. Regression: test_launcher.py::test_gh_pr_create_mentioning_update_tool_name_starts_python.

# Segments that may precede a gated push/PR in the same tool call: they cannot
# move HEAD, rewrite history or change the worktree (D1: chained pushes).
READ_ONLY_COMMANDS = {"cd", "pushd", "popd", "true", "echo", "printf"}
READ_ONLY_GIT = {"status", "log", "diff", "show", "fetch", "rev-parse"}

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: fetch is removed from the read-only chain allowlist (README updated), so git fetch origin other:other && git push origin other is denied as a chained publish. Regression: test_chain.py::test_fetch_moving_branch_before_push_is_denied.

sources.append(src or "HEAD")
if refspecs and not sources:
return None
return Action("git-push", cwd, text, sources=sources or ["HEAD"])

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: an implicit push (no refspec) is now denied when the effective push.default is matching or any remote.<name>.push is set, including git -c overrides; --config-env and GIT_CONFIG_* overrides deny it outright. Local git config reads only, no network. Regressions: test_gate.py::test_implicit_push_with_push_default_matching_is_denied, ::test_implicit_push_with_remote_push_refspecs_is_denied.

Comment on lines +805 to +806
head = current
if action.head:

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: API creation (REST POST pulls, GraphQL createPullRequest incl. variables) keeps the requested head/base, which must match the receipt; ready operations (gh pr ready, PATCH pulls/N, markPullRequestReadyForReview, *update_pull_request) look up the PR's actual head/base via gh (8 s cap) and deny when the PR cannot be established. Regressions: test_gate.py::test_api_pr_creation_binds_requested_head_and_base, ::test_ready_operations_bind_the_prs_actual_head, ::test_pr_lookup_timeout_denies_within_hook_budget.

Comment on lines +151 to +155
try:
proc.wait(timeout=wait)
return
except subprocess.TimeoutExpired:
continue

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: _kill_group keeps the SIGTERM grace period, polling the leader and the group, then always SIGKILLs the whole process group even if the leader already exited. Regression: test_concurrency.py::test_cancel_kills_child_that_ignores_sigterm (fails on the old code).

# env) and always prefer the project env's tools over anything on PATH.
venv_bin = lib.project_env(root, dict(os.environ)) / "bin"
env["PATH"] = f"{venv_bin}{os.pathsep}{env.get('PATH', '')}"
env.update({"UV_NO_SYNC": "1", "UV_FROZEN": "1"})

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: confirmed _resolve_apm_binary order (APM_BINARY_PATH > dist/ > PATH); the runner now pins APM_BINARY_PATH to the project env's bin/apm in every check environment. Regression: test_runner.py::test_lifecycle_checks_pin_project_apm_over_stale_dist (fails on the old code).

sandbox.write("FAIL_T0", "1\n")
sandbox.write("src/a.py", "x = 1\n")
sandbox.commit()
assert run(sandbox, fake_policy) == 1

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in #3594: the test now runs with --keep-going, so it exercises the behaviour it asserts regardless of core count.

…ntent_hash

CI failed test_local_package_snapshots_match_lockfile on #3580: the fingerprint refresh updated the deployed file hash but not the package content_hash in apm.lock.yaml, and preflight did not select that test for packages/ edits (apm audit --ci does not check it). Add apm.lock-snapshots to the self-check lane with a regression-trap test, and correct the hash.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit 2cc5d80 into main Nov 12, 2026
25 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-preflight-gate branch November 12, 2026 09:18
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 12, 2026
…ht receipt (#3580)" (#3598)

This reverts commit 2cc5d80.

The preToolUse hook makes every agent run the full CI-mirror preflight
locally before any push or PR. With many agents running in parallel on
one machine, those runs overload the host (load average above 90, runs
lasting up to 2 hours). CI stays the authority. Local overload
risk will be redesigned separately.

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(preflight): gate agent pushes and PRs on a local preflight receipt

2 participants