@wacando/agent 2.3.0 → 2.4.1

package/STATUS.md

@@ -1,5 +1,58 @@
 # Handoff — October 15, 2026
 
+## Runtime 2.4.1 — October 17, 2026
+
+File runtime follow-ups (lbframe/wacando-agent#24, review of #23):
+- A ciphertext left without its record (crash between the two writes) is
+  removed by the cleanup once it is more than an hour old.
+- The quarantine keeps at most 20 descriptors per conversation (100 in all),
+  and a full quarantine is cleaned up before a share is refused, so a peer's
+  forged descriptors cannot block real shares.
+- A file descriptor is also detected behind a zero-width space, BOM or word
+  joiner, with fullwidth braces, and nested, inside an array or inside prose
+  together with its key; text that only names the format (also a nested
+  `{"wacandoFile": false}`) stays text. Detection is linear in the body size.
+- `fileStatus` of an incoming file runs one step at a time with
+  `receiveFile`, so it never drops the record of a file being received.
+- The cleanup no longer runs when a read-only tool (`wacando_read`,
+  `wacando_conversations`, ...) connects: it runs before the first file
+  operation of a connection, and at every connection only for
+  `wacando-agent daemon` (SDK `files.sweepOnConnect`). A record that changed
+  while the cleanup consulted the server is kept (closes the STOP race that
+  could unlist a received file), and two processes of one identity can clean
+  up at the same time.
+See [agent tools](docs/AGENT_TOOLS.md#files-10); evidence
+`docs/evidence/issue-24/`.
+
+Embedded Wacando code rebuilt from lbframe/wacando main `87b51a9`, which
+brings lbframe/wacando#200: the embedded `scramClient` now guards its own
+`start()` (`guardStart`), so the runtime's local copy of that guard (added in
+2.4.0) is removed; an error while the stream opens is still an ordinary,
+retried connection failure. `@xmpp/events` 0.14.0 becomes an exact dependency
+([embedded Wacando code](docs/WACANDO_PACKAGES.md)); evidence
+`docs/evidence/release-2.4.1/`.
+
+## Runtime 2.4.0 — October 17, 2026
+
+Verified XMPP server (lbframe/wacando-agent#26): every XMPP connection of
+the runtime now goes through the embedded `scramClient` of lbframe/wacando#186.
+Only SCRAM-SHA-256/SHA-1 over SASL1 is used (no PLAIN, no SASL2/FAST,
+iteration count between 4096 and 100000), and the session is bound only after
+the server's ServerSignature (`v=`) was verified. A forged or missing `v=`, a
+SASL2 offer or a server without SCRAM closes the connection before any
+session: state `refused`, error `XMPP_SERVER_UNVERIFIED`, no retry and no
+reconnection in the process; the daemon exits with code 4 (code 3 for
+`SESSION_REPLACED`), at the first connection as at a reconnection. An error while
+the XMPP stream opens (a WebSocket cut on Node.js 24, a TCP reset) no longer
+kills the process with an unhandled rejection: it is an ordinary, retried
+connection failure. A repository-wide
+test forbids any raw `@xmpp/client` `client()` outside the embedded code. See
+[agent tools](docs/AGENT_TOOLS.md); evidence `docs/evidence/issue-26/`.
+
+Embedded Wacando code rebuilt from lbframe/wacando main `40dd0c3`, which also
+brings lbframe/wacando#166: `downloadFile` refuses more than 10 MiB and fails
+closed on size ([embedded Wacando code](docs/WACANDO_PACKAGES.md)).
+
 ## Runtime 2.3.0 — October 17, 2026
 
 Default origin (fix): the runtime now defaults to the production API

package/bin/wacando-agent.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { pluginVersion } from '../packages/onboarding/version.mjs';
 import { configuredOrigin } from '../packages/onboarding/network.mjs';
 import { SafeError } from '../packages/onboarding/storage.mjs';
-import { SESSION_REPLACED } from '../packages/onboarding/service.mjs';
+import { SESSION_REPLACED, XMPP_SERVER_UNVERIFIED } from '../packages/onboarding/service.mjs';
 
 const root = fileURLToPath(new URL('../', import.meta.url));
 const self = fileURLToPath(import.meta.url);
@@ -70,10 +70,10 @@ export function parseFlags(flags, allowed) {
 class UsageError extends Error {}
 const print = value => console.log(JSON.stringify(value, null, 2));
 
-async function runtime(options, report) {
+async function runtime(options, report, extra = {}) {
   const { AgentRuntime } = await import('../packages/runtime/runtime.mjs');
   const { CredentialStore } = await import('../packages/onboarding/storage.mjs');
-  return new AgentRuntime({ host: options.host ?? 'cli', origin: options.origin, store: new CredentialStore(), ...(report ? { report } : {}) });
+  return new AgentRuntime({ host: options.host ?? 'cli', origin: options.origin, store: new CredentialStore(), ...(report ? { report } : {}), ...extra });
 }
 
 commands.set('status', async flags => {
@@ -174,28 +174,41 @@ commands.set('files', async flags => {
   await withConversations(parseFlags(rest, conversationFlags), c => c.listFiles(id));
 });
 
+/** Daemon exit code of a terminal connection error: 3 replaced, 4 unverified server. */
+function terminalExitCode(error) {
+  if (!(error instanceof SafeError)) return undefined;
+  if (error.message === SESSION_REPLACED) return 3;
+  if (error.message === XMPP_SERVER_UNVERIFIED) return 4;
+  return undefined;
+}
+
 commands.set('daemon', async flags => {
   const options = parseFlags(flags, ['--agent', '--host', '--origin']);
   // Keep the process alive between heartbeats/retries until a stop signal, or
-  // until the server hands this identity to a newer session (terminal).
+  // until the server hands this identity to a newer session or fails SCRAM
+  // verification (both terminal).
   let keepAlive;
-  let replaced;
+  let terminal;
   const stop = new Promise(resolve => {
     keepAlive = setInterval(() => {}, 3600000);
-    replaced = () => resolve('replaced');
+    terminal = reason => resolve(reason);
     process.once('SIGINT', resolve); process.once('SIGTERM', resolve);
   });
   const agent = await runtime(options, event => {
     // Diagnostics carry only local enums and public ids (never content).
     process.stderr.write(`${JSON.stringify({ component: 'wacando-connection', ...event })}\n`);
-    if (event.state === 'replaced') replaced();
-  });
+    if (event.state === 'replaced' || event.state === 'refused') terminal(event.state);
+  }, { files: { sweepOnConnect: true } }); // the daemon cleans up ended file transfers at every connection (#24)
   try {
     try { print(await agent.connect(options.agent)); }
     catch (error) {
       // A retry stays scheduled unless the identity was rejected for good or
       // another process already runs it (identity lock).
-      if (!(error instanceof SafeError) || /revoked|classic OMEMO|No saved identity|Several saved|SESSION_REPLACED/.test(error.message)) throw error;
+      // The terminal exit codes hold whether the first connection or a later
+      // reconnection hits them (a supervisor must not restart into a loop).
+      const exitCode = terminalExitCode(error);
+      if (exitCode) throw Object.assign(error, { exitCode });
+      if (!(error instanceof SafeError) || /revoked|classic OMEMO|No saved identity|Several saved/.test(error.message)) throw error;
       if (/Failed step: local identity/.test(error.message)) throw new SafeError('This identity is already running in another process (identity lock). Stop it first.');
       console.error(error.message);
     }
@@ -207,9 +220,13 @@ commands.set('daemon', async flags => {
         decrypted: entry.text !== null || Boolean(entry.file), ...(entry.file ? { file: { fileId: entry.file.fileId ?? null, state: entry.file.state } } : {}) })));
     } catch (error) { if (!(error instanceof SafeError)) throw error; console.error(error.message); }
     console.error('Daemon running; stop with Ctrl-C or SIGTERM.');
-    if ((await stop) === 'replaced') {
+    const reason = await stop;
+    if (reason === 'replaced') {
       console.error(SESSION_REPLACED);
       process.exitCode = 3;
+    } else if (reason === 'refused') {
+      console.error(XMPP_SERVER_UNVERIFIED);
+      process.exitCode = 4;
     }
   } finally { clearInterval(keepAlive); await agent.close(); }
 });
@@ -283,6 +300,6 @@ if (invoked === self) {
     if (error instanceof UsageError) console.error(usage);
     else if (error instanceof SafeError) console.error(error.message);
     else console.error('Wacando command failed. Check arguments, local state permissions and service availability.');
-    process.exitCode = error instanceof UsageError ? 2 : 1;
+    process.exitCode = error instanceof UsageError ? 2 : (Number.isInteger(error?.exitCode) ? error.exitCode : 1);
   });
 }

package/docs/AGENT_TOOLS.md

@@ -96,6 +96,18 @@ Rules enforced by the runtime (and, independently, by the server):
   identity back. After an ordinary network loss the conversation client moves
   to the new session (one OMEMO provider per identity) and re-joins rooms on
   demand.
+- **Verified XMPP server** (lbframe/wacando-agent#26, lbframe/wacando#186):
+  every XMPP login of the runtime uses the embedded `scramClient`: SCRAM-SHA-256
+  or SCRAM-SHA-1 over SASL1 only (no PLAIN, no SASL2/FAST), iteration count
+  between 4096 and 100000, and the session is bound only after the server's
+  ServerSignature (`v=`) was verified. A forged or missing `v=`, a SCRAM `e=`
+  error, a SASL2 offer or a server without SCRAM closes the connection before
+  any session: state `refused`, error `XMPP_SERVER_UNVERIFIED`, no retry and no
+  reconnection in the process (a further connect is refused). The daemon exits
+  with code 4, whether the first connection or a reconnection is refused (and
+  with code 3 for `SESSION_REPLACED`, likewise). Ordinary failures (wrong or
+  expired grant, network cut, timeout) stay `retrying`. Check the configured
+  service, then restart the runtime.
 - **Message text on the CLI**: pass `-` instead of the text to read it from
   stdin, so it stays out of `ps` and shell history.
 - **Presence**: after connecting, the runtime waits for the server's echo of
@@ -176,16 +188,27 @@ Code: `packages/runtime/files.mjs`.
   The URL in a message never chooses where the runtime connects nor where the
   agent credential goes; the fetch URL is rebuilt from the pin. https only,
   except loopback http for local stacks.
-- **Receive**: a decrypted body that is a file descriptor is never shown as
-  text: any JSON object with a `wacandoFile` key, whatever its whitespace or
-  key order (`fileBodyKind`; a body that opens like one but is not valid
-  JSON counts too). A review descriptor (`wacandoFileReview`) in the room is
+- **Receive**: a decrypted body that is or carries a file descriptor is never
+  shown as text (`fileBodyKind`, lbframe/wacando-agent#21, #24): a JSON object
+  with a `wacandoFile` key at its top level, whatever its whitespace, key order,
+  escaping or values; a body that opens like one but is not valid JSON; the
+  same behind invisible format characters (zero-width space, BOM, word joiner)
+  or written with fullwidth braces; and a descriptor anywhere else (nested in
+  JSON, inside an array, in prose, a code block or a JSON string) when its key
+  is there too (an `aesgcm://…#<88 hex>` URL, or a review `secret`). Text
+  that only names the format without a key (e.g. a nested
+  `{"wacandoFile": false}` setting) stays text. Detection is linear in the
+  body size. A review descriptor (`wacandoFileReview`) in the room is
   `file: { state: 'refused', reason: 'review_descriptor' }`. It is parsed strictly against
   the pin: valid -> `file: { fileId, name, mediaType, size, state:
   'quarantined' }` in the transcript entry (and `wacando_wait`), otherwise
   `file: { state: 'refused', reason: 'invalid_descriptor' }`, nothing stored or
-  fetched. At most 100 descriptors wait in quarantine on one runtime; beyond
-  that a new share is `refused` (`too_many_quarantined`) and never stored. `wacando_receive_file` checks that the server lists the file for
+  fetched. At most 100 descriptors wait in quarantine on one runtime, and at
+  most 20 of one conversation (one peer cannot fill the quarantine for the
+  others). When either limit is reached the runtime first cleans up ended
+  transfers (a peer's forged descriptors, which the server never lists, go
+  then); if it is still full, the new share is `refused`
+  (`too_many_quarantined`) and never stored. `wacando_receive_file` checks that the server lists the file for
   this agent with the same digest, size and type, waits (bounded) while it is
   quarantined (`uploaded`), and only once the recipient owner released it
   downloads (redirects refused, size capped), verifies and decrypts
@@ -202,17 +225,28 @@ Code: `packages/runtime/files.mjs`.
   in a conversation that is not `active` (checked locally before each step and
   by the server). Past `expiresAt` (30 days) the transfer is `expired`.
   Owners keep observing exchanged files in the app until then.
-- **Local cleanup** (lbframe/wacando-agent#21, `FileTransfers.sweep`): at every
-  connection of an identity (and reconnection), before every
-  `wacando_files`/`files` listing, and before refusing a send for a full
-  queue, the runtime deletes the **local ciphertext, keys and quarantined
+- **Local cleanup** (lbframe/wacando-agent#21, #24, `FileTransfers.sweep`):
+  once per connection, before the first file operation (`wacando_send_file`,
+  `wacando_file_status`, `wacando_receive_file`, `wacando_files` and their CLI
+  and SDK forms; never from the read-only `wacando_contacts`,
+  `wacando_conversations`, `wacando_read`, `wacando_wait`); at every
+  connection and reconnection for `wacando-agent daemon` (SDK:
+  `files.sweepOnConnect: true`); before every `wacando_files`/`files` listing;
+  and before refusing a send or a received share for a full queue or
+  quarantine, the runtime deletes the **local ciphertext, keys and quarantined
   descriptors** of every transfer that can never continue: conversation no
   longer `active` (STOP) or unknown to the server, file unknown, different,
   `rejected` or `expired` on the server, or past its expiry by the local clock
   (the server's `expiresAt`, else 30 days after the local request or receipt;
   this one also works offline). A server that cannot be reached removes
   nothing else. Sent records (public metadata, no key) are kept until their
-  expiry. Leftovers of an interrupted write older than an hour are removed.
+  expiry. Leftovers of an interrupted write older than an hour are removed,
+  including a ciphertext whose record was never written (a crash between the
+  two writes: without its record it has no key). A record that changed while
+  the sweep consulted the server is kept (a file received meanwhile stays
+  listed, also if STOP follows), and no transfer step of the same process runs
+  during a removal. Two processes of one identity sweeping at once (a daemon
+  and an MCP server) only ever remove ended transfers.
   The listing reports `cleaned: { outgoing, incoming }` counts when it removed
   something. Nothing is logged.
 - **Received files are kept**: a file written to the quarantine directory is

package/docs/WACANDO_PACKAGES.md

@@ -42,7 +42,28 @@ source repository; a URL is cloned into a temporary directory.
 result is byte-identical to `packages/wacando/` and `provenance.json` (it needs
 access to the private repository, so it is not part of `npm run check`).
 
-Current source (2.2.0, unchanged in 2.3.0): lbframe/wacando main
+Current source (2.4.1): lbframe/wacando main
+`87b51a96aff0a13ca5ad6650c9c841bee72e1612` (#200 merged at `e669157`). It brings lbframe/wacando#200:
+the embedded `scramClient` applies `guardStart`, so an error while the XMPP
+stream opens rejects `start()` without leaving an unhandled rejection behind
+(the runtime's own copy of that guard is removed); `@xmpp/events` is now a
+recorded external of the embedded code and an exact dependency. The entry
+list is unchanged: `guardStart` is applied inside `scramClient`, and the
+runtime does not use `startOrStop` (`connectSession` already stops the
+reconnect loop and the client on any failure, presence echo included).
+
+2.4.0 embedded lbframe/wacando main
+`40dd0c30b3653095f08994f9534fd5110e1d0925`. It brings lbframe/wacando#186:
+`#wacando/xmpp` now also exports `scramClient`, `startScramClient` and
+`ScramAuthError` (SCRAM client verifying the ServerSignature `v=`, SASL2
+refused, iteration count capped at 100000), through which the runtime makes
+every XMPP connection (`packages/runtime/session.mjs`; `@xmpp/client` is now
+also a recorded external of the embedded code); and lbframe/wacando#166:
+`downloadFile` refuses more than 10 MiB and fails closed on size.
+`tests/scram-wiring.test.mjs` forbids any raw `@xmpp/client` `client()`
+outside the embedded code.
+
+2.2.0 and 2.3.0 embedded lbframe/wacando main
 `618922ecaf2213da18949a8b27d343c8767b64c5`, which adds the review copy of
 lbframe/wacando#169 (`fileReviewFor`, `formatFileReview`, `parseFileReview`,
 `decryptFileReview`, `isFileReviewBody` in `#wacando/omemo`). Before it,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacando/agent",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Wacando agent runtime: CLI/daemon, MCP server and Node SDK on official libsignal OMEMO, with thin Codex, Cursor and Claude Code plugins.",
   "license": "UNLICENSED",
   "type": "module",
@@ -53,6 +53,7 @@
   "dependencies": {
     "@signalapp/libsignal-client": "0.102.2",
     "@xmpp/client": "0.14.0",
+    "@xmpp/events": "0.14.0",
     "@xmpp/jid": "0.14.0",
     "@xmpp/xml": "0.14.0",
     "base64-js": "1.5.1",

package/packages/onboarding/service.mjs

@@ -13,6 +13,13 @@ const identifier = value => typeof value === 'string' && /^[a-zA-Z0-9_-]{1,200}$
 const secret = (value, prefix) => typeof value === 'string' && value.startsWith(prefix) && /^[a-zA-Z0-9_.-]{8,512}$/.test(value);
 const lostEnrollment = 'Enrollment result was not safely saved. Check the agent status on the site. If the token was consumed and no durable credential was saved, revoke this identity and create a new one with a different handle. No automatic recovery exists in v1.';
 export const SESSION_REPLACED = 'SESSION_REPLACED: this identity was taken over by a newer session elsewhere (one session per agent). Nothing reconnects automatically; restart this runtime to take it back.';
+/**
+ * lbframe/wacando-agent#26: the server failed SCRAM verification (forged or
+ * missing ServerSignature `v=`, SASL2 offered, no SCRAM mechanism, iteration
+ * count out of bounds...). Terminal: never retried automatically.
+ */
+export const XMPP_SERVER_UNVERIFIED = 'XMPP_SERVER_UNVERIFIED: the XMPP server did not prove it knows this identity\'s credential (SCRAM-SHA-256/SHA-1 with a verified server signature over SASL1 is required). The connection was closed before any session; connection attempts have stopped. Check the configured service, then restart this runtime.';
+export const SCRAM_REFUSED = 'SCRAM_REFUSED';
 const retryConnection = 'Agent credential is saved, but connection was not confirmed. Automatic retry is scheduled while this MCP host stays open. The same enrollment tool can also resume without consuming the temporary token or recreating the agent.';
 
 export class OnboardingService {
@@ -32,6 +39,9 @@ export class OnboardingService {
     // Identities whose session the server replaced (<conflict/>): terminal for
     // this process, so two runtimes never steal the session from each other.
     this.replaced = new Set();
+    // Identities whose XMPP server failed SCRAM verification (#26): terminal
+    // for this process, never retried in a loop against that server.
+    this.refused = new Set();
     this.schedule = schedule; this.cancel = cancel; this.random = random; this.report = report;
     this.onStanza = onStanza;
     this.onSession = onSession;
@@ -128,7 +138,7 @@ export class OnboardingService {
       catch {
         // open() schedules network recovery itself. Lock/storage failures also
         // remain observable and retryable, except after terminal access rejection.
-        if (!this.closed && !this.timers.has(agent.agentId) && !['revoked', 'replaced'].includes(this.states.get(agent.agentId)?.state)) this.retry(agent, 'local operation');
+        if (!this.closed && !this.timers.has(agent.agentId) && !['revoked', 'replaced', 'refused'].includes(this.states.get(agent.agentId)?.state)) this.retry(agent, 'local operation');
       }
       finally { this.recoveries.delete(recovery); }
     }, delay);
@@ -150,10 +160,18 @@ export class OnboardingService {
     this.status(agent, 'replaced', phase);
     await this.disconnect(agent.agentId);
   }
+  /** The XMPP server failed SCRAM verification: stop for good in this process. */
+  async markRefused(agent, phase = 'XMPP connection') {
+    this.refused.add(agent.agentId);
+    this.cancel(this.timers.get(agent.agentId)); this.timers.delete(agent.agentId);
+    if (this.states.get(agent.agentId)?.state !== 'refused') this.status(agent, 'refused', phase);
+    await this.disconnect(agent.agentId);
+  }
   async open(agent) {
     this.cancel(this.timers.get(agent.agentId)); this.timers.delete(agent.agentId);
     let release;
     let phase = 'local identity';
+    if (this.refused.has(agent.agentId)) throw new SafeError(XMPP_SERVER_UNVERIFIED);
     if (this.replaced.has(agent.agentId) || this.sessions.get(agent.agentId)?.session?.isReplaced?.()) {
       await this.markReplaced(agent);
       throw new SafeError(SESSION_REPLACED);
@@ -211,6 +229,12 @@ export class OnboardingService {
         await this.store.write(agent.origin, this.host, 'agent', agent.agentId, { ...agent, revoked: true });
         throw new SafeError('Agent revoked or durable access rejected. Connection attempts have stopped. Check the identity on the site.');
       }
+      if (error?.code === SCRAM_REFUSED) {
+        // Forged/missing ServerSignature or SASL2 offer: the connection is
+        // already closed; no automatic retry against this server.
+        await this.markRefused(agent, phase);
+        throw new SafeError(XMPP_SERVER_UNVERIFIED);
+      }
       const active = this.sessions.get(agent.agentId);
       if (this.replaced.has(agent.agentId) || active?.session?.isReplaced?.()) {
         // Another process took this identity over (newest session wins). Never

package/packages/onboarding/version.mjs

@@ -1,2 +1,2 @@
 // Must match all distributed plugin manifests; checked by the test suite.
-export const pluginVersion = '2.3.0';
+export const pluginVersion = '2.4.1';

package/packages/runtime/conversations.mjs

@@ -104,7 +104,7 @@ export function publicConversation(view, extra = {}) {
 
 /** Messaging for ONE connected identity. Created by AgentRuntime.conversations(). */
 export class ConversationClient {
-  constructor({ runtime, agent, session, files }) {
+  constructor({ runtime, agent, session, files, sweepOnConnect = false }) {
     this.runtime = runtime;
     this.agent = agent;
     this.session = session;
@@ -131,8 +131,11 @@ export class ConversationClient {
     this.lifecyclesLoaded = this.loadLifecycles();
     // lbframe/wacando-agent#10: encrypted files under owner approval.
     this.files = files?.(this) ?? null;
-    // lbframe/wacando-agent#21: clean up ended transfers at every connection.
-    this.filesSwept = this.sweepFiles();
+    // lbframe/wacando-agent#21, #24: clean up ended transfers once per
+    // connection, at the connection only for a daemon (sweepOnConnect), else
+    // before the first file operation: a read-only tool never deletes anything.
+    this.sweepOnConnect = sweepOnConnect;
+    this.filesSwept = this.sweepOnConnect ? this.sweepFiles() : null;
   }
 
   /** Content-free counts of the local file records removed, or null (never throws). */
@@ -191,7 +194,7 @@ export class ConversationClient {
     this.session = session;
     this.recovery = this.attachRecovery(session);
     this.lifecyclesLoaded = this.loadLifecycles();
-    this.filesSwept = this.sweepFiles();
+    this.filesSwept = this.sweepOnConnect ? this.sweepFiles() : null;
     this.tracker = new MucOriginTracker(session.client, { trustedRelayJid: this.policyJid });
     this.rooms.clear();
     for (const resolve of this.submissions.values()) resolve({ state: 'refused', reason: 'connection-lost' });
@@ -343,6 +346,8 @@ export class ConversationClient {
 
   fileTransfers() {
     if (!this.files) throw new SafeError('File transfer is not available on this runtime.');
+    // First file operation of this connection (none is read-only): clean up.
+    this.filesSwept ??= this.sweepFiles();
     return this.files;
   }
   /** Encrypt a local file, ask the owner's approval, then deposit and share it (bounded wait). */