{"id":50709354,"url":"https://github.com/kagioneko/cpos-engine-zero","last_synced_at":"2026-06-09T14:02:03.495Z","repository":{"id":361212569,"uuid":"1253226021","full_name":"kagioneko/cpos-engine-zero","owner":"kagioneko","description":"Defensive, memory-governed AI agent runtime with Context Pointer OS, Task Tape, audit trails, and governance-first MCP.","archived":false,"fork":false,"pushed_at":"2026-06-05T19:47:02.000Z","size":23915,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T20:11:57.496Z","etag":null,"topics":["agent-runtime","ai-agent","context-pointer-os","devsecops","mcp","memory-system","security"],"latest_commit_sha":null,"homepage":"https://github.com/kagioneko/cpos-engine-zero","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kagioneko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T09:01:52.000Z","updated_at":"2026-06-05T19:47:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kagioneko/cpos-engine-zero","commit_stats":null,"previous_names":["kagioneko/cpos-engine-zero"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kagioneko/cpos-engine-zero","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kagioneko%2Fcpos-engine-zero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kagioneko%2Fcpos-engine-zero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kagioneko%2Fcpos-engine-zero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kagioneko%2Fcpos-engine-zero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kagioneko","download_url":"https://codeload.github.com/kagioneko/cpos-engine-zero/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kagioneko%2Fcpos-engine-zero/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34110012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-runtime","ai-agent","context-pointer-os","devsecops","mcp","memory-system","security"],"created_at":"2026-06-09T14:02:02.395Z","updated_at":"2026-06-09T14:02:03.487Z","avatar_url":"https://github.com/kagioneko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CPOS Engine-Zero\n\n## OSS Positioning\n\nCPOS Engine-Zero is a defensive, memory-governed AI agent runtime for safe autonomy: it separates relationship memory, task execution, and runtime state while routing risky work through review-gated, metadata-only pipelines.\n\nIt combines Context Pointer OS, append-only Task Tape, approval-gated remediation,\ntamper-evident audits, hardened API controls, governance-first MCP integration,\nand a sandbox retry/replan loop that learns from failures without persisting raw\nsecrets, raw diffs, or raw command output.\n\nCPOS also supports assisted autonomy: low-risk work can proceed autonomously, while\nsecret-touching, destructive, production, network, GitHub publishing, or low-confidence\nwork is routed through a human escalation protocol. See\n`docs/HUMAN_ESCALATION_PROTOCOL.md`.\n\nCurrent MCP support is intentionally conservative: connector definitions are\nstatically checked, reviewed, and registered; execution requests are dry-run /\nmetadata-only; capability probes create approval-gated plans. Real MCP tool\nexecution is not enabled by default.\n\nSee `SECURITY.md` and `OSS_RELEASE_CHECKLIST.md` before publishing or deploying.\n\nSee `docs/backlog/V0_1_1_BACKLOG.md` for post-v0.1.0 stabilization and v0.1.1 seed tasks.\nSee `docs/backlog/V0_1_2_BACKLOG.md` for parked post-RC ideas; implementation is not started.\nSee `docs/COGNITIVE_AGENT_OS_ARCHITECTURE.md` for the repo-family Cognitive Agent OS architecture draft.\nSee `docs/SENSOR_AND_GOAL_MANAGER_SPEC.md` for the first sensor/goal-manager spec draft.\nSee `docs/EVENT_BUS_AND_WORLD_MODEL_SPEC.md` for the event bus/world-model spec draft.\nSee `docs/TAPE_MEMORY_BRIDGE_DESIGN.md` for the metadata-only tape-memory resume-pointer bridge design.\nSee `docs/TAPE_MEMORY_REAL_WRITE_GATE_DESIGN.md` for the design-only real write safety gate; real writes are not enabled.\nSee `docs/TAPE_MEMORY_BACKEND_INTERFACE_DESIGN.md` for the design-only future backend adapter boundary; no real backend is implemented.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.tape_memory_mock_writer write --pointer-json pointer.json --output-dir /tmp/cpos-tape-memory-mock --confirm-write \"WRITE TAPE MEMORY RESUME POINTER\" --json` for a test-only local mock write; it is not a real tape-memory backend.\nSee `docs/VAULT_BACKED_NOTION_HELPER.md` for the Vault-backed Notion helper replacing old hardcoded scripts.\nSee `docs/ZENN_TO_NOTION_BRIDGE_DRY_RUN.md` for the safe dry-run replacement path for Zenn draft uploads to Notion.\nSee `docs/COGNITIVE_AGENT_OS_ROADMAP.md` for the doc-only implementation roadmap.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.world_model snapshot --json` for a read-only current-state snapshot. Add `--include-resume-pointer` to embed a compact tape-memory-style resume pointer without writing to tape-memory.\nAdd `--goal-store goals/goals.example.json` to include compact read-only goal store validation.\nAdd `--include-db-inventory` and/or `--include-android-emilia` to include compact optional sensor summaries.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.goals list --json` for read-only default goal state.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.goal_store validate --path goals/goals.example.json --json` for read-only goal store validation.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.goal_store summary --path goals/goals.example.json --json` for metadata-only merged goal summary/export output.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.resume_pipeline run --goal-store goals/goals.example.json --json` for the read-only integrated reflection → pointer → validation → dry-run write-plan bundle; add `--compact` for a smaller handoff/article-friendly summary, or `--scan-compact` to attach a secret-pattern scan gate for compact payloads.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.resume_pointer build --goal-store goals/goals.example.json --json` for a stdout-only resume pointer. Add `--reflection-json eval.json --include-handoff-digest` to include Reflection Evaluator metadata and a heading-only handoff digest. Use `cpos.resume_pointer validate --pointer-json pointer.json --json` and `cpos.resume_pointer write-plan --pointer-json pointer.json --json` for validation and dry-run tape-memory write planning.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.notion_vault_client page --source docs/NOTION_RESUME_PIPELINE_SUMMARY_2026_06_07.md --title \"Cognitive Agent OS / CPOS Resume Pipeline まとめ\" --json` for a Notion dry-run using Vault placeholders.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.notion_zenn_bridge bridge --article /home/mayutama/zenn/articles/cognitive-agent-os-safety-kernel.md --json` for a Zenn-to-Notion dry-run bridge.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.reflection_evaluator evaluate --json` for read-only proposed-action evaluation. Add `--goal-store goals/goals.example.json` to let the evaluator consume compact goal-store validation via the World Model.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.sensors.db_inventory_sensor --root . --json` for path-only DB inventory.\nRun `PYTHONPATH=. .venv/bin/python -m cpos.sensors.android_emilia_sensor --json` for observe-only Android Emilia bridge reference inventory.\nSee `docs/ANDROID_EMILIA_SENSOR_BRIDGE.md` for Android Emilia observe-only sensor bridge notes.\nSee `docs/DB_REFLECTION_SOURCE_INVENTORY.md` for DB inventory/reflection-source safety notes.\nSee `docs/V0_1_1_SUMMARY.md` for the completed v0.1.1 stabilization summary.\nSee `docs/V0_1_2_RESUME_PIPELINE_SUMMARY.md` for the post-RC resume pipeline summary.\nSee `docs/V0_1_2_READINESS_REVIEW.md` for v0.1.2 readiness review, `docs/NOTION_CREDENTIAL_ROTATE_RUNBOOK.md` for Notion credential rotation steps, and `docs/ZENN_COGNITIVE_AGENT_OS_PUBLISH_CHECKLIST.md` before publishing the Zenn draft.\nSee `RELEASE_NOTES_v0.1.1.md` and `GITHUB_RELEASE_DRAFT_v0.1.1.md` for v0.1.1 release prep drafts.\nSee `RELEASE_NOTES_v0.1.2.md` and `GITHUB_RELEASE_DRAFT_v0.1.2.md` for v0.1.2 release prep drafts; no tag/release is authorized by these drafts.\nSee `docs/ANNOUNCEMENT_COPY_v0.1.2.md` for post-release announcement/community copy and safer wording guidance.\nQuick v0.1.2 links: `https://github.com/kagioneko/cpos-engine-zero/releases/tag/v0.1.2`, `docs/V0_1_2_FINAL_RELEASE_RUNBOOK.md`, `docs/V0_1_2_READINESS_REVIEW.md`.\nSee `docs/POST_RELEASE_NOTION_SUMMARY_v0.1.2.md` for a Japanese Notion summary aligned with the Zenn wording.\nSee `docs/POST_RELEASE_SUMMARY_v0.1.2.md` for the short post-release summary that ties release, Zenn, and Notion together.\nSee `docs/V0_1_2_POST_RELEASE_CHECKLIST.md` for the immediate post-release checklist and guardrails.\nSee `docs/ANNOUNCEMENT_COPY_v0.1.0.md` for reusable post-release announcement/social copy.\nSee `docs/LOCAL_RUNTIME_FILE_INVENTORY.md` for ignored local/runtime artifact handling.\n\n## Quick Competitive Demo\n\nFor a local, metadata-only demo path, seed safe fixture data and inspect readiness:\n\n```bash\n# Create demo Task Tape events only; no tool execution, patch apply, commit, push, PR, or raw output storage.\ncurl -X POST https://\u003chost\u003e/demo/fixture -d '{\"confirm\":true,\"reason\":\"demo_capture\"}'\n\n# Inspect Fast Resume + External Agent Adapter + Human Escalation + Patch Generation + Ready-to-Run + Flow Graph readiness.\ncurl https://\u003chost\u003e/demo/readiness\n```\n\nThen open the dashboard and capture **Competitive Demo Readiness**, **External\nAgent Adapter Queue / Result Scoreboard**, **Human Escalation Queue**,\n**Patch Generation Reviews**, **Ready-to-Run Execution Reviews**, and **Sandbox\nAutonomy Flow Graph**. The same evidence appears in the generated report. For\ncapture order and safety rules, see `docs/DEMO_CAPTURE_GUIDE.md`.\n\nDemo evidence assets are metadata-only screenshots/panels; they show hashes,\ncounts, endpoint hints, statuses, and safety flags, not raw diffs, raw outputs,\nrequest bodies, or secrets.\n\n![Competitive Demo Readiness](docs/assets/demo/competitive-demo-readiness.png)\n\n| External Agent Adapter | Human Escalation | Ready-to-Run | Flow Graph |\n|---|---|---|---|\n| ![External Agent Adapter Queue](docs/assets/demo/external-agent-adapter-queue.png) | ![Human Escalation Queue](docs/assets/demo/human-escalation-queue.png) | ![Ready-to-Run Gate](docs/assets/demo/ready-to-run-gate.png) | ![Sandbox Flow Graph](docs/assets/demo/sandbox-flow-graph.png) |\n\n![Generated Report Snapshot](docs/assets/demo/report-demo-readiness.png)\n\n## Core Capabilities\n- Context Pointer OS for lightweight memory references and retrieval governance\n- Append-only Task Tape with checkpoints and rollback support\n- Approval-gated remediation for sensitive or irreversible actions\n- Tamper-evident hash-chained audit logs\n- Defensive MCP connector registry, review queue, dry-run execution, and capability probes\n- HMAC, bearer-token, HTTPS, mTLS fingerprint, IP allowlist, and rate-limit controls\n- Sandbox policy modes and security profile validation\n\n## Architecture at a Glance\n\n```text\nUser / Agent Input\n        |\n        v\n+---------------------+\n| Context Router      |  classify: relationship / task / hybrid / dangerous\n+---------------------+\n        |\n        +-------------------+-------------------+--------------------+\n        |                   |                   |                    |\n        v                   v                   v                    v\n+----------------+  +----------------+  +----------------+  +----------------+\n| Context Pointer|  | Task Tape      |  | State / Runtime|  | Security Gates |\n| OS             |  | append-only    |  | short-lived    |  | auth/policy    |\n| relation refs  |  | rollback/audit |  | no persistence |  | review first   |\n+----------------+  +----------------+  +----------------+  +----------------+\n        |                   |                   |                    |\n        +-------------------+-------------------+--------------------+\n                            |\n                            v\n+-----------------------------------------------------------------------+\n| Review-Gated Execution Pipeline                                      |\n| PR dry-run -\u003e diff review -\u003e sandbox plan -\u003e execution review -\u003e run |\n| -\u003e result metadata -\u003e retry review -\u003e replan template -\u003e diff intake |\n+-----------------------------------------------------------------------+\n                            |\n                            v\n+-----------------------------------------------------------------------+\n| Persistence Boundary                                                  |\n| Store: hashes, sizes, statuses, pointers, audit metadata              |\n| Never store: secrets, raw stdout/stderr, raw diff, request bodies     |\n+-----------------------------------------------------------------------+\n```\n\nCPOS keeps relationship/context memory, task execution history, and short-lived\nruntime state separate. Cross-layer context is injected only through governed\npointers and review-gated Task Tape events, which keeps long-term memory from\nbeing polluted by failed commands or transient execution state.\n\n## Safe Autonomy Demo Flow\n\nCPOS Engine-Zero is designed around a conservative autonomy loop: every risky\nstep is review-gated, raw secrets and raw command outputs stay out of persistent\nlogs, and failed runs turn into metadata-only retry/replan artifacts instead of\nblind automatic reruns.\n\n```text\nGitHub PR dry-run\n  -\u003e GitHub diff review\n  -\u003e Sandbox patch plan\n  -\u003e Sandbox execution review\n  -\u003e Isolated sandbox run\n  -\u003e Completed result metadata\n  -\u003e Retry review\n  -\u003e Replan template\n  -\u003e Diff intake checklist\n  -\u003e Auto Fix Candidate\n  -\u003e Diff Review Draft\n  -\u003e Human-supplied GitHub diff review\n  -\u003e Back to sandbox execution\n```\n\nKey safety properties:\n\n- No branch, commit, push, or PR is created by these planning/review stages.\n- Raw diff text is accepted for review/run input but is not persisted in Task Tape.\n- Raw stdout/stderr are never persisted; only hashes, sizes, exit codes, and status flags are stored.\n- Validation commands are allowlisted and shell metacharacters are rejected.\n- `local-dev` runner mode requires explicit `CPOS_ALLOW_LOCAL_DEV_RUN=true`.\n- Failure routing uses `patch_apply`, `validation_command`, `sandbox_unavailable`, and `policy_rejected`.\n- Runtime state, caches, virtualenvs, and secret files are ignored and must not be committed.\n\nMinimal metadata-only loop:\n\n```bash\ncurl -X POST https://\u003chost\u003e/github/pr-dry-runs \\\n  -d '{\"repo\":\"kagioneko/cpos-engine-zero\",\"title\":\"Fix behavior\",\"summary\":\"metadata only\",\"files\":[\"README.md\"]}'\ncurl -X POST https://\u003chost\u003e/github/pr-dry-runs/\u003cpr_task_id\u003e/create-diff-review \\\n  -d '{\"diff_text\":\"...\",\"changed_files\":[\"README.md\"],\"validation_commands\":[\"pytest -q tests/test_report.py\"]}'\ncurl -X POST https://\u003chost\u003e/github/diff-reviews/\u003cdiff_task_id\u003e/create-sandbox-plan -d '{}'\ncurl -X POST https://\u003chost\u003e/sandbox/patch-plans/\u003cpatch_task_id\u003e/create-execution-review -d '{}'\ncurl -X POST https://\u003chost\u003e/sandbox/executions/\u003cexec_task_id\u003e/run \\\n  -d '{\"diff_text\":\"...\",\"validation_commands\":[\"pytest -q tests/test_report.py\"],\"runner_mode\":\"strict\"}'\ncurl -X POST https://\u003chost\u003e/sandbox/executions/\u003cexec_task_id\u003e/create-retry-review \\\n  -d '{\"reason\":\"validation_failed\"}'\ncurl -X POST https://\u003chost\u003e/sandbox/execution-retries/\u003cretry_task_id\u003e/create-replan-template \\\n  -d '{\"reason\":\"make_new_plan\"}'\ncurl -X POST https://\u003chost\u003e/sandbox/replan-templates/\u003creplan_task_id\u003e/create-diff-intake \\\n  -d '{\"reason\":\"next_diff\"}'\n```\n\nThe dashboard surfaces each queue/result: PR dry-run, diff review, sandbox plan,\nexecution review, completed execution result, retry review, replan template, diff\nintake, auto fix candidate, diff review draft, and sandbox flow graph.\n\n### Autonomy Loop Demo Panel\n\nThe dashboard includes an **Autonomy Loop Demo Panel** that compresses the safe\nexecution loop into one screen for demos and operations. It shows counts and next\nactions for:\n\n1. Diff Draft\n2. GitHub Diff Review\n3. Sandbox Execution Review\n4. Execution Result\n5. Retry/Replan\n6. Flow Graph\n\nThe panel is intentionally status-only. It does not create branches, apply\npatches to the live repository, run commands automatically, commit, push, create\nPRs, persist raw diff text, or persist raw stdout/stderr. It highlights the same\nsafety flags as the underlying pipeline: `metadata_only=true`,\n`raw_diff_stored=false`, `raw_outputs_stored=false`, `live_repo_patch=false`,\n`commit_created=false`, `pushed=false`, and `pr_created=false`.\n\nFor release screenshots or GIFs, follow `docs/DEMO_CAPTURE_GUIDE.md` so captured assets stay metadata-only and secret-free.\n\n### Competitive Demo Readiness\n\nCPOS exposes a metadata-only competitive demo readiness endpoint and dashboard/report\nsection that shows the full safe loop in one place:\n\n```bash\ncurl https://\u003chost\u003e/demo/readiness\ncurl -X POST https://\u003chost\u003e/demo/fixture -d '{\"confirm\":true,\"reason\":\"demo_capture\"}'\n```\n\n`/demo/fixture` creates a metadata-only demo chain for screenshots and readiness\nchecks. It requires `confirm=true` and writes Task Tape review/result events only;\nit does not execute tools, apply patches, mutate the live repo, commit, push,\ncreate PRs, or store raw diffs/outputs.\n\nThe readiness snapshot covers Fast Resume, MCP-reviewed tape memory, Human\nEscalation, Patch Generation Review, generated-diff validation harness,\nReady-to-Run Gate, Sandbox Flow Graph, and report evidence. It is presentation\nonly: it never approves reviews, executes tools, applies patches, commits, pushes,\ncreates PRs, or stores raw diffs, raw stdout/stderr, request bodies, checkpoints,\nhandoff bodies, tokens, or secret values.\n\n\n## External Agent Adapter MVP\n\nCPOS can also sit beside another agent as a defensive runtime/safety layer.\nExternal agents submit metadata-rich action contracts; CPOS stores only hashes,\nsizes, counters, and review status, then routes risky actions into the existing\nHuman Escalation queue.\n\n```bash\ncurl -X POST https://\u003chost\u003e/agent-adapter/intake \\\n  -d '{\"agent_name\":\"codex-or-hermes\",\"event_type\":\"command_request\",\"commands\":[\"pytest tests -q\"],\"changed_files\":[\"README.md\"],\"metadata\":{\"risk\":\"medium\"}}'\n\ncurl https://\u003chost\u003e/agent-adapter/actions\n\n# External agents can also report execution results as metadata-only summaries.\ncurl -X POST https://\u003chost\u003e/agent-adapter/intake \\\n  -d '{\"agent_name\":\"codex-or-hermes\",\"event_type\":\"execution_result\",\"execution_result\":{\"status\":\"failed\",\"output_redacted\":true},\"metadata\":{\"success\":false,\"exit_code\":1,\"failure_kind\":\"validation_command\"}}'\ncurl https://\u003chost\u003e/agent-adapter/execution-results\ncurl https://\u003chost\u003e/human-escalations\n```\n\nAdapter safety defaults: no raw request body persistence, no raw diff\npersistence, no raw stdout/stderr persistence, no secret values, and no automatic\nexecution. Approval records the contract only; execution remains a separately\ngated pipeline decision. Execution-result reports are scoreboard inputs only and\nstill store no raw stdout/stderr. Schema validation rejects malformed adapter\npayloads before Task Tape persistence. Secret-free payload examples are available\nin `examples/payloads/` for command requests, proposed diffs, execution results,\nand raw-output rejection checks. Start with\n`docs/EXTERNAL_AGENT_5_MIN_GUIDE.md`, then use\n`docs/AGENT_ADAPTER_INTEGRATION.md`, `docs/AGENT_ADAPTER_SCHEMA.md`, and\n`examples/agent_adapter_client.py` for deeper integration details.\n\n## Human Escalation Queue\n\nRisky review stages now attach a metadata-only Human Escalation decision to their\nTask Tape review event. The queue is available through both the API and dashboard:\n\n```bash\ncurl https://\u003chost\u003e/human-escalations\n```\n\nThe queue covers GitHub PR dry-runs, GitHub diff reviews, MCP execution/probe\nreviews, sandbox patch plans, sandbox execution reviews, sandbox retry reviews,\nand patch generation reviews. It stores only policy metadata such as review type,\nseverity, reasons, recommended mode, owning review list endpoints, approve/reject\nendpoint hints, and sandbox flow graph hints when lineage is available. It does\n**not** persist secret values, raw request bodies, raw diff text, raw stdout/stderr,\ncheckpoint contents, or raw handoff bodies.\n\nDashboard actions route approval/rejection back through the owning pipeline endpoint\n(for example `/github/pr-dry-runs/\u003ctask_id\u003e/approve` or\n`/sandbox/executions/\u003ctask_id\u003e/reject`) rather than creating a second approval\nauthority. GitHub publishing, destructive operations, secrets, production changes,\nnetwork exposure, and low-confidence tasks remain assisted-autonomy gates.\n\n## HMAC API Client Helpers\n\nCPOS API calls can use HMAC-signed requests with key rotation. Secrets must come from Vault/secret volumes; do not hardcode them in code, `.env`, crontab, or docs.\n\n### CLI signing helper\n\n```bash\npython3 -m cpos.auth_cli sign GET 'https://\u003chost\u003e/tasks?limit=1' \\\n  --registry-file /run/secrets/cpos_hmac_keys.json \\\n  --key-id 2026-05-active \\\n  --agent-id CodingAgent \\\n  --curl\n```\n\n### Python API client\n\n```python\nfrom cpos.api_client import CPOSClient\n\nclient = CPOSClient(\n    \"https://\u003chost\u003e\",\n    registry_file=\"/run/secrets/cpos_hmac_keys.json\",\n    key_id=\"2026-05-active\",\n    agent_id=\"CodingAgent\",\n)\n\nsummary = client.get_json(\"/tasks\")\nrollback = client.post_json(\"/tasks/rollback-latest\", {\"target\": \"workspace/app.py\", \"confirm\": True})\n```\n\n`CPOSClient` requires HTTPS base URLs, signs every request, supports key registry rotation, and never returns or logs secret material. Put query strings directly in the path so exact query bytes are signed.\n\n## Network Policy Middleware\n\nOptional entrance hardening is available before API auth runs.\n\n### IP allowlist\n\n```bash\nexport CPOS_IP_ALLOWLIST=\"203.0.113.0/24,2001:db8::/32\"\nexport CPOS_TRUST_PROXY_HEADERS=true\n```\n\nWhen `CPOS_TRUST_PROXY_HEADERS=true`, the first `X-Forwarded-For` address is used. Only enable this behind a trusted reverse proxy/load balancer.\n\n### Rate limiting\n\n```bash\nexport CPOS_RATE_LIMIT_ENABLED=true\nexport CPOS_RATE_LIMIT_REQUESTS=60\nexport CPOS_MUTATION_RATE_LIMIT_REQUESTS=10\nexport CPOS_RATE_LIMIT_WINDOW_SECONDS=60\n```\n\nMutation requests use the stricter mutation bucket. Rejections return `429 rate_limited` with `Retry-After` and `X-RateLimit-*` headers. IP denials and rate-limit events are written to the Security Audit Trail without request bodies or secrets.\n\n### mTLS / client certificate fingerprint gate\n\nWhen TLS/mTLS is terminated by a trusted reverse proxy, CPOS can require the proxy-provided client certificate fingerprint before API auth runs.\n\n```bash\nexport CPOS_REQUIRE_CLIENT_CERT=true\nexport CPOS_CLIENT_CERT_FINGERPRINTS_FILE=/run/secrets/cpos_client_fingerprints.txt\nexport CPOS_CLIENT_CERT_FINGERPRINT_HEADER=X-SSL-Client-SHA256\nexport CPOS_CLIENT_CERT_POLICY_MODE=enforce\n```\n\n`CPOS_CLIENT_CERT_FINGERPRINTS_FILE` may contain comma-separated or newline-separated SHA-256 fingerprints. Colons are ignored. If the file is missing, enforce mode fails closed. Set `CPOS_CLIENT_CERT_POLICY_MODE=audit` to log violations without blocking; useful for rollout so security can be tightened without killing operational freedom.\n\nRecommended layered deployment:\n\n1. Public edge / load balancer terminates HTTPS.\n2. Reverse proxy enforces real mTLS and forwards only sanitized fingerprint headers.\n3. CPOS verifies fingerprint allowlist, IP allowlist, rate limit, HMAC signature, scope, approval gates, and hash-chained audit logs.\n\n## Sandbox Policy Modes\n\nVerification runs in a hardened Docker sandbox by default.\n\n```bash\nexport CPOS_SANDBOX_MODE=strict\n```\n\nModes:\n\n| Mode | Behavior |\n| --- | --- |\n| `strict` | Docker required. If Docker is unavailable, fail closed. Recommended for production. |\n| `permissive` | Docker preferred. If unavailable, local fallback is allowed and marked in result metadata. |\n| `local-dev` | Explicit local execution for development only. |\n\nDocker hardening flags include:\n\n- `--read-only`\n- `--cap-drop ALL`\n- `--security-opt no-new-privileges`\n- `--network none`\n- `--memory` / `--cpus`\n- `--pids-limit`\n- `--tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m`\n- project mounted read-only at `/app`\n\nTunable limits:\n\n```bash\nexport CPOS_SANDBOX_MEMORY=256m\nexport CPOS_SANDBOX_CPUS=0.5\nexport CPOS_SANDBOX_PIDS_LIMIT=128\n```\n\nThis keeps production safe while preserving developer freedom through explicit mode selection.\n\n## Security Profile Presets\n\nUse profiles to switch security posture without deleting capabilities.\n\n```bash\nexport CPOS_SECURITY_PROFILE=dev\n# or: audit / hardened\n```\n\nProfiles set defaults only when a variable is not already explicitly set.\n\n| Profile | Intent |\n| --- | --- |\n| `dev` | High freedom. Local sandbox allowed, API auth/rate-limit/client-cert gates off by default. |\n| `audit` | Observation-first. Permissive sandbox and audit-mode client-cert policy; avoids fail-closed secret requirements. |\n| `hardened` | Production fail-closed. HTTPS, API auth, HMAC auth, client-cert gate, strict sandbox, rate limiting, and approval gates on by default. |\n\nInspect active posture:\n\n```http\nGET https://\u003chost\u003e/security-profile\n```\n\nIf API auth is enabled, this endpoint requires `read:integrity`.\n\n### Hardened profile validation\n\n`GET /security-profile` also returns validation results. In `hardened` profile it checks for common false-sense-of-security gaps:\n\n- HTTPS enforcement enabled\n- API/HMAC auth enabled\n- HMAC secret or key registry file exists\n- client certificate fingerprint file exists\n- strict sandbox selected\n- Docker available for strict sandbox\n- rate limiting enabled\n\nThis is advisory unless the specific runtime gate itself fails closed. It helps keep security strong without hiding which control is missing.\n\n### Security dashboard/report card\n\nThe dashboard and generated report surface profile validation status:\n\n- profile name\n- OK/CHECK status\n- number of validation failures\n- first failure names\n\nThis makes `hardened` misconfiguration visible without disabling lower-friction `dev` or `audit` workflows.\n\n## Preflight Check CLI\n\nRun deployment checks before starting CPOS:\n\n```bash\npython3 -m cpos.preflight --profile hardened\npython3 -m cpos.preflight --profile hardened --json\n```\n\nChecks include:\n\n- effective security profile\n- hardened validation failures\n- Docker availability for strict sandbox\n- HMAC key registry parse/load\n- HMAC key secret file readability\n- client certificate fingerprint file presence\n\nThe command exits non-zero when blocking validation failures are found. Use `--skip-docker` when validating config on a host without Docker.\n\n## Hardened Deployment Bundle\n\nTemplate-only hardened deployment files live in `deploy/hardened/`.\n\n```text\ndeploy/hardened/\n├── README.md\n├── hardened.env.example\n├── cpos-hmac-keys.json.example\n├── cpos-client-fingerprints.txt.example\n├── cpos-engine-zero.service.example\n└── nginx-mtls.conf.example\n```\n\nThese examples do not install services or write real secrets. Use them as a starting point, render runtime secret files from Vault/secret volumes, then run:\n\n```bash\npython3 -m cpos.preflight --profile hardened\n```\n\nbefore starting CPOS.\n\n## Vault Secret Render Helper\n\nTemplate/CLI support is available for rendering runtime secret files from Vault without printing values.\n\nShell template:\n\n```bash\ndeploy/hardened/vault-render-secrets.example.sh\n```\n\nManifest-based helper:\n\n```bash\npython3 -m cpos.vault_render deploy/hardened/vault-render-manifest.example.json --dry-run\npython3 -m cpos.vault_render deploy/hardened/vault-render-manifest.example.json --json\n```\n\nThe helper writes files with `0600` permissions into a `0700` secret directory, rejects path traversal, and does not include secret values in its result output. Ensure `VAULT_ADDR` and `VAULT_CACERT` are set before real rendering.\n\n## CI / Preflight Workflow Template\n\nA non-active GitHub Actions example lives at:\n\n```text\ndeploy/hardened/github-actions/cpos-hardened-preflight.example.yml\n```\n\nIt is intentionally outside `.github/workflows/` so it will not run until copied there intentionally.\n\nThe template runs:\n\n- secret pattern scan via `python -m cpos.secret_scan`\n- Vault render dry-run\n- hardened preflight config check\n- unit tests\n- report generation\n\nSecret scanner:\n\n```bash\npython3 -m cpos.secret_scan . --json\n```\n\nThe scanner reports file, line, and pattern name only; it does not print matched secret values.\n\nPre-publish safety gate:\n\n```bash\nPYTHONPATH=. .venv/bin/python -m cpos.prepublish_check --json\n```\n\nThis non-destructive gate combines `cpos.github_publish_guard`, `cpos.release_check`,\nand `cpos.secret_scan`. It confirms the expected GitHub remote, checks publish\nboundaries, scans for high-risk secret patterns without printing values, and reports\nfailures before any staging, commit, push, deletion, or history rewrite.\n\nA friendly explanation of the command and failure names lives in\n`docs/PUBLISH_SAFETY_USER_GUIDE.md`.\n\n## Vault Migration Guide\n\nSecret artifact migration documentation lives at:\n\n```text\ndeploy/hardened/VAULT_MIGRATION_GUIDE.md\ndeploy/hardened/SECRET_ARTIFACT_INVENTORY.md\n```\n\nThese are non-destructive guides/checklists only. They do not move, delete,\noverwrite, or upload files. Use them to inventory local key/cert/token artifacts,\nstore values in Vault, render runtime secret files, run preflight, then request\nexplicit approval before any cleanup.\n\n## Secret Inventory Metadata CLI\n\nTrack Vault migration status without storing secret values:\n\n```bash\npython3 -m cpos.secret_inventory add certs/key.pem \\\n  --type tls_private_key \\\n  --vault-path secret/cpos/tls \\\n  --field private_key\n\npython3 -m cpos.secret_inventory mark certs/key.pem --status stored_in_vault\npython3 -m cpos.secret_inventory list --json\npython3 -m cpos.secret_inventory verify --json\n```\n\nThe inventory is hash-chained JSONL metadata. It records paths, Vault references,\nfields, owners, status, and notes, but never secret values.\n\n## Secret Inventory Dashboard / Report\n\nSecret migration metadata is visible in both `/dashboard` and generated reports.\n\n- `/security-profile` returns `secret_inventory` summary.\n- Dashboard shows artifact count and status distribution.\n- `hackathon_report.html` renders recent inventory records.\n\nSet a custom inventory path if needed:\n\n```bash\nexport CPOS_SECRET_INVENTORY_PATH=/path/to/secret_inventory.jsonl\n```\n\nThe inventory stores metadata only and remains hash-chained for tamper evidence.\n\n## Multi-Agent Handoff Export\n\nExport a sanitized handoff bundle for the next session or another agent without\npassing raw logs, checkpoint contents, request bodies, tokens, or private keys.\n\n```bash\npython3 -m cpos.handoff_export --format json\npython3 -m cpos.handoff_export --format markdown --output handoff.md\n```\n\nThe bundle includes security profile validation, hash-chain integrity heads,\nPointer OS summaries, Task Tape summaries, Secret Inventory status, and a\ntruncated `NEXT_HANDOFF.md` excerpt. It is designed as a cross-agent context\nseed, not as a secret backup.\n\n## Signed / Importable Handoff Receiver\n\nSign, verify, and safely import a sanitized handoff bundle as a review-gated\nPointer OS summary. Secrets are read from Vault-rendered files only; they are\nnever printed.\n\n```bash\npython3 -m cpos.handoff_export --format json --output handoff.json\npython3 -m cpos.handoff_receiver sign handoff.json \\\n  --secret-file /run/cpos-secrets/handoff_hmac \\\n  --key-id handoff-v1 \\\n  --output handoff.signed.json\npython3 -m cpos.handoff_receiver verify handoff.signed.json \\\n  --secret-file /run/cpos-secrets/handoff_hmac \\\n  --key-id handoff-v1\npython3 -m cpos.handoff_receiver import handoff.signed.json \\\n  --secret-file /run/cpos-secrets/handoff_hmac \\\n  --key-id handoff-v1 \\\n  --require-signature\n```\n\nImport is dry-run by default. Add `--apply` to create a single\n`handoff_summary` pointer with `retrieval_rule=handoff_review_required`. The\nreceiver imports metadata and counts only; it does not store the raw handoff\nbody, checkpoint contents, or NEXT excerpt inside Pointer OS.\n\n## Handoff Inbox / Review Queue\n\nImported `handoff_summary` pointers stay review-gated until approved.\n\n```bash\npython3 -m cpos.handoff_inbox list\npython3 -m cpos.handoff_inbox approve ptr://handoff/\u003cid\u003e --reviewer AgentReviewer\npython3 -m cpos.handoff_inbox reject ptr://handoff/\u003cid\u003e --reason stale_or_untrusted\n```\n\nHTTP API:\n\n```text\nGET  /handoff-inbox?status=pending|approved|rejected|all\nPOST /handoff-inbox/\u003cpointer_id\u003e/approve  {\"confirm\": true, \"reason\": \"...\"}\nPOST /handoff-inbox/\u003cpointer_id\u003e/reject   {\"reason\": \"...\"}\n```\n\nScopes: `read:reviews` for listing and `write:reviews` for approve/reject.\nApproval changes the pointer retrieval rule to `handoff_approved`; rejection\ninvalidates the pointer with `handoff_rejected`. Raw handoff bodies are still not\nstored in Pointer OS.\n\n## Handoff Promotion Rules\n\nApproved handoff summaries can be promoted into a safe, review-gated plan before\nany retrieval or task continuation happens.\n\n```bash\npython3 -m cpos.handoff_promotion plan ptr://handoff/\u003cid\u003e\npython3 -m cpos.handoff_promotion promote ptr://handoff/\u003cid\u003e --reviewer AgentReviewer\n```\n\nHTTP API:\n\n```text\nGET  /handoff-inbox/\u003cpointer_id\u003e/promotion-plan\nPOST /handoff-inbox/\u003cpointer_id\u003e/promote  {\"confirm\": true, \"reason\": \"...\"}\n```\n\nPromotion requires an approved handoff. The generated plan explicitly blocks raw\nhandoff bodies, checkpoint contents, request bodies, secret values, and unreviewed\ncode patches. Applying promotion creates a `handoff_promotion_plan` pointer with\n`retrieval_rule=handoff_promotion_review_required`; it does not execute tasks or\nimport raw context.\n\n## Promotion Plan Executor\n\nPromotion plans are not executed directly. They can be converted into a fresh\nTask Tape review cycle for safe work resumption.\n\n```bash\npython3 -m cpos.promotion_executor create-review ptr://handoff-promotion/\u003cid\u003e\npython3 -m cpos.promotion_executor list\npython3 -m cpos.promotion_executor approve task_\u003cid\u003e\npython3 -m cpos.promotion_executor reject task_\u003cid\u003e --reason not_now\n```\n\nHTTP API:\n\n```text\nPOST /handoff-inbox/\u003cpromotion_pointer_id\u003e/execute-plan  {\"confirm\": true}\nGET  /handoff-executions\nPOST /handoff-executions/\u003ctask_id\u003e/approve               {\"confirm\": true}\nPOST /handoff-executions/\u003ctask_id\u003e/reject                {\"reason\": \"...\"}\n```\n\nThe executor creates `review_required` Task Tape events with\n`review_type=handoff_promotion_execution`. Approval only marks the resume plan as\nready and appends `handoff_promotion_execution_ready`; it does not automatically\nrun code or import raw context.\n\n## Execution Resume Planner\n\nApproved handoff execution reviews can produce small, scoped next-action\nproposals. These proposals are still review-gated and never run automatically.\n\n```bash\npython3 -m cpos.resume_planner plan task_\u003cid\u003e\npython3 -m cpos.resume_planner create-review task_\u003cid\u003e\npython3 -m cpos.resume_planner list\npython3 -m cpos.resume_planner approve task_\u003cid\u003e --action-id inspect_promotion_plan\n```\n\nHTTP API:\n\n```text\nGET  /handoff-executions/\u003ctask_id\u003e/resume-plan\nPOST /handoff-executions/\u003ctask_id\u003e/create-resume-review  {\"confirm\": true}\nGET  /resume-reviews\nPOST /resume-reviews/\u003ctask_id\u003e/approve                   {\"confirm\": true, \"action_id\": \"...\"}\nPOST /resume-reviews/\u003ctask_id\u003e/reject                    {\"reason\": \"...\"}\n```\n\nThe planner emits metadata-only proposals such as inspecting the promotion plan,\nrequesting scoped pointer references, or opening a fresh scoped task. It records\n`resume_action_ready` only after approval and keeps `execute_automatically=false`.\n\n## Lightweight Footprint Metrics\n\nCPOS keeps LLM context light by passing pointers, summaries, queue metadata, and\nhash heads rather than raw logs or checkpoint contents. The footprint endpoint\nshows this storage/control overhead explicitly:\n\n```bash\ncurl https://\u003chost\u003e/footprint\n```\n\nDashboard and generated reports show total JSONL/storage bytes, pointer/task\ncounts, and safety properties such as `secrets_included=false`,\n`handoff_imports_raw_body=false`, and\n`checkpoint_contents_exposed_by_api=false`.\n\n## Handoff Flow Graph\n\nUse a metadata-only graph to inspect where an imported handoff is in the safe\nresume pipeline:\n\n```bash\ncurl https://\u003chost\u003e/handoff-graph\ncurl 'https://\u003chost\u003e/handoff-graph?source_pointer_id=ptr://handoff/\u003cid\u003e'\n```\n\nThe graph links `handoff_summary` pointers to promotion plans, execution reviews,\nresume reviews, and ready events without exposing raw handoff bodies, checkpoint\ncontents, or secrets. The dashboard renders the same chain as\nHandoff → Promotion → Execution → Resume.\n\n## Persistent Rate Limit Backend\n\nRate limiting defaults to in-memory state. For single-host multi-process deployments\n(e.g. multiple Gunicorn workers), use the file-backed backend so workers share the\nsame sliding-window buckets:\n\n```bash\nexport CPOS_RATE_LIMIT_ENABLED=true\nexport CPOS_RATE_LIMIT_BACKEND=file\nexport CPOS_RATE_LIMIT_STORE_PATH=/var/lib/cpos/rate_limit_state.json\n```\n\nThe file-backed store records bucket keys and timestamps only. It does not store\nAuthorization headers, request bodies, tokens, or secret values. For multi-host\ndeployments, use this as the local baseline and add a Redis/Valkey backend later.\n\n## Rate Limit Backend Visibility \u0026 Redis/Valkey Hook\n\n`/security-profile` now reports the active rate-limit backend. Dashboard shows\nwhether rate limiting is off, memory-backed, file-backed, or Redis/Valkey-backed.\n\nOptional Redis/Valkey mode is configured without putting credentials in `.env`:\n\n```bash\nexport CPOS_RATE_LIMIT_BACKEND=redis\nexport CPOS_RATE_LIMIT_REDIS_URL_FILE=/run/cpos-secrets/redis_rate_limit_url\nexport CPOS_RATE_LIMIT_REDIS_KEY_PREFIX=cpos:rate_limit\n```\n\nThe Redis URL file should be rendered from Vault. If the URL file is missing, the\nbackend fails closed with `rate_limit_redis_url_not_configured`.\n\n## Handoff Graph Filters\n\nDashboard Handoff Flow Graph now supports filtering by review status and source\npointer. API filters:\n\n```bash\ncurl 'https://\u003chost\u003e/handoff-graph?review_status=approved\u0026limit=20'\ncurl 'https://\u003chost\u003e/handoff-graph?source_pointer_id=ptr://handoff/\u003cid\u003e'\n```\n\nRedis/Valkey deployment checklist lives at:\n\n```text\ndeploy/hardened/REDIS_RATE_LIMIT_GUIDE.md\n```\n\n`python3 -m cpos.preflight --profile hardened --json` validates Redis/Valkey\nrate-limit configuration without printing the URL value.\n\n## Handoff Graph Detail Drill-down\n\nThe dashboard Handoff Flow Graph includes a metadata-only drill-down panel for a\nselected handoff. It shows the related promotion plans, execution reviews, resume\nreviews, warnings, blocked inputs, and first resume action title.\n\nThe panel intentionally does not display raw handoff bodies, checkpoint contents,\nrequest bodies, proposed code, or secret values.\n\n## Report Rate-limit / Handoff Graph Widgets\n\nGenerated reports now include:\n\n- Rate Limit Backend posture: enabled/off, backend type, file store path, Redis URL file configured status without printing URL values.\n- Handoff Flow Graph table: Handoff → Promotion → Execution → Resume links with warnings/blocked-input counts and first resume action metadata.\n\nBoth widgets are metadata-only and exclude raw handoff bodies, checkpoint contents,\nrequest bodies, proposed code, tokens, and secret values.\n\n## MCP Connector Registry: Text-first Security Check\n\nMCP support starts with a safe registry/gov layer, not direct tool execution. Connector\nconfigs are submitted as JSON text, statically checked, then registered only with an\nexplicit confirmation step.\n\n```bash\npython3 -m cpos.mcp_cli check-definition connector.json --json\npython3 -m cpos.mcp_cli register connector.json --confirm --json\npython3 -m cpos.mcp_cli check-tool 'mcp://docs/search' docs.search --json\n```\n\nHTTP API:\n\n```bash\ncurl -X POST https://\u003chost\u003e/mcp/connectors/check -d @connector.json\ncurl -X POST https://\u003chost\u003e/mcp/connectors -d @connector-with-confirm.json\ncurl https://\u003chost\u003e/mcp/connectors\n```\n\nSafety rules enforced before registration:\n\n- Remote MCP URLs must be `https://`; plain HTTP is rejected.\n- Secrets are not accepted as raw values. Use `env_secret_files` paths rendered from Vault/secret volumes.\n- `allowed_tools` must be an explicit non-empty allowlist.\n- Dangerous-looking tools and private/restricted connectors require human approval.\n- Shell-wrapper stdio commands and shell metacharacters are blocked.\n- MCP audit events are hash-chained and visible through `/integrity`.\n\n## MCP Review Dashboard / Report\n\nThe dashboard now includes an MCP Connector Review section and summary card. It\nshows registered connectors, active/approval-gated counts, allowed/blocked tools,\nsecret-file reference posture, and metadata-only actions for `check-tool` and\n`disable`.\n\nGenerated reports include the same MCP Connector Registry posture plus MCP audit\nhash-chain status. This is still governance-only: no MCP server is launched and no\nMCP tool is executed from the dashboard/report.\n\n## MCP Connector Import / Review Queue\n\nMCP connector definitions can now be submitted into a review queue before they are\nregistered:\n\n```bash\npython3 -m cpos.mcp_cli submit-review connector.json --json\npython3 -m cpos.mcp_cli reviews --status pending --json\npython3 -m cpos.mcp_cli approve-review mcp_review_\u003cid\u003e --confirm --json\npython3 -m cpos.mcp_cli reject-review mcp_review_\u003cid\u003e --reason \"not needed\" --json\n```\n\nHTTP API:\n\n```bash\ncurl -X POST https://\u003chost\u003e/mcp/reviews -d @connector.json\ncurl 'https://\u003chost\u003e/mcp/reviews?status=pending'\ncurl -X POST https://\u003chost\u003e/mcp/reviews/\u003creview_id\u003e/approve -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/mcp/reviews/\u003creview_id\u003e/reject -d '{\"reason\":\"manual_reject\"}'\n```\n\nOnly definitions that pass the static security check are persisted in the queue.\nDefinitions containing raw secret-like values, plain HTTP URLs, shell wrappers, or\nother blocking findings are rejected and not stored. Approval registers the\nconnector; rejection records the reason. The review queue is hash-chained and\nincluded in `/integrity`.\n\n### Tape Memory MCP Fast Resume Cache\n\nA safe stdio connector definition for the local Tape Memory MCP resume cache is\nincluded at `config/mcp/tape_memory_mcp.json`. It is intended for token-light\nresume indexing only; CPOS Task Tape remains the source of truth.\n\n```bash\npython3 -m cpos.mcp_cli check-definition config/mcp/tape_memory_mcp.json --json\npython3 -m cpos.mcp_cli submit-review config/mcp/tape_memory_mcp.json --json\npython3 -m cpos.mcp_cli reviews --status pending --json\n```\n\nThe definition runs the local MCP server with\n`TAPE_MEMORY_DIR=/home/mayutama/.tape-memory-mcp-cpos`, allowlists only\n`load_tape`, `store_tape`, and `inspect_dictionary`, blocks\n`extend_dictionary`, requires human approval, and contains no raw secrets. The\ncache must store resume hints only: no raw diffs, raw stdout/stderr, request\nbodies, checkpoints, handoff bodies, tokens, or secret values.\n\n## MCP Execution Adapter: Dry-run / Metadata-only\n\nMCP execution requests now pass through a dry-run adapter before any real tool\nexecution exists:\n\n```bash\ncurl -X POST https://\u003chost\u003e/mcp/executions/dry-run \\\n  -d '{\"connector_id\":\"mcp://docs/search\",\"tool_name\":\"docs.search\",\"arguments\":{\"query\":\"example\"}}'\ncurl 'https://\u003chost\u003e/mcp/executions'\ncurl -X POST https://\u003chost\u003e/mcp/executions/\u003ctask_id\u003e/approve -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/mcp/executions/\u003ctask_id\u003e/reject -d '{\"reason\":\"manual_reject\"}'\n```\n\nThe adapter checks connector status, tool allowlist/blocklist, secret-like argument\nkeys, and approval requirements. It never launches MCP servers, never executes MCP\ntools, and never stores raw argument values; only argument hashes, sizes, and top-level\nkeys are written to Task Tape. Approval currently means “approved for dry-run only”\nand still does not execute the tool.\n\n## GitHub PR Workflow: Dry-run / Metadata-only\n\nIssue-to-PR planning now has a safe first stage. The API can create review-gated\nGitHub PR dry-run plans, but it does **not** create branches, commits, pushes, or\npull requests:\n\n```bash\ncurl -X POST https://\u003chost\u003e/github/pr-dry-runs \\\n  -d '{\"repo\":\"kagioneko/cpos-engine-zero\",\"title\":\"Add docs\",\"issue_number\":1,\"summary\":\"Docs update\",\"files\":[\"README.md\"]}'\ncurl 'https://\u003chost\u003e/github/pr-dry-runs'\ncurl -X POST https://\u003chost\u003e/github/pr-dry-runs/\u003ctask_id\u003e/approve -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/github/pr-dry-runs/\u003ctask_id\u003e/reject -d '{\"reason\":\"manual_reject\"}'\n```\n\nThe plan stores metadata only: summary hash/size, candidate file paths, proposed\nbranch name, proposed commit message, and PR title. Raw summary text and secrets are\nnot stored. Approval currently marks the dry-run plan as approved only; automation\nstill remains disabled until a later explicit execution adapter is added.\n\n## GitHub Diff Review: Metadata-only\n\nApproved PR dry-run plans can advance to a diff-review stage. This stage records\nonly diff metadata and remains non-executing:\n\n```bash\ncurl -X POST https://\u003chost\u003e/github/pr-dry-runs/\u003csource_task_id\u003e/create-diff-review \\\n  -d '{\"diff_text\":\"+example\",\"changed_files\":[\"README.md\"],\"validation_commands\":[\"pytest -q tests/test_report.py\"]}'\ncurl 'https://\u003chost\u003e/github/diff-reviews'\ncurl -X POST https://\u003chost\u003e/github/diff-reviews/\u003ctask_id\u003e/approve -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/github/diff-reviews/\u003ctask_id\u003e/reject -d '{\"reason\":\"manual_reject\"}'\n```\n\nRaw diff text is not stored. The Task Tape keeps hash, byte size, changed file\npaths, validation command strings, and line counters only. Approval does not apply\nthe patch; it only marks the diff plan ready for a future sandbox patch runner.\n\n## Sandbox Patch Plan: Ephemeral Workspace Gate\n\nApproved diff reviews can be promoted into a sandbox patch plan. This plan is still\nmetadata-only: it prepares an isolated validation step but does not apply patches or\nrun commands yet.\n\n```bash\ncurl -X POST https://\u003chost\u003e/github/diff-reviews/\u003cdiff_task_id\u003e/create-sandbox-plan -d '{}'\ncurl 'https://\u003chost\u003e/sandbox/patch-plans'\ncurl -X POST https://\u003chost\u003e/sandbox/patch-plans/\u003ctask_id\u003e/approve -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/sandbox/patch-plans/\u003ctask_id\u003e/reject -d '{\"reason\":\"manual_reject\"}'\n```\n\nThe Task Tape stores only plan hashes, file names, validation command hashes, and\nstatus flags. It does not store live patch application results, command output, or\nlive repository writes.\n\n\n## Sandbox Patch Execution: Isolated Runner Readiness\n\nApproved sandbox patch plans can advance to an execution-review stage. This stage\nstill stays metadata-only: it prepares an isolated runner plan, but it does not\ncopy workspaces or execute commands yet.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/patch-plans/\u003cpatch_task_id\u003e/create-execution-review -d '{}'\ncurl 'https://\u003chost\u003e/sandbox/executions'\ncurl -X POST https://\u003chost\u003e/sandbox/executions/\u003ctask_id\u003e/approve -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/sandbox/executions/\u003ctask_id\u003e/reject -d '{\"reason\":\"manual_reject\"}'\n```\n\nThe Task Tape stores hashes and status flags only. Workspace copy, patch apply,\ncommand execution, and test outputs remain deferred to a later isolated executor.\n\nA focused ready-to-run queue highlights the final human run gate after safe\nadvance flows create pending execution reviews:\n\n```bash\ncurl 'https://\u003chost\u003e/sandbox/executions/ready-to-run'\n```\n\nThis queue is metadata-only and mirrors the dashboard/report helper: it shows\nreview IDs, changed-file names, validation command counts/hashes, and the owning\napprove/run/reject endpoints. It still does not approve execution, copy\nworkspaces, apply patches, run commands, commit, push, create PRs, or store raw\ndiff/output values.\n\n\n## Sandbox Patch Execution Run: Isolated Copy Apply\n\nApproved execution plans can now be run in an ephemeral workspace copy. The runner\napplies the patch in the temp workspace and executes validation commands, while\nkeeping raw outputs out of Task Tape. Only hashes, sizes, exit codes, and status\nflags are recorded.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/executions/\u003ctask_id\u003e/run \\\n  -d '{\"diff_text\":\"...\",\"validation_commands\":[\"pytest -q tests/test_report.py\"],\"runner_mode\":\"strict\"}'\ncurl https://\u003chost\u003e/sandbox/executions/completed\n```\n\nCompleted run results are exposed as metadata-only records for dashboards and\nreports: no raw patch text, no raw stdout/stderr, no commit, no push, and no PR.\nValidation commands are constrained before execution: only pytest-style prefixes are\naccepted by default, shell metacharacters are rejected, and `local-dev` runner mode\nrequires explicit `CPOS_ALLOW_LOCAL_DEV_RUN=true` opt-in.\n\n\n## Sandbox Execution Driver: Review-Gated Advance\n\nFor stronger execution power without weakening safety, CPOS includes a sandbox\nexecution driver that can advance an approved diff through the sandbox chain in\none call: create patch plan, optionally approve it, create execution review,\noptionally approve it, and optionally run the approved execution in an ephemeral\nworkspace. Each approval still requires an explicit boolean flag; no commit, push,\nPR, raw diff persistence, or raw output persistence is introduced.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/execution-driver/advance \\\n  -d '{\n    \"diff_task_id\":\"\u003capproved_diff_task_id\u003e\",\n    \"approve_plan\":true,\n    \"approve_execution\":true,\n    \"run\":true,\n    \"diff_text\":\"...\",\n    \"validation_commands\":[\"pytest -q tests/test_report.py\"],\n    \"runner_mode\":\"strict\"\n  }'\n```\n\nThe driver is intentionally a coordinator, not a bypass: it records the same\nTask Tape review/approval/run events as the manual route, stores metadata only,\nand runs only after the execution plan is approved.\n\nFailed executions can also be advanced toward the next safe attempt without\nrerunning automatically. The failure driver creates a retry review, optionally\napproves it, creates a replan template, and optionally emits a diff-intake\nchecklist for the next human-supplied patch. It never reuses the failed\nworkspace and never stores raw stdout/stderr.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/execution-driver/replan-failure \\\n  -d '{\n    \"source_execution_task_id\":\"\u003cfailed_execution_task_id\u003e\",\n    \"approve_retry\":true,\n    \"create_replan_template\":true,\n    \"create_diff_intake\":true\n  }'\n```\n\nAuto Fix Candidates can be generated from a replan template to propose the next\nrepair strategy without storing patch text or command output. Candidates contain\nfailure kind, strategy, confidence, required human inputs, and hashes only.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/replan-templates/\u003ctask_id\u003e/create-fix-candidate \\\n  -d '{\"reason\":\"metadata_only_repair_strategy\"}'\ncurl https://\u003chost\u003e/sandbox/fix-candidates\n```\n\nDiff Review Drafts can then turn an Auto Fix Candidate into the payload shape for\nthe next GitHub diff-review request. Drafts intentionally leave `diff_text` as a\nrequired human/agent input and never persist raw diff text. A draft can also be\nrouted into the normal GitHub diff-review gate with transient diff input; the\nstored event links draft -\u003e GitHub diff review using hashes, sizes, counters, and\nlineage metadata only.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/fix-candidates/\u003ctask_id\u003e/create-diff-draft \\\n  -d '{\"reason\":\"prepare_next_diff_review\"}'\ncurl https://\u003chost\u003e/sandbox/diff-drafts\ncurl -X POST https://\u003chost\u003e/sandbox/diff-drafts/\u003cdraft_task_id\u003e/create-github-diff-review \\\n  -d '{\"source_task_id\":\"\u003capproved_pr_dry_run_task_id\u003e\",\"diff_text\":\"...\",\"changed_files\":[\"README.md\"],\"validation_commands\":[\"pytest -q tests/test_report.py\"]}'\n```\n\nPatch Generation Reviews add a stronger execution-power path for Auto Fix\nCandidates without relaxing safety gates. An approved patch-generation review can\naccept generated diff text as transient input, check it with `git apply --check`\nin an ephemeral workspace, and then safely advance to a pending Sandbox Execution\nReview. This route may approve the metadata-only GitHub Diff Review and Sandbox\nPatch Plan when `confirm=true`, but it still does not approve execution, run\ncommands, mutate the live repository, commit, push, create a PR, or store raw diff\nor raw output.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/fix-candidates/\u003ctask_id\u003e/create-patch-generation \\\n  -d '{\"reason\":\"review_generated_repair\"}'\ncurl -X POST https://\u003chost\u003e/sandbox/patch-generations/\u003cpatch_generation_task_id\u003e/approve \\\n  -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/sandbox/patch-generations/\u003cpatch_generation_task_id\u003e/validate-output \\\n  -d '{\"diff_text\":\"...\",\"changed_files\":[\"README.md\"],\"validation_commands\":[\"pytest -q tests/test_report.py\"]}'\ncurl -X POST https://\u003chost\u003e/sandbox/patch-generations/\u003cpatch_generation_task_id\u003e/advance-to-execution-review \\\n  -d '{\"confirm\":true,\"source_task_id\":\"\u003capproved_pr_dry_run_task_id\u003e\",\"diff_text\":\"...\",\"changed_files\":[\"README.md\"],\"validation_commands\":[\"pytest -q tests/test_report.py\"]}'\n```\n\n\n## Sandbox Patch Execution Retry Review\n\nFailed sandbox executions can create a retry review from failure metadata only.\nThe retry review never stores raw stdout/stderr or raw patch text, does not reuse\nthe ephemeral workspace, and does not rerun automatically. Approval only records\nthat a human accepted the retry strategy; a new diff/patch plan must still pass\nthe normal review chain.\n\n```bash\ncurl -X POST https://\u003chost\u003e/sandbox/executions/\u003ctask_id\u003e/create-retry-review \\\n  -d '{\"reason\":\"validation_failed\"}'\ncurl https://\u003chost\u003e/sandbox/execution-retries\ncurl -X POST https://\u003chost\u003e/sandbox/execution-retries/\u003cretry_task_id\u003e/approve \\\n  -d '{\"confirm\":true}'\ncurl -X POST https://\u003chost\u003e/sandbox/execution-retries/\u003cretry_task_id\u003e/create-replan-template \\\n  -d '{\"reason\":\"make_new_plan\"}'\ncurl https://\u003chost\u003e/sandbox/replan-templates\n```\n\nApproved retry reviews can create a replan template. The template contains only\nfailure metadata and a suggested next review chain; it does not include diff\ntext, raw outputs, raw patch text, commits, pushes, or PR creation.\n\nFailure metadata is classified into `patch_apply`, `validation_command`,\n`sandbox_unavailable`, or `policy_rejected` so retry/replan flows can separate\ncode/test failures from environment and governance failures.\n\nReplan templates can also emit a metadata-only diff intake checklist via\n`POST /sandbox/replan-templates/\u003ctask_id\u003e/create-diff-intake`. The intake records\nrequired human inputs and the target diff-review API, but never stores raw diff\ntext and never executes automatically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkagioneko%2Fcpos-engine-zero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkagioneko%2Fcpos-engine-zero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkagioneko%2Fcpos-engine-zero/lists"}