@neuralnomads/codenomad-dev 0.18.0-dev-20260721-d74a8a39 → 0.18.0-dev-20260731-1d4f7786

package/dist/background-processes/manager.js

@@ -2,6 +2,7 @@ import { spawn, spawnSync } from "child_process";
 import { createWriteStream, existsSync, promises as fs } from "fs";
 import path from "path";
 import { randomBytes } from "crypto";
+import { createInstanceClient } from "../workspaces/instance-client";
 const ROOT_DIR = ".codenomad/background_processes";
 const INDEX_FILE = "index.json";
 const OUTPUT_FILE = "output.txt";
@@ -511,38 +512,22 @@ export class BackgroundProcessManager {
         const notify = record.notify;
         if (!notify || !record.terminalReason)
             return;
-        if (!this.deps.workspaceManager.get(workspaceId)) {
-            throw new Error("Workspace not found");
-        }
-        const port = this.deps.workspaceManager.getInstancePort(workspaceId);
-        if (!port) {
-            throw new Error("Workspace instance is not ready");
-        }
-        const targetUrl = `http://127.0.0.1:${port}/session/${encodeURIComponent(notify.sessionID)}/prompt_async`;
-        const headers = {
-            "content-type": "application/json",
-        };
-        const authorization = this.deps.workspaceManager.getInstanceAuthorizationHeader(workspaceId);
-        if (authorization) {
-            headers.authorization = authorization;
-        }
-        const response = await fetch(targetUrl, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({
-                parts: [
-                    {
-                        type: "text",
-                        text: this.buildSyntheticCompletionPrompt(record),
-                        synthetic: true,
-                    },
-                ],
-            }),
+        const client = createInstanceClient(this.deps.workspaceManager, workspaceId, {
+            directory: notify.directory,
         });
-        if (!response.ok) {
-            const message = await response.text().catch(() => "");
-            throw new Error(message || `Prompt request failed with ${response.status}`);
+        if (!client) {
+            throw new Error("Workspace instance is not ready");
         }
+        await client.session.promptAsync({
+            sessionID: notify.sessionID,
+            parts: [
+                {
+                    type: "text",
+                    text: this.buildSyntheticCompletionPrompt(record),
+                    synthetic: true,
+                },
+            ],
+        }, { throwOnError: true });
     }
     buildCompletionPrompt(record) {
         const ref = `Background process "${record.title}" (${record.id})`;

package/dist/background-processes/manager.test.js

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { BackgroundProcessManager } from "./manager";
+const WORKSPACE_ID = "ws-test";
+const SESSION_ID = "sess-1";
+const INSTANCE_PORT = 9999;
+const AUTH_HEADER = "Basic test-auth";
+const TERMINAL_TIMEOUT_MS = 3000;
+/**
+ * Drives the real {@link BackgroundProcessManager} lifecycle (spawn a
+ * fast-exiting command with notify enabled) against a mocked transport, so the
+ * migrated `sendCompletionPrompt` path — factory + SDK client + `fetch` — is
+ * exercised end to end without touching production wiring.
+ *
+ * The workspace temp directory is intentionally left in place (under
+ * `os.tmpdir()`, OS-reaped): removing it from the test races the manager's
+ * asynchronous finalization writes, which intermittently fail with ENOENT.
+ */
+async function runCompletionPrompt(fetchImpl) {
+    const requests = [];
+    const originalFetch = globalThis.fetch;
+    // Captured now but swapped in only inside the try below, so a failure during
+    // setup (mkdtemp, manager construction) can't leak the mocked fetch.
+    const fetchMock = (async (input, init) => {
+        const req = input instanceof Request ? input : new Request(String(input), init);
+        requests.push({
+            method: req.method,
+            url: req.url,
+            headers: req.headers,
+            body: await req.text(),
+        });
+        return fetchImpl(input instanceof Request ? input : req, init);
+    });
+    let warned = false;
+    const logger = {
+        warn: () => { warned = true; },
+        debug: () => { },
+        trace: () => { },
+        info: () => { },
+        error: () => { },
+        fatal: () => { },
+        isLevelEnabled: () => false,
+        level: "info",
+        child: () => logger,
+    };
+    const workspacePath = await fs.mkdtemp(path.join(os.tmpdir(), "bp-test-"));
+    // Distinct from the workspace root so the directory-override assertion is
+    // discriminating: if `sendCompletionPrompt` stops passing `notify.directory`,
+    // the factory would fall back to `workspacePath` and the header check fails.
+    const sessionDir = path.join(workspacePath, "session-worktree");
+    // Resolve once the manager publishes a terminal (non-running) status update.
+    let resolveTerminal = () => { };
+    const terminal = new Promise((resolve) => { resolveTerminal = resolve; });
+    const eventBus = {
+        on: () => { },
+        publish: (event) => {
+            if (event?.type === "instance.event") {
+                const type = event?.event?.type;
+                const status = event?.event?.properties?.process?.status;
+                if (type === "background.process.removed" || (status && status !== "running"))
+                    resolveTerminal();
+            }
+            return true;
+        },
+    };
+    const workspaceManager = {
+        get: () => ({ path: workspacePath }),
+        getInstancePort: () => INSTANCE_PORT,
+        getInstanceAuthorizationHeader: () => AUTH_HEADER,
+    };
+    const manager = new BackgroundProcessManager({ workspaceManager, eventBus, logger });
+    try {
+        globalThis.fetch = fetchMock;
+        await manager.start(WORKSPACE_ID, "test-proc", "true", {
+            notify: true,
+            notification: { sessionID: SESSION_ID, directory: sessionDir },
+        });
+        // The terminal status update is published at the very end of finalize, so
+        // resolving on it is a deterministic completion signal. Fail loudly rather
+        // than racing a silent timeout that could mask a hang.
+        let timeoutHandle;
+        const reachedTerminal = await Promise.race([
+            terminal.then(() => true),
+            new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => resolve(false), TERMINAL_TIMEOUT_MS);
+            }),
+        ]);
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        if (!reachedTerminal) {
+            throw new Error("background process did not reach a terminal state in time");
+        }
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+    return { requests, warned, directory: sessionDir };
+}
+describe("BackgroundProcessManager.sendCompletionPrompt", () => {
+    it("posts the synthetic completion prompt to the instance via the SDK route", async () => {
+        const { requests, directory } = await runCompletionPrompt(async () => new Response("{}", { status: 200, headers: { "content-type": "application/json" } }));
+        const promptCall = requests.find((r) => r.url.includes("/prompt_async"));
+        assert.ok(promptCall, "expected a prompt_async request");
+        assert.equal(promptCall.method, "POST");
+        assert.equal(promptCall.url, `http://127.0.0.1:${INSTANCE_PORT}/session/${SESSION_ID}/prompt_async`);
+        assert.equal(promptCall.headers.get("authorization"), AUTH_HEADER);
+        // The prompt is scoped to the session's directory (a POST keeps the
+        // directory as a header — the SDK only rewrites header→query for GET/HEAD).
+        assert.equal(promptCall.headers.get("x-opencode-directory"), encodeURIComponent(directory));
+        const body = JSON.parse(promptCall.body);
+        assert.equal(body.parts.length, 1);
+        assert.equal(body.parts[0].type, "text");
+        assert.equal(body.parts[0].synthetic, true);
+        assert.match(body.parts[0].text, /test-proc/);
+    });
+    it("swallows a failed prompt and logs it without aborting finalization", async () => {
+        const { warned } = await runCompletionPrompt(async () => new Response("boom", { status: 500 }));
+        assert.equal(warned, true);
+    });
+});

package/dist/config/schema.js

@@ -19,8 +19,9 @@ const PreferencesSchema = z
     modelThinkingSelections: z.record(z.string(), z.string()).default({}),
     diffViewMode: z.enum(["split", "unified"]).default("split"),
     toolOutputExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
-    diagnosticsExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
+    diagnosticsExpansion: z.enum(["hidden", "expanded", "collapsed"]).default("expanded"),
     showUsageMetrics: z.boolean().default(true),
+    usageMetricsExpansion: z.enum(["expanded", "collapsed"]).default("collapsed"),
     autoCleanupBlankSessions: z.boolean().default(true),
     listeningMode: z.enum(["local", "all"]).default("local"),
     logLevel: z.enum(["DEBUG", "INFO", "WARN", "ERROR"]).default("DEBUG"),

package/dist/config/schema.test.js

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { PreferencesSchema } from "./schema";
+describe("chat visibility preferences", () => {
+    it("accepts hidden diagnostics and collapsed usage metrics", () => {
+        const preferences = PreferencesSchema.parse({
+            diagnosticsExpansion: "hidden",
+            usageMetricsExpansion: "collapsed",
+        });
+        assert.equal(preferences.diagnosticsExpansion, "hidden");
+        assert.equal(preferences.usageMetricsExpansion, "collapsed");
+    });
+});

package/dist/filesystem/__tests__/search-cache.test.js

@@ -8,25 +8,37 @@ describe("workspace search cache", () => {
     it("expires cached candidates after the TTL", () => {
         const workspacePath = "/tmp/workspace";
         const startTime = 1_000;
-        refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-a")], startTime);
-        const beforeExpiry = getWorkspaceCandidates(workspacePath, startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS - 1);
+        refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-a")], startTime);
+        const beforeExpiry = getWorkspaceCandidates(workspacePath, "query-a", startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS - 1);
         assert.ok(beforeExpiry);
         assert.equal(beforeExpiry.length, 1);
         assert.equal(beforeExpiry[0].name, "file-a");
-        const afterExpiry = getWorkspaceCandidates(workspacePath, startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS + 1);
+        const afterExpiry = getWorkspaceCandidates(workspacePath, "query-a", startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS + 1);
         assert.equal(afterExpiry, undefined);
     });
     it("replaces cached entries when manually refreshed", () => {
         const workspacePath = "/tmp/workspace";
-        refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-a")], 5_000);
-        const initial = getWorkspaceCandidates(workspacePath, 5_001);
+        refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-a")], 5_000);
+        const initial = getWorkspaceCandidates(workspacePath, "query-a", 5_001);
         assert.ok(initial);
         assert.equal(initial[0].name, "file-a");
-        refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-b")], 6_000);
-        const refreshed = getWorkspaceCandidates(workspacePath, 6_001);
+        refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-b")], 6_000);
+        const refreshed = getWorkspaceCandidates(workspacePath, "query-a", 6_001);
         assert.ok(refreshed);
         assert.equal(refreshed[0].name, "file-b");
     });
+    it("does not reuse candidates across query scopes", () => {
+        const workspacePath = "/tmp/workspace";
+        refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-a")], 5_000);
+        assert.equal(getWorkspaceCandidates(workspacePath, "query-a", 5_001)?.[0].name, "file-a");
+        assert.equal(getWorkspaceCandidates(workspacePath, "query-b", 5_001), undefined);
+        refreshWorkspaceCandidates(workspacePath, "query-b", () => [createEntry("file-b")], 5_000);
+        assert.equal(getWorkspaceCandidates(workspacePath, "query-a", 5_001), undefined);
+        assert.equal(getWorkspaceCandidates(workspacePath, "query-b", 5_001)?.[0].name, "file-b");
+        clearWorkspaceSearchCache(workspacePath);
+        assert.equal(getWorkspaceCandidates(workspacePath, "query-a", 5_001), undefined);
+        assert.equal(getWorkspaceCandidates(workspacePath, "query-b", 5_001), undefined);
+    });
 });
 function createEntry(name) {
     return {

package/dist/filesystem/__tests__/search.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { after, test } from "node:test";
+import { searchWorkspaceFiles } from "../search";
+import { getWorkspaceCandidates } from "../search-cache";
+const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-search-"));
+after(() => fs.rmSync(workspace, { recursive: true, force: true }));
+test("finds a matching file after more than 8000 non-matching entries", () => {
+    fs.mkdirSync(path.join(workspace, "a"));
+    fs.mkdirSync(path.join(workspace, "b"));
+    const [targetDirName, fillerDirName] = fs.readdirSync(workspace);
+    const fillerDir = path.join(workspace, fillerDirName);
+    const targetDir = path.join(workspace, targetDirName);
+    for (let index = 0; index < 8_001; index += 1) {
+        fs.writeFileSync(path.join(fillerDir, `filler-${index}.txt`), "");
+    }
+    fs.writeFileSync(path.join(targetDir, "unique-search-target.txt"), "");
+    const results = searchWorkspaceFiles(workspace, "unique-search-target", {
+        type: "file",
+        refresh: true,
+    });
+    assert.equal(results.some((entry) => entry.name === "unique-search-target.txt"), true);
+    searchWorkspaceFiles(workspace, "filler", { type: "file", refresh: true });
+    assert.equal(getWorkspaceCandidates(workspace, "file\0filler")?.length, 8_000);
+});
+test("does not revisit directory links", () => {
+    const cyclicWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-search-cycle-"));
+    try {
+        fs.symlinkSync(cyclicWorkspace, path.join(cyclicWorkspace, "cycle"), process.platform === "win32" ? "junction" : "dir");
+        assert.deepEqual(searchWorkspaceFiles(cyclicWorkspace, "not-present", { refresh: true }), []);
+    }
+    finally {
+        fs.rmSync(cyclicWorkspace, { recursive: true, force: true });
+    }
+});
+test("indexes both real and linked directory paths", () => {
+    const linkedWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-search-link-"));
+    try {
+        const realDirectory = path.join(linkedWorkspace, "b");
+        fs.mkdirSync(realDirectory);
+        fs.writeFileSync(path.join(realDirectory, "needle.txt"), "");
+        fs.symlinkSync(realDirectory, path.join(linkedWorkspace, "a"), process.platform === "win32" ? "junction" : "dir");
+        const linkedResults = searchWorkspaceFiles(linkedWorkspace, "a/needle", { type: "file", refresh: true });
+        const realResults = searchWorkspaceFiles(linkedWorkspace, "b/needle", { type: "file", refresh: true });
+        assert.equal(linkedResults.some((entry) => entry.path === "a/needle.txt"), true);
+        assert.equal(realResults.some((entry) => entry.path === "b/needle.txt"), true);
+    }
+    finally {
+        fs.rmSync(linkedWorkspace, { recursive: true, force: true });
+    }
+});

package/dist/filesystem/search-cache.js

@@ -1,10 +1,10 @@
 import path from "path";
 export const WORKSPACE_CANDIDATE_CACHE_TTL_MS = 30_000;
 const workspaceCandidateCache = new Map();
-export function getWorkspaceCandidates(rootDir, now = Date.now()) {
+export function getWorkspaceCandidates(rootDir, scope, now = Date.now()) {
     const key = normalizeKey(rootDir);
     const cached = workspaceCandidateCache.get(key);
-    if (!cached) {
+    if (!cached || cached.scope !== scope) {
         return undefined;
     }
     if (cached.expiresAt <= now) {
@@ -13,15 +13,12 @@ export function getWorkspaceCandidates(rootDir, now = Date.now()) {
     }
     return cloneEntries(cached.candidates);
 }
-export function refreshWorkspaceCandidates(rootDir, builder, now = Date.now()) {
+export function refreshWorkspaceCandidates(rootDir, scope, builder, now = Date.now()) {
     const key = normalizeKey(rootDir);
     const freshCandidates = builder();
-    if (!freshCandidates || freshCandidates.length === 0) {
-        workspaceCandidateCache.delete(key);
-        return [];
-    }
     const storedCandidates = cloneEntries(freshCandidates);
     workspaceCandidateCache.set(key, {
+        scope,
         expiresAt: now + WORKSPACE_CANDIDATE_CACHE_TTL_MS,
         candidates: storedCandidates,
     });
@@ -32,8 +29,7 @@ export function clearWorkspaceSearchCache(rootDir) {
         workspaceCandidateCache.clear();
         return;
     }
-    const key = normalizeKey(rootDir);
-    workspaceCandidateCache.delete(key);
+    workspaceCandidateCache.delete(normalizeKey(rootDir));
 }
 function cloneEntries(entries) {
     return entries.map((entry) => ({ ...entry }));

package/dist/filesystem/search.js

@@ -15,13 +15,14 @@ export function searchWorkspaceFiles(rootDir, query, options = {}) {
     const limit = normalizeLimit(options.limit);
     const typeFilter = options.type ?? "all";
     const refreshRequested = options.refresh === true;
+    const cacheScope = `${typeFilter}\0${trimmedQuery.toLowerCase()}`;
     let entries;
     try {
         if (!refreshRequested) {
-            entries = getWorkspaceCandidates(normalizedRoot);
+            entries = getWorkspaceCandidates(normalizedRoot, cacheScope);
         }
         if (!entries) {
-            entries = refreshWorkspaceCandidates(normalizedRoot, () => collectCandidates(normalizedRoot));
+            entries = refreshWorkspaceCandidates(normalizedRoot, cacheScope, () => collectCandidates(normalizedRoot, trimmedQuery, typeFilter));
         }
     }
     catch (error) {
@@ -29,7 +30,6 @@ export function searchWorkspaceFiles(rootDir, query, options = {}) {
         throw error;
     }
     if (!entries || entries.length === 0) {
-        clearWorkspaceSearchCache(normalizedRoot);
         return [];
     }
     const candidates = buildCandidateEntries(entries, typeFilter);
@@ -45,14 +45,23 @@ export function searchWorkspaceFiles(rootDir, query, options = {}) {
     }
     return matches.map((match) => match.obj.entry);
 }
-function collectCandidates(rootDir) {
-    const queue = [""];
+function collectCandidates(rootDir, query, filter) {
+    const queue = [
+        { relativeDir: "", ancestors: new Set() },
+    ];
     const entries = [];
     while (queue.length > 0 && entries.length < MAX_CANDIDATES) {
-        const relativeDir = queue.pop() || "";
+        const queuedDirectory = queue.pop();
+        const { relativeDir, ancestors } = queuedDirectory;
         const absoluteDir = relativeDir ? path.join(rootDir, relativeDir) : rootDir;
         let dirents;
+        let branchAncestors;
         try {
+            const realDir = normalizeDirectoryIdentity(fs.realpathSync.native(absoluteDir));
+            if (ancestors.has(realDir)) {
+                continue;
+            }
+            branchAncestors = new Set([...ancestors, realDir]);
             dirents = fs.readdirSync(absoluteDir, { withFileTypes: true });
         }
         catch {
@@ -75,9 +84,7 @@ function collectCandidates(rootDir) {
             }
             const isDirectory = stats.isDirectory();
             if (isDirectory && !IGNORED_DIRECTORIES.has(lowerName)) {
-                if (entries.length < MAX_CANDIDATES) {
-                    queue.push(relativePath);
-                }
+                queue.push({ relativeDir: relativePath, ancestors: branchAncestors });
             }
             const entryType = isDirectory ? "directory" : "file";
             const normalizedPath = normalizeRelativeEntryPath(relativePath);
@@ -89,6 +96,9 @@ function collectCandidates(rootDir) {
                 size: entryType === "file" ? stats.size : undefined,
                 modifiedAt: stats.mtime.toISOString(),
             };
+            if (!shouldInclude(entry.type, filter) || !fuzzysort.single(query, buildSearchKey(entry))) {
+                continue;
+            }
             entries.push(entry);
             if (entries.length >= MAX_CANDIDATES) {
                 break;
@@ -133,3 +143,6 @@ function normalizeRelativeEntryPath(relativePath) {
 function buildSearchKey(entry) {
     return entry.path.toLowerCase();
 }
+function normalizeDirectoryIdentity(directoryPath) {
+    return process.platform === "win32" ? directoryPath.toLowerCase() : directoryPath;
+}

package/dist/server/routes/auth-pages/login.html

@@ -72,10 +72,10 @@
       <p>This CodeNomad server is protected. Enter your credentials to continue.</p>
 
       <label for="username">Username</label>
-      <input id="username" autocomplete="username" placeholder="{{DEFAULT_USERNAME}}" value="" />
+      <input id="username" autocomplete="username" autocapitalize="none" autocorrect="off" spellcheck="false" placeholder="{{DEFAULT_USERNAME}}" value="{{DEFAULT_USERNAME}}" />
 
       <label for="password">Password</label>
-      <input id="password" type="password" autocomplete="current-password" value="" />
+      <input id="password" type="password" autocomplete="current-password" autocapitalize="none" autocorrect="off" spellcheck="false" value="" />
 
       <button id="submit" type="button">Continue</button>
       <div id="error" class="error" style="display: none"></div>
@@ -95,7 +95,7 @@
 
       async function submit() {
         hideError()
-        const username = $("username").value.trim()
+        const username = $("username").value
         const password = $("password").value
         if (!username || !password) {
           showError("Username and password are required.")

package/dist/server/routes/auth.js

@@ -26,7 +26,7 @@ function getLoginHtml(defaultUsername) {
         cachedLoginTemplate = readTemplate(LOGIN_TEMPLATE_URL, null);
     }
     const escapedUsername = escapeHtml(defaultUsername);
-    return cachedLoginTemplate.replace(/\{\{DEFAULT_USERNAME\}\}/g, escapedUsername);
+    return cachedLoginTemplate.replace(/\{\{DEFAULT_USERNAME\}\}/g, () => escapedUsername);
 }
 function getTokenHtml() {
     if (!cachedTokenTemplate) {

package/dist/server/routes/auth.test.js

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { it } from "node:test";
+import Fastify from "fastify";
+import { registerAuthRoutes } from "./auth";
+it("renders the escaped default username literally as the login field value", async () => {
+    const app = Fastify({ logger: false });
+    const username = " code$&\"nomad ";
+    const authManager = {
+        getSessionFromRequest: () => null,
+        getStatus: () => ({ username }),
+    };
+    registerAuthRoutes(app, { authManager });
+    const response = await app.inject({ method: "GET", url: "/login" });
+    assert.equal(response.statusCode, 200);
+    assert.ok(response.body.includes('value=" code$&"nomad "'));
+    assert.match(response.body, /const username = \$\("username"\)\.value\s*\n/);
+    assert.equal(response.body.match(/autocapitalize="none"/g)?.length, 2);
+    assert.equal(response.body.match(/autocorrect="off"/g)?.length, 2);
+    assert.equal(response.body.match(/spellcheck="false"/g)?.length, 2);
+    await app.close();
+});

package/dist/workspaces/instance-client.js

@@ -1,5 +1,5 @@
 import { createOpencodeClient } from "@opencode-ai/sdk/v2/client";
-const INSTANCE_HOST = "127.0.0.1";
+import { LOOPBACK_HOST } from "./loopback";
 const LOOPBACK_TIMEOUT_MS = 10_000;
 /**
  * Creates an OpenCode SDK client for direct loopback communication with a
@@ -11,8 +11,8 @@ const LOOPBACK_TIMEOUT_MS = 10_000;
  * OpenCode instance directly should use this factory rather than building
  * `http://127.0.0.1:{port}/...` URLs by hand.
  *
- * All requests carry a 10-second timeout — loopback calls should be
- * near-instant; a hang indicates a stuck instance.
+ * Requests carry a 10-second timeout (configurable via `timeoutMs`) —
+ * loopback calls should be near-instant; a hang indicates a stuck instance.
  *
  * The client is cheap to create (object only, no connection); create one per
  * call or cache per instance as needed. Returns `null` when the instance has
@@ -29,13 +29,14 @@ export function createInstanceClient(workspaceManager, instanceId, options = {})
     }
     const workspace = workspaceManager.get(instanceId);
     const timeoutMs = options.timeoutMs ?? LOOPBACK_TIMEOUT_MS;
+    const directory = options.directory ?? workspace?.path;
     return createOpencodeClient({
-        baseUrl: `http://${INSTANCE_HOST}:${port}/`,
+        baseUrl: `http://${LOOPBACK_HOST}:${port}/`,
         headers,
         fetch: (url, init) => fetch(url, {
             ...init,
             signal: init?.signal ?? AbortSignal.timeout(timeoutMs),
         }),
-        ...(workspace?.path ? { directory: workspace.path } : {}),
+        ...(directory ? { directory } : {}),
     });
 }