agent-migrate-adapters 0.6.1

# Agent Config Migrate

`agent-migrate` 0.6.1 inventories, sanitizes, converts, imports, transfers, and
synchronizes configuration among Codex, Pi, and Claude Code. It supports local
homes, explicit project workspaces, and SSH config Host aliases. Credentials,
sessions, history, telemetry, caches, and control state are never exported.

中文完整使用说明：[docs/usage.zh-CN.md](docs/usage.zh-CN.md)

| Agent | Tested version | Global root | Project root |
| --- | --- | --- | --- |
| Codex | 0.145.0 | `~/.codex` | `AGENTS.md`, `.codex`, `.agents/skills` |
| Pi | 0.82.1 | `~/.pi/agent` | `AGENTS.md`, `.pi` |
| Claude Code | 2.1.220 | `~/.claude`, `~/.claude.json` | `CLAUDE.md`, `.claude`, `.mcp.json` |

## Install

Install the published crate from crates.io:

```sh
cargo install ethan-acm
agent-migrate --version
```

The crates.io package is named `ethan-acm`; it installs the `agent-migrate`
executable. Rust 1.88 and pnpm 11 are required to build the complete repository
from source.

```sh
pnpm --dir resources/pi-mcp-bridge install --frozen-lockfile
pnpm --dir resources/pi-mcp-bridge run check
cargo build --release
install -m 0755 target/release/agent-migrate ~/.local/bin/agent-migrate
```

## Endpoints And Scope

Endpoints use `<agent>@<host>`, where agent is `codex`, `pi`, or `claude` and
host is `local` or a validated SSH config Host alias. Examples are
`codex@local` and `pi@lab-linux`. Project operations require `--scope project`
and an explicit `--workspace`; discovery never walks above that directory.

Global options include `--format human|json`, `--root`, `--workspace`,
`--state-root`, and `--dry-run`. JSON results use schema `1.0`. Dry runs do not
lock, snapshot, write, transfer, start a bridge, or invoke a conversation.

## Commands

```text
agent-migrate scan <endpoint> [--scope global|project]
agent-migrate export <endpoint> --output bundle [--scope ...]
agent-migrate convert --input bundle --target <agent> --output converted-bundle
agent-migrate diff --input bundle --target <agent>
agent-migrate import <endpoint> --input bundle [--map /source=/target]
agent-migrate transfer --input bundle.age --host <ssh-alias>
agent-migrate sync <source> <target> [--source-root ... --target-root ...]
agent-migrate doctor <endpoint> [--scope global|project] [--conversation]
agent-migrate rollback <snapshot-id>
agent-migrate watch <source> <target>
agent-migrate repo init|snapshot|status ...
agent-migrate recommend [--host <ssh-alias>]
agent-migrate completions bash|zsh|fish
```

`--map` is repeatable. It rewrites declared absolute path fields in structured
settings and MCP resources using component-boundary matching. Both sides must
be normalized absolute paths. An absolute path field that is in mapping mode
but has no matching declaration blocks import.

Use `--accept-lossy` for resources reported as `lossy` or
`preserved_unavailable`. Pi MCP conversion additionally requires
`--bridge-healthy`; the generated Pi extension uses the bundled MCP SDK bridge
and starts only servers declared in its sanitized configuration.

## Bundle And Secrets

Bundle schema 1.0 uses an inspectable directory with `manifest.yaml`, typed
resource directories, and `secrets.ref.yaml`. It stores SHA-256 for every file,
sanitized content, path mappings, and logical secret references. A single-file
`.yaml` wire format remains accepted for compatibility and encrypted transport. Secret values
are replaced with `${SECRET_REF:NAME}`. There is no include-secrets mode.
Encrypted transfers use age X25519 recipients, deterministic tar metadata,
SFTP staging named by ciphertext SHA-256, and fixed JSON requests over
`agent-migrate remote serve`.

SSH uses the local OpenSSH configuration, SSH Agent, ProxyJump, and host-key
policy. Password flags, shell endpoints, arbitrary remote commands, automatic
package installation, and disabled host-key checks are not available. The
same major version of `agent-migrate` must be installed remotely.

## Transactions And Recovery

Imports take a target-scoped advisory lock, reject conflicts by default,
snapshot every touched path with its hash and mode, atomically replace files, and automatically
restore the snapshot after write or doctor failure. `--conflict replace`
permits known targets to be replaced. `merge` is limited to structured JSON,
TOML, or YAML; `rename` applies to named skills, commands, and agents. Successful
imports write JSON and Markdown reports under the state root. The import result returns a snapshot ID:

```sh
agent-migrate --root /target --state-root /state rollback <snapshot-id>
```

Encrypted staging is removed after a successful import. A failed remote
operation reports a fixed `agent-migrate remote cleanup <sha256>` recovery
command while retaining only encrypted data.

## Exit Codes

| Code | Meaning |
| --- | --- |
| 0 | success |
| 2 | invalid input |
| 3 | target conflict |
| 4 | compatibility, lossy, bridge, or path-mapping block |
| 5 | remote transport or protocol failure |
| 6 | transaction or rollback failure |
| 7 | external Agent or dependency failure |
| 8 | internal invariant or serialization failure |

## Quality Gates

```sh
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo nextest run --workspace --all-features
cargo deny check
cargo machete
pnpm --dir resources/pi-mcp-bridge run check
scripts/check-file-size.sh
cargo build --release
```

`tests/integration/ssh_roundtrip.sh` drives real OpenSSH/SFTP against the
Docker Linux fixture in both directions. `tests/integration/real_agents.sh`
runs the opt-in exact-marker conversation against installed authenticated
Agents without migrating their authentication or persisting sessions.
`tests/integration/release_surface.sh` drives every local command through the
release binary and includes the isolated secret, symlink, and shell-injection
probes in `tests/security/release_security.sh`.