Skip to content

Commit 5d1a877

Browse files
wz-gsaOpenCode Agentmogul
authored
feat(patterns): add pi-coding-agent acq-kit (earendil-works/pi, npm install, unprivileged startup-only) (#399)
* feat(patterns): add pi-coding-agent acq-kit Installs earendil-works/pi (@earendil-works/pi-coding-agent) via the standard npm registry path, unprivileged, startup-phase-only — no install phase, matching openchamber's settled pattern rather than prime-agent's still-in-flight root-install-phase skeleton. Ships ahead of the in-flight prime-agent kit (#368) by design: a completed consensus vote picked pi specifically to validate the unprivileged/agent-owned/startup-only install pattern on a materially simpler target (no native-module postinstall, no Python/ IPython kernel bootstrap) before returning to prime-agent's heavier complexity. Deliberately avoids pi.dev/install.sh (a mutable live script with an interactive Node/npm preflight path) in favor of the same underlying npm command, pinned to a specific reviewed version rather than "latest". Model-provider config (USAi models.json) is deliberately deferred — an earlier draft shipped a functionless empty-array placeholder with no emitter to populate it; cut rather than shipped as scaffolding, to land later with a real pi.mjs emitter. Verified live on msb (fresh install, idempotent re-run, malicious version-string rejection, old-Node rejection, CA-decode-failure logging, registry-timeout bounding) and via validate-kits.py --strict, scan_unsafe_shell.py, and shellcheck. Co-authored-by: OpenCode Agent <[email protected]> * fix(patterns): address adversarial review findings on pi-coding-agent kit - Register pi-coding-agent (and the previously-missing prime-agent) in acq-kits/README.md's top-level kit table — it was registered in kits.yaml but never listed in the human-facing index. - Use mktemp for the CA-decode-failure error log, matching the install log's own collision-avoidance in the same script (was a hardcoded /tmp path; not exploitable in this kit's single-tenant threat model, but an unjustified inconsistency within one script). - Tighten the --ignore-scripts residual-risk comments in spec.yaml and the install script: verified every transitive dependency individually (not just the top-level package) has no lifecycle script, and note that --ignore-scripts blocks lifecycle hooks only, not npm's ordinary bin-linking step. Found via two parallel adversarial review passes against PR #399 (one targeting schema/repo-convention drift, one targeting the shell script itself) that assumed every existing claim was wrong until independently re-verified. All fixes re-verified live on msb (fresh install, idempotent re-run, CA-decode-failure now showing the mktemp'd filename) and via validate-kits.py --strict, scan_unsafe_shell.py, shellcheck, and markdownlint-cli2. Co-authored-by: OpenCode Agent <[email protected]> * fix(patterns): address pi-coding-agent review findings (PATH, CA persistence, missing kit files) Fixes 5 findings from a PR review (patterns#399): 1. pi was not reachable after install: npm prefix moved from $HOME/.npm-global (not on the guest's default PATH) to $HOME/.local (is). Verified live via a bare, fresh `sh -c` probe with zero PATH massaging. 2. The runtime CA-bundle claim was false: an install-time-only NODE_EXTRA_CA_CERTS export never reached a `pi` process launched later in a separate shell. Fixed with a thin wrapper at $HOME/.local/bin/pi that rebuilds the bundle and re-execs the real binary on every invocation, itself rebuilt every boot (not just on a fresh install) so it self-heals an already-installed sandbox. Found and fixed two additional bugs during implementation, live: an idempotent-re-run regression (lost track of the real binary path once npm's symlink was replaced by the wrapper -- fixed with a sidecar cache file) and a symlink-follow clobber (naively redirecting into the still-live npm symlink truncated the real binary itself -- fixed by removing the symlink first). Verified across 3 consecutive boots with no regressions. 3. scripts/verify, TROUBLESHOOTING.md, and docs/decisions/ were missing despite being mandatory per acq-kits/README.md. Added, matching the sibling kits' conventions -- scripts/verify's step 4 specifically probes `command -v pi` through a bare sh -c with no PATH injection, the exact check that would have caught finding 1. Live-ran the full offline + RUN_ACQ=1 suite: 7/7 live checks pass. 4. Design rationale was duplicated across spec.yaml, README.md, and the install script. Consolidated into docs/decisions/ (two ADRs, matching the sibling kits' one-decision-per-file convention); the other three now cite it instead of restating it. 5. A leaked CA-decode temp file. Fixed: a single shared install log now serves both the CA-decode-failure and npm-install-failure paths. Verified live -- no leftover files after any boot. Verified: validate-kits.py --strict (clean for pi-coding-agent; the one failure in the run is __pycache__, a pre-existing unrelated repo issue), sh -n + shellcheck + scan_unsafe_shell.py (all clean), markdownlint-cli2 (0 issues), and the full live msb regression suite. Co-authored-by: OpenCode Agent <[email protected]> * fix(patterns): address pi-coding-agent follow-up review findings Responds to basiliskus's six September 15 follow-up asks on PR #399: - Trim duplicated design rationale from spec.yaml/README.md/install script comments down to a single citation of docs/decisions/, matching the header's own stated intent (finding: remaining duplicated rationale). - Add scripts/verify step 4b: confirms `pi` resolves to this kit's CA-bundle wrapper (exports NODE_EXTRA_CA_CERTS), not npm's bare bin symlink. Step 4 alone only proved something resolved on PATH, not that it was the wrapper (finding: add a verify step for the wrapper). - Simplify verify step 8 (CA-decode failure): the CA-bundle block runs unconditionally on every boot, so the forced-removal-and- restore dance around the decode-failure probe was unnecessary. Fixed a real severity bug in the same step: a missing decode- failure message now reports `bad`, not `warn` (finding: simplify verify step 8). - Move the per-boot install log from a random mktemp path under /tmp to a fixed, truncated-per-run $HOME/.local/state/pi-coding-agent/install.log, and fix two diagnostics (TROUBLESHOOTING.md, scripts/verify step 5) that still referenced the old, now-nonexistent glob pattern (finding: fixed log path). - Guard the wrapper's NODE_EXTRA_CA_CERTS export on `[ -s "$_ca" ]`, matching the same guard already used earlier in the script, so a boot with no proxy CA and no system bundle does not point at a useless zero-length cert file. Switch the wrapper to `exec "$_pi_real"` rather than hardcoding `exec node`, preserving whatever interpreter the real binary's own shebang declares (finding: fixed wrapper nits). - Remove review-thread narration ("the review finding this file exists to address", "REGRESSION GUARD: the review's...") from code comments in favor of durable prose describing the same regression class, per this repo's own durable-references convention (finding: drop review narration comments). Verified: sh -n, shellcheck --severity=warning (0 issues on both scripts), scripts/scan_unsafe_shell.py (0 errors/warnings), validate-kits.py --strict (pi-coding-agent OK), markdownlint-cli2 (0 issues), and a live RUN_ACQ=1 scripts/verify end-to-end run on a real msb sandbox — all 8 live steps pass, including the new step 4b and the corrected step 8 severity. Co-authored-by: OpenCode Agent <[email protected]> * fix(pi-coding-agent): address basiliskus's 4th-round follow-up review Responds to basiliskus's September 17 re-review on PR #399: - Rationale still duplicated in the install script: trimmed the npm-prefix, --ignore-scripts, and CA-bundle-wrapper comment blocks (pi-coding-agent-install.sh:102-130, :158-172, :197-217) down to one-line pointers, matching what spec.yaml/README.md already do. 295 -> 245 lines. - Two dangling pointers: spec.yaml and README.md pointed at docs/decisions/ for the install-method choice (npm vs pi.dev/install.sh) and the --ignore-scripts residual risk, but neither existing ADR (ca-bundle-wrapper-not-env-var.md, local-prefix-not-npm-global.md) actually covers either. Rather than add a third ADR for reasoning that already lives correctly in one place, dropped the dangling pointers and pointed to the actual location instead (the install script's own comments; README.md's "Install method"/"Supply-chain notes" sections). - Narration remnants: removed the mktemp-history restatement (pi-coding-agent-install.sh:88-97), "not fixed here, since that's a pre-existing, separately-tracked concern" (:128-130), and "previously with no regression guard of its own" (scripts/ verify:247-254). - Stale bits from 5c47a63: ca-bundle-wrapper-not-env-var.md:122's "this decision's runtime rebuild" -> "boot-time wrapper rewrite" (the wrapper is rewritten on every boot, nothing is rebuilt "at invocation"); removed scripts/verify's now-unused warn() helper (step 8 already FAILs outright, nothing calls warn() anymore); the step 6 comment now describes the guard's actual current shape (`if ! command -v pi >/dev/null 2>&1; then …fi`), not the `|| { … }` shape from an earlier revision. Verified: sh -n and shellcheck --severity=warning (0 issues) on both modified scripts; scripts/scan_unsafe_shell.py (0 errors/warnings); validate-kits.py --strict (pi-coding-agent OK); markdownlint-cli2 (0 issues); a live RUN_ACQ=1 scripts/verify end-to-end run against a real sandbox — all 8 live steps pass, including the wrapper check (4b), the idempotent re-run (6), the bad-version rejection (7), and the CA-decode-failure surfacing (8). Co-authored-by: OpenCode Agent <[email protected]> --------- Co-authored-by: OpenCode Agent <[email protected]> Co-authored-by: Bret Mogilefsky <[email protected]>
1 parent b3afd89 commit 5d1a877

9 files changed

Lines changed: 1267 additions & 5 deletions

File tree

‎integrations/isolation/acq-kits/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ not agent behavior. (Behavioral patterns live in `skills/`, `prompts/`, etc.)
2424
| [`git-ssh-sign/`](git-ssh-sign/) | Sign git commits and tags with the SSH key forwarded from the host agent (vendored from sbx-kits-contrib). |
2525
| [`openchamber/`](openchamber/) | Run OpenChamber, a browser UI for OpenCode, inside the sandbox alongside the terminal TUI. Opt-in (see its parity note). |
2626
| [`paseo/`](paseo/) | Self-host the [Paseo](https://github.com/getpaseo/paseo) daemon + browser web UI (for coding agents) inside the sandbox on one port. Opt-in; agent-generic wrapper, no shared TUI session. |
27+
| [`prime-agent/`](prime-agent/) | Install [PrimeIntellect-ai/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent), a terminal AI coding assistant with an embedded IPython tool. Opt-in; TUI, no ports. |
28+
| [`pi-coding-agent/`](pi-coding-agent/) | Install [earendil-works/pi](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`), a plain terminal AI coding agent (read/write/edit/bash tools only). Opt-in; TUI, no ports. |
2729

2830
Each kit is self-contained: a `spec.yaml` (`hybrid/v1`), any `files/` payload, a
2931
`scripts/verify` host-side check, a `README.md` (with a **backend parity** note),

‎integrations/isolation/acq-kits/kits.yaml‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,29 @@ kits:
9191
(files/home/prime-agent-install-models-json.sh) and bootstrap the IPython
9292
kernel (files/home/prime-agent-bootstrap-kernel.sh). Publishes NO ports
9393
(prime-agent is a TUI, not a web UI) — unlike openchamber/paseo. SKELETON
94-
only (#369): the three scripts are placeholders; the real install/CA-bundle/
95-
kernel logic lands in #370-#373, and the model catalog
96-
(files/home/prime-agent-config/models.json) is generated by the USAi catalog
97-
emitter (#362). Model-provider egress is the usai-provider kit's job, not
98-
this one.
94+
only: the three scripts are placeholders; the real install/CA-bundle/
95+
kernel logic and the generated model catalog
96+
(files/home/prime-agent-config/models.json) land in follow-up work tracked
97+
in the patterns repo's prime-agent epic. Model-provider egress is the
98+
usai-provider kit's job, not this one.
99+
100+
pi-coding-agent:
101+
backends: [sbx, msb]
102+
parity: |
103+
Opt-in mixin that installs earendil-works/pi (MIT), npm package
104+
@earendil-works/pi-coding-agent — a plain terminal AI coding agent that
105+
grants the model only read/write/edit/bash tools by default (no built-in
106+
MCP, sub-agents, permission popups, or plan mode). Written entirely in the
107+
neutral vocabulary with no backend shortcut or extras: a single
108+
startup-phase script (files/home/pi-coding-agent-install.sh) installs the
109+
CLI via the standard npm registry path (npm install -g --ignore-scripts,
110+
pinned version, unprivileged per-user npm prefix, no pi.dev egress).
111+
Publishes NO ports (a TUI, not a web UI) — like prime-agent, unlike
112+
openchamber/paseo. No install phase — unlike prime-agent's still-in-flight
113+
skeleton, this kit is startup-only throughout, matching openchamber's
114+
settled pattern; shipped ahead of prime-agent to validate that pattern on
115+
a materially simpler target with no native-module or Python-kernel
116+
bootstrap step. Model-provider config (USAi models.json) is deliberately
117+
deferred — no emitter exists yet to populate it — and will land in a
118+
follow-up alongside a real pi USAi-catalog emitter. Model-provider egress
119+
is the usai-provider kit's job, not this one.
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# pi-coding-agent (acq mixin kit)
2+
3+
Installs [earendil-works/pi](https://github.com/earendil-works/pi) (MIT),
4+
npm package [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
5+
— a plain terminal AI coding agent that grants the model only
6+
`read`/`write`/`edit`/`bash` tools by default. Opt-in mixin; composes with the
7+
`usai-provider` kit and the other GSA kits.
8+
9+
pi is a **TUI, not a web UI**, so this kit publishes **no ports** (contrast
10+
the sibling `paseo` and `openchamber` kits, which each publish a browser UI
11+
port), and — unlike the sibling `prime-agent` kit — needs **no embedded
12+
Python/IPython kernel**, so this is the simplest kit in the family.
13+
14+
## Sequencing note
15+
16+
This kit ships **ahead of** the in-flight `prime-agent` kit
17+
(GSA-TTS/agentic-coding-patterns#368) by design: a completed consensus vote
18+
picked pi specifically to validate the unprivileged/agent-owned/startup-only
19+
install pattern on a materially simpler target before returning to
20+
prime-agent's heavier kernel-bootstrap complexity. prime-agent's own epic
21+
remains open, not abandoned.
22+
23+
## Status
24+
25+
`spec.yaml` and the install script are complete for **CLI install only**.
26+
Model-provider configuration (a USAi `models.json` for pi) is **deliberately
27+
deferred**, not merely out of scope: an earlier draft shipped a hand-written
28+
placeholder catalog with an empty `models` array and a script to install it,
29+
and review found that pairing provides zero functional value with no USAi
30+
catalog **pi emitter** yet to populate it (contrast prime-agent's own
31+
placeholder, which ships a real, populated model list generated by an
32+
existing emitter). That step was cut rather than shipped as functionless
33+
scaffolding, and will land together with a real `pi.mjs` emitter in a
34+
follow-up.
35+
36+
Until then, authenticate `pi` manually inside the sandbox — `/login`, an
37+
environment variable, or `~/.pi/agent/auth.json` per
38+
[pi's own provider docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md).
39+
40+
## What it does
41+
42+
- **Startup phase only** (every start, agent user, uid `1000`) — no install
43+
phase. `pi-coding-agent-install.sh` installs the `pi` CLI via
44+
`npm install -g --ignore-scripts`, pinned to a specific reviewed version,
45+
into an unprivileged per-user npm prefix (`$HOME/.local` — see
46+
[`docs/decisions/local-prefix-not-npm-global.md`](docs/decisions/local-prefix-not-npm-global.md)
47+
for why not the `$HOME/.npm-global` convention the sibling kits use).
48+
Idempotent: a no-op if `pi` is already on `PATH`. Rebuilds the CA trust
49+
bundle and the `pi` wrapper (see
50+
[`docs/decisions/ca-bundle-wrapper-not-env-var.md`](docs/decisions/ca-bundle-wrapper-not-env-var.md))
51+
on **every** boot, not just a fresh install.
52+
53+
There is no supervisor loop and nothing running in the background — `pi` is a
54+
TUI the agent runs directly; this kit does not manage a shared session the
55+
way the `openchamber`/`paseo` web-UI kits do.
56+
57+
## Install method: npm registry, not `pi.dev/install.sh`
58+
59+
pi.dev publishes a curl-pipe-to-shell installer, but this kit does **not**
60+
fetch it (a mutable live script with an interactive Node/npm preflight path,
61+
and `pi.dev` egress this kit's allow-list deliberately omits — see the
62+
install script's own header comment for the full rationale). The short
63+
version: `npm install -g @earendil-works/pi-coding-agent` needs only
64+
`registry.npmjs.org`.
65+
66+
**Open question, not yet verified:** does the installed `pi` binary itself
67+
phone home to `pi.dev` at runtime (update checks, telemetry)? If a future
68+
live trace of a running `pi` session finds that it does, add the host then
69+
with a live-tested justification — it is not allow-listed speculatively now.
70+
71+
## Egress allow-list
72+
73+
Deny-by-default. The allow-list in `spec.yaml` is pi's own install host only:
74+
75+
- `registry.npmjs.org` — npm package metadata and tarballs (no wildcard
76+
subdomain needed)
77+
78+
Deliberately **absent** (see "Install method" above for why): `pi.dev`,
79+
`github.com` / `*.githubusercontent.com`.
80+
81+
Model-provider egress (`api.gsa.usai.gov`) is **not** here — that is the
82+
`usai-provider` kit's job.
83+
84+
## Supply-chain notes
85+
86+
- **Version pin**: `PI_CODING_AGENT_VERSION` defaults to a specific, reviewed
87+
npm release rather than `latest` — this kit's behavior must not silently
88+
drift to whatever npm resolves as newest on every sandbox boot. Bump the
89+
pin deliberately, as its own reviewed change.
90+
- **Node version is checked explicitly**: pi requires Node.js >=22.19.0 (its
91+
own published npm registry metadata's `engines.node`). npm's own
92+
`engine-strict` defaults to `false`, so a plain `npm install` would
93+
otherwise proceed silently on an older Node and only fail later, opaquely,
94+
the first time `pi` itself runs. This kit checks the version explicitly
95+
before installing and fails clearly if it's too old — mirroring pi's own
96+
installer's preflight check.
97+
- **Registry fetch is bounded**: `npm install` runs with `--fetch-timeout` and
98+
`--fetch-retries=0` — verified live that against an unreachable or
99+
silently-dropping registry, npm's default retry/backoff behavior can hang
100+
well past a minute, which would delay sandbox startup. Retries are set to 0
101+
deliberately: this is a startup-phase script that runs on every boot, not a
102+
one-shot manual install, so the *next* boot already retries naturally.
103+
- **`--ignore-scripts` is not a complete mitigation.** It blocks npm
104+
lifecycle hooks at install time, not code that runs when `pi` is later
105+
**invoked** (see the install script's own comment on this exact flag) —
106+
the ephemeral, single-tenant sandbox remains the real containment
107+
boundary.
108+
- **CA-bundle handling is load-bearing, not defensive** — see
109+
[`docs/decisions/ca-bundle-wrapper-not-env-var.md`](docs/decisions/ca-bundle-wrapper-not-env-var.md)
110+
for the full design and why a runtime wrapper, not an install-time
111+
`export`, is required for the bundle to actually reach `pi`'s own later
112+
invocations.
113+
114+
## Naming
115+
116+
The kit is named `pi-coding-agent` — matching the npm package name — rather
117+
than the bare upstream shorthand `pi`. A bare `pi` kit name would collide
118+
conceptually with the ubiquitous mathematical constant/variable name in every
119+
log line, script, and error message this kit produces, a real ambiguity risk
120+
unique to this product's name that none of the sibling kits'
121+
(`openchamber`/`paseo`/`prime-agent`/`zscaler-ca-certificate`) share. Every
122+
file, script, and log line in this kit says `pi-coding-agent`, never bare
123+
`pi`, for the same reason.
124+
125+
## Backend parity
126+
127+
Written entirely in the neutral hybrid/v1 vocabulary (caps / files /
128+
commands), with no `backend_shortcuts` or `backend_extras`. acq's kit
129+
translation feeds the same spec to whatever backend it has active (sbx, msb).
130+
No published port and no supervisor loop, so no per-backend detached/port
131+
primitives are needed.
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Troubleshooting — pi-coding-agent kit
2+
3+
Failure modes specific to the pi-coding-agent kit, which installs
4+
[earendil-works/pi](https://github.com/earendil-works/pi)
5+
(`@earendil-works/pi-coding-agent`) via the npm registry at every sandbox
6+
start. Most diagnosis is done with `acq exec <sandbox> -- sh -c '…'`. Unlike
7+
the sibling `openchamber`/`paseo` kits, a bare `acq exec` here does **not**
8+
need any `PATH=` prepend to find `pi` — the install prefix is `$HOME/.local`,
9+
already first on the guest's default `PATH` (see
10+
[`docs/decisions/local-prefix-not-npm-global.md`](docs/decisions/local-prefix-not-npm-global.md)).
11+
12+
## Node.js and/or npm not found
13+
14+
**Symptoms:** the startup log shows
15+
`pi-coding-agent: node and/or npm not found on PATH; cannot install pi this
16+
boot (installing Node is out of scope for this kit — see spec.yaml)`, and `pi`
17+
never appears.
18+
19+
**Cause.** This kit deliberately does not install Node — it assumes the base
20+
image already carries it (the same assumption `openchamber` makes for its own
21+
base image). A customized or minimal base image may not.
22+
23+
**Fix:** use the `opencode` base template (the default, which ships Node), or
24+
add a Node install step ahead of this kit in your kit composition.
25+
26+
## Node.js too old
27+
28+
**Symptoms:** the startup log shows
29+
`pi-coding-agent: pi requires Node.js >=22.19.0, found vX.Y.Z; cannot install
30+
pi this boot (installing/upgrading Node is out of scope for this kit)`.
31+
32+
**Cause.** pi's own published npm registry metadata (`engines.node`) requires
33+
Node `>=22.19.0`. npm's `engine-strict` defaults to `false`, so a plain
34+
`npm install` would otherwise proceed silently on an older Node and only fail
35+
later, opaquely, the first time `pi` itself runs — this kit checks explicitly
36+
up front instead, mirroring pi's own installer's preflight check.
37+
38+
**Fix:** upgrade the base image's Node to `>=22.19.0`, or pair this kit with a
39+
Node-upgrade step. Confirm the guest's version:
40+
41+
```bash
42+
acq exec <sandbox> -- sh -c 'node --version'
43+
```
44+
45+
## Malformed `PI_CODING_AGENT_VERSION` — install refused
46+
47+
**Symptoms:** the startup log shows
48+
`pi-coding-agent: PI_CODING_AGENT_VERSION='<value>' doesn't look like a
49+
version; refusing to install` (or `... contains characters outside
50+
[0-9A-Za-z.-]; refusing to install`), and `pi` is never installed.
51+
52+
**Cause.** The kit validates the version pin's shape before it ever reaches
53+
the npm package-spec string (`@earendil-works/pi-coding-agent@<version>`).
54+
This fails **closed**: an unexpected value (typo, stray whitespace, an
55+
accidentally-injected flag-looking token) is refused rather than silently
56+
passed through. Note that this is a defensive **format** check, not a
57+
security boundary on its own — the value is always passed as a single quoted
58+
argv word, never re-parsed by a shell, so it was never shell-injectable; the
59+
check exists so a malformed pin fails loudly and immediately instead of
60+
producing a confusing downstream npm error.
61+
62+
**Fix:** set `PI_CODING_AGENT_VERSION` to either `latest` or a plain
63+
`MAJOR.MINOR.PATCH`-shaped string (matching `[0-9A-Za-z.-]` only) in the
64+
kit's `environment:`/spec configuration, then recreate the sandbox (or
65+
restart it so the startup step re-runs).
66+
67+
## npm install failure or timeout
68+
69+
**Symptoms:** the startup log shows
70+
`pi-coding-agent: npm install exited <rc> (prefix=...); pi unavailable this
71+
boot. See <log path>`, and `pi` is not on `PATH`.
72+
73+
**Cause.** Most commonly: egress to `registry.npmjs.org` is blocked (this
74+
kit's only allow-listed host), a proxy/TLS issue (see the next entry), or a
75+
slow/silently-dropping connection. The install runs with
76+
`--fetch-timeout=30000 --fetch-retries=0` deliberately — this is a
77+
**startup-phase** script that runs on every boot, not a one-shot manual
78+
install, so retrying against a systemic failure just delays the sandbox for
79+
no benefit; the *next* boot retries naturally.
80+
81+
**Fix:** check the install log and egress:
82+
83+
```bash
84+
acq exec <sandbox> -- sh -c 'cat ~/.local/state/pi-coding-agent/install.log 2>/dev/null | tail -n 40'
85+
acq exec <sandbox> -- sh -c 'echo "${HTTPS_PROXY:-unset}"'
86+
```
87+
88+
If `registry.npmjs.org` is not reachable under org network policy, confirm it
89+
is on the sandbox's effective allow-list (`sbx policy log <sandbox>` /
90+
`acq policy log <sandbox>` under org governance may show it superseded).
91+
92+
## CA-decode failure (malformed `PROXY_CA_CERT_B64`)
93+
94+
**Symptoms:** the startup log shows
95+
`pi-coding-agent: PROXY_CA_CERT_B64 failed to base64-decode; proxy CA NOT
96+
added to the bundle (see <err path>)`, typically followed by an npm/TLS
97+
failure like `unable to get local issuer certificate` or
98+
`SELF_SIGNED_CERT_IN_CHAIN` on an inspected network.
99+
100+
**Cause.** `PROXY_CA_CERT_B64` (base64-encoded PEM, supplied by whatever
101+
injects a proxy CA into the sandbox — e.g. the `zscaler-ca-certificate` kit)
102+
failed to decode. Unlike the sibling `openchamber` kit's equivalent block
103+
(which swallows this same decode failure via `2>/dev/null`), this kit's
104+
install script surfaces it explicitly, on the theory that a silently
105+
incomplete CA bundle produces a much more confusing downstream TLS error than
106+
telling you up front that the base64 itself was bad.
107+
108+
**Fix:** confirm the value is actually valid base64-encoded PEM from the
109+
source that's supposed to provide it (commonly the `zscaler-ca-certificate`
110+
kit — pair it if you're on an inspected network), then recreate/restart the
111+
sandbox:
112+
113+
```bash
114+
acq exec <sandbox> -- sh -c 'echo "PROXY_CA_CERT_B64 len=${#PROXY_CA_CERT_B64}"'
115+
acq exec <sandbox> -- sh -c 'echo "$PROXY_CA_CERT_B64" | base64 -d | head -c 40' # should start with -----BEGIN CERTIFICATE-----
116+
```
117+
118+
## pi installs but making an LLM-provider call fails TLS
119+
120+
**Symptoms:** `pi` runs, but any call it makes to a model provider on an
121+
inspected network fails with a TLS trust error (`unable to get local issuer
122+
certificate`, `SELF_SIGNED_CERT_IN_CHAIN`).
123+
124+
**Cause.** `NODE_EXTRA_CA_CERTS` only **appends** to Node's built-in trust
125+
roots — it needs the sandbox's proxy CA. Per the wrapper design in
126+
`docs/decisions/`, the CA bundle is **rebuilt once per boot** by the startup
127+
script, and the wrapper at `$HOME/.local/bin/pi` simply `exec`s the real `pi`
128+
binary with that boot's already-current bundle path — it does not rebuild
129+
anything itself at invocation. A plain `export` inside the install script's
130+
own process would not persist to a separately-launched `pi` process later,
131+
which is exactly why the wrapper exists.
132+
133+
**Fix:** confirm the wrapper still references `NODE_EXTRA_CA_CERTS` and
134+
`exec`s the real binary (this is the normal, expected shape — not a sign of
135+
breakage):
136+
137+
```bash
138+
acq exec <sandbox> -- sh -c 'cat ~/.local/bin/pi' # should show a small script that sets NODE_EXTRA_CA_CERTS and execs the real pi binary
139+
```
140+
141+
If the wrapper is missing `NODE_EXTRA_CA_CERTS` entirely (not just a static
142+
one-time export baked in at some earlier boot, but absent altogether), it has
143+
regressed; see `docs/decisions/` for the intended design and file an issue.
144+
145+
## No model provider configured
146+
147+
**Symptoms:** `pi` runs but has no LLM provider to talk to.
148+
149+
**Cause.** This kit deliberately defers model-provider configuration (no
150+
USAi `models.json` catalog exists for pi yet — see the README's "Status"
151+
section).
152+
153+
**Fix:** authenticate `pi` manually inside the sandbox — `/login`, a provider
154+
environment variable, or `~/.pi/agent/auth.json` — per
155+
[pi's own provider docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md).

0 commit comments

Comments
 (0)