docs: Windows Smart App Control known issue, optional CSO failures, doctor rows

README's Windows section says /cso failures no longer stop setup
(GSTACK_STRICT_BUILD=1 keeps them fatal), documents Smart App Control as
a known issue with today's workarounds (WSL, or turning it off) and the
Consolas fix. troubleshooting.md gains a Windows section for blocked
binaries and an entry for CSO build/publish failures. TODOS.md replaces
the Node CLI lane item with Windows code signing (needs a signing
account), the #3071 root-cause follow-up and SAC text verification.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

README.md

@@ -654,8 +654,9 @@ Data is stored in [Supabase](https://supabase.com) (open source Firebase alterna
 (on other hosts, `./setup --status` in your gstack checkout ends with the
 doctor's absolute path). Without starting a skill or spending anything, it
 prints one row per check (install, state root, Bun, hooks, Codex and its cached
-model probe, artifacts sync, the browse bundle, Claude Code, your largest
-session journal and recent /autoplan guard codes), each `ok`, `warn`,
+model probe, artifacts sync, the browse bundle, the other compiled binaries,
+the /cso native helper, Claude Code, your largest session journal and recent
+/autoplan guard codes), each `ok`, `warn`,
 `not configured` or `fail` with the command that fixes it. It exits non-zero
 only on `fail`. `--live` also runs the paid Codex model check (one short call).
 Paste its output into bug reports.
@@ -696,7 +697,9 @@ types into that element; bare `browse type <text>` types into whatever has focus
 
 **Codex says "Skipped loading skill(s) due to invalid SKILL.md"?** Your Codex skill descriptions are stale. `${CODEX_HOME:-~/.codex}/skills/gstack` is a runtime directory, not the checkout: `./setup --status` shows the Codex row's source checkout. Fix: `cd <that source> && git pull && ./setup --host codex` — for a repo-local install, run it from inside the project.
 
-**Windows users:** gstack works on Windows 11 via Git Bash or WSL. Aside is macOS-only, so on Windows (and Linux) the browser skills, `/make-pdf`, and `/diagram` always use gstack's bundled browser. Node.js is required in addition to Bun — Bun has a known bug with Playwright's pipe transport on Windows ([bun#4253](https://github.com/oven-sh/bun/issues/4253)). The browse server automatically falls back to Node.js. Make sure both `bun` and `node` are on your PATH. Native `/cso` additionally requires Windows PowerShell and Visual Studio 2022 Build Tools with the Desktop development with C++ workload; setup leaves that skill explicitly unavailable when they are absent.
+**Windows users:** gstack works on Windows 11 via Git Bash or WSL. Aside is macOS-only, so on Windows (and Linux) the browser skills, `/make-pdf`, and `/diagram` always use gstack's bundled browser. Node.js is required in addition to Bun — Bun has a known bug with Playwright's pipe transport on Windows ([bun#4253](https://github.com/oven-sh/bun/issues/4253)). The browse server automatically falls back to Node.js. Make sure both `bun` and `node` are on your PATH. Native `/cso` additionally requires PowerShell (PowerShell 7 `pwsh` is preferred; Windows PowerShell 5.1 is the fallback) and Visual Studio 2022 Build Tools with the Desktop development with C++ workload; setup leaves that skill explicitly unavailable when they are absent. /cso is optional: if its native helper fails to build or publish, setup still finishes, says which step failed with the log path and retry command, and keeps an earlier helper when it has one (`GSTACK_STRICT_BUILD=1` makes that failure fatal, as CI does).
+
+**Known issue: Windows Smart App Control** ([#2595](https://github.com/garrytan/gstack/issues/2595)). gstack's compiled binaries (`browse`, `find-browse`, `design`, `pdf`, `gstack-global-discover`) are built on your machine and unsigned, so Windows 11 with Smart App Control on refuses to start them; Git Bash shows `Permission denied`. setup detects this, names the blocked binaries and the skills that need them, and `gstack-doctor` reports them as `blocked`. Today's workarounds are running gstack inside WSL, or turning Smart App Control off. Details: [troubleshooting](docs/troubleshooting.md#windows-smart-app-control). The sidebar terminal uses Consolas on Windows, so its text no longer renders spaced out.
 
 On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file copies instead of symlinks because `ln -snf` produces frozen copies that don't refresh on `git pull`. **Re-run `cd ~/.claude/skills/gstack && ./setup` after every `git pull`** so your skill files match the repo. `setup` prints a one-line note reminding you. Unix and WSL keep symlinks and don't need the re-run.
 

TODOS.md

@@ -166,6 +166,30 @@ From the approved 2026-10 test/eval/CI audit plan; the audit PR files these.
   paid PR profile from the same touchfile closure so one command answers "what
   does my diff need?". **Effort:** M. **Priority:** P3.
 
+### P2: Windows follow-ups from the October fix wave (PR C1)
+
+- **Sign the Windows binaries so Smart App Control allows them (#2595, #2124)** —
+  `browse`, `find-browse`, `design`, `pdf` and `gstack-global-discover` are
+  compiled on the user's machine with `bun build --compile`, so they are
+  unsigned and never gain reputation; Smart App Control blocks all five. PR C1
+  only detects and explains the block (setup hint, gstack-doctor rows,
+  troubleshooting section). The fix is Authenticode-signed release artifacts
+  (for example Azure Trusted Signing) that setup downloads and verifies instead
+  of compiling, or a signed launcher. **Needs:** Garry's code-signing account
+  and certificate decision; a Windows 11 machine with Smart App Control on to
+  verify. **Effort:** L. **Priority:** P2.
+- **Find what deletes the staged CSO files during publish on #3071's machine** —
+  PR C1 made the failure non-fatal, cleared the parent's EXIT trap before the
+  native publisher `exec`, and records the outcome, but the root cause is
+  unproven (one reporter; `windows-latest` CI publishes fine). Ask for
+  `bin/.gstack-cso-build.log`, `bash -x scripts/build-cso.sh` and a Process
+  Monitor trace of the stage directory. **Effort:** M (needs the reporter's
+  machine). **Priority:** P3.
+- **Verify the Smart App Control error text on a real SAC machine** — the
+  launch probe (`bin/gstack-launch-probe.sh`) classifies exit 126/127 and
+  application-control messages as blocked from reporters' captures; nobody has
+  run it on an enforcing machine. **Effort:** S. **Priority:** P3.
+
 ### P2/P3: severe fix wave follow-ups (filed 2026-10-03, v1.91.19.0)
 
 Deferred from the approved severe fix wave (docs/designs/SEVERE_FIX_WAVE_2026_10.md), each with its reason.
@@ -176,11 +200,15 @@ Deferred from the approved severe fix wave (docs/designs/SEVERE_FIX_WAVE_2026_10
   and `--no-env-file` (verified with 1.3.2), so D0's protection against a
   project's `.env`/`bunfig.toml` is silently off there. Setup should refuse or
   warn below the floor. **Effort:** S. **Priority:** P2.
-- **Windows Node CLI lane for Smart App Control (E3; #2596, #2595, #2124)** —
-  a `dist/browse` wrapper would shadow `browse.exe` for every Windows user;
-  launcher precedence (browse vs browse.exe vs browse.cmd under Git Bash and
-  cmd) and the node-missing message need a Windows SAC machine to verify.
-  **Effort:** M. **Priority:** P2.
+- ~~**Windows Node CLI lane for Smart App Control (E3; #2596, #2595, #2124)**~~ —
+  superseded by the fix wave's PR C1: setup and gstack-doctor now detect
+  SAC-blocked binaries, and the fix wave decided against a launcher or shim
+  (it cannot be called from PowerShell, and a `bun run` shim would load the
+  caller's project `.env`/`bunfig.toml`). Signing is the follow-up below.
+  Original note: — a `dist/browse` wrapper would shadow `browse.exe` for every
+  Windows user; launcher precedence (browse vs browse.exe vs browse.cmd under
+  Git Bash and cmd) and the node-missing message need a Windows SAC machine to
+  verify. **Effort:** M. **Priority:** P2.
 - **C8 router wording behind a routing panel** — disabled skills now leave the
   router, but the "When in doubt, invoke the skill" wording change (Tier 3) was
   not run through a routing eval panel. **Effort:** S. **Priority:** P3.

docs/troubleshooting.md

@@ -26,8 +26,9 @@ section has a stable link anchor; the reason codes and anchors come from
 Run `~/.claude/skills/gstack/bin/gstack-doctor` (other hosts: `./setup --status`
 in your gstack checkout prints the doctor's absolute path). It prints one row
 each for the install, state root, Bun, hooks, Codex, the cached Codex model
-check, artifacts sync, the browse bundle, Claude Code, the largest session
-journal and recent /autoplan guard codes. Each row is `ok`, `warn`,
+check, artifacts sync, the browse bundle, the other compiled binaries, the
+/cso native helper, Claude Code, the largest session journal and recent
+/autoplan guard codes. Each row is `ok`, `warn`,
 `not configured` or `fail` with its fix; only `fail` exits non-zero. It makes
 no paid call: the Codex rows report the cached model check and its age, and
 `--live` runs that check once. Paste its output into bug reports.
@@ -655,6 +656,35 @@ Visual Studio".
 
 **Fix.** Fix the printed compiler error, then re-run `./setup`.
 
+<a id="cso-build-or-publish-failed"></a>
+### `CSO unavailable: the native helper's <stage> step failed (...)` / `CSO publish step failed (...) for <revision>; previous CSO kept: <revision>`
+
+**Meaning.** The /cso native helper is optional. Its build prerequisites were
+present, but the `build` step (compiling the helper) or the `publish` step
+(swapping the new helper into `bin/` under a lock) failed. setup used to stop
+here (#3071); now it finishes everything else and says which step failed. When
+an earlier helper was installed and the failed publish restored it, setup
+prints `previous CSO kept` and /cso keeps using that helper; otherwise /cso
+reports `not assessed`. `interrupted` means the step was killed before it could
+record a result. The outcome is in `bin/.gstack-cso-build-result`, and
+`gstack-doctor`'s `cso` row reads the same record. The build output is in
+`bin/.gstack-cso-build.log`.
+
+**Fix.** Read the log, fix what it reports, then retry from your gstack checkout:
+
+```bash
+bun run build:cso && ./setup
+```
+
+On Windows, setup and the build use PowerShell 7 (`pwsh`) when it is installed
+and fall back to Windows PowerShell 5.1. The root cause of the staged files
+vanishing during publish in #3071 is still unknown; attach the log there if you
+hit it. CI sets `GSTACK_STRICT_BUILD=1`, which makes these failures fatal so
+build regressions cannot hide.
+
+**Expected result.** setup prints no CSO line, and the doctor's `cso` row is
+`ok`.
+
 <a id="cso-windows-docker"></a>
 ### `Docker found at <path>, but native Windows Docker transport is not supported yet; static assessment only.` / `docker.exe at <path> is outside the trusted install locations (...)`
 
@@ -802,6 +832,45 @@ killed.
 
 ---
 
+## Windows
+
+<a id="windows-smart-app-control"></a>
+### `Windows blocked compiled gstack binaries at launch (Smart App Control or another application-control policy, #2595)` / `bash: .../browse.exe: Permission denied`
+
+**Meaning.** Known issue (#2595, #2124). gstack compiles five binaries on your
+machine with Bun: `browse`, `find-browse`, `design`, `pdf` and
+`gstack-global-discover`. They are unsigned, and a binary built on one machine
+never earns the reputation Smart App Control accepts instead of a signature, so
+Windows 11 with Smart App Control on refuses to start them. Git Bash reports
+that as `Permission denied`, which looks like a file-permission problem but is
+code integrity (PowerShell says `An Application Control policy has blocked this
+file`). setup now runs each binary's `--version` and names the blocked ones and
+the skills that need them: the gstack browser fallback (`/browse`, `/qa`,
+`/qa-only`, `/design-review`, `/canary`, `/benchmark`, `/pair-agent`,
+`/scrape`, `/make-pdf`), the design binary (`/design-consultation`,
+`/design-shotgun`, `/design-html`, `/plan-design-review`) and `/retro global`.
+Every other skill works. `gstack-doctor` shows the same state in its
+`browse bundle` and `binaries` rows. The exact Windows error text has not been
+verified on a Smart App Control machine; setup prints the raw first line beside
+its classification.
+
+**Fix.** There is no per-file allowlist for Smart App Control. Today's options:
+
+- Run gstack inside WSL (`wsl --install`, then install gstack in the Linux
+  distro). WSL runs gstack's Linux build, which Smart App Control does not check.
+- Or turn Smart App Control off in Windows Security > App & browser control >
+  Smart App Control settings. On Windows 11 with the April 2026 update you can
+  turn it back on later without reinstalling Windows; on older builds turning it
+  off is permanent. gstack's binaries stay blocked whenever it is on.
+
+Signed release binaries are the real fix and are tracked in `TODOS.md`. After
+Windows allows the binaries, re-run `./setup`; the message goes away.
+
+**Expected result.** setup prints no "Windows blocked" line, and
+`gstack-doctor` shows `ok` for `browse bundle` and `binaries`.
+
+---
+
 ## Memory and gbrain
 
 Every message below is also in [docs/gbrain-sync-errors.md](gbrain-sync-errors.md)