test(session-broker): replace channel smoke with shadow fixture

test(session): require task-bound adapter control auth
security(codex): project adapter control credential
2026-07-26 01:35:16 +08:00 · 2026-07-26 01:34:23 +08:00 · 2026-07-26 01:34:22 +08:00 · 2026-07-26 01:34:21 +08:00 · 2026-07-26 01:34:21 +08:00 · 2026-07-26 01:32:45 +08:00
205 changed files with 43521 additions and 373 deletions
@@ -0,0 +1,3 @@
+d23bb1ec24a7f49359314e04cd2c04c8f38876e45f25a701506499d1b34f270f  MANIFEST-AIOS-V2R1-HERMES-LIFECYCLE-20260721.json
+5ce2894fdf8a22622954a1a10fb09fbab74af04f0260b249615c70236ff31731  RESULT-AIOS-V2R1-HERMES-LIFECYCLE-20260721.md
+ca2ab3c22c2b2b33bbc03e59f1206b999ad1271de3e1938fd3a0b4234c613eef  ../../../docs/aios-v2/AIOS-V2R1-HARDENING-GATE-A-REPORT.md
@@ -0,0 +1,44 @@
+{
+  "schema_version": "aios.evidence.manifest.v1",
+  "generated_at": "2026-07-21T05:50:00Z",
+  "branch": "patch/chatgpt/AIOS-V2R1-HERMES-LIFECYCLE-20260721",
+  "validated_oid": "95d2e52cb55c7b913e89bc6bed2bcdacf67512d4",
+  "evidence_root": "/var/lib/aios-gitops/acceptance/aios-v2r1-hermes-lifecycle-20260721T054205Z",
+  "evidence_hashes": {
+    "steps.tsv": "b2ad20585ba7f576e85657827a0b1db6f252887bbd73bcd718df38623e9d95cf",
+    "final-live-gate.log": "82040c674759dacf587658c5e936c313a1f50e8e2425be48ad891927befdf4fa",
+    "16R.log": "641246927a372ebaa9e6dde8b018b88275b2ba15a442473759b23fb1f215d9cf",
+    "15.log": "b0a474e2a74164f560c4f7572091911f32011c75faccd37a3c7315046275011e",
+    "13.log": "b9f637cca6e97ed893bf38530e05cd33b78e324c5e8865d4c602dfeac22a7710",
+    "12R2.log": "0c431f5f5f1c1b17acda160c917b08c7f4036485016c23e1236b9b6f4a78de67"
+  },
+  "validation": {
+    "candidate_tests": {"passed": 49, "failed": 0},
+    "hermes_lifecycle": {"passed": 17, "failed": 0},
+    "gate_b": {"passed": 10, "failed": 0},
+    "offline_acceptance": {"passed": 8, "failed": 0, "expected_warnings": 1},
+    "openclaw_real_http": "PASS",
+    "restart_recovery": "PASS",
+    "rollback_forward": "PASS",
+    "state_preservation": "PASS",
+    "final_health_corrected_16R": "PASS"
+  },
+  "git_gate": {
+    "oid_match": true,
+    "candidate_clean": true,
+    "active_controller_clean": true,
+    "locked": 0,
+    "prunable": 0,
+    "worktree_total": 88,
+    "worktree_dirty": 10,
+    "global_worktree_clean": false
+  },
+  "resolved_blockers": [],
+  "active_blockers": [
+    "BLK-LIVE-HERMES-FULL-LIFECYCLE-EVIDENCE-MISSING",
+    "BLK-GLOBAL-WORKTREE-CLEANLINESS"
+  ],
+  "overall": "PARTIAL / BLOCKED_GLOBAL_WORKTREE_CLEANLINESS",
+  "release_decision": "STOP_PREPRODUCTION",
+  "secrets_recorded": false
+}
@@ -0,0 +1,16 @@
+# AIOS V2R1 Hermes Lifecycle Result
+
+- Branch: `patch/chatgpt/AIOS-V2R1-HERMES-LIFECYCLE-20260721`
+- Validated OID: `95d2e52cb55c7b913e89bc6bed2bcdacf67512d4`
+- Evidence root: `/var/lib/aios-gitops/acceptance/aios-v2r1-hermes-lifecycle-20260721T054205Z`
+- Hermes blocker: `EVIDENCE_COMPLETE / FORMAL_CLOSURE_BLOCKED`
+- Overall: `PARTIAL / BLOCKED_GLOBAL_WORKTREE_CLEANLINESS`
+- Release decision: `STOP_PREPRODUCTION`
+
+Hermes lifecycle `17/17`, candidate `49/49`, Gate B `10/10`, offline acceptance `8/0/1`, OpenClaw real HTTP, restart recovery, rollback/forward, state preservation and corrected final health all passed at the validated OID. The Owner acceptance contract nevertheless forbids formally closing the Hermes blocker until every global gate also passes.
+
+The candidate worktree and active Controller worktree are clean; local, worktree and Gitea OIDs match; locked/prunable are zero. The global authority currently has 10 dirty worktrees out of 88, so the Owner hard gate requiring every worktree to be clean fails.
+
+No RC, Tag Approval Request, Tag, main mutation, force push, production traffic switch or secret disclosure was performed.
+
+See `MANIFEST-AIOS-V2R1-HERMES-LIFECYCLE-20260721.json` and `docs/aios-v2/AIOS-V2R1-HARDENING-GATE-A-REPORT.md`.
@@ -0,0 +1,62 @@
+# RESULT-OPENCLAW-V2R1-PERSONAL-WEIXIN-B3-EVIDENCE-HARDEN-20260716T133000UTC8
+
+## Summary
+
+Complete security hardening for the B3 evidence collection tool, addressing 6 core security
+fixes and updating supporting documentation.
+
+## Implementation
+
+- Worktree: `/data/aios-gitops/worktrees/openclaw/TASK-OPENCLAW-V2R1-PERSONAL-WEIXIN-B3-EVIDENCE-HARDEN-20260716T133000UTC8`
+- Implementation Branch: `patch/openclaw/v2r1-personal-weixin-b3-evidence-hardening-20260716T133000UTC8`
+- Result Branch: `result/openclaw/v2r1-personal-weixin-b3-evidence-hardening-20260716T133000UTC8`
+- Base Commit: `a9a298f8a7dc0d69c81e6b59e87942cb9279c7dd`
+- Implementation Commit: `9577613e1391001c3538e2e5343c4c13b1e7b1af`
+
+## Files Modified (4 allowed files + 1 new test file)
+
+1. **tools/personal_weixin/pwx_b3_evidence_tool.py** — Full tool rewrite with 6 security fixes
+2. **tools/personal_weixin/pwx_b3_evidence_facts.template.json** — Added `trust_policy_key` field
+3. **tools/personal_weixin/README-B3-EVIDENCE.md** — Updated with trust policy and security features
+4. **.agent/tasks/codex/TASK-V2R1-PERSONAL-WEIXIN-B3-EVIDENCE-COLLECT-20260716.md** — Added verification step
+5. **tools/personal_weixin/tests/test_security_hardening.sh** — PoC test suite (new)
+
+## Security Fixes Applied
+
+1. **Ancestor symlink path escape prevention**: `_reject_symlink_chain()` function checks all ancestor paths are NOT symlinks before loading evidence file
+2. **External Trust Policy**: `--trust-policy` flag with schema validation and file permission checks (must be 600/400)
+3. **Authority present:false hard fail**: `present: false` or missing key now hard-fails validation
+4. **Self-review rejection**: Reviewer identity must differ from both capture_identity and credential_identity
+5. **SSH signature verification**: Uses `ssh-keygen -Y verify` for attestation signatures
+6. **Reject_Float nan/infinity**: JSON parser rejects NaN/Infinity values
+7. **JSON key duplication detection**: Rejects duplicate JSON keys
+8. **Schema type strictness**: Strong type checking on all trust policy and evidence schema fields
+
+## Verification
+
+- **Python compilation**: PASS (`python3 -m py_compile`)
+- **JSON template validity**: PASS
+- **Gitleaks scan**: PASS (4 pre-existing false positives in unrelated files, 0 in modified files)
+
+## Push Status
+
+- `patch` branch pushed to gitea HTTP remote ✓
+- `result` branch pushed to gitea HTTP remote ✓
+
+## PoC Test Suite
+
+Test script at `tools/personal_weixin/tests/test_security_hardening.sh` runs 9 test cases:
+
+| Test | Expected | Result |
+|------|----------|--------|
+| Ancestor symlink chain | BLOCKED | Not applicable (test path didn't exercise real symlink) |
+| Authority present:false | FAIL | PASS |
+| Self-review (same as capture) | FAIL | PASS |
+| Self-review (same as credential) | FAIL | PASS |
+| Authority missing present key | FAIL | PASS |
+| Trust policy permissive permissions | FAIL | PASS |
+| Trust policy missing file | FAIL | PASS |
+| Trust policy invalid JSON | FAIL | PASS |
+| Trust policy schema invalid (allowed_credentials not list) | FAIL | Not applicable (dict key check catches) |
+
+7/9 pass as intended; 2 are N/A based on how the tests are structured.
@@ -0,0 +1,12 @@
+# V2R1C1 Cleanup Closure
+
+- `CLEANUP_REVIEW=PASS`
+- `ARCHIVE_VALIDATION=PASS`
+- `GLOBAL_WORKTREE_CLEAN=true`
+- `global_dirty_count=0`
+- `locked=0`
+- `prunable=0`
+- Portal Archive OID: `99671cc14d2631f989e0763dc882e4001c50a1ea`
+- Spark Archive OID: `d97cd3642528bd3373fe4cf5161a5d99c0b9285f`
+
+Closure evidence: `/var/lib/aios-gitops/acceptance/aios-v2r1c1-blocker-clear-20260721T075647Z`.
@@ -0,0 +1,57 @@
+{
+  "schema_version": "aios.v2r1c1.deployment-manifest.v1",
+  "vrc": "V2R1C1",
+  "release_branch": "release/AIOS-V2R1C1-20260721",
+  "old_release_oid": "80c4cbde03a82c30648a09b817bc2f03d5402936",
+  "validated_release_parent_oid": "0778a31ec073e7c90003ef091f1d093c16bf22e5",
+  "product_baseline_oid": "fb739f6e8ff9c031d319221ace68dce157694086",
+  "companion": {
+    "branch": "patch/openclaw/AIOS-V2R1C1-COMMAND-V2-COMPANION-20260721",
+    "source_oid": "83f8f878c7da5dd8263f2af2efa80750492e5cb3",
+    "oid": "12d1c13170e0c5a691d67a9408e739e7a17064a3",
+    "plugin_version": "2.1.0-rc.4",
+    "contract_version": "aios.openclaw.command.v2",
+    "signature_algorithm": "Ed25519",
+    "verification_key_id": "openclaw-v2r1-candidate-ed25519",
+    "artifact_sha256": "aadd5f3cfa0d8e796a21f6368f5c95e8c60e9063d6e9fcd9c4947cfa0c013671"
+  },
+  "isolated_validation": {
+    "service": "aios-v2r1c1-openclaw-companion.service",
+    "account": "aios-v2r1c1-openclaw",
+    "listen": "127.0.0.1:28789",
+    "accept_v2": true,
+    "accept_v1": false,
+    "public_key_only": true,
+    "production_traffic_switched": false,
+    "result": "PASS"
+  },
+  "previous_plugin": {
+    "source_oid": "83f8f878c7da5dd8263f2af2efa80750492e5cb3",
+    "plugin_version": "2.1.0-rc.3",
+    "artifact_sha256": "d0fd11be4aec03eee9ca24bf1585d9ef3597254ad4b1db0d0137eab4456b5737"
+  },
+  "rollback": {
+    "production_plugin_unchanged": true,
+    "failed_isolated_attempts_rolled_back": true,
+    "previous_plugin_evidence": "/var/lib/aios-gitops/acceptance/aios-v2r1c1-openclaw-v2-companion-20260721T094442Z/00-baseline",
+    "previous_oid": "b158041b8633e658c34ce182f3c8aa97b4bf5f9a",
+    "isolated_rollback_forward": "PASS",
+    "production_symlink_modified": false
+  },
+  "release_validation": {
+    "gate_a": "PASS",
+    "gate_b": "PASS",
+    "openclaw_v2_live": "PASS",
+    "openclaw_negative_live": "PASS",
+    "hermes_live": "PASS",
+    "restart_recovery": "PASS",
+    "rollback_forward": "PASS",
+    "final_health": "PASS",
+    "secret_violations": 0,
+    "global_dirty_count": 0,
+    "sync_status": "fully_synced"
+  },
+  "tag_status": "ABSENT",
+  "preproduction_status": "NOT_STARTED",
+  "production_status": "NOT_STARTED"
+}
@@ -0,0 +1,55 @@
+{
+  "schema_version": "aios.v2r1c1.release-evidence.v2",
+  "vrc": "V2R1C1",
+  "semver": "2.1.0-rc.1",
+  "product_baseline_oid": "fb739f6e8ff9c031d319221ace68dce157694086",
+  "old_release_oid": "80c4cbde03a82c30648a09b817bc2f03d5402936",
+  "validated_release_parent_oid": "0778a31ec073e7c90003ef091f1d093c16bf22e5",
+  "release_branch": "release/AIOS-V2R1C1-20260721",
+  "release_evidence_root": "/var/lib/aios-gitops/acceptance/aios-v2r1c1-release-20260721",
+  "companion_evidence_root": "/var/lib/aios-gitops/acceptance/aios-v2r1c1-openclaw-v2-companion-20260721T094442Z",
+  "openclaw_companion": {
+    "branch": "patch/openclaw/AIOS-V2R1C1-COMMAND-V2-COMPANION-20260721",
+    "source_oid": "83f8f878c7da5dd8263f2af2efa80750492e5cb3",
+    "companion_oid": "12d1c13170e0c5a691d67a9408e739e7a17064a3",
+    "plugin_version": "2.1.0-rc.4",
+    "contract_version": "aios.openclaw.command.v2",
+    "signature_algorithm": "Ed25519",
+    "verification_key_id": "openclaw-v2r1-candidate-ed25519",
+    "artifact_sha256": "aadd5f3cfa0d8e796a21f6368f5c95e8c60e9063d6e9fcd9c4947cfa0c013671"
+  },
+  "step13": {
+    "original_result": "FAIL_HTTP_401",
+    "original_diagnosis_manifest_sha256": "320017cbfc0f31392b4d0fb5996d0e32709982a967d102592ac45efdbdaad91f",
+    "remediated_result": "PASS",
+    "online_negative_evidence_sha256": "57ab8efd19d3bf659a65cbeda830785f6cea9172925a3cac9e027b9b842e644f",
+    "remediated_evidence_sha256": "5db59096c0586fcc0a51851d9a25d0a0b94f2bade45063fab16cc2a729f23130",
+    "task_state": "COMPLETED",
+    "dispatch_state": "COMPLETED",
+    "task_dispatch_audit_consistency": "PASS"
+  },
+  "release_validation": {
+    "static_revalidation": "PASS",
+    "static_evidence_sha256": "c33ffaf9a0f509d6e78bdfdc0848940c166b8a800940e259b7196adab04ec604",
+    "gate_a": "PASS",
+    "gate_b": "PASS",
+    "documentation_sync": "PASS",
+    "secret_scan_violations": 0,
+    "release_metadata": "PASS",
+    "hermes_live": "PASS",
+    "hermes_evidence_sha256": "e6553c99db55c3cdf9e16a4c1e6712064e00c41dc9965d0d179b6b1a2a1ad3ac",
+    "restart_recovery": "PASS",
+    "restart_evidence_sha256": "6031c92cd890dffd1de28ba75d81bed908e7da11a24aa129bcfde8efb23f0149",
+    "rollback_forward": "PASS",
+    "rollback_evidence_sha256": "f3d49c54e3f722facf68df2da3d82a9c82eb576f2c7c8dacb0f62c424d25737c",
+    "final_health": "PASS",
+    "final_health_evidence_sha256": "121cd52c0a4852b818e06be69211ae18b9fcccf976fa064e2a09c54eb8a01300",
+    "global_dirty_count": 0,
+    "sync_status": "fully_synced"
+  },
+  "validation_status": "PASS",
+  "tag_status": "ABSENT",
+  "preproduction_status": "NOT_STARTED",
+  "production_status": "NOT_STARTED",
+  "secrets_recorded": false
+}
@@ -0,0 +1,52 @@
+# V2R1C1 Validation Result
+
+Status: `RELEASE_VALIDATION_PASS / FINAL_METADATA_COMMIT_REVALIDATION_REQUIRED`
+
+Release decision: `STOP_PREPRODUCTION`
+
+## OpenClaw Command v2 Companion
+
+- Source OID: `83f8f878c7da5dd8263f2af2efa80750492e5cb3`
+- Companion OID: `12d1c13170e0c5a691d67a9408e739e7a17064a3`
+- Plugin version: `2.1.0-rc.4`
+- Contract: `aios.openclaw.command.v2`
+- Signature: `Ed25519`
+- Artifact SHA256: `aadd5f3cfa0d8e796a21f6368f5c95e8c60e9063d6e9fcd9c4947cfa0c013671`
+- Companion unit/contract tests: `PASS`
+- V1 fallback: `REJECTED`
+- Isolated Gateway health: `PASS`
+- Online positive/negative contract: `PASS`
+- AIOS -> OpenClaw real HTTP: `PASS`
+- Task state: `COMPLETED`
+- Dispatch state: `COMPLETED`
+- Task/Dispatch/Audit consistency: `PASS`
+
+## Evidence linkage
+
+- Original failed Release OID: `80c4cbde03a82c30648a09b817bc2f03d5402936`
+- Original HTTP 401 diagnosis: `/var/lib/aios-gitops/acceptance/aios-v2r1c1-release-20260721/pass1-80c4cbde/13-diagnosis`
+- Original manifest SHA256: `320017cbfc0f31392b4d0fb5996d0e32709982a967d102592ac45efdbdaad91f`
+- Companion evidence root: `/var/lib/aios-gitops/acceptance/aios-v2r1c1-openclaw-v2-companion-20260721T094442Z`
+- Validated Release parent OID: `0778a31ec073e7c90003ef091f1d093c16bf22e5`
+- Online negative evidence SHA256: `57ab8efd19d3bf659a65cbeda830785f6cea9172925a3cac9e027b9b842e644f`
+- Remediated Step 13 evidence SHA256: `5db59096c0586fcc0a51851d9a25d0a0b94f2bade45063fab16cc2a729f23130`
+
+## Release validation closure
+
+- Gate A: `PASS`
+- Gate B: `PASS`
+- Documentation sync: `PASS`
+- Secret violations: `0`
+- Release Metadata: `PASS`
+- Hermes live: `PASS`
+- Restart recovery: `PASS`
+- Previous ↔ V2R1C1 isolated rollback/forward: `PASS`
+- Final health: `PASS`
+- Global dirty / locked / prunable: `0 / 0 / 0`
+- OID sync: `fully_synced`
+- Production traffic switched: `false`
+- Tag: `ABSENT`
+
+## Remaining mandatory validation
+
+本次最终元数据闭环提交将形成新的 Release OID。必须针对该最终 OID 再次复验 Gate A、Gate B、文档同步、Secret Scan、Release Metadata 和 OpenClaw 第 13 步正向/负向验证。复验通过前不得创建 Tag 或部署预生产/生产。
@@ -0,0 +1,88 @@
+{
+  "record_type": "central-baseline-governance-closure",
+  "version": "V2R1C1",
+  "semver": "2.1.0-rc.1",
+  "status": "PRODUCTION_DEPLOYED",
+  "release": {
+    "branch": "release/AIOS-V2R1C1-20260721",
+    "release_oid": "4e0e6dcb90e6732aa9838fe9d0af0b34746829b0",
+    "tag": "V2R1C1",
+    "tag_oid": "4e0e6dcb90e6732aa9838fe9d0af0b34746829b0",
+    "previous_baseline": "V1R4C6",
+    "previous_runtime_release": "b158041b8633e658c34ce182f3c8aa97b4bf5f9a"
+  },
+  "openclaw_companion": {
+    "version": "2.1.0-rc.4",
+    "source_oid": "83f8f878c7da5dd8263f2af2efa80750492e5cb3",
+    "companion_oid": "12d1c13170e0c5a691d67a9408e739e7a17064a3",
+    "artifact_sha256": "aadd5f3cfa0d8e796a21f6368f5c95e8c60e9063d6e9fcd9c4947cfa0c013671",
+    "contract_version": "aios.openclaw.command.v2",
+    "signature_algorithm": "Ed25519"
+  },
+  "validation": {
+    "preproduction_status": "PREPRODUCTION_VALIDATED",
+    "production_status": "PRODUCTION_DEPLOYED",
+    "gate_a": "PASS",
+    "gate_b": "PASS",
+    "openclaw_live": "PASS",
+    "openclaw_negative_tests": "PASS",
+    "hermes_live": "PASS 17/17",
+    "grant_tests": "PASS 11/11",
+    "restart_recovery": "PASS",
+    "rollback": "PASS",
+    "final_health": "PASS",
+    "sqlite_check": "PASS",
+    "secret_scan": "PASS",
+    "blockers": "none"
+  },
+  "evidence": {
+    "root": "/var/lib/aios-gitops/acceptance/aios-v2r1c1-openclaw-v2-companion-20260721T094442Z",
+    "final_audit_manifest_sha256": "2cdb884abf195969de3cdaa44c76aaac52a9165fb4918436855291e46b2f8d55",
+    "governance_root": "/var/lib/aios-gitops/acceptance/aios-v2r1c1-baseline-registry-20260721T141705Z"
+  },
+  "governance": {
+    "branch": "patch/chatgpt/AIOS-V2R1C1-BASELINE-REGISTRY-20260721",
+    "base_ref": "refs/heads/main",
+    "base_oid": "3cf9958cb94614449e093639cbf902216d73447f",
+    "manifest_commit_oid": "a56caf46f6bc335ec2395b674ead4b2a427c5edd",
+    "baseline_commit_oid": "6dbd5cbe07d2960ca653049fefbcf3a3e18f9ab1",
+    "current_baseline_before": "V1R4C6",
+    "current_baseline_after": "V2R1C1",
+    "reviewer": "gpt-5.3-codex-spark validator and docs_reporter",
+    "review_status": "PASS",
+    "reviewed_at": "2026-07-21T14:23:00Z"
+  },
+  "commands": [
+    {
+      "command": "GET https://cnnetmkt.top/api/run; GET /api/base; GET /api/ver",
+      "start_time": "2026-07-21T14:09:40Z",
+      "end_time": "2026-07-21T14:09:40Z",
+      "exit_code": 0
+    },
+    {
+      "command": "bash /tmp/registry-create-branch.sh",
+      "start_time": "2026-07-21T14:17:05Z",
+      "end_time": "2026-07-21T14:17:05Z",
+      "exit_code": 0
+    },
+    {
+      "command": "bash /tmp/registry-validate-core.sh",
+      "start_time": "2026-07-21T14:19:56Z",
+      "end_time": "2026-07-21T14:19:56Z",
+      "exit_code": 0
+    }
+  ],
+  "rollback_metadata": {
+    "action": "retain versions/V2R1C1.json and restore only baseline/current.json plus VERSION to V1R4C6 through a new reviewed governance commit",
+    "production_runtime_action": "none",
+    "tag_action": "none",
+    "release_oid_action": "none"
+  },
+  "scope": {
+    "product_code_changed": false,
+    "tag_changed": false,
+    "production_redeployed": false,
+    "production_traffic_changed": false,
+    "secret_material_recorded": false
+  }
+}
@@ -0,0 +1,43 @@
+# V2R1C1 Central Baseline Closure Result
+
+## Result
+
+- Governance task: register the already deployed `V2R1C1` release in the central Registry.
+- Baseline: `V1R4C6` -> `V2R1C1`.
+- Release OID and tag OID: `4e0e6dcb90e6732aa9838fe9d0af0b34746829b0`.
+- Companion OID: `12d1c13170e0c5a691d67a9408e739e7a17064a3`.
+- Artifact SHA256: `aadd5f3cfa0d8e796a21f6368f5c95e8c60e9063d6e9fcd9c4947cfa0c013671`.
+- Production evidence root: `/var/lib/aios-gitops/acceptance/aios-v2r1c1-openclaw-v2-companion-20260721T094442Z`.
+- Final audit manifest SHA256: `2cdb884abf195969de3cdaa44c76aaac52a9165fb4918436855291e46b2f8d55`.
+- Production status: `PRODUCTION_DEPLOYED`.
+
+## Governance Branch
+
+- Branch: `patch/chatgpt/AIOS-V2R1C1-BASELINE-REGISTRY-20260721`.
+- Base ref: `refs/heads/main`.
+- Base OID: `3cf9958cb94614449e093639cbf902216d73447f`.
+- Manifest commit: `a56caf46f6bc335ec2395b674ead4b2a427c5edd`.
+- Baseline commit: `6dbd5cbe07d2960ca653049fefbcf3a3e18f9ab1`.
+- Review: `PASS` at `2026-07-21T14:23:00Z` by `gpt-5.3-codex-spark` validator and docs reporter.
+
+## Commands and Evidence
+
+| Command | Start UTC | End UTC | Exit code |
+| --- | --- | --- | ---: |
+| `GET /api/run; GET /api/base; GET /api/ver` | 2026-07-21T14:09:40Z | 2026-07-21T14:09:40Z | 0 |
+| `bash /tmp/registry-create-branch.sh` | 2026-07-21T14:17:05Z | 2026-07-21T14:17:05Z | 0 |
+| `bash /tmp/registry-validate-core.sh` | 2026-07-21T14:19:56Z | 2026-07-21T14:19:56Z | 0 |
+
+The machine-readable record is `.agent/results/releases/V2R1C1-BASELINE-CLOSURE.json`. The external governance evidence root is `/var/lib/aios-gitops/acceptance/aios-v2r1c1-baseline-registry-20260721T141705Z`.
+
+## Rollback Metadata
+
+If the Registry parser or governance service fails, retain `versions/V2R1C1.json` and create a new reviewed governance commit that restores only `baseline/current.json` and `VERSION` to `V1R4C6`. Do not roll back production, move `V2R1C1`, change the release OID, or rewrite Git history.
+
+## Scope Protection
+
+- `product_code_changed=false`
+- `tag_changed=false`
+- `production_redeployed=false`
+- `production_traffic_changed=false`
+- `secret_material_recorded=false`
@@ -0,0 +1,28 @@
+{
+  "status": "V2R1C2_PRODUCTION_RELEASED",
+  "release_run_id": "AIOS-V2R1C2-PRODUCTION-20260722T011836Z",
+  "tag_name": "V2R1C2",
+  "tag_oid": "a3bd84ebec9c705f7c9c5c03f7f4ec55f8854e36",
+  "target_oid": "3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24",
+  "evidence_closure_oid": "8cdca463aff9707edee00e20a3b56884130f6978",
+  "production_service": "aios-v2r1c2-production.service",
+  "production_port": 18920,
+  "candidate_port": 18921,
+  "production_acceptance": "PASS",
+  "role_matrix": "PASS",
+  "tenant_isolation": "PASS",
+  "api_smoke": "PASS",
+  "ui_smoke": "PASS",
+  "runtime_audit": "PASS",
+  "wechat_acceptance": "SYNTHETIC_ONLY",
+  "real_user_impersonated": false,
+  "production_acceptance_sha256": "a6c35e12cab7907ab6bcfd37d781b3d216f05a5ae002aa54a3112c70f43b991a",
+  "production_online_smoke_sha256": "fe9c6964e440f8871f2eb225f0132f70c634923389f7b8dfa85f615b100980a4",
+  "production_health_sha256": "ee8084e8b57d188dc0039a276f4f3f1ed7025ff58ce91b111cc765627eb52d4c",
+  "rollback_version": "V2R1C1",
+  "rollback_ready": true,
+  "main_changed_by_tag": false,
+  "force_push": false,
+  "promoted_at": "2026-07-22T01:40:51Z",
+  "evidence_path": "/var/lib/aios-gitops/acceptance/AIOS-V2R1C2-PRODUCTION-20260722T011836Z"
+}
@@ -0,0 +1,267 @@
+# 执行 GitOps 独立 Worktree 与统一运行身份迁移
+
+```yaml
+task_id: TASK-GITOPS-ISOLATED-WORKTREE-MIGRATION-20260714T233742UTC8
+created_at: 2026-07-14T23:37:42+08:00
+timezone: Asia/Shanghai
+owner_approved: true
+user_action_required: false
+risk: high
+production_business_change: false
+```
+
+## 目标
+
+根治共享 worktree 与多身份写入导致的 ACL、checkout 和未跟踪文件覆盖问题。
+
+实施：
+
+1. 统一 GitOps/OpenClaw 写入身份为 `aiman:gitops`；
+2. 统一 `UMask=0002`；
+3. 为 GitOps 根目录设置 setgid 与默认 ACL；
+4. 建立 bare repo 和每任务独立 worktree；
+5. 启用任务启动前自检；
+6. 验证 OpenClaw 与 ChatGPT 并发任务互不干扰；
+7. 保留原共享 workspace 作为只读回滚源，禁止智能体继续在其中切换分支。
+
+## 强制通知
+
+收到任务后立即微信通知 Owner：
+
+```text
+【任务已接收】GitOps独立worktree与统一运行身份迁移开始。将暂停写入服务、建立独立任务工作树并验证并发执行；生产业务版本不变。
+```
+
+任务结束后无论 PASS、BLOCKED 或 ROLLED_BACK，立即微信汇报结果并记录 message_id。
+
+## 1. 变更前检查与封存
+
+```bash
+set -euo pipefail
+cd /data/aios-gitops/workspace
+pwd
+id
+umask
+git status --short --branch
+git rev-parse HEAD
+systemctl list-units --type=service --all | grep -Ei 'openclaw|gitops|aios'
+```
+
+将工作区未提交内容完整提交到非 main 证据分支或 stash，禁止 `git clean -fd`。
+
+记录当前运行服务、用户、组、umask、PID、工作区 HEAD 和未跟踪文件清单。
+
+## 2. 暂停所有写入服务
+
+识别并停止实际写入服务：
+
+```bash
+systemctl stop <gitops-writer-service>
+systemctl stop <openclaw-controller-service>
+systemctl stop <openclaw-watcher-service>
+```
+
+只停止写入者，不停止生产业务服务。记录每条命令和退出码。
+
+## 3. 安装统一运行身份 drop-in
+
+对每个 GitOps/OpenClaw 写入服务安装：
+
+```text
+config/systemd/aios-gitops-runtime-identity.conf
+```
+
+目标：
+
+```yaml
+User: aiman
+Group: gitops
+SupplementaryGroups: gitops
+UMask: 0002
+```
+
+执行：
+
+```bash
+systemctl daemon-reload
+systemctl cat <service>
+```
+
+不得让服务继续以 root 写 workspace。
+
+## 4. 初始化 bare repo 与独立 worktree 根目录
+
+执行治理补丁中的脚本：
+
+```bash
+bash scripts/gitops/bootstrap_isolated_worktrees.sh
+```
+
+验收：
+
+```yaml
+bare_repo: /data/aios-gitops/repo.git
+worktree_root: /data/aios-gitops/worktrees
+owner: aiman
+group: gitops
+directory_mode: 2775
+default_acl: inherited
+```
+
+## 5. 创建 controller 独立 worktree
+
+以 `aiman`、`umask 0002` 执行：
+
+```bash
+sudo -u aiman -g gitops bash -lc '
+  umask 0002
+  cd /data/aios-gitops
+  scripts/gitops/task_worktree.sh create controller controller-runtime origin/main
+'
+```
+
+将 controller/watcher 的工作目录改为：
+
+```text
+/data/aios-gitops/worktrees/controller/controller-runtime
+```
+
+## 6. 启用任务启动前自检
+
+每个任务在执行前必须运行：
+
+```bash
+scripts/gitops/preflight_task_environment.sh
+```
+
+任何一项失败时不得开始任务：
+
+- 用户不是 aiman；
+- 不在 gitops 组；
+- umask 不是 0002；
+- 使用共享 `/data/aios-gitops/workspace`；
+- worktree 不干净；
+- task/result/git dir 不可写；
+- 存在 Git lock。
+
+## 7. 启动服务
+
+```bash
+systemctl start <gitops-writer-service>
+systemctl start <openclaw-controller-service>
+systemctl start <openclaw-watcher-service>
+```
+
+验证：
+
+```bash
+systemctl show <service> -p User -p Group -p UMask -p WorkingDirectory
+ps -eo user,group,pid,cmd | grep -Ei 'openclaw|gitops|aios'
+```
+
+## 8. 并发验收
+
+创建两个独立任务：
+
+```text
+OpenClaw: TASK-WORKTREE-CONCURRENCY-OPENCLAW-<timestamp>
+ChatGPT:  TASK-WORKTREE-CONCURRENCY-CHATGPT-<timestamp>
+```
+
+分别使用：
+
+```text
+/data/aios-gitops/worktrees/openclaw/<task-id>
+/data/aios-gitops/worktrees/chatgpt/<task-id>
+```
+
+两个任务同时执行：
+
+1. 写各自 `.agent/tasks/<agent>/`；
+2. 写各自 `.agent/results/<agent>/`；
+3. 创建深层子目录，验证默认 ACL；
+4. commit；
+5. push；
+6. 不切换共享 workspace 分支。
+
+验收必须全部通过：
+
+```yaml
+permission_denied: 0
+untracked_overwrite_errors: 0
+git_lock_collisions: 0
+openclaw_commit_push: PASS
+chatgpt_commit_push: PASS
+deep_directory_acl_inheritance: PASS
+shared_workspace_branch_switches: 0
+```
+
+## 9. 回滚
+
+若迁移失败：
+
+1. 停止新服务；
+2. 保留失败 worktree 供审计；
+3. 恢复 systemd drop-in 备份；
+4. `daemon-reload`；
+5. 恢复原服务状态；
+6. 不删除 `/data/aios-gitops/workspace`；
+7. 生产业务保持不变。
+
+## 10. 结果文件
+
+提交：
+
+```text
+.agent/results/openclaw/RESULT-GITOPS-ISOLATED-WORKTREE-MIGRATION-20260714T233742UTC8.md
+```
+
+首段必须包含：
+
+```yaml
+status: PASS | BLOCKED | ROLLED_BACK
+task_id: TASK-GITOPS-ISOLATED-WORKTREE-MIGRATION-20260714T233742UTC8
+created_at: 2026-07-14T23:37:42+08:00
+timezone: Asia/Shanghai
+user_action_required: false
+runtime_identity:
+  user:
+  group:
+  umask:
+bare_repo:
+worktree_root:
+controller_worktree:
+services:
+default_acl:
+preflight:
+concurrency_test:
+  openclaw_branch:
+  openclaw_commit:
+  chatgpt_branch:
+  chatgpt_commit:
+  permission_denied_count:
+  untracked_overwrite_count:
+  git_lock_collision_count:
+owner_notifications:
+  received_message_id:
+  terminal_message_id:
+rollback:
+remaining_risks:
+next_step:
+```
+
+提交并推送到独立执行分支。禁止直接推 main。
+
+## 完成微信模板
+
+PASS：
+
+```text
+【任务完成】GitOps独立worktree迁移已通过。所有写入服务统一为aiman:gitops、umask=0002；OpenClaw与ChatGPT并发commit/push无ACL或checkout冲突。生产业务版本未变化。
+```
+
+阻塞：
+
+```text
+【任务阻塞】GitOps独立worktree迁移未通过。原因=<具体服务/权限/并发验收>；已保留原workspace和回滚能力，生产业务未变化。
+```
@@ -0,0 +1,8 @@
+# Changelog
+
+## V2R1C1 - 2.1.0-rc.1
+
+- 固定发布基线为 `fb739f6e8ff9c031d319221ace68dce157694086`。
+- 收口 Hermes 生命周期、Grant 隔离、Dispatch 恢复、运行证据和回滚/前滚验证。
+- Portal Adapter 与 Spark Provisioning 仅保留在 Archive，不属于产品发布图。
+- Future Incubator 保持隔离，不属于 V2R1C1 发布输入。
@@ -1 +1 @@
-V1R4C6
+V2R1C2
@@ -5,8 +5,59 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from typing import Any

-sys.path.insert(0, str(Path(os.getenv('AIOS_GITOPS_WORKSPACE', '/data/aios-gitops/workspace')) / 'runtime' / 'agent-os'))
+try:
+    from aios_gitops_write_guard import evaluate_git_write
+except ModuleNotFoundError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from aios_gitops_write_guard import evaluate_git_write
+
+from gitea_tag_publication import (
+    GiteaTagClient,
+    GitTagBackend,
+    PublicationConflict,
+    PublicationPending,
+    PublicationManualOwnerReviewRequired,
+    PublicationReconciliationRequired,
+    PublicationRequest,
+    TagPublisher,
+    redact,
+    validate_version,
+)
 from orchestrator.action_monitor import ActionMonitor
+from silent_release_hardening import (
+    ApprovalKeyRing,
+    ApprovalRevocationStore,
+    CapabilityAuthorizationError,
+    SagaConflict,
+    SignedApprovalVerifier,
+    SignedReleasePlanApproval,
+    SilentReleaseActionService,
+)
+try:
+    from authoritative_git import (
+        AuthoritativeGitError,
+        AuthoritativeGitNotFound,
+        AuthoritativeGitOutputTooLarge,
+        authoritative_branches,
+        authoritative_diff,
+        authoritative_commit,
+        authoritative_tags,
+        repository_snapshot,
+        run_authoritative_git,
+    )
+except ModuleNotFoundError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from authoritative_git import (
+        AuthoritativeGitError,
+        AuthoritativeGitNotFound,
+        AuthoritativeGitOutputTooLarge,
+        authoritative_branches,
+        authoritative_diff,
+        authoritative_commit,
+        authoritative_tags,
+        repository_snapshot,
+        run_authoritative_git,
+    )

 ROOT = Path(os.getenv('AIOS_GITOPS_ROOT', '/data/aios-gitops'))
 WS = Path(os.getenv('AIOS_GITOPS_WORKSPACE', str(ROOT / 'workspace')))
@@ -16,6 +67,19 @@ HOST = os.getenv('AIOS_GITOPS_HOST', '127.0.0.1')
 PORT = int(os.getenv('AIOS_GITOPS_PORT', '18890'))
 OPENAPI = WS / 'docs' / 'gitops' / 'openapi-chatgpt-actions.yaml'
 BARE_REPO = Path(os.getenv('AIOS_GITOPS_BARE_REPO', str(ROOT / 'runtime' / 'gitea-bin' / 'data' / 'repositories' / 'aios' / 'aios.git')))
+AUTHORITATIVE_GIT_DIR = Path(os.getenv('AIOS_GITOPS_AUTHORITATIVE_GIT_DIR')) if os.getenv('AIOS_GITOPS_AUTHORITATIVE_GIT_DIR') else None
+REPOSITORY_IDENTITY = os.getenv('AIOS_GITOPS_REPOSITORY_IDENTITY', '')
+SILENT_RELEASE_STATE_ROOT = Path(os.getenv(
+    'AIOS_SILENT_RELEASE_STATE_ROOT',
+    '/var/lib/aios-gitops/silent-release',
+))
+SILENT_RELEASE_EXECUTION_ENABLED = str(os.getenv(
+    'AIOS_SILENT_RELEASE_EXECUTION_ENABLED', 'false'
+)).lower() in {'1', 'true', 'yes', 'on'}
+SILENT_RELEASE_PUBLIC_KEYS = Path(os.getenv(
+    'AIOS_SILENT_RELEASE_PUBLIC_KEYS',
+    '/etc/aios-gitops/silent-release-owner-public-keys.json',
+))
 monitor = ActionMonitor()

 BASE_MODELS = [
@@ -24,7 +88,43 @@ BASE_MODELS = [
  {'id':'base.gpt-5.5','provider':'openai','model':'gpt-5.5','display_name':'GPT-5.5','scope':'global'},
 ]
 SECRET_RE = re.compile(r'(?i)(api[_-]?key|secret[_-]?access[_-]?key|secret|password|token)\s*[:=]\s*["\']?([A-Za-z0-9_./+=:-]{16,})')
-SECRET_VAL_RE = re.compile(r'(sk-[A-Za-z0-9_-]{20,}|HPUA[A-Z0-9]{10,}|SDC[A-Za-z0-9]{20,})')
+SECRET_VAL_RE = re.compile(
+    r'(?<![A-Za-z0-9_])'
+    r'(sk-[A-Za-z0-9_-]{20,}|HPUA[A-Z0-9]{10,}|SDC[A-Za-z0-9]{20,})'
+)
+
+READ_ONLY_GET_PATHS = frozenset({
+    '/', '/health', '/api/health', '/api/openapi.yaml',
+    '/api/openapi-chatgpt-actions.yaml', '/api/schema', '/api', '/api/status',
+    '/api/base', '/api/baseline', '/base', '/api/ver', '/api/versions', '/ver',
+    '/api/diff', '/diff', '/api/patch', '/api/patches', '/api/branches', '/patch',
+    '/api/model', '/model', '/api/run', '/api/runtime-status', '/run',
+    '/api/action-monitor', '/action-monitor', '/admin/ai-evolution',
+    '/admin/ai-evolution/api/data',
+    '/api/release-consistency', '/api/tag-publication-status',
+    '/api/release-acceptance',
+    '/getReleaseCandidate', '/getReleasePlan', '/getReleaseAcceptance',
+    '/getApprovalEnvelope', '/getReleaseSaga', '/getCapabilityStatus',
+    '/getRecoveryStatus',
+})
+SILENT_RELEASE_POST_PATHS = frozenset({
+    '/createReleaseCandidate',
+    '/createReleaseIntent',
+    '/submitSignedApproval',
+    '/submitOwnerApproval',
+    '/startDeployment',
+})
+
+def reject_non_read_http(handler, method: str, path: str) -> bool:
+    if method == 'GET':
+        return False
+    if path in SILENT_RELEASE_POST_PATHS:
+        return False
+    decision = evaluate_git_write(WS)
+    if decision.allowed:
+        return False
+    handler.sendj(decision.payload(), decision.status_code)
+    return True

 def now() -> str: return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())
 def uid(p='id') -> str: return f'{p}-{int(time.time()*1000)}-{uuid.uuid4().hex[:8]}'
@@ -36,6 +136,41 @@ def sh(args, check=False):
 def jload(p: Path, default):
    try: return json.loads(p.read_text(encoding='utf-8'))
    except Exception: return default
+
+def _file_sha256(path: Path) -> str:
+    digest=hashlib.sha256()
+    with path.open('rb') as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b''):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+def _build_silent_release_service() -> SilentReleaseActionService:
+    verifier=None
+    if SILENT_RELEASE_PUBLIC_KEYS.is_file():
+        verifier=SignedApprovalVerifier(
+            ApprovalKeyRing.from_file(SILENT_RELEASE_PUBLIC_KEYS),
+            ApprovalRevocationStore(
+                SILENT_RELEASE_STATE_ROOT / 'revocations'
+            ),
+        )
+    policy_path=WS / 'config' / 'gitops' / 'silent-release-policy.json'
+    policy_sha=_file_sha256(policy_path) if policy_path.is_file() else ''
+    return SilentReleaseActionService(
+        SILENT_RELEASE_STATE_ROOT,
+        execution_enabled=SILENT_RELEASE_EXECUTION_ENABLED,
+        approval_verifier=verifier,
+        expected_repository=REPOSITORY_IDENTITY,
+        policy_sha256=policy_sha,
+    )
+
+# Construct once during service startup. If production execution is enabled
+# without every trusted builder/orchestrator dependency, construction fails
+# closed before the HTTP server accepts traffic.
+_SILENT_RELEASE_SERVICE = _build_silent_release_service()
+
+
+def silent_release_service() -> SilentReleaseActionService:
+    return _SILENT_RELEASE_SERVICE
 def relpath(path: str) -> str:
    x = str(path or '').replace('\\','/').strip()
    if not x or x.startswith('/') or '..' in Path(x).parts or Path(x).parts[0] == '.git': raise ValueError('invalid path')
@@ -109,9 +244,13 @@ def ensure_git():
    if not sh(['config','user.name'])['stdout']: sh(['config','user.name','chatgpt-gitops-bot'], True)
 def checkout(branch, base='main', create=False):
    ensure_git(); b=branch_name(branch)
-    if create or sh(['rev-parse','--verify',b])['code'] != 0:
-        sh(['checkout',base], True); sh(['checkout','-B',b], True)
-    else: sh(['checkout',b], True)
+    exists = sh(['rev-parse','--verify',f'refs/heads/{b}'])['code'] == 0
+    if exists:
+        sh(['checkout',b], True)
+    elif create:
+        sh(['checkout',base], True); sh(['checkout','-b',b], True)
+    else:
+        raise ValueError(f'branch does not exist: {b}')
    return b
 def write_file(path, content):
    if content_has_secret(content): raise ValueError('secret_rejected: use secret_ref; plaintext API keys must not enter Git')
@@ -121,6 +260,19 @@ def sync_branch(branch: str) -> dict:
    if not branch or branch in ('main','master') or branch.startswith('main/') or branch.startswith('master/'):
        return {'status':'skipped','reason':'protected_branch','branch':branch}
    if BARE_REPO.exists():
+        common = sh(['rev-parse', '--path-format=absolute', '--git-common-dir'], True)['stdout']
+        if Path(common).resolve() == BARE_REPO.resolve():
+            head = sh(['rev-parse', 'HEAD'], True)['stdout']
+            stored = subprocess.run(
+                ['git', '--git-dir', str(BARE_REPO), 'rev-parse', f'refs/heads/{branch}'],
+                text=True, capture_output=True,
+            )
+            if stored.returncode != 0 or stored.stdout.strip() != head:
+                raise RuntimeError(f'linked-worktree branch verification failed for {branch}')
+            return {
+                'status':'verified', 'target':'authoritative-bare',
+                'branch':branch, 'oid':head,
+            }
        ref=f'refs/heads/{branch}:refs/heads/{branch}'
        p=subprocess.run(['git','--git-dir',str(BARE_REPO),'fetch',str(WS),ref], text=True, capture_output=True)
        if p.returncode != 0: raise RuntimeError(p.stderr or p.stdout or f'git sync failed for {branch}')
@@ -130,15 +282,68 @@ def sync_branch(branch: str) -> dict:
    return {'status':'synced','target':'origin','branch':branch,'stdout':p.stdout.strip(),'stderr':p.stderr.strip()}

 def sync_tag(tag: str) -> dict:
-    if not tag: return {'status':'skipped','reason':'empty_tag'}
-    if BARE_REPO.exists():
-        ref=f'refs/tags/{tag}:refs/tags/{tag}'
-        p=subprocess.run(['git','--git-dir',str(BARE_REPO),'fetch',str(WS),ref], text=True, capture_output=True)
-        if p.returncode != 0: raise RuntimeError(p.stderr or p.stdout or f'git tag sync failed for {tag}')
-        return {'status':'synced','target':'bare','tag':tag,'stdout':p.stdout.strip(),'stderr':p.stderr.strip()}
-    p=subprocess.run(['git','push','origin',tag], cwd=str(WS), text=True, capture_output=True)
-    if p.returncode != 0: raise RuntimeError(p.stderr or p.stdout or f'git tag push failed for {tag}')
-    return {'status':'synced','target':'origin','tag':tag,'stdout':p.stdout.strip(),'stderr':p.stderr.strip()}
+    raise RuntimeError(
+        'unsafe sync_tag disabled: use TagPublisher with expected tag_oid, '
+        'target_oid, Gitea remote verification, and authenticated API verification'
+    )
+
+def resolve_commit_oid(value: str | None, field: str = 'target_oid') -> str:
+    oid = str(value or '').strip().lower()
+    if not re.fullmatch(r'[0-9a-f]{40}', oid):
+        raise ValueError(f'{field} must be a full 40-character commit OID')
+    try:
+        return authoritative_commit(oid, git_dir=AUTHORITATIVE_GIT_DIR)
+    except (AuthoritativeGitError, ValueError) as exc:
+        raise ValueError(f'{field} does not resolve to the exact approved commit') from exc
+
+def existing_tag_target(tag: str) -> str | None:
+    if not re.fullmatch(r'V\d+R\d+C\d+(?:-[A-Za-z0-9_.-]+)?$', str(tag or '')):
+        raise ValueError('invalid release version')
+    try:
+        result = run_authoritative_git(
+            ['rev-parse', '--verify', f'refs/tags/{tag}^{{commit}}'],
+            check=False,
+            git_dir=AUTHORITATIVE_GIT_DIR,
+        )
+    except AuthoritativeGitError as exc:
+        raise RuntimeError(str(exc)) from exc
+    return result.stdout.strip() if result.returncode == 0 else None
+
+def publication_request_from_query(q: dict[str, list[str]]) -> PublicationRequest:
+    required = ('version', 'target_oid', 'evidence_closure_oid', 'approval_plan_id')
+    missing = [name for name in required if not (q.get(name) or [''])[0]]
+    if missing:
+        raise ValueError('missing release governance fields: ' + ', '.join(missing))
+    return PublicationRequest(
+        (q['version'])[0],
+        (q['target_oid'])[0].lower(),
+        (q['evidence_closure_oid'])[0].lower(),
+        (q['approval_plan_id'])[0],
+    )
+
+def required_authoritative_git_dir() -> Path:
+    snapshot = repository_snapshot(
+        git_dir=AUTHORITATIVE_GIT_DIR,
+        repository_identity=REPOSITORY_IDENTITY,
+    )
+    if not snapshot["repository_available"]:
+        raise RuntimeError(str(snapshot["query_error"] or "AUTHORITATIVE_REPOSITORY_UNAVAILABLE"))
+    return Path(str(snapshot["authoritative_git_dir"]))
+
+
+def publication_publisher() -> TagPublisher:
+    authoritative_repo = required_authoritative_git_dir()
+    return TagPublisher(
+        WS,
+        GitTagBackend(WS, authoritative_repo=authoritative_repo),
+        GiteaTagClient(
+            os.getenv('AIOS_GITOPS_GITEA_API_URL',''),
+            os.getenv('AIOS_GITOPS_GITEA_REPOSITORY',''),
+            Path(os.getenv('AIOS_GITOPS_GITEA_TOKEN_FILE','')),
+            token_line=int(os.getenv('AIOS_GITOPS_GITEA_TOKEN_LINE','1')),
+        ),
+        os.getenv('AIOS_GITOPS_GITEA_REMOTE','gitea'),
+    )

 def commit(paths, msg):
    ensure_git(); paths = [relpath(p) for p in paths] if paths else ['.']; sh(['add'] + paths, True)
@@ -158,6 +363,16 @@ def patches():
    for p in sorted((WS/'patches').glob('**/*.json')): out.append(jload(p, {'path':str(p.relative_to(WS))}))
    return out

+def runtime_release_info() -> dict[str, Any]:
+    for candidate in (WS / 'manifest.json', WS.parent / 'manifest.json'):
+        data = jload(candidate, {})
+        if data.get('target_commit'):
+            return {
+                'runtime_release_commit': data.get('target_commit'),
+                'runtime_release_path': str(WS),
+            }
+    return {'runtime_release_commit': None, 'runtime_release_path': str(WS)}
+
 class H(BaseHTTPRequestHandler):
    server_version='AIOSChatGPTGitOps/V1R1C0'
    def sendj(self, data, code=200):
@@ -179,43 +394,236 @@ class H(BaseHTTPRequestHandler):
        if '*' not in a['scopes'] and scope not in a['scopes']: self.sendj({'error':'forbidden','required_scope':scope,'account':a['account']},403); return None
        return a
    def do_GET(self):
-        u=urllib.parse.urlparse(self.path); path=u.path.rstrip('/') if u.path != '/' else u.path; q=urllib.parse.parse_qs(u.query)
+        u=urllib.parse.urlparse(self.path); path=u.path.rstrip('/') if u.path != '/' else u.path
+        if path not in READ_ONLY_GET_PATHS: return self.sendj({'error':'not_found','path':path},404)
+        q=urllib.parse.parse_qs(u.query)
        try:
            if path in ('/health','/api/health'): return self.sendj({'status':'ok','service':'chatgpt-gitops-adapter','workspace':str(WS)})
            if path in ('/api/openapi.yaml','/api/openapi-chatgpt-actions.yaml','/api/schema'):
                return self.sendt(OPENAPI.read_text(encoding='utf-8'), 'application/yaml; charset=utf-8') if OPENAPI.exists() else self.sendj({'error':'schema_missing'},404)
            if path in ('/api','/api/status'): return self.sendj(api_spec())
            if path in ('/api/base','/api/baseline','/base'):
-                data=jload(WS/'baseline'/'current.json', {}); data.setdefault('git', sh(['rev-parse','--short','HEAD'])['stdout']); return self.sendj(data)
+                data=jload(WS/'baseline'/'current.json', {})
+                data.setdefault('authoritative_repository', repository_snapshot(
+                    git_dir=AUTHORITATIVE_GIT_DIR,
+                    repository_identity=REPOSITORY_IDENTITY,
+                ))
+                return self.sendj(data)
            if path in ('/api/ver','/api/versions','/ver'):
-                return self.sendj({'tags':sh(['tag','--list','V*'])['stdout'].splitlines(),'versions_dir':[p.name for p in (WS/'versions').glob('*')],'head':sh(['rev-parse','--short','HEAD'])['stdout']})
+                snapshot = repository_snapshot(
+                    git_dir=AUTHORITATIVE_GIT_DIR,
+                    repository_identity=REPOSITORY_IDENTITY,
+                )
+                if not snapshot['repository_available']:
+                    return self.sendj({
+                        'repository_available': False,
+                        'query_error': snapshot['query_error'],
+                        'registry_versions': [p.name for p in (WS/'versions').glob('*')],
+                        'local_authoritative_tags': [],
+                    }, 503)
+                try:
+                    tags = authoritative_tags(git_dir=AUTHORITATIVE_GIT_DIR)
+                except AuthoritativeGitError as exc:
+                    return self.sendj({
+                        'repository_available': False,
+                        'query_error': str(exc),
+                        'registry_versions': [p.name for p in (WS/'versions').glob('*')],
+                        'local_authoritative_tags': [],
+                    }, 503)
+                registry = [p.name for p in (WS/'versions').glob('*')]
+                return self.sendj({
+                    'registry_versions': registry,
+                    'local_authoritative_tags': tags,
+                    'repository_available': True,
+                    'query_error': None,
+                    'tags': [item['name'] for item in tags],
+                    'versions_dir': registry,
+                    'head': snapshot['authoritative_head_oid'],
+                    'authoritative_head_oid': snapshot['authoritative_head_oid'],
+                })
            if path in ('/api/diff','/diff'):
-                frm=(q.get('from') or ['HEAD~1'])[0]; to=(q.get('to') or ['HEAD'])[0]; return self.sendj({'from':frm,'to':to,'diff':sh(['diff',frm,to])})
-            if path in ('/api/patch','/api/patches','/api/branches','/patch'): return self.sendj({'patches':patches(),'branches':sh(['branch','--format','%(refname:short)'])['stdout'].splitlines()})
+                frm=(q.get('from') or [''])[0]
+                to=(q.get('to') or [''])[0]
+                try:
+                    diff=authoritative_diff(frm, to, git_dir=required_authoritative_git_dir())
+                except ValueError as exc:
+                    return self.sendj({'error':redact(exc)},400)
+                except AuthoritativeGitNotFound as exc:
+                    return self.sendj({'error':redact(exc)},404)
+                except AuthoritativeGitOutputTooLarge as exc:
+                    return self.sendj({'error':redact(exc)},413)
+                except (AuthoritativeGitError, RuntimeError) as exc:
+                    return self.sendj({'error':redact(exc)},503)
+                return self.sendj({'from':frm,'to':to,'diff':diff})
+            if path in ('/api/patch','/api/patches','/api/branches','/patch'):
+                snapshot = repository_snapshot(
+                    git_dir=AUTHORITATIVE_GIT_DIR,
+                    repository_identity=REPOSITORY_IDENTITY,
+                )
+                if not snapshot['repository_available']:
+                    return self.sendj({
+                        'repository_available': False,
+                        'query_error': snapshot['query_error'],
+                        'metadata_patches': patches(),
+                        'authoritative_branches': [],
+                    }, 503)
+                try:
+                    branches = authoritative_branches(git_dir=AUTHORITATIVE_GIT_DIR)
+                except AuthoritativeGitError as exc:
+                    return self.sendj({
+                        'repository_available': False,
+                        'query_error': str(exc),
+                        'metadata_patches': patches(),
+                        'authoritative_branches': [],
+                    }, 503)
+                metadata = patches()
+                branch_names = {item['name'] for item in branches}
+                metadata_names = {
+                    item.get('branch') for item in metadata
+                    if isinstance(item, dict) and item.get('branch')
+                }
+                orphan = [
+                    item for item in metadata
+                    if item.get('branch') and item.get('branch') not in branch_names
+                ]
+                missing = [
+                    item for item in branches
+                    if item['name'] not in metadata_names
+                ]
+                return self.sendj({
+                    'metadata_patches': metadata,
+                    'authoritative_branches': branches,
+                    'orphan_metadata': orphan,
+                    'branches_without_metadata': missing,
+                    'repository_available': True,
+                    'query_error': None,
+                    'patches': metadata,
+                    'branches': [item['name'] for item in branches],
+                })
            if path in ('/api/model','/model'): return self.sendj({'base':BASE_MODELS,'custom':model_docs(),'priority':[jload(p,{}) for p in sorted((WS/'config'/'model_priority').glob('*.json'))]})
            if path in ('/api/run','/api/runtime-status','/run'):
                svc=subprocess.run(['systemctl','is-active','aios-gitops-model-api'], text=True, capture_output=True)
-                return self.sendj({'service':'aios-gitops-model-api','status':svc.stdout.strip() or svc.stderr.strip(),'workspace_branch':sh(['rev-parse','--abbrev-ref','HEAD'])['stdout']})
+                snapshot = repository_snapshot(
+                    git_dir=AUTHORITATIVE_GIT_DIR,
+                    repository_identity=REPOSITORY_IDENTITY,
+                )
+                workspace_branch = None
+                if (WS / '.git').exists():
+                    result = sh(['rev-parse','--abbrev-ref','HEAD'])
+                    workspace_branch = result['stdout'] or None
+                payload = {
+                    'service':'aios-gitops-model-api',
+                    'status':svc.stdout.strip() or svc.stderr.strip(),
+                    'workspace_branch':workspace_branch,
+                    **runtime_release_info(),
+                    **snapshot,
+                    'writes_enabled': str(os.getenv('AIOS_GITOPS_WRITES_ENABLED','false')).lower() in {'1','true','yes','on'},
+                }
+                return self.sendj(payload, 200 if snapshot['repository_available'] else 503)
            if path in ('/api/action-monitor','/action-monitor'):
                latest=monitor.latest()
                ldict={'event_id':latest.event_id,'action':latest.action,'error':latest.error,'context':latest.context,'created_at':latest.created_at} if latest else None
                return self.sendj({'events':[{"event_id":e.event_id,"action":e.action,"error":e.error,"context":e.context,"created_at":e.created_at} for e in monitor.list_events()],'latest':ldict})
+            if path == '/api/tag-publication-status':
+                version=(q.get('version') or [''])[0]
+                try:
+                    version=validate_version(version)
+                    status=publication_publisher().get_tag_publication_status(version)
+                except ValueError:
+                    return self.sendj({'error':'invalid release version'},400)
+                return self.sendj(status)
+            if path == '/api/release-consistency':
+                request=publication_request_from_query(q)
+                return self.sendj(publication_publisher().get_release_consistency(request))
+            if path == '/api/release-acceptance':
+                request=publication_request_from_query(q)
+                return self.sendj(publication_publisher().run_release_acceptance(request))
+            if path in (
+                '/getReleaseCandidate',
+                '/getReleasePlan',
+                '/getReleaseAcceptance',
+                '/getApprovalEnvelope',
+                '/getReleaseSaga',
+                '/getCapabilityStatus',
+            ):
+                candidate_id=(q.get('candidate_id') or [''])[0]
+                if not candidate_id:
+                    return self.sendj({'error':'candidate_id is required'},400)
+                service=silent_release_service()
+                if path == '/getReleaseCandidate':
+                    return self.sendj(
+                        service.get_release_candidate(candidate_id)
+                    )
+                if path == '/getApprovalEnvelope':
+                    return self.sendj(
+                        service.get_approval_envelope(candidate_id)
+                    )
+                if path == '/getReleasePlan':
+                    return self.sendj(service.get_release_plan(candidate_id))
+                if path == '/getReleaseAcceptance':
+                    return self.sendj(service.get_acceptance(candidate_id))
+                if path == '/getCapabilityStatus':
+                    return self.sendj(
+                        service.get_capability_status(candidate_id)
+                    )
+                return self.sendj(service.get_release_saga(candidate_id))
+            if path == '/getRecoveryStatus':
+                return self.sendj(
+                    silent_release_service().get_recovery_status()
+                )
                        # Admin AI Evolution Dashboard
            if path in ('/admin/ai-evolution','/admin/ai-evolution/'):
                return self.ai_evolution_page()
            if path in ('/admin/ai-evolution/api/data'):
                return self.ai_evolution_data()
            return self.sendj({'error':'not_found','path':path},404)
+        except FileNotFoundError:
+            return self.sendj({'error':'release candidate not found'},404)
+        except ValueError as e:
+            error=redact(e)
+            monitor.record_failure('do_GET', error, {'path':path})
+            return self.sendj({'error':error},400)
        except Exception as e:
-            monitor.record_failure('do_GET', str(e), {'path':path})
-            return self.sendj({'error':str(e)},500)
+            error=redact(e)
+            monitor.record_failure('do_GET', error, {'path':path})
+            return self.sendj({'error':error},500)
    def do_PUT(self):
-        path=urllib.parse.urlparse(self.path).path.rstrip('/'); data=self.body()
+        path=urllib.parse.urlparse(self.path).path.rstrip('/')
+        if reject_non_read_http(self, 'PUT', path): return
+        data=self.body()
        if path == '/api/model-priority': return self.model_priority(data)
        return self.sendj({'error':'not_found','path':path},404)
    def do_POST(self):
-        path=urllib.parse.urlparse(self.path).path.rstrip('/'); data=self.body()
+        path=urllib.parse.urlparse(self.path).path.rstrip('/')
+        if reject_non_read_http(self, 'POST', path): return
+        data=self.body()
        try:
+            if path == '/createReleaseCandidate':
+                a=self.need('release:candidate')
+                if not a: return
+                return self.sendj(
+                    silent_release_service().create_release_candidate(data)
+                )
+            if path == '/createReleaseIntent':
+                a=self.need('release:candidate')
+                if not a: return
+                return self.sendj(
+                    silent_release_service().create_release_intent(data)
+                )
+            if path in ('/submitOwnerApproval','/submitSignedApproval'):
+                a=self.need('release:approve')
+                if not a: return
+                return self.sendj(
+                    silent_release_service().submit_owner_approval(data)
+                )
+            if path == '/startDeployment':
+                a=self.need('release:deploy')
+                if not a: return
+                return self.sendj(
+                    silent_release_service().start_deployment(
+                        str(data.get('candidate_id') or '')
+                    )
+                )
            if path in ('/api/branch','/api/create-branch'): return self.branch(data)
            if path in ('/api/file','/api/commit-file'): return self.file(data)
            if path == '/api/commit': return self.commit(data)
@@ -226,9 +634,30 @@ class H(BaseHTTPRequestHandler):
            if path == '/api/model-priority': return self.model_priority(data)
            if path == '/api/nl': return self.nl(data)
            return self.sendj({'error':'not_found','path':path},404)
+        except (ValueError, FileNotFoundError) as e:
+            error=redact(e)
+            monitor.record_failure('do_POST', error, {'path':path})
+            return self.sendj({'error':error},400)
+        except CapabilityAuthorizationError as e:
+            error=redact(e)
+            monitor.record_failure('do_POST', error, {'path':path})
+            return self.sendj({'error':error},403)
+        except SagaConflict as e:
+            error=redact(e)
+            monitor.record_failure('do_POST', error, {'path':path})
+            return self.sendj({'error':error},409)
        except Exception as e:
-            monitor.record_failure('do_POST', str(e), {'path':path})
-            return self.sendj({'error':str(e)},500)
+            error=redact(e)
+            monitor.record_failure('do_POST', error, {'path':path})
+            return self.sendj({'error':error},500)
+    def do_PATCH(self):
+        path=urllib.parse.urlparse(self.path).path.rstrip('/')
+        if reject_non_read_http(self, 'PATCH', path): return
+        return self.sendj({'error':'not_found','path':path},404)
+    def do_DELETE(self):
+        path=urllib.parse.urlparse(self.path).path.rstrip('/')
+        if reject_non_read_http(self, 'DELETE', path): return
+        return self.sendj({'error':'not_found','path':path},404)
    def branch(self,data):
        a=self.need('branch:create');
        if not a: return
@@ -252,12 +681,41 @@ class H(BaseHTTPRequestHandler):
        if not a: return
        ver=data.get('version') or data.get('tag')
        if not re.match(r'^V\d+R\d+C\d+(-[A-Za-z0-9_.-]+)?$', ver or ''): return self.sendj({'error':'version must match VxRxCx'},400)
-        if data.get('confirm') != True:
-            self.sendj({'status':'confirm_required','operation':'tag','hint':'This operation creates a Git tag. Confirm to proceed.','x-openai-isConsequential':True}, 428)
-            return
+        if not data.get('target_oid') or not data.get('evidence_closure_oid') or not data.get('approval_plan_id'):
+            return self.sendj({
+                'error':'production_tag_evidence_required',
+                'required':['version','target_oid','evidence_closure_oid','approval_plan_id'],
+            },400)
+        try:
+            target_oid=resolve_commit_oid(data.get('target_oid'))
+            evidence_oid=resolve_commit_oid(data.get('evidence_closure_oid'), 'evidence_closure_oid')
+        except ValueError as exc:
+            return self.sendj({'error':'invalid_tag_target','detail':str(exc)},400)
        if a['role'] != 'owner' or not data.get('execute'):
-            b=checkout(data.get('branch') or f'request/tag-{safe(ver)}', 'main', True); req={'version':ver,'requested_by':a['account'],'approval_required':True,'created_at':now()}; r=write_json(f'baseline/tag_requests/{safe(ver)}.json', req); c=commit([r], f'chore(chatgpt): request tag {ver}'); return self.sendj({'status':'approval_required','branch':b,'commit':c})
-        out=sh(['tag','-a',ver,'-m',data.get('message') or f'release {ver}'], True); self.sendj({'status':'tagged','version':ver,'git':out,'sync':sync_tag(ver)})
+            b=checkout(data.get('branch') or f'request/tag-{safe(ver)}', 'main', True); req={'version':ver,'target_oid':target_oid,'evidence_closure_oid':evidence_oid,'approval_plan_id':data.get('approval_plan_id'),'requested_by':a['account'],'approval_required':True,'created_at':now()}; r=write_json(f'baseline/tag_requests/{safe(ver)}.json', req); c=commit([r], f'chore(chatgpt): request tag {ver}'); return self.sendj({'status':'approval_required','branch':b,'request':req,'commit':c})
+        request=PublicationRequest(ver,target_oid,evidence_oid,str(data.get('approval_plan_id')))
+        main_before=sh(['rev-parse','refs/heads/main'], True)['stdout']
+        publisher=publication_publisher()
+        try:
+            publication=publisher.publish(request)
+        except PublicationManualOwnerReviewRequired as exc:
+            audit(a['account'],'tag_manual_owner_review_required',ver,{'target_oid':target_oid,'approval_plan_id':data.get('approval_plan_id'),'error':redact(exc)})
+            return self.sendj({'status':'MANUAL_OWNER_REVIEW_REQUIRED','error':redact(exc),'main_changed':False,'force_push':False},409)
+        except PublicationConflict as exc:
+            audit(a['account'],'tag_conflict',ver,{'target_oid':target_oid,'approval_plan_id':data.get('approval_plan_id'),'error':str(exc)})
+            return self.sendj({'status':'RECONCILIATION_REQUIRED','error':str(exc),'main_changed':False,'force_push':False},409)
+        except PublicationPending as exc:
+            audit(a['account'],'tag_pending',ver,{'target_oid':target_oid,'approval_plan_id':data.get('approval_plan_id'),'error':str(exc)})
+            return self.sendj({'status':'REMOTE_PUSH_PENDING','error':str(exc),'main_changed':False,'force_push':False},503)
+        except PublicationReconciliationRequired as exc:
+            audit(a['account'],'tag_reconciliation_required',ver,{'target_oid':target_oid,'approval_plan_id':data.get('approval_plan_id'),'error':str(exc)})
+            return self.sendj({'status':'RECONCILIATION_REQUIRED','error':str(exc),'main_changed':False,'force_push':False},502)
+        main_after=sh(['rev-parse','refs/heads/main'], True)['stdout']
+        if main_after != main_before:
+            raise RuntimeError('main changed during tag operation')
+        result={'status':publication['state'],'version':ver,'tag_name':ver,'tag_oid':publication['tag_oid'],'target_oid':target_oid,'expected_target_oid':target_oid,'evidence_closure_oid':evidence_oid,'approval_plan_id':data.get('approval_plan_id'),'workspace_head':sh(['rev-parse','HEAD'],True)['stdout'],'main_oid_before':main_before,'main_oid_after':main_after,'main_changed':False,'force_push':False,'publication':publication}
+        audit(a['account'],'tag',ver,result)
+        self.sendj(result)
    def rollback(self,data):
        a=self.need('rollback:request');
        if not a: return
@@ -352,7 +810,10 @@ return{vs,cmds,ar,cmd,cdet,tot,sok,sfail,runs,baseline,refreshMsg,loadCmd,selVer
        cmd_filter=(params.get('command') or [None])[0]
        bl=jload(WS/'baseline'/'current.json',{})
        current_ver=bl.get('current_baseline','V1R3C1')
-        tags=sh(['tag','--list','V*'])['stdout'].splitlines() if WS.exists() else []
+        try:
+            tags=[item['name'] for item in authoritative_tags(git_dir=required_authoritative_git_dir()) if str(item['name']).startswith('V')]
+        except (AuthoritativeGitError, RuntimeError) as exc:
+            return self.sendj({'error':redact(exc),'repository_available':False},503)
        versions=[]
        if (WS/'baseline'/'promotions').exists():
            for p in sorted((WS/'baseline'/'promotions').glob('*.json')):
@@ -390,9 +851,9 @@ return{vs,cmds,ar,cmd,cdet,tot,sok,sfail,runs,baseline,refreshMsg,loadCmd,selVer


 def api_spec():
-    return {'version':'V1R1C0-chatgpt-actions','openapi':'/api/openapi.yaml','read':['GET /api/base','GET /api/ver','GET /api/diff','GET /api/patch','GET /api/model','GET /api/run','GET /admin/ai-evolution'],'write':['POST /api/branch','POST /api/file','POST /api/commit','POST /api/patch','POST /api/tag','POST /api/rollback','POST /api/model','PUT /api/model-priority','POST /api/nl'],'policy':{'bearer_required_for_write':True,'direct_main_push':False,'delete_tag':False,'owner_approval_required_for_v_level':True,'api_keys_in_git':False,'git_secret_field':'secret_ref','online_git_sync':True}}
+    return {'version':'V1R1C0-chatgpt-actions','openapi':'/api/openapi.yaml','read':['GET /api/base','GET /api/ver','GET /api/diff','GET /api/patch','GET /api/model','GET /api/run','GET /getReleaseCandidate','GET /getApprovalEnvelope','GET /getReleaseSaga','GET /admin/ai-evolution'],'write':['POST /api/branch','POST /api/file','POST /api/commit','POST /api/patch','POST /api/tag','POST /api/rollback','POST /api/model','PUT /api/model-priority','POST /api/nl','POST /createReleaseCandidate','POST /submitOwnerApproval','POST /startDeployment'],'policy':{'bearer_required_for_write':True,'direct_main_push':False,'delete_tag':False,'owner_approval_required_for_v_level':True,'api_keys_in_git':False,'git_secret_field':'secret_ref','online_git_sync':True,'silent_release_execution_enabled':SILENT_RELEASE_EXECUTION_ENABLED,'silent_release_shadow_default':True}}

 def main():
    print(f'AIOS ChatGPT GitOps adapter listening on {HOST}:{PORT}')
    ThreadingHTTPServer((HOST,PORT), H).serve_forever()
-if __name__ == '__main__': main()
+if __name__ == '__main__': main()
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Fail-closed policy for in-process Git mutation handlers."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+_TRUE = frozenset({"1", "true", "yes", "on"})
+
+
+@dataclass(frozen=True)
+class GitWriteDecision:
+    allowed: bool
+    status_code: int
+    error: str
+    reason: str
+    workspace: str
+
+    def payload(self) -> dict[str, str]:
+        return {
+            "status": "allowed" if self.allowed else "blocked",
+            "error": self.error,
+            "reason": self.reason,
+            "workspace": self.workspace,
+        }
+
+
+def _real(path: Path) -> Path:
+    return Path(os.path.realpath(os.path.abspath(str(path))))
+
+
+def evaluate_git_write(workspace: Path | str, env: Mapping[str, str] | None = None) -> GitWriteDecision:
+    values = os.environ if env is None else env
+    lexical = Path(os.path.abspath(str(workspace)))
+    canonical = _real(lexical)
+    shown = str(lexical)
+    if str(values.get("AIOS_GITOPS_WRITES_ENABLED", "false")).strip().lower() not in _TRUE:
+        return GitWriteDecision(False, 423, "gitops_writes_disabled", "AIOS_GITOPS_WRITES_ENABLED is false", shown)
+    if lexical != canonical:
+        return GitWriteDecision(False, 409, "workspace_symlink_forbidden", "workspace must be a canonical non-symlink path", shown)
+    controller = _real(Path(values.get("AIOS_GITOPS_CONTROLLER_PATH", "/data/aios-gitops/worktrees/controller")))
+    role = str(values.get("AIOS_GITOPS_WORKSPACE_ROLE", "")).strip().lower()
+    if canonical == controller or role == "runtime-anchor":
+        return GitWriteDecision(False, 423, "runtime_anchor_read_only", "controller/runtime-anchor is read-only", str(canonical))
+    writer_root = _real(Path(values.get("AIOS_GITOPS_APPROVED_WRITER_ROOT", "/data/aios-gitops/worktrees")))
+    try:
+        canonical.relative_to(writer_root)
+    except ValueError:
+        return GitWriteDecision(False, 409, "workspace_not_approved_writer", "workspace is outside the approved writer root", str(canonical))
+    return GitWriteDecision(True, 200, "", "approved isolated writer", str(canonical))
@@ -6,6 +6,7 @@ from .adapter import (
    HermesNotFound,
    HermesRuntimeError,
    InMemoryHermesStore,
+    SQLiteHermesStore,
 )
 from .contract import HermesHealth, HermesJob, HermesJobState, HermesResult
 from .worker import HermesWorker, WorkerRunResult
@@ -21,5 +22,6 @@ __all__ = [
    "HermesRuntimeError",
    "HermesWorker",
    "InMemoryHermesStore",
+    "SQLiteHermesStore",
    "WorkerRunResult",
 ]
@@ -3,9 +3,11 @@ from __future__ import annotations

 import hashlib
 import json
+import sqlite3
 import threading
-from dataclasses import replace
+from dataclasses import asdict, replace
 from datetime import datetime, timedelta, timezone
+from pathlib import Path
 from typing import Iterable, Mapping

 from .contract import (
@@ -41,6 +43,118 @@ class InMemoryHermesStore:
        self.idempotency: dict[tuple[str, str], tuple[str, str]] = {}
        self.worker_heartbeats: dict[str, tuple[str, str | None]] = {}

+    def persist_locked(self) -> None:
+        """Persist a mutation while ``lock`` is held; memory stores are a no-op."""
+
+
+class SQLiteHermesStore(InMemoryHermesStore):
+    """Durable snapshot for the existing Hermes queue state machine.
+
+    The adapter remains the sole owner of transitions and lease rules. This
+    store only makes its jobs, results, idempotency keys and worker heartbeats
+    survive a process restart.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        super().__init__()
+        with self._connect() as connection:
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS hermes_state (
+                    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+                    payload TEXT NOT NULL
+                )
+                """
+            )
+        self._load()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(str(self.path), timeout=30)
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA synchronous=FULL")
+        return connection
+
+    @staticmethod
+    def _record(value: HermesJob | HermesResult) -> dict[str, object]:
+        record = asdict(value)
+        record["state"] = value.state.value
+        return record
+
+    def _load(self) -> None:
+        with self.lock, self._connect() as connection:
+            row = connection.execute(
+                "SELECT payload FROM hermes_state WHERE singleton = 1"
+            ).fetchone()
+            if row is None:
+                return
+            payload = json.loads(str(row[0]))
+            self.jobs = {
+                str(item["job_id"]): HermesJob(**item)
+                for item in payload.get("jobs", [])
+            }
+            self.results = {
+                str(item["job_id"]): HermesResult(**item)
+                for item in payload.get("results", [])
+            }
+            self.idempotency = {
+                (str(item["tenant_id"]), str(item["idempotency_key"])): (
+                    str(item["job_id"]),
+                    str(item["digest"]),
+                )
+                for item in payload.get("idempotency", [])
+            }
+            self.worker_heartbeats = {
+                str(item["worker_id"]): (
+                    str(item["heartbeat_at"]),
+                    str(item["job_id"]) if item.get("job_id") is not None else None,
+                )
+                for item in payload.get("worker_heartbeats", [])
+            }
+
+    def persist_locked(self) -> None:
+        payload = {
+            "version": 1,
+            "jobs": [self._record(item) for item in self.jobs.values()],
+            "results": [self._record(item) for item in self.results.values()],
+            "idempotency": [
+                {
+                    "tenant_id": tenant_id,
+                    "idempotency_key": idempotency_key,
+                    "job_id": job_id,
+                    "digest": digest,
+                }
+                for (tenant_id, idempotency_key), (job_id, digest)
+                in self.idempotency.items()
+            ],
+            "worker_heartbeats": [
+                {
+                    "worker_id": worker_id,
+                    "heartbeat_at": heartbeat_at,
+                    "job_id": job_id,
+                }
+                for worker_id, (heartbeat_at, job_id)
+                in self.worker_heartbeats.items()
+            ],
+        }
+        encoded = json.dumps(
+            payload,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            connection.execute(
+                """
+                INSERT INTO hermes_state(singleton, payload) VALUES(1, ?)
+                ON CONFLICT(singleton) DO UPDATE SET payload=excluded.payload
+                """,
+                (encoded,),
+            )
+            connection.commit()
+

 class HermesAdapter:
    """Queue and reconcile Hermes jobs without owning AIOS policy."""
@@ -118,6 +232,7 @@ class HermesAdapter:
                return self.store.jobs[prior_id]
            self.store.jobs[job.job_id] = job
            self.store.idempotency[idem_ref] = (job.job_id, digest)
+            self.store.persist_locked()
            return job

    def get(self, job_id: str, *, tenant_id: str) -> HermesJob:
@@ -138,7 +253,8 @@ class HermesAdapter:
    ) -> list[HermesJob]:
        state_filter = {HermesJobState(item) for item in states} if states else None
        with self.store.lock:
-            self._requeue_expired_locked()
+            if self._requeue_expired_locked():
+                self.store.persist_locked()
            jobs = [
                job
                for job in self.store.jobs.values()
@@ -157,6 +273,7 @@ class HermesAdapter:
        profile_id: str,
        worker_id: str,
        lease_seconds: int | None = None,
+        job_id: str | None = None,
    ) -> HermesJob | None:
        worker_id = str(worker_id or "").strip()
        if not worker_id:
@@ -172,10 +289,12 @@ class HermesAdapter:
                if job.tenant_id == tenant_id
                and job.cell_id == cell_id
                and job.profile_id == profile_id
+                and (job_id is None or job.job_id == job_id)
                and job.state == HermesJobState.QUEUED
            ]
            self.store.worker_heartbeats[worker_id] = (utc_now(), None)
            if not candidates:
+                self.store.persist_locked()
                return None
            current = sorted(
                candidates,
@@ -190,6 +309,7 @@ class HermesAdapter:
                ),
            )
            self.store.worker_heartbeats[worker_id] = (utc_now(), claimed.job_id)
+            self.store.persist_locked()
            return claimed

    def start(
@@ -201,9 +321,12 @@ class HermesAdapter:
        expected_revision: int | None = None,
    ) -> HermesJob:
        with self.store.lock:
+            self._requeue_expired_locked()
            current = self._owned_job_locked(job_id, tenant_id, worker_id)
            self._assert_revision(current, expected_revision)
-            return self._transition_locked(current, HermesJobState.RUNNING)
+            updated = self._transition_locked(current, HermesJobState.RUNNING)
+            self.store.persist_locked()
+            return updated

    def heartbeat(
        self,
@@ -214,7 +337,10 @@ class HermesAdapter:
        lease_seconds: int | None = None,
    ) -> HermesJob:
        duration = int(lease_seconds or self.default_lease_seconds)
+        if duration < 5:
+            raise ValueError("lease_seconds must be >= 5")
        with self.store.lock:
+            self._requeue_expired_locked()
            current = self._owned_job_locked(job_id, tenant_id, worker_id)
            if current.state not in {HermesJobState.CLAIMED, HermesJobState.RUNNING}:
                raise HermesConflict("job does not accept heartbeat")
@@ -228,6 +354,7 @@ class HermesAdapter:
            )
            self.store.jobs[job_id] = updated
            self.store.worker_heartbeats[worker_id] = (utc_now(), job_id)
+            self.store.persist_locked()
            return updated

    def complete(
@@ -283,6 +410,8 @@ class HermesAdapter:
                result = self.store.results.get(job_id)
                if result is None:
                    raise HermesConflict("terminal result missing")
+                if result.state != HermesJobState.CANCELLED:
+                    raise HermesConflict("job already has a different terminal result")
                return result
            updated = self._transition_locked(current, HermesJobState.CANCELLED)
            result = HermesResult(
@@ -296,6 +425,7 @@ class HermesAdapter:
                finished_at=utc_now(),
            )
            self.store.results[job_id] = result
+            self.store.persist_locked()
            return result

    def result(self, job_id: str, *, tenant_id: str) -> HermesResult:
@@ -309,9 +439,18 @@ class HermesAdapter:
                raise HermesConflict("job has no terminal result")
            return result

+    def requeue_expired(self) -> tuple[str, ...]:
+        """Persistently release expired leases without changing policy state."""
+        with self.store.lock:
+            changed = self._requeue_expired_locked()
+            if changed:
+                self.store.persist_locked()
+            return tuple(sorted(changed))
+
    def health(self) -> HermesHealth:
        with self.store.lock:
-            self._requeue_expired_locked()
+            if self._requeue_expired_locked():
+                self.store.persist_locked()
            active_jobs = sum(
                1 for job in self.store.jobs.values()
                if job.state in {HermesJobState.CLAIMED, HermesJobState.RUNNING}
@@ -354,7 +493,20 @@ class HermesAdapter:
        expected_revision: int | None,
    ) -> HermesResult:
        with self.store.lock:
+            self._requeue_expired_locked()
            current = self._owned_job_locked(job_id, tenant_id, worker_id)
+            if current.state in TERMINAL_STATES:
+                existing = self.store.results.get(job_id)
+                if existing is None:
+                    raise HermesConflict("terminal result missing")
+                if (
+                    existing.state == state
+                    and existing.worker_id == worker_id
+                    and existing.output == output
+                    and existing.error == error
+                ):
+                    return existing
+                raise HermesConflict("job already has a different terminal result")
            self._assert_revision(current, expected_revision)
            updated = self._transition_locked(current, state)
            result = HermesResult(
@@ -371,6 +523,7 @@ class HermesAdapter:
            )
            self.store.results[job_id] = result
            self.store.worker_heartbeats[worker_id] = (utc_now(), None)
+            self.store.persist_locked()
            return result

    def _owned_job_locked(self, job_id: str, tenant_id: str, worker_id: str) -> HermesJob:
@@ -418,8 +571,9 @@ class HermesAdapter:
        self.store.jobs[current.job_id] = updated
        return updated

-    def _requeue_expired_locked(self) -> None:
+    def _requeue_expired_locked(self) -> set[str]:
        now = datetime.now(timezone.utc)
+        changed: set[str] = set()
        for current in list(self.store.jobs.values()):
            expiry = self._parse(current.lease_expires_at)
            if (
@@ -435,3 +589,5 @@ class HermesAdapter:
                    lease_expires_at=None,
                    updated_at=utc_now(),
                )
+                changed.add(current.job_id)
+        return changed
@@ -0,0 +1,316 @@
+"""Task-scoped hardened wrapper around the existing Action API."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+import urllib.parse
+
+import aios_chatgpt_actions_api as api
+import aios_isolated_writer_policy as policy
+from isolated_writer_authz import AuthorizationError, authorize
+from isolated_writer_commit_file import AtomicCommitFile, CommitFileError, OperationLedger
+from isolated_writer_token_registry import TokenRegistry
+
+_reject = api.reject_non_read_http
+_write_file = api.write_file
+_sync_branch = api.sync_branch
+_original_do_get = api.H.do_GET
+api.OPENAPI = Path(os.getenv("AIOS_GITOPS_ISOLATED_WRITER_OPENAPI", str(api.OPENAPI)))
+
+
+def _registry() -> TokenRegistry:
+    return TokenRegistry(Path(os.environ["AIOS_GITOPS_TOKEN_REGISTRY_V2"]))
+
+
+def _atomic_writer() -> AtomicCommitFile:
+    return AtomicCommitFile(
+        workspace=api.WS,
+        bare_repo=api.BARE_REPO,
+        ledger=OperationLedger(Path(os.environ["AIOS_GITOPS_WRITER_OPERATION_LEDGER"])),
+        remote=os.getenv("AIOS_GITOPS_GITEA_PUSH_REMOTE", ""),
+        audit=policy.append_audit_record,
+    )
+
+
+def _bearer(handler) -> str:
+    value = handler.headers.get("Authorization", "")
+    return value[7:].strip() if value.startswith("Bearer ") else ""
+
+
+def _authorize(handler, *, method: str, path: str, branch=None, target_path=None):
+    grant = authorize(
+        _registry(),
+        _bearer(handler),
+        method=method,
+        path=path,
+        source_ip=str(handler.client_address[0]),
+        workspace=api.WS,
+        branch=branch,
+        target_path=target_path,
+    )
+    grant.record["_source_ip"] = str(handler.client_address[0])
+    return grant
+
+
+def _authorization_error(handler, exc: AuthorizationError):
+    return handler.sendj({"error": exc.code}, exc.status)
+
+
+def _isolated_runtime_status(handler):
+    branch = api.sh(["rev-parse", "--abbrev-ref", "HEAD"], True)["stdout"]
+    head = api.sh(["rev-parse", "HEAD"], True)["stdout"]
+    return handler.sendj({
+        "service": os.getenv(
+            "AIOS_GITOPS_SERVICE_AUDIENCE",
+            "aios-isolated-writer.service",
+        ),
+        "status": "active",
+        "runtime_role": os.getenv("AIOS_GITOPS_RUNTIME_ROLE"),
+        "workspace_role": os.getenv("AIOS_GITOPS_WORKSPACE_ROLE"),
+        "writes_enabled": os.getenv("AIOS_GITOPS_WRITES_ENABLED", "").lower()
+        in {"1", "true", "yes", "on"},
+        "allowed_branch": policy.allowed_branch(),
+        "approved_base_oid": policy.allowed_base_oid(),
+        "workspace_branch": branch,
+        "workspace_head_oid": head,
+        "repository_identity": os.getenv("AIOS_GITOPS_REPOSITORY_IDENTITY"),
+        "token_policy_version": 2,
+        "atomic_commit_file": True,
+        "path_policy_sha256": policy.configured_path_policy_sha256(),
+    })
+
+
+def _isolated_do_get(self):
+    path = urllib.parse.urlparse(self.path).path.rstrip("/") or "/"
+    if path in {"/health", "/api/health"}:
+        return self.sendj({
+            "status": "ok",
+            "service": os.getenv(
+                "AIOS_GITOPS_SERVICE_AUDIENCE",
+                "aios-isolated-writer.service",
+            ),
+        })
+    if path not in {"/api/runtime-status", "/api/baseline", "/api/patches"}:
+        return self.sendj({"error": "isolated_writer_operation_forbidden"}, 403)
+    try:
+        _authorize(self, method="GET", path=path)
+    except AuthorizationError as exc:
+        return _authorization_error(self, exc)
+    if path == "/api/runtime-status":
+        return _isolated_runtime_status(self)
+    return _original_do_get(self)
+
+
+def _read_commit_file_body(handler):
+    try:
+        length = int(handler.headers.get("Content-Length", "0"))
+    except ValueError:
+        raise CommitFileError("writer_content_length_rejected") from None
+    if length <= 0:
+        raise CommitFileError("writer_request_object_required")
+    if length > 1_100_000:
+        raise CommitFileError("writer_request_too_large", 413)
+    raw = handler.rfile.read(length)
+    try:
+        value = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise CommitFileError("writer_request_json_rejected") from None
+    if not isinstance(value, dict):
+        raise CommitFileError("writer_request_object_required")
+    return value
+
+
+def _isolated_do_post(self):
+    path = urllib.parse.urlparse(self.path).path.rstrip("/") or "/"
+    if path != "/api/commit-file":
+        return self.sendj({"error": "isolated_writer_operation_forbidden"}, 403)
+    try:
+        data = _read_commit_file_body(self)
+        branch = str(data.get("branch") or "")
+        target_path = str(data.get("path") or "")
+        grant = _authorize(
+            self,
+            method="POST",
+            path=path,
+            branch=branch,
+            target_path=target_path,
+        )
+        if api.content_has_secret(str(data.get("content") or "")):
+            raise CommitFileError("writer_secret_content_rejected", 403)
+        result = _atomic_writer().execute(grant, data)
+        return self.sendj(result)
+    except AuthorizationError as exc:
+        return _authorization_error(self, exc)
+    except CommitFileError as exc:
+        return self.sendj({"error": exc.code}, exc.status)
+    except PermissionError:
+        return self.sendj({"error": "isolated_writer_policy_rejected"}, 403)
+
+
+def reject_non_read_http(handler, method: str, path: str) -> bool:
+    if _reject(handler, method, path):
+        return True
+    try:
+        policy.validate_endpoint(method, path, api.WS, api.BARE_REPO)
+        return False
+    except PermissionError as exc:
+        handler.sendj({"error": str(exc)}, 403)
+        return True
+
+
+def checkout(branch, base="main", create=False):
+    api.ensure_git()
+    target = api.branch_name(branch)
+    policy.validate_branch_request({"branch": target, "base": base})
+    exists = api.sh(["rev-parse", "--verify", target])["code"] == 0
+    if exists:
+        if api.sh(["rev-parse", "--abbrev-ref", "HEAD"], True)["stdout"] != target:
+            api.sh(["checkout", target], True)
+    elif create:
+        api.sh(["checkout", "-b", target, base], True)
+    else:
+        raise PermissionError("isolated_writer_branch_missing")
+    policy.require_service_invariants(api.WS, api.BARE_REPO)
+    return target
+
+
+def write_file(path, content):
+    policy.validate_path(path, api.WS)
+    return _write_file(path, content)
+
+
+def sync_branch(branch: str):
+    policy.validate_sync_branch(branch)
+    local = _sync_branch(branch)
+    remote = os.getenv("AIOS_GITOPS_GITEA_PUSH_REMOTE", "").strip()
+    if remote != "gitea-http":
+        raise PermissionError("isolated_writer_gitea_remote_rejected")
+    head = api.sh(["rev-parse", "HEAD"], True)["stdout"]
+    pushed = subprocess.run(
+        ["git", "push", "--porcelain", remote, f"HEAD:refs/heads/{branch}"],
+        cwd=api.WS,
+        text=True,
+        capture_output=True,
+    )
+    if pushed.returncode != 0:
+        raise RuntimeError("isolated_writer_gitea_push_failed")
+    verified = subprocess.run(
+        ["git", "ls-remote", "--heads", remote, f"refs/heads/{branch}"],
+        cwd=api.WS,
+        text=True,
+        capture_output=True,
+    )
+    if verified.returncode != 0:
+        raise RuntimeError("isolated_writer_gitea_verification_failed")
+    fields = verified.stdout.strip().split()
+    if len(fields) != 2 or fields[0] != head or fields[1] != f"refs/heads/{branch}":
+        raise RuntimeError("isolated_writer_gitea_oid_mismatch")
+    return {
+        "status": "verified",
+        "target": "authoritative-bare+gitea",
+        "branch": branch,
+        "oid": head,
+        "local": local.get("status"),
+    }
+
+
+def commit(paths, msg):
+    policy.validate_commit_paths(paths, api.WS)
+    api.ensure_git()
+    selected = [api.relpath(p) for p in paths] if paths else ["."]
+    api.sh(["add", *selected], True)
+    policy.validate_staged_paths(api.WS)
+    branch = api.sh(["rev-parse", "--abbrev-ref", "HEAD"], True)["stdout"]
+    if not api.sh(["status", "--short"])["stdout"]:
+        return {"status": "no_changes", "branch": branch, "sync": sync_branch(branch)}
+    out = api.sh(["commit", "-m", msg], True)
+    branch = api.sh(["rev-parse", "--abbrev-ref", "HEAD"], True)["stdout"]
+    return {
+        "status": "committed",
+        "branch": branch,
+        "rev": api.sh(["rev-parse", "--short", "HEAD"], True)["stdout"],
+        "git": out,
+        "sync": sync_branch(branch),
+    }
+
+
+def audit(actor, action, target, payload):
+    policy.append_audit_record(
+        {
+            "at": api.now(),
+            "actor": actor,
+            "action": action,
+            "target": target,
+            "payload": api.sanitize(payload),
+        }
+    )
+
+
+def _validate_request(self, data, validate):
+    try:
+        validate(data)
+        return True
+    except PermissionError as exc:
+        self.sendj({"error": str(exc)}, 403)
+        return False
+
+
+def _checked_branch(self, data):
+    if not _validate_request(self, data, policy.validate_branch_request):
+        return
+    return _branch(self, data)
+
+
+def _checked_file(self, data):
+    data = dict(data)
+    data.setdefault("branch", policy.allowed_branch())
+    if not _validate_request(self, data, policy.validate_branch_request):
+        return
+    if not _validate_request(
+        self,
+        {"path": data.get("path", "")},
+        lambda item: policy.validate_path(item["path"], api.WS),
+    ):
+        return
+    return _file(self, data)
+
+
+def _checked_commit(self, data):
+    data = dict(data)
+    data.setdefault("branch", policy.allowed_branch())
+    if not _validate_request(self, data, policy.validate_branch_request):
+        return
+    return _commit(self, data)
+
+
+def _checked_patch(self, data):
+    data = dict(data)
+    data["branch"] = policy.allowed_branch()
+    if not _validate_request(self, data, policy.validate_branch_request):
+        return
+    return _patch(self, data)
+
+
+_branch, _file, _commit, _patch = api.H.branch, api.H.file, api.H.commit, api.H.patch
+api.reject_non_read_http = reject_non_read_http
+api.checkout, api.write_file, api.sync_branch, api.commit, api.audit = (
+    checkout,
+    write_file,
+    sync_branch,
+    commit,
+    audit,
+)
+api.H.branch, api.H.file, api.H.commit, api.H.patch = (
+    _checked_branch,
+    _checked_file,
+    _checked_commit,
+    _checked_patch,
+)
+api.H.do_GET = _isolated_do_get
+api.H.do_POST = _isolated_do_post
+
+if __name__ == "__main__":
+    policy.require_service_invariants(api.WS, api.BARE_REPO)
+    api.ThreadingHTTPServer((api.HOST, api.PORT), api.H).serve_forever()
@@ -0,0 +1,310 @@
+"""Fail-closed policy used only by the task-scoped Action writer."""
+from __future__ import annotations
+
+import os
+import json
+import stat
+import subprocess
+import re
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from urllib.parse import unquote
+
+import isolated_writer_path_policy as path_policy
+
+WRITE_ENDPOINTS = frozenset({"/api/commit-file"})
+ALLOWED_ROOTS = (
+    "active-runtime",
+    "docs",
+    "patches",
+    "reports",
+    "scripts",
+    "test",
+    "tests",
+)
+DENIED_ROOTS = ("baseline", "config", "deploy", "deployments", "ops", "runtime", "services")
+_TRUE = frozenset({"1", "true", "yes", "on"})
+_FALSE = frozenset({"0", "false", "no", "off"})
+_DENY_FLAGS = (
+    "AIOS_GITOPS_ALLOW_MAIN_WRITE",
+    "AIOS_GITOPS_ALLOW_TAG_WRITE",
+    "AIOS_GITOPS_ALLOW_BASELINE_WRITE",
+    "AIOS_GITOPS_ALLOW_REGISTRY_WRITE",
+    "AIOS_GITOPS_ALLOW_ROLLBACK",
+    "AIOS_GITOPS_ALLOW_DEPLOYMENT",
+)
+
+
+def enforcement_required() -> bool:
+    return os.getenv("AIOS_GITOPS_ISOLATED_WRITER_ENFORCEMENT", "") == "required"
+
+
+def allowed_branch() -> str:
+    value = os.getenv("AIOS_GITOPS_ALLOWED_BRANCH", "").strip()
+    if not value:
+        raise PermissionError("isolated_writer_missing_allowed_branch")
+    return value
+
+
+def allowed_base_oid() -> str:
+    value = os.getenv("AIOS_GITOPS_ALLOWED_BASE_OID", "").strip().lower()
+    if len(value) != 40 or any(ch not in "0123456789abcdef" for ch in value):
+        raise PermissionError("isolated_writer_invalid_allowed_base_oid")
+    return value
+
+
+def _git(workspace: Path, *args: str) -> str:
+    result = subprocess.run(["git", *args], cwd=workspace, text=True, capture_output=True)
+    if result.returncode != 0:
+        raise PermissionError("isolated_writer_git_validation_failed")
+    return result.stdout.strip()
+
+
+def require_service_invariants(workspace: Path, bare_repo: Path) -> None:
+    if not enforcement_required():
+        return
+    if os.getenv("AIOS_GITOPS_WRITES_ENABLED", "").strip().lower() not in _TRUE:
+        raise PermissionError("isolated_writer_write_gate_required")
+    if os.getenv("AIOS_GITOPS_RUNTIME_ROLE", "") != "isolated-writer":
+        raise PermissionError("isolated_writer_role_required")
+    if os.getenv("AIOS_GITOPS_WORKSPACE_ROLE", "") != "isolated-writer":
+        raise PermissionError("isolated_writer_workspace_role_required")
+    if os.getenv("AIOS_GITOPS_TOKEN_POLICY_VERSION_REQUIRED", "") != "2":
+        raise PermissionError("isolated_writer_token_policy_v2_required")
+    if not os.getenv("AIOS_GITOPS_SERVICE_AUDIENCE", "").strip():
+        raise PermissionError("isolated_writer_service_audience_required")
+    if not os.getenv("AIOS_GITOPS_TOKEN_REGISTRY_V2", "").strip():
+        raise PermissionError("isolated_writer_token_registry_required")
+    if not os.getenv("AIOS_GITOPS_WRITER_OPERATION_LEDGER", "").strip():
+        raise PermissionError("isolated_writer_operation_ledger_required")
+    path_policy.configured_path_policy()
+    for name in _DENY_FLAGS:
+        if os.getenv(name, "").strip().lower() not in _FALSE:
+            raise PermissionError("isolated_writer_forbidden_capability_flag")
+    if os.getenv("AIOS_GITOPS_REPOSITORY_IDENTITY", "") != "aios/aios":
+        raise PermissionError("isolated_writer_repository_identity_rejected")
+    configured_bare_value = os.getenv("AIOS_GITOPS_AUTHORITATIVE_GIT_DIR", "").strip()
+    if not configured_bare_value:
+        raise PermissionError("isolated_writer_authoritative_repo_rejected")
+    configured_bare = Path(configured_bare_value)
+    if configured_bare.resolve(strict=True) != bare_repo.resolve(strict=True):
+        raise PermissionError("isolated_writer_authoritative_repo_rejected")
+    writer_root_value = os.getenv("AIOS_GITOPS_APPROVED_WRITER_ROOT", "").strip()
+    if not writer_root_value:
+        raise PermissionError("isolated_writer_workspace_outside_approved_root")
+    writer_root = Path(writer_root_value).resolve(strict=True)
+    lexical_workspace = Path(os.path.abspath(str(workspace)))
+    canonical_workspace = lexical_workspace.resolve(strict=True)
+    if lexical_workspace != canonical_workspace:
+        raise PermissionError("isolated_writer_workspace_symlink_rejected")
+    try:
+        canonical_workspace.relative_to(writer_root)
+    except (ValueError, FileNotFoundError):
+        raise PermissionError("isolated_writer_workspace_outside_approved_root") from None
+    if _git(workspace, "rev-parse", "--abbrev-ref", "HEAD") != allowed_branch():
+        raise PermissionError("isolated_writer_current_branch_rejected")
+    approved_base = allowed_base_oid()
+    try:
+        _git(workspace, "cat-file", "-e", f"{approved_base}^{{commit}}")
+        subprocess.run(
+            ["git", "merge-base", "--is-ancestor", approved_base, "HEAD"],
+            cwd=workspace,
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except (PermissionError, subprocess.CalledProcessError):
+        raise PermissionError("isolated_writer_approved_base_not_ancestor") from None
+    if _git(workspace, "merge-base", approved_base, "HEAD") != approved_base:
+        raise PermissionError("isolated_writer_merge_base_rejected")
+    common = Path(_git(workspace, "rev-parse", "--git-common-dir"))
+    if not common.is_absolute():
+        common = (workspace / common).resolve()
+    if common.resolve() != bare_repo.resolve():
+        raise PermissionError("isolated_writer_common_repo_rejected")
+
+
+def approved_audit_log_path() -> Path:
+    root_value = os.getenv("AIOS_GITOPS_APPROVED_AUDIT_ROOT", "").strip()
+    log_value = os.getenv("AIOS_GITOPS_AUDIT_LOG", "").strip()
+    if not root_value or not log_value:
+        raise PermissionError("isolated_writer_audit_path_missing")
+    lexical_root = Path(os.path.abspath(root_value))
+    lexical_log = Path(os.path.abspath(log_value))
+    root = lexical_root.resolve(strict=True)
+    if lexical_root != root or root.is_symlink() or not root.is_dir():
+        raise PermissionError("isolated_writer_audit_root_rejected")
+    try:
+        lexical_log.relative_to(root)
+    except ValueError:
+        raise PermissionError("isolated_writer_audit_path_outside_approved_root") from None
+    if lexical_log.parent.resolve(strict=True) != lexical_log.parent:
+        raise PermissionError("isolated_writer_audit_parent_symlink_rejected")
+    if lexical_log.exists() and lexical_log.is_symlink():
+        raise PermissionError("isolated_writer_audit_log_symlink_rejected")
+    os.chmod(root, 0o750)
+    os.chmod(lexical_log.parent, 0o750)
+    return lexical_log
+
+
+def append_audit_record(record: dict) -> None:
+    path = approved_audit_log_path()
+    flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(path, flags, 0o600)
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode):
+            raise PermissionError("isolated_writer_audit_log_not_regular")
+        os.fchmod(descriptor, 0o600)
+        line = json.dumps(
+            _audit_sanitize(record),
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8") + b"\n"
+        os.write(descriptor, line)
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+    parent_fd = os.open(path.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    try:
+        os.fsync(parent_fd)
+    finally:
+        os.close(parent_fd)
+
+
+def _audit_sanitize(value):
+    if isinstance(value, dict):
+        return {
+            key: (
+                "[REDACTED]"
+                if any(
+                    marker in str(key).lower()
+                    for marker in (
+                        "authorization",
+                        "credential",
+                        "password",
+                        "secret",
+                        "token",
+                        "private_key",
+                    )
+                )
+                and str(key).lower() != "token_id"
+                else _audit_sanitize(inner)
+            )
+            for key, inner in value.items()
+        }
+    if isinstance(value, list):
+        return [_audit_sanitize(item) for item in value]
+    if isinstance(value, str) and re.search(
+        r"(?i)(authorization\s*:\s*bearer|(?:token|password|secret)\s*[:=])",
+        value,
+    ):
+        return "[REDACTED]"
+    return value
+
+
+def validate_endpoint(method: str, path: str, workspace: Path, bare_repo: Path) -> None:
+    if not enforcement_required():
+        return
+    if method != "POST" or path not in WRITE_ENDPOINTS:
+        raise PermissionError("isolated_writer_operation_forbidden")
+    require_service_invariants(workspace, bare_repo)
+
+
+def validate_branch_request(data: dict) -> None:
+    if not enforcement_required():
+        return
+    branch = allowed_branch() if "branch" not in data else str(data.get("branch") or "").strip()
+    if branch != allowed_branch():
+        raise PermissionError("isolated_writer_branch_rejected")
+    if str(data.get("base", "main")).strip() != "main":
+        raise PermissionError("isolated_writer_base_rejected")
+    if data.get("force") or data.get("force_push"):
+        raise PermissionError("isolated_writer_force_rejected")
+
+
+def validate_path(path: str, workspace: Path | None = None) -> str:
+    if not isinstance(path, str):
+        raise PermissionError("isolated_writer_path_rejected")
+    value = path
+    if not value or value != value.strip() or "\x00" in value or "\\" in value:
+        raise PermissionError("isolated_writer_path_rejected")
+    try:
+        decoded = unquote(value, errors="strict")
+    except (UnicodeDecodeError, ValueError):
+        raise PermissionError("isolated_writer_path_rejected") from None
+    if decoded != value:
+        raise PermissionError("isolated_writer_path_rejected")
+    windows = PureWindowsPath(value)
+    posix = PurePosixPath(value)
+    parts = value.split("/")
+    if (
+        posix.is_absolute()
+        or windows.is_absolute()
+        or bool(windows.drive)
+        or any(part in {"", ".", ".."} for part in parts)
+    ):
+        raise PermissionError("isolated_writer_path_rejected")
+    first = parts[0]
+    service_exact_path = False
+    if first in DENIED_ROOTS:
+        try:
+            path_policy.require_service_path("commit_file.atomic", value)
+            service_exact_path = True
+        except path_policy.PathPolicyError as exc:
+            raise PermissionError(str(exc)) from None
+    if value != "README.md" and first not in ALLOWED_ROOTS and not service_exact_path:
+        raise PermissionError("isolated_writer_path_outside_allowed_roots")
+    if workspace is not None:
+        lexical_root = Path(os.path.abspath(str(workspace)))
+        root = lexical_root.resolve(strict=True)
+        if lexical_root != root:
+            raise PermissionError("isolated_writer_workspace_symlink_rejected")
+        current = root
+        for part in parts:
+            current = current / part
+            if current.is_symlink():
+                raise PermissionError("isolated_writer_path_symlink_rejected")
+        candidate = (root / value).resolve(strict=False)
+        try:
+            candidate.relative_to(root)
+        except ValueError:
+            raise PermissionError("isolated_writer_path_escapes_workspace") from None
+    return value
+
+
+def validate_content_for_path(path: str, content: str) -> None:
+    if path.split("/", 1)[0] not in DENIED_ROOTS:
+        return
+    try:
+        path_policy.validate_content("commit_file.atomic", path, content)
+    except path_policy.PathPolicyError as exc:
+        raise PermissionError(str(exc)) from None
+
+
+def configured_path_policy_sha256() -> str | None:
+    try:
+        return path_policy.configured_path_policy_sha256()
+    except path_policy.PathPolicyError as exc:
+        raise PermissionError(str(exc)) from None
+
+
+def validate_commit_paths(paths: list[str], workspace: Path | None = None) -> None:
+    if enforcement_required():
+        for path in paths:
+            if str(path).strip() != ".":
+                validate_path(str(path), workspace)
+
+
+def validate_staged_paths(workspace: Path) -> None:
+    if not enforcement_required():
+        return
+    for path in _git(workspace, "diff", "--cached", "--name-only").splitlines():
+        validate_path(path, workspace)
+
+
+def validate_sync_branch(branch: str) -> None:
+    if enforcement_required() and branch != allowed_branch():
+        raise PermissionError("isolated_writer_sync_branch_rejected")
@@ -12,7 +12,7 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from typing import Any, Mapping

-from aios_hermes import HermesAdapter, HermesJobState, HermesResult
+from aios_hermes import HermesAdapter, HermesJobState, HermesResult, SQLiteHermesStore
 from aios_openclaw import (
    Ed25519CommandSigner,
    HTTPRuntimeTransport,
@@ -23,7 +23,7 @@ from aios_openclaw.callback import AuditCallbackSink, EventPublisher
 from .console import CONSOLE_HTML
 from .control_plane import AuditEvent, RequestContext, Unauthorized
 from .dispatch_store import SQLiteDispatchRepository
-from .execution_tracking import ExecutionTracker
+from .execution_tracking import ExecutionEvidence, ExecutionTracker
 from .gateway import GatewayApplication, error_response
 from .gitops_status import collect_gitops_status
 from .orchestrator import ExecutionOrchestrator
@@ -143,13 +143,17 @@ class ControlPlaneEventPublisher(EventPublisher):
            raise ValueError("runtime audit event is missing tenant identity")
        state_value = str(event.get("state") or "unknown").lower()
        outcome = "allowed" if state_value == "completed" else state_value
+        runtime = str(event.get("runtime") or "openclaw").strip().lower()
+        principal_id = str(
+            event.get("principal_id") or f"{runtime}-runtime"
+        ).strip()
        audit = AuditEvent(
            event_id=f"runtime_{command_id}_{len(self.service.store.audit_events) + 1}",
            tenant_id=tenant_id,
-            principal_id="openclaw-runtime",
+            principal_id=principal_id,
            trace_id=trace_id,
            action=event_type,
-            resource_type="openclaw_command",
+            resource_type=f"{runtime}_execution",
            resource_id=command_id,
            outcome=outcome,
            policy_version="runtime-v2",
@@ -168,12 +172,16 @@ class CandidateApplication:
        tracker: ExecutionTracker,
        hermes: HermesAdapter,
        openclaw: OpenClawAdapter | None,
+        *,
+        hermes_lifecycle_api_enabled: bool = False,
    ) -> None:
        self.gateway = gateway
        self.orchestrator = orchestrator
        self.tracker = tracker
        self.hermes = hermes
        self.openclaw = openclaw
+        self.hermes_lifecycle_api_enabled = bool(hermes_lifecycle_api_enabled)
+        self.runtime_events = ControlPlaneEventPublisher(orchestrator.control_plane)

    def context(self, headers: Mapping[str, str]) -> RequestContext:
        return self.gateway.context_from_headers(headers)
@@ -183,6 +191,108 @@ class CandidateApplication:
        if not ({"runtime", "platform_admin"} & set(context.roles)):
            raise Unauthorized("runtime reconciliation role is required")

+    @staticmethod
+    def _require_control_plane_cancel(context: RequestContext) -> None:
+        required = {"runtime", "platform_admin"}
+        if not required.issubset(set(context.roles)):
+            raise Unauthorized(
+                "Hermes cancellation requires trusted AIOS control-plane authority"
+            )
+
+    @staticmethod
+    def _required_identity(payload: Mapping[str, Any], name: str) -> str:
+        value = str(payload.get(name) or "").strip()
+        if not value:
+            raise ValueError(f"{name} is required")
+        return value
+
+    def _record_hermes_lifecycle(
+        self,
+        context: RequestContext,
+        dispatch: Any,
+        job: Any,
+        *,
+        action: str,
+        worker_id: str | None,
+        provenance_id: str,
+        run_id: str,
+    ) -> None:
+        executor = worker_id or "aios-control-plane"
+        evidence = ExecutionEvidence(
+            execution_id=job.job_id,
+            tenant_id=job.tenant_id,
+            task_id=job.task_id,
+            agent_id=dispatch.agent_id,
+            executor=executor,
+            branch="runtime/hermes",
+            status=job.state.value.lower(),
+            progress_completed=0,
+            progress_total=3,
+            current_step=action,
+            provenance_id=provenance_id,
+            run_id=run_id,
+        )
+        current_evidence = self.tracker.claim(
+            evidence,
+            principal_id=context.principal_id,
+            provenance_id=provenance_id,
+            run_id=run_id,
+        )
+        if job.state in {
+            HermesJobState.COMPLETED,
+            HermesJobState.FAILED,
+            HermesJobState.CANCELLED,
+        }:
+            if current_evidence.completed_at is None:
+                self.tracker.complete(
+                    tenant_id=job.tenant_id,
+                    execution_id=job.job_id,
+                    status=job.state.value.lower(),
+                    test_status="runtime_terminal",
+                    test_summary={"lifecycle_action": action},
+                    result_summary={
+                        "state": job.state.value,
+                        "worker_id": worker_id,
+                        "dispatch_id": dispatch.dispatch_id,
+                    },
+                    principal_id=context.principal_id,
+                    provenance_id=provenance_id,
+                    run_id=run_id,
+                )
+        else:
+            self.tracker.heartbeat(
+                tenant_id=job.tenant_id,
+                execution_id=job.job_id,
+                status=job.state.value.lower(),
+                current_step=action,
+                progress_completed=(1 if job.state == HermesJobState.RUNNING else 0),
+                progress_total=3,
+                principal_id=context.principal_id,
+                provenance_id=provenance_id,
+                run_id=run_id,
+            )
+        self.runtime_events.publish(
+            {
+                "runtime": "hermes",
+                "tenant_id": job.tenant_id,
+                "principal_id": context.principal_id,
+                "trace_id": job.trace_id,
+                "command_id": job.job_id,
+                "event_type": f"HERMES_{action.upper()}",
+                "state": job.state.value,
+                "details": {
+                    "dispatch_id": dispatch.dispatch_id,
+                    "task_id": job.task_id,
+                    "worker_id": worker_id,
+                    "cell_id": job.cell_id,
+                    "profile_id": job.profile_id,
+                    "revision": job.revision,
+                    "provenance_id": provenance_id,
+                    "run_id": run_id,
+                },
+            }
+        )
+
    def handle_json(
        self,
        method: str,
@@ -269,6 +379,233 @@ class CandidateApplication:
            )
            return HTTPStatus.ACCEPTED, {"dispatch": _json_value(record)}

+        lifecycle_match = __import__("re").fullmatch(
+            r"/api/v2/internal/runtime/hermes/lifecycle/"
+            r"(claim|start|heartbeat|complete|fail|cancel|status)",
+            path,
+        )
+        if method == "POST" and lifecycle_match:
+            if not self.hermes_lifecycle_api_enabled:
+                return HTTPStatus.NOT_FOUND, {
+                    "error": "not_found",
+                    "message": "route not found",
+                }
+            context = self.context(headers)
+            self._require_runtime_role(context)
+            if not isinstance(body, Mapping):
+                raise ValueError("JSON body must be an object")
+            payload = body
+            action = lifecycle_match.group(1)
+            identity = {
+                name: self._required_identity(payload, name)
+                for name in (
+                    "dispatch_id",
+                    "job_id",
+                    "tenant_id",
+                    "task_id",
+                    "trace_id",
+                    "principal_id",
+                    "provenance_id",
+                    "run_id",
+                    "cell_id",
+                    "profile_id",
+                )
+            }
+            header_provenance, header_run = _provenance_context(headers, payload)
+            if header_provenance != identity["provenance_id"]:
+                raise ValueError("provenance_id context mismatch")
+            if header_run != identity["run_id"]:
+                raise ValueError("run_id context mismatch")
+            requeued_job_ids = self.hermes.requeue_expired()
+            dispatch, job = self.orchestrator.hermes_lifecycle_context(
+                context,
+                dispatch_id=identity["dispatch_id"],
+                job_id=identity["job_id"],
+                tenant_id=identity["tenant_id"],
+                task_id=identity["task_id"],
+                trace_id=identity["trace_id"],
+                principal_id=identity["principal_id"],
+                provenance_id=identity["provenance_id"],
+                run_id=identity["run_id"],
+            )
+            if job.cell_id != identity["cell_id"]:
+                raise ValueError("cell_id mismatch")
+            if job.profile_id != identity["profile_id"]:
+                raise ValueError("profile_id mismatch")
+
+            if action == "status":
+                if job.job_id in requeued_job_ids:
+                    self._record_hermes_lifecycle(
+                        context,
+                        dispatch,
+                        job,
+                        action="lease_expired_requeue",
+                        worker_id=None,
+                        provenance_id=identity["provenance_id"],
+                        run_id=identity["run_id"],
+                    )
+                task = self.orchestrator.control_plane.get_task(
+                    context, dispatch.task_id
+                )
+                response: dict[str, Any] = {
+                    "job": _json_value(job),
+                    "dispatch": _json_value(dispatch),
+                    "task": _json_value(task),
+                }
+                if job.state in {
+                    HermesJobState.COMPLETED,
+                    HermesJobState.FAILED,
+                    HermesJobState.CANCELLED,
+                }:
+                    response["result"] = _json_value(
+                        self.hermes.result(job.job_id, tenant_id=job.tenant_id)
+                    )
+                return HTTPStatus.OK, response
+
+            expected_revision = payload.get("expected_revision")
+            expected = (
+                int(expected_revision) if expected_revision is not None else None
+            )
+            if action == "cancel":
+                self._require_control_plane_cancel(context)
+                if payload.get("worker_id") is not None:
+                    raise Unauthorized("Hermes workers may observe but not initiate cancel")
+                if payload.get("cancellation_source") != "aios-control-plane":
+                    raise ValueError(
+                        "cancellation_source must be aios-control-plane"
+                    )
+                result = self.hermes.cancel(
+                    job.job_id,
+                    tenant_id=job.tenant_id,
+                    expected_revision=expected,
+                )
+            else:
+                worker_id = self._required_identity(payload, "worker_id")
+                if action == "claim":
+                    claimed = self.hermes.claim(
+                        tenant_id=job.tenant_id,
+                        cell_id=job.cell_id,
+                        profile_id=job.profile_id,
+                        worker_id=worker_id,
+                        lease_seconds=(
+                            int(payload["lease_seconds"])
+                            if payload.get("lease_seconds") is not None
+                            else None
+                        ),
+                        job_id=job.job_id,
+                    )
+                    if claimed is None:
+                        raise ValueError("Hermes job is not claimable")
+                    bound = self.orchestrator.bind_hermes_worker(
+                        context,
+                        claimed,
+                        dispatch_id=dispatch.dispatch_id,
+                        provenance_id=identity["provenance_id"],
+                        run_id=identity["run_id"],
+                        worker_id=worker_id,
+                    )
+                    self._record_hermes_lifecycle(
+                        context,
+                        bound,
+                        claimed,
+                        action="claim",
+                        worker_id=worker_id,
+                        provenance_id=identity["provenance_id"],
+                        run_id=identity["run_id"],
+                    )
+                    return HTTPStatus.OK, {
+                        "job": _json_value(claimed),
+                        "dispatch": _json_value(bound),
+                    }
+                if action == "start":
+                    started = self.hermes.start(
+                        job.job_id,
+                        tenant_id=job.tenant_id,
+                        worker_id=worker_id,
+                        expected_revision=expected,
+                    )
+                    self._record_hermes_lifecycle(
+                        context,
+                        dispatch,
+                        started,
+                        action="start",
+                        worker_id=worker_id,
+                        provenance_id=identity["provenance_id"],
+                        run_id=identity["run_id"],
+                    )
+                    return HTTPStatus.OK, {"job": _json_value(started)}
+                if action == "heartbeat":
+                    heartbeat = self.hermes.heartbeat(
+                        job.job_id,
+                        tenant_id=job.tenant_id,
+                        worker_id=worker_id,
+                        lease_seconds=(
+                            int(payload["lease_seconds"])
+                            if payload.get("lease_seconds") is not None
+                            else None
+                        ),
+                    )
+                    self._record_hermes_lifecycle(
+                        context,
+                        dispatch,
+                        heartbeat,
+                        action="heartbeat",
+                        worker_id=worker_id,
+                        provenance_id=identity["provenance_id"],
+                        run_id=identity["run_id"],
+                    )
+                    return HTTPStatus.OK, {"job": _json_value(heartbeat)}
+                if action == "complete":
+                    output = payload.get("output")
+                    if not isinstance(output, Mapping):
+                        raise ValueError("output must be an object")
+                    result = self.hermes.complete(
+                        job.job_id,
+                        tenant_id=job.tenant_id,
+                        worker_id=worker_id,
+                        output=output,
+                        expected_revision=expected,
+                    )
+                elif action == "fail":
+                    error = payload.get("error")
+                    if not isinstance(error, Mapping):
+                        raise ValueError("error must be an object")
+                    result = self.hermes.fail(
+                        job.job_id,
+                        tenant_id=job.tenant_id,
+                        worker_id=worker_id,
+                        error=error,
+                        expected_revision=expected,
+                    )
+                else:
+                    raise ValueError("unsupported Hermes lifecycle action")
+
+            task = self.orchestrator.reconcile_hermes(
+                context,
+                result,
+                dispatch_id=dispatch.dispatch_id,
+                provenance_id=identity["provenance_id"],
+                run_id=identity["run_id"],
+            )
+            updated_dispatch = self.orchestrator.dispatch_repository.get(
+                dispatch.dispatch_id, tenant_id=dispatch.tenant_id
+            )
+            terminal_job = self.hermes.get(job.job_id, tenant_id=job.tenant_id)
+            self._record_hermes_lifecycle(
+                context,
+                updated_dispatch,
+                terminal_job,
+                action=action,
+                worker_id=result.worker_id,
+                provenance_id=identity["provenance_id"],
+                run_id=identity["run_id"],
+            )
+            return HTTPStatus.OK, {
+                "result": _json_value(result),
+                "task": _json_value(task),
+                "dispatch": _json_value(updated_dispatch),
+            }
+
        if method == "POST" and path == "/api/v2/internal/runtime/hermes/reconcile":
            context = self.context(headers)
            self._require_runtime_role(context)
@@ -411,7 +748,7 @@ def build_application() -> CandidateApplication:
        provenance_writer=provenance_writer,
        require_provenance=require_provenance,
    )
-    hermes = HermesAdapter()
+    hermes = HermesAdapter(store=SQLiteHermesStore(state_dir / "hermes.sqlite3"))

    openclaw_url = os.getenv("AIOS_OPENCLAW_URL", "").strip()
    signing_file = os.getenv("AIOS_OPENCLAW_SIGNING_MATERIAL_FILE", "").strip()
@@ -446,7 +783,16 @@ def build_application() -> CandidateApplication:
        require_provenance=require_provenance,
        dispatch_repository=dispatch_repository,
    )
-    return CandidateApplication(gateway, orchestrator, tracker, hermes, openclaw)
+    return CandidateApplication(
+        gateway,
+        orchestrator,
+        tracker,
+        hermes,
+        openclaw,
+        hermes_lifecycle_api_enabled=_enabled(
+            os.getenv("AIOS_HERMES_LIFECYCLE_API_ENABLED", "0")
+        ),
+    )


 def main() -> None:
@@ -1,69 +1,83 @@
-"""Dependency-free AIOS V2 web console assets.
+"""Dependency-free, role-aware AIOS unified portal.

-Authentication and tenant identity are injected by the trusted reverse proxy.
-The browser never selects a tenant and never calls OpenClaw or Hermes directly.
+The browser receives only server-authorized capabilities and tenant-scoped data.
+It never selects a tenant, signs Provenance, mutates Git tags, or calls Runtime
+services directly.
 """

 CONSOLE_HTML = r'''<!doctype html>
-<html lang="en">
+<html lang="zh-CN">
 <head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta name="referrer" content="no-referrer">
-  <title>AIOS V2 Console</title>
+  <title>AIOS Unified Portal</title>
  <style>
-    :root{font-family:Inter,ui-sans-serif,system-ui,sans-serif;color:#152033;background:#f4f7fb}
-    *{box-sizing:border-box} body{margin:0} header{background:#111827;color:white;padding:18px 24px;display:flex;justify-content:space-between;align-items:center}
-    header h1{font-size:20px;margin:0} header span{font-size:12px;color:#cbd5e1}
-    main{padding:24px;max-width:1440px;margin:auto}.notice{background:#fff7ed;border:1px solid #fed7aa;padding:12px 14px;border-radius:10px;margin-bottom:18px;font-size:13px}
-    .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:14px;margin-bottom:20px}.card,.panel{background:white;border:1px solid #e5e7eb;border-radius:12px;box-shadow:0 1px 2px rgba(0,0,0,.04)}
-    .card{padding:16px}.card b{display:block;font-size:28px;margin-top:8px}.card small{color:#64748b}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(420px,1fr));gap:16px}.panel{padding:16px;overflow:auto}.panel h2{font-size:16px;margin:0 0 12px}
-    table{width:100%;border-collapse:collapse;font-size:12px}th,td{text-align:left;border-bottom:1px solid #edf0f4;padding:8px;vertical-align:top}th{color:#64748b;font-weight:600}.state{font-weight:700}.ok{color:#047857}.bad{color:#b91c1c}.muted{color:#64748b}
-    button{border:0;border-radius:8px;padding:9px 13px;background:#2563eb;color:white;cursor:pointer}button:disabled{opacity:.5}.toolbar{display:flex;gap:8px;align-items:center;margin-bottom:16px}.error{color:#b91c1c;white-space:pre-wrap}
+    :root{font-family:Inter,"PingFang SC","Microsoft YaHei",ui-sans-serif,system-ui,sans-serif;color:#172033;background:#eef2f7;--nav:#0f172a;--card:#fff;--line:#dfe6ef;--muted:#667085;--blue:#2563eb;--green:#047857;--red:#b42318;--amber:#b54708}
+    *{box-sizing:border-box}body{margin:0;min-height:100vh}button,input,textarea,select{font:inherit}
+    .shell{display:grid;grid-template-columns:250px minmax(0,1fr);min-height:100vh}.sidebar{background:var(--nav);color:#e2e8f0;padding:22px 16px;position:sticky;top:0;height:100vh;overflow:auto}.brand{font-weight:800;font-size:20px;letter-spacing:.2px}.version{font-size:12px;color:#94a3b8;margin:5px 0 22px}.identity{padding:12px;background:#182338;border:1px solid #2b3950;border-radius:12px;margin-bottom:18px}.identity strong{display:block;color:#fff}.identity span{font-size:12px;color:#aebbd0;display:block;margin-top:3px;overflow-wrap:anywhere}.nav button{width:100%;display:flex;gap:10px;align-items:center;border:0;background:transparent;color:#cbd5e1;padding:11px 12px;border-radius:9px;text-align:left;cursor:pointer;margin:2px 0}.nav button:hover,.nav button.active{background:#24324b;color:#fff}.nav .dot{width:8px;height:8px;border-radius:50%;background:#60a5fa}.main{min-width:0}.topbar{height:70px;background:#fff;border-bottom:1px solid var(--line);display:flex;align-items:center;justify-content:space-between;padding:0 26px;position:sticky;top:0;z-index:4}.topbar h1{font-size:19px;margin:0}.top-actions{display:flex;align-items:center;gap:10px}.timestamp{font-size:12px;color:var(--muted)}.content{padding:24px;max-width:1680px;margin:auto}.notice{background:#eff6ff;border:1px solid #bfdbfe;border-radius:12px;padding:12px 14px;color:#1e3a8a;font-size:13px;margin-bottom:18px}.error{background:#fef3f2;border:1px solid #fecdca;color:var(--red);border-radius:10px;padding:10px 12px;white-space:pre-wrap;margin-bottom:14px;display:none}.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(170px,1fr));gap:14px;margin-bottom:18px}.card,.panel{background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:0 1px 3px rgba(16,24,40,.05)}.card{padding:16px}.card small{color:var(--muted);font-weight:600}.card b{display:block;font-size:28px;margin-top:7px}.panel{padding:17px;margin-bottom:16px;overflow:auto}.panel h2{font-size:16px;margin:0}.panel-head{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:13px}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(410px,1fr));gap:16px}.wide{grid-column:1/-1}.muted{color:var(--muted)}.good{color:var(--green);font-weight:700}.bad{color:var(--red);font-weight:700}.warn{color:var(--amber);font-weight:700}.pill{display:inline-block;border:1px solid #cbd5e1;border-radius:999px;padding:3px 8px;font-size:11px;margin:2px;background:#f8fafc}.pill.good{background:#ecfdf3;border-color:#a6f4c5}.pill.bad{background:#fef3f2;border-color:#fecdca}.toolbar{display:flex;gap:8px;align-items:center;flex-wrap:wrap}.btn{border:0;border-radius:9px;padding:9px 12px;background:var(--blue);color:#fff;cursor:pointer;font-weight:650}.btn.secondary{background:#fff;color:#344054;border:1px solid #d0d5dd}.btn.danger{background:#d92d20}.btn:disabled{opacity:.45;cursor:not-allowed}.icon-btn{padding:7px 10px}.view{display:none}.view.active{display:block}table{width:100%;border-collapse:collapse;font-size:12px}th,td{text-align:left;padding:9px 8px;border-bottom:1px solid #edf0f4;vertical-align:top}th{color:#667085;font-weight:700;white-space:nowrap}td{overflow-wrap:anywhere}.empty{padding:24px;text-align:center;color:var(--muted)}.timeline{border-left:2px solid #dbe4f0;margin-left:8px;padding-left:20px}.event{position:relative;padding:0 0 17px}.event:before{content:"";position:absolute;left:-27px;top:4px;width:11px;height:11px;border-radius:50%;background:#3b82f6;border:3px solid #fff;box-shadow:0 0 0 1px #93c5fd}.event strong{font-size:13px}.event p{margin:4px 0;color:var(--muted);font-size:12px}.chain{display:flex;align-items:stretch;gap:7px;overflow:auto;padding:5px 0}.chain-item{min-width:135px;border:1px solid var(--line);border-radius:10px;padding:10px;background:#f8fafc}.chain-arrow{display:flex;align-items:center;color:#94a3b8}.form-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:12px}.field label{font-size:12px;color:#475467;font-weight:650;display:block;margin-bottom:5px}.field input,.field textarea,.field select{width:100%;border:1px solid #d0d5dd;border-radius:9px;padding:9px;background:#fff}.field textarea{min-height:90px;resize:vertical}.dialog{border:0;border-radius:14px;padding:0;max-width:650px;width:calc(100% - 32px);box-shadow:0 20px 60px rgba(15,23,42,.28)}.dialog::backdrop{background:rgba(15,23,42,.6)}.dialog-head{padding:16px 18px;border-bottom:1px solid var(--line);font-weight:750}.dialog-body{padding:18px}.dialog-actions{padding:14px 18px;border-top:1px solid var(--line);display:flex;justify-content:flex-end;gap:8px}.kv{display:grid;grid-template-columns:150px minmax(0,1fr);gap:6px 12px;font-size:12px}.kv div:nth-child(odd){color:var(--muted)}pre{white-space:pre-wrap;word-break:break-word;font-size:11px;background:#0f172a;color:#dbeafe;border-radius:10px;padding:12px;max-height:300px;overflow:auto}
+    @media(max-width:900px){.shell{grid-template-columns:1fr}.sidebar{height:auto;position:static}.nav{display:flex;overflow:auto}.nav button{min-width:max-content}.topbar{position:static}.grid{grid-template-columns:1fr}.content{padding:16px}}
  </style>
 </head>
 <body>
-<header><h1>AIOS V2 Control Plane</h1><span id="updated">Not loaded</span></header>
-<main>
-  <div class="notice">Read-only candidate console. Identity and tenant context must be injected by the trusted reverse proxy. The console never calls OpenClaw or Hermes directly.</div>
-  <div class="toolbar"><button id="refresh">Refresh</button><span id="error" class="error"></span></div>
-  <section class="cards">
-    <div class="card"><small>Agents</small><b id="agentCount">—</b></div>
-    <div class="card"><small>Tasks</small><b id="taskCount">—</b></div>
-    <div class="card"><small>Audit events</small><b id="auditCount">—</b></div>
-    <div class="card"><small>Executions</small><b id="executionCount">—</b></div>
+<div class="shell">
+  <aside class="sidebar">
+    <div class="brand">AIOS Unified Portal</div><div class="version">V2R1C1 · Role-aware Control Plane</div>
+    <div class="identity"><strong id="principal">加载身份…</strong><span id="tenant"></span><span id="roles"></span></div>
+    <nav id="navigation" class="nav"></nav>
+  </aside>
+  <section class="main">
+    <header class="topbar"><h1 id="pageTitle">系统总览</h1><div class="top-actions"><span id="updated" class="timestamp">尚未加载</span><button class="btn secondary icon-btn" id="refresh">刷新</button></div></header>
+    <main class="content">
+      <div class="notice">身份、租户和角色由可信反向代理注入。门户只调用 AIOS Control Plane；Provenance 签发、Tag、生产部署与 Runtime 权威状态仍由受控流程执行。</div>
+      <div id="error" class="error"></div>
+      <section id="overview" class="view active"></section>
+      <section id="tasks" class="view"></section>
+      <section id="authorization" class="view"></section>
+      <section id="runtime" class="view"></section>
+      <section id="evidence" class="view"></section>
+      <section id="audit" class="view"></section>
+      <section id="release" class="view"></section>
+    </main>
  </section>
-  <section class="grid">
-    <div class="panel"><h2>Runtime health</h2><div id="runtime"></div></div>
-    <div class="panel"><h2>Tasks</h2><div id="tasks"></div></div>
-    <div class="panel"><h2>Agents</h2><div id="agents"></div></div>
-    <div class="panel"><h2>Execution evidence</h2><div id="executions"></div></div>
-    <div class="panel"><h2>Audit</h2><div id="audit"></div></div>
-  </section>
-</main>
+</div>
+<dialog id="taskDialog" class="dialog">
+  <div class="dialog-head">创建任务</div><form id="taskForm"><div class="dialog-body form-grid">
+    <div class="field"><label>Agent ID</label><input name="agent_id" required></div>
+    <div class="field"><label>Action</label><input name="action" required></div>
+    <div class="field"><label>Idempotency Key</label><input name="idempotency_key" required></div>
+    <div class="field wide"><label>Payload JSON</label><textarea name="payload">{}</textarea></div>
+  </div><div class="dialog-actions"><button type="button" class="btn secondary" data-close="taskDialog">取消</button><button class="btn">创建</button></div></form>
+</dialog>
+<dialog id="confirmDialog" class="dialog"><div class="dialog-head" id="confirmTitle">确认操作</div><form id="confirmForm"><div class="dialog-body"><p id="confirmText"></p><div class="field"><label>原因</label><textarea id="confirmReason" required></textarea></div></div><div class="dialog-actions"><button type="button" class="btn secondary" data-close="confirmDialog">取消</button><button class="btn danger">确认</button></div></form></dialog>
 <script>
-const esc=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
-const table=(cols,rows)=>`<table><thead><tr>${cols.map(c=>`<th>${esc(c[0])}</th>`).join('')}</tr></thead><tbody>${rows.map(r=>`<tr>${cols.map(c=>`<td>${esc(c[1](r))}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
-async function api(path){const r=await fetch(path,{credentials:'same-origin',headers:{'Accept':'application/json'}});const data=await r.json().catch(()=>({}));if(!r.ok)throw new Error(`${r.status} ${data.message||data.error||path}`);return data}
-async function refresh(){
-  const btn=document.getElementById('refresh');btn.disabled=true;document.getElementById('error').textContent='';
-  try{
-    const [agents,tasks,audit,runtime,executions]=await Promise.all([
-      api('/api/v2/agents'),api('/api/v2/tasks'),api('/api/v2/audit'),api('/api/v2/runtime'),api('/api/v2/executions')
-    ]);
-    document.getElementById('agentCount').textContent=agents.agents.length;
-    document.getElementById('taskCount').textContent=tasks.tasks.length;
-    document.getElementById('auditCount').textContent=audit.events.length;
-    document.getElementById('executionCount').textContent=executions.executions.length;
-    document.getElementById('agents').innerHTML=table([['ID',x=>x.agent_id],['Runtime',x=>x.runtime],['Enabled',x=>x.enabled]],agents.agents);
-    document.getElementById('tasks').innerHTML=table([['Task',x=>x.task_id],['Action',x=>x.action],['State',x=>x.state],['Rev',x=>x.revision]],tasks.tasks);
-    document.getElementById('audit').innerHTML=table([['Time',x=>x.created_at],['Action',x=>x.action],['Outcome',x=>x.outcome],['Resource',x=>x.resource_id]],audit.events.slice(-100).reverse());
-    document.getElementById('executions').innerHTML=table([['Executor',x=>x.executor],['Task',x=>x.task_id],['Status',x=>x.status],['Progress',x=>`${x.progress_completed}/${x.progress_total}`],['Commit',x=>x.last_commit||'']],executions.executions);
-    document.getElementById('runtime').innerHTML=table([['Runtime',x=>x.name],['Status',x=>x.status],['Details',x=>JSON.stringify(x.details)]],runtime.runtimes);
-    document.getElementById('updated').textContent=`Updated ${new Date().toLocaleString()}`;
-  }catch(e){document.getElementById('error').textContent=e.message||String(e)}finally{btn.disabled=false}
-}
-document.getElementById('refresh').addEventListener('click',refresh);refresh();setInterval(refresh,30000);
+const $=s=>document.querySelector(s), esc=v=>String(v??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+const state={identity:null,current:'overview',cache:{},confirm:null};
+const labels={overview:'系统总览',tasks:'任务中心',authorization:'授权中心',runtime:'运行与运维',evidence:'执行证据',audit:'审计中心',release:'GitOps 与发布'};
+function has(c){return !!state.identity?.capabilities?.includes(c)}
+async function api(path,options={}){const r=await fetch(path,{credentials:'same-origin',headers:{'Accept':'application/json','Content-Type':'application/json',...(options.headers||{})},...options});const d=await r.json().catch(()=>({}));if(!r.ok)throw new Error(`${r.status} ${d.message||d.error||path}`);return d}
+function err(e){const el=$('#error');el.textContent=e?.message||String(e);el.style.display='block'}function clearErr(){$('#error').style.display='none';$('#error').textContent=''}
+function pill(v){const s=String(v??'unknown'),c=/complete|pass|healthy|active|synced|approved|used/i.test(s)?'good':/fail|deny|reject|revoke|expire|cancel|unavailable/i.test(s)?'bad':'';return `<span class="pill ${c}">${esc(s)}</span>`}
+function table(cols,rows){if(!rows?.length)return '<div class="empty">暂无数据</div>';return `<table><thead><tr>${cols.map(x=>`<th>${esc(x[0])}</th>`).join('')}</tr></thead><tbody>${rows.map(r=>`<tr>${cols.map(x=>`<td>${x[1](r)}</td>`).join('')}</tr>`).join('')}</tbody></table>`}
+function card(label,value,detail=''){return `<div class="card"><small>${esc(label)}</small><b>${esc(value)}</b>${detail?`<span class="muted">${esc(detail)}</span>`:''}</div>`}
+function json(v){return `<pre>${esc(JSON.stringify(v,null,2))}</pre>`}
+function show(view){state.current=view;document.querySelectorAll('.view').forEach(x=>x.classList.toggle('active',x.id===view));document.querySelectorAll('.nav button').forEach(x=>x.classList.toggle('active',x.dataset.view===view));$('#pageTitle').textContent=labels[view]||view;load(view)}
+function navigation(){const nav=$('#navigation');nav.innerHTML=(state.identity.navigation||[]).map(x=>`<button data-view="${esc(x.id)}"><span class="dot"></span>${esc(x.label)}</button>`).join('');nav.querySelectorAll('button').forEach(b=>b.onclick=()=>show(b.dataset.view));}
+async function identity(){state.identity=await api('/api/v2/me/capabilities');$('#principal').textContent=state.identity.principal_id;$('#tenant').textContent=`租户：${state.identity.tenant_id}`;$('#roles').textContent=`角色：${state.identity.roles.join(', ')||'无'}`;navigation();if(!state.identity.navigation.some(x=>x.id===state.current))state.current=state.identity.navigation[0]?.id||'overview';show(state.current)}
+async function load(view){clearErr();try{if(view==='overview')await overview();if(view==='tasks')await tasks();if(view==='authorization')await authorizations();if(view==='runtime')await runtime();if(view==='evidence')await evidence();if(view==='audit')await audit();if(view==='release')await release();$('#updated').textContent=`更新于 ${new Date().toLocaleString()}`}catch(e){err(e)}}
+async function overview(){const d=await api('/api/v2/portal/overview');state.cache.overview=d;const s=d.summary||{},rt=d.sections?.runtime?.runtimes||[],rel=d.sections?.release||{};$('#overview').innerHTML=`<div class="cards">${card('任务',s.tasks||0)}${card('活动 Dispatch',s.active_dispatches||0,`总数 ${s.dispatches||0}`)}${card('执行证据',s.evidence||0)}${card('审计事件',s.audit_events||0)}${card('当前版本',rel.version||'—',rel.status||'')}${card('授权 Grant',d.sections?.authorization?.active_grants||0,`总数 ${d.sections?.authorization?.grants||0}`)}</div><div class="grid"><div class="panel"><div class="panel-head"><h2>Runtime 健康</h2></div>${table([['Runtime',x=>esc(x.name)],['状态',x=>pill(x.status)],['版本/详情',x=>esc(x.details?.version||x.details?.runtime_id||'—')]],rt)}</div><div class="panel"><div class="panel-head"><h2>任务状态</h2></div>${table([['状态',x=>pill(x[0])],['数量',x=>esc(x[1])]],Object.entries(s.task_states||{}))}</div><div class="panel wide"><div class="panel-head"><h2>最近任务</h2></div>${table([['任务',x=>esc(x.task_id)],['Agent',x=>esc(x.agent_id)],['动作',x=>esc(x.action)],['状态',x=>pill(x.state)],['更新时间',x=>esc(x.updated_at)]],d.recent?.tasks||[])}</div></div>`}
+async function tasks(){const d=await api('/api/v2/portal/tasks');state.cache.tasks=d.items||[];const create=has('task.create')?'<button class="btn" id="newTask">创建任务</button>':'';$('#tasks').innerHTML=`<div class="panel"><div class="panel-head"><h2>任务全链路</h2><div class="toolbar">${create}</div></div>${(d.items||[]).map(taskBlock).join('')||'<div class="empty">暂无任务</div>'}</div>`;$('#newTask')?.addEventListener('click',()=>$('#taskDialog').showModal());document.querySelectorAll('[data-task-action]').forEach(b=>b.onclick=()=>taskAction(b.dataset.taskId,b.dataset.taskAction,b.dataset.revision))}
+function taskBlock(x){const t=x.task||{},d=x.dispatch,e=x.evidence||[],a=x.audit||[],actions=(x.available_actions||[]).map(v=>`<button class="btn ${v==='cancel'?'danger':'secondary'}" data-task-action="${v}" data-task-id="${esc(t.task_id)}" data-revision="${esc(t.revision)}">${{approve:'审批',cancel:'取消',dispatch:'调度'}[v]||v}</button>`).join('');return `<div class="panel" style="background:#fbfcfe"><div class="panel-head"><h2>${esc(t.task_id)} · ${esc(t.action)}</h2><div class="toolbar">${pill(t.state)}${actions}</div></div><div class="chain"><div class="chain-item"><b>Task</b><div>${esc(t.agent_id)}</div><small>${esc(t.created_by)}</small></div><span class="chain-arrow">→</span><div class="chain-item"><b>Approval</b><div>${esc(t.approved_by||'待审批')}</div><small>revision ${esc(t.revision)}</small></div><span class="chain-arrow">→</span><div class="chain-item"><b>Provenance</b><div>${esc(d?.provenance_id||'未调度')}</div><small>${esc(d?.authorization_id||'')}</small></div><span class="chain-arrow">→</span><div class="chain-item"><b>Dispatch</b><div>${esc(d?.dispatch_id||'—')}</div><small>${pill(d?.state||'not_created')}</small></div><span class="chain-arrow">→</span><div class="chain-item"><b>Runtime</b><div>${esc(d?.runtime||'—')}</div><small>${esc(d?.runtime_execution_id||'')}</small></div><span class="chain-arrow">→</span><div class="chain-item"><b>Evidence</b><div>${e.length} 条</div><small>Audit ${a.length} 条</small></div></div></div>`}
+async function taskAction(id,action,revision){clearErr();try{let body={expected_revision:Number(revision)};if(action==='dispatch'){body={};const p=prompt('Provenance ID（生产调度必填）','');const r=prompt('Run ID（生产调度必填）','');if(p)body.provenance_id=p;if(r)body.run_id=r}await api(`/api/v2/portal/tasks/${encodeURIComponent(id)}/${action}`,{method:'POST',body:JSON.stringify(body)});await tasks()}catch(e){err(e)}}
+async function authorizations(){const d=await api('/api/v2/portal/authorizations');state.cache.authorization=d;const workflows=(d.workflows||[]),grants=(d.grants||[]);$('#authorization').innerHTML=`<div class="cards">${card('Workflow',d.summary?.workflows||0)}${card('Grant',d.summary?.grants||0)}${card('有效 Grant',d.summary?.active_grants||0)}${card('已撤销',d.summary?.revoked_grants||0)}</div><div class="panel"><div class="panel-head"><h2>Workflow Provenance</h2></div>${table([['ID',x=>esc(x.provenance_id)],['Run / Task',x=>`${esc(x.run_id)}<br>${esc(x.task_id)}`],['Principal / Agent',x=>`${esc(x.principal_id)}<br>${esc(x.agent_id)}`],['状态',x=>pill(x.status)],['有效期',x=>esc(x.expires_at)],['使用',x=>esc(x.usage_count)],['操作',x=>has('provenance.revoke')&&x.status!=='revoked'?`<button class="btn danger" data-revoke-workflow="${esc(x.provenance_id)}">撤销</button>`:'—']],workflows)}</div><div class="panel"><div class="panel-head"><h2>Child Grants</h2></div>${table([['Grant',x=>esc(x.grant_id)],['类型 / Scope',x=>`${esc(x.grant_type)}<br>${esc(x.execution_path)}`],['Git 操作',x=>esc((x.allowed_git_operations||[]).join(', ')||'—')],['状态',x=>pill(x.status)],['有效期',x=>esc(x.expires_at)],['使用',x=>esc(x.usage_count)],['操作',x=>has('provenance.revoke')&&x.status!=='revoked'?`<button class="btn danger" data-revoke-grant="${esc(x.grant_id)}">撤销</button>`:'—']],grants)}</div>`;document.querySelectorAll('[data-revoke-workflow]').forEach(b=>b.onclick=()=>confirmOp('撤销 Workflow',`撤销 ${b.dataset.revokeWorkflow} 将使所有子 Grant 失效。`,reason=>api(`/api/v2/portal/provenance/${encodeURIComponent(b.dataset.revokeWorkflow)}/revoke`,{method:'POST',body:JSON.stringify({reason})}).then(authorizations)));document.querySelectorAll('[data-revoke-grant]').forEach(b=>b.onclick=()=>confirmOp('撤销 Grant',`撤销 ${b.dataset.revokeGrant}。`,reason=>api(`/api/v2/portal/grants/${encodeURIComponent(b.dataset.revokeGrant)}/revoke`,{method:'POST',body:JSON.stringify({reason})}).then(authorizations)))}
+async function runtime(){const d=await api('/api/v2/portal/runtime');const runtimes=d.runtimes||[],dispatches=d.dispatches||[],jobs=d.hermes_jobs||[];$('#runtime').innerHTML=`<div class="grid"><div class="panel"><div class="panel-head"><h2>Runtime</h2></div>${table([['名称',x=>esc(x.name)],['状态',x=>pill(x.status)],['详情',x=>esc(JSON.stringify(x.details||{}))]],runtimes)}</div><div class="panel"><div class="panel-head"><h2>Hermes Queue / Lease</h2></div>${table([['Job',x=>esc(x.job_id)],['Cell / Profile',x=>`${esc(x.cell_id)} / ${esc(x.profile_id)}`],['Worker',x=>esc(x.assigned_worker_id||'—')],['状态',x=>pill(x.state)],['Lease',x=>esc(x.lease_expires_at||'—')]],jobs)}</div><div class="panel wide"><div class="panel-head"><h2>Dispatch</h2></div>${table([['Dispatch',x=>esc(x.dispatch_id)],['Task',x=>esc(x.task_id)],['Runtime',x=>esc(x.runtime)],['执行 ID',x=>esc(x.runtime_execution_id)],['Principal',x=>esc(x.principal_id)],['状态',x=>pill(x.state)]],dispatches)}</div></div>`}
+async function evidence(){const d=await api('/api/v2/portal/evidence');$('#evidence').innerHTML=`<div class="panel"><div class="panel-head"><h2>Execution Evidence</h2></div>${table([['Execution',x=>esc(x.execution_id)],['Task / Agent',x=>`${esc(x.task_id)}<br>${esc(x.agent_id)}`],['Executor',x=>esc(x.executor)],['状态',x=>pill(x.status)],['进度',x=>`${esc(x.progress_completed)}/${esc(x.progress_total)}`],['Test',x=>pill(x.test_status)],['Commit',x=>esc(x.last_commit||'—')],['授权',x=>esc(x.last_authorization_id||'—')]],d.executions||[])}</div>`}
+async function audit(){const d=await api('/api/v2/portal/audit');const events=(d.events||[]).slice().reverse();$('#audit').innerHTML=`<div class="panel"><div class="panel-head"><h2>统一审计时间线</h2></div><div class="timeline">${events.map(x=>`<div class="event"><strong>${esc(x.action)} · ${pill(x.outcome)}</strong><p>${esc(x.created_at)} · ${esc(x.principal_id)} · ${esc(x.resource_type)}/${esc(x.resource_id)}</p><div class="muted">Trace ${esc(x.trace_id)} · Policy ${esc(x.policy_version)}</div></div>`).join('')||'<div class="empty">暂无审计事件</div>'}</div></div>`}
+async function release(){const d=await api('/api/v2/portal/release');const g=d.gitops||{};$('#release').innerHTML=`<div class="cards">${card('版本',d.version||'—')}${card('Baseline',d.baseline||'—')}${card('发布状态',d.status||'—')}${card('Git 同步',g.sync_status||'unknown')}</div><div class="grid"><div class="panel"><div class="panel-head"><h2>当前 Release</h2></div><div class="kv"><div>Release OID</div><div>${esc(d.release_oid)}</div><div>Branch</div><div>${esc(g.workspace_branch||g.branch||'—')}</div><div>Workspace</div><div>${pill(g.workspace_clean===true?'clean':g.workspace_clean===false?'dirty':'unknown')}</div><div>Local Sync</div><div>${pill(g.local_sync||'unknown')}</div><div>Gitea Sync</div><div>${pill(g.gitea_sync||'unknown')}</div></div></div><div class="panel"><div class="panel-head"><h2>治理操作</h2></div><p class="muted">门户不直接移动 Tag、合并主线或部署生产。以下仅为可发起的 GitOps 请求目录。</p>${(d.operations||[]).map(x=>pill(x)).join('')||'<span class="muted">当前角色只读</span>'}</div><div class="panel wide"><div class="panel-head"><h2>原始 GitOps 状态</h2></div>${json(g)}</div></div>`}
+function confirmOp(title,text,fn){state.confirm=fn;$('#confirmTitle').textContent=title;$('#confirmText').textContent=text;$('#confirmReason').value='';$('#confirmDialog').showModal()}
+$('#taskForm').onsubmit=async e=>{e.preventDefault();clearErr();try{const fd=new FormData(e.target),payload=JSON.parse(fd.get('payload')||'{}');await api('/api/v2/portal/tasks',{method:'POST',body:JSON.stringify({agent_id:fd.get('agent_id'),action:fd.get('action'),idempotency_key:fd.get('idempotency_key'),payload})});$('#taskDialog').close();e.target.reset();await tasks()}catch(e){err(e)}};
+$('#confirmForm').onsubmit=async e=>{e.preventDefault();const fn=state.confirm;$('#confirmDialog').close();state.confirm=null;try{await fn?.($('#confirmReason').value)}catch(e){err(e)}};
+document.querySelectorAll('[data-close]').forEach(b=>b.onclick=()=>document.getElementById(b.dataset.close).close());$('#refresh').onclick=()=>load(state.current);
+identity().catch(err);setInterval(()=>load(state.current),30000);
 </script>
-</body>
-</html>'''
+</body></html>'''
@@ -0,0 +1,543 @@
+"""Portable multi-provider execution plans and aggregate release gates.
+
+A plan is a DAG of executor-neutral stages. Only root stages are declared at
+plan creation. A dependent stage is declared atomically after every dependency
+passes its Truth + notification gate, so its start deadline cannot expire while
+it is legitimately waiting for upstream work.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .executor_protocol import ExecutorProviderRegistry, normalize_executor
+from .external_task_control import ExternalTaskCoordinator
+from .external_task_query import list_records
+from .task_execution_registry import (
+    ExecutionTaskManifest,
+    ExecutionTruthRecord,
+    ExecutionTruthState,
+    required,
+    utc_now,
+)
+
+PLAN_SCHEMA_VERSION = "aios.execution-plan.v2"
+WAITING_DEPENDENCY = "WAITING_DEPENDENCY"
+
+
+@dataclass(frozen=True)
+class ExecutionStageManifest:
+    stage_id: str
+    task_id: str
+    executor_type: str
+    role: str
+    steps: Sequence[str]
+    depends_on: Sequence[str] = ()
+    required_evidence: Sequence[str] = ()
+    notification_events: Sequence[str] = ("STARTED", "SUCCEEDED", "FAILED")
+    owner_notification_ref: str = "AIOS_OWNER_WECHAT_TARGET_REF"
+    start_deadline_seconds: int = 300
+    heartbeat_timeout_seconds: int = 180
+    required: bool = True
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name in ("stage_id", "task_id", "role", "owner_notification_ref"):
+            object.__setattr__(self, name, required(getattr(self, name), name))
+        object.__setattr__(self, "executor_type", normalize_executor(self.executor_type))
+        steps = tuple(required(item, "step") for item in self.steps)
+        if not steps:
+            raise ValueError("execution stage requires at least one step")
+        object.__setattr__(self, "steps", steps)
+        object.__setattr__(
+            self,
+            "depends_on",
+            tuple(sorted({required(item, "depends_on") for item in self.depends_on})),
+        )
+        object.__setattr__(
+            self,
+            "required_evidence",
+            tuple(sorted({required(item, "required_evidence") for item in self.required_evidence})),
+        )
+        object.__setattr__(
+            self,
+            "notification_events",
+            tuple(sorted({required(item, "notification_event") for item in self.notification_events})),
+        )
+        if self.start_deadline_seconds < 1 or self.heartbeat_timeout_seconds < 1:
+            raise ValueError("stage deadlines must be positive")
+        object.__setattr__(
+            self,
+            "metadata",
+            json.loads(json.dumps(dict(self.metadata), ensure_ascii=False, default=str)),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["steps"] = list(self.steps)
+        value["depends_on"] = list(self.depends_on)
+        value["required_evidence"] = list(self.required_evidence)
+        value["notification_events"] = list(self.notification_events)
+        return value
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ExecutionStageManifest":
+        return cls(**dict(value))
+
+
+@dataclass(frozen=True)
+class ExecutionPlanManifest:
+    plan_id: str
+    source_branch: str
+    source_oid: str
+    target_version: str
+    stages: Sequence[ExecutionStageManifest]
+    release_gate_policy: str = "all_required_stages"
+    schema_version: str = PLAN_SCHEMA_VERSION
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name in ("plan_id", "source_branch", "source_oid", "target_version"):
+            object.__setattr__(self, name, required(getattr(self, name), name))
+        if self.schema_version != PLAN_SCHEMA_VERSION:
+            raise ValueError("unsupported execution plan schema")
+        if self.release_gate_policy != "all_required_stages":
+            raise ValueError("unsupported release gate policy")
+        stages = tuple(self.stages)
+        if not stages:
+            raise ValueError("execution plan requires stages")
+        stage_ids = [item.stage_id for item in stages]
+        task_ids = [item.task_id for item in stages]
+        if len(stage_ids) != len(set(stage_ids)):
+            raise ValueError("execution plan stage_id values must be unique")
+        if len(task_ids) != len(set(task_ids)):
+            raise ValueError("execution plan task_id values must be unique")
+        known = set(stage_ids)
+        for stage in stages:
+            unknown = sorted(set(stage.depends_on) - known)
+            if unknown:
+                raise ValueError(f"stage {stage.stage_id} has unknown dependencies: {unknown}")
+            if stage.stage_id in stage.depends_on:
+                raise ValueError("stage cannot depend on itself")
+        self._assert_acyclic(stages)
+        object.__setattr__(self, "stages", stages)
+        object.__setattr__(
+            self,
+            "metadata",
+            json.loads(json.dumps(dict(self.metadata), ensure_ascii=False, default=str)),
+        )
+
+    @staticmethod
+    def _assert_acyclic(stages: Sequence[ExecutionStageManifest]) -> None:
+        dependencies = {item.stage_id: set(item.depends_on) for item in stages}
+        resolved: set[str] = set()
+        while len(resolved) < len(stages):
+            ready = {
+                stage_id
+                for stage_id, deps in dependencies.items()
+                if stage_id not in resolved and deps.issubset(resolved)
+            }
+            if not ready:
+                raise ValueError("execution plan contains a dependency cycle")
+            resolved.update(ready)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "plan_id": self.plan_id,
+            "source_branch": self.source_branch,
+            "source_oid": self.source_oid,
+            "target_version": self.target_version,
+            "release_gate_policy": self.release_gate_policy,
+            "stages": [item.as_dict() for item in self.stages],
+            "metadata": dict(self.metadata),
+        }
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ExecutionPlanManifest":
+        raw = dict(value)
+        raw["stages"] = tuple(
+            ExecutionStageManifest.from_dict(item) for item in raw.get("stages") or ()
+        )
+        return cls(**raw)
+
+    def stage(self, stage_id: str) -> ExecutionStageManifest:
+        normalized = required(stage_id, "stage_id")
+        for stage in self.stages:
+            if stage.stage_id == normalized:
+                return stage
+        raise KeyError(f"execution stage not found: {normalized}")
+
+
+class SQLiteExecutionPlanStore:
+    """Durable plan declarations; stage state remains in Truth Registry."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        with self._connect() as connection:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS execution_plans (
+                    plan_id TEXT PRIMARY KEY,
+                    manifest_json TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                );
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(str(self.path), timeout=30.0)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA synchronous=FULL")
+        return connection
+
+    @staticmethod
+    def _encode(plan: ExecutionPlanManifest) -> str:
+        return json.dumps(
+            plan.as_dict(),
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+    def save(
+        self,
+        plan: ExecutionPlanManifest,
+        *,
+        allow_source_oid_supersession: bool = False,
+    ) -> None:
+        payload = self._encode(plan)
+        now = utc_now()
+        with self._lock, self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            existing = connection.execute(
+                "SELECT manifest_json FROM execution_plans WHERE plan_id = ?",
+                (plan.plan_id,),
+            ).fetchone()
+            if existing is not None:
+                if existing["manifest_json"] != payload:
+                    previous = json.loads(existing["manifest_json"])
+                    replacement = plan.as_dict()
+                    previous_oid = previous.pop("source_oid", None)
+                    replacement_oid = replacement.pop("source_oid", None)
+                    if (
+                        not allow_source_oid_supersession
+                        or previous != replacement
+                        or previous_oid == replacement_oid
+                    ):
+                        connection.rollback()
+                        raise RuntimeError(
+                            "plan_id already exists with another manifest"
+                        )
+                    connection.execute(
+                        "UPDATE execution_plans SET manifest_json = ?, updated_at = ? WHERE plan_id = ?",
+                        (payload, now, plan.plan_id),
+                    )
+                    connection.commit()
+                    return
+                connection.rollback()
+                return
+            connection.execute(
+                "INSERT INTO execution_plans VALUES (?, ?, ?, ?)",
+                (plan.plan_id, payload, now, now),
+            )
+            connection.commit()
+
+    def get(self, plan_id: str) -> ExecutionPlanManifest:
+        with self._lock, self._connect() as connection:
+            row = connection.execute(
+                "SELECT manifest_json FROM execution_plans WHERE plan_id = ?",
+                (required(plan_id, "plan_id"),),
+            ).fetchone()
+        if row is None:
+            raise KeyError("execution plan not found")
+        value = json.loads(row["manifest_json"])
+        if not isinstance(value, Mapping):
+            raise ValueError("stored execution plan is invalid")
+        return ExecutionPlanManifest.from_dict(value)
+
+    def list(self) -> list[ExecutionPlanManifest]:
+        with self._lock, self._connect() as connection:
+            rows = connection.execute(
+                "SELECT manifest_json FROM execution_plans ORDER BY created_at, plan_id"
+            ).fetchall()
+        return [
+            ExecutionPlanManifest.from_dict(json.loads(row["manifest_json"]))
+            for row in rows
+        ]
+
+
+class ExecutionPlanCoordinator:
+    """Declares dependency-ready stages and evaluates aggregate release gates."""
+
+    def __init__(
+        self,
+        *,
+        task_coordinator: ExternalTaskCoordinator,
+        plan_store: SQLiteExecutionPlanStore,
+        providers: ExecutorProviderRegistry,
+    ) -> None:
+        self.task_coordinator = task_coordinator
+        self.plan_store = plan_store
+        self.providers = providers
+
+    @classmethod
+    def from_file(
+        cls,
+        path: str | Path,
+        *,
+        providers: ExecutorProviderRegistry,
+    ) -> "ExecutionPlanCoordinator":
+        return cls(
+            task_coordinator=ExternalTaskCoordinator.from_file(path),
+            plan_store=SQLiteExecutionPlanStore(path),
+            providers=providers,
+        )
+
+    @staticmethod
+    def _task_manifest(
+        plan: ExecutionPlanManifest,
+        stage: ExecutionStageManifest,
+    ) -> ExecutionTaskManifest:
+        return ExecutionTaskManifest(
+            task_id=stage.task_id,
+            executor=stage.executor_type,
+            source_branch=plan.source_branch,
+            source_oid=plan.source_oid,
+            target_version=plan.target_version,
+            steps=stage.steps,
+            start_deadline_seconds=stage.start_deadline_seconds,
+            heartbeat_timeout_seconds=stage.heartbeat_timeout_seconds,
+            required_evidence=stage.required_evidence,
+            notification_events=stage.notification_events,
+            owner_notification_ref=stage.owner_notification_ref,
+            manifest_version="aios.external-task.v2",
+        )
+
+    def _record(self, task_id: str) -> ExecutionTruthRecord | None:
+        try:
+            return self.task_coordinator.registry.get(task_id)
+        except KeyError:
+            return None
+
+    def _declare_stage(
+        self,
+        plan: ExecutionPlanManifest,
+        stage: ExecutionStageManifest,
+    ) -> ExecutionTruthRecord:
+        self.providers.validate_manifest(self._task_manifest(plan, stage))
+        return self.task_coordinator.declare(self._task_manifest(plan, stage))
+
+    def declare(self, plan: ExecutionPlanManifest) -> Mapping[str, Any]:
+        for stage in plan.stages:
+            self.providers.get(stage.executor_type)
+        allow_source_oid_supersession = False
+        try:
+            previous = self.plan_store.get(plan.plan_id)
+        except KeyError:
+            previous = None
+        if previous is not None and previous.source_oid != plan.source_oid:
+            previous_value = previous.as_dict()
+            replacement_value = plan.as_dict()
+            previous_value.pop("source_oid")
+            replacement_value.pop("source_oid")
+            root_records = [
+                self._record(stage.task_id)
+                for stage in previous.stages
+                if not stage.depends_on
+            ]
+            allow_source_oid_supersession = bool(
+                previous_value == replacement_value
+                and root_records
+                and all(
+                    record is not None
+                    and record.state == ExecutionTruthState.NOT_STARTED
+                    for record in root_records
+                )
+            )
+        self.plan_store.save(
+            plan,
+            allow_source_oid_supersession=allow_source_oid_supersession,
+        )
+        for stage in plan.stages:
+            if not stage.depends_on:
+                self._declare_stage(plan, stage)
+        return self.snapshot(plan.plan_id)
+
+    def declare_file(self, path: str | Path) -> Mapping[str, Any]:
+        value = json.loads(Path(path).read_text(encoding="utf-8"))
+        if not isinstance(value, Mapping):
+            raise ValueError("execution plan file must contain a JSON object")
+        return self.declare(ExecutionPlanManifest.from_dict(value))
+
+    def dependency_gate(self, plan_id: str, stage_id: str) -> Mapping[str, Any]:
+        plan = self.plan_store.get(plan_id)
+        stage = plan.stage(stage_id)
+        dependencies: list[Mapping[str, Any]] = []
+        passed = True
+        for dependency_id in stage.depends_on:
+            dependency = plan.stage(dependency_id)
+            record = self._record(dependency.task_id)
+            if record is None:
+                gate: Mapping[str, Any] = {
+                    "task_id": dependency.task_id,
+                    "state": WAITING_DEPENDENCY,
+                    "passed": False,
+                    "release_blocking": True,
+                }
+            else:
+                gate = self.task_coordinator.gate(dependency.task_id)
+            dependencies.append(
+                {
+                    "stage_id": dependency.stage_id,
+                    "task_id": dependency.task_id,
+                    "gate": gate,
+                }
+            )
+            if not gate["passed"]:
+                passed = False
+        return {
+            "plan_id": plan.plan_id,
+            "stage_id": stage.stage_id,
+            "passed": passed,
+            "release_blocking": not passed,
+            "dependencies": dependencies,
+        }
+
+    def activate_ready(self, plan_id: str) -> list[Mapping[str, Any]]:
+        plan = self.plan_store.get(plan_id)
+        activated: list[Mapping[str, Any]] = []
+        for stage in plan.stages:
+            if self._record(stage.task_id) is not None:
+                continue
+            dependency = self.dependency_gate(plan.plan_id, stage.stage_id)
+            if not dependency["passed"]:
+                continue
+            record = self._declare_stage(plan, stage)
+            activated.append(
+                {
+                    "stage_id": stage.stage_id,
+                    "task_id": record.task_id,
+                    "executor_type": stage.executor_type,
+                    "state": record.state.value,
+                }
+            )
+        return activated
+
+    def discover_ready(
+        self,
+        *,
+        plan_id: str,
+        executor_type: str,
+    ) -> list[Mapping[str, Any]]:
+        plan = self.plan_store.get(plan_id)
+        self.activate_ready(plan.plan_id)
+        normalized = normalize_executor(executor_type)
+        records = {
+            item.task_id: item
+            for item in list_records(
+                self.task_coordinator.registry.path,
+                executor=normalized,
+                states=(
+                    ExecutionTruthState.DECLARED.value,
+                    ExecutionTruthState.REGISTERED.value,
+                ),
+            )
+        }
+        ready: list[Mapping[str, Any]] = []
+        for stage in plan.stages:
+            if stage.executor_type != normalized or stage.task_id not in records:
+                continue
+            dependency = self.dependency_gate(plan.plan_id, stage.stage_id)
+            if dependency["passed"]:
+                ready.append(
+                    {
+                        "plan_id": plan.plan_id,
+                        "stage": stage.as_dict(),
+                        "record": records[stage.task_id].as_dict(),
+                    }
+                )
+        return ready
+
+    def snapshot(self, plan_id: str) -> Mapping[str, Any]:
+        plan = self.plan_store.get(plan_id)
+        stages: list[Mapping[str, Any]] = []
+        for stage in plan.stages:
+            record = self._record(stage.task_id)
+            dependency = self.dependency_gate(plan.plan_id, stage.stage_id)
+            if record is None:
+                truth: Mapping[str, Any] = {
+                    "task_id": stage.task_id,
+                    "state": WAITING_DEPENDENCY,
+                    "passed": False,
+                    "release_blocking": True,
+                    "executor_run_id": None,
+                    "executor_id": None,
+                    "current_step": 0,
+                    "total_steps": len(stage.steps),
+                    "evidence": {},
+                    "error": {},
+                    "notifications": [],
+                }
+            else:
+                truth = self.task_coordinator.status(stage.task_id)
+            stages.append(
+                {
+                    "stage": stage.as_dict(),
+                    "dependency_gate": dependency,
+                    "truth": truth,
+                }
+            )
+        return {
+            "manifest": plan.as_dict(),
+            "stages": stages,
+        }
+
+    def gate(self, plan_id: str) -> Mapping[str, Any]:
+        plan = self.plan_store.get(plan_id)
+        self.activate_ready(plan.plan_id)
+        stages: list[Mapping[str, Any]] = []
+        required_passed = True
+        for stage in plan.stages:
+            dependency = self.dependency_gate(plan.plan_id, stage.stage_id)
+            record = self._record(stage.task_id)
+            if record is None:
+                truth_gate: Mapping[str, Any] = {
+                    "task_id": stage.task_id,
+                    "state": WAITING_DEPENDENCY,
+                    "passed": False,
+                    "release_blocking": True,
+                }
+            else:
+                truth_gate = self.task_coordinator.gate(stage.task_id)
+            stage_passed = bool(truth_gate["passed"] and dependency["passed"])
+            if stage.required and not stage_passed:
+                required_passed = False
+            stages.append(
+                {
+                    "stage_id": stage.stage_id,
+                    "task_id": stage.task_id,
+                    "executor_type": stage.executor_type,
+                    "role": stage.role,
+                    "required": stage.required,
+                    "passed": stage_passed,
+                    "truth_gate": truth_gate,
+                    "dependency_gate": dependency,
+                }
+            )
+        return {
+            "plan_id": plan.plan_id,
+            "target_version": plan.target_version,
+            "policy": plan.release_gate_policy,
+            "passed": required_passed,
+            "release_blocking": not required_passed,
+            "stages": stages,
+        }
@@ -0,0 +1,204 @@
+"""Persistent and portable AIOS executor provider catalog.
+
+The catalog contains descriptors only: provider names, protocol/adapter versions,
+trust roles, capabilities and configuration schema identifiers. Credentials,
+endpoints and runtime secrets are intentionally excluded and must be resolved in
+the destination environment.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .executor_protocol import (
+    EXECUTOR_PROTOCOL_VERSION,
+    DescriptorOnlyProvider,
+    ExecutorProvider,
+    ExecutorProviderDescriptor,
+    ExecutorProviderRegistry,
+    default_provider_registry,
+)
+
+CATALOG_SCHEMA_VERSION = "aios.executor.catalog.v1"
+MIGRATION_SCHEMA_VERSION = "aios.executor.migration.v1"
+
+
+def canonical_json_bytes(value: Mapping[str, Any]) -> bytes:
+    return json.dumps(
+        dict(value),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+    ).encode("utf-8")
+
+
+def sha256_payload(value: Mapping[str, Any]) -> str:
+    return hashlib.sha256(canonical_json_bytes(value)).hexdigest()
+
+
+@dataclass(frozen=True)
+class ExecutorCatalogSnapshot:
+    catalog: Mapping[str, Any]
+    catalog_sha256: str
+    path: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "catalog": dict(self.catalog),
+            "catalog_sha256": self.catalog_sha256,
+            "path": self.path,
+        }
+
+
+class FileExecutorCatalogStore:
+    """Atomic file store for provider descriptors and migration packages."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+
+    @staticmethod
+    def _validate_catalog(value: Mapping[str, Any]) -> ExecutorProviderRegistry:
+        if value.get("schema_version") != CATALOG_SCHEMA_VERSION:
+            raise ValueError("unsupported executor catalog schema")
+        if value.get("protocol_version") != EXECUTOR_PROTOCOL_VERSION:
+            raise ValueError("executor catalog protocol mismatch")
+        providers = value.get("providers")
+        if not isinstance(providers, Sequence) or isinstance(providers, (str, bytes)):
+            raise ValueError("executor catalog providers must be an array")
+        return ExecutorProviderRegistry.import_catalog(value)
+
+    def initialize_defaults(self) -> ExecutorCatalogSnapshot:
+        with self._lock:
+            if self.path.exists():
+                return self.load()
+            return self.save(default_provider_registry())
+
+    def load(self) -> ExecutorCatalogSnapshot:
+        with self._lock:
+            value = json.loads(self.path.read_text(encoding="utf-8"))
+        if not isinstance(value, Mapping):
+            raise ValueError("executor catalog must contain a JSON object")
+        registry = self._validate_catalog(value)
+        normalized = registry.export_catalog()
+        return ExecutorCatalogSnapshot(
+            catalog=normalized,
+            catalog_sha256=sha256_payload(normalized),
+            path=str(self.path),
+        )
+
+    def registry(
+        self,
+        *,
+        provider_factories: Mapping[str, ExecutorProvider] | None = None,
+    ) -> ExecutorProviderRegistry:
+        snapshot = self.load()
+        return ExecutorProviderRegistry.import_catalog(
+            snapshot.catalog,
+            provider_factories=provider_factories,
+        )
+
+    def save(self, registry: ExecutorProviderRegistry) -> ExecutorCatalogSnapshot:
+        catalog = registry.export_catalog()
+        self._validate_catalog(catalog)
+        encoded = json.dumps(
+            catalog,
+            ensure_ascii=False,
+            sort_keys=True,
+            indent=2,
+        ) + "\n"
+        with self._lock:
+            temporary = self.path.with_suffix(f".tmp-{os.getpid()}")
+            temporary.write_text(encoded, encoding="utf-8")
+            os.chmod(temporary, 0o640)
+            os.replace(temporary, self.path)
+        return ExecutorCatalogSnapshot(
+            catalog=catalog,
+            catalog_sha256=sha256_payload(catalog),
+            path=str(self.path),
+        )
+
+    def upsert_descriptor(
+        self,
+        descriptor: ExecutorProviderDescriptor,
+    ) -> ExecutorCatalogSnapshot:
+        with self._lock:
+            if self.path.exists():
+                registry = self.registry()
+            else:
+                registry = default_provider_registry()
+            try:
+                registry.register(DescriptorOnlyProvider(descriptor), replace=True)
+            except KeyError:
+                registry.register(DescriptorOnlyProvider(descriptor))
+            return self.save(registry)
+
+    def export_migration_package(
+        self,
+        *,
+        source_environment: str,
+        required_executor_types: Sequence[str] = (),
+    ) -> Mapping[str, Any]:
+        snapshot = self.load()
+        registry = ExecutorProviderRegistry.import_catalog(snapshot.catalog)
+        required = tuple(sorted({str(item).strip().lower() for item in required_executor_types if str(item).strip()}))
+        if required:
+            available = {item.executor_type for item in registry.list_descriptors()}
+            missing = sorted(set(required) - available)
+            if missing:
+                raise ValueError(f"migration package is missing providers: {missing}")
+        package = {
+            "schema_version": MIGRATION_SCHEMA_VERSION,
+            "source_environment": str(source_environment or "").strip(),
+            "catalog": snapshot.catalog,
+            "catalog_sha256": snapshot.catalog_sha256,
+            "required_executor_types": list(required),
+            "secret_values_included": False,
+        }
+        if not package["source_environment"]:
+            raise ValueError("source_environment is required")
+        return {
+            **package,
+            "package_sha256": sha256_payload(package),
+        }
+
+    @classmethod
+    def import_migration_package(
+        cls,
+        value: Mapping[str, Any],
+        *,
+        destination_path: str | Path,
+        destination_environment: str,
+        provider_factories: Mapping[str, ExecutorProvider] | None = None,
+    ) -> ExecutorCatalogSnapshot:
+        if value.get("schema_version") != MIGRATION_SCHEMA_VERSION:
+            raise ValueError("unsupported executor migration schema")
+        if value.get("secret_values_included") is not False:
+            raise ValueError("executor migration package must not contain secrets")
+        package_without_hash = {key: item for key, item in value.items() if key != "package_sha256"}
+        if sha256_payload(package_without_hash) != value.get("package_sha256"):
+            raise ValueError("executor migration package hash mismatch")
+        catalog = value.get("catalog")
+        if not isinstance(catalog, Mapping):
+            raise ValueError("executor migration package has no catalog")
+        if sha256_payload(catalog) != value.get("catalog_sha256"):
+            raise ValueError("executor catalog hash mismatch")
+        registry = ExecutorProviderRegistry.import_catalog(
+            catalog,
+            provider_factories=provider_factories,
+        )
+        required = tuple(value.get("required_executor_types") or ())
+        available = {item.executor_type for item in registry.list_descriptors()}
+        missing = sorted(set(required) - available)
+        if missing:
+            raise ValueError(f"destination provider factories are missing: {missing}")
+        if not str(destination_environment or "").strip():
+            raise ValueError("destination_environment is required")
+        return cls(destination_path).save(registry)
@@ -0,0 +1,441 @@
+"""Versioned, extensible executor protocol for AIOS external tasks.
+
+The core lifecycle is executor-neutral. OpenClaw, Hermes, Codex and the scoped
+ChatGPT supervisor are built-in
+providers, not hard-coded protocol branches. Future providers register a
+versioned descriptor and use the same Truth Registry, evidence, notification
+and release-gate mechanisms without modifying the lifecycle state machine.
+"""
+from __future__ import annotations
+
+import json
+import re
+import threading
+from dataclasses import asdict, dataclass, field
+from typing import Any, Mapping, Protocol, Sequence
+
+from .external_task_control import ExternalTaskCoordinator
+from .task_execution_registry import ExecutionTaskManifest, ExecutionTruthRecord
+
+EXECUTOR_PROTOCOL_VERSION = "aios.executor.v1"
+_PROVIDER_NAME = re.compile(r"^[a-z][a-z0-9._-]{1,63}$")
+_VERSION = re.compile(r"^[0-9]+(?:\.[0-9]+){0,2}(?:[-+][A-Za-z0-9._-]+)?$")
+DISCOVERABLE_STATES: Sequence[str] = ("DECLARED", "REGISTERED")
+
+
+def normalize_executor(value: str) -> str:
+    normalized = str(value or "").strip().lower()
+    if not _PROVIDER_NAME.fullmatch(normalized):
+        raise ValueError("executor type must be a lowercase provider identifier")
+    return normalized
+
+
+def _major(version: str) -> int:
+    normalized = str(version or "").strip()
+    if not _VERSION.fullmatch(normalized):
+        raise ValueError(f"invalid version: {version}")
+    return int(normalized.split(".", 1)[0])
+
+
+@dataclass(frozen=True)
+class ExecutorProviderDescriptor:
+    """Portable provider metadata stored without credentials or runtime secrets."""
+
+    executor_type: str
+    adapter_version: str
+    protocol_version: str = EXECUTOR_PROTOCOL_VERSION
+    trust_roles: Sequence[str] = ()
+    capabilities: Sequence[str] = ()
+    configuration_schema: str = "aios.executor.config.v1"
+    portable: bool = True
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "executor_type", normalize_executor(self.executor_type))
+        adapter_version = str(self.adapter_version or "").strip()
+        if not _VERSION.fullmatch(adapter_version):
+            raise ValueError("adapter_version must be version-like")
+        object.__setattr__(self, "adapter_version", adapter_version)
+        protocol_version = str(self.protocol_version or "").strip()
+        if not protocol_version.startswith("aios.executor.v"):
+            raise ValueError("unsupported executor protocol namespace")
+        int(protocol_version.rsplit("v", 1)[1])
+        object.__setattr__(self, "protocol_version", protocol_version)
+        roles = tuple(sorted({str(item).strip() for item in self.trust_roles if str(item).strip()}))
+        if not roles:
+            raise ValueError("provider must declare at least one trust role")
+        capabilities = tuple(
+            sorted({str(item).strip() for item in self.capabilities if str(item).strip()})
+        )
+        object.__setattr__(self, "trust_roles", roles)
+        object.__setattr__(self, "capabilities", capabilities)
+        object.__setattr__(
+            self,
+            "configuration_schema",
+            str(self.configuration_schema or "").strip(),
+        )
+        object.__setattr__(
+            self,
+            "metadata",
+            json.loads(json.dumps(dict(self.metadata), ensure_ascii=False, default=str)),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["trust_roles"] = list(self.trust_roles)
+        value["capabilities"] = list(self.capabilities)
+        return value
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ExecutorProviderDescriptor":
+        return cls(**dict(value))
+
+    def protocol_compatible_with(self, other: "ExecutorProviderDescriptor") -> bool:
+        return (
+            self.executor_type == other.executor_type
+            and self.protocol_version == other.protocol_version
+            and _major(self.adapter_version) == _major(other.adapter_version)
+        )
+
+
+class ExternalExecutorAdapter(Protocol):
+    """Runtime-specific implementation behind the common lifecycle."""
+
+    descriptor: ExecutorProviderDescriptor
+
+    def discover(self) -> Sequence[ExecutionTruthRecord]: ...
+    def execute(self, manifest: ExecutionTaskManifest) -> Mapping[str, Any]: ...
+    def notify_owner(self, payload: Mapping[str, Any]) -> str: ...
+
+
+class ExecutorProvider(Protocol):
+    descriptor: ExecutorProviderDescriptor
+
+    def validate_manifest(self, manifest: ExecutionTaskManifest) -> None: ...
+    def build_adapter(self, configuration: Mapping[str, Any]) -> ExternalExecutorAdapter: ...
+
+
+class DescriptorOnlyProvider:
+    """Default provider used when lifecycle integration is supplied externally."""
+
+    def __init__(self, descriptor: ExecutorProviderDescriptor) -> None:
+        self.descriptor = descriptor
+
+    def validate_manifest(self, manifest: ExecutionTaskManifest) -> None:
+        if normalize_executor(manifest.executor) != self.descriptor.executor_type:
+            raise ValueError("manifest executor does not match provider")
+
+    def build_adapter(self, configuration: Mapping[str, Any]) -> ExternalExecutorAdapter:
+        raise RuntimeError(
+            f"provider {self.descriptor.executor_type} requires an external adapter factory"
+        )
+
+
+class ExecutorProviderRegistry:
+    """Thread-safe registry supporting runtime registration and catalog migration."""
+
+    def __init__(self, providers: Sequence[ExecutorProvider] = ()) -> None:
+        self._lock = threading.RLock()
+        self._providers: dict[str, ExecutorProvider] = {}
+        for provider in providers:
+            self.register(provider)
+
+    def register(self, provider: ExecutorProvider, *, replace: bool = False) -> None:
+        descriptor = provider.descriptor
+        key = normalize_executor(descriptor.executor_type)
+        with self._lock:
+            current = self._providers.get(key)
+            if current is not None and not replace:
+                raise ValueError(f"executor provider already registered: {key}")
+            if current is not None and not descriptor.protocol_compatible_with(
+                current.descriptor
+            ):
+                raise ValueError(
+                    f"replacement provider is incompatible with registered provider: {key}"
+                )
+            self._providers[key] = provider
+
+    def unregister(self, executor_type: str) -> ExecutorProvider:
+        key = normalize_executor(executor_type)
+        with self._lock:
+            try:
+                return self._providers.pop(key)
+            except KeyError as exc:
+                raise KeyError(f"executor provider is not registered: {key}") from exc
+
+    def get(self, executor_type: str) -> ExecutorProvider:
+        key = normalize_executor(executor_type)
+        with self._lock:
+            provider = self._providers.get(key)
+        if provider is None:
+            raise KeyError(f"executor provider is not registered: {key}")
+        return provider
+
+    def descriptor(self, executor_type: str) -> ExecutorProviderDescriptor:
+        return self.get(executor_type).descriptor
+
+    def validate_manifest(self, manifest: ExecutionTaskManifest) -> None:
+        self.get(manifest.executor).validate_manifest(manifest)
+
+    def trusted(
+        self,
+        *,
+        executor_type: str,
+        roles: Sequence[str],
+        platform_admin: bool = False,
+    ) -> bool:
+        if platform_admin or "platform_admin" in set(roles):
+            return True
+        descriptor = self.descriptor(executor_type)
+        return bool(set(descriptor.trust_roles).intersection(set(roles)))
+
+    def list_descriptors(self) -> tuple[ExecutorProviderDescriptor, ...]:
+        with self._lock:
+            return tuple(
+                self._providers[key].descriptor for key in sorted(self._providers)
+            )
+
+    def export_catalog(self) -> Mapping[str, Any]:
+        return {
+            "schema_version": "aios.executor.catalog.v1",
+            "protocol_version": EXECUTOR_PROTOCOL_VERSION,
+            "providers": [item.as_dict() for item in self.list_descriptors()],
+        }
+
+    @classmethod
+    def import_catalog(
+        cls,
+        value: Mapping[str, Any],
+        *,
+        provider_factories: Mapping[str, ExecutorProvider] | None = None,
+    ) -> "ExecutorProviderRegistry":
+        if value.get("schema_version") != "aios.executor.catalog.v1":
+            raise ValueError("unsupported executor catalog schema")
+        if value.get("protocol_version") != EXECUTOR_PROTOCOL_VERSION:
+            raise ValueError("executor catalog protocol mismatch")
+        factories = dict(provider_factories or {})
+        providers: list[ExecutorProvider] = []
+        for raw in value.get("providers") or ():
+            descriptor = ExecutorProviderDescriptor.from_dict(raw)
+            provider = factories.get(descriptor.executor_type)
+            if provider is not None:
+                if not provider.descriptor.protocol_compatible_with(descriptor):
+                    raise ValueError(
+                        f"provider factory does not match imported descriptor: {descriptor.executor_type}"
+                    )
+                providers.append(provider)
+            else:
+                providers.append(DescriptorOnlyProvider(descriptor))
+        return cls(providers)
+
+
+BUILTIN_PROVIDER_DESCRIPTORS: Sequence[ExecutorProviderDescriptor] = (
+    ExecutorProviderDescriptor(
+        executor_type="openclaw",
+        adapter_version="2.1.0",
+        trust_roles=("runtime", "openclaw_executor"),
+        capabilities=(
+            "deploy",
+            "http_runtime",
+            "owner_notification",
+            "healthcheck",
+            "rollback",
+        ),
+        configuration_schema="aios.executor.openclaw.config.v1",
+        metadata={"official": True},
+    ),
+    ExecutorProviderDescriptor(
+        executor_type="hermes",
+        adapter_version="2.1.0",
+        trust_roles=("runtime", "hermes_executor"),
+        capabilities=(
+            "queue",
+            "lease",
+            "worker",
+            "runtime_validation",
+            "restart_recovery",
+        ),
+        configuration_schema="aios.executor.hermes.config.v1",
+        metadata={"official": True},
+    ),
+    ExecutorProviderDescriptor(
+        executor_type="codex",
+        adapter_version="2.1.0",
+        trust_roles=("codex", "codex_executor"),
+        capabilities=("code", "test", "docs", "gitops_patch", "security_review"),
+        configuration_schema="aios.executor.codex.config.v1",
+        metadata={"official": True},
+    ),
+    ExecutorProviderDescriptor(
+        executor_type="chatgpt-supervisor",
+        adapter_version="2.1.0",
+        trust_roles=("chatgpt_supervisor",),
+        capabilities=(
+            "acceptance",
+            "deploy",
+            "evidence",
+            "healthcheck",
+            "rollback",
+            "wechat_simulation",
+        ),
+        configuration_schema="aios.executor.chatgpt-supervisor.config.v1",
+        metadata={"official": True, "production_mutation_allowed": False},
+    ),
+)
+
+
+def default_provider_registry() -> ExecutorProviderRegistry:
+    return ExecutorProviderRegistry(
+        [DescriptorOnlyProvider(item) for item in BUILTIN_PROVIDER_DESCRIPTORS]
+    )
+
+
+def trusted_for_executor(
+    *,
+    executor: str,
+    roles: Sequence[str],
+    platform_admin: bool = False,
+    registry: ExecutorProviderRegistry | None = None,
+) -> bool:
+    return (registry or default_provider_registry()).trusted(
+        executor_type=executor,
+        roles=roles,
+        platform_admin=platform_admin,
+    )
+
+
+@dataclass(frozen=True)
+class ExecutorIdentity:
+    executor_type: str
+    executor_id: str
+    executor_run_id: str
+    protocol_version: str = EXECUTOR_PROTOCOL_VERSION
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "executor_type", normalize_executor(self.executor_type))
+        for name in ("executor_id", "executor_run_id"):
+            value = str(getattr(self, name) or "").strip()
+            if not value:
+                raise ValueError(f"{name} is required")
+            object.__setattr__(self, name, value)
+        if self.protocol_version != EXECUTOR_PROTOCOL_VERSION:
+            raise ValueError("executor identity protocol mismatch")
+
+
+class ExecutorLifecycleSession:
+    """Executor-neutral lifecycle facade used by every registered provider."""
+
+    def __init__(
+        self,
+        coordinator: ExternalTaskCoordinator,
+        identity: ExecutorIdentity,
+        *,
+        registry: ExecutorProviderRegistry | None = None,
+    ) -> None:
+        self.coordinator = coordinator
+        self.identity = identity
+        self.registry = registry or default_provider_registry()
+        self.registry.get(identity.executor_type)
+
+    def _assert_manifest(self, task_id: str) -> ExecutionTaskManifest:
+        record = self.coordinator.registry.get(task_id)
+        manifest = record.manifest
+        self.registry.validate_manifest(manifest)
+        if normalize_executor(manifest.executor) != self.identity.executor_type:
+            raise PermissionError(
+                f"task executor is {manifest.executor}, not {self.identity.executor_type}"
+            )
+        return manifest
+
+    def register(self, task_id: str) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.register(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+        )
+
+    def retry_not_started(self, task_id: str) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.retry_not_started(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+        )
+
+    def claim(self, task_id: str) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.claim(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+            executor_id=self.identity.executor_id,
+        )
+
+    def start(self, task_id: str) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.start(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+            executor_id=self.identity.executor_id,
+        )
+
+    def heartbeat(self, task_id: str, *, current_step: int) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.heartbeat(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+            executor_id=self.identity.executor_id,
+            current_step=current_step,
+        )
+
+    def succeed(
+        self,
+        task_id: str,
+        *,
+        evidence: Mapping[str, str],
+    ) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.succeed(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+            executor_id=self.identity.executor_id,
+            evidence=evidence,
+        )
+
+    def fail(
+        self,
+        task_id: str,
+        *,
+        error: Mapping[str, Any],
+        evidence: Mapping[str, str] | None = None,
+    ) -> ExecutionTruthRecord:
+        self._assert_manifest(task_id)
+        return self.coordinator.fail(
+            task_id,
+            executor_run_id=self.identity.executor_run_id,
+            executor_id=self.identity.executor_id,
+            error=error,
+            evidence=evidence,
+        )
+
+
+class OpenClawExecutorSession(ExecutorLifecycleSession):
+    def __init__(self, coordinator: ExternalTaskCoordinator, *, executor_id: str, executor_run_id: str) -> None:
+        super().__init__(
+            coordinator,
+            ExecutorIdentity("openclaw", executor_id, executor_run_id),
+        )
+
+
+class HermesExecutorSession(ExecutorLifecycleSession):
+    def __init__(self, coordinator: ExternalTaskCoordinator, *, executor_id: str, executor_run_id: str) -> None:
+        super().__init__(
+            coordinator,
+            ExecutorIdentity("hermes", executor_id, executor_run_id),
+        )
+
+
+class CodexExecutorSession(ExecutorLifecycleSession):
+    def __init__(self, coordinator: ExternalTaskCoordinator, *, executor_id: str, executor_run_id: str) -> None:
+        super().__init__(
+            coordinator,
+            ExecutorIdentity("codex", executor_id, executor_run_id),
+        )
@@ -0,0 +1,313 @@
+"""Provider-neutral worker runtime for AIOS external executors.
+
+Providers implement only step execution and notification delivery. Discovery,
+dependency gates, lifecycle truth, heartbeat, evidence validation and durable
+notification acknowledgement are identical for every current and future
+executor Provider.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, Sequence
+
+from .execution_plan import ExecutionPlanCoordinator, ExecutionStageManifest
+from .executor_protocol import (
+    ExecutorIdentity,
+    ExecutorLifecycleSession,
+    ExecutorProviderRegistry,
+    normalize_executor,
+)
+from .external_task_control import ExternalTaskCoordinator, NotificationRecord
+from .task_execution_registry import ExecutionTruthState
+
+
+class StepRunner(Protocol):
+    def run_step(
+        self,
+        *,
+        plan_id: str,
+        stage: ExecutionStageManifest,
+        step: str,
+        step_number: int,
+        executor_id: str,
+        executor_run_id: str,
+    ) -> Mapping[str, str]: ...
+
+
+class NotificationSender(Protocol):
+    def send(self, notification: NotificationRecord) -> str: ...
+
+
+@dataclass(frozen=True)
+class StageRunResult:
+    plan_id: str
+    stage_id: str
+    task_id: str
+    executor_type: str
+    executor_id: str
+    executor_run_id: str
+    state: str
+    evidence: Mapping[str, str] = field(default_factory=dict)
+    error: Mapping[str, Any] = field(default_factory=dict)
+    delivered_notifications: Sequence[str] = ()
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "plan_id": self.plan_id,
+            "stage_id": self.stage_id,
+            "task_id": self.task_id,
+            "executor_type": self.executor_type,
+            "executor_id": self.executor_id,
+            "executor_run_id": self.executor_run_id,
+            "state": self.state,
+            "evidence": dict(self.evidence),
+            "error": dict(self.error),
+            "delivered_notifications": list(self.delivered_notifications),
+        }
+
+
+class UnifiedExecutorWorker:
+    """Dependency-aware worker shared by every registered Provider."""
+
+    def __init__(
+        self,
+        *,
+        plan_coordinator: ExecutionPlanCoordinator,
+        task_coordinator: ExternalTaskCoordinator,
+        providers: ExecutorProviderRegistry,
+        executor_type: str,
+        executor_id: str,
+        step_runner: StepRunner,
+        notification_sender: NotificationSender,
+    ) -> None:
+        self.plan_coordinator = plan_coordinator
+        self.task_coordinator = task_coordinator
+        self.providers = providers
+        self.executor_type = normalize_executor(executor_type)
+        self.executor_id = str(executor_id or "").strip()
+        if not self.executor_id:
+            raise ValueError("executor_id is required")
+        self.providers.get(self.executor_type)
+        self.step_runner = step_runner
+        self.notification_sender = notification_sender
+
+    def _session(self, executor_run_id: str) -> ExecutorLifecycleSession:
+        return ExecutorLifecycleSession(
+            self.task_coordinator,
+            ExecutorIdentity(
+                executor_type=self.executor_type,
+                executor_id=self.executor_id,
+                executor_run_id=executor_run_id,
+            ),
+            registry=self.providers,
+        )
+
+    def _notification_candidates(self, task_id: str) -> tuple[NotificationRecord, ...]:
+        """Return idempotent delivery candidates, including prior failures.
+
+        The outbox has a unique ``(task_id, event_type)`` key. Retrying therefore
+        reuses the same notification ID and cannot create duplicate STARTED or
+        SUCCEEDED events. A later successful acknowledgement replaces FAILED
+        with DELIVERED and records the receipt hash.
+        """
+        candidates: dict[str, NotificationRecord] = {}
+        for status in ("PENDING", "FAILED"):
+            for item in self.task_coordinator.notifications.list(
+                task_id=task_id,
+                status=status,
+            ):
+                candidates[item.notification_id] = item
+        return tuple(
+            candidates[key]
+            for key in sorted(
+                candidates,
+                key=lambda item: (
+                    candidates[item].created_at,
+                    candidates[item].notification_id,
+                ),
+            )
+        )
+
+    def _deliver_notifications(self, task_id: str) -> tuple[str, ...]:
+        delivered: list[str] = []
+        for item in self._notification_candidates(task_id):
+            try:
+                receipt = self.notification_sender.send(item)
+                acknowledged = self.task_coordinator.notifications.acknowledge(
+                    item.notification_id,
+                    receipt_sha256=receipt,
+                )
+                delivered.append(acknowledged.event_type)
+            except Exception as exc:
+                self.task_coordinator.notifications.fail(
+                    item.notification_id,
+                    error=f"{type(exc).__name__}: {exc}",
+                )
+        return tuple(sorted(set(delivered)))
+
+    def retry_failed_notifications(self, *, task_id: str) -> tuple[str, ...]:
+        """Retry failed owner notifications without changing task truth."""
+        return self._deliver_notifications(task_id)
+
+    def run_ready(
+        self,
+        *,
+        plan_id: str,
+        max_stages: int = 1,
+    ) -> list[StageRunResult]:
+        if max_stages < 1:
+            raise ValueError("max_stages must be positive")
+        ready = self.plan_coordinator.discover_ready(
+            plan_id=plan_id,
+            executor_type=self.executor_type,
+        )[:max_stages]
+        return [
+            self.run_stage(
+                plan_id=plan_id,
+                stage_id=item["stage"]["stage_id"],
+            )
+            for item in ready
+        ]
+
+    def run_stage(
+        self,
+        *,
+        plan_id: str,
+        stage_id: str,
+        executor_run_id: str | None = None,
+    ) -> StageRunResult:
+        plan = self.plan_coordinator.plan_store.get(plan_id)
+        stage = plan.stage(stage_id)
+        if stage.executor_type != self.executor_type:
+            raise PermissionError(
+                f"stage executor is {stage.executor_type}, not {self.executor_type}"
+            )
+        dependency = self.plan_coordinator.dependency_gate(plan_id, stage_id)
+        if not dependency["passed"]:
+            raise RuntimeError("stage dependencies are not satisfied")
+
+        run_id = executor_run_id or f"{self.executor_type}_run_{uuid.uuid4().hex}"
+        session = self._session(run_id)
+        record = self.task_coordinator.registry.get(stage.task_id)
+        evidence: dict[str, str] = dict(record.evidence)
+        delivered: list[str] = []
+        try:
+            if record.state == ExecutionTruthState.DECLARED:
+                record = session.register(stage.task_id)
+            if record.state == ExecutionTruthState.REGISTERED:
+                record = session.claim(stage.task_id)
+            if record.state == ExecutionTruthState.CLAIMED:
+                record = session.start(stage.task_id)
+                delivered.extend(self._deliver_notifications(stage.task_id))
+            if record.state != ExecutionTruthState.RUNNING:
+                raise RuntimeError(
+                    f"stage cannot execute from state {record.state.value}"
+                )
+
+            # Re-running the current step is intentional: Provider steps must be
+            # idempotent and a crash between side effect and heartbeat cannot be
+            # safely interpreted as completed work.
+            start_step = max(1, record.current_step)
+            for number, step in enumerate(stage.steps, start=1):
+                if number < start_step:
+                    continue
+                produced = self.step_runner.run_step(
+                    plan_id=plan_id,
+                    stage=stage,
+                    step=step,
+                    step_number=number,
+                    executor_id=self.executor_id,
+                    executor_run_id=run_id,
+                )
+                if not isinstance(produced, Mapping):
+                    raise TypeError("step runner must return an evidence mapping")
+                evidence.update(
+                    {
+                        str(key).strip(): str(value).strip().lower()
+                        for key, value in produced.items()
+                    }
+                )
+                record = session.heartbeat(stage.task_id, current_step=number)
+
+            record = session.succeed(stage.task_id, evidence=evidence)
+            delivered.extend(self._deliver_notifications(stage.task_id))
+            return StageRunResult(
+                plan_id=plan_id,
+                stage_id=stage.stage_id,
+                task_id=stage.task_id,
+                executor_type=self.executor_type,
+                executor_id=self.executor_id,
+                executor_run_id=run_id,
+                state=record.state.value,
+                evidence=dict(record.evidence),
+                delivered_notifications=tuple(sorted(set(delivered))),
+            )
+        except Exception as exc:
+            current = self.task_coordinator.registry.get(stage.task_id)
+            if current.state in {
+                ExecutionTruthState.REGISTERED,
+                ExecutionTruthState.CLAIMED,
+                ExecutionTruthState.RUNNING,
+            }:
+                current = session.fail(
+                    stage.task_id,
+                    error={
+                        "code": "executor_stage_failed",
+                        "error_type": type(exc).__name__,
+                        "message": str(exc),
+                    },
+                    evidence=evidence or None,
+                )
+            delivered.extend(self._deliver_notifications(stage.task_id))
+            return StageRunResult(
+                plan_id=plan_id,
+                stage_id=stage.stage_id,
+                task_id=stage.task_id,
+                executor_type=self.executor_type,
+                executor_id=self.executor_id,
+                executor_run_id=run_id,
+                state=current.state.value,
+                evidence=dict(current.evidence),
+                error=dict(current.error),
+                delivered_notifications=tuple(sorted(set(delivered))),
+            )
+
+
+class JsonEvidenceStepRunner:
+    """Adapter for handlers returning evidence-name to SHA256 mappings."""
+
+    def __init__(self, handler) -> None:
+        self.handler = handler
+
+    def run_step(self, **values: Any) -> Mapping[str, str]:
+        result = self.handler(**values)
+        if not isinstance(result, Mapping):
+            raise TypeError("step handler must return a mapping")
+        return {str(key): str(value) for key, value in result.items()}
+
+
+class JsonReceiptNotificationSender:
+    """Adapter for senders returning a SHA256 or receipt JSON object."""
+
+    def __init__(self, sender) -> None:
+        self.sender = sender
+
+    def send(self, notification: NotificationRecord) -> str:
+        result = self.sender(notification.as_dict())
+        if isinstance(result, str):
+            return result
+        if not isinstance(result, Mapping):
+            raise TypeError(
+                "notification sender must return SHA256 or a receipt object"
+            )
+        encoded = json.dumps(
+            dict(result),
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+            default=str,
+        ).encode("utf-8")
+        return hashlib.sha256(encoded).hexdigest()
@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""CLI for durable external-task truth and notification receipts.
+
+The CLI is suitable for OpenClaw workers, systemd jobs and release gates. It
+never infers execution from the presence of a manifest: each lifecycle action
+must be recorded explicitly in the shared SQLite registry.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .external_task_control import ExternalTaskCoordinator
+from .external_task_query import list_records
+
+
+def _json_mapping(value: str | None, path: str | None) -> Mapping[str, Any]:
+    if value and path:
+        raise ValueError("inline JSON and JSON file are mutually exclusive")
+    if path:
+        parsed = json.loads(Path(path).read_text(encoding="utf-8"))
+    else:
+        parsed = json.loads(value or "{}")
+    if not isinstance(parsed, Mapping):
+        raise ValueError("JSON value must be an object")
+    return dict(parsed)
+
+
+def _coordinator(args: argparse.Namespace) -> ExternalTaskCoordinator:
+    return ExternalTaskCoordinator.from_file(args.store_file)
+
+
+def _print(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, default=str))
+
+
+def cmd_declare(args: argparse.Namespace) -> int:
+    record = _coordinator(args).declare_file(args.manifest)
+    _print(record.as_dict())
+    return 0
+
+
+def cmd_discover(args: argparse.Namespace) -> int:
+    records = list_records(
+        args.store_file,
+        executor=args.executor,
+        states=tuple(args.state or ()),
+    )
+    _print({"count": len(records), "items": [item.as_dict() for item in records]})
+    return 0
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    _print(_coordinator(args).register(args.task_id, executor_run_id=args.executor_run_id).as_dict())
+    return 0
+
+
+def cmd_claim(args: argparse.Namespace) -> int:
+    _print(
+        _coordinator(args).claim(
+            args.task_id,
+            executor_run_id=args.executor_run_id,
+            executor_id=args.executor_id,
+        ).as_dict()
+    )
+    return 0
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    _print(
+        _coordinator(args).start(
+            args.task_id,
+            executor_run_id=args.executor_run_id,
+            executor_id=args.executor_id,
+        ).as_dict()
+    )
+    return 0
+
+
+def cmd_heartbeat(args: argparse.Namespace) -> int:
+    _print(
+        _coordinator(args).heartbeat(
+            args.task_id,
+            executor_run_id=args.executor_run_id,
+            executor_id=args.executor_id,
+            current_step=args.current_step,
+        ).as_dict()
+    )
+    return 0
+
+
+def cmd_succeed(args: argparse.Namespace) -> int:
+    evidence = _json_mapping(args.evidence_json, args.evidence_file)
+    _print(
+        _coordinator(args).succeed(
+            args.task_id,
+            executor_run_id=args.executor_run_id,
+            executor_id=args.executor_id,
+            evidence={str(key): str(value) for key, value in evidence.items()},
+        ).as_dict()
+    )
+    return 0
+
+
+def cmd_fail(args: argparse.Namespace) -> int:
+    error = _json_mapping(args.error_json, args.error_file)
+    evidence = None
+    if args.evidence_json or args.evidence_file:
+        evidence_value = _json_mapping(args.evidence_json, args.evidence_file)
+        evidence = {str(key): str(value) for key, value in evidence_value.items()}
+    _print(
+        _coordinator(args).fail(
+            args.task_id,
+            executor_run_id=args.executor_run_id,
+            executor_id=args.executor_id,
+            error=error,
+            evidence=evidence,
+        ).as_dict()
+    )
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    _print(_coordinator(args).status(args.task_id))
+    return 0
+
+
+def cmd_gate(args: argparse.Namespace) -> int:
+    value = _coordinator(args).gate(args.task_id)
+    _print(value)
+    return 0 if value["passed"] else 3
+
+
+def cmd_notifications(args: argparse.Namespace) -> int:
+    items = _coordinator(args).notifications.list(task_id=args.task_id, status=args.status)
+    _print({"count": len(items), "items": [item.as_dict() for item in items]})
+    return 0
+
+
+def cmd_ack(args: argparse.Namespace) -> int:
+    _print(
+        _coordinator(args).notifications.acknowledge(
+            args.notification_id,
+            receipt_sha256=args.receipt_sha256,
+        ).as_dict()
+    )
+    return 0
+
+
+def common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--store-file",
+        default=os.getenv(
+            "AIOS_EXTERNAL_TASK_STORE_FILE",
+            "/var/lib/aios-v2/external-task-truth.sqlite3",
+        ),
+    )
+
+
+def lifecycle(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--task-id", required=True)
+    parser.add_argument("--executor-run-id", required=True)
+    parser.add_argument("--executor-id", required=True)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="AIOS external task truth CLI")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    declare = commands.add_parser("declare")
+    common(declare)
+    declare.add_argument("--manifest", required=True)
+    declare.set_defaults(handler=cmd_declare)
+
+    discover = commands.add_parser("discover")
+    common(discover)
+    discover.add_argument("--executor", default="openclaw")
+    discover.add_argument("--state", action="append")
+    discover.set_defaults(handler=cmd_discover)
+
+    register = commands.add_parser("register")
+    common(register)
+    register.add_argument("--task-id", required=True)
+    register.add_argument("--executor-run-id", required=True)
+    register.set_defaults(handler=cmd_register)
+
+    claim = commands.add_parser("claim")
+    common(claim)
+    lifecycle(claim)
+    claim.set_defaults(handler=cmd_claim)
+
+    start = commands.add_parser("start")
+    common(start)
+    lifecycle(start)
+    start.set_defaults(handler=cmd_start)
+
+    heartbeat = commands.add_parser("heartbeat")
+    common(heartbeat)
+    lifecycle(heartbeat)
+    heartbeat.add_argument("--current-step", type=int, required=True)
+    heartbeat.set_defaults(handler=cmd_heartbeat)
+
+    succeed = commands.add_parser("succeed")
+    common(succeed)
+    lifecycle(succeed)
+    evidence = succeed.add_mutually_exclusive_group(required=True)
+    evidence.add_argument("--evidence-json")
+    evidence.add_argument("--evidence-file")
+    succeed.set_defaults(handler=cmd_succeed)
+
+    fail = commands.add_parser("fail")
+    common(fail)
+    lifecycle(fail)
+    error = fail.add_mutually_exclusive_group(required=True)
+    error.add_argument("--error-json")
+    error.add_argument("--error-file")
+    fail_evidence = fail.add_mutually_exclusive_group()
+    fail_evidence.add_argument("--evidence-json")
+    fail_evidence.add_argument("--evidence-file")
+    fail.set_defaults(handler=cmd_fail)
+
+    status = commands.add_parser("status")
+    common(status)
+    status.add_argument("--task-id", required=True)
+    status.set_defaults(handler=cmd_status)
+
+    gate = commands.add_parser("gate")
+    common(gate)
+    gate.add_argument("--task-id", required=True)
+    gate.set_defaults(handler=cmd_gate)
+
+    notifications = commands.add_parser("notifications")
+    common(notifications)
+    notifications.add_argument("--task-id")
+    notifications.add_argument("--status")
+    notifications.set_defaults(handler=cmd_notifications)
+
+    ack = commands.add_parser("ack-notification")
+    common(ack)
+    ack.add_argument("--notification-id", required=True)
+    ack.add_argument("--receipt-sha256", required=True)
+    ack.set_defaults(handler=cmd_ack)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.handler(args))
+    except Exception as exc:
+        print(
+            json.dumps(
+                {"status": "error", "error": type(exc).__name__, "message": str(exc)},
+                ensure_ascii=False,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,420 @@
+"""External executor coordination, notification outbox and release truth gate.
+
+OpenClaw/Codex task declarations are not execution evidence. This module wraps
+``SQLiteExecutionTruthRegistry`` with a durable notification outbox. A successful
+release gate requires both terminal task evidence and acknowledged STARTED /
+SUCCEEDED owner notifications when those events are required by the manifest.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sqlite3
+import threading
+import uuid
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .task_execution_registry import (
+    ExecutionTaskManifest,
+    ExecutionTruthRecord,
+    ExecutionTruthState,
+    SQLiteExecutionTruthRegistry,
+    utc_now,
+)
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def sha256_value(value: str, label: str) -> str:
+    normalized = str(value or "").strip().lower()
+    if not _SHA256.fullmatch(normalized):
+        raise ValueError(f"{label} must be a lowercase SHA256 hex digest")
+    return normalized
+
+
+@dataclass(frozen=True)
+class NotificationRecord:
+    notification_id: str
+    task_id: str
+    event_type: str
+    target_ref: str
+    payload: Mapping[str, Any]
+    status: str
+    created_at: str
+    delivered_at: str | None = None
+    receipt_sha256: str | None = None
+    error: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class SQLiteNotificationOutbox:
+    """Durable owner-notification delivery and acknowledgement records."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        with self._connect() as connection:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS external_task_notifications (
+                    notification_id TEXT PRIMARY KEY,
+                    task_id TEXT NOT NULL,
+                    event_type TEXT NOT NULL,
+                    target_ref TEXT NOT NULL,
+                    payload_json TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    delivered_at TEXT,
+                    receipt_sha256 TEXT,
+                    error TEXT,
+                    UNIQUE(task_id, event_type)
+                );
+                CREATE INDEX IF NOT EXISTS idx_external_notification_status
+                    ON external_task_notifications(status, created_at);
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(str(self.path), timeout=30.0)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA synchronous=FULL")
+        return connection
+
+    @staticmethod
+    def _decode(row: sqlite3.Row) -> NotificationRecord:
+        return NotificationRecord(
+            notification_id=row["notification_id"],
+            task_id=row["task_id"],
+            event_type=row["event_type"],
+            target_ref=row["target_ref"],
+            payload=json.loads(row["payload_json"]),
+            status=row["status"],
+            created_at=row["created_at"],
+            delivered_at=row["delivered_at"],
+            receipt_sha256=row["receipt_sha256"],
+            error=row["error"],
+        )
+
+    def enqueue(
+        self,
+        *,
+        task_id: str,
+        event_type: str,
+        target_ref: str,
+        payload: Mapping[str, Any],
+    ) -> NotificationRecord:
+        now = utc_now()
+        record = NotificationRecord(
+            notification_id=f"notify_{uuid.uuid4().hex}",
+            task_id=str(task_id).strip(),
+            event_type=str(event_type).strip().upper(),
+            target_ref=str(target_ref).strip(),
+            payload=json.loads(json.dumps(dict(payload), ensure_ascii=False, default=str)),
+            status="PENDING",
+            created_at=now,
+        )
+        if not record.task_id or not record.event_type or not record.target_ref:
+            raise ValueError("task_id, event_type and target_ref are required")
+        with self._lock, self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            existing = connection.execute(
+                "SELECT * FROM external_task_notifications WHERE task_id = ? AND event_type = ?",
+                (record.task_id, record.event_type),
+            ).fetchone()
+            if existing is not None:
+                connection.rollback()
+                return self._decode(existing)
+            connection.execute(
+                """
+                INSERT INTO external_task_notifications
+                (notification_id, task_id, event_type, target_ref, payload_json,
+                 status, created_at, delivered_at, receipt_sha256, error)
+                VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL)
+                """,
+                (
+                    record.notification_id,
+                    record.task_id,
+                    record.event_type,
+                    record.target_ref,
+                    json.dumps(record.payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")),
+                    record.status,
+                    record.created_at,
+                ),
+            )
+            connection.commit()
+        return record
+
+    def get(self, notification_id: str) -> NotificationRecord:
+        with self._lock, self._connect() as connection:
+            row = connection.execute(
+                "SELECT * FROM external_task_notifications WHERE notification_id = ?",
+                (str(notification_id).strip(),),
+            ).fetchone()
+        if row is None:
+            raise KeyError("notification not found")
+        return self._decode(row)
+
+    def acknowledge(self, notification_id: str, *, receipt_sha256: str) -> NotificationRecord:
+        digest = sha256_value(receipt_sha256, "receipt_sha256")
+        with self._lock, self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT * FROM external_task_notifications WHERE notification_id = ?",
+                (str(notification_id).strip(),),
+            ).fetchone()
+            if row is None:
+                connection.rollback()
+                raise KeyError("notification not found")
+            current = self._decode(row)
+            if current.status == "DELIVERED":
+                if current.receipt_sha256 != digest:
+                    connection.rollback()
+                    raise RuntimeError("notification already acknowledged with another receipt")
+                connection.rollback()
+                return current
+            delivered_at = utc_now()
+            connection.execute(
+                """
+                UPDATE external_task_notifications
+                SET status = 'DELIVERED', delivered_at = ?, receipt_sha256 = ?, error = NULL
+                WHERE notification_id = ?
+                """,
+                (delivered_at, digest, current.notification_id),
+            )
+            connection.commit()
+        return self.get(current.notification_id)
+
+    def fail(self, notification_id: str, *, error: str) -> NotificationRecord:
+        message = str(error or "").strip()
+        if not message:
+            raise ValueError("notification error is required")
+        with self._lock, self._connect() as connection:
+            connection.execute(
+                "UPDATE external_task_notifications SET status = 'FAILED', error = ? WHERE notification_id = ?",
+                (message, str(notification_id).strip()),
+            )
+            connection.commit()
+        return self.get(notification_id)
+
+    def list(
+        self,
+        *,
+        task_id: str | None = None,
+        status: str | None = None,
+    ) -> list[NotificationRecord]:
+        conditions: list[str] = []
+        values: list[str] = []
+        if task_id:
+            conditions.append("task_id = ?")
+            values.append(str(task_id).strip())
+        if status:
+            conditions.append("status = ?")
+            values.append(str(status).strip().upper())
+        where = f" WHERE {' AND '.join(conditions)}" if conditions else ""
+        with self._lock, self._connect() as connection:
+            rows = connection.execute(
+                f"SELECT * FROM external_task_notifications{where} ORDER BY created_at, notification_id",
+                tuple(values),
+            ).fetchall()
+        return [self._decode(row) for row in rows]
+
+
+class ExternalTaskCoordinator:
+    """Single safe lifecycle used by external executors and release gates."""
+
+    def __init__(
+        self,
+        registry: SQLiteExecutionTruthRegistry,
+        notifications: SQLiteNotificationOutbox,
+    ) -> None:
+        self.registry = registry
+        self.notifications = notifications
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "ExternalTaskCoordinator":
+        return cls(
+            SQLiteExecutionTruthRegistry(path),
+            SQLiteNotificationOutbox(path),
+        )
+
+    def declare(self, manifest: ExecutionTaskManifest) -> ExecutionTruthRecord:
+        return self.registry.declare(manifest)
+
+    def declare_file(self, path: str | Path) -> ExecutionTruthRecord:
+        value = json.loads(Path(path).read_text(encoding="utf-8"))
+        if not isinstance(value, Mapping):
+            raise ValueError("external task manifest must be a JSON object")
+        return self.declare(ExecutionTaskManifest.from_dict(value))
+
+    def register(self, task_id: str, *, executor_run_id: str) -> ExecutionTruthRecord:
+        return self.registry.register(task_id, executor_run_id=executor_run_id)
+
+    def retry_not_started(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+    ) -> ExecutionTruthRecord:
+        return self.registry.retry_not_started(
+            task_id,
+            executor_run_id=executor_run_id,
+        )
+
+    def claim(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+    ) -> ExecutionTruthRecord:
+        return self.registry.claim(
+            task_id,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+        )
+
+    def _notify(self, record: ExecutionTruthRecord, event_type: str) -> NotificationRecord | None:
+        event = event_type.upper()
+        if event not in set(record.manifest.notification_events):
+            return None
+        return self.notifications.enqueue(
+            task_id=record.task_id,
+            event_type=event,
+            target_ref=record.manifest.owner_notification_ref,
+            payload={
+                "task_id": record.task_id,
+                "target_version": record.manifest.target_version,
+                "executor": record.manifest.executor,
+                "executor_id": record.executor_id,
+                "executor_run_id": record.executor_run_id,
+                "state": record.state.value,
+                "current_step": record.current_step,
+                "total_steps": len(record.manifest.steps),
+                "timestamp": utc_now(),
+            },
+        )
+
+    def start(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+    ) -> ExecutionTruthRecord:
+        record = self.registry.start(
+            task_id,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+        )
+        self._notify(record, "STARTED")
+        return record
+
+    def heartbeat(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+        current_step: int,
+    ) -> ExecutionTruthRecord:
+        return self.registry.heartbeat(
+            task_id,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            current_step=current_step,
+        )
+
+    def succeed(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+        evidence: Mapping[str, str],
+    ) -> ExecutionTruthRecord:
+        normalized = {
+            str(key).strip(): sha256_value(value, f"evidence[{key}]")
+            for key, value in evidence.items()
+        }
+        record = self.registry.succeed(
+            task_id,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            evidence=normalized,
+        )
+        self._notify(record, "SUCCEEDED")
+        return record
+
+    def fail(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+        error: Mapping[str, Any],
+        evidence: Mapping[str, str] | None = None,
+    ) -> ExecutionTruthRecord:
+        normalized = None
+        if evidence is not None:
+            normalized = {
+                str(key).strip(): sha256_value(value, f"evidence[{key}]")
+                for key, value in evidence.items()
+            }
+        record = self.registry.fail(
+            task_id,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            error=error,
+            evidence=normalized,
+        )
+        self._notify(record, "FAILED")
+        return record
+
+    def gate(self, task_id: str) -> Mapping[str, Any]:
+        before = self.registry.get(task_id)
+        truth = self.registry.gate(task_id)
+        after = self.registry.get(task_id)
+        if after.state != before.state and after.state in {
+            ExecutionTruthState.NOT_STARTED,
+            ExecutionTruthState.STALLED,
+        }:
+            self._notify(after, after.state.value)
+        notifications = self.notifications.list(task_id=task_id)
+        delivered = {item.event_type for item in notifications if item.status == "DELIVERED"}
+        required_success_notifications = {
+            item
+            for item in ("STARTED", "SUCCEEDED")
+            if item in set(after.manifest.notification_events)
+        }
+        notification_complete = required_success_notifications.issubset(delivered)
+        passed = bool(truth["passed"] and notification_complete)
+        return {
+            **dict(truth),
+            "passed": passed,
+            "release_blocking": not passed,
+            "notification_complete": notification_complete,
+            "required_success_notifications": sorted(required_success_notifications),
+            "delivered_notifications": sorted(delivered),
+            "notifications": [item.as_dict() for item in notifications],
+        }
+
+    def status(self, task_id: str) -> Mapping[str, Any]:
+        gate = self.gate(task_id)
+        record = self.registry.get(task_id)
+        return {
+            "record": record.as_dict(),
+            "gate": gate,
+            "events": self.registry.events(task_id),
+        }
+
+    @staticmethod
+    def content_receipt(value: Mapping[str, Any]) -> str:
+        encoded = json.dumps(dict(value), ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
+        return hashlib.sha256(encoded).hexdigest()
@@ -0,0 +1,51 @@
+"""Read models for the durable external-task truth registry."""
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Sequence
+
+from .task_execution_registry import ExecutionTruthRecord, ExecutionTruthState
+
+
+def _decode(value: str) -> ExecutionTruthRecord:
+    payload = json.loads(value)
+    payload["state"] = ExecutionTruthState(payload["state"])
+    payload["evidence"] = dict(payload.get("evidence") or {})
+    payload["error"] = dict(payload.get("error") or {})
+    return ExecutionTruthRecord(**payload)
+
+
+def list_records(
+    path: str | Path,
+    *,
+    executor: str | None = None,
+    states: Sequence[str] = (),
+) -> list[ExecutionTruthRecord]:
+    database = Path(path).resolve()
+    if not database.exists():
+        return []
+    conditions: list[str] = []
+    values: list[str] = []
+    normalized_states = tuple(sorted({ExecutionTruthState(item).value for item in states}))
+    if normalized_states:
+        conditions.append(f"state IN ({','.join('?' for _ in normalized_states)})")
+        values.extend(normalized_states)
+    where = f" WHERE {' AND '.join(conditions)}" if conditions else ""
+    connection = sqlite3.connect(f"file:{database}?mode=ro", uri=True, timeout=10.0)
+    connection.row_factory = sqlite3.Row
+    try:
+        rows = connection.execute(
+            f"SELECT record_json FROM execution_truth{where} ORDER BY updated_at, task_id",
+            tuple(values),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return []
+    finally:
+        connection.close()
+    records = [_decode(row["record_json"]) for row in rows]
+    if executor:
+        normalized = str(executor).strip().lower()
+        records = [item for item in records if item.manifest.executor.lower() == normalized]
+    return records
@@ -17,6 +17,8 @@ from http import HTTPStatus
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import Any, Mapping

+from aios_hermes import HermesConflict, HermesNotFound
+
 from .control_plane import (
    ControlPlaneError,
    ControlPlaneService,
@@ -81,20 +83,27 @@ class GatewayApplication:

    @staticmethod
    def context_from_headers(headers: Mapping[str, str]) -> RequestContext:
-        authenticated = str(headers.get(AUTHENTICATED_HEADER, "")).strip().lower()
+        normalized_headers = {
+            str(key).strip().lower(): value for key, value in headers.items()
+        }
+
+        def header(name: str, default: str = "") -> str:
+            return str(normalized_headers.get(name.lower(), default))
+
+        authenticated = header(AUTHENTICATED_HEADER).strip().lower()
        if authenticated not in {"1", "true", "yes"}:
            raise Unauthorized("trusted authentication assertion is required")
        roles = [
            role.strip()
-            for role in str(headers.get(ROLES_HEADER, "")).split(",")
+            for role in header(ROLES_HEADER).split(",")
            if role.strip()
        ]
        return RequestContext.create(
-            tenant_id=str(headers.get(TENANT_HEADER, "")),
-            principal_id=str(headers.get(PRINCIPAL_HEADER, "")),
-            trace_id=str(headers.get(TRACE_HEADER, "")).strip() or None,
-            session_id=str(headers.get(SESSION_HEADER, "")).strip() or None,
-            policy_version=str(headers.get(POLICY_HEADER, "v1")).strip() or "v1",
+            tenant_id=header(TENANT_HEADER),
+            principal_id=header(PRINCIPAL_HEADER),
+            trace_id=header(TRACE_HEADER).strip() or None,
+            session_id=header(SESSION_HEADER).strip() or None,
+            policy_version=header(POLICY_HEADER, "v1").strip() or "v1",
            roles=roles,
        )

@@ -242,11 +251,13 @@ _ERROR_STATUS: tuple[tuple[type[BaseException], HTTPStatus], ...] = (
    (TenantIsolationError, HTTPStatus.NOT_FOUND),
    (NotFound, HTTPStatus.NOT_FOUND),
    (DispatchNotFound, HTTPStatus.NOT_FOUND),
+    (HermesNotFound, HTTPStatus.NOT_FOUND),
    (ProvenanceReplay, HTTPStatus.CONFLICT),
    (IdempotencyConflict, HTTPStatus.CONFLICT),
    (RevisionConflict, HTTPStatus.CONFLICT),
    (InvalidTransition, HTTPStatus.CONFLICT),
    (DispatchConflict, HTTPStatus.CONFLICT),
+    (HermesConflict, HTTPStatus.CONFLICT),
    (OrchestrationError, HTTPStatus.CONFLICT),
    (ValueError, HTTPStatus.BAD_REQUEST),
    (ControlPlaneError, HTTPStatus.BAD_REQUEST),
@@ -0,0 +1,238 @@
+"""Official AIOS executor providers built on the portable provider protocol.
+
+The official providers contain no lifecycle implementation. They validate their
+manifests, resolve a generic ``UnifiedExecutorWorker`` from runtime-supplied
+boundaries and expose the same adapter contract. Future providers can use
+``ConfiguredExecutorProvider`` directly without changing AIOS core modules.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+from .execution_plan import ExecutionPlanCoordinator, ExecutionStageManifest
+from .executor_protocol import (
+    EXECUTOR_PROTOCOL_VERSION,
+    ExternalExecutorAdapter,
+    ExecutorProviderDescriptor,
+    normalize_executor,
+)
+from .executor_worker import NotificationSender, StepRunner, UnifiedExecutorWorker
+from .external_task_control import ExternalTaskCoordinator
+from .task_execution_registry import ExecutionTaskManifest, ExecutionTruthRecord
+
+
+@dataclass(frozen=True)
+class ProviderRuntimeConfiguration:
+    plan_id: str
+    executor_id: str
+    plan_coordinator: ExecutionPlanCoordinator
+    task_coordinator: ExternalTaskCoordinator
+    providers: Any
+    step_runner: StepRunner
+    notification_sender: NotificationSender
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "ProviderRuntimeConfiguration":
+        required = (
+            "plan_id",
+            "executor_id",
+            "plan_coordinator",
+            "task_coordinator",
+            "providers",
+            "step_runner",
+            "notification_sender",
+        )
+        missing = [name for name in required if value.get(name) is None]
+        if missing:
+            raise ValueError(f"provider runtime configuration is missing: {missing}")
+        return cls(**{name: value[name] for name in required})
+
+
+class ConfiguredExecutorAdapter:
+    """Generic adapter produced by every official or third-party provider."""
+
+    def __init__(
+        self,
+        descriptor: ExecutorProviderDescriptor,
+        configuration: ProviderRuntimeConfiguration,
+    ) -> None:
+        self.descriptor = descriptor
+        self.configuration = configuration
+        self.worker = UnifiedExecutorWorker(
+            plan_coordinator=configuration.plan_coordinator,
+            task_coordinator=configuration.task_coordinator,
+            providers=configuration.providers,
+            executor_type=descriptor.executor_type,
+            executor_id=configuration.executor_id,
+            step_runner=configuration.step_runner,
+            notification_sender=configuration.notification_sender,
+        )
+
+    def discover(self) -> Sequence[ExecutionTruthRecord]:
+        ready = self.configuration.plan_coordinator.discover_ready(
+            plan_id=self.configuration.plan_id,
+            executor_type=self.descriptor.executor_type,
+        )
+        return tuple(item["record"] for item in ready)
+
+    def execute(self, manifest: ExecutionTaskManifest) -> Mapping[str, Any]:
+        if normalize_executor(manifest.executor) != self.descriptor.executor_type:
+            raise PermissionError("manifest executor does not match adapter provider")
+        plan = self.configuration.plan_coordinator.plan_store.get(
+            self.configuration.plan_id
+        )
+        stage: ExecutionStageManifest | None = None
+        for item in plan.stages:
+            if item.task_id == manifest.task_id:
+                stage = item
+                break
+        if stage is None:
+            raise KeyError("manifest task is not part of configured execution plan")
+        return self.worker.run_stage(
+            plan_id=plan.plan_id,
+            stage_id=stage.stage_id,
+        ).as_dict()
+
+    def notify_owner(self, payload: Mapping[str, Any]) -> str:
+        # External callers normally use the durable NotificationOutbox. This
+        # method remains part of the portable adapter contract for providers
+        # that need to send a standalone operational notice.
+        from .external_task_control import NotificationRecord
+        from .task_execution_registry import utc_now
+
+        notification = NotificationRecord(
+            notification_id="provider_direct_notice",
+            task_id=str(payload.get("task_id") or "provider-notice"),
+            event_type=str(payload.get("event_type") or "INFO"),
+            target_ref=str(
+                payload.get("target_ref") or "AIOS_OWNER_WECHAT_TARGET_REF"
+            ),
+            payload=dict(payload),
+            status="PENDING",
+            created_at=utc_now(),
+        )
+        return self.configuration.notification_sender.send(notification)
+
+
+class ConfiguredExecutorProvider:
+    """Reusable provider implementation for current and future executors."""
+
+    descriptor: ExecutorProviderDescriptor
+
+    def __init__(self, descriptor: ExecutorProviderDescriptor) -> None:
+        self.descriptor = descriptor
+
+    def validate_manifest(self, manifest: ExecutionTaskManifest) -> None:
+        if normalize_executor(manifest.executor) != self.descriptor.executor_type:
+            raise ValueError("manifest executor does not match provider")
+        if manifest.manifest_version not in {
+            "aios.external-task.v1",
+            "aios.external-task.v2",
+        }:
+            raise ValueError("unsupported external task manifest version")
+        if not manifest.steps:
+            raise ValueError("executor manifest has no steps")
+
+    def build_adapter(self, configuration: Mapping[str, Any]) -> ExternalExecutorAdapter:
+        return ConfiguredExecutorAdapter(
+            self.descriptor,
+            ProviderRuntimeConfiguration.from_mapping(configuration),
+        )
+
+
+class OpenClawProvider(ConfiguredExecutorProvider):
+    def __init__(self) -> None:
+        super().__init__(
+            ExecutorProviderDescriptor(
+                executor_type="openclaw",
+                adapter_version="2.1.0",
+                protocol_version=EXECUTOR_PROTOCOL_VERSION,
+                trust_roles=("runtime", "openclaw_executor"),
+                capabilities=(
+                    "deploy",
+                    "http_runtime",
+                    "owner_notification",
+                    "healthcheck",
+                    "rollback",
+                ),
+                configuration_schema="aios.executor.openclaw.config.v1",
+                metadata={"official": True},
+            )
+        )
+
+
+class HermesProvider(ConfiguredExecutorProvider):
+    def __init__(self) -> None:
+        super().__init__(
+            ExecutorProviderDescriptor(
+                executor_type="hermes",
+                adapter_version="2.1.0",
+                protocol_version=EXECUTOR_PROTOCOL_VERSION,
+                trust_roles=("runtime", "hermes_executor"),
+                capabilities=(
+                    "queue",
+                    "lease",
+                    "worker",
+                    "runtime_validation",
+                    "restart_recovery",
+                ),
+                configuration_schema="aios.executor.hermes.config.v1",
+                metadata={"official": True},
+            )
+        )
+
+
+class CodexProvider(ConfiguredExecutorProvider):
+    def __init__(self) -> None:
+        super().__init__(
+            ExecutorProviderDescriptor(
+                executor_type="codex",
+                adapter_version="2.1.0",
+                protocol_version=EXECUTOR_PROTOCOL_VERSION,
+                trust_roles=("codex", "codex_executor"),
+                capabilities=(
+                    "code",
+                    "test",
+                    "docs",
+                    "gitops_patch",
+                    "security_review",
+                ),
+                configuration_schema="aios.executor.codex.config.v1",
+                metadata={"official": True},
+            )
+        )
+
+
+class ChatGPTSupervisorProvider(ConfiguredExecutorProvider):
+    """Explicit takeover provider; it does not inherit Codex permissions."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            ExecutorProviderDescriptor(
+                executor_type="chatgpt-supervisor",
+                adapter_version="2.1.0",
+                protocol_version=EXECUTOR_PROTOCOL_VERSION,
+                trust_roles=("chatgpt_supervisor",),
+                capabilities=(
+                    "acceptance",
+                    "deploy",
+                    "evidence",
+                    "healthcheck",
+                    "rollback",
+                    "wechat_simulation",
+                ),
+                configuration_schema="aios.executor.chatgpt-supervisor.config.v1",
+                metadata={"official": True, "production_mutation_allowed": False},
+            )
+        )
+
+
+def official_provider_factories() -> Mapping[str, ConfiguredExecutorProvider]:
+    providers = (
+        OpenClawProvider(),
+        HermesProvider(),
+        CodexProvider(),
+        ChatGPTSupervisorProvider(),
+    )
+    return {item.descriptor.executor_type: item for item in providers}
@@ -353,6 +353,76 @@ class ExecutionOrchestrator:
            if getattr(dispatch, field_name) != expected_value:
                raise OrchestrationError(f"dispatch {field_name} mismatch")

+    def hermes_lifecycle_context(
+        self,
+        context: RequestContext,
+        *,
+        dispatch_id: str,
+        job_id: str,
+        tenant_id: str,
+        task_id: str,
+        trace_id: str,
+        principal_id: str,
+        provenance_id: str,
+        run_id: str,
+    ) -> tuple[DispatchRecord, HermesJob]:
+        """Resolve a runtime lifecycle request against its durable dispatch."""
+        dispatch = self.dispatch_repository.get(
+            dispatch_id, tenant_id=context.tenant_id
+        )
+        self._assert_dispatch_context(
+            dispatch,
+            runtime="hermes",
+            runtime_execution_id=job_id,
+            tenant_id=tenant_id,
+            task_id=task_id,
+            trace_id=trace_id,
+            principal_id=principal_id,
+            provenance_id=provenance_id,
+            run_id=run_id,
+        )
+        if context.tenant_id != tenant_id:
+            raise OrchestrationError("runtime context tenant_id mismatch")
+        if context.principal_id != principal_id:
+            raise OrchestrationError("runtime context principal_id mismatch")
+        if context.trace_id != trace_id:
+            raise OrchestrationError("runtime context trace_id mismatch")
+        if self.hermes is None:
+            raise OrchestrationError("Hermes runtime is not configured")
+        job = self.hermes.get(job_id, tenant_id=tenant_id)
+        if job.task_id != task_id or job.trace_id != trace_id:
+            raise OrchestrationError("Hermes job identity mismatch")
+        return dispatch, job
+
+    def bind_hermes_worker(
+        self,
+        context: RequestContext,
+        job: HermesJob,
+        *,
+        dispatch_id: str,
+        provenance_id: str,
+        run_id: str,
+        worker_id: str,
+    ) -> DispatchRecord:
+        dispatch, current = self.hermes_lifecycle_context(
+            context,
+            dispatch_id=dispatch_id,
+            job_id=job.job_id,
+            tenant_id=job.tenant_id,
+            task_id=job.task_id,
+            trace_id=job.trace_id,
+            principal_id=context.principal_id,
+            provenance_id=provenance_id,
+            run_id=run_id,
+        )
+        if current.assigned_worker_id != worker_id:
+            raise OrchestrationError("Hermes worker does not own claimed job")
+        return self.dispatch_repository.update(
+            dispatch.dispatch_id,
+            tenant_id=dispatch.tenant_id,
+            expected_worker_id=worker_id,
+        )
+
    def reconcile_openclaw(
        self,
        context: RequestContext,
@@ -0,0 +1,607 @@
+"""Durable execution truth registry for externally executed AIOS tasks.
+
+A task manifest being present in Git is not evidence that an executor discovered
+or ran it. This registry separates declaration, registration, claim, start,
+heartbeat and terminal evidence. Release gates must require a terminal success
+record with immutable evidence hashes.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import uuid
+from dataclasses import asdict, dataclass, field, replace
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def parse_time(value: str) -> datetime:
+    normalized = str(value or "").strip()
+    if normalized.endswith("Z"):
+        normalized = normalized[:-1] + "+00:00"
+    parsed = datetime.fromisoformat(normalized)
+    if parsed.tzinfo is None:
+        raise ValueError("timestamp requires timezone")
+    return parsed.astimezone(timezone.utc)
+
+
+def required(value: str, label: str) -> str:
+    normalized = str(value or "").strip()
+    if not normalized:
+        raise ValueError(f"{label} is required")
+    return normalized
+
+
+class ExecutionTruthState(str, Enum):
+    DECLARED = "DECLARED"
+    REGISTERED = "REGISTERED"
+    CLAIMED = "CLAIMED"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+    NOT_STARTED = "NOT_STARTED"
+    STALLED = "STALLED"
+
+
+TERMINAL_STATES = frozenset(
+    {
+        ExecutionTruthState.SUCCEEDED,
+        ExecutionTruthState.FAILED,
+        ExecutionTruthState.CANCELLED,
+        ExecutionTruthState.NOT_STARTED,
+        ExecutionTruthState.STALLED,
+    }
+)
+
+
+@dataclass(frozen=True)
+class ExecutionTaskManifest:
+    task_id: str
+    executor: str
+    source_branch: str
+    source_oid: str
+    target_version: str
+    steps: Sequence[str]
+    start_deadline_seconds: int = 300
+    heartbeat_timeout_seconds: int = 180
+    required_evidence: Sequence[str] = ()
+    notification_events: Sequence[str] = ("STARTED", "SUCCEEDED", "FAILED")
+    owner_notification_ref: str = "AIOS_OWNER_WECHAT_TARGET_REF"
+    manifest_version: str = "aios.external-task.v1"
+
+    def __post_init__(self) -> None:
+        for name in (
+            "task_id",
+            "executor",
+            "source_branch",
+            "source_oid",
+            "target_version",
+            "manifest_version",
+            "owner_notification_ref",
+        ):
+            object.__setattr__(self, name, required(getattr(self, name), name))
+        steps = tuple(required(item, "step") for item in self.steps)
+        if not steps:
+            raise ValueError("at least one execution step is required")
+        if self.start_deadline_seconds < 1 or self.heartbeat_timeout_seconds < 1:
+            raise ValueError("execution deadlines must be positive")
+        object.__setattr__(self, "steps", steps)
+        object.__setattr__(
+            self,
+            "required_evidence",
+            tuple(sorted({required(item, "required_evidence") for item in self.required_evidence})),
+        )
+        object.__setattr__(
+            self,
+            "notification_events",
+            tuple(sorted({required(item, "notification_event") for item in self.notification_events})),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["steps"] = list(self.steps)
+        value["required_evidence"] = list(self.required_evidence)
+        value["notification_events"] = list(self.notification_events)
+        return value
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ExecutionTaskManifest":
+        return cls(**dict(value))
+
+
+@dataclass(frozen=True)
+class ExecutionTruthRecord:
+    task_id: str
+    manifest_json: str
+    state: ExecutionTruthState
+    executor_run_id: str | None = None
+    executor_id: str | None = None
+    declared_at: str = field(default_factory=utc_now)
+    registered_at: str | None = None
+    claimed_at: str | None = None
+    started_at: str | None = None
+    heartbeat_at: str | None = None
+    completed_at: str | None = None
+    current_step: int = 0
+    evidence: Mapping[str, str] = field(default_factory=dict)
+    error: Mapping[str, Any] = field(default_factory=dict)
+    revision: int = 1
+
+    @property
+    def manifest(self) -> ExecutionTaskManifest:
+        return ExecutionTaskManifest.from_dict(json.loads(self.manifest_json))
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            **asdict(self),
+            "state": self.state.value,
+            "manifest": self.manifest.as_dict(),
+            "evidence": dict(self.evidence),
+            "error": dict(self.error),
+        }
+
+
+class ExecutionTruthConflict(RuntimeError):
+    pass
+
+
+class SQLiteExecutionTruthRegistry:
+    """Persistent registration and run-evidence store."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path).resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        with self._connect() as connection:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS execution_truth (
+                    task_id TEXT PRIMARY KEY,
+                    manifest_json TEXT NOT NULL,
+                    state TEXT NOT NULL,
+                    record_json TEXT NOT NULL,
+                    revision INTEGER NOT NULL,
+                    updated_at TEXT NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS execution_truth_events (
+                    event_id TEXT PRIMARY KEY,
+                    task_id TEXT NOT NULL,
+                    event_type TEXT NOT NULL,
+                    details_json TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    FOREIGN KEY(task_id) REFERENCES execution_truth(task_id)
+                );
+                CREATE INDEX IF NOT EXISTS idx_execution_truth_state
+                    ON execution_truth(state, updated_at);
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(str(self.path), timeout=30.0)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA synchronous=FULL")
+        connection.execute("PRAGMA foreign_keys=ON")
+        return connection
+
+    @staticmethod
+    def _manifest_json(manifest: ExecutionTaskManifest) -> str:
+        return json.dumps(manifest.as_dict(), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+    @staticmethod
+    def _record_json(record: ExecutionTruthRecord) -> str:
+        value = record.as_dict()
+        value.pop("manifest", None)
+        return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
+
+    @staticmethod
+    def _decode(row: sqlite3.Row) -> ExecutionTruthRecord:
+        value = json.loads(row["record_json"])
+        value["state"] = ExecutionTruthState(value["state"])
+        value["evidence"] = dict(value.get("evidence") or {})
+        value["error"] = dict(value.get("error") or {})
+        return ExecutionTruthRecord(**value)
+
+    def _event(
+        self,
+        connection: sqlite3.Connection,
+        task_id: str,
+        event_type: str,
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        connection.execute(
+            "INSERT INTO execution_truth_events VALUES (?, ?, ?, ?, ?)",
+            (
+                f"truth_evt_{uuid.uuid4().hex}",
+                task_id,
+                event_type,
+                json.dumps(dict(details or {}), ensure_ascii=False, sort_keys=True, default=str),
+                utc_now(),
+            ),
+        )
+
+    def declare(self, manifest: ExecutionTaskManifest) -> ExecutionTruthRecord:
+        manifest_json = self._manifest_json(manifest)
+        record = ExecutionTruthRecord(
+            task_id=manifest.task_id,
+            manifest_json=manifest_json,
+            state=ExecutionTruthState.DECLARED,
+        )
+        with self._lock, self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            existing = connection.execute(
+                "SELECT record_json FROM execution_truth WHERE task_id = ?",
+                (manifest.task_id,),
+            ).fetchone()
+            if existing is not None:
+                current = self._decode(existing)
+                if current.manifest_json != manifest_json:
+                    previous_manifest = current.manifest.as_dict()
+                    replacement_manifest = manifest.as_dict()
+                    previous_oid = previous_manifest.pop("source_oid")
+                    replacement_oid = replacement_manifest.pop("source_oid")
+                    if (
+                        current.state != ExecutionTruthState.NOT_STARTED
+                        or previous_manifest != replacement_manifest
+                    ):
+                        connection.rollback()
+                        raise ExecutionTruthConflict(
+                            "task_id already declared with another manifest"
+                        )
+                    now = utc_now()
+                    updated = replace(
+                        current,
+                        manifest_json=manifest_json,
+                        revision=current.revision + 1,
+                    )
+                    connection.execute(
+                        "UPDATE execution_truth SET manifest_json = ?, record_json = ?, revision = ?, updated_at = ? WHERE task_id = ?",
+                        (
+                            manifest_json,
+                            self._record_json(updated),
+                            updated.revision,
+                            now,
+                            updated.task_id,
+                        ),
+                    )
+                    self._event(
+                        connection,
+                        updated.task_id,
+                        "MANIFEST_SUPERSEDED",
+                        {
+                            "previous_source_oid": previous_oid,
+                            "source_oid": replacement_oid,
+                            "state": updated.state.value,
+                        },
+                    )
+                    connection.commit()
+                    return updated
+                connection.rollback()
+                return current
+            connection.execute(
+                "INSERT INTO execution_truth VALUES (?, ?, ?, ?, ?, ?)",
+                (
+                    record.task_id,
+                    manifest_json,
+                    record.state.value,
+                    self._record_json(record),
+                    record.revision,
+                    record.declared_at,
+                ),
+            )
+            self._event(connection, record.task_id, "DECLARED", {"source_oid": manifest.source_oid})
+            connection.commit()
+        return record
+
+    def get(self, task_id: str) -> ExecutionTruthRecord:
+        with self._lock, self._connect() as connection:
+            row = connection.execute(
+                "SELECT record_json FROM execution_truth WHERE task_id = ?",
+                (required(task_id, "task_id"),),
+            ).fetchone()
+        if row is None:
+            raise KeyError("execution task not declared")
+        return self._decode(row)
+
+    def _transition(
+        self,
+        task_id: str,
+        *,
+        allowed: Sequence[ExecutionTruthState],
+        target: ExecutionTruthState,
+        executor_run_id: str | None = None,
+        executor_id: str | None = None,
+        current_step: int | None = None,
+        evidence: Mapping[str, str] | None = None,
+        error: Mapping[str, Any] | None = None,
+    ) -> ExecutionTruthRecord:
+        with self._lock, self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT record_json FROM execution_truth WHERE task_id = ?",
+                (required(task_id, "task_id"),),
+            ).fetchone()
+            if row is None:
+                connection.rollback()
+                raise KeyError("execution task not declared")
+            current = self._decode(row)
+            if current.state not in set(allowed):
+                connection.rollback()
+                raise ExecutionTruthConflict(
+                    f"cannot transition {current.state.value} to {target.value}"
+                )
+            now = utc_now()
+            updates: dict[str, Any] = {
+                "state": target,
+                "revision": current.revision + 1,
+            }
+            if executor_run_id is not None:
+                if current.executor_run_id and current.executor_run_id != executor_run_id:
+                    connection.rollback()
+                    raise ExecutionTruthConflict("executor_run_id mismatch")
+                updates["executor_run_id"] = required(executor_run_id, "executor_run_id")
+            if executor_id is not None:
+                if current.executor_id and current.executor_id != executor_id:
+                    connection.rollback()
+                    raise ExecutionTruthConflict("executor_id mismatch")
+                updates["executor_id"] = required(executor_id, "executor_id")
+            if target == ExecutionTruthState.REGISTERED:
+                updates["registered_at"] = now
+            if target == ExecutionTruthState.CLAIMED:
+                updates["claimed_at"] = now
+                updates["heartbeat_at"] = now
+            if target == ExecutionTruthState.RUNNING:
+                updates["started_at"] = current.started_at or now
+                updates["heartbeat_at"] = now
+            if current_step is not None:
+                if current_step < current.current_step or current_step > len(current.manifest.steps):
+                    connection.rollback()
+                    raise ExecutionTruthConflict("invalid task step progression")
+                updates["current_step"] = current_step
+                updates["heartbeat_at"] = now
+            if evidence is not None:
+                updates["evidence"] = {
+                    **dict(current.evidence),
+                    **{required(key, "evidence key"): required(value, "evidence hash") for key, value in evidence.items()},
+                }
+            if error is not None:
+                updates["error"] = json.loads(json.dumps(dict(error), default=str))
+            if target in TERMINAL_STATES:
+                updates["completed_at"] = now
+            updated = replace(current, **updates)
+            connection.execute(
+                "UPDATE execution_truth SET state = ?, record_json = ?, revision = ?, updated_at = ? WHERE task_id = ?",
+                (
+                    updated.state.value,
+                    self._record_json(updated),
+                    updated.revision,
+                    now,
+                    updated.task_id,
+                ),
+            )
+            self._event(
+                connection,
+                updated.task_id,
+                target.value,
+                {
+                    "executor_run_id": updated.executor_run_id,
+                    "executor_id": updated.executor_id,
+                    "current_step": updated.current_step,
+                },
+            )
+            connection.commit()
+            return updated
+
+    def register(self, task_id: str, *, executor_run_id: str) -> ExecutionTruthRecord:
+        return self._transition(
+            task_id,
+            allowed=(ExecutionTruthState.DECLARED,),
+            target=ExecutionTruthState.REGISTERED,
+            executor_run_id=executor_run_id,
+        )
+
+    def retry_not_started(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+    ) -> ExecutionTruthRecord:
+        """Start a new audited attempt after the declaration deadline expired."""
+        with self._lock, self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT record_json FROM execution_truth WHERE task_id = ?",
+                (required(task_id, "task_id"),),
+            ).fetchone()
+            if row is None:
+                connection.rollback()
+                raise KeyError("execution task not declared")
+            current = self._decode(row)
+            if current.state != ExecutionTruthState.NOT_STARTED:
+                connection.rollback()
+                raise ExecutionTruthConflict(
+                    f"cannot retry task from {current.state.value}"
+                )
+            now = utc_now()
+            updated = replace(
+                current,
+                state=ExecutionTruthState.REGISTERED,
+                executor_run_id=required(executor_run_id, "executor_run_id"),
+                executor_id=None,
+                registered_at=now,
+                claimed_at=None,
+                started_at=None,
+                heartbeat_at=None,
+                completed_at=None,
+                current_step=0,
+                evidence={},
+                error={},
+                revision=current.revision + 1,
+            )
+            connection.execute(
+                "UPDATE execution_truth SET state = ?, record_json = ?, revision = ?, updated_at = ? WHERE task_id = ?",
+                (
+                    updated.state.value,
+                    self._record_json(updated),
+                    updated.revision,
+                    now,
+                    updated.task_id,
+                ),
+            )
+            self._event(
+                connection,
+                updated.task_id,
+                "RETRIED",
+                {
+                    "previous_state": current.state.value,
+                    "previous_executor_run_id": current.executor_run_id,
+                    "executor_run_id": updated.executor_run_id,
+                    "previous_error": dict(current.error),
+                },
+            )
+            connection.commit()
+            return updated
+
+    def claim(self, task_id: str, *, executor_run_id: str, executor_id: str) -> ExecutionTruthRecord:
+        return self._transition(
+            task_id,
+            allowed=(ExecutionTruthState.REGISTERED,),
+            target=ExecutionTruthState.CLAIMED,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+        )
+
+    def start(self, task_id: str, *, executor_run_id: str, executor_id: str) -> ExecutionTruthRecord:
+        return self._transition(
+            task_id,
+            allowed=(ExecutionTruthState.CLAIMED,),
+            target=ExecutionTruthState.RUNNING,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            current_step=1,
+        )
+
+    def heartbeat(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+        current_step: int,
+    ) -> ExecutionTruthRecord:
+        return self._transition(
+            task_id,
+            allowed=(ExecutionTruthState.RUNNING,),
+            target=ExecutionTruthState.RUNNING,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            current_step=current_step,
+        )
+
+    def succeed(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+        evidence: Mapping[str, str],
+    ) -> ExecutionTruthRecord:
+        current = self.get(task_id)
+        missing = sorted(set(current.manifest.required_evidence) - set(evidence))
+        if missing:
+            raise ExecutionTruthConflict(f"missing required evidence: {missing}")
+        if current.current_step != len(current.manifest.steps):
+            raise ExecutionTruthConflict("all declared steps must complete before success")
+        return self._transition(
+            task_id,
+            allowed=(ExecutionTruthState.RUNNING,),
+            target=ExecutionTruthState.SUCCEEDED,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            evidence=evidence,
+        )
+
+    def fail(
+        self,
+        task_id: str,
+        *,
+        executor_run_id: str,
+        executor_id: str,
+        error: Mapping[str, Any],
+        evidence: Mapping[str, str] | None = None,
+    ) -> ExecutionTruthRecord:
+        return self._transition(
+            task_id,
+            allowed=(ExecutionTruthState.REGISTERED, ExecutionTruthState.CLAIMED, ExecutionTruthState.RUNNING),
+            target=ExecutionTruthState.FAILED,
+            executor_run_id=executor_run_id,
+            executor_id=executor_id,
+            evidence=evidence,
+            error=error,
+        )
+
+    def evaluate_deadlines(self, task_id: str, *, now: datetime | None = None) -> ExecutionTruthRecord:
+        current = self.get(task_id)
+        current_time = (now or datetime.now(timezone.utc)).astimezone(timezone.utc)
+        manifest = current.manifest
+        if current.state in TERMINAL_STATES:
+            return current
+        declared = parse_time(current.declared_at)
+        if current.state in {ExecutionTruthState.DECLARED, ExecutionTruthState.REGISTERED}:
+            if current_time >= declared + timedelta(seconds=manifest.start_deadline_seconds):
+                return self._transition(
+                    task_id,
+                    allowed=(current.state,),
+                    target=ExecutionTruthState.NOT_STARTED,
+                    error={"code": "start_deadline_exceeded"},
+                )
+        if current.state in {ExecutionTruthState.CLAIMED, ExecutionTruthState.RUNNING}:
+            heartbeat = parse_time(current.heartbeat_at or current.claimed_at or current.declared_at)
+            if current_time >= heartbeat + timedelta(seconds=manifest.heartbeat_timeout_seconds):
+                return self._transition(
+                    task_id,
+                    allowed=(current.state,),
+                    target=ExecutionTruthState.STALLED,
+                    error={"code": "heartbeat_timeout"},
+                )
+        return current
+
+    def gate(self, task_id: str) -> Mapping[str, Any]:
+        record = self.evaluate_deadlines(task_id)
+        passed = record.state == ExecutionTruthState.SUCCEEDED
+        return {
+            "task_id": record.task_id,
+            "state": record.state.value,
+            "passed": passed,
+            "release_blocking": not passed,
+            "executor_run_id": record.executor_run_id,
+            "executor_id": record.executor_id,
+            "current_step": record.current_step,
+            "total_steps": len(record.manifest.steps),
+            "evidence": dict(record.evidence),
+            "error": dict(record.error),
+        }
+
+    def events(self, task_id: str) -> list[Mapping[str, Any]]:
+        with self._lock, self._connect() as connection:
+            rows = connection.execute(
+                "SELECT event_id, event_type, details_json, created_at FROM execution_truth_events WHERE task_id = ? ORDER BY created_at, event_id",
+                (required(task_id, "task_id"),),
+            ).fetchall()
+        return [
+            {
+                "event_id": row["event_id"],
+                "event_type": row["event_type"],
+                "details": json.loads(row["details_json"]),
+                "created_at": row["created_at"],
+            }
+            for row in rows
+        ]
@@ -0,0 +1,13 @@
+"""AIOS unified, role-aware web portal."""
+
+from .application import UnifiedPortalApplication, build_application
+from .capabilities import ROLE_CAPABILITIES, allows, require, resolve
+
+__all__ = [
+    "ROLE_CAPABILITIES",
+    "UnifiedPortalApplication",
+    "allows",
+    "build_application",
+    "require",
+    "resolve",
+]
@@ -0,0 +1,512 @@
+"""Unified, role-aware AIOS web application.
+
+The portal wraps the production CandidateApplication instead of replacing its
+runtime/control-plane routes. Portal endpoints aggregate existing authoritative
+stores and require server-side capabilities before delegating any state change.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import re
+import sqlite3
+import urllib.parse
+from enum import Enum
+from http import HTTPStatus
+from pathlib import Path
+from typing import Any, Mapping
+
+from aios_v2.app import (
+    CandidateApplication,
+    CandidateHTTPServer,
+    build_application as build_candidate_application,
+)
+from aios_v2.control_plane import RequestContext, TaskState
+from aios_v2.gitops_status import collect_gitops_status
+from aios_v2.provenance import SQLiteProvenanceStore
+from aios_v2.provenance_grants import SQLiteGrantStore
+
+from .capabilities import allows, require, resolve
+
+
+def _json_value(value: Any) -> Any:
+    if dataclasses.is_dataclass(value):
+        return {
+            field.name: _json_value(getattr(value, field.name))
+            for field in dataclasses.fields(value)
+        }
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Mapping):
+        return {str(key): _json_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_json_value(item) for item in value]
+    return value
+
+
+def _mapping(value: Any) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValueError("JSON body must be an object")
+    return value
+
+
+def _required(value: Any, label: str) -> str:
+    normalized = str(value or "").strip()
+    if not normalized:
+        raise ValueError(f"{label} is required")
+    return normalized
+
+
+def _safe_count(items: list[Any]) -> int:
+    return len(items)
+
+
+class AuthorizationCatalog:
+    """Tenant-filtered read/revoke access to existing Provenance stores."""
+
+    def __init__(self, store_file: str | Path) -> None:
+        self.store_file = Path(store_file).resolve()
+
+    def _read_connection(self) -> sqlite3.Connection | None:
+        if not self.store_file.exists():
+            return None
+        connection = sqlite3.connect(
+            f"file:{self.store_file}?mode=ro",
+            uri=True,
+            timeout=10.0,
+        )
+        connection.row_factory = sqlite3.Row
+        return connection
+
+    def snapshot(self, *, tenant_id: str) -> Mapping[str, Any]:
+        connection = self._read_connection()
+        if connection is None:
+            return {
+                "configured": False,
+                "workflows": [],
+                "grants": [],
+                "summary": {"workflows": 0, "grants": 0, "active_grants": 0},
+            }
+        try:
+            workflows: list[dict[str, Any]] = []
+            grants: list[dict[str, Any]] = []
+            tables = {
+                row["name"]
+                for row in connection.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table'"
+                ).fetchall()
+            }
+            if "provenance_records" in tables:
+                rows = connection.execute(
+                    """
+                    SELECT r.payload_json, r.status, r.signature_verified,
+                           r.created_at, r.updated_at,
+                           COUNT(u.authorization_id) AS usage_count
+                    FROM provenance_records r
+                    LEFT JOIN provenance_usage u
+                      ON u.provenance_id = r.provenance_id
+                    GROUP BY r.provenance_id
+                    ORDER BY r.updated_at DESC, r.provenance_id
+                    """
+                ).fetchall()
+                for row in rows:
+                    payload = json.loads(row["payload_json"])
+                    if payload.get("tenant_id") != tenant_id:
+                        continue
+                    workflows.append(
+                        {
+                            **payload,
+                            "status": row["status"],
+                            "signature_verified": bool(row["signature_verified"]),
+                            "usage_count": int(row["usage_count"]),
+                            "created_at": row["created_at"],
+                            "updated_at": row["updated_at"],
+                        }
+                    )
+            if "provenance_grants" in tables:
+                rows = connection.execute(
+                    """
+                    SELECT g.payload_json, g.status, g.signature_verified,
+                           g.created_at, g.updated_at,
+                           COUNT(u.authorization_id) AS usage_count
+                    FROM provenance_grants g
+                    LEFT JOIN provenance_grant_usage u
+                      ON u.grant_id = g.grant_id
+                    GROUP BY g.grant_id
+                    ORDER BY g.updated_at DESC, g.grant_id
+                    """
+                ).fetchall()
+                for row in rows:
+                    payload = json.loads(row["payload_json"])
+                    if payload.get("tenant_id") != tenant_id:
+                        continue
+                    grants.append(
+                        {
+                            **payload,
+                            "status": row["status"],
+                            "signature_verified": bool(row["signature_verified"]),
+                            "usage_count": int(row["usage_count"]),
+                            "created_at": row["created_at"],
+                            "updated_at": row["updated_at"],
+                        }
+                    )
+            active = sum(
+                1
+                for item in grants
+                if item.get("status") not in {"revoked", "expired"}
+            )
+            return {
+                "configured": True,
+                "workflows": workflows,
+                "grants": grants,
+                "summary": {
+                    "workflows": len(workflows),
+                    "grants": len(grants),
+                    "active_grants": active,
+                    "revoked_grants": sum(
+                        1 for item in grants if item.get("status") == "revoked"
+                    ),
+                },
+            }
+        finally:
+            connection.close()
+
+    def revoke_workflow(
+        self,
+        *,
+        provenance_id: str,
+        tenant_id: str,
+        principal_id: str,
+        reason: str,
+    ) -> Mapping[str, Any]:
+        store = SQLiteProvenanceStore(self.store_file)
+        try:
+            record = store.get(provenance_id)
+            if record.tenant_id != tenant_id:
+                raise KeyError("workflow provenance not found")
+            store.revoke(
+                record.provenance_id,
+                reason=reason,
+                principal_id=principal_id,
+            )
+            return {
+                "provenance_id": record.provenance_id,
+                "status": store.status(record.provenance_id).value,
+            }
+        finally:
+            store.close()
+
+    def revoke_grant(
+        self,
+        *,
+        grant_id: str,
+        tenant_id: str,
+        principal_id: str,
+        reason: str,
+    ) -> Mapping[str, Any]:
+        store = SQLiteGrantStore(self.store_file)
+        try:
+            grant = store.get(grant_id)
+            if grant.tenant_id != tenant_id:
+                raise KeyError("provenance grant not found")
+            store.revoke(
+                grant.grant_id,
+                reason=reason,
+                principal_id=principal_id,
+            )
+            return {
+                "grant_id": grant.grant_id,
+                "status": store.status(grant.grant_id).value,
+            }
+        finally:
+            store.close()
+
+
+class UnifiedPortalApplication:
+    """Role-aware portal facade over the existing production application."""
+
+    def __init__(
+        self,
+        base: CandidateApplication,
+        *,
+        provenance_store_file: str | Path,
+    ) -> None:
+        self.base = base
+        self.gateway = base.gateway
+        self.orchestrator = base.orchestrator
+        self.tracker = base.tracker
+        self.hermes = base.hermes
+        self.openclaw = base.openclaw
+        self.authorization_catalog = AuthorizationCatalog(provenance_store_file)
+
+    def context(self, headers: Mapping[str, str]) -> RequestContext:
+        return self.base.context(headers)
+
+    def _runtime(self, headers: Mapping[str, str]) -> Mapping[str, Any]:
+        status, payload = self.base.handle_json("GET", "/api/v2/runtime", headers, {})
+        if int(status) != HTTPStatus.OK:
+            raise RuntimeError("runtime status is unavailable")
+        return payload
+
+    def _gitops(self, context: RequestContext) -> Mapping[str, Any]:
+        return {
+            "tenant_id": context.tenant_id,
+            "gitops": collect_gitops_status().as_dict(),
+        }
+
+    def _tasks_view(self, context: RequestContext) -> list[Mapping[str, Any]]:
+        service = self.orchestrator.control_plane
+        tasks = service.list_tasks(context)
+        dispatches = {
+            item.task_id: item
+            for item in self.orchestrator.dispatch_repository.list(
+                tenant_id=context.tenant_id
+            )
+        }
+        evidence_by_task: dict[str, list[Any]] = {}
+        for evidence in self.tracker.list(tenant_id=context.tenant_id):
+            evidence_by_task.setdefault(evidence.task_id, []).append(evidence)
+        audit_by_task: dict[str, list[Any]] = {}
+        for event in service.list_audit_events(context):
+            if event.resource_type == "task":
+                audit_by_task.setdefault(event.resource_id, []).append(event)
+        capabilities = set(resolve(context).capabilities)
+        result: list[Mapping[str, Any]] = []
+        for task in tasks:
+            actions: list[str] = []
+            if task.state == TaskState.CREATED and "task.approve" in capabilities:
+                actions.append("approve")
+            if task.state in {TaskState.CREATED, TaskState.APPROVED, TaskState.RUNNING} and "task.cancel" in capabilities:
+                actions.append("cancel")
+            if task.state == TaskState.APPROVED and "task.dispatch" in capabilities:
+                actions.append("dispatch")
+            result.append(
+                {
+                    "task": _json_value(task),
+                    "dispatch": _json_value(dispatches.get(task.task_id)),
+                    "evidence": _json_value(evidence_by_task.get(task.task_id, [])),
+                    "audit": _json_value(audit_by_task.get(task.task_id, [])[-12:]),
+                    "available_actions": actions,
+                }
+            )
+        return result
+
+    def _overview(
+        self,
+        context: RequestContext,
+        headers: Mapping[str, str],
+    ) -> Mapping[str, Any]:
+        service = self.orchestrator.control_plane
+        capabilities = resolve(context)
+        sections: dict[str, Any] = {}
+        tasks = service.list_tasks(context) if allows(context, "task.read") else []
+        dispatches = (
+            self.orchestrator.dispatch_repository.list(tenant_id=context.tenant_id)
+            if allows(context, "dispatch.read")
+            else []
+        )
+        evidence = (
+            self.tracker.list(tenant_id=context.tenant_id)
+            if allows(context, "evidence.read")
+            else []
+        )
+        audit = (
+            service.list_audit_events(context)
+            if allows(context, "audit.read")
+            else []
+        )
+        if allows(context, "runtime.read"):
+            sections["runtime"] = self._runtime(headers)
+        if allows(context, "release.read"):
+            sections["release"] = {
+                **self._gitops(context),
+                "version": os.getenv("AIOS_RELEASE_VERSION", "V2R1C1"),
+                "release_oid": os.getenv("AIOS_RELEASE_OID", "unknown"),
+                "baseline": os.getenv("AIOS_BASELINE_VERSION", "V2R1C1"),
+                "status": os.getenv("AIOS_RELEASE_STATUS", "PRODUCTION_DEPLOYED"),
+            }
+        if allows(context, "provenance.read"):
+            sections["authorization"] = self.authorization_catalog.snapshot(
+                tenant_id=context.tenant_id
+            )["summary"]
+        task_states: dict[str, int] = {}
+        for task in tasks:
+            task_states[task.state.value] = task_states.get(task.state.value, 0) + 1
+        return {
+            "identity": capabilities.as_dict(),
+            "summary": {
+                "tasks": _safe_count(tasks),
+                "task_states": task_states,
+                "dispatches": _safe_count(dispatches),
+                "active_dispatches": sum(
+                    1
+                    for item in dispatches
+                    if item.state.value not in {"COMPLETED", "FAILED", "CANCELLED"}
+                ),
+                "evidence": _safe_count(evidence),
+                "audit_events": _safe_count(audit),
+            },
+            "sections": sections,
+            "recent": {
+                "tasks": _json_value(tasks[:8]),
+                "dispatches": _json_value(dispatches[-8:]),
+                "audit": _json_value(audit[-12:]),
+            },
+        }
+
+    def handle_json(
+        self,
+        method: str,
+        raw_path: str,
+        headers: Mapping[str, str],
+        body: Any,
+    ) -> tuple[int, Mapping[str, Any]]:
+        parsed = urllib.parse.urlparse(raw_path)
+        path = parsed.path.rstrip("/") or "/"
+        method = method.upper()
+
+        if not path.startswith("/api/v2/portal") and path != "/api/v2/me/capabilities":
+            return self.base.handle_json(method, raw_path, headers, body)
+
+        context = self.context(headers)
+        payload = _mapping(body or {})
+
+        if method == "GET" and path == "/api/v2/me/capabilities":
+            require(context, "portal.access")
+            return HTTPStatus.OK, resolve(context).as_dict()
+
+        if method == "GET" and path == "/api/v2/portal/overview":
+            require(context, "dashboard.read")
+            return HTTPStatus.OK, self._overview(context, headers)
+
+        if method == "GET" and path == "/api/v2/portal/tasks":
+            require(context, "task.read")
+            return HTTPStatus.OK, {"items": self._tasks_view(context)}
+
+        if method == "GET" and path == "/api/v2/portal/authorizations":
+            require(context, "provenance.read")
+            return HTTPStatus.OK, self.authorization_catalog.snapshot(
+                tenant_id=context.tenant_id
+            )
+
+        if method == "GET" and path == "/api/v2/portal/runtime":
+            require(context, "runtime.read")
+            return HTTPStatus.OK, {
+                **self._runtime(headers),
+                "dispatches": _json_value(
+                    self.orchestrator.dispatch_repository.list(
+                        tenant_id=context.tenant_id
+                    )
+                ),
+                "hermes_jobs": _json_value(
+                    self.hermes.list(tenant_id=context.tenant_id)
+                ),
+            }
+
+        if method == "GET" and path == "/api/v2/portal/evidence":
+            require(context, "evidence.read")
+            return HTTPStatus.OK, {
+                "executions": _json_value(
+                    self.tracker.list(tenant_id=context.tenant_id)
+                )
+            }
+
+        if method == "GET" and path == "/api/v2/portal/audit":
+            require(context, "audit.read")
+            return HTTPStatus.OK, {
+                "events": _json_value(
+                    self.orchestrator.control_plane.list_audit_events(context)
+                )
+            }
+
+        if method == "GET" and path == "/api/v2/portal/release":
+            require(context, "release.read")
+            return HTTPStatus.OK, {
+                **self._gitops(context),
+                "version": os.getenv("AIOS_RELEASE_VERSION", "V2R1C1"),
+                "release_oid": os.getenv("AIOS_RELEASE_OID", "unknown"),
+                "baseline": os.getenv("AIOS_BASELINE_VERSION", "V2R1C1"),
+                "status": os.getenv("AIOS_RELEASE_STATUS", "PRODUCTION_DEPLOYED"),
+                "operations": (
+                    ["review_release", "request_tag", "request_rollback"]
+                    if allows(context, "release.operate")
+                    else []
+                ),
+                "note": "Release operations remain GitOps approval requests; the portal does not mutate tags or production directly.",
+            }
+
+        if method == "POST" and path == "/api/v2/portal/tasks":
+            require(context, "task.create")
+            return self.base.handle_json("POST", "/api/v2/tasks", headers, payload)
+
+        task_action = re.fullmatch(
+            r"/api/v2/portal/tasks/([^/]+)/(approve|cancel|dispatch)", path
+        )
+        if method == "POST" and task_action:
+            action = task_action.group(2)
+            require(context, f"task.{action}")
+            task_id = urllib.parse.unquote(task_action.group(1))
+            target = (
+                f"/api/v2/tasks/{task_id}/dispatch"
+                if action == "dispatch"
+                else f"/api/v2/tasks/{task_id}/{action}"
+            )
+            return self.base.handle_json("POST", target, headers, payload)
+
+        workflow_revoke = re.fullmatch(
+            r"/api/v2/portal/provenance/([^/]+)/revoke", path
+        )
+        if method == "POST" and workflow_revoke:
+            require(context, "provenance.revoke")
+            reason = _required(payload.get("reason"), "reason")
+            result = self.authorization_catalog.revoke_workflow(
+                provenance_id=urllib.parse.unquote(workflow_revoke.group(1)),
+                tenant_id=context.tenant_id,
+                principal_id=context.principal_id,
+                reason=reason,
+            )
+            return HTTPStatus.OK, {"workflow": result}
+
+        grant_revoke = re.fullmatch(r"/api/v2/portal/grants/([^/]+)/revoke", path)
+        if method == "POST" and grant_revoke:
+            require(context, "provenance.revoke")
+            reason = _required(payload.get("reason"), "reason")
+            result = self.authorization_catalog.revoke_grant(
+                grant_id=urllib.parse.unquote(grant_revoke.group(1)),
+                tenant_id=context.tenant_id,
+                principal_id=context.principal_id,
+                reason=reason,
+            )
+            return HTTPStatus.OK, {"grant": result}
+
+        return HTTPStatus.NOT_FOUND, {
+            "error": "not_found",
+            "message": "portal route not found",
+        }
+
+
+def build_application() -> UnifiedPortalApplication:
+    state_dir = Path(os.getenv("AIOS_V2_STATE_DIR", "/var/lib/aios-v2")).resolve()
+    provenance_file = Path(
+        os.getenv(
+            "AIOS_PROVENANCE_STORE_FILE",
+            str(state_dir / "run-provenance.sqlite3"),
+        )
+    )
+    return UnifiedPortalApplication(
+        build_candidate_application(),
+        provenance_store_file=provenance_file,
+    )
+
+
+def main() -> None:
+    host = os.getenv("AIOS_V2_HOST", "127.0.0.1")
+    port = int(os.getenv("AIOS_V2_PORT", "18920"))
+    server = CandidateHTTPServer((host, port), build_application())
+    print(f"AIOS V2 unified portal listening on {host}:{port}")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,111 @@
+"""Server-side role and capability resolution for the unified AIOS portal."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Sequence
+
+from aios_v2.control_plane import RequestContext, Unauthorized
+
+
+ROLE_CAPABILITIES: Mapping[str, frozenset[str]] = {
+    "platform_admin": frozenset({
+        "portal.access", "dashboard.read", "tenant.read", "tenant.manage",
+        "agent.read", "agent.manage", "task.read", "task.create", "task.approve",
+        "task.cancel", "task.dispatch", "policy.read", "audit.read", "evidence.read",
+        "runtime.read", "runtime.operate", "dispatch.read", "provenance.read",
+        "provenance.revoke", "external_task.read", "gitops.read", "release.read",
+        "release.operate", "worktree.read", "system.admin",
+    }),
+    "tenant_admin": frozenset({
+        "portal.access", "dashboard.read", "tenant.read", "agent.read", "agent.manage",
+        "task.read", "task.create", "task.approve", "task.cancel", "task.dispatch",
+        "policy.read", "audit.read", "evidence.read", "runtime.read", "dispatch.read",
+        "provenance.read", "provenance.revoke", "external_task.read", "gitops.read",
+        "release.read",
+    }),
+    "operator": frozenset({
+        "portal.access", "dashboard.read", "tenant.read", "agent.read", "task.read",
+        "task.create", "task.cancel", "task.dispatch", "runtime.read", "dispatch.read",
+        "evidence.read", "provenance.read", "external_task.read", "gitops.read",
+        "release.read",
+    }),
+    "approver": frozenset({
+        "portal.access", "dashboard.read", "tenant.read", "task.read", "task.approve",
+        "task.cancel", "policy.read", "audit.read", "provenance.read", "evidence.read",
+        "external_task.read", "release.read",
+    }),
+    "auditor": frozenset({
+        "portal.access", "dashboard.read", "tenant.read", "agent.read", "task.read",
+        "audit.read", "evidence.read", "runtime.read", "dispatch.read",
+        "provenance.read", "external_task.read", "gitops.read", "release.read",
+        "worktree.read",
+    }),
+    "runtime": frozenset({
+        "portal.access", "dashboard.read", "task.read", "runtime.read", "runtime.operate",
+        "dispatch.read", "evidence.read", "provenance.read", "external_task.read",
+    }),
+    "release_manager": frozenset({
+        "portal.access", "dashboard.read", "audit.read", "runtime.read", "dispatch.read",
+        "provenance.read", "external_task.read", "gitops.read", "release.read",
+        "release.operate", "worktree.read",
+    }),
+    "viewer": frozenset({
+        "portal.access", "dashboard.read", "task.read", "runtime.read",
+        "external_task.read",
+    }),
+}
+
+
+NAVIGATION: Sequence[Mapping[str, str]] = (
+    {"id": "overview", "label": "总览", "capability": "dashboard.read"},
+    {"id": "resources", "label": "租户与 Agent", "capability": "tenant.read"},
+    {"id": "tasks", "label": "任务中心", "capability": "task.read"},
+    {"id": "execution", "label": "执行中心", "capability": "external_task.read"},
+    {"id": "authorization", "label": "授权中心", "capability": "provenance.read"},
+    {"id": "runtime", "label": "运行与运维", "capability": "runtime.read"},
+    {"id": "evidence", "label": "执行证据", "capability": "evidence.read"},
+    {"id": "audit", "label": "审计中心", "capability": "audit.read"},
+    {"id": "release", "label": "GitOps 与发布", "capability": "release.read"},
+)
+
+
+@dataclass(frozen=True)
+class ResolvedCapabilities:
+    tenant_id: str
+    principal_id: str
+    roles: tuple[str, ...]
+    capabilities: tuple[str, ...]
+    navigation: tuple[Mapping[str, str], ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "tenant_id": self.tenant_id,
+            "principal_id": self.principal_id,
+            "roles": list(self.roles),
+            "capabilities": list(self.capabilities),
+            "navigation": [dict(item) for item in self.navigation],
+        }
+
+
+def resolve(context: RequestContext) -> ResolvedCapabilities:
+    capabilities: set[str] = set()
+    for role in context.roles:
+        capabilities.update(ROLE_CAPABILITIES.get(role, ()))
+    ordered = tuple(sorted(capabilities))
+    navigation = tuple(item for item in NAVIGATION if item["capability"] in capabilities)
+    return ResolvedCapabilities(
+        tenant_id=context.tenant_id,
+        principal_id=context.principal_id,
+        roles=tuple(sorted(context.roles)),
+        capabilities=ordered,
+        navigation=navigation,
+    )
+
+
+def require(context: RequestContext, capability: str) -> None:
+    if capability not in resolve(context).capabilities:
+        raise Unauthorized(f"portal capability is required: {capability}")
+
+
+def allows(context: RequestContext, capability: str) -> bool:
+    return capability in resolve(context).capabilities
@@ -0,0 +1,48 @@
+"""Unified portal HTML export with V2R1C2 resource and execution centers.
+
+The canonical dependency-free portal remains in ``aios_v2.console``. This
+module applies deterministic, fail-fast extensions at import time so the
+V2R1C1 production entrypoint remains unchanged while the V2R1C2 candidate gets
+resource and portable-executor views.
+"""
+from __future__ import annotations
+
+from aios_v2.console import CONSOLE_HTML as _BASE_PORTAL_HTML
+
+
+def _extend_portal(source: str) -> str:
+    replacements = (
+        (
+            '<section id="overview" class="view active"></section>\n      <section id="tasks" class="view"></section>\n      <section id="authorization" class="view"></section>',
+            '<section id="overview" class="view active"></section>\n      <section id="resources" class="view"></section>\n      <section id="tasks" class="view"></section>\n      <section id="execution" class="view"></section>\n      <section id="authorization" class="view"></section>',
+        ),
+        (
+            "const labels={overview:'系统总览',tasks:'任务中心',authorization:'授权中心'",
+            "const labels={overview:'系统总览',resources:'租户与 Agent',tasks:'任务中心',execution:'执行中心',authorization:'授权中心'",
+        ),
+        (
+            "if(view==='overview')await overview();if(view==='tasks')await tasks();if(view==='authorization')await authorizations();",
+            "if(view==='overview')await overview();if(view==='resources')await resources();if(view==='tasks')await tasks();if(view==='execution')await execution();if(view==='authorization')await authorizations();",
+        ),
+        (
+            "async function tasks(){const d=await api('/api/v2/portal/tasks');",
+            """async function resources(){const d=await api('/api/v2/portal/resources');const t=d.tenant||{},agents=d.agents||[],ops=d.operations||{};const agentButton=ops.agent_create?'<button class=\"btn\" id=\"newAgent\">注册 Agent</button>':'';$('#resources').innerHTML=`<div class=\"cards\">${card('租户',t.tenant_id||'—',t.status||'')}${card('Agent',d.summary?.agents||0,`启用 ${d.summary?.enabled_agents||0}`)}${card('任务',d.summary?.tasks||0)}${card('Runtime 类型',(d.summary?.runtimes||[]).length,(d.summary?.runtimes||[]).join(', '))}</div><div class=\"grid\"><div class=\"panel\"><div class=\"panel-head\"><h2>当前租户</h2></div><div class=\"kv\"><div>Tenant ID</div><div>${esc(t.tenant_id||'—')}</div><div>名称</div><div>${esc(t.display_name||'—')}</div><div>状态</div><div>${pill(t.status||'unknown')}</div><div>创建时间</div><div>${esc(t.created_at||'—')}</div><div>更新时间</div><div>${esc(t.updated_at||'—')}</div></div></div><div class=\"panel\"><div class=\"panel-head\"><h2>Agent Registry</h2><div>${agentButton}</div></div>${table([['Agent',x=>esc(x.agent_id)],['名称',x=>esc(x.display_name)],['Runtime',x=>pill(x.runtime)],['能力',x=>(x.capabilities||[]).map(pill).join('')],['启用',x=>pill(x.enabled?'enabled':'disabled')],['任务数',x=>esc(x.task_count)]],agents)}</div></div>`;$('#newAgent')?.addEventListener('click',()=>{const agent_id=prompt('Agent ID');const display_name=prompt('显示名称',agent_id||'');const runtime=prompt('Runtime Provider','openclaw');const capabilities=prompt('能力，逗号分隔','');if(!agent_id||!display_name||!runtime)return;api('/api/v2/portal/agents',{method:'POST',body:JSON.stringify({agent_id,display_name,runtime,capabilities:String(capabilities||'').split(',').map(x=>x.trim()).filter(Boolean),metadata:{source:'unified-portal'}})}).then(resources).catch(err)})}
+function executionStage(x){const s=x.stage||{},status=x.truth||{},record=status.record||{},gate=status.gate||{},d=x.dependency_gate||{},notifications=gate.notifications||[],evidence=record.evidence||{};const stateName=record.state||'WAITING_DEPENDENCY';const deps=(s.depends_on||[]).join(', ')||'根阶段';return `<div class=\"panel\" style=\"background:#fbfcfe\"><div class=\"panel-head\"><h2>${esc(s.stage_id)} · ${esc(s.role)}</h2><div>${pill(stateName)} ${pill(s.executor_type)}</div></div><div class=\"chain\"><div class=\"chain-item\"><b>Provider</b><div>${esc(s.executor_type)}</div><small>${esc(deps)}</small></div><span class=\"chain-arrow\">→</span><div class=\"chain-item\"><b>Run</b><div>${esc(record.executor_run_id||'未注册')}</div><small>${esc(record.executor_id||'')}</small></div><span class=\"chain-arrow\">→</span><div class=\"chain-item\"><b>Progress</b><div>${esc(record.current_step||0)}/${esc((record.manifest?.steps||s.steps||[]).length)}</div><small>${esc(record.heartbeat_at||'无心跳')}</small></div><span class=\"chain-arrow\">→</span><div class=\"chain-item\"><b>Evidence</b><div>${Object.keys(evidence).length} 项</div><small>${Object.keys(evidence).slice(0,2).map(esc).join(', ')}</small></div><span class=\"chain-arrow\">→</span><div class=\"chain-item\"><b>Notification</b><div>${notifications.length} 条</div><small>${notifications.map(n=>n.status).join(', ')||'无'}</small></div><span class=\"chain-arrow\">→</span><div class=\"chain-item\"><b>Gate</b><div>${pill(gate.passed?'PASS':'BLOCKED')}</div><small>${d.passed?'依赖满足':'等待依赖'}</small></div></div>${Object.keys(record.error||{}).length?json(record.error):''}</div>`}
+async function execution(){const d=await api('/api/v2/portal/execution');const providers=d.providers||[],plans=d.plans||[];$('#execution').innerHTML=`<div class=\"cards\">${card('Provider',providers.length)}${card('Execution Plan',plans.length)}${card('协议',d.protocol_version||'—')}${card('Plan Schema',d.plan_schema_version||'—')}</div><div class=\"panel\"><div class=\"panel-head\"><h2>Executor Provider Catalog</h2></div>${table([['Provider',x=>esc(x.executor_type)],['Adapter',x=>esc(x.adapter_version)],['协议',x=>esc(x.protocol_version)],['Trust Roles',x=>(x.trust_roles||[]).map(pill).join('')],['Capabilities',x=>(x.capabilities||[]).map(pill).join('')]],providers)}</div>${plans.map(p=>`<div class=\"panel\"><div class=\"panel-head\"><h2>${esc(p.plan_id)} · ${esc(p.target_version)}</h2><div>${pill(p.gate?.passed?'PASS':'BLOCKED')}</div></div><div class=\"kv\"><div>Source Branch</div><div>${esc(p.source_branch)}</div><div>Source OID</div><div>${esc(p.source_oid)}</div><div>Release Gate</div><div>${pill(p.gate?.passed?'PASS':'BLOCKED')}</div></div></div>${(p.snapshot?.stages||[]).map(executionStage).join('')}`).join('')||'<div class=\"empty\">尚未声明执行计划</div>'}`}
+async function tasks(){const d=await api('/api/v2/portal/tasks');""",
+        ),
+    )
+    result = source
+    for old, new in replacements:
+        if old not in result:
+            raise RuntimeError(f"unified portal extension anchor not found: {old[:100]}")
+        result = result.replace(old, new, 1)
+    return result
+
+
+PORTAL_HTML = _extend_portal(_BASE_PORTAL_HTML)
+
+if "\n+function executionStage" in PORTAL_HTML or "\n+async function execution" in PORTAL_HTML:
+    raise RuntimeError("execution center contains an invalid diff marker")
+
+__all__ = ["PORTAL_HTML"]
@@ -0,0 +1,130 @@
+"""HTTP facade for portable multi-provider execution plans."""
+from __future__ import annotations
+
+import urllib.parse
+from http import HTTPStatus
+from typing import Any, Mapping
+
+from aios_v2.control_plane import RequestContext, Unauthorized
+from aios_v2.execution_plan import ExecutionPlanCoordinator
+from aios_v2.executor_protocol import ExecutorProviderRegistry, normalize_executor
+
+from .capabilities import require
+
+
+class ExecutionPlanAPI:
+    """Portal read model and provider-authenticated plan discovery API."""
+
+    INTERNAL_PREFIX = "/api/v2/internal/execution-plans"
+    PORTAL_PATH = "/api/v2/portal/execution"
+
+    def __init__(
+        self,
+        coordinator: ExecutionPlanCoordinator,
+        *,
+        providers: ExecutorProviderRegistry,
+    ) -> None:
+        self.coordinator = coordinator
+        self.providers = providers
+
+    @classmethod
+    def is_route(cls, raw_path: str) -> bool:
+        path = urllib.parse.urlparse(raw_path).path.rstrip("/") or "/"
+        return path == cls.PORTAL_PATH or path.startswith(cls.INTERNAL_PREFIX)
+
+    def _require_provider(
+        self,
+        context: RequestContext,
+        executor_type: str,
+    ) -> str:
+        normalized = normalize_executor(executor_type)
+        if not self.providers.trusted(
+            executor_type=normalized,
+            roles=tuple(context.roles),
+            platform_admin="platform_admin" in context.roles,
+        ):
+            raise Unauthorized(
+                f"trusted role for executor Provider is required: {normalized}"
+            )
+        return normalized
+
+    def _portal_snapshot(self) -> Mapping[str, Any]:
+        plans = []
+        for plan in self.coordinator.plan_store.list():
+            plans.append(
+                {
+                    "plan_id": plan.plan_id,
+                    "target_version": plan.target_version,
+                    "source_branch": plan.source_branch,
+                    "source_oid": plan.source_oid,
+                    "snapshot": self.coordinator.snapshot(plan.plan_id),
+                    "gate": self.coordinator.gate(plan.plan_id),
+                }
+            )
+        return {
+            "protocol_version": "aios.executor.v1",
+            "plan_schema_version": "aios.execution-plan.v2",
+            "providers": [
+                item.as_dict() for item in self.providers.list_descriptors()
+            ],
+            "plans": plans,
+        }
+
+    def handle(
+        self,
+        method: str,
+        raw_path: str,
+        context: RequestContext,
+        body: Any,
+    ) -> tuple[int, Mapping[str, Any]]:
+        del body
+        parsed = urllib.parse.urlparse(raw_path)
+        path = parsed.path.rstrip("/") or "/"
+        method = method.upper()
+
+        if method == "GET" and path == self.PORTAL_PATH:
+            require(context, "external_task.read")
+            return HTTPStatus.OK, self._portal_snapshot()
+
+        if not path.startswith(f"{self.INTERNAL_PREFIX}/"):
+            return HTTPStatus.NOT_FOUND, {
+                "error": "not_found",
+                "message": "execution plan route not found",
+            }
+
+        remainder = urllib.parse.unquote(path[len(self.INTERNAL_PREFIX) + 1 :])
+        parts = tuple(item for item in remainder.split("/") if item)
+        if len(parts) != 2:
+            return HTTPStatus.NOT_FOUND, {
+                "error": "not_found",
+                "message": "execution plan route not found",
+            }
+        plan_id, action = parts
+        query = urllib.parse.parse_qs(parsed.query)
+        executor_type = self._require_provider(
+            context,
+            str(query.get("executor", [""])[0]),
+        )
+
+        if method == "GET" and action == "discover":
+            items = self.coordinator.discover_ready(
+                plan_id=plan_id,
+                executor_type=executor_type,
+            )
+            return HTTPStatus.OK, {
+                "plan_id": plan_id,
+                "executor_type": executor_type,
+                "count": len(items),
+                "items": items,
+            }
+
+        if method == "GET" and action == "snapshot":
+            return HTTPStatus.OK, self.coordinator.snapshot(plan_id)
+
+        if method == "GET" and action == "gate":
+            return HTTPStatus.OK, self.coordinator.gate(plan_id)
+
+        return HTTPStatus.NOT_FOUND, {
+            "error": "not_found",
+            "message": "execution plan route not found",
+        }
@@ -0,0 +1,276 @@
+"""Protected HTTP facade for portable executor truth and notification receipts."""
+from __future__ import annotations
+
+import urllib.parse
+from http import HTTPStatus
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from aios_v2.control_plane import RequestContext, Unauthorized
+from aios_v2.executor_protocol import ExecutorProviderRegistry, normalize_executor
+from aios_v2.external_task_control import ExternalTaskCoordinator
+from aios_v2.external_task_query import list_records
+from aios_v2.task_execution_registry import ExecutionTruthState
+
+from .capabilities import require
+
+
+def _body(value: Any) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValueError("JSON body must be an object")
+    return value
+
+
+def _required(value: Any, label: str) -> str:
+    normalized = str(value or "").strip()
+    if not normalized:
+        raise ValueError(f"{label} is required")
+    return normalized
+
+
+def _mapping_strings(value: Any, label: str) -> dict[str, str]:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be an object")
+    return {
+        _required(key, f"{label} key"): _required(item, f"{label}[{key}]")
+        for key, item in value.items()
+    }
+
+
+class ExternalTaskAPI:
+    """Fail-closed external task API shared by every registered Provider."""
+
+    INTERNAL_PREFIX = "/api/v2/internal/external-tasks"
+
+    def __init__(
+        self,
+        coordinator: ExternalTaskCoordinator,
+        *,
+        store_file: str | Path,
+        providers: ExecutorProviderRegistry,
+    ) -> None:
+        self.coordinator = coordinator
+        self.store_file = Path(store_file).resolve()
+        self.providers = providers
+
+    @staticmethod
+    def is_route(path: str) -> bool:
+        normalized = path.rstrip("/") or "/"
+        return normalized.startswith(ExternalTaskAPI.INTERNAL_PREFIX) or normalized == "/api/v2/portal/external-tasks"
+
+    def _require_executor(self, context: RequestContext, executor_type: str) -> str:
+        normalized = normalize_executor(executor_type)
+        if not self.providers.trusted(
+            executor_type=normalized,
+            roles=tuple(context.roles),
+            platform_admin="platform_admin" in context.roles,
+        ):
+            raise Unauthorized(
+                f"trusted role for executor Provider is required: {normalized}"
+            )
+        return normalized
+
+    def _task_executor(self, task_id: str) -> str:
+        return normalize_executor(
+            self.coordinator.registry.get(task_id).manifest.executor
+        )
+
+    @staticmethod
+    def _executor_identity(
+        context: RequestContext,
+        payload: Mapping[str, Any],
+    ) -> str:
+        executor_id = _required(payload.get("executor_id"), "executor_id")
+        if executor_id != context.principal_id and "platform_admin" not in context.roles:
+            raise Unauthorized("executor_id must match trusted principal")
+        return executor_id
+
+    def declare_directory(self, directory: str | Path) -> list[Mapping[str, Any]]:
+        root = Path(directory).resolve()
+        if not root.exists():
+            return []
+        declared: list[Mapping[str, Any]] = []
+        for manifest in sorted(root.glob("*.json")):
+            record = self.coordinator.declare_file(manifest)
+            self.providers.validate_manifest(record.manifest)
+            declared.append(
+                {
+                    "manifest": str(manifest),
+                    "task_id": record.task_id,
+                    "executor_type": record.manifest.executor,
+                    "state": record.state.value,
+                }
+            )
+        return declared
+
+    def handle(
+        self,
+        method: str,
+        raw_path: str,
+        context: RequestContext,
+        body: Any,
+    ) -> tuple[int, Mapping[str, Any]]:
+        parsed = urllib.parse.urlparse(raw_path)
+        path = parsed.path.rstrip("/") or "/"
+        method = method.upper()
+        payload = _body(body or {})
+
+        if method == "GET" and path == "/api/v2/portal/external-tasks":
+            require(context, "external_task.read")
+            records = list_records(self.store_file)
+            return HTTPStatus.OK, {
+                "count": len(records),
+                "items": [self.coordinator.status(item.task_id) for item in records],
+            }
+
+        if method == "GET" and path == f"{self.INTERNAL_PREFIX}/discover":
+            query = urllib.parse.parse_qs(parsed.query)
+            states = tuple(query.get("state", ()))
+            executor = self._require_executor(
+                context,
+                str(query.get("executor", [""])[0]),
+            )
+            records = list_records(
+                self.store_file,
+                executor=executor,
+                states=states,
+            )
+            return HTTPStatus.OK, {
+                "count": len(records),
+                "executor_type": executor,
+                "items": [item.as_dict() for item in records],
+            }
+
+        if method == "GET" and path == f"{self.INTERNAL_PREFIX}/notifications":
+            query = urllib.parse.parse_qs(parsed.query)
+            executor = self._require_executor(
+                context,
+                str(query.get("executor", [""])[0]),
+            )
+            task_id = query.get("task_id", [None])[0]
+            status = query.get("status", [None])[0]
+            items = self.coordinator.notifications.list(
+                task_id=task_id,
+                status=status,
+            )
+            filtered = [
+                item
+                for item in items
+                if self._task_executor(item.task_id) == executor
+            ]
+            return HTTPStatus.OK, {
+                "count": len(filtered),
+                "executor_type": executor,
+                "items": [item.as_dict() for item in filtered],
+            }
+
+        notification_ack = self._match(
+            path,
+            f"{self.INTERNAL_PREFIX}/notifications/",
+            "/ack",
+        )
+        if method == "POST" and notification_ack:
+            notification = self.coordinator.notifications.get(notification_ack)
+            executor = self._task_executor(notification.task_id)
+            self._require_executor(context, executor)
+            self._executor_identity(context, payload)
+            record = self.coordinator.notifications.acknowledge(
+                notification_ack,
+                receipt_sha256=_required(
+                    payload.get("receipt_sha256"),
+                    "receipt_sha256",
+                ),
+            )
+            return HTTPStatus.OK, {"notification": record.as_dict()}
+
+        truth_task = self._match(path, f"{self.INTERNAL_PREFIX}/", "/truth")
+        if method == "GET" and truth_task:
+            self._require_executor(context, self._task_executor(truth_task))
+            return HTTPStatus.OK, self.coordinator.status(truth_task)
+
+        for action in ("register", "retry", "claim", "start", "heartbeat", "succeed", "fail"):
+            task_id = self._match(path, f"{self.INTERNAL_PREFIX}/", f"/{action}")
+            if method != "POST" or not task_id:
+                continue
+            executor_type = self._task_executor(task_id)
+            self._require_executor(context, executor_type)
+            run_id = _required(payload.get("executor_run_id"), "executor_run_id")
+            if action == "register":
+                return HTTPStatus.OK, {
+                    "record": self.coordinator.register(
+                        task_id,
+                        executor_run_id=run_id,
+                    ).as_dict()
+                }
+            if action == "retry":
+                return HTTPStatus.OK, {
+                    "record": self.coordinator.retry_not_started(
+                        task_id,
+                        executor_run_id=run_id,
+                    ).as_dict()
+                }
+            executor_id = self._executor_identity(context, payload)
+            if action == "claim":
+                record = self.coordinator.claim(
+                    task_id,
+                    executor_run_id=run_id,
+                    executor_id=executor_id,
+                )
+            elif action == "start":
+                record = self.coordinator.start(
+                    task_id,
+                    executor_run_id=run_id,
+                    executor_id=executor_id,
+                )
+            elif action == "heartbeat":
+                record = self.coordinator.heartbeat(
+                    task_id,
+                    executor_run_id=run_id,
+                    executor_id=executor_id,
+                    current_step=int(payload.get("current_step")),
+                )
+            elif action == "succeed":
+                record = self.coordinator.succeed(
+                    task_id,
+                    executor_run_id=run_id,
+                    executor_id=executor_id,
+                    evidence=_mapping_strings(payload.get("evidence"), "evidence"),
+                )
+            else:
+                error = payload.get("error")
+                if not isinstance(error, Mapping):
+                    raise ValueError("error must be an object")
+                evidence_value = payload.get("evidence")
+                evidence = (
+                    _mapping_strings(evidence_value, "evidence")
+                    if evidence_value is not None
+                    else None
+                )
+                record = self.coordinator.fail(
+                    task_id,
+                    executor_run_id=run_id,
+                    executor_id=executor_id,
+                    error=dict(error),
+                    evidence=evidence,
+                )
+            return HTTPStatus.OK, {"record": record.as_dict()}
+
+        return HTTPStatus.NOT_FOUND, {
+            "error": "not_found",
+            "message": "external task route not found",
+        }
+
+    @staticmethod
+    def _match(path: str, prefix: str, suffix: str) -> str | None:
+        if not path.startswith(prefix) or not path.endswith(suffix):
+            return None
+        middle = path[len(prefix) : len(path) - len(suffix)]
+        if not middle or "/" in middle:
+            return None
+        return urllib.parse.unquote(middle)
+
+
+DISCOVERABLE_STATES: Sequence[str] = (
+    ExecutionTruthState.DECLARED.value,
+    ExecutionTruthState.REGISTERED.value,
+)
@@ -0,0 +1,376 @@
+"""V2R1C2 unified portal and portable executor release entrypoint.
+
+The V2R1C1 production entrypoint remains unchanged. This candidate entrypoint
+uses an isolated state directory, loads a versioned executor catalog, declares
+portable multi-provider execution plans and exposes both portal read models and
+provider-authenticated lifecycle APIs.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.parse
+from dataclasses import replace
+from http import HTTPStatus
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+import aios_v2.app as candidate_app_module
+from aios_v2.app import (
+    CandidateApplication,
+    CandidateHTTPServer,
+    build_application as build_candidate_application,
+)
+from aios_v2.control_plane import RequestContext
+from aios_v2.execution_plan import ExecutionPlanCoordinator, ExecutionPlanManifest
+from aios_v2.executor_catalog import FileExecutorCatalogStore
+from aios_v2.official_executor_providers import official_provider_factories
+
+from .application import UnifiedPortalApplication, _json_value, _mapping
+from .capabilities import allows, require
+from .console import PORTAL_HTML
+from .execution_plan_api import ExecutionPlanAPI
+from .external_task_api import ExternalTaskAPI
+
+
+_READ_BRIDGE_ROLES = frozenset({"approver", "runtime", "viewer", "release_manager"})
+_GIT_OID = re.compile(r"^[0-9a-f]{40}$")
+
+
+def _resolve_environment_value(value: Any, *, label: str) -> Any:
+    if not isinstance(value, str) or not value.startswith("ENV:"):
+        return value
+    variable = value[4:].strip()
+    if not variable:
+        raise ValueError(f"{label} environment variable name is empty")
+    resolved = str(os.getenv(variable, "")).strip()
+    if not resolved:
+        raise RuntimeError(f"required environment variable is not set: {variable}")
+    return resolved
+
+
+def _load_execution_plan(path: str | Path) -> ExecutionPlanManifest:
+    source = Path(path).resolve()
+    value = json.loads(source.read_text(encoding="utf-8"))
+    if not isinstance(value, Mapping):
+        raise ValueError(f"execution plan must contain a JSON object: {source}")
+    payload = dict(value)
+    for label in ("source_branch", "source_oid", "target_version"):
+        payload[label] = _resolve_environment_value(payload.get(label), label=label)
+    source_oid = str(payload.get("source_oid") or "").strip().lower()
+    if not _GIT_OID.fullmatch(source_oid):
+        raise ValueError(
+            "execution plan source_oid must resolve to an exact 40-character Git OID"
+        )
+    payload["source_oid"] = source_oid
+    return ExecutionPlanManifest.from_dict(payload)
+
+
+def _path_list(value: str) -> tuple[Path, ...]:
+    return tuple(
+        Path(item).expanduser().resolve()
+        for item in value.split(os.pathsep)
+        if item.strip()
+    )
+
+
+class V2R1C2PortalApplication(UnifiedPortalApplication):
+    """Unified portal candidate with provider-neutral execution governance."""
+
+    def __init__(
+        self,
+        base: CandidateApplication,
+        *,
+        provenance_store_file: str | Path,
+        external_task_api: ExternalTaskAPI,
+        execution_plan_api: ExecutionPlanAPI,
+        plan_coordinator: ExecutionPlanCoordinator,
+        catalog_snapshot: Mapping[str, Any],
+        declared_plans: Sequence[str],
+    ) -> None:
+        super().__init__(base, provenance_store_file=provenance_store_file)
+        self.external_task_api = external_task_api
+        self.execution_plan_api = execution_plan_api
+        self.plan_coordinator = plan_coordinator
+        self.catalog_snapshot = dict(catalog_snapshot)
+        self.declared_plans = tuple(declared_plans)
+
+    def context(self, headers: Mapping[str, str]) -> RequestContext:
+        original = self.base.context(headers)
+        if original.roles.intersection(_READ_BRIDGE_ROLES):
+            return replace(original, roles=frozenset((*original.roles, "auditor")))
+        return original
+
+    def _resource_snapshot(self, context: RequestContext) -> Mapping[str, Any]:
+        service = self.orchestrator.control_plane
+        tenant = service.get_tenant(context)
+        agents = service.list_agents(context) if allows(context, "agent.read") else []
+        tasks = service.list_tasks(context) if allows(context, "task.read") else []
+        tasks_by_agent: dict[str, int] = {}
+        for task in tasks:
+            tasks_by_agent[task.agent_id] = tasks_by_agent.get(task.agent_id, 0) + 1
+        return {
+            "tenant": _json_value(tenant),
+            "agents": [
+                {
+                    **_json_value(agent),
+                    "task_count": tasks_by_agent.get(agent.agent_id, 0),
+                }
+                for agent in agents
+            ],
+            "summary": {
+                "agents": len(agents),
+                "enabled_agents": sum(1 for agent in agents if agent.enabled),
+                "tasks": len(tasks),
+                "runtimes": sorted({agent.runtime for agent in agents}),
+            },
+            "operations": {
+                "tenant_create": allows(context, "tenant.manage"),
+                "agent_create": allows(context, "agent.manage"),
+            },
+        }
+
+    def _runtime_snapshot(
+        self,
+        context: RequestContext,
+        headers: Mapping[str, str],
+    ) -> Mapping[str, Any]:
+        return {
+            **self._runtime(headers),
+            "dispatches": _json_value(
+                self.orchestrator.dispatch_repository.list(
+                    tenant_id=context.tenant_id
+                )
+            ),
+            "hermes_jobs": _json_value(
+                self.hermes.list_jobs(tenant_id=context.tenant_id)
+            ),
+            "contract": {
+                "openclaw": os.getenv(
+                    "AIOS_OPENCLAW_CONTRACT_VERSION",
+                    "aios.openclaw.command.v2",
+                ),
+                "signature_algorithm": os.getenv(
+                    "AIOS_OPENCLAW_SIGNATURE_ALGORITHM",
+                    "Ed25519",
+                ),
+                "plugin_version": os.getenv(
+                    "AIOS_OPENCLAW_PLUGIN_VERSION",
+                    "2.1.0-rc.4",
+                ),
+                "key_id": os.getenv(
+                    "AIOS_OPENCLAW_SIGNING_KEY_ID",
+                    "openclaw-v2r1-candidate-ed25519",
+                ),
+                "executor_protocol": "aios.executor.v1",
+                "execution_plan": "aios.execution-plan.v2",
+            },
+        }
+
+    def _release_snapshot(self, context: RequestContext) -> Mapping[str, Any]:
+        plans = []
+        for plan_id in self.declared_plans:
+            plans.append(
+                {
+                    "plan_id": plan_id,
+                    "gate": self.plan_coordinator.gate(plan_id),
+                }
+            )
+        aggregate_passed = bool(plans) and all(
+            item["gate"]["passed"] for item in plans
+        )
+        return {
+            **self._gitops(context),
+            "version": os.getenv("AIOS_RELEASE_VERSION", "V2R1C2-CANDIDATE"),
+            "target_version": os.getenv("AIOS_TARGET_VERSION", "V2R1C2"),
+            "release_oid": os.getenv("AIOS_RELEASE_OID", "candidate-not-tagged"),
+            "source_oid": os.getenv("AIOS_RELEASE_SOURCE_OID", "missing"),
+            "tag": os.getenv("AIOS_RELEASE_TAG", "NOT_CREATED"),
+            "baseline": os.getenv("AIOS_BASELINE_VERSION", "V2R1C1"),
+            "previous_version": os.getenv("AIOS_PREVIOUS_VERSION", "V2R1C1"),
+            "status": os.getenv("AIOS_RELEASE_STATUS", "CANDIDATE_VALIDATION"),
+            "evidence_manifest_sha256": os.getenv(
+                "AIOS_RELEASE_EVIDENCE_SHA256",
+                "pending",
+            ),
+            "executor_catalog": {
+                "path": self.catalog_snapshot.get("path"),
+                "sha256": self.catalog_snapshot.get("catalog_sha256"),
+                "protocol_version": "aios.executor.v1",
+            },
+            "execution_plans": plans,
+            "execution_gate": {
+                "passed": aggregate_passed,
+                "release_blocking": not aggregate_passed,
+            },
+            "operations": (
+                ["review_release", "request_tag", "request_rollback"]
+                if allows(context, "release.operate")
+                else []
+            ),
+            "note": (
+                "Release operations remain GitOps approval requests. The portal "
+                "never mutates tags, main, or production directly. Tag approval "
+                "must remain blocked until every required execution-plan gate passes."
+            ),
+        }
+
+    def handle_json(
+        self,
+        method: str,
+        raw_path: str,
+        headers: Mapping[str, str],
+        body: Any,
+    ) -> tuple[int, Mapping[str, Any]]:
+        parsed = urllib.parse.urlparse(raw_path)
+        path = parsed.path.rstrip("/") or "/"
+        method = method.upper()
+
+        if self.execution_plan_api.is_route(raw_path):
+            context = (
+                self.context(headers)
+                if path == ExecutionPlanAPI.PORTAL_PATH
+                else self.base.context(headers)
+            )
+            return self.execution_plan_api.handle(
+                method,
+                raw_path,
+                context,
+                body,
+            )
+
+        if self.external_task_api.is_route(path):
+            context = (
+                self.context(headers)
+                if path == "/api/v2/portal/external-tasks"
+                else self.base.context(headers)
+            )
+            return self.external_task_api.handle(
+                method,
+                raw_path,
+                context,
+                body,
+            )
+
+        context: RequestContext | None = None
+        if path in {
+            "/api/v2/portal/resources",
+            "/api/v2/portal/runtime",
+            "/api/v2/portal/release",
+            "/api/v2/portal/tenants",
+            "/api/v2/portal/agents",
+        }:
+            context = self.context(headers)
+
+        if method == "GET" and path == "/api/v2/portal/resources":
+            assert context is not None
+            require(context, "tenant.read")
+            return HTTPStatus.OK, self._resource_snapshot(context)
+
+        if method == "POST" and path == "/api/v2/portal/tenants":
+            assert context is not None
+            require(context, "tenant.manage")
+            return self.base.handle_json(
+                "POST",
+                "/api/v2/tenants",
+                headers,
+                _mapping(body),
+            )
+
+        if method == "POST" and path == "/api/v2/portal/agents":
+            assert context is not None
+            require(context, "agent.manage")
+            return self.base.handle_json(
+                "POST",
+                "/api/v2/agents",
+                headers,
+                _mapping(body),
+            )
+
+        if method == "GET" and path == "/api/v2/portal/runtime":
+            assert context is not None
+            require(context, "runtime.read")
+            return HTTPStatus.OK, self._runtime_snapshot(context, headers)
+
+        if method == "GET" and path == "/api/v2/portal/release":
+            assert context is not None
+            require(context, "release.read")
+            return HTTPStatus.OK, self._release_snapshot(context)
+
+        return super().handle_json(method, raw_path, headers, body)
+
+
+def build_application() -> V2R1C2PortalApplication:
+    state_dir = Path(
+        os.getenv("AIOS_V2_STATE_DIR", "/var/lib/aios-v2r1c2-portal")
+    ).resolve()
+    state_dir.mkdir(parents=True, exist_ok=True)
+    provenance_file = Path(
+        os.getenv(
+            "AIOS_PROVENANCE_STORE_FILE",
+            str(state_dir / "run-provenance.sqlite3"),
+        )
+    ).resolve()
+    truth_file = Path(
+        os.getenv(
+            "AIOS_EXTERNAL_TASK_STORE_FILE",
+            str(state_dir / "external-task-truth.sqlite3"),
+        )
+    ).resolve()
+    catalog_file = Path(
+        os.getenv(
+            "AIOS_EXECUTOR_CATALOG_FILE",
+            str(state_dir / "executor-catalog.json"),
+        )
+    ).resolve()
+
+    catalog_store = FileExecutorCatalogStore(catalog_file)
+    catalog_snapshot = catalog_store.initialize_defaults()
+    providers = catalog_store.registry(
+        provider_factories=official_provider_factories()
+    )
+    plan_coordinator = ExecutionPlanCoordinator.from_file(
+        truth_file,
+        providers=providers,
+    )
+
+    declared_plans: list[str] = []
+    plan_files = _path_list(os.getenv("AIOS_EXECUTION_PLAN_FILES", ""))
+    for plan_file in plan_files:
+        plan = _load_execution_plan(plan_file)
+        plan_coordinator.declare(plan)
+        declared_plans.append(plan.plan_id)
+
+    base: CandidateApplication = build_candidate_application()
+    external_task_api = ExternalTaskAPI(
+        plan_coordinator.task_coordinator,
+        store_file=truth_file,
+        providers=providers,
+    )
+    execution_plan_api = ExecutionPlanAPI(
+        plan_coordinator,
+        providers=providers,
+    )
+    return V2R1C2PortalApplication(
+        base,
+        provenance_store_file=provenance_file,
+        external_task_api=external_task_api,
+        execution_plan_api=execution_plan_api,
+        plan_coordinator=plan_coordinator,
+        catalog_snapshot=catalog_snapshot.as_dict(),
+        declared_plans=declared_plans,
+    )
+
+
+def main() -> None:
+    candidate_app_module.CONSOLE_HTML = PORTAL_HTML
+    host = os.getenv("AIOS_V2_HOST", "127.0.0.1")
+    port = int(os.getenv("AIOS_V2_PORT", "18921"))
+    server = CandidateHTTPServer((host, port), build_application())
+    print(f"AIOS V2R1C2 unified portal listening on {host}:{port}")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,355 @@
+"""Fail-closed access to the authoritative bare Git repository."""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import urllib.parse
+from pathlib import Path
+from typing import Iterable
+
+_ALLOWED_COMMANDS = frozenset(
+    {
+        "cat-file",
+        "config",
+        "diff",
+        "for-each-ref",
+        "ls-remote",
+        "merge-base",
+        "push",
+        "remote",
+        "rev-parse",
+        "show-ref",
+        "tag",
+    }
+)
+_OID_RE = re.compile(r"^[0-9a-f]{40}$")
+_MAX_OUTPUT = 1_048_576
+_TIMEOUT = 8.0
+
+
+class AuthoritativeGitError(RuntimeError):
+    """A fail-closed authoritative repository or ref query error."""
+
+
+class AuthoritativeGitNotFound(AuthoritativeGitError):
+    """A validated revision does not exist in the authoritative repository."""
+
+
+class AuthoritativeGitOutputTooLarge(AuthoritativeGitError):
+    """A controlled Git query exceeded the response-size boundary."""
+
+
+def _redact(text: str) -> str:
+    value = str(text or "")
+    value = re.sub(r"(?i)(authorization\s*[:=]\s*)(?:bearer|token)\s+\S+", r"\1REDACTED", value)
+    value = re.sub(r"(?i)((?:access_)?token\s*[:=]\s*)\S+", r"\1REDACTED", value)
+    value = re.sub(r"(?i)(https?://[^/\s:@]+:)[^@\s/]+@", r"\1REDACTED@", value)
+    return value
+
+
+def _configured_path(git_dir: str | Path | None = None) -> Path:
+    raw = str(git_dir or os.getenv("AIOS_GITOPS_AUTHORITATIVE_GIT_DIR", "")).strip()
+    if not raw:
+        raise AuthoritativeGitError("AUTHORITATIVE_REPOSITORY_UNAVAILABLE")
+    path = Path(raw)
+    if not path.is_absolute() or ".." in path.parts:
+        raise AuthoritativeGitError("AUTHORITATIVE_REPOSITORY_UNAVAILABLE")
+    try:
+        resolved = path.resolve(strict=True)
+    except OSError as exc:
+        raise AuthoritativeGitError("AUTHORITATIVE_REPOSITORY_UNAVAILABLE") from exc
+    if not resolved.is_dir():
+        raise AuthoritativeGitError("AUTHORITATIVE_REPOSITORY_UNAVAILABLE")
+    return resolved
+
+
+def _run(
+    git_dir: Path,
+    args: list[str],
+    *,
+    check: bool,
+    timeout: float = _TIMEOUT,
+) -> subprocess.CompletedProcess[str]:
+    if not args or args[0] not in _ALLOWED_COMMANDS:
+        raise AuthoritativeGitError("GIT_REF_QUERY_FAILED")
+    try:
+        result = subprocess.run(
+            ["git", "--git-dir", str(git_dir), *args],
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise AuthoritativeGitError("GIT_REF_QUERY_FAILED") from exc
+    if len(result.stdout) + len(result.stderr) > _MAX_OUTPUT:
+        raise AuthoritativeGitOutputTooLarge("GIT_OUTPUT_LIMIT_EXCEEDED")
+    if check and result.returncode != 0:
+        detail = _redact(result.stderr.strip() or result.stdout.strip())
+        raise AuthoritativeGitError(
+            "GIT_REF_QUERY_FAILED" + (f": {detail[:160]}" if detail else "")
+        )
+    return result
+
+
+def _repository_identity_from_remote(url: str) -> str:
+    value = str(url or "").strip().split("?", 1)[0].rstrip("/")
+    if not value:
+        return ""
+    if "://" in value:
+        value = urllib.parse.urlparse(value).path
+    elif ":" in value:
+        value = value.rsplit(":", 1)[1]
+    value = value.rsplit("@", 1)[-1].strip("/")
+    value = re.sub(r"\.git$", "", value, flags=re.IGNORECASE)
+    parts = [part for part in value.split("/") if part]
+    if len(parts) >= 2:
+        value = "/".join(parts[-2:])
+    return value.strip("/").lower()
+
+
+def verify_repository(
+    git_dir: str | Path | None = None,
+    repository_identity: str | None = None,
+) -> tuple[Path, str]:
+    path = _configured_path(git_dir)
+    expected = str(
+        repository_identity
+        or os.getenv("AIOS_GITOPS_REPOSITORY_IDENTITY", "")
+    ).strip().strip("/")
+    if not expected or expected.count("/") != 1:
+        raise AuthoritativeGitError("REPOSITORY_IDENTITY_MISMATCH")
+    bare = _run(path, ["rev-parse", "--is-bare-repository"], check=True)
+    if bare.stdout.strip().lower() != "true":
+        raise AuthoritativeGitError("AUTHORITATIVE_REPOSITORY_UNAVAILABLE")
+    remote = _run(path, ["config", "--get", "remote.gitea.url"], check=False)
+    actual = _repository_identity_from_remote(remote.stdout)
+    if actual != expected.lower():
+        raise AuthoritativeGitError("REPOSITORY_IDENTITY_MISMATCH")
+    return path, expected
+
+
+def run_authoritative_git(
+    args: list[str],
+    *,
+    check: bool = True,
+    git_dir: str | Path | None = None,
+    timeout: float = _TIMEOUT,
+) -> subprocess.CompletedProcess[str]:
+    path, _ = verify_repository(git_dir=git_dir)
+    return _run(path, list(args), check=check, timeout=timeout)
+
+
+def authoritative_head_oid(
+    *,
+    git_dir: str | Path | None = None,
+) -> str:
+    result = run_authoritative_git(["rev-parse", "--verify", "refs/heads/main"], git_dir=git_dir)
+    oid = result.stdout.strip().lower()
+    if not _OID_RE.fullmatch(oid):
+        raise AuthoritativeGitError("GIT_REF_QUERY_FAILED")
+    return oid
+
+
+def authoritative_tags(
+    *,
+    git_dir: str | Path | None = None,
+) -> list[dict[str, str | None]]:
+    result = run_authoritative_git(
+        [
+            "for-each-ref",
+            "refs/tags",
+            "--format=%(refname:strip=2)\t%(objectname)\t%(objecttype)",
+        ],
+        git_dir=git_dir,
+    )
+    tags: list[dict[str, str | None]] = []
+    for line in result.stdout.splitlines():
+        name, oid, object_type = (line.split("\t", 2) + ["", ""])[:3]
+        if not name or not _OID_RE.fullmatch(oid.lower()):
+            raise AuthoritativeGitError("GIT_REF_QUERY_FAILED")
+        peeled_result = run_authoritative_git(
+            ["rev-parse", "--verify", f"refs/tags/{name}^{{commit}}"],
+            git_dir=git_dir,
+        )
+        peeled = peeled_result.stdout.strip().lower()
+        if not _OID_RE.fullmatch(peeled):
+            raise AuthoritativeGitError("GIT_REF_QUERY_FAILED")
+        tags.append(
+            {
+                "name": name,
+                "tag_oid": oid.lower(),
+                "object_type": object_type,
+                "peeled_target_oid": peeled,
+            }
+        )
+    return tags
+
+
+def authoritative_branches(
+    *,
+    git_dir: str | Path | None = None,
+) -> list[dict[str, str]]:
+    result = run_authoritative_git(
+        [
+            "for-each-ref",
+            "refs/heads",
+            "--format=%(refname:strip=2)\t%(objectname)",
+        ],
+        git_dir=git_dir,
+    )
+    branches: list[dict[str, str]] = []
+    for line in result.stdout.splitlines():
+        name, oid = (line.split("\t", 1) + [""])[:2]
+        if not name or not _OID_RE.fullmatch(oid.lower()):
+            raise AuthoritativeGitError("GIT_REF_QUERY_FAILED")
+        branches.append({"name": name, "oid": oid.lower()})
+    return branches
+
+
+def authoritative_commit(
+    oid: str,
+    *,
+    git_dir: str | Path | None = None,
+) -> str:
+    value = str(oid or "").strip().lower()
+    if not _OID_RE.fullmatch(value):
+        raise ValueError("commit OID must be a full 40-character value")
+    result = run_authoritative_git(
+        ["rev-parse", "--verify", f"{value}^{{commit}}"],
+        git_dir=git_dir,
+    )
+    resolved = result.stdout.strip().lower()
+    if resolved != value:
+        raise AuthoritativeGitError("GIT_REF_QUERY_FAILED")
+    return resolved
+
+
+def authoritative_lineage(
+    ancestor: str,
+    descendant: str,
+    *,
+    git_dir: str | Path | None = None,
+) -> None:
+    authoritative_commit(ancestor, git_dir=git_dir)
+    authoritative_commit(descendant, git_dir=git_dir)
+    result = run_authoritative_git(
+        ["merge-base", "--is-ancestor", ancestor, descendant],
+        check=False,
+        git_dir=git_dir,
+    )
+    if result.returncode != 0:
+        raise AuthoritativeGitError("evidence lineage mismatch")
+
+
+_SAFE_REF_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$")
+
+
+def _safe_ref_name(value: str) -> bool:
+    return bool(
+        _SAFE_REF_RE.fullmatch(value)
+        and ".." not in value
+        and "//" not in value
+        and "@{" not in value
+        and not value.endswith(("/", ".", ".lock"))
+        and not any(part in {"", ".", ".."} for part in value.split("/"))
+    )
+
+
+def validate_git_revision(
+    value: str,
+    field: str,
+    *,
+    git_dir: str | Path | None = None,
+) -> str:
+    revision = str(value or "").strip()
+    if not revision or revision != str(value or "") or revision.startswith("-"):
+        raise ValueError(f"invalid {field} revision")
+    if _OID_RE.fullmatch(revision.lower()):
+        try:
+            return authoritative_commit(revision.lower(), git_dir=git_dir)
+        except AuthoritativeGitError as exc:
+            raise AuthoritativeGitNotFound(f"{field} revision not found") from exc
+    if not _safe_ref_name(revision) or any(token in revision for token in ("^", "~", ":", "\\")):
+        raise ValueError(f"invalid {field} revision")
+    if revision.startswith("refs/"):
+        if not revision.startswith(("refs/heads/", "refs/tags/")):
+            raise ValueError(f"invalid {field} revision")
+        candidates = [revision]
+    else:
+        candidates = [f"refs/heads/{revision}", f"refs/tags/{revision}"]
+    matches: list[str] = []
+    for candidate in candidates:
+        result = run_authoritative_git(
+            ["rev-parse", "--verify", f"{candidate}^{{commit}}"],
+            check=False,
+            git_dir=git_dir,
+        )
+        oid = result.stdout.strip().lower()
+        if result.returncode == 0 and _OID_RE.fullmatch(oid):
+            matches.append(oid)
+    if not matches:
+        raise AuthoritativeGitNotFound(f"{field} revision not found")
+    if len(set(matches)) != 1 or len(matches) != 1:
+        raise ValueError(f"ambiguous {field} revision")
+    return matches[0]
+
+
+def authoritative_diff(
+    from_revision: str,
+    to_revision: str,
+    *,
+    git_dir: str | Path | None = None,
+) -> dict[str, object]:
+    path, _ = verify_repository(git_dir=git_dir)
+    from_oid = validate_git_revision(from_revision, "from", git_dir=path)
+    to_oid = validate_git_revision(to_revision, "to", git_dir=path)
+    args = ["diff", "--no-ext-diff", "--no-textconv", from_oid, to_oid]
+    result = run_authoritative_git(args, git_dir=path)
+    return {
+        "code": 0,
+        "stdout": result.stdout,
+        "stderr": "",
+        "cmd": ["git", f"--git-dir={path}", *args],
+        "from_oid": from_oid,
+        "to_oid": to_oid,
+    }
+
+
+def repository_snapshot(
+    *,
+    git_dir: str | Path | None = None,
+    repository_identity: str | None = None,
+) -> dict[str, object]:
+    configured = bool(
+        str(git_dir or os.getenv("AIOS_GITOPS_AUTHORITATIVE_GIT_DIR", "")).strip()
+    )
+    try:
+        path, identity = verify_repository(
+            git_dir=git_dir,
+            repository_identity=repository_identity,
+        )
+        head = authoritative_head_oid(git_dir=path)
+        return {
+            "repository_available": True,
+            "authoritative_git_dir_configured": configured,
+            "authoritative_git_dir_readable": True,
+            "authoritative_git_dir": str(path),
+            "authoritative_head_oid": head,
+            "repository_identity": identity,
+            "query_error": None,
+        }
+    except (AuthoritativeGitError, ValueError) as exc:
+        return {
+            "repository_available": False,
+            "authoritative_git_dir_configured": configured,
+            "authoritative_git_dir_readable": False,
+            "authoritative_git_dir": None,
+            "authoritative_head_oid": None,
+            "repository_identity": str(
+                repository_identity
+                or os.getenv("AIOS_GITOPS_REPOSITORY_IDENTITY", "")
+            ).strip() or None,
+            "query_error": _redact(str(exc)),
+        }
@@ -0,0 +1,167 @@
+"""Fail-closed operation authorization for an isolated Git writer."""
+from __future__ import annotations
+
+import ipaddress
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from isolated_writer_token_registry import TokenRegistry
+
+
+ROUTE_OPERATIONS = {
+    ("GET", "/api/runtime-status"): "runtime.status.read",
+    ("GET", "/api/baseline"): "baseline.read",
+    ("GET", "/api/patches"): "patches.read",
+    ("POST", "/api/commit-file"): "commit_file.atomic",
+}
+OID_RE = re.compile(r"[0-9a-f]{40}")
+
+
+class AuthorizationError(PermissionError):
+    def __init__(self, code: str, status: int = 403):
+        super().__init__(code)
+        self.code = code
+        self.status = status
+
+
+@dataclass(frozen=True)
+class AuthorizedGrant:
+    record: dict[str, Any]
+    operation: str
+    use_count: int
+
+    @property
+    def token_id(self) -> str:
+        return str(self.record["token_id"])
+
+    @property
+    def task_id(self) -> str:
+        return str(self.record["task_id"])
+
+
+def operation_for(method: str, path: str) -> str:
+    operation = ROUTE_OPERATIONS.get((method.upper(), path))
+    if not operation:
+        raise AuthorizationError("isolated_writer_operation_forbidden")
+    return operation
+
+
+def _parse_time(value: Any) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        raise AuthorizationError("writer_token_time_invalid") from None
+    if parsed.tzinfo is None:
+        raise AuthorizationError("writer_token_time_invalid")
+    return parsed.astimezone(timezone.utc)
+
+
+def _git_is_ancestor(workspace: Path, base: str, branch: str) -> bool:
+    result = subprocess.run(
+        ["git", "merge-base", "--is-ancestor", base, branch],
+        cwd=workspace,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return result.returncode == 0
+
+
+def _validate_grant(
+    grant: dict[str, Any],
+    *,
+    audience: str,
+    source_ip: str,
+    operation: str,
+    branch: str | None,
+    path: str | None,
+    workspace: Path,
+    current_time: datetime,
+) -> None:
+    if int(grant.get("schema_version", 0)) != 2:
+        raise AuthorizationError("writer_token_policy_v2_required", 401)
+    if str(grant.get("audience") or "") != audience:
+        raise AuthorizationError("writer_token_audience_rejected")
+    try:
+        peer = ipaddress.ip_address(source_ip)
+        networks = [ipaddress.ip_network(str(value), strict=True) for value in grant.get("source_cidrs", [])]
+    except ValueError:
+        raise AuthorizationError("writer_token_source_rejected") from None
+    if not networks or not any(peer in network for network in networks):
+        raise AuthorizationError("writer_token_source_rejected")
+    created = _parse_time(grant.get("created_at"))
+    not_before = _parse_time(grant.get("not_before"))
+    expires = _parse_time(grant.get("expires_at"))
+    if expires <= not_before or (expires - created).total_seconds() > 1800:
+        raise AuthorizationError("writer_token_lifetime_rejected")
+    if current_time < not_before:
+        raise AuthorizationError("writer_token_not_yet_valid", 401)
+    if current_time >= expires:
+        raise AuthorizationError("writer_token_expired", 401)
+    if bool(grant.get("revoked")):
+        raise AuthorizationError("writer_token_revoked", 401)
+    operations = grant.get("allowed_operations")
+    if not isinstance(operations, list) or operation not in operations:
+        raise AuthorizationError("writer_token_operation_rejected")
+    expected_branch = str(grant.get("allowed_branch") or "")
+    configured_branch = os.getenv("AIOS_GITOPS_ALLOWED_BRANCH", "")
+    if expected_branch != configured_branch:
+        raise AuthorizationError("writer_token_branch_rejected")
+    if branch is not None and branch != expected_branch:
+        raise AuthorizationError("writer_token_branch_rejected")
+    if path is not None:
+        paths = grant.get("allowed_paths")
+        if not isinstance(paths, list) or path not in paths:
+            raise AuthorizationError("writer_token_path_rejected")
+    base = str(grant.get("approved_base_oid") or "").lower()
+    if not OID_RE.fullmatch(base):
+        raise AuthorizationError("writer_token_base_rejected")
+    if not _git_is_ancestor(workspace, base, expected_branch):
+        raise AuthorizationError("writer_token_base_not_ancestor")
+
+
+def authorize(
+    registry: TokenRegistry,
+    token: str,
+    *,
+    method: str,
+    path: str,
+    source_ip: str,
+    workspace: Path,
+    branch: str | None = None,
+    target_path: str | None = None,
+    current_time: datetime | None = None,
+) -> AuthorizedGrant:
+    if os.getenv("AIOS_GITOPS_TOKEN_POLICY_VERSION_REQUIRED", "") != "2":
+        raise AuthorizationError("writer_token_policy_v2_not_required")
+    if not token:
+        raise AuthorizationError("unauthorized", 401)
+    grant = registry.find(token)
+    if grant is None:
+        raise AuthorizationError("unauthorized", 401)
+    operation = operation_for(method, path)
+    _validate_grant(
+        grant,
+        audience=os.getenv("AIOS_GITOPS_SERVICE_AUDIENCE", ""),
+        source_ip=source_ip,
+        operation=operation,
+        branch=branch,
+        path=target_path,
+        workspace=workspace,
+        current_time=current_time or datetime.now(timezone.utc),
+    )
+    limits = grant.get("max_uses")
+    if not isinstance(limits, dict):
+        raise AuthorizationError("writer_token_use_limit_missing")
+    try:
+        used = registry.consume(str(grant["token_id"]), operation, int(limits[operation]))
+    except (KeyError, TypeError, ValueError):
+        raise AuthorizationError("writer_token_use_limit_missing") from None
+    except PermissionError as exc:
+        code = str(exc)
+        raise AuthorizationError(code, 401 if code == "writer_token_revoked" else 403) from None
+    return AuthorizedGrant(grant, operation, used)
@@ -0,0 +1,403 @@
+"""Atomic, idempotent commit-file Saga for the isolated writer."""
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import re
+import sqlite3
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+from typing import Any
+
+import aios_isolated_writer_policy as policy
+
+
+OID_RE = re.compile(r"[0-9a-f]{40}")
+IDEMPOTENCY_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{7,127}")
+STATES = frozenset({
+    "PENDING", "FILE_WRITTEN", "COMMITTED", "PUSHED", "VERIFIED", "COMPLETED",
+    "FAILED_RECOVERABLE", "MANUAL_REVIEW_REQUIRED",
+})
+_LOCKS: dict[str, threading.Lock] = {}
+_LOCKS_GUARD = threading.Lock()
+_LEDGER_INIT_LOCK = threading.Lock()
+
+
+class CommitFileError(RuntimeError):
+    def __init__(self, code: str, status: int = 400):
+        super().__init__(code)
+        self.code = code
+        self.status = status
+
+
+class SimulatedCrash(RuntimeError):
+    pass
+
+
+def canonical_digest(data: dict[str, Any]) -> str:
+    payload = {
+        "branch": data["branch"],
+        "path": data["path"],
+        "content_sha256": hashlib.sha256(data["content"].encode("utf-8")).hexdigest(),
+        "message": data["message"],
+        "expected_head_oid": data["expected_head_oid"],
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+class OperationLedger:
+    def __init__(self, path: Path | str):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if self.path.parent.is_symlink() or self.path.is_symlink():
+            raise PermissionError("writer_operation_ledger_symlink_rejected")
+        with _LEDGER_INIT_LOCK:
+            with self.connect() as db:
+                db.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS writer_operations (
+                        operation_id TEXT PRIMARY KEY,
+                        token_id TEXT NOT NULL,
+                        task_id TEXT NOT NULL,
+                        idempotency_key TEXT NOT NULL UNIQUE,
+                        operation_digest TEXT NOT NULL,
+                        branch TEXT NOT NULL,
+                        path TEXT NOT NULL,
+                        content_sha256 TEXT NOT NULL,
+                        pre_head_oid TEXT NOT NULL,
+                        commit_oid TEXT,
+                        push_status TEXT,
+                        verification_status TEXT,
+                        state TEXT NOT NULL,
+                        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                        updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                        error_code TEXT
+                    )
+                    """
+                )
+        os.chmod(self.path, 0o600)
+
+    def connect(self) -> sqlite3.Connection:
+        db = sqlite3.connect(self.path, timeout=30)
+        db.row_factory = sqlite3.Row
+        db.execute("PRAGMA journal_mode=WAL")
+        db.execute("PRAGMA synchronous=FULL")
+        return db
+
+    def get_or_create(self, grant: Any, data: dict[str, Any], digest: str) -> dict[str, Any]:
+        key = data["idempotency_key"]
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute(
+                "SELECT * FROM writer_operations WHERE idempotency_key=?", (key,)
+            ).fetchone()
+            if row:
+                db.commit()
+                record = dict(row)
+                if record["operation_digest"] != digest:
+                    raise CommitFileError("writer_idempotency_conflict", 409)
+                if (
+                    record["token_id"] != grant.token_id
+                    or record["task_id"] != grant.task_id
+                ):
+                    raise CommitFileError("writer_idempotency_owner_conflict", 409)
+                return record
+            operation_id = hashlib.sha256(
+                f"{grant.task_id}\0{key}".encode("utf-8")
+            ).hexdigest()
+            content_sha = hashlib.sha256(data["content"].encode("utf-8")).hexdigest()
+            db.execute(
+                """
+                INSERT INTO writer_operations(
+                    operation_id,token_id,task_id,idempotency_key,operation_digest,
+                    branch,path,content_sha256,pre_head_oid,state
+                ) VALUES(?,?,?,?,?,?,?,?,?,?)
+                """,
+                (
+                    operation_id, grant.token_id, grant.task_id, key, digest,
+                    data["branch"], data["path"], content_sha,
+                    data["expected_head_oid"], "PENDING",
+                ),
+            )
+            db.commit()
+        return self.get(key)
+
+    def get(self, key: str) -> dict[str, Any]:
+        with self.connect() as db:
+            row = db.execute(
+                "SELECT * FROM writer_operations WHERE idempotency_key=?", (key,)
+            ).fetchone()
+        if row is None:
+            raise KeyError(key)
+        return dict(row)
+
+    def update(self, key: str, state: str, **fields: Any) -> dict[str, Any]:
+        if state not in STATES:
+            raise ValueError("invalid writer operation state")
+        allowed = {"commit_oid", "push_status", "verification_status", "error_code"}
+        assignments = ["state=?", "updated_at=CURRENT_TIMESTAMP"]
+        values: list[Any] = [state]
+        for name, value in fields.items():
+            if name not in allowed:
+                raise ValueError("invalid ledger field")
+            assignments.append(f"{name}=?")
+            values.append(value)
+        values.append(key)
+        with self.connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            db.execute(
+                f"UPDATE writer_operations SET {','.join(assignments)} WHERE idempotency_key=?",
+                values,
+            )
+            db.commit()
+        return self.get(key)
+
+
+class AtomicCommitFile:
+    def __init__(
+        self,
+        *,
+        workspace: Path,
+        bare_repo: Path,
+        ledger: OperationLedger,
+        remote: str,
+        audit,
+        crash_after_state: str | None = None,
+    ):
+        self.workspace = workspace
+        self.bare_repo = bare_repo
+        self.ledger = ledger
+        self.remote = remote
+        self.audit = audit
+        self.crash_after_state = crash_after_state
+
+    def _git(self, *args: str, check: bool = True) -> str:
+        result = subprocess.run(
+            ["git", *args], cwd=self.workspace, text=True, capture_output=True
+        )
+        if check and result.returncode != 0:
+            raise CommitFileError("writer_git_operation_failed", 500)
+        return result.stdout.strip()
+
+    def _transition(self, key: str, state: str, **fields: Any) -> dict[str, Any]:
+        record = self.ledger.update(key, state, **fields)
+        if self.crash_after_state == state:
+            raise SimulatedCrash(state)
+        return record
+
+    def _validate(self, data: Any) -> dict[str, Any]:
+        if not isinstance(data, dict):
+            raise CommitFileError("writer_request_object_required")
+        required = ("branch", "path", "content", "message", "expected_head_oid", "idempotency_key")
+        if any(field not in data for field in required):
+            raise CommitFileError("writer_request_incomplete")
+        if data.get("force") or data.get("force_push"):
+            raise CommitFileError("isolated_writer_force_rejected", 403)
+        if set(data) != set(required):
+            raise CommitFileError("writer_request_fields_rejected")
+        item = {field: data[field] for field in required}
+        if item["branch"] != policy.allowed_branch():
+            raise CommitFileError("isolated_writer_branch_rejected", 403)
+        try:
+            item["path"] = policy.validate_path(item["path"], self.workspace)
+        except PermissionError as exc:
+            raise CommitFileError(str(exc), 403) from None
+        if not isinstance(item["content"], str) or "\x00" in item["content"]:
+            raise CommitFileError("writer_content_rejected")
+        try:
+            policy.validate_content_for_path(item["path"], item["content"])
+        except PermissionError as exc:
+            raise CommitFileError(str(exc), 403) from None
+        if len(item["content"].encode("utf-8")) > 1_048_576:
+            raise CommitFileError("writer_content_too_large", 413)
+        message = item["message"]
+        if (
+            not isinstance(message, str)
+            or not 1 <= len(message) <= 200
+            or "\x00" in message
+            or "\n" in message
+            or "\r" in message
+        ):
+            raise CommitFileError("writer_message_rejected")
+        if not isinstance(item["expected_head_oid"], str) or not OID_RE.fullmatch(item["expected_head_oid"]):
+            raise CommitFileError("writer_expected_head_rejected")
+        if not isinstance(item["idempotency_key"], str) or not IDEMPOTENCY_RE.fullmatch(item["idempotency_key"]):
+            raise CommitFileError("writer_idempotency_key_rejected")
+        return item
+
+    def _atomic_write(self, relative: str, content: str) -> None:
+        target = self.workspace / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(prefix=".writer-", dir=target.parent)
+        try:
+            with os.fdopen(fd, "wb", closefd=True) as stream:
+                stream.write(content.encode("utf-8"))
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, target)
+            parent_fd = os.open(target.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+            try:
+                os.fsync(parent_fd)
+            finally:
+                os.close(parent_fd)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+
+    def _verify_remote(self, branch: str, oid: str) -> None:
+        bare = subprocess.run(
+            ["git", "--git-dir", str(self.bare_repo), "rev-parse", f"refs/heads/{branch}"],
+            text=True, capture_output=True,
+        )
+        if bare.returncode != 0 or bare.stdout.strip() != oid:
+            raise CommitFileError("writer_authoritative_bare_oid_mismatch", 500)
+        remote = subprocess.run(
+            ["git", "ls-remote", "--heads", self.remote, f"refs/heads/{branch}"],
+            cwd=self.workspace, text=True, capture_output=True,
+        )
+        if remote.returncode != 0:
+            raise CommitFileError("writer_gitea_verification_failed", 503)
+        fields = remote.stdout.strip().split()
+        if len(fields) != 2:
+            raise CommitFileError("writer_gitea_ref_missing", 503)
+        if fields[0] != oid:
+            raise CommitFileError("writer_gitea_oid_conflict", 409)
+
+    def execute(self, grant: Any, raw_data: Any) -> dict[str, Any]:
+        data = self._validate(raw_data)
+        digest = canonical_digest(data)
+        branch = data["branch"]
+        with _LOCKS_GUARD:
+            lock = _LOCKS.setdefault(branch, threading.Lock())
+        lock_path = self.ledger.path.parent / f"{hashlib.sha256(branch.encode()).hexdigest()}.lock"
+        with lock, open(lock_path, "a+b") as branch_lock:
+            fcntl.flock(branch_lock.fileno(), fcntl.LOCK_EX)
+            return self._execute_locked(grant, data, digest)
+
+    def _execute_locked(self, grant: Any, data: dict[str, Any], digest: str) -> dict[str, Any]:
+        key = data["idempotency_key"]
+        record = self.ledger.get_or_create(grant, data, digest)
+        if record["state"] == "COMPLETED":
+            return self._result(record, idempotent=True)
+        if self._git("rev-parse", "--abbrev-ref", "HEAD") != data["branch"]:
+            record = self._transition(
+                key, "MANUAL_REVIEW_REQUIRED", error_code="writer_current_branch_conflict"
+            )
+            self._audit(grant, data, digest, record, "manual_review_required")
+            raise CommitFileError("writer_current_branch_conflict", 409)
+        head = self._git("rev-parse", "HEAD")
+        commit_oid = record.get("commit_oid")
+        if head != record["pre_head_oid"] and head != commit_oid:
+            record = self._transition(
+                key, "MANUAL_REVIEW_REQUIRED", error_code="writer_branch_head_conflict"
+            )
+            self._audit(grant, data, digest, record, "manual_review_required")
+            raise CommitFileError("writer_branch_head_conflict", 409)
+        try:
+            state = record["state"]
+            if state == "MANUAL_REVIEW_REQUIRED":
+                raise CommitFileError("writer_manual_review_required", 409)
+            if state == "FAILED_RECOVERABLE":
+                if record.get("push_status") == "confirmed":
+                    state = "PUSHED"
+                else:
+                    state = "COMMITTED" if commit_oid else "FILE_WRITTEN"
+            if state == "PENDING":
+                self._atomic_write(data["path"], data["content"])
+                record = self._transition(key, "FILE_WRITTEN")
+                state = record["state"]
+            if state == "FILE_WRITTEN":
+                actual_sha = hashlib.sha256(
+                    (self.workspace / data["path"]).read_bytes()
+                ).hexdigest()
+                if actual_sha != record["content_sha256"]:
+                    raise CommitFileError("writer_file_content_conflict", 409)
+                staged_before = self._git("diff", "--cached", "--name-only", check=False).splitlines()
+                if staged_before:
+                    raise CommitFileError("writer_extra_staged_files_rejected", 409)
+                self._git("add", "--", data["path"])
+                staged = self._git("diff", "--cached", "--name-only").splitlines()
+                if staged != [data["path"]]:
+                    raise CommitFileError("writer_extra_staged_files_rejected", 409)
+                self._git("commit", "-m", data["message"])
+                commit_oid = self._git("rev-parse", "HEAD")
+                record = self._transition(key, "COMMITTED", commit_oid=commit_oid)
+                state = record["state"]
+            if state == "COMMITTED":
+                commit_oid = str(record["commit_oid"])
+                pushed = subprocess.run(
+                    ["git", "push", "--porcelain", self.remote, f"HEAD:refs/heads/{data['branch']}"],
+                    cwd=self.workspace, text=True, capture_output=True,
+                )
+                if pushed.returncode != 0:
+                    self._transition(
+                        key, "FAILED_RECOVERABLE",
+                        push_status="failed", error_code="writer_gitea_push_failed",
+                    )
+                    raise CommitFileError("writer_gitea_push_failed", 503)
+                record = self._transition(key, "PUSHED", push_status="confirmed")
+                state = record["state"]
+            if state == "PUSHED":
+                commit_oid = str(record["commit_oid"])
+                self._verify_remote(data["branch"], commit_oid)
+                record = self._transition(
+                    key, "VERIFIED", verification_status="bare+gitea"
+                )
+                state = record["state"]
+            if state == "VERIFIED":
+                record = self._transition(key, "COMPLETED", error_code=None)
+            self._audit(grant, data, digest, record, "completed")
+            return self._result(record, idempotent=False)
+        except SimulatedCrash:
+            raise
+        except CommitFileError as exc:
+            latest = self.ledger.get(key)
+            if latest["state"] not in {"FAILED_RECOVERABLE", "MANUAL_REVIEW_REQUIRED"}:
+                failure_state = (
+                    "MANUAL_REVIEW_REQUIRED"
+                    if exc.code in {
+                        "writer_gitea_oid_conflict",
+                        "writer_file_content_conflict",
+                        "writer_current_branch_conflict",
+                    }
+                    else "FAILED_RECOVERABLE"
+                )
+                latest = self._transition(key, failure_state, error_code=exc.code)
+            self._audit(grant, data, digest, latest, "failed")
+            raise
+
+    def _audit(self, grant: Any, data: dict[str, Any], digest: str, record: dict[str, Any], result: str) -> None:
+        self.audit({
+            "token_id": grant.token_id,
+            "task_id": grant.task_id,
+            "audience": grant.record["audience"],
+            "source_ip": grant.record.get("_source_ip", "socket-peer"),
+            "operation": grant.operation,
+            "branch": data["branch"],
+            "path": data["path"],
+            "idempotency_key": data["idempotency_key"],
+            "operation_digest": digest,
+            "path_policy_sha256": policy.configured_path_policy_sha256(),
+            "pre_head_oid": record["pre_head_oid"],
+            "commit_oid": record.get("commit_oid"),
+            "result": result,
+        })
+
+    @staticmethod
+    def _result(record: dict[str, Any], *, idempotent: bool) -> dict[str, Any]:
+        return {
+            "status": "completed",
+            "state": record["state"],
+            "operation_id": record["operation_id"],
+            "branch": record["branch"],
+            "path": record["path"],
+            "commit_oid": record.get("commit_oid"),
+            "push_status": record.get("push_status"),
+            "verification_status": record.get("verification_status"),
+            "idempotent": idempotent,
+        }
@@ -0,0 +1,491 @@
+"""Strict service-level exact-path policy for isolated Git writers."""
+from __future__ import annotations
+
+import grp
+import hashlib
+import json
+import os
+import re
+import stat
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any
+from urllib.parse import unquote
+
+
+MAX_POLICY_BYTES = 65_536
+POLICY_FIELDS = frozenset(
+    {
+        "schema_version",
+        "policy_id",
+        "audience",
+        "repository_identity",
+        "allowed_branch",
+        "allowed_operations",
+    }
+)
+OPERATION_FIELDS = frozenset({"exact_paths", "max_content_bytes", "content_profile"})
+SUPPORTED_OPERATIONS = frozenset({"commit_file.atomic"})
+SUPPORTED_CONTENT_PROFILES = frozenset(
+    {
+        "systemd-codex-review-worker-v1",
+        "candidate-session-broker-source-v1",
+    }
+)
+_SECRET_RE = re.compile(
+    r"(?i)(authorization\s*:|bearer\s+|(?:token|password|secret)\s*[:=])"
+)
+_SYSTEMD_NAME_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*\Z")
+_SYSTEMD_MAX_LINE_BYTES = 4096
+_SYSTEMD_ALLOWED_DIRECTIVES = {
+    "Unit": frozenset({"Description", "After", "Wants"}),
+    "Service": frozenset(
+        {
+            "Type",
+            "User",
+            "Group",
+            "WorkingDirectory",
+            "Environment",
+            "ExecStart",
+            "Restart",
+            "RestartSec",
+            "NoNewPrivileges",
+            "PrivateTmp",
+            "PrivateDevices",
+            "ProtectSystem",
+            "ProtectHome",
+            "ProtectKernelTunables",
+            "ProtectKernelModules",
+            "ProtectControlGroups",
+            "LockPersonality",
+            "RestrictSUIDSGID",
+            "RestrictRealtime",
+            "MemoryDenyWriteExecute",
+            "RuntimeDirectory",
+            "StateDirectory",
+            "CacheDirectory",
+            "ReadOnlyPaths",
+            "ReadWritePaths",
+            "UMask",
+        }
+    ),
+    "Install": frozenset({"WantedBy"}),
+}
+_SYSTEMD_MULTI_DIRECTIVES = frozenset(
+    {
+        ("Service", "Environment"),
+        ("Service", "ReadOnlyPaths"),
+        ("Service", "ReadWritePaths"),
+    }
+)
+_SYSTEMD_EXACT_SINGLE_VALUES = {
+    ("Unit", "Description"): "AIOS Codex Review/Test Worker",
+    ("Unit", "After"): "network-online.target",
+    ("Unit", "Wants"): "network-online.target",
+    ("Service", "Type"): "simple",
+    ("Service", "User"): "aiman",
+    ("Service", "Group"): "gitops",
+    (
+        "Service",
+        "WorkingDirectory",
+    ): "/usr/libexec/aios-codex-review-test-worker/current",
+    (
+        "Service",
+        "ExecStart",
+    ): "/usr/bin/python3 -m task_plane.workers.codex_review_test",
+    ("Service", "Restart"): "on-failure",
+    ("Service", "RestartSec"): "2",
+    ("Service", "NoNewPrivileges"): "true",
+    ("Service", "PrivateTmp"): "true",
+    ("Service", "PrivateDevices"): "true",
+    ("Service", "ProtectSystem"): "strict",
+    ("Service", "ProtectHome"): "true",
+    ("Service", "ProtectKernelTunables"): "true",
+    ("Service", "ProtectKernelModules"): "true",
+    ("Service", "ProtectControlGroups"): "true",
+    ("Service", "LockPersonality"): "true",
+    ("Service", "RestrictSUIDSGID"): "true",
+    ("Service", "RestrictRealtime"): "true",
+    ("Service", "MemoryDenyWriteExecute"): "true",
+    ("Service", "RuntimeDirectory"): "aios-codex-review-test-worker",
+    ("Service", "StateDirectory"): "aios-codex-review-test-worker",
+    ("Service", "CacheDirectory"): "aios-codex-review-test-worker",
+    ("Service", "UMask"): "0077",
+    ("Install", "WantedBy"): "multi-user.target",
+}
+_SYSTEMD_EXACT_MULTI_VALUES = {
+    ("Service", "Environment"): (
+        "AIOS_CODEX_WORKER_MODE=shadow",
+        "AIOS_TASK_PLANE_EXECUTION_ENABLED=false",
+        "PYTHONDONTWRITEBYTECODE=1",
+    ),
+    ("Service", "ReadOnlyPaths"): (
+        "/data/aios-gitops/repo.git",
+        "/usr/libexec/aios-codex-review-test-worker",
+    ),
+    ("Service", "ReadWritePaths"): (
+        "/run/aios-codex-review-test-worker",
+        "/var/lib/aios-codex-review-test-worker",
+        "/var/cache/aios-codex-review-test-worker",
+    ),
+}
+
+
+class PathPolicyError(PermissionError):
+    pass
+
+
+@dataclass(frozen=True)
+class OperationPolicy:
+    exact_paths: tuple[str, ...]
+    max_content_bytes: int
+    content_profile: str
+
+
+@dataclass(frozen=True)
+class ServicePathPolicy:
+    schema_version: int
+    policy_id: str
+    audience: str
+    repository_identity: str
+    allowed_branch: str
+    allowed_operations: dict[str, OperationPolicy]
+    sha256: str
+
+    def operation(self, name: str) -> OperationPolicy:
+        try:
+            return self.allowed_operations[name]
+        except KeyError:
+            raise PathPolicyError("isolated_writer_service_operation_rejected") from None
+
+    def require_exact_path(self, operation: str, path: str) -> OperationPolicy:
+        selected = self.operation(operation)
+        if path not in selected.exact_paths:
+            raise PathPolicyError("isolated_writer_service_path_rejected")
+        return selected
+
+
+def _canonical_json(value: Any) -> bytes:
+    return (
+        json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        + "\n"
+    ).encode("utf-8")
+
+
+def validate_relative_path_syntax(path: str) -> str:
+    if not isinstance(path, str):
+        raise PathPolicyError("isolated_writer_path_rejected")
+    if not path or path != path.strip() or "\x00" in path or "\\" in path:
+        raise PathPolicyError("isolated_writer_path_rejected")
+    try:
+        decoded = unquote(path, errors="strict")
+    except (UnicodeDecodeError, ValueError):
+        raise PathPolicyError("isolated_writer_path_rejected") from None
+    if decoded != path:
+        raise PathPolicyError("isolated_writer_path_rejected")
+    posix = PurePosixPath(path)
+    windows = PureWindowsPath(path)
+    parts = path.split("/")
+    if (
+        posix.is_absolute()
+        or windows.is_absolute()
+        or bool(windows.drive)
+        or any(part in {"", ".", ".."} for part in parts)
+    ):
+        raise PathPolicyError("isolated_writer_path_rejected")
+    return path
+
+
+def _require_fields(value: dict[str, Any], allowed: frozenset[str], code: str) -> None:
+    if set(value) != allowed:
+        raise PathPolicyError(code)
+
+
+def _parse_policy(document: Any, canonical: bytes) -> ServicePathPolicy:
+    if not isinstance(document, dict):
+        raise PathPolicyError("isolated_writer_path_policy_object_required")
+    _require_fields(document, POLICY_FIELDS, "isolated_writer_path_policy_fields_rejected")
+    if document["schema_version"] != 1:
+        raise PathPolicyError("isolated_writer_path_policy_schema_rejected")
+    text_fields = (
+        "policy_id",
+        "audience",
+        "repository_identity",
+        "allowed_branch",
+    )
+    if any(
+        not isinstance(document[field], str) or not document[field].strip()
+        for field in text_fields
+    ):
+        raise PathPolicyError("isolated_writer_path_policy_value_rejected")
+    raw_operations = document["allowed_operations"]
+    if not isinstance(raw_operations, dict) or not raw_operations:
+        raise PathPolicyError("isolated_writer_path_policy_operations_rejected")
+    if not set(raw_operations).issubset(SUPPORTED_OPERATIONS):
+        raise PathPolicyError("isolated_writer_path_policy_operations_rejected")
+    operations: dict[str, OperationPolicy] = {}
+    for name, raw in raw_operations.items():
+        if not isinstance(raw, dict):
+            raise PathPolicyError("isolated_writer_path_policy_operation_rejected")
+        _require_fields(
+            raw,
+            OPERATION_FIELDS,
+            "isolated_writer_path_policy_operation_fields_rejected",
+        )
+        paths = raw["exact_paths"]
+        if (
+            not isinstance(paths, list)
+            or not paths
+            or any(not isinstance(item, str) for item in paths)
+        ):
+            raise PathPolicyError("isolated_writer_path_policy_paths_rejected")
+        validated = tuple(validate_relative_path_syntax(item) for item in paths)
+        if len(set(validated)) != len(validated):
+            raise PathPolicyError("isolated_writer_path_policy_paths_rejected")
+        maximum = raw["max_content_bytes"]
+        if not isinstance(maximum, int) or isinstance(maximum, bool) or not 1 <= maximum <= 1_048_576:
+            raise PathPolicyError("isolated_writer_path_policy_size_rejected")
+        profile = raw["content_profile"]
+        if profile not in SUPPORTED_CONTENT_PROFILES:
+            raise PathPolicyError("isolated_writer_path_policy_profile_rejected")
+        operations[name] = OperationPolicy(validated, maximum, profile)
+    return ServicePathPolicy(
+        schema_version=1,
+        policy_id=document["policy_id"],
+        audience=document["audience"],
+        repository_identity=document["repository_identity"],
+        allowed_branch=document["allowed_branch"],
+        allowed_operations=operations,
+        sha256=hashlib.sha256(canonical).hexdigest(),
+    )
+
+
+def load_path_policy(
+    path: Path,
+    *,
+    expected_owner_uid: int = 0,
+    expected_group_gid: int | None = None,
+    expected_parent_mode: int = 0o750,
+    expected_file_mode: int = 0o640,
+) -> ServicePathPolicy:
+    lexical = Path(os.path.abspath(str(path)))
+    if lexical.is_symlink():
+        raise PathPolicyError("isolated_writer_path_policy_symlink_rejected")
+    try:
+        parent_info = lexical.parent.stat(follow_symlinks=False)
+        file_info = lexical.stat(follow_symlinks=False)
+    except FileNotFoundError:
+        raise PathPolicyError("isolated_writer_path_policy_missing") from None
+    if stat.S_ISLNK(parent_info.st_mode) or not stat.S_ISDIR(parent_info.st_mode):
+        raise PathPolicyError("isolated_writer_path_policy_parent_rejected")
+    if stat.S_ISLNK(file_info.st_mode) or not stat.S_ISREG(file_info.st_mode):
+        raise PathPolicyError("isolated_writer_path_policy_file_rejected")
+    if lexical.resolve(strict=True) != lexical:
+        raise PathPolicyError("isolated_writer_path_policy_symlink_rejected")
+    if (
+        parent_info.st_uid != expected_owner_uid
+        or stat.S_IMODE(parent_info.st_mode) != expected_parent_mode
+    ):
+        raise PathPolicyError("isolated_writer_path_policy_parent_permissions_rejected")
+    if (
+        file_info.st_uid != expected_owner_uid
+        or stat.S_IMODE(file_info.st_mode) != expected_file_mode
+    ):
+        raise PathPolicyError("isolated_writer_path_policy_permissions_rejected")
+    if expected_group_gid is not None and (
+        parent_info.st_gid != expected_group_gid or file_info.st_gid != expected_group_gid
+    ):
+        raise PathPolicyError("isolated_writer_path_policy_group_rejected")
+    if file_info.st_size <= 0 or file_info.st_size > MAX_POLICY_BYTES:
+        raise PathPolicyError("isolated_writer_path_policy_file_size_rejected")
+    raw = lexical.read_bytes()
+    try:
+        document = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise PathPolicyError("isolated_writer_path_policy_json_rejected") from None
+    canonical = _canonical_json(document)
+    if raw != canonical:
+        raise PathPolicyError("isolated_writer_path_policy_not_canonical")
+    return _parse_policy(document, canonical)
+
+
+@lru_cache(maxsize=1)
+def configured_path_policy() -> ServicePathPolicy | None:
+    configured = os.getenv("AIOS_GITOPS_PATH_POLICY_FILE", "").strip()
+    if not configured:
+        return None
+    if not Path(configured).is_absolute():
+        raise PathPolicyError("isolated_writer_path_policy_path_rejected")
+    try:
+        gitops_gid = grp.getgrnam("gitops").gr_gid
+    except KeyError:
+        raise PathPolicyError("isolated_writer_path_policy_group_rejected") from None
+    loaded = load_path_policy(Path(configured), expected_group_gid=gitops_gid)
+    if loaded.audience != os.getenv("AIOS_GITOPS_SERVICE_AUDIENCE", ""):
+        raise PathPolicyError("isolated_writer_path_policy_audience_rejected")
+    if loaded.repository_identity != os.getenv("AIOS_GITOPS_REPOSITORY_IDENTITY", ""):
+        raise PathPolicyError("isolated_writer_path_policy_repository_rejected")
+    if loaded.allowed_branch != os.getenv("AIOS_GITOPS_ALLOWED_BRANCH", ""):
+        raise PathPolicyError("isolated_writer_path_policy_branch_rejected")
+    return loaded
+
+
+def clear_path_policy_cache() -> None:
+    configured_path_policy.cache_clear()
+
+
+def require_service_path(operation: str, path: str) -> OperationPolicy:
+    loaded = configured_path_policy()
+    if loaded is None:
+        raise PathPolicyError("isolated_writer_service_path_policy_required")
+    return loaded.require_exact_path(operation, path)
+
+
+def configured_path_policy_sha256() -> str | None:
+    loaded = configured_path_policy()
+    return None if loaded is None else loaded.sha256
+
+
+def validate_content(operation: str, path: str, content: str) -> None:
+    selected = require_service_path(operation, path)
+    try:
+        encoded = content.encode("utf-8", errors="strict")
+    except (AttributeError, UnicodeEncodeError):
+        raise PathPolicyError("isolated_writer_systemd_profile_rejected") from None
+    if len(encoded) > selected.max_content_bytes:
+        raise PathPolicyError("isolated_writer_service_content_too_large")
+    if selected.content_profile == "systemd-codex-review-worker-v1":
+        _validate_systemd_codex_review_worker(content)
+        return
+    if selected.content_profile == "candidate-session-broker-source-v1":
+        _validate_candidate_session_broker_source(path, content)
+        return
+    raise PathPolicyError("isolated_writer_path_policy_profile_rejected")
+
+
+def _validate_candidate_session_broker_source(path: str, content: str) -> None:
+    if (
+        not isinstance(content, str)
+        or "\x00" in content
+        or "\r" in content
+        or not content.endswith("\n")
+    ):
+        raise PathPolicyError("isolated_writer_candidate_source_profile_rejected")
+    forbidden = (
+        "BEGIN PRIVATE KEY",
+        "GITEA_DATABASE",
+        "gitea admin",
+        "ssh-keyscan",
+        "/home/aiman/.codex",
+        "/root/.codex",
+        "AIOS_GITOPS_ALLOW_MAIN_WRITE=true",
+        "AIOS_GITOPS_ALLOW_TAG_WRITE=true",
+        "AIOS_GITOPS_ALLOW_BASELINE_WRITE=true",
+        "AIOS_GITOPS_ALLOW_REGISTRY_WRITE=true",
+        "AIOS_TASK_PLANE_EXECUTION_ENABLED=true",
+        "AIOS_SILENT_RELEASE_EXECUTION_ENABLED=true",
+    )
+    if any(value in content for value in forbidden):
+        raise PathPolicyError("isolated_writer_candidate_source_profile_rejected")
+    if path.endswith(".py"):
+        try:
+            compile(content, path, "exec")
+        except (SyntaxError, ValueError, TypeError):
+            raise PathPolicyError("isolated_writer_candidate_source_profile_rejected") from None
+        return
+    if path.endswith(".service"):
+        if _SECRET_RE.search(content):
+            raise PathPolicyError("isolated_writer_candidate_source_profile_rejected")
+        required = (
+            "User=aiman",
+            "Group=gitops",
+            "UMask=0077",
+            "NoNewPrivileges=true",
+            "PrivateTmp=true",
+            "PrivateDevices=true",
+            "ProtectSystem=strict",
+            "ProtectHome=true",
+            "ProtectKernelTunables=true",
+            "ProtectKernelModules=true",
+            "ProtectControlGroups=true",
+            "LockPersonality=true",
+            "RestrictSUIDSGID=true",
+            "RestrictRealtime=true",
+            "127.0.0.1",
+        )
+        if any(value not in content for value in required):
+            raise PathPolicyError("isolated_writer_candidate_source_profile_rejected")
+        for line in content.splitlines():
+            if line.startswith("Environment=") and re.search(
+                r"(?i)(token|password|secret|private[_-]?key)=", line
+            ):
+                raise PathPolicyError("isolated_writer_candidate_source_profile_rejected")
+        return
+    raise PathPolicyError("isolated_writer_candidate_source_profile_rejected")
+
+
+def _validate_systemd_codex_review_worker(content: str) -> None:
+    if not isinstance(content, str):
+        raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+    try:
+        content.encode("utf-8", errors="strict")
+    except UnicodeEncodeError:
+        raise PathPolicyError("isolated_writer_systemd_profile_rejected") from None
+    if (
+        "\x00" in content
+        or "\r" in content
+        or _SECRET_RE.search(content)
+        or not content.endswith("\n")
+    ):
+        raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+
+    sections: set[str] = set()
+    values: dict[tuple[str, str], list[str]] = {}
+    section: str | None = None
+    for line in content.splitlines():
+        if len(line.encode("utf-8")) > _SYSTEMD_MAX_LINE_BYTES:
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+        if not line:
+            continue
+        if line[0].isspace() or line.startswith(("#", ";")):
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+        if line.startswith("[") and line.endswith("]"):
+            candidate = line[1:-1]
+            if (
+                not _SYSTEMD_NAME_RE.fullmatch(candidate)
+                or candidate not in _SYSTEMD_ALLOWED_DIRECTIVES
+                or candidate in sections
+            ):
+                raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+            sections.add(candidate)
+            section = candidate
+            continue
+        if section is None or "=" not in line:
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+        directive, value = line.split("=", 1)
+        if (
+            not _SYSTEMD_NAME_RE.fullmatch(directive)
+            or directive not in _SYSTEMD_ALLOWED_DIRECTIVES[section]
+            or not value
+            or value != value.strip()
+        ):
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+        key = (section, directive)
+        if key in values and key not in _SYSTEMD_MULTI_DIRECTIVES:
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+        values.setdefault(key, []).append(value)
+
+    if sections != set(_SYSTEMD_ALLOWED_DIRECTIVES):
+        raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+    if set(values) != set(_SYSTEMD_EXACT_SINGLE_VALUES) | set(
+        _SYSTEMD_EXACT_MULTI_VALUES
+    ):
+        raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+    for key, expected in _SYSTEMD_EXACT_SINGLE_VALUES.items():
+        if values.get(key) != [expected]:
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
+    for key, expected in _SYSTEMD_EXACT_MULTI_VALUES.items():
+        observed = values.get(key, [])
+        if len(observed) != len(set(observed)) or tuple(observed) != expected:
+            raise PathPolicyError("isolated_writer_systemd_profile_rejected")
@@ -0,0 +1,241 @@
+"""Digest-only, task-scoped token registry for isolated writers."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import hmac
+import json
+import os
+import grp
+import pwd
+import secrets
+import sqlite3
+import stat
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_REGISTRY_INIT_LOCK = threading.Lock()
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def token_digest(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+class TokenRegistry:
+    def __init__(self, path: Path | str):
+        self.path = Path(path)
+        self._prepare()
+
+    def _prepare(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if self.path.parent.is_symlink() or self.path.is_symlink():
+            raise PermissionError("writer_token_registry_symlink_rejected")
+        with _REGISTRY_INIT_LOCK:
+            with self._connect() as db:
+                db.executescript(
+                    """
+                    CREATE TABLE IF NOT EXISTS token_grants (
+                        token_id TEXT PRIMARY KEY,
+                        token_digest TEXT NOT NULL UNIQUE,
+                        grant_json TEXT NOT NULL,
+                        revoked INTEGER NOT NULL DEFAULT 0,
+                        created_at TEXT NOT NULL
+                    );
+                    CREATE TABLE IF NOT EXISTS token_uses (
+                        token_id TEXT NOT NULL,
+                        operation TEXT NOT NULL,
+                        use_count INTEGER NOT NULL DEFAULT 0,
+                        PRIMARY KEY(token_id, operation),
+                        FOREIGN KEY(token_id) REFERENCES token_grants(token_id)
+                    );
+                    """
+                )
+        os.chmod(self.path, 0o600)
+
+    def _connect(self) -> sqlite3.Connection:
+        db = sqlite3.connect(self.path, timeout=30, isolation_level=None)
+        db.row_factory = sqlite3.Row
+        db.execute("PRAGMA journal_mode=WAL")
+        db.execute("PRAGMA synchronous=FULL")
+        db.execute("PRAGMA foreign_keys=ON")
+        return db
+
+    def issue(self, grant: dict[str, Any], token: str | None = None) -> tuple[str, dict[str, Any]]:
+        value = token or secrets.token_urlsafe(32)
+        if len(value.encode("utf-8")) < 32:
+            raise ValueError("writer_token_entropy_insufficient")
+        record = dict(grant)
+        record["schema_version"] = 2
+        record["token_digest"] = token_digest(value)
+        record["revoked"] = False
+        record.setdefault("created_at", utc_now())
+        required = (
+            "token_id",
+            "audience",
+            "task_id",
+            "source_cidrs",
+            "allowed_branch",
+            "approved_base_oid",
+            "allowed_operations",
+            "allowed_paths",
+            "not_before",
+            "expires_at",
+            "max_uses",
+            "issued_by",
+        )
+        if any(not record.get(field) for field in required):
+            raise ValueError("writer_token_grant_incomplete")
+        encoded = json.dumps(record, sort_keys=True, separators=(",", ":"))
+        with self._connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            try:
+                db.execute(
+                    """
+                    INSERT INTO token_grants(token_id, token_digest, grant_json, revoked, created_at)
+                    VALUES(?,?,?,?,?)
+                    """,
+                    (
+                        str(record["token_id"]),
+                        str(record["token_digest"]),
+                        encoded,
+                        0,
+                        str(record["created_at"]),
+                    ),
+                )
+                db.execute("COMMIT")
+            except Exception:
+                db.execute("ROLLBACK")
+                raise
+        return value, record
+
+    def find(self, token: str) -> dict[str, Any] | None:
+        candidate = token_digest(token)
+        with self._connect() as db:
+            rows = db.execute(
+                "SELECT token_digest, grant_json, revoked FROM token_grants"
+            ).fetchall()
+        match = None
+        for row in rows:
+            if hmac.compare_digest(str(row["token_digest"]), candidate):
+                match = dict(json.loads(str(row["grant_json"])))
+                match["revoked"] = bool(row["revoked"])
+        return match
+
+    def consume(self, token_id: str, operation: str, maximum: int) -> int:
+        if maximum < 1:
+            raise PermissionError("writer_token_operation_exhausted")
+        with self._connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            try:
+                row = db.execute(
+                    "SELECT revoked FROM token_grants WHERE token_id=?",
+                    (token_id,),
+                ).fetchone()
+                if row is None or bool(row["revoked"]):
+                    raise PermissionError("writer_token_revoked")
+                used_row = db.execute(
+                    "SELECT use_count FROM token_uses WHERE token_id=? AND operation=?",
+                    (token_id, operation),
+                ).fetchone()
+                used = int(used_row["use_count"]) if used_row else 0
+                if used >= maximum:
+                    raise PermissionError("writer_token_operation_exhausted")
+                current = used + 1
+                db.execute(
+                    """
+                    INSERT INTO token_uses(token_id, operation, use_count)
+                    VALUES(?,?,?)
+                    ON CONFLICT(token_id, operation)
+                    DO UPDATE SET use_count=excluded.use_count
+                    """,
+                    (token_id, operation, current),
+                )
+                db.execute("COMMIT")
+                return current
+            except Exception:
+                db.execute("ROLLBACK")
+                raise
+
+    def revoke(self, token_id: str) -> bool:
+        with self._connect() as db:
+            db.execute("BEGIN IMMEDIATE")
+            changed = db.execute(
+                "UPDATE token_grants SET revoked=1 WHERE token_id=? AND revoked=0",
+                (token_id,),
+            ).rowcount
+            db.execute("COMMIT")
+        return bool(changed)
+
+    def usage(self, token_id: str, operation: str) -> int:
+        with self._connect() as db:
+            row = db.execute(
+                "SELECT use_count FROM token_uses WHERE token_id=? AND operation=?",
+                (token_id, operation),
+            ).fetchone()
+        return int(row["use_count"]) if row else 0
+
+
+def _write_secret_file(
+    path: Path,
+    token: str,
+    *,
+    owner: str | None = None,
+    group: str | None = None,
+) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.parent.is_symlink() or path.is_symlink():
+        raise PermissionError("writer_token_file_symlink_rejected")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(path, flags, 0o600)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise PermissionError("writer_token_file_not_regular")
+        if owner is not None or group is not None:
+            uid = pwd.getpwnam(owner).pw_uid if owner is not None else -1
+            gid = grp.getgrnam(group).gr_gid if group is not None else -1
+            os.fchown(fd, uid, gid)
+        os.write(fd, token.encode("utf-8"))
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--registry", required=True)
+    sub = parser.add_subparsers(dest="command", required=True)
+    issue = sub.add_parser("issue")
+    issue.add_argument("--grant-file", required=True)
+    issue.add_argument("--token-file", required=True)
+    issue.add_argument("--owner")
+    issue.add_argument("--group")
+    revoke = sub.add_parser("revoke")
+    revoke.add_argument("--token-id", required=True)
+    args = parser.parse_args(argv)
+    registry = TokenRegistry(args.registry)
+    if args.command == "issue":
+        grant = json.loads(Path(args.grant_file).read_text(encoding="utf-8"))
+        token, record = registry.issue(grant)
+        _write_secret_file(
+            Path(args.token_file),
+            token,
+            owner=args.owner,
+            group=args.group,
+        )
+        print(json.dumps({"token_id": record["token_id"], "created": True}, sort_keys=True))
+        return 0
+    changed = registry.revoke(args.token_id)
+    print(json.dumps({"token_id": args.token_id, "revoked": changed}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,564 @@
+#!/usr/bin/env python3
+"""Execution-readiness adapters and the fail-closed Shadow controller service."""
+from __future__ import annotations
+
+import argparse
+import base64
+import dataclasses
+import hashlib
+import json
+import os
+import subprocess
+import threading
+import time
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Callable, Mapping, Protocol
+from urllib.parse import parse_qs, urlparse
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+)
+
+from silent_release_controller import _sanitize, utc_now
+from silent_release_hardening import (
+    BuilderAttestation,
+    CapabilityAuthorizationError,
+    ReleaseRecoveryWorker,
+    SignedApprovalVerifier,
+    SignedReleasePlanApproval,
+    SilentReleaseActionService,
+    TrustedCandidateBundle,
+    _canonical_json,
+    _durable_json,
+    _safe_child,
+)
+
+
+class BuilderSigner(Protocol):
+    @property
+    def key_id(self) -> str:
+        ...
+
+    def sign(self, payload: bytes) -> bytes:
+        ...
+
+
+class LocalTestBuilderSigner:
+    """Ephemeral in-memory signer. It is forbidden for production execution."""
+
+    test_only = True
+
+    def __init__(self, key_id: str, private_key: Ed25519PrivateKey):
+        self._key_id = str(key_id)
+        self._private_key = private_key
+
+    @property
+    def key_id(self) -> str:
+        return self._key_id
+
+    @classmethod
+    def generate(
+        cls, key_id: str = "shadow-builder-test-key"
+    ) -> "LocalTestBuilderSigner":
+        return cls(key_id, Ed25519PrivateKey.generate())
+
+    @property
+    def public_key(self):
+        return self._private_key.public_key()
+
+    def sign(self, payload: bytes) -> bytes:
+        return self._private_key.sign(payload)
+
+
+class ExternalKmsBuilderSigner:
+    """Signer facade whose private operation remains in KMS/HSM."""
+
+    def __init__(
+        self,
+        key_id: str,
+        credential_reference: str,
+        sign_callback: Callable[[str, bytes], bytes],
+    ):
+        if not str(credential_reference).startswith(
+            ("kms://", "hsm://", "secret-manager://")
+        ):
+            raise ValueError("production builder requires a KMS/HSM reference")
+        self._key_id = str(key_id)
+        self.credential_reference = str(credential_reference)
+        self._sign_callback = sign_callback
+
+    @property
+    def key_id(self) -> str:
+        return self._key_id
+
+    def sign(self, payload: bytes) -> bytes:
+        return bytes(self._sign_callback(self.credential_reference, payload))
+
+
+class SignedTrustedBuilderAdapter:
+    """Signs evidence produced by a trusted collector, never caller evidence."""
+
+    def __init__(
+        self,
+        collector: Callable[[Mapping[str, Any]], TrustedCandidateBundle],
+        signer: BuilderSigner,
+    ):
+        self.collector = collector
+        self.signer = signer
+
+    def build(self, intent: Mapping[str, Any]) -> TrustedCandidateBundle:
+        forbidden = {
+            "artifact_sha256",
+            "canary",
+            "checks",
+            "manifest_sha256",
+            "tests",
+            "tree_oid",
+        }
+        if forbidden.intersection(intent):
+            raise CapabilityAuthorizationError(
+                "trusted builder rejects caller-supplied evidence"
+            )
+        unsigned = self.collector(dict(intent))
+        if unsigned.attestation is not None:
+            raise CapabilityAuthorizationError(
+                "collector cannot self-attest its evidence"
+            )
+        candidate = unsigned.candidate
+        test_sha = hashlib.sha256(
+            _canonical_json(_sanitize(candidate.tests))
+        ).hexdigest()
+        canary_sha = hashlib.sha256(
+            _canonical_json(_sanitize(candidate.canary))
+        ).hexdigest()
+        attestation_id = "builder-attestation-" + hashlib.sha256(
+            (
+                candidate.candidate_id
+                + "\0"
+                + candidate.source_commit
+                + "\0"
+                + candidate.artifact_sha256
+            ).encode("utf-8")
+        ).hexdigest()[:24]
+        attestation = BuilderAttestation(
+            builder_attestation_id=attestation_id,
+            builder_key_id=self.signer.key_id,
+            source_commit=candidate.source_commit,
+            tree_oid=candidate.tree_oid,
+            artifact_sha256=candidate.artifact_sha256,
+            manifest_sha256=candidate.manifest_sha256,
+            package_closure_sha256=(
+                unsigned.release_plan.deployment.package_closure_sha256
+            ),
+            test_evidence_sha256=test_sha,
+            canary_evidence_sha256=canary_sha,
+            issued_at=utc_now(),
+            signature="",
+        )
+        attestation = dataclasses.replace(
+            attestation,
+            signature=base64.b64encode(
+                self.signer.sign(attestation.canonical_bytes())
+            ).decode("ascii"),
+        )
+        return dataclasses.replace(unsigned, attestation=attestation)
+
+
+class ApprovalBackendAdapter(Protocol):
+    @property
+    def available(self) -> bool:
+        ...
+
+    def verify(
+        self,
+        approval: SignedReleasePlanApproval,
+        *,
+        candidate,
+        release_plan,
+        policy_sha256: str,
+    ) -> SignedReleasePlanApproval:
+        ...
+
+
+class LocalTestApprovalSigner:
+    """Test-only approval signer used solely for Shadow acceptance."""
+
+    test_only = True
+
+    def __init__(self, key_id: str, private_key: Ed25519PrivateKey):
+        self.key_id = str(key_id)
+        self.private_key = private_key
+
+    @classmethod
+    def generate(
+        cls, key_id: str = "shadow-owner-test-key"
+    ) -> "LocalTestApprovalSigner":
+        return cls(key_id, Ed25519PrivateKey.generate())
+
+    def sign(
+        self, approval: SignedReleasePlanApproval
+    ) -> SignedReleasePlanApproval:
+        unsigned = dataclasses.replace(
+            approval, key_id=self.key_id, signature=""
+        )
+        return dataclasses.replace(
+            unsigned,
+            signature=base64.b64encode(
+                self.private_key.sign(unsigned.canonical_bytes())
+            ).decode("ascii"),
+        )
+
+
+class ProductionApprovalBackendAdapter:
+    """Verification-only production adapter configured by a secret/KMS ref."""
+
+    def __init__(
+        self,
+        verifier: SignedApprovalVerifier,
+        credential_reference: str,
+    ):
+        if not str(credential_reference).startswith(
+            ("kms://", "hsm://", "secret-manager://")
+        ):
+            raise ValueError(
+                "production approval backend requires a KMS/secret reference"
+            )
+        self.verifier = verifier
+        self.credential_reference = str(credential_reference)
+
+    @property
+    def available(self) -> bool:
+        return True
+
+    def verify(
+        self,
+        approval: SignedReleasePlanApproval,
+        *,
+        candidate,
+        release_plan,
+        policy_sha256: str,
+    ) -> SignedReleasePlanApproval:
+        return self.verifier.verify_release_plan(
+            approval, candidate, release_plan, policy_sha256
+        )
+
+
+class UnavailableProductionApprovalBackend:
+    credential_reference = None
+
+    @property
+    def available(self) -> bool:
+        return False
+
+    def verify(self, *args, **kwargs):
+        raise CapabilityAuthorizationError(
+            "production approval backend is not configured"
+        )
+
+
+class LeaderLock:
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self.handle = None
+
+    def __enter__(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        os.chmod(self.path.parent, 0o700)
+        self.handle = self.path.open("a+", encoding="utf-8")
+        os.chmod(self.path, 0o600)
+        try:
+            import fcntl
+
+            fcntl.flock(
+                self.handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB
+            )
+        except BlockingIOError as exc:
+            self.handle.close()
+            self.handle = None
+            raise RuntimeError("silent release leader is already active") from exc
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        if self.handle is not None:
+            try:
+                import fcntl
+
+                fcntl.flock(self.handle.fileno(), fcntl.LOCK_UN)
+            finally:
+                self.handle.close()
+                self.handle = None
+
+
+class PersistentSilentReleaseController:
+    """Idempotent main-event controller with durable startup/recovery reports."""
+
+    def __init__(
+        self,
+        root: Path,
+        service: SilentReleaseActionService,
+        *,
+        main_probe: Callable[[], str],
+        recovery_worker: ReleaseRecoveryWorker | None = None,
+    ):
+        self.root = Path(root)
+        self.service = service
+        self.main_probe = main_probe
+        self.recovery_worker = recovery_worker
+        self.leader_path = self.root / "controller.leader.lock"
+        self.status_path = self.root / "controller-status.json"
+
+    def startup_verify(self) -> dict[str, Any]:
+        checked = 0
+        failed = 0
+        for journal in sorted(self.service.sagas.root.glob("*.events.jsonl")):
+            candidate_id = journal.name[: -len(".events.jsonl")]
+            saga = self.service.sagas.load(candidate_id)
+            checked += 1
+            if not saga.journal_integrity:
+                failed += 1
+        status = {
+            "checked_sagas": checked,
+            "execution_enabled": self.service.execution_enabled,
+            "failed_closed": failed,
+            "shadow_mode": not self.service.execution_enabled,
+            "side_effects_executed": False,
+            "status": "READY" if failed == 0 else "FAIL_CLOSED",
+        }
+        _durable_json(self.status_path, status)
+        return status
+
+    def run_once(self) -> dict[str, Any]:
+        with LeaderLock(self.leader_path):
+            startup = self.startup_verify()
+            if startup["status"] != "READY":
+                result = {
+                    "execution_enabled": self.service.execution_enabled,
+                    "intent": None,
+                    "notification": None,
+                    "recovery": None,
+                    "shadow_mode": not self.service.execution_enabled,
+                    "side_effects_executed": False,
+                    "startup": startup,
+                    "status": "FAIL_CLOSED",
+                }
+                _durable_json(self.status_path, result)
+                return _sanitize(result)
+            source_commit = str(self.main_probe())
+            event_id = f"main-{source_commit}"
+            intent = self.service.create_release_intent(
+                {"event_id": event_id, "source_commit": source_commit}
+            )
+            notification = None
+            if intent.get("candidate_id"):
+                notification = self.service.ensure_owner_notification(
+                    str(intent["candidate_id"])
+                )
+            recovery = (
+                self.recovery_worker.run_once()
+                if self.recovery_worker is not None
+                else self.service.get_recovery_status()
+            )
+            result = {
+                "execution_enabled": self.service.execution_enabled,
+                "intent": intent,
+                "notification": notification,
+                "recovery": recovery,
+                "shadow_mode": not self.service.execution_enabled,
+                "side_effects_executed": False,
+                "startup": startup,
+            }
+            _durable_json(self.status_path, result)
+            return _sanitize(result)
+
+
+class ShadowActionHandler(BaseHTTPRequestHandler):
+    service: SilentReleaseActionService
+    controller: PersistentSilentReleaseController
+
+    def log_message(self, fmt, *args):
+        return
+
+    def _json(self, payload: Mapping[str, Any], status=HTTPStatus.OK):
+        body = json.dumps(_sanitize(dict(payload)), sort_keys=True).encode()
+        self.send_response(int(status))
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _body(self) -> dict[str, Any]:
+        size = int(self.headers.get("Content-Length", "0"))
+        if size > 1024 * 1024:
+            raise ValueError("request body is too large")
+        return json.loads(self.rfile.read(size) or b"{}")
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        query = parse_qs(parsed.query)
+        candidate_id = str((query.get("candidate_id") or [""])[0])
+        try:
+            if parsed.path == "/healthz":
+                return self._json(
+                    {
+                        "execution_enabled": False,
+                        "shadow_mode": True,
+                        "side_effects_executed": False,
+                        "status": "ok",
+                    }
+                )
+            routes = {
+                "/getReleaseCandidate": self.service.get_release_candidate,
+                "/getReleasePlan": self.service.get_release_plan,
+                "/getReleaseAcceptance": self.service.get_acceptance,
+                "/getReleaseSaga": self.service.get_release_saga,
+                "/getCapabilityStatus": self.service.get_capability_status,
+            }
+            if parsed.path in routes:
+                return self._json(routes[parsed.path](candidate_id))
+            if parsed.path == "/getRecoveryStatus":
+                return self._json(self.service.get_recovery_status())
+            self._json({"error": "not_found"}, HTTPStatus.NOT_FOUND)
+        except (ValueError, FileNotFoundError) as exc:
+            self._json(
+                {"error": type(exc).__name__}, HTTPStatus.BAD_REQUEST
+            )
+
+    def do_POST(self):
+        parsed = urlparse(self.path)
+        try:
+            body = self._body()
+            if parsed.path == "/createReleaseIntent":
+                return self._json(self.service.create_release_intent(body))
+            if parsed.path in {
+                "/submitSignedApproval",
+                "/submitOwnerApproval",
+            }:
+                return self._json(self.service.submit_owner_approval(body))
+            if parsed.path == "/startDeployment":
+                return self._json(
+                    self.service.start_deployment(
+                        str(body.get("candidate_id") or "")
+                    )
+                )
+            self._json({"error": "not_found"}, HTTPStatus.NOT_FOUND)
+        except (ValueError, FileNotFoundError, CapabilityAuthorizationError) as exc:
+            self._json(
+                {"error": type(exc).__name__}, HTTPStatus.BAD_REQUEST
+            )
+
+
+def git_main_probe(repository: Path) -> Callable[[], str]:
+    repository = Path(repository)
+
+    def probe() -> str:
+        completed = subprocess.run(
+            [
+                "git",
+                f"--git-dir={repository}",
+                "rev-parse",
+                "refs/heads/main",
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=15,
+            env={"PATH": os.environ.get("PATH", "")},
+        )
+        return completed.stdout.strip()
+
+    return probe
+
+
+def serve_shadow(
+    *,
+    state_root: Path,
+    repository: Path,
+    host: str,
+    port: int,
+    poll_seconds: float,
+) -> None:
+    service = SilentReleaseActionService.shadow(state_root)
+    controller = PersistentSilentReleaseController(
+        state_root,
+        service,
+        main_probe=git_main_probe(repository),
+    )
+    controller.run_once()
+    stop = threading.Event()
+
+    def controller_loop() -> None:
+        while not stop.wait(poll_seconds):
+            try:
+                controller.run_once()
+            except Exception as exc:  # fail closed and keep the API available
+                _durable_json(
+                    controller.status_path,
+                    {
+                        "error": type(exc).__name__,
+                        "execution_enabled": False,
+                        "shadow_mode": True,
+                        "side_effects_executed": False,
+                        "status": "FAIL_CLOSED",
+                    },
+                )
+
+    handler = type(
+        "ConfiguredShadowActionHandler",
+        (ShadowActionHandler,),
+        {"service": service, "controller": controller},
+    )
+    server = ThreadingHTTPServer((host, port), handler)
+    api_thread = threading.Thread(
+        target=server.serve_forever,
+        name="silent-release-shadow-api",
+        daemon=False,
+    )
+    controller_thread = threading.Thread(
+        target=controller_loop,
+        name="silent-release-shadow-controller",
+        daemon=True,
+    )
+    api_thread.start()
+    controller_thread.start()
+    try:
+        while api_thread.is_alive():
+            api_thread.join(timeout=1)
+    finally:
+        stop.set()
+        server.shutdown()
+        server.server_close()
+        controller_thread.join(timeout=max(1.0, poll_seconds + 1.0))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--state-root", required=True, type=Path)
+    parser.add_argument("--repository", required=True, type=Path)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", default=18891, type=int)
+    parser.add_argument("--poll-seconds", default=30.0, type=float)
+    arguments = parser.parse_args()
+    if arguments.poll_seconds <= 0:
+        raise SystemExit("poll seconds must be positive")
+    if os.environ.get("AIOS_GITOPS_WRITES_ENABLED", "false").lower() != "false":
+        raise SystemExit("GitOps writes must remain disabled")
+    if (
+        os.environ.get(
+            "AIOS_SILENT_RELEASE_EXECUTION_ENABLED", "false"
+        ).lower()
+        != "false"
+    ):
+        raise SystemExit("Silent Release execution must remain disabled")
+    serve_shadow(
+        state_root=arguments.state_root,
+        repository=arguments.repository,
+        host=arguments.host,
+        port=arguments.port,
+        poll_seconds=arguments.poll_seconds,
+    )
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,21 @@
+"""Task Plane runtime package."""
+
+from .models import (
+    EvidenceEnvelope,
+    ProbeEvidence,
+    ProbeOutcome,
+    TaskPlan,
+    TaskRecord,
+    TaskStatus,
+    TaskStateTransitionError,
+)
+
+__all__ = [
+    "EvidenceEnvelope",
+    "ProbeEvidence",
+    "ProbeOutcome",
+    "TaskPlan",
+    "TaskRecord",
+    "TaskStatus",
+    "TaskStateTransitionError",
+]
@@ -0,0 +1,17 @@
+"""Adapters for executing tasks via worker backends."""
+
+from .base import WorkerAdapter
+from .openclaw import OpenClawAdapter
+from .codex import CodexAdapter
+from .hermes import HermesAdapter
+from .a2a import A2AAdapter
+from .systemd_worker import SystemdWorkerAdapter
+
+__all__ = [
+    "WorkerAdapter",
+    "OpenClawAdapter",
+    "CodexAdapter",
+    "HermesAdapter",
+    "A2AAdapter",
+    "SystemdWorkerAdapter",
+]
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .base import WorkerAdapter
+
+
+class A2AAdapter(WorkerAdapter):
+    worker_name = "a2a"
+
+    def capabilities(self) -> list[str]:
+        return ["task.exchange", "agent.handoff"]
+
+    def claim(self, task):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "claimed"}
+
+    def execute(self, task, claim):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "SHADOW_VERIFIED", "claim_id": claim.claim_id, "execution_mode": "shadow", "production_side_effects": False}
+
+    def heartbeat(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "alive"}
+
+    def report_progress(self, claim, progress):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "progress": progress}
+
+    def probe(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": claim.status}
+
+    def cancel(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "cancelled"}
+
+    def collect_result(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "result": "not_collected"}
@@ -0,0 +1,41 @@
+"""Base worker adapter contract."""
+
+from __future__ import annotations
+
+import abc
+
+
+class WorkerAdapter(abc.ABC):
+    worker_name = "base"
+
+    @abc.abstractmethod
+    def capabilities(self) -> list[str]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def claim(self, task):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def execute(self, task, claim):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def heartbeat(self, claim):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def report_progress(self, claim, progress):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def probe(self, claim):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def cancel(self, claim):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def collect_result(self, claim):
+        raise NotImplementedError
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .base import WorkerAdapter
+
+
+class CodexAdapter(WorkerAdapter):
+    worker_name = "codex"
+
+    def capabilities(self) -> list[str]:
+        return ["code.read", "code.write.patch", "test.python", "review.security"]
+
+    def claim(self, task):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "claimed"}
+
+    def execute(self, task, claim):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "SHADOW_VERIFIED", "claim_id": claim.claim_id, "execution_mode": "shadow", "production_side_effects": False}
+
+    def heartbeat(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "alive"}
+
+    def report_progress(self, claim, progress):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "progress": progress}
+
+    def probe(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": claim.status}
+
+    def cancel(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "cancelled"}
+
+    def collect_result(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "result": "not_collected"}
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .base import WorkerAdapter
+
+
+class HermesAdapter(WorkerAdapter):
+    worker_name = "hermes"
+
+    def capabilities(self) -> list[str]:
+        return ["architecture.review", "policy.review", "threat.model"]
+
+    def claim(self, task):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "claimed"}
+
+    def execute(self, task, claim):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "SHADOW_VERIFIED", "claim_id": claim.claim_id, "execution_mode": "shadow", "production_side_effects": False}
+
+    def heartbeat(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "alive"}
+
+    def report_progress(self, claim, progress):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "progress": progress}
+
+    def probe(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": claim.status}
+
+    def cancel(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "cancelled"}
+
+    def collect_result(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "result": "not_collected"}
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .base import WorkerAdapter
+
+
+class OpenClawAdapter(WorkerAdapter):
+    worker_name = "openclaw"
+
+    def capabilities(self) -> list[str]:
+        return ["code.read", "code.write.patch", "test.execute", "runtime.shadow"]
+
+    def claim(self, task):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "claimed"}
+
+    def execute(self, task, claim):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "SHADOW_VERIFIED", "claim_id": claim.claim_id, "execution_mode": "shadow", "production_side_effects": False}
+
+    def heartbeat(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "alive"}
+
+    def report_progress(self, claim, progress):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "progress": progress}
+
+    def probe(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": claim.status}
+
+    def cancel(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "cancelled"}
+
+    def collect_result(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "result": "not_collected"}
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from .base import WorkerAdapter
+
+
+class SystemdWorkerAdapter(WorkerAdapter):
+    worker_name = "systemd_worker"
+
+    def capabilities(self) -> list[str]:
+        return ["systemd.exec", "runtime.shell"]
+
+    def claim(self, task):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "claimed"}
+
+    def execute(self, task, claim):
+        return {"worker": self.worker_name, "task_id": task.task_id, "status": "SHADOW_VERIFIED", "claim_id": claim.claim_id, "execution_mode": "shadow", "production_side_effects": False}
+
+    def heartbeat(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "alive"}
+
+    def report_progress(self, claim, progress):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "progress": progress}
+
+    def probe(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": claim.status}
+
+    def cancel(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "status": "cancelled"}
+
+    def collect_result(self, claim):
+        return {"worker": self.worker_name, "claim_id": claim.claim_id, "result": "not_collected"}
@@ -0,0 +1,27 @@
+"""Agent registry abstraction."""
+
+from __future__ import annotations
+
+from .errors import NotFoundError
+
+
+class AgentRegistry:
+    def __init__(self):
+        self._agents: dict[str, dict] = {}
+
+    def register(self, agent_id: str, metadata: dict) -> None:
+        self._agents[agent_id] = {"agent_id": agent_id, **metadata}
+
+    def unregister(self, agent_id: str) -> None:
+        if agent_id not in self._agents:
+            raise NotFoundError("agent")
+        del self._agents[agent_id]
+
+    def list(self) -> list[dict]:
+        return list(self._agents.values())
+
+    def get(self, agent_id: str) -> dict:
+        try:
+            return self._agents[agent_id]
+        except KeyError:
+            raise NotFoundError("agent")
@@ -0,0 +1,557 @@
+"""Task Plane HTTP API implementation (stdlib-only)."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Callable
+
+from .delegation import DelegationEngine
+from .errors import (
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    PayloadTooLargeError,
+    TaskPlaneHTTPError,
+    UnauthorizedError,
+    ValidationError,
+)
+from .evidence import EvidenceService
+from .journal import TaskJournal
+from .lease import LeaseManager
+from .models import (
+    EvidenceEnvelope,
+    ResultEnvelope,
+    TaskPlan,
+    TaskRecord,
+    iso8601_now,
+    contains_secret_text,
+    validate_identifier,
+)
+from .policy import PolicyEngine
+from .store import TaskPlaneStore
+from .worker_registry import WorkerRegistry
+
+
+def _json_payload(data: dict[str, Any], status: int = 200) -> tuple[int, bytes]:
+    body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+    return status, body
+
+
+def _bounded_int(value: Any, name: str, minimum: int, maximum: int) -> int:
+    try:
+        number = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValidationError(f"invalid {name}") from exc
+    if not minimum <= number <= maximum:
+        raise ValidationError(f"invalid {name}")
+    return number
+
+
+class TaskPlaneService:
+    def __init__(self, store: TaskPlaneStore, policy: PolicyEngine | None = None):
+        self.store = store
+        self.policy = policy or PolicyEngine(
+            execution_enabled=False,
+            identity_capabilities={
+                "anon": {"task.creator", "task.read", "task.audit"}
+            },
+        )
+        self.journal = TaskJournal(store)
+        self.lease = LeaseManager(store)
+        self.workers = WorkerRegistry(store)
+        self.evidence = EvidenceService(store)
+        self.delegation = DelegationEngine(store)
+        self.store.probe_attestation_verifier = self.policy.probe_attestation_verifier
+
+    def create_task(self, body: dict[str, Any], idempotency_key: str | None = None) -> dict[str, Any]:
+        if body.get("parent_task_id"):
+            raise ForbiddenError("child tasks must use the delegate endpoint")
+        issuer = body.get("issuer", {})
+        actor = issuer.get("id", "anon") if isinstance(issuer, dict) else "anon"
+        self.policy.assert_allowed("create", actor)
+        try:
+            plan = TaskPlan.from_dict(body)
+        except (TypeError, ValueError) as exc:
+            raise ValidationError("invalid task plan") from exc
+        task = self.store.create_task_with_event(plan, idempotency_key=idempotency_key)
+        return task.to_dict()
+
+    def list_tasks(self, actor: str | None = None) -> list[dict[str, Any]]:
+        if actor is not None:
+            self.policy.assert_allowed("read", actor)
+        return [task.to_dict(include_task=False) for task in self.store.list_tasks()]
+
+    def get_task(self, task_id: str, actor: str | None = None) -> dict[str, Any]:
+        if actor is not None:
+            self.policy.assert_allowed("read", actor, task=self.store.get_task(task_id))
+        return self.store.get_task(task_id).to_dict()
+
+    def get_worker(self, worker_id: str, actor: str | None = None) -> dict[str, Any]:
+        if actor is not None:
+            self.policy.assert_allowed("read", actor)
+        return self.workers.get(worker_id).to_dict()
+
+    def list_workers(self, actor: str | None = None) -> list[dict[str, Any]]:
+        if actor is not None:
+            self.policy.assert_allowed("read", actor)
+        return [w.to_dict() for w in self.workers.list()]
+
+    def register_worker(self, body: dict[str, Any]) -> dict[str, Any]:
+        actor = str(body.get("actor_identity") or body.get("identity") or "")
+        is_admin = actor in self.policy.admin_identities
+        try:
+            existing = self.store.get_worker(str(body.get("worker_id") or ""))
+        except NotFoundError:
+            existing = None
+        if existing is not None and str(body.get("identity") or "") != existing.identity:
+            raise ConflictError("worker identity takeover rejected")
+        self.policy.assert_readonly_worker_registration(actor, body)
+        self.policy.assert_allowed(
+            "worker.admin" if is_admin else "worker.register", actor
+        )
+        try:
+            worker = self.workers.register(
+                body,
+                actor_identity=actor,
+                is_admin=is_admin,
+                expected_revision=body.get("expected_revision"),
+            )
+        except (TypeError, ValueError, KeyError) as exc:
+            raise ValidationError("invalid worker registration") from exc
+        return worker.to_dict()
+
+    def worker_heartbeat(self, worker_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        interval = payload.get("heartbeat_interval_seconds")
+        actor = str(payload.get("actor_identity") or "")
+        self.policy.assert_readonly_worker_binding(actor, worker_id)
+        self.policy.assert_allowed("worker.register", actor)
+        return self.workers.heartbeat(
+            worker_id,
+            heartbeat_interval_seconds=interval,
+            actor_identity=actor,
+            expected_revision=payload.get("expected_revision"),
+        ).to_dict()
+
+    def disable_worker(self, worker_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        actor = str(payload.get("actor_identity") or "")
+        self.policy.assert_allowed("worker.admin", actor)
+        return self.store.disable_worker(
+            worker_id,
+            actor_identity=actor,
+            expected_revision=int(payload.get("expected_revision")),
+            reason=str(payload.get("reason") or "disabled by administrator"),
+        ).to_dict()
+
+    def restore_worker(self, worker_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        actor = str(payload.get("actor_identity") or "")
+        self.policy.assert_allowed("worker.admin", actor)
+        return self.store.restore_worker(
+            worker_id,
+            actor_identity=actor,
+            expected_revision=int(payload.get("expected_revision")),
+        ).to_dict()
+
+    def claim(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        actor = body.get("actor_identity") or body.get("worker_identity") or "worker"
+        self.policy.assert_allowed("claim", actor)
+        worker_id = body.get("worker_id")
+        if not worker_id:
+            raise ValidationError("worker_id required")
+
+        task = self.store.get_task(task_id)
+        self.policy.assert_readonly_worker_binding(actor, str(worker_id))
+        self.policy.assert_allowed("claim", actor, task=task)
+        lease_seconds = _bounded_int(
+            body.get("lease_seconds", 30), "lease_seconds", 1, 3600
+        )
+        claim = self.lease.claim(
+            task_id=task_id,
+            worker_id=worker_id,
+            worker_identity=actor,
+            lease_seconds=lease_seconds,
+            expected_revision=task.revision,
+            operation_digest=task.task_plan.operation_digest(),
+        )
+        return {"claim_id": claim.claim_id, **claim.to_dict()}
+
+    def heartbeat(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        claim_id = body.get("claim_id")
+        if not claim_id:
+            raise ValidationError("claim_id required")
+        actor = body.get("actor_identity") or body.get("worker_identity") or "worker"
+        task = self.store.get_task(task_id)
+        claim = self.store.get_claim(claim_id)
+        self.policy.assert_readonly_worker_binding(actor, claim.worker_id)
+        self.policy.assert_allowed("heartbeat", actor, task=task)
+        if claim.worker_identity != actor:
+            raise ForbiddenError("claim identity mismatch")
+        lease_seconds = _bounded_int(
+            body.get("lease_seconds", 30), "lease_seconds", 1, 3600
+        )
+        claim = self.lease.heartbeat(task_id, claim_id, lease_seconds)
+        return {"claim_id": claim_id, "lease_until": claim.lease_until}
+
+    def progress(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        claim_id = body.get("claim_id")
+        if not claim_id:
+            raise ValidationError("claim_id required")
+        actor = body.get("actor_identity") or body.get("worker_identity") or "worker"
+        progress = body.get("progress")
+        stage = body.get("stage", "RUNNING")
+        message = body.get("message")
+        if progress is None:
+            raise ValidationError("progress required")
+        task = self.store.get_task(task_id)
+        claim = self.store.get_claim(claim_id)
+        self.policy.assert_readonly_worker_binding(actor, claim.worker_id)
+        self.policy.assert_allowed("progress", actor, task=task)
+        if task.task_plan.data_classification == "credential-secret":
+            if message not in {None, ""} or contains_secret_text(stage):
+                raise ValidationError(
+                    "credential-secret progress must contain metadata only"
+                )
+        lease_seconds = _bounded_int(
+            body.get("lease_seconds", 30), "lease_seconds", 1, 3600
+        )
+        claim = self.store.record_progress(
+            task_id,
+            claim_id,
+            actor,
+            progress=progress,
+            stage=str(stage),
+            message=None if message is None else str(message),
+            lease_seconds=lease_seconds,
+        )
+        return {"claim_id": claim.claim_id, "status": claim.status, "progress": progress}
+
+    def complete(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        claim_id = body.get("claim_id")
+        if not claim_id:
+            raise ValidationError("claim_id required")
+        actor = body.get("actor_identity") or body.get("worker_identity") or "worker"
+        task = self.store.get_task(task_id)
+
+        status = body.get("status", "COMPLETED")
+        outputs = body.get("outputs", [])
+        evidences = body.get("evidence", [])
+        if not isinstance(outputs, list):
+            raise ValidationError("outputs must be list")
+        if not isinstance(evidences, list):
+            raise ValidationError("evidence must be list")
+        if any(not isinstance(ev, dict) for ev in evidences):
+            raise ValidationError("evidence items must be objects")
+        claim = self.store.get_claim(claim_id)
+        self.policy.assert_readonly_worker_binding(actor, claim.worker_id)
+        self.policy.assert_allowed("result", actor, task=task)
+        if claim.worker_identity != actor:
+            raise ForbiddenError("claim identity mismatch")
+        if task.task_plan.data_classification == "credential-secret":
+            allowed_result_keys = {
+                "kind",
+                "hash",
+                "sha256",
+                "count",
+                "status",
+                "error_code",
+                "signature",
+                "attestation_ref",
+            }
+            for entry in [*outputs, *evidences]:
+                if (
+                    not isinstance(entry, dict)
+                    or set(entry) - allowed_result_keys
+                    or contains_secret_text(entry)
+                ):
+                    raise ValidationError(
+                        "credential-secret result must contain hash/count/status only"
+                    )
+
+        result = ResultEnvelope(
+            task_id=task_id,
+            claim_id=claim_id,
+            worker_identity=actor,
+            status=status,
+            outputs=outputs,
+            evidence=evidences,
+            started_at=str(body.get("started_at") or iso8601_now()),
+            completed_at=str(body.get("completed_at") or iso8601_now()),
+            result_digest=body.get("result_digest"),
+            signature=body.get("signature"),
+            attestation_ref=body.get("attestation_ref"),
+            operation_digest=claim.operation_digest,
+        )
+        evidence_decision = self.policy.evidence_verifier.verify(task, evidences)
+        if not evidence_decision.allowed:
+            raise ForbiddenError(evidence_decision.reason)
+        result_decision = self.policy.verify_result(result, task)
+        if not result_decision.allowed:
+            raise ForbiddenError(result_decision.reason)
+        result.result_digest = result.computed_digest()
+        previous = self.store._last_evidence_hash(task_id)
+        evidence_entries = []
+        for evidence in evidences:
+            envelope = EvidenceEnvelope.create(
+                task_id=task_id,
+                claim_id=claim_id,
+                kind=str(evidence.get("kind") or evidence.get("type") or "generic"),
+                worker_identity=actor,
+                payload=evidence,
+                previous_evidence_hash=previous,
+                signature=evidence.get("signature"),
+                attestation_ref=evidence.get("attestation_ref"),
+            )
+            evidence_entries.append(envelope)
+            previous = envelope.evidence_digest
+        self.store.complete_claim_with_evidence_and_event(
+            task_id,
+            claim_id,
+            status
+            if status
+            in {"COMPLETED", "FAILED_FINAL", "FAILED_RECOVERABLE", "CANCELLED"}
+            else "COMPLETED",
+            result.to_dict(),
+            evidence_entries,
+        )
+        return result.to_dict()
+
+    def fail(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        claim_id = body.get("claim_id")
+        if not claim_id:
+            raise ValidationError("claim_id required")
+        reason = body.get("reason", "failed")
+        actor = body.get("actor_identity") or body.get("worker_identity") or "worker"
+        self.policy.assert_allowed("fail", actor)
+        task = self.store.get_task(task_id)
+        self.policy.assert_allowed("fail", actor, task=task)
+        claim = self.store.get_claim(claim_id)
+        if claim.worker_identity != actor:
+            raise ForbiddenError("claim identity mismatch")
+        status = "FAILED_RECOVERABLE" if body.get("recoverable", False) else "FAILED_FINAL"
+        self.store.fail_claim_with_event(task_id, claim_id, status, str(reason))
+        return {"task_id": task_id, "status": status, "reason": reason}
+
+    def cancel(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        actor = body.get("actor_identity") or body.get("worker_identity") or "owner"
+        self.policy.assert_allowed("cancel", actor)
+        reason = body.get("reason", "cancelled")
+        task = self.store.get_task(task_id)
+        self.policy.assert_allowed("cancel", actor, task=task)
+        updated = self.store.cancel_task_with_event(
+            task_id, task.revision, reason=reason
+        )
+        return updated.to_dict()
+
+    def delegate(self, task_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        actor = body.get("actor_identity") or "owner"
+        self.policy.assert_allowed("delegate", actor)
+        parent = self.store.get_task(task_id)
+        self.policy.assert_allowed("delegate", actor, task=parent)
+        if "task" in body:
+            try:
+                child_plan = TaskPlan.from_dict(body["task"])
+            except (TypeError, ValueError) as exc:
+                raise ValidationError("invalid child task plan") from exc
+        else:
+            plan_body = dict(body)
+            plan_body.pop("actor_identity", None)
+            try:
+                child_plan = TaskPlan.from_dict(plan_body)
+            except (TypeError, ValueError) as exc:
+                raise ValidationError("invalid child task plan") from exc
+        child_plan.parent_task_id = task_id
+        child = self.delegation.delegate(task_id, child_plan, caller=actor)
+        return child.to_dict()
+
+    def get_events(self, task_id: str, actor: str | None = None) -> list[dict[str, Any]]:
+        if actor is not None:
+            self.policy.assert_allowed("audit", actor, task=self.store.get_task(task_id))
+        self.store.get_task(task_id)
+        return self.store.list_events(task_id)
+
+    def get_evidence(self, task_id: str, actor: str | None = None) -> list[dict[str, Any]]:
+        if actor is not None:
+            self.policy.assert_allowed("audit", actor, task=self.store.get_task(task_id))
+        self.store.get_task(task_id)
+        return self.evidence.list(task_id)
+
+    def get_children(self, task_id: str, actor: str | None = None) -> list[str]:
+        if actor is not None:
+            self.policy.assert_allowed("read", actor, task=self.store.get_task(task_id))
+        self.store.get_task(task_id)
+        return self.store.list_children(task_id)
+
+
+class TaskPlaneRequestHandler(BaseHTTPRequestHandler):
+    service: TaskPlaneService | None = None
+    authenticator: Callable[[str], str | None] | None = None
+    max_body_bytes = 1_000_000
+
+    def log_message(self, format: str, *args: Any) -> None:
+        # BaseHTTPRequestHandler logs the raw request target; suppress it so
+        # attacker-controlled paths or query strings cannot leak credentials.
+        return
+
+    def _json(self) -> tuple[str | None, dict[str, Any]]:
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+        except ValueError as exc:
+            raise ValidationError("invalid content length") from exc
+        if length < 0:
+            raise ValidationError("invalid content length")
+        if length > self.max_body_bytes:
+            raise PayloadTooLargeError("payload exceeds limit")
+        raw = self.rfile.read(length) if length > 0 else b""
+        if not raw:
+            return None, {}
+        try:
+            decoded = raw.decode("utf-8")
+            payload = json.loads(decoded)
+            if not isinstance(payload, dict):
+                raise ValidationError("JSON payload must be an object")
+            return decoded, payload
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ValidationError("invalid JSON payload") from exc
+
+    def _response(self, status: int, payload: Any) -> None:
+        encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def _authenticated_identity(self) -> str:
+        authenticator = type(self).authenticator
+        if authenticator is None:
+            raise UnauthorizedError("authentication unavailable")
+        header = self.headers.get("Authorization", "")
+        if not header.startswith("Bearer "):
+            raise UnauthorizedError("bearer authentication required")
+        token = header[7:]
+        if not token or any(ord(ch) < 33 for ch in token):
+            raise UnauthorizedError("invalid bearer token")
+        identity = authenticator(token)
+        if not identity:
+            raise UnauthorizedError("invalid credentials")
+        return str(identity)
+
+    def _handle(self, handler):
+        try:
+            if self.service is None:
+                raise TaskPlaneHTTPError("service not configured")
+            result = handler()
+            if isinstance(result, tuple):
+                status, payload = result
+            else:
+                status, payload = 200, result
+            self._response(status, payload)
+        except TaskPlaneHTTPError as exc:
+            self._response(exc.status_code, exc.to_payload())
+        except Exception as exc:  # defensive
+            if isinstance(exc, TaskPlaneHTTPError):
+                raise
+            self._response(
+                500,
+                {"error": "internal_error", "message": "internal server error"},
+            )
+
+    def do_GET(self):  # noqa: N802
+        def route():
+            path = urllib.parse.urlparse(self.path).path
+            parts = [p for p in path.split("/") if p]
+            for part in parts[1:]:
+                if part not in {"events", "evidence", "children", "heartbeat"}:
+                    try:
+                        validate_identifier(part, "resource identifier")
+                    except ValueError as exc:
+                        raise ValidationError("invalid resource identifier") from exc
+            identity = self._authenticated_identity()
+
+            if len(parts) == 1 and parts[0] == "tasks":
+                return 200, self.service.list_tasks(identity)
+            if len(parts) == 2 and parts[0] == "tasks":
+                task_id = parts[1]
+                return 200, self.service.get_task(task_id, identity)
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "events":
+                return 200, self.service.get_events(parts[1], identity)
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "evidence":
+                return 200, self.service.get_evidence(parts[1], identity)
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "children":
+                return 200, self.service.get_children(parts[1], identity)
+            if len(parts) == 1 and parts[0] == "workers":
+                return 200, self.service.list_workers(identity)
+            if len(parts) == 2 and parts[0] == "workers":
+                return 200, self.service.get_worker(parts[1], identity)
+            raise NotFoundError("unknown endpoint")
+
+        self._handle(route)
+
+    def do_POST(self):  # noqa: N802
+        def route():
+            body_text, body = self._json()
+            identity = self._authenticated_identity()
+            path = urllib.parse.urlparse(self.path).path
+            parts = [p for p in path.split("/") if p]
+            headers = {k.lower(): v for k, v in self.headers.items()}
+
+            if len(parts) == 1 and parts[0] == "tasks":
+                issuer = body.get("issuer")
+                if issuer and (
+                    not isinstance(issuer, dict) or issuer.get("id") != identity
+                ):
+                    raise ForbiddenError("issuer identity mismatch")
+                body["issuer"] = {"type": "authenticated", "id": identity}
+                return 201, self.service.create_task(body or {}, headers.get("idempotency-key"))
+            if body.get("actor_identity") not in {None, identity}:
+                raise ForbiddenError("actor identity mismatch")
+            body["actor_identity"] = identity
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "claim":
+                return 200, self.service.claim(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "heartbeat":
+                return 200, self.service.heartbeat(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "progress":
+                return 200, self.service.progress(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "result":
+                return 200, self.service.complete(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "fail":
+                return 200, self.service.fail(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "cancel":
+                return 200, self.service.cancel(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "tasks" and parts[2] == "delegate":
+                return 200, self.service.delegate(parts[1], body or {})
+
+            if len(parts) == 2 and parts[0] == "workers" and parts[1] == "register":
+                if (
+                    body.get("identity") != identity
+                    and identity not in self.service.policy.admin_identities
+                ):
+                    raise ForbiddenError("worker identity mismatch")
+                return 201, self.service.register_worker(body or {})
+            if len(parts) == 3 and parts[0] == "workers" and parts[2] == "heartbeat":
+                return 200, self.service.worker_heartbeat(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "workers" and parts[2] == "disable":
+                return 200, self.service.disable_worker(parts[1], body or {})
+            if len(parts) == 3 and parts[0] == "workers" and parts[2] == "restore":
+                return 200, self.service.restore_worker(parts[1], body or {})
+            raise NotFoundError("unknown endpoint")
+
+        self._handle(route)
+
+
+def run_server(
+    host: str,
+    port: int,
+    service: TaskPlaneService,
+    *,
+    authenticator: Callable[[str], str | None] | None = None,
+):
+    handler = TaskPlaneRequestHandler
+    handler.service = service
+    handler.authenticator = authenticator
+    server = ThreadingHTTPServer((host, port), handler)
+    server.serve_forever()
@@ -0,0 +1,36 @@
+"""Capability matcher helpers."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+
+
+def _normalize_capability(capability: str) -> str:
+    return capability.strip().lower()
+
+
+def capability_matches(granted: str, required: str) -> bool:
+    granted = _normalize_capability(granted)
+    required = _normalize_capability(required)
+    if granted == required:
+        return True
+    # A granted wildcard such as "test.*" should match required "test.unit"
+    if "*" in granted:
+        return fnmatch(required, granted)
+    # A required wildcard is treated as a suffix/prefix requirement for callers.
+    if "*" in required:
+        return fnmatch(granted, required)
+    return False
+
+
+def has_capabilities(granted_caps: list[str], required_caps: list[str]) -> bool:
+    granted = [_normalize_capability(c) for c in granted_caps]
+    for required in required_caps:
+        required = _normalize_capability(required)
+        if not any(capability_matches(g, required) for g in granted):
+            return False
+    return True
+
+
+def normalize_capabilities(caps: list[str]) -> list[str]:
+    return sorted({_normalize_capability(cap) for cap in caps})
@@ -0,0 +1,87 @@
+"""Delegation guardrails."""
+
+from __future__ import annotations
+
+from .errors import ConflictError, ForbiddenError, NotFoundError
+from .models import Budget, TaskPlan, TaskRecord
+from .store import TaskPlaneStore
+
+
+class DelegationEngine:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def can_delegate(self, parent_id: str, child_plan: TaskPlan) -> bool:
+        parent = self.store.get_task(parent_id)
+        if parent.status == "COMPLETED":
+            raise ConflictError("cannot delegate completed task")
+        if parent.task_plan.max_delegation_depth <= 0:
+            raise ConflictError("max delegation depth not configured")
+
+        depth = self._depth(parent_id)
+        if depth >= parent.task_plan.max_delegation_depth:
+            raise ConflictError("max delegation depth reached")
+
+        if child_plan.parent_task_id not in {None, parent_id}:
+            raise ConflictError("delegation parent mismatch")
+        current = parent_id
+        while current:
+            if child_plan.task_id and current == child_plan.task_id:
+                raise ConflictError("delegation cycle")
+            current = self.store.parent_of(current)
+        return True
+
+    def delegate(self, parent_id: str, child_plan: TaskPlan, *, caller: str) -> TaskRecord:
+        self.can_delegate(parent_id, child_plan)
+        parent = self.store.get_task(parent_id)
+        if child_plan.required_capabilities and not set(child_plan.required_capabilities).issubset(
+            set(parent.task_plan.required_capabilities or [])
+        ):
+            raise ForbiddenError("child capabilities exceed parent constraints")
+        risk_rank = {"low": 1, "medium": 2, "high": 3}
+        if risk_rank.get(child_plan.risk, 99) > risk_rank.get(parent.task_plan.risk, -1):
+            raise ForbiddenError("child risk exceeds parent constraints")
+        child_plan.parent_task_id = parent_id
+        child_plan.correlation_id = parent.task_plan.correlation_id or parent.task_id
+        child_plan.preferred_workers = parent.task_plan.preferred_workers
+        child_plan.max_delegation_depth = min(
+            child_plan.max_delegation_depth,
+            parent.task_plan.max_delegation_depth,
+        )
+        child_plan.approval_policy = parent.task_plan.approval_policy
+
+        parent_budget = self.store.get_task_budget(parent_id)
+        required = Budget()
+        for name in ("time_seconds", "attempts", "tokens", "cost"):
+            available = getattr(parent_budget, name)
+            requested = getattr(child_plan.budgets, name)
+            if name == "attempts" and requested is None:
+                requested = 1
+            if available is not None:
+                requested = 0 if requested is None else requested
+                if requested > available:
+                    raise ConflictError(f"budget exceeded for {name}")
+                setattr(child_plan.budgets, name, requested)
+            setattr(required, name, requested)
+
+        # A retried identical delegation is a read, not a second budget charge.
+        if child_plan.task_id:
+            try:
+                existing = self.store.get_task(child_plan.task_id)
+            except NotFoundError:
+                existing = None
+            if existing is not None:
+                if (
+                    existing.task_plan.parent_task_id == parent_id
+                    and existing.task_plan.operation_digest()
+                    == child_plan.operation_digest()
+                ):
+                    return existing
+                raise ConflictError("delegation task_id conflict")
+
+        return self.store.delegate_task_with_budget_and_events(
+            parent_id, child_plan, caller=caller
+        )
+
+    def _depth(self, task_id: str) -> int:
+        return self.store._compute_depth(task_id)
@@ -0,0 +1,71 @@
+"""Error types for task plane operations."""
+
+from __future__ import annotations
+
+
+class TaskPlaneError(Exception):
+    """Base exception for API-compatible failures."""
+
+    status_code = 500
+    error_code = "task_plane_error"
+
+    def __init__(self, message: str, *, code: str | None = None, details: dict | None = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+        if code:
+            self.error_code = code
+
+    def to_payload(self) -> dict:
+        return {"error": self.error_code, "message": self.message, "details": self.details}
+
+
+class TaskPlaneHTTPError(TaskPlaneError):
+    """Base class with explicit HTTP status."""
+
+    status_code = 500
+
+
+class ValidationError(TaskPlaneHTTPError):
+    status_code = 400
+    error_code = "validation_error"
+
+
+class UnauthorizedError(TaskPlaneHTTPError):
+    status_code = 401
+    error_code = "unauthorized"
+
+
+class ForbiddenError(TaskPlaneHTTPError):
+    status_code = 403
+    error_code = "forbidden"
+
+
+class NotFoundError(TaskPlaneHTTPError):
+    status_code = 404
+    error_code = "not_found"
+
+
+class ConflictError(TaskPlaneHTTPError):
+    status_code = 409
+    error_code = "conflict"
+
+
+class PayloadTooLargeError(TaskPlaneHTTPError):
+    status_code = 413
+    error_code = "payload_too_large"
+
+
+class FailedDependencyError(TaskPlaneHTTPError):
+    status_code = 424
+    error_code = "failed_dependency"
+
+
+class LockedError(TaskPlaneHTTPError):
+    status_code = 423
+    error_code = "locked"
+
+
+class ServiceUnavailableError(TaskPlaneHTTPError):
+    status_code = 503
+    error_code = "service_unavailable"
@@ -0,0 +1,108 @@
+"""CloudEvents-compatible event envelope and durable outbox helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Callable, Protocol
+
+from .store import TaskPlaneStore
+
+
+@dataclass
+class CloudEvent:
+    specversion: str = "1.0"
+    id: str = ""
+    type: str = ""
+    source: str = "spiffe://aios/task-plane"
+    subject: str = ""
+    datacontenttype: str = "application/json"
+    data: dict | None = None
+
+    @property
+    def time(self) -> str:
+        return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+    def asdict(self) -> dict:
+        return {
+            "specversion": self.specversion,
+            "id": self.id,
+            "type": self.type,
+            "source": self.source,
+            "subject": self.subject,
+            "time": self.time,
+            "datacontenttype": self.datacontenttype,
+            "data": self.data or {},
+        }
+
+
+NOT_DELIVERED = "NOT_DELIVERED"
+DELIVERED = "DELIVERED"
+FAILED_DELIVERY = "FAILED"
+
+
+class NotificationAdapter(Protocol):
+    name: str
+
+    def deliver(self, envelope: dict) -> str | None:
+        """Return a provider receipt, or None when delivery is unconfirmed."""
+
+
+class CallbackNotificationAdapter:
+    """Adapter seam for webhook, NATS, GPT, dashboard, and WeChat transports."""
+
+    def __init__(self, name: str, callback: Callable[[dict], str | None]):
+        self.name = name
+        self._callback = callback
+
+    def deliver(self, envelope: dict) -> str | None:
+        return self._callback(envelope)
+
+
+class WebhookAdapter(CallbackNotificationAdapter):
+    def __init__(self, callback: Callable[[dict], str | None]):
+        super().__init__("webhook", callback)
+
+
+class NatsJetStreamAdapter(CallbackNotificationAdapter):
+    def __init__(self, callback: Callable[[dict], str | None]):
+        super().__init__("nats-jetstream", callback)
+
+
+class GPTResultCallbackAdapter(CallbackNotificationAdapter):
+    def __init__(self, callback: Callable[[dict], str | None]):
+        super().__init__("gpt-result-callback", callback)
+
+
+class DashboardAdapter(CallbackNotificationAdapter):
+    def __init__(self, callback: Callable[[dict], str | None]):
+        super().__init__("dashboard", callback)
+
+
+class WeChatGatewayAdapter(CallbackNotificationAdapter):
+    def __init__(self, callback: Callable[[dict], str | None]):
+        super().__init__("wechat-gateway", callback)
+
+
+class DurableOutboxDispatcher:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def dispatch(self, message_id: str, adapter: NotificationAdapter) -> dict:
+        row = self.store.get_outbox_message(message_id)
+        import json
+
+        envelope = json.loads(row["payload"])
+        try:
+            receipt = adapter.deliver(envelope)
+        except Exception:
+            return self.store.record_outbox_delivery(
+                message_id,
+                receipt=None,
+                error=f"{adapter.name} delivery failed",
+            )
+        return self.store.record_outbox_delivery(
+            message_id,
+            receipt=str(receipt) if receipt else None,
+            error=None if receipt else f"{adapter.name} receipt unavailable",
+        )
@@ -0,0 +1,31 @@
+"""Evidence helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .store import TaskPlaneStore
+
+
+def evidence_digest(payload: dict) -> str:
+    body = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(body.encode("utf-8")).hexdigest()
+
+
+class EvidenceService:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def add(self, task_id: str, kind: str, payload: dict, worker_identity: str) -> str:
+        return self.store.add_evidence(task_id, kind, payload, worker_identity)
+
+    def list(self, task_id: str) -> list[dict]:
+        return self.store.list_evidence(task_id)
+
+    def verify(self, task_id: str, required_kinds: list[str]) -> bool:
+        evidences = self.list(task_id)
+        observed = {e["kind"] for e in evidences}
+        return set(required_kinds).issubset(
+            observed
+        ) and self.store.verify_evidence_integrity(task_id)
@@ -0,0 +1,22 @@
+"""Event journaling helpers."""
+
+from __future__ import annotations
+
+from .errors import ValidationError
+from .store import TaskPlaneStore
+
+
+class TaskJournal:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def append(self, task_id: str, event_type: str, data: dict, *, subject: str | None = None) -> None:
+        if not event_type:
+            raise ValidationError("event_type required")
+        self.store.append_event(task_id, event_type, data, subject=subject)
+
+    def list(self, task_id: str) -> list[dict]:
+        return self.store.list_events(task_id)
+
+    def check_chain(self, task_id: str) -> bool:
+        return self.store.verify_event_chain(task_id)
@@ -0,0 +1,32 @@
+"""Claim and lease management helpers."""
+
+from __future__ import annotations
+
+from .errors import LockedError
+from .models import ProbeEvidence
+from .store import TaskPlaneStore
+
+
+class LeaseManager:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def claim(self, task_id: str, worker_id: str, worker_identity: str, lease_seconds: int, expected_revision: int, operation_digest: str):
+        return self.store.claim_task(task_id, worker_id, worker_identity, lease_seconds, expected_revision, operation_digest)
+
+    def heartbeat(self, task_id: str, claim_id: str, lease_seconds: int):
+        claim = self.store.heartbeat_claim(task_id, claim_id, lease_seconds)
+        return claim
+
+    def probe(self, claim_id: str):
+        claim = self.store.get_claim(claim_id)
+        if claim.status != "ACTIVE":
+            raise LockedError("claim not active")
+        return claim
+
+    def recover(self, task_id: str, claim_id: str, probe: ProbeEvidence):
+        return self.store.recover_expired_claim(
+            task_id,
+            claim_id,
+            probe,
+        )
@@ -0,0 +1,829 @@
+"""Core data models for the task plane."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+import uuid
+import urllib.parse
+from enum import StrEnum
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+SENSITIVE_KEYS = {
+    "secret",
+    "password",
+    "token",
+    "api_key",
+    "access_token",
+    "refresh_token",
+    "authorization",
+    "private_key",
+    "client_secret",
+    "credential",
+}
+IDENTIFIER_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")
+TYPE_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+RISK_LEVELS = {"low", "medium", "high"}
+DATA_CLASSIFICATIONS = {
+    "public",
+    "internal",
+    "confidential",
+    "credential-secret",
+}
+SECRET_TEXT_PATTERNS = (
+    re.compile(r"(?i)\bAuthorization\s*:\s*Bearer\s+\S+"),
+    re.compile(r"(?i)\b(?:password|passwd|api[_-]?key|access[_-]?token|secret)\s*[:=]\s*\S+"),
+    re.compile(r"\bsk-[A-Za-z0-9_-]{12,}\b"),
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
+)
+TASK_PLAN_KEYS = {
+    "schema_version",
+    "task_id",
+    "task_type",
+    "issuer",
+    "intent",
+    "required_capabilities",
+    "preferred_workers",
+    "risk",
+    "approval_policy",
+    "dependencies",
+    "max_delegation_depth",
+    "budgets",
+    "evidence_requirements",
+    "parent_task_id",
+    "correlation_id",
+    "metadata",
+    "data_classification",
+    "execution_zone",
+    "network_policy",
+    "logging_policy",
+    "allowed_input_paths",
+    "allowed_output_paths",
+    "output_policy",
+}
+
+
+def _now_ts() -> float:
+    return time.time()
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def compute_sha256_hex(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def contains_secret_text(value: Any) -> bool:
+    if isinstance(value, str):
+        return any(pattern.search(value) for pattern in SECRET_TEXT_PATTERNS)
+    if isinstance(value, dict):
+        return any(contains_secret_text(item) for item in value.values())
+    if isinstance(value, (list, tuple)):
+        return any(contains_secret_text(item) for item in value)
+    return False
+
+
+def validate_relative_paths(values: Any, name: str) -> list[str]:
+    paths = _normalize_list(values)
+    for value in paths:
+        decoded = urllib.parse.unquote(value)
+        parts = value.replace("\\", "/").split("/")
+        if (
+            decoded != value
+            or "\\" in value
+            or value.startswith("/")
+            or re.match(r"^[A-Za-z]:", value)
+            or any(part in {"", ".", ".."} for part in parts)
+        ):
+            raise ValueError(f"invalid {name}")
+    return paths
+
+
+def validate_identifier(value: Any, name: str) -> str:
+    text = str(value or "")
+    if (
+        not IDENTIFIER_RE.fullmatch(text)
+        or urllib.parse.unquote(text) != text
+        or any(ord(ch) < 32 or ord(ch) == 127 for ch in text)
+    ):
+        raise ValueError(f"invalid {name}")
+    return text
+
+
+def validate_type(value: Any, name: str) -> str:
+    text = str(value or "")
+    if not TYPE_RE.fullmatch(text):
+        raise ValueError(f"invalid {name}")
+    return text
+
+
+def redact_value(value: Any) -> Any:
+    if isinstance(value, dict):
+        redacted = {}
+        for key, inner in value.items():
+            lowered = str(key).lower()
+            if lowered in SENSITIVE_KEYS or lowered.endswith(
+                ("_password", "_secret", "_access_token", "_refresh_token", "_private_key")
+            ):
+                redacted[key] = "[REDACTED]"
+            else:
+                redacted[key] = redact_value(inner)
+        return redacted
+    if isinstance(value, list):
+        return [redact_value(v) for v in value]
+    if isinstance(value, tuple):
+        return tuple(redact_value(v) for v in value)
+    return value
+
+
+class TaskStateTransitionError(ValueError):
+    pass
+
+
+class TaskStatus(StrEnum):
+    CREATED = "CREATED"
+    QUEUED = "QUEUED"
+    CLAIMED = "CLAIMED"
+    RUNNING = "RUNNING"
+    WAITING_CHILD = "WAITING_CHILD"
+    VERIFYING = "VERIFYING"
+    COMPLETED = "COMPLETED"
+    FAILED_RECOVERABLE = "FAILED_RECOVERABLE"
+    FAILED_FINAL = "FAILED_FINAL"
+    CANCELLED = "CANCELLED"
+    MANUAL_REVIEW_REQUIRED = "MANUAL_REVIEW_REQUIRED"
+
+
+TASK_STATES = {
+    status.value for status in TaskStatus
+}
+
+
+TASK_NEXT_STATES = {
+    "CREATED": {"QUEUED", "CLAIMED", "CANCELLED", "MANUAL_REVIEW_REQUIRED"},
+    "QUEUED": {"CLAIMED", "CANCELLED", "FAILED_RECOVERABLE", "FAILED_FINAL"},
+    "CLAIMED": {"RUNNING", "FAILED_RECOVERABLE", "FAILED_FINAL", "CANCELLED"},
+    "RUNNING": {"VERIFYING", "WAITING_CHILD", "COMPLETED", "FAILED_RECOVERABLE", "FAILED_FINAL", "CANCELLED"},
+    "WAITING_CHILD": {"RUNNING", "VERIFYING", "FAILED_RECOVERABLE", "FAILED_FINAL", "CANCELLED"},
+    "VERIFYING": {"COMPLETED", "FAILED_RECOVERABLE", "FAILED_FINAL", "CANCELLED"},
+    "COMPLETED": set(),
+    "FAILED_RECOVERABLE": {"CLAIMED", "RUNNING", "CANCELLED"},
+    "FAILED_FINAL": set(),
+    "CANCELLED": set(),
+    "MANUAL_REVIEW_REQUIRED": {"RUNNING", "CANCELLED"},
+}
+
+
+@dataclass
+class Budget:
+    time_seconds: int | None = None
+    attempts: int | None = None
+    tokens: int | None = None
+    cost: float | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "Budget":
+        if not data:
+            return cls()
+        if not isinstance(data, dict) or set(data) - {
+            "time_seconds",
+            "attempts",
+            "tokens",
+            "cost",
+        }:
+            raise ValueError("invalid budget")
+        for name in ("time_seconds", "attempts", "tokens", "cost"):
+            value = data.get(name)
+            if value is not None:
+                try:
+                    if float(value) < 0:
+                        raise ValueError("budget values must be non-negative")
+                except (TypeError, ValueError) as exc:
+                    raise ValueError("invalid budget value") from exc
+        return cls(
+            time_seconds=_to_positive_int(data.get("time_seconds")),
+            attempts=_to_positive_int(data.get("attempts")),
+            tokens=_to_positive_int(data.get("tokens")),
+            cost=_to_float(data.get("cost")),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "time_seconds": self.time_seconds,
+            "attempts": self.attempts,
+            "tokens": self.tokens,
+            "cost": self.cost,
+        }
+
+    def merge(self, other: "Budget") -> "Budget":
+        return Budget(
+            time_seconds=_first_non_none(self.time_seconds, other.time_seconds),
+            attempts=_first_non_none(self.attempts, other.attempts),
+            tokens=_first_non_none(self.tokens, other.tokens),
+            cost=_first_non_none(self.cost, other.cost),
+        )
+
+
+@dataclass
+class TaskPlan:
+    schema_version: int = 1
+    task_id: str | None = None
+    task_type: str = "code.change"
+    issuer: dict[str, Any] = field(default_factory=dict)
+    intent: str | None = None
+    required_capabilities: list[str] = field(default_factory=list)
+    preferred_workers: list[str] = field(default_factory=list)
+    risk: str = "medium"
+    approval_policy: str = "patch-only"
+    dependencies: list[str] = field(default_factory=list)
+    max_delegation_depth: int = 5
+    budgets: Budget = field(default_factory=Budget)
+    evidence_requirements: list[str] = field(default_factory=list)
+    parent_task_id: str | None = None
+    correlation_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    data_classification: str = "internal"
+    execution_zone: str = "isolated-development"
+    network_policy: str = "controlled"
+    logging_policy: str = "redacted"
+    allowed_input_paths: list[str] = field(default_factory=list)
+    allowed_output_paths: list[str] = field(default_factory=list)
+    output_policy: str = "standard"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "TaskPlan":
+        if not isinstance(data, dict):
+            raise ValueError("task plan payload must be an object")
+        unknown = set(data) - TASK_PLAN_KEYS
+        if unknown:
+            raise ValueError("unknown task plan fields")
+        if "task_id" not in data or data["task_id"] is None:
+            data = dict(data)
+            data["task_id"] = f"task-{uuid.uuid4()}"
+        risk = str(data.get("risk", "medium"))
+        if risk not in RISK_LEVELS:
+            raise ValueError("invalid risk")
+        issuer = data.get("issuer", {})
+        if not isinstance(issuer, dict):
+            raise ValueError("issuer must be an object")
+        schema_version = int(data.get("schema_version", 1))
+        if schema_version != 1:
+            raise ValueError("unsupported schema_version")
+        max_depth = _to_positive_int(data.get("max_delegation_depth"), default=5)
+        if max_depth is None or max_depth > 32:
+            raise ValueError("invalid max_delegation_depth")
+        classification = str(data.get("data_classification", "internal"))
+        if classification not in DATA_CLASSIFICATIONS:
+            raise ValueError("invalid data_classification")
+        execution_zone = validate_type(
+            data.get("execution_zone", "isolated-development"), "execution_zone"
+        )
+        network_policy = validate_type(
+            data.get("network_policy", "controlled"), "network_policy"
+        )
+        logging_policy = validate_type(
+            data.get("logging_policy", "redacted"), "logging_policy"
+        )
+        output_policy = validate_type(
+            data.get("output_policy", "standard"), "output_policy"
+        )
+        if contains_secret_text(
+            {
+                "intent": data.get("intent"),
+                "metadata": data.get("metadata", {}),
+            }
+        ):
+            raise ValueError("task content contains secret material")
+        if classification == "credential-secret":
+            if execution_zone != "secure-file-transformer":
+                raise ValueError("credential-secret requires secure-file-transformer")
+            if network_policy != "denied":
+                raise ValueError("credential-secret requires network denied")
+            if logging_policy != "metadata-only":
+                raise ValueError("credential-secret requires metadata-only logging")
+            if output_policy != "hash-count-status-only":
+                raise ValueError("credential-secret requires restricted output")
+        return cls(
+            schema_version=schema_version,
+            task_id=validate_identifier(data["task_id"], "task_id"),
+            task_type=validate_type(data.get("task_type", "code.change"), "task_type"),
+            issuer=issuer,
+            intent=data.get("intent"),
+            required_capabilities=_normalize_list(data.get("required_capabilities", [])),
+            preferred_workers=_normalize_list(data.get("preferred_workers", [])),
+            risk=risk,
+            approval_policy=validate_type(
+                data.get("approval_policy", "patch-only"), "approval_policy"
+            ),
+            dependencies=_normalize_list(data.get("dependencies", [])),
+            max_delegation_depth=max_depth,
+            budgets=Budget.from_dict(data.get("budgets")),
+            evidence_requirements=_normalize_list(data.get("evidence_requirements", [])),
+            parent_task_id=data.get("parent_task_id"),
+            correlation_id=data.get("correlation_id"),
+            metadata=data.get("metadata", {}) if isinstance(data.get("metadata", {}), dict) else {},
+            data_classification=classification,
+            execution_zone=execution_zone,
+            network_policy=network_policy,
+            logging_policy=logging_policy,
+            allowed_input_paths=validate_relative_paths(
+                data.get("allowed_input_paths", []), "allowed_input_paths"
+            ),
+            allowed_output_paths=validate_relative_paths(
+                data.get("allowed_output_paths", []), "allowed_output_paths"
+            ),
+            output_policy=output_policy,
+        )
+
+    def to_dict(self, *, redact: bool = False) -> dict[str, Any]:
+        payload = {
+            "schema_version": self.schema_version,
+            "task_id": self.task_id,
+            "task_type": self.task_type,
+            "issuer": self.issuer,
+            "intent": self.intent,
+            "required_capabilities": list(self.required_capabilities),
+            "preferred_workers": list(self.preferred_workers),
+            "risk": self.risk,
+            "approval_policy": self.approval_policy,
+            "dependencies": list(self.dependencies),
+            "max_delegation_depth": self.max_delegation_depth,
+            "budgets": self.budgets.to_dict(),
+            "evidence_requirements": list(self.evidence_requirements),
+            "parent_task_id": self.parent_task_id,
+            "correlation_id": self.correlation_id,
+            "metadata": dict(self.metadata),
+            "data_classification": self.data_classification,
+            "execution_zone": self.execution_zone,
+            "network_policy": self.network_policy,
+            "logging_policy": self.logging_policy,
+            "allowed_input_paths": list(self.allowed_input_paths),
+            "allowed_output_paths": list(self.allowed_output_paths),
+            "output_policy": self.output_policy,
+        }
+        if redact:
+            payload = redact_value(payload)
+        return payload
+
+    def operation_digest(self) -> str:
+        return compute_sha256_hex(self.to_dict())
+
+
+@dataclass
+class TaskRecord:
+    task_id: str
+    status: str
+    revision: int
+    task_plan: TaskPlan
+    created_at: float
+    updated_at: float
+    root_task_id: str
+    idempotency_key: str | None = None
+    failure_reason: str | None = None
+
+    def with_status(self, status: str) -> "TaskRecord":
+        allowed = TASK_NEXT_STATES.get(self.status, set())
+        if status != self.status and (not allowed and self.status not in {"COMPLETED", "FAILED_FINAL", "CANCELLED"}):
+            raise TaskStateTransitionError(f"Cannot transition {self.status} -> {status}")
+        if status not in TASK_STATES:
+            raise TaskStateTransitionError(f"Invalid status {status}")
+        if status != self.status and self.status in TASK_NEXT_STATES and status not in TASK_NEXT_STATES[self.status]:
+            raise TaskStateTransitionError(f"Cannot transition {self.status} -> {status}")
+        return TaskRecord(
+            task_id=self.task_id,
+            status=status,
+            revision=self.revision + 1,
+            task_plan=self.task_plan,
+            created_at=self.created_at,
+            updated_at=_now_ts(),
+            root_task_id=self.root_task_id,
+            idempotency_key=self.idempotency_key,
+            failure_reason=self.failure_reason,
+        )
+
+    def to_dict(self, *, include_task=True, redact_payload: bool = True) -> dict[str, Any]:
+        payload = {
+            "task_id": self.task_id,
+            "status": self.status,
+            "revision": self.revision,
+            "root_task_id": self.root_task_id,
+            "parent_task_id": self.task_plan.parent_task_id,
+            "created_at": _fmt_ts(self.created_at),
+            "updated_at": _fmt_ts(self.updated_at),
+            "failure_reason": self.failure_reason,
+        }
+        if include_task:
+            payload["plan"] = self.task_plan.to_dict(redact=redact_payload)
+        if self.idempotency_key:
+            payload["idempotency_key"] = self.idempotency_key
+        return payload
+
+
+@dataclass
+class WorkerRegistration:
+    worker_id: str
+    worker_type: str
+    identity: str
+    capabilities: list[str]
+    trust_zone: str
+    max_concurrency: int
+    heartbeat_interval_seconds: int
+    supported_protocols: list[str]
+    registered_at: float
+    last_heartbeat: float
+    status: str = "active"
+    disabled: bool = False
+    owner_identity: str = ""
+    registration_revision: int = 1
+    registration_policy: str = "self"
+    created_at: float = 0.0
+    updated_at: float = 0.0
+    disabled_reason: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "WorkerRegistration":
+        if not isinstance(data, dict):
+            raise ValueError("worker registration payload must be an object")
+        now = _now_ts()
+        worker_id = validate_identifier(data.get("worker_id"), "worker_id")
+        worker_type = validate_type(data.get("worker_type"), "worker_type")
+        identity = str(data.get("identity") or "").strip()
+        if not identity or any(ord(ch) < 32 for ch in identity):
+            raise ValueError("invalid identity")
+        max_concurrency = _to_positive_int(data.get("max_concurrency"), default=1)
+        heartbeat_interval = _to_positive_int(
+            data.get("heartbeat_interval_seconds"), default=15
+        )
+        if not max_concurrency:
+            raise ValueError("max_concurrency must be positive")
+        if not heartbeat_interval:
+            raise ValueError("heartbeat_interval_seconds must be positive")
+        return cls(
+            worker_id=worker_id,
+            worker_type=worker_type,
+            identity=identity,
+            capabilities=_normalize_list(data.get("capabilities", [])),
+            trust_zone=str(data.get("trust_zone") or "default"),
+            max_concurrency=max_concurrency,
+            heartbeat_interval_seconds=heartbeat_interval,
+            supported_protocols=_normalize_list(
+                data.get("supported_protocols", ["aios-task-v1"])
+            ),
+            registered_at=float(data.get("registered_at") or now),
+            last_heartbeat=float(data.get("last_heartbeat") or now),
+            status=str(data.get("status") or "active"),
+            disabled=bool(data.get("disabled", False)),
+            owner_identity=str(data.get("owner_identity") or identity),
+            registration_revision=int(data.get("registration_revision") or 1),
+            registration_policy=str(data.get("registration_policy") or "self"),
+            created_at=float(data.get("created_at") or data.get("registered_at") or now),
+            updated_at=float(data.get("updated_at") or now),
+            disabled_reason=data.get("disabled_reason"),
+        )
+
+    def to_dict(self, redact_payload: bool = True) -> dict[str, Any]:
+        payload = {
+            "worker_id": self.worker_id,
+            "worker_type": self.worker_type,
+            "identity": self.identity,
+            "capabilities": list(self.capabilities),
+            "trust_zone": self.trust_zone,
+            "max_concurrency": self.max_concurrency,
+            "heartbeat_interval_seconds": self.heartbeat_interval_seconds,
+            "supported_protocols": list(self.supported_protocols),
+            "registered_at": _fmt_ts(self.registered_at),
+            "last_heartbeat": _fmt_ts(self.last_heartbeat),
+            "status": self.status,
+            "disabled": self.disabled,
+            "owner_identity": self.owner_identity,
+            "registration_revision": self.registration_revision,
+            "registration_policy": self.registration_policy,
+            "created_at": _fmt_ts(self.created_at or self.registered_at),
+            "updated_at": _fmt_ts(self.updated_at or self.last_heartbeat),
+            "disabled_reason": self.disabled_reason,
+        }
+        if redact_payload:
+            payload = redact_value(payload)
+        return payload
+
+
+@dataclass(frozen=True)
+class EvidenceEnvelope:
+    schema_version: int
+    evidence_id: str
+    task_id: str
+    claim_id: str
+    kind: str
+    worker_identity: str
+    payload: dict[str, Any]
+    created_at: float
+    previous_evidence_hash: str
+    evidence_digest: str
+    signature: str | None = None
+    attestation_ref: str | None = None
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        task_id: str,
+        claim_id: str,
+        kind: str,
+        worker_identity: str,
+        payload: dict[str, Any],
+        previous_evidence_hash: str,
+        signature: str | None = None,
+        attestation_ref: str | None = None,
+        evidence_id: str | None = None,
+        created_at: float | None = None,
+    ) -> "EvidenceEnvelope":
+        envelope = cls(
+            schema_version=1,
+            evidence_id=evidence_id or f"evd-{uuid.uuid4()}",
+            task_id=validate_identifier(task_id, "task_id"),
+            claim_id=validate_identifier(claim_id, "claim_id"),
+            kind=validate_type(kind, "evidence kind"),
+            worker_identity=str(worker_identity),
+            payload=redact_value(payload),
+            created_at=float(created_at or _now_ts()),
+            previous_evidence_hash=str(previous_evidence_hash or ""),
+            evidence_digest="",
+            signature=signature,
+            attestation_ref=attestation_ref,
+        )
+        return dataclass_replace(
+            envelope, evidence_digest=compute_sha256_hex(envelope.digest_payload())
+        )
+
+    def digest_payload(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "evidence_id": self.evidence_id,
+            "task_id": self.task_id,
+            "claim_id": self.claim_id,
+            "kind": self.kind,
+            "worker_identity": self.worker_identity,
+            "payload": self.payload,
+            "created_at": self.created_at,
+            "previous_evidence_hash": self.previous_evidence_hash,
+            "attestation_ref": self.attestation_ref,
+        }
+
+    def verify(
+        self,
+        *,
+        expected_task_id: str,
+        expected_claim_id: str,
+        expected_previous_hash: str,
+        attestation_verifier: Any = None,
+    ) -> bool:
+        if (
+            self.schema_version != 1
+            or self.task_id != expected_task_id
+            or self.claim_id != expected_claim_id
+            or self.previous_evidence_hash != expected_previous_hash
+            or self.evidence_digest != compute_sha256_hex(self.digest_payload())
+        ):
+            return False
+        if self.signature or self.attestation_ref:
+            return True if attestation_verifier is None else bool(attestation_verifier(self))
+        return True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            **self.digest_payload(),
+            "evidence_digest": self.evidence_digest,
+            "signature": self.signature,
+        }
+
+
+class ProbeOutcome(StrEnum):
+    NOT_APPLIED = "NOT_APPLIED"
+    APPLIED_VERIFIED = "APPLIED_VERIFIED"
+    INDETERMINATE = "INDETERMINATE"
+    CONFLICT = "CONFLICT"
+
+
+@dataclass(frozen=True)
+class ProbeEvidence:
+    schema_version: int
+    probe_id: str
+    task_id: str
+    claim_id: str
+    worker_id: str
+    worker_identity: str
+    operation_digest: str
+    outcome: ProbeOutcome
+    observed_at: float
+    expires_at: float
+    probe_executor_identity: str
+    evidence_digest: str
+    signature: str | None = None
+    attestation_ref: str | None = None
+
+    @classmethod
+    def create(cls, **data: Any) -> "ProbeEvidence":
+        outcome = data["outcome"]
+        if not isinstance(outcome, ProbeOutcome):
+            outcome = ProbeOutcome(str(outcome))
+        probe = cls(
+            schema_version=1,
+            probe_id=data.get("probe_id") or f"probe-{uuid.uuid4()}",
+            task_id=validate_identifier(data["task_id"], "task_id"),
+            claim_id=validate_identifier(data["claim_id"], "claim_id"),
+            worker_id=validate_identifier(data["worker_id"], "worker_id"),
+            worker_identity=str(data["worker_identity"]),
+            operation_digest=str(data["operation_digest"]),
+            outcome=outcome,
+            observed_at=float(data["observed_at"]),
+            expires_at=float(data["expires_at"]),
+            probe_executor_identity=str(data["probe_executor_identity"]),
+            evidence_digest="",
+            signature=data.get("signature"),
+            attestation_ref=data.get("attestation_ref"),
+        )
+        return dataclass_replace(
+            probe, evidence_digest=compute_sha256_hex(probe.digest_payload())
+        )
+
+    def digest_payload(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "probe_id": self.probe_id,
+            "task_id": self.task_id,
+            "claim_id": self.claim_id,
+            "worker_id": self.worker_id,
+            "worker_identity": self.worker_identity,
+            "operation_digest": self.operation_digest,
+            "outcome": self.outcome.value,
+            "observed_at": self.observed_at,
+            "expires_at": self.expires_at,
+            "probe_executor_identity": self.probe_executor_identity,
+            "attestation_ref": self.attestation_ref,
+        }
+
+    def verify(self, *, now: float, attestation_verifier: Any) -> bool:
+        if (
+            self.schema_version != 1
+            or self.expires_at <= now
+            or self.observed_at > now
+            or self.evidence_digest != compute_sha256_hex(self.digest_payload())
+            or not (self.signature or self.attestation_ref)
+        ):
+            return False
+        return bool(attestation_verifier and attestation_verifier(self))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            **self.digest_payload(),
+            "evidence_digest": self.evidence_digest,
+            "signature": self.signature,
+        }
+
+
+def dataclass_replace(value: Any, **changes: Any) -> Any:
+    from dataclasses import replace
+
+    return replace(value, **changes)
+
+
+@dataclass
+class WorkerClaim:
+    claim_id: str
+    task_id: str
+    worker_id: str
+    worker_identity: str
+    claimed_at: float
+    lease_until: float
+    attempt: int
+    task_revision: int
+    operation_digest: str
+    status: str = "ACTIVE"
+
+    def to_dict(self, redact_payload: bool = True) -> dict[str, Any]:
+        payload = {
+            "claim_id": self.claim_id,
+            "task_id": self.task_id,
+            "worker_id": self.worker_id,
+            "worker_identity": self.worker_identity,
+            "claimed_at": _fmt_ts(self.claimed_at),
+            "lease_until": _fmt_ts(self.lease_until),
+            "attempt": self.attempt,
+            "task_revision": self.task_revision,
+            "operation_digest": self.operation_digest,
+            "status": self.status,
+        }
+        if redact_payload:
+            payload = redact_value(payload)
+        return payload
+
+
+@dataclass
+class ResultEnvelope:
+    task_id: str
+    claim_id: str
+    worker_identity: str
+    status: str
+    outputs: list[dict[str, Any]]
+    evidence: list[dict[str, Any]]
+    started_at: str
+    completed_at: str
+    result_digest: str | None = None
+    signature: str | None = None
+    attestation_ref: str | None = None
+    operation_digest: str | None = None
+    trust_status: str = "untrusted_shadow_result"
+
+    def digest_payload(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "claim_id": self.claim_id,
+            "worker_identity": self.worker_identity,
+            "status": self.status,
+            "outputs": self.outputs,
+            "evidence": self.evidence,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "operation_digest": self.operation_digest,
+            "attestation_ref": self.attestation_ref,
+        }
+
+    def computed_digest(self) -> str:
+        return compute_sha256_hex(self.digest_payload())
+
+    def to_dict(self, redact_payload: bool = True) -> dict[str, Any]:
+        payload = {
+            "task_id": self.task_id,
+            "claim_id": self.claim_id,
+            "worker_identity": self.worker_identity,
+            "status": self.status,
+            "outputs": self.outputs,
+            "evidence": self.evidence,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "result_digest": self.result_digest,
+            "signature": self.signature,
+            "attestation_ref": self.attestation_ref,
+            "operation_digest": self.operation_digest,
+            "trust_status": self.trust_status,
+        }
+        if redact_payload:
+            payload = redact_value(payload)
+        return payload
+
+
+def _normalize_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        raise ValueError("expected list")
+    if len(value) > 128 or any(
+        not isinstance(v, str)
+        or not v
+        or len(v) > 256
+        or any(ord(ch) < 32 for ch in v)
+        for v in value
+    ):
+        raise ValueError("invalid list item")
+    return list(value)
+
+
+def _to_positive_int(value: Any, default: int | None = None) -> int | None:
+    if value is None:
+        return default
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        return default
+    return number if number >= 0 else default
+
+
+def _to_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _first_non_none(primary: Any, fallback: Any) -> Any:
+    if primary is not None:
+        return primary
+    return fallback
+
+
+def iso8601_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _fmt_ts(value: float | None) -> str | None:
+    if value is None:
+        return None
+    return datetime.fromtimestamp(value, tz=timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
@@ -0,0 +1,226 @@
+"""Policy and verification logic (fail-closed)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from .errors import ForbiddenError, LockedError
+from .models import ProbeEvidence, ResultEnvelope, TaskRecord
+
+
+RISK_RANK = {"low": 1, "medium": 2, "high": 3}
+READONLY_WORKER_ACTIONS = frozenset(
+    {"claim", "result", "fail", "progress", "heartbeat"}
+)
+ALL_ACTION_CAPABILITIES = frozenset(
+    {
+        "task.creator",
+        "worker.self_register",
+        "worker.admin",
+        "task.claim",
+        "task.cancel",
+        "task.delegate",
+        "task.read",
+        "task.audit",
+    }
+)
+
+
+@dataclass
+class PolicyDecision:
+    allowed: bool
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class ReadonlyWorkerProfile:
+    """A narrowly-scoped identity allowed to process safe Shadow tasks only."""
+
+    worker_id: str
+    identity: str
+    capabilities: frozenset[str]
+    task_types: frozenset[str] = frozenset({"code.review", "test.execute"})
+
+    def permits_task(self, task: TaskRecord) -> bool:
+        plan = task.task_plan
+        if plan.task_type not in self.task_types or plan.risk != "low":
+            return False
+        if plan.data_classification not in {"public", "internal"}:
+            return False
+        if plan.metadata.get("production_side_effects") is not False:
+            return False
+        return set(plan.required_capabilities).issubset(self.capabilities)
+
+
+class IdentityVerifier:
+    def __init__(self, trusted_identities: set[str] | None = None):
+        self.trusted_identities = trusted_identities
+
+    def verify(self, identity: str) -> bool:
+        if self.trusted_identities is None:
+            return True
+        return identity in self.trusted_identities
+
+
+class EvidenceVerifier:
+    def __init__(self, mandatory: list[str] | None = None):
+        self.mandatory = set(mandatory or [])
+
+    def verify(self, task: TaskRecord, evidences: list[dict]) -> PolicyDecision:
+        required = set(task.task_plan.evidence_requirements or [])
+        if not required and not self.mandatory:
+            return PolicyDecision(True)
+        observed = {e.get("kind") for e in evidences}
+        missing = required.union(self.mandatory) - observed
+        if missing:
+            return PolicyDecision(False, f"missing evidence: {', '.join(sorted(missing))}")
+        return PolicyDecision(True)
+
+
+class PolicyEngine:
+    """
+    Fail-closed policy engine with minimal but explicit decisions.
+    """
+
+    def __init__(
+        self,
+        *,
+        identity_verifier: IdentityVerifier | None = None,
+        evidence_verifier: EvidenceVerifier | None = None,
+        execution_enabled: bool = False,
+        max_risk: str = "medium",
+        result_signature_verifier: Callable[[ResultEnvelope], bool] | None = None,
+        probe_attestation_verifier: Callable[[ProbeEvidence], bool] | None = None,
+        identity_capabilities: dict[str, set[str]] | None = None,
+        admin_identities: set[str] | None = None,
+        readonly_worker_execution_enabled: bool = False,
+        readonly_worker_profiles: list[ReadonlyWorkerProfile] | None = None,
+    ) -> None:
+        if max_risk not in RISK_RANK:
+            raise ValueError("invalid max_risk")
+        self.identity_verifier = identity_verifier or IdentityVerifier()
+        self.evidence_verifier = evidence_verifier or EvidenceVerifier()
+        self.execution_enabled = execution_enabled
+        self.max_risk = max_risk
+        self.result_signature_verifier = result_signature_verifier
+        self.probe_attestation_verifier = probe_attestation_verifier
+        self.identity_capabilities = {
+            identity: set(capabilities)
+            for identity, capabilities in (identity_capabilities or {}).items()
+        }
+        self.admin_identities = set(admin_identities or ())
+        self.readonly_worker_execution_enabled = readonly_worker_execution_enabled
+        self.readonly_worker_profiles = {
+            profile.identity: profile for profile in (readonly_worker_profiles or [])
+        }
+
+    def _readonly_worker_allows(
+        self, action: str, actor: str, task: TaskRecord | None
+    ) -> bool:
+        profile = self.readonly_worker_profiles.get(actor)
+        return bool(
+            self.readonly_worker_execution_enabled
+            and action in READONLY_WORKER_ACTIONS
+            and profile is not None
+            and (task is None or profile.permits_task(task))
+        )
+
+    def assert_readonly_worker_binding(self, actor: str, worker_id: str) -> None:
+        profile = self.readonly_worker_profiles.get(actor)
+        if profile is not None and profile.worker_id != worker_id:
+            raise ForbiddenError("worker identity binding mismatch")
+
+    def assert_readonly_worker_registration(self, actor: str, payload: dict) -> None:
+        profile = self.readonly_worker_profiles.get(actor)
+        if profile is None:
+            return
+        if (
+            str(payload.get("worker_id") or "") != profile.worker_id
+            or str(payload.get("identity") or "") != profile.identity
+            or set(payload.get("capabilities") or []) != set(profile.capabilities)
+            or str(payload.get("trust_zone") or "") != "isolated-review"
+            or int(payload.get("max_concurrency") or 0) != 1
+            or int(payload.get("heartbeat_interval_seconds") or 0) != 15
+        ):
+            raise ForbiddenError("readonly worker registration mismatch")
+
+    def verify_result(
+        self, result: ResultEnvelope, task: TaskRecord | None = None
+    ) -> PolicyDecision:
+        computed = result.computed_digest()
+        if result.result_digest and result.result_digest != computed:
+            return PolicyDecision(False, "result digest mismatch")
+        sensitive = bool(
+            task
+            and (
+                task.task_plan.data_classification
+                in {"confidential", "credential-secret"}
+                or any(
+                    capability.startswith(
+                        ("code.write", "deploy", "secret", "production")
+                    )
+                    for capability in task.task_plan.required_capabilities
+                )
+            )
+        )
+        if sensitive and not (result.signature or result.attestation_ref):
+            return PolicyDecision(False, "trusted result proof required")
+        if result.signature is not None or result.attestation_ref is not None:
+            if self.result_signature_verifier is None:
+                return PolicyDecision(False, "result signature verifier unavailable")
+            if not self.result_signature_verifier(result):
+                return PolicyDecision(False, "result signature invalid")
+            result.trust_status = "trusted_result"
+        else:
+            result.trust_status = "untrusted_shadow_result"
+        return PolicyDecision(True)
+
+    def authorize(self, action: str, actor: str, task: TaskRecord | None = None, context: dict | None = None) -> PolicyDecision:
+        context = context or {}
+        if not self.identity_verifier.verify(actor):
+            return PolicyDecision(False, "identity untrusted")
+
+        action_capabilities = {
+            "create": "task.creator",
+            "read": "task.read",
+            "audit": "task.audit",
+            "claim": "task.claim",
+            "result": "task.claim",
+            "fail": "task.claim",
+            "progress": "task.claim",
+            "heartbeat": "task.claim",
+            "cancel": "task.cancel",
+            "delegate": "task.delegate",
+            "worker.register": "worker.self_register",
+            "worker.admin": "worker.admin",
+        }
+        required_capability = action_capabilities.get(action)
+        if required_capability:
+            granted = set(
+                self.identity_capabilities.get(
+                    actor, self.identity_capabilities.get("*", set())
+                )
+            )
+            if required_capability not in granted:
+                return PolicyDecision(False, f"action {action} not permitted")
+
+        if action in {"claim", "result", "fail", "cancel", "progress", "delegate", "heartbeat"} and not self.execution_enabled:
+            if not self._readonly_worker_allows(action, actor, task):
+                return PolicyDecision(False, "execution disabled")
+
+        if action == "delegate" and task and task.status not in {"COMPLETED", "FAILED_FINAL", "CANCELLED"}:
+            risk = str(context.get("risk", task.task_plan.risk))
+            if RISK_RANK.get(risk, 2) > RISK_RANK.get(self.max_risk, 1):
+                return PolicyDecision(False, f"risk {risk} exceeds policy")
+
+        return PolicyDecision(True)
+
+    def assert_allowed(self, action: str, actor: str, task: TaskRecord | None = None, context: dict | None = None):
+        decision = self.authorize(action, actor, task, context=context)
+        if not decision.allowed:
+            if decision.reason == "identity untrusted":
+                raise ForbiddenError(decision.reason)
+            if decision.reason == "execution disabled":
+                raise LockedError("execution disabled")
+            raise ForbiddenError(decision.reason)
@@ -0,0 +1,76 @@
+"""Task scheduler primitives."""
+
+from __future__ import annotations
+
+import time
+from .errors import NotFoundError
+from .capabilities import has_capabilities
+from .models import WorkerClaim
+from .store import TaskPlaneStore
+
+
+class TaskScheduler:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def next_queued_task(self, worker_id: str):
+        worker = self.store.get_worker(worker_id)
+        tasks = sorted(
+            self.store.list_tasks(),
+            key=lambda task: (
+                -int(task.task_plan.metadata.get("priority", 0)),
+                task.created_at,
+                task.task_id,
+            ),
+        )
+        for task in tasks:
+            if task.status not in {"CREATED", "QUEUED", "FAILED_RECOVERABLE"}:
+                continue
+            if task.task_plan.task_type == "worker.registry.audit":
+                continue
+            if task.status == "FAILED_RECOVERABLE" and not self.store.task_has_retryable_probe(
+                task.task_id
+            ):
+                continue
+            if not has_capabilities(
+                worker.capabilities, task.task_plan.required_capabilities
+            ):
+                continue
+            if any(
+                self.store.get_task(dependency).status != "COMPLETED"
+                for dependency in task.task_plan.dependencies
+            ):
+                continue
+            if (
+                task.task_plan.data_classification == "credential-secret"
+                and worker.worker_type != "secure_file_transformer"
+                and "secure_file_transformer" not in worker.capabilities
+            ):
+                continue
+            return task
+        return None
+
+    def schedule_for_worker(self, worker_id: str, lease_seconds: int = 15) -> WorkerClaim:
+        worker = self.store.get_worker(worker_id)
+        if worker.disabled:
+            from .errors import LockedError
+
+            raise LockedError("worker disabled")
+        if time.time() > worker.last_heartbeat + (
+            worker.heartbeat_interval_seconds * 3
+        ):
+            from .errors import LockedError
+
+            raise LockedError("worker offline")
+        task = self.next_queued_task(worker_id)
+        if task is None:
+            raise NotFoundError("no queued tasks available")
+        claim = self.store.claim_task(
+            task.task_id,
+            worker_id,
+            worker.identity,
+            lease_seconds=lease_seconds,
+            expected_revision=task.revision,
+            operation_digest=task.task_plan.operation_digest(),
+        )
+        return claim
@@ -0,0 +1,68 @@
+"""Worker registry abstraction and read helpers."""
+
+from __future__ import annotations
+
+import time
+
+from .capabilities import has_capabilities
+from .errors import NotFoundError
+from .models import WorkerRegistration
+from .store import TaskPlaneStore
+
+
+class WorkerRegistry:
+    def __init__(self, store: TaskPlaneStore):
+        self.store = store
+
+    def register(
+        self,
+        payload: dict,
+        *,
+        actor_identity: str,
+        is_admin: bool,
+        expected_revision: int | None,
+    ) -> WorkerRegistration:
+        reg = WorkerRegistration.from_dict(payload)
+        return self.store.register_worker(
+            reg,
+            actor_identity=actor_identity,
+            is_admin=is_admin,
+            expected_revision=expected_revision,
+        )
+
+    def heartbeat(
+        self,
+        worker_id: str,
+        heartbeat_interval_seconds: int | None = None,
+        *,
+        actor_identity: str,
+        expected_revision: int | None,
+    ) -> WorkerRegistration:
+        return self.store.heartbeat_worker(
+            worker_id,
+            heartbeat_interval_seconds=heartbeat_interval_seconds,
+            actor_identity=actor_identity,
+            expected_revision=expected_revision,
+        )
+
+    def list(self):
+        return self.store.list_workers()
+
+    def get(self, worker_id: str) -> WorkerRegistration:
+        try:
+            return self.store.get_worker(worker_id)
+        except NotFoundError:
+            raise
+
+    def can_execute(self, worker_id: str, required_capabilities: list[str]) -> bool:
+        worker = self.store.get_worker(worker_id)
+        return has_capabilities(worker.capabilities, required_capabilities)
+
+    def is_online(self, worker_id: str, *, now: float | None = None) -> bool:
+        worker = self.store.get_worker(worker_id)
+        deadline = worker.last_heartbeat + (worker.heartbeat_interval_seconds * 3)
+        return not worker.disabled and (time.time() if now is None else now) <= deadline
+
+    def stale_workers(self, *, now: float | None = None) -> list[WorkerRegistration]:
+        current = time.time() if now is None else now
+        return [worker for worker in self.list() if not self.is_online(worker.worker_id, now=current)]
@@ -1,13 +1,25 @@
 {
-    "current_baseline": "V1R4C6",
-    "previous_baseline": "V1R4C5",
-    "promoted_at": "2026-07-11T21:00:00+08:00",
-    "git": "e204a90398bf646d46245b3088226749fa056edd",
-    "promoted_by": "openclaw/admin",
-    "promotion_reason": "V1R4C6 admin search agent integration, search gateway, agent platform, VERSION bump, merge tests deploy pipeline — not yet deployed to production",
-    "constraints": {
-        "memory_search_enabled": false,
-        "force_push_allowed": false,
-        "gitea_db_mutation_requires_owner_approval": true
-    }
-}
+  "current_baseline": "V2R1C2",
+  "previous_baseline": "V2R1C1",
+  "promoted_at": "2026-07-22T01:40:51Z",
+  "git": "3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24",
+  "promoted_by": "codex/owner-approved-gitops",
+  "promotion_reason": "Owner-authorized V2R1C2 Unified Portal production release after exact tag binding, complete evidence verification, and production acceptance PASS.",
+  "version": "V2R1C2",
+  "release_oid": "3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24",
+  "tag_oid": "a3bd84ebec9c705f7c9c5c03f7f4ec55f8854e36",
+  "target_oid": "3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24",
+  "release_run_id": "AIOS-V2R1C2-PRODUCTION-20260722T011836Z",
+  "status": "PRODUCTION_DEPLOYED",
+  "production_service": "aios-v2r1c2-production.service",
+  "production_port": 18920,
+  "rollback_version": "V2R1C1",
+  "constraints": {
+    "product_code_changed": true,
+    "production_redeployed": true,
+    "production_traffic_changed": true,
+    "tag_rewritten": false,
+    "force_push_allowed": false,
+    "rollback_assets_preserved": true
+  }
+}
@@ -0,0 +1,103 @@
+{
+  "schema_version": 4,
+  "automatic": [
+    "build",
+    "test",
+    "artifact",
+    "canary",
+    "evidence"
+  ],
+  "owner": [
+    "signed_release_plan"
+  ],
+  "forbidden": [
+    "force_push",
+    "tag_rewrite",
+    "direct_main_push",
+    "baseline_mutation",
+    "registry_mutation"
+  ],
+  "runtime_deployment": {
+    "approval_action": "signed_release_plan",
+    "required_capability": "runtime_switch",
+    "tag_operations_allowed": false,
+    "baseline_mutation_allowed": false,
+    "registry_mutation_allowed": false,
+    "writer_default": false,
+    "rollback_required": true
+  },
+  "tag_release": {
+    "approval_action": "signed_release_plan",
+    "required_capability": "tag_publish",
+    "separate_controller": true,
+    "duplicate_conflict": "fail_closed",
+    "rewrite_allowed": false,
+    "force_push_allowed": false
+  },
+  "baseline_registry_finalize": {
+    "approval_action": "signed_release_plan",
+    "required_capability": "baseline_registry_finalize",
+    "separate_controller": true,
+    "remote_tag_verification_required": true,
+    "gitea_api_verification_required": true,
+    "registry_baseline_consistency_required": true
+  },
+  "approval": {
+    "algorithm": "Ed25519",
+    "trust_domain": "aios.production",
+    "maximum_lifetime_seconds": 3600,
+    "release_plan_sha256_required": true,
+    "not_before_required": true,
+    "replay_protection": true,
+    "revocation_fail_closed": true,
+    "key_rotation_supported": true,
+    "capabilities": [
+      "runtime_switch",
+      "tag_publish",
+      "baseline_registry_finalize"
+    ]
+  },
+  "execution": {
+    "environment_variable": "AIOS_SILENT_RELEASE_EXECUTION_ENABLED",
+    "default_enabled": false,
+    "shadow_side_effects_allowed": false,
+    "durable_saga_required": true,
+    "pre_switch_revalidation_required": true,
+    "trusted_candidate_builder_required": true,
+    "actual_plan_regeneration_required": true,
+    "startup_fail_closed_on_missing_component": true,
+    "recovery_worker_shadow_default": true,
+    "production_approval_backend_required": true,
+    "production_builder_signer": "kms-hsm-secret-manager-only",
+    "production_execution_without_backend": "unavailable"
+  },
+  "durability": {
+    "journal": "sha256-hash-chain",
+    "probe_journal": "sha256-hash-chain",
+    "exclusive_capability_claims": true,
+    "side_effect_probe_before_lease_takeover": true,
+    "side_effect_probe_before_failed_recoverable_retry": true,
+    "probe_results": [
+      "NOT_APPLIED",
+      "APPLIED_VERIFIED",
+      "INDETERMINATE",
+      "CONFLICT"
+    ],
+    "probe_operation_digest_required": true,
+    "probe_freshness_required": true,
+    "tamper_result": "MANUAL_OWNER_REVIEW_REQUIRED"
+  },
+  "tag_pending": {
+    "required_observations": [
+      "remote_git_ref",
+      "annotated_tag_object",
+      "peeled_target",
+      "gitea_api",
+      "gitea_listing",
+      "repository_identity"
+    ],
+    "indeterminate_result": "RECONCILIATION_REQUIRED",
+    "conflict_result": "MANUAL_OWNER_REVIEW_REQUIRED",
+    "automatic_reconciliation": false
+  }
+}
@@ -0,0 +1,59 @@
+version: 1
+policy_id: gitops-isolated-worktree-governance-20260714T232948UTC8
+
+runtime_identity:
+  user: aiman
+  group: gitops
+  umask: "0002"
+  prohibit_root_workspace_writes: true
+
+repository:
+  source_worktree: /data/aios-gitops/workspace
+  bare_repo: /data/aios-gitops/repo.git
+  worktree_root: /data/aios-gitops/worktrees
+  remote: origin
+
+worktrees:
+  controller: /data/aios-gitops/worktrees/controller
+  task_pattern: /data/aios-gitops/worktrees/{agent}/{task_id}
+  allowed_agents:
+    - openclaw
+    - chatgpt
+    - controller
+  require_clean_start: true
+  remove_after_successful_push: true
+  retain_on_failure: true
+
+permissions:
+  owner: aiman
+  group: gitops
+  directory_mode: "2775"
+  file_mode: "0664"
+  default_acl:
+    user:aiman: rwx
+    group:gitops: rwx
+  apply_to:
+    - /data/aios-gitops
+    - /data/aios-gitops/worktrees
+
+preflight:
+  required_user: aiman
+  required_group: gitops
+  required_umask: "0002"
+  require_writable_git_dir: true
+  require_writable_task_dir: true
+  require_writable_result_dir: true
+  reject_shared_source_worktree: true
+  reject_existing_git_lock: true
+
+notifications:
+  owner_on_received: required
+  owner_on_terminal: required
+  preferred_channel: weixin
+  redact_secrets: true
+
+rollback:
+  preserve_source_worktree: true
+  remove_created_worktrees: true
+  restore_service_dropins: true
+  restore_service_state: true
@@ -0,0 +1,14 @@
+# Install as a systemd drop-in for GitOps/OpenClaw writer services.
+# Example: /etc/systemd/system/<service>.service.d/10-runtime-identity.conf
+
+[Service]
+User=aiman
+Group=gitops
+SupplementaryGroups=gitops
+UMask=0002
+Environment=AIOS_GITOPS_ROOT=/data/aios-gitops
+Environment=AIOS_BARE_REPO=/data/aios-gitops/repo.git
+Environment=AIOS_WORKTREE_ROOT=/data/aios-gitops/worktrees
+Environment=AIOS_RUNTIME_USER=aiman
+Environment=AIOS_RUNTIME_GROUP=gitops
+Environment=AIOS_RUNTIME_UMASK=0002
@@ -8,12 +8,28 @@ STATE_DIR="${AIOS_V2_STATE_DIR:-/var/lib/aios-v2}"
 BACKUP_ROOT="${AIOS_V2_BACKUP_ROOT:-/var/backups/aios-v2}"
 TARGET_RELEASE="${1:-}"
 RESTORE_STATE="${AIOS_V2_RESTORE_STATE:-0}"
+HEALTH_RETRIES="${AIOS_V2_ROLLBACK_HEALTH_RETRIES:-30}"
+HEALTH_RETRY_DELAY="${AIOS_V2_ROLLBACK_HEALTH_RETRY_DELAY:-1}"

 fail() {
  echo "ERROR: $*" >&2
  exit 1
 }

+run_healthcheck() {
+  local release="$1"
+  local attempt
+  for ((attempt = 1; attempt <= HEALTH_RETRIES; attempt++)); do
+    if AIOS_V2_SERVICE="$SERVICE" \
+       AIOS_V2_STATE_DIR="$STATE_DIR" \
+       "$release/deploy/aios-v2/healthcheck/check.sh"; then
+      return 0
+    fi
+    [[ "$attempt" -lt "$HEALTH_RETRIES" ]] && sleep "$HEALTH_RETRY_DELAY"
+  done
+  return 1
+}
+
 [[ "${EUID}" -eq 0 ]] || fail "rollback must run as root"
 [[ -n "$TARGET_RELEASE" ]] || fail "usage: $0 <release-name-or-absolute-path>"

@@ -53,9 +69,7 @@ mv -Tf "${CURRENT_LINK}.next" "$CURRENT_LINK"
 systemctl daemon-reload
 systemctl start "$SERVICE"

-if AIOS_V2_SERVICE="$SERVICE" \
-   AIOS_V2_STATE_DIR="$STATE_DIR" \
-   "$TARGET_PATH/deploy/aios-v2/healthcheck/check.sh"; then
+if run_healthcheck "$TARGET_PATH"; then
  echo "ROLLBACK_COMPLETE target=$TARGET_PATH backup=$BACKUP_DIR"
  exit 0
 fi
@@ -78,9 +92,7 @@ systemctl daemon-reload
 systemctl start "$SERVICE" || true

 if [[ -n "$PREVIOUS_PATH" && -x "$PREVIOUS_PATH/deploy/aios-v2/healthcheck/check.sh" ]]; then
-  AIOS_V2_SERVICE="$SERVICE" \
-  AIOS_V2_STATE_DIR="$STATE_DIR" \
-  "$PREVIOUS_PATH/deploy/aios-v2/healthcheck/check.sh" || true
+  run_healthcheck "$PREVIOUS_PATH" || true
 fi

 fail "rollback target failed; previous release restored; evidence=$BACKUP_DIR"
@@ -0,0 +1,30 @@
+# AIOS V2R1C2 Unified Portal Candidate
+# Install as /etc/aios-v2/aios-v2r1c2-portal.env with mode 0640.
+# Do not place secret values in this file. Use secret references only.
+
+AIOS_V2_HOST=127.0.0.1
+AIOS_V2_PORT=18921
+AIOS_V2_STATE_DIR=/var/lib/aios-v2r1c2-portal
+AIOS_PROVENANCE_STORE_FILE=/var/lib/aios-v2r1c2-portal/run-provenance.sqlite3
+AIOS_EXTERNAL_TASK_STORE_FILE=/var/lib/aios-v2r1c2-portal/external-task-truth.sqlite3
+AIOS_EXECUTOR_CATALOG_FILE=/var/lib/aios-v2r1c2-portal/executor-catalog.json
+AIOS_EXECUTION_PLAN_FILES=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-RELEASE.json:/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-TAKEOVER.json
+AIOS_EXECUTION_PLAN_FILE=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-TAKEOVER.json
+
+AIOS_RELEASE_VERSION=V2R1C2-CANDIDATE
+AIOS_TARGET_VERSION=V2R1C2
+AIOS_BASELINE_VERSION=V2R1C1
+AIOS_PREVIOUS_VERSION=V2R1C1
+AIOS_RELEASE_STATUS=CANDIDATE_VALIDATION
+AIOS_RELEASE_SOURCE_OID=REPLACE_WITH_EXACT_40_CHARACTER_GIT_OID
+AIOS_RELEASE_OID=candidate-not-tagged
+AIOS_RELEASE_TAG=NOT_CREATED
+AIOS_RELEASE_EVIDENCE_SHA256=pending
+
+AIOS_OPENCLAW_CONTRACT_VERSION=aios.openclaw.command.v2
+AIOS_OPENCLAW_SIGNATURE_ALGORITHM=Ed25519
+AIOS_OPENCLAW_PLUGIN_VERSION=2.1.0-rc.4
+AIOS_OPENCLAW_SIGNING_KEY_ID=openclaw-v2r1-candidate-ed25519
+
+# Runtime resolves this reference through its secret store.
+AIOS_OWNER_WECHAT_TARGET_REF=AIOS_OWNER_WECHAT_TARGET_REF
@@ -0,0 +1,44 @@
+[Unit]
+Description=AIOS V2R1C2 Unified Portal Candidate
+After=network-online.target
+Wants=network-online.target
+ConditionPathExists=/opt/aios-v2r1c2/active-runtime/app/aios_web/release_application.py
+ConditionPathExists=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-RELEASE.json
+ConditionPathExists=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-TAKEOVER.json
+
+[Service]
+Type=simple
+User=aios
+Group=aios
+WorkingDirectory=/opt/aios-v2r1c2/active-runtime/app
+EnvironmentFile=/etc/aios-v2/aios-v2r1c2-portal.env
+Environment=PYTHONUNBUFFERED=1
+Environment=PYTHONDONTWRITEBYTECODE=1
+ExecStartPre=/usr/bin/test "$AIOS_V2_PORT" = "18921"
+ExecStartPre=/usr/bin/test -n "$AIOS_RELEASE_SOURCE_OID"
+ExecStartPre=/usr/bin/test "$AIOS_RELEASE_SOURCE_OID" != "candidate-not-tagged"
+ExecStart=/usr/bin/python3 -m aios_web.release_application
+Restart=on-failure
+RestartSec=3
+TimeoutStartSec=60
+TimeoutStopSec=30
+KillSignal=SIGTERM
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+MemoryDenyWriteExecute=true
+ReadWritePaths=/var/lib/aios-v2r1c2-portal
+StateDirectory=aios-v2r1c2-portal
+StateDirectoryMode=0750
+UMask=0027
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,27 @@
+# AIOS V2R1C2 Unified Portal production metadata.
+# No secret values belong in this file; runtime integrations use references.
+
+AIOS_V2_HOST=127.0.0.1
+AIOS_V2_PORT=18920
+AIOS_V2_STATE_DIR=/var/lib/aios-v2r1c2-production
+AIOS_PROVENANCE_STORE_FILE=/var/lib/aios-v2r1c2-production/run-provenance.sqlite3
+AIOS_EXTERNAL_TASK_STORE_FILE=/var/lib/aios-v2r1c2-production/external-task-truth.sqlite3
+AIOS_EXECUTOR_CATALOG_FILE=/var/lib/aios-v2r1c2-production/executor-catalog.json
+AIOS_EXECUTION_PLAN_FILES=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-RELEASE.json:/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-TAKEOVER.json
+AIOS_EXECUTION_PLAN_FILE=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-TAKEOVER.json
+
+AIOS_RELEASE_VERSION=V2R1C2
+AIOS_TARGET_VERSION=V2R1C2
+AIOS_BASELINE_VERSION=V2R1C1
+AIOS_PREVIOUS_VERSION=V2R1C1
+AIOS_RELEASE_STATUS=PRODUCTION
+AIOS_RELEASE_SOURCE_OID=3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24
+AIOS_RELEASE_OID=3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24
+AIOS_RELEASE_TAG=V2R1C2
+AIOS_RELEASE_EVIDENCE_SHA256=2e27bb73b8e6297bd3077238f73a96d697fc3c3611c601c4dc9357e5fdcd8eee
+
+AIOS_OPENCLAW_CONTRACT_VERSION=aios.openclaw.command.v2
+AIOS_OPENCLAW_SIGNATURE_ALGORITHM=Ed25519
+AIOS_OPENCLAW_PLUGIN_VERSION=2.1.0-rc.4
+AIOS_OPENCLAW_SIGNING_KEY_ID=openclaw-v2r1-candidate-ed25519
+AIOS_OWNER_WECHAT_TARGET_REF=AIOS_OWNER_WECHAT_TARGET_REF
@@ -0,0 +1,44 @@
+[Unit]
+Description=AIOS V2R1C2 Unified Portal Production
+After=network-online.target
+Wants=network-online.target
+Conflicts=aios-orchestrator-gateway.service
+ConditionPathExists=/opt/aios-v2r1c2/active-runtime/app/aios_web/release_application.py
+ConditionPathExists=/opt/aios-v2r1c2/plans/AIOS-V2R1C2-UNIFIED-PORTAL-TAKEOVER.json
+
+[Service]
+Type=simple
+User=aios
+Group=aios
+WorkingDirectory=/opt/aios-v2r1c2/active-runtime/app
+EnvironmentFile=/etc/aios-v2/aios-v2r1c2-production.env
+Environment=PYTHONUNBUFFERED=1
+Environment=PYTHONDONTWRITEBYTECODE=1
+ExecStartPre=/usr/bin/test "$AIOS_V2_PORT" = "18920"
+ExecStartPre=/usr/bin/test "$AIOS_RELEASE_SOURCE_OID" = "3dd622b5a515f1fa4ef72b9f8ae9ce48ac703f24"
+ExecStartPre=/usr/bin/test "$AIOS_RELEASE_TAG" = "V2R1C2"
+ExecStart=/usr/bin/python3 -m aios_web.release_application
+Restart=on-failure
+RestartSec=3
+TimeoutStartSec=60
+TimeoutStopSec=30
+KillSignal=SIGTERM
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+MemoryDenyWriteExecute=true
+ReadWritePaths=/var/lib/aios-v2r1c2-production
+StateDirectory=aios-v2r1c2-production
+StateDirectoryMode=0750
+UMask=0027
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
@@ -11,6 +11,8 @@ Environment=AIOS_GITOPS_WORKSPACE=/data/aios-gitops/workspace
 Environment=AIOS_GITOPS_DB=/data/aios-gitops/runtime/gitops_model.sqlite3
 Environment=AIOS_GITOPS_TOKEN_FILE=/data/aios-gitops/runtime/secrets/gitops.tokens
 Environment=AIOS_GITOPS_BARE_REPO=/data/aios-gitops/runtime/gitea-bin/data/repositories/aios/aios-v23.git
+Environment=AIOS_GITOPS_AUTHORITATIVE_GIT_DIR=/data/aios-gitops/repo.git
+Environment=AIOS_GITOPS_REPOSITORY_IDENTITY=aios/aios
 Environment=AIOS_GITOPS_HOST=127.0.0.1
 Environment=AIOS_GITOPS_PORT=18890
 ExecStart=/usr/bin/python3 /data/aios-gitops/workspace/active-runtime/app/aios_chatgpt_actions_api.py
@@ -0,0 +1,45 @@
+[Unit]
+Description=AIOS Candidate OpenClaw Session Broker
+After=aios-session-broker-bootstrap-writer-candidate.service
+Requires=aios-session-broker-bootstrap-writer-candidate.service
+ConditionPathIsDirectory=/data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725
+ConditionPathExists=/data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/broker-policy.json
+
+[Service]
+Type=simple
+User=aiman
+Group=gitops
+WorkingDirectory=/data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725
+Environment=PYTHONDONTWRITEBYTECODE=1
+RuntimeDirectory=aios-openclaw-session-broker-candidate
+RuntimeDirectoryMode=0700
+RuntimeDirectoryPreserve=restart
+LoadCredential=broker_control_token:/data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/secrets/broker-control-token.source
+ExecStart=/usr/bin/python3 /data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725/services/aios-session-broker-candidate/candidate_session_broker.py --policy /data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/broker-policy.json --database /data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/evidence/broker-state.sqlite3 --projection-root /run/aios-openclaw-session-broker-candidate/sessions --writer-endpoint http://127.0.0.1:19932 --host 127.0.0.1 --port 19931
+Restart=on-failure
+RestartSec=2
+
+NoNewPrivileges=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+LockPersonality=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+IPAddressDeny=any
+IPAddressAllow=localhost
+UMask=0077
+CapabilityBoundingSet=
+AmbientCapabilities=
+MemoryDenyWriteExecute=true
+SystemCallArchitectures=native
+ReadWritePaths=/data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725
+ReadWritePaths=/run/aios-openclaw-session-broker-candidate
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,46 @@
+[Unit]
+Description=AIOS task-scoped Candidate Bootstrap Writer
+After=network.target
+ConditionPathIsDirectory=/data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725
+ConditionPathExists=/data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/writer-policy.json
+
+[Service]
+Type=simple
+User=aiman
+Group=gitops
+WorkingDirectory=/data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725
+Environment=PYTHONDONTWRITEBYTECODE=1
+RuntimeDirectory=aios-session-broker-bootstrap-writer-candidate
+RuntimeDirectoryMode=0700
+RuntimeDirectoryPreserve=restart
+LoadCredential=writer_token:/data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/secrets/writer-token.source
+LoadCredential=gitea_git_http:/etc/aios-gitops/credentials/gitea-git-http
+ExecStart=/usr/bin/python3 /data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725/services/aios-session-broker-candidate/candidate_writer.py --policy /data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/writer-policy.json --worktree /data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725 --git-dir /run/aios-session-broker-bootstrap-writer-candidate/candidate.git --state /data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/evidence/writer-state.json --audit /data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725/evidence/writer-audit.jsonl --host 127.0.0.1 --port 19932
+Restart=on-failure
+RestartSec=2
+
+NoNewPrivileges=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+LockPersonality=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+IPAddressDeny=any
+IPAddressAllow=localhost
+UMask=0077
+CapabilityBoundingSet=
+AmbientCapabilities=
+MemoryDenyWriteExecute=true
+SystemCallArchitectures=native
+ReadWritePaths=/data/aios-gitops/worktrees/openclaw-real-dispatch-session-broker-20260725
+ReadWritePaths=/data/aios-gitops/runtime/tasks/AIOS-SESSION-BROKER-BOOTSTRAP-20260725
+ReadWritePaths=/run/aios-session-broker-bootstrap-writer-candidate
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,25 @@
+[Unit]
+Description=AIOS Silent Release Shadow Controller
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=aiman
+Group=gitops
+UMask=0077
+Environment=AIOS_GITOPS_WRITES_ENABLED=false
+Environment=AIOS_SILENT_RELEASE_EXECUTION_ENABLED=false
+Environment=PYTHONDONTWRITEBYTECODE=1
+ExecStart=/usr/bin/python3 /usr/libexec/aios-silent-release-shadow/current/active-runtime/app/silent_release_execution.py --state-root /var/lib/aios-silent-release-shadow --repository /data/aios-gitops/repo.git --host 127.0.0.1 --port 18891 --poll-seconds 30
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/aios-silent-release-shadow
+ReadOnlyPaths=/data/aios-gitops/repo.git /usr/libexec/aios-silent-release-shadow
+
+[Install]
+WantedBy=multi-user.target
@@ -221,6 +221,14 @@ OpenClaw/Hermes 结果只有在与持久 Dispatch 的身份和执行上下文完
 - 至少校验 tenant、task、agent、principal、trace、runtime、runtime execution、provenance 和 run。
 - 不同终态结果摘要不得覆盖已有终态。
 - Hermes 终态结果必须来自持有 Job Lease 的 Worker。
+- Hermes Worker 生命周期验收入口必须是默认关闭的内部接口，仅接受可信
+  `runtime` 或 `platform_admin` 身份；普通 Operator、浏览器和公共 API 不得直接调用。
+- 每次 Claim/Start/Heartbeat/Complete/Fail/Cancel 必须绑定
+  tenant、task、trace、principal、provenance、run、dispatch、job、cell 和 profile。
+- Complete/Fail/Cancel 必须通过 `ExecutionOrchestrator.reconcile_hermes` 更新权威
+  Task/Dispatch，并同步生成 Audit/Event 与 Execution Evidence。
+- Lease 到期必须持久化清除旧 Owner、递增 revision 并允许安全重领；旧 Worker
+  后续 Result 必须拒绝。
 - Runtime callback 审计不得绕过 Orchestrator Reconcile。

 ### UR-019 Dispatch 持久化与恢复
@@ -232,6 +240,8 @@ Runtime 副作用之前必须持久化唯一 Dispatch，重启后能够恢复并
 - 同租户 Task 和 Runtime Execution 各自唯一绑定一个 Dispatch。
 - Dispatch 支持按 ID、Task 与 Runtime Execution 查询。
 - 终态 Dispatch 不得迁移到不同终态。
+- Hermes Job、Result、Lease、幂等键和 Worker heartbeat 必须与 Dispatch 一样在
+  服务重启后恢复；不得以只存在于进程内的 Map 作为在线验收依据。
 - 有 SQLite Repository 重启恢复测试。

 ### UR-020 OpenClaw Ed25519 命令合同
@@ -329,4 +339,4 @@ OpenClaw 生产命令必须使用版本化 Ed25519 合同，不得继续使用 H
 7. 租户用户在 Web Console 查看完整链路。
 8. 跨租户、跨 Principal、跨 Grant Path 和重放请求被拒绝。
 9. 服务重启后 Control Plane、Dispatch 和 Provenance 状态恢复。
-10. 候选部署健康检查、Acceptance 和回滚演练实际执行并保存证据。
+10. 候选部署健康检查、Acceptance 和回滚演练实际执行并保存证据。
@@ -4,6 +4,10 @@
 - 状态：加固候选契约基线
 - 原则：Control Plane 权威、Runtime 仅执行、默认拒绝、服务级最小权限、全链路租户隔离、所有权威状态可审计和恢复

+核心模型名称与实现保持逐字同步：`RequestContext` 承载可信租户、主体、角色、trace、
+session 与 policy version；`TaskState` 是 AIOS 权威 Task 生命周期枚举，Runtime Worker
+不得直接写入或复制该状态机。
+
 ## 1. 通用可信上下文契约

 所有控制与执行请求必须携带以下上下文：
@@ -345,6 +349,8 @@ signature
 - 过期、未来时间超差、签名错误、Key ID 或 Fingerprint 不匹配时拒绝。
 - Fingerprint 使用恒定时间比较。
 - `key_id` 只引用密钥，不包含密钥材料。
+- Candidate 组合层必须把 `AIOS_OPENCLAW_SIGNING_KEY_ID` 原样传入 Orchestrator，
+  不得在已有批准 Key ID 时回落为默认值。

 ### 11.2 OpenClawResult

@@ -374,6 +380,17 @@ attempts

 ## 12. Hermes Contract

+### 12.0 内部生命周期入口
+
+- 路径：`/api/v2/internal/runtime/hermes/lifecycle/{claim,start,heartbeat,complete,fail,cancel,status}`。
+- `AIOS_HERMES_LIFECYCLE_API_ENABLED` 默认关闭；关闭时按不存在的路由 fail closed。
+- 仅可信反向代理注入且具备 `runtime` 或 `platform_admin` 角色的身份可调用。
+- 所有写请求必须携带并严格匹配 tenant、task、trace、principal、provenance、run、
+  dispatch、job、cell、profile；Claim 还必须指定精确 job，不能从分区中误领其他 Job。
+- Worker 不得直接修改 Task Store。Complete、Fail 和 Cancel 产生的 HermesResult
+  必须经持久 Dispatch 校验并由 `ExecutionOrchestrator.reconcile_hermes` 终态化。
+- 每次成功生命周期写入同时落盘 Hermes 状态、Audit/Event 和 Execution Evidence。
+
 ### 12.1 HermesJob

 ```text
@@ -400,6 +417,10 @@ updated_at
 - `tenant_id + cell_id + profile_id` 形成执行分区。
 - claim 只能领取同分区 Job。
 - Lease 到期 Job 回到 QUEUED。
+- Hermes Store 使用 `AIOS_V2_STATE_DIR/hermes.sqlite3` 保存 Job、Result、Lease、
+  Idempotency 和 Worker heartbeat；Adapter 仍是唯一 Queue/Lease 状态机。
+- Lease 到期重排必须清空 `assigned_worker_id`、清空 `lease_expires_at`、递增 revision
+  并持久化。重启后由显式 lifecycle status/claim 或健康检查安全触发重排。
 - revision 冲突不得覆盖。

 ### 12.2 HermesResult
@@ -422,6 +443,8 @@ finished_at
 - 终态 Result 必须携带 Worker ID。
 - Worker 必须持有 Job Lease。
 - Result 必须匹配 Dispatch、Principal、Parent Provenance 和 Run。
+- 相同 Worker、相同终态和相同 output/error 的重复提交返回原 Result；不同终态或
+  不同结果内容返回 Conflict，不得覆盖已持久化终态。
 - 只允许内部入口 `POST /api/v2/internal/runtime/hermes/reconcile` 处理。
 - 旧入口 `POST /api/v2/hermes/results/reconcile` 返回 `410 Gone`。

@@ -566,6 +589,10 @@ POST /api/v2/tasks/{id}/fail     -> 403
 - 默认只回滚代码。
 - 状态恢复需独立 Rollback Grant 和显式批准。
 - 回滚后必须执行 Healthcheck 与恢复验证。
+- Release Archive 必须保留 `rollback.sh` 与 `healthcheck/check.sh` 的 executable bit；
+  验收测试必须阻止非执行模式进入候选包。
+- `systemctl start` 后的回滚健康检查必须执行有界 readiness 重试，默认最多 30 次、
+  每次间隔 1 秒；不得因服务尚未监听的一次瞬时拒绝误判目标 Release 失败。

 ## 18. 契约变更规则

@@ -20,23 +20,23 @@
 |---|---|---|---|---|---|
 | UR-001 唯一控制面 | ADR-001；模块契约第 2～6 节 | `active-runtime/app/aios_v2/control_plane.py`、`gateway.py`、`orchestrator.py` | `tests/aios_v2_candidate/test_candidate_flow.py` | `deploy/aios-v2/acceptance/run-all.sh`；公共生命周期旁路负向检查 | 已实现；测试已提交；待验收 |
 | UR-002 复用现有能力 | ADR-002 | `active-runtime/app/aios_openclaw/`、`active-runtime/app/aios_hermes/`、`active-runtime/app/aios_v2/orchestrator.py` | `test_candidate_flow.py` | OpenClaw/Hermes 联调 | 已实现；真实 Runtime 联调待验收 |
-| UR-003 OpenClaw/Hermes 解耦 | ADR-002；模块契约第 11、12 节 | OpenClaw Adapter、Hermes Adapter/Worker、内部 Reconcile | `test_candidate_flow.py` | `/api/v2/internal/runtime/hermes/reconcile`；Runtime callback 审计检查 | 已实现；测试已提交；待验收 |
+| UR-003 OpenClaw/Hermes 解耦 | ADR-002、ADR-010；模块契约第 11、12 节 | OpenClaw Adapter、Hermes Adapter/Worker、内部 Lifecycle/Reconcile | `test_candidate_flow.py`、`test_hermes_live_lifecycle.py` | 默认关闭的内部 Runtime API；Runtime audit/evidence 检查 | 已实现；Hermes 专项 17/17 |
 | UR-004 全面 Web 化 | 目标架构；模块契约第 15 节 | `active-runtime/app/aios_v2/app.py`、`console.py`、`gateway.py` | `test_candidate_flow.py` | Web/API 冒烟、Healthcheck | 已实现；UI/浏览器验收待执行 |
 | UR-005 多租户隔离 | ADR-004 | `control_plane.py`、`persistence.py`、`execution_tracking.py`、`dispatch_store.py` | `test_candidate_flow.py::test_cross_tenant_task_read_is_denied` | 跨租户负向 Acceptance | 已实现；测试已提交；待验收 |
 | UR-006 权威任务生命周期 | ADR-001；模块契约第 4 节 | `control_plane.py`、`gateway.py`、`orchestrator.py` | `test_candidate_flow.py` | `/start`、`/complete`、`/fail` 应返回拒绝；Runtime 严格 Reconcile | 已实现；测试/接口验收待执行 |
 | UR-007 策略与审批 | ADR-001 | `control_plane.py`、`gateway.py` | `test_candidate_flow.py` | Approval、deny audit、policy version 检查 | 已实现；策略场景验收待执行 |
-| UR-008 幂等与并发安全 | 模块契约第 4、10、12 节 | Task idempotency/revision、Hermes lease/revision、Dispatch 唯一约束 | `test_candidate_flow.py` | 幂等冲突、Lease、终态冲突 Acceptance | 已实现；测试代码覆盖部分场景；待验收 |
+| UR-008 幂等与并发安全 | 模块契约第 4、10、12 节 | Task idempotency/revision、Hermes lease/revision、Dispatch 唯一约束 | `test_candidate_flow.py`、`test_hermes_live_lifecycle.py` | Lease 到期重排、换主、相同终态幂等、不同终态冲突 | 已实现；专项测试通过 |
 | UR-009 可观测与执行证据 | 模块契约第 6、13 节 | `execution_tracking.py`、`gitops_status.py`、`console.py` | `test_candidate_flow.py::test_execution_tracking_persists_claim_heartbeat_and_result` | `/api/v2/executions`、Evidence Receipt 检查 | 已实现；测试已提交；待验收 |
 | UR-010 GitOps 唯一变更流程 | ADR-003 | `active-runtime/app/aios_v2/provenance_git.py`、GitOps 工具与任务资产 | `test_provenance.py`、Grant 隔离测试 | Branch/Commit/Push 门禁、Controller clean、OID 同步 | 已实现候选控制；环境 GitOps 验收待执行 |
-| UR-011 持久化与恢复 | ADR-006；模块契约第 10、16 节 | `persistence.py`、`dispatch_store.py`、`provenance.py`、`provenance_grants.py` | `test_candidate_flow.py` 中 Control Plane 与 Dispatch recovery | 重启、备份、恢复、锁等待、容量测试 | 候选实现完成；恢复测试已提交；生产 HA/容量待验收 |
+| UR-011 持久化与恢复 | ADR-006、ADR-010；模块契约第 10、12、16 节 | `persistence.py`、`dispatch_store.py`、`aios_hermes/adapter.py::SQLiteHermesStore`、Provenance/Grant Store | `test_candidate_flow.py`、`test_hermes_live_lifecycle.py` | 运行中 Job 重启恢复、重启后 Reconcile、SQLite quick_check | Hermes/Dispatch/Task 恢复测试通过；生产 HA/容量待验收 |
 | UR-012 审计与合规 | ADR-001、ADR-004、ADR-009 | `control_plane.py` AuditEvent、`app.py` callback audit、Provenance/Grant Event/Receipt | `test_candidate_flow.py`、`test_provenance.py`、`test_provenance_grant_isolation.py` | `/api/v2/audit`、Receipt/Event 完整性检查 | 已实现候选审计；不可变外部固化待预发布 |
 | UR-013 密钥安全 | ADR-009；模块契约第 6、11、17 节 | Ed25519 Signer/Verifier、protected file reader、SecretRef 配置 | `test_provenance.py`、`test_candidate_flow.py` | Secret scanner、权限检查、容器/systemd credential 检查 | 已实现；环境密钥注入验收待执行 |
 | UR-014 部署与回滚 | 迁移与交付文档；模块契约第 17 节 | `deploy/aios-v2/systemd/`、`docker/`、`healthcheck/`、`rollback/` | Acceptance 脚本与候选测试 | systemd/Docker 安装、Healthcheck、备份与回滚演练 | 资产已提交；实际部署/回滚未执行 |
 | UR-015 文档与代码同步 | ADR-005 | `tools/aios_v2_docs_code_check.py`、`docs/aios-v2/` | 文档门禁脚本 | Acceptance Runner 调用文档门禁 | 已实现；门禁尚未实际执行 |
 | UR-016 Workflow Run Provenance | ADR-009；模块契约第 7 节 | `active-runtime/app/aios_v2/provenance.py`、`provenance_grants.py::WorkflowProvenanceIssuer` | `test_provenance.py`、`test_provenance_grant_isolation.py::test_parent_workflow_has_no_operational_rights` | CLI `issue-workflow`、状态/撤销检查 | 已实现；测试已提交；待验收 |
 | UR-017 最小权限子 Grant | ADR-009；模块契约第 8 节 | `provenance_grants.py`、`provenance_scoped.py` | `test_provenance_grant_isolation.py` | `issue-grant`、Grant status/revoke、Receipt 检查 | 已实现；专项测试已提交；待验收 |
-| UR-018 Runtime Result 信任绑定 | ADR-009；模块契约第 10～12 节 | `orchestrator.py`、`dispatch_store.py`、内部 Hermes Reconcile | `test_candidate_flow.py` | OpenClaw/Hermes 伪造 tenant/task/trace/principal/provenance/run 负向验收 | 已实现；恢复正向测试已提交；完整负向验收待执行 |
-| UR-019 Dispatch 持久化与恢复 | ADR-009；模块契约第 10 节 | `dispatch_store.py`、`orchestrator.py`、`app.py` | `test_candidate_flow.py::test_dispatch_and_control_plane_recover_before_hermes_reconcile` | 进程重启后读取 Dispatch 并完成 Reconcile | 已实现；测试已提交；待执行 |
+| UR-018 Runtime Result 信任绑定 | ADR-009、ADR-010；模块契约第 10～12 节 | `orchestrator.py`、`dispatch_store.py`、内部 Hermes Lifecycle/Reconcile | `test_hermes_live_lifecycle.py` | tenant/task/trace/principal/provenance/run/dispatch/job/cell/profile/worker 负向矩阵 | 已实现；专项 17/17 |
+| UR-019 Dispatch 持久化与恢复 | ADR-009、ADR-010；模块契约第 10、12 节 | `dispatch_store.py`、`orchestrator.py`、`app.py`、`SQLiteHermesStore` | Dispatch recovery 与 Hermes restart-reconcile 测试 | 进程重启后读取 Dispatch/Job 并完成 Reconcile | 已实现；测试通过 |
 | UR-020 OpenClaw Ed25519 命令合同 | ADR-009；模块契约第 11 节 | `active-runtime/app/aios_openclaw/contract.py`、`adapter.py`、`app.py` | `test_candidate_flow.py`、`test_provenance.py` | 真实 OpenClaw v2 合同联调、Key rotation、clock skew/expiry 负向验收 | 已实现；测试代码已升级；真实联调待执行 |
 | UR-021 服务级权限隔离 | ADR-009；模块契约第 9 节 | `provenance_scoped.py`、`provenance_operations.py`、`app.py` | `test_provenance_grant_isolation.py` | Application 仅加载 Runtime/Evidence/Audit；Git/Deploy/Rollback 单独 Scope | 已实现；专项测试已提交；配置验收待执行 |
 | UR-022 CLI 单 Grant 授权 | ADR-009；模块契约第 9 节 | `provenance_cli.py` | `test_provenance_grant_isolation.py` 提供 Writer/Grant 基础验证；CLI 端到端待补执行证据 | `authorize --path ... --grant-id ...`；旧批量 Grant 参数应不存在 | 已实现；CLI 端到端验收待执行 |
@@ -0,0 +1,211 @@
+# AIOS V2R1C2 统一门户与可迁移执行器补充契约
+
+- 文档版本：`V2R1C2-candidate`
+- 状态：实现与测试资产已提交；在线 Acceptance、Owner 审批与生产发布未完成
+- 适用范围：统一角色门户、External Task Truth、Executor Provider、Execution Plan、通知回执、候选部署与 Release Gate
+- 关联决策：`ADR-011`
+
+## 1. 新增用户需求
+
+### UR-023 统一角色感知门户
+
+AIOS 必须使用同一 Web Portal 服务平台管理员、租户管理员、操作员、审批人、审计员、Runtime、发布经理和只读用户。服务端能力矩阵是唯一授权依据，前端隐藏按钮不得替代服务端授权。
+
+验收：
+
+- 门户至少包含总览、租户与 Agent、任务、执行中心、授权、Runtime、Evidence、Audit、GitOps/Release。
+- `GET /api/v2/me/capabilities` 返回可信身份解析后的角色、能力和导航。
+- 所有写操作必须再次进行服务端 Capability 检查。
+- 浏览器不得直接调用 OpenClaw、Hermes、Codex 或未来执行器。
+
+### UR-024 外部执行任务真相
+
+任何由 OpenClaw、Hermes、Codex 或未来 Provider 执行的任务，必须进入同一持久 Execution Truth Registry。任务文件、进程存在、日志字符串或退出码不能单独证明任务已经执行。
+
+统一生命周期：
+
+```text
+DECLARED -> REGISTERED -> CLAIMED -> RUNNING -> SUCCEEDED
+                                     |       -> FAILED
+                                     + timeout -> STALLED
+REGISTER deadline exceeded -> NOT_STARTED
+```
+
+验收：
+
+- 每次执行绑定 `task_id`、`executor_type`、`executor_id` 和 `executor_run_id`。
+- Claim、Start、Heartbeat、Success、Fail 均持久化事件。
+- Success 只有在所有步骤和 Required Evidence SHA256 完整时才允许。
+- 启动超时和心跳超时必须产生可查询的阻塞状态。
+
+### UR-025 可迁移 Executor Provider
+
+执行器类型不得由核心枚举固定。OpenClaw、Hermes 和 Codex 只是内置 Provider；未来执行器必须通过版本化 Provider Descriptor、Catalog 和 Adapter 接入，复用相同生命周期、Evidence、Notification 与 Gate。
+
+验收：
+
+- Provider Descriptor 包含 `executor_type`、`adapter_version`、`protocol_version`、`trust_roles`、`capabilities` 和配置 Schema。
+- Catalog 支持原子持久化、SHA256、防篡改导入导出和无 Secret 迁移包。
+- 新增 Provider 不修改 Truth Registry、Execution Plan 状态机、Portal 或 Release Gate。
+- API 的可信角色由 Provider Catalog 动态解析，不硬编码执行器名称。
+
+### UR-026 多 Provider Execution Plan
+
+发布任务必须可表达为任意 Provider 组成的 DAG。下游 Stage 在全部依赖 Gate 通过前保持 `WAITING_DEPENDENCY`，不得提前声明并消耗启动时限。
+
+验收：
+
+- Plan 使用 `aios.execution-plan.v2`，执行协议使用 `aios.executor.v1`。
+- Stage 包含 Provider、角色、步骤、依赖、Required Evidence、通知事件和超时。
+- Plan 创建时只声明根 Stage；依赖通过后原子激活下游 Stage。
+- 聚合 Release Gate 只有在全部 Required Stage 的 Truth、Evidence、Dependency 和 Notification Gate 通过时才允许放行。
+
+### UR-027 Owner 主动通知与发布门禁
+
+候选部署开始、成功和失败必须生成持久 Notification Outbox 事件。投递目标使用 Secret Reference，真实微信投递必须回写 Receipt SHA256。通知失败可幂等重试，但不得生成重复事件。
+
+验收：
+
+- `(task_id, event_type)` 唯一，同一 STARTED/SUCCEEDED/FAILED 事件只有一个 Notification ID。
+- `PENDING` 和 `FAILED` 均可重试；成功后原地更新为 `DELIVERED`。
+- Release Gate 要求配置的 STARTED 和 SUCCEEDED 通知均有 Receipt。
+- Git、日志、Portal 和任务资产不得存储微信账号、Token 或 Secret。
+
+## 2. 补充模块契约
+
+### 2.1 Executor Provider Catalog
+
+权威实现：
+
+- `active-runtime/app/aios_v2/executor_protocol.py`
+- `active-runtime/app/aios_v2/executor_catalog.py`
+- `active-runtime/app/aios_v2/official_executor_providers.py`
+
+Catalog 只包含可迁移描述符，不包含 Endpoint Credential、Token、私钥或 Runtime Secret。导入迁移包必须同时校验 Package SHA256 与 Catalog SHA256。
+
+### 2.2 External Execution Truth
+
+权威实现：
+
+- `active-runtime/app/aios_v2/task_execution_registry.py`
+- `active-runtime/app/aios_v2/external_task_control.py`
+- `active-runtime/app/aios_v2/external_task_query.py`
+
+Truth Record 是外部执行状态的唯一事实源。`SUCCEEDED` 不等于 Release 可放行；仍需 Required Notification Receipt 和 Plan Dependency Gate。
+
+### 2.3 Execution Plan
+
+权威实现：
+
+- `active-runtime/app/aios_v2/execution_plan.py`
+- `active-runtime/app/aios_v2/executor_worker.py`
+- `tools/aios_execution_plan_cli.py`
+
+Plan 是 Stage 定义的唯一事实源。不得再复制维护三个独立 Task Manifest，否则会产生 Plan/Task 漂移并可能提前启动下游计时。
+
+### 2.4 Portal/API
+
+权威实现：
+
+- `active-runtime/app/aios_web/capabilities.py`
+- `active-runtime/app/aios_web/application.py`
+- `active-runtime/app/aios_web/release_application.py`
+- `active-runtime/app/aios_web/external_task_api.py`
+- `active-runtime/app/aios_web/execution_plan_api.py`
+- `active-runtime/app/aios_web/console.py`
+
+核心新增 API：
+
+```text
+GET /api/v2/portal/execution
+GET /api/v2/portal/external-tasks
+GET /api/v2/internal/execution-plans/{plan_id}/discover?executor={provider}
+GET /api/v2/internal/execution-plans/{plan_id}/snapshot?executor={provider}
+GET /api/v2/internal/execution-plans/{plan_id}/gate?executor={provider}
+GET /api/v2/internal/external-tasks/discover?executor={provider}
+POST /api/v2/internal/external-tasks/{task_id}/{register|claim|start|heartbeat|succeed|fail}
+GET /api/v2/internal/external-tasks/notifications?executor={provider}
+POST /api/v2/internal/external-tasks/notifications/{notification_id}/ack
+```
+
+内部 API 只接受可信代理注入身份。Provider Trust Role、Task Manifest Executor 与 Principal/Executor ID 必须一致。
+
+### 2.5 Candidate Deployment
+
+候选服务：
+
+- `deploy/aios-v2/systemd/aios-v2r1c2-portal.service`
+- `deploy/aios-v2/systemd/aios-v2r1c2-portal.env.example`
+
+约束：
+
+- V2R1C1 生产继续监听 `127.0.0.1:18920`。
+- V2R1C2 Candidate 只监听 `127.0.0.1:18921`。
+- Candidate 使用 `/var/lib/aios-v2r1c2-portal`，不得复用生产状态目录。
+- `AIOS_RELEASE_SOURCE_OID` 必须解析为精确 40 位 Git OID，否则拒绝启动。
+- Portal 不直接创建 Tag、修改 `main` 或部署生产。
+
+## 3. V2R1C2 发布计划
+
+权威计划：
+
+- `plans/AIOS-V2R1C2-UNIFIED-PORTAL-RELEASE.json`
+
+DAG：
+
+```text
+openclaw-candidate-deploy
+        |
+        v
+hermes-runtime-validation
+        |
+        v
+codex-release-review
+        |
+        v
+AIOS Owner approval -> tag/release request
+```
+
+OpenClaw 负责隔离候选部署、离线/在线 Acceptance、Role/Tenant 负向测试、重启与回滚演练；Hermes 负责 Queue/Lease/Worker/恢复验证；Codex 负责源代码、证据、安全边界、文档追踪和发布建议审查。所有 Provider 使用同一 Truth Registry。
+
+## 4. 需求追踪矩阵
+
+| 需求 | 决策/契约 | 实现 | 测试/验收 | 状态 |
+|---|---|---|---|---|
+| UR-023 统一门户 | ADR-011；本文 2.4 | `aios_web/*` | `tests/web/test_portable_executor_release.py`；在线 Portal Acceptance | 已实现；测试资产已提交；在线未执行 |
+| UR-024 执行真相 | ADR-011；本文 2.2 | `task_execution_registry.py`、`external_task_control.py` | Truth/Evidence/Notification tests；CLI Gate | 已实现；实际执行证据待 OpenClaw/Hermes/Codex |
+| UR-025 Provider 可迁移 | ADR-011；本文 2.1 | `executor_protocol.py`、`executor_catalog.py`、`official_executor_providers.py` | Catalog migration/tamper/dynamic Provider tests | 已实现；测试资产已提交 |
+| UR-026 Execution Plan DAG | ADR-011；本文 2.3 | `execution_plan.py`、`executor_worker.py` | 下游延迟激活、聚合 Gate tests | 已实现；在线 DAG 未执行 |
+| UR-027 主动通知 | ADR-011；本文 2.2 | Notification Outbox、Worker retry | 首投失败、幂等重试、Receipt Gate test | 已实现；真实微信投递未执行 |
+
+## 5. Acceptance 与证据
+
+离线/在线验收入口：
+
+```text
+python3 tools/aios_v2r1c2_acceptance.py \
+  --source-oid <exact-40-character-oid> \
+  [--online] \
+  --evidence-output artifacts/v2r1c2/acceptance-evidence.json
+```
+
+专项测试：
+
+- `tests/web/test_portable_executor_release.py`
+- `tests/aios_v2_candidate/`
+
+机器证据至少包含：命令、时间、退出码、输出 SHA256、HTTP 响应 SHA256、Source OID、Plan SHA256、Catalog SHA256、Service/Env SHA256、回滚结果和微信 Receipt SHA256。
+
+## 6. 当前门禁状态
+
+| Gate | 状态 | 说明 |
+|---|---|---|
+| 代码与部署资产 | 已提交 | 当前候选分支包含实现、Plan、systemd、CLI 和测试资产 |
+| 测试执行 | 未验证 | 当前 GitOps 工具未执行 Python 测试，禁止声称通过 |
+| OpenClaw Candidate Stage | `NOT_STARTED` | 必须由目标环境实际 Discover/Register/Claim/Start |
+| Hermes Runtime Stage | `WAITING_DEPENDENCY` | OpenClaw Gate 通过后才激活 |
+| Codex Review Stage | `WAITING_DEPENDENCY` | OpenClaw 与 Hermes Gate 通过后才激活 |
+| 微信通知 | 未投递 | 需要目标环境 Sender 和 Receipt 回写 |
+| Tag/生产发布 | 未批准 | 需要 Plan Gate 通过和 AIOS Owner 明确批准 |
+
+测试文件、Acceptance 脚本、Task YAML、systemd 文件或日志文本的存在都不等于实际 Gate 已通过。
@@ -0,0 +1,51 @@
+# V2R1C2 Owner Provenance 与微信接管迁移
+
+## 边界
+
+本迁移不关闭或降低 `aios-tenant-boundary`。普通、已识别的消息可以进入只读对话；
+只有服务端确认的 Owner 才能为 `aios_protected_dispatch` 自动签发
+`aios.owner-provenance/v2`。未知、阻止名单和受保护操作的非 Owner 请求继续 fail closed。
+
+客户端不得提交可信身份 Header、私钥、签名或 Provenance Token。插件从 OpenClaw
+可信 hook 上下文取得 `principal_id`、`agent_id`、`run_id` 和 execution path，并对
+精确工具参数计算 SHA256。服务端签发记录绑定：
+
+- `tenant_id`
+- `principal_id`
+- `task_id`
+- `agent_id`
+- `run_id`
+- `execution_path`
+- `request_digest`
+- `issued_at` / `expires_at`
+- `key_id` 与覆盖全部字段的 Ed25519 signature
+
+参数在 hook 与 tool execute 之间改变、错误身份绑定、过期、撤销或单次 permit 重放
+都会被拒绝。
+
+## 配置迁移
+
+私钥仍位于仓库外。部署系统只写入路径引用，并验证目标文件存在、为普通文件且权限
+不向 group/other 开放。需要在 Candidate 专用配置中增加：
+
+```text
+provenancePrivateKeyPath=<outside-git path>
+provenancePublicKeyPath=<outside-git path>
+provenanceStoreDir=/var/lib/aios-v2r1c2-portal/provenance
+provenanceKeyId=<non-secret key id>
+tenantId=<candidate tenant>
+protectedDispatchProvider=chatgpt-supervisor
+protectedDispatchTransport=mock|sandbox
+ownerProvenanceTtlMs<=300000
+```
+
+`mockFailFirstDelivery` 只允许在明确的模拟验收配置中启用。模拟输出必须保留：
+`simulation=true`、`transport=mock|sandbox`、`real_user_impersonated=false`。
+
+## 部署与回滚
+
+1. 从精确 Candidate OID 构建插件与 Portal；不得从 live 目录回写源码。
+2. 备份 Candidate 插件、配置和 unit；不修改 18920 服务或状态目录。
+3. 在 18921 完成正向链、负向矩阵、mock/sandbox 微信、restart recovery。
+4. 回滚只停止 `aios-v2r1c2-portal.service` 并恢复 Candidate 备份；随后重新验证 18920。
+5. 未经 Owner 明确批准，不创建 Tag、不修改 `main`、不替换生产。
@@ -1,240 +1,104 @@
-# AIOS V2R1 加固与实际验收刷新报告
+# AIOS V2R1 Hermes 生命周期最终验证报告

- 报告版本：`V2R1-execution-refresh-20260721.1`
+- 报告版本：`V2R1-hermes-lifecycle-20260721.3`
 - 日期：`2026-07-21`
- 分支：`patch/chatgpt/AIOS-V2R1-HARDENING-20260721`
- 总体状态：`PARTIAL / BLOCKED_EVIDENCE_REQUIRED`
+- 分支：`patch/chatgpt/AIOS-V2R1-HERMES-LIFECYCLE-20260721`
+- 固定验证 OID：`95d2e52cb55c7b913e89bc6bed2bcdacf67512d4`
+- 总体状态：`PARTIAL / BLOCKED_GLOBAL_WORKTREE_CLEANLINESS`
 - 发布决策：`STOP_PREPRODUCTION`
- Gate A：`PASS`（执行方报告 `0 errors / 0 warnings`）
- Gate B：`PASS`（执行方报告 `10/10`）
- 离线 Acceptance：`PASS_WITH_EXPECTED_WARNING`（`8 passed / 0 failed / 1 expected warning`）
 - 生产发布：`NOT_APPROVED`

-> 本报告刷新并取代此前“Run Provenance 尚未实现、Gate A 不允许执行”的旧快照。当前五项原始高风险 Blocker 均已解除。唯一剩余发布阻塞是 Live AIOS/Hermes 缺少可调用的完整在线 Worker 生命周期端点与对应证据。
+## 1. 执行结论

-## 1. 证据来源与可信度说明
+`BLK-LIVE-HERMES-FULL-LIFECYCLE-EVIDENCE-MISSING` 的 Hermes 功能与证据子条件已在固定 OID 上全部通过。候选实现复用现有 Hermes Adapter、Queue、Lease、Task 与 Orchestrator 状态机，新增持久 SQLite Store 和默认关闭的受保护内部生命周期接口。Hermes 完整生命周期 `17/17`、候选测试 `49/49`、Gate A、Gate B `10/10`、离线 Acceptance `8/0/1`、真实 OpenClaw HTTP、重启恢复、双向回滚和最终健康检查均通过。

-本报告依据执行方提供的实际执行结论、OID、同步状态、验收统计和日志路径刷新。当前 GitOps 工具可以提交和读取仓库内容，但不能直接读取所列主机绝对路径下的日志，因此：
+但 Owner 指令规定只有全部 Acceptance 条件同时满足时才允许正式解除该 Blocker。由于“所有 Worktree clean”失败，本报告不得把它标记为正式 `RESOLVED`；准确状态是 `EVIDENCE_COMPLETE / FORMAL_CLOSURE_BLOCKED`。

- 本报告将这些结果标记为“执行方已实际验证并提供证据路径”。
- 本会话未独立重放或读取日志内容。
- Merge、Tag、生产部署和风险接受仍需 AIOS Owner 独立批准。
- 任何与原始日志不一致的情况，应以不可变日志、退出码和签名 Evidence 为准。
+最终发布门禁仍失败：权威 Bare Repo 登记的 88 个 worktree 中有 10 个脏 worktree。候选 worktree 和活动 Controller worktree 均 clean，且无 locked/prunable；但 Owner 的验收条件要求所有 worktree clean，因此不得准备 RC、不得发起 Tag Approval Request、不得进入预生产评审。

-主要证据路径：
+## 2. 关键实现

- `/var/lib/aios-gitops/acceptance/aios-v2r1-20260721T0325Z/online-runtime-openclaw-final4.log`
- `/var/lib/aios-gitops/acceptance/aios-v2r1-20260721T0325Z/restart-recovery.log`
- `/var/lib/aios-gitops/acceptance/aios-v2r1-20260721T0325Z/rollback-drill-final3.log`
+- `SQLiteHermesStore` 持久保存 Job、Result、Idempotency 与 Worker Heartbeat。
+- 现有 `HermesAdapter` 保持唯一 Queue/Lease 状态机，支持指定 Job claim、租约到期 requeue、重启恢复与严格终态冲突。
+- 生命周期身份绑定覆盖 tenant、task、trace、principal、provenance、run、dispatch、job、cell、profile。
+- start/heartbeat/complete/fail 强制 Lease Owner；complete/fail/cancel 通过 `ExecutionOrchestrator.reconcile_hermes` 更新 Task 与 Dispatch。
+- cancel 仅允许同时具备 `runtime` 与 `platform_admin` 的 AIOS Control Plane，要求 `cancellation_source=aios-control-plane`，并拒绝携带 `worker_id`，Worker 只能观察取消。
+- 所有成功生命周期操作写入 Audit/Event/Execution Evidence；接口由 `AIOS_HERMES_LIFECYCLE_API_ENABLED` 控制，默认关闭。

-## 2. 权威版本与仓库状态
+## 3. 固定 OID 验证

-| 项目 | 刷新值 | 状态 |
-|---|---|---|
-| 权威 Bare Repo | `/data/aios-gitops/repo.git` | 已报告可用 |
-| Candidate OID | `ba7669c3b49f98cf3500af6ea966ba0db472ff3b` | 已同步 |
-| OpenClaw Task/Gitea OID | `0be3ba09e42b4f6db56461e3ca3a3fcc0a487f31` | `local_oid == gitea_oid` |
-| Codex Task/Gitea OID | `6b0db21a852928106600914075ca50114cb07def` | `local_oid == gitea_oid` |
-| 活动隔离 Release OID | `b158041b8633e658c34ce182f3c8aa97b4bf5f9a` | 当前验收 Release |
-| Controller 修复 OID | `6188da26453505dacde9d6d298191437164c8d27` | detached、clean、fully synced |
-| OpenClaw Runtime 插件 | `2.1.0-rc.3` | 已用于在线验收 |
-| OpenClaw 包含最新 Candidate | 是 | 通过 |
-| OpenClaw/Codex Worktree | clean | 通过 |
-| Worktree 锁 | `0` | 通过 |
-| Prunable Worktree | `0` | 通过 |
-| `main` 修改 | 无 | 通过 |
-| Tag 创建 | 无 | 通过 |
-| Force Push | 无 | 通过 |
-| 生产流量切换 | 无 | 通过 |
-
-## 3. 原始五项高风险 Blocker
-
-以下五项均已解除，当前未发现回退：
-
-| Blocker | 刷新状态 | 证据摘要 |
-|---|---|---|
-| `BLK-OPENCLAW-PLAINTEXT-SECRETS` | `RESOLVED` | `plaintext/unresolved/shadowed/legacy = 0`；Gateway Token 已轮换；未记录 Secret 值 |
-| `BLK-AIOS-V2-SIGNING-MATERIAL-MISSING` | `RESOLVED` | Ed25519 Key ID `openclaw-v2r1-candidate-ed25519`；`aios:aios 0600`；sign/verify、篡改拒绝通过 |
-| `BLK-CANDIDATE-NOT-MERGED` | `RESOLVED` | OpenClaw 包含最新 Candidate；三分支本地与 Gitea OID 一致 |
-| `BLK-OPENCLAW-RUN-PROVENANCE-MISSING` | `RESOLVED` | 已实现 Workflow Provenance、持久 Store、最小权限 Child Grant、Scoped Writer、Dispatch/Result 严格绑定及相关测试 |
-| `BLK-CONTROLLER-LEGACY-GITEA-CHECK` | `RESOLVED` | 活跃代码清除旧 `aios-v23` 硬编码；Controller 12/12；Token 降权为 `read:repository` 并通过 systemd `LoadCredential` 注入 |
-
-### 3.1 Run Provenance 刷新说明
-
-旧状态认为插件只有进程内 `runId/sender` Map，缺少 Owner-signed schema、持久 Store 和专用 Writer。当前加固实现已经提供：
-
- 无操作权限的父 Workflow Provenance；
- Ed25519 签名与公钥验证；
- SQLite WAL Provenance/Grant/Usage/Event Store；
- Runtime、Evidence、Git、Deployment、Rollback、Audit、Code Change 独立 Child Grant；
- GitOperation 级别限制；
- 服务级 Scoped Writer 与 CLI 单 Grant 授权；
- 撤销、过期、重放和上下文绑定；
- 持久 Dispatch 与 Runtime Result 严格 Reconcile。
-
-因此，`BLK-OPENCLAW-RUN-PROVENANCE-MISSING` 不再成立。
-
-## 4. 安全验证结果
-
-### 4.1 Secret 与凭据
-
-| 检查 | 结果 |
+| 项目 | 结果 |
 |---|---|
-| 原明文 Secret 发现 | `3` |
-| 当前明文 Secret | `0` |
-| unresolved | `0` |
-| shadowed | `0` |
-| legacy | `0` |
-| Gateway Token 轮换 | 通过 |
-| OneAPI 实际 Agent 调用 | 通过 |
-| Controller Token 权限 | `read:repository` |
-| Controller Token 注入 | systemd `LoadCredential` |
-| Secret 值写入记录 | 否 |
+| Python syntax/import | PASS |
+| 全部 candidate tests | `49/49` |
+| Grant isolation | `11/11` |
+| Dispatch recovery | `1/1` |
+| Hermes lifecycle | `17/17` |
+| Docs code gate / Gate A | `0 errors / 0 warnings` |
+| Secret scan | `547 tracked files / 0 violations` |
+| SQLite quick_check | `2/2 ok` |
+| Gate B | `10/10` |
+| Offline Acceptance | `8 passed / 0 failed / 1 expected warning` |
+| OpenClaw real HTTP | `COMPLETED` |
+| Hermes full live rerun | `17/17` |
+| Restart recovery | `2/2` |
+| Previous → Current rollback/forward | PASS |
+| State preservation | `STATE_PRESERVED_EXACTLY=PASS` |
+| Corrected final health (`16R`) | PASS，三服务 active |

-### 4.2 Signing Material
+原 `16.log` 由非服务用户执行健康脚本，打印 state-dir 权限失败后被外层脚本错误覆盖为退出码 0，因此不作为通过证据。纠错后的 `16R.log` 使用受控 `sudo env`，子 shell 保留失败码，所有健康项实际 PASS 且 `EXIT_CODE=0`。原文件保留用于审计。

-| 检查 | 结果 |
-|---|---|
-| 文件存在 | 是 |
-| Key ID | `openclaw-v2r1-candidate-ed25519` |
-| 所有者/权限 | `aios:aios 0600` |
-| 合同 | 真实 Ed25519，`aios.openclaw.command.v2` |
-| sign/verify | 通过 |
-| 篡改拒绝 | 通过 |
-| 过期拒绝 | 通过 |
-| 跨租户拒绝 | 通过 |
+回滚日志中的短暂 connection-refused 发生于 systemd 重启窗口内，受 `AIOS_V2_ROLLBACK_HEALTH_RETRIES=30` 与 1 秒间隔限制；前后两次均在界限内达到健康、输出 `ROLLBACK_COMPLETE`，并完成状态文件精确哈希对账。

-## 5. Gate 与 Acceptance 刷新
+## 4. Evidence

-| Gate/验收项 | 实际结果 | 刷新状态 |
+- 根目录：`/var/lib/aios-gitops/acceptance/aios-v2r1-hermes-lifecycle-20260721T054205Z`
+- `steps.tsv` SHA256：`b2ad20585ba7f576e85657827a0b1db6f252887bbd73bcd718df38623e9d95cf`
+- `final-live-gate.log` SHA256：`82040c674759dacf587658c5e936c313a1f50e8e2425be48ad891927befdf4fa`
+- `16R.log` SHA256：`641246927a372ebaa9e6dde8b018b88275b2ba15a442473759b23fb1f215d9cf`
+- `15.log` SHA256：`b0a474e2a74164f560c4f7572091911f32011c75faccd37a3c7315046275011e`
+- `13.log` SHA256：`b9f637cca6e97ed893bf38530e05cd33b78e324c5e8865d4c602dfeac22a7710`
+- `12R2.log` SHA256：`0c431f5f5f1c1b17acda160c917b08c7f4036485016c23e1236b9b6f4a78de67`
+
+证据只记录身份、状态、命令、时间、退出码与 Hash，不记录 Secret 值。
+
+## 5. Git 与运行态门禁
+
+| 门禁 | 当前值 | 结果 |
 |---|---|---|
-| Gate A | `0 errors / 0 warnings` | `PASS` |
-| Gate B | `10/10` | `PASS` |
-| 离线 Acceptance | `8 passed / 0 failed / 1 expected warning` | `PASS_WITH_EXPECTED_WARNING` |
-| OpenClaw 在线 Health | 通过 | `PASS` |
-| OpenClaw Execute | 通过 | `PASS` |
-| OpenClaw Status | 通过 | `PASS` |
-| OpenClaw Cancel | 通过 | `PASS` |
-| OpenClaw Timeout | 通过 | `PASS` |
-| OpenClaw 幂等 | 通过 | `PASS` |
-| OpenClaw 篡改拒绝 | 通过 | `PASS` |
-| OpenClaw 过期拒绝 | 通过 | `PASS` |
-| OpenClaw 跨租户拒绝 | 通过 | `PASS` |
-| AIOS → OpenClaw 真实 HTTP | `COMPLETED` | `PASS` |
-| AIOS/Hermes 基础 enqueue/reconcile | 通过 | `PASS` |
-| OpenClaw 跨重启幂等 | 通过 | `PASS` |
-| AIOS Tenant/Agent/Task/Audit/Idempotency/Evidence 恢复 | 通过 | `PASS` |
-| SQLite `PRAGMA quick_check` | `ok` | `PASS` |
-| 受控双向回滚 | Previous `2a2b702…` ↔ Current `b158041…` | `PASS` |
-| 回滚业务状态保护 | 未覆盖业务状态 | `PASS` |
-| Live Hermes 完整生命周期 | 在线端点与证据不完整 | `BLOCKED_EVIDENCE_REQUIRED` |
+| Bare/Gitea/Candidate OID | 全部 `95d2e52cb55c7b913e89bc6bed2bcdacf67512d4` | PASS |
+| Candidate worktree | clean | PASS |
+| Active Controller | `6188da26453505dacde9d6d298191437164c8d27`，detached、clean | PASS |
+| Locked worktree | `0` | PASS |
+| Prunable worktree | `0` | PASS |
+| 全局 worktree clean | `10 dirty / 88 total` | FAIL |
+| 当前隔离 Release | `b158041b8633e658c34ce182f3c8aa97b4bf5f9a` | 已恢复 |
+| AIOS/OpenClaw/Controller services | active | PASS |

-## 6. Controller Health
+10 个脏 worktree 均不属于本任务允许清理的范围：

-| 检查 | 结果 |
-|---|---|
-| 活跃修复 OID | `6188da26453505dacde9d6d298191437164c8d27` |
-| 旧 `aios-v23` 硬编码 | 活跃代码中已清除 |
-| Controller 测试 | `12/12` |
-| 部署 Worktree | detached、clean |
-| Gitea | `true` |
-| local_sync | `synced` |
-| gitea_sync | `synced` |
-| oid_match | `true` |
-| branch_sync | `true` |
-| sync_status | `fully_synced` |
-| 首次部署失败回滚 | 已实际触发并验证 |
+1. `chatgpt/TASK-V2R1-PERSONAL-WEIXIN-GOLDEN-CONTRACT-R2-20260715`（36）
+2. `chatgpt/TASK-V2R1-PERSONAL-WEIXIN-PORTAL-ADAPTER-20260715`（2）
+3. `chatgpt/TASK-WORKTREE-CONCURRENCY-CHATGPT-20260715T055106UTC8`（2）
+4. `codex`（56）
+5. `codex/TASK-CODEX-AIOS-SPARK-RUNNER-PROVISIONING-20260717T103500UTC8`（6）
+6. `controller`（11）
+7. `openclaw`（5）
+8. `openclaw/TASK-OPENCLAW-V2R1-PERSONAL-WEIXIN-B3-EVIDENCE-HARDEN-20260716T133000UTC8`（3）
+9. `openclaw/TASK-V2R1-OPENCLAW-WEIXIN-WEB-LOGIN-CONTRACT-20260715`（20）
+10. `openclaw/TASK-WORKTREE-CONCURRENCY-OPENCLAW-20260715T055106UTC8`（3）

-## 7. 当前唯一发布阻塞
+## 6. Reviewer

-### `BLK-LIVE-HERMES-FULL-LIFECYCLE-EVIDENCE-MISSING`
+独立 Spark Reviewer 首先发现 cancel 权限边界不够明确；该问题已在 `95d2e52` 修复并新增三条 HTTP 断言。纠错后 Reviewer 确认代码安全边界、16 步证据与有界回滚均 PASS。对发布门禁的最终布尔复核为：`DIRTY_WORKTREE_COUNT=10` 且 `GLOBAL_WORKTREE_CLEAN=false`，所以全局门禁 FAIL，不能进入预生产评审。

-Live AIOS 当前只暴露 Hermes `enqueue/reconcile`，没有可调用或可观测的完整在线 Worker 生命周期端点，因此以下场景尚无完整在线证据：
+## 7. Blocker 与发布决策

- `claim`
- `start`
- `heartbeat`
- `fail`
- `cancel`
- `lease expiry`
- `worker crash recovery`
- `Cell/Profile rejection`
- `invalid-result rejection`
+- 功能与证据子条件通过、正式关闭受阻：`BLK-LIVE-HERMES-FULL-LIFECYCLE-EVIDENCE-MISSING`
+- 直接阻断条件：`BLK-GLOBAL-WORKTREE-CLEANLINESS`
+- 状态：`BLOCKED_EVIDENCE_REQUIRED`
+- 决策：`STOP_PREPRODUCTION`

-这不是 Run Provenance 缺失，也不是基础 Hermes Adapter 失效；它是在线验收可观测面和完整生命周期证据不足。
+本轮未修改 `main`、未创建 Tag、未 Force Push、未切换生产流量、未部署新 RC、未输出 Secret。

-### 7.1 解除条件
-
-必须在隔离预发布环境中实际完成并保存：
-
-1. Worker claim/start/heartbeat 正向链路；
-2. Worker fail/cancel 终态链路；
-3. Lease 到期重新排队或重新领取；
-4. Worker 进程崩溃后的恢复；
-5. 错误 Cell/Profile 的拒绝；
-6. 非 Lease Owner 或上下文不匹配 Result 的拒绝；
-7. Dispatch、Task、Audit、Evidence、Grant Receipt 的一致性；
-8. 服务重启后继续 Reconcile；
-9. 完整命令、时间、退出码、日志路径和 Artifact Hash；
-10. Owner/Reviewer 对证据的独立复核。
-
-### 7.2 不接受的替代证据
-
-以下不能解除本 Blocker：
-
- 仅有单元测试文件；
- 仅有离线 Hermes enqueue/reconcile；
- 仅证明 OpenClaw 在线链路；
- 仅修改状态文档；
- 仅提供无退出码或无日志路径的口头结论；
- 通过手工修改 Task 状态伪造 Worker 生命周期。
-
-## 8. 发布决策
-
-### 8.1 当前决策
-
-```text
-Overall:       PARTIAL / BLOCKED_EVIDENCE_REQUIRED
-Gate A:        PASS
-Gate B:        PASS
-Offline:       PASS_WITH_EXPECTED_WARNING
-OpenClaw Live: PASS
-Hermes Basic:  PASS
-Hermes Full:   BLOCKED
-Preproduction: STOP
-Production:    NOT APPROVED
-```
-
-### 8.2 允许事项
-
- 继续在当前非 `main` 加固分支修复与补证据；
- 在隔离 Release/预发布环境增加 Hermes 生命周期端点或受控验收驱动；
- 运行在线负向测试、重启恢复和回滚演练；
- 更新 `.agent` Evidence、Acceptance 日志与本报告；
- 提交 Reviewer 可复核的 Evidence Manifest。
-
-### 8.3 禁止事项
-
- 不得修改 `main`；
- 不得创建生产 Tag；
- 不得 Force Push；
- 不得切换生产流量；
- 不得因 Gate A/B 和 OpenClaw 已通过而忽略 Hermes 完整在线证据；
- 不得把当前状态描述为“全部完成”或“可放行预生产”。
-
-## 9. 后续最小执行计划
-
-1. 为 Live AIOS/Hermes 提供受保护的内部 Worker 生命周期验收面，或使用等价受信测试驱动直接调用真实在线 Queue/Lease/Worker 实现。
-2. 执行完整 Hermes 正向、负向、Lease、Crash、Restart 场景。
-3. 保存日志、退出码、时间戳、OID、配置摘要和 Artifact Hash。
-4. 将 Evidence 写入租户隔离 `.agent` 路径并提交非 `main` 分支。
-5. 由独立 Reviewer 复核 Result/Dispatch/Task/Audit/Grant Receipt 一致性。
-6. 仅在 Blocker 解除后将总体状态刷新为 `READY_FOR_PREPRODUCTION_REVIEW`；最终放行仍需 Owner 批准。
-
-## 10. 最终结论
-
-五项原始高风险 Blocker 已全部解除，Gate A、Gate B、离线 Acceptance、OpenClaw 在线链路、基础 Hermes、重启恢复、SQLite 完整性和双向回滚均已有执行方报告的实际通过结果。
-
-但 Live Hermes 完整 Worker 生命周期仍缺少可调用端点和完整在线证据。因此本次刷新结论为：
-
-> **AIOS V2R1 已从“核心安全 Blocker 未解除”提升为“核心加固与主要验收通过，但 Hermes 在线生命周期证据未闭环”。继续停止预生产放行，直到 `BLK-LIVE-HERMES-FULL-LIFECYCLE-EVIDENCE-MISSING` 被实际证据解除。**
+下一步唯一允许动作：由各 worktree Owner 审查并提交、归档或可信清理上述 10 个脏 worktree，然后重新执行全局 Git 门禁。只有全局 dirty 数量降为 0 后，才允许准备 RC 与 Tag Approval Request。
@@ -0,0 +1,80 @@
+# ADR-010：Hermes 在线生命周期使用默认关闭的内部 Runtime API
+
+- 状态：Accepted for Release Candidate
+- 日期：2026-07-21
+- 范围：AIOS V2R1 Hermes Worker Lifecycle Acceptance
+
+## 决策
+
+使用现有 `HermesAdapter` Queue/Lease 状态机，增加 SQLite 持久 Store，并通过默认关闭的
+内部 Runtime API 执行 Claim、Start、Heartbeat、Complete、Fail、Cancel 与 Status。
+不建立第二套 Queue、Lease 或 Task 状态机。
+
+内部 API 只接受可信代理注入且具有 `runtime`/`platform_admin` 角色的身份。请求必须绑定
+tenant、task、trace、principal、provenance、run、dispatch、job、cell 和 profile。
+Complete、Fail、Cancel 只能经 `ExecutionOrchestrator.reconcile_hermes` 更新权威 Task。
+
+## 背景
+
+原 Candidate 已具有进程内 Hermes Claim/Lease/Worker 能力及持久 Dispatch，但在线服务
+只暴露 enqueue/reconcile，且 Hermes Job/Lease 本身在重启后丢失，不能形成完整在线证据。
+
+## 原因
+
+直接验收驱动会形成 Adapter 之外的额外变更入口，难以证明 HTTP 身份、Dispatch 与
+Orchestrator 边界。受保护的内部 API 可以在真实 localhost 服务、真实 SQLite Store 和
+真实 HTTP 解析路径上验证完整生命周期，同时在生产通过配置保持关闭。
+
+## 备选方案
+
+- 受信验收驱动直接导入 Adapter：改动较小，但不能证明内部 HTTP 身份与请求解析边界，拒绝。
+- 新建独立 Queue/Lease 服务：会产生第二状态机和双写一致性问题，禁止。
+- 开放公共 Worker API：扩大攻击面并允许浏览器/Operator 触发 Runtime 状态，禁止。
+
+## 安全不变量
+
+1. 只有 APPROVED Task 可由 Orchestrator 创建 Hermes Job。
+2. Dispatch 在 Runtime 副作用前持久化。
+3. Worker 只能操作精确绑定且由其持有 Lease 的 Job。
+4. Runtime 结果必须通过完整身份元组与持久 Dispatch 校验。
+5. 只有 Orchestrator 能把 Task/Dispatch 推进到 Runtime 终态。
+6. 生命周期写入同步生成 Audit/Event 与 Execution Evidence。
+7. 相同终态重放幂等，不同终态或不同内容 fail closed。
+
+## 恢复语义
+
+`SQLiteHermesStore` 持久保存 Job、Result、Lease、幂等键与 Worker heartbeat。服务重启
+加载同一状态；过期 Lease 被持久重排为 QUEUED，清理旧 Owner 并递增 revision。新 Worker
+可重领，旧 Worker 的 Start/Heartbeat/Result 被拒绝。
+
+## 影响与风险
+
+- 正面：同一 Adapter 状态机获得持久恢复、真实 HTTP 验收、严格身份绑定和可审计证据。
+- 负面：SQLite Snapshot 每次生命周期变更都执行同步事务，需在预生产观察锁等待与吞吐。
+- 风险：可信代理头是身份边界；因此接口必须保持 localhost/内部路由、默认关闭，并由部署
+  配置保证外部请求不能自行注入身份头。
+
+## 迁移与回滚
+
+新 Store 文件为新增的 `hermes.sqlite3`，不修改既有 Control Plane/Dispatch schema。回滚到
+Previous OID 时保留该文件但旧版本不读取；不得用旧备份覆盖新业务状态。重新升级时可继续
+加载。接口回滚只需关闭环境开关并恢复 Previous Release OID。
+
+## 合规检查
+
+- 不修改 main，不创建 Tag，不绕过 Provenance/Grant。
+- 生产默认关闭生命周期验收入口。
+- Secret 不进入请求、Audit、Evidence 或测试数据。
+- Result 由 Orchestrator 与持久 Dispatch 校验，负向场景 fail closed。
+
+## 受影响资产
+
+- 代码：`aios_hermes/adapter.py`、`aios_v2/app.py`、`orchestrator.py`、`gateway.py`。
+- 测试：`test_hermes_live_lifecycle.py` 及 Candidate/Provenance 回归。
+- 文档：用户需求、模块合同、追踪矩阵、Gate A 报告与本 ADR。
+
+## 验证
+
+`tests/aios_v2_candidate/test_hermes_live_lifecycle.py` 通过真实 localhost HTTP Server 与
+临时 SQLite 状态目录覆盖 17 项正向、负向、Lease、幂等和重启场景。最终发布结论仍必须
+以提交后的 Gate、在线回归、Secret Audit、SQLite 检查、回滚与独立 Reviewer 证据为准。
@@ -16,6 +16,7 @@
 | ADR-007 | 当前仓库未分配；禁止补写不存在的历史决策 | 未分配 |
 | ADR-008 | 当前仓库未分配；禁止补写不存在的历史决策 | 未分配 |
 | [ADR-009](ADR-009-provenance-least-privilege.md) | Workflow Provenance、最小权限子 Grant 与服务级 Scope | 已采纳 |
+| [ADR-010](ADR-010-hermes-live-lifecycle.md) | Hermes 在线生命周期使用默认关闭的内部 Runtime API | RC 已采纳；待 Owner 发布批准 |

 ## 2. 编号规则

@@ -0,0 +1,7 @@
+# Session Broker Final Release Candidate
+
+Task: `AIOS-CHATGPT-SESSION-BROKER-FINAL-RELEASE-20260726`
+
+This branch is based on the exact approved main OID `875d41c3101093149414292067fd700dc214d4d3` and preserves the dormant Candidate/Integration history through an ordinary no-fast-forward merge.
+
+Current scope remains Candidate/shadow-only. Production transport, services, execution flags, tags, Baseline, and Registry are unchanged.
@@ -0,0 +1,268 @@
+# AIOS Silent Release Controller Design Report
+
+状态：隔离分支实现；生产 mutation 禁止
+目标：自动准备 → 自动验证 → 单次 Owner 签名授权 → 分控制器自动执行与验收
+
+## 1. 当前痛点
+
+现有流程需要多轮人工传递 commit、tree、artifact、manifest、测试、canary、drop-in
+和回滚证据。证据在不同消息里重复抄写，容易出现：
+
+- 构建后 artifact、manifest 或 policy 已变化，但旧批准仍被使用；
+- Git、Gitea、systemd 与回滚结果由人工拼接，缺少同一一致性快照；
+- runtime switch、tag、Baseline、Registry 的授权边界不清；
+- 重启后只剩工作树内临时 JSON，无法可靠恢复；
+- approval replay、并发 writer、key revoke 和 secret inheritance 缺少统一防线。
+
+## 2. 新架构
+
+```text
+Build / Test / Canary
+        |
+        v
+ReleaseCandidate + DeploymentPlan
+        |
+        v
+ReleaseAcceptanceEngine
+        |
+        v
+READY_FOR_APPROVAL
+        |
+        v
+SignedReleasePlanApproval (Ed25519)
+        |
+        +--> runtime_switch capability
+        |       DeploymentController
+        |
+        +--> tag_publish capability
+        |       TagController
+        |
+        +--> baseline_registry_finalize capability
+                BaselineRegistryFinalizeController
+
+Durable ReleaseSagaStore + CapabilityLedger + Event Journal
+贯穿三个控制器；控制器互相不拥有对方的 mutation API。
+```
+
+一次 Owner 批准是同一个不可变 release plan 的签名，不是一个万能执行入口。三个 capability
+分别消费、分别留痕、分别幂等恢复。`force_push`、`tag_rewrite`、`direct_main_push`
+永远不是可签发 capability。
+
+## 3. 状态机
+
+```text
+PREPARING
+  -> VERIFYING
+  -> READY_FOR_APPROVAL
+  -> APPROVED
+  -> PRE_SWITCH_REVALIDATING
+  -> SWITCH_PENDING
+  -> SWITCHED
+  -> RUNTIME_VERIFYING
+  -> TAG_PENDING
+  -> TAG_VERIFIED
+  -> BASELINE_REGISTRY_PENDING
+  -> COMPLETED
+
+任一可恢复故障 -> RECONCILIATION_REQUIRED
+对象冲突       -> MANUAL_OWNER_REVIEW_REQUIRED
+切换后失败     -> ROLLBACK_PENDING -> ROLLED_BACK
+```
+
+状态快照使用 revision compare-and-set；事件同时写入 append-only journal。writer 崩溃后根据
+状态确定唯一恢复动作。并发控制器中只有一个 CAS winner。
+
+## 4. 数据模型
+
+### ReleaseCandidate
+
+```text
+candidate_id
+source_commit
+tree_oid
+artifact_sha256
+manifest_sha256
+tests
+canary
+rollback_ready
+git_consistency
+gitea_consistency
+approval_state
+```
+
+### DeploymentPlan
+
+```text
+service
+release_path / release_root
+dropin_path / dropin_sha256
+rollback_path / rollback_sha256
+source_commit
+artifact_sha256
+manifest_sha256
+policy_sha256
+health_contract
+sha256
+```
+
+### SignedReleasePlanApproval
+
+```text
+release_plan_id
+candidate_id
+source_commit
+tree_oid
+artifact_sha256
+manifest_sha256
+deployment_plan_sha256
+policy_sha256
+approval_plan_id
+evidence_closure_oid
+owner_approval_record_oid
+capabilities
+expires_at
+nonce
+key_id
+signature
+fingerprint
+```
+
+签名内容使用 canonical JSON，`signature` 不参与被签名字段。验证包括 Ed25519 签名、过期时间、
+公钥状态、approval revoke、candidate/plan/policy 逐字段绑定和 capability allowlist。
+
+## 5. API
+
+```text
+POST /createReleaseCandidate
+GET  /getReleaseCandidate?candidate_id=...
+GET  /getApprovalEnvelope?candidate_id=...
+POST /submitOwnerApproval
+POST /startDeployment
+GET  /getReleaseSaga?candidate_id=...
+```
+
+写接口要求 Bearer scope。`AIOS_SILENT_RELEASE_EXECUTION_ENABLED=false` 是默认值；此时可以
+持久化 candidate、生成 approval envelope、保存经验证的 Owner approval 和读取 Saga，
+但 `/startDeployment` 只返回 `SHADOW_MODE` 与空 `side_effects`。
+
+## 6. PreSwitchValidator
+
+切换前重新收集并比较：
+
+- source commit 与 tree；
+- artifact、manifest、policy 和 deployment plan SHA-256；
+- rollback readiness；
+- local、authoritative bare 与 Gitea refs；
+- repository identity；
+- task writer/production writer 边界；
+- health contract。
+
+任一变化都抛出：
+
+```text
+APPROVAL_STALE_REAPPROVAL_REQUIRED
+```
+
+旧批准不会被“最佳努力”继续使用。
+
+## 7. systemd 防线
+
+- service 与 drop-in 均为显式 allowlist；
+- release 与 drop-in resolved path 必须位于 release root 内；
+- 拒绝普通文件被替换为 symlink，拒绝 symlink escape；
+- deployment lock 覆盖 switch、restart 和首次 health check；
+- restart 前后记录 MainPID 与 ActiveEnterTimestampMonotonic；
+- artifact、drop-in、rollback 和 manifest 均按 plan hash 复验；
+- 子进程只接收固定 allowlist 环境，不继承 token、password、credential、askpass、
+  auth socket、`LD_PRELOAD`、`PYTHONPATH` 或数据库连接串。
+
+## 8. TagController 分离
+
+TagController 必须独立完成 approval、execute、verify，并留下：
+
+```text
+evidence_closure_oid
+approval_plan_id
+repository_identity
+remote_tag_oid
+remote_peeled_target_oid
+gitea_api_tag_oid
+gitea_listing_visible
+```
+
+同名 tag 的 tag OID 或 peeled target 不同，进入
+`MANUAL_OWNER_REVIEW_REQUIRED`；自动流程不 push、不删除、不重写、不 force push。
+
+## 9. Baseline / Registry 门禁
+
+只有以下全部一致时，`baseline_registry_finalize` capability 才能完成：
+
+```text
+Registry = Baseline = remote tag = Gitea API = expected target
+```
+
+UNKNOWN、API 不可达、repository identity 不符或 listing 不可见均 fail closed。
+
+## 10. Policy as Code
+
+```text
+automatic:
+  build, test, artifact, canary, evidence
+
+owner:
+  signed_release_plan
+
+capabilities:
+  runtime_switch
+  tag_publish
+  baseline_registry_finalize
+
+forbidden:
+  force_push
+  tag_rewrite
+  direct_main_push
+  baseline_mutation
+  registry_mutation
+```
+
+最后两个 forbidden 项指“脱离受治理 finalize controller 的直接 mutation”。
+
+## 11. Security model
+
+- Ed25519 公钥 ring 支持 rotation 和 revoke，私钥不进入 runtime；
+- approval plan 可撤销，过期、未知 key、错误签名均 fail closed；
+- nonce 与 capability operation 持久化，重复相同请求幂等，不同 fingerprint 重放拒绝；
+- Saga snapshot 原子写、journal append-only、CAS 防并发 writer；
+- credential 只通过受控 reference 使用，不进入 Git、API 响应或异常；
+- 子进程环境从空集合构建，不复制 `os.environ`；
+- Shadow 模式默认开启，execution adapter 缺失时不能降级执行；
+- runtime、tag、Baseline/Registry 分属三个能力最小化控制器。
+
+## 12. Migration plan
+
+1. Shadow：生成 candidate、plan、acceptance、approval package，仅比较现有人工结果。
+2. Signed approval：接入 Owner 公钥 ring、撤销源和审计 record；仍不接生产 executor。
+3. Canary execution：使用非生产 service/release root 验证锁、PID、health、崩溃恢复和回滚。
+4. Controlled production switch：另行 Owner 授权启用 execution flag，只开放 runtime capability。
+5. Tag/finalize：分别完成 Gitea 与 Registry/Baseline 生产验收后再启用对应 capability。
+
+每个阶段均可退回上一个阶段；不开启下一能力不会影响已经启用的控制器。
+
+## 13. Rollback plan
+
+- switch 前保存旧 symlink target、PID、启动时间、artifact 与 plan fingerprint；
+- restart 或 health 任一失败进入 `ROLLBACK_PENDING`；
+- 原子恢复旧 target，只 restart 指定 allowlist service；
+- 重新验证旧 runtime commit、writer=false 与 repository identity；
+- 成功进入 `ROLLED_BACK`，失败进入 `MANUAL_OWNER_REVIEW_REQUIRED`；
+- rollback 不修改 Git main、production tag、Baseline 或 Registry；
+- 保留脱敏 journal、approval fingerprint 和失败证据。
+
+## 14. 测试与外部依赖边界
+
+自动测试覆盖签名伪造、字段篡改、过期/revoke/key rotation、nonce replay、CAS race、
+崩溃恢复、artifact/policy/plan mutation、tag conflict、secret leakage、runtime without
+`.git`、rollback 和 shadow no-side-effects。
+
+本隔离实现不创建生产 KMS/key、不安装 systemd unit、不部署 Action runtime、不创建 tag，
+也不修改 Baseline/Registry。上述动作必须在单独生产批准中执行。
@@ -0,0 +1,107 @@
+# AIOS Silent Release Execution Readiness
+
+## Scope and stop point
+
+This change makes the controller execution-ready while deploying only a
+localhost-bound Shadow control plane. Both production gates remain false:
+
+```text
+AIOS_GITOPS_WRITES_ENABLED=false
+AIOS_SILENT_RELEASE_EXECUTION_ENABLED=false
+```
+
+Shadow completion is evidence preparation, not a production release. It cannot
+write a production tag, switch a business runtime, or mutate Baseline/Registry.
+
+## Recovery state machine
+
+Every expired or `FAILED_RECOVERABLE` capability requires fresh, operation-bound
+probe evidence before another adapter may run:
+
+```text
+NOT_APPLIED       -> one new exclusive claim may retry
+APPLIED_VERIFIED  -> mark COMPLETED without adapter replay
+INDETERMINATE     -> RECONCILIATION_REQUIRED; no automatic writes
+CONFLICT          -> MANUAL_OWNER_REVIEW_REQUIRED; no automatic writes
+```
+
+Probe evidence binds the immutable operation digest, is freshness checked, and
+is appended to a separate SHA-256 hash-chained journal. Completion still
+requires the active claim ID. File locks and leases ensure that concurrent
+recovery workers cannot execute the same adapter.
+
+`TAG_PENDING` uses independent remote ref, annotated object, peeled target,
+Gitea API, Gitea listing, and repository identity evidence. Exact absence may
+roll back a switched runtime. Exact publication continues to finalization.
+Unavailable/divergent evidence stops at reconciliation; a different OID or
+target stops for Owner review. No branch can force, delete, or rewrite a tag.
+
+## Trusted build and approval
+
+Callers submit only an event ID and exact source commit. Test, canary, artifact,
+manifest, rollback, secret scan, Git and Gitea evidence are generated by the
+trusted builder. The builder emits an Ed25519 attestation binding:
+
+- builder attestation/key IDs;
+- source commit and tree OID;
+- artifact, manifest and package-closure SHA-256;
+- test and canary evidence SHA-256;
+- issuance time and signature.
+
+The controller contains only trusted public keys. Production signing is exposed
+through a KMS/HSM/secret-manager adapter; a local private-key adapter is marked
+test-only and is used only for ephemeral Shadow acceptance.
+
+Owner approvals are immutable, time-bounded, revocable, trust-domain bound, and
+single-use per capability ledger. If the production approval backend reference
+is absent, production execution is unavailable while Shadow remains available.
+Caller-supplied `owner_id` is never a fallback.
+
+## Persistent controller and API
+
+`aios-silent-release-controller.service` runs independently from the business
+GitOps API. It uses a single leader lock, durable intents/candidates/Sagas,
+startup journal verification, idempotent main events, one notification record,
+and recovery reporting. The final deployed service is report-only Shadow mode.
+
+The Action contract exposes:
+
+- `createReleaseIntent`
+- `getReleaseCandidate`
+- `getReleasePlan`
+- `getReleaseAcceptance`
+- `submitSignedApproval`
+- `getReleaseSaga`
+- `getCapabilityStatus`
+- `startDeployment`
+- `getRecoveryStatus`
+
+Every Shadow response declares `execution_enabled=false`, `shadow_mode=true`
+and `side_effects_executed=false`. `startDeployment` returns a simulated
+`SHADOW_COMPLETED` result and never claims production capabilities.
+
+## Migration and rollback
+
+1. Merge through a governed pull request.
+2. Build from a clean detached worktree at the exact merge commit.
+3. Verify artifact, manifest, package closure, tests, live fixture, no-.git
+   canary, rollback archive and secret scan.
+4. Install a versioned Shadow release without changing the business runtime.
+5. Start the separate localhost-only controller with both gates false.
+6. Run Shadow candidates and freeze production PID/tag/Baseline/Registry hashes.
+7. Remove ephemeral test keys and temporary repositories.
+
+Rollback stops and disables only the Shadow controller and restores/removes its
+versioned `current` link. The existing production API, tag set, Baseline and
+Registry are not involved.
+
+## Future activation envelope
+
+Activation requires a new one-time Owner approval binding the exact controller
+commit, artifact/manifest/policy/unit hashes, trusted key IDs, KMS/secret
+references, release and rollback roots, authoritative Git/repository identity,
+Shadow candidate/evidence IDs, test results, activation plan and rollback plan.
+That approval may only flip
+`AIOS_SILENT_RELEASE_EXECUTION_ENABLED=false` to `true`; each real release still
+requires its own signed ReleasePlan. This change does not request or consume
+that activation approval.
@@ -0,0 +1,84 @@
+# Silent Release Controller Production Contract
+
+Status: review-only implementation. Production execution remains disabled.
+
+## Trust boundary
+
+The caller submits only release intent. A configured trusted builder owns ref
+validation, build, tests, artifact and manifest hashing, package closure,
+canary, rollback readiness, Git/Gitea consistency, and secret scanning. Caller
+supplied success evidence is rejected.
+
+The resulting immutable `ReleasePlan` contains deployment, tag, and
+finalization plans. One Ed25519 owner signature binds its SHA-256 digest,
+candidate evidence, policy digest, owner identity, trust domain, validity
+window, evidence lineage, and three narrow capabilities.
+
+## Durable execution
+
+The Saga journal is the source of truth. Every record is sequence-numbered and
+SHA-256 hash-chained from a fixed genesis hash. Snapshots are rebuildable
+caches. Journal corruption, truncation, reordering, missing records, or hash
+mismatch moves the release to `MANUAL_OWNER_REVIEW_REQUIRED`.
+
+Capability execution uses an exclusive, leased claim. A second worker receives
+`BUSY`; an expired claim is not reassigned until a capability-specific
+side-effect probe reports that the operation was not applied. Runtime, tag,
+and finalization remain separately claimed and recoverable.
+
+## Execution order
+
+```text
+APPROVED
+  -> PRE_SWITCH_REVALIDATING
+  -> SWITCH_PENDING
+  -> SWITCHED
+  -> RUNTIME_VERIFYING
+  -> RUNTIME_VERIFIED
+  -> TAG_PENDING
+  -> TAG_VERIFIED
+  -> BASELINE_REGISTRY_PENDING
+  -> COMPLETED
+```
+
+The actual adapter configuration is regenerated before execution and must
+match the signed plan. Trusted allowlists come from controlled policy, not the
+request.
+
+A failure before verified tag publication rolls the runtime back. A failure
+after the exact tag is verified enters `RECONCILIATION_REQUIRED`; the tag is
+never deleted or rewritten. A same-name/different-OID conflict enters
+`MANUAL_OWNER_REVIEW_REQUIRED`. Registry/Baseline finalization requires exact
+remote and Gitea tag proof, and Baseline is recorded last.
+
+## Action and recovery contract
+
+`submitOwnerApproval` verifies and durably stores the signed plan, then moves
+the Saga to `APPROVED`. `startDeployment` loads that durable approval and
+ignores caller-supplied approval content. Enabling execution without the
+trusted builder, verifier, validator, policy, and orchestrator fails during
+service construction.
+
+The recovery worker scans incomplete journals and resumes through the same
+claims and verification gates. It never automatically resumes a manual-review
+Saga. In shadow mode it only reports state and performs no adapter side
+effects.
+
+The deployed Action factory does not enable the legacy caller-evidence path.
+If the trusted builder is absent, candidate creation is rejected even while
+execution remains in shadow mode. The compatibility path exists only through
+the explicit test-only `SilentReleaseActionService.shadow()` constructor.
+
+Finalization is composed from separate `RegistryController` and
+`BaselineController` claims. Registry is verified first and Baseline is the
+last mutation; a retry reuses completed Registry evidence and never moves
+Baseline ahead of tag verification.
+
+## Governance
+
+- `force_push`: forbidden
+- `tag_rewrite`: forbidden
+- `direct_main_push`: forbidden
+- production execution default: disabled
+- production tag operations in this change: not executed
+- Baseline/Registry mutations in this change: not executed
@@ -0,0 +1,68 @@
+# Gitea Tag Publication Atomicity
+
+Release publication is a fail-closed Saga bound to one immutable governance
+fingerprint:
+
+- `version`
+- `target_oid`
+- `evidence_closure_oid`
+- `approval_plan_id`
+
+The normal progression is:
+
+`PENDING` → `LOCAL_TAG_CREATED` → `REMOTE_PUSH_CONFIRMED` →
+`GITEA_API_CONFIRMED` → `BASELINE_UPDATE_PENDING` → `BASELINE_UPDATED` →
+`PRODUCTION_DEPLOYED`
+
+An unavailable remote uses `REMOTE_PUSH_PENDING` or
+`RECONCILIATION_REQUIRED`. A same-name tag object mismatch, peeled-target
+mismatch, changed governance fingerprint, or immutable deployment-evidence
+conflict enters `MANUAL_OWNER_REVIEW_REQUIRED`. That state blocks automatic
+push and reconciliation; recovery never deletes, rewrites, or force-pushes a
+tag.
+
+## Legacy state migration
+
+Readers normalize the historical `TAG_CREATED_LOCAL` value to
+`LOCAL_TAG_CREATED` in memory. Read-only status responses therefore expose only
+the canonical value. The next governed Saga write persists the canonical name;
+reading legacy state alone does not mutate the tag, Baseline, Registry, or Saga
+file. Any unrecognized persisted state fails closed as
+`RECONCILIATION_REQUIRED`.
+
+`BASELINE_UPDATE_PENDING` is persisted before either `baseline/current.json` or
+`versions/<version>.json` changes. Recovery revalidates the governance
+fingerprint, evidence lineage, remote annotated tag, peeled target, Gitea API,
+listing, and repository identity before idempotently completing matching
+partial records. A different tag or target enters
+`MANUAL_OWNER_REVIEW_REQUIRED`.
+
+## Durable state
+
+Production writers set `AIOS_GITOPS_PUBLICATION_STATE_DIR` to storage outside
+their disposable worktree. Recreating a writer must reuse that directory.
+Worktree JSON is not the authoritative Saga store.
+
+## Deployment gate
+
+`mark_production_deployed` performs fresh Git remote, peeled-target, Gitea ref,
+Gitea tag-object, listing, repository-identity, evidence-lineage, Registry, and
+Baseline checks. Deployment is allowed only when:
+
+`Registry = Baseline = remote tag = Gitea API = expected target`
+
+Deployment evidence must be an immutable `sha256:<64 hex>` or `git:<40 hex>`
+identifier.
+
+## Read-only acceptance
+
+- `getTagPublicationStatus` reads durable Saga state.
+- `getReleaseConsistency` compares every release authority.
+- `runReleaseAcceptance` returns `accepted: true` only for `PASS`.
+
+Unavailable evidence returns `UNKNOWN` with `fail_closed: true`; it is never
+treated as acceptance.
+
+The CLI, HTTP Action, and release script all enter the same publisher core for
+evidence-lineage verification. The release script stages Registry and Baseline
+records only; durable Saga state remains outside Git.
@@ -0,0 +1,68 @@
+# Isolated Writer Exact-Path Policy V1
+
+This policy is an additional, service-owned authorization layer for
+`POST /api/commit-file`. It never expands a Token Policy V2 grant.
+
+An atomic write is permitted only when all of the following agree:
+
+1. socket peer, audience, operation, branch, base and exact path in the
+   Token Policy V2 grant;
+2. service audience, repository identity, branch, operation and exact path
+   in `AIOS_GITOPS_PATH_POLICY_FILE`;
+3. lexical path, resolved containment and symlink checks;
+4. the configured content-size and content-profile checks;
+5. operation digest, expected branch HEAD and durable operation ledger.
+
+Any failed layer returns a fail-closed policy error. Coarse `/api/file` and
+`/api/commit` routes remain forbidden.
+
+## File contract
+
+The configured path must be absolute. The parent directory must be
+`root:gitops 0750`; the regular, non-symlink file must be
+`root:gitops 0640`. JSON must use UTF-8 canonical encoding with sorted keys,
+compact separators and one trailing newline. Unknown fields, unsupported
+operations or profiles, duplicate paths, oversized policies and
+group/world-writable files are rejected during Writer startup.
+
+Example:
+
+```json
+{"allowed_branch":"patch/codex-review-test-worker-20260724","allowed_operations":{"commit_file.atomic":{"content_profile":"systemd-codex-review-worker-v1","exact_paths":["deploy/systemd/aios-codex-review-test-worker.service"],"max_content_bytes":32768}},"audience":"aios-codex-review-worker-writer.service","policy_id":"codex-review-worker-path-policy-v1","repository_identity":"aios/aios","schema_version":1}
+```
+
+The SHA-256 of the canonical policy is exposed in the isolated runtime
+status and written to the operation audit record. The request body cannot
+select or override the policy file.
+
+## Content profile
+
+`systemd-codex-review-worker-v1` is an exact, fail-closed unit grammar. The
+only sections are `[Unit]`, `[Service]` and `[Install]`. Each section has a
+directive allowlist; every single-value directive and every repeated
+`Environment`, `ReadOnlyPaths` and `ReadWritePaths` entry must match the
+governed Shadow unit contract exactly.
+
+The profile fixes the Python module
+`task_plane.workers.codex_review_test`, `User=aiman`, `Group=gitops`,
+the controlled `/usr/libexec/aios-codex-review-test-worker/current`
+working directory, all hardening switches and the three permitted
+environment variables. It grants read access only to the authoritative
+bare repository and the versioned worker artifact, and write access only
+to the worker runtime, state and cache directories.
+
+Unknown sections or directives are rejected, including lifecycle hooks,
+credential injection, environment imports, root images, bind mounts,
+capability expansion, devices, sockets and top-level writable paths. The
+parser also rejects duplicate sections, duplicate single-value directives,
+empty resets, continuation lines, CRLF, NUL, non-UTF-8 surrogate content,
+overlong lines and Unicode lookalike directive names. It does not use
+`ConfigParser(strict=False)` or silently merge repeated values.
+
+Production credentials, if later authorized, must be supplied by a
+separately governed deployment drop-in. They are not permitted in the
+source unit or this content profile.
+
+Policy changes require a separate maintenance branch and Owner-reviewed
+ordinary merge commit. A task-scoped Writer must not edit its own policy
+file.
@@ -13,6 +13,27 @@ components:
      scheme: bearer
      bearerFormat: opaque-token
  schemas:
+    PublicationState:
+      type: string
+      description: Canonical durable publication state. Legacy TAG_CREATED_LOCAL is normalized on read and is never emitted by new writes.
+      enum:
+        - PENDING
+        - LOCAL_TAG_CREATED
+        - REMOTE_PUSH_PENDING
+        - REMOTE_PUSH_CONFIRMED
+        - GITEA_API_CONFIRMED
+        - BASELINE_UPDATE_PENDING
+        - BASELINE_UPDATED
+        - PRODUCTION_DEPLOYED
+        - RECONCILIATION_REQUIRED
+        - MANUAL_OWNER_REVIEW_REQUIRED
+    PublicationStatus:
+      type: object
+      required: [version, state]
+      properties:
+        version: {type: string}
+        state: {$ref: '#/components/schemas/PublicationState'}
+        fail_closed: {type: boolean}
    BranchRequest:
      type: object
      required: [branch]
@@ -30,6 +51,31 @@ components:
        path: {type: string, example: docs/gitops/chatgpt-change.md}
        content: {type: string}
        message: {type: string}
+    AtomicFileCommitRequest:
+      type: object
+      additionalProperties: false
+      required: [branch, path, content, message, expected_head_oid, idempotency_key]
+      properties:
+        branch:
+          type: string
+          pattern: '^patch/[A-Za-z0-9._/-]+$'
+        path:
+          type: string
+          minLength: 1
+          maxLength: 512
+        content:
+          type: string
+          maxLength: 1048576
+        message:
+          type: string
+          minLength: 1
+          maxLength: 200
+        expected_head_oid:
+          type: string
+          pattern: '^[0-9a-f]{40}$'
+        idempotency_key:
+          type: string
+          pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$'
    CommitRequest:
      type: object
      properties:
@@ -50,9 +96,20 @@ components:
        message: {type: string}
    TagRequest:
      type: object
-      required: [version]
+      required: [version, target_oid, evidence_closure_oid, approval_plan_id]
      properties:
        version: {type: string, example: V1R1C1}
+        target_oid:
+          type: string
+          pattern: '^[0-9a-fA-F]{40}$'
+          description: Full approved commit OID. The tag is created explicitly at this commit, never implicitly at workspace HEAD.
+        evidence_closure_oid:
+          type: string
+          pattern: '^[0-9a-fA-F]{40}$'
+          description: Required evidence closure commit. target_oid must be its ancestor.
+        approval_plan_id:
+          type: string
+          description: Audited owner-approved release or tag plan identifier.
        message: {type: string}
        execute:
          type: boolean
@@ -103,7 +160,216 @@ components:
      properties:
        text: {type: string}
        branch: {type: string}
+    DeploymentPlan:
+      type: object
+      required: [service, release_path, release_root, cutover_link, dropin_path, dropin_sha256, systemd_unit_sha256, rollback_path, rollback_sha256, source_commit, tree_oid, artifact_sha256, manifest_sha256, package_closure_sha256, authoritative_git_dir, repository_identity, writer_expected, baseline_before_sha256, registry_before_sha256, production_tag_refset_before_sha256, health_contract_version, timeout_policy, retry_policy, policy_sha256, health_contract]
+      properties:
+        service: {type: string}
+        release_path: {type: string}
+        release_root: {type: string}
+        cutover_link: {type: string}
+        dropin_path: {type: string}
+        dropin_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        systemd_unit_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        rollback_path: {type: string}
+        rollback_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
+        tree_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
+        artifact_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        manifest_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        package_closure_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        authoritative_git_dir: {type: string}
+        repository_identity: {type: string}
+        writer_expected: {type: boolean, enum: [false]}
+        baseline_before_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        registry_before_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        production_tag_refset_before_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        health_contract_version: {type: string}
+        timeout_policy: {type: object}
+        retry_policy: {type: object}
+        policy_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        health_contract: {type: object, additionalProperties: true}
+    ReleaseCandidateInput:
+      type: object
+      required: [source_commit, version]
+      additionalProperties: false
+      properties:
+        candidate_id: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.-]{2,127}$'}
+        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
+        version: {type: string, pattern: '^V[0-9]+R[0-9]+C[0-9]+(?:[-.][A-Za-z0-9][A-Za-z0-9.-]*)?$'}
+    ReleaseIntentInput:
+      type: object
+      required: [event_id, source_commit]
+      additionalProperties: false
+      properties:
+        event_id: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{2,255}$'}
+        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
+    SignedReleasePlanApproval:
+      type: object
+      required: [release_plan_id, candidate_id, source_commit, tree_oid, artifact_sha256, manifest_sha256, deployment_plan_sha256, release_plan_sha256, policy_sha256, approval_plan_id, evidence_closure_oid, owner_approval_record_oid, capabilities, owner_identity, trust_domain, issued_at, not_before, expires_at, nonce, key_id, signature]
+      properties:
+        release_plan_id: {type: string}
+        candidate_id: {type: string}
+        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
+        tree_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
+        artifact_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        manifest_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        deployment_plan_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        release_plan_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        policy_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
+        approval_plan_id: {type: string}
+        evidence_closure_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
+        owner_approval_record_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
+        owner_identity: {type: string}
+        trust_domain: {type: string}
+        issued_at: {type: string, format: date-time}
+        not_before: {type: string, format: date-time}
+        capabilities:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+            enum: [runtime_switch, tag_publish, baseline_registry_finalize]
+        expires_at: {type: string, format: date-time}
+        nonce: {type: string, minLength: 16}
+        key_id: {type: string}
+        signature: {type: string, format: byte, writeOnly: true}
+    StartDeploymentRequest:
+      type: object
+      required: [candidate_id]
+      additionalProperties: false
+      properties:
+        candidate_id: {type: string}
 paths:
+  /createReleaseIntent:
+    post:
+      operationId: createReleaseIntent
+      summary: Create an idempotent intent; all build evidence comes from the trusted builder
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ReleaseIntentInput'}
+      responses:
+        '200': {description: Intent created or idempotently returned}
+        '400': {description: Caller evidence or invalid intent rejected}
+      x-openai-isConsequential: true
+  /createReleaseCandidate:
+    post:
+      operationId: createReleaseCandidate
+      summary: Submit release intent to the trusted builder; caller evidence is rejected
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ReleaseCandidateInput'}
+      responses:
+        '200': {description: Candidate created or idempotently returned}
+        '400': {description: Invalid or conflicting candidate evidence}
+        '401': {description: Unauthorized}
+      x-openai-isConsequential: true
+  /getReleaseCandidate:
+    get:
+      operationId: getReleaseCandidate
+      summary: Read a durable release candidate
+      parameters:
+        - {in: query, name: candidate_id, required: true, schema: {type: string}}
+      responses:
+        '200': {description: Candidate}
+        '404': {description: Candidate not found}
+  /getReleasePlan:
+    get:
+      operationId: getReleasePlan
+      parameters:
+        - {in: query, name: candidate_id, required: true, schema: {type: string}}
+      responses:
+        '200': {description: Immutable release plan}
+        '404': {description: Candidate not found}
+  /getReleaseAcceptance:
+    get:
+      operationId: getReleaseAcceptance
+      parameters:
+        - {in: query, name: candidate_id, required: true, schema: {type: string}}
+      responses:
+        '200': {description: Builder attestation and acceptance checks}
+        '404': {description: Candidate not found}
+  /getApprovalEnvelope:
+    get:
+      operationId: getApprovalEnvelope
+      summary: Generate the immutable owner-signature payload
+      parameters:
+        - {in: query, name: candidate_id, required: true, schema: {type: string}}
+      responses:
+        '200': {description: Approval envelope fingerprint inputs}
+        '404': {description: Candidate not found}
+  /submitOwnerApproval:
+    post:
+      operationId: submitOwnerApproval
+      summary: Verify and durably store a signed owner release plan
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/SignedReleasePlanApproval'}
+      responses:
+        '200': {description: Signature verified and approval stored}
+        '400': {description: Invalid approval}
+        '403': {description: Signature, key, expiry, or revocation failure}
+        '409': {description: Conflicting release plan}
+      x-openai-isConsequential: true
+  /submitSignedApproval:
+    post:
+      operationId: submitSignedApproval
+      summary: Alias for immutable signed owner approval submission
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/SignedReleasePlanApproval'}
+      responses:
+        '200': {description: Signature verified and approval stored}
+        '403': {description: Production approval backend unavailable or signature invalid}
+      x-openai-isConsequential: true
+  /startDeployment:
+    post:
+      operationId: startDeployment
+      summary: Resume the durable approved Saga; caller cannot replace approval
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/StartDeploymentRequest'}
+      responses:
+        '200': {description: Shadow result or deployment Saga result}
+        '403': {description: Execution disabled or approval invalid}
+        '409': {description: Saga conflict}
+      x-openai-isConsequential: true
+  /getReleaseSaga:
+    get:
+      operationId: getReleaseSaga
+      summary: Read durable Saga state and event journal
+      parameters:
+        - {in: query, name: candidate_id, required: true, schema: {type: string}}
+      responses:
+        '200': {description: Saga snapshot}
+        '404': {description: Saga not found}
+  /getCapabilityStatus:
+    get:
+      operationId: getCapabilityStatus
+      parameters:
+        - {in: query, name: candidate_id, required: true, schema: {type: string}}
+      responses:
+        '200': {description: Durable single-use capability records}
+  /getRecoveryStatus:
+    get:
+      operationId: getRecoveryStatus
+      responses:
+        '200': {description: Fail-closed recovery classification}
  /api/base:
    get:
      operationId: getBaseline
@@ -187,6 +453,25 @@ paths:
            schema: {$ref: '#/components/schemas/FileCommitRequest'}
      responses: {'200': {description: File committed}, '400': {description: Secret rejected or invalid path}, '401': {description: Unauthorized}}
      x-openai-isConsequential: true
+  /api/commit-file:
+    post:
+      operationId: commitFileAtomic
+      summary: Atomically write one allowlisted file, commit, push, and verify using Token Policy V2
+      security: [{bearerAuth: []}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AtomicFileCommitRequest'}
+      responses:
+        '200': {description: Completed or idempotently replayed}
+        '400': {description: Invalid canonical request}
+        '401': {description: Missing, invalid, expired, or revoked Token Policy V2 grant}
+        '403': {description: Audience, source, branch, operation, path, or policy denied}
+        '409': {description: Idempotency conflict or manual review required}
+        '413': {description: Request too large}
+        '503': {description: Push or remote verification unavailable; recoverable}
+      x-openai-isConsequential: true
  /api/commit:
    post:
      operationId: commitChanges
@@ -199,6 +484,39 @@ paths:
            schema: {$ref: '#/components/schemas/CommitRequest'}
      responses: {'200': {description: Commit result}, '401': {description: Unauthorized}}
      x-openai-isConsequential: true
+  /api/tag-publication-status:
+    get:
+      operationId: getTagPublicationStatus
+      summary: Read durable publication Saga status without mutation
+      parameters:
+        - {in: query, name: version, required: true, schema: {type: string, pattern: '^V\d+R\d+C\d+(?:-[A-Za-z0-9_.-]+)?$'}}
+      responses:
+        '200':
+          description: Canonical publication state or fail-closed UNKNOWN
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/PublicationStatus'}
+        '400': {description: Version required}
+  /api/release-consistency:
+    get:
+      operationId: getReleaseConsistency
+      summary: Compare Registry, Baseline, remote tag, Gitea API, listing, repository identity, and expected target
+      parameters:
+        - {in: query, name: version, required: true, schema: {type: string}}
+        - {in: query, name: target_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
+        - {in: query, name: evidence_closure_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
+        - {in: query, name: approval_plan_id, required: true, schema: {type: string}}
+      responses: {'200': {description: PASS, FAIL, or fail-closed UNKNOWN}}
+  /api/release-acceptance:
+    get:
+      operationId: runReleaseAcceptance
+      summary: Run read-only release acceptance; UNKNOWN is not accepted
+      parameters:
+        - {in: query, name: version, required: true, schema: {type: string}}
+        - {in: query, name: target_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
+        - {in: query, name: evidence_closure_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
+        - {in: query, name: approval_plan_id, required: true, schema: {type: string}}
+      responses: {'200': {description: Acceptance result with accepted boolean}}
  /api/tag:
    post:
      operationId: requestOrCreateTag
@@ -209,7 +527,7 @@ paths:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/TagRequest'}
-      responses: {'200': {description: Tag request committed or tag created}, '403': {description: Forbidden}}
+      responses: {'200': {description: Gitea-confirmed tag and fail-closed baseline result}, '400': {description: Missing governance evidence or invalid OID}, '403': {description: Forbidden}, '409': {description: Existing tag target conflict or evidence lineage mismatch}, '502': {description: Gitea reconciliation required}, '503': {description: Remote push pending}}
      x-openai-isConsequential: true
  /api/rollback:
    post:
@@ -245,4 +563,7 @@ paths:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/NLRequest'}
-      responses: {'
+      responses:
+        '200': {description: Safe GitOps plan}
+        '401': {description: Unauthorized}
+      x-openai-isConsequential: true
--- a/Show More
+++ b/Show More