@sigrun/ext-curator 0.0.0-stage → 0.1.0

package/dist/notices.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The post-review notice (`src/notices.ts`, Task B5): what the user
+ * sees when a review changed something — ONE ambient record on the
+ * originating conversation (`curator.notice`, place `status`), one
+ * line per change (`Learned: <summary>`), with a `navigate` action to
+ * the curator view anchored at the review.
+ *
+ * The ambient seam is the ONLY carrier (the brief): a notice is never
+ * a transcript entry (a fork would replay it) and never a notifier or
+ * channel delivery (gateway channels get no notice by default, spec
+ * P8). Ambient records are display-only — no action route reaches
+ * them — so Undo lives on the curator VIEW; the notice's button just
+ * navigates there.
+ *
+ * The body must pass the server's own ambient validation (a `status`
+ * slot allows ONE line-level block, literal content only — ambient
+ * bodies carry no data document, so bindings are rejected): a single
+ * `callout` whose title joins the change lines and whose actions
+ * carry the navigate button. One line-level block per seam rule.
+ *
+ * DURABILITY: each notice is remembered in `notices.json` under the
+ * user's state dir (`readNotices` is the view's lookup) — an Undo
+ * after a restart still knows which conversation's ambient record to
+ * clear. The file is bounded: recording a notice replaces the entry
+ * of the SAME review id (a re-run of one review id is one notice) and
+ * the file keeps the newest 50 (matching the feed window the view
+ * shows — older notices have nothing left to undo once the feed rolls
+ * past them).
+ */
+import type { ConversationId } from "@earendil-works/pi-durable";
+import type { CurationRunResult, SigrunHost } from "@sigrun/sigrun/extension";
+import { CURATOR_NOTICE_KIND } from "./index.js";
+export { CURATOR_NOTICE_KIND };
+/** What one recorded notice remembers (the view's undo lookup). */
+export interface NoticeRecord {
+    /** The review the notice announced (the undo key). */
+    readonly reviewId: string;
+    /** The conversation whose ambient slot carries the notice. */
+    readonly conversationId: ConversationId;
+    /** When the notice was set (ISO). */
+    readonly at: string;
+}
+/**
+ * Announce one completed review: when the result carries changes, set
+ * the `curator.notice` ambient record on the conversation and record
+ * the notice durably. No changes → nothing (an unchanged conversation
+ * stays untouched). Answers the notice record (undefined when no
+ * notice was set).
+ */
+export declare function notify(host: SigrunHost, conversationId: ConversationId, user: string, result: CurationRunResult & {
+    readonly reviewId?: string;
+}): Promise<NoticeRecord | undefined>;
+/** Read the user's recorded notices (newest first); absent/malformed → []. */
+export declare function readNotices(host: SigrunHost, user: string): Promise<readonly NoticeRecord[]>;

package/dist/notices.js

@@ -0,0 +1,127 @@
+/**
+ * The post-review notice (`src/notices.ts`, Task B5): what the user
+ * sees when a review changed something — ONE ambient record on the
+ * originating conversation (`curator.notice`, place `status`), one
+ * line per change (`Learned: <summary>`), with a `navigate` action to
+ * the curator view anchored at the review.
+ *
+ * The ambient seam is the ONLY carrier (the brief): a notice is never
+ * a transcript entry (a fork would replay it) and never a notifier or
+ * channel delivery (gateway channels get no notice by default, spec
+ * P8). Ambient records are display-only — no action route reaches
+ * them — so Undo lives on the curator VIEW; the notice's button just
+ * navigates there.
+ *
+ * The body must pass the server's own ambient validation (a `status`
+ * slot allows ONE line-level block, literal content only — ambient
+ * bodies carry no data document, so bindings are rejected): a single
+ * `callout` whose title joins the change lines and whose actions
+ * carry the navigate button. One line-level block per seam rule.
+ *
+ * DURABILITY: each notice is remembered in `notices.json` under the
+ * user's state dir (`readNotices` is the view's lookup) — an Undo
+ * after a restart still knows which conversation's ambient record to
+ * clear. The file is bounded: recording a notice replaces the entry
+ * of the SAME review id (a re-run of one review id is one notice) and
+ * the file keeps the newest 50 (matching the feed window the view
+ * shows — older notices have nothing left to undo once the feed rolls
+ * past them).
+ */
+import { join } from "node:path";
+import { CURATOR_NOTICE_KIND } from "./index.js";
+export { CURATOR_NOTICE_KIND };
+/** The notice ledger's file name under the user's state dir. */
+const NOTICES_FILE = "notices.json";
+/** How many notices the ledger keeps (the view's feed window). */
+const NOTICE_LEDGER_MAX = 50;
+/** The zero-signal context the ambient write runs under (the review
+ *  body has no caller signal of its own — the run's deadline bound it). */
+const CONTEXT = { abortSignal: undefined };
+/**
+ * Announce one completed review: when the result carries changes, set
+ * the `curator.notice` ambient record on the conversation and record
+ * the notice durably. No changes → nothing (an unchanged conversation
+ * stays untouched). Answers the notice record (undefined when no
+ * notice was set).
+ */
+export async function notify(host, conversationId, user, result) {
+    if (result.status !== "completed")
+        return undefined;
+    if (result.changes.length === 0)
+        return undefined;
+    const reviewId = result.reviewId;
+    if (reviewId === undefined || reviewId === "")
+        return undefined;
+    const at = new Date().toISOString();
+    await host.setAmbient(conversationId, {
+        key: CURATOR_NOTICE_KIND,
+        place: "status",
+        body: noticeBody(result.changes.map((change) => change.summary), reviewId),
+    }, CONTEXT);
+    const record = { reviewId, conversationId, at };
+    await recordNotice(host, user, record);
+    return record;
+}
+/**
+ * The notice body: ONE line-level `callout` (the `status` slot's
+ * one-line rule) whose title joins the change summaries and whose
+ * actions navigate to the curator view anchored at the review.
+ */
+function noticeBody(summaries, reviewId) {
+    const lines = summaries.map((summary) => `Learned: ${summary}`);
+    return {
+        v: 1,
+        root: {
+            type: "callout",
+            id: "curator-notice",
+            tone: "neutral",
+            // The one-line rule makes the title the line the channels show;
+            // multiple changes join on the same line (a statusline slot).
+            title: lines.join(" · "),
+            body: "Open the curator view to review or undo.",
+            actions: [
+                {
+                    id: "open",
+                    label: "Curator",
+                    icon: "book",
+                    action: {
+                        type: "navigate",
+                        target: {
+                            view: {
+                                extension: "curator",
+                                id: "curator",
+                                params: { review: reviewId },
+                            },
+                        },
+                    },
+                },
+            ],
+        },
+    };
+}
+/** The ledger file path for one user. */
+function noticesFile(host, user) {
+    return join(host.stores.user(user).paths.state, NOTICES_FILE);
+}
+/** Read the user's recorded notices (newest first); absent/malformed → []. */
+export async function readNotices(host, user) {
+    const { readStateJson } = await import("./queue.js");
+    const parsed = await readStateJson(noticesFile(host, user), []);
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter((entry) => typeof entry === "object" &&
+        entry !== null &&
+        typeof entry.reviewId === "string" &&
+        typeof entry.conversationId === "number" &&
+        typeof entry.at === "string");
+}
+/** Record one notice: replace the same review's entry, keep the newest 50. */
+async function recordNotice(host, user, record) {
+    const { writeStateJson } = await import("./queue.js");
+    const current = await readNotices(host, user);
+    const next = [
+        record,
+        ...current.filter((entry) => entry.reviewId !== record.reviewId),
+    ].slice(0, NOTICE_LEDGER_MAX);
+    await writeStateJson(host.stores.user(user).paths.state, NOTICES_FILE, next);
+}

package/dist/prompts.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The review prompt (`src/prompts.ts`, Task B2): what a fork review or
+ * digest review submits as its only input. The fork carries the
+ * parent's transcript, so the instruction is the reviewer's brief, not
+ * the material.
+ *
+ * The CONTENT is spec §6.2's review-prompt requirements (the wording is
+ * ours; the snapshot test pins it once written):
+ *
+ * - what a skill is — a procedure for a repeatable class of task, for
+ *   this user; pitfalls as a rule plus one clause of why; no incident
+ *   narration, dates, PR numbers or quoted chatter;
+ * - the do-not-capture list — environment failures, negative claims
+ *   about tools, transient errors, unresolved failures presented as
+ *   workflows, one-off tasks, codebase facts (the repo's AGENTS.md),
+ *   secrets, and personal facts (a memory target when one is offered);
+ * - the routing rule — each lesson goes in exactly one place: one
+ *   skill, one overlay, or one target;
+ * - update the skill in play before creating one; class-level names;
+ * - "Nothing to save" is a valid outcome;
+ * - never store another participant's words;
+ * - the hint arguments and exactly the allowed tools.
+ *
+ * Loop 2's digest reviews reuse this instruction verbatim (Task B4).
+ */
+import type { CurationHint } from "@sigrun/sigrun/extension";
+/** What `reviewInstruction` needs (the brief's exact shape). */
+export interface ReviewInstructionOpts {
+    /** Owner write attempts the review folds in (empty: none pending). */
+    readonly hints: readonly CurationHint[];
+    /** Curation targets offered to this run, with their guidance. */
+    readonly targets: readonly {
+        readonly id: string;
+        readonly guidance: readonly string[];
+    }[];
+    /** The run's allow list — the instruction names these and no others. */
+    readonly allow: readonly string[];
+    /** `/learn`'s optional focus, riding along when given. */
+    readonly focus?: string;
+}
+/**
+ * Build the review instruction (the run's only input). Deterministic:
+ * fixed inputs produce the fixed text the snapshot pins.
+ */
+export declare function reviewInstruction(opts: ReviewInstructionOpts): string;

package/dist/prompts.js

@@ -0,0 +1,57 @@
+/**
+ * The review prompt (`src/prompts.ts`, Task B2): what a fork review or
+ * digest review submits as its only input. The fork carries the
+ * parent's transcript, so the instruction is the reviewer's brief, not
+ * the material.
+ *
+ * The CONTENT is spec §6.2's review-prompt requirements (the wording is
+ * ours; the snapshot test pins it once written):
+ *
+ * - what a skill is — a procedure for a repeatable class of task, for
+ *   this user; pitfalls as a rule plus one clause of why; no incident
+ *   narration, dates, PR numbers or quoted chatter;
+ * - the do-not-capture list — environment failures, negative claims
+ *   about tools, transient errors, unresolved failures presented as
+ *   workflows, one-off tasks, codebase facts (the repo's AGENTS.md),
+ *   secrets, and personal facts (a memory target when one is offered);
+ * - the routing rule — each lesson goes in exactly one place: one
+ *   skill, one overlay, or one target;
+ * - update the skill in play before creating one; class-level names;
+ * - "Nothing to save" is a valid outcome;
+ * - never store another participant's words;
+ * - the hint arguments and exactly the allowed tools.
+ *
+ * Loop 2's digest reviews reuse this instruction verbatim (Task B4).
+ */
+/**
+ * Build the review instruction (the run's only input). Deterministic:
+ * fixed inputs produce the fixed text the snapshot pins.
+ */
+export function reviewInstruction(opts) {
+    const lines = [
+        "You are the curator. Review the conversation above and distill durable lessons for this user.",
+    ];
+    if (opts.focus !== undefined) {
+        lines.push(`Focus: ${opts.focus}.`);
+    }
+    lines.push("", "A skill is a procedure for a repeatable class of task, for this user. State pitfalls as a rule plus one clause of why. No incident narration, no dates, no PR numbers, no quoted chatter.", "", "Do NOT capture: environment failures; negative claims about tools; transient errors; unresolved failures presented as workflows; one-off tasks; codebase facts (those belong in the repo's AGENTS.md); secrets; personal facts (those go to the memory target when one is offered). Never store another participant's words.", "", "Each lesson goes in exactly one place: one skill, one overlay, or one target. Update the skill in play before creating one; pick class-level names.", "", '"Nothing to save" is a valid outcome — when nothing qualifies, finish with that sentence and change nothing.');
+    if (opts.targets.length > 0) {
+        lines.push("", "Targets:");
+        for (const target of opts.targets) {
+            for (const line of target.guidance) {
+                lines.push(`- ${target.id}: ${line}`);
+            }
+            if (target.guidance.length === 0) {
+                lines.push(`- ${target.id}.`);
+            }
+        }
+    }
+    if (opts.hints.length > 0) {
+        lines.push("", "The user made these write attempts between reviews — fold their intent in:");
+        for (const [index, hint] of opts.hints.entries()) {
+            lines.push(`${index + 1}. ${hint.tool} ${JSON.stringify(hint.args)} at ${hint.at}`);
+        }
+    }
+    lines.push("", `Your tools: ${opts.allow.join(", ")}. Nothing else.`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/queue.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The review queues (`src/queue.ts`, Task B2):
+ *
+ * - `ReviewQueue` — one in-flight review PER USER, FIFO per user (a
+ *   burst of settles on one user's conversations reviews in order,
+ *   never concurrently; two users never serialize against each other).
+ *   `onRunSettled` enqueues and returns; the queue owns the run. The
+ *   auto-namer's pattern: a per-key promise chain, `idle()` for tests.
+ * - `queueDigest` — the mixed-conversation spill: loop 1 never forks a
+ *   shared conversation, it appends the id to the per-user
+ *   `digest-queue.json` (state), and loop 2's digest step (Task B4)
+ *   consumes the list. Dedup by conversation id — one pending entry per
+ *   conversation, however many runs triggered it — with the taken
+ *   hints merged into the entry (the decision took them read-and-clear;
+ *   the digest run folds them into its instruction).
+ * - the refunded-hints file (`pending-hints.json`) — the fix for the
+ *   dropped-hints bug: `takeHints` is read-and-clear, so a review that
+ *   ends failed / cancelled / deadline would otherwise lose its hints
+ *   for good. Non-completed reviews write them back (refund, merged by
+ *   hint id); the decision merges a conversation's refunded batch into
+ *   every fresh take; a COMPLETED review (or a digest entry that takes
+ *   ownership) clears the ids it consumed. The transfer is deliberately
+ *   at-least-once: a crash between refund and clear duplicates a hint
+ *   (dedup absorbs it), never drops one.
+ *
+ * Errors never break a chain: the queue's contract is that a job's
+ * failure is the job's business (the loop records it); the chain keeps
+ * draining.
+ *
+ * Every hints helper here dedups by hint id: a hint may briefly live in
+ * two places (host + refund file, refund file + digest entry) around a
+ * crash, and dedup makes the overlap harmless.
+ */
+import type { SigrunHost, CurationHint } from "@sigrun/sigrun/extension";
+import type { ConversationId } from "@earendil-works/pi-durable";
+/** One queued review: the user it belongs to, and the work. */
+export interface ReviewJob {
+    /** The reviewed user — the one-in-flight key. */
+    readonly user: string;
+    /** The review body; must not throw (record failures inside). */
+    readonly work: () => Promise<void>;
+}
+/**
+ * The per-user FIFO review queue. `enqueue` never runs the work on the
+ * caller's stack — it appends to the user's chain; `idle()` resolves
+ * when NO user has work in flight or queued.
+ */
+export declare class ReviewQueue {
+    /** One promise chain per user (the FIFO + the one-in-flight rule). */
+    private readonly chains;
+    /** Jobs not yet finished, across every user (the `idle()` counter). */
+    private pending;
+    /** Every live `idle()` waiter, released together at drain. */
+    private waiters;
+    /** Append one job to its user's chain. */
+    enqueue(job: ReviewJob): void;
+    /**
+     * Resolve when every enqueued job has finished (immediately when
+     * the queue is empty). Tests await this; production never does.
+     */
+    idle(): Promise<void>;
+}
+/**
+ * Read one JSON state file with a fallback: absent or malformed → the
+ * fallback value (state files are the loop's own bookkeeping — a bad
+ * file degrades to defaults, never a broken loop).
+ */
+export declare function readStateJson<T>(file: string, fallback: T): Promise<T>;
+/** Write one JSON state file under the user's state dir (tab indents). */
+export declare function writeStateJson<T>(stateDir: string, name: string, value: T): Promise<void>;
+/** The digest-queue file: pending mixed conversations, deduped by id. */
+export interface DigestQueueFile {
+    readonly conversations: readonly DigestQueueEntry[];
+}
+/** One pending digest: the conversation, with the hints it triggered on. */
+export interface DigestQueueEntry {
+    readonly id: ConversationId;
+    readonly hints: readonly CurationHint[];
+}
+/** Read the digest queue's entries for one user; absent/malformed → []. */
+export declare function readDigestQueue(host: SigrunHost, user: string): Promise<readonly DigestQueueEntry[]>;
+/** Overwrite the digest queue's entries (the digest step's write-back). */
+export declare function writeDigestQueue(host: SigrunHost, user: string, conversations: readonly DigestQueueEntry[]): Promise<void>;
+/**
+ * Remove one conversation's digest entry (the digest step, after the
+ * review completed and took ownership of its hints). Idempotent.
+ */
+export declare function removeDigestEntry(host: SigrunHost, user: string, conversationId: ConversationId): Promise<void>;
+/**
+ * Queue one conversation for loop 2's digest (Task B4 consumes): append
+ * to `digest-queue.json` under the user's state dir, dedup by id, the
+ * taken hints merged into the existing entry by hint id (never dropped).
+ */
+export declare function queueDigest(host: SigrunHost, user: string, conversationId: ConversationId, hints?: readonly CurationHint[]): Promise<void>;
+/** Merge two hint batches into one, deduped by hint id. */
+export declare function mergeHints(first: readonly CurationHint[], second: readonly CurationHint[]): readonly CurationHint[];
+/** The hints refunded for one conversation (a read; nothing is cleared). */
+export declare function pendingHintsFor(host: SigrunHost, user: string, conversationId: ConversationId): Promise<readonly CurationHint[]>;
+/**
+ * Refund: write a non-completed review's hints back, merged into the
+ * conversation's refunded batch by hint id (never dropped, never
+ * duplicated — an unchanged entry is not rewritten).
+ */
+export declare function refundHints(host: SigrunHost, user: string, conversationId: ConversationId, hints: readonly CurationHint[]): Promise<void>;
+/**
+ * Clear: drop the hint ids a consumer took ownership of (a completed
+ * review, or a digest entry that persists them); the conversation's
+ * entry leaves when it empties. An unknown id (e.g. a fresh hint that
+ * was never refunded) is a no-op, and so is an untouched file.
+ */
+export declare function clearPendingHints(host: SigrunHost, user: string, conversationId: ConversationId, hints: readonly CurationHint[]): Promise<void>;

package/dist/queue.js

@@ -0,0 +1,237 @@
+/**
+ * The review queues (`src/queue.ts`, Task B2):
+ *
+ * - `ReviewQueue` — one in-flight review PER USER, FIFO per user (a
+ *   burst of settles on one user's conversations reviews in order,
+ *   never concurrently; two users never serialize against each other).
+ *   `onRunSettled` enqueues and returns; the queue owns the run. The
+ *   auto-namer's pattern: a per-key promise chain, `idle()` for tests.
+ * - `queueDigest` — the mixed-conversation spill: loop 1 never forks a
+ *   shared conversation, it appends the id to the per-user
+ *   `digest-queue.json` (state), and loop 2's digest step (Task B4)
+ *   consumes the list. Dedup by conversation id — one pending entry per
+ *   conversation, however many runs triggered it — with the taken
+ *   hints merged into the entry (the decision took them read-and-clear;
+ *   the digest run folds them into its instruction).
+ * - the refunded-hints file (`pending-hints.json`) — the fix for the
+ *   dropped-hints bug: `takeHints` is read-and-clear, so a review that
+ *   ends failed / cancelled / deadline would otherwise lose its hints
+ *   for good. Non-completed reviews write them back (refund, merged by
+ *   hint id); the decision merges a conversation's refunded batch into
+ *   every fresh take; a COMPLETED review (or a digest entry that takes
+ *   ownership) clears the ids it consumed. The transfer is deliberately
+ *   at-least-once: a crash between refund and clear duplicates a hint
+ *   (dedup absorbs it), never drops one.
+ *
+ * Errors never break a chain: the queue's contract is that a job's
+ * failure is the job's business (the loop records it); the chain keeps
+ * draining.
+ *
+ * Every hints helper here dedups by hint id: a hint may briefly live in
+ * two places (host + refund file, refund file + digest entry) around a
+ * crash, and dedup makes the overlap harmless.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * The per-user FIFO review queue. `enqueue` never runs the work on the
+ * caller's stack — it appends to the user's chain; `idle()` resolves
+ * when NO user has work in flight or queued.
+ */
+export class ReviewQueue {
+    /** One promise chain per user (the FIFO + the one-in-flight rule). */
+    chains = new Map();
+    /** Jobs not yet finished, across every user (the `idle()` counter). */
+    pending = 0;
+    /** Every live `idle()` waiter, released together at drain. */
+    waiters = [];
+    /** Append one job to its user's chain. */
+    enqueue(job) {
+        const previous = this.chains.get(job.user) ?? Promise.resolve();
+        this.pending += 1;
+        const next = previous
+            .then(job.work)
+            .catch(() => undefined)
+            .finally(() => {
+            this.pending -= 1;
+            if (this.chains.get(job.user) === next)
+                this.chains.delete(job.user);
+            if (this.pending === 0 && this.waiters.length > 0) {
+                const waiters = this.waiters;
+                this.waiters = [];
+                for (const resolve of waiters)
+                    resolve();
+            }
+        });
+        this.chains.set(job.user, next);
+    }
+    /**
+     * Resolve when every enqueued job has finished (immediately when
+     * the queue is empty). Tests await this; production never does.
+     */
+    idle() {
+        if (this.pending === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+}
+/** The digest-queue file name under the user's state dir. */
+const DIGEST_QUEUE_FILE = "digest-queue.json";
+/**
+ * Read one JSON state file with a fallback: absent or malformed → the
+ * fallback value (state files are the loop's own bookkeeping — a bad
+ * file degrades to defaults, never a broken loop).
+ */
+export async function readStateJson(file, fallback) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        return fallback; // absent: never written
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Write one JSON state file under the user's state dir (tab indents). */
+export async function writeStateJson(stateDir, name, value) {
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(join(stateDir, name), `${JSON.stringify(value, null, "\t")}\n`, "utf8");
+}
+/** Read the digest queue file path for one user's state dir. */
+function digestQueueFile(stateDir) {
+    return join(stateDir, DIGEST_QUEUE_FILE);
+}
+/** Read the digest queue from a file; absent/malformed → []. */
+async function readDigestQueueFile(file) {
+    const parsed = await readStateJson(file, {});
+    if (!Array.isArray(parsed.conversations))
+        return [];
+    return parsed.conversations.filter((entry) => typeof entry === "object" &&
+        entry !== null &&
+        typeof entry.id === "number" &&
+        Array.isArray(entry.hints));
+}
+/** Read the digest queue's entries for one user; absent/malformed → []. */
+export async function readDigestQueue(host, user) {
+    return await readDigestQueueFile(digestQueueFile(host.stores.user(user).paths.state));
+}
+/** Overwrite the digest queue's entries (the digest step's write-back). */
+export async function writeDigestQueue(host, user, conversations) {
+    await writeStateJson(host.stores.user(user).paths.state, DIGEST_QUEUE_FILE, { conversations });
+}
+/**
+ * Remove one conversation's digest entry (the digest step, after the
+ * review completed and took ownership of its hints). Idempotent.
+ */
+export async function removeDigestEntry(host, user, conversationId) {
+    const queue = [...(await readDigestQueue(host, user))];
+    const next = queue.filter((entry) => entry.id !== conversationId);
+    if (next.length === queue.length)
+        return; // absent: nothing to remove
+    await writeDigestQueue(host, user, next);
+}
+/**
+ * Queue one conversation for loop 2's digest (Task B4 consumes): append
+ * to `digest-queue.json` under the user's state dir, dedup by id, the
+ * taken hints merged into the existing entry by hint id (never dropped).
+ */
+export async function queueDigest(host, user, conversationId, hints = []) {
+    const file = digestQueueFile(host.stores.user(user).paths.state);
+    const queue = [...(await readDigestQueueFile(file))];
+    const existing = queue.find((entry) => entry.id === conversationId);
+    if (existing === undefined) {
+        queue.push({ id: conversationId, hints });
+    }
+    else {
+        const seen = new Set(existing.hints.map((hint) => hint.id));
+        const merged = [
+            ...existing.hints,
+            ...hints.filter((hint) => !seen.has(hint.id)),
+        ];
+        if (merged.length === existing.hints.length)
+            return; // nothing new
+        queue[queue.indexOf(existing)] = { id: conversationId, hints: merged };
+    }
+    await writeDigestQueue(host, user, queue);
+}
+/** The refunded-hints file name under the user's state dir. */
+const PENDING_HINTS_FILE = "pending-hints.json";
+/** Read the refunded-hints file; absent/malformed → []. */
+async function readPendingHints(file) {
+    const parsed = await readStateJson(file, []);
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter((entry) => typeof entry === "object" &&
+        entry !== null &&
+        typeof entry.conversationId === "number" &&
+        Array.isArray(entry.hints));
+}
+/** Merge two hint batches into one, deduped by hint id. */
+export function mergeHints(first, second) {
+    const seen = new Set(first.map((hint) => hint.id));
+    return [...first, ...second.filter((hint) => !seen.has(hint.id))];
+}
+/** The hints refunded for one conversation (a read; nothing is cleared). */
+export async function pendingHintsFor(host, user, conversationId) {
+    const entries = await readPendingHints(join(host.stores.user(user).paths.state, PENDING_HINTS_FILE));
+    return entries.find((entry) => entry.conversationId === conversationId)
+        ?.hints ?? [];
+}
+/**
+ * Refund: write a non-completed review's hints back, merged into the
+ * conversation's refunded batch by hint id (never dropped, never
+ * duplicated — an unchanged entry is not rewritten).
+ */
+export async function refundHints(host, user, conversationId, hints) {
+    if (hints.length === 0)
+        return;
+    const stateDir = host.stores.user(user).paths.state;
+    const entries = [
+        ...(await readPendingHints(join(stateDir, PENDING_HINTS_FILE))),
+    ];
+    const existing = entries.find((entry) => entry.conversationId === conversationId);
+    if (existing === undefined) {
+        entries.push({ conversationId, hints });
+    }
+    else {
+        const merged = mergeHints(existing.hints, hints);
+        if (merged.length === existing.hints.length)
+            return; // nothing new
+        entries[entries.indexOf(existing)] = {
+            conversationId,
+            hints: merged,
+        };
+    }
+    await writeStateJson(stateDir, PENDING_HINTS_FILE, entries);
+}
+/**
+ * Clear: drop the hint ids a consumer took ownership of (a completed
+ * review, or a digest entry that persists them); the conversation's
+ * entry leaves when it empties. An unknown id (e.g. a fresh hint that
+ * was never refunded) is a no-op, and so is an untouched file.
+ */
+export async function clearPendingHints(host, user, conversationId, hints) {
+    const stateDir = host.stores.user(user).paths.state;
+    const entries = [
+        ...(await readPendingHints(join(stateDir, PENDING_HINTS_FILE))),
+    ];
+    const index = entries.findIndex((entry) => entry.conversationId === conversationId);
+    if (index === -1)
+        return; // nothing refunded: no entry to clear
+    const consumed = new Set(hints.map((hint) => hint.id));
+    const remaining = entries[index].hints.filter((hint) => !consumed.has(hint.id));
+    if (remaining.length === entries[index].hints.length)
+        return; // untouched
+    if (remaining.length === 0)
+        entries.splice(index, 1);
+    else
+        entries[index] = { conversationId, hints: remaining };
+    await writeStateJson(stateDir, PENDING_HINTS_FILE, entries);
+}

package/dist/settings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The curator's per-user settings (`src/settings.ts`, Task B1): read
+ * LIVE through the per-user scoped store, with defaults for every
+ * absent or malformed field — the read never throws (a bad edit disables
+ * nothing; the loop reads per event, like the gateway's live config).
+ *
+ * The stored object is the user's scoped settings for THIS extension
+ * (`settings/curator.json` in the real host); the fields sit at its top
+ * level. Unknown keys ride along untouched — they may belong to a later
+ * task of this extension and are none of the reader's business.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+/** The per-user curator settings (spec §6.2). */
+export interface CuratorSettings {
+    /** Whether the curator runs for this user at all (restart-free: read per event). */
+    readonly enabled: boolean;
+    /** Pauses the loops without disabling the view or `/learn` (a vacation switch). */
+    readonly paused: boolean;
+    /** The model idle-pass digest runs use (absent: the server default). */
+    readonly idleModel?: string;
+    /** Model calls between reviews (spec §5 pins 10). */
+    readonly threshold: number;
+    /** Idle-pass digest runs per day (spec §5 pins 12). */
+    readonly dailyRuns: number;
+}
+/** The defaults every absent or malformed field falls back to. */
+export declare const DEFAULT_CURATOR_SETTINGS: Readonly<CuratorSettings>;
+/**
+ * Parse a raw settings object into {@link CuratorSettings}: every field
+ * validated by TYPE and range, falling back to its default — the read
+ * is total, never a throw.
+ */
+export declare function parseCuratorSettings(raw: Record<string, unknown>): CuratorSettings;
+/**
+ * Read one user's settings LIVE through the per-user scoped store,
+ * merged over the defaults.
+ */
+export declare function readSettings(host: SigrunHost, user: string): Promise<CuratorSettings>;