@wacando/agent 2.4.0 → 2.4.1

package/STATUS.md

@@ -1,5 +1,37 @@
 # 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

package/bin/wacando-agent.mjs

@@ -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 => {
@@ -198,7 +198,7 @@ commands.set('daemon', async flags => {
     // Diagnostics carry only local enums and public ids (never content).
     process.stderr.write(`${JSON.stringify({ component: 'wacando-connection', ...event })}\n`);
     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) {

package/docs/AGENT_TOOLS.md

@@ -188,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
@@ -214,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,17 @@ 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.4.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacando/agent",
-  "version": "2.4.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/version.mjs

@@ -1,2 +1,2 @@
 // Must match all distributed plugin manifests; checked by the test suite.
-export const pluginVersion = '2.4.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). */

package/packages/runtime/files.mjs

@@ -29,8 +29,10 @@ import { protectedDirectory, SafeError, storageError } from '../onboarding/stora
 // directory (0700/0600). The runtime never opens, extracts or executes it.
 // Nothing here logs; errors carry no name, digest, URL token or key.
 //
-// Local retention (lbframe/wacando-agent#21): sweep() runs at every connection
-// and before every listing; it deletes the local ciphertext, keys and
+// Local retention (lbframe/wacando-agent#21, #24): sweep() runs before the
+// first file operation of each connection (at every connection for the
+// daemon, never from a read-only tool), before every listing and before a
+// full queue or quarantine refuses; it deletes the local ciphertext, keys and
 // quarantined descriptors of transfers that can never continue (STOP or any
 // other closed conversation, rejected, expired or unknown on the server, or
 // past their 30-day expiry by the local clock). A RECEIVED file, written to
@@ -40,11 +42,15 @@ import { protectedDirectory, SafeError, storageError } from '../onboarding/stora
 export const FILE_POLL_MS = 2000;
 export const MAX_PENDING_OUTGOING = 10;
 export const MAX_QUARANTINED_INCOMING = 100;
+// One conversation (one peer) can fill only part of the quarantine (lbframe/wacando-agent#24).
+export const MAX_QUARANTINED_PER_CONVERSATION = 20;
 export const FILE_RETENTION_MS = 30 * 24 * 3600 * 1000;
-// Leftovers of an interrupted write (staged ciphertext, .part) older than this are removed by the sweep.
+// Leftovers of an interrupted write (staged ciphertext, .part, a ciphertext
+// without its record) older than this are removed by the sweep.
 const STALE_LEFTOVER_MS = 3600 * 1000;
 const STAGED = /^staged-[0-9a-f-]{36}\.bin$/;
 const PART = /^\.[0-9a-f-]{36}\.part$/;
+const COMMITTED = /^(fil_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.bin$/;
 const FILE_ID = /^fil_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const UPLOAD_PATH = /^\/v1\/uploads\/(fil_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/[A-Za-z0-9_-]{43}$/;
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
@@ -66,6 +72,7 @@ export const fileErrors = {
   download: 'The encrypted file could not be downloaded from the configured Wacando upload origin. Retry later.',
   plainText: 'A message body may not be a file share; use wacando_send_file.',
   tooManyIncoming: `Too many received files are waiting in quarantine on this runtime (at most ${MAX_QUARANTINED_INCOMING}). This file share was refused and never stored; ask your owner to authorize or the sender to resend later.`,
+  tooManyInConversation: `Too many received files of this conversation are waiting in quarantine (at most ${MAX_QUARANTINED_PER_CONVERSATION} per conversation). This file share was refused and never stored; ask your owner to authorize or the sender to resend later.`,
   orphan: 'The file could not be kept on this device after the request: nothing will be deposited. Your owner sees a pending request without a review copy and can refuse it; it expires after 30 days.',
   noOwnerDevice: 'Your owner has no active Wacando app device to review this file: ask your owner to open the Wacando desktop app (signed in) to approve it, then call wacando_file_status. The file stays pending; nothing was deposited.',
   reviewRetry: 'The review copy for your owner could not be deposited yet; call wacando_file_status to retry. The file stays pending.',
@@ -161,23 +168,67 @@ export function ownOwnerId(view, agentId) {
 }
 
 /**
- * Pure: whether a message body is a Wacando file descriptor, whatever its
- * whitespace or key order: 'share' (file share, `wacandoFile`), 'review'
- * (owner review descriptor, `wacandoFileReview`, never meant for a room) or
- * null. Such a body is never shown nor sent as text (it carries a key).
+ * Pure: whether a message body is, or carries, a Wacando file descriptor:
+ * 'share' (file share, `wacandoFile`), 'review' (owner review descriptor,
+ * `wacandoFileReview`, never meant for a room) or null. Such a body is never
+ * shown nor sent as text: it carries a key (lbframe/wacando-agent#21, #24).
+ * Detected whatever the whitespace, key order or JSON escaping, behind
+ * invisible format characters (ZWSP, BOM, word joiner...) or compatibility
+ * forms (fullwidth braces):
+ * - a JSON object with such a key at its top level (strict: whatever its
+ *   values), or a body that opens like one but is not valid JSON;
+ * - a descriptor anywhere else (nested in JSON, in an array, in prose, a code
+ *   block or a JSON string), only when its key material is there too: an
+ *   `aesgcm://...#<88 hex>` URL for a share, a `"secret"` of 88 hex for a
+ *   review. Text that merely names the format (e.g. a nested
+ *   `{"wacandoFile":false}` setting) carries no key and stays text.
+ * Linear in the body size (a hostile body cannot stall the event loop).
  */
 export function fileBodyKind(text) {
   if (typeof text !== 'string') return null;
-  const trimmed = text.trim();
-  if (!trimmed.startsWith('{')) return null;
-  let value;
-  try { value = JSON.parse(trimmed); } catch {
-    // Not JSON: still a descriptor when it opens like one (never shown as text).
-    return /^\{\s*"wacandoFileReview"\s*:/.test(trimmed) ? 'review' : /^\{\s*"wacandoFile"\s*:/.test(trimmed) ? 'share' : null;
-  }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-  if (Object.hasOwn(value, 'wacandoFileReview')) return 'review';
-  return Object.hasOwn(value, 'wacandoFile') ? 'share' : null;
+  // Detection only: the body itself is never rewritten.
+  const plain = text.normalize('NFKC').replace(/\p{Cf}/gu, '').trim();
+  if (plain.startsWith('{') || plain.startsWith('[')) {
+    let value;
+    let parsed = true;
+    try { value = JSON.parse(plain); } catch { parsed = false; }
+    if (parsed) {
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        if (Object.hasOwn(value, 'wacandoFileReview')) return 'review';
+        if (Object.hasOwn(value, 'wacandoFile')) return 'share';
+      }
+    } else if (/^[[\s]*\{\s*"wacandoFileReview"\s*:/.test(plain)) return 'review';
+    else if (/^[[\s]*\{\s*"wacandoFile"\s*:/.test(plain)) return 'share';
+  }
+  let unescaped = plain;
+  for (let i = 0; i < 3; i++) {
+    const next = unescaped.replace(/\\u([0-9a-fA-F]{4})/g, (_, code) => String.fromCharCode(Number.parseInt(code, 16))).replace(/\\(["/\\])/g, '$1');
+    if (next === unescaped) break;
+    unescaped = next;
+  }
+  if (/"wacandoFileReview"\s*:/.test(unescaped) && /"secret"\s*:\s*"[0-9a-fA-F]{88}"/.test(unescaped)) return 'review';
+  if (/"wacandoFile"\s*:/.test(unescaped) && hasAesgcmKey(unescaped)) return 'share';
+  return null;
+}
+
+const URL_END = /[\s"#]/;
+const KEY_HEX = /^[0-9a-fA-F]{88}/;
+/**
+ * Pure: whether the text holds an `aesgcm://<no space, quote or #>#<88 hex>`
+ * URL, in one linear pass (the equivalent regular expression is quadratic on
+ * `aesgcm://` repeated without a `#`, #24 review LOW-2): every later
+ * `aesgcm://` inside the same URL body ends at the same character.
+ */
+function hasAesgcmKey(text) {
+  let from = 0;
+  for (;;) {
+    const start = text.indexOf('aesgcm://', from);
+    if (start < 0) return false;
+    let end = start + 'aesgcm://'.length;
+    while (end < text.length && !URL_END.test(text[end])) end++;
+    if (text[end] === '#' && KEY_HEX.test(text.slice(end + 1, end + 89))) return true;
+    from = end;
+  }
 }
 
 const BARE_JID = /^[^\s/@]+@[^\s/@]+$/;
@@ -269,15 +320,24 @@ export class FileVault {
     try { await rename(join(dir, staged), join(dir, `${FileVault.id(fileId)}.bin`)); } catch { throw storageError(); }
   }
   async dropStaged(staged) { if (STAGED.test(staged ?? '')) await unlink(join(await this.dir('outgoing'), staged)).catch(() => {}); }
-  /** Remove interrupted-write leftovers (staged ciphertext, .part files) older than `before` (ms). Returns the count. */
+  /**
+   * Remove interrupted-write leftovers older than `before` (ms): staged
+   * ciphertext, .part files, and a committed ciphertext whose record was never
+   * written (a crash between the rename and the record, lbframe/wacando-agent#24;
+   * without its record it has no key and can never be used). Returns the count.
+   */
   async dropLeftovers(before) {
     let count = 0;
     for (const kind of ['outgoing', 'incoming']) {
       const dir = await this.dir(kind);
       for (const name of await readdir(dir)) {
-        if (!STAGED.test(name) && !PART.test(name)) continue;
+        const orphan = kind === 'outgoing' ? COMMITTED.exec(name)?.[1] : null;
+        if (!STAGED.test(name) && !PART.test(name) && !orphan) continue;
         const info = await stat(join(dir, name)).catch(() => null);
-        if (info?.isFile() && info.mtimeMs < before && await unlink(join(dir, name)).then(() => true, () => false)) count++;
+        if (!info?.isFile() || info.mtimeMs >= before) continue;
+        // Its record may have been written since the directory was read.
+        if (orphan && await lstat(join(dir, `${orphan}.json`)).then(() => true, error => error.code !== 'ENOENT')) continue;
+        if (await unlink(join(dir, name)).then(() => true, () => false)) count++;
       }
     }
     return count;
@@ -326,6 +386,7 @@ export class FileTransfers {
     this.pollMs = pollMs;
     this.fetch = fetch;
     this.busy = new Map(); // fileId -> in-flight advance (one at a time per file)
+    this.claims = new WeakSet(); // busy entries that are a sweep removal
   }
 
   get pin() { return this.pinSetting ?? (this.pinSetting = uploadPin(this.c.agent.origin)); }
@@ -489,15 +550,24 @@ export class FileTransfers {
   async status(fileId, { timeoutMs = 0 } = {}) {
     FileVault.id(fileId);
     if (await this.vault.read('outgoing', fileId)) return this.once(fileId, () => this.advance(fileId, timeoutMs));
-    const incoming = await this.vault.read('incoming', fileId);
-    if (!incoming) throw new SafeError(fileErrors.unknown);
-    return this.incomingState(incoming, { timeoutMs, fetch: false });
+    // Incoming: one step at a time per file, like receive (a record written by
+    // a receive in flight is never dropped by this step, #24 review LOW-1).
+    return this.once(fileId, async () => {
+      const incoming = await this.vault.read('incoming', fileId);
+      if (!incoming) throw new SafeError(fileErrors.unknown);
+      return this.incomingState(incoming, { timeoutMs, fetch: false });
+    });
   }
 
+  /**
+   * One transfer step at a time per file in this process: a caller joins the
+   * step in flight; a removal by the sweep (a claim) is waited for first.
+   */
   once(fileId, run) {
     const running = this.busy.get(fileId);
-    if (running) return running;
-    const task = run().finally(() => this.busy.delete(fileId));
+    if (running && !this.claims.has(running)) return running;
+    const task = (running ? running.then(() => run(), () => run()) : run())
+      .finally(() => { if (this.busy.get(fileId) === task) this.busy.delete(fileId); });
     this.busy.set(fileId, task);
     return task;
   }
@@ -617,19 +687,36 @@ export class FileTransfers {
       }
       return { ...publicIncoming(known), state: known.path ? 'received' : 'quarantined' };
     }
-    if ((await this.vault.list('incoming')).filter(r => !r.path).length >= MAX_QUARANTINED_INCOMING) {
-      return { state: 'refused', reason: 'too_many_quarantined', note: fileErrors.tooManyIncoming };
+    // Bounded quarantine, and one conversation (one peer) fills at most part of
+    // it. Ended transfers do not count: clean them up before refusing (#24).
+    let full = await this.quarantineFull(conversationId);
+    if (full) {
+      await this.sweep().catch(() => null);
+      full = await this.quarantineFull(conversationId);
     }
+    if (full) return { state: 'refused', reason: 'too_many_quarantined', note: full };
     const record = { fileId, conversationId, messageId, share, ciphertextSha256: share.ciphertextSha256, receivedAt: new Date(this.now()).toISOString() };
     await this.vault.write('incoming', fileId, record);
     return { ...publicIncoming(record), state: 'quarantined', note: `In quarantine until your owner authorizes it; then call wacando_receive_file. ${UNTRUSTED}` };
   }
 
+  /** The refusal note when the quarantine (or this conversation's share of it) is full, else null. */
+  async quarantineFull(conversationId) {
+    const waiting = (await this.vault.list('incoming')).filter(r => !r.path);
+    if (waiting.length >= MAX_QUARANTINED_INCOMING) return fileErrors.tooManyIncoming;
+    if (waiting.filter(r => r.conversationId === conversationId).length >= MAX_QUARANTINED_PER_CONVERSATION) return fileErrors.tooManyInConversation;
+    return null;
+  }
+
   /** Fetch a released incoming file into the quarantine directory (bounded wait for the release). */
   async receive(fileId, { timeoutMs = 0 } = {}) {
-    const record = await this.vault.read('incoming', FileVault.id(fileId));
-    if (!record) throw new SafeError(fileErrors.unknown);
-    return this.once(fileId, () => this.incomingState(record, { timeoutMs, fetch: true }));
+    FileVault.id(fileId);
+    // Read inside the step: a removal by the sweep is never overtaken.
+    return this.once(fileId, async () => {
+      const record = await this.vault.read('incoming', fileId);
+      if (!record) throw new SafeError(fileErrors.unknown);
+      return this.incomingState(record, { timeoutMs, fetch: true });
+    });
   }
 
   async incomingState(record, { timeoutMs, fetch }) {
@@ -640,17 +727,17 @@ export class FileTransfers {
       const view = await this.c.conversation(record.conversationId);
       if (view.state !== 'active') {
         // STOP is terminal: this agent can never fetch it; drop the key.
-        await this.vault.remove('incoming', record.fileId);
+        await this.dropIncoming(record);
         return { file: summary, state: 'refused', reason: 'conversation_closed', note: fileErrors.notActive(view.state) };
       }
       const dto = (await this.serverFiles(record.conversationId)).find(f => f.id === record.fileId);
       if (!dto || dto.recipientAgentId !== this.c.agent.agentId || dto.ciphertextSha256 !== record.share.ciphertextSha256 ||
           dto.sizeBytes !== record.share.ciphertextSize || dto.mediaType !== record.share.mediaType) {
-        await this.vault.remove('incoming', record.fileId);
+        await this.dropIncoming(record);
         return { file: summary, state: 'refused', reason: 'not_approved_file', note: 'The server does not list this file as approved for this agent. It was refused and never fetched.' };
       }
       if (this.expired(dto)) {
-        await this.vault.remove('incoming', record.fileId);
+        await this.dropIncoming(record);
         return { file: summary, state: 'expired', note: fileApiMessages.FILE_EXPIRED };
       }
       if (dto.status === 'released' && fetch) return this.fetchReleased(record, dto, summary);
@@ -663,6 +750,12 @@ export class FileTransfers {
     }
   }
 
+  /** Drop a quarantined descriptor (its key), never the record of a file received meanwhile. */
+  async dropIncoming(record) {
+    if ((await this.vault.read('incoming', record.fileId))?.path) return;
+    await this.vault.remove('incoming', record.fileId);
+  }
+
   async fetchReleased(record, dto, summary) {
     let file;
     try {
@@ -690,16 +783,22 @@ export class FileTransfers {
 
   /**
    * Delete the local secrets of every transfer that can never continue
-   * (lbframe/wacando-agent#21), at connection and before each listing:
+   * (lbframe/wacando-agent#21, #24), before the first file operation of a
+   * connection (at every connection for the daemon), before each listing and
+   * before a full queue or quarantine refuses:
    * - pending/deposited sends (ciphertext + key) and quarantined descriptors
    *   (key): conversation no longer active (STOP is terminal) or unknown to
    *   the server, file unknown, different, rejected or expired on the server,
    *   or past its 30-day expiry by the local clock (even offline);
    * - sent records (public metadata only, no key): past their expiry;
-   * - interrupted-write leftovers older than an hour.
+   * - interrupted-write leftovers older than an hour, including a ciphertext
+   *   whose record was never written.
    * A received file (written to the quarantine directory) and its record are
    * never touched. A server that cannot be reached removes nothing it cannot
-   * decide locally. Transfers in progress in this process are skipped.
+   * decide locally. Transfers in progress in this process are skipped; a
+   * record that changed since it was listed (e.g. a file received meanwhile)
+   * is kept. Another process of the same identity may sweep at the same time:
+   * every step tolerates a file the other one already removed.
    * Returns content-free counts.
    */
   sweep() {
@@ -721,14 +820,31 @@ export class FileTransfers {
         if (this.busy.has(record.fileId)) continue;
         if (!(await this.ended(direction, record, now, server))) continue;
         if (this.busy.has(record.fileId)) continue;
-        await this.vault.remove(direction, record.fileId);
-        counts[direction]++;
+        if (await this.claim(direction, record)) counts[direction]++;
       }
     }
     await this.vault.dropLeftovers(now - STALE_LEFTOVER_MS).catch(() => 0);
     return counts;
   }
 
+  /**
+   * Remove an ended record unless it changed since it was listed. Set as the
+   * file's busy step in the same tick as the caller's last busy check, so no
+   * step of this process (receive, status) interleaves with the removal.
+   */
+  claim(direction, record) {
+    const removal = (async () => {
+      const fresh = await this.vault.read(direction, record.fileId);
+      if (!fresh || JSON.stringify(fresh) !== JSON.stringify(record)) return false;
+      await this.vault.remove(direction, record.fileId);
+      return true;
+    })();
+    const held = removal.finally(() => { if (this.busy.get(record.fileId) === held) this.busy.delete(record.fileId); });
+    this.claims.add(held);
+    this.busy.set(record.fileId, held);
+    return held;
+  }
+
   /** Conversation state and files as the server lists them for this agent; 'gone' when unknown; null when unreachable. */
   async serverState(conversationId) {
     let state;

package/packages/runtime/runtime.mjs

@@ -30,9 +30,12 @@ export function publicIdentity(agent, state) {
  */
 export class AgentRuntime {
   /**
-   * `files`: `{ uploadOrigin, quarantineDir }` (defaults: WACANDO_UPLOAD_ORIGIN
-   * or the API origin; WACANDO_QUARANTINE_DIR or a directory inside the
-   * protected runtime state) plus test hooks (`now`, `sleep`, `pollMs`, `fetch`).
+   * `files`: `{ uploadOrigin, quarantineDir, sweepOnConnect }` (defaults:
+   * WACANDO_UPLOAD_ORIGIN or the API origin; WACANDO_QUARANTINE_DIR or a
+   * directory inside the protected runtime state; `sweepOnConnect: true`
+   * cleans up ended transfers at every connection, as the daemon does,
+   * otherwise before the first file operation of a connection) plus test
+   * hooks (`now`, `sleep`, `pollMs`, `fetch`).
    */
   constructor({ host = 'cli', origin, store = new CredentialStore(), report, request, connect, onStanza, files = {} } = {}) {
     if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(host)) throw new SafeError('Invalid runtime host name.');
@@ -147,7 +150,7 @@ export class AgentRuntime {
     if (client && client.session !== session) this.rebind(agent.agentId, session);
     if (!client) {
       const files = await this.fileTransfersFor(agent);
-      client = new ConversationClient({ runtime: this, agent, session, files });
+      client = new ConversationClient({ runtime: this, agent, session, files, sweepOnConnect: this.fileOptions.sweepOnConnect === true });
       this.clients.set(agent.agentId, client);
       for (const stanza of this.buffered.get(agent.agentId) ?? []) client.handle(stanza);
       this.buffered.delete(agent.agentId);
@@ -220,7 +223,7 @@ export class AgentRuntime {
 
   /** File transfer state of one identity: private directories, pinned upload origin. */
   async fileTransfersFor(agent) {
-    const { uploadOrigin, quarantineDir = process.env.WACANDO_QUARANTINE_DIR, ...hooks } = this.fileOptions;
+    const { uploadOrigin, quarantineDir = process.env.WACANDO_QUARANTINE_DIR, sweepOnConnect: _sweep, ...hooks } = this.fileOptions;
     const pin = uploadPin(agent.origin, uploadOrigin ?? process.env.WACANDO_UPLOAD_ORIGIN);
     const base = join(await this.store.directory(agent.origin, this.host), `files-${digest(agent.agentId)}`);
     const vault = new FileVault(base, quarantineDir ? join(quarantineDir, digest(`${agent.origin}\n${agent.agentId}`).slice(0, 32)) : undefined);

package/packages/runtime/session.mjs

@@ -3,32 +3,6 @@ import { SCRAM_REFUSED, XMPP_SERVER_UNVERIFIED } from '../onboarding/service.mjs
 import { SafeError } from '../onboarding/storage.mjs';
 import { loadDevice } from './device.mjs';
 
-/**
- * @xmpp/connection 0.14.0 `start()` creates its "online" promise (rejected by
- * any entity 'error') BEFORE awaiting `open()`. When an 'error' is emitted
- * while the stream opens (Node.js 24's WebSocket reports a socket cut that
- * way), `open()` rejects, `start()` throws without ever awaiting that promise
- * and its rejection is unhandled: the whole process (daemon, MCP server)
- * dies. Same steps, with the "online" promise always observed.
- */
-function observeOnlinePromise(xmpp) {
-  xmpp.start = async function start() {
-    if (this.status !== 'offline') throw new Error('Connection is not offline');
-    const { service, domain, lang } = this.options;
-    await this.connect(service);
-    const online = new Promise((resolve, reject) => {
-      const settle = () => { this.removeListener('online', onOnline); this.removeListener('error', onError); };
-      const onOnline = value => { settle(); resolve(value); };
-      const onError = error => { settle(); reject(error); };
-      this.on('online', onOnline);
-      this.on('error', onError);
-    });
-    online.catch(() => {});
-    await this.open({ domain, lang });
-    return online;
-  };
-}
-
 const unavailable = () => new SafeError('Secure messaging is unavailable. Retry the saved identity.');
 
 /** SafeError for a ScramAuthError: the fixed message plus its local reason enum (no secret). */
@@ -47,13 +21,18 @@ const serverUnverified = error => Object.assign(new SafeError(XMPP_SERVER_UNVERI
  * SASL1 only, and authentication succeeds only once the server's
  * ServerSignature (`v=`) was verified. A refusal closes the connection,
  * stops @xmpp/client's reconnect and rejects with `code: 'SCRAM_REFUSED'`.
+ * Any failure (start, presence echo or deadline) stops the reconnect loop and
+ * the client before rejecting: the same guarantee as the embedded
+ * `startOrStop`, extended to the presence echo, so that helper is not used.
  */
 export async function connectSession({ jid, password, service, stateBaseDir, onStanza, onReplaced, timeoutMs = 15000 }) {
   const provider = await loadDevice(jid, stateBaseDir);
   const at = jid.indexOf('@');
   const domain = jid.slice(at + 1);
+  // scramClient applies the embedded guardStart (lbframe/wacando#200): an
+  // 'error' while the stream opens rejects start() (an ordinary, retried
+  // failure here), never leaves an unhandled rejection behind.
   const xmpp = scramClient({ service, domain, username: jid.slice(0, at), password });
-  observeOnlinePromise(xmpp);
   // One server-enforced session per agent (lbframe/wacando #15): a newer login
   // ends this one with <conflict/>. Remember it so nothing reconnects in a loop.
   let replaced = false;

package/packages/wacando/chunks/{chunk-FFLYSYV6.mjs → chunk-4Z6TL6JY.mjs}

@@ -1,4 +1,4 @@
-// Embedded from lbframe/wacando@40dd0c30b3653095f08994f9534fd5110e1d0925 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
+// Embedded from lbframe/wacando@87b51a96aff0a13ca5ad6650c9c841bee72e1612 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
 
 // packages/contracts/src/errors.ts
 var DomainError = class extends Error {

package/packages/wacando/chunks/{chunk-FUNUGIGH.mjs → chunk-5Q4655F4.mjs}

@@ -1,11 +1,35 @@
-// Embedded from lbframe/wacando@40dd0c30b3653095f08994f9534fd5110e1d0925 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
+// Embedded from lbframe/wacando@87b51a96aff0a13ca5ad6650c9c841bee72e1612 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
 import {
   XMPP_DOMAIN
-} from "./chunk-FFLYSYV6.mjs";
+} from "./chunk-4Z6TL6JY.mjs";
 
 // packages/xmpp/src/scram.ts
 import { client } from "@xmpp/client";
 import xml from "@xmpp/xml";
+
+// packages/xmpp/src/start.ts
+import { promise, timeout } from "@xmpp/events";
+var guarded = /* @__PURE__ */ new WeakSet();
+function guardStart(entity) {
+  if (guarded.has(entity)) return entity;
+  const target = entity;
+  target.start = async function start() {
+    if (this.status !== "offline") {
+      throw new Error("Connection is not offline");
+    }
+    const { service, domain, lang } = this.options;
+    await this.connect(service);
+    const online = promise(this, "online");
+    online.catch(() => {
+    });
+    await this.open({ domain, lang });
+    return online;
+  };
+  guarded.add(entity);
+  return entity;
+}
+
+// packages/xmpp/src/scram.ts
 var SASL1_NS = "urn:ietf:params:xml:ns:xmpp-sasl";
 var SASL2_NS = "urn:xmpp:sasl:2";
 var SCRAM_MIN_ITERATIONS = 4096;
@@ -337,6 +361,7 @@ function scramClient(options) {
     refused = new ScramAuthError(reason);
     void cut(xmpp, refused);
   });
+  guardStart(xmpp);
   states.set(xmpp, state);
   return xmpp;
 }

package/packages/wacando/chunks/{chunk-F7J3K43U.mjs → chunk-L6IDYNL5.mjs}

@@ -1,7 +1,7 @@
-// Embedded from lbframe/wacando@40dd0c30b3653095f08994f9534fd5110e1d0925 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
+// Embedded from lbframe/wacando@87b51a96aff0a13ca5ad6650c9c841bee72e1612 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
 import {
   DomainError
-} from "./chunk-FFLYSYV6.mjs";
+} from "./chunk-4Z6TL6JY.mjs";
 
 // packages/omemo/src/ns.ts
 var NS_OMEMO = "eu.siacs.conversations.axolotl";

package/packages/wacando/omemo-wire.mjs

@@ -1,4 +1,4 @@
-// Embedded from lbframe/wacando@40dd0c30b3653095f08994f9534fd5110e1d0925 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
+// Embedded from lbframe/wacando@87b51a96aff0a13ca5ad6650c9c841bee72e1612 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
 import {
   BODY_MARKER,
   GCM_IV_BYTES,
@@ -29,8 +29,8 @@ import {
   signerJid,
   signerRole,
   targetJid
-} from "./chunks/chunk-F7J3K43U.mjs";
-import "./chunks/chunk-FFLYSYV6.mjs";
+} from "./chunks/chunk-L6IDYNL5.mjs";
+import "./chunks/chunk-4Z6TL6JY.mjs";
 
 // packages/omemo/src/policy-wire.ts
 import xml from "@xmpp/xml";

package/packages/wacando/omemo.mjs

@@ -1,9 +1,9 @@
-// Embedded from lbframe/wacando@40dd0c30b3653095f08994f9534fd5110e1d0925 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
+// Embedded from lbframe/wacando@87b51a96aff0a13ca5ad6650c9c841bee72e1612 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
 import {
   authenticatedMessageOrigin,
   pepFetchItems,
   pepPublish
-} from "./chunks/chunk-FUNUGIGH.mjs";
+} from "./chunks/chunk-5Q4655F4.mjs";
 import {
   BODY_MARKER,
   GCM_IV_BYTES,
@@ -37,13 +37,13 @@ import {
   signerJid,
   signerRole,
   utf8Encode
-} from "./chunks/chunk-F7J3K43U.mjs";
+} from "./chunks/chunk-L6IDYNL5.mjs";
 import {
   ALLOWED_MEDIA_TYPES,
   MAX_FILE_BYTES,
   MIN_FILE_BYTES,
   looksLikePlaintext
-} from "./chunks/chunk-FFLYSYV6.mjs";
+} from "./chunks/chunk-4Z6TL6JY.mjs";
 
 // packages/omemo/src/libsignal.ts
 import { jid as parseJid2 } from "@xmpp/jid";

package/packages/wacando/xmpp.mjs

@@ -1,4 +1,4 @@
-// Embedded from lbframe/wacando@40dd0c30b3653095f08994f9534fd5110e1d0925 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
+// Embedded from lbframe/wacando@87b51a96aff0a13ca5ad6650c9c841bee72e1612 by scripts/embed-wacando.mjs. Do not edit; see provenance.json.
 import {
   MucJoinError,
   MucOriginTracker,
@@ -13,8 +13,8 @@ import {
   startScramClient,
   unwrapPolicyDelivery,
   waitForStanza
-} from "./chunks/chunk-FUNUGIGH.mjs";
-import "./chunks/chunk-FFLYSYV6.mjs";
+} from "./chunks/chunk-5Q4655F4.mjs";
+import "./chunks/chunk-4Z6TL6JY.mjs";
 
 // packages/xmpp/src/index.ts
 import { default as default2 } from "@xmpp/xml";

package/plugins/wacando/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wacando",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Connect agents with Wacando onboarding and view conversations in the built-in Codex browser.",
   "author": { "name": "Wacando" },
   "skills": "./skills/",

package/plugins/wacando-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wacando-claude",
   "displayName": "Wacando",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Connect agents with Wacando onboarding and view live Claude Code conversations locally.",
   "author": { "name": "Wacando" },
   "keywords": ["agents", "conversation", "local", "observability"],

package/plugins/wacando-cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wacando-cursor",
   "displayName": "Wacando",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Connect agents with Wacando onboarding and view conversations in the built-in Cursor browser.",
   "author": { "name": "Wacando" },
   "keywords": ["agents", "conversation", "local", "observability"],

package/provenance.json

@@ -240,10 +240,10 @@
     "source": {
       "repository": "lbframe/wacando",
       "branch": "main",
-      "commit": "40dd0c30b3653095f08994f9534fd5110e1d0925",
+      "commit": "87b51a96aff0a13ca5ad6650c9c841bee72e1612",
       "trees": {
         "packages/contracts/src": "bf79bedbbb5bd0dc5cbf7d3a027a30f76a3f6904",
-        "packages/xmpp/src": "d8dbc0ea4b286c26bfb3e7b347c3210b27365c9b",
+        "packages/xmpp/src": "06bc1e27b585ce669cf12c10b01b7771d44b91f4",
         "packages/omemo/src": "850b707c9705211a6136486c78c38882699e8b39"
       },
       "packages": [
@@ -274,6 +274,7 @@
     "externals": {
       "@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",
@@ -329,39 +330,40 @@
       "packages/xmpp/src/scram.ts",
       "packages/xmpp/src/single-session.ts",
       "packages/xmpp/src/stanza.ts",
+      "packages/xmpp/src/start.ts",
       "packages/xmpp/src/timeouts.ts",
       "packages/xmpp/src/upload.ts"
     ],
     "files": [
       {
-        "path": "packages/wacando/chunks/chunk-F7J3K43U.mjs",
-        "bytes": 13681,
-        "sha256": "5b2797e10cb4c5ca5c976f2f670c5c41b18b403d28dc9622a07617e71dc33e80"
+        "path": "packages/wacando/chunks/chunk-4Z6TL6JY.mjs",
+        "bytes": 2164,
+        "sha256": "510beba0db3b2bf41032a4bd2abd003662504f03721f69cdca8ca62da7e2491c"
       },
       {
-        "path": "packages/wacando/chunks/chunk-FFLYSYV6.mjs",
-        "bytes": 2164,
-        "sha256": "d84c6ca7a529acc6be0da790124bb73a35fd6c7703beb370fb4e8003eb2ca0e0"
+        "path": "packages/wacando/chunks/chunk-5Q4655F4.mjs",
+        "bytes": 27209,
+        "sha256": "05463ed7058575f8d167c157ac88c8ce44d77f1296235afd6bc96ef72e82501b"
       },
       {
-        "path": "packages/wacando/chunks/chunk-FUNUGIGH.mjs",
-        "bytes": 26532,
-        "sha256": "b237936a6254b8263768aef19c80c427183ed3f607c9af9f33595477bc0bddc9"
+        "path": "packages/wacando/chunks/chunk-L6IDYNL5.mjs",
+        "bytes": 13681,
+        "sha256": "cda8c73a2d729ba969abea7bd5a460f142c4df3b30dc84cfc4ee4092d2c448a4"
       },
       {
         "path": "packages/wacando/omemo-wire.mjs",
         "bytes": 5683,
-        "sha256": "bf44f885b9e3e65da624f9251ec1b2148e8e647a6398c22750003cda3c961e84"
+        "sha256": "3cfcbc94e80e57856db5a9f9ded5f441a333cf1849481273f6f23d62ed4a4414"
       },
       {
         "path": "packages/wacando/omemo.mjs",
         "bytes": 109777,
-        "sha256": "334fe2228f4bdc5c66e9968c707094b6bc76f5a60a8f9fa59dad4a8cb1788c49"
+        "sha256": "b06b6771e7f1796150611ee2da60887f682ccba26262107e1a869732e57fc5f6"
       },
       {
         "path": "packages/wacando/xmpp.mjs",
         "bytes": 2834,
-        "sha256": "1d5536b43cf9d38414c1ccd4c73334a07db60b57c6b584f6a61916010a3453e1"
+        "sha256": "e95455a1bc5d8d5c8773129c45fdd2ab19f2282b16acf446f981ccd2051c220c"
       }
     ]
   }