gstack/test/gstack-session-kind.test.ts

/**
 * gstack-session-kind — classifies the session so skills know whether a human can
 * answer an AskUserQuestion. Drives the AUQ-failure fallback branch:
 *   spawned     → auto-choose (orchestrator)
 *   headless    → BLOCK on AUQ failure
 *   interactive → prose fallback on AUQ failure
 *
 * These permutations are the contract the resolver rule depends on. Run with a
 * SCRUBBED env (the test process itself runs inside Conductor, so CONDUCTOR_* /
 * CLAUDE_CODE_* would leak in and contaminate the classification).
 *
 * Free, deterministic, gate-tier.
 */
import { describe, test, expect } from 'bun:test';
import { execFileSync } from 'child_process';
import * as path from 'path';

const BIN = path.resolve(__dirname, '..', 'bin', 'gstack-session-kind');

/** Run the helper with ONLY the supplied env (plus PATH so bash resolves). */
function kind(env: Record<string, string>): string {
  return execFileSync(BIN, [], {
    env: { PATH: process.env.PATH ?? '/usr/bin:/bin', ...env },
    encoding: 'utf-8',
    timeout: 30_000,
  }).trim();
}

describe('gstack-session-kind', () => {
  test('OPENCLAW_SESSION → spawned (highest precedence)', () => {
    expect(kind({ OPENCLAW_SESSION: '1' })).toBe('spawned');
    // spawned wins even when other markers are also present
    expect(kind({ OPENCLAW_SESSION: '1', GSTACK_HEADLESS: '1', CONDUCTOR_PORT: '5' })).toBe('spawned');
  });

  test('GSTACK_HEADLESS → headless', () => {
    expect(kind({ GSTACK_HEADLESS: '1' })).toBe('headless');
  });

  test('CONDUCTOR_* → interactive (a human host is present)', () => {
    expect(kind({ CONDUCTOR_WORKSPACE_PATH: '/tmp/ws' })).toBe('interactive');
    expect(kind({ CONDUCTOR_PORT: '55010' })).toBe('interactive');
  });

  test('CLAUDE_CODE_ENTRYPOINT=cli → interactive', () => {
    expect(kind({ CLAUDE_CODE_ENTRYPOINT: 'cli' })).toBe('interactive');
  });

  test('interactive host beats CI markers', () => {
    expect(kind({ CONDUCTOR_PORT: '5', CI: '1' })).toBe('interactive');
  });

  test('CI / GITHUB_ACTIONS with no host → headless', () => {
    expect(kind({ CI: '1' })).toBe('headless');
    expect(kind({ GITHUB_ACTIONS: 'true' })).toBe('headless');
  });

  test('GSTACK_HEADLESS beats CONDUCTOR (explicit override wins)', () => {
    expect(kind({ GSTACK_HEADLESS: '1', CONDUCTOR_PORT: '5' })).toBe('headless');
  });

  test('bare env → interactive (degrade-safe default)', () => {
    expect(kind({})).toBe('interactive');
  });

  test('empty GSTACK_HEADLESS is treated as unset (interactive)', () => {
    // The resolver/helper guard on -n, so an empty string must NOT mean headless —
    // this is the opt-out path harness suites use to exercise the interactive branch.
    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');
  });
});