@yemi33/minions 0.1.2323 → 0.1.2325

package/dashboard/js/fre.js

@@ -294,7 +294,6 @@ function renderCcHint() {
       'line-height:1.5',
     ].join(';');
     document.body.appendChild(mount);
-    // eslint-disable-next-line no-unsanitized/property -- reason: static string literal — no user-controlled data is interpolated
     mount.innerHTML =
       '<div id="cc-hint-arrow" style="position:absolute;top:-7px;width:12px;height:12px;background:var(--surface);border-left:1px solid var(--blue);border-top:1px solid var(--blue);transform:rotate(45deg)"></div>' +
       '<div style="font-weight:700;color:var(--blue);margin-bottom:4px">&#x1F44B; Start here</div>' +

package/dashboard.js

@@ -28,10 +28,13 @@ const v8 = require('v8');
 const llm = require('./engine/llm');
 const { resolveRuntime } = require('./engine/runtimes');
 
-// Dashboard version stamp — captured at module load so it reflects the code actually running
+// Dashboard version stamp — captured at module load so it reflects the code actually running.
+// codeCommit is read via _readGitHeadShort (defined below — function declarations
+// are hoisted, so the call here resolves fine) instead of spawning a `git`
+// subprocess; see that function's doc comment for the rationale.
 const _dashboardVersion = {
   codeVersion: (() => { try { return require('./package.json').version; } catch {} try { return require('@yemi33/minions/package.json').version; } catch {} return null; })(),
-  codeCommit: (() => { try { return require('child_process').execSync('git rev-parse --short HEAD', { cwd: __dirname, encoding: 'utf8', timeout: 5000, windowsHide: true }).trim(); } catch { return null; } })(),
+  codeCommit: _readGitHeadShort(__dirname).commit,
   startedAt: new Date().toISOString(),
   pid: process.pid,
 };
@@ -2252,13 +2255,16 @@ let _diskVersionCacheTs = 0;
 const DISK_VERSION_TTL = 60000; // re-check every 60s
 
 // Read the short HEAD commit by parsing `.git` directly — NO `git` subprocess.
-// The old `execSync('git rev-parse --short HEAD', { timeout: 5000 })` spawned a
-// synchronous child process on the dashboard's single event loop; under
-// concurrent agent git activity (worktree add/merge holding repo locks) that
-// subprocess could take its full 5s timeout, and because getDiskVersion runs
-// inside the /api/status rebuild, every in-flight poll blocked for that whole
-// window. Reading `.git/HEAD` + the resolved ref (loose ref, then packed-refs
-// fallback) is a couple of tiny synchronous file reads with zero process spawn.
+// The old `execSync('git rev-parse --short HEAD', { timeout: 5000 })` (both here
+// and in the `_dashboardVersion.codeCommit` init near the top of this file)
+// spawned a synchronous child process on the dashboard's single event loop;
+// under concurrent agent git activity (worktree add/merge holding repo locks)
+// that subprocess could take its full 5s timeout, and because getDiskVersion
+// runs inside the /api/status rebuild, every in-flight poll blocked for that
+// whole window. Reading `.git/HEAD` + the resolved ref (loose ref, then
+// packed-refs fallback) is a couple of tiny synchronous file reads with zero
+// process spawn. Function declarations are hoisted, so `_dashboardVersion`'s
+// module-load-time init above can call this even though it's defined here.
 // Returns { commit, isGitRepo }: commit is the 7-char short SHA or null.
 function _readGitHeadShort(repoDir) {
   try {

package/docs/command-center.md

@@ -31,7 +31,7 @@ Canonical envelope (`_buildCcErrorEnvelope` in `dashboard.js`):
 
 **No auto-retry policy.** The backend never re-spawns the LLM after an error envelope. The client never silently resends the user's turn. Retry is a single-click manual action — guards against silent budget burn on `budget-exceeded`, infinite loops on `auth-failure`, and accidental re-charges on `context-limit`. The 429 + reconnect paths (rate-limited fetch retry, SSE reconnect-after-disconnect) remain — those are transport-level, not error-envelope-level.
 
-**Session-reset notices (`sessionReset` / `sessionResetReason`).** The streaming `done` event can carry `sessionReset: true` with a `sessionResetReason` of `promptChanged` (Minions updated its CC prompt template), `runtimeChanged` (CC runtime switched), or `idleReap` (W-mr0qs0vw — the persistent `copilot --acp` worker was killed by the idle reaper after `engine.ccWorkerIdleTimeoutMs` of inactivity, so the next message cold-spawns a fresh session with no memory). Both classic (`dashboard/js/command-center.js`) and slim (`dashboard/slim/js/command-send.js` + `chat.js#appendSystemNotice`) render a centered, muted system notice; for `idleReap` the text is "Context window cleared after inactivity — fresh session started." The idle-reap flag is a one-shot drained per turn via `ccWorkerPool.consumeIdleReapNotice(tabId)`.
+**Session-reset notices (`sessionReset` / `sessionResetReason`).** The streaming `done` event can carry `sessionReset: true` with a `sessionResetReason` of `promptChanged` (Minions updated its CC prompt template), `runtimeChanged` (CC runtime switched), or `idleReap` (W-mr0qs0vw — the persistent `copilot --acp` worker was killed by the idle reaper after `engine.ccWorkerIdleTimeoutMs` of inactivity, so the next message cold-spawns a fresh session with no memory). Both classic (`dashboard/js/command-center.js`) and slim (`dashboard/slim/js/command-send.js` + `chat.js#appendSystemNotice`) render a centered, muted system notice; for `idleReap` the text is "Context window cleared after inactivity — fresh session started." The idle-reap flag is a one-shot drained per turn via `ccWorkerPool.consumeIdleReapNotice(tabId)`. **`ccWorkerIdleTimeoutMs: 0`** is an explicit "never idle-reap" sentinel (W-mr1qbj90000d30bd) — it bypasses the normal `[60000, 28800000]` clamp, maps to an `Infinity` window in `cc-worker-pool.js#setIdleTimeoutMs`, and the warm worker then only dies on an explicit `closeTab`. Settings page exposes this as the "Never idle-reap CC workers" toggle.
 
 ## Image attachments (PL-cc-image-attachments)
 

package/docs/engine-restart.md

@@ -54,6 +54,10 @@ To kill them now, run: node engine.js kill
 
 If an agent is killed as an orphan and the work item retries, cooldowns use exponential backoff (2^failures, max 8x) to prevent spam-retrying broken tasks.
 
+### 5. Crash-Loop Counter + Alert (W-mr2azk6i000y06e0)
+
+The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/supervisor.js#checkEngine` (dead-PID), `engine/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
+
 ## Safe Restart Pattern
 
 ```bash

package/docs/live-checkout-mode.md

@@ -32,7 +32,7 @@ Implementation: `engine.js` builds a `liveProjectsInUse` set from the active dis
 
 Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status --porcelain` from `project.localPath`. Any output (staged, unstaged, untracked) **returns** an explicit `{ ok:false, reason:'dirty', dirtyFiles:[…] }` result (it does NOT throw), which refuses the dispatch immediately:
 
-- Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically). **Reserved for this confirmed-dirty result only** — a thrown helper/git error is `LIVE_CHECKOUT_FAILED`, see below (#305).
+- Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically). **Reserved for this confirmed-dirty result only** — a thrown helper/git error is `LIVE_CHECKOUT_FAILED`, see below (#305). **Auto-cleanup exception (W-mqzmkoqt000hbca2, #582):** when `liveCheckoutAutoReset` or `liveCheckoutAutoStash` is enabled (per-project or fleet-wide), `spawnAgent` treats the dirty refusal as retryable instead — the engine re-cleans the tree on every attempt, so the two-strike cap below is skipped and the dispatch keeps retrying up to the normal `maxRetries` cap. The `dispatch.js` `neverRetry` entry is kept only as a defensive fallback for callers that omit the explicit `agentRetryable` override.
 - Inbox alert written via `dispatch.writeInboxAlert('live-checkout-dirty-<wi-id>', body)`. The body lists the dirty files verbatim from `git status --porcelain`.
 - 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>`.
@@ -69,6 +69,9 @@ This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted c
 - **Fleet-wide:** Dashboard → Settings → `Live-checkout auto-reset (fleet-wide)` (`engine.liveCheckoutAutoReset`).
 - **Per-project override:** set `liveCheckoutAutoReset: true|false` on the project object in `config.json` (see the config snippet under *Enabling live mode*). A per-project boolean overrides the fleet-wide default for that project. *(Per-project Settings-UI persistence is deferred — the per-project override is config.json-only for now.)*
 
+#### 2c. Stale `.git/index.lock` self-heal (W-mr3tayu4)
+
+Before any preflight git command runs, `prepareLiveCheckout` calls the shared, age-gated `shared.removeStaleIndexLock(localPath)` to clear a leftover `.git/index.lock` from a crashed/killed git process. Live mode never resets/cleans the operator tree, so nothing else would clear it, and — since `LIVE_CHECKOUT_FAILED` is retryable — every automatic retry used to hit the same stale lock and fail identically forever until an operator deleted it by hand. The remover only touches locks older than 5 minutes, so a lock held by a currently-running git process is never removed out from under it. `engine.js`'s own worktree-mode lock cleanup now delegates to the same shared helper.
 
 ### 3. No auto-pull, no `--force`, no fast-forward
 
@@ -275,6 +278,6 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `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.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) — **unless** `liveCheckoutAutoReset`/`liveCheckoutAutoStash` is enabled, in which case the two-strike cap is skipped entirely and the dirty failure stays retryable up to `maxRetries` (W-mqzmkoqt000hbca2, #582). |
 | `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/docs/plan-lifecycle.md

@@ -69,6 +69,10 @@ When all PRD items reach `done` or `failed` status, `checkPlanCompletion()` fire
 3. **PR work item** created for shared-branch plans (to merge the feature branch)
 4. **PRD status** persisted as `completed` with `_completionNotified`; files stay active until manual archive
 
+`checkPlanCompletion()` also **self-heals a stale `completed` PRD**: if a completed plan later gains an unmaterialized item or one of its items regresses off a terminal status, the PRD is reverted to `active` (status flipped, `_completionNotified` cleared) so the materializer recreates the missing work item and the normal completion flow can run again.
+
+**Separate lighter-weight path — `advancePrdStatusOnAllItemsDone()` (P-d7e8f9a1).** Called at the end of `syncPrdFromPrs` on the PR-poll cadence, this independently advances a PRD's top-level `status` to `completed` once every `missing_features` item has both (1) a work item in a `DONE_STATUSES` state and (2) its linked PR merged (or no linked PR, for non-code items). It skips frozen PRDs (`paused`, `rejected`, `awaiting-approval`, `completed`, `archived` — `_PRD_FROZEN_STATUSES`) and writes idempotently via `mutateJsonFileLocked` + `skipWriteIfUnchanged`. Unlike `checkPlanCompletion()`, it does not create the verify task, completion summary, or PR work item — those still only come from the `checkPlanCompletion()` path above.
+
 ## Verification Task
 
 The verification task (`planItemId: "VERIFY"`) is the final step. It:
@@ -118,7 +122,7 @@ The verify agent does not call `archivePlan()`. After the testing guide and any
 
 Manual archive behavior:
 
-1. For PRD JSON files, the dashboard archives them **in-place** in `prd/` — the file is not moved. The JSON is stamped with `archived: true`, `status: "archived"`, and `archivedAt` (Phase 10 step 4.2b). The `.backup` sidecar is left intact since the file keeps its canonical path.
+1. For PRD JSON files, the dashboard archives them **in-place** in `prd/` — the file is not moved. The JSON is stamped with `archived: true`, `status: "archived"`, and `archivedAt` (Phase 10 step 4.2b). **No `.backup` sidecar is written or restored for any `prd/*.json`** — Phase 10 step 4.3 dropped the PRD backup/restore lifecycle entirely (root-level PRDs used to get one to survive the now-retired rename race; SQL is canonical, so a stale `.backup` is pure resurrection fuel, not a safety net).
 2. If the PRD has `source_plan`, the matching `plans/<source>.md` is moved to `plans/archive/<source>.md`.
 3. Pending or queued work items linked to the archived PRD are cancelled with `_cancelledBy: "plan-archived"`; completed work items remain as history.
 4. Plan worktrees are cleaned up by the archive handler/lifecycle cleanup path.

package/package.json

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