@commonlyai/cli 0.1.221 → 0.1.223

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.221",
+  "version": "0.1.223",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -96,6 +96,7 @@ import { createSeatStop } from '../lib/seat-stop.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
 import { describeUpstreamRefusal } from '../lib/upstream-refusal.js';
 import { createTurnRunner, supervisedRunPolicy } from '../lib/supervised-turn.js';
+import { describeFirstOutputWatch } from '../lib/first-output-watchdog.js';
 import {
   DEFAULT_HOOK_TIMEOUT_MS,
   clampHookTimeoutMs,
@@ -1586,6 +1587,7 @@ export const performRun = ({
     seat: agentName, turnTimeoutMs: effectiveTurnTimeoutMs, supervise: supervising, log,
   });
   if (supervising) log(turnRunner.describe(adapter?.name));
+  if (adapter?.name === 'claude') log(describeFirstOutputWatch());
   const runtimeReporter = createRuntimeReporter({
     client: runtimeReportClient || { post: async () => {} },
     harness: adapter.name, detect: () => adapter.detect(),

package/src/lib/adapters/claude.js

@@ -97,6 +97,8 @@ import { claudeConfigDirFor, claudeContextTokens, claudeTranscriptPath } from '.
 import { skillsAsText } from '../skill-prompt.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 import { PUBLIC_WITHHELD_TOOLS } from '../public-withheld-tools.js';
+import { isShippedCommonlyMcpCommand } from '../declared-mcp-guard.js';
+import { isAnswerableToolError, PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE } from '../public-tool-error.js';
 
 // See codex.js for the rationale on bumping the default + env override.
 // Keeping both adapters in lockstep so any wrapper agent runtime has the
@@ -533,6 +535,87 @@ export const claudeResultText = (stdout, { credentials = [] } = {}) => {
     .trim();
 };
 
+// TASK-256: what a public seat's own stream says about its Commonly MCP server.
+// Claude Code reports each server's state in the init event (`connected` or
+// `failed`), and a failed tool call as a `tool_result` with `is_error: true`
+// whose content is the server's text, the shipped MCP's `{status, body,
+// message}` JSON (both measured on Claude Code 2.1.314; `-p` waits for a slow
+// server, so init reports it connected rather than pending). Ready is a positive
+// witness: `connected` in init, or `pending` followed by a Commonly call that
+// returned, since a server may finish starting during the turn. A stream with no
+// init event, or with a Commonly server in any other state, never showed the
+// server working, so the turn is withheld. A failed
+// Commonly call withholds it unless `isAnswerableToolError` names an answer the
+// person can be given (the predicate the OpenCode adapter uses). Only servers
+// that run the shipped Commonly MCP count. Returns the failure, or null.
+const toolResultText = (content) => {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter((part) => part?.type === 'text').map((part) => String(part.text ?? '')).join('');
+};
+
+export const claudePublicMcpWitness = (stdout, mcpServers) => {
+  const names = (Array.isArray(mcpServers) ? mcpServers : [])
+    .filter((server) => server?.name && isShippedCommonlyMcpCommand(server.command))
+    .map((server) => String(server.name));
+  if (!names.length) return null;
+  const events = String(stdout || '').split('\n').map(parseEvent).filter(Boolean);
+  const init = events.find((event) => event.type === 'system' && event.subtype === 'init');
+  const servers = Array.isArray(init?.mcp_servers) ? init.mcp_servers : [];
+  const toolNames = new Map();
+  for (const event of events) {
+    if (event.type !== 'assistant') continue;
+    for (const block of event.message?.content || []) {
+      if (block?.type === 'tool_use' && block.id) toolNames.set(block.id, String(block.name || ''));
+    }
+  }
+  const results = events
+    .filter((event) => event.type === 'user' && Array.isArray(event.message?.content))
+    .flatMap((event) => event.message.content)
+    .filter((block) => block?.type === 'tool_result')
+    .map((block) => ({ block, tool: toolNames.get(block.tool_use_id) || '' }));
+  // Init names a server as declared; tool names carry it with every character
+  // outside [A-Za-z0-9_-] turned to `_` (`commonly.me` → `mcp__commonly_me__`,
+  // measured on 2.1.314).
+  const prefixOf = (name) => `mcp__${name.replace(/[^A-Za-z0-9_-]/g, '_')}__`;
+  for (const name of names) {
+    const status = servers.find((server) => server?.name === name)?.status;
+    const returned = status === 'pending'
+      && results.some(({ block, tool }) => block.is_error !== true && tool.startsWith(prefixOf(name)));
+    if (status !== 'connected' && !returned) {
+      return { code: PUBLIC_MCP_NOT_READY_CODE, tool: name, error: init ? `status ${status || 'absent'}` : 'no init event' };
+    }
+  }
+  const prefixes = names.map(prefixOf);
+  for (const { block, tool } of results) {
+    if (block.is_error !== true || !prefixes.some((prefix) => tool.startsWith(prefix))) continue;
+    const error = toolResultText(block.content);
+    if (!isAnswerableToolError(error)) return { code: PUBLIC_TOOL_FAILED_CODE, tool, error };
+  }
+  return null;
+};
+
+const publicWitnessError = ({ code, tool, error }) => {
+  const reason = String(error).replace(/\s+/g, ' ').slice(0, 160) || '(empty error)';
+  const what = code === PUBLIC_MCP_NOT_READY_CODE
+    ? `Commonly MCP server ${tool} was not shown connected`
+    : `Commonly tool ${tool} failed in a way the model must not narrate`;
+  const failure = new Error(
+    `public seat withheld this turn's reply: ${what} (${reason}), so nothing was posted and the event stays unacked for retry`,
+  );
+  failure.code = code;
+  return failure;
+};
+
+// The reply a turn posts. A public seat's turn is witnessed first (TASK-256).
+const turnReply = (stdout, { credentials, publicMcp }) => {
+  if (publicMcp) {
+    const failure = claudePublicMcpWitness(stdout, publicMcp);
+    if (failure) throw publicWitnessError(failure);
+  }
+  return claudeResultText(stdout, { credentials });
+};
+
 // The failure tail for a non-zero exit. Stream events are mostly system init
 // and status lines, which would push the terminal error past the 2000-char cut,
 // so keep the result text, or the lines that are not system or stream events.
@@ -593,6 +676,13 @@ const runClaude = ({
       const table = Number.isInteger(proc.pid) ? processTable() : null;
       if (table) stallSnapshot = descendantsOf(table, proc.pid);
       killProcessTree(proc, 'SIGTERM', treeIo(() => table));
+      // A stopped process holds a SIGTERM it handles (claude does) until it is
+      // continued, so a turn frozen with SIGSTOP sat out the whole grace below:
+      // 191 s on a 180 s window (rivet, 2026-11-01). SIGCONT lets it act on the
+      // SIGTERM now. A process that is not stopped is unaffected unless it
+      // handles SIGCONT (a job-control shell does); the SIGKILL below still
+      // lands at the grace either way.
+      killProcessTree(proc, 'SIGCONT', treeIo(() => table));
       // A process parked in a system call may not act on SIGTERM. SIGKILL the
       // child, its group when it leads one, and its descendants.
       stallKill = setTimeout(() => {
@@ -1191,6 +1281,10 @@ export default {
     // undefined and '' as absence itself; it does not need a guard, it needs
     // the value.
     const publicTrust = isConfinedTrust(ctx.environment?.sandbox?.trust);
+    // Only a stranger-facing seat is witnessed (TASK-256). A workspace seat is
+    // confined too, but it answers its own team, and an outage it narrates
+    // there is a signal, not a leak.
+    const witnessedMcp = ctx.environment?.sandbox?.trust === 'public' ? ctx.environment?.mcp : null;
     const workCues = publicTrust ? [] : WORK_CUES;
     const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
       freshSession: !isResume,
@@ -1330,12 +1424,16 @@ export default {
       const contextTokens = claudeContextTokens({
         cwd: physicalPath(ctx.cwd), sessionId, configDir: claudeConfigDirFor({ ...env, HOME: childHome || env?.HOME }),
       });
-      return { text: claudeResultText(stdout, { credentials: spawnCredentials(spawnCtx) }), newSessionId: sessionId, contextTokens };
+      return {
+        text: turnReply(stdout, { credentials: spawnCredentials(spawnCtx), publicMcp: witnessedMcp }),
+        newSessionId: sessionId,
+        contextTokens,
+      };
     } catch (err) {
       // A public seat's refusal is not a session-store failure, whatever its
       // message happens to contain: it must reach the run loop, never the
       // fresh-session retry below (#2247).
-      if (err?.code === PUBLIC_MCP_UNAVAILABLE_CODE) throw err;
+      if ([PUBLIC_MCP_UNAVAILABLE_CODE, PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE].includes(err?.code)) throw err;
       // Self-heal against a corrupted session store. If the persisted id is
       // already in use (or claude has forgotten about it), discard it and
       // restart the turn with a fresh UUID. Without this, a single bad
@@ -1393,7 +1491,11 @@ export default {
           cwd: physicalPath(ctx.cwd), sessionId: freshId,
           configDir: claudeConfigDirFor({ ...retry.env, HOME: retry.childHome || retry.env?.HOME }),
         });
-        return { text: claudeResultText(stdout, { credentials: spawnCredentials(retryCtx) }), newSessionId: freshId, contextTokens };
+        return {
+          text: turnReply(stdout, { credentials: spawnCredentials(retryCtx), publicMcp: witnessedMcp }),
+          newSessionId: freshId,
+          contextTokens,
+        };
       }
       throw err;
     } finally {

package/src/lib/adapters/opencode.js

@@ -56,7 +56,7 @@ import { wrapArgvWithSeatbelt } from '../sandbox/seatbelt.js';
 import { resolvePublicSandboxMode } from '../sandbox/mode.js';
 import { resolveProviderKeyFile, startProviderProxy } from '../provider-proxy.js';
 import { isShippedCommonlyMcpCommand } from '../declared-mcp-guard.js';
-import { isAnswerableToolError } from '../public-tool-error.js';
+import { isAnswerableToolError, PUBLIC_TOOL_FAILED_CODE } from '../public-tool-error.js';
 import { startInstanceProxy } from '../instance-proxy.js';
 import { PUBLIC_WITHHELD_TOOLS } from '../public-withheld-tools.js';
 
@@ -390,7 +390,7 @@ const makeEventParser = () => {
 // stays beside the adapter-agnostic readiness witness (TASK-256): it sees the
 // runtime's own view of each call, and the witness sees a server that never
 // started, so each catches what the other cannot.
-export const PUBLIC_TOOL_FAILED_CODE = 'public_tool_failed';
+export { PUBLIC_TOOL_FAILED_CODE };
 
 export const publicToolFailure = (toolErrors, mcpServers) => {
   const prefixes = (Array.isArray(mcpServers) ? mcpServers : [])

package/src/lib/first-output-watchdog.js

@@ -77,6 +77,17 @@ export const physicalPath = (dir) => {
 // How long a stalled spawn gets to exit after SIGTERM before SIGKILL.
 export const STALL_KILL_GRACE_MS = 10_000;
 
+// The boot line for a claude seat. This watchdog is the stall guard a claude
+// turn runs: the seats supervisor's stall window is off for claude
+// (STALL_DEFAULTS_MS in supervised-turn.js), and its package default of 120 s
+// was once read as this one's (the G6 walk, 2026-11-01).
+export const describeFirstOutputWatch = (env = process.env) => {
+  const windowMs = firstOutputWindowMs(env);
+  if (!windowMs) return 'first-output watchdog OFF for claude (COMMONLY_FIRST_OUTPUT_WINDOW_MS=0)';
+  return `first-output watchdog ON for claude: a turn with no model output in ${windowMs}ms is killed `
+    + `(SIGTERM, then SIGKILL ${STALL_KILL_GRACE_MS}ms later if it is still alive)`;
+};
+
 /**
  * SIGKILL each snapshotted descendant of a stalled spawn that is still alive
  * once the spawn itself has exited. Its parent may have exited, so it may now

package/src/lib/public-tool-error.js

@@ -33,6 +33,12 @@
 
 export const ANSWERABLE_API_STATUSES = new Set([400, 403, 404, 409, 410, 413, 422]);
 
+// The two ways a public turn is withheld over its Commonly MCP server: a tool
+// call failed in a way the model must not narrate, or the server was never shown
+// working. Both leave the event unacked for retry.
+export const PUBLIC_TOOL_FAILED_CODE = 'public_tool_failed';
+export const PUBLIC_MCP_NOT_READY_CODE = 'public_mcp_not_ready';
+
 const INVALID_ARGUMENTS_RE = /^The \S+ tool was called with invalid arguments: /;
 
 const parsePayload = (text) => {

package/src/lib/spawn-retry.js

@@ -7,6 +7,8 @@
  * retry policy here so every adapter gets the same bounded behavior.
  */
 
+import { PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE } from './public-tool-error.js';
+
 export const SPAWN_FAILURE_CLASS = Object.freeze({
   // The provider refused the request's CONTENT. Re-sending the same content
   // can only be refused again, so this class is never retried: the run loop
@@ -121,6 +123,15 @@ const errorText = (error) => [
 
 export const classifySpawnFailure = (error) => {
   const text = errorText(error);
+  // A public seat's withheld turn (TASK-256) quotes the tool's own error, which
+  // is vendor text: the code decides, so the event stays unacked for retry and
+  // is never acked as refused or parked behind a quota or configuration
+  // cooldown by that text. A throttle keeps its backoff, which also retries.
+  if (error?.code === PUBLIC_TOOL_FAILED_CODE || error?.code === PUBLIC_MCP_NOT_READY_CODE) {
+    return error?.status === 429 || RATE_LIMIT_RE.test(text)
+      ? SPAWN_FAILURE_CLASS.RATE_LIMIT
+      : SPAWN_FAILURE_CLASS.RUNTIME;
+  }
   // First: the refusal text carries none of the words below today, but a
   // refusal must never be read as a transient condition and retried.
   if (CONTENT_REFUSED_RE.test(text)) return SPAWN_FAILURE_CLASS.CONTENT_REFUSED;