@sigrun/ext-curator 0.0.0-stage → 0.1.0

package/dist/settings.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+/** The defaults every absent or malformed field falls back to. */
+export const DEFAULT_CURATOR_SETTINGS = {
+    enabled: true,
+    paused: false,
+    threshold: 10,
+    dailyRuns: 12,
+};
+/** A positive integer (thresholds and run budgets are counts). */
+function positiveInteger(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value > 0);
+}
+/**
+ * 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 function parseCuratorSettings(raw) {
+    return {
+        enabled: typeof raw.enabled === "boolean"
+            ? raw.enabled
+            : DEFAULT_CURATOR_SETTINGS.enabled,
+        paused: typeof raw.paused === "boolean"
+            ? raw.paused
+            : DEFAULT_CURATOR_SETTINGS.paused,
+        ...(typeof raw.idleModel === "string" && raw.idleModel.length > 0
+            ? { idleModel: raw.idleModel }
+            : {}),
+        threshold: positiveInteger(raw.threshold)
+            ? raw.threshold
+            : DEFAULT_CURATOR_SETTINGS.threshold,
+        dailyRuns: positiveInteger(raw.dailyRuns)
+            ? raw.dailyRuns
+            : DEFAULT_CURATOR_SETTINGS.dailyRuns,
+    };
+}
+/**
+ * Read one user's settings LIVE through the per-user scoped store,
+ * merged over the defaults.
+ */
+export async function readSettings(host, user) {
+    const raw = await host.stores.user(user).settings.get();
+    return parseCuratorSettings(raw);
+}

package/dist/steps/archive.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The archive step (`src/steps/archive.ts`, Task B3): loop 2's first
+ * deterministic step — no model, pure store reads plus applies.
+ *
+ * Two 30-day rules (spec §6.2), both `>=` on milliseconds:
+ *
+ * - A LEARNED skill archives when it is unused for 30 days (per
+ *   `usage(user)`; a skill with no usage row counts as used on its
+ *   `createdAt` — never used is the oldest it can be) AND created at
+ *   least 30 days ago, AND it is neither pinned nor referenced by one
+ *   of the user's job prompts (`jobSkillRefs`, paused jobs included —
+ *   archiving under a paused job would break its prompt on resume).
+ *   Already-archived rows are left alone. The archive goes through
+ *   `skills(user).apply(name, {kind:"archive"}, {reason})` — the feed
+ *   records it as a curator change, so the view's undo covers it.
+ *
+ * - An OVERLAY whose upstream vanished (`orphanedSince`, stamped by
+ *   `markOrphans` during the overlay-detect step) is REMOVED after
+ *   30 days orphaned: the detection pass before this one marked it,
+ *   this pass (a later one) reaps it — a returning upstream in between
+ *   clears the mark and spares it.
+ *
+ * The step is idempotent by construction (archived rows are skipped,
+ * removed overlays are gone), so a tick that crashes mid-step and
+ * resumes re-runs it safely.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+/** The archive threshold (spec §5: 30 days), as days for the export. */
+export declare const ARCHIVE_UNUSED_DAYS = 30;
+/** The archive threshold in milliseconds. */
+export declare const ARCHIVE_UNUSED_MS: number;
+/** The feed reason stamped on a skill archive. */
+export declare const ARCHIVE_REASON = "unused for 30 days";
+/** The feed reason stamped on an orphaned-overlay removal. */
+export declare const ORPHAN_REMOVAL_REASON = "orphaned for 30 days";
+/**
+ * Archive the user's unused learned skills and reap their long-orphaned
+ * overlays (loop 2 step `archive`).
+ */
+export declare function archiveUnused(host: SigrunHost, user: string, now: () => Date): Promise<void>;

package/dist/steps/archive.js

@@ -0,0 +1,88 @@
+/**
+ * The archive step (`src/steps/archive.ts`, Task B3): loop 2's first
+ * deterministic step — no model, pure store reads plus applies.
+ *
+ * Two 30-day rules (spec §6.2), both `>=` on milliseconds:
+ *
+ * - A LEARNED skill archives when it is unused for 30 days (per
+ *   `usage(user)`; a skill with no usage row counts as used on its
+ *   `createdAt` — never used is the oldest it can be) AND created at
+ *   least 30 days ago, AND it is neither pinned nor referenced by one
+ *   of the user's job prompts (`jobSkillRefs`, paused jobs included —
+ *   archiving under a paused job would break its prompt on resume).
+ *   Already-archived rows are left alone. The archive goes through
+ *   `skills(user).apply(name, {kind:"archive"}, {reason})` — the feed
+ *   records it as a curator change, so the view's undo covers it.
+ *
+ * - An OVERLAY whose upstream vanished (`orphanedSince`, stamped by
+ *   `markOrphans` during the overlay-detect step) is REMOVED after
+ *   30 days orphaned: the detection pass before this one marked it,
+ *   this pass (a later one) reaps it — a returning upstream in between
+ *   clears the mark and spares it.
+ *
+ * The step is idempotent by construction (archived rows are skipped,
+ * removed overlays are gone), so a tick that crashes mid-step and
+ * resumes re-runs it safely.
+ */
+/** The archive threshold (spec §5: 30 days), as days for the export. */
+export const ARCHIVE_UNUSED_DAYS = 30;
+/** The archive threshold in milliseconds. */
+export const ARCHIVE_UNUSED_MS = ARCHIVE_UNUSED_DAYS * 86_400_000;
+/** The feed reason stamped on a skill archive. */
+export const ARCHIVE_REASON = "unused for 30 days";
+/** The feed reason stamped on an orphaned-overlay removal. */
+export const ORPHAN_REMOVAL_REASON = "orphaned for 30 days";
+/**
+ * Whether `iso` is at least `thresholdMs` before `now`. An unparseable
+ * stamp answers FALSE — bad data spares the skill/overlay, it never
+ * destroys.
+ */
+function atLeast(thresholdMs, now, iso) {
+    if (iso === undefined)
+        return false;
+    const at = Date.parse(iso);
+    return Number.isFinite(at) && now.getTime() - at >= thresholdMs;
+}
+/**
+ * Archive the user's unused learned skills and reap their long-orphaned
+ * overlays (loop 2 step `archive`).
+ */
+export async function archiveUnused(host, user, now) {
+    const at = now();
+    await archiveSkills(host, user, at);
+    await reapOrphanedOverlays(host, user, at);
+}
+/** The learned-skill half of the archive step. */
+async function archiveSkills(host, user, now) {
+    const store = host.curation.skills(user);
+    const skills = await store.list();
+    const usage = await host.curation.usage(user);
+    const jobRefs = await host.curation.jobSkillRefs(user);
+    for (const skill of skills) {
+        if (skill.archived)
+            continue;
+        if (skill.pinned)
+            continue;
+        if (jobRefs.has(skill.name))
+            continue;
+        // Unused ≥ 30 days: never-used counts from creation.
+        const lastUsed = usage[skill.name] ?? skill.createdAt;
+        if (!atLeast(ARCHIVE_UNUSED_MS, now, lastUsed))
+            continue;
+        if (!atLeast(ARCHIVE_UNUSED_MS, now, skill.createdAt))
+            continue;
+        await store.apply(skill.name, { kind: "archive" }, { reason: ARCHIVE_REASON });
+    }
+}
+/** The orphaned-overlay half of the archive step. */
+async function reapOrphanedOverlays(host, user, now) {
+    const store = host.curation.overlays(user);
+    for (const overlay of await store.list()) {
+        if (!atLeast(ARCHIVE_UNUSED_MS, now, overlay.orphanedSince))
+            continue;
+        await store.remove(overlay.key, {
+            actor: "curator",
+            reason: ORPHAN_REMOVAL_REASON,
+        });
+    }
+}

package/dist/steps/diet.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { type ModelStepDeps } from "./run.js";
+/** The diet threshold (the brief: > 12 KB). */
+export declare const DIET_BYTES: number;
+/** How long a skill must be unchanged before a diet (the brief: 24h). */
+export declare const DIET_UNCHANGED_MS: number;
+/** The loop-2 diet step: diet at most one eligible skill. */
+export declare function dietStep(deps: ModelStepDeps): Promise<boolean>;

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>;