diff --git a/.claude/skills/dev-onboard/SKILL.md b/.claude/skills/dev-onboard/SKILL.md index d8c2def..809b580 100644 --- a/.claude/skills/dev-onboard/SKILL.md +++ b/.claude/skills/dev-onboard/SKILL.md @@ -14,8 +14,9 @@ finish by printing the punchlist of whatever remains for the human. - Node.js 20+ (`node --version`); - VS Code 1.90+; - Docker Sandboxes - required for real sandbox runs, optional for build-only work. Windows - install lands `sbx` at `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` (not on PATH); probe - with `sbx version` at that path, and note that sign-in is a manual browser step. + install lands `sbx` at `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`; probe it there + rather than through PATH, which may or may not carry it. `sbx diagnose` reports every + precondition at once (binary, daemon, authentication); sign-in is a manual browser step. 2. **Git identity**: commits carry no agent identity in messages (see `git-commit-push`); nothing to configure beyond a normal user. 3. `npm install`. diff --git a/.claude/skills/ext-run-local/SKILL.md b/.claude/skills/ext-run-local/SKILL.md index db3da8b..e7109f7 100644 --- a/.claude/skills/ext-run-local/SKILL.md +++ b/.claude/skills/ext-run-local/SKILL.md @@ -10,9 +10,12 @@ running the extension and checking the FR's behaviour by hand. ## Prerequisites check -- Docker Sandboxes installed and signed in. `sbx` is not on PATH on Windows - probe it at - `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` (`sbx version`). Without it the extension loads - but every lifecycle action fails; layer-only changes can still be smoke-tested. +- Docker Sandboxes installed and signed in. Do not rely on PATH on Windows - probe it at + `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` (`sbx diagnose` reports binary, daemon and + sign-in in one go). Without it the extension loads and now says so - `⚠ Sandbox not + available` in the status bar, a readiness node in the Sandboxes view, a modal on New + Sandbox (FR-059) - while every lifecycle action stays blocked; layer-only changes can + still be smoke-tested. ## Steps diff --git a/.claude/skills/spec-implement/SKILL.md b/.claude/skills/spec-implement/SKILL.md index 5dfb857..ff5558f 100644 --- a/.claude/skills/spec-implement/SKILL.md +++ b/.claude/skills/spec-implement/SKILL.md @@ -26,7 +26,8 @@ CLAUDE.md is the rule surface - this skill sequences it, it does not replace it. 4. **Respect the traps** (they are documented in CLAUDE.md, they bite anyway): esbuild does not typecheck - only `npm run verify` proves the code; there is no `sbx start` - resume is `sbx run`; `/home/agent/workspace` is a decoy - the real mount is the translated host path; - `sbx` is not on PATH on Windows. + never rely on `sbx` being on PATH on Windows (`sbxPath()` checks the install location + first, on every call - do not reintroduce a memo). 5. **Protect the invariants**: attach ("Connect") stays the primary action when a sandbox exists; no implicit default sandbox; terminal-first (no chat panels); secrets only over stdin, never argv/env/image; argv allowlist and path containment stay intact. diff --git a/CLAUDE.md b/CLAUDE.md index 28b24dc..95e48db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,9 +50,12 @@ There is no test runner yet; verification is `npm run verify` + manual run + dir one carve-out: the bash template in `src/script.ts` *renders* sbx calls into the generated `.sandbox/scripts/sbx.sh` (FR-052) for external shells; the extension never executes them, but keep the template in sync when CLI shapes change. -- **`sbx` is not on PATH** (Windows): it lives at - `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`. `sbxPath()` resolves it; that same path - is used as the terminal `shellPath`. +- **Never rely on `sbx` being on PATH** (Windows): it lives at + `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`, and `sbxPath()` checks that location + *before* PATH, on every call. A PATH entry may or may not exist (some installs have one), + and it never rescues a VS Code window that was already open when sbx was installed — that + process captured its environment beforehand. The resolved path doubles as the terminal + `shellPath`. - **There is no `sbx start`** — resume a stopped sandbox with `sbx run ` (or `sbx exec`, which auto-starts). - Lifecycle: Create/Attach → `sbx run`; Stop → `sbx stop`; destroy → `sbx rm --force`; diff --git a/docs/Architecture.md b/docs/Architecture.md index 9a320b2..db813e6 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -409,9 +409,11 @@ executable and `shellArgs` = the `run`/`exec` invocation. The native terminal ow real PTY (ConPTY on Windows), so ANSI, cursor control, resize, and interactive agents work with no native dependency (no `node-pty`). This satisfies FR-010/FR-011. -The `sbx` executable is resolved at runtime: the Windows installer places it at -`%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe` and does **not** add it to `PATH`, so -`sbx.ts` checks that location first and falls back to the bare command name. +The `sbx` executable is resolved at runtime, on every call (§4): the Windows installer places +it at `%LOCALAPPDATA%\DockerSandboxes\bin\sbx.exe`, so `sbx.ts` checks that location first and +falls back to the bare command name. Whether a `PATH` entry for that directory also exists +varies by install and is **not** relied upon — and it would not help the case that matters +anyway, a window already open when sbx was installed, whose environment block predates it. **Agent terminals are pooled per sandbox and reused** — a second `sbx run ` is not a separate instance, it's another attach session into the same microVM (shared