codex-model-router 1.1.0 → 1.2.0

package/MAINTAINERS.md

@@ -0,0 +1,92 @@
+# Maintainer Guide
+
+## First npm publication bootstrap
+
+The first publication of a new npm package cannot use Trusted Publishing because the npm package settings do not exist yet. Use the Release workflow's explicit `bootstrap` publication mode exactly once.
+
+The bootstrap token must be a granular npm access token with package read/write access and non-interactive publishing permission. Store it only as the GitHub Actions repository secret named `NPM_TOKEN`; never commit it to the repository or write it into workflow logs.
+
+For the first publication:
+
+1. Open **Actions → Release → Run workflow**.
+2. Keep the workflow definition branch on `main`.
+3. Enter the exact version tag required by `package.json`, for example `v1.2.0`.
+4. Select `bootstrap` for `publish_mode`.
+5. Run the workflow.
+
+The tag may already exist. When it does, the workflow checks out that exact tag and verifies that it is reachable from `main`.
+
+When the tag does not yet exist, a manual bootstrap run starts from the exact current `origin/main` commit, verifies the requested tag matches `v<package.json version>`, runs all tests, validates the release metadata and current Changelog entry, and only then creates and pushes the tag. Normal mode and tag-triggered runs are never allowed to create a missing tag.
+
+Bootstrap mode is rejected when the npm package or exact version already exists. The token is exposed only to the guarded bootstrap step. Tag-triggered releases and manual runs in `normal` mode never receive `NPM_TOKEN`.
+
+After the first version is published, configure Trusted Publishing as described below. Once a later release succeeds through OIDC, delete the `NPM_TOKEN` repository secret.
+
+## npm Trusted Publishing setup
+
+This one-time npm account configuration cannot be committed to the repository.
+
+On the npm package settings page for `codex-model-router`, add a GitHub Actions trusted publisher with:
+
+```text
+Organization or user: Honguan
+Repository: codex-model-router
+Workflow filename: release.yml
+Environment: leave empty unless the workflow is updated to use one
+```
+
+The same relationship can be configured by an authenticated maintainer with npm 11.15.0 or newer:
+
+```sh
+npm trust github codex-model-router \
+  --repo Honguan/codex-model-router \
+  --file release.yml \
+  --allow-publish \
+  --yes
+npm trust list codex-model-router
+```
+
+Normal releases use only `contents: write` and `id-token: write` and publish with provenance.
+
+## Release checklist
+
+1. Verify all Issues and pull-request checks are complete.
+2. Update `package.json`, `CHANGELOG.md`, README version examples, and the shared manifest behavior together.
+3. Run `npm run check`, `npm test`, `npm run test:package`, and `npm pack --dry-run`.
+4. Confirm CI passes on Windows, Linux, and macOS with Node.js 18, 20, 22, and 24.
+5. Confirm actionlint and ShellCheck pass.
+6. For normal releases, create and push the exact tag `v<package.json version>` from `main`.
+7. For the first package publication only, the manual bootstrap flow may create the missing exact tag after all validations pass.
+8. Verify the Release workflow publishes with npm provenance.
+9. Verify the clean public npm end-to-end step passes before the GitHub Release appears.
+10. Confirm `npm view codex-model-router version` and `npx --yes codex-model-router@<version> --version`.
+
+## Manual release retry
+
+Open **Actions → Release → Run workflow**, keep the workflow definition on `main`, and enter the exact version tag in the required `tag` field.
+
+Select publication mode as follows:
+
+- `bootstrap`: only for the first creation of the npm package; it may safely create the missing exact version tag from current `main` after validation.
+- `normal`: every later version and every idempotent retry after the package exists; the tag must already exist.
+
+The branch selector chooses which workflow definition to run; it is not the release target. For an existing tag, the workflow checks out that tag, verifies that its commit is reachable from `main`, validates that the tag matches `package.json`, and then resumes the npm and GitHub Release checks.
+
+Never enter a branch name in the `tag` field. Never reuse a package version that already exists on npm. Never use bootstrap mode for later versions.
+
+## Compatibility update checklist
+
+For every release that changes generated paths, TOML fields, models, or Codex integration:
+
+1. Review the official Codex subagent, skill, and configuration references.
+2. Record the exact Codex CLI version used as the compatibility baseline.
+3. Run the compatibility smoke check in CI.
+4. Update README paths and minimum version claims.
+5. Test project and global scope separately.
+6. Preserve Windows junction, POSIX symlink, LF/CRLF, and user-modification tests.
+
+## Recovery
+
+A failed npm publication does not create a GitHub Release. For an unpublished package, verify the `NPM_TOKEN` bootstrap secret and run the exact version with `publish_mode=bootstrap`; the workflow can create the missing tag safely when necessary. For an existing package, fix the Trusted Publisher relationship and retry the existing exact tag with `publish_mode=normal`.
+
+Delete or recreate a tag manually only when npm does not contain that version and the existing tag is demonstrably wrong. Published npm versions are immutable and must never be reused.

package/README.md

@@ -1,74 +1,140 @@
 # codex-model-router
 
-A small Node.js CLI that installs a Codex skill and two custom subagents without replacing unrelated user configuration.
+A small Node.js CLI that safely installs advisory Codex subagent routing for Terra, Luna, and Sol without replacing unrelated user configuration.
 
-Routing is advisory: Terra reads the skill and decides when to delegate. This package does not intercept prompts or guarantee a hard model switch.
+> Routing is advisory. Terra reads the installed skill and decides when to delegate. This package does not intercept prompts or guarantee a hard model switch.
 
-## Requirements
+## Compatibility
 
-- Node.js 18 or newer
-- A current Codex release with custom agents and local skills
+Compatibility was verified on 2026-07-31 against:
 
-## Install
+- Codex CLI `0.145.0` or newer
+- Node.js 18, 20, 22, and 24
+- Windows, Linux, and macOS GitHub-hosted runners
+- Codex project agents in `.codex/agents/`
+- Codex user agents in `$CODEX_HOME/agents/` or `~/.codex/agents/`
+- project skills in `.agents/skills/`
+- user skills in `~/.agents/skills/`
+
+The selected Codex account must have access to `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.6-sol`. Older Codex versions may not recognize the generated agent or skill files.
 
-From npm after publication:
+## Quick start
+
+Preview a project installation without changing files:
 
 ```sh
-npx codex-model-router install
+npx codex-model-router install --set-default --dry-run
 ```
 
-From GitHub:
+Install Terra/high as the project default, add Luna and Sol, then verify:
 
 ```sh
-npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v1.1.0.tar.gz
-codex-model-router install
+npx codex-model-router install --set-default
+npx codex-model-router doctor
 ```
 
-Project scope is the default. Use `--global` only when the setup should apply to every project:
+Remove only unchanged package-managed settings and files:
 
 ```sh
-codex-model-router install --global
+npx codex-model-router uninstall
 ```
 
-A normal install preserves an existing main model. To explicitly set Terra/high and make the change reversible:
+## Install
+
+Run directly from npm without installing the CLI globally:
 
 ```sh
-codex-model-router install --set-default
+npx codex-model-router install
 ```
 
-Preview without writing anything:
+Install the CLI command globally:
 
 ```sh
-codex-model-router install --set-default --dry-run
-codex-model-router uninstall --dry-run
+npm install -g codex-model-router
+codex-model-router install
 ```
 
-## What is changed
+Installing the CLI globally only makes the command available system-wide. It does not modify user-level Codex configuration. The separate `install --global` option applies routing to the current user's Codex configuration.
+
+Install a specific GitHub release:
+
+```sh
+npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v1.2.0.tar.gz
+codex-model-router install
+```
 
-Project scope manages only:
+## Project and global scope
+
+Project scope is the default:
+
+```sh
+codex-model-router install
+```
+
+It manages only:
 
 ```text
 .codex/config.toml
 .codex/agents/luna.toml
 .codex/agents/sol.toml
+.codex/model-router-state.json
+.codex/config.toml.codex-model-router.bak        # only when needed
 .agents/skills/model-router/SKILL.md
 ```
 
-Global scope uses `$CODEX_HOME` or `~/.codex` for Codex files and `~/.agents/skills/model-router/` for the skill.
+During a mutating operation it may temporarily create:
+
+```text
+.codex/model-router.lock
+.codex/model-router-transaction.json
+.codex/model-router-transaction-data/
+```
+
+These transient files are removed after a successful operation or safe recovery.
+
+Use global scope only when the routing configuration should apply to every Codex project for the current user:
+
+```sh
+codex-model-router install --global
+codex-model-router doctor --global
+```
+
+Global scope manages the equivalent paths under `$CODEX_HOME` and stores the skill under `~/.agents/skills/model-router/`. When `CODEX_HOME` is unset, it defaults to `~/.codex`.
+
+## Existing settings
+
+A normal install adds Terra/high only when the top-level values are absent. Existing model values are preserved:
+
+```sh
+codex-model-router install
+```
+
+To explicitly set and track Terra/high:
 
-A plain install adds Terra/high only when the top-level values are absent. Existing values are preserved. `--set-default` replaces only `model` and `model_reasoning_effort`, records the exact prior values, and restores them during uninstall only when the user has not changed them afterward.
+```sh
+codex-model-router install --set-default
+```
+
+`--set-default` changes only:
 
-Existing Luna, Sol, or skill files are never overwritten. Uninstall removes only unchanged package-owned files. Unrelated TOML settings, comments, BOM, ordering, and LF/CRLF line endings are preserved.
+```toml
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
+```
+
+The exact prior values are recorded. Uninstall restores them only while the current values still match what the package installed. Later user edits are preserved and reported instead of overwritten.
+
+Existing Luna, Sol, or skill files are never overwritten. Unrelated TOML settings, comments, BOM, ordering, and LF/CRLF line endings are preserved.
 
 ## Installed routing
 
-- Terra/high: normal questions, coding, debugging, fixes, tests, and implementation
-- Luna/high: deterministic repeated edits, bulk patterns, searches, formatting, counting, extraction, and summaries
-- Sol/medium/workspace-write: security-sensitive or high-regression-risk review and implementation
-- Sol normally reviews first; it may edit files when Terra explicitly delegates implementation or a confirmed fix
-- Simple questions do not spawn a subagent
+- Terra/high handles normal questions, coding, debugging, fixes, tests, and implementation.
+- Luna/high handles deterministic repeated edits, bulk patterns, searches, formatting, counting, extraction, and summaries.
+- Sol/medium/workspace-write handles security-sensitive or high-regression-risk review and implementation.
+- Sol normally reviews first and may edit files only when Terra explicitly delegates implementation or a confirmed fix.
+- Simple questions do not spawn a subagent.
 
-Users may edit model names, reasoning levels, and `sandbox_mode` directly in the generated TOML files. Later installs preserve those manual edits and `doctor` reports them as user-modified.
+Users may edit model names, reasoning levels, and `sandbox_mode` directly in the generated TOML files. Later installs preserve manual edits, and `doctor` reports changed managed files.
 
 ## Commands
 
@@ -79,78 +145,78 @@ codex-model-router doctor [--global]
 codex-model-router --version
 ```
 
-`doctor` is read-only. Exit code `0` means healthy; exit code `1` reports missing, invalid, user-modified, overridden, or unsafe state.
+`doctor` is read-only. Exit code `0` means healthy; exit code `1` means action is required.
 
-## Automatic npm publication
+Common statuses:
 
-Create a GitHub Actions repository secret named `NPM_TOKEN`:
+- `healthy`: the managed item matches its expected state.
+- `preserve` or `user-modified`: user content was detected and left unchanged.
+- `missing` or `invalid`: a required item is absent or malformed.
+- `unsafe-state`: state paths or path components are unsafe.
+- `locked` or `stale-lock`: another operation is active or a previous process ended unexpectedly.
+- `unfinished`, `recoverable`, `conflicting`, or `corrupt`: an interrupted transaction needs attention.
 
-```text
-Repository Settings
-→ Secrets and variables
-→ Actions
-→ New repository secret
-```
+## Safety behavior
 
-Paste the npm access token as the secret value. Never place the real token in this repository or in the workflow YAML.
+- Rejects malformed, non-UTF-8, duplicate, or unsafe configuration before writing.
+- Rejects symlinks and Windows junctions in managed paths so writes cannot escape the selected scope.
+- Uses a scope-level process lock to prevent concurrent install/uninstall races.
+- Uses an atomic transaction journal and private snapshots to recover interrupted multi-file operations.
+- Never overwrites post-interruption user changes during recovery.
+- Uses atomic file replacement and rollback for handled failures.
+- Removes or restores only unchanged package-managed content.
+- Never modifies `AGENTS.md`, shell profiles, editor settings, hooks, MCP servers, telemetry, accounts, or environment variables.
+- Dry-run creates no files, directories, backups, locks, journals, or state.
+- Tests use temporary directories and never touch real Codex configuration.
 
-The `Release` workflow runs after a pull request is merged into `main`, or when started manually. It:
+## Troubleshooting
 
-1. Runs syntax checks, tests, and the packed-package smoke test.
-2. Reads the name and version from `package.json`.
-3. Creates the matching GitHub release when missing.
-4. Checks whether that exact version already exists on npm.
-5. Publishes only a version that is not already present.
+### Agents or skills do not appear
 
-Before merging a new release, update `package.json` and `CHANGELOG.md` to the new version. Merges without a version change do not republish the package.
+Restart Codex after installation. Verify the selected scope with `doctor` or `doctor --global`, and confirm that your Codex version is at least the compatibility baseline above.
 
-The npm token must have package read/write permission and must be permitted to publish without an interactive OTP when the account or package requires 2FA.
+### `user-modified`
 
-To publish the current version after adding the secret, open `Actions → Release → Run workflow`.
+The file or setting was changed after installation. The CLI intentionally leaves it untouched. Review the reported path and decide manually whether to retain the custom value or reinstall the package template under a different name.
 
-## Manual npm publication
+### `unsafe-state` or unsafe path component
 
-The package name is unscoped and public. Before the first publish, confirm the name is available and sign in:
+Do not delete the reported file blindly. Check whether `.codex`, `.agents`, `CODEX_HOME`, or one of their parent directories is a symlink or Windows junction. Use a normal directory inside the intended project or user scope.
 
-```sh
-npm view codex-model-router
-npm login
-npm whoami
-```
+### Active or stale lock
 
-Review exactly what will be uploaded:
+An active lock includes the operation and process ID. Wait for that process to finish. A later mutating command automatically removes a stale lock only when the recorded local process is no longer alive. A corrupt or remote-host lock must be inspected manually before removal.
 
-```sh
-npm run check
-npm test
-npm run test:package
-npm pack --dry-run
-npm publish --dry-run
-```
+### Interrupted transaction
 
-Publish from the package root:
+Run `doctor` first. A mutating command automatically rolls back `unfinished` or `recoverable` transactions when all hashes still match. `conflicting` means a managed file changed after interruption; preserve that file and resolve the journal manually rather than forcing an overwrite. `corrupt` means the journal or snapshot cannot be trusted.
 
-```sh
-npm publish
-```
+### Untracked backup already exists
 
-After publication, verify:
+The CLI refuses to replace `config.toml.codex-model-router.bak`. Compare it with `config.toml`, move it to a clearly named safe location, and retry only after confirming its ownership.
+
+### Permission or `CODEX_HOME` errors
+
+For project scope, verify write access to the project. For global scope, print and verify `CODEX_HOME`; do not run with elevated privileges merely to bypass an unexplained path error.
+
+### Manual backup recovery
+
+The managed `.bak` is the exact pre-change configuration. Before restoring it, stop Codex, preserve the current `config.toml` under a new name, verify both files, and restore only within the same project/global scope.
+
+### npx uses an old version
+
+Request the exact version first:
 
 ```sh
-npm view codex-model-router version
-npx codex-model-router --version
+npx --yes codex-model-router@1.2.0 --version
 ```
 
-For maximum security, npm Trusted Publishing can replace the long-lived token later.
+When necessary, inspect the npm cache with `npm cache verify`; avoid deleting unrelated cache directories blindly.
 
-## Safety behavior
+## Security and release integrity
 
-- Refuses malformed or unsafe configuration before writing
-- Uses atomic file replacement and rolls back failed multi-file upgrades where possible
-- Stores a small package-owned state file and one backup only when an existing config is changed
-- Never modifies `AGENTS.md`, shell profiles, editor settings, hooks, MCP servers, telemetry, or environment variables
-- Dry-run creates no files, directories, backups, or temporary state
+Security vulnerabilities should be reported privately according to [SECURITY.md](SECURITY.md).
 
-Restart Codex if newly installed agents or skills are not immediately visible.
+Releases use npm Trusted Publishing through GitHub Actions, verified provenance, exact tag/version validation, current-version-only release notes, workflow linting, and a clean public-registry end-to-end install/doctor/uninstall check before the GitHub Release is created. Maintainer setup and release steps are documented in [MAINTAINERS.md](MAINTAINERS.md).
 
 Codex references: [Subagents](https://developers.openai.com/codex/subagents), [Build skills](https://developers.openai.com/codex/build-skills), and [Configuration reference](https://developers.openai.com/codex/config-reference).

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest stable release receives security fixes.
+
+## Reporting a vulnerability
+
+Do not report security vulnerabilities through a public Issue.
+
+Use GitHub's private security advisory feature for this repository and include:
+
+- affected version and operating system
+- selected project or global scope
+- minimal reproduction steps
+- files or paths affected
+- expected and observed behavior
+
+Do not include npm tokens, OpenAI credentials, private Codex configuration, or unrelated project source code.
+
+Reports involving path escape, unsafe uninstall, transaction recovery, release provenance, or package publication are treated as security-sensitive.

package/lib/manifest.js

@@ -0,0 +1,95 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+
+export const VERSION = packageJson.version;
+
+export const DEFAULTS = Object.freeze({
+  model: "gpt-5.6-terra",
+  model_reasoning_effort: "high"
+});
+
+const luna = `name = "luna"
+description = "Low-risk helper for repeated edits, searches, formatting, extraction, counting, and summaries."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "high"
+developer_instructions = """
+Handle only deterministic, low-risk work delegated by Terra.
+Follow the assigned pattern exactly and return a concise result.
+Escalate ambiguous, security-sensitive, or logic-heavy decisions to Terra.
+"""
+`;
+
+const sol = `name = "sol"
+description = "High-capability specialist for security-sensitive or high-regression-risk work."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "medium"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Review or implement only when explicitly delegated by Terra.
+For review-only tasks, report concrete findings without changing files.
+For implementation tasks, make focused changes, run relevant checks, and report the result to Terra.
+Focus on security, authentication, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state, and regression risk.
+Do not expand the scope beyond the delegated task.
+"""
+`;
+
+const skill = `---
+name: model-router
+description: Route Codex work between Terra, Luna, and Sol with the fewest required agents.
+---
+
+Terra handles ordinary questions, coding, debugging, fixes, testing, and implementation. Never create a Terra subagent.
+Use Luna only for deterministic low-risk repeated edits, bulk patterns, read-heavy searches, formatting, counting, extraction, or summaries; prefer Luna when the same clear operation repeats at least three times.
+Use Sol for security, authentication, authorization, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state changes, high-regression-risk logic, or an explicit review. Prefer review-only delegation first; when implementation or a confirmed fix is explicitly required, Sol may edit files in workspace-write mode and run relevant checks.
+Do not spawn a subagent for a simple question. Use the minimum number of agents and run Luna with Sol only when both independent tasks are required.
+`;
+
+export const TEMPLATES = Object.freeze({
+  luna: Object.freeze({ relative: ["agents", "luna.toml"], content: luna }),
+  sol: Object.freeze({ relative: ["agents", "sol.toml"], content: sol }),
+  skill: Object.freeze({ content: skill })
+});
+
+const legacySolReadOnly = `name = "sol"
+description = "Read-only reviewer for security-sensitive or high-regression-risk logic."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Review only. Focus on security, authentication, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state, and regression risk.
+Report concrete findings to Terra; do not apply fixes.
+"""
+`;
+
+const legacySkillReadOnly = `---
+name: model-router
+description: Route Codex work between Terra, Luna, and Sol with the fewest required agents.
+---
+
+Terra handles ordinary questions, coding, debugging, fixes, testing, and implementation. Never create a Terra subagent.
+Use Luna only for deterministic low-risk repeated edits, bulk patterns, read-heavy searches, formatting, counting, extraction, or summaries; prefer Luna when the same clear operation repeats at least three times.
+Use Sol only as a read-only reviewer for security, authentication, authorization, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state changes, high-regression-risk logic, or an explicit review. Terra applies fixes.
+Do not spawn a subagent for a simple question. Use the minimum number of agents and run Luna with Sol only when both independent tasks are required.
+`;
+
+export const LEGACY_TEMPLATES = Object.freeze({
+  luna: Object.freeze([]),
+  sol: Object.freeze([legacySolReadOnly]),
+  skill: Object.freeze([legacySkillReadOnly])
+});
+
+export const AGENT_EXPECTATIONS = Object.freeze({
+  luna: Object.freeze({
+    name: "luna",
+    model: "gpt-5.6-luna",
+    model_reasoning_effort: "high"
+  }),
+  sol: Object.freeze({
+    name: "sol",
+    model: "gpt-5.6-sol",
+    model_reasoning_effort: "medium",
+    sandbox_mode: "workspace-write"
+  })
+});