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-prune-stale-generated.test.ts

@@ -35,16 +35,26 @@ function mk(t: string) {
   const src = path.join(t, 'src');
   const gen = path.join(t, 'gen');
   const host = path.join(t, 'host');
-  // Source templates: a flat skill and the one prefixed source (gstack-upgrade).
+  // Source templates: a flat skill, the one prefixed source (gstack-upgrade), and a
+  // skill whose frontmatter `name:` differs from its directory (gen-skill-docs
+  // renders that one as gstack-test, never gstack-run-tests).
   for (const s of ['qa', 'gstack-upgrade']) {
     fs.mkdirSync(path.join(src, s), { recursive: true });
     fs.writeFileSync(path.join(src, s, 'SKILL.md.tmpl'), 'x');
   }
+  fs.mkdirSync(path.join(src, 'run-tests'), { recursive: true });
+  fs.writeFileSync(path.join(src, 'run-tests', 'SKILL.md.tmpl'), '---\nname: test\n---\nx\n');
   // Generated tree: live renders + two retired ones + the gstack sidecar.
-  for (const g of ['gstack-qa', 'gstack-upgrade', 'gstack-oldskill', 'gstack-gone', 'gstack-extra', 'gstack']) {
+  for (const g of ['gstack-qa', 'gstack-upgrade', 'gstack-test', 'gstack-oldskill', 'gstack-gone', 'gstack-extra', 'gstack']) {
     fs.mkdirSync(path.join(gen, g), { recursive: true });
     fs.writeFileSync(path.join(gen, g, 'SKILL.md'), `${BANNER}# ${g}\n`);
   }
+  // A symlink IN the render tree (a dev linking a WIP skill) whose target must
+  // survive: `rm -rf` on a slash-terminated link would empty the target.
+  const elsewhere = path.join(t, 'elsewhere');
+  fs.mkdirSync(elsewhere, { recursive: true });
+  fs.writeFileSync(path.join(elsewhere, 'SKILL.md'), `${BANNER}# wip\n`);
+  fs.symlinkSync(elsewhere, path.join(gen, 'gstack-wip'));
   fs.mkdirSync(host, { recursive: true });
   // Host entries: symlink (Unix), bannered real copy (Windows/Kiro), user's own dir.
   fs.symlinkSync(path.join(gen, 'gstack-qa') + '/', path.join(host, 'gstack-qa'));
@@ -58,19 +68,22 @@ function mk(t: string) {
   fs.mkdirSync(path.join(host, 'gstack-extra'));
   fs.writeFileSync(path.join(host, 'gstack-extra', 'SKILL.md'), `${BANNER}copy\n`);
   fs.writeFileSync(path.join(host, 'gstack-extra', 'notes.md'), 'my notes\n');
-  return { src, gen, host };
+  return { src, gen, host, elsewhere };
 }
 
 function runPrune(src: string, gen: string, host?: string) {
   const script = [
     'set -e',
+    'log() { echo "$@"; }',
     // _cleanup_weak_dir and the helpers it leans on come from main's ownership
     // gate; the prune routes bannered real dirs through it.
     extractFn('_gstack_link_target_abs'),
     extractFn('_gstack_target_is_ours'),
+    extractFn('_gstack_generated_header'),
     extractFn('_backup_skill_md'),
     extractFn('_cleanup_weak_dir'),
     extractFn('_owned_for_windows_refresh'),
+    extractFn('_skill_source_exists'),
     extractFn('_prune_stale_generated'),
     `_prune_stale_generated "${src}" "${gen}" ${host ? `"${host}"` : ''}`,
   ].join('\n');
@@ -100,7 +113,11 @@ describe('setup: _prune_stale_generated', () => {
       expect(r.stdout).toContain('pruned retired skill: gstack-oldskill');
       expect(r.stdout).toContain('pruned retired skill: gstack-gone');
 
-      expect(fs.readdirSync(gen).sort()).toEqual(['gstack', 'gstack-qa', 'gstack-upgrade']);
+      // gstack-test survives on its frontmatter name; the wip symlink is skipped, its target intact.
+      expect(fs.readdirSync(gen).sort()).toEqual(['gstack', 'gstack-qa', 'gstack-test', 'gstack-upgrade', 'gstack-wip']);
+      expect(fs.readFileSync(path.join(t, 'elsewhere', 'SKILL.md'), 'utf-8')).toContain('# wip');
+      expect(r.stdout).not.toContain('gstack-wip');
+      expect(r.stdout).not.toContain('gstack-test');
       // Symlink to a retired render + bannered copy of one: removed.
       expect(fs.existsSync(path.join(host, 'gstack-oldskill'))).toBe(false);
       expect(fs.lstatSync(path.join(host, 'gstack-oldskill'), { throwIfNoEntry: false })).toBeUndefined();
@@ -119,17 +136,46 @@ describe('setup: _prune_stale_generated', () => {
     }
   });
 
-  test('no host dir → prunes the render tree only; missing render tree → no-op', () => {
+  test('no host dir → prunes the render tree only; a host dir is cleaned even after the generator already removed the render', () => {
     const t = fs.mkdtempSync(path.join(os.tmpdir(), 'prune-'));
     try {
       const { src, gen, host } = mk(t);
       expect(runPrune(src, gen).status).toBe(0);
       expect(fs.existsSync(path.join(gen, 'gstack-oldskill'))).toBe(false);
-      expect(fs.lstatSync(path.join(host, 'gstack-oldskill')).isSymbolicLink()).toBe(true); // dangling, but not ours to touch here
+      expect(fs.lstatSync(path.join(host, 'gstack-oldskill')).isSymbolicLink()).toBe(true); // dangling, but no host dir was passed
 
-      const r = runPrune(src, path.join(t, 'nope'), host);
+      // gen-skill-docs prunes its own render tree before setup runs; the host
+      // entries it left dangling must still be cleaned from the host dir alone.
+      const r = runPrune(src, gen, host);
       expect(r.status).toBe(0);
-      expect(r.stdout).toBe('');
+      expect(r.stdout).toContain('pruned retired skill: gstack-oldskill');
+      expect(fs.lstatSync(path.join(host, 'gstack-oldskill'), { throwIfNoEntry: false })).toBeUndefined();
+      expect(fs.existsSync(path.join(host, 'gstack-gone'))).toBe(false);
+      expect(fs.lstatSync(path.join(host, 'gstack-qa')).isSymbolicLink()).toBe(true);
+      expect(fs.readFileSync(path.join(host, 'gstack-mine', 'SKILL.md'), 'utf-8')).toContain('user skill');
+
+      // A render tree that does not exist at all is a no-op when no host dir is passed.
+      const none = runPrune(src, path.join(t, 'nope'));
+      expect(none.status).toBe(0);
+      expect(none.stdout).toBe('');
+    } finally {
+      fs.rmSync(t, { recursive: true, force: true });
+    }
+  });
+
+  test('a host symlink that points outside gstack is never removed, even under a retired name', () => {
+    const t = fs.mkdtempSync(path.join(os.tmpdir(), 'prune-'));
+    try {
+      const { src, gen, host } = mk(t);
+      const theirs = path.join(t, 'their-skill');
+      fs.mkdirSync(theirs);
+      fs.writeFileSync(path.join(theirs, 'SKILL.md'), '---\nname: gstack-gone\n---\ntheirs\n');
+      fs.rmSync(path.join(host, 'gstack-gone'), { recursive: true, force: true });
+      fs.symlinkSync(theirs, path.join(host, 'gstack-gone'));
+      const r = runPrune(src, gen, host);
+      expect(r.status).toBe(0);
+      expect(fs.lstatSync(path.join(host, 'gstack-gone')).isSymbolicLink()).toBe(true);
+      expect(fs.readFileSync(path.join(theirs, 'SKILL.md'), 'utf-8')).toContain('theirs');
     } finally {
       fs.rmSync(t, { recursive: true, force: true });
     }