@akshar5/cohall 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.3.0](https://github.com/AksharP5/cohall/compare/v0.2.0...v0.3.0) (2026-08-06)
+
+
+### Features
+
+* add durable task tracing ([b7c2564](https://github.com/AksharP5/cohall/commit/b7c2564c770453a3c67821a9521aacac4f4a58e2))
+
+## 0.2.0 (2026-08-05)
+
+- Initial public release of the CLI, embedded agent skill, optional MCP server,
+  self-hosted relay, and cross-device delegation runtime.

package/README.md

@@ -117,12 +117,16 @@ npx -y @akshar5/cohall delegate --target @linux --no-wait \
   --prompt 'Run the test suite and report failures.'
 npx -y @akshar5/cohall wait <task-id> --timeout 1800
 npx -y @akshar5/cohall cancel <task-id>
+npx -y @akshar5/cohall trace <task-id> --follow
 npx -y @akshar5/cohall thread <thread-id>
 ```
 
 Follow-ups using the same `thread_id` resume the provider session on the target
 device. Active cancellation remains `cancelling` until the target acknowledges
-that its local process stopped.
+that its local process stopped. `trace` reports the durable relay and device
+lifecycle without prompts, results, credentials, or provider session IDs.
+`--follow` emits changed snapshots as newline-delimited JSON until the task is
+terminal.
 
 ## Optional MCP
 
@@ -132,6 +136,7 @@ server exposes:
 - `list_devices`
 - `delegate`
 - `task_status`
+- `task_trace`
 - `wait_task`
 - `cancel_task`
 - `thread_context`

package/bin/cohall.js

@@ -17,9 +17,9 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // packages/protocol/src/index.ts
 import { Schema } from "effect";
-var version = "0.2.0", 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.3.0", 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, MessageRole, ConnectionRole, AuthSession, CreatePairingInput, PairingCredential, ExchangePairingInput, SessionCredential, PairingResult, Capability, Workspace, Device, Thread, Message, Task, 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;
+})).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(() => {
   DeviceId = uuid("DeviceId");
   ThreadId = uuid("ThreadId");
@@ -39,6 +39,7 @@ var init_src = __esm(() => {
     "failed",
     "cancelled"
   ]);
+  TaskTraceEventKind = Schema.Literals([...TaskStatus.literals, "requeued"]);
   MessageRole = Schema.Literals(["human", "agent", "system"]);
   ConnectionRole = Schema.Literals(["client", "device"]);
   AuthSession = Schema.Struct({
@@ -128,6 +129,28 @@ var init_src = __esm(() => {
     startedAt: Schema.optionalKey(Timestamp),
     completedAt: Schema.optionalKey(Timestamp)
   });
+  TaskTraceEvent = Schema.Struct({
+    kind: TaskTraceEventKind,
+    at: Timestamp,
+    detail: Schema.optionalKey(optionalText(512))
+  });
+  TaskTrace = Schema.Struct({
+    taskId: TaskId,
+    threadId: ThreadId,
+    status: TaskStatus,
+    provider: Provider,
+    sourceDeviceId: Schema.optionalKey(DeviceId),
+    targetDevice: Device,
+    parentTaskId: Schema.optionalKey(TaskId),
+    workspace: Schema.optionalKey(bounded(4096)),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+    startedAt: Schema.optionalKey(Timestamp),
+    completedAt: Schema.optionalKey(Timestamp),
+    events: boundedArray(TaskTraceEvent, 100),
+    truncated: Schema.Boolean,
+    error: Schema.optionalKey(optionalText(16384))
+  });
   ThreadContext = Schema.Struct({
     thread: Thread,
     messages: boundedArray(Message, 20),
@@ -436,6 +459,10 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
   ...row.error === null ? {} : { error: row.error },
   ...row.started_at === null ? {} : { startedAt: row.started_at },
   ...row.completed_at === null ? {} : { completedAt: row.completed_at }
+}), taskTraceEventFromRow = (row) => decode("RelayStore.decodeTaskTraceEvent", TaskTraceEvent, {
+  kind: row.kind,
+  at: row.created_at,
+  ...row.detail === null ? {} : { detail: row.detail }
 }), rolesFromRow = (row) => Schema9.decodeUnknownSync(Schema9.Array(ConnectionRole))(JSON.parse(row.roles_json)), authSessionFromRow = (row) => {
   const roles = rolesFromRow(row);
   const role = roles[0];
@@ -480,7 +507,31 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     selected.unshift(item);
   }
   return { items: selected, truncated: selected.length < items.length };
+}, derivedTraceEvents = (task) => {
+  const detail = "Derived from task timestamps; earlier trace events were not recorded";
+  const events = [
+    TaskTraceEvent.make({ kind: "queued", at: task.createdAt, detail })
+  ];
+  if (task.startedAt !== undefined) {
+    events.push(TaskTraceEvent.make({ kind: "running", at: task.startedAt, detail }));
+  } else if (task.status === "assigned") {
+    events.push(TaskTraceEvent.make({ kind: "assigned", at: task.updatedAt, detail }));
+  }
+  if (task.status === "cancelling") {
+    events.push(TaskTraceEvent.make({ kind: "cancelling", at: task.updatedAt, detail }));
+  }
+  if (task.completedAt !== undefined && (task.status === "completed" || task.status === "failed" || task.status === "cancelled")) {
+    events.push(TaskTraceEvent.make({ kind: task.status, at: task.completedAt, detail }));
+  }
+  return events;
 }, makeService = (db) => {
+  const recordTaskTraceEvent = (taskId, kind, detail, createdAt = now()) => {
+    db.query(`INSERT INTO task_trace_events (task_id, kind, created_at, detail)
+       VALUES (?, ?, ?, ?)`).run(taskId, kind, createdAt, detail);
+    db.query(`DELETE FROM task_trace_events WHERE task_id = ? AND id NOT IN (
+         SELECT id FROM task_trace_events WHERE task_id = ? ORDER BY id DESC LIMIT 1000
+       )`).run(taskId, taskId);
+  };
   const queryTask = (taskId) => db.query("SELECT * FROM tasks WHERE id = ?").get(taskId);
   const getTask = Effect9.fn("RelayStore.getTask")(function* (taskId) {
     const row = yield* Effect9.try({
@@ -495,6 +546,46 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     }
     return yield* taskFromRow(row);
   });
+  const traceTask = Effect9.fn("RelayStore.traceTask")(function* (taskId) {
+    const task = yield* getTask(taskId);
+    const [deviceRow, eventRows] = yield* Effect9.try({
+      try: () => [
+        db.query("SELECT * FROM devices WHERE id = ?").get(task.targetDeviceId),
+        db.query(`SELECT * FROM (
+                 SELECT id, kind, created_at, detail FROM task_trace_events
+                 WHERE task_id = ? ORDER BY id DESC LIMIT 101
+               ) ORDER BY id`).all(taskId)
+      ],
+      catch: operationError("RelayStore.traceTask")
+    });
+    if (deviceRow === null) {
+      return yield* Effect9.fail(new PersistenceError({
+        operation: "RelayStore.traceTask.device",
+        message: `Unknown target device ${task.targetDeviceId}`
+      }));
+    }
+    const targetDevice = yield* deviceFromRow(deviceRow);
+    const selectedRows = eventRows.slice(-100);
+    const recordedEvents = yield* Effect9.forEach(selectedRows, taskTraceEventFromRow);
+    const events = recordedEvents.length === 0 ? derivedTraceEvents(task) : recordedEvents;
+    return TaskTrace.make({
+      taskId: task.id,
+      threadId: task.threadId,
+      status: task.status,
+      provider: task.provider,
+      targetDevice,
+      createdAt: task.createdAt,
+      updatedAt: task.updatedAt,
+      events,
+      truncated: eventRows.length > 100 || recordedEvents.length === 0 || recordedEvents[0]?.kind !== "queued",
+      ...task.sourceDeviceId === undefined ? {} : { sourceDeviceId: task.sourceDeviceId },
+      ...task.parentTaskId === undefined ? {} : { parentTaskId: task.parentTaskId },
+      ...task.workspace === undefined ? {} : { workspace: task.workspace },
+      ...task.startedAt === undefined ? {} : { startedAt: task.startedAt },
+      ...task.completedAt === undefined ? {} : { completedAt: task.completedAt },
+      ...task.error === undefined ? {} : { error: task.error }
+    });
+  });
   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(),
@@ -506,8 +597,12 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     yield* Effect9.try({
       try: () => db.transaction(() => {
         const timestamp = now();
+        const interrupted = db.query("SELECT id FROM tasks WHERE status IN ('assigned', 'running')").all();
         db.query("UPDATE devices SET status = 'offline'").run();
         db.query("UPDATE tasks SET status = 'queued', updated_at = ? WHERE status IN ('assigned', 'running')").run(timestamp);
+        for (const task of interrupted) {
+          recordTaskTraceEvent(TaskId.make(task.id), "requeued", "Relay restarted before the task completed", timestamp);
+        }
         db.query("DELETE FROM auth_pairings WHERE expires_at <= ? OR used_at IS NOT NULL").run(timestamp);
         db.query("UPDATE auth_sessions SET revoked_at = ? WHERE revoked_at IS NULL AND roles_json LIKE '%,%'").run(timestamp);
       })(),
@@ -602,6 +697,7 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
               target_device_id, parent_task_id, workspace, provider_session_id,
               created_at, updated_at
             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(task.id, task.threadId, task.prompt, task.context ?? null, task.provider, task.status, task.sourceDeviceId ?? null, task.targetDeviceId, task.parentTaskId ?? null, task.workspace ?? null, task.providerSessionId ?? null, task.createdAt, task.updatedAt);
+        recordTaskTraceEvent(task.id, "queued", "Relay accepted the task", timestamp);
         db.query(`INSERT INTO messages (
               id, thread_id, role, kind, author_id, author_name, content, created_at,
               task_id, device_id
@@ -658,16 +754,22 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     });
     return yield* Effect9.forEach(rows, taskFromRow);
   });
-  const transition = Effect9.fn("RelayStore.transition")(function* (taskId, expected, update) {
+  const transition = Effect9.fn("RelayStore.transition")(function* (taskId, expected, update, event) {
     const current = yield* getTask(taskId);
     if (!expected.includes(current.status)) {
       return current;
     }
     const placeholders = expected.map(() => "?").join(", ");
+    const timestamp = now();
     yield* Effect9.try({
-      try: () => db.query(`UPDATE tasks SET status = ?, provider_session_id = ?, result = ?, error = ?,
-           started_at = ?, completed_at = ?, updated_at = ?
-           WHERE id = ? AND status IN (${placeholders})`).run(update.status ?? current.status, update.providerSessionId ?? current.providerSessionId ?? null, update.result ?? current.result ?? null, update.error ?? current.error ?? null, update.startedAt ?? current.startedAt ?? null, update.completedAt ?? current.completedAt ?? null, now(), taskId, ...expected),
+      try: () => db.transaction(() => {
+        const result = db.query(`UPDATE tasks SET status = ?, provider_session_id = ?, result = ?, error = ?,
+             started_at = ?, completed_at = ?, updated_at = ?
+             WHERE id = ? AND status IN (${placeholders})`).run(update.status ?? current.status, update.providerSessionId ?? current.providerSessionId ?? null, update.result ?? current.result ?? null, update.error ?? current.error ?? null, update.startedAt ?? current.startedAt ?? null, update.completedAt ?? current.completedAt ?? null, timestamp, taskId, ...expected);
+        if (result.changes === 1 && event !== undefined) {
+          recordTaskTraceEvent(taskId, event.kind, event.detail, timestamp);
+        }
+      })(),
       catch: operationError("RelayStore.transition")
     });
     return yield* getTask(taskId);
@@ -677,13 +779,19 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     if (current.status !== "queued") {
       return current;
     }
+    const timestamp = now();
     yield* Effect9.try({
-      try: () => db.query(`UPDATE tasks SET status = 'assigned', updated_at = ?
-             WHERE id = ? AND status = 'queued' AND NOT EXISTS (
-               SELECT 1 FROM tasks active
-               WHERE active.target_device_id = ? AND active.id <> ?
-                 AND active.status IN ('assigned', 'running', 'cancelling')
-             )`).run(now(), taskId, current.targetDeviceId, taskId),
+      try: () => db.transaction(() => {
+        const result = db.query(`UPDATE tasks SET status = 'assigned', updated_at = ?
+               WHERE id = ? AND status = 'queued' AND NOT EXISTS (
+                 SELECT 1 FROM tasks active
+                 WHERE active.target_device_id = ? AND active.id <> ?
+                   AND active.status IN ('assigned', 'running', 'cancelling')
+               )`).run(timestamp, taskId, current.targetDeviceId, taskId);
+        if (result.changes === 1) {
+          recordTaskTraceEvent(taskId, "assigned", "Relay dispatched the task over the device WebSocket", timestamp);
+        }
+      })(),
       catch: operationError("RelayStore.assignTask")
     });
     return yield* getTask(taskId);
@@ -712,6 +820,7 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
         if (updated.changes !== 1) {
           return;
         }
+        recordTaskTraceEvent(taskId, status, status === "completed" ? "Target device completed the task" : status === "failed" ? "Target device reported a task failure" : "Target device acknowledged cancellation", timestamp);
         if (providerSessionId !== undefined) {
           db.query(`INSERT INTO provider_sessions (thread_id, device_id, provider, session_id, updated_at)
                VALUES (?, ?, ?, ?, ?)
@@ -737,14 +846,26 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     if (["completed", "failed", "cancelled"].includes(current.status)) {
       return current;
     }
-    return current.status === "queued" ? yield* transition(taskId, ["queued"], { status: "cancelled", completedAt: now() }) : yield* transition(taskId, ["assigned", "running", "cancelling"], {
+    if (current.status === "cancelling") {
+      return current;
+    }
+    const timestamp = now();
+    return current.status === "queued" ? yield* transition(taskId, ["queued"], { status: "cancelled", completedAt: timestamp }, { kind: "cancelled", detail: "Client cancelled the task before dispatch" }) : yield* transition(taskId, ["assigned", "running"], {
       status: "cancelling"
-    });
+    }, { kind: "cancelling", detail: "Client requested task cancellation" });
   });
   const requeueTasksFor = Effect9.fn("RelayStore.requeueTasksFor")(function* (deviceId) {
+    const timestamp = now();
     yield* Effect9.try({
-      try: () => db.query(`UPDATE tasks SET status = 'queued', updated_at = ?
-           WHERE target_device_id = ? AND status IN ('assigned', 'running')`).run(now(), deviceId),
+      try: () => db.transaction(() => {
+        const interrupted = db.query(`SELECT id FROM tasks WHERE target_device_id = ?
+               AND status IN ('assigned', 'running')`).all(deviceId);
+        db.query(`UPDATE tasks SET status = 'queued', updated_at = ?
+             WHERE target_device_id = ? AND status IN ('assigned', 'running')`).run(timestamp, deviceId);
+        for (const task of interrupted) {
+          recordTaskTraceEvent(TaskId.make(task.id), "requeued", "Target device disconnected before task completion", timestamp);
+        }
+      })(),
       catch: operationError("RelayStore.requeueTasksFor")
     });
   });
@@ -867,11 +988,12 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
     markDeviceOffline: (deviceId) => updateDeviceStatus(deviceId, "offline"),
     createDelegation: createDelegation2,
     getTask,
+    traceTask,
     threadContext: threadContext2,
     pendingTasksFor,
     assignTask,
-    rollbackAssignment: (taskId) => transition(taskId, ["assigned"], { status: "queued" }),
-    acceptTask: (taskId, deviceId) => requireTarget(taskId, deviceId).pipe(Effect9.flatMap(() => transition(taskId, ["assigned"], { status: "running", startedAt: now() }))),
+    rollbackAssignment: (taskId) => transition(taskId, ["assigned"], { status: "queued" }, { kind: "requeued", detail: "Target device was unavailable during dispatch" }),
+    acceptTask: (taskId, deviceId) => requireTarget(taskId, deviceId).pipe(Effect9.flatMap(() => transition(taskId, ["assigned"], { status: "running", startedAt: now() }, { kind: "running", detail: "Target device accepted the task and started the provider" }))),
     finishTask: (taskId, deviceId, result, providerSessionId) => terminal(taskId, deviceId, "completed", result, undefined, providerSessionId),
     failTask: (taskId, deviceId, error) => terminal(taskId, deviceId, "failed", undefined, error),
     acknowledgeCancellation: (taskId, deviceId) => terminal(taskId, deviceId, "cancelled"),
@@ -919,6 +1041,13 @@ var PersistenceError, Service2, operationError = (operation) => (cause) => new P
         );
         CREATE INDEX IF NOT EXISTS tasks_thread_created ON tasks(thread_id, created_at);
         CREATE INDEX IF NOT EXISTS tasks_target_status ON tasks(target_device_id, status);
+        CREATE TABLE IF NOT EXISTS task_trace_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+          kind TEXT NOT NULL, created_at TEXT NOT NULL, detail TEXT
+        );
+        CREATE INDEX IF NOT EXISTS task_trace_events_task_id
+          ON task_trace_events(task_id, id);
         CREATE TABLE IF NOT EXISTS provider_sessions (
           thread_id TEXT NOT NULL REFERENCES threads(id) ON DELETE CASCADE,
           device_id TEXT NOT NULL REFERENCES devices(id) ON DELETE CASCADE,
@@ -1296,6 +1425,10 @@ Content-Length: 0\r
       if (request.method === "GET" && task?.[1] !== undefined) {
         return json(yield* store.getTask(yield* pathId(TaskId, task[1])));
       }
+      const trace = url.pathname.match(/^\/api\/tasks\/([^/]+)\/trace$/);
+      if (request.method === "GET" && trace?.[1] !== undefined) {
+        return json(yield* store.traceTask(yield* pathId(TaskId, trace[1])));
+      }
       const cancel2 = url.pathname.match(/^\/api\/tasks\/([^/]+)\/cancel$/);
       if (request.method === "POST" && cancel2?.[1] !== undefined) {
         const id = yield* pathId(TaskId, cancel2[1]);
@@ -1556,6 +1689,7 @@ var make = (options) => {
       body: JSON.stringify(input)
     }),
     getTask: (taskId) => request("RelayClient.getTask", `/api/tasks/${encodeURIComponent(taskId)}`, Task),
+    traceTask: (taskId) => request("RelayClient.traceTask", `/api/tasks/${encodeURIComponent(taskId)}/trace`, TaskTrace),
     cancelTask: (taskId) => request("RelayClient.cancelTask", `/api/tasks/${encodeURIComponent(taskId)}/cancel`, Task, {
       method: "POST"
     }),
@@ -1897,12 +2031,15 @@ keeps its local files, credentials, browser state, provider login, skills, and
 permissions. The relay carries prompts, final results, and task state; it is not
 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.
+
 ## Delegate work
 
 1. List devices unless the target is already explicit:
 
    \`\`\`bash
-   npx -y @akshar5/cohall devices
+   cohall devices
    \`\`\`
 
 2. Choose a target whose provider, workspaces, platform, and capabilities fit
@@ -1911,7 +2048,7 @@ a lead agent.
 3. Delegate one concrete outcome. Send only the context the target needs:
 
    \`\`\`bash
-   npx -y @akshar5/cohall delegate \\
+   cohall delegate \\
      --target @macbook \\
      --provider codex \\
      --workspace /Users/me/dev/project \\
@@ -1930,7 +2067,7 @@ a lead agent.
    its local session:
 
    \`\`\`bash
-   npx -y @akshar5/cohall delegate \\
+   cohall delegate \\
      --thread 11111111-1111-4111-8111-111111111111 \\
      --target @macbook \\
      --prompt 'Check whether yesterday’s deployment failed for the same reason.'
@@ -1955,17 +2092,17 @@ ordinary shell or a separate agent turn.
 Queue work when the current agent can make independent progress:
 
 \`\`\`bash
-npx -y @akshar5/cohall delegate --target @linux --no-wait \\
+cohall delegate --target @linux --no-wait \\
   --prompt 'Run the project test suite and report failures.'
-npx -y @akshar5/cohall status <task-id>
-npx -y @akshar5/cohall wait <task-id> --timeout 1800
+cohall status <task-id>
+cohall wait <task-id> --timeout 1800
 \`\`\`
 
 The timeout error includes the task ID and last known status. The task continues
 unless cancelled:
 
 \`\`\`bash
-npx -y @akshar5/cohall cancel <task-id>
+cohall cancel <task-id>
 \`\`\`
 
 Active cancellation is acknowledged by the target device; \`cancelling\` means
@@ -1974,7 +2111,7 @@ the provider process has not confirmed termination yet.
 ## Read shared context
 
 \`\`\`bash
-npx -y @akshar5/cohall thread <thread-id>
+cohall thread <thread-id>
 \`\`\`
 
 This returns a byte-bounded recent window of prompts, final responses, and task
@@ -1985,7 +2122,7 @@ states. Check \`truncated\`; older history remains on the relay when it is true.
 Use \`--prompt-file\` or stdin for multiline work without shell interpolation:
 
 \`\`\`bash
-npx -y @akshar5/cohall delegate --target @macbook --prompt - <<'COHALL_PROMPT'
+cohall delegate --target @macbook --prompt - <<'COHALL_PROMPT'
 Analyze the authenticated pages in the attached task context.
 Return the shared conclusions, disagreements, and source URLs.
 COHALL_PROMPT
@@ -1995,11 +2132,21 @@ Only one input may read stdin. Use \`--context-file\` when the prompt uses stdin
 
 ## Diagnostics
 
-If a command cannot connect or no target is available, run:
+Trace a known task before inspecting machine-local service logs:
+
+\`\`\`bash
+cohall trace <task-id> --follow
+\`\`\`
+
+The trace is redacted and reports relay dispatch, device execution, retries,
+and terminal state. Use \`cohall thread <thread-id>\` when prompt and result
+history is relevant.
+
+If Cohall cannot connect or no target is available, run:
 
 \`\`\`bash
-npx -y @akshar5/cohall doctor
-npx -y @akshar5/cohall devices
+cohall doctor
+cohall devices
 \`\`\`
 
 Return the diagnostic failure to the user rather than claiming remote work ran.
@@ -2197,7 +2344,7 @@ var knownProviders = Provider.literals;
 
 // apps/device/src/delegation.ts
 init_src();
-import { Effect as Effect4, Schema as Schema5 } from "effect";
+import { Effect as Effect4, Schedule, Schema as Schema5 } from "effect";
 
 class DeviceSelectionError extends Schema5.TaggedErrorClass()("Cohall.DeviceSelectionError", { message: Schema5.String, devices: Schema5.Array(Schema5.String) }) {
 }
@@ -2269,6 +2416,22 @@ var waitForTask = Effect4.fn("Cohall.waitForTask")(function* (client, initial, t
   }
   return task;
 });
+var followTaskTrace = Effect4.fn("Cohall.followTaskTrace")(function* (client, taskId, onTrace) {
+  let revision;
+  const poll = client.traceTask(taskId).pipe(Effect4.tap((trace) => {
+    const latest = trace.events.at(-1);
+    const nextRevision = `${trace.status}:${latest?.kind ?? "none"}:${latest?.at ?? "none"}`;
+    if (nextRevision === revision) {
+      return Effect4.succeed(undefined);
+    }
+    revision = nextRevision;
+    return Effect4.sync(() => onTrace(trace));
+  }));
+  return yield* poll.pipe(Effect4.repeat({
+    until: (trace) => terminalTaskStatuses.has(trace.status),
+    schedule: Schedule.spaced("1 second")
+  }));
+});
 var threadContext = Effect4.fn("Cohall.threadContext")(function* (client, threadId) {
   return yield* client.threadContext(threadId);
 });
@@ -2291,7 +2454,7 @@ var valueOptions = new Set([
   "token-file",
   "workspace"
 ]);
-var flagOptions = new Set(["client-only", "no-wait"]);
+var flagOptions = new Set(["client-only", "follow", "no-wait"]);
 var aliases = new Map([
   ["-c", "context"],
   ["-p", "prompt"],
@@ -2310,6 +2473,7 @@ Usage:
                   [--context text] [--thread uuid] [--workspace path]
                   [--timeout seconds] [--no-wait]
   cohall status <task-id>
+  cohall trace <task-id> [--follow]
   cohall wait <task-id> [--timeout seconds]
   cohall cancel <task-id>
   cohall thread <thread-id>
@@ -2405,6 +2569,7 @@ var identifier = (arguments_, label) => {
   return value;
 };
 var print = (value) => console.log(JSON.stringify(value, null, 2));
+var printLine = (value) => console.log(JSON.stringify(value));
 var readInput = async (arguments_, name) => {
   const direct = option(arguments_, name);
   const path = option(arguments_, `${name}-file`);
@@ -2706,6 +2871,16 @@ var runCli = async (command2, raw) => {
     print(taskResult(await Effect5.runPromise(relay.getTask(id))));
     return;
   }
+  if (command2 === "trace") {
+    allowOptions(arguments_, ["follow"]);
+    const id = Schema6.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
+    if (arguments_.options.has("follow")) {
+      await Effect5.runPromise(followTaskTrace(relay, id, printLine));
+      return;
+    }
+    print(await Effect5.runPromise(relay.traceTask(id)));
+    return;
+  }
   if (command2 === "wait") {
     allowOptions(arguments_, ["timeout"]);
     const id = Schema6.decodeUnknownSync(TaskId)(identifier(arguments_, "task id"));
@@ -2730,7 +2905,7 @@ var runCli = async (command2, raw) => {
 
 // apps/device/src/daemon.ts
 init_src();
-import { Effect as Effect6, Schedule, Schema as Schema7 } from "effect";
+import { Effect as Effect6, Schedule as Schedule2, Schema as Schema7 } from "effect";
 import { realpath as realpath2 } from "node:fs/promises";
 import { arch, hostname as hostname2, platform as platform3 } from "node:os";
 import { basename, isAbsolute as isAbsolute2, relative } from "node:path";
@@ -3012,7 +3187,7 @@ var runDaemon = (configuration) => {
     tasks: new Map,
     completed: new Set
   };
-  return connect(configuration, state).pipe(Effect6.repeat({ schedule: Schedule.spaced("2 seconds") }), Effect6.ensuring(Effect6.sync(() => {
+  return connect(configuration, state).pipe(Effect6.repeat({ schedule: Schedule2.spaced("2 seconds") }), Effect6.ensuring(Effect6.sync(() => {
     state.socket?.close();
     for (const controller of state.tasks.values()) {
       controller.abort();
@@ -3069,6 +3244,11 @@ var runMcp = async (configuration) => {
     description: "Read the current state and result of a Cohall task.",
     inputSchema: { task_id: z.string().uuid() }
   }, async ({ task_id }) => output(taskResult(await Effect7.runPromise(client2.getTask(TaskId.make(task_id))))));
+  server.registerTool("task_trace", {
+    title: "Trace a delegated task",
+    description: "Read the redacted relay and device lifecycle for troubleshooting a Cohall task.",
+    inputSchema: { task_id: z.string().uuid() }
+  }, async ({ task_id }) => output(await Effect7.runPromise(client2.traceTask(TaskId.make(task_id)))));
   server.registerTool("wait_task", {
     title: "Wait for delegated work",
     description: "Wait for a Cohall task to finish and return its final result.",
@@ -3126,4 +3306,4 @@ await main().catch((cause) => {
   process.exitCode = 1;
 });
 
-//# debugId=7CC47D186DE52B1264756E2164756E21
+//# debugId=AB53FFE376B97AD664756E2164756E21