@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{watch-actions.js → watches/actions.js}

@@ -1,5 +1,5 @@
 /**
- * engine/watch-actions.js — Follow-up action registry for watches.
+ * engine/watches/actions.js — Follow-up action registry for watches.
  *
  * When a watch fires, the engine first writes the inbox alert (the existing
  * `notify` field) and then — if the watch carries a structured `action` —
@@ -11,7 +11,7 @@
  * Handlers MUST swallow their own errors and return `{ ok: false, summary }`
  * rather than throwing — this keeps a single bad action from poisoning the
  * watches tick (other watches should still fire). The caller in
- * engine/watches.js wraps the invocation in try/catch as a backstop.
+ * engine/watches/index.js wraps the invocation in try/catch as a backstop.
  *
  * Templating: action params support {{var}} substitution from `ctx`. Strings
  * and one level of nested string fields are templated recursively. Built-in
@@ -29,7 +29,7 @@ const https = require('https');
 const crypto = require('crypto');
 const { URL } = require('url');
 
-const shared = require('./shared');
+const shared = require('../core/shared');
 const {
   WATCH_ACTION_TYPE, WI_STATUS, WORK_TYPE, DONE_STATUSES, PLAN_STATUS,
   log, ts, uid, mutateWorkItems,
@@ -53,7 +53,7 @@ const WATCH_DEDUP_ACTIVE_STATUSES = new Set([
 // must NOT include Date.now()/uid()/triggerCount so the same logical work
 // produces the same key across ticks and engine restarts.
 //
-// Stored on the dispatched WI under `meta._watchDedupKey`; engine/watch-actions.js
+// Stored on the dispatched WI under `meta._watchDedupKey`; this module
 // scans existing pending+active WIs and skips the push if a match is found.
 function computeWatchDedupKey(watch, dispatchedItemShape) {
   const stable = {
@@ -77,7 +77,7 @@ function computeWatchDedupKey(watch, dispatchedItemShape) {
 // `false` on parse/eval errors (with a `[safe-expr]` warn). That contract
 // is what keeps the "invalid expression skips + warns" acceptance criterion
 // a one-liner here — we trust safe-expr to do the logging.
-const safeExpr = require('./safe-expr');
+const safeExpr = require('../core/safe-expr');
 
 // ── Action registry ──────────────────────────────────────────────────────────
 
@@ -362,7 +362,7 @@ async function runWatchActionChain(watch, ctx) {
 //
 // P-w11a4c9e — Phase 6.1: NOTIFY is now the single registered code path for
 // inbox notifications. The legacy `watch.notify === 'inbox'` branch in
-// engine/watches.js no longer writes to the inbox itself — it instead
+// engine/watches/index.js no longer writes to the inbox itself — it instead
 // synthesizes an implicit `{type:'notify'}` step prepended to the action
 // chain. To keep the legacy slug shape `watch-<id>-<triggerCount>` (so
 // existing dedup / readers see no change), this handler defaults to that
@@ -720,7 +720,7 @@ registerActionType(WATCH_ACTION_TYPE.TRIGGER_PIPELINE, {
     const pipelineId = String(p.pipelineId || ctx.pipelineId || '').trim();
     if (!pipelineId) return { ok: false, summary: 'trigger-pipeline: pipelineId is required' };
     let pipelineMod;
-    try { pipelineMod = require('./pipeline'); }
+    try { pipelineMod = require('../orchestration/pipeline'); }
     catch (err) { return { ok: false, summary: `trigger-pipeline: pipeline module unavailable (${err.message})` }; }
     let pipeline;
     try { pipeline = pipelineMod.getPipeline(pipelineId); }
@@ -749,7 +749,7 @@ registerActionType(WATCH_ACTION_TYPE.ARCHIVE_PLAN, {
     const p = ctx.params || {};
     const planFile = String(p.planFile || ctx.planFile || '').trim();
     if (!planFile) return { ok: false, summary: 'archive-plan: planFile is required' };
-    const store = require('./prd-store');
+    const store = require('../planning/prd-store');
     if (!store.readPrd(planFile)) return { ok: false, summary: `archive-plan: ${planFile} not found` };
     let updated = false;
     store.mutatePrd(planFile, (data) => {
@@ -776,7 +776,7 @@ registerActionType(WATCH_ACTION_TYPE.RESUME_PLAN, {
     const p = ctx.params || {};
     const planFile = String(p.planFile || ctx.planFile || '').trim();
     if (!planFile) return { ok: false, summary: 'resume-plan: planFile is required' };
-    const store = require('./prd-store');
+    const store = require('../planning/prd-store');
     if (!store.readPrd(planFile)) return { ok: false, summary: `resume-plan: ${planFile} not found` };
     let updated = false;
     store.mutatePrd(planFile, (data) => {
@@ -844,7 +844,7 @@ function _ccTriageReadFileTail(filePath, maxBytes) {
 function _ccTriageLookupLatestDispatch(workItemId) {
   if (!workItemId) return null;
   try {
-    const queries = require('./queries');
+    const queries = require('../core/queries');
     const dispatch = queries.getDispatch() || {};
     let latest = null;
     for (const listName of ['completed', 'active', 'pending']) {
@@ -862,7 +862,7 @@ function _ccTriageLookupLatestDispatch(workItemId) {
 }
 
 function _ccTriageBuildArtifactSection(watch, ctx, kinds) {
-  const fence = require('./untrusted-fence');
+  const fence = require('../core/untrusted-fence');
   const attachments = [];
   const requested = Array.isArray(kinds) && kinds.length > 0
     ? kinds.map(k => String(k || '').trim().toLowerCase()).filter(k => CC_TRIAGE_ALLOWED_ARTIFACTS.has(k))
@@ -879,7 +879,7 @@ function _ccTriageBuildArtifactSection(watch, ctx, kinds) {
     dispatchEntry = _ccTriageLookupLatestDispatch(workItemId);
     if (dispatchEntry?.id && requested.includes('completion-report')) {
       try {
-        const queries = require('./queries');
+        const queries = require('../core/queries');
         completionReport = queries.getDispatchCompletionReport(dispatchEntry.id);
       } catch { completionReport = null; }
     }
@@ -936,7 +936,7 @@ registerActionType(WATCH_ACTION_TYPE.CC_TRIAGE, {
     { key: 'timeoutMs', required: false, description: `Engine-side HTTP timeout in ms. Default ${CC_TRIAGE_DEFAULT_TIMEOUT_MS} (10 min), capped at ${CC_TRIAGE_MAX_TIMEOUT_MS} (1 h).` },
   ],
   handler: async (watch, ctx) => {
-    const fence = require('./untrusted-fence');
+    const fence = require('../core/untrusted-fence');
     const p = ctx.params || {};
     const promptRaw = String(p.prompt || '').trim();
     if (!promptRaw) return { ok: false, summary: 'cc-triage: prompt is required' };

package/engine/{watches.js → watches/index.js}

@@ -1,6 +1,6 @@
 /**
- * engine/watches.js -- Persistent watch jobs that survive engine restarts.
- * Zero dependencies -- uses only Node.js built-ins + engine/shared.js.
+ * engine/watches/index.js -- Persistent watch jobs that survive engine restarts.
+ * Zero dependencies -- uses only Node.js built-ins + engine/core/shared.js.
  *
  * Watches monitor targets (PRs, work items, meetings, plans, schedules,
  * pipelines, dispatches, agents, ...) for conditions (merged, build-fail,
@@ -29,18 +29,19 @@
  * Built-in types: pr, work-item, meeting, plan, schedule, pipeline, dispatch,
  * agent. Additional types can be added at runtime via registerTargetType().
  *
- * Canonical plugin example: `watches.d/http.js` (W-mp7i22mu00191b07) — a
+ * Canonical plugin example: `watch-plugins/http.js` (W-mp7i22mu00191b07) — a
  * generic HTTP poller that demonstrates the full plugin contract including
  * `contextVars` (exposing `{{httpStatus}}`, `{{extracted}}`, `{{prevExtracted}}`,
  * etc. to action templates) and a background-fetch cache (because the engine
  * tick path is synchronous; plugins that need async I/O maintain their own
  * cache and return cached entities from the synchronous fetchEntity).
  *
- * ── Plugin folder (`watches.d/`) — W-mp7hg58e000b5212 ────────────────────────
+ * ── Plugin folder (`watch-plugins/`) ─────────────────────────────────────────
  *
- * At engine boot, every `*.js` file in `<MINIONS_DIR>/watches.d/` is loaded
+ * At engine boot, every `*.js` file in `<MINIONS_DIR>/watch-plugins/` is loaded
  * and its exports are passed to registerTargetType(). This lets users add
- * new watch target types without editing engine source.
+ * new watch target types without editing engine source. Plugins cannot replace
+ * built-in or previously registered target types.
  *
  * Each plugin file exports either:
  *
@@ -51,7 +52,7 @@
  *
  * or an array of those objects for multi-target plugins.
  *
- * Resolution: `path.join(MINIONS_DIR, 'watches.d')` so it works in both dev
+ * Resolution: `path.join(MINIONS_DIR, 'watch-plugins')` so it works in both dev
  * (D:/squad) and installed (~/.minions) layouts. A missing folder is a silent
  * no-op (not an error). Each file is required inside its own try/catch — one
  * bad plugin must not break boot or block other plugins. Successful loads
@@ -66,11 +67,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { mutateWatches, ts, uid, log, writeToInbox,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS } = shared;
-const watchActions = require('./watch-actions');
-const apiValidation = require('./api-validation');
+const watchActions = require('./actions');
+const apiValidation = require('../api/api-validation');
 
 // Default check interval: 5 minutes (300000ms). Engine tick runs every 10s
 // (W-mpxpckey000laa4f), so watches are checked every N ticks where
@@ -483,7 +484,7 @@ function validateWatchId(value) {
  * @returns {Array<object>}
  */
 function getWatches() {
-  return require('./watches-store').readWatches();
+  return require('./store').readWatches();
 }
 
 /**
@@ -507,7 +508,7 @@ function createWatch(input, config) {
     notify: validated.notify,
     stopAfter: validated.stopAfter,   // 0 = run forever; N = expire after N triggers
     onNotMet: validated.onNotMet,     // null | 'notify' — action per poll when condition not met
-    action: validated.action,         // optional follow-up action — see engine/watch-actions.js
+    action: validated.action,         // optional follow-up action — see engine/watches/actions.js
     // P-w10b6e2d — Phase 5: optional requires[] — when present every entry
     // must also evaluate truthy for the watch to fire. See evaluateWatch.
     requires: validated.requires,
@@ -1118,7 +1119,7 @@ registerTargetType(WATCH_TARGET_TYPE.PR, {
         return { triggered: changed, message: changed ? `PR ${target} head commit changed: ${prev} → ${cur}` : '' };
       }
       case WATCH_CONDITION.MERGEABLE_FLIPPED: {
-        // engine/github.js:902-923 documents that mergeable=null means
+        // engine/providers/github.js:902-923 documents that mergeable=null means
         // "GitHub still computing" — NOT a positive signal. Only fire on
         // transitions between defined boolean values (true↔false). Any
         // transition involving null or undefined is ignored.
@@ -1130,7 +1131,7 @@ registerTargetType(WATCH_TARGET_TYPE.PR, {
       }
       case WATCH_CONDITION.READY_FOR_MERGE: {
         // Compound predicate — fires when ALL gating signals line up.
-        // Registered as an absolute condition (engine/shared.js
+        // Registered as an absolute condition (engine/core/shared.js
         // WATCH_ABSOLUTE_CONDITIONS) so it auto-expires on first trigger
         // when stopAfter=0. Treat isDraft !== true (catches null/undefined
         // legacy PRs that don't expose the field).
@@ -1431,7 +1432,7 @@ registerTargetType(WATCH_TARGET_TYPE.SCHEDULE, {
   validateTarget: _validateStringTarget,
   fetchEntity: _findSchedule,
   // P-w2c8d1e7 — Phase 1.2: surface next_run as null. Cron parsing in
-  // engine/scheduler.js exposes parseCronExpr/.matches() but not a
+  // engine/orchestration/scheduler.js exposes parseCronExpr/.matches() but not a
   // next-fire calculator, so the snapshot field is reserved (always null
   // today) for forward-compat with future predicates that gain a helper.
   captureState: (s) => ({
@@ -1490,7 +1491,7 @@ function _completedStageCount(run) {
 }
 // P-w2c8d1e7 — Phase 1.2: report the id of the first non-terminal stage
 // in run.stages iteration order. run.stages is built from pipeline.stages
-// in declaration order (engine/pipeline.js startRun ~line 84) so the first
+// in declaration order (engine/orchestration/pipeline.js startRun ~line 84) so the first
 // non-terminal entry is the currently-executing or next-pending stage.
 const _PIPELINE_TERMINAL = new Set([shared.PIPELINE_STATUS.COMPLETED, shared.PIPELINE_STATUS.FAILED, shared.PIPELINE_STATUS.STOPPED]);
 function _currentPipelineStageId(run) {
@@ -1688,22 +1689,24 @@ registerTargetType(WATCH_TARGET_TYPE.AGENT, {
   },
 });
 
-// ── Plugin folder discovery (W-mp7hg58e000b5212) ─────────────────────────────
-// Auto-load `<MINIONS_DIR>/watches.d/*.js` at module load time, AFTER the 8
-// built-in registerTargetType() calls so plugins can override built-ins by
-// re-using their key (last-write-wins). Per the README block at the top of
-// this file: missing folder is silent, per-file try/catch isolates failures,
-// and INFO/WARN logs trace what loaded.
-function _loadPluginTargetTypes() {
-  const dir = path.join(shared.MINIONS_DIR, 'watches.d');
+// ── Plugin folder discovery ───────────────────────────────────────────────────
+// Auto-load `<MINIONS_DIR>/watch-plugins/*.js` at module load time, AFTER the 8
+// built-in registerTargetType() calls. Duplicate target names are rejected so
+// a plugin cannot silently replace core behavior. Missing folder is silent;
+// per-file try/catch isolates failures and INFO/WARN logs trace what loaded.
+function _loadPluginDirectory(directoryName, { legacy = false } = {}) {
+  const dir = path.join(shared.MINIONS_DIR, directoryName);
   let entries;
   try {
     entries = fs.readdirSync(dir);
   } catch (err) {
     if (err && err.code === 'ENOENT') return; // silent no-op
-    log('warn', `watches.d/ readdir failed: ${err.message}`);
+    log('warn', `${directoryName}/ readdir failed: ${err.message}`);
     return;
   }
+  if (legacy && entries.some(name => name.endsWith('.js'))) {
+    log('warn', 'Legacy watches.d/ plugins are still loaded for compatibility; move them to watch-plugins/');
+  }
   for (const fname of entries.sort()) {
     if (!fname.endsWith('.js')) continue;
     const fp = path.join(dir, fname);
@@ -1714,21 +1717,29 @@ function _loadPluginTargetTypes() {
       const list = Array.isArray(mod) ? mod : [mod];
       for (const entry of list) {
         if (!entry || !entry.name || !entry.spec) {
-          log('warn', `watches.d/${fname}: export missing { name, spec } — skipping entry`);
+          log('warn', `${directoryName}/${fname}: export missing { name, spec } — skipping entry`);
+          continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(TARGET_TYPES, entry.name)) {
+          log('warn', `${directoryName}/${fname}: target type '${entry.name}' already registered — skipping duplicate`);
           continue;
         }
         try {
           registerTargetType(entry.name, entry.spec);
-          log('info', `Loaded watch target type '${entry.name}' from watches.d/${fname}`);
+          log('info', `Loaded watch target type '${entry.name}' from ${directoryName}/${fname}`);
         } catch (regErr) {
-          log('warn', `watches.d/${fname}: registerTargetType('${entry.name}') failed: ${regErr.message}`);
+          log('warn', `${directoryName}/${fname}: registerTargetType('${entry.name}') failed: ${regErr.message}`);
         }
       }
     } catch (err) {
-      log('warn', `watches.d/${fname}: load failed: ${err.message}`);
+      log('warn', `${directoryName}/${fname}: load failed: ${err.message}`);
     }
   }
 }
+function _loadPluginTargetTypes() {
+  _loadPluginDirectory('watch-plugins');
+  _loadPluginDirectory('watches.d', { legacy: true });
+}
 _loadPluginTargetTypes();
 
 module.exports = {
@@ -1748,8 +1759,8 @@ module.exports = {
   registerTargetType,
   getTargetType,
   listTargetTypes,
-  // Re-exported from engine/watch-actions for callers that prefer a single
-  // import surface (dashboard.js handlers, tests). See engine/watch-actions.js
+  // Re-exported from engine/watches/actions for callers that prefer a single
+  // import surface (dashboard.js handlers, tests).
   // for the canonical implementations and the action registry.
   registerActionType: watchActions.registerActionType,
   getActionType: watchActions.getActionType,
@@ -1761,5 +1772,5 @@ module.exports = {
   _captureState,  // exported for testing
   _runActionTask, // exported for testing — invoked by checkWatches per fired action
   _TARGET_TYPES: TARGET_TYPES, // exported for testing — direct registry access
-  _loadPluginTargetTypes, // exported for testing — re-scans watches.d/
+  _loadPluginTargetTypes, // exported for testing — re-scans watch-plugins/
 };

package/engine/{watches-store.js → watches/store.js}

@@ -1,4 +1,4 @@
-// engine/watches-store.js — SQL-backed watches.
+// engine/watches/store.js — SQL-backed watches.
 //
 // A single SQL table (no per-scope split), with a diff-then-apply mutator.
 //
@@ -29,7 +29,7 @@ function _readWatchesFromSqlOnly(db) {
 }
 
 function readWatches() {
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   return _readWatchesFromSqlOnly(getDb());
 }
 
@@ -100,11 +100,11 @@ function _applyWatchesDiff(db, diff) {
 }
 
 function applyWatchesMutation(mutator) {
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   let db;
   try { db = getDb(); }
   catch (e) {
-    throw new Error(`engine/watches-store: SQLite unavailable (${e.message}); cannot mutate watches`);
+    throw new Error(`engine/watches/store: SQLite unavailable (${e.message}); cannot mutate watches`);
   }
 
   return withTransaction(db, () => {

package/engine/{create-pr-worktree.js → worktrees/create-pr.js}

@@ -21,7 +21,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 const PATCH_APPLY_TIMEOUT_MS = 120000;
 

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

@@ -9,7 +9,7 @@
 //      worktree was borrowed from the pool, returned to the pool, or is
 //      anchored by live keep_processes PIDs / managed_spawn cwds.
 //
-//   2. On engine boot (engine/cli.js): scan each project's worktree root
+//   2. On engine boot (engine/operations/cli.js): scan each project's worktree root
 //      for orphan W-* dirs whose dispatch is not active
 //      or pending) AND that are not pool entries. Such dirs are leftovers
 //      from a prior crash that block retries with
@@ -24,21 +24,21 @@
 const fs = require('fs');
 const path = require('path');
 
-const shared = require('./shared');
-const worktreePool = require('./worktree-pool');
+const shared = require('../core/shared');
+const worktreePool = require('./pool');
 
 const DEFAULT_ORPHAN_RETENTION_MS = 2 * 60 * 60 * 1000;
 const DEFAULT_QUARANTINE_RETENTION_MS = 24 * 60 * 60 * 1000;
 
 let keepProcessSweep = null;
 function _keepProcessSweep() {
-  if (!keepProcessSweep) keepProcessSweep = require('./keep-process-sweep');
+  if (!keepProcessSweep) keepProcessSweep = require('../processes/keep-process-sweep');
   return keepProcessSweep;
 }
 
 let managedSpawn = null;
 function _managedSpawn() {
-  if (!managedSpawn) managedSpawn = require('./managed-spawn');
+  if (!managedSpawn) managedSpawn = require('../processes/managed-spawn');
   return managedSpawn;
 }
 
@@ -263,12 +263,13 @@ function _maybeEscalateStuck(resolvedPath, errorMsg, opts = {}) {
       const minAgeMs = agentTimeoutMs * 2;
       const killFn = typeof opts.killImmediate === 'function'
         ? opts.killImmediate
-        : shared.killImmediate;
+        : (proc, holder) => shared.terminateProcess('engine.worktree-gc.orphan-holder', proc, {
+            expectedIdentity: { pid: holder.pid, startedAt: holder.startedAt },
+          });
       for (const h of holders) {
         if (!_isSafeReapHolder(h, basename, minAgeMs)) continue;
         try {
-          killFn({ pid: h.pid });
-          reapedPids.push(h.pid);
+          if (killFn({ pid: h.pid }, h) !== false) reapedPids.push(h.pid);
         } catch { /* fail-open — keep trying other holders */ }
       }
       if (reapedPids.length > 0) {
@@ -869,6 +870,15 @@ function reconcileStaleWorktreeDirectories(opts) {
     Number.isFinite(Number(opts.quarantineRetentionMs))
       ? Number(opts.quarantineRetentionMs)
       : DEFAULT_QUARANTINE_RETENTION_MS);
+  // W-ms5tb6ha016fda10 — bounded (but longest) window for PROTECTED quarantine
+  // dirs, whose dirty WIP has no durable recovery ref. 0 keeps them forever.
+  // W-ms87rbe601a66d13 — the config→default resolution goes through
+  // `shared.resolveQuarantineRetentionMs` so this sweep and the recovery-REF
+  // sweep read the operator override through ONE seam and cannot diverge.
+  const protectedQuarantineRetentionMs = Math.max(0,
+    Number.isFinite(Number(opts.protectedQuarantineRetentionMs))
+      ? Number(opts.protectedQuarantineRetentionMs)
+      : shared.resolveQuarantineRetentionMs(opts.config));
 
   const result = {
     scanned: 0,
@@ -1120,9 +1130,29 @@ function reconcileStaleWorktreeDirectories(opts) {
       }
       let protectedQuarantine = true;
       try { protectedQuarantine = !!_hasProtectedQuarantineMarker(candidate); } catch {}
+      // W-ms5tb6ha016fda10 — a protected quarantine keeps the LONGEST window,
+      // but no longer an infinite one. `protectedQuarantineRetentionMs === 0`
+      // is the explicit operator opt-out that restores forever-retention.
+      // Non-quarantine dirs are never affected: the marker probe fails open to
+      // `true`, so an unreadable dir is still preserved.
       if (protectedQuarantine) {
-        keep('protected', candidate);
-        continue;
+        if (protectedQuarantineRetentionMs === 0) {
+          keep('protected', candidate);
+          continue;
+        }
+        let protectedStat;
+        try { protectedStat = _fs.statSync(candidate); }
+        catch {
+          keep('protected', candidate);
+          continue;
+        }
+        const protectedCreatedAt = _isQuarantineDirName(name)
+          ? _quarantineCreatedAt(name, protectedStat.mtimeMs)
+          : protectedStat.mtimeMs;
+        if ((now - protectedCreatedAt) < protectedQuarantineRetentionMs) {
+          keep('protected', candidate);
+          continue;
+        }
       }
 
       let owned = false;
@@ -1222,7 +1252,7 @@ function reconcileStaleWorktreeDirectories(opts) {
  *   2. Normalized abs path is currently in any `worktreePool` entry (idle
  *      or borrowed) — see `extraPoolPaths` for the test override.
  *   3. Worktree contains (or equals) the cwd of any live managed_spawn
- *      spec — matches `engine/cleanup.js`'s tick-time protection so a
+ *      spec — matches `engine/orchestration/cleanup.js`'s tick-time protection so a
  *      completed dispatch with long-running services survives engine
  *      restart. (PR #2627 review — Issue 1)
  *
@@ -1394,16 +1424,21 @@ function pruneOrphanWorktrees(opts) {
         continue;
       }
       // Quarantine directories are recovery artifacts, not ordinary crash
-      // residue. Keep them for a deterministic recovery window, and keep
-      // protected quarantines indefinitely when no durable backup ref exists.
+      // residue. Keep them for a deterministic recovery window.
+      //
+      // W-ms5tb6ha016fda10 — PROTECTED quarantines (dirty WIP that could NOT be
+      // snapshotted to a durable `refs/minions/quarantine-wip/*` ref) used to be
+      // kept FOREVER. That is why a busy install accumulated 20 quarantine dirs
+      // with no expiry. They still get the LONGEST window — `engine
+      // .worktreeProtectedQuarantineRetentionMs`, whose default is DERIVED from
+      // `shared.QUARANTINE_REF_RETENTION_MS` (30 days) so directories and
+      // recovery refs expire together — but the window is now finite. Setting the
+      // config value to 0 restores indefinite retention (for the recovery refs
+      // too, since W-ms87rbe601a66d13 routes both sweeps through
+      // `shared.resolveQuarantineRetentionMs`).
       if (_isQuarantineDirName(name)) {
         let protectedQuarantine = true;
         try { protectedQuarantine = shared.hasProtectedQuarantineMarker(wtPath); } catch {}
-        if (protectedQuarantine) {
-          projStats.kept++; result.kept++;
-          projStats.preserved++; result.preserved++;
-          continue;
-        }
         let quarantineStat;
         try { quarantineStat = _fs.statSync(wtPath); }
         catch {
@@ -1412,10 +1447,23 @@ function pruneOrphanWorktrees(opts) {
           continue;
         }
         const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
-        const retentionMs = Math.max(0,
-          Number.isFinite(Number(opts.quarantineRetentionMs))
-            ? Number(opts.quarantineRetentionMs)
-            : DEFAULT_QUARANTINE_RETENTION_MS);
+        const protectedRetentionMs = Math.max(0,
+          Number.isFinite(Number(opts.protectedQuarantineRetentionMs))
+            ? Number(opts.protectedQuarantineRetentionMs)
+            : shared.resolveQuarantineRetentionMs(opts.config));
+        const retentionMs = protectedQuarantine
+          ? protectedRetentionMs
+          : Math.max(0,
+            Number.isFinite(Number(opts.quarantineRetentionMs))
+              ? Number(opts.quarantineRetentionMs)
+              : DEFAULT_QUARANTINE_RETENTION_MS);
+        // 0 == keep forever (explicit operator opt-out), and only for the
+        // protected class — an unprotected quarantine always has a durable ref.
+        if (protectedQuarantine && retentionMs === 0) {
+          projStats.kept++; result.kept++;
+          projStats.preserved++; result.preserved++;
+          continue;
+        }
         const createdAt = _quarantineCreatedAt(name, quarantineStat.mtimeMs);
         if ((now - createdAt) < retentionMs) {
           projStats.kept++; result.kept++;