@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/turn-notice.d.ts

@@ -0,0 +1,154 @@
+/** Sentinel model the CLI stamps on its synthetic placeholder turns. Mirrors
+ *  `@herdctl/chat`'s `SYNTHETIC_MODEL` (kept local to avoid a value import churn). */
+export declare const SYNTHETIC_MODEL = "<synthetic>";
+/** The three notice families a dead-ended turn resolves to. */
+export type TurnNoticeKind = "usage_limit" | "error" | "max_turns";
+/**
+ * A surfaced turn-ending condition. `message` is the one-line human summary the
+ * banner shows; `resetTime` (usage-limit only) is the parsed "resets …" clause;
+ * `retryable` says whether offering a Continue/Retry affordance is safe (a usage
+ * limit is NOT retryable — it only clears when the quota resets).
+ */
+export interface TurnNotice {
+    kind: TurnNoticeKind;
+    message: string;
+    /** Usage-limit only: the reset clause, e.g. `"7:10pm (America/New_York)"`. */
+    resetTime?: string;
+    /** Optional secondary detail (e.g. the raw SDK error subtype / message). */
+    detail?: string;
+    /** Whether a Continue/Retry affordance is safe to offer for this notice. */
+    retryable: boolean;
+}
+/** Loosely-typed shape of the fields we read off an SDK message / JSONL entry. */
+interface RawMessage {
+    type?: string;
+    subtype?: string;
+    is_error?: boolean;
+    success?: boolean;
+    message?: {
+        role?: string;
+        model?: string;
+        content?: unknown;
+        stop_reason?: string;
+    };
+}
+/**
+ * Classify a synthetic assistant message's text.
+ *
+ * Returns a `usage_limit` {@link TurnNotice} for a "session/usage limit" message
+ * (with the reset clause parsed out), the sentinel `"declined"` for the
+ * runtime's own `"No response requested."` (and any other non-limit synthetic —
+ * a placeholder the UI should simply suppress, never render), or `null` for
+ * empty text.
+ */
+export declare function classifySyntheticText(text: string): TurnNotice | "declined" | null;
+/**
+ * Classify a terminal `type:"result"` SDK message. Returns an `error`/`max_turns`
+ * {@link TurnNotice} when the result marks a genuine failure, else `null` for a
+ * successful turn.
+ *
+ * The authoritative failure signal is the **subtype** — the SDK's error results
+ * always carry an `error_*` subtype (`error_during_execution`, `error_max_turns`,
+ * …) — or an explicit `success === false`. This mirrors `@herdctl/core`'s own
+ * success computation (`chatSession`: `subtype.startsWith("error") || success ===
+ * false`), so Paddock's banner never disagrees with herdctl about whether a turn
+ * failed.
+ *
+ * We DELIBERATELY do NOT treat `is_error === true` as a failure on its own
+ * (issue #329 regression): `SDKResultSuccess` is typed `is_error: boolean`, and
+ * the runtime stamps `is_error:true` (with `api_error_status`) on a
+ * `subtype:"success"` result when the turn RECOVERED from a transient mid-turn
+ * API error (e.g. "Connection closed mid-response") and still produced a normal
+ * reply. Reading that as a turn failure rendered a false "turn failed" banner
+ * directly beneath a perfectly good reply on essentially every session-mode turn.
+ * A genuine error always carries an `error_*` subtype, so nothing is lost.
+ */
+export declare function classifyResult(result: {
+    subtype?: string;
+    is_error?: boolean;
+    success?: boolean;
+}): TurnNotice | null;
+/** Build a plain `error` notice from a free-text turn-failure message (a thrown
+ *  error / a failed `chat:complete` that never reached a `result`). */
+export declare function errorNotice(message: string | undefined): TurnNotice;
+/**
+ * Classify one raw SDK/JSONL message. Surfaces a {@link TurnNotice} for a
+ * synthetic usage-limit assistant message or a terminal error result; returns
+ * `null` for everything else — ordinary output, a successful result, and every
+ * suppressed synthetic placeholder (`"No response requested."`).
+ */
+export declare function noticeFromMessage(m: RawMessage): TurnNotice | null;
+/**
+ * Did this streamed message emit REAL assistant prose — a non-synthetic assistant
+ * message carrying non-empty **text** content, regardless of `stop_reason`?
+ *
+ * The live paths (`ws.ts`) OR-accumulate this across every message of a turn (a
+ * per-turn `producedReply` flag) so a terminal error/`max_turns` result that
+ * arrives AFTER the turn already showed the user real prose does not paint a false
+ * "turn failed" banner beneath the answer (issues #380, #394). In session mode the
+ * SDK's terminal `result` frame — streamed live but never persisted — can carry an
+ * `error_*` subtype / `success:false` even though the turn produced a perfectly
+ * good reply; on reload the history path ({@link scanTranscriptNotice}) suppresses
+ * the dead-end via its "any real assistant text supersedes the notice" rule, and
+ * this predicate lets the live path apply the SAME rule.
+ *
+ * #394 — why this is TEXT-ANY-STOP_REASON, not text+`end_turn`. The original #380
+ * predicate required a SINGLE message with non-empty text AND `stop_reason:
+ * "end_turn"`. Long tool-driven turns break both halves: (a) the visible prose
+ * usually rides on a message that ALSO makes a tool call → `stop_reason:"tool_use"`
+ * (excluded by the old gate), and (b) the terminal `end_turn` message is frequently
+ * **thinking-only** (zero text). So `producedReply` never flipped true and the
+ * benign terminal error result was surfaced. Keying off ANY non-synthetic assistant
+ * text (across all of the turn's messages, no `stop_reason` gate) makes a
+ * text+`tool_use` message count and exactly matches `scanTranscriptNotice`, killing
+ * the live/history asymmetry.
+ *
+ * DELIBERATELY text-only (a bare `thinking` block does NOT count): this mirrors the
+ * history path — which clears only on real text — so a genuinely empty turn (no
+ * assistant text ANYWHERE, e.g. an `error_max_turns` that wrote nothing renderable)
+ * still surfaces its error notice.
+ */
+export declare function messageProducedReply(m: RawMessage): boolean;
+/**
+ * Should an already-classified {@link TurnNotice} be dropped because a complete
+ * reply already streamed this turn (issue #380)? An `error` / `max_turns`
+ * dead-end beneath a good answer is a false alarm — suppress it. A `usage_limit`
+ * is NOT suppressed: a session-limit stop is a real dead-end still worth showing
+ * even alongside text.
+ */
+export declare function suppressNoticeAfterReply(notice: TurnNotice, producedReply: boolean): boolean;
+/**
+ * Did this turn effectively succeed for the purposes of its post-turn side
+ * effects — the queue drain, the after-turn curation sweep, and the recovery
+ * watch (issue #404)?
+ *
+ * The raw `result.success` handed back by the drive is computed purely from the
+ * terminal `result` frame (`!error_* subtype && !success:false`). In session
+ * mode that frame routinely carries an `error_*` subtype / `success:false` even
+ * when a complete reply already streamed — the very asymmetry the #380/#394
+ * banner fix exists for. Gating side effects on the raw signal silently strands
+ * a queued follow-up (the flush that {@link drainQueue} owns never runs), skips
+ * the sweep, and drops the recovery arm.
+ *
+ * This is the side-effect twin of {@link suppressNoticeAfterReply}: both trust
+ * the same `producedReply` signal (a real assistant reply streamed this turn) to
+ * override a benign trailing failure. A turn is effectively successful when the
+ * raw signal says so OR a real reply was produced. A genuinely dead turn (no
+ * reply — a Stop, an up-front API error) keeps `false`, so its queue is held.
+ */
+export declare function turnEffectivelySucceeded(rawSuccess: boolean, producedReply: boolean): boolean;
+/**
+ * Scan a transcript JSONL file for a TRAILING dead-end notice to surface on
+ * reload (the history-hydration path). Only the synthetic usage-limit case is
+ * recoverable from history: `@herdctl/core` drops synthetic messages when it
+ * parses the transcript, and an `error_max_turns` turn writes NOTHING at all —
+ * so those are live-only.
+ *
+ * A usage-limit notice is surfaced only when it is the LAST thing that happened
+ * on the transcript: a later real assistant reply (a non-synthetic assistant
+ * message with text) means the chat recovered, so any earlier limit is cleared.
+ * Returns the trailing notice, or `null`. Never throws (a missing/unreadable
+ * file → `null`).
+ */
+export declare function scanTranscriptNotice(filePath: string): Promise<TurnNotice | null>;
+export {};

package/packages/server/dist/turn-notice.js

@@ -0,0 +1,271 @@
+/**
+ * Turn-notice classification (issue #329)
+ *
+ * A keeper turn can end without producing a normal assistant reply, and today
+ * those endings are INVISIBLE in the UI — the chat just looks dead. Two families:
+ *
+ *   1. A **synthetic** runtime message. The Claude Code CLI answers a turn it
+ *      cannot really run with an assistant message tagged `model:"<synthetic>"`
+ *      and `stop_reason:"stop_sequence"`. The most important one on this box is
+ *      the shared Max-plan quota: `"You've hit your session limit · resets …"`.
+ *      The interleaved `"No response requested."` placeholders are the runtime
+ *      declining its own follow-up turns under the limit. `@herdctl/chat`'s
+ *      translator DROPS every synthetic message (so no text ever streams), and
+ *      `@herdctl/core`'s history parser drops them too — hence the silent stop.
+ *
+ *   2. A terminal **error result**. The Claude Agent SDK ends a turn with a
+ *      `type:"result"` message whose `subtype`/`is_error` mark a failure:
+ *      `error_max_turns` (the turn hit its max-turns cap and wrote NOTHING
+ *      renderable to the transcript), `error_during_execution`, an API/overload
+ *      error, etc.
+ *
+ * This module turns either signal into a small {@link TurnNotice} DTO that the
+ * live path (`ws.ts` per-message inspection) and the history-hydration path
+ * (`scanTranscriptNotice`) both surface to the client as a distinct notice turn.
+ * Pure + unit-tested; no I/O except {@link scanTranscriptNotice}.
+ */
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+/** Sentinel model the CLI stamps on its synthetic placeholder turns. Mirrors
+ *  `@herdctl/chat`'s `SYNTHETIC_MODEL` (kept local to avoid a value import churn). */
+export const SYNTHETIC_MODEL = "<synthetic>";
+/** Flatten an assistant `content` (string, or an array of text blocks) to text. */
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((b) => (b && typeof b === "object" && typeof b.text === "string"
+            ? b.text
+            : ""))
+            .join("");
+    }
+    return "";
+}
+/**
+ * Classify a synthetic assistant message's text.
+ *
+ * Returns a `usage_limit` {@link TurnNotice} for a "session/usage limit" message
+ * (with the reset clause parsed out), the sentinel `"declined"` for the
+ * runtime's own `"No response requested."` (and any other non-limit synthetic —
+ * a placeholder the UI should simply suppress, never render), or `null` for
+ * empty text.
+ */
+export function classifySyntheticText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    // The shared Max-plan quota. Match on "session limit" / "usage limit" rather
+    // than the exact string so a reworded CLI message still surfaces.
+    if (/\b(session|usage) limit\b/i.test(trimmed) || /hit your .*limit/i.test(trimmed)) {
+        const resetTime = /resets?\s+(.+?)\s*$/i.exec(trimmed)?.[1]?.trim() || undefined;
+        return {
+            kind: "usage_limit",
+            message: trimmed,
+            ...(resetTime ? { resetTime } : {}),
+            retryable: false,
+        };
+    }
+    // "No response requested." and any other synthetic placeholder: not a limit,
+    // carries no real output — suppress it (never a chat bubble).
+    return "declined";
+}
+/** Human-readable message for a terminal error `result`'s subtype. */
+function errorMessageForSubtype(subtype) {
+    if (subtype === "error_max_turns") {
+        return {
+            kind: "max_turns",
+            message: "Claude reached its turn limit before finishing this turn.",
+        };
+    }
+    return {
+        kind: "error",
+        message: "Claude's turn failed before producing a reply.",
+    };
+}
+/**
+ * Classify a terminal `type:"result"` SDK message. Returns an `error`/`max_turns`
+ * {@link TurnNotice} when the result marks a genuine failure, else `null` for a
+ * successful turn.
+ *
+ * The authoritative failure signal is the **subtype** — the SDK's error results
+ * always carry an `error_*` subtype (`error_during_execution`, `error_max_turns`,
+ * …) — or an explicit `success === false`. This mirrors `@herdctl/core`'s own
+ * success computation (`chatSession`: `subtype.startsWith("error") || success ===
+ * false`), so Paddock's banner never disagrees with herdctl about whether a turn
+ * failed.
+ *
+ * We DELIBERATELY do NOT treat `is_error === true` as a failure on its own
+ * (issue #329 regression): `SDKResultSuccess` is typed `is_error: boolean`, and
+ * the runtime stamps `is_error:true` (with `api_error_status`) on a
+ * `subtype:"success"` result when the turn RECOVERED from a transient mid-turn
+ * API error (e.g. "Connection closed mid-response") and still produced a normal
+ * reply. Reading that as a turn failure rendered a false "turn failed" banner
+ * directly beneath a perfectly good reply on essentially every session-mode turn.
+ * A genuine error always carries an `error_*` subtype, so nothing is lost.
+ */
+export function classifyResult(result) {
+    const subtype = typeof result.subtype === "string" ? result.subtype : undefined;
+    // A `subtype:"success"` result is a completed turn, full stop. `is_error` only
+    // counts as a failure when the runtime gave us NO subtype at all (defensive:
+    // some other runtime shape that reports is_error without one).
+    const failed = (subtype !== undefined && subtype.startsWith("error")) ||
+        result.success === false ||
+        (subtype === undefined && result.is_error === true);
+    if (!failed)
+        return null;
+    const { kind, message } = errorMessageForSubtype(subtype);
+    return {
+        kind,
+        message,
+        ...(subtype ? { detail: subtype } : {}),
+        retryable: true,
+    };
+}
+/** Build a plain `error` notice from a free-text turn-failure message (a thrown
+ *  error / a failed `chat:complete` that never reached a `result`). */
+export function errorNotice(message) {
+    const detail = message?.trim();
+    return {
+        kind: "error",
+        message: "Claude's turn failed before producing a reply.",
+        ...(detail ? { detail } : {}),
+        retryable: true,
+    };
+}
+/**
+ * Classify one raw SDK/JSONL message. Surfaces a {@link TurnNotice} for a
+ * synthetic usage-limit assistant message or a terminal error result; returns
+ * `null` for everything else — ordinary output, a successful result, and every
+ * suppressed synthetic placeholder (`"No response requested."`).
+ */
+export function noticeFromMessage(m) {
+    if (m.type === "assistant" && m.message?.model === SYNTHETIC_MODEL) {
+        const r = classifySyntheticText(contentText(m.message?.content));
+        return r && r !== "declined" ? r : null;
+    }
+    if (m.type === "result") {
+        return classifyResult(m);
+    }
+    return null;
+}
+/**
+ * Did this streamed message emit REAL assistant prose — a non-synthetic assistant
+ * message carrying non-empty **text** content, regardless of `stop_reason`?
+ *
+ * The live paths (`ws.ts`) OR-accumulate this across every message of a turn (a
+ * per-turn `producedReply` flag) so a terminal error/`max_turns` result that
+ * arrives AFTER the turn already showed the user real prose does not paint a false
+ * "turn failed" banner beneath the answer (issues #380, #394). In session mode the
+ * SDK's terminal `result` frame — streamed live but never persisted — can carry an
+ * `error_*` subtype / `success:false` even though the turn produced a perfectly
+ * good reply; on reload the history path ({@link scanTranscriptNotice}) suppresses
+ * the dead-end via its "any real assistant text supersedes the notice" rule, and
+ * this predicate lets the live path apply the SAME rule.
+ *
+ * #394 — why this is TEXT-ANY-STOP_REASON, not text+`end_turn`. The original #380
+ * predicate required a SINGLE message with non-empty text AND `stop_reason:
+ * "end_turn"`. Long tool-driven turns break both halves: (a) the visible prose
+ * usually rides on a message that ALSO makes a tool call → `stop_reason:"tool_use"`
+ * (excluded by the old gate), and (b) the terminal `end_turn` message is frequently
+ * **thinking-only** (zero text). So `producedReply` never flipped true and the
+ * benign terminal error result was surfaced. Keying off ANY non-synthetic assistant
+ * text (across all of the turn's messages, no `stop_reason` gate) makes a
+ * text+`tool_use` message count and exactly matches `scanTranscriptNotice`, killing
+ * the live/history asymmetry.
+ *
+ * DELIBERATELY text-only (a bare `thinking` block does NOT count): this mirrors the
+ * history path — which clears only on real text — so a genuinely empty turn (no
+ * assistant text ANYWHERE, e.g. an `error_max_turns` that wrote nothing renderable)
+ * still surfaces its error notice.
+ */
+export function messageProducedReply(m) {
+    if (m.type !== "assistant")
+        return false;
+    if (m.message?.model === SYNTHETIC_MODEL)
+        return false;
+    return contentText(m.message?.content).trim().length > 0;
+}
+/**
+ * Should an already-classified {@link TurnNotice} be dropped because a complete
+ * reply already streamed this turn (issue #380)? An `error` / `max_turns`
+ * dead-end beneath a good answer is a false alarm — suppress it. A `usage_limit`
+ * is NOT suppressed: a session-limit stop is a real dead-end still worth showing
+ * even alongside text.
+ */
+export function suppressNoticeAfterReply(notice, producedReply) {
+    return producedReply && (notice.kind === "error" || notice.kind === "max_turns");
+}
+/**
+ * Did this turn effectively succeed for the purposes of its post-turn side
+ * effects — the queue drain, the after-turn curation sweep, and the recovery
+ * watch (issue #404)?
+ *
+ * The raw `result.success` handed back by the drive is computed purely from the
+ * terminal `result` frame (`!error_* subtype && !success:false`). In session
+ * mode that frame routinely carries an `error_*` subtype / `success:false` even
+ * when a complete reply already streamed — the very asymmetry the #380/#394
+ * banner fix exists for. Gating side effects on the raw signal silently strands
+ * a queued follow-up (the flush that {@link drainQueue} owns never runs), skips
+ * the sweep, and drops the recovery arm.
+ *
+ * This is the side-effect twin of {@link suppressNoticeAfterReply}: both trust
+ * the same `producedReply` signal (a real assistant reply streamed this turn) to
+ * override a benign trailing failure. A turn is effectively successful when the
+ * raw signal says so OR a real reply was produced. A genuinely dead turn (no
+ * reply — a Stop, an up-front API error) keeps `false`, so its queue is held.
+ */
+export function turnEffectivelySucceeded(rawSuccess, producedReply) {
+    return rawSuccess || producedReply;
+}
+/**
+ * Scan a transcript JSONL file for a TRAILING dead-end notice to surface on
+ * reload (the history-hydration path). Only the synthetic usage-limit case is
+ * recoverable from history: `@herdctl/core` drops synthetic messages when it
+ * parses the transcript, and an `error_max_turns` turn writes NOTHING at all —
+ * so those are live-only.
+ *
+ * A usage-limit notice is surfaced only when it is the LAST thing that happened
+ * on the transcript: a later real assistant reply (a non-synthetic assistant
+ * message with text) means the chat recovered, so any earlier limit is cleared.
+ * Returns the trailing notice, or `null`. Never throws (a missing/unreadable
+ * file → `null`).
+ */
+export async function scanTranscriptNotice(filePath) {
+    let pending = null;
+    try {
+        const rl = createInterface({
+            input: createReadStream(filePath, { encoding: "utf8" }),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (entry.type !== "assistant")
+                continue;
+            const model = entry.message?.model;
+            if (model === SYNTHETIC_MODEL) {
+                const r = classifySyntheticText(contentText(entry.message?.content));
+                if (r && r !== "declined")
+                    pending = r; // a usage-limit dead-end
+                // a "declined" placeholder neither sets nor clears the pending notice
+            }
+            else if (contentText(entry.message?.content).trim().length > 0) {
+                // A real assistant reply: the turn was actually answered → clear.
+                pending = null;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return pending;
+}

package/packages/server/dist/unread.d.ts

@@ -0,0 +1,36 @@
+export declare class UnreadStore {
+    private readonly stateFile;
+    /** In-memory set of manually-unread keys (loaded once, written through on change). */
+    private marked;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read — same
+     * lost-update guard as {@link StarStore} / {@link ReadStateStore}.
+     */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /**
+     * Whether this user has manually flagged this chat unread. Non-throwing: any
+     * load error reads as false. Pass `null` for `username` to read the shared bucket.
+     */
+    isUnread(username: string | null, agent: string, sessionId: string): Promise<boolean>;
+    /**
+     * Set (or clear) this user's manual-unread flag for this chat, persisting the
+     * change. Idempotent. Returns whether the flag actually CHANGED, mirroring
+     * `StarStore.setStarred`. Pass `null` for `username` to write the shared bucket.
+     */
+    setUnread(username: string | null, agent: string, sessionId: string, unread: boolean): Promise<boolean>;
+    /**
+     * Set (or clear) this user's manual-unread flag for MANY chats in ONE write
+     * (#508) — the subtree "mark read / mark unread" action. Same single-persist
+     * rationale as `ArchiveStore.setManyArchived`: a client-side loop over a
+     * 21-chat family can half-succeed and leave the family in two different states.
+     * Returns the ids whose flag actually changed.
+     */
+    setManyUnread(username: string | null, agent: string, sessionIds: readonly string[], unread: boolean): Promise<string[]>;
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    private persist;
+}

package/packages/server/dist/unread.js

@@ -0,0 +1,123 @@
+/**
+ * UnreadStore — a Paddock-side sidecar for the per-chat, per-user MANUAL "unread"
+ * override (#458).
+ *
+ * The unread affordance (#160) is normally DERIVED: a chat reads as unread when
+ * the agent finished a turn (`lastTurnCompletedAt`) more recently than the user
+ * last viewed it (`ReadStateStore` `lastSeen`). This store adds an explicit,
+ * user-driven override on top of that derivation: "mark this chat unread" so it
+ * resurfaces its cue the next time you come back to the list — the email-client
+ * pattern. It cannot be expressed by pushing `lastSeen` backwards, because that
+ * value is deliberately MONOTONIC (see {@link ReadStateStore}); it needs its own
+ * flag.
+ *
+ * Shape/pattern is a near-verbatim copy of {@link StarStore} — a tiny JSON
+ * sidecar in the data dir, write-through, serialised, corruption-tolerant, only
+ * storing the SET keys (an unread=false clears the key) so the file stays compact.
+ * The one difference is KEYING: like read-state (and unlike star/archive, which
+ * are shared) the override is PER USER — "I haven't dealt with this yet" is
+ * personal — so it reuses {@link keyOf} from read-state:
+ *   - Real identity (trusted-header / jwt): `username \0 agent \0 sessionId`
+ *   - No user (`none` mode / anonymous):     `agent \0 sessionId` (shared bucket)
+ *
+ * Written `0o600` (like read-state) — low-sensitivity personal metadata (which
+ * chats you flagged to revisit), but no reason for it to be world-readable.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { keyOf } from "./read-state.js";
+const STATE_FILE = "unread-state.json";
+export class UnreadStore {
+    stateFile;
+    /** In-memory set of manually-unread keys (loaded once, written through on change). */
+    marked = null;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read — same
+     * lost-update guard as {@link StarStore} / {@link ReadStateStore}.
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.marked)
+            return Promise.resolve(this.marked);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                let keys = [];
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed))
+                        keys = parsed.filter((k) => typeof k === "string");
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.marked = new Set(keys);
+                return this.marked;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /**
+     * Whether this user has manually flagged this chat unread. Non-throwing: any
+     * load error reads as false. Pass `null` for `username` to read the shared bucket.
+     */
+    async isUnread(username, agent, sessionId) {
+        const set = await this.ensureLoaded().catch(() => new Set());
+        return set.has(keyOf(username, agent, sessionId));
+    }
+    /**
+     * Set (or clear) this user's manual-unread flag for this chat, persisting the
+     * change. Idempotent. Returns whether the flag actually CHANGED, mirroring
+     * `StarStore.setStarred`. Pass `null` for `username` to write the shared bucket.
+     */
+    async setUnread(username, agent, sessionId, unread) {
+        const set = await this.ensureLoaded();
+        const key = keyOf(username, agent, sessionId);
+        if (unread === set.has(key))
+            return false; // no-op — avoid a needless write
+        if (unread)
+            set.add(key);
+        else
+            set.delete(key);
+        await this.persist(set);
+        return true;
+    }
+    /**
+     * Set (or clear) this user's manual-unread flag for MANY chats in ONE write
+     * (#508) — the subtree "mark read / mark unread" action. Same single-persist
+     * rationale as `ArchiveStore.setManyArchived`: a client-side loop over a
+     * 21-chat family can half-succeed and leave the family in two different states.
+     * Returns the ids whose flag actually changed.
+     */
+    async setManyUnread(username, agent, sessionIds, unread) {
+        const set = await this.ensureLoaded();
+        const changed = [];
+        for (const sessionId of sessionIds) {
+            const key = keyOf(username, agent, sessionId);
+            if (unread === set.has(key))
+                continue; // already in the target state
+            if (unread)
+                set.add(key);
+            else
+                set.delete(key);
+            changed.push(sessionId);
+        }
+        if (changed.length)
+            await this.persist(set);
+        return changed;
+    }
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    persist(set) {
+        this.writing = this.writing.then(async () => {
+            const json = JSON.stringify([...set], null, 2);
+            await fs.writeFile(this.stateFile, json, { encoding: "utf8", mode: 0o600 }).catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

package/packages/server/dist/usage.d.ts

@@ -0,0 +1,66 @@
+import type { TokenTotals } from "./models.js";
+/** A chat's context fill (last turn) plus its cumulative lifetime token totals. */
+export interface SessionTokenUsage {
+    /** True once at least one assistant turn carried a usage block. */
+    hasData: boolean;
+    /** Number of assistant turns (unique message ids) with usage. */
+    turnCount: number;
+    /**
+     * Context-window fill as of the last completed turn:
+     * `input + cache_read + cache_creation` of the final assistant message. This
+     * matches core's `SessionUsage.inputTokens` so the ring/meter math is unchanged.
+     */
+    contextTokens: number;
+    /** Cumulative uncached input tokens across every turn. */
+    inputTotal: number;
+    /** Cumulative output tokens across every turn. */
+    outputTotal: number;
+    /** Cumulative cache-read input tokens across every turn. */
+    cacheReadTotal: number;
+    /** Cumulative cache-creation (write) input tokens across every turn. */
+    cacheCreationTotal: number;
+    /**
+     * The same token totals split by the model that produced them (keyed by the
+     * `message.model` on each assistant turn). A chat can span models — the
+     * composer switches model per turn, and the running model may differ from the
+     * project default — so cost must be priced per-model, not at one blended rate.
+     * The flat `*Total` fields above stay model-agnostic for the token headline.
+     */
+    byModel: Record<string, TokenTotals>;
+}
+/**
+ * Stream a transcript file and accumulate cumulative token usage. Deduplicates
+ * assistant messages by `message.id` (keep-first) so repeated stream frames for
+ * one message are counted once. Returns {@link EMPTY} for a missing/unreadable
+ * file (parity with core, which returns a zeroed summary).
+ */
+export declare function readSessionTokenUsageFile(file: string): Promise<SessionTokenUsage>;
+/**
+ * Cumulative token usage for a chat, resolved from `<projectDir>/.chats/`.
+ * Memoized on the transcript's mtime. Returns {@link EMPTY} for an unsafe
+ * session id or a session with no transcript yet.
+ */
+export declare function readSessionTokenUsage(projectDir: string, sessionId: string): Promise<SessionTokenUsage>;
+/**
+ * Per-message context-window fill, keyed by the transcript record `uuid` that the
+ * messages DTO carries (issue #451). For every `type:"assistant"` record we store
+ * `input + cache_read + cache_creation` — the context-window fill at that turn.
+ *
+ * A single assistant message is written across several JSONL records (one per
+ * content block: text, tool_use, …), each with its own `uuid` but the SAME
+ * message-level `usage`, so keying by record `uuid` resolves any of a message's
+ * turn ids to the identical fill. Callers forward-fill the value across the
+ * non-assistant records between turns (user prompts, tool results) to answer
+ * "how full was the context as of this point" for every message.
+ *
+ * This is a SEPARATE pass from {@link readSessionTokenUsageFile} on purpose: it
+ * only runs on the open-chat messages path, never the chat-list rings, so the
+ * list DTO stays lean. It rides its own mtime cache below.
+ */
+export declare function readContextSeriesFile(file: string): Promise<Map<string, number>>;
+/**
+ * Per-message context series for a chat, resolved from `<projectDir>/.chats/`.
+ * Memoized on the transcript's mtime (parity with {@link readSessionTokenUsage}).
+ * Returns an empty map for an unsafe session id or a session with no transcript.
+ */
+export declare function readContextSeries(projectDir: string, sessionId: string): Promise<Map<string, number>>;