openmausbot 0.1.85 → 0.1.87

package/dist-server/server/decision-log.js

@@ -15,44 +15,88 @@
 // credentials included), and fire-and-forget — an audit log must never
 // take down the decision it is auditing.
 //
+// Layout and retention follow the usage ledger: one file per UTC month under
+// <data>/decisions/YYYY-MM.ndjson, and a month file is deleted only once the
+// whole month is older than the retention window (default 180 days, config
+// `decisions.retentionDays` or OMB_DECISION_RETENTION_DAYS), so at least that
+// much history is always kept. Older servers wrote one decisions.ndjson that
+// rotated to .1 at 4 MB; both are still read, never written, and removed by
+// the same window once their last row is older than it.
+//
 // Deliberately NOT covered: ask_bot peer-approval cards. They never cross
 // the runtime bus (peer-approval.ts appends its cards straight to the
 // store), so wiring them here would mean a second, parallel tap — a
 // separate change if it earns its keep.
-import { readFileSync } from "node:fs";
-import { appendFile, rename, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { readdirSync, readFileSync } from "node:fs";
+import { appendFile, mkdir, readdir, stat, unlink } from "node:fs/promises";
+import { basename, join } from "node:path";
 import { redactSecrets } from "./redact.js";
-const FILE_NAME = "decisions.ndjson";
-// Rotation is logrotate at its simplest: when the live file crosses the cap
-// it becomes `.1` (clobbering the previous `.1`) and a fresh file starts.
-// Total disk is bounded at ~2× the cap; at a few hundred bytes per row that
-// is years of human-scale approvals, and anything fancier — dated segments,
-// compression — is more machinery than an audit trail this size warrants.
-const MAX_BYTES = 4 * 1024 * 1024;
+import { csvCell } from "./usage-ledger.js";
+const DIR = "decisions";
+const LEGACY_FILE = "decisions.ndjson";
+const MONTH_FILE = /^(\d{4})-(\d{2})\.ndjson$/;
+const DAY_MS = 24 * 60 * 60_000;
+const PRUNE_EVERY_MS = 60 * 60_000;
+export const DEFAULT_DECISION_RETENTION_DAYS = 180;
+export const MAX_DECISION_RETENTION_DAYS = 3650;
 const writeQueues = new Map();
-async function writeDecision(dataDir, row, maxBytes) {
-    const file = join(dataDir, FILE_NAME);
-    try {
-        if ((await stat(file)).size >= maxBytes)
-            await rename(file, `${file}.1`);
-    }
-    catch {
-        /* no live file yet — nothing to rotate */
+const lastPrune = new Map();
+let retentionDays = () => DEFAULT_DECISION_RETENTION_DAYS;
+/** The server binds its configured window once; see decisionRetentionDays. */
+export function bindDecisionRetention(provider) {
+    retentionDays = provider;
+}
+/** The window in force now. The admin activity log (admin-activity.ts)
+ * keeps its months for the same time, so one setting covers both. */
+export function boundRetentionDays() {
+    return retentionDays();
+}
+/** The retention window in days: OMB_DECISION_RETENTION_DAYS when it is a
+ * whole number in range, else the configured value, else 180. */
+export function decisionRetentionDays(configured, env = process.env) {
+    const fromEnv = env.OMB_DECISION_RETENTION_DAYS?.trim();
+    const parsed = fromEnv ? Number(fromEnv) : NaN;
+    if (Number.isInteger(parsed) && parsed >= 1 && parsed <= MAX_DECISION_RETENTION_DAYS)
+        return parsed;
+    if (typeof configured === "number" && Number.isInteger(configured) && configured >= 1 && configured <= MAX_DECISION_RETENTION_DAYS)
+        return configured;
+    return DEFAULT_DECISION_RETENTION_DAYS;
+}
+const actorScope = new AsyncLocalStorage();
+/** Run `work` as a person's card answer: every `source: "user"` row it
+ * writes names `actor`, without each resolver having to thread it through. */
+export function withDecisionActor(actor, work) {
+    return actorScope.run(actor, work);
+}
+function monthKey(at) {
+    return `${at.getUTCFullYear()}-${String(at.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+export function decisionFileFor(dataDir, at) {
+    return join(dataDir, DIR, `${monthKey(at)}.ndjson`);
+}
+async function writeDecision(dataDir, record) {
+    const at = new Date(record.at);
+    await mkdir(join(dataDir, DIR), { recursive: true, mode: 0o700 });
+    await appendFile(decisionFileFor(dataDir, at), JSON.stringify(record) + "\n", { mode: 0o600 });
+    if (at.getTime() - (lastPrune.get(dataDir) ?? 0) >= PRUNE_EVERY_MS) {
+        lastPrune.set(dataDir, at.getTime());
+        await pruneDecisions(dataDir, retentionDays(), at);
     }
-    const record = redactSecrets({ at: new Date().toISOString(), ...row });
-    await appendFile(file, JSON.stringify(record) + "\n", { mode: 0o600 });
 }
 /** Append one decision row. Fire-and-forget, mirroring the event bus tee:
  * the fold that calls this is delivering approvals and cards, and a full
  * disk must not turn into denied tools. */
-export function appendDecision(dataDir, row, opts) {
+export function appendDecision(dataDir, row) {
+    const actor = row.actor ?? (row.source === "user" ? actorScope.getStore() : undefined);
+    // Redact now, not when the queue drains: the row is what was true at the
+    // moment of the decision.
+    const record = redactSecrets({ at: new Date().toISOString(), ...row, ...(actor ? { actor } : {}) });
     const previous = writeQueues.get(dataDir) ?? Promise.resolve();
-    // Serialize stat → optional rotate → append for each directory. Without
-    // this queue two simultaneous approvals can both rotate, overwrite .1,
-    // or append out of decision order.
+    // Serialize appends (and the occasional prune) per directory, so two
+    // simultaneous approvals keep their decision order.
     const queued = previous
-        .then(() => writeDecision(dataDir, row, opts?.maxBytes ?? MAX_BYTES))
+        .then(() => writeDecision(dataDir, record))
         .catch(() => {
         /* logging must never take down the fold */
     });
@@ -67,40 +111,157 @@ export function appendDecision(dataDir, row, opts) {
 export async function flushDecisionLog(dataDir) {
     await writeQueues.get(dataDir);
 }
+/** Delete what the window no longer covers: a month file once the first
+ * instant after its month is at or before `now - days`, a legacy file once
+ * its last write is. Returns the names removed. Never throws. */
+export async function pruneDecisions(dataDir, days, now = new Date()) {
+    const cutoff = now.getTime() - days * DAY_MS;
+    const removed = await pruneMonthFiles(join(dataDir, DIR), days, now);
+    for (const name of [`${LEGACY_FILE}.1`, LEGACY_FILE]) {
+        try {
+            if ((await stat(join(dataDir, name))).mtimeMs > cutoff)
+                continue;
+            await unlink(join(dataDir, name));
+            removed.push(name);
+        }
+        catch {
+            /* absent */
+        }
+    }
+    return removed;
+}
+/** Delete the `YYYY-MM.ndjson` files in `dir` whose whole month is at or
+ * before `now - days`. Returns the names removed. Never throws. Shared with
+ * the admin activity log. */
+export async function pruneMonthFiles(dir, days, now = new Date()) {
+    const cutoff = now.getTime() - days * DAY_MS;
+    const removed = [];
+    let names = [];
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        /* nothing written in the new layout yet */
+    }
+    for (const name of names) {
+        const match = MONTH_FILE.exec(name);
+        if (!match || Date.UTC(Number(match[1]), Number(match[2]), 1) > cutoff)
+            continue;
+        try {
+            await unlink(join(dir, name));
+            removed.push(name);
+        }
+        catch {
+            /* already gone, or not ours to remove */
+        }
+    }
+    return removed;
+}
 const isDecisionRow = (value) => typeof value === "object" &&
     value !== null &&
     typeof value.at === "string" &&
     typeof value.threadId === "string" &&
     typeof value.decision === "string" &&
     typeof value.source === "string";
-/** The newest `limit` rows, oldest first — the same order the inspector
- * uses for thread events. Reads `.1` before the live file so a request
- * right after a rotation still sees history instead of a nearly empty
- * log; whole-file reads are fine here because rotation caps both files,
- * unlike the unbounded per-thread event logs that need a tail walk. */
-export function readDecisions(dataDir, limit) {
-    const file = join(dataDir, FILE_NAME);
+function readRows(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
     const rows = [];
-    for (const path of [`${file}.1`, file]) {
-        let text;
+    for (const line of text.split("\n")) {
+        if (!line)
+            continue;
         try {
-            text = readFileSync(path, "utf8");
+            const value = JSON.parse(line);
+            if (isDecisionRow(value))
+                rows.push(value);
         }
         catch {
-            continue;
+            /* a line torn mid-write — skip the fragment, keep the rest */
         }
-        for (const line of text.split("\n")) {
-            if (!line)
-                continue;
-            try {
-                const value = JSON.parse(line);
-                if (isDecisionRow(value))
-                    rows.push(value);
-            }
-            catch {
-                /* a line torn mid-write — skip the fragment, keep the rest */
-            }
+    }
+    return rows;
+}
+/** Every file that may hold rows, oldest first: the legacy pair (which only
+ * ever holds rows older than any month file), then the months in order. */
+function sources(dataDir) {
+    let months = [];
+    try {
+        months = readdirSync(join(dataDir, DIR)).filter((name) => MONTH_FILE.test(name)).sort();
+    }
+    catch {
+        /* no month files yet */
+    }
+    return [join(dataDir, `${LEGACY_FILE}.1`), join(dataDir, LEGACY_FILE), ...months.map((name) => join(dataDir, DIR, name))];
+}
+/** The newest `limit` rows, oldest first — the same order the inspector
+ * uses for thread events. Reads month files newest first and stops once it
+ * has enough, so a long history costs no more than the page asked for. */
+export function readDecisions(dataDir, limit) {
+    const files = sources(dataDir);
+    const chunks = [];
+    let count = 0;
+    for (let index = files.length - 1; index >= 0 && count < limit; index -= 1) {
+        const rows = readRows(files[index]);
+        chunks.unshift(rows);
+        count += rows.length;
+    }
+    return chunks.flat().slice(-limit);
+}
+/** Every row whose time falls inside the range, oldest first. */
+export function readDecisionRange(dataDir, range) {
+    const from = range.from.getTime();
+    const to = range.to.getTime();
+    const first = monthKey(range.from);
+    const last = monthKey(range.to);
+    const rows = [];
+    for (const file of sources(dataDir)) {
+        // Month files outside the range are skipped unread; legacy files have no month.
+        const month = MONTH_FILE.exec(basename(file));
+        if (month && (`${month[1]}-${month[2]}` < first || `${month[1]}-${month[2]}` > last))
+            continue;
+        for (const row of readRows(file)) {
+            const at = Date.parse(row.at);
+            if (at >= from && at <= to)
+                rows.push(row);
         }
     }
-    return rows.slice(-limit);
+    return rows;
+}
+export function actorLabel(actor) {
+    if (!actor)
+        return "";
+    if (actor.kind === "loopback")
+        return "This computer";
+    if (actor.kind === "worker")
+        return "Local service";
+    return actor.email ?? actor.label;
+}
+/** One line per decision, spreadsheet-ready. Cells go through the usage
+ * CSV's formula neutralising, and every row through redaction again, so an
+ * export never carries more than the log itself may. */
+export function decisionsCsv(rows) {
+    const header = ["time", "decision", "source", "bot", "tool", "summary", "rule", "unattended", "answered_by", "thread", "request"];
+    const lines = [header.join(",")];
+    for (const raw of rows) {
+        const row = redactSecrets(raw);
+        lines.push([
+            row.at,
+            row.decision,
+            row.source,
+            row.botName || row.botId || "",
+            row.tool ?? "",
+            row.summary ?? "",
+            row.rule ?? "",
+            row.unattended ? "yes" : "",
+            actorLabel(row.actor),
+            row.threadId,
+            row.requestId ?? "",
+        ].map(csvCell).join(","));
+    }
+    return lines.join("\n") + "\n";
 }

package/dist-server/server/default-model-selection.js

@@ -1,10 +1,14 @@
+const claudeFirst = (instances) => instances.find((instance) => instance.driverKind === "claudeAgent") ?? instances[0];
 /** A saved choice is intentional: an unavailable provider or removed model
  * sends new bots to setup instead of silently changing their provider. */
-export function selectDefaultModelSelection(instances, preferred) {
+export function selectDefaultModelSelection(instances, preferred, context = {}) {
     if (preferred) {
         const instance = instances.find((candidate) => candidate.instanceId === preferred.instanceId);
         if (instance?.snapshot.state !== "available" ||
             instance.snapshot.authenticated === false ||
+            // An organisation that disallows the saved engine makes it unusable,
+            // exactly like an unavailable one: setup, never another provider.
+            context.refusal?.(instance) !== undefined ||
             (preferred.variant !== undefined && !instance.capabilities?.modelVariants) ||
             !(instance.models.default === preferred.model || instance.models.options.some((model) => model.id === preferred.model))) {
             return { instanceId: "", model: "" };
@@ -16,7 +20,29 @@ export function selectDefaultModelSelection(instances, preferred) {
             delete selection.effort;
         return selection;
     }
-    const available = instances.filter((instance) => instance.snapshot.state === "available");
-    const pick = available.find((instance) => instance.driverKind === "claudeAgent") ?? available[0];
+    // The organisation's policy is inert (no refusal) unless this desktop is enrolled.
+    const available = instances.filter((instance) => instance.snapshot.state === "available" && context.refusal?.(instance) === undefined);
+    const company = context.company;
+    let pick;
+    if (company && instances.some((instance) => company(instance.instanceId))) {
+        // Enrolled: an installed but signed-out personal Claude would send every
+        // new bot to setup although a Company model can run. Prefer instances that
+        // can run a turn now; a working personal engine still wins, so billing
+        // stays the person's explicit choice.
+        const ready = available.filter((instance) => instance.access === "custom" || instance.snapshot.authenticated !== false);
+        pick = claudeFirst(ready.filter((instance) => !company(instance.instanceId))) ?? claudeFirst(ready) ?? claudeFirst(available);
+    }
+    else {
+        pick = claudeFirst(available);
+    }
     return { instanceId: pick?.instanceId ?? "", model: pick?.models.default ?? "" };
 }
+/** Complete a new bot's selection with the workspace's new-bot effort. An
+ * explicit effort or model variant is the caller's choice and wins; an engine
+ * that does not offer the level keeps sending none rather than failing turn 1. */
+export function withNewBotEffort(selection, effort, offered) {
+    if (!effort || selection.effort !== undefined || selection.variant !== undefined || !offered?.includes(effort)) {
+        return selection;
+    }
+    return { ...selection, effort };
+}

package/dist-server/server/delegations.js

@@ -16,7 +16,7 @@ import { writeFileAtomic } from "./atomic.js";
 import { getOrCreateChannel, mirrorExchange } from "./comms-visibility.js";
 import { DATA_DIR } from "./config.js";
 import { newId } from "./contracts.js";
-import { requestPeerApproval } from "./peer-approval.js";
+import { peerApprovalFailure, requestPeerApproval } from "./peer-approval.js";
 import { canAccessTeam, peerAllowed } from "./peer-roster.js";
 /** Per source-thread queue. Persisted to delegations.json on every change
  * and reloaded at boot: a handoff queued right before a restart runs after
@@ -40,6 +40,13 @@ const RESULT_MAX_CHARS = 4_000;
  * to expire. This is not an uptime clock: sleep within a running process
  * still counts, and a non-expired restored window keeps its deadline. */
 export const DELEGATION_TTL_MS = 24 * 60 * 60 * 1000;
+/** How long a handoff may wait on a target that never goes idle. The 24-hour
+ * window above bounds the rare case; the busy hold is the common one — a peer
+ * stays busy for a whole day and the delegating bot hears nothing back. Past
+ * this cap a still-blocked handoff expires with its own wording. Env-tunable
+ * so tests (and patient teams) can shrink or stretch it. */
+const configuredBusyHoldMaxMs = Number(process.env.OMB_DELEGATION_BUSY_HOLD_MAX_MS);
+export const DELEGATION_BUSY_HOLD_MAX_MS = Math.max(1_000, Number.isFinite(configuredBusyHoldMaxMs) && process.env.OMB_DELEGATION_BUSY_HOLD_MAX_MS !== "" ? configuredBusyHoldMaxMs : 2 * 60 * 60 * 1000);
 let receipts = [];
 function saveReceipts() {
     try {
@@ -63,6 +70,10 @@ export function recordDelegationReceipt(receipt) {
     };
     if (receipt.result !== undefined)
         bounded.result = receipt.result.slice(0, RESULT_MAX_CHARS);
+    if (receipt.approvalOutcome !== undefined) {
+        bounded.approvalOutcome = receipt.approvalOutcome;
+        bounded.approvalSource = peerApprovalFailure(receipt.approvalOutcome).approvalSource;
+    }
     receipts = [bounded, ...receipts.filter((existing) => existing.id !== bounded.id)]
         .filter((existing) => now - existing.finishedAt <= RECEIPT_MAX_AGE_MS)
         .slice(0, MAX_RECEIPTS);
@@ -90,9 +101,9 @@ export function threadsWaitingOn(toBotId) {
 }
 /** Mark a target's observed busy period as finished and return the source
  * threads that should be retried. A handoff waits until the target is free,
- * bounded only by the 24-hour expiry — this just clears the "parked on a
- * busy period" marker so the next drain re-evaluates it, rather than
- * counting or limiting retries.
+ * bounded by the busy-hold cap and the 24-hour expiry — this just clears the
+ * "parked on a busy period" marker so the next drain re-evaluates it, rather
+ * than counting or limiting retries.
  * `only` narrows the release: a bot that is still busy in one thread has
  * nevertheless freed a slot for the fresh-thread handoffs waiting on it,
  * while its active-thread handoffs go on waiting for it to go idle. */
@@ -104,6 +115,7 @@ export function releaseDelegationsWaitingOn(toBotId, only) {
             if (item.toBotId !== toBotId || item.waitingOnBusy !== true || (only && !only(item)))
                 continue;
             delete item.waitingOnBusy;
+            delete item.busySince;
             any = true;
         }
         if (any)
@@ -164,8 +176,14 @@ export function _loadPending() {
                 };
                 if (item.approvalAlreadyGranted === true)
                     loaded.approvalAlreadyGranted = true;
-                if (item.waitingOnBusy === true)
+                if (item.waitingOnBusy === true) {
                     loaded.waitingOnBusy = true;
+                    const currentHold = Number.isFinite(item.busySince) && item.busySince <= now &&
+                        now - item.busySince < DELEGATION_BUSY_HOLD_MAX_MS;
+                    loaded.busySince = currentHold ? item.busySince : now;
+                    if (!currentHold)
+                        backfilled = true;
+                }
                 if (item.waitAnnounced === true || legacyAlreadyAnnounced)
                     loaded.waitAnnounced = true;
                 if (typeof item.originatingGroupId === "string" && item.originatingGroupId) {
@@ -212,6 +230,10 @@ export function _loadPending() {
                 const receipt = { id, sourceThreadId, toBotId, toBotName, status, finishedAt: finishedAt };
                 if (typeof result === "string")
                     receipt.result = result;
+                if (candidate.approvalOutcome === "deny" || candidate.approvalOutcome === "expired" || candidate.approvalOutcome === "cancelled") {
+                    receipt.approvalOutcome = candidate.approvalOutcome;
+                    receipt.approvalSource = peerApprovalFailure(candidate.approvalOutcome).approvalSource;
+                }
                 loaded.push(receipt);
             }
             receipts = loaded.slice(0, MAX_RECEIPTS);
@@ -405,41 +427,61 @@ function acknowledgeDelegation(threadId, itemId) {
     savePending();
 }
 const isExpired = (item, now) => now - item.queuedAt >= DELEGATION_TTL_MS;
+/** Past the busy-hold cap — the tighter bound that fires while its target is
+ * still busy, long before the 24-hour window. */
+const busyHoldExpired = (item, now) => item.busySince !== undefined && now - item.busySince >= DELEGATION_BUSY_HOLD_MAX_MS;
+/** The busy-hold cap in chip-ready words ("2 hours", "90 minutes"). */
+export function busyHoldCapText(maxMs = DELEGATION_BUSY_HOLD_MAX_MS) {
+    const minutes = Math.max(1, Math.round(maxMs / 60_000));
+    const amount = minutes % 60 === 0 ? minutes / 60 : minutes;
+    const unit = minutes % 60 === 0 ? "hour" : "minute";
+    return `${amount} ${unit}${amount === 1 ? "" : "s"}`;
+}
 /** Record an expired handoff. The chip goes into the source thread only
  * while it still belongs to the bot that owns the handoff — a deleted
  * conversation gets the receipt and nothing else. */
 function expireDelegation(bus, sourceThreadId, item, ownerId) {
-    const name = bus.store.bot(item.toBotId)?.name ?? item.toBotId;
+    const target = bus.store.bot(item.toBotId);
+    const name = target?.name ?? item.toBotId;
+    // A busy hold has its own words so a two-hour busy wait is never reported
+    // as a 24-hour one; every other expiry keeps the TTL wording.
+    const now = Date.now();
+    const busyHold = Boolean(target) && busyHoldExpired(item, now) && !isExpired(item, now);
     recordDelegationReceipt({
         id: item.id,
         sourceThreadId,
         toBotId: item.toBotId,
         toBotName: name,
         status: "expired",
-        result: `@${name} was not free to take this for 24 hours`,
+        result: busyHold ? `@${name} was still busy after ${busyHoldCapText()}` : `@${name} was not free to take this for 24 hours`,
     });
     if (!sourceThreadBelongsToBot(bus.store, ownerId, sourceThreadId))
         return;
     bus.store.appendMessage(sourceThreadId, {
         role: "bot",
         kind: "activity",
-        tool: { name: `Delegation to @${name} expired — not picked up within 24 hours`, ok: false },
+        tool: {
+            name: busyHold
+                ? `Delegation to @${name} expired — still busy after ${busyHoldCapText()}`
+                : `Delegation to @${name} expired — not picked up within 24 hours`,
+            ok: false,
+        },
     });
 }
-/** Past its 24 hours AND unable to be delivered right now — the same rule
+/** Past a delivery bound AND unable to be delivered right now — the same rule
  * `processOne` applies, so the hourly sweep and a live drain never disagree
- * about which items are actually stuck. A target that was deleted counts as
- * "cannot take the turn": there is nothing to wait on, so such items still
- * expire even though there is no bot left to test busy/free against. */
+ * about which items are actually stuck. The busy-hold cap expires a handoff
+ * whose target has been busy the whole time; the 24-hour TTL catches the
+ * rest. A target that was deleted counts as "cannot take the turn": there is
+ * nothing to wait on, so such items still expire even though there is no bot
+ * left to test busy/free against. */
 function isDueForExpiry(bus, item, now) {
-    if (!isExpired(item, now))
-        return false;
     const target = bus.store.bot(item.toBotId);
     if (!target)
-        return true;
-    return !targetCanTakeTurn(bus, target, item);
+        return isExpired(item, now);
+    return !targetCanTakeTurn(bus, target, item) && (isExpired(item, now) || busyHoldExpired(item, now));
 }
-/** Expire every queued handoff past DELEGATION_TTL_MS that still cannot be
+/** Expire every queued handoff past a delivery bound that still cannot be
  * delivered, wherever it waits. A drain already expires what it touches;
  * this covers the handoff nothing drains — a target that never settles
  * while its source sits idle. A thread mid-drain is skipped: that drain
@@ -549,13 +591,15 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
     if (dropIfThreadGone(bus, target, sourceThreadId, item)) {
         return "settled";
     }
-    // Past its 24 hours AND the target still cannot take the turn: this is the
-    // bound on a busy wait. Use the same free/busy test as holdWhileTargetBusy;
-    // an available target gets even an overdue item. Restart recovery renews
-    // elapsed windows in _loadPending before any target becomes busy. Decide
-    // before announcing a wait so an item cannot post both chips in one pass.
+    // Past a delivery bound AND the target still cannot take the turn: this is
+    // the bound on a busy wait — the busy-hold cap when the target has been
+    // busy the whole time, the 24-hour TTL otherwise. Use the same free/busy
+    // test as holdWhileTargetBusy; an available target gets even an overdue
+    // item. Restart recovery renews elapsed windows in _loadPending before any
+    // target becomes busy. Decide before announcing a wait so an item cannot
+    // post both chips in one pass.
     const canTakeTurn = targetCanTakeTurn(bus, target, item);
-    if (!canTakeTurn && isExpired(item, Date.now())) {
+    if (!canTakeTurn && (isExpired(item, Date.now()) || busyHoldExpired(item, Date.now()))) {
         expireDelegation(bus, sourceThreadId, item, sender.id);
         return "settled";
     }
@@ -564,6 +608,7 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
         return held;
     if (item.waitingOnBusy) {
         delete item.waitingOnBusy;
+        delete item.busySince;
         savePending();
     }
     if (sender.approvePeerComms && !item.approvalAlreadyGranted) {
@@ -582,22 +627,26 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
                 toBotName: target.name,
                 status: "dropped",
                 result: "the peer or source conversation no longer exists",
+                ...(verdict !== "allow" ? { approvalOutcome: verdict } : {}),
             });
             return "settled";
         }
         if (verdict !== "allow") {
+            const failure = peerApprovalFailure(verdict);
             recordDelegationReceipt({
                 id: item.id,
                 sourceThreadId,
                 toBotId: target.id,
                 toBotName: target.name,
-                status: "denied",
-                result: "the user denied this handoff",
+                status: verdict === "deny" ? "denied" : verdict,
+                approvalOutcome: verdict,
+                result: verdict === "deny" ? "the user denied this handoff" : failure.error,
             });
             bus.store.appendMessage(sourceThreadId, {
                 role: "bot",
                 kind: "activity",
-                tool: { name: `Delegation to @${target.name} denied by user`, ok: false },
+                tool: { name: verdict === "deny" ? `Delegation to @${target.name} denied by user`
+                        : `Delegation to @${target.name}: ${failure.error}`, ok: false },
             });
             return "settled";
         }
@@ -614,9 +663,10 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
         }
         // Approval may have waited for minutes (or, with approvalAlreadyGranted,
         // up to 24h since the original ask_bot approval) — recheck the same
-        // free/busy-gated expiry as the pre-approval path before dispatching.
+        // free/busy-gated, busy-hold-capped expiry as the pre-approval path
+        // before dispatching.
         const canTakeTurnAfterApproval = targetCanTakeTurn(bus, current, item);
-        if (!canTakeTurnAfterApproval && isExpired(item, Date.now())) {
+        if (!canTakeTurnAfterApproval && (isExpired(item, Date.now()) || busyHoldExpired(item, Date.now()))) {
             expireDelegation(bus, sourceThreadId, item, currentSender.id);
             return "settled";
         }
@@ -642,30 +692,33 @@ async function processOne(bus, approvalBus, from, sourceThreadId, item, runTarge
     await runTarget(item.toBotId, prefixed, item.depth + 1, sourceThreadId, channel, item.id, sender.id, item.targetThreadId);
     return "dispatched";
 }
-/** "Is the target free to take this handoff right now?" What "busy" means
- * depends on where the turn will run: a classic delegation lands in the
- * target's active thread, so it needs the bot to be idle; a fresh-thread
- * handoff needs only a free slot. This is the single free/busy test shared
- * by the expiry decision in `processOne` and the hold decision below, so
- * the two can never disagree about whether a handoff could have been
- * delivered right now. */
+/** "Is the target free to take this handoff right now?" Both shapes ask for
+ * a free capacity slot, never whole-bot idleness: a classic delegation lands
+ * in the target's standing thread and applies the same admission startTurn
+ * uses for a direct turn there, while a fresh-thread handoff needs any free
+ * slot. This is the single free/busy test shared by the expiry decision in
+ * `processOne` and the hold decision below, so the two can never disagree
+ * about whether a handoff could have been delivered right now. */
 function targetCanTakeTurn(bus, target, item) {
     return item.targetThreadId
         ? (bus.threadSlotFree ? bus.threadSlotFree(target.id) : !target.busy)
-        : !target.busy;
-}
-/** A busy target holds the handoff. Neither counts busy periods — the only
- * bound is DELEGATION_TTL_MS, checked in processOne before this runs (using
- * the same `targetCanTakeTurn` test, passed in as `canTakeTurn` when the
- * caller already computed it so the two checks can't disagree). One waiting
- * chip per handoff, worded for what the target is actually doing. Returns
- * null when the target can take the turn now. */
+        : bus.canAdmitDirectTurn
+            ? bus.canAdmitDirectTurn(target.id, target.threadId)
+            : !target.busy;
+}
+/** A busy target holds the handoff. Neither counts busy periods — the bounds
+ * are the busy-hold cap and DELEGATION_TTL_MS, checked in processOne before
+ * this runs (using the same `targetCanTakeTurn` test, passed in as
+ * `canTakeTurn` when the caller already computed it so the two checks can't
+ * disagree). One waiting chip per handoff, worded for what the target is
+ * actually doing. Returns null when the target can take the turn now. */
 function holdWhileTargetBusy(bus, target, sourceThreadId, item, canTakeTurn = targetCanTakeTurn(bus, target, item)) {
     if (canTakeTurn)
         return null;
     if (item.waitingOnBusy)
         return "requeued";
     item.waitingOnBusy = true;
+    item.busySince = Date.now();
     if (!item.waitAnnounced) {
         item.waitAnnounced = true;
         bus.store.appendMessage(sourceThreadId, {
@@ -724,7 +777,7 @@ function sourceThreadBelongsToBot(store, botId, threadId) {
  * have moved either bot, or narrowed the sender's peers, in between. */
 function dropIfUnreachable(bus, sender, target, sourceThreadId, item) {
     const sectionsDiffer = !canAccessTeam(sender, target.section);
-    if (!sectionsDiffer && !target.hidden && peerAllowed(sender, target.id))
+    if (!sectionsDiffer && !target.hidden && peerAllowed(sender, target))
         return false;
     const reason = sectionsDiffer
         ? "bots now belong to different sections"