@commonlyai/cli 0.1.18 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.18",
+  "version": "0.1.24",
   "license": "Apache-2.0",
   "description": "The Commonly CLI \u2014 connect agents, manage pods, iterate fast",
   "type": "module",
@@ -28,7 +28,8 @@
   ],
   "scripts": {
     "start": "node src/index.js",
-    "lint": "eslint src/",
+    "lint": "eslint src --ext .js",
+    "lint:fix": "eslint src --ext .js --fix",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "prepublishOnly": "node -e \"require('fs').copyFileSync('../docs/agents/skills/commonly/SKILL.md','skills/commonly/SKILL.md')\""
   },
@@ -36,6 +37,7 @@
     "commander": "^12.0.0"
   },
   "devDependencies": {
+    "eslint": "^8.56.0",
     "jest": "^29.7.0"
   },
   "jest": {

package/src/commands/agent.js

@@ -351,6 +351,25 @@ export const assertSandboxDeclaredForPublicPod = async ({
   );
 };
 
+// ── wake: toggle ADR-018 ambient wake on an attached agent ──────────────────
+
+/**
+ * Set `config.wakeOnMessage.enabled` on an installation via the registry
+ * PATCH route (user JWT, pod member or creator). Pure core — takes the token
+ * record so the command doesn't need to ask for the pod again.
+ */
+export const setWakeOnMessage = async ({ client, record, enabled }) => {
+  if (!record?.podId || !record?.agentName) {
+    throw new Error('token record is missing podId/agentName — re-attach the agent');
+  }
+  const instanceId = record.instanceId || 'default';
+  await client.patch(
+    `/api/registry/pods/${record.podId}/agents/${record.agentName}`,
+    { instanceId, config: { wakeOnMessage: { enabled: Boolean(enabled) } } },
+  );
+  return { agentName: record.agentName, podId: record.podId, instanceId, enabled: Boolean(enabled) };
+};
+
 // ── attach: register a local-CLI-wrapped agent (ADR-005) ────────────────────
 
 /**
@@ -364,6 +383,7 @@ export const performAttach = async ({
   podId,
   displayName,
   envPath = null,
+  wakeOnMessage = false,
   log = () => {},
 }) => {
   const adapter = getAdapter(adapterName);
@@ -506,6 +526,10 @@ export const performAttach = async ({
         host: 'byo',
       },
       ...(environment ? { environment } : {}),
+      // ADR-018: ambient wake is a per-install opt-in read by
+      // agentMentionService (`config.wakeOnMessage.enabled === true`, default
+      // OFF). Until now the only way to set it for a BYO seat was a DB write.
+      ...(wakeOnMessage ? { wakeOnMessage: { enabled: true } } : {}),
     },
     scopes: ['context:read', 'messages:write', 'memory:read', 'memory:write'],
   });
@@ -1069,6 +1093,7 @@ export const performRun = ({
       && /^(HEARTBEAT_OK|HEARTBEAT_NOOP)$/i.test(replyText);
     const silentReply = !replyText || replyText === 'NO_REPLY' || heartbeatControlReply;
     let delivered = agentPostedItself;
+    let deliveryRefusal = null;
 
     if (event.type === 'agent.ask') {
       if (silentReply) {
@@ -1154,11 +1179,32 @@ export const performRun = ({
         uploadName: `${agentName}-reply-${event._id}.md`,
         log: (line) => log(`[${event.type}] ${line}`),
       });
-      delivered = true;
-      log(
-        `[${event.type}] posted ${Buffer.byteLength(replyText)} bytes as `
-        + `${delivery.messages} message${delivery.messages === 1 ? '' : 's'} (${delivery.mode})`,
-      );
+      if (delivery.refused) {
+        // A run-cap refusal is a successful HTTP request but not a delivery.
+        // Ack it so the kernel does not replay the same text (the server
+        // guidance expressly says not to retry unchanged), while preserving
+        // the refusal and its partial-post count for the seat and event ledger.
+        deliveryRefusal = delivery;
+        const guidance = delivery.guidance || 'The server refused this message; do not retry it unchanged.';
+        const detail = `after ${delivery.messages}/${delivery.attemptedMessages} message${delivery.attemptedMessages === 1 ? '' : 's'}`;
+        log(`[${event.type}] wrapper delivery refused ${detail} (${delivery.reason}): ${guidance}`);
+        onError?.(Object.assign(
+          new Error(`${event.type} wrapper delivery refused ${detail}: ${guidance}`),
+          {
+            code: 'agent_delivery_refused',
+            reason: delivery.reason,
+            eventId: event._id,
+            postedMessages: delivery.messages,
+            attemptedMessages: delivery.attemptedMessages,
+          },
+        ));
+      } else {
+        delivered = true;
+        log(
+          `[${event.type}] posted ${Buffer.byteLength(replyText)} bytes as `
+          + `${delivery.messages} message${delivery.messages === 1 ? '' : 's'} (${delivery.mode})`,
+        );
+      }
     }
     if (result.memorySummary) {
       try {
@@ -1176,6 +1222,21 @@ export const performRun = ({
     // streak. Recording only on completion means a spawn failure that gets
     // redelivered never double-counts toward the cap.
     cascadeGovernor.record(eventPodId, trigger);
+    if (deliveryRefusal) {
+      return {
+        outcome: 'no_action',
+        reason: deliveryRefusal.reason,
+        details: {
+          mode: deliveryRefusal.mode,
+          postedMessages: deliveryRefusal.messages,
+          attemptedMessages: deliveryRefusal.attemptedMessages,
+          ...(typeof deliveryRefusal.consecutive === 'number'
+            ? { consecutive: deliveryRefusal.consecutive }
+            : {}),
+          ...(deliveryRefusal.guidance ? { guidance: deliveryRefusal.guidance } : {}),
+        },
+      };
+    }
     return { outcome: delivered ? 'posted' : 'no_action' };
   };
 
@@ -1724,6 +1785,7 @@ Docs:
     .option('--env <path>', 'Path to environment.json (ADR-008 — sandbox/skills/MCP)')
     .option('--import-memory [path]', 'Import local memory (CLAUDE.md / MEMORY.md / ~/.claude project memory, or a given file/dir) into the agent after attach')
     .option('--yes', 'Skip the import confirmation prompt')
+    .option('--wake-on-message', 'Wake this agent on every message in the pod, not only @mentions (ADR-018 ambient wake; default off). Change later with: commonly agent wake <name> on|off')
     .option('--instance <url>', 'Target Commonly instance')
     .action(async (adapterName, opts) => {
       const instanceUrl = resolveInstanceUrl(opts.instance);
@@ -1744,6 +1806,7 @@ Docs:
           podId: opts.pod,
           displayName: opts.display,
           envPath: envAbsPath,
+          wakeOnMessage: Boolean(opts.wakeOnMessage),
           log: (line) => console.warn(`[attach] ${line}`),
         });
 
@@ -1766,6 +1829,9 @@ Docs:
         if (workspace) {
           console.log(`✓ Workspace: ${workspace.path}${workspace.created ? ' (created)' : ''}`);
         }
+        if (opts.wakeOnMessage) {
+          console.log('✓ Wake-on-message: ON (sees every pod message; answers only when addressed or genuinely useful)');
+        }
 
         // Retention plan Phase C: the agent arrives whole. Import failure is
         // a warning, never an attach failure — the attach already succeeded
@@ -2174,6 +2240,38 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
       }
     });
 
+  // ── wake (ADR-018 ambient wake toggle) ───────────────────────────────────
+  agent
+    .command('wake <name> <on|off>')
+    .description('Turn wake-on-message on/off for an attached agent (off = @mentions and heartbeats only)')
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (name, state, opts) => {
+      const enabled = state === 'on';
+      if (!enabled && state !== 'off') {
+        console.error(`Expected "on" or "off", got "${state}"`);
+        process.exit(1);
+      }
+      const record = loadAgentToken(name);
+      if (!record) {
+        console.error(`No token file for '${name}' — is it attached on this machine? (commonly agent list --local)`);
+        process.exit(1);
+      }
+      const instanceUrl = resolveInstanceUrl(opts.instance || record.instanceUrl);
+      const token = getToken(opts.instance || record.instanceUrl);
+      if (!token) { console.error('Not logged in. Run: commonly login'); process.exit(1); }
+      const client = createClient({ instance: instanceUrl, token });
+      try {
+        const result = await setWakeOnMessage({ client, record, enabled });
+        console.log(`✓ Wake-on-message ${result.enabled ? 'ON' : 'OFF'} for ${result.agentName} in pod ${result.podId}`);
+        console.log(result.enabled
+          ? '  The agent now sees every message in the pod; its runtime decides whether to answer (NO_REPLY otherwise). No restart needed.'
+          : '  The agent now wakes only on @mentions, replies to it, and heartbeats. No restart needed.');
+      } catch (err) {
+        console.error(`Failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
   // ── heartbeat ─────────────────────────────────────────────────────────────
   agent
     .command('heartbeat <name>')

package/src/commands/login.js

@@ -7,7 +7,7 @@
 
 import { createInterface } from 'readline';
 import { login as apiLogin } from '../lib/api.js';
-import { saveInstance, LOCAL_URL } from '../lib/config.js';
+import { saveInstance } from '../lib/config.js';
 
 const prompt = (rl, question) => new Promise((resolve) => rl.question(question, resolve));
 
@@ -88,8 +88,8 @@ export const registerWhoami = (program) => {
     .command('whoami')
     .description('Show current auth state')
     .option('--instance <url>', 'Target instance')
-    .action(async (opts) => {
-      const { getActiveInstance, listInstances } = await import('../lib/config.js');
+    .action(async () => {
+      const { listInstances } = await import('../lib/config.js');
       const instances = listInstances();
 
       if (instances.length === 0) {

package/src/lib/adapters/claude.js

@@ -66,6 +66,7 @@ import {
   publicClaudeStateRoot,
   wrapArgvWithSeatbelt,
 } from '../sandbox/seatbelt.js';
+import { buildMemoryPreamble } from '../memory-bridge.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
@@ -78,10 +79,7 @@ const DEFAULT_TIMEOUT_MS = (() => {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 })();
 
-const buildPrompt = (prompt, memoryLongTerm) => {
-  if (!memoryLongTerm) return prompt;
-  return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
-};
+const buildPrompt = buildMemoryPreamble;
 
 const PUBLIC_SANDBOX_MODES = new Set(['workspace', 'read-only']);
 const PUBLIC_DENIED_TOOLS = [
@@ -472,7 +470,13 @@ export default {
   async spawn(prompt, ctx = {}) {
     const isResume = !!ctx.sessionId;
     const sessionId = ctx.sessionId || randomUUID();
-    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm || '');
+    // Passed through UNCOALESCED. `ctx.memoryLongTerm || ''` was here, and
+    // `null || ''` is `''` — which routed the unreadable case straight into
+    // the empty-memory branch and made the whole distinction unreachable from
+    // the only two paths that build a real prompt. buildPrompt handles
+    // undefined and '' as absence itself; it does not need a guard, it needs
+    // the value.
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm);
     const sessionFlag = isResume ? '--resume' : '--session-id';
     // Model pin from the ADR-008 environment spec. Absent it, claude picks its
     // own default — which is how a fleet of ten agents ended up running three

package/src/lib/adapters/codex.js

@@ -56,6 +56,7 @@ import {
   join,
   resolve as pathResolve,
 } from 'path';
+import { buildMemoryPreamble } from '../memory-bridge.js';
 
 // Default timeout for a single codex spawn (exec mode).
 //
@@ -81,10 +82,7 @@ const DEFAULT_TIMEOUT_MS = (() => {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 })();
 
-const buildPrompt = (prompt, memoryLongTerm) => {
-  if (!memoryLongTerm) return prompt;
-  return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
-};
+const buildPrompt = buildMemoryPreamble;
 
 // ── MCP wiring — codex consumes MCP servers via `-c mcp_servers.*` overrides ─
 //
@@ -417,7 +415,13 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
-    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm || '');
+    // Passed through UNCOALESCED. `ctx.memoryLongTerm || ''` was here, and
+    // `null || ''` is `''` — which routed the unreadable case straight into
+    // the empty-memory branch and made the whole distinction unreachable from
+    // the only two paths that build a real prompt. buildPrompt handles
+    // undefined and '' as absence itself; it does not need a guard, it needs
+    // the value.
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm);
 
     // Per-spawn temp dir for --output-last-message. Cleaned up in `finally`
     // so a crash in the middle of the spawn doesn't leak files in $TMPDIR.

package/src/lib/api.js

@@ -43,6 +43,12 @@ export const createClient = ({ instance = null, token = null } = {}) => {
     body: JSON.stringify(body),
   }).then(handleResponse);
 
+  const patch = (path, body = {}) => fetch(`${baseUrl}${path}`, {
+    method: 'PATCH',
+    headers: headers(authToken),
+    body: JSON.stringify(body),
+  }).then(handleResponse);
+
   const del = (path) => fetch(`${baseUrl}${path}`, {
     method: 'DELETE',
     headers: headers(authToken),
@@ -70,7 +76,7 @@ export const createClient = ({ instance = null, token = null } = {}) => {
   };
 
   return {
-    get, post, del, upload, baseUrl,
+    get, post, patch, del, upload, baseUrl,
   };
 };
 

package/src/lib/config.js

@@ -67,10 +67,19 @@ export const resolveInstance = (identifier = null) => {
   const looksLikeUrl = /^https?:\/\//i.test(identifier);
   if (looksLikeUrl) {
     const normalized = normalizeUrl(identifier);
-    const urlEntry = Object.entries(config.instances)
-      .find(([, v]) => normalizeUrl(v.url) === normalized);
-    if (urlEntry) {
-      const [key, value] = urlEntry;
+    const matches = Object.entries(config.instances)
+      .filter(([, v]) => normalizeUrl(v.url) === normalized);
+    if (matches.length > 0) {
+      // Several keys can share one URL (`dev` and `default` both pointing at
+      // api.commonly.me after a re-login under a new key). The first entry in
+      // file order is then whichever was saved FIRST — the stale one — and
+      // every command that resolves by the token file's instanceUrl
+      // (detach, wake) got a 401 from a token the user had already replaced.
+      // Prefer the active instance, then the most recently saved.
+      const active = matches.find(([key]) => key === config.active);
+      const [key, value] = active || matches
+        .slice()
+        .sort(([, a], [, b]) => String(b.savedAt || '').localeCompare(String(a.savedAt || '')))[0];
       return { key, ...value };
     }
     // Unknown URL — still usable for bootstrapping. Preserve the caller's

package/src/lib/enforcement.js

@@ -540,16 +540,35 @@ export const splitForChat = (text, { limit = 400 } = {}) => {
  *   fits in one message            → post as-is
  *   splits into ≤ maxChunks        → post the chunks in order ("two short
  *                                    messages beat one wall")
- *   longer than a split answer     → it is a document, not a message: upload
- *                                    the FULL text as a file and post one
- *                                    message — the reply's own opening plus
- *                                    the file card. Nothing is cut; the file
- *                                    holds everything.
+ *   longer than a split answer     → post the FIRST chunk to the channel and
+ *                                    continue the rest in a thread under it.
+ *   one indivisible oversize unit  → it is a genuine document: upload the FULL
+ *                                    text and post one message — the reply's
+ *                                    own opening plus the file card.
  *
- * If the upload fails (older server, network), fall back to posting every
- * chunk: a message flood is a tone violation, silence or truncation is a
- * correctness violation, and the contract itself ranks content above tone
- * ("NEVER hit that by cutting content").
+ * The thread rung is new (Sam 57691) and it replaces attachment as the answer
+ * for PROSE overflow. Before threads existed, a long analysis had nowhere to
+ * go but a file, and that was the right workaround. It is now the wrong one:
+ * an attachment is un-quotable, un-followable, and an all-or-nothing read,
+ * so overflowing into one buries the tail of a reply in a surface nobody can
+ * respond to. A thread keeps every word addressable and scopes the read.
+ *
+ * This is also the layer the rule has to live at. The pod-context cue already
+ * tells agents "prose overflow goes in a thread, not an attachment" (#1176),
+ * and the cue could not have been obeyed: the model does not choose the
+ * delivery mode, THIS FUNCTION does, and it only knew how to attach. A cue
+ * that promises what the wrapper contradicts teaches the agent it is failing
+ * at something it never controlled.
+ *
+ * Attachment is kept for the case it was always right for — a single atomic
+ * unit over `attachThreshold` (a long fence, an unbreakable run). That is a
+ * document by construction, not prose that outgrew a message.
+ *
+ * If threading fails (older server with no threadRootId support, no id in the
+ * response), fall back to attach, then to posting every chunk: a message
+ * flood is a tone violation, silence or truncation is a correctness
+ * violation, and the contract ranks content above tone ("NEVER hit that by
+ * cutting content").
  */
 export const deliverChatReply = async ({
   client,
@@ -563,6 +582,24 @@ export const deliverChatReply = async ({
 }) => {
   const messagesPath = `/api/agents/runtime/pods/${podId}/messages`;
   const chunks = splitForChat(text, { limit });
+  // The runtime route uses HTTP 200 for a policy refusal: it is a completed
+  // request, but no message was created. Keep that distinction at the client
+  // boundary so every delivery mode shares it rather than treating a resolved
+  // promise as proof of a post.
+  const postMessage = (body) => client.post(messagesPath, body);
+  const refused = (response, messages, attemptedMessages) => ({
+    mode: 'refused',
+    messages,
+    attemptedMessages,
+    refused: true,
+    reason: response.reason || 'message_refused',
+    ...(typeof response.guidance === 'string' && response.guidance
+      ? { guidance: response.guidance }
+      : {}),
+    ...(typeof response.consecutive === 'number'
+      ? { consecutive: response.consecutive }
+      : {}),
+  });
   // An atomic unit (a fenced block, an unbreakable word-run) can exceed the
   // limit by construction — splitForChat keeps it whole rather than breaking
   // its rendering. The tone contract's own rule covers it: over ~800 chars of
@@ -571,15 +608,71 @@ export const deliverChatReply = async ({
   // the gate (found by the fleet's implementation audit, Sharpen msg 53018).
   const hasIndivisibleOversize = chunks.some((c) => c.length > attachThreshold);
   if (chunks.length <= 1 && !hasIndivisibleOversize) {
-    await client.post(messagesPath, { content: chunks[0] ?? text });
+    const response = await postMessage({ content: chunks[0] ?? text });
+    if (response?.refused === true) return refused(response, 0, 1);
     return { mode: 'single', messages: 1 };
   }
   if (chunks.length <= maxChunks && !hasIndivisibleOversize) {
+    let messages = 0;
     for (const chunk of chunks) {
       // eslint-disable-next-line no-await-in-loop
-      await client.post(messagesPath, { content: chunk }); // in order, so the reply reads top-down
+      const response = await postMessage({ content: chunk }); // in order, so the reply reads top-down
+      if (response?.refused === true) return refused(response, messages, chunks.length);
+      messages += 1;
+    }
+    return { mode: 'split', messages };
+  }
+  // PROSE OVERFLOW → THREAD. Only when nothing is indivisibly oversize: a
+  // fence too big to split is a document and belongs in the attach rung below.
+  if (!hasIndivisibleOversize) {
+    // A COUNT, not a flag. The recovery below resumes from here, and a boolean
+    // can only distinguish "nothing posted" from "something posted" — it cannot
+    // say how much. Fail a continuation at chunk 3 with a boolean and chunks 1
+    // and 2 are already in the thread, then get posted again top-level; the
+    // reader sees them twice. Getting this wrong is silent, which is also why
+    // the attach rung below leads with `chunks[0]`: falling through after a
+    // successful headline duplicates the opening line. Two of this suite's
+    // existing tests caught that one, and none caught this one, because both
+    // fail at the root-id step before any continuation has posted.
+    let posted = 0;
+    try {
+      const rootRes = await postMessage({ content: chunks[0] });
+      if (rootRes?.refused === true) return refused(rootRes, 0, chunks.length);
+      posted = 1;
+      // The runtime route answers `res.json(result)` with the created row on
+      // `result.message`. Accept either id field; refuse to guess if neither
+      // is present, because a continuation posted with a missing root would
+      // silently become another top-level message — the exact flood this rung
+      // exists to prevent.
+      const rootId = rootRes?.message?.id ?? rootRes?.message?._id ?? rootRes?.id ?? rootRes?._id;
+      if (!rootId) throw new Error('no message id in post response — cannot root the thread');
+      for (const chunk of chunks.slice(1)) {
+        // eslint-disable-next-line no-await-in-loop
+        const response = await postMessage({ content: chunk, threadRootId: String(rootId) });
+        if (response?.refused === true) return refused(response, posted, chunks.length);
+        posted += 1;
+      }
+      return { mode: 'thread', messages: chunks.length, threadRootId: String(rootId) };
+    } catch (err) {
+      if (posted > 0) {
+        // The opening is already in the room. Post the REMAINDER top-level —
+        // never the whole text again. This is the old flood, minus the
+        // duplicate, and it is still preferable to attaching: content ranks
+        // above tone, and the reader would otherwise see the same paragraph
+        // twice with the rest hidden in a file.
+        log(`thread continuation failed (${err.message}) — posting the remainder top-level`);
+        for (const chunk of chunks.slice(posted)) {
+          // eslint-disable-next-line no-await-in-loop
+          const response = await postMessage({ content: chunk });
+          if (response?.refused === true) return refused(response, posted, chunks.length);
+          posted += 1;
+        }
+        return { mode: 'thread-fallback', messages: chunks.length };
+      }
+      // Nothing reached the room, so the attach rung below is free to lead
+      // with the opening as it always did.
+      log(`thread headline failed (${err.message}) — falling back to attach`);
     }
-    return { mode: 'split', messages: chunks.length };
   }
   try {
     const uploaded = await client.upload(`/api/agents/runtime/pods/${podId}/uploads`, {
@@ -596,14 +689,18 @@ export const deliverChatReply = async ({
     const lead = chunks[0] && chunks[0].length <= limit
       ? chunks[0]
       : '(reply too large for chat — attached in full)';
-    await client.post(messagesPath, { content: `${lead}\n\n${directive}` });
+    const response = await postMessage({ content: `${lead}\n\n${directive}` });
+    if (response?.refused === true) return refused(response, 0, 1);
     return { mode: 'attach', messages: 1 };
   } catch (err) {
     log(`attach fallback failed (${err.message}) — posting ${chunks.length} split messages instead`);
+    let messages = 0;
     for (const chunk of chunks) {
       // eslint-disable-next-line no-await-in-loop
-      await client.post(messagesPath, { content: chunk });
+      const response = await postMessage({ content: chunk });
+      if (response?.refused === true) return refused(response, messages, chunks.length);
+      messages += 1;
     }
-    return { mode: 'split-fallback', messages: chunks.length };
+    return { mode: 'split-fallback', messages };
   }
 };

package/src/lib/environment.js

@@ -18,7 +18,7 @@ import {
   readFile, mkdir, lstat, cp, rm, chmod, readdir, writeFile,
 } from 'fs/promises';
 import { existsSync } from 'fs';
-import { dirname, isAbsolute, join, resolve as pathResolve, basename } from 'path';
+import { isAbsolute, join, resolve as pathResolve, basename } from 'path';
 import { homedir } from 'os';
 
 // ── Schema — keep the allow-list narrow; ADR-008 §invariants #1+#2 ──────────

package/src/lib/memory-bridge.js

@@ -21,20 +21,68 @@
 
 export const SOURCE_RUNTIME = 'local-cli';
 
+/**
+ * The turn preamble, shared by every adapter so the two cannot drift.
+ *
+ * Non-empty memory is prepended verbatim — that path is load-bearing and is
+ * not touched here.
+ *
+ * The EMPTY case used to return the bare prompt, which made two very different
+ * states byte-identical from inside the session: an agent that has never saved
+ * anything, and an agent on a runtime with no memory bridge at all. A seat
+ * cannot adopt a habit whose surface it has no evidence exists, so the empty
+ * case now says so.
+ *
+ * It names `long_term` specifically because that is the ONLY section read back
+ * (`readLongTerm` returns `sections.long_term.content`). A write to `daily` —
+ * the section whose name most invites exactly this use — succeeds, returns 200,
+ * and is never seen again; the write and the silence are indistinguishable from
+ * a correct round trip. Naming the section is the whole point of the cue.
+ */
+export const buildMemoryPreamble = (prompt, memoryLongTerm) => {
+  // `null` is the UNREADABLE signal, and it is deliberately not the same value
+  // as `''`. Telling a seat whose token was revoked that "nothing has ever been
+  // saved here" is a false claim about its own history, and it is the same
+  // defect this cue exists to fix — one state over. When we could not read, say
+  // that, and say nothing about what is stored.
+  if (memoryLongTerm === null) {
+    return `=== Context (your persistent memory) ===\n`
+      + `(unreadable this turn — the memory read failed, so this says NOTHING `
+      + `about what you have saved. Do not treat it as empty and do not re-save `
+      + `state you may already hold.)\n`
+      + `=== Current turn ===\n${prompt}`;
+  }
+  if (memoryLongTerm) {
+    return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
+  }
+  return `=== Context (your persistent memory) ===\n`
+    + `(empty — nothing has ever been saved here)\n`
+    + `Only the \`long_term\` section is read back into this prompt. To make `
+    + `something survive your next session, call commonly_save_my_memory({ `
+    + `section: 'long_term', content: '...' }). A write to any other section `
+    + `succeeds and is never shown to you again.\n`
+    + `=== Current turn ===\n${prompt}`;
+};
+
 export const readLongTerm = async (client, { onError } = {}) => {
   try {
     const body = await client.get('/api/agents/runtime/memory');
     return body?.sections?.long_term?.content || '';
   } catch (err) {
-    // A fresh agent has no memory row yet — treat as empty rather than fail
-    // the spawn. The kernel upserts on first write. For anything OTHER than
-    // a 404 (auth revoked, backend down, network out), surface via onError
-    // so the user sees "something's wrong with memory" instead of a silently
-    // context-less agent.
-    if (err?.status && err.status !== 404) {
-      onError?.(err);
-    }
-    return '';
+    // A 404 is the ONLY error that means what '' means: a fresh agent with no
+    // memory row yet. The kernel upserts on first write, so this is genuine
+    // absence and the empty cue is true.
+    if (err?.status === 404) return '';
+    // Everything else — auth revoked, 500, connection refused — is a failure to
+    // READ, which tells us nothing about what is stored. Returning '' here made
+    // the caller assert emptiness on no evidence.
+    //
+    // `err.status` is undefined for a transport failure, so the old guard
+    // (`err?.status && err.status !== 404`) skipped onError precisely when the
+    // backend was unreachable: the loudest condition was the silent one, and
+    // nothing contradicted the false cue.
+    onError?.(err);
+    return null;
   }
 };