potiuk opened a new pull request, #291:
URL: https://github.com/apache/airflow-steward/pull/291
## Summary
New
[`docs/setup/sandbox-troubleshooting.md`](docs/setup/sandbox-troubleshooting.md)
catalogs known sandbox-shaped failure modes — the cases where the
secure-agent setup's sandbox blocks a legitimate workflow and the
surfaced error doesn't name the sandbox as the cause. Three seed
entries cover the failures actually encountered in recent
sessions; the catalog grows by experience (new entries appended
as they're hit).
### The three seed entries
| Failure | Symptom | Cause | Fix |
|---|---|---|---|
| SSH agent / Yubikey unreachable | "agent refused operation", "Permission
denied (publickey)" | Socket path
(`/private/tmp/com.apple.launchd.*/Listeners`) not in `allowRead` despite
`SSH_AUTH_SOCK` passing through env | Add the launchd socket glob to
`sandbox.filesystem.allowRead` |
| Test cannot bind to localhost port | `Errno 13 Permission denied`,
`Address already in use` red herrings | Loopback not in
`sandbox.network.allowedDomains`; bind works, but test's own HTTP client to
`127.0.0.1:NNNN` blocked | Add `localhost` and `127.0.0.1` to `allowedDomains` |
| Docker / Podman socket denied | "Cannot connect to the Docker daemon" |
`Read(~/.docker/**)` denial (protecting credentials) also blocks the runtime
socket | Allow `~/.docker/run/docker.sock` specifically; narrow the deny to
`config.json` + `contexts/**` |
### Entry shape
Every entry is structured identically so a future reader can grep
into the page and pattern-match:
1. **Symptom** — verbatim error text (grep target).
2. **Root cause** — which sandbox layer + why the restriction
exists.
3. **Fix** — concrete settings.json snippet with per-entry
rationale.
4. **Notes** — platform variants, alternative paths, when *not*
to apply the widening.
A closing *Adding a new entry* section documents the shape so
new failure modes land in the same form.
### Cross-references
- `docs/setup/README.md` *Deep documentation* — new bullet.
- `docs/setup/secure-agent-setup.md` *See also* — new bullet.
### Why docs-only
This PR deliberately does **not** widen the framework's reference
`.claude/settings.json`. Framework-internal work doesn't need the
three widenings (no test binds to localhost in the framework
itself, no docker dependency, no SSH-agent path beyond what
`~/.gnupg/` already covers). Dogfooding a kitchen-sink set of
allowances would narrow the framework's own security posture
without buying anything. The catalog is the discoverable
resource — adopters apply the widenings to their own
`~/.claude/settings.json` as they hit each case.
### `.typos.toml` entry
Adds `ERRO` to `extend-identifiers` so the doc can quote docker's
actual truncated log prefix (`ERRO[0000] …`) verbatim. Preserves
the greppability of the catalog against the literal error strings
users see.
### Sequencing
This is **PR-1 of 3** addressing sandbox friction:
- **PR-1 (this PR)** — catalog + cross-links. Reference resource.
- **PR-2 (next)** — `setup-isolated-setup-doctor` skill: in-session
probes that map known failure shapes back to entries in this
catalog. Will reference this doc for remediation text.
- **PR-3** — PostToolUse hint hook that annotates sandbox-shaped
errors after the fact. Will reference this doc too.
## Test plan
- [x] `prek run --files docs/setup/sandbox-troubleshooting.md
docs/setup/secure-agent-setup.md docs/setup/README.md .typos.toml` —
markdownlint / doctoc / typos / private-key / whitespace all pass.
- [x] All anchors in the new file resolve when rendered (doctoc
auto-generated the TOC).
- [ ] First adopter who hits a sandbox failure on one of the three
cataloged cases: verify the entry text is sufficient to find +
fix without further guidance.
- [ ] Next sandbox failure NOT in the catalog: appended as a new
entry in the same shape per *Adding a new entry*.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
