ce-work — Skillopedia

Work Execution Command Outcome - Result: A fully implemented, locally verified change set from a plan, specification, or concrete work prompt. - Next consumer: In standalone use, the shipping workflow takes the verified change through review and delivery. In Return-to-Caller Mode, the invoking workflow receives the structured implementation and verification result and owns its remaining gates. - Done: Every in-scope task is complete, required verification evidence is recorded, relevant checks pass, and the run reaches either its owned shipping handoff (with a code-review receipt or explicit s…

\n\nvalidate_model_override() {\n local route=\"$1\" override=\"${CE_WORK_MODEL_OVERRIDE:-}\" override_target=\"${CE_WORK_MODEL_OVERRIDE_TARGET:-}\" target base base_lower\n [ -n \"$override\" ] || { [ -z \"$override_target\" ]; return; }\n case \"$override_target\" in\n codex|claude|grok|cursor|composer|opencode|antigravity) ;;\n *) return 1 ;;\n esac\n target=\"$(route_target \"$route\")\" || return 1\n [ \"$override_target\" = \"$target\" ] || return 0\n base=\"$override\"\n case \"$route\" in\n cursor|composer|grok-cursor)\n [[ \"$override\" =~ $CURSOR_MODEL_RE ]] || return 1\n base=\"${BASH_REMATCH[1]}\"\n ;;\n esac\n if [ \"$route\" = cursor ]; then\n base_lower=\"$(printf '%s' \"$base\" | tr '[:upper:]' '[:lower:]')\"\n case \"$base_lower\" in composer|composer-*|grok|grok-*|cursor-grok-*) return 1 ;; esac\n return 0\n fi\n case \"$route:$base\" in\n codex:gpt-*|codex:o[0-9]*|claude:fable|claude:opus|claude:sonnet|claude:haiku|claude:claude-*|grok-cli:grok-*|grok-cursor:grok-*|grok-cursor:cursor-grok-*|composer:composer-*|opencode:*/*) ;;\n antigravity:gemini-*) [[ \"$base\" =~ ^gemini-[A-Za-z0-9._-]+$ ]] || return 1 ;;\n *) return 1 ;;\n esac\n}\n\n# Accept an effort only where the route's ACP adapter exposes an effort option\n# and lists the value (claude effort, codex and grok reasoning_effort, checked\n# 2026-10-06 through acpx 0.19.4; antigravity thinking_level, checked\n# 2026-10-14; opencode 2.x effort, checked 2026-10-23). Codex and OpenCode\n# levels vary per model, and OpenCode 1.x has no effort option, so a listed\n# level can still be refused before the prompt is sent. Cursor fixes effort in\n# the model preset, so any effort there makes the route unavailable instead of\n# being dropped.\nvalidate_effort_override() {\n local route=\"$1\" effort=\"${EFFORT_REQUESTED:-}\"\n [ -n \"$effort\" ] || return 0\n case \"$route:$effort\" in\n claude:low|claude:medium|claude:high|claude:xhigh|claude:max) ;;\n codex:low|codex:medium|codex:high|codex:xhigh|codex:max|codex:ultra) ;;\n grok-cli:low|grok-cli:medium|grok-cli:high|grok-cli:xhigh) ;;\n antigravity:low|antigravity:medium|antigravity:high) ;;\n opencode:none|opencode:low|opencode:medium|opencode:high|opencode:xhigh|opencode:max) ;;\n *) return 1 ;;\n esac\n}\n\n# The worker runs in the prepared workspace with every permission request\n# approved. Each adapter runs in its write-capable mode (codex agent, claude\n# default, cursor agent, opencode build, antigravity auto_edit, since its\n# default mode waits on approvals that never come); none of them confines\n# writes to the workspace, which references/cross-model-execution.md records\n# per route. Codex, Claude, and Antigravity run at high effort and native Grok\n# at xhigh unless the authorization requests another level.\nadapter_argv() {\n local route=\"$1\" model\n acpx_agent \"$route\" >/dev/null || return 1\n model=\"$(route_model \"$route\")\"\n acpx_base_argv \"$route\" \"$WORKSPACE\" \"$MCP_CONFIG\" \"$ACPX_TIMEOUT\" \"$CLAUDE_WRAPPER\" \"$GEMINI_HOME_DIR\"\n printf '%s\\0' --approve-all\n [ \"$model\" = auto ] || printf '%s\\0' --model \"$model\"\n acpx_agent_argv \"$route\"\n case \"$route\" in\n codex) printf '%s\\0' --config-option mode=agent --config-option \"reasoning_effort=${EFFORT_REQUESTED:-high}\" ;;\n # Claude otherwise starts in the user's default permission mode.\n claude) printf '%s\\0' --config-option mode=default --config-option \"effort=${EFFORT_REQUESTED:-high}\" ;;\n grok-cli) printf '%s\\0' --config-option \"reasoning_effort=${EFFORT_REQUESTED:-xhigh}\" ;;\n cursor|composer|grok-cursor) printf '%s\\0' --config-option mode=agent ;;\n opencode) printf '%s\\0' --config-option mode=build\n [ -z \"${EFFORT_REQUESTED:-}\" ] || printf '%s\\0' --config-option \"effort=$EFFORT_REQUESTED\" ;;\n antigravity) printf '%s\\0' --config-option mode=auto_edit --config-option \"thinking_level=${EFFORT_REQUESTED:-high}\" ;;\n esac\n printf '%s\\0' --file \"$PROMPT_FILE\"\n}\n\nACPX_TIMEOUT=\"${CE_PEER_HARD_SECS:-7200}\"\ncase \"$ACPX_TIMEOUT\" in ''|0|*[!0-9]*) ACPX_TIMEOUT=7200 ;; esac\n\nif [ \"${1:-}\" = \"--emit-adapter\" ]; then\n WORKSPACE=\"\u003cworkspace>\"\n PROMPT_FILE=\"\u003cprompt-file>\"\n MCP_CONFIG=\"\u003cmcp-config>\"\n CLAUDE_WRAPPER=\"\u003cclaude-safe-mode-wrapper>\"\n GEMINI_HOME_DIR=\"\u003cgemini-home>\"\n ROUTE=\"${2:-}\"\n EFFORT_REQUESTED=\"${CROSS_MODEL_EFFORT_OVERRIDE:-}\"\n validate_model_override \"$ROUTE\" || {\n printf \"model override '%s' not compatible with route '%s'\\n\" \"${CE_WORK_MODEL_OVERRIDE:-}\" \"$ROUTE\" >&2\n exit 2\n }\n validate_effort_override \"$ROUTE\" || {\n printf \"effort override '%s' not compatible with route '%s'\\n\" \"$EFFORT_REQUESTED\" \"$ROUTE\" >&2\n exit 2\n }\n adapter_argv \"$ROUTE\" >/dev/null 2>&1 || { printf \"unknown route '%s'\\n\" \"$ROUTE\" >&2; exit 2; }\n adapter_argv \"$ROUTE\" | tr '\\0' ' '\n printf '\\n'\n exit 0\nfi\n\nSIGN_IN_STALL_REASON=\"transport unavailable (pre-egress, route): Antigravity is waiting for a Google sign-in; the agy CLI's sign-in does not carry over, so sign the ACP runtime in once: put {\\\"auth\\\":{\\\"type\\\":\\\"oauth-personal\\\"}} in ${GEMINI_HOME:-~/.gemini}/antigravity-acp/settings.json, run npx -y --package '$(acpx_package_spec)' -- acpx antigravity exec ok in a terminal and finish the browser sign-in, then retry\"\n\n# --check-model antigravity \u003cmodel>: acpx checks --model against the models the\n# session advertises before any prompt, so opening a session answers whether the\n# account offers the model. acpx records the session under $HOME/.acpx; the\n# check deletes that record, and the directories when it created them. A scratch\n# HOME is not an option: the runtime then never opens the session.\nif [ \"${1:-}\" = \"--check-model\" ]; then\n ROUTE=\"${2:-}\"\n CE_WORK_MODEL_OVERRIDE=\"${3:-}\"\n CE_WORK_MODEL_OVERRIDE_TARGET=antigravity\n [ \"$ROUTE\" = antigravity ] || { printf \"no model check for route '%s'\\n\" \"$ROUTE\" >&2; exit 2; }\n validate_model_override antigravity && [ -n \"$CE_WORK_MODEL_OVERRIDE\" ] || {\n printf \"model '%s' not compatible with route 'antigravity'\\n\" \"$CE_WORK_MODEL_OVERRIDE\" >&2\n exit 2\n }\n command -v jq >/dev/null 2>&1 || { echo \"transport unavailable (pre-egress, shared): jq not found; the ACP stream is read with jq\" >&2; exit 2; }\n CHECK_DIR=\"$(mktemp -d \"${TMPDIR:-/tmp}/ce-work-model-check-XXXXXX\")\" || exit 2\n CHECK_PID=\"\"\n ACPX_STATE=\"${HOME:-}/.acpx\"\n ACPX_STATE_EXISTED=false; [ -d \"$ACPX_STATE\" ] && ACPX_STATE_EXISTED=true\n # Every exit path stops the detached acpx group (TERM, then KILL) and removes\n # what the check created.\n check_cleanup() {\n local i\n # Probe the whole group, not the leader: acpx can exit and leave the\n # runtime running in its group.\n if [ -n \"$CHECK_PID\" ] && kill -0 -- -\"$CHECK_PID\" 2>/dev/null; then\n kill -TERM -- -\"$CHECK_PID\" 2>/dev/null\n for i in 1 2 3 4 5; do kill -0 -- -\"$CHECK_PID\" 2>/dev/null || break; sleep 1; done\n kill -KILL -- -\"$CHECK_PID\" 2>/dev/null || true\n fi\n rm -rf \"$CHECK_DIR\"\n [ \"$ACPX_STATE_EXISTED\" = true ] || { rmdir \"$ACPX_STATE/sessions\" \"$ACPX_STATE\" 2>/dev/null || true; }\n }\n trap check_cleanup EXIT\n trap 'exit 130' INT TERM HUP QUIT\n mkdir \"$CHECK_DIR/cwd\" || exit 2\n acpx_preflight antigravity \"$CHECK_DIR/cwd\" || {\n printf 'transport unavailable (pre-egress, %s): %s\\n' \"$ACPX_SCOPE\" \"$ACPX_UNAVAILABLE\" >&2\n exit 2\n }\n GEMINI_HOME_DIR=\"$(acpx_antigravity_home \"$CHECK_DIR\")\" || { echo \"cannot prepare a private Antigravity home\" >&2; exit 2; }\n printf '{\"mcpServers\":[]}\\n' > \"$CHECK_DIR/mcp.json\"\n open_check_session() {\n ARGS=()\n while IFS= read -r -d '' token; do ARGS+=(\"$token\"); done \u003c \u003c(\n acpx_base_argv antigravity \"$CHECK_DIR/cwd\" \"$CHECK_DIR/mcp.json\" \"$ACPX_TIMEOUT\" \"\" \"$GEMINI_HOME_DIR\")\n ARGS+=(--model \"$CE_WORK_MODEL_OVERRIDE\" antigravity sessions new --name \"ce-work-model-check-$\")\n set -m\n (cd \"$CHECK_DIR\" && exec \"${ARGS[@]}\" \u003c /dev/null > \"$CHECK_DIR/stdout\" 2> \"$CHECK_DIR/stderr\") &\n CHECK_PID=$!\n set +m\n CHECK_DEADLINE=$(( $(date +%s) + ACPX_SESSION_START_SECS ))\n while kill -0 \"$CHECK_PID\" 2>/dev/null && [ \"$(date +%s)\" -lt \"$CHECK_DEADLINE\" ]; do sleep 1; done\n if kill -0 \"$CHECK_PID\" 2>/dev/null; then\n echo \"$SIGN_IN_STALL_REASON\" >&2\n exit 2\n fi\n wait \"$CHECK_PID\"\n CHECK_EXIT=$?\n }\n open_check_session\n if [ \"$CHECK_EXIT\" -ne 0 ] && acpx_npm_resolution_retryable \"$CHECK_DIR/stderr\" \"$CHECK_DIR/stdout\"; then\n log \"npm could not resolve a package; retrying the model check once with fresh metadata (npm policy unchanged)\"\n ACPX_NPM_REFRESH=true\n open_check_session\n fi\n RECORD_ID=\"$(jq -r 'select(.action? == \"session_ensured\") | .acpxRecordId // empty' \"$CHECK_DIR/stdout\" 2>/dev/null | tail -1)\"\n case \"$RECORD_ID\" in ''|*[!A-Za-z0-9-]*) ;; *) rm -f \"$ACPX_STATE/sessions/$RECORD_ID.json\" ;; esac\n [ \"$CHECK_EXIT\" -eq 0 ] && exit 0\n REASON=\"$(acpx_npm_failure_reason \"$CHECK_DIR/stderr\")\"\n if [ -n \"$REASON\" ]; then\n printf 'transport unavailable (pre-egress, shared): %s\\n' \"${REASON:0:200}\" >&2\n else\n REASON=\"$(acpx_npm_failure_reason \"$CHECK_DIR/stdout\")\"\n [ -n \"$REASON\" ] || REASON=\"$(acpx_failure_evidence \"$CHECK_DIR/stdout\")\"\n [ -n \"$REASON\" ] || REASON=\"$(grep -m1 -e 'did not advertise' -e 'Error' \"$CHECK_DIR/stderr\" 2>/dev/null)\"\n printf 'transport unavailable (pre-egress, route): %s\\n' \"${REASON:-acpx exited $CHECK_EXIT while opening a session}\" >&2\n fi\n exit 2\nfi\n\nAUTHORIZATION=\"${1:-}\"\nWORKSPACE=\"${2:-}\"\nPACKET=\"${3:-}\"\nEXPECTED_PACKET_DIGEST=\"${4:-}\"\nRESULT_DIR=\"${5:-}\"\n[[ \"$EXPECTED_PACKET_DIGEST\" =~ ^[0-9a-f]{64}$ ]] || { log \"expected packet digest must be lowercase SHA-256\"; exit 2; }\n[ -n \"$AUTHORIZATION\" ] || { log \"controller authorization JSON path is required\"; exit 2; }\n[ -d \"$WORKSPACE\" ] || { log \"workspace '$WORKSPACE' is not a directory\"; exit 2; }\n[ -f \"$PACKET\" ] && [ ! -L \"$PACKET\" ] || { log \"unit packet '$PACKET' is not a regular non-link file\"; exit 2; }\n[ -d \"$RESULT_DIR\" ] && [ ! -L \"$RESULT_DIR\" ] || { log \"result dir '$RESULT_DIR' is not a directory\"; exit 2; }\n\nDISPATCH_AUTHORIZATION=\"$AUTHORIZATION\"\nDISPATCH_WORKSPACE=\"$WORKSPACE\"\nDISPATCH_PACKET=\"$PACKET\"\nDISPATCH_RESULT_DIR=\"$RESULT_DIR\"\n\nMAX_PACKET_BYTES=\"${CE_WORK_MAX_PACKET_BYTES:-200000}\"\ncase \"$MAX_PACKET_BYTES\" in ''|*[!0-9]*) MAX_PACKET_BYTES=200000 ;; esac\n\nSKILL_ROOT=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\" || exit 2\nPERSONA=\"$SKILL_ROOT/references/agents/implementation-worker.md\"\nSCHEMA=\"$SKILL_ROOT/references/implementation-result-schema.json\"\n[ -f \"$PERSONA\" ] && [ -f \"$SCHEMA\" ] || { log \"worker persona or result schema missing\"; exit 2; }\n\nSCRATCH=\"$(mktemp -d \"${TMPDIR:-/tmp}/ce-work-adapter-XXXXXX\")\" || exit 2\nchmod 700 \"$SCRATCH\"\nPROMPT_FILE=\"$SCRATCH/prompt.md\"\n# acpx prints the ACP stream on stdout; npm and adapter diagnostics go to stderr.\nRAW_STDOUT=\"$SCRATCH/stdout.log\"\nRAW_STDERR=\"$SCRATCH/stderr.log\"\nSTREAM=\"$SCRATCH/stream.redacted\"\nREPLY_TEXT=\"$SCRATCH/reply.txt\"\nSERVED_MODELS=\"$SCRATCH/served-models\"\nMCP_CONFIG=\"$SCRATCH/mcp.json\"\nCLAUDE_WRAPPER=\"\"\nGEMINI_HOME_DIR=\"\"\nSESSION_STALL_MARKER=\"$SCRATCH/session-stalled\"\nRAW_LIMIT_MARKER=\"$SCRATCH/raw-output-limit\"\nPACKET_SNAPSHOT=\"$SCRATCH/unit-packet\"\nAUTH_VALUES=\"$SCRATCH/authorization-values\"\nRESULT_FILE=\"$RESULT_DIR/implementation-result.json\"\nLOG_FILE=\"$RESULT_DIR/adapter.log\"\nLOG_RETAINED=0\ntrap 'rm -rf \"$SCRATCH\"' EXIT\n\n# The controller's create-exclusive authorization artifact is the production\n# dispatch capability. Read it once through a no-follow descriptor, validate\n# its exact route/model/packet contract, and derive every dispatch identity\n# field from those bytes before constructing a prompt or invoking a model CLI.\n\"$PY\" - \"$AUTHORIZATION\" \"$EXPECTED_PACKET_DIGEST\" \"$AUTH_VALUES\" \u003c\u003c'PY'\nimport json, os, re, stat, sys\n\nsource, expected_packet_digest, output = sys.argv[1:]\nrequired = {\n \"schema_version\", \"run_id\", \"unit_id\", \"attempt_id\", \"route\", \"target\", \"harness\",\n \"intermediaries\", \"model_requested\", \"restriction_posture\",\n \"restrictions\", \"activity_posture\", \"packet_digest\",\n}\ncontracts = {\n \"codex\": (\"codex\", \"codex\", [], \"cooperative\"),\n \"claude\": (\"claude\", \"claude\", [], \"cooperative\"),\n \"grok-cli\": (\"grok\", \"grok\", [], \"cooperative\"),\n \"cursor\": (\"cursor\", \"cursor-agent\", [], \"cooperative\"),\n \"composer\": (\"composer\", \"cursor-agent\", [\"cursor\"], \"cooperative\"),\n \"grok-cursor\": (\"grok\", \"cursor-agent\", [\"cursor\"], \"cooperative\"),\n \"opencode\": (\"opencode\", \"opencode\", [], \"cooperative\"),\n \"antigravity\": (\"antigravity\", \"antigravity\", [], \"cooperative\"),\n}\n\ndef fail(message):\n raise ValueError(message)\n\ndef model_allowed(route, model):\n if not isinstance(model, str) or not model or \"\\n\" in model or \"\\r\" in model:\n return False\n if route in (\"cursor\", \"composer\", \"grok-cursor\"):\n match = re.fullmatch(r\"([A-Za-z0-9][A-Za-z0-9._:/-]*)(?:\\[[A-Za-z0-9._=,:-]*\\])?\", model)\n if not match:\n return False\n base = match.group(1)\n if route == \"composer\":\n return bool(re.fullmatch(r\"composer-[A-Za-z0-9._-]+\", base))\n if route == \"grok-cursor\":\n return bool(re.fullmatch(r\"(?:cursor-)?grok-[A-Za-z0-9._-]+\", base))\n lowered = base.lower()\n return not (lowered in {\"composer\", \"grok\"} or lowered.startswith((\"composer-\", \"grok-\", \"cursor-grok-\")))\n if route == \"codex\":\n return model == \"auto\" or bool(re.fullmatch(r\"(?:gpt-[A-Za-z0-9._-]+|o[0-9][A-Za-z0-9._-]*)\", model))\n if route == \"claude\":\n return model in {\"auto\", \"fable\", \"opus\", \"sonnet\", \"haiku\"} or bool(re.fullmatch(r\"claude-[A-Za-z0-9._-]+\", model))\n if route == \"grok-cli\":\n return model == \"auto\" or bool(re.fullmatch(r\"grok-[A-Za-z0-9._-]+\", model))\n if route == \"opencode\":\n return model == \"auto\" or bool(re.fullmatch(r\"[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9._-]+\", model))\n if route == \"antigravity\":\n return bool(re.fullmatch(r\"gemini-[A-Za-z0-9._-]+\", model))\n return False\n\ntry:\n flags = os.O_RDONLY | getattr(os, \"O_NOFOLLOW\", 0)\n fd = os.open(os.path.abspath(source), flags)\n try:\n before = os.fstat(fd)\n if not stat.S_ISREG(before.st_mode):\n fail(\"authorization is not a regular file\")\n geteuid = getattr(os, \"geteuid\", None)\n if geteuid is not None and before.st_uid != geteuid():\n fail(\"authorization is not owned by the current user\")\n if stat.S_IMODE(before.st_mode) != 0o600:\n fail(\"authorization mode is not 0600\")\n if before.st_size > 64 * 1024:\n fail(\"authorization exceeds 65536 bytes\")\n chunks, total = [], 0\n while True:\n part = os.read(fd, min(65536, 65537 - total))\n if not part:\n break\n chunks.append(part)\n total += len(part)\n if total > 65536:\n fail(\"authorization grew past 65536 bytes\")\n after = os.fstat(fd)\n if (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns, before.st_ctime_ns) != (\n after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns, after.st_ctime_ns\n ):\n fail(\"authorization changed while being read\")\n finally:\n os.close(fd)\n try:\n value = json.loads(b\"\".join(chunks))\n except (ValueError, UnicodeDecodeError) as exc:\n fail(f\"authorization is malformed JSON: {exc}\")\n if not isinstance(value, dict) or set(value) - {\"effort_requested\"} != required:\n fail(\"authorization keys do not match the exact controller schema\")\n if type(value[\"schema_version\"]) is not int or value[\"schema_version\"] != 1:\n fail(\"authorization schema_version must be 1\")\n for key in (\"run_id\", \"unit_id\", \"attempt_id\"):\n if not isinstance(value[key], str) or not re.fullmatch(r\"[A-Za-z0-9._-]{1,128}\", value[key]) or not value[key].strip(\".\"):\n fail(f\"authorization {key} is unsafe\")\n route = value[\"route\"]\n if route not in contracts:\n fail(\"authorization route is unsupported\")\n target, harness, intermediaries, posture = contracts[route]\n if (value[\"target\"], value[\"harness\"], value[\"intermediaries\"], value[\"restriction_posture\"]) != (target, harness, intermediaries, posture):\n fail(\"authorization route identity or restriction posture is inconsistent\")\n if value[\"activity_posture\"] not in {\"incremental\", \"hard-only\"}:\n fail(\"authorization activity_posture is invalid\")\n restrictions = value[\"restrictions\"]\n if not isinstance(restrictions, list) or not all(isinstance(item, str) for item in restrictions):\n fail(\"authorization restrictions must be a string list\")\n if not model_allowed(route, value[\"model_requested\"]):\n fail(\"authorization model is incompatible with the fixed route\")\n effort = value.get(\"effort_requested\", \"\")\n if \"effort_requested\" in value and (not isinstance(effort, str) or not re.fullmatch(r\"[A-Za-z0-9][A-Za-z0-9_-]{0,31}\", effort)):\n fail(\"authorization effort_requested is not a short plain token\")\n packet_digest = value[\"packet_digest\"]\n if not isinstance(packet_digest, str) or not re.fullmatch(r\"[0-9a-f]{64}\", packet_digest):\n fail(\"authorization packet_digest is not lowercase SHA-256\")\n if packet_digest != expected_packet_digest:\n fail(\"authorization packet digest does not match dispatch\")\n authorization_digest = __import__(\"hashlib\").sha256(b\"\".join(chunks)).hexdigest()\n fields = (\n authorization_digest, value[\"run_id\"], value[\"unit_id\"], value[\"attempt_id\"],\n route, target, harness, value[\"model_requested\"], value[\"activity_posture\"], posture, effort,\n )\n out = os.open(output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)\n try:\n os.write(out, b\"\\0\".join(item.encode() for item in fields) + b\"\\0\")\n finally:\n os.close(out)\nexcept (OSError, ValueError) as exc:\n print(f\"controller authorization rejected: {exc}\", file=sys.stderr)\n raise SystemExit(2)\nPY\nAUTH_EXIT=$?\n[ \"$AUTH_EXIT\" -eq 0 ] || { log \"controller authorization rejected\"; exit 2; }\n\nAUTH_FIELDS=()\nwhile IFS= read -r -d '' field; do AUTH_FIELDS+=(\"$field\"); done \u003c \"$AUTH_VALUES\"\n[ \"${#AUTH_FIELDS[@]}\" -eq 11 ] || { log \"controller authorization projection is incomplete\"; exit 2; }\nOBSERVED_AUTH_DIGEST=\"${AUTH_FIELDS[0]}\"\nRUN_ID=\"${AUTH_FIELDS[1]}\"\nUNIT_ID=\"${AUTH_FIELDS[2]}\"\nATTEMPT_ID=\"${AUTH_FIELDS[3]}\"\nROUTE=\"${AUTH_FIELDS[4]}\"\nAUTH_TARGET=\"${AUTH_FIELDS[5]}\"\nAUTH_HARNESS=\"${AUTH_FIELDS[6]}\"\nMODEL_REQUESTED=\"${AUTH_FIELDS[7]}\"\nACTIVITY_POSTURE=\"${AUTH_FIELDS[8]}\"\nRESTRICTION_POSTURE=\"${AUTH_FIELDS[9]}\"\nEFFORT_REQUESTED=\"${AUTH_FIELDS[10]}\"\nRUNNER_JOB_ID=\"${CE_PEER_JOB_ID:-}\"\n[[ \"$RUNNER_JOB_ID\" =~ ^[A-Za-z0-9._-]{1,128}$ && \"$RUNNER_JOB_ID\" =~ [A-Za-z0-9_-] ]] || {\n log \"runner job identity is missing or unsafe\"\n exit 2\n}\n\n# A valid JSON file is not itself dispatch authority. Prove the exact no-follow\n# snapshot and every raw controller-returned path back to the controller before\n# prompt construction. Only its AUTHORIZED status permits external egress.\nCONTROLLER=\"$SKILL_ROOT/scripts/unit-workspace.py\"\nAUTH_RESPONSE=\"$(\"$PY\" \"$CONTROLLER\" authorize-dispatch \\\n --authorization \"$DISPATCH_AUTHORIZATION\" \\\n --authorization-digest \"$OBSERVED_AUTH_DIGEST\" \\\n --workspace \"$DISPATCH_WORKSPACE\" \\\n --packet \"$DISPATCH_PACKET\" \\\n --packet-digest \"$EXPECTED_PACKET_DIGEST\" \\\n --result-dir \"$DISPATCH_RESULT_DIR\" \\\n --run-id \"$RUN_ID\" --unit-id \"$UNIT_ID\" --attempt-id \"$ATTEMPT_ID\" --job-id \"$RUNNER_JOB_ID\" 2>&1)\"\nCONTROLLER_EXIT=$?\nAUTH_STATUS=\"${AUTH_RESPONSE%%

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\\n'*}\"\nif [ \"$CONTROLLER_EXIT\" -ne 0 ] || [ \"$AUTH_STATUS\" != \"AUTHORIZED\" ]; then\n [ -n \"$AUTH_RESPONSE\" ] && printf '%s\\n' \"$AUTH_RESPONSE\" >&2\n log \"controller dispatch authorization failed\"\n exit 2\nfi\n\n# Canonicalize operational paths only after the handshake. The controller\n# compares the raw paths it returned, including platform compatibility symlinks.\nWORKSPACE=\"$(cd \"$WORKSPACE\" && pwd -P)\" || exit 2\nPACKET=\"$(cd \"$(dirname \"$PACKET\")\" && pwd -P)/$(basename \"$PACKET\")\" || exit 2\nRESULT_DIR=\"$(cd \"$RESULT_DIR\" && pwd -P)\" || exit 2\ncase \"$RESULT_DIR/\" in \"$WORKSPACE/\"*) log \"result dir must be outside the worker workspace\"; exit 2 ;; esac\ncase \"$PACKET\" in \"$WORKSPACE\"/*) log \"unit packet must be outside the worker workspace\"; exit 2 ;; esac\ngit -C \"$WORKSPACE\" rev-parse --is-inside-work-tree >/dev/null 2>&1 || { log \"workspace is not a Git worktree\"; exit 2; }\nchmod 700 \"$RESULT_DIR\" 2>/dev/null || { log \"result dir could not be made private\"; exit 2; }\nRESULT_DIR_IDENTITY=\"$(\"$PY\" - \"$RESULT_DIR\" \u003c\u003c'PY'\nimport os, stat, sys\n\npath = sys.argv[1]\nflags = os.O_RDONLY | getattr(os, \"O_DIRECTORY\", 0) | getattr(os, \"O_NOFOLLOW\", 0)\nfd = os.open(path, flags)\ntry:\n info = os.fstat(fd)\n if not stat.S_ISDIR(info.st_mode):\n raise OSError(\"result dir is not a directory\")\n print(f\"{info.st_dev}:{info.st_ino}\")\nfinally:\n os.close(fd)\nPY\n)\" || { log \"result dir identity could not be captured\"; exit 2; }\n\nwrite_adapter_log() {\n \"$PY\" -c '\nimport os, stat, sys\n\npath, expected = sys.argv[1:]\ndir_flags = os.O_RDONLY | getattr(os, \"O_DIRECTORY\", 0) | getattr(os, \"O_NOFOLLOW\", 0)\ntry:\n dir_fd = os.open(path, dir_flags)\n try:\n directory = os.fstat(dir_fd)\n if not stat.S_ISDIR(directory.st_mode):\n raise OSError(\"result dir is not a directory\")\n if f\"{directory.st_dev}:{directory.st_ino}\" != expected:\n raise OSError(\"result dir identity changed during route\")\n file_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, \"O_NOFOLLOW\", 0)\n log_fd = os.open(\"adapter.log\", file_flags, 0o600, dir_fd=dir_fd)\n try:\n target = os.fstat(log_fd)\n if not stat.S_ISREG(target.st_mode):\n raise OSError(\"adapter log is not a regular file\")\n os.fchmod(log_fd, 0o600)\n while True:\n chunk = sys.stdin.buffer.read(65536)\n if not chunk:\n break\n view = memoryview(chunk)\n while view:\n view = view[os.write(log_fd, view):]\n finally:\n os.close(log_fd)\n finally:\n os.close(dir_fd)\nexcept OSError as error:\n print(f\"adapter log retention refused: {error}\", file=sys.stderr)\n raise SystemExit(2)\n' \"$RESULT_DIR\" \"$RESULT_DIR_IDENTITY\"\n}\n\nwrite_result_receipt() {\n \"$PY\" -c '\nimport os, secrets, stat, sys\n\npath, expected = sys.argv[1:]\ndir_flags = os.O_RDONLY | getattr(os, \"O_DIRECTORY\", 0) | getattr(os, \"O_NOFOLLOW\", 0)\ndir_fd = None\nreceipt_fd = None\ntmp_name = None\ntry:\n data = sys.stdin.buffer.read()\n dir_fd = os.open(path, dir_flags)\n directory = os.fstat(dir_fd)\n if not stat.S_ISDIR(directory.st_mode):\n raise OSError(\"result dir is not a directory\")\n if f\"{directory.st_dev}:{directory.st_ino}\" != expected:\n raise OSError(\"result dir identity changed during route\")\n file_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, \"O_NOFOLLOW\", 0)\n for _ in range(128):\n candidate = f\".result-{os.getpid()}-{secrets.token_hex(8)}\"\n try:\n receipt_fd = os.open(candidate, file_flags, 0o600, dir_fd=dir_fd)\n tmp_name = candidate\n break\n except FileExistsError:\n continue\n if receipt_fd is None:\n raise OSError(\"could not reserve a result receipt temporary file\")\n target = os.fstat(receipt_fd)\n if not stat.S_ISREG(target.st_mode):\n raise OSError(\"result receipt temporary file is not regular\")\n os.fchmod(receipt_fd, 0o600)\n view = memoryview(data)\n while view:\n view = view[os.write(receipt_fd, view):]\n os.close(receipt_fd)\n receipt_fd = None\n os.replace(\n tmp_name,\n \"implementation-result.json\",\n src_dir_fd=dir_fd,\n dst_dir_fd=dir_fd,\n )\n tmp_name = None\nexcept OSError as error:\n print(f\"result receipt publication refused: {error}\", file=sys.stderr)\n raise SystemExit(2)\nfinally:\n if receipt_fd is not None:\n os.close(receipt_fd)\n if tmp_name is not None and dir_fd is not None:\n try:\n os.unlink(tmp_name, dir_fd=dir_fd)\n except OSError:\n pass\n if dir_fd is not None:\n os.close(dir_fd)\n' \"$RESULT_DIR\" \"$RESULT_DIR_IDENTITY\"\n}\n\n# Read the packet once through a no-follow descriptor, hash those exact bytes,\n# and build the prompt from the private snapshot. The controller-provided\n# digest is therefore bound to the content that actually crosses the route.\nOBSERVED_PACKET_DIGEST=\"$(\"$PY\" - \"$PACKET\" \"$PACKET_SNAPSHOT\" \"$MAX_PACKET_BYTES\" \u003c\u003c'PY'\nimport hashlib, os, stat, sys\n\nsource, snapshot, raw_cap = sys.argv[1:]\ncap = int(raw_cap)\nflags = os.O_RDONLY | getattr(os, \"O_NOFOLLOW\", 0)\nfd = os.open(source, flags)\ntry:\n info = os.fstat(fd)\n if not stat.S_ISREG(info.st_mode):\n raise OSError(\"unit packet is not a regular file\")\n chunks, total = [], 0\n while True:\n chunk = os.read(fd, min(65536, cap + 1 - total))\n if not chunk:\n break\n chunks.append(chunk)\n total += len(chunk)\n if total > cap:\n raise OSError(f\"unit packet exceeds {cap} bytes\")\nfinally:\n os.close(fd)\ndata = b\"\".join(chunks)\nout = os.open(snapshot, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)\ntry:\n view = memoryview(data)\n while view:\n written = os.write(out, view)\n view = view[written:]\nfinally:\n os.close(out)\nprint(hashlib.sha256(data).hexdigest())\nPY\n)\" || { log \"unit packet could not be snapshotted safely\"; exit 2; }\n[ \"$OBSERVED_PACKET_DIGEST\" = \"$EXPECTED_PACKET_DIGEST\" ] || {\n log \"unit packet digest mismatch (expected $EXPECTED_PACKET_DIGEST, observed $OBSERVED_PACKET_DIGEST)\"\n exit 2\n}\n\nredact_stream() {\n CE_WORK_REDACT_FILE=\"${CE_WORK_REDACT_FILE:-}\" \"$PY\" -c '\nimport json, os, sys\n\n# The ACP stream is JSON, so a value is also matched in its escaped forms.\ndef forms(value):\n yield value\n try:\n text = value.decode(\"utf-8\")\n except UnicodeDecodeError:\n return\n yield json.dumps(text, ensure_ascii=False)[1:-1].encode(\"utf-8\")\n yield json.dumps(text)[1:-1].encode(\"ascii\")\n\np = os.environ.get(\"CE_WORK_REDACT_FILE\", \"\")\nif p:\n try:\n values = sorted(\n {form for v in open(p, \"rb\").read().splitlines() if v for form in forms(v)},\n key=lambda value: (-len(value), value),\n )\n except OSError:\n values = []\nelse:\n values = []\n\ndef emit(data):\n while data:\n written = os.write(sys.stdout.fileno(), data)\n data = data[written:]\n\npending = b\"\"\nmax_value_bytes = max((len(value) for value in values), default=1)\ntry:\n if not values:\n while True:\n chunk = os.read(sys.stdin.fileno(), 65536)\n if not chunk:\n break\n emit(chunk)\n sys.exit(0)\n\n while True:\n chunk = os.read(sys.stdin.fileno(), 65536)\n if not chunk:\n break\n pending += chunk\n offset = 0\n output = bytearray()\n while len(pending) - offset >= max_value_bytes:\n match = next((value for value in values if pending.startswith(value, offset)), None)\n if match is not None:\n output.extend(b\"[REDACTED]\")\n offset += len(match)\n else:\n output.append(pending[offset])\n offset += 1\n emit(bytes(output))\n pending = pending[offset:]\n offset = 0\n output = bytearray()\n while offset \u003c len(pending):\n match = next((value for value in values if pending.startswith(value, offset)), None)\n if match is not None:\n output.extend(b\"[REDACTED]\")\n offset += len(match)\n else:\n output.append(pending[offset])\n offset += 1\n emit(bytes(output))\nexcept BrokenPipeError:\n os._exit(0)\n'\n}\n\ncap_stream() {\n \"$PY\" -c '\nimport os, sys\n\nremaining = int(sys.argv[1])\nwhile True:\n chunk = os.read(sys.stdin.fileno(), 65536)\n if not chunk:\n break\n if remaining:\n retained = chunk[:remaining]\n while retained:\n written = os.write(sys.stdout.fileno(), retained)\n retained = retained[written:]\n remaining -= min(len(chunk), remaining)\n' \"$MAX_RAW_BYTES\"\n}\n\n{\n cat \"$PERSONA\"\n if [ \"$ROUTE\" = codex ]; then\n printf '\\n\\nSocket binds, OS permission checks, peer credentials, and similar capability probes are host-owned. Preserve the host command and observed result; do not treat a sandbox EPERM as proof the host lacks the capability.\\n'\n fi\n printf '\\n\\nThe required final-result JSON schema is:\\n\\n'\n cat \"$SCHEMA\"\n printf '\\n\\n--- BOUNDED IMPLEMENTATION UNIT PACKET ---\\n\\n'\n redact_stream \u003c \"$PACKET_SNAPSHOT\"\n} > \"$PROMPT_FILE\"\nchmod 600 \"$PROMPT_FILE\"\n\nTARGET=\"$AUTH_TARGET\"\nHARNESS=\"$AUTH_HARNESS\"\n\npublish_unavailable() {\n local reason terminal_status=\"${2:-unavailable}\" actual_route=\"${3:-}\"\n # Failure evidence can quote the stream, so it is redacted like the log.\n reason=\"$(printf '%s' \"$1\" | redact_stream)\"\n if [ \"$LOG_RETAINED\" -ne 1 ]; then\n printf '%s\\n' \"$reason\" | write_adapter_log || {\n log \"result dir or adapter log identity changed during route\"\n exit 2\n }\n LOG_RETAINED=1\n fi\n \"$PY\" - \"$ROUTE\" \"$TARGET\" \"$HARNESS\" \"$MODEL_REQUESTED\" \"$EXPECTED_PACKET_DIGEST\" \"$LOG_FILE\" \"$reason\" \"$ACTIVITY_POSTURE\" \"$RESTRICTION_POSTURE\" \"$terminal_status\" \"$actual_route\" \"$EFFORT_REQUESTED\" \u003c\u003c'PY' | write_result_receipt\nimport json, sys\nroute, target, harness, requested, packet_digest, log, reason, activity, restriction, terminal_status, actual_route, effort = sys.argv[1:]\nvalue = {\n \"schema_version\": 1, \"terminal_status\": terminal_status,\n \"summary\": \"External route failed after launch\" if terminal_status == \"failed\" else \"External route unavailable\",\n \"changed_files\": [], \"evidence\": [], \"scope_expansion\": None,\n \"requested_route\": route, \"actual_route\": actual_route or None, \"target\": target, \"harness\": harness,\n \"intermediaries\": [\"cursor\"] if route in (\"composer\", \"grok-cursor\") else [],\n \"model_requested\": requested, \"model_actual\": \"unverified\", \"model_receipt_status\": \"unverified\",\n \"effort_requested\": effort or None,\n \"packet_digest\": packet_digest,\n \"activity_posture\": activity, \"restriction_posture\": restriction,\n \"failure_reason\": reason, \"raw_log\": log,\n}\njson.dump(value, sys.stdout, indent=2)\nsys.stdout.write(\"\\n\")\nPY\n}\n\nif [ \"${CE_WORK_REQUIRE_ENFORCED_CONFINEMENT:-}\" = \"1\" ] && [ \"$RESTRICTION_POSTURE\" != adapter-enforced ]; then\n publish_unavailable \"route offers cooperative workspace restriction, not required enforceable confinement\" || exit 2\n exit 2\nfi\n\nvalidate_effort_override \"$ROUTE\" || {\n publish_unavailable \"effort override '$EFFORT_REQUESTED' not compatible with route '$ROUTE'\" || exit 2\n exit 2\n}\n\n# The Codex desktop app (Codex.app, or ChatGPT.app since the July 2026 merger)\n# ships `codex` at Contents/Resources without linking it onto PATH (#1272).\n# Append, never prepend, so a PATH-installed CLI stays authoritative.\n# CROSS_MODEL_CODEX_APP_DIRS (colon-separated) overrides the probed dirs.\nif ! command -v codex >/dev/null 2>&1; then\n OLDIFS=\"$IFS\"; IFS=':'\n for d in ${CROSS_MODEL_CODEX_APP_DIRS-\"${HOME:-}/Applications/ChatGPT.app/Contents/Resources:/Applications/ChatGPT.app/Contents/Resources:${HOME:-}/Applications/Codex.app/Contents/Resources:/Applications/Codex.app/Contents/Resources\"}; do\n if [ -n \"$d\" ] && [ -x \"$d/codex\" ]; then PATH=\"${PATH:+$PATH:}$d\"; export PATH; break; fi\n done\n IFS=\"$OLDIFS\"\nfi\n\n# Nothing is sent to a provider before this point.\nif ! command -v jq >/dev/null 2>&1; then\n publish_unavailable \"transport unavailable (pre-egress, shared): jq not found; the ACP stream is read with jq\" || exit 2\n exit 2\nfi\nacpx_preflight \"$ROUTE\" \"$WORKSPACE\" || {\n publish_unavailable \"transport unavailable (pre-egress, $ACPX_SCOPE): $ACPX_UNAVAILABLE\" || exit 2\n exit 2\n}\nif [ \"$ROUTE\" = claude ]; then\n CLAUDE_WRAPPER=\"$(acpx_claude_wrapper \"$SCRATCH\")\" || {\n publish_unavailable \"transport unavailable (pre-egress, route): cannot prepare the Claude --safe-mode launcher\" || exit 2\n exit 2\n }\nfi\nif [ \"$ROUTE\" = antigravity ]; then\n GEMINI_HOME_DIR=\"$(acpx_antigravity_home \"$SCRATCH\")\" || {\n publish_unavailable \"transport unavailable (pre-egress, route): cannot prepare a private Antigravity home\" || exit 2\n exit 2\n }\nfi\nprintf '{\"mcpServers\":[]}\\n' > \"$MCP_CONFIG\"\n\nARGS=()\nwhile IFS= read -r -d '' token; do ARGS+=(\"$token\"); done \u003c \u003c(adapter_argv \"$ROUTE\")\n\nMIN_ENV=(env -i \"PATH=$PATH\" \"PYTHONDONTWRITEBYTECODE=1\")\n[ -n \"${HOME:-}\" ] && MIN_ENV+=(\"HOME=$HOME\")\n[ -n \"${USER:-}\" ] && MIN_ENV+=(\"USER=$USER\")\n[ -n \"${TMPDIR:-}\" ] && MIN_ENV+=(\"TMPDIR=$TMPDIR\")\n[ -n \"${LANG:-}\" ] && MIN_ENV+=(\"LANG=$LANG\")\n[ -n \"${LC_ALL:-}\" ] && MIN_ENV+=(\"LC_ALL=$LC_ALL\")\n[ -n \"${XDG_CONFIG_HOME:-}\" ] && MIN_ENV+=(\"XDG_CONFIG_HOME=$XDG_CONFIG_HOME\")\n# npm reads its config file for authentication.\nfor name in npm_config_cache NPM_CONFIG_CACHE npm_config_registry NPM_CONFIG_REGISTRY npm_config_userconfig NPM_CONFIG_USERCONFIG \\\n npm_config_min_release_age NPM_CONFIG_MIN_RELEASE_AGE npm_config_before NPM_CONFIG_BEFORE \\\n npm_config_min_release_age_exclude NPM_CONFIG_MIN_RELEASE_AGE_EXCLUDE; do\n [ -n \"${!name:-}\" ] && MIN_ENV+=(\"$name=${!name}\")\ndone\n# Preserve route-specific config-directory pointers so existing CLI-native login\n# remains reachable. Credential-bearing API-key variables are intentionally not\n# forwarded; the worker gets paths to the CLI's own auth store, not secrets.\ncase \"$ROUTE\" in\n codex) [ -n \"${CODEX_HOME:-}\" ] && MIN_ENV+=(\"CODEX_HOME=$CODEX_HOME\") ;;\n claude) [ -n \"${CLAUDE_CONFIG_DIR:-}\" ] && MIN_ENV+=(\"CLAUDE_CONFIG_DIR=$CLAUDE_CONFIG_DIR\") ;;\n grok-cli) [ -n \"${GROK_CONFIG_HOME:-}\" ] && MIN_ENV+=(\"GROK_CONFIG_HOME=$GROK_CONFIG_HOME\") ;;\n opencode)\n [ -n \"${OPENCODE_CONFIG_DIR:-}\" ] && MIN_ENV+=(\"OPENCODE_CONFIG_DIR=$OPENCODE_CONFIG_DIR\")\n [ -n \"${OPENCODE_CONFIG:-}\" ] && MIN_ENV+=(\"OPENCODE_CONFIG=$OPENCODE_CONFIG\")\n ;;\n cursor|composer|grok-cursor)\n [ -n \"${CURSOR_CONFIG_DIR:-}\" ] && MIN_ENV+=(\"CURSOR_CONFIG_DIR=$CURSOR_CONFIG_DIR\")\n ;;\nesac\n\nACTIVITY_POLL_SECS=\"${CE_WORK_ACTIVITY_POLL_SECS:-15}\"\ncase \"$ACTIVITY_POLL_SECS\" in ''|*[!0-9]*) ACTIVITY_POLL_SECS=15 ;; esac\n[ \"$ACTIVITY_POLL_SECS\" -lt 1 ] && ACTIVITY_POLL_SECS=1\nMAX_RAW_BYTES=\"${CE_WORK_MAX_RAW_BYTES:-10485760}\"\ncase \"$MAX_RAW_BYTES\" in ''|*[!0-9]*) MAX_RAW_BYTES=10485760 ;; esac\n[ \"$MAX_RAW_BYTES\" -lt 1 ] && MAX_RAW_BYTES=10485760\n\nraw_byte_count() {\n local total=0 bytes file\n for file in \"$RAW_STDOUT\" \"$RAW_STDERR\"; do\n [ -f \"$file\" ] || continue\n bytes=\"$(wc -c \u003c \"$file\" | tr -d '[:space:]')\"\n case \"$bytes\" in ''|*[!0-9]*) bytes=0 ;; esac\n total=$((total + bytes))\n done\n printf '%s' \"$total\"\n}\n\nACTIVE_ROUTE_PID=\"\"\nACTIVITY_PID=\"\"\n# The route runs in its own process group (set -m below). npm launches acpx through\n# `sh -c`, and a shell that does not exec its command (Ubuntu's dash) would stop a\n# leader-only TERM short of acpx and the agent, so signal the whole group.\nstop_route() {\n kill -TERM -- -\"$1\" 2>/dev/null || kill -TERM \"$1\" 2>/dev/null || true\n}\nterminate_route() {\n [ -n \"$ACTIVITY_PID\" ] && kill \"$ACTIVITY_PID\" 2>/dev/null || true\n [ -n \"$ACTIVE_ROUTE_PID\" ] && stop_route \"$ACTIVE_ROUTE_PID\"\n [ -n \"$ACTIVE_ROUTE_PID\" ] && wait \"$ACTIVE_ROUTE_PID\" 2>/dev/null || true\n rm -rf \"$SCRATCH\"\n exit 143\n}\ntrap 'terminate_route' TERM INT\n\nset +e\n# npx resolves packages from its working directory's node_modules and .npmrc first;\n# acpx gets the agent's cwd from --cwd, so start it from private scratch.\nlaunch_route() {\n set -m\n (cd \"$SCRATCH\" && exec \"${MIN_ENV[@]}\" \"${ARGS[@]}\" \u003c /dev/null > \"$RAW_STDOUT\" 2> \"$RAW_STDERR\") &\n ACTIVE_ROUTE_PID=$!\n set +m\n (\n # A foreground sleep would outlive this subshell's TERM and hold the script's\n # output open, so callers (bun 1.4 spawnSync) would wait out the poll interval.\n # Kill every background job, so a TERM between `sleep &` and `$!` still reaps it.\n trap 'kill $(jobs -p) 2>/dev/null; exit 0' TERM\n previous=0\n session=open\n [ \"$ROUTE\" = antigravity ] && session=starting\n started=\"$(date +%s)\"\n while kill -0 \"$ACTIVE_ROUTE_PID\" 2>/dev/null; do\n current=\"$(raw_byte_count)\"\n if [ \"$current\" -gt \"$MAX_RAW_BYTES\" ]; then\n : > \"$RAW_LIMIT_MARKER\"\n log \"activity route=$ROUTE raw-output-limit bytes=$current cap=$MAX_RAW_BYTES\"\n stop_route \"$ACTIVE_ROUTE_PID\"\n break\n fi\n if [ \"$session\" != open ] && [ $(( $(date +%s) - started )) -ge \"$ACPX_SESSION_START_SECS\" ]; then\n session=\"$(acpx_session_state \"$RAW_STDOUT\")\"\n if [ \"$session\" = pending ]; then\n : > \"$SESSION_STALL_MARKER\"\n log \"Antigravity opened no session within ${ACPX_SESSION_START_SECS}s; stopping the route\"\n stop_route \"$ACTIVE_ROUTE_PID\"\n break\n fi\n fi\n if [ \"$current\" != \"$previous\" ]; then\n log \"activity route=$ROUTE output-updated\"\n previous=\"$current\"\n fi\n sleep \"$ACTIVITY_POLL_SECS\" &\n wait $!\n done\n ) &\n ACTIVITY_PID=$!\n wait \"$ACTIVE_ROUTE_PID\"\n ROUTE_EXIT=$?\n kill \"$ACTIVITY_PID\" 2>/dev/null || true\n wait \"$ACTIVITY_PID\" 2>/dev/null || true\n ACTIVE_ROUTE_PID=\"\"\n ACTIVITY_PID=\"\"\n}\nLAUNCH_STARTED=\"$(date +%s)\"\nlaunch_route\nif acpx_npm_resolution_retryable \"$RAW_STDERR\" \"$RAW_STDOUT\" && [ \"$(acpx_outcome \"$RAW_STDOUT\")\" = not-sent ]; then\n REMAINING=$(( ACPX_TIMEOUT - ( $(date +%s) - LAUNCH_STARTED ) ))\n if [ \"$REMAINING\" -gt 0 ]; then\n log \"npm could not resolve a package; retrying the same route once with fresh metadata in the ${REMAINING}s left (nothing was sent; npm policy unchanged)\"\n ACPX_NPM_REFRESH=true\n ACPX_TIMEOUT=\"$REMAINING\"\n ARGS=()\n while IFS= read -r -d '' token; do ARGS+=(\"$token\"); done \u003c \u003c(adapter_argv \"$ROUTE\")\n launch_route\n fi\nfi\nRAW_BYTES=\"$(raw_byte_count)\"\n[ \"$RAW_BYTES\" -gt \"$MAX_RAW_BYTES\" ] && : > \"$RAW_LIMIT_MARKER\"\n# acpx echoes the outbound prompt and the contents of files the agent reads, so\n# everything retained or published comes from the redacted copy. The protocol is\n# parsed from the private raw stream: a redaction value can collide with ACP text.\nredact_stream \u003c \"$RAW_STDOUT\" > \"$STREAM\"\n{\n cat \"$STREAM\"\n redact_stream \u003c \"$RAW_STDERR\"\n} | cap_stream | write_adapter_log || {\n log \"result dir or adapter log identity changed during route\"\n exit 2\n}\nLOG_RETAINED=1\n\nif [ -f \"$RAW_LIMIT_MARKER\" ]; then\n publish_unavailable \"fixed route raw output exceeded ${MAX_RAW_BYTES} bytes\" || exit 2\n exit 1\nfi\n\n# The run's outcome is its own prompt's result, not acpx's exit code.\nOUTCOME=\"$(acpx_outcome \"$RAW_STDOUT\")\"\ncase \"$OUTCOME\" in\n end_turn) ;;\n not-sent)\n # Nothing reached the provider: npm could not fetch acpx (every route fails\n # alike), or the adapter refused before the prompt (this route only).\n REASON=\"$(acpx_npm_failure_reason \"$RAW_STDERR\")\"\n if [ -n \"$REASON\" ]; then\n REASON=\"transport unavailable (pre-egress, shared): ${REASON:0:200}\"\n elif [ -f \"$SESSION_STALL_MARKER\" ]; then\n REASON=\"$SIGN_IN_STALL_REASON\"\n else\n node_line=\"$(acpx_node_startup_line \"$RAW_STDERR\")\"\n if [ -n \"$node_line\" ]; then\n REASON=\"transport unavailable (pre-egress, route): ${node_line:0:200}\"\n else\n REASON=\"$(acpx_npm_failure_reason \"$RAW_STDOUT\")\"\n [ -n \"$REASON\" ] || REASON=\"$(acpx_failure_evidence \"$STREAM\")\"\n REASON=\"transport unavailable (pre-egress, route): ${REASON:-acpx exited $ROUTE_EXIT before sending the prompt}\"\n fi\n fi\n publish_unavailable \"$REASON\" || exit 2\n exit 2\n ;;\n *)\n REASON=\"$(acpx_permission_cancel_reason \"$RAW_STDOUT\" \"$ROUTE_EXIT\")\"\n [ -n \"$REASON\" ] || REASON=\"$(acpx_failure_evidence \"$STREAM\")\"\n publish_unavailable \"fixed route ended with $OUTCOME (acpx exit $ROUTE_EXIT)${REASON:+: $REASON}\" failed \"$ROUTE\" || exit 2\n exit 1\n ;;\nesac\n\n# The reply and served models are redacted with the rest of the receipt below.\nacpx_text \"$RAW_STDOUT\" \"$REPLY_TEXT\"\nacpx_served_models \"$RAW_STDOUT\" > \"$SERVED_MODELS\"\nset +e\nCE_WORK_REDACT_FILE=\"${CE_WORK_REDACT_FILE:-}\" \"$PY\" - \\\n \"$REPLY_TEXT\" \"$SERVED_MODELS\" \"$ROUTE\" \"$TARGET\" \"$HARNESS\" \\\n \"$MODEL_REQUESTED\" \"$EXPECTED_PACKET_DIGEST\" \"$LOG_FILE\" \"$ACTIVITY_POSTURE\" \"$RESTRICTION_POSTURE\" \"$EFFORT_REQUESTED\" \\\n \"$(acpx_reply_evidence \"$RAW_STDOUT\")\" \"$(acpx_advertised_models \"$RAW_STDOUT\")\" \u003c\u003c'PY' | write_result_receipt\nimport json, os, re, sys\nreply, served_models, route, target, harness, requested, packet_digest, log, activity, restriction, effort, reply_evidence, advertised = sys.argv[1:]\n\ndef redactions():\n p=os.environ.get(\"CE_WORK_REDACT_FILE\", \"\")\n if not p: return []\n try: return sorted(set(v for v in open(p, encoding=\"utf-8\").read().splitlines() if v), key=lambda value: (-len(value), value))\n except OSError: return []\n\nredaction_values=redactions()\n\ndef redact(value):\n if isinstance(value,str):\n for secret in redaction_values: value=value.replace(secret, \"[REDACTED]\")\n return value\n if isinstance(value,list): return [redact(child) for child in value]\n if isinstance(value,dict): return {key:redact(child) for key,child in value.items()}\n return value\n\ndef parse_text(text):\n found=[]\n decoder=json.JSONDecoder()\n def inspect(value):\n if isinstance(value,dict):\n if all(k in value for k in (\"terminal_status\",\"summary\",\"changed_files\",\"evidence\",\"scope_expansion\")):\n found.append(value)\n for child in value.values(): inspect(child)\n elif isinstance(value,list):\n for child in value: inspect(child)\n elif isinstance(value,str):\n inner=re.sub(r\"^```(?:json)?\\s*|\\s*```$\", \"\", value.strip(), flags=re.S)\n for i,ch in enumerate(inner):\n if ch not in \"[{\": continue\n try:\n child,_=decoder.raw_decode(inner,i); inspect(child)\n except Exception: pass\n inspect(text)\n for line in text.splitlines():\n try: inspect(json.loads(line))\n except Exception: pass\n return found[-1] if found else None\n\ndef normalize_served_model(value):\n # Strip terminal control sequences before validating the receipt token;\n # never publish a partially sanitized or otherwise unsafe identity.\n text=str(value)\n text=re.sub(r\"\\x1b\\[[0-?]*[ -/]*[@-~]\", \"\", text)\n text=re.sub(r\"\\x1b\\][^\\x07\\x1b]*(?:\\x07|\\x1b\\\\)\", \"\", text)\n text=\"\".join(ch for ch in text if ord(ch) >= 0x20 and ord(ch) != 0x7f).strip()\n return text if 0 \u003c len(text) \u003c= 128 else \"unverified\"\n\ntry: text=open(reply, encoding=\"utf-8\", errors=\"replace\").read()\nexcept OSError: text=\"\"\nworker=parse_text(text)\nvalid=isinstance(worker,dict)\nworker_fields=(\"terminal_status\", \"summary\", \"changed_files\", \"evidence\", \"scope_expansion\")\nif valid:\n valid=(set(worker) == set(worker_fields)\n and worker.get(\"terminal_status\") in (\"completed\",\"blocked\",\"scope_expansion\")\n and isinstance(worker.get(\"summary\"),str) and bool(worker[\"summary\"])\n and isinstance(worker.get(\"changed_files\"),list) and all(isinstance(x,str) and x for x in worker[\"changed_files\"])\n and isinstance(worker.get(\"evidence\"),list) and all(isinstance(x,str) and x for x in worker[\"evidence\"])\n and ((worker[\"terminal_status\"]==\"scope_expansion\" and isinstance(worker.get(\"scope_expansion\"),dict))\n or (worker[\"terminal_status\"]!=\"scope_expansion\" and worker.get(\"scope_expansion\") is None)))\n\n# The adapter's _meta report is its own assertion of the served model, so a\n# match is recorded as \"asserted\", never \"verified\". Requested and served ids\n# are compared on the model id before any Cursor preset bracket; an alias\n# names its Claude family. An auxiliary model (Claude's Haiku) may also be\n# reported, so a served id in the requested family wins, else the heaviest.\nserved=[]\ntry:\n for line in open(served_models, encoding=\"utf-8\", errors=\"replace\").read().splitlines():\n model, _, tokens = line.rpartition(\" \")\n model=normalize_served_model(model)\n if model != \"unverified\":\n served.append((model, int(tokens) if tokens.isdigit() else 0))\nexcept OSError:\n pass\nmodel_base=lambda value: value.split(\"[\",1)[0].lower()\nfamily=model_base(requested)\nif family in (\"fable\",\"opus\",\"sonnet\",\"haiku\"): family=\"claude-\"+family\nin_family=[m for m,_ in served if model_base(m)==family or model_base(m).startswith(family+\"-\")]\nif not served: actual, receipt = \"unverified\", \"unverified\"\nelif requested == \"auto\": actual, receipt = max(served, key=lambda item: item[1])[0], \"asserted\"\nelif in_family: actual, receipt = in_family[0], \"asserted\"\nelse: actual, receipt = max(served, key=lambda item: item[1])[0], \"mismatch\"\n\nintermediaries=[\"cursor\"] if route in (\"composer\",\"grok-cursor\") else []\nbase_receipt={\n \"schema_version\":1,\n \"requested_route\":route, \"actual_route\":route, \"target\":target, \"harness\":harness,\n \"intermediaries\":intermediaries, \"model_requested\":requested, \"model_actual\":actual,\n \"model_receipt_status\":receipt, \"effort_requested\":effort or None, \"activity_posture\":activity,\n \"packet_digest\":packet_digest,\n \"restriction_posture\":restriction,\n \"failure_reason\":None, \"raw_log\":log,\n}\nif valid:\n base_receipt.update({key:worker[key] for key in worker_fields})\nelse:\n base_receipt.update({\"terminal_status\":\"failed\", \"summary\":\"Adapter terminal output failed result schema\",\n \"changed_files\":[], \"evidence\":[], \"scope_expansion\":None,\n \"failure_reason\":\"; \".join([\"terminal output failed implementation result schema\"]\n + ([f\"reply: {reply_evidence}\"] if reply_evidence else [])\n + ([f\"advertised models: {advertised}\"] if advertised else []))})\nbase_receipt=redact(base_receipt)\njson.dump(base_receipt,sys.stdout,indent=2)\nsys.stdout.write(\"\\n\")\nsys.exit(0 if valid else 4)\nPY\nNORMALIZE_STATUSES=(\"${PIPESTATUS[@]}\")\nNORMALIZE_EXIT=\"${NORMALIZE_STATUSES[0]}\"\nPUBLISH_EXIT=\"${NORMALIZE_STATUSES[1]}\"\nif [ \"$PUBLISH_EXIT\" -ne 0 ]; then exit 2; fi\nif [ \"$NORMALIZE_EXIT\" -ne 0 ]; then exit 1; fi\n\nTERMINAL_STATUS=\"$(\"$PY\" -c 'import json,sys; print(json.load(open(sys.argv[1]))[\"terminal_status\"])' \"$RESULT_FILE\")\"\ncase \"$TERMINAL_STATUS\" in\n completed|blocked|scope_expansion) exit 0 ;;\n *) exit 1 ;;\nesac\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":62397,"content_sha256":"2a0d8b0b6a8eb2b137b56072cfb134afa3ad41faaea3e337743adbc42677403b"},{"filename":"scripts/packs-resolve.py","content":"#!/usr/bin/env python3\n\"\"\"Resolve the Compound Packs declared in this repo's CE config into pack roots.\n\nReads the `packs:` list from `\u003crepo-root>/.compound-engineering/config.yaml`\nand `config.local.yaml` (both layers concatenate; local adds, never replaces),\nvalidates each entry, resolves path and git sources, enumerates the packs each\nsource publishes, applies selection, and prints one JSON object to stdout:\n\n {\"roots\": [{\"id\": \"...\", \"dir\": \"/abs/path\", \"nested_rule_shaped\": 0}],\n \"warnings\": [...], \"errors\": [...], \"entries\": \u003cnumber of parsed packs entries>}\n\n`nested_rule_shaped` counts the rule-shaped `.md` files one level below the\npack's top level. Discovery never reads them (subdirectories are storage), so\nthe count is informational and is reported by the health check, not warned.\n\nExit 0 whenever resolution ran (per-entry failures are data in `errors` /\n`warnings`); non-zero only when the resolver itself cannot run. Consumers treat\n`errors` as loud per-entry configuration problems and `warnings` as degraded\navailability (e.g. an unreachable git source skipped per the warn-and-continue\ncontract).\n\n`--declared-only` answers the config-only question without touching git or the\ncache: it parses both config layers, shape-checks each entry, and prints\n\n {\"declared\": \u003cbool|null>, \"entries\": \u003cn>, \"errors\": [...]}\n\nwhere `declared` is true when any entry parsed or the `packs:` block is\nmalformed (a broken declaration is still a declaration the consumer should\nsurface), false when neither config layer names packs, and null when no\nrepository -- and so no config -- could be located.\n\nEntry shape (documented subset -- anything else under `packs:` is a loud error):\n\n packs:\n - source: packs/local-rules # repo-relative path\n - source: ~/packs/kk-style # ~ or absolute path\n - source: https://github.com/o/r # git URL: ref required\n ref: v1.2.0 # tag, sha, or branch\n path: packs # optional subfolder (git only)\n pack: [rails, inertia] # one id, a list, or omit = all\n id: rails-core # rename (single-pack entries)\n - source: https://github.com/o/r/tree/main/packs # tree-URL sugar\n\nGit sources cache under `\u003cscratch-root>/ce-packs/\u003csha256(url\\\\nref)>` with an\natomic temp-clone-then-rename, so a keyed path's existence proves a complete\nclone. All git subprocesses run non-interactively (GIT_TERMINAL_PROMPT=0, ssh\nBatchMode, bounded timeout): missing credentials degrade to a warning, never a\nhang. A missing `git` binary degrades git sources only (each warns and is\nskipped); path sources still resolve, with the repository located by walking up\nfrom the working directory to the nearest `.git` entry. Environment overrides:\nCE_PACKS_CACHE_ROOT (cache base for tests), CE_PACKS_GIT_TIMEOUT (seconds,\ndefault 60).\n\nA published pack is a directory a consumer lists and reads itself, so nothing\nin it may link outside its source: a pack whose tree holds such a link is not\npublished (a loud per-entry error), never trimmed a file at a time.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport functools\nimport hashlib\nimport json\nimport os\nimport re\nimport shutil\nimport stat\nimport subprocess\nimport sys\nimport tempfile\n\nIS_WINDOWS = os.name == \"nt\"\n_uid_getter = getattr(os, \"geteuid\", None) or getattr(os, \"getuid\", None)\n_EFFECTIVE_UID = _uid_getter() if _uid_getter is not None else None\nGIT_TIMEOUT = float(os.environ.get(\"CE_PACKS_GIT_TIMEOUT\") or 60)\n\nCONFIG_FILES = (\"config.yaml\", \"config.local.yaml\")\nKNOWN_KEYS = {\"source\", \"ref\", \"path\", \"pack\", \"id\"}\nSCALAR_KEYS = (\"source\", \"ref\", \"path\", \"id\") # every known key but the list-valued `pack`\n_TREE_URL_RE = re.compile(\n r\"^(?P\u003cbase>https?://github\\.com/[^/\\s]+/[^/\\s]+?)(?:\\.git)?/tree/(?P\u003cref>[^/\\s]+)(?:/(?P\u003cpath>[^\\s]*))?/?$\"\n)\n\n\ndef _is_git_url(source: str) -> bool:\n return bool(\n re.match(r\"^(https?|ssh|git|file)://\", source) or re.match(r\"^[\\w.-]+@[\\w.-]+:\", source)\n )\n\n\ndef _within(path: str, parent: str) -> bool:\n \"\"\"True when `path` is `parent` or lies below it (both already realpath'd).\"\"\"\n return path == parent or path.startswith(parent + os.sep)\n\n\n# --- scratch root (peer-job-runner shape: probe /tmp, fall back to TMPDIR) ---\n\ndef _owned_dir(path: str) -> bool:\n \"\"\"Directory, not a symlink, owned by the effective uid (POSIX).\"\"\"\n try:\n st = os.lstat(path)\n except OSError:\n return False\n if not stat.S_ISDIR(st.st_mode):\n return False\n if _EFFECTIVE_UID is not None and st.st_uid != _EFFECTIVE_UID:\n return False\n return True\n\n\ndef _private_root_usable(path: str) -> bool:\n \"\"\"Create or repair `path` as a private (0700) root owned by this user.\"\"\"\n try:\n os.mkdir(path, 0o700)\n except FileExistsError:\n pass\n except OSError:\n return False\n if not IS_WINDOWS:\n if not _owned_dir(path):\n return False\n try:\n os.chmod(path, 0o700)\n except OSError:\n return False\n return os.path.isdir(path) and os.access(path, os.W_OK)\n\n\ndef _trusted_checkout(path: str) -> bool:\n \"\"\"A real directory (never a symlink) that this user owns; ownership is POSIX-only.\"\"\"\n if os.path.islink(path) or not os.path.isdir(path):\n return False\n return IS_WINDOWS or _owned_dir(path)\n\n\[email protected]_cache(maxsize=None)\ndef cache_base() -> str | None:\n configured = os.environ.get(\"CE_PACKS_CACHE_ROOT\")\n if configured:\n root = os.path.abspath(configured)\n os.makedirs(root, exist_ok=True)\n return root\n if IS_WINDOWS:\n base = os.environ.get(\"LOCALAPPDATA\") or tempfile.gettempdir()\n root = os.path.join(base, \"compound-engineering-packs\")\n return root if _private_root_usable(root) else None\n if _EFFECTIVE_UID is None:\n return None\n for base in (\"/tmp\", os.environ.get(\"TMPDIR\") or \"/tmp\"):\n root = os.path.join(base, f\"compound-engineering-{_EFFECTIVE_UID}\")\n if _private_root_usable(root):\n packs = os.path.join(root, \"ce-packs\")\n if _private_root_usable(packs):\n return packs\n return None\n\n\n# --- minimal YAML reader for the documented packs: subset --------------------\n\ndef _strip_comment(line: str) -> str:\n \"\"\"Drop a trailing comment (a # preceded by whitespace, outside quotes).\n\n A quote toggles quoted state only when it opens a value (start of line or\n after `: `/`- `/`[`/`,`) or closes one it opened -- a mid-word apostrophe\n (``it's``) is ordinary content and must not absorb a later comment.\n \"\"\"\n out, quote = [], \"\"\n for i, ch in enumerate(line):\n prev = line[i - 1] if i else \" \"\n if quote:\n if ch == quote:\n quote = \"\"\n elif ch in \"'\\\"\" and prev in \" \\t[,:\":\n quote = ch\n elif ch == \"#\" and prev in \" \\t\":\n break\n out.append(ch)\n return \"\".join(out).rstrip()\n\n\ndef _scalar(raw: str):\n raw = raw.strip()\n if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in \"'\\\"\":\n return raw[1:-1]\n if raw.lower() in (\"true\", \"false\"):\n return raw.lower() == \"true\"\n return raw\n\n\ndef _parse_value(raw: str):\n raw = raw.strip()\n if raw.startswith(\"[\") and raw.endswith(\"]\"):\n inner = raw[1:-1].strip()\n return [] if not inner else [_scalar(part) for part in inner.split(\",\")]\n return _scalar(raw)\n\n\ndef parse_packs_block(path: str, errors: list) -> list:\n \"\"\"Return the entry dicts under this file's top-level `packs:` key.\"\"\"\n if not os.path.isfile(path):\n return []\n with open(path, encoding=\"utf-8-sig\", errors=\"replace\") as fh:\n lines = fh.read().splitlines()\n entries, in_packs, current, pending_list_key = [], False, None, None\n for lineno, raw in enumerate(lines, 1):\n line = _strip_comment(raw)\n if not line.strip():\n continue\n indent = len(line) - len(line.lstrip())\n if indent == 0 and not (in_packs and line.lstrip().startswith(\"-\")):\n # A new top-level key ends the packs block; a zero-indent list item\n # (`- source: ...`) is still part of it -- YAML allows both styles.\n key, sep, rest = line.partition(\":\")\n in_packs = bool(sep) and key.strip() == \"packs\" and rest.strip() in (\"\", \"[]\")\n if sep and key.strip() == \"packs\" and not in_packs:\n # `packs: \u003cinline value>` is malformed, not absent: say so rather\n # than letting a flow list or a bare path declare nothing.\n errors.append(\n f\"{os.path.basename(path)}:{lineno}: `packs:` must be a block list of\"\n f\" `- source: ...` entries (got `{line.strip()}`)\"\n )\n current, pending_list_key = None, None\n continue\n if not in_packs:\n continue\n stripped = line.strip()\n loc = f\"{os.path.basename(path)}:{lineno}\"\n if stripped.startswith(\"- \") or stripped == \"-\":\n body = stripped[1:].strip()\n if pending_list_key and current is not None and \":\" not in body:\n current[pending_list_key].append(_scalar(body))\n continue\n current, pending_list_key = {\"_origin\": os.path.basename(path), \"_line\": lineno}, None\n entries.append(current)\n if body:\n if \":\" not in body:\n errors.append(f\"{loc}: unrecognized packs entry `{stripped}` -- expected `key: value`\")\n continue\n key, _, val = body.partition(\":\")\n _set_key(current, key.strip(), val, loc, errors)\n continue\n if current is None:\n errors.append(f\"{loc}: unrecognized line under packs: `{stripped}` -- expected a `- source: ...` entry\")\n continue\n if \":\" not in stripped:\n errors.append(f\"{loc}: unrecognized line under packs: `{stripped}` -- expected `key: value`\")\n continue\n key, _, val = stripped.partition(\":\")\n key = key.strip()\n if val.strip() == \"\" and key == \"pack\":\n current[key] = []\n pending_list_key = key\n continue\n pending_list_key = None\n _set_key(current, key, val, loc, errors)\n return entries\n\n\ndef _set_key(entry: dict, key: str, raw_val: str, loc: str, errors: list) -> None:\n if key not in KNOWN_KEYS:\n errors.append(f\"{loc}: unknown packs entry key `{key}:` -- accepted keys: {', '.join(sorted(KNOWN_KEYS))}\")\n return\n entry[key] = _parse_value(raw_val)\n\n\n# --- git ---------------------------------------------------------------------\n\[email protected]_cache(maxsize=None)\ndef _git_env() -> dict:\n env = dict(os.environ)\n env[\"GIT_TERMINAL_PROMPT\"] = \"0\"\n env[\"GIT_ASKPASS\"] = env.get(\"GIT_ASKPASS\") or \"true\"\n ssh = env.get(\"GIT_SSH_COMMAND\") or \"ssh\"\n if \"BatchMode\" not in ssh:\n env[\"GIT_SSH_COMMAND\"] = ssh + \" -o BatchMode=yes\"\n return env\n\n\ndef _run_git(args: list, cwd: str | None = None):\n return subprocess.run(\n [\"git\", *args], cwd=cwd, env=_git_env(), timeout=GIT_TIMEOUT,\n capture_output=True, text=True,\n )\n\n\ndef resolve_git_source(url: str, ref: str, warnings: list, label: str) -> str | None:\n \"\"\"Return the cached checkout dir for url@ref, cloning on miss. None = warn+skip.\"\"\"\n if shutil.which(\"git\") is None:\n warnings.append(f\"{label}: git binary not found; source skipped\")\n return None\n base = cache_base()\n if base is None:\n warnings.append(f\"{label}: no writable cache root for git sources; source skipped\")\n return None\n key = hashlib.sha256(f\"{url}\\n{ref}\".encode()).hexdigest()\n dest = os.path.join(base, key)\n if os.path.lexists(dest):\n if _trusted_checkout(dest):\n return dest\n warnings.append(f\"{label}: cached checkout {dest} is a symlink or not owned by this user; refetching\")\n # rmtree refuses to follow a symlink (and ignores a plain file); unlink\n # those explicitly so a planted link is removed, never its target.\n shutil.rmtree(dest, ignore_errors=True)\n if os.path.islink(dest) or os.path.isfile(dest):\n try:\n os.unlink(dest)\n except OSError:\n pass\n if os.path.lexists(dest):\n warnings.append(f\"{label}: cannot replace untrusted cached checkout {dest}; source skipped\")\n return None\n tmp = tempfile.mkdtemp(prefix=f\"{key}.part-\", dir=base)\n try:\n try:\n proc = _run_git([\"clone\", \"--quiet\", \"--depth\", \"1\", \"--no-recurse-submodules\",\n \"--branch\", ref, \"--end-of-options\", url, tmp])\n except subprocess.TimeoutExpired:\n warnings.append(f\"{label}: git clone timed out after {int(GIT_TIMEOUT)}s; source skipped\")\n return None\n if proc.returncode != 0:\n # tag/branch clone failed -- retry treating ref as a commit sha\n try:\n fetched = (\n _run_git([\"init\", \"--quiet\", tmp]).returncode == 0\n and _run_git([\"fetch\", \"--quiet\", \"--depth\", \"1\", \"--end-of-options\", url, ref], cwd=tmp).returncode == 0\n and _run_git([\"checkout\", \"--quiet\", \"FETCH_HEAD\"], cwd=tmp).returncode == 0\n )\n if not fetched:\n warnings.append(f\"{label}: cannot fetch `{ref}` from {url}; source skipped\")\n return None\n except subprocess.TimeoutExpired:\n warnings.append(f\"{label}: git fetch timed out after {int(GIT_TIMEOUT)}s; source skipped\")\n return None\n if not os.path.lexists(dest):\n try:\n os.replace(tmp, dest)\n except OSError:\n # Expected when another resolver published the same key\n # concurrently; anything else leaves no checkout to return.\n if not os.path.lexists(dest):\n warnings.append(f\"{label}: could not publish the clone to {dest}; source skipped\")\n return None\n if _trusted_checkout(dest):\n return dest\n warnings.append(\n f\"{label}: cached checkout {dest} appeared during the clone and is a symlink or not owned by this user; source skipped\"\n )\n return None\n finally:\n if os.path.isdir(tmp):\n shutil.rmtree(tmp, ignore_errors=True)\n\n\n# --- pack enumeration --------------------------------------------------------\n\n_FRONTMATTER_KEYS = (\"title:\", \"applies_when:\")\n_FRONTMATTER_CAP = 64 * 1024 # frontmatter must close within this many characters\n# A pack's README is its description, never a rule, whatever frontmatter it\n# carries: it is not published, not reported as skipped, and not counted.\n_README = \"readme.md\"\n\n\[email protected]_cache(maxsize=None)\ndef _is_knowledge_file(path: str) -> bool:\n \"\"\"True when the file opens with a `---` frontmatter block, closed by a `---`\n line within the cap, that carries `title:` and `applies_when:`. A UTF-8 BOM\n is not part of the content.\"\"\"\n try:\n with open(path, encoding=\"utf-8-sig\", errors=\"replace\") as fh:\n lines = fh.read(_FRONTMATTER_CAP).splitlines()\n except OSError:\n return False\n if not lines or lines[0].strip() != \"---\":\n return False\n for end, line in enumerate(lines[1:], 1):\n if line.strip() == \"---\":\n fm = \"\\n\".join(lines[1:end])\n break\n else:\n return False\n return all(re.search(rf\"^\\s*{re.escape(k)}\", fm, re.MULTILINE) for k in _FRONTMATTER_KEYS)\n\n\ndef _contained_md_files(directory: str, boundary: str, escaped: list) -> list:\n \"\"\"Paths of the `.md` entries directly under `directory`, minus its README,\n whose real path stays within `boundary` (a realpath). An entry that links\n outside it is appended to `escaped` and never opened, so a pack cannot read\n files off the user's machine.\"\"\"\n try:\n names = sorted(os.listdir(directory))\n except OSError:\n return []\n files = []\n for name in names:\n if not name.endswith(\".md\") or name.lower() == _README:\n continue\n child = os.path.join(directory, name)\n if _within(os.path.realpath(child), boundary):\n files.append(child)\n else:\n escaped.append(child)\n return files\n\n\ndef _contained_child_dirs(directory: str, boundary: str, escaped: list) -> list:\n \"\"\"`(name, path)` of the non-hidden directories directly under `directory`\n whose real path stays within `boundary`; one that links outside it is\n appended to `escaped` and never entered.\"\"\"\n try:\n names = sorted(os.listdir(directory))\n except OSError:\n return []\n dirs = []\n for name in names:\n child = os.path.join(directory, name)\n if name.startswith(\".\") or not os.path.isdir(child):\n continue\n if _within(os.path.realpath(child), boundary):\n dirs.append((name, child))\n else:\n escaped.append(child)\n return dirs\n\n\ndef _has_knowledge_files(directory: str, boundary: str, escaped: list) -> bool:\n return any(_is_knowledge_file(f) for f in _contained_md_files(directory, boundary, escaped))\n\n\ndef _escaping_links(root: str, boundary: str) -> list:\n \"\"\"Symlinks anywhere under `root` (walked without following links) whose real\n path leaves `boundary`, sorted. Only a link can leave: every other entry sits\n under `root`, which is already inside the boundary.\"\"\"\n leaks = []\n for dirpath, dirnames, filenames in os.walk(root, followlinks=False):\n for name in dirnames + filenames:\n child = os.path.join(dirpath, name)\n if os.path.islink(child) and not _within(os.path.realpath(child), boundary):\n leaks.append(child)\n return sorted(leaks)\n\n\ndef enumerate_packs(source_root: str, boundary: str, escaped: list, self_name: str | None = None) -> dict:\n \"\"\"Map published pack id -> dir. Immediate children only; self = single pack.\n\n `boundary` is the realpath every child directory and rule file must stay\n within (the git checkout, the repository, or the source root itself); a\n child that links outside it is recorded in `escaped` and skipped. Symlinks\n that stay inside the boundary are ordinary content.\n \"\"\"\n if _has_knowledge_files(source_root, boundary, escaped):\n name = self_name or os.path.basename(os.path.abspath(source_root))\n return {name: source_root}\n return {\n name: child\n for name, child in _contained_child_dirs(source_root, boundary, escaped)\n if _has_knowledge_files(child, boundary, escaped)\n }\n\n\ndef nested_rule_shaped(pack_dir: str, boundary: str) -> tuple:\n \"\"\"`(total, subdirs)`: how many rule-shaped files sit in the immediate\n subdirectories of `pack_dir`, and which subdirectories hold them. Scans one\n level down only, inside `boundary`, so the pack's data is never walked.\n Subdirectories are storage, so these files are counted, never published.\"\"\"\n hits, total = [], 0\n for name, child in _contained_child_dirs(pack_dir, boundary, []):\n count = sum(1 for f in _contained_md_files(child, boundary, []) if _is_knowledge_file(f))\n if count:\n hits.append(name)\n total += count\n return total, hits\n\n\ndef nested_rules_warning(pack_id: str, pack_dir: str, boundary: str) -> str | None:\n \"\"\"The warning for a pack directory with no rule at its top level whose\n subdirectories hold rule-shaped files: it registers, yet nothing can ever be\n discovered. None when the subdirectories hold none. The caller establishes\n that the top level is empty of rules; a pack with top-level rules keeps its\n nested files as storage and gets `nested_rule_shaped` instead.\"\"\"\n total, hits = nested_rule_shaped(pack_dir, boundary)\n if not hits:\n return None\n where = \", \".join(f\"`{name}/`\" for name in hits)\n return (\n f\"pack `{pack_id}` has {total} rule-shaped file(s) under {where} that discovery\"\n \" never reads -- move rules to the pack's top level (see https://everyinc.github.io/compound-engineering-plugin/guides/packs/, Pack layout)\"\n )\n\n\n# --- entry resolution --------------------------------------------------------\n\ndef _entry_label(entry: dict) -> str:\n return f\"{entry.get('_origin', 'config')}:{entry.get('_line', '?')}\"\n\n\ndef _entry_shape_ok(entry: dict, label: str, errors: list) -> bool:\n \"\"\"I/O-free checks on one parsed entry: `source:` present, and the scalar\n keys actually scalar. False after appending the error.\"\"\"\n for key in SCALAR_KEYS:\n val = entry.get(key)\n if val is not None and not isinstance(val, str):\n errors.append(f\"{label}: `{key}:` must be a single string (got {val!r})\")\n return False\n if not entry.get(\"source\"):\n errors.append(f\"{label}: entry has no `source:`\")\n return False\n return True\n\n\ndef resolve_entry(entry: dict, repo_root: str, roots: list, warnings: list, errors: list) -> None:\n label = _entry_label(entry)\n if not _entry_shape_ok(entry, label, errors):\n return\n source, ref, sub_path = entry[\"source\"], entry.get(\"ref\"), entry.get(\"path\")\n\n tree = _TREE_URL_RE.match(source)\n if tree:\n t_ref, t_path = tree.group(\"ref\"), tree.group(\"path\") or \"\"\n if isinstance(ref, str) and ref != t_ref:\n errors.append(f\"{label}: tree URL pins ref `{t_ref}` but entry says `ref: {ref}` -- remove one\")\n return\n if isinstance(sub_path, str) and sub_path.strip(\"/\") != t_path.strip(\"/\"):\n errors.append(f\"{label}: tree URL path `{t_path}` conflicts with `path: {sub_path}` -- remove one\")\n return\n source, ref, sub_path = tree.group(\"base\"), t_ref, t_path or None\n\n if _is_git_url(source):\n if not isinstance(ref, str) or not ref:\n errors.append(f\"{label}: git source `{source}` requires `ref:` (tag, sha, or branch)\")\n return\n if ref.startswith(\"-\") or source.startswith(\"-\"):\n errors.append(f\"{label}: git source/ref may not begin with `-`\")\n return\n checkout = resolve_git_source(source, ref, warnings, label)\n if checkout is None:\n if tree:\n warnings.append(\n f\"{label}: if the branch name contains `/`, tree-URL parsing splits it wrong -- use explicit `ref:` and `path:` fields\"\n )\n return\n git_meta = {\"url\": source, \"ref\": ref}\n source_root = os.path.join(checkout, sub_path) if sub_path else checkout\n real_root, real_checkout = os.path.realpath(source_root), os.path.realpath(checkout)\n if not _within(real_root, real_checkout):\n errors.append(f\"{label}: path `{sub_path}` escapes the source checkout\")\n return\n source_root, boundary = real_root, real_checkout\n if not os.path.isdir(source_root):\n errors.append(f\"{label}: path `{sub_path}` does not exist in {source}@{ref}\")\n return\n else:\n git_meta = None\n if ref is not None:\n errors.append(f\"{label}: `ref:` is only valid on git sources; path sources are read live\")\n return\n if sub_path is not None:\n errors.append(f\"{label}: `path:` is only valid on git sources; point `source:` at the directory instead\")\n return\n expanded = os.path.expanduser(source)\n if os.path.isabs(expanded):\n source_root = os.path.realpath(expanded)\n boundary = source_root\n else:\n source_root = os.path.realpath(os.path.join(repo_root, expanded))\n repo_real = os.path.realpath(repo_root)\n if not _within(source_root, repo_real) or _within(source_root, os.path.join(repo_real, \".git\")):\n errors.append(f\"{label}: repo-relative source `{source}` resolves outside the repository\")\n return\n boundary = repo_real\n if not os.path.isdir(source_root):\n errors.append(f\"{label}: source directory `{source}` does not exist\")\n return\n\n if git_meta:\n # Display name for a single-pack git source: the path: subfolder's\n # basename, else the URL's last path segment (never the cache key).\n tail = (sub_path or source).rstrip(\"/\").rsplit(\"/\", 1)[-1]\n self_name = re.sub(r\"\\.git$\", \"\", tail.split(\":\")[-1]) or None\n else:\n self_name = None\n escaped = []\n published = enumerate_packs(source_root, boundary, escaped, self_name)\n for link in escaped:\n warnings.append(\n f\"{label}: skipped `{os.path.relpath(link, source_root)}` in `{source}` -- it links outside the source\"\n )\n if not published:\n warnings.append(f\"{label}: source `{source}` publishes no packs (no directories with valid knowledge files)\")\n # Each child directory is a would-be pack with no top-level rule (one\n # with a rule would have published); say when its rules sit one level\n # too deep, so the author learns why nothing published.\n for name, child in _contained_child_dirs(source_root, boundary, []):\n nested = nested_rules_warning(name, child, boundary)\n if nested:\n warnings.append(f\"{label}: {nested}\")\n return\n\n selection = entry.get(\"pack\")\n if selection is None:\n selected = dict(published)\n else:\n wanted = selection if isinstance(selection, list) else [selection]\n if not wanted:\n warnings.append(f\"{label}: `pack:` lists no ids; nothing installed from `{source}`\")\n return\n missing = [w for w in wanted if w not in published]\n if missing:\n errors.append(\n f\"{label}: pack id(s) {', '.join(map(str, missing))} not published by `{source}`\"\n f\" -- available: {', '.join(sorted(published)) or 'none'}\"\n )\n return\n selected = {w: published[w] for w in wanted}\n\n override = entry.get(\"id\")\n if override is not None:\n if len(selected) != 1:\n errors.append(f\"{label}: `id:` override requires the entry to install exactly one pack\")\n return\n selected = {str(override): next(iter(selected.values()))}\n\n for pack_id, pack_dir in selected.items():\n # Consumers list the pack directory themselves, so a link that leaves\n # the source anywhere inside it would let pack content read files off\n # the user's machine: refuse the whole pack. (Top-level escapes were\n # already named as skipped during enumeration.)\n leaks = _escaping_links(pack_dir, boundary)\n if leaks:\n names = \", \".join(f\"`{os.path.relpath(p, pack_dir)}`\" for p in leaks)\n errors.append(f\"{label}: pack `{pack_id}` not published -- {names} link(s) outside the source\")\n continue\n for child in _contained_md_files(pack_dir, boundary, []):\n name = os.path.basename(child)\n if os.path.isfile(child) and not _is_knowledge_file(child):\n warnings.append(\n f\"{label}: skipped pack file `{pack_id}/{name}` (missing `title`/`applies_when` frontmatter)\"\n )\n # A published pack has a rule at its top level, so rule-shaped files in\n # its subdirectories are storage: counted for the health report, not warned.\n nested_total, _ = nested_rule_shaped(pack_dir, boundary)\n root = {\"id\": pack_id, \"dir\": pack_dir, \"nested_rule_shaped\": nested_total, \"_label\": label}\n if git_meta:\n root.update(git_meta)\n roots.append(root)\n\n\ndef _emit(declared_only: bool, entries: list, roots: list, warnings: list, errors: list,\n declared: bool | None = None) -> int:\n if declared_only:\n print(json.dumps({\"declared\": declared, \"entries\": len(entries), \"errors\": errors}))\n else:\n print(json.dumps({\n \"roots\": [{k: v for k, v in r.items() if not k.startswith(\"_\")} for r in roots],\n \"warnings\": warnings,\n \"errors\": errors,\n \"entries\": len(entries),\n }))\n return 0\n\n\ndef _repo_root() -> str | None:\n \"\"\"The enclosing checkout's top level: git's answer when git is on PATH,\n otherwise the nearest ancestor of the working directory holding a `.git`\n entry (a directory, or the file a worktree or submodule leaves). None when\n the working directory is not inside a checkout.\"\"\"\n if shutil.which(\"git\") is not None:\n proc = subprocess.run([\"git\", \"rev-parse\", \"--show-toplevel\"],\n stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True)\n return proc.stdout.strip() if proc.returncode == 0 else None\n current = os.getcwd()\n while True:\n if os.path.lexists(os.path.join(current, \".git\")):\n return current\n parent = os.path.dirname(current)\n if parent == current:\n return None\n current = parent\n\n\ndef _main(argv: list) -> int:\n parser = argparse.ArgumentParser(description=\"Resolve the Compound Packs declared in CE config.\")\n parser.add_argument(\n \"--declared-only\", action=\"store_true\",\n help=\"parse and shape-check the packs: entries only; no git or cache work\",\n )\n args = parser.parse_args(argv)\n warnings, errors, roots, entries = [], [], [], []\n\n repo_root = _repo_root()\n if repo_root is None:\n warnings.append(\"not inside a git repository; no CE config to read\")\n return _emit(args.declared_only, entries, roots, warnings, errors)\n cfg_dir = os.path.join(repo_root, \".compound-engineering\")\n for name in CONFIG_FILES:\n entries.extend(parse_packs_block(os.path.join(cfg_dir, name), errors))\n\n if args.declared_only:\n for entry in entries:\n _entry_shape_ok(entry, _entry_label(entry), errors)\n return _emit(True, entries, roots, warnings, errors, declared=bool(entries or errors))\n\n for entry in entries:\n try:\n resolve_entry(entry, repo_root, roots, warnings, errors)\n except Exception as exc: # one entry's surprise is that entry's error, not everyone's\n errors.append(f\"{_entry_label(entry)}: unexpected error resolving entry: {exc}\")\n\n # First declaration wins: config.yaml entries precede config.local.yaml in\n # CONFIG_FILES, so a personal pack can never displace the team's.\n by_id = {}\n final = []\n for root in roots:\n prev = by_id.get(root[\"id\"])\n if prev is not None:\n errors.append(\n f\"duplicate pack id `{root['id']}`: {root['_label']} ignored, {prev['_label']} kept\"\n \" -- rename one with `id:`\"\n )\n continue\n by_id[root[\"id\"]] = root\n final.append(root)\n return _emit(False, entries, final, warnings, errors)\n\n\ndef main() -> int:\n try:\n return _main(sys.argv[1:])\n except Exception as exc: # never a traceback: consumers need valid JSON\n print(json.dumps({\n \"roots\": [], \"warnings\": [], \"errors\": [f\"packs resolver failed unexpectedly: {exc}\"], \"entries\": 0,\n }))\n return 0\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n","content_type":"text/x-python; charset=utf-8","language":"python","size":31561,"content_sha256":"39c36946cd1a59ca564e60e4e049934831eb4bfb5cfce9de32ab6b4b522ef228"},{"filename":"scripts/peer-job-runner.py","content":"#!/usr/bin/env python3\n\"\"\"Detached peer-job runner: start/status/wait/result/reap for delegated work.\n\nSome harnesses enforce a hard ceiling on a single shell tool call and kill the\nsupervising shell mid-run, so no tool call may span a peer worker's runtime.\nThis runner splits the lifecycle so every call is short and all durable state\nlives on disk:\n\n start claim a job dir, preflight the worker, detach it into its own\n session (double fork with os.setsid between the forks), print ONLY\n the job id, return fast. The detached process supervises the worker\n and writes ONE atomic terminal record. Also sweeps sibling run roots\n older than 24 hours (best-effort, owner-checked).\n status print each job's state word without blocking.\n wait bounded poll (~1s cadence, never longer than --max-secs) that\n returns early once every watched job has settled. With\n --deadline-secs it also ends at the aggregate deadline and closes\n with one line naming what to do next.\n result ownership-checked bounded read of a done job's published artifact.\n reap ask each job's detached supervisor to terminate it now; returns fast.\n If the supervisor itself is gone, reap kills the worker tree and\n writes the terminal record itself. Reaping a terminal job is a\n safe no-op.\n\nJob directory (durable state, the source of truth):\n \u003croot>/\u003cskill>/\u003crun-id>/jobs/\u003cjob-id>/\n meta.json identity: skill, run id, label, input digest, start time,\n worker argv, result path (written at start, before detach)\n pid supervisor pid + worker pid (written by the supervisor before\n start returns; its presence marks \"detached\"). Platform-\n conditional fields — consumers must use .get(): POSIX adds\n supervisor_pgid; Windows adds job_name (its job object) and\n supervisor_identity / worker_identity (GetProcessTimes guards\n so a recycled pid is not treated as the original process).\n out.log worker's combined stdout+stderr (byte growth = liveness)\n reason terminal detail, written before the status rename so the\n status file is always the LAST record to land\n status exactly one word, published atomically (tmp + os.replace):\n done | failed | timeout | died-without-result\n\nStates reported by status/wait:\n running detached, no terminal record yet\n done worker exited 0 (and, when --result-path was declared,\n the result file exists non-empty)\n failed nonzero exit, byte-cap kill, or exit 0 without the\n declared result\n timeout supervisor idle/hard window fired, or a requested reap\n died-without-result worker killed by an external signal with no result\n evidence (or vanished together with its supervisor)\n never-started meta exists but nothing was ever detached (preflight\n failure)\n unreadable an ownership or sanity check failed; content withheld\n\nSupervision (runs inside the detached session, never in a tool call): poll\n~2s; liveness is out.log byte growth; idle window with no growth reaps the\nworker tree; a hard cap reaps it regardless; byte caps on out.log and the\npublished result classify as failed with a recorded reason. Reaping is TERM\nto the worker's own process group (the worker is started as a session/group\nleader), a grace period, then KILL — with a deepest-first tree walk as the\nfallback when the group kill is unavailable. The supervisor classifies the\noutcome exactly once; when both the worker's internal cap and the\nsupervisor's window fire, the supervisor's record wins.\n\nEnvironment overrides (defaults in parentheses):\n CE_PEER_JOBS_ROOT base dir (/tmp/compound-engineering-\u003ceffective-uid>,\n or $TMPDIR/compound-engineering-\u003ceffective-uid> when\n /tmp cannot host a writable private root, e.g. under\n a sandbox that only allowlists $TMPDIR)\n CE_WORK_RUNS_ROOT parent CE Work dir containing all \u003crun-id>/ dirs\n CE_PEER_IDLE_SECS idle window, no out.log growth (240)\n CE_PEER_HARD_SECS hard cap on worker wall clock\n (default: max(1230, CROSS_MODEL_HARD_SECS+30);\n an explicit value always wins)\n CROSS_MODEL_HARD_SECS when CE_PEER_HARD_SECS is unset, widens the\n supervisor hard window (see above)\n CE_PEER_LOG_MAX_BYTES out.log byte cap (10485760)\n CE_PEER_RESULT_MAX_BYTES result byte cap, supervise + read (5242880)\n CE_PEER_POLL_SECS supervisor poll interval (2)\n CE_PEER_GRACE_SECS TERM-to-KILL grace during reap (5)\n CE_PEER_BASH Windows: absolute bash.exe for peer workers\n (preferred over PATH / WSL System32 bash)\n CLAUDE_CODE_GIT_BASH_PATH Claude Code Git Bash path; used on Windows when\n CE_PEER_BASH is unset (#1268)\n\nSecurity posture: the job root is a predictable, owner-private directory under\nworld-shared /tmp. Every read of job state opens the file first (no-follow) and\nverifies the descriptor's owner (os.fstat st_uid == os.geteuid, guarded where\ngeteuid is unavailable) before any content is emitted; a mismatch reports\n\"unreadable\", never content. Reads are bounded by size caps — out.log is never\nslurped. Directory/file creation uses 0700/0600 modes, exclusive no-follow\ncreation, owner/type verification on path components, exact 0700 verification\non the top-level root, and atomic rename for every publish. The worker argv is\nexec'd directly (argv list, never a shell); job\nids are minted internally; --skill/--run-id/--label are restricted to\n[A-Za-z0-9._-]. Nothing here ever prompts: headless/CI-safe by design.\n\nPlatform (#1243): the mechanisms above describe POSIX. Native Windows Python\nhas no fork/setsid, uid, mode bits, or process groups, so the same contract is\nmet by win32 equivalents, all behind `sys.platform == \"win32\"` branches so the\nPOSIX path is behaviorally unchanged:\n detach re-invoke this script as a DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP\n child (CREATE_BREAKAWAY_FROM_JOB where the job allows) running the\n internal `__supervise` entrypoint; the pid file is the ack.\n reap cmd_reap drops a `.reap` marker the supervisor polls for (no directed\n signal to a detached, console-less process).\n teardown the worker tree lives in a named Job Object -- the real killpg\n analog, since it reaches descendants of an already-exited leader,\n which taskkill /T cannot (it walks parent->child from a LIVE\n parent). Windows releases a named object's name once the last\n handle closes, so a cmd_reap running after the supervisor died\n falls back to a Toolhelp32 snapshot walk; that works because\n Windows never reparents orphans, so a dead pid still appears as\n th32ParentProcessID on its live children. A recycled pid that is\n now this process (or whose GetProcessTimes identity does not\n match the pid file) is not the original leader: sweep stale-PPID\n descendants, do not TerminateProcess the live reused process.\n ownership st_uid == geteuid becomes: the object's owner SID is one this token\n creates objects as (user or default-owner SID), checked on the opened\n handle (GetSecurityInfo) exactly like the POSIX fstat-by-fd check.\n privacy 0700/0600 modes become a hardened ACL (icacls: break inheritance,\n grant only the user + SYSTEM + Administrators — the root-equivalents).\n jobs root defaults under %LOCALAPPDATA%\\\\compound-engineering-jobs (then the\n user temp dir), owner-private, since there is no shared /tmp.\n\nPure stdlib. No third-party dependencies.\n\"\"\"\nimport argparse\nimport calendar\nimport glob\nimport json\nimport math\nimport os\nimport re\nimport shutil\nimport signal\nimport stat\nimport subprocess\nimport sys\nimport tempfile\nimport time\n\n# Identifier charset for --skill/--run-id/--label and bare job refs. The dot is\n# allowed (model/date tokens use it) but an all-dot value (\".\", \"..\") would be a\n# path component that escapes the jobs root, so it is rejected separately below.\nSAFE_RE = re.compile(r\"^[A-Za-z0-9._-]+$\")\n\n\ndef _is_safe_token(value: str) -> bool:\n return bool(SAFE_RE.match(value)) and value.strip(\".\") != \"\"\n\n\nTERMINAL_STATES = (\"done\", \"failed\", \"timeout\", \"died-without-result\")\nIS_WINDOWS = sys.platform == \"win32\"\n_uid_getter = getattr(os, \"geteuid\", None) or getattr(os, \"getuid\", None)\n_EFFECTIVE_UID = _uid_getter() if _uid_getter is not None else None\nif IS_WINDOWS:\n # No geteuid on Windows; the current-user SID is the ownership identity\n # (see the Windows security section below), and the per-user jobs root lives\n # under LOCALAPPDATA (falling back to the user temp dir) with a hardened ACL\n # so the jobs root has a working default rather than a required override.\n _WIN_ROOT_BASE = os.environ.get(\"LOCALAPPDATA\") or tempfile.gettempdir()\n DEFAULT_ROOT = os.path.join(_WIN_ROOT_BASE, \"compound-engineering-jobs\")\nelif _EFFECTIVE_UID is not None:\n DEFAULT_ROOT = os.path.join(\"/tmp\", f\"compound-engineering-{_EFFECTIVE_UID}\")\nelse:\n DEFAULT_ROOT = None\nO_NOFOLLOW = getattr(os, \"O_NOFOLLOW\", 0)\n# Windows CPython opens os.open() descriptors in CRT *text* mode by default:\n# writes expand \\n -> \\r\\n and reads stop at the first 0x1A (Ctrl-Z EOF), which\n# would silently corrupt and truncate a peer's result artifact and desync the\n# out.log byte caps from st_size. O_BINARY is 0 on POSIX, so this is a no-op\n# there and every os.open below stays byte-exact on both platforms.\nO_BINARY = getattr(os, \"O_BINARY\", 0)\nSWEEP_AGE_SECS = 24 * 3600\nCLAIM_ATTEMPTS = 16\nSTATUS_READ_CAP = 256\nREASON_READ_CAP = 1024\nMETA_READ_CAP = 64 * 1024\nSTARTED_AT_FORMAT = \"%Y-%m-%dT%H:%M:%SZ\"\nREAP_SETTLE_SECS = 15\n\nEXIT_CODES_DOC = \"\"\"\\\nexit codes:\n 0 the command itself succeeded. For status/wait this means the query ran;\n it says nothing about job outcomes — parse stdout (or --json) for states.\n For `result` it means a done job's artifact (or a --path file) was emitted;\n for reap it includes the safe no-op on an already-terminal job.\n 1 runtime error (preflight failure, unknown job, detach failure); for a\n multi-job reap, also the code when its jobs failed in different ways\n 2 usage error; for `result`: the job is still running\n 3 for `result`: job settled but not done (failed / timeout /\n died-without-result / never-started), or the result file is missing\n 4 the read was refused, so content is never emitted: the ownership check\n failed (job state or result not owned by the current user), or the path\n is there but unreadable (a symlink rejected by O_NOFOLLOW, a non-regular\n file, a byte-cap overrun). Only a genuinely absent file is 3.\n\nenvironment overrides: CE_PEER_JOBS_ROOT, CE_WORK_RUNS_ROOT, CE_PEER_IDLE_SECS,\nCE_PEER_HARD_SECS, CROSS_MODEL_HARD_SECS, CE_PEER_LOG_MAX_BYTES,\nCE_PEER_RESULT_MAX_BYTES, CE_PEER_POLL_SECS, CE_PEER_GRACE_SECS (defaults in\nthe module docstring).\n\"\"\"\n\n\nclass RunnerError(Exception):\n \"\"\"Actionable operational error: message to stderr, exit 1.\"\"\"\n\n\nclass Unreadable(Exception):\n \"\"\"Job state failed an ownership or sanity check; content withheld.\"\"\"\n\n\n# --- configuration -----------------------------------------------------------\n\n# Supervisor hard-window floor: clears the highest cross-model worker default\n# (review skills use CROSS_MODEL_HARD_SECS:-1200) so an unset knob still nests\n# worker \u003c deadline \u003c runner without orchestrator arithmetic. Grace matches the\n# historical prose +30s so a raised knob widens the runner the same way.\n_RUNNER_HARD_FLOOR = 1230.0\n_RUNNER_HARD_GRACE = 30.0\n\n\ndef _private_root_usable(path: str) -> bool:\n \"\"\"True when `path` is (or can now be) a directory we own and can write into.\n\n Creation is the probe: a sandbox that denies writes under /tmp refuses the\n mkdir, and one that lets a pre-existing root stand still fails the access\n check, so both land on the fallback instead of failing at the first job.\n \"\"\"\n try:\n os.mkdir(path, 0o700)\n except FileExistsError:\n pass\n except OSError:\n return False\n try:\n _check_owned_dir(path)\n except (OSError, RunnerError):\n return False\n return os.access(path, os.W_OK)\n\n\ndef _fallback_root() -> str:\n return os.path.join(os.environ.get(\"TMPDIR\") or \"/tmp\", f\"compound-engineering-{_EFFECTIVE_UID}\")\n\n\ndef jobs_root_base() -> str:\n configured = os.environ.get(\"CE_PEER_JOBS_ROOT\")\n if configured:\n return os.path.abspath(configured)\n if DEFAULT_ROOT is None:\n raise RunnerError(\"effective user ID is unavailable; cannot derive the jobs root\")\n if IS_WINDOWS or _private_root_usable(DEFAULT_ROOT):\n return os.path.abspath(DEFAULT_ROOT)\n # Same order and candidates as the skills' shell preamble, so a job started\n # there is found here.\n return os.path.abspath(_fallback_root())\n\n\ndef candidate_jobs_root_bases() -> list:\n \"\"\"Every root an existing job may live under: the configured root alone, or\n both the /tmp root and the $TMPDIR fallback (deduplicated, primary first).\n\n Creation uses jobs_root_base(); lookup of an already-started job must not\n depend on which root *this* invocation would create under, because a\n sandboxed session and a later unsandboxed one resolve different roots.\n \"\"\"\n configured = os.environ.get(\"CE_PEER_JOBS_ROOT\")\n if configured:\n return [os.path.abspath(configured)]\n if DEFAULT_ROOT is None:\n raise RunnerError(\"effective user ID is unavailable; cannot derive the jobs root\")\n bases = [os.path.abspath(DEFAULT_ROOT)]\n if not IS_WINDOWS:\n fallback = os.path.abspath(_fallback_root())\n if fallback not in bases:\n bases.append(fallback)\n return bases\n\n\ndef skill_runs_root(skill: str) -> str:\n if skill == \"ce-work\" and os.environ.get(\"CE_WORK_RUNS_ROOT\"):\n return os.path.abspath(os.environ[\"CE_WORK_RUNS_ROOT\"])\n return os.path.join(jobs_root_base(), skill)\n\n\ndef candidate_skill_runs_roots(skill: str) -> list:\n if skill == \"ce-work\" and os.environ.get(\"CE_WORK_RUNS_ROOT\"):\n return [os.path.abspath(os.environ[\"CE_WORK_RUNS_ROOT\"])]\n return [os.path.join(base, skill) for base in candidate_jobs_root_bases()]\n\n\ndef _env_num(name: str, default: float, conv, *, allow_zero: bool = False):\n raw = os.environ.get(name)\n if not raw:\n return default\n try:\n val = conv(raw)\n except ValueError:\n return default\n if allow_zero and val == 0:\n return None\n return val if val > 0 else default\n\n\ndef _derived_hard_default() -> float:\n \"\"\"Outermost supervisor hard window when CE_PEER_HARD_SECS is unset.\n\n Reads ambient CROSS_MODEL_HARD_SECS (the runner already forwards os.environ\n to the worker, so a user-set knob is present here). Explicit CE_PEER_HARD_SECS\n still wins via cfg() — ce-work and elevation paths keep their own windows.\n \"\"\"\n cross = _env_num(\"CROSS_MODEL_HARD_SECS\", 0.0, float)\n return max(_RUNNER_HARD_FLOOR, cross + _RUNNER_HARD_GRACE)\n\n\ndef cfg(skill=None) -> dict:\n return {\n \"idle\": _env_num(\"CE_PEER_IDLE_SECS\", 240.0, float, allow_zero=skill == \"ce-work\"),\n \"hard\": _env_num(\"CE_PEER_HARD_SECS\", _derived_hard_default(), float),\n \"log_max\": int(_env_num(\"CE_PEER_LOG_MAX_BYTES\", 10 * 1024 * 1024, int)),\n \"result_max\": int(_env_num(\"CE_PEER_RESULT_MAX_BYTES\", 5 * 1024 * 1024, int)),\n \"poll\": _env_num(\"CE_PEER_POLL_SECS\", 2.0, float),\n \"grace\": _env_num(\"CE_PEER_GRACE_SECS\", 5.0, float),\n }\n\n\n# --- Windows security + process primitives ------------------------------------\n#\n# POSIX ownership is `fstat().st_uid == geteuid()` plus mode 0700/0600. Windows\n# has neither uids nor mode bits, so the equivalent identity is the current\n# user's SID: a job dir/file is \"ours\" when its owner SID is one this process's\n# token creates objects as (the user SID or the token's default owner SID -- an\n# elevated process defaults new objects to Administrators). A foreign user's\n# planted dir carries neither SID and is rejected, exactly as a uid mismatch is\n# on POSIX. The DACL is hardened to user+SYSTEM+Administrators (root-equivalents,\n# mirroring how root still reaches a 0700 dir) with inheritance broken, so no\n# world/Users grant survives. Pure stdlib via ctypes -- no pywin32.\n\nif IS_WINDOWS:\n import ctypes\n import msvcrt\n from ctypes import wintypes\n\n _advapi32 = ctypes.WinDLL(\"advapi32\", use_last_error=True)\n _kernel32 = ctypes.WinDLL(\"kernel32\", use_last_error=True)\n\n _SE_FILE_OBJECT = 1\n _OWNER_SECURITY_INFORMATION = 0x00000001\n _TOKEN_QUERY = 0x0008\n _TOKEN_USER_CLASS = 1\n _TOKEN_OWNER_CLASS = 4\n _STILL_ACTIVE = 259\n _WAIT_TIMEOUT = 0x00000102\n _PROCESS_QUERY_LIMITED_INFORMATION = 0x1000\n _SYNCHRONIZE = 0x00100000\n # A detached, console-less parent still gives its children a NEW console\n # unless this is set, so every job would flash a window on the user's\n # desktop. Applied to the worker and to every helper tool we shell out to.\n _WIN_NO_WINDOW = getattr(subprocess, \"CREATE_NO_WINDOW\", 0x08000000)\n\n def _win_tool(name: str) -> str:\n \"\"\"Absolute path to a System32 tool. CreateProcess searches the\n application and current directories before System32, so invoking\n `icacls`/`taskkill` by bare name from an untrusted CWD is a binary-\n hijack surface. Falls back to the bare name only if System32 is\n unresolvable, which is strictly better than never running.\"\"\"\n root = os.environ.get(\"SystemRoot\") or r\"C:\\Windows\"\n candidate = os.path.join(root, \"System32\", name + \".exe\")\n return candidate if os.path.isfile(candidate) else name\n\n _advapi32.ConvertSidToStringSidW.argtypes = [\n ctypes.c_void_p, ctypes.POINTER(ctypes.c_wchar_p)]\n _advapi32.ConvertSidToStringSidW.restype = wintypes.BOOL\n _advapi32.OpenProcessToken.argtypes = [\n wintypes.HANDLE, wintypes.DWORD, ctypes.POINTER(wintypes.HANDLE)]\n _advapi32.OpenProcessToken.restype = wintypes.BOOL\n _advapi32.GetTokenInformation.argtypes = [\n wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD,\n ctypes.POINTER(wintypes.DWORD)]\n _advapi32.GetTokenInformation.restype = wintypes.BOOL\n _advapi32.GetSecurityInfo.argtypes = [\n wintypes.HANDLE, ctypes.c_int, wintypes.DWORD,\n ctypes.POINTER(ctypes.c_void_p), ctypes.c_void_p, ctypes.c_void_p,\n ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p)]\n _advapi32.GetSecurityInfo.restype = wintypes.DWORD\n _advapi32.GetNamedSecurityInfoW.argtypes = [\n wintypes.LPCWSTR, ctypes.c_int, wintypes.DWORD,\n ctypes.POINTER(ctypes.c_void_p), ctypes.c_void_p, ctypes.c_void_p,\n ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p)]\n _advapi32.GetNamedSecurityInfoW.restype = wintypes.DWORD\n _kernel32.GetCurrentProcess.restype = wintypes.HANDLE\n _kernel32.OpenProcess.argtypes = [\n wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]\n _kernel32.OpenProcess.restype = wintypes.HANDLE\n _kernel32.GetProcessTimes.argtypes = [\n wintypes.HANDLE,\n ctypes.POINTER(wintypes.FILETIME),\n ctypes.POINTER(wintypes.FILETIME),\n ctypes.POINTER(wintypes.FILETIME),\n ctypes.POINTER(wintypes.FILETIME),\n ]\n _kernel32.GetProcessTimes.restype = wintypes.BOOL\n _kernel32.QueryFullProcessImageNameW.argtypes = [\n wintypes.HANDLE, wintypes.DWORD, wintypes.LPWSTR,\n ctypes.POINTER(wintypes.DWORD)]\n _kernel32.QueryFullProcessImageNameW.restype = wintypes.BOOL\n _kernel32.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]\n _kernel32.WaitForSingleObject.restype = wintypes.DWORD\n _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]\n _kernel32.CloseHandle.restype = wintypes.BOOL\n _kernel32.LocalFree.argtypes = [wintypes.HGLOBAL]\n _kernel32.LocalFree.restype = wintypes.HGLOBAL\n _kernel32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]\n _kernel32.CreateJobObjectW.restype = wintypes.HANDLE\n _kernel32.OpenJobObjectW.argtypes = [\n wintypes.DWORD, wintypes.BOOL, wintypes.LPCWSTR]\n _kernel32.OpenJobObjectW.restype = wintypes.HANDLE\n _kernel32.AssignProcessToJobObject.argtypes = [\n wintypes.HANDLE, wintypes.HANDLE]\n _kernel32.AssignProcessToJobObject.restype = wintypes.BOOL\n _kernel32.TerminateJobObject.argtypes = [wintypes.HANDLE, wintypes.UINT]\n _kernel32.TerminateJobObject.restype = wintypes.BOOL\n\n _JOB_OBJECT_TERMINATE = 0x0008\n _PROCESS_TERMINATE = 0x0001\n _PROCESS_SET_QUOTA = 0x0100\n _TH32CS_SNAPPROCESS = 0x00000002\n _TH32CS_SNAPTHREAD = 0x00000004\n _THREAD_SUSPEND_RESUME = 0x0002\n # CreateProcess CREATE_SUSPENDED: primary thread starts frozen so we can\n # AssignProcessToJobObject before any user code (or child spawn) runs.\n _CREATE_SUSPENDED = 0x00000004\n\n class _PROCESSENTRY32W(ctypes.Structure):\n _fields_ = [\n (\"dwSize\", wintypes.DWORD),\n (\"cntUsage\", wintypes.DWORD),\n (\"th32ProcessID\", wintypes.DWORD),\n (\"th32DefaultHeapID\", ctypes.POINTER(ctypes.c_ulong)),\n (\"th32ModuleID\", wintypes.DWORD),\n (\"cntThreads\", wintypes.DWORD),\n (\"th32ParentProcessID\", wintypes.DWORD),\n (\"pcPriClassBase\", ctypes.c_long),\n (\"dwFlags\", wintypes.DWORD),\n (\"szExeFile\", ctypes.c_wchar * 260),\n ]\n\n class _THREADENTRY32(ctypes.Structure):\n _fields_ = [\n (\"dwSize\", wintypes.DWORD),\n (\"cntUsage\", wintypes.DWORD),\n (\"th32ThreadID\", wintypes.DWORD),\n (\"th32OwnerProcessID\", wintypes.DWORD),\n (\"tpBasePri\", ctypes.c_long),\n (\"tpDeltaPri\", ctypes.c_long),\n (\"dwFlags\", wintypes.DWORD),\n ]\n\n _kernel32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]\n _kernel32.CreateToolhelp32Snapshot.restype = ctypes.c_void_p\n _kernel32.Process32FirstW.argtypes = [\n ctypes.c_void_p, ctypes.POINTER(_PROCESSENTRY32W)]\n _kernel32.Process32FirstW.restype = wintypes.BOOL\n _kernel32.Process32NextW.argtypes = [\n ctypes.c_void_p, ctypes.POINTER(_PROCESSENTRY32W)]\n _kernel32.Process32NextW.restype = wintypes.BOOL\n _kernel32.Thread32First.argtypes = [\n ctypes.c_void_p, ctypes.POINTER(_THREADENTRY32)]\n _kernel32.Thread32First.restype = wintypes.BOOL\n _kernel32.Thread32Next.argtypes = [\n ctypes.c_void_p, ctypes.POINTER(_THREADENTRY32)]\n _kernel32.Thread32Next.restype = wintypes.BOOL\n _kernel32.OpenThread.argtypes = [\n wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]\n _kernel32.OpenThread.restype = wintypes.HANDLE\n _kernel32.ResumeThread.argtypes = [wintypes.HANDLE]\n _kernel32.ResumeThread.restype = wintypes.DWORD\n _kernel32.TerminateProcess.argtypes = [wintypes.HANDLE, wintypes.UINT]\n _kernel32.TerminateProcess.restype = wintypes.BOOL\n\n def _win_process_children_map():\n \"\"\"th32ParentProcessID -> [child pids] from one Toolhelp snapshot.\"\"\"\n snap = _kernel32.CreateToolhelp32Snapshot(_TH32CS_SNAPPROCESS, 0)\n if not snap or snap == ctypes.c_void_p(-1).value:\n return {}\n children = {}\n try:\n entry = _PROCESSENTRY32W()\n entry.dwSize = ctypes.sizeof(_PROCESSENTRY32W)\n more = _kernel32.Process32FirstW(snap, ctypes.byref(entry))\n while more:\n children.setdefault(entry.th32ParentProcessID, []).append(\n entry.th32ProcessID)\n more = _kernel32.Process32NextW(snap, ctypes.byref(entry))\n finally:\n _kernel32.CloseHandle(ctypes.c_void_p(snap))\n return children\n\n def _win_descendants_deepest_first(root_pid: int, children=None):\n \"\"\"Children before parents, via a process snapshot. This is the direct\n analog of the POSIX `ps`-based walk and carries the same pid-reuse\n exposure. It works on an EXITED leader because Windows never reparents\n orphans: a dead pid still appears as th32ParentProcessID on its live\n children (unlike POSIX, where orphans are reparented to init).\"\"\"\n if children is None:\n children = _win_process_children_map()\n order, queue = [], [root_pid]\n while queue:\n for child in children.get(queue.pop(0), []):\n order.append(child)\n queue.append(child)\n return list(reversed(order))\n\n def _win_process_identity(pid: int):\n \"\"\"Creation time plus image path — analog of `ps -o lstart= -o command=`.\n\n Creation time is the PID-reuse guard: Windows recycles PIDs aggressively,\n and a recycled pid always carries a later FILETIME than the worker we\n recorded. None means unproven (gone or unopenable).\"\"\"\n handle = _kernel32.OpenProcess(\n _PROCESS_QUERY_LIMITED_INFORMATION, False, pid)\n if not handle:\n return None\n try:\n created, exited, kernel, user = (wintypes.FILETIME() for _ in range(4))\n if not _kernel32.GetProcessTimes(\n handle, ctypes.byref(created), ctypes.byref(exited),\n ctypes.byref(kernel), ctypes.byref(user)):\n return None\n started = (created.dwHighDateTime \u003c\u003c 32) | created.dwLowDateTime\n if not started:\n return None\n size = wintypes.DWORD(32768)\n buf = ctypes.create_unicode_buffer(size.value)\n image = (buf.value if _kernel32.QueryFullProcessImageNameW(\n handle, 0, buf, ctypes.byref(size)) else \"\")\n finally:\n _kernel32.CloseHandle(handle)\n return \"{} {}\".format(started, image)\n\n def _win_process_start_time(pid: int):\n handle = _kernel32.OpenProcess(\n _PROCESS_QUERY_LIMITED_INFORMATION, False, pid)\n if not handle:\n return None\n try:\n created, exited, kernel, user = (wintypes.FILETIME() for _ in range(4))\n if not _kernel32.GetProcessTimes(\n handle, ctypes.byref(created), ctypes.byref(exited),\n ctypes.byref(kernel), ctypes.byref(user)):\n return None\n started = (created.dwHighDateTime \u003c\u003c 32) | created.dwLowDateTime\n return started or None\n finally:\n _kernel32.CloseHandle(handle)\n\n def _win_process_identity_matches(pid: int, recorded) -> bool:\n if not recorded:\n return True\n current = _win_process_identity(pid)\n return current is not None and current == recorded\n\n def _win_terminate_pid(pid: int) -> bool:\n if pid \u003c= 0 or pid == os.getpid():\n return False\n handle = _kernel32.OpenProcess(_PROCESS_TERMINATE, False, pid)\n if not handle:\n return False\n try:\n return bool(_kernel32.TerminateProcess(handle, 1))\n finally:\n _kernel32.CloseHandle(handle)\n\n def _win_job_name(job_dir: str) -> str:\n \"\"\"A per-job named kernel object. Naming it is what makes this a real\n pgid analog: a DIFFERENT process (cmd_reap, after the supervisor is\n gone) can reopen it by name and terminate the whole tree.\"\"\"\n return \"Local\\\\ce-peer-job-\" + os.path.basename(job_dir.rstrip(\"\\\\/\"))\n\n def _win_create_job(name: str):\n \"\"\"Create the job the worker tree will live in. Deliberately WITHOUT\n JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE: like a POSIX process group, the job\n must outlive the supervisor so a dead-supervisor reap still finds a\n live tree to classify and sweep (matching the POSIX lifecycle tests).\"\"\"\n handle = _kernel32.CreateJobObjectW(None, name)\n return handle or None\n\n def _win_assign_to_job(job_handle, pid: int) -> bool:\n proc = _kernel32.OpenProcess(\n _PROCESS_SET_QUOTA | _PROCESS_TERMINATE, False, pid)\n if not proc:\n return False\n try:\n return bool(_kernel32.AssignProcessToJobObject(job_handle, proc))\n finally:\n _kernel32.CloseHandle(proc)\n\n def _win_resume_process(pid: int) -> bool:\n \"\"\"Resume every thread of a CREATE_SUSPENDED process. subprocess.Popen\n does not expose hThread from PROCESS_INFORMATION, so walk the thread\n snapshot. CREATE_SUSPENDED only freezes the primary thread; resuming\n all owned threads is still correct and idempotent for running ones.\"\"\"\n snap = _kernel32.CreateToolhelp32Snapshot(_TH32CS_SNAPTHREAD, 0)\n if not snap or snap == ctypes.c_void_p(-1).value:\n return False\n resumed = False\n try:\n entry = _THREADENTRY32()\n entry.dwSize = ctypes.sizeof(_THREADENTRY32)\n more = _kernel32.Thread32First(snap, ctypes.byref(entry))\n while more:\n if entry.th32OwnerProcessID == pid:\n handle = _kernel32.OpenThread(\n _THREAD_SUSPEND_RESUME, False, entry.th32ThreadID)\n if handle:\n try:\n # (DWORD)-1 == failure; 0xFFFFFFFF as unsigned.\n if _kernel32.ResumeThread(handle) != 0xFFFFFFFF:\n resumed = True\n finally:\n _kernel32.CloseHandle(handle)\n more = _kernel32.Thread32Next(snap, ctypes.byref(entry))\n finally:\n _kernel32.CloseHandle(ctypes.c_void_p(snap))\n return resumed\n\n def _win_terminate_job(name: str) -> bool:\n \"\"\"Terminate every process in the named job, whatever the tree shape.\n This is the piece taskkill /T cannot do: it reaches descendants whose\n parent has already exited, because job membership is inherited and\n does not depend on a live parent to walk from.\"\"\"\n handle = _kernel32.OpenJobObjectW(_JOB_OBJECT_TERMINATE, False, name)\n if not handle:\n return False\n try:\n return bool(_kernel32.TerminateJobObject(handle, 1))\n finally:\n _kernel32.CloseHandle(handle)\n\n _WIN_IDENTITY_SIDS = None\n\n def _win_sid_to_string(psid) -> str:\n strp = ctypes.c_wchar_p()\n if not _advapi32.ConvertSidToStringSidW(psid, ctypes.byref(strp)):\n raise OSError(f\"ConvertSidToStringSid failed: {ctypes.get_last_error()}\")\n try:\n return strp.value\n finally:\n _kernel32.LocalFree(ctypes.cast(strp, wintypes.HGLOBAL))\n\n def _win_token_sid(token, info_class) -> str:\n size = wintypes.DWORD(0)\n _advapi32.GetTokenInformation(token, info_class, None, 0, ctypes.byref(size))\n buf = (ctypes.c_byte * size.value)()\n if not _advapi32.GetTokenInformation(\n token, info_class, buf, size, ctypes.byref(size)\n ):\n raise OSError(f\"GetTokenInformation failed: {ctypes.get_last_error()}\")\n # TOKEN_USER / TOKEN_OWNER both begin with a PSID at offset 0.\n sid_ptr = ctypes.cast(buf, ctypes.POINTER(ctypes.c_void_p))[0]\n return _win_sid_to_string(ctypes.c_void_p(sid_ptr))\n\n def _win_identity_sids() -> frozenset:\n \"\"\"The SID strings this process's token creates objects as: the user SID\n and the default-owner SID (they differ for an elevated process). Cached;\n an object owned by any of these is treated as ours.\"\"\"\n global _WIN_IDENTITY_SIDS\n if _WIN_IDENTITY_SIDS is not None:\n return _WIN_IDENTITY_SIDS\n token = wintypes.HANDLE()\n if not _advapi32.OpenProcessToken(\n _kernel32.GetCurrentProcess(), _TOKEN_QUERY, ctypes.byref(token)\n ):\n raise OSError(f\"OpenProcessToken failed: {ctypes.get_last_error()}\")\n try:\n sids = {\n _win_token_sid(token, _TOKEN_USER_CLASS),\n _win_token_sid(token, _TOKEN_OWNER_CLASS),\n }\n finally:\n _kernel32.CloseHandle(token)\n _WIN_IDENTITY_SIDS = frozenset(s for s in sids if s)\n return _WIN_IDENTITY_SIDS\n\n def _win_owner_sid(api, target) -> str:\n \"\"\"Shared GetSecurityInfo / GetNamedSecurityInfoW shape: read the OWNER\n SID into a freshly allocated security descriptor and stringify it. The\n SID points INSIDE that descriptor, so freeing the descriptor is the only\n (and required) cleanup -- never free the SID separately.\"\"\"\n psid = ctypes.c_void_p()\n psd = ctypes.c_void_p()\n err = api(target, _SE_FILE_OBJECT, _OWNER_SECURITY_INFORMATION,\n ctypes.byref(psid), None, None, None, ctypes.byref(psd))\n if err != 0:\n raise OSError(f\"{api.__name__} failed: {err}\")\n try:\n return _win_sid_to_string(psid)\n finally:\n _kernel32.LocalFree(ctypes.cast(psd, wintypes.HGLOBAL))\n\n def _win_owner_sid_from_handle(handle: int) -> str:\n return _win_owner_sid(_advapi32.GetSecurityInfo, wintypes.HANDLE(handle))\n\n def _win_owner_sid_from_path(path: str) -> str:\n return _win_owner_sid(_advapi32.GetNamedSecurityInfoW, path)\n\n def _win_owns_path(path: str) -> bool:\n return _win_owner_sid_from_path(path) in _win_identity_sids()\n\n def _win_owns_handle(handle: int) -> bool:\n return _win_owner_sid_from_handle(handle) in _win_identity_sids()\n\n def _win_run_quiet(cmd) -> bool:\n \"\"\"Fire-and-forget a Windows tool (icacls/taskkill): output suppressed,\n exit status returned but never raised. check=False suppresses a NONZERO\n exit, NOT a missing executable -- Popen still raises FileNotFoundError\n when the tool is absent from PATH, which would otherwise escape the\n supervisor's teardown and turn an already-classified `done` job into\n `failed`. Returns True only when the tool ran and exited 0.\"\"\"\n try:\n return subprocess.run(\n cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,\n check=False, creationflags=_WIN_NO_WINDOW).returncode == 0\n except OSError:\n return False\n\n def _win_harden_acl(path: str) -> None:\n \"\"\"Break inheritance and grant only the current user plus the\n root-equivalents (SYSTEM, Administrators), so no world/Users grant\n survives -- the 0700 analog. Best-effort: the owner check and the\n O_EXCL/O_CREAT claim remain the hard gates if icacls is unavailable.\"\"\"\n sids = _win_identity_sids()\n if not sids:\n return False\n inherit = \"(OI)(CI)\" if os.path.isdir(path) else \"\"\n # Grant EVERY identity SID, not an arbitrary one from the set: an\n # elevated token carries two (user + default owner), and picking one\n # nondeterministically could grant the wrong principal.\n grants = []\n for sid in sorted(sids) + [\"S-1-5-18\", \"S-1-5-32-544\"]:\n grants += [\"/grant:r\", f\"*{sid}:{inherit}F\"]\n return _win_run_quiet([_win_tool(\"icacls\"), path, \"/inheritance:r\"] + grants)\n\n def _win_pid_alive(pid: int) -> bool:\n handle = _kernel32.OpenProcess(\n _PROCESS_QUERY_LIMITED_INFORMATION | _SYNCHRONIZE, False, pid)\n if not handle:\n return False\n try:\n return _kernel32.WaitForSingleObject(handle, 0) == _WAIT_TIMEOUT\n finally:\n _kernel32.CloseHandle(handle)\n\n def _win_kill_tree(\n root_pid: int, grace: float, job_name=None, expected_identity=None,\n ) -> bool:\n \"\"\"Terminate the worker tree. Returns whether the LEADER was\n alive when the kill began -- the reap classification signal -- which is\n independent of how much of the tree we then sweep.\n\n The job object is the primary mechanism and the true killpg analog: it\n reaches descendants even after the leader has exited. taskkill /T can\n NOT -- it walks parent->child from a live parent, so against an exited\n pid it returns \"process not found\" and silently leaves grandchildren\n running forever. That is why the sweep is attempted whenever a job name\n exists, regardless of leader liveness.\n\n No graceful phase: a console-less worker cannot receive taskkill's\n WM_CLOSE (it reports \"can only be terminated forcefully\"), so the grace\n window was pure latency that also widened the cmd_reap race.\n\n The job is only reachable by the process that created it: Windows\n releases a named object's NAME once the last handle closes, even while\n member processes keep the object alive (verified: OpenJobObject then\n fails with ERROR_FILE_NOT_FOUND). So a cmd_reap running after the\n supervisor died cannot use it, and falls back to the snapshot walk --\n which is exactly the dead-leader case, hence deepest-first descendants\n BEFORE the leader, and never gated on leader liveness.\n\n A live pid at root_pid is not automatically the original leader:\n Windows recycles PIDs, and cmd_reap is often the next python.exe after\n the worker exits (the orphan-grandchild smoke). Never terminate this\n process, and never terminate a live pid whose GetProcessTimes identity\n does not match the recorded worker. Stale-PPID orphans still show the\n dead leader as parent. When the pid was reused, the start-time cutoff\n applies only to *direct* children of that pid (the new process's own\n children vs stale-PPID orphans). A pre-reuse child's full subtree is\n still original-tree work, including descendants spawned after reuse.\"\"\"\n self_pid = os.getpid()\n is_self = root_pid == self_pid\n alive = (not is_self) and _win_pid_alive(root_pid)\n recorded_leader = alive and _win_process_identity_matches(\n root_pid, expected_identity)\n if job_name:\n _win_terminate_job(job_name)\n # Always Toolhelp-sweep after (or without) the job terminate: children\n # that raced outside the job before AssignProcessToJobObject completed\n # are not members, and TerminateJobObject alone would leave them.\n # CREATE_SUSPENDED closes that spawn race; this remains the belt.\n children_map = _win_process_children_map()\n reuse_cutoff = None\n if not recorded_leader and (is_self or alive):\n reuse_cutoff = _win_process_start_time(root_pid)\n if reuse_cutoff is not None:\n def _predates_reuse(pid):\n started = _win_process_start_time(pid)\n return started is None or started \u003c reuse_cutoff\n kill_set = _pre_reuse_descendant_pids(\n root_pid, children_map, _predates_reuse, self_pid)\n else:\n kill_set = None\n for pid in _win_descendants_deepest_first(root_pid, children_map):\n if pid == self_pid:\n continue\n if kill_set is not None and pid not in kill_set:\n continue\n _win_terminate_pid(pid)\n if recorded_leader:\n _win_terminate_pid(root_pid)\n return recorded_leader\n\n\n# --- hardened I/O primitives --------------------------------------------------\n\ndef _euid():\n return _EFFECTIVE_UID\n\n\ndef _check_owned_dir(path: str, require_private: bool = False) -> None:\n st = os.lstat(path)\n if not stat.S_ISDIR(st.st_mode):\n raise RunnerError(f\"{path}: not a real directory (symlink or file planted?)\")\n if IS_WINDOWS:\n # SID ownership stands in for st_uid; the hardened ACL (not a mode bit)\n # provides privacy, so there is no separate require_private gate.\n if not _win_owns_path(path):\n raise RunnerError(f\"{path}: not owned by the current user\")\n return\n euid = _euid()\n if euid is not None and st.st_uid != euid:\n raise RunnerError(f\"{path}: not owned by the current user\")\n if require_private:\n mode = stat.S_IMODE(st.st_mode)\n if mode != 0o700:\n raise RunnerError(f\"{path}: must have mode 0700, found {mode:04o}\")\n\n\ndef ensure_owned_dirs(base: str, path: str) -> None:\n \"\"\"mkdir -p `path` (mode 0700) verifying owner and type on every component\n from `base` down — a planted symlink or foreign dir aborts, never traversed.\"\"\"\n rel = os.path.relpath(path, base)\n comps = [] if rel == \".\" else rel.split(os.sep)\n cur = base\n created_base = True\n try:\n os.mkdir(cur, 0o700)\n except FileExistsError:\n created_base = False\n _check_owned_dir(cur)\n if IS_WINDOWS:\n # `icacls /inheritance:r` is destructive and irreversible in a way\n # POSIX's chmod 0700 is not: it permanently drops inherited ACEs. So\n # only re-ACL a root this runner owns -- one we just created, or the\n # managed default (repairing a default left non-private, which is what\n # the POSIX unconditional chmod is for). A pre-existing user-supplied\n # CE_PEER_JOBS_ROOT keeps its ACLs and rests on the owner check.\n default_root = os.path.abspath(DEFAULT_ROOT) if DEFAULT_ROOT else None\n ours = created_base or (\n default_root is not None\n and os.path.normcase(cur) == os.path.normcase(default_root))\n if ours and not _win_harden_acl(cur):\n # Never proceed as if hardened: an unverified root is the one case\n # where the privacy half of the model would silently be missing.\n raise RunnerError(\n f\"{cur}: could not harden the jobs-root ACL (icacls failed or \"\n \"is unavailable); refusing to use a root whose privacy is \"\n \"unverified\"\n )\n else:\n os.chmod(cur, 0o700)\n _check_owned_dir(cur, require_private=True)\n for comp in comps:\n cur = os.path.join(cur, comp)\n created = False\n try:\n os.mkdir(cur, 0o700)\n created = True\n except FileExistsError:\n pass\n if created:\n if IS_WINDOWS:\n _win_harden_acl(cur)\n else:\n os.chmod(cur, 0o700)\n _check_owned_dir(cur)\n\n\ndef read_owned(path: str, cap: int) -> bytes:\n \"\"\"Open no-follow, verify the OPENED descriptor's owner via fstat, enforce\n the size cap, and return content. Raises Unreadable on any trust failure.\"\"\"\n fd = os.open(path, os.O_RDONLY | O_NOFOLLOW | O_BINARY)\n try:\n st = os.fstat(fd)\n if IS_WINDOWS:\n # Verify the OPENED handle's owner SID (TOCTOU-safe, like the POSIX\n # fstat-by-fd check) before emitting a byte.\n if not _win_owns_handle(msvcrt.get_osfhandle(fd)):\n raise Unreadable(f\"{path}: not owned by the current user; refusing to read\")\n else:\n euid = _euid()\n if euid is not None and st.st_uid != euid:\n raise Unreadable(f\"{path}: not owned by the current user; refusing to read\")\n if not stat.S_ISREG(st.st_mode):\n raise Unreadable(f\"{path}: not a regular file\")\n if st.st_size > cap:\n raise Unreadable(f\"{path}: {st.st_size} bytes exceeds the {cap}-byte read cap\")\n chunks = []\n got = 0\n while got \u003c= cap:\n chunk = os.read(fd, 65536)\n if not chunk:\n break\n chunks.append(chunk)\n got += len(chunk)\n if got > cap:\n raise Unreadable(f\"{path}: grew past the {cap}-byte read cap during read\")\n return b\"\".join(chunks)\n finally:\n os.close(fd)\n\n\ndef create_exclusive(path: str, data: bytes = b\"\", mode: int = 0o600) -> None:\n fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | O_NOFOLLOW | O_BINARY, mode)\n try:\n if data:\n os.write(fd, data)\n finally:\n os.close(fd)\n\n\ndef write_atomic(path: str, data: bytes) -> None:\n fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), prefix=\".tmp-\")\n try:\n with os.fdopen(fd, \"wb\") as f:\n f.write(data)\n os.replace(tmp, path)\n except BaseException:\n try:\n os.unlink(tmp)\n except OSError:\n pass\n raise\n\n\ndef write_terminal(job_dir: str, state: str, reason: str, overwrite: bool = True) -> None:\n \"\"\"Publish the single terminal record. The reason detail lands FIRST so the\n atomic status rename is always the last record; a reason write failure never\n blocks the status.\"\"\"\n status_path = os.path.join(job_dir, \"status\")\n if not overwrite and os.path.lexists(status_path):\n return\n try:\n write_atomic(os.path.join(job_dir, \"reason\"), (reason.rstrip(\"\\n\") + \"\\n\").encode())\n except OSError:\n pass\n write_atomic(status_path, (state + \"\\n\").encode())\n\n\n# --- job identity and resolution ----------------------------------------------\n\ndef mint_job_id() -> str:\n return f\"{time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())}-{os.urandom(4).hex()}\"\n\n\ndef claim_job_dir(jobs_root: str):\n \"\"\"Atomically claim a fresh job dir: os.mkdir (no -p) fails on collision,\n so the id is regenerated rather than a dir ever being shared.\"\"\"\n for _ in range(CLAIM_ATTEMPTS):\n job_id = mint_job_id()\n job_dir = os.path.join(jobs_root, job_id)\n try:\n os.mkdir(job_dir, 0o700)\n return job_id, job_dir\n except FileExistsError:\n continue\n raise RunnerError(f\"could not claim a unique job dir after {CLAIM_ATTEMPTS} attempts\")\n\n\ndef resolve_job_dir(ref: str, skill=None) -> str:\n if os.sep in ref:\n p = os.path.abspath(ref)\n if os.path.isdir(p):\n return p\n raise RunnerError(f\"no such job dir: {ref}\")\n if not _is_safe_token(ref):\n raise RunnerError(f\"invalid job ref: {ref!r}\")\n if skill is not None:\n if not _is_safe_token(skill):\n raise RunnerError(f\"invalid skill: {skill!r}\")\n search_roots = candidate_skill_runs_roots(skill)\n patterns = [os.path.join(root, \"*\", \"jobs\", ref) for root in search_roots]\n else:\n search_roots = candidate_jobs_root_bases()\n patterns = [os.path.join(root, \"*\", \"*\", \"jobs\", ref) for root in search_roots]\n matches = sorted({match for pattern in patterns for match in glob.glob(pattern)})\n if not matches:\n raise RunnerError(f\"job not found under {', '.join(search_roots)}: {ref}\")\n if len(matches) > 1:\n raise RunnerError(f\"ambiguous job id {ref}: {len(matches)} matches; pass the job dir path\")\n return matches[0]\n\n\ndef job_state(job_dir: str) -> str:\n try:\n _check_owned_dir(job_dir)\n except (RunnerError, OSError):\n return \"unreadable\"\n try:\n word = read_owned(os.path.join(job_dir, \"status\"), STATUS_READ_CAP)\n word = word.decode(\"utf-8\", \"replace\").strip()\n return word if word in TERMINAL_STATES else \"unreadable\"\n except FileNotFoundError:\n pass\n except (Unreadable, OSError):\n return \"unreadable\"\n if os.path.lexists(os.path.join(job_dir, \"pid\")):\n return \"running\"\n return \"never-started\"\n\n\ndef job_reason(job_dir: str) -> str:\n \"\"\"The terminal record's detail line, or \"\" when unavailable. Decorative\n context for a message; never load-bearing, so every failure reads as \"\".\"\"\"\n try:\n raw = read_owned(os.path.join(job_dir, \"reason\"), REASON_READ_CAP)\n except (Unreadable, OSError):\n return \"\"\n return raw.decode(\"utf-8\", \"replace\").strip()\n\n\n# --- process-tree control -----------------------------------------------------\n\ndef _pid_alive(pid: int) -> bool:\n if IS_WINDOWS:\n return _win_pid_alive(pid)\n try:\n os.kill(pid, 0)\n return True\n except ProcessLookupError:\n return False\n except OSError:\n return True\n\n\ndef _pid_running(pid: int) -> bool:\n \"\"\"True only for a live process, NOT a \u003cdefunct> zombie. os.kill(pid, 0)\n succeeds for a zombie (the process exited but has not been reaped), which\n must not count as a live worker when classifying a reap: a zombie leader\n means the worker is gone (died-without-result), not still running (timeout).\n Falls back to the kill -0 result when process state is unavailable.\"\"\"\n if IS_WINDOWS:\n # Windows has no \u003cdefunct> zombie state -- a terminated process's handle\n # is signaled and OpenProcess-based liveness already reports it dead.\n return _win_pid_alive(pid)\n if not _pid_alive(pid):\n return False\n try:\n out = subprocess.run(\n [\"ps\", \"-o\", \"state=\", \"-p\", str(pid)],\n capture_output=True, text=True, check=False,\n ).stdout.strip()\n except OSError:\n return True\n if not out:\n return False\n return not out.startswith(\"Z\")\n\n\ndef _kill_quiet(pid: int, sig: int) -> bool:\n try:\n os.kill(pid, sig)\n return True\n except OSError:\n return False\n\n\ndef _killpg_quiet(pgid: int, sig: int) -> bool:\n try:\n os.killpg(pgid, sig)\n return True\n except OSError:\n return False\n\n\ndef _descendants_deepest_first(root_pid: int):\n \"\"\"Fallback tree enumeration via ps when a process-group kill is not\n available: children die before their parents can respawn or orphan them.\"\"\"\n try:\n out = subprocess.run(\n [\"ps\", \"-eo\", \"pid=,ppid=\"], capture_output=True, text=True, check=False\n ).stdout\n except OSError:\n return []\n children = {}\n for line in out.splitlines():\n parts = line.split()\n if len(parts) != 2:\n continue\n try:\n pid, ppid = int(parts[0]), int(parts[1])\n except ValueError:\n continue\n children.setdefault(ppid, []).append(pid)\n order, queue = [], [root_pid]\n while queue:\n for child in children.get(queue.pop(0), []):\n order.append(child)\n queue.append(child)\n return list(reversed(order))\n\n\ndef _signal_group_or_tree(pid: int, sig: int) -> None:\n \"\"\"Signal the pid's process group, falling back to a deepest-first tree\n walk when the group kill is unavailable.\"\"\"\n if not _killpg_quiet(pid, sig):\n for descendant in _descendants_deepest_first(pid):\n _kill_quiet(descendant, sig)\n _kill_quiet(pid, sig)\n\n\ndef _pre_reuse_descendant_pids(root_pid, children, predates_reuse, skip_pid=None):\n \"\"\"Direct children that predate a recycled leader pid, plus each of those\n children's full subtree.\n\n Toolhelp still lists the original tree under a dead pid as parent, mixed\n with the new process's own children. The start-time cutoff applies only to\n direct children. A pre-reuse child's later descendants stay original-tree\n work even if they started after the reuse.\n \"\"\"\n keep = set()\n queue = []\n for child in children.get(root_pid, []):\n if skip_pid is not None and child == skip_pid:\n continue\n if not predates_reuse(child):\n continue\n queue.append(child)\n while queue:\n pid = queue.pop(0)\n if skip_pid is not None and pid == skip_pid:\n continue\n if pid in keep:\n continue\n keep.add(pid)\n queue.extend(children.get(pid, []))\n return keep\n\n\ndef kill_tree(root_pid: int, grace: float, job_name=None, expected_identity=None) -> bool:\n \"\"\"TERM the pid's process group (workers are started as group leaders),\n falling back to a deepest-first tree walk; grace, then KILL survivors.\n\n `job_name` is Windows-only (the worker's job object, the pgid analog) and\n is ignored on POSIX, where the pgid is derived from the pid itself.\n `expected_identity` is Windows-only (GetProcessTimes identity recorded at\n start) and is ignored on POSIX.\"\"\"\n if IS_WINDOWS:\n return _win_kill_tree(root_pid, grace, job_name, expected_identity)\n # Do NOT early-return just because the leader pid is dead: killpg targets\n # the pgid, which persists while any group member lives even after the\n # leader exits, so a dead leader can still front a live group we must sweep.\n # Use _pid_running (zombie-aware), not _pid_alive: a just-exited leader is\n # briefly a \u003cdefunct> zombie for which kill -0 still succeeds, and counting\n # that as alive would misclassify the reap as timeout instead of\n # died-without-result (and make the dead-leader sweep test timing-dependent).\n leader_alive = _pid_running(root_pid)\n # Snapshot the descendant set BEFORE any KILL: once the group leader is\n # reaped its children reparent to init and drop out of the tree, so a set\n # enumerated after the kill would miss them and leak orphans.\n survivors = _descendants_deepest_first(root_pid)\n _signal_group_or_tree(root_pid, signal.SIGTERM)\n deadline = time.monotonic() + grace\n while time.monotonic() \u003c deadline:\n if leader_alive and not _pid_alive(root_pid):\n break\n time.sleep(0.1)\n _killpg_quiet(root_pid, signal.SIGKILL)\n for pid in survivors:\n _kill_quiet(pid, signal.SIGKILL)\n _kill_quiet(root_pid, signal.SIGKILL)\n return leader_alive\n\n\n# --- the supervisor (runs inside the detached session) -------------------------\n\ndef classify_exit(rc: int, result_path, conf: dict):\n result_size = None\n if result_path:\n try:\n st = os.lstat(result_path)\n if stat.S_ISREG(st.st_mode) and st.st_size > 0:\n result_size = st.st_size\n except OSError:\n pass\n if result_size is not None and result_size > conf[\"result_max\"]:\n return \"failed\", (\n f\"result exceeded byte cap ({result_size} > {conf['result_max']} bytes)\"\n )\n if rc == 0:\n if result_path is None or result_size is not None:\n return \"done\", \"worker exited 0\"\n return \"failed\", \"worker exited 0 without publishing a non-empty result\"\n if rc \u003c 0:\n if result_size is not None:\n return \"done\", f\"worker killed by signal {-rc} after publishing its result\"\n return \"died-without-result\", (\n f\"worker killed by signal {-rc} with no result evidence\"\n )\n return \"failed\", f\"worker exited {rc}\"\n\n\ndef classify_exit_with_pending_reap(rc: int, result_path, conf: dict, reap_pending: bool):\n \"\"\"Classify a worker that already exited, optionally under a pending reap.\n\n When reap is pending (Windows `.reap` or POSIX SIGTERM flag) and the worker\n was killed by the fallback path, classify_exit would record \"failed\" for a\n non-zero kill exit — prefer timeout. When the worker already completed\n successfully (done + result), keep that: a late reap must not rewrite a\n finished peer run.\n \"\"\"\n state, reason = classify_exit(rc, result_path, conf)\n if reap_pending and state != \"done\":\n return \"timeout\", \"reaped on request before completion\"\n return state, reason\n\n\ndef _reap_worker(proc, conf: dict, job_name=None) -> None:\n # Deliberately parallel to kill_tree but driven by proc.poll(): an unreaped\n # Popen child is a zombie that os.kill(pid, 0) still reports alive, so the\n # pid-based liveness check would burn the whole grace window.\n if proc.poll() is not None:\n return\n if IS_WINDOWS:\n _win_kill_tree(proc.pid, conf[\"grace\"], job_name)\n try:\n proc.wait(timeout=5)\n except Exception:\n pass\n return\n _signal_group_or_tree(proc.pid, signal.SIGTERM)\n deadline = time.monotonic() + conf[\"grace\"]\n while time.monotonic() \u003c deadline:\n if proc.poll() is not None:\n break\n time.sleep(0.1)\n if proc.poll() is None:\n _killpg_quiet(proc.pid, signal.SIGKILL)\n for pid in _descendants_deepest_first(proc.pid):\n _kill_quiet(pid, signal.SIGKILL)\n try:\n proc.wait(timeout=5)\n except Exception:\n pass\n\n\ndef _reap_requested(flag: dict, job_dir: str) -> bool:\n \"\"\"POSIX delivers the reap as SIGTERM (sets flag). Windows has no reliable\n directed-signal path to a detached, console-less supervisor, so cmd_reap\n drops a `.reap` marker in the job dir and the loop polls for it.\"\"\"\n if flag[\"reap\"]:\n return True\n if IS_WINDOWS and os.path.lexists(os.path.join(job_dir, \".reap\")):\n return True\n return False\n\n\ndef _interruptible_sleep(secs: float, flag: dict, job_dir: str) -> None:\n end = time.monotonic() + secs\n while time.monotonic() \u003c end:\n # On POSIX _reap_requested reduces to flag[\"reap\"] (the IS_WINDOWS\n # branch never fires), so this is the original signal-driven behavior.\n if _reap_requested(flag, job_dir):\n return\n time.sleep(min(0.1, max(0.01, end - time.monotonic())))\n\n\ndef _is_system32_wsl_bash(path: str) -> bool:\n \"\"\"True for Windows System32 WSL launchers, including Sysnative aliases.\"\"\"\n if not path:\n return False\n base = os.path.basename(path).lower()\n if base not in (\"bash\", \"bash.exe\", \"sh\", \"sh.exe\"):\n return False\n system_root = os.environ.get(\"SystemRoot\") or r\"C:\\Windows\"\n windows_root = os.path.abspath(system_root)\n blocked_parents = {\n os.path.normcase(os.path.join(windows_root, name))\n for name in (\"System32\", \"Sysnative\")\n }\n parent = os.path.normcase(os.path.dirname(os.path.abspath(path)))\n return parent in blocked_parents\n\n\ndef _git_bash_well_known_paths():\n \"\"\"Standard Git for Windows bash.exe locations.\"\"\"\n pf64 = os.environ.get(\"ProgramW6432\") or \"\"\n pf = os.environ.get(\"ProgramFiles\") or r\"C:\\Program Files\"\n pf86 = os.environ.get(\"ProgramFiles(x86)\") or r\"C:\\Program Files (x86)\"\n local = os.environ.get(\"LOCALAPPDATA\") or \"\"\n roots = []\n seen = set()\n for root in (pf64, pf, pf86):\n if not root:\n continue\n key = os.path.normcase(os.path.abspath(root))\n if key in seen:\n continue\n seen.add(key)\n roots.append(root)\n paths = []\n for root in roots:\n paths.extend([\n os.path.join(root, \"Git\", \"bin\", \"bash.exe\"),\n os.path.join(root, \"Git\", \"usr\", \"bin\", \"bash.exe\"),\n ])\n if local:\n paths.extend([\n os.path.join(local, \"Programs\", \"Git\", \"bin\", \"bash.exe\"),\n os.path.join(local, \"Programs\", \"Git\", \"usr\", \"bin\", \"bash.exe\"),\n ])\n return paths\n\n\ndef _windows_path_shell_candidates():\n \"\"\"Every bash/sh on PATH in PATH order (not only shutil.which's first hit).\"\"\"\n path_env = os.environ.get(\"PATH\") or \"\"\n names = (\"bash.exe\", \"bash\", \"sh.exe\", \"sh\")\n found = []\n seen = set()\n for directory in path_env.split(os.pathsep):\n if not directory:\n continue\n for name in names:\n candidate = os.path.join(directory, name)\n try:\n if not os.path.isfile(candidate):\n continue\n except OSError:\n continue\n key = os.path.normcase(os.path.abspath(candidate))\n if key in seen:\n continue\n seen.add(key)\n found.append(candidate)\n return found\n\n\ndef _env_assignment_token(token: str, allow_option_like: bool = False) -> bool:\n \"\"\"True for env(1) NAME=value operands (not options or the command).\"\"\"\n if (\n not token\n or (token.startswith(\"-\") and not allow_option_like)\n or \"=\" not in token\n ):\n return False\n return True\n\n\ndef _env_option_advance(tok: str) -> int:\n \"\"\"How many argv slots an env(1) option occupies (incl. the option itself).\n\n GNU env options that take a separate operand: -u/--unset, -C/--chdir.\n Attached `--name=value` forms are a single slot.\n Short options may be clustered. No-operand flags (-i/-v and their exact\n long aliases and signal-handling options) advance one slot; -u/-C consume\n the rest of the token as an\n attached operand or the next argv slot. Unsupported options fail closed\n before worker detach.\n (#1292 Codex P2)\n \"\"\"\n if tok in (\"-u\", \"--unset\", \"-C\", \"--chdir\"):\n return 2\n if tok.startswith((\"--unset=\", \"--chdir=\")):\n return 1\n if tok in (\"--ignore-environment\", \"--debug\"):\n return 1\n if tok == \"--list-signal-handling\" or tok in (\n \"--block-signal\",\n \"--default-signal\",\n \"--ignore-signal\",\n ) or tok.startswith((\n \"--block-signal=\",\n \"--default-signal=\",\n \"--ignore-signal=\",\n )):\n return 1\n if tok == \"--null\":\n raise RunnerError(\n \"env -0/--null cannot be used with a command by native Windows \"\n \"peer workers; remove the null-output option\"\n )\n if not tok.startswith(\"-\"):\n return 1\n if tok.startswith(\"--\"):\n raise RunnerError(\n f\"unsupported env long option {tok!r} for native Windows peer \"\n \"workers; use an exact supported option or pass -- before \"\n \"option-like assignments\"\n )\n\n cluster = tok[1:]\n for index, option in enumerate(cluster):\n if option in \"iv\":\n continue\n if option == \"0\":\n raise RunnerError(\n \"env -0/--null cannot be used with a command by native \"\n \"Windows peer workers; remove the null-output option\"\n )\n if option == \"S\":\n raise RunnerError(\n \"env -S/--split-string is unsupported for native Windows \"\n \"peer workers; pass env assignments and the command as \"\n \"separate arguments\"\n )\n if option in \"uC\":\n return 1 if index + 1 \u003c len(cluster) else 2\n raise RunnerError(\n f\"unsupported env short-option cluster {tok!r} for native \"\n \"Windows peer workers; pass env options separately\"\n )\n return 1\n\n\ndef _env_bash_index(argv):\n \"\"\"Locate the env(1)-launched bash/sh command, for #1268/#1292 rewriting.\n\n Matches the production cross-model shape `env VAR=… bash script.sh …`\n (#1268). Operand-taking options (-u/-C and long forms) consume their\n arguments before the command token is sought (#1292). Split-string forms\n fail closed because Python shlex does not match Git env.exe semantics.\n\n Returns (argv_index, None), or (-1, None) when no bash/sh command is\n present.\n \"\"\"\n if not argv:\n return -1, None\n if os.path.basename(argv[0]).lower() not in (\"env\", \"env.exe\"):\n return -1, None\n i = 1\n options_done = False\n while i \u003c len(argv):\n tok = argv[i]\n if tok in (\"-\", \"--\") and not options_done:\n options_done = True\n i += 1\n continue\n if _env_assignment_token(tok, allow_option_like=options_done):\n options_done = True\n i += 1\n continue\n if not options_done and (\n tok in (\"-S\", \"--split-string\") or tok.startswith(\n (\"-S\", \"--split-string=\")\n )\n ):\n raise RunnerError(\n \"env -S/--split-string is unsupported for native Windows \"\n \"peer workers; pass env assignments and the command as \"\n \"separate arguments\"\n )\n if not options_done and tok.startswith(\"-\"):\n span = _env_option_advance(tok)\n if span > 1 and i + 1 >= len(argv):\n return -1, None\n i += span\n continue\n base = os.path.basename(tok).lower()\n if base in (\"bash\", \"bash.exe\", \"sh\", \"sh.exe\"):\n return i, None\n return -1, None\n return -1, None\n\n\ndef _windows_path_is_absolute(path: str) -> bool:\n \"\"\"True for Windows absolute paths (drive letter or path separator).\"\"\"\n return os.sep in path or (len(path) >= 2 and path[1] == \":\")\n\n\ndef _prefer_windows_posix_shell(token: str) -> str:\n \"\"\"Absolute non-WSL bash/sh kept; bare names and System32 go through resolve.\n\n Explicit absolute paths (portable Git, custom installs) must not be\n substituted by the preferred resolver (#1292 Codex P2). Bare `bash`/`sh`\n and System32 WSL launchers still use `_resolve_windows_posix_shell()`.\n \"\"\"\n if _windows_path_is_absolute(token):\n path = os.path.abspath(token)\n if not os.path.isfile(path):\n raise RunnerError(\n f\"peer worker shell does not exist or is not a regular file: {token}\"\n )\n if _is_system32_wsl_bash(path):\n return _resolve_windows_posix_shell()\n return path\n return _resolve_windows_posix_shell()\n\n\ndef _rewrite_windows_env_bash_argv(argv):\n \"\"\"Rewrite bare bash/sh inside an env-prefixed argv.\n\n Returns (argv, resolved_shell_or_None). Raises RunnerError when a bash/sh\n token is present but no usable non-WSL shell can be resolved. Absolute\n non-WSL bash tokens are kept unchanged (#1292 P2). Split-string options\n are rejected before detach because their parser semantics are not safely\n reproduced here (#1292).\n \"\"\"\n idx, split_prefix = _env_bash_index(argv)\n if idx \u003c 0:\n return list(argv), None\n out = list(argv)\n assert split_prefix is None\n shell = _prefer_windows_posix_shell(out[idx])\n if os.path.normcase(os.path.abspath(out[idx])) != os.path.normcase(shell):\n out[idx] = shell\n return out, shell\n\n\ndef _resolve_windows_posix_shell() -> str:\n \"\"\"Absolute path to a non-WSL POSIX shell for native Windows peer workers.\n\n Order: CE_PEER_BASH, CLAUDE_CODE_GIT_BASH_PATH, well-known Git Bash\n installs, then every PATH bash/sh excluding System32 WSL. Fail closed when\n nothing usable remains — never select System32\\\\bash.exe (#1268).\n \"\"\"\n candidates = []\n for key in (\"CE_PEER_BASH\", \"CLAUDE_CODE_GIT_BASH_PATH\"):\n val = (os.environ.get(key) or \"\").strip()\n if val:\n candidates.append(val)\n candidates.extend(_git_bash_well_known_paths())\n candidates.extend(_windows_path_shell_candidates())\n\n seen = set()\n for raw in candidates:\n path = os.path.abspath(raw)\n key = os.path.normcase(path)\n if key in seen:\n continue\n seen.add(key)\n if not os.path.isfile(path):\n continue\n if _is_system32_wsl_bash(path):\n continue\n return path\n\n raise RunnerError(\n \"no usable Git Bash (or other non-WSL POSIX shell) for native Windows \"\n \"peer workers; install Git for Windows or set CE_PEER_BASH / \"\n \"CLAUDE_CODE_GIT_BASH_PATH to an absolute bash.exe path \"\n \"(System32\\\\bash.exe / WSL is not used)\"\n )\n\n\ndef _popen_argv(argv):\n \"\"\"Argv for subprocess.Popen.\n\n On Windows, CreateProcess does not honor shebang, so a bare *.sh / *.bash\n worker must be launched through bash/sh. Prefer Git Bash over System32\n WSL bash (#1268). Bare `bash`/`sh` prefixes (review skills) and bare\n `bash`/`sh` tokens after `env VAR=…` (cross-model) are rewritten to that\n absolute path. Explicit absolute non-WSL bash/sh paths are kept (#1292 P2).\n meta.json still records the caller argv for authorize-dispatch contracts\n that forbid a shell prefix on ce-work.\n \"\"\"\n if not IS_WINDOWS or not argv:\n return list(argv)\n head = argv[0]\n base = os.path.basename(head).lower()\n if base in (\"env\", \"env.exe\"):\n rewritten, _shell = _rewrite_windows_env_bash_argv(argv)\n return rewritten\n if base in (\"bash\", \"bash.exe\", \"sh\", \"sh.exe\"):\n shell = _prefer_windows_posix_shell(head)\n if os.path.normcase(os.path.abspath(head)) == os.path.normcase(shell):\n return list(argv)\n return [shell] + list(argv[1:])\n lower = head.lower()\n if not (lower.endswith(\".sh\") or lower.endswith(\".bash\")):\n return list(argv)\n shell = _resolve_windows_posix_shell()\n return [shell, head] + list(argv[1:])\n\n\ndef supervise(job_dir: str, argv, result_path, conf: dict, ack_fd: int) -> None:\n \"\"\"The watchdog around the worker child. Owns liveness (out.log growth),\n the idle/hard windows, byte caps, reap-on-request, and the single terminal\n classification.\"\"\"\n flag = {\"reap\": False}\n\n def on_term(signum, frame):\n flag[\"reap\"] = True\n\n if not IS_WINDOWS:\n signal.signal(signal.SIGTERM, on_term)\n signal.signal(signal.SIGHUP, signal.SIG_IGN)\n # On Windows there is no SIGHUP and no reliable directed SIGTERM to a\n # detached supervisor; reap arrives via the `.reap` marker polled below.\n\n acked = False\n\n def ack():\n nonlocal acked\n if acked:\n return\n acked = True\n # Windows detach has no ack pipe (ack_fd is None): the pid file written\n # just above IS the ack, and the parent polls for it.\n if ack_fd is None:\n return\n try:\n os.write(ack_fd, b\"ok\")\n os.close(ack_fd)\n except OSError:\n pass\n\n log_fd = None\n job_name = None\n job_handle = None\n try:\n log_fd = os.open(\n os.path.join(job_dir, \"out.log\"),\n os.O_WRONLY | os.O_APPEND | O_NOFOLLOW | O_BINARY)\n if IS_WINDOWS:\n # Created BEFORE the worker so the tree can never start outside it.\n # The handle is held for the supervisor's lifetime; the job is what\n # makes teardown reach descendants of an exited leader.\n job_name = _win_job_name(job_dir)\n job_handle = _win_create_job(job_name)\n devnull = os.open(os.devnull, os.O_RDONLY)\n try:\n # Export the interpreter running this supervisor so Windows workers\n # (and any adapter that honors it) do not re-resolve to the Store\n # python3 stub — see resolve-python convention / #1247.\n worker_env = {\n **os.environ,\n \"CE_PEER_JOB_ID\": os.path.basename(job_dir),\n \"CE_PEER_PYTHON\": sys.executable,\n }\n popen_kwargs = dict(\n stdin=devnull,\n stdout=log_fd,\n stderr=log_fd,\n env=worker_env,\n close_fds=True,\n )\n if IS_WINDOWS:\n # New process group so the worker's own tree is isolated; reap =\n # job terminate + Toolhelp walk (there is no killpg on Windows).\n # CREATE_NO_WINDOW because the supervisor is console-less, so\n # without it Windows allocates a NEW console per worker and the\n # user sees a window flash for every job. (It is mutually\n # exclusive with DETACHED_PROCESS, which is why the supervisor\n # itself uses DETACHED_PROCESS and only the worker uses this.)\n # CREATE_SUSPENDED: assign to the Job Object before any worker\n # code runs, so early child spawns inherit membership.\n popen_kwargs[\"creationflags\"] = (\n subprocess.CREATE_NEW_PROCESS_GROUP\n | _WIN_NO_WINDOW\n | _CREATE_SUSPENDED)\n else:\n popen_kwargs[\"start_new_session\"] = True # worker leads its own group\n # Wrap bare *.sh on Windows at spawn time only — meta still has the\n # caller argv (see _popen_argv).\n proc = subprocess.Popen(_popen_argv(argv), **popen_kwargs)\n finally:\n os.close(devnull)\n pid_doc = {\n \"supervisor_pid\": os.getpid(),\n \"worker_pid\": proc.pid,\n }\n if IS_WINDOWS:\n sup_ident = _win_process_identity(os.getpid())\n worker_ident = _win_process_identity(proc.pid)\n if sup_ident:\n pid_doc[\"supervisor_identity\"] = sup_ident\n if worker_ident:\n pid_doc[\"worker_identity\"] = worker_ident\n # Assign while still suspended, then resume. Record the job only\n # once the worker is actually a member, so a later reap never trusts\n # a name that owns nothing. If assignment fails (job creation denied,\n # or a nested-job restriction), leave it unset and let teardown fall\n # back to the Toolhelp walk.\n if job_handle is not None and _win_assign_to_job(job_handle, proc.pid):\n pid_doc[\"job_name\"] = job_name\n else:\n job_name = None\n if not _win_resume_process(proc.pid):\n raise RunnerError(\n f\"could not resume suspended Windows worker pid {proc.pid}\"\n )\n else:\n # pgid drives POSIX group kills; Windows reaps by job object.\n pid_doc[\"supervisor_pgid\"] = os.getpgid(0)\n # The pid file lands before the parent is acked, so a returned `start`\n # guarantees the detach marker exists (status never mis-reads a fresh\n # job as never-started).\n write_atomic(os.path.join(job_dir, \"pid\"), (json.dumps(pid_doc) + \"\\n\").encode())\n except Exception as exc:\n write_terminal(job_dir, \"failed\", f\"could not launch worker: {exc}\")\n ack()\n return\n ack()\n\n start_t = time.monotonic()\n last_growth = start_t\n last_size = 0\n while True:\n rc = proc.poll()\n if rc is not None:\n state, reason = classify_exit_with_pending_reap(\n rc, result_path, conf, _reap_requested(flag, job_dir),\n )\n break\n if _reap_requested(flag, job_dir):\n # Classification is fixed BEFORE the kill: even if the worker\n # publishes and exits 0 during the grace window, the supervisor's\n # record wins.\n _reap_worker(proc, conf, job_name)\n state, reason = \"timeout\", \"reaped on request before completion\"\n break\n try:\n size = os.fstat(log_fd).st_size\n except OSError:\n size = last_size\n now = time.monotonic()\n if size > last_size:\n last_size, last_growth = size, now\n if size > conf[\"log_max\"]:\n _reap_worker(proc, conf, job_name)\n state, reason = \"failed\", (\n f\"out.log exceeded byte cap ({size} > {conf['log_max']} bytes)\"\n )\n break\n if conf[\"idle\"] is not None and now - last_growth >= conf[\"idle\"]:\n _reap_worker(proc, conf, job_name)\n state, reason = \"timeout\", f\"no output for {conf['idle']:g}s (idle window)\"\n break\n if now - start_t >= conf[\"hard\"]:\n _reap_worker(proc, conf, job_name)\n state, reason = \"timeout\", f\"hard cap {conf['hard']:g}s exceeded\"\n break\n _interruptible_sleep(conf[\"poll\"], flag, job_dir)\n # An externally killed worker can leave group members behind (its shell's\n # children); sweep the group before publishing so no orphan outlives the\n # terminal record. A pgid cannot be recycled while members remain.\n if IS_WINDOWS:\n # Job-object sweep: unlike taskkill this still reaches descendants when\n # the worker leader has already exited, which is the orphan case the\n # POSIX killpg pair below covers.\n _win_kill_tree(proc.pid, min(conf[\"grace\"], 1.0), job_name)\n else:\n _killpg_quiet(proc.pid, signal.SIGTERM)\n _killpg_quiet(proc.pid, signal.SIGKILL)\n write_terminal(job_dir, state, reason)\n\n\ndef detach_supervisor(job_dir: str, argv, result_path, conf: dict) -> bool:\n \"\"\"setsid double-fork. The grandchild (new session, stdio on /dev/null,\n reparented to init) runs the supervisor; the parent returns once the\n supervisor acks that the pid file exists.\"\"\"\n if IS_WINDOWS:\n return detach_supervisor_windows(job_dir, argv, result_path, conf)\n sys.stdout.flush()\n sys.stderr.flush()\n read_fd, write_fd = os.pipe()\n pid1 = os.fork()\n if pid1 == 0:\n os.close(read_fd)\n os.setsid()\n if os.fork() > 0:\n os._exit(0)\n rc = 0\n try:\n devnull = os.open(os.devnull, os.O_RDWR)\n os.dup2(devnull, 0)\n os.dup2(devnull, 1)\n os.dup2(devnull, 2)\n if devnull > 2:\n os.close(devnull)\n supervise(job_dir, argv, result_path, conf, write_fd)\n except BaseException:\n rc = 1\n try:\n write_terminal(\n job_dir, \"failed\", \"supervisor crashed before classification\",\n overwrite=False,\n )\n except BaseException:\n pass\n os._exit(rc)\n os.close(write_fd)\n os.waitpid(pid1, 0)\n ack = b\"\"\n try:\n while len(ack) \u003c 2:\n chunk = os.read(read_fd, 2 - len(ack))\n if not chunk:\n break\n ack += chunk\n finally:\n os.close(read_fd)\n return ack == b\"ok\"\n\n\ndef detach_supervisor_windows(job_dir: str, argv, result_path, conf: dict) -> bool:\n \"\"\"Windows detach: there is no fork/setsid, so re-invoke this script as a\n fresh DETACHED_PROCESS running the internal `__supervise` entrypoint. The\n spawn spec travels through an owner-private file in the job dir; the parent\n returns once the supervisor has left its ack marker (the pid file, or a\n terminal status if the worker could not launch). CREATE_BREAKAWAY_FROM_JOB\n is the analog of setsid's reparent-to-init: it lets the supervisor outlive a\n launching harness that runs inside a kill-on-close Job Object, falling back\n when the job forbids breakaway.\"\"\"\n spec = {\"argv\": list(argv), \"result_path\": result_path, \"conf\": conf}\n create_exclusive(\n os.path.join(job_dir, \".spawn.json\"),\n (json.dumps(spec) + \"\\n\").encode(),\n )\n cmd = [sys.executable, os.path.abspath(__file__), \"__supervise\", job_dir]\n base_flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP\n devnull = os.open(os.devnull, os.O_RDWR)\n proc = None\n try:\n for flags in (base_flags | subprocess.CREATE_BREAKAWAY_FROM_JOB, base_flags):\n try:\n proc = subprocess.Popen(\n cmd,\n stdin=devnull, stdout=devnull, stderr=devnull,\n close_fds=True, creationflags=flags,\n )\n break\n except OSError:\n proc = None\n if proc is None:\n return False\n finally:\n os.close(devnull)\n\n pid_path = os.path.join(job_dir, \"pid\")\n status_path = os.path.join(job_dir, \"status\")\n deadline = time.monotonic() + 15.0\n while time.monotonic() \u003c deadline:\n if os.path.lexists(pid_path) or os.path.lexists(status_path):\n return True\n if proc.poll() is not None:\n # Supervisor process exited without leaving a marker: detach failed.\n return os.path.lexists(pid_path) or os.path.lexists(status_path)\n time.sleep(0.05)\n # Deadline with the supervisor still running. Do not abandon it: reporting\n # a detach failure while leaving a live, unreachable supervisor/worker pair\n # behind is exactly the orphan this runner exists to prevent. The snapshot\n # walk reaches the worker as the supervisor's child.\n try:\n if proc.poll() is None:\n _win_kill_tree(proc.pid, 0.0)\n except Exception:\n pass\n return False\n\n\ndef _win_supervise_from_spec(job_dir: str) -> int:\n \"\"\"Internal `__supervise` entrypoint: the detached Windows supervisor. Drops\n its console-less std handles onto NUL, reads the owner-checked spawn spec,\n and runs the shared supervisor loop with a file-based (not fd) ack.\"\"\"\n rc = 0\n # Redundant with detach_supervisor_windows, which already binds this\n # process's stdio to NUL via Popen -- kept deliberately so the entrypoint is\n # self-contained: a supervisor is long-lived, and any future/manual\n # invocation that inherited a real pipe could block forever once it filled.\n try:\n devnull = os.open(os.devnull, os.O_RDWR)\n for fd in (0, 1, 2):\n try:\n os.dup2(devnull, fd)\n except OSError:\n pass\n if devnull > 2:\n os.close(devnull)\n except OSError:\n pass\n try:\n _check_owned_dir(job_dir)\n spec = json.loads(read_owned(os.path.join(job_dir, \".spawn.json\"), META_READ_CAP))\n argv = spec[\"argv\"]\n result_path = spec.get(\"result_path\")\n conf = spec[\"conf\"]\n try:\n os.unlink(os.path.join(job_dir, \".spawn.json\"))\n except OSError:\n pass\n supervise(job_dir, argv, result_path, conf, None)\n except BaseException:\n rc = 1\n try:\n write_terminal(\n job_dir, \"failed\", \"supervisor crashed before classification\",\n overwrite=False,\n )\n except BaseException:\n pass\n return rc\n\n\n# --- subcommands ---------------------------------------------------------------\n\ndef sweep_stale_runs(skill_dir: str, keep: str) -> None:\n \"\"\"Best-effort retention: remove sibling run roots older than 24h.\n Owner-checked via lstat; never raises, never touches the current run.\"\"\"\n try:\n entries = list(os.scandir(skill_dir))\n except OSError:\n return\n now = time.time()\n euid = _euid()\n keep_abs = os.path.abspath(keep)\n for entry in entries:\n if os.path.abspath(entry.path) == keep_abs:\n continue\n try:\n st = entry.stat(follow_symlinks=False)\n except OSError:\n continue\n if not stat.S_ISDIR(st.st_mode):\n continue\n if IS_WINDOWS:\n try:\n if not _win_owns_path(entry.path):\n continue\n except OSError:\n continue\n elif euid is not None and st.st_uid != euid:\n continue\n if now - st.st_mtime \u003c= SWEEP_AGE_SECS:\n continue\n shutil.rmtree(entry.path, ignore_errors=True)\n\n\ndef _require_detach_support() -> None:\n \"\"\"Detached peer jobs need a supported detach path: os.fork/os.setsid on\n POSIX, or the native Windows DETACHED_PROCESS path (#1243). Checked first,\n before jobs_root_base()/geteuid, so an unsupported host fails with this clear\n message instead of jobs_root_base()'s unrelated \"effective user ID is\n unavailable\" error or an AttributeError mid-detach. Native Windows is now\n supported; only a non-win32 Python missing fork/setsid (some embedded\n builds) is rejected here.\"\"\"\n if IS_WINDOWS:\n return\n if not hasattr(os, \"fork\") or not hasattr(os, \"setsid\"):\n raise RunnerError(\n \"detached peer jobs require os.fork/os.setsid on this platform; no \"\n \"job was started. Run under a POSIX Python, or on native Windows use \"\n \"a Windows Python 3 build (see \"\n \"EveryInc/compound-engineering-plugin#1243).\"\n )\n\n\ndef cmd_start(args, worker_argv) -> int:\n _require_detach_support()\n for flag, value in ((\"--skill\", args.skill), (\"--run-id\", args.run_id)):\n if not _is_safe_token(value):\n raise RunnerError(f\"{flag} must match [A-Za-z0-9._-]+ and not be all dots (got {value!r})\")\n if args.label is not None and not _is_safe_token(args.label):\n raise RunnerError(f\"--label must match [A-Za-z0-9._-]+ and not be all dots (got {args.label!r})\")\n if not worker_argv:\n raise RunnerError(\"no worker argv; place it after `--`\")\n\n base = jobs_root_base()\n skill_dir = skill_runs_root(args.skill)\n run_dir = os.path.join(skill_dir, args.run_id)\n jobs_root = os.path.join(run_dir, \"jobs\")\n ensure_owned_dirs(skill_dir if skill_dir != os.path.join(base, args.skill) else base, jobs_root)\n if not args.no_sweep:\n sweep_stale_runs(skill_dir, keep=run_dir)\n\n job_id, job_dir = claim_job_dir(jobs_root)\n result_path = os.path.abspath(args.result_path) if args.result_path else None\n\n argv0 = worker_argv[0]\n problem = None\n windows_posix_shell = None\n base0 = os.path.basename(argv0).lower()\n if IS_WINDOWS and base0 in (\"bash\", \"bash.exe\", \"sh\", \"sh.exe\"):\n # Prefer Git Bash over PATH/System32 WSL before meta + detach (#1268).\n # Keep an explicit absolute non-WSL bash (portable Git) (#1292 P2).\n try:\n resolved = _prefer_windows_posix_shell(argv0)\n windows_posix_shell = resolved\n except RunnerError as exc:\n problem = str(exc)\n resolved = argv0\n elif IS_WINDOWS and base0 in (\"env\", \"env.exe\"):\n # Production cross-model: env VAR=… bash script.sh — rewrite bash\n # before detach so env cannot PATH-resolve System32 WSL (#1268).\n if os.sep in argv0 or (len(argv0) >= 2 and argv0[1] == \":\"):\n resolved = os.path.abspath(argv0)\n if not os.path.isfile(resolved):\n problem = \"does not exist or is not a regular file\"\n else:\n resolved = shutil.which(argv0)\n if resolved is None:\n problem = \"was not found on PATH\"\n resolved = argv0\n try:\n rewritten, shell = _rewrite_windows_env_bash_argv(list(worker_argv))\n if shell is not None:\n windows_posix_shell = shell\n worker_argv = rewritten\n except RunnerError as exc:\n problem = str(exc) if problem is None else f\"{problem}; {exc}\"\n elif os.sep in argv0 or (IS_WINDOWS and len(argv0) >= 2 and argv0[1] == \":\"):\n resolved = os.path.abspath(argv0)\n if not os.path.isfile(resolved):\n problem = \"does not exist or is not a regular file\"\n elif IS_WINDOWS and resolved.lower().endswith((\".sh\", \".bash\")):\n # CreateProcess cannot run shebang scripts; _popen_argv wraps with\n # Git Bash. Require that shell now so start fails closed, not after\n # detach. Skip the X_OK check — Windows often marks .sh non-exec.\n try:\n windows_posix_shell = _resolve_windows_posix_shell()\n except RunnerError as exc:\n problem = str(exc)\n elif not os.access(resolved, os.X_OK):\n problem = \"is not executable\"\n else:\n resolved = shutil.which(argv0)\n if resolved is None:\n problem = \"was not found on PATH\"\n resolved = argv0\n elif IS_WINDOWS and resolved.lower().endswith((\".sh\", \".bash\")):\n try:\n windows_posix_shell = _resolve_windows_posix_shell()\n except RunnerError as exc:\n problem = str(exc)\n elif IS_WINDOWS and os.path.basename(resolved).lower() in (\n \"bash\", \"bash.exe\", \"sh\", \"sh.exe\",\n ):\n # which() may have returned System32 WSL — rewrite now.\n try:\n resolved = _resolve_windows_posix_shell()\n windows_posix_shell = resolved\n except RunnerError as exc:\n problem = str(exc)\n argv = [resolved] + list(worker_argv[1:])\n\n conf = cfg(args.skill)\n meta = {\n \"job_id\": job_id,\n \"skill\": args.skill,\n \"run_id\": args.run_id,\n \"label\": args.label,\n \"input_digest\": args.input_digest,\n \"started_at\": time.strftime(STARTED_AT_FORMAT, time.gmtime()),\n \"worker_argv\": argv,\n \"result_path\": result_path,\n \"sweep_enabled\": not args.no_sweep,\n \"supervision\": conf,\n }\n if windows_posix_shell:\n meta[\"windows_posix_shell\"] = windows_posix_shell\n try:\n create_exclusive(\n os.path.join(job_dir, \"meta.json\"),\n (json.dumps(meta, indent=2) + \"\\n\").encode(),\n )\n except OSError as exc:\n raise RunnerError(f\"cannot write job metadata for {job_id}: {exc}\")\n\n if problem is not None:\n raise RunnerError(\n f\"preflight failed for job {job_id}: worker {argv0!r} {problem}; \"\n f\"nothing was detached (job left never-started at {job_dir})\"\n )\n try:\n create_exclusive(os.path.join(job_dir, \"out.log\"))\n except OSError as exc:\n raise RunnerError(\n f\"preflight failed for job {job_id}: job dir not writable ({exc}); \"\n \"nothing was detached\"\n )\n\n if not detach_supervisor(job_dir, argv, result_path, conf):\n raise RunnerError(\n f\"detach failed for job {job_id}: supervisor did not acknowledge; \"\n f\"inspect {job_dir}\"\n )\n print(job_id)\n return 0\n\n\ndef _emit_states(rows, as_json: bool) -> None:\n if as_json:\n print(json.dumps(\n [{\"ref\": r, \"job_dir\": d, \"state\": s} for r, d, s in rows]\n ))\n elif len(rows) == 1:\n print(rows[0][2])\n else:\n for ref, _, state in rows:\n print(f\"{ref}\\t{state}\")\n\n\ndef cmd_status(args) -> int:\n rows = []\n for ref in args.jobs:\n job_dir = resolve_job_dir(ref, args.skill)\n rows.append((ref, job_dir, job_state(job_dir)))\n _emit_states(rows, args.json)\n return 0\n\n\ndef _finite_secs(raw: str) -> float:\n try:\n value = float(raw)\n except ValueError:\n raise argparse.ArgumentTypeError(f\"not a number of seconds: {raw!r}\")\n if not math.isfinite(value) or value \u003c 0:\n raise argparse.ArgumentTypeError(f\"must be a finite, nonnegative number of seconds: {raw!r}\")\n return value\n\n\ndef _job_meta(job_dir: str) -> dict:\n try:\n meta = json.loads(read_owned(os.path.join(job_dir, \"meta.json\"), META_READ_CAP))\n except (Unreadable, OSError, ValueError):\n return {}\n return meta if isinstance(meta, dict) else {}\n\n\ndef _started_epoch(job_dir: str, meta: dict):\n try:\n return calendar.timegm(time.strptime(meta[\"started_at\"], STARTED_AT_FORMAT))\n except (KeyError, TypeError, ValueError):\n pass\n try:\n return os.lstat(os.path.join(job_dir, \"meta.json\")).st_mtime\n except OSError:\n return None\n\n\ndef _summary_reason(job_dir: str, state: str) -> str:\n if state == \"unreadable\":\n # Never read `reason` from a directory that failed its ownership check.\n return \"state unreadable (ownership or corruption); no result\"\n if state == \"never-started\":\n return job_reason(job_dir) or \"never started; no result\"\n if state in TERMINAL_STATES and state != \"done\":\n return job_reason(job_dir)\n return \"\"\n\n\ndef _emit_deadline_summary(rows, metas, deadline_at, as_json: bool) -> None:\n now = time.time()\n jobs = []\n for ref, d, state in rows:\n meta = metas[ref]\n started = _started_epoch(d, meta)\n jobs.append({\n \"ref\": ref,\n \"job_dir\": d,\n \"label\": meta.get(\"label\") or \"-\",\n \"state\": state,\n \"elapsed_secs\": int(now - started) if started is not None else None,\n \"reason\": _summary_reason(d, state),\n })\n running = [j[\"ref\"] for j in jobs if j[\"state\"] == \"running\"]\n secs_left = max(0, math.ceil(deadline_at - now))\n deadline_passed = bool(running) and now >= deadline_at\n if as_json:\n print(json.dumps({\n \"jobs\": jobs,\n \"all_settled\": not running,\n \"deadline_passed\": deadline_passed,\n \"secs_left\": secs_left,\n }))\n return\n for j in jobs:\n elapsed = \"?\" if j[\"elapsed_secs\"] is None else f\"{j['elapsed_secs']}s\"\n print(f\"{j['label']}\\t{j['ref']}\\t{j['state']}\\t{elapsed}\" + (f\"\\t{j['reason']}\" if j[\"reason\"] else \"\"))\n if not running:\n print(\"all settled\")\n elif deadline_passed:\n print(\n f\"deadline passed: reap {' '.join(running)}, then wait once more; \"\n \"a job still running after that counts as timed out\"\n )\n else:\n print(f\"waiting: {len(running)} of {len(jobs)} still running; {secs_left}s left before the deadline\")\n\n\ndef cmd_wait(args) -> int:\n dirs = [(ref, resolve_job_dir(ref, args.skill)) for ref in args.jobs]\n deadline = time.monotonic() + max(0.0, args.max_secs)\n metas = {}\n deadline_at = None\n if args.deadline_secs is not None:\n metas = {ref: _job_meta(d) for ref, d in dirs}\n starts = [s for s in (_started_epoch(d, metas[ref]) for ref, d in dirs) if s is not None]\n # No start time anywhere means no way to measure the window: let it pass\n # now rather than restart it on every call.\n window = args.deadline_secs + args.deadline_grace_secs\n last_start = max(starts) if starts else time.time() - window\n deadline_at = last_start + window\n until_deadline = deadline_at - time.time()\n if until_deadline > 0:\n deadline = min(deadline, time.monotonic() + until_deadline)\n else:\n # Past the deadline, poll briefly so jobs just reaped can record\n # their terminal state before the summary prints.\n deadline = min(deadline, time.monotonic() + REAP_SETTLE_SECS)\n rows = [(ref, d, \"running\") for ref, d in dirs]\n while True:\n # Settled states are final; only still-running jobs get re-read.\n rows = [\n (ref, d, state if state != \"running\" else job_state(d))\n for ref, d, state in rows\n ]\n if all(state != \"running\" for _, _, state in rows):\n break\n remaining = deadline - time.monotonic()\n if remaining \u003c= 0:\n break\n time.sleep(min(1.0, remaining))\n if args.deadline_secs is not None:\n _emit_deadline_summary(rows, metas, deadline_at, args.json)\n else:\n _emit_states(rows, args.json)\n return 0\n\n\ndef _emit_bytes(data: bytes) -> None:\n buffer = getattr(sys.stdout, \"buffer\", None)\n if buffer is not None:\n buffer.write(data)\n buffer.flush()\n else:\n sys.stdout.write(data.decode(\"utf-8\", \"replace\"))\n\n\ndef _report_absent_artifact(target: str, args) -> int:\n \"\"\"An absent --path artifact is an outcome, not a read error: a peer that\n skipped its gate exits 0 and writes nothing, so the file is legitimately\n missing on the most common fold-in path. Name that outcome, and when the\n caller also passed the job id, name the job's state -- otherwise \"still\n running\" and \"ran, produced nothing\" arrive as one errno the caller cannot\n act on. Each outcome keeps the exit code the job-result contract already\n assigns it, so a trust or lookup failure never reads as the routine skip:\n 2 running, 4 ownership, 1 unknown job, 3 settled with no artifact.\"\"\"\n sys.stderr.write(f\"peer-job-runner: no artifact at {target}\\n\")\n if not args.job:\n return 3\n try:\n job_dir = resolve_job_dir(args.job, args.skill)\n except RunnerError as exc:\n sys.stderr.write(f\"peer-job-runner: {exc}\\n\")\n return 1\n state = job_state(job_dir)\n if state == \"unreadable\":\n # Do not read `reason` here: job_dir already failed its owner check, and\n # O_NOFOLLOW guards only the final component, so a swapped directory\n # could redirect that read.\n sys.stderr.write(\n f\"peer-job-runner: job state unreadable (ownership or corruption): {job_dir}\\n\"\n )\n return 4\n if state == \"running\":\n sys.stderr.write(f\"peer-job-runner: job {args.job} is still running\\n\")\n return 2\n reason = job_reason(job_dir)\n sys.stderr.write(\n f\"peer-job-runner: job {args.job}: {state}\" + (f\" ({reason})\" if reason else \"\") + \"\\n\"\n )\n return 3\n\n\ndef cmd_result(args) -> int:\n if not getattr(args, \"path\", None) and not args.job:\n sys.stderr.write(\"peer-job-runner: result needs a job id or --path FILE\\n\")\n return 2\n if getattr(args, \"path\", None):\n # Verified read of an arbitrary artifact: same fd-ownership check and\n # bounded read as job results. Exists because fold-in filenames can embed\n # values unknown at start time (so no --result-path was declared), yet the\n # consumer must never read a predictable /tmp path unchecked.\n target = os.path.abspath(args.path)\n try:\n data = read_owned(target, cfg()[\"result_max\"])\n except Unreadable as exc:\n sys.stderr.write(f\"peer-job-runner: unreadable: {exc}\\n\")\n return 4\n except FileNotFoundError:\n return _report_absent_artifact(target, args)\n except OSError as exc:\n # Only a genuine ENOENT is \"the peer produced nothing\". Every other\n # read failure means the path is there but was refused -- a planted\n # symlink rejected by O_NOFOLLOW is the case this guard exists for --\n # so it takes the trust-failure code, never the routine one.\n sys.stderr.write(f\"peer-job-runner: refused to read {target}: {exc}\\n\")\n return 4\n _emit_bytes(data)\n return 0\n job_dir = resolve_job_dir(args.job, args.skill)\n state = job_state(job_dir)\n if state == \"unreadable\":\n sys.stderr.write(\n f\"peer-job-runner: job state unreadable (ownership or corruption): {job_dir}\\n\"\n )\n return 4\n if state == \"running\":\n sys.stderr.write(\"peer-job-runner: running\\n\")\n return 2\n if state != \"done\":\n sys.stderr.write(f\"peer-job-runner: {state}\\n\")\n return 3\n conf = cfg()\n try:\n meta = json.loads(read_owned(os.path.join(job_dir, \"meta.json\"), META_READ_CAP))\n except Unreadable as exc:\n sys.stderr.write(f\"peer-job-runner: unreadable: {exc}\\n\")\n return 4\n except (OSError, ValueError) as exc:\n sys.stderr.write(f\"peer-job-runner: cannot read job metadata: {exc}\\n\")\n return 4\n result_path = meta.get(\"result_path\") if isinstance(meta, dict) else None\n if not result_path:\n sys.stderr.write(\"peer-job-runner: job declared no result path; nothing to emit\\n\")\n return 0\n try:\n data = read_owned(result_path, conf[\"result_max\"])\n except Unreadable as exc:\n sys.stderr.write(f\"peer-job-runner: unreadable: {exc}\\n\")\n return 4\n except OSError as exc:\n sys.stderr.write(f\"peer-job-runner: result missing or unreadable: {exc}\\n\")\n return 3\n _emit_bytes(data)\n return 0\n\n\ndef cmd_reap(args) -> int:\n codes = set()\n for ref in args.jobs:\n try:\n rc = _reap_one(ref, args.skill)\n except RunnerError as exc:\n sys.stderr.write(f\"peer-job-runner: {exc}\\n\")\n rc = 1\n if rc:\n sys.stderr.write(f\"peer-job-runner: reap {ref}: exit {rc}\\n\")\n codes.add(rc)\n # Exit codes are categories, so a mixed set reports the generic failure and\n # leaves the per-job detail on stderr.\n return codes.pop() if len(codes) == 1 else (1 if codes else 0)\n\n\ndef _reap_one(ref: str, skill) -> int:\n job_dir = resolve_job_dir(ref, skill)\n state = job_state(job_dir)\n if state in TERMINAL_STATES or state == \"never-started\":\n return 0\n if state == \"unreadable\":\n sys.stderr.write(\n f\"peer-job-runner: job state unreadable (ownership or corruption): {job_dir}\\n\"\n )\n return 4\n conf = cfg()\n pid_doc = None\n try:\n pid_doc = json.loads(read_owned(os.path.join(job_dir, \"pid\"), META_READ_CAP))\n except (Unreadable, OSError, ValueError):\n pid_doc = None\n if not isinstance(pid_doc, dict):\n pid_doc = {}\n sup_pid = pid_doc.get(\"supervisor_pid\")\n sup_pgid = pid_doc.get(\"supervisor_pgid\")\n worker_pid = pid_doc.get(\"worker_pid\")\n # Windows-only: the worker tree's job object. Named precisely so this\n # process -- which never held the supervisor's handle -- can reopen and\n # terminate the tree even after the worker leader has exited.\n job_name = pid_doc.get(\"job_name\")\n worker_identity = pid_doc.get(\"worker_identity\")\n supervisor_identity = pid_doc.get(\"supervisor_identity\")\n\n supervisor_ours = (\n isinstance(sup_pid, int)\n and not (IS_WINDOWS and sup_pid == os.getpid())\n and _pid_alive(sup_pid)\n and (\n not IS_WINDOWS\n or _win_process_identity_matches(sup_pid, supervisor_identity)\n )\n )\n if supervisor_ours:\n # The supervisor owns TERM-grace-KILL and the terminal classification.\n # POSIX signals it (SIGTERM to the group or pid); Windows drops the\n # `.reap` marker the supervisor's loop polls for.\n if IS_WINDOWS:\n try:\n with open(os.path.join(job_dir, \".reap\"), \"w\") as f:\n f.write(\"reap\\n\")\n signaled = True\n except OSError:\n signaled = False\n else:\n signaled = (isinstance(sup_pgid, int) and _killpg_quiet(sup_pgid, signal.SIGTERM)) \\\n or _kill_quiet(sup_pid, signal.SIGTERM)\n if signaled:\n # kill -0 is true for a zombie, so confirm the classification landed\n # rather than trusting the signal; fall through to self-cleanup if not.\n # Windows: the supervisor only notices `.reap` on its next poll tick\n # (default 2s), so min(grace, 1.0) alone is shorter than one poll and\n # races into the fallback self-classify path.\n wait_budget = min(conf[\"grace\"], 1.0)\n if IS_WINDOWS:\n wait_budget = max(wait_budget, conf[\"poll\"] + 0.25)\n deadline = time.monotonic() + wait_budget\n while time.monotonic() \u003c deadline:\n if job_state(job_dir) in TERMINAL_STATES:\n return 0\n time.sleep(0.05)\n\n # Supervisor gone: perform the tree kill and classification ourselves,\n # with a short grace so reap still returns quickly. Sweep whenever we have a\n # worker pid, NOT only when its leader is still alive: a child can survive in\n # the worker's process group after the leader exits, and kill_tree targets\n # the pgid precisely so that orphan is swept instead of leaked. Guarding this\n # on _pid_alive would re-defeat kill_tree's dead-leader-safe path. kill_tree\n # returns whether the leader was alive, which is the reap classification.\n worker_leader_alive = False\n if isinstance(worker_pid, int):\n worker_leader_alive = kill_tree(\n worker_pid, min(conf[\"grace\"], 1.0), job_name, worker_identity)\n # A worker can publish its declared result and exit before this fallback runs\n # (e.g. the supervisor died mid-run, then the worker completed cleanly). Honor\n # that result instead of discarding it as died-without-result: read the\n # declared result_path and classify from the artifact, mirroring\n # classify_exit. Only with no usable result do we fall back to timeout (leader\n # was alive) / died-without-result (leader gone).\n result_path = _job_meta(job_dir).get(\"result_path\")\n result_size = None\n if result_path:\n try:\n st = os.lstat(result_path)\n if stat.S_ISREG(st.st_mode) and st.st_size > 0:\n result_size = st.st_size\n except OSError:\n pass\n if result_size is not None and result_size > conf[\"result_max\"]:\n word, reason = \"failed\", (\n f\"result exceeded byte cap ({result_size} > {conf['result_max']} bytes)\"\n )\n elif result_size is not None:\n word, reason = \"done\", \"worker published its result before reap (supervisor was gone)\"\n elif worker_leader_alive:\n word, reason = \"timeout\", (\n \"reaped by request; supervisor was gone, worker tree killed by reap\"\n )\n else:\n word, reason = \"died-without-result\", (\n \"supervisor and worker both gone without a terminal record\"\n )\n write_terminal(job_dir, word, reason, overwrite=False)\n return 0\n\n\n# --- CLI -----------------------------------------------------------------------\n\ndef build_parser() -> argparse.ArgumentParser:\n parser = argparse.ArgumentParser(\n prog=\"peer-job-runner.py\",\n description=(\n \"Detached, supervised job lifecycle for delegated peer work: \"\n \"no call here ever spans the worker's runtime.\"\n ),\n epilog=EXIT_CODES_DOC,\n formatter_class=argparse.RawDescriptionHelpFormatter,\n )\n sub = parser.add_subparsers(dest=\"cmd\", required=True)\n\n p_start = sub.add_parser(\n \"start\",\n help=\"claim a job, preflight, detach the worker, print the job id\",\n )\n p_start.add_argument(\"--skill\", required=True)\n p_start.add_argument(\"--run-id\", required=True, dest=\"run_id\")\n p_start.add_argument(\"--label\", default=None)\n p_start.add_argument(\"--input-digest\", default=None, dest=\"input_digest\")\n p_start.add_argument(\n \"--result-path\", default=None, dest=\"result_path\",\n help=\"worker's expected result file; done then requires it non-empty\",\n )\n p_start.add_argument(\n \"--no-sweep\", action=\"store_true\",\n help=\"retain old sibling run roots (ce-work durable recovery)\",\n )\n\n p_status = sub.add_parser(\"status\", help=\"print each job's state word\")\n p_status.add_argument(\"--skill\", default=None, help=\"limit job-id lookup to this skill\")\n p_status.add_argument(\"--json\", action=\"store_true\")\n p_status.add_argument(\"jobs\", nargs=\"+\", help=\"job ids or job dir paths\")\n\n p_wait = sub.add_parser(\n \"wait\", help=\"bounded poll until all watched jobs settle (or the cap)\"\n )\n p_wait.add_argument(\"--skill\", default=None, help=\"limit job-id lookup to this skill\")\n p_wait.add_argument(\"--max-secs\", type=float, default=30.0, dest=\"max_secs\")\n p_wait.add_argument(\n \"--deadline-secs\", type=_finite_secs, default=None, dest=\"deadline_secs\",\n help=(\n \"aggregate deadline, counted from the last job's start; prints each \"\n \"job's label, state and elapsed time, then one line: 'all settled', \"\n \"'waiting: ...', or 'deadline passed: reap ...'\"\n ),\n )\n p_wait.add_argument(\n \"--deadline-grace-secs\", type=_finite_secs, default=0.0, dest=\"deadline_grace_secs\",\n help=\"added to --deadline-secs, so a caller can pass a worker cap unchanged\",\n )\n p_wait.add_argument(\"--json\", action=\"store_true\")\n p_wait.add_argument(\"jobs\", nargs=\"+\", help=\"job ids or job dir paths\")\n\n p_result = sub.add_parser(\n \"result\",\n help=\"emit a done job's artifact (exit: 0 done, 2 running, 3 other, 4 unreadable)\",\n )\n p_result.add_argument(\"--skill\", default=None, help=\"limit job-id lookup to this skill\")\n p_result.add_argument(\"job\", nargs=\"?\", default=None)\n p_result.add_argument(\n \"--path\",\n default=None,\n help=(\n \"ownership-checked bounded read of this file instead of a job's \"\n \"declared result; pass the job id too so an absent file reports \"\n \"that job's state\"\n ),\n )\n\n p_reap = sub.add_parser(\n \"reap\", help=\"terminate running jobs now; no-op for any already terminal\"\n )\n p_reap.add_argument(\"--skill\", default=None, help=\"limit job-id lookup to this skill\")\n p_reap.add_argument(\"jobs\", nargs=\"+\", help=\"job ids or job dir paths\")\n return parser\n\n\ndef main(argv) -> int:\n # Internal Windows detach re-invocation (not a user-facing subcommand): the\n # detached supervisor process runs `__supervise \u003cjob_dir>`. Gated on\n # IS_WINDOWS so POSIX keeps its previous behavior exactly (argparse usage\n # error), and so a non-win32 Python without geteuid -- where the ownership\n # checks degrade -- can never be steered into exec'ing argv from a planted\n # .spawn.json. Only the Windows detach path ever emits this argv.\n if IS_WINDOWS and argv and argv[0] == \"__supervise\":\n if len(argv) \u003c 2:\n return 2\n return _win_supervise_from_spec(argv[1])\n worker_argv = []\n if \"--\" in argv:\n split = argv.index(\"--\")\n argv, worker_argv = argv[:split], argv[split + 1:]\n args = build_parser().parse_args(argv)\n try:\n if args.cmd == \"start\":\n return cmd_start(args, worker_argv)\n if args.cmd == \"status\":\n return cmd_status(args)\n if args.cmd == \"wait\":\n return cmd_wait(args)\n if args.cmd == \"result\":\n return cmd_result(args)\n if args.cmd == \"reap\":\n return cmd_reap(args)\n return 2\n except RunnerError as exc:\n sys.stderr.write(f\"peer-job-runner: {exc}\\n\")\n return 1\n except Unreadable as exc:\n sys.stderr.write(f\"peer-job-runner: unreadable: {exc}\\n\")\n return 4\n\n\nif __name__ == \"__main__\":\n sys.exit(main(sys.argv[1:]))\n","content_type":"text/x-python; charset=utf-8","language":"python","size":109274,"content_sha256":"bf177d5142120d024b59d8285bbfea45505b6a226c333ddb4afc069228032412"},{"filename":"scripts/unit_workspace_ignored.py","content":"\"\"\"Metadata inventory of the canonical checkout's git-ignored entries.\n\nVerification runs in the canonical checkout; ignored state is never copied or\nrestored. Two inventories taken before and after verification diff into a\ndisclosure of changed, removed, and created ignored paths.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nimport stat\n\nfrom unit_workspace_state import Operational, git\n\n\ndef ignored_paths(repo: str) -> set[str]:\n raw = git(repo, \"ls-files\", \"--others\", \"--ignored\", \"--exclude-standard\", \"-z\", \"--\")\n return set(filter(None, raw.decode(\"utf-8\", \"surrogateescape\").split(\"\\0\")))\n\n\ndef artifact_path(repo: str, rel: str) -> str:\n repo = os.path.abspath(repo)\n target = os.path.abspath(os.path.join(repo, rel))\n if target == repo or os.path.commonpath([repo, target]) != repo:\n raise Operational(\"BLOCKED\", \"ignored artifact path escaped canonical repository\")\n return target\n\n\ndef _entry_type(mode: int) -> str:\n if stat.S_ISLNK(mode):\n return \"symlink\"\n if stat.S_ISDIR(mode):\n return \"directory\"\n if stat.S_ISREG(mode):\n return \"file\"\n return \"other\"\n\n\ndef inventory_ignored_state(repo: str) -> dict[str, tuple]:\n \"\"\"lstat every ignored entry; an entry that cannot be inspected is recorded, not refused.\"\"\"\n repo = os.path.abspath(repo)\n inventory: dict[str, tuple] = {}\n for rel in ignored_paths(repo):\n try:\n entry = os.lstat(artifact_path(repo, rel))\n except OSError:\n inventory[rel] = (\"uninspectable\",)\n continue\n inventory[rel] = (\n _entry_type(entry.st_mode),\n entry.st_size,\n entry.st_mtime_ns,\n entry.st_ino,\n entry.st_dev,\n entry.st_nlink,\n stat.S_IMODE(entry.st_mode),\n entry.st_ctime_ns,\n )\n return inventory\n\n\ndef _comparable(record: tuple) -> tuple:\n # Windows ctime is creation time, so it cannot signal an in-place mutation there.\n return record if os.name != \"nt\" else record[:-1]\n\n\ndef diff_ignored_state(before: dict[str, tuple], after: dict[str, tuple], sample_limit: int = 20) -> dict:\n changed: list[str] = []\n uninspectable = 0\n for rel in before.keys() & after.keys():\n old, new = before[rel], after[rel]\n if old[0] == \"uninspectable\" or new[0] == \"uninspectable\":\n uninspectable += 1\n elif _comparable(old) != _comparable(new):\n changed.append(rel)\n removed = sorted(before.keys() - after.keys())\n created = sorted(after.keys() - before.keys())\n changed.sort()\n return {\n \"before\": len(before),\n \"after\": len(after),\n \"changed\": len(changed),\n \"removed\": len(removed),\n \"created\": len(created),\n \"uninspectable\": uninspectable,\n \"sample\": {\n \"changed\": changed[:sample_limit],\n \"removed\": removed[:sample_limit],\n \"created\": created[:sample_limit],\n },\n \"sample_limit\": sample_limit,\n \"restored\": False,\n }\n","content_type":"text/x-python; charset=utf-8","language":"python","size":3059,"content_sha256":"9ce83a16ebc06af61fee4b22334d4384f4387035669df7d0e4afbf9ab8f296e4"},{"filename":"scripts/unit_workspace_integration.py","content":"\"\"\"Canonical integration, locking, wave sequencing, and exact restoration.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nimport re\nimport secrets\nimport shutil\nfrom pathlib import Path\n\nfrom unit_workspace_state import *\nfrom unit_workspace_jobs import find_attempt, parse_diff_paths, scope_expansion_pending\n\n\ndef integration_lock_path(doc: dict) -> str:\n ident = doc[\"repository\"][\"identity_digest\"] + \"\\0\" + doc[\"branch\"][\"ref\"]\n # Anchor to the root this run actually lives under (run_dir searches both\n # candidate roots), never the current invocation's preferred creation root:\n # a fallback-root run must validate and release the lock it recorded.\n run_root = os.path.dirname(run_dir(doc[\"run_id\"]))\n return os.path.join(run_root, \".locks\", f\"integration-{digest_bytes(ident.encode())}.json\")\n\n\ndef read_integration_lock(path: str) -> dict:\n return read_private_json(path)\n\n\ndef validated_lock_nonce(doc: dict, unit_id: str, lock: dict) -> str:\n expected = {\n \"run_id\": doc[\"run_id\"],\n \"unit_id\": unit_id,\n \"repository\": doc[\"repository\"][\"identity_digest\"],\n \"branch_ref\": doc[\"branch\"][\"ref\"],\n }\n if any(lock.get(k) != v for k, v in expected.items()):\n raise Operational(\"BLOCKED\", \"integration lock identity mismatch\")\n nonce = lock.get(\"nonce\")\n if not isinstance(nonce, str) or not re.fullmatch(r\"[0-9a-f]{48}\", nonce):\n raise TrustFailure(\"integration lock nonce is malformed\")\n return nonce\n\n\ndef validate_lock(doc: dict, unit_id: str, token: str) -> tuple[str, dict]:\n path = integration_lock_path(doc)\n try:\n lock = read_integration_lock(path)\n except TrustFailure as exc:\n if not os.path.lexists(path):\n raise Operational(\"BLOCKED\", \"integration lock is missing\") from exc\n raise\n nonce = validated_lock_nonce(doc, unit_id, lock)\n if nonce != token:\n raise Operational(\"BLOCKED\", \"integration lock token or identity mismatch\")\n return path, lock\n\n\ndef cmd_integration_acquire(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n plan_verification = bool(getattr(args, \"plan_verification\", False))\n recover_only = bool(getattr(args, \"recover_only\", False))\n allowed_states = INTEGRATABLE_STATES | {\"preserved\", \"committed\", \"cleaned\"}\n if plan_verification or (recover_only and unit and unit.get(\"state\") == \"native-completed\"):\n allowed_states.add(\"native-completed\")\n if not unit or unit[\"state\"] not in allowed_states:\n raise Operational(\"REFUSED\", \"unit is not ready for integration\")\n if not plan_verification and unit[\"state\"] != \"native-completed\":\n validate_wave_order(doc, unit)\n path = integration_lock_path(doc)\n existing = doc.get(\"integration_lock\")\n if existing:\n if not args.resume:\n raise Operational(\"REFUSED\", \"integration claim already exists; pass --resume to recover the same claim\")\n if existing.get(\"phase\", \"held\") != \"held\":\n raise Operational(\"REFUSED\", \"integration claim is releasing; resume or retry release before acquisition\")\n validate_lock(doc, args.unit_id, existing[\"nonce\"])\n return \"ACQUIRED\", {\"lock_token\": existing[\"nonce\"], \"resumed\": True, \"path\": path}\n nonce = secrets.token_hex(24)\n resumed = False\n if recover_only:\n lock = read_integration_lock(path)\n nonce = validated_lock_nonce(doc, args.unit_id, lock)\n resumed = True\n else:\n payload = {\"run_id\": args.run_id, \"unit_id\": args.unit_id, \"nonce\": nonce, \"repository\": doc[\"repository\"][\"identity_digest\"], \"branch_ref\": doc[\"branch\"][\"ref\"], \"created_at\": now_iso()}\n try:\n create_private(path, (json.dumps(payload, sort_keys=True) + \"\\n\").encode())\n test_fault(\"integration-lock-after-create\")\n except Operational as exc:\n if exc.word == \"INTERRUPTED\":\n raise\n lock = read_integration_lock(path)\n if lock.get(\"run_id\") == args.run_id and lock.get(\"unit_id\") == args.unit_id:\n if not args.resume:\n raise Operational(\"REFUSED\", \"integration lock file already exists; pass --resume to recover its claim\")\n nonce = validated_lock_nonce(doc, args.unit_id, lock)\n resumed = True\n else:\n raise Operational(\"BLOCKED\", \"another run/unit owns canonical integration\", {\"owner_run\": lock.get(\"run_id\"), \"owner_unit\": lock.get(\"unit_id\")})\n with locked_manifest(args.run_id, write=True) as doc:\n doc[\"integration_lock\"] = {\"unit_id\": args.unit_id, \"nonce\": nonce, \"path\": path, \"phase\": \"held\"}\n event(doc, \"integration-lock-acquired\", args.unit_id, {\"resumed\": resumed})\n return \"ACQUIRED\", {\"lock_token\": nonce, \"resumed\": resumed, \"path\": path}\n\n\ndef semantic_snapshot(repo: str) -> dict:\n head = git_text(repo, \"rev-parse\", \"HEAD\")\n head_tree = git_text(repo, \"rev-parse\", \"HEAD^{tree}\")\n index_tree = git_text(repo, \"write-tree\")\n raw = git(repo, \"status\", \"--porcelain=v2\", \"-z\", \"--untracked-files=all\")\n worktree_index = git(repo, \"diff\", \"--name-only\", \"-z\")\n return {\n \"head\": head,\n \"branch_ref\": git_text(repo, \"symbolic-ref\", \"-q\", \"HEAD\", check=False),\n \"head_tree\": head_tree,\n \"index_tree\": index_tree,\n \"status_sha256\": digest_bytes(raw),\n \"status_empty\": not bool(raw),\n \"worktree_index_empty\": not bool(worktree_index),\n }\n\n\ndef expected_apply_snapshot(repo: str, pre_head: str, unit: dict) -> dict:\n transport = unit[\"transport\"]\n if pre_head == transport[\"base\"]:\n tree = transport[\"tree\"]\n else:\n # Compute the same semantic three-way result as applying the\n # base-parented transport commit, without touching the canonical index.\n merged = git_text(repo, \"merge-tree\", \"--write-tree\", pre_head, transport[\"commit\"])\n tree = merged.splitlines()[0] if merged else \"\"\n if not tree:\n raise Operational(\"BLOCKED\", \"could not derive expected canonical apply tree\")\n raw = git(repo, \"diff-tree\", \"-r\", \"-M\", \"--name-status\", \"-z\", pre_head, tree)\n return {\"index_tree\": tree, \"changed_paths\": parse_diff_paths(raw)}\n\n\ndef matches_expected_apply(repo: str, unit: dict, snap: dict | None = None) -> bool:\n snap = snap or semantic_snapshot(repo)\n pre = unit.get(\"integration\", {}).get(\"pre_fold\")\n expected = unit.get(\"integration\", {}).get(\"expected_apply\")\n if not pre or not expected:\n return False\n return (\n snap[\"head\"] == pre[\"head\"]\n and snap[\"index_tree\"] == expected[\"index_tree\"]\n and snap[\"worktree_index_empty\"]\n and status_paths(repo) == set(expected[\"changed_paths\"])\n )\n\n\ndef wave_members(doc: dict, unit: dict) -> list[dict]:\n wave = unit.get(\"wave\", {})\n wave_id = wave.get(\"id\")\n if not wave_id:\n return []\n base = wave.get(\"base\")\n members = [\n candidate for candidate in doc.get(\"units\", {}).values()\n if candidate.get(\"wave\", {}).get(\"id\") == wave_id\n ]\n positions = [candidate.get(\"wave\", {}).get(\"position\") for candidate in members]\n if any(candidate.get(\"wave\", {}).get(\"base\") != base for candidate in members):\n raise Operational(\"BLOCKED\", \"wave members do not share one recorded base\")\n if len(set(positions)) != len(positions):\n raise Operational(\"BLOCKED\", \"wave positions are not unique\")\n return sorted(members, key=lambda candidate: candidate[\"wave\"][\"position\"])\n\n\ndef validate_wave_order(doc: dict, unit: dict) -> None:\n members = wave_members(doc, unit)\n earlier_unresolved = [\n candidate[\"unit_id\"] for candidate in members\n if candidate[\"wave\"][\"position\"] \u003c unit[\"wave\"][\"position\"]\n and not (\n candidate.get(\"state\") in {\"committed\", \"preserved\", \"cleaned\"}\n or (\n candidate.get(\"state\") == \"native-completed\"\n and unit_accepted_commit(candidate) is not None\n )\n )\n ]\n if earlier_unresolved:\n raise Operational(\n \"BLOCKED\",\n \"earlier wave units must be committed or preserved before this fold-in\",\n {\"reason\": \"earlier wave unit not resolved\", \"units\": earlier_unresolved},\n )\n\n\ndef wave_member_changed_paths(candidate: dict) -> set[str] | None:\n transport = candidate.get(\"transport\", {})\n if transport.get(\"commit\"):\n paths = transport.get(\"changed_paths\")\n elif candidate.get(\"state\") == \"native-completed\":\n if unit_accepted_commit(candidate) is None:\n raise TrustFailure(\"native wave completion evidence is malformed\")\n completion = find_attempt(candidate).get(\"fallback\", {}).get(\"completed\")\n paths = completion.get(\"changed_paths\") if isinstance(completion, dict) else None\n else:\n return None\n if not isinstance(paths, list) or any(not isinstance(path, str) for path in paths):\n raise TrustFailure(\"wave member changed paths are malformed\")\n return set(paths)\n\n\ndef validate_wave_collisions(\n doc: dict,\n unit: dict,\n overrides: dict[str, set[str]] | None = None,\n require_complete: bool = True,\n) -> None:\n members = wave_members(doc, unit)\n if not members:\n return\n overrides = overrides or {}\n changed_by_unit: dict[str, set[str]] = {}\n unterminated: list[str] = []\n for candidate in members:\n unit_id = candidate[\"unit_id\"]\n paths = overrides.get(unit_id)\n if paths is None:\n paths = wave_member_changed_paths(candidate)\n if paths is None:\n unterminated.append(unit_id)\n else:\n changed_by_unit[unit_id] = paths\n if unterminated:\n if require_complete:\n raise Operational(\n \"BLOCKED\",\n \"every wave worker must terminalize before the first fold-in\",\n {\"reason\": \"wave not fully terminalized\", \"units\": unterminated},\n )\n collisions: dict[str, list[str]] = {}\n for index, left in enumerate(members):\n for right in members[index + 1:]:\n left_paths = changed_by_unit.get(left[\"unit_id\"])\n right_paths = changed_by_unit.get(right[\"unit_id\"])\n if left_paths is None or right_paths is None:\n continue\n overlap = sorted(left_paths & right_paths)\n if overlap:\n collisions[f'{left[\"unit_id\"]}:{right[\"unit_id\"]}'] = overlap\n if collisions:\n raise Operational(\n \"BLOCKED\",\n \"wave transports have a changed-path collision\",\n {\"reason\": \"changed-path collision\", \"collisions\": collisions},\n )\n\n\ndef validate_wave_ready(doc: dict, unit: dict) -> None:\n members = wave_members(doc, unit)\n if not members:\n return\n validate_wave_order(doc, unit)\n validate_wave_collisions(doc, unit)\n\n\ndef validate_wave_advancement(members: list[dict], unit: dict, parent: str, canonical: str) -> list[str]:\n position = unit[\"wave\"][\"position\"]\n targets = [candidate for candidate in members if candidate[\"wave\"][\"position\"] > position]\n for candidate in targets:\n allowed = candidate[\"wave\"].get(\"allowed_heads\", [])\n if canonical in allowed:\n continue\n if not allowed or allowed[-1] != parent:\n raise Operational(\"BLOCKED\", \"wave advancement is not the exact recorded canonical chain\")\n return [candidate[\"unit_id\"] for candidate in targets]\n\n\ndef advance_wave_allowed_heads(members: list[dict], position: int, canonical: str) -> list[str]:\n advanced: list[str] = []\n for candidate in members:\n if candidate[\"wave\"][\"position\"] \u003c= position:\n continue\n allowed = candidate[\"wave\"].setdefault(\"allowed_heads\", [])\n if canonical not in allowed:\n allowed.append(canonical)\n advanced.append(candidate[\"unit_id\"])\n return advanced\n\n\ndef validate_dependencies_ready(doc: dict, unit: dict) -> None:\n missing: list[str] = []\n unaccepted: list[str] = []\n for dependency_id in unit.get(\"dependencies\", []):\n dependency = doc.get(\"units\", {}).get(dependency_id)\n if dependency is None:\n missing.append(dependency_id)\n continue\n if unit_accepted_commit(dependency) is None:\n unaccepted.append(dependency_id)\n if missing or unaccepted:\n raise Operational(\n \"BLOCKED\",\n \"unit dependencies must have controller-accepted canonical commits before preflight\",\n {\n \"unit_id\": unit[\"unit_id\"],\n \"missing_dependencies\": missing,\n \"unaccepted_dependencies\": unaccepted,\n },\n )\n\n\ndef dependency_advanced_head(doc: dict, unit: dict, head: str) -> bool:\n dependency_commits = [\n unit_accepted_commit(doc[\"units\"][dependency_id])\n for dependency_id in unit.get(\"dependencies\", [])\n ]\n if any(commit is None for commit in dependency_commits):\n return False\n accepted_heads = {\n commit\n for unit_id, candidate in doc.get(\"units\", {}).items()\n if unit_id != unit.get(\"unit_id\")\n if (commit := unit_accepted_commit(candidate)) is not None\n }\n if head not in accepted_heads:\n return False\n allowed_heads = unit.get(\"wave\", {}).get(\"allowed_heads\", [])\n required_ancestors = {\n *accepted_heads,\n *dependency_commits,\n *allowed_heads,\n unit.get(\"workspace\", {}).get(\"base\"),\n }\n required_ancestors.discard(None)\n repo = doc[\"repository\"][\"toplevel\"]\n return all(\n git_text(repo, \"merge-base\", commit, head, check=False) == commit\n for commit in required_ancestors\n )\n\n\ndef validate_preflight_ancestry(doc: dict, unit: dict, heads: set[str]) -> None:\n required = {\n commit\n for unit_id, candidate in doc.get(\"units\", {}).items()\n if unit_id != unit[\"unit_id\"]\n and (commit := unit_accepted_commit(candidate)) is not None\n }\n wave = unit.get(\"wave\", {})\n required.update(head for head in wave.get(\"allowed_heads\", []) if head != wave.get(\"base\"))\n\n repo = doc[\"repository\"][\"toplevel\"]\n missing = {\n head: sorted(\n commit for commit in required\n if git_text(repo, \"merge-base\", commit, head, check=False) != commit\n )\n for head in sorted(heads)\n }\n missing = {head: commits for head, commits in missing.items() if commits}\n if missing:\n raise Operational(\n \"BLOCKED\",\n \"preflight HEAD omits controller-accepted prerequisite commits\",\n {\"unit_id\": unit[\"unit_id\"], \"missing_ancestry\": missing},\n )\n\n\ndef cmd_preflight(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n info = validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit or unit[\"state\"] not in {\"integration-pending\", \"preserved\"}:\n raise Operational(\"REFUSED\", \"unit is not integration-pending\")\n validate_lock(doc, args.unit_id, args.lock_token)\n validate_dependencies_ready(doc, unit)\n if scope_expansion_pending(unit):\n raise Operational(\n \"BLOCKED\",\n \"worker requested scope expansion; inspect the retained result and transport, then resolve or re-dispatch explicitly\",\n {\n \"unit_id\": args.unit_id,\n \"terminal_status\": \"scope_expansion\",\n \"transport\": unit[\"transport\"],\n \"recovery_path\": unit[\"recovery_path\"],\n },\n )\n validate_wave_ready(doc, unit)\n allowed = set(unit[\"wave\"].get(\"allowed_heads\", []))\n requested: set[str] = set()\n if args.allowed_head:\n requested = {git_text(info[\"toplevel\"], \"rev-parse\", f\"{h}^{{commit}}\") for h in args.allowed_head}\n if any(head not in allowed and not dependency_advanced_head(doc, unit, head) for head in requested):\n raise Operational(\"BLOCKED\", \"unrecorded same-wave HEAD allowance\")\n if info[\"head\"] not in allowed and not dependency_advanced_head(doc, unit, info[\"head\"]):\n raise Operational(\"BLOCKED\", \"canonical HEAD advanced outside the recorded wave\")\n validate_preflight_ancestry(doc, unit, requested | {info[\"head\"]})\n snap = semantic_snapshot(info[\"toplevel\"])\n if not snap[\"status_empty\"] or snap[\"index_tree\"] != snap[\"head_tree\"]:\n raise Operational(\"BLOCKED\", \"canonical checkout is not clean at preflight\")\n expected = expected_apply_snapshot(info[\"toplevel\"], snap[\"head\"], unit)\n intent_revision = doc[\"revision\"] + 1\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][args.unit_id]\n unit[\"state\"] = \"integration-pending\"\n unit[\"integration\"][\"intent_revision\"] = intent_revision\n unit[\"integration\"][\"pre_fold\"] = snap\n unit[\"integration\"][\"expected_apply\"] = expected\n event(doc, \"canonical-apply-intent\", args.unit_id, {\"transport\": unit[\"transport\"][\"commit\"], \"pre_head\": snap[\"head\"]})\n return \"PREFLIGHT_OK\", {\"unit_id\": args.unit_id, \"pre_fold\": snap, \"transport\": unit[\"transport\"]}\n\n\ndef cmd_mark_applied(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n validate_lock(doc, args.unit_id, args.lock_token)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit or unit[\"state\"] not in {\"integration-pending\", \"integrated\"} or not unit[\"integration\"].get(\"pre_fold\"):\n raise Operational(\"REFUSED\", \"no recorded preflight intent\")\n repo = validate_repo(doc)[\"toplevel\"]\n snap = semantic_snapshot(repo)\n if snap[\"head\"] != unit[\"integration\"][\"pre_fold\"][\"head\"]:\n raise Operational(\"BLOCKED\", \"canonical HEAD moved before apply was recorded\")\n if not matches_expected_apply(repo, unit, snap):\n raise Operational(\"BLOCKED\", \"canonical state does not match the expected transport application\")\n test_fault(\"after-apply-observed\")\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][args.unit_id]\n unit[\"state\"] = \"integrated\"\n unit[\"integration\"][\"applied\"] = {\"at\": now_iso(), \"post_index_tree\": snap[\"index_tree\"], \"status_sha256\": snap[\"status_sha256\"]}\n event(doc, \"transport-applied\", args.unit_id, {\"post_index_tree\": snap[\"index_tree\"]})\n return \"APPLIED\", {\"unit_id\": args.unit_id, \"post_index_tree\": snap[\"index_tree\"]}\n\n\ndef cmd_mark_verified(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id, write=True) as doc:\n validate_lock(doc, args.unit_id, args.lock_token)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit or unit[\"state\"] not in {\"integrated\", \"verified\"}:\n raise Operational(\"REFUSED\", \"unit is not applied\")\n repo = validate_repo(doc)[\"toplevel\"]\n if not matches_expected_apply(repo, unit):\n raise Operational(\n \"BLOCKED\",\n \"canonical state changed after the recorded transport application\",\n {\n \"unit_id\": args.unit_id,\n \"reason\": \"canonical state no longer matches the expected transport application\",\n },\n )\n evidence = {\"at\": now_iso(), \"digest\": args.evidence_digest, \"summary\": args.summary}\n ignored_state = getattr(args, \"ignored_state\", None)\n if isinstance(ignored_state, str):\n ignored_state = parse_json_arg(ignored_state, \"ignored-state\")\n if ignored_state is not None:\n evidence[\"ignored_state\"] = ignored_state\n unit[\"integration\"][\"verification\"] = evidence\n unit[\"state\"] = \"verified\"\n event(doc, \"canonical-verification-passed\", args.unit_id, {\"digest\": args.evidence_digest})\n return \"VERIFIED\", {\"unit_id\": args.unit_id, \"verification\": evidence}\n\n\ndef reconcile_commit(doc: dict, unit: dict) -> dict | None:\n repo = doc[\"repository\"][\"toplevel\"]\n head = git_text(repo, \"rev-parse\", \"HEAD\")\n parents = git_text(repo, \"rev-list\", \"--parents\", \"-n\", \"1\", head).split()\n expected_parent = unit[\"integration\"][\"pre_fold\"][\"head\"]\n expected_tree = unit[\"integration\"][\"applied\"][\"post_index_tree\"]\n actual_tree = git_text(repo, \"rev-parse\", \"HEAD^{tree}\")\n if parents == [head, expected_parent] and actual_tree == expected_tree and not status_paths(repo):\n return {\"commit\": head, \"parent\": expected_parent, \"tree\": actual_tree, \"at\": now_iso()}\n return None\n\n\ndef cmd_mark_committed(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n validate_lock(doc, args.unit_id, args.lock_token)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit or unit[\"state\"] not in {\"verified\", \"committed\"}:\n raise Operational(\"REFUSED\", \"unit has not passed canonical verification\")\n commit = reconcile_commit(doc, unit)\n if not commit:\n raise Operational(\"BLOCKED\", \"canonical commit parent/tree/cleanliness do not match recorded integration\")\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][args.unit_id]\n unit[\"integration\"][\"canonical_commit\"] = commit\n unit[\"state\"] = \"committed\"\n event(doc, \"canonical-commit-confirmed\", args.unit_id, {\"commit\": commit[\"commit\"]})\n return \"COMMITTED\", {\"unit_id\": args.unit_id, \"canonical_commit\": commit}\n\n\ndef cmd_wave_advance(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n info = validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit or unit.get(\"state\") != \"committed\":\n raise Operational(\"REFUSED\", \"only a committed wave unit can advance its siblings\")\n validate_lock(doc, args.unit_id, args.lock_token)\n members = wave_members(doc, unit)\n if not members:\n raise Operational(\"REFUSED\", \"unit does not belong to a parallel wave\")\n validate_wave_ready(doc, unit)\n canonical = git_text(info[\"toplevel\"], \"rev-parse\", f\"{args.canonical_commit}^{{commit}}\")\n recorded = unit.get(\"integration\", {}).get(\"canonical_commit\", {})\n if recorded.get(\"commit\") != canonical or info[\"head\"] != canonical:\n raise Operational(\"BLOCKED\", \"canonical wave commit does not match manifest and HEAD\")\n parent = unit.get(\"integration\", {}).get(\"pre_fold\", {}).get(\"head\")\n if recorded.get(\"parent\") != parent:\n raise Operational(\"BLOCKED\", \"canonical wave commit parent is not the recorded pre-fold HEAD\")\n validate_wave_advancement(members, unit, parent, canonical)\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][args.unit_id]\n position = unit[\"wave\"][\"position\"]\n advanced = advance_wave_allowed_heads(wave_members(doc, unit), position, canonical)\n event(doc, \"wave-advanced\", args.unit_id, {\"canonical_commit\": canonical, \"eligible_siblings\": advanced})\n return \"WAVE_ADVANCED\", {\"unit_id\": args.unit_id, \"canonical_commit\": canonical, \"eligible_siblings\": advanced}\n\n\ndef path_in_tree(repo: str, treeish: str, rel: str) -> bool:\n out = git(repo, \"ls-tree\", \"-z\", \"--full-tree\", treeish, \"--\", rel)\n return bool(out)\n\n\ndef remove_introduced_paths(repo: str, unit: dict) -> None:\n pre = unit[\"integration\"][\"pre_fold\"][\"head\"]\n base = unit[\"transport\"][\"base\"]\n commit = unit[\"transport\"][\"commit\"]\n raw = git(repo, \"diff-tree\", \"-r\", \"-M\", \"--name-status\", \"-z\", base, commit)\n for rel in parse_diff_paths(raw):\n if path_in_tree(repo, pre, rel):\n continue\n target = os.path.abspath(os.path.join(repo, rel))\n if os.path.commonpath([repo, target]) != repo:\n raise Operational(\"BLOCKED\", \"transport path escaped canonical repository\")\n if os.path.islink(target) or os.path.isfile(target):\n os.unlink(target)\n elif os.path.isdir(target):\n shutil.rmtree(target)\n parent = os.path.dirname(target)\n while parent != repo and os.path.commonpath([repo, parent]) == repo:\n try:\n os.rmdir(parent)\n except OSError:\n break\n parent = os.path.dirname(parent)\n\n\ndef restore(run_id: str, unit_id: str, lock_token: str) -> bool:\n with locked_manifest(run_id) as doc:\n validate_lock(doc, unit_id, lock_token)\n unit = doc[\"units\"].get(unit_id)\n if not unit or not unit[\"integration\"].get(\"pre_fold\"):\n raise Operational(\"REFUSED\", \"unit has no pre-fold snapshot\")\n repo = doc[\"repository\"][\"toplevel\"]\n pre = dict(unit[\"integration\"][\"pre_fold\"])\n git_dir = git_text(repo, \"rev-parse\", \"--path-format=absolute\", \"--absolute-git-dir\")\n cherry_pick_head = os.path.join(git_dir, \"CHERRY_PICK_HEAD\")\n expected_conflict = False\n if os.path.isfile(cherry_pick_head) and git_text(repo, \"rev-parse\", \"HEAD\") == pre[\"head\"]:\n expected_conflict = Path(cherry_pick_head).read_text().strip() == unit[\"transport\"][\"commit\"]\n current = None if expected_conflict else semantic_snapshot(repo)\n already_exact = current == pre if current else False\n expected_apply = matches_expected_apply(repo, unit, current) if current else False\n partial_reset = bool(current) and (\n unit.get(\"state\") == \"restoring\"\n and current[\"head\"] == pre[\"head\"]\n and current[\"index_tree\"] == pre[\"index_tree\"]\n and current[\"worktree_index_empty\"]\n and status_paths(repo).issubset(set(unit[\"integration\"][\"expected_apply\"][\"changed_paths\"]))\n )\n if not (already_exact or expected_apply or partial_reset or expected_conflict):\n raise Operational(\"BLOCKED\", \"canonical state is not a proven in-flight transport state; refusing destructive restoration\")\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"][unit_id]\n unit[\"state\"] = \"restoring\"\n event(doc, \"restore-intent\", unit_id)\n if not already_exact:\n git(repo, \"cherry-pick\", \"--abort\", check=False)\n git(repo, \"reset\", \"--hard\", pre[\"head\"])\n test_fault(\"restore-after-reset\")\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"][unit_id]\n remove_introduced_paths(repo, unit)\n test_fault(\"restore-after-path-removal\")\n actual = semantic_snapshot(repo)\n exact = actual == pre\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"][unit_id]\n unit[\"integration\"][\"restore\"] = {\n \"at\": now_iso(),\n \"exact\": exact,\n \"already_exact\": already_exact,\n \"snapshot\": actual,\n }\n if exact:\n unit[\"state\"] = \"preserved\"\n event(doc, \"canonical-restored\", unit_id)\n else:\n blocker = {\"at\": now_iso(), \"unit_id\": unit_id, \"reason\": \"exact pre-fold restoration could not be proven\"}\n doc[\"blockers\"].append(blocker)\n event(doc, \"restore-blocked\", unit_id)\n return exact\n\n\ndef cmd_restore(args) -> tuple[str, dict]:\n exact = restore(args.run_id, args.unit_id, args.lock_token)\n if not exact:\n raise Operational(\"BLOCKED\", \"exact pre-fold restoration could not be proven\")\n return \"PRESERVED\", {\"unit_id\": args.unit_id, \"recovery_path\": os.path.join(run_dir(args.run_id), \"units\", args.unit_id)}\n\n\n\n\ndef release_lock_is_owned(doc: dict, unit_id: str, lock_token: str, lock: dict) -> bool:\n expected = {\n \"run_id\": doc[\"run_id\"],\n \"unit_id\": unit_id,\n \"repository\": doc[\"repository\"][\"identity_digest\"],\n \"branch_ref\": doc[\"branch\"][\"ref\"],\n }\n if any(lock.get(key) != value for key, value in expected.items()):\n return False\n nonce = lock.get(\"nonce\")\n if not isinstance(nonce, str) or not re.fullmatch(r\"[0-9a-f]{48}\", nonce):\n return False\n return nonce == lock_token\n\n\ndef integration_release(run_id: str, unit_id: str, lock_token: str) -> None:\n with locked_manifest(run_id, write=True) as doc:\n held = doc.get(\"integration_lock\")\n if not held or held.get(\"unit_id\") != unit_id or held.get(\"nonce\") != lock_token:\n raise Operational(\"REFUSED\", \"integration lock token or identity mismatch\")\n unit = doc[\"units\"].get(unit_id)\n pre_apply = bool(\n unit\n and unit.get(\"state\") == \"integration-pending\"\n and not unit.get(\"integration\", {}).get(\"pre_fold\")\n )\n if not unit or (unit[\"state\"] not in {\"committed\", \"preserved\", \"cleaned\", \"native-completed\"} and not pre_apply):\n raise Operational(\"REFUSED\", \"integration lock releases only before preflight or after accepted completion\")\n path = held.get(\"path\")\n if path != integration_lock_path(doc):\n raise Operational(\"BLOCKED\", \"manifest integration lock path changed\")\n phase = held.get(\"phase\", \"held\")\n if phase == \"held\":\n validate_lock(doc, unit_id, lock_token)\n held[\"phase\"] = \"releasing\"\n held[\"release_started_at\"] = now_iso()\n event(doc, \"integration-lock-release-intent\", unit_id)\n elif phase != \"releasing\":\n raise Operational(\"BLOCKED\", \"manifest integration claim has an unknown phase\")\n with locked_manifest(run_id, write=True) as doc:\n held = doc.get(\"integration_lock\")\n if not held or held.get(\"unit_id\") != unit_id or held.get(\"nonce\") != lock_token or held.get(\"phase\") != \"releasing\":\n raise Operational(\"BLOCKED\", \"manifest integration claim changed\")\n if held.get(\"path\") != path or path != integration_lock_path(doc):\n raise Operational(\"BLOCKED\", \"manifest integration lock path changed\")\n current = None\n try:\n current = read_integration_lock(path)\n except TrustFailure:\n if os.path.lexists(path):\n raise\n if current is not None and release_lock_is_owned(doc, unit_id, lock_token, current):\n try:\n os.unlink(path)\n except FileNotFoundError:\n pass\n test_fault(\"integration-release-after-unlink\")\n if os.path.lexists(path):\n current = read_integration_lock(path)\n if release_lock_is_owned(doc, unit_id, lock_token, current):\n raise Operational(\"BLOCKED\", \"integration lock file remained after release\")\n doc[\"integration_lock\"] = None\n event(doc, \"integration-lock-released\", unit_id)\n\n\ndef cmd_integration_release(args) -> tuple[str, dict]:\n integration_release(args.run_id, args.unit_id, args.lock_token)\n return \"RELEASED\", {\"unit_id\": args.unit_id}\n","content_type":"text/x-python; charset=utf-8","language":"python","size":31248,"content_sha256":"b69040ccbee60fb8c7b1fc80b9fde638a14baac12683a6e52899a08600f5f88d"},{"filename":"scripts/unit_workspace_jobs.py","content":"\"\"\"Unit preparation, runner evidence, and complete-tree transport lifecycle.\"\"\"\n\nfrom __future__ import annotations\n\nimport base64\nimport json\nimport os\nimport re\nimport stat\n\nfrom unit_workspace_state import *\n\n\ndef _valid_retry_commit_id(value: object) -> bool:\n return isinstance(value, str) and re.fullmatch(r\"(?:[0-9a-f]{40}|[0-9a-f]{64})\", value) is not None\n\n\ndef _validate_retry_base(doc: dict, unit: dict, requested_base: str) -> None:\n wave = unit.get(\"wave\", {})\n original_base = wave.get(\"base\")\n allowed_heads = wave.get(\"allowed_heads\", [])\n if not _valid_retry_commit_id(original_base):\n raise TrustFailure(\"recorded retry base is malformed\")\n if not isinstance(allowed_heads, list) or any(not _valid_retry_commit_id(head) for head in allowed_heads):\n raise TrustFailure(\"recorded retry HEAD allowances are malformed\")\n\n accepted_heads = {\n commit\n for candidate in doc.get(\"units\", {}).values()\n if (commit := unit_accepted_commit(candidate)) is not None\n }\n latest_allowed = allowed_heads[-1] if allowed_heads else original_base\n if requested_base != original_base and requested_base not in accepted_heads:\n raise Operational(\n \"BLOCKED\",\n \"retry base is not a controller-accepted canonical head\",\n {\"requested_base\": requested_base, \"latest_allowed_head\": latest_allowed},\n )\n repo = doc[\"repository\"][\"toplevel\"]\n required = accepted_heads | {original_base, *allowed_heads}\n missing = sorted(\n commit for commit in required\n if git_text(repo, \"merge-base\", commit, requested_base, check=False) != commit\n )\n if missing:\n raise Operational(\n \"BLOCKED\",\n \"retry base omits controller-accepted canonical history\",\n {\n \"requested_base\": requested_base,\n \"latest_allowed_head\": latest_allowed,\n \"missing_ancestry\": missing,\n },\n )\n\n\ndef _record_retry_base(doc: dict, unit: dict, requested_base: str) -> None:\n wave = unit[\"wave\"]\n position = wave.get(\"position\")\n if not isinstance(position, int):\n raise TrustFailure(\"recorded retry wave position is malformed\")\n targets = [unit]\n if wave.get(\"id\"):\n for candidate in doc.get(\"units\", {}).values():\n candidate_wave = candidate.get(\"wave\", {})\n if candidate is unit or candidate_wave.get(\"id\") != wave[\"id\"]:\n continue\n candidate_position = candidate_wave.get(\"position\")\n if not isinstance(candidate_position, int):\n raise TrustFailure(\"recorded wave position is malformed\")\n if candidate_position > position:\n targets.append(candidate)\n for candidate in targets:\n candidate_wave = candidate.get(\"wave\", {})\n if candidate_wave.get(\"base\") != wave.get(\"base\"):\n raise Operational(\"BLOCKED\", \"wave members do not share one recorded base\")\n allowed_heads = candidate_wave.setdefault(\"allowed_heads\", [])\n if not isinstance(allowed_heads, list) or any(not _valid_retry_commit_id(head) for head in allowed_heads):\n raise TrustFailure(\"recorded retry HEAD allowances are malformed\")\n if requested_base not in allowed_heads:\n allowed_heads.append(requested_base)\n\n\ndef cmd_prepare(args) -> tuple[str, dict]:\n uid = safe_id(args.unit_id, \"unit id\")\n attempt_id = safe_id(args.attempt_id, \"attempt id\")\n packet_bytes = read_external_packet(args.packet)\n packet_digest = digest_bytes(packet_bytes)\n with locked_manifest(args.run_id) as doc:\n info = validate_repo(doc)\n repo = info[\"toplevel\"]\n base = git_text(repo, \"rev-parse\", f\"{args.base}^{{commit}}\")\n if info[\"head\"] != base:\n raise Operational(\"BLOCKED\", \"canonical HEAD does not equal requested unit base\")\n if status_paths(repo):\n raise Operational(\"BLOCKED\", \"canonical checkout is dirty; external workspace unavailable\")\n existing = doc[\"units\"].get(uid)\n unit_root = os.path.join(run_dir(args.run_id), \"units\", uid)\n workspace = os.path.join(unit_root, \"workspace\")\n packet_path = os.path.join(unit_root, \"packet.md\")\n authorization_path = os.path.join(unit_root, \"authorization.json\")\n authorization = attempt_authorization(doc, args.activity_posture, uid, attempt_id, packet_digest)\n authorization_bytes = (json.dumps(authorization, sort_keys=True, separators=(\",\", \":\")) + \"\\n\").encode()\n authorization_digest = digest_bytes(authorization_bytes)\n contract_wave_base = existing.get(\"wave\", {}).get(\"base\") if existing else base\n expected_contract = {\n \"dependencies\": list(args.dependency),\n \"wave\": {\"id\": args.wave_id, \"base\": contract_wave_base, \"position\": args.wave_position},\n \"packet_digest\": packet_digest,\n \"attempt_id\": attempt_id,\n \"authorization\": authorization,\n \"authorization_path\": authorization_path,\n \"authorization_digest\": authorization_digest,\n }\n retrying = False\n if existing:\n matching_attempts = [attempt for attempt in existing.get(\"attempts\", []) if attempt.get(\"attempt_id\") == attempt_id]\n if not matching_attempts:\n cleanup = existing.get(\"cleanup\")\n if (\n existing.get(\"state\") != \"cleaned\"\n or not isinstance(cleanup, dict)\n or cleanup.get(\"abandoned\") is not True\n or cleanup.get(\"artifact_cleanup\", {}).get(\"complete\") is not True\n ):\n raise Operational(\"REFUSED\", \"a fresh attempt requires an exactly abandoned and fully cleaned prior attempt\")\n if doc.get(\"integration_lock\"):\n raise Operational(\"REFUSED\", \"release the prior integration lock before preparing a retry\")\n if existing.get(\"dependencies\") != list(args.dependency):\n raise Operational(\"BLOCKED\", \"retry dependencies differ from the recorded unit\")\n prior_wave = existing.get(\"wave\", {})\n if {\n \"id\": prior_wave.get(\"id\"),\n \"position\": prior_wave.get(\"position\"),\n } != {\"id\": args.wave_id, \"position\": args.wave_position}:\n raise Operational(\"BLOCKED\", \"retry wave identity/position differs from the recorded unit\")\n _validate_retry_base(doc, existing, base)\n retrying = True\n else:\n attempt = find_attempt(existing, attempt_id)\n if existing and not retrying and (\n existing.get(\"workspace\", {}).get(\"path\") != workspace\n or existing.get(\"workspace\", {}).get(\"base\") != base\n ):\n raise Operational(\"BLOCKED\", \"duplicate unit id has a different workspace contract\")\n if existing and not retrying:\n if existing.get(\"state\") == \"cleaned\" or existing.get(\"cleanup\"):\n raise Operational(\n \"REFUSED\",\n \"cleaned unit cannot reuse a recorded attempt id; supply a fresh --attempt-id after exact abandonment cleanup and lock release\",\n )\n observed_contract = {\n \"dependencies\": existing.get(\"dependencies\"),\n \"wave\": {key: existing.get(\"wave\", {}).get(key) for key in (\"id\", \"base\", \"position\")},\n \"packet_digest\": existing.get(\"packet_digest\"),\n \"attempt_id\": attempt.get(\"attempt_id\"),\n \"authorization\": attempt.get(\"authorization\"),\n \"authorization_path\": attempt.get(\"authorization_path\"),\n \"authorization_digest\": attempt.get(\"authorization_digest\"),\n }\n if observed_contract != expected_contract or existing.get(\"packet\", {}).get(\"path\") != packet_path:\n raise Operational(\"BLOCKED\", \"resumed prepare contract differs from the recorded unit\")\n if read_private(packet_path, MAX_PACKET_BYTES) != packet_bytes:\n raise Operational(\"BLOCKED\", \"controller-owned unit packet no longer matches supplied bytes\")\n if read_private(authorization_path, MAX_JSON_BYTES) != authorization_bytes:\n raise Operational(\"BLOCKED\", \"controller-owned authorization no longer matches the recorded attempt\")\n result_fd, _ = open_recorded_result_dir(existing)\n os.close(result_fd)\n if existing and not retrying and existing[\"workspace\"].get(\"registered\"):\n if existing.get(\"state\") == \"queued\":\n validate_pristine_unit_base(doc, existing)\n else:\n validate_workspace(doc, existing)\n return \"PREPARED\", {\n \"unit_id\": uid, \"attempt_id\": attempt_id,\n \"workspace\": workspace, \"result_dir\": os.path.join(unit_root, \"result\"),\n \"packet_path\": packet_path, \"packet_digest\": packet_digest,\n \"authorization_path\": authorization_path, \"authorization_digest\": authorization_digest,\n \"adapter\": attempt[\"adapter\"],\n \"base\": base, \"resumed\": True,\n }\n ensure_private_dir(unit_root)\n result_dir = os.path.join(unit_root, \"result\")\n ensure_private_dir(result_dir)\n result_dir_identity = private_result_dir_identity(result_dir)\n if os.path.lexists(packet_path):\n if read_private(packet_path, MAX_PACKET_BYTES) != packet_bytes:\n raise Operational(\"BLOCKED\", \"controller-owned packet path contains different bytes\")\n else:\n create_private(packet_path, packet_bytes)\n if os.path.lexists(authorization_path):\n if read_private(authorization_path, MAX_JSON_BYTES) != authorization_bytes:\n raise Operational(\"BLOCKED\", \"controller-owned authorization path contains different bytes\")\n else:\n create_private(authorization_path, authorization_bytes)\n attempt_record = {\n \"attempt_id\": attempt_id,\n \"job_id\": None,\n \"dispatch_authorization_receipt\": None,\n \"process_state\": \"never-started\",\n \"activity\": {\"posture\": args.activity_posture, \"latest_at\": None},\n \"fallback\": {\"eligible\": False, \"reason\": None, \"claimed\": None},\n \"authorization\": authorization,\n \"authorization_path\": authorization_path,\n \"authorization_digest\": authorization_digest,\n \"authorization_retained\": True,\n \"adapter\": os.path.realpath(os.path.join(os.path.dirname(__file__), \"cross-model-work.sh\")),\n \"terminal_receipt\": None,\n }\n if not existing:\n unit = {\n \"unit_id\": uid,\n \"state\": \"queued\",\n \"dependencies\": list(args.dependency),\n \"wave\": {\"id\": args.wave_id, \"base\": base, \"position\": args.wave_position, \"allowed_heads\": [base]},\n \"packet_digest\": packet_digest,\n \"packet\": {\"path\": packet_path, \"digest\": packet_digest, \"bytes\": len(packet_bytes), \"retained\": True},\n \"workspace\": {\"path\": workspace, \"base\": base, \"registered\": False},\n \"result_dir_identity\": result_dir_identity,\n \"attempts\": [attempt_record],\n \"transport\": {\"base\": None, \"tree\": None, \"commit\": None, \"ref\": None, \"digest\": None, \"changed_paths\": []},\n \"integration\": {\"intent_revision\": None, \"pre_fold\": None, \"expected_apply\": None, \"applied\": None, \"verification\": None, \"canonical_commit\": None, \"restore\": None},\n \"cleanup\": None,\n \"recovery_path\": unit_root,\n }\n with locked_manifest(args.run_id, write=True) as doc:\n if uid in doc[\"units\"]:\n raise Operational(\"BLOCKED\", \"unit was concurrently claimed\")\n doc[\"units\"][uid] = unit\n event(doc, \"worktree-add-intent\", uid, {\"path\": workspace, \"base\": base})\n elif retrying:\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"].get(uid)\n cleanup = unit.get(\"cleanup\") if unit else None\n if (\n not unit\n or unit.get(\"state\") != \"cleaned\"\n or not isinstance(cleanup, dict)\n or cleanup.get(\"abandoned\") is not True\n or cleanup.get(\"artifact_cleanup\", {}).get(\"complete\") is not True\n or doc.get(\"integration_lock\")\n ):\n raise Operational(\"BLOCKED\", \"unit retry eligibility changed while it was being prepared\")\n if any(attempt.get(\"attempt_id\") == attempt_id for attempt in unit.get(\"attempts\", [])):\n raise Operational(\"BLOCKED\", \"retry attempt id was concurrently claimed\")\n info = validate_repo(doc)\n if info[\"head\"] != base:\n raise Operational(\"BLOCKED\", \"canonical HEAD changed while retry was being prepared\")\n if unit.get(\"dependencies\") != list(args.dependency):\n raise Operational(\"BLOCKED\", \"retry dependencies differ from the recorded unit\")\n prior_wave = unit.get(\"wave\", {})\n if {\n \"id\": prior_wave.get(\"id\"),\n \"position\": prior_wave.get(\"position\"),\n } != {\"id\": args.wave_id, \"position\": args.wave_position}:\n raise Operational(\"BLOCKED\", \"retry wave identity/position differs from the recorded unit\")\n _validate_retry_base(doc, unit, base)\n previous = find_attempt(unit)\n previous[\"cleanup_receipt\"] = dict(cleanup)\n restore = unit.get(\"integration\", {}).get(\"restore\")\n if restore is not None:\n previous[\"restore_receipt\"] = json.loads(json.dumps(restore))\n unit[\"state\"] = \"queued\"\n unit[\"packet_digest\"] = packet_digest\n unit[\"packet\"] = {\"path\": packet_path, \"digest\": packet_digest, \"bytes\": len(packet_bytes), \"retained\": True}\n unit[\"workspace\"] = {\"path\": workspace, \"base\": base, \"registered\": False}\n unit[\"result_dir_identity\"] = result_dir_identity\n _record_retry_base(doc, unit, base)\n unit[\"attempts\"].append(attempt_record)\n unit[\"transport\"] = {\"base\": None, \"tree\": None, \"commit\": None, \"ref\": None, \"digest\": None, \"changed_paths\": []}\n unit[\"integration\"] = {\"intent_revision\": None, \"pre_fold\": None, \"expected_apply\": None, \"applied\": None, \"verification\": None, \"canonical_commit\": None, \"restore\": None}\n unit[\"cleanup\"] = None\n unit[\"recovery_path\"] = unit_root\n event(doc, \"unit-retry-prepared\", uid, {\"attempt_id\": attempt_id, \"base\": base})\n event(doc, \"worktree-add-intent\", uid, {\"path\": workspace, \"base\": base})\n with locked_manifest(args.run_id) as doc:\n common = doc[\"repository\"][\"common_dir\"]\n repo = doc[\"repository\"][\"toplevel\"]\n with admin_lock(common):\n if not os.path.exists(workspace):\n git(repo, \"worktree\", \"add\", \"--detach\", workspace, base)\n test_fault(\"after-worktree-add\")\n with locked_manifest(args.run_id) as doc:\n unit = doc[\"units\"][uid]\n validate_pristine_unit_base(doc, unit)\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][uid]\n unit[\"workspace\"][\"registered\"] = True\n event(doc, \"worktree-prepared\", uid, {\"path\": workspace, \"base\": base})\n return \"PREPARED\", {\n \"unit_id\": uid, \"attempt_id\": attempt_id,\n \"workspace\": workspace, \"result_dir\": os.path.join(unit_root, \"result\"),\n \"packet_path\": packet_path, \"packet_digest\": packet_digest,\n \"authorization_path\": authorization_path, \"authorization_digest\": authorization_digest,\n \"adapter\": attempt_record[\"adapter\"],\n \"base\": base, \"resumed\": False,\n }\n\n\ndef runner_job_dir(run_id: str, job_id: str) -> str:\n return os.path.join(run_dir(run_id), \"jobs\", safe_id(job_id, \"job id\"))\n\n\ndef process_evidence(job_dir: str) -> dict:\n validate_private_dir(job_dir)\n status_path = os.path.join(job_dir, \"status\")\n if os.path.lexists(status_path):\n word = read_private(status_path, 256).decode(\"ascii\", \"strict\").strip()\n if word not in TERMINAL_PROCESS:\n raise TrustFailure(\"runner terminal state is invalid\")\n elif os.path.lexists(os.path.join(job_dir, \"pid\")):\n read_private_json(os.path.join(job_dir, \"pid\"))\n word = \"running\"\n else:\n word = \"never-started\"\n failure_reason = None\n reason_path = os.path.join(job_dir, \"reason\")\n if word in TERMINAL_PROCESS and os.path.lexists(reason_path):\n failure_reason = read_private(reason_path, 4096).decode(\"utf-8\", \"strict\").strip() or None\n activity = {\"latest_at\": None, \"log_bytes\": 0}\n log = os.path.join(job_dir, \"out.log\")\n if os.path.lexists(log):\n st = stat_private_file(log)\n activity = {\"latest_at\": time.strftime(\"%Y-%m-%dT%H:%M:%SZ\", time.gmtime(st.st_mtime)), \"log_bytes\": st.st_size}\n return {\"process_state\": word, \"failure_reason\": failure_reason, \"activity\": activity}\n\n\nHOST_RECEIPT_FIELDS = (\n \"requested_route\", \"actual_route\", \"target\", \"harness\", \"intermediaries\",\n \"model_requested\", \"model_actual\", \"model_receipt_status\", \"effort_requested\", \"activity_posture\",\n \"restriction_posture\", \"failure_reason\", \"raw_log\", \"packet_digest\",\n)\nMAX_RESULT_BYTES = 5 * 1024 * 1024\nMAX_REPORTED_CHANGED_FILES = 1000\n\n\ndef _validate_private_dir_fd(fd: int, path: str) -> os.stat_result:\n st = os.fstat(fd)\n effective_uid = os.geteuid() if hasattr(os, \"geteuid\") else None\n if not stat.S_ISDIR(st.st_mode):\n raise TrustFailure(f\"not a real directory: {path}\")\n if effective_uid is not None and st.st_uid != effective_uid:\n raise TrustFailure(f\"directory is not owned by current user: {path}\")\n mode = stat.S_IMODE(st.st_mode)\n if mode != 0o700:\n raise TrustFailure(f\"directory mode is {mode:04o}, expected 0700: {path}\")\n return st\n\n\ndef private_result_dir_identity(path: str) -> dict:\n try:\n fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open result directory {path}: {exc}\") from exc\n try:\n st = _validate_private_dir_fd(fd, path)\n return {\"dev\": st.st_dev, \"ino\": st.st_ino}\n finally:\n os.close(fd)\n\n\ndef open_recorded_result_dir(unit: dict) -> tuple[int, str]:\n result_dir = os.path.join(os.path.dirname(unit[\"workspace\"][\"path\"]), \"result\")\n identity = unit.get(\"result_dir_identity\")\n if (\n not isinstance(identity, dict)\n or set(identity) != {\"dev\", \"ino\"}\n or any(not isinstance(identity.get(key), int) or isinstance(identity.get(key), bool) for key in (\"dev\", \"ino\"))\n ):\n raise TrustFailure(\"unit has no valid controller-recorded result directory identity\")\n try:\n fd = os.open(result_dir, os.O_RDONLY | os.O_DIRECTORY | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open result directory {result_dir}: {exc}\") from exc\n try:\n st = _validate_private_dir_fd(fd, result_dir)\n if (st.st_dev, st.st_ino) != (identity[\"dev\"], identity[\"ino\"]):\n raise TrustFailure(\"controller result directory identity changed\")\n return fd, result_dir\n except Exception:\n os.close(fd)\n raise\n\n\ndef read_private_at(dir_fd: int, name: str, cap: int, display_path: str) -> bytes:\n if os.path.basename(name) != name or name in {\"\", \".\", \"..\"}:\n raise TrustFailure(f\"unsafe state file name: {name!r}\")\n try:\n fd = os.open(name, os.O_RDONLY | O_NOFOLLOW, dir_fd=dir_fd)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open state file {display_path}: {exc}\") from exc\n try:\n st = os.fstat(fd)\n effective_uid = os.geteuid() if hasattr(os, \"geteuid\") else None\n if not stat.S_ISREG(st.st_mode):\n raise TrustFailure(f\"state is not a regular file: {display_path}\")\n if effective_uid is not None and st.st_uid != effective_uid:\n raise TrustFailure(f\"state is not owned by current user: {display_path}\")\n mode = stat.S_IMODE(st.st_mode)\n if mode != 0o600:\n raise TrustFailure(f\"state mode is {mode:04o}, expected 0600: {display_path}\")\n if st.st_size > cap:\n raise TrustFailure(f\"state exceeds {cap}-byte limit: {display_path}\")\n out = bytearray()\n while len(out) \u003c= cap:\n part = os.read(fd, min(65536, cap + 1 - len(out)))\n if not part:\n break\n out.extend(part)\n if len(out) > cap:\n raise TrustFailure(f\"state grew beyond {cap}-byte limit: {display_path}\")\n return bytes(out)\n finally:\n os.close(fd)\n\n\ndef stat_private_at(\n dir_fd: int,\n name: str,\n display_path: str,\n *,\n missing_ok: bool = False,\n) -> os.stat_result | None:\n if os.path.basename(name) != name or name in {\"\", \".\", \"..\"}:\n raise TrustFailure(f\"unsafe state file name: {name!r}\")\n try:\n fd = os.open(name, os.O_RDONLY | O_NOFOLLOW, dir_fd=dir_fd)\n except FileNotFoundError:\n if missing_ok:\n return None\n raise TrustFailure(f\"cannot safely open state file {display_path}: file is missing\")\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open state file {display_path}: {exc}\") from exc\n try:\n st = os.fstat(fd)\n effective_uid = os.geteuid() if hasattr(os, \"geteuid\") else None\n if not stat.S_ISREG(st.st_mode):\n raise TrustFailure(f\"state is not a regular file: {display_path}\")\n if effective_uid is not None and st.st_uid != effective_uid:\n raise TrustFailure(f\"state is not owned by current user: {display_path}\")\n mode = stat.S_IMODE(st.st_mode)\n if mode != 0o600:\n raise TrustFailure(f\"state mode is {mode:04o}, expected 0600: {display_path}\")\n return st\n finally:\n os.close(fd)\n\n\ndef read_recorded_result_file(unit: dict, name: str, cap: int) -> bytes:\n result_fd, result_dir = open_recorded_result_dir(unit)\n try:\n return read_private_at(\n result_fd,\n name,\n cap,\n os.path.join(result_dir, name),\n )\n finally:\n os.close(result_fd)\n\n\ndef read_recorded_result_json(unit: dict) -> tuple[dict, bytes]:\n result_path = os.path.join(os.path.dirname(unit[\"workspace\"][\"path\"]), \"result\", \"implementation-result.json\")\n raw = read_recorded_result_file(unit, \"implementation-result.json\", MAX_RESULT_BYTES)\n try:\n value = json.loads(raw)\n except (ValueError, UnicodeDecodeError) as exc:\n raise TrustFailure(f\"malformed JSON state: {result_path}\") from exc\n if not isinstance(value, dict):\n raise TrustFailure(f\"JSON state is not an object: {result_path}\")\n return value, raw\n\n\ndef terminal_receipt(\n unit: dict,\n attempt: dict,\n *,\n unavailable: bool = False,\n launched_failure: bool = False,\n) -> dict:\n result_dir = os.path.join(os.path.dirname(unit[\"workspace\"][\"path\"]), \"result\")\n receipt, result_bytes = read_recorded_result_json(unit)\n authorization = attempt.get(\"authorization\")\n if not isinstance(authorization, dict):\n raise Operational(\"BLOCKED\", \"attempt has no controller-issued route authorization\")\n expected = {\n \"requested_route\": authorization[\"route\"],\n \"actual_route\": None if unavailable else authorization[\"route\"],\n \"target\": authorization[\"target\"],\n \"harness\": authorization[\"harness\"],\n \"intermediaries\": authorization[\"intermediaries\"],\n \"model_requested\": authorization[\"model_requested\"],\n \"effort_requested\": authorization.get(\"effort_requested\"),\n \"restriction_posture\": authorization[\"restriction_posture\"],\n \"packet_digest\": unit[\"packet_digest\"],\n }\n if unavailable or launched_failure:\n expected[\"activity_posture\"] = authorization[\"activity_posture\"]\n mismatches = {key: {\"expected\": value, \"actual\": receipt.get(key)} for key, value in expected.items() if receipt.get(key) != value}\n if mismatches:\n raise Operational(\"BLOCKED\", \"adapter terminal receipt does not match controller authorization\", {\"mismatches\": mismatches})\n terminal_status = receipt.get(\"terminal_status\")\n if unavailable:\n neutral = {\n \"schema_version\": 1,\n \"terminal_status\": \"unavailable\",\n \"summary\": \"External route unavailable\",\n \"changed_files\": [],\n \"evidence\": [],\n \"scope_expansion\": None,\n \"model_actual\": \"unverified\",\n \"model_receipt_status\": \"unverified\",\n }\n invalid = {key: {\"expected\": value, \"actual\": receipt.get(key)} for key, value in neutral.items() if receipt.get(key) != value}\n failure_reason = receipt.get(\"failure_reason\")\n if invalid or not isinstance(failure_reason, str) or not failure_reason or len(failure_reason.encode()) > 4096:\n raise Operational(\n \"BLOCKED\",\n \"failed runner did not publish a bounded neutral unavailable receipt\",\n {\"mismatches\": invalid},\n )\n elif launched_failure:\n neutral = {\n \"schema_version\": 1,\n \"terminal_status\": \"failed\",\n \"changed_files\": [],\n \"evidence\": [],\n \"scope_expansion\": None,\n }\n invalid = {key: {\"expected\": value, \"actual\": receipt.get(key)} for key, value in neutral.items() if receipt.get(key) != value}\n failure_reason = receipt.get(\"failure_reason\")\n summary = receipt.get(\"summary\")\n if (\n invalid\n or not isinstance(failure_reason, str)\n or not failure_reason\n or len(failure_reason.encode()) > 4096\n or not isinstance(summary, str)\n or not summary\n or len(summary.encode()) > 4096\n ):\n raise Operational(\n \"BLOCKED\",\n \"failed runner did not publish a bounded neutral launched-route receipt\",\n {\"mismatches\": invalid},\n )\n else:\n if terminal_status not in {\"completed\", \"blocked\", \"scope_expansion\"}:\n raise Operational(\"BLOCKED\", \"successful runner did not publish a host-resolvable adapter result\")\n if terminal_status == \"scope_expansion\" and not isinstance(receipt.get(\"scope_expansion\"), dict):\n raise Operational(\"BLOCKED\", \"scope-expansion adapter result has no expansion receipt\")\n changed_files = receipt.get(\"changed_files\")\n if (\n not isinstance(changed_files, list)\n or len(changed_files) > MAX_REPORTED_CHANGED_FILES\n or any(not isinstance(path, str) or not path for path in changed_files)\n ):\n raise Operational(\"BLOCKED\", \"adapter terminal receipt has invalid changed-files evidence\")\n raw_log = receipt.get(\"raw_log\")\n expected_log = os.path.join(result_dir, \"adapter.log\")\n if not isinstance(raw_log, str) or os.path.abspath(raw_log) != expected_log:\n raise Operational(\"BLOCKED\", \"adapter raw-log receipt escaped the controller result directory\")\n log_bytes = read_recorded_result_file(unit, \"adapter.log\", 10 * 1024 * 1024)\n return {key: receipt.get(key) for key in HOST_RECEIPT_FIELDS} | {\n \"terminal_status\": receipt[\"terminal_status\"],\n \"summary\": str(receipt.get(\"summary\", \"\"))[:4096],\n \"changed_files\": changed_files,\n \"changed_file_count\": len(changed_files),\n \"evidence_count\": len(receipt.get(\"evidence\", [])),\n \"scope_expansion_requested\": receipt.get(\"scope_expansion\") is not None,\n \"result_sha256\": digest_bytes(result_bytes),\n \"raw_log_sha256\": digest_bytes(log_bytes),\n \"raw_log_bytes\": len(log_bytes),\n }\n\n\ndef _validate_authorized_failed_job(\n run_id: str,\n unit: dict,\n attempt: dict,\n) -> None:\n job_id = attempt.get(\"job_id\")\n if not isinstance(job_id, str):\n raise Operational(\"BLOCKED\", \"failed receipt has no bound runner job\")\n job_dir = runner_job_dir(run_id, job_id)\n if process_evidence(job_dir)[\"process_state\"] != \"failed\":\n raise Operational(\"BLOCKED\", \"failed receipt requires authoritative failed runner evidence\")\n meta = read_private_json(os.path.join(job_dir, \"meta.json\"))\n if meta.get(\"job_id\") != job_id:\n raise Operational(\"BLOCKED\", \"runner job metadata identity mismatch\")\n validate_runner_contract(run_id, unit, meta)\n expected_result_dir = os.path.join(os.path.dirname(unit[\"workspace\"][\"path\"]), \"result\")\n expected_dispatch = {\n \"attempt_id\": attempt.get(\"attempt_id\"),\n \"job_id\": job_id,\n \"authorization_path\": attempt.get(\"authorization_path\"),\n \"authorization_digest\": attempt.get(\"authorization_digest\"),\n \"workspace\": unit[\"workspace\"][\"path\"],\n \"packet_path\": unit[\"packet\"][\"path\"],\n \"packet_digest\": unit[\"packet_digest\"],\n \"result_dir\": expected_result_dir,\n \"result_dir_identity\": unit.get(\"result_dir_identity\"),\n }\n if attempt.get(\"dispatch_authorization_receipt\") != expected_dispatch:\n raise Operational(\"BLOCKED\", \"failed receipt is not bound to the exact authorized dispatch\")\n\n\ndef _authorized_failed_terminal_receipt(\n run_id: str,\n unit: dict,\n attempt: dict,\n *,\n unavailable: bool,\n) -> dict:\n _validate_authorized_failed_job(run_id, unit, attempt)\n return terminal_receipt(\n unit,\n attempt,\n unavailable=unavailable,\n launched_failure=not unavailable,\n )\n\n\ndef unavailable_terminal_receipt(run_id: str, unit: dict, attempt: dict) -> dict:\n return _authorized_failed_terminal_receipt(run_id, unit, attempt, unavailable=True)\n\n\ndef launched_failure_terminal_receipt(run_id: str, unit: dict, attempt: dict) -> dict:\n return _authorized_failed_terminal_receipt(run_id, unit, attempt, unavailable=False)\n\n\ndef record_terminal_validation_failure(run_id: str, unit_id: str, error: Operational) -> None:\n if isinstance(error, TrustFailure):\n raise error\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"][unit_id]\n result_digest = digest_bytes(read_recorded_result_file(unit, \"implementation-result.json\", MAX_RESULT_BYTES))\n with locked_manifest(run_id, write=True) as doc:\n attempt = find_attempt(doc[\"units\"][unit_id])\n failure = {\n \"at\": now_iso(),\n \"word\": error.word,\n \"reason\": str(error),\n \"detail\": error.detail,\n \"job_id\": attempt.get(\"job_id\"),\n \"result_sha256\": result_digest,\n }\n attempt[\"terminal_validation_failure\"] = failure\n fallback = attempt.setdefault(\"fallback\", {})\n fallback.setdefault(\"claimed\", None)\n fallback[\"eligible\"] = fallback.get(\"claimed\") is None\n fallback[\"reason\"] = \"terminal-validation-failure\"\n event(doc, \"terminal-validation-failed\", unit_id, failure)\n\n\ndef validate_terminal_validation_failure(run_id: str, unit: dict, attempt: dict) -> dict:\n failure = attempt.get(\"terminal_validation_failure\")\n if not isinstance(failure, dict) or failure.get(\"job_id\") != attempt.get(\"job_id\"):\n raise Operational(\"REFUSED\", \"attempt has no exact terminal-validation failure\")\n observed = process_evidence(runner_job_dir(run_id, attempt[\"job_id\"]))[\"process_state\"]\n if observed != \"done\":\n raise Operational(\"BLOCKED\", \"terminal-validation job evidence changed\")\n if digest_bytes(read_recorded_result_file(unit, \"implementation-result.json\", MAX_RESULT_BYTES)) != failure.get(\"result_sha256\"):\n raise Operational(\"BLOCKED\", \"terminal-validation result evidence changed\")\n return failure\n\n\ndef retire_terminal_validation_failure(unit: dict) -> None:\n attempt = find_attempt(unit)\n failure = attempt.get(\"terminal_validation_failure\")\n claimed = attempt.get(\"fallback\", {}).get(\"claimed\")\n if failure is not None and not claimed:\n attempt.pop(\"terminal_validation_failure\")\n attempt[\"fallback\"] = {\"eligible\": False, \"reason\": None, \"claimed\": None}\n\n\ndef validate_runner_contract(run_id: str, unit: dict, meta: dict) -> None:\n unit_id = unit[\"unit_id\"]\n expected_result_dir = os.path.join(run_dir(run_id), \"units\", unit_id, \"result\")\n expected_result_file = os.path.join(expected_result_dir, \"implementation-result.json\")\n if meta.get(\"skill\") != \"ce-work\":\n raise Operational(\"BLOCKED\", \"runner skill must be 'ce-work'\")\n if meta.get(\"run_id\") != run_id:\n raise Operational(\"BLOCKED\", f\"runner run id must equal the controller run id exactly: expected {run_id!r}\")\n if meta.get(\"label\") != unit_id:\n raise Operational(\n \"BLOCKED\",\n f\"runner label must equal unit id exactly: expected {unit_id!r}, got {meta.get('label')!r}\",\n )\n if meta.get(\"input_digest\") != unit[\"packet_digest\"]:\n raise Operational(\"BLOCKED\", \"runner input digest must equal the controller packet digest\")\n if not isinstance(meta.get(\"result_path\"), str) or os.path.abspath(meta[\"result_path\"]) != expected_result_file:\n raise Operational(\n \"BLOCKED\",\n f\"runner result path must be the controller result file: {expected_result_file}\",\n )\n attempt = find_attempt(unit)\n authorization = attempt.get(\"authorization\")\n authorization_path = attempt.get(\"authorization_path\")\n authorization_digest = attempt.get(\"authorization_digest\")\n if not isinstance(authorization, dict) or not isinstance(authorization_path, str) or not isinstance(authorization_digest, str):\n raise Operational(\"BLOCKED\", \"attempt has no controller-issued authorization artifact\")\n authorization_bytes = read_private(authorization_path, MAX_JSON_BYTES)\n try:\n observed_authorization = json.loads(authorization_bytes)\n except (ValueError, UnicodeDecodeError) as exc:\n raise TrustFailure(\"controller authorization artifact is malformed\") from exc\n if observed_authorization != authorization or digest_bytes(authorization_bytes) != authorization_digest:\n raise Operational(\"BLOCKED\", \"controller authorization artifact no longer matches the recorded attempt\")\n expected_argv = [\n attempt.get(\"adapter\"), authorization_path, unit[\"workspace\"][\"path\"],\n unit[\"packet\"][\"path\"], unit[\"packet_digest\"], expected_result_dir,\n ]\n if meta.get(\"worker_argv\") != expected_argv:\n raise Operational(\n \"BLOCKED\", \"runner worker argv does not match the controller-issued fixed-route contract\",\n {\"expected_argv\": expected_argv, \"actual_argv\": meta.get(\"worker_argv\")},\n )\n\n\ndef cmd_authorize_dispatch(args) -> tuple[str, dict]:\n run_id = safe_id(args.run_id, \"run id\")\n unit_id = safe_id(args.unit_id, \"unit id\")\n attempt_id = safe_id(args.attempt_id, \"attempt id\")\n job_id = safe_id(args.job_id, \"job id\")\n if not re.fullmatch(r\"[0-9a-f]{64}\", args.authorization_digest):\n raise Operational(\"REFUSED\", \"observed authorization digest must be lowercase SHA-256\")\n if not re.fullmatch(r\"[0-9a-f]{64}\", args.packet_digest):\n raise Operational(\"REFUSED\", \"observed packet digest must be lowercase SHA-256\")\n with locked_manifest(run_id, write=True) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit, attempt_id)\n if unit.get(\"state\") not in {\"queued\", \"authoring\"}:\n raise Operational(\"REFUSED\", \"dispatch authorization is available only before worker completion\")\n bound_job = attempt.get(\"job_id\")\n if bound_job not in (None, job_id):\n raise Operational(\"AMBIGUOUS\", \"attempt is already bound to another job\")\n job_dir = os.path.join(run_dir(run_id), \"jobs\", job_id)\n validate_private_dir(job_dir)\n meta = read_private_json(os.path.join(job_dir, \"meta.json\"))\n if meta.get(\"job_id\") != job_id:\n raise Operational(\"BLOCKED\", \"runner job metadata identity mismatch\")\n validate_runner_contract(run_id, unit, meta)\n\n expected_authorization_path = attempt.get(\"authorization_path\")\n expected_authorization_digest = attempt.get(\"authorization_digest\")\n if os.path.abspath(args.authorization) != expected_authorization_path:\n raise Operational(\"BLOCKED\", \"authorization path does not match the recorded attempt\")\n if args.authorization_digest != expected_authorization_digest:\n raise Operational(\"BLOCKED\", \"observed authorization digest does not match the recorded attempt\")\n authorization_bytes = read_private(expected_authorization_path, MAX_JSON_BYTES)\n if digest_bytes(authorization_bytes) != expected_authorization_digest:\n raise Operational(\"BLOCKED\", \"controller authorization bytes no longer match the recorded digest\")\n try:\n authorization = json.loads(authorization_bytes)\n except (ValueError, UnicodeDecodeError) as exc:\n raise TrustFailure(\"controller authorization artifact is malformed\") from exc\n if authorization != attempt.get(\"authorization\"):\n raise Operational(\"BLOCKED\", \"controller authorization object no longer matches the recorded attempt\")\n if (\n authorization.get(\"run_id\") != run_id\n or authorization.get(\"unit_id\") != unit_id\n or authorization.get(\"attempt_id\") != attempt_id\n ):\n raise Operational(\"BLOCKED\", \"authorization run/unit/attempt identity mismatch\")\n\n expected_workspace = unit[\"workspace\"][\"path\"]\n if os.path.abspath(args.workspace) != expected_workspace:\n raise Operational(\"BLOCKED\", \"workspace path does not match the recorded unit\")\n expected_dispatch_authorization_receipt = {\n \"attempt_id\": attempt_id,\n \"job_id\": job_id,\n \"authorization_path\": expected_authorization_path,\n \"authorization_digest\": expected_authorization_digest,\n \"workspace\": expected_workspace,\n \"packet_path\": unit[\"packet\"][\"path\"],\n \"packet_digest\": unit[\"packet_digest\"],\n \"result_dir\": os.path.join(os.path.dirname(expected_workspace), \"result\"),\n \"result_dir_identity\": unit.get(\"result_dir_identity\"),\n }\n recorded_dispatch_authorization_receipt = attempt.get(\"dispatch_authorization_receipt\")\n if recorded_dispatch_authorization_receipt is not None and (\n bound_job != job_id\n or recorded_dispatch_authorization_receipt != expected_dispatch_authorization_receipt\n ):\n raise Operational(\"BLOCKED\", \"recorded dispatch authorization does not match the exact request\")\n resumed = recorded_dispatch_authorization_receipt == expected_dispatch_authorization_receipt\n if resumed:\n validate_workspace(doc, unit)\n else:\n validate_pristine_unit_base(doc, unit)\n\n expected_packet = unit[\"packet\"][\"path\"]\n if os.path.abspath(args.packet) != expected_packet:\n raise Operational(\"BLOCKED\", \"packet path does not match the controller-owned unit packet\")\n if args.packet_digest != unit[\"packet_digest\"] or authorization.get(\"packet_digest\") != unit[\"packet_digest\"]:\n raise Operational(\"BLOCKED\", \"packet digest does not match the recorded authorization\")\n packet_bytes = read_private(expected_packet, MAX_PACKET_BYTES)\n if digest_bytes(packet_bytes) != unit[\"packet_digest\"]:\n raise Operational(\"BLOCKED\", \"controller-owned packet bytes no longer match the recorded digest\")\n\n expected_result_dir = os.path.join(os.path.dirname(expected_workspace), \"result\")\n if os.path.abspath(args.result_dir) != expected_result_dir:\n raise Operational(\"BLOCKED\", \"result directory does not match the recorded unit\")\n result_fd, _ = open_recorded_result_dir(unit)\n os.close(result_fd)\n if not resumed:\n attempt[\"job_id\"] = job_id\n attempt[\"dispatch_authorization_receipt\"] = expected_dispatch_authorization_receipt\n unit[\"state\"] = \"authoring\"\n event(doc, \"job-bound\", unit_id, {\n \"attempt_id\": attempt_id,\n \"job_id\": job_id,\n \"source\": \"authorize-dispatch\",\n })\n return \"AUTHORIZED\", {\n \"run_id\": run_id,\n \"unit_id\": unit_id,\n \"attempt_id\": attempt_id,\n \"job_id\": job_id,\n \"resumed\": resumed,\n \"authorization_digest\": expected_authorization_digest,\n \"packet_digest\": unit[\"packet_digest\"],\n }\n\n\ndef matching_runner_jobs(run_id: str, unit: dict) -> list[str]:\n jobs = os.path.join(run_dir(run_id), \"jobs\")\n validate_private_dir(jobs)\n matches: list[str] = []\n for entry in os.scandir(jobs):\n if not entry.is_dir(follow_symlinks=False):\n continue\n safe_id(entry.name, \"job id\")\n validate_private_dir(entry.path)\n meta = read_private_json(os.path.join(entry.path, \"meta.json\"))\n if (\n meta.get(\"skill\") == \"ce-work\"\n and meta.get(\"run_id\") == run_id\n and meta.get(\"label\") == unit[\"unit_id\"]\n and meta.get(\"input_digest\") == unit[\"packet_digest\"]\n ):\n validate_runner_contract(run_id, unit, meta)\n matches.append(entry.name)\n return sorted(matches)\n\n\ndef find_attempt(unit: dict, attempt_id: str | None = None) -> dict:\n attempts = unit.get(\"attempts\", [])\n if attempt_id:\n matches = [a for a in attempts if a.get(\"attempt_id\") == attempt_id]\n else:\n matches = attempts[-1:]\n if len(matches) != 1:\n raise Operational(\"AMBIGUOUS\", \"attempt could not be identified exactly\")\n return matches[0]\n\n\ndef scope_expansion_pending(unit: dict) -> bool:\n \"\"\"Return whether the current authored result still requires host resolution.\"\"\"\n receipt = find_attempt(unit).get(\"terminal_receipt\")\n return isinstance(receipt, dict) and receipt.get(\"terminal_status\") == \"scope_expansion\"\n\n\ndef cmd_record_job(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit, args.attempt_id)\n if attempt.get(\"job_id\"):\n if attempt[\"job_id\"] != args.job_id:\n raise Operational(\"AMBIGUOUS\", \"attempt is already bound to another job\")\n return \"AUTHORING\", {\n \"unit_id\": args.unit_id,\n \"job_id\": args.job_id,\n \"resumed\": True,\n \"unit_state\": unit[\"state\"],\n }\n job_dir = runner_job_dir(args.run_id, args.job_id)\n meta = read_private_json(os.path.join(job_dir, \"meta.json\"))\n validate_runner_contract(args.run_id, unit, meta)\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][args.unit_id]\n attempt = find_attempt(unit, args.attempt_id)\n bound_job = attempt.get(\"job_id\")\n if bound_job == args.job_id:\n return \"AUTHORING\", {\n \"unit_id\": args.unit_id,\n \"job_id\": args.job_id,\n \"resumed\": True,\n \"unit_state\": unit[\"state\"],\n }\n if bound_job is not None:\n raise Operational(\"AMBIGUOUS\", \"attempt was concurrently bound\")\n if unit.get(\"state\") != \"queued\":\n raise Operational(\"REFUSED\", \"an unbound job can be recorded only while the unit is queued\")\n attempt[\"job_id\"] = args.job_id\n unit[\"state\"] = \"authoring\"\n event(doc, \"job-bound\", args.unit_id, {\"attempt_id\": args.attempt_id, \"job_id\": args.job_id})\n return \"AUTHORING\", {\"unit_id\": args.unit_id, \"job_id\": args.job_id, \"resumed\": False}\n\n\ndef sync_job(run_id: str, unit_id: str) -> dict:\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"].get(unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit)\n if not attempt.get(\"job_id\"):\n return {\"process_state\": \"never-started\", \"activity\": attempt[\"activity\"]}\n evidence = process_evidence(runner_job_dir(run_id, attempt[\"job_id\"]))\n failure_receipt = None\n oversized_result_failure = False\n if evidence[\"process_state\"] == \"failed\":\n result_fd, result_dir = open_recorded_result_dir(unit)\n try:\n result_stat = stat_private_at(\n result_fd,\n \"implementation-result.json\",\n os.path.join(result_dir, \"implementation-result.json\"),\n missing_ok=True,\n )\n finally:\n os.close(result_fd)\n if result_stat is not None and result_stat.st_size > MAX_RESULT_BYTES:\n _validate_authorized_failed_job(run_id, unit, attempt)\n oversized_result_failure = True\n else:\n for reader in (unavailable_terminal_receipt, launched_failure_terminal_receipt):\n try:\n failure_receipt = reader(run_id, unit, attempt)\n break\n except TrustFailure:\n raise\n except Operational:\n continue\n with locked_manifest(run_id, write=True) as doc:\n attempt = find_attempt(doc[\"units\"][unit_id])\n prior_state = attempt.get(\"process_state\")\n prior_activity = dict(attempt[\"activity\"])\n prior_fallback = dict(attempt.get(\"fallback\", {}))\n prior_receipt = attempt.get(\"terminal_receipt\")\n attempt[\"process_state\"] = evidence[\"process_state\"]\n attempt[\"activity\"].update(evidence[\"activity\"])\n if failure_receipt is not None:\n attempt[\"terminal_receipt\"] = failure_receipt\n authoritative_failure = evidence[\"process_state\"] in TERMINAL_PROCESS - {\"done\"} or (\n evidence[\"process_state\"] == \"never-started\" and bool(attempt.get(\"job_id\"))\n )\n effective_failure_reason = None\n if authoritative_failure:\n effective_failure_reason = (\n failure_receipt[\"failure_reason\"]\n if failure_receipt is not None\n else evidence[\"failure_reason\"]\n if oversized_result_failure and evidence[\"failure_reason\"]\n else evidence[\"process_state\"]\n )\n fallback = attempt.setdefault(\"fallback\", {})\n fallback.setdefault(\"claimed\", None)\n fallback[\"eligible\"] = fallback.get(\"claimed\") is None\n fallback[\"reason\"] = effective_failure_reason\n changed = (\n prior_state != evidence[\"process_state\"]\n or prior_activity != attempt[\"activity\"]\n or prior_fallback != attempt.get(\"fallback\", {})\n or prior_receipt != attempt.get(\"terminal_receipt\")\n )\n if changed:\n event(doc, \"job-synced\", unit_id, {\"process_state\": evidence[\"process_state\"]})\n if prior_state != evidence[\"process_state\"] and evidence[\"process_state\"] in TERMINAL_PROCESS:\n event(doc, \"job-terminal\", unit_id, {\"process_state\": evidence[\"process_state\"]})\n if failure_receipt is not None and prior_receipt != failure_receipt:\n receipt_event = \"route-unavailable\" if failure_receipt[\"terminal_status\"] == \"unavailable\" else \"route-failed\"\n event(doc, receipt_event, unit_id, {\"failure_reason\": failure_receipt[\"failure_reason\"]})\n activity = dict(attempt[\"activity\"])\n return {\n \"process_state\": evidence[\"process_state\"],\n \"failure_reason\": effective_failure_reason,\n \"activity\": activity,\n }\n\n\ndef cmd_sync_job(args) -> tuple[str, dict]:\n evidence = sync_job(args.run_id, args.unit_id)\n return \"SYNCED\", {\"unit_id\": args.unit_id, **evidence}\n\n\ndef transport_ref(run_id: str, unit_id: str) -> str:\n return f\"refs/ce-work/{digest_bytes(run_id.encode())[:20]}/{digest_bytes(unit_id.encode())[:20]}\"\n\n\ndef no_sequencer(workspace: str) -> None:\n git_dir = git_text(workspace, \"rev-parse\", \"--path-format=absolute\", \"--absolute-git-dir\")\n for name in (\"MERGE_HEAD\", \"CHERRY_PICK_HEAD\", \"REVERT_HEAD\", \"rebase-merge\", \"rebase-apply\"):\n if os.path.exists(os.path.join(git_dir, name)):\n raise Operational(\"BLOCKED\", f\"worker workspace has unresolved Git operation: {name}\")\n\n\ndef parse_diff_paths(raw: bytes) -> list[str]:\n parts = raw.split(b\"\\0\")\n paths: list[str] = []\n expect_paths = 0\n for part in parts:\n if not part:\n continue\n text = part.decode(\"utf-8\", \"surrogateescape\")\n if expect_paths:\n paths.append(text)\n expect_paths -= 1\n else:\n expect_paths = 2 if text.startswith((\"R\", \"C\")) else 1\n if expect_paths:\n raise Operational(\"BLOCKED\", \"incomplete NUL-delimited transport inventory\")\n return paths\n\n\ndef diff_changes_gitlink(raw: bytes) -> bool:\n for record in raw.split(b\"\\0\"):\n if not record.startswith(b\":\"):\n continue\n fields = record[1:].split(b\" \", 4)\n if len(fields) >= 2 and b\"160000\" in fields[:2]:\n return True\n return False\n\n\ndef terminalize(run_id: str, unit_id: str) -> dict:\n evidence = sync_job(run_id, unit_id)\n if evidence[\"process_state\"] != \"done\":\n detail = {}\n if evidence[\"process_state\"] == \"failed\":\n with locked_manifest(run_id) as doc:\n attempt = find_attempt(doc[\"units\"][unit_id])\n receipt = attempt.get(\"terminal_receipt\")\n if isinstance(receipt, dict) and receipt.get(\"terminal_status\") == \"unavailable\":\n detail = {\"terminal_receipt\": receipt, \"failure_reason\": receipt[\"failure_reason\"]}\n raise Operational(\n \"BLOCKED\",\n f\"worker is not authoritatively done ({evidence['process_state']})\",\n detail,\n )\n try:\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"].get(unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n receipt = terminal_receipt(unit, find_attempt(unit))\n if receipt.get(\"model_receipt_status\") == \"mismatch\":\n raise Operational(\"BLOCKED\", \"adapter reported a served-model mismatch\")\n except Operational as exc:\n record_terminal_validation_failure(run_id, unit_id, exc)\n raise\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"].get(unit_id)\n if unit and unit[\"state\"] == \"authoring\":\n find_attempt(unit)[\"terminal_receipt\"] = receipt\n unit[\"state\"] = \"authored\"\n event(doc, \"worker-output-authored\", unit_id, {\"route\": receipt[\"actual_route\"], \"model\": receipt[\"model_actual\"]})\n if receipt[\"terminal_status\"] == \"blocked\":\n raise Operational(\n \"BLOCKED\",\n \"worker returned a host-resolvable blocker\",\n {\n \"unit_id\": unit_id,\n \"terminal_status\": \"blocked\",\n \"summary\": receipt[\"summary\"],\n \"terminal_receipt\": receipt,\n \"recovery_path\": os.path.join(run_dir(run_id), \"units\", unit_id),\n },\n )\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"].get(unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n if unit[\"state\"] == \"integration-pending\" and unit[\"transport\"].get(\"commit\"):\n retire_terminal_validation_failure(unit)\n return unit[\"transport\"]\n if unit[\"state\"] != \"authored\":\n raise Operational(\"BLOCKED\", f\"unit cannot terminalize from {unit['state']}\")\n if find_attempt(unit).get(\"fallback\", {}).get(\"claimed\"):\n raise Operational(\n \"REFUSED\",\n \"native fallback already owns implementation; worker output cannot be terminalized\",\n )\n validate_workspace(doc, unit)\n workspace = unit[\"workspace\"][\"path\"]\n base = unit[\"workspace\"][\"base\"]\n repo = doc[\"repository\"][\"toplevel\"]\n try:\n no_sequencer(workspace)\n ignored_raw = git(workspace, \"ls-files\", \"--others\", \"--ignored\", \"--exclude-standard\", \"-z\")\n ignored_paths = [\n part.decode(\"utf-8\", \"surrogateescape\")\n for part in ignored_raw.split(b\"\\0\")\n if part\n ]\n if ignored_paths:\n preview = json.dumps(ignored_paths[:20], ensure_ascii=True)\n suffix = f\" and {len(ignored_paths) - 20} more\" if len(ignored_paths) > 20 else \"\"\n raise Operational(\n \"BLOCKED\",\n f\"worker workspace contains ignored untracked output that cannot enter the transport: {preview}{suffix}\",\n {\"ignored_paths\": ignored_paths[:100], \"ignored_path_count\": len(ignored_paths)},\n )\n git(workspace, \"add\", \"-A\", \"--\", \".\")\n tree = git_text(workspace, \"write-tree\")\n mode_diff = git(repo, \"diff-tree\", \"-r\", \"--raw\", \"-z\", \"--no-renames\", base, tree)\n if diff_changes_gitlink(mode_diff):\n raise Operational(\"BLOCKED\", \"submodule state cannot be transported implicitly\")\n except Operational as exc:\n record_terminal_validation_failure(run_id, unit_id, exc)\n raise\n ref = transport_ref(run_id, unit_id)\n existing = git_text(repo, \"rev-parse\", \"-q\", \"--verify\", ref, check=False)\n if existing:\n parents = git_text(repo, \"rev-list\", \"--parents\", \"-n\", \"1\", existing).split()\n existing_tree = git_text(repo, \"rev-parse\", f\"{existing}^{{tree}}\")\n if parents != [existing, base] or existing_tree != tree:\n raise Operational(\"BLOCKED\", \"preexisting transport ref does not match final tree/base\")\n commit = existing\n else:\n env = {\n \"GIT_AUTHOR_NAME\": \"ce-work transport\",\n \"GIT_AUTHOR_EMAIL\": \"ce-work@localhost\",\n \"GIT_COMMITTER_NAME\": \"ce-work transport\",\n \"GIT_COMMITTER_EMAIL\": \"ce-work@localhost\",\n }\n commit = git(repo, \"commit-tree\", tree, \"-p\", base, input_data=f\"ce-work transport {run_id}/{unit_id}\\n\".encode(), env=env).decode().strip()\n zero = \"0\" * len(commit)\n git(repo, \"update-ref\", ref, commit, zero)\n test_fault(\"after-transport-ref\")\n raw_diff = git(repo, \"diff-tree\", \"-r\", \"-M\", \"--name-status\", \"-z\", base, commit)\n paths = parse_diff_paths(raw_diff)\n tdigest = digest_bytes(base.encode() + b\"\\0\" + tree.encode() + b\"\\0\" + commit.encode() + b\"\\0\" + raw_diff)\n transport = {\n \"base\": base, \"tree\": tree, \"commit\": commit, \"ref\": ref,\n \"digest\": tdigest, \"changed_paths\": paths,\n \"inventory_b64\": base64.b64encode(raw_diff).decode(),\n }\n # Make successful cleanup non-destructive: after F is pinned, normalize the\n # retained inspection worktree to the exact transported tree.\n git(workspace, \"reset\", \"--hard\", commit)\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"][unit_id]\n if unit[\"state\"] not in (\"authored\", \"integration-pending\"):\n raise Operational(\"BLOCKED\", \"unit state changed during terminalization\")\n retire_terminal_validation_failure(unit)\n unit[\"state\"] = \"integration-pending\"\n unit[\"transport\"] = transport\n event(doc, \"transport-pinned\", unit_id, {\"commit\": commit, \"ref\": ref, \"digest\": tdigest})\n return transport\n\n\ndef cmd_terminalize(args) -> tuple[str, dict]:\n transport = terminalize(args.run_id, args.unit_id)\n return \"INTEGRATION_PENDING\", {\"unit_id\": args.unit_id, \"transport\": transport}\n","content_type":"text/x-python; charset=utf-8","language":"python","size":56411,"content_sha256":"2dd58f0599026fadeede47b8dd90708e22087c33a2164c93b5ef83b9f0e88eac"},{"filename":"scripts/unit_workspace_lifecycle.py","content":"\"\"\"Resume, fallback, reap, and finalized-artifact lifecycle operations.\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nimport re\nimport shutil\nimport subprocess\nimport sys\nfrom types import SimpleNamespace\n\nfrom unit_workspace_state import *\nfrom unit_workspace_jobs import *\nfrom unit_workspace_integration import *\n\n\ndef cmd_status(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n validate_repo(doc)\n source = doc.get(\"source\") or {\"kind\": \"plan\", **doc.get(\"plan\", {})}\n if args.unit_id:\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n body = {\"run_id\": args.run_id, \"revision\": doc[\"revision\"], \"source\": source, \"unit\": unit, \"integration_lock\": doc.get(\"integration_lock\"), \"verifications\": doc.get(\"verifications\", []), \"blockers\": doc.get(\"blockers\", [])}\n else:\n body = {\"run_id\": args.run_id, \"revision\": doc[\"revision\"], \"source\": source, \"units\": doc[\"units\"], \"integration_lock\": doc.get(\"integration_lock\"), \"verifications\": doc.get(\"verifications\", []), \"blockers\": doc.get(\"blockers\", []), \"recovery_path\": run_dir(args.run_id)}\n return \"STATUS\", body\n\n\ndef unfinished_run(doc: dict, canonical_head: str) -> bool:\n units = doc.get(\"units\")\n if not isinstance(units, dict):\n raise TrustFailure(\"manifest units are malformed\")\n if not units:\n return True\n states: list[str] = []\n for uid, unit in units.items():\n if not isinstance(uid, str) or not SAFE_ID.fullmatch(uid) or not isinstance(unit, dict):\n raise TrustFailure(\"manifest unit identity or record is malformed\")\n state = unit.get(\"state\")\n if state not in UNIT_STATES:\n raise TrustFailure(f\"manifest unit state is invalid: {uid}\")\n states.append(state)\n terminal_states = {\"cleaned\", \"native-completed\"}\n if any(state not in terminal_states for state in states):\n return True\n for uid, unit in doc[\"units\"].items():\n if unit.get(\"state\") != \"native-completed\":\n continue\n attempt = find_attempt(unit)\n fallback = attempt.get(\"fallback\", {})\n claim = fallback.get(\"claimed\") if isinstance(fallback, dict) else None\n completion = fallback.get(\"completed\") if isinstance(fallback, dict) else None\n claim_valid = isinstance(claim, dict) and claim.get(\"mode\") in {\"prefer\", \"require\"}\n if not (\n claim_valid\n and isinstance(completion, dict)\n and completion.get(\"claim\") == claim\n and isinstance(completion.get(\"at\"), str)\n and completion.get(\"at\")\n and isinstance(completion.get(\"summary\"), str)\n and completion.get(\"summary\")\n and isinstance(completion.get(\"evidence_digest\"), str)\n and re.fullmatch(r\"[0-9a-f]{64}\", completion[\"evidence_digest\"])\n and isinstance(completion.get(\"accepted_head\"), str)\n and re.fullmatch(r\"[0-9a-f]{40}|[0-9a-f]{64}\", completion[\"accepted_head\"])\n and completion.get(\"base\") == unit.get(\"workspace\", {}).get(\"base\")\n and isinstance(completion.get(\"snapshot\"), dict)\n and completion[\"snapshot\"].get(\"head\") == completion[\"accepted_head\"]\n and completion[\"snapshot\"].get(\"branch_ref\") == doc.get(\"branch\", {}).get(\"ref\")\n and completion[\"snapshot\"].get(\"status_empty\") is True\n and completion[\"snapshot\"].get(\"worktree_index_empty\") is True\n and completion[\"snapshot\"].get(\"head_tree\") == completion[\"snapshot\"].get(\"index_tree\")\n and completion[\"snapshot\"].get(\"status_sha256\") == digest_bytes(b\"\")\n ):\n raise TrustFailure(f\"native fallback completion receipt is malformed: {uid}\")\n receipts = doc.get(\"verifications\", [])\n if not isinstance(receipts, list) or any(not isinstance(receipt, dict) for receipt in receipts):\n raise TrustFailure(\"manifest verification receipts are malformed\")\n accepted_units = accepted_unit_commit_snapshot(units)\n if accepted_units is None:\n return True\n return doc.get(\"integration_lock\") is not None or not any(\n receipt.get(\"verification_exit\") == 0\n and receipt.get(\"accepted_units\") == accepted_units\n and receipt.get(\"canonical_head\") == canonical_head\n and canonical_head in accepted_units.values()\n for receipt in receipts\n )\n\n\ndef discover_resume_run(repo: str, plan_digest: str) -> tuple[str, list[dict]]:\n if not re.fullmatch(r\"[0-9a-f]{64}\", plan_digest):\n raise Operational(\"REFUSED\", \"plan digest must be a lowercase SHA-256 hex value\")\n ensure_root()\n info = repo_info(repo)\n candidates: list[dict] = []\n # A run recorded under the other candidate root (sandboxed vs unsandboxed\n # session) must still be discoverable; scan every candidate that exists.\n # Read-only: repairing a root this session cannot write (a leftover /tmp\n # tree under the sandbox) would abort discovery before the writable one.\n entries = []\n for root in candidate_runs_roots():\n if not os.path.isdir(root) or os.path.islink(root):\n continue\n entries.extend(os.scandir(root))\n for entry in sorted(entries, key=lambda row: row.path):\n if entry.name == \".locks\":\n continue\n if not entry.is_dir(follow_symlinks=False):\n raise TrustFailure(f\"unexpected non-directory entry in run root: {entry.path}\")\n if not SAFE_ID.fullmatch(entry.name) or not entry.name.strip(\".\"):\n raise TrustFailure(f\"unsafe run entry name: {entry.path}\")\n validate_private_dir(entry.path)\n doc = read_private_json(os.path.join(entry.path, \"manifest.json\"))\n if doc.get(\"schema_version\") != SCHEMA_VERSION or doc.get(\"run_id\") != entry.name:\n raise TrustFailure(f\"manifest schema or run identity mismatch: {entry.path}\")\n repository = doc.get(\"repository\")\n branch = doc.get(\"branch\")\n plan = doc.get(\"plan\")\n source = doc.get(\"source\")\n if not isinstance(repository, dict) or not isinstance(branch, dict) or not isinstance(plan, dict):\n raise TrustFailure(f\"manifest repository, branch, or plan record is malformed: {entry.path}\")\n if (\n repository.get(\"identity_digest\") != info[\"identity_digest\"]\n or repository.get(\"toplevel\") != info[\"toplevel\"]\n or repository.get(\"git_dir\") != info[\"git_dir\"]\n or branch.get(\"ref\") != info[\"branch_ref\"]\n ):\n continue\n if source is not None and not isinstance(source, dict):\n raise TrustFailure(f\"manifest source record is malformed: {entry.path}\")\n source_kind = source.get(\"kind\") if isinstance(source, dict) else plan.get(\"kind\", \"plan\")\n source_digest = source.get(\"digest\") if isinstance(source, dict) else plan.get(\"digest\")\n if source_kind != \"plan\" or source_digest != plan_digest:\n continue\n validate_source(doc)\n if unfinished_run(doc, info[\"head\"]):\n candidates.append({\n \"run_id\": entry.name,\n \"updated_at\": doc.get(\"updated_at\"),\n \"recovery_path\": entry.path,\n \"unit_states\": {uid: unit.get(\"state\") for uid, unit in doc[\"units\"].items()},\n })\n if not candidates:\n raise Operational(\"NOT_FOUND\", \"no unfinished run matches repository, branch, and plan digest\", {\"candidates\": []})\n if len(candidates) > 1:\n raise Operational(\"AMBIGUOUS\", \"multiple unfinished runs match; pass --run-id\", {\"candidates\": candidates})\n return candidates[0][\"run_id\"], candidates\n\n\ndef resolve_resume_run(args) -> str:\n if args.run_id:\n if args.repo or args.plan_digest:\n raise Operational(\"REFUSED\", \"resume accepts --run-id alone or both --repo and --plan-digest\")\n return safe_id(args.run_id, \"run id\")\n if not args.repo or not args.plan_digest:\n raise Operational(\"REFUSED\", \"resume requires --run-id or both --repo and --plan-digest\")\n run_id, _ = discover_resume_run(args.repo, args.plan_digest)\n return run_id\n\n\ndef retained_worker_blocker(run_id: str, unit_id: str, error: Operational) -> dict | None:\n if error.word != \"BLOCKED\" or str(error) != \"worker returned a host-resolvable blocker\":\n return None\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"].get(unit_id)\n if not unit or unit.get(\"state\") != \"authored\":\n return None\n attempt = find_attempt(unit)\n receipt = attempt.get(\"terminal_receipt\")\n if (\n attempt.get(\"process_state\") != \"done\"\n or attempt.get(\"terminal_validation_failure\") is not None\n or not isinstance(receipt, dict)\n or receipt.get(\"terminal_status\") != \"blocked\"\n ):\n return None\n blocker = {\n \"unit_id\": unit_id,\n \"terminal_status\": \"blocked\",\n \"summary\": receipt.get(\"summary\", \"\"),\n \"terminal_receipt\": receipt,\n \"recovery_path\": os.path.join(run_dir(run_id), \"units\", unit_id),\n }\n return blocker if error.detail == blocker else None\n\n\ndef resume_terminalize(run_id: str, unit_id: str) -> list[dict]:\n try:\n transport = terminalize(run_id, unit_id)\n except Operational as exc:\n blocker = retained_worker_blocker(run_id, unit_id, exc)\n if blocker is None:\n raise\n return [{\n \"unit_id\": unit_id,\n \"action\": \"worker-blocker-retained\",\n \"terminal_status\": blocker[\"terminal_status\"],\n \"summary\": blocker[\"summary\"],\n \"recovery_path\": blocker[\"recovery_path\"],\n }]\n return [{\"unit_id\": unit_id, \"action\": \"terminalized\", \"transport\": transport[\"commit\"]}]\n\n\ndef resume_monitor(run_id: str, unit_id: str) -> list[dict]:\n evidence = sync_job(run_id, unit_id)\n actions = [{\"unit_id\": unit_id, \"action\": \"monitored\", \"process_state\": evidence[\"process_state\"]}]\n if evidence[\"process_state\"] == \"done\":\n actions.extend(resume_terminalize(run_id, unit_id))\n return actions\n\n\ndef resolve_unit_recovery_blockers(run_id: str, unit_id: str, reason: str | None = None) -> None:\n with locked_manifest(run_id, write=True) as doc:\n resolved = 0\n for blocker in doc.get(\"blockers\", []):\n if (\n blocker.get(\"unit_id\") == unit_id\n and blocker.get(\"retain_integration_lock\") is True\n and (reason is None or blocker.get(\"reason\") == reason)\n and not blocker.get(\"resolved_at\")\n ):\n blocker[\"resolved_at\"] = now_iso()\n blocker[\"resolved_by\"] = \"resume\"\n resolved += 1\n if resolved:\n event(doc, \"recovery-blockers-resolved\", unit_id, {\"count\": resolved})\n\n\ndef plan_wide_verification_attempts(doc: dict) -> list[dict]:\n attempts = doc.get(\"verification_attempts\", [])\n if not isinstance(attempts, list) or any(not isinstance(attempt, dict) for attempt in attempts):\n raise TrustFailure(\"manifest plan-wide verification attempts are malformed\")\n for attempt in attempts:\n if (\n not isinstance(attempt.get(\"attempt_id\"), str)\n or not re.fullmatch(r\"[0-9a-f]{32}\", attempt[\"attempt_id\"])\n or attempt.get(\"status\") not in {\"pending\", \"receipt-recorded\"}\n or not isinstance(attempt.get(\"integration_lock_nonce\"), str)\n or not re.fullmatch(r\"[0-9a-f]{48}\", attempt[\"integration_lock_nonce\"])\n or not isinstance(attempt.get(\"lock_unit_id\"), str)\n or not SAFE_ID.fullmatch(attempt[\"lock_unit_id\"])\n ):\n raise TrustFailure(\"manifest plan-wide verification attempt identity or state is malformed\")\n return attempts\n\n\ndef pending_plan_wide_verification(doc: dict, lock: dict) -> dict | None:\n attempts = plan_wide_verification_attempts(doc)\n pending = [\n attempt for attempt in attempts\n if attempt.get(\"status\") == \"pending\"\n and attempt.get(\"integration_lock_nonce\") == lock.get(\"nonce\")\n and attempt.get(\"lock_unit_id\") == lock.get(\"unit_id\")\n ]\n if len(pending) > 1:\n raise TrustFailure(\"multiple pending plan-wide verification attempts share one integration lock\")\n return pending[0] if pending else None\n\n\ndef receipted_plan_wide_verification(doc: dict, lock: dict) -> dict | None:\n attempts = plan_wide_verification_attempts(doc)\n recorded = [\n attempt for attempt in attempts\n if attempt.get(\"status\") == \"receipt-recorded\"\n and attempt.get(\"integration_lock_nonce\") == lock.get(\"nonce\")\n and attempt.get(\"lock_unit_id\") == lock.get(\"unit_id\")\n ]\n if len(recorded) > 1:\n raise TrustFailure(\"multiple receipted plan-wide verification attempts share one integration lock\")\n if not recorded:\n return None\n evidence_digest = recorded[0].get(\"evidence_digest\")\n if not isinstance(evidence_digest, str) or not re.fullmatch(r\"[0-9a-f]{64}\", evidence_digest):\n raise TrustFailure(\"plan-wide verification attempt receipt digest is malformed\")\n verifications = doc.get(\"verifications\", [])\n if not isinstance(verifications, list) or any(not isinstance(receipt, dict) for receipt in verifications):\n raise TrustFailure(\"manifest verification receipts are malformed\")\n receipts = [\n receipt for receipt in verifications\n if receipt.get(\"evidence_digest\") == evidence_digest\n ]\n if len(receipts) != 1:\n raise TrustFailure(\"plan-wide verification receipt is missing or duplicated\")\n return recorded[0]\n\n\ndef plan_wide_blocker_retains_lock(doc: dict, lock: dict) -> bool:\n return any(\n blocker.get(\"unit_id\") is None\n and blocker.get(\"retain_integration_lock\") is True\n and blocker.get(\"integration_lock_nonce\") == lock.get(\"nonce\")\n and not blocker.get(\"resolved_at\")\n for blocker in doc.get(\"blockers\", [])\n )\n\n\ndef resume_finalize_committed(run_id: str, unit_id: str) -> list[dict]:\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"][unit_id]\n state = unit[\"state\"]\n lock = doc.get(\"integration_lock\")\n pending_plan_verification = pending_plan_wide_verification(doc, lock) if lock else None\n receipted_plan_verification = receipted_plan_wide_verification(doc, lock) if lock else None\n retained_plan_lock = bool(lock and plan_wide_blocker_retains_lock(doc, lock))\n wave_id = unit.get(\"wave\", {}).get(\"id\")\n cleanup = unit.get(\"cleanup\") or {}\n artifact_cleanup_complete = cleanup.get(\"artifact_cleanup\", {}).get(\"complete\") is True\n if state in {\"cleaned\", \"native-completed\"}:\n actions: list[dict] = []\n if (state == \"cleaned\" or cleanup) and not artifact_cleanup_complete:\n cmd_cleanup(SimpleNamespace(\n run_id=run_id,\n unit_id=unit_id,\n abandon=False,\n expect_transport=None,\n expect_job=None,\n ))\n actions.append({\"unit_id\": unit_id, \"action\": \"artifact-cleanup-reconciled\"})\n if lock and lock.get(\"unit_id\") == unit_id:\n if pending_plan_verification:\n raise Operational(\n \"BLOCKED\",\n \"pending plan-wide verification retains the canonical integration lock\",\n {\n \"unit_id\": unit_id,\n \"verification_attempt_id\": pending_plan_verification.get(\"attempt_id\"),\n \"retain_integration_lock\": True,\n },\n )\n if retained_plan_lock:\n raise Operational(\n \"BLOCKED\",\n \"plan-wide verification blocker retains the canonical integration lock\",\n {\"unit_id\": unit_id, \"retain_integration_lock\": True},\n )\n if state == \"native-completed\" and not receipted_plan_verification:\n raise Operational(\n \"BLOCKED\",\n \"native-completed unit retains the canonical integration lock without a plan-wide verification receipt\",\n {\"unit_id\": unit_id, \"retain_integration_lock\": True},\n )\n cmd_integration_release(SimpleNamespace(run_id=run_id, unit_id=unit_id, lock_token=lock[\"nonce\"]))\n actions.append({\"unit_id\": unit_id, \"action\": \"integration-release-reconciled\"})\n return actions\n canonical_record = unit.get(\"integration\", {}).get(\"canonical_commit\")\n canonical = canonical_record.get(\"commit\") if isinstance(canonical_record, dict) else None\n if state != \"committed\" or not canonical:\n raise Operational(\"BLOCKED\", \"committed-unit recovery lacks an accepted canonical commit\")\n if lock is None:\n lock_token = cmd_integration_acquire(SimpleNamespace(run_id=run_id, unit_id=unit_id, resume=False))[1][\"lock_token\"]\n elif lock.get(\"unit_id\") == unit_id:\n lock_token = lock[\"nonce\"]\n with locked_manifest(run_id) as doc:\n validate_lock(doc, unit_id, lock_token)\n else:\n raise Operational(\"BLOCKED\", \"another unit holds the canonical integration lock\")\n actions: list[dict] = []\n if wave_id:\n cmd_wave_advance(SimpleNamespace(\n run_id=run_id,\n unit_id=unit_id,\n lock_token=lock_token,\n canonical_commit=canonical,\n ))\n actions.append({\"unit_id\": unit_id, \"action\": \"wave-advance-reconciled\", \"commit\": canonical})\n cmd_cleanup(SimpleNamespace(\n run_id=run_id,\n unit_id=unit_id,\n abandon=False,\n expect_transport=None,\n expect_job=None,\n ))\n cmd_integration_release(SimpleNamespace(run_id=run_id, unit_id=unit_id, lock_token=lock_token))\n resolve_unit_recovery_blockers(run_id, unit_id)\n actions.append({\"unit_id\": unit_id, \"action\": \"committed-unit-finalized\", \"commit\": canonical})\n return actions\n\n\ndef cmd_resume(args) -> tuple[str, dict]:\n run_id = resolve_resume_run(args)\n actions: list[dict] = []\n with locked_manifest(run_id) as doc:\n validate_repo(doc)\n unit_ids = list(doc[\"units\"])\n claim = doc.get(\"integration_lock\")\n releasing = dict(claim) if isinstance(claim, dict) and claim.get(\"phase\") == \"releasing\" else None\n orphan_unit = None\n orphan_path = integration_lock_path(doc)\n if claim is None and os.path.lexists(orphan_path):\n orphan = read_integration_lock(orphan_path)\n candidate = orphan.get(\"unit_id\")\n if orphan.get(\"run_id\") != run_id or not isinstance(candidate, str) or candidate not in doc[\"units\"]:\n raise Operational(\n \"BLOCKED\",\n \"external integration lock does not belong to this run/unit\",\n {\"owner_run\": orphan.get(\"run_id\"), \"owner_unit\": candidate},\n )\n validated_lock_nonce(doc, candidate, orphan)\n orphan_unit = candidate\n if releasing:\n integration_release(run_id, releasing[\"unit_id\"], releasing[\"nonce\"])\n actions.append({\"unit_id\": releasing[\"unit_id\"], \"action\": \"integration-release-reconciled\"})\n if orphan_unit:\n cmd_integration_acquire(SimpleNamespace(\n run_id=run_id,\n unit_id=orphan_unit,\n resume=True,\n recover_only=True,\n ))\n actions.append({\"unit_id\": orphan_unit, \"action\": \"integration-lock-adopted\"})\n for uid in unit_ids:\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"][uid]\n state = unit[\"state\"]\n attempt = find_attempt(unit)\n lock = doc.get(\"integration_lock\")\n if state == \"queued\" and not attempt.get(\"job_id\"):\n matches = matching_runner_jobs(run_id, unit)\n if len(matches) > 1:\n raise Operational(\"AMBIGUOUS\", f\"multiple runner jobs match queued unit {uid}\")\n if len(matches) == 1:\n with locked_manifest(run_id, write=True) as current:\n current_unit = current[\"units\"][uid]\n current_attempt = find_attempt(current_unit)\n if current_attempt.get(\"job_id\") not in (None, matches[0]):\n raise Operational(\"AMBIGUOUS\", \"attempt was concurrently bound\")\n current_attempt[\"job_id\"] = matches[0]\n current_unit[\"state\"] = \"authoring\"\n event(current, \"job-adopted\", uid, {\"job_id\": matches[0]})\n actions.append({\"unit_id\": uid, \"action\": \"job-adopted\", \"job_id\": matches[0]})\n actions.extend(resume_monitor(run_id, uid))\n elif state == \"authoring\" and attempt.get(\"job_id\"):\n actions.extend(resume_monitor(run_id, uid))\n elif state == \"authored\":\n actions.extend(resume_terminalize(run_id, uid))\n elif state == \"restoring\" and lock and lock.get(\"unit_id\") == uid:\n exact = restore(run_id, uid, lock[\"nonce\"])\n if not exact:\n raise Operational(\"BLOCKED\", \"exact pre-fold preservation could not be proven\")\n integration_release(run_id, uid, lock[\"nonce\"])\n resolve_unit_recovery_blockers(\n run_id,\n uid,\n reason=\"integration failed and exact restoration could not be proven\",\n )\n actions.append({\n \"unit_id\": uid,\n \"action\": \"restored\",\n \"canonical_preserved\": True,\n \"integration_lock_released\": True,\n })\n elif state == \"preserved\" and lock and lock.get(\"unit_id\") == uid:\n validate_lock(doc, uid, lock[\"nonce\"])\n restore_evidence = unit.get(\"integration\", {}).get(\"restore\")\n pre_fold = unit.get(\"integration\", {}).get(\"pre_fold\")\n if (\n not isinstance(restore_evidence, dict)\n or restore_evidence.get(\"exact\") is not True\n or not isinstance(pre_fold, dict)\n or restore_evidence.get(\"snapshot\") != pre_fold\n ):\n raise Operational(\"BLOCKED\", \"preserved-unit recovery lacks exact restoration evidence\")\n if semantic_snapshot(doc[\"repository\"][\"toplevel\"]) != pre_fold:\n raise Operational(\"BLOCKED\", \"canonical checkout no longer matches the exact restored snapshot\")\n integration_release(run_id, uid, lock[\"nonce\"])\n resolve_unit_recovery_blockers(\n run_id,\n uid,\n reason=\"integration failed after exact restoration but lock release failed\",\n )\n actions.append({\"unit_id\": uid, \"action\": \"integration-release-reconciled\"})\n elif state == \"integration-pending\" and not unit[\"integration\"].get(\"pre_fold\") and lock and lock.get(\"unit_id\") == uid:\n validate_lock(doc, uid, lock[\"nonce\"])\n integration_release(run_id, uid, lock[\"nonce\"])\n actions.append({\"unit_id\": uid, \"action\": \"preflight-lock-released\"})\n elif state == \"integration-pending\" and unit[\"integration\"].get(\"pre_fold\") and lock and lock.get(\"unit_id\") == uid:\n validate_lock(doc, uid, lock[\"nonce\"])\n repo = doc[\"repository\"][\"toplevel\"]\n snap = semantic_snapshot(repo)\n if snap == unit[\"integration\"][\"pre_fold\"]:\n exact = restore(run_id, uid, lock[\"nonce\"])\n if not exact:\n raise Operational(\"BLOCKED\", \"exact pre-fold preservation could not be proven\")\n integration_release(run_id, uid, lock[\"nonce\"])\n actions.append({\n \"unit_id\": uid,\n \"action\": \"preflight-exact-state-recovered\",\n \"canonical_preserved\": True,\n \"integration_lock_released\": True,\n })\n else:\n if not matches_expected_apply(repo, unit, snap):\n raise Operational(\"BLOCKED\", \"canonical dirt does not match the expected in-flight transport; preserved for recovery\")\n with locked_manifest(run_id, write=True) as current:\n current_unit = current[\"units\"][uid]\n current_unit[\"state\"] = \"integrated\"\n current_unit[\"integration\"][\"applied\"] = {\n \"at\": now_iso(),\n \"post_index_tree\": snap[\"index_tree\"],\n \"status_sha256\": snap[\"status_sha256\"],\n \"reconciled\": True,\n }\n event(current, \"transport-apply-reconciled\", uid, {\"post_index_tree\": snap[\"index_tree\"]})\n actions.append({\"unit_id\": uid, \"action\": \"apply-reconciled\"})\n elif state in {\"integrated\", \"verified\"} and lock and lock.get(\"unit_id\") == uid:\n validate_lock(doc, uid, lock[\"nonce\"])\n commit = None\n if state == \"verified\":\n with locked_manifest(run_id) as current:\n commit = reconcile_commit(current, current[\"units\"][uid])\n if commit:\n with locked_manifest(run_id, write=True) as current:\n current[\"units\"][uid][\"integration\"][\"canonical_commit\"] = commit\n current[\"units\"][uid][\"state\"] = \"committed\"\n event(current, \"canonical-commit-reconciled\", uid, {\"commit\": commit[\"commit\"]})\n actions.append({\"unit_id\": uid, \"action\": \"commit-reconciled\", \"commit\": commit[\"commit\"]})\n actions.extend(resume_finalize_committed(run_id, uid))\n else:\n exact = restore(run_id, uid, lock[\"nonce\"])\n if not exact:\n raise Operational(\"BLOCKED\", \"exact pre-fold preservation could not be proven\")\n integration_release(run_id, uid, lock[\"nonce\"])\n actions.append({\n \"unit_id\": uid,\n \"action\": \"pre-commit-integration-restored\",\n \"interrupted_state\": state,\n \"canonical_preserved\": True,\n \"integration_lock_released\": True,\n })\n elif state in {\"committed\", \"cleaned\", \"native-completed\"}:\n actions.extend(resume_finalize_committed(run_id, uid))\n return \"RESUMED\", {\"run_id\": run_id, \"actions\": actions, \"redispatched\": False, \"applied\": False}\n\n\ndef fallback_basis(doc: dict, unit: dict) -> tuple[str, dict]:\n if unit.get(\"state\") == \"integration-pending\" and unit.get(\"transport\", {}).get(\"commit\"):\n raise Operational(\"REFUSED\", \"pinned worker transport must be reconciled rather than bypassed by fallback\")\n attempt = find_attempt(unit)\n process_state = attempt.get(\"process_state\")\n if process_state == \"done\" and attempt.get(\"terminal_validation_failure\"):\n validate_terminal_validation_failure(doc[\"run_id\"], unit, attempt)\n snap = semantic_snapshot(doc[\"repository\"][\"toplevel\"])\n allowed_heads = set(unit.get(\"wave\", {}).get(\"allowed_heads\", []))\n if (\n snap[\"head\"] not in allowed_heads\n and not dependency_advanced_head(doc, unit, snap[\"head\"])\n ) or not snap[\"status_empty\"] or snap[\"index_tree\"] != snap[\"head_tree\"]:\n raise Operational(\"BLOCKED\", \"canonical checkout diverged or is dirty; native fallback is not safe\")\n return \"terminal-validation-failure\", attempt\n if process_state in TERMINAL_PROCESS - {\"done\"} or (process_state == \"never-started\" and attempt.get(\"job_id\")):\n snap = semantic_snapshot(doc[\"repository\"][\"toplevel\"])\n allowed_heads = set(unit.get(\"wave\", {}).get(\"allowed_heads\", []))\n if (\n snap[\"head\"] not in allowed_heads\n and not dependency_advanced_head(doc, unit, snap[\"head\"])\n ) or not snap[\"status_empty\"] or snap[\"index_tree\"] != snap[\"head_tree\"]:\n raise Operational(\"BLOCKED\", \"canonical checkout diverged or is dirty; native fallback is not safe\")\n recorded = attempt.get(\"terminal_receipt\")\n if process_state == \"failed\" and isinstance(recorded, dict) and recorded.get(\"terminal_status\") in {\"unavailable\", \"failed\"}:\n reader = (\n unavailable_terminal_receipt\n if recorded[\"terminal_status\"] == \"unavailable\"\n else launched_failure_terminal_receipt\n )\n observed = reader(doc[\"run_id\"], unit, attempt)\n if observed != recorded:\n raise Operational(\"BLOCKED\", \"recorded failed receipt evidence changed\")\n return observed[\"failure_reason\"], attempt\n return str(attempt.get(\"fallback\", {}).get(\"reason\") or process_state), attempt\n restore_evidence = unit.get(\"integration\", {}).get(\"restore\")\n if unit.get(\"state\") == \"preserved\" and restore_evidence and restore_evidence.get(\"exact\") is True:\n if doc.get(\"integration_lock\"):\n raise Operational(\"REFUSED\", \"release the integration lock after exact restoration before fallback\")\n actual = semantic_snapshot(doc[\"repository\"][\"toplevel\"])\n expected = unit[\"integration\"].get(\"pre_fold\")\n if actual != expected:\n raise Operational(\"BLOCKED\", \"canonical checkout no longer matches the exact restored snapshot\")\n return \"canonical-attempt-preserved\", attempt\n if process_state == \"running\":\n raise Operational(\"REFUSED\", \"a live attempt still owns implementation; fallback is not authorized\")\n if process_state == \"done\":\n raise Operational(\"REFUSED\", \"successful worker output must be reconciled rather than bypassed by fallback\")\n raise Operational(\"REFUSED\", \"no authoritative terminal or exactly restored attempt authorizes fallback\")\n\n\ndef cmd_claim_fallback(args) -> tuple[str, dict]:\n # Refresh runner evidence first. A stale manifest cannot authorize native\n # work while a detached attempt may still be live.\n with locked_manifest(args.run_id) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit)\n should_sync = bool(attempt.get(\"job_id\")) and unit.get(\"state\") == \"authoring\"\n if should_sync:\n sync_job(args.run_id, args.unit_id)\n\n with locked_manifest(args.run_id, write=True) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit)\n fallback = attempt.setdefault(\"fallback\", {})\n fallback.setdefault(\"completed\", None)\n claimed = fallback.get(\"claimed\")\n if claimed:\n return \"FALLBACK_ALREADY_AUTHORIZED\", {\n \"unit_id\": args.unit_id,\n \"start_native\": False,\n \"reason\": claimed[\"reason\"],\n \"claim\": claimed,\n }\n validate_dependencies_ready(doc, unit)\n reason, attempt = fallback_basis(doc, unit)\n claim_snapshot = semantic_snapshot(doc[\"repository\"][\"toplevel\"])\n wave = unit.get(\"wave\", {})\n if wave.get(\"id\"):\n validate_wave_order(doc, unit)\n allowed_heads = wave.get(\"allowed_heads\", [])\n if not allowed_heads or (\n claim_snapshot[\"head\"] != allowed_heads[-1]\n and not dependency_advanced_head(doc, unit, claim_snapshot[\"head\"])\n ):\n raise Operational(\"BLOCKED\", \"native fallback must start from the latest recorded wave head\")\n mode = doc.get(\"binding\", {}).get(\"mode\")\n if mode not in {\"prefer\", \"require\"}:\n raise Operational(\"REFUSED\", f\"binding mode {mode!r} does not authorize native fallback\")\n claim = {\n \"at\": now_iso(),\n \"reason\": reason,\n \"caller_mode\": args.caller_mode,\n \"mode\": mode,\n \"canonical_head\": claim_snapshot[\"head\"],\n }\n fallback.update({\"eligible\": False, \"reason\": reason, \"claimed\": claim})\n event(doc, \"native-fallback-authorized\", args.unit_id, {\"reason\": reason, \"mode\": mode, \"caller_mode\": args.caller_mode})\n return \"FALLBACK_AUTHORIZED\", {\"unit_id\": args.unit_id, \"start_native\": True, \"reason\": reason, \"claim\": claim}\n\n\ndef validate_fallback_ancestry(doc: dict, unit: dict, accepted_head: str) -> None:\n required: list[dict] = []\n dependency_ids = set(unit.get(\"dependencies\", []))\n for dependency_id in unit.get(\"dependencies\", []):\n dependency = doc.get(\"units\", {}).get(dependency_id)\n accepted_commit = unit_accepted_commit(dependency) if isinstance(dependency, dict) else None\n if accepted_commit is None:\n raise Operational(\n \"BLOCKED\",\n \"unit dependency completion evidence changed before native fallback completion\",\n {\"unit_id\": unit[\"unit_id\"], \"dependency_id\": dependency_id},\n )\n required.append({\"kind\": \"dependency\", \"unit_id\": dependency_id, \"commit\": accepted_commit})\n\n wave = unit.get(\"wave\", {})\n if wave.get(\"id\"):\n wave_members(doc, unit)\n base = wave.get(\"base\")\n for head in wave.get(\"allowed_heads\", []):\n if head != base:\n required.append({\"kind\": \"wave-head\", \"commit\": head})\n\n represented_commits = {item[\"commit\"] for item in required}\n for accepted_unit_id in sorted(doc.get(\"units\", {})):\n if accepted_unit_id == unit[\"unit_id\"] or accepted_unit_id in dependency_ids:\n continue\n accepted_unit = doc[\"units\"][accepted_unit_id]\n accepted_commit = unit_accepted_commit(accepted_unit)\n if accepted_commit is None or accepted_commit in represented_commits:\n continue\n required.append({\"kind\": \"accepted-unit\", \"unit_id\": accepted_unit_id, \"commit\": accepted_commit})\n represented_commits.add(accepted_commit)\n\n missing = [\n item for item in required\n if git_text(\n doc[\"repository\"][\"toplevel\"], \"merge-base\", item[\"commit\"], accepted_head, check=False,\n ) != item[\"commit\"]\n ]\n if missing:\n raise Operational(\n \"BLOCKED\",\n \"accepted native fallback head does not contain every controller-accepted prerequisite\",\n {\"unit_id\": unit[\"unit_id\"], \"accepted_head\": accepted_head, \"missing_ancestry\": missing},\n )\n\n\ndef cmd_complete_fallback(args) -> tuple[str, dict]:\n if not re.fullmatch(r\"[0-9a-f]{64}\", args.evidence_digest):\n raise Operational(\"REFUSED\", \"native fallback evidence digest must be lowercase SHA-256 hex\")\n summary = args.summary.strip()\n if not summary or \"\\0\" in summary or len(summary.encode()) > 1024:\n raise Operational(\"REFUSED\", \"native fallback summary must be non-empty and at most 1024 bytes\")\n if not re.fullmatch(r\"[0-9a-f]{40}|[0-9a-f]{64}\", args.accepted_head):\n raise Operational(\"REFUSED\", \"native fallback accepted head must be a Git object id\")\n\n with locked_manifest(args.run_id, write=True) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit)\n fallback = attempt.get(\"fallback\")\n claim = fallback.get(\"claimed\") if isinstance(fallback, dict) else None\n if not isinstance(claim, dict):\n raise Operational(\"REFUSED\", \"native fallback completion requires an existing claim\")\n if fallback.get(\"completed\") is not None or unit.get(\"state\") == \"native-completed\":\n raise Operational(\"REFUSED\", \"native fallback completion was already recorded\")\n claim_mode = claim.get(\"mode\")\n if claim_mode not in {\"prefer\", \"require\"}:\n raise Operational(\"REFUSED\", \"native fallback completion requires an authorized prefer or require claim\")\n if doc.get(\"integration_lock\") is not None:\n raise Operational(\"REFUSED\", \"release the integration lock before completing native fallback\")\n\n repo = doc[\"repository\"][\"toplevel\"]\n snapshot = semantic_snapshot(repo)\n if snapshot.get(\"branch_ref\") != doc[\"branch\"][\"ref\"]:\n raise Operational(\"BLOCKED\", \"canonical branch changed before native fallback completion\")\n if snapshot.get(\"status_empty\") is not True:\n raise Operational(\"BLOCKED\", \"commit or restore canonical changes before completing native fallback\")\n accepted_commit = git_text(repo, \"rev-parse\", \"--verify\", f\"{args.accepted_head}^{{commit}}\", check=False)\n if accepted_commit != args.accepted_head or snapshot.get(\"head\") != args.accepted_head:\n raise Operational(\"BLOCKED\", \"accepted native fallback head does not match canonical HEAD\")\n base = unit.get(\"workspace\", {}).get(\"base\")\n if not isinstance(base, str) or git_text(repo, \"merge-base\", base, args.accepted_head, check=False) != base:\n raise Operational(\"BLOCKED\", \"accepted native fallback head does not descend from the recorded unit base\")\n validate_fallback_ancestry(doc, unit, args.accepted_head)\n\n wave = unit.get(\"wave\", {})\n changed_paths: list[str] = []\n advanced: list[str] = []\n if wave.get(\"id\"):\n validate_wave_order(doc, unit)\n claim_head = claim.get(\"canonical_head\")\n allowed_heads = wave.get(\"allowed_heads\", [])\n if (\n not isinstance(claim_head, str)\n or not allowed_heads\n or claim_head != allowed_heads[-1]\n or git_text(repo, \"merge-base\", claim_head, args.accepted_head, check=False) != claim_head\n ):\n raise Operational(\"BLOCKED\", \"native fallback completion does not extend the latest recorded wave head\")\n raw = git(repo, \"diff-tree\", \"-r\", \"-M\", \"--name-status\", \"-z\", claim_head, args.accepted_head)\n changed_paths = parse_diff_paths(raw)\n validate_wave_collisions(\n doc,\n unit,\n overrides={unit[\"unit_id\"]: set(changed_paths)},\n require_complete=False,\n )\n members = wave_members(doc, unit)\n validate_wave_advancement(members, unit, claim_head, args.accepted_head)\n\n receipt = {\n \"at\": now_iso(),\n \"base\": base,\n \"accepted_head\": args.accepted_head,\n \"evidence_digest\": args.evidence_digest,\n \"summary\": summary,\n \"snapshot\": snapshot,\n \"claim\": dict(claim),\n \"changed_paths\": changed_paths,\n }\n fallback[\"completed\"] = receipt\n unit[\"state\"] = \"native-completed\"\n if wave.get(\"id\"):\n advanced = advance_wave_allowed_heads(members, wave[\"position\"], args.accepted_head)\n event(doc, \"wave-advanced\", args.unit_id, {\n \"canonical_commit\": args.accepted_head,\n \"eligible_siblings\": advanced,\n })\n event(doc, \"native-fallback-completed\", args.unit_id, {\n \"accepted_head\": args.accepted_head,\n \"evidence_digest\": args.evidence_digest,\n })\n return \"FALLBACK_COMPLETED\", {\n \"unit_id\": args.unit_id,\n \"completion\": receipt,\n \"eligible_siblings\": advanced,\n }\n\n\ndef cmd_reap(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n attempt = find_attempt(unit)\n if not attempt.get(\"job_id\"):\n return \"REAPED\", {\"unit_id\": args.unit_id, \"process_state\": \"never-started\"}\n job_dir = runner_job_dir(args.run_id, attempt[\"job_id\"])\n runner = os.path.join(os.path.dirname(__file__), \"peer-job-runner.py\")\n proc = subprocess.run([sys.executable, runner, \"reap\", job_dir], capture_output=True, check=False)\n if proc.returncode not in (0,):\n raise Operational(\"BLOCKED\", f\"runner reap failed: {proc.stderr.decode('utf-8', 'replace').strip()}\")\n evidence = sync_job(args.run_id, args.unit_id)\n return \"REAPED\", {\"unit_id\": args.unit_id, **evidence, \"recovery_path\": os.path.join(run_dir(args.run_id), \"units\", args.unit_id)}\n\n\ndef remove_finalized_artifacts(run_id: str, unit_id: str) -> None:\n \"\"\"Prune bulky controller-owned artifacts only after a unit is finalized.\"\"\"\n with locked_manifest(run_id) as doc:\n unit = doc[\"units\"].get(unit_id)\n cleanup = unit.get(\"cleanup\") if unit else None\n if (\n not unit\n or unit.get(\"state\") not in {\"cleaned\", \"native-completed\"}\n or not isinstance(cleanup, dict)\n ):\n raise Operational(\"REFUSED\", \"artifact pruning requires a finalized unit with recorded cleanup\")\n attempt_job_ids = [attempt.get(\"job_id\") for attempt in unit.get(\"attempts\", []) if attempt.get(\"job_id\")]\n authorization_paths = [attempt.get(\"authorization_path\") for attempt in unit.get(\"attempts\", []) if attempt.get(\"authorization_path\")]\n packet_path = unit.get(\"packet\", {}).get(\"path\")\n result_dir = os.path.join(os.path.dirname(unit[\"workspace\"][\"path\"]), \"result\")\n root = run_dir(run_id)\n paths = [(packet_path, \"file\"), (result_dir, \"dir\")]\n paths.extend((authorization_path, \"file\") for authorization_path in authorization_paths)\n paths.extend((runner_job_dir(run_id, job_id), \"dir\") for job_id in attempt_job_ids)\n for candidate, kind in paths:\n if not candidate or not os.path.lexists(candidate):\n continue\n absolute = os.path.abspath(candidate)\n if os.path.commonpath([root, absolute]) != root or absolute == root:\n raise Operational(\"BLOCKED\", \"finalized artifact path escaped the owned run\")\n if kind == \"file\":\n read_private(absolute, MAX_PACKET_BYTES)\n os.unlink(absolute)\n else:\n validate_private_dir(absolute)\n shutil.rmtree(absolute)\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"][unit_id]\n unit[\"packet\"][\"retained\"] = False\n for attempt in unit.get(\"attempts\", []):\n attempt[\"bulky_artifacts_retained\"] = False\n attempt[\"authorization_retained\"] = False\n unit[\"cleanup\"][\"artifact_cleanup\"] = {\"at\": now_iso(), \"complete\": True}\n event(doc, \"finalized-artifacts-pruned\", unit_id, {\"job_count\": len(attempt_job_ids)})\n\n\ndef retained_blocked_abandonment_receipt(run_id: str, unit: dict, attempt: dict) -> dict:\n recorded = attempt.get(\"terminal_receipt\")\n if (\n unit.get(\"state\") != \"authored\"\n or attempt.get(\"process_state\") != \"done\"\n or attempt.get(\"terminal_validation_failure\") is not None\n or not isinstance(recorded, dict)\n or recorded.get(\"terminal_status\") != \"blocked\"\n ):\n raise Operational(\"REFUSED\", \"done output is not an exactly retained worker blocker\")\n observed_process = process_evidence(runner_job_dir(run_id, attempt[\"job_id\"]))[\"process_state\"]\n if observed_process != \"done\":\n raise Operational(\"BLOCKED\", \"retained worker-blocker job evidence changed\")\n observed_receipt = terminal_receipt(unit, attempt)\n if observed_receipt != recorded:\n raise Operational(\"BLOCKED\", \"retained worker-blocker receipt evidence changed\")\n return {\n \"kind\": \"retained-worker-blocker\",\n \"value\": attempt[\"job_id\"],\n \"process_state\": observed_process,\n \"terminal_status\": recorded[\"terminal_status\"],\n \"result_sha256\": recorded[\"result_sha256\"],\n \"raw_log_sha256\": recorded[\"raw_log_sha256\"],\n }\n\n\ndef owned_workspace_path(run_id: str, unit_id: str, recorded_workspace: str) -> str:\n unit_root = os.path.join(run_dir(run_id), \"units\", unit_id)\n expected_workspace = os.path.join(unit_root, \"workspace\")\n if os.path.abspath(recorded_workspace) != expected_workspace:\n raise TrustFailure(\"manifest workspace path does not match the controller-owned unit workspace\")\n validate_private_dir(unit_root)\n return expected_workspace\n\n\ndef remove_unregistered_owned_workspace(run_id: str, unit_id: str, recorded_workspace: str) -> None:\n expected_workspace = owned_workspace_path(run_id, unit_id, recorded_workspace)\n if not os.path.lexists(expected_workspace):\n return\n entry = os.lstat(expected_workspace)\n uid_getter = getattr(os, \"geteuid\", None) or getattr(os, \"getuid\", None)\n effective_uid = uid_getter() if uid_getter is not None else None\n if not stat.S_ISDIR(entry.st_mode) or stat.S_ISLNK(entry.st_mode):\n raise Operational(\"BLOCKED\", \"unregistered workspace path is not a real directory\")\n if effective_uid is not None and entry.st_uid != effective_uid:\n raise Operational(\"BLOCKED\", \"unregistered workspace is not owned by the current user\")\n shutil.rmtree(expected_workspace)\n if os.path.lexists(expected_workspace):\n raise Operational(\"BLOCKED\", \"unregistered workspace remained after cleanup\")\n\n\ndef cmd_cleanup(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(args.unit_id)\n if not unit:\n raise Operational(\"REFUSED\", \"unknown unit\")\n cleanup_recorded = isinstance(unit.get(\"cleanup\"), dict)\n if unit[\"state\"] == \"cleaned\" or (unit[\"state\"] == \"native-completed\" and cleanup_recorded):\n if not unit.get(\"cleanup\", {}).get(\"artifact_cleanup\", {}).get(\"complete\"):\n pass\n else:\n return \"CLEANED\", {\"unit_id\": args.unit_id, \"resumed\": True}\n if unit[\"state\"] == \"cleaned\" or (unit[\"state\"] == \"native-completed\" and cleanup_recorded):\n remove_finalized_artifacts(args.run_id, args.unit_id)\n return \"CLEANED\", {\"unit_id\": args.unit_id, \"resumed\": True}\n with locked_manifest(args.run_id) as doc:\n unit = doc[\"units\"][args.unit_id]\n attempt = find_attempt(unit)\n if attempt.get(\"process_state\") == \"running\":\n raise Operational(\"REFUSED\", \"cannot cleanup a live worker\")\n commit = unit[\"transport\"].get(\"commit\")\n abandonment_receipt = None\n if args.abandon:\n if commit:\n if args.expect_transport != commit:\n raise Operational(\"REFUSED\", \"abandon cleanup requires exact transport SHA\")\n abandonment_receipt = {\"kind\": \"transport\", \"value\": commit}\n else:\n terminal_failures = TERMINAL_PROCESS - {\"done\"}\n validation_failure = attempt.get(\"process_state\") == \"done\" and attempt.get(\"terminal_validation_failure\")\n if not attempt.get(\"job_id\"):\n raise Operational(\"REFUSED\", \"transport-free cleanup requires an authoritative failed or reaped job\")\n if args.expect_job != attempt[\"job_id\"]:\n raise Operational(\"REFUSED\", \"transport-free cleanup requires the exact terminal job id\")\n if validation_failure:\n validate_terminal_validation_failure(args.run_id, unit, attempt)\n abandonment_receipt = {\"kind\": \"terminal-validation-failure\", \"value\": attempt[\"job_id\"], \"process_state\": \"done\"}\n elif attempt.get(\"process_state\") == \"done\":\n abandonment_receipt = retained_blocked_abandonment_receipt(args.run_id, unit, attempt)\n else:\n if attempt.get(\"process_state\") not in terminal_failures:\n raise Operational(\"REFUSED\", \"transport-free cleanup requires an authoritative failed or reaped job\")\n observed = process_evidence(runner_job_dir(args.run_id, attempt[\"job_id\"]))[\"process_state\"]\n if observed != attempt[\"process_state\"] or observed not in terminal_failures:\n raise Operational(\"BLOCKED\", \"terminal job evidence changed; refusing cleanup\")\n abandonment_receipt = {\"kind\": \"terminal-job\", \"value\": attempt[\"job_id\"], \"process_state\": observed}\n elif unit[\"state\"] != \"committed\":\n raise Operational(\"REFUSED\", \"uncommitted output is retained unless explicitly abandoned\")\n workspace = unit[\"workspace\"][\"path\"]\n ref = unit[\"transport\"].get(\"ref\")\n repo = doc[\"repository\"][\"toplevel\"]\n common = doc[\"repository\"][\"common_dir\"]\n workspace = owned_workspace_path(args.run_id, args.unit_id, workspace)\n with locked_manifest(args.run_id, write=True) as doc:\n event(doc, \"cleanup-intent\", args.unit_id, {\"workspace\": workspace, \"ref\": ref, \"abandonment_receipt\": abandonment_receipt})\n with admin_lock(common):\n present = [r for r in worktree_rows(repo) if os.path.realpath(str(r.get(\"worktree\", \"\"))) == os.path.realpath(workspace)]\n if present:\n git(repo, \"worktree\", \"remove\", \"--force\", workspace)\n test_fault(\"cleanup-after-worktree-remove\")\n if any(os.path.realpath(str(r.get(\"worktree\", \"\"))) == os.path.realpath(workspace) for r in worktree_rows(repo)):\n raise Operational(\"BLOCKED\", \"worktree remained registered after cleanup\")\n remove_unregistered_owned_workspace(args.run_id, args.unit_id, workspace)\n if ref and commit:\n current = git_text(repo, \"rev-parse\", \"-q\", \"--verify\", ref, check=False)\n if current and current != commit:\n raise Operational(\"BLOCKED\", \"transport ref changed; refusing cleanup\")\n if current:\n git(repo, \"update-ref\", \"-d\", ref, commit)\n with locked_manifest(args.run_id, write=True) as doc:\n unit = doc[\"units\"][args.unit_id]\n finalized_state = \"native-completed\" if unit[\"state\"] == \"native-completed\" else \"cleaned\"\n unit[\"cleanup\"] = {\n \"at\": now_iso(),\n \"workspace_removed\": True,\n \"ref_removed\": True,\n \"abandoned\": bool(args.abandon),\n \"abandonment_receipt\": abandonment_receipt,\n \"artifact_cleanup\": {\"at\": None, \"complete\": False},\n }\n unit[\"state\"] = finalized_state\n event(doc, \"unit-cleaned\", args.unit_id)\n test_fault(\"cleanup-before-artifact-prune\")\n remove_finalized_artifacts(args.run_id, args.unit_id)\n return \"CLEANED\", {\"unit_id\": args.unit_id, \"resumed\": False}\n","content_type":"text/x-python; charset=utf-8","language":"python","size":50994,"content_sha256":"0b0d4ba5125f92f8441425c8c1fdfd7ba5577849dafce2fd90d17de39cf90a5d"},{"filename":"scripts/unit_workspace_state.py","content":"\"\"\"Private, crash-recoverable workspace controller for ce-work external units.\n\nThe generic peer-job runner owns process supervision. This controller owns the\nrepository-specific transaction: one private run manifest, detached sibling\nworktrees, complete-tree transport commits, canonical integration evidence,\nexact restoration, retention, and explicit cleanup. It never launches a model\nCLI and never commits a worker's output in the canonical checkout.\n\nEvery successful command prints a status word and one compact JSON document.\nTrust failures print only ``UNREADABLE`` and an error on stderr.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport base64\nimport contextlib\nimport fcntl\nimport hashlib\nimport json\nimport os\nimport re\nimport secrets\nimport shutil\nimport stat\nimport subprocess\nimport sys\nimport tempfile\nimport time\nfrom pathlib import Path\n\n\nSCHEMA_VERSION = 1\nPLAN_CHECKPOINT_MESSAGE = \"docs(ce-work): checkpoint selected implementation plan\"\n_uid_getter = getattr(os, \"geteuid\", None) or getattr(os, \"getuid\", None)\n_EFFECTIVE_UID = _uid_getter() if _uid_getter is not None else None\nOWNER_SCRATCH_ROOT = (\n os.path.join(\"/tmp\", f\"compound-engineering-{_EFFECTIVE_UID}\")\n if _EFFECTIVE_UID is not None\n else None\n)\nMAX_JSON_BYTES = 2 * 1024 * 1024\nMAX_PACKET_BYTES = 200_000\nSAFE_ID = re.compile(r\"^[A-Za-z0-9._-]{1,128}$\")\nO_NOFOLLOW = getattr(os, \"O_NOFOLLOW\", 0)\nO_DIRECTORY = getattr(os, \"O_DIRECTORY\", 0)\nTERMINAL_PROCESS = {\"done\", \"failed\", \"timeout\", \"died-without-result\"}\nINTEGRATABLE_STATES = {\"integration-pending\", \"integrated\", \"verified\"}\nUNIT_STATES = {\n \"queued\", \"authoring\", \"authored\", \"integration-pending\", \"integrated\",\n \"restoring\", \"verified\", \"committed\", \"preserved\", \"cleaned\", \"native-completed\",\n}\nGIT_LOCAL_ENV_VARS = frozenset({\n \"GIT_ALTERNATE_OBJECT_DIRECTORIES\",\n \"GIT_COMMON_DIR\",\n \"GIT_CONFIG\",\n \"GIT_CONFIG_COUNT\",\n \"GIT_CONFIG_PARAMETERS\",\n \"GIT_DIR\",\n \"GIT_GRAFT_FILE\",\n \"GIT_IMPLICIT_WORK_TREE\",\n \"GIT_INDEX_FILE\",\n # Listed by `git rev-parse --local-env-vars` on git \u003c 2.41 (e.g. Debian\n # bookworm's 2.39); dropped from the list by newer git. Scrub it so an\n # inherited value cannot leak into unit verification on old git.\n \"GIT_INTERNAL_SUPER_PREFIX\",\n \"GIT_NO_REPLACE_OBJECTS\",\n \"GIT_OBJECT_DIRECTORY\",\n \"GIT_PREFIX\",\n \"GIT_REPLACE_REF_BASE\",\n \"GIT_SHALLOW_FILE\",\n \"GIT_WORK_TREE\",\n})\n\n\nclass Operational(Exception):\n def __init__(self, word: str, message: str, detail: dict | None = None):\n super().__init__(message)\n self.word = word\n self.detail = detail or {}\n\n\nclass TrustFailure(Operational):\n def __init__(self, message: str):\n super().__init__(\"UNREADABLE\", message)\n\n\ndef now_iso() -> str:\n return time.strftime(\"%Y-%m-%dT%H:%M:%SZ\", time.gmtime())\n\n\ndef test_fault(point: str) -> None:\n \"\"\"Deterministic crash-window injection for the repository test suite.\"\"\"\n configured = {value.strip() for value in os.environ.get(\"CE_WORK_TEST_FAULT\", \"\").split(\",\") if value.strip()}\n if point in configured:\n raise Operational(\"INTERRUPTED\", f\"injected test interruption at {point}\")\n\n\ndef _private_root_usable(path: str) -> bool:\n \"\"\"True when `path` is (or can now be) a directory we own and can write into.\n\n Creation is the probe: a sandbox that denies writes under /tmp refuses the\n mkdir, and one that lets a pre-existing root stand still fails the access\n check, so both land on the fallback instead of failing at the first run.\n \"\"\"\n try:\n os.mkdir(path, 0o700)\n except FileExistsError:\n pass\n except OSError:\n return False\n try:\n st = os.lstat(path)\n except OSError:\n return False\n if not stat.S_ISDIR(st.st_mode):\n return False\n if _EFFECTIVE_UID is not None and st.st_uid != _EFFECTIVE_UID:\n return False\n return os.access(path, os.W_OK)\n\n\ndef _fallback_scratch_root() -> str:\n return os.path.join(os.environ.get(\"TMPDIR\") or \"/tmp\", f\"compound-engineering-{_EFFECTIVE_UID}\")\n\n\ndef owner_scratch_root() -> str:\n \"\"\"The owner-private scratch root, in the same candidate order as the skills' shell preamble.\"\"\"\n if OWNER_SCRATCH_ROOT is None:\n raise TrustFailure(\"effective user ID is unavailable; cannot derive the runs root\")\n if _private_root_usable(OWNER_SCRATCH_ROOT):\n return OWNER_SCRATCH_ROOT\n return _fallback_scratch_root()\n\n\ndef runs_root() -> str:\n configured = os.environ.get(\"CE_WORK_RUNS_ROOT\")\n if configured:\n return os.path.abspath(configured)\n peer_root = os.environ.get(\"CE_PEER_JOBS_ROOT\")\n if peer_root:\n return os.path.join(os.path.abspath(peer_root), \"ce-work\")\n return os.path.join(owner_scratch_root(), \"ce-work\")\n\n\ndef safe_id(value: str, label: str) -> str:\n if not SAFE_ID.fullmatch(value) or not value.strip(\".\"):\n raise Operational(\"REFUSED\", f\"unsafe {label}: {value!r}\")\n return value\n\n\ndef digest_bytes(data: bytes) -> str:\n return hashlib.sha256(data).hexdigest()\n\n\ndef _valid_git_object_id(value: object) -> bool:\n if not isinstance(value, str):\n return False\n try:\n raw = bytes.fromhex(value)\n except ValueError:\n return False\n return len(raw) in {20, 32} and raw.hex() == value\n\n\ndef _native_completion_commit(unit: dict) -> str | None:\n attempts = unit.get(\"attempts\")\n if not isinstance(attempts, list) or not attempts or not isinstance(attempts[-1], dict):\n return None\n fallback = attempts[-1].get(\"fallback\")\n if not isinstance(fallback, dict):\n return None\n claim = fallback.get(\"claimed\")\n completion = fallback.get(\"completed\")\n if not isinstance(claim, dict) or not isinstance(completion, dict) or completion.get(\"claim\") != claim:\n return None\n claim_mode = claim.get(\"mode\")\n if claim_mode not in {\"prefer\", \"require\"}:\n return None\n accepted_head = completion.get(\"accepted_head\")\n base = unit.get(\"workspace\", {}).get(\"base\")\n snapshot = completion.get(\"snapshot\")\n wave = unit.get(\"wave\", {})\n changed_paths = completion.get(\"changed_paths\")\n if not (\n _valid_git_object_id(accepted_head)\n and _valid_git_object_id(base)\n and completion.get(\"base\") == base\n and isinstance(completion.get(\"at\"), str)\n and bool(completion[\"at\"])\n and isinstance(completion.get(\"summary\"), str)\n and bool(completion[\"summary\"])\n and isinstance(completion.get(\"evidence_digest\"), str)\n and len(completion[\"evidence_digest\"]) == 64\n and _valid_git_object_id(completion[\"evidence_digest\"])\n and isinstance(snapshot, dict)\n and snapshot.get(\"head\") == accepted_head\n and snapshot.get(\"status_empty\") is True\n and snapshot.get(\"worktree_index_empty\") is True\n and _valid_git_object_id(snapshot.get(\"head_tree\"))\n and snapshot.get(\"head_tree\") == snapshot.get(\"index_tree\")\n and snapshot.get(\"status_sha256\") == digest_bytes(b\"\")\n and (\n not wave.get(\"id\")\n or (\n _valid_git_object_id(claim.get(\"canonical_head\"))\n and isinstance(changed_paths, list)\n and all(isinstance(path, str) for path in changed_paths)\n )\n )\n ):\n return None\n return accepted_head\n\n\ndef unit_accepted_commit(unit: dict) -> str | None:\n if unit.get(\"state\") == \"native-completed\":\n return _native_completion_commit(unit)\n if unit.get(\"state\") != \"cleaned\":\n return None\n integration = unit.get(\"integration\")\n if not isinstance(integration, dict):\n return None\n canonical = integration.get(\"canonical_commit\")\n if not (\n isinstance(canonical, dict)\n and all(_valid_git_object_id(canonical.get(field)) for field in (\"commit\", \"parent\", \"tree\"))\n and isinstance(canonical.get(\"at\"), str)\n and bool(canonical[\"at\"])\n ):\n return None\n return canonical[\"commit\"]\n\n\ndef unit_ready_for_run_verification(unit: object) -> bool:\n return isinstance(unit, dict) and unit_accepted_commit(unit) is not None\n\n\ndef accepted_unit_commit_snapshot(units: object) -> dict[str, str] | None:\n if not isinstance(units, dict):\n return None\n snapshot: dict[str, str] = {}\n for unit_id in sorted(units):\n if not isinstance(unit_id, str) or not SAFE_ID.fullmatch(unit_id):\n return None\n unit = units[unit_id]\n if not isinstance(unit, dict):\n return None\n commit = unit_accepted_commit(unit)\n if commit is None:\n return None\n snapshot[unit_id] = commit\n return snapshot\n\n\ndef _mode(st: os.stat_result) -> int:\n return stat.S_IMODE(st.st_mode)\n\n\ndef _euid() -> int | None:\n return _EFFECTIVE_UID\n\n\ndef validate_private_dir(path: str) -> None:\n try:\n fd = os.open(path, os.O_RDONLY | O_DIRECTORY | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open directory {path}: {exc}\") from exc\n try:\n st = os.fstat(fd)\n if not stat.S_ISDIR(st.st_mode):\n raise TrustFailure(f\"not a real directory: {path}\")\n if _euid() is not None and st.st_uid != _euid():\n raise TrustFailure(f\"directory is not owned by current user: {path}\")\n if _mode(st) != 0o700:\n raise TrustFailure(f\"directory mode is {_mode(st):04o}, expected 0700: {path}\")\n finally:\n os.close(fd)\n\n\ndef ensure_private_dir(path: str) -> None:\n try:\n os.mkdir(path, 0o700)\n except FileExistsError:\n pass\n validate_private_dir(path)\n\n\ndef _owner_root_for_runs(root: str) -> str | None:\n if OWNER_SCRATCH_ROOT is None:\n return None\n for candidate in (OWNER_SCRATCH_ROOT, _fallback_scratch_root()):\n owner_root = os.path.abspath(candidate)\n try:\n if os.path.commonpath([owner_root, os.path.abspath(root)]) == owner_root:\n return owner_root\n except ValueError: # different drives on Windows: not under this candidate\n continue\n return None\n\n\ndef _ensure_owner_scratch_root(path: str) -> None:\n try:\n os.mkdir(path, 0o700)\n except FileExistsError:\n pass\n try:\n fd = os.open(path, os.O_RDONLY | O_DIRECTORY | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open owner scratch root {path}: {exc}\") from exc\n try:\n current = os.fstat(fd)\n if not stat.S_ISDIR(current.st_mode):\n raise TrustFailure(f\"owner scratch root is not a real directory: {path}\")\n if _euid() is not None and current.st_uid != _euid():\n raise TrustFailure(f\"owner scratch root is not owned by current user: {path}\")\n if _mode(current) != 0o700:\n os.fchmod(fd, 0o700)\n repaired = os.fstat(fd)\n if repaired.st_uid != current.st_uid or _mode(repaired) != 0o700:\n raise TrustFailure(f\"could not repair owner scratch root mode to 0700: {path}\")\n finally:\n os.close(fd)\n\n\ndef ensure_root() -> str:\n return ensure_runs_root(runs_root())\n\n\ndef ensure_runs_root(root: str) -> str:\n \"\"\"Create or verify one runs root (the creation root, or the other candidate\n root an existing run was found under) and its private lock directory.\"\"\"\n owner_root = _owner_root_for_runs(root)\n if owner_root is not None:\n _ensure_owner_scratch_root(owner_root)\n parent = os.path.dirname(root)\n # The configured root's ancestors are caller-controlled; the private root\n # itself and everything below it are the durable confidentiality boundary.\n os.makedirs(parent, mode=0o700, exist_ok=True)\n ensure_private_dir(root)\n ensure_private_dir(os.path.join(root, \".locks\"))\n return root\n\n\ndef read_private(path: str, cap: int = MAX_JSON_BYTES) -> bytes:\n try:\n fd = os.open(path, os.O_RDONLY | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open state file {path}: {exc}\") from exc\n try:\n st = os.fstat(fd)\n if not stat.S_ISREG(st.st_mode):\n raise TrustFailure(f\"state is not a regular file: {path}\")\n if _euid() is not None and st.st_uid != _euid():\n raise TrustFailure(f\"state is not owned by current user: {path}\")\n if _mode(st) != 0o600:\n raise TrustFailure(f\"state mode is {_mode(st):04o}, expected 0600: {path}\")\n if st.st_size > cap:\n raise TrustFailure(f\"state exceeds {cap}-byte limit: {path}\")\n out = bytearray()\n while len(out) \u003c= cap:\n part = os.read(fd, min(65536, cap + 1 - len(out)))\n if not part:\n break\n out.extend(part)\n if len(out) > cap:\n raise TrustFailure(f\"state grew beyond {cap}-byte limit: {path}\")\n return bytes(out)\n finally:\n os.close(fd)\n\n\ndef stat_private_file(path: str) -> os.stat_result:\n \"\"\"Validate a private file by descriptor without consuming its content.\"\"\"\n try:\n fd = os.open(path, os.O_RDONLY | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open state file {path}: {exc}\") from exc\n try:\n st = os.fstat(fd)\n if not stat.S_ISREG(st.st_mode):\n raise TrustFailure(f\"state is not a regular file: {path}\")\n if _euid() is not None and st.st_uid != _euid():\n raise TrustFailure(f\"state is not owned by current user: {path}\")\n if _mode(st) != 0o600:\n raise TrustFailure(f\"state mode is {_mode(st):04o}, expected 0600: {path}\")\n return st\n finally:\n os.close(fd)\n\n\ndef read_private_json(path: str) -> dict:\n try:\n value = json.loads(read_private(path))\n except TrustFailure:\n raise\n except (ValueError, UnicodeDecodeError) as exc:\n raise TrustFailure(f\"malformed JSON state: {path}\") from exc\n if not isinstance(value, dict):\n raise TrustFailure(f\"JSON state is not an object: {path}\")\n return value\n\n\ndef create_private(path: str, data: bytes) -> None:\n try:\n fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | O_NOFOLLOW, 0o600)\n except OSError as exc:\n raise Operational(\"BLOCKED\", f\"cannot exclusively create {path}: {exc}\") from exc\n try:\n os.write(fd, data)\n os.fsync(fd)\n finally:\n os.close(fd)\n\n\ndef atomic_private_json(path: str, doc: dict) -> None:\n data = (json.dumps(doc, sort_keys=True, separators=(\",\", \":\")) + \"\\n\").encode()\n if len(data) > MAX_JSON_BYTES:\n raise Operational(\"BLOCKED\", \"manifest exceeds bounded state size\")\n parent = os.path.dirname(path)\n fd, tmp = tempfile.mkstemp(prefix=\".manifest-\", dir=parent)\n try:\n os.fchmod(fd, 0o600)\n with os.fdopen(fd, \"wb\", closefd=True) as stream:\n stream.write(data)\n stream.flush()\n os.fsync(stream.fileno())\n os.replace(tmp, path)\n dfd = os.open(parent, os.O_RDONLY | O_DIRECTORY | O_NOFOLLOW)\n try:\n os.fsync(dfd)\n finally:\n os.close(dfd)\n except BaseException:\n with contextlib.suppress(OSError):\n os.unlink(tmp)\n raise\n\n\ndef candidate_runs_roots() -> list:\n \"\"\"Every root an existing run may live under (configured root alone, or the\n /tmp root and the $TMPDIR fallback, primary first). Creation uses runs_root();\n lookup must not depend on which root this invocation would create under.\"\"\"\n configured = os.environ.get(\"CE_WORK_RUNS_ROOT\")\n if configured:\n return [os.path.abspath(configured)]\n peer_root = os.environ.get(\"CE_PEER_JOBS_ROOT\")\n if peer_root:\n return [os.path.join(os.path.abspath(peer_root), \"ce-work\")]\n if OWNER_SCRATCH_ROOT is None:\n raise TrustFailure(\"effective user ID is unavailable; cannot derive the runs root\")\n roots = [os.path.join(os.path.abspath(OWNER_SCRATCH_ROOT), \"ce-work\")]\n fallback = os.path.join(os.path.abspath(_fallback_scratch_root()), \"ce-work\")\n if fallback not in roots:\n roots.append(fallback)\n return roots\n\n\ndef run_dir(run_id: str) -> str:\n rid = safe_id(run_id, \"run id\")\n for root in candidate_runs_roots():\n existing = os.path.join(root, rid)\n if os.path.isdir(existing) and not os.path.islink(existing):\n return existing\n return os.path.join(runs_root(), rid)\n\n\[email protected]\ndef locked_manifest(run_id: str, write: bool = False):\n run_id = safe_id(run_id, \"run id\")\n rd = run_dir(run_id)\n ensure_runs_root(os.path.dirname(rd))\n validate_private_dir(rd)\n lock_path = os.path.join(rd, \"manifest.lock\")\n try:\n fd = os.open(lock_path, os.O_RDWR | O_NOFOLLOW)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely open manifest lock: {exc}\") from exc\n try:\n st = os.fstat(fd)\n if not stat.S_ISREG(st.st_mode) or (_euid() is not None and st.st_uid != _euid()) or _mode(st) != 0o600:\n raise TrustFailure(\"manifest lock owner/type/mode validation failed\")\n fcntl.flock(fd, fcntl.LOCK_EX if write else fcntl.LOCK_SH)\n doc = read_private_json(os.path.join(rd, \"manifest.json\"))\n if doc.get(\"schema_version\") != SCHEMA_VERSION or doc.get(\"run_id\") != run_id:\n raise TrustFailure(\"manifest schema or run identity mismatch\")\n before = json.dumps(doc, sort_keys=True, separators=(\",\", \":\"))\n yield doc\n after = json.dumps(doc, sort_keys=True, separators=(\",\", \":\"))\n if write and after != before:\n doc[\"revision\"] = int(doc.get(\"revision\", 0)) + 1\n doc[\"updated_at\"] = now_iso()\n atomic_private_json(os.path.join(rd, \"manifest.json\"), doc)\n finally:\n with contextlib.suppress(OSError):\n fcntl.flock(fd, fcntl.LOCK_UN)\n os.close(fd)\n\n\ndef sanitized_git_environment(overrides: dict | None = None) -> dict[str, str]:\n process_env = {key: value for key, value in os.environ.items() if key not in GIT_LOCAL_ENV_VARS}\n process_env.update(overrides or {})\n return process_env\n\n\ndef git(repo: str, *args: str, input_data: bytes | None = None, check: bool = True, env: dict | None = None) -> bytes:\n proc = subprocess.run(\n [\"git\", \"-C\", repo, *args], input=input_data, capture_output=True,\n env=sanitized_git_environment(env), check=False,\n )\n if check and proc.returncode != 0:\n message = proc.stderr.decode(\"utf-8\", \"replace\").strip()\n raise Operational(\"BLOCKED\", f\"git {' '.join(args)} failed: {message}\")\n return proc.stdout\n\n\ndef git_text(repo: str, *args: str, check: bool = True) -> str:\n return git(repo, *args, check=check).decode(\"utf-8\", \"surrogateescape\").strip()\n\n\ndef commit_index_tree(repo: str, message: str) -> str:\n \"\"\"Commit the verified index directly, without invoking repository hooks.\"\"\"\n if not message.strip() or \"\\0\" in message:\n raise Operational(\"REFUSED\", \"commit message must be non-empty and contain no NUL\")\n parent = git_text(repo, \"rev-parse\", \"HEAD\")\n branch_ref = git_text(repo, \"symbolic-ref\", \"-q\", \"HEAD\")\n tree = git_text(repo, \"write-tree\")\n commit = git(\n repo,\n \"commit-tree\", tree, \"-p\", parent,\n input_data=f\"{message.rstrip()}\\n\".encode(\"utf-8\"),\n ).decode(\"ascii\", \"strict\").strip()\n git(repo, \"update-ref\", branch_ref, commit, parent)\n return commit\n\n\ndef repo_info(repo: str) -> dict:\n repo = os.path.realpath(repo)\n top = os.path.realpath(git_text(repo, \"rev-parse\", \"--show-toplevel\"))\n if top != repo:\n repo = top\n branch = git_text(repo, \"symbolic-ref\", \"-q\", \"HEAD\", check=False)\n if not branch:\n raise Operational(\"REFUSED\", \"canonical checkout must be on a branch\")\n git_dir = os.path.realpath(git_text(repo, \"rev-parse\", \"--path-format=absolute\", \"--absolute-git-dir\"))\n common = os.path.realpath(git_text(repo, \"rev-parse\", \"--path-format=absolute\", \"--git-common-dir\"))\n st = os.stat(common)\n roots = sorted(git_text(repo, \"rev-list\", \"--max-parents=0\", \"HEAD\").splitlines())\n identity = digest_bytes((common + f\"\\0{st.st_dev}\\0{st.st_ino}\\0\" + \"\\n\".join(roots)).encode())\n return {\n \"toplevel\": repo,\n \"git_dir\": git_dir,\n \"common_dir\": common,\n \"common_dev\": st.st_dev,\n \"common_ino\": st.st_ino,\n \"identity_digest\": identity,\n \"branch_ref\": branch,\n \"head\": git_text(repo, \"rev-parse\", \"HEAD\"),\n \"head_tree\": git_text(repo, \"rev-parse\", \"HEAD^{tree}\"),\n }\n\n\ndef validate_source(doc: dict) -> None:\n source = doc.get(\"source\")\n if source is not None:\n if not isinstance(source, dict):\n raise TrustFailure(\"manifest source record is malformed\")\n kind = source.get(\"kind\")\n if kind == \"prompt\":\n if source.get(\"storage\") != \"run\" or source.get(\"path\") != \"source/bare-prompt.md\":\n raise TrustFailure(\"prompt source location is malformed\")\n if not isinstance(source.get(\"digest\"), str) or not re.fullmatch(r\"[0-9a-f]{64}\", source[\"digest\"]):\n raise TrustFailure(\"prompt source digest is malformed\")\n data = read_private(os.path.join(run_dir(doc[\"run_id\"]), source[\"path\"]), MAX_PACKET_BYTES)\n if digest_bytes(data) != source.get(\"digest\"):\n raise TrustFailure(\"prompt source digest does not match private content\")\n elif kind == \"plan\":\n if source.get(\"storage\") != \"repository\" or not isinstance(source.get(\"path\"), str):\n raise TrustFailure(\"plan source location is malformed\")\n if not isinstance(source.get(\"digest\"), str) or not re.fullmatch(r\"[0-9a-f]{64}\", source[\"digest\"]):\n raise TrustFailure(\"plan source digest is malformed\")\n else:\n raise TrustFailure(\"manifest source kind is invalid\")\n\n\ndef validate_repo(doc: dict) -> dict:\n validate_source(doc)\n recorded = doc[\"repository\"]\n current = repo_info(recorded[\"toplevel\"])\n for key in (\"toplevel\", \"git_dir\", \"common_dir\", \"common_dev\", \"common_ino\", \"identity_digest\"):\n if current[key] != recorded[key]:\n raise Operational(\"BLOCKED\", f\"canonical repository identity changed ({key})\")\n if current[\"branch_ref\"] != doc[\"branch\"][\"ref\"]:\n raise Operational(\"BLOCKED\", \"canonical branch changed\")\n return current\n\n\ndef resolve_plan(repo: str, plan: str) -> tuple[str, str]:\n supplied = os.path.abspath(plan if os.path.isabs(plan) else os.path.join(repo, plan))\n try:\n st = os.lstat(supplied)\n except OSError as exc:\n raise Operational(\"REFUSED\", f\"selected plan is missing: {exc}\") from exc\n if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode):\n raise Operational(\"REFUSED\", \"selected plan must be one regular non-symlink file\")\n # OS temp roots may themselves be compatibility symlinks (macOS /var ->\n # /private/var). Reject a symlink at the selected file, then compare the\n # resolved file against the already-resolved canonical repository.\n absolute = os.path.realpath(supplied)\n if os.path.commonpath([repo, absolute]) != repo:\n raise Operational(\"REFUSED\", \"plan must be inside the canonical repository\")\n return absolute, os.path.relpath(absolute, repo)\n\n\ndef parse_json_arg(raw: str, label: str) -> dict:\n try:\n value = json.loads(raw)\n except ValueError as exc:\n raise Operational(\"REFUSED\", f\"invalid {label} JSON\") from exc\n if not isinstance(value, dict):\n raise Operational(\"REFUSED\", f\"{label} must be a JSON object\")\n return value\n\n\nROUTE_CONTRACTS = {\n \"codex\": {\"target\": \"codex\", \"harness\": \"codex\", \"intermediaries\": [], \"default_model\": \"auto\", \"restriction_posture\": \"cooperative\"},\n \"claude\": {\"target\": \"claude\", \"harness\": \"claude\", \"intermediaries\": [], \"default_model\": \"auto\", \"restriction_posture\": \"cooperative\"},\n \"grok-cli\": {\"target\": \"grok\", \"harness\": \"grok\", \"intermediaries\": [], \"default_model\": \"auto\", \"restriction_posture\": \"cooperative\"},\n \"cursor\": {\"target\": \"cursor\", \"harness\": \"cursor-agent\", \"intermediaries\": [], \"default_model\": \"auto\", \"restriction_posture\": \"cooperative\"},\n \"composer\": {\"target\": \"composer\", \"harness\": \"cursor-agent\", \"intermediaries\": [\"cursor\"], \"default_model\": \"composer-2.5[fast=true]\", \"restriction_posture\": \"cooperative\"},\n \"grok-cursor\": {\"target\": \"grok\", \"harness\": \"cursor-agent\", \"intermediaries\": [\"cursor\"], \"default_model\": \"grok-4.7[context=256k,reasoning_effort=high,fast=true]\", \"restriction_posture\": \"cooperative\"},\n \"opencode\": {\"target\": \"opencode\", \"harness\": \"opencode\", \"intermediaries\": [], \"default_model\": \"auto\", \"restriction_posture\": \"cooperative\"},\n \"antigravity\": {\"target\": \"antigravity\", \"harness\": \"antigravity\", \"intermediaries\": [], \"default_model\": \"gemini-4-argon\", \"restriction_posture\": \"cooperative\"},\n}\n# Cursor's ACP model ids may carry a bracketed preset; route families apply to\n# the id before the bracket.\nCURSOR_MODEL = re.compile(r\"([A-Za-z0-9][A-Za-z0-9._:/-]*)(?:\\[[A-Za-z0-9._=,:-]*\\])?\")\n\n\ndef route_model_allowed(route: str, model: str) -> bool:\n if route in {\"cursor\", \"composer\", \"grok-cursor\"}:\n match = CURSOR_MODEL.fullmatch(model)\n if not match:\n return False\n base = match.group(1)\n if route == \"composer\":\n return bool(re.fullmatch(r\"composer-[A-Za-z0-9._-]+\", base))\n if route == \"grok-cursor\":\n return bool(re.fullmatch(r\"(?:cursor-)?grok-[A-Za-z0-9._-]+\", base))\n lowered = base.lower()\n return not (lowered in {\"composer\", \"grok\"} or lowered.startswith((\"composer-\", \"grok-\", \"cursor-grok-\")))\n if not re.fullmatch(r\"[A-Za-z0-9][A-Za-z0-9._:/-]*\", model):\n return False\n if route == \"codex\":\n return model == \"auto\" or bool(re.fullmatch(r\"(?:gpt-[A-Za-z0-9._-]+|o[0-9][A-Za-z0-9._-]*)\", model))\n if route == \"claude\":\n return model in {\"auto\", \"fable\", \"opus\", \"sonnet\", \"haiku\"} or bool(re.fullmatch(r\"claude-[A-Za-z0-9._-]+\", model))\n if route == \"grok-cli\":\n return model == \"auto\" or bool(re.fullmatch(r\"grok-[A-Za-z0-9._-]+\", model))\n if route == \"opencode\":\n return model == \"auto\" or bool(re.fullmatch(r\"[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9._-]+\", model))\n if route == \"antigravity\":\n # Antigravity also serves Claude and gpt-oss models; this route exists for Gemini.\n return bool(re.fullmatch(r\"gemini-[A-Za-z0-9._-]+\", model))\n return False\n\n\nEFFORT_TOKEN = re.compile(r\"[A-Za-z0-9][A-Za-z0-9_-]{0,31}\")\n\n\ndef fixed_route_contract(binding: dict, egress: dict, word: str = \"BLOCKED\") -> dict:\n if not isinstance(binding, dict) or not isinstance(egress, dict):\n raise Operational(word, \"run binding or egress sanction is malformed\")\n expected_binding_fields = {\"mode\", \"target\", \"model\", \"source\"}\n if set(binding) != expected_binding_fields:\n raise Operational(word, \"binding must contain exactly mode, target, model, and source\")\n if binding.get(\"mode\") not in {\"prefer\", \"require\"}:\n raise Operational(word, \"binding mode must be 'prefer' or 'require'\")\n source = binding.get(\"source\")\n if not isinstance(source, str) or not source or \"\\0\" in source or len(source.encode()) > 256:\n raise Operational(word, \"binding source must be a non-empty string of at most 256 bytes\")\n route = egress.get(\"route\")\n contract = ROUTE_CONTRACTS.get(route)\n if not contract:\n allowed = \", \".join(ROUTE_CONTRACTS)\n raise Operational(word, f\"unsupported egress route {route!r}; expected one of: {allowed}\")\n if binding.get(\"target\") != contract[\"target\"]:\n raise Operational(word, \"binding target does not match the sanctioned fixed route\")\n intermediaries = egress.get(\"intermediaries\")\n if intermediaries != contract[\"intermediaries\"]:\n raise Operational(word, \"egress intermediaries do not match the fixed route\")\n model = binding.get(\"model\")\n if model is not None and (not isinstance(model, str) or not model):\n raise Operational(word, \"binding model must be null or a non-empty string\")\n requested_model = model or contract[\"default_model\"]\n if not route_model_allowed(route, requested_model):\n raise Operational(word, \"binding model is not compatible with the sanctioned fixed route\")\n restrictions = egress.get(\"restrictions\", [])\n if not isinstance(restrictions, list) or not all(isinstance(item, str) for item in restrictions):\n raise Operational(word, \"egress restrictions must be a string list\")\n effort = egress.get(\"effort\")\n if effort is not None and (not isinstance(effort, str) or not EFFORT_TOKEN.fullmatch(effort)):\n raise Operational(word, \"egress effort must be a short plain token\")\n return contract\n\n\ndef attempt_authorization(\n doc: dict,\n activity_posture: str,\n unit_id: str,\n attempt_id: str,\n packet_digest: str,\n) -> dict:\n binding = doc.get(\"binding\")\n egress = doc.get(\"egress\")\n contract = fixed_route_contract(binding, egress)\n route = egress.get(\"route\")\n intermediaries = egress.get(\"intermediaries\")\n model = binding.get(\"model\")\n restrictions = egress.get(\"restrictions\", [])\n authorization = {\n \"schema_version\": 1,\n \"run_id\": doc[\"run_id\"],\n \"unit_id\": unit_id,\n \"attempt_id\": attempt_id,\n \"route\": route,\n \"target\": contract[\"target\"],\n \"harness\": contract[\"harness\"],\n \"intermediaries\": list(contract[\"intermediaries\"]),\n \"model_requested\": model or contract[\"default_model\"],\n \"restriction_posture\": contract[\"restriction_posture\"],\n \"restrictions\": list(restrictions),\n \"activity_posture\": activity_posture,\n \"packet_digest\": packet_digest,\n }\n # Present only when requested, so an unset run keeps the original key set.\n if egress.get(\"effort\") is not None:\n authorization[\"effort_requested\"] = egress[\"effort\"]\n return authorization\n\n\ndef read_external_packet(path: str, label: str = \"unit packet\") -> bytes:\n supplied = os.path.abspath(path)\n try:\n fd = os.open(supplied, os.O_RDONLY | O_NOFOLLOW)\n except OSError as exc:\n raise Operational(\"REFUSED\", f\"cannot safely open {label}: {exc}\") from exc\n try:\n st = os.fstat(fd)\n if not stat.S_ISREG(st.st_mode):\n raise Operational(\"REFUSED\", f\"{label} must be one regular non-symlink file\")\n if st.st_size > MAX_PACKET_BYTES:\n raise Operational(\"REFUSED\", f\"{label} exceeds {MAX_PACKET_BYTES}-byte limit\")\n data = bytearray()\n while len(data) \u003c= MAX_PACKET_BYTES:\n part = os.read(fd, min(65536, MAX_PACKET_BYTES + 1 - len(data)))\n if not part:\n break\n data.extend(part)\n if len(data) > MAX_PACKET_BYTES:\n raise Operational(\"REFUSED\", f\"{label} exceeds {MAX_PACKET_BYTES}-byte limit\")\n return bytes(data)\n finally:\n os.close(fd)\n\n\ndef event(doc: dict, kind: str, unit_id: str | None = None, detail: dict | None = None) -> None:\n row = {\"at\": now_iso(), \"kind\": kind}\n if unit_id is not None:\n row[\"unit_id\"] = unit_id\n if detail:\n row[\"detail\"] = detail\n doc.setdefault(\"events\", []).append(row)\n\n\ndef cmd_init(args) -> tuple[str, dict]:\n ensure_root()\n rid = safe_id(args.run_id, \"run id\")\n info = repo_info(args.repo)\n if args.plan:\n if not args.plan_digest or args.prompt_digest:\n raise Operational(\"REFUSED\", \"plan source requires only --plan-digest\")\n plan_abs, plan_rel = resolve_plan(info[\"toplevel\"], args.plan)\n source_bytes = Path(plan_abs).read_bytes()\n source_kind = \"plan\"\n supplied_digest = args.plan_digest\n source_record = {\n \"kind\": source_kind,\n \"storage\": \"repository\",\n \"path\": plan_rel,\n \"digest\": digest_bytes(source_bytes),\n }\n else:\n if not args.prompt_digest or args.plan_digest:\n raise Operational(\"REFUSED\", \"prompt source requires only --prompt-digest\")\n prompt_abs = os.path.realpath(os.path.abspath(args.prompt_brief))\n if os.path.commonpath([info[\"toplevel\"], prompt_abs]) == info[\"toplevel\"]:\n raise Operational(\"REFUSED\", \"prompt brief must be outside the canonical repository\")\n source_bytes = read_external_packet(args.prompt_brief, \"prompt brief\")\n source_kind = \"prompt\"\n supplied_digest = args.prompt_digest\n source_record = {\n \"kind\": source_kind,\n \"storage\": \"run\",\n \"path\": \"source/bare-prompt.md\",\n \"digest\": digest_bytes(source_bytes),\n }\n actual_digest = source_record[\"digest\"]\n if actual_digest != supplied_digest:\n raise Operational(\"REFUSED\", f\"selected {source_kind} digest does not match content\")\n binding = parse_json_arg(args.binding_json, \"binding\")\n egress = parse_json_arg(args.egress_json, \"egress\")\n fixed_route_contract(binding, egress, \"REFUSED\")\n rd = run_dir(rid)\n try:\n os.mkdir(rd, 0o700)\n except FileExistsError:\n try:\n existing = os.lstat(rd)\n except OSError as exc:\n raise TrustFailure(f\"cannot safely inspect run directory {rd}: {exc}\") from exc\n if stat.S_ISDIR(existing.st_mode) and not os.path.lexists(os.path.join(rd, \"manifest.json\")):\n raise Operational(\n \"BLOCKED\",\n \"run directory exists without a controller manifest; choose a new run id or remove the directory after confirming no initialization is active\",\n )\n validate_private_dir(rd)\n with locked_manifest(rid) as existing:\n validate_repo(existing)\n existing_source = existing.get(\"source\")\n if not isinstance(existing_source, dict):\n plan = existing.get(\"plan\")\n existing_source = {\n \"kind\": \"plan\",\n \"storage\": \"repository\",\n \"path\": plan.get(\"path\") if isinstance(plan, dict) else None,\n \"digest\": plan.get(\"digest\") if isinstance(plan, dict) else None,\n }\n if (\n existing[\"repository\"][\"identity_digest\"] != info[\"identity_digest\"]\n or existing_source.get(\"kind\") != source_kind\n or existing_source.get(\"digest\") != actual_digest\n ):\n raise Operational(\"BLOCKED\", \"run id already belongs to another repository or source\")\n if existing.get(\"binding\") != binding or existing.get(\"egress\") != egress:\n raise Operational(\n \"BLOCKED\",\n \"run id binding or egress sanction differs from the recorded fixed contract; resume with the recorded contract or choose a new run id\",\n )\n return \"READY\", {\n \"run_id\": rid,\n \"revision\": existing[\"revision\"],\n \"resumed\": True,\n \"source_kind\": source_kind,\n \"source_digest\": actual_digest,\n \"recovery_path\": rd,\n }\n validate_private_dir(rd)\n for child in (\"units\", \"jobs\", \"packets\", \"source\"):\n ensure_private_dir(os.path.join(rd, child))\n if source_kind == \"prompt\":\n create_private(os.path.join(rd, source_record[\"path\"]), source_bytes)\n create_private(os.path.join(rd, \"manifest.lock\"), b\"\")\n created = now_iso()\n doc = {\n \"schema_version\": SCHEMA_VERSION,\n \"revision\": 0,\n \"run_id\": rid,\n \"created_at\": created,\n \"updated_at\": created,\n \"repository\": {k: info[k] for k in (\"toplevel\", \"git_dir\", \"common_dir\", \"common_dev\", \"common_ino\", \"identity_digest\")},\n \"branch\": {\"ref\": info[\"branch_ref\"], \"initial_head\": info[\"head\"]},\n \"source\": source_record,\n \"plan\": {\n \"kind\": source_kind,\n \"path\": plan_rel if source_kind == \"plan\" else None,\n \"digest\": actual_digest,\n \"checkpoint\": None,\n },\n \"binding\": binding,\n \"egress\": egress,\n \"integration_lock\": None,\n \"units\": {},\n \"verification_attempts\": [],\n \"verifications\": [],\n \"blockers\": [],\n \"events\": [{\"at\": created, \"kind\": \"run-created\"}],\n }\n create_private(os.path.join(rd, \"manifest.json\"), (json.dumps(doc, sort_keys=True, separators=(\",\", \":\")) + \"\\n\").encode())\n return \"READY\", {\n \"run_id\": rid,\n \"revision\": 0,\n \"resumed\": False,\n \"source_kind\": source_kind,\n \"source_digest\": actual_digest,\n \"recovery_path\": rd,\n }\n\n\ndef status_paths(repo: str) -> set[str]:\n raw = git(repo, \"status\", \"--porcelain=v1\", \"-z\", \"--untracked-files=all\")\n parts = raw.split(b\"\\0\")\n paths: set[str] = set()\n i = 0\n while i \u003c len(parts):\n entry = parts[i]\n i += 1\n if not entry:\n continue\n if len(entry) \u003c 4:\n raise Operational(\"BLOCKED\", \"unexpected porcelain status record\")\n code = entry[:2]\n paths.add(entry[3:].decode(\"utf-8\", \"surrogateescape\"))\n if b\"R\" in code or b\"C\" in code:\n if i >= len(parts) or not parts[i]:\n raise Operational(\"BLOCKED\", \"incomplete rename status record\")\n paths.add(parts[i].decode(\"utf-8\", \"surrogateescape\"))\n i += 1\n return paths\n\n\ndef reconcile_plan_checkpoint(repo: str, doc: dict, info: dict, plan_rel: str) -> dict | None:\n \"\"\"Recover the controller's plan commit when its manifest receipt was interrupted.\"\"\"\n prior = doc.get(\"branch\", {}).get(\"initial_head\")\n commit = info[\"head\"]\n if commit == prior:\n return None\n lineage = git_text(repo, \"rev-list\", \"--parents\", \"-n\", \"1\", commit).split()\n changed = set(filter(None, git(repo, \"diff-tree\", \"--no-commit-id\", \"--name-only\", \"-r\", \"-z\", commit).decode(\"utf-8\", \"surrogateescape\").split(\"\\0\")))\n message = git(repo, \"show\", \"-s\", \"--format=%B\", commit).decode(\"utf-8\", \"surrogateescape\").rstrip(\"\\n\")\n plan_bytes = git(repo, \"show\", f\"{commit}:{plan_rel}\", check=False)\n if (\n not _valid_git_object_id(prior)\n or lineage != [commit, prior]\n or changed != {plan_rel}\n or message != PLAN_CHECKPOINT_MESSAGE\n or digest_bytes(plan_bytes) != doc[\"plan\"][\"digest\"]\n ):\n raise Operational(\n \"BLOCKED\",\n \"canonical HEAD advanced without a recorded matching plan checkpoint\",\n {\"expected_prior_head\": prior, \"head\": commit},\n )\n committed_at = int(git_text(repo, \"show\", \"-s\", \"--format=%ct\", commit))\n return {\n \"prior_head\": prior,\n \"commit\": commit,\n \"tree\": info[\"head_tree\"],\n \"path\": plan_rel,\n \"digest\": doc[\"plan\"][\"digest\"],\n \"at\": time.strftime(\"%Y-%m-%dT%H:%M:%SZ\", time.gmtime(committed_at)),\n }\n\n\ndef cmd_checkpoint_plan(args) -> tuple[str, dict]:\n with locked_manifest(args.run_id, write=True) as doc:\n info = validate_repo(doc)\n repo = info[\"toplevel\"]\n plan = doc.get(\"plan\")\n if not isinstance(plan, dict) or plan.get(\"kind\", \"plan\") != \"plan\" or not plan.get(\"path\"):\n dirty = status_paths(repo)\n if dirty:\n raise Operational(\"BLOCKED\", \"prompt-backed external execution requires a clean canonical checkout\", {\"dirty_paths\": sorted(dirty)})\n return \"NOOP\", {\"checkpoint\": None, \"head\": info[\"head\"], \"source_kind\": \"prompt\"}\n plan_rel = plan[\"path\"]\n plan_abs, _ = resolve_plan(repo, plan_rel)\n if digest_bytes(Path(plan_abs).read_bytes()) != doc[\"plan\"][\"digest\"]:\n raise Operational(\"BLOCKED\", \"selected plan content no longer matches recorded digest\")\n dirty = status_paths(repo)\n if not dirty:\n checkpoint = doc[\"plan\"].get(\"checkpoint\")\n if checkpoint is not None:\n return \"NOOP\", {\"checkpoint\": checkpoint, \"head\": info[\"head\"]}\n checkpoint = reconcile_plan_checkpoint(repo, doc, info, plan_rel)\n if checkpoint is None:\n return \"NOOP\", {\"checkpoint\": None, \"head\": info[\"head\"]}\n doc[\"plan\"][\"checkpoint\"] = checkpoint\n event(doc, \"plan-checkpoint\", detail={\"commit\": checkpoint[\"commit\"], \"path\": plan_rel})\n return \"CHECKPOINTED\", {\"checkpoint\": checkpoint}\n if dirty != {plan_rel}:\n raise Operational(\"BLOCKED\", \"canonical dirt is not exactly the selected plan\", {\"dirty_paths\": sorted(dirty)})\n prior = info[\"head\"]\n git(repo, \"add\", \"--\", plan_rel)\n staged = set(filter(None, git(repo, \"diff\", \"--cached\", \"--name-only\", \"-z\").decode(\"utf-8\", \"surrogateescape\").split(\"\\0\")))\n if staged != {plan_rel}:\n git(repo, \"reset\", \"--mixed\", prior)\n raise Operational(\"BLOCKED\", \"staged paths are not exactly the selected plan\")\n try:\n commit_index_tree(repo, PLAN_CHECKPOINT_MESSAGE)\n except Operational:\n git(repo, \"reset\", \"--mixed\", prior, check=False)\n raise\n commit = git_text(repo, \"rev-parse\", \"HEAD\")\n test_fault(\"checkpoint-plan-after-commit\")\n if status_paths(repo):\n raise Operational(\"BLOCKED\", \"checkpoint committed but canonical checkout is not clean\")\n cp = {\"prior_head\": prior, \"commit\": commit, \"tree\": git_text(repo, \"rev-parse\", \"HEAD^{tree}\"), \"path\": plan_rel, \"digest\": doc[\"plan\"][\"digest\"], \"at\": now_iso()}\n with locked_manifest(args.run_id, write=True) as doc:\n validate_repo(doc)\n doc[\"plan\"][\"checkpoint\"] = cp\n event(doc, \"plan-checkpoint\", detail={\"commit\": commit, \"path\": plan_rel})\n return \"CHECKPOINTED\", {\"checkpoint\": cp}\n\n\[email protected]\ndef admin_lock(common_dir: str):\n root = ensure_root()\n key = digest_bytes(os.path.realpath(common_dir).encode())\n path = os.path.join(root, \".locks\", f\"worktree-{key}.lock\")\n try:\n create_private(path, b\"\")\n except Operational:\n pass\n data = read_private(path, 64)\n del data\n fd = os.open(path, os.O_RDWR | O_NOFOLLOW)\n try:\n fcntl.flock(fd, fcntl.LOCK_EX)\n yield\n finally:\n fcntl.flock(fd, fcntl.LOCK_UN)\n os.close(fd)\n\n\ndef worktree_rows(repo: str) -> list[dict]:\n raw = git_text(repo, \"worktree\", \"list\", \"--porcelain\")\n rows, row = [], {}\n for line in raw.splitlines() + [\"\"]:\n if not line:\n if row:\n rows.append(row)\n row = {}\n continue\n key, _, value = line.partition(\" \")\n row[key] = value if value else True\n return rows\n\n\ndef validate_workspace(doc: dict, unit: dict) -> dict:\n repo = doc[\"repository\"][\"toplevel\"]\n workspace = unit[\"workspace\"][\"path\"]\n owned = os.path.join(run_dir(doc[\"run_id\"]), \"units\", unit[\"unit_id\"])\n if os.path.commonpath([os.path.realpath(workspace), os.path.realpath(owned)]) != os.path.realpath(owned):\n raise Operational(\"BLOCKED\", \"workspace escaped its owned unit directory\")\n validate_private_dir(workspace)\n matches = [r for r in worktree_rows(repo) if os.path.realpath(str(r.get(\"worktree\", \"\"))) == os.path.realpath(workspace)]\n if len(matches) != 1:\n raise Operational(\"BLOCKED\", \"workspace is not registered exactly once\")\n if \"detached\" not in matches[0]:\n raise Operational(\"BLOCKED\", \"unit workspace is not detached\")\n common = os.path.realpath(git_text(workspace, \"rev-parse\", \"--path-format=absolute\", \"--git-common-dir\"))\n if common != doc[\"repository\"][\"common_dir\"]:\n raise Operational(\"BLOCKED\", \"unit workspace belongs to another repository\")\n return matches[0]\n\n\ndef validate_pristine_unit_base(doc: dict, unit: dict) -> dict:\n row = validate_workspace(doc, unit)\n workspace = unit[\"workspace\"][\"path\"]\n base = unit[\"workspace\"][\"base\"]\n if git_text(workspace, \"rev-parse\", \"HEAD\") != base:\n raise Operational(\"BLOCKED\", \"unit workspace HEAD no longer equals the recorded base\")\n dirty = status_paths(workspace)\n if dirty:\n raise Operational(\n \"BLOCKED\",\n \"unit workspace is dirty before dispatch authorization\",\n {\"dirty_paths\": sorted(dirty)},\n )\n return row\n","content_type":"text/x-python; charset=utf-8","language":"python","size":44528,"content_sha256":"f9e2a0ee3a4361efdad25aa97cfdcb4a329ec4187b22eb80bf0f479e540f0f08"},{"filename":"scripts/unit_workspace_transaction.py","content":"\"\"\"Fail-stop canonical integration for one terminalized external unit.\"\"\"\n\nfrom __future__ import annotations\n\nimport hashlib\nimport json\nimport os\nimport secrets\nimport shutil\nimport subprocess\nfrom pathlib import Path\nfrom types import SimpleNamespace\n\nfrom unit_workspace_state import *\nfrom unit_workspace_integration import (\n cmd_integration_acquire,\n cmd_integration_release,\n cmd_mark_applied,\n cmd_mark_committed,\n cmd_mark_verified,\n cmd_preflight,\n cmd_restore,\n cmd_wave_advance,\n matches_expected_apply,\n remove_introduced_paths,\n semantic_snapshot,\n validate_lock,\n)\nfrom unit_workspace_lifecycle import (\n cmd_cleanup,\n pending_plan_wide_verification,\n plan_wide_verification_attempts,\n receipted_plan_wide_verification,\n)\nfrom unit_workspace_ignored import diff_ignored_state, inventory_ignored_state\n\n\ndef _args(**values):\n return SimpleNamespace(**values)\n\n\ndef _verification_command(args, operation: str = \"integrate\") -> list[str]:\n command = list(args.verification_command)\n if command and command[0] == \"--\":\n command.pop(0)\n if not command or any(not value or \"\\0\" in value for value in command):\n raise Operational(\"REFUSED\", f\"{operation} requires a non-empty verification command after --\")\n return command\n\n\ndef _remove_owned_new_paths(repo: str, paths: set[str], pre_head: str) -> None:\n for rel in sorted(paths, key=lambda value: (value.count(\"/\"), value), reverse=True):\n if git(repo, \"ls-tree\", \"-z\", \"--full-tree\", pre_head, \"--\", rel):\n continue\n target = os.path.abspath(os.path.join(repo, rel))\n if os.path.commonpath([repo, target]) != repo:\n raise Operational(\"BLOCKED\", \"verification artifact path escaped canonical repository\")\n if os.path.islink(target) or os.path.isfile(target):\n os.unlink(target)\n elif os.path.isdir(target):\n shutil.rmtree(target)\n\n\ndef _restore_owned_verification(\n run_id: str,\n unit_id: str,\n token: str,\n before: dict,\n before_paths: set[str],\n after_paths: set[str],\n) -> None:\n with locked_manifest(run_id) as doc:\n validate_repo(doc)\n unit = doc[\"units\"].get(unit_id)\n if not unit or not unit.get(\"integration\", {}).get(\"pre_fold\"):\n raise Operational(\"BLOCKED\", \"owned verification restoration lacks pre-fold evidence\")\n repo = doc[\"repository\"][\"toplevel\"]\n pre = dict(unit[\"integration\"][\"pre_fold\"])\n expected = unit[\"integration\"][\"expected_apply\"]\n if not (\n before[\"head\"] == pre[\"head\"]\n and before[\"index_tree\"] == expected[\"index_tree\"]\n and before[\"worktree_index_empty\"]\n and before_paths == set(expected[\"changed_paths\"])\n ):\n raise Operational(\"BLOCKED\", \"owned verification did not start from the expected transport application\")\n if git_text(repo, \"rev-parse\", \"HEAD\") != pre[\"head\"]:\n raise Operational(\"BLOCKED\", \"verification changed canonical HEAD; refusing automatic restoration\")\n verification_paths = after_paths - before_paths\n with locked_manifest(run_id, write=True) as doc:\n doc[\"units\"][unit_id][\"state\"] = \"restoring\"\n event(doc, \"restore-intent\", unit_id, {\"source\": \"controller-owned-verification\"})\n git(repo, \"reset\", \"--hard\", pre[\"head\"])\n with locked_manifest(run_id) as doc:\n remove_introduced_paths(repo, doc[\"units\"][unit_id])\n _remove_owned_new_paths(repo, verification_paths, pre[\"head\"])\n actual = semantic_snapshot(repo)\n exact = actual == pre\n with locked_manifest(run_id, write=True) as doc:\n unit = doc[\"units\"][unit_id]\n unit[\"integration\"][\"restore\"] = {\"at\": now_iso(), \"exact\": exact, \"snapshot\": actual}\n if exact:\n unit[\"state\"] = \"preserved\"\n event(doc, \"canonical-restored\", unit_id, {\"source\": \"controller-owned-verification\"})\n else:\n blocker = {\"at\": now_iso(), \"unit_id\": unit_id, \"reason\": \"exact pre-fold restoration could not be proven\"}\n doc[\"blockers\"].append(blocker)\n event(doc, \"restore-blocked\", unit_id, {\"source\": \"controller-owned-verification\"})\n if not exact:\n raise Operational(\"BLOCKED\", \"exact pre-fold restoration could not be proven\")\n\n\ndef _verification_log(run_id: str, unit_id: str) -> tuple[str, object]:\n parent = os.path.join(run_dir(run_id), \"units\", unit_id, \"result\")\n validate_private_dir(parent)\n path = os.path.join(parent, f\"host-verification-{secrets.token_hex(6)}.log\")\n fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | O_NOFOLLOW, 0o600)\n return path, os.fdopen(fd, \"wb\")\n\n\ndef _run_verification_log(run_id: str) -> tuple[str, object]:\n parent = os.path.join(run_dir(run_id), \"jobs\")\n validate_private_dir(parent)\n path = os.path.join(parent, f\"run-verification-{secrets.token_hex(6)}.log\")\n fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | O_NOFOLLOW, 0o600)\n return path, os.fdopen(fd, \"wb\")\n\n\ndef _validate_accepted_run_head(repo: str, units: dict, current_head: str) -> None:\n \"\"\"Require HEAD to be the accepted commit that contains every completed unit.\"\"\"\n commits: set[str] = set()\n for unit in units.values():\n commit = unit_accepted_commit(unit)\n if commit is None:\n raise Operational(\"BLOCKED\", \"unit completion evidence changed before plan-wide verification\")\n base = unit.get(\"workspace\", {}).get(\"base\")\n if not isinstance(base, str) or git_text(repo, \"merge-base\", base, commit, check=False) != base:\n raise Operational(\n \"BLOCKED\",\n \"controller-accepted unit commit does not descend from its recorded base\",\n {\"unit_id\": unit.get(\"unit_id\"), \"base\": base, \"accepted_commit\": commit},\n )\n if commit in commits:\n raise Operational(\"BLOCKED\", \"unit completion evidence contains duplicate accepted commits\")\n commits.add(commit)\n\n if current_head not in commits:\n raise Operational(\n \"BLOCKED\",\n \"canonical HEAD no longer matches the final controller-accepted unit commit\",\n {\"accepted_heads\": sorted(commits), \"actual_head\": current_head},\n )\n if any(git_text(repo, \"merge-base\", commit, current_head, check=False) != commit for commit in commits):\n raise Operational(\n \"BLOCKED\",\n \"canonical HEAD does not contain every controller-accepted unit\",\n {\"accepted_heads\": sorted(commits), \"actual_head\": current_head},\n )\n\n\ndef _record_run_verification_attempt(\n args,\n attempt_id: str,\n lock_unit: str,\n lock_token: str,\n command: list[str],\n before: dict,\n verification_log: str,\n) -> None:\n with locked_manifest(args.run_id, write=True) as doc:\n validate_lock(doc, lock_unit, lock_token)\n doc.setdefault(\"verification_attempts\", [])\n attempts = plan_wide_verification_attempts(doc)\n if any(attempt.get(\"attempt_id\") == attempt_id for attempt in attempts):\n raise TrustFailure(\"plan-wide verification attempt identity is duplicated\")\n attempts.append({\n \"attempt_id\": attempt_id,\n \"started_at\": now_iso(),\n \"status\": \"pending\",\n \"integration_lock_nonce\": lock_token,\n \"lock_unit_id\": lock_unit,\n \"argv\": command,\n \"summary\": args.verification_summary,\n \"canonical_snapshot\": before,\n \"verification_log\": verification_log,\n })\n event(doc, \"run-verification-started\", None, {\"attempt_id\": attempt_id})\n\n\ndef _record_run_verification_receipt(args, attempt_id: str, lock_token: str, receipt: dict) -> None:\n with locked_manifest(args.run_id, write=True) as doc:\n attempts = plan_wide_verification_attempts(doc)\n matches = [attempt for attempt in attempts if attempt.get(\"attempt_id\") == attempt_id]\n if len(matches) != 1:\n raise TrustFailure(\"plan-wide verification attempt identity is missing or duplicated\")\n attempt = matches[0]\n if attempt.get(\"status\") != \"pending\" or attempt.get(\"integration_lock_nonce\") != lock_token:\n raise TrustFailure(\"plan-wide verification attempt state or lock identity changed\")\n validate_lock(doc, attempt[\"lock_unit_id\"], lock_token)\n doc.setdefault(\"verifications\", []).append(receipt)\n attempt.update({\n \"status\": \"receipt-recorded\",\n \"completed_at\": now_iso(),\n \"evidence_digest\": receipt[\"evidence_digest\"],\n })\n event(doc, \"run-verification-passed\" if receipt[\"verification_exit\"] == 0 else \"run-verification-failed\", None, {\n \"attempt_id\": attempt_id,\n \"evidence_digest\": receipt[\"evidence_digest\"],\n \"verification_exit\": receipt[\"verification_exit\"],\n })\n if receipt[\"verification_exit\"] != 0:\n doc[\"blockers\"].append({\n \"at\": now_iso(),\n \"unit_id\": None,\n \"reason\": \"plan-wide verification failed\",\n \"evidence_digest\": receipt[\"evidence_digest\"],\n })\n\n\ndef _verify_run_locked(\n args,\n repo: str,\n command: list[str],\n units: dict,\n attempt_id: str,\n lock_unit: str,\n lock_token: str,\n) -> tuple[str, dict]:\n before = semantic_snapshot(repo)\n before_paths = status_paths(repo)\n if not before[\"status_empty\"] or before_paths:\n raise Operational(\"BLOCKED\", \"verify-run requires a clean canonical checkout\")\n _validate_accepted_run_head(repo, units, before[\"head\"])\n accepted_units = accepted_unit_commit_snapshot(units)\n if accepted_units is None:\n raise Operational(\"BLOCKED\", \"unit completion evidence changed before plan-wide verification\")\n before_ignored = inventory_ignored_state(repo)\n\n verification_log, stream = _run_verification_log(args.run_id)\n with stream:\n _record_run_verification_attempt(\n args,\n attempt_id,\n lock_unit,\n lock_token,\n command,\n before,\n verification_log,\n )\n try:\n proc = subprocess.run(\n command,\n cwd=repo,\n stdin=subprocess.DEVNULL,\n stdout=stream,\n stderr=subprocess.STDOUT,\n env=sanitized_git_environment({\"PYTHONDONTWRITEBYTECODE\": \"1\"}),\n check=False,\n )\n verification_exit = proc.returncode\n except OSError as exc:\n stream.write(f\"verification launch failed: {exc}\\n\".encode(\"utf-8\", \"replace\"))\n verification_exit = 127\n test_fault(\"verify-run-before-receipt\")\n\n after = semantic_snapshot(repo)\n after_paths = status_paths(repo)\n ignored_state = diff_ignored_state(before_ignored, inventory_ignored_state(repo))\n cleaned_paths: list[str] = []\n if after != before:\n if after[\"branch_ref\"] != before[\"branch_ref\"] or after[\"head\"] != before[\"head\"]:\n with locked_manifest(args.run_id, write=True) as doc:\n lock = doc.get(\"integration_lock\") or {}\n blocker = {\n \"at\": now_iso(),\n \"unit_id\": None,\n \"reason\": \"plan-wide verification changed canonical branch or HEAD\",\n \"retain_integration_lock\": True,\n \"integration_lock_nonce\": lock.get(\"nonce\"),\n }\n doc[\"blockers\"].append(blocker)\n event(doc, \"run-verification-restore-blocked\", None, {\"verification_exit\": verification_exit})\n raise Operational(\n \"BLOCKED\",\n \"plan-wide verification changed canonical branch or HEAD; automatic restoration refused\",\n {\n \"verification_exit\": verification_exit,\n \"verification_log\": verification_log,\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n \"retain_integration_lock\": True,\n },\n )\n deletion_paths = after_paths - before_paths\n cleaned_paths = sorted(deletion_paths)\n git(repo, \"reset\", \"--hard\", before[\"head\"])\n _remove_owned_new_paths(repo, deletion_paths, before[\"head\"])\n restored = semantic_snapshot(repo)\n if restored != before:\n with locked_manifest(args.run_id, write=True) as doc:\n lock = doc.get(\"integration_lock\") or {}\n blocker = {\n \"at\": now_iso(),\n \"unit_id\": None,\n \"reason\": \"plan-wide verification restoration could not be proven\",\n \"retain_integration_lock\": True,\n \"integration_lock_nonce\": lock.get(\"nonce\"),\n }\n doc[\"blockers\"].append(blocker)\n event(doc, \"run-verification-restore-blocked\", None, {\"verification_exit\": verification_exit})\n raise Operational(\n \"BLOCKED\",\n \"plan-wide verification restoration could not be proven\",\n {\n \"verification_exit\": verification_exit,\n \"verification_log\": verification_log,\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n \"retain_integration_lock\": True,\n },\n )\n\n log_digest = hashlib.sha256(Path(verification_log).read_bytes()).hexdigest()\n receipt = {\n \"attempt_id\": attempt_id,\n \"at\": now_iso(),\n \"argv\": command,\n \"summary\": args.verification_summary,\n \"verification_exit\": verification_exit,\n \"log_sha256\": log_digest,\n \"canonical_head\": before[\"head\"],\n \"accepted_units\": accepted_units,\n \"canonical_state_changed\": after != before,\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n \"verification_log\": verification_log if verification_exit != 0 else None,\n \"verification_log_retained\": verification_exit != 0,\n }\n receipt[\"evidence_digest\"] = digest_bytes(json.dumps(receipt, sort_keys=True, separators=(\",\", \":\")).encode())\n _record_run_verification_receipt(args, attempt_id, lock_token, receipt)\n if verification_exit != 0:\n raise Operational(\n \"BLOCKED\",\n \"plan-wide authoritative verification failed\",\n {\n \"verification_exit\": verification_exit,\n \"verification_log\": verification_log,\n \"evidence_digest\": receipt[\"evidence_digest\"],\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n },\n )\n os.unlink(verification_log)\n return \"RUN_VERIFIED\", {\n \"verification_exit\": 0,\n \"evidence_digest\": receipt[\"evidence_digest\"],\n \"canonical_head\": before[\"head\"],\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n \"verification_log_retained\": False,\n }\n\n\ndef cmd_verify_run(args) -> tuple[str, dict]:\n \"\"\"Run a plan-wide gate while holding the canonical integration lock.\"\"\"\n command = _verification_command(args, \"verify-run\")\n with locked_manifest(args.run_id) as doc:\n info = validate_repo(doc)\n units = doc.get(\"units\", {})\n if not units or any(not unit_ready_for_run_verification(unit) for unit in units.values()):\n raise Operational(\n \"REFUSED\",\n \"verify-run requires every unit to be terminal with an accepted canonical commit\",\n )\n if doc.get(\"integration_lock\") is not None:\n raise Operational(\"BLOCKED\", \"verify-run requires no active integration lock\")\n repo = info[\"toplevel\"]\n lock_unit = sorted(units)[-1]\n acquired = cmd_integration_acquire(_args(\n run_id=args.run_id,\n unit_id=lock_unit,\n resume=False,\n plan_verification=True,\n ))[1]\n token = acquired[\"lock_token\"]\n attempt_id = secrets.token_hex(16)\n try:\n with locked_manifest(args.run_id) as doc:\n validate_repo(doc)\n units = doc.get(\"units\", {})\n if not units or any(not unit_ready_for_run_verification(unit) for unit in units.values()):\n raise Operational(\"BLOCKED\", \"external unit completion evidence changed before plan-wide verification\")\n accepted_units = dict(units)\n result = _verify_run_locked(\n args,\n repo,\n command,\n accepted_units,\n attempt_id,\n lock_unit,\n token,\n )\n except Operational as exc:\n with locked_manifest(args.run_id) as doc:\n lock = doc.get(\"integration_lock\")\n pending = pending_plan_wide_verification(doc, lock) if isinstance(lock, dict) else None\n receipted = receipted_plan_wide_verification(doc, lock) if isinstance(lock, dict) else None\n if not exc.detail.get(\"retain_integration_lock\") and not (\n pending and pending.get(\"attempt_id\") == attempt_id\n ):\n if receipted and receipted.get(\"attempt_id\") == attempt_id:\n test_fault(\"verify-run-after-receipt\")\n cmd_integration_release(_args(run_id=args.run_id, unit_id=lock_unit, lock_token=token))\n raise\n test_fault(\"verify-run-after-receipt\")\n cmd_integration_release(_args(run_id=args.run_id, unit_id=lock_unit, lock_token=token))\n return result\n\n\ndef _integration_recovery_failure(args, original: Operational, failure: Operational, phase: str) -> Operational:\n if phase == \"restore\":\n reason = \"integration failed and exact restoration could not be proven\"\n event_name = \"integration-restore-blocked\"\n else:\n reason = \"integration failed after exact restoration but lock release failed\"\n event_name = \"integration-release-blocked\"\n detail = {\n \"reason\": reason,\n \"unit_id\": args.unit_id,\n \"original_failure\": str(original),\n \"original_word\": original.word,\n f\"{phase}_failure\": str(failure),\n f\"{phase}_word\": failure.word,\n \"retain_integration_lock\": True,\n \"recovery_path\": os.path.join(run_dir(args.run_id), \"units\", args.unit_id),\n }\n if \"ignored_state\" in original.detail:\n detail[\"ignored_state\"] = original.detail[\"ignored_state\"]\n with locked_manifest(args.run_id, write=True) as doc:\n doc[\"blockers\"].append({\"at\": now_iso(), **detail})\n event(doc, event_name, args.unit_id, {\n \"original_word\": original.word,\n f\"{phase}_word\": failure.word,\n })\n return Operational(\"BLOCKED\", reason, detail)\n\n\ndef cmd_integrate(args) -> tuple[str, dict]:\n command = _verification_command(args)\n if not args.commit_message.strip() or len(args.commit_message.encode()) > 1024:\n raise Operational(\"REFUSED\", \"commit message must be non-empty and at most 1024 bytes\")\n\n token = None\n before = None\n verification_log = None\n committed = False\n ignored_state = None\n try:\n acquired = cmd_integration_acquire(_args(run_id=args.run_id, unit_id=args.unit_id, resume=False))[1]\n token = acquired[\"lock_token\"]\n cmd_preflight(_args(\n run_id=args.run_id,\n unit_id=args.unit_id,\n lock_token=token,\n allowed_head=args.allowed_head,\n ))\n with locked_manifest(args.run_id) as doc:\n repo = doc[\"repository\"][\"toplevel\"]\n transport = doc[\"units\"][args.unit_id][\"transport\"][\"commit\"]\n git(repo, \"cherry-pick\", \"--no-commit\", transport)\n cmd_mark_applied(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))\n with locked_manifest(args.run_id) as doc:\n unit = doc[\"units\"][args.unit_id]\n if not matches_expected_apply(repo, unit):\n raise Operational(\"BLOCKED\", \"canonical apply changed before verification\")\n before = semantic_snapshot(repo)\n before_paths = status_paths(repo)\n before_ignored = inventory_ignored_state(repo)\n\n verification_log, stream = _verification_log(args.run_id, args.unit_id)\n with stream:\n try:\n proc = subprocess.run(\n command,\n cwd=repo,\n stdin=subprocess.DEVNULL,\n stdout=stream,\n stderr=subprocess.STDOUT,\n env=sanitized_git_environment({\"PYTHONDONTWRITEBYTECODE\": \"1\"}),\n check=False,\n )\n verification_exit = proc.returncode\n except OSError as exc:\n stream.write(f\"verification launch failed: {exc}\\n\".encode(\"utf-8\", \"replace\"))\n verification_exit = 127\n after = semantic_snapshot(repo)\n after_paths = status_paths(repo)\n ignored_state = diff_ignored_state(before_ignored, inventory_ignored_state(repo))\n verification_failed = verification_exit != 0 or after != before\n if verification_failed:\n _restore_owned_verification(args.run_id, args.unit_id, token, before, before_paths, after_paths)\n cleaned_paths = sorted(after_paths - before_paths)\n log_digest = hashlib.sha256(Path(verification_log).read_bytes()).hexdigest()\n if verification_failed:\n cmd_integration_release(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))\n token = None\n raise Operational(\n \"BLOCKED\",\n \"authoritative verification failed or changed canonical state\",\n {\n \"unit_id\": args.unit_id,\n \"verification_exit\": verification_exit,\n \"verification_log\": verification_log,\n \"canonical_state_changed\": after != before,\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n },\n )\n evidence = digest_bytes(json.dumps({\n \"argv\": command,\n \"exit\": verification_exit,\n \"log_sha256\": log_digest,\n \"before\": before,\n \"after\": after,\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n }, sort_keys=True, separators=(\",\", \":\")).encode())\n cmd_mark_verified(_args(\n run_id=args.run_id,\n unit_id=args.unit_id,\n lock_token=token,\n evidence_digest=evidence,\n summary=args.verification_summary,\n ignored_state=ignored_state,\n ))\n test_fault(\"before-canonical-commit\")\n commit_index_tree(repo, args.commit_message)\n committed_body = cmd_mark_committed(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))[1]\n committed = True\n canonical = committed_body[\"canonical_commit\"][\"commit\"]\n test_fault(\"after-canonical-commit-confirmed\")\n with locked_manifest(args.run_id) as doc:\n wave_id = doc[\"units\"][args.unit_id].get(\"wave\", {}).get(\"id\")\n if wave_id:\n cmd_wave_advance(_args(\n run_id=args.run_id,\n unit_id=args.unit_id,\n lock_token=token,\n canonical_commit=canonical,\n ))\n cmd_cleanup(_args(\n run_id=args.run_id,\n unit_id=args.unit_id,\n abandon=False,\n expect_transport=None,\n expect_job=None,\n ))\n cmd_integration_release(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))\n token = None\n return \"UNIT_COMMITTED\", {\n \"unit_id\": args.unit_id,\n \"canonical_commit\": canonical,\n \"verification_digest\": evidence,\n \"verification_log_retained\": False,\n \"cleaned_paths\": cleaned_paths,\n \"ignored_state\": ignored_state,\n }\n except (Operational, TrustFailure) as original:\n if ignored_state is not None:\n original.detail.setdefault(\"ignored_state\", ignored_state)\n if token is not None and committed:\n detail = {\n \"reason\": \"canonical commit accepted but post-commit finalization is incomplete\",\n \"unit_id\": args.unit_id,\n \"canonical_commit\": canonical,\n \"original_failure\": str(original),\n \"original_word\": original.word,\n \"retain_integration_lock\": True,\n \"recovery_path\": os.path.join(run_dir(args.run_id), \"units\", args.unit_id),\n \"ignored_state\": ignored_state,\n }\n with locked_manifest(args.run_id, write=True) as doc:\n doc[\"blockers\"].append({\"at\": now_iso(), **detail})\n event(doc, \"post-commit-finalization-blocked\", args.unit_id, {\n \"canonical_commit\": canonical,\n \"original_word\": original.word,\n })\n raise Operational(\n \"BLOCKED\",\n \"canonical commit accepted but post-commit finalization is incomplete\",\n detail,\n ) from original\n if token is not None and original.detail.get(\"retain_integration_lock\"):\n raise\n if token is not None:\n with locked_manifest(args.run_id) as doc:\n unit = doc[\"units\"].get(args.unit_id)\n pre_fold = unit.get(\"integration\", {}).get(\"pre_fold\") if unit else None\n if not pre_fold:\n cmd_integration_release(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))\n token = None\n raise\n try:\n cmd_restore(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))\n except (Operational, TrustFailure) as restore_failure:\n raise _integration_recovery_failure(args, original, restore_failure, \"restore\") from restore_failure\n try:\n cmd_integration_release(_args(run_id=args.run_id, unit_id=args.unit_id, lock_token=token))\n token = None\n except (Operational, TrustFailure) as release_failure:\n raise _integration_recovery_failure(args, original, release_failure, \"release\") from release_failure\n raise\n","content_type":"text/x-python; charset=utf-8","language":"python","size":26523,"content_sha256":"b04646a8a28216f8f38b1db68d8578af5ceb777ef4e17b04ee2f3e8fe2608208"},{"filename":"scripts/unit-workspace.py","content":"#!/usr/bin/env python3\n\"\"\"CLI entrypoint for the ce-work crash-recoverable workspace controller.\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport os\nimport sys\n\nfrom unit_workspace_state import Operational, TrustFailure, cmd_checkpoint_plan, cmd_init\nfrom unit_workspace_jobs import cmd_authorize_dispatch, cmd_prepare, cmd_record_job, cmd_sync_job, cmd_terminalize\nfrom unit_workspace_integration import (\n cmd_integration_acquire,\n cmd_integration_release,\n cmd_mark_applied,\n cmd_mark_committed,\n cmd_mark_verified,\n cmd_preflight,\n cmd_restore,\n cmd_wave_advance,\n)\nfrom unit_workspace_lifecycle import cmd_claim_fallback, cmd_cleanup, cmd_complete_fallback, cmd_reap, cmd_resume, cmd_status\nfrom unit_workspace_transaction import cmd_integrate, cmd_verify_run\n\n\ndef build_parser() -> argparse.ArgumentParser:\n parser = argparse.ArgumentParser(prog=\"unit-workspace.py\")\n sub = parser.add_subparsers(dest=\"command\", required=True)\n\n p = sub.add_parser(\"init\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--repo\", required=True)\n source = p.add_mutually_exclusive_group(required=True)\n source.add_argument(\"--plan\")\n source.add_argument(\"--prompt-brief\")\n p.add_argument(\"--plan-digest\")\n p.add_argument(\"--prompt-digest\")\n p.add_argument(\"--binding-json\", default=\"{}\")\n p.add_argument(\"--egress-json\", default=\"{}\")\n\n p = sub.add_parser(\"checkpoint-plan\")\n p.add_argument(\"--run-id\", required=True)\n\n p = sub.add_parser(\"prepare\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--base\", required=True)\n p.add_argument(\"--packet\", required=True)\n p.add_argument(\"--attempt-id\", default=\"attempt-1\")\n p.add_argument(\"--activity-posture\", choices=(\"incremental\", \"hard-only\"), default=\"hard-only\")\n p.add_argument(\"--dependency\", action=\"append\", default=[])\n p.add_argument(\"--wave-id\")\n p.add_argument(\"--wave-position\", type=int, default=0)\n\n p = sub.add_parser(\"record-job\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--attempt-id\", required=True)\n p.add_argument(\"--job-id\", required=True)\n\n p = sub.add_parser(\"authorize-dispatch\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--attempt-id\", required=True)\n p.add_argument(\"--job-id\", required=True)\n p.add_argument(\"--authorization\", required=True)\n p.add_argument(\"--authorization-digest\", required=True)\n p.add_argument(\"--workspace\", required=True)\n p.add_argument(\"--packet\", required=True)\n p.add_argument(\"--packet-digest\", required=True)\n p.add_argument(\"--result-dir\", required=True)\n\n for name in (\"sync-job\", \"terminalize\", \"reap\"):\n p = sub.add_parser(name)\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n\n p = sub.add_parser(\"integration-acquire\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--resume\", action=\"store_true\")\n\n p = sub.add_parser(\"preflight\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n p.add_argument(\"--allowed-head\", action=\"append\", default=[])\n\n p = sub.add_parser(\"mark-applied\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n\n p = sub.add_parser(\"mark-verified\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n p.add_argument(\"--evidence-digest\", required=True)\n p.add_argument(\"--summary\", default=\"authoritative verification passed\")\n p.add_argument(\"--ignored-state\", default=None)\n\n p = sub.add_parser(\"mark-committed\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n\n p = sub.add_parser(\"integrate\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--commit-message\", required=True)\n p.add_argument(\"--verification-summary\", default=\"authoritative verification passed\")\n p.add_argument(\"--allowed-head\", action=\"append\", default=[])\n p.add_argument(\"verification_command\", nargs=argparse.REMAINDER)\n\n p = sub.add_parser(\"verify-run\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--verification-summary\", default=\"plan-wide authoritative verification passed\")\n p.add_argument(\"verification_command\", nargs=argparse.REMAINDER)\n\n p = sub.add_parser(\"wave-advance\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n p.add_argument(\"--canonical-commit\", required=True)\n\n p = sub.add_parser(\"restore\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n\n p = sub.add_parser(\"status\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\")\n\n p = sub.add_parser(\"resume\")\n p.add_argument(\"--run-id\")\n p.add_argument(\"--repo\")\n p.add_argument(\"--plan-digest\")\n\n p = sub.add_parser(\"claim-fallback\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--caller-mode\", choices=(\"interactive\", \"headless\"), required=True)\n\n p = sub.add_parser(\"complete-fallback\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--accepted-head\", required=True)\n p.add_argument(\"--evidence-digest\", required=True)\n p.add_argument(\"--summary\", required=True)\n\n p = sub.add_parser(\"cleanup\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--abandon\", action=\"store_true\")\n p.add_argument(\"--expect-transport\")\n p.add_argument(\"--expect-job\")\n\n p = sub.add_parser(\"integration-release\")\n p.add_argument(\"--run-id\", required=True)\n p.add_argument(\"--unit-id\", required=True)\n p.add_argument(\"--lock-token\", required=True)\n return parser\n\n\nCOMMANDS = {\n \"init\": cmd_init,\n \"checkpoint-plan\": cmd_checkpoint_plan,\n \"prepare\": cmd_prepare,\n \"authorize-dispatch\": cmd_authorize_dispatch,\n \"record-job\": cmd_record_job,\n \"sync-job\": cmd_sync_job,\n \"terminalize\": cmd_terminalize,\n \"integration-acquire\": cmd_integration_acquire,\n \"preflight\": cmd_preflight,\n \"mark-applied\": cmd_mark_applied,\n \"mark-verified\": cmd_mark_verified,\n \"mark-committed\": cmd_mark_committed,\n \"integrate\": cmd_integrate,\n \"verify-run\": cmd_verify_run,\n \"wave-advance\": cmd_wave_advance,\n \"restore\": cmd_restore,\n \"status\": cmd_status,\n \"resume\": cmd_resume,\n \"claim-fallback\": cmd_claim_fallback,\n \"complete-fallback\": cmd_complete_fallback,\n \"reap\": cmd_reap,\n \"cleanup\": cmd_cleanup,\n \"integration-release\": cmd_integration_release,\n}\n\n\ndef main(argv: list[str]) -> int:\n os.umask(0o077)\n args = build_parser().parse_args(argv)\n try:\n word, body = COMMANDS[args.command](args)\n print(word)\n print(json.dumps(body, sort_keys=True, separators=(\",\", \":\")))\n return 0\n except TrustFailure as exc:\n print(\"UNREADABLE\")\n sys.stderr.write(f\"unit-workspace: {exc}\\n\")\n return 4\n except Operational as exc:\n print(exc.word)\n if exc.detail:\n print(json.dumps(exc.detail, sort_keys=True, separators=(\",\", \":\")))\n sys.stderr.write(f\"unit-workspace: {exc}\\n\")\n return 1\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main(sys.argv[1:]))\n","content_type":"text/x-python; charset=utf-8","language":"python","size":8013,"content_sha256":"669e8be96565d5e9c31523ce13e37d97aa36c635c221546e09bfa99c182a91bd"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Work Execution Command","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Outcome","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Result:","type":"text","marks":[{"type":"strong"}]},{"text":" A fully implemented, locally verified change set from a plan, specification, or concrete work prompt.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Next consumer:","type":"text","marks":[{"type":"strong"}]},{"text":" In standalone use, the shipping workflow takes the verified change through review and delivery. In Return-to-Caller Mode, the invoking workflow receives the structured implementation and verification result and owns its remaining gates.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Done:","type":"text","marks":[{"type":"strong"}]},{"text":" Every in-scope task is complete, required verification evidence is recorded, relevant checks pass, and the run reaches either its owned shipping handoff (with a code-review receipt or explicit skip phrase — see Phase 3-4), a complete return result, or an explicit blocker.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Intent:","type":"text","marks":[{"type":"strong"}]},{"text":" Finish the requested feature without renegotiating the plan or transferring canonical integration authority. Workers receive bounded units; the host orchestrator inspects actual changes and owns authoritative verification and canonical commits.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"Bundled references must be read, never approximated.","type":"text","marks":[{"type":"strong"}]},{"text":" Resolve each reference or script path named below from this skill's loaded ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory, using the full skill path the harness supplied, and never glob the target repository to find a bundled file. Read each reference when you enter the phase it governs; a read made before that phase does not satisfy it, and a reference this file says to read again is read again at its step even when already in context. If the harness does not expose the skill directory, or a required file cannot be read, stop before the action it governs and report which file is missing. Do not reconstruct its rules from memory; report the missing reference instead of continuing natively.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 0: Input Triage","type":"text"}]},{"type":"paragraph","content":[{"text":"Recovery activation comes first.","type":"text","marks":[{"type":"strong"}]},{"text":" Before classifying the input as a plan, a path, a blank, or a bare prompt, recognize requests to resume, inspect, reap, or clean up an existing run. Recovery never dispatches a new worker, selects a new route, discovers another plan, reruns completed verification, or enters either shipping path. If the run id is missing, ask for it; never guess one.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before any other input decision, read ","type":"text"},{"text":"references/input-triage.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". It decides source resolution, control tokens, recovery, read-only discovery, plan readiness, non-code routing, blank input, and bare-prompt sizing. Three rules from it hold here:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A bare prompt that is Trivial — one or two files, no behavioral change — skips the task list but still resolves its execution engine before writing. A purely mechanical diff also ships without a post-PR watch. When either is uncertain, take the fuller route.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A bare prompt that ","type":"text"},{"text":"ce-plan","type":"text","marks":[{"type":"code_inline"}]},{"text":" already sized in this session is executed, not planned again. A decision the user would weigh is asked as a question, never as a route back to ","type":"text"},{"text":"ce-plan","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"ce-brainstorm","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If that reference cannot be read, stop; never treat control tokens or a non-executable artifact as code work.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When triage selects Return-to-Caller Mode, read ","type":"text"},{"text":"references/return-to-caller.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" immediately and record that it governs how this run ends. If it cannot be read, stop before any mutation; do not fall back to standalone behavior.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 1: Quick Start","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Establish the workspace.","type":"text","marks":[{"type":"strong"}]},{"text":" Before moving branches, editing, dispatching, or committing, read ","type":"text"},{"text":"references/workspace-setup.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". It decides the writable checkout, plan clarification, branch placement, the pre-work inventory, already-dirty files, and task setup. Never write without a writable canonical checkout, and never write on the real default branch unless the user explicitly directed that in this session.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not commit or publish anything the user did not offer.","type":"text","marks":[{"type":"strong"}]},{"text":" When a unit needs a file that was already dirty, standalone mode asks once whether to include or exclude that file. Return-to-Caller Mode neither asks nor edits it; it returns blocked, naming the collision and how to recover.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve the engine, then strategy.","type":"text","marks":[{"type":"strong"}]},{"text":" After bounded plan intake and task derivation, but before selecting a unit for execution, writing, dispatching, or committing, read ","type":"text"},{"text":"references/execution-engines.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and complete its route selection. It applies with or without a typed binding; native execution is eligible only when that reference selects it or exhausts an allowed fallback. The engine choice never changes which reference governs how the run ends.","type":"text"}]},{"type":"paragraph","content":[{"text":"If cross-model execution is selected, read ","type":"text"},{"text":"references/cross-model-execution.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" before any content or authority crosses to the other model. It defines controller initialization, the post-init engine lock, bounded egress, transactions, recovery, and receipts.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before choosing inline, serial, or parallel execution, and before dispatching any worker, read ","type":"text"},{"text":"references/execution-strategy.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". It decides scheduling, isolation, the packet each worker receives, worker lifecycle, and integration. The host orchestrator keeps authoritative verification and makes the canonical commits.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 2: Execute","type":"text"}]},{"type":"paragraph","content":[{"text":"Before the first implementation write, including on the Trivial route, read ","type":"text"},{"text":"references/implementation-loop.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". It decides how evidence is chosen, verification, when to stop a unit, incremental commits, following existing patterns, continuous testing, where simplification stops, UI work, progress tracking, and settled decisions.","type":"text"}]},{"type":"paragraph","content":[{"text":"The commit rule from this file stays in force throughout: every implementation commit names only that unit's owned files. A bare ","type":"text"},{"text":"git commit","type":"text","marks":[{"type":"code_inline"}]},{"text":" can absorb the user's pre-existing index, so it is forbidden.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 3-4: Quality Check and Finishing Work","type":"text"}]},{"type":"paragraph","content":[{"text":"After the tasks and local verification are complete, standalone mode reads ","type":"text"},{"text":"references/shipping-workflow.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" before any quality check or delivery. It decides simplification, code-review receipts and fallbacks, leftover findings, final validation, and delivery.","type":"text"}]},{"type":"paragraph","content":[{"text":"Code-review completion gate (standalone only).","type":"text","marks":[{"type":"strong"}]},{"text":" Code review must actually happen before shipping. The run is not done, must not call a commit or shipping skill, and must not report that shipping is complete until the shipping reference has recorded either an actual completed ","type":"text"},{"text":"ce-code-review","type":"text","marks":[{"type":"code_inline"}]},{"text":" receipt or one of its exact authorized skip states. Never substitute a mental self-review or findings already applied earlier. This rule does not apply in Return-to-Caller Mode.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Return-to-Caller Mode","type":"text"}]},{"type":"paragraph","content":[{"text":"Return-to-Caller Mode performs implementation and local verification only. It must not enter Phase 3-4 or run final simplification, code review, PR creation, CI watching, babysitting, or any other standalone shipping action; the caller owns those steps.","type":"text"}]},{"type":"paragraph","content":[{"text":"Immediately before emitting the result, read ","type":"text"},{"text":"references/return-to-caller.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" again. It alone defines the full return result, the check that evidence is complete, the route and model records, recovery semantics, and ","type":"text"},{"text":"standalone_shipping_skipped: true","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not build a complete result from this file.","type":"text"}]},{"type":"paragraph","content":[{"text":"If that required read fails after planning or implementation created state, preserve every changed file, commit, workspace, and controller record. Return the minimum blocked result from this file: ","type":"text"},{"text":"status: blocked","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"plan_path","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"run_id","type":"text","marks":[{"type":"code_inline"}]},{"text":" when known, ","type":"text"},{"text":"changed_state","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"blockers","type":"text","marks":[{"type":"code_inline"}]},{"text":" naming the missing reference, and ","type":"text"},{"text":"recovery_path","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not erase partial state, report success, or fall into the standalone shipping path.","type":"text"}]}]},"metadata":{"date":"2026-11-02","name":"ce-work","author":"@skillopedia","source":{"stars":25863,"repo_name":"compound-engineering-plugin","origin_url":"https://github.com/EveryInc/compound-engineering-plugin/blob/HEAD/skills/ce-work/SKILL.md","repo_owner":"EveryInc","body_sha256":"c9b392620e8ae856882cd5a493b1f0e5941aa06935a73578846e703e0f00ce00","cluster_key":"6dbf2b56e2d927326e38ea98e62d0266f6c3416bcfd69fd50cb7482268fbb102","clean_bundle":{"format":"clean-skill-bundle-v1","source":"EveryInc/compound-engineering-plugin/skills/ce-work/SKILL.md","text_bytes":588114,"source_commit":"77cc431daaebea7ee9f33ac530a66eec5404572b","skills_sh_rank":5601,"attachment_count":26,"text_attachments":26,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/ce-work/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"software-engineering","import_tag":"skills-sh-top20k-2026-11","description":"Execute a plan or concrete work prompt end-to-end. Use when implementing from a plan document, a spec path, or a clear build request; use ce-debug for open-ended bugs. Use when an outer orchestrator needs implementation and local verification only, without the shipping tail.","argument-hint":"[Plan path, work description, or recovery request with run id; blank uses latest] | [mode:return-to-caller [implementation_engine:\u003ccompact-json>] [implementation_run:\u003csafe-id>] \u003cplan path> for outer orchestrators]"}},"renderedAt":1793666059281}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.