Add trusted authorization for exact coding-agent pushes

[pengfei-threemoonslab]

Summary

• Add the contract-v18 human-authorization state machine for one exact coding-agent operation.
• Derive an unsigned, content-addressed authorization request from a validated review_required receipt and complete closed review set.
• Verify an externally produced, short-lived Ed25519 grant against a fixed host-owned trust policy; Agents Shipgate ships no signer, private-key loader, or approval command.
• Preserve the static verdict and merge authority while an accepted grant projects only one guarded agent_action_required command.
• Add verifier v0.6, handoff v6, human-authorization v1 schemas, a deterministic signature vector, local-contract v7, and the corresponding documentation.

Why

PR #274 correctly made conversation-level approval and coding-agent-authored declarations insufficient to clear a human-review boundary. That fail-closed behavior also exposed an adoption problem: users normally ask Codex or Claude Code to perform the reviewed operation.

This follow-up adds a narrow trusted bridge. A coding agent still cannot approve itself or invent semantic declarations. A separately protected host authenticates the human and signs one exact operation bound to the reviewed receipt, artifact set, engine, executor, repository, base/merge/source identities, trees, complete review set, destination ref, HTTPS endpoint, and force-with-lease OID.

Security and behavior

• Static release_decision, merge_verdict, merge authority, and completion authority never change.
• The only v1 operation is an exact force-with-lease Git push; raw git push is never exposed as agent authority.
• Synthetic PR merge commits, worktree overlays, Git replace refs, mutable/non-HTTPS endpoints, plugin-enabled plans, stale leases, expired/revoked grants, and editable workspace runtimes fail closed.
• Execution revalidates the receipt closure, engine, trust policy, grant, clock, repository, commit, and tree immediately before dispatch.
• The source graph is copied into an isolated bare store with lazy fetch and remote helpers disabled, then index-pack/fsck validated. Pack stdout, stderr, and elapsed time are bounded; SHA-1 and SHA-256 repositories are covered.
• V1 is POSIX-only and requires a real host broker boundary protecting the full Python environment/site-packages, dependencies, trust policy, credentials, and key. Same-UID file modes are not isolation.
• The 512 MiB compressed-pack ceiling does not bound expanded-object CPU/memory/disk; production brokers must impose cgroup/container-equivalent quotas.

Validation

• python -m pytest -q --ignore=tests/test_packaging.py
• pytest tests/test_packaging.py -q — 6 passed
• Final focused authorization/control/schema/trust-boundary suite — 589 passed
• python -m ruff check .
• python scripts/generate_schemas.py --check
• Documentation links and generated llms-full.txt contract checks
• Preflight: 64 changed files, no protected-surface touches, deterministic verification required
• Committed verifier: control.state=complete, decision=passed, merge_verdict=mergeable
• Receipt closure validated: sha256:039fde3df8b743d4631d839079ec704933ad70ce546734e6bcacaa34d4646af5

Human-owned follow-up before marking ready

Protected agent instructions were intentionally not edited by the coding agent. After reviewing this protocol, a human should update the protected AGENTS.md, shipped SKILL.md copies, Cursor/Claude instruction surfaces, and mirrored verifier prompts to describe the request → external sign → reverify → guarded execute flow, then regenerate parity outputs.