@yemi33/minions 0.1.2306 → 0.1.2308

package/dashboard.js

@@ -258,8 +258,12 @@ function reloadConfig() {
   // Settings change takes effect without a dashboard restart (W-mr0qs0vw). The
   // pool stays dependency-free at load and relies on this push.
   try {
-    const idleMs = Number(CONFIG.engine?.ccWorkerIdleTimeoutMs)
-      || shared.ENGINE_DEFAULTS.ccWorkerIdleTimeoutMs;
+    // W-mr1qbj90000d30bd — 0 is the explicit "never idle-reap" sentinel and
+    // must NOT fall through to the default via `||` (0 is falsy in JS).
+    const cfgIdle = CONFIG.engine?.ccWorkerIdleTimeoutMs;
+    const idleMs = Number(cfgIdle) === 0
+      ? 0
+      : (Number(cfgIdle) || shared.ENGINE_DEFAULTS.ccWorkerIdleTimeoutMs);
     ccWorkerPool.setIdleTimeoutMs(idleMs);
   } catch { /* invalid value or pool unavailable — keep prior window */ }
 }
@@ -434,6 +438,15 @@ function mergeSettingsConfigUpdate(current, candidate, body, patch = {}) {
       } else {
         delete currentProject.checkoutMode;
       }
+      // W-mqtvnnj1000357fa — mirror the per-project liveCheckoutAutoStash
+      // override the same way: present on candidate → copy; absent → clear so
+      // the engine fleet-wide `engine.liveCheckoutAutoStash` applies. Without
+      // this branch the validated update is silently dropped before reaching disk.
+      if (Object.prototype.hasOwnProperty.call(candidateProject, 'liveCheckoutAutoStash')) {
+        currentProject.liveCheckoutAutoStash = candidateProject.liveCheckoutAutoStash;
+      } else {
+        delete currentProject.liveCheckoutAutoStash;
+      }
       // W-mqiaw974 (issue #241): the field was renamed from the legacy
       // `worktreeMode`. Drop any stale legacy key on every settings save so a
       // migrated project never carries both fields.
@@ -10957,6 +10970,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // the per-project dropdown. resolveCheckoutMode honors the legacy
           // worktreeMode field; 'worktree' (default) or 'live'.
           checkoutMode: shared.resolveCheckoutMode(p),
+          // W-mqtvnnj1000357fa — surface the RAW per-project auto-stash override
+          // (true / false / undefined) so the Settings UI can pre-select the
+          // tri-state dropdown. Undefined means "use fleet default"
+          // (engine.liveCheckoutAutoStash); only an explicit boolean overrides.
+          liveCheckoutAutoStash: (typeof p.liveCheckoutAutoStash === 'boolean') ? p.liveCheckoutAutoStash : undefined,
           workSources: {
             pullRequests: { enabled: p.workSources?.pullRequests?.enabled !== false, cooldownMinutes: p.workSources?.pullRequests?.cooldownMinutes ?? 30 },
             workItems: { enabled: p.workSources?.workItems?.enabled !== false, cooldownMinutes: p.workSources?.workItems?.cooldownMinutes ?? 0 }
@@ -11049,12 +11067,6 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // larger models); max 1h (matches CC_CALL_TIMEOUT_MS so the watchdog
           // never outlives the outer abort).
           ccTurnTimeoutMs: [10000, 3600000],
-          // W-mr0qs0vw — ACP worker idle-reaper window. 1min floor (anything
-          // shorter would reap a warm worker between a user's own messages and
-          // thrash cold-spawns); 8h ceiling (a config typo shouldn't pin a warm
-          // copilot process in memory indefinitely). Stored in ms; the Settings
-          // UI presents minutes and converts.
-          ccWorkerIdleTimeoutMs: [60000, 28800000],
           // W-mq9acoo800177bcb — bounded-concurrency for pre-dispatch validator.
           // 1 floor (sequential fallback) and 20 ceiling (above this the LLM
           // provider's per-second rate limits dominate; throughput gains taper).
@@ -11070,6 +11082,29 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             _setEngineConfig(key, val);
           }
         }
+        // W-mr0qs0vw / W-mr1qbj90000d30bd — ACP worker idle-reaper window.
+        // 1min floor (anything shorter would reap a warm worker between a
+        // user's own messages and thrash cold-spawns); 8h ceiling (a config
+        // typo shouldn't pin a warm copilot process in memory indefinitely).
+        // Handled OUTSIDE the generic numericFields loop because `0` is a
+        // valid, deliberate sentinel meaning "never idle-reap" (only closeTab
+        // kills the warm worker) — it must bypass the [60000, 28800000]
+        // clamp for that one value instead of being clamped up to 60000 or
+        // falling back to the default via `Number(e[key]) || D[key]`
+        // (0 is falsy in JS). Stored in ms; the Settings UI presents minutes.
+        if (e.ccWorkerIdleTimeoutMs !== undefined) {
+          const rawIdle = Number(e.ccWorkerIdleTimeoutMs);
+          if (rawIdle === 0) {
+            _setEngineConfig('ccWorkerIdleTimeoutMs', 0);
+          } else {
+            let val = rawIdle || D.ccWorkerIdleTimeoutMs;
+            const raw = val;
+            val = Math.max(60000, val);
+            val = Math.min(28800000, val);
+            if (val !== raw) _clamped.push(`ccWorkerIdleTimeoutMs: ${raw} → ${val} (range: 60000–28800000)`);
+            _setEngineConfig('ccWorkerIdleTimeoutMs', val);
+          }
+        }
         // String fields
         if (e.worktreeRoot !== undefined) _setEngineConfig('worktreeRoot', String(e.worktreeRoot || D.worktreeRoot));
         // W-mpejf0fq000e84d6: operator login override. Empty string clears
@@ -11412,6 +11447,18 @@ What would you like to discuss or change? When you're happy, say "approve" and I
               else proj.liveValidation = validatedLv;
             }
           }
+          // W-mqtvnnj1000357fa — per-project live-checkout auto-stash override.
+          // null / '' / undefined clears the override (engine fleet-wide
+          // `engine.liveCheckoutAutoStash` applies); an explicit boolean pins
+          // the per-project decision. Anything else is coerced to boolean.
+          if (Object.prototype.hasOwnProperty.call(update, 'liveCheckoutAutoStash')) {
+            const rawStash = update.liveCheckoutAutoStash;
+            if (rawStash === null || rawStash === '' || rawStash === undefined) {
+              delete proj.liveCheckoutAutoStash;
+            } else {
+              proj.liveCheckoutAutoStash = !!rawStash;
+            }
+          }
         }
       }
 
@@ -14889,6 +14936,14 @@ if (require.main === module) {
         if (!alive) {
           console.log(`[watchdog] Engine PID ${control.pid} is dead — auto-restarting...`);
           restartEngine();
+          // Crash-loop counter (W-mr2c46590003e3ee) — shares the same rolling
+          // window in control.json as engine/supervisor.js and
+          // engine/watchdog.js so a single crash isn't tallied 2-3x across
+          // the three independent respawn mechanisms; only THIS automatic
+          // dead-PID path counts (the user-triggered "Restart Engine" button
+          // in handleEngineRestart above is deliberate, not self-healing, so
+          // it's intentionally excluded).
+          try { shared.recordEngineRespawn('dashboard:in-process-watchdog'); } catch { /* best-effort */ }
         } else {
           _markEngineAsDegradedIfFrozen();
         }

package/docs/completion-reports.md

@@ -118,7 +118,7 @@ All `meta.skill` fields are optional and backward-compatible — older agents th
 |---|---|---|
 | `meta.skill.invoked` | object | The project skill the agent actually ran. Shape: `{name, path, kind, intent}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-project-skills.js`) and `intent` is the bucket it served (`build`, `review`, `fix`, `test`, `plan`, `research`, `deploy`, `observability`, `meta`). Omit when no skill was invoked. |
 | `meta.skill.findings` | number | Count of findings/artifacts the invoked skill returned. Semantics is per-skill; treat as opaque integer. Omit when no skill was invoked. |
-| `meta.skill.skipped` | object | Set when a project skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope, meta-work on the skill itself, etc.). Shape: `{name, reason}`. Mirror the skip rationale into the PR comment / completion summary so a human sees the reasoning. |
+| `meta.skill.skipped` | object | Set when a project skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope, meta-work on the skill itself, etc.). Shape: `{name, reason}`. **Before recording a skip you MUST validate it against the skill's own documented scope** — re-read the skill's SKILL.md checklist and confirm the skip reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item; if the diff trips any such item, skipping is not permitted (apply the skill or that item instead). Mirror the skip rationale into the PR comment so a human sees it **before** merge, not only via a later API call — `minions pr comment … --skill-skipped-file <f>` / `--skill-skipped-json <j>` folds a visible `> ⚠️ Skipped project skill: <name> — <reason>` callout into the same comment as the verdict (single renderer `engine/comment-format.js#buildSkippedSkillSection`, byte-identical on GitHub and ADO). The `{name, reason}` in the comment MUST match the one recorded here (no drift). |
 
 Dispatchers can suppress the block entirely by setting `meta.skipProjectSkills: true` on the work item — the playbook then renders without the skills block. Use this for meta-work that targets the skill itself; the engine still accepts `meta.skill.skipped` in the report regardless. The PR-82 `meta.skipProjectReviewSkills` flag is preserved as an alias (suppresses the block on every dispatch type, not just review).
 
@@ -150,7 +150,7 @@ All `meta.review` fields are optional and backward-compatible — older agents t
 |---|---|---|
 | `meta.review.skillInvoked` | object | The project review skill the agent actually ran. Shape: `{name, path, kind}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-project-skills.js`). Omit when no skill was invoked. Aliased by `meta.skill.invoked`. |
 | `meta.review.skillFindings` | number | Count of findings the invoked skill returned. Used later to measure skill quality and the value-add of first-principles review on top. Omit when no skill was invoked. Aliased by `meta.skill.findings`. |
-| `meta.review.skillSkipped` | object | Set when a project review skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope diff, meta-review of the skill itself, etc.). Shape: `{name, reason}`. Aliased by `meta.skill.skipped`. |
+| `meta.review.skillSkipped` | object | Set when a project review skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope diff, meta-review of the skill itself, etc.). Shape: `{name, reason}`. Aliased by `meta.skill.skipped`. **The skip reason is validated against the skill's own scope** — before recording a skip the agent must re-read the skill's SKILL.md checklist and confirm the reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item; if the diff trips any such item, skipping is not permitted. The same `{name, reason}` must also be surfaced in the PR review comment (visible `> ⚠️ Skipped project skill` callout, via `minions pr comment … --skill-skipped-json`) so a human sees it before merge — no drift between the report and the comment. |
 
 Dispatchers can suppress the block entirely by setting `meta.skipProjectReviewSkills: true` on the review work item — the playbook then renders identically to the pre-W-mq16xtdx 8-step contract. Use this for meta-reviews of the review skill itself; the engine still accepts `meta.review.skillSkipped` in the report regardless. (W-mq1cczi90006b21f generalized this to `meta.skipProjectSkills`, which suppresses the block on every dispatch type — both flags are honored.)
 

package/docs/harness-transparency.md

@@ -119,6 +119,24 @@ evaluation pass) can see what tooling drove a dispatch:
    paths review/fix agents append the section themselves per
    `playbooks/shared-rules.md` → "Harness transparency / self-report". Every
    surface consumes the one renderer, so there is no second formatter to drift.
+
+   **Skipped in-scope project skill (W-mr287sc0000uc214).** The same PR-comment
+   surface also folds in a VISIBLE (non-collapsed) `> ⚠️ Skipped project skill:
+   <name> — <reason>` callout when the agent self-reported that it intentionally
+   skipped an available, in-scope project (review) skill
+   (`meta.review.skillSkipped` / `meta.skill.skipped`). This lived only in the
+   completion-report JSON before — invisible to a human reading the PR pre-merge.
+   `engine/comment-format.js#buildSkippedSkillSection(skillSkipped)` is the single
+   neutral renderer (sibling of `buildHarnessUsedSection`); it is threaded through
+   `buildMinionsCommentBody` (optional `skillSkipped` arg) and both posters
+   (`gh-comment.js` / `ado-comment.js`), and the `minions pr comment` CLI turns
+   `--skill-skipped-file` / `--skill-skipped-json` into the record. Two rules
+   attach to the skip (see `docs/completion-reports.md` → Review/Project skill
+   outcomes): the skip reason must be **validated against the skill's own
+   documented checklist** before it is recorded (a skip that contradicts an
+   explicit "Flag if…" / "Requirements" item the skill covers is invalid), and
+   the `{name, reason}` rendered in the comment must match the one recorded in the
+   report (no drift).
 2. **Final agent note** — for a non-clean completion (failure / partial) the
    single final agent report (`engine/lifecycle.js#writeNonCleanAgentReport`)
    folds the grounded harness footprint in as the same `buildHarnessUsedSection`

package/docs/live-checkout-mode.md

@@ -37,7 +37,17 @@ Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status
 - Work item stamped with `_pendingReason: 'live_checkout_dirty'` so the dashboard surfaces the block.
 - Completion summary: `live-checkout refused: N dirty file(s) in <localPath>`.
 
-The engine never calls `git reset --hard`, `git clean -fd`, `git stash`, or any other state-mutating command against the operator's checkout — not at spawn, not at cleanup, not on timeout, not on engine restart. The dispatch-scoped cleanup paths (`worktreePool.returnToPool`, `worktree-gc.gcDispatchWorktreeIfOrphan`, `_quarantineDirtyWorktree`) are naturally no-ops because `worktreePath` stays `null` end-to-end (`engine.js:1219`). The **periodic** worktree GC, however, is NOT `worktreePath`-gated — it derives its targets from `git worktree list --porcelain`, which for a live project returns the operator's *own* primary checkout. So `engine/cleanup.js#runPeriodicWorktreeSweep` now **filters out live-checkout projects entirely** (`shared.isLiveCheckoutProject`) before handing the list to the three pruners (PL-live-checkout-reliability-hardening), keeping the operator's real checkout out of the GC decision surface rather than relying only on the pruners' path-equality + ownership-marker gates.
+The engine never calls `git reset --hard`, `git clean -fd`, or any other state-mutating command against the operator's checkout — not at spawn, not at cleanup, not on timeout, not on engine restart. The dispatch-scoped cleanup paths (`worktreePool.returnToPool`, `worktree-gc.gcDispatchWorktreeIfOrphan`, `_quarantineDirtyWorktree`) are naturally no-ops because `worktreePath` stays `null` end-to-end (`engine.js:1219`). The **periodic** worktree GC, however, is NOT `worktreePath`-gated — it derives its targets from `git worktree list --porcelain`, which for a live project returns the operator's *own* primary checkout. So `engine/cleanup.js#runPeriodicWorktreeSweep` now **filters out live-checkout projects entirely** (`shared.isLiveCheckoutProject`) before handing the list to the three pruners (PL-live-checkout-reliability-hardening), keeping the operator's real checkout out of the GC decision surface rather than relying only on the pruners' path-equality + ownership-marker gates. (The one **opt-in** exception is auto-stash — see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa) — which the operator explicitly enables and which the engine never reverses on the operator's behalf.)
+
+#### 2b. Opt-in auto-stash on dirty (W-mqtvnnj1000357fa)
+
+By default the dirty refusal above stands. When the operator opts in, the engine instead **stashes** the dirty changes so the dispatch can proceed without manual intervention:
+
+- **Enable** via per-project `project.liveCheckoutAutoStash: true` (takes priority) or the fleet-wide fallback `engine.liveCheckoutAutoStash: true` (default `false`). Resolution is `engine/live-checkout.js#resolveLiveCheckoutAutoStash` — an explicit per-project boolean wins; otherwise the engine value applies; otherwise `false`. Both are surfaced as Settings toggles (the per-project control is a tri-state *Use fleet default / On / Off* select; the fleet-wide one lives under **Settings → Worktrees**).
+- When enabled and the tree is dirty, `spawnAgent` delegates the whole flow to `engine/live-checkout.js#applyLiveCheckoutAutoStash`, which calls `performLiveCheckoutAutoStash` to run `git stash push --include-untracked -m "minions-auto-stash-<dispatchId>-<timestamp>"` in `project.localPath` (`--include-untracked` so the `??` files that `git status --porcelain` counts as dirty are parked too). The stash git command runs **outside any file lock**.
+- On stash **success** the helper re-runs `prepareLiveCheckout` (the tree is now clean), clears any stale `_pendingReason: 'live_checkout_dirty'` stamp (via the injected `clearDirtyStamp` callback), writes a `live-checkout-autostash-<wi-id>` inbox note with the stash name + manual-pop guidance, and returns `{ outcome:'stashed', liveResult }` so dispatch proceeds. If the re-preflight throws, it returns `{ outcome:'threw', error }` and `spawnAgent` fails the dispatch as `LIVE_CHECKOUT_FAILED`.
+- On stash **failure** the error is surfaced (logged, never swallowed), the helper returns `{ outcome:'unchanged', liveResult }`, and the dispatch falls through to the normal retry-once-then-fail dirty path above.
+- The engine **never pops the stash** automatically — that is the operator's choice. The stash name is logged and noted so the operator can `git stash pop` (or `git stash apply`) in `project.localPath` manually.
 
 #### 2a. Thrown pre-spawn failures are retryable, NOT dirty (#305)
 
@@ -82,6 +92,21 @@ Issue #226 only de-risked the *new-branch* path. The *existing-branch* `git chec
 
 **Branch existence is checked against `refs/heads/<branch>` specifically** (not a bare `rev-parse --verify <branch>`, which DWIM-resolves a same-named tag or remote ref and would silently detach HEAD).
 
+#### 3b. Worktree-conflict failures are non-retryable (W-mr28h2j2000y0de1)
+
+A second deterministic existing-branch checkout failure mode is a **worktree conflict**. When the target branch is *also* checked out in a **second worktree** somewhere else — a leftover from a prior isolated-worktree dispatch, a manually-created worktree, or a stale worktree left behind by a `checkoutMode` change — a plain `git checkout <branch>` inside the operator checkout refuses with git's own literal wording:
+
+```
+fatal: 'work/W-…' is already used by worktree at 'C:/office/worktrees/W-…'
+```
+
+Like the blob-fetch case this is **structural, not transient** — it does *not* clear on retry, ever, until a human or the engine removes/reassigns the other worktree. Root-caused live against production incident W-mr25v4je000c70c5, where the WI retried 4 times across 3 agents over ~40 minutes, failing identically each time while the blocking worktree (which held real, un-pushed operator WIP matching the WI's own file scope) sat untouched.
+
+- **Detection + typed result.** `prepareLiveCheckout` matches git's stable phrasing (`_isWorktreeConflictError`) and captures the conflicting worktree path (`_extractConflictingWorktreePath`), returning `{ ok:false, reason:'worktree-conflict', op, branch, conflictingWorktreePath, message, originalRef, originalRefType }` instead of throwing. The same no-half-switch HEAD restore (§3a) runs first, so the operator tree is left on its original ref.
+- **Auto-resolve attempt before refusing.** Review feedback on the original PR (calebt_microsoft) was that classifying the conflict as non-retryable doesn't actually *resolve* it — the operator still has to clean up by hand every time. `spawnAgent` now calls `_tryAutoResolveLiveCheckoutWorktreeConflict` first: it only removes the conflicting worktree when **all** of (1) the path resolves inside this project's configured `worktreeRoot` (the standard location for engine-created worktrees), (2) it carries the engine ownership marker (`shared.hasWorktreeOwnerMarker` — never touches a worktree a human created by hand), and (3) `shared.removeWorktree` itself agrees to remove it (which independently refuses a worktree with a **live** dispatch running inside it via `isWorktreePathLive`, and refuses real-repo-root / non-linked-worktree paths). When the removal succeeds, `prepareLiveCheckout` is retried once and, on success, the dispatch proceeds normally — no failure, no alert, no operator action needed. This resolves the common case (a stale worktree orphaned by a crashed dispatch or a `checkoutMode` change) fully automatically.
+- **Non-retryable classification (fallback).** When auto-resolve isn't safe (foreign/manual worktree, still-live dispatch, or removal failure) or the retried checkout still conflicts, `spawnAgent` completes the dispatch with the dedicated **`FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT`** (`'live-checkout-worktree-conflict'`; in `dispatch.js`'s `neverRetry` set) plus a `live-checkout-worktree-conflict-<wi-id>` inbox alert and a `_pendingReason: 'live_checkout_worktree_conflict'` stamp — instead of `LIVE_CHECKOUT_FAILED` (retryable) retry-storming to `maxRetries`.
+- **Recovery.** The alert names the conflicting path and offers two options: (1) if that worktree is stale, `git worktree remove <path>` (or `--force` if dirty — with an explicit warning that force discards its uncommitted changes) to free the branch; (2) if it holds real WIP, finish/commit/push directly from that worktree instead of re-dispatching this WI in live mode, or rename/retarget the branch. The engine only ever suggests `git worktree remove` against the **other** worktree — it never mutates `project.localPath` beyond the best-effort `checkout <originalRef>` undo, and the auto-resolve path above never touches a worktree the engine didn't create or that still has an agent running inside it.
+
 ### 4. No worktree pool, no per-WI subdirectory isolation
 
 Live mode shares one checkout per project. There is no pool to recycle, no quarantine directory, no per-WI subdirectory under the project root. The mutating-concurrency cap (Guarantee 1) is the only isolation mechanism: agents take turns in the same directory.
@@ -139,6 +164,26 @@ The core invariant holds end-to-end through restore: **the engine only ever swit
 
 Absent / `null` / `''` reads as `'worktree'` (the default) — explicit is preferred. A legacy `"worktreeMode": "live"` is still honored (and `"worktreeMode": "isolated"` reads as `'worktree'`), but new configs should use `checkoutMode`.
 
+### Enabling auto-stash on dirty (config.json)
+
+```jsonc
+{
+  // Fleet-wide fallback (default false) — applies to every live project that
+  // doesn't set its own override.
+  "engine": { "liveCheckoutAutoStash": true },
+  "projects": [{
+    "name": "android-aosp",
+    "checkoutMode": "live",
+    // Per-project override wins over engine.liveCheckoutAutoStash. Omit the
+    // field to inherit the fleet setting; `false` forces fail-on-dirty even
+    // when the fleet setting is true.
+    "liveCheckoutAutoStash": true
+  }]
+}
+```
+
+With auto-stash on, a dirty tree is `git stash push --include-untracked`'d before dispatch instead of refusing (see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa)). The engine never pops the stash — recover with `git stash pop` manually.
+
 ### Recovering from `live_checkout_dirty` refusal
 
 When dispatch is blocked by a dirty tree, the dashboard shows the work item as pending with `_pendingReason: 'live_checkout_dirty'` and an inbox alert lists the dirty files. (To make the engine *auto-recover* from this instead of refusing — at the cost of discarding the dirty changes — enable [opt-in auto-reset](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).) From the project checkout:
@@ -180,7 +225,7 @@ The engine has no opinion about local branches; this hygiene is the operator's r
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:
 
 - **No `auto` mode.** The choice between `worktree` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
-- **No auto-stash on dirty refusal.** The engine refuses and exits; it never `git stash`es to "make room" for a dispatch. Stashes silently mutate the operator's tree and conflate engine state with operator state. (The `liveCheckoutAutoReset` escape hatch — ON by default as of W-mqzbbhn2 — **discards** rather than stashes; set it to `false` per-project / fleet-wide to keep the terminal dirty-tree refusal. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
+- **No auto-stash on dirty refusal _by default_.** Out of the box the engine refuses and exits; it never `git stash`es to "make room" for a dispatch, because that silently mutates the operator's tree and conflates engine state with operator state. The operator can **opt in** per-project (`project.liveCheckoutAutoStash`) or fleet-wide (`engine.liveCheckoutAutoStash`) to auto-stash instead of refusing — see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa). Even then the engine never **pops** the stash on the operator's behalf. (The `liveCheckoutAutoReset` escape hatch — ON by default as of W-mqzbbhn2 — **discards** rather than stashes; set it to `false` per-project / fleet-wide to keep the terminal dirty-tree refusal. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
 - **No concurrent dispatches per project.** The cap is 1; raising it would require per-WI subdirectories, which live mode explicitly does not provide.
 - **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
 - **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.
@@ -194,10 +239,11 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
 | `engine/shared.js` — `resolveLiveCheckoutAutoReset` + `ENGINE_DEFAULTS.liveCheckoutAutoReset` | Pure precedence resolver (per-project boolean > fleet-wide engine default > false) + the fleet-wide default (ON as of W-mqzbbhn2). Gates the dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20). |
 | `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
-| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch` classification** for partial-clone hydration failures, **opt-in dirty auto-reset** (`git fetch origin` + `reset --hard origin/<branch>` + re-check + `live-checkout-autoreset-<wiId>` note when `liveCheckoutAutoReset` is on), **50 MB git maxBuffer** (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening; auto-reset + maxBuffer W-mqvejug6000eeb20). |
+| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch`/`worktree-conflict` classification** for partial-clone hydration failures and cross-worktree branch conflicts, **opt-in dirty auto-reset** (`git fetch origin` + `reset --hard origin/<branch>` + re-check + `live-checkout-autoreset-<wiId>` note when `liveCheckoutAutoReset` is on), **50 MB git maxBuffer** (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening; auto-reset + maxBuffer W-mqvejug6000eeb20). |
 | `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + **self-healing dirty recovery** (auto-commit agent WIP onto the agent branch) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (now also on unexpected restore errors) (P-d9e6b2c4; self-heal PL-live-checkout-reliability-hardening). |
+| `engine/live-checkout.js` — `resolveLiveCheckoutAutoStash`, `performLiveCheckoutAutoStash`, `applyLiveCheckoutAutoStash` | Opt-in auto-stash: resolver (per-project boolean wins, else `engine.liveCheckoutAutoStash`, else false) + `git stash push --include-untracked` runner returning `{ ok, stashMessage, error? }` (never throws on git failure) + the `applyLiveCheckoutAutoStash` orchestrator (stash → re-preflight → clear retry stamp → operator inbox note) returning a `{ outcome:'unchanged'\|'stashed'\|'threw' }` discriminant. Engine never auto-pops (W-mqtvnnj1000357fa). |
 | `engine/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared wrapper that fires the dispatch-end restore from a persisted dispatch record; used by `cli.js` + both `timeout.js` reaping paths so a restart-spanning live dispatch is never stranded (PL-live-checkout-reliability-hardening). |
-| `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
+| `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, delegates opt-in auto-stash to `applyLiveCheckoutAutoStash` on a dirty tree (W-mqtvnnj1000357fa), handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
 | `engine.js` — `spawnAgent` mid-op / detached-HEAD refusal block | Emits `LIVE_CHECKOUT_MID_OPERATION`, writes `live-checkout-blocked-<wi-id>` alert, stamps `_pendingReason: 'live_checkout_mid_operation'` / `'live_checkout_detached_head'` (P-c5a1f3b8). |
 | `engine.js` — `spawnAgent` originalRef persistence | Persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch` so restore survives an engine restart (P-c5a1f3b8). |
 | `engine.js` — `onAgentClose` live-mode restore wiring | Calls `restoreLiveCheckoutAtDispatchEnd` on every terminal result (P-d9e6b2c4). |
@@ -208,10 +254,11 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
 | `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` step-4 restore | `reset --hard HEAD` (not the index-leaking `checkout -- .`) + retried untracked removal + `liveTreeDirty` surfaced + `shared.removeWorktree` teardown (PL-live-checkout-reliability-hardening). |
 | `dashboard/js/settings.js` — checkoutMode dropdown + chip + `set-liveCheckoutAutoReset` fleet toggle | Operator-facing UI; the fleet-wide auto-reset toggle persists to `engine.liveCheckoutAutoReset` (per-project UI deferred — config.json only) (P-a3f9b207; auto-reset toggle W-mqvejug6000eeb20). |
-| `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring}.test.js` | Wiring and contract tests (P-a3f9b208). |
+| `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring,live-checkout-auto-stash}.test.js` | Wiring and contract tests (P-a3f9b208; auto-stash helpers W-mqtvnnj1000357fa). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` | Non-retryable refusal class for a mid-operation / detached-HEAD operator tree (in-progress merge/rebase/cherry-pick/revert/bisect or detached HEAD), distinct from the dirty-tree class. Emitted by `spawnAgent`'s mid-op / detached-HEAD refusal block (P-a7f3c1d9; wired P-c5a1f3b8). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH` | Non-retryable refusal class for an existing-branch checkout that could not hydrate the tree on a blobless GVFS partial clone (auth-less cache fetch, headless) — deterministic, so excluded from mechanical retry (PL-live-checkout-reliability-hardening). |
+| `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT` | Non-retryable refusal class for an existing-branch checkout that refused because the branch is already checked out in another worktree — structural, so excluded from mechanical retry (W-mr28h2j2000y0de1). |
 | `engine.js` — `_liveCheckoutDirtyAttempts` counter | Dedicated two-strike dirty memory (survives the discovery + retry `_pendingReason` scrubs that defeated #434); first dirty failure retries once, second fails non-retryably (PL-live-checkout-reliability-hardening). |
-| `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY`, `LIVE_CHECKOUT_MID_OPERATION`, and `LIVE_CHECKOUT_BLOB_FETCH` from mechanical retry. |
+| `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY`, `LIVE_CHECKOUT_MID_OPERATION`, `LIVE_CHECKOUT_BLOB_FETCH`, and `LIVE_CHECKOUT_WORKTREE_CONFLICT` from mechanical retry. |
 | `engine/timeout.js` header comment | Confirms no special live-mode kill handling. |

package/engine/ado-comment.js

@@ -34,7 +34,7 @@
  * changes) stay `active` so they block/notify the author.
  */
 
-const { buildMinionsCommentBody } = require('./comment-format');
+const { buildMinionsCommentBody, buildSkippedSkillSection } = require('./comment-format');
 const { acquireAdoToken } = require('./ado-token');
 
 const ADO_API_VERSION = '7.1';
@@ -108,6 +108,7 @@ async function _defaultAcquireToken() {
  * @param {string} args.kind           comment kind (marker)
  * @param {string} [args.workItemId]   originating work-item id (marker)
  * @param {object} [args.harnessUsed]  grounded harnessUsed record (folded into body)
+ * @param {object} [args.skillSkipped] skipped-project-skill record `{name, reason}` (folded into body, visible)
  * @param {number} [args.timeoutMs=30000]
  * @param {Function} [args.acquireToken]  () => Promise<string> — injectable token source
  * @param {Function} [args.fetchImpl=fetch] injectable fetch
@@ -123,6 +124,7 @@ async function postAdoPrComment({
   kind,
   workItemId,
   harnessUsed,
+  skillSkipped,
   resolved = false,
   timeoutMs = 30000,
   acquireToken = _defaultAcquireToken,
@@ -134,7 +136,7 @@ async function postAdoPrComment({
   _validatePrNumber(prNumber);
 
   // buildMinionsCommentBody validates marker fields and throws on bad input.
-  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed });
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed, skillSkipped });
 
   const token = await acquireToken();
   if (!token || typeof token !== 'string') {
@@ -184,6 +186,7 @@ module.exports = {
   // Re-export the neutral builder so ADO callers have a single import surface,
   // mirroring engine/gh-comment.js.
   buildMinionsCommentBody,
+  buildSkippedSkillSection,
   // Internal validators exported for tests.
   _validateOrgBase,
   _validateProject,

package/engine/cc-worker-pool.js

@@ -38,7 +38,10 @@
  *   - closeTab                → `session/cancel` if inflight, then kill proc
  *   - Idle > timeout       → kill proc (reaper sweep every 60 s; window is
  *                            ENGINE_DEFAULTS.ccWorkerIdleTimeoutMs, default
- *                            30 min, pushed in via setIdleTimeoutMs())
+ *                            30 min, pushed in via setIdleTimeoutMs()). A
+ *                            timeout of 0 is the "never idle-reap" sentinel
+ *                            (W-mr1qbj90000d30bd) — the warm worker is only
+ *                            ever killed by an explicit closeTab.
  *
  * Auth precheck: when `copilot --acp` exits before the initialize handshake
  * completes, surface
@@ -171,11 +174,18 @@ let _reaperTimer = null;
 const _reapedTabs = new Map();
 
 // Update the idle-reaper window at runtime. Called by dashboard.js on every
-// reloadConfig() with `engine.ccWorkerIdleTimeoutMs`. Ignores non-finite /
-// non-positive values so a config typo can't disable reaping or set a negative
-// window; the floor of 1000ms keeps a misconfigured tiny value from thrashing.
+// reloadConfig() with `engine.ccWorkerIdleTimeoutMs`. `0` is the explicit
+// "never idle-reap" sentinel (W-mr1qbj90000d30bd) — it sets the window to
+// Infinity so `_reapIdleTabs()` never kills a warm worker for inactivity;
+// only an explicit `closeTab` does. Ignores non-finite / negative values so a
+// config typo can't disable reaping or set a negative window; the floor of
+// 1000ms keeps a misconfigured tiny positive value from thrashing.
 function setIdleTimeoutMs(ms) {
   const n = Number(ms);
+  if (n === 0) {
+    _idleReaperMs = Infinity;
+    return _idleReaperMs;
+  }
   if (!Number.isFinite(n) || n <= 0) return _idleReaperMs;
   _idleReaperMs = Math.max(1000, n);
   return _idleReaperMs;
@@ -876,6 +886,8 @@ function _ensureReaper() {
 }
 
 function _reapIdleTabs() {
+  // W-mr1qbj90000d30bd — idle-reap disabled entirely (sentinel: 0 → Infinity).
+  if (_idleReaperMs === Infinity) return;
   const now = _internals.now();
   for (const [tabId, worker] of [..._tabs]) {
     if (worker.inflight) continue;

package/engine/cli.js

@@ -250,7 +250,7 @@ const CLI_COMMAND_DOCS = Object.freeze({
   'mcp-sync': { args: '',                      summary: 'Print harness propagation diagnostic (same source as `minions doctor --harness`; read-only, no writes)' },
   doctor:     { args: '[--harness]',           summary: 'Check prerequisites and runtime health (--harness: print harness propagation diagnostic)' },
   config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
-  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--resolved] [--harness-file <f>|--harness-json <j>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh (ADO: --resolved posts pre-closed)' },
+  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--resolved] [--harness-file <f>|--harness-json <j>] [--skill-skipped-file <f>|--skill-skipped-json <j>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh (ADO: --resolved posts pre-closed)' },
   bridge:     { args: 'status|health|enable|disable',         summary: 'Constellation bridge: toggle and inspect the read-only cross-repo feed' },
 });
 
@@ -475,6 +475,49 @@ function resolveHarnessUsedForComment(flags) {
   return shared.groundHarnessUsed(parsed, propagated);
 }
 
+// resolveSkillSkippedForComment(flags) — W-mr287sc0000uc214. Turn the
+// `minions pr comment` skip flags into a canonical `{name, reason}` record for
+// the posters' `skillSkipped` param (engine/gh-comment.js / engine/ado-comment.js),
+// which fold it via buildMinionsCommentBody -> buildSkippedSkillSection into a
+// VISIBLE callout in the same comment as the verdict.
+//
+// Source precedence mirrors the harness resolver: `--skill-skipped-file <path>`
+// (JSON on disk) wins over the inline `--skill-skipped-json <json>`; neither
+// supplied -> returns undefined so the comment body is byte-identical to today
+// (no callout). Read/parse failures are HARD errors (process.exit(2)). Accepts
+// the raw `{name, reason}` shape or a `meta.skill` / `meta.review` wrapper; a
+// record with no non-empty `name` yields undefined (nothing to surface).
+function resolveSkillSkippedForComment(flags) {
+  const fileArg = flags['skill-skipped-file'];
+  const jsonArg = flags['skill-skipped-json'];
+
+  let raw;
+  if (fileArg !== undefined) {
+    try {
+      raw = fs.readFileSync(fileArg, 'utf8');
+    } catch (e) {
+      console.error(`error: could not read --skill-skipped-file ${fileArg}: ${e.message}`);
+      process.exit(2);
+    }
+  } else if (jsonArg !== undefined) {
+    raw = String(jsonArg);
+  } else {
+    return undefined;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    const src = fileArg !== undefined ? `--skill-skipped-file ${fileArg}` : '--skill-skipped-json';
+    console.error(`error: invalid JSON in ${src}: ${e.message}`);
+    process.exit(2);
+  }
+
+  const { _extractSkillSkipped } = require('./comment-format');
+  return _extractSkillSkipped(parsed) || undefined;
+}
+
 const commands = {
   start(...startArgs) {
     // Apply --cli / --model fleet flags before any engine wiring touches
@@ -2044,6 +2087,10 @@ const commands = {
       console.log('  --harness-file <path>   JSON file with the { skills, mcpServers, commands, docs } record (wins over --harness-json)');
       console.log('  --harness-json <json>   same record inline as a JSON string');
       console.log('  --dispatch-id <id>      grounding manifest override (else basename of $MINIONS_COMPLETION_REPORT)');
+      console.log('');
+      console.log('Skipped in-scope project skill (folded in as a VISIBLE "⚠️ Skipped project skill" callout):');
+      console.log('  --skill-skipped-file <path>   JSON file with the { name, reason } skip record (wins over --skill-skipped-json)');
+      console.log('  --skill-skipped-json <json>   same record inline as a JSON string (also accepts a meta.skill/meta.review wrapper)');
       console.log('  --resolved              (ADO only) post the thread pre-resolved/closed — for non-actionable FYI/praise notes');
       console.log('');
       console.log('Posts a PR comment with the hidden minions marker, the collapsible');
@@ -2117,6 +2164,12 @@ const commands = {
     // -> undefined -> body byte-identical to today.
     const harnessUsed = resolveHarnessUsedForComment(flags);
 
+    // W-mr287sc0000uc214 — thread the skipped-in-scope-project-skill self-report
+    // into both posters so it's surfaced as a VISIBLE callout in the same comment
+    // as the verdict (not buried in the completion-report JSON). Absent flags
+    // -> undefined -> body byte-identical to today.
+    const skillSkipped = resolveSkillSkippedForComment(flags);
+
     // ── Azure DevOps: <prNumber> --host ado --ado-org --ado-project --repo-id ──
     if (isAdo) {
       const [prNumberRaw] = positional;
@@ -2136,7 +2189,7 @@ const commands = {
       const orgBase = flags['org-base'] || `https://dev.azure.com/${adoOrg}`;
       const adoComment = require('./ado-comment');
       adoComment.postAdoPrComment({
-        orgBase, project, repositoryId, prNumber, body, agentId, kind, workItemId, harnessUsed,
+        orgBase, project, repositoryId, prNumber, body, agentId, kind, workItemId, harnessUsed, skillSkipped,
         resolved: flags.resolved === true,
       }).then((result) => {
         if (result && result.threadId) {
@@ -2175,7 +2228,7 @@ const commands = {
 
     try {
       const result = ghComment.postPrComment({
-        repo, prNumber, body, agentId, kind, workItemId, harnessUsed,
+        repo, prNumber, body, agentId, kind, workItemId, harnessUsed, skillSkipped,
       });
       if (result.output) console.log(result.output);
     } catch (e) {
@@ -2316,6 +2369,8 @@ module.exports = {
   _dispatchSessionBranch: dispatchSessionBranch,
   // P-7a3c9e21 — harness-flag resolver exported for CLI-threading tests.
   _resolveHarnessUsedForComment: resolveHarnessUsedForComment,
+  // W-mr287sc0000uc214 — skipped-project-skill flag resolver exported for tests.
+  _resolveSkillSkippedForComment: resolveSkillSkippedForComment,
   // W-mpcyvff6000pf828 (#2653) — heartbeat writer + factory exported for tests
   _writeHeartbeatNow: writeHeartbeatNow,
   _createHeartbeatInterval: createHeartbeatInterval,

package/engine/comment-format.js

@@ -36,6 +36,13 @@ const HARNESS_KINDS = [
 const HARNESS_SUMMARY_ICON = '\u{1F9F0}'; // 🧰
 const HARNESS_WARN_ICON = '⚠️'; // ⚠️
 
+// W-mr287sc0000uc214 — the visible "skipped project skill" callout. The label is
+// a stable literal so buildMinionsCommentBody can dedupe (never stack two
+// callouts) and tests can assert on it. Clamps mirror the harness field caps.
+const SKILL_SKIPPED_LABEL = '**Skipped project skill:**';
+const SKILL_SKIPPED_MAX_NAME_LEN = 200;
+const SKILL_SKIPPED_MAX_REASON_LEN = 1000;
+
 // Canonical Minions site URL. shared-rules.md ("Brand link (MANDATORY)") requires
 // the human-readable "Minions" mention in a PR/ADO comment to render as a markdown
 // hyperlink to this destination. Keep this in sync with the literal in
@@ -119,6 +126,64 @@ function buildHarnessUsedSection(harnessUsed) {
     + `${lines.join('\n')}${legend}\n\n</details>`;
 }
 
+/**
+ * Extract a canonical `{ name, reason }` skip record from a self-reported skip
+ * value. Accepts the raw `{ name, reason }` shape directly, or a `meta` wrapper
+ * that carries it — `meta.skill` (`{ skipped: { name, reason } }`) or
+ * `meta.review` (`{ skillSkipped: { name, reason } }`) — so callers can pass the
+ * completion-report block verbatim. Returns null when no non-empty `name` is
+ * present so callers treat "no skip" as a single falsy case.
+ * @param {*} input
+ * @returns {{name:string, reason:string}|null}
+ */
+function _extractSkillSkipped(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  let node = input;
+  if (input.skipped && typeof input.skipped === 'object' && !Array.isArray(input.skipped)) {
+    node = input.skipped; // meta.skill shape
+  } else if (input.skillSkipped && typeof input.skillSkipped === 'object' && !Array.isArray(input.skillSkipped)) {
+    node = input.skillSkipped; // meta.review shape
+  }
+  const name = typeof node.name === 'string' ? node.name.trim() : '';
+  if (!name) return null;
+  const reason = typeof node.reason === 'string' ? node.reason.trim() : '';
+  return { name, reason };
+}
+
+/**
+ * Render the "skipped project skill" self-report as a VISIBLE Markdown
+ * blockquote callout (W-mr287sc0000uc214), e.g.:
+ *   > ⚠️ **Skipped project skill:** `FMF-review-context` — small 2-file diff…
+ *
+ * A review/fix agent may self-report that it intentionally skipped an available,
+ * in-scope project (review) skill via `meta.review.skillSkipped` /
+ * `meta.skill.skipped` (shape `{name, reason}`). That skip used to live ONLY in
+ * the completion-report JSON — invisible to a human reading the PR before merge.
+ * This is a sibling of buildHarnessUsedSection (same neutral chokepoint, same
+ * `_clean` hygiene) but a VISIBLE blockquote rather than a collapsed <details>:
+ * the whole point is that a human reviewing the PR sees the skip rationale in the
+ * same comment as the APPROVE / REQUEST_CHANGES verdict, before merge.
+ *
+ * Deliberately platform-NEUTRAL Markdown so the GitHub and ADO posters fold in a
+ * byte-identical callout — there is no second renderer to drift. Accepts either
+ * the raw `{name, reason}` record or a `meta.skill` / `meta.review` wrapper.
+ *
+ * Returns '' when the record is absent/malformed (no skip name), so callers can
+ * append it unconditionally without emitting a stray callout — reports without
+ * meta.review.skillSkipped / meta.skill.skipped render identically to today.
+ *
+ * @param {object|null} skillSkipped `{name, reason}` or a meta.skill/meta.review wrapper
+ * @returns {string} '' when empty, else a one-line `> ⚠️ …` blockquote
+ */
+function buildSkippedSkillSection(skillSkipped) {
+  const parsed = _extractSkillSkipped(skillSkipped);
+  if (!parsed) return '';
+  const name = _clean(parsed.name).slice(0, SKILL_SKIPPED_MAX_NAME_LEN);
+  const reasonClean = parsed.reason ? _clean(parsed.reason).slice(0, SKILL_SKIPPED_MAX_REASON_LEN) : '';
+  const tail = reasonClean ? ` — ${reasonClean}` : ''; // em dash
+  return `> ${HARNESS_WARN_ICON} ${SKILL_SKIPPED_LABEL} \`${name}\`${tail}`;
+}
+
 // ── Minions marker + neutral comment-body builder ───────────────────────────
 //
 // The hidden HTML-comment marker and the body composition (marker + harness
@@ -188,15 +253,26 @@ function _buildMarker({ agentId, kind, workItemId }) {
  * Idempotency: if `body` already starts with a minions marker it is returned
  * with the harness/brand transforms applied but no second marker prepended.
  *
- * @param {{agentId:string, kind:string, workItemId?:string, body?:string, harnessUsed?:object}} args
+ * @param {{agentId:string, kind:string, workItemId?:string, body?:string, harnessUsed?:object, skillSkipped?:object}} args
  * @returns {string} the final comment body
  */
-function buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed }) {
+function buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed, skillSkipped }) {
   // Validate the inputs even when the body is pre-marked, so callers can't
   // silently bypass validation by pre-marking their body.
   _validateMarkerInputs({ agentId, kind, workItemId });
   let safeBody = body == null ? '' : String(body);
 
+  // Fold in the VISIBLE "skipped project skill" callout (W-mr287sc0000uc214)
+  // BEFORE the collapsed harness section so a human sees the skip rationale in
+  // the same comment as the verdict — not buried in a <details> or reachable
+  // only via a separate API call. Dedup on the stable label so a re-marked body
+  // already carrying the callout doesn't stack a second one. Absent/malformed
+  // skip → '' → no-op (byte-identical to today).
+  const skipSection = buildSkippedSkillSection(skillSkipped);
+  if (skipSection && !safeBody.includes(SKILL_SKIPPED_LABEL)) {
+    safeBody = safeBody ? `${safeBody}\n\n${skipSection}` : skipSection;
+  }
+
   // Fold the grounded harness-usage digest in as a collapsible <details>
   // section. Append at the END so it survives the marker-idempotency path;
   // dedup on the summary line so a re-marked body that already carries the
@@ -232,6 +308,7 @@ function parseMinionsMarker(body) {
 
 module.exports = {
   buildHarnessUsedSection,
+  buildSkippedSkillSection,
   linkifyBrandTrailer,
   MINIONS_BRAND_URL,
   // Neutral marker + body builder (consumed by gh-comment.js and ado-comment.js).
@@ -247,4 +324,7 @@ module.exports = {
   _validateMarkerInputs,
   // Exported for tests / advanced callers that want to mirror the kind mapping.
   HARNESS_KINDS,
+  // W-mr287sc0000uc214 — skipped-project-skill callout helpers.
+  _extractSkillSkipped,
+  SKILL_SKIPPED_LABEL,
 };