@commonlyai/cli 0.1.68 → 0.1.70

package/package.json

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

package/src/commands/agent.js

@@ -34,11 +34,13 @@ import { detectMemorySources, composeImport, importMemory } from '../lib/memory-
 import { detectSkills, importSkills } from '../lib/skills-import.js';
 import { parseEnvironmentFile, resolveWorkspace, validateEnvironmentSpec } from '../lib/environment.js';
 import { ADAPTERS_WITH_DEFAULT_MCP, defaultMcpServers } from '../lib/default-environment.js';
+import { withholdGrantBroker } from '../lib/grant-broker-guard.js';
 import {
   FOCUS_FRAME_MAX_CODE_POINTS,
   formatPodFocusFrame,
   readPodFocus,
 } from '../lib/pod-focus.js';
+import { claimReleaseFor, ackResultFor } from '../lib/claim-outcome.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
@@ -871,6 +873,27 @@ export const performRun = ({
   sleepImpl = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
 }) => {
   const client = createClient({ instance: instanceUrl, token });
+
+  // THE SEAT'S OWN RECORD IS THE ONLY DECLARATION THERE IS. The broker reaches a
+  // seat as an injected MCP entry written by hand into its environment — no
+  // server projection puts it there (`GRANT_BROKER_URL` is imported by one
+  // route, the daemon assignment, and that one already refuses). So a seat run
+  // by `commonly agent run` under launchd spawns the entry verbatim, and the
+  // confinement it promises is declared in a different field (`sandbox`), which
+  // can disagree. The daemon half of this refusal already runs
+  // (`daemon-supervisor.js`); this is the same predicate at the only other site
+  // that can see the record — same code, so one refusal with two emitters.
+  //
+  // IN MEMORY, RECORD UNTOUCHED (wren 71641): the withheld environment is what
+  // the adapter spawns with, and the stored record keeps its broker, so the
+  // daemon stays the layer that judges a host it knows. Applied once for the
+  // run rather than per turn: `agent run` reads its record once at boot.
+  const seatEnvironment = withholdGrantBroker(environment, adapter?.name, {
+    instanceUrl,
+    onRefuse: (refusal, names) => log(
+      `${refusal.code} (${refusal.reason}) — withholding ${names.join(', ')}: ${refusal.detail}`,
+    ),
+  });
   let running = true;
   // Stop-after-N-auth-failures: without this, a revoked token leaves the
   // poller hammering 401s forever at 60s backoff — invisible to the user.
@@ -1045,6 +1068,7 @@ export const performRun = ({
       // goes in a sibling field instead of being spelled into the reason.
       return {
         outcome: 'no_action',
+        refused: { reason: 'cascade-cap' },
         reason: 'cascade-cap',
         details: {
           // The id of what was dropped. `reason` and `streak` say a refusal
@@ -1139,16 +1163,19 @@ export const performRun = ({
     } finally {
       // A silent, normally completed human wake is an explicit decline, not
       // a successful answer. Tell the kernel so it can hand the message to
-      // exactly one remaining original listener. Any posted reply, refusal
-      // with a reason, or thrown spawn retains completion/legacy semantics:
-      // re-offering those would duplicate a visible response or defeat normal
-      // at-least-once redelivery after an infrastructure failure.
-      const claimOutcome = event.type === 'message.posted'
-        && event.payload?.senderIsHuman === true
-        && turnResult?.outcome === 'no_action' && !turnResult?.reason
-        ? 'declined'
-        : (turnResult ? 'completed' : undefined);
-      await claimKeeper?.release(claimOutcome);
+      // exactly one remaining original listener. A refusal — the upstream
+      // route down, or the server refusing the post — is NAMED (TASK-099): it
+      // carries its class so the kernel's record can tell "answered" from
+      // "never ran", and on a human wake the kernel hands it on exactly as it
+      // does a decline, because a failure local to THIS seat must not make a
+      // human's message disappear. A thrown spawn keeps the legacy release, so
+      // normal at-least-once redelivery still happens after an infrastructure
+      // failure. One decision point, shared with the batch path — see
+      // lib/claim-outcome.js.
+      const release = claimReleaseFor(event, turnResult);
+      await claimKeeper?.release(release.outcome, {
+        reason: release.reason, status: release.status,
+      });
     }
   };
 
@@ -1190,7 +1217,7 @@ export const performRun = ({
       cwd: agentCwd,
       env: process.env,
       memoryLongTerm,
-      environment,
+      environment: seatEnvironment,
       // Runtime context the Claude/Codex adapters expose only to their
       // per-spawn MCP environment. Claude keeps ${COMMONLY_*} placeholders
       // literal on disk and lets its native MCP parser expand them, so the
@@ -1397,6 +1424,7 @@ export const performRun = ({
     if (deliveryRefusal) {
       return {
         outcome: 'no_action',
+        refused: { reason: 'delivery-refused' },
         reason: deliveryRefusal.reason,
         details: {
           mode: deliveryRefusal.mode,
@@ -1409,14 +1437,22 @@ export const performRun = ({
         },
       };
     }
-    // A refusal is not a decline. `no_action` with no reason means "the agent
-    // chose not to answer" and hands a human wake to one remaining listener;
-    // nothing about the agent's choice happened here — the model never ran — so
-    // say what did happen, and let the event close rather than fan a
-    // route-wide refusal out across the rest of the fleet.
+    // A refusal is not a decline, and it is not a close either. `no_action`
+    // with no reason means "the agent chose not to answer" and hands a human
+    // wake to one remaining listener; nothing about the agent's choice happened
+    // here — the model never ran — so the release says WHICH class of refusal
+    // it was (TASK-099). The kernel routes from there: on a human wake the
+    // message is handed to one remaining listener exactly as a decline is
+    // (this seat's upstream route being down says nothing about theirs), and on
+    // any other wake it is terminal. The free-text detail stays in the seat
+    // log and the event ack; the kernel records the class.
     if (!delivered && upstream) {
       return {
         outcome: 'no_action',
+        refused: {
+          reason: 'upstream-refused',
+          ...(Number.isInteger(upstream.status) ? { status: upstream.status } : {}),
+        },
         reason: `upstream-refused-${upstream.status}`,
         details: {
           status: upstream.status,
@@ -1461,6 +1497,7 @@ export const performRun = ({
 
   const batchAdmissionResult = (event, admission) => ({
     outcome: 'no_action',
+    refused: { reason: 'cascade-cap' },
     reason: 'cascade-cap',
     details: {
       messageId: event?.payload?.messageId || null,
@@ -1646,14 +1683,14 @@ export const performRun = ({
         .filter((entry) => entry.claimKeeper)
         .map(async (entry) => {
           // Preserve ADR-018 D6.1 per binding message: a silent human
-          // broadcast may be handed to one remaining listener, while every
-          // other completed batch item closes normally.
-          const claimOutcome = entry.event.type === 'message.posted'
-            && entry.event.payload?.senderIsHuman === true
-            && turnResult?.outcome === 'no_action' && !turnResult?.reason
-            ? 'declined'
-            : (turnResult ? 'completed' : undefined);
-          await entry.claimKeeper.release(claimOutcome);
+          // broadcast may be handed to one remaining listener, a refusal
+          // closes with its reason, and every other completed batch item
+          // closes normally. Same decision point as the single-event path.
+          // Same decision point as the single-event path.
+          const release = claimReleaseFor(entry.event, turnResult);
+          await entry.claimKeeper.release(release.outcome, {
+            reason: release.reason, status: release.status,
+          });
         }));
     }
   };
@@ -1743,7 +1780,7 @@ export const performRun = ({
             try {
               const deliveryId = event.payload?.deliveryId;
               await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
-                result: entry.result,
+                result: ackResultFor(entry.result),
                 ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
               });
             } catch (ackErr) {
@@ -1843,7 +1880,7 @@ export const performRun = ({
         try {
           const deliveryId = event.payload?.deliveryId;
           await client.post(`/api/agents/runtime/events/${event._id}/ack`, {
-            result,
+            result: ackResultFor(result),
             ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
           });
         } catch (ackErr) {

package/src/lib/claim-outcome.js

@@ -0,0 +1,120 @@
+/**
+ * claimReleaseFor — the ONE decision about how a finished turn releases its
+ * ADR-018 attention claim.
+ *
+ * It lives here, extracted from two byte-identical copies in the run loop
+ * (single-event and batch release), for the reason a second copy is always a
+ * risk: the batch path is the one `message.posted` actually reaches, so a
+ * change applied to only one of them would pass review and do nothing.
+ *
+ * Three outcomes, and the KERNEL decides what each one does with the wake
+ * (TASK-099 ruling, corrected at 71194/71195/71210):
+ *
+ *   - `refused`   — the lease holder could not deliver. Nothing about the
+ *                   agent's CHOICE happened: the model never ran (an upstream
+ *                   429/502/401, named by TASK-096) or the server refused the
+ *                   post. On a HUMAN wake the kernel hands the message to one
+ *                   remaining listener exactly as it does for a decline — a
+ *                   per-seat budget failure must not make a human's message
+ *                   disappear — and records the refuser so the chain stays
+ *                   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.
+ *   - `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.
+ *
+ * The refusal CLASS is an enum, not free text: `upstream-refused` (with the
+ * HTTP status), `cascade-cap`, `delivery-refused`. The kernel stores the class
+ * so refusals are countable, and rejects anything else with a 400. A producer
+ * that cannot classify itself maps to `delivery-refused` before sending — the
+ * mapping is here, in one place, rather than in each producer.
+ *
+ * A thrown turn returns no turnResult and releases with no outcome — the
+ * legacy holder-only DELETE whose at-least-once redelivery is the correct
+ * behaviour for a crashed spawn (the lid closed, the process died).
+ */
+
+/** The classes the kernel accepts. Mirrors `REFUSAL_REASONS` in agentsRuntime. */
+export const REFUSAL_REASONS = ['upstream-refused', 'cascade-cap', 'delivery-refused'];
+
+/** What an unclassifiable refusal is recorded as, rather than a fourth class. */
+export const DEFAULT_REFUSAL_REASON = 'delivery-refused';
+
+/**
+ * The range the kernel accepts for a refusal's `status` — its
+ * `MIN_UPSTREAM_STATUS` / `MAX_UPSTREAM_STATUS` in `messageClaimService`.
+ * A number outside it is not a refusal status the kernel will record: it
+ * answers 400, and the 400 fallback in `enforcement.release` re-releases as
+ * `completed` — which is terminal. So forwarding an out-of-range number does
+ * not merely lose the number, it loses the handoff: an upstream refusal on a
+ * human wake would be recorded as a clean completion. The sender's rule has to
+ * be the receiver's rule, which is why the bound lives here as well as there.
+ */
+export const MIN_UPSTREAM_STATUS = 400;
+export const MAX_UPSTREAM_STATUS = 599;
+
+/**
+ * @param {{type?: string, payload?: {senderIsHuman?: boolean}}} event
+ * @param {{refused?: {reason?: string, status?: number}|true, outcome?: string, reason?: string}|undefined} turnResult
+ * @returns {{outcome?: 'refused'|'declined'|'completed', reason?: string, status?: number}}
+ */
+export const claimReleaseFor = (event, turnResult) => {
+  if (!turnResult) return { outcome: undefined };
+  // `refused: true` is still honoured: it is what an older producer shape (and
+  // a third-party wrapper following TASK-096's docs) sends, and it means the
+  // same thing — `delivery-refused`, the class that claims the least.
+  if (turnResult.refused) {
+    const declared = typeof turnResult.refused === 'object' ? turnResult.refused : {};
+    const reason = REFUSAL_REASONS.includes(declared.reason)
+      ? declared.reason
+      : DEFAULT_REFUSAL_REASON;
+    // The status is the instance of the class, and only the upstream class has
+    // one: a cap refusal or a refused post never saw an upstream HTTP status,
+    // so sending its number would put a field on the record that cannot mean
+    // what a reader would assume. It is also bounded by what the kernel
+    // accepts — an out-of-range number keeps the class and drops only the
+    // number, so the refusal still hands off instead of falling back to
+    // `completed`.
+    const status = reason === 'upstream-refused'
+      && Number.isInteger(declared.status)
+      && declared.status >= MIN_UPSTREAM_STATUS
+      && declared.status <= MAX_UPSTREAM_STATUS
+      ? declared.status
+      : undefined;
+    return {
+      outcome: 'refused',
+      reason,
+      ...(status !== undefined ? { status } : {}),
+    };
+  }
+  if (event?.type === 'message.posted'
+      && event.payload?.senderIsHuman === true
+      && turnResult.outcome === 'no_action'
+      && !turnResult.reason) {
+    return { outcome: 'declined' };
+  }
+  return { outcome: 'completed' };
+};
+
+/**
+ * `refused` is a LOCAL release marker: the producer sets it so the claim
+ * release can name the outcome (see `claimReleaseFor`), and nothing else reads
+ * it. The event ack is a wire payload with its own readers, and the information
+ * that belongs there already reaches them as `reason` — so the marker is
+ * dropped at the ack boundary rather than widening the ack with an internal
+ * flag. Returns the result unchanged when there is no marker, so the common
+ * path never sees a rebuilt object.
+ *
+ * @param {object|undefined} turnResult
+ */
+export const ackResultFor = (turnResult) => {
+  if (!turnResult || !turnResult.refused) return turnResult;
+  // ts-eslint's `arg`/`vars` ignore pattern is `^_`, and ignoreRestSiblings is
+  // off in this repo's config — so the dropped key is renamed rather than
+  // left to trip no-unused-vars.
+  const { refused: _refused, ...rest } = turnResult;
+  return rest;
+};

package/src/lib/enforcement.js

@@ -434,7 +434,7 @@ export const createClaimKeeper = (client, {
       if (timer && typeof timer.unref === 'function') timer.unref();
     },
 
-    async release(outcome) {
+    async release(outcome, { reason, status } = {}) {
       stopRenewal();
       if (!acquired || lost) return;
       try {
@@ -442,7 +442,35 @@ export const createClaimKeeper = (client, {
         // outcome. Besides keeping old clients' DELETE shape intact, callers
         // that assert their transport arguments must not see a synthetic
         // `undefined` body. An explicit outcome is the new D6.1 contract.
-        await (outcome ? client.del(path, { outcome }) : client.del(path));
+        //
+        // `reason` and `status` ride only with a refusal (TASK-099) and only
+        // when the producer named them: the kernel stores the class as the
+        // record of why a delivery never happened, so an absent reason must
+        // stay absent rather than become the string "undefined".
+        if (!outcome) {
+          await client.del(path);
+          return;
+        }
+        const body = {
+          outcome,
+          ...(reason ? { reason } : {}),
+          ...(status !== undefined ? { status } : {}),
+        };
+        try {
+          await client.del(path, body);
+        } catch (err) {
+          // An older kernel validates the outcome against its own
+          // decline/completed enum and answers 400 — as it does for a reason
+          // it does not recognise. A CLI that ships before (or runs against a
+          // server earlier than) the third outcome must still release its
+          // lease, or the message stays claimed until it expires: one retry as
+          // `completed`, which is exactly what the old release did. Bounded to
+          // a 400 — a 500 or a timeout is not turned into a second write, and
+          // a second 400 is not retried again.
+          if (outcome !== 'refused' || err?.status !== 400) throw err;
+          log(`claim on message ${messageId}: kernel rejected the refused outcome (400) — releasing as completed`);
+          await client.del(path, { outcome: 'completed' });
+        }
       } catch {
         // Best-effort: a miss just means the lease already expired.
       }

package/src/lib/environment.js

@@ -69,6 +69,22 @@ export const normalizeSandboxTrust = (sandbox) => (
     ? { ...sandbox, trust: LEGACY_SANDBOX_TRUST[sandbox.trust] }
     : sandbox
 );
+/**
+ * A declared trust resolved THROUGH the legacy table: `internal` → `public`,
+ * anything else (including absent) is itself.
+ *
+ * Exported so every gate reads the mapping once. `normalizeSandboxTrust` above
+ * rewrites a whole sandbox object; this is the scalar form for a site that only
+ * compares the trust and must not write anything back. The server spells the
+ * same predicate `effectiveSandboxTrust` (`grantBrokerConfinement.ts`) — the two
+ * sides have to read `internal` the same way or one of them confines a seat the
+ * other withholds from (Wren 71662).
+ */
+export const effectiveSandboxTrust = (trust) => (
+  typeof trust === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_SANDBOX_TRUST, trust)
+    ? LEGACY_SANDBOX_TRUST[trust]
+    : trust
+);
 
 const expandHome = (p) => {
   if (!p || typeof p !== 'string') return p;

package/src/lib/grant-broker-guard.js

@@ -74,7 +74,7 @@
  */
 import { isGrantBrokerUrl } from './adapters/pi-mcp-client.mjs';
 import { ADAPTERS_WITH_DEFAULT_SANDBOX } from './default-environment.js';
-import { LEGACY_SANDBOX_TRUST } from './environment.js';
+import { effectiveSandboxTrust } from './environment.js';
 import { PUBLIC_SANDBOX_MODES, resolvePublicSandboxMode } from './sandbox/mode.js';
 
 /** One typed code, two emitters (`decidedBy` says which one spoke). */
@@ -92,13 +92,6 @@ export const ENFORCING_MODES = new Set([...PUBLIC_SANDBOX_MODES, 'bwrap']);
 const URL_PLACEHOLDERS = ['${COMMONLY_API_URL}', '${COMMONLY_INSTANCE_URL}'];
 const PARSE_ANCHOR = 'https://grant-declaration.invalid';
 
-/** `internal` → `public`; anything else (including absent) is itself. */
-const effectiveTrust = (trust) => (
-  typeof trust === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_SANDBOX_TRUST, trust)
-    ? LEGACY_SANDBOX_TRUST[trust]
-    : trust
-);
-
 /**
  * A bound instance is only trimmed here (`agent.js` does the same). Any
  * trailing slash it carries is deliberately left alone: the doubled slash it
@@ -190,7 +183,7 @@ export const confinementReason = (environment, adapter, platform = process.platf
   if (sandbox === null || typeof sandbox !== 'object' || Array.isArray(sandbox)) return 'sandbox_absent';
   const declared = sandbox;
   if (declared.mode === 'none') return 'sandbox_mode_none';
-  if (effectiveTrust(declared.trust) !== 'public') return 'sandbox_trust_not_public';
+  if (effectiveSandboxTrust(declared.trust) !== 'public') return 'sandbox_trust_not_public';
   const mode = resolvePublicSandboxMode(declared, platform);
   if (typeof mode !== 'string' || !ENFORCING_MODES.has(mode)) return 'sandbox_mode_unenforceable';
   return null;
@@ -220,7 +213,7 @@ const detailFor = (reason, adapter, environment) => {
   }
   const trust = environment?.sandbox?.trust;
   const shown = trust === undefined ? 'absent' : `'${String(trust)}'`;
-  return `the declared sandbox.trust is ${shown}${shown === 'absent' ? '' : ` (effective '${String(effectiveTrust(trust))}')`},`
+  return `the declared sandbox.trust is ${shown}${shown === 'absent' ? '' : ` (effective '${String(effectiveSandboxTrust(trust))}')`},`
     + " and no host confines a seat whose trust is not 'public'; declare sandbox.trust 'public'" + ` ${drop}`;
 };
 

package/src/lib/sandbox/mode.js

@@ -12,23 +12,30 @@
  *   darwin  → 'workspace' (the claude adapter maps it to Seatbelt)
  *   else    → 'bwrap'     (bubblewrap; attach checks it is installed)
  *
- * Resolution is PUBLIC-only on purpose. A non-public declaration keeps whatever
- * mode it wrote, and an adapter that cannot enforce it is expected to refuse
- * rather than quietly spawn unconfined. An explicit mode on a public
- * declaration still wins — including a wrong one, which the caller then
- * refuses (Vera 69548: an unresolvable public mode must not fall through to a
- * bare, unconfined spawn).
+ * Resolution is PUBLIC-only on purpose, and PUBLIC IS THE EFFECTIVE TRUST: a
+ * legacy `internal` declaration reads as `public` (environment.js, Wren 69585),
+ * so the mapping is applied before this comparison. Comparing the raw value
+ * made `{ trust: 'internal' }` resolve to no mode at all — the mapping was
+ * applied in `confinementReason` and not here, which is half a rule, and the
+ * half that failed was the one that WITHHOLDS: the grant broker was taken from
+ * a seat this daemon would have confined. A non-public declaration keeps
+ * whatever mode it wrote, and an adapter that cannot enforce it is expected to
+ * refuse rather than quietly spawn unconfined. An explicit mode on a public
+ * declaration still wins — including a wrong one, which the caller then refuses
+ * (Vera 69548: an unresolvable public mode must not fall through to a bare,
+ * unconfined spawn).
  *
  * NOT used by the codex adapter. Codex's `mode` is read-vs-write access, not a
  * host mechanism — its permission profiles run on both platforms — so its
  * derived default is 'workspace' everywhere.
  */
+import { effectiveSandboxTrust } from '../environment.js';
 
 export const PUBLIC_SANDBOX_MODES = new Set(['workspace', 'read-only']);
 
 export const resolvePublicSandboxMode = (sandbox, platform = process.platform) => {
   const declared = sandbox?.mode;
-  if (sandbox?.trust !== 'public') return declared;
+  if (effectiveSandboxTrust(sandbox?.trust) !== 'public') return declared;
   if (declared !== undefined && declared !== null) return declared;
   return platform === 'darwin' ? 'workspace' : 'bwrap';
 };