feat(session-kind): explicit GSTACK_SESSION_KIND override; skill-start spawned gates keyed on kind (#2733)

Claude Code subagents inherit the parent env byte-for-byte, so ambient
markers classify them as the parent's kind and the spawned classification
was unreachable outside OpenClaw. GSTACK_SESSION_KIND=spawned (step 0,
spawned-only by design) lets a dispatching skill mark its subagent per
command. skill-start now keys SPAWNED_SESSION and the spawned-session
instruction block on the resolved kind (was raw OPENCLAW_SESSION),
suppresses CONDUCTOR_SESSION for spawned sessions, gates all 11
interactive-onboarding blocks plus their ack-at-emit marker writes on
kind != spawned, and adds a destructive-gate carve-out to the spawned
block (conservative-continue, never prose-STOP).

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

test/gstack-session-kind.test.ts

@@ -68,3 +68,34 @@ describe('gstack-session-kind', () => {
     expect(kind({ GSTACK_HEADLESS: '' })).toBe('interactive');
   });
 });
+
+describe('GSTACK_SESSION_KIND explicit override (#2733)', () => {
+  test('spawned wins over every ambient marker (step 0, explicit beats ambient)', () => {
+    // Claude Code subagents inherit the parent env byte-for-byte, so the
+    // per-command marker must outrank whatever the parent session looks like.
+    expect(kind({ GSTACK_SESSION_KIND: 'spawned' })).toBe('spawned');
+    expect(kind({ GSTACK_SESSION_KIND: 'spawned', CONDUCTOR_PORT: '5' })).toBe('spawned');
+    expect(kind({ GSTACK_SESSION_KIND: 'spawned', CONDUCTOR_WORKSPACE_PATH: '/x', CI: '1' })).toBe('spawned');
+    expect(kind({ GSTACK_SESSION_KIND: 'spawned', GSTACK_HEADLESS: '1' })).toBe('spawned');
+    expect(kind({ GSTACK_SESSION_KIND: 'spawned', CLAUDE_CODE_ENTRYPOINT: 'cli' })).toBe('spawned');
+  });
+
+  test('only "spawned" is honored — reserved values fall through to detection', () => {
+    // Deliberately narrow: "headless" already has GSTACK_HEADLESS, and letting
+    // an env var force "interactive" over CI markers would be a footgun.
+    expect(kind({ GSTACK_SESSION_KIND: 'headless' })).toBe('interactive');
+    expect(kind({ GSTACK_SESSION_KIND: 'headless', OPENCLAW_SESSION: '1' })).toBe('spawned');
+    expect(kind({ GSTACK_SESSION_KIND: 'interactive', CI: '1' })).toBe('headless');
+  });
+
+  test('invalid values are ignored (case-sensitive)', () => {
+    expect(kind({ GSTACK_SESSION_KIND: 'bogus' })).toBe('interactive');
+    expect(kind({ GSTACK_SESSION_KIND: 'bogus', CI: '1' })).toBe('headless');
+    expect(kind({ GSTACK_SESSION_KIND: 'SPAWNED' })).toBe('interactive');
+  });
+
+  test('empty GSTACK_SESSION_KIND is treated as unset', () => {
+    expect(kind({ GSTACK_SESSION_KIND: '' })).toBe('interactive');
+    expect(kind({ GSTACK_SESSION_KIND: '', OPENCLAW_SESSION: '1' })).toBe('spawned');
+  });
+});

test/gstack-skill-start.test.ts

@@ -197,6 +197,61 @@ describe('gstack-skill-start behavior', () => {
     }
   });
 
+  test('spawned override suppresses CONDUCTOR_SESSION, emits SPAWNED_SESSION + block, gates onboarding (#2733)', () => {
+    const freshGh = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ss-spawned-'));
+    fs.writeFileSync(path.join(freshGh, 'config.yaml'), 'update_check: false\n');
+    try {
+      const out = runStart([], {
+        GSTACK_SESSION_KIND: 'spawned',
+        CONDUCTOR_WORKSPACE_PATH: '/x',
+        GSTACK_HOME: freshGh,
+      });
+      expect(out).toMatch(/^SESSION_KIND: spawned$/m);
+      // spawned outranks Conductor: prose-to-nobody is always wrong.
+      expect(out).not.toContain('CONDUCTOR_SESSION: true');
+      expect(out).toMatch(/^SPAWNED_SESSION: true$/m);
+      // The ONLY instruction block a spawned session gets is spawned-session —
+      // none of the 11 interactive-onboarding blocks may emit (no human is
+      // watching; auto-answered prompts would write config nobody approved).
+      const ids = (out.match(/^GSTACK_INSTRUCTION_BEGIN: (\S+)/gm) ?? []).map(
+        (h) => h.replace(/^GSTACK_INSTRUCTION_BEGIN: /, ''),
+      );
+      expect(ids).toEqual(['spawned-session']);
+      // Script-side ack-at-emit markers stay UNWRITTEN, so the one-time
+      // prompts fire intact on the next human session.
+      expect(fs.existsSync(path.join(freshGh, '.activated'))).toBe(false);
+      expect(fs.existsSync(path.join(freshGh, '.first-loop-tip-shown'))).toBe(false);
+      expect(fs.existsSync(path.join(freshGh, '.completeness-intro-seen'))).toBe(false);
+      expect(fs.existsSync(path.join(freshGh, '.telemetry-prompted'))).toBe(false);
+    } finally {
+      fs.rmSync(freshGh, { recursive: true, force: true });
+    }
+  });
+
+  test('legacy OPENCLAW_SESSION still gets full spawned behavior through the kind-keyed gates', () => {
+    // Regression pin for the raw-marker → $_SESSION_KIND migration (#2733):
+    // OpenClaw sessions must behave exactly as before the re-keying.
+    const freshGh = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ss-openclaw-'));
+    fs.writeFileSync(path.join(freshGh, 'config.yaml'), 'update_check: false\n');
+    try {
+      const out = runStart([], {
+        OPENCLAW_SESSION: '1',
+        CONDUCTOR_WORKSPACE_PATH: '/x',
+        GSTACK_HOME: freshGh,
+      });
+      expect(out).toMatch(/^SESSION_KIND: spawned$/m);
+      expect(out).not.toContain('CONDUCTOR_SESSION: true');
+      expect(out).toMatch(/^SPAWNED_SESSION: true$/m);
+      const ids = (out.match(/^GSTACK_INSTRUCTION_BEGIN: (\S+)/gm) ?? []).map(
+        (h) => h.replace(/^GSTACK_INSTRUCTION_BEGIN: /, ''),
+      );
+      expect(ids).toEqual(['spawned-session']);
+      expect(fs.existsSync(path.join(freshGh, '.activated'))).toBe(false);
+    } finally {
+      fs.rmSync(freshGh, { recursive: true, force: true });
+    }
+  });
+
   test('display-only tips ack at emit and never re-fire (OV6)', () => {
     const freshGh = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ss-refire-'));
     fs.writeFileSync(path.join(freshGh, 'config.yaml'), 'update_check: false\n');

test/preamble-compose.test.ts

@@ -83,6 +83,9 @@ describe('Conductor signal (skill-start script)', () => {
     const script = fs.readFileSync(path.join(import.meta.dir, '..', 'bin', 'gstack-skill-start'), 'utf-8');
     expect(script).toContain('echo "CONDUCTOR_SESSION: true"');
     expect(script).toMatch(/"\$_SESSION_KIND" != "headless"[\s\S]*CONDUCTOR_WORKSPACE_PATH[\s\S]*CONDUCTOR_PORT[\s\S]*CONDUCTOR_SESSION: true/);
+    // #2733: spawned outranks Conductor — a spawned session inside a Conductor
+    // workspace auto-chooses instead of rendering prose to nobody.
+    expect(script).toMatch(/"\$_SESSION_KIND" != "headless"[\s\S]{0,80}"\$_SESSION_KIND" != "spawned"[\s\S]{0,200}CONDUCTOR_SESSION: true/);
   });
 
   test('claude preamble render invokes the script and interprets CONDUCTOR_SESSION', () => {