@sigrun/ext-curator 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-02
+### Added
+- Scaffold: the `createCurator` factory (the loader contract) declaring the
+  `curator` extension, the `curator-tick` job over the `curator.tick` task,
+  the `/learn` command, the `curator.notice` ambient kind, the
+  `curator.overlay-question` interaction kind, the curator view surface, and
+  per-user settings (`enabled`, `paused`, `idleModel`, `threshold`,
+  `dailyRuns`) read with defaults.
+- Loop 2: the idle maintenance pass — the `curator.tick` task running one
+  resumable pass fragment per fired tick (a durable per-user step cursor
+  under a 5-minute self-deadline), the eligibility gate (quiet user, no
+  full pass in 24h, first-run grace), and the deterministic steps:
+  archiving skills unused for 30 days (pinned and job-referenced spared)
+  and reaping overlays orphaned for 30 days; overlay drift detection
+  queues changed upstreams for re-check.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @sigrun/ext-curator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The curator built-in extension for
+[sigrun](https://github.com/sigrun-ai/sigrun): per-user curation loops
+over learned skills and curation targets.
+
+- **Loop 1 — fork review.** After a settled run in an owned conversation
+  (threshold model calls since the last review, or pending review hints),
+  the curator forks the conversation at its newest entry and drives a
+  bounded review run whose writes land in the owner's learned-skill
+  store.
+- **Loop 2 — idle pass.** The `curator-tick` job (every 15 minutes)
+  walks idle users through a resumable pass: archiving unused skills,
+  re-checking drifted overlays, digesting conversations, dieting and
+  merging skills, and running target maintenance.
+
+Per-user settings (via the user's scoped settings store) control it:
+`enabled` (default true), `paused` (default false), `idleModel`,
+`threshold` (default 10), `dailyRuns` (default 12). `/learn [focus]`
+requests a review on demand; the curator view lists skills, overlays and
+the change feed with per-review undo.
+
+## What you see
+
+Mostly nothing. When a review CHANGES something, the originating
+conversation's status line carries one quiet notice — a
+`Learned: …` line per change with a button to the **Curator** view
+(the notice never lands in the transcript, so forks never replay it,
+and it is never pushed to a notifier or chat channel).
+
+The **Curator** view (per user; only your own data ever renders) lists
+
+- **Learned skills** — name, description, last used, with a pin toggle
+  and archive/restore on each;
+- **Overlays** — your notes on upstream skills, flagged `orphaned`
+  when the upstream vanished;
+- **The change feed** — the newest 50 changes, grouped by review, each
+  group with an **Undo review** button that reverts every change that
+  review made (and clears its notice);
+- a **pause switch** — `Pause curation` stops both loops for you
+  without disabling anything else; the view and `/learn` keep working
+  while paused.
+
+Undo is two clicks (notice → view → Undo), not one: the notice lives
+on the display-only ambient seam, so the undo action lives on the
+view.
+
+## `/learn [focus]`
+
+`/learn` asks for a review of the conversation NOW — bypassing the
+call-count threshold but keeping every eligibility rule. In a
+conversation with other participants the answer says so and the
+owner's hints are queued; the digest reviews the OWNER'S attributed
+turns only — another participant's words never enter it. Focus, when
+given, rides the review's instruction. `/learn` works
+while paused: the pause switch stops the automatic loops, not your
+own explicit ask.
+
+This package is a sigrun built-in: sigrun core ships and loads it by
+default (`builtinExtensions.curator: false` disables it). It is not
+useful outside sigrun.

package/dist/backoff.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The per-user review backoff (`src/backoff.ts`, Task B2): a failed
+ * review pauses THAT user's reviews on openclaw's ladder — 15, then
+ * 30, then 60 minutes (spec §6.2) — so background curation never adds
+ * to an already degraded provider. A success resets the ladder.
+ *
+ * In-memory by design (the plan's interface): the ladder protects the
+ * provider, not the user's data, and a restart re-arms it clean.
+ */
+/**
+ * The backoff ladder, per user. Every method takes `now` (the fake
+ * clock seam) — the loop reads one clock for every decision.
+ */
+export declare class Backoff {
+    private readonly users;
+    /** Whether `user`'s reviews are paused at `now`. */
+    blocked(user: string, now: Date): boolean;
+    /** Step the ladder: block `user` for 15, then 30, then 60 minutes. */
+    failure(user: string, now: Date): void;
+    /** A success resets the ladder entirely. */
+    success(user: string): void;
+}

package/dist/backoff.js

@@ -0,0 +1,39 @@
+/**
+ * The per-user review backoff (`src/backoff.ts`, Task B2): a failed
+ * review pauses THAT user's reviews on openclaw's ladder — 15, then
+ * 30, then 60 minutes (spec §6.2) — so background curation never adds
+ * to an already degraded provider. A success resets the ladder.
+ *
+ * In-memory by design (the plan's interface): the ladder protects the
+ * provider, not the user's data, and a restart re-arms it clean.
+ */
+/** The ladder steps, in minutes (15 → 30 → 60). */
+const STEPS_MINUTES = [15, 30, 60];
+/**
+ * The backoff ladder, per user. Every method takes `now` (the fake
+ * clock seam) — the loop reads one clock for every decision.
+ */
+export class Backoff {
+    users = new Map();
+    /** Whether `user`'s reviews are paused at `now`. */
+    blocked(user, now) {
+        const state = this.users.get(user);
+        if (state === undefined || state.unblockAt === undefined)
+            return false;
+        return now.getTime() < state.unblockAt;
+    }
+    /** Step the ladder: block `user` for 15, then 30, then 60 minutes. */
+    failure(user, now) {
+        const state = this.users.get(user) ?? { failures: 0 };
+        const step = Math.min(state.failures, STEPS_MINUTES.length - 1);
+        const minutes = STEPS_MINUTES[step];
+        this.users.set(user, {
+            failures: state.failures + 1,
+            unblockAt: now.getTime() + minutes * 60_000,
+        });
+    }
+    /** A success resets the ladder entirely. */
+    success(user) {
+        this.users.delete(user);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * sigrun-ext-curator: the curator factory (the loader contract).
+ *
+ * The sigrun extension-package contract (sigrun's src/harness/loader.ts):
+ * the default export is a FACTORY DECLARING the host parameter (arity 1 —
+ * the host rule), called once at boot, before `Harness.open` reads the
+ * registry. The factory registers handlers only — no timers, no I/O in
+ * the factory body (the lifecycle rule); the loops start through their
+ * own surfaces (the settled-run handler and the job's task).
+ *
+ * What the scaffold declares (Task B1; the behaviors land with their
+ * tasks):
+ *
+ * - `extension` — `defineExtension({ name: "curator", tasks: [tickTask] })`:
+ *   the name is the loader slug; the task is the durable body the job
+ *   fires.
+ * - `jobs` — `curator-tick`, `every: "15m"` (spec §5 pins the interval),
+ *   `action: { kind: "task", task: "curator.tick" }` — jobs are the only
+ *   time-based scheduler, so loop 2's cadence is a job, never a timer.
+ * - `runSettled` — loop 1's decision hook (Task B2): decides on settle
+ *   and enqueues a review; the review itself runs on the per-user
+ *   queue, never inside the hook deadline.
+ * - `commands` — `/learn [focus]`: enqueue a loop 1 review of this
+ *   conversation now, bypassing the threshold but not eligibility
+ *   (Task B5).
+ * - `ambientKinds` / `interactionKinds` — the seam's write-gate
+ *   declarations: `curator.notice` (the post-review ambient notice) and
+ *   `curator.overlay-question` (the unsure-overlay question).
+ * - `surfaces` — the curator view: learned skills (pin,
+ *   archive/restore), overlays, the feed grouped by review with undo,
+ *   and the pause switch (Task B5).
+ *
+ * Per-user settings (`src/settings.ts`) are read live per event through
+ * the host's per-user scoped store — nothing is captured at factory time.
+ */
+import type { AnyTask } from "@earendil-works/pi-durable";
+import type { SigrunExtensionResult, SigrunHost } from "@sigrun/sigrun/extension";
+/** The durable task kind the tick job fires (TaskRecord.kind). */
+export declare const CURATOR_TICK_TASK = "curator.tick";
+/** The definition version persisted with the task. */
+export declare const CURATOR_TICK_VERSION = 1;
+/** The tick job's name (spec §5: every 15 minutes). */
+export declare const CURATOR_TICK_JOB = "curator-tick";
+/** The post-review ambient notice key (Task B5's display surface). */
+export declare const CURATOR_NOTICE_KIND = "curator.notice";
+/** The unsure-overlay question kind (Task B4's interaction). */
+export declare const CURATOR_OVERLAY_QUESTION_KIND = "curator.overlay-question";
+/**
+ * Loop 2's durable body (Task B3): one phase calling `tick(host, now)`
+ * — as many pass fragments as the tick's own 5-minute deadline
+ * allows; unfinished steps resume on the next fired tick through the
+ * per-user pass cursor (`pass.json`). The scaffold's terminal-commit
+ * shape stays: whatever the pass did, the task phase itself only
+ * runs the tick and completes.
+ */
+export declare function createTickTask(host: SigrunHost): AnyTask;
+export { createLearnCommand } from "./learn.js";
+export type { LearnNow, LearnOutcome } from "./learn.js";
+export { createCuratorView, viewAccess, groupFeed, VIEW_FEED_LIMIT } from "./view.js";
+export type { CuratorViewData } from "./view.js";
+/**
+ * The sigrun extension-package factory: builds the curator's declared
+ * surface over the host. One factory call, one wiring. The constructed
+ * loop-1 state (the review queue, the backoff ladder) is plain memory
+ * the handlers use — no timers, no I/O run here.
+ */
+export default function createCurator(host: SigrunHost): SigrunExtensionResult;
+export { parseCuratorSettings, readSettings, DEFAULT_CURATOR_SETTINGS, } from "./settings.js";
+export { notify, readNotices } from "./notices.js";
+export type { NoticeRecord } from "./notices.js";
+export type { CuratorSettings } from "./settings.js";
+export { createLoop1, CURSORS_FILE, LOOP1_MAX_TOOL_CALLS, LOOP1_MAX_OUTPUT_TOKENS, LOOP1_DEADLINE_MS, } from "./loop1.js";
+export type { Loop1Deps } from "./loop1.js";
+export { enqueueLearn, learnReviewId } from "./learn.js";
+export { createLoop2, eligibleUsers, tick, IDLE_THRESHOLD_MS, LOOP2_TICK_DEADLINE_MS, FIRST_RUN_GRACE_MS, FULL_PASS_INTERVAL_MS, PASS_FILE, PASS_STEPS, FIRST_TICK_FILE, } from "./loop2.js";
+export type { StepId, PassCursor, TickOptions, Loop2Deps } from "./loop2.js";
+export { archiveUnused, ARCHIVE_UNUSED_DAYS, ARCHIVE_UNUSED_MS, } from "./steps/archive.js";
+export { detectOverlayDrift, OverlayRecheckQueue, RECHECK_QUEUE_FILE, recheckOverlays, overlayQuestionHandler, } from "./steps/overlays.js";
+export { digestsStep, reviewDigest, DIGEST_VIEW_GRACE_MS } from "./steps/digests.js";
+export { dietStep, DIET_BYTES, DIET_UNCHANGED_MS } from "./steps/diet.js";
+export { mergeStep } from "./steps/merge.js";
+export { maintainTargets } from "./steps/targets.js";
+export { digestRunWithBudget, parseVerdict, MODEL_STEP_MAX_TOOL_CALLS, MODEL_STEP_MAX_OUTPUT_TOKENS, } from "./steps/run.js";
+export type { ModelStepDeps, RunBudget, DigestRun, DigestRunInput } from "./steps/run.js";
+export { Backoff } from "./backoff.js";
+export { ReviewQueue, queueDigest, readDigestQueue, removeDigestEntry, } from "./queue.js";
+export type { ReviewJob } from "./queue.js";
+export { reviewInstruction } from "./prompts.js";
+export type { ReviewInstructionOpts } from "./prompts.js";

package/dist/index.js

@@ -0,0 +1,143 @@
+/**
+ * sigrun-ext-curator: the curator factory (the loader contract).
+ *
+ * The sigrun extension-package contract (sigrun's src/harness/loader.ts):
+ * the default export is a FACTORY DECLARING the host parameter (arity 1 —
+ * the host rule), called once at boot, before `Harness.open` reads the
+ * registry. The factory registers handlers only — no timers, no I/O in
+ * the factory body (the lifecycle rule); the loops start through their
+ * own surfaces (the settled-run handler and the job's task).
+ *
+ * What the scaffold declares (Task B1; the behaviors land with their
+ * tasks):
+ *
+ * - `extension` — `defineExtension({ name: "curator", tasks: [tickTask] })`:
+ *   the name is the loader slug; the task is the durable body the job
+ *   fires.
+ * - `jobs` — `curator-tick`, `every: "15m"` (spec §5 pins the interval),
+ *   `action: { kind: "task", task: "curator.tick" }` — jobs are the only
+ *   time-based scheduler, so loop 2's cadence is a job, never a timer.
+ * - `runSettled` — loop 1's decision hook (Task B2): decides on settle
+ *   and enqueues a review; the review itself runs on the per-user
+ *   queue, never inside the hook deadline.
+ * - `commands` — `/learn [focus]`: enqueue a loop 1 review of this
+ *   conversation now, bypassing the threshold but not eligibility
+ *   (Task B5).
+ * - `ambientKinds` / `interactionKinds` — the seam's write-gate
+ *   declarations: `curator.notice` (the post-review ambient notice) and
+ *   `curator.overlay-question` (the unsure-overlay question).
+ * - `surfaces` — the curator view: learned skills (pin,
+ *   archive/restore), overlays, the feed grouped by review with undo,
+ *   and the pause switch (Task B5).
+ *
+ * Per-user settings (`src/settings.ts`) are read live per event through
+ * the host's per-user scoped store — nothing is captured at factory time.
+ */
+import { defineExtension, defineTask } from "@earendil-works/pi-durable";
+import { createLoop1 } from "./loop1.js";
+import { createLoop2 } from "./loop2.js";
+import { createLearnCommand } from "./learn.js";
+import { createCuratorView } from "./view.js";
+import { Backoff } from "./backoff.js";
+import { ReviewQueue } from "./queue.js";
+import { overlayQuestionHandler } from "./steps/overlays.js";
+/** The durable task kind the tick job fires (TaskRecord.kind). */
+export const CURATOR_TICK_TASK = "curator.tick";
+/** The definition version persisted with the task. */
+export const CURATOR_TICK_VERSION = 1;
+/** The tick job's name (spec §5: every 15 minutes). */
+export const CURATOR_TICK_JOB = "curator-tick";
+/** The post-review ambient notice key (Task B5's display surface). */
+export const CURATOR_NOTICE_KIND = "curator.notice";
+/** The unsure-overlay question kind (Task B4's interaction). */
+export const CURATOR_OVERLAY_QUESTION_KIND = "curator.overlay-question";
+/**
+ * Loop 2's durable body (Task B3): one phase calling `tick(host, now)`
+ * — as many pass fragments as the tick's own 5-minute deadline
+ * allows; unfinished steps resume on the next fired tick through the
+ * per-user pass cursor (`pass.json`). The scaffold's terminal-commit
+ * shape stays: whatever the pass did, the task phase itself only
+ * runs the tick and completes.
+ */
+export function createTickTask(host) {
+    return defineTask({
+        name: CURATOR_TICK_TASK,
+        version: CURATOR_TICK_VERSION,
+        initial: () => ({ phase: "tick" }),
+        phases: {
+            tick: async (_task, runtime, context) => {
+                await createLoop2({ host }).tick();
+                await runtime.commit(() => ({
+                    status: "terminal",
+                    outcome: { status: "completed", result: undefined },
+                }), context);
+            },
+        },
+        abort: async (_task, runtime, context) => {
+            await runtime.commit(() => ({
+                status: "terminal",
+                outcome: { status: "aborted", reason: "job disabled or deleted" },
+            }), context);
+        },
+    });
+}
+export { createLearnCommand } from "./learn.js";
+export { createCuratorView, viewAccess, groupFeed, VIEW_FEED_LIMIT } from "./view.js";
+/**
+ * The sigrun extension-package factory: builds the curator's declared
+ * surface over the host. One factory call, one wiring. The constructed
+ * loop-1 state (the review queue, the backoff ladder) is plain memory
+ * the handlers use — no timers, no I/O run here.
+ */
+export default function createCurator(host) {
+    const loop1 = createLoop1({
+        host,
+        queue: new ReviewQueue(),
+        backoff: new Backoff(),
+    });
+    // Loop 2 needs no factory-time binding: the tick task builds its own
+    // `createLoop2({ host })` per phase (the job is the only scheduler).
+    // The overlay question's answer applies here (Task B4): the
+    // unsure-overlay interaction seeded by the re-check step settles
+    // through the generic interaction lifecycle.
+    const overlayAnswers = overlayQuestionHandler(host);
+    return {
+        extension: defineExtension({
+            name: "curator",
+            tasks: [createTickTask(host)],
+        }),
+        // Loop 1's decision hook: decide + enqueue + return (the review
+        // runs on the queue; the hook deadline never bounds it).
+        runSettled: loop1.onRunSettled,
+        // The overlay question's answer hook (the design's only prompt).
+        interactionSettled: overlayAnswers.interactionSettled,
+        // Loop 2's cadence: the ONLY time-based scheduler (the worker
+        // `every` is retired; jobs are the timer).
+        jobs: [
+            {
+                name: CURATOR_TICK_JOB,
+                schedule: { every: "15m" },
+                action: { kind: "task", task: CURATOR_TICK_TASK },
+            },
+        ],
+        commands: [createLearnCommand(host, loop1.learnNow)],
+        ambientKinds: [CURATOR_NOTICE_KIND],
+        interactionKinds: [CURATOR_OVERLAY_QUESTION_KIND],
+        surfaces: { views: [createCuratorView(host)] },
+    };
+}
+export { parseCuratorSettings, readSettings, DEFAULT_CURATOR_SETTINGS, } from "./settings.js";
+export { notify, readNotices } from "./notices.js";
+export { createLoop1, CURSORS_FILE, LOOP1_MAX_TOOL_CALLS, LOOP1_MAX_OUTPUT_TOKENS, LOOP1_DEADLINE_MS, } from "./loop1.js";
+export { enqueueLearn, learnReviewId } from "./learn.js";
+export { createLoop2, eligibleUsers, tick, IDLE_THRESHOLD_MS, LOOP2_TICK_DEADLINE_MS, FIRST_RUN_GRACE_MS, FULL_PASS_INTERVAL_MS, PASS_FILE, PASS_STEPS, FIRST_TICK_FILE, } from "./loop2.js";
+export { archiveUnused, ARCHIVE_UNUSED_DAYS, ARCHIVE_UNUSED_MS, } from "./steps/archive.js";
+export { detectOverlayDrift, OverlayRecheckQueue, RECHECK_QUEUE_FILE, recheckOverlays, overlayQuestionHandler, } from "./steps/overlays.js";
+export { digestsStep, reviewDigest, DIGEST_VIEW_GRACE_MS } from "./steps/digests.js";
+export { dietStep, DIET_BYTES, DIET_UNCHANGED_MS } from "./steps/diet.js";
+export { mergeStep } from "./steps/merge.js";
+export { maintainTargets } from "./steps/targets.js";
+export { digestRunWithBudget, parseVerdict, MODEL_STEP_MAX_TOOL_CALLS, MODEL_STEP_MAX_OUTPUT_TOKENS, } from "./steps/run.js";
+export { Backoff } from "./backoff.js";
+export { ReviewQueue, queueDigest, readDigestQueue, removeDigestEntry, } from "./queue.js";
+export { reviewInstruction } from "./prompts.js";

package/dist/learn.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `/learn [focus]` (`src/learn.ts`, Task B5): the foreground command
+ * that asks for a review NOW — the same review loop 1 would run, but
+ * bypassing the THRESHOLD (the user asked; no call-count gate stands
+ * between them and a review) while keeping every ELIGIBILITY rule (an
+ * internal conversation, or a conversation whose owner is not the
+ * caller, still gets nothing).
+ *
+ * The command only ENQUEUES (loop 1's queue owns the review body —
+ * the command's route deadline never bounds a review) and answers
+ * `{notice}` naming what will happen:
+ *
+ * - owner-only conversation → "a curator review of this conversation
+ *   will run now" (with the focus when given);
+ * - a MIXED conversation (loop 1 would never fork it) → the answer
+ *   says the curator only learns from the owner's own messages: the
+ *   conversation goes to loop 2's digest queue, which reviews only
+ *   the owner's attributed turns.
+ *
+ * The hint set folds in like every review (pending hints, refunded
+ * batches), and `focus` rides the instruction (`reviewInstruction`).
+ */
+import type { ConversationId, EntryId } from "@earendil-works/pi-durable";
+import type { CurationHint, ExtensionCommandContribution, SigrunHost } from "@sigrun/sigrun/extension";
+/** What {@link createLearnCommand} runs the request through (loop 1's
+ *  `learnNow`, so the command and the settle hook share ONE review
+ *  path). */
+export type LearnNow = (conversationId: ConversationId, user: string, focus: string | undefined) => Promise<LearnOutcome>;
+/** What `learnNow` answers: which path took the request. */
+export type LearnOutcome = {
+    readonly kind: "queued";
+} | {
+    readonly kind: "digest";
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+/**
+ * The `/learn` command contribution, bound to the host and loop 1's
+ * `learnNow`. Runs with the invoking principal: its `user` is the
+ * owner the review would learn for.
+ */
+export declare function createLearnCommand(host: SigrunHost, learnNow: LearnNow): ExtensionCommandContribution;
+/**
+ * The `/learn` enqueue path, shared by the command and usable directly:
+ * decide eligibility, then fork-queue or digest-queue — never running a
+ * review on the caller's stack. Exported for loop 1 to expose as its
+ * `learnNow` seam (the same decision tree the settle hook walks, minus
+ * the threshold gate and the paused/enabled gates: `/learn` works while
+ * paused — the vacation switch stops the LOOPS, not the user's own
+ * explicit ask).
+ */
+export declare function enqueueLearn(host: SigrunHost, queue: {
+    enqueue(job: {
+        readonly user: string;
+        readonly work: () => Promise<void>;
+    }): void;
+}, conversationId: ConversationId, user: string, focus: string | undefined, reviewBody: (owner: string, id: ConversationId, hints: readonly CurationHint[], newestEntry: EntryId | undefined, focus: string | undefined) => Promise<void>): Promise<LearnOutcome>;
+/** The review id a `/learn`-triggered review runs under. */
+export declare function learnReviewId(): string;

package/dist/learn.js

@@ -0,0 +1,97 @@
+/**
+ * `/learn [focus]` (`src/learn.ts`, Task B5): the foreground command
+ * that asks for a review NOW — the same review loop 1 would run, but
+ * bypassing the THRESHOLD (the user asked; no call-count gate stands
+ * between them and a review) while keeping every ELIGIBILITY rule (an
+ * internal conversation, or a conversation whose owner is not the
+ * caller, still gets nothing).
+ *
+ * The command only ENQUEUES (loop 1's queue owns the review body —
+ * the command's route deadline never bounds a review) and answers
+ * `{notice}` naming what will happen:
+ *
+ * - owner-only conversation → "a curator review of this conversation
+ *   will run now" (with the focus when given);
+ * - a MIXED conversation (loop 1 would never fork it) → the answer
+ *   says the curator only learns from the owner's own messages: the
+ *   conversation goes to loop 2's digest queue, which reviews only
+ *   the owner's attributed turns.
+ *
+ * The hint set folds in like every review (pending hints, refunded
+ * batches), and `focus` rides the instruction (`reviewInstruction`).
+ */
+import { randomUUID } from "node:crypto";
+import { clearPendingHints, mergeHints, pendingHintsFor, queueDigest, } from "./queue.js";
+/** The command's `{notice}` for each outcome (the wording is pinned by
+ *  the tests only in the mixed case; the queued wording names focus). */
+function noticeFor(outcome, focus) {
+    switch (outcome.kind) {
+        case "queued": {
+            const withFocus = focus === "" ? "" : ` (focus: ${focus})`;
+            return `A curator review of this conversation will run now${withFocus}.`;
+        }
+        case "digest":
+            return "This conversation has other participants: the curator only learns from your own messages, and the review will run from those alone.";
+        case "refused":
+            return `No curator review: ${outcome.reason}`;
+    }
+}
+/**
+ * The `/learn` command contribution, bound to the host and loop 1's
+ * `learnNow`. Runs with the invoking principal: its `user` is the
+ * owner the review would learn for.
+ */
+export function createLearnCommand(host, learnNow) {
+    return {
+        name: "learn",
+        description: "Ask the curator to review this conversation now",
+        args: "[focus]",
+        run: async (ctx) => {
+            const user = ctx.principal.user;
+            if (user === undefined) {
+                return { notice: "No curator review: you are not signed in." };
+            }
+            const focus = ctx.args.trim();
+            const outcome = await learnNow(ctx.conversationId, user, focus === "" ? undefined : focus);
+            return { notice: noticeFor(outcome, focus === "" ? undefined : focus) };
+        },
+    };
+}
+/**
+ * The `/learn` enqueue path, shared by the command and usable directly:
+ * decide eligibility, then fork-queue or digest-queue — never running a
+ * review on the caller's stack. Exported for loop 1 to expose as its
+ * `learnNow` seam (the same decision tree the settle hook walks, minus
+ * the threshold gate and the paused/enabled gates: `/learn` works while
+ * paused — the vacation switch stops the LOOPS, not the user's own
+ * explicit ask).
+ */
+export async function enqueueLearn(host, queue, conversationId, user, focus, reviewBody) {
+    const eligibility = await host.curation.eligibility(conversationId);
+    if (eligibility.internal) {
+        return { kind: "refused", reason: "this conversation is internal" };
+    }
+    if (eligibility.owner !== user) {
+        return {
+            kind: "refused",
+            reason: "this conversation belongs to another user",
+        };
+    }
+    const hints = mergeHints(await pendingHintsFor(host, user, conversationId), await host.curation.takeHints(conversationId));
+    if (eligibility.ownerOnly && eligibility.unattributed === 0) {
+        queue.enqueue({
+            user,
+            work: () => reviewBody(user, conversationId, hints, eligibility.newestEntry, focus).catch(() => undefined),
+        });
+        return { kind: "queued" };
+    }
+    // Mixed authorship or unattributed entries: never forked — the
+    // digest queue (loop 2 reviews only the owner's attributed turns).
+    await queueDigest(host, user, conversationId, hints);
+    await clearPendingHints(host, user, conversationId, hints);
+    return { kind: "digest" };
+}
+/** The review id a `/learn`-triggered review runs under. */
+export function learnReviewId() {
+    return `learn-${randomUUID()}`;
+}

package/dist/loop1.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 type { ConversationId } from "@earendil-works/pi-durable";
+import type { ExtensionRunSettledHandler, SigrunHost } from "@sigrun/sigrun/extension";
+import { Backoff } from "./backoff.js";
+import { type LearnOutcome } from "./learn.js";
+/** The per-conversation cursor file under the user's state dir. */
+export declare const CURSORS_FILE = "cursors.json";
+/** The fork-review bounds (spec §6.2: a handful of calls, small output, ~2 minutes). */
+export declare const LOOP1_MAX_TOOL_CALLS = 8;
+export declare const LOOP1_MAX_OUTPUT_TOKENS = 2048;
+export declare const LOOP1_DEADLINE_MS = 120000;
+/** What {@link createLoop1} needs (all but `now` are required). */
+export interface Loop1Deps {
+    readonly host: SigrunHost;
+    /** The per-user review queue — the handler never runs a review itself. */
+    readonly queue: {
+        enqueue(job: {
+            readonly user: string;
+            readonly work: () => Promise<void>;
+        }): void;
+    };
+    /** The per-user failure ladder this loop steps. */
+    readonly backoff: Backoff;
+    /** The clock every backoff decision reads (tests fake it). */
+    readonly now?: () => Date;
+    /** One line per unexpected error; defaults to `console.error`. */
+    readonly log?: (message: string) => void;
+}
+/**
+ * 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 declare function createLoop1(deps: Loop1Deps): {
+    readonly onRunSettled: ExtensionRunSettledHandler;
+    readonly learnNow: (conversationId: ConversationId, user: string, focus: string | undefined) => Promise<LearnOutcome>;
+};