gsd-pi 2.76.0-dev.4c866b677 → 2.76.0-dev.7218806ab

package/src/resources/extensions/gsd/preferences.ts

@@ -68,13 +68,13 @@ export { resolveAllSkillReferences } from "./preferences-skills.js";
 // These lived in preferences-skills.ts but imported loadEffectiveGSDPreferences
 // back from this file, creating a circular dependency. Moved here since they
 // are trivial wrappers over loadEffectiveGSDPreferences.
-export function resolveSkillDiscoveryMode(): SkillDiscoveryMode {
-  const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillDiscoveryMode(basePath?: string): SkillDiscoveryMode {
+  const prefs = loadEffectiveGSDPreferences(basePath);
   return prefs?.preferences.skill_discovery ?? "suggest";
 }
 
-export function resolveSkillStalenessDays(): number {
-  const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillStalenessDays(basePath?: string): number {
+  const prefs = loadEffectiveGSDPreferences(basePath);
   return prefs?.preferences.skill_staleness_days ?? 60;
 }
 
@@ -109,16 +109,16 @@ function legacyGlobalPreferencesPath(): string {
   return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
 
-function projectPreferencesPath(): string {
-  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPath(basePath: string = process.cwd()): string {
+  return join(gsdRoot(basePath), "PREFERENCES.md");
 }
 // Legacy lowercase files can still exist in older projects. Keep them as a
 // compatibility-only fallback, but route new reads/writes through PREFERENCES.md.
 function legacyGlobalPreferencesPathLowercase(): string {
   return join(gsdHome(), "preferences.md");
 }
-function legacyProjectPreferencesPathLowercase(): string {
-  return join(gsdRoot(process.cwd()), "preferences.md");
+function legacyProjectPreferencesPathLowercase(basePath: string = process.cwd()): string {
+  return join(gsdRoot(basePath), "preferences.md");
 }
 
 export function getGlobalGSDPreferencesPath(): string {
@@ -129,8 +129,8 @@ export function getLegacyGlobalGSDPreferencesPath(): string {
   return legacyGlobalPreferencesPath();
 }
 
-export function getProjectGSDPreferencesPath(): string {
-  return projectPreferencesPath();
+export function getProjectGSDPreferencesPath(basePath?: string): string {
+  return projectPreferencesPath(basePath);
 }
 
 // ─── Loading ────────────────────────────────────────────────────────────────
@@ -141,14 +141,14 @@ export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
     ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 
-export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(projectPreferencesPath(), "project")
-    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(), "project");
+export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
+  return loadPreferencesFile(projectPreferencesPath(basePath), "project")
+    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
 
-export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
+export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
-  const projectPreferences = loadProjectGSDPreferences();
+  const projectPreferences = loadProjectGSDPreferences(basePath);
 
   if (!globalPreferences && !projectPreferences) return null;
 
@@ -603,8 +603,8 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */
-export function getIsolationMode(): "none" | "worktree" | "branch" {
-  const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function getIsolationMode(basePath?: string): "none" | "worktree" | "branch" {
+  const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
   if (prefs?.isolation === "worktree") return "worktree";
   if (prefs?.isolation === "branch") return "branch";
   return "none"; // default — no isolation, work on current branch

package/src/resources/extensions/gsd/prompts/discuss-headless.md

@@ -162,6 +162,10 @@ Preserve the specification's exact terminology, emphasis, and specific framing.
 6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `{{contextPath}}`, and called `gsd_plan_milestone`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
@@ -234,6 +238,10 @@ For single-milestone projects, do NOT write this file.
 
 7. {{multiMilestoneCommitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, the primary `CONTEXT.md`, called `gsd_plan_milestone` for the primary milestone, and written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ## Critical Rules

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -339,7 +339,20 @@ These sections are in addition to whatever other context the discussion surfaced
 6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -418,6 +431,20 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 
 7. {{multiMilestoneCommitInstruction}}
 
-After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (Phase 1)
+- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
+- [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing all phases above, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 
 {{inlinedTemplates}}

package/src/resources/extensions/gsd/tests/compaction-snapshot.test.ts

@@ -0,0 +1,123 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  buildSnapshot,
+  readCompactionSnapshot,
+  writeCompactionSnapshot,
+  DEFAULT_SNAPSHOT_BYTES,
+} from '../compaction-snapshot.ts';
+import { closeDatabase, openDatabase } from '../gsd-db.ts';
+import { createMemory } from '../memory-store.ts';
+import { executeResume } from '../tools/resume-tool.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-snap-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+test('buildSnapshot: renders memories, exec history, and active context', () => {
+  const snap = buildSnapshot({
+    generatedAt: new Date('2026-04-20T12:00:00.000Z'),
+    activeContext: 'M001 / S01 / T01 — wire gsd_exec',
+    memories: [
+      { id: 'MEM001', category: 'gotcha', content: 'FTS5 needs Porter tokenizer', confidence: 0.9,
+        source_unit_type: null, source_unit_id: null, created_at: '', updated_at: '',
+        superseded_by: null, hit_count: 0, scope: 'project', seq: 1, tags: [], structured_fields: null },
+    ],
+    execHistory: [
+      {
+        id: 'abc',
+        runtime: 'bash',
+        purpose: 'count TODOs',
+        started_at: '', finished_at: '', duration_ms: 10,
+        exit_code: 0, signal: null, timed_out: false,
+        stdout_bytes: 1, stderr_bytes: 0, stdout_truncated: false, stderr_truncated: false,
+        stdout_path: '/tmp/abc.stdout', stderr_path: '/tmp/abc.stderr', meta_path: '/tmp/abc.meta.json',
+      },
+    ],
+  });
+  assert.match(snap, /Active context/);
+  assert.match(snap, /M001 \/ S01 \/ T01/);
+  assert.match(snap, /FTS5 needs Porter tokenizer/);
+  assert.match(snap, /\[abc\] bash exit:0 — count TODOs/);
+});
+
+test('buildSnapshot: enforces the byte cap with a truncation marker', () => {
+  const longMemories = Array.from({ length: 50 }, (_v, i) => ({
+    id: `MEM${String(i).padStart(3, '0')}`,
+    category: 'gotcha',
+    content: 'x'.repeat(200),
+    confidence: 0.8,
+    source_unit_type: null,
+    source_unit_id: null,
+    created_at: '',
+    updated_at: '',
+    superseded_by: null,
+    hit_count: 0,
+    scope: 'project',
+    seq: i,
+    tags: [] as string[],
+    structured_fields: null,
+  }));
+  const snap = buildSnapshot(
+    { generatedAt: new Date(), memories: longMemories, execHistory: [] },
+    { maxBytes: 512, maxMemories: 50 },
+  );
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= 512, 'should respect cap');
+  assert.match(snap, /\[truncated\]/, 'should include truncation marker');
+});
+
+test('buildSnapshot: handles empty state with an explanatory placeholder', () => {
+  const snap = buildSnapshot({ generatedAt: new Date(), memories: [], execHistory: [] });
+  assert.match(snap, /_No durable memories/);
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= DEFAULT_SNAPSHOT_BYTES);
+});
+
+test('writeCompactionSnapshot + readCompactionSnapshot + executeResume: end-to-end', () => {
+  const base = freshBase();
+  try {
+    openDatabase(':memory:');
+    createMemory({ category: 'architecture', content: 'Single-writer DB through gsd-db.ts', confidence: 0.95 });
+    createMemory({ category: 'convention', content: 'Prefer typed helpers over raw SQL', confidence: 0.9 });
+
+    const out = writeCompactionSnapshot(base, { activeContext: 'M099 resume check' });
+    assert.ok(out.path.endsWith('last-snapshot.md'));
+    assert.ok(out.bytes > 0);
+    assert.equal(out.memories, 2);
+
+    const contents = readCompactionSnapshot(base);
+    assert.ok(contents);
+    assert.match(contents!, /Single-writer DB through gsd-db\.ts/);
+    assert.match(contents!, /M099 resume check/);
+
+    const tool = executeResume({}, { baseDir: base });
+    assert.ok(!tool.isError);
+    assert.equal(tool.details.found, true);
+    assert.match(tool.content[0].text, /Single-writer DB through gsd-db\.ts/);
+
+    // also verify the file content matches (without trailing newline)
+    const raw = readFileSync(out.path, 'utf-8');
+    assert.ok(raw.endsWith('\n'));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test('executeResume: reports friendly empty state when no snapshot exists', () => {
+  const base = freshBase();
+  try {
+    const result = executeResume({}, { baseDir: base });
+    assert.equal(result.details.found, false);
+    assert.match(result.content[0].text, /No snapshot found/);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -768,6 +768,37 @@ test("runProviderChecks detects claude.cmd in PATH on Windows (#4503)", { skip:
   });
 });
 
+test("runProviderChecks detects claude.exe in PATH on Windows (#4548)", { skip: process.platform !== "win32" }, () => {
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cc-exe-home-")));
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(binDir, { recursive: true });
+
+  // Some Windows installs ship a direct claude.exe binary (not a .cmd shim).
+  const fakeClaudeExe = join(binDir, "claude.exe");
+  writeFileSync(fakeClaudeExe, "");
+
+  withEnv({
+    HOME: tmpHome,
+    ANTHROPIC_API_KEY: undefined,
+    ANTHROPIC_OAUTH_TOKEN: undefined,
+    COPILOT_GITHUB_TOKEN: undefined,
+    GH_TOKEN: undefined,
+    GITHUB_TOKEN: undefined,
+    PATH: `${binDir};${process.env.PATH ?? ""}`,
+    PATHEXT: ".COM;.EXE;.BAT;.CMD",
+  }, () => {
+    try {
+      const results = runProviderChecks();
+      const anthropic = results.find(r => r.name === "anthropic");
+      assert.ok(anthropic, "anthropic result should exist");
+      assert.equal(anthropic!.status, "ok", "should be ok when claude.exe is in PATH (#4548)");
+      assert.ok(anthropic!.message.toLowerCase().includes("claude"), "should mention claude-code as source");
+    } finally {
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});
+
 test("PROVIDER_ROUTES includes google-gemini-cli as route for google (#2922)", async () => {
   const { readFileSync: readFS } = await import("node:fs");
   const { dirname: dirn, join: joinPath } = await import("node:path");

package/src/resources/extensions/gsd/tests/exec-history.test.ts

@@ -0,0 +1,124 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { listExecHistory, searchExecHistory } from '../exec-history.ts';
+import { executeExecSearch } from '../tools/exec-search-tool.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-exec-history-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function writeRun(base: string, id: string, overrides: Record<string, unknown> = {}): void {
+  const dir = join(base, '.gsd', 'exec');
+  mkdirSync(dir, { recursive: true });
+  const stdoutPath = join(dir, `${id}.stdout`);
+  const stderrPath = join(dir, `${id}.stderr`);
+  const metaPath = join(dir, `${id}.meta.json`);
+  writeFileSync(stdoutPath, (overrides.stdout as string | undefined) ?? `stdout for ${id}\n`);
+  writeFileSync(stderrPath, '');
+  writeFileSync(
+    metaPath,
+    JSON.stringify({
+      id,
+      runtime: 'bash',
+      purpose: `purpose for ${id}`,
+      started_at: '2026-04-20T12:00:00.000Z',
+      finished_at: '2026-04-20T12:00:00.100Z',
+      duration_ms: 100,
+      exit_code: 0,
+      signal: null,
+      timed_out: false,
+      stdout_bytes: 12,
+      stderr_bytes: 0,
+      stdout_truncated: false,
+      stderr_truncated: false,
+      stdout_path: stdoutPath,
+      stderr_path: stderrPath,
+      ...overrides,
+    }),
+  );
+}
+
+test('listExecHistory: returns empty list when .gsd/exec missing', () => {
+  const base = freshBase();
+  try {
+    assert.deepEqual(listExecHistory(base), []);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('listExecHistory: skips malformed meta files', () => {
+  const base = freshBase();
+  try {
+    const dir = join(base, '.gsd', 'exec');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'bad.meta.json'), '{not-json');
+    writeRun(base, 'ok-1');
+    const list = listExecHistory(base);
+    assert.equal(list.length, 1);
+    assert.equal(list[0]!.id, 'ok-1');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('searchExecHistory: filters by query, runtime, and failing_only', () => {
+  const base = freshBase();
+  try {
+    writeRun(base, 'playwright-run', { purpose: 'playwright snapshot' });
+    writeRun(base, 'grep-run', { purpose: 'grep TODOs' });
+    writeRun(base, 'failing-run', { exit_code: 1, purpose: 'boom' });
+    writeRun(base, 'node-run', { runtime: 'node', purpose: 'dedupe' });
+
+    const playwrightHits = searchExecHistory(base, { query: 'playwright' });
+    assert.equal(playwrightHits.length, 1);
+    assert.equal(playwrightHits[0]!.entry.id, 'playwright-run');
+
+    const failingHits = searchExecHistory(base, { failing_only: true });
+    assert.equal(failingHits.length, 1);
+    assert.equal(failingHits[0]!.entry.id, 'failing-run');
+
+    const nodeHits = searchExecHistory(base, { runtime: 'node' });
+    assert.equal(nodeHits.length, 1);
+    assert.equal(nodeHits[0]!.entry.runtime, 'node');
+
+    const unlimited = searchExecHistory(base, {});
+    assert.equal(unlimited.length, 4);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeExecSearch: returns helpful empty-state message when no matches', () => {
+  const base = freshBase();
+  try {
+    const result = executeExecSearch({ query: 'missing' }, { baseDir: base });
+    assert.ok(!result.isError);
+    assert.match(result.content[0].text, /No prior gsd_exec runs/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeExecSearch: includes stdout_path and preview in details', () => {
+  const base = freshBase();
+  try {
+    writeRun(base, 'summary-run', { stdout: 'found 42 TODOs\n' });
+    const result = executeExecSearch({ query: 'summary' }, { baseDir: base });
+    const details = result.details as { results: Array<{ id: string; stdout_path: string }> };
+    assert.equal(details.results.length, 1);
+    assert.equal(details.results[0]!.id, 'summary-run');
+    assert.match(details.results[0]!.stdout_path, /summary-run\.stdout$/);
+    assert.match(result.content[0].text, /found 42 TODOs/);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/exec-sandbox.test.ts

@@ -0,0 +1,210 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { EXEC_DEFAULTS, runExecSandbox, type ExecSandboxOptions } from '../exec-sandbox.ts';
+import { buildExecOptions, executeGsdExec } from '../tools/exec-tool.ts';
+import { isContextModeEnabled } from '../preferences-types.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-exec-test-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function baseOpts(base: string, overrides: Partial<ExecSandboxOptions> = {}): ExecSandboxOptions {
+  return {
+    baseDir: base,
+    clamp_timeout_ms: EXEC_DEFAULTS.clampTimeoutMs,
+    default_timeout_ms: 10_000,
+    stdout_cap_bytes: 1_024,
+    stderr_cap_bytes: 1_024,
+    digest_chars: 120,
+    env_allowlist: EXEC_DEFAULTS.envAllowlist,
+    ...overrides,
+  };
+}
+
+test('runExecSandbox: captures stdout, persists artifacts, returns digest', async () => {
+  const base = freshBase();
+  try {
+    const result = await runExecSandbox(
+      { runtime: 'bash', script: 'echo hello world' },
+      baseOpts(base),
+    );
+    assert.equal(result.exit_code, 0);
+    assert.equal(result.timed_out, false);
+    assert.ok(result.digest.includes('hello world'), `digest should contain stdout: ${result.digest}`);
+    assert.ok(result.stdout_path.startsWith(join(base, '.gsd', 'exec')), 'stdout path under .gsd/exec');
+    assert.equal(readFileSync(result.stdout_path, 'utf-8').trim(), 'hello world');
+    const meta = JSON.parse(readFileSync(result.meta_path, 'utf-8')) as Record<string, unknown>;
+    assert.equal(meta.runtime, 'bash');
+    assert.equal(meta.exit_code, 0);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('runExecSandbox: enforces stdout cap and marks truncation', async () => {
+  const base = freshBase();
+  try {
+    const result = await runExecSandbox(
+      // Emit far more than the cap so truncation triggers.
+      { runtime: 'bash', script: 'head -c 8000 /dev/urandom | base64' },
+      baseOpts(base, { stdout_cap_bytes: 256 }),
+    );
+    assert.equal(result.stdout_truncated, true, 'should mark stdout truncated');
+    assert.ok(result.stdout_bytes <= 256, `stdout_bytes within cap (got ${result.stdout_bytes})`);
+    const stdout = readFileSync(result.stdout_path, 'utf-8');
+    assert.ok(stdout.endsWith('[truncated: stdout cap reached]\n'), 'truncation marker appended');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('runExecSandbox: enforces timeout and surfaces timed_out', async () => {
+  const base = freshBase();
+  try {
+    const started = Date.now();
+    const result = await runExecSandbox(
+      { runtime: 'bash', script: 'sleep 10' },
+      baseOpts(base, { default_timeout_ms: 150, clamp_timeout_ms: 150 }),
+    );
+    const elapsed = Date.now() - started;
+    assert.equal(result.timed_out, true);
+    assert.ok(elapsed < 5_000, `should return well before 10s (took ${elapsed}ms)`);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('runExecSandbox: forwards only allowlisted env vars', async () => {
+  const base = freshBase();
+  try {
+    const result = await runExecSandbox(
+      { runtime: 'bash', script: 'echo PATH=$PATH SECRET=$GSD_TEST_SECRET' },
+      baseOpts(base, {
+        env_allowlist: [],
+        env: { PATH: '/usr/bin:/bin', HOME: '/tmp', GSD_TEST_SECRET: 'should-be-blocked' },
+      }),
+    );
+    const stdout = readFileSync(result.stdout_path, 'utf-8');
+    assert.ok(stdout.includes('PATH=/usr/bin:/bin'), 'PATH forwarded');
+    assert.ok(!stdout.includes('should-be-blocked'), 'non-allowlisted var blocked');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('runExecSandbox: node runtime executes JS', async () => {
+  const base = freshBase();
+  try {
+    const result = await runExecSandbox(
+      { runtime: 'node', script: 'console.log("node-ok:" + (1+2))' },
+      baseOpts(base),
+    );
+    assert.equal(result.exit_code, 0);
+    assert.ok(result.digest.includes('node-ok:3'));
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ── exec-tool executor ────────────────────────────────────────────────────
+
+test('executeGsdExec: runs by default when context_mode is unset', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      { runtime: 'bash', script: 'echo default-on-run' },
+      { baseDir: base, preferences: {} },
+    );
+    assert.ok(!result.isError, 'should succeed with no preferences');
+    assert.equal(result.details.operation, 'gsd_exec');
+    assert.equal(result.details.exit_code, 0);
+    assert.ok(result.content[0].text.includes('default-on-run'));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeGsdExec: runs when preferences is null (fresh project)', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      { runtime: 'bash', script: 'echo null-prefs-run' },
+      { baseDir: base, preferences: null },
+    );
+    assert.ok(!result.isError, 'null preferences should not disable');
+    assert.ok(result.content[0].text.includes('null-prefs-run'));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeGsdExec: blocked only when context_mode.enabled=false', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      { runtime: 'bash', script: 'echo should-not-run' },
+      { baseDir: base, preferences: { context_mode: { enabled: false } } },
+    );
+    assert.equal(result.isError, true);
+    assert.equal((result.details as { error?: string }).error, 'context_mode_disabled');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeGsdExec: runs when enabled explicitly set to true', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      { runtime: 'bash', script: 'echo explicit-on' },
+      { baseDir: base, preferences: { context_mode: { enabled: true } } },
+    );
+    assert.ok(!result.isError);
+    assert.ok(result.content[0].text.includes('explicit-on'));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeGsdExec: rejects empty script', async () => {
+  const base = freshBase();
+  try {
+    const result = await executeGsdExec(
+      { runtime: 'bash', script: '   ' },
+      { baseDir: base, preferences: { context_mode: { enabled: true } } },
+    );
+    assert.equal(result.isError, true);
+    assert.equal((result.details as { error?: string }).error, 'invalid_params');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('isContextModeEnabled: defaults to true; only explicit false disables', () => {
+  assert.equal(isContextModeEnabled(undefined), true, 'undefined prefs → on');
+  assert.equal(isContextModeEnabled(null), true, 'null prefs → on');
+  assert.equal(isContextModeEnabled({}), true, 'empty prefs → on');
+  assert.equal(isContextModeEnabled({ context_mode: {} }), true, 'empty block → on');
+  assert.equal(isContextModeEnabled({ context_mode: { enabled: true } }), true);
+  assert.equal(isContextModeEnabled({ context_mode: { enabled: false } }), false);
+});
+
+test('buildExecOptions: clamps out-of-range values to safe defaults', () => {
+  const opts = buildExecOptions('/tmp/base', {
+    enabled: true,
+    exec_timeout_ms: 999_999_999,
+    exec_stdout_cap_bytes: 1,
+    exec_digest_chars: -20,
+  });
+  assert.equal(opts.default_timeout_ms, EXEC_DEFAULTS.clampTimeoutMs, 'timeout clamped to upper bound');
+  assert.equal(opts.stdout_cap_bytes, 4_096, 'stdout cap clamped to floor');
+  assert.equal(opts.digest_chars, 0, 'digest chars clamped to floor');
+});