git:20260913.a4dd8ba to git:20260921.0e7012b

+ Codex, or Gemini CLI. Runtime-specific diagnostics; Claude has six live

+ binding, podman / docker through the container gateway,

+ per-project scratch directory, the ssh signing key's readability, and `gh` running

+ outside the sandbox — each pointing the

+ sandbox?"* — live probes of SSH agent, port binding, podman /

+ docker through the container gateway, per-project scratch dir.

+ Catches over-restrictive allowlists.

+ user may have one of six independent restrictions, or all

+ six, and discovering them one re-run at a time is annoying.

+ ## The 6 probes

+ The current set covers the six failure modes the catalog

+ Failure modes: `SSH_AUTH_SOCK` is passed through `claude-iso`'s

+ `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 reports as unreachable while the socket is plainly

+ there. The second is the one a signed commit hits as

+ `No private key found for public key`.

+ | `✗ bind: [Errno 1] Operation not permitted` | Fail | The sandbox refuses listening sockets outright; `sandbox.network.allowLocalBinding` is unset. Fails before any egress rule is consulted, so `allowedDomains` changes do not help. |

+ | `✗ bind: ...` (other errno) | Fail | The sandbox blocks `bind(2)` on `127.0.0.1` for another reason. Rare; report the literal error. |

+ ### Probe 3 — Podman / Docker through the container gateway

+ Tests whether the runtime CLI can talk to the [container

+ gateway](../../../../tools/container-gateway/README.md), not the

+ real daemon socket — the sandbox never gets a route to the daemon

+ itself. Run for each of `podman` / `docker` that is on `PATH`; ⊘

+ each that is not installed (this is not a sandbox failure, just an

+ absent prerequisite). Each remaining check narrows down which of

+ the three wiring pieces (env var, running gateway, allowed socket)

+ is missing, in the order a fresh install would hit them.

+ # Two candidates, not the hook's three-way order (which also checks

+ # $MAGPIE_CONTAINER_GATEWAY_SRC and $HOME/.claude/scripts/container-gateway/src

+ # for an operator install): this probe only ever needs to run the read-only

+ # `status` subcommand against a source already reachable from this doctor

+ # session, so it deliberately omits the operator-install path rather than

+ # widen what the probe depends on being readable.

+ gw_src=".apache-magpie/tools/container-gateway/src"

+ [ -d "$gw_src/container_gateway" ] || gw_src="tools/container-gateway/src"

+ status_json=$(PYTHONPATH="$gw_src" python3 -m container_gateway status --project "$PWD" 2>/dev/null)

+

+ gw_state() { # $1=backend -> serving | not-serving | not-running

+ printf '%s' "$status_json" | python3 -c "

+ import json, sys

+ try:

+ d = json.load(sys.stdin)

+ except Exception:

+ print('not-running'); sys.exit()

+ if not d.get('running'):

+ print('not-running')

+ elif '$1' in d.get('serving', []):

+ print('serving')

+ else:

+ print('not-serving')

+ " 2>/dev/null

+ }

+

+ _probe_timeout() { # seconds cmd...; portable across GNU timeout, macOS Homebrew's gtimeout, or neither

+ local secs="$1"

+ shift

+ if command -v timeout > /dev/null 2>&1; then

+ timeout "$secs" "$@"

+ elif command -v gtimeout > /dev/null 2>&1; then

+ gtimeout "$secs" "$@"

+ else

+ "$@" &

+ local cmd_pid=$!

+ (sleep "$secs" && kill "$cmd_pid" 2> /dev/null) &

+ local watchdog_pid=$!

+ wait "$cmd_pid" 2> /dev/null

+ local rc=$?

+ kill "$watchdog_pid" 2> /dev/null

+ wait "$watchdog_pid" 2> /dev/null

+ return "$rc"

+ fi

+ }

+

+ for rt in podman docker; do

+ case "$rt" in podman) url="${CONTAINER_HOST:-}";; docker) url="${DOCKER_HOST:-}";; esac

+ if [ -z "$url" ]; then

+ echo "PROBE: ${rt}-runtime → ✗ ($( [ "$rt" = podman ] && echo CONTAINER_HOST || echo DOCKER_HOST ) unset — gateway not wired into settings)"

+ continue

+ fi

+ # The CLIs read a unix:// URL's authority as a host component, so only the

+ # absolute "unix:///path" spelling reaches the socket: "unix://./x" dials

+ # "/.//x". A relative value still stats fine here (the socket does exist

+ # relative to the cwd), so catch it by shape or the real cause is lost in

+ # the generic failure branch below.

+ case "$url" in

+ unix:///*) ;;

+ unix://*|unix:*)

+ echo "PROBE: ${rt}-runtime → ✗ ($( [ "$rt" = podman ] && echo CONTAINER_HOST || echo DOCKER_HOST )=$url is not absolute — the CLIs do not resolve a relative unix:// value against the cwd; use unix:///<project>/.apache-magpie-local/run/$rt.sock)"

+ continue ;;

+ sock="${url#unix://}"

+ case "$(gw_state "$rt")" in

+ not-running)

+ echo "PROBE: ${rt}-runtime → ✗ (gateway socket missing at $sock — container gateway not running)"

+ continue ;;

+ not-serving)

+ case "$rt" in

+ podman) hint="is the Podman machine started" ;;

+ docker) hint="is Docker Desktop (or the docker daemon) started" ;;

+ esac

+ echo "PROBE: ${rt}-runtime → ✗ (gateway running without a $rt backend — $hint? start it, then restart the gateway)"

+ continue ;;

+ esac

+ if [ ! -S "$sock" ]; then

+ echo "PROBE: ${rt}-runtime → ✗ (gateway socket missing at $sock — container gateway not running)"

+ continue

+ fi

+ if _probe_timeout 15 "$rt" info > /dev/null 2>"${TMPDIR:-/tmp}/$rt-probe.err"; then

+ echo "PROBE: ${rt}-runtime → ✓ ($rt reaches the container gateway at $sock)"

+ else

+ rc=$?

+ err=$(head -1 "${TMPDIR:-/tmp}/$rt-probe.err")

+ case "$rc" in

+ 137|143)

+ # The shell-fallback branch of _probe_timeout kills the child with

+ # SIGTERM (rc 143) or, if it does not respond, SIGKILL (rc 137);

+ # `$err` is typically empty in this case, so name the hang instead

+ # of falling through to an uninformative "rc=143: ".

+ echo "PROBE: ${rt}-runtime → ✗ (no response in 15s — $rt info hung; is the backend daemon stuck?)" ;;

+ *)

+ case "$err" in

+ *"operation not permitted"*|*"Operation not permitted"*)

+ echo "PROBE: ${rt}-runtime → ✗ (connect to $sock denied — add it to sandbox.network.allowUnixSockets)" ;;

+ *"502"*|*"unreachable"*)

+ echo "PROBE: ${rt}-runtime → ✗ (gateway up, backend down: $err)" ;;

+ *) echo "PROBE: ${rt}-runtime → ✗ (rc=$rc: $err)" ;;

+ esac ;;

+ esac

+ fi

+ `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 both an adopter checkout and this

+ framework's own worktree. The `gw_state` check runs **before** the

+ raw socket-file test: a backend `status` does not list under

+ `serving` never gets a socket file in the first place, 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 below is a defensive fallback for an already-serving

+ backend whose socket vanished mid-probe, not the primary check.

+

+ | `✓ <rt> reaches the container gateway at <sock>` | Pass | CLI → gateway → daemon all answer. |

+ | `✗ … unset — gateway not wired into settings` | Fail | The reference `env` block is missing from project settings. |

+ | `✗ gateway socket missing` | Fail | The `SessionStart` hook did not start the gateway, or it exited; check `<project>/.apache-magpie-local/run/container-gateway.log`. |

+ | `✗ gateway running without a <rt> backend` | Fail | `status` reports the gateway up but `serving` does not list this CLI's backend — the Podman machine or Docker daemon behind it is not running. Start it from outside the sandbox, then restart the gateway. |

+ | `✗ connect … denied` | Fail | The gateway socket is not in `sandbox.network.allowUnixSockets`. |

+ | `✗ gateway up, backend down` | Fail | Podman machine / Docker not running on the host; start it from your own terminal. |

+ | `✗ no response in 15s — <rt> info hung` | Fail | `_probe_timeout` killed a stalled `<rt> info` call; the backend daemon behind the gateway is likely wedged — restart it from outside the sandbox. |

+ 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.

+

+ ### 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 punches only specific

+ subpaths writable, so a session whose `TMPDIR` falls back to `/tmp`

+ gets 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 assignment wins

+ over `env.TMPDIR` from any settings file, so the shared root is the

+ expected value and no configuration changes it. Each session still

+ gets a per-project, per-session scratchpad underneath it.

+

+ **Command:**

+

+ ```bash

+ if [ -z "$TMPDIR" ]; then

+ echo "PROBE: project-scratch → ✗ (TMPDIR not set)"

+ elif [ ! -d "$TMPDIR" ]; then

+ echo "PROBE: project-scratch → ✗ (TMPDIR set but directory missing: $TMPDIR)"

+ elif ! touch "$TMPDIR/.doctor-probe" 2>/dev/null; then

+ echo "PROBE: project-scratch → ✗ (TMPDIR not writable inside sandbox: $TMPDIR)"

+ else

+ rm -f "$TMPDIR/.doctor-probe"

+ slug=$(pwd | sed 's|/|-|g')

+ case "$TMPDIR" in

+ *"$slug"*) echo "PROBE: project-scratch → ✓ (per-project + writable: $TMPDIR)" ;;

+ *) echo "PROBE: project-scratch → ✓ (writable; shared session root, which is the harness default: $TMPDIR)" ;;

+ esac

+ fi

+ ```

+

+ **Interpretation:**

+

+ | Result | Status | Meaning |

+ |---|---|---|

+ | `✓ per-project + writable` | Pass | `TMPDIR` resolves under this project's path slug and accepts writes. |

+ | `✓ writable; shared session root` | Pass | The expected value on current Claude Code. Every project on the machine shares this directory, so write through the per-session scratchpad beneath it, or use unique filenames — but there is nothing to fix. |

+ | `✗ TMPDIR not set` | Fail | Tooling falls back to `/tmp`, which is read-only inside the sandbox. |

+ | `✗ directory missing` | Fail | `TMPDIR` names a path nothing has created yet. |

+ | `✗ not writable inside sandbox` | Fail | `TMPDIR` points outside `sandbox.filesystem.allowWrite`. |

+

+ **On ✗ → remediation:**

+ [`docs/setup/sandbox-troubleshooting.md` — Temp files fail with "Read-only file system" under `/tmp`](../../../../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 is asked for a touch — and the

+ touch overlay, which waits for `ssh-keygen` to block, never sees it

+ block.

+

+ **Command:**

+

+ ```bash

+ if [ "$(git config --get gpg.format)" != "ssh" ]; then

+ echo "PROBE: signing-key → ⊘ (gpg.format is not ssh)"

+ else

+ key="$(git config --get user.signingkey)"

+ case "$key" in

+ "") echo "PROBE: signing-key → ⊘ (gpg.format=ssh but user.signingkey unset)" ;;

+ ssh-*) echo "PROBE: signing-key → ✓ (user.signingkey is a literal key, nothing to read)" ;;

+ *)

+ key="${key/#\~/$HOME}"

+ if head -c 1 "$key" >/dev/null 2>"${TMPDIR:-/tmp}/signing-key.err"; then

+ echo "PROBE: signing-key → ✓ ($key readable inside sandbox)"

+ else

+ echo "PROBE: signing-key → ✗ ($key not readable inside sandbox: $(head -1 "${TMPDIR:-/tmp}/signing-key.err"))"

+ fi ;;

+ esac

+ fi

+ # The touch overlay's wrapper, when git is pointed at it: git inside the

+ # sandbox reads the same global config and has to be able to start it.

+ prog="$(git config --get gpg.ssh.program || git config --get gpg.program)"

+ if [ -n "$prog" ]; then

+ prog="${prog/#\~/$HOME}"

+ if head -c 1 "$prog" >/dev/null 2>&1; then

+ echo "PROBE: signing-program → ✓ ($prog readable inside sandbox)"

+ else

+ echo "PROBE: signing-program → ✗ ($prog not readable inside sandbox — every sandboxed signed commit fails with 'cannot exec')"

+ fi

+ fi

+ ```

+

+ **Interpretation:**

+

+ | Result | Status | Meaning |

+ |---|---|---|

+ | `✓ readable inside sandbox` | Pass | `ssh-keygen` will be able to open the public key. |

+ | `✓ literal key` | Pass | `user.signingkey` holds the key text itself; no file is involved. |

+ | `✗ not readable inside sandbox` | Fail | The sandbox's `~/.ssh/` read deny covers the public key; add that one file to `allowRead`. |

+ | `⊘ gpg.format is not ssh` | Skip | Signing goes through gpg (or is off); the previous entry's socket rules are what matter. |

+ | `⊘ user.signingkey unset` | Skip | Misconfigured signing, not a sandbox problem — mention it, do not fail the probe. |

+ | `signing-program → ✓` | Pass | git's signing program (the touch overlay's `gpg-touch-wrap-*` wrapper, or whatever `gpg.ssh.program` / `gpg.program` names) can be started from inside the sandbox. Nothing printed when neither key is set: git uses its default `ssh-keygen` / `gpg` from `PATH`. |

+ | `signing-program → ✗` | Fail | The program git is configured to sign with is read-denied inside the sandbox — for the overlay wrapper, `~/.claude/scripts/` is. Every sandboxed signed commit fails at once with `cannot exec`; add the wrapper's two files to `allowRead`. |

+

+ **On ✗ → remediation:**

+ [`docs/setup/sandbox-troubleshooting.md` — Signed commit fails before any touch when git signs with ssh](../../../../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](../../../../docs/setup/sandbox-troubleshooting.md#signed-commit-fails-with-cannot-exec-of-the-touch-overlay-wrapper)

+ for the program.

+

+ ### Probe 6 — `gh` runs outside the sandbox

+

+ Tests whether `gh` can reach GitHub from a sandboxed Bash call, and

+ if not, whether the `sandbox.excludedCommands: ["gh *"]` exclusion

+ that the framework reference relies on is in place. On macOS a

+ sandboxed `gh` cannot verify TLS or read the keychain

+ (`x509: OSStatus -26276` / `HTTP 401`), so the exclusion is the only

+ thing that makes it work — and the exclusion applies only when

+ every segment of a Bash invocation is `cd …` or `gh …`.

+

+ The probe deliberately runs `gh` through `sh -c` so that the

+ exclusion cannot apply to the probe itself: that shows what an

+ *un-excluded* `gh` does on this machine.

+

+ **Command:**

+

+ ```bash

+ if ! command -v gh > /dev/null 2>&1; then

+ echo "PROBE: gh-sandbox → ⊘ (gh not on PATH)"

+ else

+ out=$(sh -c 'gh api user --jq .login' 2>&1); rc=$?

+ if [ $rc -eq 0 ]; then

+ echo "PROBE: gh-sandbox → ✓ (gh works inside the sandbox; exclusion not needed on this platform)"

+ else

+ excl=$(cat .claude/settings.json .claude/settings.local.json ~/.claude/settings.json 2>/dev/null \

+ | grep -c '"gh \*"')

+ case "$out" in

+ *"OSStatus -26276"*|*"HTTP 401"*)

+ if [ "$excl" -gt 0 ]; then

+ echo "PROBE: gh-sandbox → ✓ (sandboxed gh fails as expected; \"gh *\" is in excludedCommands — keep gh calls to cd/gh-only segments)"

+ else

+ echo "PROBE: gh-sandbox → ✗ (sandboxed gh fails: $(echo "$out" | head -1); \"gh *\" NOT found in excludedCommands)"

+ fi ;;

+ *) echo "PROBE: gh-sandbox → ⚠ (gh failed for another reason, rc=$rc: $(echo "$out" | head -1))" ;;

+ esac

+ fi

+ # A catch-all ask rule prompts on every gh call, reads included:

+ # Claude Code evaluates deny, then ask, then allow, regardless of

+ # how specific the allow rules are.

+ if cat .claude/settings.json .claude/settings.local.json ~/.claude/settings.json 2>/dev/null \

+ | grep -q '"Bash(gh \*)"'; then

+ echo "PROBE: gh-sandbox → ⚠ (catch-all \"Bash(gh *)\" in permissions.ask — every gh call prompts, read-only allow rules never fire)"

+ fi

+ fi

+ ```

+

+ **Interpretation:**

+

+ | Result | Status | Meaning |

+ |---|---|---|

+ | `✓ gh works inside the sandbox` | Pass | Platform lets `gh` verify TLS and read its token inside the sandbox (typical on Linux). |

+ | `✓ … "gh *" is in excludedCommands` | Pass | The known macOS shape, and the framework's exclusion is present. Calls still fail if they are not `cd`/`gh`-only invocations — see the catalog entry. |

+ | `✗ … NOT found in excludedCommands` | Fail | `gh` cannot work inside the sandbox on this machine and nothing runs it outside. |

+ | `⚠ gh failed for another reason` | Warn | Not the catalogued shape (network down, not logged in, …); inspect the message. |

+ | `⚠ catch-all "Bash(gh *)" in permissions.ask` | Warn | Ask beats allow regardless of specificity, so this rule prompts on every read-only `gh` call. Replace it with the explicit write-subcommand list from the reference `.claude/settings.json`. Extra line, printed after the main result. |

+ | `⊘ gh not on PATH` | Skip | `gh` not installed; not a sandbox restriction. |

+

+ `~/.claude/settings.json` is usually unreadable from inside the

+ sandbox, so the exclusion check may only see the project-scope

+ files; if the user keeps the exclusion at user scope, a ✗ here is

+ a false alarm — say so when reporting.

+

+ Even with the exclusion present, a `gh` call is only excluded when

+ every part of the Bash invocation is `cd …` or `gh …`: a pipe, a

+ `$(…)` substitution, a loop, or any file redirection (`> file`,

+ even `> /dev/null`) puts it back in the sandbox. The redirection

+ case is a Claude Code regression tracked in

+ [anthropics/claude-code#95532](https://github.com/anthropics/claude-code/issues/95532);

+ the catalog entry shows the `gh tofile` alias that works around it.

+ When the user reports a `gh` failure that this probe does not

+ reproduce, ask for the exact command line — the shape is usually

+ the answer.

+

+ **On ✗ → remediation:**

+ [`docs/setup/sandbox-troubleshooting.md` — `gh` fails with TLS `OSStatus -26276` or `HTTP 401` inside the sandbox](../../../../docs/setup/sandbox-troubleshooting.md#gh-fails-with-tls-osstatus--26276-or-http-401-inside-the-sandbox).

+

+ > All six probes pass (or are not applicable). The sandbox is

+ > entry* section and (optionally) extend this skill with another