@yemi33/minions 0.1.2301 → 0.1.2303

package/dashboard.js

@@ -4263,12 +4263,25 @@ function _resetPreambleCache() {
   _preambleCacheTs = 0;
 }
 
+// Compact one-word-ish label for a project's effective dispatch checkout mode,
+// for CC state surfaces (preamble + refresh). 'worktree' | 'live' |
+// 'hybrid (live-validation: <type>)' so CC can see at a glance whether a project
+// authors in isolated worktrees, runs in-place on the operator tree, or splits
+// the two (coding → worktree, validation type → live). See resolveCheckoutMode.
+function _projectCheckoutModeLabel(p) {
+  const mode = shared.resolveCheckoutMode(p);
+  if (mode === 'live' && p && p.liveValidation && p.liveValidation.type) {
+    return `hybrid (live-validation: ${p.liveValidation.type})`;
+  }
+  return mode;
+}
+
 function buildCCStatePreamble() {
   const now = Date.now();
   if (_preambleCache && now - _preambleCacheTs < PREAMBLE_TTL) return _preambleCache;
   // Lightweight snapshot — just enough to orient. Use tools for details.
   const agents = getAgents().map(a => `- ${a.name} (${a.id}): ${a.status}${a.currentTask ? ' — ' + a.currentTask.slice(0, 60) : ''}`).join('\n');
-  const projects = PROJECTS.map(p => `- ${p.name}: ${p.localPath}`).join('\n');
+  const projects = PROJECTS.map(p => `- ${p.name}: ${p.localPath} [${_projectCheckoutModeLabel(p)}]`).join('\n');
 
   const dq = getDispatchQueue();
   const active = (dq.active || []).map(d => `- ${d.agentName || d.agent}: ${(d.task || '').slice(0, 50)}`).join('\n') || '(none)';
@@ -4340,7 +4353,7 @@ function buildCCStateRefresh() {
   // Agent roster carries the current task too — without it a resumed session
   // sees only that an agent is "busy", never *what* it is busy with.
   const agents = getAgents().map(a => `- ${a.name}: ${a.status}${a.currentTask ? ' — ' + a.currentTask.slice(0, 50) : ''}`).join('\n');
-  const projects = PROJECTS.map(p => `- ${p.name} (${p.repo || p.localPath})`).join('\n');
+  const projects = PROJECTS.map(p => `- ${p.name} (${p.repo || p.localPath}) [${_projectCheckoutModeLabel(p)}]`).join('\n');
 
   // MCP servers — just names + source for orientation
   let mcpLine = '(none discovered)';
@@ -11337,6 +11350,31 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             }
             // Drop the legacy field so a migrated project never carries both.
             delete proj.worktreeMode;
+            // Defensive cleanup: liveValidation is only honored under
+            // checkoutMode:'live'. If this update moves the project OFF live,
+            // drop any stale hybrid block so resolveCheckoutMode doesn't have to
+            // warn-and-ignore an orphaned liveValidation on every resolve.
+            if (shared.resolveCheckoutMode(proj) !== 'live') {
+              delete proj.liveValidation;
+            }
+          }
+          // Hybrid live-validation block (per-project). Only meaningful when the
+          // resolved checkout mode is 'live' — runs AFTER the checkoutMode block
+          // above so resolveCheckoutMode(proj) reflects the intended final mode.
+          // Empty string / null clears the override; any other value flows
+          // through shared.validateLiveValidation which throws HTTP 400 on
+          // malformed input or when checkoutMode !== 'live'. Absent key leaves
+          // any existing block untouched (so a Settings save that omits the
+          // field never silently drops a configured hybrid project).
+          if (Object.prototype.hasOwnProperty.call(update, 'liveValidation')) {
+            const rawLv = update.liveValidation;
+            if (rawLv === '' || rawLv === null || rawLv === undefined) {
+              delete proj.liveValidation;
+            } else {
+              const validatedLv = shared.validateLiveValidation(rawLv, { checkoutMode: shared.resolveCheckoutMode(proj) });
+              if (validatedLv === undefined) delete proj.liveValidation;
+              else proj.liveValidation = validatedLv;
+            }
           }
         }
       }
@@ -14301,7 +14339,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Settings
     { method: 'GET', path: '/api/settings', desc: 'Return current engine + claude + routing config', handler: handleSettingsRead },
-    { method: 'POST', path: '/api/settings', desc: 'Update engine + claude + agent + projects config', params: 'engine?, claude?, agents?, projects?', handler: handleSettingsUpdate },
+    { method: 'POST', path: '/api/settings', desc: 'Update engine + claude + agent + projects config', params: 'engine?, claude?, agents?, projects? (per-project: checkoutMode, liveValidation, mainBranch, workSources)', handler: handleSettingsUpdate },
     { method: 'POST', path: '/api/settings/routing', desc: 'Update routing.md', params: 'content', handler: handleSettingsRouting },
     { method: 'POST', path: '/api/settings/reset', desc: 'Reset engine + claude + agent settings to defaults', handler: handleSettingsReset },
 
@@ -14512,6 +14550,7 @@ module.exports = {
   _resolveScheduleProjectValue: resolveScheduleProjectValue,
   _collectArchivedWorkItems: collectArchivedWorkItems,
   buildCCStatePreamble,
+  _projectCheckoutModeLabel,
   buildCCStateRefresh,
   _resetRefreshCache,
   _routesAsMeta,

package/engine/shared.js

@@ -2757,6 +2757,47 @@ function validateCheckoutMode(value) {
   return value;
 }
 
+// Validate + normalize a per-project `liveValidation` block (hybrid mode).
+// Hybrid = checkoutMode:'live' + liveValidation:{ type, autoDispatch }: coding
+// work items author in isolated worktrees (escaping the live cap) while only
+// work items whose type === liveValidation.type run in-place on the live
+// checkout. See resolveCheckoutMode (which routes per work-item type) and
+// docs/live-checkout-mode.md.
+//
+// Returns:
+//   - undefined → caller should clear the field (empty / null / '' input)
+//   - { type, autoDispatch? } normalized object on success
+// Throws HTTP 400 (via _httpError) on malformed input, or when the effective
+// checkout mode is not 'live' (liveValidation is meaningless without it — it is
+// silently ignored at resolve time, so we refuse to persist a misconfiguration).
+//
+// `opts.checkoutMode` is the project's effective (resolved) checkout mode; pass
+// shared.resolveCheckoutMode(project) AFTER any checkoutMode update has been
+// applied so the gate sees the intended final mode.
+function validateLiveValidation(value, opts) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw _httpError(400, 'Invalid liveValidation: must be an object { type, autoDispatch }.');
+  }
+  const checkoutMode = opts && opts.checkoutMode;
+  if (checkoutMode !== CHECKOUT_MODES.LIVE) {
+    throw _httpError(400, 'liveValidation requires checkoutMode "live" (hybrid mode). Set checkoutMode to "live" first, or clear liveValidation.');
+  }
+  const type = typeof value.type === 'string' ? value.type.trim() : '';
+  if (!type) {
+    throw _httpError(400, 'Invalid liveValidation: "type" is required and must be a non-empty string — the work-item type that runs on the live checkout (e.g. "build-and-test").');
+  }
+  const out = { type };
+  // autoDispatch (optional): when true, lifecycle auto-creates a validation WI
+  // of `type` after each coding WI completes with a PR (engine/lifecycle.js
+  // autoDispatchLiveValidationWi). Coerce to a strict boolean; absent leaves it
+  // off so the operator opts in explicitly.
+  if (Object.prototype.hasOwnProperty.call(value, 'autoDispatch')) {
+    out.autoDispatch = !!value.autoDispatch;
+  }
+  return out;
+}
+
 // ── Engine Defaults ─────────────────────────────────────────────────────────
 // Single source of truth for engine configuration defaults.
 // Used by: engine.js, minions.js (init). config.template.json only has the project schema.
@@ -9192,6 +9233,7 @@ module.exports = {
   validateProjectPath,
   CHECKOUT_MODES,
   validateCheckoutMode,
+  validateLiveValidation,
   resolveCheckoutMode,
   isLiveCheckoutProject,
   resolveLiveCheckoutAutoReset,

package/engine.js

@@ -4168,6 +4168,12 @@ async function spawnAgent(dispatchItem, config) {
     // re-attached on next start via PID file + live-output.log. We do NOT call
     // proc.unref(): the engine still tracks exit while it's alive; detached
     // only kicks in when the engine itself goes away.
+    // Expose the engine-resolved working directory so playbooks (setup, qa-*,
+    // shared-rules) can read $MINIONS_AGENT_CWD as the authoritative worktree /
+    // live-checkout root instead of guessing from pwd. Mirrors the spawn `cwd`
+    // exactly — the agent's process already starts here, but cd-ing around or
+    // sub-shells can drift, so the env var is the stable anchor.
+    childEnv.MINIONS_AGENT_CWD = cwd;
     proc = runFile(process.execPath, spawnArgs, {
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -4499,6 +4505,9 @@ async function spawnAgent(dispatchItem, config) {
           || dispatchItem.meta?.keep_processes_skip_workdir_check) {
         childEnv.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK = '1';
       }
+      // Re-expose the engine-resolved cwd on steering resume (matches the
+      // initial spawn path) so $MINIONS_AGENT_CWD stays valid across resumes.
+      childEnv.MINIONS_AGENT_CWD = cwd;
       let resumeProc;
       try {
         // detached so the resumed steering session also survives engine death (matches initial spawn)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2301",
+  "version": "0.1.2303",
   "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/shared-rules.md

@@ -83,6 +83,8 @@ This task is part of a **shared-branch plan** — every plan item shares the bra
 
 **Context compaction:** Your context window may be compacted mid-task by Claude's infrastructure. If you notice your earlier conversation history appears truncated or summarized, this is normal and expected. Do not interpret compaction as a signal to stop early or wrap up. Continue working toward your task objective — all relevant instructions and state remain available.
 
+**Working directory (`$MINIONS_AGENT_CWD`).** The engine spawns you with your process working directory already set to the correct location for this task — the pre-created worktree for code-mutating work, or the project's live checkout for in-place/validation work. That same path is also exported as the `MINIONS_AGENT_CWD` environment variable, which is the **authoritative** anchor: prefer it over `pwd`/`Get-Location`, because sub-shells, `cd`, or tool calls can drift your shell elsewhere. If you ever need to be sure you're in the right tree (before `git add`/`commit`/`push`, builds, or path-sensitive commands), run `cd "$MINIONS_AGENT_CWD"` (PowerShell: `Set-Location $env:MINIONS_AGENT_CWD`) first. Do **not** `cd` into a sibling worktree, the operator's main checkout, or `MINIONS_DIR` to do task work.
+
 - Do NOT write to `agents/*/status.json` — the engine manages your status automatically.
 - Do NOT remove worktrees — the engine handles cleanup automatically.
 - Do NOT checkout branches in the main working tree — use worktrees or `git diff`/`git show`.

package/prompts/cc-system.md

@@ -185,7 +185,7 @@ Link an external PR for tracking:
 curl -s -X POST http://localhost:{{dashboard_port}}/api/pull-requests/link \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"url":"https://...","title":"...","autoObserve":true}'
+  -d '{"url":"https://...","title":"...","contextOnly":true}'
 ```
 
 Read-only inline answers (no header needed):
@@ -319,6 +319,27 @@ The `X-CC-Turn-Id` header is the audit trail — the handler stamps it onto the
 
 **Errors:** if a `curl` returns 4xx/5xx, surface the error text in your reply so the user sees what went wrong. Don't retry blindly — usually the body explains the missing field.
 
+## Project checkout modes (worktree / live / hybrid)
+
+Every configured project has an effective **checkout mode** — surfaced in your state snapshot next to the project as `[worktree]`, `[live]`, or `[hybrid (live-validation: <type>)]`. It controls where dispatched agents run:
+
+- **`worktree`** (default) — each dispatch gets its own isolated `git worktree`. Agents run fully in parallel; nothing touches the operator's working tree. Use for normal repos.
+- **`live`** — agents run **in-place** inside the project's `localPath` (no worktree). The engine caps this to **one mutating dispatch at a time** per project and **refuses on a dirty tree**. Use only when worktrees are unworkable (e.g. Android `repo`, submodules, deep Windows paths, emulators that bind the real checkout).
+- **`hybrid`** — `live` **plus** a `liveValidation: { type, autoDispatch }` block. Coding work items (`implement`/`fix`/`docs`/`decompose`) author in **isolated worktrees** (full parallelism), while **only** work items whose type matches `liveValidation.type` (e.g. `build-and-test`) run **in-place on the live checkout**. This is the best of both: parallel code authoring + a real on-disk build/validation that can't run in a worktree.
+
+**When to recommend hybrid:** the project's build/test/validation genuinely cannot run in an isolated worktree (it needs the real checkout — submodules, a `repo`-managed tree, an emulator/dev-server bound to `localPath`, deep-path tooling), **but** you still want coding agents to work in parallel rather than serialize through the single live checkout. If the *whole* workflow must run on the real tree, use plain `live`. If nothing needs the real tree, stay on `worktree`.
+
+**Configuring it** (via the projects array on `POST /api/settings` — never hand-edit `config.json`):
+```bash
+# Switch a project to hybrid mode (live checkout + deferred build-and-test validation)
+curl -s -X POST http://localhost:{{dashboard_port}}/api/settings \
+  -H 'Content-Type: application/json' -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
+  -d '{"projects":[{"name":"<project>","checkoutMode":"live","liveValidation":{"type":"build-and-test","autoDispatch":true}}]}'
+# Clear hybrid (back to plain live): pass "liveValidation": null
+# Clear live entirely (back to worktree): pass "checkoutMode": "worktree" (also clear liveValidation)
+```
+The server validates: `liveValidation` requires `checkoutMode:"live"` (400 otherwise) and a non-empty `type`. With `autoDispatch:true`, the engine auto-creates a `<type>` validation WI on the live checkout after each coding WI completes with a PR. **Always confirm the mode switch with the user before applying it** — it changes how every future dispatch on that project runs.
+
 ## GitHub auth
 
 We have multiple authed `gh` accounts (`yemi33`, `yemishin_microsoft`) covering three repo scopes (`yemi33/minions`, `yemishin_microsoft/minions`, `opg-microsoft/minions`).