@yemi33/minions 0.1.2123 → 0.1.2124

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/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.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 }
@@ -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,
@@ -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.2124",
   "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"