Isolated Setup Doctor

<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):
     <project-config> → adopting project's `.apache-magpie/` directory -->

setup-isolated-setup-doctor

Runtime routing (run before the Claude-specific probes)

Use the operator's explicitly requested runtime when supplied; otherwise use the active session's runtime. An installed executable or configuration directory alone does not select a runtime. For the routing below, treat that selection as the active harness.

When the active harness is Codex, first require the static verification in docs/adapters/codex.md, then run the shared live environment probes inside the active Codex sandbox. Attribute failures separately to native sandbox/network denial, approval policy, or the POSIX agent-iso layer. Do not prescribe a .claude settings change for a Codex failure. Then stop before the Claude-specific branch below.

When the selected runtime is Gemini CLI, follow docs/adapters/gemini.md: verify the profile first, then diagnose the actual tool result in the active Gemini session. Distinguish policy refusal, sandbox expansion, hook or trust failures, and wrapper or authentication problems. Do not require Claude configuration or prescribe Claude settings changes; then stop before the Claude-specific probes below.

When the harness is Claude Code, continue below. If the harness cannot be determined, ask once.

This is the diagnostic layer over the secure agent setup. verify checks statically that the setup is installed right, catching drift and missing pieces. This skill checks whether common workflows are functionally blocked by the sandbox as configured, catching over-restrictive allowlists. (install puts the setup in place; update reports framework drift.)

Run verify first when the install itself is in doubt: fresh machine, recent upgrade, sandbox-state surprise. Run doctor when the install is known good and a workflow fails in a sandbox-shaped way: agent unreachable, socket error, port permission error.

Every probe maps to a numbered entry in docs/setup/sandbox-troubleshooting.md. The doctor identifies which entry applies now; it does not re-explain the remediation. If a fail shows a failure mode not catalogued there, propose appending a new entry per the catalog's Adding a new entry section.

Golden rules

• Read-only. Each probe is a small, deterministic, side-effect-free check. The skill never edits a settings file, never runs a command with dangerouslyDisableSandbox, and never installs anything. If a check fails, surface it and point at the catalog entry; do not auto-fix.
• Run every probe, even on early failure. Do not stop at the first ✗. A user may have one of eight independent restrictions or all eight, and finding them one re-run at a time is annoying.
• Distinguish ✗ (failing) from ⊘ (not applicable). ✗ means the probe ran and the sandbox blocked it. ⊘ means the probe was skipped because a prerequisite is absent (e.g. no docker / podman on PATH → docker probe ⊘, not ✗).
• Surface evidence. Each report line names the probe command, the exit code, and the relevant stderr snippet. "Looks blocked" is not useful; "ssh-add -l → rc=2 → Could not open a connection to your authentication agent" is.
• Map each ✗ to a catalog entry. The fail report links directly to the matching section of docs/setup/sandbox-troubleshooting.md. Do not paraphrase the remediation; the catalog is the single source of truth.

The 8 probes

The probes cover the catalog's failure modes that a sandboxed command can detect on its own; the signing entries that need a live touch or a terminal are verified by setup-isolated-setup-verify check 10 instead. New probes are added when new entries land in the catalog, so the two stay in lock-step.

Probe 1 — SSH agent / Yubikey reachable

Tests whether ssh-agent is reachable from inside the sandbox. Two failure modes: SSH_AUTH_SOCK passes through claude-iso's env whitelist but the socket file is not in sandbox.filesystem.allowRead, so the agent's ssh / git push subprocesses cannot even stat(2) it; or, on macOS, the file is readable but its path is missing from sandbox.network.allowUnixSockets, so connect(2) is denied and the agent looks unreachable while the socket is plainly there. A signed commit hits the second as No private key found for public key.

Command:

bash <skill-dir>/scripts/probe-1-ssh-agent.sh

Interpretation:

On ✗ → remediation: docs/setup/sandbox-troubleshooting.md — SSH agent / Yubikey appears unreachable from inside the sandbox.

Probe 2 — Localhost port bind

Tests whether a process inside the sandbox can bind to a loopback port AND then talk to itself over loopback. The catalog documents the second half failing (egress proxy blocks 127.0.0.1).

Command:

bash <skill-dir>/scripts/probe-2-localhost-bind.sh

Interpretation:

On ✗ → remediation: docs/setup/sandbox-troubleshooting.md — Test cannot bind to a localhost port.

Probe 3 — Podman / Docker through the container gateway

Tests whether the runtime CLI can talk to the container gateway, not the real daemon socket; the sandbox never gets a route to the daemon itself. Run it for each of podman / docker on PATH; ⊘ each one not installed (an absent prerequisite, not a sandbox failure). The remaining checks narrow down which of the three wiring pieces (env var, running gateway, allowed socket) is missing, in the order a fresh install would hit them.

Command:

bash <skill-dir>/scripts/probe-3-container-gateway.sh

status_json comes from the gateway's own read-only status subcommand. The doctor may call it from inside the sandbox, since it neither binds a socket nor touches the daemon. gw_src picks the adopter's pinned snapshot (.apache-magpie/tools/container-gateway/src) when present, else the framework repo's own tree (tools/container-gateway/src), so the same probe runs in an adopter checkout and in this framework's own worktree. The gw_state check runs before the raw socket-file test. A backend that status does not list under serving never gets a socket file, so testing -S "$sock" first would misreport "gateway not running" for the "running, but this backend's machine/daemon is down" case. The -S test is a defensive fallback for an already-serving backend whose socket vanished mid-probe, not the primary check.

Interpretation:

An empty podman machine list from inside the sandbox is a read denial on the machine's directory, not proof that no machine exists. Decide the machine's real state from outside the sandbox, per the catalog entry below.

On ✗ → remediation: docs/setup/sandbox-troubleshooting.md — Docker / Podman command fails with a socket error.

Probe 4 — Per-project scratch directory (TMPDIR)

Tests whether the session has a writable scratch directory. The sandbox mounts the host /tmp read-only and makes only specific subpaths writable, so a session whose TMPDIR falls back to /tmp has no scratch area at all.

TMPDIR landing on the shared session root rather than a per-project directory is not a finding. Claude Code sets TMPDIR itself when it builds the sandbox, and that wins over env.TMPDIR from any settings file, so the shared root is expected and no configuration changes it. Each session still gets a per-project, per-session scratchpad beneath it.

Command:

bash <skill-dir>/scripts/probe-4-scratch-dir.sh

Interpretation:

On ✗ → remediation: docs/setup/sandbox-troubleshooting.md — Temp files fail with "Read-only file system" under /tmp.

Do not propose env.TMPDIR in a settings file as the fix. Claude Code overrides it when it builds the sandbox, so the setting is accepted and silently has no effect. The giveaway is a directory that exists, is named exactly as configured, and stays empty. The catalog entry above covers what is actually actionable.

Probe 5 — Signing key readable (gpg.format=ssh)

Tests whether the public key git hands to ssh-keygen -Y sign can be opened from inside the sandbox. Failure mode: the framework denies ~/.ssh/ wholesale, so with gpg.format=ssh every signed commit fails before the hardware key asks for a touch. The touch overlay, which waits for ssh-keygen to block, never sees it block.

Command:

bash <skill-dir>/scripts/probe-5-signing-key.sh

Interpretation:

On ✗ → remediation: docs/setup/sandbox-troubleshooting.md — Signed commit fails before any touch when git signs with ssh for the key, and docs/setup/sandbox-troubleshooting.md — Signed commit fails with "cannot exec" of the touch-overlay wrapper for the program.