@cozibud/harness 0.1.0 → 0.2.0

package/README.md

@@ -1,24 +1,48 @@
-# `@cozibud/harness`
-
-Internal infrastructure for the Cozibud Watch local-client bridge. It invokes a
-supported local AI client and exposes the provider-neutral runtime used by the
-bridge engineering tools.
-
-This package is not a released Watch feature. The authenticated server relay,
-device pairing, and production delivery path are not included, and the local
-HTTP adapter must not be exposed to a LAN or the internet.
-
-## Maintainer smoke check
-
-After building or installing an explicitly reviewed version:
-
-```text
-cozibud-harness --help
-```
-
-Provider setup and request commands are internal acceptance tools. They use the
-provider's own installed client and sign-in state; the harness does not accept
-or store provider passwords.
-
-Release and bootstrap procedures live in the private repository's
-`docs/NPM-HARNESS-PUBLISHING.md` operator runbook.
+# `@cozibud/harness`
+
+Connect a signed-in Codex CLI to your Cozibud household for watch voice.
+Keep the computer awake and the outbound relay running while using voice.
+Watch voice requires Codex CLI 0.159.0 or newer and a server supporting relay
+protocol 2. This source version still needs its package and server release.
+
+## Watch voice
+
+After installing the released harness, sign in to Codex with `codex login`.
+Run this single command:
+
+```text
+cozibud-harness relay --provider codex
+```
+
+On the first run, open the displayed Cozibud link and approve your computer
+in the household you use on your watch. The command then connects automatically.
+Later runs reuse the saved pairing. Keep this command running and the computer awake.
+If the watch finds no connected computer, **Open guide on phone** shows the setup steps.
+
+On the watch, select the child, speak, and check the transcript. **Send & save**
+authorizes the server to validate and save one record. Ambiguous requests ask
+for clarification. A saved-record receipt appears only after server readback.
+No microphone audio is sent to the bridge; the confirmed transcript and selected
+child context go to your signed-in Codex client and its model service.
+
+Your Codex login stays local. Pairing credentials are protected with your
+Windows account's DPAPI on Windows, or a user-only file on other systems.
+Disconnect the computer in Cozibud's Watch settings to revoke its access.
+Use `COZIBUD_RELAY_URL` to choose another HTTPS server before pairing; pairings
+are scoped to that origin. The relay requires no inbound computer port.
+The separate local HTTP adapter must remain on loopback.
+
+## Maintainer smoke check
+
+After building or installing an explicitly reviewed version:
+
+```text
+cozibud-harness --help
+```
+
+Provider setup and request commands are internal acceptance tools. They use the
+provider's own installed client and sign-in state; the harness does not accept
+or store provider passwords.
+
+Release and bootstrap procedures live in the private repository's
+`docs/NPM-HARNESS-PUBLISHING.md` operator runbook.

package/dist/cli.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { ensureRelayPairing, pairRelay, relayOrigin } from "./pairing.js";
 import { createBuiltInDrivers } from "./process-driver.js";
+import { FileRelayExecutionStore, OutboundRelayBridge, RelayTransportError } from "./relay-client.js";
 import { HarnessRuntime } from "./runtime.js";
 import { createHarnessHttpServer } from "./server.js";
 import { DEFAULT_COZIBUD_MCP_URL, setupProvider } from "./setup.js";
@@ -20,26 +25,96 @@ function promptFrom(args) {
     return parts.join(" ").trim();
 }
 function printHelp() {
-    console.log(`Cozibud local LLM harness
-
-Usage:
-  cozibud-harness setup [--provider codex|claude|gemini|cursor] [--mcp-url https://cozibud.com/api/mcp]
-  cozibud-harness ask [--provider codex|claude|gemini|cursor] [--locale en-US] "When was the last bottle?"
-  cozibud-harness serve [--host 127.0.0.1] [--port 8798]
-
-Quick start:
-  setup   prepares a signed-in local client and the MCP access its bridge turns need
-  ask     sends one typed request through an already signed-in provider
-
-Environment:
-  COZIBUD_HARNESS_TOKEN     bearer token (generated for this run when omitted)
-  COZIBUD_HARNESS_ORIGINS   comma-separated browser origins allowed by CORS
-  COZIBUD_CODEX_PATH        optional Codex executable path
-  COZIBUD_CLAUDE_PATH       optional Claude executable path
-  COZIBUD_GEMINI_PATH       optional Gemini executable path
-  COZIBUD_CURSOR_PATH       optional Cursor Agent executable path
+    console.log(`Cozibud local LLM harness
+
+Usage:
+  cozibud-harness setup [--provider codex|claude|gemini|cursor] [--mcp-url https://cozibud.com/api/mcp]
+  cozibud-harness ask [--provider codex|claude|gemini|cursor] [--locale en-US] "When was the last bottle?"
+  cozibud-harness relay [--provider codex]
+  cozibud-harness pair [--name "My computer"]
+  cozibud-harness serve [--host 127.0.0.1] [--port 8798]
+
+Quick start:
+  setup   prepares a signed-in local client and the MCP access its bridge turns need
+  ask     sends one typed request through an already signed-in provider
+  relay   pairs this computer if needed, then keeps watch voice connected
+
+Environment:
+  COZIBUD_HARNESS_TOKEN     bearer token (generated for this run when omitted)
+  COZIBUD_HARNESS_ORIGINS   comma-separated browser origins allowed by CORS
+  COZIBUD_RELAY_URL          canonical Cozibud origin (defaults to https://cozibud.com)
+  COZIBUD_RELAY_CREDENTIAL   optional paired credential override (never printed)
+  COZIBUD_RELAY_PAIRING      protected pairing file path
+  COZIBUD_RELAY_STATE        local idempotency journal path
+  COZIBUD_CODEX_PATH        optional Codex executable path
+  COZIBUD_CLAUDE_PATH       optional Claude executable path
+  COZIBUD_GEMINI_PATH       optional Gemini executable path
+  COZIBUD_CURSOR_PATH       optional Cursor Agent executable path
+  COZIBUD_CURSOR_WORKSPACE  stable dedicated empty Cursor bridge workspace
   COZIBUD_CURSOR_MCP_CONFIG optional Cursor user MCP config path (test/development override)`);
 }
+async function relay(args) {
+    const provider = value(args, "--provider", "codex");
+    const driver = createBuiltInDrivers().find((candidate) => candidate.id === provider);
+    if (!driver)
+        throw new Error(`Unknown provider: ${provider}. Choose codex, claude, gemini, or cursor.`);
+    if (provider !== "codex")
+        throw new Error("Watch voice currently requires Codex CLI.");
+    const baseUrl = relayOrigin(process.env.COZIBUD_RELAY_URL?.trim() || "https://cozibud.com");
+    const available = await driver.probe();
+    if (available.state === "unavailable")
+        throw new Error(available.message);
+    const version = available.version?.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!version || (Number(version[1]) === 0 && Number(version[2]) < 159))
+        throw new Error("Watch voice requires Codex CLI 0.159.0 or newer. Update Codex, sign in, and retry.");
+    const controller = new AbortController();
+    process.once("SIGINT", () => controller.abort());
+    process.once("SIGTERM", () => controller.abort());
+    let credential = process.env.COZIBUD_RELAY_CREDENTIAL?.trim() || await ensureRelayPairing({ origin: baseUrl,
+        name: value(args, "--name", hostname()), path: pairingPath(), write: console.log, signal: controller.signal });
+    const createBridge = () => {
+        const namespace = createHash("sha256").update(`${baseUrl}\n${credential}`).digest("hex").slice(0, 20);
+        const statePath = process.env.COZIBUD_RELAY_STATE?.trim() || join(homedir(), ".cozibud", `relay-state-${namespace}.json`);
+        return new OutboundRelayBridge({ baseUrl, credential, driver, store: new FileRelayExecutionStore(statePath) });
+    };
+    let bridge = createBridge();
+    let repaired = false;
+    let connected = false;
+    let backoffMs = 1_000;
+    while (!controller.signal.aborted) {
+        try {
+            if (!connected) {
+                await bridge.connect();
+                connected = true;
+                backoffMs = 1_000;
+                console.log(`Cozibud relay connected with ${driver.label}. No local or LAN listener is open.`);
+            }
+            const state = await bridge.step();
+            if (state === "idle")
+                await pause(1_000, controller.signal);
+        }
+        catch (error) {
+            if (error instanceof RelayTransportError && [401, 403, 404].includes(error.status)) {
+                await bridge.close();
+                if ([401, 403].includes(error.status) && !process.env.COZIBUD_RELAY_CREDENTIAL?.trim() && !repaired && !controller.signal.aborted) {
+                    repaired = true;
+                    console.log("This computer's pairing is no longer valid. Approve it again to reconnect.");
+                    credential = await pairRelay({ origin: baseUrl, name: value(args, "--name", hostname()), path: pairingPath(), write: console.log, signal: controller.signal });
+                    bridge = createBridge();
+                    connected = false;
+                    continue;
+                }
+                throw new Error("Desktop pairing is expired, revoked, or disabled. Run pair again on the selected server.");
+            }
+            connected = false;
+            console.error("Cozibud relay disconnected; retrying the outbound connection.");
+            await pause(backoffMs, controller.signal);
+            backoffMs = Math.min(15_000, backoffMs * 2);
+        }
+    }
+    await bridge.close();
+}
+function pairingPath() { return process.env.COZIBUD_RELAY_PAIRING?.trim() || join(homedir(), ".cozibud", "relay-pairing.json"); }
 async function ask(args) {
     const provider = value(args, "--provider", "codex");
     const locale = value(args, "--locale", "en-US");
@@ -118,6 +193,11 @@ try {
     }
     else if (command === "ask")
         await ask(args);
+    else if (command === "relay")
+        await relay(args);
+    else if (command === "pair")
+        await pairRelay({ origin: process.env.COZIBUD_RELAY_URL || "https://cozibud.com",
+            name: value(args, "--name", hostname()), path: pairingPath(), write: console.log });
     else if (command === "serve")
         await serve(args);
     else
@@ -127,3 +207,12 @@ catch (error) {
     console.error(error instanceof Error ? error.message : "The local harness failed.");
     process.exitCode = 1;
 }
+function pause(ms, signal) {
+    return new Promise(resolve => {
+        const done = () => { clearTimeout(timer); signal.removeEventListener("abort", done); resolve(); };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+        if (signal.aborted)
+            done();
+    });
+}

package/dist/contracts.d.ts

@@ -7,6 +7,10 @@ export interface HarnessTurnInput {
     source: HarnessInputSource;
     client: HarnessClient;
     locale?: string;
+    /** Server request-bound identity that every care-record write must use. */
+    careRecordIdempotencyKey?: string;
+    /** Server-supplied interpretation instructions; no MCP writes in this mode. */
+    interpretation?: string;
 }
 export interface HarnessTurnRequest extends HarnessTurnInput {
     harness: string;

package/dist/cursor-workspace.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_CURSOR_WORKSPACE: string;
+export declare function cursorWorkspacePath(configured?: string | undefined): string;
+export declare function ensureCursorWorkspace(configured?: string): string;

package/dist/cursor-workspace.js

@@ -0,0 +1,39 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+export const DEFAULT_CURSOR_WORKSPACE = join(homedir(), ".cozibud", "cursor-workspace");
+export function cursorWorkspacePath(configured = process.env.COZIBUD_CURSOR_WORKSPACE) {
+    const override = configured?.trim();
+    if (override && !isAbsolute(override))
+        throw new Error("COZIBUD_CURSOR_WORKSPACE must be an absolute path.");
+    const candidate = override || DEFAULT_CURSOR_WORKSPACE;
+    return resolve(candidate);
+}
+export function ensureCursorWorkspace(configured) {
+    const workspace = cursorWorkspacePath(configured);
+    const root = parse(workspace).root;
+    const current = resolve(process.cwd());
+    const isWithin = (parent, candidate) => {
+        const path = relative(parent, candidate);
+        return path !== "" && !isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`);
+    };
+    if (workspace === root || workspace === current || isWithin(current, workspace) || isWithin(workspace, current)) {
+        throw new Error("Cursor bridge workspace must be dedicated and outside the current repository or worktree.");
+    }
+    try {
+        const state = lstatSync(workspace);
+        if (state.isSymbolicLink() || !state.isDirectory()) {
+            throw new Error("Cursor bridge workspace must be a real directory, not a file or symbolic link.");
+        }
+        if (readdirSync(workspace).length !== 0) {
+            throw new Error("Cursor bridge workspace must be empty and dedicated to Cozibud.");
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        mkdirSync(workspace, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(workspace, 0o700);
+    return workspace;
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from "./process-driver.js";
 export * from "./runtime.js";
 export * from "./server.js";
 export * from "./setup.js";
+export * from "./relay-client.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export * from "./process-driver.js";
 export * from "./runtime.js";
 export * from "./server.js";
 export * from "./setup.js";
+export * from "./relay-client.js";

package/dist/pairing-secret.d.ts

@@ -0,0 +1,8 @@
+export declare function protectPairing(value: string): Promise<{
+    protection: string;
+    value: string;
+}>;
+export declare function unprotectPairing(row: {
+    protection: string;
+    value: string;
+}): Promise<string>;

package/dist/pairing-secret.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+/** Windows DPAPI binds the pairing secret to the signed-in OS user. */
+async function dpapi(value, decrypt) {
+    const script = [
+        "Add-Type -AssemblyName System.Security;",
+        "$inputValue = [Console]::In.ReadToEnd();",
+        decrypt
+            ? "$bytes = [Convert]::FromBase64String($inputValue); $plain = [Security.Cryptography.ProtectedData]::Unprotect($bytes,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser); [Console]::Out.Write([Text.Encoding]::UTF8.GetString($plain));"
+            : "$bytes = [Text.Encoding]::UTF8.GetBytes($inputValue); $protected = [Security.Cryptography.ProtectedData]::Protect($bytes,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser); [Console]::Out.Write([Convert]::ToBase64String($protected));",
+    ].join("\n");
+    return new Promise((resolve, reject) => {
+        const child = spawn(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { windowsHide: true, stdio: ["pipe", "pipe", "ignore"] });
+        let output = "";
+        const timer = setTimeout(() => child.kill(), 10_000);
+        child.stdout.on("data", chunk => { output += chunk.toString(); });
+        child.stdin.on("error", () => { });
+        child.once("error", () => { clearTimeout(timer); reject(new Error("Could not access the protected desktop pairing.")); });
+        child.once("close", code => { clearTimeout(timer); code === 0 ? resolve(output) : reject(new Error("Could not access the protected desktop pairing. Pair again on this computer.")); });
+        // Plaintext never appears in argv, environment values or diagnostics.
+        child.stdin.end(value);
+    });
+}
+export async function protectPairing(value) {
+    return process.platform === "win32" ? { protection: "dpapi", value: await dpapi(value, false) }
+        : { protection: "user-file", value };
+}
+export async function unprotectPairing(row) {
+    if (row.protection === "dpapi" && process.platform === "win32")
+        return dpapi(row.value, true);
+    if (row.protection === "user-file" && process.platform !== "win32")
+        return row.value;
+    throw new Error("This pairing cannot be used on this computer. Run pair again.");
+}

package/dist/pairing.d.ts

@@ -0,0 +1,14 @@
+export declare function relayOrigin(value: string): string;
+export declare function readPairing(path: string, origin: string): Promise<string | null>;
+export declare function pairRelay(options: {
+    origin: string;
+    name: string;
+    path: string;
+    write: (message: string) => void;
+    fetchImpl?: typeof fetch;
+    wait?: (ms: number) => Promise<void>;
+    now?: () => number;
+    signal?: AbortSignal;
+}): Promise<string>;
+/** Relay is also the first-run setup command; approval remains in the browser. */
+export declare function ensureRelayPairing(options: Parameters<typeof pairRelay>[0]): Promise<string>;

package/dist/pairing.js

@@ -0,0 +1,87 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { protectPairing, unprotectPairing } from "./pairing-secret.js";
+export function relayOrigin(value) {
+    const url = new URL(value);
+    if (url.username || url.password || url.pathname !== "/" || url.search || url.hash ||
+        (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) {
+        throw new Error("Use an HTTPS server origin, or HTTP on loopback for local testing.");
+    }
+    return url.origin;
+}
+export async function readPairing(path, origin) {
+    try {
+        const row = JSON.parse(await unprotectPairing(JSON.parse(await readFile(path, "utf8"))));
+        if (row.origin !== relayOrigin(origin) || !Number.isFinite(Date.parse(row.expiresAt)) || Date.parse(row.expiresAt) <= Date.now())
+            return null;
+        if (typeof row.credential !== "string" || !row.credential.startsWith("cbr_"))
+            throw new Error("Invalid local pairing. Run pair again.");
+        return row.credential;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function pairRelay(options) {
+    const origin = relayOrigin(options.origin), fetcher = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const wait = options.wait ?? (ms => new Promise((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); options.signal?.removeEventListener("abort", abort); };
+        const done = () => { cleanup(); resolve(); };
+        const abort = () => { cleanup(); reject(options.signal?.reason); };
+        const timer = setTimeout(done, ms);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+    }));
+    const post = (path, body) => fetcher(`${origin}${path}`, { method: "POST", redirect: "error",
+        headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000) });
+    const response = await post("/api/watch-relay/v1/bridge-authorizations", { bridgeName: options.name });
+    if (!response.ok)
+        throw new Error(response.status === 404 ? "Watch voice is not enabled on this server yet." : "Could not start desktop pairing. Try again later.");
+    const authorization = await response.json();
+    if (!authorization.device_code || !authorization.user_code || !Number.isFinite(authorization.expires_in) || !Number.isFinite(authorization.interval))
+        throw new Error("Invalid pairing response.");
+    const activation = new URL("/watch/activate", origin);
+    activation.searchParams.set("bridge", "1");
+    activation.searchParams.set("code", authorization.user_code);
+    options.write(`Open ${activation.href}\nSign in to your Cozibud household and approve ${options.name}.`);
+    const deadline = now() + authorization.expires_in * 1000;
+    let interval = Math.max(5, authorization.interval);
+    while (now() < deadline) {
+        await wait(interval * 1000);
+        options.signal?.throwIfAborted();
+        if (now() >= deadline)
+            break;
+        const exchange = await post("/api/watch-relay/v1/token", { deviceCode: authorization.device_code });
+        const result = await exchange.json();
+        if (exchange.ok && result.credential?.startsWith("cbr_") && Number.isFinite(result.expiresIn)) {
+            await mkdir(dirname(options.path), { recursive: true, mode: 0o700 });
+            const protectedPairing = await protectPairing(JSON.stringify({ origin, credential: result.credential, bridgeId: result.bridgeId,
+                expiresAt: new Date(now() + result.expiresIn * 1000).toISOString() }));
+            await writeFile(options.path, JSON.stringify(protectedPairing), { mode: 0o600 });
+            if (process.platform !== "win32")
+                await chmod(options.path, 0o600);
+            options.write("Desktop paired.");
+            return result.credential;
+        }
+        if (result.error?.code === "authorization_pending")
+            continue;
+        if (result.error?.code === "slow_down" || exchange.status === 429) {
+            interval += 5;
+            continue;
+        }
+        throw new Error("Pairing was denied or expired. Run pair again.");
+    }
+    throw new Error("Pairing expired. Run pair again.");
+}
+/** Relay is also the first-run setup command; approval remains in the browser. */
+export async function ensureRelayPairing(options) {
+    const saved = await readPairing(options.path, options.origin);
+    if (saved)
+        return saved;
+    options.write("This computer needs pairing. Approve it in Cozibud; the relay will start automatically.");
+    return pairRelay(options);
+}

package/dist/process-driver.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessDriver } from "./contracts.js";
+import type { HarnessDriver, HarnessTurnInput } from "./contracts.js";
 declare const TEMP_DIRECTORY_CLEANUP_OPTIONS: {
     readonly recursive: true;
     readonly force: true;
@@ -13,7 +13,7 @@ export interface ProcessHarnessDefinition {
     versionArgs?: string[];
     /** Applied only to a fresh empty directory created by this driver. */
     emptyDirectoryArgs?: string[];
-    args(): string[];
+    args(input?: HarnessTurnInput): string[];
 }
 declare function messageText(value: unknown): string | null;
 declare function appendNovelText(current: string, candidate: string): {

package/dist/process-driver.js

@@ -4,9 +4,37 @@ import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { delimiter, isAbsolute, join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
+import { ensureCursorWorkspace } from "./cursor-workspace.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TEMP_DIRECTORY_CLEANUP_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 };
+let cursorRunTail = Promise.resolve();
+async function acquireCursorRun(signal, label) {
+    const predecessor = cursorRunTail.catch(() => undefined);
+    let release;
+    const held = new Promise((resolve) => { release = resolve; });
+    cursorRunTail = predecessor.then(() => held);
+    if (signal.aborted) {
+        void predecessor.then(release);
+        throw new Error(`${label} was cancelled.`);
+    }
+    let cancelWait;
+    const cancelled = new Promise((_, reject) => {
+        cancelWait = () => reject(new Error(`${label} was cancelled.`));
+        signal.addEventListener("abort", cancelWait, { once: true });
+    });
+    try {
+        await Promise.race([predecessor, cancelled]);
+    }
+    catch (error) {
+        void predecessor.then(release);
+        throw error;
+    }
+    finally {
+        signal.removeEventListener("abort", cancelWait);
+    }
+    return release;
+}
 function stopProcess(child) {
     if (!child.pid || child.exitCode !== null)
         return;
@@ -24,6 +52,8 @@ function stopProcess(child) {
     }
 }
 function carePrompt(input) {
+    if (input.interpretation)
+        return `${input.interpretation}\n<caregiver_request>\n${input.prompt}\n</caregiver_request>`;
     const origin = `${input.client} ${input.source}`;
     return [
         "You are handling a Cozibud family-care request.",
@@ -31,6 +61,10 @@ function carePrompt(input) {
         "Do not inspect or modify local files and do not run shell commands.",
         "Ask a short follow-up only when ambiguity would make a care record incorrect.",
         "Otherwise return a concise, spoken-friendly answer and confirm writes only after the tool succeeds.",
+        ...(input.careRecordIdempotencyKey ? [
+            `For every Cozibud care-record write in this turn, pass clientEventId exactly ${input.careRecordIdempotencyKey}.`,
+            "Do not claim that a care record was saved unless the Cozibud tool succeeds with that identity.",
+        ] : []),
         `Input origin: ${origin}. Locale: ${input.locale ?? "unspecified"}.`,
         "<caregiver_request>",
         input.prompt,
@@ -88,8 +122,9 @@ export function createProcessHarnessDriver(definition, options = {}) {
         command: definition.command,
         authentication: "existing-login",
         async probe() {
+            const probeCwd = definition.id === "cursor" ? ensureCursorWorkspace(options.cwd) : options.cwd;
             return await new Promise((resolve) => {
-                const child = spawn(definition.command, definition.versionArgs ?? ["--version"], { ...spawnOptions, stdio: ["ignore", "pipe", "pipe"] });
+                const child = spawn(definition.command, definition.versionArgs ?? ["--version"], { ...spawnOptions, cwd: probeCwd, stdio: ["ignore", "pipe", "pipe"] });
                 let output = "";
                 let bytes = 0;
                 let overflow = false;
@@ -124,130 +159,139 @@ export function createProcessHarnessDriver(definition, options = {}) {
         async run(input, context) {
             if (context.signal.aborted)
                 throw new Error(`${definition.label} was cancelled.`);
-            const ephemeralCwd = options.cwd ? null : await mkdtemp(join(tmpdir(), "cozibud-harness-"));
-            let turnError;
+            const releaseCursor = definition.id === "cursor" ? await acquireCursorRun(context.signal, definition.label) : undefined;
             try {
-                if (context.signal.aborted)
-                    throw new Error(`${definition.label} was cancelled.`);
-                return await new Promise((resolve, reject) => {
-                    const args = [...definition.args(), ...(ephemeralCwd ? definition.emptyDirectoryArgs ?? [] : [])];
-                    const child = spawn(definition.command, args, { ...spawnOptions, cwd: options.cwd ?? ephemeralCwd, stdio: ["pipe", "pipe", "pipe"] });
-                    child.stdin.on("error", () => { });
-                    child.stdin.end(carePrompt(input));
-                    const decoder = new StringDecoder("utf8");
-                    let pending = "";
-                    let response = "";
-                    let outputBytes = 0;
-                    let settled = false;
-                    let timedOut = false;
-                    let failure;
-                    let stopping = false;
-                    const stop = () => { if (!stopping) {
-                        stopping = true;
-                        stopProcess(child);
-                    } };
-                    const finish = (error) => {
-                        if (settled)
-                            return;
-                        settled = true;
-                        clearTimeout(timer);
-                        context.signal.removeEventListener("abort", abort);
-                        if (error)
-                            reject(error);
-                        else
-                            resolve({ text: response.trim() });
-                    };
-                    const abort = () => stop();
-                    context.signal.addEventListener("abort", abort, { once: true });
-                    const timer = setTimeout(() => { timedOut = true; stop(); }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-                    const lineReceived = (line) => {
-                        if (failure || context.signal.aborted || timedOut)
-                            return;
-                        try {
-                            const event = JSON.parse(line);
-                            if (event?.type === "error" && event.severity === "warning")
+                const stableCwd = definition.id === "cursor" ? ensureCursorWorkspace(options.cwd) : options.cwd;
+                const ephemeralCwd = stableCwd ? null : await mkdtemp(join(tmpdir(), "cozibud-harness-"));
+                let turnError;
+                try {
+                    if (context.signal.aborted)
+                        throw new Error(`${definition.label} was cancelled.`);
+                    return await new Promise((resolve, reject) => {
+                        const args = [...definition.args(input), ...(ephemeralCwd ? definition.emptyDirectoryArgs ?? [] : [])];
+                        const child = spawn(definition.command, args, { ...spawnOptions, cwd: stableCwd ?? ephemeralCwd, stdio: ["pipe", "pipe", "pipe"] });
+                        child.stdin.on("error", () => { });
+                        child.stdin.end(carePrompt(input));
+                        const decoder = new StringDecoder("utf8");
+                        let pending = "";
+                        let response = "";
+                        let outputBytes = 0;
+                        let settled = false;
+                        let timedOut = false;
+                        let failure;
+                        let stopping = false;
+                        const stop = () => { if (!stopping) {
+                            stopping = true;
+                            stopProcess(child);
+                        } };
+                        const finish = (error) => {
+                            if (settled)
                                 return;
-                            if (event && (event.is_error === true || event.type === "error" || event.type === "turn.failed" || event.error)) {
-                                failure = new Error(`${definition.label} reported a failed turn. Check the client's sign-in, subscription, and Cozibud MCP authorization, then retry.`);
-                                stop();
+                            settled = true;
+                            clearTimeout(timer);
+                            context.signal.removeEventListener("abort", abort);
+                            if (error)
+                                reject(error);
+                            else
+                                resolve({ text: response.trim() });
+                        };
+                        const abort = () => stop();
+                        context.signal.addEventListener("abort", abort, { once: true });
+                        const timer = setTimeout(() => { timedOut = true; stop(); }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+                        const lineReceived = (line) => {
+                            if (failure || context.signal.aborted || timedOut)
                                 return;
+                            try {
+                                const event = JSON.parse(line);
+                                if (event?.type === "error" && event.severity === "warning")
+                                    return;
+                                if (event && (event.is_error === true || event.type === "error" || event.type === "turn.failed" || event.error)) {
+                                    failure = new Error(`${definition.label} reported a failed turn. Check the client's sign-in, subscription, and Cozibud MCP authorization, then retry.`);
+                                    stop();
+                                    return;
+                                }
+                                const candidate = messageText(event);
+                                if (!candidate)
+                                    return;
+                                const next = event.type === "message" && event.delta === true
+                                    ? { value: response + candidate, delta: candidate }
+                                    : appendNovelText(response, candidate);
+                                response = next.value;
+                                if (next.delta)
+                                    context.emit({ type: "assistant.delta", text: next.delta });
+                            }
+                            catch {
+                                // Never return provider diagnostics as household answers.
+                            }
+                        };
+                        const count = (chunk) => {
+                            outputBytes += chunk.length;
+                            if (outputBytes <= MAX_OUTPUT_BYTES && !failure)
+                                return true;
+                            if (!failure) {
+                                failure = new Error("Harness output exceeded the 1 MiB safety limit.");
+                                pending = "";
+                                stop();
                             }
-                            const candidate = messageText(event);
-                            if (!candidate)
+                            return false;
+                        };
+                        child.stderr.on("data", (chunk) => { count(chunk); });
+                        child.stdout.on("data", (chunk) => {
+                            if (!count(chunk))
                                 return;
-                            const next = event.type === "message" && event.delta === true
-                                ? { value: response + candidate, delta: candidate }
-                                : appendNovelText(response, candidate);
-                            response = next.value;
-                            if (next.delta)
-                                context.emit({ type: "assistant.delta", text: next.delta });
+                            pending += decoder.write(chunk);
+                            let newline;
+                            while ((newline = pending.indexOf("\n")) >= 0) {
+                                const line = pending.slice(0, newline);
+                                pending = pending.slice(newline + 1);
+                                lineReceived(line);
+                            }
+                        });
+                        child.once("error", (error) => {
+                            finish(new Error(error.code === "ENOENT" ? `${definition.command} is not installed or is not on PATH.` : `${definition.label} failed to start.`));
+                        });
+                        child.once("close", (code) => {
+                            if (failure)
+                                return finish(failure);
+                            if (timedOut)
+                                return finish(new Error(`${definition.label} timed out.`));
+                            if (context.signal.aborted)
+                                return finish(new Error(`${definition.label} was cancelled.`));
+                            if (code !== 0)
+                                return finish(new Error(`${definition.label} exited with code ${code ?? "unknown"}. Check the client's sign-in, subscription, and Cozibud MCP authorization.`));
+                            lineReceived(pending + decoder.end());
+                            if (failure)
+                                return finish(failure);
+                            if (!response.trim())
+                                return finish(new Error(`${definition.label} returned no assistant response.`));
+                            finish();
+                        });
+                    });
+                }
+                catch (error) {
+                    turnError = error;
+                    throw error;
+                }
+                finally {
+                    if (definition.id === "cursor" && stableCwd)
+                        ensureCursorWorkspace(stableCwd);
+                    if (ephemeralCwd) {
+                        try {
+                            await (options.removeDirectory ?? rm)(ephemeralCwd, TEMP_DIRECTORY_CLEANUP_OPTIONS);
                         }
                         catch {
-                            // Never return provider diagnostics as household answers.
-                        }
-                    };
-                    const count = (chunk) => {
-                        outputBytes += chunk.length;
-                        if (outputBytes <= MAX_OUTPUT_BYTES && !failure)
-                            return true;
-                        if (!failure) {
-                            failure = new Error("Harness output exceeded the 1 MiB safety limit.");
-                            pending = "";
-                            stop();
-                        }
-                        return false;
-                    };
-                    child.stderr.on("data", (chunk) => { count(chunk); });
-                    child.stdout.on("data", (chunk) => {
-                        if (!count(chunk))
-                            return;
-                        pending += decoder.write(chunk);
-                        let newline;
-                        while ((newline = pending.indexOf("\n")) >= 0) {
-                            const line = pending.slice(0, newline);
-                            pending = pending.slice(newline + 1);
-                            lineReceived(line);
+                            const cleanupWarning = "Temporary working-directory cleanup did not complete.";
+                            if (turnError instanceof Error)
+                                turnError.message = `${turnError.message} ${cleanupWarning}`;
+                            else
+                                throw new Error(`${definition.label} completed, but temporary working-directory cleanup did not complete.`);
                         }
-                    });
-                    child.once("error", (error) => {
-                        finish(new Error(error.code === "ENOENT" ? `${definition.command} is not installed or is not on PATH.` : `${definition.label} failed to start.`));
-                    });
-                    child.once("close", (code) => {
-                        if (failure)
-                            return finish(failure);
-                        if (timedOut)
-                            return finish(new Error(`${definition.label} timed out.`));
-                        if (context.signal.aborted)
-                            return finish(new Error(`${definition.label} was cancelled.`));
-                        if (code !== 0)
-                            return finish(new Error(`${definition.label} exited with code ${code ?? "unknown"}. Check the client's sign-in, subscription, and Cozibud MCP authorization.`));
-                        lineReceived(pending + decoder.end());
-                        if (failure)
-                            return finish(failure);
-                        if (!response.trim())
-                            return finish(new Error(`${definition.label} returned no assistant response.`));
-                        finish();
-                    });
-                });
-            }
-            catch (error) {
-                turnError = error;
-                throw error;
-            }
-            finally {
-                if (ephemeralCwd) {
-                    try {
-                        await (options.removeDirectory ?? rm)(ephemeralCwd, TEMP_DIRECTORY_CLEANUP_OPTIONS);
-                    }
-                    catch {
-                        const cleanupWarning = "Temporary working-directory cleanup did not complete.";
-                        if (turnError instanceof Error)
-                            turnError.message = `${turnError.message} ${cleanupWarning}`;
-                        else
-                            throw new Error(`${definition.label} completed, but temporary working-directory cleanup did not complete.`);
                     }
                 }
             }
+            finally {
+                releaseCursor?.();
+            }
         },
     };
 }
@@ -284,7 +328,8 @@ export const builtInProcessHarnesses = [
         label: "Codex CLI",
         command: codexExecutable.command,
         versionArgs: [...codexExecutable.prefixArgs, "--version"],
-        args: () => [...codexExecutable.prefixArgs, "exec", "--json", "--ephemeral", "--skip-git-repo-check", "--sandbox", "read-only", "-c", "mcp_servers.cozibud.required=true", "-"],
+        args: (input) => [...codexExecutable.prefixArgs, "exec", "--json", "--ephemeral", "--skip-git-repo-check", "--sandbox", "read-only",
+            ...(input?.interpretation ? ["--ignore-user-config", "--ignore-rules", "-c", "features.shell_tool=false", "-c", "features.apps=false", "-c", "features.multi_agent=false", "-c", "features.hooks=false", "-c", "web_search=\"disabled\""] : ["-c", "mcp_servers.cozibud.required=true"]), "-"],
     },
     {
         id: "claude",
@@ -305,9 +350,13 @@ export const builtInProcessHarnesses = [
         id: "cursor",
         label: "Cursor Agent",
         command: cursorExecutable.command,
-        emptyDirectoryArgs: ["--trust"],
         versionArgs: [...cursorExecutable.prefixArgs, "--version"],
-        args: () => [...cursorExecutable.prefixArgs, "-p", "--output-format", "stream-json"],
+        args: () => [
+            ...cursorExecutable.prefixArgs,
+            "-p", "--output-format", "stream-json", "--mode", "ask",
+            ...(process.platform === "win32" ? [] : ["--sandbox", "enabled"]),
+            "--trust",
+        ],
     },
 ];
 export function createBuiltInDrivers() {

package/dist/relay-client.d.ts

@@ -0,0 +1,69 @@
+import type { HarnessDriver } from "./contracts.js";
+export type StoredExecution = {
+    state: "started";
+    updatedAt: string;
+} | {
+    state: "completed";
+    modelOutput: string;
+    updatedAt: string;
+} | {
+    state: "failed" | "cancelled";
+    code: string;
+    message: string;
+    updatedAt: string;
+};
+export interface RelayExecutionStore {
+    get(requestId: string): Promise<StoredExecution | null>;
+    set(requestId: string, value: StoredExecution): Promise<void>;
+}
+export declare class MemoryRelayExecutionStore implements RelayExecutionStore {
+    private readonly values;
+    get(id: string): Promise<StoredExecution | null>;
+    set(id: string, value: StoredExecution): Promise<void>;
+}
+/** Privacy-bounded local journal: request ids and terminal results only, never prompts or credentials. */
+export declare class FileRelayExecutionStore implements RelayExecutionStore {
+    private readonly path;
+    private readonly maxEntries;
+    private readonly retentionMs;
+    private writeQueue;
+    constructor(path: string, maxEntries?: number, retentionMs?: number);
+    private read;
+    get(id: string): Promise<StoredExecution | null>;
+    set(id: string, value: StoredExecution): Promise<void>;
+    private write;
+}
+type Fetch = typeof fetch;
+export declare class RelayTransportError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+export declare class OutboundRelayBridge {
+    private readonly options;
+    readonly connectionId: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly active;
+    private readonly tasks;
+    private readonly scheduled;
+    private readonly cancelled;
+    constructor(options: {
+        baseUrl: string;
+        credential: string;
+        driver: HarnessDriver;
+        store: RelayExecutionStore;
+        fetchImpl?: Fetch;
+        maxActive?: number;
+    });
+    private get fetcher();
+    private headers;
+    private json;
+    connect(): Promise<unknown>;
+    step(): Promise<"idle" | "command" | "cancel">;
+    idle(): Promise<void>;
+    close(): Promise<void>;
+    private acknowledge;
+    private result;
+    private fromStored;
+    private handle;
+}
+export {};

package/dist/relay-client.js

@@ -0,0 +1,166 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { WATCH_RELAY_PROTOCOL_VERSION } from "./relay-protocol.js";
+export class MemoryRelayExecutionStore {
+    values = new Map();
+    async get(id) { return this.values.get(id) ?? null; }
+    async set(id, value) { this.values.set(id, value); }
+}
+/** Privacy-bounded local journal: request ids and terminal results only, never prompts or credentials. */
+export class FileRelayExecutionStore {
+    path;
+    maxEntries;
+    retentionMs;
+    writeQueue = Promise.resolve();
+    constructor(path, maxEntries = 100, retentionMs = 24 * 60 * 60_000) {
+        this.path = path;
+        this.maxEntries = maxEntries;
+        this.retentionMs = retentionMs;
+    }
+    async read() {
+        try {
+            return JSON.parse(await readFile(this.path, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    }
+    async get(id) { await this.writeQueue; return (await this.read())[id] ?? null; }
+    async set(id, value) {
+        const write = this.writeQueue.then(() => this.write(id, value));
+        this.writeQueue = write.catch(() => { });
+        await write;
+    }
+    async write(id, value) {
+        const values = await this.read();
+        values[id] = value;
+        const cutoff = Date.now() - this.retentionMs;
+        const retained = Object.entries(values).filter(([, row]) => Date.parse(row.updatedAt) >= cutoff)
+            .sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt)).slice(0, this.maxEntries);
+        await mkdir(dirname(this.path), { recursive: true });
+        const temporary = `${this.path}.${process.pid}.tmp`;
+        await writeFile(temporary, JSON.stringify(Object.fromEntries(retained)), { encoding: "utf8", mode: 0o600 });
+        await rename(temporary, this.path);
+    }
+}
+export class RelayTransportError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super("Cozibud relay request failed.");
+        this.status = status;
+        this.code = code;
+    }
+}
+export class OutboundRelayBridge {
+    options;
+    connectionId = randomUUID();
+    active = new Map();
+    tasks = new Set();
+    scheduled = new Set();
+    cancelled = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get fetcher() { return this.options.fetchImpl ?? fetch; }
+    headers(extra) { return { authorization: `Bearer ${this.options.credential}`, ...extra }; }
+    async json(path, init) {
+        const response = await this.fetcher(new URL(path, this.options.baseUrl), { ...init, redirect: "error", signal: AbortSignal.timeout(20_000) });
+        if (!response.ok) {
+            const code = await response.json().then(value => value.error?.code).catch(() => undefined);
+            throw new RelayTransportError(response.status, code ?? `relay_http_${response.status}`);
+        }
+        return response.status === 204 ? null : response.json();
+    }
+    async connect() {
+        return this.json("/api/watch-relay/v1/connect", { method: "POST", headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ connectionId: this.connectionId, protocolVersion: WATCH_RELAY_PROTOCOL_VERSION }) });
+    }
+    async step() {
+        const full = this.scheduled.size >= (this.options.maxActive ?? 2);
+        const delivery = await this.json(`/api/watch-relay/v1/deliveries/next${full ? "?cancelOnly=1" : ""}`, { method: "GET",
+            headers: this.headers({ "x-cozibud-connection": this.connectionId }) });
+        if (!delivery)
+            return "idle";
+        if (delivery.type === "cancel") {
+            this.cancelled.add(delivery.requestId);
+            this.active.get(delivery.requestId)?.abort();
+            return "cancel";
+        }
+        if (this.scheduled.has(delivery.command.requestId)) {
+            await this.acknowledge(delivery.command);
+            return "command";
+        }
+        this.scheduled.add(delivery.command.requestId);
+        // A transport loss after the local terminal result is journaled is
+        // recovered by stable-id redelivery; do not turn it into an unhandled
+        // rejection or execute the provider again.
+        const task = this.handle(delivery.command).catch(() => { }).finally(() => { this.scheduled.delete(delivery.command.requestId); this.tasks.delete(task); });
+        this.tasks.add(task);
+        return "command";
+    }
+    async idle() { await Promise.all(this.tasks); }
+    async close() { for (const controller of this.active.values())
+        controller.abort(); await this.idle(); }
+    async acknowledge(command) {
+        await this.json(`/api/watch-relay/v1/deliveries/${command.deliveryId}/ack`, { method: "POST", headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ requestId: command.requestId, connectionId: this.connectionId }) });
+    }
+    async result(command, result) {
+        await this.json(`/api/watch-relay/v1/deliveries/${command.deliveryId}/result`, { method: "POST", headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ requestId: command.requestId, connectionId: this.connectionId, ...result }) });
+    }
+    fromStored(value) {
+        if (value.state === "completed")
+            return { state: "completed", modelOutput: value.modelOutput };
+        if (value.state === "started")
+            return { state: "failed", error: { code: "execution_interrupted", message: "The prior local execution ended without a durable result; it was not repeated." } };
+        return { state: value.state, error: { code: value.code, message: value.message } };
+    }
+    async handle(command) {
+        if (this.active.has(command.requestId)) {
+            await this.acknowledge(command);
+            return;
+        }
+        const stored = await this.options.store.get(command.requestId);
+        if (stored) {
+            await this.acknowledge(command);
+            await this.result(command, this.fromStored(stored));
+            return;
+        }
+        await this.acknowledge(command);
+        await this.options.store.set(command.requestId, { state: "started", updatedAt: new Date().toISOString() });
+        const controller = new AbortController();
+        this.active.set(command.requestId, controller);
+        if (this.cancelled.delete(command.requestId))
+            controller.abort();
+        let terminal;
+        if (controller.signal.aborted) {
+            terminal = { state: "cancelled", code: "cancelled", message: "The request was cancelled.", updatedAt: new Date().toISOString() };
+        }
+        else
+            try {
+                const prompt = command.transcript ?? JSON.stringify(command.action);
+                const source = command.source === "structured-action" ? "quick-action" : command.source;
+                const output = await this.options.driver.run({ prompt, source, client: command.client,
+                    interpretation: command.interpretation,
+                    careRecordIdempotencyKey: `relay:${command.requestId}` }, {
+                    turnId: command.requestId, signal: controller.signal,
+                    // Progress remains local in v1; bounded server progress is reserved by the protocol.
+                    emit: () => { },
+                });
+                terminal = { state: "completed", modelOutput: output.text, updatedAt: new Date().toISOString() };
+            }
+            catch (error) {
+                const cancelled = controller.signal.aborted;
+                terminal = { state: cancelled ? "cancelled" : "failed", code: cancelled ? "cancelled" : "provider_failed",
+                    message: cancelled ? "The request was cancelled." : (error instanceof Error ? error.message.slice(0, 512) : "The local provider failed."), updatedAt: new Date().toISOString() };
+            }
+        this.active.delete(command.requestId);
+        await this.options.store.set(command.requestId, terminal);
+        await this.result(command, this.fromStored(terminal));
+    }
+}

package/dist/relay-protocol.d.ts

@@ -0,0 +1,18 @@
+/** Versioned wire values consumed by the outbound Cozibud relay client. */
+export declare const WATCH_RELAY_PROTOCOL: "cozibud.watch-relay.v2";
+export declare const WATCH_RELAY_PROTOCOL_VERSION: 2;
+export type WatchRelayCommand = Readonly<{
+    protocol: typeof WATCH_RELAY_PROTOCOL;
+    requestId: string;
+    deliveryId: string;
+    attempt: number;
+    source: "typed" | "voice-transcript" | "structured-action";
+    client: "web" | "phone" | "watch";
+    transcript?: string;
+    action?: Readonly<{
+        id: string;
+        arguments: Readonly<Record<string, unknown>>;
+    }>;
+    expiresAt: string;
+    interpretation?: string;
+}>;

package/dist/relay-protocol.js

@@ -0,0 +1,3 @@
+/** Versioned wire values consumed by the outbound Cozibud relay client. */
+export const WATCH_RELAY_PROTOCOL = "cozibud.watch-relay.v2";
+export const WATCH_RELAY_PROTOCOL_VERSION = 2;

package/dist/setup.d.ts

@@ -7,6 +7,7 @@ export type SetupCommandResult = {
 };
 export type SetupCommandRunner = (command: string, args: string[], options: {
     interactive: boolean;
+    cwd?: string;
 }) => Promise<SetupCommandResult>;
 export type SetupWriter = (message: string) => void;
 export declare const runSetupCommand: SetupCommandRunner;
@@ -23,6 +24,7 @@ export declare function setupProvider(options?: {
     run?: SetupCommandRunner;
     write?: SetupWriter;
     cursorConfig?: CursorMcpConfigStore;
+    cursorWorkspace?: string;
 }): Promise<void>;
 export declare function setupCodex(options?: {
     command?: string;

package/dist/setup.js

@@ -3,11 +3,13 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { executable } from "./process-driver.js";
+import { ensureCursorWorkspace } from "./cursor-workspace.js";
 export const DEFAULT_COZIBUD_MCP_URL = "https://cozibud.com/api/mcp";
 const MAX_SETUP_OUTPUT_BYTES = 64 * 1024;
 export const runSetupCommand = async (command, args, options) => await new Promise((resolve) => {
     const resolved = executable(command);
     const child = spawn(resolved.command, [...resolved.prefixArgs, ...args], {
+        cwd: options.cwd,
         windowsHide: true,
         stdio: options.interactive ? "inherit" : ["ignore", "pipe", "pipe"],
     });
@@ -242,16 +244,22 @@ async function setupCursorProvider(options) {
     const executable = providerCommand("cursor", options.command);
     const args = (...values) => [...executable.prefixArgs, ...values];
     const missing = `Cursor Agent is not installed or is not on PATH. Install it from ${installUrl("cursor")} and run setup again.`;
+    const cwd = ensureCursorWorkspace(options.workspace);
+    const runInWorkspace = async (values, interactive) => {
+        const result = await options.run(executable.command, values, { interactive, cwd: ensureCursorWorkspace(cwd) });
+        ensureCursorWorkspace(cwd);
+        return result;
+    };
     options.write("Checking Cursor Agent…");
-    requireSuccess(await options.run(executable.command, args("--version"), { interactive: false }), missing, "Cursor Agent was found but could not be started.");
-    const login = await options.run(executable.command, args("status"), { interactive: false });
+    requireSuccess(await runInWorkspace(args("--version"), false), missing, "Cursor Agent was found but could not be started.");
+    const login = await runInWorkspace(args("status"), false);
     if (!succeeded(login)) {
         options.write("Opening Cursor sign-in in your browser…");
-        requireSuccess(await options.run(executable.command, args("login"), { interactive: true }), missing, "Cursor sign-in did not complete.");
+        requireSuccess(await runInWorkspace(args("login"), true), missing, "Cursor sign-in did not complete.");
     }
     else
         options.write("Cursor sign-in is ready.");
-    requireSuccess(await options.run(executable.command, args("status"), { interactive: false }), missing, "Cursor still reports that you are signed out.");
+    requireSuccess(await runInWorkspace(args("status"), false), missing, "Cursor still reports that you are signed out.");
     const currentConfig = await options.config.read();
     if (cursorConfiguredUrl(currentConfig) !== options.mcpUrl) {
         options.write("Adding the Cozibud connection to Cursor's user MCP configuration…");
@@ -260,8 +268,8 @@ async function setupCursorProvider(options) {
     else
         options.write("The Cozibud connection is configured with the expected endpoint.");
     options.write("Opening Cozibud sign-in and permission approval in your browser…");
-    requireSuccess(await options.run(executable.command, args("mcp", "login", "cozibud"), { interactive: true }), missing, "Cozibud sign-in or permission approval did not complete.");
-    const verified = await options.run(executable.command, args("mcp", "list"), { interactive: false });
+    requireSuccess(await runInWorkspace(args("mcp", "login", "cozibud"), true), missing, "Cozibud sign-in or permission approval did not complete.");
+    const verified = await runInWorkspace(args("mcp", "list"), false);
     requireSuccess(verified, missing, "Cursor could not verify the Cozibud MCP connection after sign-in.");
     if (!cursorReportsConnected(verified.output))
         throw new Error("Cursor did not report a ready Cozibud MCP connection after sign-in.");
@@ -277,7 +285,7 @@ export async function setupProvider(options = {}) {
     if (provider === "codex")
         await setupCodexProvider({ command: options.command, mcpUrl, run, write });
     else if (provider === "cursor")
-        await setupCursorProvider({ command: options.command, mcpUrl, run, write, config: options.cursorConfig ?? cursorConfigStore() });
+        await setupCursorProvider({ command: options.command, mcpUrl, run, write, config: options.cursorConfig ?? cursorConfigStore(), workspace: options.cursorWorkspace });
     else
         await setupInteractiveProvider(provider, { command: options.command, mcpUrl, run, write });
 }

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@cozibud/harness",
-  "version": "0.1.0",
-  "description": "Cozibud local-client bridge and CLI.",
-  "type": "module",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rongduan-zhu/cozibud.git",
-    "directory": "packages/harness"
-  },
-  "homepage": "https://github.com/rongduan-zhu/cozibud/tree/main/packages/harness#readme",
-  "bugs": {
-    "url": "https://github.com/rongduan-zhu/cozibud/issues"
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "cozibud-harness": "dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "prepack": "npm run build",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run --root ../.. packages/harness/src"
-  }
-}
+{
+  "name": "@cozibud/harness",
+  "version": "0.2.0",
+  "description": "Cozibud local-client bridge and CLI.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rongduan-zhu/cozibud.git",
+    "directory": "packages/harness"
+  },
+  "homepage": "https://github.com/rongduan-zhu/cozibud/tree/main/packages/harness#readme",
+  "bugs": {
+    "url": "https://github.com/rongduan-zhu/cozibud/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "cozibud-harness": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --root ../.. packages/harness/src"
+  }
+}