@akshar5/cohall 0.10.1 → 0.11.0

package/bin/cohall.js

@@ -17,7 +17,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // packages/protocol/src/index.ts
 import { Effect, Schema } from "effect";
-var version = "0.10.1", maxSocketPayloadBytes, maxAttachmentBytes, maxTaskAttachments = 2, maxProgressNoteBytes = 1024, bounded = (maxLength) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maxLength)), optionalText = (maxLength) => Schema.String.check(Schema.isMaxLength(maxLength)), boundedArray = (schema, maxLength) => Schema.Array(schema).check(Schema.isMaxLength(maxLength)), count, uuid = (name) => Schema.String.check(Schema.isUUID(4)).pipe(Schema.brand(name)), isoTimestamp = (name) => Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/, {
+var version = "0.11.0", maxSocketPayloadBytes, maxAttachmentBytes, maxTaskAttachments = 2, maxProgressNoteBytes = 1024, bounded = (maxLength) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maxLength)), optionalText = (maxLength) => Schema.String.check(Schema.isMaxLength(maxLength)), boundedArray = (schema, maxLength) => Schema.Array(schema).check(Schema.isMaxLength(maxLength)), count, uuid = (name) => Schema.String.check(Schema.isUUID(4)).pipe(Schema.brand(name)), isoTimestamp = (name) => Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/, {
   expected: "an ISO-8601 UTC timestamp"
 })).pipe(Schema.brand(name)), BotId, Bot, DeviceId, ThreadId, MessageId, TaskId, TaskRequestId, TaskRunId, ClarificationId, AuthSessionId, OperationId, Timestamp, TaskDeadline, taskDeadlineError = "Task deadline exceeded", taskDeadlinePassed = (task, time = Date.now()) => task.expiresAt !== undefined && Date.parse(task.expiresAt) <= time, Platform, Provider, DeviceStatus, TaskStatus, OperationStatus, TaskTraceEventKind, MessageRole, ConnectionRole, AuthSession, CreatePairingInput, PairingCredential, ExchangePairingInput, SessionCredential, PairingResult, Capability, Workspace, Device, maxDevicePageDevices = 16, maxDevicePageResponseBytes, DevicePage, minimumDeviceOperationVersion = "0.5.0", parsedVersion = (value) => {
   const match = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
@@ -420,25 +420,25 @@ var init_src = __esm(() => {
 });
 
 // apps/relay/src/config.ts
-import { Effect as Effect13, Schema as Schema14 } from "effect";
-import { access as access5, chmod as chmod7, mkdir as mkdir8, readFile as readFile4, writeFile as writeFile9 } from "node:fs/promises";
+import { Effect as Effect13, Schema as Schema15 } from "effect";
+import { access as access5, chmod as chmod7, mkdir as mkdir9, readFile as readFile4, writeFile as writeFile10 } from "node:fs/promises";
 import { homedir as homedir5, platform as platform5 } from "node:os";
-import { isAbsolute as isAbsolute6, join as join9, resolve as resolve5 } from "node:path";
+import { isAbsolute as isAbsolute6, join as join10, resolve as resolve5 } from "node:path";
 var RelayConfiguration, defaultDataDirectory = () => {
   if (platform5() === "win32") {
-    return join9(process.env.LOCALAPPDATA ?? join9(homedir5(), "AppData", "Local"), "Cohall");
+    return join10(process.env.LOCALAPPDATA ?? join10(homedir5(), "AppData", "Local"), "Cohall");
   }
   if (platform5() === "darwin") {
-    return join9(homedir5(), "Library", "Application Support", "Cohall", "relay");
+    return join10(homedir5(), "Library", "Application Support", "Cohall", "relay");
   }
   const dataHome = process.env.XDG_DATA_HOME;
-  return join9(dataHome !== undefined && isAbsolute6(dataHome) ? dataHome : join9(homedir5(), ".local", "share"), "cohall");
+  return join10(dataHome !== undefined && isAbsolute6(dataHome) ? dataHome : join10(homedir5(), ".local", "share"), "cohall");
 }, generatedToken = () => Array.from(crypto.getRandomValues(new Uint8Array(32)), (value) => value.toString(16).padStart(2, "0")).join(""), tokenFrom = async (path) => {
   if (await access5(path).then(() => true).catch(() => false)) {
     return (await readFile4(path, "utf8")).trim();
   }
   const token = generatedToken();
-  await writeFile9(path, `${token}
+  await writeFile10(path, `${token}
 `, { mode: 384 });
   if (platform5() !== "win32") {
     await chmod7(path, 384);
@@ -455,14 +455,14 @@ var RelayConfiguration, defaultDataDirectory = () => {
   throw new Error(`${name} must be true or false`);
 }, isLoopback2 = (host) => host === "127.0.0.1" || host === "localhost" || host === "::1", loadEnvironmentConfiguration;
 var init_config = __esm(() => {
-  RelayConfiguration = Schema14.Struct({
-    host: Schema14.NonEmptyString,
-    port: Schema14.Int.check(Schema14.isBetween({ minimum: 1, maximum: 65535 })),
-    token: Schema14.String.check(Schema14.isMinLength(32)),
-    dataDirectory: Schema14.NonEmptyString,
-    databasePath: Schema14.NonEmptyString,
-    allowRemote: Schema14.Boolean,
-    historyTaskLimit: Schema14.Int.check(Schema14.isBetween({ minimum: 100, maximum: 1e5 }))
+  RelayConfiguration = Schema15.Struct({
+    host: Schema15.NonEmptyString,
+    port: Schema15.Int.check(Schema15.isBetween({ minimum: 1, maximum: 65535 })),
+    token: Schema15.String.check(Schema15.isMinLength(32)),
+    dataDirectory: Schema15.NonEmptyString,
+    databasePath: Schema15.NonEmptyString,
+    allowRemote: Schema15.Boolean,
+    historyTaskLimit: Schema15.Int.check(Schema15.isBetween({ minimum: 100, maximum: 1e5 }))
   });
   loadEnvironmentConfiguration = Effect13.tryPromise({
     try: async () => {
@@ -473,21 +473,21 @@ var init_config = __esm(() => {
         throw new Error("Remote relay binding is disabled. Use a private network or TLS reverse proxy, then set COHALL_RELAY_ALLOW_REMOTE=true.");
       }
       const dataDirectory = resolve5(process.env.COHALL_DATA_DIR ?? defaultDataDirectory());
-      await mkdir8(dataDirectory, { recursive: true, mode: 448 });
+      await mkdir9(dataDirectory, { recursive: true, mode: 448 });
       if (platform5() !== "win32") {
         await chmod7(dataDirectory, 448);
       }
-      const token = process.env.COHALL_TOKEN ?? await tokenFrom(join9(dataDirectory, "owner-token"));
+      const token = process.env.COHALL_TOKEN ?? await tokenFrom(join10(dataDirectory, "owner-token"));
       if (token.length < 32) {
         throw new Error("The Cohall relay owner token must be at least 32 characters");
       }
       const historyTaskLimit = Number(process.env.COHALL_HISTORY_TASK_LIMIT ?? "1000");
-      return Schema14.decodeUnknownSync(RelayConfiguration)({
+      return Schema15.decodeUnknownSync(RelayConfiguration)({
         host,
         port,
         token,
         dataDirectory,
-        databasePath: join9(dataDirectory, "cohall.db"),
+        databasePath: join10(dataDirectory, "cohall.db"),
         allowRemote,
         historyTaskLimit
       });
@@ -673,12 +673,12 @@ __export(exports_store, {
   RelayStore: () => exports_store,
   PersistenceError: () => PersistenceError
 });
-import { Context as Context2, Effect as Effect14, Layer as Layer2, Schema as Schema15 } from "effect";
+import { Context as Context2, Effect as Effect14, Layer as Layer2, Schema as Schema16 } from "effect";
 import { createHash as createHash2, randomBytes } from "node:crypto";
 var PersistenceError, TaskProgressError, TaskInputError, TaskDeadlineError, TaskRequestError, Service2, operationError = (operation) => (cause) => new PersistenceError({
   operation,
   message: cause instanceof Error ? cause.message : String(cause)
-}), decode2 = (operation, schema, value) => Schema15.decodeUnknownEffect(schema)(value).pipe(Effect14.mapError(operationError(operation))), threadFromRow = (row) => decode2("RelayStore.decodeThread", Thread, {
+}), decode2 = (operation, schema, value) => Schema16.decodeUnknownEffect(schema)(value).pipe(Effect14.mapError(operationError(operation))), threadFromRow = (row) => decode2("RelayStore.decodeThread", Thread, {
   id: row.id,
   title: row.title,
   createdAt: row.created_at,
@@ -777,7 +777,7 @@ var PersistenceError, TaskProgressError, TaskInputError, TaskDeadlineError, Task
   kind: row.kind,
   at: row.created_at,
   ...row.detail === null ? {} : { detail: row.detail }
-}), rolesFromRow = (row) => Schema15.decodeUnknownSync(Schema15.Array(ConnectionRole))(JSON.parse(row.roles_json)), authSessionFromRow = (row) => {
+}), rolesFromRow = (row) => Schema16.decodeUnknownSync(Schema16.Array(ConnectionRole))(JSON.parse(row.roles_json)), authSessionFromRow = (row) => {
   const roles = rolesFromRow(row);
   const role = roles[0];
   return role === undefined ? Effect14.fail(new PersistenceError({
@@ -1115,9 +1115,9 @@ var PersistenceError, TaskProgressError, TaskInputError, TaskDeadlineError, Task
     const devices = new Map;
     let retainedTasks = 0;
     for (const row of rows) {
-      const status = Schema15.decodeUnknownSync(TaskStatus)(row.status);
-      const provider = Schema15.decodeUnknownSync(Provider)(row.provider);
-      const deviceId = Schema15.decodeUnknownSync(DeviceId)(row.device_id);
+      const status = Schema16.decodeUnknownSync(TaskStatus)(row.status);
+      const provider = Schema16.decodeUnknownSync(Provider)(row.provider);
+      const deviceId = Schema16.decodeUnknownSync(DeviceId)(row.device_id);
       retainedTasks += row.tasks;
       totalStatus[status] += row.tasks;
       totalProviders.set(provider, (totalProviders.get(provider) ?? 0) + row.tasks);
@@ -1909,7 +1909,7 @@ var PersistenceError, TaskProgressError, TaskInputError, TaskDeadlineError, Task
         if (pairing === null) {
           throw new Error("Pairing credential is invalid, expired, or already used");
         }
-        const roles = Schema15.decodeUnknownSync(Schema15.Array(ConnectionRole))(JSON.parse(pairing.roles_json));
+        const roles = Schema16.decodeUnknownSync(Schema16.Array(ConnectionRole))(JSON.parse(pairing.roles_json));
         const deviceId = roles.includes("device") ? makeDeviceId() : undefined;
         const consumed = db.query("UPDATE auth_pairings SET used_at = ? WHERE token_hash = ? AND used_at IS NULL").run(timestamp, pairing.token_hash);
         if (consumed.changes !== 1) {
@@ -2183,19 +2183,19 @@ var init_store = __esm(() => {
   init_src();
   init_database();
   init_store();
-  PersistenceError = class PersistenceError extends Schema15.TaggedErrorClass()("RelayStore.PersistenceError", {
-    operation: Schema15.String,
-    message: Schema15.String,
-    missingRecord: Schema15.optionalKey(Schema15.Literals(["task", "operation"]))
+  PersistenceError = class PersistenceError extends Schema16.TaggedErrorClass()("RelayStore.PersistenceError", {
+    operation: Schema16.String,
+    message: Schema16.String,
+    missingRecord: Schema16.optionalKey(Schema16.Literals(["task", "operation"]))
   }) {
   };
-  TaskProgressError = class TaskProgressError extends Schema15.TaggedErrorClass()("RelayStore.TaskProgressError", { status: Schema15.Literals([403, 409]), message: Schema15.String }) {
+  TaskProgressError = class TaskProgressError extends Schema16.TaggedErrorClass()("RelayStore.TaskProgressError", { status: Schema16.Literals([403, 409]), message: Schema16.String }) {
   };
-  TaskInputError = class TaskInputError extends Schema15.TaggedErrorClass()("RelayStore.TaskInputError", { status: Schema15.Literals([403, 409]), message: Schema15.String }) {
+  TaskInputError = class TaskInputError extends Schema16.TaggedErrorClass()("RelayStore.TaskInputError", { status: Schema16.Literals([403, 409]), message: Schema16.String }) {
   };
-  TaskDeadlineError = class TaskDeadlineError extends Schema15.TaggedErrorClass()("RelayStore.TaskDeadlineError", { status: Schema15.Literals([400, 409]), message: Schema15.String }) {
+  TaskDeadlineError = class TaskDeadlineError extends Schema16.TaggedErrorClass()("RelayStore.TaskDeadlineError", { status: Schema16.Literals([400, 409]), message: Schema16.String }) {
   };
-  TaskRequestError = class TaskRequestError extends Schema15.TaggedErrorClass()("RelayStore.TaskRequestError", { status: Schema15.Literals([409, 410]), message: Schema15.String }) {
+  TaskRequestError = class TaskRequestError extends Schema16.TaggedErrorClass()("RelayStore.TaskRequestError", { status: Schema16.Literals([409, 410]), message: Schema16.String }) {
   };
   Service2 = class Service2 extends Context2.Service()("@cohall/RelayStore") {
   };
@@ -2211,7 +2211,7 @@ __export(exports_main, {
   canReadTaskAttachments: () => canReadTaskAttachments,
   canDispatchTaskToDevice: () => canDispatchTaskToDevice
 });
-import { Effect as Effect15, ManagedRuntime, Schema as Schema16, Schedule as Schedule4 } from "effect";
+import { Effect as Effect15, ManagedRuntime, Schema as Schema17, Schedule as Schedule4 } from "effect";
 import { createHash as createHash3, timingSafeEqual } from "node:crypto";
 import { access as access6, chmod as chmod8 } from "node:fs/promises";
 import { createServer } from "node:http";
@@ -2314,7 +2314,7 @@ Content-Length: 0\r
 }, body = (request, decode3) => Effect15.tryPromise({
   try: () => request.json(),
   catch: () => new RequestError({ status: 400, message: "Expected a JSON request body" })
-}).pipe(Effect15.flatMap(decode3), Effect15.mapError((cause) => cause instanceof RequestError ? cause : new RequestError({ status: 400, message: String(cause).slice(0, 2048) }))), pathId = (schema, value) => Schema16.decodeUnknownEffect(schema)(value).pipe(Effect15.mapError(() => new RequestError({ status: 400, message: `Invalid identifier: ${value}` }))), scoreDevice = (device, input, sourceDeviceId) => {
+}).pipe(Effect15.flatMap(decode3), Effect15.mapError((cause) => cause instanceof RequestError ? cause : new RequestError({ status: 400, message: String(cause).slice(0, 2048) }))), pathId = (schema, value) => Schema17.decodeUnknownEffect(schema)(value).pipe(Effect15.mapError(() => new RequestError({ status: 400, message: `Invalid identifier: ${value}` }))), scoreDevice = (device, input, sourceDeviceId) => {
   const prompt = `${input.prompt} ${input.context ?? ""}`.toLowerCase();
   const needsXcode = /\b(xcode|ios|macos|swiftui|app store)\b/.test(prompt);
   const needsBrowser = /\b(browser|chrome|youtube|twitter|logged[- ]?in|signed[- ]?in|x\.com)\b/.test(prompt);
@@ -2713,6 +2713,14 @@ Content-Length: 0\r
         return yield* store.exchangePairing(input.token);
       })).then((value) => json(value, 201)).catch(() => json({ error: "Pairing credential is invalid, expired, or already used" }, 401));
     }
+    if (url.pathname === "/api/device/credential" && request.method === "GET") {
+      const authorization = request.headers.get("authorization");
+      const token = authorization?.startsWith("Bearer ") === true ? authorization.slice("Bearer ".length) : undefined;
+      if (token === undefined || await authenticate(token, "device") === undefined) {
+        return json({ error: "Unauthorized" }, 401);
+      }
+      return json({ ok: true });
+    }
     const attachmentRoute = request.method === "GET" && /^\/api\/tasks\/[^/]+\/attachments(?:\/[^/]+)?$/.test(url.pathname);
     const progressRoute = request.method === "POST" && /^\/api\/tasks\/[^/]+\/progress$/.test(url.pathname);
     const inputRoute = request.method === "POST" && /^\/api\/tasks\/[^/]+\/input$/.test(url.pathname);
@@ -3048,9 +3056,9 @@ var init_main = __esm(async () => {
   init_config();
   init_hub();
   init_store();
-  RequestError = class RequestError extends Schema16.TaggedErrorClass()("Relay.RequestError", {
-    status: Schema16.Int,
-    message: Schema16.String
+  RequestError = class RequestError extends Schema17.TaggedErrorClass()("Relay.RequestError", {
+    status: Schema17.Int,
+    message: Schema17.String
   }) {
   };
   maxTaskRequestBodyBytes = 3 * 1024 * 1024;
@@ -3174,6 +3182,7 @@ var make = (options) => {
   });
   const devicePage = (after) => request("RelayClient.devices", `/api/devices/page${after === undefined ? "" : `?after=${encodeURIComponent(after)}`}`, DevicePage, undefined, maxDevicePageResponseBytes);
   return Service.of({
+    verifyDeviceCredential: () => request("RelayClient.verifyDeviceCredential", "/api/device/credential", Schema2.Struct({ ok: Schema2.Literal(true) })).pipe(Effect2.asVoid),
     devices: () => Effect2.gen(function* () {
       const first = yield* devicePage().pipe(Effect2.catch((cause) => cause instanceof RelayRequestError && cause.status === 404 ? request("RelayClient.devices", "/api/devices", Schema2.Array(Device)) : Effect2.fail(cause)));
       if (!("devices" in first))
@@ -3317,29 +3326,30 @@ var make = (options) => {
 };
 var exchangePairing = (baseUrl, input) => Effect2.gen(function* () {
   const operation = "RelayClient.exchangePairing";
-  const response = yield* Effect2.tryPromise({
-    try: (signal) => fetch(`${normalizeBaseUrl(baseUrl)}/api/auth/pair`, {
-      method: "POST",
-      signal: AbortSignal.any([signal, AbortSignal.timeout(30000)]),
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    }),
-    catch: (cause) => new RelayRequestError({
+  const json = yield* Effect2.tryPromise({
+    try: async (signal) => {
+      const response = await fetch(`${normalizeBaseUrl(baseUrl)}/api/auth/pair`, {
+        method: "POST",
+        signal: AbortSignal.any([signal, AbortSignal.timeout(30000)]),
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input)
+      });
+      if (!response.ok) {
+        throw new RelayRequestError({
+          operation,
+          message: await responseMessage(response, operation),
+          status: response.status
+        });
+      }
+      return jsonBody(response, operation).catch((cause) => {
+        throw cause instanceof RelayDecodeError ? cause : new RelayDecodeError({ operation, message: String(cause) });
+      });
+    },
+    catch: (cause) => cause instanceof RelayRequestError || cause instanceof RelayDecodeError ? cause : new RelayRequestError({
       operation,
       message: cause instanceof Error ? cause.message : String(cause)
     })
   });
-  if (!response.ok) {
-    return yield* Effect2.fail(new RelayRequestError({
-      operation,
-      message: yield* Effect2.promise(() => responseMessage(response, operation)),
-      status: response.status
-    }));
-  }
-  const json = yield* Effect2.tryPromise({
-    try: () => jsonBody(response, operation),
-    catch: (cause) => cause instanceof RelayDecodeError ? cause : new RelayDecodeError({ operation, message: String(cause) })
-  });
   return yield* Schema2.decodeUnknownEffect(PairingResult)(json).pipe(Effect2.mapError((cause) => new RelayDecodeError({ operation, message: String(cause) })));
 });
 var layer = (options) => Layer.succeed(Service, make(options));
@@ -3893,10 +3903,10 @@ var run = (options) => Effect3.callback((resume, signal) => {
 });
 
 // apps/device/src/cli.ts
-import { Effect as Effect10, Schema as Schema11 } from "effect";
-import { access as access4, mkdir as mkdir7, open as open4, stat as stat4, writeFile as writeFile7 } from "node:fs/promises";
+import { Effect as Effect10, Schema as Schema12 } from "effect";
+import { access as access4, mkdir as mkdir8, open as open5, stat as stat4, writeFile as writeFile8 } from "node:fs/promises";
 import { homedir as homedir4 } from "node:os";
-import { dirname as dirname6, join as join8, resolve as resolve4 } from "node:path";
+import { dirname as dirname6, join as join9, resolve as resolve4 } from "node:path";
 
 // skills/cohall/SKILL.md
 var SKILL_default = `---
@@ -4162,6 +4172,125 @@ cohall devices
 Return the diagnostic failure to the user rather than claiming remote work ran.
 `;
 
+// docs/onboarding.md
+var onboarding_default = `# Set up Cohall with your agent
+
+These instructions are for the agent doing the setup. Read the path that matches
+the owner's request, complete the verification steps, and report what works.
+\`cohall onboard\` prints this same guide without changing the machine.
+
+## Choose the role
+
+- A relay address and pairing token mean **join an existing relay**.
+- A request to host a relay means **host a relay** on an always-on machine.
+- If neither is clear, ask whether this machine should host or join, and obtain
+  the relay address before pairing. A laptop that sleeps is a poor relay host.
+- For an existing installation, inspect \`cohall config\` and run \`cohall doctor\`
+  before repairing it. Reuse working credentials and workspace settings.
+
+Detect the OS, Node.js version, package manager, installed provider CLIs, and
+existing workspace roots. Cohall requires Node.js 24 or newer. Follow
+[installation](https://github.com/AksharP5/cohall/blob/main/docs/install.md) for package commands and
+[services](https://github.com/AksharP5/cohall/blob/main/docs/services.md) for the current OS. Use the owner's authorization for
+installation and autostart; obtain it when missing. Provider login requires the
+owner's account and should stay on the machine that runs that provider.
+
+Keep tokens out of command arguments, shell history, logs, and setup briefs.
+Read them through a hidden terminal prompt, stdin, or a private token file.
+
+## Host a relay
+
+1. Choose a machine that stays awake and a persistent relay data directory.
+   Install Cohall globally so its service has a stable executable path.
+2. Start \`cohall relay\` once in the foreground. The default listener is
+   \`127.0.0.1:8787\`; the relay creates a private owner token in its data directory
+   when none is supplied. Preserve that directory and include it in backups.
+3. Make the relay reachable through the owner's private Tailscale network or
+   HTTPS reverse proxy. Confirm the address from a joining machine with
+   \`GET /api/health\`. Plain HTTP is suitable only inside an independently
+   encrypted private network, never as a public listener.
+4. Configure relay autostart. The packaged relay service instructions cover
+   Linux; macOS and Windows relay hosts need an owner-approved supervisor.
+   \`cohall service install\` installs a **device worker**, not a relay.
+   Prepare the managed relay with the same data and owner configuration. Stop
+   the foreground relay to release its address, start the managed service, and
+   verify relay health before pairing devices.
+5. On the relay host, create a ten-minute, single-use pairing token for each
+   joining machine:
+
+   \`\`\`bash
+   cohall pair --label "Workstation"
+   \`\`\`
+
+   Set \`COHALL_RELAY_URL\` to the reachable address when creating the pairing so
+   its \`join_instructions\` use that address. The owner token is read from the
+   relay data directory on the host; a service using a different user or data
+   directory needs the matching owner configuration. Transfer the pairing token
+   privately and send the returned join instructions separately.
+
+6. If this host should also run agent work, pair it as another device and
+   complete the joining path below. Hosting a relay alone does not register a
+   worker or install its agent integration.
+
+## Join an existing relay
+
+1. Confirm the relay address and the role. A worker runs providers against its
+   own allowed workspaces; a client-only installation submits work elsewhere.
+   Request a fresh token if the supplied one has expired or was already used.
+2. Choose existing workspace roots and installed providers for a worker.
+   Confirm provider login on this machine. Use \`--providers codex\`,
+   \`--providers claude-code\`, or \`--providers opencode\` to limit selection;
+   \`auto\` enables every detected provider. Grok Bots have a separate
+   [gateway setup](https://github.com/AksharP5/cohall/blob/main/docs/grok-bot.md).
+3. Run guided setup with the confirmed address:
+
+   \`\`\`bash
+   cohall init --relay https://your-relay.example
+   \`\`\`
+
+   A terminal prompts for the pairing token without echoing it. Scripts and
+   agents without an interactive terminal supply it on stdin or with
+   \`--token-file\`; see the [pairing examples](https://github.com/AksharP5/cohall/blob/main/docs/install.md#pair-a-machine).
+   Client-only setup adds \`--client-only\` and uses a client-only pairing.
+   \`init\` writes configuration and installs the Cohall skill for Codex,
+   Claude Code, and OpenCode. It preserves existing settings during repair.
+
+4. For a worker, run \`cohall device\` in the foreground or install its service
+   after a global package installation. \`cohall init --service\` can install the
+   worker service during setup. A client-only installation needs no device
+   service. For Grok Bots, use the gateway instructions to verify availability.
+5. Use the CLI and installed skill in a harness that can run commands. If the
+   owner prefers MCP, run \`cohall integrations\` and follow the entry for the
+   actual harness in [agent integrations](https://github.com/AksharP5/cohall/blob/main/docs/integrations.md). Configure exactly
+   one Cohall server for that configuration, restart or reconnect the harness,
+   and ask it to call \`list_devices\`. Installing a skill does not configure MCP.
+
+## Verify before calling setup complete
+
+1. Run \`cohall doctor\`. Confirm relay access and client authentication. A worker
+   should be online or busy with the intended providers and workspaces.
+   \`doctor --all\` checks the other registered workers.
+2. If using MCP, check the real host connection in the doctor report after
+   asking the harness to call \`list_devices\`. A successful server self-test
+   alone does not establish that the harness loaded it.
+3. From the requesting client, run a harmless delegation to the intended
+   worker, using its target from \`cohall devices\` and an advertised provider:
+
+   \`\`\`bash
+   cohall delegate --target @workstation --provider codex --timeout 60 \\
+     "Reply with exactly cohall-ready. Do not inspect or change files."
+   \`\`\`
+
+   Require a completed result containing \`cohall-ready\`. Provider detection
+   alone does not prove authentication or execution works. For a Grok Bot,
+   use its target from \`cohall bots\` and \`--provider grok-bot\`.
+
+4. Report the relay host/address, this machine's role, selected providers and
+   workspaces, autostart state, integration used, and checks that passed.
+   Identify any remaining login, permission, or connectivity step. Include no
+   tokens or private task content.
+`;
+
 // apps/device/src/config.ts
 init_src();
 import { Effect as Effect4, Schema as Schema4 } from "effect";
@@ -5229,9 +5358,15 @@ var terminalPrompter = () => {
     close: () => terminal.close()
   };
 };
+var setupRelayUrl = (input) => {
+  if (input === undefined || input.trim().length === 0) {
+    throw new Error("Relay URL is required. Run `cohall onboard` to choose a relay host or join an existing relay.");
+  }
+  return normalizeRelayUrl(input);
+};
 var guidedSetupInput = async (options, prompter) => {
   const existing = await readStoredConfiguration();
-  const relayUrl = normalizeRelayUrl(options.relayUrl ?? await prompter.answer("Relay URL", existing?.relayUrl ?? "http://127.0.0.1:8787"));
+  const relayUrl = setupRelayUrl(options.relayUrl ?? await prompter.answer("Relay URL", existing?.relayUrl ?? ""));
   const credentials = credentialsForRelay(existing, relayUrl);
   const hasRequiredCredentials = credentials.clientToken !== undefined && (options.clientOnly || credentials.deviceToken !== undefined);
   let workspaces = options.clientOnly ? existing?.workspaces ?? [] : options.workspaces;
@@ -6489,7 +6624,7 @@ var isLoopback = (url) => url.hostname === "localhost" || url.hostname === "[::1
 var verifyClientCredential = async (relayUrl, token) => {
   await Effect8.runPromise(exports_src.make({ baseUrl: relayUrl, token }).devices());
 };
-var verifyDeviceCredential = (relayUrl, token) => new Promise((resolvePromise, reject) => {
+var verifyLegacyDeviceCredential = (relayUrl, token) => new Promise((resolvePromise, reject) => {
   const socket = new WebSocket(websocketUrl(relayUrl), {
     handshakeTimeout: 1e4,
     maxPayload: 1024 * 1024,
@@ -6528,6 +6663,12 @@ var verifyDeviceCredential = (relayUrl, token) => new Promise((resolvePromise, r
   socket.once("error", (cause) => finish(cause));
   socket.once("close", () => finish(new Error("New relay rejected the stored device credential")));
 });
+var verifyDeviceCredential = (relayUrl, token) => Effect8.runPromise(exports_src.make({ baseUrl: relayUrl, token }).verifyDeviceCredential()).catch((cause) => {
+  if (cause instanceof RelayRequestError && (cause.status === 401 || cause.status === 404)) {
+    return verifyLegacyDeviceCredential(relayUrl, token);
+  }
+  throw cause;
+});
 var switchRelay = async (options) => {
   if (process.env.COHALL_RELAY_URL !== undefined) {
     throw new Error("Unset COHALL_RELAY_URL before changing the stored relay URL");
@@ -6623,7 +6764,7 @@ var readInputAttachments = async (paths2) => {
     if (!source.isFile()) {
       throw new Error(`Attachment ${name} must be a regular file`);
     }
-    const handle = await open3(path, constants3.O_RDONLY | (process.platform === "win32" ? 0 : constants3.O_NOFOLLOW));
+    const handle = await open3(path, constants3.O_RDONLY | (process.platform === "win32" ? 0 : constants3.O_NOFOLLOW | constants3.O_NONBLOCK));
     try {
       const metadata = await handle.stat();
       if (!metadata.isFile() || metadata.dev !== source.dev || metadata.ino !== source.ino || metadata.size < 1 || metadata.size > maxAttachmentBytes) {
@@ -6680,7 +6821,7 @@ var collectOutputs = async (directory) => {
       throw new Error(`Output ${name} repeats another file name`);
     }
     names.add(key);
-    const handle = await open3(join7(directory, name), constants3.O_RDONLY | (process.platform === "win32" ? 0 : constants3.O_NOFOLLOW));
+    const handle = await open3(join7(directory, name), constants3.O_RDONLY | (process.platform === "win32" ? 0 : constants3.O_NOFOLLOW | constants3.O_NONBLOCK));
     try {
       const metadata = await handle.stat();
       const pathMetadata = await lstat2(join7(directory, name));
@@ -6706,6 +6847,248 @@ import {
   getDefaultEnvironment,
   StdioClientTransport
 } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+// apps/device/src/mcp-host-diagnostics.ts
+init_src();
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Schema as Schema11 } from "effect";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { constants as constants4 } from "node:fs";
+import { lstat as lstat3, mkdir as mkdir7, open as open4, opendir, rename as rename4, rm as rm5, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join8 } from "node:path";
+var maxRecords = 8;
+var maxRecordBytes = 4096;
+var retentionMs = 7 * 24 * 60 * 60 * 1000;
+var recordName = /^[\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}\.json$/;
+var text3 = Schema11.String.check(Schema11.isMaxLength(128));
+var count2 = Schema11.Int.check(Schema11.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }));
+var McpHostSession = Schema11.Struct({
+  schema_version: Schema11.Literal(1),
+  launch_id: Schema11.String.check(Schema11.isUUID(4)),
+  launched_at: Timestamp,
+  server_version: text3,
+  initialized_at: Schema11.optionalKey(Timestamp),
+  client: Schema11.optionalKey(Schema11.Struct({ name: text3, version: text3 })),
+  tools_list: Schema11.optionalKey(Schema11.Struct({ at: Timestamp, tool_count: count2 })),
+  tools_call_count: count2,
+  last_tool_call_at: Schema11.optionalKey(Timestamp),
+  closed_at: Schema11.optionalKey(Timestamp)
+});
+var storagePath = (configPath) => `${configPath}.mcp-hosts`;
+var recordsIn = async (directory) => {
+  const records = [];
+  let entries = 0;
+  for await (const entry of await opendir(directory)) {
+    if (++entries > 64)
+      throw new Error("MCP host diagnostics directory exceeded its entry limit");
+    if (!recordName.test(entry.name))
+      continue;
+    const path = join8(directory, entry.name);
+    const metadata = await lstat3(path).catch((cause) => {
+      if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+        return;
+      throw cause;
+    });
+    if (metadata !== undefined)
+      records.push({ path, modified: metadata.mtimeMs });
+  }
+  return records.sort((left, right) => right.modified - left.modified || left.path.localeCompare(right.path));
+};
+var readMcpHostDiagnostics = async (configPath = configurationPath()) => {
+  const path = storagePath(configPath);
+  const warnings = [];
+  let records;
+  try {
+    records = await recordsIn(path);
+  } catch (cause) {
+    if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {
+      return { status: "not_observed", path, sessions: [], warnings };
+    }
+    return {
+      status: "unavailable",
+      path,
+      sessions: [],
+      warnings,
+      error: `Cannot read MCP host diagnostics at ${path}. Restore access to this diagnostics directory, then restart the Cohall MCP connection in your host.`
+    };
+  }
+  const sessions = [];
+  let invalid = 0;
+  for (const record2 of records.filter((record3) => record3.modified >= Date.now() - retentionMs).slice(0, maxRecords)) {
+    try {
+      const handle = await open4(record2.path, constants4.O_RDONLY | (process.platform === "win32" ? 0 : constants4.O_NOFOLLOW | constants4.O_NONBLOCK));
+      try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.size > maxRecordBytes)
+          throw new Error("Invalid record");
+        const data = await readBoundedFile(handle, maxRecordBytes);
+        if (data.length > maxRecordBytes)
+          throw new Error("Invalid record");
+        sessions.push(Schema11.decodeUnknownSync(McpHostSession)(JSON.parse(data.toString("utf8"))));
+      } finally {
+        await handle.close();
+      }
+    } catch (cause) {
+      if (!(cause instanceof Error && ("code" in cause) && cause.code === "ENOENT"))
+        invalid += 1;
+    }
+  }
+  if (invalid > 0) {
+    warnings.push(`${invalid} MCP host diagnostics record(s) could not be read. Reset the diagnostics directory ${path}, then restart the Cohall MCP connection in your host.`);
+  }
+  if (sessions.length === 0 && invalid > 0) {
+    return {
+      status: "unavailable",
+      path,
+      sessions,
+      warnings,
+      error: "No valid MCP host diagnostics records could be read"
+    };
+  }
+  const latest = sessions[0];
+  if (latest !== undefined) {
+    if (latest.initialized_at === undefined) {
+      warnings.push(`${latest.closed_at === undefined ? "An MCP launch was recorded" : "A recorded MCP launch ended"} without client initialization. If your host still lacks Cohall tools, check its MCP command and selected config, then restart its Cohall connection.`);
+    } else if (latest.tools_list?.tool_count === 0) {
+      warnings.push("A recorded MCP launch returned an empty tools list. If Cohall tools are missing, check the host's Cohall MCP command and update or restart its connection.");
+    } else if (latest.tools_list === undefined && latest.tools_call_count === 0) {
+      warnings.push("An MCP host initialized Cohall but no tool discovery or calls were observed. If Cohall tools are missing, refresh or restart its MCP connection in that host.");
+    }
+  }
+  return {
+    status: sessions.some((session) => session.initialized_at !== undefined) ? "observed" : "not_observed",
+    path,
+    sessions,
+    warnings
+  };
+};
+var createMcpHostDiagnostics = (server) => {
+  const transport = new StdioServerTransport;
+  if (process.env.COHALL_MCP_SELF_TEST === "1")
+    return transport;
+  const directory = storagePath(configurationPath());
+  let session = McpHostSession.make({
+    schema_version: 1,
+    launch_id: randomUUID2(),
+    launched_at: now(),
+    server_version: version,
+    tools_call_count: 0
+  });
+  const path = join8(directory, `${session.launch_id}.json`);
+  let dirty = true;
+  let disabled = false;
+  let stopped = false;
+  let writing;
+  let timer;
+  const schedule = () => {
+    if (disabled || stopped || timer !== undefined)
+      return;
+    timer = setTimeout(() => {
+      timer = undefined;
+      flush();
+    }, 250);
+    timer.unref();
+  };
+  const flush = () => {
+    if (writing !== undefined)
+      return writing;
+    if (!dirty || disabled)
+      return Promise.resolve();
+    dirty = false;
+    const snapshot = session;
+    writing = (async () => {
+      await mkdir7(directory, { recursive: true, mode: 448 });
+      await recordsIn(directory);
+      const temporary = `${path}.tmp`;
+      try {
+        const json = `${JSON.stringify(snapshot)}
+`;
+        if (Buffer.byteLength(json) > maxRecordBytes)
+          throw new Error("Record exceeded its limit");
+        await writeFile7(temporary, json, { flag: "wx", mode: 384 });
+        await rename4(temporary, path);
+      } finally {
+        await rm5(temporary, { force: true });
+      }
+      const records = await recordsIn(directory);
+      const expired = records.filter((record2, index) => index >= maxRecords || record2.modified < Date.now() - retentionMs);
+      await Promise.all(expired.map((record2) => rm5(record2.path, { force: true })));
+    })().catch((cause) => {
+      disabled = true;
+      const reason = cause instanceof Error ? "code" in cause && typeof cause.code === "string" ? cause.code : cause.message : "Unknown filesystem error";
+      console.error(`Cohall MCP host diagnostics are unavailable (${reason.replace(/[\r\n]/g, " ").slice(0, 160)}). Check diagnostics storage access; MCP tools remain available.`);
+    }).finally(() => {
+      writing = undefined;
+      if (dirty)
+        schedule();
+    });
+    return writing;
+  };
+  const changed = () => {
+    dirty = true;
+    schedule();
+  };
+  const shutdown = async () => {
+    if (stopped)
+      return;
+    stopped = true;
+    clearTimeout(timer);
+    session = { ...session, closed_at: now() };
+    dirty = true;
+    await writing;
+    await flush();
+  };
+  flush();
+  process.once("beforeExit", () => void shutdown());
+  const initialized = server.oninitialized;
+  server.oninitialized = () => {
+    initialized?.();
+    const client = server.getClientVersion();
+    session = {
+      ...session,
+      initialized_at: now(),
+      ...client === undefined ? {} : { client: { name: client.name.slice(0, 128), version: client.version.slice(0, 128) } }
+    };
+    changed();
+  };
+  const closed = server.onclose;
+  server.onclose = () => {
+    closed?.();
+    shutdown();
+  };
+  const pendingLists = new Set;
+  const start = transport.start.bind(transport);
+  transport.start = async () => {
+    const receive = transport.onmessage;
+    transport.onmessage = (message) => {
+      if ("id" in message && message.id !== undefined && "method" in message) {
+        if (message.method === "tools/list" && pendingLists.size < 32)
+          pendingLists.add(message.id);
+        if (message.method === "tools/call") {
+          session = {
+            ...session,
+            tools_call_count: Math.min(session.tools_call_count + 1, Number.MAX_SAFE_INTEGER),
+            last_tool_call_at: now()
+          };
+          changed();
+        }
+      }
+      receive?.(message);
+    };
+    await start();
+  };
+  const send = transport.send.bind(transport);
+  transport.send = async (message) => {
+    await send(message);
+    if ("id" in message && message.id !== undefined && pendingLists.delete(message.id) && "result" in message && Array.isArray(message.result.tools)) {
+      session = { ...session, tools_list: { at: now(), tool_count: message.result.tools.length } };
+      changed();
+    }
+  };
+  return transport;
+};
+
+// apps/device/src/mcp-diagnostics.ts
 var checkMcp = async (entrypoint, relayUrl, token) => {
   const client = new Client({ name: "cohall-doctor", version });
   const transport = new StdioClientTransport({
@@ -6714,6 +7097,7 @@ var checkMcp = async (entrypoint, relayUrl, token) => {
     env: {
       ...getDefaultEnvironment(),
       COHALL_CONFIG: configurationPath(),
+      COHALL_MCP_SELF_TEST: "1",
       COHALL_RELAY_URL: relayUrl,
       COHALL_CLIENT_TOKEN: token
     },
@@ -6784,6 +7168,7 @@ var aliases = new Map([
 var help = `Cohall connects agents running on your own devices.
 
 Usage:
+  cohall onboard
   cohall init [--relay url] [--workspace path] [--providers list] [--service]
   cohall join --relay <url> --workspace <path> [--providers list] [--token-file <path>]
   cohall configure [--relay url] [--name name] [--workspace path]
@@ -6914,7 +7299,7 @@ var printLine = (value) => console.log(JSON.stringify(value));
 var readTextFile = async (path, limit, exceeded) => {
   if ((await stat4(path)).size > limit)
     throw new Error(exceeded);
-  const file = await open4(path, "r");
+  const file = await open5(path, "r");
   try {
     const data = await readBoundedFile(file, limit);
     if (data.length > limit)
@@ -6989,17 +7374,17 @@ var ownerClient = async () => {
 };
 var installSkill = async (target) => {
   const roots = {
-    agents: join8(homedir4(), ".agents", "skills", "cohall", "SKILL.md"),
-    claude: join8(homedir4(), ".claude", "skills", "cohall", "SKILL.md"),
-    opencode: join8(homedir4(), ".config", "opencode", "skills", "cohall", "SKILL.md")
+    agents: join9(homedir4(), ".agents", "skills", "cohall", "SKILL.md"),
+    claude: join9(homedir4(), ".claude", "skills", "cohall", "SKILL.md"),
+    opencode: join9(homedir4(), ".config", "opencode", "skills", "cohall", "SKILL.md")
   };
   const selected = target === "all" ? Object.values(roots) : (target in roots) ? [roots[target]] : undefined;
   if (selected === undefined) {
     throw new Error("Skill target must be agents, claude, opencode, or all");
   }
   for (const path of selected) {
-    await mkdir7(dirname6(path), { recursive: true });
-    await writeFile7(path, SKILL_default);
+    await mkdir8(dirname6(path), { recursive: true });
+    await writeFile8(path, SKILL_default);
   }
   return selected;
 };
@@ -7007,13 +7392,19 @@ var printHelp = () => console.log(help);
 var printSkill = () => console.log(SKILL_default.trimEnd());
 var runCli = async (command, raw) => {
   const arguments_ = parseArguments(raw);
+  if (command === "onboard") {
+    allowOptions(arguments_, []);
+    noPositionals(arguments_, command);
+    console.log(onboarding_default.trimEnd());
+    return;
+  }
   if (command === "reply") {
     allowOptions(arguments_, ["message", "message-file", "error", "question", "run-id"]);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     const error = option(arguments_, "error");
     const question = option(arguments_, "question");
     const rawRunId = option(arguments_, "run-id");
-    const runId = rawRunId === undefined ? undefined : Schema11.decodeUnknownSync(TaskRunId)(rawRunId);
+    const runId = rawRunId === undefined ? undefined : Schema12.decodeUnknownSync(TaskRunId)(rawRunId);
     if ((error !== undefined || question !== undefined) && (option(arguments_, "message") !== undefined || option(arguments_, "message-file") !== undefined || error !== undefined && question !== undefined)) {
       throw new Error("Use one of --question, --error, or --message/--message-file");
     }
@@ -7021,7 +7412,7 @@ var runCli = async (command, raw) => {
     if (error === undefined && question === undefined && message === undefined) {
       throw new Error("A bot reply requires --message, --message-file, --error, or --question");
     }
-    const reply = question !== undefined ? { question: Schema11.decodeUnknownSync(RequestTaskInput.fields.question)(question) } : error === undefined ? { result: message ?? "" } : { error };
+    const reply = question !== undefined ? { question: Schema12.decodeUnknownSync(RequestTaskInput.fields.question)(question) } : error === undefined ? { result: message ?? "" } : { error };
     await writeBotReply(id, reply, runId);
     print({ submitted: true, task_id: id });
     return;
@@ -7037,6 +7428,9 @@ var runCli = async (command, raw) => {
       "workspace"
     ]);
     noPositionals(arguments_, command);
+    if (arguments_.options.has("client-only") && arguments_.options.has("service")) {
+      throw new Error("A client-only setup cannot install a device service");
+    }
     const token = option(arguments_, "token-file") === undefined ? undefined : await pairingToken(arguments_);
     const interactive = process.stdin.isTTY === true && process.stderr.isTTY === true;
     const relayUrl = option(arguments_, "relay");
@@ -7095,7 +7489,7 @@ var runCli = async (command, raw) => {
         workspaces: result.configuration.workspaces,
         skills: installedSkills,
         ...service === undefined ? {} : { service },
-        next: service === undefined && !arguments_.options.has("client-only") ? "Run `cohall service install` for background availability, or `cohall device` now." : "Run `cohall doctor` to verify this device."
+        next: service === undefined && !arguments_.options.has("client-only") ? "Run `cohall service install` for background availability, or `cohall device` now. Then run `cohall doctor` and the delegation check in `cohall onboard`." : "Run `cohall doctor`, then the delegation check in `cohall onboard`."
       });
     } finally {
       prompter.close();
@@ -7187,7 +7581,7 @@ var runCli = async (command, raw) => {
       if (arguments_.positionals.length !== 2 || arguments_.positionals[0] !== "abandon") {
         throw new Error("Usage: cohall upgrades [abandon <operation-id>]");
       }
-      print(await Effect10.runPromise(relay2.abandonOperation(Schema11.decodeUnknownSync(OperationId)(arguments_.positionals[1]))));
+      print(await Effect10.runPromise(relay2.abandonOperation(Schema12.decodeUnknownSync(OperationId)(arguments_.positionals[1]))));
       return;
     }
     print(await Effect10.runPromise(relay2.operations()));
@@ -7203,9 +7597,9 @@ var runCli = async (command, raw) => {
       "workspace"
     ]);
     noPositionals(arguments_, command);
-    const token = await pairingToken(arguments_);
-    const relayUrl = normalizeRelayUrl(option(arguments_, "relay") ?? "http://127.0.0.1:8787");
     const existing = await readStoredConfiguration();
+    const relayUrl = setupRelayUrl(option(arguments_, "relay") ?? existing?.relayUrl);
+    const token = await pairingToken(arguments_);
     const suppliedWorkspaces = values(arguments_, "workspace");
     const workspaces = suppliedWorkspaces.length === 0 ? existing?.workspaces : suppliedWorkspaces;
     const deviceName = option(arguments_, "name");
@@ -7287,7 +7681,7 @@ var runCli = async (command, raw) => {
       ...model === undefined ? {} : { model },
       ...grokGateway === undefined ? {} : { grokGateway },
       ...(sandbox ?? existing?.sandbox) === undefined ? {} : {
-        sandbox: Schema11.decodeUnknownSync(Schema11.Literals(["read-only", "workspace-write", "danger-full-access"]))(sandbox ?? existing?.sandbox)
+        sandbox: Schema12.decodeUnknownSync(Schema12.Literals(["read-only", "workspace-write", "danger-full-access"]))(sandbox ?? existing?.sandbox)
       }
     });
     await writeStoredConfiguration(configuration2);
@@ -7352,6 +7746,7 @@ var runCli = async (command, raw) => {
       return;
     });
     const clientToken = process.env.COHALL_CLIENT_TOKEN ?? storedCredentials.clientToken;
+    const mcpHost = await readMcpHostDiagnostics();
     const mcp = clientToken === undefined ? { status: "not configured" } : await checkMcp(process.argv[1] ?? "", relayUrl, clientToken);
     const hasDeviceCredential = process.env.COHALL_DEVICE_TOKEN !== undefined || storedCredentials.deviceToken !== undefined;
     const deviceId = process.env.COHALL_DEVICE_ID ?? configuration2?.deviceId;
@@ -7373,6 +7768,8 @@ var runCli = async (command, raw) => {
       ...response?.ok === true ? [] : ["Relay is unreachable"],
       ...versionWarning === undefined ? [] : [versionWarning],
       ...mcp.status === "error" ? [`MCP check failed: ${mcp.error}`] : [],
+      ...mcpHost.warnings,
+      ...mcpHost.status === "unavailable" ? [`MCP host diagnostics unavailable: ${mcpHost.error}`] : [],
       ...clientAuthentication.status === "error" ? [clientAuthentication.error] : [],
       ...hasDeviceCredential && response?.ok === true && clientAuthentication.status !== "error" && currentDevice?.status !== "online" && currentDevice?.status !== "busy" ? [
         clientToken === undefined ? "Device status cannot be checked without a client credential" : "Device daemon is not connected or is not registered with the relay"
@@ -7388,7 +7785,8 @@ var runCli = async (command, raw) => {
       config_path: configurationPath(),
       client_credential: process.env.COHALL_CLIENT_TOKEN !== undefined || storedCredentials.clientToken !== undefined,
       client_authentication: clientAuthentication.status === "ok" ? { status: "ok" } : clientAuthentication,
-      mcp,
+      mcp: { ...mcp, scope: "server self-test" },
+      mcp_host: mcpHost,
       device_credential: hasDeviceCredential,
       workspaces: configuration2?.workspaces ?? [],
       providers: providerExecutables,
@@ -7435,7 +7833,8 @@ var runCli = async (command, raw) => {
         relay_url: configuration2.relayUrl,
         pairing_token: credential.token,
         expires_at: credential.expiresAt,
-        roles
+        roles,
+        join_instructions: `Join my existing Cohall relay at ${configuration2.relayUrl} as ${arguments_.options.has("client-only") ? "a client that submits work only" : "a worker and client"}. Follow https://github.com/AksharP5/cohall/blob/main/docs/onboarding.md, "Join an existing relay". I will provide the one-time pairing token separately; read it through a hidden terminal prompt, stdin, or a token file. ${arguments_.options.has("client-only") ? "Use cohall init --client-only; no device service is needed." : "Choose existing workspace roots and installed providers before running cohall init."} Finish the verification steps and report what passed.`
       });
       return;
     }
@@ -7447,11 +7846,11 @@ var runCli = async (command, raw) => {
     }
     if (command === "forget") {
       allowOptions(arguments_, []);
-      print(await Effect10.runPromise(relay2.forgetDevice(Schema11.decodeUnknownSync(DeviceId)(identifier(arguments_, "device id")))));
+      print(await Effect10.runPromise(relay2.forgetDevice(Schema12.decodeUnknownSync(DeviceId)(identifier(arguments_, "device id")))));
       return;
     }
     allowOptions(arguments_, []);
-    print(await Effect10.runPromise(relay2.revokeAuthSession(Schema11.decodeUnknownSync(AuthSessionId)(identifier(arguments_, "session id")))));
+    print(await Effect10.runPromise(relay2.revokeAuthSession(Schema12.decodeUnknownSync(AuthSessionId)(identifier(arguments_, "session id")))));
     return;
   }
   const { configuration, relay } = await client();
@@ -7460,20 +7859,20 @@ var runCli = async (command, raw) => {
     const rawQuestion = option(arguments_, "question");
     if (rawQuestion === undefined)
       throw new Error("--question is required");
-    const question = Schema11.decodeUnknownSync(RequestTaskInput.fields.question)(rawQuestion);
-    const id = arguments_.positionals.length === 0 ? undefined : Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const question = Schema12.decodeUnknownSync(RequestTaskInput.fields.question)(rawQuestion);
+    const id = arguments_.positionals.length === 0 ? undefined : Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     const rawRunId = option(arguments_, "run-id");
-    const runId = rawRunId === undefined ? undefined : Schema11.decodeUnknownSync(TaskRunId)(rawRunId);
+    const runId = rawRunId === undefined ? undefined : Schema12.decodeUnknownSync(TaskRunId)(rawRunId);
     print(await Effect10.runPromise(requestInput(relay, configuration, question, id, runId)));
     return;
   }
   if (command === "answer") {
     allowOptions(arguments_, ["request-id", "message", "message-file"]);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     const requestId = option(arguments_, "request-id");
     if (requestId === undefined)
       throw new Error("--request-id is required; use the input request id from status or inbox");
-    const input = Schema11.decodeUnknownSync(AnswerTaskInput)({
+    const input = Schema12.decodeUnknownSync(AnswerTaskInput)({
       requestId,
       answer: await readInput(arguments_, "message")
     });
@@ -7488,8 +7887,8 @@ var runCli = async (command, raw) => {
     const note = option(arguments_, "message");
     if (note === undefined)
       throw new Error("--message is required");
-    const input = Schema11.decodeUnknownSync(TaskProgressInput)({ note });
-    print(await Effect10.runPromise(relay.reportTaskProgress(Schema11.decodeUnknownSync(TaskId)(rawId), input)));
+    const input = Schema12.decodeUnknownSync(TaskProgressInput)({ note });
+    print(await Effect10.runPromise(relay.reportTaskProgress(Schema12.decodeUnknownSync(TaskId)(rawId), input)));
     return;
   }
   if (command === "devices") {
@@ -7549,15 +7948,15 @@ var runCli = async (command, raw) => {
     const requestId = option(arguments_, "request-id");
     const task = await Effect10.runPromise(createDelegation(relay, configuration, {
       prompt,
-      ...requestId === undefined ? {} : { requestId: Schema11.decodeUnknownSync(TaskRequestId)(requestId) },
+      ...requestId === undefined ? {} : { requestId: Schema12.decodeUnknownSync(TaskRequestId)(requestId) },
       ...target === undefined ? {} : { target },
       ...context === undefined ? {} : { context },
-      ...thread === undefined ? {} : { threadId: Schema11.decodeUnknownSync(ThreadId)(thread) },
-      ...parent === undefined ? {} : { parentTaskId: Schema11.decodeUnknownSync(TaskId)(parent) },
+      ...thread === undefined ? {} : { threadId: Schema12.decodeUnknownSync(ThreadId)(thread) },
+      ...parent === undefined ? {} : { parentTaskId: Schema12.decodeUnknownSync(TaskId)(parent) },
       ...workspace === undefined ? {} : { workspace },
-      ...provider === undefined ? {} : { provider: Schema11.decodeUnknownSync(Provider)(provider) },
+      ...provider === undefined ? {} : { provider: Schema12.decodeUnknownSync(Provider)(provider) },
       ...attachments2.length === 0 ? {} : { attachments: attachments2 },
-      ...deadline === undefined ? {} : { expiresAt: Schema11.decodeUnknownSync(TaskDeadline)(deadline) }
+      ...deadline === undefined ? {} : { expiresAt: Schema12.decodeUnknownSync(TaskDeadline)(deadline) }
     }));
     const completed = arguments_.options.has("no-wait") ? task : await Effect10.runPromise(waitForTask(relay, task, waitSeconds));
     print(arguments_.options.has("no-wait") ? taskResult(completed) : await acknowledgedTaskResult(relay, completed));
@@ -7568,7 +7967,7 @@ var runCli = async (command, raw) => {
     if (arguments_.positionals[0] === "ack") {
       if (arguments_.positionals.length !== 2)
         throw new Error("Usage: cohall inbox ack <task-id>");
-      const id = Schema11.decodeUnknownSync(TaskId)(arguments_.positionals[1]);
+      const id = Schema12.decodeUnknownSync(TaskId)(arguments_.positionals[1]);
       print(await Effect10.runPromise(relay.acknowledgeCompletion(id)));
       return;
     }
@@ -7578,13 +7977,13 @@ var runCli = async (command, raw) => {
   }
   if (command === "status") {
     allowOptions(arguments_, []);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     print(taskResult(await Effect10.runPromise(relay.getTask(id))));
     return;
   }
   if (command === "attachments") {
     allowOptions(arguments_, []);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     print(await Effect10.runPromise(relay.listAttachments(id)));
     return;
   }
@@ -7597,18 +7996,18 @@ var runCli = async (command, raw) => {
     if (destination === undefined) {
       throw new Error("--output is required");
     }
-    const id = Schema11.decodeUnknownSync(TaskId)(arguments_.positionals[0]);
-    const name = Schema11.decodeUnknownSync(AttachmentName)(arguments_.positionals[1]);
+    const id = Schema12.decodeUnknownSync(TaskId)(arguments_.positionals[0]);
+    const name = Schema12.decodeUnknownSync(AttachmentName)(arguments_.positionals[1]);
     const directionInput = option(arguments_, "direction");
-    const direction = directionInput === undefined ? undefined : Schema11.decodeUnknownSync(AttachmentDirection)(directionInput);
+    const direction = directionInput === undefined ? undefined : Schema12.decodeUnknownSync(AttachmentDirection)(directionInput);
     const data = await Effect10.runPromise(relay.readAttachment(id, name, direction));
-    await writeFile7(destination, data, { flag: "wx", mode: 384 });
+    await writeFile8(destination, data, { flag: "wx", mode: 384 });
     print({ task_id: id, name, path: resolve4(destination), bytes: data.length });
     return;
   }
   if (command === "trace") {
     allowOptions(arguments_, ["follow"]);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     if (arguments_.options.has("follow")) {
       await Effect10.runPromise(followTaskTrace(relay, id, printLine));
       return;
@@ -7618,19 +8017,19 @@ var runCli = async (command, raw) => {
   }
   if (command === "wait") {
     allowOptions(arguments_, ["timeout"]);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     print(taskResult(await Effect10.runPromise(waitForTask(relay, id, timeout(arguments_)))));
     return;
   }
   if (command === "cancel") {
     allowOptions(arguments_, []);
-    const id = Schema11.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    const id = Schema12.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
     print(taskResult(await Effect10.runPromise(relay.cancelTask(id))));
     return;
   }
   if (command === "thread") {
     allowOptions(arguments_, []);
-    const id = Schema11.decodeUnknownSync(ThreadId)(identifier(arguments_, "thread id"));
+    const id = Schema12.decodeUnknownSync(ThreadId)(identifier(arguments_, "thread id"));
     print(await Effect10.runPromise(threadContext(relay, id)));
     return;
   }
@@ -7639,15 +8038,15 @@ var runCli = async (command, raw) => {
 
 // apps/device/src/daemon.ts
 init_src();
-import { Effect as Effect11, Schedule as Schedule3, Schema as Schema12 } from "effect";
-import { constants as constants4 } from "node:fs";
-import { open as open5, realpath as realpath4, stat as stat5 } from "node:fs/promises";
+import { Effect as Effect11, Schedule as Schedule3, Schema as Schema13 } from "effect";
+import { constants as constants5 } from "node:fs";
+import { open as open6, realpath as realpath4, stat as stat5 } from "node:fs/promises";
 import { arch, hostname as hostname3, platform as platform4 } from "node:os";
-import { basename as basename3, isAbsolute as isAbsolute5, relative as relative2 } from "node:path";
+import { basename as basename3, isAbsolute as isAbsolute5, relative as relative2, sep } from "node:path";
 import { WebSocket as WebSocket2 } from "ws";
 var maxQueuedRelayMessages = 8;
 
-class DeviceConnectionError extends Schema12.TaggedErrorClass()("Device.ConnectionError", { message: Schema12.String }) {
+class DeviceConnectionError extends Schema13.TaggedErrorClass()("Device.ConnectionError", { message: Schema13.String }) {
 }
 var socketUrl = (configuration) => {
   const url = new URL(configuration.relayUrl);
@@ -7724,7 +8123,7 @@ var allowedWorkspace = async (configuration, requested) => {
   const candidate = await realpath4(selected);
   const allowed = configuration.workspaces.some((root) => {
     const child = relative2(root, candidate);
-    return child === "" || !child.startsWith("..") && !isAbsolute5(child);
+    return child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute5(child);
   });
   if (!allowed) {
     throw new Error(`Workspace ${candidate} is outside this device's configured workspace roots`);
@@ -7734,8 +8133,8 @@ var allowedWorkspace = async (configuration, requested) => {
 var openAllowedWorkspace = async (configuration, requested) => {
   const path = await allowedWorkspace(configuration, requested);
   const operatingSystem2 = platform4();
-  const flags = constants4.O_RDONLY | (operatingSystem2 === "win32" ? 0 : constants4.O_DIRECTORY | constants4.O_NOFOLLOW);
-  const handle = await open5(path, flags);
+  const flags = constants5.O_RDONLY | (operatingSystem2 === "win32" ? 0 : constants5.O_DIRECTORY | constants5.O_NOFOLLOW);
+  const handle = await open6(path, flags);
   const identity = await handle.stat();
   if (!identity.isDirectory()) {
     await handle.close();
@@ -8168,9 +8567,9 @@ var connect = (configuration, state) => Effect11.tryPromise({
         if (closed) {
           return;
         }
-        const text3 = Buffer.isBuffer(message) ? message.toString("utf8") : message instanceof ArrayBuffer ? Buffer.from(message).toString("utf8") : Array.isArray(message) ? Buffer.concat(message).toString("utf8") : Buffer.from(message).toString("utf8");
+        const text4 = Buffer.isBuffer(message) ? message.toString("utf8") : message instanceof ArrayBuffer ? Buffer.from(message).toString("utf8") : Array.isArray(message) ? Buffer.concat(message).toString("utf8") : Buffer.from(message).toString("utf8");
         const event = await Effect11.runPromise(Effect11.try({
-          try: () => JSON.parse(text3),
+          try: () => JSON.parse(text4),
           catch: () => new DeviceConnectionError({ message: "Relay sent invalid JSON" })
         }).pipe(Effect11.flatMap(decodeSocketEvent)));
         if (event._tag === "Connected") {
@@ -8263,10 +8662,9 @@ var runDaemon = (configuration) => {
 // apps/device/src/mcp.ts
 init_src();
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { Effect as Effect12, Schema as Schema13 } from "effect";
+import { Effect as Effect12, Schema as Schema14 } from "effect";
 import * as z from "zod/v4";
-import { writeFile as writeFile8 } from "node:fs/promises";
+import { writeFile as writeFile9 } from "node:fs/promises";
 
 // apps/device/src/mcp-build-notice.ts
 import { execFile as execFile3 } from "node:child_process";
@@ -8336,7 +8734,7 @@ var runMcp = async (configuration) => {
       run_id: z.string().uuid().optional(),
       question: z.string().min(1).max(maxClarificationBytes)
     }
-  }, async ({ task_id, run_id, question }) => output(await Effect12.runPromise(requestInput(client2, configuration, Schema13.decodeUnknownSync(RequestTaskInput.fields.question)(question), task_id === undefined ? undefined : Schema13.decodeUnknownSync(TaskId)(task_id), run_id === undefined ? undefined : Schema13.decodeUnknownSync(TaskRunId)(run_id)))));
+  }, async ({ task_id, run_id, question }) => output(await Effect12.runPromise(requestInput(client2, configuration, Schema14.decodeUnknownSync(RequestTaskInput.fields.question)(question), task_id === undefined ? undefined : Schema14.decodeUnknownSync(TaskId)(task_id), run_id === undefined ? undefined : Schema14.decodeUnknownSync(TaskRunId)(run_id)))));
   server.registerTool("task_answer", {
     title: "Answer a worker's question",
     description: "Answer the current clarification and resume the same task. Use input_request.id from task_status or delegate as request_id, or inputRequest.id from completion_inbox. Only the original requester or relay owner can answer. Use wait_task to collect the resumed result.",
@@ -8345,7 +8743,7 @@ var runMcp = async (configuration) => {
       request_id: z.string().uuid(),
       answer: z.string().min(1).max(maxClarificationBytes)
     }
-  }, async ({ task_id, request_id, answer }) => output(taskResult(await Effect12.runPromise(client2.answerTaskInput(Schema13.decodeUnknownSync(TaskId)(task_id), Schema13.decodeUnknownSync(AnswerTaskInput)({ requestId: request_id, answer }))))));
+  }, async ({ task_id, request_id, answer }) => output(taskResult(await Effect12.runPromise(client2.answerTaskInput(Schema14.decodeUnknownSync(TaskId)(task_id), Schema14.decodeUnknownSync(AnswerTaskInput)({ requestId: request_id, answer }))))));
   server.registerTool("task_progress", {
     title: "Report task progress",
     description: `Replace the latest progress note for a running task on this device. Use brief milestones, up to ${maxProgressNoteBytes} UTF-8 bytes. Inherits the delegated task ID when omitted.`,
@@ -8357,8 +8755,8 @@ var runMcp = async (configuration) => {
     const id = task_id ?? configuration.mcpTaskId;
     if (id === undefined)
       throw new Error("Task id is required outside delegated work");
-    const input = Schema13.decodeUnknownSync(TaskProgressInput)({ note });
-    return output(await Effect12.runPromise(client2.reportTaskProgress(Schema13.decodeUnknownSync(TaskId)(id), input)));
+    const input = Schema14.decodeUnknownSync(TaskProgressInput)({ note });
+    return output(await Effect12.runPromise(client2.reportTaskProgress(Schema14.decodeUnknownSync(TaskId)(id), input)));
   });
   server.registerTool("list_devices", {
     title: "List Cohall devices",
@@ -8404,7 +8802,7 @@ var runMcp = async (configuration) => {
     const attachments2 = await readInputAttachments(attachment_paths ?? []);
     const task = await Effect12.runPromise(createDelegation(client2, configuration, {
       prompt,
-      ...request_id === undefined ? {} : { requestId: Schema13.decodeUnknownSync(TaskRequestId)(request_id) },
+      ...request_id === undefined ? {} : { requestId: Schema14.decodeUnknownSync(TaskRequestId)(request_id) },
       ...provider === undefined ? {} : { provider },
       ...target === undefined ? {} : { target },
       ...context === undefined ? {} : { context },
@@ -8412,7 +8810,7 @@ var runMcp = async (configuration) => {
       ...parent_task_id === undefined ? {} : { parentTaskId: TaskId.make(parent_task_id) },
       ...workspace === undefined ? {} : { workspace },
       ...attachments2.length === 0 ? {} : { attachments: attachments2 },
-      ...deadline === undefined ? {} : { expiresAt: Schema13.decodeUnknownSync(TaskDeadline)(deadline) }
+      ...deadline === undefined ? {} : { expiresAt: Schema14.decodeUnknownSync(TaskDeadline)(deadline) }
     }), { signal });
     const completed = wait ? await Effect12.runPromise(waitForTask(client2, task, timeout_seconds), { signal }) : task;
     return output(wait ? await acknowledgedTaskResult(client2, completed, signal) : taskResult(completed));
@@ -8446,11 +8844,12 @@ var runMcp = async (configuration) => {
       output_path: z.string(),
       direction: z.enum(["input", "output"]).optional()
     }
-  }, async ({ task_id, name, output_path, direction }) => {
-    const safeName = Schema13.decodeUnknownSync(AttachmentName)(name);
-    const safeDirection = direction === undefined ? undefined : Schema13.decodeUnknownSync(AttachmentDirection)(direction);
-    const data = await Effect12.runPromise(client2.readAttachment(TaskId.make(task_id), safeName, safeDirection));
-    await writeFile8(output_path, data, { flag: "wx", mode: 384 });
+  }, async ({ task_id, name, output_path, direction }, { signal }) => {
+    const safeName = Schema14.decodeUnknownSync(AttachmentName)(name);
+    const safeDirection = direction === undefined ? undefined : Schema14.decodeUnknownSync(AttachmentDirection)(direction);
+    const data = await Effect12.runPromise(client2.readAttachment(TaskId.make(task_id), safeName, safeDirection), { signal });
+    signal.throwIfAborted();
+    await writeFile9(output_path, data, { flag: "wx", mode: 384, signal });
     return output({ task_id, name: safeName, output_path, bytes: data.length });
   });
   server.registerTool("task_trace", {
@@ -8480,7 +8879,7 @@ var runMcp = async (configuration) => {
     description: "Read shared task prompts and final results for a cross-device thread.",
     inputSchema: { thread_id: z.string().uuid() }
   }, async ({ thread_id }) => output(await Effect12.runPromise(threadContext(client2, ThreadId.make(thread_id)))));
-  await server.connect(new StdioServerTransport);
+  await server.connect(createMcpHostDiagnostics(server.server));
 };
 
 // apps/device/src/main.ts
@@ -8536,4 +8935,4 @@ await main().catch((cause) => {
   process.exitCode = 1;
 });
 
-//# debugId=10C40468ADA26DC864756E2164756E21
+//# debugId=6DD87AF6E4752A1764756E2164756E21