@akshar5/cohall 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.6](https://github.com/AksharP5/cohall/compare/v0.4.5...v0.4.6) (2026-08-08)
+
+
+### Bug Fixes
+
+* **skill:** explain cross-device workflows and recovery ([#34](https://github.com/AksharP5/cohall/issues/34)) ([0bba7b9](https://github.com/AksharP5/cohall/commit/0bba7b9645d2c1f577332ebb21a885b973fc6e80))
+
+## [0.4.5](https://github.com/AksharP5/cohall/compare/v0.4.4...v0.4.5) (2026-08-07)
+
+
+### Bug Fixes
+
+* **relay:** keep upgrades available and forget stale devices ([#32](https://github.com/AksharP5/cohall/issues/32)) ([d5b054d](https://github.com/AksharP5/cohall/commit/d5b054db37b8e2737af7540cac4f74f64e457a7f))
+
 ## [0.4.4](https://github.com/AksharP5/cohall/compare/v0.4.3...v0.4.4) (2026-08-07)
 
 

package/README.md

@@ -36,6 +36,27 @@ session IDs. It does not plan work, copy device credentials, or SSH into a
 machine. Each device runs its own provider CLI with its existing local login,
 configuration, skills, MCP servers, permissions, and workspace access.
 
+## What to use it for
+
+Once the skill is installed, requests in an ordinary agent thread can be as
+direct as:
+
+- “Ask `@macbook` to build the iOS app in Xcode and diagnose the signing error.”
+- “Have `@devbox` reproduce this failure against its Docker services.”
+- “Use `@archlinux`'s signed-in browser to inspect the failed deployment.”
+- “Queue the full test suite on `@devbox`; keep working here and report back.”
+
+The current agent turns that request into a focused Cohall task and incorporates
+the result when it returns. `@macbook` is a device selector understood through
+the installed skill, not special chat syntax built into your harness.
+
+T3 Connect is a remote interface to a T3 Code environment: use it when you want
+to browse that machine's projects, terminal, files, and diffs yourself. Cohall
+instead lets the agent in your current Codex, Claude Code, OpenCode, T3Code, or
+other harness delegate an outcome to an agent on another machine. It provides
+cross-harness CLI/MCP access, durable offline queues, resumable agent threads,
+and redacted task traces. The two tools can be used together.
+
 ## Quick start
 
 Run Cohall anywhere Node.js 24 or newer is installed. Use whichever JavaScript
@@ -91,6 +112,26 @@ npx -y @akshar5/cohall device
 then writes a per-user configuration file with Unix mode `0600`. Workspace roots
 must already exist and are resolved to canonical paths.
 
+## Availability and restarts
+
+The relay must be reachable to accept new tasks or return status. Once accepted,
+a task is stored in SQLite and survives relay or target-device restarts. Work for
+an offline target waits on the relay and starts when that device reconnects.
+Interrupted running work is re-queued with at-least-once delivery, so prompts
+that cause external changes should be safe to retry.
+
+The packaged service definitions reconnect automatically:
+
+- the Linux relay starts at boot through systemd socket and service units;
+- a Linux device starts with its user service, or at boot when user lingering is
+  enabled;
+- a macOS device starts when that user logs in through its LaunchAgent;
+- a Windows device starts at user logon through Task Scheduler.
+
+Powered-off devices do not run work. A powered-off relay cannot accept new work,
+but tasks already written to its persistent data directory remain there for its
+next start. See [service setup](docs/services.md) for installation and checks.
+
 ## Use from an agent
 
 Install the same embedded skill for Codex, Claude Code, and OpenCode:
@@ -226,8 +267,13 @@ the same npm, Bun, or pnpm installation and restarts only active Cohall relay
 and device jobs. Active jobs restart even when the installed files are already
 current, ensuring an older loaded process is replaced. Cohall refuses to restart
 a service configured to use a different global installation; run that service's
-executable directly or update its service definition first. Use `cohall upgrade --dry-run` to inspect the plan or
-`cohall upgrade --no-restart` to update files without restarting services.
+executable directly or update its service definition first.
+
+- `cohall upgrade --dry-run` previews the plan.
+- `cohall upgrade --no-restart` updates files without restarting services.
+
+Linux relays can use the packaged systemd socket unit so new connections remain
+available while the relay process is replaced; see [service setup](docs/services.md).
 Environment variables override stored values:
 
 | Variable                                  | Purpose                                        |
@@ -250,6 +296,11 @@ Environment variables override stored values:
 | `COHALL_RELAY_ALLOW_REMOTE`               | Explicit non-loopback binding opt-in           |
 
 The owner token can create pairing credentials, list sessions, and revoke them.
+`cohall forget <device-id>` removes an offline device from discovery after
+confirming it has no outstanding tasks, revokes its device credential, and
+preserves its completed task history. On the relay host, owner commands read the
+protected local owner-token file automatically; remote owner commands require
+`COHALL_TOKEN`.
 Ordinary client and device credentials are role-separated, device-bound where
 applicable, expiring, and stored only as SHA-256 hashes by the relay.
 

package/bin/cohall.js

@@ -17,7 +17,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // packages/protocol/src/index.ts
 import { Schema } from "effect";
-var version = "0.4.4", 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)), 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.4.6", 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)), 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)), DeviceId, ThreadId, MessageId, TaskId, AuthSessionId, Timestamp, Platform, Provider, DeviceStatus, TaskStatus, TaskTraceEventKind, MessageRole, ConnectionRole, AuthSession, CreatePairingInput, PairingCredential, ExchangePairingInput, SessionCredential, PairingResult, Capability, Workspace, Device, Thread, Message, Task, TaskTraceEvent, TaskTrace, ThreadContext, CreateTaskInput, SocketEvent, ErrorResponse, terminalTaskStatuses, isTerminalTask = (task) => terminalTaskStatuses.has(task.status), now = () => Timestamp.make(new Date().toISOString()), makeDeviceId = () => DeviceId.make(crypto.randomUUID()), makeThreadId = () => ThreadId.make(crypto.randomUUID()), makeMessageId = () => MessageId.make(crypto.randomUUID()), makeTaskId = () => TaskId.make(crypto.randomUUID()), makeAuthSessionId = () => AuthSessionId.make(crypto.randomUUID()), decodeCreatePairingInput, decodeExchangePairingInput, decodeCreateTaskInput, decodeDevice, decodeSocketEvent;
 var init_src = __esm(() => {
@@ -330,6 +330,9 @@ class Hub {
       }
     }
   }
+  closeDevice(deviceId) {
+    this.#devices.get(deviceId)?.close(4003, "Device forgotten");
+  }
   hasDevice(deviceId) {
     return this.#devices.get(deviceId)?.readyState === WebSocket2.OPEN;
   }
@@ -588,11 +591,35 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
   });
   const listDevices = Effect9.fn("RelayStore.listDevices")(function* () {
     const rows = yield* Effect9.try({
-      try: () => db.query("SELECT * FROM devices ORDER BY name COLLATE NOCASE, id").all(),
+      try: () => db.query("SELECT * FROM devices WHERE forgotten_at IS NULL ORDER BY name COLLATE NOCASE, id").all(),
       catch: operationError("RelayStore.listDevices")
     });
     return yield* Effect9.forEach(rows, deviceFromRow);
   });
+  const forgetDevice = Effect9.fn("RelayStore.forgetDevice")(function* (deviceId) {
+    const row = yield* Effect9.try({
+      try: () => db.transaction(() => {
+        const device = db.query("SELECT * FROM devices WHERE id = ? AND forgotten_at IS NULL").get(deviceId);
+        if (device === null) {
+          throw new Error(`Unknown device ${deviceId}`);
+        }
+        if (device.status !== "offline") {
+          throw new Error(`Device ${deviceId} must be offline before it can be forgotten`);
+        }
+        const outstanding = db.query(`SELECT COUNT(*) AS count FROM tasks
+               WHERE target_device_id = ? AND status NOT IN ('completed', 'failed', 'cancelled')`).get(deviceId);
+        if ((outstanding?.count ?? 0) > 0) {
+          throw new Error(`Device ${deviceId} still has outstanding tasks`);
+        }
+        const timestamp = now();
+        db.query("UPDATE devices SET forgotten_at = ? WHERE id = ?").run(timestamp, deviceId);
+        db.query("UPDATE auth_sessions SET revoked_at = ? WHERE bound_device_id = ? AND revoked_at IS NULL").run(timestamp, deviceId);
+        return device;
+      })(),
+      catch: operationError("RelayStore.forgetDevice")
+    });
+    return yield* deviceFromRow(row);
+  });
   const recover = Effect9.fn("RelayStore.recover")(function* () {
     yield* Effect9.try({
       try: () => db.transaction(() => {
@@ -620,7 +647,8 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
             architecture = excluded.architecture, status = excluded.status,
             providers_json = excluded.providers_json, capabilities_json = excluded.capabilities_json,
             workspaces_json = excluded.workspaces_json, version = excluded.version,
-            last_seen_at = excluded.last_seen_at, connected_at = excluded.connected_at`).run(device.id, device.name, device.hostname, device.platform, device.architecture, device.status, JSON.stringify(device.providers), JSON.stringify(device.capabilities), JSON.stringify(device.workspaces), device.version, device.lastSeenAt, device.connectedAt ?? null),
+            last_seen_at = excluded.last_seen_at, connected_at = excluded.connected_at,
+            forgotten_at = NULL`).run(device.id, device.name, device.hostname, device.platform, device.architecture, device.status, JSON.stringify(device.providers), JSON.stringify(device.capabilities), JSON.stringify(device.workspaces), device.version, device.lastSeenAt, device.connectedAt ?? null),
       catch: operationError("RelayStore.upsertDevice")
     });
     return device;
@@ -983,6 +1011,7 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
   return Service2.of({
     recover,
     listDevices,
+    forgetDevice,
     upsertDevice,
     heartbeat: (deviceId, status) => updateDeviceStatus(deviceId, status),
     markDeviceOffline: (deviceId) => updateDeviceStatus(deviceId, "offline"),
@@ -1017,7 +1046,7 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
           platform TEXT NOT NULL, architecture TEXT NOT NULL, status TEXT NOT NULL,
           providers_json TEXT NOT NULL, capabilities_json TEXT NOT NULL,
           workspaces_json TEXT NOT NULL, version TEXT NOT NULL, last_seen_at TEXT NOT NULL,
-          connected_at TEXT
+          connected_at TEXT, forgotten_at TEXT
         );
         CREATE TABLE IF NOT EXISTS threads (
           id TEXT PRIMARY KEY, title TEXT NOT NULL, created_at TEXT NOT NULL,
@@ -1065,6 +1094,10 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
         );
         CREATE INDEX IF NOT EXISTS auth_sessions_token ON auth_sessions(token_hash);
       `);
+    const deviceColumns = db.query("PRAGMA table_info(devices)").all();
+    if (!deviceColumns.some((column) => column.name === "forgotten_at")) {
+      db.exec("ALTER TABLE devices ADD COLUMN forgotten_at TEXT");
+    }
   },
   catch: operationError("RelayStore.migrate")
 }), layer2 = (path) => Layer2.effect(Service2, Effect9.acquireRelease(Effect9.try({
@@ -1084,7 +1117,8 @@ var init_store = __esm(() => {
 // apps/relay/src/main.ts
 var exports_main = {};
 __export(exports_main, {
-  runRelay: () => runRelay
+  runRelay: () => runRelay,
+  relayListenOptions: () => relayListenOptions
 });
 import { Effect as Effect10, ManagedRuntime, Schema as Schema11 } from "effect";
 import { createHash as createHash2, timingSafeEqual } from "node:crypto";
@@ -1092,7 +1126,22 @@ import { access as access4, chmod as chmod5 } from "node:fs/promises";
 import { createServer } from "node:http";
 import { platform as platform5 } from "node:os";
 import { WebSocketServer } from "ws";
-var RequestError, json = (value, status = 200) => Response.json(value, {
+var RequestError, relayListenOptions = (configuration, environment = process.env, pid = process.pid) => {
+  const listenPid = Number(environment.LISTEN_PID);
+  const listenFds = Number(environment.LISTEN_FDS);
+  if (listenPid !== pid || !Number.isInteger(listenFds) || listenFds < 1) {
+    return { host: configuration.host, port: configuration.port };
+  }
+  const descriptorNames = environment.LISTEN_FDNAMES?.split(":") ?? [];
+  const namedIndex = descriptorNames.indexOf("cohall-relay");
+  if (namedIndex >= 0 && namedIndex < listenFds) {
+    return { fd: 3 + namedIndex };
+  }
+  if (listenFds === 1) {
+    return { fd: 3 };
+  }
+  throw new Error("Cohall received multiple systemd sockets but none was named cohall-relay");
+}, json = (value, status = 200) => Response.json(value, {
   status,
   headers: {
     "cache-control": "no-store",
@@ -1414,6 +1463,22 @@ Content-Length: 0\r
       if (url.pathname === "/api/devices" && request.method === "GET") {
         return json(yield* store.listDevices());
       }
+      const forgetDevice = url.pathname.match(/^\/api\/devices\/([^/]+)\/forget$/);
+      if (request.method === "POST" && forgetDevice?.[1] !== undefined) {
+        if (principal !== "owner") {
+          return yield* new RequestError({ status: 403, message: "Owner token required" });
+        }
+        const id = yield* pathId(DeviceId, forgetDevice[1]);
+        if (hub.hasDevice(id)) {
+          return yield* new RequestError({
+            status: 409,
+            message: `Device ${id} must be offline before it can be forgotten`
+          });
+        }
+        const forgotten = yield* store.forgetDevice(id);
+        hub.closeDevice(id);
+        return json(forgotten);
+      }
       if (url.pathname === "/api/tasks" && request.method === "POST") {
         const input = yield* body(request, decodeCreateTaskInput);
         const target = yield* chooseDevice(input, sourceDeviceId);
@@ -1444,7 +1509,7 @@ Content-Length: 0\r
       }
       return yield* new RequestError({ status: 404, message: "Route not found" });
     }).pipe(Effect10.mapError((cause) => cause instanceof RequestError ? cause : new RequestError({
-      status: cause._tag !== "RelayStore.PersistenceError" ? 500 : cause.message.startsWith("Unknown") ? 404 : cause.message.includes("outstanding task limit") ? 429 : 500,
+      status: cause._tag !== "RelayStore.PersistenceError" ? 500 : cause.message.startsWith("Unknown") ? 404 : cause.message.includes("outstanding task limit") ? 429 : cause.message.includes("must be offline") || cause.message.includes("still has outstanding tasks") ? 409 : 500,
       message: cause.message
     })));
     return run2(effect).catch((cause) => cause instanceof RequestError ? json({ error: cause.status === 500 ? "Relay request failed" : cause.message }, cause.status) : json({ error: "Relay request failed" }, 500));
@@ -1543,12 +1608,14 @@ Content-Length: 0\r
   });
   await new Promise((resolve3, reject) => {
     server.once("error", reject);
-    server.listen(configuration.port, configuration.host, () => {
+    server.listen(relayListenOptions(configuration), () => {
       server.off("error", reject);
       resolve3();
     });
   });
-  console.log(`Cohall relay listening on http://${configuration.host}:${configuration.port}`);
+  const address = server.address();
+  const listener = typeof address === "string" ? address : address?.family === "IPv6" ? `[${address.address}]:${address.port}` : `${address?.address ?? configuration.host}:${address?.port ?? configuration.port}`;
+  console.log(`Cohall relay listening on http://${listener}`);
   let stopping = false;
   const shutdown = async () => {
     if (stopping) {
@@ -1684,6 +1751,7 @@ var make = (options) => {
   });
   return Service.of({
     devices: () => request("RelayClient.devices", "/api/devices", Schema2.Array(Device)),
+    forgetDevice: (deviceId) => request("RelayClient.forgetDevice", `/api/devices/${encodeURIComponent(deviceId)}/forget`, Device, { method: "POST" }),
     createTask: (input) => request("RelayClient.createTask", "/api/tasks", Task, {
       method: "POST",
       body: JSON.stringify(input)
@@ -2160,6 +2228,22 @@ a lead agent.
 Use the installed \`cohall\` executable when it is available. Fall back to
 \`npx -y @akshar5/cohall\` only when Cohall is not installed globally.
 
+## Recognize cross-device requests
+
+Treat phrases such as “run this on my Mac,” “ask \`@devbox\`,” or “have the Linux
+machine check this” as target intent. The \`@name\` form is a Cohall device
+selector, not chat syntax supplied by the harness. Resolve it with \`cohall
+devices\`, then delegate the smallest useful outcome.
+
+Good reasons to delegate include:
+
+- Xcode, simulators, signing state, or a signed-in browser on a Mac;
+- Docker services, deployment access, or a repository checkout on a server;
+- long tests that can run remotely while useful local work continues;
+- any machine-local tool, file, login, or network access unavailable here.
+
+Do not delegate ordinary local work when the other device provides no advantage.
+
 ## Delegate work
 
 1. List devices unless the target is already explicit:
@@ -2224,6 +2308,12 @@ cohall status <task-id>
 cohall wait <task-id> --timeout 1800
 \`\`\`
 
+An accepted task for an offline target waits durably on the relay and dispatches
+when the device reconnects. Accepted tasks survive relay and device restarts.
+The relay itself must be reachable to accept a new task. Interrupted execution
+uses at-least-once delivery and may run again, so make consequential prompts safe
+to retry.
+
 The timeout error includes the task ID and last known status. The task continues
 unless cancelled:
 
@@ -2323,6 +2413,15 @@ var defaultConfigDirectory = () => {
   }
   return join2(process.env.XDG_CONFIG_HOME ?? join2(homedir2(), ".config"), "cohall");
 };
+var defaultRelayDataDirectory = () => {
+  if (platform2() === "win32") {
+    return join2(process.env.LOCALAPPDATA ?? join2(homedir2(), "AppData", "Local"), "Cohall");
+  }
+  if (platform2() === "darwin") {
+    return join2(homedir2(), "Library", "Application Support", "Cohall", "relay");
+  }
+  return join2(process.env.XDG_DATA_HOME ?? join2(homedir2(), ".local", "share"), "cohall");
+};
 var configurationPath = () => resolve(process.env.COHALL_CONFIG ?? join2(defaultConfigDirectory(), "config.json"));
 var normalizeRelayUrl = (input) => {
   const url = new URL(input);
@@ -2454,9 +2553,12 @@ var loadClientConfiguration = Effect3.tryPromise({
 var loadOwnerConfiguration = Effect3.tryPromise({
   try: async () => {
     const stored = await storedOrDefaults();
-    const token = process.env.COHALL_TOKEN;
-    if (token === undefined) {
-      throw new Error("No owner credential. Set COHALL_TOKEN on the owner-authenticated machine.");
+    const ownerTokenPath = join2(resolve(process.env.COHALL_DATA_DIR ?? defaultRelayDataDirectory()), "owner-token");
+    const token = process.env.COHALL_TOKEN ?? await readFile(ownerTokenPath, "utf8").then((value) => value.trim()).catch(() => {
+      return;
+    });
+    if (token === undefined || token.length === 0) {
+      throw new Error("No owner credential. Run this command on the relay host or set COHALL_TOKEN.");
     }
     return ClientConfiguration.make({
       relayUrl: normalizeRelayUrl(process.env.COHALL_RELAY_URL ?? stored.relayUrl),
@@ -3013,6 +3115,7 @@ Usage:
   cohall pair [--label name] [--client-only]
   cohall sessions
   cohall revoke <session-id>
+  cohall forget <device-id>
   cohall doctor
   cohall upgrade [--to version|latest] [--no-restart] [--dry-run]
   cohall device
@@ -3386,7 +3489,7 @@ var runCli = async (command, raw) => {
     });
     return;
   }
-  if (command === "pair" || command === "sessions" || command === "revoke") {
+  if (command === "pair" || command === "sessions" || command === "revoke" || command === "forget") {
     const { configuration: configuration2, relay: relay2 } = await ownerClient();
     if (command === "pair") {
       allowOptions(arguments_, ["client-only", "label"]);
@@ -3407,6 +3510,11 @@ var runCli = async (command, raw) => {
       print(await Effect5.runPromise(relay2.authSessions()));
       return;
     }
+    if (command === "forget") {
+      allowOptions(arguments_, []);
+      print(await Effect5.runPromise(relay2.forgetDevice(Schema7.decodeUnknownSync(DeviceId)(identifier(arguments_, "device id")))));
+      return;
+    }
     allowOptions(arguments_, []);
     print(await Effect5.runPromise(relay2.revokeAuthSession(Schema7.decodeUnknownSync(AuthSessionId)(identifier(arguments_, "session id")))));
     return;
@@ -3925,4 +4033,4 @@ await main().catch((cause) => {
   process.exitCode = 1;
 });
 
-//# debugId=DF7F5BA91512F2FF64756E2164756E21
+//# debugId=0FE6295B18AAAAEC64756E2164756E21