[issue #101] Document pinned-launcher operational caveat and post-commissioning evidence checklist

[Saber5656]

Summary

Repo-side deliverable for issue #101 (milestone M1 of the deterministic-harness migration, epic #120). Documents the operational caveat that day-to-day operation of the enforced Codex main agent must go through the pinned launcher, and adds a post-commissioning evidence checklist for the human administrator. The host-side deployment/commissioning itself is human-only (sudo/root) and intentionally not performed by this change.

Changes

• docs/runbooks/main-agent-enforcement.md
  • New Operational Caveat: Use the Pinned Launcher section: day-to-day operation must start through the root-owned pinned launcher; Codex App / IDE integrations / app-server sessions / direct codex invocations / the legacy wrapper remain out of enforcement scope with no ingress_enforced claim; the implemented ingress is Codex-only for now while the ingress contract stays launch-source-agnostic (refs [orchestrator] Make the frontdoor ingress contract launch-source-agnostic (extensible to Claude/Cursor/Grok) #119 and frontdoor-orchestrator-protocol.md).
  • New Post-Commissioning Evidence Checklist section with the exact assurance-report JSON paths (decision, profiles[0].claim_results.action_enforced, profiles[0].effective_claims, profiles[0].attestation_digest) and the authoritative sources for commissioning_id / sealed generation_id / selected generation_id / activation_id, requiring the generation ids to match across sources.

Testing

• python3 scripts/validate_all.py → result: pass (41 suites), re-run after each commit.
• Referenced paths verified to exist (organization/runtime/workflows/frontdoor-orchestrator-protocol.md, organization/runtime/workflows/profiles/verify_enforcement.md); profile id codex-main-agent-a-prime matches the shipped profiles.
• Docs-only change; no code or contract files touched.

Review

• tech-devopssec role review (independent session): approve, zero blocking findings. One minor evidence-clarity defect (report JSON nesting and generation-id sources left implicit) was fixed in the second commit; field paths were re-verified against agent_integration_assurance.py and the generation/activation state layout.

Human handoff (host work, out of scope here)

• Execute docs/runbooks/main-agent-enforcement.md end to end as the human administrator (root), commission per profiles/verify_enforcement.md, seal and select an active generation.
• Run the installed agent_integration_assurance.py report and record the report output and generation ids as evidence in the Agents-Vault task record — this is the issue close condition, so this PR intentionally does not auto-close the issue.

Refs #101

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added operational guidance requiring use of the approved, release-pinned launcher for the enforced main-agent frontend.
  • Clarified which launch paths are outside enforcement scope and that enforcement currently applies only through Codex.
  • Added a post-commissioning checklist covering assurance reports, enforcement verification, identifier cross-checks, and deployment acceptance evidence.
  • Clarified that incomplete or failed checks suppress enforcement claims.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e03734c3-2f82-40b2-9347-58703baddf86

📥 Commits

Reviewing files that changed from the base of the PR and between f71b8cd and 173c792.

📒 Files selected for processing (1)

• docs/runbooks/main-agent-enforcement.md

---

📝 Walkthrough

Walkthrough

The runbook documents the pinned launcher required for enforcement and adds a post-commissioning checklist covering assurance reports, sealed-generation validation, identifier cross-checks, runtime acceptance, and claim suppression conditions.

Changes

Main-agent enforcement operations

Layer / File(s)	Summary
Pinned launcher enforcement scope docs/runbooks/main-agent-enforcement.md	Limits enforcement evidence and ingress_enforced claims to the root-owned, release-pinned saihai-codex-main-agent launcher and identifies the current Codex-only ingress scope.
Post-commissioning evidence checklist docs/runbooks/main-agent-enforcement.md	Adds administrator steps for generating and preserving assurance reports, validating decisions and attestation data, cross-checking commissioning identifiers, completing runtime acceptance, and recording evidence without promoting claims.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• Issue #101 — The runbook changes implement the pinned launcher caveat and commissioning verification steps described by this issue.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation update about the pinned launcher caveat and post-commissioning evidence checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-101-enforcement-runbook-caveat

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}