@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{live-checkout.js → worktrees/live-checkout.js}

@@ -129,7 +129,7 @@
  * and a mock sentinel-existence probe via the private `_exists` option
  * (signature `(absPath:string) => boolean`, defaulting to fs.existsSync).
  * Production callers omit both and the helper falls back to
- * `require('./shared').shellSafeGit` and `fs.existsSync` respectively.
+ * `require('../core/shared').shellSafeGit` and `fs.existsSync` respectively.
  *
  * `checkLiveCheckoutDirty` / `checkLiveCheckoutStaleBase` (W-mrcifup2000c218a):
  * ALLOCATION-TIME pre-dispatch counterparts to the dirty / stale-base checks
@@ -151,7 +151,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 // W-mqvejug6000eeb20 — generous stdout ceiling for the read-only git probes in
 // this module (`git status --porcelain`, `rev-parse`, …). Node's execFile
@@ -444,7 +444,7 @@ function _defaultResolveAutoFreshen(localPath) {
 // isolation / in tests that never trigger the write). Best-effort.
 function _defaultWriteInboxNote(slug, content) {
   // eslint-disable-next-line global-require
-  return require('./dispatch').writeInboxAlert(slug, content);
+  return require('../orchestration/dispatch').writeInboxAlert(slug, content);
 }
 
 // Best-effort, side-effect-light resolution of `mainRef` as a restore target
@@ -1574,7 +1574,7 @@ async function checkLiveCheckoutStaleBase(opts = {}) {
  *
  * Dispatch-end counterpart to prepareLiveCheckout. Runs from spawnAgent's
  * onAgentClose (engine.js) on EVERY terminal result AND from the engine-restart
- * orphan/reattach completion path (engine/cli.js), so the operator's working
+ * orphan/reattach completion path (engine/operations/cli.js), so the operator's working
  * tree is switched back to the ref it was on before the live-mode agent ran.
  *
  * Behaviour (locked by human steer steer-bc5861ff95, 2026-06-19):

package/engine/{worktree-pool.js → worktrees/pool.js}

@@ -21,8 +21,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const smallStateStore = require('./small-state-store');
+const shared = require('../core/shared');
+const smallStateStore = require('../persistence/small-state-store');
 
 const { log, ENGINE_DEFAULTS } = shared;
 

package/engine/{worktree-preflight.js → worktrees/preflight.js}

@@ -1,3 +1,4 @@
+// engine/worktrees/preflight.js — disk-capacity gate before worktree allocation.
 const fs = require('fs');
 const path = require('path');
 

package/engine/worktrees/quarantine-refs.js

@@ -0,0 +1,173 @@
+const shared = require('../core/shared');
+
+// W-ms87lj8j018j2572 — the retention window is OWNED by engine/core/shared.js so the
+// ref-prune window and `ENGINE_DEFAULTS.worktreeProtectedQuarantineRetentionMs`
+// (which sweeps the corresponding quarantine DIRECTORIES) cannot drift apart.
+// Re-exported here for existing consumers; never redefine the literal.
+const { QUARANTINE_REF_RETENTION_DAYS, QUARANTINE_REF_RETENTION_MS } = shared;
+const DELETE_CONCURRENCY = 8;
+
+const QUARANTINE_REF_PREFIXES = Object.freeze([
+  'refs/minions/quarantine/',
+  'refs/minions/quarantine-wip/',
+]);
+
+/** True only for refs inside the two Minions-owned quarantine namespaces.
+ *  Branches, tags, and near-miss namespaces must never be pruned. */
+function isQuarantineRef(ref) {
+  return QUARANTINE_REF_PREFIXES.some(prefix => String(ref || '').startsWith(prefix));
+}
+
+/** Canonical creation time encoded as the trailing `/<epoch-ms>` ref segment.
+ *  Returns null for anything that is not a plain positive integer so callers
+ *  can preserve (never speculatively delete) malformed refs. */
+function quarantineRefTimestampMs(ref) {
+  const timestamp = String(ref || '').split('/').pop();
+  if (!/^\d+$/.test(timestamp)) return null;
+  const parsed = Number(timestamp);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function quarantineRefCreatedAtMs(ref, fallbackCreatedAt) {
+  const fromRef = quarantineRefTimestampMs(ref);
+  if (fromRef !== null) return fromRef;
+  const fallback = Date.parse(fallbackCreatedAt || '');
+  return Number.isFinite(fallback) ? fallback : null;
+}
+
+async function _readProjectQuarantineRefs(project) {
+  const output = await shared.shellSafeGit([
+    'for-each-ref',
+    '--format=%(refname)|%(objectname)|%(creatordate:iso-strict)',
+    'refs/minions/quarantine/',
+    'refs/minions/quarantine-wip/',
+  ], { cwd: project.localPath, timeout: 15000 });
+  const seenRefs = new Set();
+  return String(output || '').split(/\r?\n/).filter(Boolean).map(line => {
+    const [ref, sha, fallbackCreatedAt] = line.split('|');
+    if (!ref || seenRefs.has(ref)) return null;
+    seenRefs.add(ref);
+    const createdAtMs = quarantineRefCreatedAtMs(ref, fallbackCreatedAt);
+    return { ref, sha, fallbackCreatedAt, createdAtMs };
+  }).filter(Boolean);
+}
+
+async function listQuarantineRefs(projects) {
+  const candidates = (Array.isArray(projects) ? projects : []).filter(project => project?.localPath);
+  const results = await Promise.allSettled(candidates.map(async project => {
+    const refs = await _readProjectQuarantineRefs(project);
+    return refs.map(({ ref, sha, fallbackCreatedAt, createdAtMs }) => {
+      return {
+        project: project.name || '',
+        ref,
+        sha,
+        createdAt: createdAtMs ? new Date(createdAtMs).toISOString() : (fallbackCreatedAt || ''),
+        kind: ref.startsWith('refs/minions/quarantine-wip/') ? 'wip' : 'commits',
+      };
+    });
+  }));
+  const items = [];
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === 'fulfilled') items.push(...result.value);
+    else items.push({ project: candidates[i].name || '', error: result.reason?.message || String(result.reason) });
+  }
+  return items.sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
+}
+
+async function _mapWithConcurrency(items, limit, worker) {
+  // Canonical implementation lives in engine/core/shared.js — kept as a thin
+  // alias so there is only one promise-pool in the worktree modules.
+  await shared.mapWithConcurrency(items, limit, worker);
+}
+
+/** TTL sweep for Minions quarantine recovery refs.
+ *  Fails safe: only refs in the two Minions-owned namespaces whose ref-name
+ *  timestamp proves they are at least `retentionMs` old are deleted, each with a
+ *  SHA-guarded `update-ref -d`. Malformed refs and per-project/per-ref failures
+ *  are reported, never treated as expiry. Idempotent — a second sweep finds
+ *  nothing left to remove. W-ms87rbe601a66d13 — a non-positive `retentionMs`
+ *  means INDEFINITE retention (the `0` opt-out mirrored from the directory
+ *  sweep) and deletes nothing; it must never read as "everything is expired". */
+async function pruneExpiredQuarantineRefs(projects, {
+  now = Date.now(),
+  retentionMs = QUARANTINE_REF_RETENTION_MS,
+} = {}) {
+  const expiryEnabled = Number.isFinite(Number(retentionMs)) && Number(retentionMs) > 0;
+  const candidates = (Array.isArray(projects) ? projects : []).filter(project => project?.localPath);
+  const results = await Promise.allSettled(candidates.map(async project => {
+    const refs = (await _readProjectQuarantineRefs(project)).filter(item => isQuarantineRef(item.ref));
+    const scanned = refs.length;
+    const malformedRefs = [];
+    const expired = [];
+    let retained = 0;
+
+    for (const item of refs) {
+      const createdAtMs = quarantineRefTimestampMs(item.ref);
+      if (createdAtMs === null) {
+        malformedRefs.push({ project: project.name || '', ref: item.ref });
+        continue;
+      }
+      if (expiryEnabled && now - createdAtMs >= retentionMs) expired.push(item);
+      else retained++;
+    }
+
+    let removed = 0;
+    const failures = [];
+    await _mapWithConcurrency(expired, DELETE_CONCURRENCY, async item => {
+      try {
+        await shared.shellSafeGit(['update-ref', '-d', item.ref, item.sha], {
+          cwd: project.localPath,
+          timeout: 15000,
+        });
+        removed++;
+      } catch (e) {
+        failures.push({
+          project: project.name || '',
+          ref: item.ref,
+          error: e?.message || String(e),
+        });
+      }
+    });
+    return { scanned, removed, retained, malformedRefs, failures };
+  }));
+
+  const summary = {
+    scanned: 0,
+    removed: 0,
+    retained: 0,
+    malformed: 0,
+    failed: 0,
+    malformedRefs: [],
+    errors: [],
+  };
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === 'fulfilled') {
+      summary.scanned += result.value.scanned;
+      summary.removed += result.value.removed;
+      summary.retained += result.value.retained;
+      summary.malformed += result.value.malformedRefs.length;
+      summary.malformedRefs.push(...result.value.malformedRefs);
+      summary.failed += result.value.failures.length;
+      summary.errors.push(...result.value.failures);
+    } else {
+      summary.errors.push({
+        project: candidates[i]?.name || '',
+        error: result.reason?.message || String(result.reason),
+      });
+    }
+  }
+  return summary;
+}
+
+module.exports = {
+  QUARANTINE_REF_RETENTION_DAYS,
+  QUARANTINE_REF_RETENTION_MS,
+  QUARANTINE_REF_PREFIXES,
+  isQuarantineRef,
+  quarantineRefTimestampMs,
+  quarantineRefCreatedAtMs,
+  listQuarantineRefs,
+  pruneExpiredQuarantineRefs,
+};