@sigrun/ext-curator 0.0.0-stage → 0.2.0

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

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