@yemi33/minions 0.1.2215 → 0.1.2217

package/engine/shared.js

@@ -192,6 +192,54 @@ function ts() { return new Date().toISOString(); }
 function logTs() { return new Date().toLocaleTimeString(); }
 function dateStamp() { return new Date().toISOString().slice(0, 10); }
 
+// ── Node / node:sqlite version gate (issue #244) ────────────────────────────
+// `node:sqlite` (the only state backend post Phase 9.4) is built-in only on
+// Node >= 22.5.0. On older Node the `--experimental-sqlite` self-reexec is a
+// no-op and every getDb() throws a raw stack trace. These helpers give the CLI
+// preflight + `minions doctor` a single, NUMERIC (not lexical) version gate and
+// one canonical remediation line so both surfaces agree.
+const NODE_SQLITE_MIN_VERSION = '22.5.0';
+
+/**
+ * Numeric semver-ish comparison of two dotted version strings. Compares
+ * major/minor/patch as integers so '22.5.0' sorts AFTER '22.10.0' would NOT —
+ * i.e. it does NOT lexically compare ('9' > '22' under string compare). Missing
+ * components are treated as 0. Returns -1 (a<b), 0 (a==b), or 1 (a>b).
+ */
+function compareDottedVersions(a, b) {
+  const parse = (v) => String(v == null ? '' : v)
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  const av = parse(a);
+  const bv = parse(b);
+  const len = Math.max(av.length, bv.length);
+  for (let i = 0; i < len; i++) {
+    const x = av[i] || 0;
+    const y = bv[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/**
+ * True when the given Node version (default: the running runtime) can load the
+ * built-in `node:sqlite` module — i.e. Node >= 22.5.0. Numeric comparison, so
+ * the 22.4.x → 22.5.0 boundary is handled correctly and 22.10+ / 24+ pass.
+ */
+function nodeSupportsBuiltinSqlite(version = process.versions.node) {
+  return compareDottedVersions(version, NODE_SQLITE_MIN_VERSION) >= 0;
+}
+
+/**
+ * The canonical one-line remediation emitted by both `minions doctor` (as the
+ * failing Node.js check message) and the top-level CLI preflight when Node is
+ * too old for built-in node:sqlite. Keep the wording identical across surfaces.
+ */
+function nodeSqliteRemediationLine(version = process.versions.node) {
+  return `Node.js: v${version} - Minions requires Node >= 22.5 (24 LTS recommended) for built-in node:sqlite. Upgrade Node, then run minions start.`;
+}
+
 // ── F6 (P-f6commentedit): Comment-edit dedup helpers ────────────────────────
 // Shared by engine/github.js + engine/ado.js pollPrHumanComments so a comment
 // EDITED after first observation triggers a single re-dispatch (and only one).
@@ -2483,25 +2531,60 @@ function classifyInboxItem(name, content) {
   return 'project-notes';
 }
 
-// ── Worktree Mode Enum (P-a3f9b201) ─────────────────────────────────────────
-// Per-project switch between the default `isolated` mode (engine creates a
-// dedicated worktree per dispatch under ../worktrees) and `live` mode (the
+// ── Checkout Mode Enum (P-a3f9b201; consolidated W-mqiaw974, issue #241) ──────
+// Per-project switch between the default `worktree` mode (engine creates a
+// dedicated git worktree per dispatch under ../worktrees) and `live` mode (the
 // agent runs directly in the operator's working checkout — used for repos
 // where git worktrees are unworkable, e.g. submodules, hooks, large binary
-// caches). Default is `isolated`; absent/undefined `worktreeMode` on a
-// project entry MUST read as 'isolated' everywhere downstream. Unknown
+// caches). Default is `worktree`; absent/undefined `checkoutMode` on a
+// project entry MUST read as 'worktree' everywhere downstream. Unknown
 // values are rejected at the validators — never silently coerced — so a
 // typo in the dashboard or in config.json cannot wedge dispatch into an
 // unknown mode.
-const WORKTREE_MODES = Object.freeze({ ISOLATED: 'isolated', LIVE: 'live' });
-
-function validateWorktreeMode(value) {
+//
+// LEGACY FIELD (back-compat): this field used to be named `worktreeMode` with
+// the enum { isolated, live }. The rename consolidated the two overlapping
+// fields into a single `checkoutMode` { worktree, live }: `isolated` → the
+// implicit `worktree` behavior, `live` → `live`. `resolveCheckoutMode` still
+// reads the legacy `worktreeMode` field so existing live-checkout projects in
+// config.json keep working without an on-disk rewrite. Tracked in
+// docs/deprecated.json (id: worktreemode-field-rename).
+const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
+
+// Resolve a project's effective checkout mode, honoring the legacy
+// `worktreeMode` field for back-compat. Reading order:
+//   1. canonical `project.checkoutMode` ('worktree' | 'live')
+//   2. legacy `project.worktreeMode` ('isolated' → 'worktree', 'live' → 'live')
+//   3. default → 'worktree'
+// Always returns one of CHECKOUT_MODES — never undefined — so call sites can
+// compare against the enum without a falsy guard.
+function resolveCheckoutMode(project) {
+  if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
+  const canonical = project.checkoutMode;
+  if (canonical === CHECKOUT_MODES.LIVE) return CHECKOUT_MODES.LIVE;
+  if (canonical === CHECKOUT_MODES.WORKTREE) return CHECKOUT_MODES.WORKTREE;
+  // Legacy field fallback (only consulted when checkoutMode is absent/unknown).
+  const legacy = project.worktreeMode;
+  if (legacy === 'live') return CHECKOUT_MODES.LIVE;
+  // legacy 'isolated' (and anything else) → the default worktree behavior.
+  return CHECKOUT_MODES.WORKTREE;
+}
+
+// Convenience predicate: does this project dispatch in-place (live checkout)?
+function isLiveCheckoutProject(project) {
+  return resolveCheckoutMode(project) === CHECKOUT_MODES.LIVE;
+}
+
+function validateCheckoutMode(value) {
   if (value === undefined || value === null || value === '') return undefined;
   if (typeof value !== 'string') {
-    throw _httpError(400, `Invalid worktreeMode: must be a string (got ${typeof value}). Accepted values: 'isolated', 'live'.`);
+    throw _httpError(400, `Invalid checkoutMode: must be a string (got ${typeof value}). Accepted values: 'worktree', 'live'.`);
   }
-  if (value !== WORKTREE_MODES.ISOLATED && value !== WORKTREE_MODES.LIVE) {
-    throw _httpError(400, `Invalid worktreeMode: "${value}". Accepted values: 'isolated' (default), 'live'.`);
+  // Back-compat: silently coerce the legacy 'isolated' value to the canonical
+  // 'worktree' so an old client / cached dashboard tab doesn't 400.
+  if (value === 'isolated') return CHECKOUT_MODES.WORKTREE;
+  if (value !== CHECKOUT_MODES.WORKTREE && value !== CHECKOUT_MODES.LIVE) {
+    throw _httpError(400, `Invalid checkoutMode: "${value}". Accepted values: 'worktree' (default), 'live'.`);
   }
   return value;
 }
@@ -5564,7 +5647,9 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * field for read-only stages. Only code-mutating pipeline stages need a
  * worktree, and they take the normal code-mutating path below.
  *
- * **Live-checkout mode (P-a3f9b202).** When `project.worktreeMode === 'live'`
+ * **Live-checkout mode (P-a3f9b202).** When the project's resolved checkout
+ * mode is `'live'` (`shared.isLiveCheckoutProject(project)`; canonical
+ * `project.checkoutMode === 'live'` or legacy `project.worktreeMode === 'live'`)
  * the resolver short-circuits BEFORE both branches below and returns
  * `{ cwd: <abs localPath>, worktreeRootDir: null, liveMode: true }` for ALL
  * task types — read-only and code-mutating alike. The agent runs directly
@@ -5591,7 +5676,7 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * caught post-resolve). The mutating containment check happens later in
  * spawnAgent, against the actual worktree path.
  *
- * @param {{ localPath?: string|null, worktreeMode?: string|null }|null|undefined} project
+ * @param {{ localPath?: string|null, checkoutMode?: string|null, worktreeMode?: string|null }|null|undefined} project
  * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
  * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
  * @param {{ workdir?: string|null }} [options] — optional per-WI overrides
@@ -5603,7 +5688,7 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  *      then runs shared.applyWorkdir(worktreePath, result.workdir) to land
  *      the agent inside the subpackage cwd)
  *   The optional `liveMode` discriminator lets callers branch on one boolean
- *   instead of re-reading `project.worktreeMode`.
+ *   instead of re-resolving the project's checkout mode.
  * @throws {Error} LIVE_CHECKOUT_NO_LOCALPATH (live mode, missing localPath),
  *                 INVALID_WORKDIR (live or read-only, workdir escapes base),
  *                 WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT (isolated code-mutating),
@@ -5618,11 +5703,11 @@ function resolveSpawnPaths(project, type, minionsDir, options) {
   // Runs BEFORE the read-only / code-mutating split so live mode is the
   // single decision point regardless of task type — read-only tasks in
   // live mode still report liveMode:true so downstream callers don't have
-  // to re-read project.worktreeMode to know they're running in-place.
-  if (project?.worktreeMode === WORKTREE_MODES.LIVE) {
+  // to re-resolve the project's checkout mode to know they're running in-place.
+  if (isLiveCheckoutProject(project)) {
     if (!project.localPath) {
       const err = new Error(
-        'live-checkout mode requires project.localPath (worktreeMode === "live" but localPath is missing/falsy).'
+        'live-checkout mode requires project.localPath (checkoutMode === "live" but localPath is missing/falsy).'
       );
       err.code = 'LIVE_CHECKOUT_NO_LOCALPATH';
       throw err;
@@ -8368,6 +8453,11 @@ module.exports = {
   EDITS_SEEN_CAP, // F6 (P-f6commentedit)
   logTs,
   dateStamp,
+  // Node / node:sqlite version gate (issue #244)
+  NODE_SQLITE_MIN_VERSION,
+  compareDottedVersions,
+  nodeSupportsBuiltinSqlite,
+  nodeSqliteRemediationLine,
   log,
   safeRead,
   safeReadOrNull,
@@ -8561,8 +8651,10 @@ module.exports = {
   HAS_DANGEROUS_KEY_MAX_NODES,
   validateProjectName,
   validateProjectPath,
-  WORKTREE_MODES,
-  validateWorktreeMode,
+  CHECKOUT_MODES,
+  validateCheckoutMode,
+  resolveCheckoutMode,
+  isLiveCheckoutProject,
   validatePid,
   PR_FIX_CAUSE,
   getPrFixAutomationCause,

package/engine/timeout.js

@@ -1,7 +1,7 @@
 /**
  * engine/timeout.js — Runtime timeout, stale-orphan cleanup, steering, and idle checks.
  *
- * Live-checkout dispatches (project.worktreeMode === 'live') are killed by PID
+ * Live-checkout dispatches (project.checkoutMode === 'live') are killed by PID
  * exactly like isolated-mode dispatches — no special handling, no in-place
  * `git reset`/`git clean`, no working-tree cleanup. The engine only ever sends
  * SIGTERM/SIGKILL to the tracked process; the operator owns the checkout.

package/engine/worktree-pool.js

@@ -89,7 +89,7 @@ function getProjectPoolSize(projectName, config) {
   // borrow path in spawnAgent into running for a project that no longer
   // wants pooled worktrees. Beats both per-project worktreePoolSize and the
   // engine-wide fleet default.
-  if (proj && proj.worktreeMode === shared.WORKTREE_MODES.LIVE) return 0;
+  if (shared.isLiveCheckoutProject(proj)) return 0;
   if (proj && Number.isFinite(Number(proj.worktreePoolSize))) {
     return Math.max(0, Math.floor(Number(proj.worktreePoolSize)));
   }

package/engine.js

@@ -2046,7 +2046,7 @@ async function spawnAgent(dispatchItem, config) {
   }
 
   // ── Live-checkout mode handling (P-a3f9b204) ─────────────────────────────
-  // When project.worktreeMode === 'live', resolveSpawnPaths returned
+  // When the project's checkout mode is 'live', resolveSpawnPaths returned
   //   cwd = project.localPath, worktreeRootDir = null, liveMode = true.
   // Instead of creating an engine-managed worktree we run prepareLiveCheckout
   // in-place: it validates a clean tree and then checks out (or creates) the
@@ -9247,13 +9247,13 @@ async function tickInner() {
     if (d.meta?.branch) lockedBranches.add(sanitizeBranch(d.meta.branch));
   }
   // P-a3f9b205: Per-project mutating-concurrency gate for live-mode projects.
-  // When project.worktreeMode === 'live', the agent runs in-place inside the
-  // operator's localPath instead of a dedicated worktree, so two concurrent
+  // When the project's checkout mode is 'live', the agent runs in-place inside
+  // the operator's localPath instead of a dedicated worktree, so two concurrent
   // mutating dispatches to the same project would clobber each other's
   // index / working tree. Seed `liveProjectsInUse` from dispatch.active so
   // the gate survives across ticks (not just within one allocation pass).
   // Read-only types (meeting/ask/explore/plan/plan-to-prd) never write, so
-  // they are excluded from the cap. Isolated-mode projects are also
+  // they are excluded from the cap. Worktree-mode projects are also
   // excluded — they get a fresh worktree per dispatch and are naturally
   // safe.
   const liveProjectsInUse = new Set();
@@ -9262,7 +9262,7 @@ async function tickInner() {
     const projName = d.project || d.meta?.project?.name || null;
     if (!projName) continue;
     const projCfg = shared.findProjectByName(shared.getProjects(config), projName);
-    if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+    if (shared.isLiveCheckoutProject(projCfg)) {
       liveProjectsInUse.add(projName);
     }
   }
@@ -9439,7 +9439,7 @@ async function tickInner() {
       && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
     ) {
       const projCfg = shared.findProjectByName(shared.getProjects(config), itemProjName);
-      if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+      if (shared.isLiveCheckoutProject(projCfg)) {
         liveProjectsInUse.add(itemProjName);
       }
     }
@@ -9517,7 +9517,7 @@ async function tickInner() {
     const projName = d.project || d.meta?.project?.name || null;
     if (!projName) continue;
     const projCfg = shared.findProjectByName(shared.getProjects(config), projName);
-    if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+    if (shared.isLiveCheckoutProject(projCfg)) {
       postLiveProjectsInUse.add(projName);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2215",
+  "version": "0.1.2217",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"