fix: pre-landing review fixes for the Aside-first branch

Review army + adversarial passes (Claude and Codex) on the merged branch:

setup
- _prune_stale_generated scans the host dirs too (the generator already
  removed the render before setup ran, so the host branch was dead), skips
  symlinks in the render tree (rm -rf on a slash-terminated link empties its
  target), removes a host symlink only when it resolves into gstack, cleans a
  bannered real dir through _cleanup_weak_dir, recognizes frontmatter-renamed
  skills, and logs through log. The always-run codex render passes every host
  dir that may link to it.
- NEEDS_BUILD checks all three binaries (with $_EXE) and lib/ sources; the
  browser hint and the bootstrap summary honor GSTACK_SKIP_ASIDE, treat a
  requested skip as a request, and derive one skill list.

lib/aside-render.ts + bin/gstack-render.ts
- The loopback server carries a per-render secret path, checks containment on
  the real path (symlink escapes are 403), and rejects malformed encoding.
- Inline eval results are one base64 line, so page text cannot forge
  ASIDE_DIR= or the sentinel; the last ASIDE_DIR wins.
- runProc escalates SIGTERM to SIGKILL, bounds every wait, and clears every
  timer (an uncleared one kept gstack-render alive after printing OK).
- renderTmpDir refuses a shared /tmp name owned by someone else; the work dir
  and server are created inside try; goto's budget follows the render budget.
- probeAside classifies a present-but-failing CLI as ASIDE_NOT_RUNNING like
  the skills' bash probe; render() retries on gstack's own browser when Aside
  could not start or its private CDP bridge is gone (never on a page error
  or a timeout of a running script); the CLI reports the engine that actually
  rendered, exits 0 on --help, rejects non-numeric flags, documents
  --wait-timeout, fences EVAL/PAGE_ERRORS as untrusted content, and names the
  daemon's cookie-import JS lock remedy.
- The browse path passes --scale only when asked (a scale change rebuilds
  the daemon context) and restores the viewport after a sized screenshot.

resolvers / templates
- The bash probe honors GSTACK_SKIP_ASIDE and has a perl deadline on stock
  macOS; .local is no longer LOCAL (mDNS); same-origin filters compare parsed
  origins; link status is HEAD-checked only on LOCAL targets; every
  aside exec goes through the receipted _aside_exec prelude
  ({{ASIDE_EXEC_PRELUDE}}), including nine template blocks that called it
  bare; the design sketch and diagram staging use private directories.
- The generator prunes only bannered renders and never a host whose
  generation failed.

Docs, stale comments and dead code cleaned; goldens re-rendered; tests
updated and added for every behavior above.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

test/setup-browser-hint.test.ts

@@ -9,8 +9,13 @@
  *   - _browser_hint, the one-line "browser:" hint under every host's
  *     "gstack ready" block;
  *   - the Chromium bootstrap summary printed last.
+ * Both sites also honor GSTACK_SKIP_ASIDE=1 (the library's and the skills'
+ * opt-out): with it set, an installed Aside counts as absent, so the lines
+ * describe the bundled browser, never Aside. And the Aside-absent skill list
+ * is DERIVED from the Aside-first list plus /pair-agent (which always runs on
+ * gstack's own browser), so the two can never drift.
  * Behavior fixture: extract the code from setup and run it with the Aside
- * probe stubbed and the reason set or empty.
+ * probe stubbed, the reason set or empty, and the opt-out set or unset.
  */
 import { describe, test, expect } from 'bun:test';
 import { spawnSync } from 'child_process';
@@ -40,14 +45,26 @@ function summaryReasonBlock(): string {
 // so the test never depends on whether the machine running it has Aside.
 const COMMAND_SHADOW = 'command() { if [ "$1" = "-v" ] && [ "$2" = "aside" ]; then [ "$ASIDE_PRESENT" = "1" ]; else builtin command "$@"; fi; }';
 
-function runBash(lines: string[]): string {
-  const r = spawnSync('bash', ['-c', lines.join('\n')], { encoding: 'utf-8', timeout: 30_000 });
+function runBash(lines: string[], env: Record<string, string> = {}): string {
+  // GSTACK_SKIP_ASIDE is read from the environment. Strip any inherited value
+  // so the outcome is decided by the test, never by the operator's shell.
+  const base: Record<string, string | undefined> = { ...process.env };
+  delete base.GSTACK_SKIP_ASIDE;
+  const r = spawnSync('bash', ['-c', lines.join('\n')], { encoding: 'utf-8', timeout: 30_000, env: { ...base, ...env } });
   expect(r.stderr).toBe('');
   expect(r.status).toBe(0);
   return r.stdout;
 }
 
-function runHint(opts: { aside: boolean; reason: string }): string {
+/** `skipAside` is the value GSTACK_SKIP_ASIDE carries in the environment;
+ *  omitted means unset. Only the literal "1" is the opt-out. */
+type SiteOpts = { aside: boolean; reason: string; skipAside?: string };
+
+function siteEnv(opts: SiteOpts): Record<string, string> {
+  return opts.skipAside === undefined ? {} : { GSTACK_SKIP_ASIDE: opts.skipAside };
+}
+
+function runHint(opts: SiteOpts): string {
   return runBash([
     'set -e',
     'log() { echo "$@"; }',
@@ -56,10 +73,10 @@ function runHint(opts: { aside: boolean; reason: string }): string {
     `_PW_FAIL_REASON=${JSON.stringify(opts.reason)}`,
     extractFn('_browser_hint'),
     '_browser_hint',
-  ]);
+  ], siteEnv(opts));
 }
 
-function runSummary(opts: { aside: boolean; reason: string }): string {
+function runSummary(opts: SiteOpts): string {
   return runBash([
     'set -e',
     'log() { echo "$@"; }',
@@ -68,8 +85,19 @@ function runSummary(opts: { aside: boolean; reason: string }): string {
     'SOURCE_GSTACK_DIR=/nonexistent-gstack-dir', // no telemetry binary → the event is skipped
     `_PW_FAIL_REASON=${JSON.stringify(opts.reason)}`,
     summaryReasonBlock(),
+    // The two skill lists the block defines, so a test can check the
+    // derivation at runtime and not only in the source text.
+    'echo "ASIDE_SKILLS=$_PW_ASIDE_SKILLS"',
+    'echo "BROWSER_SKILLS=$_PW_BROWSER_SKILLS"',
     'echo REACHED_END=1',
-  ]);
+  ], siteEnv(opts));
+}
+
+function summaryLists(out: string): { aside: string; browser: string } {
+  const aside = out.match(/^ASIDE_SKILLS=(.*)$/m)?.[1];
+  const browser = out.match(/^BROWSER_SKILLS=(.*)$/m)?.[1];
+  if (aside === undefined || browser === undefined) throw new Error(`summary block did not define both skill lists:\n${out}`);
+  return { aside, browser };
 }
 
 describe('setup: _browser_hint', () => {
@@ -103,6 +131,40 @@ describe('setup: _browser_hint', () => {
     expect(out).toContain('re-run ./setup');
     expect(out).not.toContain('gstack browser (fallback)');
   });
+
+  test('static pin: the hint honors the GSTACK_SKIP_ASIDE opt-out before probing for Aside', () => {
+    expect(extractFn('_browser_hint')).toContain('[ "${GSTACK_SKIP_ASIDE:-}" != "1" ] && command -v aside');
+  });
+
+  test('GSTACK_SKIP_ASIDE=1 with Aside on PATH, bootstrap fine → treated as Aside absent: the fallback line, never Aside (primary)', () => {
+    const out = runHint({ aside: true, reason: '', skipAside: '1' });
+    expect(out).toContain('browser: gstack browser (fallback). Install Aside for the primary path: aside.com (macOS 15+)');
+    expect(out).not.toContain('Aside (primary)');
+  });
+
+  test('GSTACK_SKIP_ASIDE=1 with Aside on PATH, bootstrap failed → none available; Aside is not promised', () => {
+    const out = runHint({ aside: true, reason: 'chromium-install', skipAside: '1' });
+    expect(out).toContain('browser: none available');
+    expect(out).toContain('chromium-install');
+    expect(out).not.toContain('Aside (primary)');
+  });
+
+  test('only the literal 1 opts out: GSTACK_SKIP_ASIDE=0 or empty keeps Aside primary', () => {
+    for (const v of ['0', '']) {
+      const out = runHint({ aside: true, reason: '', skipAside: v });
+      expect(out).toContain('browser: Aside (primary) — gstack browser is the fallback');
+    }
+  });
+});
+
+describe('setup: _browser_hint treats GSTACK_SKIP_PLAYWRIGHT as a request, not a failure', () => {
+  test('Aside absent, bootstrap skipped by request → names the flag, does not say fix the bootstrap', () => {
+    const out = runHint({ aside: false, reason: 'skipped' });
+    expect(out).toContain('browser: none available');
+    expect(out).toContain('skipped by request (GSTACK_SKIP_PLAYWRIGHT=1)');
+    expect(out).toContain('re-run ./setup without the flag');
+    expect(out).not.toContain('fix the bootstrap');
+  });
 });
 
 describe('setup: Chromium bootstrap summary is Aside-aware', () => {
@@ -132,4 +194,44 @@ describe('setup: Chromium bootstrap summary is Aside-aware', () => {
     expect(out).not.toContain('Browser unavailable');
     expect(out).toContain('REACHED_END=1');
   });
+
+  test('GSTACK_SKIP_ASIDE=1 with Aside on PATH → the Aside-absent wording: the skills need the bundled browser', () => {
+    const out = runSummary({ aside: true, reason: 'chromium-install', skipAside: '1' });
+    expect(out).toContain('Browser unavailable: Chromium bootstrap did not complete (chromium-install)');
+    expect(out).toContain('Skills that need it:');
+    expect(out).toContain('/pair-agent');
+    expect(out).not.toContain('Aside is installed');
+    expect(out).not.toContain('only their bundled fallback is missing');
+    expect(out).toContain('REACHED_END=1');
+  });
+
+  test('static pin: _PW_BROWSER_SKILLS is derived from _PW_ASIDE_SKILLS (plus /pair-agent) so the two lists cannot drift', () => {
+    const block = summaryReasonBlock();
+    expect(block).toContain('_PW_BROWSER_SKILLS="$_PW_ASIDE_SKILLS,');
+    const asideLine = block.match(/^_PW_ASIDE_SKILLS="(.*)"$/m)?.[1];
+    const browserLine = block.match(/^_PW_BROWSER_SKILLS="(.*)"$/m)?.[1];
+    expect(asideLine).toBeDefined();
+    expect(browserLine).toBeDefined();
+    // /pair-agent always runs on gstack's own browser, so it belongs only to
+    // the derived list, never to the Aside-first list.
+    expect(asideLine).not.toContain('/pair-agent');
+    expect(browserLine).toContain('/pair-agent');
+    expect(block).toContain('[ "${GSTACK_SKIP_ASIDE:-}" != "1" ] && command -v aside');
+  });
+
+  test('runtime: the Aside-absent list is the Aside list plus /pair-agent, and each arm prints its own list verbatim', () => {
+    const present = runSummary({ aside: true, reason: 'chromium-install' });
+    const { aside, browser } = summaryLists(present);
+    expect(aside.length).toBeGreaterThan(0);
+    expect(aside).not.toContain('/pair-agent');
+    expect(browser.startsWith(`${aside}, /pair-agent`)).toBe(true);
+    // Aside present: the Aside-first skills keep running there, and /pair-agent
+    // is called out as needing the bundled browser itself.
+    expect(present).toContain(`Aside is installed, so ${aside} keep running there; only their bundled fallback is missing.`);
+    expect(present).toContain('/pair-agent needs the bundled browser itself');
+    // Aside absent: the derived list, /pair-agent included, is what needs it.
+    const absent = runSummary({ aside: false, reason: 'chromium-install' });
+    expect(absent).toContain(`Skills that need it: ${browser}.`);
+    expect(summaryLists(absent)).toEqual({ aside, browser });
+  });
 });