fix: unify executor registration, dispatch and exit verification

[thisisjun786]

CXC displays and stores executor, but its spawn hook classified agent_type: "executor" as explorer/reviewer, and its exit evidence hook only matched worker. This change makes executor identity consistent while preserving existing installations that have only built-in worker.

• Resolve executor tasks to native executor when $CODEX_HOME/agents/executor.toml exists, otherwise retain built-in worker. The pure payload builder also defaults to worker unless registration is known. Both names use executor settings and the same exit evidence gate.
• Add optional cxc subagents register executor. Content-hash provenance permits updates to unchanged managed prompts, preserving user-edited or differing unmarked files and symlinks. Updates retain the exact previous content as a backup. Identical legacy prompts can be adopted. Registration does not change project model choices, permissions, worker roles or hook trust.
• Apply exit verification to both implementation types and share their constant with the review observer. Explicit role identity takes priority over message inference.
• Document optional registration after hook approval, a copyable marketplace-chat request and CLI command, and the required new session after registration. A role file is not proof that an already-running session loaded it.

Maintainer review follow-up

The missing-registration upgrade path now has a regression test: the original unconditional executor mapping fails; worker fallback passes. Managed prompt updates, user-edit preservation and legacy adoption are tested. Latest dev (including #92/#93) was incorporated with a normal merge so the published branch history is preserved.

Validation

Full combined suite: 2711 total / 2640 passed / 0 failed / 71 conditional skips. Focused registration/CLI/spawn suites: 46 passed. Component build, changed-core strict TypeScript, measured inventory/gate and Linux platform smoke pass. Tests cover concurrent initial registration, conflicts and symlinks, absent/present native roles and the production payload resolver.

The original fresh-session executor probe succeeded before this follow-up. This follow-up changed no installed user roles or settings. Actual modified SubagentStop delivery still requires normal hook reapproval; invoked-entrypoint tests do not prove native hook delivery. No merge or release requested.

Design and evidence: devlog/_fin/260908_executor_role_registration/.

[lidge-jun]

Independent review — holding this PR

An anthropic/claude-opus-5 reviewer read this diff in isolation and returned REQUEST-CHANGES. I verified its central finding against the tree before acting on it, so this is a hold rather than a rejection: the routing and exit-verification half of this change is careful and correct, and the reviewer said so explicitly.

Blocker

ROLE_AGENT_TYPE.executor emits agent_type: "executor" unconditionally, and buildSpawnPayload reads that map with no fallback. But executor is not a codex-rs built-in — it resolves only after a manual cxc subagents register executor plus a session restart. So on upgrade, an install that previously dispatched executors starts failing at the host tool boundary with unknown agent_type 'executor', where the plugin has no opportunity to catch or explain it.

I confirmed this is reachable rather than theoretical. dev currently declares Record<RoleName, "explorer" | "worker"> at spawn-wrapper.ts:24, and ~/.codex/agents/ on my machine is empty — the exact state every existing user is in at merge time. Because PABCD routes B-phase writes through the executor role, this takes out the implementation path of the workflow rather than a peripheral feature.

Your own validation is unusually honest and I want to be clear that I read it that way. The gap is narrow: every test and the live probe run after registration succeeded. There is no case covering a spawn on an install where executor.toml does not exist yet.

Suggested fix: check for $CODEX_HOME/agents/executor.toml in resolveSpawnPayload and fall back to "worker" when it is absent. Both GATED_AGENT_TYPES and inferRole already accept worker, so the fallback costs nothing structurally. Alternatively let session-start-healing-declared-features register the role, or at minimum warn at session start when the role file is missing.

Also worth fixing in the same pass

• The README registration command uses an unexpanded <plugin-root> placeholder pointing at a versioned cache path that changes on every upgrade, and it sits before the hook-approval step. Since the blocker makes that command mandatory, an uncopyable form is an availability problem.
• role-registration.ts:36 has no upgrade path: byte inequality is the only "differs" signal, there is no --force (the parser rejects extra arguments at cli.ts:39-43), and no provenance marker. Once the shipped prompt changes, every registered user is pinned to the old one with no supported remedy. A # codexclaw-managed: <hash> line would let you distinguish a stale managed file from a user edit.

Confirmed correct

The reviewer specifically verified and I want this on record: the legacy worker alias still routes correctly at spawn-attach-hook.ts:441; GATED_AGENT_TYPES is a strict superset of the old single-element set, so the exit gate cannot have lost a case it used to catch; and review-observer.ts:41 importing the same constant rather than duplicating a literal structurally guarantees the receipt gate and the review observer partition children instead of racing. That last part was called the strongest thing in the diff.

Minor items — the doubled role prompt after registration, the stale built-ins line at agents/README.md:15, and a "worker" comment at review-observer.ts:61 — can ride along or follow.

Note that dev has moved since you opened this (#92 and #93 both landed and touch the READMEs), so this will need a rebase.

Full verdicts and adjudication for all three PRs: devlog/_plan/260908_dev_install_track/021_wp3_review_verdicts.md on dev.

[thisisjun786]

Thanks for catching the upgrade path. You were right: my original live validation only covered an already-registered executor.

Addressed in 11d41b8 and 9a546f0:

• Missing or inaccessible $CODEX_HOME/agents/executor.toml now keeps executor tasks on built-in worker. The pure builder also defaults to worker unless registration is known. The missing-registration regression fails with the original unconditional mapping and passes with the fallback.
• Registration now adds a content-hash provenance marker. Re-running it updates intact managed prompts, adopts an identical unmarked legacy prompt, and preserves differing unmarked or user-edited files. Updates retain the previous bytes in a hash-named backup; conflicting files and symlinks remain protected.
• Registration is documented as optional, after hook approval, with a copyable Codex-chat request for marketplace installations and the CLI command. The new-session requirement remains explicit: file presence does not prove that an existing session loaded the role.
• Integrated current dev, including test: cover Windows short-path source bindings #92/fix(subagents): persist effort and add global defaults with live OCX models #93, with a normal merge to preserve the published branch history. The shared executor/worker exit-gate behavior remains intact.

Validation: 2,711 tests total, 2,640 passed, 71 conditional skips, 0 failures; focused registration/CLI/spawn suites 46/46 passed. Component build, changed-core strict TypeScript, measured inventory/gate and Linux platform smoke passed. Independent follow-up review found no blockers. These are local results; GitHub checks are separate. No installed user roles or hook trust records were changed in this follow-up.

The registered prompt still accompanies the inline task instructions; I left that non-blocking prompt-deduplication item for a separate change. Ready for another review of the upgrade compatibility fix.