/sync

name: sync
description: Dry-run active plugin cache drift; refresh/reinstall only with approval; keep shims separate.

> Before asking, read [User Questions](../../shared/codex-user-questions.md).

Sync

> Task-size routing follows [Proportional Execution](../../shared/native-skill-contract.md#proportional-execution); this skill's specialized lifecycle and acceptance checks remain authoritative.

Inspect and refresh the public-GitHub Codex Rig plugin through supported Codex CLI operations. Never copy files into an installed cache, edit Codex configuration by hand, or treat cached package directories as mutable source trees.

Sync never mutates external agent files. Direct plugin installation does not install Codex-home permissions; explicit setup or sync invokes the installed-package GitHub profile helper preserving explicit default permissions and supplying `local-workflow` when no default exists. This checkout separately defines a project-local opt-in profile. Never edit Codex home by hand in place of this managed lifecycle. Before plugin removal, run `agent-shims remove` while manager is still available. On native Windows, where `agent-shims remove` is platform-blocked, run `agent-shims doctor` instead, record its reported residue, and proceed with that documented residue; manual shim removal stays the user's action. After refresh or reinstall, run `agent-shims doctor` to report prior shim residue; new installation and relinking remain platform-blocked. Report unknown or modified `codex-rig-*.toml` files without removing, adopting, or repairing them.

Input Schema

{
  "mode": "check|refresh",
  "marketplace": "borda-ai-rig",
  "plugin": "codex-rig@borda-ai-rig",
  "ref": "optional Git ref; omitted follows the remote default branch",
  "done_when": "active selection, package identity, and profile ownership/integrity are recorded; an approved refresh is reinstalled and rechecked"
}

Only frozen marketplace and plugin identifiers are accepted. `check` is default and is read-only. `refresh` requires explicit user approval because it fetches marketplace state, changes local plugin cache, and manages the opt-in GitHub-read profile in Codex home.

Workflow

01: Create the result directory

Run `create_run.py --skill sync` per `../../shared/helper-cli-contract.md` in consuming project. Record Codex CLI version, resolved executable, `CODEX_HOME` presence without secret values, operating system, and requested mode.

02: Inspect current state without mutation

Run authoritative help for available CLI, then collect:

codex plugin marketplace list --json
codex plugin list --marketplace borda-ai-rig --json

If documented `--json` option is absent, capture text form and mark structured comparison unavailable. Never invent flag. Record exactly one of: `not-configured`, `not-installed`, `disabled`, `active`, `ambiguous`, or `cli-unsupported`.

For one active installation, resolve selected cache path reported or implied by observed CLI contract. Require regular `.codex-plugin/plugin.json` and `package-manifest.json`; reject symlinks, path escape, duplicate selections, name/version disagreement, unsupported manifest schema, and package-file hash mismatch. Never select cache by lexical or modification-time "latest" rules.

Inspect the managed `github-read` config state without writing: report absent, current, or unverifiable. Inspect legacy plugin-owned reader and PR rules for safe removal; an edited or unrecognized owned rule blocks setup before writes. Absence is valid before setup and does not authorize installation during `check`.

02b: Global instruction health

At explicit check or after an approved refresh, run `PLUGIN_ROOT/bin/python PLUGIN_ROOT/scripts/install_global_agents.py --check --source <installed-package>/assets/AGENTS.md --codex-home <home>`, where `PLUGIN_ROOT` and `<installed-package>` are the selected cache path from step 02. On native Windows use `PLUGIN_ROOT/bin/python.cmd` instead of `PLUGIN_ROOT/bin/python`. The block renders the plugin root, so a marketplace-checkout `--source` needs `--plugin-root <installed-package>` or reports a current block as `stale-managed-template`. A nonzero result is degraded instruction composition even when package hashes pass. Report overlapping or stale global policy and the bounded recognizable legacy skill signatures; do not declare healthy or delete user skills automatically. For a verified old duplicate prefix, prepare its exact digest and review the prefix before offering the separate `--migrate-legacy-prefix-sha256` lifecycle action. That action backs up the entire file and preserves the custom suffix; it does not remove legacy skills. Source checkout edits do not update an active installation.

03: Report external-agent residue without touching it

Read-only scan user agent directory for exact `codex-rig-*.toml` names. Record names and hashes, never file bodies. Classify every match `unmanaged-or-unknown` unless compatible lifecycle manager and its ownership state are available and verified. Plugin-only sync never deletes or overwrites match.

04: Stop after dry run unless refresh was explicitly approved

Show installed state, marketplace source, configured ref or default-branch tracking, resolved revision when marketplace checkout exposes it, current version, package verification result, possible external-agent residue, proposed commands, network/cache effects, profile changes, and rollback limit. Disclose GitHub reads, local PR checkout, output-file writes, `.git` workspace write access, and proxy destination rules. Include legacy-rule removal and backups in approved effects. Ask for approval before `refresh`. A check-only request, missing approval, ambiguous source, foreign marketplace, or unverified active package stops without mutation.

05: Refresh through the Codex CLI

After approval, use only commands confirmed by authoritative help:

Apply full networked CLI approval/