@yemi33/minions 0.1.2123 → 0.1.2125

package/dashboard/js/refresh.js

@@ -146,7 +146,7 @@ const RENDER_VERSIONS = {
   dispatch: 2,
   engineLog: 2,
   metrics: 1,
-  workItems: 1,
+  workItems: 2,
   skills: 1,
   mcpServers: 1,
   schedules: 1,

package/dashboard/js/render-work-items.js

@@ -15,8 +15,71 @@ const _WI_ENRICHMENT_FIELDS = [
   '_pr', '_prUrl', '_pendingReason', '_skipReason', '_blockedBy',
   '_humanFeedback', '_reopened', '_managedSpawnPartial', '_securityFlag',
   '_artifacts', 'referencesCount', 'acceptanceCriteriaCount',
+  // W-mq08kuog001110a6 — _preDispatchEval IS persisted to disk by
+  // engine/dispatch.js#_persistInvalidWorkItem, but the slim /api/status
+  // overlay may drop it on later passes. Carry it across the overlay so
+  // the Needs-Attention badge survives /state polls.
+  '_preDispatchEval',
 ];
 
+// W-mq08kuog001110a6 — Needs-Attention badge for stuck pending work items.
+//
+// A pending WI is "needs attention" when the engine is intentionally refusing
+// to dispatch it and a human (or follow-up dispatch) has to unblock it.
+// Surfaces existing engine state (_preDispatchEval / _pendingReason) — no
+// new fields, no dispatcher behavior change.
+//
+// Triggers:
+//   * _preDispatchEval.valid === false (pre-dispatch acceptance gate rejected)
+//   * _pendingReason in { pr_not_found, no_agent, budget_exceeded, dependency_unmet }
+//
+// Does NOT trigger for transient reasons that auto-clear:
+//   * cooldown / retry_cooldown — wait it out
+//   * already_dispatched — engine reconciles on next tick
+//   * branch_locked — wait for the holding dispatch
+//
+// Returns { kind, short, full } when the item needs attention, else null.
+// Pure helper (no DOM / escapeHtml deps) so it can be unit-tested in Node.
+function needsAttentionInfo(item) {
+  if (!item || item.status !== 'pending') return null;
+
+  if (item._preDispatchEval && item._preDispatchEval.valid === false) {
+    var rawReason = String(item._preDispatchEval.reason || '(no reason recorded)');
+    var firstLine = rawReason.split(/\r?\n/, 1)[0] || rawReason;
+    return {
+      kind: 'pre_dispatch_eval',
+      short: 'Pre-dispatch evaluation rejected: ' + firstLine,
+      full: rawReason,
+    };
+  }
+
+  var reason = item._pendingReason;
+  if (!reason) return null;
+
+  if (reason === 'pr_not_found') {
+    var prRef = item.prNumber || item.targetPr || item.pr_id || '?';
+    var prMsg = 'Target PR not tracked: PR #' + prRef + '. The PR was likely merged/closed or never linked.';
+    return { kind: 'pr_not_found', short: prMsg, full: prMsg };
+  }
+  if (reason === 'no_agent') {
+    var noAgentMsg = 'No agent assigned and routing.md has no match for type=' + (item.type || 'unknown') + '.';
+    return { kind: 'no_agent', short: noAgentMsg, full: noAgentMsg };
+  }
+  if (reason === 'budget_exceeded') {
+    var agent = item.agent || item.dispatched_to || '<unknown>';
+    var budgetMsg = 'Assigned agent ' + agent + ' is over its maxBudgetUsd cap.';
+    return { kind: 'budget_exceeded', short: budgetMsg, full: budgetMsg };
+  }
+  if (reason === 'dependency_unmet') {
+    var deps = Array.isArray(item.depends_on) && item.depends_on.length
+      ? item.depends_on.join(', ')
+      : '<unknown>';
+    var depMsg = 'Waiting on dependencies: ' + deps + '. (One or more are not yet done.)';
+    return { kind: 'dependency_unmet', short: depMsg, full: depMsg };
+  }
+  return null;
+}
+
 // Pull each project's work-items.json straight off disk through
 // /state/projects/<name>/work-items.json. The endpoint is a static-file
 // passthrough with mtime+size ETag — there is no server-side cache in the
@@ -129,6 +192,15 @@ function wiRow(item) {
     '<td>' + priBadge(item.priority) + '</td>' +
     '<td>' + statusBadge(item.status || 'pending') +
       (item._reopened ? ' <span style="font-size:var(--text-xs);color:var(--purple);margin-left:4px" title="This item was reopened from a previously completed state">reopened</span>' : '') +
+      (function() {
+        // W-mq08kuog001110a6 — Needs-Attention badge for stuck pending WIs.
+        // Click anywhere on the row to open the modal where the full reason
+        // is rendered under "Why this is blocked".
+        var info = needsAttentionInfo(item);
+        if (!info) return '';
+        var tooltip = (info.short || '').replace(/\s+/g, ' ').slice(0, 120);
+        return ' <span class="pr-badge needs-attention" style="font-size:var(--text-xs);margin-left:4px" title="' + escapeHtml(tooltip) + ' — click row for full reason">&#x26A0; Needs attention</span>';
+      })() +
       (item._pendingReason && item.status === 'pending' && item._pendingReason !== 'already_dispatched' ? ' <span style="font-size:var(--text-xs);color:var(--muted);margin-left:4px" title="Pending reason: ' + escapeHtml(item._pendingReason) + '">' + escapeHtml(item._pendingReason.replace(/_/g, ' ')) + '</span>' : '') +
       (item._pendingReason === 'already_dispatched' && item.status === 'pending' ? ' <span style="font-size:var(--text-xs);color:var(--blue);margin-left:4px" title="In dispatch queue, waiting to be assigned">queued</span>' : '') +
       (item._managedSpawnPartial && Array.isArray(item._managedSpawnPartial.failed) && item._managedSpawnPartial.failed.length
@@ -597,7 +669,28 @@ function _wiRenderDetail(item) {
     (item._reopened ? ' <span style="font-size:var(--text-xs);color:var(--purple);margin-left:4px" title="This item was reopened from a previously completed state">reopened</span>' : '') + ' ' +
     '<span class="dispatch-type ' + (item.type || 'implement') + '">' + escapeHtml(item.type || 'implement') + '</span>' +
     '<span class="prd-item-priority ' + (item.priority || '') + '">' + escapeHtml(item.priority || 'medium') + '</span>' +
+    (function() {
+      // W-mq08kuog001110a6 — Needs-Attention chip in the detail modal header.
+      var info = needsAttentionInfo(item);
+      if (!info) return '';
+      return ' <span class="pr-badge needs-attention" style="font-size:var(--text-xs);margin-left:4px" title="See &quot;Why this is blocked&quot; below">&#x26A0; Needs attention</span>';
+    })() +
     '</div>';
+  // W-mq08kuog001110a6 — "Why this is blocked" section, rendered FIRST so the
+  // human eye lands on the unblocking reason before scrolling through agent,
+  // source, dates, etc. _preDispatchEval reasons are evaluator prose and can
+  // be multi-line — render verbatim in a <pre> to preserve newlines.
+  (function() {
+    var info = needsAttentionInfo(item);
+    if (!info) return;
+    html += field(
+      'Why this is blocked',
+      '<div style="border-left:3px solid var(--yellow);padding:8px 10px;background:rgba(210,153,34,0.08);border-radius:var(--radius-sm)">' +
+        '<div style="font-size:var(--text-sm);color:var(--muted);margin-bottom:4px">reason: <code>' + escapeHtml(info.kind) + '</code></div>' +
+        '<pre style="margin:0;font-size:var(--text-sm);white-space:pre-wrap;word-break:break-word;font-family:var(--font-mono, monospace)">' + escapeHtml(info.full) + '</pre>' +
+      '</div>'
+    );
+  })();
   // Description: rendered from the FULL record once it's hydrated. The /api/status
   // slice drops `description` to keep the SPA payload <500KB; on first paint we
   // either render the title as a placeholder or, when description is already
@@ -788,4 +881,10 @@ function openInboxNote(filename) {
   switchPage('inbox');
 }
 
-window.MinionsWork = { wiRow, renderWorkItems, editWorkItem, submitWorkItemEdit, deleteWorkItem, archiveWorkItem, toggleWorkItemArchive, retryWorkItem, wiPrev, wiNext, feedbackWorkItem, submitFeedback, openCreateWorkItemModal, openWorkItemDetail, openAllWorkItems, viewAgentOutput, openInboxNote };
+if (typeof window !== 'undefined') {
+  window.MinionsWork = { wiRow, renderWorkItems, editWorkItem, submitWorkItemEdit, deleteWorkItem, archiveWorkItem, toggleWorkItemArchive, retryWorkItem, wiPrev, wiNext, feedbackWorkItem, submitFeedback, openCreateWorkItemModal, openWorkItemDetail, openAllWorkItems, viewAgentOutput, openInboxNote, needsAttentionInfo };
+}
+// exported for testing — pure helpers safe to require under Node (no DOM deps).
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { needsAttentionInfo };
+}

package/dashboard/styles.css

@@ -322,6 +322,8 @@
   .pr-badge.no-build { background: var(--surface); color: var(--muted); border: 1px solid var(--border); }
   .pr-badge.build-stale { background: rgba(210,153,34,0.15); color: var(--orange); border: 1px dashed var(--orange); }
   .pr-badge.build-escalated { background: rgba(248,81,73,0.25); color: var(--red); border: 2px solid var(--red); font-weight: 600; }
+  /* W-mq08kuog001110a6 — Needs-Attention chip for stuck pending work items. */
+  .pr-badge.needs-attention { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); font-weight: 600; cursor: help; }
   .error-details-btn { font-size: var(--text-xs); padding: var(--space-1) var(--space-3); margin-left: var(--space-2); background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid var(--red); border-radius: var(--radius-lg); cursor: pointer; font-weight: 600; text-transform: uppercase; letter-spacing: 0.3px; }
   .error-details-btn:hover { background: rgba(248,81,73,0.3); }
   .pr-empty { color: var(--muted); font-style: italic; font-size: var(--text-md); padding: var(--space-6) 0; }

package/dashboard.js

@@ -11477,7 +11477,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       invalidateStatusCache();
       return jsonReply(res, 200, { ok: true });
     }},
-    { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message', handler: async (req, res) => {
+    { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message, supersede? (all|unacked|<steerId>), scope? (agent|current-dispatch)', handler: async (req, res) => {
       const body = await readBody(req);
       const { agent, message } = body;
       if (!agent || !message) return jsonReply(res, 400, { error: 'agent and message required' });
@@ -11491,7 +11491,54 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         return jsonReply(res, 409, { error: 'Agent session is finishing; retry when the next session starts' });
       }
 
-      const entry = steering.writeSteeringMessage(agentId, text);
+      // W-mq066js7000fff1f-e (Gap E) — supersede prior messages before
+      // writing the new one. Accept 'all', 'unacked', or a specific
+      // steerId. Bad shapes are silently ignored (best-effort).
+      const supersede = body.supersede ? String(body.supersede).trim() : '';
+      let superseded = [];
+      if (supersede) {
+        const provisionalSteerId = `steer-pending-${Date.now()}`;
+        superseded = steering.supersedeMessages(agentId, supersede, { reason: `superseded by new steer (${supersede})`, newSteerId: provisionalSteerId });
+      }
+
+      // W-mq066js7000fff1f-e — dedupe: if no supersede arg AND an
+      // identical body is already pending within the 5-min window, echo
+      // back the existing steerId instead of writing a duplicate file.
+      if (!supersede) {
+        const dup = steering.findRecentDuplicate(agentId, text);
+        if (dup) {
+          const delivery = _steeringDeliveryState(agentId);
+          return jsonReply(res, 200, {
+            ok: true,
+            deduplicated: true,
+            steerId: dup.steerId,
+            status: dup.status || steering.STATUS.QUEUED,
+            file: dup.file,
+            // Gap D observability URL — points at the SQL delivery-state row
+            // for /api/steering/:id (back-compat with master's contract).
+            deliveryUrl: dup.steerId ? `/api/steering/${dup.steerId}` : null,
+            message: 'Identical steering message already pending — returning existing entry',
+            ...delivery,
+            inboxCount: steering.listUnreadSteeringMessages(agentId).length,
+          });
+        }
+      }
+
+      // W-mq066js7000fff1f-f (Gap F) — per-dispatch scoping. With
+      // scope='current-dispatch' we stamp the active dispatch id so the
+      // engine filters this entry out of any future unrelated dispatch's
+      // resume prompt. With scope='agent' (default) the message is
+      // agent-wide and picks up on the next dispatch regardless of id.
+      const scope = body.scope ? String(body.scope).trim().toLowerCase() : 'agent';
+      let targetDispatchId = null;
+      let scopeApplied = scope;
+      if (scope === 'current-dispatch') {
+        const active = (getDispatchQueue().active || []).find(d => d.agent === agentId);
+        if (active?.id) targetDispatchId = String(active.id);
+        else scopeApplied = 'agent'; // no active dispatch → fall back
+      }
+
+      const entry = steering.writeSteeringMessage(agentId, text, { targetDispatchId });
       const delivery = _steeringDeliveryState(agentId);
 
       // Also append to live-output.log so it shows in the chat view
@@ -11506,12 +11553,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const steerId = entry?.steerId || null;
       return jsonReply(res, 200, {
         ok: true,
+        deduplicated: false,
+        steerId,
+        status: entry?.status || (steerId ? steering.STATUS.QUEUED : null),
+        targetDispatchId: entry?.targetDispatchId || null,
+        scope: scopeApplied,
+        superseded: superseded.map(s => ({ steerId: s.steerId, previousStatus: s.previousStatus })),
         message: delivery.pendingDelivery ? 'Steering message pending delivery' : 'Steering message queued',
         ...delivery,
         file: entry?.file || null,
         inboxCount: steering.listUnreadSteeringMessages(agentId).length,
-        steerId,
-        status: steerId ? 'queued' : null,
         deliveryUrl: steerId ? `/api/steering/${steerId}` : null,
       });
     }},

package/docs/README.md

@@ -36,6 +36,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
 - [team-memory.md](team-memory.md) — Per-agent memory layer (`knowledge/agents/<id>.md`) and the consolidation/routing rules that populate it from `notes/inbox/`.
 - [watches.md](watches.md) — Persistent monitoring jobs (`engine/watches.json`): target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
+- [workspace-manifests.md](workspace-manifests.md) — Declarative per-agent permission scoping: `allowed_tools` / `allowed_repos` / `allowed_external_urls` / `memory_scope`, dispatch-time repo gate, and runtime `--allowedTools` narrowing.
 
 ## Operations
 

package/docs/workspace-manifests.md

@@ -0,0 +1,104 @@
+# Workspace Manifests — Declarative Permission Scoping for Agents
+
+> **Status:** Implemented in W-mq07avbk000m5543. Inspired by OpenAI's AGENTS.md / Workspace Manifest primitive (April 2026, [link](https://openai.com/index/the-next-evolution-of-the-agents-sdk/)).
+
+Workspace manifests move per-agent tool / repo / URL / memory permissions from implicit system-prompt text to **machine-readable, runtime-enforced declarations**. Each agent's manifest lives on its config entry and is enforced at dispatch time and spawn time without requiring agents to read or honour prompt language.
+
+## Schema
+
+A manifest lives on each agent definition under `workspace_manifest`. All fields are optional; any missing field is **permissive** (no restriction), so agents without a manifest behave exactly as they did before this feature shipped.
+
+```json
+{
+  "agents": {
+    "ralph": {
+      "name": "Ralph",
+      "role": "Engineer",
+      "skills": ["implementation", "testing"],
+      "workspace_manifest": {
+        "allowed_tools": ["Edit", "Read", "Bash", "Grep", "Glob"],
+        "allowed_repos": ["github:yemi33/minions", "opg-microsoft/minions"],
+        "allowed_external_urls": ["github.com", "*.npmjs.com"],
+        "memory_scope": "shared"
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Semantics |
+| ----- | ---- | ------- | --------- |
+| `allowed_tools` | `string[]` \| `null` | `null` (permissive) | Canonical tool-name whitelist (e.g. `Edit`, `Read`, `Bash`). Empty array = deny all. Case-sensitive. Merged into the runtime adapter's `--allowedTools` flag at spawn time. |
+| `allowed_repos` | `string[]` \| `null` | `null` (permissive) | Canonical PR-scope (`github:owner/repo`, `ado:org/proj/repo`) or bare `owner/repo`. Empty array = deny all. Case-insensitive. Enforced at dispatch time — out-of-scope dispatch fails with `failure_class: 'workspace-manifest-repo-forbidden'`. |
+| `allowed_external_urls` | `string[]` \| `null` | `null` (permissive) | Host allow-list for `web_fetch` / `web_search`. Bare host (`github.com`) = exact match; `*.example.com` = wildcard subdomain **and** apex. Empty array = deny all. Currently advisory — see "Enforcement points" below. |
+| `memory_scope` | `'private'` \| `'shared'` \| `'read-only-shared'` | `'shared'` | What slice of team knowledge the agent can read/write. Currently exposed via `shared.agentMemoryScope(agent)` for callers that want to gate inbox writes; full enforcement at the consolidation layer is future work. |
+
+## Default behaviour & backward compatibility
+
+The defaults are deliberately permissive so the manifest can be rolled out incrementally:
+
+```js
+// engine/shared.js
+const WORKSPACE_MANIFEST_DEFAULTS = {
+  allowed_tools:         null,   // no tool restriction
+  allowed_repos:         null,   // no repo restriction
+  allowed_external_urls: null,   // no URL restriction
+  memory_scope:          'shared',
+};
+```
+
+A config that never mentions `workspace_manifest` produces the exact same dispatch and spawn behaviour as the pre-manifest engine. Built-in agents (Ripley, Dallas, Lambert, Rebecca, Ralph) ship without manifests by default — manifests are an opt-in per-agent hardening primitive, not a fleet-wide default.
+
+## Enforcement points
+
+| Phase | Location | What it does |
+| ----- | -------- | ------------ |
+| **Dispatch — repo gate** | `engine.js spawnAgent()` (right after project resolution) | Calls `shared.agentCanUseRepo(agent, project)`. Mismatch → `completeDispatch(... FAILURE_CLASS.WORKSPACE_MANIFEST_REPO, agentRetryable: false)` and `cleanupTempAgent` runs. Non-retryable because the structural answer is "widen the manifest or pick a different agent". |
+| **Spawn — tool merge** | `engine.js spawnAgent()` → `_buildAgentSpawnFlags(..., allowedTools)` | `shared.mergeManifestAllowedTools(claudeConfig.allowedTools, manifest.allowed_tools)` produces the intersection of the runtime baseline and the manifest list. Result is passed as `--allowedTools <csv>` to Claude / Copilot / Codex, so the CLI itself enforces the narrowed surface. Empty manifest list (`[]`) = deny-all. Same merge runs on the steering-resume codepath. |
+| **Agent context** | Future work (playbook.js) | Manifest can be surfaced into the agent prompt so the agent sees its declared scope. Today, `shared.resolveAgentManifest(agent)` returns the resolved struct any caller can read. |
+| **URL fetch** | Advisory today | `shared.agentCanFetchUrl(agent, url)` is available for runtime intercepts. Minions itself does not currently intercept `web_fetch` inside the spawned CLI subprocess; a future runtime adapter hook can wire this. |
+| **Memory scope** | Advisory today | `shared.agentMemoryScope(agent)` is available for consolidation / playbook / inbox callers. Semantics: `private` = agent only sees its own `knowledge/agents/<id>.md`; `shared` = full team knowledge (current default); `read-only-shared` = reads shared memory but should not write inbox/notes. |
+
+## Helpers (in `engine/shared.js`)
+
+```js
+const { MEMORY_SCOPES, WORKSPACE_MANIFEST_DEFAULTS,
+        validateWorkspaceManifest, resolveAgentManifest,
+        agentCanUseRepo, agentCanUseTool, agentCanFetchUrl, agentMemoryScope,
+        mergeManifestAllowedTools, formatManifestRejection } = require('./engine/shared');
+```
+
+- `validateWorkspaceManifest(manifest)` → `{ ok, errors }`. `null`/`undefined` is valid (uses defaults).
+- `resolveAgentManifest(agent, config?)` → fresh copy of `WORKSPACE_MANIFEST_DEFAULTS` overlaid with the agent's `workspace_manifest`. Malformed manifest silently falls back to defaults; surface the error via `validateWorkspaceManifest` at config-load time.
+- `agentCanUseRepo(agent, projectOrString)` → `bool`. Accepts a project object or a string identifier (`github:owner/repo`, `ado:org/proj/repo`, or bare `owner/repo`). Case-insensitive.
+- `agentCanUseTool(agent, toolName)` → `bool`. Case-sensitive.
+- `agentCanFetchUrl(agent, url)` → `bool`. Wildcard `*.example.com` matches subdomains **and** apex.
+- `agentMemoryScope(agent)` → one of `MEMORY_SCOPES`. Unknown values fall back to `'shared'`.
+- `mergeManifestAllowedTools(baselineCsv, manifestArray)` → merged CSV. Intersection semantics: `null` manifest = baseline unchanged; empty array = deny-all; empty baseline + manifest = manifest as ceiling.
+- `formatManifestRejection({ agentId, kind, target, allowed })` → structured human-readable rejection string used by the dispatch repo gate.
+
+## Failure classes (`shared.FAILURE_CLASS`)
+
+| Code | Meaning |
+| ---- | ------- |
+| `workspace-manifest-repo-forbidden` | Dispatch routed an agent to a project not in its `allowed_repos`. Non-retryable. |
+| `workspace-manifest-tool-forbidden` | Reserved for future tool-call intercepts. Non-retryable as-is. |
+| `workspace-manifest-url-forbidden`  | Reserved for future URL-fetch intercepts. Non-retryable as-is. |
+
+## Audit trail
+
+Because rejections route through the standard `completeDispatch(... ERROR ...)` path, the existing dispatch + inbox + dashboard timeline machinery already surfaces every manifest rejection. No new state file or event topic was added. Per-agent audit of what each minion actually touched can be derived from existing `engine/dispatch.json` records filtered by `failure_class === 'workspace-manifest-repo-forbidden'`.
+
+## Rollout guidance
+
+1. Leave defaults (no manifests) until you have at least one agent that should be locked down (e.g. a contract agent that should only ever touch one repo, or an external collaborator's agent).
+2. Set `workspace_manifest.allowed_repos` first — it's the highest-impact gate and is fully enforced at dispatch time.
+3. Add `workspace_manifest.allowed_tools` for agents whose role doesn't need `Bash` / `WebFetch` / `WebSearch`. The runtime CLI enforces this, so the narrowing is hard-edged.
+4. Treat `allowed_external_urls` and `memory_scope` as documentation today; they become hard gates as we add runtime intercepts.
+
+## Related
+
+- `engine/shared.js` — manifest helpers and `FAILURE_CLASS`.
+- `engine.js spawnAgent()` — dispatch-time enforcement.
+- `test/unit/workspace-manifest.test.js` — full validator + gate + integration tests.
+- [`completion-reports.md`](completion-reports.md) — how the dispatch failure surfaces in the standard completion contract.

package/engine/shared.js

@@ -3503,6 +3503,9 @@ const FAILURE_CLASS = {
   MANAGED_SPAWN_HEALTHCHECK_FAILED: 'managed-spawn-healthcheck-failed', // P-7a3b1c92: at least one managed-spawn spec was spawned but failed its healthcheck within timeout_s. Engine killed the failing PIDs; siblings stay alive. Dispatch ERROR with the failing spec name + log tail surfaced in the inbox alert.
   INJECTION_FLAGGED: 'injection-flagged', // F5 (W-mpeklod3000we69c): the agent set `securityFlags.injectionAttempt:true` in its completion report after spotting a prompt-injection attempt inside an <UNTRUSTED-INPUT> fence. Engine writes a security inbox note + stamps `_securityFlag` on the WI and treats the dispatch as non-retryable so a human can review the source before the agent re-runs.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).
+  WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.
+  WORKSPACE_MANIFEST_TOOL: 'workspace-manifest-tool-forbidden', // W-mq07avbk000m5543: out-of-scope tool call (manifest enforcement at the runtime gate). Non-retryable as-is.
+  WORKSPACE_MANIFEST_URL: 'workspace-manifest-url-forbidden',   // W-mq07avbk000m5543: out-of-scope external URL fetch. Non-retryable as-is.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {
@@ -3594,6 +3597,243 @@ function pruneDefaultClaudeConfig(config) {
   return changed;
 }
 
+// ── Workspace Manifest (W-mq07avbk000m5543) ──────────────────────────────────
+//
+// Per-agent declarative permission manifest, inspired by OpenAI's AGENTS.md /
+// Workspace Manifest primitive (April 2026). Lives on each agent definition
+// under `workspace_manifest`:
+//
+//   {
+//     allowed_tools:         string[] | null,   // tool-name whitelist; null = no restriction
+//     allowed_repos:         string[] | null,   // canonical PR-scope or owner/repo allow-list; null = no restriction
+//     allowed_external_urls: string[] | null,   // host allow-list (apex or *.subdomain); null = no restriction
+//     memory_scope:          'private' | 'shared' | 'read-only-shared'  // default 'shared'
+//   }
+//
+// Backward compat: any null/missing field is permissive — a config with no
+// manifest behaves exactly as the pre-manifest engine did. Enforcement is
+// performed at three points today:
+//
+//   1. Dispatch time (engine.js spawnAgent): `agentCanUseRepo()` is checked
+//      against the resolved project; mismatch fails with FAILURE_CLASS.WORKSPACE_MANIFEST_REPO.
+//   2. Spawn flags (engine.js spawnAgent): `mergeManifestAllowedTools()` narrows
+//      the runtime adapter's `--allowedTools` flag so the CLI itself enforces it.
+//   3. Documentation/agent context (playbook.js): the manifest is surfaced in the
+//      agent prompt so the agent knows its scope. URL + memory_scope enforcement
+//      remains advisory pending future runtime intercepts.
+
+const MEMORY_SCOPES = ['private', 'shared', 'read-only-shared'];
+
+const WORKSPACE_MANIFEST_DEFAULTS = {
+  allowed_tools: null,
+  allowed_repos: null,
+  allowed_external_urls: null,
+  memory_scope: 'shared',
+};
+
+function _isStringArrayOrNull(value, fieldName, errors) {
+  if (value == null) return;
+  if (!Array.isArray(value)) {
+    errors.push(`workspace_manifest.${fieldName} must be an array of strings (got ${typeof value})`);
+    return;
+  }
+  for (let i = 0; i < value.length; i++) {
+    if (typeof value[i] !== 'string' || value[i].length === 0) {
+      errors.push(`workspace_manifest.${fieldName}[${i}] must be a non-empty string`);
+    }
+  }
+}
+
+/**
+ * Validate a workspace_manifest object. Returns `{ ok, errors }`.
+ * A `null`/`undefined` manifest is valid (it falls through to defaults).
+ */
+function validateWorkspaceManifest(manifest) {
+  const errors = [];
+  if (manifest == null) return { ok: true, errors };
+  if (typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { ok: false, errors: ['workspace_manifest must be an object'] };
+  }
+  _isStringArrayOrNull(manifest.allowed_tools, 'allowed_tools', errors);
+  _isStringArrayOrNull(manifest.allowed_repos, 'allowed_repos', errors);
+  _isStringArrayOrNull(manifest.allowed_external_urls, 'allowed_external_urls', errors);
+  if (manifest.memory_scope != null && !MEMORY_SCOPES.includes(manifest.memory_scope)) {
+    errors.push(`workspace_manifest.memory_scope must be one of ${MEMORY_SCOPES.join('|')} (got "${manifest.memory_scope}")`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Resolve an agent's effective workspace manifest by merging the per-agent
+ * value (if any) over `WORKSPACE_MANIFEST_DEFAULTS`. Returns a fresh copy on
+ * every call so callers can mutate the result without leaking changes back
+ * into the shared default reference.
+ *
+ * A malformed `agent.workspace_manifest` (non-object) silently falls back to
+ * defaults — the engine logs a warning at config-load time via
+ * `validateWorkspaceManifest`, so a strict reject here would just turn a
+ * documented config error into a runtime crash.
+ */
+function resolveAgentManifest(agent, _config) {
+  const out = { ...WORKSPACE_MANIFEST_DEFAULTS };
+  if (!agent || typeof agent !== 'object') return out;
+  const m = agent.workspace_manifest;
+  if (!m || typeof m !== 'object' || Array.isArray(m)) return out;
+  if (Array.isArray(m.allowed_tools)) out.allowed_tools = m.allowed_tools.slice();
+  if (Array.isArray(m.allowed_repos)) out.allowed_repos = m.allowed_repos.slice();
+  if (Array.isArray(m.allowed_external_urls)) out.allowed_external_urls = m.allowed_external_urls.slice();
+  if (typeof m.memory_scope === 'string' && MEMORY_SCOPES.includes(m.memory_scope)) {
+    out.memory_scope = m.memory_scope;
+  }
+  return out;
+}
+
+function _repoTargetToScopeCandidates(target) {
+  // Accepts a project object or a string identifier. Returns an array of
+  // lowercased canonical/shorthand strings to match against the allow-list.
+  if (!target) return [];
+  if (typeof target === 'string') {
+    const raw = target.trim();
+    if (!raw) return [];
+    const lower = raw.toLowerCase();
+    const candidates = new Set([lower]);
+    // Strip host prefix to surface the bare owner/repo form too.
+    const m = lower.match(/^(github|ado):(.+)$/);
+    if (m) candidates.add(m[2]);
+    return [...candidates];
+  }
+  if (typeof target === 'object') {
+    try {
+      const scope = getProjectPrScope(target);
+      if (scope) {
+        const lower = scope.toLowerCase();
+        const candidates = new Set([lower]);
+        const m = lower.match(/^(github|ado):(.+)$/);
+        if (m) candidates.add(m[2]);
+        return [...candidates];
+      }
+    } catch { /* defensive: malformed project — fall through */ }
+  }
+  return [];
+}
+
+/**
+ * Check whether `agent` (with its workspace_manifest) is allowed to operate
+ * against `repoTarget`. `repoTarget` may be a project object or a string
+ * (canonical `github:owner/repo` / `ado:org/proj/repo` or bare `owner/repo`).
+ *
+ * - `null`/missing manifest or `allowed_repos: null` → permissive (returns true).
+ * - Empty allow-list (`[]`) → denies everything (deliberate lockdown).
+ * - Empty/null target → returns false (cannot scope a target with no identity).
+ * - Comparison is case-insensitive; bare `owner/repo` in the manifest matches
+ *   both the host-prefixed canonical form and the bare form on the target.
+ */
+function agentCanUseRepo(agent, repoTarget) {
+  const manifest = resolveAgentManifest(agent);
+  if (manifest.allowed_repos == null) return true;
+  const candidates = _repoTargetToScopeCandidates(repoTarget);
+  if (candidates.length === 0) return false;
+  const allowed = manifest.allowed_repos.map(r => String(r).trim().toLowerCase()).filter(Boolean);
+  if (allowed.length === 0) return false;
+  // Build the same candidate set for each allow-list entry so bare owner/repo
+  // matches host-prefixed forms and vice versa.
+  for (const entry of allowed) {
+    const entryCandidates = _repoTargetToScopeCandidates(entry);
+    if (entryCandidates.some(e => candidates.includes(e))) return true;
+  }
+  return false;
+}
+
+/**
+ * Check whether `agent` may invoke `toolName`. Case-sensitive comparison —
+ * tool names are canonical (e.g. `Edit`, `Read`, `Bash`).
+ *
+ * Null/missing `allowed_tools` → permissive.
+ * Empty array → denies everything.
+ */
+function agentCanUseTool(agent, toolName) {
+  const manifest = resolveAgentManifest(agent);
+  if (manifest.allowed_tools == null) return true;
+  if (typeof toolName !== 'string' || toolName.length === 0) return false;
+  return manifest.allowed_tools.includes(toolName);
+}
+
+/**
+ * Check whether `agent` may fetch `urlString`. Wildcard entries of the form
+ * `*.example.com` match any subdomain AND the apex (`example.com`). Bare
+ * `example.com` matches only the exact host.
+ *
+ * Null/missing `allowed_external_urls` → permissive.
+ * Empty array → denies everything.
+ * Malformed URL → denied (cannot extract host to compare).
+ */
+function agentCanFetchUrl(agent, urlString) {
+  const manifest = resolveAgentManifest(agent);
+  if (manifest.allowed_external_urls == null) return true;
+  let host = '';
+  try {
+    host = new URL(String(urlString)).hostname.toLowerCase();
+  } catch { return false; }
+  if (!host) return false;
+  if (manifest.allowed_external_urls.length === 0) return false;
+  for (const raw of manifest.allowed_external_urls) {
+    const entry = String(raw).trim().toLowerCase();
+    if (!entry) continue;
+    if (entry.startsWith('*.')) {
+      const suffix = entry.slice(2);
+      if (host === suffix || host.endsWith('.' + suffix)) return true;
+    } else if (host === entry) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Return the agent's effective memory scope. Unknown values fall back to 'shared'. */
+function agentMemoryScope(agent) {
+  const manifest = resolveAgentManifest(agent);
+  return MEMORY_SCOPES.includes(manifest.memory_scope) ? manifest.memory_scope : 'shared';
+}
+
+/**
+ * Merge a manifest's `allowed_tools` list into the runtime adapter's existing
+ * `allowedTools` CSV baseline. Returns the merged CSV string the runtime
+ * adapter expects (Claude/Copilot/Codex all accept `--allowedTools <csv>`).
+ *
+ * Semantics:
+ *   - `manifestTools == null` → baseline unchanged (manifest unrestricted).
+ *   - `manifestTools == []` → empty string (deliberate deny-all lockdown).
+ *   - `baseline` empty + `manifestTools` non-empty → manifest becomes the new ceiling.
+ *   - Otherwise → intersection (manifest narrows baseline); order follows manifest.
+ */
+function mergeManifestAllowedTools(baseline, manifestTools) {
+  if (manifestTools == null) return baseline == null ? '' : baseline;
+  if (!Array.isArray(manifestTools)) return baseline == null ? '' : baseline;
+  if (manifestTools.length === 0) return '';
+  const baselineSet = (() => {
+    if (baseline == null || baseline === '') return null; // no baseline = no ceiling
+    const parts = String(baseline).split(',').map(s => s.trim()).filter(Boolean);
+    return new Set(parts);
+  })();
+  if (baselineSet == null) return manifestTools.filter(Boolean).join(',');
+  return manifestTools.filter(t => typeof t === 'string' && baselineSet.has(t)).join(',');
+}
+
+/**
+ * Build a human-readable rejection message describing an out-of-scope tool/repo/url
+ * call against an agent's manifest. Used by the dispatch repo gate (engine.js)
+ * and surfaced into the dispatch failure record + inbox alert.
+ */
+function formatManifestRejection({ agentId, kind, target, allowed } = {}) {
+  const agent = agentId || '<unknown-agent>';
+  const k = kind || 'tool';
+  const t = (typeof target === 'string' ? target : JSON.stringify(target)) || '<unknown>';
+  const allowList = Array.isArray(allowed) && allowed.length > 0
+    ? allowed.join(', ')
+    : '(none)';
+  return `workspace_manifest rejection — agent "${agent}" attempted ${k} "${t}" but its workspace_manifest.allowed_${k}s does not include it. Allowed: ${allowList}.`;
+}
+
 // ── Project Helpers ──────────────────────────────────────────────────────────
 
 function getProjects(config) {
@@ -5926,13 +6166,29 @@ function getPinnedItems() {
 // Generic rate-limit tracker reusable by both ADO and GitHub integrations.
 // Returns an object with recordThrottle, recordSuccess, isThrottled, getState.
 
-function createThrottleTracker({ label, baseBackoffMs = 60000, maxBackoffMs = 32 * 60000 } = {}) {
+function createThrottleTracker({ label, baseBackoffMs = 60000, maxBackoffMs = 32 * 60000, jitterRatio = 0.2 } = {}) {
+  // Clamp jitterRatio to [0, 0.5]. Out-of-range or non-finite inputs warn and clamp.
+  // jitter is dither on the SCHEDULED WAKE only — the deterministic 60s→32min
+  // ladder is unchanged. Server Retry-After remains the FLOOR; jitter extends
+  // upward only (multiplier in [1, 1 + jitterRatio]), never shortens.
+  let _jitterRatio = jitterRatio;
+  if (typeof _jitterRatio !== 'number' || !Number.isFinite(_jitterRatio) || _jitterRatio < 0 || _jitterRatio > 0.5) {
+    const clamped = (typeof _jitterRatio === 'number' && Number.isFinite(_jitterRatio))
+      ? Math.max(0, Math.min(0.5, _jitterRatio))
+      : 0.2;
+    log('warn', `[${label}] createThrottleTracker: invalid jitterRatio ${_jitterRatio}, clamped to ${clamped}`);
+    _jitterRatio = clamped;
+  }
+
   let state = { throttled: false, retryAfter: 0, consecutiveHits: 0, backoffMs: baseBackoffMs };
 
   function recordThrottle(retryAfterMs) {
     state.consecutiveHits++;
     state.backoffMs = Math.min(state.backoffMs * 2, maxBackoffMs);
-    const waitMs = (retryAfterMs > 0) ? retryAfterMs : state.backoffMs;
+    const baseWaitMs = (retryAfterMs > 0) ? retryAfterMs : state.backoffMs;
+    // Apply jitter on top of the base wake. Multiplier is in [1, 1 + jitterRatio]
+    // so the wake is jittered upward only — server Retry-After stays a floor.
+    const waitMs = baseWaitMs * (1 + (Math.random() * _jitterRatio));
     state.throttled = true;
     state.retryAfter = Date.now() + waitMs;
     // Throttle retries are deterministic backoff math — info, not warn.
@@ -6087,6 +6343,17 @@ module.exports = {
   DEFAULT_AGENTS,
   DEFAULT_CLAUDE,
   pruneDefaultClaudeConfig,
+  // Workspace manifest (W-mq07avbk000m5543)
+  MEMORY_SCOPES,
+  WORKSPACE_MANIFEST_DEFAULTS,
+  validateWorkspaceManifest,
+  resolveAgentManifest,
+  agentCanUseRepo,
+  agentCanUseTool,
+  agentCanFetchUrl,
+  agentMemoryScope,
+  mergeManifestAllowedTools,
+  formatManifestRejection,
   getProjects,
   formatUnknownProjectError,
   findProjectByName,

package/engine/steering.js

@@ -19,6 +19,43 @@ function _generateSteerId() {
   return `steer-${crypto.randomBytes(8).toString('hex').slice(0, 10)}`;
 }
 
+// W-mq066js7000fff1f-e (Gap E): identical-text dedupe window. POST
+// /api/agents/steer collapses identical bodies within this window to
+// the existing steerId instead of writing a duplicate inbox file.
+const DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+
+// W-mq066js7000fff1f-e/f: status enum for the inbox frontmatter +
+// supersede operations. Mirrors the steering_deliveries observability
+// table (Gap D) so callers can speak the same vocabulary regardless
+// of which storage backend is live.
+const STATUS = Object.freeze({
+  QUEUED: 'queued',
+  LIVE_KILL: 'live_kill',
+  DEFERRED: 'deferred',
+  RE_SPAWNING: 're_spawning',
+  DELIVERED: 'delivered',
+  ACKNOWLEDGED: 'acknowledged',
+  STRANDED: 'stranded',
+  DROPPED: 'dropped',
+});
+
+const UNACKED_STATUSES = new Set([
+  STATUS.QUEUED,
+  STATUS.LIVE_KILL,
+  STATUS.DEFERRED,
+  STATUS.RE_SPAWNING,
+  STATUS.STRANDED,
+]);
+
+// Statuses that should still appear as "live" in the dedupe lookup.
+const DEDUPE_CANDIDATE_STATUSES = new Set([
+  STATUS.QUEUED,
+  STATUS.LIVE_KILL,
+  STATUS.DEFERRED,
+  STATUS.RE_SPAWNING,
+  STATUS.DELIVERED,
+]);
+
 function agentInboxDir(agentId) {
   return path.join(AGENTS_DIR, agentId, 'inbox');
 }
@@ -73,15 +110,22 @@ function _readEntry(filePath, legacy = false) {
     ? fmCreatedAtMs
     : _createdAtFromPath(filePath, stat);
   const steerId = _frontmatterValue(raw, 'steerId') || null;
+  const status = _frontmatterValue(raw, 'status') || STATUS.QUEUED;
+  const targetDispatchId = _frontmatterValue(raw, 'targetDispatchId') || null;
+  const lastError = _frontmatterValue(raw, 'lastError') || null;
+  const source = _frontmatterValue(raw, 'source') || 'human';
   return {
     path: filePath,
     file: path.basename(filePath),
     createdAtMs,
     createdAt: new Date(createdAtMs).toISOString(),
-    steerId,
     raw,
     message: _messageFromRaw(raw),
     steerId,
+    status,
+    targetDispatchId,
+    lastError,
+    source,
     legacy,
   };
 }
@@ -94,10 +138,6 @@ function _uniqueSteeringPath(inboxDir, createdAtMs) {
   return filePath;
 }
 
-function _generateSteerId() {
-  return crypto.randomBytes(6).toString('hex');
-}
-
 // Contract block describing the ACK-file protocol. Injected into the prompt
 // alongside any pending steering messages so the agent knows how to confirm
 // it has read+addressed a labeled message. Mirrored verbatim into
@@ -111,9 +151,24 @@ function ackContractBlock() {
   ].join('\n');
 }
 
+function _renderFrontmatter(data) {
+  const createdAtMs = Number(data.createdAtMs) || Date.now();
+  const lines = [
+    '---',
+    `createdAt: ${new Date(createdAtMs).toISOString()}`,
+    `createdAtMs: ${createdAtMs}`,
+    `source: ${data.source || 'human'}`,
+    `steerId: ${data.steerId}`,
+    `status: ${data.status || STATUS.QUEUED}`,
+  ];
+  if (data.targetDispatchId) lines.push(`targetDispatchId: ${data.targetDispatchId}`);
+  if (data.lastError) lines.push(`lastError: ${String(data.lastError).replace(/[\r\n]+/g, ' ').trim()}`);
+  lines.push('---', '', String(data.message || '').trim(), '');
+  return lines.join('\n');
+}
+
 function writeSteeringMessage(agentId, message, opts = {}) {
   const createdAtMs = Number(opts.createdAtMs) || Date.now();
-  const createdAt = new Date(createdAtMs).toISOString();
   const inboxDir = agentInboxDir(agentId);
   fs.mkdirSync(inboxDir, { recursive: true });
   const filePath = _uniqueSteeringPath(inboxDir, createdAtMs);
@@ -134,17 +189,15 @@ function writeSteeringMessage(agentId, message, opts = {}) {
       steerId,
     }));
   }
-  const body = [
-    '---',
-    `createdAt: ${createdAt}`,
-    `createdAtMs: ${createdAtMs}`,
-    `source: ${source}`,
-    `steerId: ${steerId}`,
-    '---',
-    '',
-    bodyText,
-    '',
-  ].join('\n');
+  const body = _renderFrontmatter({
+    createdAtMs,
+    source,
+    steerId,
+    status: opts.status || STATUS.QUEUED,
+    targetDispatchId: opts.targetDispatchId || null,
+    lastError: opts.lastError || null,
+    message: bodyText,
+  });
   shared.safeWrite(filePath, body);
 
   // W-mq066js7000fff1f-a (Gap D): insert a 'queued' row into the
@@ -169,7 +222,22 @@ function writeSteeringMessage(agentId, message, opts = {}) {
   return _readEntry(filePath);
 }
 
-function listUnreadSteeringMessages(agentId, opts = {}) {
+function _updateEntryStatus(entry, newStatus, opts = {}) {
+  if (!entry?.path) return null;
+  const body = _renderFrontmatter({
+    createdAtMs: entry.createdAtMs,
+    source: entry.source || 'human',
+    steerId: entry.steerId,
+    status: newStatus,
+    targetDispatchId: entry.targetDispatchId,
+    lastError: opts.lastError !== undefined ? opts.lastError : entry.lastError,
+    message: entry.message,
+  });
+  shared.safeWrite(entry.path, body);
+  return _readEntry(entry.path);
+}
+
+function listAllSteeringEntries(agentId, opts = {}) {
   const includeLegacy = opts.includeLegacy !== false;
   const entries = [];
   const inboxDir = agentInboxDir(agentId);
@@ -189,8 +257,40 @@ function listUnreadSteeringMessages(agentId, opts = {}) {
   return entries;
 }
 
-function buildPendingSteeringPrompt(agentId) {
-  const entries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+function listUnreadSteeringMessages(agentId, opts = {}) {
+  // Back-compat shape: "unread" = anything still pending agent attention
+  // (queued/live_kill/deferred/re_spawning/delivered/stranded). Explicit
+  // 'dropped' or 'acknowledged' rows are filtered so supersede/ack don't
+  // resurrect carry-over messages on the next dispatch.
+  return listAllSteeringEntries(agentId, opts).filter(entry => {
+    const status = entry.status || STATUS.QUEUED;
+    return status !== STATUS.DROPPED && status !== STATUS.ACKNOWLEDGED;
+  });
+}
+
+// W-mq066js7000fff1f-f (Gap F): per-dispatch scoping. Callers that know
+// which dispatch they're about to spawn can pass {currentDispatchId} so
+// messages tagged for a different (older) dispatch are filtered out.
+// Pre-spawn messages (targetDispatchId null) always pass through.
+// Without currentDispatchId, no filtering happens — back-compat for
+// callers that haven't been updated to pass the dispatch id yet.
+function buildPendingSteeringPrompt(agentId, opts = {}) {
+  const includePrior = opts.includePrior === true;
+  const currentDispatchId = opts.currentDispatchId || null;
+  const allEntries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+  const entries = includePrior
+    ? allEntries
+    : allEntries.filter(entry => {
+        // Pre-spawn / agent-scoped messages (null targetDispatchId) always
+        // pick up on the next dispatch — the agent never had a chance to
+        // hear them yet.
+        if (!entry.targetDispatchId) return true;
+        // No dispatch context → don't try to filter (back-compat).
+        if (!currentDispatchId) return true;
+        // Per-dispatch messages only belong to their tagged dispatch.
+        return entry.targetDispatchId === currentDispatchId;
+      });
+
   if (entries.length === 0) return { entries, prompt: '' };
 
   const sections = [
@@ -206,6 +306,69 @@ function buildPendingSteeringPrompt(agentId) {
   return { entries, prompt: sections.join('\n') };
 }
 
+// W-mq066js7000fff1f-e (Gap E): dedupe lookup for POST /api/agents/steer.
+// Returns the existing entry whose normalized body matches `message` and
+// was created within `opts.windowMs` (default 5 min); null otherwise.
+// Only entries in "live" delivery states qualify — dropped/acknowledged
+// rows are ignored so a previously-superseded duplicate body is allowed
+// to be re-sent.
+function findRecentDuplicate(agentId, message, opts = {}) {
+  const trimmed = String(message || '').trim();
+  if (!trimmed) return null;
+  const windowMs = Number(opts.windowMs) > 0 ? Number(opts.windowMs) : DEDUPE_WINDOW_MS;
+  const now = Number(opts.now) > 0 ? Number(opts.now) : Date.now();
+  const entries = listAllSteeringEntries(agentId);
+  // Newest first — UI usually steers in a tight loop, the most recent
+  // identical message is the one we want to deduplicate against.
+  entries.sort((a, b) => b.createdAtMs - a.createdAtMs);
+  for (const entry of entries) {
+    const status = entry.status || STATUS.QUEUED;
+    if (!DEDUPE_CANDIDATE_STATUSES.has(status)) continue;
+    if (now - entry.createdAtMs > windowMs) continue;
+    if (entry.message.trim() !== trimmed) continue;
+    return entry;
+  }
+  return null;
+}
+
+// W-mq066js7000fff1f-e (Gap E): supersede prior steering messages.
+// mode:
+//   'all'      — drop every entry whose status is neither dropped nor
+//                acknowledged (queued/live_kill/deferred/re_spawning/
+//                delivered/stranded).
+//   'unacked'  — drop queued/live_kill/deferred/re_spawning/stranded but
+//                leave 'delivered' alone (agent already saw it).
+//   <steerId>  — drop the single entry with that steerId.
+// Returns the list of dropped {steerId, file, path, previousStatus}.
+function supersedeMessages(agentId, mode, opts = {}) {
+  if (!mode) return [];
+  const newSteerId = opts.newSteerId || null;
+  const reason = opts.reason || (newSteerId ? `superseded by ${newSteerId}` : 'superseded');
+  const entries = listAllSteeringEntries(agentId);
+  const dropped = [];
+  for (const entry of entries) {
+    const status = entry.status || STATUS.QUEUED;
+    let target = false;
+    if (mode === 'all') {
+      if (status !== STATUS.ACKNOWLEDGED && status !== STATUS.DROPPED) target = true;
+    } else if (mode === 'unacked') {
+      if (UNACKED_STATUSES.has(status)) target = true;
+    } else {
+      // Specific steerId
+      if (entry.steerId && entry.steerId === mode) target = true;
+    }
+    if (!target) continue;
+    _updateEntryStatus(entry, STATUS.DROPPED, { lastError: reason });
+    dropped.push({
+      steerId: entry.steerId,
+      file: entry.file,
+      path: entry.path,
+      previousStatus: status,
+    });
+  }
+  return dropped;
+}
+
 function _eventTimestampMs(obj, observedAtMs) {
   const value = obj?.timestamp || obj?.createdAt || obj?.created_at || obj?.time || obj?.data?.timestamp;
   const parsed = value ? Date.parse(value) : NaN;
@@ -342,9 +505,17 @@ module.exports = {
   ackContractBlock,
   writeSteeringMessage,
   listUnreadSteeringMessages,
+  listAllSteeringEntries,
   buildPendingSteeringPrompt,
+  findRecentDuplicate,
+  supersedeMessages,
   sessionIdFromEvent,
   sessionIdFromOutputLine,
   ackProcessedSteeringMessages,
   ackSteeringFromAckDir,
+  STATUS,
+  DEDUPE_WINDOW_MS,
+  // Exposed for unit tests only.
+  _updateEntryStatus,
+  _generateSteerId,
 };

package/engine.js

@@ -1232,6 +1232,37 @@ async function spawnAgent(dispatchItem, config) {
   }
   const metaProjectFields = metaProject && typeof metaProject === 'object' ? metaProject : {};
   const project = projectResolution.project ? { ...projectResolution.project, ...metaProjectFields } : {};
+
+  // ── Workspace manifest repo gate (W-mq07avbk000m5543) ────────────────────
+  // Dispatch-time enforcement of `agents.<id>.workspace_manifest.allowed_repos`.
+  // Built-in agents and any agent without a manifest are permissive (returns
+  // true). Temp agents (temp-*) don't appear in config.agents so they fall
+  // through to permissive as well. Mismatch fails non-retryably because the
+  // structural answer is "widen the manifest or pick a different agent" —
+  // re-spawning the same agent against the same project would deterministically
+  // re-trip the gate.
+  const _manifestAgent = (config.agents && config.agents[agentId]) || null;
+  if (project && project.name && !shared.agentCanUseRepo(_manifestAgent, project)) {
+    const _manifest = shared.resolveAgentManifest(_manifestAgent);
+    const _scope = (() => { try { return shared.getProjectPrScope(project) || project.name; } catch { return project.name; } })();
+    const msg = shared.formatManifestRejection({
+      agentId,
+      kind: 'repo',
+      target: _scope,
+      allowed: _manifest.allowed_repos,
+    });
+    log('warn', `spawnAgent: workspace-manifest repo gate denied ${agentId} → ${_scope} for ${id}`);
+    completeDispatch(
+      id,
+      DISPATCH_RESULT.ERROR,
+      msg.slice(0, 800),
+      'workspace_manifest.allowed_repos blocks this agent from this repo. Widen the manifest or route the work to a different agent.',
+      { failureClass: FAILURE_CLASS.WORKSPACE_MANIFEST_REPO, agentRetryable: false },
+    );
+    cleanupTempAgent(agentId);
+    return null;
+  }
+
   // W-mp73x32w000l143d: decouple agent cwd from worktree placement.
   // resolveSpawnPaths returns:
   //   - read-only types: { cwd: <project dir or MINIONS_DIR>, worktreeRootDir: null }
@@ -1295,7 +1326,7 @@ async function spawnAgent(dispatchItem, config) {
   // work-item prompts after setup because reused worktrees can live at arbitrary paths.
   const systemPrompt = buildSystemPrompt(agentId, config, project);
   const agentContext = buildAgentContext(agentId, config, project);
-  const pendingSteering = steering.buildPendingSteeringPrompt(agentId);
+  const pendingSteering = steering.buildPendingSteeringPrompt(agentId, { currentDispatchId: id });
   const completionReportPath = shared.dispatchCompletionReportPath(id);
   if (completionReportPath) {
     try {
@@ -2405,7 +2436,10 @@ async function spawnAgent(dispatchItem, config) {
   const args = _buildAgentSpawnFlags(runtime, {
     model: effectiveModel,
     maxTurns: _maxTurnsForType(type, engineConfig),
-    allowedTools: claudeConfig.allowedTools,
+    allowedTools: shared.mergeManifestAllowedTools(
+      claudeConfig.allowedTools,
+      shared.resolveAgentManifest(_manifestAgent).allowed_tools,
+    ),
     effort: requestedEffort,
     sessionId: cachedSessionId,
     maxBudget: resolvedMaxBudget,
@@ -2759,7 +2793,7 @@ async function spawnAgent(dispatchItem, config) {
       // Write new prompt with all unACKed steering messages. This keeps delivery
       // durable if the killed process had older pending messages that never
       // produced processing evidence before the resume.
-      const pendingForResume = steering.buildPendingSteeringPrompt(agentId);
+      const pendingForResume = steering.buildPendingSteeringPrompt(agentId, { currentDispatchId: id });
       const steerPromptBody = pendingForResume.prompt || steerMsg;
       const steerPrompt = `Message from your human teammate:\n\n${steerPromptBody}\n\nRespond to this, then continue working on your current task.`;
       const steerPromptPath = path.join(dispatchTmpDir, `prompt-steer-${safeId}.md`);
@@ -2775,7 +2809,10 @@ async function spawnAgent(dispatchItem, config) {
       const resumeArgs = _buildAgentSpawnFlags(runtime, {
         model: effectiveModel,
         maxTurns: engineConfig?.maxTurns || ENGINE_DEFAULTS.maxTurns,
-        allowedTools: claudeConfig?.allowedTools,
+        allowedTools: shared.mergeManifestAllowedTools(
+          claudeConfig?.allowedTools,
+          shared.resolveAgentManifest(_manifestAgent).allowed_tools,
+        ),
         sessionId: steerSessionId,
         maxBudget: resolvedMaxBudget,
         bare: resolvedBare,

package/package.json

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