@yemi33/minions 0.1.2304 → 0.1.2306

package/dashboard/slim/js/modals-tiles.js

@@ -123,135 +123,23 @@
     });
   }
 
-  // Collapsible "Completed work" section appended to the queued popout (only).
-  // Collapsed by DEFAULT; clicking (or Enter/Space on) the header toggles the
-  // list. Sources data.dispatch.completed — the same recent window the slim
-  // History feed reads (capped to the last 20 by the /api/status snapshot) —
-  // so it adds no new API calls. Status semantics reuse completionStatus /
-  // completionTitle for parity with the History feed.
-  function renderCompletedSection(body, data) {
-    var dispatch = data.dispatch || {};
-    // Snapshot delivers completed oldest→newest; reverse for most-recent-first.
-    var completed = Array.isArray(dispatch.completed) ? dispatch.completed.slice().reverse() : [];
-
-    var section = document.createElement('div');
-    section.className = 'tile-completed-section collapsed';
-
-    var head = document.createElement('div');
-    head.className = 'tile-completed-section-head';
-    head.setAttribute('role', 'button');
-    head.setAttribute('tabindex', '0');
-    head.setAttribute('aria-expanded', 'false');
-    var caret = document.createElement('span');
-    caret.className = 'tile-caret';
-    caret.textContent = '▸';
-    var label = document.createElement('span');
-    label.className = 'tile-completed-section-title';
-    label.textContent = 'Completed work (' + completed.length + ')';
-    head.appendChild(caret);
-    head.appendChild(label);
-
-    var listWrap = document.createElement('div');
-    listWrap.className = 'tile-completed-section-body';
-    listWrap.hidden = true;
-
-    if (!completed.length) {
-      tileEmpty(listWrap, 'No completed work yet.');
-    } else {
-      completed.forEach(function(c) {
-        var who = c.agentName || c.agent || c.dispatched_to || '—';
-        var when = c.completed_at || c.completedAt || c.endedAt || c.started_at || c.startedAt;
-        var status = completionStatus(c);
-        var chip = status === 'ok' ? { text: 'done', cls: 'green' }
-                 : status === 'warn' ? { text: 'partial', cls: 'amber' }
-                 : { text: 'failed', cls: 'red' };
-        listWrap.appendChild(tileCard({
-          title: completionTitle(c),
-          meta: who + (when ? ' · completed ' + relTime(when) : ''),
-          chip: chip,
-        }));
-      });
-    }
-
-    function toggle() {
-      var open = !section.classList.toggle('collapsed');
-      head.setAttribute('aria-expanded', open ? 'true' : 'false');
-      caret.textContent = open ? '▾' : '▸';
-      listWrap.hidden = !open;
-    }
-    head.addEventListener('click', toggle);
-    head.addEventListener('keydown', function(ev) {
-      if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); toggle(); }
-    });
-
-    section.appendChild(head);
-    section.appendChild(listWrap);
-    body.appendChild(section);
-  }
-
-  // Collapsible "Pending work items" section appended to the queued popout
-  // (W-mqv1xbcm). Sources data.workItems filtered to status === 'pending' — the
-  // same /api/work-items slice the slim poll merges onto the snapshot — so it
-  // adds no new API calls and refreshes whenever the popout is re-opened.
-  // Expanded by DEFAULT (more prominent than the collapsed Completed section)
-  // since these are the queued WIs the operator most wants to scan. Mirrors
-  // renderCompletedSection's structure + tileCard usage; all text via
-  // textContent (no innerHTML) to keep the SEC-03 baseline clean. Each card
-  // shows title, id, project (project || _source), type, and the engine's
-  // _pendingReason as a chip when set.
-  function renderPendingSection(body, data) {
-    var pending = (Array.isArray(data.workItems) ? data.workItems : []).filter(function(w) {
-      return w && w.status === 'pending';
-    });
-
-    var section = document.createElement('div');
-    section.className = 'tile-completed-section';
-
-    var head = document.createElement('div');
-    head.className = 'tile-completed-section-head';
-    head.setAttribute('role', 'button');
-    head.setAttribute('tabindex', '0');
-    head.setAttribute('aria-expanded', 'true');
-    var caret = document.createElement('span');
-    caret.className = 'tile-caret';
-    caret.textContent = '▾';
-    var label = document.createElement('span');
-    label.className = 'tile-completed-section-title';
-    label.textContent = 'Pending work items (' + pending.length + ')';
-    head.appendChild(caret);
-    head.appendChild(label);
-
-    var listWrap = document.createElement('div');
-    listWrap.className = 'tile-completed-section-body';
-
-    if (!pending.length) {
-      tileEmpty(listWrap, 'No pending work items.');
-    } else {
-      pending.forEach(function(w) {
-        var project = w.project || w._source;
-        var meta = [w.id || null, project || null, w.type || null].filter(Boolean).join(' · ');
-        var card = { title: w.title || w.id || '(untitled)', meta: meta };
-        if (w._pendingReason) {
-          card.chip = { text: String(w._pendingReason).replace(/_/g, ' '), cls: 'amber' };
-        }
-        listWrap.appendChild(tileCard(card));
-      });
-    }
-
-    function toggle() {
-      var open = !section.classList.toggle('collapsed');
-      head.setAttribute('aria-expanded', open ? 'true' : 'false');
-      caret.textContent = open ? '▾' : '▸';
-      listWrap.hidden = !open;
-    }
-    head.addEventListener('click', toggle);
-    head.addEventListener('keydown', function(ev) {
-      if (ev.key === 'Enter' || ev.key === ' ') { ev.preventDefault(); toggle(); }
-    });
-
-    section.appendChild(head);
-    section.appendChild(listWrap);
-    body.appendChild(section);
+  // Queued-work tile body — reuses the LITERAL classic dashboard Work Items
+  // screen instead of a slim-specific list, so there is one work-items UI, not
+  // two (W-mqrdggys000f94a4 / "reuse, don't fork"). Slim and classic are two
+  // separate IIFE bundles with no shared scope, so we can't call the classic
+  // renderWorkItems() in-process; instead we embed the real /work screen in an
+  // iframe with the chrome-off ?embed=1 mode. The iframed page IS the classic
+  // screen — full filter/sort + every row action (edit/cancel/retry/archive/
+  // delete/feedback), backed by the same /api/work-items data + endpoints —
+  // with zero duplicated rendering logic. Classic is reachable at /work even
+  // with slim-ux ON (only / is taken over). Built with createElement (no
+  // innerHTML) to satisfy the dashboard no-unsanitized lint gate.
+  function renderQueuedWorkBody(body) {
+    var frame = document.createElement('iframe');
+    frame.className = 'slim-work-embed';
+    frame.src = '/work?embed=1';
+    frame.title = 'Work Items';
+    body.appendChild(frame);
   }
 
   function renderPrTileBody(body, data) {
@@ -375,7 +263,7 @@
   var TILE_VIEWS = {
     engine:     { title: 'Engine',            render: renderEngineTileBody },
     dispatches: { title: 'Active dispatches', render: function(body, data) { renderDispatchTileBody(body, data, true); } },
-    queued:     { title: 'Queued work',       render: function(body, data) { renderDispatchTileBody(body, data, false); renderPendingSection(body, data); renderCompletedSection(body, data); } },
+    queued:     { title: 'Queued work',       render: function(body) { renderQueuedWorkBody(body); } },
     prs:        { title: 'Pull requests',     render: renderPrTileBody },
     watches:    { title: 'Watches',           render: renderWatchTileBody },
   };
@@ -400,6 +288,9 @@
     // The "+ Link PR" header chip only applies to the PR list.
     var headerChip = document.getElementById('slim-tile-modal-linkpr');
     if (headerChip) headerChip.style.display = (key === 'prs') ? '' : 'none';
+    // The queued tile embeds the full classic /work screen in an iframe — widen
+    // the modal + drop the body padding so the embedded table gets real estate.
+    modal.classList.toggle('tile-modal--work', key === 'queued');
     view.render(body, lastStatusData || {});
     modal.classList.add('open');
   }

package/dashboard/slim/styles.css

@@ -680,6 +680,15 @@
     /* Cockpit-tile detail modal: list of dispatches / PRs / watches, or a
        key/value engine readout (reuses .agent-detail-row). */
     #slim-tile-modal .modal { width: 720px; max-width: calc(100vw - 32px); }
+    /* W-mqrdggys000f94a4 — the Queued-work tile embeds the full classic /work
+       screen in an iframe; widen the modal + remove body padding so the
+       embedded work-items table gets the full width/height. */
+    #slim-tile-modal.tile-modal--work .modal { width: 1180px; }
+    #slim-tile-modal.tile-modal--work .modal-body { padding: 0; }
+    .slim-work-embed {
+      display: block; width: 100%; height: calc(100vh - 160px); min-height: 360px;
+      border: 0; background: var(--bg);
+    }
     .tile-item {
       display: block;
       text-decoration: none;
@@ -712,20 +721,6 @@
     .tile-chip.blue  { background: rgba(88, 166, 255, 0.12); color: var(--blue);  border-color: var(--blue); }
     .tile-empty { color: var(--muted); font-style: italic; font-size: var(--text-md); }
 
-    /* Collapsible "Completed work" section in the queued popout. Collapsed by
-       default; the caret rotates and the body unhides on toggle. */
-    .tile-completed-section { margin-top: 12px; border-top: 1px solid var(--border); padding-top: 10px; }
-    .tile-completed-section-head {
-      display: flex; align-items: center; gap: 6px;
-      cursor: pointer; user-select: none;
-      font-size: var(--text-md); font-weight: 600; color: var(--text);
-      padding: 2px 0;
-    }
-    .tile-completed-section-head:hover { color: var(--blue); }
-    .tile-completed-section-head:focus-visible { outline: 1px solid var(--blue); outline-offset: 2px; border-radius: var(--radius); }
-    .tile-caret { font-size: var(--text-sm); color: var(--muted); width: 12px; display: inline-block; text-align: center; }
-    .tile-completed-section-body { margin-top: 8px; }
-
     /* Collapsible PR sections (Active / Merged-Completed / Abandoned). Uses
        native <details>/<summary> — no JS wiring needed for the toggle. */
     .tile-section { margin-bottom: 10px; }

package/dashboard/styles.css

@@ -1288,6 +1288,64 @@
   .project-mode-live { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); }
   .project-mode-hybrid { background: rgba(88,166,255,0.15); color: var(--blue); border: 1px solid var(--blue); }
 
+  /* Clickable checkout-mode pill (W-mr1b67zi0006b788) — swaps the "help"
+   * cursor for "pointer" and adds a hover/focus highlight so it reads as
+   * interactive, opening the picker in _openCheckoutModeMenu(). */
+  .project-mode-pill-clickable { cursor: pointer; }
+  .project-mode-pill-clickable:hover,
+  .project-mode-pill-clickable:focus-visible {
+    filter: brightness(1.2);
+    outline: 1px solid var(--blue);
+    outline-offset: 1px;
+  }
+
+  /* Checkout-mode picker popover (W-mr1b67zi0006b788). Rendered via
+   * document.createElement in _openCheckoutModeMenu (no innerHTML), appended
+   * to <body> and positioned under the clicked pill. */
+  .checkout-mode-menu {
+    z-index: 1000;
+    min-width: 220px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md, 6px);
+    box-shadow: 0 4px 16px rgba(0,0,0,0.3);
+    padding: 6px;
+    font-size: var(--text-sm);
+  }
+  .checkout-mode-menu-title {
+    font-weight: 600; color: var(--muted);
+    padding: 4px 8px 6px; border-bottom: 1px solid var(--border);
+    margin-bottom: 4px;
+  }
+  .checkout-mode-menu-item {
+    padding: 6px 8px; border-radius: 4px; cursor: pointer;
+    color: var(--text);
+  }
+  .checkout-mode-menu-item:hover,
+  .checkout-mode-menu-item:focus {
+    background: var(--surface); outline: none;
+  }
+  .checkout-mode-menu-item-active { color: var(--blue); font-weight: 600; }
+  .checkout-mode-menu-item-desc {
+    font-size: var(--text-xs); color: var(--muted); font-weight: 400;
+    margin-top: 2px; line-height: 1.35;
+  }
+  .checkout-mode-menu-select {
+    width: 100%; margin: 4px 0 8px; padding: 4px 6px;
+    background: var(--surface); color: var(--text); border: 1px solid var(--border);
+    border-radius: 4px;
+  }
+  .checkout-mode-menu-actions {
+    display: flex; justify-content: flex-end; gap: 6px; padding-top: 4px;
+  }
+  .checkout-mode-menu-btn {
+    padding: 4px 10px; border-radius: 4px; border: 1px solid var(--border);
+    background: var(--surface); color: var(--text); cursor: pointer; font-size: var(--text-sm);
+  }
+  .checkout-mode-menu-btn-primary {
+    background: var(--blue); color: #fff; border-color: var(--blue);
+  }
+
   /* QA tab (W-mpeiwz6k0005bf34-d) — targets / runbooks / runs sections.
    * Reuses surface/border/text tokens defined in :root so the QA page
    * blends with the rest of the dashboard. */
@@ -1547,3 +1605,24 @@
   .cc-error strong { color: var(--red); }
   .cc-error code { font-family: monospace; font-size: var(--text-xs);
     color: var(--muted); }
+
+  /* W-mqrdggys000f94a4 — chrome-off "embed" mode (?embed=1). Strips the global
+     dashboard chrome so a single page (e.g. /work?embed=1) can be iframed inside
+     the slim cockpit's Queued-work modal and render as just its panel. The
+     html.embed class is applied in layout.html's head before first paint. */
+  html.embed body > header,
+  html.embed #projects-bar,
+  html.embed #setup-banner,
+  html.embed #fre-banner,
+  html.embed .engine-alert,
+  html.embed .paused-banner,
+  html.embed .sidebar,
+  html.embed #cc-drawer,
+  html.embed #cc-overlay { display: none !important; }
+  /* Do NOT override .page-layout to display:block here — that detaches
+     .page-content from its bounded-height flex parent, so it grows to full
+     content height and the fixed-height iframe clips it with no scrollbar (the
+     Queued-work popup "doesn't scroll"). The sidebar is hidden above, so the
+     base .page-layout flex row already gives .page-content full width plus a
+     bounded height to scroll within. */
+  html.embed .page-content { padding: 12px 16px; overflow-y: auto; }

package/dashboard.js

@@ -1350,12 +1350,15 @@ function linkPullRequestForTracking({ url, title, project: projectName, contextO
 // W-mpmwxkzm0009ba0b — Per-row auto-observe toggle backing helper for
 // POST /api/pull-requests/observe. Flips canonical `contextOnly` on an
 // existing tracked PR record under a lock (per CLAUDE.md mutate convention).
-// Body shape: { host: 'github'|'ado', slug, number, observe: boolean }.
-// The public `observe` body param is preserved for backward compatibility
-// (W-mq5s5ttx000j7ab8-c); internally it maps to `contextOnly = !observe`.
+// Body shape: { host: 'github'|'ado', slug, number, contextOnly: boolean }.
+// `contextOnly` is canonical and read first; the legacy `observe` body
+// param (W-mq5s5ttx000j7ab8-c) is accepted as a documented back-compat
+// fallback (`contextOnly = !observe`) for any caller that still sends it —
+// the dashboard client itself now sends `contextOnly` exclusively
+// (P-2b6e4d81; see docs/deprecated.json#pr-observe-observe-body-param).
 // Returns the updated record + the PR path that was touched. Throws an
 // Error with `statusCode` for the route handler to map to an HTTP status.
-function updatePullRequestObserveFlag({ host, slug, number, observe } = {}, config = CONFIG, minionsDir = MINIONS_DIR) {
+function updatePullRequestObserveFlag({ host, slug, number, observe, contextOnly } = {}, config = CONFIG, minionsDir = MINIONS_DIR) {
   const hostStr = String(host || '').trim().toLowerCase();
   const slugStr = String(slug || '').trim();
   const numberInt = Number.parseInt(number, 10);
@@ -1374,8 +1377,13 @@ function updatePullRequestObserveFlag({ host, slug, number, observe } = {}, conf
     err.statusCode = 400;
     throw err;
   }
-  if (typeof observe !== 'boolean') {
-    const err = new Error('observe must be a boolean');
+  let contextOnlyValue;
+  if (typeof contextOnly === 'boolean') {
+    contextOnlyValue = contextOnly;
+  } else if (typeof observe === 'boolean') {
+    contextOnlyValue = !observe;
+  } else {
+    const err = new Error('contextOnly (or legacy observe) must be a boolean');
     err.statusCode = 400;
     throw err;
   }
@@ -1394,7 +1402,7 @@ function updatePullRequestObserveFlag({ host, slug, number, observe } = {}, conf
     shared.mutatePullRequests(prPath, (prs) => {
       const pr = prs.find(p => p && p.id === canonicalId);
       if (!pr) return prs;
-      pr.contextOnly = !observe;
+      pr.contextOnly = contextOnlyValue;
       updated = { id: pr.id, contextOnly: pr.contextOnly };
       updatedPath = prPath;
       return prs;
@@ -13086,6 +13094,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const inputs = [
         CONFIG_PATH,
         path.join(ENGINE_DIR, 'dispatch.json'),
+        // Central work-items.json at MINIONS_DIR root — backs the 'central'
+        // scope (schedule/pipeline/CC-created rootless WIs, per
+        // work-items-store.js#_filePathForScope). Without this, a new
+        // central-scope WI never busts the ETag until dispatch.json changes.
+        shared.centralWorkItemsPath(MINIONS_DIR),
       ];
       for (const p of projects) {
         if (p && p.name) {
@@ -13106,7 +13119,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'GET', path: '/api/pull-requests', desc: 'Fully-enriched pull requests (per-project files joined + url backfill + _project stamp)', handler: (req, res) => {
       const config = queries.getConfig();
       const projects = config.projects || [];
-      const inputs = [CONFIG_PATH];
+      const inputs = [
+        CONFIG_PATH,
+        // Central pull-requests.json at MINIONS_DIR root — backs the
+        // 'central' scope per pull-requests-store.js#_filePathForScope.
+        // Mirrors the same class of staleness fix as /api/work-items.
+        shared.centralPullRequestsPath(MINIONS_DIR),
+      ];
       for (const p of projects) {
         if (p && p.name) inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json'));
       }
@@ -13137,6 +13156,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const inputs = [
         path.join(ENGINE_DIR, 'metrics.json'),
         path.join(ENGINE_DIR, 'dispatch.json'),
+        // getMetrics() enriches from getPullRequests(), which includes the
+        // central pull-requests.json scope — include it here too so a new
+        // central-scope PR busts the ETag (same class of bug as /api/work-items).
+        shared.centralPullRequestsPath(MINIONS_DIR),
       ];
       for (const p of projects) {
         if (p && p.name) inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json'));
@@ -13721,7 +13744,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       }
     }},
 
-    { method: 'POST', path: '/api/pull-requests/observe', desc: 'Toggle canonical contextOnly flag on a tracked PR (public `observe` body param is preserved as the inverse for backward compat)', params: 'host (github|ado), slug, number, observe (boolean)', handler: async (req, res) => {
+    { method: 'POST', path: '/api/pull-requests/observe', desc: 'Toggle canonical contextOnly flag on a tracked PR (legacy `observe` body param is preserved as the inverse for backward compat)', params: 'host (github|ado), slug, number, contextOnly (boolean; legacy observe (boolean) also accepted)', handler: async (req, res) => {
       const body = await readBody(req);
       reloadConfig();
       try {
@@ -14463,6 +14486,15 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     "img-src 'self' data:; " +
     "connect-src 'self'"
   );
+  // The Slim UX "Queued work" tile (W-mqrdggys000f94a4) embeds this classic SPA
+  // at /work?embed=1 in a SAME-ORIGIN iframe. buildSecurityHeaders() stamped
+  // X-Frame-Options: DENY on every response above, which makes the browser
+  // refuse to render the iframe ("localhost refused to connect"). Relax to
+  // SAMEORIGIN for the chrome-off embed request only — the standalone classic
+  // dashboard keeps DENY. Mirrors serveSlimUx's embeddable relaxation for /slim.
+  if (/[?&]embed=1(?:&|$)/.test(req.url)) {
+    res.setHeader('X-Frame-Options', 'SAMEORIGIN');
+  }
   if (req.headers['if-none-match'] === HTML_ETAG) {
     res.statusCode = 304;
     res.end();

package/docs/completion-reports.md

@@ -85,6 +85,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
+| `invalidates` | string[] | Optional. List of work-item IDs (e.g. `["W-abc123"]`) whose goals are superseded by this completion. The engine cancels each listed WI that is currently in `pending` or `queued` status, stamping `cancellationReason: "invalidated-by:<source-wi-id>"`. WIs in any other status (dispatched, done, failed, cancelled) are skipped with a warning — they are NOT cancelled. Missing IDs also log a warning and are skipped. Only processed on successful (`effectiveSuccess`) completions. See [Goal invalidation](#goal-invalidation). |
 | `meta.review` | object | Optional, review tasks only. Records project-local review-skill outcome — see [Review skill outcomes](#review-skill-outcomes). Aliased by the generalized `meta.skill` (W-mq1cczi90006b21f). |
 | `meta.skill` | object | Optional. Records project-local skill outcome for ANY playbook type that surfaces a `## Project skills` block (implement / fix / plan / review / etc.). See [Project skill outcomes](#project-skill-outcomes). |
 | `meta.descriptionAudit` | object | Optional, `fix` / `implement` dispatches that push commits. Records the PR description audit + screenshot-refresh outcome — see [PR description audit](#pr-description-audit). |
@@ -191,6 +192,30 @@ Record the outcome under `meta.descriptionAudit`. All fields are optional and ba
 
 Dispatchers can suppress the audit entirely by setting `meta.skipDescriptionAudit: true` on the work item — the playbook then renders an explicit "audit suppressed" notice instead of the audit steps. Use this for skill-meta updates, doc-only fixes whose PR description text won't be affected by the diff, and follow-up dispatches that explicitly own the description themselves.
 
+## Goal invalidation
+
+P-mqyp0009y025z6a7. An optional `invalidates: string[]` field in the completion report lets a completing work item cancel the goals of sibling or downstream WIs that are no longer needed.
+
+```json
+{
+  "status": "success",
+  "summary": "Implemented approach A; approach B work items are no longer needed.",
+  "invalidates": ["W-approach-b-001", "W-approach-b-002"]
+}
+```
+
+**Semantics:**
+
+- `invalidates` is an array of work-item ID strings (same format as WI IDs: `W-xxx`).
+- The field is **optional and additive** — existing completion reports without it are unaffected.
+- The engine processes `invalidates[]` only on **successful** completions (code 0, no `agentReportedFailure`, no `skipDoneStatus`).
+- Each listed WI is cancelled only if it is currently in `pending` or `queued` status. WIs in any other status (`dispatched`, `done`, `failed`, `cancelled`, …) are **not** cancelled; a warning is logged instead.
+- Missing WI IDs (IDs not found in any project's work-items) produce a warning but do **not** throw — the rest of the `invalidates[]` list is still processed.
+- Each cancellation stamps `cancellationReason: "invalidated-by:<source-wi-id>"` and `cancelledAt` on the cancelled WI.
+- A `work_items` state event is emitted for each successful cancellation so the dashboard reflects it.
+
+**Implementation:** `engine/lifecycle.js#applyGoalInvalidation`, called from `runPostCompletionHooks` after the source WI is marked done.
+
 ## Harness usage (`harnessUsed`)
 
 P-a8f3c2d1. Optional self-report of the harness affordances the agent actually

package/docs/copilot-cli-schema.md

@@ -26,6 +26,7 @@
 | `capabilities.bareMode` | **`false`** | No `--bare`. Closest equivalent is `--no-custom-instructions` (suppresses AGENTS.md only, not all auto-discovery). |
 | `capabilities.fallbackModel` | **`false`** | No `--fallback-model` flag. |
 | `capabilities.sessionPersistenceControl` | **`false`** | Copilot manages session state internally in `~/.copilot/session-state/`. Engine cannot opt out without `--config-dir`. |
+| `capabilities.imageInput` | **`true`** | Base64 image payloads are materialized to temp files and passed as `--attachment <path>` (repeatable flag, W-mqv7324u0021db5d). See §10a. |
 
 | Default | Value |
 |---|---|
@@ -182,6 +183,7 @@ Empirically confirmed flags for non-interactive Copilot invocations:
 | `--stream on` / `--stream off` | optional | Default is `on`. See §4. |
 | `--enable-reasoning-summaries` | optional | Maps from `opts.reasoningSummaries`; only Anthropic models populate `assistant.reasoning_delta`. |
 | `--add-dir <path>` | injected by spawn-agent | Same role as on the Claude path — registers extra read-allowed dirs (skill discovery). |
+| `--attachment <path>` | injected for image inputs | Passes an image file to the model. Repeatable. The adapter writes each base64 image payload to a temp file, emits one `--attachment` per file, and deletes temps after spawn (W-mqv7324u0021db5d). Gated by `capabilities.imageInput`. |
 | `-v` / `--verbose` | **never emit** | Does not exist on Copilot. The Claude adapter emits `--verbose`; the Copilot adapter MUST NOT. |
 
 ### 3.1 `--autopilot` vs single-shot
@@ -602,7 +604,8 @@ When implementing `engine/runtimes/copilot.js`:
 3. `buildArgs(opts)` always emits:
    `--output-format json -s --allow-all --no-ask-user --autopilot --log-level error`
    plus the conditional flags from §3, plus `--no-custom-instructions` /
-   `--disable-builtin-mcps` per `opts.suppressAgentsMd` / `opts.disableBuiltinMcps`.
+   `--disable-builtin-mcps` per `opts.suppressAgentsMd` / `opts.disableBuiltinMcps`,
+   plus `--attachment <path>` (repeatable) for each image in `opts.images` (§10a).
    **Never** emit `--verbose`.
 4. `buildPrompt()` injects `<system>...</system>\n\n` block when sysprompt is
    non-empty; passthrough otherwise (§2).
@@ -643,6 +646,33 @@ When the spike's findings disagree with the plan text, **this document wins**
 
 ---
 
+## 10a. Image Attachments — `--attachment` (W-mqv7324u0021db5d)
+
+`capabilities.imageInput: true`. The Copilot CLI accepts image files via
+`--attachment <path>` (the flag is repeatable). The adapter's `buildArgs(opts)`
+materializes each base64 payload from `opts.images` to a temp file in
+`opts.tmpDir`, appends `--attachment <path>` per file, and arranges cleanup after
+`spawn` returns.
+
+```js
+// Simplified adapter flow (see engine/runtimes/copilot.js _buildAttachmentArgs)
+for (const img of opts.images ?? []) {
+  const ext = MIME_TO_EXT[img.mimeType] ?? 'bin';
+  const filePath = path.join(opts.tmpDir, `attachment-${i}.${ext}`);
+  fs.writeFileSync(filePath, Buffer.from(img.dataBase64, 'base64'));
+  args.push('--attachment', filePath);
+}
+```
+
+**Supported MIME types** (empirically confirmed against Copilot v1.0.36):
+`image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+
+When `capabilities.imageInput` is false (e.g., Codex adapter), the engine's
+`_resolveImageOpts` returns a typed `model-unavailable` error before spawn so
+callers get a clean rejection instead of a silent drop.
+
+---
+
 ## Provenance
 
 - Test host: Windows 11, PowerShell 7+, `copilot.exe` 1.0.36 from WinGet.

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Accepted — implementation in progress**
 
-> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–9 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, qa_runs + qa_sessions, pr_links, cooldowns + pending_rebases + cc_sessions + doc_sessions, and steering_deliveries — see `CHANGELOG.md` and `engine/db/migrations/`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true). Phase 9.4 went further and deleted the silent SQL-unavailable JSON fallbacks in the engine — SQL is now the only reader/writer for everything migrated; the JSON mirror layer is dual-written as a passive mirror and slated for deletion in Phase 9.5. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
+> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–10 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, qa_runs + qa_sessions, pr_links, cooldowns + pending_rebases + cc_sessions + doc_sessions, and steering_deliveries (Phases 0–9); plans + prds + prd_items + prd_verify_prs (Phase 10, migration `015-plans-prds.js`) — see `CHANGELOG.md` and `engine/db/migrations/`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true). Phase 9.4 went further and deleted the silent SQL-unavailable JSON fallbacks in the engine — SQL is now the only reader/writer for everything migrated; the JSON mirror layer is dual-written as a passive mirror and slated for deletion in Phase 9.5. Phase 10 dual-writes PRD state to SQL (`engine/prd-store.js`) and flips reads to SQL when the `prdReadsFromSql` feature flag is ON (default ON — reversible). The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
 
 ## Executive Summary
 

package/docs/live-checkout-mode.md

@@ -54,7 +54,7 @@ By default the dirty tree refusal (Guarantee 2) is terminal — the engine never
 3. If ON: `git fetch origin` + `git reset --hard origin/<branch>`, then **re-run the porcelain preflight once**. If the tree is now clean, dispatch proceeds normally. If the reset failed or the tree is *still* dirty, it falls back to the safe `{ ok:false, reason:'dirty' }` refusal — the engine never dispatches onto an unexpected tree.
 4. On a successful reset it writes a single `live-checkout-autoreset-<wiId>` inbox note listing **exactly which paths were discarded**, so the operator can recover them from `git reflog` / `git fsck --lost-found`.
 
-This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout — which is why it is **OFF by default** and strictly opt-in. Use it only for unattended/CI-style live checkouts where the tree is expected to track the remote and any local drift is disposable.
+This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout. As of W-mqzbbhn2 it is **ON by default**: discarding disposable dirt via reset-to-remote keeps live-checkout branches aligned with origin instead of accumulating `minions: auto-save agent WIP` commits on every dirty exit. Set `liveCheckoutAutoReset: false` (per-project or fleet-wide) to restore the terminal dirty-tree refusal for live checkouts whose local drift you want preserved.
 
 - **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.)*
@@ -103,6 +103,8 @@ Live-mode agents run **in-place** in the operator's checkout, so when a dispatch
 
 - **Original-ref capture.** `prepareLiveCheckout` records the operator's starting ref *before* the first checkout: `git symbolic-ref --short HEAD` → `{ originalRef:<branch>, originalRefType:'branch' }`, falling back to `git rev-parse HEAD` → `{ originalRef:<sha>, originalRefType:'detached' }`. `spawnAgent` persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch`, so the restore survives an engine restart, where the in-memory spawn closure is gone and only the persisted record remains.
 - **Self-healing dirty recovery (PL-live-checkout-reliability-hardening).** Before the plain checkout, if the tree is **dirty AND HEAD is on the agent branch** (and that branch differs from `originalRef`), the dirt is provably **agent-authored** — the engine created that branch and verified the tree clean before switching to it. The leftovers are committed onto the **agent branch** (`git add -A` + `git commit --no-verify -m "minions: auto-save agent WIP (dispatch …)"`), so the plain `git checkout <originalRef>` then succeeds and the operator tree returns clean. This is the fix for the *"no recovery from dirty checkout"* deadlock, where an agent's crash-leftover WIP refused the restore, stranded the tree dirty on the agent branch, and then made **every future WI** for that project fail `LIVE_CHECKOUT_DIRTY` until a human cleaned it. It only ever mutates the engine-created branch, never the operator's branch, never discards (the WIP lands as a visible, revertable commit / on its PR), and gitignored artifacts are never staged (so a tree dirty only with ignored build output never reaches here). Best-effort: a failed auto-commit falls through to the manual-recovery alert below.
+- **Retry-with-backoff on the WIP auto-save commit (#608).** The `git add -A` + `git commit` above (and the equivalent self-heal commit described below) go through `_commitAgentWipWithRetry`: a bounded retry (3 attempts, linear backoff) that fires only when the commit fails with an `index.lock` / "another git process" message — i.e. a transient collision with a concurrent git invocation — never on a genuine failure like "nothing to commit". Previously a single failed attempt (e.g. a `.git/index.lock` race) silently aborted the auto-save, leaving the tree dirty on the agent branch and letting the pollution below take hold.
+- **Orphaned-agent-branch self-heal at dispatch start (#608).** If dispatch-end restore is ever skipped or interrupted (crash, forced kill, an engine restart racing the restore), the *next* dispatch for that project can start with HEAD already sitting on a stray `work/<wi-id>` branch from the previous run — and, before this fix, `prepareLiveCheckout`'s dirty-tree check ran *before* `originalRef` was even captured, so the function returned `{ reason: 'dirty' }` immediately and the branch was never noticed or cleaned, silently repeating for every subsequent dispatch. `prepareLiveCheckout` now recognizes this case: if the tree is still dirty after the existing auto-clean-artifacts recheck, and the current branch (read from the already-fetched `git status --porcelain -b` header, no extra git call) matches the `work/<id>` naming convention (`_looksLikeAgentBranch`) and differs from this dispatch's own target branch, the WIP is committed onto that stray branch (again via `_commitAgentWipWithRetry`) and HEAD is switched back to `mainRef` before the normal flow continues. This only ever touches a branch matching the engine's own naming convention — an operator's own feature branch (e.g. `feature/x`) is never mistaken for engine litter and is left untouched.
 - **AUTO-RESTORE (best-effort, never `--force`).** At dispatch-end `restoreLiveCheckoutAtDispatchEnd` issues a **plain** `git checkout <originalRef>` — no `--force`, no `-B`, no reset, no clean, no stash. It no-ops when there is nothing to restore: no captured `originalRef`, the agent branch *is* the original ref, or HEAD already sits on the original ref (matched against the branch name *or* the raw sha so the detached-HEAD case is recognized). It is strictly best-effort: every error is swallowed and logged, and a restore never alters the dispatch result.
 - **Fallback notify (only when a safe switch is impossible).** If git declines the plain checkout — most likely because the agent left uncommitted changes a checkout would overwrite — the refusal is **honored**: the tree is left exactly as the agent left it and a deduped `live-checkout-branch-<dispatchId>` inbox alert tells the operator how to switch back manually (`git -C <localPath> checkout <originalRef>`). The engine never forces the switch. An **unexpected** restore error (git missing, repo corruption, a GVFS blob fetch on the switch-back) now also writes this alert, so a non-refusal failure never silently strands the tree.
 - **Terminal-failure alert.** When the dispatch ends in a non-success terminal state, a deduped `live-checkout-failed-<dispatchId>` inbox alert is written so the operator knows a live-mode run failed inside their own checkout (where any partial work is visible). This is independent of the restore and fires even when the restore itself succeeds.
@@ -178,7 +180,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 opt-in `liveCheckoutAutoReset` is the one sanctioned escape hatch — but it **discards** rather than stashes, is OFF by default, and is gated on explicit per-project / fleet-wide opt-in. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
+- **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 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.
@@ -190,7 +192,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | File | Purpose |
 |---|---|
 | `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 (OFF). Gates the opt-in dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20). |
+| `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` — `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). |