@shogo-ai/worker 1.7.4 → 1.7.7

package/src/lib/runtime-manager.ts

@@ -33,11 +33,14 @@
  */
 import { type ChildProcess, spawn } from 'node:child_process';
 import { createHmac, randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { resolveRuntime, type ResolvedRuntime } from './runtime-resolver.ts';
-import type { RuntimeResolver } from './tunnel.ts';
+import type { ResolveRejection, RuntimeResolver } from './tunnel.ts';
+import { CloudFileTransport } from '@shogo-ai/sdk';
+import { CloudSyncWatcher } from './cloud-sync-watcher.ts';
+import { cloneProject, gitIsAvailable, isGitRepo } from './git-cloner.ts';
 
 /** Port range for random allocation (mirrors apps/api desktop manager). */
 const PORT_RANGE_START = 37100;
@@ -83,8 +86,6 @@ export interface ProjectSpawnConfig {
   aiProxyToken?: string;
   /** Tech-stack id (for runtime to seed correct template if PROJECT_DIR is empty). */
   techStackId?: string;
-  /** Template id passed through to the runtime. */
-  templateId?: string;
   /** Friendly project name. */
   name?: string;
   /** Workspace id for this project. */
@@ -149,8 +150,55 @@ export interface WorkerRuntimeManagerOptions {
    * Prisma-derived secrets (AI proxy token, security policy, etc.).
    */
   enrichSpawnConfig?: (projectId: string, base: ProjectSpawnConfig) => Promise<ProjectSpawnConfig>;
+  /**
+   * Auto-pull configuration. When enabled, the manager will clone a
+   * project's workspace from Shogo Cloud into `<projectsDir>/<projectId>/`
+   * on first request, then keep edits in sync via a {@link CloudSyncWatcher}.
+   *
+   * This is what makes "pin a staging project to a paired VPS, send a
+   * webhook" work end-to-end without the user manually running
+   * `shogo project pull` first.
+   */
+  autoPull?: AutoPullOptions;
+}
+
+export interface AutoPullOptions {
+  /** Master switch. Defaults to false; the `worker start` command flips
+   *  it on for `cli_worker` instances unless `--no-auto-pull` is passed. */
+  enabled: boolean;
+  /** Directory under which each project's workspace lives. Required when enabled. */
+  projectsDir: string;
+  /** Watch the pulled workspace and push edits back to cloud. Default: true. */
+  watch?: boolean;
+  /**
+   * Prefer the git smart-HTTP backend over the file transport for the
+   * initial clone and the watcher's flush path. Defaults to `true`:
+   * the worker will probe `git --version` and fall back to the file
+   * transport if git isn't installed. Set to `false` (via `--no-git` on
+   * `worker start`) to force the file-transport path even when git is
+   * available — useful for environments where outbound HTTPS to git's
+   * pack RPC endpoints is blocked at the firewall.
+   */
+  useGit?: boolean;
+  /** Optional logger. Defaults to the manager's logger. */
+  logger?: Pick<Console, 'log' | 'warn' | 'error'>;
+  /** Test seam: swap in fakes for the git-cloner ops without resorting
+   *  to module-level mocking (which leaks across bun:test files). Each
+   *  field falls back to the real implementation when not provided. */
+  gitOps?: Partial<GitOpsAdapter>;
 }
 
+/** Subset of git-cloner that the runtime-manager actually calls. */
+export interface GitOpsAdapter {
+  cloneProject: typeof cloneProject;
+  gitIsAvailable: typeof gitIsAvailable;
+  isGitRepo: typeof isGitRepo;
+}
+
+/** Per-project sync strategy. Recorded so the watcher (or stopAll) can
+ *  branch on it without re-probing `git --version`. */
+export type SyncMode = 'git' | 'files';
+
 /** Internal per-project runtime record. */
 interface InternalRuntime {
   projectId: string;
@@ -203,6 +251,81 @@ function splitPathAndQuery(pathWithQuery: string): { pathname: string; search: s
   return { pathname: pathWithQuery.slice(0, q), search: pathWithQuery.slice(q) };
 }
 
+/** True if the directory exists and contains no entries (or doesn't exist). */
+function isDirEmpty(dir: string): boolean {
+  try {
+    const entries = readdirSync(dir);
+    return entries.length === 0;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Render the operator-facing multi-line error the worker raises when it
+ * cannot determine a real on-disk workspace for a project.
+ *
+ * Why it's verbose: every branch here represents a real misconfig the
+ * operator has to fix before the worker can serve traffic, and the
+ * runtime's own `WORKSPACE_DIR fell back to '/app/workspace'` warning
+ * is only visible in the spawned child's stderr (often hidden behind
+ * the worker's logging seam). Surfacing the full menu of fixes — flag,
+ * env var, manual `shogo project pull` — at the throw site means an
+ * operator's first sight of the failure is also their fix.
+ */
+export function formatWorkspaceMisconfigError(
+  projectId: string,
+  reason: 'no-auto-pull-config' | 'no-projects-dir' | 'auto-pull-disabled',
+  expectedDir: string | null,
+): string {
+  const lines: string[] = [];
+  lines.push(`Cannot spawn agent-runtime for project ${projectId}: no workspace directory available.`);
+  lines.push('');
+  switch (reason) {
+    case 'no-auto-pull-config':
+      lines.push(
+        '  Reason: WorkerRuntimeManager was constructed without an `autoPull` config and ' +
+          'no caller-provided `projectDir` was found on disk.',
+      );
+      lines.push(
+        '          This usually means a programmatic embedder forgot to wire up enrichSpawnConfig ' +
+          'or autoPull. CLI users should not see this — please file a bug.',
+      );
+      break;
+    case 'no-projects-dir':
+      lines.push(
+        '  Reason: auto-pull is configured but `projectsDir` is empty. The worker needs a ' +
+          'persistent root directory under which it can store cloned project workspaces.',
+      );
+      break;
+    case 'auto-pull-disabled':
+      lines.push(
+        '  Reason: auto-pull was disabled (--no-auto-pull) and the expected pre-pulled ' +
+          `workspace at ${expectedDir} is missing or empty.`,
+      );
+      break;
+  }
+  lines.push('');
+  lines.push('  How to fix (pick one):');
+  lines.push('    1. Re-enable auto-pull (default).  Drop the --no-auto-pull flag and restart');
+  lines.push('       the worker.  The first inbound request for this project will clone its');
+  lines.push('       workspace from Shogo Cloud into <projectsDir>/<projectId>/.');
+  lines.push('');
+  lines.push('    2. Pre-pull manually with `shogo project pull <projectId>` before starting');
+  lines.push('       the worker.  Use this when you want full control over when the clone runs');
+  lines.push('       (slow links, scheduled maintenance windows, etc.).');
+  lines.push('');
+  lines.push('    3. Point the worker at an existing workspace by setting either:');
+  lines.push('         --projects-dir <path>           (per-invocation flag)');
+  lines.push('         SHOGO_PROJECTS_DIR=<path>       (env var, persists across restarts)');
+  lines.push('         shogo config set projectsDir <path>');
+  lines.push('       Whichever path you pick must contain a subdirectory named after the ');
+  lines.push(`       project id (e.g. <path>/${projectId}/) populated with the project's source.`);
+  lines.push('');
+  lines.push('  Docs: https://shogo.ai/docs/self-hosted-worker#workspace-seeding');
+  return lines.join('\n');
+}
+
 export class WorkerRuntimeManager implements RuntimeResolver {
   private readonly opts: WorkerRuntimeManagerOptions;
   private readonly log: Pick<Console, 'log' | 'warn' | 'error'>;
@@ -212,6 +335,14 @@ export class WorkerRuntimeManager implements RuntimeResolver {
   private resolved: ResolvedRuntime | null = null;
   private stopped = false;
 
+  /** Active watchers per projectId, keyed by projectId. Stopped in stopAll. */
+  private readonly watchers = new Map<string, CloudSyncWatcher>();
+  /** Projects we've already pulled (or attempted to pull) this lifetime. */
+  private readonly pulledProjects = new Set<string>();
+  /** Which sync strategy each project ended up using. Used by the watcher
+   *  to pick between git commit-push and file-transport flush modes. */
+  private readonly syncModes = new Map<string, SyncMode>();
+
   constructor(opts: WorkerRuntimeManagerOptions = {}) {
     this.opts = opts;
     this.log = opts.logger ?? console;
@@ -265,6 +396,42 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     return deriveRuntimeToken(projectId);
   }
 
+  /**
+   * Tell the {@link WorkerTunnel} why we returned `null` from
+   * `resolveLocalUrl`. The tunnel echoes this into the structured 502
+   * body so a Studio client reading the response can tell whether the
+   * request hit a path the worker has no opinion about
+   * (`/api/projects`) versus an /agent path that lacked a project
+   * context.
+   *
+   * Stable codes:
+   *   CLI_WORKER_HAS_NO_DATA_API     — non-/agent path; cli-worker
+   *                                    instances are execution targets,
+   *                                    not data sources. Studio is
+   *                                    expected to gate stateful API
+   *                                    routing on `instance.kind` and
+   *                                    fall back to cloud for these.
+   *   CLI_WORKER_NO_PROJECT_FOR_PATH — /agent path arrived without a
+   *                                    `projectId` and we don't have a
+   *                                    single active project to fall
+   *                                    back to.
+   */
+  describeRejection(pathWithQuery: string, projectId?: string): ResolveRejection {
+    const { pathname } = splitPathAndQuery(pathWithQuery);
+    if (!(pathname.startsWith('/agent/') || pathname === '/agent')) {
+      return {
+        code: 'CLI_WORKER_HAS_NO_DATA_API',
+        message: `cli-worker only serves /agent/* paths; tried: ${pathname}`,
+      };
+    }
+    return {
+      code: 'CLI_WORKER_NO_PROJECT_FOR_PATH',
+      message:
+        `cli-worker received an /agent path without a single active project; ` +
+        `projectId=${projectId ?? 'none'}, path=${pathname}`,
+    };
+  }
+
   private async spawnConfigFor(projectId: string): Promise<ProjectSpawnConfig | null> {
     const base = this.opts.defaultSpawnConfig;
     if (!base) return null;
@@ -283,10 +450,21 @@ export class WorkerRuntimeManager implements RuntimeResolver {
   /**
    * Idempotently ensure a runtime exists for this projectId. Concurrent
    * callers share the in-flight spawn promise.
+   *
+   * Side effect: if `opts.autoPull.enabled` is true and this is the first
+   * time we've seen this projectId, we'll clone the workspace from cloud
+   * BEFORE spawning the runtime. Failures are non-fatal — the runtime
+   * still spawns and falls back to template-seeded defaults so the worker
+   * never bricks because the cloud Files API was momentarily down.
    */
   async ensureRunning(projectId: string, config: ProjectSpawnConfig): Promise<RuntimeStatusInfo> {
     if (this.stopped) throw new Error('WorkerRuntimeManager is stopped');
 
+    // Apply auto-pull before any runtime spawn so the runtime's PROJECT_DIR
+    // points at a fully-cloned workspace. Idempotent: subsequent calls hit
+    // the `pulledProjects` short-circuit.
+    config = await this.maybeAutoPull(projectId, config);
+
     const existing = this.runtimes.get(projectId);
     if (existing?.status === 'running') {
       this.touch(projectId);
@@ -309,6 +487,245 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     }
   }
 
+  /**
+   * Public entry point for tests + the `worker start` command to pre-warm
+   * a project's workspace without spawning anything. Internally idempotent.
+   */
+  async ensurePulled(projectId: string, config: ProjectSpawnConfig): Promise<ProjectSpawnConfig> {
+    return this.maybeAutoPull(projectId, config);
+  }
+
+  private async maybeAutoPull(projectId: string, config: ProjectSpawnConfig): Promise<ProjectSpawnConfig> {
+    const auto = this.opts.autoPull;
+
+    // ── Workspace-locatability invariants for the cli-worker ──
+    //
+    // The agent-runtime hard-falls-back to `/app/workspace` (a Docker
+    // convention) when none of WORKSPACE_DIR / AGENT_DIR / PROJECT_DIR
+    // are set. On a self-hosted VPS that path doesn't exist, so the
+    // runtime boots but every project-aware route silently serves
+    // empty state. To keep that bug from ever shipping again, the
+    // worker spawn path is required to either:
+    //
+    //   (a) populate `cfg.projectDir` itself before reaching here
+    //       (desktop AGPL adapter does this through `enrichSpawnConfig`,
+    //       cloud sets WORKSPACE_DIR via Knative env vars), OR
+    //   (b) carry an `autoPull` config with a `projectsDir` so this
+    //       method can synthesise a per-project workspace path on
+    //       disk and clone the cloud snapshot into it.
+    //
+    // Anything else is a misconfiguration — the runtime would either
+    // not find the workspace or scribble into a co-tenant's tree —
+    // so we throw with a multi-line operator-facing message instead
+    // of letting the agent-runtime print a deceptively-mild warning.
+    //
+    // The bypass for `enrichSpawnConfig` callers is deliberate: the
+    // desktop AGPL adapter wires up its own per-project Prisma-derived
+    // workspace path and does NOT need autoPull. We honour `projectDir`
+    // when the directory actually exists.
+    if (config.projectDir && existsSync(config.projectDir)) {
+      return config;
+    }
+
+    if (!auto) {
+      throw new Error(formatWorkspaceMisconfigError(projectId, 'no-auto-pull-config', null));
+    }
+
+    if (!auto.projectsDir) {
+      throw new Error(formatWorkspaceMisconfigError(projectId, 'no-projects-dir', null));
+    }
+
+    if (!auto.enabled) {
+      // Operator opted out of auto-pull. Honour a pre-pulled workspace
+      // (`shogo project pull <id>` lays one down at the canonical path);
+      // anything else is a misconfig because the runtime has nothing to
+      // operate on.
+      const candidate = join(auto.projectsDir, projectId);
+      if (existsSync(candidate) && !isDirEmpty(candidate)) {
+        return { ...config, projectDir: candidate };
+      }
+      throw new Error(formatWorkspaceMisconfigError(projectId, 'auto-pull-disabled', candidate));
+    }
+
+    if (this.pulledProjects.has(projectId)) {
+      // Already attempted in this process — return the canonical path
+      // so a previous failure doesn't strand the runtime on the
+      // /app/workspace fallback.
+      return { ...config, projectDir: join(auto.projectsDir, projectId) };
+    }
+
+    const projectDir = join(auto.projectsDir, projectId);
+    const log = auto.logger ?? this.log;
+    const git = {
+      cloneProject: auto.gitOps?.cloneProject ?? cloneProject,
+      gitIsAvailable: auto.gitOps?.gitIsAvailable ?? gitIsAvailable,
+      isGitRepo: auto.gitOps?.isGitRepo ?? isGitRepo,
+    };
+
+    // Mark before attempting so failures don't cause repeated re-pulls
+    // on every single request — the runtime will still start with an
+    // empty WORKSPACE_DIR and seed templates as a fallback.
+    this.pulledProjects.add(projectId);
+
+    try {
+      mkdirSync(projectDir, { recursive: true });
+      const isEmpty = isDirEmpty(projectDir);
+      const alreadyGitRepo = git.isGitRepo(projectDir);
+
+      // Strategy:
+      //   1. If git is available AND the dir is empty (no .git, no files):
+      //        clone via smart-HTTP, then top-up `.shogo/` (SQLite, gitignored)
+      //        via the file transport.
+      //   2. If git is available AND the dir already has a .git/: trust
+      //        the existing clone. The watcher / a later `shogo project
+      //        checkout` brings refs forward.
+      //   3. Otherwise (git unavailable, useGit=false, OR the dir has
+      //        non-empty content with no .git/): fall back to file transport.
+      const wantGit = auto.useGit !== false;
+      const gitAvailable = wantGit ? await git.gitIsAvailable() : false;
+      const mode: SyncMode = (gitAvailable && (isEmpty || alreadyGitRepo)) ? 'git' : 'files';
+      this.syncModes.set(projectId, mode);
+
+      if (mode === 'git') {
+        if (isEmpty) {
+          log.log(`[WorkerRuntimeManager] auto-pull: git clone project ${projectId} into ${projectDir}`);
+          try {
+            const res = await git.cloneProject({
+              apiUrl: config.cloudUrl,
+              apiKey: config.apiKey,
+              projectId,
+              localDir: projectDir,
+              shallow: true,
+              logger: log,
+            });
+            log.log(`[WorkerRuntimeManager] auto-pull: ${projectId} cloned at ${res.commitSha.slice(0, 8)}`);
+          } catch (err: any) {
+            // Git clone failed — try the file transport as a fallback.
+            // We DON'T retry git on subsequent runs: the mode flip is
+            // sticky for this projectId's lifetime to avoid bouncing.
+            log.warn(
+              `[WorkerRuntimeManager] auto-pull: git clone failed for ${projectId} (${err?.message ?? err}); ` +
+                `falling back to CloudFileTransport.downloadAll`,
+            );
+            this.syncModes.set(projectId, 'files');
+            await this.fileTransportClone(projectId, projectDir, config, log);
+          }
+        } else if (alreadyGitRepo) {
+          log.log(`[WorkerRuntimeManager] auto-pull: ${projectId} already has .git/; skipping clone`);
+        }
+
+        // After a git clone, top-up gitignored `.shogo/` SQLite state via
+        // the file transport. `.shogo/` is excluded from git but the
+        // agent-runtime requires it for state continuity across pins.
+        if (this.syncModes.get(projectId) === 'git') {
+          await this.topUpShogoState(projectId, projectDir, config, log);
+        }
+      } else if (isEmpty) {
+        // Pure file-transport path (git unavailable or disabled).
+        await this.fileTransportClone(projectId, projectDir, config, log);
+      } else {
+        log.log(`[WorkerRuntimeManager] auto-pull: ${projectId} workspace already populated; skipping clone`);
+      }
+
+      // Spin up a watcher so locally written files sync back to cloud.
+      // We only need ONE watcher per project regardless of how many
+      // runtimes spawn for it. The watcher's mode mirrors the chosen
+      // sync strategy: git → commit+push on flush, files → PUT per file.
+      if (auto.watch !== false && !this.watchers.has(projectId)) {
+        try {
+          const transport = new CloudFileTransport({
+            apiUrl: config.cloudUrl,
+            apiKey: config.apiKey,
+            projectId,
+            localDir: projectDir,
+          });
+          const finalMode = this.syncModes.get(projectId) ?? 'files';
+          const watcher = new CloudSyncWatcher({
+            rootDir: projectDir,
+            transport,
+            logger: log,
+            mode: finalMode,
+            git: finalMode === 'git'
+              ? {
+                  apiUrl: config.cloudUrl,
+                  apiKey: config.apiKey,
+                  projectId,
+                }
+              : undefined,
+          });
+          watcher.start();
+          this.watchers.set(projectId, watcher);
+        } catch (err: any) {
+          log.warn(`[WorkerRuntimeManager] auto-pull: watcher start failed for ${projectId}: ${err?.message ?? err}`);
+        }
+      }
+    } catch (err: any) {
+      log.warn(
+        `[WorkerRuntimeManager] auto-pull: failed for ${projectId} — runtime will fall back to template defaults. ` +
+          `(${err?.message ?? err})`,
+      );
+    }
+
+    // Always set projectDir so the runtime points at the (possibly empty)
+    // persistent location instead of a tmpdir. This keeps the runtime
+    // crash-resilient — restarts find the same workspace.
+    return { ...config, projectDir };
+  }
+
+  /** File-transport clone of an entire project workspace into `projectDir`. */
+  private async fileTransportClone(
+    projectId: string,
+    projectDir: string,
+    config: ProjectSpawnConfig,
+    log: Pick<Console, 'log' | 'warn' | 'error'>,
+  ): Promise<void> {
+    log.log(`[WorkerRuntimeManager] auto-pull: file-transport clone of ${projectId} into ${projectDir}`);
+    const transport = new CloudFileTransport({
+      apiUrl: config.cloudUrl,
+      apiKey: config.apiKey,
+      projectId,
+      localDir: projectDir,
+    });
+    const stats = await transport.downloadAll();
+    log.log(
+      `[WorkerRuntimeManager] auto-pull: ${projectId} downloaded ${stats.downloaded} files ` +
+        `(${stats.errors.length} errors)`,
+    );
+  }
+
+  /**
+   * After a git clone, the worker's workspace is missing `.shogo/`
+   * (the per-project SQLite state directory) because `.shogo/` is
+   * gitignored. Pull just those entries via the file transport so the
+   * agent-runtime sees consistent DB state on first spawn.
+   */
+  private async topUpShogoState(
+    projectId: string,
+    projectDir: string,
+    config: ProjectSpawnConfig,
+    log: Pick<Console, 'log' | 'warn' | 'error'>,
+  ): Promise<void> {
+    try {
+      const transport = new CloudFileTransport({
+        apiUrl: config.cloudUrl,
+        apiKey: config.apiKey,
+        projectId,
+        localDir: projectDir,
+      });
+      const manifest = await transport.listManifest();
+      const shogoEntries = manifest.filter((e: { path: string }) => e.path === '.shogo' || e.path.startsWith('.shogo/'));
+      if (shogoEntries.length === 0) return;
+      const stats = await transport.downloadFiles(shogoEntries);
+      log.log(
+        `[WorkerRuntimeManager] auto-pull: ${projectId} .shogo/ top-up downloaded ${stats.downloaded} ` +
+          `files (${stats.errors.length} errors)`,
+      );
+    } catch (err: any) {
+      // Non-fatal: the runtime will create a fresh SQLite db if needed.
+      log.warn(`[WorkerRuntimeManager] auto-pull: .shogo top-up failed for ${projectId}: ${err?.message ?? err}`);
+    }
+  }
+
   status(projectId: string): RuntimeStatusInfo | null {
     const r = this.runtimes.get(projectId);
     return r ? this.snapshot(r) : null;
@@ -345,6 +762,21 @@ export class WorkerRuntimeManager implements RuntimeResolver {
 
   async stopAll(signal: NodeJS.Signals = 'SIGTERM'): Promise<void> {
     this.stopped = true;
+    // Stop watchers FIRST so their final flush has a chance to PUT before
+    // we tear down processes. We don't await individual stops in parallel
+    // with runtime stops because watcher.stop() does network IO and we
+    // want it to complete before the runtime kill.
+    const watcherIds = Array.from(this.watchers.keys());
+    await Promise.all(watcherIds.map(async (id) => {
+      const w = this.watchers.get(id);
+      this.watchers.delete(id);
+      if (w) {
+        try { await w.stop(); } catch (err: any) {
+          this.log.warn(`[WorkerRuntimeManager] watcher stop ${id}: ${err?.message ?? err}`);
+        }
+      }
+    }));
+
     const ids = Array.from(this.runtimes.keys());
     await Promise.all(ids.map((id) => this.stop(id, signal).catch((err) => {
       this.log.error(`[WorkerRuntimeManager] Failed to stop ${id}: ${err?.message ?? err}`);
@@ -383,7 +815,7 @@ export class WorkerRuntimeManager implements RuntimeResolver {
       slot.apiServerPort = slot.agentPort + API_PORT_OFFSET;
     }
 
-    const env = this.buildEnv(slot);
+    const env = this.buildEnv(slot, resolved.path);
     const cwd = this.resolveCwd(slot);
     const { command, args } = this.spawnCommand(resolved.path);
 
@@ -441,7 +873,7 @@ export class WorkerRuntimeManager implements RuntimeResolver {
     }
   }
 
-  private buildEnv(slot: InternalRuntime): NodeJS.ProcessEnv {
+  private buildEnv(slot: InternalRuntime, runtimeBinPath: string): NodeJS.ProcessEnv {
     const cfg = slot.spawnConfig;
     const env: NodeJS.ProcessEnv = {
       ...(this.opts.env ?? process.env),
@@ -461,13 +893,42 @@ export class WorkerRuntimeManager implements RuntimeResolver {
       env.PROJECT_DIR = cfg.projectDir;
       env.WORKSPACE_DIR = cfg.projectDir;
     }
+    // Tell the agent-runtime to skip its built-in S3Sync — the worker is
+    // already running a CloudFileTransport watcher against this WORKSPACE_DIR.
+    // Without this both sides upload the same files and the watcher loops on
+    // its own writes.
+    if (this.opts.autoPull?.enabled) {
+      env.SHOGO_CLOUD_SYNC = '1';
+    }
     if (cfg.aiProxyUrl) env.AI_PROXY_URL = cfg.aiProxyUrl;
     if (cfg.aiProxyToken) env.AI_PROXY_TOKEN = cfg.aiProxyToken;
     if (cfg.techStackId) env.TECH_STACK_ID = cfg.techStackId;
-    if (cfg.templateId) env.TEMPLATE_ID = cfg.templateId;
     if (cfg.name) env.AGENT_NAME = cfg.name;
     if (cfg.workspaceId) env.WORKSPACE_ID = cfg.workspaceId;
 
+    // Belt-and-suspenders: explicitly point the spawned agent-runtime at
+    // the WASM sidecar that ships next to its binary. The runtime's own
+    // `code-extractor.ts:getWasmDir()` would derive the same path from
+    // `dirname(process.execPath)` as a fallback, but exporting it here:
+    //
+    //   (a) makes the resolved location observable via `env | grep
+    //       TREE_SITTER` for an operator debugging a self-hosted box,
+    //   (b) survives a future build-script regression that breaks the
+    //       sidecar copy on a per-platform basis (the env var still
+    //       points to the expected directory, so the loud failure in
+    //       `code-extractor.ts:getLanguage()` reports the right path),
+    //   (c) keeps explicit operator overrides working — the runtime
+    //       reads `process.env.TREE_SITTER_WASM_DIR` first, so an
+    //       operator who sets it externally still wins.
+    //
+    // We do NOT verify the directory exists here. The runtime's
+    // resolver does that check; if it's missing we want the loud
+    // runtime error (which lists every override knob), not a silent
+    // worker-side `process.env` deletion that hides the bundling bug.
+    if (!env.TREE_SITTER_WASM_DIR) {
+      env.TREE_SITTER_WASM_DIR = join(dirname(runtimeBinPath), 'tree-sitter-wasm');
+    }
+
     if (cfg.extraEnv) Object.assign(env, cfg.extraEnv);
     return env;
   }

package/src/lib/tunnel.ts

@@ -21,6 +21,20 @@
  */
 import { hostname as osHostname, platform, arch as osArch } from 'node:os';
 
+/**
+ * Structured reason returned to the cloud (and ultimately to a Studio
+ * client) when {@link RuntimeResolver.resolveLocalUrl} declines to
+ * forward a tunneled request. Surfaced verbatim in the 502 body so a
+ * future debugger reading the response without log access can tell
+ * what happened.
+ */
+export interface ResolveRejection {
+  /** Stable machine-readable identifier (UPPER_SNAKE_CASE). */
+  code: string;
+  /** Human-readable explanation. Should reference the actual path. */
+  message: string;
+}
+
 /**
  * Pluggable resolver for the tunnel — provided by whoever owns the local
  * services that the cloud's tunneled requests should be forwarded to.
@@ -55,6 +69,14 @@ export interface RuntimeResolver {
 
   /** Status snapshot for a single project — used in metadata payloads. */
   status(projectId: string): { status: string; agentPort?: number } | null;
+
+  /**
+   * Describe why a path was rejected. Called by the tunnel after a
+   * `resolveLocalUrl` returned null so the structured 502 body can
+   * carry an actionable code + message. Optional — when absent the
+   * tunnel falls back to a generic `NO_LOCAL_RUNTIME` payload.
+   */
+  describeRejection?(pathWithQuery: string, projectId?: string): ResolveRejection;
 }
 
 interface TunnelRequest {
@@ -391,11 +413,24 @@ export class WorkerTunnel {
     try {
       const url = await this.resolveLocalUrl(msg.path, msg.projectId);
       if (!url) {
+        // Structured 502 body so future debuggers reading the response
+        // (without access to worker logs) can tell what happened. The
+        // resolver provides the code/message; the tunnel always echoes
+        // back the original path so the operator doesn't have to
+        // correlate request-ids to figure out which fetch failed.
+        const rejection: ResolveRejection = this.opts.resolver.describeRejection
+          ? this.opts.resolver.describeRejection(msg.path, msg.projectId)
+          : { code: 'NO_LOCAL_RUNTIME', message: `no local runtime available for path: ${msg.path}` };
         this.sendFrame({
           type: 'response',
           requestId: msg.requestId,
           status: 502,
-          body: JSON.stringify({ error: 'No local runtime available for path' }),
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            code: rejection.code,
+            message: rejection.message,
+            path: msg.path,
+          }),
         });
         return;
       }
@@ -636,6 +671,10 @@ export class WorkerTunnel {
       heartbeatLoop: () => self.heartbeatLoop(),
       connectWs: () => self.connectWs(),
       cleanupWs: () => self.cleanupWs(),
+      handleRequest: (msg: TunnelRequest) => self.handleRequest(msg),
+      installFakeWs: (fake: WebSocket) => {
+        self.ws = fake;
+      },
       getCloudUrl: () => self.getCloudUrl(),
       getWsBaseUrl: () => self.getWsBaseUrl(),
       buildWsUrl: () => self.buildWsUrl(),