openmausbot 0.1.84 → 0.1.86

package/dist-server/server/room-handoffs.js

@@ -78,8 +78,15 @@ export class RoomHandoffs {
     trackExecutionPauses() {
         const now = this.now();
         const executing = new Set();
+        // Roots that still own unsettled nodes. A conversation stopped while a
+        // dispatched teammate executes leaves a terminal root above live work;
+        // pause accounting must survive that root until the whole tree settles.
+        const unsettled = new Set();
         for (const n of this.nodes.values()) {
-            if (!terminal(n) && n.status === "running")
+            if (terminal(n))
+                continue;
+            unsettled.add(n.rootId);
+            if (n.status === "running")
                 executing.add(n.rootId);
         }
         for (const rootId of executing) {
@@ -93,7 +100,7 @@ export class RoomHandoffs {
                 pause.since = undefined;
             }
             const root = this.nodes.get(rootId);
-            if (!root || terminal(root))
+            if (!root || !unsettled.has(rootId))
                 this.pauses.delete(rootId);
         }
     }
@@ -236,12 +243,13 @@ export class RoomHandoffs {
         const node = this.nodes.get(generation);
         if (!node || node.status !== "source")
             return;
+        // An accepted assignment belongs to the queue, not the provider that
+        // submitted it. A failed/expired source turn must not erase that work.
+        // Explicit Stop, deletion and revoked routes still cancel separately.
         if (!ok)
-            this.cancelTree(node, "The originating room turn did not finish", "failed");
-        else {
-            node.status = "waiting";
-            this.publish(node);
-        }
+            node.result = "The originating turn ended before its teammates returned.";
+        node.status = "waiting";
+        this.publish(node);
     }
     cancelTree(node, reason, status = "cancelled") {
         for (const child of this.children(node.id))
@@ -252,6 +260,8 @@ export class RoomHandoffs {
             node.result = reason;
             this.controllers.get(node.id)?.abort();
         }
+        // Settlement closes the paused span now, not at the next periodic tick.
+        this.trackExecutionPauses();
         this.publish(node);
     }
     cancelRoom(groupId, threadId) {
@@ -300,6 +310,7 @@ export class RoomHandoffs {
             node.status = "cancelled";
             node.result = reason;
             this.controllers.get(node.id)?.abort();
+            this.trackExecutionPauses();
             this.publish(node);
         }
         return left;
@@ -337,8 +348,10 @@ export class RoomHandoffs {
             }
             if (n.status !== "queued" && n.status !== "resume")
                 continue;
-            // A newly queued child starts only after its author has settled.
-            if (parent && (parent.status === "source" || parent.status === "running"))
+            // Independent conversations can start as soon as work is accepted.
+            // Same-room speakers still serialize; never overlap their shared chat.
+            if (parent && (parent.status === "source" || parent.status === "running") &&
+                (parent.threadId === n.threadId || (n.groupId && n.groupId === parent.groupId)))
                 continue;
             // A stopped source stops waiting; only work that never started is
             // dropped with it. A teammate mid-turn keeps its process and reports.
@@ -371,14 +384,29 @@ export class RoomHandoffs {
                 if (terminal(n))
                     return;
                 n.result = result.text.slice(0, 12_000);
-                if (!result.ok)
-                    this.cancelTree(n, n.result || "Room agent failed", "failed");
-                else if (this.children(n.id).length > childCount)
+                if (this.children(n.id).length > childCount)
                     n.status = "waiting";
+                else if (!result.ok)
+                    this.cancelTree(n, n.result || "Room agent failed", "failed");
                 else
                     n.status = "completed";
+                // Close the paused span with the settlement itself: work enqueued
+                // before the next periodic tick must be admitted against the aged
+                // budget, not the still-open pause's overstated runway.
+                this.trackExecutionPauses();
                 this.publish(n);
-            }).catch(e => { this.cancelTree(n, String(e).slice(0, 1000), "failed"); })
+            }).catch(e => {
+                if (terminal(n))
+                    return;
+                n.result = String(e).slice(0, 1000);
+                if (this.children(n.id).length > childCount) {
+                    n.status = "waiting";
+                    this.trackExecutionPauses();
+                    this.publish(n);
+                }
+                else
+                    this.cancelTree(n, n.result, "failed");
+            })
                 .finally(() => this.controllers.delete(n.id));
         }
     }

package/dist-server/server/routes/hosted-slack.js

@@ -0,0 +1,20 @@
+// GET /api/bots/:id/slack-management: where, in the organisation's Admin, this
+// bot's Slack app is managed. A deep link only: this server holds no Slack
+// logic, contacts nobody, and the link carries identifiers, never a credential.
+// Client-scoped in server/request-auth.ts, so a member reading Bot Settings
+// gets the same link; Admin authorizes whoever opens it.
+import { hostedSlackManagement } from "../hosted-slack.js";
+import { PASS } from "./table.js";
+export function createHostedSlackRoutes(deps) {
+    return async ({ res, path, method, json }) => {
+        const m = path.match(/^\/api\/bots\/([\w-]+)\/slack-management$/);
+        if (!m || method !== "GET")
+            return PASS;
+        const bot = deps.bot(m[1]);
+        if (!bot || bot.hidden)
+            return json(res, 404, { error: "no such bot" });
+        res.setHeader("cache-control", "no-store");
+        // The id in the link is the stored bot's, not the text from the request.
+        return json(res, 200, hostedSlackManagement(bot.id, deps.hostedReady(), deps.env));
+    };
+}

package/dist-server/server/routes/table.js

@@ -0,0 +1,14 @@
+/** "Not my route": the next handler, then index.ts's inline routes, get a turn. */
+export const PASS = Symbol("route.pass");
+export const ROUTES = [];
+/** Runs handlers in order until one answers; true means stop routing. A
+ * handler that wrote a response but returned PASS by mistake still counts as
+ * answered, so the request can never reach a second handler. */
+export async function dispatchRoutes(routes, ctx) {
+    for (const route of routes) {
+        const out = await route(ctx);
+        if (out !== PASS || ctx.res.headersSent || ctx.res.writableEnded)
+            return true;
+    }
+    return false;
+}

package/dist-server/server/routine-requests.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { z } from "zod";
 import { cronScheduleLabel } from "../shared/cron-label.js";
 import { normalizeCronSchedule, nextCronRuns } from "../shared/routine-schedule.js";
@@ -59,6 +60,7 @@ const routineToolDefinitionSchema = z.object({
     durationMinutes: z.number().optional(),
     timeoutMinutes: z.number().nullable().optional(),
     continuity: z.boolean().optional(),
+    overlap: z.enum(["skip", "queue"]).optional(),
 }).strict();
 const routineToolChangesSchema = routineToolDefinitionSchema
     .omit({ timeoutMinutes: true })
@@ -174,6 +176,7 @@ const storedDefinitionSchema = z.object({
     durationMinutes: z.number().int().min(5).max(240),
     timeoutMinutes: z.number().int().min(5).max(240).optional(),
     continuity: z.boolean().optional(),
+    overlap: z.enum(["skip", "queue"]).optional(),
 }).strict();
 const storedChangesSchema = storedDefinitionSchema
     .omit({ schedule: true, timeoutMinutes: true })
@@ -382,6 +385,7 @@ function normalizeDefinition(input, now) {
         durationMinutes: duration(input.durationMinutes),
         ...(timeoutMinutes == null ? {} : { timeoutMinutes }),
         ...(input.continuity === true ? { continuity: true } : {}),
+        ...(input.overlap === "queue" ? { overlap: "queue" } : {}),
     };
 }
 function normalizeChanges(input, now) {
@@ -400,6 +404,8 @@ function normalizeChanges(input, now) {
         changes.timeoutMinutes = timeout(input.timeoutMinutes);
     if (input.continuity !== undefined)
         changes.continuity = input.continuity === true;
+    if (input.overlap !== undefined)
+        changes.overlap = input.overlap;
     return changes;
 }
 function routineId(value) {
@@ -619,6 +625,7 @@ function effectiveDefinition(operation, manager) {
         durationMinutes: existing.durationMinutes,
         ...(existing.timeoutMinutes === undefined ? {} : { timeoutMinutes: existing.timeoutMinutes }),
         ...(existing.continuity ? { continuity: true } : {}),
+        ...(existing.overlap ? { overlap: existing.overlap } : {}),
     };
     if (operation.action !== "update")
         return base;
@@ -654,7 +661,7 @@ function cardCopy(operation, manager, timeZone, now) {
     const nextRunAt = nextForOperation(operation, manager, now);
     const scheduleTimeZone = definition.schedule.type === "cron" ? definition.schedule.timeZone : timeZone;
     const when = operation.action === "run_now" ? "Now" : scheduleText(definition.schedule, timeZone);
-    const destination = definition.runOn === "cloud" ? "Cloud VM" : "This OpenMausBot setup";
+    const destination = definition.runOn === "cloud" ? "Box-hosted agent" : "Bot’s current model and configured computer";
     const current = operation.action === "create"
         ? null
         : manager.listRoutines().find((routine) => routine.id === operation.routineId) ?? null;
@@ -699,6 +706,7 @@ function cardCopy(operation, manager, timeZone, now) {
             `Runs on: ${destination}`,
             `Run limit: ${definition.timeoutMinutes === undefined ? "No limit" : `${definition.timeoutMinutes} minutes`}`,
             `Continuity: ${definition.continuity ? "Carries the previous run's report into the next run" : "Each run starts fresh"}`,
+            `While busy: ${definition.overlap === "queue" ? "Queue one scheduled run; skip further occurrences until it starts" : "Skip overlapping scheduled occurrences"}`,
             // Last before the instructions: the one sentence that says what
             // confirming actually does, in the reader's terms.
             ...(operation.action === "create" || operation.action === "update"
@@ -723,6 +731,7 @@ function inputFromDefinition(definition, botId, now) {
         durationMinutes: definition.durationMinutes,
         ...(definition.timeoutMinutes === undefined ? {} : { timeoutMinutes: definition.timeoutMinutes }),
         ...(definition.continuity ? { continuity: true } : {}),
+        ...(definition.overlap === "queue" ? { overlap: "queue" } : {}),
     };
 }
 function updateFromChanges(changes, now, currentSchedule) {
@@ -741,6 +750,8 @@ function updateFromChanges(changes, now, currentSchedule) {
         patch.timeoutMinutes = changes.timeoutMinutes;
     if (changes.continuity !== undefined)
         patch.continuity = changes.continuity;
+    if (changes.overlap !== undefined)
+        patch.overlap = changes.overlap;
     return patch;
 }
 function canonicalValue(value) {
@@ -793,6 +804,33 @@ function requestCommit(payload, messageId) {
     };
 }
 function revalidateOperation(operation, manager, botId, now) {
+    if (operation.action === "create") {
+        const definition = operation.routine;
+        const owner = operation.forBot?.botId ?? botId;
+        const schedule = asSchedule(definition.schedule, now);
+        const duplicate = manager.listRoutines().find((routine) => {
+            if (!routine.enabled || routine.target !== "bot" || routine.botId !== owner
+                || routine.runOn !== definition.runOn || routine.prompt !== definition.instructions
+                || routine.durationMinutes !== definition.durationMinutes
+                || routine.timeoutMinutes !== definition.timeoutMinutes
+                || Boolean(routine.continuity) !== Boolean(definition.continuity)
+                || (routine.overlap ?? "skip") !== (definition.overlap ?? "skip")
+                || (routine.attachments?.length ?? 0) > 0)
+                return false;
+            // An omitted start means "every N minutes", not a new phase each time
+            // the model retries. Explicit starts and all other constraints stay exact.
+            const candidate = schedule.type === "interval" && routine.schedule.type === "interval"
+                && definition.schedule.type === "interval" && definition.schedule.anchorAt === undefined
+                ? { ...schedule, anchorAt: routine.schedule.anchorAt }
+                : schedule;
+            return isDeepStrictEqual(candidate, routine.schedule);
+        });
+        if (duplicate) {
+            // The tool cannot choose a result destination. Return the existing ID,
+            // without moving its reports or treating a renamed request as new work.
+            throw new RoutineRequestError(`An enabled routine with the same instructions and execution settings already exists (${duplicate.id}). Use list_routines to review it, then update or run that routine instead.`, 409);
+        }
+    }
     const current = operation.action === "create"
         ? null
         : verifyManageSnapshot(operation, manager, botId);

package/dist-server/server/routines.js

@@ -6,6 +6,7 @@ import { DATA_DIR } from "./config.js";
 import { writeFileAtomic } from "./atomic.js";
 import { redactSecretsInText } from "./redact.js";
 import { normalizeCronSchedule, nextCronRuns } from "../shared/routine-schedule.js";
+import { isRoutineProblemRun } from "../shared/routines.js";
 const persistedSourceThreadId = z.string().trim().min(1).optional().catch(undefined);
 const webhookRunReceiptSchema = z.object({
     webhookId: z.string().min(1).max(200),
@@ -432,6 +433,9 @@ function sanitizeInput(input, after) {
         throw new Error("Attachments can only run on this computer until cloud file staging is available");
     }
     const continuity = input.continuity === true;
+    if (input.overlap !== undefined && input.overlap !== "skip" && input.overlap !== "queue") {
+        throw new Error("Choose skip or queue for overlapping runs");
+    }
     if (continuity && target === "room-goal") {
         throw new Error("Room goals do not carry continuity yet");
     }
@@ -448,6 +452,7 @@ function sanitizeInput(input, after) {
         ...(timeoutMinutes === undefined ? {} : { timeoutMinutes }),
         attachments,
         ...(continuity ? { continuity: true } : {}),
+        ...(input.overlap === "queue" ? { overlap: "queue" } : {}),
     };
 }
 export class RoutineManager {
@@ -482,9 +487,13 @@ export class RoutineManager {
                         attachments: loadAttachments(routine.attachments),
                         sourceThreadId: persistedSourceThreadId.parse(routine.sourceThreadId),
                         resultsThreadId: persistedSourceThreadId.parse(routine.resultsThreadId),
+                        overlap: routine.overlap === "queue" ? "queue" : undefined,
+                        skippedRuns: Number.isSafeInteger(routine.skippedRuns) && routine.skippedRuns > 0 ? routine.skippedRuns : undefined,
+                        lastSkippedAt: Number.isSafeInteger(routine.lastSkippedAt) && routine.lastSkippedAt >= 0 && routine.lastSkippedAt <= MAX_DATE_MS ? routine.lastSkippedAt : undefined,
                     };
                     if (loaded.timeoutMinutes === undefined)
                         delete loaded.timeoutMinutes;
+                    delete loaded.failureStreak;
                     return [loaded];
                 })
                 : [];
@@ -564,7 +573,16 @@ export class RoutineManager {
         }
     }
     listRoutines() {
-        return this.routines.map(cloneRoutine);
+        return this.routines.map(routine => this.routineWithHealth(routine));
+    }
+    routineWithHealth(routine) {
+        // Successful delegated/provider turns are not successful runs until the
+        // routine settles. Cancellation and missed schedules are not attempts.
+        const outcomes = this.runs.filter(run => run.routineId === routine.id && (run.status === "failed" || run.status === "completed")).reverse()
+            .sort((a, b) => (b.finishedAt ?? b.createdAt) - (a.finishedAt ?? a.createdAt) || b.createdAt - a.createdAt);
+        const success = outcomes.findIndex(run => run.status === "completed");
+        const failures = success < 0 ? outcomes.length : success;
+        return { ...cloneRoutine(routine), ...(failures ? { failureStreak: failures } : {}) };
     }
     /** Whether this computer should stay awake for routines: a run is in
      * flight, or an enabled routine is due within the horizon. The schedule
@@ -664,7 +682,7 @@ export class RoutineManager {
             if (receipt) {
                 const committed = this.routines.find((routine) => routine.id === receipt.resultId);
                 if (committed)
-                    return cloneRoutine(committed);
+                    return this.routineWithHealth(committed);
                 throw new Error("This routine request was already applied");
             }
         }
@@ -693,14 +711,14 @@ export class RoutineManager {
                 this.rememberRoutineRequest(request, routine.id, at);
         }, discardResults);
         this.emitRoutine(routine);
-        return cloneRoutine(routine);
+        return this.routineWithHealth(routine);
     }
     update(id, patch, request) {
         if (request) {
             const receipt = this.matchingRoutineRequestReceipt(request);
             if (receipt) {
                 const committed = this.routines.find((routine) => routine.id === receipt.resultId);
-                return committed ? cloneRoutine(committed) : null;
+                return committed ? this.routineWithHealth(committed) : null;
             }
         }
         const routine = this.routines.find((r) => r.id === id);
@@ -720,6 +738,7 @@ export class RoutineManager {
             timeoutMinutes: Object.hasOwn(patch, "timeoutMinutes") ? patch.timeoutMinutes : routine.timeoutMinutes,
             attachments: patch.attachments ?? routine.attachments,
             continuity: patch.continuity ?? routine.continuity,
+            overlap: Object.hasOwn(patch, "overlap") ? patch.overlap : routine.overlap,
         }, now);
         if (this.targetState(clean) === "missing")
             throw new Error(this.missingTargetMessage(clean.target));
@@ -749,6 +768,8 @@ export class RoutineManager {
             // rather than false, so switching continuity off has to delete it.
             if (!clean.continuity)
                 delete routine.continuity;
+            if (clean.overlap !== "queue")
+                delete routine.overlap;
             if (Object.hasOwn(patch, "timeoutMinutes") && patch.timeoutMinutes == null) {
                 delete routine.timeoutMinutes;
             }
@@ -769,7 +790,7 @@ export class RoutineManager {
         for (const run of cancelledRuns)
             this.emitRun(run);
         this.emitRoutine(routine);
-        return cloneRoutine(routine);
+        return this.routineWithHealth(routine);
     }
     remove(id, request) {
         if (request) {
@@ -1043,6 +1064,27 @@ export class RoutineManager {
         }
         return cloneRun(run);
     }
+    /** Clear every failure indicator at once: stamp seenAt on each unseen
+     * failed/missed run in one committed save, then emit the updated runs so
+     * connected clients drop their dots immediately. A failed save rolls the
+     * stamps back so a retry still finds the unseen runs. */
+    markAllSeen() {
+        if (!this.runs.some((run) => !run.seenAt && isRoutineProblemRun(run)))
+            return [];
+        const stampAt = this.now();
+        const updated = [];
+        this.commitMutation(() => {
+            for (const run of this.runs) {
+                if (run.seenAt || !isRoutineProblemRun(run))
+                    continue;
+                run.seenAt = stampAt;
+                updated.push(run);
+            }
+        });
+        for (const run of updated)
+            this.emitRun(run);
+        return updated.map(cloneRun);
+    }
     get isTicking() { return this.ticking; }
     start() {
         if (this.timer)
@@ -1098,8 +1140,10 @@ export class RoutineManager {
                             : pendingAt;
                         // Frequent recurring work must not build an unbounded queue of stale
                         // copies. Elapsed intervals keep their phase; cron keeps its calendar.
-                        const overlapping = (routine.schedule.type === "interval" || routine.schedule.type === "cron") && this.runs.some((run) => run.routineId === routine.id && ["queued", "running", "waiting"].includes(run.status));
-                        if (!overlapping) {
+                        const overlapping = routine.schedule.type !== "once" && this.runs.some((run) => run.routineId === routine.id && ["queued", "running", "waiting"].includes(run.status));
+                        const scheduledQueued = this.runs.some(run => run.routineId === routine.id && run.status === "queued" &&
+                            (run.triggerSource ?? (run.manual ? "manual" : "schedule")) === "schedule");
+                        if (!overlapping || (routine.overlap === "queue" && !scheduledQueued)) {
                             const run = this.newRun(routine, scheduledFor, false, allocations);
                             if (late > CATCH_UP_MS) {
                                 run.status = "missed";
@@ -1108,6 +1152,10 @@ export class RoutineManager {
                             }
                             scheduledRuns.push(run);
                         }
+                        else {
+                            routine.skippedRuns = Math.min(Number.MAX_SAFE_INTEGER, (routine.skippedRuns ?? 0) + 1);
+                            routine.lastSkippedAt = scheduledFor;
+                        }
                         routine.nextRunAt =
                             routine.schedule.type === "once" ? null : nextOccurrence(routine.schedule, Math.max(now, scheduledFor));
                         // `updatedAt` is the optimistic definition revision carried by
@@ -1170,7 +1218,10 @@ export class RoutineManager {
                         continue;
                     }
                 }
-                const state = this.targetState(run);
+                // A bot can have spare thread slots while this routine is waiting on
+                // a teammate. Queue means after THIS run, not merely a free bot slot.
+                const sameRoutineWorking = triggerSource === "schedule" && this.runs.some(other => other.id !== run.id && other.routineId === run.routineId && ["running", "waiting"].includes(other.status));
+                const state = sameRoutineWorking ? "busy" : this.targetState(run);
                 if (state === "busy") {
                     // A queued run behind a busy target is deferred, not silent. Stamp
                     // the wait once so receipts and cards can say how long it has been
@@ -1453,11 +1504,16 @@ export class RoutineManager {
         routine.resultsThreadId = value.trim();
     }
     emitRoutine(routine) {
-        this.options.emit?.({ kind: "routine", routine: cloneRoutine(routine) });
+        this.options.emit?.({ kind: "routine", routine: this.routineWithHealth(routine) });
     }
     emitRun(run) {
         this.options.emit?.({ kind: "routine.run", run: cloneRun(run) });
         this.notifyRunChanged(run);
+        if (run.status === "completed" || run.status === "failed") {
+            const routine = this.routines.find(candidate => candidate.id === run.routineId);
+            if (routine)
+                this.emitRoutine(routine);
+        }
     }
     notifyRunChanged(run) {
         try {

package/dist-server/server/shared-computer-control.js

@@ -1,5 +1,6 @@
 /** A local desktop call competes with ordinary bot turns for the same screen.
  * Leases expire if Electron crashes; human takeover always wins renewal. */
+const LEASE_EXPIRY_MS = 40_000;
 export class SharedComputerControl {
     leases = new Map();
     resources;
@@ -11,12 +12,38 @@ export class SharedComputerControl {
             this.release(id);
             throw Object.assign(new Error("This computer is in use locally or held by a person. Wait, then observe it again before acting."), { status: 409 });
         }
-        clearTimeout(this.leases.get(id));
-        this.leases.set(id, setTimeout(() => this.release(id), 40_000));
+        this.arm(id);
+    }
+    /** Extends a held lease for one long desktop action without re-running the
+     * takeover checks: a heartbeat while the operation is pending must not be
+     * able to lose its own screen. Renewing an expired or released id is a
+     * no-op — the lease is gone and only acquire can bring it back. */
+    renew(id) {
+        if (this.leases.has(id))
+            this.arm(id);
+    }
+    /** (Re)arm the expiry timer. The generation counter makes a stale timer a
+     * no-op: only the callback of the newest arming may release the lease. */
+    arm(id) {
+        const previous = this.leases.get(id);
+        if (previous)
+            clearTimeout(previous.timer);
+        const generation = (previous?.generation ?? 0) + 1;
+        this.leases.set(id, {
+            timer: setTimeout(() => {
+                if (this.leases.get(id)?.generation === generation)
+                    this.release(id);
+            }, LEASE_EXPIRY_MS),
+            generation,
+            lastActivity: Date.now(),
+        });
     }
     release(id) {
-        clearTimeout(this.leases.get(id));
-        this.leases.delete(id);
+        const lease = this.leases.get(id);
+        if (lease) {
+            clearTimeout(lease.timer);
+            this.leases.delete(id);
+        }
         this.resources.release({ threadId: `shared:${id}`, generation: id });
     }
     close() { for (const id of this.leases.keys())

package/dist-server/server/spend.js

@@ -1,33 +1,76 @@
+// Spend limits over the usage ledger: what this workspace has spent this
+// month against its cap, the refusal a turn gets once the cap is reached,
+// and the one-per-month notices when the month crosses the warning
+// threshold and the cap. The figure is every cost in the ledger: what
+// engines reported (on a workspace of personal subscriptions, their
+// equivalents too) plus the estimates booked for engines that report tokens
+// but no price (server/model-prices.ts). A turn on an unpriced model counts
+// nothing. Enforced only with the `budgets` entitlement; without it the
+// setting is inert.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { entitled } from "./enterprise.js";
-import { readUsage } from "./usage-ledger.js";
+import { readUsage, usageRowKey } from "./usage-ledger.js";
 const DEFAULT_WARN_AT_PERCENT = 80;
 const CACHE_MS = 15_000;
 // Every turn start asks; reading the month file each time would be silly.
+// A read keeps the keys of the rows it summed, so a booked row can be told
+// apart from the same row read back later.
 const cache = new Map();
+// Booked turns whose ledger row may not be on disk yet: dataDir → row key →
+// cost. The append is asynchronous, and a turn that ran longer than CACHE_MS
+// would otherwise be re-read out of the month before its own row landed.
+const unwritten = new Map();
 function monthOf(now) {
     return now.toISOString().slice(0, 7);
 }
-/** Reported cost this month so far, from the ledger, cached briefly. */
+const costOf = (value) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0);
+/** Reported and estimated cost this month so far: the ledger file (read at
+ * most every CACHE_MS) plus turns booked since whose rows have not landed. */
 export function monthToDateSpend(dataDir, now = new Date()) {
     const month = monthOf(now);
-    const hit = cache.get(dataDir);
-    if (hit && hit.month === month && now.getTime() - hit.at < CACHE_MS)
-        return hit.spentUsd;
-    const from = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
-    const spentUsd = readUsage(dataDir, { from, to: now }).reduce((sum, row) => sum + (typeof row.costUsd === "number" && Number.isFinite(row.costUsd) ? row.costUsd : 0), 0);
-    cache.set(dataDir, { at: now.getTime(), month, spentUsd });
-    return spentUsd;
-}
-/** Called right after a turn is booked, so the next check sees it without
- * waiting for the ledger's append to land or the cache to expire. */
-export function noteSpend(dataDir, costUsd, now = new Date()) {
-    const hit = cache.get(dataDir);
-    if (hit && hit.month === monthOf(now) && typeof costUsd === "number" && Number.isFinite(costUsd) && costUsd > 0) {
-        hit.spentUsd += costUsd;
+    let read = cache.get(dataDir);
+    if (!read || read.month !== month || now.getTime() - read.at >= CACHE_MS) {
+        const from = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+        const rows = readUsage(dataDir, { from, to: now });
+        read = { at: now.getTime(), month, fileUsd: rows.reduce((sum, row) => sum + costOf(row.costUsd), 0), keys: new Set(rows.map(usageRowKey)) };
+        cache.set(dataDir, read);
     }
+    let pending = 0;
+    for (const [key, entry] of unwritten.get(dataDir) ?? []) {
+        if (entry.month === month && !read.keys.has(key))
+            pending += entry.costUsd;
+    }
+    return read.fileUsd + pending;
+}
+/** Called as a turn is booked, with the ledger's write for its row
+ * (appendUsage's promise). The cost counts from memory at once; when the
+ * row lands it moves into the cached read, and a re-read that already sees
+ * the row never counts it twice. A write that failed stops counting, as
+ * the ledger has no row for it. */
+export function noteSpend(dataDir, row, written) {
+    const costUsd = costOf(row.costUsd);
+    if (!costUsd)
+        return;
+    const key = usageRowKey(row);
+    const month = row.at.slice(0, 7);
+    const entries = unwritten.get(dataDir) ?? new Map();
+    unwritten.set(dataDir, entries);
+    entries.set(key, { month, costUsd });
+    void written.then((landed) => {
+        entries.delete(key);
+        if (entries.size === 0 && unwritten.get(dataDir) === entries)
+            unwritten.delete(dataDir);
+        const read = cache.get(dataDir);
+        if (landed && read && read.month === month && !read.keys.has(key)) {
+            read.fileUsd += costUsd;
+            read.keys.add(key);
+        }
+    });
 }
 export function resetSpendCacheForTests() {
     cache.clear();
+    unwritten.clear();
 }
 /** The cap and where the month stands against it; null when there is no
  * enforceable cap (no entitlement, or none set). */
@@ -59,3 +102,55 @@ export function assertWithinBudget(cfg, dataDir, now = new Date(), isEntitled =
         return;
     throw Object.assign(new Error(`this workspace has reached its monthly spend limit of $${usd(state.monthlyUsd)} — an admin can raise it under Settings → Usage`), { status: 409, code: "spend_cap" });
 }
+const ALERTS_FILE = "alerts.json";
+function readMarks(dataDir) {
+    try {
+        const value = JSON.parse(readFileSync(join(dataDir, "usage", ALERTS_FILE), "utf8"));
+        if (typeof value !== "object" || value === null)
+            return null;
+        const marks = value;
+        return typeof marks.month === "string" && typeof marks.monthlyUsd === "number" ? marks : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The notice this booking should raise, if any: the cap the first time the
+ * month reaches it, the warning the first time it crosses the threshold, and
+ * nothing again for either that month. A new month, or a different cap, is a
+ * new budget and starts over. Marks live beside the ledger so a restart does
+ * not repeat them; if they cannot be written the notice is still sent once
+ * for this run. */
+export function takeSpendAlert(dataDir, state) {
+    if (!state || (!state.warn && !state.exceeded))
+        return null;
+    const saved = readMarks(dataDir) ?? memoryMarks.get(dataDir) ?? null;
+    const marks = saved && saved.month === state.month && saved.monthlyUsd === state.monthlyUsd
+        ? saved
+        : { month: state.month, monthlyUsd: state.monthlyUsd };
+    const alert = state.exceeded && !marks.cap ? "cap" : state.warn && !marks.warn && !marks.cap ? "warn" : null;
+    if (!alert)
+        return null;
+    // Reaching the cap also answers the warning: one notice, the stronger one.
+    const next = { ...marks, warn: true, ...(alert === "cap" ? { cap: true } : {}) };
+    memoryMarks.set(dataDir, next);
+    try {
+        mkdirSync(join(dataDir, "usage"), { recursive: true, mode: 0o700 });
+        writeFileSync(join(dataDir, "usage", ALERTS_FILE), JSON.stringify(next), { mode: 0o600 });
+    }
+    catch {
+        /* bookkeeping must never take down the turn */
+    }
+    return alert;
+}
+const memoryMarks = new Map();
+export function resetSpendAlertsForTests() {
+    memoryMarks.clear();
+}
+/** The notice's words. English like the server's other notification titles. */
+export function spendAlertText(alert, state) {
+    const spent = `$${state.spentUsd.toFixed(2)} of $${usd(state.monthlyUsd)} spent this month (${state.month})`;
+    return alert === "cap"
+        ? { title: "Monthly spend limit reached", body: `${spent}. New turns are refused until an admin raises the limit under Settings → Usage.` }
+        : { title: `Spend is at ${state.percent}% of the monthly limit`, body: `${spent}. New turns stop when the limit is reached.` };
+}