@yemi33/minions 0.1.2453 → 0.1.2455

package/engine/providers/gh-comment.js

@@ -108,6 +108,35 @@ function _runGh(execFileSync, args, timeoutMs, env) {
   return execFileSync('gh', args, opts);
 }
 
+// GitHub GraphQL node id for a review thread (opaque, e.g. `PRRT_kwDO…`). We
+// don't decode it — only guard against empty / whitespace values before it is
+// interpolated into a `gh api graphql` argv (argv form, no shell, so this is a
+// sanity check, not an injection gate).
+const GH_NODE_ID_RE = /^[A-Za-z0-9_=+/.:-]+$/;
+
+function _validateThreadNodeId(threadId) {
+  if (typeof threadId !== 'string' || !GH_NODE_ID_RE.test(threadId)) {
+    throw new Error(`invalid reviewThreadId: ${JSON.stringify(threadId)} (expected a GitHub review-thread node id)`);
+  }
+}
+
+/**
+ * Run `gh api graphql` and return the parsed JSON `data` object. Throws on a
+ * transport failure (execFileSync non-zero — e.g. permission denied) and on a
+ * GraphQL `errors` payload (some gh versions exit 0 but embed errors).
+ */
+function _runGhGraphql(execFileSync, gqlArgs, timeoutMs, env) {
+  const raw = _runGh(execFileSync, ['api', 'graphql', ...gqlArgs], timeoutMs, env);
+  let parsed;
+  try { parsed = JSON.parse(String(raw || '').trim() || '{}'); }
+  catch (e) { throw new Error(`gh api graphql: unparseable response (${e.message})`); }
+  if (parsed && Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+    const msg = parsed.errors.map((x) => x?.message || String(x)).join('; ');
+    throw new Error(`gh api graphql error: ${msg}`);
+  }
+  return parsed && parsed.data ? parsed.data : {};
+}
+
 /**
  * Resolve the per-slug PAT for `repo` and return an env override suitable for
  * passing to `_runGh`. Returns `undefined` when no mapping exists (caller
@@ -207,6 +236,132 @@ function postPrReviewComment({
   }
 }
 
+/**
+ * Reply to an existing GitHub PR *review thread* with a fix summary and resolve
+ * that thread — instead of opening a fresh top-level comment or a new review
+ * thread that the author must triage.
+ *
+ * This is the fix-summary path for GitHub (W-msd9os8e00qnd628). GitHub has no
+ * "resolved" state for conversation (issue) comments — only inline review
+ * threads can be resolved — so this is the ONLY way to post an addressed-finding
+ * summary that ends in a resolved state. When no review-thread node id is
+ * available the caller must fall back to `postPrComment` (an informational
+ * top-level summary that MUST NOT claim to be "resolved").
+ *
+ * Mechanics (via `gh api graphql`, per-slug PAT threaded through GH_TOKEN):
+ *   1. Query the thread by node id → `isResolved` + existing comment bodies.
+ *   2. `addPullRequestReviewThreadReply` unless a comment already carries THIS
+ *      dispatch's hidden marker (agentId + kind + workItemId) — marker-keyed so
+ *      retries / restarts / duplicate callbacks don't double-post.
+ *   3. `resolveReviewThread` unless already resolved.
+ *
+ * Idempotency + partial-failure: the reply and resolve are distinct round-trips.
+ * A reply success followed by a resolve failure throws (so the caller sees it
+ * and can retry); the retry re-queries, finds the reply present (skips it), and
+ * re-attempts only the resolve. Local state is never marked resolved when the
+ * `resolveReviewThread` mutation failed.
+ *
+ * Self-authored / shared-credential semantics: resolution is gated only by the
+ * thread node identity and marker, never by `viewerDidAuthor` or reviewer/fixer
+ * equality — a shared platform credential must not block a legitimate fix reply.
+ *
+ * @param {object} args
+ * @param {string} args.repo        owner/name (for per-slug token routing)
+ * @param {string} args.threadId    review-thread GraphQL node id
+ * @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 {boolean} [args.resolve=true]  resolve the thread after replying
+ * @param {number} [args.timeoutMs=30000]
+ * @param {Function} [args.execFileSync]
+ * @param {Function} [args.resolveTokenForSlug]
+ * @returns {{threadId:string, replied:boolean, alreadyReplied:boolean, resolved:boolean, alreadyResolved:boolean}}
+ */
+function replyAndResolveReviewThread({
+  repo,
+  threadId,
+  body,
+  agentId,
+  kind,
+  workItemId,
+  model,
+  resolve = true,
+  timeoutMs = 30000,
+  execFileSync = _execFileSync,
+  resolveTokenForSlug,
+} = {}) {
+  _validateRepo(repo);
+  _validateThreadNodeId(threadId);
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, model, body });
+  const env = _resolveTokenEnvForRepo(repo, resolveTokenForSlug);
+
+  // ── 1. Read the current thread (isResolved + comment bodies) for idempotency ─
+  const queryData = _runGhGraphql(
+    execFileSync,
+    [
+      '-f',
+      'query=query($id:ID!){ node(id:$id){ __typename ... on PullRequestReviewThread { id isResolved comments(first:100){ nodes { body } } } } }',
+      '-f', `id=${threadId}`,
+    ],
+    timeoutMs,
+    env,
+  );
+  const node = queryData && queryData.node;
+  if (!node || (node.__typename && node.__typename !== 'PullRequestReviewThread')) {
+    throw new Error(`gh review thread ${threadId}: not a PullRequestReviewThread (only inline review threads can be resolved)`);
+  }
+  const alreadyResolved = node.isResolved === true;
+  const existingBodies = Array.isArray(node.comments?.nodes)
+    ? node.comments.nodes.map((c) => String(c?.body || ''))
+    : [];
+  const alreadyReplied = existingBodies.some((b) => {
+    const marker = parseMinionsMarker(b);
+    if (!marker) return false;
+    if (marker.agentId !== agentId || marker.kind !== kind) return false;
+    if (workItemId) return marker.workItemId === workItemId;
+    return marker.workItemId === undefined;
+  });
+
+  // ── 2. Reply on the originating thread (unless we already did) ──
+  let replied = false;
+  if (!alreadyReplied) {
+    _runGhGraphql(
+      execFileSync,
+      [
+        '-f',
+        'query=mutation($id:ID!,$body:String!){ addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$id, body:$body}){ comment { id } } }',
+        '-f', `id=${threadId}`,
+        '-f', `body=${finalBody}`,
+      ],
+      timeoutMs,
+      env,
+    );
+    replied = true;
+  }
+
+  // ── 3. Resolve the thread (unless already resolved / not requested) ──
+  // A failure here after a successful reply throws; the retry skips the reply
+  // (marker present) and re-attempts only the resolve.
+  let resolved = alreadyResolved;
+  if (resolve && !alreadyResolved) {
+    _runGhGraphql(
+      execFileSync,
+      [
+        '-f',
+        'query=mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread { isResolved } } }',
+        '-f', `id=${threadId}`,
+      ],
+      timeoutMs,
+      env,
+    );
+    resolved = true;
+  }
+
+  return { threadId, replied, alreadyReplied, resolved, alreadyResolved };
+}
+
 module.exports = {
   // Builders / parsers (pure functions — usable from anywhere)
   buildMinionsCommentBody,
@@ -222,9 +377,13 @@ module.exports = {
   // gh wrappers (argv-form, --body-file)
   postPrComment,
   postPrReviewComment,
+  // GitHub review-thread reply + resolve (fix-summary path, GraphQL)
+  replyAndResolveReviewThread,
   // Internal helpers exported for tests / advanced callers
   _buildMarker,
   _writeTempBodyFile,
   _resolveTokenEnvForRepo,
+  _validateThreadNodeId,
+  _runGhGraphql,
   _clearTokenWarnings: () => _warnedUnresolvedSlugs.clear(),
 };

package/engine/recovery/stop-stack.js

@@ -104,9 +104,22 @@ const STOP_STACK_EXIT = Object.freeze({
   REFUSED_UNVERIFIED: 4,
 });
 
-// Matches the internal installer's quiescence window so a stop driven by the
-// migration gate cannot be shorter than the wait that follows it.
+// The FLOOR of the internal installer's quiescence window (see
+// bin/install-internal-minions.js#QUIESCE_TIMEOUT_FLOOR_MS), so a stop driven by
+// the migration gate can never be shorter than the wait that follows it. That
+// window is derived from the target runtime and only ever widens from here.
 const DEFAULT_STOP_TIMEOUT_MS = 60000;
+/**
+ * Grace added on top of the ENGINE'S OWN drain budget (`engine.shutdownTimeout`)
+ * when a caller derives a teardown deadline from it, covering the fixed work
+ * either side of the drain: writing stop intent, stopping the supervisor and
+ * dashboard, the verified reap, and the WAL-index release.
+ *
+ * Exported because it is a cross-surface number: `minions restart` applies it,
+ * and the standalone internal installer — which requires nothing from `engine/`
+ * and therefore mirrors the value — is held to it by a drift test.
+ */
+const DRAIN_GRACE_MS = 5000;
 const PID_POLL_MS = 100;
 const SHM_POLL_MS = 500;
 /**
@@ -600,6 +613,7 @@ module.exports = {
   STOP_STACK_HOLDER_REASONS,
   STOP_STACK_EXIT,
   DEFAULT_STOP_TIMEOUT_MS,
+  DRAIN_GRACE_MS,
   POST_KILL_GRACE_MS,
   PID_POLL_MS,
   SHM_POLL_MS,

package/engine/runtimes/claude.js

@@ -874,6 +874,9 @@ const capabilities = {
   effortLevels: true,
   // Emits `total_cost_usd` and detailed token usage in the result event
   costTracking: true,
+  // Native billable unit is USD dollar cost (rendered as `$`). Typed metadata
+  // so the display layer never branches on the runtime name (W-msdcgitc).
+  billableUnit: 'usd',
   // Family shorthands (`sonnet` / `opus` / `haiku`) are accepted by the CLI
   modelShorthands: true,
   // No public model enumeration mechanism — settings UI uses free-text

package/engine/runtimes/codex.js

@@ -993,6 +993,10 @@ const capabilities = {
   systemPromptFile: false,
   effortLevels: true,
   costTracking: false,
+  // Native billable unit is USD (Codex reports no cost telemetry today, so it
+  // renders as unavailable). Typed metadata so the display layer never branches
+  // on the runtime name (W-msdcgitc).
+  billableUnit: 'usd',
   modelShorthands: false,
   modelDiscovery: true,
   // Bundled catalogs can lag staged/custom model availability. Let Codex

package/engine/runtimes/copilot.js

@@ -906,8 +906,24 @@ function parseOutput(raw, { maxTextLength = 0 } = {}) {
         numTurns: turnEndCount,
         // Copilot-specific extension — preserved alongside the standard shape
         // so the engine can distinguish "this turn cost N premium requests"
-        // from token accounting on the Claude path.
-        premiumRequests: typeof u.premiumRequests === 'number' ? u.premiumRequests : 0,
+        // from token accounting on the Claude path. NULL (not 0) when the
+        // installed CLI did not report the field for this run, so the engine
+        // records it as UNAVAILABLE rather than a real "0 premium requests"
+        // (W-msdcgitc). Treated as authoritative — never derived from tokens,
+        // model, or elapsed time.
+        premiumRequests: typeof u.premiumRequests === 'number' ? u.premiumRequests : null,
+        // Generic typed billable-unit descriptor (runtime/usage contract,
+        // W-msdcgitc). `value` is the authoritative provider-reported count for
+        // THIS result event (per-invocation, already scoped — not a running
+        // total the engine must diff), and `reported:false` marks an
+        // unavailable observation the engine keeps distinct from a real 0. The
+        // engine accumulates this generically (shared.accumulateBillableUnits)
+        // without ever branching on the runtime name.
+        billable: {
+          unit: 'premiumRequests',
+          value: typeof u.premiumRequests === 'number' ? u.premiumRequests : null,
+          reported: typeof u.premiumRequests === 'number',
+        },
         sessionDurationMs: typeof u.sessionDurationMs === 'number' ? u.sessionDurationMs : 0,
       };
     }
@@ -1439,6 +1455,11 @@ const capabilities = {
   effortLevels: true,
   // result.usage carries premiumRequests count, no USD or tokens
   costTracking: false,
+  // Native billable unit is GitHub Copilot premium requests, not USD. The
+  // display layer renders this in the same position Claude shows dollar cost
+  // (W-msdcgitc). Typed metadata so orchestration/dashboard never branch on the
+  // runtime name; adapters without a native credit unit default to 'usd'.
+  billableUnit: 'premiumRequests',
   // No 'sonnet'/'opus'/'haiku' shorthand — Copilot expects full model IDs
   modelShorthands: false,
   // GET https://api.githubcopilot.com/models works (verified during spike)

package/engine.js

@@ -11706,7 +11706,7 @@ function discoverFromWorkItems(config, project) {
     newWork.push({
       type: workType,
       agent: agentId,
-      agentName: config.agents[agentId]?.name || tempAgents.get(agentId)?.name || agentId,
+      agentName: config.agents[agentId]?.name || tempAgents.get(agentId)?.name || shared.tempAgentCallSign(agentId) || agentId,
       agentRole: config.agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent',
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
@@ -12952,7 +12952,7 @@ function resolvePendingDispatchAgent(item, config) {
 function assignPendingDispatchAgent(item, agentId, config) {
   const agents = config.agents || {};
   item.agent = agentId;
-  item.agentName = agents[agentId]?.name || tempAgents.get(agentId)?.name || agentId;
+  item.agentName = agents[agentId]?.name || tempAgents.get(agentId)?.name || shared.tempAgentCallSign(agentId) || agentId;
   item.agentRole = agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent';
   delete item._agentBusySince;
   delete item.skipReason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2453",
+  "version": "0.1.2455",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/fix.md

@@ -232,8 +232,29 @@ Pick the disposition that matches the finding and post the matching reply, then
 - **Won't fix / disagree** (comment is invalid, stale, already addressed, out of scope, or harmful) → Reply with the evidence-backed rationale explaining why no code change was made. Leave the thread **active** for the reviewer to decide; do NOT resolve unilaterally.
 
 Host-specific mechanics:
-- **GitHub**: Reply to each review comment, then resolve the conversation for the four resolve-eligible dispositions above. Leave Won't-fix threads unresolved.
-- **ADO**: Use `az` CLI first to reply to each thread and update status when supported; use ADO MCP only as a fallback when `az` is unavailable or insufficient. Set status to `fixed` for Fixed/Satisfied-elsewhere/Tracked-as-follow-up and `closed` for Deferred; leave `active` for Won't-fix rationale replies.
+- **Preferred (both hosts): reply on the ORIGINATING thread and resolve it in one call** with
+  `minions pr comment <repo> --thread <threadId> --resolve --agent <id> --kind fix [--wi <finding-id>] --body-file <path>`
+  (ADO: add `--host ado --ado-org … --ado-project … --repo-id …` and, for Deferred, `--resolve-status closed`;
+  GitHub: `--thread` is the review-thread GraphQL node id). The `--thread` id is the **structured thread/finding
+  identity carried on the work item / your `reviewFindingResolution` evidence** — never resolve by matching title or
+  body text, and never resolve sibling threads or all threads in bulk. This path is idempotent: re-running after a
+  retry, restart, or a provider timeout re-checks the thread, skips a reply it already posted (matched by the hidden
+  minions marker), and re-attempts only the unfinished resolve.
+- **Do NOT open a fresh active thread to summarize an addressed finding.** A new top-level/active thread for a fix
+  you already made just adds triage noise the author must re-close. Post the summary as a reply on the finding's own
+  thread via `--thread … --resolve` above.
+- **GitHub**: `--thread … --resolve` replies to the review thread and resolves it via `resolveReviewThread` for the
+  four resolve-eligible dispositions. Leave Won't-fix threads unresolved. If no review-thread id exists (the finding
+  was a top-level conversation comment), a top-level `minions pr comment` reply is informational only — GitHub has no
+  resolved state for conversation comments, so do **not** claim it is "resolved."
+- **ADO**: `--thread … --resolve` posts the reply on the originating thread and transitions it (`fixed` for
+  Fixed/Satisfied-elsewhere/Tracked-as-follow-up, `--resolve-status closed` for Deferred). Prefer it over raw `az`;
+  if you must fall back, use `az` first (ADO MCP only when `az` is insufficient), reply on the existing thread, and
+  set its status — do not create a new thread just for the fix summary. Leave `active` for Won't-fix rationale replies.
+
+Never auto-resolve a finding the agent did NOT actually address. When the fix report says the finding was not
+addressed, is ambiguous, needs human input, or lacks the required commit/`file:line` resolution evidence, reply with
+the rationale and leave the thread **active**. Human feedback is not auto-resolved merely because a dispatch completed.
 
 Hard rule: never resolve, close, or mark-fixed a thread without first posting a reply that explains the disposition. The chunk-5 / Caleb-Tseng / MaiLibraryViewModel thread (ADO 5215549 thread 65692221) is the canonical bad example — closed silently with no audit trail.
 

package/playbooks/shared-rules.md

@@ -262,6 +262,18 @@ non-actionable thread is posted pre-resolved in a single call. Prefer
 thread `status` field yourself: `closed` (4) for non-actionable notes (or `fixed`
 (2) when the comment records something already handled), `active` (1) for
 actionable findings. The verdict/summary comment itself stays `active`.
+
+**Fix summaries reply on the originating thread — never a new active thread.**
+When you are recording that an existing review finding was *addressed*, reply on
+that finding's own thread and transition it, rather than opening a fresh thread:
+`minions pr comment <pr> --host ado --ado-org … --ado-project … --repo-id … --thread <threadId> --resolve [--resolve-status closed] --agent <id> --kind fix [--wi <finding-id>] --body-file <path>`.
+The `--thread` id is **structured thread/finding identity** from the work item or
+your `reviewFindingResolution` evidence — resolve only that thread, keyed by id,
+never by matching comment title/body text and never in bulk across sibling
+threads. The reply+status transition is idempotent across retries/restarts: it
+re-reads the thread, skips a reply already carrying your minions marker, and only
+re-applies the status if the earlier PATCH failed — so a partial failure stays
+visible and retryable instead of being silently marked resolved locally.
 {{/ado_shared_rules}}
 {{#github_shared_rules}}
 **GitHub mechanism.** GitHub has no "resolved" state for PR *conversation*
@@ -273,9 +285,19 @@ single API call that creates a thread pre-resolved. So on GitHub:
   `<details><summary>Non-blocking observations</summary>…</details>` block inside
   the verdict comment so they are visible but de-emphasized and create no separate
   unresolved threads. `--resolved` is rejected on the GitHub path for this reason.
+- **To record that an existing review finding was addressed**, reply on that
+  finding's own review thread and resolve it in one idempotent call:
+  `minions pr comment <repo> --thread <reviewThreadNodeId> --resolve --agent <id> --kind fix [--wi <finding-id>] --body-file <path>`.
+  The `--thread` node id is **structured thread identity** from the work item or
+  your `reviewFindingResolution` evidence — resolve only that thread, never by
+  matching comment text and never in bulk. Do **not** open a fresh active thread
+  to summarize a fix you already made. If the finding was a *top-level*
+  conversation comment (no review-thread node id), a top-level `minions pr comment`
+  reply is informational only — never call it "resolved."
 - If you DO post a non-actionable note as its own **inline review thread**, resolve
-  it immediately after posting via the GraphQL `resolveReviewThread` mutation
-  (issue comments cannot be resolved this way; only review threads can):
+  it immediately after posting (equivalent to `--thread … --resolve`, or the raw
+  GraphQL `resolveReviewThread` mutation below; issue comments cannot be resolved
+  this way, only review threads can):
   ```bash
   # 1. find the thread node id for the comment you just posted
   gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){