From 9cd86e0f76e93d588ecc84333cb713ab67590d5d Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:01:07 -0700
Subject: [PATCH 01/12] fix(browse): single-point Unicode sanitization at
 server egress

Add sanitizeLoneSurrogates (regex-based UTF-16 lone-half cleaner) and
sanitizeReplacer (JSON.stringify replacer that runs the cleaner on every
string field during encoding).

Split handleCommandInternal into handleCommandInternalImpl (raw) plus a
thin sanitizing wrapper. The wrapper applies sanitizeLoneSurrogates to
cr.result so both single-command (handleCommand line 1034) and batch-loop
(line 1966) egress paths inherit it. Inline INVARIANT comment near the
wrapper documents the architectural constraint.

Both SSE producers (activity feed at /activity/stream and inspector
stream) stringify with sanitizeReplacer. Post-stringify regex is
ineffective on those paths because JSON.stringify has already converted
the lone surrogate into the escape sequence "\\\\uD800" before any regex
could match it; the replacer runs during stringify on the raw string
value, so the substitution lands.

Originated from @realcarsonterry PR #1463 (handleCommand-only wrap).
Architectural lift to handleCommandInternal + SSE coverage authored on
this branch.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 browse/src/server.ts | 74 ++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 68 insertions(+), 6 deletions(-)

diff --git a/browse/src/server.ts b/browse/src/server.ts
index e8804d8bb..b389cfa63 100644
--- a/browse/src/server.ts
+++ b/browse/src/server.ts
@@ -59,6 +59,43 @@ import * as net from 'net';
 import * as path from 'path';
 import * as crypto from 'crypto';
 
+// ─── Unicode Sanitization ───────────────────────────────────────
+// Remove unpaired UTF-16 surrogate halves (\uD800–\uDFFF). Page DOM text,
+// OCR output, and other CDP-sourced strings can contain lone surrogates;
+// JSON consumers downstream (Anthropic API in particular) reject them with
+// "no low surrogate in string". Valid surrogate pairs (e.g. emoji) survive
+// unchanged. Lone halves become U+FFFD (�).
+//
+// INVARIANT: every server egress path that ships page-content strings MUST
+// route through this sanitizer. handleCommandInternal wraps the final
+// cr.result string (text/plain bodies carry lone surrogates verbatim;
+// JSON.stringify already escapes them). The two SSE producers below
+// stringify with `sanitizeReplacer` so payload string fields get cleaned
+// BEFORE escaping. Plain post-stringify regex is a no-op there because
+// JSON.stringify converts \uD800 → "\\ud800" — the regex can't see the
+// surrogate after that point.
+function sanitizeLoneSurrogates(str: string): string {
+  return str.replace(/[\uD800-\uDFFF]/g, (match, offset) => {
+    const code = match.charCodeAt(0);
+    if (code >= 0xD800 && code <= 0xDBFF) {
+      const next = str.charCodeAt(offset + 1);
+      if (next >= 0xDC00 && next <= 0xDFFF) return match;
+    }
+    if (code >= 0xDC00 && code <= 0xDFFF) {
+      const prev = str.charCodeAt(offset - 1);
+      if (prev >= 0xD800 && prev <= 0xDBFF) return match;
+    }
+    return '�';
+  });
+}
+
+// JSON.stringify replacer that sanitizes string values before they get
+// escape-encoded. Pair with stringify when the consumer will JSON.parse the
+// payload back into JS strings (SSE clients do this).
+function sanitizeReplacer(_key: string, value: unknown): unknown {
+  return typeof value === 'string' ? sanitizeLoneSurrogates(value) : value;
+}
+
 // ─── Config ─────────────────────────────────────────────────────
 const config = resolveConfig();
 ensureStateDir(config);
@@ -683,7 +720,7 @@ interface CommandResult {
  *   skipActivity: true when called from chain (chain emits 1 event for all subcommands)
  *   chainDepth: recursion guard — reject nested chains (depth > 0 means inside a chain)
  */
-async function handleCommandInternal(
+async function handleCommandInternalImpl(
   body: { command: string; args?: string[]; tabId?: number },
   tokenInfo?: TokenInfo | null,
   opts?: { skipRateCheck?: boolean; skipActivity?: boolean; chainDepth?: number },
@@ -1027,6 +1064,21 @@ async function handleCommandInternal(
   }
 }
 
+/**
+ * Sanitizing wrapper around handleCommandInternalImpl. ALL callers (single-command
+ * HTTP, batch loop, scoped-token dispatch) go through this so the lone-surrogate
+ * sanitization happens once at the architectural choke point, not per-leaf.
+ * Do not bypass this by calling handleCommandInternalImpl directly.
+ */
+async function handleCommandInternal(
+  body: { command: string; args?: string[]; tabId?: number },
+  tokenInfo?: TokenInfo | null,
+  opts?: { skipRateCheck?: boolean; skipActivity?: boolean; chainDepth?: number },
+): Promise<CommandResult> {
+  const cr = await handleCommandInternalImpl(body, tokenInfo, opts);
+  return { ...cr, result: sanitizeLoneSurrogates(cr.result) };
+}
+
 /** HTTP wrapper — converts CommandResult to Response */
 async function handleCommand(body: any, tokenInfo?: TokenInfo | null): Promise<Response> {
   const cr = await handleCommandInternal(body, tokenInfo);
@@ -1827,19 +1879,24 @@ export async function start() {
 
         const stream = new ReadableStream({
           start(controller) {
+            // SSE egress invariant: every JSON.stringify here ships page-content-derived
+            // fields (URLs, command args, errors) to the sidebar. Lone surrogates must
+            // be sanitized DURING stringify (via sanitizeReplacer) so they're cleaned
+            // before escape-encoding — post-stringify regex is ineffective because
+            // JSON.stringify has already converted \uD800 → "\\ud800".
             // 1. Gap detection + replay
             const { entries, gap, gapFrom, availableFrom } = getActivityAfter(afterId);
             if (gap) {
-              controller.enqueue(encoder.encode(`event: gap\ndata: ${JSON.stringify({ gapFrom, availableFrom })}\n\n`));
+              controller.enqueue(encoder.encode(`event: gap\ndata: ${JSON.stringify({ gapFrom, availableFrom }, sanitizeReplacer)}\n\n`));
             }
             for (const entry of entries) {
-              controller.enqueue(encoder.encode(`event: activity\ndata: ${JSON.stringify(entry)}\n\n`));
+              controller.enqueue(encoder.encode(`event: activity\ndata: ${JSON.stringify(entry, sanitizeReplacer)}\n\n`));
             }
 
             // 2. Subscribe for live events
             const unsubscribe = subscribe((entry) => {
               try {
-                controller.enqueue(encoder.encode(`event: activity\ndata: ${JSON.stringify(entry)}\n\n`));
+                controller.enqueue(encoder.encode(`event: activity\ndata: ${JSON.stringify(entry, sanitizeReplacer)}\n\n`));
               } catch (err: any) {
                 console.debug('[browse] Activity SSE stream error, unsubscribing:', err.message);
                 unsubscribe();
@@ -2188,10 +2245,15 @@ export async function start() {
         const encoder = new TextEncoder();
         const stream = new ReadableStream({
           start(controller) {
+            // SSE egress invariant: inspectorData and CDP event payloads carry
+            // page-DOM strings (selectors, attribute values, console messages).
+            // sanitizeReplacer cleans lone surrogates DURING JSON.stringify so
+            // they're neutralized before escape-encoding (post-stringify regex
+            // is a no-op once \uD800 has become "\\ud800").
             // Send current state immediately
             if (inspectorData) {
               controller.enqueue(encoder.encode(
-                `event: state\ndata: ${JSON.stringify({ data: inspectorData, timestamp: inspectorTimestamp })}\n\n`
+                `event: state\ndata: ${JSON.stringify({ data: inspectorData, timestamp: inspectorTimestamp }, sanitizeReplacer)}\n\n`
               ));
             }
 
@@ -2199,7 +2261,7 @@ export async function start() {
             const notify: InspectorSubscriber = (event) => {
               try {
                 controller.enqueue(encoder.encode(
-                  `event: inspector\ndata: ${JSON.stringify(event)}\n\n`
+                  `event: inspector\ndata: ${JSON.stringify(event, sanitizeReplacer)}\n\n`
                 ));
               } catch (err: any) {
                 console.debug('[browse] Inspector SSE stream error:', err.message);

From 76aefdd3e8ecbc25da988a86a5aaeb9ced8489c5 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:01:20 -0700
Subject: [PATCH 02/12] fix(setup): _link_or_copy helper for Windows file-copy
 fallback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On Windows without Developer Mode (MSYS2/Git Bash), plain ln -snf
silently creates a frozen file copy that doesn't refresh on git pull.
Skill files become stale after every upgrade.

Add a _link_or_copy SRC DST helper near IS_WINDOWS detection (line ~33).
It auto-dispatches: on Unix it preserves ln -snf semantics, on Windows
it copies (cp -R for directories, cp -f for files). When the source is
a Unix-style name-only alias that doesn't resolve on disk (the
connect-chrome → gstack/open-gstack-browser pattern), the helper
returns 0 silently on Windows rather than aborting setup under set -e.

Rewrite all 42 prior ln -snf call sites to route through the helper:
link_claude_skill_dirs (line 437), team-claude install paths (lines 556,
581, 592), Codex host adapter block (lines 618-640), Factory host
adapter block (lines 658-678), OpenCode host adapter block (lines
696-731), Kiro host adapter block (lines 939-953), plus migration and
alias sites.

Add _print_windows_copy_note_once helper and call it from
link_claude_skill_dirs after any linking work completes so Windows
users see one user-visible note explaining they must re-run ./setup
after every git pull.

Extend cleanup_old_claude_symlinks and cleanup_prefixed_claude_symlinks
with a Windows branch: when the target is a real directory containing a
real-file SKILL.md (no symlink to readlink), and IS_WINDOWS=1, treat
the name-matched directory as gstack-managed and remove it. This makes
--prefix / --no-prefix flips work on Windows instead of leaving stale
copies behind.

Originated from @realcarsonterry PR #1462 (1 of 42 sites). Helper
extraction, 42-site rewrite, alias-resolution edge case, and Windows
cleanup compat authored on this branch.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 setup | 137 ++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 96 insertions(+), 41 deletions(-)

diff --git a/setup b/setup
index f812511e4..b51fed83d 100755
--- a/setup
+++ b/setup
@@ -30,6 +30,47 @@ case "$(uname -s)" in
   MINGW*|MSYS*|CYGWIN*|Windows_NT) IS_WINDOWS=1 ;;
 esac
 
+# ─── Symlink-or-copy helper ───────────────────────────────────
+# On macOS/Linux: create a symlink (existing behavior).
+# On Windows without Developer Mode (MSYS2/Git Bash): plain ln -snf silently
+# creates a frozen file copy that doesn't refresh after `git pull`. We use
+# explicit `cp -R` / `cp -f` so the user gets a real copy and the staleness
+# is reportable (re-run ./setup after pull). Auto-detects file vs dir.
+#
+# INVARIANT: every symlink in this script MUST route through this helper.
+# A raw ln call here will be caught by test/setup-windows-fallback.test.ts
+# (the static-invariant assertion D7).
+_link_or_copy() {
+  local src="$1"
+  local dst="$2"
+  if [ "$IS_WINDOWS" -eq 1 ]; then
+    rm -rf "$dst"
+    # Unix `ln -snf` accepts a name-only or relative-path source even when the
+    # target doesn't resolve from CWD (e.g. the connect-chrome alias points at
+    # the sibling-relative "gstack/open-gstack-browser"). On Windows the
+    # equivalent semantics don't exist — we'd need a real source on disk to
+    # copy. Skip the alias quietly rather than aborting setup under `set -e`.
+    if [ ! -e "$src" ]; then
+      return 0
+    fi
+    if [ -d "$src" ]; then
+      cp -R "$src" "$dst"
+    else
+      cp -f "$src" "$dst"
+    fi
+  else
+    ln -snf "$src" "$dst"
+  fi
+}
+
+_WINDOWS_COPY_NOTE_PRINTED=0
+_print_windows_copy_note_once() {
+  if [ "$IS_WINDOWS" -eq 1 ] && [ "$_WINDOWS_COPY_NOTE_PRINTED" -eq 0 ]; then
+    echo "  note: Windows install uses file copies (no Developer Mode required). Re-run ./setup after every 'git pull' to refresh skill files."
+    _WINDOWS_COPY_NOTE_PRINTED=1
+  fi
+}
+
 # ─── Quiet mode helper ────────────────────────────────────────
 QUIET=0
 log() { [ "$QUIET" -eq 0 ] && echo "$@" || true; }
@@ -401,12 +442,13 @@ link_claude_skill_dirs() {
       mkdir -p "$target"
       # Validate target isn't a symlink before creating the link
       if [ -L "$target/SKILL.md" ]; then rm "$target/SKILL.md"; fi
-      ln -snf "$gstack_dir/$dir_name/SKILL.md" "$target/SKILL.md"
+      _link_or_copy "$gstack_dir/$dir_name/SKILL.md" "$target/SKILL.md"
       linked+=("$link_name")
     fi
   done
   if [ ${#linked[@]} -gt 0 ]; then
     echo "  linked skills: ${linked[*]}"
+    _print_windows_copy_note_once
   fi
 }
 
@@ -442,6 +484,13 @@ cleanup_old_claude_symlinks() {
             removed+=("$skill_name")
             ;;
         esac
+      # Windows install pattern: real dir with real-file SKILL.md (no symlink
+      # available, so we can't readlink to verify provenance). The outer loop
+      # iterates known gstack skill names from "$gstack_dir"/*, so a name match
+      # plus IS_WINDOWS is safe to treat as gstack-managed during a mode flip.
+      elif [ "$IS_WINDOWS" -eq 1 ] && [ -d "$old_target" ] && [ -f "$old_target/SKILL.md" ]; then
+        rm -rf "$old_target"
+        removed+=("$skill_name")
       fi
     fi
   done
@@ -483,6 +532,12 @@ cleanup_prefixed_claude_symlinks() {
             removed+=("gstack-$skill_name")
             ;;
         esac
+      # Windows install pattern: real dir with real-file SKILL.md. Same
+      # reasoning as cleanup_old_claude_symlinks — directory name match plus
+      # IS_WINDOWS is safe during a mode flip.
+      elif [ "$IS_WINDOWS" -eq 1 ] && [ -d "$prefixed_target" ] && [ -f "$prefixed_target/SKILL.md" ]; then
+        rm -rf "$prefixed_target"
+        removed+=("gstack-$skill_name")
       fi
     fi
   done
@@ -520,7 +575,7 @@ link_codex_skill_dirs() {
       target="$skills_dir/$skill_name"
       # Create or update symlink
       if [ -L "$target" ] || [ ! -e "$target" ]; then
-        ln -snf "$skill_dir" "$target"
+        _link_or_copy "$skill_dir" "$target"
         linked+=("$skill_name")
       fi
     fi
@@ -545,7 +600,7 @@ create_agents_sidecar() {
     local dst="$agents_gstack/$asset"
     if [ -d "$src" ] || [ -f "$src" ]; then
       if [ -L "$dst" ] || [ ! -e "$dst" ]; then
-        ln -snf "$src" "$dst"
+        _link_or_copy "$src" "$dst"
       fi
     fi
   done
@@ -556,7 +611,7 @@ create_agents_sidecar() {
     local dst="$agents_gstack/$file"
     if [ -f "$src" ]; then
       if [ -L "$dst" ] || [ ! -e "$dst" ]; then
-        ln -snf "$src" "$dst"
+        _link_or_copy "$src" "$dst"
       fi
     fi
   done
@@ -582,29 +637,29 @@ create_codex_runtime_root() {
   mkdir -p "$codex_gstack" "$codex_gstack/browse" "$codex_gstack/gstack-upgrade" "$codex_gstack/review"
 
   if [ -f "$agents_dir/gstack/SKILL.md" ]; then
-    ln -snf "$agents_dir/gstack/SKILL.md" "$codex_gstack/SKILL.md"
+    _link_or_copy "$agents_dir/gstack/SKILL.md" "$codex_gstack/SKILL.md"
   fi
   if [ -d "$gstack_dir/bin" ]; then
-    ln -snf "$gstack_dir/bin" "$codex_gstack/bin"
+    _link_or_copy "$gstack_dir/bin" "$codex_gstack/bin"
   fi
   if [ -d "$gstack_dir/browse/dist" ]; then
-    ln -snf "$gstack_dir/browse/dist" "$codex_gstack/browse/dist"
+    _link_or_copy "$gstack_dir/browse/dist" "$codex_gstack/browse/dist"
   fi
   if [ -d "$gstack_dir/browse/bin" ]; then
-    ln -snf "$gstack_dir/browse/bin" "$codex_gstack/browse/bin"
+    _link_or_copy "$gstack_dir/browse/bin" "$codex_gstack/browse/bin"
   fi
   if [ -f "$agents_dir/gstack-upgrade/SKILL.md" ]; then
-    ln -snf "$agents_dir/gstack-upgrade/SKILL.md" "$codex_gstack/gstack-upgrade/SKILL.md"
+    _link_or_copy "$agents_dir/gstack-upgrade/SKILL.md" "$codex_gstack/gstack-upgrade/SKILL.md"
   fi
   # Review runtime assets (individual files, NOT the whole review/ dir which has SKILL.md)
   for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
     if [ -f "$gstack_dir/review/$f" ]; then
-      ln -snf "$gstack_dir/review/$f" "$codex_gstack/review/$f"
+      _link_or_copy "$gstack_dir/review/$f" "$codex_gstack/review/$f"
     fi
   done
   # ETHOS.md — referenced by "Search Before Building" in all skill preambles
   if [ -f "$gstack_dir/ETHOS.md" ]; then
-    ln -snf "$gstack_dir/ETHOS.md" "$codex_gstack/ETHOS.md"
+    _link_or_copy "$gstack_dir/ETHOS.md" "$codex_gstack/ETHOS.md"
   fi
 }
 
@@ -622,27 +677,27 @@ create_factory_runtime_root() {
   mkdir -p "$factory_gstack" "$factory_gstack/browse" "$factory_gstack/gstack-upgrade" "$factory_gstack/review"
 
   if [ -f "$factory_dir/gstack/SKILL.md" ]; then
-    ln -snf "$factory_dir/gstack/SKILL.md" "$factory_gstack/SKILL.md"
+    _link_or_copy "$factory_dir/gstack/SKILL.md" "$factory_gstack/SKILL.md"
   fi
   if [ -d "$gstack_dir/bin" ]; then
-    ln -snf "$gstack_dir/bin" "$factory_gstack/bin"
+    _link_or_copy "$gstack_dir/bin" "$factory_gstack/bin"
   fi
   if [ -d "$gstack_dir/browse/dist" ]; then
-    ln -snf "$gstack_dir/browse/dist" "$factory_gstack/browse/dist"
+    _link_or_copy "$gstack_dir/browse/dist" "$factory_gstack/browse/dist"
   fi
   if [ -d "$gstack_dir/browse/bin" ]; then
-    ln -snf "$gstack_dir/browse/bin" "$factory_gstack/browse/bin"
+    _link_or_copy "$gstack_dir/browse/bin" "$factory_gstack/browse/bin"
   fi
   if [ -f "$factory_dir/gstack-upgrade/SKILL.md" ]; then
-    ln -snf "$factory_dir/gstack-upgrade/SKILL.md" "$factory_gstack/gstack-upgrade/SKILL.md"
+    _link_or_copy "$factory_dir/gstack-upgrade/SKILL.md" "$factory_gstack/gstack-upgrade/SKILL.md"
   fi
   for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
     if [ -f "$gstack_dir/review/$f" ]; then
-      ln -snf "$gstack_dir/review/$f" "$factory_gstack/review/$f"
+      _link_or_copy "$gstack_dir/review/$f" "$factory_gstack/review/$f"
     fi
   done
   if [ -f "$gstack_dir/ETHOS.md" ]; then
-    ln -snf "$gstack_dir/ETHOS.md" "$factory_gstack/ETHOS.md"
+    _link_or_copy "$gstack_dir/ETHOS.md" "$factory_gstack/ETHOS.md"
   fi
 }
 
@@ -660,42 +715,42 @@ create_opencode_runtime_root() {
   mkdir -p "$opencode_gstack" "$opencode_gstack/browse" "$opencode_gstack/design" "$opencode_gstack/gstack-upgrade" "$opencode_gstack/review" "$opencode_gstack/qa" "$opencode_gstack/plan-devex-review"
 
   if [ -f "$opencode_dir/gstack/SKILL.md" ]; then
-    ln -snf "$opencode_dir/gstack/SKILL.md" "$opencode_gstack/SKILL.md"
+    _link_or_copy "$opencode_dir/gstack/SKILL.md" "$opencode_gstack/SKILL.md"
   fi
   if [ -d "$gstack_dir/bin" ]; then
-    ln -snf "$gstack_dir/bin" "$opencode_gstack/bin"
+    _link_or_copy "$gstack_dir/bin" "$opencode_gstack/bin"
   fi
   if [ -d "$gstack_dir/browse/dist" ]; then
-    ln -snf "$gstack_dir/browse/dist" "$opencode_gstack/browse/dist"
+    _link_or_copy "$gstack_dir/browse/dist" "$opencode_gstack/browse/dist"
   fi
   if [ -d "$gstack_dir/browse/bin" ]; then
-    ln -snf "$gstack_dir/browse/bin" "$opencode_gstack/browse/bin"
+    _link_or_copy "$gstack_dir/browse/bin" "$opencode_gstack/browse/bin"
   fi
   if [ -d "$gstack_dir/design/dist" ]; then
-    ln -snf "$gstack_dir/design/dist" "$opencode_gstack/design/dist"
+    _link_or_copy "$gstack_dir/design/dist" "$opencode_gstack/design/dist"
   fi
   if [ -f "$opencode_dir/gstack-upgrade/SKILL.md" ]; then
-    ln -snf "$opencode_dir/gstack-upgrade/SKILL.md" "$opencode_gstack/gstack-upgrade/SKILL.md"
+    _link_or_copy "$opencode_dir/gstack-upgrade/SKILL.md" "$opencode_gstack/gstack-upgrade/SKILL.md"
   fi
   for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
     if [ -f "$gstack_dir/review/$f" ]; then
-      ln -snf "$gstack_dir/review/$f" "$opencode_gstack/review/$f"
+      _link_or_copy "$gstack_dir/review/$f" "$opencode_gstack/review/$f"
     fi
   done
   if [ -d "$gstack_dir/review/specialists" ]; then
-    ln -snf "$gstack_dir/review/specialists" "$opencode_gstack/review/specialists"
+    _link_or_copy "$gstack_dir/review/specialists" "$opencode_gstack/review/specialists"
   fi
   if [ -d "$gstack_dir/qa/templates" ]; then
-    ln -snf "$gstack_dir/qa/templates" "$opencode_gstack/qa/templates"
+    _link_or_copy "$gstack_dir/qa/templates" "$opencode_gstack/qa/templates"
   fi
   if [ -d "$gstack_dir/qa/references" ]; then
-    ln -snf "$gstack_dir/qa/references" "$opencode_gstack/qa/references"
+    _link_or_copy "$gstack_dir/qa/references" "$opencode_gstack/qa/references"
   fi
   if [ -f "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" ]; then
-    ln -snf "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" "$opencode_gstack/plan-devex-review/dx-hall-of-fame.md"
+    _link_or_copy "$gstack_dir/plan-devex-review/dx-hall-of-fame.md" "$opencode_gstack/plan-devex-review/dx-hall-of-fame.md"
   fi
   if [ -f "$gstack_dir/ETHOS.md" ]; then
-    ln -snf "$gstack_dir/ETHOS.md" "$opencode_gstack/ETHOS.md"
+    _link_or_copy "$gstack_dir/ETHOS.md" "$opencode_gstack/ETHOS.md"
   fi
 }
 
@@ -721,7 +776,7 @@ link_factory_skill_dirs() {
       [ "$skill_name" = "gstack" ] && continue
       target="$skills_dir/$skill_name"
       if [ -L "$target" ] || [ ! -e "$target" ]; then
-        ln -snf "$skill_dir" "$target"
+        _link_or_copy "$skill_dir" "$target"
         linked+=("$skill_name")
       fi
     fi
@@ -753,7 +808,7 @@ link_opencode_skill_dirs() {
       [ "$skill_name" = "gstack" ] && continue
       target="$skills_dir/$skill_name"
       if [ -L "$target" ] || [ ! -e "$target" ]; then
-        ln -snf "$skill_dir" "$target"
+        _link_or_copy "$skill_dir" "$target"
         linked+=("$skill_name")
       fi
     fi
@@ -796,7 +851,7 @@ if [ "$INSTALL_CLAUDE" -eq 1 ]; then
       _OGB_LINK="$INSTALL_SKILLS_DIR/gstack-connect-chrome"
     fi
     if [ -L "$_OGB_LINK" ] || [ ! -e "$_OGB_LINK" ]; then
-      ln -snf "gstack/open-gstack-browser" "$_OGB_LINK"
+      _link_or_copy "gstack/open-gstack-browser" "$_OGB_LINK"
     fi
     if [ "$LOCAL_INSTALL" -eq 1 ]; then
       log "gstack ready (project-local)."
@@ -842,7 +897,7 @@ if [ "$INSTALL_CLAUDE" -eq 1 ]; then
       log "  browse: $BROWSE_BIN"
     else
       mkdir -p "$CLAUDE_SKILLS_DIR"
-      ln -snf "$SOURCE_GSTACK_DIR" "$CLAUDE_GSTACK_LINK"
+      _link_or_copy "$SOURCE_GSTACK_DIR" "$CLAUDE_GSTACK_LINK"
       log "  symlinked $CLAUDE_GSTACK_LINK -> $SOURCE_GSTACK_DIR"
       INSTALL_SKILLS_DIR="$CLAUDE_SKILLS_DIR"
       INSTALL_GSTACK_DIR="$CLAUDE_GSTACK_LINK"
@@ -863,7 +918,7 @@ if [ "$INSTALL_CLAUDE" -eq 1 ]; then
         _OGB_LINK="$INSTALL_SKILLS_DIR/gstack-connect-chrome"
       fi
       if [ -L "$_OGB_LINK" ] || [ ! -e "$_OGB_LINK" ]; then
-        ln -snf "gstack/open-gstack-browser" "$_OGB_LINK"
+        _link_or_copy "gstack/open-gstack-browser" "$_OGB_LINK"
       fi
       log "gstack ready (claude)."
       log "  browse: $BROWSE_BIN"
@@ -903,21 +958,21 @@ if [ "$INSTALL_KIRO" -eq 1 ]; then
   # Remove old whole-dir symlink from previous installs
   [ -L "$KIRO_GSTACK" ] && rm -f "$KIRO_GSTACK"
   mkdir -p "$KIRO_GSTACK" "$KIRO_GSTACK/browse" "$KIRO_GSTACK/gstack-upgrade" "$KIRO_GSTACK/review"
-  ln -snf "$SOURCE_GSTACK_DIR/bin" "$KIRO_GSTACK/bin"
-  ln -snf "$SOURCE_GSTACK_DIR/browse/dist" "$KIRO_GSTACK/browse/dist"
-  ln -snf "$SOURCE_GSTACK_DIR/browse/bin" "$KIRO_GSTACK/browse/bin"
+  _link_or_copy "$SOURCE_GSTACK_DIR/bin" "$KIRO_GSTACK/bin"
+  _link_or_copy "$SOURCE_GSTACK_DIR/browse/dist" "$KIRO_GSTACK/browse/dist"
+  _link_or_copy "$SOURCE_GSTACK_DIR/browse/bin" "$KIRO_GSTACK/browse/bin"
   # ETHOS.md — referenced by "Search Before Building" in all skill preambles
   if [ -f "$SOURCE_GSTACK_DIR/ETHOS.md" ]; then
-    ln -snf "$SOURCE_GSTACK_DIR/ETHOS.md" "$KIRO_GSTACK/ETHOS.md"
+    _link_or_copy "$SOURCE_GSTACK_DIR/ETHOS.md" "$KIRO_GSTACK/ETHOS.md"
   fi
   # gstack-upgrade skill
   if [ -f "$AGENTS_DIR/gstack-upgrade/SKILL.md" ]; then
-    ln -snf "$AGENTS_DIR/gstack-upgrade/SKILL.md" "$KIRO_GSTACK/gstack-upgrade/SKILL.md"
+    _link_or_copy "$AGENTS_DIR/gstack-upgrade/SKILL.md" "$KIRO_GSTACK/gstack-upgrade/SKILL.md"
   fi
   # Review runtime assets (individual files, not whole dir)
   for f in checklist.md design-checklist.md greptile-triage.md TODOS-format.md; do
     if [ -f "$SOURCE_GSTACK_DIR/review/$f" ]; then
-      ln -snf "$SOURCE_GSTACK_DIR/review/$f" "$KIRO_GSTACK/review/$f"
+      _link_or_copy "$SOURCE_GSTACK_DIR/review/$f" "$KIRO_GSTACK/review/$f"
     fi
   done
 

From 4288756aac4b17567e34e5b0755be07914327cf1 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:01:45 -0700
Subject: [PATCH 03/12] fix(docs): rename stale gbrain_sync_mode to
 artifacts_sync_mode + register /document-generate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five stale gstack-config references in docs/ pointed to the deprecated
gbrain_sync_mode key (renamed to artifacts_sync_mode in v1.27.0.0):
- docs/gbrain-sync.md: lines 62, 110, 111, 173
- docs/gbrain-sync-errors.md: lines 26, 203

Users following the docs would set a key that gstack-brain-sync no
longer reads, silently breaking artifacts sync.

Originated from @realcarsonterry PR #1461 (verbatim).

Also register /document-generate in AGENTS.md (Operational + memory
table) and docs/skills.md (skill index). The skill shipped in v1.35.0.0
but the doc-inventory cross-check in test/skill-validation.test.ts was
failing because neither file mentioned it.

Allowlist the new test/docs-config-keys.test.ts file in
test/no-stale-gstack-brain-refs.test.ts — it intentionally lists the
deprecated keys in its DEPRECATED_KEYS denylist (defending the rename).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 AGENTS.md                               | 1 +
 docs/gbrain-sync-errors.md              | 4 ++--
 docs/gbrain-sync.md                     | 8 ++++----
 docs/skills.md                          | 1 +
 test/no-stale-gstack-brain-refs.test.ts | 3 +++
 5 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c1e5595fc..868ea55c9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,6 +47,7 @@ Invoke them by name (e.g., `/office-hours`).
 | `/canary` | Post-deploy monitoring loop using the browse daemon. |
 | `/landing-report` | Read-only dashboard for the workspace-aware ship queue. |
 | `/document-release` | Update all docs to match what you just shipped. |
+| `/document-generate` | Write missing docs from scratch in four Diataxis quadrants. |
 | `/setup-deploy` | One-time deploy config detection (Fly.io, Render, Vercel, etc.). |
 | `/gstack-upgrade` | Update gstack to the latest version. |
 
diff --git a/docs/gbrain-sync-errors.md b/docs/gbrain-sync-errors.md
index 52120a8b2..7ab50cdfe 100644
--- a/docs/gbrain-sync-errors.md
+++ b/docs/gbrain-sync-errors.md
@@ -23,7 +23,7 @@ This pulls the repo into `~/.gstack/` and re-registers merge drivers.
 
 If you don't want to restore here, dismiss the hint with:
 ```bash
-gstack-config set gbrain_sync_mode_prompted true
+gstack-config set artifacts_sync_mode_prompted true
 ```
 
 ---
@@ -200,7 +200,7 @@ canonical config files from the brain repo.
 
 1. `gstack-brain-sync --status` — is mode `off`?
 2. `~/.gstack/.git` exists?
-3. `gstack-config get gbrain_sync_mode` — should be `full` or `artifacts-only`.
+3. `gstack-config get artifacts_sync_mode` — should be `full` or `artifacts-only`.
 4. The file you expect to sync — is it in the allowlist?
    `cat ~/.gstack/.brain-allowlist`
 5. Privacy class filter — if mode is `artifacts-only`, behavioral files
diff --git a/docs/gbrain-sync.md b/docs/gbrain-sync.md
index e5f1d7007..62a12b56a 100644
--- a/docs/gbrain-sync.md
+++ b/docs/gbrain-sync.md
@@ -59,7 +59,7 @@ privacy mode:
 - **Only artifacts**: plans, designs, retros, learnings — skip
   behavioral data (timelines, developer profile).
 - **Decline**: keep everything local. You can turn sync on later with
-  `gstack-config set gbrain_sync_mode full`.
+  `gstack-config set artifacts_sync_mode full`.
 
 Your answer is persisted. You won't be asked again.
 
@@ -107,8 +107,8 @@ output. Scan it for problems.
 
 Change anytime with:
 ```bash
-gstack-config set gbrain_sync_mode full
-gstack-config set gbrain_sync_mode off
+gstack-config set artifacts_sync_mode full
+gstack-config set artifacts_sync_mode off
 ```
 
 ## Secret protection
@@ -170,7 +170,7 @@ gstack-brain-uninstall
 This:
 
 - Removes `~/.gstack/.git/` and all `.brain-*` config files.
-- Clears `gbrain_sync_mode` in `gstack-config`.
+- Clears `artifacts_sync_mode` in `gstack-config`.
 - Does NOT touch your learnings, plans, retros, or developer profile.
 
 Add `--delete-remote` to also delete the private GitHub repo (GitHub only,
diff --git a/docs/skills.md b/docs/skills.md
index b20bf665d..626af0f80 100644
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -24,6 +24,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
 | [`/benchmark`](#benchmark) | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. Track trends over time. |
 | [`/cso`](#cso) | **Chief Security Officer** | OWASP Top 10 + STRIDE threat modeling security audit. Scans for injection, auth, crypto, and access control issues. |
 | [`/document-release`](#document-release) | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
+| [`/document-generate`](#document-generate) | **Documentation Architect** | Bootstrap docs from scratch. Reads the codebase, partitions the public surface, writes the four Diataxis quadrants: tutorial, how-to, reference, explanation. |
 | [`/retro`](#retro) | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. |
 | [`/browse`](#browse) | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
 | [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
diff --git a/test/no-stale-gstack-brain-refs.test.ts b/test/no-stale-gstack-brain-refs.test.ts
index 509299183..5aa007d67 100644
--- a/test/no-stale-gstack-brain-refs.test.ts
+++ b/test/no-stale-gstack-brain-refs.test.ts
@@ -55,6 +55,9 @@ const ALLOWLIST = [
   'test/gstack-upgrade.test.ts',
   // This test itself references the patterns to grep for.
   'test/no-stale-gstack-brain-refs.test.ts',
+  // The v1.36.0.0 doc-config drift guard intentionally defends the rename
+  // by listing the deprecated keys in its DEPRECATED_KEYS denylist.
+  'test/docs-config-keys.test.ts',
   // memory.md documents the rename context.
   'setup-gbrain/memory.md',
   // The new init script's header comment intentionally cites the rename.

From f8bffda67e5e02d183b266863116f9c8a67fa30b Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:01:54 -0700
Subject: [PATCH 04/12] ci(windows): migrate windows-free-tests to paid faster
 runner + register wave tests

Move the Windows free-test job from GitHub-hosted windows-latest to
Blacksmith's paid Windows runner (blacksmith-2vcpu-windows-2022).
Spin-up drops from ~60s to ~10s and Bun installs land 3-4x faster. The
label can swap to namespace-profile-windows or ubicloud-windows-* if
this repo's Blacksmith installation isn't configured.

Register the four new wave tests in the workflow's curated test list:
  - browse/test/server-sanitize-surrogates.test.ts
  - test/setup-windows-fallback.test.ts
  - test/build-script-shell-compat.test.ts
  - test/docs-config-keys.test.ts

These tests cover the Windows-hardening surface that this wave ships
(sanitizer wiring, _link_or_copy helper, build-script subshells, doc-
config drift), so they need to run on Windows where the bug shapes
actually manifest.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/windows-free-tests.yml | 25 +++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/windows-free-tests.yml b/.github/workflows/windows-free-tests.yml
index 1b0d5c793..533089dd5 100644
--- a/.github/workflows/windows-free-tests.yml
+++ b/.github/workflows/windows-free-tests.yml
@@ -1,6 +1,6 @@
 name: Windows Free Tests
 
-# Curated subset of the free test suite that runs on windows-latest.
+# Curated subset of the free test suite that runs on a paid faster Windows runner.
 #
 # Codex's v1.18.0.0 review flagged that the existing evals.yml workflow uses
 # a Linux container, so a windows-latest matrix entry there isn't a drop-in.
@@ -8,11 +8,17 @@ name: Windows Free Tests
 # targeted resolver tests that exercise the Bun.which-based claude binary
 # resolution + the GSTACK_CLAUDE_BIN override path on Windows.
 #
-# What this DOES NOT do (out of scope for v1.18.0.0):
+# Runner: migrated v1.36.0.0 from GitHub-hosted `windows-latest` to Blacksmith's
+# paid Windows runner. Spin-up is ~10s vs ~60s and Bun installs land 3-4x faster.
+# If Blacksmith isn't configured for this org, swap to `windows-latest` (the
+# free GitHub runner, slower but always available). Namespace, Ubicloud-Windows,
+# and other paid pools work too — just match your org's billing.
+#
+# What this DOES NOT do (still out of scope, tracked as follow-up):
 #   - Run the full free suite on Windows. The 24 tests that hardcode /bin/sh,
 #     spawn('sh',...), or raw /tmp/ paths are excluded by scripts/test-free-shards.ts
 #     --windows-only. They need POSIX-bound surfaces to be ported off shell
-#     primitives before they can run on Windows. Tracked as a follow-up TODO.
+#     primitives before they can run on Windows.
 #   - Run Playwright/browser-backed tests. Browse server bring-up on Windows is
 #     a separate concern (PR #1238 windows-pty-bun-pty-fix is in flight).
 
@@ -27,7 +33,10 @@ concurrency:
 
 jobs:
   windows-free-tests:
-    runs-on: windows-latest
+    # Paid faster Windows runner. Verify the label matches what's enabled for
+    # this repo's Blacksmith installation. Common alternatives:
+    #   blacksmith-4vcpu-windows-2022, namespace-profile-windows, windows-latest
+    runs-on: blacksmith-2vcpu-windows-2022
     timeout-minutes: 15
 
     steps:
@@ -91,7 +100,9 @@ jobs:
         continue-on-error: true
 
       - name: Verify new portability work on Windows
-        # Tests targeting the v1.20.0.0 lane plus v1.30.0.0 fix-wave additions.
+        # Tests targeting the v1.20.0.0 lane plus v1.30.0.0 fix-wave additions
+        # plus v1.36.0.0 Windows-install hardening (sanitizer + _link_or_copy
+        # helper + build-script subshells + doc/config-key drift guard).
         # v1.30.0.0 extension covers icacls hardening (#1308), bash.exe telemetry
         # wrap (#1306), and Bun.which-based binary resolvers (#1307). These must
         # pass on Windows for the wave's "Windows hardening" framing to be honest.
@@ -102,6 +113,10 @@ jobs:
             test/test-free-shards.test.ts \
             browse/test/file-permissions.test.ts \
             browse/test/security.test.ts \
+            browse/test/server-sanitize-surrogates.test.ts \
+            test/setup-windows-fallback.test.ts \
+            test/build-script-shell-compat.test.ts \
+            test/docs-config-keys.test.ts \
             make-pdf/test/browseClient.test.ts \
             make-pdf/test/pdftotext.test.ts
         shell: bash

From f5c2fee3a9dca55ad1f2785a9d8c8d0780689a2c Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:02:10 -0700
Subject: [PATCH 05/12] test: wave coverage for sanitizer, link_or_copy, build
 script, doc drift
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four new test files (29 cases total):

browse/test/server-sanitize-surrogates.test.ts:
  - 11 unit cases for sanitizeLoneSurrogates (passthrough, valid pair,
    lone high/low mid-string, trailing/leading lone, adjacent doubles,
    pair-then-lone, lone-then-pair, empty)
  - 2 bug-repro tests pinning the regression intent (UTF-8 round-trip,
    JSON.parse round-trip with codepoint assertion)
  - 4 wiring invariants asserting the architectural choke points stay
    intact (handleCommandInternalImpl rename, central sanitization
    line, sanitizeReplacer function exists, SSE producers stringify
    with replacer)
  Function extracted from server.ts via regex + eval'd in test scope
  so no production-code export is needed.

test/setup-windows-fallback.test.ts:
  - Static invariant (D7): zero raw `ln` calls outside the
    _link_or_copy helper body and comments
  - Helper-existence assertions
  - 4-cell behavior matrix (file/dir × Windows/Unix) via awk-style
    helper extraction + bash -c sourcing
  - Windows-note printer registration check
  Mirrors test/setup-conductor-worktree.test.ts patterns.

test/build-script-shell-compat.test.ts:
  - Regex assertion that package.json scripts.* contain no bash brace
    groups (Bun-Windows-hostile)
  - Subshell-precedence check for `.version` redirects
  Strips single-quoted strings before regexing so embedded JS code
  inside echo '...' doesn't false-positive.

test/docs-config-keys.test.ts:
  - DEPRECATED_KEYS denylist scanned across docs/**/*.md
  - Round-trip test for `gstack-config get artifacts_sync_mode`
  Defends the v1.27.0.0 rename from doc drift.

Updates to two existing tests:
  - test/setup-conductor-worktree.test.ts: expect `_link_or_copy`
    instead of `ln -snf` at the Conductor-worktree guard call site
  - test/gen-skill-docs.test.ts: same swap at three assertion sites
    (Codex section, Claude link_claude_skill_dirs body, Codex
    link_codex_skill_dirs body)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../test/server-sanitize-surrogates.test.ts   | 129 ++++++++++++++++++
 test/build-script-shell-compat.test.ts        |  40 ++++++
 test/docs-config-keys.test.ts                 |  81 +++++++++++
 test/gen-skill-docs.test.ts                   |   7 +-
 test/setup-conductor-worktree.test.ts         |   5 +-
 test/setup-windows-fallback.test.ts           | 122 +++++++++++++++++
 6 files changed, 379 insertions(+), 5 deletions(-)
 create mode 100644 browse/test/server-sanitize-surrogates.test.ts
 create mode 100644 test/build-script-shell-compat.test.ts
 create mode 100644 test/docs-config-keys.test.ts
 create mode 100644 test/setup-windows-fallback.test.ts

diff --git a/browse/test/server-sanitize-surrogates.test.ts b/browse/test/server-sanitize-surrogates.test.ts
new file mode 100644
index 000000000..156d9a3e9
--- /dev/null
+++ b/browse/test/server-sanitize-surrogates.test.ts
@@ -0,0 +1,129 @@
+import { describe, test, expect } from 'bun:test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// The sanitizer is module-private in server.ts. Rather than refactor it to a
+// separate module just for testing, we extract its source via a regex slice and
+// eval it in a fresh function scope. Keeps the production layout untouched.
+const SERVER_PATH = path.resolve(import.meta.dir, '..', 'src', 'server.ts');
+const SERVER_SRC = fs.readFileSync(SERVER_PATH, 'utf-8');
+
+const fnMatch = SERVER_SRC.match(
+  /function sanitizeLoneSurrogates\(str: string\): string \{[\s\S]*?\n\}/
+);
+if (!fnMatch) throw new Error('Could not locate sanitizeLoneSurrogates in server.ts');
+
+// Strip TS annotations so eval works under plain JS.
+const jsSrc = fnMatch[0].replace('(str: string): string', '(str)');
+const sanitizeLoneSurrogates = new Function(`${jsSrc}\nreturn sanitizeLoneSurrogates;`)() as (
+  s: string,
+) => string;
+
+describe('sanitizeLoneSurrogates — unit cases', () => {
+  test('passthrough ASCII', () => {
+    expect(sanitizeLoneSurrogates('hello')).toBe('hello');
+  });
+
+  test('passthrough empty string', () => {
+    expect(sanitizeLoneSurrogates('')).toBe('');
+  });
+
+  test('preserves valid surrogate pair (U+1F389 🎉)', () => {
+    expect(sanitizeLoneSurrogates('hi 🎉')).toBe('hi 🎉');
+  });
+
+  test('replaces lone high surrogate mid-string', () => {
+    expect(sanitizeLoneSurrogates('a\uD800b')).toBe('a�b');
+  });
+
+  test('replaces lone low surrogate mid-string', () => {
+    expect(sanitizeLoneSurrogates('a\uDC00b')).toBe('a�b');
+  });
+
+  test('replaces trailing lone high at end of string', () => {
+    expect(sanitizeLoneSurrogates('a\uD800')).toBe('a�');
+  });
+
+  test('replaces leading lone low at start of string', () => {
+    expect(sanitizeLoneSurrogates('\uDC00b')).toBe('�b');
+  });
+
+  test('replaces two adjacent lone highs', () => {
+    expect(sanitizeLoneSurrogates('\uD800\uD800')).toBe('��');
+  });
+
+  test('replaces two adjacent lone lows', () => {
+    expect(sanitizeLoneSurrogates('\uDC00\uDC00')).toBe('��');
+  });
+
+  test('preserves valid pair followed by lone low', () => {
+    // 𐀀 = U+10000 = 𐀀, then a separate lone low.
+    const input = '𐀀\uDC00';
+    const output = sanitizeLoneSurrogates(input);
+    // Valid pair intact, trailing lone low replaced.
+    expect(output).toBe('𐀀�');
+  });
+
+  test('preserves valid pair preceded by lone low', () => {
+    const input = '\uDC00𐀀';
+    const output = sanitizeLoneSurrogates(input);
+    expect(output).toBe('�𐀀');
+  });
+});
+
+describe('sanitizeLoneSurrogates — bug-repro (D5)', () => {
+  // Pin the regression intent: a future refactor that drops sanitization
+  // must fail this test even if happy-path tests still pass.
+  test('unsanitized lone surrogate causes UTF-8 encode to substitute, sanitized version is stable', () => {
+    const badPayload = 'page content\uD800more content';
+
+    // Buffer.from(str, 'utf-8') silently substitutes invalid sequences with
+    // EF BF BD (U+FFFD). Round-trip is therefore lossy for lone surrogates.
+    const roundTrippedRaw = Buffer.from(badPayload, 'utf-8').toString('utf-8');
+    expect(roundTrippedRaw).not.toBe(badPayload); // proves the bug exists pre-sanitize
+
+    // After sanitization the round-trip is stable.
+    const sanitized = sanitizeLoneSurrogates(badPayload);
+    const roundTrippedSanitized = Buffer.from(sanitized, 'utf-8').toString('utf-8');
+    expect(roundTrippedSanitized).toBe(sanitized);
+  });
+
+  test('JSON.parse(JSON.stringify(...)) round-trip is stable after sanitization', () => {
+    // Anthropic's API path wraps the response body in a tool_result JSON
+    // object. JSON.stringify CAN encode a lone surrogate (escapes it), but
+    // some downstream consumers reject the resulting body.
+    const badPayload = 'before\uD800after';
+    const sanitized = sanitizeLoneSurrogates(badPayload);
+    const wrapped = JSON.stringify({ content: sanitized });
+    const reparsed = JSON.parse(wrapped) as { content: string };
+    // .toBe(sanitized) already proves the surrogate was replaced; the
+    // additional explicit check below documents the specific code points.
+    expect(reparsed.content).toBe(sanitized);
+    expect(reparsed.content.charCodeAt(6)).toBe(0xfffd); // � not \uD800
+  });
+});
+
+describe('sanitizeLoneSurrogates — wiring invariants', () => {
+  test('server.ts wraps every command result through handleCommandInternal', () => {
+    // The architectural choice is to wrap once at handleCommandInternal so
+    // both single-command HTTP and the batch loop inherit. If a future
+    // refactor moves sanitization back to handleCommand only, this test
+    // fails by detecting the missing wrapper.
+    expect(SERVER_SRC).toContain('async function handleCommandInternalImpl(');
+    expect(SERVER_SRC).toContain('result: sanitizeLoneSurrogates(cr.result)');
+  });
+
+  test('SSE activity feed sanitizes outbound frames via sanitizeReplacer', () => {
+    // Replacer must run DURING stringify; post-stringify regex is ineffective
+    // because JSON.stringify converts \uD800 → "\\ud800" before our regex sees it.
+    expect(SERVER_SRC).toContain('JSON.stringify(entry, sanitizeReplacer)');
+  });
+
+  test('SSE inspector stream sanitizes outbound frames via sanitizeReplacer', () => {
+    expect(SERVER_SRC).toContain('JSON.stringify(event, sanitizeReplacer)');
+  });
+
+  test('sanitizeReplacer is a function defined in server.ts', () => {
+    expect(SERVER_SRC).toContain('function sanitizeReplacer(');
+  });
+});
diff --git a/test/build-script-shell-compat.test.ts b/test/build-script-shell-compat.test.ts
new file mode 100644
index 000000000..ee13fb709
--- /dev/null
+++ b/test/build-script-shell-compat.test.ts
@@ -0,0 +1,40 @@
+import { describe, test, expect } from 'bun:test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8')) as {
+  scripts: Record<string, string>;
+};
+
+// Strip single-quoted strings so JS code emitted as `echo '{ ... }'` doesn't
+// trip the shell-brace-group check. Conservative: only `'...'` segments.
+function stripSingleQuoted(s: string): string {
+  return s.replace(/'[^']*'/g, "''");
+}
+
+describe('package.json build scripts — POSIX shell compat (D-1460)', () => {
+  // Bun's Windows shell parser doesn't grok bash brace groups `{ cmd; }`.
+  // Subshells `( cmd )` are POSIX-universal. This test prevents regression.
+  test('no bash brace groups in any npm script', () => {
+    const offending: { script: string; pattern: string }[] = [];
+    for (const [name, body] of Object.entries(PKG.scripts)) {
+      const stripped = stripSingleQuoted(body);
+      const match = stripped.match(/\{\s+[^}]*;\s*\}/);
+      if (match) {
+        offending.push({ script: name, pattern: match[0] });
+      }
+    }
+    expect(offending).toEqual([]);
+  });
+
+  test('every `> path/.version` redirect is preceded by a subshell, not a brace group', () => {
+    // The original PR #1460 target: package.json line 12 had three of these.
+    const build = PKG.scripts.build ?? '';
+    const versionRedirects = [...build.matchAll(/(\([^)]*\)|\{[^}]*\})\s*>\s*\S+\/\.version/g)];
+    expect(versionRedirects.length).toBeGreaterThan(0);
+    for (const m of versionRedirects) {
+      expect(m[1].startsWith('(')).toBe(true);
+    }
+  });
+});
diff --git a/test/docs-config-keys.test.ts b/test/docs-config-keys.test.ts
new file mode 100644
index 000000000..2ced29d6e
--- /dev/null
+++ b/test/docs-config-keys.test.ts
@@ -0,0 +1,81 @@
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const CONFIG_BIN = path.join(ROOT, 'bin', 'gstack-config');
+
+// gstack-config accepts arbitrary keys (free-form YAML store), so we can't
+// build an authoritative set of "valid keys" from the script. Instead, defend
+// the specific invariant this wave introduces: deprecated keys must not
+// reappear in user-facing docs. Extend the denylist as future renames happen.
+const DEPRECATED_KEYS = new Set<string>([
+  // Renamed to artifacts_sync_mode in v1.27.0.0, doc references re-deprecated
+  // in v1.36.0.0 alongside the same rename of *_prompted.
+  'gbrain_sync_mode',
+  'gbrain_sync_mode_prompted',
+]);
+
+function scanDocsForConfigKeys(): { docPath: string; key: string; line: number }[] {
+  const hits: { docPath: string; key: string; line: number }[] = [];
+  const docsDir = path.join(ROOT, 'docs');
+  // Recurse docs/ but skip dotfiles. CHANGELOG.md/TODOS.md are excluded by virtue
+  // of being top-level; we only scan docs/**.
+  const stack = [docsDir];
+  while (stack.length) {
+    const cur = stack.pop()!;
+    for (const ent of fs.readdirSync(cur, { withFileTypes: true })) {
+      if (ent.name.startsWith('.')) continue;
+      const full = path.join(cur, ent.name);
+      if (ent.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!ent.name.endsWith('.md')) continue;
+      const text = fs.readFileSync(full, 'utf-8');
+      const lines = text.split('\n');
+      lines.forEach((line, idx) => {
+        // Match `gstack-config set <key>` or `gstack-config get <key>`.
+        for (const m of line.matchAll(/gstack-config\s+(?:set|get)\s+([a-z][a-z0-9_]*)/g)) {
+          hits.push({ docPath: full, key: m[1], line: idx + 1 });
+        }
+      });
+    }
+  }
+  return hits;
+}
+
+describe('docs ↔ gstack-config key drift guard', () => {
+  test('docs/ references at least one config key (smoke)', () => {
+    const hits = scanDocsForConfigKeys();
+    expect(hits.length).toBeGreaterThan(0);
+  });
+
+  test('no doc references a deprecated config key', () => {
+    const hits = scanDocsForConfigKeys();
+    const stale = hits.filter((h) => DEPRECATED_KEYS.has(h.key));
+    if (stale.length > 0) {
+      console.error('Deprecated config keys referenced in docs:', stale);
+    }
+    expect(stale).toEqual([]);
+  });
+
+  test('`gstack-config get artifacts_sync_mode` returns a value (the rename landed)', () => {
+    // Run from a clean HOME so the user's local config doesn't pollute.
+    const tmpHome = fs.mkdtempSync(path.join(require('os').tmpdir(), 'gstack-cfg-'));
+    try {
+      const result = spawnSync(CONFIG_BIN, ['get', 'artifacts_sync_mode'], {
+        encoding: 'utf-8',
+        env: { ...process.env, HOME: tmpHome, GSTACK_HOME: tmpHome },
+        timeout: 5000,
+      });
+      expect(result.status).toBe(0);
+      // A known key returns its default value, not the "unknown key" error string.
+      expect(result.stderr).not.toContain('not recognized');
+      expect(result.stdout.trim().length).toBeGreaterThan(0);
+    } finally {
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts
index 4bf8abeee..309fd7e4b 100644
--- a/test/gen-skill-docs.test.ts
+++ b/test/gen-skill-docs.test.ts
@@ -2198,7 +2198,7 @@ describe('setup script validation', () => {
     expect(codexSection).toContain('create_codex_runtime_root');
     expect(codexSection).toContain('link_codex_skill_dirs');
     expect(codexSection).not.toContain('link_claude_skill_dirs');
-    expect(codexSection).not.toContain('ln -snf "$GSTACK_DIR" "$CODEX_GSTACK"');
+    expect(codexSection).not.toContain('_link_or_copy "$GSTACK_DIR" "$CODEX_GSTACK"');
   });
 
   test('Codex install prefers repo-local .agents/skills when setup runs from there', () => {
@@ -2238,7 +2238,8 @@ describe('setup script validation', () => {
     const fnEnd = setupContent.indexOf('}', setupContent.indexOf('linked[@]}', fnStart));
     const fnBody = setupContent.slice(fnStart, fnEnd);
     expect(fnBody).toContain('mkdir -p "$target"');
-    expect(fnBody).toContain('ln -snf "$gstack_dir/$dir_name/SKILL.md" "$target/SKILL.md"');
+    // v1.36.0.0: routes through _link_or_copy helper for Windows fallback (cp on MSYS2/Git Bash).
+    expect(fnBody).toContain('_link_or_copy "$gstack_dir/$dir_name/SKILL.md" "$target/SKILL.md"');
   });
 
   // REGRESSION: cleanup functions must handle both old symlinks AND new real-directory pattern
@@ -2345,7 +2346,7 @@ describe('setup script validation', () => {
     expect(fnBody).toContain('design-checklist.md');
     expect(fnBody).toContain('greptile-triage.md');
     expect(fnBody).toContain('TODOS-format.md');
-    expect(fnBody).not.toContain('ln -snf "$gstack_dir" "$codex_gstack"');
+    expect(fnBody).not.toContain('_link_or_copy "$gstack_dir" "$codex_gstack"');
   });
 
   test('direct Codex installs are migrated out of ~/.codex/skills/gstack', () => {
diff --git a/test/setup-conductor-worktree.test.ts b/test/setup-conductor-worktree.test.ts
index 6fb675afc..29609ac8f 100644
--- a/test/setup-conductor-worktree.test.ts
+++ b/test/setup-conductor-worktree.test.ts
@@ -8,10 +8,11 @@ const ROOT = path.resolve(import.meta.dir, '..');
 const SETUP_SCRIPT = path.join(ROOT, 'setup');
 
 describe('setup: Conductor worktree guard', () => {
-  test('setup contains the real-dir guard before the ln -snf into ~/.claude/skills/', () => {
+  test('setup contains the real-dir guard before the symlink-or-copy into ~/.claude/skills/', () => {
     const content = fs.readFileSync(SETUP_SCRIPT, 'utf-8');
     const guardIdx = content.indexOf('_SKIP_CLAUDE_REGISTER=0');
-    const lnIdx = content.indexOf('ln -snf "$SOURCE_GSTACK_DIR" "$CLAUDE_GSTACK_LINK"');
+    // v1.36.0.0: symlink work routes through _link_or_copy helper for Windows fallback.
+    const lnIdx = content.indexOf('_link_or_copy "$SOURCE_GSTACK_DIR" "$CLAUDE_GSTACK_LINK"');
     expect(guardIdx).toBeGreaterThan(-1);
     expect(lnIdx).toBeGreaterThan(-1);
     expect(guardIdx).toBeLessThan(lnIdx);
diff --git a/test/setup-windows-fallback.test.ts b/test/setup-windows-fallback.test.ts
new file mode 100644
index 000000000..6c3735860
--- /dev/null
+++ b/test/setup-windows-fallback.test.ts
@@ -0,0 +1,122 @@
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const SETUP_SCRIPT = path.join(ROOT, 'setup');
+const SETUP_SRC = fs.readFileSync(SETUP_SCRIPT, 'utf-8');
+
+// Slice out the _link_or_copy helper body via awk-style anchors so the test is
+// resilient to line-number drift.
+function extractHelper(): string {
+  const start = SETUP_SRC.indexOf('_link_or_copy() {');
+  const end = SETUP_SRC.indexOf('\n}\n', start);
+  if (start < 0 || end < 0) throw new Error('Could not locate _link_or_copy() in setup');
+  return SETUP_SRC.slice(start, end + 2);
+}
+
+describe('setup: _link_or_copy invariant (D7)', () => {
+  test('helper function is defined near the top of setup', () => {
+    expect(SETUP_SRC).toContain('_link_or_copy() {');
+    expect(SETUP_SRC).toContain('if [ "$IS_WINDOWS" -eq 1 ]; then');
+  });
+
+  test('zero raw `ln` calls outside the helper body and comments', () => {
+    // Pull the helper body out of the source first so its internal `ln -snf`
+    // (the Unix branch) is exempted from the invariant.
+    const helper = extractHelper();
+    const withoutHelper = SETUP_SRC.replace(helper, '');
+
+    // Strip shell comments to allow prose mentions of `ln -snf` in docstrings.
+    const lines = withoutHelper.split('\n');
+    const offending: { lineNo: number; line: string }[] = [];
+    lines.forEach((line, idx) => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('#')) return;
+      // Match standalone `ln ` invocations (allow `ln` as a substring in
+      // variable names like `linked`, `_LINK`).
+      if (/(^|[\s;&|`])ln\s+-/.test(line)) {
+        offending.push({ lineNo: idx + 1, line: line.trim() });
+      }
+    });
+    expect(offending).toEqual([]);
+  });
+
+  test('Windows-copy note message exists in setup', () => {
+    expect(SETUP_SRC).toContain('Windows install uses file copies');
+    expect(SETUP_SRC).toContain('_print_windows_copy_note_once');
+  });
+
+  test('link_claude_skill_dirs calls the Windows note printer', () => {
+    const fnStart = SETUP_SRC.indexOf('link_claude_skill_dirs() {');
+    const fnEnd = SETUP_SRC.indexOf('\n}\n', fnStart);
+    const fnBody = SETUP_SRC.slice(fnStart, fnEnd);
+    expect(fnBody).toContain('_print_windows_copy_note_once');
+  });
+});
+
+describe('setup: _link_or_copy helper — behavior matrix', () => {
+  // Source the helper into a temp shell with IS_WINDOWS set and exercise
+  // each cell of the file/dir × Windows/Unix matrix.
+  function runHelper(
+    isWindows: '0' | '1',
+    srcKind: 'file' | 'dir',
+  ): { ok: boolean; targetIsSymlink: boolean; targetExists: boolean; stderr: string } {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-helper-'));
+    try {
+      const src = path.join(tmp, 'source');
+      const dst = path.join(tmp, 'dest');
+      if (srcKind === 'file') {
+        fs.writeFileSync(src, 'hello\n');
+      } else {
+        fs.mkdirSync(src);
+        fs.writeFileSync(path.join(src, 'inner.txt'), 'hello\n');
+      }
+      const helper = extractHelper();
+      // IS_WINDOWS must exist as a shell-readable var before sourcing.
+      const script = `IS_WINDOWS=${isWindows}\n${helper}\n_link_or_copy "${src}" "${dst}"\n`;
+      const result = spawnSync('bash', ['-c', script], {
+        encoding: 'utf-8',
+        timeout: 5000,
+      });
+      const lst = fs.lstatSync(dst, { throwIfNoEntry: false });
+      return {
+        ok: result.status === 0,
+        targetIsSymlink: lst?.isSymbolicLink() ?? false,
+        targetExists: lst !== undefined,
+        stderr: result.stderr,
+      };
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+
+  test('IS_WINDOWS=0 + file → symlink (existing Unix behavior)', () => {
+    const r = runHelper('0', 'file');
+    expect(r.ok).toBe(true);
+    expect(r.targetExists).toBe(true);
+    expect(r.targetIsSymlink).toBe(true);
+  });
+
+  test('IS_WINDOWS=0 + dir → symlink', () => {
+    const r = runHelper('0', 'dir');
+    expect(r.ok).toBe(true);
+    expect(r.targetIsSymlink).toBe(true);
+  });
+
+  test('IS_WINDOWS=1 + file → regular file copy (no symlink)', () => {
+    const r = runHelper('1', 'file');
+    expect(r.ok).toBe(true);
+    expect(r.targetExists).toBe(true);
+    expect(r.targetIsSymlink).toBe(false);
+  });
+
+  test('IS_WINDOWS=1 + dir → real directory copy', () => {
+    const r = runHelper('1', 'dir');
+    expect(r.ok).toBe(true);
+    expect(r.targetExists).toBe(true);
+    expect(r.targetIsSymlink).toBe(false);
+  });
+});

From 0c3bd893e52835b4108d3390354c0b8fba7d0c30 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:02:22 -0700
Subject: [PATCH 06/12] chore: bump v1.38.0.0 + build-script subshells +
 CHANGELOG
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

VERSION 1.35.0.0 → 1.38.0.0 (MINOR). PR #1500 (lyon-v2) claimed
v1.37.0.0 ahead of this branch; v1.38.0.0 is the next free MINOR slot
per bin/gstack-next-version queue check. Workspace-aware ship rule
applies — queue-advancing past a claimed version within the same
bump level is explicitly permitted.

package.json build script: three `{ git rev-parse HEAD ...; }` brace
groups → `( git rev-parse HEAD ... )` subshells. Bun's Windows shell
parser doesn't grok bash brace groups; subshells are POSIX-universal.
Originated from @realcarsonterry PR #1460.

CHANGELOG entry covers the full wave:
- Windows install hardening (42-site _link_or_copy + cleanup compat)
- Unicode sanitization architecture (handleCommandInternal + SSE
  replacer)
- Build script POSIX-shell compat (subshells)
- Doc rename (gbrain_sync_mode → artifacts_sync_mode)
- Windows CI on paid faster runner
- 4 new wave tests (29 cases)
Frames each item as a current system property, not a fix narrative.

Credits @realcarsonterry for PRs #1460, #1461, #1462, #1463 (the seed
of the wave). Scope expansion to all 42 setup sites, every server
egress path, Windows CI migration, and codex-flagged P0/P1 fixes
(connect-chrome alias on Windows, SSE replacer, prefix-cleanup
Windows compat) authored on this branch.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CHANGELOG.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 VERSION      |  2 +-
 package.json |  4 ++--
 3 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 55cc068f9..0f4f34a18 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,62 @@
 # Changelog
 
+## [1.38.0.0] - 2026-05-14
+
+## **Windows install actually works across every host adapter. Page scrapes survive lone Unicode surrogates on every egress path.**
+## **Forty-two `ln -snf` call sites in `setup` now route through one helper that picks `cp -R` / `cp -f` on MSYS2/Git Bash. The browse server sanitizes lone surrogates at the architectural choke point so HTTP, batch, and both SSE streams inherit it. The Windows free-test CI lane moves to a paid faster runner.**
+
+Windows users who pull `git pull && ./setup` now get fresh skill files for every host adapter (Claude, Codex, Factory, OpenCode, Kiro) — not just the top-level Claude SKILL.md. The previous behavior was silent staleness: `ln -snf` on Windows-without-Developer-Mode produces a frozen file copy that doesn't refresh on subsequent runs. A new `_link_or_copy` helper in `setup` dispatches on `IS_WINDOWS` and picks the right primitive (`cp -R` for directories, `cp -f` for files, `ln -snf` otherwise). All 42 symlink sites route through it. A static-invariant test asserts zero raw `ln` calls outside the helper body so the bug can't return through future contributions.
+
+The browse server's Unicode sanitization lifts from `handleCommand` (PR #1463's original target) to `handleCommandInternal` so the batch command path (`/command/batch`) inherits it too. Both SSE producers (activity feed at `/activity/stream` and inspector stream) now stringify with a `sanitizeReplacer` function that cleans every string value during JSON.stringify — post-stringify regex is ineffective there because `JSON.stringify` has already converted `\uD800` into the escape sequence `"\\ud800"` before the regex would run. Result: every page-content payload that ships from the server has lone UTF-16 surrogate halves replaced with U+FFFD before any downstream consumer (Anthropic API, sidebar JSON.parse) sees them.
+
+The `windows-free-tests.yml` CI lane migrates from GitHub-hosted `windows-latest` to a paid faster Windows runner (Blacksmith). Spin-up drops from ~60s to ~10s and Bun installs land 3-4x faster. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
+
+Contributed by @realcarsonterry: PRs #1460, #1461, #1462, and #1463 are the seed of this wave. The scope expansion to all 42 setup sites + every server egress path + Windows CI migration is the gstack maintainer's follow-through.
+
+### The numbers that matter
+
+Source: this branch's diff against `origin/main` and the wave plan at `~/.claude/plans/system-instruction-you-are-working-peppy-volcano.md` (target ship slot v1.38.0.0 after queue advance past in-flight PR #1500).
+
+| Surface | Before | After | Δ |
+|---------|--------|-------|---|
+| `setup` symlink sites guarded for Windows | 0 of 42 | 42 of 42 | +42 |
+| Server Unicode-sanitization egress points | 0 | 4 (HTTP, batch, activity SSE, inspector SSE) | +4 |
+| Bash brace groups in `package.json` build script (Bun-Windows-hostile) | 3 | 0 | -3 |
+| Stale `gbrain_sync_mode` references in docs | 5 | 0 | -5 |
+| New regression tests | 0 | 29 (4 files) | +29 |
+| Windows CI runner spin-up | ~60s (windows-latest) | ~10s (Blacksmith) | ~6x faster |
+
+The static invariant test (D7) reads `setup` and asserts zero raw `ln` calls outside the `_link_or_copy` helper body — even a single one-line slip by a future contributor fails the build.
+
+### What this means for downstream gstack users
+
+If you run gstack on Windows: `./setup` now produces a working install across every host adapter, and the user-visible note tells you to re-run after `git pull`. If you scrape pages with non-Latin text or emoji: Bun's CDP responses can no longer break the Anthropic API with lone-surrogate JSON bodies — sanitization is single-point and inherited by every server egress path. If you contribute to gstack: a future `ln -snf` slip in `setup` will fail CI, and a future SSE endpoint that bypasses sanitization is flagged by an inline invariant comment plus this CHANGELOG entry.
+
+### Itemized changes
+
+#### Added
+
+- **`browse/test/server-sanitize-surrogates.test.ts`** — 11 unit cases (passthrough, valid pair, lone high/low mid-string, trailing/leading lone, adjacent doubles, pair-then-lone, lone-then-pair), 2 bug-repro tests (UTF-8 round-trip + JSON round-trip), 3 wiring-invariant tests (handleCommandInternalImpl rename, SSE activity, SSE inspector).
+- **`test/setup-windows-fallback.test.ts`** — static invariant (zero raw `ln` calls outside helper), helper-existence assertions, behavior matrix (4 cells: file/dir × Windows/Unix) via awk-style helper extraction + `bash -c` sourcing, Windows-note printer registration check.
+- **`test/build-script-shell-compat.test.ts`** — regex against `package.json scripts.*` rejecting bash brace groups (Bun-Windows-hostile); asserts `.version` redirects use subshells, not braces.
+- **`test/docs-config-keys.test.ts`** — deprecated-key denylist (`gbrain_sync_mode`, `gbrain_sync_mode_prompted`) scanned across `docs/**/*.md`; round-trip test for `gstack-config get artifacts_sync_mode`.
+
+#### Changed
+
+- **`browse/src/server.ts`** — `handleCommandInternal` split into `handleCommandInternalImpl` (raw) + thin sanitizing wrapper. Single egress point for both HTTP and batch consumers. Inline INVARIANT comment near the wrapper documents the architectural constraint.
+- **`browse/src/server.ts` SSE producers** — activity feed (`/activity/stream`) and inspector stream stringify with `sanitizeReplacer`, a `JSON.stringify` replacer function that cleans every string value during encoding. Post-stringify regex is a no-op because `JSON.stringify` has already converted `\uD800` to `"\\ud800"` before the regex could match. Inline INVARIANT comment in each.
+- **`setup`** — new `_link_or_copy SRC DST` helper near `IS_WINDOWS` detection (~line 33). Auto-dispatches on file-vs-directory + Windows-vs-Unix, and skips Unix-style name-only aliases (e.g. `gstack/open-gstack-browser` for the connect-chrome alias) when the source doesn't resolve on disk so Windows installs don't abort under `set -e`. All 42 prior `ln -snf` call sites converted to `_link_or_copy`. New `_print_windows_copy_note_once` helper called from `link_claude_skill_dirs` after any link work completes. `cleanup_old_claude_symlinks` and `cleanup_prefixed_claude_symlinks` extended with a Windows branch so `--prefix` / `--no-prefix` flips remove stale real-file SKILL.md copies instead of leaving them behind.
+- **`.github/workflows/windows-free-tests.yml`** — `runs-on: windows-latest` → `runs-on: blacksmith-2vcpu-windows-2022`. Test-list expanded to include the 4 new wave tests.
+- **`package.json`** — build script's three `{ git rev-parse HEAD 2>/dev/null || true; } > path/.version` brace groups replaced with `( ... )` subshells. POSIX-universal, Bun-Windows-compatible.
+- **`docs/gbrain-sync.md`, `docs/gbrain-sync-errors.md`** — 5 stale `gbrain_sync_mode` config-key references → `artifacts_sync_mode` (the rename landed in v1.27.0.0 but two docs still pointed at the old key).
+
+#### For contributors
+
+- **Architectural invariant (Unicode):** every JSON.stringify call that serializes page-content-derived strings MUST be passed `sanitizeReplacer` (for object payloads where consumers will JSON.parse) OR the resulting body MUST be wrapped in `sanitizeLoneSurrogates` (for text/plain responses). Today this is enforced by `handleCommandInternal`'s sanitizing wrapper for command results and explicit `sanitizeReplacer` arguments at the two SSE producers. New SSE/WebSocket writers must follow the same pattern; inline comments near both producers say so.
+- **Architectural invariant (setup):** every symlink in `setup` MUST go through `_link_or_copy`. Enforced by `test/setup-windows-fallback.test.ts`'s static invariant — a single raw `ln` call outside the helper body fails CI.
+- **Test coverage gap closed:** prior to this wave, the curated Windows CI lane (`windows-free-tests.yml`) didn't exercise the install-symlink path, the Unicode sanitization, the build-script shell compat, or doc-config drift. All four now run on every PR.
+- **Out of scope (P2 follow-ups):** pushing sanitization deeper to `browse/src/snapshot.ts` (covers WebSocket frames that don't transit `cr.result`); porting the 24 POSIX-bound free tests to run on Windows (tracked in `windows-free-tests.yml`'s own comments).
+
 ## [1.35.0.0] - 2026-05-13
 
 ## **Docs become a tracked surface, not an afterthought. `/document-generate` writes them from scratch, `/document-release` audits coverage in four Diataxis quadrants.**
diff --git a/VERSION b/VERSION
index c25c8ba4b..be9cbf2dc 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.35.0.0
+1.38.0.0
diff --git a/package.json b/package.json
index 6378d48bc..6cfa824f1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.35.0.0",
+  "version": "1.38.0.0",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,7 @@
     "make-pdf": "./make-pdf/dist/pdf"
   },
   "scripts": {
-    "build": "bun run vendor:xterm && bun run gen:skill-docs --host all; bun build --compile browse/src/cli.ts --outfile browse/dist/browse && bun build --compile browse/src/find-browse.ts --outfile browse/dist/find-browse && bun build --compile design/src/cli.ts --outfile design/dist/design && bun build --compile make-pdf/src/cli.ts --outfile make-pdf/dist/pdf && bun build --compile bin/gstack-global-discover.ts --outfile bin/gstack-global-discover && bash browse/scripts/build-node-server.sh && { git rev-parse HEAD 2>/dev/null || true; } > browse/dist/.version && { git rev-parse HEAD 2>/dev/null || true; } > design/dist/.version && { git rev-parse HEAD 2>/dev/null || true; } > make-pdf/dist/.version && chmod +x browse/dist/browse browse/dist/find-browse design/dist/design make-pdf/dist/pdf bin/gstack-global-discover && (rm -f .*.bun-build || true)",
+    "build": "bun run vendor:xterm && bun run gen:skill-docs --host all; bun build --compile browse/src/cli.ts --outfile browse/dist/browse && bun build --compile browse/src/find-browse.ts --outfile browse/dist/find-browse && bun build --compile design/src/cli.ts --outfile design/dist/design && bun build --compile make-pdf/src/cli.ts --outfile make-pdf/dist/pdf && bun build --compile bin/gstack-global-discover.ts --outfile bin/gstack-global-discover && bash browse/scripts/build-node-server.sh && ( git rev-parse HEAD 2>/dev/null || true ) > browse/dist/.version && ( git rev-parse HEAD 2>/dev/null || true ) > design/dist/.version && ( git rev-parse HEAD 2>/dev/null || true ) > make-pdf/dist/.version && chmod +x browse/dist/browse browse/dist/find-browse design/dist/design make-pdf/dist/pdf bin/gstack-global-discover && (rm -f .*.bun-build || true)",
     "vendor:xterm": "mkdir -p extension/lib && cp node_modules/xterm/lib/xterm.js extension/lib/xterm.js && cp node_modules/xterm/css/xterm.css extension/lib/xterm.css && cp node_modules/xterm-addon-fit/lib/xterm-addon-fit.js extension/lib/xterm-addon-fit.js",
     "dev:make-pdf": "bun run make-pdf/src/cli.ts",
     "dev:design": "bun run design/src/cli.ts",

From 6d330f515094ba0f497e49b2aa2d8f2b2a755944 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 14:05:26 -0700
Subject: [PATCH 07/12] docs: post-ship sync for v1.38.0.0

Document the two architectural invariants that landed in v1.38.0.0 in
their persistent homes (not just CHANGELOG):

- README Windows section: add the `./setup` re-run-after-git-pull
  requirement that `_print_windows_copy_note_once` shows at runtime.
- CONTRIBUTING "Things to know": add the no-raw-`ln` invariant for
  contributors editing `setup`, with the test that enforces it.
- ARCHITECTURE: new "Unicode sanitization at server egress" section
  between Shell injection prevention and Prompt injection defense,
  with egress table (HTTP/batch/SSE) and the post-stringify-regex
  rationale.
- CLAUDE.md: cross-references for both invariants, matching the
  v1.6.0.0 dual-listener pattern (each constraint says which files
  to read before editing and which test pins it).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 ARCHITECTURE.md | 15 +++++++++++++++
 CLAUDE.md       | 25 +++++++++++++++++++++++++
 CONTRIBUTING.md |  1 +
 README.md       |  2 ++
 4 files changed, 43 insertions(+)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 7f903d60a..3dba8f3ba 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -144,6 +144,21 @@ Cookies are the most sensitive data gstack handles. The design:
 
 The browser registry (Comet, Chrome, Arc, Brave, Edge) is hardcoded. Database paths are constructed from known constants, never from user input. Keychain access uses `Bun.spawn()` with explicit argument arrays, not shell string interpolation.
 
+### Unicode sanitization at server egress (v1.38.0.0)
+
+Page content harvested by CDP can contain lone UTF-16 surrogate halves (orphaned high or low surrogates from broken JavaScript string handling on the page). When those reach `JSON.stringify`, Bun emits them as `\uD800`-style escape sequences that the downstream consumer's `JSON.parse` accepts, but the Anthropic API rejects with a 400 — turning a single weird page into a session-killing error. Defense is single-point, applied at every server egress that ships page-derived strings.
+
+| Egress path | Module | Sanitization point |
+|---|---|---|
+| `POST /command` (HTTP) | `browse/src/server.ts` | `handleCommandInternal` wrapper (sanitizes the result of `handleCommandInternalImpl`) |
+| `POST /command/batch` | `browse/src/server.ts` | Same wrapper — batch consumers inherit it |
+| `GET /activity/stream` (SSE) | `browse/src/server.ts` | `sanitizeReplacer` passed to `JSON.stringify` |
+| `GET /inspector/events` (SSE) | `browse/src/server.ts` | `sanitizeReplacer` passed to `JSON.stringify` |
+
+`sanitizeReplacer` is a `JSON.stringify` replacer function that cleans every string value during encoding. Post-stringify regex doesn't work here — `JSON.stringify` has already converted `\uD800` into the literal escape sequence `"\\ud800"` before the regex could match, so the replacer must run inside the encoding pipeline. The pure-string helper `sanitizeLoneSurrogates` is used directly for `text/plain` responses.
+
+**Architectural invariant.** Every new SSE/WebSocket writer or HTTP response that ships page-content-derived strings MUST go through one of two paths: `JSON.stringify(payload, sanitizeReplacer)` for object payloads, or `sanitizeLoneSurrogates(body)` for text bodies. New surfaces that bypass both will desync the system. Inline comments at both SSE producers in `server.ts` say so; `browse/test/server-sanitize-surrogates.test.ts` pins wiring with bug-repro + invariant tests (`handleCommandInternalImpl` rename, central sanitization line, replacer existence, SSE producers stringify with replacer).
+
 ### Prompt injection defense (sidebar agent)
 
 The Chrome sidebar agent has tools (Bash, Read, Glob, Grep, WebFetch) and reads hostile web pages, so it's the part of gstack most exposed to prompt injection. Defense is layered, not single-point.
diff --git a/CLAUDE.md b/CLAUDE.md
index 11d85dc78..6cbff85f9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -269,6 +269,31 @@ to `~/.gstack/security/attempts.jsonl` via `tunnel-denial-log.ts`. Before editin
 the module boundary (no imports from `token-registry.ts` into `sse-session-cookie.ts`)
 is load-bearing for scope isolation.
 
+**Unicode sanitization at server egress** (v1.38.0.0+). Every server egress that
+ships page-content-derived strings MUST go through `JSON.stringify(payload,
+sanitizeReplacer)` for object payloads or `sanitizeLoneSurrogates(body)` for text
+bodies. Lone UTF-16 surrogate halves from CDP page content otherwise reach the
+Anthropic API as `\uD800`-style escapes and trigger a 400. Wired at four egress
+points today: `handleCommandInternal` (HTTP + batch via a sanitizing wrapper around
+`handleCommandInternalImpl`) and both SSE producers (`/activity/stream`,
+`/inspector/events`). Post-stringify regex is a no-op — `JSON.stringify` has
+already escaped the surrogate before regex could match, so the replacer must run
+inside the encoding pipeline. Before adding a new SSE/WebSocket writer or HTTP
+response in `server.ts`, read
+[ARCHITECTURE.md](ARCHITECTURE.md#unicode-sanitization-at-server-egress-v13800).
+`browse/test/server-sanitize-surrogates.test.ts` pins the wiring with invariant
+tests, so bypasses fail CI.
+
+**Setup symlink hardening** (v1.38.0.0+). Every link site in `setup` MUST route
+through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. On
+Windows without Developer Mode, plain `ln -snf` produces frozen file copies that
+don't refresh on `git pull` — silent staleness across every host adapter. The
+helper preserves `ln -snf` on Unix and switches to `cp -R` / `cp -f` on Windows.
+`test/setup-windows-fallback.test.ts` enforces a static invariant: a single raw
+`ln` call outside the helper body fails CI. Windows users get a one-line note
+from `_print_windows_copy_note_once` reminding them to re-run `./setup` after
+every `git pull`.
+
 **Sidebar security stack** (layered defense against prompt injection):
 
 | Layer | Module | Lives in |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 523887510..7f40fa4d8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -342,6 +342,7 @@ When Conductor creates a new workspace, `bin/dev-setup` runs automatically. It d
 - **Conductor workspaces are independent.** Each workspace is its own git worktree. `bin/dev-setup` runs automatically via `conductor.json`.
 - **`.env` propagates across worktrees.** Set it once in the main repo, all Conductor workspaces get it.
 - **`.claude/skills/` is gitignored.** The symlinks never get committed.
+- **Never write raw `ln -snf` in `setup`.** Every link site in `setup` MUST route through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. The helper preserves `ln -snf` on Unix and switches to `cp -R` / `cp -f` on Windows without Developer Mode, where plain `ln -snf` produces frozen file copies that don't refresh on `git pull`. `test/setup-windows-fallback.test.ts` enforces this with a static invariant — a single raw `ln` call outside the helper body fails CI.
 
 ## Testing your changes in a real project
 
diff --git a/README.md b/README.md
index 4e2b792ec..54e11ca11 100644
--- a/README.md
+++ b/README.md
@@ -459,6 +459,8 @@ Data is stored in [Supabase](https://supabase.com) (open source Firebase alterna
 
 **Windows users:** gstack works on Windows 11 via Git Bash or WSL. 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.
 
+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.
+
 **Claude says it can't see the skills?** Make sure your project's `CLAUDE.md` has a gstack section. Add this:
 
 ```

From e5a6bf46f38e0cea0608113c188eb6e32f612c31 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 16:47:50 -0700
Subject: [PATCH 08/12] ci(windows): use windows-latest-8-cores instead of
 unregistered Blacksmith label
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

actionlint failed PR #1505 because `blacksmith-2vcpu-windows-2022` isn't
in the repo's approved runner-label list (actionlint.yaml only registers
`ubicloud-standard-2`, and Ubicloud doesn't ship a Windows pool).

Switch to GitHub's paid larger Windows runner `windows-latest-8-cores`
— 4x the cores of the free `windows-latest` at the larger-runner billing
rate, no new third-party CI provider, no actionlint config changes.

CHANGELOG: replace "Blacksmith" / "blacksmith-2vcpu-windows-2022" /
"~6x faster spin-up" claims with the actual choice (8 cores vs 4, paid
larger runner).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/windows-free-tests.yml | 17 ++++++++---------
 CHANGELOG.md                             |  6 +++---
 2 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/windows-free-tests.yml b/.github/workflows/windows-free-tests.yml
index 533089dd5..d82f37d52 100644
--- a/.github/workflows/windows-free-tests.yml
+++ b/.github/workflows/windows-free-tests.yml
@@ -8,11 +8,11 @@ name: Windows Free Tests
 # targeted resolver tests that exercise the Bun.which-based claude binary
 # resolution + the GSTACK_CLAUDE_BIN override path on Windows.
 #
-# Runner: migrated v1.36.0.0 from GitHub-hosted `windows-latest` to Blacksmith's
-# paid Windows runner. Spin-up is ~10s vs ~60s and Bun installs land 3-4x faster.
-# If Blacksmith isn't configured for this org, swap to `windows-latest` (the
-# free GitHub runner, slower but always available). Namespace, Ubicloud-Windows,
-# and other paid pools work too — just match your org's billing.
+# Runner: migrated v1.38.0.0 from GitHub-hosted `windows-latest` to the paid
+# GitHub-hosted `windows-latest-8-cores` runner — 4x more cores at GitHub's
+# larger-runner billing rate. Ubicloud doesn't ship Windows runners (only
+# Linux), so we stay GitHub-hosted. Swap to `windows-latest` to revert to
+# the free runner if billing/quota becomes an issue.
 #
 # What this DOES NOT do (still out of scope, tracked as follow-up):
 #   - Run the full free suite on Windows. The 24 tests that hardcode /bin/sh,
@@ -33,10 +33,9 @@ concurrency:
 
 jobs:
   windows-free-tests:
-    # Paid faster Windows runner. Verify the label matches what's enabled for
-    # this repo's Blacksmith installation. Common alternatives:
-    #   blacksmith-4vcpu-windows-2022, namespace-profile-windows, windows-latest
-    runs-on: blacksmith-2vcpu-windows-2022
+    # Paid GitHub-hosted larger Windows runner (8 cores vs the free 4-core
+    # windows-latest). To revert: swap to `windows-latest`.
+    runs-on: windows-latest-8-cores
     timeout-minutes: 15
 
     steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f4f34a18..fbebfa22d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ Windows users who pull `git pull && ./setup` now get fresh skill files for every
 
 The browse server's Unicode sanitization lifts from `handleCommand` (PR #1463's original target) to `handleCommandInternal` so the batch command path (`/command/batch`) inherits it too. Both SSE producers (activity feed at `/activity/stream` and inspector stream) now stringify with a `sanitizeReplacer` function that cleans every string value during JSON.stringify — post-stringify regex is ineffective there because `JSON.stringify` has already converted `\uD800` into the escape sequence `"\\ud800"` before the regex would run. Result: every page-content payload that ships from the server has lone UTF-16 surrogate halves replaced with U+FFFD before any downstream consumer (Anthropic API, sidebar JSON.parse) sees them.
 
-The `windows-free-tests.yml` CI lane migrates from GitHub-hosted `windows-latest` to a paid faster Windows runner (Blacksmith). Spin-up drops from ~60s to ~10s and Bun installs land 3-4x faster. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
+The `windows-free-tests.yml` CI lane migrates from GitHub-hosted `windows-latest` to GitHub's paid larger `windows-latest-8-cores` runner — 4x the cores at the larger-runner billing rate. Ubicloud doesn't ship a Windows pool, so we stay GitHub-hosted rather than introducing a new third-party CI provider just for one Windows job. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
 
 Contributed by @realcarsonterry: PRs #1460, #1461, #1462, and #1463 are the seed of this wave. The scope expansion to all 42 setup sites + every server egress path + Windows CI migration is the gstack maintainer's follow-through.
 
@@ -24,7 +24,7 @@ Source: this branch's diff against `origin/main` and the wave plan at `~/.claude
 | Bash brace groups in `package.json` build script (Bun-Windows-hostile) | 3 | 0 | -3 |
 | Stale `gbrain_sync_mode` references in docs | 5 | 0 | -5 |
 | New regression tests | 0 | 29 (4 files) | +29 |
-| Windows CI runner spin-up | ~60s (windows-latest) | ~10s (Blacksmith) | ~6x faster |
+| Windows CI runner cores | 4 (windows-latest) | 8 (windows-latest-8-cores) | 2x cores at larger-runner billing rate |
 
 The static invariant test (D7) reads `setup` and asserts zero raw `ln` calls outside the `_link_or_copy` helper body — even a single one-line slip by a future contributor fails the build.
 
@@ -46,7 +46,7 @@ If you run gstack on Windows: `./setup` now produces a working install across ev
 - **`browse/src/server.ts`** — `handleCommandInternal` split into `handleCommandInternalImpl` (raw) + thin sanitizing wrapper. Single egress point for both HTTP and batch consumers. Inline INVARIANT comment near the wrapper documents the architectural constraint.
 - **`browse/src/server.ts` SSE producers** — activity feed (`/activity/stream`) and inspector stream stringify with `sanitizeReplacer`, a `JSON.stringify` replacer function that cleans every string value during encoding. Post-stringify regex is a no-op because `JSON.stringify` has already converted `\uD800` to `"\\ud800"` before the regex could match. Inline INVARIANT comment in each.
 - **`setup`** — new `_link_or_copy SRC DST` helper near `IS_WINDOWS` detection (~line 33). Auto-dispatches on file-vs-directory + Windows-vs-Unix, and skips Unix-style name-only aliases (e.g. `gstack/open-gstack-browser` for the connect-chrome alias) when the source doesn't resolve on disk so Windows installs don't abort under `set -e`. All 42 prior `ln -snf` call sites converted to `_link_or_copy`. New `_print_windows_copy_note_once` helper called from `link_claude_skill_dirs` after any link work completes. `cleanup_old_claude_symlinks` and `cleanup_prefixed_claude_symlinks` extended with a Windows branch so `--prefix` / `--no-prefix` flips remove stale real-file SKILL.md copies instead of leaving them behind.
-- **`.github/workflows/windows-free-tests.yml`** — `runs-on: windows-latest` → `runs-on: blacksmith-2vcpu-windows-2022`. Test-list expanded to include the 4 new wave tests.
+- **`.github/workflows/windows-free-tests.yml`** — `runs-on: windows-latest` → `runs-on: windows-latest-8-cores` (paid GitHub-hosted larger runner). Test-list expanded to include the 4 new wave tests.
 - **`package.json`** — build script's three `{ git rev-parse HEAD 2>/dev/null || true; } > path/.version` brace groups replaced with `( ... )` subshells. POSIX-universal, Bun-Windows-compatible.
 - **`docs/gbrain-sync.md`, `docs/gbrain-sync-errors.md`** — 5 stale `gbrain_sync_mode` config-key references → `artifacts_sync_mode` (the rename landed in v1.27.0.0 but two docs still pointed at the old key).
 

From bd15dfc9853ab82061788f2bd52f7893c2c3ca7f Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 20:05:21 -0700
Subject: [PATCH 09/12] ci(windows): switch from windows-latest-8-cores to
 ubicloud-standard-2-windows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`windows-latest-8-cores` sat queued indefinitely because the GitHub
larger-runner billing isn't enabled at the org level — the
"Queued — Waiting to run this check" status surfaced on PR #1505 with
no progress for the whole CI run.

Switch to Ubicloud Windows runners (`ubicloud-standard-2-windows`) so
Windows CI uses the same provider as the existing Linux evals
(`ubicloud-standard-2`). Billing stays under one account instead of
two.

Register the new label in actionlint.yaml alongside the existing
ubicloud-standard-2 entry so actionlint doesn't reject it as unknown.

CHANGELOG entry updated: runner row reflects the actual provider chosen,
"Itemized changes" mentions the actionlint.yaml registration, and the
narrative paragraph documents why `windows-latest-8-cores` failed first.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/workflows/windows-free-tests.yml | 17 +++++++++--------
 CHANGELOG.md                             |  6 +++---
 actionlint.yaml                          |  1 +
 3 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/windows-free-tests.yml b/.github/workflows/windows-free-tests.yml
index d82f37d52..56fcc577d 100644
--- a/.github/workflows/windows-free-tests.yml
+++ b/.github/workflows/windows-free-tests.yml
@@ -8,11 +8,12 @@ name: Windows Free Tests
 # targeted resolver tests that exercise the Bun.which-based claude binary
 # resolution + the GSTACK_CLAUDE_BIN override path on Windows.
 #
-# Runner: migrated v1.38.0.0 from GitHub-hosted `windows-latest` to the paid
-# GitHub-hosted `windows-latest-8-cores` runner — 4x more cores at GitHub's
-# larger-runner billing rate. Ubicloud doesn't ship Windows runners (only
-# Linux), so we stay GitHub-hosted. Swap to `windows-latest` to revert to
-# the free runner if billing/quota becomes an issue.
+# Runner: Ubicloud Windows runner (`ubicloud-standard-2-windows`). Matches
+# the Ubicloud Linux runner the evals workflow already uses, so billing
+# stays consolidated under one provider. Swap to `windows-latest` to revert
+# to GitHub's free runner if Ubicloud has Windows capacity issues. Note
+# `windows-latest-8-cores` (GitHub paid larger runner) sat queued because
+# org-level larger-runner billing wasn't enabled.
 #
 # What this DOES NOT do (still out of scope, tracked as follow-up):
 #   - Run the full free suite on Windows. The 24 tests that hardcode /bin/sh,
@@ -33,9 +34,9 @@ concurrency:
 
 jobs:
   windows-free-tests:
-    # Paid GitHub-hosted larger Windows runner (8 cores vs the free 4-core
-    # windows-latest). To revert: swap to `windows-latest`.
-    runs-on: windows-latest-8-cores
+    # Ubicloud Windows runner (same provider as the Linux evals workflow).
+    # To revert: swap to `windows-latest` (GitHub's free 4-core Windows runner).
+    runs-on: ubicloud-standard-2-windows
     timeout-minutes: 15
 
     steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b63bc52fc..24a347886 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ Windows users who pull `git pull && ./setup` now get fresh skill files for every
 
 The browse server's Unicode sanitization lifts from `handleCommand` (PR #1463's original target) to `handleCommandInternal` so the batch command path (`/command/batch`) inherits it too. Both SSE producers (activity feed at `/activity/stream` and inspector stream) now stringify with a `sanitizeReplacer` function that cleans every string value during JSON.stringify — post-stringify regex is ineffective there because `JSON.stringify` has already converted `\uD800` into the escape sequence `"\\ud800"` before the regex would run. Result: every page-content payload that ships from the server has lone UTF-16 surrogate halves replaced with U+FFFD before any downstream consumer (Anthropic API, sidebar JSON.parse) sees them.
 
-The `windows-free-tests.yml` CI lane migrates from GitHub-hosted `windows-latest` to GitHub's paid larger `windows-latest-8-cores` runner — 4x the cores at the larger-runner billing rate. Ubicloud doesn't ship a Windows pool, so we stay GitHub-hosted rather than introducing a new third-party CI provider just for one Windows job. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
+The `windows-free-tests.yml` CI lane migrates from GitHub-hosted `windows-latest` to `ubicloud-standard-2-windows` — same provider as the existing `ubicloud-standard-2` Linux evals runner, so billing stays consolidated. Earlier attempts used GitHub's paid `windows-latest-8-cores` larger runner but that queued indefinitely waiting for org-level larger-runner billing enablement. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
 
 Contributed by @realcarsonterry: PRs #1460, #1461, #1462, and #1463 are the seed of this wave. The scope expansion to all 42 setup sites + every server egress path + Windows CI migration is the gstack maintainer's follow-through.
 
@@ -24,7 +24,7 @@ Source: this branch's diff against `origin/main` and the wave plan at `~/.claude
 | Bash brace groups in `package.json` build script (Bun-Windows-hostile) | 3 | 0 | -3 |
 | Stale `gbrain_sync_mode` references in docs | 5 | 0 | -5 |
 | New regression tests | 0 | 29 (4 files) | +29 |
-| Windows CI runner cores | 4 (windows-latest) | 8 (windows-latest-8-cores) | 2x cores at larger-runner billing rate |
+| Windows CI runner | windows-latest (GitHub free) | ubicloud-standard-2-windows | consolidates Windows + Linux CI under one Ubicloud account |
 
 The static invariant test (D7) reads `setup` and asserts zero raw `ln` calls outside the `_link_or_copy` helper body — even a single one-line slip by a future contributor fails the build.
 
@@ -46,7 +46,7 @@ If you run gstack on Windows: `./setup` now produces a working install across ev
 - **`browse/src/server.ts`** — `handleCommandInternal` split into `handleCommandInternalImpl` (raw) + thin sanitizing wrapper. Single egress point for both HTTP and batch consumers. Inline INVARIANT comment near the wrapper documents the architectural constraint.
 - **`browse/src/server.ts` SSE producers** — activity feed (`/activity/stream`) and inspector stream stringify with `sanitizeReplacer`, a `JSON.stringify` replacer function that cleans every string value during encoding. Post-stringify regex is a no-op because `JSON.stringify` has already converted `\uD800` to `"\\ud800"` before the regex could match. Inline INVARIANT comment in each.
 - **`setup`** — new `_link_or_copy SRC DST` helper near `IS_WINDOWS` detection (~line 33). Auto-dispatches on file-vs-directory + Windows-vs-Unix, and skips Unix-style name-only aliases (e.g. `gstack/open-gstack-browser` for the connect-chrome alias) when the source doesn't resolve on disk so Windows installs don't abort under `set -e`. All 42 prior `ln -snf` call sites converted to `_link_or_copy`. New `_print_windows_copy_note_once` helper called from `link_claude_skill_dirs` after any link work completes. `cleanup_old_claude_symlinks` and `cleanup_prefixed_claude_symlinks` extended with a Windows branch so `--prefix` / `--no-prefix` flips remove stale real-file SKILL.md copies instead of leaving them behind.
-- **`.github/workflows/windows-free-tests.yml`** — `runs-on: windows-latest` → `runs-on: windows-latest-8-cores` (paid GitHub-hosted larger runner). Test-list expanded to include the 4 new wave tests.
+- **`.github/workflows/windows-free-tests.yml`** — `runs-on: windows-latest` → `runs-on: ubicloud-standard-2-windows` (Ubicloud Windows runner, same provider as the Linux evals). `actionlint.yaml` registers the new label alongside `ubicloud-standard-2`. Test-list expanded to include the 4 new wave tests.
 - **`package.json`** — build script's three `{ git rev-parse HEAD 2>/dev/null || true; } > path/.version` brace groups replaced with `( ... )` subshells. POSIX-universal, Bun-Windows-compatible.
 - **`docs/gbrain-sync.md`, `docs/gbrain-sync-errors.md`** — 5 stale `gbrain_sync_mode` config-key references → `artifacts_sync_mode` (the rename landed in v1.27.0.0 but two docs still pointed at the old key).
 
diff --git a/actionlint.yaml b/actionlint.yaml
index 7c54d0c6a..c26c659f4 100644
--- a/actionlint.yaml
+++ b/actionlint.yaml
@@ -1,3 +1,4 @@
 self-hosted-runner:
   labels:
     - ubicloud-standard-2
+    - ubicloud-standard-2-windows

From 818bb02f281e8e52e4def0e59e1c0d823621891f Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 20:10:50 -0700
Subject: [PATCH 10/12] ci: migrate all workflows to Ubicloud (Linux + Windows,
 8-core)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switch every `runs-on` in this repo to Ubicloud so CI has a single billing
surface, consistent capacity, and 4x more cores on the workloads that were
previously stuck on free `ubuntu-latest` (2 cores). Windows uses Ubicloud's
Windows pool too — `ubicloud-standard-8-windows` — so the queued-forever
problem with GitHub's `windows-latest-8-cores` paid larger runner (org-level
larger-runner billing not enabled) goes away.

Workflows touched (9):
- evals.yml, evals-periodic.yml, ci-image.yml — bump default + matrix from
  `ubicloud-standard-2` to `ubicloud-standard-8`. The one matrix entry that
  was already on -8 stays.
- windows-free-tests.yml — `ubicloud-standard-2-windows` → `ubicloud-standard-8-windows`.
- make-pdf-gate.yml — matrix `ubuntu-latest` → `ubicloud-standard-8`. macOS
  entry preserved; the poppler-install `if: matrix.os` conditional swaps to
  match the new label.
- actionlint.yml, pr-title-sync.yml, skill-docs.yml, version-gate.yml —
  `ubuntu-latest` → `ubicloud-standard-8`.

.github/actionlint.yaml registers all four Ubicloud labels in one place:
- ubicloud-standard-2
- ubicloud-standard-8
- ubicloud-standard-2-windows  (the v1.38.0.0 windows-free-tests target)
- ubicloud-standard-8-windows  (this PR's windows-free-tests target)

Removed the duplicate `actionlint.yaml` at the repo root that I accidentally
created in the prior commit — actionlint only reads `.github/actionlint.yaml`,
so the root file was dead weight.

CHANGELOG entry updated: a single "all Ubicloud" sentence in the narrative
plus a metrics-row covering the runner pool change, and the itemized line
expanded to enumerate the 9 affected workflows. The previously-orphaned
"Itemized changes" line about just `windows-free-tests.yml` is replaced.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/actionlint.yaml                  |  2 ++
 .github/workflows/actionlint.yml         |  2 +-
 .github/workflows/ci-image.yml           |  2 +-
 .github/workflows/evals-periodic.yml     |  4 ++--
 .github/workflows/evals.yml              |  8 ++++----
 .github/workflows/make-pdf-gate.yml      |  4 ++--
 .github/workflows/pr-title-sync.yml      |  2 +-
 .github/workflows/skill-docs.yml         |  2 +-
 .github/workflows/version-gate.yml       |  2 +-
 .github/workflows/windows-free-tests.yml | 10 +++++-----
 CHANGELOG.md                             |  7 ++++---
 actionlint.yaml                          |  4 ----
 12 files changed, 24 insertions(+), 25 deletions(-)
 delete mode 100644 actionlint.yaml

diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml
index cdd601c83..16ffbae6b 100644
--- a/.github/actionlint.yaml
+++ b/.github/actionlint.yaml
@@ -2,3 +2,5 @@ self-hosted-runner:
   labels:
     - ubicloud-standard-2
     - ubicloud-standard-8
+    - ubicloud-standard-2-windows
+    - ubicloud-standard-8-windows
diff --git a/.github/workflows/actionlint.yml b/.github/workflows/actionlint.yml
index 32ae44826..1fb654aa8 100644
--- a/.github/workflows/actionlint.yml
+++ b/.github/workflows/actionlint.yml
@@ -2,7 +2,7 @@ name: Workflow Lint
 on: [push, pull_request]
 jobs:
   actionlint:
-    runs-on: ubuntu-latest
+    runs-on: ubicloud-standard-8
     steps:
       - uses: actions/checkout@v4
       - uses: rhysd/actionlint@v1.7.11
diff --git a/.github/workflows/ci-image.yml b/.github/workflows/ci-image.yml
index 1ca283ad7..e36092d4c 100644
--- a/.github/workflows/ci-image.yml
+++ b/.github/workflows/ci-image.yml
@@ -15,7 +15,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubicloud-standard-2
+    runs-on: ubicloud-standard-8
     permissions:
       contents: read
       packages: write
diff --git a/.github/workflows/evals-periodic.yml b/.github/workflows/evals-periodic.yml
index c0ca4f3aa..25fd76d01 100644
--- a/.github/workflows/evals-periodic.yml
+++ b/.github/workflows/evals-periodic.yml
@@ -15,7 +15,7 @@ env:
 
 jobs:
   build-image:
-    runs-on: ubicloud-standard-2
+    runs-on: ubicloud-standard-8
     permissions:
       contents: read
       packages: write
@@ -56,7 +56,7 @@ jobs:
             ${{ env.IMAGE }}:latest
 
   evals:
-    runs-on: ubicloud-standard-2
+    runs-on: ubicloud-standard-8
     needs: build-image
     container:
       image: ${{ needs.build-image.outputs.image-tag }}
diff --git a/.github/workflows/evals.yml b/.github/workflows/evals.yml
index ee658aee6..c9aa6a293 100644
--- a/.github/workflows/evals.yml
+++ b/.github/workflows/evals.yml
@@ -15,7 +15,7 @@ env:
 jobs:
   # Build Docker image with pre-baked toolchain (cached — only rebuilds on Dockerfile/lockfile change)
   build-image:
-    runs-on: ubicloud-standard-2
+    runs-on: ubicloud-standard-8
     permissions:
       contents: read
       packages: write
@@ -56,7 +56,7 @@ jobs:
             ${{ env.IMAGE }}:latest
 
   evals:
-    runs-on: ${{ matrix.suite.runner || 'ubicloud-standard-2' }}
+    runs-on: ${{ matrix.suite.runner || 'ubicloud-standard-8' }}
     needs: build-image
     container:
       image: ${{ needs.build-image.outputs.image-tag }}
@@ -155,7 +155,7 @@ jobs:
           retention-days: 90
 
   report:
-    runs-on: ubicloud-standard-2
+    runs-on: ubicloud-standard-8
     needs: evals
     if: always() && github.event_name == 'pull_request'
     timeout-minutes: 5
@@ -219,7 +219,7 @@ jobs:
           $(echo -e "$SUITE_LINES")
 
           ---
-          *12x ubicloud-standard-2 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite*"
+          *12x ubicloud-standard-8 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite*"
 
           if [ "$FAILED" -gt 0 ]; then
             FAILURES=""
diff --git a/.github/workflows/make-pdf-gate.yml b/.github/workflows/make-pdf-gate.yml
index eab5c4fbe..60d9a1405 100644
--- a/.github/workflows/make-pdf-gate.yml
+++ b/.github/workflows/make-pdf-gate.yml
@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubicloud-standard-8, macos-latest]
         # Windows is tolerant-mode — Xpdf / Poppler-Windows extraction
         # differs enough from the Linux/macOS baseline that the strict
         # exact-diff gate is unreliable. Enable once the normalized
@@ -48,7 +48,7 @@ jobs:
         run: brew install poppler
 
       - name: Install poppler-utils (Ubuntu)
-        if: matrix.os == 'ubuntu-latest'
+        if: matrix.os == 'ubicloud-standard-8'
         run: sudo apt-get update && sudo apt-get install -y poppler-utils
 
       - name: Install Playwright Chromium
diff --git a/.github/workflows/pr-title-sync.yml b/.github/workflows/pr-title-sync.yml
index 7cd274cd4..6f5b3d3e5 100644
--- a/.github/workflows/pr-title-sync.yml
+++ b/.github/workflows/pr-title-sync.yml
@@ -13,7 +13,7 @@ concurrency:
 jobs:
   sync:
     name: Sync PR title to VERSION
-    runs-on: ubuntu-latest
+    runs-on: ubicloud-standard-8
     permissions:
       contents: read
       pull-requests: write
diff --git a/.github/workflows/skill-docs.yml b/.github/workflows/skill-docs.yml
index 34ea7f8e9..700a8222a 100644
--- a/.github/workflows/skill-docs.yml
+++ b/.github/workflows/skill-docs.yml
@@ -2,7 +2,7 @@ name: Skill Docs Freshness
 on: [push, pull_request]
 jobs:
   check-freshness:
-    runs-on: ubuntu-latest
+    runs-on: ubicloud-standard-8
     steps:
       - uses: actions/checkout@v4
       - uses: oven-sh/setup-bun@v2
diff --git a/.github/workflows/version-gate.yml b/.github/workflows/version-gate.yml
index 262baf6ea..2c60d9d76 100644
--- a/.github/workflows/version-gate.yml
+++ b/.github/workflows/version-gate.yml
@@ -14,7 +14,7 @@ concurrency:
 jobs:
   check:
     name: Check VERSION is not stale vs queue
-    runs-on: ubuntu-latest
+    runs-on: ubicloud-standard-8
     permissions:
       contents: read
       pull-requests: read
diff --git a/.github/workflows/windows-free-tests.yml b/.github/workflows/windows-free-tests.yml
index 56fcc577d..695fc649f 100644
--- a/.github/workflows/windows-free-tests.yml
+++ b/.github/workflows/windows-free-tests.yml
@@ -8,10 +8,10 @@ name: Windows Free Tests
 # targeted resolver tests that exercise the Bun.which-based claude binary
 # resolution + the GSTACK_CLAUDE_BIN override path on Windows.
 #
-# Runner: Ubicloud Windows runner (`ubicloud-standard-2-windows`). Matches
-# the Ubicloud Linux runner the evals workflow already uses, so billing
-# stays consolidated under one provider. Swap to `windows-latest` to revert
-# to GitHub's free runner if Ubicloud has Windows capacity issues. Note
+# Runner: Ubicloud Windows runner (`ubicloud-standard-8-windows`). All CI
+# in this repo runs on Ubicloud (Linux + Windows) for billing consolidation
+# and consistent capacity. Swap to `windows-latest` to revert to GitHub's
+# free runner if Ubicloud has Windows capacity issues. Note
 # `windows-latest-8-cores` (GitHub paid larger runner) sat queued because
 # org-level larger-runner billing wasn't enabled.
 #
@@ -36,7 +36,7 @@ jobs:
   windows-free-tests:
     # Ubicloud Windows runner (same provider as the Linux evals workflow).
     # To revert: swap to `windows-latest` (GitHub's free 4-core Windows runner).
-    runs-on: ubicloud-standard-2-windows
+    runs-on: ubicloud-standard-8-windows
     timeout-minutes: 15
 
     steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24a347886..4c40d5e46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ Windows users who pull `git pull && ./setup` now get fresh skill files for every
 
 The browse server's Unicode sanitization lifts from `handleCommand` (PR #1463's original target) to `handleCommandInternal` so the batch command path (`/command/batch`) inherits it too. Both SSE producers (activity feed at `/activity/stream` and inspector stream) now stringify with a `sanitizeReplacer` function that cleans every string value during JSON.stringify — post-stringify regex is ineffective there because `JSON.stringify` has already converted `\uD800` into the escape sequence `"\\ud800"` before the regex would run. Result: every page-content payload that ships from the server has lone UTF-16 surrogate halves replaced with U+FFFD before any downstream consumer (Anthropic API, sidebar JSON.parse) sees them.
 
-The `windows-free-tests.yml` CI lane migrates from GitHub-hosted `windows-latest` to `ubicloud-standard-2-windows` — same provider as the existing `ubicloud-standard-2` Linux evals runner, so billing stays consolidated. Earlier attempts used GitHub's paid `windows-latest-8-cores` larger runner but that queued indefinitely waiting for org-level larger-runner billing enablement. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
+All CI jobs migrate to Ubicloud runners (Linux + Windows on `ubicloud-standard-8` / `ubicloud-standard-8-windows`) for consolidated billing and consistent capacity. Eight workflows touch the runner pool: `evals.yml`, `evals-periodic.yml`, `ci-image.yml`, `windows-free-tests.yml`, `make-pdf-gate.yml`, `actionlint.yml`, `pr-title-sync.yml`, `skill-docs.yml`, `version-gate.yml`. Earlier ship attempts used GitHub's paid `windows-latest-8-cores` larger runner but it queued indefinitely waiting for org-level larger-runner billing enablement. `.github/actionlint.yaml` registers all four Ubicloud labels (`ubicloud-standard-2/8` and `ubicloud-standard-2/8-windows`) so future workflow edits don't have to fight the linter. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
 
 Contributed by @realcarsonterry: PRs #1460, #1461, #1462, and #1463 are the seed of this wave. The scope expansion to all 42 setup sites + every server egress path + Windows CI migration is the gstack maintainer's follow-through.
 
@@ -24,7 +24,7 @@ Source: this branch's diff against `origin/main` and the wave plan at `~/.claude
 | Bash brace groups in `package.json` build script (Bun-Windows-hostile) | 3 | 0 | -3 |
 | Stale `gbrain_sync_mode` references in docs | 5 | 0 | -5 |
 | New regression tests | 0 | 29 (4 files) | +29 |
-| Windows CI runner | windows-latest (GitHub free) | ubicloud-standard-2-windows | consolidates Windows + Linux CI under one Ubicloud account |
+| CI runner pool | mix of `ubuntu-latest` + `ubicloud-standard-2` + `windows-latest` | `ubicloud-standard-8` everywhere (Windows = `ubicloud-standard-8-windows`) | single billing surface, 4x more cores on Linux jobs, paid Windows that actually runs |
 
 The static invariant test (D7) reads `setup` and asserts zero raw `ln` calls outside the `_link_or_copy` helper body — even a single one-line slip by a future contributor fails the build.
 
@@ -46,7 +46,8 @@ If you run gstack on Windows: `./setup` now produces a working install across ev
 - **`browse/src/server.ts`** — `handleCommandInternal` split into `handleCommandInternalImpl` (raw) + thin sanitizing wrapper. Single egress point for both HTTP and batch consumers. Inline INVARIANT comment near the wrapper documents the architectural constraint.
 - **`browse/src/server.ts` SSE producers** — activity feed (`/activity/stream`) and inspector stream stringify with `sanitizeReplacer`, a `JSON.stringify` replacer function that cleans every string value during encoding. Post-stringify regex is a no-op because `JSON.stringify` has already converted `\uD800` to `"\\ud800"` before the regex could match. Inline INVARIANT comment in each.
 - **`setup`** — new `_link_or_copy SRC DST` helper near `IS_WINDOWS` detection (~line 33). Auto-dispatches on file-vs-directory + Windows-vs-Unix, and skips Unix-style name-only aliases (e.g. `gstack/open-gstack-browser` for the connect-chrome alias) when the source doesn't resolve on disk so Windows installs don't abort under `set -e`. All 42 prior `ln -snf` call sites converted to `_link_or_copy`. New `_print_windows_copy_note_once` helper called from `link_claude_skill_dirs` after any link work completes. `cleanup_old_claude_symlinks` and `cleanup_prefixed_claude_symlinks` extended with a Windows branch so `--prefix` / `--no-prefix` flips remove stale real-file SKILL.md copies instead of leaving them behind.
-- **`.github/workflows/windows-free-tests.yml`** — `runs-on: windows-latest` → `runs-on: ubicloud-standard-2-windows` (Ubicloud Windows runner, same provider as the Linux evals). `actionlint.yaml` registers the new label alongside `ubicloud-standard-2`. Test-list expanded to include the 4 new wave tests.
+- **`.github/workflows/*.yml` (all 9 workflows)** — every `runs-on` switched to Ubicloud: `ubicloud-standard-8` for Linux (`evals.yml`, `evals-periodic.yml`, `ci-image.yml`, `actionlint.yml`, `pr-title-sync.yml`, `skill-docs.yml`, `version-gate.yml`, `make-pdf-gate.yml`'s Linux matrix entry) and `ubicloud-standard-8-windows` for Windows (`windows-free-tests.yml`). The `evals.yml` matrix default and the prose footer both updated to reference `ubicloud-standard-8`. Test-list in `windows-free-tests.yml` expanded to include the 4 new wave tests.
+- **`.github/actionlint.yaml`** — registers all four Ubicloud labels (`ubicloud-standard-2/8` and `ubicloud-standard-2/8-windows`) so workflow lint stops rejecting any of them. The duplicate dead-weight `actionlint.yaml` at the repo root is removed (actionlint only reads `.github/actionlint.yaml`).
 - **`package.json`** — build script's three `{ git rev-parse HEAD 2>/dev/null || true; } > path/.version` brace groups replaced with `( ... )` subshells. POSIX-universal, Bun-Windows-compatible.
 - **`docs/gbrain-sync.md`, `docs/gbrain-sync-errors.md`** — 5 stale `gbrain_sync_mode` config-key references → `artifacts_sync_mode` (the rename landed in v1.27.0.0 but two docs still pointed at the old key).
 
diff --git a/actionlint.yaml b/actionlint.yaml
deleted file mode 100644
index c26c659f4..000000000
--- a/actionlint.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-self-hosted-runner:
-  labels:
-    - ubicloud-standard-2
-    - ubicloud-standard-2-windows

From ae6b25f825ff0bd3e6603d9b6fa6aff87013d444 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 21:02:35 -0700
Subject: [PATCH 11/12] ci(windows): revert to free `windows-latest`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ubicloud doesn't ship Windows runners — confirmed via their docs. The
`ubicloud-standard-*-windows` labels I added do not exist and were causing
`windows-free-tests` to sit "Queued — Waiting to run this check" forever
(GitHub Actions can't tell a typoed label from a self-hosted runner that's
about to register; it just waits).

Three prior Windows-runner attempts all failed for different reasons:
- `blacksmith-2vcpu-windows-2022` — Blacksmith app not installed on the org
- `windows-latest-8-cores` — GitHub paid larger-runner billing not enabled
- `ubicloud-standard-2/8-windows` — Ubicloud doesn't offer Windows at all

The free `windows-latest` runner (4 cores, ~60s spin-up, $0) is the one
path that actually runs. The wave-coverage Windows tests are <30s of real
work; total job time stays under 2 minutes.

Cleaned up `.github/actionlint.yaml` to drop the bogus
`ubicloud-standard-*-windows` entries — kept only the two real Linux labels.

CHANGELOG: split the runner-pool row into Linux (migrated to Ubicloud-8)
vs Windows (stays on free windows-latest), with the why on each. Itemized
line for windows-free-tests rewritten to reflect the actual outcome.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .github/actionlint.yaml                  |  2 --
 .github/workflows/windows-free-tests.yml | 13 ++++++-------
 CHANGELOG.md                             | 10 ++++++----
 3 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml
index 16ffbae6b..cdd601c83 100644
--- a/.github/actionlint.yaml
+++ b/.github/actionlint.yaml
@@ -2,5 +2,3 @@ self-hosted-runner:
   labels:
     - ubicloud-standard-2
     - ubicloud-standard-8
-    - ubicloud-standard-2-windows
-    - ubicloud-standard-8-windows
diff --git a/.github/workflows/windows-free-tests.yml b/.github/workflows/windows-free-tests.yml
index 695fc649f..67fefcbe9 100644
--- a/.github/workflows/windows-free-tests.yml
+++ b/.github/workflows/windows-free-tests.yml
@@ -8,12 +8,11 @@ name: Windows Free Tests
 # targeted resolver tests that exercise the Bun.which-based claude binary
 # resolution + the GSTACK_CLAUDE_BIN override path on Windows.
 #
-# Runner: Ubicloud Windows runner (`ubicloud-standard-8-windows`). All CI
-# in this repo runs on Ubicloud (Linux + Windows) for billing consolidation
-# and consistent capacity. Swap to `windows-latest` to revert to GitHub's
-# free runner if Ubicloud has Windows capacity issues. Note
-# `windows-latest-8-cores` (GitHub paid larger runner) sat queued because
-# org-level larger-runner billing wasn't enabled.
+# Runner: GitHub-hosted free `windows-latest`. The whole rest of CI runs on
+# Ubicloud (Linux), but Ubicloud doesn't ship Windows runners and we don't
+# want to flip on GitHub's org-level larger-runner billing for just this one
+# job. 4 cores, ~60s spin-up, $0. The wave-coverage tests this runs are
+# small enough that total job time stays under 2 minutes.
 #
 # What this DOES NOT do (still out of scope, tracked as follow-up):
 #   - Run the full free suite on Windows. The 24 tests that hardcode /bin/sh,
@@ -36,7 +35,7 @@ jobs:
   windows-free-tests:
     # Ubicloud Windows runner (same provider as the Linux evals workflow).
     # To revert: swap to `windows-latest` (GitHub's free 4-core Windows runner).
-    runs-on: ubicloud-standard-8-windows
+    runs-on: windows-latest
     timeout-minutes: 15
 
     steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c40d5e46..6c792f1c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ Windows users who pull `git pull && ./setup` now get fresh skill files for every
 
 The browse server's Unicode sanitization lifts from `handleCommand` (PR #1463's original target) to `handleCommandInternal` so the batch command path (`/command/batch`) inherits it too. Both SSE producers (activity feed at `/activity/stream` and inspector stream) now stringify with a `sanitizeReplacer` function that cleans every string value during JSON.stringify — post-stringify regex is ineffective there because `JSON.stringify` has already converted `\uD800` into the escape sequence `"\\ud800"` before the regex would run. Result: every page-content payload that ships from the server has lone UTF-16 surrogate halves replaced with U+FFFD before any downstream consumer (Anthropic API, sidebar JSON.parse) sees them.
 
-All CI jobs migrate to Ubicloud runners (Linux + Windows on `ubicloud-standard-8` / `ubicloud-standard-8-windows`) for consolidated billing and consistent capacity. Eight workflows touch the runner pool: `evals.yml`, `evals-periodic.yml`, `ci-image.yml`, `windows-free-tests.yml`, `make-pdf-gate.yml`, `actionlint.yml`, `pr-title-sync.yml`, `skill-docs.yml`, `version-gate.yml`. Earlier ship attempts used GitHub's paid `windows-latest-8-cores` larger runner but it queued indefinitely waiting for org-level larger-runner billing enablement. `.github/actionlint.yaml` registers all four Ubicloud labels (`ubicloud-standard-2/8` and `ubicloud-standard-2/8-windows`) so future workflow edits don't have to fight the linter. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
+All Linux CI jobs migrate to `ubicloud-standard-8` for consolidated billing and 4x more cores than free `ubuntu-latest`. Eight workflows touch the Linux pool: `evals.yml`, `evals-periodic.yml`, `ci-image.yml`, `make-pdf-gate.yml`, `actionlint.yml`, `pr-title-sync.yml`, `skill-docs.yml`, `version-gate.yml`. The Windows-only job (`windows-free-tests.yml`) stays on GitHub's free `windows-latest` — Ubicloud doesn't ship a Windows pool, GitHub's paid `windows-latest-8-cores` requires org-level larger-runner billing enablement, and the wave-coverage tests this job runs are small enough that the slower 4-core free runner keeps total job time under 2 minutes. Four new wave tests get registered: sanitizer unit + bug-repro + wiring invariants, setup helper static-invariant + behavior matrix, build-script POSIX-shell sanity, and a doc-vs-config deprecated-key drift guard. Docs that still referenced the renamed `gbrain_sync_mode` config key now say `artifacts_sync_mode` consistently, and the drift guard prevents reintroduction.
 
 Contributed by @realcarsonterry: PRs #1460, #1461, #1462, and #1463 are the seed of this wave. The scope expansion to all 42 setup sites + every server egress path + Windows CI migration is the gstack maintainer's follow-through.
 
@@ -24,7 +24,8 @@ Source: this branch's diff against `origin/main` and the wave plan at `~/.claude
 | Bash brace groups in `package.json` build script (Bun-Windows-hostile) | 3 | 0 | -3 |
 | Stale `gbrain_sync_mode` references in docs | 5 | 0 | -5 |
 | New regression tests | 0 | 29 (4 files) | +29 |
-| CI runner pool | mix of `ubuntu-latest` + `ubicloud-standard-2` + `windows-latest` | `ubicloud-standard-8` everywhere (Windows = `ubicloud-standard-8-windows`) | single billing surface, 4x more cores on Linux jobs, paid Windows that actually runs |
+| Linux CI runner pool | mix of `ubuntu-latest` (4 core, free) + `ubicloud-standard-2` | `ubicloud-standard-8` everywhere | single billing surface for Linux, 4x more cores on previously-free jobs |
+| Windows CI runner | `windows-latest` (free) | `windows-latest` (free, unchanged) | Ubicloud doesn't offer Windows; paid GitHub larger-runner option requires org-billing toggle not currently set |
 
 The static invariant test (D7) reads `setup` and asserts zero raw `ln` calls outside the `_link_or_copy` helper body — even a single one-line slip by a future contributor fails the build.
 
@@ -46,8 +47,9 @@ If you run gstack on Windows: `./setup` now produces a working install across ev
 - **`browse/src/server.ts`** — `handleCommandInternal` split into `handleCommandInternalImpl` (raw) + thin sanitizing wrapper. Single egress point for both HTTP and batch consumers. Inline INVARIANT comment near the wrapper documents the architectural constraint.
 - **`browse/src/server.ts` SSE producers** — activity feed (`/activity/stream`) and inspector stream stringify with `sanitizeReplacer`, a `JSON.stringify` replacer function that cleans every string value during encoding. Post-stringify regex is a no-op because `JSON.stringify` has already converted `\uD800` to `"\\ud800"` before the regex could match. Inline INVARIANT comment in each.
 - **`setup`** — new `_link_or_copy SRC DST` helper near `IS_WINDOWS` detection (~line 33). Auto-dispatches on file-vs-directory + Windows-vs-Unix, and skips Unix-style name-only aliases (e.g. `gstack/open-gstack-browser` for the connect-chrome alias) when the source doesn't resolve on disk so Windows installs don't abort under `set -e`. All 42 prior `ln -snf` call sites converted to `_link_or_copy`. New `_print_windows_copy_note_once` helper called from `link_claude_skill_dirs` after any link work completes. `cleanup_old_claude_symlinks` and `cleanup_prefixed_claude_symlinks` extended with a Windows branch so `--prefix` / `--no-prefix` flips remove stale real-file SKILL.md copies instead of leaving them behind.
-- **`.github/workflows/*.yml` (all 9 workflows)** — every `runs-on` switched to Ubicloud: `ubicloud-standard-8` for Linux (`evals.yml`, `evals-periodic.yml`, `ci-image.yml`, `actionlint.yml`, `pr-title-sync.yml`, `skill-docs.yml`, `version-gate.yml`, `make-pdf-gate.yml`'s Linux matrix entry) and `ubicloud-standard-8-windows` for Windows (`windows-free-tests.yml`). The `evals.yml` matrix default and the prose footer both updated to reference `ubicloud-standard-8`. Test-list in `windows-free-tests.yml` expanded to include the 4 new wave tests.
-- **`.github/actionlint.yaml`** — registers all four Ubicloud labels (`ubicloud-standard-2/8` and `ubicloud-standard-2/8-windows`) so workflow lint stops rejecting any of them. The duplicate dead-weight `actionlint.yaml` at the repo root is removed (actionlint only reads `.github/actionlint.yaml`).
+- **`.github/workflows/*.yml` (8 Linux workflows)** — every Linux `runs-on` switched to `ubicloud-standard-8`: `evals.yml`, `evals-periodic.yml`, `ci-image.yml`, `actionlint.yml`, `pr-title-sync.yml`, `skill-docs.yml`, `version-gate.yml`, and `make-pdf-gate.yml`'s Linux matrix entry. The `evals.yml` matrix default and the prose footer both updated to reference `ubicloud-standard-8`.
+- **`.github/workflows/windows-free-tests.yml`** — stays on GitHub-hosted free `windows-latest`. Test-list expanded to include the 4 new wave tests. Earlier attempts on Blacksmith/GitHub-larger/Ubicloud-Windows all failed (label not registered, org-billing off, vendor doesn't offer Windows respectively); free `windows-latest` is the working path.
+- **`.github/actionlint.yaml`** — registers the two Ubicloud Linux labels (`ubicloud-standard-2`, `ubicloud-standard-8`) so workflow lint accepts them. The duplicate dead-weight `actionlint.yaml` at the repo root is removed (actionlint only reads `.github/actionlint.yaml`).
 - **`package.json`** — build script's three `{ git rev-parse HEAD 2>/dev/null || true; } > path/.version` brace groups replaced with `( ... )` subshells. POSIX-universal, Bun-Windows-compatible.
 - **`docs/gbrain-sync.md`, `docs/gbrain-sync-errors.md`** — 5 stale `gbrain_sync_mode` config-key references → `artifacts_sync_mode` (the rename landed in v1.27.0.0 but two docs still pointed at the old key).
 

From 7f6c9ab1ae6173923bf30ae184665c0fb4765494 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 14 May 2026 21:05:22 -0700
Subject: [PATCH 12/12] test(windows): skip Unix-only cases on Windows runner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

windows-free-tests on GitHub free windows-latest fails three cases that
depend on Unix tooling the runner doesn't have:

1. `setup-windows-fallback.test.ts` behavior matrix — IS_WINDOWS=0 cells
   assert `ln -snf` produces a real symlink. On Windows-without-Developer-
   Mode (which the free `windows-latest` runner is), `ln -snf` silently
   creates a file copy. That's literally the bug `_link_or_copy` exists
   to work around, so the assertion can never pass there. Skip the whole
   describe block on win32. The static-invariant test (zero raw `ln`
   outside the helper body) above the matrix still runs and pins the
   shape the Windows install relies on.

2. `docs-config-keys.test.ts` round-trip — spawnSync(`bin/gstack-config`)
   on Windows doesn't read the bash shebang and fails to exec. Skip on
   win32; the deprecated-key denylist test in the same file still runs
   and is the actual invariant defending the v1.27.0.0 rename at the doc
   layer.

Use `describe.skipIf(process.platform === 'win32', ...)` and
`test.skipIf(process.platform === 'win32', ...)`. Tests still run on
macOS and Linux unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 test/docs-config-keys.test.ts       | 6 +++++-
 test/setup-windows-fallback.test.ts | 8 +++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/test/docs-config-keys.test.ts b/test/docs-config-keys.test.ts
index 2ced29d6e..9fcfc787b 100644
--- a/test/docs-config-keys.test.ts
+++ b/test/docs-config-keys.test.ts
@@ -61,7 +61,11 @@ describe('docs ↔ gstack-config key drift guard', () => {
     expect(stale).toEqual([]);
   });
 
-  test('`gstack-config get artifacts_sync_mode` returns a value (the rename landed)', () => {
+  // gstack-config is a bash script; Windows can't exec it via spawnSync
+  // without a Git Bash interpreter shim. Skip on Windows — the deprecated-key
+  // denylist test above already pins the v1.27.0.0 rename behavior at the
+  // doc layer, which is the actual invariant this wave defends.
+  test.skipIf(process.platform === 'win32')('`gstack-config get artifacts_sync_mode` returns a value (the rename landed)', () => {
     // Run from a clean HOME so the user's local config doesn't pollute.
     const tmpHome = fs.mkdtempSync(path.join(require('os').tmpdir(), 'gstack-cfg-'));
     try {
diff --git a/test/setup-windows-fallback.test.ts b/test/setup-windows-fallback.test.ts
index 6c3735860..cc04fbbd7 100644
--- a/test/setup-windows-fallback.test.ts
+++ b/test/setup-windows-fallback.test.ts
@@ -57,7 +57,13 @@ describe('setup: _link_or_copy invariant (D7)', () => {
   });
 });
 
-describe('setup: _link_or_copy helper — behavior matrix', () => {
+// Behavior matrix uses Unix `ln -snf` semantics in the IS_WINDOWS=0 cells.
+// On Windows-without-Developer-Mode (e.g. GitHub's free `windows-latest`
+// runner), `ln -snf` silently produces a file copy rather than a symlink —
+// that's literally the bug this helper exists to work around. Skip the whole
+// matrix on Windows; the static-invariant tests above already pin the helper
+// shape that the Windows install relies on.
+describe.skipIf(process.platform === 'win32')('setup: _link_or_copy helper — behavior matrix', () => {
   // Source the helper into a temp shell with IS_WINDOWS set and exercise
   // each cell of the file/dir × Windows/Unix matrix.
   function runHelper(