@sigrun/ext-curator 0.0.0-stage → 0.1.0

package/dist/loop1.js

@@ -0,0 +1,250 @@
+/**
+ * Loop 1 — the post-run fork review (`src/loop1.ts`, Task B2, spec
+ * §6.2).
+ *
+ * `onRunSettled` DECIDES and ENQUEUES, then returns: runSettled
+ * handlers are abandoned at `SIGRUN_HOOK_DEADLINE` (30 s), so the
+ * review body NEVER runs on the handler's stack — it runs through the
+ * per-user `ReviewQueue`.
+ *
+ * The decision tree (the brief, verbatim authority):
+ *
+ * 1. owner present, settings enabled and not paused, not backed off —
+ *    else return (the hints are left pending, never consumed by a
+ *    review that will not run);
+ * 2. an internal conversation returns (the bus already withholds
+ *    internal settles; this read-side gate is the belt);
+ * 3. `eligibility.ownerOnly && unattributed === 0` → the fork path:
+ *    take the hints (read-and-clear) merged with any refunded batch
+ *    (`pending-hints.json` — hints a previous review consumed but
+ *    never reviewed), count `modelCallsSince(id, lastReviewedEntry)`,
+ *    and review when hints are pending (answered or not — an aborted
+ *    run's hints stay pending until the next settle) or the run
+ *    answered at/over the threshold;
+ * 4. anything else (mixed authorship, unattributed entries) → the
+ *    threshold trigger alone queues a `queueDigest` entry: never
+ *    forked, handed to loop 2 (Task B4). (Hints ride in that durable
+ *    entry — taken read-and-clear and folded into the digest run's
+ *    instruction by Task B4 — and the refund file drains into it, so
+ *    no hint can wait on both.)
+ *
+ * The review itself: the allow-list is `skill_manage` + the served
+ * targets' tools + `read` when the parent's selection carries it; the
+ * bounds are the spec's (8 tool calls, 2048 output tokens, 2 minutes);
+ * a watch on the parent aborts the run's signal the moment the parent
+ * moves. Success anchors the per-conversation cursor
+ * (`cursors.json`) at the eligibility snapshot's newest entry; a
+ * failed run steps that user's backoff ladder; any NON-completed
+ * outcome (failed, cancelled, deadline — or a thrown review) refunds
+ * its hints to `pending-hints.json`, so a consumed-but-unreviewed
+ * hint survives until some review completes with it in hand.
+ */
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { notify } from "./notices.js";
+import { enqueueLearn } from "./learn.js";
+import { reviewInstruction } from "./prompts.js";
+import { clearPendingHints, mergeHints, pendingHintsFor, queueDigest, readStateJson, refundHints, writeStateJson, } from "./queue.js";
+import { readSettings } from "./settings.js";
+/** The per-conversation cursor file under the user's state dir. */
+export const CURSORS_FILE = "cursors.json";
+/** The fork-review bounds (spec §6.2: a handful of calls, small output, ~2 minutes). */
+export const LOOP1_MAX_TOOL_CALLS = 8;
+export const LOOP1_MAX_OUTPUT_TOKENS = 2048;
+export const LOOP1_DEADLINE_MS = 120_000;
+/**
+ * Create loop 1: the `runSettled` handler the factory wires, and the
+ * `learnNow` seam `/learn` runs the same review path through. The
+ * handler owns only the decision; the queue owns the review.
+ */
+export function createLoop1(deps) {
+    const now = deps.now ?? (() => new Date());
+    const log = deps.log ?? ((message) => console.error(`curator: ${message}`));
+    const onRunSettled = async (event) => {
+        const owner = event.owner;
+        if (owner === undefined)
+            return;
+        const id = event.conversationId;
+        const settings = await readSettings(deps.host, owner);
+        if (!settings.enabled || settings.paused)
+            return;
+        if (deps.backoff.blocked(owner, now()))
+            return;
+        const eligibility = await deps.host.curation.eligibility(id);
+        if (eligibility.internal)
+            return;
+        if (eligibility.ownerOnly && eligibility.unattributed === 0) {
+            await enqueueForkReview(owner, id, event, eligibility.newestEntry, settings.threshold);
+        }
+        else {
+            // Mixed authorship: never forked, whatever triggered us — loop
+            // 2's digest step (Task B4) reviews only the owner's turns.
+            // The same trigger gates both routes: hints (taken read-and-clear,
+            // merged into the queued entry so the digest run folds them in)
+            // or an answered run at/over the threshold (the cursor never
+            // advances on this branch, so that is "ever" — what a backlog
+            // wants).
+            const hints = mergeHints(await pendingHintsFor(deps.host, owner, id), await deps.host.curation.takeHints(id));
+            if (hints.length === 0) {
+                if (event.outcome.status !== "answered")
+                    return;
+                const cursors = await readCursors(deps.host, owner);
+                const calls = await deps.host.curation.modelCallsSince(id, cursors.lastReviewedEntry[String(id)]);
+                if (calls < settings.threshold)
+                    return;
+            }
+            await queueDigest(deps.host, owner, id, hints);
+            // The digest entry is durable and owns these ids now — drain the
+            // refund file so a later owner-only settle cannot re-fire them.
+            // After the write, never before: a crash in between duplicates a
+            // hint into two durable places (queueDigest dedups by id), it
+            // never drops one.
+            await clearPendingHints(deps.host, owner, id, hints);
+        }
+    };
+    /**
+     * Trigger evaluation for one owner-only conversation: hints always
+     * fire; otherwise the run must have answered at/over the threshold.
+     */
+    async function enqueueForkReview(owner, id, event, newestEntry, threshold) {
+        // Hints first (read-and-clear), merged with anything a previous
+        // non-completed review refunded for this conversation (dedup by
+        // hint id): a hint stays pending across failures until some
+        // review actually completes with it in hand. When the merged set
+        // is empty, only the threshold can fire and nothing was consumed.
+        const hints = mergeHints(await pendingHintsFor(deps.host, owner, id), await deps.host.curation.takeHints(id));
+        if (hints.length === 0) {
+            if (event.outcome.status !== "answered")
+                return;
+            const cursors = await readCursors(deps.host, owner);
+            const calls = await deps.host.curation.modelCallsSince(id, cursors.lastReviewedEntry[String(id)]);
+            if (calls < threshold)
+                return;
+        }
+        deps.queue.enqueue({
+            user: owner,
+            work: () => runForkReview(owner, id, hints, newestEntry, undefined, `review-${randomUUID()}`).catch((error) => {
+                log(`loop 1: review of conversation ${String(id)} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }),
+        });
+    }
+    /** The review body (queue-owned; never on the handler's stack). */
+    async function runForkReview(owner, id, hints, newestEntry, focus, reviewId) {
+        try {
+            await reviewBody(owner, id, hints, newestEntry, focus, reviewId);
+        }
+        catch (error) {
+            // The body threw before any outcome was recorded (a host read,
+            // the watch, the run itself): the hints were no more consumed
+            // than the run was — refund them, then let the queue's logger
+            // have the error. A refund that itself fails must not mask the
+            // original error.
+            await refundHints(deps.host, owner, id, hints).catch(() => undefined);
+            throw error;
+        }
+    }
+    /** The review proper, factored out of {@link runForkReview}'s refund guard. */
+    async function reviewBody(owner, id, hints, newestEntry, focus, reviewId) {
+        const targets = await deps.host.curation.targets(owner, id);
+        const selection = await deps.host.curation.tools(id);
+        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,
+            ...(focus === undefined ? {} : { focus }),
+        });
+        // The parent abort: any activity on the parent while the review
+        // runs fires the signal — the review reviews the conversation it
+        // saw (the host-side driver re-checks the same state itself).
+        const abort = new AbortController();
+        const stopWatch = await deps.host.conversations.watch(id, () => {
+            abort.abort();
+        });
+        let result;
+        try {
+            result = await deps.host.curation.forkReview(id, {
+                instruction,
+                allow,
+                maxToolCalls: LOOP1_MAX_TOOL_CALLS,
+                maxOutputTokens: LOOP1_MAX_OUTPUT_TOKENS,
+                deadlineMs: LOOP1_DEADLINE_MS,
+                reviewId,
+                signal: abort.signal,
+            });
+        }
+        finally {
+            await stopWatch();
+        }
+        if (result.status === "completed") {
+            deps.backoff.success(owner);
+            // Anchor the next count at what this review covered. An absent
+            // newestEntry cannot anchor anything — the next review counts
+            // everything, an extra review at worst.
+            if (newestEntry !== undefined) {
+                await writeCursor(deps.host, owner, id, newestEntry);
+            }
+            // The review consumed these hints for good — clear their
+            // refunded ids so a later settle cannot re-fire on them.
+            await clearPendingHints(deps.host, owner, id, hints);
+            // Task B5: announce the changes (no changes → no notice). The
+            // notice is isolated: a failing setAmbient or ledger write
+            // degrades to a missing notice — never a thrown body, which the
+            // refund guard would answer with a phantom refund of an
+            // already-applied review (re-reviewing learned material).
+            await notify(deps.host, id, owner, { ...result, reviewId }).catch((error) => {
+                log(`loop 1: notice after the review of conversation ${String(id)} could not be set: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+        else {
+            if (result.status === "failed")
+                deps.backoff.failure(owner, now());
+            // No review happened for these hints (provider failure, the
+            // parent moving, or the deadline): refund them — the host was
+            // cleared at decision time, so the refund file is the only
+            // place they survive; the next settle merges them back in.
+            await refundHints(deps.host, owner, id, hints);
+        }
+    }
+    /** `/learn`'s seam (Task B5): the same review path minus the
+     *  threshold gate — eligibility still decides, and a mixed
+     *  conversation goes to the digest queue with the mixed-conversation
+     *  notice. The paused/enabled gates deliberately do NOT apply: the
+     *  vacation switch stops the loops, not the user's explicit ask. */
+    const learnNow = (conversationId, user, focus) => enqueueLearn(deps.host, deps.queue, conversationId, user, focus, (owner, id, hints, newestEntry, reviewFocus) => runForkReview(owner, id, hints, newestEntry, reviewFocus, `learn-${randomUUID()}`).catch((error) => {
+        log(`loop 1: /learn review of conversation ${String(id)} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }));
+    return { onRunSettled, learnNow };
+}
+/** Read the per-user cursors file (absent or malformed → empty). */
+async function readCursors(host, user) {
+    const raw = await readStateJson(join(host.stores.user(user).paths.state, CURSORS_FILE), { lastReviewedEntry: {} });
+    // Harden the shape before anyone writes through it: only a plain
+    // object of conversation-id keys → integer entries is a cursor map.
+    const entries = raw?.lastReviewedEntry;
+    if (entries === null || typeof entries !== "object" || Array.isArray(entries)) {
+        return { lastReviewedEntry: {} };
+    }
+    const lastReviewedEntry = {};
+    for (const [key, value] of Object.entries(entries)) {
+        if (typeof value === "number" && Number.isInteger(value)) {
+            lastReviewedEntry[key] = value;
+        }
+    }
+    return { lastReviewedEntry };
+}
+/** Write one conversation's anchor into the cursors file. */
+async function writeCursor(host, user, id, entry) {
+    const cursors = await readCursors(host, user);
+    cursors.lastReviewedEntry[String(id)] = entry;
+    await writeStateJson(host.stores.user(user).paths.state, CURSORS_FILE, cursors);
+}

package/dist/loop2.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Loop 2 — the scheduled idle maintenance pass (`src/loop2.ts`, Task
+ * B3, spec §6.2).
+ *
+ * Clocked by the `curator-tick` job (the only time-based scheduler);
+ * each fired task runs {@link tick} once, and a tick does AT MOST one
+ * pass-fragment: every user's pass is a small resumable queue of
+ * steps with a durable cursor (`pass.json` under the user's state
+ * dir), so a tick interrupted at its self-imposed 5-minute deadline
+ * leaves the cursor pointing at the next step and the NEXT tick
+ * resumes exactly there. Nothing depends on finishing in one go.
+ *
+ * The eligibility gate ({@link eligibleUsers}, spec): a user is due
+ * when they are QUIET — the newest `lastActivityAt` across their
+ * conversations is older than the idle threshold. "No live run" rides
+ * the same clock: activity is stamped at submission admission AND at
+ * run settlement (core's activity seam), so a user with a live run is
+ * never past the idle threshold — the recency check observes it. A
+ * user with no activity at all (never used, or quiet since before the
+ * seam existed) is quiet too. Plus: settings enabled and not paused,
+ * no full pass in the last 24h, and past the install's first-run
+ * grace (the FIRST tick instant + 24h, recorded once in the
+ * extension's own state — the grace is install-wide, per spec: "no
+ * pass until one full interval after install").
+ *
+ * The cursor (`PassCursor`): `steps` is the pass's queue, `done` how
+ * many steps finished (persisted after EVERY step — that is the
+ * resume point), `dailyRunsUsed`/`day` the per-user model-run budget
+ * Task B4's model steps spend (a calendar day rollover re-arms it).
+ *
+ * The step table: B3 owns the two deterministic steps (`archive`,
+ * `overlay-detect`); the five model steps are declared in the queue
+ * and run as no-ops here — Task B4 fills them in.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+/**
+ * The idle threshold (spec §5 pins SIGRUN_IDLE_THRESHOLD's default at
+ * 10 minutes; the extension reads the semantics, not the env — the
+ * host's activity seam already carries it).
+ */
+export declare const IDLE_THRESHOLD_MS = 600000;
+/**
+ * The tick's self-imposed deadline: 5 minutes, well under the worker/
+ * job deadline, so a pass fragment always outlives its own tick.
+ */
+export declare const LOOP2_TICK_DEADLINE_MS = 300000;
+/** The first-run grace: no pass until 24h after the first tick ever. */
+export declare const FIRST_RUN_GRACE_MS: number;
+/** How long a completed pass keeps its user ineligible. */
+export declare const FULL_PASS_INTERVAL_MS: number;
+/** The per-user pass-cursor file name (under the user's state dir). */
+export declare const PASS_FILE = "pass.json";
+/**
+ * The extension-scope state file holding the install-wide first-tick
+ * instant (the grace anchor). Chosen name; recorded here as the seam.
+ */
+export declare const FIRST_TICK_FILE = "loop2-first-tick.json";
+/** One pass's step kinds, in run order (deterministic steps first). */
+export declare const PASS_STEPS: readonly ["archive", "overlay-detect", "overlay-recheck", "digests", "diet", "merge", "targets"];
+/** A pass step's kind (the cursor's queue entries). */
+export type StepId = (typeof PASS_STEPS)[number];
+/** The durable per-user pass cursor (the resume point). */
+export interface PassCursor {
+    /** When this pass started (ISO); the 24h window anchors here. */
+    readonly startedAt: string;
+    /** The step queue, in run order. */
+    readonly steps: readonly StepId[];
+    /** How many steps have finished — the next tick resumes at `steps[done]`. */
+    readonly done: number;
+    /** Model runs spent today (Task B4 decrements the budget). */
+    readonly dailyRunsUsed: number;
+    /** The UTC day the budget counts against (`YYYY-MM-DD`). */
+    readonly day: string;
+}
+/** What {@link tick} accepts (all optional). */
+export interface TickOptions {
+    /** One line per unexpected error; defaults to `console.error`. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * The users due for a pass (spec §6.2): quiet, settings on, past the
+ * first-run grace, and without a completed pass in the last 24h. An
+ * INCOMPLETE pass does not block — the next tick resumes it.
+ */
+export declare function eligibleUsers(host: SigrunHost, now: () => Date): Promise<readonly string[]>;
+/** What {@link createLoop2} needs (all but `host` are optional). */
+export interface Loop2Deps {
+    /** The host the pass reads. */
+    readonly host: SigrunHost;
+    /** The clock every gate and step reads (tests fake it). */
+    readonly now?: () => Date;
+    /** One line per unexpected error; defaults to `console.error`. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * Create loop 2: the tick the factory's task calls (a thin binding of
+ * {@link tick} to its deps). The durable cadence stays the job's —
+ * this creates no timers.
+ */
+export declare function createLoop2(deps: Loop2Deps): {
+    readonly tick: () => Promise<void>;
+};
+/**
+ * One tick: as many pass fragments as fit before the 5-minute
+ * self-deadline. Per-user failures are logged and never break the
+ * tick — the cursor makes every user resumable.
+ */
+export declare function tick(host: SigrunHost, now: () => Date, opts?: TickOptions): Promise<void>;

package/dist/loop2.js

@@ -0,0 +1,323 @@
+/**
+ * Loop 2 — the scheduled idle maintenance pass (`src/loop2.ts`, Task
+ * B3, spec §6.2).
+ *
+ * Clocked by the `curator-tick` job (the only time-based scheduler);
+ * each fired task runs {@link tick} once, and a tick does AT MOST one
+ * pass-fragment: every user's pass is a small resumable queue of
+ * steps with a durable cursor (`pass.json` under the user's state
+ * dir), so a tick interrupted at its self-imposed 5-minute deadline
+ * leaves the cursor pointing at the next step and the NEXT tick
+ * resumes exactly there. Nothing depends on finishing in one go.
+ *
+ * The eligibility gate ({@link eligibleUsers}, spec): a user is due
+ * when they are QUIET — the newest `lastActivityAt` across their
+ * conversations is older than the idle threshold. "No live run" rides
+ * the same clock: activity is stamped at submission admission AND at
+ * run settlement (core's activity seam), so a user with a live run is
+ * never past the idle threshold — the recency check observes it. A
+ * user with no activity at all (never used, or quiet since before the
+ * seam existed) is quiet too. Plus: settings enabled and not paused,
+ * no full pass in the last 24h, and past the install's first-run
+ * grace (the FIRST tick instant + 24h, recorded once in the
+ * extension's own state — the grace is install-wide, per spec: "no
+ * pass until one full interval after install").
+ *
+ * The cursor (`PassCursor`): `steps` is the pass's queue, `done` how
+ * many steps finished (persisted after EVERY step — that is the
+ * resume point), `dailyRunsUsed`/`day` the per-user model-run budget
+ * Task B4's model steps spend (a calendar day rollover re-arms it).
+ *
+ * The step table: B3 owns the two deterministic steps (`archive`,
+ * `overlay-detect`); the five model steps are declared in the queue
+ * and run as no-ops here — Task B4 fills them in.
+ */
+import { join } from "node:path";
+import { readStateJson, writeStateJson } from "./queue.js";
+import { readSettings } from "./settings.js";
+import { archiveUnused } from "./steps/archive.js";
+import { detectOverlayDrift, recheckOverlays } from "./steps/overlays.js";
+import { digestsStep } from "./steps/digests.js";
+import { dietStep } from "./steps/diet.js";
+import { mergeStep } from "./steps/merge.js";
+import { maintainTargets } from "./steps/targets.js";
+/**
+ * The idle threshold (spec §5 pins SIGRUN_IDLE_THRESHOLD's default at
+ * 10 minutes; the extension reads the semantics, not the env — the
+ * host's activity seam already carries it).
+ */
+export const IDLE_THRESHOLD_MS = 600_000;
+/**
+ * The tick's self-imposed deadline: 5 minutes, well under the worker/
+ * job deadline, so a pass fragment always outlives its own tick.
+ */
+export const LOOP2_TICK_DEADLINE_MS = 300_000;
+/** The first-run grace: no pass until 24h after the first tick ever. */
+export const FIRST_RUN_GRACE_MS = 24 * 60 * 60 * 1000;
+/** How long a completed pass keeps its user ineligible. */
+export const FULL_PASS_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** The per-user pass-cursor file name (under the user's state dir). */
+export const PASS_FILE = "pass.json";
+/**
+ * The extension-scope state file holding the install-wide first-tick
+ * instant (the grace anchor). Chosen name; recorded here as the seam.
+ */
+export const FIRST_TICK_FILE = "loop2-first-tick.json";
+/** One pass's step kinds, in run order (deterministic steps first). */
+export const PASS_STEPS = [
+    "archive",
+    "overlay-detect",
+    "overlay-recheck",
+    "digests",
+    "diet",
+    "merge",
+    "targets",
+];
+/** The step-queue kinds Task B4 owns (the five model steps). */
+const MODEL_STEPS = new Set([
+    "overlay-recheck",
+    "digests",
+    "diet",
+    "merge",
+    "targets",
+]);
+/** The UTC calendar day of `at` (budget days are UTC). */
+function dayOf(at) {
+    return at.toISOString().slice(0, 10);
+}
+/** Read the install-wide first-tick instant; absent/malformed → none. */
+async function readFirstTick(host) {
+    const parsed = await readStateJson(join(host.stores.paths.state, FIRST_TICK_FILE), {});
+    if (typeof parsed.firstTickAt !== "string")
+        return undefined;
+    const at = Date.parse(parsed.firstTickAt);
+    return Number.isFinite(at) ? new Date(at) : undefined;
+}
+/** Record the install's first-tick instant (once — the grace anchor). */
+async function writeFirstTick(host, at) {
+    await writeStateJson(host.stores.paths.state, FIRST_TICK_FILE, {
+        firstTickAt: at.toISOString(),
+    });
+}
+/** Read one user's pass cursor; absent/malformed → none (a fresh pass). */
+async function readPass(host, user) {
+    const parsed = await readStateJson(join(host.stores.user(user).paths.state, PASS_FILE), {});
+    const known = new Set(PASS_STEPS);
+    if (typeof parsed.startedAt !== "string")
+        return undefined;
+    if (!Array.isArray(parsed.steps) || parsed.steps.length === 0)
+        return undefined;
+    if (!parsed.steps.every((step) => typeof step === "string" && known.has(step))) {
+        return undefined;
+    }
+    if (typeof parsed.done !== "number" ||
+        !Number.isInteger(parsed.done) ||
+        parsed.done < 0 ||
+        parsed.done > parsed.steps.length) {
+        return undefined;
+    }
+    if (typeof parsed.dailyRunsUsed !== "number" ||
+        !Number.isInteger(parsed.dailyRunsUsed) ||
+        parsed.dailyRunsUsed < 0) {
+        return undefined;
+    }
+    if (typeof parsed.day !== "string")
+        return undefined;
+    return {
+        startedAt: parsed.startedAt,
+        steps: parsed.steps,
+        done: parsed.done,
+        dailyRunsUsed: parsed.dailyRunsUsed,
+        day: parsed.day,
+    };
+}
+/** Persist one user's pass cursor (after every step — the resume point). */
+async function writePass(host, user, cursor) {
+    await writeStateJson(host.stores.user(user).paths.state, PASS_FILE, cursor);
+}
+/**
+ * Whether the user is QUIET: their newest conversation activity is
+ * older than the idle threshold. No activity at all is quiet. A live
+ * run stamps activity at admission, so it is never quiet mid-run.
+ */
+async function isQuiet(host, user, now) {
+    const conversations = await host.conversations.list({ owner: user });
+    let newest;
+    for (const conversation of conversations) {
+        if (conversation.lastActivityAt === undefined)
+            continue;
+        const at = Date.parse(conversation.lastActivityAt);
+        if (Number.isFinite(at) && (newest === undefined || at > newest)) {
+            newest = at;
+        }
+    }
+    return newest === undefined || now.getTime() - newest >= IDLE_THRESHOLD_MS;
+}
+/**
+ * The users due for a pass (spec §6.2): quiet, settings on, past the
+ * first-run grace, and without a completed pass in the last 24h. An
+ * INCOMPLETE pass does not block — the next tick resumes it.
+ */
+export async function eligibleUsers(host, now) {
+    const firstTick = await readFirstTick(host);
+    if (firstTick === undefined)
+        return []; // the grace never started
+    const at = now();
+    if (at.getTime() - firstTick.getTime() < FIRST_RUN_GRACE_MS)
+        return [];
+    const due = [];
+    for (const row of await host.users.list()) {
+        const settings = await readSettings(host, row.user);
+        if (!settings.enabled || settings.paused)
+            continue;
+        if (!(await isQuiet(host, row.user, at)))
+            continue;
+        const pass = await readPass(host, row.user);
+        if (pass !== undefined && pass.done >= pass.steps.length) {
+            // A completed pass: due again only past its 24h window.
+            if (at.getTime() - Date.parse(pass.startedAt) < FULL_PASS_INTERVAL_MS) {
+                continue;
+            }
+        }
+        due.push(row.user);
+    }
+    return due;
+}
+/**
+ * Create loop 2: the tick the factory's task calls (a thin binding of
+ * {@link tick} to its deps). The durable cadence stays the job's —
+ * this creates no timers.
+ */
+export function createLoop2(deps) {
+    const now = deps.now ?? (() => new Date());
+    return {
+        tick: () => tick(deps.host, now, { log: deps.log }),
+    };
+}
+/**
+ * One tick: as many pass fragments as fit before the 5-minute
+ * self-deadline. Per-user failures are logged and never break the
+ * tick — the cursor makes every user resumable.
+ */
+export async function tick(host, now, opts = {}) {
+    const log = opts.log ?? ((message) => console.error(`curator: ${message}`));
+    const startedAt = now();
+    const firstTick = await readFirstTick(host);
+    if (firstTick === undefined) {
+        // The install instant: the grace window opens now, and no pass
+        // runs before it ends (24h of quiet install first).
+        await writeFirstTick(host, startedAt);
+        return;
+    }
+    if (startedAt.getTime() - firstTick.getTime() < FIRST_RUN_GRACE_MS)
+        return;
+    const deadlineAt = startedAt.getTime() + LOOP2_TICK_DEADLINE_MS;
+    for (const user of await eligibleUsers(host, now)) {
+        if (now().getTime() >= deadlineAt)
+            break;
+        await runPass(host, user, now, deadlineAt, log).catch((error) => {
+            log(`loop 2: pass for ${user} failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+}
+/** The step table: B3's deterministic steps and B4's model steps. */
+const STEP_RUNNERS = {
+    archive: archiveUnused,
+    "overlay-detect": detectOverlayDrift,
+    "overlay-recheck": recheckOverlays,
+    digests: digestsStep,
+    diet: dietStep,
+    merge: mergeStep,
+    targets: maintainTargets,
+};
+/**
+ * Walk one user's pass from its cursor: run steps while the tick's
+ * deadline holds, persisting `done` after every step. A MODEL step that
+ * answers false (the daily budget is spent) STOPS the pass for the day:
+ * the cursor keeps pointing at that step, and the next tick — or the
+ * next day's re-armed budget — resumes exactly there.
+ */
+async function runPass(host, user, now, deadlineAt, log) {
+    const today = dayOf(now());
+    const read = await readPass(host, user);
+    let fresh;
+    if (read === undefined || read.done >= read.steps.length) {
+        // No pass yet, or the previous pass completed (its 24h window is
+        // why the user is eligible again): a fresh cursor from step one.
+        fresh = {
+            startedAt: now().toISOString(),
+            steps: [...PASS_STEPS],
+            done: 0,
+            dailyRunsUsed: 0,
+            day: today,
+        };
+    }
+    else if (read.day !== today) {
+        // A new day re-arms the model-run budget mid-pass.
+        fresh = { ...read, day: today, dailyRunsUsed: 0 };
+    }
+    else {
+        fresh = read;
+    }
+    // The cursor holder — one mutable slot every writer goes through, so
+    // the budget closure always sees the live cursor.
+    const state = { cursor: fresh };
+    await writePass(host, user, state.cursor);
+    // The daily model-run budget (Task B4): `dailyRuns` minus what today
+    // already spent. Every spend persists the cursor BEFORE its run —
+    // a crash may waste a run, it never overspends the day.
+    const settings = await readSettings(host, user);
+    const budget = {
+        left: () => Math.max(0, settings.dailyRuns - state.cursor.dailyRunsUsed),
+        spend: async () => {
+            if (state.cursor.dailyRunsUsed >= settings.dailyRuns)
+                return false;
+            state.cursor = {
+                ...state.cursor,
+                dailyRunsUsed: state.cursor.dailyRunsUsed + 1,
+            };
+            await writePass(host, user, state.cursor);
+            return true;
+        },
+    };
+    while (state.cursor.done < state.cursor.steps.length) {
+        const cursor = state.cursor;
+        // Out of tick budget: stop BEFORE the next step — the cursor is
+        // the resume point the next tick picks up.
+        if (now().getTime() >= deadlineAt)
+            return;
+        const step = cursor.steps[cursor.done];
+        const runner = STEP_RUNNERS[step];
+        const deps = {
+            host,
+            user,
+            now,
+            deadlineAt,
+            budget,
+            log,
+        };
+        try {
+            if (MODEL_STEPS.has(step)) {
+                const proceed = await runner(deps);
+                if (!proceed) {
+                    // The daily cap (or the tick deadline) stopped the pass: the
+                    // cursor stays at this step — the next tick resumes it, and a
+                    // new day re-arms the budget.
+                    log(`loop 2: ${user} stopped at step "${step}" for the day`);
+                    return;
+                }
+            }
+            else {
+                await runner(host, user, now);
+            }
+        }
+        catch (error) {
+            // The step failed; the pass moves on — a deterministic step
+            // wedging the cursor forever would be worse than skipping it
+            // this pass (idempotent steps make a later pass safe).
+            log(`loop 2: ${user} step "${step}" failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        state.cursor = { ...state.cursor, done: state.cursor.done + 1 };
+        await writePass(host, user, state.cursor);
+    }
+}