@yemi33/minions 0.1.2305 → 0.1.2307

package/engine.js

@@ -138,7 +138,7 @@ const worktreePool = require('./engine/worktree-pool');
 // ─── State Readers (delegated to engine/queries.js) ─────────────────────────
 
 const { getConfig, getControl, getDispatch, getNotes,
-  getAgentStatus, getAgentCharter, getInboxFiles,
+  getAgentStatus, getInboxFiles,
   collectSkillFiles, getSkillIndex, getKnowledgeBaseIndex,
   getPrs, SKILLS_DIR } = queries;
 
@@ -1974,6 +1974,43 @@ function _applyAgentTempEnv(childEnv, project) {
   } catch { /* leave inherited TEMP untouched */ }
 }
 
+// W-mr28h2j2000y0de1 review (calebt_microsoft, 2026-07-01): "classify as
+// non-retryable" alone leaves the operator to manually clean up every time.
+// Before refusing, ATTEMPT to actually resolve the conflict — remove the
+// conflicting worktree and let the caller retry the checkout — but ONLY when
+// it is safe to do so. Every one of these gates must pass or we leave the
+// conflicting worktree untouched and fall back to the existing refusal:
+//   1. conflictPath resolves inside THIS project's configured worktreeRoot —
+//      the standard location for engine-created worktrees. Anything outside
+//      it might be a human's own tree; shared.removeWorktree's containment
+//      check would refuse it anyway, but we check first for a clearer reason.
+//   2. it carries the engine ownership marker (shared.hasWorktreeOwnerMarker)
+//      — a hand-made worktree (`git worktree add /tmp/foo …`) has no marker.
+//   3. shared.removeWorktree succeeds. It independently refuses to touch a
+//      worktree with a LIVE dispatch running inside it (isWorktreePathLive,
+//      fails open) and refuses real-repo-root / non-linked-worktree paths.
+// Returns { removed, reason } for alert/log enrichment either way.
+function _tryAutoResolveLiveCheckoutWorktreeConflict({ conflictPath, gitRoot, engineConfig, log }) {
+  try {
+    const _wtRoot = path.resolve(gitRoot, (engineConfig && engineConfig.worktreeRoot) || ENGINE_DEFAULTS.worktreeRoot);
+    const _resolvedConflict = path.resolve(conflictPath);
+    if (_resolvedConflict !== _wtRoot && !_resolvedConflict.startsWith(_wtRoot + path.sep)) {
+      return { removed: false, reason: 'outside the configured worktreeRoot — not engine-managed, left untouched' };
+    }
+    if (!shared.hasWorktreeOwnerMarker(_resolvedConflict)) {
+      return { removed: false, reason: 'no engine ownership marker — likely human-created, left untouched' };
+    }
+    const _removed = shared.removeWorktree(_resolvedConflict, gitRoot, _wtRoot);
+    if (!_removed) {
+      return { removed: false, reason: 'shared.removeWorktree declined (live dispatch active inside it, real-repo guard, or removal failure — see engine logs)' };
+    }
+    return { removed: true, reason: 'removed stale engine-owned worktree' };
+  } catch (e) {
+    log('warn', `live-checkout: auto-resolve threw: ${e.message}`);
+    return { removed: false, reason: `auto-resolve threw: ${e.message}` };
+  }
+}
+
 async function spawnAgent(dispatchItem, config) {
   const { id, agent: agentId, type, meta } = dispatchItem;
   // Resolve prompt — prefers sidecar file when dispatchItem._promptFile is set
@@ -2420,6 +2457,56 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // ── Auto-stash a dirty live-checkout tree (W-mqtvnnj1000357fa) ──────────
+    // When the tree is dirty AND auto-stash is enabled (per-project field wins,
+    // else engine fleet-wide fallback), `git stash push --include-untracked` the
+    // operator's changes so dispatch can proceed instead of failing with
+    // FAILURE_CLASS.LIVE_CHECKOUT_DIRTY. The full flow (stash → re-preflight →
+    // clear retry stamp → operator inbox note) lives in live-checkout.js to keep
+    // spawnAgent lean; here we only handle the engine-specific outcomes. The
+    // engine NEVER pops the stash automatically (operator choice).
+    // NOTE: the helper gates on `liveResult.reason === 'dirty'` internally so the
+    // confirmed-dirty refusal `if` below remains the first textual match for that
+    // dirty-reason check in this file.
+    const _autoStash = await _liveCheckout.applyLiveCheckoutAutoStash({
+      liveResult: _liveResult,
+      project,
+      engine: engineConfig,
+      localPath: cwd,
+      branchName,
+      mainRef: _liveMainRef,
+      gitOpts: _gitOpts,
+      dispatchId: id,
+      wiId: _wiIdForAlert,
+      log: (msg, lvl) => log(lvl || 'info', msg),
+      clearDirtyStamp: () => {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi && wi._pendingReason === 'live_checkout_dirty') delete wi._pendingReason;
+            return data;
+          });
+        }
+      },
+      writeStashNote: (key, body) => writeInboxAlert(key, body),
+    });
+    if (_autoStash.outcome === 'threw') {
+      const stashLiveErr = _autoStash.error;
+      log('error', `spawnAgent: live-checkout helper threw after auto-stash for ${id}: ${stashLiveErr.message}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        `live-checkout failed: ${stashLiveErr.message}`.slice(0, 800),
+        'Live-checkout helper threw after auto-stash (not proof of a dirty tree). Auto-retried with bounded backoff; transient git/branch-lock state usually clears on the next attempt.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_FAILED },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
+    _liveResult = _autoStash.liveResult;
     if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'dirty') {
       const _dirtyFiles = Array.isArray(_liveResult.dirtyFiles) ? _liveResult.dirtyFiles : [];
       const _branchInfo = typeof _liveResult.branchInfo === 'string' ? _liveResult.branchInfo : '';
@@ -2637,6 +2724,109 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // W-mr28h2j2000y0de1: worktree-conflict refusal. The existing-branch
+    // `git checkout` refused because the target branch is ALSO checked out in a
+    // SECOND worktree elsewhere (a leftover from a prior isolated-worktree
+    // dispatch, a manually-created worktree, or a stale worktree left by a
+    // checkoutMode change). This is a STRUCTURAL conflict — it does NOT clear on
+    // retry, ever, until a human or the engine removes/reassigns the other
+    // worktree — so it gets its own non-retryable FAILURE_CLASS instead of
+    // LIVE_CHECKOUT_FAILED's bounded retry-storm. prepareLiveCheckout already
+    // best-effort switched HEAD back to the operator's original ref.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'worktree-conflict') {
+      // W-mr28h2j2000y0de1 review (calebt_microsoft): try to actually RESOLVE
+      // the conflict before refusing. Only proceeds when the conflicting
+      // worktree is engine-owned and not live-in-use (see
+      // _tryAutoResolveLiveCheckoutWorktreeConflict); on success, retry the
+      // checkout once and fall through to the normal success path below.
+      const _conflictPathForResolve = typeof _liveResult.conflictingWorktreePath === 'string' && _liveResult.conflictingWorktreePath
+        ? _liveResult.conflictingWorktreePath
+        : null;
+      if (_conflictPathForResolve) {
+        const _resolveOutcome = _tryAutoResolveLiveCheckoutWorktreeConflict({
+          conflictPath: _conflictPathForResolve, gitRoot: cwd, engineConfig, log,
+        });
+        if (_resolveOutcome.removed) {
+          log('info', `live-checkout: auto-resolved worktree conflict — ${_resolveOutcome.reason} at ${_conflictPathForResolve}; retrying checkout`);
+          try {
+            _liveResult = await _liveCheckout.prepareLiveCheckout({
+              localPath: cwd,
+              branchName,
+              mainRef: _liveMainRef,
+              gitOpts: _gitOpts,
+              dispatchId: id,
+              wiId: _wiIdForAlert,
+              skipDirtyCheck: !!project.skipLiveCheckoutDirtyCheck,
+              log: (msg, lvl) => log(lvl || 'info', msg),
+            });
+          } catch (retryErr) {
+            log('warn', `live-checkout: retry after auto-resolve threw: ${retryErr.message}`);
+            _liveResult = { ok: false, reason: 'worktree-conflict', conflictingWorktreePath: _conflictPathForResolve, message: retryErr.message };
+          }
+        } else {
+          log('info', `live-checkout: worktree conflict at ${_conflictPathForResolve} not auto-resolved (${_resolveOutcome.reason})`);
+        }
+      }
+    }
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'worktree-conflict') {
+      const _conflictMsg = typeof _liveResult.message === 'string' ? _liveResult.message : '';
+      const _conflictPath = typeof _liveResult.conflictingWorktreePath === 'string' && _liveResult.conflictingWorktreePath
+        ? _liveResult.conflictingWorktreePath
+        : null;
+      const _pathPhrase = _conflictPath ? `\`${_conflictPath}\`` : 'an unknown location';
+      const _alertBody = [
+        '# Live-checkout blocked: branch already used by another worktree',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**Branch:** ${branchName}`,
+        `**Conflicting worktree:** ${_conflictPath || '(unknown location)'}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine could not switch \`${cwd}\` onto \`${branchName}\` because that branch is already checked out in another worktree at ${_pathPhrase}. This is a structural conflict — **it will NOT clear on retry**. Your tree was left on its original ref (the engine never forces, resets, or cleans it).`,
+        ...(_conflictMsg ? ['', '```', _conflictMsg, '```'] : []),
+        '',
+        '## Recovery',
+        '',
+        `Pick ONE, depending on whether the other worktree still holds work you need:`,
+        '',
+        `1. **If that worktree is stale / no longer needed** — remove it to free the branch for the live checkout:`,
+        '',
+        '```',
+        `git worktree remove ${_conflictPath || '<path>'}`,
+        `# or, if it has uncommitted changes you are SURE you can discard (this DISCARDS that WIP):`,
+        `git worktree remove --force ${_conflictPath || '<path>'}`,
+        '```',
+        '',
+        `2. **If that worktree holds real work-in-progress** — do NOT re-dispatch this work item in live mode. Finish, commit, and push directly from ${_pathPhrase} instead, or rename/retarget the branch so the two no longer collide.`,
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-worktree-conflict-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      try {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi) wi._pendingReason = 'live_checkout_worktree_conflict';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: ${branchName} already used by worktree at ${_conflictPath || 'unknown location'}`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        'Live-checkout could not switch onto the branch because it is already checked out in another worktree. Structural — operator must remove/reassign the conflicting worktree (or finish its WIP) before re-dispatch. Retrying is provably useless.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
     // PL-live-checkout-reliability-hardening: a clean spawn clears the two-strike
     // dirty counter so a project that was transiently dirty once isn't treated as
@@ -8049,6 +8239,20 @@ function discoverFromWorkItems(config, project) {
     const promptItem = linkedPr ? withWorkItemPrContext(item, linkedPr) : item;
     const prBranch = linkedPr?.branch || '';
     const isPrTargeted = !!(linkedPr && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));
+    // Issue #607 — `linkedPr` above resolves through the LOOSE
+    // extractWorkItemPrRef (title/first-paragraph-of-description text scan),
+    // which is fine for prompt-context enrichment (promptItem, above) that
+    // downgrades gracefully on a miss. But `dispatch.meta.pr` is a hard signal:
+    // `_isPrBackedDispatch`/`getStalePrDispatchReason` (engine/dispatch.js)
+    // treat ANY dispatch carrying it as PR-backed and will cancel the source
+    // work item outright if the tracked PR turns out to be merged/abandoned/
+    // context-only or branch-mismatched. A loose text match against an
+    // unrelated already-tracked PR (e.g. an ordinary implement item whose
+    // description says "see PR #99 for context") must never bind meta.pr —
+    // only a STRUCTURED PR pointer (targetPr/pr/references[]/pr_followup —
+    // see extractStructuredWorkItemPrRef) is strong enough evidence of real
+    // operator intent to make this dispatch cancellable on PR staleness.
+    const dispatchLinkedPr = (linkedPr && getStructuredWorkItemPrRef(item)) ? linkedPr : null;
     // W-mq18ec6h000p7b87: gate on the STRUCTURED-only ref. Loose
     // getWorkItemPrRef would also pick up description-scan refs (e.g. a
     // refactor item whose prose mentioned "PR #3015 for context") and trip
@@ -8130,7 +8334,7 @@ function discoverFromWorkItems(config, project) {
       agentRole: config.agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent',
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
-      meta: { dispatchKey: key, cooldownKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(isPrTargeted || (item.branchStrategy === 'shared-branch' && item.featureBranch)), item: promptItem, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution, ...(linkedPr ? { pr: linkedPr } : {}) }
+      meta: { dispatchKey: key, cooldownKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(isPrTargeted || (item.branchStrategy === 'shared-branch' && item.featureBranch)), item: promptItem, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution, ...(dispatchLinkedPr ? { pr: dispatchLinkedPr } : {}) }
     });
 
     } catch (err) { log('warn', `discoverFromWorkItems: skipping ${item.id}: ${err.message}`); }
@@ -9914,8 +10118,8 @@ async function tickInner() {
     // sibling-less stamps are preserved as tracking signals.
     try {
       const result = pruneScopeMismatchDuplicatePrs(config);
-      if (result?.pruned > 0) {
-        log('info', `[pull-requests] scope-mismatch sweep pruned ${result.pruned} duplicate record(s) across ${result.scanned} scanned`);
+      if (result?.pruned > 0 || result?.relocated > 0) {
+        log('info', `[pull-requests] scope-mismatch sweep pruned ${result.pruned} duplicate record(s), relocated ${result.relocated || 0} record(s) across ${result.scanned} scanned`);
       }
     } catch (err) {
       log('warn', `[pull-requests] scope-mismatch sweep error: ${err?.message || err}`);
@@ -10564,7 +10768,7 @@ module.exports = {
 
   // State readers/writers
   getConfig, getControl, getDispatch, getRouting, getNotes,
-  getAgentStatus, getAgentCharter, getInboxFiles, getPrs,
+  getAgentStatus, getInboxFiles, getPrs,
   validateConfig,
 
   // Dispatch management (re-exported from engine/dispatch.js)
@@ -10602,6 +10806,7 @@ module.exports = {
   findExistingWorktree, // exported for testing
   probeBranchOnRemote, // exported for testing (W-mphnm6a1000281b8)
   _maxTurnsForType, buildProjectContext, normalizeAc, _buildAgentSpawnFlags, _classifyAgentFailure, // exported for testing
+  _tryAutoResolveLiveCheckoutWorktreeConflict, // exported for testing (W-mr28h2j2000y0de1 review — auto-resolve worktree conflicts)
   _isOutputTruncated, AGENT_OUTPUT_CAP_BYTES, // P-8e4c2a17: exported for testing (OUTPUT_TRUNCATED detection)
   promoteCheckpointSteeringForClose, // exported for testing
   normalizePrBranch, resolvePrBranch, prCausePart, getPrCauseHead, getPrCauseBase, getPrAutomationCauseKey, getPrAutomationDispatchKey, // exported for testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2305",
+  "version": "0.1.2307",
   "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"

package/playbooks/review.md

@@ -30,6 +30,8 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
 {{#project_skills_block}}
 {{project_skills_block}}
 
+> **Skipping an in-scope review skill is gated.** Before you record a `meta.review.skillSkipped` (or `meta.skill.skipped`) outcome for any skill listed above, re-read that skill's own SKILL.md checklist and confirm your skip reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item it documents. If the diff trips ANY such item, do NOT skip — apply the skill (or at least that item). When you do skip, surface the exact same `{name, reason}` in your PR review comment via `minions pr comment … --skill-skipped-json '{"name":"…","reason":"…"}'` so a human sees it alongside your verdict before merge (no drift between the report and the comment). See `playbooks/shared-rules.md` → "Skipped an in-scope project skill?".
+
 {{/project_skills_block}}
 2. Think about deploy risk before commenting:
    - What user-visible behavior changed?

package/playbooks/shared-rules.md

@@ -176,6 +176,15 @@ When you author a **PR review / fix summary comment**, the same harness footprin
 
 One bullet per affordance, in the order skills → MCP servers → commands → docs; `N` is the bullet count. Whether the CLI folds it in or you hand-render it on a raw fallback, the section is the human-readable mirror of your `harnessUsed` completion field — keep the two consistent.
 
+### Skipped an in-scope project skill? Validate the skip, then surface it in the PR comment
+
+`meta.review.skillSkipped` / `meta.skill.skipped` (shape `{name, reason}`, see `docs/completion-reports.md`) lets you self-report that you intentionally skipped an available, **in-scope** project (review) skill. Two hard rules apply — this is not aspirational:
+
+1. **Validate the skip against the skill's own scope before recording it.** Re-read the skipped skill's SKILL.md review criteria / checklist (the content already injected via the `## Project skills` / `## Project review skills` block). Confirm your skip reason does **not** contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item the skill documents. If the diff trips ANY explicit checklist item the skill covers, skipping is **not** permitted — apply the skill (or at minimum that specific checklist item). A skip reason that waves away a gate the skill explicitly documents (e.g. "no CHANGELOG needed for this diff" when the skill's CHANGELOG Requirements section says otherwise) is invalid.
+2. **Surface the skip in the PR comment, not just the JSON.** When you post a review/fix summary comment, the skip must be visible in the same comment as the verdict so a human sees it **before** merge. Via `minions pr comment` (GitHub and ADO `--host ado`), pass `--skill-skipped-file <path>` (JSON `{name, reason}`) or inline `--skill-skipped-json <json>`; the shared builder (`engine/comment-format.js#buildSkippedSkillSection`, consumed by both `engine/gh-comment.js` and `engine/ado-comment.js`) folds a byte-identical `> ⚠️ Skipped project skill: <name> — <reason>` callout in for you. On raw fallbacks (`gh pr comment` / `az repos pr comment` / ADO REST) render that exact one-line blockquote callout yourself.
+
+The **same** `{name, reason}` you record in `meta.review.skillSkipped` / `meta.skill.skipped` must be the one rendered in the PR comment — no drift between the two.
+
 ## Minions API access
 
 The Minions dashboard runs at `http://localhost:7331` whenever the engine is up. Agents may call its HTTP endpoints when (and only when) the playbook explicitly authorizes it for a particular task — most dispatches do not need any API access, and uninvited writes to engine-managed state are still prohibited (see "Do NOT write to `agents/*/status.json`" above).