@shogo-ai/worker 1.7.4 → 1.7.7

package/src/lib/__tests__/runtime-manager-auto-pull.test.ts

@@ -0,0 +1,275 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Tests for the `WorkerRuntimeManager` auto-pull hook (Chunk E of the
+ * project-pull feature).
+ *
+ * We exercise the path via the public `ensurePulled(projectId, config)`
+ * entry point so we don't have to spawn an actual agent-runtime binary.
+ * The internal CloudFileTransport is exercised end-to-end against a fake
+ * `fetch` that scripts the manifest + presign + download responses.
+ *
+ * Coverage:
+ *   - autoPull disabled → no clone, projectDir not injected
+ *   - autoPull enabled + empty target dir → clone runs, projectDir set
+ *   - autoPull enabled + populated target dir → no clone (skip)
+ *   - autoPull enabled + cloud failure → soft-fail, projectDir still set
+ *   - second call for same projectId is short-circuited (idempotent)
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// We need to inject a fake fetch into the global so the SDK's
+// CloudFileTransport picks it up.
+let scriptedFetch: typeof fetch | null = null;
+const originalFetch = globalThis.fetch;
+beforeEach(() => {
+  globalThis.fetch = ((input: any, init?: RequestInit) => {
+    if (!scriptedFetch) throw new Error('no scripted fetch set');
+    return scriptedFetch(input, init);
+  }) as any;
+});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  scriptedFetch = null;
+});
+
+function scriptManifest(files: Array<{ path: string; size: number; content: string }>) {
+  return (async (input: any, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input.url;
+    if (url.includes('/workspace/manifest')) {
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          projectId: 'p',
+          source: 's3',
+          generatedAt: '',
+          files: files.map((f) => ({ path: f.path, size: f.size, lastModified: null, etag: null })),
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      );
+    }
+    if (url.includes('/s3/presign')) {
+      const body = JSON.parse((init?.body as string) || '{}') as { files: Array<{ path: string; action: string }> };
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          urls: body.files.map((f) => ({ path: f.path, action: f.action, url: `https://dl.test/${f.path}` })),
+        }),
+        { status: 200 },
+      );
+    }
+    if (url.startsWith('https://dl.test/')) {
+      const path = url.slice('https://dl.test/'.length);
+      const file = files.find((f) => f.path === path);
+      if (!file) return new Response('not found', { status: 404 });
+      return new Response(file.content, { status: 200 });
+    }
+    return new Response('unhandled', { status: 500 });
+  }) as unknown as typeof fetch;
+}
+
+describe('WorkerRuntimeManager auto-pull', () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'wrm-auto-pull-'));
+  });
+  afterEach(() => {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it('throws a loud, multi-line error when auto-pull is disabled and no workspace was pre-pulled', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    scriptedFetch = scriptManifest([{ path: 'a.ts', size: 1, content: 'A' }]);
+
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: false, projectsDir: dir },
+    });
+
+    let caught: Error | null = null;
+    try {
+      await mgr.ensurePulled('proj-1', {
+        cloudUrl: 'https://api.test',
+        apiKey: 'shogo_sk_x',
+      });
+    } catch (err: any) {
+      caught = err;
+    }
+
+    expect(caught).not.toBeNull();
+    const msg = caught!.message;
+    // Multi-line so a future debugger reading the worker's stderr can
+    // see the full menu of fixes without log archaeology.
+    expect(msg.split('\n').length).toBeGreaterThan(5);
+    expect(msg).toContain('auto-pull was disabled');
+    expect(msg).toContain('--no-auto-pull');
+    expect(msg).toContain('shogo project pull');
+    expect(msg).toContain('--projects-dir');
+    expect(msg).toContain('SHOGO_PROJECTS_DIR');
+    expect(msg).toContain(join(dir, 'proj-1'));
+    expect(msg).toContain('https://shogo.ai/docs/self-hosted-worker');
+
+    // The ask was loud-failure, not silent-mkdir: the dir must NOT have
+    // been touched (so a follow-up `shogo project pull` lands cleanly).
+    expect(existsSync(join(dir, 'proj-1'))).toBe(false);
+  });
+
+  it('honours a pre-pulled workspace when auto-pull is disabled', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    // No scripted fetch — the manager must NOT try to clone.
+    scriptedFetch = (async () => {
+      throw new Error('auto-pull is disabled, no fetch should fire');
+    }) as unknown as typeof fetch;
+
+    const target = join(dir, 'proj-prepulled');
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, 'AGENTS.md'), 'pre-pulled by `shogo project pull`');
+
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: false, projectsDir: dir },
+    });
+    const result = await mgr.ensurePulled('proj-prepulled', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(result.projectDir).toBe(target);
+    expect(readFileSync(join(target, 'AGENTS.md'), 'utf-8')).toBe(
+      'pre-pulled by `shogo project pull`',
+    );
+  });
+
+  it('throws when no autoPull config and no caller-provided projectDir', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+
+    const mgr = new WorkerRuntimeManager({});
+
+    let caught: Error | null = null;
+    try {
+      await mgr.ensurePulled('proj-x', {
+        cloudUrl: 'https://api.test',
+        apiKey: 'shogo_sk_x',
+      });
+    } catch (err: any) {
+      caught = err;
+    }
+
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('without an `autoPull` config');
+  });
+
+  it('honours an existing caller-provided projectDir without touching autoPull', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    scriptedFetch = (async () => {
+      throw new Error('caller-provided projectDir — no fetch should fire');
+    }) as unknown as typeof fetch;
+
+    const target = join(dir, 'desktop-managed');
+    mkdirSync(target, { recursive: true });
+
+    const mgr = new WorkerRuntimeManager({
+      // autoPull intentionally omitted — desktop adapter case.
+    });
+    const result = await mgr.ensurePulled('proj-desktop', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+      projectDir: target,
+    });
+
+    expect(result.projectDir).toBe(target);
+  });
+
+  it('clones into <projectsDir>/<projectId> when the dir is empty', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    scriptedFetch = scriptManifest([
+      { path: 'config.json', size: 2, content: '{}' },
+      { path: 'AGENTS.md', size: 5, content: 'AGENT' },
+    ]);
+
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: false },
+    });
+    const result = await mgr.ensurePulled('proj-2', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(result.projectDir).toBe(join(dir, 'proj-2'));
+    expect(existsSync(join(dir, 'proj-2', 'config.json'))).toBe(true);
+    expect(readFileSync(join(dir, 'proj-2', 'config.json'), 'utf-8')).toBe('{}');
+    expect(readFileSync(join(dir, 'proj-2', 'AGENTS.md'), 'utf-8')).toBe('AGENT');
+  });
+
+  it('skips clone when the target directory already has files', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    const target = join(dir, 'proj-3');
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, 'config.json'), '{"existing": true}');
+
+    // Set the manifest to return a different file — if clone runs, it would
+    // overwrite. Use atomic-replace semantics from downloadAll() so we'd
+    // see the existing file blown away. We assert it's preserved.
+    scriptedFetch = scriptManifest([{ path: 'fresh.md', size: 5, content: 'NEW' }]);
+
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: false },
+    });
+    const result = await mgr.ensurePulled('proj-3', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(result.projectDir).toBe(target);
+    expect(existsSync(join(target, 'fresh.md'))).toBe(false);
+    expect(readFileSync(join(target, 'config.json'), 'utf-8')).toBe('{"existing": true}');
+  });
+
+  it('soft-fails when the cloud is unreachable, still sets projectDir', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    // Manifest returns 500 — autoPull should swallow and continue.
+    scriptedFetch = (async () => new Response('boom', { status: 500 })) as unknown as typeof fetch;
+
+    const warnings: string[] = [];
+    const logger = {
+      log: () => {},
+      warn: (...args: any[]) => warnings.push(args.join(' ')),
+      error: () => {},
+    };
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, logger, useGit: false },
+    });
+    const result = await mgr.ensurePulled('proj-4', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(result.projectDir).toBe(join(dir, 'proj-4'));
+    expect(warnings.some((w) => w.includes('auto-pull: failed for proj-4'))).toBe(true);
+  });
+
+  it('is idempotent — second call short-circuits the manifest fetch', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    let manifestRequests = 0;
+    scriptedFetch = (async (input: any, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input.url;
+      if (url.includes('/workspace/manifest')) {
+        manifestRequests++;
+        return new Response(JSON.stringify({ ok: true, files: [], source: 's3', generatedAt: '' }), { status: 200 });
+      }
+      return new Response('', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: false },
+    });
+    const config = { cloudUrl: 'https://api.test', apiKey: 'shogo_sk_x' };
+    await mgr.ensurePulled('proj-5', config);
+    await mgr.ensurePulled('proj-5', config);
+    await mgr.ensurePulled('proj-5', config);
+
+    expect(manifestRequests).toBe(1);
+  });
+});

package/src/lib/__tests__/runtime-manager-describe-rejection.test.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Coverage for `WorkerRuntimeManager.describeRejection` — the
+ * structured-rejection hook that the {@link WorkerTunnel} reads when
+ * `resolveLocalUrl` returns null.
+ *
+ * The tunnel echoes the returned `code` + `message` (plus the original
+ * path) into the 502 body so a Studio client reading the response can
+ * tell exactly what the worker refused to do. This file pins the wire
+ * shape so a future refactor doesn't silently change the body Studio
+ * relies on.
+ */
+import { describe, expect, it } from 'bun:test';
+import { WorkerRuntimeManager } from '../runtime-manager.ts';
+
+describe('WorkerRuntimeManager.describeRejection', () => {
+  it('flags non-/agent paths with CLI_WORKER_HAS_NO_DATA_API and the original path', () => {
+    const mgr = new WorkerRuntimeManager({});
+    const r = mgr.describeRejection('/api/projects?workspaceId=abc', 'p-1');
+    expect(r.code).toBe('CLI_WORKER_HAS_NO_DATA_API');
+    // Path in the message must be the pathname only — `?workspaceId=abc`
+    // is verbose and the tunnel echoes the full path separately.
+    expect(r.message).toContain('/api/projects');
+    expect(r.message).toContain('cli-worker only serves /agent/* paths');
+  });
+
+  it('flags /agent paths missing a project context with CLI_WORKER_NO_PROJECT_FOR_PATH', () => {
+    const mgr = new WorkerRuntimeManager({});
+    const r = mgr.describeRejection('/agent/chat', undefined);
+    expect(r.code).toBe('CLI_WORKER_NO_PROJECT_FOR_PATH');
+    expect(r.message).toContain('/agent/chat');
+    expect(r.message).toContain('projectId=none');
+  });
+
+  it('preserves the projectId when one is provided but no runtime exists', () => {
+    const mgr = new WorkerRuntimeManager({});
+    const r = mgr.describeRejection('/agent/chat', 'proj-42');
+    expect(r.code).toBe('CLI_WORKER_NO_PROJECT_FOR_PATH');
+    expect(r.message).toContain('projectId=proj-42');
+  });
+});

package/src/lib/__tests__/runtime-manager-git-pull.test.ts

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Tests for the GIT-mode branch of `WorkerRuntimeManager.maybeAutoPull`.
+ *
+ * Strategy:
+ *   - Mock `../git-cloner` so `cloneProject()` doesn't actually spawn git.
+ *   - Mock `globalThis.fetch` for the `.shogo/` SQLite top-up pass and
+ *     the manifest endpoint.
+ *   - Assert that:
+ *       * a fresh project triggers `cloneProject()`
+ *       * the `.shogo/` top-up issues a manifest+download for only those entries
+ *       * a populated `.git/` dir skips re-clone
+ *       * cloneProject failure flips the mode to 'files' and runs the
+ *         file-transport fallback
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ─── git-cloner fakes injected via `autoPull.gitOps` ────────────────
+type CloneCall = { apiUrl: string; apiKey: string; projectId: string; localDir: string; shallow?: boolean };
+const cloneCalls: CloneCall[] = [];
+let cloneShouldThrow = false;
+const gitOps = {
+  cloneProject: async (opts: CloneCall) => {
+    cloneCalls.push(opts);
+    if (cloneShouldThrow) throw new Error('simulated clone failure');
+    mkdirSync(join(opts.localDir, '.git'), { recursive: true });
+    writeFileSync(join(opts.localDir, 'AGENTS.md'), 'AGENT');
+    return { commitSha: 'deadbeef' };
+  },
+  gitIsAvailable: async () => true,
+  isGitRepo: (dir: string) => existsSync(join(dir, '.git')),
+};
+
+// ─── fetch shim ────────────────────────────────────────────────────
+let scriptedFetch: typeof fetch | null = null;
+const originalFetch = globalThis.fetch;
+beforeEach(() => {
+  cloneCalls.length = 0;
+  cloneShouldThrow = false;
+  globalThis.fetch = ((input: any, init?: RequestInit) => {
+    if (!scriptedFetch) throw new Error('no scripted fetch set');
+    return scriptedFetch(input, init);
+  }) as any;
+});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  scriptedFetch = null;
+});
+
+function scriptShogoTopup(files: Array<{ path: string; content: string }>) {
+  return (async (input: any, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input.url;
+    if (url.includes('/workspace/manifest')) {
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          projectId: 'p',
+          source: 's3',
+          generatedAt: '',
+          files: files.map((f) => ({ path: f.path, size: f.content.length, lastModified: null, etag: null })),
+        }),
+        { status: 200 },
+      );
+    }
+    if (url.includes('/s3/presign')) {
+      const body = JSON.parse((init?.body as string) || '{}') as { files: Array<{ path: string; action: string }> };
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          urls: body.files.map((f) => ({ path: f.path, action: f.action, url: `https://dl.test/${encodeURIComponent(f.path)}` })),
+        }),
+        { status: 200 },
+      );
+    }
+    if (url.startsWith('https://dl.test/')) {
+      const path = decodeURIComponent(url.slice('https://dl.test/'.length));
+      const file = files.find((f) => f.path === path);
+      return file
+        ? new Response(file.content, { status: 200 })
+        : new Response('not found', { status: 404 });
+    }
+    return new Response('unhandled', { status: 500 });
+  }) as unknown as typeof fetch;
+}
+
+describe('WorkerRuntimeManager auto-pull (git mode)', () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'wrm-git-pull-'));
+  });
+  afterEach(() => {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  it('clones via git when git is available and the dir is empty', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    scriptedFetch = scriptShogoTopup([]); // no .shogo entries
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: true, gitOps },
+    });
+    const result = await mgr.ensurePulled('proj-g1', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(result.projectDir).toBe(join(dir, 'proj-g1'));
+    expect(cloneCalls.length).toBe(1);
+    expect(cloneCalls[0]!.projectId).toBe('proj-g1');
+    expect(cloneCalls[0]!.localDir).toBe(join(dir, 'proj-g1'));
+    expect(cloneCalls[0]!.shallow).toBe(true);
+    // The stub created AGENTS.md.
+    expect(existsSync(join(dir, 'proj-g1', 'AGENTS.md'))).toBe(true);
+  });
+
+  it('downloads .shogo/* via the file transport after a successful git clone', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    scriptedFetch = scriptShogoTopup([
+      { path: '.shogo/db.sqlite', content: 'SQLITE-DB' },
+      { path: '.shogo/snapshots/2024.sqlite', content: 'SNAP' },
+      // non-.shogo entries in the manifest must be ignored by the top-up.
+      { path: 'src/App.tsx', content: 'APP' },
+    ]);
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: true, gitOps },
+    });
+    await mgr.ensurePulled('proj-g2', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(cloneCalls.length).toBe(1);
+    const target = join(dir, 'proj-g2');
+    // .shogo/* was downloaded via the file transport.
+    expect(existsSync(join(target, '.shogo', 'db.sqlite'))).toBe(true);
+    expect(existsSync(join(target, '.shogo', 'snapshots', '2024.sqlite'))).toBe(true);
+    // src/App.tsx was NOT downloaded — git handles that.
+    expect(existsSync(join(target, 'src', 'App.tsx'))).toBe(false);
+  });
+
+  it('skips re-cloning when the local dir already has a .git/', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    const target = join(dir, 'proj-g3');
+    mkdirSync(join(target, '.git'), { recursive: true });
+    writeFileSync(join(target, 'AGENTS.md'), 'existing');
+
+    scriptedFetch = scriptShogoTopup([]); // top-up still fires but is a no-op
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: true, gitOps },
+    });
+    await mgr.ensurePulled('proj-g3', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(cloneCalls.length).toBe(0);
+    // Existing content is preserved.
+    expect(existsSync(join(target, 'AGENTS.md'))).toBe(true);
+  });
+
+  it('falls back to file transport when cloneProject throws', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    cloneShouldThrow = true;
+    // Manifest serves a real file so the fallback downloadAll can produce something.
+    scriptedFetch = scriptShogoTopup([
+      { path: 'fallback.txt', content: 'FROM-FILES' },
+    ]);
+    const warnings: string[] = [];
+    const logger = {
+      log: () => {},
+      warn: (...args: any[]) => warnings.push(args.join(' ')),
+      error: () => {},
+    };
+
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: true, logger, gitOps },
+    });
+    await mgr.ensurePulled('proj-g4', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+
+    expect(cloneCalls.length).toBe(1);
+    expect(warnings.some((w) => w.includes('git clone failed'))).toBe(true);
+    expect(existsSync(join(dir, 'proj-g4', 'fallback.txt'))).toBe(true);
+  });
+
+  it('uses file transport (not git) when useGit=false', async () => {
+    const { WorkerRuntimeManager } = await import('../runtime-manager.ts');
+    scriptedFetch = scriptShogoTopup([
+      { path: 'plain.txt', content: 'P' },
+    ]);
+    const mgr = new WorkerRuntimeManager({
+      autoPull: { enabled: true, projectsDir: dir, watch: false, useGit: false, gitOps },
+    });
+    await mgr.ensurePulled('proj-g5', {
+      cloudUrl: 'https://api.test',
+      apiKey: 'shogo_sk_x',
+    });
+    expect(cloneCalls.length).toBe(0);
+    expect(existsSync(join(dir, 'proj-g5', 'plain.txt'))).toBe(true);
+  });
+});

package/src/lib/__tests__/runtime-manager-tree-sitter-env.test.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Tests for the belt-and-suspenders `TREE_SITTER_WASM_DIR` injection
+ * added to `WorkerRuntimeManager.buildEnv` in PR #2 ("Bundle tree-
+ * sitter WASMs alongside compiled agent-runtime binary").
+ *
+ * The contract we verify:
+ *
+ *   1. When the worker spawns an `agent-runtime` binary at
+ *      `/path/to/shogo-agent-runtime`, the spawn env contains
+ *      `TREE_SITTER_WASM_DIR=/path/to/tree-sitter-wasm`. Operators
+ *      who run `env | grep TREE_SITTER` on a debugging session see
+ *      exactly where the runtime is configured to look.
+ *
+ *   2. An operator-provided override on the worker host
+ *      (`process.env.TREE_SITTER_WASM_DIR=/custom/path`) flows
+ *      through to the spawned runtime — `buildEnv` does NOT clobber
+ *      a pre-existing env value. The runtime's resolver also reads
+ *      the env first, so the override stack-traces correctly.
+ *
+ *   3. When a per-project `extraEnv` block sets the same variable,
+ *      the per-project value wins over both the inherited env and
+ *      the binary-adjacent default. (extraEnv is documented as the
+ *      last-merged layer; we keep that invariant.)
+ *
+ * `buildEnv` is a private method. We invoke it via a typed cast —
+ * the same pattern other tests in this directory use for accessing
+ * private internals (`runtime-manager-describe-rejection.test.ts`).
+ * The signature of `buildEnv(slot, runtimeBinPath)` is exercised
+ * directly with a synthesized `slot` rather than going through the
+ * full spawn pipeline, because the spawn pipeline requires a real
+ * binary on disk. The test surface is the env-shape contract, not
+ * the spawn-orchestration logic (which is covered elsewhere).
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { dirname, join } from 'node:path';
+import { WorkerRuntimeManager } from '../runtime-manager';
+
+/**
+ * Construct a fake `InternalRuntime` slot just rich enough for
+ * `buildEnv` to read every field it touches. Mirrors the shape of
+ * `InternalRuntime` in runtime-manager.ts; if that shape grows new
+ * fields used by buildEnv, this fixture must follow.
+ */
+function fakeSlot(overrides: Record<string, unknown> = {}): unknown {
+  return {
+    projectId: 'proj-tree-sitter-env-test',
+    agentPort: 41000,
+    apiServerPort: 41100,
+    spawnConfig: {
+      cloudUrl: 'https://cloud.test',
+      apiKey: 'api-key',
+      ...((overrides.spawnConfig as Record<string, unknown>) ?? {}),
+    },
+    ...overrides,
+  };
+}
+
+describe('WorkerRuntimeManager.buildEnv — TREE_SITTER_WASM_DIR injection', () => {
+  it('exports TREE_SITTER_WASM_DIR=dirname(runtimeBinPath)/tree-sitter-wasm by default', () => {
+    const mgr = new WorkerRuntimeManager({
+      env: {} as NodeJS.ProcessEnv, // start from a clean env so we can isolate the injection
+    }) as unknown as { buildEnv(slot: unknown, runtimeBinPath: string): NodeJS.ProcessEnv };
+
+    const runtimeBinPath = '/opt/shogo/runtime/shogo-agent-runtime-linux-x64';
+    const env = mgr.buildEnv(fakeSlot(), runtimeBinPath);
+
+    expect(env.TREE_SITTER_WASM_DIR).toBe(join(dirname(runtimeBinPath), 'tree-sitter-wasm'));
+    expect(env.TREE_SITTER_WASM_DIR).toBe('/opt/shogo/runtime/tree-sitter-wasm');
+  });
+
+  it('honors a worker-host override when process.env already sets TREE_SITTER_WASM_DIR', () => {
+    const mgr = new WorkerRuntimeManager({
+      env: {
+        TREE_SITTER_WASM_DIR: '/operator/override/path',
+      } as NodeJS.ProcessEnv,
+    }) as unknown as { buildEnv(slot: unknown, runtimeBinPath: string): NodeJS.ProcessEnv };
+
+    const env = mgr.buildEnv(fakeSlot(), '/opt/shogo/runtime/shogo-agent-runtime-linux-x64');
+    expect(env.TREE_SITTER_WASM_DIR).toBe('/operator/override/path');
+  });
+
+  it('per-project extraEnv override beats both worker-host env and binary-adjacent default', () => {
+    const mgr = new WorkerRuntimeManager({
+      env: {
+        TREE_SITTER_WASM_DIR: '/worker/host/path',
+      } as NodeJS.ProcessEnv,
+    }) as unknown as { buildEnv(slot: unknown, runtimeBinPath: string): NodeJS.ProcessEnv };
+
+    const env = mgr.buildEnv(
+      fakeSlot({
+        spawnConfig: {
+          cloudUrl: 'https://cloud.test',
+          apiKey: 'api-key',
+          extraEnv: { TREE_SITTER_WASM_DIR: '/per/project/override' },
+        },
+      }),
+      '/opt/shogo/runtime/shogo-agent-runtime-linux-x64',
+    );
+    expect(env.TREE_SITTER_WASM_DIR).toBe('/per/project/override');
+  });
+
+  it('preserves the cli-worker contract: PROJECT_ID, PORT, SHOGO_API_KEY co-exist with TREE_SITTER_WASM_DIR', () => {
+    // Drive-by: assert injecting the new variable doesn't clobber the
+    // existing env keys. Reduces blast radius if a future refactor of
+    // buildEnv reorders the assignments.
+    const mgr = new WorkerRuntimeManager({
+      env: {} as NodeJS.ProcessEnv,
+    }) as unknown as { buildEnv(slot: unknown, runtimeBinPath: string): NodeJS.ProcessEnv };
+
+    const env = mgr.buildEnv(
+      fakeSlot({ projectId: 'co-exist-check', agentPort: 42424, apiServerPort: 42525 }),
+      '/runtime/shogo-agent-runtime',
+    );
+
+    expect(env.PROJECT_ID).toBe('co-exist-check');
+    expect(env.PORT).toBe('42424');
+    expect(env.API_SERVER_PORT).toBe('42525');
+    expect(env.SHOGO_API_KEY).toBe('api-key');
+    expect(env.TREE_SITTER_WASM_DIR).toBe('/runtime/tree-sitter-wasm');
+  });
+});