feat(codex): add trusted remote Codex brain runner

.agent/dispatch/V2R1-PERSONAL-WEIXIN-IMMEDIATE-WORK-UNITS.json

@@ -0,0 +1,76 @@
+{
+  "contract_commit": "cbe33ecab8e9794ba5f318bea43aeaf447a56fbc",
+  "created_at": "2026-07-18T04:58:00+00:00",
+  "schema_version": 2,
+  "state_writer": "gateway",
+  "work_units": [
+    {
+      "id": "R0-DISCOVER-SECRET-PROVIDER",
+      "track": "R_RUNNER",
+      "gate": "R0_RUNNER_LIVE_RECOVERY",
+      "primary": "openclaw",
+      "fallback": "codex",
+      "status": "READY",
+      "quorum": "requires_gpt_plus_one_executor"
+    },
+    {
+      "id": "P2-INVENTORY-REAL-EVIDENCE",
+      "track": "P_PERSONAL_WEIXIN",
+      "gate": "P2_REAL_B3_EVIDENCE",
+      "primary": "openclaw",
+      "fallback": "codex",
+      "status": "READY",
+      "quorum": "requires_gpt_plus_one_executor"
+    },
+    {
+      "id": "P1-POST-CONTRACT-REACK",
+      "track": "P_PERSONAL_WEIXIN",
+      "gate": "P1_REPAIR3_CODE",
+      "primary": "codex",
+      "fallback": "openclaw",
+      "status": "READY",
+      "quorum": "requires_gpt_plus_one_executor"
+    },
+    {
+      "id": "Q0-GPT-HEALTH-INIT",
+      "track": "_QUORUM",
+      "gate": "Q0_GPT_AND_EXECUTOR_HEALTH",
+      "primary": "gateway",
+      "fallback": null,
+      "status": "READY",
+      "quorum": "gateway_initiated"
+    },
+    {
+      "id": "Q1-ACTIVE-EXECUTOR-ELECTION",
+      "track": "_QUORUM",
+      "gate": "Q1_ELECT_ACTIVE_EXECUTOR",
+      "primary": "gateway",
+      "fallback": null,
+      "status": "PENDING",
+      "depends_on": "Q0-GPT-HEALTH-INIT",
+      "quorum": "gateway_initiated"
+    },
+    {
+      "id": "Q2-FAILOVER-HEALTHCHECK",
+      "track": "_QUORUM",
+      "gate": "Q2_STANDBY_HEALTH_MONITOR",
+      "primary": "gateway",
+      "fallback": null,
+      "status": "PENDING",
+      "depends_on": "Q1-ACTIVE-EXECUTOR-ELECTION",
+      "quorum": "log_only_if_active_ok"
+    },
+    {
+      "id": "Q3-UNATTENDED-ACCEPTANCE-MATRIX",
+      "track": "_QUORUM",
+      "gate": "A0_AUTOMATION_CLOSED",
+      "primary": "gateway",
+      "fallback": null,
+      "status": "PENDING_LIVE_EVIDENCE",
+      "depends_on": "Q2-FAILOVER-HEALTHCHECK",
+      "quorum": "requires_gpt_plus_one_executor",
+      "required_scenarios": 16,
+      "may_mark_pass_without_live_evidence": false
+    }
+  ]
+}

.agent/policies/V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT.yaml

@@ -0,0 +1,248 @@
+{
+  "adaptive_dispatch": {
+    "codex_first": [
+      "complex_code",
+      "security_boundary",
+      "architecture",
+      "high_risk_review",
+      "strong_model_materially_better"
+    ],
+    "default_orchestrator": "openclaw",
+    "dynamic_executor_selection": {
+      "large_repetitive_infrastructure_monitoring": "openclaw",
+      "complex_code_security_architecture": "codex",
+      "both_healthy_active": "assign_by_preference",
+      "one_healthy_active": "use_healthy_only",
+      "both_unhealthy_blocked": true
+    },
+    "max_attempts_per_work_unit": 2,
+    "on_timeout": [
+      "mark_TIMEOUT",
+      "preserve_logs",
+      "switch_agent"
+    ],
+    "openclaw_first": [
+      "quality_close",
+      "large_or_repetitive",
+      "long_running",
+      "infra_or_git_inventory",
+      "cost_sensitive"
+    ],
+    "single_state_writer_lease_required": true,
+    "strict_role_partition": false,
+    "state_writer": "gateway",
+    "timeout_can_pass": false
+  },
+  "authoritative_state": {
+    "b3": "BLOCKED_EVIDENCE_REQUIRED",
+    "b4": "NOT_STARTED",
+    "baseline": "V1R4C6",
+    "production_release": "NOT_STARTED",
+    "release": "paused",
+    "repair3": {
+      "base": "8d9c6da90fc8caa69b691d243c6fefb40b6b0575",
+      "candidate": "PASS_CANDIDATE_PREPARED",
+      "commit": "e110cda9968cadc5c7b7179ec5003b05aad11ce4",
+      "exact4": "PASS",
+      "result": "49a9c2e0cc898ecf2bbd45f454e007644d7f3045"
+    },
+    "runner": {
+      "artifact_sha256": "85c472c05a1e55a5899b215d3cd41df53912787de529ac9cb3d5308da4158130",
+      "commit": "bbd27cf06acf1f589eef291eab54d4b127aa3aea",
+      "live": "BLOCKED_GATEWAY_SECRET_REF_UNAVAILABLE",
+      "offline": "PASS",
+      "result": "e789632e359e9232d8ae081e7c4f23ed7b615a9d"
+    }
+  },
+  "central_gpt": {
+    "required": "HEALTHY",
+    "health_definition": {
+      "live_probe_required": true,
+      "workspace_agent_validated_live_or_responses_validated_live": true,
+      "configuration_or_credential_presence_is_insufficient": true,
+      "unknown_is_not_healthy": true
+    },
+    "independent_review": {
+      "single_executor_mode": true,
+      "required_evidence": [
+        "committed_git_tree",
+        "full_commit_oid",
+        "test_logs_with_rc",
+        "gitleaks",
+        "artifact_digest",
+        "worktree_bare_gitea_oid",
+        "live_runtime_evidence"
+      ],
+      "model_judgment_insufficient": true
+    }
+  },
+  "contract_id": "V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT",
+  "executor_quorum": {
+    "minimum_healthy": 1,
+    "candidates": [
+      "openclaw",
+      "codex"
+    ],
+    "quorum_pass": [
+      "GPT_HEALTHY_AND_OPENCLAW_HEALTHY",
+      "GPT_HEALTHY_AND_CODEX_HEALTHY"
+    ],
+    "quorum_block": [
+      "GPT_UNHEALTHY",
+      "GPT_HEALTHY_BUT_BOTH_EXECUTORS_UNAVAILABLE",
+      "GPT_OR_SOLE_EXECUTOR_UNKNOWN"
+    ]
+  },
+  "automation_closed_success_conditions": [
+    "CENTRAL_GPT_HEALTH=PASS",
+    "EXECUTOR_QUORUM=PASS",
+    "ACTIVE_EXECUTOR=openclaw|codex",
+    "EVENT_TRIGGER=PASS",
+    "POLLING=PASS",
+    "FAILOVER=PASS",
+    "LIFECYCLE_SYNC=PASS",
+    "TWO_CYCLE_UNATTENDED_LOOP=PASS",
+    "RESTART_RECOVERY=PASS",
+    "AUTOMATION_CLOSED=PASS"
+  ],
+  "gateway_lifecycle_events": [
+    "TASK_DISPATCHED",
+    "TASK_STARTED",
+    "TASK_ENDED",
+    "DECISION_APPLIED",
+    "PROJECT_SUMMARY",
+    "PROJECT_COMPLETED"
+  ],
+  "facts_policy": {
+    "accept": [
+      "committed_git_tree",
+      "full_oid",
+      "worktree_bare_gitea_oid_match",
+      "test_log_with_rc",
+      "immutable_digest",
+      "result_only_commit",
+      "live_evidence"
+    ],
+    "reject": [
+      "verbal_claim",
+      "readme_only",
+      "local_only_commit",
+      "environment_variable_as_secret_ref",
+      "compile_only",
+      "timeout_as_pass",
+      "unrelated_repo",
+      "fabricated_evidence"
+    ]
+  },
+  "forbidden_git": [
+    "reset",
+    "amend",
+    "rebase",
+    "force_push",
+    "direct_main_push",
+    "direct_bare_ref_mutation",
+    "unapproved_gitea_db_mutation",
+    "reuse_accident_worktree",
+    "delete_live_worktree_to_clear_collision"
+  ],
+  "generated_at": "2026-07-18T04:58:00+00:00",
+  "handoff": {
+    "ack": "CONTRACT_ACK=<full_contract_commit_oid>",
+    "advance": "independent_verification_required",
+    "all_agents_match": true
+  },
+  "join_gate": {
+    "requires": [
+      "AUTOMATION_CLOSED",
+      "RUNNER_RECOVERED",
+      "B3_PASS",
+      "B4_PASS",
+      "INTEGRATION_PASS"
+    ]
+  },
+  "model_policy": {
+    "codex": "strongest_model_actually_available_in_runtime",
+    "gpt_5_6": "use_only_if_exposed",
+    "no_unverified_model_claims": true,
+    "openclaw_default": "DeepSeek V4 Flash"
+  },
+  "owner_authorization": {
+    "adaptive_agent_assignment_authorized": true,
+    "agent_substitution_authorized": true,
+    "autonomous_execution": true,
+    "may_bypass_release_controls": false,
+    "may_bypass_secret_controls": false,
+    "may_fabricate_evidence": false,
+    "user_step_by_step_confirmation_required": false
+  },
+  "release_gates": [
+    "AUTOMATION_CLOSED",
+    "MAIN_MERGE",
+    "STAGING_AND_CANARY",
+    "PRODUCTION"
+  ],
+  "schema_version": 4,
+  "self_healing": {
+    "priorities": {
+      "p0": "central_gpt_failure",
+      "p1": "both_executors_unavailable",
+      "p2": "active_executor_failed_with_healthy_standby",
+      "p3": "standby_executor_alone_failed"
+    },
+    "rules": {
+      "standby_failure_when_active_ok": {
+        "action": "log_only",
+        "block_business": false,
+        "create_blocking_gate": false,
+        "pause_release": false
+      },
+      "active_executor_failure": {
+        "action": "failover_to_standby",
+        "inherit_contract_commit": true,
+        "inherit_event_id": true,
+        "inherit_state_version": true,
+        "mark_original_task": "INTERRUPTED_AGENT_FAILOVER",
+        "new_executor_continues_from_checkpoint": true,
+        "block_duplicate_side_effects": true
+      },
+      "both_unavailable_block": "BLOCKED_NO_HEALTHY_EXECUTOR"
+    }
+  },
+  "state_rules": [
+    "tracks_run_parallel",
+    "runner_block_does_not_block_offline_work_or_evidence_inventory",
+    "join_requires_both_tracks",
+    "failure_stops_dependents",
+    "production_remains_V1R4C6_paused_until_production_pass",
+    "gateway_persists_authoritative_state",
+    "lifecycle_events_persisted_regardless_of_openclaw_online"
+  ],
+  "status": "ACTIVE",
+  "tracks": {
+    "P_PERSONAL_WEIXIN": {
+      "b3": "BLOCKED_EVIDENCE_REQUIRED",
+      "b4": "NOT_STARTED",
+      "parallel": true,
+      "repair3": "PASS_CANDIDATE_PREPARED",
+      "repair3_commit": "e110cda9968cadc5c7b7179ec5003b05aad11ce4"
+    },
+    "R_RUNNER": {
+      "commit": "bbd27cf06acf1f589eef291eab54d4b127aa3aea",
+      "current": "BLOCKED_GATEWAY_SECRET_REF_UNAVAILABLE",
+      "fallback": "codex",
+      "parallel": true,
+      "primary": "openclaw",
+      "required": [
+        "artifact_verified",
+        "approved_secret_provider_contract",
+        "owner_probe_verified",
+        "service_healthy",
+        "heartbeat_healthy",
+        "gateway_auth",
+        "durable_task_create_read_cancel",
+        "execution_channel",
+        "live_rollback"
+      ]
+    }
+  }
+}

.agent/state/V2R1-PERSONAL-WEIXIN-PRODUCTION-STATE.json

@@ -0,0 +1,44 @@
+{
+  "b3": "BLOCKED_EVIDENCE_REQUIRED",
+  "b4": "NOT_STARTED",
+  "baseline": "V1R4C6",
+  "contract_branch": "task/governance/v2r1-personal-weixin-production-contract-20260717",
+  "contract_commit": "cbe33ecab8e9794ba5f318bea43aeaf447a56fbc",
+  "dispatch_commit": null,
+  "executor_quorum": {
+    "candidates": ["openclaw", "codex"],
+    "minimum_healthy": 1,
+    "openclaw": "UNKNOWN",
+    "codex": "UNKNOWN"
+  },
+  "active_executor": null,
+  "standby_executor": null,
+  "central_gpt": "UNKNOWN",
+  "automation_closed": {
+    "central_gpt_health": "UNKNOWN",
+    "executor_quorum": "UNKNOWN",
+    "active_executor": null,
+    "event_trigger": "UNKNOWN",
+    "polling": "UNKNOWN",
+    "failover": "UNKNOWN",
+    "lifecycle_sync": "UNKNOWN",
+    "two_cycle_unattended_loop": "UNKNOWN",
+    "restart_recovery": "UNKNOWN",
+    "result": "NOT_STARTED"
+  },
+  "lifecycle_events": [],
+  "production_release": "NOT_STARTED",
+  "release": "paused",
+  "repair3": "PASS_CANDIDATE_PREPARED",
+  "runner": "BLOCKED_GATEWAY_SECRET_REF_UNAVAILABLE",
+  "schema_version": 2,
+  "single_state_writer": "gateway",
+  "single_state_writer_lease_required": true,
+  "quorum_controller": {
+    "implementation": "CODE_COMMITTED_TESTED_PENDING_LIVE_ACCEPTANCE",
+    "live_acceptance": "NOT_STARTED",
+    "health_source": "ROOT_OWNED_METADATA_ONLY_LIVE_PROBE_RECEIPTS",
+    "unknown_counts_as_healthy": false
+  },
+  "updated_at": "2026-07-18T04:58:00+00:00"
+}

.agent/tasks/codex/TASK-CODEX-APPLY-VERIFY-AIOS-ORCHESTRATOR-GATEWAY-V1.md

@@ -0,0 +1,69 @@
+# Codex task: apply and verify AIOS Orchestrator Gateway v1
+
+Contract: `cbe33ecab8e9794ba5f318bea43aeaf447a56fbc`
+
+Use the strongest actually available Codex model for the initial security review.
+If unavailable or timed out, record TIMEOUT/NOT_EXECUTED and let OpenClaw run
+the deterministic test path. Do not count a timeout as PASS.
+
+## Apply
+
+1. Create a new clean append-only branch and isolated worktree.
+2. Validate the delivery tarball and `SHA256SUMS`.
+3. Run the external `scripts/apply_gateway_patch.sh` with `SOURCE_DIR` and
+   `WORKTREE`; do not alter unrelated paths.
+4. Review all added code, especially:
+   - exact contract and optimistic state-version checks;
+   - event/decision idempotency;
+   - SQLite leases and retry behavior;
+   - Workspace Agent `202` asynchronous callback flow;
+   - Responses background creation and polling;
+   - file-inbox and Git-ref polling;
+   - traversal/symlink protections;
+   - OpenClaw lifecycle synchronization;
+   - systemd sandbox;
+   - install and rollback transactions.
+
+## Tests
+
+Run from the final source tree:
+
+- Python compile for all gateway and helper files;
+- unit tests;
+- JSON schema/config parsing;
+- Bash syntax;
+- `systemd-analyze verify`;
+- event duplicate and payload-conflict tests;
+- stale state-version rejection;
+- lease/double-claim test;
+- Workspace trigger failure and Responses fallback;
+- response queued/in-progress/completed polling;
+- file-inbox recovery after HTTP failure;
+- Git-ref initial baseline and subsequent-change event;
+- task start/end and project summary synchronization;
+- dispatch traversal and symlink rejection;
+- retry/backoff/dead-letter;
+- install dry-run;
+- rollback test in an isolated fixture;
+- `git diff --check`;
+- full repository tests;
+- final Gitleaks.
+
+## Commit and review
+
+1. Create an append-only implementation commit.
+2. Push without force.
+3. Confirm `WORKTREE_OID == BARE_OID == GITEA_OID`.
+4. Create an independent RESULT-only branch and exact-one result commit.
+5. Record the source bundle SHA-256, implementation OID, RESULT OID, tests,
+   Gitleaks, systemd validation and remaining external configuration blockers.
+
+## Forbidden
+
+No reset, amend, rebase, force push, direct main push, controller mutation,
+secret disclosure, fabricated test result, production deployment or B3 evidence
+fabrication.
+
+Success:
+
+`GATEWAY_CODE_REVIEW=PASS IMPLEMENTATION=<oid> RESULT=<oid> OID_MATCH=YES`

.agent/tasks/codex/TASK-CODEX-V2R1-ADAPTIVE-PRODUCTION-EXECUTION-20260717.md

@@ -0,0 +1,13 @@
+# Codex V2R1 adaptive execution
+CONTRACT_ACK=cbe33ecab8e9794ba5f318bea43aeaf447a56fbc
+Read `.agent/policies/V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT.yaml`.
+Execute P1-POST-CONTRACT-REACK now:
+- read-only verify Repair3 e110cda9968cadc5c7b7179ec5003b05aad11ce4
+- read-only verify RESULT 49a9c2e0cc898ecf2bbd45f454e007644d7f3045
+- verify lineage from 8d9c6da90fc8caa69b691d243c6fefb40b6b0575, exact4, tests, Gitleaks and RESULT-only scope
+- do not modify Repair3 code in this unit
+Act as fallback for OpenClaw only on timeout/unavailability. Use GPT-5.6 only if actually exposed; otherwise strongest visible model. Prefer OpenClaw when quality is comparable or volume is high; prefer Codex for complex/security-critical work.
+Forbidden: reset, amend, rebase, force push, direct main push, controller mutation, secret disclosure, fabricated evidence, skipped gates.
+Report:
+CONTRACT=cbe33ecab8e9794ba5f318bea43aeaf447a56fbc WORK_UNIT=<id> TRACK=<id> GATE=<id> AGENT=codex STATUS=<status> IMPLEMENTATION=<oid-or-NONE> RESULT=<oid-or-NONE> OID_MATCH=<YES-or-NO> BLOCKER=<reason-or-NONE>
+Keep BASELINE=V1R4C6 RELEASE=paused PRODUCTION_RELEASE=NOT_STARTED until production gate passes.

.agent/tasks/openclaw/TASK-OPENCLAW-A0-THREE-PARTY-SELF-HEALING-AND-RELEASE-20260718.md

@@ -0,0 +1,119 @@
+# OpenClaw A0 Three-Party Self-Healing and Release Supervision
+
+CONTRACT_ACK=cbe33ecab8e9794ba5f318bea43aeaf447a56fbc
+
+## Mission
+
+Close the GPT/OpenClaw/Codex unattended loop before any main merge or production release. OpenClaw is the default state writer and long-running supervisor, but work may be reassigned dynamically under the shared contract.
+
+## Authoritative inputs
+
+- Governance contract: `cbe33ecab8e9794ba5f318bea43aeaf447a56fbc`
+- Governance dispatch head before this task: `9195470ceb78fd57ffface3dcc38f40b75efa9d8`
+- Gateway integration implementation: `c3984ca2b4388875d2875b4fdfdf95a2984f6ab3`
+- Gateway integration RESULT: `4e63b1559aa3fc07b1384154c97b2c90b84353ed`
+- Three-party self-healer candidate branch: `patch/a0-three-party-self-healing-20260718-20260718T043256`
+- Production baseline: `V1R4C6`
+- Release status: `paused`
+
+## Priority invariant
+
+Continuously evaluate exactly three parties:
+
+1. `central_gpt` — Orchestrator Gateway plus a valid Workspace Agent or Responses API decision channel.
+2. `openclaw` — OpenClaw watcher, lifecycle sync, durable task execution and heartbeat.
+3. `codex` — Codex watcher, auto-claim, lifecycle sync, durable task execution and heartbeat.
+
+When exactly two parties are HEALTHY and the third is explicitly UNHEALTHY, create a P0 repair work unit for the unique unhealthy party before every other task. UNKNOWN is not UNHEALTHY and must fail closed. Do not repair when fewer than two are healthy or any health result is ambiguous.
+
+## A0-SH1: supervise implementation completion
+
+Codex owns the high-risk code changes. Independently verify that the final implementation contains:
+
+- strict root-owned configuration validation and no symlink chain;
+- fixed built-in party adapters rather than arbitrary untrusted repair commands;
+- bounded stdout/stderr redaction so tokens and secrets cannot enter audit logs;
+- exclusive lease, cooldown, circuit breaker and stale lease recovery;
+- event trigger plus periodic polling;
+- OpenClaw lifecycle events: `TASK_DISPATCHED`, `TASK_STARTED`, `TASK_ENDED`, `DECISION_APPLIED`, `PROJECT_SUMMARY`, `PROJECT_COMPLETED`;
+- durable file outbox fallback when HTTP callback is unavailable;
+- systemd service and timer;
+- health and repair adapters for central GPT, OpenClaw and Codex;
+- install, verify and rollback scripts;
+- deterministic tests for all health combinations and failures.
+
+Reject the current candidate if it only contains `automation/three_party_self_healer.py` without these controls.
+
+## A0-SH2: live three-party validation
+
+After Codex implementation RESULT passes, deploy only to a non-production acceptance context and run:
+
+1. All-three healthy steady state for at least three poll intervals.
+2. GPT unhealthy while OpenClaw and Codex healthy: GPT repair becomes P0 and recovers.
+3. OpenClaw unhealthy while GPT and Codex healthy: OpenClaw repair becomes P0 and recovers.
+4. Codex unhealthy while GPT and OpenClaw healthy: Codex repair becomes P0 and recovers.
+5. One healthy plus two unhealthy: no repair; fail closed.
+6. Any UNKNOWN health: no repair; fail closed.
+7. Repair timeout: retry with backoff, then circuit open.
+8. Service restart: state, lease and pending work recover.
+9. HTTP event path unavailable: file inbox polling recovers.
+10. Git webhook unavailable: Git ref polling detects change.
+11. Duplicate event ID: no duplicate dispatch.
+12. Main Workspace Agent channel unavailable: Responses fallback takes over only with a valid approved credential.
+13. OpenClaw receives every task start/end and project summary notification.
+14. Two consecutive unattended decision/execution/result cycles complete with no chat message or manual dispatch.
+
+Do not use dummy API keys or environment-variable presence as proof of a valid central decision channel.
+
+## A0-SH3: authoritative closure
+
+Only after independent verification of the above create one append-only state update and an exact-one RESULT file. Required output:
+
+```text
+AUTOMATION_CLOSED=PASS
+CENTRAL_GPT_HEALTH=PASS
+OPENCLAW_AUTO_CLAIM=PASS
+CODEX_AUTO_CLAIM=PASS
+THREE_PARTY_SELF_HEALING=PASS
+EVENT_TRIGGER=PASS
+POLLING=PASS
+OPENCLAW_LIFECYCLE_SYNC=PASS
+TWO_CYCLE_UNATTENDED_LOOP=PASS
+RESTART_RECOVERY=PASS
+ROLLBACK=PASS
+```
+
+Any missing item keeps `AUTOMATION_CLOSED=NO`.
+
+## Release continuation
+
+After and only after `AUTOMATION_CLOSED=PASS`, automatically resume the governed release sequence:
+
+1. Real B3 evidence intake and independent review.
+2. B4 implementation and validation.
+3. Full integration, regression, security and migration tests.
+4. Normal PR/GitOps merge to main; never direct-push main.
+5. Immutable release artifact, digest, SBOM and signature.
+6. Staging and rollback exercise.
+7. Canary and monitoring validation.
+8. Owner/admin GitOps production deployment using existing approved release controls.
+9. Production smoke tests and production RESULT-only commit.
+
+External facts that cannot be fabricated — real WeChat credentials/raw-wire, valid secret references and owner-only release approval — remain fail-closed blockers. The loop must monitor them and resume automatically when they become available.
+
+## Forbidden
+
+- reset, amend, rebase, force push;
+- direct push to main;
+- controller mutation;
+- secret disclosure;
+- dummy credentials presented as production credentials;
+- fabricated B3 evidence;
+- timeout or skipped checks recorded as PASS;
+- production release before `AUTOMATION_CLOSED=PASS`.
+
+Progress format:
+
+```text
+CONTRACT=cbe33ecab8e9794ba5f318bea43aeaf447a56fbc WORK_UNIT=<id> AGENT=openclaw STATUS=<status> COMMIT=<oid-or-NONE> BLOCKER=<stable-reason-or-NONE>
+```

.agent/tasks/openclaw/TASK-OPENCLAW-DEPLOY-AIOS-ORCHESTRATOR-GATEWAY-V1.md

@@ -0,0 +1,68 @@
+# OpenClaw task: deploy and supervise AIOS Orchestrator Gateway v1
+
+Contract: `cbe33ecab8e9794ba5f318bea43aeaf447a56fbc`
+
+You are the default orchestrator and deployment supervisor.
+
+## Preconditions
+
+- Codex has applied and independently reviewed this source bundle on a clean,
+  append-only branch.
+- Implementation and RESULT OIDs are identical across worktree, bare repo and
+  Gitea.
+- Final Gitleaks and repository tests are PASS.
+- No force push, reset, amend or rebase occurred.
+
+## Responsibilities
+
+1. Validate the source bundle SHA-256 and `SHA256SUMS`.
+2. Review the generated systemd service, poll timer, tmpfiles and sysusers files.
+3. Install through `scripts/install_aios_orchestrator_gateway.sh`.
+4. Configure one or both central-model channels:
+   - published Workspace Agent API channel with `agtch_...` trigger ID and a
+     Workspace Agent access token stored outside Git; or
+   - Responses API fallback with an approved model and API key stored outside Git.
+5. Publish the callback endpoint securely and configure the Workspace Agent
+   action from `workspace-agent/orchestrator-decision-action.openapi.yaml`.
+6. Confirm that the Workspace Agent instructions match
+   `workspace-agent/CENTRAL_AGENT_INSTRUCTIONS.md`.
+7. Enable both:
+   - the continuously running gateway service;
+   - the independent `aios-orchestrator-gateway-poll.timer`.
+8. Verify HTTP event ingestion, file-inbox polling, Git-ref polling,
+   Workspace Agent trigger acceptance, callback decision, Responses background
+   polling fallback, dispatch queue generation, retry leases and loop guards.
+9. Verify OpenClaw receives and synchronizes:
+   - TASK_DISPATCHED
+   - TASK_STARTED
+   - TASK_ENDED
+   - PROJECT_SUMMARY
+   - PROJECT_COMPLETED
+10. Run a harmless bootstrap work unit through OpenClaw and Codex and confirm
+    duplicate event submission is idempotent.
+11. Run rollback, reinstall and heartbeat/health verification.
+12. Create one RESULT-only review recording exact commits, artifact digest,
+    tests, systemd security, polling recovery, lifecycle synchronization and
+    rollback.
+
+## Fail-closed boundaries
+
+- Do not put Workspace Agent tokens, API keys, callback tokens or gateway
+  credentials in Git, logs, command arguments or RESULT files.
+- Do not claim the gateway resolves the existing B3 credential/raw-wire blocker.
+- Do not advance B4 or production merely because this gateway is healthy.
+- Do not bypass owner/admin production release approvals.
+- Do not use reset, amend, rebase, force push, direct main push or bare-ref edits.
+
+## Required final status
+
+Success:
+
+`ORCHESTRATOR_GATEWAY_LIVE=PASS POLLING=PASS OPENCLAW_SYNC=PASS ROLLBACK=PASS`
+
+Blocker:
+
+`ORCHESTRATOR_GATEWAY_LIVE=BLOCKED reason=<stable_reason>`
+
+Keep `BASELINE=V1R4C6 RELEASE=paused PRODUCTION_RELEASE=NOT_STARTED` until the
+existing production contract advances all release gates.

.agent/tasks/openclaw/TASK-OPENCLAW-V2R1-ADAPTIVE-PRODUCTION-ORCHESTRATION-20260717.md

@@ -0,0 +1,13 @@
+# OpenClaw V2R1 adaptive orchestration
+CONTRACT_ACK=cbe33ecab8e9794ba5f318bea43aeaf447a56fbc
+Read `.agent/policies/V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT.yaml`.
+You are default orchestrator and sole authoritative state writer.
+Execute immediately:
+1. R0-DISCOVER-SECRET-PROVIDER: discover approved provider metadata and owner-probe source without reading or outputting secrets. Environment variables alone are not approved secret refs.
+2. P2-INVENTORY-REAL-EVIDENCE: inventory approved restricted B3 evidence locations; validate existing facts; never synthesize evidence.
+3. Independently verify Codex results before advancing.
+Prefer OpenClaw for comparable-quality, large, repetitive, long-running, infrastructure and cost-sensitive work. Prefer Codex strongest actually available model for complex code, security boundaries, architecture and high-risk review. On timeout mark TIMEOUT and switch agent; never infer PASS.
+Forbidden: reset, amend, rebase, force push, direct main push, controller mutation, secret disclosure, fabricated evidence, skipped gates.
+Report:
+CONTRACT=cbe33ecab8e9794ba5f318bea43aeaf447a56fbc WORK_UNIT=<id> TRACK=<id> GATE=<id> AGENT=openclaw STATUS=<status> COMMIT=<oid-or-NONE> BLOCKER=<reason-or-NONE>
+Keep BASELINE=V1R4C6 RELEASE=paused PRODUCTION_RELEASE=NOT_STARTED until production gate passes.

.gitignore

@@ -11,7 +11,3 @@ runtime/tmp/
 runtime/cache/
 logs/
 config/test_write_perms
-/data/webops.sqlite3
-/data/webops.sqlite3-wal
-/data/webops.sqlite3-shm
-/data/webops.sqlite3-journal

README-AIOS-CODEX-WATCHER.md

@@ -0,0 +1,11 @@
+# AIOS Codex automatic command watcher
+
+The watcher polls the governed `commands/active` queue without a chat trigger. It uses SQLite transactions for exclusive leases, records the exact command digest, rejects contract drift, retries transient failures, dead-letters exhausted work, and resumes from the last durable phase so an end-event retry does not execute a work unit twice.
+
+Commands are JSON documents validated by `schemas/codex-command.schema.json`. `acceptance_probe` is the only built-in action and has no external side effect. Production `codex` work requires an administrator-provisioned absolute executor path; the instruction is passed on standard input, never argv or environment. The executor receives a sanitized environment and must obtain credentials through its approved file or exec provider. If the executor is absent, the task fails closed and follows the retry/dead-letter policy.
+
+The watcher provides at-most-once execution. It writes the `EXECUTING` phase before launching an external executor; if the host dies after an external effect but before a result is durably recorded, recovery does not replay the work and instead dead-letters the ambiguity for human review. Start and end event JSON is persisted before transmission, so response-loss retries reuse the exact event ID and payload and are deduplicated by the Gateway.
+
+Lifecycle evidence is appended to `/var/log/aios-codex-watcher/audit.jsonl` as `CODEX_AUTO_CLAIM`, `TASK_STARTED`, `TASK_EXECUTED`, `TASK_ENDED`, and `EVENT_POSTED`. Inputs, tokens, stdout, and stderr are not logged; only result digests are retained.
+
+Install from a reviewed commit with `sudo scripts/install_aios_codex_watcher.sh`. The installer creates a content-addressed release, atomically updates `current`, writes a receipt, and enables the five-second systemd timer. The existing Gateway inbound token file is referenced in place and never copied.

README-AIOS-ORCHESTRATOR-GATEWAY.md

@@ -0,0 +1,107 @@
+# AIOS Orchestrator Gateway v0.2
+
+This component turns the current passive GPT orchestration pattern into a
+durable, unattended loop:
+
+```text
+Gitea/OpenClaw/Codex event
+  -> HTTP event endpoint or polled file inbox
+  -> durable SQLite state machine
+  -> Workspace Agent API trigger
+  -> strict callback decision
+  -> Responses API background fallback and polling
+  -> OpenClaw/Codex dispatch queues
+  -> start/end/result events
+  -> next orchestration cycle
+```
+
+## Reliability mechanisms
+
+The gateway does not depend on one timer, webhook or model call:
+
+- HTTP event ingestion.
+- Periodic file-inbox polling for missed webhooks and offline producers.
+- Local bare-Git ref polling for `main`, governance, patch and result refs.
+- Workspace Agent retries with a stable event `Idempotency-Key`.
+- Workspace Agent callback timeout and Responses API background fallback.
+- Responses status polling until completion or fail-closed terminal status.
+- SQLite optimistic state versions, idempotency records and processing leases.
+- Exponential retry with a maximum retry count and dead-letter state.
+- Same-blocker and maximum-hop guards to stop non-progress loops.
+- A systemd timer runs `--poll-once` as an independent reliability watchdog.
+
+Workspace Agent trigger runs are asynchronous and do not expose a retrievable
+final response. The central Workspace Agent must therefore call the
+`submit_orchestration_decision` action.
+
+## OpenClaw synchronization
+
+Every lifecycle stage is durably written to the OpenClaw synchronization queue:
+
+- `TASK_DISPATCHED`
+- `TASK_STARTED`
+- `TASK_ENDED`
+- `DECISION_APPLIED`
+- `PROJECT_SUMMARY`
+- `PROJECT_COMPLETED`
+
+An optional authenticated OpenClaw HTTP endpoint can receive the same records.
+A failed HTTP delivery remains in the lifecycle retry queue. OpenClaw remains
+the default project-status synchronizer and authoritative progress presenter.
+
+## Agent execution contract
+
+Each dispatched JSON envelope contains:
+
+- exact contract commit;
+- source event;
+- clean base commit;
+- primary and fallback agent;
+- allowed paths;
+- required checks;
+- forbidden operations;
+- completion event callback format.
+
+OpenClaw and Codex must send a `work_unit_started` event before execution and a
+`work_unit_completed`, `work_unit_blocked`, or `work_unit_failed` event when
+they stop. This guarantees that OpenClaw can synchronize every task start,
+finish, and overall project summary.
+
+## Security
+
+- Model and callback credentials are read only from root-owned secret files.
+- Credentials never enter Git, dispatch payloads or logs.
+- The gateway runs as a dedicated unprivileged user.
+- Dispatch and sync paths are protected against traversal and symlink targets.
+- All state changes require the exact contract commit and current state version.
+- Production evidence, credentials and approvals stay fail-closed.
+- Git history operations remain controlled by the committed governance contract.
+
+## Deployment sequence
+
+1. Apply this source bundle to a clean append-only branch.
+2. Run unit, repository, shell, JSON, systemd and Gitleaks checks.
+3. Configure one or both model channels:
+   - published Workspace Agent API channel and Workspace Agent access token;
+   - Responses API key and approved fallback model.
+4. Publish the decision callback as a Workspace Agent action or MCP tool.
+5. Install the service through `scripts/install_aios_orchestrator_gateway.sh`.
+6. Run `scripts/verify_aios_orchestrator_gateway.sh`.
+7. Submit a harmless event and verify:
+   - trigger acceptance;
+   - strict decision callback;
+   - dispatch file;
+   - OpenClaw task-start/task-end/project-summary synchronization;
+   - duplicate idempotency;
+   - polling recovery after suppressing the HTTP webhook.
+
+The installer copies an explicit gateway-only allowlist into a release directory
+named by its SHA-256 digest, atomically updates `/opt/aios-orchestrator-gateway/current`,
+and persists `/var/lib/aios-orchestrator-gateway/install-receipt.json` with the
+current and previous release. `--dry-run` performs source validation and emits
+`AIOS_ORCHESTRATOR_INSTALL_DRY_RUN=PASS` without changing installed state.
+
+Rollback reads that root-owned `0600` receipt, verifies both release directory
+names and `SOURCE_DIGEST` files, coordinates the gateway and poll units, and
+atomically switches `current` to the previous release. Repeating the same
+rollback is a no-op and emits `NOOP_ALREADY_ROLLED_BACK`.

active-runtime/app/aios_chatgpt_actions_api.py

@@ -10,11 +10,22 @@ from orchestrator.action_monitor import ActionMonitor
 
 ROOT = Path(os.getenv('AIOS_GITOPS_ROOT', '/data/aios-gitops'))
 WS = Path(os.getenv('AIOS_GITOPS_WORKSPACE', str(ROOT / 'workspace')))
+sys.path.insert(0, str(WS))
+from services.aios_orchestrator_gateway.action_bridge import (
+    CallbackBridgeError,
+    submit_orchestration_decision,
+)
+
 SECRETS = Path(os.getenv('AIOS_GITOPS_SECRETS_DIR', str(ROOT / 'runtime' / 'secrets')))
 TOKEN_FILE = Path(os.getenv('AIOS_GITOPS_TOKEN_FILE', str(SECRETS / 'gitops.tokens')))
 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'
+ORCHESTRATOR_OPENAPI = WS / 'workspace-agent' / 'orchestrator-decision-action.openapi.yaml'
+ORCHESTRATOR_CONTRACT_COMMIT = os.getenv('AIOS_ORCHESTRATOR_CONTRACT_COMMIT', '')
+ORCHESTRATOR_CALLBACK_SECRET_REF = os.getenv('AIOS_ORCHESTRATOR_CALLBACK_SECRET_REF', '')
+_resolver = os.getenv('AIOS_ORCHESTRATOR_SECRET_REF_RESOLVER', '')
+ORCHESTRATOR_SECRET_REF_RESOLVER = Path(_resolver) if _resolver else None
 BARE_REPO = Path(os.getenv('AIOS_GITOPS_BARE_REPO', str(ROOT / 'runtime' / 'gitea-bin' / 'data' / 'repositories' / 'aios' / 'aios.git')))
 monitor = ActionMonitor()
 
@@ -184,6 +195,8 @@ class H(BaseHTTPRequestHandler):
             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 == '/api/orchestrator-decision.openapi.yaml':
+                return self.sendt(ORCHESTRATOR_OPENAPI.read_text(encoding='utf-8'), 'application/yaml; charset=utf-8') if ORCHESTRATOR_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)
@@ -216,6 +229,7 @@ class H(BaseHTTPRequestHandler):
     def do_POST(self):
         path=urllib.parse.urlparse(self.path).path.rstrip('/'); data=self.body()
         try:
+            if path == '/v1/orchestrator/decisions': return self.orchestration_decision(data)
             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)
@@ -229,6 +243,25 @@ class H(BaseHTTPRequestHandler):
         except Exception as e:
             monitor.record_failure('do_POST', str(e), {'path':path})
             return self.sendj({'error':str(e)},500)
+    def orchestration_decision(self,data):
+        a=self.need('orchestrator:decision')
+        if not a: return
+        if not ORCHESTRATOR_CONTRACT_COMMIT or ORCHESTRATOR_SECRET_REF_RESOLVER is None:
+            return self.sendj({'error':'CALLBACK_CONFIGURATION_UNAVAILABLE'},503)
+        try:
+            result=submit_orchestration_decision(
+                data,
+                contract_commit=ORCHESTRATOR_CONTRACT_COMMIT,
+                secret_ref=ORCHESTRATOR_CALLBACK_SECRET_REF,
+                resolver=ORCHESTRATOR_SECRET_REF_RESOLVER,
+            )
+        except CallbackBridgeError as exc:
+            return self.sendj({'error':exc.category},exc.status_code)
+        except Exception:
+            # The outer request handler records exception strings. Keep this
+            # secret-bearing boundary metadata-only even for unexpected faults.
+            return self.sendj({'error':'CALLBACK_INTERNAL_ERROR'},500)
+        return self.sendj(result,202)
     def branch(self,data):
         a=self.need('branch:create');
         if not a: return
@@ -390,7 +423,7 @@ 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','orchestrator_openapi':'/api/orchestrator-decision.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 /v1/orchestrator/decisions','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,'orchestrator_decision_scope':'orchestrator:decision','orchestrator_callback_credential':'secret_ref_only','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}}
 
 def main():
     print(f'AIOS ChatGPT GitOps adapter listening on {HOST}:{PORT}')

active-runtime/app/aios_v2r1/audit.py

@@ -1,89 +0,0 @@
-"""Append-only audit chain for AIOS V2R1."""
-from __future__ import annotations
-
-import hashlib
-import json
-from pathlib import Path
-import sqlite3
-from typing import Any
-
-from .tenant_context import canonical_json, isoformat, require_ident
-
-
-class AuditLog:
-    def __init__(self, database: str | Path) -> None:
-        self.database = str(database)
-        with sqlite3.connect(self.database) as db:
-            db.execute("PRAGMA journal_mode=WAL")
-            db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS audit_events (
-                    seq INTEGER PRIMARY KEY AUTOINCREMENT,
-                    tenant_id TEXT NOT NULL,
-                    trace_id TEXT NOT NULL,
-                    event_type TEXT NOT NULL,
-                    payload TEXT NOT NULL,
-                    previous_hash TEXT NOT NULL,
-                    event_hash TEXT NOT NULL UNIQUE,
-                    created_at TEXT NOT NULL
-                )
-                """
-            )
-
-    def append(self, *, tenant_id: str, trace_id: str, event_type: str, payload: dict[str, Any]) -> str:
-        tenant_id = require_ident("tenant_id", tenant_id, tenant=True)
-        trace_id = require_ident("trace_id", trace_id)
-        event_type = require_ident("event_type", event_type)
-        with sqlite3.connect(self.database) as db:
-            previous = db.execute(
-                "SELECT event_hash FROM audit_events ORDER BY seq DESC LIMIT 1"
-            ).fetchone()
-            previous_hash = previous[0] if previous else "GENESIS"
-            body = {
-                "tenant_id": tenant_id,
-                "trace_id": trace_id,
-                "event_type": event_type,
-                "payload": payload,
-                "previous_hash": previous_hash,
-                "created_at": isoformat(),
-            }
-            digest = hashlib.sha256(
-                canonical_json(body)
-            ).hexdigest()
-            db.execute(
-                "INSERT INTO audit_events VALUES(NULL,?,?,?,?,?,?,?)",
-                (
-                    tenant_id,
-                    trace_id,
-                    event_type,
-                    json.dumps(payload, ensure_ascii=False),
-                    previous_hash,
-                    digest,
-                    body["created_at"],
-                ),
-            )
-            return digest
-
-    def verify(self) -> bool:
-        previous = "GENESIS"
-        with sqlite3.connect(self.database) as db:
-            rows = db.execute(
-                "SELECT tenant_id,trace_id,event_type,payload,previous_hash,event_hash,created_at "
-                "FROM audit_events ORDER BY seq"
-            )
-            for row in rows:
-                body = {
-                    "tenant_id": row[0],
-                    "trace_id": row[1],
-                    "event_type": row[2],
-                    "payload": json.loads(row[3]),
-                    "previous_hash": row[4],
-                    "created_at": row[6],
-                }
-                if row[4] != previous:
-                    return False
-                digest = hashlib.sha256(canonical_json(body)).hexdigest()
-                if digest != row[5]:
-                    return False
-                previous = digest
-        return True

active-runtime/app/aios_v2r1/cell_manager.py

@@ -1,73 +0,0 @@
-"""AIOS V2R1 Tenant Cell lifecycle CLI primitives."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime, timezone
-import json
-from pathlib import Path
-
-from .tenant_context import ValidationError, require_ident
-
-
-@dataclass(frozen=True)
-class CellRecord:
-    tenant_id: str
-    cell_id: str
-    version: str
-    state: str
-    config_digest: str
-    created_at: str
-
-
-class CellManager:
-    def __init__(self, registry: str | Path) -> None:
-        self.registry = Path(registry)
-        self.registry.parent.mkdir(parents=True, exist_ok=True)
-        if not self.registry.exists():
-            self.registry.write_text("{\"cells\":{}}\n", encoding="utf-8")
-
-    def _load(self) -> dict:
-        return json.loads(self.registry.read_text(encoding="utf-8"))
-
-    def _save(self, value: dict) -> None:
-        self.registry.write_text(
-            json.dumps(value, ensure_ascii=False, indent=2) + "\n",
-            encoding="utf-8",
-        )
-
-    def create(self, tenant_id: str, cell_id: str, version: str, digest: str) -> CellRecord:
-        tenant_id = require_ident("tenant_id", tenant_id, tenant=True)
-        cell_id = require_ident("cell_id", cell_id)
-        data = self._load()
-        if tenant_id in data["cells"]:
-            raise ValidationError("tenant already has a cell")
-        record = CellRecord(
-            tenant_id,
-            cell_id,
-            version,
-            "created",
-            digest,
-            datetime.now(timezone.utc).isoformat(),
-        )
-        data["cells"][tenant_id] = record.__dict__
-        self._save(data)
-        return record
-
-    def status(self, tenant_id: str) -> CellRecord:
-        data = self._load()
-        item = data["cells"].get(tenant_id)
-        if not item:
-            raise ValidationError("unknown tenant")
-        return CellRecord(**item)
-
-    def transition(self, tenant_id: str, state: str) -> CellRecord:
-        allowed = {"created", "starting", "healthy", "upgrading", "rollback", "failed"}
-        if state not in allowed:
-            raise ValidationError("invalid cell state")
-        data = self._load()
-        item = data["cells"].get(tenant_id)
-        if not item:
-            raise ValidationError("unknown tenant")
-        item["state"] = state
-        self._save(data)
-        return CellRecord(**item)

active-runtime/app/aios_v2r1/channel_adapter.py

@@ -1,64 +0,0 @@
-"""The only V2R1 ingress adapter: verified context to routed ledger record."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime
-from threading import RLock
-from typing import Callable, Mapping, Any
-
-from .message_ledger import LedgerRecord, MessageLedger
-from .router import Route, TenantRouter
-from .session_pool import SessionLease, SessionPool
-from .tenant_context import CanonicalMessage, TenantContext, utc_now
-
-
-@dataclass(frozen=True)
-class IngressResult:
-    record: LedgerRecord
-    route: Route
-    session: SessionLease
-
-
-class ChannelAdapter:
-    """Fail-closed runtime ingress composition.
-
-    The adapter intentionally accepts no tenant or Cell authority outside the
-    signed context and TenantRouter.  A process lock keeps rollback handling
-    deterministic for a single runtime while SQLite protects cross-process
-    ledger writes.
-    """
-
-    def __init__(
-        self,
-        *,
-        router: TenantRouter,
-        ledger: MessageLedger,
-        session_pool: SessionPool,
-        signing_key: bytes,
-        clock: Callable[[], datetime] = utc_now,
-    ) -> None:
-        self._router = router
-        self._ledger = ledger
-        self._session_pool = session_pool
-        self._signing_key = signing_key
-        self._clock = clock
-        self._lock = RLock()
-
-    def ingest(self, *, token: str, message: Mapping[str, Any]) -> IngressResult:
-        with self._lock:
-            context = TenantContext.verify(token, self._signing_key, now=self._clock())
-            canonical = CanonicalMessage.from_mapping(message)
-            canonical.assert_context(context)
-            route = self._router.assert_context_route(context)
-            self._router.assert_message_route(canonical)
-            self._session_pool.assert_available(context, route)
-
-            existed = self._ledger.matches(canonical)
-            record = self._ledger.append(canonical)
-            try:
-                lease = self._session_pool.acquire(context, route)
-            except Exception:
-                if not existed:
-                    self._ledger.remove(record)
-                raise
-            return IngressResult(record=record, route=route, session=lease)

active-runtime/app/aios_v2r1/cli.py

@@ -1,48 +0,0 @@
-"""aios-cell command implementation for V2R1 Cell lifecycle."""
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-
-from .cell_manager import CellManager
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="aios-cell")
-    parser.add_argument("registry")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    create = sub.add_parser("create")
-    create.add_argument("tenant_id")
-    create.add_argument("cell_id")
-    create.add_argument("version")
-    create.add_argument("digest")
-
-    status = sub.add_parser("status")
-    status.add_argument("tenant_id")
-
-    transition = sub.add_parser("transition")
-    transition.add_argument("tenant_id")
-    transition.add_argument("state")
-
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    manager = CellManager(args.registry)
-    if args.command == "create":
-        result = manager.create(args.tenant_id, args.cell_id, args.version, args.digest)
-    elif args.command == "status":
-        result = manager.status(args.tenant_id)
-    elif args.command == "transition":
-        result = manager.transition(args.tenant_id, args.state)
-    else:
-        return 2
-    print(json.dumps(result.__dict__, ensure_ascii=False, sort_keys=True))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

active-runtime/app/aios_v2r1/fleet.py

@@ -1,106 +0,0 @@
-"""OpenClaw Cell lifecycle adapter for AIOS V2R1."""
-from __future__ import annotations
-
-from dataclasses import asdict, dataclass, field
-import json
-from pathlib import Path
-import subprocess
-from typing import Any, Mapping
-
-from .tenant_context import ValidationError, V2R1Error, require_ident
-
-
-@dataclass(frozen=True)
-class CellSpec:
-    tenant_id: str
-    image: str
-    runtime: str = "docker"
-    port: int | None = None
-    memory: str = "2g"
-    cpus: str = "2"
-    pids_limit: int = 512
-    network: str = "bridge"
-    env: tuple[str, ...] = field(default_factory=tuple)
-
-    def __post_init__(self) -> None:
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        if self.runtime not in {"docker", "podman"}:
-            raise ValidationError("unsupported runtime")
-        if not self.image:
-            raise ValidationError("image required")
-
-
-class OpenClawFleet:
-    def __init__(self, binary: str = "openclaw") -> None:
-        self.binary = binary
-
-    def _run(self, args: list[str]) -> dict[str, Any]:
-        proc = subprocess.run(
-            [self.binary, *args],
-            check=False,
-            text=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        )
-        if proc.returncode:
-            raise V2R1Error(proc.stderr.strip() or "openclaw command failed")
-        data = json.loads(proc.stdout or "{}")
-        if isinstance(data, dict):
-            return data
-        return {"result": data}
-
-    def create(self, spec: CellSpec) -> dict[str, Any]:
-        return self._run([
-            "fleet", "create", spec.tenant_id,
-            "--image", spec.image,
-            "--runtime", spec.runtime,
-            "--json",
-        ])
-
-    def status(self, tenant_id: str) -> dict[str, Any]:
-        require_ident("tenant_id", tenant_id, tenant=True)
-        return self._run(["fleet", "status", tenant_id, "--json"])
-
-    def doctor(self, tenant_id: str | None = None) -> dict[str, Any]:
-        args = ["fleet", "doctor"]
-        if tenant_id:
-            require_ident("tenant_id", tenant_id, tenant=True)
-            args.append(tenant_id)
-        args.append("--json")
-        return self._run(args)
-
-    def backup(self, tenant_id: str, output: str | Path) -> dict[str, Any]:
-        return self._run(["fleet", "backup", tenant_id, "--out", str(output), "--json"])
-
-    def restore(self, tenant_id: str, archive: str | Path) -> dict[str, Any]:
-        return self._run(["fleet", "restore", tenant_id, "--from", str(archive), "--json"])
-
-    def upgrade(self, tenant_id: str, image: str) -> dict[str, Any]:
-        return self._run(["fleet", "upgrade", tenant_id, "--image", image, "--json"])
-
-
-def load_inventory(path: str | Path) -> list[CellSpec]:
-    raw = json.loads(Path(path).read_text(encoding="utf-8"))
-    if raw.get("schema_version") != "aios.cells.v1":
-        raise ValidationError("invalid inventory schema")
-    result: list[CellSpec] = []
-    seen: set[str] = set()
-    for item in raw.get("cells", []):
-        spec = CellSpec(
-            tenant_id=item["tenant_id"],
-            image=item["image"],
-            runtime=item.get("runtime", "docker"),
-            port=item.get("port"),
-            env=tuple(item.get("env", [])),
-        )
-        if spec.tenant_id in seen:
-            raise ValidationError("duplicate tenant")
-        seen.add(spec.tenant_id)
-        result.append(spec)
-    if not result:
-        raise ValidationError("no cells")
-    return result
-
-
-def inventory_as_dict(items: list[CellSpec]) -> dict[str, Any]:
-    return {"schema_version": "aios.cells.v1", "cells": [asdict(x) for x in items]}

active-runtime/app/aios_v2r1/hermes_fabric.py

@@ -1,143 +0,0 @@
-"""Tenant-partitioned Hermes shared agent fabric primitives."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from contextlib import closing
-from pathlib import Path
-import sqlite3
-from typing import Any
-
-from .tenant_context import (
-    CanonicalMessage,
-    ConflictError,
-    ScopeError,
-    ValidationError,
-    isoformat,
-    require_ident,
-)
-
-
-@dataclass(frozen=True)
-class FabricJob:
-    job_id: str
-    tenant_id: str
-    cell_id: str
-    profile_id: str
-    session_id: str
-    event_id: str
-    status: str = "queued"
-
-    def __post_init__(self) -> None:
-        for name in (
-            "job_id", "cell_id", "profile_id", "session_id", "event_id"
-        ):
-            require_ident(name, getattr(self, name))
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        if self.status not in {"queued", "running", "completed", "failed", "cancelled"}:
-            raise ValidationError("invalid job status")
-
-
-class HermesFabric:
-    """Shared scheduler storage with mandatory tenant partition keys."""
-
-    def __init__(self, database: str | Path) -> None:
-        self.database = str(database)
-        with closing(sqlite3.connect(self.database)) as connection, connection as db:
-            db.execute("PRAGMA journal_mode=WAL")
-            db.execute("PRAGMA synchronous=FULL")
-            db.execute(
-                """
-                CREATE TABLE IF NOT EXISTS fabric_jobs (
-                    job_id TEXT PRIMARY KEY,
-                    tenant_id TEXT NOT NULL,
-                    cell_id TEXT NOT NULL,
-                    profile_id TEXT NOT NULL,
-                    session_id TEXT NOT NULL,
-                    event_id TEXT NOT NULL UNIQUE,
-                    status TEXT NOT NULL,
-                    created_at TEXT NOT NULL,
-                    updated_at TEXT NOT NULL
-                )
-                """
-            )
-            db.execute(
-                "CREATE INDEX IF NOT EXISTS idx_fabric_tenant_queue "
-                "ON fabric_jobs(tenant_id, cell_id, status)"
-            )
-
-    def enqueue(
-        self,
-        *,
-        message: CanonicalMessage,
-        profile_id: str,
-    ) -> FabricJob:
-        profile_id = require_ident("profile_id", profile_id)
-        if not message.command_capable:
-            raise ScopeError("non-command events cannot create execution jobs")
-        if not message.is_authenticated_human_command:
-            raise ScopeError("only authenticated human commands can create jobs")
-        job = FabricJob(
-            job_id=f"job-{message.event_id}",
-            tenant_id=message.tenant_id,
-            cell_id=message.cell_id,
-            profile_id=profile_id,
-            session_id=message.session_id,
-            event_id=message.event_id,
-        )
-        now = isoformat()
-        conflict: ConflictError | None = None
-        try:
-            with closing(sqlite3.connect(self.database)) as connection, connection as db:
-                db.execute("PRAGMA journal_mode=WAL")
-                db.execute(
-                    "INSERT INTO fabric_jobs VALUES(?,?,?,?,?,?,?,?,?)",
-                    (
-                        job.job_id,
-                        job.tenant_id,
-                        job.cell_id,
-                        job.profile_id,
-                        job.session_id,
-                        job.event_id,
-                        job.status,
-                        now,
-                        now,
-                    ),
-                )
-        except sqlite3.IntegrityError:
-            conflict = ConflictError(
-                "fabric event already exists or violates queue uniqueness"
-            )
-        if conflict is not None:
-            raise conflict
-        return job
-
-    def claim(self, tenant_id: str, cell_id: str, profile_id: str) -> FabricJob | None:
-        require_ident("tenant_id", tenant_id, tenant=True)
-        require_ident("cell_id", cell_id)
-        require_ident("profile_id", profile_id)
-        with closing(sqlite3.connect(self.database)) as connection, connection as db:
-            db.execute("BEGIN IMMEDIATE")
-            row = db.execute(
-                "SELECT * FROM fabric_jobs WHERE tenant_id=? AND cell_id=? "
-                "AND profile_id=? AND status='queued' ORDER BY created_at LIMIT 1",
-                (tenant_id, cell_id, profile_id),
-            ).fetchone()
-            if not row:
-                db.commit()
-                return None
-            db.execute(
-                "UPDATE fabric_jobs SET status='running', updated_at=? WHERE job_id=?",
-                (isoformat(), row[0]),
-            )
-            db.commit()
-        return FabricJob(*row[:7])
-
-    def health(self) -> dict[str, Any]:
-        with closing(sqlite3.connect(self.database)) as connection, connection as db:
-            count = db.execute("SELECT count(*) FROM fabric_jobs").fetchone()[0]
-        return {
-            "component": "hermes_fabric",
-            "jobs": count,
-            "checked_at": datetime.now(timezone.utc).isoformat(),
-        }

active-runtime/app/aios_v2r1/hermes_profile.py

@@ -1,47 +0,0 @@
-"""Hermes shared fabric profile isolation primitives."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-import os
-
-from .tenant_context import ValidationError, require_ident
-
-
-@dataclass(frozen=True)
-class HermesProfile:
-    tenant_id: str
-    cell_id: str
-    profile_id: str
-    hermes_home: Path
-    workspace: Path
-
-    def __post_init__(self) -> None:
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        for name in ("cell_id", "profile_id"):
-            require_ident(name, getattr(self, name))
-        if not self.hermes_home.is_absolute() or not self.workspace.is_absolute():
-            raise ValidationError("profile paths must be absolute")
-
-    @property
-    def environment(self) -> dict[str, str]:
-        return {
-            "HERMES_HOME": str(self.hermes_home),
-            "HOME": str(self.hermes_home),
-            "AIOS_TENANT_ID": self.tenant_id,
-            "AIOS_CELL_ID": self.cell_id,
-            "AIOS_PROFILE_ID": self.profile_id,
-        }
-
-    def prepare(self) -> None:
-        self.hermes_home.mkdir(parents=True, exist_ok=True)
-        self.workspace.mkdir(parents=True, exist_ok=True)
-        os.chmod(self.hermes_home, 0o700)
-        os.chmod(self.workspace, 0o700)
-
-    def assert_path_allowed(self, path: str | Path) -> None:
-        target = Path(path).resolve()
-        for root in (self.hermes_home.resolve(), self.workspace.resolve()):
-            if target == root or root in target.parents:
-                return
-        raise ValidationError("path escapes profile isolation boundary")

active-runtime/app/aios_v2r1/identity.py

@@ -1,158 +0,0 @@
-"""Fail-closed identity binding for authenticated external ingress.
-
-External payload claims are not authority.  An HMAC-authenticated envelope is
-the sole factory for :class:`AuthenticatedPrincipal`; the resolver then checks
-every claim against the authoritative ``TenantRouter`` before the runtime signs
-an internal ``TenantContext``.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-import hashlib
-import hmac
-import re
-from typing import Any, Mapping
-
-from .router import Route, TenantRouter
-from .tenant_context import ScopeError, ValidationError, canonical_json, require_ident
-
-
-_PROVENANCE = object()
-_SIGNATURE_RE = re.compile(r"^[0-9a-f]{64}$")
-_SCOPE_FIELDS = (
-    "principal_id", "tenant_id", "cell_id", "channel",
-    "channel_account_id", "session_id", "message",
-)
-
-
-class AuthenticationError(ValidationError):
-    """Authentication or identity resolution failed without disclosing scope."""
-
-
-@dataclass(frozen=True, init=False)
-class AuthenticatedPrincipal:
-    """A principal which only the verified envelope factory can create."""
-
-    principal_id: str
-
-    def __init__(self, principal_id: str, *, _provenance: object) -> None:
-        if _provenance is not _PROVENANCE:
-            raise TypeError("AuthenticatedPrincipal is created by authenticated ingress only")
-        object.__setattr__(self, "principal_id", require_ident("principal_id", principal_id))
-
-    @classmethod
-    def _verified(cls, principal_id: str) -> "AuthenticatedPrincipal":
-        return cls(principal_id, _provenance=_PROVENANCE)
-
-
-@dataclass(frozen=True)
-class IdentityClaims:
-    tenant_id: str
-    cell_id: str
-    channel: str
-    channel_account_id: str
-    session_id: str
-
-    def __post_init__(self) -> None:
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        for field in ("cell_id", "channel", "channel_account_id", "session_id"):
-            require_ident(field, getattr(self, field))
-
-
-@dataclass(frozen=True)
-class AuthenticatedIngress:
-    principal: AuthenticatedPrincipal
-    claims: IdentityClaims
-    message: Mapping[str, Any]
-
-
-@dataclass(frozen=True)
-class RuntimeIdentity:
-    tenant_id: str
-    cell_id: str
-    principal_id: str
-    channel: str
-    channel_account_id: str
-    session_id: str
-
-
-class IngressAuthenticator:
-    """Verify a canonical HMAC envelope before any identity lookup occurs."""
-
-    def __init__(self, hmac_key: bytes) -> None:
-        if not isinstance(hmac_key, bytes) or len(hmac_key) < 32:
-            raise ValidationError("ingress HMAC key must be at least 32 bytes")
-        self._hmac_key = hmac_key
-
-    @staticmethod
-    def _signed_payload(request: Mapping[str, Any]) -> dict[str, Any]:
-        if not isinstance(request, Mapping):
-            raise ValidationError("ingress request must be an object")
-        if set(request) != {*_SCOPE_FIELDS, "signature"}:
-            raise ValidationError("ingress request fields are invalid")
-        values = {field: request[field] for field in _SCOPE_FIELDS}
-        if not isinstance(values["message"], Mapping):
-            raise ValidationError("ingress message must be an object")
-        return values
-
-    def authenticate(self, request: Mapping[str, Any]) -> AuthenticatedIngress:
-        values = self._signed_payload(request)
-        signature = request["signature"]
-        if not isinstance(signature, str) or not _SIGNATURE_RE.fullmatch(signature):
-            raise AuthenticationError("invalid ingress signature")
-        expected = hmac.new(
-            self._hmac_key, canonical_json(values), hashlib.sha256
-        ).hexdigest()
-        if not hmac.compare_digest(expected, signature):
-            raise AuthenticationError("invalid ingress signature")
-        return AuthenticatedIngress(
-            principal=AuthenticatedPrincipal._verified(values["principal_id"]),
-            claims=IdentityClaims(
-                tenant_id=values["tenant_id"],
-                cell_id=values["cell_id"],
-                channel=values["channel"],
-                channel_account_id=values["channel_account_id"],
-                session_id=values["session_id"],
-            ),
-            message=dict(values["message"]),
-        )
-
-
-class RuntimeIdentityResolver:
-    """Resolve authenticated ingress identity through ``TenantRouter`` only."""
-
-    def __init__(self, router: TenantRouter) -> None:
-        self._router = router
-
-    def resolve(
-        self, principal: AuthenticatedPrincipal, claims: IdentityClaims
-    ) -> RuntimeIdentity:
-        if not isinstance(principal, AuthenticatedPrincipal):
-            raise AuthenticationError("untrusted principal type")
-        try:
-            route: Route = self._router.resolve(
-                channel=claims.channel,
-                channel_account_id=claims.channel_account_id,
-                principal_id=principal.principal_id,
-                session_id=claims.session_id,
-            )
-        except (ScopeError, ValidationError) as exc:
-            raise AuthenticationError("identity is not registered") from None
-        expected = (
-            claims.tenant_id, claims.cell_id, claims.channel,
-            claims.channel_account_id, principal.principal_id, claims.session_id,
-        )
-        actual = (
-            route.tenant_id, route.cell_id, route.channel,
-            route.channel_account_id, route.principal_id, route.session_id,
-        )
-        if actual != expected:
-            raise AuthenticationError("identity claims do not match authoritative route")
-        return RuntimeIdentity(
-            tenant_id=route.tenant_id,
-            cell_id=route.cell_id,
-            principal_id=route.principal_id,
-            channel=route.channel,
-            channel_account_id=route.channel_account_id,
-            session_id=route.session_id or "",
-        )

active-runtime/app/aios_v2r1/memory_scope.py

@@ -1,60 +0,0 @@
-"""Tenant-scoped memory namespace and access policy for AIOS V2R1."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import PurePosixPath
-from typing import Literal
-
-from .tenant_context import ScopeError, ValidationError, require_ident
-
-
-MemoryKind = Literal["session", "profile", "cell", "tenant", "shared_artifact"]
-
-
-@dataclass(frozen=True)
-class MemoryScope:
-    tenant_id: str
-    cell_id: str
-    profile_id: str
-    session_id: str | None
-    kind: MemoryKind
-
-    def __post_init__(self) -> None:
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        for name in ("cell_id", "profile_id"):
-            require_ident(name, getattr(self, name))
-        if self.session_id is not None:
-            require_ident("session_id", self.session_id)
-        if self.kind not in {"session", "profile", "cell", "tenant", "shared_artifact"}:
-            raise ValidationError("invalid memory kind")
-        if self.kind == "session" and self.session_id is None:
-            raise ValidationError("session memory requires session_id")
-
-    @property
-    def namespace(self) -> str:
-        parts = ["tenant", self.tenant_id, "cell", self.cell_id]
-        if self.kind in {"profile", "session"}:
-            parts.extend(["profile", self.profile_id])
-        if self.kind == "session":
-            parts.extend(["session", str(self.session_id)])
-        parts.extend(["memory", self.kind])
-        return str(PurePosixPath(*parts))
-
-    def assert_access(self, requested: "MemoryScope", *, write: bool = False) -> None:
-        if self.tenant_id != requested.tenant_id:
-            raise ScopeError("cross-tenant memory access denied")
-        if self.cell_id != requested.cell_id:
-            raise ScopeError("cross-cell memory access denied")
-        if requested.kind == "shared_artifact":
-            if write:
-                raise ScopeError("shared artifacts are immutable")
-            return
-        if self.profile_id != requested.profile_id and requested.kind in {"profile", "session"}:
-            raise ScopeError("cross-profile memory access denied")
-        if requested.kind == "session" and self.session_id != requested.session_id:
-            raise ScopeError("cross-session memory access denied")
-
-
-def qualify_memory_key(scope: MemoryScope, key: str) -> str:
-    key = require_ident("memory_key", key)
-    return f"{scope.namespace}/{key}"

active-runtime/app/aios_v2r1/message_ledger.py

@@ -1,224 +0,0 @@
-"""Tenant-scoped append-only message ledger and exact quote resolver."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import timedelta
-from contextlib import closing
-import os
-from pathlib import Path
-import sqlite3
-from typing import Iterable
-
-from .tenant_context import (
-    CanonicalMessage,
-    ConflictError,
-    ScopeError,
-    ValidationError,
-    isoformat,
-    normalize_message_id,
-    parse_time,
-    utc_now,
-)
-
-
-@dataclass(frozen=True)
-class LedgerRecord:
-    tenant_id: str
-    cell_id: str
-    channel: str
-    channel_account_id: str
-    peer_id: str
-    direction: str
-    message_id: str
-    event_id: str
-    body: str
-    occurred_at: str
-    expires_at: str
-
-
-class MessageLedger:
-    """Exact-ID ledger.
-
-    The resolver never uses time windows, prefixes, similarity, or nearest-message
-    fallbacks. Ambiguity and absence fail closed.
-    """
-
-    def __init__(self, database: str | Path, *, ttl_days: int = 7) -> None:
-        if not 1 <= ttl_days <= 365:
-            raise ValidationError("ttl_days must be between 1 and 365")
-        self.database = Path(database)
-        self.ttl_days = ttl_days
-        self.database.parent.mkdir(parents=True, exist_ok=True)
-        self._initialize()
-        try:
-            os.chmod(self.database, 0o600)
-        except OSError:
-            pass
-
-    def _connect(self) -> sqlite3.Connection:
-        db = sqlite3.connect(str(self.database), timeout=30)
-        db.row_factory = sqlite3.Row
-        db.execute("PRAGMA journal_mode=WAL")
-        db.execute("PRAGMA synchronous=FULL")
-        db.execute("PRAGMA busy_timeout=30000")
-        return db
-
-    def _initialize(self) -> None:
-        with closing(self._connect()) as connection, connection as db:
-            db.executescript(
-                """
-                CREATE TABLE IF NOT EXISTS message_ledger (
-                    tenant_id TEXT NOT NULL,
-                    cell_id TEXT NOT NULL,
-                    channel TEXT NOT NULL,
-                    channel_account_id TEXT NOT NULL,
-                    peer_id TEXT NOT NULL,
-                    direction TEXT NOT NULL CHECK(direction IN ('inbound','outbound','internal')),
-                    message_id TEXT NOT NULL,
-                    event_id TEXT NOT NULL,
-                    body TEXT NOT NULL,
-                    occurred_at TEXT NOT NULL,
-                    expires_at TEXT NOT NULL,
-                    created_at TEXT NOT NULL,
-                    PRIMARY KEY(
-                      tenant_id, cell_id, channel, channel_account_id,
-                      peer_id, direction, message_id
-                    ),
-                    UNIQUE(tenant_id, cell_id, event_id)
-                );
-                CREATE INDEX IF NOT EXISTS idx_message_reply_lookup ON message_ledger(
-                    tenant_id, cell_id, channel, channel_account_id,
-                    peer_id, message_id, expires_at
-                );
-                """
-            )
-
-    def append(self, message: CanonicalMessage) -> LedgerRecord:
-        """Append one exact message through the runtime write path.
-
-        This is intentionally the owner of validation, idempotency, and the
-        immediate SQLite transaction.  Runtime callers must not depend on the
-        legacy ``remember`` compatibility name.
-        """
-        message_id = normalize_message_id(message.message_id)
-        now = utc_now()
-        expires = isoformat(now + timedelta(days=self.ttl_days))
-        key = (
-            message.tenant_id,
-            message.cell_id,
-            message.channel,
-            message.channel_account_id,
-            message.peer_id,
-            message.direction,
-            message_id,
-        )
-        storage_error: ConflictError | None = None
-        try:
-            with closing(self._connect()) as connection, connection as db:
-                db.execute("BEGIN IMMEDIATE")
-                existing = db.execute(
-                    "SELECT event_id, body, occurred_at, expires_at FROM message_ledger "
-                    "WHERE tenant_id=? AND cell_id=? AND channel=? AND channel_account_id=? "
-                    "AND peer_id=? AND direction=? AND message_id=?",
-                    key,
-                ).fetchone()
-                if existing:
-                    if existing["body"] != message.body:
-                        db.rollback()
-                        raise ConflictError("message ID collision with different content")
-                    db.commit()
-                    return LedgerRecord(
-                        *key, existing["event_id"], existing["body"],
-                        existing["occurred_at"], existing["expires_at"],
-                    )
-                db.execute(
-                    "INSERT INTO message_ledger VALUES(?,?,?,?,?,?,?,?,?,?,?,?)",
-                    (*key, message.event_id, message.body, message.occurred_at, expires, isoformat(now)),
-                )
-                db.commit()
-        except sqlite3.Error:
-            storage_error = ConflictError("ledger storage unavailable")
-        if storage_error is not None:
-            # Raise outside the sqlite exception handler so callers cannot inspect
-            # a driver exception through __cause__ or __context__.
-            raise storage_error
-        return LedgerRecord(*key, message.event_id, message.body, message.occurred_at, expires)
-
-    def remember(self, message: CanonicalMessage) -> LedgerRecord:
-        """Backward-compatible API wrapper for callers outside the runtime path."""
-        return self.append(message)
-
-    def matches(self, message: CanonicalMessage) -> bool:
-        """Whether this exact message is already durably represented."""
-        message_id = normalize_message_id(message.message_id)
-        with closing(self._connect()) as connection, connection as db:
-            row = db.execute(
-                "SELECT event_id, body FROM message_ledger WHERE tenant_id=? AND "
-                "cell_id=? AND channel=? AND channel_account_id=? AND peer_id=? "
-                "AND direction=? AND message_id=?",
-                (
-                    message.tenant_id, message.cell_id, message.channel,
-                    message.channel_account_id, message.peer_id, message.direction,
-                    message_id,
-                ),
-            ).fetchone()
-        return bool(row and row["event_id"] == message.event_id and row["body"] == message.body)
-
-    def remove(self, record: LedgerRecord) -> None:
-        """Compensate a newly appended record if a later ingress step fails."""
-        with closing(self._connect()) as connection, connection as db:
-            db.execute(
-                "DELETE FROM message_ledger WHERE tenant_id=? AND cell_id=? AND "
-                "channel=? AND channel_account_id=? AND peer_id=? AND direction=? "
-                "AND message_id=? AND event_id=?",
-                (
-                    record.tenant_id, record.cell_id, record.channel,
-                    record.channel_account_id, record.peer_id, record.direction,
-                    record.message_id, record.event_id,
-                ),
-            )
-
-    def resolve_quote(self, message: CanonicalMessage) -> str:
-        if message.quoted_body is not None:
-            return message.quoted_body
-        if message.reply_to_message_id is None:
-            raise ScopeError("quoted_text_unavailable")
-        reply_id = normalize_message_id(
-            message.reply_to_message_id,
-            field_name="reply_to_message_id",
-        )
-        with closing(self._connect()) as connection, connection as db:
-            rows = db.execute(
-                "SELECT direction, body, event_id FROM message_ledger "
-                "WHERE tenant_id=? AND cell_id=? AND channel=? AND channel_account_id=? "
-                "AND peer_id=? AND message_id=? AND expires_at>?",
-                (
-                    message.tenant_id,
-                    message.cell_id,
-                    message.channel,
-                    message.channel_account_id,
-                    message.peer_id,
-                    reply_id,
-                    isoformat(),
-                ),
-            ).fetchall()
-        if len(rows) == 1:
-            return str(rows[0]["body"])
-        if len(rows) > 1:
-            raise ConflictError("ambiguous reply ID across message directions")
-        raise ScopeError("quoted_text_unavailable")
-
-    def purge_expired(self) -> int:
-        with closing(self._connect()) as connection, connection as db:
-            cursor = db.execute(
-                "DELETE FROM message_ledger WHERE expires_at<=?", (isoformat(),)
-            )
-            return cursor.rowcount
-
-    def integrity_check(self) -> str:
-        with closing(self._connect()) as connection, connection as db:
-            return str(db.execute("PRAGMA integrity_check").fetchone()[0])
-
-    def count(self) -> int:
-        with closing(self._connect()) as connection, connection as db:
-            return int(db.execute("SELECT count(*) FROM message_ledger").fetchone()[0])

active-runtime/app/aios_v2r1/router.py

@@ -1,336 +0,0 @@
-"""Authoritative tenant registry and fail-closed message router."""
-from __future__ import annotations
-
-from contextlib import contextmanager
-from contextlib import closing
-from dataclasses import dataclass
-from datetime import datetime, timedelta
-import sqlite3
-from pathlib import Path
-from typing import Callable, Iterator
-
-from .tenant_context import (
-    CanonicalMessage,
-    ConflictError,
-    ScopeError,
-    TenantContext,
-    ValidationError,
-    isoformat,
-    parse_time,
-    require_ident,
-    utc_now,
-)
-
-
-@dataclass(frozen=True)
-class Route:
-    tenant_id: str
-    cell_id: str
-    channel: str
-    channel_account_id: str
-    principal_id: str
-    session_id: str | None
-
-
-class TenantRouter:
-    """SQLite-backed routing registry.
-
-    Channel accounts are authoritative tenant ownership boundaries. Principal and
-    session bindings may narrow a route, but can never move traffic to another
-    tenant or Cell.
-    """
-
-    def __init__(
-        self, database: str | Path, *, clock: Callable[[], datetime] = utc_now
-    ) -> None:
-        self.database = str(database)
-        self._clock = clock
-        self._initialize()
-
-    def _connect(self) -> sqlite3.Connection:
-        connection = sqlite3.connect(self.database, timeout=30, isolation_level=None)
-        connection.row_factory = sqlite3.Row
-        connection.execute("PRAGMA foreign_keys=ON")
-        connection.execute("PRAGMA journal_mode=WAL")
-        connection.execute("PRAGMA synchronous=FULL")
-        connection.execute("PRAGMA busy_timeout=30000")
-        return connection
-
-    @contextmanager
-    def _transaction(self) -> Iterator[sqlite3.Connection]:
-        connection = self._connect()
-        try:
-            connection.execute("BEGIN IMMEDIATE")
-            yield connection
-            connection.execute("COMMIT")
-        except Exception:
-            connection.execute("ROLLBACK")
-            raise
-        finally:
-            connection.close()
-
-    def _initialize(self) -> None:
-        with closing(self._connect()) as connection, connection as db:
-            db.executescript(
-                """
-                CREATE TABLE IF NOT EXISTS tenants (
-                    tenant_id TEXT PRIMARY KEY,
-                    cell_id TEXT NOT NULL UNIQUE,
-                    status TEXT NOT NULL CHECK(status IN ('active','suspended','retired')),
-                    created_at TEXT NOT NULL,
-                    updated_at TEXT NOT NULL
-                );
-                CREATE TABLE IF NOT EXISTS channel_routes (
-                    channel TEXT NOT NULL,
-                    channel_account_id TEXT NOT NULL,
-                    tenant_id TEXT NOT NULL,
-                    cell_id TEXT NOT NULL,
-                    created_at TEXT NOT NULL,
-                    PRIMARY KEY(channel, channel_account_id),
-                    FOREIGN KEY(tenant_id) REFERENCES tenants(tenant_id)
-                );
-                CREATE TABLE IF NOT EXISTS principal_routes (
-                    channel TEXT NOT NULL,
-                    channel_account_id TEXT NOT NULL,
-                    principal_id TEXT NOT NULL,
-                    tenant_id TEXT NOT NULL,
-                    cell_id TEXT NOT NULL,
-                    created_at TEXT NOT NULL,
-                    PRIMARY KEY(channel, channel_account_id, principal_id),
-                    FOREIGN KEY(channel, channel_account_id)
-                      REFERENCES channel_routes(channel, channel_account_id)
-                );
-                CREATE TABLE IF NOT EXISTS session_bindings (
-                    tenant_id TEXT NOT NULL,
-                    session_id TEXT NOT NULL,
-                    cell_id TEXT NOT NULL,
-                    principal_id TEXT NOT NULL,
-                    expires_at TEXT NOT NULL,
-                    created_at TEXT NOT NULL,
-                    PRIMARY KEY(tenant_id, session_id),
-                    FOREIGN KEY(tenant_id) REFERENCES tenants(tenant_id)
-                );
-                CREATE INDEX IF NOT EXISTS idx_session_expiry
-                  ON session_bindings(expires_at);
-                """
-            )
-
-    def register_tenant(self, tenant_id: str, cell_id: str) -> None:
-        tenant_id = require_ident("tenant_id", tenant_id, tenant=True)
-        cell_id = require_ident("cell_id", cell_id)
-        now = isoformat(self._clock())
-        with self._transaction() as db:
-            row = db.execute(
-                "SELECT cell_id, status FROM tenants WHERE tenant_id=?", (tenant_id,)
-            ).fetchone()
-            if row:
-                if row["cell_id"] != cell_id:
-                    raise ConflictError("tenant already bound to another cell")
-                db.execute(
-                    "UPDATE tenants SET status='active', updated_at=? WHERE tenant_id=?",
-                    (now, tenant_id),
-                )
-                return
-            conflict = db.execute(
-                "SELECT tenant_id FROM tenants WHERE cell_id=?", (cell_id,)
-            ).fetchone()
-            if conflict:
-                raise ConflictError("cell already belongs to another tenant")
-            db.execute(
-                "INSERT INTO tenants VALUES(?,?,?,?,?)",
-                (tenant_id, cell_id, "active", now, now),
-            )
-
-    def set_tenant_status(self, tenant_id: str, status: str) -> None:
-        tenant_id = require_ident("tenant_id", tenant_id, tenant=True)
-        if status not in {"active", "suspended", "retired"}:
-            raise ValidationError("invalid tenant status")
-        with self._transaction() as db:
-            cursor = db.execute(
-                "UPDATE tenants SET status=?, updated_at=? WHERE tenant_id=?",
-                (status, isoformat(self._clock()), tenant_id),
-            )
-            if cursor.rowcount != 1:
-                raise ValidationError("unknown tenant")
-
-    def bind_channel(
-        self,
-        *,
-        tenant_id: str,
-        channel: str,
-        channel_account_id: str,
-    ) -> None:
-        tenant_id = require_ident("tenant_id", tenant_id, tenant=True)
-        channel = require_ident("channel", channel)
-        channel_account_id = require_ident("channel_account_id", channel_account_id)
-        with self._transaction() as db:
-            tenant = db.execute(
-                "SELECT cell_id, status FROM tenants WHERE tenant_id=?", (tenant_id,)
-            ).fetchone()
-            if not tenant or tenant["status"] != "active":
-                raise ValidationError("tenant is not active")
-            existing = db.execute(
-                "SELECT tenant_id, cell_id FROM channel_routes "
-                "WHERE channel=? AND channel_account_id=?",
-                (channel, channel_account_id),
-            ).fetchone()
-            if existing:
-                if existing["tenant_id"] != tenant_id or existing["cell_id"] != tenant["cell_id"]:
-                    raise ConflictError("channel account already belongs to another tenant")
-                return
-            db.execute(
-                "INSERT INTO channel_routes VALUES(?,?,?,?,?)",
-                (channel, channel_account_id, tenant_id, tenant["cell_id"], isoformat(self._clock())),
-            )
-
-    def bind_principal(
-        self,
-        *,
-        tenant_id: str,
-        channel: str,
-        channel_account_id: str,
-        principal_id: str,
-    ) -> None:
-        principal_id = require_ident("principal_id", principal_id)
-        route = self.resolve_channel(channel, channel_account_id)
-        if route.tenant_id != tenant_id:
-            raise ScopeError("principal cannot cross tenant boundary")
-        with self._transaction() as db:
-            existing = db.execute(
-                "SELECT tenant_id, cell_id FROM principal_routes WHERE "
-                "channel=? AND channel_account_id=? AND principal_id=?",
-                (channel, channel_account_id, principal_id),
-            ).fetchone()
-            if existing:
-                if existing["tenant_id"] != tenant_id or existing["cell_id"] != route.cell_id:
-                    raise ConflictError("principal route conflict")
-                return
-            db.execute(
-                "INSERT INTO principal_routes VALUES(?,?,?,?,?,?)",
-                (
-                    channel,
-                    channel_account_id,
-                    principal_id,
-                    tenant_id,
-                    route.cell_id,
-                    isoformat(self._clock()),
-                ),
-            )
-
-    def bind_session(
-        self,
-        *,
-        tenant_id: str,
-        session_id: str,
-        cell_id: str,
-        principal_id: str,
-        ttl_seconds: int = 86400,
-    ) -> None:
-        tenant_id = require_ident("tenant_id", tenant_id, tenant=True)
-        session_id = require_ident("session_id", session_id)
-        cell_id = require_ident("cell_id", cell_id)
-        principal_id = require_ident("principal_id", principal_id)
-        if not 60 <= ttl_seconds <= 31 * 86400:
-            raise ValidationError("invalid session TTL")
-        now = self._clock()
-        expires = isoformat(now + timedelta(seconds=ttl_seconds))
-        with self._transaction() as db:
-            tenant = db.execute(
-                "SELECT cell_id, status FROM tenants WHERE tenant_id=?", (tenant_id,)
-            ).fetchone()
-            if not tenant or tenant["status"] != "active" or tenant["cell_id"] != cell_id:
-                raise ScopeError("session cell does not match tenant")
-            existing = db.execute(
-                "SELECT cell_id, principal_id FROM session_bindings "
-                "WHERE tenant_id=? AND session_id=?",
-                (tenant_id, session_id),
-            ).fetchone()
-            if existing and (
-                existing["cell_id"] != cell_id or existing["principal_id"] != principal_id
-            ):
-                raise ConflictError("session is already bound to another principal or cell")
-            db.execute(
-                "INSERT INTO session_bindings VALUES(?,?,?,?,?,?) "
-                "ON CONFLICT(tenant_id,session_id) DO UPDATE SET expires_at=excluded.expires_at",
-                (tenant_id, session_id, cell_id, principal_id, expires, isoformat(now)),
-            )
-
-    def resolve_channel(self, channel: str, channel_account_id: str) -> Route:
-        channel = require_ident("channel", channel)
-        channel_account_id = require_ident("channel_account_id", channel_account_id)
-        with closing(self._connect()) as connection, connection as db:
-            row = db.execute(
-                "SELECT r.tenant_id, r.cell_id, t.status FROM channel_routes r "
-                "JOIN tenants t ON t.tenant_id=r.tenant_id "
-                "WHERE r.channel=? AND r.channel_account_id=?",
-                (channel, channel_account_id),
-            ).fetchone()
-        if not row:
-            raise ScopeError("unknown channel account")
-        if row["status"] != "active":
-            raise ScopeError("tenant is not active")
-        return Route(row["tenant_id"], row["cell_id"], channel, channel_account_id, "", None)
-
-    def resolve(
-        self,
-        *,
-        channel: str,
-        channel_account_id: str,
-        principal_id: str,
-        session_id: str | None = None,
-    ) -> Route:
-        principal_id = require_ident("principal_id", principal_id)
-        base = self.resolve_channel(channel, channel_account_id)
-        with closing(self._connect()) as connection, connection as db:
-            principal = db.execute(
-                "SELECT tenant_id, cell_id FROM principal_routes WHERE "
-                "channel=? AND channel_account_id=? AND principal_id=?",
-                (channel, channel_account_id, principal_id),
-            ).fetchone()
-            if principal and (
-                principal["tenant_id"] != base.tenant_id or principal["cell_id"] != base.cell_id
-            ):
-                raise ScopeError("principal route violates channel ownership")
-            if session_id is not None:
-                session_id = require_ident("session_id", session_id)
-                session = db.execute(
-                    "SELECT cell_id, principal_id, expires_at FROM session_bindings "
-                    "WHERE tenant_id=? AND session_id=?",
-                    (base.tenant_id, session_id),
-                ).fetchone()
-                if not session:
-                    raise ScopeError("unknown session")
-                if parse_time(session["expires_at"]) <= self._clock():
-                    raise ScopeError("session expired")
-                if session["cell_id"] != base.cell_id or session["principal_id"] != principal_id:
-                    raise ScopeError("session scope mismatch")
-        return Route(
-            base.tenant_id,
-            base.cell_id,
-            channel,
-            channel_account_id,
-            principal_id,
-            session_id,
-        )
-
-    def assert_message_route(self, message: CanonicalMessage) -> Route:
-        route = self.resolve(
-            channel=message.channel,
-            channel_account_id=message.channel_account_id,
-            principal_id=message.principal_id,
-            session_id=message.session_id,
-        )
-        if message.tenant_id != route.tenant_id or message.cell_id != route.cell_id:
-            raise ScopeError("message claims do not match authoritative route")
-        return route
-
-    def assert_context_route(self, context: TenantContext) -> Route:
-        route = self.resolve(
-            channel=context.channel,
-            channel_account_id=context.channel_account_id,
-            principal_id=context.principal_id,
-            session_id=context.session_id,
-        )
-        if context.tenant_id != route.tenant_id or context.cell_id != route.cell_id:
-            raise ScopeError("context claims do not match authoritative route")
-        return route

active-runtime/app/aios_v2r1/runtime.py

@@ -1,136 +0,0 @@
-"""V2R1 runtime composition root for authenticated channel ingress."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Callable, Mapping
-
-from .channel_adapter import ChannelAdapter, IngressResult
-from .identity import (
-    AuthenticationError,
-    IngressAuthenticator,
-    RuntimeIdentity,
-    RuntimeIdentityResolver,
-)
-from .message_ledger import MessageLedger
-from .router import TenantRouter
-from .session_pool import SessionPool
-from .tenant_context import ConflictError, ScopeError, TenantContext, ValidationError, utc_now
-
-
-@dataclass(frozen=True)
-class RuntimeIngressResponse:
-    """Sanitised boundary response; no exception text crosses external ingress."""
-
-    status: str
-    result: IngressResult | None = None
-
-
-class RuntimeWiring:
-    """Own the only external-to-runtime identity binding and message path.
-
-    The request accepted by :meth:`ingest` is an HMAC-authenticated envelope;
-    tenant, cell, channel, account, session, principal, and message claims are
-    signed together.  The envelope is then resolved against ``TenantRouter``.
-    Only that resolved identity can mint the short-lived internal context passed
-    to ``ChannelAdapter``.
-    """
-
-    def __init__(
-        self,
-        *,
-        router: TenantRouter,
-        ledger: MessageLedger,
-        session_pool: SessionPool,
-        channel_adapter: ChannelAdapter,
-        identity_resolver: RuntimeIdentityResolver,
-        ingress_authenticator: IngressAuthenticator,
-        internal_signing_key: bytes,
-        clock: Callable[[], datetime],
-    ) -> None:
-        self.router = router
-        self.ledger = ledger
-        self.session_pool = session_pool
-        self.channel_adapter = channel_adapter
-        self.identity_resolver = identity_resolver
-        self._ingress_authenticator = ingress_authenticator
-        self._internal_signing_key = internal_signing_key
-        self._clock = clock
-
-    @classmethod
-    def create(
-        cls,
-        root: str | Path,
-        *,
-        signing_key: bytes,
-        ingress_hmac_key: bytes | None = None,
-        clock: Callable[[], datetime] = utc_now,
-    ) -> "RuntimeWiring":
-        if not isinstance(signing_key, bytes) or len(signing_key) < 32:
-            raise ValidationError("internal signing key must be at least 32 bytes")
-        # Kept optional for one controlled migration release; the external
-        # request path still cannot supply a TenantContext token.
-        hmac_key = ingress_hmac_key if ingress_hmac_key is not None else signing_key
-        root_path = Path(root)
-        root_path.mkdir(parents=True, exist_ok=True)
-        router = TenantRouter(root_path / "router.sqlite3", clock=clock)
-        ledger = MessageLedger(root_path / "message_ledger.sqlite3")
-        session_pool = SessionPool(router)
-        adapter = ChannelAdapter(
-            router=router,
-            ledger=ledger,
-            session_pool=session_pool,
-            signing_key=signing_key,
-            clock=clock,
-        )
-        return cls(
-            router=router,
-            ledger=ledger,
-            session_pool=session_pool,
-            channel_adapter=adapter,
-            identity_resolver=RuntimeIdentityResolver(router),
-            ingress_authenticator=IngressAuthenticator(hmac_key),
-            internal_signing_key=signing_key,
-            clock=clock,
-        )
-
-    def _issue_internal_context(self, identity: RuntimeIdentity) -> TenantContext:
-        """Mint internal scope only after all claims matched the router route."""
-        return TenantContext.issue(
-            lifetime_seconds=300,
-            now=self._clock(),
-            tenant_id=identity.tenant_id,
-            cell_id=identity.cell_id,
-            principal_id=identity.principal_id,
-            principal_type="authenticated_user",
-            session_id=identity.session_id,
-            task_id=None,
-            channel=identity.channel,
-            channel_account_id=identity.channel_account_id,
-        )
-
-    def ingest(self, *, request: Mapping[str, Any]) -> RuntimeIngressResponse:
-        """Authenticate, resolve, issue internal context, then append and lease.
-
-        The only successful route is ``IngressAuthenticator`` ->
-        ``RuntimeIdentityResolver`` -> ``ChannelAdapter`` ->
-        ``MessageLedger.append`` + ``SessionPool``.  The legacy caller-supplied
-        TenantContext token interface is intentionally not accepted.
-        """
-        try:
-            ingress = self._ingress_authenticator.authenticate(request)
-            identity = self.identity_resolver.resolve(ingress.principal, ingress.claims)
-            context = self._issue_internal_context(identity)
-            result = self.channel_adapter.ingest(
-                token=context.sign(self._internal_signing_key), message=ingress.message
-            )
-            return RuntimeIngressResponse(status="ACCEPTED", result=result)
-        except (AuthenticationError, ScopeError):
-            return RuntimeIngressResponse(status="AUTH_FAILED")
-        except ValidationError:
-            return RuntimeIngressResponse(status="VALIDATION_FAILED")
-        except ConflictError:
-            return RuntimeIngressResponse(status="CONFLICT")
-        except Exception:
-            return RuntimeIngressResponse(status="INTERNAL_ERROR")

active-runtime/app/aios_v2r1/secret_scope.py

@@ -1,33 +0,0 @@
-"""Tenant and Cell scoped secret reference model.
-
-This module never stores secret values. It stores ownership and retrieval scope
-metadata for integration with a real secret broker.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Literal
-
-from .tenant_context import ValidationError, require_ident
-
-
-@dataclass(frozen=True)
-class SecretRef:
-    secret_id: str
-    tenant_id: str
-    cell_id: str
-    kind: Literal["channel", "model", "tool", "runtime"]
-    version: str
-    broker_path: str
-
-    def __post_init__(self) -> None:
-        for name in ("secret_id", "cell_id", "version"):
-            require_ident(name, getattr(self, name))
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        if self.kind not in {"channel", "model", "tool", "runtime"}:
-            raise ValidationError("invalid secret kind")
-        if not self.broker_path.startswith("secret://"):
-            raise ValidationError("secret broker path required")
-
-    def can_be_used_by(self, *, tenant_id: str, cell_id: str) -> bool:
-        return self.tenant_id == tenant_id and self.cell_id == cell_id

active-runtime/app/aios_v2r1/session_pool.py

@@ -1,59 +0,0 @@
-"""Process-local session lease pool backed by TenantRouter authority."""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from threading import RLock
-
-from .router import Route, TenantRouter
-from .tenant_context import ScopeError, TenantContext
-
-
-@dataclass(frozen=True)
-class SessionLease:
-    tenant_id: str
-    cell_id: str
-    principal_id: str
-    session_id: str
-
-
-class SessionPool:
-    """Tracks active leases without creating a second session authority store."""
-
-    def __init__(self, router: TenantRouter) -> None:
-        self._router = router
-        self._leases: dict[tuple[str, str], SessionLease] = {}
-        self._lock = RLock()
-
-    @staticmethod
-    def _assert_route(context: TenantContext, route: Route) -> None:
-        if (
-            route.tenant_id != context.tenant_id
-            or route.cell_id != context.cell_id
-            or route.principal_id != context.principal_id
-            or route.session_id != context.session_id
-        ):
-            raise ScopeError("session lease does not match authoritative route")
-
-    def assert_available(self, context: TenantContext, route: Route) -> None:
-        """Re-resolve the context from the router before a ledger mutation."""
-        self._assert_route(context, route)
-        self._assert_route(context, self._router.assert_context_route(context))
-
-    def acquire(self, context: TenantContext, route: Route) -> SessionLease:
-        self._assert_route(context, route)
-        lease = SessionLease(
-            tenant_id=context.tenant_id,
-            cell_id=context.cell_id,
-            principal_id=context.principal_id,
-            session_id=context.session_id,
-        )
-        with self._lock:
-            return self._leases.setdefault((lease.tenant_id, lease.session_id), lease)
-
-    def release(self, lease: SessionLease) -> None:
-        with self._lock:
-            self._leases.pop((lease.tenant_id, lease.session_id), None)
-
-    def active_count(self) -> int:
-        with self._lock:
-            return len(self._leases)

active-runtime/app/aios_v2r1/tenant_context.py

@@ -1,316 +0,0 @@
-"""Signed tenant context and canonical message contract for AIOS V2R1."""
-from __future__ import annotations
-
-import base64
-from dataclasses import asdict, dataclass
-from datetime import datetime, timedelta, timezone
-import hashlib
-import hmac
-import json
-import re
-import secrets
-from typing import Any, Mapping
-
-VERSION = "V2R1C0"
-MAX_SAFE_INTEGER = 9_007_199_254_740_991
-TENANT_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$")
-IDENT_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9._:@-]{0,126}[A-Za-z0-9])?$")
-
-
-class V2R1Error(RuntimeError):
-    pass
-
-
-class ValidationError(V2R1Error):
-    pass
-
-
-class ScopeError(V2R1Error):
-    pass
-
-
-class ConflictError(V2R1Error):
-    pass
-
-
-def utc_now() -> datetime:
-    return datetime.now(timezone.utc)
-
-
-def isoformat(value: datetime | None = None) -> str:
-    return (value or utc_now()).astimezone(timezone.utc).isoformat()
-
-
-def parse_time(value: str) -> datetime:
-    if not isinstance(value, str) or not value.strip():
-        raise ValidationError("timestamp must be a non-empty string")
-    text = value.strip()
-    if text.endswith("Z"):
-        text = text[:-1] + "+00:00"
-    try:
-        parsed = datetime.fromisoformat(text)
-    except ValueError as exc:
-        raise ValidationError(f"invalid timestamp: {value!r}") from exc
-    if parsed.tzinfo is None:
-        raise ValidationError("timestamp must include timezone")
-    return parsed.astimezone(timezone.utc)
-
-
-def require_ident(name: str, value: Any, *, tenant: bool = False) -> str:
-    if not isinstance(value, str):
-        raise ValidationError(f"{name} must be a string")
-    value = value.strip()
-    pattern = TENANT_RE if tenant else IDENT_RE
-    if not pattern.fullmatch(value):
-        raise ValidationError(f"invalid {name}: {value!r}")
-    return value
-
-
-def normalize_message_id(value: Any, *, field_name: str = "message_id") -> str:
-    if isinstance(value, bool):
-        raise ValidationError(f"{field_name} cannot be boolean")
-    if isinstance(value, str):
-        value = value.strip()
-        if not value or len(value) > 256 or any(ord(ch) < 32 for ch in value):
-            raise ValidationError(f"invalid {field_name}")
-        return value
-    if isinstance(value, int):
-        if abs(value) > MAX_SAFE_INTEGER:
-            raise ValidationError(f"{field_name} is an unsafe numeric ID")
-        return str(value)
-    raise ValidationError(f"{field_name} must be a lossless string or safe integer")
-
-
-def canonical_json(value: Any) -> bytes:
-    return json.dumps(
-        value, ensure_ascii=False, separators=(",", ":"), sort_keys=True
-    ).encode("utf-8")
-
-
-def _b64(data: bytes) -> str:
-    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
-
-
-def _unb64(value: str) -> bytes:
-    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
-
-
-@dataclass(frozen=True)
-class TenantContext:
-    tenant_id: str
-    cell_id: str
-    principal_id: str
-    principal_type: str
-    session_id: str
-    task_id: str | None
-    channel: str
-    channel_account_id: str
-    issued_at: str
-    expires_at: str
-    nonce: str
-
-    def __post_init__(self) -> None:
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        for name in (
-            "cell_id", "principal_id", "principal_type", "session_id",
-            "channel", "channel_account_id", "nonce",
-        ):
-            require_ident(name, getattr(self, name))
-        if self.task_id is not None:
-            require_ident("task_id", self.task_id)
-        issued = parse_time(self.issued_at)
-        expires = parse_time(self.expires_at)
-        if expires <= issued or expires - issued > timedelta(hours=1):
-            raise ValidationError("invalid tenant context lifetime")
-
-    @classmethod
-    def issue(cls, *, lifetime_seconds: int = 300, now: datetime | None = None, **scope: Any) -> "TenantContext":
-        if not 1 <= lifetime_seconds <= 3600:
-            raise ValidationError("lifetime_seconds must be between 1 and 3600")
-        current = (now or utc_now()).astimezone(timezone.utc)
-        return cls(
-            **scope,
-            issued_at=isoformat(current),
-            expires_at=isoformat(current + timedelta(seconds=lifetime_seconds)),
-            nonce=secrets.token_hex(16),
-        )
-
-    def sign(self, key: bytes) -> str:
-        if len(key) < 32:
-            raise ValidationError("signing key must be at least 32 bytes")
-        payload = _b64(canonical_json(asdict(self)))
-        signature = _b64(hmac.new(key, payload.encode("ascii"), hashlib.sha256).digest())
-        return f"{payload}.{signature}"
-
-    @classmethod
-    def verify(
-        cls,
-        token: str,
-        key: bytes,
-        *,
-        now: datetime | None = None,
-        expected_tenant_id: str | None = None,
-        expected_cell_id: str | None = None,
-    ) -> "TenantContext":
-        if len(key) < 32:
-            raise ValidationError("signing key must be at least 32 bytes")
-        try:
-            payload, encoded_signature = token.split(".", 1)
-            actual = _unb64(encoded_signature)
-            if encoded_signature != _b64(actual):
-                raise ValidationError("non-canonical tenant context signature")
-            data = json.loads(_unb64(payload))
-        except Exception as exc:
-            raise ValidationError("malformed tenant context token") from exc
-        expected = hmac.new(key, payload.encode("ascii"), hashlib.sha256).digest()
-        if not hmac.compare_digest(actual, expected):
-            raise ValidationError("tenant context signature mismatch")
-        context = cls(**data)
-        current = (now or utc_now()).astimezone(timezone.utc)
-        if current < parse_time(context.issued_at) - timedelta(seconds=60):
-            raise ValidationError("tenant context issued in future")
-        if current >= parse_time(context.expires_at):
-            raise ValidationError("tenant context expired")
-        if expected_tenant_id and context.tenant_id != expected_tenant_id:
-            raise ScopeError("tenant mismatch")
-        if expected_cell_id and context.cell_id != expected_cell_id:
-            raise ScopeError("cell mismatch")
-        return context
-
-
-@dataclass(frozen=True)
-class CanonicalMessage:
-    tenant_id: str
-    cell_id: str
-    principal_id: str
-    principal_type: str
-    origin_type: str
-    channel: str
-    channel_account_id: str
-    peer_id: str
-    conversation_id: str
-    session_id: str
-    task_id: str | None
-    event_id: str
-    message_id: str
-    reply_to_message_id: str | None
-    direction: str
-    command_capable: bool
-    occurred_at: str
-    received_at: str
-    body: str
-    quoted_body: str | None
-    adapter_name: str
-    adapter_version: str
-    schema_version: str = "aios.message.v1"
-
-    def __post_init__(self) -> None:
-        if self.schema_version != "aios.message.v1":
-            raise ValidationError("unsupported message schema version")
-        require_ident("tenant_id", self.tenant_id, tenant=True)
-        for name in (
-            "cell_id", "principal_id", "principal_type", "origin_type", "channel",
-            "channel_account_id", "peer_id", "conversation_id", "session_id",
-            "event_id", "adapter_name", "adapter_version",
-        ):
-            require_ident(name, getattr(self, name))
-        if self.task_id is not None:
-            require_ident("task_id", self.task_id)
-        normalize_message_id(self.message_id)
-        if self.reply_to_message_id is not None:
-            normalize_message_id(self.reply_to_message_id, field_name="reply_to_message_id")
-        if self.direction not in {"inbound", "outbound", "internal"}:
-            raise ValidationError("invalid direction")
-        if not isinstance(self.command_capable, bool):
-            raise ValidationError("command_capable must be boolean")
-        parse_time(self.occurred_at)
-        parse_time(self.received_at)
-        if not isinstance(self.body, str):
-            raise ValidationError("body must be a string")
-        if self.quoted_body is not None and not isinstance(self.quoted_body, str):
-            raise ValidationError("quoted_body must be a string or null")
-
-    @classmethod
-    def from_mapping(cls, data: Mapping[str, Any]) -> "CanonicalMessage":
-        content = data.get("content") or {}
-        adapter = data.get("adapter") or {}
-        if not isinstance(content, Mapping) or not isinstance(adapter, Mapping):
-            raise ValidationError("content and adapter must be objects")
-        values = dict(data)
-        return cls(
-            schema_version=values.get("schema_version", "aios.message.v1"),
-            tenant_id=values["tenant_id"],
-            cell_id=values["cell_id"],
-            principal_id=values["principal_id"],
-            principal_type=values["principal_type"],
-            origin_type=values["origin_type"],
-            channel=values["channel"],
-            channel_account_id=values["channel_account_id"],
-            peer_id=values["peer_id"],
-            conversation_id=values["conversation_id"],
-            session_id=values["session_id"],
-            task_id=values.get("task_id"),
-            event_id=values["event_id"],
-            message_id=normalize_message_id(values["message_id"]),
-            reply_to_message_id=(
-                normalize_message_id(values["reply_to_message_id"], field_name="reply_to_message_id")
-                if values.get("reply_to_message_id") is not None else None
-            ),
-            direction=values["direction"],
-            command_capable=values["command_capable"],
-            occurred_at=values["occurred_at"],
-            received_at=values["received_at"],
-            body=content.get("body", ""),
-            quoted_body=content.get("quoted_body"),
-            adapter_name=adapter["name"],
-            adapter_version=adapter["version"],
-        )
-
-    def assert_context(self, context: TenantContext) -> None:
-        fields = (
-            "tenant_id", "cell_id", "principal_id", "session_id", "task_id",
-            "channel", "channel_account_id",
-        )
-        mismatches = [name for name in fields if getattr(self, name) != getattr(context, name)]
-        if mismatches:
-            raise ScopeError("message/context mismatch: " + ", ".join(mismatches))
-
-    @property
-    def is_authenticated_human_command(self) -> bool:
-        return (
-            self.direction == "inbound"
-            and self.command_capable
-            and self.principal_type == "authenticated_user"
-            and self.origin_type == "channel_user"
-        )
-
-
-@dataclass(frozen=True)
-class PolicyDecision:
-    allowed: bool
-    approval_required: bool
-    code: str
-    reason: str
-
-
-READ_ONLY_TOOLS = frozenset({
-    "read", "grep", "glob", "find", "ls", "web_search", "web_fetch",
-    "memory_search", "sessions_list", "sessions_history", "session_status",
-})
-
-
-def evaluate_tool_call(tool_name: str, message: CanonicalMessage) -> PolicyDecision:
-    normalized = tool_name.strip().lower() if isinstance(tool_name, str) else ""
-    if not normalized:
-        return PolicyDecision(False, False, "invalid_tool", "tool name missing")
-    if normalized in READ_ONLY_TOOLS:
-        return PolicyDecision(True, False, "read_only", "read-only operation")
-    if not message.is_authenticated_human_command:
-        return PolicyDecision(
-            False, False, "origin_denied",
-            "side effects require an authenticated current human command",
-        )
-    return PolicyDecision(
-        True, True, "approval_required",
-        "authenticated human side effect requires explicit approval",
-    )

agents/registry.yaml

@@ -1,7 +1,8 @@
+<<<<<<< HEAD
 # AIOS Agent Command Plane Registry
 # Git is the single source of truth for all agent commands.
 version: 1.0.0
-created_at: "2026-07-08T15:20:00+08:00"
+created_at: 2026-07-08T15:20:00+08:00
 baseline: V1R3C1
 
 commands:
@@ -11,22 +12,6 @@ commands:
   completed_path: "agents/commands/completed/"
   failed_path: "agents/commands/failed/"
 
-directories:
-  commands/active: "New commands pending execution — Git is the only entry point"
-  commands/running: "Commands currently being executed by an agent"
-  commands/completed: "Commands that finished successfully — moved here on success"
-  commands/failed: "Commands that finished with errors — moved here on failure"
-
-lifecycle:
-  new: active/
-  running: running/
-  success: completed/
-  failure: failed/
-
-# Command lifecycle state machine:
-# active/ → locked & moved to running/ → execute → success → completed/
-#                                                          → failure → failed/
-
 policies:
   path: "agents/policies/"
   source: "git"
@@ -53,4 +38,30 @@ audit:
   agent_runs: "audit/agent-runs/"
   version_history: "audit/version-history/"
   command_history: "audit/command-history/"
-  interaction_history: "audit/interaction-history/"
+=======
+# AIOS Agent Command Registry
+# Git is the single source of truth for all agent commands.
+
+registry_version: 1.0.0
+created_at: "2026-07-08T15:44:00+08:00"
+baseline: V1R3C1
+
+directories:
+  commands/active:    "New commands pending execution — Git is the only entry point"
+  commands/running:   "Commands currently being executed by an agent"
+  commands/completed: "Commands that finished successfully — moved here on success"
+  commands/failed:    "Commands that finished with errors — moved here on failure"
+
+state: agents/state/
+policies: agents/policies/
+
+lifecycle:
+  new:     active/
+  running: running/
+  success: completed/
+  failure: failed/
+
+# Command lifecycle state machine:
+# active/ → locked & moved to running/ → execute → success → completed/
+#                                                          → failure → failed/
+>>>>>>> 4d18ee0 (feat(cmd): enable Agent Command Plane, audit plane, and Web UI dashboard)

automation/a0_unattended_loop_probe.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Prove two real central-decision to Gateway-dispatch to Codex lifecycle cycles."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sqlite3
+import time
+import uuid
+
+from health_probe_common import (
+    ProbeError, gateway_base, load_config, read_token, request_json, state_version,
+)
+
+
+REQUIRED_MARKERS = {"CODEX_AUTO_CLAIM", "TASK_STARTED", "TASK_EXECUTED", "TASK_ENDED", "EVENT_POSTED"}
+
+
+def marker_counts(path: Path, command_id: str) -> dict[str, int]:
+    counts = {marker: 0 for marker in REQUIRED_MARKERS}
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            marker = record.get("marker")
+            if record.get("command_id") == command_id and marker in counts:
+                counts[marker] += 1
+    return counts
+
+
+def watcher_status(database: Path, command_id: str) -> str | None:
+    with sqlite3.connect(f"file:{database}?mode=ro", uri=True, timeout=2) as db:
+        row = db.execute("SELECT status FROM commands WHERE command_id=?", (command_id,)).fetchone()
+    return None if row is None else str(row[0])
+
+
+def wait_for_cycle(config: dict[str, object], token: str, cycle: int) -> tuple[str, str]:
+    endpoint = str(config["gateway_event_url"])
+    project = str(config["project_key"])
+    event_id = f"a0-cycle-{cycle}-" + uuid.uuid4().hex
+    work_unit_id = f"A0-CODEX-CYCLE-{cycle}-" + uuid.uuid4().hex[:16]
+    event = {
+        "schema_version": 1,
+        "project_key": project,
+        "contract_commit": config["contract_commit"],
+        "event_id": event_id,
+        "source_agent": "system",
+        "event_type": "a0_unattended_acceptance_requested",
+        "work_unit_id": work_unit_id,
+        "status": "READY",
+        "state_version": state_version(endpoint, project, token),
+        "implementation_commit": None,
+        "result_commit": None,
+        "blocker": None,
+        "evidence_refs": [],
+        "payload": {
+            "acceptance_contract": {
+                "verdict": "DISPATCH",
+                "work_unit_id": work_unit_id,
+                "track_id": "A0_AUTOMATION",
+                "gate_id": "A0_AUTOMATION_CLOSED",
+                "primary_agent": "codex",
+                "fallback_agent": "openclaw",
+                "clean_base_commit": config["probe_clean_base_commit"],
+                "allowed_paths": [],
+                "required_checks": ["acceptance_probe"],
+                "forbidden_operations": ["production_mutation", "git_mutation"],
+                "instruction": "Run the fixed side-effect-free acceptance probe only.",
+            }
+        },
+    }
+    request_json(endpoint, token, method="POST", payload=event)
+    deadline = time.monotonic() + int(config["cycle_timeout_seconds"])
+    channel = None
+    while time.monotonic() < deadline:
+        _, status = request_json(endpoint + "/" + event_id, token)
+        if status.get("status") == "TRIGGER_FAILED":
+            raise ProbeError("central_trigger_failed")
+        if status.get("status") == "DECIDED" and status.get("decision_applied") is True:
+            channel = status.get("trigger_channel")
+            break
+        time.sleep(float(config["poll_interval_seconds"]))
+    if channel not in {"workspace_agent", "responses_api"}:
+        raise ProbeError("central_decision_timeout")
+
+    database = Path(str(config["codex_database_path"]))
+    audit = Path(str(config["codex_audit_log"]))
+    while time.monotonic() < deadline:
+        if database.exists() and audit.exists() and watcher_status(database, work_unit_id) == "COMPLETED":
+            counts = marker_counts(audit, work_unit_id)
+            if all(counts[marker] == 1 for marker in REQUIRED_MARKERS):
+                for suffix in ("started", "ended"):
+                    _, lifecycle = request_json(endpoint + "/" + work_unit_id + ":" + suffix, token)
+                    if lifecycle.get("event_id") != work_unit_id + ":" + suffix:
+                        raise ProbeError("gateway_lifecycle_missing")
+                return event_id, str(channel)
+        time.sleep(float(config["poll_interval_seconds"]))
+    raise ProbeError("gateway_dispatch_or_codex_lifecycle_timeout")
+
+
+def project_summaries_since(database: Path, project: str, since: int) -> int:
+    with sqlite3.connect(f"file:{database}?mode=ro", uri=True, timeout=2) as db:
+        row = db.execute(
+            "SELECT COUNT(*) FROM lifecycle WHERE project_key=? AND kind='PROJECT_SUMMARY' AND created_at>=?",
+            (project, since),
+        ).fetchone()
+    return 0 if row is None else int(row[0])
+
+
+def run(config_path: Path) -> int:
+    config = load_config(config_path)
+    endpoint = str(config["gateway_event_url"])
+    gateway_base(endpoint)
+    token = read_token(Path(str(config["gateway_token_file"])))
+    started = int(time.time())
+    results = [wait_for_cycle(config, token, cycle) for cycle in (1, 2)]
+    if len({item[0] for item in results}) != 2:
+        raise ProbeError("duplicate_cycle_event")
+    if project_summaries_since(
+        Path(str(config["gateway_database_path"])), str(config["project_key"]), started
+    ) < 2:
+        raise ProbeError("project_summary_not_persisted")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", required=True, type=Path)
+    args = parser.parse_args()
+    try:
+        return run(args.config)
+    except (KeyError, OSError, ProbeError, sqlite3.Error, ValueError):
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

automation/central_gpt_health_probe.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Prove a real central-model decision through the authenticated Gateway."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+import time
+from pathlib import Path
+import uuid
+
+from health_probe_common import (
+    ProbeError, atomic_receipt, gateway_base, load_config, read_token,
+    request_json, state_version,
+)
+
+PENDING_PATH = Path("/run/aios-health/central-gpt.pending.json")
+
+
+def _load_pending(
+    path: Path, contract: str, *, owners: set[int] | None = None
+) -> tuple[str, int] | None:
+    allowed_owners = {0} if owners is None else owners
+    if not path.exists():
+        return None
+    info = path.lstat()
+    if (
+        not path.is_absolute()
+        or stat.S_ISLNK(info.st_mode)
+        or not stat.S_ISREG(info.st_mode)
+        or stat.S_IMODE(info.st_mode) & ~0o640
+        or (os.name == "posix" and info.st_uid not in allowed_owners)
+        or path.resolve(strict=True) != Path(os.path.abspath(path))
+    ):
+        raise ProbeError("unsafe_pending_marker")
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict) or set(value) != {"contract_commit", "event_id", "state_version"}:
+        raise ProbeError("invalid_pending_marker")
+    event_id = value["event_id"]
+    version = value["state_version"]
+    if (
+        value["contract_commit"] != contract
+        or not isinstance(event_id, str)
+        or not event_id.startswith("health-central-")
+        or len(event_id) != 47
+        or not isinstance(version, int)
+        or version < 0
+    ):
+        raise ProbeError("invalid_pending_marker")
+    return event_id, version
+
+
+def _clear_pending(path: Path) -> None:
+    if not path.exists():
+        return
+    info = path.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        raise ProbeError("unsafe_pending_marker")
+    path.unlink()
+
+
+def _safe_reason(exc: BaseException) -> str:
+    reason = str(exc)
+    if reason and len(reason) <= 64 and all(char.islower() or char.isdigit() or char == "_" for char in reason):
+        return reason
+    return "probe_error"
+
+
+def run(config_path: Path, pending_path: Path = PENDING_PATH) -> int:
+    config = load_config(config_path)
+    endpoint = config["gateway_event_url"]
+    gateway_base(endpoint)
+    token = read_token(Path(config["gateway_token_file"]))
+    project = config["project_key"]
+    contract = config["contract_commit"]
+    pending = _load_pending(pending_path, contract)
+    is_new = pending is None
+    if is_new:
+        event_id = "health-central-" + uuid.uuid4().hex
+        version = state_version(endpoint, project, token)
+        atomic_receipt(
+            pending_path,
+            {"contract_commit": contract, "event_id": event_id, "state_version": version},
+        )
+    else:
+        event_id, version = pending
+    event = {
+        "schema_version": 1,
+        "project_key": project,
+        "contract_commit": contract,
+        "event_id": event_id,
+        "source_agent": "system",
+        "event_type": "central_gpt_health_probe",
+        "work_unit_id": "CENTRAL-GPT-HEALTH",
+        "status": "READY",
+        "state_version": version,
+        "implementation_commit": None,
+        "result_commit": None,
+        "blocker": None,
+        "evidence_refs": [],
+        "payload": {"probe": "side_effect_free", "nonce": event_id},
+    }
+    should_post = is_new
+    if not is_new:
+        try:
+            _, observed = request_json(endpoint + "/" + event_id, token)
+        except ProbeError as exc:
+            if str(exc) != "gateway_http_404":
+                raise
+            should_post = True
+    else:
+        observed = None
+    if should_post:
+        try:
+            status, _ = request_json(endpoint, token, method="POST", payload=event)
+        except ProbeError as exc:
+            if str(exc) == "gateway_fail_closed_409":
+                _clear_pending(pending_path)
+            raise
+        if status not in {200, 202}:
+            raise ProbeError("event_not_accepted")
+        observed = None
+    deadline = time.monotonic() + int(config["central_timeout_seconds"])
+    while time.monotonic() < deadline:
+        _, observed = request_json(endpoint + "/" + event_id, token)
+        if observed.get("status") in {"DECIDED", "TRIGGER_FAILED", "DEAD_LETTER"}:
+            break
+        time.sleep(float(config["poll_interval_seconds"]))
+    if isinstance(observed, dict) and observed.get("status") == "DEAD_LETTER":
+        _clear_pending(pending_path)
+        raise ProbeError("central_event_dead_letter")
+    if not isinstance(observed, dict) or observed.get("status") != "DECIDED" or observed.get("decision_applied") is not True:
+        raise ProbeError("central_decision_not_proven")
+    channel = observed.get("trigger_channel")
+    if channel not in {"workspace_agent", "responses_api", "codex_local"}:
+        raise ProbeError("central_channel_not_proven")
+    _clear_pending(pending_path)
+    now = int(time.time())
+    atomic_receipt(
+        Path(config["central_receipt_path"]),
+        {
+            "subject": "central_gpt",
+            "health": "HEALTHY",
+            "live_probe_succeeded": True,
+            "observed_at_epoch": now,
+            "event_id": event_id,
+            "decision_applied": True,
+            "state_version_after": observed["state_version_after"],
+            "workspace_agent": {"validated_live": channel == "workspace_agent"},
+            "responses_api": {"validated_live": channel == "responses_api"},
+            "codex_local": {"validated_live": channel == "codex_local"},
+        },
+    )
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", required=True, type=Path)
+    args = parser.parse_args()
+    try:
+        return run(args.config)
+    except (KeyError, OSError, ProbeError, ValueError) as exc:
+        print(f"CENTRAL_GPT_PROBE=BLOCKED reason={_safe_reason(exc)}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

automation/codex_central_decision.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+from pathlib import Path
+import time
+import urllib.error
+import urllib.request
+
+from services.aios_orchestrator_gateway.codex_local import CodexLocalClient
+from services.aios_orchestrator_gateway.config import Config
+from services.aios_orchestrator_gateway.models import Event
+from services.aios_orchestrator_gateway.securefs import read_secure_json
+
+
+LOG = logging.getLogger("aios-codex-central-decision")
+
+
+class CodexCentralWorker:
+    def __init__(self, config: Config, client: CodexLocalClient | None = None):
+        if config.central_channel != "codex_local" or config.codex_queue_dir is None:
+            raise RuntimeError("codex_local_not_selected")
+        self.config = config
+        self.client = client or CodexLocalClient()
+        self.root = config.codex_queue_dir
+        self.pending = self.root / "pending"
+        self.processing = self.root / "processing"
+        self.processed = self.root / "processed"
+        self.dead = self.root / "dead-letter"
+
+    def recover_interrupted(self) -> None:
+        for path in sorted(self.processing.glob("*.json")):
+            target = self.pending / path.name
+            if target.exists():
+                path.unlink()
+            else:
+                path.replace(target)
+
+    def run_one(self) -> bool:
+        candidates = sorted(self.pending.glob("*.json"))
+        if not candidates:
+            return False
+        source = candidates[0]
+        claimed = self.processing / source.name
+        try:
+            source.replace(claimed)
+        except FileNotFoundError:
+            return False
+        wrapper = read_secure_json(claimed, expected_uid=None)
+        attempts = wrapper.get("attempts")
+        next_attempt_at = wrapper.get("next_attempt_at")
+        event = Event.from_dict(wrapper.get("event"))
+        if (
+            not isinstance(attempts, int) or attempts < 0
+            or not isinstance(next_attempt_at, (int, float)) or next_attempt_at < 0
+        ):
+            self._dead_letter(claimed)
+            return True
+        if next_attempt_at > time.time():
+            claimed.replace(self.pending / claimed.name)
+            return False
+        if event.contract_commit != self.config.contract_commit:
+            self._dead_letter(claimed)
+            return True
+        try:
+            decision = self.client.decide(event)
+            self._submit(decision.to_dict(), event.event_id)
+        except Exception as exc:
+            LOG.warning("codex_decision_failed category=%s", type(exc).__name__)
+            wrapper["attempts"] = attempts + 1
+            wrapper["next_attempt_at"] = int(time.time()) + self.config.retry_base_seconds
+            self._rewrite(claimed, wrapper)
+            if wrapper["attempts"] > self.config.max_retries:
+                self._dead_letter(claimed)
+            else:
+                claimed.replace(self.pending / claimed.name)
+            return True
+        claimed.replace(self.processed / claimed.name)
+        return True
+
+    def _submit(self, decision: dict, event_id: str) -> None:
+        body = json.dumps(decision, separators=(",", ":"), sort_keys=True).encode()
+        url = f"http://{self.config.host}:{self.config.port}/v1/orchestrator/decisions"
+        request = urllib.request.Request(
+            url, data=body, method="POST",
+            headers={
+                "Authorization": f"Bearer {self.config.callback_token()}",
+                "Content-Type": "application/json",
+                "Idempotency-Key": event_id,
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                if response.status not in {200, 202}:
+                    raise RuntimeError("gateway_decision_rejected")
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise RuntimeError("gateway_decision_unavailable") from exc
+
+    @staticmethod
+    def _rewrite(path: Path, value: dict) -> None:
+        temp = path.with_name(f".{path.name}.tmp-{os.getpid()}")
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o640)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, separators=(",", ":"), sort_keys=True)
+            handle.flush(); os.fsync(handle.fileno())
+        os.replace(temp, path)
+
+    def _dead_letter(self, path: Path) -> None:
+        target = self.dead / path.name
+        if target.exists():
+            path.unlink()
+        else:
+            path.replace(target)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--gateway-config", required=True, type=Path)
+    parser.add_argument("--once", action="store_true")
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s %(message)s")
+    worker = CodexCentralWorker(Config.from_file(args.gateway_config))
+    worker.recover_interrupted()
+    if args.once:
+        worker.run_one()
+        return 0
+    while True:
+        if not worker.run_one():
+            time.sleep(2)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

automation/codex_central_health_probe.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+import time
+import uuid
+
+from services.aios_orchestrator_gateway.codex_local import CodexLocalClient
+from services.aios_orchestrator_gateway.config import Config
+from services.aios_orchestrator_gateway.models import Event
+
+
+def _atomic_receipt(path: Path, value: dict) -> None:
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    fd, temp = tempfile.mkstemp(prefix=".codex-health-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, separators=(",", ":"), sort_keys=True)
+            handle.flush(); os.fsync(handle.fileno())
+        os.chmod(temp, 0o600)
+        os.replace(temp, path)
+    finally:
+        if os.path.exists(temp): os.unlink(temp)
+
+
+def run(config_path: Path, receipt: Path) -> int:
+    config = Config.from_file(config_path)
+    if config.central_channel != "codex_local":
+        raise RuntimeError("codex_local_not_selected")
+    event_id = "codex-health-" + uuid.uuid4().hex
+    event = Event.from_dict({
+        "schema_version": 1, "project_key": config.project_key,
+        "contract_commit": config.contract_commit, "event_id": event_id,
+        "source_agent": "system", "event_type": "codex_local_health_probe",
+        "work_unit_id": "CODEX-LOCAL-HEALTH", "status": "READY",
+        "state_version": 0, "implementation_commit": None,
+        "result_commit": None, "blocker": "health_probe_has_no_release_evidence",
+        "evidence_refs": [], "payload": {"allowed_work_unit_ids": []},
+    })
+    decision = CodexLocalClient().decide(event)
+    if decision.verdict == "DISPATCH" or decision.next_work_units:
+        raise RuntimeError("unsafe_health_decision")
+    _atomic_receipt(receipt, {
+        "subject": "codex_local", "health": "HEALTHY",
+        "codex_login_status": 0, "codex_exec": 0,
+        "decision_schema_valid": True, "observed_at_epoch": int(time.time()),
+    })
+    print("CODEX_CENTRAL_HEALTH=PASS")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--gateway-config", required=True, type=Path)
+    parser.add_argument("--receipt", required=True, type=Path)
+    args = parser.parse_args()
+    try:
+        return run(args.gateway_config, args.receipt)
+    except Exception as exc:
+        reason = str(exc)
+        safe = reason if reason.replace("_", "").isalnum() and len(reason) <= 64 else type(exc).__name__
+        print(f"CODEX_CENTRAL_HEALTH=BLOCKED reason={safe}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

automation/codex_executor_health_probe.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Queue one fixed no-side-effect command and prove the watcher lifecycle."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sqlite3
+import stat
+import time
+import uuid
+
+from health_probe_common import (
+    ProbeError, atomic_receipt, gateway_base, load_config, read_token,
+    request_json, state_version,
+)
+
+
+MARKERS = {"CODEX_AUTO_CLAIM", "TASK_STARTED", "TASK_EXECUTED", "TASK_ENDED", "EVENT_POSTED"}
+
+
+def _write_command(path: Path, value: dict[str, object]) -> None:
+    directory = path.parent
+    info = directory.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) & 0o002:
+        raise ProbeError("unsafe_command_queue")
+    data = (json.dumps(value, sort_keys=True, separators=(",", ":")) + "\n").encode()
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o640)
+    try:
+        os.write(fd, data)
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _status(database: Path, command_id: str) -> str | None:
+    with sqlite3.connect(f"file:{database}?mode=ro", uri=True, timeout=2) as db:
+        row = db.execute("SELECT status FROM commands WHERE command_id=?", (command_id,)).fetchone()
+    return None if row is None else str(row[0])
+
+
+def _markers(path: Path, command_id: str) -> dict[str, int]:
+    result = {name: 0 for name in MARKERS}
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            try:
+                item = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if item.get("command_id") == command_id and item.get("marker") in result:
+                result[item["marker"]] += 1
+    return result
+
+
+def run(config_path: Path) -> int:
+    config = load_config(config_path)
+    endpoint = config["gateway_event_url"]
+    gateway_base(endpoint)
+    token = read_token(Path(config["gateway_token_file"]))
+    command_id = "health-codex-" + uuid.uuid4().hex
+    version = state_version(endpoint, config["project_key"], token)
+    command = {
+        "schema_version": 1,
+        "command_id": command_id,
+        "project_key": config["project_key"],
+        "work_unit_id": command_id,
+        "contract_commit": config["contract_commit"],
+        "state_version": version,
+        "execution": {"kind": "acceptance_probe", "input": "fixed-side-effect-free-health-probe-v1"},
+    }
+    _write_command(Path(config["codex_command_queue"]) / f"{command_id}.json", command)
+    deadline = time.monotonic() + int(config["codex_timeout_seconds"])
+    database = Path(config["codex_database_path"])
+    audit = Path(config["codex_audit_log"])
+    while time.monotonic() < deadline:
+        if database.exists() and audit.exists() and _status(database, command_id) == "COMPLETED":
+            counts = _markers(audit, command_id)
+            if all(counts[name] == 1 for name in MARKERS):
+                for suffix in ("started", "ended"):
+                    _, event = request_json(endpoint + "/" + command_id + ":" + suffix, token)
+                    if event.get("event_id") != command_id + ":" + suffix:
+                        raise ProbeError("gateway_lifecycle_missing")
+                atomic_receipt(
+                    Path(config["codex_receipt_path"]),
+                    {
+                        "subject": "codex",
+                        "health": "HEALTHY",
+                        "live_probe_succeeded": True,
+                        "observed_at_epoch": int(time.time()),
+                        "command_id": command_id,
+                        "lifecycle_complete": True,
+                        "duplicate_side_effects": False,
+                    },
+                )
+                return 0
+        time.sleep(float(config["poll_interval_seconds"]))
+    raise ProbeError("codex_lifecycle_not_proven")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", required=True, type=Path)
+    args = parser.parse_args()
+    try:
+        return run(args.config)
+    except (KeyError, OSError, ProbeError, sqlite3.Error, ValueError):
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

automation/executor_quorum_controller.py

@@ -0,0 +1,940 @@
+#!/usr/bin/env python3
+"""Durable GPT + one-executor quorum and failover controller.
+
+The controller persists decisions before dispatch and never stores credentials.
+Health is accepted only from metadata-only, live-probe receipts.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sqlite3
+import stat
+import subprocess
+import tempfile
+import time
+import urllib.error
+import urllib.request
+import urllib.parse
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Iterable, Mapping
+
+
+ALLOWED_LIFECYCLE_EVENTS = frozenset(
+    {
+        "TASK_DISPATCHED",
+        "TASK_STARTED",
+        "TASK_ENDED",
+        "DECISION_APPLIED",
+        "PROJECT_SUMMARY",
+        "PROJECT_COMPLETED",
+    }
+)
+EXECUTORS = ("openclaw", "codex")
+SECRET_KEYS = frozenset(
+    {
+        "secret",
+        "token",
+        "password",
+        "api_key",
+        "authorization",
+        "credential",
+        "private_key",
+        "environment",
+        "env",
+        "argv",
+        "stdout",
+        "stderr",
+    }
+)
+
+
+class Health(str, Enum):
+    HEALTHY = "HEALTHY"
+    UNHEALTHY = "UNHEALTHY"
+    UNKNOWN = "UNKNOWN"
+
+
+class ControllerError(RuntimeError):
+    """Fail-closed controller error."""
+
+
+class EventConflict(ControllerError):
+    """An event id was reused with a different payload."""
+
+
+class StaleStateVersion(ControllerError):
+    """A dispatch attempted to overwrite a newer task state."""
+
+
+@dataclass(frozen=True)
+class QuorumDecision:
+    allowed: bool
+    priority: str
+    status: str
+    active_executor: str | None
+    standby_executor: str | None
+    repair_required: bool
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def digest_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def _contains_forbidden_key(value: Any) -> bool:
+    if isinstance(value, Mapping):
+        for key, child in value.items():
+            normalized = str(key).strip().lower().replace("-", "_")
+            if normalized in SECRET_KEYS or _contains_forbidden_key(child):
+                return True
+    elif isinstance(value, list):
+        return any(_contains_forbidden_key(item) for item in value)
+    return False
+
+
+def validate_metadata_only(value: Mapping[str, Any]) -> None:
+    if _contains_forbidden_key(value):
+        raise ControllerError("secret-bearing or output-bearing fields are forbidden")
+
+
+def atomic_json_write(path: Path, value: Mapping[str, Any], mode: int = 0o600) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    validate_secure_directory(path.parent)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(path.parent))
+    try:
+        os.fchmod(fd, mode)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(canonical_json(value))
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def validate_secure_directory(path: Path, *, expected_uid: int | None = None) -> None:
+    info = path.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+        raise ControllerError(f"unsafe directory type rejected: {path}")
+    if os.name == "posix" and path.resolve(strict=True) != Path(os.path.abspath(path)):
+        raise ControllerError(f"symlinked directory component rejected: {path}")
+    if os.name == "posix" and info.st_mode & 0o022:
+        raise ControllerError(f"group/world-writable directory rejected: {path}")
+    if expected_uid is not None and info.st_uid != expected_uid:
+        raise ControllerError(f"unexpected owner for directory {path}")
+
+
+def read_secure_json(path: Path, *, expected_uid: int | None = None) -> dict[str, Any]:
+    info = path.lstat()
+    if stat.S_ISLNK(info.st_mode):
+        raise ControllerError(f"symlink rejected: {path}")
+    if not stat.S_ISREG(info.st_mode):
+        raise ControllerError(f"not a regular file: {path}")
+    if os.name == "posix" and info.st_mode & 0o022:
+        raise ControllerError(f"group/world-writable file rejected: {path}")
+    validate_secure_directory(path.parent, expected_uid=expected_uid)
+    if os.name == "posix" and path.resolve(strict=True) != Path(os.path.abspath(path)):
+        raise ControllerError(f"symlinked file component rejected: {path}")
+    if expected_uid is not None and info.st_uid != expected_uid:
+        raise ControllerError(f"unexpected owner for {path}")
+    with path.open("r", encoding="utf-8") as handle:
+        value = json.load(handle)
+    if not isinstance(value, dict):
+        raise ControllerError(f"JSON object required: {path}")
+    validate_metadata_only(value)
+    return value
+
+
+def read_gateway_token(path: Path) -> str:
+    if not path.is_absolute():
+        raise ControllerError("gateway token path must be absolute")
+    try:
+        info = path.lstat()
+    except FileNotFoundError as exc:
+        raise ControllerError("gateway token unavailable") from exc
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        raise ControllerError("gateway token must be a regular non-symlink file")
+    if stat.S_IMODE(info.st_mode) & ~0o640:
+        raise ControllerError("gateway token mode exceeds 0640")
+    if os.name == "posix" and info.st_uid not in {0, os.geteuid()}:
+        raise ControllerError("gateway token owner is not approved")
+    if os.name == "posix" and path.resolve(strict=True) != Path(os.path.abspath(path)):
+        raise ControllerError("gateway token has a symlinked path component")
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(path, flags)
+    try:
+        opened = os.fstat(fd)
+        if not stat.S_ISREG(opened.st_mode) or opened.st_ino != info.st_ino or opened.st_dev != info.st_dev:
+            raise ControllerError("gateway token changed during validation")
+        data = os.read(fd, 16_385)
+        if os.read(fd, 1):
+            raise ControllerError("gateway token too large")
+    finally:
+        os.close(fd)
+    if not data or len(data) > 16_384 or b"\n" in data or b"\r" in data:
+        raise ControllerError("gateway token format rejected")
+    try:
+        token = data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ControllerError("gateway token encoding rejected") from exc
+    if not token:
+        raise ControllerError("gateway token unavailable")
+    return token
+
+
+def validate_health_receipt(
+    receipt: Mapping[str, Any],
+    subject: str,
+    *,
+    now: float | None = None,
+    max_age_seconds: int = 60,
+) -> Health:
+    validate_metadata_only(receipt)
+    if receipt.get("subject") != subject:
+        return Health.UNKNOWN
+    try:
+        health = Health(str(receipt.get("health", "UNKNOWN")))
+    except ValueError:
+        return Health.UNKNOWN
+    if health is not Health.HEALTHY:
+        return health
+    if receipt.get("live_probe_succeeded") is not True:
+        return Health.UNKNOWN
+    observed_at = receipt.get("observed_at_epoch")
+    if not isinstance(observed_at, (int, float)):
+        return Health.UNKNOWN
+    now = time.time() if now is None else now
+    if observed_at > now + 5 or now - observed_at > max_age_seconds:
+        return Health.UNKNOWN
+    if subject == "central_gpt":
+        workspace = receipt.get("workspace_agent")
+        responses = receipt.get("responses_api")
+        workspace_ok = isinstance(workspace, Mapping) and workspace.get("validated_live") is True
+        responses_ok = isinstance(responses, Mapping) and responses.get("validated_live") is True
+        if not (workspace_ok or responses_ok):
+            return Health.UNKNOWN
+    return Health.HEALTHY
+
+
+def choose_executor(workload: str) -> str:
+    if workload in {"complex_code", "security_boundary", "architecture", "complex_code_security_architecture"}:
+        return "codex"
+    return "openclaw"
+
+
+def evaluate_quorum(
+    central_gpt: Health,
+    openclaw: Health,
+    codex: Health,
+    workload: str,
+) -> QuorumDecision:
+    if central_gpt is not Health.HEALTHY:
+        status = "BLOCKED_CENTRAL_GPT_UNKNOWN" if central_gpt is Health.UNKNOWN else "BLOCKED_CENTRAL_GPT_UNHEALTHY"
+        return QuorumDecision(False, "P0", status, None, None, True)
+
+    healthy = [name for name, health in (("openclaw", openclaw), ("codex", codex)) if health is Health.HEALTHY]
+    if not healthy:
+        has_unknown = Health.UNKNOWN in {openclaw, codex}
+        status = "BLOCKED_EXECUTOR_HEALTH_UNKNOWN" if has_unknown else "BLOCKED_NO_HEALTHY_EXECUTOR"
+        return QuorumDecision(False, "P1", status, None, None, True)
+
+    if len(healthy) == 1:
+        active = healthy[0]
+        standby = "codex" if active == "openclaw" else "openclaw"
+        return QuorumDecision(True, "P3", "EXECUTOR_QUORUM_PASS", active, standby, False)
+
+    active = choose_executor(workload)
+    standby = "codex" if active == "openclaw" else "openclaw"
+    return QuorumDecision(True, "NONE", "EXECUTOR_QUORUM_PASS", active, standby, False)
+
+
+class QuorumStore:
+    def __init__(self, path: Path):
+        self.path = path
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        expected_uid = os.geteuid() if os.name == "posix" else None
+        validate_secure_directory(path.parent, expected_uid=expected_uid)
+        if path.exists() or path.is_symlink():
+            info = path.lstat()
+            if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+                raise ControllerError(f"unsafe database path rejected: {path}")
+            if expected_uid is not None and info.st_uid != expected_uid:
+                raise ControllerError(f"unexpected database owner: {path}")
+        self.db = sqlite3.connect(str(path), isolation_level=None, timeout=30)
+        if os.name == "posix":
+            path.chmod(0o600)
+        self.db.row_factory = sqlite3.Row
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA synchronous=FULL")
+        self._initialize()
+
+    def close(self) -> None:
+        self.db.close()
+
+    def _initialize(self) -> None:
+        self.db.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS events (
+                event_id TEXT PRIMARY KEY,
+                payload_digest TEXT NOT NULL,
+                payload_json TEXT NOT NULL,
+                source TEXT NOT NULL,
+                status TEXT NOT NULL,
+                created_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS tasks (
+                work_unit TEXT PRIMARY KEY,
+                contract_commit TEXT NOT NULL,
+                event_id TEXT NOT NULL,
+                state_version INTEGER NOT NULL,
+                workload TEXT NOT NULL,
+                status TEXT NOT NULL,
+                active_executor TEXT,
+                standby_executor TEXT,
+                checkpoint TEXT,
+                lease_owner TEXT,
+                lease_until REAL,
+                interrupted_executor TEXT,
+                recovery_priority TEXT NOT NULL,
+                updated_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS lifecycle (
+                sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+                work_unit TEXT NOT NULL,
+                event_type TEXT NOT NULL,
+                executor TEXT,
+                state_version INTEGER NOT NULL,
+                metadata_json TEXT NOT NULL,
+                created_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS effects (
+                effect_id TEXT PRIMARY KEY,
+                work_unit TEXT NOT NULL,
+                payload_digest TEXT NOT NULL,
+                status TEXT NOT NULL,
+                created_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS outbox (
+                outbox_id TEXT PRIMARY KEY,
+                destination TEXT NOT NULL,
+                payload_digest TEXT NOT NULL,
+                payload_json TEXT NOT NULL,
+                status TEXT NOT NULL,
+                attempts INTEGER NOT NULL DEFAULT 0,
+                next_attempt REAL NOT NULL,
+                created_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS blockers (
+                blocker_key TEXT PRIMARY KEY,
+                occurrences INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                updated_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS observed_refs (
+                ref_name TEXT PRIMARY KEY,
+                oid TEXT NOT NULL,
+                updated_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS summaries (
+                work_unit TEXT PRIMARY KEY,
+                summary_digest TEXT NOT NULL,
+                summary_json TEXT NOT NULL,
+                created_at REAL NOT NULL
+            );
+            CREATE UNIQUE INDEX IF NOT EXISTS lifecycle_once
+            ON lifecycle(work_unit, event_type, COALESCE(executor, ''), state_version);
+            """
+        )
+
+    def ingest_event(self, event_id: str, payload: Mapping[str, Any], source: str) -> bool:
+        validate_metadata_only(payload)
+        encoded = canonical_json(payload)
+        digest = hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+        existing = self.db.execute("SELECT payload_digest FROM events WHERE event_id=?", (event_id,)).fetchone()
+        if existing:
+            if existing["payload_digest"] != digest:
+                self.db.execute("UPDATE events SET status='DEAD_LETTER_CONFLICT' WHERE event_id=?", (event_id,))
+                raise EventConflict(f"event id payload conflict: {event_id}")
+            return False
+        self.db.execute(
+            "INSERT INTO events VALUES(?,?,?,?,?,?)",
+            (event_id, digest, encoded, source, "ACCEPTED", time.time()),
+        )
+        return True
+
+    def upsert_task(
+        self,
+        *,
+        work_unit: str,
+        contract_commit: str,
+        event_id: str,
+        state_version: int,
+        workload: str,
+        decision: QuorumDecision,
+        checkpoint: str | None = None,
+    ) -> str:
+        now = time.time()
+        self.db.execute("BEGIN IMMEDIATE")
+        try:
+            current = self.db.execute("SELECT * FROM tasks WHERE work_unit=?", (work_unit,)).fetchone()
+            if current and state_version < current["state_version"]:
+                raise StaleStateVersion(f"stale state version for {work_unit}")
+            interrupted: str | None = None
+            recovery_priority = decision.priority
+            status = "BLOCKED"
+            if decision.allowed:
+                status = "READY"
+                if current and current["active_executor"] and current["active_executor"] != decision.active_executor:
+                    interrupted = current["active_executor"]
+                    recovery_priority = "P2"
+                    status = "INTERRUPTED_AGENT_FAILOVER"
+                    if checkpoint is None:
+                        checkpoint = current["checkpoint"]
+            if current:
+                if contract_commit != current["contract_commit"] or event_id != current["event_id"]:
+                    raise ControllerError("failover must preserve contract_commit and event_id")
+                if (
+                    current["state_version"] == state_version
+                    and current["active_executor"] == decision.active_executor
+                    and current["status"] in {"RUNNING", "COMPLETED"}
+                ):
+                    self.db.execute("COMMIT")
+                    return current["status"]
+                self.db.execute(
+                    """UPDATE tasks SET state_version=?, workload=?, status=?, active_executor=?,
+                    standby_executor=?, checkpoint=?, interrupted_executor=?, recovery_priority=?, updated_at=? WHERE work_unit=?""",
+                    (
+                        state_version,
+                        workload,
+                        status,
+                        decision.active_executor,
+                        decision.standby_executor,
+                        checkpoint,
+                        interrupted,
+                        recovery_priority,
+                        now,
+                        work_unit,
+                    ),
+                )
+            else:
+                self.db.execute(
+                    "INSERT INTO tasks VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                    (
+                        work_unit,
+                        contract_commit,
+                        event_id,
+                        state_version,
+                        workload,
+                        status,
+                        decision.active_executor,
+                        decision.standby_executor,
+                        checkpoint,
+                        None,
+                        None,
+                        interrupted,
+                        recovery_priority,
+                        now,
+                    ),
+                )
+            self.db.execute("COMMIT")
+            return status
+        except Exception:
+            self.db.execute("ROLLBACK")
+            raise
+
+    def claim_lease(self, work_unit: str, worker: str, ttl_seconds: int, now: float | None = None) -> bool:
+        now = time.time() if now is None else now
+        self.db.execute("BEGIN IMMEDIATE")
+        try:
+            task = self.db.execute(
+                "SELECT active_executor, status, lease_owner, lease_until FROM tasks WHERE work_unit=?",
+                (work_unit,),
+            ).fetchone()
+            if not task:
+                raise ControllerError(f"unknown work unit: {work_unit}")
+            if worker != task["active_executor"]:
+                self.db.execute("ROLLBACK")
+                return False
+            if task["status"] in {"BLOCKED", "COMPLETED"}:
+                self.db.execute("ROLLBACK")
+                return False
+            lease_live = task["lease_owner"] and task["lease_until"] and task["lease_until"] > now
+            if lease_live and task["lease_owner"] != worker:
+                self.db.execute("ROLLBACK")
+                return False
+            self.db.execute(
+                "UPDATE tasks SET lease_owner=?, lease_until=?, status='RUNNING', updated_at=? WHERE work_unit=?",
+                (worker, now + ttl_seconds, now, work_unit),
+            )
+            self.db.execute("COMMIT")
+            return True
+        except Exception:
+            if self.db.in_transaction:
+                self.db.execute("ROLLBACK")
+            raise
+
+    def dispatch_task(
+        self,
+        *,
+        work_unit: str,
+        contract_commit: str,
+        event_id: str,
+        state_version: int,
+        workload: str,
+        decision: QuorumDecision,
+        checkpoint: str | None = None,
+    ) -> str:
+        status = self.upsert_task(
+            work_unit=work_unit,
+            contract_commit=contract_commit,
+            event_id=event_id,
+            state_version=state_version,
+            workload=workload,
+            decision=decision,
+            checkpoint=checkpoint,
+        )
+        if decision.allowed and status != "COMPLETED":
+            metadata = {
+                "contract_commit": contract_commit,
+                "event_id": event_id,
+                "status": status,
+            }
+            self.append_lifecycle(work_unit, "TASK_DISPATCHED", decision.active_executor, state_version, metadata)
+            self.enqueue(
+                f"dispatch:{work_unit}:{state_version}:{decision.active_executor}",
+                "gateway",
+                {"event_type": "TASK_DISPATCHED", "work_unit": work_unit, **metadata},
+            )
+        return status
+
+    def start_task(self, work_unit: str, executor: str, state_version: int, lease_ttl_seconds: int) -> bool:
+        if not self.claim_lease(work_unit, executor, lease_ttl_seconds):
+            return False
+        self.append_lifecycle(work_unit, "TASK_STARTED", executor, state_version, {"status": "RUNNING"})
+        self.enqueue(
+            f"started:{work_unit}:{state_version}:{executor}",
+            "gateway",
+            {"event_type": "TASK_STARTED", "work_unit": work_unit, "executor": executor, "state_version": state_version},
+        )
+        return True
+
+    def end_task(
+        self,
+        work_unit: str,
+        executor: str,
+        state_version: int,
+        result: str,
+        summary: Mapping[str, Any],
+        *,
+        project_completed: bool = False,
+    ) -> None:
+        validate_metadata_only(summary)
+        self.db.execute("BEGIN IMMEDIATE")
+        try:
+            task = self.db.execute("SELECT active_executor,state_version FROM tasks WHERE work_unit=?", (work_unit,)).fetchone()
+            if not task or task["active_executor"] != executor:
+                raise ControllerError("only the active executor may end a task")
+            if task["state_version"] != state_version:
+                raise StaleStateVersion(f"stale state version for {work_unit}")
+            self.db.execute(
+                "UPDATE tasks SET status='COMPLETED', lease_owner=NULL, lease_until=NULL, updated_at=? WHERE work_unit=?",
+                (time.time(), work_unit),
+            )
+            self.append_lifecycle(work_unit, "TASK_ENDED", executor, state_version, {"result": result})
+            self.append_lifecycle(work_unit, "DECISION_APPLIED", executor, state_version, {"result": result})
+            self.append_lifecycle(work_unit, "PROJECT_SUMMARY", executor, state_version, summary)
+            if project_completed:
+                self.append_lifecycle(work_unit, "PROJECT_COMPLETED", executor, state_version, {"result": result})
+            self.persist_summary(work_unit, summary)
+            outbound = (
+                ("TASK_ENDED", {"result": result}),
+                ("DECISION_APPLIED", {"result": result}),
+                ("PROJECT_SUMMARY", dict(summary)),
+            )
+            for event_type, metadata in outbound:
+                self.enqueue(
+                    f"{event_type.lower()}:{work_unit}:{state_version}:{executor}",
+                    "gateway",
+                    {
+                        "event_type": event_type,
+                        "work_unit": work_unit,
+                        "executor": executor,
+                        "state_version": state_version,
+                        **metadata,
+                    },
+                )
+            if project_completed:
+                self.enqueue(
+                    f"project_completed:{work_unit}:{state_version}:{executor}",
+                    "gateway",
+                    {
+                        "event_type": "PROJECT_COMPLETED",
+                        "work_unit": work_unit,
+                        "executor": executor,
+                        "state_version": state_version,
+                        "result": result,
+                    },
+                )
+            self.db.execute("COMMIT")
+        except Exception:
+            if self.db.in_transaction:
+                self.db.execute("ROLLBACK")
+            raise
+
+    def record_effect(self, effect_id: str, work_unit: str, payload: Mapping[str, Any]) -> bool:
+        validate_metadata_only(payload)
+        digest = digest_json(payload)
+        existing = self.db.execute("SELECT payload_digest FROM effects WHERE effect_id=?", (effect_id,)).fetchone()
+        if existing:
+            if existing["payload_digest"] != digest:
+                raise EventConflict(f"effect id payload conflict: {effect_id}")
+            return False
+        self.db.execute(
+            "INSERT INTO effects VALUES(?,?,?,?,?)",
+            (effect_id, work_unit, digest, "COMPLETED", time.time()),
+        )
+        return True
+
+    def append_lifecycle(
+        self,
+        work_unit: str,
+        event_type: str,
+        executor: str | None,
+        state_version: int,
+        metadata: Mapping[str, Any],
+    ) -> None:
+        if event_type not in ALLOWED_LIFECYCLE_EVENTS:
+            raise ControllerError(f"unsupported lifecycle event: {event_type}")
+        validate_metadata_only(metadata)
+        self.db.execute(
+            "INSERT OR IGNORE INTO lifecycle(work_unit,event_type,executor,state_version,metadata_json,created_at) VALUES(?,?,?,?,?,?)",
+            (work_unit, event_type, executor, state_version, canonical_json(metadata), time.time()),
+        )
+
+    def persist_summary(self, work_unit: str, summary: Mapping[str, Any]) -> None:
+        validate_metadata_only(summary)
+        encoded = canonical_json(summary)
+        digest = hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+        self.db.execute(
+            "INSERT OR REPLACE INTO summaries VALUES(?,?,?,?)",
+            (work_unit, digest, encoded, time.time()),
+        )
+
+    def enqueue(self, outbox_id: str, destination: str, payload: Mapping[str, Any]) -> bool:
+        validate_metadata_only(payload)
+        encoded = canonical_json(payload)
+        digest = hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+        existing = self.db.execute("SELECT payload_digest FROM outbox WHERE outbox_id=?", (outbox_id,)).fetchone()
+        if existing:
+            if existing["payload_digest"] != digest:
+                raise EventConflict(f"outbox id payload conflict: {outbox_id}")
+            return False
+        self.db.execute(
+            "INSERT INTO outbox VALUES(?,?,?,?,?,?,?,?)",
+            (outbox_id, destination, digest, encoded, "PENDING", 0, time.time(), time.time()),
+        )
+        return True
+
+    def record_blocker(self, blocker_key: str, threshold: int) -> str:
+        now = time.time()
+        row = self.db.execute("SELECT occurrences FROM blockers WHERE blocker_key=?", (blocker_key,)).fetchone()
+        occurrences = (row["occurrences"] if row else 0) + 1
+        status = "DEAD_LETTER" if occurrences > threshold else "RETRY"
+        self.db.execute(
+            "INSERT INTO blockers VALUES(?,?,?,?) ON CONFLICT(blocker_key) DO UPDATE SET occurrences=excluded.occurrences,status=excluded.status,updated_at=excluded.updated_at",
+            (blocker_key, occurrences, status, now),
+        )
+        return status
+
+    def deliver_outbox(self, sender: Callable[[Mapping[str, Any]], None], max_attempts: int, now: float | None = None) -> tuple[int, int]:
+        now = time.time() if now is None else now
+        sent = 0
+        failed = 0
+        rows = self.db.execute(
+            "SELECT * FROM outbox WHERE status='PENDING' AND next_attempt<=? ORDER BY created_at,outbox_id LIMIT 100",
+            (now,),
+        ).fetchall()
+        for row in rows:
+            payload = json.loads(row["payload_json"])
+            validate_metadata_only(payload)
+            try:
+                sender(payload)
+            except Exception:
+                attempts = row["attempts"] + 1
+                status = "DEAD_LETTER" if attempts >= max_attempts else "PENDING"
+                delay = min(300, 2 ** min(attempts, 8))
+                self.db.execute(
+                    "UPDATE outbox SET attempts=?,status=?,next_attempt=? WHERE outbox_id=?",
+                    (attempts, status, now + delay, row["outbox_id"]),
+                )
+                failed += 1
+            else:
+                self.db.execute(
+                    "UPDATE outbox SET attempts=attempts+1,status='SENT',next_attempt=? WHERE outbox_id=?",
+                    (now, row["outbox_id"]),
+                )
+                sent += 1
+        return sent, failed
+
+    def observe_ref(self, ref_name: str, oid: str) -> bool:
+        row = self.db.execute("SELECT oid FROM observed_refs WHERE ref_name=?", (ref_name,)).fetchone()
+        changed = row is not None and row["oid"] != oid
+        self.db.execute(
+            "INSERT INTO observed_refs VALUES(?,?,?) ON CONFLICT(ref_name) DO UPDATE SET oid=excluded.oid,updated_at=excluded.updated_at",
+            (ref_name, oid, time.time()),
+        )
+        return changed
+
+
+def spool_after_http_failure(
+    sender: Callable[[Mapping[str, Any]], None],
+    payload: Mapping[str, Any],
+    spool_dir: Path,
+    event_id: str,
+) -> bool:
+    validate_metadata_only(payload)
+    try:
+        sender(payload)
+        return True
+    except Exception:
+        atomic_json_write(spool_dir / f"{event_id}.json", {"event_id": event_id, "payload": dict(payload)})
+        return False
+
+
+def poll_file_inbox(store: QuorumStore, inbox_dir: Path) -> int:
+    if not inbox_dir.exists():
+        return 0
+    validate_secure_directory(inbox_dir, expected_uid=os.geteuid() if os.name == "posix" else None)
+    count = 0
+    for path in sorted(inbox_dir.glob("*.json")):
+        if path.is_symlink():
+            raise ControllerError(f"symlink inbox entry rejected: {path}")
+        item = read_secure_json(path, expected_uid=os.geteuid() if os.name == "posix" else None)
+        event_id = item.get("event_id")
+        payload = item.get("payload")
+        if not isinstance(event_id, str) or not isinstance(payload, dict):
+            raise ControllerError(f"invalid inbox envelope: {path}")
+        if store.ingest_event(event_id, payload, "file-inbox"):
+            count += 1
+        path.unlink()
+    return count
+
+
+def resolve_git_ref(repo: Path, ref_name: str) -> str:
+    if not repo.is_absolute():
+        raise ControllerError("Git repository path must be absolute")
+    info = repo.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+        raise ControllerError("Git repository must be a non-symlink directory")
+    if os.name == "posix" and repo.resolve(strict=True) != Path(os.path.abspath(repo)):
+        raise ControllerError("Git repository has a symlinked path component")
+    if os.name == "posix" and info.st_mode & 0o002:
+        raise ControllerError("world-writable Git repository rejected")
+    try:
+        completed = subprocess.run(
+            [
+                "git",
+                "-c",
+                f"safe.directory={repo}",
+                "-C",
+                str(repo),
+                "rev-parse",
+                "--verify",
+                ref_name,
+            ],
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as exc:
+        raise ControllerError("Git ref unavailable") from exc
+    oid = completed.stdout.strip()
+    if len(oid) != 40 or any(character not in "0123456789abcdef" for character in oid.lower()):
+        raise ControllerError("invalid Git object id")
+    return oid
+
+
+def poll_git_refs(
+    store: QuorumStore,
+    repo: Path,
+    refs: Iterable[str],
+    resolver: Callable[[Path, str], str] = resolve_git_ref,
+) -> int:
+    changed = 0
+    for ref_name in refs:
+        if not ref_name.startswith("refs/") or ".." in ref_name or ref_name.endswith("/"):
+            raise ControllerError(f"invalid Git ref: {ref_name}")
+        oid = resolver(repo, ref_name)
+        if store.observe_ref(ref_name, oid):
+            event_id = f"gitref:{ref_name}:{oid}"
+            if store.ingest_event(event_id, {"ref": ref_name, "oid": oid}, "git-ref-poll"):
+                changed += 1
+    return changed
+
+
+def responses_fallback_allowed(
+    workspace_agent_ok: bool,
+    receipt: Mapping[str, Any],
+    *,
+    now: float | None = None,
+) -> bool:
+    validate_metadata_only(receipt)
+    if workspace_agent_ok:
+        return False
+    responses = receipt.get("responses_api")
+    return (
+        validate_health_receipt(receipt, "central_gpt", now=now) is Health.HEALTHY
+        and isinstance(responses, Mapping)
+        and responses.get("validated_live") is True
+    )
+
+
+def _validate_gateway_url(url: str) -> None:
+    parsed = urllib.parse.urlparse(url)
+    if (
+        parsed.scheme != "http"
+        or parsed.hostname != "127.0.0.1"
+        or parsed.port != 18920
+        or parsed.path != "/v1/orchestrator/events"
+        or parsed.params
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ControllerError("gateway endpoint must be the fixed loopback endpoint")
+
+
+def get_gateway_state(url: str, project_key: str, token: str, timeout: float = 5.0) -> int:
+    _validate_gateway_url(url)
+    state_url = url.removesuffix("/events") + "/state/" + urllib.parse.quote(project_key, safe="")
+    request = urllib.request.Request(
+        state_url,
+        headers={"Authorization": f"Bearer {token}"},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload = json.loads(response.read(262_145))
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return 0
+        raise ControllerError(f"gateway state rejected HTTP {exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        raise ControllerError("gateway state unavailable") from exc
+    version = payload.get("state_version") if isinstance(payload, Mapping) else None
+    if not isinstance(version, int) or version < 0:
+        raise ControllerError("gateway state version invalid")
+    return version
+
+
+def post_json(url: str, payload: Mapping[str, Any], token: str, timeout: float = 5.0) -> None:
+    validate_metadata_only(payload)
+    _validate_gateway_url(url)
+    request = urllib.request.Request(
+        url,
+        data=canonical_json(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            if response.status < 200 or response.status >= 300:
+                raise ControllerError(f"gateway rejected HTTP {response.status}")
+    except urllib.error.HTTPError as exc:
+        raise ControllerError(f"gateway rejected HTTP {exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise ControllerError("gateway unavailable") from exc
+
+
+def run_once(config_path: Path) -> int:
+    config = read_secure_json(config_path, expected_uid=0 if os.name == "posix" else None)
+    gateway_url = config["gateway_event_url"]
+    token = read_gateway_token(Path(config["gateway_token_file"]))
+    state_version = get_gateway_state(gateway_url, config["project_key"], token)
+    store = QuorumStore(Path(config["database_path"]))
+    try:
+        receipts: dict[str, Health] = {}
+        for subject in ("central_gpt", "openclaw", "codex"):
+            receipt_path = Path(config["health_receipts"][subject])
+            try:
+                receipt = read_secure_json(receipt_path, expected_uid=0 if os.name == "posix" else None)
+                receipts[subject] = validate_health_receipt(
+                    receipt,
+                    subject,
+                    max_age_seconds=int(config.get("max_health_age_seconds", 60)),
+                )
+            except (FileNotFoundError, ControllerError, json.JSONDecodeError):
+                receipts[subject] = Health.UNKNOWN
+        decision = evaluate_quorum(
+            receipts["central_gpt"], receipts["openclaw"], receipts["codex"], config.get("default_workload", "large_repetitive_infrastructure_monitoring")
+        )
+        quorum_event_id = f"quorum-{time.time_ns()}"
+        store.enqueue(
+            quorum_event_id,
+            "gateway",
+            {
+                "schema_version": 1,
+                "project_key": config["project_key"],
+                "contract_commit": config["contract_commit"],
+                "event_id": quorum_event_id,
+                "source_agent": "system",
+                "event_type": "executor_quorum_evaluated",
+                "work_unit_id": "A0-AUTOMATION-QUORUM",
+                "status": "READY" if decision.allowed else "BLOCKED",
+                "state_version": state_version,
+                "implementation_commit": None,
+                "result_commit": None,
+                "blocker": None if decision.allowed else decision.status,
+                "evidence_refs": [],
+                "payload": {
+                    "allowed": decision.allowed,
+                    "priority": decision.priority,
+                    "quorum_status": decision.status,
+                    "active_executor": decision.active_executor,
+                    "standby_executor": decision.standby_executor,
+                },
+            },
+        )
+        poll_file_inbox(store, Path(config["file_inbox_path"]))
+        git_polling = config.get("git_ref_polling")
+        if isinstance(git_polling, Mapping):
+            poll_git_refs(store, Path(git_polling["repository"]), git_polling["refs"])
+        store.deliver_outbox(
+            lambda payload: post_json(gateway_url, payload, token),
+            max_attempts=int(config["blocker_retry_threshold"]),
+        )
+        return 0 if decision.allowed else 2
+    finally:
+        store.close()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", type=Path, required=True)
+    parser.add_argument("--once", action="store_true", required=True)
+    return parser
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return run_once(args.config)
+    except (ControllerError, KeyError, OSError, sqlite3.Error, json.JSONDecodeError) as error:
+        print(f"automation-quorum-controller: fail-closed: {type(error).__name__}", file=os.sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

automation/health_probe_common.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Strict metadata-only helpers shared by root health probes."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import stat
+import tempfile
+from typing import Any
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class ProbeError(RuntimeError):
+    pass
+
+
+def secure_regular(path: Path, *, max_mode: int, owners: set[int]) -> os.stat_result:
+    if not path.is_absolute():
+        raise ProbeError("path_not_absolute")
+    info = path.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        raise ProbeError("unsafe_file_type")
+    if stat.S_IMODE(info.st_mode) & ~max_mode:
+        raise ProbeError("unsafe_file_mode")
+    if os.name == "posix" and info.st_uid not in owners:
+        raise ProbeError("unsafe_file_owner")
+    if os.name == "posix" and path.resolve(strict=True) != Path(os.path.abspath(path)):
+        raise ProbeError("symlinked_path_component")
+    return info
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    secure_regular(path, max_mode=0o600, owners={0})
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ProbeError("config_not_object")
+    return value
+
+
+def read_token(path: Path) -> str:
+    info = secure_regular(path, max_mode=0o640, owners={0, os.geteuid()})
+    if info.st_size <= 0 or info.st_size > 16_384:
+        raise ProbeError("invalid_token_size")
+    fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    try:
+        opened = os.fstat(fd)
+        if not stat.S_ISREG(opened.st_mode) or opened.st_ino != info.st_ino or opened.st_dev != info.st_dev:
+            raise ProbeError("token_changed_during_validation")
+        data = os.read(fd, 16_385)
+        if os.read(fd, 1):
+            raise ProbeError("invalid_token_size")
+    finally:
+        os.close(fd)
+    if b"\n" in data or b"\r" in data:
+        raise ProbeError("invalid_token_format")
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ProbeError("invalid_token_encoding") from exc
+
+
+def gateway_base(endpoint: str) -> str:
+    parsed = urllib.parse.urlparse(endpoint)
+    if (
+        parsed.scheme != "http"
+        or parsed.hostname != "127.0.0.1"
+        or parsed.port != 18920
+        or parsed.path != "/v1/orchestrator/events"
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ProbeError("invalid_gateway_endpoint")
+    return endpoint.removesuffix("/events")
+
+
+def request_json(
+    url: str,
+    token: str,
+    *,
+    method: str = "GET",
+    payload: dict[str, Any] | None = None,
+    timeout: float = 10.0,
+) -> tuple[int, dict[str, Any]]:
+    data = None if payload is None else json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    headers = {"Authorization": f"Bearer {token}"}
+    if data is not None:
+        headers["Content-Type"] = "application/json"
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = json.loads(response.read(262_145))
+            if not isinstance(body, dict):
+                raise ProbeError("gateway_response_not_object")
+            return response.status, body
+    except urllib.error.HTTPError as exc:
+        if exc.code in {401, 403, 409, 422}:
+            raise ProbeError(f"gateway_fail_closed_{exc.code}") from exc
+        raise ProbeError(f"gateway_http_{exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        raise ProbeError("gateway_unavailable") from exc
+
+
+def state_version(endpoint: str, project_key: str, token: str) -> int:
+    url = gateway_base(endpoint) + "/state/" + urllib.parse.quote(project_key, safe="")
+    try:
+        _, value = request_json(url, token)
+    except ProbeError as exc:
+        if str(exc) == "gateway_http_404":
+            return 0
+        raise
+    version = value.get("state_version")
+    if not isinstance(version, int) or version < 0:
+        raise ProbeError("invalid_state_version")
+    return version
+
+
+def atomic_receipt(path: Path, value: dict[str, Any]) -> None:
+    if not path.is_absolute() or path.parent != Path("/run/aios-health"):
+        raise ProbeError("invalid_receipt_path")
+    parent = path.parent
+    info = parent.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
+        raise ProbeError("unsafe_receipt_directory")
+    if os.name == "posix" and (info.st_uid != 0 or stat.S_IMODE(info.st_mode) != 0o750):
+        raise ProbeError("unsafe_receipt_directory_metadata")
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=parent)
+    try:
+        # Receipts contain availability metadata only. Give the dedicated
+        # aios-quorum group read access so its unprivileged controller can
+        # consume them, while retaining root ownership and no public access.
+        if os.name == "posix":
+            os.fchown(fd, 0, info.st_gid)
+        os.fchmod(fd, 0o640)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, sort_keys=True, separators=(",", ":"))
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)

automation/remote_codex_health_probe.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+import time
+
+from services.aios_orchestrator_gateway.config import Config
+from services.aios_orchestrator_gateway.remote_codex import RemoteCodexBroker
+
+
+def atomic_receipt(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, temporary = tempfile.mkstemp(prefix=".remote-codex-health-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, separators=(",", ":"), sort_keys=True)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def run(config_path: Path, receipt: Path, healthy_within: int) -> int:
+    config = Config.from_file(config_path)
+    if config.central_channel != "remote_codex":
+        raise RuntimeError("remote_codex_not_selected")
+    broker = RemoteCodexBroker(
+        config.database_path,
+        contract_commit=config.contract_commit,
+        lease_seconds=config.remote_job_lease_seconds,
+        max_retries=config.max_retries,
+    )
+    try:
+        snapshot = broker.health_snapshot(healthy_within_seconds=healthy_within)
+    finally:
+        broker.close()
+    if snapshot["healthy_runners"] < 1:
+        raise RuntimeError("remote_codex_runner_unhealthy")
+    atomic_receipt(receipt, {
+        "subject": "remote_codex",
+        "health": "HEALTHY",
+        "contract_commit": config.contract_commit,
+        "healthy_runners": snapshot["healthy_runners"],
+        "runner_count": snapshot["runner_count"],
+        "job_counts": snapshot["job_counts"],
+        "observed_at_epoch": int(time.time()),
+    })
+    print("REMOTE_CODEX_HEALTH=PASS")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--gateway-config", required=True, type=Path)
+    parser.add_argument("--receipt", required=True, type=Path)
+    parser.add_argument("--healthy-within-seconds", type=int, default=300)
+    args = parser.parse_args()
+    try:
+        return run(args.gateway_config, args.receipt, args.healthy_within_seconds)
+    except Exception as exc:
+        reason = str(exc)
+        safe = reason if reason.replace("_", "").isalnum() and len(reason) <= 64 else type(exc).__name__
+        print(f"REMOTE_CODEX_HEALTH=BLOCKED reason={safe}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

config/aios-automation-quorum-controller.example.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "../schemas/automation-quorum-controller.schema.json",
+  "project_key": "v2r1-personal-weixin-production",
+  "contract_commit": "cbe33ecab8e9794ba5f318bea43aeaf447a56fbc",
+  "database_path": "/var/lib/aios-automation-quorum/controller.sqlite3",
+  "file_inbox_path": "/var/lib/aios-automation-quorum/inbox",
+  "default_workload": "large_repetitive_infrastructure_monitoring",
+  "health_receipts": {
+    "central_gpt": "/run/aios-health/central-gpt.json",
+    "openclaw": "/run/aios-health/openclaw.json",
+    "codex": "/run/aios-health/codex.json"
+  },
+  "git_ref_polling": {
+    "repository": "/data/aios-gitops/repo.git",
+    "refs": [
+      "refs/heads/task/governance/v2r1-personal-weixin-production-contract-20260717"
+    ]
+  },
+  "blocker_retry_threshold": 3,
+  "max_health_age_seconds": 60,
+  "lease_ttl_seconds": 120,
+  "gateway_event_url": "http://127.0.0.1:18920/v1/orchestrator/events",
+  "gateway_token_file": "/etc/aios-orchestrator-gateway/inbound.token"
+}

config/aios-codex-watcher.example.json

@@ -0,0 +1,17 @@
+{
+  "active_dir": "/data/aios-gitops/workspace/agents/commands/active",
+  "completed_dir": "/data/aios-gitops/workspace/agents/commands/completed",
+  "dead_letter_dir": "/data/aios-gitops/workspace/agents/commands/dead-letter",
+  "database_path": "/var/lib/aios-codex-watcher/state.sqlite3",
+  "audit_log_path": "/var/log/aios-codex-watcher/audit.jsonl",
+  "gateway_endpoint": "http://127.0.0.1:18920/v1/orchestrator/events",
+  "gateway_token_file": "/etc/aios-orchestrator-gateway/inbound.token",
+  "contract_commit": "cbe33ecab8e9794ba5f318bea43aeaf447a56fbc",
+  "lease_seconds": 60,
+  "retry_seconds": 10,
+  "max_attempts": 5,
+  "poll_seconds": 5,
+  "executor_path": null,
+  "executor_args": [],
+  "executor_timeout_seconds": 1800
+}

config/aios-health-probes.example.json

@@ -0,0 +1,17 @@
+{
+  "project_key": "v2r1-personal-weixin-production",
+  "contract_commit": "cbe33ecab8e9794ba5f318bea43aeaf447a56fbc",
+  "gateway_event_url": "http://127.0.0.1:18920/v1/orchestrator/events",
+  "gateway_token_file": "/etc/aios-orchestrator-gateway/inbound.token",
+  "gateway_database_path": "/var/lib/aios-orchestrator-gateway/state.sqlite3",
+  "probe_clean_base_commit": "c3984ca2b4388875d2875b4fdfdf95a2984f6ab3",
+  "central_receipt_path": "/run/aios-health/central-gpt.json",
+  "codex_receipt_path": "/run/aios-health/codex.json",
+  "codex_command_queue": "/data/aios-gitops/workspace/agents/commands/active",
+  "codex_database_path": "/var/lib/aios-codex-watcher/state.sqlite3",
+  "codex_audit_log": "/var/log/aios-codex-watcher/audit.jsonl",
+  "central_timeout_seconds": 90,
+  "codex_timeout_seconds": 90,
+  "cycle_timeout_seconds": 180,
+  "poll_interval_seconds": 1
+}

config/aios-orchestrator-gateway.example.json

@@ -0,0 +1,65 @@
+{
+  "host": "127.0.0.1",
+  "port": 18920,
+  "database_path": "/var/lib/aios-orchestrator-gateway/state.sqlite3",
+  "event_inbox_dir": "/var/lib/aios-orchestrator-gateway/inbox/events",
+  "decision_inbox_dir": "/var/lib/aios-orchestrator-gateway/inbox/decisions",
+  "dispatch_outbox_dir": "/var/lib/aios-orchestrator-gateway/outbox",
+  "openclaw_sync_dir": "/var/lib/aios-orchestrator-gateway/openclaw-sync",
+  "command_queue_dir": "/var/lib/aios-orchestrator-gateway/commands",
+  "inbound_token_file": "/etc/aios-orchestrator-gateway/inbound.token",
+  "callback_token_file": "/etc/aios-orchestrator-gateway/callback.token",
+  "contract_commit": "cbe33ecab8e9794ba5f318bea43aeaf447a56fbc",
+  "central_channel": "remote_codex",
+  "codex_local": {
+    "queue_dir": "/var/lib/aios-codex-brain/queue",
+    "timeout_seconds": 300
+  },
+  "remote_codex": {
+    "request_max_bytes": 262144,
+    "job_lease_seconds": 120,
+    "runners": [
+      {
+        "runner_id": "codex-brain-192-168-88-6",
+        "token_file": "/etc/aios-orchestrator-gateway/remote-codex-88-6.token",
+        "scopes": ["claim", "heartbeat", "decision", "fail"]
+      }
+    ]
+  },
+  "workspace_agent": {
+    "trigger_id": null,
+    "access_token_file": null
+  },
+  "responses_fallback": {
+    "api_key_file": null,
+    "model": null
+  },
+  "polling": {
+    "interval_seconds": 10,
+    "summary_interval_seconds": 300
+  },
+  "loop_controls": {
+    "callback_timeout_seconds": 900,
+    "lease_seconds": 60,
+    "retry_base_seconds": 10,
+    "max_retries": 5,
+    "max_same_blocker_retries": 3,
+    "max_hops_per_gate": 20
+  },
+  "openclaw_sync": {
+    "endpoint": null,
+    "token_file": null
+  },
+  "project_key": "v2r1-personal-weixin-production",
+  "git_poll": {
+    "enabled": true,
+    "bare_repo": "/data/aios-gitops/repo.git",
+    "ref_prefixes": [
+      "refs/heads/main",
+      "refs/heads/task/governance/",
+      "refs/heads/patch/",
+      "refs/heads/result/"
+    ],
+    "interval_seconds": 30
+  }
+}

deploy/systemd/aios-gitops-model-api.service

@@ -13,6 +13,7 @@ Environment=AIOS_GITOPS_TOKEN_FILE=/data/aios-gitops/runtime/secrets/gitops.toke
 Environment=AIOS_GITOPS_BARE_REPO=/data/aios-gitops/runtime/gitea-bin/data/repositories/aios/aios-v23.git
 Environment=AIOS_GITOPS_HOST=127.0.0.1
 Environment=AIOS_GITOPS_PORT=18890
+EnvironmentFile=-/etc/aios-gitops/orchestrator-callback.env
 ExecStart=/usr/bin/python3 /data/aios-gitops/workspace/active-runtime/app/aios_chatgpt_actions_api.py
 Restart=always
 RestartSec=3

deploy/v2r1/healthcheck.sh

@@ -1,20 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-printf 'AIOS V2R1C0 RC1 health check\n'
-
-python3 - <<'PY'
-from pathlib import Path
-required = [
- 'active-runtime/app/aios_v2r1/tenant_context.py',
- 'active-runtime/app/aios_v2r1/router.py',
- 'active-runtime/app/aios_v2r1/hermes_fabric.py',
- 'openclaw/plugins/aios-tenant-boundary/openclaw.plugin.json',
-]
-missing=[p for p in required if not Path(p).exists()]
-if missing:
-    raise SystemExit('missing: '+','.join(missing))
-print('artifact presence PASS')
-PY
-
-echo 'runtime health requires OpenClaw environment probe'

deploy/v2r1/install.sh

@@ -1,29 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT=$(cd "$(dirname "$0")/../.." && pwd)
-EXPECTED_BRANCH="release/v2r1c0-tenant-cell-fabric-20260712"
-
-if [[ "$(git -C "$ROOT" branch --show-current)" != "$EXPECTED_BRANCH" ]]; then
-  echo "wrong release branch"
-  exit 1
-fi
-
-COMMIT=$(git -C "$ROOT" rev-parse HEAD)
-echo "Installing AIOS V2R1C0 RC1 commit=$COMMIT"
-
-python3 - <<'PY'
-import compileall
-if not compileall.compile_dir('active-runtime/app/aios_v2r1', quiet=1):
-    raise SystemExit(1)
-print('python compile PASS')
-PY
-
-if [[ -f openclaw/plugins/aios-tenant-boundary/package.json ]]; then
-  echo "plugin package PASS"
-else
-  echo "plugin package missing"
-  exit 1
-fi
-
-echo "Installation preflight PASS"

deploy/v2r1/validate.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-MODE=${1:---check}
-
-case "$MODE" in
-  --check)
-    echo "V2R1C0 RC1 validation mode"
-    ;;
-  --install)
-    echo "Install requires approved OpenClaw Cell target"
-    ;;
-  --rollback)
-    echo "Rollback requires recorded Cell backup"
-    ;;
-  *)
-    echo "Usage: $0 [--check|--install|--rollback]"
-    exit 2
-    ;;
-esac
-
-python3 - <<'PY'
-import compileall
-raise SystemExit(0 if compileall.compile_dir('active-runtime/app/aios_v2r1', quiet=1) else 1)
-PY
-
-echo "python runtime syntax: PASS"

docs/AIOS_AUTOMATION_QUORUM_CONTROLLER.md

@@ -0,0 +1,137 @@
+# AIOS GPT + one-executor automation quorum
+
+## Authority and release boundary
+
+The Gateway is the only authoritative state writer. It must hold the SQLite writer lease before changing task state. A model response, service process, configured credential, or agent presence does not establish health. Release remains paused until all live acceptance rows are backed by logs and exit codes.
+
+Minimum quorum:
+
+```text
+central_gpt=HEALTHY AND (openclaw=HEALTHY OR codex=HEALTHY)
+```
+
+`UNKNOWN` never counts as healthy. If one executor is proven healthy, an unhealthy or unknown standby is P3 telemetry only and cannot block the active gate. If no executor is proven healthy, the controller blocks. Central GPT `UNKNOWN` or `UNHEALTHY` always blocks.
+
+## Live health receipts
+
+The controller reads three root-owned metadata-only JSON receipts from `/run/aios-health`. Files must be regular files, must not be symlinks, and neither files nor parent directories may be group/world writable. The controller rejects fields named `secret`, `token`, `password`, `api_key`, `authorization`, `credential`, `private_key`, `environment`, `env`, `argv`, `stdout`, or `stderr` at any depth.
+
+A receipt claiming `HEALTHY` must contain:
+
+```json
+{
+  "subject": "codex",
+  "health": "HEALTHY",
+  "live_probe_succeeded": true,
+  "observed_at_epoch": 1784347200
+}
+```
+
+The central GPT receipt additionally requires either `workspace_agent.validated_live=true` or `responses_api.validated_live=true`. Responses fallback is allowed only after a real Responses decision probe succeeded; credential/configuration presence is insufficient.
+
+The controller and probes use only the fixed loopback endpoint
+`http://127.0.0.1:18920/v1/orchestrator/events`. The bearer is read from
+`/etc/aios-orchestrator-gateway/inbound.token`; the file must be absolute,
+root-owned, regular, non-symlinked, no wider than `0640`, nonempty, and contain
+no CR/LF. It is never accepted through argv, environment, logs, receipts, or
+Git. HTTP `401`, `403`, `409`, and `422` are terminal fail-closed results for a
+probe attempt.
+
+The authenticated metadata query
+`GET /v1/orchestrator/events/<event_id>` returns only the event ID, public
+status, selected central channel, whether the decision was applied, and the
+resulting state version. It never returns the submitted event, model output,
+credential, or work-unit instruction.
+
+## Durable behavior
+
+SQLite persists ingress event digests, optimistic task state versions, leases, checkpoints, lifecycle events, effect IDs, outbox messages, blocker counts, observed Git refs, and project summaries. Reusing an event/effect/outbox ID with different content fails closed. An expired lease may be reclaimed; a live lease cannot be stolen.
+
+On active-executor failure, a healthy standby receives the same `contract_commit`, `event_id`, state version, and checkpoint. The former executor is recorded as `INTERRUPTED_AGENT_FAILOVER`. Unique effect IDs prevent replay of completed side effects.
+
+The Gateway persists these events even when OpenClaw is offline:
+
+```text
+TASK_DISPATCHED
+TASK_STARTED
+TASK_ENDED
+DECISION_APPLIED
+PROJECT_SUMMARY
+PROJECT_COMPLETED
+```
+
+OpenClaw mirroring is optional and uses the durable outbox with bounded retry and dead-letter. HTTP ingress failure spools a metadata-only file for polling; the configured local Git refs are also polled and changes missed by webhooks become idempotent events. Repeated blockers beyond the configured threshold enter `DEAD_LETTER`.
+
+## Install, verify, and rollback
+
+Installation is versioned and does not overwrite an existing release:
+
+```bash
+sudo scripts/install_automation_quorum_controller.sh "$PWD" 20260718.1
+sudo systemctl enable --now aios-automation-quorum-controller.timer
+sudo systemctl enable --now aios-central-gpt-health-probe.timer
+sudo systemctl enable --now aios-codex-executor-health-probe.timer
+```
+
+Run deterministic verification before enablement:
+
+```bash
+scripts/verify_automation_quorum_controller.sh "$PWD"
+```
+
+The two root probes are fixed, bounded, side-effect-free programs. They write
+receipts atomically with mode `0600` below the root-owned `0750`
+`/run/aios-health`. The Codex probe may write only one `acceptance_probe`
+command into the controlled watcher queue; it cannot accept arbitrary command
+text from configuration.
+
+Run the strict two-cycle closure only after both services are installed from an
+immutable committed release:
+
+```bash
+sudo /opt/aios-automation-quorum/current/bin/a0-unattended-loop-probe \
+  --config /etc/aios-automation-quorum/health-probes.json
+```
+
+Each cycle requires a live central decision that dispatches the named Codex
+acceptance work unit through the Gateway. The verifier then requires exactly
+one claim/start/execute/end/post marker, both lifecycle events in the Gateway,
+and a persisted `PROJECT_SUMMARY`. Directly queuing a command cannot satisfy
+this two-cycle closure.
+
+Rollback accepts only an existing non-symlink directory below `/opt/aios-automation-quorum/releases`. Repeating rollback to the current target is a no-op:
+
+```bash
+sudo scripts/rollback_automation_quorum_controller.sh \
+  /opt/aios-automation-quorum/releases/20260718.0
+```
+
+## Live acceptance matrix
+
+Each row requires captured logs, timestamps, exit codes, committed OIDs, Gitleaks output, and where applicable live Gateway DB evidence. Static unit tests are necessary but cannot close the gate.
+
+1. GPT + OpenClaw healthy, Codex stopped: two unattended cycles.
+2. GPT + Codex healthy, OpenClaw stopped: two unattended cycles.
+3. Both executors healthy: OpenClaw gets repetitive infrastructure; Codex gets complex code/security.
+4. Active stops mid-task: standby continues from checkpoint with no duplicate effect.
+5. Standby alone stops: active flow continues and no repair gate is created.
+6. GPT stops: execution blocks even with two healthy executors.
+7. GPT healthy and both executors stop: `BLOCKED_NO_HEALTHY_EXECUTOR`.
+8. `UNKNOWN` is never counted as healthy.
+9. HTTP ingress failure recovers through file polling.
+10. Missed webhook recovers through Git ref polling.
+11. Gateway restart restores events, leases, and outbox.
+12. Repeated event ID does not create a second dispatch; changed payload dead-letters.
+13. Repeated blocker beyond threshold dead-letters.
+14. Workspace Agent failure falls back only with a live-validated Responses channel.
+15. OpenClaw offline: Codex lifecycle and project summary remain complete in Gateway.
+16. Codex offline: OpenClaw lifecycle and project summary remain complete in Gateway.
+
+Until all rows pass against the live service, retain:
+
+```text
+AUTOMATION_CLOSED=NOT_STARTED
+BASELINE=V1R4C6
+RELEASE=paused
+PRODUCTION_RELEASE=NOT_STARTED
+```

docs/architecture/AIOS_AGENT_AUDIT_PLANE.md

@@ -1,3 +1,4 @@
+<<<<<<< HEAD
 # AIOS Agent Audit Plane Architecture
 
 ## Overview
@@ -27,7 +28,6 @@ Agent Command Plane (agents/commands/)
     |     audit/agent-runs/        (per-agent log)
     |     audit/command-history/   (per-command log)
     |     audit/version-history/   (per-baseline log)
-    |     audit/interaction-history/ (agent conversation traces)
     |
     +---> Git Commit
               |
@@ -45,39 +45,8 @@ Agent Command Plane (agents/commands/)
 5. Git commit locks the audit record
 6. Web UI displays timeline from git history
 
-## Directory Structure
-
-```
-audit/
-├── agent-runs/          # Per-execution records (JSON)
-├── command-history/     # Command lifecycle history
-├── version-history/     # Version/baseline change log
-└── interaction-history/ # Agent conversation traces
-```
-
 ## Audit Record Schema
 
-Current agent-run records use the following fields:
-
-| Field | Description |
-|-------|-------------|
-| agent_run_id | Unique execution ID |
-| command | Command file name |
-| agent | Executing agent name |
-| version | Baseline version at execution time |
-| objective | Human-readable goal |
-| start_time | ISO-8601 start timestamp |
-| end_time | ISO-8601 completion timestamp |
-| interaction_count | Agent-owner interaction turns |
-| tool_call_count | Tool invocations during execution |
-| changed_files | Files modified in this run |
-| commit_sha | Git commit hash |
-| test_result | Test verification outcome |
-| final_result | SUCCESS / FAILED / PARTIAL |
-| evidence_path | Link to evidence directory |
-
-Legacy records remain valid and may use the following compatibility shape:
-
 ```json
 {
   "id": "",
@@ -103,6 +72,51 @@ Legacy records remain valid and may use the following compatibility shape:
 - Every code change must be traceable to who/what agent created it
 - No agent-created changes without audit trail
 
+## Related
+
+- [Agent Command Plane](../agents/README.md)
+- [Baseline System](baseline-system.md)
+=======
+# AIOS Agent Audit Plane
+
+## Purpose
+
+Every agent action is recorded. All code changes are traceable to:
+- Who made the change
+- Why the change was made
+- When it was made
+- Which version introduced it
+- What test results showed
+
+## Directory Structure
+
+```
+audit/
+├── agent-runs/         # Per-execution records (JSON)
+├── command-history/    # Command lifecycle history
+├── version-history/    # Version/baseline change log
+└── interaction-history/ # Agent conversation traces
+```
+
+## Agent Run Record
+
+| Field | Description |
+|-------|-------------|
+| agent_run_id | Unique execution ID |
+| command | Command file name |
+| agent | Executing agent name |
+| version | Baseline version at execution time |
+| objective | Human-readable goal |
+| start_time | ISO-8601 start timestamp |
+| end_time | ISO-8601 completion timestamp |
+| interaction_count | Agent-owner interaction turns |
+| tool_call_count | Tool invocations during execution |
+| changed_files | Files modified in this run |
+| commit_sha | Git commit hash |
+| test_result | Test verification outcome |
+| final_result | SUCCESS / FAILED / PARTIAL |
+| evidence_path | Link to evidence directory |
+
 ## Version History
 
 Records baseline promotions, rollbacks, and version changes.
@@ -113,9 +127,6 @@ Conversation logs between agent and owner for each command execution.
 
 ## Audit Trail Requirement
 
-All changes are tracked via Git with signed commits where possible. Every commit references the originating Command ID.
-
-## Related
-
-- [Agent Command Plane](../agents/README.md)
-- [Baseline System](baseline-system.md)
+All changes tracked via Git with signed commits where possible.
+Every commit message references the originating Command ID.
+>>>>>>> 4d18ee0 (feat(cmd): enable Agent Command Plane, audit plane, and Web UI dashboard)

docs/architecture/AIOS_V1R5_to_V2R1_Migration_Plan.md

@@ -1,26 +0,0 @@
-# AIOS V1R5 to V2R1 Migration Plan
-
-## Goal
-
-Move from shared Gateway assumptions to Tenant Cell isolation.
-
-## Order
-
-1. Establish Tenant Registry and signed Tenant Context.
-2. Implement Tenant Router.
-3. Implement OpenClaw Cell lifecycle management.
-4. Introduce canonical message envelope.
-5. Add provenance and execution policy enforcement.
-6. Migrate Hermes into shared fabric with isolated profiles.
-7. Migrate memory, secrets and audit storage.
-
-## Do Not
-
-- Do not modify Hermes first.
-- Do not share production credentials across tenants.
-- Do not treat workspace separation as a sandbox.
-- Do not allow unknown message origins to execute tools.
-
-## Acceptance
-
-Each migration stage requires automated tests and runtime evidence before promotion.

docs/architecture/AIOS_V2R1_OpenClaw_Tenant_Cell_Hermes_Shared_Agent_Fabric_Architecture.md

@@ -1,49 +0,0 @@
-# AIOS V2R1 OpenClaw Tenant Cell + Hermes Shared Agent Fabric Architecture
-
-## Status
-
-Release train: V2R1C0
-
-Purpose: replace shared runtime trust assumptions with tenant-isolated Cell architecture.
-
-## Principles
-
-1. OpenClaw Gateway is a trust boundary.
-2. Each production tenant receives an isolated Cell.
-3. Hermes provides shared scheduling/fabric capability but not shared tenant state.
-4. Tenant identity, origin, session and task scope are mandatory in every event.
-5. Unknown provenance fails closed.
-
-## Target Components
-
-- Tenant Router
-- OpenClaw Cell Manager
-- Canonical Message Envelope
-- Tenant Inbox/Outbox Ledger
-- Secret Scope Manager
-- Memory Namespace Manager
-- Hermes Profile Worker Fabric
-- Sandbox Execution Layer
-- Audit Event Pipeline
-
-## Migration Order
-
-Phase 1: Tenant Router + Cell Manager
-
-Phase 2: Canonical Message and Policy Layer
-
-Phase 3: Hermes Shared Agent Fabric
-
-Phase 4: Memory, Secret and Audit isolation
-
-Phase 5: Production tenant migration
-
-## Release Gate
-
-A V2R1 production release requires:
-
-- tenant isolation tests passed
-- message provenance tests passed
-- runtime commit matches release commit
-- OpenClaw plugin runtime inspection passed
-- rollback verified

docs/runbooks/A0-CALLBACK-TRANSPORT-AND-PENDING-RECOVERY.md

@@ -0,0 +1,65 @@
+# A0 callback transport and pending-decision recovery
+
+This runbook separates code acceptance from live callback acceptance. Passing
+unit tests does not prove that a cloud Workspace Agent can reach the installed
+tool endpoint.
+
+## Transport configuration
+
+Choose exactly one mode in the owner-managed remote-tool configuration:
+
+- `remote_https_action`: `endpoint` must be the real public HTTPS Action URL.
+- `secure_mcp_tunnel`: `endpoint` must exactly match an entry in
+  `approved_mcp_tunnel_endpoints`.
+
+The configuration stores only `access_secret_ref` and `callback_secret_ref`.
+It must not contain resolved credentials. Startup rejects HTTP, loopback,
+unspecified/private literal addresses, URL credentials, query/fragment data,
+unapproved tunnel endpoints, and known placeholder markers.
+
+Generate the cloud-facing manifest only after owner configuration exists:
+
+```bash
+PYTHONPATH=/opt/aios-orchestrator-gateway/current \
+python3 /opt/aios-orchestrator-gateway/current/scripts/generate_orchestrator_tool_manifest.py \
+  --transport-config /etc/aios-orchestrator-gateway/remote-tool.json \
+  --output /var/lib/aios-orchestrator-gateway/orchestrator-tool-manifest.json
+```
+
+The generated Action manifest exposes only
+`submit_orchestration_decision`. The MCP manifest lists the same single tool
+with write-side-effect and idempotency annotations.
+
+## Recovery
+
+Plan mode is read-only:
+
+```bash
+PYTHONPATH=/opt/aios-orchestrator-gateway/current \
+python3 /opt/aios-orchestrator-gateway/current/scripts/recover_pending_decisions.py \
+  --config /etc/aios-orchestrator-gateway/config.json --plan
+```
+
+Application handles at most one leased record and never resends a model prompt
+or replays a decision:
+
+```bash
+PYTHONPATH=/opt/aios-orchestrator-gateway/current \
+python3 /opt/aios-orchestrator-gateway/current/scripts/recover_pending_decisions.py \
+  --config /etc/aios-orchestrator-gateway/config.json --apply-one
+```
+
+## Required live acceptance
+
+Do not mark the live Gate PASS until metadata-only evidence proves, in order:
+
+1. Workspace trigger returned HTTP 202.
+2. The remote callback tool received one authenticated request.
+3. The bridge returned HTTP 202 from the loopback 18920 decision endpoint.
+4. The event reached `DECIDED`, `callback_state=APPLIED`, and
+   `decision_applied=true`.
+5. Recovery planning and one apply cycle did not create a second outbox side
+   effect for the same event.
+
+Never include Authorization, token values, resolved SecretRefs, prompts, or raw
+model output in logs or RESULT files.

docs/superpowers/plans/2026-07-14-v2r1-runtime-release-plan.md

@@ -1,601 +0,0 @@
-# V2R1 Authenticated Runtime Release Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Close exactly five reviewed blockers between the replayed V2R1 tree and an evidence-backed, authenticated, digest-bound release candidate.
-
-**Architecture:** Use one canonical `aios_v2r1` Python package; authenticate a Node-to-Python loopback envelope before server-side Weixin projection and authority resolution; make `ACCEPTED` terminal; dispatch through a durable outbox and the verified Hermes HTTP router; stage an isolated OpenClaw candidate with three services; promote only byte-identical artifacts after live reconciliation evidence.
-
-**Tech Stack:** Python 3.11 and pytest, SQLite, Node.js, OpenClaw 2026.6.11, loopback HTTP, systemd credentials and units, SHA-256 manifests.
-
-## Global gates and dynamic blocker ledger
-
-- B1 and B2 may proceed only after review accepts the corrected design and plan.
-- B3, B4, and B5 are evidence-gated. Unresolved evidence stops that task before implementation, commit, or ledger append.
-- Current outbound evidence is `EVIDENCE_REQUIRED`; B4 and B5 remain stopped until a verified provider echo exactly binds `client_id -> message_id`.
-- Keep exactly five blocker commits, one each for B1 through B5. The docs-correction commit is the reviewed starting point, not a blocker.
-- Do not create a tag, edit `VERSION` or `baseline/current.json`, push `main`, deploy/restart a live service, modify active OpenClaw configuration, or invoke Fleet.
-- All OpenClaw loader work uses an isolated temporary or candidate config/state directory.
-- `ACCEPTED` is terminal. Legacy handling is reachable only when bridge mode is explicitly `disabled`.
-- Never claim exactly-once Hermes delivery or use time/approximation as message authority.
-
-After docs review, initialize the stable per-worktree ledger from the then-current tip rather than a hardcoded SHA:
-
-```bash
-test -z "$(git status --porcelain)"
-test "$(git branch --show-current)" = "integration/v2r1-runtime-20260714"
-start_sha="$(git rev-parse HEAD)"
-start_parent="$(git rev-parse HEAD^)"
-start_tree="$(git rev-parse HEAD^{tree})"
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-umask 077
-test ! -e "$ledger"
-printf 'START\t%s\t%s\t%s\n' "$start_sha" "$start_parent" "$start_tree" >"$ledger"
-```
-
-Expected: the clean reviewed docs-correction tip is `START`. At the beginning of every blocker, rehydrate and verify the latest ledger row before work:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-test -s "$ledger"
-IFS=$'\t' read -r last_label last_sha last_parent last_tree < <(tail -n 1 "$ledger")
-test "$(git rev-parse HEAD)" = "$last_sha"
-test "$(git rev-parse HEAD^)" = "$last_parent"
-test "$(git rev-parse HEAD^{tree})" = "$last_tree"
-```
-
-Each blocker appends `label, SHA, parent, tree` only after its review passes. The ledger stays in the worktree Git directory and is never staged.
-
----
-
-## Task B1: Prove the real OpenClaw plugin loader and permission contract
-
-**Files:**
-
-- Modify: `openclaw/plugins/aios-tenant-boundary/package.json`
-- Modify: `openclaw/plugins/aios-tenant-boundary/openclaw.plugin.json`
-- Modify only on demonstrated hook failure: `openclaw/plugins/aios-tenant-boundary/dist/index.js`
-- Modify only on demonstrated policy failure: `openclaw/plugins/aios-tenant-boundary/dist/policy.js`
-- Create: `openclaw/plugins/aios-tenant-boundary/test/compat.test.js`
-- Create: `openclaw/plugins/aios-tenant-boundary/test/policy.test.js`
-- Create: `openclaw/plugins/aios-tenant-boundary/test/loader.test.mjs`
-
-**Exact contract:** package/manifest versions `2.1.0-rc.1`; `blockUnknownAgentRuns` boolean default `false`; `approvalTimeoutMs` integer min `1000`, max `300000`, default `60000`; every runtime-read property declared. Default permission proves only `before_tool_call` is usable. `before_agent_run` and `agent_end` require `plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess=true`. Fake API tests are supplemental; real runtime inspection is mandatory.
-
-- [ ] Add Node tests for missing/blocked/allowlisted senders, automation, read-only tools, absent provenance, approval, exact timeout bounds, cleanup, age pruning, versions, and schema.
-- [ ] Add `loader.test.mjs` to parse real inspect JSON and assert linked path, version, diagnostics, hooks, and permission state.
-- [ ] Run initial RED:
-
-```bash
-cd openclaw/plugins/aios-tenant-boundary
-npm test
-```
-
-Expected RED: current package has no tracked tests; version and missing-schema assertions fail.
-
-- [ ] Normalize versions/schema; change runtime only when an executable test proves incompatibility. Capture TAP and prove at least one test executed:
-
-```bash
-tmp="$(mktemp -d)"
-set -o pipefail
-npm test -- --test-reporter=tap | tee "$tmp/plugin.tap"
-test "$(grep -c '^ok [0-9]' "$tmp/plugin.tap")" -gt 0
-test -z "$(grep '^not ok ' "$tmp/plugin.tap" || true)"
-```
-
-Expected GREEN: npm exits 0, TAP contains one or more `ok` test records, and contains no `not ok` record.
-- [ ] Run the real loader twice in isolated state:
-
-```bash
-repo="$(git rev-parse --show-toplevel)"
-tmp="$(mktemp -d)"
-export OPENCLAW_STATE_DIR="$tmp/state"
-export OPENCLAW_CONFIG_PATH="$tmp/state/openclaw.json"
-mkdir -p "$OPENCLAW_STATE_DIR"
-openclaw plugins install --link "$repo/openclaw/plugins/aios-tenant-boundary"
-openclaw plugins inspect aios-tenant-boundary --runtime --json >"$tmp/default-inspect.json"
-node "$repo/openclaw/plugins/aios-tenant-boundary/test/loader.test.mjs" default "$tmp/default-inspect.json"
-openclaw config set plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess true --strict-json
-openclaw config validate
-set +e
-openclaw doctor --lint --json >"$tmp/doctor-lint.json"
-doctor_rc=$?
-set -e
-test "$doctor_rc" = 0 || test "$doctor_rc" = 1
-python3 - "$tmp/doctor-lint.json" <<'PY'
-import json, sys
-data = json.load(open(sys.argv[1]))
-def walk(value):
-    if isinstance(value, dict):
-        yield value
-        for child in value.values(): yield from walk(child)
-    elif isinstance(value, list):
-        for child in value: yield from walk(child)
-bad = [item for item in walk(data) if str(item.get("severity", "")).lower() in {"error", "fatal"} and "plugin" in json.dumps(item).lower()]
-assert not bad, bad
-PY
-openclaw doctor --post-upgrade --json >"$tmp/doctor-plugin.json"
-openclaw plugins inspect aios-tenant-boundary --runtime --json >"$tmp/opt-in-inspect.json"
-node "$repo/openclaw/plugins/aios-tenant-boundary/test/loader.test.mjs" opt-in "$tmp/opt-in-inspect.json"
-```
-
-Expected GREEN: config validation and post-upgrade doctor exit 0; lint doctor may exit 0 or 1, warnings are allowed, parsed JSON contains zero error/fatal plugin findings; default inspection proves only `before_tool_call`; opt-in proves `before_agent_run`, `before_tool_call`, `agent_end`.
-
-- [ ] Run carried-forward tests:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH=active-runtime/app python3 -m pytest tests/v2r1 tests/integration -q
-```
-
-Expected GREEN: `32 passed`.
-
-- [ ] Commit and append ledger:
-
-```bash
-git add openclaw/plugins/aios-tenant-boundary/package.json openclaw/plugins/aios-tenant-boundary/openclaw.plugin.json \
-  openclaw/plugins/aios-tenant-boundary/dist/index.js openclaw/plugins/aios-tenant-boundary/dist/policy.js \
-  openclaw/plugins/aios-tenant-boundary/test/compat.test.js openclaw/plugins/aios-tenant-boundary/test/policy.test.js \
-  openclaw/plugins/aios-tenant-boundary/test/loader.test.mjs
-git commit -m "fix(v2r1): prove OpenClaw plugin compatibility"
-```
-
-### Review B1
-
-- [ ] `git diff --check HEAD^ HEAD` has no output; commit contains only named B1 paths and unchanged optional `dist` files do not appear.
-- [ ] Re-run Node tests, both real loader permission modes, validation/doctor, and 32 Python tests.
-- [ ] Prove B1 parent equals ledger `START` and, before the final append step, the ledger still contains only `START`.
-- [ ] Stop if real inspection does not prove default-only `before_tool_call` and explicit conversation-access hooks.
-- [ ] After every prior B1 review check passes, append B1 and verify the recorded commit identity:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-printf 'B1\t%s\t%s\t%s\n' "$(git rev-parse HEAD)" "$(git rev-parse HEAD^)" "$(git rev-parse HEAD^{tree})" >>"$ledger"
-IFS=$'\t' read -r label sha parent tree < <(tail -n 1 "$ledger")
-test "$label" = B1
-test "$sha" = "$(git rev-parse HEAD)"
-test "$parent" = "$(git rev-parse HEAD^)"
-test "$tree" = "$(git rev-parse HEAD^{tree})"
-```
-
----
-
-## Task B2: Package only `aios_v2r1` and repair the exact legacy import set
-
-**Files:**
-
-- Create: `active-runtime/pyproject.toml`
-- Create: `active-runtime/app/aios_v2r1/__init__.py`
-- Create: `active-runtime/app/aios_v2r1/ingress_service.py`
-- Modify: `active-runtime/app/aios_v2r1/cli.py`
-- Create: `tests/v2r1/test_ingress_service.py`
-- Create: `tests/test_v2r1_package_identity.py`
-- Modify: the exact 23 Appendix A test files, and no unlisted legacy import file
-
-**Exact contract:** V2R1 imports only as `aios_v2r1`; no `active_runtime` shim/alias/namespace extension/copied tree. Wheel includes `aios_v2r1`, excludes `active_runtime` and legacy `app`. Legacy repository tests change `active_runtime.app.*` to `app.*` and run with `PYTHONPATH='active-runtime:active-runtime/app'`. Mutation routes return bounded `SERVICE_NOT_CONFIGURED` until B3/B4 processors exist. Existing cell CLI stays compatible and `serve` is separate.
-
-- [ ] Rehydrate the stable blocker ledger using the global snippet and require its latest label is `B1`.
-- [ ] Rehydrate the exact explorer manifest path and compare sorted actual/expected lists between exact marker lines. The marker names are assembled from split literals so this command cannot match itself:
-
-```bash
-actual="$(git rev-parse --git-path v2r1-active-runtime-imports.actual)"
-expected="$(git rev-parse --git-path v2r1-active-runtime-imports.expected)"
-plan=docs/superpowers/plans/2026-07-14-v2r1-runtime-release-plan.md
-begin="$(printf '%s' 'APPENDIX_A_''BEGIN')"
-end="$(printf '%s' 'APPENDIX_A_''END')"
-tick="$(printf '\140')"
-git grep -l -E '^(from|import) active_runtime\.app' -- tests | sort >"$actual"
-awk -v begin="${tick}${begin}${tick}" -v end="${tick}${end}${tick}" '
-  $0 == begin {inside=1; next}
-  $0 == end {inside=0; next}
-  inside && /^- tests\// {sub(/^- /, ""); print}
-' "$plan" | sort >"$expected"
-test "$(wc -l < "$actual" | tr -d ' ')" = 23
-test "$(wc -l < "$expected" | tr -d ' ')" = 23
-cmp -s "$actual" "$expected"
-```
-
-Expected: exact match to 23 paths. Drift requires another docs review.
-
-- [ ] Add package/service/CLI tests; run initial RED:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' \
-  python3 -m pytest tests/v2r1/test_ingress_service.py tests/test_v2r1_package_identity.py -q
-```
-
-Expected RED: package metadata, ingress service, and identity tests do not exist.
-
-- [ ] Implement package/disabled processor boundary and replace imports in exactly Appendix A. Prove no shim/old import:
-
-```bash
-test ! -e active_runtime
-test -z "$(git grep -l -E '^(from|import) active_runtime\.app' -- tests || true)"
-```
-
-- [ ] Run full collect and full suite:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' python3 -m pytest --collect-only -q
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' python3 -m pytest -q
-```
-
-Expected GREEN: zero collection/import errors and complete suite passes; pre-existing failures still block B2.
-
-- [ ] Build and inspect isolated wheel:
-
-```bash
-tmp="$(mktemp -d)"
-python3 -m pip wheel --no-deps --no-build-isolation active-runtime -w "$tmp/wheels"
-wheel="$(find "$tmp/wheels" -name '*.whl' -print -quit)"
-python3 -m venv "$tmp/venv"
-"$tmp/venv/bin/python" -m pip install --no-deps "$wheel"
-"$tmp/venv/bin/python" - "$wheel" <<'PY'
-import sys, zipfile
-names = zipfile.ZipFile(sys.argv[1]).namelist()
-assert any(n.endswith("aios_v2r1/ingress_service.py") for n in names)
-assert not any(n.startswith("active_runtime/") or n.startswith("app/") for n in names)
-import aios_v2r1
-assert aios_v2r1.__name__ == "aios_v2r1"
-PY
-```
-
-Expected GREEN: one wheel, one V2R1 namespace, installed identity `aios_v2r1`.
-
-- [ ] Stage six named paths plus exact explorer list, commit, append ledger:
-
-```bash
-actual="$(git rev-parse --git-path v2r1-active-runtime-imports.actual)"
-git add active-runtime/pyproject.toml active-runtime/app/aios_v2r1/__init__.py \
-  active-runtime/app/aios_v2r1/ingress_service.py active-runtime/app/aios_v2r1/cli.py \
-  tests/v2r1/test_ingress_service.py tests/test_v2r1_package_identity.py
-while IFS= read -r path; do git add -- "$path"; done <"$actual"
-git commit -m "feat(v2r1): package canonical authenticated ingress"
-```
-
-### Review B2
-
-- [ ] Require `git diff --check`, exactly 29 paths (six named plus Appendix A), exact-list/no-shim checks, full collect/full pytest, and wheel identity.
-- [ ] Require B2 parent equals B1 in ledger.
-- [ ] Prove mutation routes remain fail-closed until authenticated processors are installed.
-- [ ] After all prior B2 review checks pass, append B2 and verify the recorded commit identity:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-printf 'B2\t%s\t%s\t%s\n' "$(git rev-parse HEAD)" "$(git rev-parse HEAD^)" "$(git rev-parse HEAD^{tree})" >>"$ledger"
-IFS=$'\t' read -r label sha parent tree < <(tail -n 1 "$ledger")
-test "$label" = B2
-test "$sha" = "$(git rev-parse HEAD)"
-test "$parent" = "$(git rev-parse HEAD^)"
-test "$tree" = "$(git rev-parse HEAD^{tree})"
-```
-
----
-
-## Task B3: Implement authenticated Node transport and server-side Weixin authority
-
-**Evidence gate before code:** create `release/v2r1c0-rc1/weixin-bridge-evidence.json` only after recording installed TS/JS paths and SHA-256, exact inbound bigint/raw fields, authenticated account/sender/conversation sources, authority-map owner/mode/schema, candidate credential contract, and `disabled|enforced` mode owner. Stop if any source is inferred, Node would need the authority map, or patch targets are not byte-idempotent.
-
-**Files after evidence acceptance:**
-
-- Modify: `active-runtime/app/aios_v2r1/identity.py`
-- Modify: `active-runtime/app/aios_v2r1/tenant_context.py`
-- Modify: `active-runtime/app/aios_v2r1/ingress_service.py`
-- Create: `active-runtime/app/aios_v2r1/bridge_auth.py`
-- Create: `active-runtime/app/aios_v2r1/weixin_projection.py`
-- Create: `fixes/patch_openclaw_weixin_v2r1_ingress.py`
-- Create: `tests/v2r1/test_bridge_auth.py`
-- Create: `tests/v2r1/test_weixin_projection.py`
-- Create: `tests/integration/test_v2r1_bridge_transport.py`
-- Create: `tests/test_weixin_v2r1_ingress_bridge.py`
-- Create: four `tests/fixtures/weixin_v2r1/*.json` files named in the commit command
-- Create: `release/v2r1c0-rc1/weixin-bridge-evidence.json`
-
-**Exact contract:** Every authenticated POST has wire shape `{"unsigned_body":{"schema_version":"aios.signed-request.v1","key_id":"bridge-current","issued_at_ms":1784000000000,"nonce":"base64url-16-byte-value","route_payload":{}},"signature":"lowercase-64-hex"}`. `unsigned_body` has exactly those five fields; `route_payload` holds only route-specific content. The signing object is exactly `{"method":"POST","path":"<exact route>","body":unsigned_body}`. Canonical JSON is UTF-8 with recursive Unicode-codepoint-sorted object keys, no whitespace, no ASCII escaping, no floats, and string IDs; the outer `signature` is the lowercase 64-hex HMAC-SHA256 of those bytes. There is no authorization header, nested signature, or alternate route form. Python verifies before projection. Skew 30 seconds; replay five minutes; active+previous rotation; fresh nonce retry. Node reads bridge-ingress and the separate receipt-read keyring through distinct `$CREDENTIALS_DIRECTORY` files. Python owns projection/authority/internal signing. `POST /v1/receipts/status` accepts `account_id` plus exactly one of `event_id|receipt_id`, resolves only same-account/event scope, and uses receipt-read. Response max 4096 bytes. `REPLAY_REJECTED` is transport/service-only, never `RuntimeIngressResponse`. Accepted is terminal; legacy disabled-only. `Date.now()` and every local `_ms` timestamp are telemetry only.
-
-- [ ] Rehydrate the stable ledger with the global snippet and require latest label `B2` before evidence collection.
-- [ ] Add RED tests for the one exact wire/signing contract on `/v1/ingress` and `/v1/receipts/status`, including rejection of extra/missing fields, signature-inside-body, authorization-header variants, nonce lengths, skew boundaries, replay, key rotation, fresh retry, roles, bounded routes, terminal accepted, disabled legacy, bigint, and exact quote/attachment.
-- [ ] Run initial RED:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' \
-  python3 -m pytest tests/v2r1/test_bridge_auth.py tests/v2r1/test_weixin_projection.py \
-    tests/integration/test_v2r1_bridge_transport.py tests/test_weixin_v2r1_ingress_bridge.py -q
-```
-
-Expected RED: authenticator, server projection, processor, patcher absent.
-
-- [ ] Implement authenticated transport/server projection and byte-idempotent TS/JS patch. Never embed authority or internal key in Node.
-- [ ] Run focused, existing Weixin, full collect, and full pytest. Expected GREEN: all pass.
-- [ ] Commit exactly 15 paths and append ledger:
-
-```bash
-git add active-runtime/app/aios_v2r1/identity.py active-runtime/app/aios_v2r1/tenant_context.py \
-  active-runtime/app/aios_v2r1/ingress_service.py active-runtime/app/aios_v2r1/bridge_auth.py \
-  active-runtime/app/aios_v2r1/weixin_projection.py fixes/patch_openclaw_weixin_v2r1_ingress.py \
-  tests/v2r1/test_bridge_auth.py tests/v2r1/test_weixin_projection.py \
-  tests/integration/test_v2r1_bridge_transport.py tests/test_weixin_v2r1_ingress_bridge.py \
-  tests/fixtures/weixin_v2r1/text.json tests/fixtures/weixin_v2r1/quoted-text.json \
-  tests/fixtures/weixin_v2r1/image-with-text.json tests/fixtures/weixin_v2r1/unresolved-reference.json \
-  release/v2r1c0-rc1/weixin-bridge-evidence.json
-git commit -m "feat(v2r1): bridge authenticated Weixin authority"
-```
-
-### Review B3
-
-- [ ] Require exactly 15 named paths, `git diff --check`, focused/full tests, and a second patcher pass with empty diff.
-- [ ] Prove Node transports evidence only; Python owns projection/authority; RuntimeWiring re-resolves.
-- [ ] Prove fresh nonce on retry, terminal accepted, and legacy unreachable in `enforced`.
-- [ ] Require B3 parent equals B2. Stop without commit/ledger append when evidence is unresolved.
-- [ ] After all prior B3 review checks pass, append B3 and verify the recorded commit identity:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-printf 'B3\t%s\t%s\t%s\n' "$(git rev-parse HEAD)" "$(git rev-parse HEAD^)" "$(git rev-parse HEAD^{tree})" >>"$ledger"
-IFS=$'\t' read -r label sha parent tree < <(tail -n 1 "$ledger")
-test "$label" = B3
-test "$sha" = "$(git rev-parse HEAD)"
-test "$parent" = "$(git rev-parse HEAD^)"
-test "$tree" = "$(git rev-parse HEAD^{tree})"
-```
-
----
-
-## Task B4: Connect the durable outbox to the verified Hermes HTTP router
-
-**Evidence gate before code:** create `release/v2r1c0-rc1/hermes-http-contract-evidence.json` from live listener/unit/source/schema inspection and `release/v2r1c0-rc1/weixin-outbound-binding-evidence.json` from raw protocol evidence. Hermes evidence resolves schemas, `aios-hermes-router.service`, source digest, exact 140-second timeout, tenant/user ownership, and repeated-`route_id` behavior as idempotent/non-idempotent. Outbound evidence must prove exact provider echo `client_id -> message_id`. Current ACK `ret/errmsg` plus reference `ref_msg.message_item.msg_id/ref_msg.message_item.create_time_ms` is `EVIDENCE_REQUIRED` and hard-stops B4; timestamp cannot unlock it.
-
-**Files only after both gates pass:**
-
-- Create: `active-runtime/app/aios_v2r1/outbox.py`
-- Create: `active-runtime/app/aios_v2r1/hermes_http.py`
-- Create: `active-runtime/app/aios_v2r1/hermes_worker.py`
-- Create: `active-runtime/app/aios_v2r1/outbound_receipt.py`
-- Modify: `active-runtime/app/aios_v2r1/ingress_service.py`
-- Modify: `active-runtime/app/aios_v2r1/message_ledger.py`
-- Create: `tests/v2r1/test_outbox.py`
-- Create: `tests/v2r1/test_hermes_http.py`
-- Create: `tests/v2r1/test_outbound_receipt.py`
-- Create: `tests/integration/test_v2r1_delivery_flow.py`
-- Modify: `fixes/patch_openclaw_weixin_outbound_quotes.py`
-- Create: `fixes/patch_openclaw_weixin_outbound_receipts.py`
-- Create: `openclaw/plugins/aios-tenant-boundary/dist/receipt-client.js`
-- Create: `openclaw/plugins/aios-tenant-boundary/dist/outbound-receipt-journal.js`
-- Create: `openclaw/plugins/aios-tenant-boundary/test/receipt-client.test.js`
-- Modify: `tests/test_weixin_outbound_quote_timestamp.py`
-- Create: `tests/test_weixin_outbound_receipt_boundary.py`
-- Create: both evidence JSON files named above
-
-**Exact contract:** readiness `GET http://127.0.0.1:18791/health/ready`; dispatch `POST http://127.0.0.1:18791/internal/hermes/route`; downstream 140 seconds; worker deadline 150 seconds; 120-second direct timeout forbidden. States `pending|leased|delivered|delivery_unknown|dead`. No exactly-once. Unknown idempotency stops; known false prevents ambiguous retry; known true retries same `route_id`/digest. After B4 evidence, the actual Node Weixin sender receives a separate `outbound-receipt-write` `LoadCredential=` and uses the same one POST signing contract for `/v1/outbound-receipts`: exact five-field `unsigned_body`, exact `{method,path,body}` signing object, canonical JSON, and outer lowercase 64-hex HMAC-SHA256 signature.
-
-Node alone owns its callback journal at `$STATE_DIRECTORY/outbound-receipts`. The gateway unit supplies a gateway-specific `StateDirectory=` with `StateDirectoryMode=0700`; the directory and its mode-`0600` files are owned and readable only by that gateway's service user. The send-boundary patch persists one sanitized per-client-ID JSON entry using a safe fixed-width digest filename: same-directory temporary file, file `fsync`, atomic rename to `.pending`, then directory `fsync`. Records contain only bounded IDs, send-success, attempt count, and next-attempt metadata—no bodies, quotes, attachments, signatures, credentials, key material, or provider payloads. Startup recovery and a background worker perform bounded authenticated callback retries without invoking Weixin send again. A pending record is deleted and the directory `fsync`ed only after an authenticated application ACK. Python owns receipt/outbox/worker storage and has no second send journal. Missing exact binding records `EVIDENCE_REQUIRED`, null provider ID, hard stop; `Date.now()` and local `_ms` fields remain telemetry only.
-
-- [ ] Rehydrate the stable ledger and require latest label `B3` before evidence collection.
-- [ ] Execute evidence collectors first. Current expected result is `EVIDENCE_REQUIRED`; stop with no runtime edit, B4 commit, or ledger append.
-- [ ] After future exact binding acceptance, add RED tests for replay/collision/lease/unknown/dead, HTTP schema, 140/150 budgets, idempotency branches, the exact receipt signing role, exact provider mapping, ledger quote, `$STATE_DIRECTORY/outbound-receipts` resolution, directory/file ownership and `0700`/`0600` modes, file/directory `fsync`, atomic `.pending` rename, startup/background bounded retry, no-body/no-secret persistence, no content resend, and authenticated-ACK-only delete plus directory `fsync`.
-- [ ] Run initial RED:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' \
-  python3 -m pytest tests/v2r1/test_outbox.py tests/v2r1/test_hermes_http.py \
-    tests/v2r1/test_outbound_receipt.py tests/integration/test_v2r1_delivery_flow.py \
-    tests/test_weixin_outbound_quote_timestamp.py tests/test_weixin_outbound_receipt_boundary.py -q
-node --test openclaw/plugins/aios-tenant-boundary/test/receipt-client.test.js
-```
-
-Expected RED after evidence acceptance: modules absent.
-
-- [ ] Implement outbox, bounded HTTP adapter/worker, authenticated callback client, Node-owned durable callback journal, actual Weixin send-boundary patch, role-authenticated receipt route, exact Python receipt store, and outbound ledger append only after exact binding. Run Python, Node, both patchers twice for byte-idempotence, actual send-boundary, full, and loader tests; expected GREEN, with callback failure journaled without resend, timeout ambiguity `delivery_unknown`, and no exactly-once assertion.
-- [ ] Commit exactly 19 paths:
-
-```bash
-git add active-runtime/app/aios_v2r1/outbox.py active-runtime/app/aios_v2r1/hermes_http.py \
-  active-runtime/app/aios_v2r1/hermes_worker.py active-runtime/app/aios_v2r1/outbound_receipt.py \
-  active-runtime/app/aios_v2r1/ingress_service.py active-runtime/app/aios_v2r1/message_ledger.py \
-  tests/v2r1/test_outbox.py tests/v2r1/test_hermes_http.py tests/v2r1/test_outbound_receipt.py \
-  tests/integration/test_v2r1_delivery_flow.py fixes/patch_openclaw_weixin_outbound_quotes.py \
-  fixes/patch_openclaw_weixin_outbound_receipts.py openclaw/plugins/aios-tenant-boundary/dist/receipt-client.js \
-  openclaw/plugins/aios-tenant-boundary/dist/outbound-receipt-journal.js \
-  openclaw/plugins/aios-tenant-boundary/test/receipt-client.test.js tests/test_weixin_outbound_quote_timestamp.py \
-  tests/test_weixin_outbound_receipt_boundary.py release/v2r1c0-rc1/hermes-http-contract-evidence.json \
-  release/v2r1c0-rc1/weixin-outbound-binding-evidence.json
-git commit -m "feat(v2r1): dispatch through evidenced Hermes outbox"
-```
-
-### Review B4
-
-- [ ] Require exactly 19 paths, accepted evidence digests, `git diff --check`, Python/Node/patcher/send-boundary/full/loader tests.
-- [ ] Prove 150 exceeds exact 140 and no 120-second production deadline remains.
-- [ ] Search changed files for exactly-once claims and timestamp/approximate binding; require none.
-- [ ] Require B4 parent equals B3. If either evidence remains unresolved, correct result is STOP with no commit.
-- [ ] After all prior B4 review checks pass, append B4 and verify the recorded commit identity:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-printf 'B4\t%s\t%s\t%s\n' "$(git rev-parse HEAD)" "$(git rev-parse HEAD^)" "$(git rev-parse HEAD^{tree})" >>"$ledger"
-IFS=$'\t' read -r label sha parent tree < <(tail -n 1 "$ledger")
-test "$label" = B4
-test "$sha" = "$(git rev-parse HEAD)"
-test "$parent" = "$(git rev-parse HEAD^)"
-test "$tree" = "$(git rev-parse HEAD^{tree})"
-```
-
----
-
-## Task B5: Build digest-bound isolated candidate staging and rollback
-
-**Evidence gate before code:** accepted B3/B4 ledger entries. `capture_live_preflight.py` creates one evidence file containing a reconciled Gitea branch-consistency sentinel (`status=healthy`, `drift_count=0`, refs matching candidate) and the V1R4C6 live snapshot (host identity, capture time, Git SHA, units, commands, listeners, OpenClaw version, config/plugin digests, credential metadata, state/database paths, mounts, active artifact, rollback target). `release_ctl.py --preflight-file` validates the schema, exact current host, sentinel, all required fields, and freshness no older than 300 seconds. Stop if either record is missing, stale, host-mismatched, malformed, or inconsistent before staging or promotion.
-
-**Files:**
-
-- Create: `deploy/v2r1/release_ctl.py`
-- Create: `deploy/v2r1/capture_live_preflight.py`
-- Modify: `deploy/v2r1/install.sh`, `deploy/v2r1/validate.sh`, `deploy/v2r1/healthcheck.sh`
-- Create: `deploy/v2r1/rollback.sh`
-- Create: `deploy/v2r1/aios-v2r1-candidate-gateway.service`
-- Create: `deploy/v2r1/aios-v2r1-production-gateway.service`
-- Create: `deploy/v2r1/aios-v2r1-ingress.service`
-- Create: `deploy/v2r1/aios-v2r1-hermes-worker.service`
-- Create: `deploy/v2r1/openclaw-candidate.json5`
-- Create: `release/v2r1c0-rc1/FLEET_UNSUPPORTED`
-- Create: `tests/deploy/test_v2r1_release_contract.py`
-- Modify: `release/v2r1c0-rc1/RELEASE.md`
-
-**Exact contract:** `python3 deploy/v2r1/release_ctl.py` exposes only `build`, `stage`, `verify-stage`, `promote`, `status`, and `rollback`. Forward states are exactly `BUILT -> STAGED -> STAGE_VERIFIED -> PRODUCTION`; rollback states are `ROLLBACK_STARTED -> ROLLED_BACK|ROLLBACK_FAILED`. Forward commands accept `--preflight-file`; callers supply no artifact, reconciled-sentinel, or runtime-snapshot digest strings. The controller validates the evidence and computes/persists all three digests internally. `verify-stage` and `promote` each recapture live evidence with the collector, revalidate it, recompute the triplet, and reject any drift from the recorded candidate state. Deterministic same bytes stage/prod; isolated users/state/config/ports/credentials; `LoadCredential=` least-role delivery; linked candidate plugin with runtime inspect, `allowConversationAccess=true`, config validate, doctor, inspect; `NOOP_DIGEST_MATCH` zero mutation/controller calls. Candidate and production gateway units use distinct dedicated users and distinct `StateDirectory=` values (`aios-v2r1-candidate-gateway` versus `aios-v2r1-production-gateway`), both set `StateDirectoryMode=0700`, and resolve journals only below their own `$STATE_DIRECTORY/outbound-receipts`; sharing, symlinking, or bind-mounting journal state is forbidden. The current root-run production gateway remains root-owned only until its audited migration; candidate staging never reads it, and migrated mode-`0600` records become readable only by the production gateway user. STOP blocks forward actions but permits only `rollback --rollback-only --to-previous-recorded --reason-file "$reason_file"`; exact prior digest/snapshot, no forward migration, cannot remove STOP, audited.
-
-- [ ] Rehydrate the stable ledger and require latest label `B4` before live evidence capture.
-- [ ] Add RED release tests for deterministic builds, dirty/secret rejection, rejection of caller digest arguments, preflight schema/required fields/exact-host/sentinel/freshness-at-300-seconds, tamper and recapture drift, isolated config, loader sequence, unit credentials, candidate/production service-user ownership, exact distinct `StateDirectory=` names and paths, `StateDirectoryMode=0700`, journal file mode `0600`, no shared/symlink/bind-mounted journal state, root-production transition only during audited migration, no-op, STOP forward block, constrained rollback, readiness timeout, and prior integrity.
-- [ ] Run initial RED:
-
-```bash
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' python3 -m pytest tests/deploy/test_v2r1_release_contract.py -q
-```
-
-Expected RED: driver, collector, units/config, rollback wrapper, lifecycle absent.
-
-- [ ] Implement deterministic artifact and the executable state machine; wrappers never switch branches/create tags/edit baseline/version/suppress errors. Exercise exact commands:
-
-```bash
-preflight_file="$(mktemp)"
-python3 deploy/v2r1/capture_live_preflight.py --output "$preflight_file"
-python3 deploy/v2r1/release_ctl.py build --source "$source_sha" --output "$build_dir" --preflight-file "$preflight_file"
-python3 deploy/v2r1/release_ctl.py stage --artifact "$artifact" --preflight-file "$preflight_file" --root "$release_root"
-python3 deploy/v2r1/release_ctl.py verify-stage --preflight-file "$preflight_file" --root "$release_root"
-python3 deploy/v2r1/release_ctl.py promote --preflight-file "$preflight_file" --root "$release_root"
-python3 deploy/v2r1/release_ctl.py status --root "$release_root"
-python3 deploy/v2r1/release_ctl.py rollback --root "$release_root" --rollback-only --to-previous-recorded --reason-file "$reason_file"
-```
-
-Expected GREEN: the collector creates the evidence file; the controller accepts no caller digest strings, validates it, and computes the artifact/sentinel/runtime triplet internally. State records advance only through `BUILT,STAGED,STAGE_VERIFIED,PRODUCTION`; `verify-stage` and `promote` recapture current live state and require the same triplet; rollback records `ROLLBACK_STARTED` then `ROLLED_BACK` or `ROLLBACK_FAILED`.
-- [ ] Execute candidate loader in isolated environment:
-
-```bash
-tmp="$(mktemp -d)"
-candidate_release="$tmp/release/current"
-export OPENCLAW_STATE_DIR="$tmp/openclaw-state"
-export OPENCLAW_CONFIG_PATH="$tmp/openclaw-state/openclaw.json"
-mkdir -p "$OPENCLAW_STATE_DIR"
-openclaw plugins install --link "$candidate_release/openclaw/plugins/aios-tenant-boundary"
-openclaw plugins inspect aios-tenant-boundary --runtime --json >"$tmp/plugin-before.json"
-openclaw config set plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess true --strict-json
-openclaw config validate
-set +e
-openclaw doctor --lint --json >"$tmp/doctor-lint.json"
-doctor_rc=$?
-set -e
-test "$doctor_rc" = 0 || test "$doctor_rc" = 1
-python3 - "$tmp/doctor-lint.json" <<'PY'
-import json, sys
-data = json.load(open(sys.argv[1]))
-def walk(value):
-    if isinstance(value, dict):
-        yield value
-        for child in value.values(): yield from walk(child)
-    elif isinstance(value, list):
-        for child in value: yield from walk(child)
-bad = [item for item in walk(data) if str(item.get("severity", "")).lower() in {"error", "fatal"} and "plugin" in json.dumps(item).lower()]
-assert not bad, bad
-PY
-openclaw doctor --post-upgrade --json >"$tmp/doctor-plugin.json"
-openclaw plugins inspect aios-tenant-boundary --runtime --json >"$tmp/plugin-after.json"
-```
-
-Expected GREEN: plugin path inside candidate; config validation and post-upgrade doctor exit 0; lint doctor exits 0 or 1, warnings are allowed, and parsed JSON has zero error/fatal plugin findings; final inspect proves three hooks/permission; active V1R4C6 paths are absent.
-
-- [ ] Run release/full Python/Node/loader tests, two byte-identical builds, and refreshed sentinel/snapshot comparisons. Expected GREEN: all pass.
-- [ ] Commit exactly 14 paths and append ledger:
-
-```bash
-git add deploy/v2r1/release_ctl.py deploy/v2r1/capture_live_preflight.py deploy/v2r1/install.sh \
-  deploy/v2r1/validate.sh deploy/v2r1/healthcheck.sh deploy/v2r1/rollback.sh \
-  deploy/v2r1/aios-v2r1-candidate-gateway.service deploy/v2r1/aios-v2r1-production-gateway.service \
-  deploy/v2r1/aios-v2r1-ingress.service \
-  deploy/v2r1/aios-v2r1-hermes-worker.service deploy/v2r1/openclaw-candidate.json5 \
-  release/v2r1c0-rc1/FLEET_UNSUPPORTED tests/deploy/test_v2r1_release_contract.py release/v2r1c0-rc1/RELEASE.md
-git commit -m "deploy(v2r1): bind candidate release to live evidence"
-```
-
-### Review B5
-
-- [ ] Require exactly 14 paths, no live secret/snapshot payload in Git, `git diff --check`, complete tests, two identical builds.
-- [ ] Inspect both gateway units and acceptance-test distinct service users, distinct `StateDirectory=` names/absolute paths, `StateDirectoryMode=0700`, mode-`0600` journal files, and no shared, symlinked, or bind-mounted receipt journal.
-- [ ] Prove candidate paths never resolve active V1R4C6; STOP blocks forward while rollback selects only recorded previous state and cannot remove STOP.
-- [ ] Prove staging validates the collector-created file and `verify-stage`/`promote` each recapture current live sentinel/runtime state, compute digests internally, and compare the same triplet; prove no caller-supplied digest option exists.
-- [ ] Require B5 parent equals B4.
-- [ ] After all prior B5 review checks pass, append B5 and verify the recorded commit identity:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-printf 'B5\t%s\t%s\t%s\n' "$(git rev-parse HEAD)" "$(git rev-parse HEAD^)" "$(git rev-parse HEAD^{tree})" >>"$ledger"
-IFS=$'\t' read -r label sha parent tree < <(tail -n 1 "$ledger")
-test "$label" = B5
-test "$sha" = "$(git rev-parse HEAD)"
-test "$parent" = "$(git rev-parse HEAD^)"
-test "$tree" = "$(git rev-parse HEAD^{tree})"
-```
-
-## Final five-commit verification
-
-Run only after all evidence/task reviews pass:
-
-```bash
-ledger="$(git rev-parse --git-path v2r1-blocker-ledger.tsv)"
-python3 - "$ledger" <<'PY'
-from pathlib import Path
-import subprocess, sys
-rows = [line.split("\t") for line in Path(sys.argv[1]).read_text().splitlines()]
-assert [row[0] for row in rows] == ["START", "B1", "B2", "B3", "B4", "B5"]
-for i in range(1, len(rows)):
-    label, sha, recorded_parent, recorded_tree = rows[i]
-    parent = subprocess.check_output(["git", "rev-parse", sha + "^"], text=True).strip()
-    tree = subprocess.check_output(["git", "rev-parse", sha + "^{tree}"], text=True).strip()
-    assert parent == rows[i - 1][1]
-    assert parent == recorded_parent and tree == recorded_tree, label
-start, head = rows[0][1], rows[-1][1]
-assert subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip() == head
-assert subprocess.check_output(["git", "rev-list", "--count", f"{start}..{head}"], text=True).strip() == "5"
-assert not subprocess.check_output(["git", "rev-list", "--merges", f"{start}..{head}"], text=True).strip()
-PY
-test -z "$(git status --porcelain)"
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' python3 -m pytest --collect-only -q
-PYTHONDONTWRITEBYTECODE=1 PYTEST_ADDOPTS='-p no:cacheprovider' PYTHONPATH='active-runtime:active-runtime/app' python3 -m pytest -q
-(cd openclaw/plugins/aios-tenant-boundary && npm test)
-```
-
-Expected: labels exactly `START,B1,B2,B3,B4,B5`; current HEAD/parent/tree match recorded values; `START..HEAD` has exactly five commits and no merge; clean tree; full collect/full Python/Node/loader/release tests pass.
-
-Review authority roles, status spelling, timeout units, routes, response bounds, terminal semantics, evidence states, types, and sentinel behavior. Scan unresolved markers with split literals:
-
-```bash
-marker_pattern="$(printf '%s' 'TO''DO|T''BD|FIX''ME|CHANGE''_ME|INSERT''_')"
-git grep -nE "$marker_pattern" -- active-runtime deploy/v2r1 openclaw/plugins/aios-tenant-boundary release/v2r1c0-rc1 tests
-```
-
-Expected: no matches. Any contradiction, type mismatch, unresolved evidence, extra blocker commit, or missing review stops release preparation.
-
-## Appendix A: Exact legacy `active_runtime.app` import files
-
-`APPENDIX_A_BEGIN`
-- tests/test_agent_event_bus.py
-- tests/test_agent_observability_loop.py
-- tests/test_architect_governance.py
-- tests/test_architect_research_timeline.py
-- tests/test_architecture_change_classifier.py
-- tests/test_architecture_owner_gate.py
-- tests/test_architect_weekly_research.py
-- tests/test_change_governance.py
-- tests/test_governance_event_bridge.py
-- tests/test_governance_timeline.py
-- tests/test_search_agent_adapter.py
-- tests/test_search_architect_integration.py
-- tests/test_search_gateway_dashboard.py
-- tests/test_search_gateway_general_capability.py
-- tests/test_search_gateway_orchestrator.py
-- tests/test_search_gateway.py
-- tests/test_search_provider_registry.py
-- tests/test_task_center.py
-- tests/test_task_dashboard_view.py
-- tests/test_task_event_and_statistics.py
-- tests/test_task_lifecycle.py
-- tests/test_task_orchestrator.py
-- tests/test_v1r4c1_risk_fixes.py
-`APPENDIX_A_END`

docs/superpowers/specs/2026-07-14-v2r1-runtime-bridge-design.md

@@ -1,287 +0,0 @@
-# V2R1 Authenticated Runtime Bridge Design
-
-**Date:** 2026-07-14
-**Status:** Preflight design — B3/B4/B5 evidence-gated
-**Release target:** V2R1C0 RC1
-**Scope:** Executable OpenClaw policy compatibility, canonical Python packaging, authenticated Weixin loopback ingress, exact message authority, real Hermes HTTP dispatch, and digest-bound release operations.
-
-## Decision and execution gates
-
-Three alternatives were evaluated:
-
-- **Alternative A — preserve the verified replay and stop at documentation.** Lowest immediate risk, but every runtime release blocker remains open.
-- **Alternative B — patch only the Weixin path.** Demonstrates a message path but cannot prove plugin loading, transport authority, durable dispatch, artifact identity, or rollback.
-- **Alternative C — close five independently reviewed blockers.** Prove the plugin, package one Python namespace, build the authenticated bridge, connect a durable outbox to the real Hermes HTTP router, then rehearse a digest-bound release.
-
-Alternative C remains the selected architecture because active full-execution authorization covers implementation preparation. That authorization does not waive the following gates:
-
-- B1 and B2 may start only after this corrected design and plan are reviewed.
-- B3 stops unless the installed Weixin payload shape, patch target hashes, authority-map ownership, and transport signing boundary are evidenced.
-- B4 stops unless Hermes request/response schema, router ownership, downstream timeout, idempotency behavior, and exact outbound message binding are evidenced.
-- B5 stops unless B3 and B4 are accepted and the reconciled sentinel plus the V1R4C6 live-runtime snapshot are current for the candidate digest.
-
-The present outbound evidence is insufficient, so B4 and B5 are currently stopped. This document defines the fail-closed path; it does not claim the missing evidence exists.
-
-## Verified preflight observations
-
-Read-only inspection on 2026-07-14 established these facts:
-
-- OpenClaw is `2026.6.11` and exposes `plugins install --link`, `plugins inspect --runtime --json`, `config set`, `config validate`, and `doctor`.
-- The OpenClaw schema requires a non-bundled plugin to opt into conversation-bearing hooks with `plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess=true`.
-- Without that opt-in, the tenant-boundary plugin's currently usable policy hook is `before_tool_call`; `before_agent_run` and `agent_end` cannot be treated as delivered authority.
-- `aios-hermes-router.service` owns `/opt/aios-v23/shared/hermes_route_memory/hermes_router_service.py` and listens on `127.0.0.1:18791`.
-- `GET http://127.0.0.1:18791/health/ready` returns router readiness and identifies the executor health URL.
-- `POST http://127.0.0.1:18791/internal/hermes/route` is the router submission endpoint.
-- The router forwards to the executor with an exact 140-second timeout. The existing direct Weixin helper uses 120 seconds, so it is incompatible and cannot be reused as the worker deadline.
-- Router ownership and schema are inspectable, but replay/idempotency behavior for repeated `route_id` is not proved.
-- A Weixin reference event exposes `ref_msg.message_item.msg_id` and `ref_msg.message_item.create_time_ms`, but not the original outbound `client_id`. The send acknowledgement exposes only `ret` and `errmsg`. No exact `client_id -> message_id` binding currently exists.
-
-## Execution modes and terminal semantics
-
-The gateway has exactly two modes:
-
-- `disabled`: the V2R1 bridge performs no submission and the legacy message path may run.
-- `enforced`: every eligible Weixin event is handled by the V2R1 bridge. The legacy path is prohibited.
-
-There is no shadow, dual-send, or fall-through mode. In `enforced` mode:
-
-- `ACCEPTED` is terminal. The Node caller must not invoke the legacy handler, Hermes directly, or a second transport path.
-- A duplicate with the same canonical event and payload returns the same accepted receipt and is also terminal.
-- `AUTH_FAILED`, `VALIDATION_FAILED`, `CONFLICT`, and `INTERNAL_ERROR` are terminal runtime results for that attempt. They never authorize legacy fallback. `REPLAY_REJECTED` belongs only to the authenticated HTTP transport/service boundary and is never a `RuntimeIngressResponse.status`.
-- A transport timeout requires a receipt-status query. A retry is allowed only when the status is absent and must use a fresh nonce while retaining the same exact event identity.
-
-Legacy handling is therefore reachable only when configuration explicitly says `disabled`, never as error recovery.
-
-## Architecture and data flow
-
-```text
-Authenticated Weixin event in isolated OpenClaw candidate gateway
-  -> Node bridge client reads bridge credential from CREDENTIALS_DIRECTORY
-  -> Node signs the exact method/path/unsigned_body object and POSTs the outer wrapper to 127.0.0.1
-  -> Python ingress service authenticates freshness, nonce, key role, and replay
-  -> server-side WeixinProjection parses exact protocol evidence
-  -> server-side root-owned authority map supplies tenant/cell/principal/session
-  -> Python signs an internal RuntimeWiring request with a separate key role
-  -> RuntimeWiring.ingest -> TenantRouter -> MessageLedger -> SessionPool
-  -> ingress receipt reaches terminal ACCEPTED
-  -> HermesOutbox -> dedicated Hermes worker
-  -> HermesHttpAdapter -> 127.0.0.1:18791/internal/hermes/route
-  -> Weixin send boundary -> outbound receipt evidence
-```
-
-Node never constructs `CanonicalMessage`, never opens the authority map, and never supplies tenant or cell authority. Python never trusts route claims from the raw Weixin object. The root-owned authority map is keyed by authenticated account, sender, and conversation evidence; its result is still re-resolved through `TenantRouter` before mutation.
-
-## One POST signing contract
-
-Every authenticated POST route uses exactly one wire shape; there is no `auth`, authorization header, nested signature, or route-specific signing variant:
-
-```json
-{"unsigned_body":{"schema_version":"aios.signed-request.v1","key_id":"bridge-current","issued_at_ms":1784000000000,"nonce":"base64url-16-byte-value","route_payload":{}},"signature":"lowercase-64-hex"}
-```
-
-`unsigned_body` contains exactly `schema_version`, `key_id`, `issued_at_ms`, `nonce`, and `route_payload`. `route_payload` is the route-specific content: ingress account/sender/conversation/raw event, receipt-status account plus one identifier, or outbound receipt. The signer constructs exactly:
-
-```json
-{"method":"POST","path":"<exact route>","body":{"schema_version":"aios.signed-request.v1","key_id":"bridge-current","issued_at_ms":1784000000000,"nonce":"base64url-16-byte-value","route_payload":{}}}
-```
-
-The signing input is canonical JSON encoded as UTF-8, with object keys recursively sorted by Unicode code point, `,` and `:` separators, no insignificant whitespace, no ASCII escaping of Unicode, no floats, and protocol IDs represented as strings. `signature` is lowercase 64-hex HMAC-SHA256 of those bytes. It is outside `unsigned_body` and outside the signing input. Verification reconstructs the same object using literal method `POST` and the exact request path; no normalized, decoded, prefix-matched, or caller-declared path is accepted.
-
-Transport authentication is fail-closed:
-
-- accepted clock skew is at most 30 seconds in either direction;
-- `(key_id, nonce)` is retained in a durable replay cache for five minutes;
-- a nonce decoding to any length other than 16 bytes is rejected;
-- a repeated nonce is `REPLAY_REJECTED`, even when payload and signature are identical;
-- every retry creates a cryptographically fresh nonce and `issued_at_ms` while preserving the exact event/message identity used for idempotency;
-- the keyring contains one active key and at most one previous key; `key_id` selects the key and unknown IDs fail;
-- rotation first installs the new verifier key, then switches the Node signer, then removes the old key only after the five-minute replay window and maximum request lifetime have elapsed.
-
-The Node candidate gateway receives the bridge-ingress and receipt-read keyrings through separate systemd `LoadCredential=` entries below `$CREDENTIALS_DIRECTORY`. It never receives the Python internal signing key or authority map. Only after B4 evidence is accepted, the Node Weixin sender receives a third, separate `outbound-receipt-write` credential for authenticated callbacks.
-
-## Service routes and bounded responses
-
-The Python service binds loopback only and exposes exactly:
-
-- `GET /health/live`
-- `GET /health/ready`
-- `POST /v1/ingress`
-- `POST /v1/receipts/status`
-- `POST /v1/outbound-receipts`
-
-`POST /v1/ingress` requires the `bridge-ingress` HMAC role. `POST /v1/receipts/status` requires `receipt-read`; its `route_payload` contains `account_id` plus exactly one of `event_id` or `receipt_id`. Both or neither is `VALIDATION_FAILED`. Resolution is restricted to the same account and event scope, and unknown/cross-account identifiers return the same bounded result. `POST /v1/outbound-receipts` requires `outbound-receipt-write`; no receipt role can submit ingress. Every route uses the one POST signing contract above and the same nonce, skew, replay, rotation, and fresh-retry rules.
-
-Request bodies are at most 1 MiB. Any JSON response is at most 4096 bytes and contains only stable codes and bounded identifiers. The ingress response fields are `status`, `event_id`, `message_id`, and `receipt_id`. The receipt-status response fields are `status`, `receipt_id`, `event_id`, `updated_at`, `outbox_status`, `outbound_status`, and `evidence_state`. No response contains message bodies, quote text, attachments, route objects, paths, signatures, keys, provider payloads, or exception text.
-
-Runtime-to-HTTP status mapping is exact:
-
-| Stable status | HTTP | Retry rule |
-|---|---:|---|
-| `ACCEPTED` | 202 | Terminal; query receipt after transport uncertainty |
-| `AUTH_FAILED` | 401 | No retry until credential or authority changes |
-| `REPLAY_REJECTED` | 409 | Transport/service only; retry same event with a fresh nonce |
-| `VALIDATION_FAILED` | 400 | No retry |
-| `CONFLICT` | 409 | Operator review |
-| `INTERNAL_ERROR` | 503 | Query receipt first; identical event may retry with fresh nonce |
-
-## Canonical Python package
-
-The release package has one V2R1 import identity: `aios_v2r1`. There is no `active_runtime` compatibility shim, alias package, `sys.modules` alias, or copied source tree.
-
-`active-runtime/pyproject.toml` packages `aios_v2r1` from `active-runtime/app`. Repository tests use `PYTHONPATH='active-runtime:active-runtime/app'`: legacy modules import as `app.*`, while V2R1 imports as `aios_v2r1.*`. The implementation plan enumerates all 23 known `active_runtime.app` test imports and replaces them explicitly. Full collection, full pytest, and wheel inspection must prove the wheel contains one V2R1 namespace and that source and installed imports resolve to `aios_v2r1` only.
-
-## Exact projection, quote, and attachment authority
-
-`WeixinProjection` runs in Python after transport authentication. It preserves numeric Weixin IDs from the JSON token as decimal strings and rejects a value that has already passed through unsafe JavaScript-number conversion.
-
-- `event_id` is deterministic from authenticated account, sender, conversation, direction, and exact protocol event ID.
-- `message_id` is an exact provider/server message ID when supplied.
-- `reply_to_message_id` comes only from an explicit reference ID.
-- `quoted_body` comes only from explicit referenced text or from `MessageLedger.resolve_quote()` using the fully scoped exact message ID.
-- Timestamp, nearest-message order, recent-message cache, numeric approximation, prefix, similarity, and local client ID are never quote authority.
-
-`CanonicalAttachment` contains `attachment_id`, `kind`, `media_type`, `sha256`, and `size_bytes`. Attachment bytes are accepted only when exact protocol identity and digest/size verification both pass. A reference without exact media evidence cannot fall back to the latest image.
-
-`Date.now()` is local send telemetry only. It may populate a local observation timestamp but cannot populate a provider timestamp, resolve a quote, correlate a client ID, or select a message.
-
-## Outbound evidence and hard stop
-
-The current Weixin protocol evidence cannot bind an outbound client ID to a later reference:
-
-- send acknowledgement: `ret` and `errmsg` only;
-- later reference: `ref_msg.message_item.msg_id` and `ref_msg.message_item.create_time_ms`;
-- absent evidence: the original outbound `client_id` echoed beside the provider `message_id`.
-
-Therefore outbound quote authority is unavailable. A successful send may be recorded as transport success, but `OutboundReceipt.evidence_state` must be `EVIDENCE_REQUIRED`, and the release gate must hard STOP. `sent` does not mean `confirmed`, and neither timestamp equality nor proximity may upgrade it.
-
-The only acceptable future unlock is verified provider/reference evidence that echoes or otherwise exactly binds `client_id -> message_id`. That evidence must include the raw protocol fields, parser test, collision test, and a durable mapping scoped by tenant, cell, account, peer, direction, and exact IDs. Until then no outbound record becomes quote authority.
-
-`OutboundReceipt` has stable fields:
-
-```text
-receipt_id, outbox_id, tenant_id, cell_id, channel, channel_account_id,
-peer_id, client_message_id, provider_message_id, payload_sha256,
-status = sent | confirmed | failed,
-evidence_state = EXACT | EVIDENCE_REQUIRED
-```
-
-`provider_message_id` is null while evidence is unavailable. `POST /v1/outbound-receipts` rejects any attempt to synthesize it from `Date.now()`, `ref_msg.message_item.create_time_ms`, message order, or approximate matching. Every local timestamp field is explicitly suffixed `_ms` and remains telemetry.
-
-After B4 evidence is accepted, the actual Node Weixin sender owns its outbound callback retry journal at `$STATE_DIRECTORY/outbound-receipts`. Its systemd unit declares a gateway-specific `StateDirectory=` and `StateDirectoryMode=0700`; systemd owns that directory to the unit's `User=`/`Group=`, and no other gateway service user may read it. The sender receives its separate `outbound-receipt-write` `LoadCredential=` entry only at that gate. Each journal entry is one sanitized JSON record per client ID, named by a safe fixed-width digest of that ID. It contains only bounded identifiers, send-success state, callback-attempt count, and next-attempt metadata—never message bodies, quote text, attachments, signatures, key material, credentials, or provider payloads.
-
-Persistence is exact: create a same-directory temporary file with mode `0600`, owned and readable only by that gateway's service user, write the sanitized record, `fsync` the file, atomically rename it to its final `.pending` name, then `fsync` the directory. Startup recovery and a background worker retry authenticated callbacks with bounded attempts and backoff; they never call the Weixin send operation again. A pending record is deleted, followed by directory `fsync`, only after the Python callback returns an authenticated application ACK. Transport uncertainty, non-ACK responses, and callback authentication failures retain the record for bounded retry.
-
-Ownership is deliberately split. Node owns this send-success/callback-retry journal. Python owns the authenticated receipt endpoint, receipt store, outbox, and Hermes worker state. Python does not create or own a second send journal, so there is only one durable resend boundary.
-
-## Real Hermes HTTP adapter and outbox semantics
-
-The runtime does not claim that the local `HermesFabric` SQLite primitive is the production Hermes transport. Production dispatch uses:
-
-- readiness: `GET http://127.0.0.1:18791/health/ready`;
-- submission: `POST http://127.0.0.1:18791/internal/hermes/route`;
-- owner: `aios-hermes-router.service`;
-- downstream executor budget: exactly 140 seconds;
-- worker HTTP deadline: 150 seconds, so the known 120-second direct-bridge mismatch is removed.
-
-`HermesHttpAdapter` validates bounded request and response schemas before accepting a result. `HermesOutbox` provides durable intent and leases, but the system makes no exactly-once claim. Exact local states are `pending`, `leased`, `delivered`, `delivery_unknown`, and `dead`.
-
-Repeated delivery behavior depends on evidence:
-
-- if the verified router contract proves the same `route_id` and payload digest are idempotent, an expired/failed attempt may retry with that exact pair;
-- if idempotency is false, the worker never automatically retries an ambiguous submission;
-- if idempotency is unresolved, B4 stops before implementation and commit;
-- a client timeout or connection loss after send becomes `delivery_unknown`, never a fabricated failure or success.
-
-B4 evidence must record the live listener, owning unit, executable/source digest, readiness response schema, route request fields, route response fields, exact 140-second downstream timeout, router tenant/user ownership rules, and repeated-`route_id` behavior. The dedicated `aios-v2r1-hermes-worker.service` is installed only in B5 after this evidence is accepted.
-
-## OpenClaw plugin compatibility and permissions
-
-The plugin configuration contract is exact:
-
-- `blockUnknownAgentRuns`: boolean, default `false`;
-- `approvalTimeoutMs`: integer, minimum `1000`, maximum `300000`, default `60000`;
-- package and manifest versions are identical;
-- every property read by runtime code appears in `configSchema`.
-
-Unit tests with a fake API remain useful, but they are insufficient. B1 must run the real OpenClaw loader in an isolated state/config directory. It must prove two permission states:
-
-1. Default hook permissions: runtime inspection shows only `before_tool_call` is usable for this plugin; no test treats `before_agent_run` provenance as present.
-2. Explicit conversation access: set `plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess=true`, validate config, reload/inspect runtime, and prove `before_agent_run`, `before_tool_call`, and `agent_end` are installed.
-
-The default remains fail-closed for side effects because absent run provenance cannot authorize them. Candidate production never relies on the default-only state; the isolated staging config explicitly opts in and is validated.
-
-## Isolated candidate staging and plugin loader sequence
-
-B5 defines separate staging and production gateway units plus the isolated ingress and worker units. Staging starts the candidate trio; production gateway activation occurs only through the evidence-gated promotion/migration:
-
-- `aios-v2r1-candidate-gateway.service`
-- `aios-v2r1-production-gateway.service`
-- `aios-v2r1-ingress.service`
-- `aios-v2r1-hermes-worker.service`
-
-The candidate gateway uses its dedicated service user with `StateDirectory=aios-v2r1-candidate-gateway`; the migrated production gateway uses a different dedicated service user with `StateDirectory=aios-v2r1-production-gateway`. Both units set `StateDirectoryMode=0700`, and both resolve their journal only as `$STATE_DIRECTORY/outbound-receipts`. The names, absolute paths, owners, and journal contents are distinct; staging and production never share, bind-mount, or symlink journal state. The current root-run production gateway retains its own root-owned state only until an explicit audited migration. Candidate staging never reads that state. Migration verifies pending records contain no bodies or secrets, installs them only into the production-specific directory with its service user ownership and mode `0600`, and leaves no root-owned production journal in active use.
-
-The candidate gateway has its own OpenClaw state directory, config file, port, credentials, and plugin link. It does not edit or restart the active V1R4C6 gateway. The loader sequence against the candidate state is fixed:
-
-```bash
-openclaw plugins install --link "$candidate_release/openclaw/plugins/aios-tenant-boundary"
-openclaw plugins inspect aios-tenant-boundary --runtime --json
-openclaw config set plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess true --strict-json
-openclaw config validate
-openclaw doctor --lint --json
-openclaw doctor --post-upgrade --json
-openclaw plugins inspect aios-tenant-boundary --runtime --json
-```
-
-The environment supplies the isolated config/state paths. Any command that resolves to the active V1R4C6 config is a hard stop. Inspection output must prove the linked candidate path, version, hooks, and permission state.
-
-## Artifact, preflight evidence, promotion, and rollback
-
-One deterministic archive and manifest are built from a clean reviewed commit. Staging and production consume byte-identical artifact digests. `NOOP_DIGEST_MATCH` returns exit 0 and performs no extraction, migration, symlink change, restart, or deployment audit increment.
-
-The executable controller is `python3 deploy/v2r1/release_ctl.py` with commands `build`, `stage`, `verify-stage`, `promote`, `status`, and `rollback`. Forward state transitions are exactly `BUILT -> STAGED -> STAGE_VERIFIED -> PRODUCTION`; skipping or reversing a forward edge is rejected. `capture_live_preflight.py` creates the evidence file and every mutating controller command accepts it as `--preflight-file`; callers never supply digest strings. The controller validates the evidence schema, exact host identity, reconciled sentinel health and candidate refs, required runtime fields, and capture freshness of at most 300 seconds. It then computes the artifact, reconciled-sentinel, and runtime-snapshot SHA-256 digests internally and persists that triplet in the state record.
-
-`verify-stage` and `promote` each invoke the live collector again, validate the fresh result by the same rules, recompute the triplet internally, and compare the recaptured live state with the recorded candidate state. Any host, sentinel, candidate-ref, runtime-field, artifact, or digest drift rejects the transition. `status` is read-only. Rollback transitions are `PRODUCTION -> ROLLBACK_STARTED -> ROLLED_BACK`; a failed recovery records `ROLLBACK_FAILED` without claiming the prior state is active. `NOOP_DIGEST_MATCH` leaves the current state and all three digests unchanged.
-
-Before staging and again before promotion, both pieces of live evidence are mandatory:
-
-- reconciled Gitea branch-consistency sentinel: `status=healthy`, `drift_count=0`, and recorded refs matching the candidate manifest;
-- V1R4C6 live-runtime snapshot: active Git SHA, service units, process commands, listener ports, OpenClaw version, config/plugin digests, credential metadata without secrets, state/database paths, mounts, current artifact identity, and rollback target.
-
-The snapshot is immutable, SHA-256-addressed, and timestamped. Promotion rejects a snapshot older than 300 seconds or any live drift from it. `capture_live_preflight.py` creates these evidence inputs from live inspection; `release_ctl.py` may validate and recapture them but may not invent missing fields or accept caller-asserted digests.
-
-The host sentinel `/var/lib/aios-v2r1/STOP` blocks forward mutation: install, migration, staging activation, promotion, candidate/production restart, and new artifact selection. It does not block one constrained recovery command:
-
-```text
-rollback --rollback-only --to-previous-recorded --reason-file "$reason_file"
-```
-
-That escape may only select the exact previous digest and its recorded compatible database snapshot; it cannot install new bytes, run forward migrations, choose an arbitrary digest, remove the sentinel, or start a new candidate. It writes an audit record before and after the attempt. If previous-state evidence is missing or fails digest/integrity checks, rollback also stops.
-
-The tracked `release/v2r1c0-rc1/FLEET_UNSUPPORTED` capability sentinel remains authoritative. `OpenClawFleet` and `openclaw fleet` are outside this release.
-
-## Stop conditions
-
-Preparation or release stops when any of these is true:
-
-- corrected design/plan review is not accepted;
-- a B3/B4/B5 evidence gate remains unresolved;
-- authoritative Git refs differ from reviewed values or the worktree is dirty;
-- the real plugin loader does not prove the required hook permissions;
-- transport key role, `key_id`, timestamp, exact nonce length, skew, replay cache, rotation, or fresh-retry behavior fails;
-- Node attempts projection/authority resolution or Python trusts route claims from the raw event;
-- `ACCEPTED` can fall through to legacy processing, or legacy runs while bridge mode is `enforced`;
-- quote or attachment resolution uses timestamp, approximation, recent order, or a local client ID;
-- outbound evidence remains `EVIDENCE_REQUIRED`;
-- Hermes schema, ownership, 140-second downstream budget, router identity rules, or repeated-route behavior is unresolved;
-- any code or document claims exactly-once Hermes delivery;
-- the candidate gateway is not isolated from V1R4C6;
-- reconciled sentinel or V1R4C6 live-runtime snapshot is absent, stale, inconsistent, or digest-invalid;
-- artifact, migration, staging, or production digest differs;
-- the STOP sentinel blocks a forward action;
-- constrained rollback cannot prove the exact previous artifact and compatible snapshot;
-- any main, tag, `VERSION`, baseline, live service, or deployment mutation occurs without the separate release authorization.
-
-## Acceptance
-
-The design is review-complete when the plan contains exactly five blocker commits, dynamically anchors their parent chain at B1 start, enumerates all legacy import edits, and has executable RED/GREEN/review gates. Runtime release acceptance additionally requires all B3/B4/B5 evidence gates, the full Python collection and suite, the real Node/OpenClaw loader harness, exact receipt semantics, isolated candidate staging, deterministic artifacts, current live evidence, and rehearsed constrained rollback.

openapi/aios-orchestrator-gateway.openapi.yaml

@@ -0,0 +1,228 @@
+openapi: 3.0.3
+info:
+  title: AIOS Orchestrator Gateway metadata API
+  version: 0.2.0
+servers:
+  - url: http://127.0.0.1:18920
+paths:
+  /v1/orchestrator/central/jobs/claim:
+    post:
+      summary: Claim one remote Codex decision job
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/RunnerId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required: [contract_commit]
+              properties:
+                contract_commit:
+                  type: string
+                  pattern: '^[0-9a-f]{40}$'
+      responses:
+        '200':
+          description: Job lease or no available job
+        '401':
+          description: Runner or token scope rejected
+        '409':
+          description: Contract or idempotency conflict
+  /v1/orchestrator/central/jobs/{job_id}/heartbeat:
+    post:
+      summary: Extend an active remote Codex job lease
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - $ref: '#/components/parameters/RunnerId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        $ref: '#/components/requestBodies/RemoteLeaseRequest'
+      responses:
+        '202': {description: Lease extended}
+        '401': {description: Runner, scope, or lease credential rejected}
+        '409': {description: Lease is stale or owned by another runner}
+  /v1/orchestrator/central/jobs/{job_id}/decision:
+    post:
+      summary: Submit one strict decision for a leased job
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - $ref: '#/components/parameters/RunnerId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required: [lease_token, claim_idempotency_key, decision]
+              properties:
+                lease_token: {type: string, pattern: '^[0-9a-f]{64}$'}
+                claim_idempotency_key: {type: string}
+                decision: {$ref: '#/components/schemas/Decision'}
+      responses:
+        '202': {description: Decision accepted and applied exactly once}
+        '401': {description: Runner, scope, or lease credential rejected}
+        '409': {description: State, contract, lease, or idempotency conflict}
+        '422': {description: Decision schema or allowed work-unit violation}
+  /v1/orchestrator/central/jobs/{job_id}/fail:
+    post:
+      summary: Fail a leased job into retry or dead-letter
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/JobId'
+        - $ref: '#/components/parameters/RunnerId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required: [lease_token, claim_idempotency_key, category]
+              properties:
+                lease_token: {type: string, pattern: '^[0-9a-f]{64}$'}
+                claim_idempotency_key: {type: string}
+                category: {type: string, pattern: '^[A-Za-z0-9_]{1,64}$'}
+      responses:
+        '202': {description: Failure recorded}
+        '401': {description: Runner, scope, or lease credential rejected}
+        '409': {description: Lease or idempotency conflict}
+  /v1/orchestrator/events:
+    post:
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '202':
+          description: Event accepted
+        '409':
+          description: Idempotency or state conflict
+        '422':
+          description: Invalid event
+  /v1/orchestrator/events/{event_id}:
+    get:
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: event_id
+          required: true
+          schema:
+            type: string
+            pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
+      responses:
+        '200':
+          description: Metadata-only event status
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required: [event_id, status, trigger_http_status, trigger_error_category, trigger_channel, remote_id, callback_state, callback_deadline, callback_attempts, decision_applied, state_version_after]
+                properties:
+                  event_id:
+                    type: string
+                  status:
+                    enum: [RECEIVED, AWAITING_DECISION, DECIDED, TRIGGER_FAILED, DEAD_LETTER]
+                  trigger_channel:
+                    type: string
+                    nullable: true
+                    enum: [workspace_agent, responses_api, codex_local, remote_codex]
+                  trigger_http_status:
+                    type: integer
+                    nullable: true
+                    minimum: 100
+                    maximum: 599
+                  trigger_error_category:
+                    type: string
+                    nullable: true
+                    enum: [UNAUTHORIZED, FORBIDDEN, NOT_FOUND, NOT_RUNNABLE, NETWORK_ERROR]
+                  remote_id:
+                    type: string
+                    nullable: true
+                  callback_state:
+                    enum: [PENDING, SENT, AWAITING_CALLBACK, CALLBACK_RECEIVED, APPLIED, STALE_SUPERSEDED, DEAD_LETTER]
+                  callback_deadline:
+                    type: integer
+                    nullable: true
+                    minimum: 0
+                  callback_attempts:
+                    type: integer
+                    minimum: 0
+                  decision_applied:
+                    type: boolean
+                  state_version_after:
+                    type: integer
+                    nullable: true
+                    minimum: 0
+        '401':
+          description: Missing or invalid bearer
+        '404':
+          description: Event not found
+components:
+  parameters:
+    JobId:
+      in: path
+      name: job_id
+      required: true
+      schema:
+        type: string
+        pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$'
+    RunnerId:
+      in: header
+      name: X-AIOS-Runner-ID
+      required: true
+      schema: {type: string, maxLength: 128}
+    IdempotencyKey:
+      in: header
+      name: Idempotency-Key
+      required: true
+      schema: {type: string, minLength: 16, maxLength: 128}
+  requestBodies:
+    RemoteLeaseRequest:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            additionalProperties: false
+            required: [lease_token, claim_idempotency_key]
+            properties:
+              lease_token: {type: string, pattern: '^[0-9a-f]{64}$'}
+              claim_idempotency_key: {type: string}
+  schemas:
+    Decision:
+      type: object
+      additionalProperties: false
+      required: [schema_version, project_key, contract_commit, event_id, expected_state_version, verdict, state_updates, next_work_units, requires_human_input, stop_reason]
+      properties:
+        schema_version: {type: integer, enum: [1]}
+        project_key: {type: string}
+        contract_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
+        event_id: {type: string}
+        expected_state_version: {type: integer, minimum: 0}
+        verdict: {type: string, enum: [BLOCKED, COMPLETE, DISPATCH, NOOP]}
+        state_updates: {type: array, items: {type: object}}
+        next_work_units: {type: array, items: {type: object}}
+        requires_human_input: {type: boolean}
+        stop_reason: {type: string, nullable: true}
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer

openclaw/plugins/aios-tenant-boundary/dist/index.js

@@ -1,111 +0,0 @@
-import {
-  classifyRun,
-  decideToolCall,
-  resolveSenderId,
-  runKey,
-} from "./policy.js";
-
-const MAX_RUN_AGE_MS = 60 * 60 * 1000;
-
-function prune(activeRuns, now = Date.now()) {
-  for (const [key, value] of activeRuns.entries()) {
-    if (now - value.recordedAt > MAX_RUN_AGE_MS) activeRuns.delete(key);
-  }
-}
-
-function approvalTimeout(config) {
-  const value = config.approvalTimeoutMs;
-  return Number.isInteger(value) && value >= 1000 && value <= 300000
-    ? value
-    : 60000;
-}
-
-export default {
-  id: "aios-tenant-boundary",
-  name: "AIOS Tenant Boundary",
-  description: "Fail-closed user-origin and side-effect policy for Tenant Cells.",
-
-  register(api) {
-    const activeRuns = new Map();
-
-    api.on(
-      "before_agent_run",
-      async (event, ctx) => {
-        prune(activeRuns);
-        const config = event.context?.pluginConfig ?? api.pluginConfig ?? {};
-        const trust = classifyRun(ctx, config);
-        const key = runKey(event, ctx);
-        const existing = key ? activeRuns.get(key) : undefined;
-        if (existing && existing.senderId !== trust.senderId) {
-          return {
-            outcome: "block",
-            reason: "run_scope_sender_conflict",
-            message: "This run scope is already bound to a different authenticated sender.",
-          };
-        }
-        if (key) {
-          activeRuns.set(key, { ...trust, recordedAt: Date.now() });
-        }
-
-        if (
-          config.blockUnknownAgentRuns === true &&
-          trust.trusted !== true &&
-          trust.reason !== "job_id_present"
-        ) {
-          return {
-            outcome: "block",
-            reason: trust.reason,
-            message: "This message cannot be verified as coming from the active authenticated user.",
-          };
-        }
-        return { outcome: "pass" };
-      },
-      { priority: 100 },
-    );
-
-    api.on(
-      "before_tool_call",
-      async (event, ctx) => {
-        prune(activeRuns);
-        const config = event.context?.pluginConfig ?? api.pluginConfig ?? {};
-        const key = runKey(event, ctx);
-        let trust = key ? activeRuns.get(key) : undefined;
-        const senderId = resolveSenderId(ctx);
-        if (trust && senderId && trust.senderId !== senderId) {
-          trust = { trusted: false, reason: "run_scope_sender_conflict" };
-        }
-        const decision = decideToolCall(event.toolName, trust, config);
-
-        if (decision.action === "block") {
-          return {
-            block: true,
-            blockReason: `AIOS V2R1 origin policy denied tool call: ${decision.code}`,
-          };
-        }
-        if (decision.action === "approval") {
-          return {
-            requireApproval: {
-              title: `Approve ${String(event.toolName)}`,
-              description: "Authenticated user requested a side-effecting tool call in this Tenant Cell.",
-              severity: "warning",
-              timeoutMs: approvalTimeout(config),
-              allowedDecisions: ["allow-once", "deny"],
-              pluginId: "aios-tenant-boundary",
-            },
-          };
-        }
-        return undefined;
-      },
-      { priority: 100 },
-    );
-
-    api.on(
-      "agent_end",
-      async (event, ctx) => {
-        const key = runKey(event, ctx);
-        if (key) activeRuns.delete(key);
-      },
-      { priority: 100 },
-    );
-  },
-};

openclaw/plugins/aios-tenant-boundary/dist/policy.js

@@ -1,89 +0,0 @@
-const DEFAULT_READ_ONLY_TOOLS = Object.freeze([
-  "read", "grep", "glob", "find", "ls", "web_search", "web_fetch",
-  "memory_search", "sessions_list", "sessions_history", "session_status",
-]);
-
-function strings(value) {
-  return Array.isArray(value)
-    ? value.filter((item) => typeof item === "string" && item.trim())
-        .map((item) => item.trim())
-    : [];
-}
-
-export function resolveSenderId(ctx = {}) {
-  const direct = typeof ctx.senderId === "string" ? ctx.senderId.trim() : "";
-  const nested = typeof ctx.channelContext?.sender?.id === "string"
-    ? ctx.channelContext.sender.id.trim()
-    : "";
-  return direct || nested || undefined;
-}
-
-export function classifyRun(ctx = {}, config = {}) {
-  const senderId = resolveSenderId(ctx);
-  const trusted = new Set(strings(config.trustedSenderIds));
-  const blocked = new Set(strings(config.blockedSenderIds));
-
-  if (typeof ctx.jobId === "string" && ctx.jobId) {
-    return { trusted: false, origin: "automation", reason: "job_id_present" };
-  }
-  if (!senderId) {
-    return { trusted: false, origin: "system_or_unknown", reason: "sender_id_missing" };
-  }
-  if (blocked.has(senderId)) {
-    return { trusted: false, origin: "blocked_sender", reason: "sender_blocked", senderId };
-  }
-  if (config.requireExplicitTrustedSenders !== false && !trusted.has(senderId)) {
-    return { trusted: false, origin: "untrusted_sender", reason: "sender_not_allowlisted", senderId };
-  }
-  return {
-    trusted: true,
-    origin: "authenticated_channel_user",
-    reason: "sender_verified",
-    senderId,
-  };
-}
-
-export function decideToolCall(toolName, runTrust, config = {}) {
-  const name = typeof toolName === "string" ? toolName.trim().toLowerCase() : "";
-  const configured = strings(config.readOnlyTools).map((item) => item.toLowerCase());
-  const readOnly = new Set(configured.length ? configured : DEFAULT_READ_ONLY_TOOLS);
-  if (!name) {
-    return { action: "block", code: "tool_name_missing" };
-  }
-  if (readOnly.has(name)) {
-    return { action: "allow", code: "read_only" };
-  }
-  if (!runTrust || runTrust.trusted !== true) {
-    return {
-      action: "block",
-      code: runTrust?.reason || "run_provenance_missing",
-    };
-  }
-  if (config.requireApprovalForHumanSideEffects === false) {
-    return { action: "allow", code: "trusted_side_effect" };
-  }
-  return { action: "approval", code: "human_side_effect" };
-}
-
-export function runKey(event = {}, ctx = {}) {
-  const exact = (...values) => {
-    const normalized = values
-      .filter((value) => typeof value === "string")
-      .map((value) => value.trim())
-      .filter(Boolean);
-    return normalized.length > 0 && new Set(normalized).size === 1
-      ? normalized[0]
-      : undefined;
-  };
-  const runId = exact(event.runId, ctx.runId);
-  const agentId = exact(event.agentId, ctx.agentId);
-  const sessionId = exact(
-    event.sessionId,
-    event.sessionKey,
-    ctx.sessionId,
-    ctx.sessionKey,
-  );
-  return runId && agentId && sessionId
-    ? JSON.stringify([runId, agentId, sessionId])
-    : undefined;
-}

openclaw/plugins/aios-tenant-boundary/openclaw.plugin.json

@@ -1,25 +0,0 @@
-{
-  "id": "aios-tenant-boundary",
-  "name": "AIOS Tenant Boundary",
-  "description": "Enforces AIOS V2R1 tenant provenance and tool policy boundaries.",
-  "version": "2.1.0-rc.1",
-  "entry": "dist/index.js",
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "requireExplicitTrustedSenders": { "type": "boolean", "default": true },
-      "trustedSenderIds": { "type": "array", "items": { "type": "string" }, "default": [] },
-      "blockedSenderIds": { "type": "array", "items": { "type": "string" }, "default": [] },
-      "readOnlyTools": { "type": "array", "items": { "type": "string" } },
-      "requireApprovalForHumanSideEffects": { "type": "boolean", "default": true },
-      "blockUnknownAgentRuns": { "type": "boolean", "default": false },
-      "approvalTimeoutMs": {
-        "type": "integer",
-        "minimum": 1000,
-        "maximum": 300000,
-        "default": 60000
-      }
-    }
-  }
-}

openclaw/plugins/aios-tenant-boundary/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "@aios/openclaw-tenant-boundary",
-  "version": "2.1.0-rc.1",
-  "type": "module",
-  "description": "AIOS V2R1 Tenant Cell provenance and side-effect policy boundary for OpenClaw.",
-  "files": [
-    "dist",
-    "openclaw.plugin.json"
-  ],
-  "scripts": {
-    "test": "node --test test/*.test.js"
-  },
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ]
-  }
-}

openclaw/plugins/aios-tenant-boundary/test/compat.test.js

@@ -1,64 +0,0 @@
-import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
-import test from "node:test";
-
-import plugin from "../dist/index.js";
-
-const packageJson = JSON.parse(
-  await readFile(new URL("../package.json", import.meta.url), "utf8"),
-);
-const manifest = JSON.parse(
-  await readFile(new URL("../openclaw.plugin.json", import.meta.url), "utf8"),
-);
-
-function registrations(config = {}) {
-  const seen = [];
-  plugin.register({
-    pluginConfig: config,
-    on(name, handler, options) {
-      seen.push({ name, handler, options });
-    },
-  });
-  return seen;
-}
-
-test("package, manifest, and executable test command are release compatible", () => {
-  assert.equal(packageJson.version, "2.1.0-rc.1");
-  assert.equal(manifest.version, "2.1.0-rc.1");
-  assert.equal(packageJson.scripts.test, "node --test test/*.test.js");
-});
-
-test("schema declares every runtime-read property and exact B1 bounds", () => {
-  const properties = manifest.configSchema.properties;
-  const runtimeKeys = [
-    "approvalTimeoutMs",
-    "blockUnknownAgentRuns",
-    "blockedSenderIds",
-    "readOnlyTools",
-    "requireApprovalForHumanSideEffects",
-    "requireExplicitTrustedSenders",
-    "trustedSenderIds",
-  ];
-  assert.deepEqual(Object.keys(properties).sort(), runtimeKeys);
-  assert.deepEqual(properties.blockUnknownAgentRuns, {
-    type: "boolean",
-    default: false,
-  });
-  assert.deepEqual(properties.approvalTimeoutMs, {
-    type: "integer",
-    minimum: 1000,
-    maximum: 300000,
-    default: 60000,
-  });
-});
-
-test("all three hooks register exactly once at priority 100", () => {
-  const seen = registrations();
-  assert.deepEqual(
-    seen.map(({ name }) => name).sort(),
-    ["agent_end", "before_agent_run", "before_tool_call"],
-  );
-  for (const registration of seen) {
-    assert.deepEqual(registration.options, { priority: 100 });
-  }
-});

openclaw/plugins/aios-tenant-boundary/test/loader.test.mjs

@@ -1,50 +0,0 @@
-import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
-import { realpath } from "node:fs/promises";
-
-const [mode, inspectPath] = process.argv.slice(2);
-assert.ok(["default", "opt-in"].includes(mode), `unsupported mode: ${mode}`);
-assert.ok(inspectPath, "inspect JSON path is required");
-
-const data = JSON.parse(await readFile(inspectPath, "utf8"));
-const plugin = data.plugin;
-assert.equal(plugin.id, "aios-tenant-boundary");
-assert.equal(plugin.version, "2.1.0-rc.1");
-assert.equal(plugin.status, "loaded");
-assert.equal(plugin.activated, true);
-assert.equal(await realpath(plugin.rootDir), await realpath(new URL("..", import.meta.url)));
-assert.equal(await realpath(plugin.source), await realpath(new URL("../dist/index.js", import.meta.url)));
-assert.equal(data.install.source, "path");
-assert.equal(await realpath(data.install.installPath), await realpath(plugin.rootDir));
-
-const hooks = data.typedHooks
-  .map(({ name, priority }) => ({ name, priority }))
-  .sort((a, b) => a.name.localeCompare(b.name));
-const expectedNames = mode === "default"
-  ? ["before_tool_call"]
-  : ["agent_end", "before_agent_run", "before_tool_call"];
-assert.deepEqual(hooks.map(({ name }) => name), expectedNames);
-assert.ok(hooks.every(({ priority }) => priority === 100));
-
-const diagnostics = data.diagnostics ?? [];
-assert.equal(
-  diagnostics.filter(({ level, severity }) =>
-    ["error", "fatal"].includes(String(level ?? severity).toLowerCase())).length,
-  0,
-);
-if (mode === "default") {
-  assert.deepEqual(
-    diagnostics.map(({ level, message }) => ({ level, message })).sort((a, b) => a.message.localeCompare(b.message)),
-    ["agent_end", "before_agent_run"].map((hook) => ({
-      level: "warn",
-      message: `typed hook "${hook}" blocked because non-bundled plugins must set plugins.entries.aios-tenant-boundary.hooks.allowConversationAccess=true`,
-    })).sort((a, b) => a.message.localeCompare(b.message)),
-  );
-} else {
-  assert.deepEqual(diagnostics, []);
-}
-
-const properties = plugin.configJsonSchema?.properties ?? {};
-for (const key of ["approvalTimeoutMs", "blockUnknownAgentRuns"]) {
-  assert.ok(Object.hasOwn(properties, key), `missing runtime schema property: ${key}`);
-}

openclaw/plugins/aios-tenant-boundary/test/policy.test.js

@@ -1,261 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import plugin from "../dist/index.js";
-import {
-  classifyRun,
-  decideToolCall,
-  resolveSenderId,
-  runKey,
-} from "../dist/policy.js";
-
-function registration(config = {}) {
-  const handlers = new Map();
-  plugin.register({
-    pluginConfig: config,
-    on(name, handler) {
-      handlers.set(name, handler);
-    },
-  });
-  return {
-    beforeAgentRun: handlers.get("before_agent_run"),
-    beforeToolCall: handlers.get("before_tool_call"),
-    agentEnd: handlers.get("agent_end"),
-  };
-}
-
-function agentContext(id, senderId) {
-  return {
-    runId: `run-${id}`,
-    agentId: "agent-main",
-    sessionKey: `session-${id}`,
-    ...(senderId ? { senderId } : {}),
-  };
-}
-
-function toolContext(id, extra = {}) {
-  return {
-    runId: `run-${id}`,
-    agentId: "agent-main",
-    sessionId: `session-${id}`,
-    ...extra,
-  };
-}
-
-test("sender classification covers missing, blocked, allowlisted, and automation", () => {
-  assert.equal(resolveSenderId({ channelContext: { sender: { id: " nested " } } }), "nested");
-  assert.deepEqual(classifyRun({}, {}), {
-    trusted: false,
-    origin: "system_or_unknown",
-    reason: "sender_id_missing",
-  });
-  assert.equal(
-    classifyRun({ senderId: "blocked" }, { blockedSenderIds: ["blocked"] }).reason,
-    "sender_blocked",
-  );
-  assert.equal(
-    classifyRun(
-      { senderId: "alice" },
-      { requireExplicitTrustedSenders: true, trustedSenderIds: ["alice"] },
-    ).trusted,
-    true,
-  );
-  assert.deepEqual(classifyRun({ jobId: "job-1" }, {}), {
-    trusted: false,
-    origin: "automation",
-    reason: "job_id_present",
-  });
-});
-
-test("unknown agent runs default to pass but fail closed when explicitly enabled", async () => {
-  const defaultHandlers = registration();
-  assert.deepEqual(
-    await defaultHandlers.beforeAgentRun({}, agentContext("default")),
-    { outcome: "pass" },
-  );
-
-  const enforced = registration({ blockUnknownAgentRuns: true });
-  const denied = await enforced.beforeAgentRun({}, agentContext("denied"));
-  assert.equal(denied.outcome, "block");
-  assert.equal(denied.reason, "sender_id_missing");
-  assert.doesNotMatch(denied.reason + denied.message, /undefined|\r|\n/);
-
-  assert.deepEqual(
-    await enforced.beforeAgentRun({}, { ...agentContext("job"), jobId: "job-1" }),
-    { outcome: "pass" },
-  );
-});
-
-test("read-only tools pass without provenance and side effects fail with a stable reason", async () => {
-  assert.deepEqual(decideToolCall("read", undefined, {}), {
-    action: "allow",
-    code: "read_only",
-  });
-  assert.deepEqual(decideToolCall("shell", undefined, {}), {
-    action: "block",
-    code: "run_provenance_missing",
-  });
-
-  const handlers = registration();
-  assert.equal(await handlers.beforeToolCall({ toolName: "read" }, {}), undefined);
-  const blocked = await handlers.beforeToolCall({ toolName: "shell" }, {});
-  assert.equal(blocked.block, true);
-  assert.equal(
-    blocked.blockReason,
-    "AIOS V2R1 origin policy denied tool call: run_provenance_missing",
-  );
-});
-
-test("trusted human side effects request approval with exact timeout validation", async () => {
-  for (const [configured, expected] of [
-    [undefined, 60000],
-    [1000, 1000],
-    [300000, 300000],
-    [999, 60000],
-    [300001, 60000],
-    [60000.5, 60000],
-    ["1000", 60000],
-    [null, 60000],
-  ]) {
-    const config = {
-      requireExplicitTrustedSenders: true,
-      trustedSenderIds: ["alice"],
-    };
-    if (configured !== undefined) config.approvalTimeoutMs = configured;
-    const handlers = registration(config);
-    const id = `approval-${String(configured)}`;
-    await handlers.beforeAgentRun({}, agentContext(id, "alice"));
-    const result = await handlers.beforeToolCall({ toolName: "shell" }, toolContext(id));
-    assert.equal(result.requireApproval.timeoutMs, expected, String(configured));
-    assert.deepEqual(result.requireApproval.allowedDecisions, ["allow-once", "deny"]);
-  }
-});
-
-test("active run provenance is isolated by registration, run, and sender", async () => {
-  const config = {
-    requireExplicitTrustedSenders: true,
-    trustedSenderIds: ["alice", "bob"],
-  };
-  const first = registration(config);
-  const second = registration(config);
-  await first.beforeAgentRun({}, agentContext("shared", "alice"));
-
-  const otherSender = await first.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("shared", { senderId: "bob" }),
-  );
-  assert.equal(otherSender.block, true);
-  assert.match(otherSender.blockReason, /run_scope_sender_conflict$/);
-
-  const otherRegistration = await second.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("shared"),
-  );
-  assert.equal(otherRegistration.block, true);
-  assert.match(otherRegistration.blockReason, /run_provenance_missing$/);
-});
-
-test("agent_end cleanup removes only the matching shared scope", async () => {
-  const handlers = registration({
-    requireExplicitTrustedSenders: true,
-    trustedSenderIds: ["alice", "bob"],
-  });
-  await handlers.beforeAgentRun({}, agentContext("alice-scope", "alice"));
-  await handlers.beforeAgentRun({}, agentContext("bob-scope", "bob"));
-  await handlers.agentEnd({}, toolContext("alice-scope"));
-
-  const alice = await handlers.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("alice-scope"),
-  );
-  assert.equal(alice.block, true);
-
-  const bob = await handlers.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("bob-scope"),
-  );
-  assert.ok(bob.requireApproval);
-});
-
-test("run provenance expires after the bounded age", async (t) => {
-  const originalNow = Date.now;
-  t.after(() => { Date.now = originalNow; });
-  let now = 1_000_000;
-  Date.now = () => now;
-  const handlers = registration({
-    requireExplicitTrustedSenders: true,
-    trustedSenderIds: ["alice"],
-  });
-  await handlers.beforeAgentRun({}, agentContext("expiring", "alice"));
-  now += 60 * 60 * 1000 + 1;
-  const result = await handlers.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("expiring"),
-  );
-  assert.equal(result.block, true);
-  assert.match(result.blockReason, /run_provenance_missing$/);
-});
-
-test("host-shaped tool context without sender reuses trusted shared scope", async () => {
-  const handlers = registration({
-    requireExplicitTrustedSenders: true,
-    trustedSenderIds: ["alice"],
-  });
-  await handlers.beforeAgentRun({}, agentContext("host-shape", "alice"));
-  const result = await handlers.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("host-shape"),
-  );
-  assert.ok(result.requireApproval);
-  assert.equal(result.block, undefined);
-});
-
-test("shared scope collision fails closed without overwriting original sender", async () => {
-  const handlers = registration({
-    requireExplicitTrustedSenders: true,
-    trustedSenderIds: ["alice", "bob"],
-  });
-  assert.deepEqual(
-    await handlers.beforeAgentRun({}, agentContext("collision", "alice")),
-    { outcome: "pass" },
-  );
-  const collision = await handlers.beforeAgentRun(
-    {},
-    agentContext("collision", "bob"),
-  );
-  assert.equal(collision.outcome, "block");
-  assert.equal(collision.reason, "run_scope_sender_conflict");
-  assert.doesNotMatch(collision.message, /alice|bob/);
-
-  const original = await handlers.beforeToolCall(
-    { toolName: "shell" },
-    toolContext("collision"),
-  );
-  assert.ok(original.requireApproval);
-});
-
-test("shared scope normalization is exact and incomplete scope fails closed", async () => {
-  const sessionId = runKey({}, {
-    runId: " run-1 ", agentId: " agent-1 ", sessionId: " session-1 ",
-  });
-  const sessionKey = runKey({}, {
-    runId: "run-1", agentId: "agent-1", sessionKey: "session-1",
-  });
-  assert.equal(sessionId, JSON.stringify(["run-1", "agent-1", "session-1"]));
-  assert.equal(sessionKey, sessionId);
-  assert.equal(runKey({}, {
-    runId: "run-1",
-    agentId: "agent-1",
-    sessionId: "session-1",
-    sessionKey: "different-session",
-  }), undefined);
-  assert.equal(runKey({}, { agentId: "agent-1", sessionId: "session-1" }), undefined);
-
-  const handlers = registration();
-  const missing = await handlers.beforeToolCall(
-    { toolName: "shell" },
-    { agentId: "agent-1", sessionId: "session-1" },
-  );
-  assert.equal(missing.block, true);
-  assert.match(missing.blockReason, /run_provenance_missing$/);
-});

release/v2r1c0-rc1/RELEASE.md

@@ -1,36 +0,0 @@
-# AIOS V2R1C0 RC1
-
-## Architecture
-
-OpenClaw Tenant Cell + Hermes Shared Agent Fabric.
-
-## Included
-
-- Signed Tenant Context
-- Canonical Message Envelope
-- Tenant Router
-- OpenClaw Cell lifecycle adapter
-- Exact Message Ledger
-- Hermes tenant partitioned scheduler
-- Memory Namespace policy
-- Secret Scope references
-- Append-only Audit Chain
-- Hermes Profile isolation
-- OpenClaw tenant boundary plugin
-
-## Release Gates
-
-Before production:
-
-- automated isolation tests pass
-- OpenClaw plugin runtime inspect passes
-- Cell health probes pass
-- running commit matches release commit
-- rollback test passes
-
-## Security Rules
-
-Unknown provenance fails closed.
-Quoted text is data, not command input.
-Cross-tenant access is denied.
-Shared Fabric does not share tenant state.

remote-runner/aios_remote_codex_brain.py

@@ -0,0 +1,459 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import json
+import logging
+import os
+from pathlib import Path
+import signal
+import stat
+import subprocess
+import tempfile
+import threading
+import time
+from typing import Any
+import urllib.error
+import urllib.request
+import uuid
+
+from services.aios_orchestrator_gateway.errors import ConfigurationError, TriggerError, ValidationError
+from services.aios_orchestrator_gateway.models import DECISION_SCHEMA, Event
+from services.aios_orchestrator_gateway.remote_codex import validate_remote_decision
+from services.aios_orchestrator_gateway.securefs import atomic_write_json, read_secure_bytes, read_secure_json
+
+
+LOG = logging.getLogger("aios-remote-codex-brain")
+REQUIRED_EXEC_FLAGS = (
+    "--json", "--output-schema", "--output-last-message", "--sandbox",
+    "--config", "--cd", "--ephemeral",
+)
+APPROVED_CODEX_ROOTS = (
+    Path("/usr/lib/node_modules/@openai/codex"),
+    Path("/usr/local/lib/node_modules/@openai/codex"),
+    Path("/opt/openai/codex"),
+)
+EXPECTED_CODEX_VERSION = "0.144.6"
+
+
+@dataclass(frozen=True)
+class RunnerConfig:
+    gateway_url: str
+    runner_id: str
+    token_file: Path
+    contract_commit: str
+    codex_binary: Path
+    codex_home: Path
+    controller_readonly: Path
+    state_file: Path
+    timeout_seconds: int
+    poll_seconds: int
+    heartbeat_seconds: int
+
+    @classmethod
+    def from_file(cls, path: Path) -> "RunnerConfig":
+        raw = read_secure_json(path, expected_uid=0)
+        expected = {
+            "gateway_url", "runner_id", "token_file", "contract_commit",
+            "codex_binary", "codex_home", "controller_readonly", "state_file",
+            "timeout_seconds", "poll_seconds", "heartbeat_seconds",
+        }
+        if set(raw) != expected:
+            raise ConfigurationError("invalid_runner_config_fields")
+
+        def absolute(name: str) -> Path:
+            value = raw.get(name)
+            if not isinstance(value, str) or not Path(value).is_absolute():
+                raise ConfigurationError(f"invalid_{name}")
+            return Path(value)
+
+        url = raw.get("gateway_url")
+        if url != "http://127.0.0.1:28920/v1/orchestrator":
+            raise ConfigurationError("gateway_must_use_approved_loopback_tunnel")
+        runner_id = raw.get("runner_id")
+        contract = raw.get("contract_commit")
+        if not isinstance(runner_id, str) or not runner_id or len(runner_id) > 128:
+            raise ConfigurationError("invalid_runner_id")
+        if not isinstance(contract, str) or len(contract) != 40 or any(c not in "0123456789abcdef" for c in contract):
+            raise ConfigurationError("invalid_contract_commit")
+
+        def bounded(name: str, low: int, high: int) -> int:
+            value = raw.get(name)
+            if not isinstance(value, int) or not low <= value <= high:
+                raise ConfigurationError(f"invalid_{name}")
+            return value
+
+        return cls(
+            gateway_url=url, runner_id=runner_id, token_file=absolute("token_file"),
+            contract_commit=contract, codex_binary=absolute("codex_binary"),
+            codex_home=absolute("codex_home"),
+            controller_readonly=absolute("controller_readonly"),
+            state_file=absolute("state_file"),
+            timeout_seconds=bounded("timeout_seconds", 30, 3600),
+            poll_seconds=bounded("poll_seconds", 1, 300),
+            heartbeat_seconds=bounded("heartbeat_seconds", 5, 300),
+        )
+
+
+class RemoteCodexRunner:
+    def __init__(self, config: RunnerConfig):
+        self.config = config
+        self._stop = threading.Event()
+
+    def _environment(self) -> dict[str, str]:
+        return {
+            "CODEX_HOME": str(self.config.codex_home),
+            "HOME": str(self.config.codex_home.parent),
+            "PATH": f"{self.config.codex_binary.parent}:/usr/bin:/bin",
+            "LANG": "C.UTF-8", "LC_ALL": "C.UTF-8",
+        }
+
+    @staticmethod
+    def _safe_regular(path: Path, *, owner_uid: int, mode: int | None = None) -> os.stat_result:
+        info = path.lstat()
+        if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+            raise ConfigurationError("unsafe_regular_file")
+        if info.st_uid != owner_uid:
+            raise ConfigurationError("unsafe_file_owner")
+        if mode is not None and stat.S_IMODE(info.st_mode) != mode:
+            raise ConfigurationError("unsafe_file_mode")
+        return info
+
+    def validate_official_cli(self) -> None:
+        binary = self.config.codex_binary
+        if not binary.is_absolute() or not binary.exists():
+            raise ConfigurationError("codex_cli_not_installed")
+        link_info = binary.lstat()
+        if link_info.st_uid != 0:
+            raise ConfigurationError("unsafe_codex_launcher")
+        if not stat.S_ISLNK(link_info.st_mode) and link_info.st_mode & (stat.S_IWGRP | stat.S_IWOTH):
+            raise ConfigurationError("unsafe_codex_launcher")
+        target = binary.resolve(strict=True)
+        target_info = target.lstat()
+        if not stat.S_ISREG(target_info.st_mode) or target_info.st_uid != 0:
+            raise ConfigurationError("unsafe_codex_target")
+        if target_info.st_mode & (stat.S_IWGRP | stat.S_IWOTH) or not os.access(target, os.X_OK):
+            raise ConfigurationError("unsafe_codex_target")
+        approved = next((root for root in APPROVED_CODEX_ROOTS if target.is_relative_to(root)), None)
+        if approved is None:
+            raise ConfigurationError("unapproved_codex_install_root")
+        if approved.name == "codex" and "node_modules" in approved.parts:
+            package = approved / "package.json"
+            value = read_secure_json(package, expected_uid=0)
+            if value.get("name") != "@openai/codex" or value.get("version") != EXPECTED_CODEX_VERSION:
+                raise ConfigurationError("unofficial_codex_package")
+            native = list(approved.glob("node_modules/@openai/codex-*/vendor/*/bin/codex"))
+            if len(native) != 1:
+                raise ConfigurationError("codex_native_binary_missing")
+            native_info = native[0].lstat()
+            if (
+                not stat.S_ISREG(native_info.st_mode) or native_info.st_uid != 0
+                or native_info.st_mode & (stat.S_IWGRP | stat.S_IWOTH)
+                or not os.access(native[0], os.X_OK)
+            ):
+                raise ConfigurationError("unsafe_codex_native_binary")
+        result = self._run_quiet([str(binary), "exec", "--help"], 30, capture_stdout=True)
+        if result.returncode != 0 or any(flag not in result.stdout for flag in REQUIRED_EXEC_FLAGS):
+            raise ConfigurationError("codex_cli_version_incompatible")
+
+    def validate_auth_metadata(self) -> None:
+        auth = self.config.codex_home / "auth.json"
+        self._safe_regular(auth, owner_uid=os.geteuid(), mode=0o600)
+
+    def login_status(self) -> None:
+        result = self._run_quiet(
+            [str(self.config.codex_binary), "login", "status"], 30, capture_stdout=True
+        )
+        if result.returncode != 0:
+            raise ConfigurationError("codex_authentication_required")
+        normalized = result.stdout.lower()
+        if "oneapi" in normalized or "api key" in normalized or "chatgpt" not in normalized:
+            raise ConfigurationError("codex_chatgpt_authentication_required")
+
+    def validate_runtime_boundary(self) -> None:
+        controller = self.config.controller_readonly
+        if not controller.is_dir() or controller.is_symlink() or os.access(controller, os.W_OK):
+            raise ConfigurationError("controller_not_read_only")
+        if (controller / ".git").exists():
+            raise ConfigurationError("controller_must_not_be_git_worktree")
+        state_parent = self.config.state_file.parent
+        state_parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if state_parent.is_symlink():
+            raise ConfigurationError("unsafe_state_directory")
+
+    def health_check(self) -> None:
+        self.validate_official_cli()
+        self.validate_auth_metadata()
+        self.validate_runtime_boundary()
+        self.login_status()
+
+    def _run_quiet(self, argv: list[str], timeout: int, *, capture_stdout: bool = False) -> subprocess.CompletedProcess[str]:
+        try:
+            return subprocess.run(
+                argv, cwd=self.config.controller_readonly, env=self._environment(),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE if capture_stdout else subprocess.DEVNULL,
+                stderr=subprocess.STDOUT if capture_stdout else subprocess.DEVNULL,
+                text=True, timeout=timeout, check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise ConfigurationError("codex_cli_probe_failed") from exc
+
+    def _token(self) -> str:
+        info = self._safe_regular(self.config.token_file, owner_uid=os.geteuid(), mode=0o600)
+        if info.st_size > 4096:
+            raise ConfigurationError("runner_token_too_large")
+        raw = read_secure_bytes(self.config.token_file, expected_uid=os.geteuid(), max_bytes=4096)
+        if not raw or b"\n" in raw or b"\r" in raw:
+            raise ConfigurationError("invalid_runner_token")
+        return raw.decode("utf-8")
+
+    def _request(self, path: str, scope: str, body: dict[str, Any], key: str) -> dict[str, Any]:
+        encoded = json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
+        request = urllib.request.Request(
+            f"{self.config.gateway_url}/{path.lstrip('/')}", data=encoded, method="POST",
+            headers={
+                "Authorization": f"Bearer {self._token()}",
+                "Content-Type": "application/json",
+                "Idempotency-Key": key,
+                "X-AIOS-Runner-ID": self.config.runner_id,
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                if response.status not in {200, 202}:
+                    raise TriggerError("gateway_request_rejected")
+                raw = response.read(1_048_577)
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise TriggerError(f"gateway_{scope}_unavailable") from exc
+        if len(raw) > 1_048_576:
+            raise TriggerError("gateway_response_too_large")
+        try:
+            value = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise TriggerError("gateway_invalid_response") from exc
+        if not isinstance(value, dict):
+            raise TriggerError("gateway_invalid_response")
+        return value
+
+    def _load_state(self) -> dict[str, Any] | None:
+        try:
+            return read_secure_json(self.config.state_file, expected_uid=os.geteuid())
+        except FileNotFoundError:
+            return None
+
+    def _save_state(self, value: dict[str, Any]) -> None:
+        atomic_write_json(self.config.state_file, value, mode=0o600)
+
+    def _clear_state(self) -> None:
+        try:
+            self.config.state_file.unlink()
+            directory_fd = os.open(self.config.state_file.parent, os.O_RDONLY | os.O_DIRECTORY)
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+        except FileNotFoundError:
+            pass
+
+    def _claim(self) -> dict[str, Any] | None:
+        claim_key = "claim-" + uuid.uuid4().hex
+        response = self._request(
+            "central/jobs/claim", "claim",
+            {"contract_commit": self.config.contract_commit}, claim_key,
+        )
+        if response.get("claimed") is False:
+            return None
+        required = {
+            "claimed", "job_id", "runner_id", "lease_version", "lease_until",
+            "lease_token", "event", "claim_idempotency_key",
+        }
+        if set(response) != required or response.get("runner_id") != self.config.runner_id:
+            raise TriggerError("invalid_claim_response")
+        event = Event.from_dict(response.get("event"))
+        if event.contract_commit != self.config.contract_commit:
+            raise ValidationError("contract_version_mismatch")
+        state = {
+            "phase": "CLAIMED", "job_id": response["job_id"],
+            "lease_token": response["lease_token"], "claim_idempotency_key": claim_key,
+            "event": event.to_dict(), "decision": None,
+        }
+        self._save_state(state)
+        return state
+
+    def _heartbeat(self, state: dict[str, Any], key: str | None = None) -> dict[str, Any]:
+        return self._request(
+            f"central/jobs/{state['job_id']}/heartbeat", "heartbeat",
+            {"lease_token": state["lease_token"],
+             "claim_idempotency_key": state["claim_idempotency_key"]},
+            key or ("heartbeat-" + uuid.uuid4().hex),
+        )
+
+    def _exec(self, event: Event, heartbeat_state: dict[str, Any]) -> dict[str, Any]:
+        prompt = (
+            "读取只读治理合同与本次事件。只输出符合Decision Schema的决策。"
+            "不得修改Git、部署生产、读取秘密或伪造证据；证据不足时输出BLOCKED。\n"
+            + event.canonical_json()
+        )
+        runtime_root = self.config.state_file.parent / "runtime"
+        runtime_root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        os.chmod(runtime_root, 0o700)
+        with tempfile.TemporaryDirectory(prefix="remote-decision-", dir=runtime_root) as directory:
+            root = Path(directory)
+            schema_path = root / "decision.schema.json"
+            output_path = root / "decision.json"
+            schema_path.write_text(json.dumps(DECISION_SCHEMA, separators=(",", ":")), encoding="utf-8")
+            schema_path.chmod(0o600)
+            argv = [
+                str(self.config.codex_binary), "exec", "--json",
+                "--output-schema", str(schema_path),
+                "--output-last-message", str(output_path),
+                "--sandbox", "read-only", "--config", 'approval_policy="never"',
+                "--cd", str(self.config.controller_readonly), "--ephemeral", "-",
+            ]
+            process = subprocess.Popen(
+                argv, cwd=self.config.controller_readonly, env=self._environment(),
+                stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                text=True, start_new_session=True,
+            )
+            heartbeat_error: list[Exception] = []
+            heartbeat_stop = threading.Event()
+
+            def heartbeat_loop() -> None:
+                while not heartbeat_stop.wait(self.config.heartbeat_seconds):
+                    try:
+                        self._heartbeat(heartbeat_state)
+                    except Exception as exc:
+                        heartbeat_error.append(exc)
+                        return
+
+            thread = threading.Thread(target=heartbeat_loop, daemon=True)
+            thread.start()
+            try:
+                process.communicate(prompt, timeout=self.config.timeout_seconds)
+            except subprocess.TimeoutExpired as exc:
+                self._terminate_group(process)
+                raise TriggerError("codex_exec_timeout") from exc
+            finally:
+                heartbeat_stop.set(); thread.join(timeout=5)
+            if heartbeat_error:
+                raise TriggerError("lease_heartbeat_failed")
+            if process.returncode != 0:
+                raise TriggerError("codex_exec_nonzero")
+            try:
+                if output_path.stat().st_size > 1_048_576:
+                    raise TriggerError("codex_output_too_large")
+                value = json.loads(output_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                raise TriggerError("codex_exec_invalid_json") from exc
+            if not isinstance(value, dict):
+                raise TriggerError("codex_exec_invalid_json")
+            return validate_remote_decision(value, event).to_dict()
+
+    @staticmethod
+    def _terminate_group(process: subprocess.Popen[str]) -> None:
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+            process.wait(timeout=2)
+        except (ProcessLookupError, subprocess.TimeoutExpired):
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            process.wait(timeout=5)
+
+    def _submit(self, state: dict[str, Any]) -> None:
+        key = state.get("decision_idempotency_key")
+        if not isinstance(key, str):
+            key = "decision-" + uuid.uuid4().hex
+            state["decision_idempotency_key"] = key
+            self._save_state(state)
+        response = self._request(
+            f"central/jobs/{state['job_id']}/decision", "decision",
+            {"lease_token": state["lease_token"],
+             "claim_idempotency_key": state["claim_idempotency_key"],
+             "decision": state["decision"]}, key,
+        )
+        if response.get("accepted") is not True or response.get("completed") is not True:
+            raise TriggerError("decision_not_confirmed")
+        self._clear_state()
+
+    def _fail(self, state: dict[str, Any], category: str) -> None:
+        key = state.get("fail_idempotency_key")
+        if not isinstance(key, str):
+            key = "fail-" + uuid.uuid4().hex
+            state["fail_idempotency_key"] = key
+            self._save_state(state)
+        self._request(
+            f"central/jobs/{state['job_id']}/fail", "fail",
+            {"lease_token": state["lease_token"],
+             "claim_idempotency_key": state["claim_idempotency_key"],
+             "category": category}, key,
+        )
+        self._clear_state()
+
+    def run_one(self) -> bool:
+        self.health_check()
+        state = self._load_state()
+        if state is None:
+            state = self._claim()
+            if state is None:
+                return False
+        try:
+            self._heartbeat(state, state.get("recovery_heartbeat_key") or "recover-" + uuid.uuid4().hex)
+            if state.get("phase") == "CLAIMED":
+                event = Event.from_dict(state.get("event"))
+                decision = self._exec(event, state)
+                state["phase"] = "DECIDED"
+                state["decision"] = decision
+                self._save_state(state)
+            if state.get("phase") != "DECIDED" or not isinstance(state.get("decision"), dict):
+                raise TriggerError("invalid_runner_state")
+            self._submit(state)
+            return True
+        except (ConfigurationError, TriggerError, ValidationError) as exc:
+            category = type(exc).__name__.upper()
+            try:
+                self._fail(state, category)
+            except Exception:
+                LOG.warning("remote_job_retained category=TRANSPORT_UNAVAILABLE")
+            raise
+
+    def run_forever(self) -> None:
+        while not self._stop.is_set():
+            try:
+                worked = self.run_one()
+            except Exception as exc:
+                LOG.warning("remote_cycle_failed category=%s", type(exc).__name__)
+                worked = False
+            self._stop.wait(0 if worked else self.config.poll_seconds)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", required=True, type=Path)
+    parser.add_argument("--once", action="store_true")
+    parser.add_argument("--health", action="store_true")
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s %(message)s")
+    try:
+        runner = RemoteCodexRunner(RunnerConfig.from_file(args.config))
+        if args.health:
+            runner.health_check()
+            print("REMOTE_CODEX_BRAIN_HEALTH=PASS")
+            return 0
+        if args.once:
+            runner.run_one()
+            return 0
+        runner.run_forever()
+        return 0
+    except Exception as exc:
+        reason = str(exc)
+        safe = reason if reason.replace("_", "").isalnum() and len(reason) <= 64 else type(exc).__name__
+        print(f"REMOTE_CODEX_BRAIN=BLOCKED reason={safe}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

remote-runner/install_remote_codex_brain.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+umask 0077
+
+SOURCE_ROOT="${SOURCE_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+CONTRACT_COMMIT="${CONTRACT_COMMIT:-cbe33ecab8e9794ba5f318bea43aeaf447a56fbc}"
+INSTALL_ROOT=/opt/aios-remote-codex-brain
+CONFIG_ROOT=/etc/aios-remote-codex-brain
+STATE_ROOT=/var/lib/aios-remote-codex-brain
+SERVICE_USER=aios-remote-codex
+CODEX_BINARY=/usr/bin/codex
+CODEX_HOME="$STATE_ROOT/.codex"
+CONTROLLER="$INSTALL_ROOT/controller-readonly"
+RUNNER_ID="codex-brain-192-168-88-6"
+EXPECTED_CODEX_VERSION=0.144.6
+
+fail() { printf 'STATUS=%s\nAUTOMATION_CLOSED=NO\n' "$1" >&2; exit 2; }
+[[ "$(id -u)" -eq 0 ]] || fail OWNER_INSTALL_REQUIRED
+for command in python3 node npm runuser systemctl systemd-analyze ssh sha256sum; do
+  command -v "$command" >/dev/null 2>&1 || fail "MISSING_COMMAND_${command}"
+done
+
+id "$SERVICE_USER" >/dev/null 2>&1 || useradd --system --home-dir "$STATE_ROOT" --shell /usr/sbin/nologin "$SERVICE_USER"
+install -d -o root -g root -m 0755 "$INSTALL_ROOT" "$INSTALL_ROOT/releases"
+install -d -o root -g "$SERVICE_USER" -m 0750 "$CONFIG_ROOT"
+install -d -o "$SERVICE_USER" -g "$SERVICE_USER" -m 0700 "$STATE_ROOT" "$CODEX_HOME" "$STATE_ROOT/runtime"
+
+[[ -e "$CODEX_BINARY" ]] || fail BLOCKED_CODEX_CLI_NOT_INSTALLED
+resolved="$(readlink -f "$CODEX_BINARY")"
+case "$resolved" in
+  /usr/lib/node_modules/@openai/codex/*|/usr/local/lib/node_modules/@openai/codex/*|/opt/openai/codex/*) ;;
+  *) fail BLOCKED_UNOFFICIAL_CODEX_CLI ;;
+esac
+python3 - "$CODEX_BINARY" "$resolved" <<'PY' || exit 2
+import os,stat,sys
+launcher=os.lstat(sys.argv[1]); target=os.lstat(sys.argv[2])
+if launcher.st_uid != 0: raise SystemExit(2)
+if not stat.S_ISLNK(launcher.st_mode) and launcher.st_mode & (stat.S_IWGRP|stat.S_IWOTH): raise SystemExit(2)
+if target.st_uid != 0 or target.st_mode & (stat.S_IWGRP|stat.S_IWOTH): raise SystemExit(2)
+if not stat.S_ISREG(target.st_mode) or not os.access(sys.argv[2],os.X_OK): raise SystemExit(2)
+PY
+package_root="$(npm root -g)/@openai/codex"
+[[ -f "$package_root/package.json" && ! -L "$package_root/package.json" ]] || fail BLOCKED_UNOFFICIAL_CODEX_CLI
+[[ "$(node -e "console.log(require('$package_root/package.json').name)")" = '@openai/codex' ]] || fail BLOCKED_UNOFFICIAL_CODEX_CLI
+[[ "$(node -e "console.log(require('$package_root/package.json').version)")" = "$EXPECTED_CODEX_VERSION" ]] || fail BLOCKED_CODEX_CLI_VERSION_INCOMPATIBLE
+mapfile -d '' native_targets < <(find "$package_root/node_modules/@openai" -path '*/vendor/*/bin/codex' -type f -perm /111 -print0)
+[[ "${#native_targets[@]}" -eq 1 ]] || fail BLOCKED_UNOFFICIAL_CODEX_CLI
+python3 - "${native_targets[0]}" <<'PY' || exit 2
+import os,stat,sys
+s=os.lstat(sys.argv[1])
+if not stat.S_ISREG(s.st_mode) or s.st_uid != 0 or s.st_mode & (stat.S_IWGRP|stat.S_IWOTH) or not os.access(sys.argv[1],os.X_OK): raise SystemExit(2)
+PY
+
+help_file="$(mktemp)"; trap 'rm -f "$help_file"' EXIT
+runuser -u "$SERVICE_USER" -- env -i HOME="$STATE_ROOT" CODEX_HOME="$CODEX_HOME" PATH=/usr/bin:/bin \
+  "$CODEX_BINARY" exec --help >"$help_file" 2>&1 || fail BLOCKED_CODEX_CLI_VERSION_INCOMPATIBLE
+for flag in --json --output-schema --output-last-message --sandbox --config --cd --ephemeral; do
+  grep -Fq -- "$flag" "$help_file" || fail BLOCKED_CODEX_CLI_VERSION_INCOMPATIBLE
+done
+rm -f "$help_file"; trap - EXIT
+
+AUTH_JSON="$CODEX_HOME/auth.json"
+[[ -e "$AUTH_JSON" ]] || fail BLOCKED_REMOTE_CODEX_AUTHENTICATION_REQUIRED
+python3 - "$AUTH_JSON" "$SERVICE_USER" <<'PY' || exit 2
+import os,pwd,stat,sys
+s=os.lstat(sys.argv[1]); uid=pwd.getpwnam(sys.argv[2]).pw_uid
+if stat.S_ISLNK(s.st_mode) or not stat.S_ISREG(s.st_mode) or s.st_uid != uid or stat.S_IMODE(s.st_mode) != 0o600: raise SystemExit(2)
+PY
+status_file="$(mktemp)"; trap 'rm -f "$status_file"' EXIT
+runuser -u "$SERVICE_USER" -- env -i HOME="$STATE_ROOT" CODEX_HOME="$CODEX_HOME" PATH=/usr/bin:/bin \
+  "$CODEX_BINARY" login status >"$status_file" 2>&1 || fail BLOCKED_REMOTE_CODEX_AUTHENTICATION_REQUIRED
+grep -Eqi 'chatgpt' "$status_file" || fail BLOCKED_REMOTE_CODEX_AUTHENTICATION_REQUIRED
+grep -Eqi 'one[ -]?api|api key' "$status_file" && fail BLOCKED_REMOTE_CODEX_AUTHENTICATION_REQUIRED
+rm -f "$status_file"; trap - EXIT
+
+for required in \
+  "$CONFIG_ROOT/runner.token" \
+  "$CONFIG_ROOT/tunnel_ed25519" \
+  "$CONFIG_ROOT/known_hosts"; do
+  [[ -f "$required" && ! -L "$required" ]] || fail BLOCKED_REMOTE_CODEX_TUNNEL_UNAVAILABLE
+  chown "$SERVICE_USER:$SERVICE_USER" "$required"
+  chmod 0600 "$required"
+done
+
+for required in \
+  remote-runner/aios_remote_codex_brain.py \
+  remote-runner/verify_remote_codex_brain.sh \
+  services/aios_orchestrator_gateway/__init__.py \
+  systemd/aios-remote-codex-brain.service \
+  systemd/aios-remote-codex-brain-health.service \
+  systemd/aios-remote-codex-brain-health.timer \
+  systemd/aios-remote-codex-tunnel.service \
+  .agent/policies/V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT.yaml; do
+  [[ -f "$SOURCE_ROOT/$required" && ! -L "$SOURCE_ROOT/$required" ]] || fail INVALID_SOURCE
+done
+
+digest="$(find "$SOURCE_ROOT/remote-runner" "$SOURCE_ROOT/services/aios_orchestrator_gateway" "$SOURCE_ROOT/systemd" -type f -print0 | sort -z | xargs -0 sha256sum | sha256sum | awk '{print $1}')"
+release="$INSTALL_ROOT/releases/$digest"
+if [[ ! -e "$release" ]]; then
+  install -d -o root -g root -m 0755 "$release" "$release/remote-runner" "$release/services" "$release/systemd"
+  cp -a "$SOURCE_ROOT/remote-runner/." "$release/remote-runner/"
+  cp -a "$SOURCE_ROOT/services/aios_orchestrator_gateway" "$release/services/"
+  cp -a "$SOURCE_ROOT/systemd/." "$release/systemd/"
+  find "$release" -type d -exec chmod 0755 {} +
+  find "$release" -type f -exec chmod 0644 {} +
+  chmod 0755 "$release/remote-runner/"*.py "$release/remote-runner/"*.sh
+  chown -R root:root "$release"
+fi
+ln -sfn "$release" "$INSTALL_ROOT/.current-$digest"
+mv -Tf "$INSTALL_ROOT/.current-$digest" "$INSTALL_ROOT/current"
+
+rm -rf "$CONTROLLER"
+install -d -o root -g root -m 0555 "$CONTROLLER/.agent/policies"
+install -o root -g root -m 0444 \
+  "$SOURCE_ROOT/.agent/policies/V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT.yaml" \
+  "$CONTROLLER/.agent/policies/V2R1-PERSONAL-WEIXIN-PRODUCTION-EXECUTION-CONTRACT.yaml"
+
+cat >"$CONFIG_ROOT/config.json" <<EOF
+{
+  "gateway_url":"http://127.0.0.1:28920/v1/orchestrator",
+  "runner_id":"$RUNNER_ID",
+  "token_file":"$CONFIG_ROOT/runner.token",
+  "contract_commit":"$CONTRACT_COMMIT",
+  "codex_binary":"$CODEX_BINARY",
+  "codex_home":"$CODEX_HOME",
+  "controller_readonly":"$CONTROLLER",
+  "state_file":"$STATE_ROOT/runner-state.json",
+  "timeout_seconds":300,
+  "poll_seconds":5,
+  "heartbeat_seconds":30
+}
+EOF
+chown root:"$SERVICE_USER" "$CONFIG_ROOT/config.json"
+chmod 0640 "$CONFIG_ROOT/config.json"
+
+cat >"$CONFIG_ROOT/tunnel.env" <<'EOF'
+AIOS_GATEWAY_SSH_HOST=hw.imruyi.top
+AIOS_GATEWAY_SSH_PORT=22
+AIOS_GATEWAY_SSH_USER=aios-remote-codex-tunnel
+EOF
+chown root:"$SERVICE_USER" "$CONFIG_ROOT/tunnel.env"
+chmod 0640 "$CONFIG_ROOT/tunnel.env"
+
+for unit in aios-remote-codex-brain.service aios-remote-codex-brain-health.service aios-remote-codex-brain-health.timer aios-remote-codex-tunnel.service; do
+  install -o root -g root -m 0644 "$SOURCE_ROOT/systemd/$unit" "/etc/systemd/system/$unit"
+done
+systemd-analyze verify \
+  /etc/systemd/system/aios-remote-codex-brain.service \
+  /etc/systemd/system/aios-remote-codex-brain-health.service \
+  /etc/systemd/system/aios-remote-codex-brain-health.timer \
+  /etc/systemd/system/aios-remote-codex-tunnel.service
+systemctl daemon-reload
+systemctl enable --now aios-remote-codex-tunnel.service
+systemctl enable --now aios-remote-codex-brain.service aios-remote-codex-brain-health.timer
+printf 'REMOTE_CODEX_BRAIN_INSTALL=PASS\nRELEASE_DIGEST=%s\n' "$digest"

remote-runner/verify_remote_codex_brain.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+umask 0077
+
+CONFIG=/etc/aios-remote-codex-brain/config.json
+CURRENT=/opt/aios-remote-codex-brain/current
+[[ -f "$CONFIG" && ! -L "$CONFIG" ]] || { echo 'REMOTE_CODEX_VERIFY=BLOCKED'; exit 1; }
+[[ -L "$CURRENT" ]] || { echo 'REMOTE_CODEX_VERIFY=BLOCKED'; exit 1; }
+resolved="$(readlink -f "$CURRENT")"
+case "$resolved" in /opt/aios-remote-codex-brain/releases/*) ;; *) echo 'REMOTE_CODEX_VERIFY=BLOCKED'; exit 1;; esac
+systemctl is-active --quiet aios-remote-codex-tunnel.service
+systemctl is-active --quiet aios-remote-codex-brain.service
+systemctl is-enabled --quiet aios-remote-codex-brain-health.timer
+runuser -u aios-remote-codex -- env -i \
+  HOME=/var/lib/aios-remote-codex-brain \
+  CODEX_HOME=/var/lib/aios-remote-codex-brain/.codex \
+  PATH=/usr/bin:/bin \
+  PYTHONPATH="$CURRENT" \
+  /usr/bin/python3 "$CURRENT/remote-runner/aios_remote_codex_brain.py" --config "$CONFIG" --health
+printf 'REMOTE_CODEX_VERIFY=PASS\n'

schemas/automation-quorum-controller.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aios.local/schemas/automation-quorum-controller.schema.json",
+  "title": "AIOS GPT plus one-executor quorum controller configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "project_key",
+    "contract_commit",
+    "database_path",
+    "file_inbox_path",
+    "health_receipts",
+    "blocker_retry_threshold",
+    "max_health_age_seconds",
+    "lease_ttl_seconds",
+    "gateway_event_url",
+    "gateway_token_file"
+  ],
+  "properties": {
+    "$schema": {"type": "string"},
+    "project_key": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},
+    "contract_commit": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
+    "database_path": {"type": "string", "pattern": "^/"},
+    "file_inbox_path": {"type": "string", "pattern": "^/"},
+    "default_workload": {
+      "enum": [
+        "large_repetitive_infrastructure_monitoring",
+        "complex_code_security_architecture"
+      ]
+    },
+    "health_receipts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["central_gpt", "openclaw", "codex"],
+      "properties": {
+        "central_gpt": {"type": "string", "pattern": "^/"},
+        "openclaw": {"type": "string", "pattern": "^/"},
+        "codex": {"type": "string", "pattern": "^/"}
+      }
+    },
+    "git_ref_polling": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "refs"],
+      "properties": {
+        "repository": {"type": "string", "pattern": "^/"},
+        "refs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"type": "string", "pattern": "^refs/"}
+        }
+      }
+    },
+    "blocker_retry_threshold": {"type": "integer", "minimum": 1, "maximum": 20},
+    "max_health_age_seconds": {"type": "integer", "minimum": 5, "maximum": 300},
+    "lease_ttl_seconds": {"type": "integer", "minimum": 15, "maximum": 3600},
+    "gateway_event_url": {"type": "string", "const": "http://127.0.0.1:18920/v1/orchestrator/events"},
+    "gateway_token_file": {"type": "string", "pattern": "^/"}
+  }
+}

schemas/callback-transport.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AIOS Callback Transport",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mode", "endpoint", "approved_mcp_tunnel_endpoints"],
+  "properties": {
+    "mode": {
+      "enum": ["remote_https_action", "secure_mcp_tunnel"]
+    },
+    "endpoint": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "approved_mcp_tunnel_endpoints": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {"type": "string", "format": "uri", "pattern": "^https://"}
+    }
+  }
+}

schemas/codex-command.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aios.local/schemas/codex-command.schema.json",
+  "title": "AIOS Codex command",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "command_id", "project_key", "work_unit_id", "contract_commit", "state_version", "execution"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "command_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},
+    "project_key": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},
+    "work_unit_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},
+    "contract_commit": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
+    "state_version": {"type": "integer", "minimum": 0},
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "input"],
+      "properties": {
+        "kind": {"enum": ["acceptance_probe", "codex"]},
+        "input": {"type": "string", "maxLength": 65536}
+      }
+    }
+  }
+}

schemas/decision.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AIOS Orchestrator Decision",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "project_key",
+    "contract_commit",
+    "event_id",
+    "expected_state_version",
+    "verdict",
+    "state_updates",
+    "next_work_units",
+    "requires_human_input",
+    "stop_reason"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1
+    },
+    "project_key": {
+      "type": "string"
+    },
+    "contract_commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "event_id": {
+      "type": "string"
+    },
+    "expected_state_version": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "verdict": {
+      "type": "string",
+      "enum": [
+        "BLOCKED",
+        "COMPLETE",
+        "DISPATCH",
+        "NOOP"
+      ]
+    },
+    "state_updates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "key",
+          "value"
+        ],
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "next_work_units": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "track_id",
+          "gate_id",
+          "primary_agent",
+          "fallback_agent",
+          "clean_base_commit",
+          "allowed_paths",
+          "required_checks",
+          "forbidden_operations",
+          "instruction"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "track_id": {
+            "type": "string"
+          },
+          "gate_id": {
+            "type": "string"
+          },
+          "primary_agent": {
+            "type": "string",
+            "enum": [
+              "openclaw",
+              "codex"
+            ]
+          },
+          "fallback_agent": {
+            "type": "string",
+            "enum": [
+              "openclaw",
+              "codex"
+            ]
+          },
+          "clean_base_commit": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40}$"
+          },
+          "allowed_paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "required_checks": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "forbidden_operations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "instruction": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "requires_human_input": {
+      "type": "boolean"
+    },
+    "stop_reason": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  }
+}

schemas/event.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AIOS Orchestrator Event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "project_key",
+    "contract_commit",
+    "event_id",
+    "source_agent",
+    "event_type",
+    "work_unit_id",
+    "status",
+    "state_version",
+    "implementation_commit",
+    "result_commit",
+    "blocker",
+    "evidence_refs",
+    "payload"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "project_key": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "contract_commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "event_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "source_agent": {
+      "enum": [
+        "openclaw",
+        "codex",
+        "gitea",
+        "system",
+        "workspace-agent"
+      ]
+    },
+    "event_type": {
+      "type": "string"
+    },
+    "work_unit_id": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "READY",
+        "RUNNING",
+        "PASS",
+        "BLOCKED",
+        "FAIL",
+        "TIMEOUT",
+        "NOT_EXECUTED"
+      ]
+    },
+    "state_version": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "implementation_commit": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "result_commit": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "blocker": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "maxLength": 512
+    },
+    "evidence_refs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 64
+    },
+    "payload": {
+      "type": "object"
+    }
+  }
+}

scripts/bootstrap_orchestration_loop.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Seed exactly one orchestration event when the project has no durable state."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT))
+
+from services.aios_orchestrator_gateway.config import Config
+from services.aios_orchestrator_gateway.models import Event
+from services.aios_orchestrator_gateway.securefs import atomic_write_bytes_shared
+from services.aios_orchestrator_gateway.store import Store
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", type=Path, required=True)
+    args = parser.parse_args()
+
+    config = Config.from_file(args.config)
+    store = Store(config.database_path)
+    if store.project_state(config.project_key) is not None:
+        print("ORCHESTRATION_BOOTSTRAP=NOOP reason=STATE_EXISTS")
+        return 0
+
+    event = Event.from_dict(
+        {
+            "schema_version": 1,
+            "project_key": config.project_key,
+            "contract_commit": config.contract_commit,
+            "event_id": "bootstrap-" + config.contract_commit[:24],
+            "source_agent": "system",
+            "event_type": "orchestration_bootstrap",
+            "work_unit_id": "ORCHESTRATION-BOOTSTRAP",
+            "status": "READY",
+            "state_version": 0,
+            "implementation_commit": None,
+            "result_commit": None,
+            "blocker": None,
+            "evidence_refs": [],
+            "payload": {
+                "reason": "initial_gateway_install",
+                "polling_enabled": True,
+                "openclaw_sync_required": True,
+            },
+        }
+    )
+    path = config.event_inbox_dir / "pending" / f"{event.event_id}.json"
+    atomic_write_bytes_shared(
+        path,
+        (event.canonical_json() + "\n").encode(),
+        mode=0o640,
+        group_writable_directory=True,
+    )
+    print(f"ORCHESTRATION_BOOTSTRAP=PASS event_id={event.event_id}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/generate_orchestrator_tool_manifest.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from services.aios_orchestrator_gateway.callback_transport import CallbackTransport
+
+
+def atomic_write(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, path)
+        directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--transport-config", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    value = json.loads(args.transport_config.read_text(encoding="utf-8"))
+    if "callback_transport" in value:
+        value = value["callback_transport"]
+    transport = CallbackTransport.from_dict(value)
+    manifest = (
+        transport.action_openapi()
+        if transport.mode == "remote_https_action"
+        else {"endpoint": transport.endpoint, "tools": [transport.mcp_tool()]}
+    )
+    atomic_write(args.output, manifest)
+    print(f"TOOL_MANIFEST=PASS mode={transport.mode}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/install_aios_codex_watcher.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+[[ ${EUID} -eq 0 ]] || { echo "root required" >&2; exit 1; }
+ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd -P)
+CONFIG=${1:-/etc/aios-codex-watcher/config.json}
+[[ "$CONFIG" = /* ]] || { echo "config path must be absolute" >&2; exit 1; }
+[[ -f "$CONFIG" && ! -L "$CONFIG" ]] || { echo "pre-provisioned regular config required" >&2; exit 1; }
+
+for path in \
+  services/aios_codex_watcher/__init__.py \
+  services/aios_codex_watcher/__main__.py \
+  services/aios_codex_watcher/watcher.py \
+  systemd/aios-codex-watcher.service \
+  systemd/aios-codex-watcher.timer \
+  systemd/aios-codex-watcher.sysusers \
+  systemd/aios-codex-watcher.tmpfiles \
+  systemd/aios-codex-central.sysusers \
+  systemd/aios-codex-central.tmpfiles; do
+  [[ -f "$ROOT/$path" && ! -L "$ROOT/$path" ]] || { echo "missing or unsafe: $path" >&2; exit 1; }
+done
+
+digest=$(sha256sum \
+  "$ROOT/services/aios_codex_watcher/__init__.py" \
+  "$ROOT/services/aios_codex_watcher/__main__.py" \
+  "$ROOT/services/aios_codex_watcher/watcher.py" | sha256sum | awk '{print $1}')
+release="/opt/aios-codex-watcher/releases/$digest"
+install -d -o root -g root -m 0755 "$release/services/aios_codex_watcher" "$release/bin"
+install -o root -g root -m 0644 "$ROOT/services/aios_codex_watcher/"*.py "$release/services/aios_codex_watcher/"
+
+launcher="$release/bin/aios-codex-watcher"
+printf '%s\n' '#!/usr/bin/env bash' 'set -euo pipefail' \
+  "export PYTHONPATH='$release'" \
+  "exec /usr/bin/python3 -m services.aios_codex_watcher \"\$@\"" >"$launcher"
+chown root:root "$launcher"
+chmod 0755 "$launcher"
+
+install -d -o root -g root -m 0755 /opt/aios-codex-watcher /etc/aios-codex-watcher
+ln -sfn "releases/$digest" /opt/aios-codex-watcher/current.new
+mv -Tf /opt/aios-codex-watcher/current.new /opt/aios-codex-watcher/current
+install -o root -g root -m 0644 "$ROOT/systemd/aios-codex-watcher.service" /etc/systemd/system/
+install -o root -g root -m 0644 "$ROOT/systemd/aios-codex-watcher.timer" /etc/systemd/system/
+install -o root -g root -m 0644 "$ROOT/systemd/aios-codex-watcher.sysusers" /usr/lib/sysusers.d/
+install -o root -g root -m 0644 "$ROOT/systemd/aios-codex-watcher.tmpfiles" /usr/lib/tmpfiles.d/
+install -o root -g root -m 0644 "$ROOT/systemd/aios-codex-central.sysusers" /usr/lib/sysusers.d/
+install -o root -g root -m 0644 "$ROOT/systemd/aios-codex-central.tmpfiles" /usr/lib/tmpfiles.d/
+systemd-sysusers /usr/lib/sysusers.d/aios-codex-watcher.sysusers
+systemd-sysusers /usr/lib/sysusers.d/aios-codex-central.sysusers
+systemd-tmpfiles --create /usr/lib/tmpfiles.d/aios-codex-watcher.tmpfiles
+systemd-tmpfiles --create /usr/lib/tmpfiles.d/aios-codex-central.tmpfiles
+commands=/data/aios-gitops/workspace/agents/commands
+for directory in "$commands/active" "$commands/completed"; do
+  [[ -d "$directory" && ! -L "$directory" ]] || { echo "missing or unsafe command directory: $directory" >&2; exit 1; }
+  [[ $(stat -c '%U:%G' "$directory") == aios-orchestrator:aios-orchestrator ]] || { echo "unexpected command directory owner: $directory" >&2; exit 1; }
+  mode=$(stat -c '%a' "$directory")
+  (( (8#$mode & 2) == 0 )) || { echo "world-writable command directory: $directory" >&2; exit 1; }
+done
+if [[ -e "$commands/dead-letter" || -L "$commands/dead-letter" ]]; then
+  [[ -d "$commands/dead-letter" && ! -L "$commands/dead-letter" ]] || { echo "unsafe dead-letter directory" >&2; exit 1; }
+else
+  install -d -o aios-orchestrator -g aios-orchestrator -m 0750 "$commands/dead-letter"
+fi
+[[ $(stat -c '%U:%G' "$commands/dead-letter") == aios-orchestrator:aios-orchestrator ]] || { echo "unexpected dead-letter owner" >&2; exit 1; }
+mode=$(stat -c '%a' "$commands/dead-letter")
+(( (8#$mode & 2) == 0 )) || { echo "world-writable dead-letter directory" >&2; exit 1; }
+printf '{"release_sha256":"%s","installed_at":"%s"}\n' "$digest" "$(date -u +%FT%TZ)" >"$release/receipt.json"
+chmod 0644 "$release/receipt.json"
+systemctl daemon-reload
+systemctl enable --now aios-codex-watcher.timer
+printf 'installed_sha256=%s\n' "$digest"

scripts/install_aios_orchestrator_gateway.sh

@@ -0,0 +1,367 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+umask 0077
+
+SOURCE_ROOT="${SOURCE_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+INSTALL_ROOT="${INSTALL_ROOT:-/opt/aios-orchestrator-gateway}"
+CONFIG_ROOT="${CONFIG_ROOT:-/etc/aios-orchestrator-gateway}"
+STATE_ROOT="${STATE_ROOT:-/var/lib/aios-orchestrator-gateway}"
+UNIT_ROOT="${UNIT_ROOT:-/etc/systemd/system}"
+SYSUSERS_ROOT="${SYSUSERS_ROOT:-/etc/sysusers.d}"
+TMPFILES_ROOT="${TMPFILES_ROOT:-/etc/tmpfiles.d}"
+DRY_RUN=0
+
+if [[ "${1:-}" == "--dry-run" ]]; then
+  DRY_RUN=1
+fi
+
+fail() {
+  printf 'AIOS_ORCHESTRATOR_INSTALL=BLOCKED reason=%s\n' "$1" >&2
+  exit 2
+}
+
+[[ "$(id -u)" -eq 0 ]] || fail OWNER_INSTALL_REQUIRED
+
+for cmd in git python3 systemd-analyze systemctl systemd-sysusers systemd-tmpfiles sha256sum find sort xargs; do
+  command -v "$cmd" >/dev/null 2>&1 || fail "MISSING_COMMAND_${cmd}"
+done
+
+if [[ -f "$SOURCE_ROOT/SHA256SUMS" ]]; then
+  (cd "$SOURCE_ROOT" && sha256sum --check SHA256SUMS)
+fi
+
+for path in \
+  "$SOURCE_ROOT/services/aios_orchestrator_gateway" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.service" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway-poll.service" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway-poll.timer" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.sysusers" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.tmpfiles" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-remote-tool.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central.sysusers" \
+  "$SOURCE_ROOT/systemd/aios-codex-central.tmpfiles" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-decision.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-health.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-health.timer" \
+  "$SOURCE_ROOT/automation/remote_codex_health_probe.py" \
+  "$SOURCE_ROOT/config/aios-orchestrator-gateway.example.json"; do
+  [[ -e "$path" ]] || fail "MISSING_SOURCE_${path}"
+done
+
+PYCACHE="/tmp/aios-orchestrator-install-pycache-$$"
+rm -rf "$PYCACHE"
+PYTHONPYCACHEPREFIX="$PYCACHE" python3 -m compileall -q "$SOURCE_ROOT/services" "$SOURCE_ROOT/scripts" "$SOURCE_ROOT/automation"
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH="$SOURCE_ROOT" \
+  python3 -m unittest -v tests.test_aios_orchestrator_gateway tests.test_aios_remote_codex
+rm -rf "$PYCACHE"
+for script in "$SOURCE_ROOT"/scripts/*.sh; do bash -n "$script"; done
+python3 -m json.tool "$SOURCE_ROOT/config/aios-orchestrator-gateway.example.json" >/dev/null
+systemd-analyze verify \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.service" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway-poll.service" \
+  "$SOURCE_ROOT/systemd/aios-orchestrator-gateway-poll.timer"
+systemd-analyze verify \
+  "$SOURCE_ROOT/systemd/aios-codex-central-decision.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-health.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-health.timer"
+
+SOURCE_FILES=(
+  README-AIOS-ORCHESTRATOR-GATEWAY.md
+  docs/runbooks/A0-CALLBACK-TRANSPORT-AND-PENDING-RECOVERY.md
+  config/aios-orchestrator-gateway.example.json
+  schemas/decision.schema.json
+  schemas/event.schema.json
+  scripts/bootstrap_orchestration_loop.py
+  scripts/install_aios_orchestrator_gateway.sh
+  scripts/report_orchestrator_event.py
+  scripts/rollback_aios_orchestrator_gateway.sh
+  scripts/verify_aios_orchestrator_gateway.sh
+  systemd/aios-orchestrator-gateway-poll.service
+  systemd/aios-orchestrator-gateway-poll.timer
+  systemd/aios-orchestrator-gateway.service
+  systemd/aios-orchestrator-gateway.sysusers
+  systemd/aios-orchestrator-gateway.tmpfiles
+  systemd/aios-orchestrator-remote-tool.service
+  systemd/aios-codex-central-decision.service
+  systemd/aios-codex-central-health.service
+  systemd/aios-codex-central-health.timer
+  systemd/aios-codex-central.sysusers
+  systemd/aios-codex-central.tmpfiles
+  schemas/callback-transport.schema.json
+  scripts/generate_orchestrator_tool_manifest.py
+  scripts/recover_pending_decisions.py
+  scripts/install_codex_local_central.sh
+  automation/codex_central_decision.py
+  automation/codex_central_health_probe.py
+  automation/remote_codex_health_probe.py
+  tests/test_aios_orchestrator_gateway.py
+  tests/test_aios_remote_codex.py
+  tests/test_aios_orchestrator_gateway_rollback.sh
+  tests/test_aios_callback_recovery.py
+  workspace-agent/CENTRAL_AGENT_INSTRUCTIONS.md
+  workspace-agent/orchestrator-decision-action.openapi.yaml
+  openapi/aios-orchestrator-gateway.openapi.yaml
+)
+while IFS= read -r path; do SOURCE_FILES+=("$path"); done < <(
+  cd "$SOURCE_ROOT"
+  find services/aios_orchestrator_gateway -type f ! -path '*/__pycache__/*' ! -name '*.pyc' -print | sort
+)
+for path in "${SOURCE_FILES[@]}"; do
+  [[ -f "$SOURCE_ROOT/$path" && ! -L "$SOURCE_ROOT/$path" ]] || fail "INVALID_SOURCE_FILE_${path}"
+done
+
+SOURCE_DIGEST="$(
+  cd "$SOURCE_ROOT"
+  printf '%s\0' "${SOURCE_FILES[@]}" | sort -z | xargs -0 sha256sum \
+    | sha256sum \
+    | awk '{print $1}'
+)"
+[[ "$SOURCE_DIGEST" =~ ^[0-9a-f]{64}$ ]] || fail SOURCE_DIGEST_INVALID
+RELEASE_DIR="$INSTALL_ROOT/releases/$SOURCE_DIGEST"
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  printf 'AIOS_ORCHESTRATOR_INSTALL_DRY_RUN=PASS digest=%s release=%s\n' \
+    "$SOURCE_DIGEST" "$RELEASE_DIR"
+  exit 0
+fi
+
+systemd-sysusers "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.sysusers"
+systemd-sysusers "$SOURCE_ROOT/systemd/aios-codex-central.sysusers"
+
+install -d -m 0755 "$INSTALL_ROOT/releases"
+install -d -o root -g aios-orchestrator -m 0750 "$CONFIG_ROOT"
+install -d -m 0700 "$STATE_ROOT"
+
+systemd-tmpfiles --create "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.tmpfiles"
+systemd-tmpfiles --create "$SOURCE_ROOT/systemd/aios-codex-central.tmpfiles"
+
+if [[ ! -d "$RELEASE_DIR" ]]; then
+  TMP_RELEASE="$INSTALL_ROOT/releases/.tmp-$SOURCE_DIGEST-$$"
+  install -d -m 0755 "$TMP_RELEASE"
+  for path in "${SOURCE_FILES[@]}"; do
+    install -d -m 0755 "$TMP_RELEASE/$(dirname "$path")"
+    cp -a "$SOURCE_ROOT/$path" "$TMP_RELEASE/$path"
+  done
+  printf '%s\n' "$SOURCE_DIGEST" > "$TMP_RELEASE/SOURCE_DIGEST"
+  chmod -R go-w "$TMP_RELEASE"
+  mv "$TMP_RELEASE" "$RELEASE_DIR"
+fi
+
+PREVIOUS_TARGET=""
+if [[ -L "$INSTALL_ROOT/current" ]]; then
+  PREVIOUS_TARGET="$(readlink -f "$INSTALL_ROOT/current")"
+fi
+
+install -m 0644 "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.service" \
+  "$UNIT_ROOT/aios-orchestrator-gateway.service"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-orchestrator-gateway-poll.service" \
+  "$UNIT_ROOT/aios-orchestrator-gateway-poll.service"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-orchestrator-gateway-poll.timer" \
+  "$UNIT_ROOT/aios-orchestrator-gateway-poll.timer"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.sysusers" \
+  "$SYSUSERS_ROOT/aios-orchestrator-gateway.conf"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-orchestrator-gateway.tmpfiles" \
+  "$TMPFILES_ROOT/aios-orchestrator-gateway.conf"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-codex-central.sysusers" \
+  "$SYSUSERS_ROOT/aios-codex-central.conf"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-codex-central.tmpfiles" \
+  "$TMPFILES_ROOT/aios-codex-central.conf"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-orchestrator-remote-tool.service" \
+  "$UNIT_ROOT/aios-orchestrator-remote-tool.service"
+
+if [[ ! -f "$CONFIG_ROOT/inbound.token" ]]; then
+  python3 - <<'PY' > "$CONFIG_ROOT/inbound.token"
+import secrets, sys
+sys.stdout.write(secrets.token_urlsafe(48))
+PY
+fi
+[[ ! -L "$CONFIG_ROOT/inbound.token" ]] || fail INBOUND_TOKEN_SYMLINK
+chown root:aios-orchestrator "$CONFIG_ROOT/inbound.token"
+chmod 0640 "$CONFIG_ROOT/inbound.token"
+
+if [[ ! -f "$CONFIG_ROOT/callback.token" ]]; then
+  python3 - <<'PY' > "$CONFIG_ROOT/callback.token"
+import secrets, sys
+sys.stdout.write(secrets.token_urlsafe(48))
+PY
+fi
+[[ ! -L "$CONFIG_ROOT/callback.token" ]] || fail CALLBACK_TOKEN_SYMLINK
+chown root:aios-orchestrator "$CONFIG_ROOT/callback.token"
+chmod 0640 "$CONFIG_ROOT/callback.token"
+
+# Historical installers appended one LF. Remove only that exact legacy byte in
+# place; reject every other newline form without ever copying or printing data.
+python3 - "$CONFIG_ROOT/config.json" "$CONFIG_ROOT/inbound.token" "$CONFIG_ROOT/callback.token" <<'PY'
+import json, os, pathlib, stat, sys
+config_path = pathlib.Path(sys.argv[1])
+names = list(sys.argv[2:])
+if config_path.is_file() and not config_path.is_symlink():
+    config = json.loads(config_path.read_text())
+    candidates = [
+        config.get("inbound_token_file"),
+        config.get("callback_token_file"),
+        (config.get("workspace_agent") or {}).get("access_token_file"),
+        (config.get("responses_fallback") or {}).get("api_key_file"),
+        (config.get("openclaw_sync") or {}).get("bearer_token_file"),
+    ]
+    candidates.extend(
+        item.get("token_file") for item in (config.get("remote_codex") or {}).get("runners", [])
+        if isinstance(item, dict)
+    )
+    names.extend(name for name in candidates if isinstance(name, str) and name)
+for name in dict.fromkeys(names):
+    path = pathlib.Path(name)
+    if not path.is_absolute() or path.is_symlink() or path.resolve() != path:
+        raise SystemExit("invalid token path")
+    fd = os.open(name, os.O_RDWR | getattr(os, "O_NOFOLLOW", 0))
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_size <= 0 or info.st_size > 16384:
+            raise SystemExit("invalid token metadata")
+        data = os.read(fd, info.st_size)
+        if data.endswith(b"\n") and b"\n" not in data[:-1] and b"\r" not in data:
+            os.ftruncate(fd, info.st_size - 1)
+            os.fsync(fd)
+        elif b"\n" in data or b"\r" in data:
+            raise SystemExit("invalid token format")
+    finally:
+        os.close(fd)
+PY
+
+if [[ ! -f "$CONFIG_ROOT/config.json" ]]; then
+  install -m 0600 \
+    "$SOURCE_ROOT/config/aios-orchestrator-gateway.example.json" \
+    "$CONFIG_ROOT/config.json.example"
+  printf 'AIOS_ORCHESTRATOR_INSTALL=BLOCKED reason=CONFIGURATION_REQUIRED digest=%s\n' \
+    "$SOURCE_DIGEST"
+  exit 2
+fi
+
+chown root:aios-orchestrator "$CONFIG_ROOT/config.json"
+chmod 0640 "$CONFIG_ROOT/config.json"
+
+python3 -m json.tool "$CONFIG_ROOT/config.json" >/dev/null
+AIOS_ORCHESTRATOR_CONFIG_OWNER_UID=0 \
+AIOS_ORCHESTRATOR_SECRET_OWNER_UID=0 \
+PYTHONPATH="$RELEASE_DIR" \
+python3 - "$CONFIG_ROOT/config.json" <<'PY'
+import sys
+from pathlib import Path
+from services.aios_orchestrator_gateway.config import Config
+cfg = Config.from_file(Path(sys.argv[1]))
+cfg.inbound_token()
+cfg.callback_token()
+if cfg.workspace_trigger_id:
+    cfg.workspace_token()
+if cfg.responses_api_key_file:
+    cfg.responses_api_key()
+if cfg.openclaw_sync_endpoint:
+    cfg.openclaw_sync_token()
+for runner in cfg.remote_runner_credentials:
+    for scope in runner.scopes:
+        cfg.remote_runner_token(runner.runner_id, scope)
+print("CONFIG_VALIDATE=PASS")
+PY
+
+# Commit the release pointer only after every candidate/config/secret check has
+# succeeded. A failed validation therefore leaves the running release intact.
+ln -s "$RELEASE_DIR" "$INSTALL_ROOT/.current-new-$$"
+mv -Tf "$INSTALL_ROOT/.current-new-$$" "$INSTALL_ROOT/current"
+
+python3 - "$STATE_ROOT/install-receipt.json" "$SOURCE_DIGEST" "$RELEASE_DIR" "$PREVIOUS_TARGET" <<'PY'
+import json, os, sys, tempfile
+from pathlib import Path
+path = Path(sys.argv[1])
+data = {
+    "schema_version": 1,
+    "source_digest": sys.argv[2],
+    "current_release": sys.argv[3],
+    "previous_release": sys.argv[4] or None,
+    "last_rollback": None,
+}
+path.parent.mkdir(parents=True, exist_ok=True)
+fd, temp = tempfile.mkstemp(prefix=".install-receipt-", dir=path.parent)
+try:
+    with os.fdopen(fd, "w") as handle:
+        json.dump(data, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.chmod(temp, 0o600)
+    os.replace(temp, path)
+    directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(directory)
+    finally:
+        os.close(directory)
+finally:
+    try:
+        os.unlink(temp)
+    except FileNotFoundError:
+        pass
+PY
+chown root:root "$STATE_ROOT/install-receipt.json"
+chmod 0600 "$STATE_ROOT/install-receipt.json"
+
+systemctl daemon-reload
+systemctl enable aios-orchestrator-gateway.service
+systemctl enable aios-orchestrator-gateway-poll.timer
+systemctl stop aios-orchestrator-gateway-poll.timer || true
+systemctl stop aios-orchestrator-gateway-poll.service || true
+
+rollback_activation() {
+  if [[ -n "$PREVIOUS_TARGET" && -d "$PREVIOUS_TARGET" ]]; then
+    bash "$RELEASE_DIR/scripts/rollback_aios_orchestrator_gateway.sh" || true
+  else
+    systemctl stop aios-orchestrator-gateway.service || true
+  fi
+  fail ACTIVATION_FAILED_ROLLED_BACK
+}
+
+systemctl restart aios-orchestrator-gateway.service || rollback_activation
+python3 - <<'PY' || rollback_activation
+import json, time, urllib.request
+for _ in range(30):
+    try:
+        with urllib.request.urlopen("http://127.0.0.1:18920/healthz", timeout=1) as response:
+            body = json.loads(response.read(65536))
+            if response.status == 200 and body.get("status") == "active":
+                raise SystemExit(0)
+    except Exception:
+        pass
+    time.sleep(0.5)
+raise SystemExit(1)
+PY
+systemctl start aios-orchestrator-gateway-poll.timer || rollback_activation
+systemctl is-active --quiet aios-orchestrator-gateway.service
+systemctl is-active --quiet aios-orchestrator-gateway-poll.timer
+
+AIOS_ORCHESTRATOR_CONFIG_OWNER_UID=0 \
+AIOS_ORCHESTRATOR_SECRET_OWNER_UID=0 \
+PYTHONPATH="$INSTALL_ROOT/current" \
+python3 "$INSTALL_ROOT/current/scripts/bootstrap_orchestration_loop.py" \
+  --config "$CONFIG_ROOT/config.json"
+systemctl start aios-orchestrator-gateway-poll.service || rollback_activation
+
+if [[ -f "$CONFIG_ROOT/remote-tool.json" ]]; then
+  [[ ! -L "$CONFIG_ROOT/remote-tool.json" ]] || fail REMOTE_TOOL_CONFIG_SYMLINK
+  chown root:aios-orchestrator "$CONFIG_ROOT/remote-tool.json"
+  chmod 0640 "$CONFIG_ROOT/remote-tool.json"
+  PYTHONPATH="$RELEASE_DIR" python3 - "$CONFIG_ROOT/remote-tool.json" <<'PY'
+import sys
+from pathlib import Path
+from services.aios_orchestrator_gateway.remote_tool_server import RemoteToolServerConfig
+RemoteToolServerConfig.from_file(Path(sys.argv[1]))
+print("REMOTE_TOOL_CONFIG_VALIDATE=PASS")
+PY
+  PYTHONPATH="$RELEASE_DIR" python3 \
+    "$RELEASE_DIR/scripts/generate_orchestrator_tool_manifest.py" \
+    --transport-config "$CONFIG_ROOT/remote-tool.json" \
+    --output "$STATE_ROOT/orchestrator-tool-manifest.json"
+  systemctl enable --now aios-orchestrator-remote-tool.service
+else
+  printf 'REMOTE_TOOL_CONFIGURATION=BLOCKED reason=REMOTE_CALLBACK_ENDPOINT_CONFIGURATION\n'
+fi
+
+printf 'AIOS_ORCHESTRATOR_INSTALL=PASS digest=%s previous=%s\n' \
+  "$SOURCE_DIGEST" "${PREVIOUS_TARGET:-NONE}"

scripts/install_automation_quorum_controller.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ ${EUID} -ne 0 ]]; then
+  echo "root required" >&2
+  exit 1
+fi
+
+SOURCE_ROOT=${1:?usage: install_automation_quorum_controller.sh SOURCE_ROOT VERSION}
+VERSION=${2:?usage: install_automation_quorum_controller.sh SOURCE_ROOT VERSION}
+[[ ${VERSION} =~ ^[0-9A-Za-z._-]+$ ]] || { echo "invalid version" >&2; exit 1; }
+SOURCE_REAL=$(readlink -f -- "${SOURCE_ROOT}" 2>/dev/null || true)
+[[ ${SOURCE_ROOT} = /* && -n ${SOURCE_REAL} && ${SOURCE_ROOT} == "${SOURCE_REAL}" && -d ${SOURCE_ROOT} && ! -L ${SOURCE_ROOT} ]] || {
+  echo "unsafe source root" >&2
+  exit 1
+}
+
+SOURCE_FILES=(
+  automation/executor_quorum_controller.py
+  automation/health_probe_common.py
+  automation/central_gpt_health_probe.py
+  automation/codex_executor_health_probe.py
+  automation/a0_unattended_loop_probe.py
+  schemas/automation-quorum-controller.schema.json
+  config/aios-automation-quorum-controller.example.json
+  config/aios-health-probes.example.json
+  systemd/aios-automation-quorum-controller.service
+  systemd/aios-automation-quorum-controller.timer
+  systemd/aios-automation-quorum-controller.sysusers
+  systemd/aios-automation-quorum-controller.tmpfiles
+  systemd/aios-central-gpt-health-probe.service
+  systemd/aios-central-gpt-health-probe.timer
+  systemd/aios-codex-executor-health-probe.service
+  systemd/aios-codex-executor-health-probe.timer
+)
+for relative in "${SOURCE_FILES[@]}"; do
+  [[ -f ${SOURCE_ROOT}/${relative} && ! -L ${SOURCE_ROOT}/${relative} ]] || {
+    echo "unsafe source file: ${relative}" >&2
+    exit 1
+  }
+done
+
+INSTALL_ROOT=/opt/aios-automation-quorum
+VERSION_DIR=${INSTALL_ROOT}/releases/${VERSION}
+[[ ! -e ${VERSION_DIR} ]] || { echo "version already installed" >&2; exit 1; }
+
+install -d -o root -g root -m 0755 "${VERSION_DIR}/bin" "${VERSION_DIR}/share"
+install -o root -g root -m 0755 "${SOURCE_ROOT}/automation/executor_quorum_controller.py" \
+  "${VERSION_DIR}/bin/executor-quorum-controller"
+install -o root -g root -m 0644 "${SOURCE_ROOT}/automation/health_probe_common.py" \
+  "${VERSION_DIR}/bin/health_probe_common.py"
+install -o root -g root -m 0755 "${SOURCE_ROOT}/automation/central_gpt_health_probe.py" \
+  "${VERSION_DIR}/bin/central-gpt-health-probe"
+install -o root -g root -m 0755 "${SOURCE_ROOT}/automation/codex_executor_health_probe.py" \
+  "${VERSION_DIR}/bin/codex-executor-health-probe"
+install -o root -g root -m 0755 "${SOURCE_ROOT}/automation/a0_unattended_loop_probe.py" \
+  "${VERSION_DIR}/bin/a0-unattended-loop-probe"
+install -o root -g root -m 0644 "${SOURCE_ROOT}/schemas/automation-quorum-controller.schema.json" \
+  "${VERSION_DIR}/share/automation-quorum-controller.schema.json"
+python3 -m py_compile "${VERSION_DIR}/bin/executor-quorum-controller" \
+  "${VERSION_DIR}/bin/health_probe_common.py" \
+  "${VERSION_DIR}/bin/central-gpt-health-probe" \
+  "${VERSION_DIR}/bin/codex-executor-health-probe"
+python3 -m py_compile "${VERSION_DIR}/bin/a0-unattended-loop-probe"
+
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-automation-quorum-controller.service" /etc/systemd/system/
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-automation-quorum-controller.timer" /etc/systemd/system/
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-central-gpt-health-probe.service" /etc/systemd/system/
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-central-gpt-health-probe.timer" /etc/systemd/system/
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-codex-executor-health-probe.service" /etc/systemd/system/
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-codex-executor-health-probe.timer" /etc/systemd/system/
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-automation-quorum-controller.sysusers" /usr/lib/sysusers.d/aios-automation-quorum-controller.conf
+install -o root -g root -m 0644 "${SOURCE_ROOT}/systemd/aios-automation-quorum-controller.tmpfiles" /usr/lib/tmpfiles.d/aios-automation-quorum-controller.conf
+
+systemd-sysusers /usr/lib/sysusers.d/aios-automation-quorum-controller.conf
+systemd-tmpfiles --create /usr/lib/tmpfiles.d/aios-automation-quorum-controller.conf
+install -d -o root -g aios-quorum -m 0750 /etc/aios-automation-quorum
+if [[ ! -e /etc/aios-automation-quorum/controller.json ]]; then
+  install -o root -g aios-quorum -m 0640 \
+    "${SOURCE_ROOT}/config/aios-automation-quorum-controller.example.json" \
+    /etc/aios-automation-quorum/controller.json
+fi
+if [[ ! -e /etc/aios-automation-quorum/health-probes.json ]]; then
+  install -o root -g root -m 0600 \
+    "${SOURCE_ROOT}/config/aios-health-probes.example.json" \
+    /etc/aios-automation-quorum/health-probes.json
+fi
+
+PREVIOUS_TARGET=$(readlink -f "${INSTALL_ROOT}/current" 2>/dev/null || true)
+RECEIPT=${VERSION_DIR}/install-receipt.json
+python3 - "${VERSION_DIR}" "${VERSION}" "${PREVIOUS_TARGET}" "${RECEIPT}" <<'PY'
+import hashlib, json, os, pathlib, sys, tempfile
+root, version, previous, receipt = map(pathlib.Path, (sys.argv[1], sys.argv[2], sys.argv[3] or ".", sys.argv[4]))
+files = {}
+for item in sorted(root.rglob("*")):
+    if item.is_file() and not item.is_symlink():
+        files[str(item.relative_to(root))] = hashlib.sha256(item.read_bytes()).hexdigest()
+payload = {"version": str(version), "previous_target": "" if str(previous) == "." else str(previous), "files": files}
+fd, temp = tempfile.mkstemp(dir=str(receipt.parent), prefix=".receipt-")
+with os.fdopen(fd, "w", encoding="utf-8") as handle:
+    json.dump(payload, handle, sort_keys=True, separators=(",", ":"))
+    handle.write("\n")
+os.chmod(temp, 0o600)
+os.replace(temp, receipt)
+PY
+
+ln -sfn "${VERSION_DIR}" "${INSTALL_ROOT}/.current-${VERSION}"
+mv -Tf "${INSTALL_ROOT}/.current-${VERSION}" "${INSTALL_ROOT}/current"
+
+systemctl daemon-reload
+echo "installed=${VERSION_DIR}"
+echo "previous=${PREVIOUS_TARGET}"

scripts/install_codex_local_central.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+umask 0077
+
+SOURCE_ROOT="${SOURCE_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+UNIT_ROOT="${UNIT_ROOT:-/etc/systemd/system}"
+SYSUSERS_ROOT="${SYSUSERS_ROOT:-/etc/sysusers.d}"
+TMPFILES_ROOT="${TMPFILES_ROOT:-/etc/tmpfiles.d}"
+CODEX_BINARY=/usr/local/bin/codex
+CODEX_HOME=/var/lib/aios-codex-brain/.codex
+AUTH_JSON="$CODEX_HOME/auth.json"
+CONTROLLER=/data/aios-gitops/worktrees/controller
+LOCK=/run/lock/aios-codex-auth.lock
+
+fail() {
+  printf 'STATUS=%s\nAUTOMATION_CLOSED=NO\n' "$1" >&2
+  exit 2
+}
+
+[[ "$(id -u)" -eq 0 ]] || fail OWNER_INSTALL_REQUIRED
+for command in python3 runuser systemctl systemd-analyze systemd-sysusers systemd-tmpfiles; do
+  command -v "$command" >/dev/null 2>&1 || fail "MISSING_COMMAND_${command}"
+done
+
+for path in \
+  "$SOURCE_ROOT/systemd/aios-codex-central-decision.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-health.service" \
+  "$SOURCE_ROOT/systemd/aios-codex-central-health.timer" \
+  "$SOURCE_ROOT/systemd/aios-codex-central.sysusers" \
+  "$SOURCE_ROOT/systemd/aios-codex-central.tmpfiles" \
+  "$SOURCE_ROOT/automation/codex_central_decision.py" \
+  "$SOURCE_ROOT/automation/codex_central_health_probe.py"; do
+  [[ -f "$path" && ! -L "$path" ]] || fail INVALID_SOURCE
+done
+
+systemd-sysusers "$SOURCE_ROOT/systemd/aios-codex-central.sysusers"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-codex-central.sysusers" "$SYSUSERS_ROOT/aios-codex-central.conf"
+install -m 0644 "$SOURCE_ROOT/systemd/aios-codex-central.tmpfiles" "$TMPFILES_ROOT/aios-codex-central.conf"
+systemd-tmpfiles --create "$SOURCE_ROOT/systemd/aios-codex-central.tmpfiles"
+
+for unit in aios-codex-central-decision.service aios-codex-central-health.service aios-codex-central-health.timer; do
+  install -m 0644 "$SOURCE_ROOT/systemd/$unit" "$UNIT_ROOT/$unit"
+done
+systemd-analyze verify \
+  "$UNIT_ROOT/aios-codex-central-decision.service" \
+  "$UNIT_ROOT/aios-codex-central-health.service" \
+  "$UNIT_ROOT/aios-codex-central-health.timer"
+
+[[ -f "$CODEX_BINARY" && ! -L "$CODEX_BINARY" && -x "$CODEX_BINARY" ]] || \
+  fail BLOCKED_CODEX_CLI_VERSION_INCOMPATIBLE
+[[ -d "$CONTROLLER" && ! -L "$CONTROLLER" ]] || fail CONTROLLER_WORKDIR_UNAVAILABLE
+
+help_output="$(runuser -u aios-codex-brain -- env -i \
+  CODEX_HOME="$CODEX_HOME" HOME=/var/lib/aios-codex-brain \
+  PATH=/usr/local/bin:/usr/bin:/bin LANG=C.UTF-8 LC_ALL=C.UTF-8 \
+  "$CODEX_BINARY" exec --help 2>/dev/null)" || fail BLOCKED_CODEX_CLI_VERSION_INCOMPATIBLE
+for flag in --json --output-schema --output-last-message --sandbox --ask-for-approval --cd --ephemeral; do
+  grep -F -- "$flag" <<<"$help_output" >/dev/null || fail BLOCKED_CODEX_CLI_VERSION_INCOMPATIBLE
+done
+unset help_output
+
+[[ -e "$AUTH_JSON" ]] || fail BLOCKED_CODEX_AUTHENTICATION_REQUIRED
+if ! python3 - "$AUTH_JSON" <<'PY'
+import os,pwd,stat,sys
+p=sys.argv[1]
+s=os.lstat(p)
+if stat.S_ISLNK(s.st_mode) or not stat.S_ISREG(s.st_mode): raise SystemExit("unsafe auth")
+if s.st_uid != pwd.getpwnam("aios-codex-brain").pw_uid: raise SystemExit("wrong owner")
+if stat.S_IMODE(s.st_mode) != 0o600: raise SystemExit("wrong mode")
+PY
+then
+  fail BLOCKED_CODEX_AUTHENTICATION_REQUIRED
+fi
+
+runuser -u aios-codex-brain -- env -i \
+  CODEX_HOME="$CODEX_HOME" HOME=/var/lib/aios-codex-brain \
+  PATH=/usr/local/bin:/usr/bin:/bin LANG=C.UTF-8 LC_ALL=C.UTF-8 \
+  "$CODEX_BINARY" login status >/dev/null 2>&1 || fail BLOCKED_CODEX_AUTHENTICATION_REQUIRED
+
+systemctl daemon-reload
+systemctl enable --now aios-codex-central-decision.service
+systemctl enable --now aios-codex-central-health.timer
+systemctl start aios-codex-central-health.service || fail BLOCKED_CODEX_AUTHENTICATION_REQUIRED
+printf 'CODEX_LOCAL_CENTRAL_INSTALL=PASS\n'

scripts/recover_pending_decisions.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from services.aios_orchestrator_gateway.config import Config
+from services.aios_orchestrator_gateway.recovery import (
+    PendingDecisionRecovery,
+    RecoverySettings,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", type=Path, required=True)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--plan", action="store_true")
+    mode.add_argument("--apply-one", action="store_true")
+    args = parser.parse_args()
+    config = Config.from_file(args.config)
+    recovery = PendingDecisionRecovery(RecoverySettings(
+        database_path=config.database_path,
+        contract_commit=config.contract_commit,
+        lease_seconds=config.lease_seconds,
+        max_retries=config.max_retries,
+        retry_after=config.retry_base_seconds,
+    ), plan_only=args.plan)
+    if args.plan:
+        print(json.dumps(recovery.plan(), separators=(",", ":"), sort_keys=True))
+    else:
+        print(json.dumps({"processed_event_id": recovery.apply_one()}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/report_orchestrator_event.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Submit an OpenClaw/Codex task lifecycle event over HTTP or a polled inbox."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import urllib.error
+import urllib.request
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT))
+
+from services.aios_orchestrator_gateway.models import Event
+from services.aios_orchestrator_gateway.securefs import atomic_write_bytes_shared, read_secure_json, read_secure_text
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser()
+    p.add_argument("--project-key", required=True)
+    p.add_argument("--contract-commit", required=True)
+    p.add_argument("--event-id", required=True)
+    p.add_argument("--source-agent", required=True, choices=["openclaw", "codex", "gitea", "system"])
+    p.add_argument("--event-type", required=True)
+    p.add_argument("--work-unit-id", required=True)
+    p.add_argument(
+        "--status",
+        required=True,
+        choices=["READY", "RUNNING", "PASS", "BLOCKED", "FAIL", "TIMEOUT", "NOT_EXECUTED"],
+    )
+    p.add_argument("--state-version", type=int, required=True)
+    p.add_argument("--implementation-commit")
+    p.add_argument("--result-commit")
+    p.add_argument("--blocker")
+    p.add_argument("--evidence-ref", action="append", default=[])
+    p.add_argument("--payload-file", type=Path)
+    p.add_argument("--endpoint")
+    p.add_argument("--token-file", type=Path)
+    p.add_argument("--inbox-dir", type=Path)
+    p.add_argument("--timeout-seconds", type=int, default=15)
+    return p
+
+
+def main() -> int:
+    args = parser().parse_args()
+    if not args.endpoint and not args.inbox_dir:
+        raise SystemExit("either --endpoint or --inbox-dir is required")
+    if args.endpoint and not args.token_file:
+        raise SystemExit("--token-file is required with --endpoint")
+    payload = {}
+    if args.payload_file:
+        if not args.payload_file.is_absolute():
+            raise SystemExit("--payload-file must be absolute")
+        payload = read_secure_json(
+            args.payload_file, expected_uid=os.getuid(), max_bytes=262_144
+        )
+        if not isinstance(payload, dict):
+            raise SystemExit("payload root must be an object")
+
+    event = Event.from_dict(
+        {
+            "schema_version": 1,
+            "project_key": args.project_key,
+            "contract_commit": args.contract_commit,
+            "event_id": args.event_id,
+            "source_agent": args.source_agent,
+            "event_type": args.event_type,
+            "work_unit_id": args.work_unit_id,
+            "status": args.status,
+            "state_version": args.state_version,
+            "implementation_commit": args.implementation_commit,
+            "result_commit": args.result_commit,
+            "blocker": args.blocker,
+            "evidence_refs": args.evidence_ref,
+            "payload": payload,
+        }
+    )
+    encoded = event.canonical_json().encode()
+    http_error: Exception | None = None
+
+    if args.endpoint:
+        token = read_secure_text(
+            args.token_file,
+            expected_uid=None,
+            max_bytes=64_000,
+        )
+        request = urllib.request.Request(
+            args.endpoint.rstrip("/") + "/v1/orchestrator/events",
+            data=encoded,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Idempotency-Key": event.event_id,
+                "User-Agent": "aios-agent-event-reporter/0.2",
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=args.timeout_seconds) as response:
+                response.read(65_536)
+                if response.status not in {200, 202}:
+                    raise RuntimeError(f"unexpected HTTP {response.status}")
+                print(f"EVENT_SUBMIT=PASS event_id={event.event_id} channel=http")
+                return 0
+        except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as exc:
+            http_error = exc
+
+    if args.inbox_dir:
+        pending = args.inbox_dir / "pending"
+        path = pending / f"{event.event_id}.json"
+        atomic_write_bytes_shared(
+            path,
+            (json.dumps(event.to_dict(), indent=2, sort_keys=True) + "\n").encode(),
+            mode=0o640,
+            group_writable_directory=True,
+        )
+        print(f"EVENT_SUBMIT=PASS event_id={event.event_id} channel=file_inbox")
+        return 0
+
+    print(
+        f"EVENT_SUBMIT=FAIL event_id={event.event_id} reason={type(http_error).__name__}",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/rollback_aios_orchestrator_gateway.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+umask 0077
+
+INSTALL_ROOT="${INSTALL_ROOT:-/opt/aios-orchestrator-gateway}"
+STATE_ROOT="${STATE_ROOT:-/var/lib/aios-orchestrator-gateway}"
+RECEIPT="$STATE_ROOT/install-receipt.json"
+
+fail() {
+  printf 'AIOS_ORCHESTRATOR_ROLLBACK=BLOCKED reason=%s\n' "$1" >&2
+  exit 2
+}
+
+[[ "$(id -u)" -eq 0 ]] || fail OWNER_REQUIRED
+[[ -f "$RECEIPT" ]] || fail RECEIPT_MISSING
+[[ ! -L "$RECEIPT" ]] || fail RECEIPT_SYMLINK
+[[ "$(stat -c '%u:%a' "$RECEIPT")" == "0:600" ]] || fail RECEIPT_PERMISSION
+
+readarray -t VALUES < <(
+python3 - "$RECEIPT" "$INSTALL_ROOT/releases" "$INSTALL_ROOT/current" <<'PY'
+import json, os, stat, sys
+from pathlib import Path
+receipt = Path(sys.argv[1])
+releases = Path(sys.argv[2]).resolve()
+current_link = Path(sys.argv[3])
+data = json.loads(receipt.read_text())
+previous = data.get("previous_release")
+current = data.get("current_release")
+if not previous or not current:
+    raise SystemExit(2)
+previous_path = Path(previous).resolve()
+current_path = Path(current).resolve()
+if previous_path.parent != releases or current_path.parent != releases:
+    raise SystemExit(2)
+if not stat.S_ISDIR(os.lstat(previous_path).st_mode) or not stat.S_ISDIR(os.lstat(current_path).st_mode):
+    raise SystemExit(2)
+for release in (previous_path, current_path):
+    if len(release.name) != 64 or any(ch not in "0123456789abcdef" for ch in release.name):
+        raise SystemExit(2)
+    digest_file = release / "SOURCE_DIGEST"
+    if digest_file.is_symlink() or not digest_file.is_file():
+        raise SystemExit(2)
+    if digest_file.read_text(encoding="utf-8").strip() != release.name:
+        raise SystemExit(2)
+last = data.get("last_rollback")
+if isinstance(last, dict) and last.get("to") == current and current_link.is_symlink():
+    if current_link.resolve() == current_path:
+        print("ALREADY_ROLLED_BACK")
+        raise SystemExit(0)
+print(previous_path)
+print(current_path)
+PY
+) || fail RECEIPT_INVALID
+
+if [[ "${VALUES[0]:-}" == "ALREADY_ROLLED_BACK" ]]; then
+  echo "AIOS_ORCHESTRATOR_ROLLBACK=PASS result=NOOP_ALREADY_ROLLED_BACK"
+  exit 0
+fi
+[[ "${#VALUES[@]}" -eq 2 ]] || fail RECEIPT_INVALID
+PREVIOUS="${VALUES[0]}"
+CURRENT="${VALUES[1]}"
+systemctl stop aios-orchestrator-gateway-poll.timer || true
+systemctl stop aios-orchestrator-gateway-poll.service || true
+systemctl stop aios-orchestrator-gateway.service || true
+ln -s "$PREVIOUS" "$INSTALL_ROOT/.current-rollback-$$"
+mv -Tf "$INSTALL_ROOT/.current-rollback-$$" "$INSTALL_ROOT/current"
+systemctl start aios-orchestrator-gateway.service
+systemctl is-active --quiet aios-orchestrator-gateway.service
+systemctl start aios-orchestrator-gateway-poll.timer
+systemctl is-active --quiet aios-orchestrator-gateway-poll.timer
+
+python3 - "$RECEIPT" "$PREVIOUS" "$CURRENT" <<'PY'
+import json, os, sys, tempfile
+from pathlib import Path
+path = Path(sys.argv[1])
+data = json.loads(path.read_text())
+data["current_release"] = sys.argv[2]
+data["previous_release"] = sys.argv[3]
+data["last_rollback"] = {"from": sys.argv[3], "to": sys.argv[2]}
+fd, temp = tempfile.mkstemp(prefix=".rollback-receipt-", dir=path.parent)
+try:
+    with os.fdopen(fd, "w") as handle:
+        json.dump(data, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.chmod(temp, 0o600)
+    os.chown(temp, 0, 0)
+    os.replace(temp, path)
+    directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(directory)
+    finally:
+        os.close(directory)
+finally:
+    try:
+        os.unlink(temp)
+    except FileNotFoundError:
+        pass
+PY
+
+printf 'AIOS_ORCHESTRATOR_ROLLBACK=PASS current=%s previous=%s\n' "$PREVIOUS" "$CURRENT"

scripts/rollback_automation_quorum_controller.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ ${EUID} -ne 0 ]]; then
+  echo "root required" >&2
+  exit 1
+fi
+
+TARGET=${1:?usage: rollback_automation_quorum_controller.sh ABSOLUTE_RELEASE_PATH}
+INSTALL_ROOT=/opt/aios-automation-quorum
+TARGET_REAL=$(readlink -f -- "${TARGET}" 2>/dev/null || true)
+[[ -n ${TARGET_REAL} && ${TARGET} == "${TARGET_REAL}" ]] || { echo "non-canonical or missing rollback target" >&2; exit 1; }
+case ${TARGET_REAL} in
+  "${INSTALL_ROOT}"/releases/*) ;;
+  *) echo "target outside release root" >&2; exit 1 ;;
+esac
+[[ -d ${TARGET_REAL} && ! -L ${TARGET} ]] || { echo "invalid rollback target" >&2; exit 1; }
+
+CURRENT=$(readlink -f "${INSTALL_ROOT}/current" 2>/dev/null || true)
+if [[ ${CURRENT} == "${TARGET_REAL}" ]]; then
+  echo "already_current=${CURRENT}"
+  exit 0
+fi
+
+ln -sfn "${TARGET_REAL}" "${INSTALL_ROOT}/.rollback-current"
+mv -Tf "${INSTALL_ROOT}/.rollback-current" "${INSTALL_ROOT}/current"
+systemctl daemon-reload
+systemctl try-restart aios-automation-quorum-controller.timer
+echo "rolled_back_to=$(readlink -f "${INSTALL_ROOT}/current")"

scripts/validate_automation_quorum_schema.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Dependency-free, deterministic validation for the shipped controller config."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+REQUIRED = {
+    "project_key",
+    "contract_commit",
+    "database_path",
+    "file_inbox_path",
+    "health_receipts",
+    "blocker_retry_threshold",
+    "max_health_age_seconds",
+    "lease_ttl_seconds",
+    "gateway_event_url",
+    "gateway_token_file",
+}
+OPTIONAL = {"$schema", "default_workload", "git_ref_polling"}
+WORKLOADS = {
+    "large_repetitive_infrastructure_monitoring",
+    "complex_code_security_architecture",
+}
+
+
+def fail(message: str) -> None:
+    raise ValueError(message)
+
+
+def absolute_path(value: object, name: str) -> None:
+    if not isinstance(value, str) or not value.startswith("/") or "\x00" in value:
+        fail(f"{name} must be an absolute POSIX path")
+
+
+def bounded_integer(value: object, name: str, minimum: int, maximum: int) -> None:
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        fail(f"{name} must be an integer in [{minimum}, {maximum}]")
+
+
+def validate(config: object, schema: object) -> None:
+    if not isinstance(config, dict) or not isinstance(schema, dict):
+        fail("config and schema must be JSON objects")
+    if schema.get("$schema") != "https://json-schema.org/draft/2020-12/schema":
+        fail("unexpected JSON Schema dialect")
+    if schema.get("additionalProperties") is not False:
+        fail("schema must reject additional properties")
+    if set(schema.get("required", [])) != REQUIRED:
+        fail("schema required fields drifted from validator")
+    keys = set(config)
+    if not REQUIRED <= keys or keys - REQUIRED - OPTIONAL:
+        fail("missing or unexpected top-level config fields")
+    absolute_path(config["database_path"], "database_path")
+    absolute_path(config["file_inbox_path"], "file_inbox_path")
+    absolute_path(config["gateway_token_file"], "gateway_token_file")
+    project_key = config["project_key"]
+    if not isinstance(project_key, str) or not project_key or len(project_key) > 128:
+        fail("project_key is invalid")
+    commit = config["contract_commit"]
+    if not isinstance(commit, str) or len(commit) != 40 or any(c not in "0123456789abcdef" for c in commit):
+        fail("contract_commit must be a full lowercase Git OID")
+    receipts = config["health_receipts"]
+    if not isinstance(receipts, dict) or set(receipts) != {"central_gpt", "openclaw", "codex"}:
+        fail("health_receipts must contain exactly central_gpt, openclaw, and codex")
+    for subject, value in receipts.items():
+        absolute_path(value, f"health_receipts.{subject}")
+    git_polling = config.get("git_ref_polling")
+    if git_polling is not None:
+        if not isinstance(git_polling, dict) or set(git_polling) != {"repository", "refs"}:
+            fail("git_ref_polling must contain exactly repository and refs")
+        absolute_path(git_polling["repository"], "git_ref_polling.repository")
+        refs = git_polling["refs"]
+        if not isinstance(refs, list) or not refs or len(refs) != len(set(refs)):
+            fail("git_ref_polling.refs must be a non-empty unique list")
+        if any(not isinstance(ref, str) or not ref.startswith("refs/") or ".." in ref for ref in refs):
+            fail("git_ref_polling.refs contains an invalid ref")
+    if config.get("default_workload", "large_repetitive_infrastructure_monitoring") not in WORKLOADS:
+        fail("unsupported default_workload")
+    bounded_integer(config["blocker_retry_threshold"], "blocker_retry_threshold", 1, 20)
+    bounded_integer(config["max_health_age_seconds"], "max_health_age_seconds", 5, 300)
+    bounded_integer(config["lease_ttl_seconds"], "lease_ttl_seconds", 15, 3600)
+    url = config["gateway_event_url"]
+    parsed = urlparse(url) if isinstance(url, str) else None
+    if (
+        not parsed
+        or parsed.scheme != "http"
+        or parsed.hostname != "127.0.0.1"
+        or parsed.port != 18920
+        or parsed.path != "/v1/orchestrator/events"
+        or parsed.query
+        or parsed.fragment
+    ):
+        fail("gateway_event_url must be the fixed loopback orchestrator endpoint")
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print(f"usage: {Path(sys.argv[0]).name} CONFIG SCHEMA", file=sys.stderr)
+        return 2
+    with Path(sys.argv[1]).open("r", encoding="utf-8") as handle:
+        config = json.load(handle)
+    with Path(sys.argv[2]).open("r", encoding="utf-8") as handle:
+        schema = json.load(handle)
+    try:
+        validate(config, schema)
+    except ValueError as error:
+        print(f"schema validation failed: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/verify_aios_orchestrator_gateway.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+CONFIG="${1:-/etc/aios-orchestrator-gateway/config.json}"
+PORT="${PORT:-18920}"
+
+python3 -m json.tool "$CONFIG" >/dev/null
+systemd-analyze verify \
+  /etc/systemd/system/aios-orchestrator-gateway.service \
+  /etc/systemd/system/aios-orchestrator-gateway-poll.service \
+  /etc/systemd/system/aios-orchestrator-gateway-poll.timer
+systemctl is-active --quiet aios-orchestrator-gateway.service
+systemctl is-active --quiet aios-orchestrator-gateway-poll.timer
+
+health="$(curl --fail --silent --show-error "http://127.0.0.1:${PORT}/healthz")"
+python3 -c '
+import json, sys
+v=json.load(sys.stdin)
+assert v["service"]=="aios-orchestrator-gateway"
+assert v["status"]=="active"
+assert v["polling"] is True
+assert len(v["contract_commit"])==40
+' <<<"$health"
+
+systemctl start aios-orchestrator-gateway-poll.service
+if journalctl -u aios-orchestrator-gateway.service -n 200 --no-pager \
+  | grep -Eqi 'Bearer |token=|api[_-]?key|secret='; then
+  echo "AIOS_ORCHESTRATOR_VERIFY=BLOCKED reason=SECRET_PATTERN_IN_LOG" >&2
+  exit 2
+fi
+
+echo "AIOS_ORCHESTRATOR_VERIFY=PASS"

scripts/verify_automation_quorum_controller.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}
+
+python3 -m py_compile "${ROOT}/automation/executor_quorum_controller.py"
+python3 -m py_compile \
+  "${ROOT}/automation/health_probe_common.py" \
+  "${ROOT}/automation/central_gpt_health_probe.py" \
+  "${ROOT}/automation/codex_executor_health_probe.py" \
+  "${ROOT}/automation/a0_unattended_loop_probe.py"
+python3 -m unittest discover -s "${ROOT}/tests" -p 'test_executor_quorum_controller.py' -v
+python3 -m unittest discover -s "${ROOT}/tests" -p 'test_aios_health_probes.py' -v
+python3 -m json.tool "${ROOT}/config/aios-automation-quorum-controller.example.json" >/dev/null
+python3 -m json.tool "${ROOT}/schemas/automation-quorum-controller.schema.json" >/dev/null
+python3 "${ROOT}/scripts/validate_automation_quorum_schema.py" \
+  "${ROOT}/config/aios-automation-quorum-controller.example.json" \
+  "${ROOT}/schemas/automation-quorum-controller.schema.json"
+python3 -m py_compile "${ROOT}/scripts/validate_automation_quorum_schema.py"
+bash -n "${ROOT}/scripts/install_automation_quorum_controller.sh"
+bash -n "${ROOT}/scripts/rollback_automation_quorum_controller.sh"
+bash -n "${ROOT}/scripts/verify_automation_quorum_controller.sh"
+systemd-analyze verify \
+  "${ROOT}/systemd/aios-automation-quorum-controller.service" \
+  "${ROOT}/systemd/aios-automation-quorum-controller.timer" \
+  "${ROOT}/systemd/aios-central-gpt-health-probe.service" \
+  "${ROOT}/systemd/aios-central-gpt-health-probe.timer" \
+  "${ROOT}/systemd/aios-codex-executor-health-probe.service" \
+  "${ROOT}/systemd/aios-codex-executor-health-probe.timer"

scripts/wechat_send_backend.py

@@ -0,0 +1,652 @@
+#!/usr/bin/env python3
+"""Hardened WeChat outbound backend for AIOS.
+
+Only the dedicated UCC adapter is a supported send backend.  OpenClaw channel
+discovery is retained for diagnostics, but generic OpenClaw chat or agent
+delivery is never promoted to WeChat delivery.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import selectors
+import signal
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, Tuple
+
+
+OPENCLAW_BIN = os.environ.get("AIOS_OPENCLAW_BIN", "openclaw")
+WECHAT_ACCOUNT_ID = os.environ.get("AIOS_WECHAT_ACCOUNT_ID", "")
+WECHAT_CHANNEL = os.environ.get("AIOS_WECHAT_CHANNEL", "")
+SEND_BACKEND = os.environ.get("AIOS_WECHAT_SEND_BACKEND", "")
+UCC_ADAPTER_URL = os.environ.get("AIOS_UCC_WECHAT_ADAPTER_URL", "http://127.0.0.1:18800")
+UCC_ADAPTER_TOKEN = os.environ.get("AIOS_UCC_WECHAT_ADAPTER_TOKEN") or os.environ.get(
+    "AIOS_WECHAT_QR_ADAPTER_TOKEN", ""
+)
+UCC_SEND_PATH = os.environ.get("AIOS_UCC_WECHAT_SEND_PATH", "/api/internal/wechat/send")
+_allowed_origins = os.environ.get("AIOS_UCC_WECHAT_ALLOWED_ORIGINS", "").strip()
+UCC_ADAPTER_ALLOWED_ORIGINS = tuple(
+    origin.strip() for origin in _allowed_origins.split(",") if origin.strip()
+) or (
+    "http://127.0.0.1:18800",
+    "http://[::1]:18800",
+)
+
+MAX_TARGET_BYTES = 512
+MAX_CONTENT_BYTES = 32 * 1024
+MAX_IDENTIFIER_BYTES = 512
+MAX_METADATA_BYTES = 8 * 1024
+MAX_METADATA_DEPTH = 32
+MAX_METADATA_NODES = 1024
+MAX_RESPONSE_BYTES = 64 * 1024
+MAX_ENDPOINT_BYTES = 256
+_DEFAULT_TIMEOUT_SECONDS = 10
+_MAX_TIMEOUT_SECONDS = 30
+_LEGACY_SEND_PATH = "/internal/channels/wechat/send"
+_SAFE_PATH = re.compile(r"^/[A-Za-z0-9._~!$&'()*+,;=:@%/-]+$")
+_MAX_PATH_DECODE_ROUNDS = 4
+_OPENCLAW_TIMEOUT_RETURN_CODE = 124
+_OPENCLAW_OUTPUT_LIMIT_RETURN_CODE = 125
+_OPENCLAW_SPAWN_ERROR_RETURN_CODE = 126
+
+
+def _bounded_timeout(value: str) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return _DEFAULT_TIMEOUT_SECONDS
+    return min(max(parsed, 1), _MAX_TIMEOUT_SECONDS)
+
+
+REQUEST_TIMEOUT_SECONDS = _bounded_timeout(os.environ.get("AIOS_UCC_WECHAT_TIMEOUT_SECONDS", "10"))
+
+
+class BackendResult:
+    def __init__(self, ok: bool, backend: str, status: str, data: Dict[str, Any]) -> None:
+        self.ok = ok
+        self.backend = backend
+        self.status = status
+        self.data = data
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"ok": self.ok, "backend": self.backend, "status": self.status, **self.data}
+
+
+class _BackendProtocolError(Exception):
+    """Internal marker whose details must never cross the module boundary."""
+
+
+def _openclaw_base_args() -> List[str]:
+    """Return the OpenClaw 2026.6.11-compatible command prefix.
+
+    Gateway/auth global flags are not supported by the installed CLI and would
+    also expose credentials through the process argument vector.
+    """
+
+    return [OPENCLAW_BIN]
+
+
+def _terminate_process_tree(process: Any) -> None:
+    if os.name == "posix":
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+        except OSError:
+            pass
+        try:
+            process.wait(timeout=0.5)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        time.sleep(0.05)
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except OSError:
+            pass
+        try:
+            process.wait(timeout=0.5)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        return
+    if process.poll() is not None:
+        return
+    try:
+        process.terminate()
+        process.wait(timeout=1)
+        return
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    try:
+        process.kill()
+        process.wait(timeout=1)
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def _run_openclaw(
+    args: List[str], timeout: int = 15
+) -> subprocess.CompletedProcess[str]:
+    bounded_timeout = min(max(int(timeout), 1), _MAX_TIMEOUT_SECONDS)
+    popen_options: Dict[str, Any] = {
+        "stdout": subprocess.PIPE,
+        "stderr": subprocess.PIPE,
+    }
+    if os.name == "posix":
+        popen_options["start_new_session"] = True
+    elif hasattr(subprocess, "CREATE_NEW_PROCESS_GROUP"):
+        popen_options["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    try:
+        process = subprocess.Popen(args, **popen_options)
+    except (OSError, ValueError):
+        return subprocess.CompletedProcess(args, _OPENCLAW_SPAWN_ERROR_RETURN_CODE, "", "")
+
+    selector = selectors.DefaultSelector()
+    streams = {"stdout": process.stdout, "stderr": process.stderr}
+    buffers = {"stdout": bytearray(), "stderr": bytearray()}
+    try:
+        for name, stream in streams.items():
+            if stream is not None:
+                selector.register(stream, selectors.EVENT_READ, name)
+    except (OSError, ValueError):
+        selector.close()
+        _terminate_process_tree(process)
+        for stream in streams.values():
+            if stream is not None:
+                stream.close()
+        return subprocess.CompletedProcess(args, _OPENCLAW_SPAWN_ERROR_RETURN_CODE, "", "")
+
+    deadline = time.monotonic() + bounded_timeout
+    total_bytes = 0
+    return_code: Optional[int] = None
+    try:
+        while selector.get_map():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return_code = _OPENCLAW_TIMEOUT_RETURN_CODE
+                break
+            events = selector.select(min(remaining, 0.1))
+            for key, _mask in events:
+                allowance = MAX_RESPONSE_BYTES - total_bytes
+                try:
+                    chunk = os.read(key.fileobj.fileno(), min(8192, allowance + 1))
+                except OSError:
+                    return_code = _OPENCLAW_SPAWN_ERROR_RETURN_CODE
+                    break
+                if not chunk:
+                    selector.unregister(key.fileobj)
+                    key.fileobj.close()
+                    continue
+                if len(chunk) > allowance:
+                    return_code = _OPENCLAW_OUTPUT_LIMIT_RETURN_CODE
+                    break
+                buffers[key.data].extend(chunk)
+                total_bytes += len(chunk)
+            if return_code is not None:
+                break
+    finally:
+        selector.close()
+
+    if return_code is not None:
+        _terminate_process_tree(process)
+        for stream in streams.values():
+            if stream is not None and not stream.closed:
+                stream.close()
+        return subprocess.CompletedProcess(args, return_code, "", "")
+    try:
+        completed_return_code = process.wait(timeout=1)
+    except subprocess.TimeoutExpired:
+        _terminate_process_tree(process)
+        return subprocess.CompletedProcess(args, _OPENCLAW_TIMEOUT_RETURN_CODE, "", "")
+    stdout = buffers["stdout"].decode("utf-8", errors="replace")
+    stderr = buffers["stderr"].decode("utf-8", errors="replace")
+    return subprocess.CompletedProcess(args, completed_return_code, stdout, stderr)
+
+
+def _json_dict(text: str) -> Dict[str, Any]:
+    try:
+        value = json.loads(text or "{}")
+    except (RecursionError, TypeError, ValueError, json.JSONDecodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def discover_openclaw_wechat_channel() -> Optional[str]:
+    """Discover an explicitly typed WeChat/Weixin channel for diagnostics."""
+
+    if WECHAT_CHANNEL:
+        return WECHAT_CHANNEL
+    try:
+        proc = _run_openclaw(_openclaw_base_args() + ["channels", "list", "--json"], timeout=15)
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return None
+    if proc.returncode != 0:
+        return None
+    data = _json_dict(proc.stdout[:MAX_RESPONSE_BYTES])
+    candidates: List[str] = []
+
+    def walk(value: Any) -> None:
+        if isinstance(value, dict):
+            name = value.get("name") or value.get("channel") or value.get("id")
+            kind = value.get("type") or value.get("kind")
+            if isinstance(name, str) and isinstance(kind, str):
+                label = f"{name} {kind}".lower()
+                if "wechat" in label or "weixin" in label:
+                    candidates.append(name)
+            for child in value.values():
+                walk(child)
+        elif isinstance(value, list):
+            for child in value:
+                walk(child)
+
+    walk(data)
+    return candidates[0] if candidates else None
+
+
+def _auth_headers() -> Dict[str, str]:
+    headers = {"Content-Type": "application/json", "Accept": "application/json"}
+    if UCC_ADAPTER_TOKEN:
+        headers["Authorization"] = "Bearer " + UCC_ADAPTER_TOKEN
+    return headers
+
+
+def _safe_path(value: Any) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    path = value if value.startswith("/") else "/" + value
+    try:
+        encoded_path = path.encode("utf-8")
+    except UnicodeEncodeError:
+        return None
+    if len(encoded_path) > MAX_ENDPOINT_BYTES:
+        return None
+    if not _SAFE_PATH.fullmatch(path):
+        return None
+    decoded = path
+    for _ in range(_MAX_PATH_DECODE_ROUNDS):
+        try:
+            next_decoded = urllib.parse.unquote_to_bytes(decoded).decode("utf-8")
+        except UnicodeDecodeError:
+            return None
+        if next_decoded == decoded:
+            break
+        decoded = next_decoded
+    if "%" in decoded or "\\" in decoded or "\x00" in decoded:
+        return None
+    if not _SAFE_PATH.fullmatch(decoded):
+        return None
+    if any(segment in {".", ".."} for segment in decoded.split("/")):
+        return None
+    return path
+
+
+def _unique_paths(paths: List[str]) -> List[str]:
+    out: List[str] = []
+    for candidate in paths:
+        path = _safe_path(candidate)
+        if path and path not in out:
+            out.append(path)
+        if len(out) == 2:
+            break
+    return out
+
+
+def _ucc_send_paths() -> List[str]:
+    canonical = _safe_path(UCC_SEND_PATH) or "/api/internal/wechat/send"
+    return _unique_paths([canonical, _LEGACY_SEND_PATH])
+
+
+def _canonical_origin(value: Any) -> Optional[str]:
+    if not isinstance(value, str) or not value or len(value) > 2048:
+        return None
+    if "\\" in value or any(ord(character) < 32 for character in value):
+        return None
+    try:
+        parsed = urllib.parse.urlsplit(value)
+        port = parsed.port
+    except (UnicodeError, ValueError):
+        return None
+    scheme = parsed.scheme.lower()
+    if scheme not in {"http", "https"} or not parsed.hostname:
+        return None
+    if parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in {"", "/"}:
+        return None
+    try:
+        host = parsed.hostname.rstrip(".").encode("idna").decode("ascii").lower()
+    except UnicodeError:
+        return None
+    if not host:
+        return None
+    if port is None:
+        port = 80 if scheme == "http" else 443
+    rendered_host = f"[{host}]" if ":" in host else host
+    return f"{scheme}://{rendered_host}:{port}"
+
+
+def _adapter_base_url() -> Optional[str]:
+    origin = _canonical_origin(UCC_ADAPTER_URL)
+    allowed = {
+        canonical
+        for canonical in (_canonical_origin(value) for value in UCC_ADAPTER_ALLOWED_ORIGINS)
+        if canonical
+    }
+    return origin if origin and origin in allowed else None
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        req: Any,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> None:
+        del req, fp, code, msg, headers, newurl
+        return None
+
+
+def _open_no_redirect(request: urllib.request.Request, timeout: int) -> Any:
+    opener = urllib.request.build_opener(_NoRedirectHandler())
+    return opener.open(request, timeout=timeout)
+
+
+def ucc_adapter_alive() -> bool:
+    base_url = _adapter_base_url()
+    if not base_url:
+        return False
+    request = urllib.request.Request(
+        base_url + "/health", headers=_auth_headers(), method="GET"
+    )
+    try:
+        with _open_no_redirect(request, timeout=min(5, REQUEST_TIMEOUT_SECONDS)) as response:
+            return 200 <= int(response.status) < 300
+    except (OSError, ValueError, urllib.error.URLError):
+        return False
+
+
+def select_backend() -> Dict[str, Any]:
+    explicit = SEND_BACKEND.strip().lower()
+    if explicit:
+        if explicit == "ucc-adapter":
+            return {"backend": "ucc-adapter", "reason": "explicit"}
+        return {"backend": "unavailable", "reason": "unsupported_backend"}
+    if ucc_adapter_alive():
+        return {"backend": "ucc-adapter", "reason": "ucc_adapter_alive"}
+    return {"backend": "unavailable", "reason": "ucc_adapter_unavailable"}
+
+
+def _post_ucc(path: str, payload: Dict[str, Any]) -> Tuple[int, Dict[str, Any]]:
+    base_url = _adapter_base_url()
+    safe_path = _safe_path(path)
+    if not base_url or not safe_path:
+        raise _BackendProtocolError("invalid adapter endpoint")
+    try:
+        body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise _BackendProtocolError("invalid request payload") from exc
+    request = urllib.request.Request(
+        base_url + safe_path,
+        data=body,
+        headers=_auth_headers(),
+        method="POST",
+    )
+    with _open_no_redirect(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:
+        raw = response.read(MAX_RESPONSE_BYTES + 1)
+        if len(raw) > MAX_RESPONSE_BYTES:
+            raise _BackendProtocolError("adapter response too large")
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise _BackendProtocolError("adapter response encoding invalid") from exc
+        data = _json_dict(text)
+        if not data:
+            raise _BackendProtocolError("adapter response invalid")
+        return int(response.status), data
+
+
+def _ucc_response_sent(data: Dict[str, Any]) -> bool:
+    return isinstance(data, dict) and data.get("ok") is True and data.get("status") == "sent"
+
+
+def _ucc_result_is_ok(data: Dict[str, Any], dry_run: bool = False) -> bool:
+    expected_status = "dry_run" if dry_run else "sent"
+    return isinstance(data, dict) and data.get("ok") is True and data.get("status") == expected_status
+
+
+def _utf8_size(value: str) -> Optional[int]:
+    try:
+        return len(value.encode("utf-8"))
+    except UnicodeEncodeError:
+        return None
+
+
+def _valid_identifier(value: Any, required: bool = False) -> bool:
+    if not isinstance(value, str):
+        return False
+    if required and not value.strip():
+        return False
+    if not value:
+        return not required
+    if len(value) > MAX_IDENTIFIER_BYTES:
+        return False
+    size = _utf8_size(value)
+    return size is not None and size <= MAX_IDENTIFIER_BYTES and not any(
+        ord(character) < 32 or ord(character) == 127 for character in value
+    )
+
+
+def _validate_metadata(metadata: Any) -> Optional[str]:
+    if not isinstance(metadata, dict):
+        return "invalid_input"
+    nodes = 0
+    stack: List[Tuple[Any, int]] = [(metadata, 0)]
+    while stack:
+        value, depth = stack.pop()
+        nodes += 1
+        if depth > MAX_METADATA_DEPTH or nodes > MAX_METADATA_NODES:
+            return "input_too_large"
+        if isinstance(value, dict):
+            if len(value) + nodes + len(stack) > MAX_METADATA_NODES:
+                return "input_too_large"
+            for key, child in value.items():
+                if (
+                    not isinstance(key, str)
+                    or len(key) > MAX_METADATA_BYTES
+                    or _utf8_size(key) is None
+                ):
+                    return "invalid_input"
+                stack.append((child, depth + 1))
+        elif isinstance(value, list):
+            if len(value) + nodes + len(stack) > MAX_METADATA_NODES:
+                return "input_too_large"
+            stack.extend((child, depth + 1) for child in value)
+        elif isinstance(value, str):
+            if len(value) > MAX_METADATA_BYTES:
+                return "input_too_large"
+            if _utf8_size(value) is None:
+                return "invalid_input"
+        elif value is not None and not isinstance(value, (bool, int, float)):
+            return "invalid_input"
+    try:
+        encoded = json.dumps(
+            metadata,
+            ensure_ascii=False,
+            allow_nan=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+    except (RecursionError, TypeError, UnicodeEncodeError, ValueError):
+        return "invalid_input"
+    return "input_too_large" if len(encoded) > MAX_METADATA_BYTES else None
+
+
+def _validate_payload(
+    target: Any,
+    content: Any,
+    account_id: Any,
+    message_id: Any,
+    metadata: Any,
+    dry_run: Any,
+) -> Optional[str]:
+    if not isinstance(target, str) or not isinstance(content, str):
+        return "invalid_input"
+    if not target.strip() or not content.strip() or not isinstance(dry_run, bool):
+        return "invalid_input"
+    if any(ord(character) < 32 or ord(character) == 127 for character in target):
+        return "invalid_input"
+    if "\x00" in content or not _valid_identifier(account_id) or not _valid_identifier(message_id):
+        return "invalid_input"
+    if len(target) > MAX_TARGET_BYTES or len(content) > MAX_CONTENT_BYTES:
+        return "input_too_large"
+    target_size = _utf8_size(target)
+    content_size = _utf8_size(content)
+    if target_size is None or content_size is None:
+        return "invalid_input"
+    if target_size > MAX_TARGET_BYTES or content_size > MAX_CONTENT_BYTES:
+        return "input_too_large"
+    return _validate_metadata(metadata)
+
+
+def _safe_provider_message_id(value: Any) -> Optional[str]:
+    if not isinstance(value, str) or not value:
+        return None
+    if len(value) > MAX_IDENTIFIER_BYTES:
+        return None
+    size = _utf8_size(value)
+    if size is None or size > MAX_IDENTIFIER_BYTES:
+        return None
+    if any(ord(character) < 32 or ord(character) == 127 for character in value):
+        return None
+    return value
+
+
+def send_ucc_adapter(
+    target: str,
+    content: str,
+    account_id: str = "",
+    message_id: str = "",
+    metadata: Optional[Dict[str, Any]] = None,
+    dry_run: bool = False,
+) -> BackendResult:
+    effective_account = account_id or WECHAT_ACCOUNT_ID
+    effective_metadata: Any = {} if metadata is None else metadata
+    error_code = _validate_payload(
+        target,
+        content,
+        effective_account,
+        message_id,
+        effective_metadata,
+        dry_run,
+    )
+    if error_code:
+        return BackendResult(False, "ucc-adapter", "failed", {"code": error_code})
+
+    payload = {
+        "target": target,
+        "content": content,
+        "account_id": effective_account,
+        "message_id": message_id,
+        "metadata": effective_metadata,
+        "dry_run": dry_run,
+    }
+    last_endpoint: Optional[str] = None
+    for path in _ucc_send_paths():
+        last_endpoint = path
+        try:
+            http_status, data = _post_ucc(path, payload)
+        except urllib.error.HTTPError as exc:
+            if exc.code in {404, 405}:
+                continue
+            return BackendResult(
+                False,
+                "ucc-adapter",
+                "failed",
+                {"code": "ucc_adapter_http_error", "http_status": int(exc.code), "endpoint": path},
+            )
+        except (OSError, ValueError, urllib.error.URLError, _BackendProtocolError):
+            return BackendResult(
+                False,
+                "ucc-adapter",
+                "failed",
+                {"code": "ucc_adapter_unavailable", "endpoint": path},
+            )
+        except Exception:
+            # Fail closed without returning exception text, type, or chained cause.
+            return BackendResult(
+                False,
+                "ucc-adapter",
+                "failed",
+                {"code": "ucc_adapter_unavailable", "endpoint": path},
+            )
+
+        if not (200 <= http_status < 300):
+            return BackendResult(
+                False,
+                "ucc-adapter",
+                "failed",
+                {"code": "ucc_adapter_http_error", "http_status": http_status, "endpoint": path},
+            )
+        if not _ucc_result_is_ok(data, dry_run):
+            return BackendResult(
+                False,
+                "ucc-adapter",
+                "failed",
+                {"code": "ucc_adapter_rejected", "http_status": http_status, "endpoint": path},
+            )
+        confirmed_status = "dry_run" if dry_run else "sent"
+        result_data: Dict[str, Any] = {
+            "code": confirmed_status,
+            "http_status": http_status,
+            "endpoint": path,
+        }
+        provider_message_id = _safe_provider_message_id(data.get("provider_message_id"))
+        if provider_message_id:
+            result_data["provider_message_id"] = provider_message_id
+        return BackendResult(True, "ucc-adapter", confirmed_status, result_data)
+
+    data: Dict[str, Any] = {"code": "ucc_adapter_unavailable"}
+    if last_endpoint:
+        data["endpoint"] = last_endpoint
+    return BackendResult(False, "ucc-adapter", "failed", data)
+
+
+def send_openclaw_channel(
+    target: str,
+    content: str,
+    account_id: str = "",
+    message_id: str = "",
+    metadata: Optional[Dict[str, Any]] = None,
+    dry_run: bool = False,
+) -> BackendResult:
+    del target, content, account_id, message_id, metadata, dry_run
+    return BackendResult(
+        False,
+        "openclaw-channel",
+        "failed",
+        {"code": "unsupported_backend"},
+    )
+
+
+def send_message(
+    target: str,
+    content: str,
+    account_id: str = "",
+    message_id: str = "",
+    metadata: Optional[Dict[str, Any]] = None,
+    dry_run: bool = False,
+) -> Dict[str, Any]:
+    selected = select_backend()
+    if selected.get("backend") == "ucc-adapter":
+        return send_ucc_adapter(
+            target, content, account_id, message_id, metadata, dry_run
+        ).to_dict()
+    code = "unsupported_backend" if selected.get("reason") == "unsupported_backend" else "wechat_outbound_backend_unavailable"
+    return BackendResult(False, "unavailable", "failed", {"code": code}).to_dict()
+
+
+if __name__ == "__main__":
+    print(json.dumps(select_backend(), ensure_ascii=False, separators=(",", ":")))

services/__init__.py

@@ -0,0 +1 @@
+"""AIOS services namespace."""

services/aios_codex_watcher/__init__.py

@@ -0,0 +1,5 @@
+"""Reliable, fail-closed Codex command watcher."""
+
+from .watcher import CommandWatcher, Config, load_config
+
+__all__ = ["CommandWatcher", "Config", "load_config"]

services/aios_codex_watcher/__main__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .watcher import CommandWatcher, load_config
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Claim and execute Codex work units")
+    parser.add_argument("--config", required=True)
+    parser.add_argument("--once", action="store_true", help="process one scan and exit")
+    args = parser.parse_args()
+    watcher = CommandWatcher(load_config(args.config))
+    return watcher.run_once() if args.once else watcher.run_forever()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

services/aios_codex_watcher/watcher.py

@@ -0,0 +1,501 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from contextlib import contextmanager
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import sqlite3
+import stat
+import subprocess
+import time
+import threading
+from typing import Any, Callable
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+
+OID_RE = re.compile(r"^[0-9a-f]{40}$")
+ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+TERMINAL = {"COMPLETED", "DEAD_LETTER", "REJECTED"}
+CODEX_AUTH_LOCK = Path("/run/lock/aios-codex-auth.lock")
+_CODEX_EXECUTION_LOCK = threading.Lock()
+
+
+class WatcherError(RuntimeError):
+    pass
+
+
+@contextmanager
+def _codex_auth_lock():
+    with _CODEX_EXECUTION_LOCK:
+        fd = os.open(CODEX_AUTH_LOCK, os.O_RDWR | getattr(os, "O_NOFOLLOW", 0))
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or stat.S_IMODE(info.st_mode) & ~0o660:
+                raise WatcherError("unsafe_codex_auth_lock")
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            yield
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+            os.close(fd)
+
+
+@dataclass(frozen=True)
+class Config:
+    active_dir: Path
+    completed_dir: Path
+    dead_letter_dir: Path
+    database_path: Path
+    audit_log_path: Path
+    gateway_endpoint: str
+    gateway_token_file: Path
+    contract_commit: str
+    lease_seconds: int
+    retry_seconds: int
+    max_attempts: int
+    poll_seconds: float
+    executor_path: Path | None
+    executor_args: tuple[str, ...]
+    executor_timeout_seconds: int
+
+
+def _absolute(value: Any, key: str) -> Path:
+    if not isinstance(value, str) or not value or not Path(value).is_absolute():
+        raise WatcherError(f"invalid_{key}")
+    return Path(value)
+
+
+def _secure_regular(path: Path, *, writable_mask: int = 0o022) -> os.stat_result:
+    info = os.lstat(path)
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        raise WatcherError(f"unsafe_file:{path}")
+    if stat.S_IMODE(info.st_mode) & writable_mask:
+        raise WatcherError(f"unsafe_mode:{path}")
+    return info
+
+
+def _read_secure_text(
+    path: Path,
+    *,
+    writable_mask: int = 0o022,
+    max_bytes: int,
+    allowed_owners: set[int] | None = None,
+) -> str:
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(path, flags)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or stat.S_IMODE(info.st_mode) & writable_mask:
+            raise WatcherError(f"unsafe_file:{path}")
+        if allowed_owners is not None and info.st_uid not in allowed_owners:
+            raise WatcherError(f"owner_mismatch:{path}")
+        if info.st_size > max_bytes:
+            raise WatcherError(f"file_too_large:{path}")
+        chunks: list[bytes] = []
+        total = 0
+        while True:
+            chunk = os.read(fd, min(65_536, max_bytes + 1 - total))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            total += len(chunk)
+            if total > max_bytes:
+                raise WatcherError(f"file_too_large:{path}")
+        return b"".join(chunks).decode("utf-8")
+    finally:
+        os.close(fd)
+
+
+def load_config(path_value: str) -> Config:
+    path = _absolute(path_value, "config_path")
+    raw = json.loads(_read_secure_text(path, max_bytes=131_072, allowed_owners={0, os.geteuid()}))
+    expected = {
+        "active_dir", "completed_dir", "dead_letter_dir", "database_path",
+        "audit_log_path", "gateway_endpoint", "gateway_token_file",
+        "contract_commit", "lease_seconds", "retry_seconds", "max_attempts",
+        "poll_seconds", "executor_path", "executor_args",
+        "executor_timeout_seconds",
+    }
+    if not isinstance(raw, dict) or set(raw) != expected:
+        raise WatcherError("invalid_config_fields")
+    contract = raw["contract_commit"]
+    if not isinstance(contract, str) or not OID_RE.fullmatch(contract):
+        raise WatcherError("invalid_contract_commit")
+    endpoint = raw["gateway_endpoint"]
+    if not isinstance(endpoint, str) or not endpoint.startswith("http://127.0.0.1:") or not endpoint.endswith("/v1/orchestrator/events"):
+        raise WatcherError("gateway_endpoint_must_be_loopback")
+    executor_raw = raw["executor_path"]
+    executor = None if executor_raw is None else _absolute(executor_raw, "executor_path")
+    executor_args = raw["executor_args"]
+    if not isinstance(executor_args, list) or any(not isinstance(x, str) or not x for x in executor_args):
+        raise WatcherError("invalid_executor_args")
+    ints = ("lease_seconds", "retry_seconds", "max_attempts", "executor_timeout_seconds")
+    if any(not isinstance(raw[x], int) or raw[x] <= 0 for x in ints):
+        raise WatcherError("invalid_positive_integer")
+    if not isinstance(raw["poll_seconds"], (int, float)) or raw["poll_seconds"] <= 0:
+        raise WatcherError("invalid_poll_seconds")
+    return Config(
+        active_dir=_absolute(raw["active_dir"], "active_dir"),
+        completed_dir=_absolute(raw["completed_dir"], "completed_dir"),
+        dead_letter_dir=_absolute(raw["dead_letter_dir"], "dead_letter_dir"),
+        database_path=_absolute(raw["database_path"], "database_path"),
+        audit_log_path=_absolute(raw["audit_log_path"], "audit_log_path"),
+        gateway_endpoint=endpoint,
+        gateway_token_file=_absolute(raw["gateway_token_file"], "gateway_token_file"),
+        contract_commit=contract,
+        lease_seconds=raw["lease_seconds"], retry_seconds=raw["retry_seconds"],
+        max_attempts=raw["max_attempts"], poll_seconds=float(raw["poll_seconds"]),
+        executor_path=executor, executor_args=tuple(executor_args),
+        executor_timeout_seconds=raw["executor_timeout_seconds"],
+    )
+
+
+def canonical_digest(value: dict[str, Any]) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def validate_command(value: Any, expected_contract: str) -> dict[str, Any]:
+    expected = {
+        "schema_version", "command_id", "project_key", "work_unit_id",
+        "contract_commit", "state_version", "execution",
+    }
+    if not isinstance(value, dict) or set(value) != expected or value.get("schema_version") != 1:
+        raise WatcherError("invalid_command_fields")
+    for key in ("command_id", "project_key", "work_unit_id"):
+        if not isinstance(value[key], str) or not ID_RE.fullmatch(value[key]):
+            raise WatcherError(f"invalid_{key}")
+    if value["contract_commit"] != expected_contract:
+        raise WatcherError("contract_commit_mismatch")
+    if not isinstance(value["state_version"], int) or value["state_version"] < 0:
+        raise WatcherError("invalid_state_version")
+    execution = value["execution"]
+    if not isinstance(execution, dict) or set(execution) != {"kind", "input"}:
+        raise WatcherError("invalid_execution")
+    if execution["kind"] not in {"acceptance_probe", "codex"}:
+        raise WatcherError("invalid_execution_kind")
+    if not isinstance(execution["input"], str) or len(execution["input"].encode()) > 65_536:
+        raise WatcherError("invalid_execution_input")
+    return value
+
+
+class CommandWatcher:
+    def __init__(
+        self,
+        config: Config,
+        *,
+        clock: Callable[[], float] = time.time,
+        event_poster: Callable[[dict[str, Any]], None] | None = None,
+        executor: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+        worker_id: str | None = None,
+    ) -> None:
+        self.config = config
+        self.clock = clock
+        self.worker_id = worker_id or f"{os.uname().nodename}:{os.getpid()}:{uuid.uuid4().hex[:8]}"
+        self._uses_gateway = event_poster is None
+        self.event_poster = event_poster or self._post_event
+        self.executor = executor or self._execute
+        self._prepare()
+
+    def _prepare(self) -> None:
+        for directory in (self.config.active_dir, self.config.completed_dir, self.config.dead_letter_dir):
+            info = os.lstat(directory)
+            if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) & 0o002:
+                raise WatcherError(f"unsafe_directory:{directory}")
+        self.config.database_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.config.audit_log_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        with self._db() as db:
+            db.execute("PRAGMA journal_mode=WAL")
+            db.execute("""
+                CREATE TABLE IF NOT EXISTS commands (
+                    command_id TEXT PRIMARY KEY, work_unit_id TEXT NOT NULL UNIQUE,
+                    payload_sha256 TEXT NOT NULL,
+                    source_path TEXT NOT NULL, status TEXT NOT NULL,
+                    phase TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
+                    lease_owner TEXT, lease_until REAL, next_attempt REAL NOT NULL DEFAULT 0,
+                    result_json TEXT, start_event_json TEXT, end_event_json TEXT,
+                    last_error TEXT, updated_at REAL NOT NULL
+                )
+            """)
+
+    def _db(self) -> sqlite3.Connection:
+        db = sqlite3.connect(self.config.database_path, timeout=5, isolation_level=None)
+        db.row_factory = sqlite3.Row
+        return db
+
+    def _audit(self, marker: str, command_id: str, **fields: Any) -> None:
+        safe = {k: v for k, v in fields.items() if k not in {"input", "token", "secret"}}
+        record = {"time": int(self.clock()), "marker": marker, "command_id": command_id, **safe}
+        fd = os.open(self.config.audit_log_path, os.O_APPEND | os.O_CREAT | os.O_WRONLY | os.O_NOFOLLOW, 0o600)
+        try:
+            os.write(fd, (json.dumps(record, sort_keys=True, separators=(",", ":")) + "\n").encode())
+        finally:
+            os.close(fd)
+
+    def _read_command(self, path: Path) -> tuple[dict[str, Any], str]:
+        raw = _read_secure_text(path, max_bytes=131_072, allowed_owners={0, os.geteuid()})
+        value = validate_command(json.loads(raw), self.config.contract_commit)
+        return value, canonical_digest(value)
+
+    def _register(self, command: dict[str, Any], digest: str, path: Path) -> str:
+        now = self.clock()
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute("SELECT payload_sha256,status FROM commands WHERE command_id=?", (command["command_id"],)).fetchone()
+            if row:
+                db.execute("COMMIT")
+                if row["payload_sha256"] != digest:
+                    raise WatcherError("duplicate_command_payload_conflict")
+                return "duplicate_terminal" if row["status"] in TERMINAL else "existing"
+            prior_work_unit = db.execute(
+                "SELECT command_id FROM commands WHERE work_unit_id=?",
+                (command["work_unit_id"],),
+            ).fetchone()
+            if prior_work_unit:
+                db.execute("COMMIT")
+                raise WatcherError("duplicate_work_unit")
+            db.execute(
+                "INSERT INTO commands(command_id,work_unit_id,payload_sha256,source_path,status,phase,updated_at) VALUES(?,?,?,?,?,?,?)",
+                (command["command_id"], command["work_unit_id"], digest, str(path), "PENDING", "START", now),
+            )
+            db.execute("COMMIT")
+        return "new"
+
+    def _claim(self, command_id: str) -> sqlite3.Row | None:
+        now = self.clock()
+        with self._db() as db:
+            db.execute("BEGIN IMMEDIATE")
+            row = db.execute("SELECT * FROM commands WHERE command_id=?", (command_id,)).fetchone()
+            if not row or row["status"] in TERMINAL or row["next_attempt"] > now:
+                db.execute("COMMIT")
+                return None
+            if row["lease_until"] is not None and row["lease_until"] > now and row["lease_owner"] != self.worker_id:
+                db.execute("COMMIT")
+                return None
+            attempts = row["attempts"] + 1
+            db.execute(
+                "UPDATE commands SET status='CLAIMED',attempts=?,lease_owner=?,lease_until=?,updated_at=? WHERE command_id=?",
+                (attempts, self.worker_id, now + self.config.lease_seconds, now, command_id),
+            )
+            row = db.execute("SELECT * FROM commands WHERE command_id=?", (command_id,)).fetchone()
+            db.execute("COMMIT")
+        assert row is not None
+        self._audit("CODEX_AUTO_CLAIM", command_id, attempt=row["attempts"], worker=self.worker_id)
+        return row
+
+    def _update(self, command_id: str, *, status: str, phase: str, result: dict[str, Any] | None = None, error: str | None = None) -> None:
+        with self._db() as db:
+            release = status in TERMINAL
+            db.execute(
+                "UPDATE commands SET status=?,phase=?,result_json=COALESCE(?,result_json),last_error=?,lease_owner=CASE WHEN ? THEN NULL ELSE lease_owner END,lease_until=CASE WHEN ? THEN NULL ELSE lease_until END,updated_at=? WHERE command_id=?",
+                (status, phase, json.dumps(result, sort_keys=True) if result is not None else None, error, release, release, self.clock(), command_id),
+            )
+
+    def _retry_or_dead(self, command_id: str, path: Path, error: Exception) -> None:
+        message = f"{type(error).__name__}:{str(error)[:240]}"
+        with self._db() as db:
+            row = db.execute("SELECT attempts,phase FROM commands WHERE command_id=?", (command_id,)).fetchone()
+            attempts = row["attempts"] if row else self.config.max_attempts
+            if str(error) == "gateway_stale_state_version" and row:
+                column = "start_event_json" if row["phase"] == "START" else "end_event_json"
+                db.execute(f"UPDATE commands SET {column}=NULL WHERE command_id=?", (command_id,))
+            if attempts >= self.config.max_attempts:
+                db.execute("UPDATE commands SET status='DEAD_LETTER',last_error=?,lease_owner=NULL,lease_until=NULL,updated_at=? WHERE command_id=?", (message, self.clock(), command_id))
+                self._move(path, self.config.dead_letter_dir)
+                self._audit("DEAD_LETTER", command_id, error=message)
+            else:
+                db.execute("UPDATE commands SET status='RETRY',last_error=?,next_attempt=?,lease_owner=NULL,lease_until=NULL,updated_at=? WHERE command_id=?", (message, self.clock() + self.config.retry_seconds, self.clock(), command_id))
+                self._audit("RETRY_SCHEDULED", command_id, attempt=attempts, error=message)
+
+    def _event(self, command: dict[str, Any], event_type: str, status: str, suffix: str, result: dict[str, Any] | None = None) -> dict[str, Any]:
+        return {
+            "schema_version": 1, "project_key": command["project_key"],
+            "contract_commit": command["contract_commit"],
+            "event_id": f"{command['command_id']}:{suffix}", "source_agent": "codex",
+            "event_type": event_type, "work_unit_id": command["work_unit_id"],
+            "status": status, "state_version": command["state_version"],
+            "implementation_commit": None, "result_commit": None, "blocker": None,
+            "evidence_refs": [], "payload": {"command_id": command["command_id"], "result": result or {}},
+        }
+
+    def _gateway_token(self) -> str:
+        token = _read_secure_text(
+            self.config.gateway_token_file,
+            writable_mask=0o027,
+            max_bytes=16_384,
+            allowed_owners={0, os.geteuid()},
+        )
+        if not token or "\n" in token or "\r" in token:
+            raise WatcherError("invalid_gateway_token")
+        return token
+
+    def _gateway_state_version(self, project_key: str, fallback: int) -> int:
+        state_url = self.config.gateway_endpoint.removesuffix("/events") + "/state/" + urllib.parse.quote(project_key, safe="")
+        request = urllib.request.Request(
+            state_url,
+            headers={"Authorization": f"Bearer {self._gateway_token()}"},
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=15) as response:
+                payload = json.loads(response.read(262_145))
+                version = payload.get("state_version")
+                if not isinstance(version, int) or version < 0:
+                    raise WatcherError("invalid_gateway_state")
+                return version
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                return fallback
+            raise WatcherError(f"gateway_state_http_{exc.code}") from exc
+        except urllib.error.URLError as exc:
+            raise WatcherError("gateway_state_unavailable") from exc
+
+    def _durable_event(self, command: dict[str, Any], column: str, event: dict[str, Any]) -> dict[str, Any]:
+        with self._db() as db:
+            row = db.execute(f"SELECT {column} FROM commands WHERE command_id=?", (command["command_id"],)).fetchone()
+            if row and row[column]:
+                return json.loads(row[column])
+        if self._uses_gateway:
+            event["state_version"] = self._gateway_state_version(command["project_key"], command["state_version"])
+        encoded = json.dumps(event, sort_keys=True, separators=(",", ":"))
+        with self._db() as db:
+            db.execute(f"UPDATE commands SET {column}=? WHERE command_id=? AND {column} IS NULL", (encoded, command["command_id"]))
+            saved = db.execute(f"SELECT {column} FROM commands WHERE command_id=?", (command["command_id"],)).fetchone()
+        if not saved or not saved[column]:
+            raise WatcherError("event_persistence_failed")
+        return json.loads(saved[column])
+
+    def _post_event(self, event: dict[str, Any]) -> None:
+        request = urllib.request.Request(
+            self.config.gateway_endpoint,
+            data=json.dumps(event, separators=(",", ":")).encode(),
+            headers={"Authorization": f"Bearer {self._gateway_token()}", "Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=15) as response:
+                if response.status not in {200, 201, 202}:
+                    raise WatcherError(f"gateway_http_{response.status}")
+        except urllib.error.HTTPError as exc:
+            body = exc.read(16_384)
+            try:
+                reason = json.loads(body).get("error")
+            except (json.JSONDecodeError, UnicodeDecodeError, AttributeError):
+                reason = None
+            if exc.code == 409 and reason == "stale_state_version":
+                raise WatcherError("gateway_stale_state_version") from exc
+            raise WatcherError(f"gateway_http_{exc.code}") from exc
+        except urllib.error.URLError as exc:
+            raise WatcherError("gateway_unavailable") from exc
+
+    def _execute(self, command: dict[str, Any]) -> dict[str, Any]:
+        execution = command["execution"]
+        if execution["kind"] == "acceptance_probe":
+            return {"kind": "acceptance_probe", "input_sha256": hashlib.sha256(execution["input"].encode()).hexdigest(), "exit_code": 0}
+        assert self.config.executor_path is not None
+        with _codex_auth_lock():
+            proc = subprocess.run(
+                [str(self.config.executor_path), *self.config.executor_args],
+                input=execution["input"], text=True, stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL, timeout=self.config.executor_timeout_seconds,
+                check=False, env={"PATH": "/usr/bin:/bin", "LANG": "C.UTF-8"},
+            )
+        if proc.returncode != 0:
+            raise WatcherError(f"codex_executor_failed:{proc.returncode}")
+        return {"kind": "codex", "exit_code": 0}
+
+    def _preflight_execution(self, command: dict[str, Any]) -> None:
+        if command["execution"]["kind"] == "acceptance_probe":
+            return
+        if self.config.executor_path is None:
+            raise WatcherError("codex_executor_unavailable")
+        info = _secure_regular(self.config.executor_path)
+        if not info.st_mode & stat.S_IXUSR:
+            raise WatcherError("codex_executor_not_executable")
+
+    def _move(self, source: Path, target_dir: Path) -> None:
+        if not source.exists() and not source.is_symlink():
+            return
+        target = target_dir / source.name
+        if target.exists() or target.is_symlink():
+            target = target_dir / f"{source.stem}-{uuid.uuid4().hex[:8]}{source.suffix}"
+        os.replace(source, target)
+
+    def _reject_unregistered(self, path: Path, error: Exception) -> None:
+        command_id = path.stem[:128] if ID_RE.fullmatch(path.stem[:128]) else f"invalid-{uuid.uuid4().hex[:12]}"
+        self._audit("COMMAND_REJECTED", command_id, error=f"{type(error).__name__}:{str(error)[:240]}")
+        self._move(path, self.config.dead_letter_dir)
+
+    def process_path(self, path: Path) -> bool:
+        try:
+            command, digest = self._read_command(path)
+            registration = self._register(command, digest, path)
+            if registration == "duplicate_terminal":
+                self._move(path, self.config.completed_dir)
+                return False
+            row = self._claim(command["command_id"])
+            if row is None:
+                return False
+            phase = row["phase"]
+            result = json.loads(row["result_json"]) if row["result_json"] else None
+            if phase == "START":
+                start_event = self._durable_event(
+                    command,
+                    "start_event_json",
+                    self._event(command, "work_unit_started", "RUNNING", "started"),
+                )
+                self.event_poster(start_event)
+                self._audit("TASK_STARTED", command["command_id"])
+                self._update(command["command_id"], status="PENDING", phase="EXECUTE")
+                phase = "EXECUTE"
+            if phase == "EXECUTE":
+                self._preflight_execution(command)
+                self._update(command["command_id"], status="CLAIMED", phase="EXECUTING")
+                phase = "EXECUTING"
+                result = self.executor(command)
+                self._audit("TASK_EXECUTED", command["command_id"], result=result)
+                self._update(command["command_id"], status="PENDING", phase="END", result=result)
+                phase = "END"
+            elif phase == "EXECUTING":
+                raise WatcherError("ambiguous_execution_not_repeated")
+            if phase == "END":
+                assert result is not None
+                end_event = self._durable_event(
+                    command,
+                    "end_event_json",
+                    self._event(command, "work_unit_ended", "PASS", "ended", result),
+                )
+                self.event_poster(end_event)
+                self._audit("TASK_ENDED", command["command_id"])
+                self._audit("EVENT_POSTED", command["command_id"], event="work_unit_ended")
+                self._update(command["command_id"], status="COMPLETED", phase="DONE", result=result)
+                self._move(path, self.config.completed_dir)
+            return True
+        except Exception as exc:
+            try:
+                if isinstance(exc, WatcherError) and str(exc) in {"duplicate_command_payload_conflict", "duplicate_work_unit"}:
+                    self._reject_unregistered(path, exc)
+                elif "command" in locals():
+                    self._retry_or_dead(command["command_id"], path, exc)
+                else:
+                    self._reject_unregistered(path, exc)
+            except Exception:
+                pass
+            return False
+
+    def run_once(self) -> int:
+        failures = 0
+        for path in sorted(self.config.active_dir.glob("*.json")):
+            if not self.process_path(path):
+                failures += 1
+        return 1 if failures else 0
+
+    def run_forever(self) -> int:
+        while True:
+            self.run_once()
+            time.sleep(self.config.poll_seconds)

services/aios_orchestrator_gateway/__init__.py

@@ -0,0 +1,3 @@
+"""Reliable central orchestration gateway for AIOS."""
+
+__version__ = "0.2.0"

services/aios_orchestrator_gateway/__main__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from .config import Config
+from .service import Runtime, serve
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="AIOS Orchestrator Gateway")
+    parser.add_argument("--config", type=Path, required=True)
+    parser.add_argument("--log-level", default="INFO")
+    parser.add_argument(
+        "--poll-once",
+        action="store_true",
+        help="Run one inbox/model/outbox/OpenClaw synchronization polling cycle.",
+    )
+    args = parser.parse_args()
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    if args.poll_once:
+        runtime = Runtime(Config.from_file(args.config))
+        runtime.poll_once()
+        return 0
+    serve(args.config)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

services/aios_orchestrator_gateway/action_bridge.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+from typing import Any, Callable
+import urllib.error
+import urllib.request
+
+from .models import Decision
+
+
+GATEWAY_DECISION_URL = "http://127.0.0.1:18920/v1/orchestrator/decisions"
+SECRET_REF_RE = re.compile(r"^secret://[A-Za-z0-9._/-]{1,480}$")
+
+
+class CallbackBridgeError(RuntimeError):
+    def __init__(self, category: str, status_code: int) -> None:
+        super().__init__(category)
+        self.category = category
+        self.status_code = status_code
+
+
+def _trusted_resolver(path: Path) -> Path:
+    if not path.is_absolute():
+        raise CallbackBridgeError("CALLBACK_CONFIGURATION_UNAVAILABLE", 503)
+    try:
+        info = path.lstat()
+        resolved = path.resolve(strict=True)
+    except OSError as exc:
+        raise CallbackBridgeError("CALLBACK_CONFIGURATION_UNAVAILABLE", 503) from exc
+    if (
+        resolved != path
+        or stat.S_ISLNK(info.st_mode)
+        or not stat.S_ISREG(info.st_mode)
+        or info.st_uid != 0
+        or stat.S_IMODE(info.st_mode) & 0o022
+        or not stat.S_IMODE(info.st_mode) & 0o111
+    ):
+        raise CallbackBridgeError("CALLBACK_CONFIGURATION_UNAVAILABLE", 503)
+    return resolved
+
+
+def resolve_secret_ref(secret_ref: str, resolver: Path) -> str:
+    if not isinstance(secret_ref, str) or not SECRET_REF_RE.fullmatch(secret_ref):
+        raise CallbackBridgeError("CALLBACK_CONFIGURATION_UNAVAILABLE", 503)
+    executable = _trusted_resolver(resolver)
+    request = json.dumps(
+        {"operation": "resolve", "secret_ref": secret_ref},
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode()
+    try:
+        result = subprocess.run(
+            [str(executable)],
+            input=request,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            env={"PATH": "/usr/bin:/bin", "LANG": "C", "LC_ALL": "C"},
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise CallbackBridgeError("CALLBACK_CREDENTIAL_UNAVAILABLE", 503) from exc
+    token = result.stdout.removesuffix(b"\n")
+    if (
+        result.returncode != 0
+        or not token
+        or len(token) > 16_384
+        or b"\n" in token
+        or b"\r" in token
+    ):
+        raise CallbackBridgeError("CALLBACK_CREDENTIAL_UNAVAILABLE", 503)
+    try:
+        return token.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise CallbackBridgeError("CALLBACK_CREDENTIAL_UNAVAILABLE", 503) from exc
+
+
+def submit_orchestration_decision(
+    payload: dict[str, Any],
+    *,
+    contract_commit: str,
+    secret_ref: str,
+    resolver: Path,
+    request_open: Callable[..., Any] = urllib.request.urlopen,
+) -> dict[str, Any]:
+    try:
+        decision = Decision.from_dict(payload)
+    except Exception as exc:
+        raise CallbackBridgeError("INVALID_DECISION", 422) from exc
+    if decision.contract_commit != contract_commit:
+        raise CallbackBridgeError("CONTRACT_MISMATCH", 409)
+    token = resolve_secret_ref(secret_ref, resolver)
+    request = urllib.request.Request(
+        GATEWAY_DECISION_URL,
+        data=json.dumps(
+            decision.to_dict(), separators=(",", ":"), sort_keys=True
+        ).encode(),
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Idempotency-Key": decision.event_id,
+            "User-Agent": "aios-chatgpt-actions/decision-bridge-v1",
+        },
+    )
+    try:
+        with request_open(request, timeout=10) as response:
+            raw = response.read(65_537)
+            if response.status != 202 or len(raw) > 65_536:
+                raise CallbackBridgeError("CALLBACK_HTTP_ERROR", 502)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 409:
+            raise CallbackBridgeError("STALE_STATE", 409) from exc
+        raise CallbackBridgeError("CALLBACK_HTTP_ERROR", 502) from exc
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise CallbackBridgeError("CALLBACK_NETWORK_ERROR", 502) from exc
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CallbackBridgeError("CALLBACK_RESPONSE_INVALID", 502) from exc
+    if (
+        not isinstance(value, dict)
+        or value.get("accepted") is not True
+        or not isinstance(value.get("state_version"), int)
+    ):
+        raise CallbackBridgeError("CALLBACK_RESPONSE_INVALID", 502)
+    return {"accepted": True, "state_version": value["state_version"]}

services/aios_orchestrator_gateway/callback_transport.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import ipaddress
+from typing import Any
+from urllib.parse import urlparse
+
+from .errors import ConfigurationError
+from .models import DECISION_SCHEMA
+
+
+TRANSPORT_MODES = {"remote_https_action", "secure_mcp_tunnel"}
+FORBIDDEN_HOSTS = {"localhost", "localhost.localdomain"}
+FORBIDDEN_MARKERS = {"replace_with_actions_host", "placeholder"}
+
+
+def _https_endpoint(value: Any, *, public: bool) -> str:
+    if not isinstance(value, str) or not value or any(
+        marker in value.lower() for marker in FORBIDDEN_MARKERS
+    ):
+        raise ConfigurationError("invalid_callback_endpoint")
+    parsed = urlparse(value)
+    host = (parsed.hostname or "").lower()
+    if (
+        parsed.scheme != "https"
+        or not host
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+        or host in FORBIDDEN_HOSTS
+    ):
+        raise ConfigurationError("invalid_callback_endpoint")
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        address = None
+    if address is not None and (
+        address.is_loopback
+        or address.is_private
+        or address.is_unspecified
+        or address.is_link_local
+        or address.is_multicast
+        or address.is_reserved
+    ):
+        raise ConfigurationError("invalid_callback_endpoint")
+    if public and (address is None and ("." not in host or host.endswith((".local", ".internal")))):
+        raise ConfigurationError("callback_endpoint_not_public")
+    return value.rstrip("/")
+
+
+@dataclass(frozen=True)
+class CallbackTransport:
+    mode: str
+    endpoint: str
+    approved_mcp_tunnel_endpoints: tuple[str, ...]
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "CallbackTransport":
+        expected = {"mode", "endpoint", "approved_mcp_tunnel_endpoints"}
+        if not isinstance(value, dict) or set(value) != expected:
+            raise ConfigurationError("invalid_callback_transport_fields")
+        mode = value.get("mode")
+        if mode not in TRANSPORT_MODES:
+            raise ConfigurationError("invalid_callback_transport_mode")
+        approved = value.get("approved_mcp_tunnel_endpoints")
+        if not isinstance(approved, list) or any(not isinstance(x, str) for x in approved):
+            raise ConfigurationError("invalid_approved_mcp_tunnel_endpoints")
+        normalized_approved = tuple(_https_endpoint(item, public=False) for item in approved)
+        endpoint = _https_endpoint(value.get("endpoint"), public=mode == "remote_https_action")
+        if mode == "secure_mcp_tunnel" and endpoint not in normalized_approved:
+            raise ConfigurationError("unapproved_secure_mcp_tunnel_endpoint")
+        return cls(mode, endpoint, normalized_approved)
+
+    def action_openapi(self) -> dict[str, Any]:
+        if self.mode != "remote_https_action":
+            raise ConfigurationError("action_manifest_for_wrong_transport")
+        return {
+            "openapi": "3.1.0",
+            "info": {"title": "AIOS Orchestrator Decision Callback", "version": "1.1.0"},
+            "servers": [{"url": self.endpoint}],
+            "paths": {
+                "/v1/orchestrator/decisions": {
+                    "post": {
+                        "operationId": "submit_orchestration_decision",
+                        "summary": "Submit one strict orchestration decision",
+                        "security": [{"bearerAuth": []}],
+                        "requestBody": {
+                            "required": True,
+                            "content": {"application/json": {"schema": DECISION_SCHEMA}},
+                        },
+                        "responses": {"202": {"description": "Accepted"}},
+                    }
+                }
+            },
+            "components": {
+                "securitySchemes": {
+                    "bearerAuth": {"type": "http", "scheme": "bearer"}
+                }
+            },
+        }
+
+    def mcp_tool(self) -> dict[str, Any]:
+        if self.mode != "secure_mcp_tunnel":
+            raise ConfigurationError("mcp_manifest_for_wrong_transport")
+        return {
+            "name": "submit_orchestration_decision",
+            "description": "Validate and submit one AIOS orchestration decision.",
+            "inputSchema": DECISION_SCHEMA,
+            "annotations": {
+                "title": "Submit orchestration decision",
+                "readOnlyHint": False,
+                "destructiveHint": False,
+                "idempotentHint": True,
+                "openWorldHint": False,
+            },
+        }

services/aios_orchestrator_gateway/clients.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .errors import TriggerError
+from .models import DECISION_SCHEMA, Decision, Event
+
+
+@dataclass(frozen=True)
+class WorkspaceTriggerResult:
+    http_status: int
+    remote_id: None = None
+
+
+WORKSPACE_HTTP_CATEGORIES = {
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    409: "NOT_RUNNABLE",
+}
+
+
+class WorkspaceAgentClient:
+    """Asynchronous Workspace Agent trigger.
+
+    The official endpoint returns only 202 and no run ID or retrievable output.
+    Completion therefore arrives through the gateway callback endpoint.
+    """
+
+    def __init__(self, trigger_id: str, token: str, timeout_seconds: int = 30):
+        self.trigger_id = trigger_id
+        self.token = token
+        self.timeout_seconds = timeout_seconds
+
+    def trigger(self, event: Event) -> WorkspaceTriggerResult:
+        url = f"https://api.chatgpt.com/v1/workspace_agents/{self.trigger_id}/trigger"
+        prompt = (
+            "Process this AIOS orchestration event under the committed contract. "
+            "When complete, call submit_orchestration_decision with strict JSON. "
+            "Do not fabricate tests, Git state, secrets, evidence, or deployment facts.\n\n"
+            + event.canonical_json()
+        )
+        body = json.dumps(
+            {
+                "conversation_key": event.project_key,
+                "input": prompt,
+            }
+        ).encode()
+        request = urllib.request.Request(
+            url,
+            data=body,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json",
+                "Idempotency-Key": event.event_id,
+                "User-Agent": "aios-orchestrator-gateway/0.2",
+            },
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
+                if response.status != 202:
+                    raise TriggerError(
+                        "workspace_agent_unexpected_http_status",
+                        http_status=response.status,
+                    )
+                return WorkspaceTriggerResult(http_status=202)
+        except urllib.error.HTTPError as exc:
+            category = WORKSPACE_HTTP_CATEGORIES.get(exc.code)
+            raise TriggerError(
+                "workspace_agent_http_error",
+                http_status=exc.code,
+                category=category,
+            ) from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise TriggerError(
+                "workspace_agent_network_error",
+                category="NETWORK_ERROR",
+            ) from exc
+
+
+class ResponsesClient:
+    """Background Responses API client with polling and strict output validation."""
+
+    def __init__(self, api_key: str, model: str, timeout_seconds: int = 60):
+        self.api_key = api_key
+        self.model = model
+        self.timeout_seconds = timeout_seconds
+
+    def start(self, event: Event) -> str:
+        body = {
+            "model": self.model,
+            "background": True,
+            "instructions": (
+                "You are the AIOS central orchestration brain. Apply the exact "
+                "contract_commit in the event. Return only a strict decision. "
+                "Never fabricate evidence, secrets, Git facts, tests, approvals, "
+                "or deployment state. Keep external blockers fail-closed."
+            ),
+            "input": event.canonical_json(),
+            "text": {
+                "format": {
+                    "type": "json_schema",
+                    "name": "aios_orchestrator_decision",
+                    "strict": True,
+                    "schema": DECISION_SCHEMA,
+                }
+            },
+            "metadata": {
+                "event_id": event.event_id,
+                "project_key": event.project_key,
+                "contract_commit": event.contract_commit,
+            },
+        }
+        payload = self._request(
+            "POST",
+            "https://api.openai.com/v1/responses",
+            body,
+            idempotency_key=event.event_id,
+        )
+        response_id = payload.get("id")
+        if not isinstance(response_id, str) or not response_id.startswith("resp_"):
+            raise TriggerError("responses_missing_id")
+        return response_id
+
+    def poll(self, response_id: str) -> tuple[str, Decision | None]:
+        payload = self._request(
+            "GET",
+            f"https://api.openai.com/v1/responses/{response_id}",
+            None,
+        )
+        status = payload.get("status")
+        if status in {"queued", "in_progress"}:
+            return str(status), None
+        if status == "completed":
+            text = _extract_output_text(payload)
+            try:
+                return "completed", Decision.from_dict(json.loads(text))
+            except json.JSONDecodeError as exc:
+                raise TriggerError("responses_invalid_json") from exc
+        if status in {"failed", "cancelled", "incomplete"}:
+            raise TriggerError(f"responses_{status}")
+        raise TriggerError("responses_unknown_status")
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        body: dict[str, Any] | None,
+        *,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        encoded = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "aios-orchestrator-gateway/0.2",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        request = urllib.request.Request(
+            url,
+            data=encoded,
+            method=method,
+            headers=headers,
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
+                raw = response.read(4_194_304)
+                if response.status not in {200, 201}:
+                    raise TriggerError(f"responses_http_{response.status}")
+        except urllib.error.HTTPError as exc:
+            raise TriggerError(f"responses_http_{exc.code}") from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise TriggerError("responses_request_failed") from exc
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise TriggerError("responses_invalid_payload") from exc
+        if not isinstance(payload, dict):
+            raise TriggerError("responses_payload_not_object")
+        return payload
+
+
+def _extract_output_text(payload: dict[str, Any]) -> str:
+    output = payload.get("output")
+    if not isinstance(output, list):
+        raise TriggerError("responses_missing_output")
+    for item in output:
+        if not isinstance(item, dict):
+            continue
+        content = item.get("content")
+        if not isinstance(content, list):
+            continue
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "output_text":
+                text = part.get("text")
+                if isinstance(text, str):
+                    return text
+    raise TriggerError("responses_missing_output_text")

services/aios_orchestrator_gateway/codex_local.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+import fcntl
+import json
+import os
+from pathlib import Path
+import pwd
+import signal
+import stat
+import subprocess
+import tempfile
+import threading
+from typing import Iterator
+
+from .errors import ConfigurationError, TriggerError, ValidationError
+from .models import DECISION_SCHEMA, Decision, Event
+from .securefs import ensure_shared_directory, read_secure_json
+
+
+CODEX_BINARY = Path("/usr/local/bin/codex")
+CODEX_HOME = Path("/var/lib/aios-codex-brain/.codex")
+AUTH_JSON = CODEX_HOME / "auth.json"
+CONTROLLER_WORKDIR = Path("/data/aios-gitops/worktrees/controller")
+AUTH_LOCK = Path("/run/lock/aios-codex-auth.lock")
+REQUIRED_EXEC_FLAGS = (
+    "--json", "--output-schema", "--output-last-message", "--sandbox",
+    "--ask-for-approval", "--cd", "--ephemeral",
+)
+FORBIDDEN_INSTRUCTIONS = (
+    "reset --hard", "force push", "push main", "auth.json", "read secret",
+    "production deploy", "production deployment",
+)
+_PROCESS_LOCK = threading.Lock()
+
+
+@dataclass(frozen=True)
+class CodexLocalSettings:
+    timeout_seconds: int = 300
+    binary: Path = CODEX_BINARY
+    codex_home: Path = CODEX_HOME
+    auth_json: Path = AUTH_JSON
+    controller_workdir: Path = CONTROLLER_WORKDIR
+    lock_path: Path = AUTH_LOCK
+    expected_auth_uid: int | None = None
+
+
+def _regular_nofollow(path: Path) -> os.stat_result:
+    info = path.lstat()
+    if stat.S_ISLNK(info.st_mode) or not stat.S_ISREG(info.st_mode):
+        raise ConfigurationError("unsafe_codex_auth_file")
+    if path.resolve(strict=True) != path:
+        raise ConfigurationError("unsafe_codex_auth_path")
+    return info
+
+
+def validate_auth_json(path: Path, expected_uid: int | None = None) -> None:
+    if not path.is_absolute() or not path.exists():
+        raise ConfigurationError("codex_authentication_required")
+    info = _regular_nofollow(path)
+    uid = pwd.getpwnam("aios-codex-brain").pw_uid if expected_uid is None else expected_uid
+    if info.st_uid != uid:
+        raise ConfigurationError("codex_auth_wrong_owner")
+    if stat.S_IMODE(info.st_mode) != 0o600:
+        raise ConfigurationError("codex_auth_wrong_mode")
+
+
+class CodexLocalClient:
+    """Serialized, fail-closed local Codex decision client.
+
+    Authentication values are never opened by this class. The Codex CLI is the
+    sole consumer of its own cache after metadata validation.
+    """
+
+    def __init__(self, settings: CodexLocalSettings = CodexLocalSettings()):
+        self.settings = settings
+
+    def _environment(self) -> dict[str, str]:
+        return {
+            "CODEX_HOME": str(self.settings.codex_home),
+            "HOME": str(self.settings.codex_home.parent),
+            "PATH": f"{self.settings.binary.parent}:/usr/bin:/bin",
+            "LANG": "C.UTF-8",
+            "LC_ALL": "C.UTF-8",
+        }
+
+    def _validate_fixed_paths(self) -> None:
+        s = self.settings
+        for path in (s.binary, s.codex_home, s.auth_json, s.controller_workdir, s.lock_path):
+            if not path.is_absolute():
+                raise ConfigurationError("codex_path_not_absolute")
+        if not s.binary.exists() or not os.access(s.binary, os.X_OK):
+            raise ConfigurationError("codex_binary_unavailable")
+        if s.binary.is_symlink() or not s.binary.is_file():
+            raise ConfigurationError("unsafe_codex_binary")
+        if not s.controller_workdir.is_dir() or s.controller_workdir.is_symlink():
+            raise ConfigurationError("unsafe_controller_workdir")
+        validate_auth_json(s.auth_json, s.expected_auth_uid)
+
+    @contextmanager
+    def _auth_lock(self) -> Iterator[None]:
+        with _PROCESS_LOCK:
+            flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0)
+            fd = os.open(self.settings.lock_path, flags, 0o600)
+            try:
+                info = os.fstat(fd)
+                if not stat.S_ISREG(info.st_mode) or stat.S_IMODE(info.st_mode) & ~0o660:
+                    raise ConfigurationError("unsafe_codex_auth_lock")
+                if info.st_uid != os.geteuid():
+                    raise ConfigurationError("unsafe_codex_auth_lock_owner")
+                fcntl.flock(fd, fcntl.LOCK_EX)
+                yield
+            finally:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+                os.close(fd)
+
+    def _run_quiet(self, argv: list[str], timeout: int) -> subprocess.CompletedProcess[str]:
+        try:
+            return subprocess.run(
+                argv, cwd=self.settings.controller_workdir, env=self._environment(),
+                stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL, text=True, timeout=timeout, check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise ConfigurationError("codex_cli_probe_failed") from exc
+
+    def _probe_cli_unlocked(self) -> None:
+        result = self._run_quiet([str(self.settings.binary), "exec", "--help"], 30)
+        if result.returncode != 0 or any(flag not in result.stdout for flag in REQUIRED_EXEC_FLAGS):
+            raise ConfigurationError("blocked_codex_cli_version_incompatible")
+
+    def _login_status_unlocked(self) -> None:
+        result = self._run_quiet([str(self.settings.binary), "login", "status"], 30)
+        if result.returncode != 0:
+            raise ConfigurationError("codex_authentication_required")
+
+    def health_check(self) -> None:
+        self._validate_fixed_paths()
+        with self._auth_lock():
+            self._probe_cli_unlocked()
+            self._login_status_unlocked()
+
+    def decide(self, event: Event) -> Decision:
+        self._validate_fixed_paths()
+        with self._auth_lock():
+            self._probe_cli_unlocked()
+            self._login_status_unlocked()
+            value = self._exec_unlocked(event)
+        return self._validate_decision(value, event)
+
+    def _exec_unlocked(self, event: Event) -> dict:
+        prompt = (
+            "读取已提交治理合同。读取下列本次事件JSON。只输出一个符合Decision Schema的决策。"
+            "不得修改Git、运行部署、读取秘密或伪造证据。证据不足时输出BLOCKED决策。\n"
+            + event.canonical_json()
+        )
+        runtime_root = self.settings.codex_home.parent / "runtime"
+        runtime_root.mkdir(mode=0o700, parents=True, exist_ok=True)
+        if runtime_root.is_symlink() or runtime_root.resolve(strict=True) != runtime_root:
+            raise ConfigurationError("unsafe_codex_runtime_directory")
+        os.chmod(runtime_root, 0o700)
+        with tempfile.TemporaryDirectory(prefix="decision-", dir=runtime_root) as directory:
+            root = Path(directory)
+            schema_path = root / "decision.schema.json"
+            output_path = root / "decision.json"
+            schema_path.write_text(json.dumps(DECISION_SCHEMA, separators=(",", ":")), encoding="utf-8")
+            schema_path.chmod(0o600)
+            argv = [
+                str(self.settings.binary), "exec", "--json",
+                "--output-schema", str(schema_path),
+                "--output-last-message", str(output_path),
+                "--sandbox", "read-only", "--ask-for-approval", "never",
+                "--cd", str(self.settings.controller_workdir), "--ephemeral", "-",
+            ]
+            process = subprocess.Popen(
+                argv, cwd=self.settings.controller_workdir, env=self._environment(),
+                stdin=subprocess.PIPE, stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL, text=True, start_new_session=True,
+            )
+            try:
+                process.communicate(prompt, timeout=self.settings.timeout_seconds)
+            except subprocess.TimeoutExpired as exc:
+                self._terminate_group(process)
+                raise TriggerError("codex_exec_timeout") from exc
+            if process.returncode != 0:
+                raise TriggerError("codex_exec_nonzero")
+            try:
+                if output_path.stat().st_size > 1_048_576:
+                    raise TriggerError("codex_output_too_large")
+                value = json.loads(output_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                raise TriggerError("codex_exec_invalid_json") from exc
+            if not isinstance(value, dict):
+                raise TriggerError("codex_exec_invalid_json")
+            return value
+
+    @staticmethod
+    def _terminate_group(process: subprocess.Popen[str]) -> None:
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+            process.wait(timeout=2)
+        except (ProcessLookupError, subprocess.TimeoutExpired):
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            process.wait(timeout=5)
+
+    @staticmethod
+    def _validate_decision(value: dict, event: Event) -> Decision:
+        decision = Decision.from_dict(value)
+        if decision.contract_commit != event.contract_commit:
+            raise ValidationError("contract_version_mismatch")
+        if decision.event_id != event.event_id or decision.project_key != event.project_key:
+            raise ValidationError("event_identity_mismatch")
+        if decision.expected_state_version != event.state_version:
+            raise ValidationError("state_version_mismatch")
+        allowed = event.payload.get("allowed_work_unit_ids", [])
+        if not isinstance(allowed, list) or any(not isinstance(item, str) for item in allowed):
+            raise ValidationError("invalid_allowed_work_units")
+        if any(unit.id not in allowed for unit in decision.next_work_units):
+            raise ValidationError("work_unit_not_allowed")
+        for unit in decision.next_work_units:
+            instruction = unit.instruction.lower()
+            if any(item in instruction for item in FORBIDDEN_INSTRUCTIONS):
+                raise ValidationError("forbidden_operation")
+        return decision
+
+
+class CodexLocalQueue:
+    """Atomic, idempotent event handoff from Gateway to the brain service."""
+
+    def __init__(self, root: Path):
+        self.root = root
+        for name in ("pending", "processing", "processed", "dead-letter"):
+            ensure_shared_directory(root / name, group_writable=True)
+
+    def enqueue(self, event: Event) -> Path:
+        pending = self.root / "pending"
+        path = pending / f"{event.event_id}.json"
+        body = json.dumps(
+            {"attempts": 0, "next_attempt_at": 0, "event": event.to_dict()},
+            separators=(",", ":"), sort_keys=True,
+        )
+        try:
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o640)
+        except FileExistsError:
+            existing = read_secure_json(path, expected_uid=None)
+            if existing.get("event") != event.to_dict():
+                raise TriggerError("codex_queue_idempotency_conflict")
+            return path
+        os.fchmod(fd, 0o640)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(body)
+            handle.flush()
+            os.fsync(handle.fileno())
+        return path

services/aios_orchestrator_gateway/config.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import stat
+from typing import Any
+
+from .errors import ConfigurationError
+from .securefs import read_secure_bytes, read_secure_json, verify_secure_file
+
+
+REMOTE_RUNNER_SCOPES = frozenset({"claim", "heartbeat", "decision", "fail"})
+
+
+@dataclass(frozen=True)
+class RemoteRunnerCredential:
+    runner_id: str
+    token_file: Path
+    scopes: frozenset[str]
+
+
+@dataclass(frozen=True)
+class Config:
+    host: str
+    port: int
+    project_key: str
+    database_path: Path
+    event_inbox_dir: Path
+    decision_inbox_dir: Path
+    dispatch_outbox_dir: Path
+    openclaw_sync_dir: Path
+    command_queue_dir: Path
+    inbound_token_file: Path
+    callback_token_file: Path
+    contract_commit: str
+    central_channel: str
+    codex_queue_dir: Path | None
+    codex_timeout_seconds: int
+    workspace_trigger_id: str | None
+    workspace_token_file: Path | None
+    responses_api_key_file: Path | None
+    responses_model: str | None
+    poll_interval_seconds: int
+    summary_interval_seconds: int
+    callback_timeout_seconds: int
+    lease_seconds: int
+    retry_base_seconds: int
+    max_retries: int
+    max_same_blocker_retries: int
+    max_hops_per_gate: int
+    openclaw_sync_endpoint: str | None
+    openclaw_sync_token_file: Path | None
+    git_poll_enabled: bool
+    git_poll_bare_repo: Path | None
+    git_poll_ref_prefixes: tuple[str, ...]
+    git_poll_interval_seconds: int
+    remote_request_max_bytes: int
+    remote_job_lease_seconds: int
+    remote_runner_credentials: tuple[RemoteRunnerCredential, ...]
+
+    @classmethod
+    def from_file(cls, path: Path) -> "Config":
+        owner_uid = int(os.environ.get("AIOS_ORCHESTRATOR_CONFIG_OWNER_UID", "0"))
+        raw = read_secure_json(path, expected_uid=owner_uid)
+        expected = {
+            "host", "port", "project_key", "database_path", "event_inbox_dir",
+            "decision_inbox_dir", "dispatch_outbox_dir", "openclaw_sync_dir",
+            "command_queue_dir", "inbound_token_file", "callback_token_file",
+            "contract_commit", "workspace_agent", "responses_fallback",
+            "central_channel", "codex_local", "polling", "loop_controls",
+            "openclaw_sync", "git_poll",
+        }
+        if frozenset(raw) not in {frozenset(expected), frozenset(expected | {"remote_codex"})}:
+            raise ConfigurationError("invalid_config_fields")
+
+        def path_value(key: str) -> Path:
+            value = raw.get(key)
+            if not isinstance(value, str):
+                raise ConfigurationError(f"invalid_{key}")
+            result = Path(value)
+            if not result.is_absolute():
+                raise ConfigurationError(f"path_not_absolute:{key}")
+            return result
+
+        def integer(container: dict[str, Any], key: str, lo: int, hi: int) -> int:
+            value = container.get(key)
+            if not isinstance(value, int) or not lo <= value <= hi:
+                raise ConfigurationError(f"invalid_{key}")
+            return value
+
+        host = raw.get("host")
+        port = raw.get("port")
+        project_key = raw.get("project_key")
+        contract = raw.get("contract_commit")
+        if not isinstance(host, str) or not host:
+            raise ConfigurationError("invalid_host")
+        if not isinstance(project_key, str) or not project_key:
+            raise ConfigurationError("invalid_project_key")
+        if not isinstance(port, int) or not 1 <= port <= 65535:
+            raise ConfigurationError("invalid_port")
+        if not isinstance(contract, str) or len(contract) != 40:
+            raise ConfigurationError("invalid_contract_commit")
+
+        workspace = raw.get("workspace_agent")
+        responses = raw.get("responses_fallback")
+        codex_local = raw.get("codex_local")
+        polling = raw.get("polling")
+        loop = raw.get("loop_controls")
+        sync = raw.get("openclaw_sync")
+        git_poll = raw.get("git_poll")
+        remote_codex = raw.get("remote_codex", {
+            "request_max_bytes": 262144,
+            "job_lease_seconds": 120,
+            "runners": [],
+        })
+        if not all(isinstance(x, dict) for x in (workspace, responses, codex_local, polling, loop, sync, git_poll, remote_codex)):
+            raise ConfigurationError("invalid_nested_config")
+
+        central_channel = raw.get("central_channel")
+        if central_channel not in {"codex_local", "remote_codex", "workspace_agent", "responses_api"}:
+            raise ConfigurationError("invalid_central_channel")
+
+        if set(remote_codex) != {"request_max_bytes", "job_lease_seconds", "runners"}:
+            raise ConfigurationError("invalid_remote_codex_fields")
+        remote_request_max = integer(remote_codex, "request_max_bytes", 1024, 1_048_576)
+        remote_lease = integer(remote_codex, "job_lease_seconds", 30, 3600)
+        raw_runners = remote_codex.get("runners")
+        if not isinstance(raw_runners, list) or len(raw_runners) > 32:
+            raise ConfigurationError("invalid_remote_runners")
+        runner_credentials: list[RemoteRunnerCredential] = []
+        seen_runners: set[str] = set()
+        for item in raw_runners:
+            if not isinstance(item, dict) or set(item) != {"runner_id", "token_file", "scopes"}:
+                raise ConfigurationError("invalid_remote_runner")
+            runner_id = item.get("runner_id")
+            token_path = item.get("token_file")
+            scopes = item.get("scopes")
+            if (
+                not isinstance(runner_id, str) or not runner_id
+                or len(runner_id) > 128
+                or any(ch not in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._:-" for ch in runner_id)
+                or runner_id in seen_runners
+            ):
+                raise ConfigurationError("invalid_remote_runner_id")
+            if not isinstance(token_path, str) or not Path(token_path).is_absolute():
+                raise ConfigurationError("invalid_remote_runner_token_file")
+            if (
+                not isinstance(scopes, list) or not scopes
+                or any(not isinstance(scope, str) or scope not in REMOTE_RUNNER_SCOPES for scope in scopes)
+                or len(scopes) != len(set(scopes))
+            ):
+                raise ConfigurationError("invalid_remote_runner_scopes")
+            seen_runners.add(runner_id)
+            runner_credentials.append(RemoteRunnerCredential(
+                runner_id=runner_id, token_file=Path(token_path), scopes=frozenset(scopes)
+            ))
+        if central_channel == "remote_codex" and not runner_credentials:
+            raise ConfigurationError("remote_codex_runner_required")
+
+        trigger_id = workspace.get("trigger_id")
+        workspace_token = workspace.get("access_token_file")
+        if trigger_id is not None:
+            if not isinstance(trigger_id, str) or not trigger_id.startswith("agtch_"):
+                raise ConfigurationError("invalid_workspace_trigger_id")
+            if not isinstance(workspace_token, str) or not Path(workspace_token).is_absolute():
+                raise ConfigurationError("invalid_workspace_token_file")
+            workspace_token_file = Path(workspace_token)
+        else:
+            workspace_token_file = None
+
+        responses_key = responses.get("api_key_file")
+        responses_model = responses.get("model")
+        if responses_key is not None:
+            if not isinstance(responses_key, str) or not Path(responses_key).is_absolute():
+                raise ConfigurationError("invalid_responses_key_file")
+            if not isinstance(responses_model, str) or not responses_model:
+                raise ConfigurationError("invalid_responses_model")
+            responses_key_file = Path(responses_key)
+        else:
+            responses_key_file = None
+            responses_model = None
+
+        codex_queue = codex_local.get("queue_dir")
+        codex_timeout = integer(codex_local, "timeout_seconds", 30, 3600)
+        if central_channel in {"codex_local", "remote_codex"}:
+            if trigger_id is not None or responses_key_file is not None:
+                raise ConfigurationError("parked_channel_must_be_disabled")
+            if central_channel == "codex_local":
+                if not isinstance(codex_queue, str) or not Path(codex_queue).is_absolute():
+                    raise ConfigurationError("invalid_codex_queue_dir")
+                codex_queue_dir = Path(codex_queue)
+            else:
+                codex_queue_dir = None
+        else:
+            codex_queue_dir = None
+            if central_channel == "workspace_agent" and trigger_id is None:
+                raise ConfigurationError("workspace_channel_not_configured")
+            if central_channel == "responses_api" and responses_key_file is None:
+                raise ConfigurationError("responses_channel_not_configured")
+
+        endpoint = sync.get("endpoint")
+        token_file = sync.get("token_file")
+        if endpoint is not None and (not isinstance(endpoint, str) or not endpoint.startswith(("http://", "https://"))):
+            raise ConfigurationError("invalid_openclaw_sync_endpoint")
+        if endpoint is not None:
+            if not isinstance(token_file, str) or not Path(token_file).is_absolute():
+                raise ConfigurationError("invalid_openclaw_sync_token_file")
+            sync_token_file = Path(token_file)
+        else:
+            sync_token_file = None
+
+        git_enabled = git_poll.get("enabled")
+        if not isinstance(git_enabled, bool):
+            raise ConfigurationError("invalid_git_poll_enabled")
+        git_bare_repo_raw = git_poll.get("bare_repo")
+        git_prefixes_raw = git_poll.get("ref_prefixes")
+        if git_enabled:
+            if not isinstance(git_bare_repo_raw, str) or not Path(git_bare_repo_raw).is_absolute():
+                raise ConfigurationError("invalid_git_poll_bare_repo")
+            if (
+                not isinstance(git_prefixes_raw, list)
+                or not git_prefixes_raw
+                or any(not isinstance(item, str) or not item.startswith("refs/") for item in git_prefixes_raw)
+            ):
+                raise ConfigurationError("invalid_git_poll_ref_prefixes")
+            git_bare_repo = Path(git_bare_repo_raw)
+            git_prefixes = tuple(git_prefixes_raw)
+        else:
+            git_bare_repo = None
+            git_prefixes = ()
+
+        return cls(
+            host=host,
+            port=port,
+            project_key=project_key,
+            database_path=path_value("database_path"),
+            event_inbox_dir=path_value("event_inbox_dir"),
+            decision_inbox_dir=path_value("decision_inbox_dir"),
+            dispatch_outbox_dir=path_value("dispatch_outbox_dir"),
+            openclaw_sync_dir=path_value("openclaw_sync_dir"),
+            command_queue_dir=path_value("command_queue_dir"),
+            inbound_token_file=path_value("inbound_token_file"),
+            callback_token_file=path_value("callback_token_file"),
+            contract_commit=contract,
+            central_channel=central_channel,
+            codex_queue_dir=codex_queue_dir,
+            codex_timeout_seconds=codex_timeout,
+            workspace_trigger_id=trigger_id,
+            workspace_token_file=workspace_token_file,
+            responses_api_key_file=responses_key_file,
+            responses_model=responses_model,
+            poll_interval_seconds=integer(polling, "interval_seconds", 1, 300),
+            summary_interval_seconds=integer(polling, "summary_interval_seconds", 10, 86400),
+            callback_timeout_seconds=integer(loop, "callback_timeout_seconds", 30, 86400),
+            lease_seconds=integer(loop, "lease_seconds", 10, 3600),
+            retry_base_seconds=integer(loop, "retry_base_seconds", 1, 3600),
+            max_retries=integer(loop, "max_retries", 0, 20),
+            max_same_blocker_retries=integer(loop, "max_same_blocker_retries", 0, 20),
+            max_hops_per_gate=integer(loop, "max_hops_per_gate", 1, 100),
+            openclaw_sync_endpoint=endpoint,
+            openclaw_sync_token_file=sync_token_file,
+            git_poll_enabled=git_enabled,
+            git_poll_bare_repo=git_bare_repo,
+            git_poll_ref_prefixes=git_prefixes,
+            git_poll_interval_seconds=integer(git_poll, "interval_seconds", 5, 3600),
+            remote_request_max_bytes=remote_request_max,
+            remote_job_lease_seconds=remote_lease,
+            remote_runner_credentials=tuple(runner_credentials),
+        )
+
+    def _secret(self, path: Path) -> str:
+        owner_uid = int(os.environ.get("AIOS_ORCHESTRATOR_SECRET_OWNER_UID", "0"))
+        info = verify_secure_file(path, expected_uid=owner_uid)
+        if stat.S_IMODE(info.st_mode) & ~0o640:
+            raise ConfigurationError(f"permissive_secret_mode:{path}")
+        data = read_secure_bytes(path, expected_uid=owner_uid, max_bytes=64_000)
+        if not data or b"\n" in data or b"\r" in data:
+            raise ConfigurationError(f"invalid_secret_format:{path}")
+        try:
+            return data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ConfigurationError(f"secret_not_utf8:{path}") from exc
+
+    def inbound_token(self) -> str:
+        return self._secret(self.inbound_token_file)
+
+    def callback_token(self) -> str:
+        return self._secret(self.callback_token_file)
+
+    def workspace_token(self) -> str | None:
+        return self._secret(self.workspace_token_file) if self.workspace_token_file else None
+
+    def responses_api_key(self) -> str | None:
+        return self._secret(self.responses_api_key_file) if self.responses_api_key_file else None
+
+    def openclaw_sync_token(self) -> str | None:
+        return self._secret(self.openclaw_sync_token_file) if self.openclaw_sync_token_file else None
+
+    def remote_runner_token(self, runner_id: str, scope: str) -> bytes:
+        for credential in self.remote_runner_credentials:
+            if credential.runner_id == runner_id:
+                if scope not in credential.scopes:
+                    raise ConfigurationError("remote_runner_scope_denied")
+                return self._secret(credential.token_file).encode("utf-8")
+        raise ConfigurationError("remote_runner_not_allowed")

services/aios_orchestrator_gateway/dispatch.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+import os
+import stat
+from typing import Any
+
+from .errors import DispatchError
+from .securefs import (
+    atomic_write_bytes,
+    atomic_write_bytes_shared,
+    ensure_secure_directory,
+    ensure_shared_directory,
+    read_secure_bytes,
+)
+
+
+SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+
+
+class DispatchSink:
+    """Reliable file-based dispatch adapter for existing OpenClaw/Codex watchers."""
+
+    def __init__(self, outbox_dir: Path, command_queue_dir: Path, contract_commit: str):
+        self.outbox_dir = Path(outbox_dir)
+        self.command_queue_dir = Path(command_queue_dir)
+        self.contract_commit = contract_commit
+        ensure_secure_directory(self.outbox_dir)
+        ensure_shared_directory(self.command_queue_dir)
+
+    def dispatch(self, record: dict[str, Any]) -> tuple[Path, Path]:
+        work_unit_id = record.get("work_unit_id")
+        event_id = record.get("event_id")
+        agent = record.get("assigned_agent")
+        payload_json = record.get("payload_json")
+        if (
+            not isinstance(work_unit_id, str)
+            or not SAFE_ID.fullmatch(work_unit_id)
+            or not isinstance(event_id, str)
+            or not SAFE_ID.fullmatch(event_id)
+            or agent not in {"openclaw", "codex"}
+            or not isinstance(payload_json, str)
+        ):
+            raise DispatchError("invalid_dispatch_record")
+        try:
+            work_unit = json.loads(payload_json)
+        except json.JSONDecodeError as exc:
+            raise DispatchError("invalid_dispatch_payload") from exc
+
+        project_key = record.get("project_key")
+        state_version = record.get("state_version")
+
+        envelope = {
+            "schema_version": 1,
+            "contract_commit": self.contract_commit,
+            "event_id": event_id,
+            "assigned_agent": agent,
+            "work_unit": work_unit,
+            "callback": {
+                "event_endpoint": "/v1/orchestrator/events",
+                "start_event_type": "work_unit_started",
+                "end_event_type": "work_unit_completed",
+            },
+        }
+        outbox_path = self.outbox_dir / "dispatched" / f"{work_unit_id}.json"
+        if agent == "codex":
+            if (
+                not isinstance(project_key, str)
+                or not SAFE_ID.fullmatch(project_key)
+                or not isinstance(state_version, int)
+                or state_version < 0
+            ):
+                raise DispatchError("invalid_dispatch_context")
+            required_checks = work_unit.get("required_checks", [])
+            execution_kind = (
+                "acceptance_probe"
+                if isinstance(required_checks, list) and "acceptance_probe" in required_checks
+                else "codex"
+            )
+            queue_value = {
+                "schema_version": 1,
+                "command_id": work_unit_id,
+                "project_key": project_key,
+                "work_unit_id": work_unit_id,
+                "contract_commit": self.contract_commit,
+                "state_version": state_version,
+                "execution": {
+                    "kind": execution_kind,
+                    "input": work_unit.get("instruction", ""),
+                },
+            }
+            # The Codex watcher polls the configured active directory itself.
+            queue_path = self.command_queue_dir / f"{work_unit_id}.json"
+        else:
+            queue_value = envelope
+            queue_path = self.command_queue_dir / agent / "pending" / f"{work_unit_id}.json"
+        ensure_secure_directory(outbox_path.parent)
+        ensure_shared_directory(queue_path.parent)
+
+        # Idempotent immutable payload: existing identical file is accepted.
+        self._write_idempotent_json(outbox_path, envelope, shared=False)
+        self._write_idempotent_json(queue_path, queue_value, shared=True)
+        return outbox_path, queue_path
+
+    @staticmethod
+    def _write_idempotent_json(path: Path, value: dict[str, Any], *, shared: bool) -> None:
+        payload = (json.dumps(value, indent=2, sort_keys=True) + "\n").encode()
+        try:
+            st = os.lstat(path)
+        except FileNotFoundError:
+            if shared:
+                atomic_write_bytes_shared(path, payload, mode=0o640)
+            else:
+                atomic_write_bytes(path, payload, mode=0o600)
+            return
+        if not stat.S_ISREG(st.st_mode):
+            raise DispatchError(f"dispatch_target_not_regular:{path.name}")
+        existing = read_secure_bytes(path, expected_uid=None, max_bytes=1_048_576)
+        if existing != payload:
+            raise DispatchError(f"dispatch_idempotency_conflict:{path.name}")

services/aios_orchestrator_gateway/errors.py

@@ -0,0 +1,37 @@
+class OrchestratorError(Exception):
+    """Base orchestration error."""
+
+
+class ConfigurationError(OrchestratorError):
+    """Unsafe or invalid configuration."""
+
+
+class ValidationError(OrchestratorError):
+    """Invalid event or decision."""
+
+
+class AuthenticationError(OrchestratorError):
+    """Authentication failed."""
+
+
+class ConflictError(OrchestratorError):
+    """Idempotency, lease, or optimistic concurrency conflict."""
+
+
+class TriggerError(OrchestratorError):
+    """Central model trigger failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        http_status: int | None = None,
+        category: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.http_status = http_status
+        self.category = category
+
+
+class DispatchError(OrchestratorError):
+    """Dispatch or synchronization output failed."""

services/aios_orchestrator_gateway/models.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import json
+import re
+from typing import Any
+
+from .errors import ValidationError
+
+
+OID_RE = re.compile(r"^[0-9a-f]{40}$")
+ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+AGENTS = {"openclaw", "codex", "gitea", "system", "workspace-agent"}
+EVENT_STATUSES = {"READY", "RUNNING", "PASS", "BLOCKED", "FAIL", "TIMEOUT", "NOT_EXECUTED"}
+VERDICTS = {"DISPATCH", "BLOCKED", "COMPLETE", "NOOP"}
+EXECUTORS = {"openclaw", "codex"}
+
+
+def req_str(value: dict[str, Any], key: str, pattern: re.Pattern[str] | None = None) -> str:
+    item = value.get(key)
+    if not isinstance(item, str) or not item:
+        raise ValidationError(f"invalid_{key}")
+    if pattern is not None and not pattern.fullmatch(item):
+        raise ValidationError(f"invalid_{key}")
+    return item
+
+
+def opt_oid(item: Any, key: str) -> str | None:
+    if item is None:
+        return None
+    if not isinstance(item, str) or not OID_RE.fullmatch(item):
+        raise ValidationError(f"invalid_{key}")
+    return item
+
+
+def string_list(value: dict[str, Any], key: str, limit: int) -> tuple[str, ...]:
+    raw = value.get(key)
+    if not isinstance(raw, list) or len(raw) > limit:
+        raise ValidationError(f"invalid_{key}")
+    result: list[str] = []
+    for item in raw:
+        if not isinstance(item, str) or not item or len(item) > 1024:
+            raise ValidationError(f"invalid_{key}")
+        result.append(item)
+    return tuple(result)
+
+
+@dataclass(frozen=True)
+class Event:
+    schema_version: int
+    project_key: str
+    contract_commit: str
+    event_id: str
+    source_agent: str
+    event_type: str
+    work_unit_id: str
+    status: str
+    state_version: int
+    implementation_commit: str | None = None
+    result_commit: str | None = None
+    blocker: str | None = None
+    evidence_refs: tuple[str, ...] = ()
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "Event":
+        allowed = {
+            "schema_version", "project_key", "contract_commit", "event_id",
+            "source_agent", "event_type", "work_unit_id", "status",
+            "state_version", "implementation_commit", "result_commit",
+            "blocker", "evidence_refs", "payload",
+        }
+        if not isinstance(value, dict) or set(value) - allowed:
+            raise ValidationError("invalid_event_fields")
+        if value.get("schema_version") != 1:
+            raise ValidationError("unsupported_event_schema")
+        source = req_str(value, "source_agent")
+        status = req_str(value, "status")
+        if source not in AGENTS:
+            raise ValidationError("invalid_source_agent")
+        if status not in EVENT_STATUSES:
+            raise ValidationError("invalid_event_status")
+        version = value.get("state_version")
+        if not isinstance(version, int) or version < 0:
+            raise ValidationError("invalid_state_version")
+        blocker = value.get("blocker")
+        if blocker is not None and (not isinstance(blocker, str) or len(blocker) > 512):
+            raise ValidationError("invalid_blocker")
+        payload = value.get("payload", {})
+        if not isinstance(payload, dict):
+            raise ValidationError("invalid_payload")
+        if len(json.dumps(payload, sort_keys=True).encode()) > 262_144:
+            raise ValidationError("payload_too_large")
+        return cls(
+            schema_version=1,
+            project_key=req_str(value, "project_key", ID_RE),
+            contract_commit=req_str(value, "contract_commit", OID_RE),
+            event_id=req_str(value, "event_id", ID_RE),
+            source_agent=source,
+            event_type=req_str(value, "event_type", ID_RE),
+            work_unit_id=req_str(value, "work_unit_id", ID_RE),
+            status=status,
+            state_version=version,
+            implementation_commit=opt_oid(value.get("implementation_commit"), "implementation_commit"),
+            result_commit=opt_oid(value.get("result_commit"), "result_commit"),
+            blocker=blocker,
+            evidence_refs=string_list(value, "evidence_refs", 64),
+            payload=payload,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": 1,
+            "project_key": self.project_key,
+            "contract_commit": self.contract_commit,
+            "event_id": self.event_id,
+            "source_agent": self.source_agent,
+            "event_type": self.event_type,
+            "work_unit_id": self.work_unit_id,
+            "status": self.status,
+            "state_version": self.state_version,
+            "implementation_commit": self.implementation_commit,
+            "result_commit": self.result_commit,
+            "blocker": self.blocker,
+            "evidence_refs": list(self.evidence_refs),
+            "payload": self.payload,
+        }
+
+    def canonical_json(self) -> str:
+        return json.dumps(self.to_dict(), separators=(",", ":"), sort_keys=True)
+
+    def digest(self) -> str:
+        return hashlib.sha256(self.canonical_json().encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class WorkUnit:
+    id: str
+    track_id: str
+    gate_id: str
+    primary_agent: str
+    fallback_agent: str
+    clean_base_commit: str
+    allowed_paths: tuple[str, ...]
+    required_checks: tuple[str, ...]
+    forbidden_operations: tuple[str, ...]
+    instruction: str
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "WorkUnit":
+        expected = {
+            "id", "track_id", "gate_id", "primary_agent", "fallback_agent",
+            "clean_base_commit", "allowed_paths", "required_checks",
+            "forbidden_operations", "instruction",
+        }
+        if not isinstance(value, dict) or set(value) != expected:
+            raise ValidationError("invalid_work_unit_fields")
+        primary = req_str(value, "primary_agent")
+        fallback = req_str(value, "fallback_agent")
+        if primary not in EXECUTORS or fallback not in EXECUTORS or primary == fallback:
+            raise ValidationError("invalid_agent_assignment")
+        instruction = req_str(value, "instruction")
+        if len(instruction.encode()) > 65_536:
+            raise ValidationError("instruction_too_large")
+        return cls(
+            id=req_str(value, "id", ID_RE),
+            track_id=req_str(value, "track_id", ID_RE),
+            gate_id=req_str(value, "gate_id", ID_RE),
+            primary_agent=primary,
+            fallback_agent=fallback,
+            clean_base_commit=req_str(value, "clean_base_commit", OID_RE),
+            allowed_paths=string_list(value, "allowed_paths", 128),
+            required_checks=string_list(value, "required_checks", 128),
+            forbidden_operations=string_list(value, "forbidden_operations", 64),
+            instruction=instruction,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "track_id": self.track_id,
+            "gate_id": self.gate_id,
+            "primary_agent": self.primary_agent,
+            "fallback_agent": self.fallback_agent,
+            "clean_base_commit": self.clean_base_commit,
+            "allowed_paths": list(self.allowed_paths),
+            "required_checks": list(self.required_checks),
+            "forbidden_operations": list(self.forbidden_operations),
+            "instruction": self.instruction,
+        }
+
+
+@dataclass(frozen=True)
+class Decision:
+    schema_version: int
+    project_key: str
+    contract_commit: str
+    event_id: str
+    expected_state_version: int
+    verdict: str
+    state_updates: dict[str, str]
+    next_work_units: tuple[WorkUnit, ...]
+    requires_human_input: bool
+    stop_reason: str | None
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "Decision":
+        expected = {
+            "schema_version", "project_key", "contract_commit", "event_id",
+            "expected_state_version", "verdict", "state_updates",
+            "next_work_units", "requires_human_input", "stop_reason",
+        }
+        if not isinstance(value, dict) or set(value) != expected:
+            raise ValidationError("invalid_decision_fields")
+        if value.get("schema_version") != 1:
+            raise ValidationError("unsupported_decision_schema")
+        version = value.get("expected_state_version")
+        if not isinstance(version, int) or version < 0:
+            raise ValidationError("invalid_expected_state_version")
+        verdict = req_str(value, "verdict")
+        if verdict not in VERDICTS:
+            raise ValidationError("invalid_verdict")
+        updates = value.get("state_updates")
+        normalized: dict[str, str] = {}
+        if isinstance(updates, dict):
+            update_items = [{"key": key, "value": item} for key, item in updates.items()]
+        elif isinstance(updates, list):
+            update_items = updates
+        else:
+            raise ValidationError("invalid_state_updates")
+        if len(update_items) > 128:
+            raise ValidationError("invalid_state_updates")
+        for update in update_items:
+            if not isinstance(update, dict) or set(update) != {"key", "value"}:
+                raise ValidationError("invalid_state_update")
+            key = update.get("key")
+            item = update.get("value")
+            if not isinstance(key, str) or not ID_RE.fullmatch(key):
+                raise ValidationError("invalid_state_update_key")
+            if not isinstance(item, str) or not item or len(item) > 256:
+                raise ValidationError("invalid_state_update_value")
+            if key in normalized:
+                raise ValidationError("duplicate_state_update_key")
+            normalized[key] = item
+        raw_units = value.get("next_work_units")
+        if not isinstance(raw_units, list) or len(raw_units) > 32:
+            raise ValidationError("invalid_next_work_units")
+        units = tuple(WorkUnit.from_dict(item) for item in raw_units)
+        human = value.get("requires_human_input")
+        if not isinstance(human, bool):
+            raise ValidationError("invalid_requires_human_input")
+        stop = value.get("stop_reason")
+        if stop is not None and (not isinstance(stop, str) or len(stop) > 512):
+            raise ValidationError("invalid_stop_reason")
+        if verdict == "DISPATCH" and not units:
+            raise ValidationError("dispatch_without_work_units")
+        if verdict != "DISPATCH" and units:
+            raise ValidationError("work_units_without_dispatch")
+        return cls(
+            schema_version=1,
+            project_key=req_str(value, "project_key", ID_RE),
+            contract_commit=req_str(value, "contract_commit", OID_RE),
+            event_id=req_str(value, "event_id", ID_RE),
+            expected_state_version=version,
+            verdict=verdict,
+            state_updates=normalized,
+            next_work_units=units,
+            requires_human_input=human,
+            stop_reason=stop,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": 1,
+            "project_key": self.project_key,
+            "contract_commit": self.contract_commit,
+            "event_id": self.event_id,
+            "expected_state_version": self.expected_state_version,
+            "verdict": self.verdict,
+            "state_updates": [
+                {"key": key, "value": value}
+                for key, value in sorted(self.state_updates.items())
+            ],
+            "next_work_units": [u.to_dict() for u in self.next_work_units],
+            "requires_human_input": self.requires_human_input,
+            "stop_reason": self.stop_reason,
+        }
+
+
+DECISION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": [
+        "schema_version", "project_key", "contract_commit", "event_id",
+        "expected_state_version", "verdict", "state_updates",
+        "next_work_units", "requires_human_input", "stop_reason",
+    ],
+    "properties": {
+        "schema_version": {"type": "integer", "const": 1},
+        "project_key": {"type": "string"},
+        "contract_commit": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
+        "event_id": {"type": "string"},
+        "expected_state_version": {"type": "integer", "minimum": 0},
+        "verdict": {"type": "string", "enum": sorted(VERDICTS)},
+        "state_updates": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["key", "value"],
+                "properties": {
+                    "key": {"type": "string"},
+                    "value": {"type": "string"}
+                }
+            }
+        },
+        "next_work_units": {
+            "type": "array",
+            "maxItems": 32,
+            "items": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": [
+                    "id", "track_id", "gate_id", "primary_agent",
+                    "fallback_agent", "clean_base_commit", "allowed_paths",
+                    "required_checks", "forbidden_operations", "instruction",
+                ],
+                "properties": {
+                    "id": {"type": "string"},
+                    "track_id": {"type": "string"},
+                    "gate_id": {"type": "string"},
+                    "primary_agent": {"type": "string", "enum": ["openclaw", "codex"]},
+                    "fallback_agent": {"type": "string", "enum": ["openclaw", "codex"]},
+                    "clean_base_commit": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
+                    "allowed_paths": {"type": "array", "items": {"type": "string"}},
+                    "required_checks": {"type": "array", "items": {"type": "string"}},
+                    "forbidden_operations": {"type": "array", "items": {"type": "string"}},
+                    "instruction": {"type": "string"},
+                },
+            },
+        },
+        "requires_human_input": {"type": "boolean"},
+        "stop_reason": {"type": ["string", "null"]},
+    },
+}

services/aios_orchestrator_gateway/recovery.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import socket
+
+from .store import Store
+
+
+@dataclass(frozen=True)
+class RecoverySettings:
+    database_path: Path
+    contract_commit: str
+    lease_seconds: int
+    max_retries: int
+    retry_after: int
+
+
+class PendingDecisionRecovery:
+    def __init__(self, settings: RecoverySettings, *, plan_only: bool = False):
+        self.settings = settings
+        self.store = Store(settings.database_path, read_only=plan_only)
+        self.owner = f"recovery-{socket.gethostname()}"
+
+    def plan(self) -> dict[str, int]:
+        return self.store.pending_decision_plan(
+            self.settings.contract_commit, self.settings.max_retries
+        )
+
+    def apply_one(self) -> str | None:
+        # Recovery never calls a model or replays a decision. It only advances
+        # durable callback bookkeeping under a lease.
+        return self.store.recover_one_pending(
+            owner=self.owner,
+            contract_commit=self.settings.contract_commit,
+            lease_seconds=self.settings.lease_seconds,
+            max_retries=self.settings.max_retries,
+            retry_after=self.settings.retry_after,
+        )

services/aios_orchestrator_gateway/remote_codex.py

@@ -0,0 +1,461 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import hmac
+import json
+from pathlib import Path
+import secrets
+import sqlite3
+import threading
+import time
+from typing import Any
+
+from .errors import AuthenticationError, ConfigurationError, ConflictError, ValidationError
+from .models import Decision, Event
+
+
+REMOTE_SCOPES = frozenset({"claim", "heartbeat", "decision", "fail"})
+
+
+def require_idempotency_key(value: str | None) -> str:
+    if not isinstance(value, str) or not 16 <= len(value) <= 128:
+        raise ValidationError("invalid_idempotency_key")
+    if any(ch not in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._:-" for ch in value):
+        raise ValidationError("invalid_idempotency_key")
+    return value
+
+
+def authenticate_runner(config: Any, runner_id: str | None, scope: str, header: str) -> bytes:
+    if scope not in REMOTE_SCOPES:
+        raise AuthenticationError("invalid_runner_scope")
+    if not isinstance(runner_id, str) or not runner_id:
+        raise AuthenticationError("missing_runner_id")
+    if not header.startswith("Bearer "):
+        raise AuthenticationError("missing_bearer")
+    try:
+        expected = config.remote_runner_token(runner_id, scope)
+    except ConfigurationError as exc:
+        raise AuthenticationError("runner_not_authorized") from exc
+    supplied = header[7:].encode("utf-8")
+    if not hmac.compare_digest(supplied, expected):
+        raise AuthenticationError("invalid_bearer")
+    return expected
+
+
+def validate_remote_decision(value: dict[str, Any], event: Event) -> Decision:
+    decision = Decision.from_dict(value)
+    if decision.contract_commit != event.contract_commit:
+        raise ValidationError("contract_version_mismatch")
+    if decision.event_id != event.event_id or decision.project_key != event.project_key:
+        raise ValidationError("event_identity_mismatch")
+    if decision.expected_state_version != event.state_version:
+        raise ValidationError("state_version_mismatch")
+    allowed = event.payload.get("allowed_work_unit_ids", [])
+    if not isinstance(allowed, list) or any(not isinstance(item, str) for item in allowed):
+        raise ValidationError("invalid_allowed_work_units")
+    if any(unit.id not in allowed for unit in decision.next_work_units):
+        raise ValidationError("work_unit_not_allowed")
+    return decision
+
+
+@dataclass(frozen=True)
+class RemoteLease:
+    job_id: str
+    runner_id: str
+    lease_version: int
+    lease_until: int
+    lease_token: str
+    event: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "job_id": self.job_id,
+            "runner_id": self.runner_id,
+            "lease_version": self.lease_version,
+            "lease_until": self.lease_until,
+            "lease_token": self.lease_token,
+            "event": self.event,
+        }
+
+
+class RemoteCodexBroker:
+    """Durable, exact-once remote decision job broker.
+
+    Lease credentials are derived with HMAC from the scoped runner token and
+    are never logged or persisted in plaintext.
+    """
+
+    def __init__(self, database_path: Path, *, contract_commit: str,
+                 lease_seconds: int, max_retries: int):
+        self.database_path = Path(database_path)
+        self.contract_commit = contract_commit
+        self.lease_seconds = lease_seconds
+        self.max_retries = max_retries
+        self._local = threading.local()
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.database_path, timeout=30, isolation_level=None)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA foreign_keys=ON")
+        connection.execute("PRAGMA busy_timeout=30000")
+        return connection
+
+    def _conn(self) -> sqlite3.Connection:
+        connection = getattr(self._local, "connection", None)
+        if connection is None:
+            connection = self._connect()
+            self._local.connection = connection
+        return connection
+
+    def close(self) -> None:
+        connection = getattr(self._local, "connection", None)
+        if connection is not None:
+            connection.close()
+            self._local.connection = None
+
+    def _initialize(self) -> None:
+        connection = self._connect()
+        try:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS remote_jobs (
+                    job_id TEXT PRIMARY KEY,
+                    event_id TEXT NOT NULL UNIQUE,
+                    event_digest TEXT NOT NULL,
+                    event_json TEXT NOT NULL,
+                    contract_commit TEXT NOT NULL,
+                    expected_state_version INTEGER NOT NULL,
+                    status TEXT NOT NULL,
+                    runner_id TEXT,
+                    lease_version INTEGER NOT NULL DEFAULT 0,
+                    lease_until INTEGER,
+                    attempts INTEGER NOT NULL DEFAULT 0,
+                    next_attempt_at INTEGER NOT NULL DEFAULT 0,
+                    failure_category TEXT,
+                    decision_digest TEXT,
+                    created_at INTEGER NOT NULL,
+                    updated_at INTEGER NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS idx_remote_jobs_claim
+                    ON remote_jobs(status, next_attempt_at, lease_until, created_at);
+                CREATE TABLE IF NOT EXISTS remote_requests (
+                    runner_id TEXT NOT NULL,
+                    scope TEXT NOT NULL,
+                    idempotency_key TEXT NOT NULL,
+                    request_digest TEXT NOT NULL,
+                    job_id TEXT,
+                    lease_version INTEGER,
+                    response_json TEXT NOT NULL,
+                    created_at INTEGER NOT NULL,
+                    PRIMARY KEY(runner_id, scope, idempotency_key)
+                );
+                CREATE TABLE IF NOT EXISTS remote_runners (
+                    runner_id TEXT PRIMARY KEY,
+                    last_seen_at INTEGER NOT NULL,
+                    last_scope TEXT NOT NULL
+                );
+                """
+            )
+        finally:
+            connection.close()
+
+    @staticmethod
+    def _digest(value: dict[str, Any]) -> str:
+        canonical = json.dumps(value, separators=(",", ":"), sort_keys=True).encode()
+        return hashlib.sha256(canonical).hexdigest()
+
+    @staticmethod
+    def _lease_token(token: bytes, job_id: str, runner_id: str,
+                     lease_version: int, claim_key: str) -> str:
+        message = f"{job_id}\0{runner_id}\0{lease_version}\0{claim_key}".encode()
+        return hmac.new(token, message, hashlib.sha256).hexdigest()
+
+    def enqueue(self, event: Event) -> tuple[bool, str]:
+        if event.contract_commit != self.contract_commit:
+            raise ConflictError("contract_version_mismatch")
+        now = int(time.time())
+        digest = event.digest()
+        connection = self._conn()
+        connection.execute("BEGIN IMMEDIATE")
+        try:
+            existing = connection.execute(
+                "SELECT event_digest FROM remote_jobs WHERE event_id=?", (event.event_id,)
+            ).fetchone()
+            if existing is not None:
+                if existing["event_digest"] != digest:
+                    raise ConflictError("remote_job_idempotency_conflict")
+                connection.execute("COMMIT")
+                return False, event.event_id
+            connection.execute(
+                """
+                INSERT INTO remote_jobs(
+                    job_id,event_id,event_digest,event_json,contract_commit,
+                    expected_state_version,status,next_attempt_at,created_at,updated_at
+                ) VALUES(?,?,?,?,?,?,'PENDING',?,?,?)
+                """,
+                (event.event_id, event.event_id, digest, event.canonical_json(),
+                 event.contract_commit, event.state_version, now, now, now),
+            )
+            connection.execute("COMMIT")
+            return True, event.event_id
+        except Exception:
+            connection.execute("ROLLBACK")
+            raise
+
+    def _touch_runner(self, connection: sqlite3.Connection, runner_id: str, scope: str, now: int) -> None:
+        connection.execute(
+            """
+            INSERT INTO remote_runners(runner_id,last_seen_at,last_scope) VALUES(?,?,?)
+            ON CONFLICT(runner_id) DO UPDATE SET
+                last_seen_at=excluded.last_seen_at,last_scope=excluded.last_scope
+            """, (runner_id, now, scope),
+        )
+
+    def _replay(self, connection: sqlite3.Connection, runner_id: str, scope: str,
+                key: str, digest: str) -> dict[str, Any] | None:
+        row = connection.execute(
+            "SELECT request_digest,response_json FROM remote_requests "
+            "WHERE runner_id=? AND scope=? AND idempotency_key=?",
+            (runner_id, scope, key),
+        ).fetchone()
+        if row is None:
+            return None
+        if row["request_digest"] != digest:
+            raise ConflictError("idempotency_payload_conflict")
+        return json.loads(row["response_json"])
+
+    def _record(self, connection: sqlite3.Connection, *, runner_id: str, scope: str,
+                key: str, digest: str, response: dict[str, Any], job_id: str | None,
+                lease_version: int | None, now: int) -> None:
+        connection.execute(
+            """
+            INSERT INTO remote_requests(
+                runner_id,scope,idempotency_key,request_digest,job_id,
+                lease_version,response_json,created_at
+            ) VALUES(?,?,?,?,?,?,?,?)
+            """,
+            (runner_id, scope, key, digest, job_id, lease_version,
+             json.dumps(response, separators=(",", ":"), sort_keys=True), now),
+        )
+
+    def claim(self, *, runner_id: str, idempotency_key: str,
+              runner_token: bytes) -> dict[str, Any]:
+        key = require_idempotency_key(idempotency_key)
+        request = {"runner_id": runner_id, "contract_commit": self.contract_commit}
+        digest = self._digest(request)
+        now = int(time.time())
+        connection = self._conn()
+        connection.execute("BEGIN IMMEDIATE")
+        try:
+            replay = self._replay(connection, runner_id, "claim", key, digest)
+            if replay is not None:
+                if replay == {"claimed": False}:
+                    connection.execute("COMMIT")
+                    return replay
+                row = connection.execute(
+                    "SELECT status,runner_id,lease_version,lease_until FROM remote_jobs WHERE job_id=?",
+                    (replay.get("job_id"),),
+                ).fetchone()
+                if row is not None and row["runner_id"] == runner_id and row["status"] == "LEASED":
+                    replay["lease_token"] = self._lease_token(
+                        runner_token, str(replay["job_id"]), runner_id,
+                        int(row["lease_version"]), key,
+                    )
+                    connection.execute("COMMIT")
+                    return replay
+                raise ConflictError("claim_replay_no_longer_active")
+
+            connection.execute(
+                """
+                UPDATE remote_jobs SET
+                    status=CASE WHEN attempts + 1 > ? THEN 'DEAD_LETTER' ELSE 'RETRY' END,
+                    attempts=attempts+1,runner_id=NULL,lease_until=NULL,
+                    failure_category='STALE_LEASE',next_attempt_at=?,updated_at=?
+                WHERE status='LEASED' AND lease_until < ?
+                """, (self.max_retries, now, now, now),
+            )
+            row = connection.execute(
+                """
+                SELECT * FROM remote_jobs
+                WHERE status IN ('PENDING','RETRY') AND next_attempt_at <= ?
+                  AND contract_commit=?
+                ORDER BY created_at LIMIT 1
+                """, (now, self.contract_commit),
+            ).fetchone()
+            self._touch_runner(connection, runner_id, "claim", now)
+            if row is None:
+                response = {"claimed": False}
+                self._record(connection, runner_id=runner_id, scope="claim", key=key,
+                             digest=digest, response=response, job_id=None,
+                             lease_version=None, now=now)
+                connection.execute("COMMIT")
+                return response
+            lease_version = int(row["lease_version"]) + 1
+            lease_until = now + self.lease_seconds
+            connection.execute(
+                """
+                UPDATE remote_jobs SET status='LEASED',runner_id=?,lease_version=?,
+                    lease_until=?,updated_at=? WHERE job_id=? AND status IN ('PENDING','RETRY')
+                """, (runner_id, lease_version, lease_until, now, row["job_id"]),
+            )
+            lease = RemoteLease(
+                job_id=str(row["job_id"]), runner_id=runner_id,
+                lease_version=lease_version, lease_until=lease_until,
+                lease_token=self._lease_token(runner_token, str(row["job_id"]), runner_id,
+                                              lease_version, key),
+                event=json.loads(row["event_json"]),
+            )
+            response = {"claimed": True, **lease.to_dict(), "claim_idempotency_key": key}
+            persisted_response = dict(response)
+            persisted_response.pop("lease_token")
+            self._record(connection, runner_id=runner_id, scope="claim", key=key,
+                         digest=digest, response=persisted_response, job_id=lease.job_id,
+                         lease_version=lease_version, now=now)
+            connection.execute("COMMIT")
+            return response
+        except Exception:
+            connection.execute("ROLLBACK")
+            raise
+
+    def _validate_lease(self, connection: sqlite3.Connection, *, job_id: str,
+                        runner_id: str, lease_token: str, claim_key: str,
+                        runner_token: bytes, allow_completed: bool = False) -> sqlite3.Row:
+        row = connection.execute("SELECT * FROM remote_jobs WHERE job_id=?", (job_id,)).fetchone()
+        if row is None:
+            raise ConflictError("remote_job_not_found")
+        if row["runner_id"] != runner_id:
+            raise ConflictError("remote_job_not_leased")
+        expected = self._lease_token(runner_token, job_id, runner_id,
+                                     int(row["lease_version"]), claim_key)
+        if not hmac.compare_digest(lease_token, expected):
+            raise AuthenticationError("invalid_lease_token")
+        if allow_completed and row["status"] == "COMPLETED":
+            return row
+        if row["status"] != "LEASED":
+            raise ConflictError("remote_job_not_leased")
+        if row["lease_until"] is None or int(row["lease_until"]) < int(time.time()):
+            raise ConflictError("remote_lease_expired")
+        return row
+
+    def heartbeat(self, *, job_id: str, runner_id: str, lease_token: str,
+                  claim_key: str, idempotency_key: str, runner_token: bytes) -> dict[str, Any]:
+        key = require_idempotency_key(idempotency_key)
+        request = {"job_id": job_id, "lease_token": lease_token, "claim_key": claim_key}
+        digest = self._digest(request); now = int(time.time())
+        connection = self._conn(); connection.execute("BEGIN IMMEDIATE")
+        try:
+            replay = self._replay(connection, runner_id, "heartbeat", key, digest)
+            if replay is not None:
+                connection.execute("COMMIT"); return replay
+            row = self._validate_lease(connection, job_id=job_id, runner_id=runner_id,
+                                       lease_token=lease_token, claim_key=claim_key,
+                                       runner_token=runner_token)
+            lease_until = now + self.lease_seconds
+            connection.execute("UPDATE remote_jobs SET lease_until=?,updated_at=? WHERE job_id=?",
+                               (lease_until, now, job_id))
+            self._touch_runner(connection, runner_id, "heartbeat", now)
+            response = {"accepted": True, "job_id": job_id,
+                        "lease_version": int(row["lease_version"]), "lease_until": lease_until}
+            self._record(connection, runner_id=runner_id, scope="heartbeat", key=key,
+                         digest=digest, response=response, job_id=job_id,
+                         lease_version=int(row["lease_version"]), now=now)
+            connection.execute("COMMIT"); return response
+        except Exception:
+            connection.execute("ROLLBACK"); raise
+
+    def event_for_submission(self, *, job_id: str, runner_id: str, lease_token: str,
+                             claim_key: str, runner_token: bytes) -> Event:
+        row = self._validate_lease(self._conn(), job_id=job_id, runner_id=runner_id,
+                                   lease_token=lease_token, claim_key=claim_key,
+                                   runner_token=runner_token, allow_completed=True)
+        return Event.from_dict(json.loads(row["event_json"]))
+
+    def complete(self, *, job_id: str, runner_id: str, idempotency_key: str,
+                 request_digest: str, decision_digest: str,
+                 state_version_after: int) -> dict[str, Any]:
+        key = require_idempotency_key(idempotency_key); now = int(time.time())
+        connection = self._conn(); connection.execute("BEGIN IMMEDIATE")
+        try:
+            replay = self._replay(connection, runner_id, "decision", key, request_digest)
+            if replay is not None:
+                connection.execute("COMMIT"); return replay
+            row = connection.execute("SELECT * FROM remote_jobs WHERE job_id=?", (job_id,)).fetchone()
+            if row is None:
+                raise ConflictError("remote_job_not_found")
+            if row["status"] == "COMPLETED":
+                if row["decision_digest"] != decision_digest:
+                    raise ConflictError("remote_decision_idempotency_conflict")
+            elif row["status"] == "LEASED" and row["runner_id"] == runner_id:
+                connection.execute(
+                    "UPDATE remote_jobs SET status='COMPLETED',decision_digest=?,lease_until=NULL,updated_at=? WHERE job_id=?",
+                    (decision_digest, now, job_id),
+                )
+            else:
+                raise ConflictError("remote_job_not_leased")
+            response = {"accepted": True, "job_id": job_id,
+                        "state_version": state_version_after, "completed": True}
+            self._record(connection, runner_id=runner_id, scope="decision", key=key,
+                         digest=request_digest, response=response, job_id=job_id,
+                         lease_version=int(row["lease_version"]), now=now)
+            self._touch_runner(connection, runner_id, "decision", now)
+            connection.execute("COMMIT"); return response
+        except Exception:
+            connection.execute("ROLLBACK"); raise
+
+    def fail(self, *, job_id: str, runner_id: str, lease_token: str, claim_key: str,
+             category: str, idempotency_key: str, runner_token: bytes,
+             retry_after: int) -> dict[str, Any]:
+        if not isinstance(category, str) or not category or len(category) > 64 or not category.replace("_", "").isalnum():
+            raise ValidationError("invalid_failure_category")
+        key = require_idempotency_key(idempotency_key)
+        request = {"job_id": job_id, "lease_token": lease_token,
+                   "claim_key": claim_key, "category": category}
+        digest = self._digest(request); now = int(time.time())
+        connection = self._conn(); connection.execute("BEGIN IMMEDIATE")
+        try:
+            replay = self._replay(connection, runner_id, "fail", key, digest)
+            if replay is not None:
+                connection.execute("COMMIT"); return replay
+            row = self._validate_lease(connection, job_id=job_id, runner_id=runner_id,
+                                       lease_token=lease_token, claim_key=claim_key,
+                                       runner_token=runner_token)
+            attempts = int(row["attempts"]) + 1
+            status = "DEAD_LETTER" if attempts > self.max_retries else "RETRY"
+            connection.execute(
+                """
+                UPDATE remote_jobs SET status=?,attempts=?,failure_category=?,
+                    next_attempt_at=?,runner_id=NULL,lease_until=NULL,updated_at=? WHERE job_id=?
+                """, (status, attempts, category, now + max(0, retry_after), now, job_id),
+            )
+            response = {"accepted": True, "job_id": job_id, "status": status,
+                        "attempts": attempts}
+            self._record(connection, runner_id=runner_id, scope="fail", key=key,
+                         digest=digest, response=response, job_id=job_id,
+                         lease_version=int(row["lease_version"]), now=now)
+            self._touch_runner(connection, runner_id, "fail", now)
+            connection.execute("COMMIT"); return response
+        except Exception:
+            connection.execute("ROLLBACK"); raise
+
+    def health_snapshot(self, *, healthy_within_seconds: int = 300) -> dict[str, Any]:
+        now = int(time.time())
+        connection = self._conn()
+        rows = connection.execute(
+            "SELECT runner_id,last_seen_at,last_scope FROM remote_runners ORDER BY runner_id"
+        ).fetchall()
+        counts = {
+            str(row["status"]): int(row["count"])
+            for row in connection.execute(
+                "SELECT status,COUNT(*) AS count FROM remote_jobs GROUP BY status"
+            ).fetchall()
+        }
+        return {
+            "channel": "remote_codex",
+            "contract_commit": self.contract_commit,
+            "healthy_runners": sum(1 for row in rows if now - int(row["last_seen_at"]) <= healthy_within_seconds),
+            "runner_count": len(rows),
+            "job_counts": counts,
+        }

services/aios_orchestrator_gateway/remote_tool.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import hmac
+import json
+import os
+from pathlib import Path
+import secrets
+import stat
+import time
+from typing import Any, Callable
+
+from .callback_transport import CallbackTransport
+from .errors import AuthenticationError, ValidationError
+from .models import Decision
+from .models import ID_RE, OID_RE
+from .securefs import ensure_secure_directory
+
+
+AUDIT_FIELDS = (
+    "callback_request_id", "event_id", "contract_commit", "received_at",
+    "schema_valid", "auth_valid", "forward_status", "state_version_after",
+)
+
+
+class CallbackAudit:
+    def __init__(self, path: Path):
+        self.path = path
+
+    def write(self, record: dict[str, Any]) -> None:
+        if set(record) != set(AUDIT_FIELDS):
+            raise ValueError("invalid_callback_audit_fields")
+        ensure_secure_directory(self.path.parent)
+        flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0)
+        fd = os.open(self.path, flags, 0o600)
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or stat.S_IMODE(info.st_mode) & 0o077:
+                raise ValueError("unsafe_callback_audit_file")
+            data = (json.dumps(record, separators=(",", ":"), sort_keys=True) + "\n").encode()
+            os.write(fd, data)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+
+
+class MinimalDecisionTool:
+    """Transport-neutral single-tool boundary; no generic GitOps operations."""
+
+    def __init__(
+        self,
+        transport: CallbackTransport,
+        *,
+        contract_commit: str,
+        access_token: str,
+        forward: Callable[[dict[str, Any]], dict[str, Any]],
+        audit: CallbackAudit,
+    ):
+        self.transport = transport
+        self.contract_commit = contract_commit
+        self.access_token = access_token
+        self.forward = forward
+        self.audit = audit
+
+    def tools(self) -> list[dict[str, Any]]:
+        return [self.transport.mcp_tool()] if self.transport.mode == "secure_mcp_tunnel" else []
+
+    def authenticate(self, authorization: str) -> None:
+        if not hmac.compare_digest(authorization, f"Bearer {self.access_token}"):
+            raise AuthenticationError("invalid_bearer")
+
+    def submit(self, payload: dict[str, Any], authorization: str) -> dict[str, Any]:
+        request_id = secrets.token_hex(16)
+        received_at = int(time.time())
+        schema_valid = False
+        auth_valid = False
+        raw_event_id = payload.get("event_id") if isinstance(payload, dict) else None
+        raw_contract = payload.get("contract_commit") if isinstance(payload, dict) else None
+        event_id = raw_event_id if isinstance(raw_event_id, str) and ID_RE.fullmatch(raw_event_id) else None
+        contract = raw_contract if isinstance(raw_contract, str) and OID_RE.fullmatch(raw_contract) else None
+        forward_status = "REJECTED"
+        state_version = None
+        try:
+            self.authenticate(authorization)
+            auth_valid = True
+            decision = Decision.from_dict(payload)
+            schema_valid = True
+            if decision.contract_commit != self.contract_commit:
+                raise ValidationError("contract_version_mismatch")
+            result = self.forward(decision.to_dict())
+            if result.get("accepted") is not True or not isinstance(result.get("state_version"), int):
+                raise ValidationError("invalid_forward_response")
+            forward_status = "202"
+            state_version = result["state_version"]
+            return result
+        finally:
+            self.audit.write({
+                "callback_request_id": request_id,
+                "event_id": event_id,
+                "contract_commit": contract,
+                "received_at": received_at,
+                "schema_valid": schema_valid,
+                "auth_valid": auth_valid,
+                "forward_status": forward_status,
+                "state_version_after": state_version,
+            })
+
+    def handle_mcp(self, request: dict[str, Any], authorization: str) -> dict[str, Any]:
+        self.authenticate(authorization)
+        method = request.get("method")
+        request_id = request.get("id")
+        if method == "tools/list":
+            return {"jsonrpc": "2.0", "id": request_id, "result": {"tools": self.tools()}}
+        if method != "tools/call":
+            raise ValidationError("unsupported_mcp_method")
+        params = request.get("params")
+        if not isinstance(params, dict) or params.get("name") != "submit_orchestration_decision":
+            raise ValidationError("unsupported_mcp_tool")
+        arguments = params.get("arguments")
+        if not isinstance(arguments, dict):
+            raise ValidationError("invalid_mcp_arguments")
+        result = self.submit(arguments, authorization)
+        return {"jsonrpc": "2.0", "id": request_id, "result": {"structuredContent": result}}