/sync

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

Sync

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 stays inert; explicit setup or sync invokes installed-package GitHub reader-rule helper. Never substitute approval-UI saved prefix or direct home-file edit for this managed lifecycle. Before plugin removal, run `agent-shims remove` while manager is still available. 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 reader-rule 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 persistent GitHub reader approval in Codex home.

Workflow

01: Create the result directory

Create `.reports/codex/sync/<timestamp>/` 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. Do not select cache by lexical or modification-time "latest" rules.

Inspect managed reader-rule state without writing: report absent, current, stale-version, or unverifiable. Absence is valid before setup and does not authorize installing rules during `check`.

Inspect optional `rules/codex-rig-pr-collection.rules` with the same ownership/integrity discipline. Record its exact approved PR URLs; absent is the default. Approved refresh carries forward only those managed targets to the new verified installed collector. New targets require explicit setup with repeatable `--approve-pr <canonical-pr-url>` on the rule helper; never infer targets from PR metadata or migrate UI-saved collector grants. Disclose collector fetch, supported output writes, and safe local checkout in addition to existing reader-wide scope. Teardown removes both owned files. Any invalid managed PR file blocks all permission updates before backups or writes.

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, reader-rule changes, and rollback limit. Disclose full wrapper scope: GitHub reads, local PR checkout, and output-file writes. Include exact legacy-rule migration 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 the full networked CLI approval and denial contract in `../../shared/native-skill-contract.md` to the complete owning command for each Git marketplace add/upgrade or `sync_codex.py` wrapper that owns one. The operation-specific brief is: `Action and purpose`: refresh the approved marketplace and reconcile the selected Codex Rig plugin; `External capability`: marketplace download and lifecycle refresh; `Credential behavior`: use configured Codex marketplace access without reading or changing credentials; `Filesystem and worktree effects`: change the local plugin cache and Codex-home plugin state, never the source worktree; `Retry policy and safe denial outcome`: stop the turn on denial and leave the checked state unchanged. Runtime approval is separate from lifecycle approval and never expands marketplace, plugin, ref, or mutation scope; never request a broad `codex` approval prefix. Local marketplace/plugin listing remains sandboxed. `codex plugin add` from the configured snapshot needs no separate network escalation; an approved wrapper already owns its nested marketplace add/upgrade.

codex plugin marketplace add Borda/AI-Rig
codex plugin marketplace upgrade borda-ai-rig
codex plugin add codex-rig@borda-ai-rig

For release pin, supply `--ref` with published revision whose Codex Rig packa