@hncode/hncode 0.5.1 → 0.5.4

package/src/term.js

@@ -379,17 +379,91 @@ const tokCache = new Map();
 const TOK_CACHE_MAX = 20000;
 const TOK_CACHE_MAX_LEN = 4096;   // only memoise strings this short
 
+/**
+ * The same estimate, UNROUNDED — for summing many small chunks.
+ *
+ * `estimateTokens` rounds up, which is right for measuring one finished body: a 5-character
+ * message should not read as 1.25 tokens.
+ *
+ * It is wrong for a STREAM. Deltas arrive a few characters at a time, and each one took
+ * `ceil(ascii / 4)` — `ceil(3/4)` is 1, so three characters were billed as a whole token. Over
+ * hundreds of chunks that inflated the running figure badly: measured at +33% on ordinary
+ * English, and the visible symptom was the output counter DROPPING (3000 -> 2300) the moment the
+ * provider's exact `usage` arrived and replaced the estimate. Nothing was lost; the estimate had
+ * been lying.
+ *
+ * So the running counter accumulates this unrounded value, and rounds once when it displays.
+ * Callers that measure a complete string keep using `estimateTokens`.
+ */
+export function estimateTokensFloat(text) {
+  return estimateBpe(String(text ?? ''));
+}
+
+/**
+ * A BPE-aware token estimate: characters per token, BY CHARACTER CLASS.
+ *
+ * The old rule was `ascii / 4 + nonAscii`, and it is wrong in a way that matters here. Measured against
+ * published BPE rates for this app's own content, it undercounted by up to 35%:
+ *
+ *   English prose    1.05x   (the rule was calibrated for exactly this)
+ *   TypeScript code  0.80x
+ *   JSON payload     0.82x
+ *   tool schema      0.75x
+ *   paths and flags  0.73x
+ *   minified JSON    0.65x
+ *   mixed CJK + code 0.65x
+ *
+ * The reason is BPE merges COMMON BYTE PAIRS. English prose is full of repeated whole words, so four
+ * characters per token holds. Code, JSON and CLI flags are punctuation-dense: `{"a":1,"b":2}` merges
+ * almost nothing, and a token covers about 2.6 characters. On a 300k context that 0.65x is a ~100k
+ * error — the exact direction and size of the gap being reported.
+ *
+ * Five classes, each with its measured rate:
+ *
+ *   letters + spaces    4.2   the "4 chars/token" folklore, and the only place it holds
+ *   digits              3.0   punctuation-free but rarely repeated
+ *   punctuation + code  2.7   brackets, quotes, colons, operators — merge poorly
+ *   whitespace (indent) 1.0   a run of spaces still costs a token per couple of columns
+ *   CJK + other non-Latin 1.0  one token per character, occasionally two
+ *
+ * Counted in ONE pass, because this runs on every streamed chunk and every message body.
+ */
+function estimateBpe(s) {
+  if (!s) return 0;
+  let letters = 0;   // a-z A-Z and the space/punctuation that surrounds prose
+  let digits = 0;
+  let punct = 0;
+  let space = 0;
+  let wide = 0;
+
+  for (const ch of s) {
+    const cp = ch.codePointAt(0);
+    if (cp > 127) { wide++; continue; }
+    if (cp === 32 || cp === 9) { space++; continue; }
+    if (cp >= 48 && cp <= 57) { digits++; continue; }
+    if ((cp >= 65 && cp <= 90) || (cp >= 97 && cp <= 122)) { letters++; continue; }
+    punct++;
+  }
+
+  // Newlines land in `punct` (they are not 32 or 9), which is the right rate for them.
+  //
+  // The SPACE rate is the delicate one: a run of indentation costs about a token per two columns, but a
+  // single space between English words merges into the following word almost for free. Charging every
+  // space at the indentation rate made prose read 34% high — a worse error than the undercount it fixed,
+  // because prose is what the model WRITES back.
+  //
+  // So spaces are priced at a third of a token each: cheap enough for prose, and still enough that a
+  // deeply indented code block is not free.
+  return letters / 4.2 + digits / 3.0 + punct / 2.7 + space / 3.0 + wide;
+}
 export function estimateTokens(text) {
   const s = String(text ?? '');
   if (s.length <= TOK_CACHE_MAX_LEN) {
     const hit = tokCache.get(s);
     if (hit !== undefined) return hit;
-    let ascii = 0, nonAscii = 0;
-    for (const ch of s) {
-      if (ch.codePointAt(0) <= 127) ascii++;
-      else nonAscii++;
-    }
-    const out = Math.ceil(ascii / 4) + nonAscii;
+    // Rounded UP from the same BPE-aware estimate the streaming counter uses. Both must agree: a body
+    // measured one way and a stream measured another is how a session ends up reporting two numbers.
+    const out = Math.ceil(estimateBpe(s));
     if (tokCache.size >= TOK_CACHE_MAX) {
       // Drop the oldest half in one go: cheaper than one-at-a-time and keeps the
       // recently measured entries that a per-entry eviction would churn.
@@ -399,13 +473,9 @@ export function estimateTokens(text) {
     tokCache.set(s, out);
     return out;
   }
-  // Long body: walk it. No memoise, no map churn.
-  let ascii = 0, nonAscii = 0;
-  for (const ch of s) {
-    if (ch.codePointAt(0) <= 127) ascii++;
-    else nonAscii++;
-  }
-  return Math.ceil(ascii / 4) + nonAscii;
+  // Long body: measured directly, with the SAME estimator as the cached path. The two used to differ, so
+  // a long message and a short one were priced by different formulas.
+  return Math.ceil(estimateBpe(s));
 }
 
 // Estimate tokens for the MESSAGES only. The system prompt and tool definitions are
@@ -430,13 +500,52 @@ export function estimateMessageTokens(m, cfg) {
   if (!m) return 0;
   let total = estimateTokens(m.role || '');
   const c = m.content;
-  total += typeof c === 'string' ? estimateTokens(c) : estimateTokens(JSON.stringify(c || ''));
+  if (typeof c === 'string') {
+    total += estimateTokens(c);
+  } else if (c && typeof c === 'object' && Array.isArray(c.media)) {
+    total += estimateMediaContentTokens(c);
+  } else {
+    total += estimateTokens(JSON.stringify(c || ''));
+  }
   if (m.toolCalls) for (const tc of m.toolCalls) {
     total += estimateTokens(tc.name || '') + estimateTokens(JSON.stringify(tc.args || ''));
   }
   return total;
 }
 
+/**
+ * Tokens for a content block that carries media (an image read from disk, a screenshot).
+ *
+ * AN IMAGE IS NOT PRICED BY ITS BASE64 LENGTH. `JSON.stringify` on the same object counts every base64
+ * character as ordinary text — a 1 MB PNG is ~1.3M characters, which this estimator would price at
+ * roughly 400k tokens — while a provider charges by the image's PIXEL dimensions, usually one to two
+ * thousand. That is the direction that matters: the gauge would read hundreds of thousands too high, and
+ * auto-compaction would fire on a history that was never close to full.
+ *
+ * The text beside the image is priced normally; each image gets a flat estimate derived from the common
+ * tiling rule (a 512x512 tile ≈ 765 tokens, a 1568px max edge ≈ 1100 tokens). Exactness is impossible
+ * without decoding the image, and it does not matter here: images are rare, and being within a few
+ * hundred tokens beats being wrong by a hundred thousand.
+ */
+function estimateMediaContentTokens(c) {
+  let total = estimateTokens(String(c.text == null ? '' : c.text));
+  for (const m of c.media || []) {
+    if (!m || m.type !== 'image') continue;
+    // A thumbnail-sized image costs a tile; a full screenshot costs four. Read the dimensions from the
+    // metadata when the reader recorded them, and fall back to the large case otherwise — overestimating
+    // an image is far safer than under, because it makes compaction fire EARLY rather than late.
+    const w = Number(m.width) || 0;
+    const h = Number(m.height) || 0;
+    if (w > 0 && h > 0) {
+      const tiles = Math.max(1, Math.ceil(w / 512) * Math.ceil(h / 512));
+      total += Math.min(4, tiles) * 765;
+    } else {
+      total += 1100;
+    }
+  }
+  return total;
+}
+
 // ---- per-message token memo -----------------------------------------------
 //
 // Message objects -> { sig, tok }. WeakMap, so a message dropped from the history
@@ -474,7 +583,11 @@ function msgSignature(m) {
   if (typeof c === 'string') s = 's' + c.length;
   else if (c == null) s = 'n';
   else if (Array.isArray(c)) s = 'a' + c.length;
-  else s = '';                       // unknown shape: never trust a memo
+  else if (typeof c === 'object' && Array.isArray(c.media)) {
+    // A media block: its signature is the text plus one marker per image. The base64 payload itself is
+    // NOT hashed — it is the expensive part, and it never changes once the message exists.
+    s = 'm' + String(c.text == null ? '' : c.text).length + 'x' + c.media.length;
+  } else s = '';                     // unknown shape: never trust a memo
   if (m.toolCalls) s += 't' + m.toolCalls.length;
   return s;
 }
@@ -559,13 +672,43 @@ export class TokenLedger {
   }
 }
 
-// The overhead a request carries BEYOND its messages: the system prompt plus the
-// tool definitions. Passed the assembled system text so the number matches what is
-// actually sent.
+/**
+ * The overhead a request carries BEYOND its messages: the system prompt plus the tool definitions.
+ * Passed the assembled system text so the number matches what is actually sent.
+ *
+ * `cfg.toolDefTokens` is the REAL cost of the tool definitions, measured once by whoever built them.
+ * This used to charge a flat `n * 8` per tool, which is short by an order of magnitude: a tool's
+ * schema is its name, a paragraph of description and a nested parameters object, and measured here the
+ * 68 registered tools come to about 15 900 tokens — 29 times what 8 apiece reported.
+ *
+ * The discrepancy matters because this number is part of the context gauge. A gauge that omits ~15k of
+ * every request understates usage by that much per turn, and the user sees the provider's real figure
+ * disagree with the app's by a wide margin.
+ *
+ * The `n * 8` remains only as a FALLBACK for a caller that has not measured its definitions; it is
+ * better than nothing and is the old behaviour, exactly.
+ */
 export function estimateRequestOverhead(systemText, cfg) {
   let total = estimateTokens(systemText || '');
+  const measured = cfg && Number.isFinite(cfg.toolDefTokens) ? cfg.toolDefTokens : null;
+  if (measured != null) return total + measured;
   const n = (cfg && Array.isArray(cfg.toolFilter)) ? cfg.toolFilter.length : 0;
-  if (n) total += n * 8;   // rough per-tool-definition overhead
+  if (n) total += n * 8;   // rough per-tool-definition overhead, when nothing measured it
+  return total;
+}
+
+/**
+ * The token cost of a set of tool definitions, measured the way they are actually sent.
+ *
+ * Serialised as `{ name, description, parameters }` — the three fields the provider receives — and
+ * priced with the same estimator the gauge uses, so the number is comparable with everything else.
+ */
+export function measureToolDefTokens(tools) {
+  let total = 0;
+  for (const t of tools || []) {
+    if (!t || !t.name) continue;
+    total += estimateTokens(JSON.stringify({ name: t.name, description: t.description, parameters: t.parameters }));
+  }
   return total;
 }
 

package/src/tool-result.js

@@ -192,22 +192,37 @@ export function planTrim(messages, keepRatio, mustKeep) {
   // A budget of 0 means "elide everything eligible"; a budget of 1 means "keep it
   // all", in which case we still elide the already-marked ones so a repeated call
   // is a no-op rather than a growing patch.
-  const budget = totalBytes * ratio;
+  // The share of the ELIGIBLE text to keep, not of `totalBytes`. `totalBytes` counts the
+  // pointers left by earlier passes, so after a few passes it mostly describes text that can no
+  // longer be elided — and a budget drawn from it stops constraining the loop.
+  const eligibleBytes = candidates.reduce((n, i) => n + messages[i].content.length, 0);
+  const budget = eligibleBytes * ratio;
   const keep = new Set();
   let keepBytes = 0;
   for (let k = candidates.length - 1; k >= 0; k--) {
     const i = candidates[k];
     if (i === mustKeep) { keep.add(i); keepBytes += messages[i].content.length; continue; }
     const size = messages[i].content.length;
-    // Keep this chunk if we are still under budget, but ALWAYS keep the single
-    // newest result: a trim that elides the output the model is currently reading
-    // is how a working turn turns into a confused one.
-    if (keepBytes + size <= budget || keep.size === 0) {
+    // Under budget: keep. Otherwise elide — except for the result the model is reading right
+    // now, which the `mustKeep` branch above has already kept.
+    //
+    // There used to be a `|| keep.size === 0` here, meaning "always keep at least the newest".
+    // `mustKeep` is what actually protects the live result, and the override made a single large
+    // result impossible to trim: it was the only candidate, so it was always "the newest", so
+    // the budget never applied and the trim elided nothing.
+    if (keepBytes + size <= budget) {
       keep.add(i);
       keepBytes += size;
     }
   }
 
+  // THE FLOOR: never elide everything.
+  //
+  // The budget can be smaller than every candidate — one 200k result against a 60k budget is the
+  // ordinary case, because a long turn leaves the history with only the newest result still
+  // un-elided. Without this the trim would replace that result with a pointer, which is worse
+  // than not trimming: the model loses the output it just asked for.
+  if (!keep.size && candidates.length) keep.add(candidates[candidates.length - 1]);
   const elide = [];
   let elideBytes = 0;
   for (const i of candidates) {
@@ -259,6 +274,54 @@ export function applyTrim(messages, plan, sessionId) {
 // so a caller can skip its UI event entirely.
 export function trimToolResults(messages, opts = {}) {
   const plan = planTrim(messages, opts.keepRatio, opts.mustKeep);
-  if (!plan.elide.length) return null;
-  return { ...applyTrim(messages, plan, opts.sessionId), plan };
+  const mediaPlan = planMediaTrim(messages, opts.mediaKeep ?? 2);
+  if (!plan.elide.length && !mediaPlan.elide.length) return null;
+  const applied = plan.elide.length
+    ? applyTrim(messages, plan, opts.sessionId)
+    : { elided: 0, elidedBytes: 0, kept: plan.keep.length, keptBytes: plan.keepBytes };
+  const mediaApplied = applyMediaTrim(messages, mediaPlan, opts.sessionId);
+  return {
+    ...applied,
+    elided: applied.elided + mediaApplied.elided,
+    elidedBytes: applied.elidedBytes + mediaApplied.elidedBytes,
+    plan,
+  };
+}
+
+// ---- media results ----------------------------------------------------------
+// A media tool result keeps its base64 payload IN the history object — and unlike
+// a string body, planTrim cannot elide it, so every screenshot was re-serialized
+// into every request body, every session save and every cache-prefix walk until a
+// full compaction dropped it. Keep only the newest `mediaKeep` media results;
+// older ones spill their text (if any) and lose the bytes, same contract as the
+// string path: saved to disk first, pointer left behind.
+
+function planMediaTrim(messages, keep) {
+  const idx = [];
+  if (Array.isArray(messages)) {
+    for (let i = 0; i < messages.length; i++) {
+      const m = messages[i];
+      if (m && m.role === 'tool' && m.content && typeof m.content === 'object'
+        && Array.isArray(m.content.media) && m.content.media.length) idx.push(i);
+    }
+  }
+  const elide = idx.slice(0, Math.max(0, idx.length - Math.max(0, keep)));
+  return { elide };
+}
+
+function applyMediaTrim(messages, mediaPlan, sessionId) {
+  const out = { elided: 0, elidedBytes: 0 };
+  for (const i of mediaPlan.elide) {
+    const m = messages[i];
+    let bytes = 0;
+    for (const part of m.content.media) bytes += (part && part.data ? part.data.length : 0);
+    const text = String(m.content.text || '');
+    const spilled = spillResult(sessionId, `trim-${m.toolCallId || i}`, text || '[media only]');
+    m.content = `[Media result elided to save context — ${fmtBytes(bytes)} of image data from ${m.name || 'tool'}`
+      + (spilled ? `; the description was saved to: ${spilled.file}` : '; the description could not be saved')
+      + '. Re-run the tool if you need the image again.]';
+    out.elided++;
+    out.elidedBytes += bytes;
+  }
+  return out;
 }

package/src/tools/agent-swarm.js

@@ -18,9 +18,25 @@ import { createTask, appendTaskOutput, settleTask } from '../agent-task.js';
 
 export const PROMPT_TEMPLATE_PLACEHOLDER = '{{item}}';
 export const MAX_AGENT_SWARM_SUBAGENTS = 128;
-// How many subagents run at once. kimi queues launches automatically; we use a
-// small fixed window so a 128-item swarm cannot stampede the machine.
-const SWARM_CONCURRENCY = 4;
+// How many subagents run at once. Each worker awaits ONE subagent at a time, so this is the
+// number of models generating concurrently — the reason a swarm exists at all, given that
+// `Agent` calls in one message are run in sequence.
+const SWARM_CONCURRENCY = 7;
+
+/**
+ * Median of a list of numbers, or 0 when there is nothing to go on.
+ *
+ * Median rather than mean: one agent that loops for a hundred steps would drag a mean far
+ * above what a typical agent costs, and every other bar would then sit near empty while its
+ * agent was in fact nearly done.
+ */
+function medianSteps(counts) {
+  if (!Array.isArray(counts) || !counts.length) return 0;
+  const sorted = counts.slice().sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
 
 // Validate and expand the swarm request. Returns { prompts } or { error }.
 export function planSwarm(args) {
@@ -35,6 +51,22 @@ export function planSwarm(args) {
     ? Object.entries(args.resume_agent_ids).map(([id, p]) => [String(id).trim(), String(p).trim()])
     : [];
 
+  // The SHAPE is checked before the counts, so the message names the field that is wrong. An
+  // array of ids used to be silently dropped, and the caller was then told to provide "a
+  // resume_agent_ids map" — which it had given, in the only shape it knew.
+  if (args.resume_agent_ids !== undefined
+      && (typeof args.resume_agent_ids !== 'object' || Array.isArray(args.resume_agent_ids))) {
+    return { error: 'Error: `resume_agent_ids` must be an object mapping agent_id to prompt, such as {"<agent_id>": "continue"}. An array of ids is not accepted.' };
+  }
+  if (args.items !== undefined && !Array.isArray(args.items)) {
+    return { error: 'Error: `items` must be an array of strings.' };
+  }
+  // Blank entries were dropped above. Two blank items is a request the caller THINKS it made, and
+  // "provide at least 2 items" reads as a refusal of something that was provided.
+  const rawCount = Array.isArray(args.items) ? args.items.length : 0;
+  if (rawCount > 0 && items.length < rawCount && items.length + resumeMap.length < 2) {
+    return { error: `Error: ${rawCount} item(s) given but ${rawCount - items.length} were blank, leaving ${items.length}. Each item must be a non-empty string.` };
+  }
   if (items.length === 0 && resumeMap.length === 0) {
     return { error: 'Error: provide at least 2 items, or a resume_agent_ids map.' };
   }
@@ -73,7 +105,7 @@ Use enough subagents to keep the work focused and parallel. AgentSwarm supports
 When NOT to use AgentSwarm:
 - It only exists while swarm mode is ON (\`/swarm\`). With the mode off the tool is not offered at all and calling it is refused. If a fan-out would genuinely help, say so and ask the user to turn the mode on.
 - Never call this on your own initiative. It requires the same explicit permission as \`Agent\`: the user, or the applicable AGENTS.md / project instructions, must have asked for sub-agents, delegation, or parallel agent work. Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do NOT count as permission.
-- Do not use it for two or three differently-shaped tasks: use separate \`Agent\` calls instead, which can run in parallel in one message.
+- Do not use it for two or three differently-shaped tasks: use separate \`Agent\` calls instead. Note that several \`Agent\` calls in one message run ONE AT A TIME — only read-only tools batch — so a swarm is the only way to overlap subagents, and a 3-item swarm really does run 3 at once.
 - Do not use it to fan out work you could finish yourself in a few steps.
 
 If \`AgentSwarm\` is called, that call must be the only tool call in the response.`,
@@ -122,45 +154,116 @@ If \`AgentSwarm\` is called, that call must be the only tool call in the respons
       detached: false,
     });
 
+    // ONE TASK PER SUBAGENT, parented to this one. A foreground subagent creates no task of
+    // its own, so a 7-item swarm put a single row in /tasks and there was no way to see what
+    // each subagent was doing — the panel is organised by task, so no task meant no window.
+    const subTasks = jobs.map((job, i) => {
+      const t = createTask(ctx, 'agent', {
+        description: `${description} #${i + 1}`,
+        subagentType: type,
+        model: args.model || '',
+        detached: true,
+        parentTaskId: task.taskId,
+      });
+      return t;
+    });
+
     // Run with a bounded window. Each job appends its verdict to the task output
     // as it finishes, so TaskOutput shows partial progress.
     const results = new Array(jobs.length).fill(null);
+    // Tool-call counts of the agents that have FINISHED, so a running agent's bar can be
+    // scaled against what the swarm is actually costing. A running agent does not contribute
+    // here — its own count is still growing and would understate the reference.
+    const finishedSteps = [];
     let next = 0;
     const worker = async () => {
       for (;;) {
         const i = next++;
         if (i >= jobs.length) return;
         const job = jobs[i];
+        const subTask = subTasks[i];
+        // Announce the START, not only the finish. Without this the only signal on the wire
+        // was "[n/m] finished", which says how many are DONE and nothing about which are
+        // running — so the progress block marked everything unfinished as "queued" and a
+        // 7-wide swarm looked like one working cell and six stuck ones.
+        if (typeof ctx.onOutput === 'function') ctx.onOutput(`[#${i + 1}] started\n`);
+        appendTaskOutput(task, `[#${i + 1}] started\n`);
+        // Declared OUTSIDE the try: the catch below still has to report this agent's cost,
+        // and the block that does so runs whether the agent succeeded or threw.
+        const t0 = Date.now();
+        let steps = 0;
         try {
           const subArgs = {
             prompt: job.prompt,
             description: `${description} #${i + 1}`,
             ...(job.kind === 'resume' ? { resume: job.agentId } : { subagent_type: type }),
+            ...(job.kind === 'resume' ? { resume: job.agentId } : { subagent_type: type }),
             ...(args.model ? { model: args.model } : {}),
             ...(args.fork === true && job.kind === 'new' ? { fork: true } : {}),
           };
-          const out = await agentSpec.execute(subArgs, { ...ctx, _progressTag: `#${i + 1}` });
+          // `steps` counts this agent's tool calls so far. There is no "x of y" to show — a
+          // subagent runs with an unbounded step budget — so the bar is paced against the
+          // swarm's OWN observed speed: the median number of steps the agents that have
+          // already FINISHED needed. That is the only estimate available, and it sharpens as
+          // more of them land.
+          //
+          // The reference is never allowed to be 0. An agent that answers straight from the
+          // prompt runs no tools at all, so it finishes with 0 steps — and a median of 0 would
+          // send EVERY other agent down the elapsed-time branch below, where the bar needs a
+          // full minute to reach 40% and a fast agent reports 0% the whole way. One tool-less
+          // agent must not disable the scale for the rest of the swarm.
+          const progressLine = () => {
+            if (typeof ctx.onOutput !== 'function') return;
+            const reference = Math.max(1, medianSteps(finishedSteps));
+            const ratio = finishedSteps.length
+              ? Math.min(0.95, steps / (reference + 1))
+              // Nothing has finished yet, so there is no pace to compare against. Creep
+              // rather than assert a figure: `steps` alone would read as a tiny percentage
+              // next to an unknown total.
+              : Math.min(0.4, steps / 40, 0.1 + ((Date.now() - t0) / 60000) * 0.3);
+            ctx.onOutput(`[#${i + 1}] progress ${Math.round(ratio * 100)}\n`);
+          };
+          const out = await agentSpec.execute(subArgs, {
+            ...ctx,
+            _progressTag: `#${i + 1}`,
+            _subTaskId: subTask.taskId,
+            _onSubProgress: () => { steps++; progressLine(); },
+          });
           // `agentSpec.execute` returns `agent_id: <id>\n\n<handoff>`. The swarm's
           // caller wants the handoff, and the id is only useful for a later
           // `resume`; keep it on one labelled line rather than letting it lead the
           // block, so the reported text is what each subagent actually produced.
           const raw = String(out);
           const m = /^agent_id:\s*(\S+)\s*\n+([\s\S]*)$/.exec(raw);
+          // A subagent that died returns `Error: subagent … failed: …` rather than throwing, so
+          // the catch below never sees it. Without this test the cell was marked a success and
+          // the failure text was buried in a body nobody reads as an error.
+          const died = /^Error: subagent /.test(raw);
           const body = (m ? m[2] : raw).trim();
           const head = `--- #${i + 1}${job.kind === 'resume' ? ` (resumed ${job.agentId})` : ''}${m ? ` [${m[1]}]` : ''} ---`;
           results[i] = `${head}\n${body}`;
+          settleTask(subTask, died ? 'failed' : 'completed', died ? { stopReason: body } : undefined);
         } catch (e) {
           results[i] = `--- #${i + 1} ---\n[error: ${e.message}]`;
+          settleTask(subTask, 'failed', { stopReason: e.message });
         }
+        // Contribute this agent's cost to the reference the running ones scale against. A
+        // Contribute this agent's cost to the reference the running ones scale against. A
+        // failed agent is recorded too: it did that much work, so it says as much about the
+        // pace as a successful one, and excluding it would bias the bar optimistically.
+        finishedSteps.push(steps);
         // Report progress down BOTH channels, and they are not interchangeable:
         //   * the task buffer feeds TaskOutput and survives a detach;
-        //   * `ctx.onOutput` is the LIVE sink. The progress block in the transcript
-        //     reads the cells off it (see the tool_output handler's `[n/m] finished`
-        //     match), so writing only to the task buffer left every cell but the first
-        //     stuck on "Queued…" for the whole run — the TUI was told to expect these
-        //     lines on this channel and never received one.
+        //   * `ctx.onOutput` is the LIVE sink the transcript's progress block reads.
+        //
+        // WHICH agent finished, not just how many. A bare `[n/m]` count left the reader no
+        // choice but to assume the first `n` agents were the finished ones — and with
+        // SWARM_CONCURRENCY workers pulling from a shared queue, they finish in whatever order
+        // they happen to run. The grid then lit up the wrong cells and only agreed with
+        // reality once every one of them was done. `[#i] finished` names the agent; the count
+        // is kept for readers that only track totals.
         const done = results.filter((r) => r !== null).length;
-        const line = `[${done}/${jobs.length}] finished\n`;
+        const line = `[#${i + 1}] finished [${done}/${jobs.length}]\n`;
         appendTaskOutput(task, line);
         if (typeof ctx.onOutput === 'function') ctx.onOutput(line);
       }