swarmdo 1.27.0 → 1.30.0

package/v3/@swarmdo/cli/.claude/helpers/auto-memory-hook.mjs

@@ -13,7 +13,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -52,13 +52,30 @@ async function gracefulExit(signal) {
 process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });
 process.on('SIGINT', () => { gracefulExit('SIGINT'); });
 
-// Ensure data dir
-if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
-
 // ============================================================================
 // Simple JSON File Backend (implements IMemoryBackend interface)
 // ============================================================================
 
+// Collapse entries that are the SAME memory — identical content signature but
+// distinct ids — keeping the first occurrence. The auto-memory bridge
+// historically re-imported every session with a fresh random id, bloating the
+// store ~22x (#53); this heals already-bloated stores and de-dupes defensively.
+// Keyed by namespace + content hash (or raw content) so genuinely distinct
+// memories are never merged. Pure.
+function dedupeByContentSignature(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const e of entries) {
+    const ns = (e && e.namespace) || 'default';
+    const body = (e && e.metadata && e.metadata.contentHash) || (e && (e.content || e.value)) || '';
+    const sig = ns + '\u0001' + body;
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    out.push(e);
+  }
+  return out;
+}
+
 class JsonFileBackend {
   constructor(filePath) {
     this.filePath = filePath;
@@ -70,7 +87,12 @@ class JsonFileBackend {
       try {
         const data = JSON.parse(readFileSync(this.filePath, 'utf-8'));
         if (Array.isArray(data)) {
-          for (const entry of data) this.entries.set(entry.id, entry);
+          // Collapse content-duplicates left by the pre-#53 import bug (same
+          // memory re-imported each session under a fresh id). Auto-heals an
+          // already-bloated store by rewriting it once when dupes are dropped.
+          const deduped = dedupeByContentSignature(data);
+          for (const entry of deduped) this.entries.set(entry.id, entry);
+          if (deduped.length < data.length) this._persist();
         }
       } catch { /* start fresh */ }
     }
@@ -99,7 +121,11 @@ class JsonFileBackend {
   async query(opts) {
     let results = [...this.entries.values()];
     if (opts?.namespace) results = results.filter(e => e.namespace === opts.namespace);
-    if (opts?.type) results = results.filter(e => e.type === opts.type);
+    // NOTE: opts.type is the QueryType search STRATEGY (semantic|keyword|hybrid|…),
+    // NOT an entry MemoryType. This JSON backend has no vector search, so the
+    // strategy is moot — filtering entries by it excluded everything (a 'hybrid'
+    // query matched no 'semantic' entries), which zeroed out the bridge's
+    // content-hash dedup and let the store bloat ~22x per re-import (#53).
     if (opts?.limit) results = results.slice(0, opts.limit);
     return results;
   }
@@ -367,32 +393,43 @@ async function doStatus() {
 // Main
 // ============================================================================
 
-const command = process.argv[2] || 'status';
-
-// Dynamic import() failures can surface as unhandled rejections on a later
-// microtask even when the awaiting call site already caught them, which would
-// otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
-// reason under SWARMDO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
-// (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
-process.on('unhandledRejection', (reason) => {
-  if (DEBUG) {
-    const detail = reason && reason.message ? reason.message : String(reason);
-    process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
-  }
-});
-
-try {
-  switch (command) {
-    case 'import': await doImport(); break;
-    case 'sync': await doSync(); break;
-    case 'status': await doStatus(); break;
-    default:
-      console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
-      break;
+// Only dispatch CLI commands when this file is executed directly
+// (`node auto-memory-hook.mjs …`), NOT when it is imported by a test —
+// importing must not run a command or exit the process (#53 regression test
+// imports JsonFileBackend + dedupeByContentSignature below).
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  // Ensure data dir (only when actually running a command, not on import)
+  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+  const command = process.argv[2] || 'status';
+
+  // Dynamic import() failures can surface as unhandled rejections on a later
+  // microtask even when the awaiting call site already caught them, which would
+  // otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the
+  // reason under SWARMDO_DEBUG/DEBUG so genuine async bugs aren't silently hidden
+  // (FIX 2 — the previous `() => {}` discarded every rejection process-wide).
+  process.on('unhandledRejection', (reason) => {
+    if (DEBUG) {
+      const detail = reason && reason.message ? reason.message : String(reason);
+      process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);
+    }
+  });
+
+  try {
+    switch (command) {
+      case 'import': await doImport(); break;
+      case 'sync': await doSync(); break;
+      case 'status': await doStatus(); break;
+      default:
+        console.log('Usage: auto-memory-hook.mjs <import|sync|status>');
+        break;
+    }
+  } catch (err) {
+    // Hooks must never crash Claude Code - fail silently
+    try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
   }
-} catch (err) {
-  // Hooks must never crash Claude Code - fail silently
-  try { dim(`Error (non-critical): ${err.message}`); } catch (_) {}
+  // Force clean exit — process.exitCode alone isn't enough if async errors override it
+  process.exit(0);
 }
-// Force clean exit — process.exitCode alone isn't enough if async errors override it
-process.exit(0);
+
+// Exported for unit tests (the run-guard above keeps import side-effect-free).
+export { JsonFileBackend, dedupeByContentSignature };

package/v3/@swarmdo/cli/bin/cli.js

@@ -93,6 +93,20 @@ console.log = (...args) => {
   _origLog.apply(console, args);
 };
 
+// Claude Code plugin hint (code.claude.com/docs/en/plugin-hints): when a
+// session runs swarmdo through Claude Code's Bash tool, emit the one-line
+// marker so Claude Code can offer to install our plugin. Emitted here in the
+// bin shim — NOT in dist/src/index.js — so it also covers the #2256 fast
+// paths below (--version/--help are exactly the probes Claude runs on an
+// unfamiliar CLI). Claude Code strips the line from all output before it
+// reaches the model and only prompts if/when swarmdo-core is listed in the
+// official Anthropic marketplace; until then it is silently dropped.
+if (process.env.CLAUDECODE) {
+  process.stderr.write(
+    '<claude-code-hint v="1" type="plugin" value="swarmdo-core@claude-plugins-official" />\n'
+  );
+}
+
 // #2256 fast path: --version / -V / --help / -h must NOT trigger heavy
 // imports (agentic-flow, swarmvector ONNX, etc.) — those eagerly download a
 // 23 MB ONNX model on cold cache, blocking 60+ s and causing SIGTERM
@@ -116,6 +130,30 @@ console.log = (...args) => {
   // loading. The version short-circuit is the only one safe to inline.
 }
 
+// #45 fast path: `compact-snapshot` is wired to UserPromptSubmit (fires on
+// EVERY prompt) and PreCompact, so it must not pay the full-CLI bootstrap
+// (~0.6s incl. the 23 MB ONNX load). Its own module imports only fs/git/output
+// + the pure engine, so dispatch it directly and exit before any heavy import.
+// A bare `--help` still falls through to the rich help path below.
+{
+  const _argv = process.argv.slice(2);
+  if (_argv[0] === 'compact-snapshot' && !_argv.includes('--help') && !_argv.includes('-h')) {
+    try {
+      const mod = await import('../dist/src/commands/compact-snapshot.js');
+      const cmd = mod.default ?? mod.compactSnapshotCommand;
+      const rest = _argv.slice(1);
+      const args = rest.filter((a) => !a.startsWith('-'));
+      const flags = {};
+      for (const a of rest) if (a.startsWith('--')) flags[a.replace(/^--/, '')] = true;
+      const res = await cmd.action({ cwd: process.cwd(), args, flags, rawArgs: rest });
+      process.exit(res && typeof res.exitCode === 'number' ? res.exitCode : 0);
+    } catch (e) {
+      // Best-effort: a failure here must never block a turn (it runs in hooks).
+      process.exit(0);
+    }
+  }
+}
+
 // Check if we should run in MCP server mode
 // Conditions:
 //   1. stdin is being piped AND no CLI arguments provided (auto-detect)

package/v3/@swarmdo/cli/dist/src/apply/apply.d.ts

@@ -41,6 +41,12 @@ export interface HunkResult {
     at?: number;
     /** how many context lines were trimmed to make it fit */
     fuzzUsed?: number;
+    /**
+     * True when the matched block occurs at MORE THAN ONE position in the file —
+     * the hunk landed at the nearest, but a duplicate/boilerplate block elsewhere
+     * means it may have modified the wrong occurrence. Callers should verify.
+     */
+    ambiguous?: boolean;
 }
 export interface ApplyResult {
     ok: boolean;

package/v3/@swarmdo/cli/dist/src/apply/apply.js

@@ -19,7 +19,10 @@ export function parsePatch(text) {
     let hunk = null;
     const stripPrefix = (p) => p.replace(/^[ab]\//, '').replace(/\t.*$/, '').trim();
     for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
+        // CRLF tolerance (#9): a diff generated on/for CRLF files carries \r on
+        // every line; strip it so hunk content compares EOL-agnostically.
+        const raw = lines[i];
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
         if (line.startsWith('diff --git')) {
             cur = null;
             hunk = null;
@@ -90,6 +93,16 @@ function blockMatchesAt(source, at, block) {
             return false;
     return true;
 }
+/** How many positions in `source` the `block` matches. Pure. */
+function countMatches(source, block) {
+    if (block.length === 0)
+        return 0;
+    let n = 0;
+    for (let i = 0; i + block.length <= source.length; i++)
+        if (blockMatchesAt(source, i, block))
+            n++;
+    return n;
+}
 /**
  * Find where `block` occurs in `source`, preferring the position nearest
  * `expected` (0-based). Returns -1 if not found. Deterministic: on ties the
@@ -117,9 +130,19 @@ function findBlock(source, block, expected) {
 export function applyPatch(source, patch, opts = {}) {
     const fuzz = opts.fuzz ?? 2;
     const trailingNewline = source.endsWith('\n');
+    // CRLF support (#9): match EOL-agnostically, then write inserted lines with
+    // the file's dominant EOL so CRLF sources stay CRLF. `lines` keeps each
+    // line's original bytes (untouched lines round-trip exactly); `matchLines`
+    // is the \r-stripped twin every comparison runs against. The two are spliced
+    // in lockstep so indices stay aligned.
+    const crlfCount = (source.match(/\r\n/g) ?? []).length;
+    const newlineCount = (source.match(/\n/g) ?? []).length;
+    const dominantCrlf = crlfCount > newlineCount - crlfCount;
     const lines = source.split('\n');
     if (trailingNewline)
         lines.pop(); // drop the empty element from a trailing \n
+    const stripCr = (s) => (s.endsWith('\r') ? s.slice(0, -1) : s);
+    const matchLines = lines.map(stripCr);
     let offset = 0;
     const results = [];
     // If a hunk that reaches EOF carries an explicit no-newline marker, it — not
@@ -142,7 +165,7 @@ export function applyPatch(source, patch, opts = {}) {
                 if (lead > leadTrimmable || tail > tailTrimmable)
                     continue;
                 const trimmed = oldBlock.slice(lead, oldBlock.length - tail);
-                const at = findBlock(lines, trimmed, expected + lead);
+                const at = findBlock(matchLines, trimmed, expected + lead);
                 if (at >= 0) {
                     placed = at - lead;
                     usedFuzz = f;
@@ -156,13 +179,18 @@ export function applyPatch(source, patch, opts = {}) {
             results.push({ hunk, applied: false });
             continue;
         }
-        // Splice: remove oldBlock.length lines at `placed`, insert newBlock.
-        // (trimLead/trimTail only affected *matching*, not what we replace.)
-        void trimLead;
-        void trimTail;
-        lines.splice(placed, oldBlock.length, ...newBlock);
+        // A hunk is AMBIGUOUS if the block it matched on occurs elsewhere too — the
+        // nearest-match tiebreak may have picked the wrong duplicate. Check the
+        // matched (trimmed) block against the current lines BEFORE splicing.
+        const matchedBlock = oldBlock.slice(trimLead, oldBlock.length - trimTail);
+        const ambiguous = countMatches(matchLines, matchedBlock) > 1;
+        // Splice: remove oldBlock.length lines at `placed`, insert newBlock —
+        // raw lines get the file's dominant EOL, the match twin stays stripped.
+        const insertRaw = dominantCrlf ? newBlock.map((l) => l + '\r') : newBlock;
+        lines.splice(placed, oldBlock.length, ...insertRaw);
+        matchLines.splice(placed, oldBlock.length, ...newBlock);
         offset += newBlock.length - oldBlock.length;
-        results.push({ hunk, applied: true, at: placed, fuzzUsed: usedFuzz });
+        results.push({ hunk, applied: true, at: placed, fuzzUsed: usedFuzz, ...(ambiguous && { ambiguous: true }) });
         // If this hunk's new content is now the tail of the file, its markers
         // determine whether the file ends with a newline.
         if (placed + newBlock.length === lines.length)
@@ -173,6 +201,11 @@ export function applyPatch(source, patch, opts = {}) {
     const endWithNewline = eofNoEol === undefined ? trailingNewline : !eofNoEol;
     if (endWithNewline)
         result += '\n';
+    // An inserted line that became the no-trailing-newline tail carries the
+    // dominant-EOL \r it was given for joining — a bare CR at EOF is never
+    // meaningful, so drop it.
+    else if (result.endsWith('\r'))
+        result = result.slice(0, -1);
     return { ok: results.every((r) => r.applied), result, hunks: results };
 }
 /**

package/v3/@swarmdo/cli/dist/src/commands/apply.js

@@ -32,6 +32,7 @@ async function run(ctx) {
     const root = ctx.cwd || process.cwd();
     const dryRun = ctx.flags['dry-run'] === true;
     const partial = ctx.flags.partial === true;
+    const strict = ctx.flags.strict === true;
     // The parser may deliver --fuzz as a number or a string; accept both.
     const fuzz = typeof ctx.flags.fuzz === 'number' ? ctx.flags.fuzz
         : typeof ctx.flags.fuzz === 'string' ? parseInt(ctx.flags.fuzz, 10)
@@ -61,6 +62,7 @@ async function run(ctx) {
     }
     let totalApplied = 0;
     let totalRejected = 0;
+    let totalAmbiguous = 0;
     const writes = [];
     for (const fp of patches) {
         const file = targetFile(root, fp);
@@ -85,8 +87,16 @@ async function run(ctx) {
         totalApplied += applied;
         totalRejected += rejected;
         const fuzzy = res.hunks.filter((h) => h.applied && (h.fuzzUsed ?? 0) > 0).length;
+        const ambiguous = res.hunks.filter((h) => h.applied && h.ambiguous).length;
+        totalAmbiguous += ambiguous;
         const tag = rejected === 0 ? output.dim('ok') : output.bold(`${rejected} rejected`);
-        output.writeln(`${rel}  ${applied}/${res.hunks.length} hunks${fuzzy ? output.dim(` (${fuzzy} fuzzy)`) : ''}  ${tag}`);
+        const ambTag = ambiguous ? output.error(` ⚠ ${ambiguous} ambiguous`) : '';
+        output.writeln(`${rel}  ${applied}/${res.hunks.length} hunks${fuzzy ? output.dim(` (${fuzzy} fuzzy)`) : ''}  ${tag}${ambTag}`);
+        if (ambiguous) {
+            for (const h of res.hunks.filter((x) => x.applied && x.ambiguous)) {
+                output.writeln(output.dim(`    ⚠ hunk @ line ${(h.at ?? 0) + 1}: matched a block that also appears elsewhere — verify it landed on the intended one`));
+            }
+        }
         if (rejected === 0 || partial) {
             if (res.result !== source)
                 writes.push({ file, content: res.result });
@@ -97,9 +107,11 @@ async function run(ctx) {
             fs.writeFileSync(w.file, w.content);
     }
     const verb = dryRun ? 'would apply' : 'applied';
-    output.writeln(output.dim(`${verb} ${totalApplied} hunks, ${totalRejected} rejected${dryRun ? ' (dry run)' : ''}`));
-    // Exit 1 if anything was rejected — a CI/agent can branch on it.
-    const code = totalRejected > 0 ? 1 : 0;
+    const ambSummary = totalAmbiguous ? `, ${totalAmbiguous} ambiguous` : '';
+    output.writeln(output.dim(`${verb} ${totalApplied} hunks, ${totalRejected} rejected${ambSummary}${dryRun ? ' (dry run)' : ''}`));
+    // Exit 1 if anything was rejected — a CI/agent can branch on it. With --strict,
+    // an ambiguous match (possibly landed on the wrong duplicate) also fails.
+    const code = totalRejected > 0 || (strict && totalAmbiguous > 0) ? 1 : 0;
     return { success: code === 0, exitCode: code };
 }
 export const applyCommand = {
@@ -109,6 +121,7 @@ export const applyCommand = {
         { name: 'dry-run', description: 'report what would apply/reject without writing', type: 'boolean' },
         { name: 'fuzz', description: 'max context lines to drop when matching a drifted hunk (default 2)', type: 'string' },
         { name: 'partial', description: 'write files even when some of their hunks are rejected', type: 'boolean' },
+        { name: 'strict', description: 'exit 1 if any hunk matched an ambiguous (duplicated) block, even if it applied', type: 'boolean' },
     ],
     examples: [
         { command: 'swarmdo apply changes.patch', description: 'Apply a patch file' },

package/v3/@swarmdo/cli/dist/src/commands/compact-snapshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `swarmdo compact-snapshot` — capture / restore a compaction-survival digest.
+ *
+ *   swarmdo compact-snapshot write   # snapshot working state (call on PreCompact)
+ *   swarmdo compact-snapshot read    # print the digest, then consume it (first
+ *                                    # prompt after compaction re-injects it)
+ *   swarmdo compact-snapshot read --keep   # print without consuming
+ *
+ * The digest (recently edited files, uncommitted changes, branch) lets an agent
+ * re-ground after context compaction instead of re-exploring. The engine is
+ * pure + tested (../compact-snapshot/compact-snapshot.ts); this wrapper does the
+ * fs read (edit ledger), git calls, and one-shot persistence.
+ */
+import type { Command } from '../types.js';
+export declare const compactSnapshotCommand: Command;
+export default compactSnapshotCommand;
+//# sourceMappingURL=compact-snapshot.d.ts.map

package/v3/@swarmdo/cli/dist/src/commands/compact-snapshot.js

@@ -0,0 +1,133 @@
+/**
+ * `swarmdo compact-snapshot` — capture / restore a compaction-survival digest.
+ *
+ *   swarmdo compact-snapshot write   # snapshot working state (call on PreCompact)
+ *   swarmdo compact-snapshot read    # print the digest, then consume it (first
+ *                                    # prompt after compaction re-injects it)
+ *   swarmdo compact-snapshot read --keep   # print without consuming
+ *
+ * The digest (recently edited files, uncommitted changes, branch) lets an agent
+ * re-ground after context compaction instead of re-exploring. The engine is
+ * pure + tested (../compact-snapshot/compact-snapshot.ts); this wrapper does the
+ * fs read (edit ledger), git calls, and one-shot persistence.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { output } from '../output.js';
+import { buildDigest, formatDigest, isDigestEmpty, } from '../compact-snapshot/compact-snapshot.js';
+const DIGEST_FILE = 'compact-digest.json';
+const LEDGER_FILE = 'pending-insights.jsonl';
+function dataDir(root) {
+    return path.join(root, '.swarmdo', 'data');
+}
+/** Best-effort git; returns '' on any failure (not-a-repo, no git). */
+function git(root, args) {
+    try {
+        return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 8 * 1024 * 1024 });
+    }
+    catch {
+        return '';
+    }
+}
+/** Read edit records from the pending-insights ledger. Tolerant of junk lines. */
+function readEdits(root) {
+    const p = path.join(dataDir(root), LEDGER_FILE);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const rec = JSON.parse(line);
+            if (rec && rec.type === 'edit' && typeof rec.file === 'string') {
+                out.push({ file: rec.file, timestamp: typeof rec.timestamp === 'number' ? rec.timestamp : 0 });
+            }
+        }
+        catch { /* skip malformed line */ }
+    }
+    return out;
+}
+function doWrite(root) {
+    // Drop swarmdo's own state dirs — they're not the user's working set and
+    // are usually gitignored anyway; filtering keeps the digest signal clean.
+    const gitStatus = git(root, ['status', '--porcelain'])
+        .split('\n')
+        .filter(Boolean)
+        .filter((l) => !/(^|\s|"|-> )\.(swarmdo|swarm|git)\//.test(l));
+    const digest = buildDigest({
+        now: Date.now(),
+        edits: readEdits(root),
+        gitStatus,
+        branch: git(root, ['rev-parse', '--abbrev-ref', 'HEAD']).trim() || undefined,
+    });
+    if (isDigestEmpty(digest)) {
+        // Nothing worth restoring — remove any stale digest so a later `read` is clean.
+        try {
+            fs.rmSync(path.join(dataDir(root), DIGEST_FILE));
+        }
+        catch { /* none */ }
+        output.writeln('compact-snapshot: no working state to capture');
+        return { success: true, exitCode: 0 };
+    }
+    try {
+        fs.mkdirSync(dataDir(root), { recursive: true });
+        fs.writeFileSync(path.join(dataDir(root), DIGEST_FILE), JSON.stringify(digest, null, 2) + '\n');
+    }
+    catch (e) {
+        output.printError(`compact-snapshot: could not write digest — ${e.message}`);
+        return { success: false, exitCode: 1 };
+    }
+    output.writeln(`compact-snapshot: captured ${digest.recentFiles.length} edited + ${digest.uncommitted.length} uncommitted`);
+    return { success: true, exitCode: 0 };
+}
+function doRead(root, keep) {
+    const file = path.join(dataDir(root), DIGEST_FILE);
+    let digest;
+    try {
+        digest = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { success: true, exitCode: 0 };
+    } // no digest → nothing to inject
+    const text = formatDigest(digest, Date.now());
+    if (text)
+        process.stdout.write(text + '\n');
+    if (!keep) {
+        try {
+            fs.rmSync(file);
+        }
+        catch { /* already gone */ }
+    } // consume-once
+    return { success: true, exitCode: 0 };
+}
+async function run(ctx) {
+    const root = ctx.cwd || process.cwd();
+    const mode = (ctx.args[0] ?? 'read').toLowerCase();
+    if (mode === 'write')
+        return doWrite(root);
+    if (mode === 'read')
+        return doRead(root, ctx.flags.keep === true);
+    output.printError(`compact-snapshot: unknown mode "${mode}" (use write | read)`);
+    return { success: false, exitCode: 1 };
+}
+export const compactSnapshotCommand = {
+    name: 'compact-snapshot',
+    description: 'Capture/restore a working-state digest that survives context compaction — recent edits, uncommitted changes, branch — so an agent re-grounds instead of re-exploring',
+    options: [
+        { name: 'keep', description: 'on read, print the digest without consuming it', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo compact-snapshot write', description: 'Snapshot working state (wire to a PreCompact hook)' },
+        { command: 'swarmdo compact-snapshot read', description: 'Print + consume the digest (wire to the first post-compaction prompt)' },
+    ],
+    action: run,
+};
+export default compactSnapshotCommand;
+//# sourceMappingURL=compact-snapshot.js.map

package/v3/@swarmdo/cli/dist/src/commands/index.js

@@ -22,6 +22,7 @@ const commandLoaders = {
     // Deterministic command-output compression (rtk/headroom demand) — a
     // zero-token stream filter, distinct from caveman `compress` for files.
     compact: () => import('./compact.js'),
+    'compact-snapshot': () => import('./compact-snapshot.js'),
     // Secret detection + redaction on the agent data path (gitleaks/trufflehog
     // demand) — mask API keys/tokens before they reach an LLM/log/memory.
     redact: () => import('./redact.js'),
@@ -286,7 +287,7 @@ export async function getCommandsByCategory() {
     // three slots from 'statusline' onward (completionsCmd received the
     // statusline module, analyzeCmd received completions, …), scrambling the
     // categorized help. Every load now has a named slot.
-    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, testreportCmd,] = await Promise.all([
+    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, testreportCmd, compactSnapshotCmd,] = await Promise.all([
         loadCommand('daemon'), loadCommand('doctor'), loadCommand('embeddings'), loadCommand('neural'),
         loadCommand('performance'), loadCommand('security'), loadCommand('swarmvector'), loadCommand('hive-mind'),
         loadCommand('config'), loadCommand('statusline'), loadCommand('compress'), loadCommand('efficiency'),
@@ -294,7 +295,7 @@ export async function getCommandsByCategory() {
         loadCommand('analyze'), loadCommand('route'), loadCommand('progress'), loadCommand('providers'),
         loadCommand('plugins'), loadCommand('deployment'), loadCommand('claims'), loadCommand('issues'),
         loadCommand('update'), loadCommand('process'), loadCommand('guidance'), loadCommand('appliance'),
-        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'), loadCommand('license'), loadCommand('sbom'), loadCommand('apply'), loadCommand('hotspots'), loadCommand('affected'), loadCommand('cycles'), loadCommand('testreport'),
+        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'), loadCommand('license'), loadCommand('sbom'), loadCommand('apply'), loadCommand('hotspots'), loadCommand('affected'), loadCommand('cycles'), loadCommand('testreport'), loadCommand('compact-snapshot'),
     ]);
     return {
         primary: [
@@ -310,7 +311,7 @@ export async function getCommandsByCategory() {
         utility: [
             configCmd, doctorCmd, daemonCmd, completionsCmd,
             migrateCmd, workflowCmd, demoCmd,
-            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, testreportCmd, efficiencyCmd,
+            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, testreportCmd, compactSnapshotCmd, efficiencyCmd,
         ].filter(Boolean),
         analysis: [
             analyzeCmd, routeCmd, progressCmd, usageCmd, hudCmd, codegraphCmd,

package/v3/@swarmdo/cli/dist/src/commands/pack.d.ts

@@ -13,6 +13,14 @@
  * land in the bundle.
  */
 import type { Command } from '../types.js';
+/**
+ * Decode a file buffer to bundle text, honoring BOMs (#10). UTF-16 LE/BE
+ * files decode to text (previously their NUL bytes tripped the binary
+ * heuristic and the file was silently dropped); a UTF-8 BOM is stripped
+ * instead of leaking into the bundle. Returns null for genuinely-binary
+ * content (NUL byte without a text BOM). Exported for tests.
+ */
+export declare function decodeText(buf: Buffer): string | null;
 export declare const packCommand: Command;
 export default packCommand;
 //# sourceMappingURL=pack.d.ts.map

package/v3/@swarmdo/cli/dist/src/commands/pack.js

@@ -35,6 +35,31 @@ function looksBinary(buf) {
             return true;
     return false;
 }
+/**
+ * Decode a file buffer to bundle text, honoring BOMs (#10). UTF-16 LE/BE
+ * files decode to text (previously their NUL bytes tripped the binary
+ * heuristic and the file was silently dropped); a UTF-8 BOM is stripped
+ * instead of leaking into the bundle. Returns null for genuinely-binary
+ * content (NUL byte without a text BOM). Exported for tests.
+ */
+export function decodeText(buf) {
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+        return buf.subarray(3).toString('utf8');
+    }
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+        const body = buf.subarray(2);
+        if (body.length % 2 !== 0)
+            return null;
+        return body.toString('utf16le');
+    }
+    if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+        const body = Buffer.from(buf.subarray(2)); // copy: swap16 mutates in place
+        if (body.length % 2 !== 0)
+            return null;
+        return body.swap16().toString('utf16le');
+    }
+    return looksBinary(buf) ? null : buf.toString('utf8');
+}
 function walk(o) {
     const files = [];
     const stack = [o.root];
@@ -82,9 +107,10 @@ function walk(o) {
                 catch {
                     continue;
                 }
-                if (looksBinary(buf))
+                const text = decodeText(buf);
+                if (text === null)
                     continue;
-                files.push({ path: rel, content: buf.toString('utf8') });
+                files.push({ path: rel, content: text });
             }
         }
     }