Merge remote-tracking branch 'origin/main' into garrytan/gbrain-code-smell-audit

# Conflicts:
#	CHANGELOG.md
#	browse/test/dual-listener.test.ts
#	browse/test/fixtures/security-bench-haiku-responses.json
#	browse/test/sidebar-tabs.test.ts
#	browse/test/sidebar-ux.test.ts
#	browse/test/terminal-agent.test.ts
#	claude/SKILL.md.tmpl
#	scripts/gen-skill-docs.ts
#	scripts/proactive-suggestions.json
#	spec/SKILL.md
#	test/gen-skill-docs.test.ts
#	test/host-config.test.ts

scripts/resolvers/types.ts

@@ -16,6 +16,27 @@ export interface HostPaths {
   makePdfDir: string;
 }
 
+/**
+ * Make a host path safe to interpolate INSIDE DOUBLE QUOTES in generated bash.
+ *
+ * Tilde-based hosts (Claude, factory) resolve to paths like
+ * `~/.claude/skills/gstack/bin`. Bash only performs tilde expansion when the
+ * `~` is UNQUOTED, so `"~/.claude/..."` is a literal relative path that never
+ * resolves. A `[ -x "~/..." ]` test is therefore always false and a
+ * `"~/..." --flag` invocation always fails — the surrounding block silently
+ * becomes dead code rather than erroring.
+ *
+ * Env-var hosts already use `$GSTACK_BIN`, which expands correctly when
+ * quoted, so they pass through untouched.
+ *
+ * Use this ONLY where the path lands inside double quotes. Unquoted
+ * interpolations (`${ctx.paths.binDir}/gstack-slug`) expand fine as-is and are
+ * left alone so generated docs keep the more readable `~`.
+ */
+export function quoteSafePath(hostPath: string): string {
+  return hostPath.startsWith('~/') ? `$HOME/${hostPath.slice(2)}` : hostPath;
+}
+
 /**
  * HOST_PATHS — derived from host configs.
  * Each config's globalRoot/localSkillRoot determines the path structure.
@@ -50,6 +71,16 @@ function buildHostPaths(): Record<string, HostPaths> {
 
 export const HOST_PATHS: Record<string, HostPaths> = buildHostPaths();
 
+/**
+ * Render a HostPaths binary dir as a shell-expandable absolute path.
+ * Claude-style dirs are `~`-rooted (e.g. `~/.claude/skills/gstack/browse/dist`)
+ * and expand via `$HOME`; env-var hosts already carry an absolute `$GSTACK_*`
+ * value, so they pass through untouched — prepending `$HOME` would double it.
+ */
+export function toShellPath(dir: string): string {
+  return dir.startsWith('~') ? `$HOME${dir.slice(1)}` : dir;
+}
+
 import type { Model } from '../models';
 export type { Model } from '../models';