@sigrun/ext-curator 0.0.0-stage → 0.2.0

package/dist/steps/diet.js

@@ -0,0 +1,131 @@
+/**
+ * The skill-diet step (`src/steps/diet.ts`, Task B4 — loop 2 step
+ * `diet`): ONE oversized learned skill per pass is rewritten so its
+ * `##` sections move out to `references/` files verbatim (openclaw's
+ * diet), and a SECOND model run compares old and new and answers
+ * `{"loss": false}` — anything else (a reported loss, or an unparseable
+ * answer) undoes the rewrite through `skills.undo`, so no unverified
+ * diet ever stands.
+ *
+ * Eligibility (the brief): a learned skill whose SKILL.md is > 12 KB
+ * and unchanged for 24h — "unchanged" reads the skill store's feed: the
+ * newest curator/agent-authored entry for the skill must be older than
+ * 24h (a skill with no feed entry at all counts as its creation, so a
+ * freshly created giant waits a day before its first diet).
+ *
+ * The runs: the FIRST carries the full SKILL.md and instructs the
+ * move-to-references rewrite (the run performs it through its allowed
+ * `skill_manage` tool — `write_file` under `references/` plus the
+ * trimmed patch); the SECOND carries old and new side by side and asks
+ * only the fixed JSON loss answer. Both are ordinary budget-spending
+ * digest runs on the idle model.
+ */
+import { digestRunWithBudget, parseVerdict, stepLog } from "./run.js";
+/** The diet threshold (the brief: > 12 KB). */
+export const DIET_BYTES = 12 * 1024;
+/** How long a skill must be unchanged before a diet (the brief: 24h). */
+export const DIET_UNCHANGED_MS = 24 * 60 * 60 * 1000;
+/** The diet's allow list: the rewrite runs through skill_manage. */
+const DIET_ALLOW = ["skill_manage"];
+/** The loop-2 diet step: diet at most one eligible skill. */
+export async function dietStep(deps) {
+    const { host, user } = deps;
+    const log = stepLog(deps);
+    if (deps.budget.left() < 1)
+        return false; // the day is spent: stop the pass
+    const store = host.curation.skills(user);
+    const feed = await store.feed(200);
+    for (const row of await store.list()) {
+        if (deps.now().getTime() >= deps.deadlineAt)
+            return false;
+        if (row.archived)
+            continue;
+        if (row.bytes <= DIET_BYTES)
+            continue;
+        const last = newestEntry(feed, row.name) ?? row.createdAt;
+        if (deps.now().getTime() - Date.parse(last) < DIET_UNCHANGED_MS)
+            continue;
+        const done = await dietOne(deps, row.name).catch((error) => {
+            log(`loop 2: ${user} diet of skill ${row.name} failed: ${error instanceof Error ? error.message : String(error)}`);
+            return true;
+        });
+        return done; // ONE skill per pass, whatever happened
+    }
+    return true;
+}
+/** Diet one skill: rewrite, compare, undo on loss or unparseable. */
+async function dietOne(deps, name) {
+    const { host, user } = deps;
+    const store = host.curation.skills(user);
+    const oldBody = await store.view(name);
+    if (oldBody === "")
+        return true; // unreadable: nothing to diet safely
+    // Run 1 — the rewrite (the run moves `##` sections to references/
+    // verbatim through its skill_manage tool).
+    const rewrite = await digestRunWithBudget(deps, {
+        input: rewriteInput(name, oldBody),
+        allow: DIET_ALLOW,
+    });
+    if (rewrite === undefined)
+        return false; // no budget left today
+    if (rewrite.result.status !== "completed" || rewrite.result.changes.length === 0) {
+        return true;
+    }
+    // Run 2 — the loss compare over old and NEW bodies.
+    const newBody = await store.view(name);
+    const compare = await digestRunWithBudget(deps, {
+        input: compareInput(name, oldBody, newBody),
+        allow: DIET_ALLOW, // the compare may read files through skill_manage
+    });
+    if (compare === undefined) {
+        // Budget ran out mid-diet: an UNVERIFIED rewrite must not stand.
+        await undoChanges(store, rewrite.result);
+        return false;
+    }
+    const verdict = compare.result.status === "completed"
+        ? parseVerdict(compare.result.text)
+        : undefined;
+    if (verdict !== undefined && verdict.loss === false)
+        return true; // verified
+    // A reported loss, an unparseable answer, or a failed compare run:
+    // the rewrite is undone (the brief — or the change is undone).
+    await undoChanges(store, rewrite.result);
+    return true;
+}
+/** Undo one run's changes through the skill store. */
+async function undoChanges(store, run) {
+    const ids = run.changes
+        .map((change) => change.changeId)
+        .filter((id) => typeof id === "string" && id !== "");
+    if (ids.length > 0)
+        await store.undo(ids);
+}
+/** The feed's newest entry for one skill (feed is newest-first). */
+function newestEntry(feed, skill) {
+    return feed.find((entry) => entry.skill === skill)?.at;
+}
+/** The rewrite run's input (run 1). */
+function rewriteInput(name, body) {
+    return [
+        `You are the curator. The learned skill "${name}" is too large. Diet it: keep the skill's SKILL.md to its opening summary and its core procedure, and move every \`##\` section that is reference material (examples, long tables, background) into files under \`references/\` VERBATIM — unchanged text, only relocated. Re-link them from SKILL.md with a one-line pointer each.`,
+        "",
+        "The current SKILL.md in full:",
+        body,
+        "",
+        "Use your skill_manage tool to write the files (write_file for each references/ file, then patch SKILL.md). Move text verbatim; never summarize, merge, or drop a rule. When you are done, answer with one line naming what you moved.",
+    ].join("\n");
+}
+/** The loss-compare run's input (run 2). */
+function compareInput(name, oldBody, newBody) {
+    return [
+        `You are the curator. The learned skill "${name}" was just dieted: sections moved to references/ files. Compare the OLD body with the NEW body plus the reference files' pointers, and decide whether any rule, pitfall, or instruction present in the old body was dropped or weakened anywhere in the new shape.`,
+        "",
+        "The OLD SKILL.md:",
+        oldBody,
+        "",
+        "The NEW SKILL.md (references/ files are reachable through its pointers):",
+        newBody,
+        "",
+        'Answer with ONLY this JSON: {"loss": false} when nothing was dropped or weakened, or {"loss": true} when something was.',
+    ].join("\n");
+}

package/dist/steps/digests.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The mixed-conversation digest step (`src/steps/digests.ts`, Task B4 —
+ * loop 2 step `digests`): the conversations loop 1 refused to fork
+ * (mixed authorship, unattributed entries) are reviewed here, NEVER
+ * forked — a fresh internal digest run over a text digest of the
+ * OWNER'S attributed turns plus the assistant replies to them.
+ *
+ * Attribution (fail closed, P1's rule — another user's words can never
+ * enter the owner's digest): the PRIMARY per-entry source is
+ * `curation.authors(conversationId)` — core's map of every user-input
+ * entry in the active context to its author (an entry ABSENT from the
+ * map or mapped to `undefined` is unattributed and never the owner's).
+ * When the map is EMPTY (no attributed entry at all — a pre-P1-shaped
+ * or fresh conversation), the step falls back to `curation.eligibility`:
+ * an owner-only conversation with zero unattributed entries attributes
+ * EVERY user turn to the owner (that is what `ownerOnly` means). A
+ * mixed conversation whose map has no entry for the digesting user has
+ * no attributable turn — none is included, the fail-closed skip below
+ * leaves it queued.
+ *
+ * ✅ HOST GAP RESOLVED (2026-11-01): this step originally read per-entry
+ * authors from a `sigrun.authors` doc projected onto the watched view
+ * (`docs["sigrun.authors"].byEntry`) — but pi-durable's structural view
+ * mounts only its five built-in docs, so that projection never existed
+ * and mixed conversations digested NOTHING. Core now serves the map
+ * directly (`host.curation.authors`, core commit "feat(curation):
+ * per-entry author map on host.curation"); the view-doc path is gone.
+ *
+ * Assistant replies: an assistant entry is included only when it
+ * belongs to the run an OWNER turn started — the entries after an
+ * owner-attributed user entry, up to the next user entry (a reply that
+ * follows another user's turn answers that turn, and is excluded with
+ * it).
+ *
+ * Durability: the queue file is read WITHOUT clearing; an entry is
+ * removed only after its review COMPLETED (a failed run leaves it for
+ * the next pass). The B2 carry: consumption dedups hints by id — the
+ * entry's own hints merge with the conversation's refunded batch
+ * (`pending-hints.json`), and completing the review drains both.
+ */
+import type { ConversationId } from "@earendil-works/pi-durable";
+import { type ModelStepDeps } from "./run.js";
+/** The digest step's own view-acquisition grace: how long to wait for
+ *  the watched conversation's first frame (the real host delivers the
+ *  snapshot before `watch` resolves; the grace only bounds an anomaly). */
+export declare const DIGEST_VIEW_GRACE_MS = 10000;
+/** The loop-2 digest step: review every queued mixed conversation.
+ *  Answers FALSE when the daily budget ran out (the pass stops). */
+export declare function digestsStep(deps: ModelStepDeps): Promise<boolean>;
+/**
+ * Review ONE conversation (exported for the step loop): watch its view,
+ * build the owner's digest, run the review, and consume the queue
+ * entry on completion. False = out of budget (the caller stops).
+ */
+export declare function reviewDigest(deps: ModelStepDeps, conversationId: ConversationId): Promise<boolean>;

package/dist/steps/digests.js

@@ -0,0 +1,243 @@
+/**
+ * The mixed-conversation digest step (`src/steps/digests.ts`, Task B4 —
+ * loop 2 step `digests`): the conversations loop 1 refused to fork
+ * (mixed authorship, unattributed entries) are reviewed here, NEVER
+ * forked — a fresh internal digest run over a text digest of the
+ * OWNER'S attributed turns plus the assistant replies to them.
+ *
+ * Attribution (fail closed, P1's rule — another user's words can never
+ * enter the owner's digest): the PRIMARY per-entry source is
+ * `curation.authors(conversationId)` — core's map of every user-input
+ * entry in the active context to its author (an entry ABSENT from the
+ * map or mapped to `undefined` is unattributed and never the owner's).
+ * When the map is EMPTY (no attributed entry at all — a pre-P1-shaped
+ * or fresh conversation), the step falls back to `curation.eligibility`:
+ * an owner-only conversation with zero unattributed entries attributes
+ * EVERY user turn to the owner (that is what `ownerOnly` means). A
+ * mixed conversation whose map has no entry for the digesting user has
+ * no attributable turn — none is included, the fail-closed skip below
+ * leaves it queued.
+ *
+ * ✅ HOST GAP RESOLVED (2026-11-01): this step originally read per-entry
+ * authors from a `sigrun.authors` doc projected onto the watched view
+ * (`docs["sigrun.authors"].byEntry`) — but pi-durable's structural view
+ * mounts only its five built-in docs, so that projection never existed
+ * and mixed conversations digested NOTHING. Core now serves the map
+ * directly (`host.curation.authors`, core commit "feat(curation):
+ * per-entry author map on host.curation"); the view-doc path is gone.
+ *
+ * Assistant replies: an assistant entry is included only when it
+ * belongs to the run an OWNER turn started — the entries after an
+ * owner-attributed user entry, up to the next user entry (a reply that
+ * follows another user's turn answers that turn, and is excluded with
+ * it).
+ *
+ * Durability: the queue file is read WITHOUT clearing; an entry is
+ * removed only after its review COMPLETED (a failed run leaves it for
+ * the next pass). The B2 carry: consumption dedups hints by id — the
+ * entry's own hints merge with the conversation's refunded batch
+ * (`pending-hints.json`), and completing the review drains both.
+ */
+import { clearPendingHints, mergeHints, pendingHintsFor, readDigestQueue, removeDigestEntry, } from "../queue.js";
+import { notify } from "../notices.js";
+import { reviewInstruction } from "../prompts.js";
+import { digestRunWithBudget, stepLog } from "./run.js";
+/** The digest step's own view-acquisition grace: how long to wait for
+ *  the watched conversation's first frame (the real host delivers the
+ *  snapshot before `watch` resolves; the grace only bounds an anomaly). */
+export const DIGEST_VIEW_GRACE_MS = 10_000;
+/** The entry kinds that carry a user turn (attribution.ts's set). */
+const USER_KINDS = new Set([
+    "pi.user",
+    "sigrun.user.expanded",
+    "sigrun.blocks.answer",
+]);
+/** The loop-2 digest step: review every queued mixed conversation.
+ *  Answers FALSE when the daily budget ran out (the pass stops). */
+export async function digestsStep(deps) {
+    const { host, user } = deps;
+    const log = stepLog(deps);
+    if (deps.budget.left() < 1)
+        return false; // the day is spent: stop the pass
+    const entries = await readDigestQueue(host, user);
+    for (const entry of entries) {
+        if (deps.now().getTime() >= deps.deadlineAt)
+            return false;
+        const done = await reviewDigest(deps, entry.id).catch((error) => {
+            log(`loop 2: ${user} digest of conversation ${String(entry.id)} failed: ${error instanceof Error ? error.message : String(error)}`);
+            return true;
+        });
+        if (!done)
+            return false; // out of daily budget: stop for the day
+    }
+    return true;
+}
+/**
+ * Review ONE conversation (exported for the step loop): watch its view,
+ * build the owner's digest, run the review, and consume the queue
+ * entry on completion. False = out of budget (the caller stops).
+ */
+export async function reviewDigest(deps, conversationId) {
+    const { host, user } = deps;
+    const log = stepLog(deps);
+    const view = await watchFirstFrame(deps, conversationId);
+    if (view === undefined) {
+        log(`loop 2: ${user} digest of conversation ${String(conversationId)} saw no view`);
+        return true; // unreadable: leave it queued, move on
+    }
+    const digest = await ownerDigest(deps, conversationId, view);
+    if (digest === undefined) {
+        log(`loop 2: ${user} digest of conversation ${String(conversationId)} has no attributable turns`);
+        return true; // fail closed: leave it queued for a per-entry source
+    }
+    // The B2 carry: the entry owns its hints; the refund file may hold
+    // the same ids (a crash between queueDigest and the clear) — merge
+    // by hint id so a stranded hint is consumed exactly once.
+    const hints = mergeHints(await pendingHintsFor(host, user, conversationId), (await readDigestQueue(host, user)).find((entry) => entry.id === conversationId)?.hints ?? []);
+    const targets = await host.curation.targets(user, conversationId);
+    const selection = await host.curation.tools(conversationId);
+    const allow = [
+        ...new Set([
+            "skill_manage",
+            ...targets.flatMap((target) => [...target.tools]),
+            ...(selection.includes("read") ? ["read"] : []),
+        ]),
+    ];
+    const instruction = reviewInstruction({
+        hints,
+        targets: targets.map((target) => ({
+            id: target.id,
+            guidance: [...target.guidance],
+        })),
+        allow,
+    });
+    const run = await digestRunWithBudget(deps, {
+        input: `${digest}\n\n${instruction}`,
+        allow,
+    });
+    if (run === undefined)
+        return false; // no budget left today
+    if (run.result.status !== "completed")
+        return true; // leave it queued
+    // The review consumed these hints for good: the queue entry goes and
+    // the refund file drains of the same ids.
+    await removeDigestEntry(deps.host, user, conversationId);
+    await clearPendingHints(host, user, conversationId, hints);
+    // Task B5: a digest review that CHANGED something announces itself
+    // on the originating (mixed) conversation — the same notice shape a
+    // fork review sets, undoable from the view. The notice is isolated:
+    // a failing setAmbient or ledger write degrades to a missing notice,
+    // never a failed step (the catch above would strand a COMPLETED
+    // review's entry back in the queue as if the run had failed).
+    await notify(host, conversationId, user, {
+        ...run.result,
+        reviewId: run.reviewId,
+    }).catch((error) => {
+        log(`loop 2: ${user} notice after the digest of conversation ${String(conversationId)} could not be set: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return true;
+}
+/**
+ * Watch the conversation and resolve its FIRST frame (the snapshot the
+ * real host pushes before `watch` resolves), bounded by the grace.
+ */
+async function watchFirstFrame(deps, conversationId) {
+    let frame;
+    let releaseFrame;
+    const first = new Promise((resolve) => {
+        releaseFrame = resolve;
+    });
+    const stop = await deps.host.conversations.watch(conversationId, (view) => {
+        frame = view;
+        releaseFrame();
+    });
+    try {
+        if (frame === undefined) {
+            const grace = Math.min(DIGEST_VIEW_GRACE_MS, Math.max(0, deps.deadlineAt - deps.now().getTime()));
+            await Promise.race([
+                first,
+                new Promise((resolve) => setTimeout(resolve, grace)),
+            ]);
+        }
+    }
+    finally {
+        await stop();
+    }
+    return frame;
+}
+/** The owner's digest of one view, or undefined when no user turn is
+ *  attributable (the fail-closed skip). */
+async function ownerDigest(deps, conversationId, view) {
+    const { host, user } = deps;
+    // Per-entry attribution, the PRIMARY source: entry id → author,
+    // skipping unattributed entries (author undefined — an entry absent
+    // from this record reads unattributed, so `undefined === user` is
+    // false and the turn is excluded: never learn from unattributed).
+    const attributed = await host.curation.authors(conversationId);
+    const byEntry = {};
+    for (const [entryId, author] of attributed) {
+        if (author !== undefined)
+            byEntry[String(entryId)] = author;
+    }
+    // The empty map means "no attributed entry at all" (a pre-P1-shaped
+    // or fresh conversation): fall back to the whole-conversation
+    // eligibility read so owner-only conversations still digest.
+    let everyTurnIsOwners = false;
+    if (Object.keys(byEntry).length === 0) {
+        const eligibility = await host.curation.eligibility(conversationId);
+        everyTurnIsOwners =
+            eligibility.owner === user && eligibility.ownerOnly && eligibility.unattributed === 0;
+    }
+    const lines = [];
+    let inOwnerRun = false;
+    let sawOwnerTurn = false;
+    const hasPerEntry = Object.keys(byEntry).length > 0;
+    for (const entry of view.entries ?? []) {
+        if (USER_KINDS.has(entry.kind)) {
+            const author = byEntry[String(entry.id)];
+            inOwnerRun = hasPerEntry ? author === user : everyTurnIsOwners;
+            if (!inOwnerRun)
+                continue;
+            const text = entryText(entry, "user");
+            if (text === "")
+                continue;
+            lines.push(`User (${user}): ${text}`);
+            sawOwnerTurn = true;
+            continue;
+        }
+        if (entry.kind === "pi.assistant") {
+            if (!inOwnerRun)
+                continue; // replies to another user's turn
+            const text = entryText(entry, "assistant");
+            if (text === "")
+                continue;
+            lines.push(`Assistant: ${text}`);
+        }
+    }
+    if (!sawOwnerTurn)
+        return undefined;
+    return [`Conversation digest (only ${user}'s turns and the replies to them):`, "", ...lines]
+        .join("\n");
+}
+/** One entry's text for `role` (string content, or the text blocks). */
+function entryText(entry, role) {
+    const parts = [];
+    for (const message of entry.model ?? []) {
+        if (message.role !== role)
+            continue;
+        const content = message.content;
+        if (typeof content === "string") {
+            parts.push(content);
+        }
+        else if (Array.isArray(content)) {
+            for (const block of content) {
+                if (typeof block === "object" &&
+                    block !== null &&
+                    typeof block.text === "string") {
+                    parts.push(block.text);
+                }
+            }
+        }
+    }
+    return parts.join("\n").trim();
+}

package/dist/steps/merge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The merge step (`src/steps/merge.ts`, Task B4 — loop 2 step `merge`):
+ * ONE pair of learned skills a run judges same-class merges — the run
+ * patches the survivor and the step archives the other with
+ * `absorbed_into` naming the survivor (the spec's merge shape).
+ *
+ * The verdict (`{"merge": ["a","b"], "survivor": "a"}`) is the run's
+ * final text in the fixed JSON shape. It must name exactly two KNOWN,
+ * unarchived, learned skills with a known survivor among them —
+ * anything else (unparseable text, unknown names, a mismatched
+ * survivor) changes nothing, and a run that already wrote through its
+ * tools is reverted with `undoReview` (an unverified merge never
+ * stands, mirroring the diet's compare rule).
+ */
+import { type ModelStepDeps } from "./run.js";
+/** The loop-2 merge step: at most one judged merge per pass. */
+export declare function mergeStep(deps: ModelStepDeps): Promise<boolean>;

package/dist/steps/merge.js

@@ -0,0 +1,81 @@
+/**
+ * The merge step (`src/steps/merge.ts`, Task B4 — loop 2 step `merge`):
+ * ONE pair of learned skills a run judges same-class merges — the run
+ * patches the survivor and the step archives the other with
+ * `absorbed_into` naming the survivor (the spec's merge shape).
+ *
+ * The verdict (`{"merge": ["a","b"], "survivor": "a"}`) is the run's
+ * final text in the fixed JSON shape. It must name exactly two KNOWN,
+ * unarchived, learned skills with a known survivor among them —
+ * anything else (unparseable text, unknown names, a mismatched
+ * survivor) changes nothing, and a run that already wrote through its
+ * tools is reverted with `undoReview` (an unverified merge never
+ * stands, mirroring the diet's compare rule).
+ */
+import { digestRunWithBudget, parseVerdict, stepLog } from "./run.js";
+/** The merge's allow list: the run patches through skill_manage. */
+const MERGE_ALLOW = ["skill_manage"];
+/** The loop-2 merge step: at most one judged merge per pass. */
+export async function mergeStep(deps) {
+    const { host, user } = deps;
+    const log = stepLog(deps);
+    if (deps.budget.left() < 1)
+        return false; // the day is spent: stop the pass
+    const skills = await host.curation.skills(user).list();
+    const active = skills.filter((row) => !row.archived);
+    if (active.length < 2)
+        return true; // nothing mergeable
+    const result = await digestRunWithBudget(deps, {
+        input: mergeInput(active),
+        allow: MERGE_ALLOW,
+    });
+    if (result === undefined)
+        return false; // no budget left today
+    if (result.result.status !== "completed")
+        return true;
+    const verdict = parseVerdict(result.result.text);
+    const plan = verdict === undefined ? undefined : mergePlan(verdict, active);
+    if (plan !== undefined) {
+        // The run patched the survivor; the step archives the absorbed
+        // skill naming it (absorbed_into) — undoable through the feed.
+        await host.curation.skills(user).apply(plan.absorbed, { kind: "archive", absorbedInto: plan.survivor }, { reason: `merged into ${plan.survivor}` });
+        return true;
+    }
+    // Unparseable or unusable verdict: a run that wrote anyway is undone
+    // — an unverified merge never stands (net: no change).
+    if (result.result.changes.length > 0) {
+        await host.curation.undoReview(user, result.reviewId).catch((error) => {
+            log(`loop 2: ${user} merge undo of review failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    return true;
+}
+/** Validate a verdict into a merge plan; undefined when it names
+ *  anything but exactly two known active skills and a survivor of them. */
+function mergePlan(verdict, active) {
+    if (!Array.isArray(verdict.merge) || verdict.merge.length !== 2)
+        return undefined;
+    const [first, second] = verdict.merge;
+    if (typeof first !== "string" || typeof second !== "string")
+        return undefined;
+    if (typeof verdict.survivor !== "string")
+        return undefined;
+    const names = new Set(active.map((row) => row.name));
+    if (!names.has(first) || !names.has(second))
+        return undefined;
+    if (verdict.survivor !== first && verdict.survivor !== second)
+        return undefined;
+    const absorbed = verdict.survivor === first ? second : first;
+    return { survivor: verdict.survivor, absorbed };
+}
+/** The merge run's input: the candidate list and the fixed verdict. */
+function mergeInput(active) {
+    const rows = active.map((row) => `- ${row.name} (${row.bytes} bytes): ${row.description}`);
+    return [
+        "You are the curator. These are the user's learned skills. Decide whether exactly ONE pair covers the same class of task and should merge (the survivor absorbs the other's rules; use your skill_manage tool to patch the survivor so it covers both). Most passes find no pair — that is fine.",
+        "",
+        ...rows,
+        "",
+        'When you merged a pair, answer with ONLY this JSON: {"merge": ["<survivor>", "<absorbed>"], "survivor": "<survivor>"}. Otherwise answer with {}.',
+    ].join("\n");
+}

package/dist/steps/overlays.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Overlay drift detection (`src/steps/overlays.ts`, Task B3 — the
+ * DETECTION half; the re-check model step is Task B4's).
+ *
+ * `detectOverlayDrift` walks every stored overlay and compares the
+ * hash it was written against (`upstreamHash`) with the upstream as it
+ * stands (`upstream(user, key)?.hash`):
+ *
+ * - ABSENT upstream → `overlays(user).markOrphans(present, now)`: the
+ *   host-side pass stamps `orphanedSince` (or clears it when the
+ *   upstream is back). The present-predicate answers from this pass's
+ *   upstream reads, so the mark and the drift walk agree on the same
+ *   observation.
+ *
+ * - CHANGED hash → the overlay is QUEUED for a re-check in
+ *   `overlay-recheck-queue.json` under the user's state dir (the file
+ *   name this repo chose for the seam; the `overlay-recheck` step
+ *   takes it from there). Queueing is all B3 does — deciding
+ *   keep/drop/rewrite takes a model and is the next step's business.
+ *   Keys dedup by their canonical JSON, so a pass that re-observes
+ *   the same drift twice queues it once.
+ *
+ * Deterministic by design: reads + one `markOrphans` + one state-file
+ * write; no model, no interaction.
+ *
+ * Task B4 adds the RE-CHECK half: `recheckOverlays` (the loop-2 model
+ * step) drains the queue, one `digestRun` per drifted key, and applies
+ * the run's verdict — keep (re-anchor the same text on the new hash),
+ * drop (remove), rewrite (put the verdict's new text), or unsure (ONE
+ * `curator.overlay-question` interaction per skill in ONE new
+ * user-owned conversation per pass, applied by `overlayQuestionHandler`
+ * from `interactionSettled`). An unparseable verdict changes nothing.
+ */
+import type { CurationOverlayKey, SigrunHost, SigrunLifecycleHandlers } from "@sigrun/sigrun/extension";
+import { type ModelStepDeps } from "./run.js";
+/**
+ * The overlay-recheck queue's file name under the user's state dir —
+ * the seam B3 writes and Task B4's `overlay-recheck` step consumes.
+ */
+export declare const RECHECK_QUEUE_FILE = "overlay-recheck-queue.json";
+/** A stable identity for one overlay key (dedup and diffs). */
+export declare function keyId(key: CurationOverlayKey): string;
+/** Read the queued re-check keys; absent/malformed → []. */
+export declare function readRecheckQueue(host: SigrunHost, user: string): Promise<readonly CurationOverlayKey[]>;
+/**
+ * The queue B4 consumes: `take()` drains (read-and-clear — a taken
+ * re-check is the re-check step's to finish), `enqueue` appends deduped.
+ */
+export declare class OverlayRecheckQueue {
+    private readonly host;
+    private readonly user;
+    constructor(host: SigrunHost, user: string);
+    /** Append keys, deduped against what is queued (by identity). */
+    enqueue(keys: readonly CurationOverlayKey[]): Promise<void>;
+    /** Read and clear the queue (B4's `overlay-recheck` step start). */
+    take(): Promise<readonly CurationOverlayKey[]>;
+}
+/**
+ * The overlay-detect step: mark orphans with the host and queue every
+ * drifted overlay for a re-check (loop 2 step `overlay-detect`).
+ */
+export declare function detectOverlayDrift(host: SigrunHost, user: string): Promise<void>;
+/**
+ * The overlay-recheck step (loop 2 step `overlay-recheck`): drain the
+ * re-check queue and re-check every drifted overlay — ONE digest run
+ * per key, under the daily budget. Verdicts apply immediately
+ * (keep/drop/rewrite); "unsure" asks the user (the design's only
+ * prompt) and the answer applies through {@link overlayQuestionHandler}.
+ * Answers FALSE when the daily budget ran out mid-queue (the pass
+ * stops for the day; the keys still queued re-check next pass — the
+ * re-check queue only drains as keys complete).
+ *
+ * Crash-durability posture (the B3 carry): `take()` is read-then-clear,
+ * never at-least-once — DETECTION is the system of record; a lost
+ * queue entry self-heals on the next detect pass. A crash after a
+ * run but before its verdict applied wastes one model run, nothing
+ * more (the verdict is re-derived next pass).
+ */
+export declare function recheckOverlays(deps: ModelStepDeps): Promise<boolean>;
+/**
+ * The `interactionSettled` half: apply a settled overlay question's
+ * answer. EVERY terminal status (answered, skipped, cancelled, expired)
+ * drops the entry from the pending file — the file is bounded by
+ * terminal statuses (one open entry per skill key). Only ANSWERED
+ * records with a `verdict` of keep/drop apply; `keep` re-anchors the
+ * remembered overlay text on the remembered hash; `drop` removes the
+ * overlay. The callId is looked up in BOTH the v2 `questions` map and
+ * the migrated `legacy` list, so pre-v2 questions stay answerable
+ * where they were asked. Idempotent per callId (an applied question
+ * leaves the pending file).
+ */
+export declare function overlayQuestionHandler(host: SigrunHost): Pick<SigrunLifecycleHandlers, "interactionSettled">;