mixdog 1.2.5 → 1.3.0

package/src/runtime/shared/agent-avatar.mjs

@@ -0,0 +1,320 @@
+// The Mixdog mascot: a blocky pixel creature on a 16x12 grid, painted from the
+// string layers in agent-avatar-sprites.mjs (design/mockups/mixy-art). Every
+// look is the same body block; the species (ears, marks, tail, legs), an
+// accessory, the expression and the colour vary. An agent's `agent.json`
+// stores its pick as `avatar: { kind: 'mascot', species, accessory,
+// expression, color }` (an older `variant` reads as its mapped look), or its
+// own images per motion state as `avatar: { kind: 'custom', states: { idle,
+// typing?, message? } }`. An agent without one gets a stable look from its id.
+import { MIXY_AGENT_ID } from '../agent/orchestrator/session/agent-home.mjs';
+import { MASCOT_SPRITES } from './agent-avatar-sprites.mjs';
+
+/** The palette an avatar colour is chosen from. */
+export const AGENT_AVATAR_COLORS = Object.freeze([
+  '#e6e6e6',
+  '#9a9a9a',
+  '#f06a5f',
+  '#f59a42',
+  '#f2c94c',
+  '#5cc98a',
+  '#3fc1c9',
+  '#5b9bff',
+  '#9b7bff',
+  '#ef6fb0',
+]);
+
+/** Every species a user can pick: the six dogs. Mixy's own (`mixy`) is not one of them. */
+export const MASCOT_SPECIES = Object.freeze(['labrador', 'shepherd', 'terrier', 'corgi', 'husky', 'shiba']);
+export const MASCOT_ACCESSORIES = Object.freeze(['none', 'collar', 'glasses', 'beanie', 'scarf', 'bow']);
+/** Picks that were removed, read as their nearest remaining option. */
+const RETIRED_SPECIES = { dalmatian: 'labrador', cat: 'labrador', bird: 'labrador', robot: 'labrador' };
+const RETIRED_ACCESSORIES = { headset: 'glasses' };
+export const MASCOT_EXPRESSIONS = Object.freeze(['calm', 'happy', 'wink', 'sleepy']);
+
+/** Mixy, the primary assistant: its own silver pup with one ear up and a
+ *  slate collar with the gold star medal. Never offered in the picker. */
+export const MIXY_AVATAR = Object.freeze({
+  kind: 'mascot',
+  species: 'mixy',
+  accessory: 'none',
+  expression: 'calm',
+  color: '#e6e6e6',
+});
+
+/** The fixed inks a sprite letter names; B, D, L and E depend on the look. */
+export const MASCOT_INKS = Object.freeze({
+  K: '#141414',
+  G: '#f2c94c',
+  R: '#e5534b',
+  O: '#f59a42',
+  W: '#f4f4f4',
+  C: '#3fc1c9',
+  M: '#8a8a90',
+  S: '#2a2b30',
+  P: '#ef8fb4',
+  N: '#f06a5f',
+  n: '#c4544c',
+  r: '#b94039',
+  F: '#ef6fb0',
+  f: '#b8497f',
+});
+
+/** `hex` with every channel scaled by `k`. */
+export function shadeHex(hex, k) {
+  const n = Number.parseInt(hex.slice(1), 16);
+  const channel = (shift) =>
+    Math.round(((n >> shift) & 255) * k)
+      .toString(16)
+      .padStart(2, '0');
+  return `#${channel(16)}${channel(8)}${channel(0)}`;
+}
+
+/** `hex` mixed `k` of the way to white. */
+function liftHex(hex, k) {
+  const n = Number.parseInt(hex.slice(1), 16);
+  const channel = (shift) => {
+    const value = (n >> shift) & 255;
+    return Math.round(value + (255 - value) * k)
+      .toString(16)
+      .padStart(2, '0');
+  };
+  return `#${channel(16)}${channel(8)}${channel(0)}`;
+}
+
+// The 12 looks before species existed, `<ears>-<expression>-<plain|collar>`:
+// each reads as the species with those ears, the collar as an accessory.
+const LEGACY_EARS = { floppy: 'labrador', perky: 'shepherd', folded: 'terrier' };
+const LEGACY_VARIANTS = Object.keys(LEGACY_EARS).flatMap((ears) =>
+  ['calm', 'happy'].flatMap((expression) => ['plain', 'collar'].map((extra) => `${ears}-${expression}-${extra}`))
+);
+
+/** An older `variant` as its species, accessory and expression; null if unknown. */
+export function mascotFromVariant(variant) {
+  if (!LEGACY_VARIANTS.includes(variant)) return null;
+  const [ears, expression, extra] = variant.split('-');
+  return { species: LEGACY_EARS[ears], accessory: extra === 'collar' ? 'collar' : 'none', expression };
+}
+
+/** `species-accessory-expression`: a look's key (data attributes, tests). */
+export const mascotLook = (avatar) => `${avatar.species}-${avatar.accessory}-${avatar.expression}`;
+
+function layerCells(rows, color, eye) {
+  if (!rows) return [];
+  const ink = (key) => {
+    if (key === 'B') return color;
+    if (key === 'D') return shadeHex(color, 0.7);
+    if (key === 'L') return liftHex(color, 0.35);
+    return MASCOT_INKS[key === 'E' ? eye : key];
+  };
+  const cells = [];
+  rows.forEach((row, y) => {
+    for (let x = 0; x < row.length; x += 1) if (row[x] !== '.') cells.push({ x, y, fill: ink(row[x]) });
+  });
+  return cells;
+}
+
+/** A look's cells by part, in paint order — the groups the renderer draws
+ *  (tail, legs, then the bobbing body with its ears, marks, eyes and
+ *  accessory). `blink` is the closed eyes an idle blink shows. Null for an
+ *  unknown species. */
+export function mascotParts(avatar) {
+  const species = MASCOT_SPRITES.species[avatar.species];
+  if (!species) return null;
+  const paint = (rows) => layerCells(rows, avatar.color, species.eye);
+  return {
+    tail: paint(species.tail && MASCOT_SPRITES.tails[species.tail]),
+    legs: paint(MASCOT_SPRITES.legs[species.legs]),
+    body: paint(MASCOT_SPRITES.body),
+    ear: paint(species.ears),
+    marks: paint(species.marks),
+    eyes: paint(MASCOT_SPRITES.eyes[avatar.expression]),
+    blink: paint(MASCOT_SPRITES.eyes.sleepy),
+    accessory: paint(MASCOT_SPRITES.accessories[avatar.accessory]),
+  };
+}
+
+/** The look as one still frame: each cell's final fill. [] when unknown. */
+export function mascotCells(avatar) {
+  const parts = mascotParts(avatar);
+  if (!parts) return [];
+  const cells = new Map();
+  for (const part of ['tail', 'legs', 'body', 'ear', 'marks', 'eyes', 'accessory']) {
+    for (const cell of parts[part]) cells.set(`${cell.y},${cell.x}`, cell);
+  }
+  return [...cells.values()];
+}
+
+/** Cells as one SVG path per fill, each row's run one rectangle. */
+export function cellPaths(cells) {
+  const byFill = new Map();
+  for (const { x, y, fill } of cells) {
+    const rows = byFill.get(fill) ?? new Map();
+    byFill.set(fill, rows);
+    rows.set(y, [...(rows.get(y) ?? []), x]);
+  }
+  return [...byFill].map(([fill, rows]) => {
+    let d = '';
+    for (const [y, xs] of [...rows].sort(([a], [b]) => a - b)) {
+      const sorted = [...new Set(xs)].sort((a, b) => a - b);
+      for (let i = 0; i < sorted.length; ) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j += 1;
+        const run = j - i + 1;
+        d += `M${sorted[i]} ${y}h${run}v1h-${run}z`;
+        i = j + 1;
+      }
+    }
+    return { fill, d };
+  });
+}
+
+/** The motion states an avatar shows today, `idle` first (a custom avatar's
+ *  one required image, and every missing state's fallback). */
+export const AGENT_AVATAR_STATES = Object.freeze(['idle', 'typing', 'message']);
+
+/** The single image avatar before per-state images: a PNG beside AGENT.md
+ *  under a content-hash name. Still read, as a custom avatar's idle image. */
+export const AGENT_AVATAR_IMAGE_FILE = /^avatar-[0-9a-f]{12}\.png$/;
+/** One state's image in `agents/<id>/avatar/`, under a content-hash name (a
+ *  new upload is a new name, so caches by name never go stale). An animated
+ *  one keeps its still first frame beside it (avatarPosterFile). */
+export const AGENT_AVATAR_STATE_FILE = /^(idle|typing|message)-[0-9a-f]{12}\.(png|gif|webp)$/;
+export const AGENT_AVATAR_DIR = 'avatar';
+/** The largest image upload accepted, and the largest side of an animation. */
+export const AGENT_AVATAR_IMAGE_MAX_BYTES = 1024 * 1024;
+export const AGENT_AVATAR_IMAGE_MAX_SIDE = 512;
+
+/** A state image's path under the agent's folder ('/'-separated). */
+export const agentAvatarStatePath = (file) =>
+  AGENT_AVATAR_IMAGE_FILE.test(file) ? file : `${AGENT_AVATAR_DIR}/${file}`;
+/** The still first frame stored beside an animated state image. */
+export const avatarPosterFile = (file) => file.replace(/\.(png|gif|webp)$/, '.poster.png');
+/** The image a custom avatar shows in `state`: its own, else idle's. */
+export const customAvatarStateFile = (avatar, state) => avatar.states[state] ?? avatar.states.idle;
+
+const u16le = (bytes, at) => bytes[at] | (bytes[at + 1] << 8);
+const u24le = (bytes, at) => bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+const u32be = (bytes, at) => ((bytes[at] << 24) | (bytes[at + 1] << 16) | (bytes[at + 2] << 8) | bytes[at + 3]) >>> 0;
+const ascii = (bytes, at, length) => String.fromCharCode(...bytes.subarray(at, at + length));
+
+/** An upload's format and size, read from its header bytes: a PNG (an APNG
+ *  counts as animated), a GIF (always treated as animated) or a WebP; null
+ *  for anything else — SVG and every other markup included. */
+export function avatarImageInfo(bytes) {
+  if (!(bytes instanceof Uint8Array) || bytes.length < 30) return null;
+  if (u32be(bytes, 0) === 0x89504e47 && u32be(bytes, 4) === 0x0d0a1a0a && ascii(bytes, 12, 4) === 'IHDR') {
+    let animated = false;
+    for (let at = 8; at + 8 <= bytes.length; at += 12 + u32be(bytes, at)) {
+      const type = ascii(bytes, at + 4, 4);
+      if (type === 'acTL') animated = true;
+      if (type === 'IDAT' || type === 'IEND') break;
+    }
+    return { format: 'png', width: u32be(bytes, 16), height: u32be(bytes, 20), animated };
+  }
+  if (ascii(bytes, 0, 6) === 'GIF87a' || ascii(bytes, 0, 6) === 'GIF89a') {
+    return { format: 'gif', width: u16le(bytes, 6), height: u16le(bytes, 8), animated: true };
+  }
+  if (ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP') {
+    const chunk = ascii(bytes, 12, 4);
+    if (chunk === 'VP8X') {
+      const animated = (bytes[20] & 0x02) !== 0;
+      return { format: 'webp', width: u24le(bytes, 24) + 1, height: u24le(bytes, 27) + 1, animated };
+    }
+    if (chunk === 'VP8 ') {
+      return { format: 'webp', width: u16le(bytes, 26) & 0x3fff, height: u16le(bytes, 28) & 0x3fff, animated: false };
+    }
+    if (chunk === 'VP8L') {
+      const bits = (bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24)) >>> 0;
+      return { format: 'webp', width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1, animated: false };
+    }
+  }
+  return null;
+}
+
+/** Why bytes cannot be a state image ('' when they can): not a PNG, GIF or
+ *  WebP, over 1 MB, not square, or over 512px. */
+export function agentAvatarImageProblem(bytes) {
+  const info = avatarImageInfo(bytes);
+  if (!info) return 'must be a PNG, GIF or WebP image';
+  if (bytes.length > AGENT_AVATAR_IMAGE_MAX_BYTES) return 'is larger than 1 MB';
+  if (!info.width || info.width !== info.height) return 'must be square';
+  if (info.width > AGENT_AVATAR_IMAGE_MAX_SIDE) return 'must be 512px or smaller';
+  return '';
+}
+
+function normalizeCustom(states) {
+  if (!states || typeof states !== 'object') return null;
+  const kept = {};
+  for (const state of AGENT_AVATAR_STATES) {
+    const file = states[state];
+    if (file == null) continue;
+    const own = typeof file === 'string' && AGENT_AVATAR_STATE_FILE.test(file) && file.startsWith(`${state}-`);
+    const legacy = state === 'idle' && typeof file === 'string' && AGENT_AVATAR_IMAGE_FILE.test(file);
+    if (!own && !legacy) return null;
+    kept[state] = file;
+  }
+  return kept.idle ? { kind: 'custom', states: kept } : null;
+}
+
+const pick = (value, list, fallback) => (value == null ? fallback : list.includes(value) ? value : null);
+
+/** A stored avatar as the app understands it, or null when it is not one. An
+ *  older single image reads as a custom avatar with only its idle image; an
+ *  older mascot `variant` as its mapped species, accessory and expression. */
+export function normalizeAgentAvatar(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.kind === 'image') {
+    return typeof value.file === 'string' && AGENT_AVATAR_IMAGE_FILE.test(value.file)
+      ? { kind: 'custom', states: { idle: value.file } }
+      : null;
+  }
+  if (value.kind === 'custom') return normalizeCustom(value.states);
+  if (value.kind !== 'mascot') return null;
+  const color = typeof value.color === 'string' ? value.color.toLowerCase() : '';
+  if (!AGENT_AVATAR_COLORS.includes(color)) return null;
+  const look =
+    value.species == null && typeof value.variant === 'string'
+      ? mascotFromVariant(value.variant)
+      : {
+          species: pick(
+            RETIRED_SPECIES[value.species] ?? value.species,
+            [...MASCOT_SPECIES, MIXY_AVATAR.species],
+            null
+          ),
+          accessory: pick(RETIRED_ACCESSORIES[value.accessory] ?? value.accessory, MASCOT_ACCESSORIES, 'none'),
+          expression: pick(value.expression, MASCOT_EXPRESSIONS, 'calm'),
+        };
+  if (!look?.species || !look.accessory || !look.expression) return null;
+  return { kind: 'mascot', ...look, color };
+}
+
+// FNV-1a: a small stable string hash, the same on every platform.
+function hashId(id) {
+  let hash = 0x811c9dc5;
+  for (const char of String(id)) {
+    hash ^= char.codePointAt(0);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash;
+}
+
+/** The look of an agent that never picked one: fixed by its id — the
+ *  species, accessory and colour it had before species existed (its old
+ *  variant, mapped), with the neutral face every default wears. */
+export function defaultAgentAvatar(id) {
+  const hash = hashId(id);
+  return {
+    kind: 'mascot',
+    ...mascotFromVariant(LEGACY_VARIANTS[hash % LEGACY_VARIANTS.length]),
+    expression: 'calm',
+    color: AGENT_AVATAR_COLORS[Math.floor(hash / LEGACY_VARIANTS.length) % AGENT_AVATAR_COLORS.length],
+  };
+}
+
+/** What an agent shows: its own images, else Mixy's fixed look (for Mixy),
+ *  its own mascot pick, or its id default. */
+export function agentAvatar(id, stored) {
+  const own = normalizeAgentAvatar(stored);
+  if (id === MIXY_AGENT_ID) return own ?? { ...MIXY_AVATAR };
+  return own ?? defaultAgentAvatar(id);
+}

package/src/runtime/shared/agent-route-config.d.mts

@@ -0,0 +1,3 @@
+// Types for the desktop's one import of agent-route-config.mjs.
+export const WORKFLOW_AGENT_KIND: 'agent';
+export function isContactAgentId(value: unknown, kind?: unknown): boolean;

package/src/runtime/shared/agent-route-config.mjs

@@ -16,6 +16,22 @@ export const DEFAULT_DISABLED_AGENT_IDS = Object.freeze([
 // runs only once the user turns it on and picks its model.
 export const DEFAULT_DISABLED_AGENT_ROSTER = Object.freeze([...DEFAULT_DISABLED_AGENT_IDS, 'maintainer']);
 
+/** The AGENT.md frontmatter `kind` the Workflows page writes when it creates
+ *  an agent: a workflow delegation role, never a contact (봇). */
+export const WORKFLOW_AGENT_KIND = 'agent';
+
+/** A contact agent (a 봇): one the user made — not Mixy ('lead'), not a
+ *  shipped role (the starter sub-agents Worker, Reviewer, … and the
+ *  Maintainer), and not marked `kind: agent` (made on the Workflows page).
+ *  `kind` is the definition's frontmatter `kind`; an unmarked custom agent
+ *  stays a contact. The one rule for the runtime (delegation, agent catalogs)
+ *  and the desktop (contacts, agent lists). */
+export function isContactAgentId(value, kind) {
+  const id = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  const marked = typeof kind === 'string' && kind.trim().toLowerCase() === WORKFLOW_AGENT_KIND;
+  return Boolean(id) && id !== 'lead' && !DEFAULT_DISABLED_AGENT_ROSTER.includes(id) && !marked;
+}
+
 function record(value) {
   return isPlainObject(value) ? value : {};
 }

package/src/runtime/shared/atomic-file.mjs

@@ -19,7 +19,8 @@ import {
   unlink as unlinkAsync,
   writeFile as writeFileAsync,
 } from 'node:fs/promises';
-import { dirname, basename, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { dirname, basename, join, relative, isAbsolute, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { DEFAULT_BACKOFFS_MS, recordLockTiming, withFileLock, withFileLockSync } from './file-lock.mjs';
 import {
@@ -88,21 +89,30 @@ function nextRenameDelayMs(err, attempt, backoffs) {
   return backoffs[attempt] + Math.floor(Math.random() * Math.min(50, Math.max(1, backoffs[attempt])));
 }
 
+/**
+ * Attempt `attempt` (0-based) of the renameWithRetry schedule: null when the
+ * rename landed, else the delay before the next attempt. Throws the rename's
+ * own error when that error or the attempt count ends the loop — the same
+ * final error renameWithRetrySync throws. A caller that must not block waits
+ * the delay asynchronously between attempts.
+ */
+export function renameAttempt(src, dst, attempt, opts = {}) {
+  try {
+    renameSync(src, dst);
+    return null;
+  } catch (err) {
+    const delayMs = nextRenameDelayMs(err, attempt, renameBackoffs(opts));
+    if (delayMs === null) throw err;
+    return delayMs;
+  }
+}
+
 export function renameWithRetrySync(src, dst, opts = {}) {
-  const backoffs = renameBackoffs(opts);
-  let lastErr = null;
-  for (let attempt = 0; attempt <= backoffs.length; attempt++) {
-    try {
-      renameSync(src, dst);
-      return true;
-    } catch (err) {
-      lastErr = err;
-      const delayMs = nextRenameDelayMs(err, attempt, backoffs);
-      if (delayMs === null) break;
-      sleepSync(delayMs);
-    }
+  for (let attempt = 0; ; attempt++) {
+    const delayMs = renameAttempt(src, dst, attempt, opts);
+    if (delayMs === null) return true;
+    sleepSync(delayMs);
   }
-  throw lastErr;
 }
 
 async function renameWithRetry(src, dst, opts = {}) {
@@ -155,7 +165,18 @@ async function fsyncPathAsync(path, tolerated) {
   }
 }
 
+// Node sets NODE_TEST_CONTEXT in every `--test` process. A secret (credential)
+// write from a test must land under the temp dir; anything else is a fixture
+// about to overwrite a real profile, so fail loudly instead.
+function assertTestSecretWriteSafe(filePath, opts) {
+  if (opts.secret !== true || !process.env.NODE_TEST_CONTEXT) return;
+  const rel = relative(resolve(tmpdir()).toLowerCase(), resolve(filePath).toLowerCase());
+  if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return;
+  throw new Error(`refusing to write a secret outside the temp dir under node --test: ${filePath}`);
+}
+
 export function writeFileAtomicSync(filePath, data, opts = {}) {
+  assertTestSecretWriteSafe(filePath, opts);
   const run = () => {
     const dir = dirname(filePath);
     mkdirSync(dir, { recursive: true });
@@ -280,6 +301,7 @@ export function updateJsonAtomicSync(filePath, mutator, opts = {}) {
 // block the host event loop on read/write/fsync/rename.
 // Async writes retain atomic rename publication; truncate recovery is sync-only.
 export async function writeFileAtomicAsync(filePath, data, opts = {}) {
+  assertTestSecretWriteSafe(filePath, opts);
   const run = async () => {
     const dir = dirname(filePath);
     await mkdirAsync(dir, { recursive: true });

package/src/runtime/shared/background-tasks.mjs

@@ -7,6 +7,7 @@ import {
 } from './tool-execution-contract.mjs';
 import { presentErrorText } from './err-text.mjs';
 import { clean } from './clean.mjs';
+import { emitSessionActivityChange } from './session-activity-signal.mjs';
 import {
   parseTaskNotification,
   renderTaskCompletionEnvelope,
@@ -104,12 +105,17 @@ function hasScopeCriteria(scope) {
   return Boolean(scope?.callerSessionId || scope?.routingSessionId || scope?.clientHostPid);
 }
 
-function taskMatchesScope(task, options = {}, { includeUnattributed = true } = {}) {
+function taskSessionIdOf(task) {
+  return task.ownerSessionId || task.notifyContext?.callerSessionId || task.notifyContext?.routingSessionId || null;
+}
+
+// `scope` is normalizeTaskScope(options), normalized once per scan by the
+// caller: a scan is O(tasks), and the daemon runs one per session per
+// busy-count, so per-task normalization multiplied into seconds under load.
+function taskMatchesScope(task, scope, { includeUnattributed = true } = {}) {
   if (!task) return false;
-  const scope = normalizeTaskScope(options);
   if (!hasScopeCriteria(scope)) return true;
-  const taskSessionId =
-    task.ownerSessionId || task.notifyContext?.callerSessionId || task.notifyContext?.routingSessionId || null;
+  const taskSessionId = taskSessionIdOf(task);
   const taskClientHostPid = task.clientHostPid || task.notifyContext?.clientHostPid || null;
   // Legacy/unattributed tasks remain visible so old async jobs are still recoverable.
   if (!taskSessionId && !taskClientHostPid) return includeUnattributed;
@@ -127,11 +133,13 @@ function pruneTasks(options = {}) {
   const { force = false, surface } = options;
   const now = Date.now();
   const wanted = clean(surface);
-  for (const [taskId, task] of [...tasks.entries()]) {
+  const scope = normalizeTaskScope(options);
+  // Deleting the entry being visited is safe during Map iteration.
+  for (const [taskId, task] of tasks) {
     if (wanted && task.surface !== wanted) continue;
-    if (!taskMatchesScope(task, options)) continue;
     const finishedAt = task.finishedAtMs || 0;
-    if (force || (finishedAt > 0 && now - finishedAt > TASK_TTL_MS)) tasks.delete(taskId);
+    if (!force && !(finishedAt > 0 && now - finishedAt > TASK_TTL_MS)) continue;
+    if (taskMatchesScope(task, scope)) tasks.delete(taskId);
   }
   if (tasks.size <= MAX_TASKS) return;
   const removable = [...tasks.values()]
@@ -197,6 +205,7 @@ export function registerBackgroundTask({
     notifyOnCancel: notifyOnCancel === true,
   };
   tasks.set(id, task);
+  emitSessionActivityChange(task.ownerSessionId || '');
   return task;
 }
 
@@ -230,38 +239,64 @@ export function getBackgroundTask(taskId, options = {}) {
   if (!task) return null;
   const wanted = clean(options.surface);
   if (wanted && task.surface !== wanted) return null;
-  if (!taskMatchesScope(task, options)) return null;
+  if (!taskMatchesScope(task, normalizeTaskScope(options))) return null;
   return task;
 }
 
+function countsAsActive(task, wanted, awaitedOnly) {
+  return task.status === 'running' && !(awaitedOnly && task.detached === true) && (!wanted || task.surface === wanted);
+}
+
 /** Lifetime signal: a session-owned background task remains live
- * work even while the interactive turn is idle and every view is detached. */
+ * work even while the interactive turn is idle and every view is detached.
+ * `awaitedOnly` leaves out `detached` tasks: processes a finished command
+ * deliberately left running (an app or server it launched), which nothing is
+ * waiting on and which may outlive the session's work by days.
+ * A read: pruning only ever drops finished tasks, which never count here. */
 export function hasActiveBackgroundTasks(options = {}) {
-  pruneTasks(options);
   const wanted = clean(options.surface);
-  return [...tasks.values()].some(
-    (task) =>
-      task.status === 'running' &&
-      (!wanted || task.surface === wanted) &&
-      taskMatchesScope(task, options, { includeUnattributed: false })
-  );
+  const awaitedOnly = options.awaitedOnly === true;
+  const scope = normalizeTaskScope(options);
+  for (const task of tasks.values()) {
+    if (countsAsActive(task, wanted, awaitedOnly) && taskMatchesScope(task, scope, { includeUnattributed: false })) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Every owner session `hasActiveBackgroundTasks({ callerSessionId, surface,
+ *  awaitedOnly })` answers true for, from ONE pass over the tasks: a caller
+ *  asking for every session (busy counts, pool rows) scans once instead of
+ *  once per session. */
+export function activeBackgroundTaskSessionIds(options = {}) {
+  const wanted = clean(options.surface);
+  const awaitedOnly = options.awaitedOnly === true;
+  const ids = new Set();
+  for (const task of tasks.values()) {
+    if (!countsAsActive(task, wanted, awaitedOnly)) continue;
+    const sessionId = taskSessionIdOf(task);
+    if (sessionId) ids.add(sessionId);
+  }
+  return ids;
 }
 
 export function listBackgroundTasks(options = {}) {
   const { surface } = options;
   pruneTasks(options);
   const wanted = clean(surface);
+  const scope = normalizeTaskScope(options);
   return [...tasks.values()]
     .filter((task) => !wanted || task.surface === wanted)
-    .filter((task) => taskMatchesScope(task, options))
+    .filter((task) => taskMatchesScope(task, scope))
     .map((task) => taskSummary(task));
 }
 
 export function cleanupBackgroundTasks(options = {}) {
   const wanted = clean(options.surface);
+  const scope = normalizeTaskScope(options);
   const countForSurface = () =>
-    [...tasks.values()].filter((task) => (!wanted || task.surface === wanted) && taskMatchesScope(task, options))
-      .length;
+    [...tasks.values()].filter((task) => (!wanted || task.surface === wanted) && taskMatchesScope(task, scope)).length;
   const before = countForSurface();
   pruneTasks(options);
   const after = countForSurface();
@@ -331,6 +366,7 @@ export function cancelBackgroundTasks(options = {}) {
   const reason = clean(options.reason) || 'cancelled';
   const wanted = clean(options.surface);
   const executionSessionId = clean(options.executionSessionId);
+  const scope = normalizeTaskScope(options);
   let cancelled = 0;
   for (const task of [...tasks.values()]) {
     if (wanted && task.surface !== wanted) continue;
@@ -341,7 +377,7 @@ export function cancelBackgroundTasks(options = {}) {
       // Delegated work executes in its bound session; before binding it still
       // belongs to the registering session. Notification ownership is separate.
       if ((clean(task.meta?.sessionId) || task.ownerSessionId) !== executionSessionId) continue;
-    } else if (!taskMatchesScope(task, options, { includeUnattributed: false })) continue;
+    } else if (!taskMatchesScope(task, scope, { includeUnattributed: false })) continue;
     if (TERMINAL_STATUSES.has(task.status)) {
       if (options.notify === false) silenceCancelledNotification(task);
       continue;
@@ -413,6 +449,7 @@ export function completeBackgroundTask(
   if (error != null) task.error = presentErrorText(error, { surface: task.surface });
   if (resultType) task.resultType = resultType;
   if (instruction) task.notificationInstruction = compactText(instruction, 1_000);
+  emitSessionActivityChange(task.ownerSessionId || '');
   if (notify) {
     task.meta = sanitizeTaskMeta(task.meta);
     notifyTaskCompletion(task, instruction);
@@ -522,6 +559,9 @@ export function renderBackgroundTaskNotification(task) {
       : resultTextForTask(task);
   if (task.surface === 'shell') {
     const parsed = parseTaskNotification(result);
+    // The completion envelope already carries the result (exit code,
+    // duration, output or its summary): deliver it as is.
+    if (parsed?.result) return result;
     return renderShellCompletionNotice({
       jobId: task.taskId,
       status: task.status,

package/src/runtime/shared/child-spawn-gate.mjs

@@ -1,4 +1,4 @@
-import { availableParallelism } from 'node:os';
+import { availableParallelism, totalmem } from 'node:os';
 import { createOwnerFairGate } from './owner-fair-gate.mjs';
 import { currentToolExecutionOwner } from './tool-execution-owner.mjs';
 import { positiveInt } from './numbers.mjs';
@@ -9,8 +9,9 @@ import { positiveInt } from './numbers.mjs';
 // singleton semaphore CAN bound the number of concurrent child processes (rg,
 // mixdog-graph, …) across ALL agents/workers in this daemon.
 //
-// Default: Windows search scales conservatively from 1..4 with CPU count;
-// code-graph remains 1. Other platforms are unbounded. Windows measurements
+// Default: Windows search and code-graph-query scale 2..8 with CPU count;
+// code-graph builds 1..4 with cores and memory. Other platforms bound search
+// only. Windows measurements
 // showed both extremes are poor: cap 1 creates multi-session queue latency,
 // while unbounded multithreaded rg amplifies Defender/process-scan and disk
 // contention. Separate lanes isolate short search from long graph builds.
@@ -28,7 +29,8 @@ function resolveDefaultChildSpawnLaneMaxInflight(
   laneName,
   env = process.env,
   platform = process.platform,
-  parallelism = availableParallelism()
+  parallelism = availableParallelism(),
+  memoryBytes = totalmem()
 ) {
   const lane = _laneName(laneName);
   const laneOverride = positiveInt(env[`MIXDOG_CHILD_SPAWN_${_laneEnvKey(lane)}_MAX_INFLIGHT`]);
@@ -45,13 +47,19 @@ function resolveDefaultChildSpawnLaneMaxInflight(
   // Slots are held only across the spawn itself, so a small cap smooths the
   // AV convoy without limiting how many commands run concurrently.
   if (lane === 'process-spawn') return Math.max(2, Math.min(4, Math.floor(cpus / 6) || 2));
-  // One cold graph build saturates memory/disk; allow a second only on big hosts.
-  if (lane === 'code-graph') return cpus >= 12 ? 2 : 1;
-  if (lane !== 'search') return 1;
-  // Multiple rg processes beat one under multi-session load, but each process
-  // is itself threaded and Defender amplifies excess fan-out. Burst stress
-  // measured cap-4 starvation (find p50 15s at 8 concurrent sessions), so
-  // scale with cores and cap at eight: 4→2, 8→3, 12→4, 18→6, 24+→8.
+  // Graph builds (Worker thread + native walk/parse) hold a slot for seconds
+  // and are memory-heavy: one per 4 cores and per 4 GiB, 1..4. Builds of one
+  // repo are already single-flight (build.mjs); distinct repos are independent.
+  if (lane === 'code-graph') {
+    const memGb = Math.floor((Number(memoryBytes) || 0) / 1024 ** 3);
+    return Math.max(1, Math.min(4, Math.floor(cpus / 4), Math.floor(memGb / 4)));
+  }
+  if (lane !== 'search' && lane !== 'code-graph-query') return 1;
+  // Short read-only walks: rg, and the graph binary's `--manifest` that
+  // validates a cached graph. Multiple processes beat one under multi-session
+  // load, but each is itself threaded and Defender amplifies excess fan-out.
+  // Burst stress measured cap-4 starvation (find p50 15s at 8 concurrent
+  // sessions), so scale with cores and cap at eight: 4→2, 8→3, 12→4, 18→6, 24+→8.
   return Math.max(2, Math.min(8, Math.ceil(cpus / 3)));
 }
 
@@ -87,11 +95,13 @@ function _laneSetting(name, suffix, fallback) {
 // ── Lanes ────────────────────────────────────────────────────────────────
 // Independent optional limits and queues:
 //   'search'     — short-lived rg processes.
-//   'code-graph' — long-lived graph workers / native graph binaries. A cold
-//               graph build can hold its slot for seconds-to-minutes; a
-//               single shared lane would let one build
-//               stall every rg spawn behind it. Separate lanes remove that
-//               starvation class while keeping each spawn family bounded.
+//   'code-graph' — long-lived graph build workers. A cold build can hold its
+//               slot for seconds-to-minutes; a single shared lane would let
+//               one build stall every rg spawn behind it. Separate lanes
+//               remove that starvation class while keeping each spawn
+//               family bounded.
+//   'code-graph-query' — the short read-only manifest walk that validates
+//               a cached graph, so queries never wait behind builds.
 function _makeLane(name) {
   const limit = resolveDefaultChildSpawnLaneMaxInflight(name);
   const queueMax = _laneSetting(name, 'MAX_QUEUE', 1024);