@commonlyai/cli 0.1.175 → 0.1.177

package/node_modules/@commonlyai/seats/README.md

@@ -4,6 +4,21 @@ The adapters that run an agent CLI as a supervised seat: one prompt in, one CLI
 
 It is private and is not published on its own. `@commonlyai/cli` depends on it as `file:../packages/seats` and lists it in `bundleDependencies`, so it ships inside the CLI tarball.
 
+## Release path
+
+- A push to `main` touching `cli/` or `packages/seats/` triggers
+  [npm publish](../../.github/workflows/npm-publish.yml). If the packed files changed,
+  it publishes the next CLI patch with seats bundled ([CLI package](../../cli/package.json)).
+  [Deploy Dev](../../.github/workflows/deploy-dev.yml) is manually dispatched and builds service images separately.
+- The publish job assigns the version. PRs leave version lines alone
+  ([version guard](../../.github/workflows/package-version-guard.yml), TASK-466).
+- Operator-pinned fleet seats select their CLI path in each seat's local `run.sh` launcher,
+  outside this repo. Update that pin and restart the seat to load a release.
+  Global CLI installs must be upgraded too; publishing does not update a running seat.
+- Check the running wrapper's CLI path and the live spawn argv to see what it runs
+  ([diagnosis guide](../../docs/runbooks/diagnosing-a-silent-seat.md#2-read-the-live-spawn--the-prompt-is-in-argv)).
+  The registry describes configuration; it does not prove what was loaded.
+
 **Rule:** nothing here imports Commonly code. An adapter that needs Commonly policy (the memory preamble, the legacy sandbox-trust names, the fleet seat-model switch) takes it as a host object through its factory, for example `createHermesAdapter(host)`. The CLI binds that host in `cli/src/lib/adapters/<name>.js`. `cli/__tests__/seats-package.test.mjs` enforces the import rule and checks that the tarball carries every source file.
 
 The extraction plan is D62, extract-in-place.

package/package.json

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

package/src/commands/agent.js

@@ -32,7 +32,7 @@ import {
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
 import { startPoller, terminalDeliveryAckError } from '../lib/poller.js';
 import { formatDigestFrame } from '../lib/digest-frame.js';
-import { startWebhookServer, forwardToLocalWebhook } from '../lib/webhook-server.js';
+import { startWebhookServer, forwardToLocalWebhook, logOnlyHandler } from '../lib/webhook-server.js';
 import { getAdapter, listAdapterNames } from '../lib/adapters/index.js';
 import {
   getSession,
@@ -76,7 +76,7 @@ import {
   formatPodFocusFrame,
   readPodFocus,
 } from '../lib/pod-focus.js';
-import { claimReleaseFor, ackResultFor } from '../lib/claim-outcome.js';
+import { claimReleaseFor, ackResultFor, EMPTY_OUTPUT } from '../lib/claim-outcome.js';
 import { prepareCommitAttribution } from '../lib/commit-attribution.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
@@ -2214,6 +2214,13 @@ export const performRun = ({
         },
       };
     }
+    // Empty output is not the sentinel. A seat that answered `NO_REPLY` read
+    // its batch and chose silence; one that printed nothing may have crashed,
+    // timed out or lost its route without saying so. The bare `no_action`
+    // stays the sentinel's alone, because a digest counts as read only on
+    // that (sable, #2753). Release, hand-off and spawn counting treat
+    // `empty-output` exactly as they treat a bare decline.
+    if (!delivered && !replyText) return { outcome: 'no_action', reason: EMPTY_OUTPUT };
     return { outcome: delivered ? 'posted' : 'no_action' };
   };
 
@@ -2681,9 +2688,15 @@ export const performRun = ({
         for (const entry of actionEntries) entry.result = turnResult;
         // A digest was context in this successful waking turn, never an
         // independent action. If the waking work stood down or the provider
-        // refused the batch, leave it unread for the next real turn.
+        // refused the batch, leave it unread for the next real turn. A reply
+        // the server skipped as `silent_or_empty` is the seat choosing silence
+        // (the server's answer to an intentional NO_REPLY), so it read the
+        // digest. Empty output (`empty-output`) is not a choice anyone can see:
+        // a broken seat produces it every turn, and reading on it would drain
+        // the backlog that seat never saw.
         if (turnResult?.outcome === 'posted'
-          || (turnResult?.outcome === 'no_action' && !turnResult?.reason)) {
+          || (turnResult?.outcome === 'no_action'
+            && (!turnResult?.reason || turnResult.reason === 'silent_or_empty'))) {
           for (const entry of activeEntries) {
             if (entry.event.deliveryMode === 'digest') {
               entry.result = { outcome: 'no_action', reason: 'digest-read' };
@@ -2914,7 +2927,8 @@ export const performRun = ({
           }
           const batchSpawned = batch.entries.some((entry) => (
             entry.result?.outcome === 'posted'
-            || (entry.result?.outcome === 'no_action' && !entry.result?.reason)
+            || (entry.result?.outcome === 'no_action'
+              && (!entry.result?.reason || entry.result.reason === EMPTY_OUTPUT))
           ));
           if (batchSpawned) {
             consecutiveSpawnFailures = 0;
@@ -3462,11 +3476,7 @@ Docs:
         port,
         path: opts.path,
         secret: opts.secret,
-        onEvent: async (event) => {
-          // Developer's agent code handles this — just ack locally
-          console.log(`[local] ${event.type} from pod ${event.podId}`);
-          return { outcome: 'acknowledged' };
-        },
+        onEvent: logOnlyHandler,
         onReady: (url) => console.log(`Local server ready: ${url}`),
       });
 

package/src/lib/claim-outcome.js

@@ -20,8 +20,9 @@
  *                   finite. On any other wake it is terminal. The routing is
  *                   the kernel's: this module only names the outcome.
  *   - `declined`  — a silent, normally completed human broadcast. The agent
- *                   chose not to answer, so the kernel hands it to exactly one
- *                   remaining original listener.
+ *                   chose not to answer, or printed nothing (`empty-output`),
+ *                   so the kernel hands it to exactly one remaining original
+ *                   listener.
  *   - `completed` — everything else that produced a result: a posted reply, or
  *                   a skip with a reason (`no-prompt`, `claim-held`,
  *                   `duplicate-delivery`) where nothing was refused.
@@ -43,6 +44,13 @@ export const REFUSAL_REASONS = ['upstream-refused', 'cascade-cap', 'delivery-ref
 /** What an unclassifiable refusal is recorded as, rather than a fourth class. */
 export const DEFAULT_REFUSAL_REASON = 'delivery-refused';
 
+/**
+ * The reason a turn that printed nothing carries. It releases like a bare
+ * decline, so a human's message still reaches another listener, but it is not
+ * the `NO_REPLY` sentinel and does not mark a digest read.
+ */
+export const EMPTY_OUTPUT = 'empty-output';
+
 /**
  * The range the kernel accepts for a refusal's `status` — its
  * `MIN_UPSTREAM_STATUS` / `MAX_UPSTREAM_STATUS` in `messageClaimService`.
@@ -93,7 +101,7 @@ export const claimReleaseFor = (event, turnResult) => {
   if (event?.type === 'message.posted'
       && event.payload?.senderIsHuman === true
       && turnResult.outcome === 'no_action'
-      && !turnResult.reason) {
+      && (!turnResult.reason || turnResult.reason === EMPTY_OUTPUT)) {
     return { outcome: 'declined' };
   }
   return { outcome: 'completed' };

package/src/lib/poller.js

@@ -8,6 +8,7 @@
 
 import { createClient } from './api.js';
 import { formatDigestFrame } from './digest-frame.js';
+import { EMPTY_OUTPUT } from './claim-outcome.js';
 
 // Delivery failures that must stop a consumer rather than fall through to the
 // normal at-least-once retry path. A stale delivery belongs to a replacement
@@ -80,7 +81,8 @@ export const startPoller = ({
         } : event;
         let result = { outcome: 'no_action' };
         try {
-          result = (await onEvent(forwarded)) || { outcome: 'no_action' };
+          // A handler that returns nothing said nothing: not a read of the digest.
+          result = (await onEvent(forwarded)) || { outcome: 'no_action', reason: EMPTY_OUTPUT };
         } catch (handlerErr) {
           result = { outcome: 'error', reason: handlerErr.message };
         }

package/src/lib/webhook-server.js

@@ -8,6 +8,7 @@
 
 import { createServer } from 'http';
 import { createHmac } from 'crypto';
+import { EMPTY_OUTPUT } from './claim-outcome.js';
 
 export const startWebhookServer = ({
   port = 3001,
@@ -47,9 +48,10 @@ export const startWebhookServer = ({
         return;
       }
 
-      let result = { outcome: 'acknowledged' };
+      // A handler that returns nothing said nothing (#2753).
+      let result = { outcome: 'no_action', reason: EMPTY_OUTPUT };
       try {
-        result = (await onEvent(event)) || { outcome: 'acknowledged' };
+        result = (await onEvent(event)) || { outcome: 'no_action', reason: EMPTY_OUTPUT };
       } catch (err) {
         result = { outcome: 'error', reason: err.message };
       }
@@ -67,6 +69,17 @@ export const startWebhookServer = ({
   });
 });
 
+/**
+ * The handler `agent connect` serves on its own port. It only logs what
+ * arrives, and no agent has read the event, so it states no outcome a read
+ * would count as: the wake still settles, and the pod digest stays unread
+ * (Sable, #2753).
+ */
+export const logOnlyHandler = async (event) => {
+  console.log(`[local] ${event.type} from pod ${event.podId}`);
+  return { outcome: 'no_action', reason: EMPTY_OUTPUT };
+};
+
 /**
  * Forward a polled event to a local webhook server.
  * Used by `agent connect` to bridge polling → local HTTP.
@@ -84,5 +97,13 @@ export const forwardToLocalWebhook = async (event, webhookUrl, secret = null) =>
 
   const res = await fetch(webhookUrl, { method: 'POST', headers, body: payload });
   if (!res.ok) throw new Error(`Local webhook returned HTTP ${res.status}`);
-  try { return await res.json(); } catch { return { outcome: 'acknowledged' }; }
+  // Only a stated outcome counts. An empty or non-JSON body, or one without
+  // an outcome, is a handler that said nothing, the same as a CLI turn that
+  // printed nothing, so it must not read the pod digest (Rhea, #2753).
+  let body = null;
+  try { body = await res.json(); } catch { body = null; }
+  if (!body || typeof body !== 'object' || typeof body.outcome !== 'string') {
+    return { outcome: 'no_action', reason: EMPTY_OUTPUT };
+  }
+  return body;
 };