@yemi33/minions 0.1.1985 → 0.1.1987

package/docs/README.md

@@ -15,6 +15,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
+- [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
 - [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
 - [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
@@ -39,6 +40,7 @@ Operational runbooks for engine operators and fleet maintainers.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
 - [onboarding.md](onboarding.md) — First-30-minutes walkthrough for a new operator: install, init, dispatch a first work item, watch it land.
+- [security.md](security.md) — Threat model: single-user/loopback deployment assumptions, dashboard Origin gate, data-flow trust boundaries, secret handling, and known residual risks (CSRF sweep, prompt injection, log-redactor audit).
 
 ---
 

package/docs/constellation-bridge.md

@@ -0,0 +1,94 @@
+# Constellation bridge
+
+Minions ships a small read-only surface that the [Constellation](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation) dashboard polls to project Minions engine state (agents, dispatch queue, PR pipeline) into its HUD. This page documents the Minions-side of that contract.
+
+> **The bridge polling logic itself lives in the Constellation repo** (`packages/agent/src/bridges/`). Minions only owns the on/off flag, the marker-file contract, and the `minions bridge` subcommand for local debugging.
+
+## Quick start
+
+```bash
+minions bridge status     # Show enabled flag + last-seen Constellation agent
+minions bridge health     # Probe http://127.0.0.1:7331/api/status and print the projection
+minions bridge enable     # Set engine.constellationBridge.enabled = true
+minions bridge disable    # Set engine.constellationBridge.enabled = false
+```
+
+## Config flag
+
+```json
+{
+  "engine": {
+    "constellationBridge": {
+      "enabled": false
+    }
+  }
+}
+```
+
+Default: `false`. The flag is backfilled into existing configs on `minions init` (including the implicit init that runs on every `minions update`).
+
+**Strict semantics.** Only the literal boolean `true` enables the bridge. Any missing, malformed, or non-boolean value (e.g. the string `"true"`, the number `1`, `null`) is treated as **disabled**. The Constellation-side reader MUST mirror this check — no truthy coercion — so a typo'd `"enabled": "false"` does not silently turn the bridge on.
+
+Toggle without editing JSON by hand:
+
+```bash
+minions bridge enable
+minions bridge disable
+```
+
+Both subcommands write `~/.minions/config.json` atomically via `mutateJsonFileLocked`, so concurrent edits from the engine/dashboard cannot tear the file.
+
+## Marker-file contract
+
+The Constellation agent's bridge writes a marker file on every successful poll. Minions reads it with `minions bridge status` so a local operator can verify the bridge is alive and Constellation is talking to it.
+
+- **Path:** `~/.minions/engine/constellation-bridge.json` (exposed as `CONSTELLATION_BRIDGE_MARKER_PATH` in `engine/shared.js`).
+- **Owner:** the Constellation agent. The Minions engine **never** writes this file — it is a one-way breadcrumb from Constellation → Minions.
+
+### Schema (`schemaVersion: 1`)
+
+```json
+{
+  "schemaVersion": 1,
+  "lastSeenAt": "2026-05-19T04:41:23.123Z",
+  "agentVersion": "0.2.3",
+  "source": "constellation-agent"
+}
+```
+
+| Field           | Required | Notes                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------ |
+| `schemaVersion` | yes      | Must equal `1`. Any other value causes Minions to ignore the marker entirely (treated as no-marker, same as a missing file). New fields are added behind a deliberate version bump. |
+| `lastSeenAt`    | yes      | ISO-8601 UTC timestamp of the last successful poll.                      |
+| `agentVersion`  | no       | Constellation agent semver string, surfaced in `bridge status`.         |
+| `source`        | no       | Free-form identifier, expected `"constellation-agent"` today.            |
+
+Writers MUST use an atomic-replace pattern (`write to tmp + rename`) so a partial write never leaves Minions reading a half-baked JSON blob.
+
+## `minions bridge health`
+
+`bridge health` performs a synchronous probe of the Minions dashboard's `GET /api/status` endpoint and prints a **curated subset** — the same fields the Constellation bridge would project into its own data model. This is intentionally small: full `/api/status` is large, unstable, and may expose unrelated local state.
+
+Sample output:
+
+```text
+bridge: dashboard reachable on http://127.0.0.1:7331
+  projection (same fields the Constellation bridge would read):
+    engineState: running
+    enginePid: 1234
+    minionsVersion: 0.1.1984
+    agentCount: 5
+    activeAgentCount: 2
+    dispatchPending: 1
+    dispatchActive: 2
+    dispatchCompleted: 14
+    projectCount: 3
+```
+
+If the dashboard is not listening, `bridge health` prints `dashboard not running on :7331 — start it with \`minions dash\`` and exits 1. Use this exit code to gate scripted health checks.
+
+## Cross-repo coordination
+
+The Constellation-side PR ([P-wi1-bridge-readonly](https://office.visualstudio.com/DefaultCollection/ISS/_git/constellation)) lands independently of this Minions PR. The Minions side merges first with the default `enabled: false`, then the Constellation side lights up bridge polling. Operators flip the flag to `true` only after both sides are deployed.
+
+The Constellation agent's bridge reads `~/.minions/config.json` directly (no Minions HTTP API call) so config edits propagate without waiting for the engine to restart.

package/docs/security.md

@@ -0,0 +1,177 @@
+# Minions Security Model
+
+This document records the threat model for Minions today. It is intentionally
+narrow: it describes what the engine and dashboard are designed to protect
+against, what they are **not** designed to protect against, and the residual
+risks an operator should know about. It is the source of truth for "is X a
+vulnerability or a documented assumption?" questions.
+
+If you are implementing a change that touches authentication, the dashboard
+HTTP surface, secret handling, or the agent prompt boundary, read this first
+and update it in the same PR if the model changes.
+
+## 1. Deployment model
+
+Minions is designed as a **single-user, localhost-only, single-tenant**
+developer tool:
+
+- One human operator runs `minions start` on a workstation (or a remote DevBox
+  they treat as their own workstation). Agents dispatched by the engine run as
+  the same OS user as the engine and dashboard.
+- The dashboard binds `127.0.0.1` only (see
+  [`dashboard.js`](../dashboard.js) — `server.listen(PORT, '127.0.0.1', ...)`)
+  and is **not** intended to be reachable from any other host.
+- Configuration, runtime state, secrets, project worktrees, and agent output
+  all live on the same machine under `MINIONS_DIR` and the operator's git
+  worktrees.
+
+**Multi-tenant deployment is explicitly out of scope.** Minions is not a
+hosted service. The engine, dashboard, agents, MCP helpers, and any tools the
+operator invokes from the same shell session form one trust domain. Anything
+that could allow a second human to share that trust domain — exposing the
+dashboard port, mirroring `MINIONS_DIR` to another user, running the engine as
+a service account read by multiple operators — is unsupported and not
+defended against here.
+
+## 2. Dashboard threat model
+
+The dashboard (`dashboard.js`, port 7331) is the only HTTP surface in the
+system. Its threat model:
+
+### In scope (intentional, not vulnerabilities)
+
+- **Loopback bind.** The dashboard binds `127.0.0.1` only; no LAN, container,
+  or VPN client can reach it. Operators who tunnel the port elsewhere (SSH
+  port forward, `ngrok`, etc.) opt out of this assumption and inherit
+  responsibility for whatever auth gate they place in front.
+- **Same-user process access.** Any process running as the same OS user as
+  the engine (other agent runtimes, MCP helpers, `curl` from a terminal,
+  `minions` CLI subcommands) can call `/api/*`. This is intentional — it is
+  how `minions dispatch`, the Copilot/Claude runtimes, and operator scripts
+  drive the engine. We do not attempt to authenticate same-user callers.
+- **No authentication gate.** There is no login, no session cookie, no
+  per-user ACL. The single-user assumption above is the entire authn story.
+  Adding authn would not increase security in the single-user model; it would
+  only break local CLI/MCP tooling.
+
+### Residual risks defended today
+
+- **Cross-origin browser requests / CSRF / DNS rebinding.** A browser tab the
+  operator visits could in principle issue requests to `http://127.0.0.1:7331`.
+  The dashboard defends against this with:
+  - An **Origin gate** on mutating methods (`POST`/`PUT`/`PATCH`/`DELETE`)
+    and CORS preflights — see `dashboard.js` ~3677–3730 and
+    `shared.isAllowedOrigin` / `shared.buildSecurityHeaders` in
+    [`engine/shared.js`](../engine/shared.js). Requests whose `Origin` (or
+    `Referer`, if `Origin` is absent) is not in the local allowlist are
+    rejected with HTTP 403. Callers without an `Origin` header at all
+    (Node `http.request`, `curl` without `-H Origin`, CLI tooling) are
+    allowed through to preserve local automation.
+  - Baseline **security headers** (CSP, `X-Content-Type-Options`,
+    `Referrer-Policy`, clickjacking protections) applied to every response
+    via `shared.buildSecurityHeaders()`.
+
+### Residual risks tracked elsewhere
+
+- **CSRF hardening sweep.** A broader hardening pass — deny-by-default CORS,
+  `Sec-Fetch-Site: same-origin` enforcement on mutating endpoints, and an
+  optional bearer-token gate as a secondary defense — is **deferred to a
+  separate plan** (`D-f8-csrf` in
+  `prd/security-fix-plan-from-weekly-review-2026-05-18.json`, open question
+  `Q-csrf-followup`). This document does not gate that work; if and when the
+  CSRF follow-up plan ships, update §2 to reflect the new posture.
+
+### Recommended hardening (if F8 ever moves from docs to code)
+
+If we revisit this assumption — e.g. the dashboard ever serves more than one
+operator, or we want defense-in-depth beyond Origin checks — the recommended
+shape is:
+
+1. Reject mutating requests whose `Origin` / `Sec-Fetch-Site` is not
+   `same-origin`, instead of the current allowlist + missing-header pass-through.
+2. Switch CORS to deny-by-default and explicitly opt specific endpoints in.
+3. Add an optional bearer token (operator-supplied via env) as a secondary
+   gate; require it on mutating endpoints when set.
+4. Document the resulting break in CLI/MCP tooling and provide a token
+   injection path for it.
+
+## 3. Data flow trust boundaries
+
+Minions reads from several sources with very different trust levels. The
+engine and dashboard treat them differently on purpose:
+
+| Source | Trust | Examples | Handling |
+|---|---|---|---|
+| **Operator config** | Trusted | `config.json`, `projects/`, `notes.md`, `notes/inbox/*` authored by the human, `pinned.md` | Read as-is. The operator is assumed to control these files. |
+| **Agent output** | Semi-trusted | Completion reports, fenced `completion` blocks, learnings notes, PR comments authored by the shared `gh` identity | Schema-validated; completion JSON is gated by the per-spawn nonce (`MINIONS_COMPLETION_NONCE`, see [`completion-reports.md`](completion-reports.md) → "Trust boundary"). Reports without a valid nonce are rejected with `failure_class: 'completion-nonce-mismatch'`. |
+| **External APIs** | Untrusted | GitHub REST/GraphQL responses, Azure DevOps REST responses, GitHub/ADO PR comment bodies, CI/run logs | Validated and shape-checked before persistence. Strings sourced from these responses are never passed as raw arguments to shells or `git`; see F2 (gh shell-injection fix) and F7 (`git log` execFile conversion) in the same security plan. |
+| **Agent-controlled paths** | Untrusted | Paths supplied to dashboard endpoints by agents (e.g. `/api/agent-output`) | Normalized through `shared.sanitizePath` to constrain to the expected root; see F4 in the same plan. |
+
+The agent-output trust boundary deserves emphasis: completion reports are the
+single most powerful signal an agent can emit (they advance work-item status,
+mark PRs reviewed, trigger merges). The nonce gate exists specifically so a
+report written by an unrelated process — or by a stale dispatch from a
+previous tick — cannot be silently consumed. Anything in the report body
+itself remains agent-controlled and is treated as such (no `eval`, no shell
+interpolation, schema-validated fields only).
+
+## 4. Secret management
+
+- **PATs and API tokens live in environment variables only.** GitHub tokens
+  (`GH_TOKEN`, `COPILOT_GITHUB_TOKEN`), Azure DevOps PATs, and any
+  runtime-specific credentials are read from the engine's process
+  environment. They are not persisted to `config.json`, work-item state,
+  PR metadata, or any other on-disk JSON Minions owns.
+- **Tokens are never intentionally logged.** Engine code that shells out to
+  `gh` or the ADO CLI threads the token via per-call `GH_TOKEN=...`
+  environment injection (see `engine/gh-token.js`), so the value never
+  appears on a command line or in `live-output.log`.
+- **The log redactor is best-effort, not authoritative.** A best-effort
+  redactor scrubs token-shaped strings from logs and agent output, but its
+  coverage has **not** been formally audited (deferred as `D-f9`, open
+  question `Q-f9-log-redactor`). Treat redaction as a defense-in-depth nicety,
+  not a guarantee — do not rely on it to keep a leaked token out of an
+  uploaded log bundle. If a token may have appeared in output, rotate it.
+
+## 5. Known limitations
+
+These are accepted limitations of the current model. They are documented
+rather than fixed because (a) they are out of scope for the single-user
+threat model, (b) they are tracked under other items, or (c) a fix would
+break operator workflows we want to preserve.
+
+- **No authentication gate on the dashboard.** Intentional — see §2. The
+  single-user UX (and `minions` CLI, MCP integrations, and operator scripts
+  that POST to `/api/*` without juggling a token) depends on this. Revisit
+  only if the deployment model in §1 changes.
+- **Prompt-injection surface from PR comments and inbox notes.** Agent
+  prompts splice in human-authored content (pinned notes, `notes/inbox/*`,
+  PR comment bodies, `pendingHumanFeedback`) without a fenced delimiter
+  separating "instructions" from "data." A malicious PR comment author
+  could attempt to steer an agent that reads the comment thread. Mitigation
+  (F5 — delimited untrusted content blocks) is **blocked on an open
+  question** (`Q-f5-delimiter`) about which delimiter token to standardize
+  on. Until F5 lands, operators should treat external PR comment threads
+  as a low-but-nonzero injection surface.
+- **Temp-file predictability.** Per-dispatch temp paths can be predictable
+  in some shells, opening a narrow TOCTOU window for a same-user process to
+  race the engine. Tracked as **F6** in this same security plan
+  (`P-f6-tmp-toctou`); the fix moves dispatch temp dirs to per-spawn unique
+  paths with restrictive permissions.
+- **Log redactor coverage is unaudited.** See §4 and `D-f9` /
+  `Q-f9-log-redactor`. Until the audit lands, treat any log bundle that
+  might contain agent output, CI logs, or `live-output.log` excerpts as
+  potentially containing tokens, and rotate accordingly.
+- **CSRF hardening sweep is deferred.** See §2. Origin gate + security
+  headers are in place today; the broader sweep (deny-by-default CORS,
+  `Sec-Fetch-Site` enforcement, optional bearer token) is `D-f8-csrf` /
+  `Q-csrf-followup`.
+
+---
+
+**Updating this doc:** If you change the dashboard's bind address, add or
+remove an authn/authz mechanism, change how completion reports are trusted,
+change how secrets are read, or land any of F5 / F6 / F9 / the CSRF
+follow-up, update the relevant section here in the same PR. Keep the
+"in-scope vs residual vs deferred" split — it is the part reviewers come
+back to.

package/engine/bridge.js

@@ -0,0 +1,124 @@
+/**
+ * engine/bridge.js — Constellation-bridge config + marker accessors.
+ *
+ * Pure helpers for the `minions bridge ...` subcommand and any future
+ * code that wants to inspect or mutate the read-only Constellation bridge
+ * surface. The bridge polling logic itself lives in the Constellation
+ * repo (P-wi1-bridge-readonly) — this file owns ONLY the on/off flag, the
+ * marker-file contract, and atomic config writes for the toggle.
+ *
+ * Strict semantics: only the literal boolean `true` enables the bridge.
+ * Mirror this check on the Constellation reader to avoid truthy coercion
+ * silently flipping bridge state on a typo'd `"enabled": "false"`.
+ */
+
+const path = require('path');
+const shared = require('./shared');
+
+const {
+  MINIONS_DIR,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
+  safeJson,
+  mutateJsonFileLocked,
+} = shared;
+
+const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
+
+/**
+ * Strict check: `true` ⇔ bridge enabled. Any other shape (missing field,
+ * non-object, string "true", etc.) returns false.
+ */
+function isBridgeEnabled(config) {
+  return config?.engine?.constellationBridge?.enabled === true;
+}
+
+/**
+ * Read the cross-repo marker written by the Constellation agent. Returns
+ * `null` when the file is missing, unreadable, or schema-mismatched.
+ *
+ * Marker shape (see ENGINE_DEFAULTS.constellationBridge docstring):
+ *   { schemaVersion: 1, lastSeenAt: ISO8601,
+ *     agentVersion?: string, source?: 'constellation-agent' }
+ */
+function readBridgeMarker(markerPath = CONSTELLATION_BRIDGE_MARKER_PATH) {
+  const raw = safeJson(markerPath);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.schemaVersion !== CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION) return null;
+  if (typeof raw.lastSeenAt !== 'string') return null;
+  return {
+    schemaVersion: raw.schemaVersion,
+    lastSeenAt: raw.lastSeenAt,
+    agentVersion: typeof raw.agentVersion === 'string' ? raw.agentVersion : null,
+    source: typeof raw.source === 'string' ? raw.source : null,
+  };
+}
+
+/**
+ * Flip `config.engine.constellationBridge.enabled` atomically via
+ * mutateJsonFileLocked. Returns `{ previous: bool, current: bool }`.
+ * `configPath` override exists for unit tests.
+ */
+function setBridgeEnabled(enabled, configPath = CONFIG_PATH) {
+  const next = enabled === true;
+  let previous = false;
+  mutateJsonFileLocked(configPath, (cfg) => {
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return cfg;
+    cfg.engine = cfg.engine || {};
+    cfg.engine.constellationBridge = cfg.engine.constellationBridge || {};
+    previous = cfg.engine.constellationBridge.enabled === true;
+    cfg.engine.constellationBridge.enabled = next;
+    return cfg;
+  });
+  return { previous, current: next };
+}
+
+/**
+ * Human-readable relative age string (e.g. "12s ago", "3m ago", "2h ago").
+ * Caps at "1d+ ago" — anything older than the bridge polling cadence is
+ * already actionable as "stale".
+ */
+function formatRelativeAge(isoTimestamp, nowMs = Date.now()) {
+  const t = Date.parse(isoTimestamp);
+  if (!Number.isFinite(t)) return '(unknown)';
+  const deltaSec = Math.max(0, Math.round((nowMs - t) / 1000));
+  if (deltaSec < 60) return `${deltaSec}s ago`;
+  if (deltaSec < 3600) return `${Math.round(deltaSec / 60)}m ago`;
+  if (deltaSec < 86400) return `${Math.round(deltaSec / 3600)}h ago`;
+  return '1d+ ago';
+}
+
+/**
+ * Compose the small stable projection the Constellation bridge consumes
+ * from `/api/status`. Kept narrow on purpose: full /api/status is large,
+ * unstable, and may surface unrelated local state. New fields go behind
+ * a deliberate schema version bump.
+ */
+function projectStatusForBridge(statusJson) {
+  if (!statusJson || typeof statusJson !== 'object') return null;
+  const dispatch = statusJson.dispatch || {};
+  const queueCount = (arr) => (Array.isArray(arr) ? arr.length : 0);
+  return {
+    engineState: statusJson.control?.state ?? null,
+    enginePid: statusJson.control?.pid ?? null,
+    minionsVersion: statusJson.version ?? null,
+    agentCount: Array.isArray(statusJson.agents) ? statusJson.agents.length : null,
+    activeAgentCount: Array.isArray(statusJson.agents)
+      ? statusJson.agents.filter(a => a && a.status && a.status !== 'idle').length
+      : null,
+    dispatchPending: queueCount(dispatch.pending),
+    dispatchActive: queueCount(dispatch.active),
+    dispatchCompleted: queueCount(dispatch.completed),
+    projectCount: Array.isArray(statusJson.projects) ? statusJson.projects.length : null,
+  };
+}
+
+module.exports = {
+  isBridgeEnabled,
+  readBridgeMarker,
+  setBridgeEnabled,
+  formatRelativeAge,
+  projectStatusForBridge,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
+};

package/engine/cc-worker-pool.js

@@ -136,6 +136,12 @@ class Worker {
     this.killed = false;
     this.spawnError = null;
     this.firstSystemPromptSent = false;
+    // In-flight spawn+initialize+session/new promise. Set by getSession()
+    // before the worker is registered in _tabs, cleared after the handshake
+    // settles. Racing getSession() callers await this to avoid the
+    // "warm-reuse path returns sessionId=null while init is still pending"
+    // hang on first message of a freshly-warmed tab (W-mpd45blx00072f04).
+    this.initPromise = null;
   }
 
   // ── Spawn + initialize handshake ────────────────────────────────────────
@@ -499,6 +505,31 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
   //   'cold-spawn'  — fresh proc + initialize + session/new
   let lifecycle = 'warm-reuse';
 
+  if (worker) {
+    // W-mpd45blx00072f04: if the existing worker is still mid-init (warm
+    // fired but session/new hasn't resolved yet), await the in-flight init
+    // BEFORE evaluating warm-reuse / newSession / cold-spawn — otherwise we
+    // return a SessionHandle with sessionId=null and the caller's first
+    // session/prompt fires with a null sessionId, causing every subsequent
+    // session/update notification to be dropped by _handleMessage's
+    // sessionId-match guard. User-visible symptom: first message on a
+    // freshly-warmed CC tab hangs (no chunks streamed, eventual onDone
+    // with empty text).
+    if (worker.initPromise) {
+      try {
+        await worker.initPromise;
+      } catch (err) {
+        // Warm init failed (e.g., auth). The originating call has already
+        // (or is about to) delete _tabs[tabId] and close the worker in its
+        // own catch handler. Surface the same error to this caller so the
+        // dashboard's spawn-failed path runs instead of hanging.
+        throw err;
+      }
+      // Re-read in case the failing initPromise's cleanup already ran.
+      worker = _tabs.get(tabId) || null;
+    }
+  }
+
   if (worker) {
     if (worker.killed) {
       _tabs.delete(tabId);
@@ -533,8 +564,24 @@ async function getSession({ tabId, model, effort, mcpServers, systemPromptHash,
       tabId, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd,
     });
     _tabs.set(tabId, worker);
+    // Set initPromise BEFORE awaiting so concurrent getSession() callers
+    // landing during the spawn+initialize+session/new round-trip can detect
+    // and await it (W-mpd45blx00072f04). Clear on settle so callers that
+    // arrive AFTER init succeeds skip the no-op await. Attach the clear
+    // handler as both success+failure listeners (not .finally()) so the
+    // chained promise has a rejection handler and doesn't surface as an
+    // unhandled rejection when init throws.
+    const initPromise = worker._spawnAndInit();
+    worker.initPromise = initPromise;
+    const clearInit = () => {
+      // Only clear if we're still the active promise — defensive against
+      // a future refactor that calls _spawnAndInit twice for the same
+      // Worker (current code path never does).
+      if (worker.initPromise === initPromise) worker.initPromise = null;
+    };
+    initPromise.then(clearInit, clearInit);
     try {
-      await worker._spawnAndInit();
+      await initPromise;
     } catch (err) {
       _tabs.delete(tabId);
       try { worker.close(); } catch { /* already torn down */ }

package/engine/cleanup.js

@@ -273,35 +273,42 @@ function _killProcessInWorktree(dir, activeProcesses, activeIds) {
     log('info', `Killed orphaned process for dispatch ${id} before worktree removal`);
   }
 
-  // Check PID files in engine/tmp/ — only kill if no active dispatch matches
+  // Check PID files in engine/tmp/ — both legacy flat layout and per-dispatch
+  // dirs (P-f6-tmp-toctou). Only kill if no active dispatch matches.
   try {
-    const tmpDir = path.join(ENGINE_DIR, 'tmp');
-    for (const f of fs.readdirSync(tmpDir)) {
-      if (!f.startsWith('pid-') || !f.endsWith('.pid')) continue;
-      const pidFileName = f.replace(/^pid-/, '').replace(/\.pid$/, '');
-      if (!dirLower.includes(pidFileName.slice(-8))) continue;
+    shared.forEachPidFile((pidFilePath, fileName, layout) => {
+      const pidFileName = fileName.replace(/^pid-/, '').replace(/\.pid$/, '');
+      if (!dirLower.includes(pidFileName.slice(-8))) return;
       // Verify this PID file's dispatch is not active
       let isActive = false;
       for (const id of activeIds) { if (pidFileName.includes(id.slice(-8))) { isActive = true; break; } }
-      if (isActive) continue; // still active — do not kill
-      const pid = parseInt(fs.readFileSync(path.join(tmpDir, f), 'utf8').trim(), 10);
+      if (isActive) return; // still active — do not kill
+      let pid;
+      try { pid = parseInt(fs.readFileSync(pidFilePath, 'utf8').trim(), 10); }
+      catch { return; }
       if (pid > 0) {
         // Verify the PID still belongs to a Minions runtime process before killing.
         // The shared helper inspects the PID's full command line for `claude` /
         // `copilot` so a recycled PID running an unrelated process is skipped.
         try {
           if (process.platform === 'win32') {
-            if (!shared.isProcessCommandLineMatchingAgent(pid)) continue;
+            if (!shared.isProcessCommandLineMatchingAgent(pid)) return;
             exec(`taskkill /F /T /PID ${pid}`, { stdio: 'pipe', timeout: 5000, windowsHide: true });
           } else {
-            if (!shared.isProcessCommandLineMatchingAgent(pid)) continue;
+            if (!shared.isProcessCommandLineMatchingAgent(pid)) return;
             try { process.kill(-pid, 'SIGKILL'); } catch { process.kill(pid, 'SIGKILL'); }
           }
-          log('info', `Killed orphaned PID ${pid} (${f}) before worktree removal`);
+          log('info', `Killed orphaned PID ${pid} (${fileName}, ${layout}) before worktree removal`);
         } catch {} // process may already be dead
       }
-      try { fs.unlinkSync(path.join(tmpDir, f)); } catch {}
-    }
+      if (layout === 'dispatch-dir') {
+        // Remove the entire per-dispatch dir — its remaining sidecars are
+        // orphans of the same dead process.
+        try { shared.removeDispatchTmpDir(path.dirname(pidFilePath)); } catch {}
+      } else {
+        try { fs.unlinkSync(pidFilePath); } catch {}
+      }
+    });
   } catch {} // tmp dir may not exist
 }
 
@@ -313,9 +320,35 @@ async function runCleanup(config, verbose = false) {
   let cleaned = { tempFiles: 0, liveOutputs: 0, worktrees: 0, zombies: 0 };
 
   // 1. Clean stale temp prompt/sysprompt files and orphaned safeWrite .tmp.* files (older than 1 hour)
+  // P-f6-tmp-toctou: also sweep abandoned per-dispatch dirs (engine/tmp/dispatch-*),
+  // and recurse into them so leftover prompt/sysprompt sidecars from crashed
+  // dispatches don't accumulate.
   const oneHourAgo = Date.now() - 3600000;
   const tmpDir = path.join(ENGINE_DIR, 'tmp');
   const scanDirs = [ENGINE_DIR, ...(fs.existsSync(tmpDir) ? [tmpDir] : [])];
+  // Discover dispatch-* dirs under engine/tmp/ and scan their contents too.
+  if (fs.existsSync(tmpDir)) {
+    try {
+      for (const entry of fs.readdirSync(tmpDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (!entry.name.startsWith('dispatch-')) continue;
+        const full = path.join(tmpDir, entry.name);
+        if (!shared.validateDispatchTmpDir(full)) continue;
+        scanDirs.push(full);
+      }
+    } catch { /* tmp dir may be empty/missing */ }
+  }
+  // Track which dispatch dirs we touch so we can rm empty ones whose owning
+  // dispatch is no longer in the active set.
+  const activeDispatchTmpDirs = new Set();
+  try {
+    const dispatch = getDispatch();
+    for (const queue of ['pending', 'active']) {
+      for (const e of dispatch[queue] || []) {
+        if (e?.tmpDir) activeDispatchTmpDirs.add(path.resolve(e.tmpDir));
+      }
+    }
+  } catch { /* dispatch.json may be empty */ }
   for (const dir of scanDirs) {
     // Each directory gets its own try-catch so one failure doesn't abort other directories (Bug #27)
     let dirEntries;
@@ -341,6 +374,22 @@ async function runCleanup(config, verbose = false) {
       }
     }
   }
+  // Reap empty/stale per-dispatch tmp dirs not referenced by an active entry.
+  cleaned.dispatchDirs = 0;
+  if (fs.existsSync(tmpDir)) {
+    try {
+      for (const entry of fs.readdirSync(tmpDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith('dispatch-')) continue;
+        const full = path.join(tmpDir, entry.name);
+        if (!shared.validateDispatchTmpDir(full)) continue;
+        if (activeDispatchTmpDirs.has(path.resolve(full))) continue;
+        let stat;
+        try { stat = fs.statSync(full); } catch { continue; }
+        if (stat.mtimeMs >= oneHourAgo) continue;
+        if (shared.removeDispatchTmpDir(full)) cleaned.dispatchDirs++;
+      }
+    } catch { /* sweep is best-effort */ }
+  }
 
   // 2. Clean live-output.log and live-output-prev.log for idle agents (not currently working)
   for (const [agentId] of Object.entries(config.agents || {})) {
@@ -1111,31 +1160,31 @@ async function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'cap cooldowns: ' + e.message); }
 
   // 12. Clean stale PID files — remove PID files whose process is no longer running
+  // P-f6-tmp-toctou: walks BOTH legacy flat layout and per-dispatch-dir layout
+  // via shared.forEachPidFile.
   cleaned.pidFiles = 0;
   try {
     const tmpDir = path.join(ENGINE_DIR, 'tmp');
     if (fs.existsSync(tmpDir)) {
-      let pidDirEntries;
-      try { pidDirEntries = fs.readdirSync(tmpDir); } catch { pidDirEntries = []; }
       const activePids = new Set();
       for (const [, info] of activeProcesses) {
         if (info.proc?.pid) activePids.add(String(info.proc.pid));
       }
-      for (const f of pidDirEntries) {
-        if (!f.startsWith('pid-') || !f.endsWith('.pid')) continue;
-        const fp = path.join(tmpDir, f);
+      shared.forEachPidFile((pidFilePath, fileName, layout) => {
         try {
-          const pidStr = fs.readFileSync(fp, 'utf8').trim();
+          const pidStr = fs.readFileSync(pidFilePath, 'utf8').trim();
           // Skip if actively tracked
-          if (activePids.has(pidStr)) continue;
+          if (activePids.has(pidStr)) return;
           // Check if file is stale (>1 hour old)
-          const stat = fs.statSync(fp);
+          const stat = fs.statSync(pidFilePath);
           if (stat.mtimeMs < oneHourAgo) {
-            fs.unlinkSync(fp);
+            fs.unlinkSync(pidFilePath);
             cleaned.pidFiles++;
+            // For dispatch-dir layout, the empty/stale dispatch dir gets reaped
+            // by the stale-dispatch-dir sweep in step 1.
           }
         } catch { /* cleanup */ }
-      }
+      });
     }
   } catch (e) { log('warn', 'clean stale PID files: ' + e.message); }