hanamizuki/solopreneur/codex-agents-bootstrap

Bootstrap Codex Agents

Run the bundled scripts/install-codex-agents.sh with /bin/bash. The script uses the active Codex installation list, validates every managed source before copying, and preserves hand-authored user-layer identities declared by the base $CODEX_HOME/config.toml or recursively under $CODEX_HOME/agents/, including hidden files and directories. It requires codex, jq, and Python 3.9 or newer. TOML parsing always uses the bundled Tomli 2.4.1; runtime package installation and network access are unnecessary.

The collision check is deliberately more conservative than Codex: it never follows a symlink in the user agent tree, base config, or a declared role's config_file. A pre-existing unsafe, dangling, or non-regular path fails the all-source preflight before any managed copy is committed. A base config role keeps its exact table-key identity unless its config_file supplies a nonblank root name, which Codex trims and uses as the identity. Managed destinations and orphan reporting remain top-level only.

The same user-layer identity scan runs again after staging and immediately before destination ownership is rechecked. A collision or unsafe path that appears during staging aborts before committing the affected copy, and the cleanup trap removes its staged temporary file; this narrows the ordinary race window but does not claim atomic coordination with independent config writers.

Treat the result as a check of the base user-layer candidates, not proof of the effective runtime role. Profile, project, command-line, or managed configuration layers may have higher precedence and are outside this bootstrap's collision scope.

Report all Installed, Updated, Unchanged, Skipped, Inactive, and Orphaned entries exactly as returned. On a nonzero exit, report only actions the script explicitly says were committed; never present a planned copy as successful. Surface the error and stop.

A disabled plugin with a retained managed destination appears in both Inactive and Orphaned: inactive explains why it was not refreshed, while orphaned means only that no active solopreneur plugin source currently claims the fully owned top-level copy. It is a manual-review candidate, not proof that the file is unused or removable: a profile, project, command-line, managed, or other config layer may still reference or override it. Never describe an orphan as safe to remove. Any later removal requires explicit user approval after auditing every relevant config layer and the exact path.

Only emit Orphaned when the exact marker, root TOML name, filename, and canonical plugin/agent pair all agree. This proves solopreneur ownership, not runtime non-use. A Skipped entry that says ownership is not proven is suspicious and must not be presented as safe to remove.

After an install or update, tell the user to start a new Codex conversation so the refreshed agent configuration is loaded.