commonswarm 0.1.38 → 0.1.40

package/cswarm.cjs

@@ -13520,7 +13520,7 @@ __export(cli_exports, {
   resolveTurnBudgetOrDefer: () => resolveTurnBudgetOrDefer
 });
 module.exports = __toCommonJS(cli_exports);
-var import_node_crypto19 = require("node:crypto");
+var import_node_crypto20 = require("node:crypto");
 var import_node_fs7 = require("node:fs");
 var import_promises11 = require("node:fs/promises");
 var import_node_path20 = require("node:path");
@@ -33451,6 +33451,7 @@ var FileListenerEffectStore = class {
 };
 
 // src/listener/grok-model.ts
+var import_node_crypto14 = require("node:crypto");
 var import_promises5 = require("node:fs/promises");
 var import_node_os7 = require("node:os");
 var import_node_path11 = require("node:path");
@@ -33695,7 +33696,7 @@ var GrokListenerModel = class {
       clientName: "cswarm-listener"
     });
     try {
-      await handle.session.enablePromptsAfterCanary();
+      await this.enablePromptsAfterGrokCanary(handle);
       this.workerCanary = false;
       this.worker = handle;
       return handle;
@@ -33704,6 +33705,37 @@ var GrokListenerModel = class {
       throw error;
     }
   }
+  /** Force Grok's measured shell permission path without changing worker cwd. */
+  async enablePromptsAfterGrokCanary(handle) {
+    const sentinelPath = (0, import_node_path11.join)(
+      (0, import_node_os7.tmpdir)(),
+      `cswarm-grok-permission-canary-${process.pid}-${(0, import_node_crypto14.randomUUID)()}`
+    );
+    let canaryError;
+    try {
+      await handle.session.enablePromptsAfterCanary({
+        timeoutMs: ACP_CANARY_TIMEOUT_MS,
+        probeText: `Use a shell command to create ${sentinelPath} with content CSWARM_CANARY_NOOP. You must use the shell. Do nothing else.`,
+        ...this.options.onCanaryAttempt ? { onAttempt: this.options.onCanaryAttempt } : {}
+      });
+    } catch (error) {
+      canaryError = error;
+    }
+    let sentinelCreated = false;
+    try {
+      await (0, import_promises5.lstat)(sentinelPath);
+      sentinelCreated = true;
+      await (0, import_promises5.unlink)(sentinelPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (sentinelCreated) {
+      throw new AcpPermissionCanaryError(
+        "Grok bridge wrote the permission canary sentinel; permission denial did not block the write"
+      );
+    }
+    if (canaryError !== void 0) throw canaryError;
+  }
   /** Validate the operator's login artifact without copying or replacing its home. */
   async validateLocalAuth() {
     if (this.options.open) return;
@@ -33760,7 +33792,7 @@ var GrokListenerModel = class {
 };
 
 // src/listener/opencode-model.ts
-var import_node_crypto14 = require("node:crypto");
+var import_node_crypto15 = require("node:crypto");
 var import_promises6 = require("node:fs/promises");
 var import_node_path12 = require("node:path");
 function asError(error) {
@@ -33786,7 +33818,7 @@ var OpenCodeListenerModel = class {
   prepareWorkerCwd;
   permissionMode;
   pendingOpenWaitMs;
-  instanceId = (0, import_node_crypto14.randomUUID)();
+  instanceId = (0, import_node_crypto15.randomUUID)();
   worker = null;
   workerHome = null;
   /** Worker homes retained after failed close or unsettled open. */
@@ -34148,7 +34180,13 @@ var OpenCodeListenerModel = class {
       if (this.closed || this.cancelled || generation !== this.openGeneration) {
         await this.performSingleOwnerCleanup(handle, home, this.instanceId, pending);
       }
-      await handle.session.enablePromptsAfterCanary();
+      if (this.options.onCanaryAttempt) {
+        await handle.session.enablePromptsAfterCanary({
+          onAttempt: this.options.onCanaryAttempt
+        });
+      } else {
+        await handle.session.enablePromptsAfterCanary();
+      }
       if (this.closed || this.cancelled || generation !== this.openGeneration) {
         await this.performSingleOwnerCleanup(handle, home, this.instanceId, pending);
       }
@@ -34193,7 +34231,7 @@ var OpenCodeListenerModel = class {
 };
 
 // src/listener/claude-model.ts
-var import_node_crypto15 = require("node:crypto");
+var import_node_crypto16 = require("node:crypto");
 var import_promises7 = require("node:fs/promises");
 var import_node_os8 = require("node:os");
 var import_node_path13 = require("node:path");
@@ -34336,13 +34374,14 @@ var ClaudeListenerModel = class {
   async enablePromptsAfterClaudeCanary(handle) {
     const sentinelPath = (0, import_node_path13.join)(
       (0, import_node_os8.tmpdir)(),
-      `cswarm-claude-permission-canary-${process.pid}-${(0, import_node_crypto15.randomUUID)()}`
+      `cswarm-claude-permission-canary-${process.pid}-${(0, import_node_crypto16.randomUUID)()}`
     );
     let sentinelCreated = false;
     try {
       await handle.session.enablePromptsAfterCanary({
         timeoutMs: ACP_CANARY_TIMEOUT_MS,
-        probeText: `Create the file ${sentinelPath} using the Write tool with content CSWARM_CANARY_NOOP. You must use the Write tool. Do nothing else.`
+        probeText: `Create the file ${sentinelPath} using the Write tool with content CSWARM_CANARY_NOOP. You must use the Write tool. Do nothing else.`,
+        ...this.options.onCanaryAttempt ? { onAttempt: this.options.onCanaryAttempt } : {}
       });
     } finally {
       try {
@@ -34362,7 +34401,7 @@ var ClaudeListenerModel = class {
 };
 
 // src/listener/codex-model.ts
-var import_node_crypto16 = require("node:crypto");
+var import_node_crypto17 = require("node:crypto");
 var import_promises8 = require("node:fs/promises");
 var import_node_os9 = require("node:os");
 var import_node_path14 = require("node:path");
@@ -34505,13 +34544,14 @@ var CodexListenerModel = class {
   async enablePromptsAfterCodexCanary(handle) {
     const sentinelPath = (0, import_node_path14.join)(
       (0, import_node_os9.tmpdir)(),
-      `cswarm-codex-permission-canary-${process.pid}-${(0, import_node_crypto16.randomUUID)()}`
+      `cswarm-codex-permission-canary-${process.pid}-${(0, import_node_crypto17.randomUUID)()}`
     );
     let sentinelCreated = false;
     try {
       await handle.session.enablePromptsAfterCanary({
         timeoutMs: ACP_CANARY_TIMEOUT_MS,
-        probeText: `Use a shell command to create ${sentinelPath} with content CSWARM_CANARY_NOOP. You must use the shell. Do nothing else.`
+        probeText: `Use a shell command to create ${sentinelPath} with content CSWARM_CANARY_NOOP. You must use the shell. Do nothing else.`,
+        ...this.options.onCanaryAttempt ? { onAttempt: this.options.onCanaryAttempt } : {}
       });
     } finally {
       try {
@@ -34531,7 +34571,7 @@ var CodexListenerModel = class {
 };
 
 // src/listener/runtime.ts
-var import_node_crypto17 = require("node:crypto");
+var import_node_crypto18 = require("node:crypto");
 
 // src/cloud/delivery.ts
 var UUID_RE12 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -35487,7 +35527,7 @@ function sameEffectSignal(record, signal) {
   return record.signalId === signal.id.toLowerCase() && record.signalKind === signal.kind && record.askBody === signal.body && record.askUntil === signal.until && record.senderOwnerRelation === (signal.sender_owner_relation ?? "unknown");
 }
 function immutableSignalFingerprint(signalId, signalKind2, body, until, senderOwnerRelation) {
-  return (0, import_node_crypto17.createHash)("sha256").update(JSON.stringify([
+  return (0, import_node_crypto18.createHash)("sha256").update(JSON.stringify([
     signalId,
     signalKind2,
     body,
@@ -36477,6 +36517,7 @@ var STATUS_ALLOWED_KEYS = /* @__PURE__ */ new Set([
   "stoppedAt",
   "lastSignalId",
   "lastErrorCode",
+  "lastErrorDetail",
   "providerVersion",
   "providerLastMeasuredVersion",
   "lastWorkerStderrTail",
@@ -36538,7 +36579,7 @@ function parseStatus(raw) {
   const nullableUuid2 = (candidate) => candidate === null || typeof candidate === "string" && UUID_RE15.test(candidate);
   const nullableCount = (candidate) => candidate === null || typeof candidate === "number" && Number.isSafeInteger(candidate) && candidate >= 0;
   const nullableTimestamp2 = (candidate) => candidate === null || typeof candidate === "string" && Number.isFinite(Date.parse(candidate));
-  if (row.version !== 1 || typeof row.instanceId !== "string" || !UUID_RE15.test(row.instanceId) || row.provider !== "grok" && row.provider !== "opencode" && row.provider !== "claude" && row.provider !== "codex" || typeof row.profileId !== "string" || typeof row.workspaceId !== "string" || !UUID_RE15.test(row.workspaceId) || typeof row.principalId !== "string" || !UUID_RE15.test(row.principalId) || !Number.isSafeInteger(row.pid) || row.pid < 1 || typeof row.state !== "string" || !["starting", "ready", "stopping", "stopped", "failed"].includes(row.state) || typeof row.startedAt !== "string" || !Number.isFinite(Date.parse(row.startedAt)) || !(row.readyAt === null || typeof row.readyAt === "string" && Number.isFinite(Date.parse(row.readyAt))) || typeof row.updatedAt !== "string" || !Number.isFinite(Date.parse(row.updatedAt)) || !(row.stoppedAt === null || typeof row.stoppedAt === "string" && Number.isFinite(Date.parse(row.stoppedAt))) || !nullableUuid2(row.lastSignalId) || !(row.lastErrorCode === null || typeof row.lastErrorCode === "string" && /^[a-z0-9_-]{1,96}$/.test(row.lastErrorCode)) || !(row.providerVersion === void 0 || row.providerVersion === null || typeof row.providerVersion === "string" && SEMVER_RE2.test(row.providerVersion)) || !(row.providerLastMeasuredVersion === void 0 || row.providerLastMeasuredVersion === null || typeof row.providerLastMeasuredVersion === "string" && SEMVER_RE2.test(row.providerLastMeasuredVersion)) || (row.providerVersion === null || row.providerVersion === void 0) !== (row.providerLastMeasuredVersion === null || row.providerLastMeasuredVersion === void 0) || !(row.lastWorkerStderrTail === void 0 || row.lastWorkerStderrTail === null || typeof row.lastWorkerStderrTail === "string" && row.lastWorkerStderrTail.length > 0 && row.lastWorkerStderrTail.length <= 2048 && !/swm_(?:agt|inv|cap)_/i.test(row.lastWorkerStderrTail)) || typeof row.logPath !== "string" || !(0, import_node_path16.isAbsolute)(row.logPath) || !(row.deliveryMode === void 0 || row.deliveryMode === null || typeof row.deliveryMode === "string" && STATUS_DELIVERY_MODES.has(row.deliveryMode)) || !(row.pendingDeliveryCount === void 0 || nullableCount(row.pendingDeliveryCount)) || !(row.lastTerminalDeliveryFailureCount === void 0 || nullableCount(row.lastTerminalDeliveryFailureCount)) || !(row.lastTerminalDeliveryFailureAt === void 0 || nullableTimestamp2(row.lastTerminalDeliveryFailureAt)) || !(row.lastClaimAt === void 0 || nullableTimestamp2(row.lastClaimAt)) || !(row.lastAckAt === void 0 || nullableTimestamp2(row.lastAckAt)) || !(row.routeMode === void 0 || row.routeMode === "worker" || row.routeMode === "main" || row.routeMode === "split") || !(row.deferOverChars === void 0 || row.deferOverChars === null || typeof row.deferOverChars === "number" && Number.isSafeInteger(row.deferOverChars) && row.deferOverChars >= 1 && row.deferOverChars <= 1e4) || !(row.pendingForMainCount === void 0 || typeof row.pendingForMainCount === "number" && Number.isSafeInteger(row.pendingForMainCount) && row.pendingForMainCount >= 0) || !(row.droppedForMainCount === void 0 || typeof row.droppedForMainCount === "number" && Number.isSafeInteger(row.droppedForMainCount) && row.droppedForMainCount >= 0)) {
+  if (row.version !== 1 || typeof row.instanceId !== "string" || !UUID_RE15.test(row.instanceId) || row.provider !== "grok" && row.provider !== "opencode" && row.provider !== "claude" && row.provider !== "codex" || typeof row.profileId !== "string" || typeof row.workspaceId !== "string" || !UUID_RE15.test(row.workspaceId) || typeof row.principalId !== "string" || !UUID_RE15.test(row.principalId) || !Number.isSafeInteger(row.pid) || row.pid < 1 || typeof row.state !== "string" || !["starting", "ready", "stopping", "stopped", "failed"].includes(row.state) || typeof row.startedAt !== "string" || !Number.isFinite(Date.parse(row.startedAt)) || !(row.readyAt === null || typeof row.readyAt === "string" && Number.isFinite(Date.parse(row.readyAt))) || typeof row.updatedAt !== "string" || !Number.isFinite(Date.parse(row.updatedAt)) || !(row.stoppedAt === null || typeof row.stoppedAt === "string" && Number.isFinite(Date.parse(row.stoppedAt))) || !nullableUuid2(row.lastSignalId) || !(row.lastErrorCode === null || typeof row.lastErrorCode === "string" && /^[a-z0-9_-]{1,96}$/.test(row.lastErrorCode)) || !(row.lastErrorDetail === void 0 || row.lastErrorDetail === null || typeof row.lastErrorDetail === "string" && row.lastErrorDetail.length > 0 && row.lastErrorDetail.length <= 2048 && !/swm_(?:agt|inv|cap)_/i.test(row.lastErrorDetail)) || !(row.providerVersion === void 0 || row.providerVersion === null || typeof row.providerVersion === "string" && SEMVER_RE2.test(row.providerVersion)) || !(row.providerLastMeasuredVersion === void 0 || row.providerLastMeasuredVersion === null || typeof row.providerLastMeasuredVersion === "string" && SEMVER_RE2.test(row.providerLastMeasuredVersion)) || (row.providerVersion === null || row.providerVersion === void 0) !== (row.providerLastMeasuredVersion === null || row.providerLastMeasuredVersion === void 0) || !(row.lastWorkerStderrTail === void 0 || row.lastWorkerStderrTail === null || typeof row.lastWorkerStderrTail === "string" && row.lastWorkerStderrTail.length > 0 && row.lastWorkerStderrTail.length <= 2048 && !/swm_(?:agt|inv|cap)_/i.test(row.lastWorkerStderrTail)) || typeof row.logPath !== "string" || !(0, import_node_path16.isAbsolute)(row.logPath) || !(row.deliveryMode === void 0 || row.deliveryMode === null || typeof row.deliveryMode === "string" && STATUS_DELIVERY_MODES.has(row.deliveryMode)) || !(row.pendingDeliveryCount === void 0 || nullableCount(row.pendingDeliveryCount)) || !(row.lastTerminalDeliveryFailureCount === void 0 || nullableCount(row.lastTerminalDeliveryFailureCount)) || !(row.lastTerminalDeliveryFailureAt === void 0 || nullableTimestamp2(row.lastTerminalDeliveryFailureAt)) || !(row.lastClaimAt === void 0 || nullableTimestamp2(row.lastClaimAt)) || !(row.lastAckAt === void 0 || nullableTimestamp2(row.lastAckAt)) || !(row.routeMode === void 0 || row.routeMode === "worker" || row.routeMode === "main" || row.routeMode === "split") || !(row.deferOverChars === void 0 || row.deferOverChars === null || typeof row.deferOverChars === "number" && Number.isSafeInteger(row.deferOverChars) && row.deferOverChars >= 1 && row.deferOverChars <= 1e4) || !(row.pendingForMainCount === void 0 || typeof row.pendingForMainCount === "number" && Number.isSafeInteger(row.pendingForMainCount) && row.pendingForMainCount >= 0) || !(row.droppedForMainCount === void 0 || typeof row.droppedForMainCount === "number" && Number.isSafeInteger(row.droppedForMainCount) && row.droppedForMainCount >= 0)) {
     throw new Error("stored listener status is malformed");
   }
   const routeMode = row.routeMode ?? "worker";
@@ -36554,6 +36595,7 @@ function parseStatus(raw) {
     lastTerminalDeliveryFailureAt: row.lastTerminalDeliveryFailureAt ?? null,
     lastClaimAt: row.lastClaimAt ?? null,
     lastAckAt: row.lastAckAt ?? null,
+    lastErrorDetail: row.lastErrorDetail ?? null,
     lastWorkerStderrTail: row.lastWorkerStderrTail ?? null,
     providerVersion: row.providerVersion ?? null,
     providerLastMeasuredVersion: row.providerLastMeasuredVersion ?? null,
@@ -36571,6 +36613,9 @@ async function writeListenerStatus(paths, status) {
       throw new Error("listener status is missing delivery metadata fields");
     }
   }
+  if (!("lastErrorDetail" in parsed)) {
+    throw new Error("listener status is missing local error detail metadata");
+  }
   parseStatus(serialized);
   await writeSecureJsonFile(paths.statusPath, serialized);
 }
@@ -36588,6 +36633,9 @@ async function appendListenerEvent(paths, event) {
     "status",
     "failure_code",
     "attempt",
+    "total",
+    "passed",
+    "reason",
     "delay_ms",
     "index",
     "delivery_mode",
@@ -36624,6 +36672,15 @@ async function appendListenerEvent(paths, event) {
     if (!allowed.has(key2)) {
       throw new Error(`listener event field is not allowed: ${key2}`);
     }
+    if ((key2 === "attempt" || key2 === "total") && !(typeof value === "number" && Number.isSafeInteger(value) && value >= 1)) {
+      throw new Error("listener event attempt count is not allowed");
+    }
+    if (key2 === "passed" && typeof value !== "boolean") {
+      throw new Error("listener event canary result is not allowed");
+    }
+    if (key2 === "reason" && !(value === null || typeof value === "string" && value.length > 0)) {
+      throw new Error("listener event canary reason is not allowed");
+    }
     if (key2 === "delivery_mode" && !(value === null || typeof value === "string" && deliveryModes.has(value))) {
       throw new Error("listener event delivery mode is not allowed");
     }
@@ -36658,6 +36715,9 @@ async function appendListenerEvent(paths, event) {
       throw new Error("listener event contains unsafe text");
     }
   }
+  if (event.event === "listener_canary_attempt" && (typeof event.attempt !== "number" || typeof event.total !== "number" || event.attempt > event.total || typeof event.passed !== "boolean" || !(event.reason === null || typeof event.reason === "string"))) {
+    throw new Error("listener canary attempt event is incomplete");
+  }
   await ensureSecureStateDirectory(paths.instanceDirectory);
   const serialized = `${JSON.stringify(event)}
 `;
@@ -36887,7 +36947,7 @@ async function queryListenerControl(paths, command2, timeoutMs = CONTROL_TIMEOUT
 }
 
 // src/listener/supervisor.ts
-var import_node_crypto18 = require("node:crypto");
+var import_node_crypto19 = require("node:crypto");
 var UUID_RE16 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var LISTENER_RESTART_MAX_ATTEMPTS = 5;
 var LISTENER_RESTART_INITIAL_MS = 1e3;
@@ -36931,6 +36991,17 @@ function safeErrorCode(error) {
   const name = error.name.toLowerCase().replace(/[^a-z0-9_-]+/g, "_");
   return name.slice(0, 96) || "listener_error";
 }
+function localDiagnostic(message, maxChars) {
+  const redacted = message.replace(
+    /swm_(?:agt|inv|cap)_[^\s"'\\]*/gi,
+    "[redacted]"
+  ).trim();
+  if (redacted.length === 0) return null;
+  return redacted.slice(0, maxChars);
+}
+function safeErrorDetail(error) {
+  return localDiagnostic(error.message, 2048);
+}
 var TAIL_SERIALIZED_BUDGET_BYTES = 3e3;
 function fitWorkerStderrTailForLog(tail) {
   let fitted = tail.trim();
@@ -36952,7 +37023,7 @@ async function runListenerSupervisor(options) {
   const now = options.now ?? Date.now;
   const startedAt = iso2(now);
   const controller = new AbortController();
-  const proposedInstanceId = (0, import_node_crypto18.randomUUID)();
+  const proposedInstanceId = (0, import_node_crypto19.randomUUID)();
   let status = {
     version: 1,
     instanceId: proposedInstanceId,
@@ -36969,6 +37040,7 @@ async function runListenerSupervisor(options) {
     stoppedAt: null,
     lastSignalId: null,
     lastErrorCode: null,
+    lastErrorDetail: null,
     providerVersion: null,
     providerLastMeasuredVersion: null,
     lastWorkerStderrTail: null,
@@ -37044,6 +37116,7 @@ async function runListenerSupervisor(options) {
       transition("ready", {
         readyAt: event.ts,
         lastErrorCode: null,
+        lastErrorDetail: null,
         lastWorkerStderrTail: null,
         providerVersion: versionNotice?.runningVersion ?? null,
         providerLastMeasuredVersion: versionNotice?.lastMeasuredVersion ?? null
@@ -37051,6 +37124,17 @@ async function runListenerSupervisor(options) {
       log({ ts: event.ts, event: "listener_ready" });
       return;
     }
+    if (event.type === "canary_attempt") {
+      log({
+        ts: event.ts,
+        event: "listener_canary_attempt",
+        attempt: event.attempt,
+        total: event.total,
+        passed: event.passed,
+        reason: event.reason === null ? null : localDiagnostic(event.reason, 128)
+      });
+      return;
+    }
     if (event.type === "effect") {
       status = {
         ...status,
@@ -37244,6 +37328,7 @@ async function runListenerSupervisor(options) {
       transition("starting", {
         readyAt: null,
         lastErrorCode: restartCode,
+        lastErrorDetail: safeErrorDetail(stop.error),
         lastWorkerStderrTail: restartStderrTail,
         providerVersion: null,
         providerLastMeasuredVersion: null
@@ -37259,6 +37344,7 @@ async function runListenerSupervisor(options) {
       transition("stopped", {
         stoppedAt,
         lastErrorCode: null,
+        lastErrorDetail: null,
         lastWorkerStderrTail: null
       });
       log({ ts: stoppedAt, event: "listener_stopped" });
@@ -37268,6 +37354,7 @@ async function runListenerSupervisor(options) {
       transition("failed", {
         stoppedAt,
         lastErrorCode: code,
+        lastErrorDetail: safeErrorDetail(stop.error),
         lastWorkerStderrTail: failedStderrTail
       });
       log({
@@ -37289,6 +37376,9 @@ async function runListenerSupervisor(options) {
     transition("failed", {
       stoppedAt,
       lastErrorCode: code,
+      lastErrorDetail: safeErrorDetail(
+        error instanceof Error ? error : new Error(String(error))
+      ),
       lastWorkerStderrTail: failedStderrTail
     });
     log({
@@ -38204,6 +38294,7 @@ var HOOK_CHECK_TIMEOUT_MS = 3e3;
 var HOOK_DEFAULT_COOLDOWN_SECONDS = 30;
 var HOOK_SURFACED_IDS_MAX = 1024;
 var HOOK_BODY_PREVIEW_CHARS = 240;
+var HOOK_MULTI_PRINCIPAL_GUIDANCE = "This host runs multiple agents. The CommonSwarm hook needs --principal-id. Reinstall it for this agent: cswarm hook install claude --principal-id <uuid> --write";
 function exactKeys2(row, keys) {
   const expected = new Set(keys);
   return Object.keys(row).length === expected.size && Object.keys(row).every((key2) => expected.has(key2));
@@ -38433,7 +38524,7 @@ async function listenerIsLive(context) {
     return false;
   }
 }
-async function discoverContexts(stateDirectory2, isListenerLive = listenerIsLive) {
+async function discoverStoredStatusContexts(stateDirectory2) {
   let entries;
   try {
     entries = await (0, import_promises10.readdir)(stateDirectory2, { withFileTypes: true });
@@ -38450,11 +38541,46 @@ async function discoverContexts(stateDirectory2, isListenerLive = listenerIsLive
       entry.name,
       instanceDirectory
     );
-    const statusIsLive = storedStatus === null ? null : await isListenerLive(storedStatus);
-    if (statusIsLive === false) {
+    if (storedStatus !== null) {
       contexts.push({
         instanceDirectory,
         paths: storedStatus.paths,
+        status: storedStatus.status
+      });
+    }
+  }
+  return contexts;
+}
+async function discoverListenerHookPrincipalIds(stateDirectory2 = defaultListenerStateDirectory()) {
+  if (!(0, import_node_path19.isAbsolute)(stateDirectory2)) return [];
+  const stored = await discoverStoredStatusContexts(stateDirectory2);
+  return [...new Set(stored.map((context) => context.status.principalId))].sort();
+}
+async function discoverContexts(stateDirectory2, principalIds, isListenerLive = listenerIsLive) {
+  const storedContexts = await discoverStoredStatusContexts(stateDirectory2);
+  const availablePrincipals = new Set(
+    storedContexts.map((context) => context.status.principalId)
+  );
+  let selectedPrincipals;
+  if (principalIds === void 0) {
+    if (availablePrincipals.size > 1) {
+      return { contexts: [], requiresPrincipalScope: true };
+    }
+    selectedPrincipals = availablePrincipals;
+  } else {
+    if (principalIds.some((principalId) => !UUID_RE18.test(principalId))) {
+      return { contexts: [], requiresPrincipalScope: false };
+    }
+    selectedPrincipals = new Set(principalIds.map((principalId) => principalId.toLowerCase()));
+  }
+  const contexts = [];
+  for (const storedStatus of storedContexts) {
+    if (!selectedPrincipals.has(storedStatus.status.principalId)) continue;
+    const statusIsLive = await isListenerLive(storedStatus);
+    if (statusIsLive === false) {
+      contexts.push({
+        instanceDirectory: storedStatus.instanceDirectory,
+        paths: storedStatus.paths,
         status: storedStatus.status,
         listenerLive: false,
         credential: null,
@@ -38463,22 +38589,21 @@ async function discoverContexts(stateDirectory2, isListenerLive = listenerIsLive
       continue;
     }
     await deleteSecureJsonFile(
-      (0, import_node_path19.join)(instanceDirectory, RETIRED_HOOK_CREDENTIAL_FILE)
+      (0, import_node_path19.join)(storedStatus.instanceDirectory, RETIRED_HOOK_CREDENTIAL_FILE)
     ).catch(() => void 0);
     try {
-      const credential = await readListenerCredentialState(instanceDirectory);
+      const credential = await readListenerCredentialState(storedStatus.instanceDirectory);
       contexts.push({
-        instanceDirectory,
-        paths: storedStatus?.paths ?? null,
-        status: storedStatus?.status ?? null,
+        instanceDirectory: storedStatus.instanceDirectory,
+        paths: storedStatus.paths,
+        status: storedStatus.status,
         listenerLive: statusIsLive,
         credential,
-        credentialReadFailed: credential === null && storedStatus !== null
+        credentialReadFailed: credential === null
       });
     } catch {
-      if (storedStatus === null) continue;
       contexts.push({
-        instanceDirectory,
+        instanceDirectory: storedStatus.instanceDirectory,
         paths: storedStatus.paths,
         status: storedStatus.status,
         listenerLive: statusIsLive,
@@ -38487,7 +38612,7 @@ async function discoverContexts(stateDirectory2, isListenerLive = listenerIsLive
       });
     }
   }
-  return contexts;
+  return { contexts, requiresPrincipalScope: false };
 }
 function entryFromSignal(signal, principalId, directory, now) {
   const senderName = signal.from_kind === "agent" ? directory?.agents.find((agent) => agent.principal_id === signal.from)?.name ?? null : directory?.members.find((member) => member.user_id === signal.from)?.display_name ?? null;
@@ -38620,10 +38745,16 @@ async function checkListenerHooks(options) {
     if (!Number.isSafeInteger(cooldownSeconds) || cooldownSeconds < 0 || cooldownSeconds > 86400) {
       return "";
     }
-    const contexts = await discoverContexts(
+    const discovery = await discoverContexts(
       stateDirectory2,
+      options.principalIds,
       options.isListenerLive ?? listenerIsLive
     );
+    if (discovery.requiresPrincipalScope) {
+      await (options.write ?? (() => void 0))(HOOK_MULTI_PRINCIPAL_GUIDANCE);
+      return HOOK_MULTI_PRINCIPAL_GUIDANCE;
+    }
+    const contexts = discovery.contexts;
     if (contexts.length === 0) return "";
     const networkAllowed = contexts.some((context) => context.listenerLive !== false) ? await reserveCheck(
       stateDirectory2,
@@ -38849,8 +38980,8 @@ var ACCEPTED_AGENT_CREDENTIAL_MESSAGES = [
   AGENT_CREDENTIAL_MESSAGE_D088
 ];
 function packageVersion() {
-  if ("0.1.38".length > 0) {
-    return "0.1.38";
+  if ("0.1.40".length > 0) {
+    return "0.1.40";
   }
   try {
     const value = JSON.parse(
@@ -38986,8 +39117,8 @@ Usage:
   cswarm listen start ${requiredAgentCredential} [--url <url> --anon-key <key>] --workspace-id <uuid> --provider grok|opencode|claude|codex [--cwd <absolute-path>] [--model <model>] [--effort <level>] [--permissions deny|allow] [--grok-executable <path>] [--opencode-executable <path>] [--claude-executable <path>] [--codex-executable <path>] [--turn-budget <duration>] [--route worker|main|split] [--defer-over <chars>] [--foreground] [--json]
   cswarm listen status [--url <url> --anon-key <key>] --workspace-id <uuid> --principal-id <uuid> [--json]
   cswarm listen stop [--url <url> --anon-key <key>] --workspace-id <uuid> --principal-id <uuid> [--json]
-  cswarm hook check [--cooldown <seconds>]
-  cswarm hook install claude [--write]
+  cswarm hook check [--principal-id <uuid> ...] [--cooldown <seconds>]
+  cswarm hook install claude [--principal-id <uuid>] [--write]
   cswarm hook uninstall claude --write
   cswarm new "<workspace name>" [--url <url> --anon-key <key>] [--json]
   cswarm new --name "<workspace name>" [--url <url> --anon-key <key>] [--json]
@@ -39033,7 +39164,7 @@ Credential selection for command/dogfood:
                             command, dogfood
                                           task protocol commands              -- either form
                             listen start  persists durable state, rotates -- needs expires_at
-                            hook check    reads the listener's owned 0600 credential state;
+                            hook check    reads only the selected listener's owned 0600 credential state;
                                           never accepts or prints a credential
                             hook install/uninstall
                                           edits only local Claude Code settings; no credential
@@ -39065,10 +39196,11 @@ listen start --route worker|main|split chooses where directed messages go. worke
 is the unchanged default. main queues every ask or note for the interactive session.
 split queues messages whose body is longer than --defer-over <chars>; the bound is
 1..10000 and an equal-length message stays on the worker path. Run cswarm hook check
-to surface queued messages. hook check has its own 3s ceiling, exits 0 on every
-outcome, and skips network checks made within --cooldown seconds (default 30).
-hook install claude prints the UserPromptSubmit JSON by default and changes the
-project's .claude/settings.json only with --write; uninstall also requires --write.
+--principal-id <uuid> to surface that agent's queued messages. A bare check works only
+when the state directory holds one principal. hook check has its own 3s ceiling, exits 0
+on every outcome, and skips network checks made within --cooldown seconds (default 30).
+hook install claude prints principal-scoped UserPromptSubmit JSON by default and changes
+the project's .claude/settings.json only with --write; uninstall also requires --write.
 
 Invite, legacy token accept, principal create/revoke, human token mint/revoke, link, new, and workspace close require a
 stored human login. Agent self-surrender of a token uses --agent-token-file or --agent-token-stdin and never takes the secret on argv. Invite-link accept signs in when needed, then accepts and
@@ -39449,7 +39581,7 @@ async function runNew(args) {
   assertWorkspaceName(name);
   const cloud = await target(args);
   const human = await humanCredential(args, cloud);
-  const proposedId = (0, import_node_crypto19.randomUUID)();
+  const proposedId = (0, import_node_crypto20.randomUUID)();
   let result;
   try {
     result = await new ThinCommandClient(cloud).sendConnect({
@@ -41637,6 +41769,11 @@ function renderListenerStatus(status) {
     status.lastSignalId ? `Last handled signal: ${status.lastSignalId}.` : "No signal has been handled yet.",
     status.lastErrorCode ? `Last status code: ${status.lastErrorCode}.` : "No listener error is recorded."
   ];
+  if (status.lastErrorDetail) {
+    const [first, ...rest] = status.lastErrorDetail.split("\n");
+    lines.push(`Last error detail (local only): ${first}`);
+    for (const line of rest) lines.push(`  ${line}`);
+  }
   if (status.lastWorkerStderrTail) {
     const tailLines = status.lastWorkerStderrTail.split("\n").filter((line) => line.trim().length > 0);
     lines.push("Worker stderr (local log only):");
@@ -41766,6 +41903,9 @@ function listenerFailureMessage(code, provider) {
     if (provider === "codex") {
       return "the Codex bridge did not complete the read-only ACP permission canary; no workspace signal prompt was delivered. Confirm ChatGPT/Codex sign-in, then retry";
     }
+    if (provider === "grok") {
+      return "the Grok bridge did not complete the ACP permission canary; no workspace signal prompt was delivered. The local cswarm listen status output includes the final error detail; read it, then retry";
+    }
     return "the host did not prove that CommonSwarm controls ACP tool permissions; no model prompt was delivered";
   }
   if (code === "process_exit") {
@@ -41918,13 +42058,14 @@ async function runConfiguredListener(options) {
       lastWorkerStderrTail = tail.length > 0 ? tail : null;
     };
   };
-  const newModel = () => {
+  const newModel = (onCanaryAttempt) => {
     providerVersionNotice = null;
     return options.provider === "opencode" ? new OpenCodeListenerModel({
       cwd: options.cwd,
       permissionMode: options.permissionMode,
       promptTimeoutMs: resolveTurnBudgetMs,
       onWorkerStderrTail: newWorkerStderrTailSink(),
+      onCanaryAttempt,
       onVersionNotice,
       ...options.model ? { model: options.model } : {},
       ...options.opencodeExecutable ? { executable: options.opencodeExecutable } : options.executable ? { executable: options.executable } : {}
@@ -41933,6 +42074,7 @@ async function runConfiguredListener(options) {
       permissionMode: options.permissionMode,
       promptTimeoutMs: resolveTurnBudgetMs,
       onWorkerStderrTail: newWorkerStderrTailSink(),
+      onCanaryAttempt,
       onVersionNotice,
       ...options.claudeExecutable ? { executable: options.claudeExecutable } : options.executable ? { executable: options.executable } : {}
     }) : options.provider === "codex" ? new CodexListenerModel({
@@ -41940,6 +42082,7 @@ async function runConfiguredListener(options) {
       permissionMode: options.permissionMode,
       promptTimeoutMs: resolveTurnBudgetMs,
       onWorkerStderrTail: newWorkerStderrTailSink(),
+      onCanaryAttempt,
       onVersionNotice,
       ...options.codexExecutable ? { executable: options.codexExecutable } : options.executable ? { executable: options.executable } : {}
     }) : new GrokListenerModel({
@@ -41947,6 +42090,7 @@ async function runConfiguredListener(options) {
       permissionMode: options.permissionMode,
       promptTimeoutMs: resolveTurnBudgetMs,
       onWorkerStderrTail: newWorkerStderrTailSink(),
+      onCanaryAttempt,
       onVersionNotice,
       ...options.model ? { model: options.model } : {},
       ...options.effort ? { effort: options.effort } : {},
@@ -42000,13 +42144,23 @@ async function runConfiguredListener(options) {
             "listener delivery journal was not selected for this instance"
           );
         }
+        const onCanaryAttempt = (attempt, total, result) => {
+          onEvent({
+            type: "canary_attempt",
+            attempt,
+            total,
+            passed: result.passed,
+            reason: result.reason ?? null,
+            ts: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        };
         return await runListenerRuntime({
           target: options.cloud,
           workspaceId: options.workspaceId,
           principalId: options.principalId,
           credentialSession,
           store: effectStore,
-          model: newModel(),
+          model: newModel(onCanaryAttempt),
           signal,
           onEvent,
           declareModel: listenerModelLabel(options.provider),
@@ -42327,7 +42481,13 @@ async function runListen(args) {
   throw new UsageError("listen requires start, status, or stop");
 }
 var CLAUDE_HOOK_COMMAND = "cswarm hook check";
-function claudeUserPromptHookSnippet() {
+function scopedClaudeHookCommand(principalId) {
+  return `${CLAUDE_HOOK_COMMAND} --principal-id ${listenerUuid(principalId, "principal-id")}`;
+}
+function isCommonSwarmClaudeHook(value) {
+  return typeof value === "string" && (value === CLAUDE_HOOK_COMMAND || /^cswarm hook check --principal-id [0-9a-f-]{36}$/.test(value));
+}
+function claudeUserPromptHookSnippet(principalId) {
   return {
     hooks: {
       UserPromptSubmit: [
@@ -42335,7 +42495,7 @@ function claudeUserPromptHookSnippet() {
           hooks: [
             {
               type: "command",
-              command: CLAUDE_HOOK_COMMAND
+              command: scopedClaudeHookCommand(principalId)
             }
           ]
         }
@@ -42360,21 +42520,40 @@ function readProjectSettings(path) {
   }
   return value;
 }
-function installClaudeHook(settings) {
+function installClaudeHook(settings, principalId) {
   const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? { ...settings.hooks } : {};
   const current = Array.isArray(hooks.UserPromptSubmit) ? [...hooks.UserPromptSubmit] : [];
-  const alreadyInstalled = current.some((group) => {
-    if (!group || typeof group !== "object" || Array.isArray(group)) return false;
-    const commands = group.hooks;
-    return Array.isArray(commands) && commands.some(
-      (hook) => hook && typeof hook === "object" && !Array.isArray(hook) && hook.type === "command" && hook.command === CLAUDE_HOOK_COMMAND
-    );
-  });
-  if (!alreadyInstalled) {
-    const snippetHooks = claudeUserPromptHookSnippet().hooks.UserPromptSubmit;
-    current.push(snippetHooks[0]);
+  const command2 = scopedClaudeHookCommand(principalId);
+  let installed = false;
+  const groups = [];
+  for (const group of current) {
+    if (!group || typeof group !== "object" || Array.isArray(group)) {
+      groups.push(group);
+      continue;
+    }
+    const row = { ...group };
+    if (!Array.isArray(row.hooks)) {
+      groups.push(group);
+      continue;
+    }
+    const commands = [];
+    for (const hook of row.hooks) {
+      if (hook && typeof hook === "object" && !Array.isArray(hook) && hook.type === "command" && isCommonSwarmClaudeHook(hook.command)) {
+        if (!installed) {
+          commands.push({ ...hook, command: command2 });
+          installed = true;
+        }
+        continue;
+      }
+      commands.push(hook);
+    }
+    if (commands.length > 0) groups.push({ ...row, hooks: commands });
+  }
+  if (!installed) {
+    const snippetHooks = claudeUserPromptHookSnippet(principalId).hooks.UserPromptSubmit;
+    groups.push(snippetHooks[0]);
   }
-  hooks.UserPromptSubmit = current;
+  hooks.UserPromptSubmit = groups;
   return { ...settings, hooks };
 }
 function uninstallClaudeHook(settings) {
@@ -42394,7 +42573,7 @@ function uninstallClaudeHook(settings) {
       groups.push(group);
       continue;
     }
-    row.hooks = row.hooks.filter((hook) => !(hook && typeof hook === "object" && !Array.isArray(hook) && hook.type === "command" && hook.command === CLAUDE_HOOK_COMMAND));
+    row.hooks = row.hooks.filter((hook) => !(hook && typeof hook === "object" && !Array.isArray(hook) && hook.type === "command" && isCommonSwarmClaudeHook(hook.command)));
     if (row.hooks.length > 0) groups.push(row);
   }
   if (groups.length > 0) hooks.UserPromptSubmit = groups;
@@ -42406,10 +42585,29 @@ function uninstallClaudeHook(settings) {
   }
   return { ...settings, hooks };
 }
+async function hookInstallPrincipalId(args) {
+  const explicit = args.optional("principal-id");
+  if (explicit !== void 0) return listenerUuid(explicit, "principal-id");
+  const principalIds = await discoverListenerHookPrincipalIds(
+    defaultListenerStateDirectory()
+  );
+  if (principalIds.length === 1) return principalIds[0];
+  if (principalIds.length > 1) {
+    throw new Error(
+      "hook install claude found multiple agents on this host. Choose this agent explicitly: cswarm hook install claude --principal-id <uuid> [--write]"
+    );
+  }
+  throw new Error(
+    "hook install claude could not find a listener principal. Name this agent explicitly: cswarm hook install claude --principal-id <uuid> [--write]"
+  );
+}
 async function runHook(args) {
   const command2 = args.positionals[1];
   if (command2 === "check") {
-    args.assertShape(["cooldown"], 2);
+    args.assertShape(["cooldown", "principal-id"], 2);
+    const rawPrincipalIds = args.all("principal-id");
+    if (rawPrincipalIds.some((principalId2) => !UUID_RE19.test(principalId2))) return;
+    const principalIds = rawPrincipalIds.map((principalId2) => principalId2.toLowerCase());
     const rawCooldown = args.optional("cooldown");
     const cooldownSeconds = rawCooldown === void 0 ? void 0 : Number(rawCooldown);
     if (cooldownSeconds !== void 0 && (!/^\d+$/.test(rawCooldown) || !Number.isSafeInteger(cooldownSeconds) || cooldownSeconds < 0 || cooldownSeconds > 86400)) {
@@ -42419,43 +42617,41 @@ async function runHook(args) {
       process.exit(0);
     }, 3e3);
     hardExit.unref();
-    try {
-      await runListenerHookCheck({
-        ...cooldownSeconds === void 0 ? {} : { cooldownSeconds },
-        write: async (output) => {
-          await new Promise((resolve, reject) => {
-            process.stdout.write(`${output}
+    await runListenerHookCheck({
+      ...cooldownSeconds === void 0 ? {} : { cooldownSeconds },
+      ...principalIds.length === 0 ? {} : { principalIds },
+      write: async (output) => {
+        await new Promise((resolve, reject) => {
+          process.stdout.write(`${output}
 `, (error) => {
-              if (error) reject(error);
-              else resolve();
-            });
+            if (error) reject(error);
+            else resolve();
           });
-        }
-      });
-      return;
-    } finally {
-      clearTimeout(hardExit);
-    }
+        });
+      }
+    });
+    return;
   }
   if (command2 !== "install" && command2 !== "uninstall") {
     throw new UsageError("hook requires check, install, or uninstall");
   }
-  args.assertShape(["write"], 3);
+  args.assertShape(command2 === "install" ? ["write", "principal-id"] : ["write"], 3);
   if (args.positionals[2] !== "claude") {
     throw new Error("hook install/uninstall currently supports claude");
   }
   if (command2 === "uninstall" && !args.has("write")) {
     throw new Error("hook uninstall claude requires --write");
   }
-  const snippet = claudeUserPromptHookSnippet();
-  if (!args.has("write")) {
+  const principalId = command2 === "install" ? await hookInstallPrincipalId(args) : null;
+  const snippet = principalId === null ? null : claudeUserPromptHookSnippet(principalId);
+  if (command2 === "install" && !args.has("write")) {
     process.stdout.write(`${JSON.stringify(snippet, null, 2)}
 `);
     return;
   }
   const path = projectClaudeSettingsPath();
   const settings = readProjectSettings(path);
-  const updated = command2 === "install" ? installClaudeHook(settings) : uninstallClaudeHook(settings);
+  const updated = command2 === "install" ? installClaudeHook(settings, principalId) : uninstallClaudeHook(settings);
   (0, import_node_fs7.mkdirSync)((0, import_node_path20.dirname)(path), { recursive: true });
   (0, import_node_fs7.writeFileSync)(path, `${JSON.stringify(updated, null, 2)}
 `, {
@@ -42463,7 +42659,7 @@ async function runHook(args) {
     mode: 384
   });
   process.stdout.write(
-    command2 === "install" ? `Installed the Claude Code UserPromptSubmit hook in ${path}. It runs: ${CLAUDE_HOOK_COMMAND}
+    command2 === "install" ? `Installed the Claude Code UserPromptSubmit hook in ${path}. It runs: ${scopedClaudeHookCommand(principalId)}
 ` : `Removed the CommonSwarm UserPromptSubmit hook from ${path}. Other settings were kept.
 `
   );
@@ -42541,8 +42737,8 @@ async function runFilePut(args) {
     workspaceId: context.selected.selectedWorkspace,
     credential: context.selected.bearer
   };
-  const fileId = (0, import_node_crypto19.randomUUID)();
-  const versionId = (0, import_node_crypto19.randomUUID)();
+  const fileId = (0, import_node_crypto20.randomUUID)();
+  const versionId = (0, import_node_crypto20.randomUUID)();
   const createCommandId = newCommandId();
   const commitCommandId = newCommandId();
   const created = await onceRetried(
@@ -42779,7 +42975,7 @@ async function runDogfood(args) {
   const { selectedWorkspace, bearer } = await commandWorkspaceAndCredential(args, cloud);
   const client = new ThinCommandClient(cloud);
   const route = stream(args);
-  const taskId = args.optional("task-id") ?? (0, import_node_crypto19.randomUUID)();
+  const taskId = args.optional("task-id") ?? (0, import_node_crypto20.randomUUID)();
   const ttl = Number(args.optional("ttl-ms") ?? "3600000");
   if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > 144e5) {
     throw new Error("--ttl-ms must be an integer in 1..14400000");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commonswarm",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "CommonSwarm CLI — coordination for teams where people and AI agents work side by side.",
   "bin": {
     "cswarm": "cswarm.cjs"