mixdog 1.3.1 → 1.3.2

package/src/runtime/agent/orchestrator/session/compact/runner.mjs

@@ -25,6 +25,8 @@ import { stripRuntimeUserContext, withRuntimeUserContext } from '../runtime-user
 import { carryMessageId, messageIdOf } from '../message-ids.mjs';
 import { normalizeIngestRole, shouldExcludeIngestMessage } from '../../../../memory/lib/session-ingest.mjs';
 import { codexWireSendOpts } from '../manager/session-id.mjs';
+import { messageHasReferencableMedia, referenceMessageMedia } from '../../../../attachments/attachment-reference.mjs';
+import { messageAttachmentTokens } from '../attachment-preflight.mjs';
 import { rebaseCompactedEffortConfiguration } from '../../providers/effort-configuration.mjs';
 import {
   COMPACTION_SYSTEM_PROMPT,
@@ -73,8 +75,13 @@ function splitFreshSource(messages) {
     // Budgeting, AI input and rule-only retention use this same projection.
     // Keep current-turn reminders; remove only proven runtime additions from
     // older requests. Unmarked legacy text remains part of the summary budget.
+    // Older requests also carry their attachments by reference from here on:
+    // the file stays on disk under the path the reference names, so the
+    // compacted context keeps the pointer instead of the whole document.
     live: conversation
-      .map((message, index) => (index === latestUserIndex ? message : stripRuntimeUserContext(message)))
+      .map((message, index) =>
+        index === latestUserIndex ? message : referenceMessageMedia(stripRuntimeUserContext(message))
+      )
       .filter((message) => !isSummaryMessage(message)),
     sanitized,
   };
@@ -135,6 +142,9 @@ function summarySendOpts(opts) {
     // Fast mode is opt-in (it needs separate account credits); the summary
     // follows the route/session choice and never enables it on its own.
     fast: opts.fast ?? opts.sendOpts?.fast ?? false,
+    // Usage-ledger source for a foreground session's summary call (a
+    // background session's own sourceType still wins there).
+    requestKind: 'compaction',
     maxOutputTokens: opts.maxOutputTokens || SUMMARY_OUTPUT_TOKENS,
     providerState: undefined,
     onToolCall: undefined,
@@ -548,15 +558,43 @@ function freshContextLayout(source, budgetTokens, opts) {
   return { handoffText, summaryMessage, tail, stableHead, mandatory, mandatoryCost: estimateMessagesTokens(mandatory) };
 }
 
-function assertMandatoryFits(budget, mandatoryCost, summaryMessage, contextWindow) {
-  if (mandatoryCost > budget || (summaryMessage && mandatoryCost === budget)) {
-    const window = Number(contextWindow) > 0 ? ` (currently ${contextWindow} tokens)` : '';
-    throw new Error(
-      `freshContextCompactMessages: mandatory session context/latest instruction exceeds compact budget=${budget} ` +
-        `(mandatory=${mandatoryCost}); the model context window${window} is too small for the tool definitions ` +
-        'and session context. Increase the model context size.'
-    );
-  }
+function mandatoryOverflows(budget, mandatoryCost, summaryMessage) {
+  return mandatoryCost > budget || (summaryMessage && mandatoryCost === budget);
+}
+
+export const LATEST_TURN_EXCEEDS_CONTEXT = 'LATEST_TURN_EXCEEDS_CONTEXT';
+
+// Says what does not fit and what would make it fit. A larger window is only
+// offered when one would actually hold the required size.
+function assertMandatoryFits(budget, mandatoryCost, summaryMessage, contextWindow, latestUser) {
+  if (!mandatoryOverflows(budget, mandatoryCost, summaryMessage)) return;
+  // Fixed sentences with the sizes inline: the desktop re-speaks each one
+  // through its catalog (error-notice-copy / transcript-failure-text).
+  const count = (value) => Number(value).toLocaleString('en-US');
+  const window = Number(contextWindow) > 0 ? `${count(contextWindow)}-token` : 'current';
+  const attachments = messageAttachmentTokens(latestUser);
+  const cause =
+    attachments > 0
+      ? `Its attachments alone are about ${count(attachments)} tokens.`
+      : 'The latest message and protected session context (system rules, tool definitions) are that large.';
+  const error = new Error(
+    `The latest message cannot fit this model (${LATEST_TURN_EXCEEDS_CONTEXT}): it needs about ` +
+      `${count(mandatoryCost)} tokens, but the ${window} window leaves ${count(budget)} for it. ${cause} ` +
+      'Shorten the message or move large pasted text into a file the model can read. ' +
+      `A larger context window helps only if it holds ${count(mandatoryCost)} tokens plus room for the answer.`
+  );
+  error.code = LATEST_TURN_EXCEEDS_CONTEXT;
+  throw error;
+}
+
+// The source with the latest request's attachments sent by reference. Same
+// source when it carries none.
+function withLatestAttachmentsReferenced(source) {
+  const latest = latestActualUserInstructionIndex(source.live);
+  if (latest < 0 || !messageHasReferencableMedia(source.live[latest])) return source;
+  const live = source.live.slice();
+  live[latest] = referenceMessageMedia(live[latest]);
+  return { ...source, live };
 }
 
 function assertHandoffFits(summaryMessage, room) {
@@ -584,14 +622,26 @@ export function freshContextCompactMessages(messages, budgetTokens, opts = {}) {
     });
   }
 
-  const source = splitFreshSource(baseSanitized);
-  const { handoffText, summaryMessage, tail, stableHead, mandatory, mandatoryCost } = freshContextLayout(
-    source,
-    budgetTokens,
-    opts
-  );
-  const budget = freshContextBudget({ targetBudget, budgetTokens, mandatoryCost, summaryMessage, opts });
-  assertMandatoryFits(budget, mandatoryCost, summaryMessage, opts.contextWindow);
+  let source = splitFreshSource(baseSanitized);
+  let layout = freshContextLayout(source, budgetTokens, opts);
+  let budget = freshContextBudget({ targetBudget, budgetTokens, ...layout, opts });
+  // The latest request is mandatory and kept verbatim — except its
+  // attachments: when they are what does not fit (or the provider already
+  // refused this request as too long), they travel by reference instead of
+  // failing the turn, and every later turn, forever.
+  if (
+    opts.referenceLatestAttachments === true ||
+    mandatoryOverflows(budget, layout.mandatoryCost, layout.summaryMessage)
+  ) {
+    const referenced = withLatestAttachmentsReferenced(source);
+    if (referenced !== source) {
+      source = referenced;
+      layout = freshContextLayout(source, budgetTokens, opts);
+      budget = freshContextBudget({ targetBudget, budgetTokens, ...layout, opts });
+    }
+  }
+  const { handoffText, summaryMessage, tail, stableHead, mandatory, mandatoryCost } = layout;
+  assertMandatoryFits(budget, mandatoryCost, summaryMessage, opts.contextWindow, tail.latestUser);
   const handoff = handoffRoomFor(budget, mandatoryCost, opts);
   const summaryContent = String(summaryMessage?.content || '');
   assertHandoffFits(summaryMessage, handoff.room);

package/src/runtime/agent/orchestrator/session/compact/summary-mode.mjs

@@ -0,0 +1,16 @@
+// compaction.summaryMode — which model writes a compaction summary
+// (loop/fresh-context.mjs compactionSummaryPlan):
+//   smart       warm prompt cache: fork the conversation's own cached request;
+//               cold: the Maintainer, else the subscription provider's lighter
+//               model, else the conversation's own model (isolated)
+//   maintainer  the Maintainer (isolated), else the conversation's own model
+//   self        the conversation's own model: fork when warm, isolated when cold
+export const COMPACTION_SUMMARY_MODES = Object.freeze(['smart', 'maintainer', 'self']);
+
+/** The saved mode; the previous release's boolean `useMaintainer:false`
+ *  reads as 'self', true or absent as the 'smart' default. */
+export function normalizeCompactionSummaryMode(compaction) {
+  const mode = compaction?.summaryMode;
+  if (COMPACTION_SUMMARY_MODES.includes(mode)) return mode;
+  return compaction?.useMaintainer === false ? 'self' : 'smart';
+}

package/src/runtime/agent/orchestrator/session/compact/summary-route.mjs

@@ -0,0 +1,87 @@
+// What the compaction summary route choice reads: whether the session's
+// prompt cache is still warm (a fork of its last request would read it), and
+// the lighter model of a subscription provider.
+import { cacheCapabilityForProvider, providerTailCacheLifetimeMs } from '../../agent-runtime/cache-strategy.mjs';
+import { getModelMetadataSync } from '../../../../shared/llm/model-catalog.mjs';
+import {
+  _compareVersion as compareAnthropicVersion,
+  _loadModelCache as loadAnthropicCatalogCache,
+} from '../../providers/anthropic-model-resolve.mjs';
+import { gptVersion } from '../../providers/openai-model-capabilities.mjs';
+import { loadSavedCodexCatalog } from '../../providers/openai-oauth-catalog-store.mjs';
+import { compactionForkRequest } from '../side-question-store.mjs';
+
+// A provider outside the Anthropic/OpenAI lifetimes whose catalog marks prompt
+// caching: the shortest common cache lifetime (Gemini's default TTL).
+const CATALOG_PROMPT_CACHE_LIFETIME_MS = 5 * 60_000;
+// The cache is read when the fork is sent, after the route choice: a request
+// this close to its lifetime counts as cold.
+const WARM_MARGIN_MIN_MS = 30_000;
+const WARM_MARGIN_RATIO = 0.1;
+
+/** How long the cache a saved request wrote or read stays readable, in ms:
+ *  Infinity when it does not expire (openai-oauth), 0 when it is not cached.
+ *  Anthropic: the request's message-tail tier (5m / 1h); OpenAI: the 30m tail
+ *  that holds the conversation (the Lead's 12h breakpoint covers only the
+ *  stable tools/instructions prefix). */
+function requestCacheLifetimeMs(request) {
+  const name = request?.provider?.name;
+  if (name === 'openai-oauth') return Infinity;
+  if (name === 'openai' || cacheCapabilityForProvider(name) === 'explicit-breakpoint') {
+    return providerTailCacheLifetimeMs(name, request.opts?.cacheStrategy) ?? 0;
+  }
+  const info = request.provider.getCachedModelInfo?.(request.model) || getModelMetadataSync(request.model, name);
+  return info?.supportsPromptCaching ? CATALOG_PROMPT_CACHE_LIFETIME_MS : 0;
+}
+
+/** Whether the session's last settled request is still inside the cache
+ *  lifetime it used, with a safety margin. No forkable request = cold. */
+export function compactionCacheWarm(sessionId, now = Date.now()) {
+  const request = compactionForkRequest(sessionId);
+  if (!request) return false;
+  const lifetime = requestCacheLifetimeMs(request);
+  if (lifetime === Infinity) return true;
+  const margin = Math.max(WARM_MARGIN_MIN_MS, lifetime * WARM_MARGIN_RATIO);
+  return now - Number(request.sentAt) < lifetime - margin;
+}
+
+function compareGptVersion(a, b) {
+  const [aMajor, aMinor] = gptVersion(a);
+  const [bMajor, bMinor] = gptVersion(b);
+  // Same version: the undated alias over a dated snapshot.
+  return aMajor - bMajor || aMinor - bMinor || b.length - a.length;
+}
+
+// The lighter family per subscription provider: its newest catalog model.
+// API-key providers bill per token and get no lighter step. `catalog` reads
+// the provider's saved catalog only (disk cache, no auth or network on the
+// compaction path): Anthropic's within its 24h TTL, Codex's stale or not.
+const LIGHTER_FAMILY = Object.freeze({
+  'anthropic-oauth': {
+    catalog: loadAnthropicCatalogCache,
+    matches: (row) => row.family === 'haiku',
+    compare: compareAnthropicVersion,
+  },
+  'openai-oauth': {
+    catalog: loadSavedCodexCatalog,
+    matches: (row, id) => id.includes('-luna') && gptVersion(id) !== null,
+    compare: compareGptVersion,
+  },
+});
+
+/** The newest lighter-family model the saved catalog of `providerName` lists
+ *  for this account, or null (not a subscription provider, no saved catalog,
+ *  none listed). */
+export async function lighterSubscriptionModel(providerName) {
+  const family = LIGHTER_FAMILY[providerName];
+  if (!family) return null;
+  const catalog = await family.catalog();
+  if (!Array.isArray(catalog)) return null;
+  let best = null;
+  for (const row of catalog) {
+    const id = String(row?.id || '');
+    if (!id || !family.matches(row, id)) continue;
+    if (!best || family.compare(id, best) > 0) best = id;
+  }
+  return best;
+}

package/src/runtime/agent/orchestrator/session/compact/summary.mjs

@@ -59,6 +59,8 @@ Rules:
 - Use terse bullets, not prose paragraphs.
 - Preserve exact file paths, commands, error strings, and identifiers when known.
 - Use the same language as the active user thread when it is clear.
+- Record work as Done or In Progress only when a tool call and its result in the history show it (an agent spawn/send result, an edit, a command outcome). An assistant's stated intent with no matching tool call is not started: list it under Next Steps as "announced, not started".
+- Attribute every decision, answer, and version/choice to its source: the user (message or ask_user answer), a named agent's report, or the assistant. Never credit an agent or the assistant with a user's answer.
 - Do not mention the summary process or that context was compacted.`;
 
 // The final user turn of a summary forked from the session's own cached

package/src/runtime/agent/orchestrator/session/compact/text-utils.mjs

@@ -1,6 +1,10 @@
 // Text/token/message helpers and secret redaction for compaction.
 import { createHash } from 'node:crypto';
-import { attachmentTextForPart, isAttachmentReference, isPermanentAttachmentError } from '../../../../attachments/store.mjs';
+import {
+  attachmentTextForPart,
+  isAttachmentReference,
+  isPermanentAttachmentError,
+} from '../../../../attachments/store.mjs';
 import { estimateMessagesTokens } from '../context-utils.mjs';
 import { inlineFileKind } from '../../../../shared/inline-file-kind.mjs';
 

package/src/runtime/agent/orchestrator/session/compact/user-message-kind.mjs

@@ -5,6 +5,7 @@
 import { SUMMARY_PREFIX_ANCHOR } from './summary-anchor.mjs';
 import { isImportedMessage } from '../imported-message.mjs';
 import {
+  CONTROL_MARKER_RE,
   isInternalRuntimeNotificationText,
   isModelVisibleToolCompletionWrapper,
 } from '../../../../shared/tool-execution-contract.mjs';
@@ -132,7 +133,6 @@ export function isActualUserInstructionMessage(message) {
 // isActualUserInstructionMessage deliberately keeps treating "[truncated]" as
 // an instruction (compaction tail selection depends on it), so the real-turn
 // predicate below recognizes it on its own.
-const CONTROL_MARKER_RE = /^\[(?:truncated|request interrupted(?: by user(?: for tool use)?| by process restart)?)\]$/i;
 
 /** Whether a message stands for real human conversation: a compact summary
  *  (it replaced earlier human turns), imported prose, or the user's own

package/src/runtime/agent/orchestrator/session/compaction-archive-capture.mjs

@@ -226,7 +226,7 @@ const recordExists = (dir, sessionId) => existsSync(join(dir, `${sessionId}.json
  *  since `epoch` was captured wins. Any outcome but a rename removes the temp
  *  file. */
 async function publishArchive({ dir, path, sessionId, text, epoch }) {
-  const tmp = join(dir, `.${basename(path)}.${randomBytes(8).toString('hex')}.tmp`);
+  const tmp = join(dir, `${basename(path)}.mixdog-tmp-${randomBytes(4).toString('hex')}`);
   const removeTmp = () => {
     try {
       unlinkSync(tmp);

package/src/runtime/agent/orchestrator/session/context-utils.mjs

@@ -260,24 +260,55 @@ function messageImageAllowance(m) {
   if (!m || typeof m !== 'object') return 0;
   return messageImageDescriptors(m).reduce((sum, descriptor) => sum + imageDescriptorAllowance(descriptor), 0);
 }
-// Inline document (PDF) allowance: Anthropic bills ~1,500-3,000 tokens per
-// page and a typical PDF page is ~50-100KB, so ~bytes/16 with a floor and a
-// cap. The base64 payload itself is excluded from text estimates (see
+// Inline document (PDF) allowance. A native PDF reader turns every page into
+// one image AND sends the text it extracts from that page (the provider PDF
+// docs: each page is billed as an image plus its text, typically
+// 1,500-3,000 text tokens for a dense page). The page image is bounded like
+// any image — the reader downscales it to the vision ceiling — so a page costs
+// at most IMAGE_TOKEN_ALLOWANCE for its picture whatever its file size. A
+// scanned page has no text layer and costs only its picture.
+//
+// The base64 payload itself is excluded from text estimates (see
 // jsonFallbackFromPart), so this allowance is the document's entire cost.
 const FILE_TOKEN_ALLOWANCE_FLOOR = 1_500;
 const FILE_MAX_TOKEN_ALLOWANCE = 300_000;
-// A PDF that records its page count (intake and the read tool do) is priced per
-// page; the size-based figure stays as the floor, so a dense scan still costs
-// at least its bytes. Inline and stored parts carry the same count.
-const FILE_TOKENS_PER_PAGE = 2_500;
+// Extracted PDF text is priced at two characters per token: the low end of
+// the documented per-page range for Latin text, and close to the measured
+// density of Korean/CJK text, so neither is read low.
+const PDF_TEXT_CHARS_PER_TOKEN = 2;
+// A PDF that records its page count but not its text layer (older parts, an
+// inline part from a path that did not measure it) keeps the documented
+// mid-range per-page figure.
+const FILE_TOKENS_PER_PAGE_UNMEASURED = 2_500;
 // A PDF that lowers to text costs at most its extraction budget (~4 bytes/token).
 const PDF_TEXT_MAX_TOKENS = Math.ceil(PDF_TEXT_MAX_BYTES / 4);
+// Without a page count only the file size is known: ~bytes/16 (a typical page
+// is 50-100KB) with a floor and a cap. Never used once pages are known — a
+// scan's bytes are its image data, which the reader downscales, so bytes/16
+// priced a 5 MB, 37-page scan at ~330k tokens instead of ~58k.
 function fileDescriptorAllowance(descriptor, nativePdf = true) {
-  const bySize = Math.ceil((descriptor.sizeBytes || 0) / 16);
-  const byPage = (descriptor.pageCount || 0) * FILE_TOKENS_PER_PAGE;
-  const native = Math.min(FILE_MAX_TOKEN_ALLOWANCE, Math.max(FILE_TOKEN_ALLOWANCE_FLOOR, bySize, byPage));
+  const pages = descriptor.pageCount || 0;
+  let native;
+  if (pages > 0 && Number.isFinite(descriptor.textChars)) {
+    native = pages * IMAGE_TOKEN_ALLOWANCE + Math.ceil(descriptor.textChars / PDF_TEXT_CHARS_PER_TOKEN);
+  } else if (pages > 0) {
+    native = pages * FILE_TOKENS_PER_PAGE_UNMEASURED;
+  } else {
+    native = Math.max(FILE_TOKEN_ALLOWANCE_FLOOR, Math.ceil((descriptor.sizeBytes || 0) / 16));
+  }
+  native = Math.min(FILE_MAX_TOKEN_ALLOWANCE, native);
   return nativePdf ? native : Math.min(native, PDF_TEXT_MAX_TOKENS);
 }
+
+/** The tokens one PDF part costs inline (native reader unless `nativePdf` is false). */
+export function pdfPartAllowance(part, { nativePdf = true } = {}) {
+  return contentFileDescriptors([part]).reduce((sum, d) => sum + fileDescriptorAllowance(d, nativePdf), 0);
+}
+
+/** The tokens one image part costs inline. */
+export function imagePartAllowance(part) {
+  return contentImageDescriptors([part]).reduce((sum, d) => sum + imageDescriptorAllowance(d), 0);
+}
 /**
  * How many tokens the native-PDF meter overstates `messages` for a provider
  * that takes PDFs as text (nativePdf === false); subtract it from the

package/src/runtime/agent/orchestrator/session/human-gate/delegation.mjs

@@ -0,0 +1,230 @@
+// session/human-gate/delegation.mjs
+// Who a delegated session works for, recorded when it is created and re-bound
+// only when another session sends it work (rebindDelegation): a sub-agent (any
+// depth) and a task session a bot created carry `delegation` on their session
+// record —
+//   { rootSessionId, rootAgentId, via, run?, path }
+// `rootSessionId` is the top-level conversation (a bot's home chat, a room
+// member session, a coding Lead's session); `rootAgentId` the bot or Mixy it
+// acts for ('' under a coding Lead); `via` how that root was acting when the
+// work started: 'home' (the bot's own attended chat), 'room', 'run' (a
+// schedule/webhook turn; `run` = { kind, name }) or 'coding'; `path` the steps
+// from the root down ({ kind: 'task' } | { kind: 'agent', agent }).
+// It is copied from the parent's record (or bound from the parent itself when
+// the parent is top-level) by the host at creation — never from tool input —
+// so no parent walk happens at gate time. It follows the session that drives
+// the work: when a session sends an existing worker (or task session) a new
+// request, the record is re-bound to what that sender is doing now, so work an
+// unattended run started asks when the attended chat later reuses it, and the
+// reverse. A background wake of the worker is no new request and keeps it. A
+// record from before this field existed is
+// backfilled once, from its parent by the same rules (backfillOf), and kept on
+// the in-memory record, which its next save persists. A session that has a
+// parent link but no valid or derivable root is UNRESOLVED: the gate fails
+// closed on it. `via: 'unknown'` — a legacy task session that names its bot
+// but not where it was created: acts as that bot, never remembers.
+import { agentHomeSessionId, agentIdOfHomeSession } from '../agent-home.mjs';
+import { roomMemberOfSession } from '../agent-room.mjs';
+import { loadSession } from '../store/load-session.mjs';
+import { _liveSessions } from '../store/live-state.mjs';
+import { saveSessionAsync } from '../store/save-worker.mjs';
+import { isTurnInFlight, runtimeState } from '../manager/runtime-state.mjs';
+import { unattendedApprovalPort } from './unattended-port.mjs';
+
+const VIA = new Set(['home', 'room', 'run', 'coding', 'unknown']);
+const AGENT_ID = /^[A-Za-z0-9_-]+$/;
+const MAX_PATH = 32;
+const clean = (value) => (typeof value === 'string' ? value.trim() : '');
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const agentOwned = (record) =>
+  clean(record?.owner).toLowerCase() === 'agent' || clean(record?.visibility).toLowerCase() === 'agent-only';
+
+/** The session that started `record` (its spawn parent, or the chat that
+ *  created a task session), or '' for a top-level session. */
+function parentOf(record) {
+  if (agentOwned(record)) return clean(record.parentSessionId) || clean(record.ownerSessionId);
+  return clean(record?.taskOrigin?.sessionId);
+}
+
+/** The step a new session adds to its parent's path. */
+function stepOf(record) {
+  return agentOwned(record) ? { kind: 'agent', agent: clean(record.agent) } : { kind: 'task' };
+}
+
+function validDelegation(value) {
+  if (!isRecord(value) || !clean(value.rootSessionId) || !VIA.has(value.via)) return null;
+  if (!Array.isArray(value.path) || value.path.length === 0 || value.path.length > MAX_PATH) return null;
+  if (value.via === 'run' && !isRecord(value.run)) return null;
+  return value;
+}
+
+/** A failed rebind leaves `{ unresolved: true }` instead of a delegation: an
+ *  explicit "no root", so the legacy backfill cannot derive one again from a
+ *  parent that still holds a run. */
+const UNRESOLVED = Object.freeze({ unresolved: true });
+const isUnresolvedMark = (value) => isRecord(value) && value.unresolved === true;
+
+/** The recorded delegation of `record`, else its legacy backfill; null when
+ *  it has none or was explicitly left unresolved. */
+function delegationOfRecord(id, record, depth) {
+  if (isUnresolvedMark(record.delegation)) return null;
+  return validDelegation(record.delegation) || backfillOf(id, record, depth);
+}
+
+function loadRecord(sessionId) {
+  try {
+    return loadSession(sessionId);
+  } catch {
+    return null;
+  }
+}
+
+/** How a top-level session `sessionId` is acting right now (no record needed
+ *  for a home or room member id, which name their agent themselves). */
+function bindingOf(sessionId, record, { legacy = false } = {}) {
+  // A legacy record is classified from what was recorded, never from what the
+  // parent is doing now (a run going or ended since says nothing about it).
+  const run = legacy ? null : unattendedApprovalPort()?.runOf?.(sessionId);
+  if (run && run.kind !== 'room') {
+    return { rootAgentId: clean(run.agentId), via: 'run', run: { kind: run.kind, name: String(run.name || '') } };
+  }
+  const member = roomMemberOfSession(sessionId);
+  if (member) return { rootAgentId: member.agentId, via: 'room' };
+  const home = agentIdOfHomeSession(sessionId);
+  if (home) return { rootAgentId: home, via: 'home' };
+  if (!record || agentOwned(record)) return null;
+  // A Lead with host-set bot provenance (session-options taskOriginSuffix) is
+  // a bot's task session, never coding work: its root is that bot's chat.
+  const source = sourceTaskOf(record);
+  if (source === false) return null;
+  if (source) {
+    const task = { rootSessionId: agentHomeSessionId(source.bot), rootAgentId: source.bot, task: true };
+    if (source.from === 'home') return { ...task, via: 'home' };
+    if (source.from === 'run') return { ...task, via: 'run', run: { kind: 'schedule', name: '' } };
+    if (source.from === undefined) return { ...task, via: 'unknown' };
+    return null; // a room (which one is not recorded) or anything else: ambiguous
+  }
+  return { rootAgentId: '', via: 'coding' };
+}
+
+/** A Lead's host-set bot provenance `agent:<bot>[@from]`: `{ bot, from }`,
+ *  null when it has none, false when it is malformed. */
+function sourceTaskOf(record) {
+  const source = clean(record?.sourceName);
+  if (agentOwned(record) || clean(record?.sourceType) !== 'lead' || !source.startsWith('agent:')) return null;
+  const [bot, from, ...rest] = source.slice(6).split('@');
+  return AGENT_ID.test(bot) && !rest.length ? { bot, from } : false;
+}
+
+/** The root of a top-level `parent` for a child taking `step`. */
+function rootFrom(parent, record, step, options) {
+  const binding = bindingOf(parent, record, options);
+  if (!binding) return null;
+  const { task, ...root } = binding;
+  return { rootSessionId: parent, ...root, path: task ? [{ kind: 'task' }, step] : [step] };
+}
+
+/** The delegation a legacy `record` (id `id`, a parent link, none recorded)
+ *  is given, derived now from what was recorded — its own host-set `@run`
+ *  provenance, else its parent's record, which must exist — and kept on the
+ *  live record; null when it cannot be derived. Never `via: 'home'`: whether
+ *  an old record was started by the attended chat (or by a run that has
+ *  ended since) is not recorded, so home ancestry becomes 'unknown' — that
+ *  bot, never remembered. Only a session created with its `delegation` can be
+ *  'home'. */
+function backfillOf(id, record, depth = 0) {
+  const parent = parentOf(record);
+  if (!parent || parent === id || depth >= MAX_PATH) return null;
+  const own = sourceTaskOf(record);
+  let delegation = null;
+  if (own && own.from === 'run') {
+    // A run's task session stays the run's, whatever its origin chat is doing now.
+    delegation = {
+      rootSessionId: agentHomeSessionId(own.bot),
+      rootAgentId: own.bot,
+      via: 'run',
+      run: { kind: 'schedule', name: '' },
+      path: [{ kind: 'task' }],
+    };
+  } else {
+    const parentRecord = loadRecord(parent);
+    if (!parentRecord) return null;
+    const step = stepOf(record);
+    if (parentOf(parentRecord)) {
+      const inherited = delegationOfRecord(parent, parentRecord, depth + 1);
+      if (!inherited || inherited.path.length >= MAX_PATH) return null;
+      delegation = { ...inherited, path: [...inherited.path, step] };
+    } else {
+      delegation = rootFrom(parent, parentRecord, step, { legacy: true });
+    }
+    if (delegation?.via === 'home') delegation = { ...delegation, via: 'unknown' };
+  }
+  if (delegation && _liveSessions.get(id) === record) record.delegation = delegation;
+  return delegation;
+}
+
+/**
+ * The `delegation` to record on a session being created with `opts` (its
+ * owner/visibility, parentSessionId/ownerSessionId, taskOrigin and agent), or
+ * null: none for a top-level session, none for one whose parent's root cannot
+ * be established (the record then stays unresolved and the gate fails closed).
+ */
+export function delegationForNewSession(opts = {}) {
+  const parent = parentOf(opts);
+  if (!parent || parent === clean(opts.id)) return null;
+  return delegationUnder(parent, stepOf(opts));
+}
+
+/** The delegation of a session taking `step` under the session `parent`. */
+function delegationUnder(parent, step) {
+  const record = loadRecord(parent);
+  if (record && parentOf(record)) {
+    // The parent is delegated itself: its recorded root, one step deeper.
+    const inherited = delegationOfRecord(parent, record);
+    if (!inherited || inherited.path.length >= MAX_PATH) return null;
+    return { ...inherited, path: [...inherited.path, step] };
+  }
+  return rootFrom(parent, record, step);
+}
+
+/**
+ * Session `callerSessionId` sends the delegated session `sessionId` new work
+ * (`agent send`, a spawn of its tag, a task-session send): from now on it
+ * acts as that caller does — the delegation it would have been created with
+ * under the caller — and the record is saved, so a restart keeps it. A worker
+ * a run started is attended when the chat sends it work, and the other way
+ * round; only the requests of the session that sends it count, never the
+ * session that created it. A turn already running keeps its attended status
+ * against a run (the run's request queues behind it and asks): it is never
+ * loosened mid-turn. Resolves true when the record changed; false when
+ * nothing applies (no record, not delegated, no or the same caller, the same
+ * delegation) or the running turn kept its status. A caller whose root cannot
+ * be established leaves the record without one, which the gate fails closed on.
+ */
+export async function rebindDelegation(sessionId, callerSessionId) {
+  const id = clean(sessionId);
+  const caller = clean(callerSessionId);
+  const record = id ? loadRecord(id) : null;
+  if (!record || record.closed === true || !caller || caller === id || !parentOf(record)) return false;
+  const current = validDelegation(record.delegation);
+  const next = delegationUnder(caller, stepOf(record));
+  if (next ? JSON.stringify(current) === JSON.stringify(next) : isUnresolvedMark(record.delegation)) return false;
+  if (next?.via === 'run' && current?.via !== 'run' && isTurnInFlight(runtimeState.get(id))) return false;
+  record.delegation = next || { ...UNRESOLVED };
+  await saveSessionAsync(record, { expectedGeneration: record.generation });
+  return true;
+}
+
+/** `{ state: 'top' }` for a top-level session (or one with no record),
+ *  `{ state: 'resolved', ...delegation }` for a delegated one, `{ state:
+ *  'unresolved' }` for one with a parent link and no valid recorded root. */
+export function delegationOf(sessionId) {
+  const id = clean(sessionId);
+  const record = id ? loadRecord(id) : null;
+  if (!record) return { state: 'top' };
+  const parent = parentOf(record);
+  if (!parent) return { state: 'top' };
+  const delegation = parent === id ? null : delegationOfRecord(id, record);
+  return delegation ? { state: 'resolved', ...delegation } : { state: 'unresolved' };
+}