@yemi33/minions 0.1.2454 → 0.1.2455

package/docs/temporary-agents.md

@@ -0,0 +1,172 @@
+# Temporary Agents — ephemeral `temp-<uid>` fallback dispatch
+
+Minions normally dispatches work to a fixed roster of **named agents** (Ripley, Dallas, …;
+see [`named-agents.md`](named-agents.md)). When every eligible named agent is busy and the
+operator has opted in, the engine can spawn a **temporary agent** — a one-shot, unnamed
+`temp-<uid>` identity that exists only to absorb overflow work so the queue does not stall.
+
+This document describes the complete temp-agent behavior, verified against the current
+implementation. Temp agents are deliberately minimal: they have **no charter, no persona,
+no personal memory, and no persistent config record**. They are a scheduling escape valve,
+not a sixth teammate.
+
+> Orientation only — the load-bearing contracts live in code. Cross-references:
+> [`named-agents.md`](named-agents.md), [`team-memory.md`](team-memory.md),
+> [`workspace-manifests.md`](workspace-manifests.md), [`runtime-adapters.md`](runtime-adapters.md),
+> and [`../CLAUDE.md`](../CLAUDE.md).
+
+## 1. When and why a temp agent is created
+
+Temp agents are an **opt-in, last-resort** step of agent resolution in
+`resolveAgent(workType, config, opts)` (`engine/orchestration/routing.js`). Resolution tries,
+in order: agent hints → routing `preferred` → routing `fallback` → any idle configured agent
+(lowest error rate first). Only if **all** of those miss does it consider a temp agent, and
+only when every one of these gates passes:
+
+1. **Config gate — `engine.allowTempAgents`.** Defaults to **`false`**
+   (`ENGINE_DEFAULTS.allowTempAgents`, `engine/core/shared.js`). With it off, `resolveAgent`
+   returns `null` and the work item simply stays `pending` until a named agent frees up — no
+   temp is ever created (`engine/orchestration/routing.js`, the `if (config.engine?.allowTempAgents)`
+   branch). It is exposed as a Settings toggle ("Allow Temp Agents", `set-allowTempAgents`) in
+   `dashboard/js/settings.js` and surfaced on `GET /api/*` status via `dashboard.js`.
+2. **Concurrency gate — per-tick temp budget.** The engine calls `setTempBudget(maxConcurrent - activeCount)`
+   once per tick (`engine.js`), so temps count against `engine.maxConcurrent` exactly like
+   named agents. When the budget is exhausted, `resolveAgent` logs
+   `Temp agent refused … per-tick budget exhausted` and returns `null`. This guard stops a
+   mass-discovery pass (e.g. a PR-poll sweep over 20 failing PRs) from registering one temp per
+   pending item and spawning far more processes than `maxConcurrent` allows (closes #1209).
+
+Because a `temp-<uid>` id is by construction never equal to a named author agent, a temp is
+always a valid **non-author** reviewer under the self-review ban, and a valid reassignment
+target under `excludeAgent`. Temp creation is also the documented fallback for the
+**decompose** flow: when `engine.autoDecompose` splits an `implement:large` item and all
+permanent agents are busy, the engine can spawn a `temp-<uid>` to run a sub-task
+(see [`../CLAUDE.md`](../CLAUDE.md) → "Decomposition").
+
+## 2. Naming and runtime/state representation
+
+- **Id:** `temp-${shared.uid()}` — e.g. `temp-mscilxge004b1de2`. The `temp-` prefix is a
+  reserved sentinel checked throughout the engine; a configured agent id may not collide with
+  it (`docs/specs/agent-configurability.md`).
+- **Display name / role:** `{ name: "Temp-<4chars>", role: "Temporary Agent" }`, derived from
+  characters 5–8 of the id (`engine/orchestration/routing.js`).
+- **In-memory only:** the record lives in a module-level `Map` `tempAgents` in
+  `engine/orchestration/routing.js` (`tempAgentId → { name, role, createdAt }`). It is **not**
+  written to `config.json`, and **not** persisted to SQLite. The authoritative agent identity
+  for the work travels on the work item / dispatch record (`item.agent`, `item.agentName`,
+  `item.agentRole`), which persist normally.
+- **Dashboard/API:** an *active* temp agent is added to the agent roster snapshot by
+  `engine/core/queries.js#getAgents` with `emoji: 💨`, `expertise: []`, and `_temp: true`, so
+  it shows up as a tile while it runs. Temp agents are deliberately **excluded** from per-agent
+  aggregate metrics — PR counts and runtime-by-agent skip `temp-*` ids
+  (`engine/core/queries.js`).
+
+## 3. Charter / persona — not inherited
+
+A temp agent does **not** inherit, copy, or reference the charter or persona of any permanent
+agent. It has no `charter.md`: `buildSystemPrompt` reads
+`agents/<id>/charter.md`, which returns empty for a temp id, and falls back to a bare identity
+of `{ name, role: "Temporary Agent", expertise: [] }` (`engine/agents/playbook.js`). The system
+prompt therefore carries only the generic role label and the shared team rules — no expertise
+tags, no voice, no boundaries section.
+
+## 4. Memory, notes, and pinned context — retrieved, not inherited
+
+Temp agents get the **shared, non-personal** context every dispatch gets, but accrue and read
+**no personal memory**. Exact behavior (`engine/agents/playbook.js`):
+
+| Context source | Temp agent behavior |
+|----------------|---------------------|
+| `pinned.md` (operator pinned context) | **Injected** — unconditional, same as any agent. |
+| Task-selected **Relevant Memory** pack (`memoryRetrieval` on) | **Injected** — the retrieval query is keyed on the **work item / project**, not the agent persona, so temps get the same project-scoped pack. |
+| `notes.md` (team notes) | **Injected** (when the Relevant Memory pack did not already replace legacy injection). Not gated on agent id. |
+| Applicable **review-learning** lessons | **Injected** — project/file-scoped recall, agent-independent. |
+| Per-agent memory `knowledge/agents/<id>.md` | **NOT injected** — the injection is explicitly skipped for ids starting with `temp-` (`engine/agents/playbook.js`), and no such file exists for a temp anyway. |
+
+It does **not** inherit a *specific* permanent agent's `knowledge/agents/<agentId>.md`
+notebook — there is no "borrow Ripley's memory" path. A temp reads shared/project memory only.
+
+**Write side (consolidation).** A temp agent's findings never become durable personal memory.
+The consolidation pipeline (`engine/memory/consolidation.js`) skips `temp-*` authors in
+`appendToAgentMemory`, `reconcileAndAppendToAgentMemory`, and `maybeSummarizeAgentMemory`, and
+memory routing treats `temp-*` as an ineligible route. Team-wide consolidation into `notes.md`
+and the categorized `knowledge/` KB still happens from any inbox note the temp writes (those
+are team-scoped, not per-agent), but nothing is filed under a `temp-*` identity.
+
+## 5. Runtime, CLI, model, tools, and workspace manifest
+
+Because a temp agent has **no `config.agents.<id>` entry**, every per-agent override resolves to
+`null` and falls through to the **engine fleet defaults** (`engine.js#spawnAgent`, with
+`agentConfig = config.agents?.[agentId] || null`):
+
+- **CLI runtime:** `resolveAgentCli(null, engine)` → `engine.defaultCli` → `'copilot'`.
+- **Model:** `resolveAgentModel(null, engine)` → `engine.defaultModel` → runtime default.
+- **Budget:** `resolveAgentMaxBudget(null, engine)` → `engine.maxBudgetUsd`.
+- **Bare mode:** `resolveAgentBareMode(null, engine)` → `engine.claudeBareMode` → `false`.
+- **Workspace manifest:** `resolveAgentManifest(null)` returns the **permissive default** — no
+  `allowed_repos` gate, no `allowed_tools` narrowing (`engine/core/shared.js`,
+  [`workspace-manifests.md`](workspace-manifests.md)). A temp therefore inherits the fleet
+  `--allowedTools` set unmodified and is never blocked by the repo gate.
+- **Session resume:** temp ids are excluded from session persistence in every runtime adapter
+  (`getResumeSessionId` / session save short-circuit on `temp-*` in
+  `engine/runtimes/{claude,copilot,codex}.js`), so a temp never resumes a prior session.
+
+Spawn otherwise follows the normal path — worktree allocation, prompt build, and
+`engine/agents/spawn-agent.js` — identical to a named agent.
+
+## 6. Routing, retries, and permanent-agent availability
+
+- **Overflow only.** A temp is only ever chosen after hints, preferred, fallback, and any idle
+  configured agent all miss. The moment a named agent is idle, routing prefers it — temps are
+  never chosen ahead of an available permanent.
+- **API validation.** `POST /api/work-items` accepts an explicit `temp-*` agent id **only when
+  `allowTempAgents` is true**; otherwise it is rejected as an unknown agent
+  (`engine/planning/work-item-validation.js`; the `tempAllowed` check).
+- **Retry / reassignment.** The per-agent retry-reassignment machinery
+  ([`named-agents.md` §3](named-agents.md)) treats a temp id like any other agent for
+  `excludeAgent` purposes. If `allowTempAgents` is off (or the budget is exhausted) and no
+  alternate named agent exists, the engine writes a deduped inbox note advising the operator to
+  enable `allowTempAgents` or add another routing target, then re-dispatches to the same agent to
+  avoid deadlock (`engine.js`).
+- **Unknown-agent guard.** A pending dispatch whose `item.agent` is a `temp-*` id is **not**
+  treated as an "unknown configured agent" and is not re-routed on that basis (`engine.js`), so a
+  temp assignment survives to spawn even though it is absent from `config.agents`.
+
+## 7. Lifecycle and cleanup
+
+- **Ephemeral by design.** `cleanupTempAgent(agentId)` (`engine.js`) runs on **every**
+  dispatch-completion path (success, failure, timeout, orphan recovery, …). It deletes the id
+  from the in-memory `tempAgents` map and removes the `agents/<temp-id>/` directory (live-output
+  log etc.), wrapped in `shared._retryFsOp` so Windows `EBUSY`/`EPERM` from AV/file-indexer locks
+  are retried (regression test: `test/unit/cleanup-temp-agent-retry.test.js`).
+- **Orphan sweep.** As a backstop, the periodic cleanup pass
+  (`engine/orchestration/cleanup.js`) reaps `agents/temp-*` directories that are no longer
+  referenced by any dispatch record, using a **1-hour mtime gate** so a still-spawning temp is
+  never reaped mid-launch.
+- **Restart behavior.** The `tempAgents` map is in-memory, so an engine restart discards the
+  `{ name, role }` record. The persisted work-item/dispatch fields (`item.agent`,
+  `item.agentName`, `item.agentRole`) survive, and if a pending temp dispatch is resumed after
+  restart, `buildSystemPrompt` degrades gracefully to the default `Temporary Agent` identity
+  (`engine/agents/playbook.js`). No temp identity is re-registered or "revived" — it simply runs
+  out its one dispatch and is cleaned up.
+- **Retained artifacts.** Only team-scoped artifacts a temp produced during its run persist:
+  inbox notes it wrote (subject to normal team consolidation), tracked PRs it opened (attributed
+  to the `temp-*` id but excluded from per-agent PR metrics), and the work item's own history.
+  No personal memory, charter, or config record is retained.
+
+## 8. Limitations and isolation implications
+
+- **Off by default; overflow only.** With `allowTempAgents: false` (the default) temps never
+  exist; enabling them is an explicit operator decision (config + Settings toggle).
+- **Fleet-default permissions.** A temp runs with the fleet-default runtime, model, budget, and
+  tool set, and a **permissive** workspace manifest (no repo gate, no tool narrowing). If your
+  isolation model depends on per-agent `workspace_manifest` restrictions, note that a temp agent
+  bypasses them by construction — it has no manifest to enforce. Constrain temps through
+  fleet-level `engine.*` defaults (e.g. `engine.maxBudgetUsd`, `engine.allowedTools`) rather than
+  per-agent config.
+- **No accountable persona / no learning.** Temps carry no charter and accrue no personal
+  memory, so their work is not shaped by, and does not feed back into, any named agent's memory.
+  They are appropriate for burst capacity, not for work that should build durable per-agent
+  context.
+- **Concurrency-bounded.** The per-tick temp budget ties temp creation to `engine.maxConcurrent`;
+  temps cannot exceed the global concurrency cap.

package/engine/ado/comment.js

@@ -31,18 +31,68 @@
  * `active` (1). ADO honors the status field on thread creation, so unlike GitHub
  * this needs no second API round-trip. Actionable comments (bugs, required
  * changes) stay `active` so they block/notify the author.
+ *
+ * Fix summaries on the ORIGINATING thread (W-msd9os8e00qnd628):
+ * `replyToAdoThread` posts a fix-summary reply onto an existing review thread
+ * and transitions that thread to `fixed` (2) / `closed` (4), rather than opening
+ * a fresh active summary thread. It reads the thread first so retries / restarts
+ * / duplicate callbacks are idempotent (marker-keyed reply dedupe; already-
+ * resolved threads left as-is) and a reply/PATCH partial failure is surfaced and
+ * retryable.
  */
 
-const { buildMinionsCommentBody } = require('../providers/comment-format');
+const { buildMinionsCommentBody, parseMinionsMarker } = require('../providers/comment-format');
 const { acquireAdoToken } = require('./token');
 
 const ADO_API_VERSION = '7.1';
 
-// ADO CommentThreadStatus enum values we use. `active` (1) is the default for
-// actionable threads; `closed` (4) is used for non-actionable threads posted
-// pre-resolved so they don't clutter the PR with noise the author must triage.
+// ADO CommentThreadStatus enum. `active` (1) is the default for actionable
+// threads; `fixed` (2) records a finding the fix agent addressed; `closed` (4)
+// is used for non-actionable threads posted pre-resolved so they don't clutter
+// the PR with noise the author must triage.
+const ADO_THREAD_STATUS_UNKNOWN = 0;
 const ADO_THREAD_STATUS_ACTIVE = 1;
+const ADO_THREAD_STATUS_FIXED = 2;
+const ADO_THREAD_STATUS_WONT_FIX = 3;
 const ADO_THREAD_STATUS_CLOSED = 4;
+const ADO_THREAD_STATUS_BY_DESIGN = 5;
+const ADO_THREAD_STATUS_PENDING = 6;
+
+// Canonical mapping from a caller-friendly status name to the ADO enum value.
+// Used by the reply-and-resolve path so a fix agent can transition the
+// ORIGINATING thread to a resolved state (`fixed`/`closed`) rather than opening
+// a new active summary thread. `active` is the "leave unresolved" sentinel.
+const ADO_THREAD_STATUS_BY_NAME = Object.freeze({
+  active: ADO_THREAD_STATUS_ACTIVE,
+  fixed: ADO_THREAD_STATUS_FIXED,
+  wontfix: ADO_THREAD_STATUS_WONT_FIX,
+  'wont-fix': ADO_THREAD_STATUS_WONT_FIX,
+  closed: ADO_THREAD_STATUS_CLOSED,
+  resolved: ADO_THREAD_STATUS_FIXED,
+  bydesign: ADO_THREAD_STATUS_BY_DESIGN,
+  'by-design': ADO_THREAD_STATUS_BY_DESIGN,
+  pending: ADO_THREAD_STATUS_PENDING,
+});
+
+// Thread statuses that mean "resolved" for idempotency purposes — a thread
+// already in one of these needs no further status PATCH.
+const ADO_RESOLVED_THREAD_STATUSES = new Set([
+  ADO_THREAD_STATUS_FIXED,
+  ADO_THREAD_STATUS_WONT_FIX,
+  ADO_THREAD_STATUS_CLOSED,
+  ADO_THREAD_STATUS_BY_DESIGN,
+]);
+
+function resolveAdoThreadStatus(status) {
+  if (typeof status === 'number' && Number.isInteger(status)) return status;
+  const key = String(status || '').trim().toLowerCase();
+  if (key === '') return ADO_THREAD_STATUS_ACTIVE;
+  const mapped = ADO_THREAD_STATUS_BY_NAME[key];
+  if (mapped === undefined) {
+    throw new Error(`invalid thread status: ${JSON.stringify(status)} (expected one of ${Object.keys(ADO_THREAD_STATUS_BY_NAME).join(', ')})`);
+  }
+  return mapped;
+}
 
 // ── Validation (ADO-specific) ────────────────────────────────────────────────
 // Field validation for the marker (agentId / kind / workItemId) is done inside
@@ -72,6 +122,12 @@ function _validatePrNumber(prNumber) {
   }
 }
 
+function _validateThreadId(threadId) {
+  if (typeof threadId !== 'number' || !Number.isInteger(threadId) || threadId <= 0) {
+    throw new Error(`invalid threadId: ${JSON.stringify(threadId)} (expected positive integer)`);
+  }
+}
+
 /**
  * Build the ADO threads endpoint for a PR. `orgBase` already includes the org
  * (e.g. https://dev.azure.com/contoso). Project + repositoryId are URL-encoded.
@@ -82,6 +138,25 @@ function buildThreadsUrl({ orgBase, project, repositoryId, prNumber }) {
     + `/pullRequests/${prNumber}/threads?api-version=${ADO_API_VERSION}`;
 }
 
+/**
+ * Endpoint for a single existing thread (GET current status/comments, PATCH
+ * status). `orgBase` already includes the org.
+ */
+function buildThreadUrl({ orgBase, project, repositoryId, prNumber, threadId }) {
+  const base = String(orgBase).replace(/\/+$/, '');
+  return `${base}/${encodeURIComponent(project)}/_apis/git/repositories/${encodeURIComponent(repositoryId)}`
+    + `/pullRequests/${prNumber}/threads/${threadId}?api-version=${ADO_API_VERSION}`;
+}
+
+/**
+ * Endpoint for the comments collection of an existing thread (POST a reply).
+ */
+function buildThreadCommentsUrl({ orgBase, project, repositoryId, prNumber, threadId }) {
+  const base = String(orgBase).replace(/\/+$/, '');
+  return `${base}/${encodeURIComponent(project)}/_apis/git/repositories/${encodeURIComponent(repositoryId)}`
+    + `/pullRequests/${prNumber}/threads/${threadId}/comments?api-version=${ADO_API_VERSION}`;
+}
+
 /**
  * Default token acquisition — thin wrapper over engine/ado/token.js so callers
  * can inject a stub in tests. Returns the bearer token string or throws.
@@ -174,12 +249,193 @@ async function postAdoPrComment({
   };
 }
 
+/**
+ * Reply to an EXISTING review thread with a fix summary and transition that
+ * thread to a resolved status — instead of opening a new active summary thread.
+ *
+ * This is the fix-summary path for Azure DevOps (W-msd9os8e00qnd628): when a fix
+ * agent has evidence a review finding was addressed, it replies on the
+ * originating thread (identified by the structured `threadId` carried on the
+ * work item / completion report) and moves that thread to `fixed` (2) / `closed`
+ * (4). Contrast with `postAdoPrComment`, which creates a fresh thread.
+ *
+ * Idempotency (retries / engine restarts / duplicate completion callbacks /
+ * provider timeouts): the current thread is read first. A reply whose hidden
+ * marker already matches this dispatch's structured identity (agentId + kind +
+ * workItemId) is treated as already-posted and the reply POST is skipped; a
+ * thread already in a resolved status is left as-is. Resolution is keyed by the
+ * explicit `threadId` and the structured marker — never by body/title text — so
+ * sibling findings are never bulk-resolved.
+ *
+ * Partial-failure visibility: the reply POST and the status PATCH are distinct
+ * round-trips. If the reply succeeds but the status PATCH fails, we throw so the
+ * caller sees the failure and can retry; the retry re-reads the thread, finds
+ * the reply already present (skips it), and re-attempts only the PATCH. Local
+ * state is never marked resolved when the provider PATCH failed.
+ *
+ * @param {object} args
+ * @param {string} args.orgBase
+ * @param {string} args.project
+ * @param {string} args.repositoryId
+ * @param {number} args.prNumber
+ * @param {number} args.threadId       existing ADO thread id (positive integer)
+ * @param {string} args.body           reply body (pre-marker; builder prepends marker)
+ * @param {string} args.agentId
+ * @param {string} args.kind
+ * @param {string} [args.workItemId]
+ * @param {string} [args.model]
+ * @param {(string|number)} [args.status='fixed']  target status; 'active' leaves the thread unresolved
+ * @param {number} [args.timeoutMs=30000]
+ * @param {Function} [args.acquireToken]
+ * @param {Function} [args.fetchImpl]
+ * @returns {Promise<{threadId:number, commentId:(number|undefined), replied:boolean, alreadyReplied:boolean, resolved:boolean, alreadyResolved:boolean, statusApplied:(number|null)}>}
+ */
+async function replyToAdoThread({
+  orgBase,
+  project,
+  repositoryId,
+  prNumber,
+  threadId,
+  body,
+  agentId,
+  kind,
+  workItemId,
+  model,
+  status = 'fixed',
+  timeoutMs = 30000,
+  acquireToken = _defaultAcquireToken,
+  fetchImpl,
+} = {}) {
+  _validateOrgBase(orgBase);
+  _validateProject(project);
+  _validateRepositoryId(repositoryId);
+  _validatePrNumber(prNumber);
+  _validateThreadId(threadId);
+
+  const targetStatus = resolveAdoThreadStatus(status);
+
+  // buildMinionsCommentBody validates marker fields and throws on bad input.
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, model, body });
+
+  const token = await acquireToken();
+  if (!token || typeof token !== 'string') {
+    throw new Error('ADO comment: could not acquire an access token (az account get-access-token failed)');
+  }
+
+  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (!doFetch) throw new Error('ADO comment: no fetch implementation available');
+
+  const authHeaders = {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  };
+  const threadUrl = buildThreadUrl({ orgBase, project, repositoryId, prNumber, threadId });
+
+  // ── 1. Read the current thread (status + existing comments) for idempotency ──
+  const getRes = await doFetch(threadUrl, {
+    method: 'GET',
+    headers: authHeaders,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!getRes.ok) {
+    const detail = await getRes.text().catch(() => '');
+    throw new Error(`ADO thread GET ${getRes.status} ${getRes.statusText}: ${String(detail).slice(0, 500)}`);
+  }
+  const thread = await getRes.json().catch(() => ({}));
+  const existingComments = Array.isArray(thread.comments) ? thread.comments : [];
+  const currentStatus = typeof thread.status === 'number'
+    ? thread.status
+    : resolveAdoThreadStatus(thread.status || 'active');
+
+  // Idempotency: has THIS dispatch (structured marker identity) already replied?
+  const alreadyReplied = existingComments.some((c) => {
+    const marker = parseMinionsMarker(String(c?.content || ''));
+    if (!marker) return false;
+    if (marker.agentId !== agentId || marker.kind !== kind) return false;
+    // When a workItemId is supplied it is the structured finding identity — a
+    // match on it (or its absence on both sides) confirms this is our reply.
+    if (workItemId) return marker.workItemId === workItemId;
+    return marker.workItemId === undefined;
+  });
+
+  // The first comment id anchors a reply to the originating thread.
+  const parentCommentId = existingComments.length > 0 && Number.isInteger(existingComments[0]?.id)
+    ? existingComments[0].id
+    : 1;
+
+  let replied = false;
+  let commentId;
+  if (!alreadyReplied) {
+    const commentsUrl = buildThreadCommentsUrl({ orgBase, project, repositoryId, prNumber, threadId });
+    const postRes = await doFetch(commentsUrl, {
+      method: 'POST',
+      headers: authHeaders,
+      body: JSON.stringify({ parentCommentId, content: finalBody, commentType: 1 }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!postRes.ok) {
+      const detail = await postRes.text().catch(() => '');
+      throw new Error(`ADO thread reply POST ${postRes.status} ${postRes.statusText}: ${String(detail).slice(0, 500)}`);
+    }
+    const postJson = await postRes.json().catch(() => ({}));
+    commentId = postJson && postJson.id;
+    replied = true;
+  }
+
+  // ── 2. Transition the thread status (skip when unresolved requested or the
+  //       thread is already in the requested/equivalent resolved state) ──
+  const wantsResolve = targetStatus !== ADO_THREAD_STATUS_ACTIVE
+    && targetStatus !== ADO_THREAD_STATUS_UNKNOWN;
+  const alreadyResolved = wantsResolve && currentStatus === targetStatus;
+  let resolved = ADO_RESOLVED_THREAD_STATUSES.has(currentStatus);
+  let statusApplied = null;
+
+  if (wantsResolve && currentStatus !== targetStatus) {
+    // The reply above may already be committed. A PATCH failure here throws so
+    // the caller can retry; the retry skips the (now-present) reply and PATCHes
+    // again — local state is never marked resolved on a failed PATCH.
+    const patchRes = await doFetch(threadUrl, {
+      method: 'PATCH',
+      headers: authHeaders,
+      body: JSON.stringify({ status: targetStatus }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!patchRes.ok) {
+      const detail = await patchRes.text().catch(() => '');
+      throw new Error(`ADO thread status PATCH ${patchRes.status} ${patchRes.statusText}: ${String(detail).slice(0, 500)} (reply ${replied ? 'was' : 'was not'} posted; retry is idempotent)`);
+    }
+    statusApplied = targetStatus;
+    resolved = true;
+  }
+
+  return {
+    threadId,
+    commentId,
+    replied,
+    alreadyReplied,
+    resolved,
+    alreadyResolved: !!alreadyResolved,
+    statusApplied,
+  };
+}
+
 module.exports = {
   postAdoPrComment,
+  replyToAdoThread,
   buildThreadsUrl,
+  buildThreadUrl,
+  buildThreadCommentsUrl,
+  resolveAdoThreadStatus,
   ADO_API_VERSION,
+  ADO_THREAD_STATUS_UNKNOWN,
   ADO_THREAD_STATUS_ACTIVE,
+  ADO_THREAD_STATUS_FIXED,
+  ADO_THREAD_STATUS_WONT_FIX,
   ADO_THREAD_STATUS_CLOSED,
+  ADO_THREAD_STATUS_BY_DESIGN,
+  ADO_THREAD_STATUS_PENDING,
+  ADO_THREAD_STATUS_BY_NAME,
+  ADO_RESOLVED_THREAD_STATUSES,
   // Re-export the neutral builder so ADO callers have a single import surface,
   // mirroring engine/providers/gh-comment.js.
   buildMinionsCommentBody,
@@ -188,5 +444,6 @@ module.exports = {
   _validateProject,
   _validateRepositoryId,
   _validatePrNumber,
+  _validateThreadId,
   _defaultAcquireToken,
 };

package/engine/agents/llm.js

@@ -55,6 +55,26 @@ function _emptyDailyDelta() {
   return { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0 };
 }
 
+// Merge a source billableUnits map ({unit:{total,reported,unavailable}}) into a
+// target object's billableUnits (W-msdcgitc). Used to fold buffered CC/doc-chat
+// deltas into the persisted metrics and to re-merge on a failed flush. Generic
+// over unit name so no runtime-name branch is needed.
+function _mergeBillableUnits(target, source) {
+  if (!source || typeof source !== 'object') return;
+  if (!target.billableUnits || typeof target.billableUnits !== 'object') {
+    target.billableUnits = {};
+  }
+  for (const [unit, b] of Object.entries(source)) {
+    if (!b || typeof b !== 'object') continue;
+    const bucket = target.billableUnits[unit]
+      || { total: 0, reported: 0, unavailable: 0 };
+    bucket.total += b.total || 0;
+    bucket.reported += b.reported || 0;
+    bucket.unavailable += b.unavailable || 0;
+    target.billableUnits[unit] = bucket;
+  }
+}
+
 function _ensureFlushTimer() {
   if (_flushTimer) return;
   const interval = shared.ENGINE_DEFAULTS.metricsFlushIntervalMs || 10000;
@@ -74,6 +94,7 @@ function trackEngineUsage(category, usage) {
   cat.outputTokens += usage.outputTokens || 0;
   cat.cacheRead += usage.cacheRead || 0;
   cat.cacheCreation += usage.cacheCreation || 0;
+  shared.accumulateBillableUnits(cat, usage.billable);
   if (usage.durationMs) {
     cat.totalDurationMs += usage.durationMs;
     cat.timedCalls += 1;
@@ -86,6 +107,7 @@ function trackEngineUsage(category, usage) {
   daily.inputTokens += usage.inputTokens || 0;
   daily.outputTokens += usage.outputTokens || 0;
   daily.cacheRead += usage.cacheRead || 0;
+  shared.accumulateBillableUnits(daily, usage.billable);
 
   _ensureFlushTimer();
 }
@@ -135,6 +157,7 @@ function flushMetricsBuffer() {
             cat.errorsByCode[code] = (cat.errorsByCode[code] || 0) + count;
           }
         }
+        _mergeBillableUnits(cat, delta.billableUnits);
       }
       if (!metrics._daily) metrics._daily = {};
       for (const [day, delta] of Object.entries(pending.daily)) {
@@ -146,6 +169,7 @@ function flushMetricsBuffer() {
         d.inputTokens += delta.inputTokens;
         d.outputTokens += delta.outputTokens;
         d.cacheRead += delta.cacheRead;
+        _mergeBillableUnits(d, delta.billableUnits);
       }
       return metrics;
     });
@@ -164,12 +188,14 @@ function flushMetricsBuffer() {
           c.errorsByCode[code] = (c.errorsByCode[code] || 0) + count;
         }
       }
+      _mergeBillableUnits(c, delta.billableUnits);
     }
     for (const [day, delta] of Object.entries(pending.daily)) {
       if (!_pendingMetrics.daily[day]) _pendingMetrics.daily[day] = _emptyDailyDelta();
       const d = _pendingMetrics.daily[day];
       d.costUsd += delta.costUsd; d.inputTokens += delta.inputTokens;
       d.outputTokens += delta.outputTokens; d.cacheRead += delta.cacheRead;
+      _mergeBillableUnits(d, delta.billableUnits);
     }
     console.error('metrics flush:', e.message);
   }

package/engine/agents/playbook.js

@@ -1373,7 +1373,8 @@ function _checkPlaybookSections(content, context = '') {
 
 // Lean system prompt: agent identity + rules only (~2-4KB, never grows)
 function buildSystemPrompt(agentId, config, project) {
-  const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', expertise: [] };
+  const agent = config.agents[agentId] || tempAgents.get(agentId)
+    || { name: shared.tempAgentDisplayName(agentId), role: 'Temporary Agent', expertise: [] };
   const charter = safeRead(path.join(AGENTS_DIR, agentId, 'charter.md')); // returns '' for temp agents (no charter file)
   project = project || getProjects(config)[0] || {};
 

package/engine/core/queries.js

@@ -501,9 +501,15 @@ function getMetrics() {
     const runtimeName = shared.resolveAgentCli(configuredAgents[agentId], engineConfig);
     m.runtime = runtimeName;
     try {
-      m.costTracking = resolveRuntime(runtimeName).capabilities?.costTracking === true;
+      const caps = resolveRuntime(runtimeName).capabilities || {};
+      m.costTracking = caps.costTracking === true;
+      // Typed native billable unit for the display layer (W-msdcgitc). Copilot
+      // reports 'premiumRequests'; adapters without one default to 'usd'. The
+      // dashboard reads THIS, never the runtime name, to decide labels/units.
+      m.billableUnit = typeof caps.billableUnit === 'string' ? caps.billableUnit : 'usd';
     } catch {
       m.costTracking = false;
+      m.billableUnit = 'usd';
     }
   }
 
@@ -895,7 +901,21 @@ function getAgents(config) {
   const seen = new Set(roster.map(a => a.id));
   for (const d of (dispatch.active || [])) {
     if (d.agent && d.agent.startsWith('temp-') && !seen.has(d.agent)) {
-      roster.push({ id: d.agent, name: d.agentName || d.agent, role: d.agentRole || 'Temp Agent', emoji: '\u{1F4A8}', expertise: [], _temp: true });
+      // Additive friendly display identity; the canonical `id` (temp-<uid>)
+      // stays the machine identity for routing/SQL/paths/memory. `name` falls
+      // back to the deterministic call sign when the dispatch record predates
+      // friendly naming (e.g. after a restart with no in-memory tempAgents).
+      const identity = shared.resolveAgentIdentity(d.agent, config);
+      roster.push({
+        id: d.agent,
+        name: d.agentName || identity.displayName || d.agent,
+        role: d.agentRole || 'Temporary Agent',
+        emoji: '\u{1F4A8}',
+        expertise: [],
+        _temp: true,
+        isTemp: true,
+        callSign: identity.callSign,
+      });
       seen.add(d.agent);
     }
   }
@@ -949,8 +969,13 @@ function getAgents(config) {
 
     const chartered = fs.existsSync(path.join(AGENTS_DIR, a.id, 'charter.md'));
     if (lastAction.length > 120) lastAction = lastAction.slice(0, 120) + '...';
+    // Structured display identity (canonical id stays authoritative; friendly
+    // name + temp flag are additive). Clients render a "Temp" badge from `isTemp`.
+    const isTemp = a.isTemp === true || shared.isTempAgentId(a.id);
     return {
       ...a,
+      isTemp,
+      callSign: isTemp ? (a.callSign || shared.tempAgentCallSign(a.id)) : null,
       runtime,
       model,
       displayModel: modelDisplay.model,