clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 44

docs: truss analysis of jail-spawn Permission Denied + debugging reference #132

Merged
clawdie merged 1 commit from docs/truss-spawn-analysis into main 2026-06-21 17:23:45 +02:00
Conversation 0 Commits 1 Files changed 2 +50
2 changed files with 50 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/README.md
View file

@ -16,3 +16,5 @@ A quick-reference guide to every document in this folder.
| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All |
| [`MULTI-AGENT-HOST-PLAN.md`](MULTI-AGENT-HOST-PLAN.md) | **Current sprint**: multi-agent task-board tests + CLI surface gaps | All agents |
| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | ISO boot validation, Pi spawn path, cost mode enforcement (P2/P3 done) | All agents |
| [`TRUSS-SPAWN-ANALYSIS.md`](TRUSS-SPAWN-ANALYSIS.md) | truss trace of jail-spawn Permission Denied — root cause + fix | Debugging |
| [`VAULT-PROVISION-FIRST-PROOF.md`](VAULT-PROVISION-FIRST-PROOF.md) | First-proof runbook: vault → jail → `.env` chain (clean CLI) | Agents, Sam |

48
docs/TRUSS-SPAWN-ANALYSIS.md Normal file
View file

@ -0,0 +1,48 @@
# truss Analysis — colibri-daemon Jail Spawn (2026-06-21)
**Trace saved:** `/tmp/daemon.truss` (1964 lines, captured during successful spawn)
## The Bug
The daemon could not spawn agents inside jails. `colibri spawn-agent --jail-name`
returned "Permission denied (os error 13)" even though `sudo -n jexec proof0 ...`
worked fine from the shell.
## What truss Revealed
Two independent issues, both masked by the same EACCES error:
### 1. Bare command names in daemon(8) PATH
The daemon constructed spawn commands with bare names (`sudo`, `jexec`).
Under `daemon(8) -u clawdie`, the inherited PATH may be empty or reordered,
so `execvp` missed `/usr/local/bin/sudo` and returned EACCES.
**Fix:** `resolve_program()` — absolutizes bare names by searching a fixed
list (`/usr/local/sbin`, `/usr/local/bin`, `/usr/sbin`, `/usr/bin`, `/sbin`,
`/bin`), returning the first executable found. PR #131.
### 2. Staging directory owned by root
For jailed spawns with environment variables, the daemon's
`prepare_spawn_command` stages files under the jail root at
`<jail_root>/var/run/colibri-stage/<stage_id>/`. This directory was
created by a previous run (as root) and was mode 755 root:wheel.
The daemon runs as `clawdie` and could not write staging files there.
**Fix:** `chmod 777 <jail_root>/var/run/colibri-stage` (or, better:
`agent-jail-bootstrap.sh` should pre-create this directory with appropriate
ownership).
## The Winning Spawn
```
program=/usr/local/bin/sudo requested=sudo
args=["-n", "jexec", "proof0", "/bin/sh",
"/var/run/colibri-stage/<id>/launch.sh",
"/var/run/colibri-stage/<id>/env.sh", "-",
"/usr/local/bin/colibri-test-agent"]
path=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```
Agent spawned, vault provision ran, `.env` written. Track A complete.