openmausbot 0.1.56 → 0.1.58

package/dist-server/server/mcp-bridge.js

@@ -1,17 +1,17 @@
-// The one transparent stdio bridge behind both MCP entry points
+// The one stdio bridge behind both MCP entry points
 // (container-mcp.ts for the Local VM, vps-container-mcp.ts for the BYO VPS).
-// It defines no tools and parses no MCP messages: bytes in, bytes out.
 //
-// The single exception to that transparency is the who-is-driving gate
-// (opt-in via `gate`). While the person holds control of this computer in
-// the app, a `tools/call` from the agent is answered with a refusal HERE,
-// on the near side, and never forwarded — Cua Driver on the far side has
-// no concept of a person holding the wheel, so the refusal cannot come
-// from anywhere else. Everything that is not a tools/call still passes
-// through untouched, and with no gate configured the bridge remains the
-// byte-for-byte pipe described above.
+// It is almost transparent — bytes in, bytes out — with two deliberate
+// near-side exceptions:
 //
-// Two behaviors live here so neither entry point can drift:
+//   1. `ping`. The bundled cua-driver (through at least v0.22.1) does not
+//      implement this MCP method and would answer with -32601. Answering it
+//      here keeps the handshake alive without reaching the driver.
+//   2. The who-is-driving `gate` (opt-in via `gate`). While the person holds
+//      control of this computer, a `tools/call` from the agent is answered
+//      with a refusal here and never forwarded.
+//
+// Both behaviors live here so neither entry point can drift:
 //   1. Exit without truncation. `process.exit()` in a close/error handler
 //      discards whatever is still buffered on stdout — a final MCP result
 //      would be cut mid-frame. The bridge sets exitCode and unpipes instead,
@@ -165,6 +165,36 @@ export function createGateInterceptor(options) {
         });
     };
 }
+/** The near-side MCP method filter. `ping` is answered here so the bundled
+ * cua-driver is never invoked for it; everything else is delegated to the
+ * gate (if configured) or forwarded untouched. */
+export function createMcpBridgeInterceptor(options) {
+    const afterPing = options.gate
+        ? createGateInterceptor({
+            isHeld: options.gate.isHeld,
+            forward: options.forward,
+            refuse: options.answer,
+            refusalText: options.gate.refusalText,
+        })
+        : options.forward;
+    return (line) => {
+        let frame = null;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            // not a frame this bridge understands — forward untouched
+        }
+        if (frame && frame.method === "ping") {
+            // Notifications have no `id` and require no response.
+            if (frame.id !== undefined) {
+                options.answer(JSON.stringify({ jsonrpc: "2.0", id: frame.id, result: {} }));
+            }
+            return;
+        }
+        afterPing(line);
+    };
+}
 export function runMcpBridge(options) {
     const child = spawn(options.command, options.args, {
         shell: false,
@@ -174,39 +204,38 @@ export function runMcpBridge(options) {
     // docker may exit before it drains stdin; pipe() leaves this error unhandled.
     child.stdin.on("error", () => { });
     child.stderr.pipe(process.stderr);
-    let detach;
-    if (options.gate) {
-        const client = createControlClient({ url: options.gate.url, token: options.gate.token });
-        const inbound = createLineSplitter(createGateInterceptor({
-            isHeld: async () => (await client.state(true)).held,
-            forward: (line) => child.stdin.write(line + "\n"),
-            refuse: (line) => process.stdout.write(line + "\n"),
-        }));
-        const onStdin = (chunk) => inbound.push(chunk);
-        process.stdin.on("data", onStdin);
-        process.stdin.on("end", () => {
-            inbound.flush();
-            child.stdin.end();
-        });
-        // Injected refusals must never land inside one of the child's
-        // half-written frames, so the child's stdout is re-emitted at line
-        // granularity as well.
-        const outbound = createLineSplitter((line) => process.stdout.write(line + "\n"));
-        child.stdout.on("data", (chunk) => outbound.push(chunk));
-        child.stdout.on("end", () => outbound.flush());
-        detach = () => {
-            process.stdin.off("data", onStdin);
-            process.stdin.pause();
-        };
-    }
-    else {
-        process.stdin.pipe(child.stdin);
-        child.stdout.pipe(process.stdout);
-        detach = () => {
-            process.stdin.unpipe(child.stdin);
-            process.stdin.pause();
-        };
-    }
+    const client = options.gate
+        ? createControlClient({ url: options.gate.url, token: options.gate.token })
+        : null;
+    const answer = (line) => process.stdout.write(line + "\n");
+    const forward = (line) => child.stdin.write(line + "\n");
+    const inbound = createLineSplitter(createMcpBridgeInterceptor({
+        answer,
+        forward,
+        ...(options.gate
+            ? {
+                gate: {
+                    isHeld: async () => (await client.state(true)).held,
+                },
+            }
+            : {}),
+    }));
+    const onStdin = (chunk) => inbound.push(chunk);
+    process.stdin.on("data", onStdin);
+    process.stdin.on("end", () => {
+        inbound.flush();
+        child.stdin.end();
+    });
+    // Injected responses and refusals must never land inside one of the
+    // child's half-written frames, so the child's stdout is re-emitted at
+    // line granularity as well.
+    const outbound = createLineSplitter((line) => process.stdout.write(line + "\n"));
+    child.stdout.on("data", (chunk) => outbound.push(chunk));
+    child.stdout.on("end", () => outbound.flush());
+    const detach = () => {
+        process.stdin.off("data", onStdin);
+        process.stdin.pause();
+    };
     let watchdog = null;
     if (options.liveness) {
         const liveness = options.liveness;

package/dist-server/server/package-export.js

@@ -119,6 +119,7 @@ export function createBotPackageExport(input) {
             name: bot.name,
             title: bot.title,
             description: bot.description,
+            ...(bot.soul !== undefined ? { soul: bot.soul } : {}),
             appearance,
         };
         const assigned = agentPlaybooks.get(bot.id);

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

@@ -0,0 +1,332 @@
+// propose_profile: a bot proposes changes to its own name, title, description,
+// SOUL.md, or working folder; the change lands only when the user confirms the card. Same
+// shape as routine-requests.ts, much smaller: the profile commits in one
+// store call, and staleness is a hash of the five fields instead of a
+// scheduler revision. Everything here is re-validated at confirm time —
+// a card can sit open for days.
+import { lineDiff } from "../shared/line-diff.js";
+import { BOT_PROFILE_LIMITS } from "../shared/bot-profile.js";
+import { PROFILE_REQUEST_FIELDS } from "../shared/profile-request.js";
+import { parseBotProfilePatch } from "./bot-profile.js";
+import { validateBotCwd } from "./bot-cwd.js";
+import { newId } from "./contracts.js";
+import { profileRevision, profileSnapshot } from "./profile-revision.js";
+import { recordProfileChange } from "./profile-versions.js";
+import { redactSecretsInText } from "./redact.js";
+const MAX_REASON = 500;
+const MAX_DIFF_LINES = 400;
+const STALE = "This bot's profile changed after this card was prepared. Ask the bot to review it and propose again.";
+const NO_SUCH_BOT = "That bot no longer exists";
+const LABELS = {
+    name: "Name",
+    title: "Title",
+    description: "Description",
+};
+const PRIVATE_WORKSPACE = "its private workspace";
+const CHOOSE_ONE = "Choose at least one of name, title, description, soul, cwd";
+export class ProfileRequestError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.name = "ProfileRequestError";
+        this.status = status;
+    }
+}
+function reasonText(value) {
+    if (typeof value !== "string")
+        throw new ProfileRequestError("reason is required");
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new ProfileRequestError("reason is required");
+    if (trimmed.length > MAX_REASON) {
+        throw new ProfileRequestError(`reason must be ${MAX_REASON} characters or fewer`);
+    }
+    return redactSecretsInText(trimmed);
+}
+/** `parseBotProfilePatch` would silently accept a key like `notifications` —
+ * valid for the broader bot patch, not for a profile request. Reject keys
+ * outside the proposable fields ourselves first, for exact copy. */
+function parseChanges(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new ProfileRequestError(CHOOSE_ONE);
+    }
+    const keys = Object.keys(input);
+    for (const key of keys) {
+        if (!PROFILE_REQUEST_FIELDS.includes(key)) {
+            throw new ProfileRequestError(`unsupported profile field: ${key}`);
+        }
+    }
+    if (keys.length === 0) {
+        throw new ProfileRequestError(CHOOSE_ONE);
+    }
+    // The working folder is not a profile-patch field (PATCH /api/bots checks
+    // it with validateBotCwd, not parseBotProfilePatch), so it is split off and
+    // checked the same way that route does: absolute, exists, is a folder.
+    // "" (or null) means the private workspace.
+    const { cwd: rawCwd, ...profileInput } = input;
+    let cwdChange;
+    if (rawCwd !== undefined) {
+        const checked = validateBotCwd(rawCwd);
+        if (!checked.ok)
+            throw new ProfileRequestError(checked.error, 400);
+        cwdChange = checked.cwd ?? "";
+    }
+    const parsed = Object.keys(profileInput).length
+        ? parseBotProfilePatch(profileInput, true)
+        : { ok: true, patch: {} };
+    if (!parsed.ok)
+        throw new ProfileRequestError(parsed.error, 400);
+    const changes = {};
+    if (cwdChange !== undefined)
+        changes.cwd = cwdChange;
+    for (const field of PROFILE_REQUEST_FIELDS) {
+        if (field === "cwd")
+            continue;
+        const value = parsed.patch[field];
+        // This payload is hidden under the card's visible fields, so the store's
+        // shallow card redaction cannot reach it. Scrub before it is persisted.
+        if (typeof value !== "string")
+            continue;
+        const redacted = redactSecretsInText(value);
+        // A mask can be LONGER than the secret it replaces (e.g. an 8-char
+        // value becomes "«redacted 8 chars»"), so a value that passed the raw
+        // cap can come out the other side over it. Re-check with the exact
+        // copy the parser itself would have used.
+        if (field === "soul") {
+            if (Buffer.byteLength(redacted, "utf8") > BOT_PROFILE_LIMITS.soul) {
+                throw new ProfileRequestError("standing instructions must be at most 24000 bytes");
+            }
+        }
+        else {
+            const limit = BOT_PROFILE_LIMITS[field];
+            if (redacted.length > limit) {
+                throw new ProfileRequestError(`${field} must be at most ${limit} characters`);
+            }
+        }
+        changes[field] = redacted;
+    }
+    return changes;
+}
+export function profileCardCopy(target, fullProfile, before, changes, reason) {
+    // Whether this is a first-time setup is a property of the bot's WHOLE
+    // profile, not of the fields this particular proposal happens to touch —
+    // otherwise a name-only rename of an established bot reads as "Set up X?"
+    // just because title/description/soul never appear in `before`.
+    const isSetup = !fullProfile.title && !fullProfile.description && !fullProfile.soul;
+    const title = target.crossBot
+        ? `Update @${target.name}'s profile?`
+        : isSetup
+            ? `Set up ${target.name}?`
+            : `Update ${target.name}'s profile?`;
+    const lines = target.crossBot ? [`Whose profile: @${target.name}`, `Why: ${reason}`] : [`Why: ${reason}`];
+    for (const field of PROFILE_REQUEST_FIELDS) {
+        if (field === "soul" || field === "cwd")
+            continue;
+        if (changes[field] === undefined)
+            continue;
+        lines.push(`${LABELS[field]}: "${before[field] ?? ""}" → "${changes[field]}"`);
+    }
+    if (changes.cwd !== undefined) {
+        lines.push(`Working folder: ${before.cwd || PRIVATE_WORKSPACE} → ${changes.cwd || PRIVATE_WORKSPACE}`);
+    }
+    if (changes.soul !== undefined) {
+        const beforeSoul = before.soul ?? "";
+        const afterSoul = changes.soul;
+        const bytesBefore = Buffer.byteLength(beforeSoul, "utf8");
+        const bytesAfter = Buffer.byteLength(afterSoul, "utf8");
+        lines.push(`SOUL.md (${bytesBefore} → ${bytesAfter} bytes):`);
+        const diff = lineDiff(beforeSoul, afterSoul);
+        if (diff.length > MAX_DIFF_LINES) {
+            // Truncating a diff can hide the very instructions being approved.
+            // The full replacement is already byte-bounded by profile validation
+            // and is readable in the same generic card on desktop and phones.
+            lines.push("Large change — complete proposed instructions (replaces the current SOUL.md):");
+            lines.push(afterSoul || "(empty)");
+        }
+        else {
+            lines.push(...diff);
+        }
+    }
+    // The closing line says the consequence of exactly what is on the card:
+    // a folder change moves where the bot's tools read and write; the other
+    // fields change what it is told. Either way nothing runs on confirm.
+    const onlyFolder = Object.keys(changes).every((field) => field === "cwd");
+    if (changes.cwd !== undefined)
+        lines.push(`${target.name}'s tools will read and write files in that folder.`);
+    lines.push(onlyFolder ? "Nothing runs." : `Changes what ${target.name} is told on every turn. Nothing runs.`);
+    const detail = lines.join("\n");
+    const fields = PROFILE_REQUEST_FIELDS.filter((field) => changes[field] !== undefined);
+    const summary = `${title} · ${fields.join(", ")}`;
+    return { title, summary, detail };
+}
+export class ProfileRequestService {
+    store;
+    now;
+    canPersist;
+    /** Public: a caller's section membership can change between propose and
+     * confirm, and tests flip this mid-scenario to model that. */
+    validateTarget;
+    constructor(options) {
+        this.store = options.store;
+        this.now = options.now ?? Date.now;
+        this.canPersist = options.canPersist;
+        this.validateTarget = options.validateTarget;
+    }
+    propose(args) {
+        const reason = reasonText(args.reason);
+        const changes = parseChanges(args.changes);
+        const targetBotId = args.targetBotId ?? args.botId;
+        const target = this.store.bot(targetBotId);
+        if (!target)
+            throw new ProfileRequestError(NO_SUCH_BOT, 404);
+        const crossBot = targetBotId !== args.botId;
+        if (crossBot && this.validateTarget) {
+            const refusal = this.validateTarget(args.botId, targetBotId);
+            if (refusal)
+                throw new ProfileRequestError(refusal, 403);
+        }
+        const snapshot = profileSnapshot(target);
+        const before = {};
+        const finalChanges = {};
+        for (const field of PROFILE_REQUEST_FIELDS) {
+            const value = changes[field];
+            if (value === undefined)
+                continue;
+            if (value === snapshot[field])
+                continue;
+            before[field] = redactSecretsInText(snapshot[field]);
+            finalChanges[field] = value;
+        }
+        if (Object.keys(finalChanges).length === 0) {
+            throw new ProfileRequestError("Nothing would change");
+        }
+        const requestId = newId();
+        const targetName = redactSecretsInText(target.name);
+        const payload = {
+            version: 1,
+            requestId,
+            botId: args.botId,
+            threadId: args.threadId,
+            targetBotId,
+            targetName,
+            createdAt: this.now(),
+            reason,
+            changes: finalChanges,
+            before,
+            expectedRevision: profileRevision(target),
+        };
+        const copy = profileCardCopy({ name: targetName, crossBot }, snapshot, before, finalChanges, reason);
+        const persistence = this.canPersist?.(args.botId, args.threadId);
+        if (persistence && !persistence.ok) {
+            throw new ProfileRequestError(persistence.error, persistence.status);
+        }
+        const messageInput = {
+            role: "bot",
+            kind: "options",
+            card: {
+                title: copy.title,
+                subtitle: copy.detail,
+                options: ["Confirm", "Cancel"],
+                requestId,
+                tool: "update_profile",
+                profileRequest: payload,
+            },
+        };
+        if (args.from)
+            messageInput.from = args.from;
+        const message = this.store.appendMessage(args.threadId, messageInput);
+        return { requestId, messageId: message.id, title: copy.title, summary: copy.summary, detail: copy.detail };
+    }
+    /** Claims a profile card even after it was settled, so a duplicate click
+     * never re-applies an already-applied change. */
+    resolve(args) {
+        const message = this.store
+            .messagesFor(args.threadId)
+            .find((candidate) => candidate.card?.requestId === args.requestId && candidate.card.profileRequest);
+        const card = message?.card;
+        const payload = card?.profileRequest;
+        if (!message || !card || !payload)
+            return { claimed: false, state: "not_found" };
+        if (payload.requestId !== card.requestId) {
+            return { claimed: true, state: "invalid", error: "This profile request does not match its card", status: 409 };
+        }
+        if (args.behavior !== "allow" && args.behavior !== "deny") {
+            return { claimed: true, state: "invalid", error: "Profile confirmations must be confirmed or cancelled", status: 400 };
+        }
+        if (payload.botId !== args.botId || payload.threadId !== args.threadId) {
+            return { claimed: true, state: "invalid", error: "This profile request belongs to another conversation", status: 403 };
+        }
+        if (card.answered)
+            return { claimed: true, state: "already_settled", behavior: card.answered };
+        try {
+            const target = this.store.bot(payload.targetBotId);
+            // The profile and receipt share one durable write. If saving the card
+            // failed afterward, a retry only settles it; it never reapplies fields.
+            if (target?.lastProfileRequestId === payload.requestId) {
+                const settled = this.store.patchMessage(args.threadId, message.id, {
+                    card: { ...card, answered: "allow", held: undefined, profileRequest: { ...payload, appliedAt: payload.appliedAt ?? this.now() } },
+                });
+                if (!settled)
+                    throw new ProfileRequestError("This profile confirmation card is no longer available", 409);
+                return { claimed: true, state: "already_settled", behavior: "allow" };
+            }
+            if (args.behavior === "deny") {
+                this.store.patchMessage(args.threadId, message.id, { card: { ...card, answered: "deny", held: undefined } });
+                return { claimed: true, state: "denied" };
+            }
+            if (!target)
+                throw new ProfileRequestError(NO_SUCH_BOT, 404);
+            const crossBot = payload.targetBotId !== payload.botId;
+            if (crossBot && this.validateTarget) {
+                const refusal = this.validateTarget(payload.botId, payload.targetBotId);
+                if (refusal)
+                    throw new ProfileRequestError(refusal, 404);
+            }
+            if (profileRevision(target) !== payload.expectedRevision) {
+                throw new ProfileRequestError(STALE, 409);
+            }
+            const { cwd, ...rest } = payload.changes;
+            const validated = Object.keys(rest).length ? parseChanges(rest) : {};
+            const patch = { ...validated, lastProfileRequestId: payload.requestId };
+            if (cwd !== undefined) {
+                // Re-checked at confirm: a card can sit open for days and the folder
+                // may be gone by then. 409 like the stale case — the card is no longer
+                // applicable as prepared.
+                const checked = validateBotCwd(cwd || null);
+                if (!checked.ok)
+                    throw new ProfileRequestError(checked.error, 409);
+                patch.cwd = checked.cwd ?? undefined;
+            }
+            if (!this.store.patchBotProfile(target.id, patch))
+                throw new ProfileRequestError(NO_SUCH_BOT, 404);
+            recordProfileChange(target.id, "bot", `card:${message.id}`, payload.before, payload.changes);
+            const appliedAt = this.now();
+            const settled = this.store.patchMessage(args.threadId, message.id, {
+                card: { ...card, answered: "allow", held: undefined, profileRequest: { ...payload, appliedAt } },
+            });
+            if (!settled)
+                throw new ProfileRequestError("This profile confirmation card is no longer available", 409);
+            const fields = PROFILE_REQUEST_FIELDS.filter((field) => payload.changes[field] !== undefined);
+            return { claimed: true, state: "applied", targetBotId: target.id, fields };
+        }
+        catch (error) {
+            const status = error instanceof ProfileRequestError ? error.status : 400;
+            const detail = error instanceof Error ? error.message : String(error);
+            const saved = this.store.bot(payload.targetBotId)?.lastProfileRequestId === payload.requestId;
+            const notice = "Profile saved. Confirm again to finish recording this decision; the changes will not be applied again.";
+            try {
+                this.store.patchMessage(args.threadId, message.id, {
+                    card: { ...card, held: saved ? notice : redactSecretsInText(detail).slice(0, 500) },
+                });
+            }
+            catch { /* The durable profile receipt still permits a safe retry. */ }
+            if (saved)
+                return {
+                    claimed: true, state: "applied", targetBotId: payload.targetBotId,
+                    fields: PROFILE_REQUEST_FIELDS.filter((field) => payload.changes[field] !== undefined),
+                    settlementPending: true, message: notice,
+                };
+            return { claimed: true, state: "invalid", error: detail, status };
+        }
+    }
+}

package/dist-server/server/profile-revision.js

@@ -0,0 +1,15 @@
+// The revision token a profile card pins to. It covers exactly the
+// fields a bot may propose (PROFILE_REQUEST_FIELDS), so a confirmation fails closed if any of them
+// moved between the card and the click — the profile analogue of a
+// routine's expectedUpdatedAt (bots have no updatedAt of their own).
+import { createHash } from "node:crypto";
+export function profileSnapshot(bot) {
+    return { name: bot.name, title: bot.title, description: bot.description, soul: bot.soul ?? "", cwd: bot.cwd ?? "" };
+}
+export function profileRevision(bot) {
+    // A later proposal can restore identical text. Keep its private receipt
+    // in the opaque revision so an older, interrupted card cannot apply twice.
+    return createHash("sha256")
+        .update(JSON.stringify({ ...profileSnapshot(bot), lastProfileRequestId: bot.lastProfileRequestId ?? "" }), "utf8")
+        .digest("hex");
+}

package/dist-server/server/profile-versions.js

@@ -0,0 +1,154 @@
+// Per-bot profile history: an append-only NDJSON file in the bot folder,
+// one row per changed field. Same discipline as decision-log.ts — 0600,
+// through redactSecrets, serialized per file, fire-and-forget — because a
+// history write must never fail the change it records. Full before/after
+// text is kept only for the soul; redacted versions cannot be restored
+// exactly and are not rollback targets. Other fields keep short one-liners.
+import { appendFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { PROFILE_REQUEST_FIELDS } from "../shared/profile-request.js";
+import { botFolder } from "./bot-folder.js";
+import { redactSecrets } from "./redact.js";
+const FILE_NAME = "history.ndjson";
+const ONE_LINER = 200;
+const MAX_HISTORY_READ_BYTES = 8 * 1024 * 1024;
+const writeQueues = new Map();
+export function historyFile(botId) {
+    return join(botFolder(botId), FILE_NAME);
+}
+function oneLiner(value) {
+    return value.replace(/\s+/g, " ").trim().slice(0, ONE_LINER);
+}
+function rowFor(field, at, actor, via, before, after) {
+    if (field === "soul") {
+        const b = Buffer.byteLength(before, "utf8");
+        const a = Buffer.byteLength(after, "utf8");
+        return { id: randomUUID(), at, actor, via, field, summary: `soul: ${b} → ${a} bytes`, before, after };
+    }
+    const b = oneLiner(before);
+    const a = oneLiner(after);
+    return { id: randomUUID(), at, actor, via, field, summary: `${field}: ${JSON.stringify(b)} → ${JSON.stringify(a)}`, before: b, after: a };
+}
+function withRestoreEligibility(row) {
+    const redacted = redactSecrets(row);
+    const canRestore = row.field === "soul" && typeof row.before === "string" &&
+        row.canRestore !== false && row.before === redacted.before &&
+        !/«redacted \d+ chars»/.test(row.before);
+    return {
+        ...redacted,
+        canRestore,
+        restoreUnavailableReason: row.field === "soul" && !canRestore
+            ? "This version is missing exact text or contains redacted sensitive text and cannot be restored."
+            : undefined,
+    };
+}
+async function writeRows(botId, rows) {
+    // A bot's folder is created when the bot is (writeSoulMirror on bot
+    // creation), so a real change always finds it there. If it is gone, the
+    // bot was deleted between the change firing and this write landing —
+    // skip rather than recreate a folder for a bot that no longer exists.
+    if (!existsSync(botFolder(botId)))
+        return;
+    const file = historyFile(botId);
+    mkdirSync(botFolder(botId), { recursive: true, mode: 0o700 });
+    const text = rows.map((row) => JSON.stringify(withRestoreEligibility(row))).join("\n") + "\n";
+    await appendFile(file, text, { mode: 0o600 });
+}
+/** Record every field that differs between `before` and `after`. */
+export function recordProfileChange(botId, actor, via, before, after) {
+    const at = Date.now();
+    const rows = [];
+    for (const field of PROFILE_REQUEST_FIELDS) {
+        const b = before[field] ?? "";
+        const a = after[field] ?? "";
+        if (b !== a)
+            rows.push(rowFor(field, at, actor, via, b, a));
+    }
+    if (!rows.length)
+        return;
+    const previous = writeQueues.get(botId) ?? Promise.resolve();
+    const queued = previous.then(() => writeRows(botId, rows)).catch(() => {
+        /* history must never take down the change it records */
+    });
+    writeQueues.set(botId, queued);
+    void queued.finally(() => {
+        if (writeQueues.get(botId) === queued)
+            writeQueues.delete(botId);
+    });
+}
+/** Test/shutdown seam. */
+export async function flushProfileHistory(botId) {
+    await writeQueues.get(botId);
+}
+/** Shutdown seam for every bot at once: awaits whatever is currently
+ * queued, so a history write in flight when the process stops still lands
+ * before it exits. Each queued promise already swallows its own error
+ * (`writeRows` must never take down the change it records), so this never
+ * rejects either. */
+export async function flushAllProfileHistory() {
+    await Promise.allSettled(writeQueues.values());
+}
+const isRow = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.at === "number" &&
+    typeof value.field === "string" &&
+    typeof value.actor === "string";
+/** Newest first, bounded to 500 rows from the newest 8 MiB. The append-only
+ * log keeps older changes without making every settings read load them. */
+export function readHistory(botId, limit = 100) {
+    let text;
+    let offset;
+    let end;
+    try {
+        const fd = openSync(historyFile(botId), "r");
+        try {
+            const size = fstatSync(fd).size;
+            offset = Math.max(0, size - MAX_HISTORY_READ_BYTES);
+            const buffer = Buffer.alloc(size - offset);
+            let length = 0;
+            while (length < buffer.length) {
+                const count = readSync(fd, buffer, length, buffer.length - length, offset + length);
+                if (!count)
+                    break;
+                length += count;
+            }
+            end = offset + length;
+            text = buffer.subarray(0, length).toString("utf8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    const lines = text.split("\n");
+    const maxRows = Math.min(500, Math.max(1, limit));
+    for (let index = lines.length - 1; index >= (offset > 0 ? 1 : 0) && rows.length < maxRows; index--) {
+        const line = lines[index];
+        end -= Buffer.byteLength(line, "utf8") + (index < lines.length - 1 ? 1 : 0);
+        if (!line)
+            continue;
+        try {
+            const value = JSON.parse(line);
+            if (isRow(value)) {
+                // Old logs had only millisecond timestamps (not unique). Their
+                // append-only byte position gives each legacy entry a stable id,
+                // even as the bounded read window moves after later appends.
+                const id = typeof value.id === "string" && value.id
+                    ? value.id
+                    : `legacy-${createHash("sha256").update(`${end}:${line}`).digest("hex")}`;
+                // Recheck old logs too: they predate eligibility metadata and may
+                // already contain irreversible redaction markers in the before-text.
+                rows.push(withRestoreEligibility({ ...value, id }));
+            }
+        }
+        catch {
+            /* torn line — skip */
+        }
+    }
+    return rows;
+}