Merge origin/main into garrytan/trunk-land-skill

Reconcile VERSION (1.56.0.0 stays above main's 1.55.0.0), package.json, and
CHANGELOG (1.56.0.0 entry on top of main's 1.54/1.55 entries). Regenerated
all host SKILL.md against main's resolver changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/gbrain-exec.ts

@@ -137,6 +137,18 @@ export function buildGbrainEnv(opts: BuildGbrainEnvOptions = {}): NodeJS.Process
   return out;
 }
 
+/**
+ * Windows can't directly spawn the `gbrain` launcher (bun/npm install it as a
+ * `gbrain.cmd`/`.ps1` shim) or a shebang script like the bash `gstack-brain-sync`
+ * — `spawnSync`/`spawn` resolve those only through a shell's PATHEXT + interpreter
+ * lookup. Without `shell: true` the child spawn fails ENOENT, which on the sync
+ * orchestrator surfaced as "brain-sync exited undefined" (#1731). Gate on platform
+ * so POSIX keeps the cheaper no-shell path. Exported so the static-grep tripwire
+ * (test/gbrain-spawn-windows-shell.test.ts) can assert every gbrain/brain-sync
+ * spawn carries it.
+ */
+export const NEEDS_SHELL_ON_WINDOWS = process.platform === "win32";
+
 export interface SpawnGbrainOptions {
   /** Timeout in milliseconds. Defaults to 30s. */
   timeout?: number;
@@ -166,6 +178,7 @@ export function spawnGbrain(args: string[], opts: SpawnGbrainOptions = {}): Spaw
     cwd: opts.cwd,
     stdio: opts.stdio || ["ignore", "pipe", "pipe"],
     env: buildGbrainEnv({ baseEnv: opts.baseEnv, announce: opts.announce }),
+    shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
   });
 }
 
@@ -198,6 +211,7 @@ export function spawnGbrainAsync(
     stdio: opts.stdio || ["ignore", "pipe", "pipe"],
     cwd: opts.cwd,
     env: buildGbrainEnv({ baseEnv: opts.baseEnv, announce: false }),
+    shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
   });
 }
 
@@ -212,5 +226,6 @@ export function execGbrainText(args: string[], opts: SpawnGbrainOptions = {}): s
     cwd: opts.cwd,
     stdio: opts.stdio || ["ignore", "pipe", "pipe"],
     env: buildGbrainEnv({ baseEnv: opts.baseEnv, announce: opts.announce }),
+    shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
   });
 }

lib/gbrain-guards.ts

@@ -0,0 +1,266 @@
+/**
+ * gbrain-guards — defense-in-depth against gbrain's destructive code paths (#1734).
+ *
+ * gbrain (the separate CLI gstack shells out to) can rm-rf a user's working tree
+ * during an autopilot race (its own bug, upstream gbrain #1526). gstack can't fix
+ * that, but it MUST stop treating gbrain's destructive subcommands as safe. These
+ * guards gate the two ways the orchestrator can reach destruction:
+ *
+ *   1. `sources remove --confirm-destructive`  → decideSourceRemove()
+ *   2. `sync --strategy code` (can auto-reclone) → decideCodeSync()
+ *
+ * plus an autopilot-active check (detectAutopilot) that refuses to run destructive
+ * ops concurrently with the daemon.
+ *
+ * Design notes grounded in the real gbrain 0.41.x surface:
+ *   - There is NO `--keep-storage` flag and NO structured capability command, and
+ *     subcommand `--help` is generic — so capability detection is best-effort and
+ *     defaults to "unsupported". When we can't protect a user-managed source's
+ *     files, we FAIL CLOSED (refuse the remove) rather than delete unprotected.
+ *   - The autopilot lock filename isn't documented and (gbrain #1226) ignores
+ *     GBRAIN_HOME, so the live `gbrain autopilot` process is the PRIMARY signal;
+ *     known lock paths under both the configured home and ~/.gbrain are secondary.
+ *   - We refuse only on an AFFIRMATIVE autopilot signal — inability to introspect
+ *     never blocks a normal sync (that would brick the tool).
+ *   - Path containment uses realpath so a symlink inside ~/.gbrain/clones can't
+ *     smuggle a delete out to a user repo.
+ *
+ * Pure decision functions; the orchestrator logs the reasons (observability).
+ */
+
+import { spawnSync } from "child_process";
+import { existsSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join, resolve, sep } from "path";
+import { execGbrainJson, execGbrainText, NEEDS_SHELL_ON_WINDOWS } from "./gbrain-exec";
+import { parseSourcesList, type GbrainSourceRow } from "./gbrain-sources";
+
+export function gbrainHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.GBRAIN_HOME || join(homedir(), ".gbrain");
+}
+
+/**
+ * Directories gbrain owns and may delete safely. A source whose local_path
+ * resolves inside one of these is gbrain-managed; outside = user-managed and
+ * must be protected. Both the configured home and the default ~/.gbrain are
+ * checked because gbrain #1226 shows home-resolution is inconsistent.
+ */
+function clonesDirs(env: NodeJS.ProcessEnv = process.env): string[] {
+  return [...new Set([join(gbrainHome(env), "clones"), join(homedir(), ".gbrain", "clones")])];
+}
+
+/** True if `p` resolves (symlinks + `..` collapsed) to a location inside `dir`. */
+export function isInside(p: string, dir: string): boolean {
+  let rp: string;
+  let rd: string;
+  try { rp = realpathSync(p); } catch { rp = resolve(p); }
+  try { rd = realpathSync(dir); } catch { rd = resolve(dir); }
+  const base = rd.endsWith(sep) ? rd : rd + sep;
+  return rp === rd || rp.startsWith(base);
+}
+
+// ── Autopilot detection (E1: multi-signal, affirmative-only) ────────────────
+
+export interface AutopilotStatus {
+  active: boolean;
+  /** Which signal fired (lock path or "process"), or null when inactive. */
+  signal: string | null;
+}
+
+export interface AutopilotProbe {
+  /** Override the lock-path list (tests). */
+  lockPaths?: string[];
+  /** Override the live-process check (tests). */
+  processRunning?: () => boolean;
+}
+
+/**
+ * Detect a running gbrain autopilot. Refuse the caller's destructive op only on
+ * an affirmative signal; absence of a confirmable mechanism returns inactive so
+ * normal syncs are never bricked.
+ */
+export function detectAutopilot(
+  env: NodeJS.ProcessEnv = process.env,
+  probe: AutopilotProbe = {},
+): AutopilotStatus {
+  // Secondary signal: known lock files. gbrain #1226 — the lock ignores
+  // GBRAIN_HOME, so check both the configured home and the default ~/.gbrain.
+  const lockPaths = probe.lockPaths ?? [
+    join(gbrainHome(env), "autopilot.lock"),
+    join(homedir(), ".gbrain", "autopilot.lock"),
+    join(gbrainHome(env), "autopilot.pid"),
+    join(homedir(), ".gbrain", "autopilot.pid"),
+  ];
+  for (const lp of lockPaths) {
+    if (existsSync(lp)) return { active: true, signal: `lock:${lp}` };
+  }
+  // Primary signal: a live `gbrain autopilot` process.
+  const running = (probe.processRunning ?? defaultProcessRunning)();
+  if (running) return { active: true, signal: "process:gbrain autopilot" };
+  return { active: false, signal: null };
+}
+
+function defaultProcessRunning(): boolean {
+  // No reliable pgrep on Windows; rely on the lock-file signal there.
+  if (process.platform === "win32") return false;
+  const r = spawnSync("pgrep", ["-f", "gbrain autopilot"], { encoding: "utf-8", timeout: 3_000 });
+  return r.status === 0 && (r.stdout || "").trim().length > 0;
+}
+
+// ── Capability detection (E4 + Codex: per-process memo, no persistent cache) ─
+//
+// No structured capability command exists and subcommand --help is generic, so
+// --keep-storage support can't be probed reliably; default unsupported. Memoize
+// per process (keyed to the resolved gbrain identity) rather than persisting a
+// cross-run cache — Codex flagged stale persistent caches, and the probe is cheap.
+
+let _keepStorageMemo: { key: string; value: boolean } | undefined;
+
+function gbrainIdentity(env: NodeJS.ProcessEnv): string {
+  const r = spawnSync("gbrain", ["--version"], {
+    encoding: "utf-8",
+    timeout: 3_000,
+    shell: NEEDS_SHELL_ON_WINDOWS,
+    env,
+  });
+  return (r.stdout || "").trim() || "unknown";
+}
+
+export function gbrainSupportsKeepStorage(env: NodeJS.ProcessEnv = process.env): boolean {
+  const key = gbrainIdentity(env);
+  if (_keepStorageMemo && _keepStorageMemo.key === key) return _keepStorageMemo.value;
+  let value = false;
+  for (const args of [["sources", "remove", "--help"], ["--help"]]) {
+    try {
+      if (/--keep-storage/.test(execGbrainText(args, { baseEnv: env, timeout: 5_000 }))) {
+        value = true;
+        break;
+      }
+    } catch {
+      // generic/empty help or non-zero exit → treat as unsupported
+    }
+  }
+  _keepStorageMemo = { key, value };
+  return value;
+}
+
+/** Test-only: reset the per-process capability memo. */
+export function _resetCapabilityMemo(): void {
+  _keepStorageMemo = undefined;
+}
+
+// ── Destructive-op decisions ────────────────────────────────────────────────
+
+/**
+ * Fetch + normalize the source list. Throws on read/parse failure so callers can
+ * distinguish "couldn't read" (fail closed) from "empty list" (source absent).
+ * Injectable for hermetic tests.
+ */
+export function fetchSources(env: NodeJS.ProcessEnv = process.env): GbrainSourceRow[] {
+  const raw = execGbrainJson(["sources", "list", "--json"], { baseEnv: env });
+  if (raw === null) throw new Error("gbrain sources list returned no JSON");
+  return parseSourcesList(raw);
+}
+
+export interface RemoveDecision {
+  allow: boolean;
+  /** Extra args to append to `sources remove` (e.g. --keep-storage). */
+  extraArgs: string[];
+  reason: string;
+}
+
+/**
+ * Decide whether `sources remove <id>` is safe, and with what flags.
+ *
+ * Fail-closed cases (allow=false):
+ *   - sources list unreadable/unparseable (can't prove the row is safe).
+ *   - the row is user-managed (remote_url set AND local_path outside gbrain's
+ *     clones) and gbrain has no --keep-storage to protect the files.
+ *
+ * Allowed: absent row (no-op), gbrain-managed (inside clones), or path-managed
+ * without a remote_url (gbrain's remove won't touch an outside-clones path that
+ * it didn't clone). --keep-storage is appended whenever supported, as extra armor.
+ */
+export interface DecideRemoveOpts {
+  /** Override capability detection (tests / cached caps). */
+  keepStorage?: boolean;
+  /** Override the source-list fetch (tests). Throwing simulates a read failure. */
+  fetchRows?: (env: NodeJS.ProcessEnv) => GbrainSourceRow[];
+}
+
+export function decideSourceRemove(
+  sourceId: string,
+  env: NodeJS.ProcessEnv = process.env,
+  opts: DecideRemoveOpts = {},
+): RemoveDecision {
+  const keepStorage = opts.keepStorage ?? gbrainSupportsKeepStorage(env);
+  const extra = keepStorage ? ["--keep-storage"] : [];
+
+  let rows: GbrainSourceRow[];
+  try {
+    rows = (opts.fetchRows ?? fetchSources)(env);
+  } catch {
+    return { allow: false, extraArgs: [], reason: "could not read sources list; refusing remove (fail closed)" };
+  }
+
+  const row = rows.find((r) => r.id === sourceId);
+  if (!row) return { allow: true, extraArgs: extra, reason: "source absent (no-op)" };
+
+  const remoteUrl = row.config?.remote_url;
+  const userManaged =
+    !!remoteUrl && !!row.local_path && !clonesDirs(env).some((d) => isInside(row.local_path!, d));
+
+  if (userManaged) {
+    if (keepStorage) {
+      return { allow: true, extraArgs: ["--keep-storage"], reason: "user-managed; --keep-storage protects files" };
+    }
+    return {
+      allow: false,
+      extraArgs: [],
+      reason:
+        `refusing remove of user-managed source "${sourceId}" (remote_url set, local_path ` +
+        `${row.local_path} outside gbrain clones) — this gbrain has no --keep-storage to ` +
+        `protect the working tree. Upgrade gbrain or remove the source manually.`,
+    };
+  }
+
+  return { allow: true, extraArgs: extra, reason: "gbrain-managed or path-managed without remote_url" };
+}
+
+export interface SyncDecision {
+  allow: boolean;
+  reason: string;
+}
+
+/**
+ * Decide whether `sync --strategy code --source <id>` is safe to run.
+ *
+ * A source with a remote_url can trigger gbrain's auto-reclone, the ungated
+ * rm-rf path behind the data loss (gbrain #1526). Require an explicit
+ * --allow-reclone opt-in for URL-managed sources. Read failure here is NOT
+ * itself destructive, so it fails open (proceed) — the autopilot guard, checked
+ * first, is the primary protection against the race that caused the loss.
+ */
+export function decideCodeSync(
+  sourceId: string,
+  env: NodeJS.ProcessEnv = process.env,
+  allowReclone = false,
+  fetchRows: (env: NodeJS.ProcessEnv) => GbrainSourceRow[] = fetchSources,
+): SyncDecision {
+  let rows: GbrainSourceRow[];
+  try {
+    rows = fetchRows(env);
+  } catch {
+    return { allow: true, reason: "sources unreadable; proceeding (sync read is non-destructive)" };
+  }
+  const row = rows.find((r) => r.id === sourceId);
+  if (row?.config?.remote_url && !allowReclone) {
+    return {
+      allow: false,
+      reason:
+        `source "${sourceId}" is URL-managed (remote_url set); sync may auto-reclone and ` +
+        `delete the working tree. Re-run /sync-gbrain with --allow-reclone to proceed.`,
+    };
+  }
+  return { allow: true, reason: "no remote_url, or reclone explicitly allowed" };
+}

lib/gbrain-local-status.ts

@@ -35,7 +35,7 @@ import {
 } from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
-import { buildGbrainEnv } from "./gbrain-exec";
+import { buildGbrainEnv, NEEDS_SHELL_ON_WINDOWS } from "./gbrain-exec";
 
 export type LocalEngineStatus =
   | "ok"
@@ -113,6 +113,7 @@ export function resolveGbrainBin(env?: NodeJS.ProcessEnv): string | null {
       timeout: 2_000,
       stdio: ["ignore", "ignore", "ignore"],
       env: e,
+      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
     });
     result = "gbrain";
   } catch {
@@ -135,6 +136,7 @@ export function readGbrainVersion(env?: NodeJS.ProcessEnv): string {
       timeout: 2_000,
       stdio: ["ignore", "pipe", "ignore"],
       env: e,
+      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
     });
     result = out.trim().split("\n")[0] || "";
   } catch {
@@ -241,6 +243,7 @@ function freshClassify(env?: NodeJS.ProcessEnv): LocalEngineStatus {
       timeout: PROBE_TIMEOUT_MS,
       stdio: ["ignore", "pipe", "pipe"],
       env: buildGbrainEnv({ baseEnv: env ?? process.env }),
+      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
     });
     return "ok";
   } catch (err) {

lib/gbrain-sources.ts

@@ -11,6 +11,7 @@
 
 import { execFileSync, spawnSync } from "child_process";
 import { withErrorContext } from "./gstack-memory-helpers";
+import { NEEDS_SHELL_ON_WINDOWS } from "./gbrain-exec";
 
 export interface SourceState {
   /** "absent" — id not registered. "match" — id at expected path. "drift" — id at different path. */
@@ -26,6 +27,37 @@ export interface EnsureResult {
   state: SourceState;
 }
 
+/**
+ * One row of `gbrain sources list --json`. `config.remote_url` distinguishes
+ * URL-managed sources (gbrain owns the clone, may auto-reclone) from
+ * path-managed ones (user owns the working tree) — load-bearing for the #1734
+ * destructive-op guards.
+ */
+export interface GbrainSourceRow {
+  id?: string;
+  local_path?: string;
+  page_count?: number;
+  config?: { remote_url?: string | null } | null;
+}
+
+/**
+ * Normalize `gbrain sources list --json` output to an array of source rows.
+ *
+ * gbrain has shipped two shapes: a wrapped `{ sources: [...] }` object (v0.20+)
+ * and, in older/other variants, a bare top-level array. #1576 was a crash when a
+ * reader assumed one shape; the parse is centralized here so every reader
+ * (probeSource, sourcePageCount, sourceLocalPath, the #1734 remote_url audit)
+ * agrees on the shape in ONE place. Returns [] for null/garbage rather than
+ * throwing — callers treat "no rows" as absent.
+ */
+export function parseSourcesList(raw: unknown): GbrainSourceRow[] {
+  if (Array.isArray(raw)) return raw as GbrainSourceRow[];
+  if (raw && typeof raw === "object" && Array.isArray((raw as { sources?: unknown }).sources)) {
+    return (raw as { sources: GbrainSourceRow[] }).sources;
+  }
+  return [];
+}
+
 export interface EnsureOptions {
   /** Pass --federated to `gbrain sources add`. Default false. */
   federated?: boolean;
@@ -56,6 +88,7 @@ export function probeSource(id: string, env?: NodeJS.ProcessEnv): SourceState {
       timeout: 30_000,
       stdio: ["ignore", "pipe", "pipe"],
       env,
+      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
     });
   } catch (err) {
     const e = err as NodeJS.ErrnoException & { stderr?: Buffer };
@@ -69,14 +102,14 @@ export function probeSource(id: string, env?: NodeJS.ProcessEnv): SourceState {
     throw err;
   }
 
-  let parsed: { sources?: Array<{ id?: string; local_path?: string }> };
+  let parsed: unknown;
   try {
     parsed = JSON.parse(stdout);
   } catch (err) {
     throw new Error(`gbrain sources list returned non-JSON output: ${(err as Error).message}`);
   }
 
-  const sources = parsed.sources || [];
+  const sources = parseSourcesList(parsed);
   const match = sources.find((s) => s.id === id);
   if (!match) return { status: "absent" };
   return {
@@ -129,6 +162,7 @@ export async function ensureSourceRegistered(
         encoding: "utf-8",
         timeout: 30_000,
         env,
+        shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
       });
       if (rm.status !== 0) {
         throw new Error(`gbrain sources remove ${id} failed: ${rm.stderr || rm.stdout || `exit ${rm.status}`}`);
@@ -142,6 +176,7 @@ export async function ensureSourceRegistered(
       encoding: "utf-8",
       timeout: 30_000,
       env,
+      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
     });
     if (add.status !== 0) {
       throw new Error(`gbrain sources add ${id} failed: ${add.stderr || add.stdout || `exit ${add.status}`}`);
@@ -167,14 +202,14 @@ export function sourcePageCount(id: string, env?: NodeJS.ProcessEnv): number | n
       timeout: 30_000,
       stdio: ["ignore", "pipe", "pipe"],
       env,
+      shell: NEEDS_SHELL_ON_WINDOWS, // #1731: gbrain is a .cmd shim on Windows
     });
   } catch {
     return null;
   }
 
   try {
-    const parsed = JSON.parse(stdout) as { sources?: Array<{ id?: string; page_count?: number }> };
-    const match = (parsed.sources || []).find((s) => s.id === id);
+    const match = parseSourcesList(JSON.parse(stdout)).find((s) => s.id === id);
     if (!match) return null;
     if (typeof match.page_count !== "number") return null;
     return match.page_count;