@yemi33/minions 0.1.2454 → 0.1.2455

package/dashboard/pages/work.html

@@ -1,6 +1,7 @@
       <section id="work-items-section" style="overflow:visible">
         <h2>Work Items <span class="count" id="wi-count">0</span>
           <button class="btn-add" style="margin-left:8px" onclick="openCreateWorkItemModal()">+ New</button>
+          <button id="wi-bulk-toggle" type="button" class="pr-pager-btn" style="font-size:var(--text-sm);padding:2px 8px;margin-left:4px" onclick="wiToggleBulkMode()" aria-pressed="false" aria-controls="wi-bulk-bar" title="Enter bulk-selection mode">Bulk select</button>
           <button id="work-archive-toggle" type="button" class="pr-pager-btn" style="font-size:var(--text-sm);padding:2px 8px;margin-left:4px" onclick="toggleWorkItemArchive()" aria-expanded="false" aria-controls="work-items-archive">See Archive</button>
           <span style="font-size:var(--text-sm);color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">tasks dispatched to agents — auto-created from PRDs or added manually</span>
         </h2>
@@ -44,6 +45,18 @@
           <button class="pr-filter-reset" type="button" onclick="resetWiFilters()">Reset filters</button>
           <span class="pr-filter-summary" id="wi-filter-summary" aria-live="polite"></span>
         </div>
+        <div id="wi-bulk-bar" class="wi-bulk-bar" role="toolbar" aria-label="Bulk work-item actions" hidden>
+          <label class="wi-bulk-selectall"><input type="checkbox" id="wi-bulk-selectall-cb" onchange="wiToggleSelectAll(this)" aria-label="Select all filtered work items"> Select all</label>
+          <span id="wi-bulk-count" aria-live="polite">0 selected</span>
+          <span class="wi-bulk-actions">
+            <button type="button" class="pr-pager-btn" data-bulk-action="cancel" onclick="wiBulkAction('cancel')" disabled>Cancel</button>
+            <button type="button" class="pr-pager-btn" data-bulk-action="archive" onclick="wiBulkAction('archive')" disabled>Archive</button>
+            <button type="button" class="pr-pager-btn" data-bulk-action="retry" onclick="wiBulkAction('retry')" disabled>Retry</button>
+            <button type="button" class="btn-destructive" data-bulk-action="delete" onclick="wiBulkAction('delete')" disabled>Delete</button>
+          </span>
+          <button type="button" class="pr-filter-reset" onclick="wiClearSelection()">Clear</button>
+          <button type="button" class="pr-filter-reset" onclick="wiExitBulkMode()">Exit bulk mode</button>
+        </div>
         <div id="work-items-content"><p class="empty">No work items yet.</p></div>
         <div id="work-items-archive" style="display:none;margin-top:12px"></div>
       </section>

package/dashboard/styles.css

@@ -126,6 +126,10 @@
   .agent-name { font-weight: 600; font-size: var(--text-xl); }
   .agent-role { font-size: var(--text-base); color: var(--muted); margin-bottom: var(--space-4); }
   .status-badge { font-size: var(--text-sm); font-weight: 600; padding: var(--space-1) var(--space-4); border-radius: var(--radius-xl); text-transform: uppercase; letter-spacing: 0.5px; }
+  /* Temporary-agent marker — additive display identity next to a friendly call
+     sign. Neutral, low-emphasis pill so the temp status stays unmistakable
+     without competing with the agent name (W-msd8zdzb00i550a8). */
+  .agent-temp-badge { display: inline-block; font-size: var(--text-sm); font-weight: 600; padding: 0 var(--space-2); margin-left: var(--space-2); border-radius: var(--radius-sm); text-transform: uppercase; letter-spacing: 0.4px; vertical-align: middle; color: var(--muted); background: var(--surface); border: 1px solid var(--border); }
   .status-badge.idle { background: var(--surface); color: var(--muted); border: 1px solid var(--border); }
   .status-badge.working { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); animation: pulse 1.5s infinite; }
   .status-badge.done { background: rgba(63,185,80,0.15); color: var(--green); border: 1px solid var(--green); }
@@ -2008,3 +2012,72 @@
      height (no magic 64px, no vh). */
   html.embed-settings .modal-body.settings-body { flex: 1 1 auto; min-height: 0; }
   html.embed-settings .settings-layout { height: 100%; }
+
+  /* ── Work-item overflow menu + bulk-operations mode (W-mscjvm33007r79ef) ──
+   * The overflow (⋯) menu is rendered via document.createElement in
+   * wiOpenOverflowMenu (no innerHTML), appended to <body> and positioned under
+   * the clicked button — mirroring .checkout-mode-menu above. The bulk bar and
+   * selection affordances only appear when bulk mode is explicitly enabled. */
+  .wi-overflow-btn { line-height: 1; }
+  .wi-overflow-menu {
+    position: absolute;
+    z-index: 1000;
+    min-width: 180px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md, 6px);
+    box-shadow: 0 4px 16px rgba(0,0,0,0.3);
+    padding: 4px;
+    display: flex;
+    flex-direction: column;
+  }
+  .wi-overflow-item {
+    display: block;
+    width: 100%;
+    text-align: left;
+    padding: 6px 10px;
+    border: none;
+    background: none;
+    border-radius: 4px;
+    color: var(--text);
+    font-size: var(--text-sm);
+    font-family: inherit;
+    cursor: pointer;
+  }
+  .wi-overflow-item:hover,
+  .wi-overflow-item:focus {
+    background: var(--surface);
+    outline: none;
+  }
+  .wi-overflow-item.wi-overflow-item-destructive { color: var(--red); }
+
+  .wi-bulk-bar {
+    display: flex;
+    align-items: center;
+    gap: var(--space-4, 8px);
+    flex-wrap: wrap;
+    margin: 8px 0;
+    padding: 8px 10px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm, 4px);
+    font-size: var(--text-sm);
+  }
+  .wi-bulk-bar[hidden] { display: none; }
+  .wi-bulk-selectall {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    cursor: pointer;
+    color: var(--text);
+  }
+  #wi-bulk-count { color: var(--muted); min-width: 80px; }
+  .wi-bulk-actions { display: inline-flex; gap: 6px; flex-wrap: wrap; }
+  .wi-bulk-actions button:disabled { opacity: 0.5; cursor: default; }
+  #wi-bulk-toggle.active {
+    background: var(--blue);
+    color: #fff;
+    border-color: var(--blue);
+  }
+  .wi-bulk-cell { width: 28px; text-align: center; }
+  tr.wi-row-selected > td { background: rgba(80,140,255,0.12); }

package/dashboard-build.js

@@ -38,7 +38,7 @@ const DASHBOARD_PAGE_SUB_FRAGMENTS = {
 // Every dashboard/js/*.js file belongs here unless it is lazy-loaded through a
 // dedicated route (only memory-search.js today, served at /assets/memory-search.js).
 const DASHBOARD_JS_FILES = [
-  'utils', 'state', 'features-client', 'render-utils', 'charter-editor', 'detail-panel', 'live-stream',
+  'utils', 'agent-identity', 'state', 'features-client', 'render-utils', 'charter-editor', 'detail-panel', 'live-stream',
   'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
   'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
   'render-other', 'render-managed', 'memory-panel', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
@@ -151,7 +151,7 @@ const SLIM_JS_ORDER = [
 // charter-editor MUST precede detail-panel (see the "charter-editor registered
 // before detail-panel" test).
 const SLIM_CLASSIC_PANEL_JS = [
-  'utils', 'render-utils', 'charter-editor', 'live-stream', 'render-agents', 'detail-panel',
+  'utils', 'agent-identity', 'render-utils', 'charter-editor', 'live-stream', 'render-agents', 'detail-panel',
 ];
 
 // Cache for the assembled slim source fragments (layout/css/body/js). Keyed on

package/dashboard.js

@@ -2538,6 +2538,9 @@ let _toolsInventoryCacheTs = 0;
 let _toolsInventoryRefreshPromise = null;
 let _toolsInventoryChild = null;
 let _toolsInventoryScanner = _scanToolsInventoryInChild;
+// Most recent failed refresh ({ message, ts }); cleared on the next success.
+// Surfaced as a response header so a stale-serve still exposes refresh failure.
+let _toolsInventoryLastError = null;
 
 function _validateToolsInventoryPayload(payload) {
   if (!payload || typeof payload !== 'object'
@@ -2600,11 +2603,12 @@ function _terminateToolsInventoryChild() {
   try { shared.terminateProcess('dashboard.tools-inventory-shutdown', child); } catch { /* child may already be gone */ }
 }
 
-function _refreshToolsInventory() {
-  const now = Date.now();
-  if (_toolsInventoryCache && now - _toolsInventoryCacheTs < TOOLS_INVENTORY_CACHE_TTL_MS) {
-    return Promise.resolve(_toolsInventoryCache);
-  }
+// Start (or join) the single-flight child-process scan. Concurrent callers
+// share one in-flight promise so a burst of /api/tools polls never spawns
+// duplicate children. On success the cache + payload-derived ETag are swapped
+// in and the last-error is cleared; on failure the error is recorded (so a
+// stale-serve can still surface it) and re-thrown to the caller that awaited.
+function _startToolsInventoryScan() {
   if (_toolsInventoryRefreshPromise) return _toolsInventoryRefreshPromise;
 
   _toolsInventoryRefreshPromise = Promise.resolve()
@@ -2616,19 +2620,68 @@ function _refreshToolsInventory() {
       _toolsInventoryCacheJson = json;
       _toolsInventoryCacheEtag = `"tools-${crypto.createHash('sha256').update(json).digest('hex')}"`;
       _toolsInventoryCacheTs = Date.now();
+      _toolsInventoryLastError = null;
       return next;
     })
+    .catch(err => {
+      _toolsInventoryLastError = { message: String((err && err.message) || err), ts: Date.now() };
+      throw err;
+    })
     .finally(() => {
       _toolsInventoryRefreshPromise = null;
     });
   return _toolsInventoryRefreshPromise;
 }
 
+function _toolsInventoryAgeMs() {
+  return _toolsInventoryCacheTs ? Date.now() - _toolsInventoryCacheTs : Infinity;
+}
+
+// Resolve the tools inventory. Default (no opts) preserves the original
+// block-on-expiry contract used by the CC warm path. `{ allowStale: true }`
+// opts into stale-while-revalidate: once a cache exists it is always returned
+// immediately while a background single-flight refresh runs, so the request
+// never blocks on the multi-second child scan again. Only a truly cold cache
+// (no inventory yet) blocks so callers never see missing data. A persistently
+// failing background refresh stays visible via _toolsInventoryLastError (and
+// the X-Tools-Inventory-Error header) rather than re-introducing a blocking
+// rescan — a rescan that is itself likely to fail would just restore the very
+// ~8-10s hang this path removed.
+function _refreshToolsInventory(opts) {
+  const allowStale = !!(opts && opts.allowStale);
+  const age = _toolsInventoryAgeMs();
+
+  // Fresh — serve without a scan.
+  if (_toolsInventoryCache && age < TOOLS_INVENTORY_CACHE_TTL_MS) {
+    return Promise.resolve(_toolsInventoryCache);
+  }
+
+  // Stale-while-revalidate: any cache, however old, is served now while a
+  // single-flight background refresh runs (errors swallowed here — the
+  // recorded last-error still surfaces via the response header).
+  if (allowStale && _toolsInventoryCache) {
+    const bg = _startToolsInventoryScan();
+    if (bg && typeof bg.catch === 'function') bg.catch(() => { /* surfaced via header */ });
+    return Promise.resolve(_toolsInventoryCache);
+  }
+
+  // Cold cache (nothing to serve) — block on a fresh scan.
+  return _startToolsInventoryScan();
+}
+
 async function handleToolsInventory(req, res) {
   try {
-    await _refreshToolsInventory();
+    await _refreshToolsInventory({ allowStale: true });
+    const age = _toolsInventoryAgeMs();
+    const refreshing = _toolsInventoryRefreshPromise != null;
     res.setHeader('ETag', _toolsInventoryCacheEtag);
     res.setHeader('Cache-Control', 'private, max-age=0, must-revalidate');
+    // Freshness/error signals so the page can represent stale/refresh/error
+    // state without changing the inventory payload shape.
+    res.setHeader('X-Tools-Inventory-Age-Ms', String(Number.isFinite(age) ? age : 0));
+    if (age >= TOOLS_INVENTORY_CACHE_TTL_MS) res.setHeader('X-Tools-Inventory-Stale', '1');
+    if (refreshing) res.setHeader('X-Tools-Inventory-Refreshing', '1');
+    if (_toolsInventoryLastError) res.setHeader('X-Tools-Inventory-Error', '1');
     if (_ifNoneMatchHasEtag(req?.headers?.['if-none-match'], _toolsInventoryCacheEtag)) {
       res.statusCode = 304;
       res.end();
@@ -2653,9 +2706,26 @@ function _resetToolsInventoryCacheForTesting() {
   _toolsInventoryCacheEtag = null;
   _toolsInventoryCacheTs = 0;
   _toolsInventoryRefreshPromise = null;
+  _toolsInventoryLastError = null;
   _toolsInventoryScanner = _scanToolsInventoryInChild;
 }
 
+// Age the cache just past the fresh-TTL so the next request exercises the
+// stale-while-revalidate path (serve cached now, refresh in the background).
+function _expireToolsInventoryCacheForTesting() {
+  if (_toolsInventoryCacheTs) {
+    _toolsInventoryCacheTs = Date.now() - TOOLS_INVENTORY_CACHE_TTL_MS - 1;
+  }
+}
+
+// Age the cache back by an arbitrary amount so a test can drive it far past any
+// prior staleness window and assert the serve-cached-now contract still holds.
+function _ageToolsInventoryCacheForTesting(ageMs) {
+  if (_toolsInventoryCacheTs) {
+    _toolsInventoryCacheTs = Date.now() - ageMs;
+  }
+}
+
 function parsePinnedEntries(content) {
   if (!content) return [];
   const entries = [];
@@ -17170,7 +17240,7 @@ module.exports = {
   _resetStatusCacheForTesting,
   _ifNoneMatchHasEtag,
   _scanStatusMtimes, _refreshStatusMtimes, _resetStatusMtimeCacheForTesting, // exported for testing
-  handleToolsInventory, _refreshToolsInventory, _setToolsInventoryScannerForTesting, _resetToolsInventoryCacheForTesting, // exported for testing
+  handleToolsInventory, _refreshToolsInventory, _setToolsInventoryScannerForTesting, _resetToolsInventoryCacheForTesting, _expireToolsInventoryCacheForTesting, _ageToolsInventoryCacheForTesting, // exported for testing
   collectCcProjectSkills, _mapProjectSkillsForCc, // exported for testing
   _ensureConfiguredProjectStateFiles: ensureConfiguredProjectStateFiles, _resetInitializedProjectStatesForTesting, // exported for testing
   _countWorktrees, _refreshWorktreeCount, _scanWorktreeCount, _resetWorktreeCountCacheForTesting, // exported for testing
@@ -17326,6 +17396,22 @@ if (require.main === module) {
     Promise.resolve(queries.getKnowledgeBaseEntries())
       .catch(err => console.warn(`[dashboard] KB cache warm failed: ${err && err.message}`));
 
+    // W-msdbk1rg — warm the tools inventory (skills/commands/MCP) shortly after
+    // boot so the first Skills & MCP page open renders instantly instead of
+    // blocking ~8-10s on the cold child scan (the nested project-embedded skill
+    // walk over large monorepos dominates). Deferred + unref'd so it never
+    // competes with boot or the first /api/status snapshot, and single-flighted
+    // inside _refreshToolsInventory so it can't duplicate an in-flight scan.
+    const _toolsWarmTimer = setTimeout(() => {
+      try {
+        const pending = _refreshToolsInventory();
+        if (pending && typeof pending.catch === 'function') {
+          pending.catch(err => console.warn(`[dashboard] tools inventory warm failed: ${err && err.message}`));
+        }
+      } catch (err) { console.warn(`[dashboard] tools inventory warm failed: ${err && err.message}`); }
+    }, 3000);
+    if (typeof _toolsWarmTimer.unref === 'function') _toolsWarmTimer.unref();
+
     // Auto-open the browser. `minions restart` and the upgrade path set
     // MINIONS_NO_AUTO_OPEN=1 because the CLI orchestrates the open itself
     // after observing whether an existing tab reconnected; the primitive

package/docs/README.md

@@ -78,6 +78,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX design notes: simplified surface concepts driving the project picker, inline project link, and decoupled folder picker.
 - [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) — End-to-end hybrid memory system: file-backed inputs and consolidation, SQL/FTS5 records, retrieval and fallback, prompt bounds, episodic capture, the review-learning lifecycle (capture/recall/promotion/contradiction/diagnostics) and its rollout history + acceptance measurement, security, APIs, and operations.
+- [temporary-agents.md](temporary-agents.md) — Ephemeral `temp-<uid>` fallback agents: the opt-in `engine.allowTempAgents` + per-tick concurrency gates, in-memory naming/state, why they carry no charter/persona and no personal memory (but do get pinned/team/project memory), fleet-default runtime/model/tool/manifest resolution, routing/retry behavior, lifecycle/cleanup across restart, and isolation implications.
 - [timeouts-and-liveness.md](timeouts-and-liveness.md) — What kills (or doesn't kill) a live tracked agent: the wall-clock vs steering kill invariants, spawn-phase watchdog gates, steering safety nets, and stale-orphan detection ladder.
 - [visual-evidence-ci.md](visual-evidence-ci.md) — GitHub Actions before/after dashboard capture: path and label triggers, deterministic base/head fixtures, artifact/comment lifecycle, trust boundary, and local reproduction.
 - [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watch-plugins/` extension folder.

package/docs/copilot-cli-schema.md

@@ -22,6 +22,7 @@
 | `capabilities.systemPromptFile` | **`false`** | No `--system-prompt-file` flag exists. Inject system prompt via a `<system>` block prepended to stdin. |
 | `capabilities.effortLevels` | **`true`** | `--effort` accepts `low|medium|high|xhigh` (no `max`). Adapter must map `'max' → 'xhigh'`. |
 | `capabilities.costTracking` | **`false`** | `result.usage` contains `premiumRequests` (count, not USD), no token counts, no cost. |
+| `capabilities.billableUnit` | **`'premiumRequests'`** | Native billable unit. The adapter emits `usage.billable = { unit: 'premiumRequests', value, reported }` and the dashboard renders premium requests in the same position a USD runtime shows dollar cost. When the CLI does not report the field, `value` is `null` and `reported` is `false` (recorded as unavailable, never a fake `0`). See [runtime-adapters.md → Billable-unit usage accounting](runtime-adapters.md#billable-unit-usage-accounting). |
 | `capabilities.modelShorthands` | **`false`** | The Copilot CLI requires full model IDs (`claude-sonnet-4.5`, `gpt-5.4`). Minions may accept internal aliases (`haiku`, `sonnet`, `opus`), but the adapter translates them to Copilot model IDs before invoking the CLI. |
 | `capabilities.budgetCap` | **`false`** | No `--max-budget-usd` flag. |
 | `capabilities.bareMode` | **`false`** | No `--bare` equivalent. |

package/docs/engine-restart.md

@@ -134,8 +134,10 @@ Stopping is deliberately two commands, because "ask the engine to shut down" and
 | `minions stop --all` | Ordered whole-stack teardown: stop-intent → supervisor → dashboard → graceful engine drain → identity-verified reap → late-respawn sweep → verification. | The daemons being verified down. It reports the `engine/state.db-shm` state but does not wait for it. |
 | `minions stop --all --wait` | The same teardown, and then waits for `engine/state.db-shm` to be released. | The database handles being released, or the budget expiring. |
 
-`--timeout <ms>` sets the budget for the whole sequence (default 60000, matching
-the internal installer's quiescence window).
+`--timeout <ms>` sets the budget for the whole sequence (default 60000, the
+floor of the internal installer's quiescence window — that window is derived from
+the target runtime's own `engine.shutdownTimeout` and only ever widens from
+here, so a stop is never shorter than the wait that follows it).
 
 Bare `minions stop` is unchanged and will stay that way: recovery paths, operator
 scripts, and the engine's own callers depend on "request shutdown and return".

package/docs/internal-install.md

@@ -164,16 +164,55 @@ by `test/unit/install-internal-minions.test.js`.
    until the database handles are actually released. Release requires **both**
    signals: the processes are dead *and* `engine/state.db-shm` is absent or
    empty — a live shared-memory index means a connection still holds the WAL. If
-   the handles are not released within the bounded timeout the run **fails
-   closed**, before any uninstall or package mutation, and prints which stop path
-   was taken, the exact argv it issued, and the exact PIDs still holding the
-   database. Whether services were actually stopped is recorded so a rollback can
-   restart them. Skipped on a machine with no existing runtime.
+   the handles are not released within the derived budget (see *How long the gate
+   waits* below) the run **fails closed**, before any uninstall or package
+   mutation, and prints which stop path was taken, the exact argv it issued, the
+   budget that expired and where it came from, and the exact PIDs still holding
+   the database. Whether services were actually stopped is recorded so a rollback
+   can restart them. Skipped on a machine with no existing runtime.
 
    When the run does fail closed here, end the holders it names yourself — the
    refusal prints each surviving process by name and PID, and the dashboard is
    the usual one — then re-run the installer.
 
+   ### How long the gate waits
+
+   The wait budget is **derived from the runtime being stopped**, not fixed. It is
+   the pinned root's own `engine.shutdownTimeout` — the budget the engine gives
+   itself to drain pooled leases before exiting — plus the same grace
+   `minions restart` applies when it derives a teardown deadline the same way
+   (`engine/recovery/stop-stack.js#DRAIN_GRACE_MS`, 5 s).
+
+   | Input | Budget |
+   |-------|--------|
+   | `engine.shutdownTimeout` in the pinned root's `config.json` | that value + 5 s grace |
+   | config missing, unreadable, malformed, or nonsensical (negative, zero, non-numeric, `NaN`) | `ENGINE_DEFAULTS.shutdownTimeout` (300 s) + 5 s grace |
+   | derived budget below the floor | **floor 60 s** |
+   | derived budget above the ceiling | **ceiling 900 s (15 min)** |
+
+   A fixed window could not be right: the *runtime* decides how long a teardown
+   legitimately takes. The previous fixed 60 s was shorter than the **default**
+   drain budget of five minutes, so a busy stack was declared stuck while it was
+   still shutting down exactly as designed.
+
+   Bounded on both sides because the input is operator-supplied data this gate
+   does not own. The **floor** is `stop-stack.js#DEFAULT_STOP_TIMEOUT_MS`, so the
+   change can only ever widen the window — a runtime configured with a very short
+   drain never makes the gate stricter than it was — and the wait after a stop is
+   never shorter than the stop's own budget. The **ceiling** means a corrupt or
+   hostile `config.json` cannot hang an unattended migration indefinitely; at ~3x
+   the default runtime's budget it clamps nothing a real stack needs. A clamp is
+   named in the refusal output, so "it gave up too early" stays an answerable
+   question.
+
+   The budget is always read from the **pinned** root — the one `MINIONS_HOME` is
+   pinned to and the one whose services are being stopped — never from the
+   installing process's own root. The installer is deliberately standalone (Node
+   built-ins only, so it runs on a machine with no Minions to import from), so the
+   engine default and the grace are *mirrored* constants; a drift test in
+   `test/unit/install-internal-minions.test.js` binds both to their engine-side
+   originals so the copies cannot silently diverge.
+
    ### Which stop verb is issued
 
    The installer prefers `minions stop --all --wait`, and falls back to the bare

package/docs/named-agents.md

@@ -29,6 +29,48 @@ The `name`, `emoji`, `role`, and `expertise` fields are **human-facing metadata*
 label the agent in the dashboard and document intent. They do **not** drive dispatch (see
 §3) and the `expertise` array is not executable (see §4).
 
+### 1.1 Temporary agents and friendly call signs
+
+When every permanent agent is busy and `engine.allowTempAgents` is set, the engine
+spawns an **ephemeral agent** with a machine id of the form `temp-<uid>` (see
+[`engine/orchestration/routing.js`](../engine/orchestration/routing.js)). That canonical
+`temp-…` id is the **only** machine identity — it is unchanged for routing, SQL keys,
+filesystem paths, live-output logs, process ownership, APIs, per-agent memory rules
+(§8: `temp-*` ids are skipped for personal memory), and PR/reconciliation records.
+
+For display only, each temp agent also gets a stable, memorable **call sign** such as
+`Cosmic Comet`, rendered next to a visible `Temp` badge (`CallSign` + badge). This is
+an *additive display identity*, never a rename of the machine id.
+
+**Deterministic-from-id invariant (no persisted state).** The call sign is derived
+purely from the immutable canonical id by
+[`shared.tempAgentCallSign(id)`](../engine/core/shared.js): a single FNV-1a 32-bit hash of
+the lower-cased id selects an adjective from its low bits (`h % ADJ`) and a name from its
+high bits (`⌊h / ADJ⌋ % NAMES`), each drawn from a curated, roster-disjoint vocabulary.
+Because the derivation depends only on the id and nothing else:
+
+- **Restart- and history-stable** — the same id always yields the same call sign across
+  engine/dashboard restarts and for long-exited agents in archived/history views, so no
+  SQL migration or JSON runtime state is needed (and none is added). An already-assigned
+  name is preserved by construction — it cannot drift when the active set changes.
+- **Collision behavior is deterministic** — the ~24×24 adjective/name space plus the
+  single-hash bit-slice keeps concurrently-visible temp agents well-spread; the curated
+  `name` list is disjoint from the shipped roster (Ripley/Dallas/Lambert/Rebecca/Ralph)
+  so a call sign never equals a configured display name, and the always-visible `Temp`
+  badge disambiguates even a rare full collision.
+- **Case-insensitive** — legacy mixed-case `Temp-*` ids derive the same call sign as
+  their canonical lower-case form.
+
+The client mirrors this vocabulary + algorithm in
+[`dashboard/js/agent-identity.js`](../dashboard/js/agent-identity.js) (`MinionsAgentIdentity`),
+the single formatter every user-facing renderer calls, so a legacy record missing the
+server-stamped `agentName` still renders the identical stable call sign. Parity between
+the two implementations is asserted by
+[`test/unit/temp-agent-identity.test.js`](../test/unit/temp-agent-identity.test.js).
+API payloads expose structured fields (`id`, friendly `name`/`callSign`, `isTemp`) rather
+than replacing ids with formatted strings, and the canonical `temp-…` id stays discoverable
+in detail views/tooltips for debugging.
+
 ## 2. How an agent is configured
 
 The full per-agent config shape supported under `config.agents.<id>`:
@@ -123,6 +165,12 @@ context; `_any_` routes to any available idle agent (lowest error rate first).
 `implement:large` is selected for items with `estimated_complexity: "large"`. If both
 preferred and fallback are busy, the engine falls back to any idle agent.
 
+**Overflow → temp agents.** If no configured agent is idle and the operator has enabled
+`engine.allowTempAgents` (default off), the engine may spawn an ephemeral, personaless
+`temp-<uid>` agent as a last-resort fallback. Temp agents inherit fleet-default runtime/model/
+tools and shared/project memory but carry no charter and no personal memory. See
+[`temporary-agents.md`](temporary-agents.md).
+
 **Dispatch rules** (from `routing.md`):
 
 - **Eager by default** — the engine spawns every agent that can start work, not one at a time.

package/docs/runtime-adapters.md

@@ -108,6 +108,44 @@ marker and visible sign-off, and lifecycle persists the same value as
 `minionsReview.model`. Model catalogs are never used to guess an implicit
 runtime default.
 
+### Billable-unit usage accounting
+
+Some runtimes bill a native, non-USD unit — the GitHub Copilot CLI reports
+**premium requests** per session/turn. `parseOutput().usage` therefore carries a
+generic typed descriptor alongside the token/cost fields so the engine accounts
+for credits without ever branching on a runtime name:
+
+```js
+usage.billable = { unit: 'premiumRequests', value: <number|null>, reported: <bool> }
+```
+
+- **Authoritative, never derived.** `value` is the count the CLI reported; the
+  engine never estimates credits from tokens, model, elapsed time, or pricing.
+- **Unavailable ≠ 0.** When the installed CLI did not expose the field for a run,
+  the adapter emits `value: null, reported: false` (and Copilot leaves
+  `premiumRequests` / `costUsd` `null`, not `0`). Surfaces render unreported as
+  `N/A`, distinct from a genuine reported `0`.
+- **Already scoped — no delta diffing.** Copilot `parseOutput` reassigns
+  `usage` on each terminal `result` event, so the value is the finalized count
+  for THIS invocation / pooled turn, not a running session total. Downstream code
+  therefore **sums** per-invocation values; it does not diff cumulative counters.
+  This per-invocation scoping is what makes streamed, resumed, retried, and
+  pooled dispatches safe from double-counting.
+
+`shared.accumulateBillableUnits(target, usage.billable)` folds a descriptor into
+`target.billableUnits[unit] = { total, reported, unavailable }`, used by
+`engine/orchestration/lifecycle.js#updateMetrics` (per-agent / `_engine` /
+`_daily`) and `engine/agents/llm.js` (Command Center / doc-chat). USD is
+deliberately **excluded** from this path — dollar cost already flows through the
+richer `costUsd` + token accounting, so routing it here too would double-count.
+The map persists inside the existing metrics JSON blob (no migration; older rows
+simply lack the field), and `engine/core/queries.js#getMetrics` resolves
+`m.billableUnit` from the runtime capability so the dashboard keys off typed
+metadata, never the runtime name. A future adapter can surface its own unit by
+setting `capabilities.billableUnit` and emitting `usage.billable` — no call-site
+changes required.
+
+
 ## Capability Flags
 
 Engine code branches on consumed flags, never on runtime names. A capability
@@ -122,6 +160,7 @@ to act on that behavioral split.
 | `systemPromptFile` | ✓ | ✗ | ✗ | sysprompt via `--system-prompt-file` (else inlined into stdin by `buildPrompt`). |
 | `effortLevels` | ✓ | ✓ | ✓ | Runtime reasoning-effort controls. Codex maps through `--config model_reasoning_effort=...`; Copilot maps `'max'` to `'xhigh'`; Claude leaves `'max'` alone. |
 | `costTracking` | ✓ | ✗ | ✗ | USD + token counts in the result event. Copilot only emits `premiumRequests`; Codex accounting is not assumed. |
+| `billableUnit` | `usd` | `premiumRequests` | `usd` | Typed native billable unit for the display layer. The dashboard renders THIS unit in the same position a USD runtime shows dollar cost, switching labels/units/tooltips off the metadata — never a runtime-name branch. Adapters with no native credit unit default to `'usd'`. |
 | `modelShorthands` | ✓ | ✗ | ✗ | Bare `sonnet`/`opus`/`haiku` accepted by Claude only. |
 | `modelDiscovery` | ✗ | ✓ | ✓ | `listModels()` returns a real catalog when supported (Copilot API, Codex `debug models --bundled`). |
 | `strictModelCatalog` | — | — | ✗ | An explicit false lets the runtime validate IDs missing from its cached catalog; Codex uses this because bundled catalogs can lag staged/custom models. |