@memnexus-ai/mx-agent-cli 0.1.289 → 0.1.291

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memnexus-ai/mx-agent-cli",
3
- "version": "0.1.289",
3
+ "version": "0.1.291",
4
4
  "description": "CLI for creating and managing AI agent teams",
5
5
  "type": "module",
6
6
  "bin": {
@@ -135,8 +135,9 @@ const DEST_DEBRIS_DIR = 'worktrees';
135
135
  * generated `.claude/` inside. Scanning INTO that debris made one orphaned
136
136
  * file in the main repo hard-block every session start that needed to
137
137
  * regenerate `.claude/` (customer-portal, 2026-08-01). The skipped subtree is
138
- * still carried over verbatim by cpSync, which does not follow symlinks
139
- * (`dereference: false`), so nothing is followed and nothing is lost.
138
+ * still carried over verbatim — by a rename across the swap (see
139
+ * carryOverUnmanaged / swapStagingIntoPlace), which neither follows nor reads
140
+ * a link inside it, so nothing is followed and nothing is lost.
140
141
  *
141
142
  * SHELTER (SF-13 / SF-14, security review of #4818). The dest skip is keyed on
142
143
  * NAME + POSITION (`<dest>/worktrees`), NOT on a `.git` marker. A marker-keyed
@@ -258,6 +259,25 @@ function pruneExtras(destDir, expected) {
258
259
 
259
260
  /**
260
261
  * Remove stale `.claude.staging-*` / `.claude.prev-*` siblings of `destRoot`.
262
+ *
263
+ * CRASH-DURABLE DEBRIS RECOVERY (the finding that blocked PR #5160's Must Fix 2).
264
+ * `swapStagingIntoPlace` carries `worktrees/` across by rename, which leaves one
265
+ * window — between `staging`→`destRoot` and `prev/worktrees`→`destRoot/worktrees`
266
+ * — where the debris lives only inside `.claude.prev-*`. A crash in that window
267
+ * (SIGKILL, an operator's Ctrl-C on a boot that looks hung, OOM, `docker stop`)
268
+ * runs no `catch` and no `finally`, so recovery cannot live in one: it has to be
269
+ * done by the NEXT run, here, before the sweep deletes anything. Issue #4882
270
+ * established what is inside that tree — abandoned agent worktrees holding real
271
+ * un-shipped work — so an rmSync of it is not "clearing debris".
272
+ *
273
+ * So, per orphan, before removing it:
274
+ * • orphan holds `worktrees/` and the live `.claude/` does NOT — the crash case:
275
+ * rename it back into place (O(1), same filesystem), then sweep the rest.
276
+ * • BOTH hold one — the live tree wins, but the orphan's copy may hold work no
277
+ * one has seen. Never delete it: rename the whole orphan to `.claude.rescue-*`
278
+ * and write a CRITICAL naming the path. `.rescue-` matches neither sweep
279
+ * prefix, so no later run can delete the operator's only copy.
280
+ *
261
281
  * @param destRoot absolute path to the `.claude/` dir about to be generated
262
282
  * @returns names of the siblings that were swept (for observability/tests)
263
283
  */
@@ -276,11 +296,51 @@ export function sweepOrphanSiblings(destRoot) {
276
296
  try { unlinkSync(p); swept.push(ent.name); } catch { /* best-effort */ }
277
297
  continue;
278
298
  }
299
+ if (!recoverOrphanedDebris(p, dest)) continue; // preserved as .rescue-* — do not sweep
279
300
  try { rmSync(p, { recursive: true, force: true }); swept.push(ent.name); } catch { /* best-effort */ }
280
301
  }
281
302
  return swept;
282
303
  }
283
304
 
305
+ /**
306
+ * Rescue a `worktrees/` tree stranded inside orphan sibling `orphan` (see
307
+ * sweepOrphanSiblings). Returns true if `orphan` is safe to delete, false if it
308
+ * was preserved as `.rescue-*` and must be left alone.
309
+ *
310
+ * Fails SAFE in every direction: a symlink at either end, or any rename error,
311
+ * preserves rather than deletes.
312
+ */
313
+ function recoverOrphanedDebris(orphan, dest) {
314
+ const stranded = join(orphan, DEST_DEBRIS_DIR);
315
+ let st;
316
+ try { st = lstatSync(stranded); } catch { return true; } // no debris — ordinary orphan
317
+ if (!st.isDirectory()) return true; // symlink/file — not the debris tree
318
+
319
+ const live = join(dest, DEST_DEBRIS_DIR);
320
+ if (!existsSync(live)) {
321
+ try {
322
+ renameSync(stranded, live);
323
+ process.stderr.write(
324
+ `generate-claude: recovered ${DEST_DEBRIS_DIR}/ stranded in ${orphan} by an ` +
325
+ `interrupted earlier run — restored to ${live}.\n`,
326
+ );
327
+ return true;
328
+ } catch { /* fall through to preserve */ }
329
+ }
330
+ const rescue = `${dest}.rescue-${basename(orphan)}`;
331
+ try {
332
+ if (existsSync(rescue)) return false; // a prior rescue is already parked here — leave both
333
+ renameSync(orphan, rescue);
334
+ process.stderr.write(
335
+ `generate-claude: CRITICAL — ${orphan} holds a ${DEST_DEBRIS_DIR}/ tree that cannot be ` +
336
+ `restored automatically (${live} already exists). Preserved as ${rescue} instead of ` +
337
+ `deleting it — agent worktrees there may hold un-shipped work (#4882). Review and remove ` +
338
+ `it manually.\n`,
339
+ );
340
+ } catch { /* even the rescue rename failed — still never delete */ }
341
+ return false;
342
+ }
343
+
284
344
  // ── GENERATE-TO-STAGING + ATOMIC SWAP (Phase 4 prereq; Red Team finding 1) ────
285
345
  //
286
346
  // Generation writes the WHOLE tree into a staging dir (a sibling of destRoot so
@@ -304,11 +364,14 @@ export function sweepOrphanSiblings(destRoot) {
304
364
  * swap must never move a smuggled link into place. The real committed `.claude/`
305
365
  * is symlink-free, so this is a no-op in the field.
306
366
  *
307
- * EXCEPT inside the `worktrees/` debris dir: see assertNoSymlinksInTree's
308
- * TRAVERSAL SCOPE and SHELTER notes.
309
- * It is copied verbatim without being followed — cpSync defaults to
310
- * `dereference: false`, so a link inside debris is copied AS a link and is never
311
- * read through. It is preserved, not honoured, and never enters the config the
367
+ * EXCEPT the `worktrees/` debris dir: see assertNoSymlinksInTree's TRAVERSAL
368
+ * SCOPE and SHELTER notes. It is NOT copied here — it is agent worktrees, i.e.
369
+ * full checkouts with their own node_modules, routinely tens of gigabytes, and a
370
+ * recursive copy of it made every generation take (effectively) forever and
371
+ * needed 2x its size in free disk. It is instead RENAMED across the swap by
372
+ * swapStagingIntoPlace (staging is a sibling of destRoot, so the rename is
373
+ * same-filesystem and O(1)). Preserved verbatim either way: a rename never
374
+ * follows or reads through a link inside it, and it never enters the config the
312
375
  * generator emits.
313
376
  */
314
377
  function carryOverUnmanaged(destRoot, staging) {
@@ -326,6 +389,7 @@ function carryOverUnmanaged(destRoot, staging) {
326
389
  });
327
390
  for (const ent of listDir(destRoot)) {
328
391
  if (existsSync(join(staging, ent.name))) continue; // generator-managed — its version wins
392
+ if (ent.name === DEST_DEBRIS_DIR) continue; // renamed across the swap, never copied
329
393
  cpSync(join(destRoot, ent.name), join(staging, ent.name), { recursive: true });
330
394
  }
331
395
  }
@@ -334,9 +398,13 @@ function carryOverUnmanaged(destRoot, staging) {
334
398
  * Atomically move `staging` into place at `destRoot`:
335
399
  * 1. rename existing `destRoot` → `destRoot.prev-<ts>` (if it exists)
336
400
  * 2. rename `staging` → `destRoot`
337
- * 3. remove the prev dir on success
401
+ * 3. rename `prev/worktrees` → `destRoot/worktrees` (foreign debris carried
402
+ * across by rename, not by copy — see carryOverUnmanaged)
403
+ * 4. remove the prev dir on success
338
404
  * If step 2 fails after step 1, restore the prev dir back to `destRoot`
339
- * (best-effort, loud). The caller removes `staging` on any throw.
405
+ * (best-effort, loud) — the debris is still inside prev at that point, so the
406
+ * restored `.claude/` is byte-identical to what was there. The caller removes
407
+ * `staging` on any throw.
340
408
  */
341
409
  function swapStagingIntoPlace(destRoot, staging) {
342
410
  let destExists = true;
@@ -370,7 +438,28 @@ function swapStagingIntoPlace(destRoot, staging) {
370
438
  }
371
439
  throw err;
372
440
  }
373
- if (destExists) rmSync(prev, { recursive: true, force: true });
441
+ if (destExists) {
442
+ // Move the foreign debris dir (agent worktrees) into the new tree. Both paths
443
+ // are siblings under the same parent, so this is an O(1) same-filesystem
444
+ // rename regardless of how many gigabytes are inside. Best-effort and loud:
445
+ // debris is not config, so a failure here must not fail a valid generation —
446
+ // but the operator needs to know where the worktrees went.
447
+ const debrisPrev = join(prev, DEST_DEBRIS_DIR);
448
+ const debrisDest = join(destRoot, DEST_DEBRIS_DIR);
449
+ if (existsSync(debrisPrev) && !existsSync(debrisDest)) {
450
+ try {
451
+ renameSync(debrisPrev, debrisDest);
452
+ } catch (err) {
453
+ const d = err instanceof Error ? err.message : String(err);
454
+ process.stderr.write(
455
+ `generate-claude: WARN — could not carry ${DEST_DEBRIS_DIR}/ across the swap ` +
456
+ `(${d}). Recover it manually: mv ${debrisPrev} ${debrisDest}\n`,
457
+ );
458
+ return; // leave prev in place so the debris is recoverable
459
+ }
460
+ }
461
+ rmSync(prev, { recursive: true, force: true });
462
+ }
374
463
  }
375
464
 
376
465
  // ── last-known-good permission-layer cache (Red Team CRITICAL B) ─────────────
@@ -418,6 +507,18 @@ function hashPermissionLayer(settingsBytes, hookEntries) {
418
507
  /**
419
508
  * Read the permission layer (settings.json + hooks/) from a TRUSTED source dir
420
509
  * (an origin-pinned snapshot). Returns null if there is no settings.json.
510
+ *
511
+ * SECOND IMPLEMENTATION WARNING. hook-launcher.sh's `layer_hash()` recomputes
512
+ * this exact digest in bash so a heal can verify the cache before trusting it.
513
+ * The two must agree on which entries are included, their order, the framing
514
+ * bytes, and the file bytes; if they diverge, the launcher rejects every cache
515
+ * forever and silently degrades to the UNVERIFIED working tree. The specific
516
+ * trap: readdirSync RETURNS dot-prefixed names and a bash glob does not match
517
+ * them, so one `.gitkeep` here used to break the launcher fleet-wide. Both
518
+ * sides now include dotfiles (launcher: `shopt -s dotglob`), and
519
+ * agent-config/hooks/hook-launcher.test.sh case 13 seeds a cache containing a
520
+ * dotfile through refreshPermissionCache below and asserts the launcher still
521
+ * trusts it. Change either implementation, run that test.
421
522
  */
422
523
  function readPermissionLayer(srcDir) {
423
524
  const settingsPath = join(srcDir, 'settings.json');