om-memory-system 4.30.1 → 4.31.2

package/dist/services/profile-cleanup-routes.js

@@ -1,8 +1,9 @@
 import * as aiCleanup from "./ai-cleanup-handlers.js";
 import * as autoCleanup from "./auto-cleanup-handlers.js";
+import * as categoryCleanup from "./api-handlers.js";
 /**
- * The profile cleanup routes: AI Cleanup (start, status, stop, apply) and the undo of the
- * last automatic cleanup. Returns the JSON body, or undefined when the path and method are
+ * The profile cleanup routes: AI Cleanup (start, status, stop, apply), the undo of the
+ * last automatic cleanup, and category cleanup (start, status, apply, undo). Returns the JSON body, or undefined when the path and method are
  * not a cleanup route. The body is read only for the routes that need it.
  */
 export async function routeProfileCleanup(path, method, url, readBody) {
@@ -28,5 +29,21 @@ export async function routeProfileCleanup(path, method, url, readBody) {
         const body = await readBody();
         return autoCleanup.handleAutoCleanupUndo(body.userId || undefined);
     }
+    if (path === "/api/user-profile/category-cleanup") {
+        if (method === "POST") {
+            const body = await readBody();
+            return categoryCleanup.handleCategoryCleanupStart(body.userId || undefined);
+        }
+        if (method === "GET")
+            return categoryCleanup.handleCategoryCleanupStatus(queryUser);
+    }
+    if (path === "/api/user-profile/category-cleanup/apply" && method === "POST") {
+        const body = await readBody();
+        return categoryCleanup.handleCategoryCleanupApply(body.userId || undefined, body);
+    }
+    if (path === "/api/user-profile/category-cleanup/undo" && method === "POST") {
+        const body = await readBody();
+        return categoryCleanup.handleCategoryCleanupUndo(body.userId || undefined);
+    }
     return undefined;
 }

package/dist/services/settings-snapshot.js

@@ -34,6 +34,9 @@ const editable = [
     "rerankerModel",
     "rerankerTimeoutMs",
     "keywordMode",
+    "skillLearning",
+    "skillLearningRedact",
+    "skillFolders",
     ...MEMORY_LIMIT_SETTINGS,
 ];
 /** Keys a project config cannot override, so the page always shows the global value. */
@@ -55,6 +58,8 @@ const globalOnly = [
     "rerankerModel",
     "rerankerApiKey",
     "rerankerTimeoutMs",
+    "skillLearningRedact",
+    "skillFolders",
 ];
 function readSettingsFile(path) {
     if (!path)
@@ -112,7 +117,8 @@ export function getSettingsSnapshot(directory) {
             return [key, nestedMemorySetting(limitRule, global, project)];
         }
         const projectOverrides = Object.hasOwn(project, key) &&
-            (key === "captureTrace"
+            // A project may turn these off, never on.
+            (key === "captureTrace" || key === "skillLearning"
                 ? project[key] === false
                 : !key.endsWith("RetentionDays") && !globalOnly.includes(key));
         const source = projectOverrides

package/dist/services/skill-learning/agent-proposals.d.ts

@@ -0,0 +1,76 @@
+import { type SkillRef } from "./draft-turns.js";
+import { NO_CHANGE_PROPOSED } from "./drafting.js";
+import { type SkillProposal } from "./proposal-store.js";
+import { type SkillIndex } from "./skill-index.js";
+import type { SkillStore } from "./store.js";
+/**
+ * The agent path (design §8): the coding agent reads a skill's evidence and
+ * proposes a revised file itself. No model call. The proposal is pending, and
+ * apply still waits for the user's request.
+ */
+export declare const DEFAULT_EVIDENCE_TURNS = 10;
+export declare const MAX_EVIDENCE_TURNS = 20;
+export declare const MAX_PROPOSED_BYTES: number;
+export interface AgentDeps {
+    store: SkillStore;
+    index: SkillIndex;
+    now: number;
+}
+export interface EvidenceTurn {
+    id: number;
+    createdAt: number;
+    host: string;
+    prompt: string;
+    replies: string[];
+    tools: Array<{
+        name: string;
+        outcome: string;
+        error: string | null;
+    }>;
+    /** A tool call failed after the skill loaded in this turn. */
+    failedAfterUse: boolean;
+    /** Text was cut to keep the turn within 4,000 characters, or the total within 60,000. */
+    cut: boolean;
+}
+export type AgentFailure = {
+    ok: false;
+    code: string;
+    message: string;
+};
+export type EvidenceResult = {
+    ok: true;
+    ref: SkillRef;
+    content: string;
+    turns: EvidenceTurn[];
+} | AgentFailure;
+export type ProposeResult = {
+    ok: true;
+    code: "proposed";
+    proposal: SkillProposal;
+} | {
+    ok: true;
+    code: "no-change";
+    message: typeof NO_CHANGE_PROPOSED;
+} | AgentFailure;
+/**
+ * The skill's current file and its newest recorded turns, at most `limit`.
+ * Turns with a failed call after the skill loaded come first. The text is as
+ * stored, which is redacted when redaction is on, within the drafting budget.
+ */
+export declare function skillEvidence(path: string, limit: number, deps: AgentDeps): Promise<EvidenceResult>;
+export interface ProposalInput {
+    content: string;
+    summary: string;
+    evidenceTurnIds: number[];
+}
+/**
+ * Saves the agent's revised `SKILL.md` as a pending `improve` proposal. The
+ * base hash and the diff come from the file on disk. The same content gives
+ * `no-change` and counts as a review, as a model draft does.
+ */
+export declare function proposeImprovement(path: string, input: ProposalInput, deps: AgentDeps): Promise<ProposeResult>;
+/**
+ * Saves the agent's new `SKILL.md` as a pending `new` proposal at
+ * `<folder>/<name>/SKILL.md`, with the checks `draftNewSkill` makes.
+ */
+export declare function proposeNewSkill(name: string, folder: string, input: ProposalInput, deps: AgentDeps): Promise<ProposeResult>;

package/dist/services/skill-learning/agent-proposals.js

@@ -0,0 +1,180 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hashSkillContent, SKILL_FILE_NAME } from "./apply.js";
+import { countSkillUses, MAX_TOTAL_TURN_CHARS, MAX_TURN_CHARS, recentSkillTurns, skillRef, turnsById, USES_WHERE, useArgs, } from "./draft-turns.js";
+import { NO_CHANGE_PROPOSED, READ_ONLY, SKILL_NAME, sameText, withFinalNewline, } from "./drafting.js";
+import { lineDiff } from "./line-diff.js";
+import { createProposal, setSkillReview } from "./proposal-store.js";
+import { readFrontMatter } from "./skill-index.js";
+/**
+ * The agent path (design §8): the coding agent reads a skill's evidence and
+ * proposes a revised file itself. No model call. The proposal is pending, and
+ * apply still waits for the user's request.
+ */
+export const DEFAULT_EVIDENCE_TURNS = 10;
+export const MAX_EVIDENCE_TURNS = 20;
+export const MAX_PROPOSED_BYTES = 100 * 1024;
+function readSkill(path, index) {
+    const ref = skillRef(index, path);
+    if (!ref)
+        return { ok: false, code: "not-found", message: `${path} is not a watched skill` };
+    try {
+        const raw = readFileSync(path);
+        return { ok: true, ref, raw, current: raw.toString("utf8") };
+    }
+    catch {
+        return { ok: false, code: "not-found", message: `${path} cannot be read` };
+    }
+}
+/** Turn ids and hosts, with whether a call failed after the skill loaded (ranking's rule). */
+async function turnFacts(store, ref, ids) {
+    const db = await store.db();
+    const rows = await db.all(`SELECT t.id, t.host, EXISTS (
+       SELECT 1 FROM tool_calls tc WHERE tc.turn_id = t.id AND tc.outcome = 'error'
+         AND tc.position > (SELECT MIN(COALESCE(su.position, -1)) FROM skill_uses su
+                            WHERE su.turn_id = t.id AND ${USES_WHERE})
+     ) AS failed
+     FROM turns t WHERE t.id IN (SELECT value FROM json_each(?))`, [...useArgs(ref), JSON.stringify(ids)]);
+    return new Map(rows.map((row) => [
+        Number(row.id),
+        { host: String(row.host), failed: Number(row.failed) === 1 },
+    ]));
+}
+/** One turn cut to `allowance` characters: prompt, then tool errors, then replies. */
+function budgetTurn(turn, allowance) {
+    let left = allowance;
+    let cut = false;
+    const take = (text) => {
+        const kept = text.slice(0, Math.max(0, left));
+        if (kept.length < text.length)
+            cut = true;
+        left -= kept.length;
+        return kept;
+    };
+    const prompt = take(turn.prompt);
+    const tools = turn.tools.map((t) => ({ ...t, error: t.error === null ? null : take(t.error) }));
+    const replies = turn.replies.map(take).filter((reply) => reply !== "");
+    return { prompt, tools, replies, cut, used: allowance - left };
+}
+/**
+ * The skill's current file and its newest recorded turns, at most `limit`.
+ * Turns with a failed call after the skill loaded come first. The text is as
+ * stored, which is redacted when redaction is on, within the drafting budget.
+ */
+export async function skillEvidence(path, limit, deps) {
+    const skill = readSkill(path, deps.index);
+    if (!skill.ok)
+        return skill;
+    const db = await deps.store.existingDb();
+    const recent = db ? await recentSkillTurns(db, skill.ref, limit) : [];
+    const facts = recent.length > 0
+        ? await turnFacts(deps.store, skill.ref, recent.map((t) => t.id))
+        : new Map();
+    const failedFirst = [
+        ...recent.filter((t) => facts.get(t.id)?.failed),
+        ...recent.filter((t) => !facts.get(t.id)?.failed),
+    ];
+    const turns = [];
+    let left = MAX_TOTAL_TURN_CHARS;
+    for (const turn of failedFirst) {
+        if (left <= 0)
+            break;
+        const { used, ...kept } = budgetTurn(turn, Math.min(MAX_TURN_CHARS, left));
+        left -= used;
+        const fact = facts.get(turn.id);
+        turns.push({
+            id: turn.id,
+            createdAt: turn.createdAt,
+            host: fact?.host ?? "",
+            ...kept,
+            failedAfterUse: fact?.failed ?? false,
+        });
+    }
+    return { ok: true, ref: skill.ref, content: skill.current, turns };
+}
+function tooLarge(content) {
+    if (Buffer.byteLength(content, "utf8") <= MAX_PROPOSED_BYTES)
+        return null;
+    return { ok: false, code: "too-large", message: "content is over 100 KB" };
+}
+/** The given ids that name a recorded turn. */
+async function existingTurnIds(store, ids) {
+    const db = await store.existingDb();
+    if (!db || ids.length === 0)
+        return [];
+    const found = new Set((await turnsById(db, ids)).map((turn) => turn.id));
+    return ids.filter((id, i) => found.has(id) && ids.indexOf(id) === i);
+}
+/**
+ * Saves the agent's revised `SKILL.md` as a pending `improve` proposal. The
+ * base hash and the diff come from the file on disk. The same content gives
+ * `no-change` and counts as a review, as a model draft does.
+ */
+export async function proposeImprovement(path, input, deps) {
+    if (deps.store.isReadOnly())
+        return READ_ONLY;
+    const large = tooLarge(input.content);
+    if (large)
+        return large;
+    const skill = readSkill(path, deps.index);
+    if (!skill.ok)
+        return skill;
+    const content = withFinalNewline(input.content);
+    if (sameText(content, skill.current)) {
+        const db = await deps.store.existingDb();
+        const uses = db ? await countSkillUses(db, skill.ref) : 0;
+        await setSkillReview(deps.store, path, deps.now, uses);
+        return { ok: true, code: "no-change", message: NO_CHANGE_PROPOSED };
+    }
+    const proposal = await createProposal(deps.store, {
+        kind: "improve",
+        skillName: skill.ref.name,
+        skillPath: path,
+        baseHash: hashSkillContent(skill.raw),
+        content,
+        diff: lineDiff(skill.current, content),
+        summary: input.summary.trim(),
+        evidenceTurnIds: await existingTurnIds(deps.store, input.evidenceTurnIds),
+        draftedBy: "agent",
+    }, deps.now);
+    return { ok: true, code: "proposed", proposal };
+}
+/**
+ * Saves the agent's new `SKILL.md` as a pending `new` proposal at
+ * `<folder>/<name>/SKILL.md`, with the checks `draftNewSkill` makes.
+ */
+export async function proposeNewSkill(name, folder, input, deps) {
+    if (deps.store.isReadOnly())
+        return READ_ONLY;
+    if (!SKILL_NAME.test(name)) {
+        return {
+            ok: false,
+            code: "invalid-name",
+            message: "A new skill name may hold only lower-case letters, digits and single hyphens",
+        };
+    }
+    const large = tooLarge(input.content);
+    if (large)
+        return large;
+    const content = withFinalNewline(input.content);
+    const front = readFrontMatter(content);
+    if (front.name !== name || !front.description?.trim()) {
+        return {
+            ok: false,
+            code: "invalid-content",
+            message: `The front matter needs name: ${name} and a description`,
+        };
+    }
+    const proposal = await createProposal(deps.store, {
+        kind: "new",
+        skillName: name,
+        skillPath: join(folder, name, SKILL_FILE_NAME),
+        baseHash: null,
+        content,
+        diff: lineDiff("", content),
+        summary: input.summary.trim(),
+        evidenceTurnIds: await existingTurnIds(deps.store, input.evidenceTurnIds),
+        draftedBy: "agent",
+    }, deps.now);
+    return { ok: true, code: "proposed", proposal };
+}

package/dist/services/skill-learning/apply.d.ts

@@ -0,0 +1,50 @@
+import { type SkillAppliedBy, type SkillProposal } from "./proposal-store.js";
+import type { SkillStore } from "./store.js";
+/** The only file name OMMS writes in a skill folder. */
+export declare const SKILL_FILE_NAME = "SKILL.md";
+export interface ApplyDeps {
+    /** An initialised store. */
+    store: SkillStore;
+    /** The watched skill folders. */
+    folders: readonly string[];
+    now?: () => number;
+}
+export type ApplyFailureCode = "not-found" | "not-pending" | "not-skill-file" | "outside-folder" | "invalid-name" | "stale" | "exists" | "read-only" | "write-failed";
+export type ApplyResult = {
+    ok: true;
+    code: "applied";
+    proposal: SkillProposal;
+    path: string;
+    writtenHash: string;
+} | {
+    ok: false;
+    code: ApplyFailureCode;
+    message: string;
+};
+export type UndoFailureCode = "not-found" | "not-applied" | "no-version" | "outside-folder" | "changed" | "read-only" | "write-failed";
+export type UndoResult = {
+    ok: true;
+    code: "undone";
+    proposal: SkillProposal;
+    path: string;
+} | {
+    ok: false;
+    code: UndoFailureCode;
+    message: string;
+    /** For `changed`: the content undo would have restored, null for a new skill. */
+    savedContent?: string | null;
+};
+/** sha256 of a skill file's content, as stored in `base_hash` and `written_hash`. */
+export declare function hashSkillContent(content: string | Buffer): string;
+/**
+ * Writes a pending proposal to its `SKILL.md` (design §7). Checks the real
+ * path, the file name, a new skill's name and the base hash first. Saves the
+ * previous content before the write. Expected outcomes return a result code.
+ */
+export declare function applyProposal(id: string, by: SkillAppliedBy, deps: ApplyDeps): Promise<ApplyResult>;
+/**
+ * Restores the content saved before the last apply, or deletes the file the
+ * apply created. Only when the file still matches what OMMS wrote; otherwise
+ * refuses and returns the saved content.
+ */
+export declare function undoProposal(id: string, deps: ApplyDeps): Promise<UndoResult>;

package/dist/services/skill-learning/apply.js

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { deleteSkillVersion, getLatestVersion, getProposal, saveSkillVersion, updateProposalState, } from "./proposal-store.js";
+import { clearSkillIndexCache } from "./skill-index.js";
+/** The only file name OMMS writes in a skill folder. */
+export const SKILL_FILE_NAME = "SKILL.md";
+const NEW_SKILL_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const TEMP_SUFFIX = ".omms-tmp";
+/** sha256 of a skill file's content, as stored in `base_hash` and `written_hash`. */
+export function hashSkillContent(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function readHash(path) {
+    try {
+        return hashSkillContent(readFileSync(path));
+    }
+    catch {
+        return null;
+    }
+}
+function realFolders(folders) {
+    const real = [];
+    for (const folder of folders) {
+        try {
+            real.push(realpathSync(folder));
+        }
+        catch {
+            // A missing folder holds nothing to write to.
+        }
+    }
+    return real;
+}
+/**
+ * The real path of `path` after following links. A part that does not exist
+ * yet (a new skill's folder or file) is joined onto the real path of the
+ * nearest part that does.
+ */
+function realTarget(path) {
+    const missing = [];
+    let current = resolve(path);
+    for (;;) {
+        try {
+            return join(realpathSync(current), ...missing.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolve(path);
+            missing.push(basename(current));
+            current = parent;
+        }
+    }
+}
+function isInside(path, folder) {
+    return path.startsWith(folder.endsWith(sep) ? folder : folder + sep);
+}
+/** The real file to write, only when it is a `SKILL.md` inside a watched folder. */
+function checkTarget(path, folders) {
+    if (!path || basename(path) !== SKILL_FILE_NAME) {
+        return {
+            ok: false,
+            code: "not-skill-file",
+            message: `Only ${SKILL_FILE_NAME} files can be written`,
+        };
+    }
+    const real = realTarget(path);
+    const roots = realFolders(folders);
+    if (basename(real) !== SKILL_FILE_NAME) {
+        return {
+            ok: false,
+            code: "not-skill-file",
+            message: `${path} links to a file that is not ${SKILL_FILE_NAME}`,
+        };
+    }
+    if (!roots.some((root) => isInside(real, root))) {
+        return { ok: false, code: "outside-folder", message: `${path} is not inside a watched folder` };
+    }
+    return { ok: true, real, folders: roots };
+}
+/**
+ * Writes a temp file beside the target, then moves it into place in one step.
+ * With `overwrite` false, a hard link puts it in place and fails when a file
+ * appeared there since the check, so a new skill never replaces one.
+ */
+function replaceFile(path, content, overwrite = true) {
+    const temp = path + TEMP_SUFFIX;
+    try {
+        writeFileSync(temp, content);
+        if (overwrite) {
+            renameSync(temp, path);
+        }
+        else {
+            linkSync(temp, path);
+            rmSync(temp, { force: true });
+        }
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Writes a pending proposal to its `SKILL.md` (design §7). Checks the real
+ * path, the file name, a new skill's name and the base hash first. Saves the
+ * previous content before the write. Expected outcomes return a result code.
+ */
+export async function applyProposal(id, by, deps) {
+    const now = deps.now ?? Date.now;
+    const { store } = deps;
+    if (store.isReadOnly()) {
+        return {
+            ok: false,
+            code: "read-only",
+            message: "skills.db is from a newer OMMS and is read-only",
+        };
+    }
+    const proposal = await getProposal(store, id);
+    if (!proposal)
+        return { ok: false, code: "not-found", message: `No proposal ${id}` };
+    if (proposal.state !== "pending") {
+        return { ok: false, code: "not-pending", message: `Proposal ${id} is ${proposal.state}` };
+    }
+    if (proposal.kind === "new" && !NEW_SKILL_NAME.test(proposal.skillName)) {
+        return {
+            ok: false,
+            code: "invalid-name",
+            message: "A new skill name may hold only lower-case letters, digits and single hyphens",
+        };
+    }
+    const target = checkTarget(proposal.skillPath, deps.folders);
+    if (!target.ok)
+        return target;
+    const { real } = target;
+    let previous = null;
+    if (proposal.kind === "new") {
+        if (existsSync(real)) {
+            return { ok: false, code: "exists", message: `${proposal.skillPath} already exists` };
+        }
+    }
+    else {
+        // A missing file or a changed file both mean the draft no longer fits.
+        const current = readHash(real);
+        if (current === null || current !== proposal.baseHash) {
+            await updateProposalState(store, id, "stale", now());
+            return { ok: false, code: "stale", message: "Stale: the file changed since this draft" };
+        }
+        previous = readFileSync(real, "utf8");
+    }
+    const writtenHash = hashSkillContent(proposal.content);
+    const versionId = await saveSkillVersion(store, { proposalId: id, path: real, previousContent: previous, writtenHash }, now());
+    try {
+        if (proposal.kind === "new")
+            mkdirSync(dirname(real), { recursive: true });
+        replaceFile(real, proposal.content, proposal.kind !== "new");
+    }
+    catch (error) {
+        await deleteSkillVersion(store, versionId);
+        if (error.code === "EEXIST") {
+            return { ok: false, code: "exists", message: `${proposal.skillPath} already exists` };
+        }
+        return { ok: false, code: "write-failed", message: errorText(error) };
+    }
+    clearSkillIndexCache();
+    const appliedAt = now();
+    await updateProposalState(store, id, "applied", appliedAt, by);
+    return {
+        ok: true,
+        code: "applied",
+        proposal: { ...proposal, state: "applied", appliedBy: by, updatedAt: appliedAt },
+        path: real,
+        writtenHash,
+    };
+}
+/** Removes a new skill's folder when undo left it empty. Never a watched folder itself. */
+function removeEmptyFolder(folder, roots) {
+    if (roots.includes(folder))
+        return;
+    try {
+        if (readdirSync(folder).length === 0)
+            rmdirSync(folder);
+    }
+    catch {
+        // The folder is gone or not empty; leave it.
+    }
+}
+/**
+ * Restores the content saved before the last apply, or deletes the file the
+ * apply created. Only when the file still matches what OMMS wrote; otherwise
+ * refuses and returns the saved content.
+ */
+export async function undoProposal(id, deps) {
+    const now = deps.now ?? Date.now;
+    const { store } = deps;
+    if (store.isReadOnly()) {
+        return {
+            ok: false,
+            code: "read-only",
+            message: "skills.db is from a newer OMMS and is read-only",
+        };
+    }
+    const proposal = await getProposal(store, id);
+    if (!proposal)
+        return { ok: false, code: "not-found", message: `No proposal ${id}` };
+    if (proposal.state !== "applied") {
+        return { ok: false, code: "not-applied", message: `Proposal ${id} is ${proposal.state}` };
+    }
+    const version = await getLatestVersion(store, id);
+    if (!version)
+        return { ok: false, code: "no-version", message: `No saved version for ${id}` };
+    const target = checkTarget(version.path, deps.folders);
+    if (!target.ok)
+        return { ok: false, code: "outside-folder", message: target.message };
+    const { real, folders } = target;
+    if (readHash(real) !== version.writtenHash) {
+        return {
+            ok: false,
+            code: "changed",
+            message: "The file changed since OMMS wrote it, so undo would lose that change",
+            savedContent: version.previousContent,
+        };
+    }
+    try {
+        if (version.previousContent === null) {
+            unlinkSync(real);
+            removeEmptyFolder(dirname(real), folders);
+        }
+        else {
+            replaceFile(real, version.previousContent);
+        }
+    }
+    catch (error) {
+        return { ok: false, code: "write-failed", message: errorText(error) };
+    }
+    clearSkillIndexCache();
+    const undoneAt = now();
+    await updateProposalState(store, id, "undone", undoneAt);
+    return {
+        ok: true,
+        code: "undone",
+        proposal: { ...proposal, state: "undone", updatedAt: undoneAt },
+        path: real,
+    };
+}

package/dist/services/skill-learning/auto-review.d.ts

@@ -0,0 +1,40 @@
+import { TableLease } from "../turso/table-lease.js";
+import { type DraftDeps } from "./drafting.js";
+import type { SkillStore } from "./store.js";
+/** A skill in automatic mode is reviewed after this many new uses... */
+export declare const AUTO_REVIEW_MIN_USES = 10;
+/** ...and at least this long after its last review. */
+export declare const AUTO_REVIEW_MIN_GAP_MS: number;
+/** The web app checks for due skills this often. */
+export declare const AUTO_REVIEW_INTERVAL_MS: number;
+export declare const SKILL_REVIEW_LEASE_TABLE = "skill_review_lease";
+/** The review run record in `skills.db`, shared by every process. */
+export declare function skillReviewLease(store: SkillStore, now?: () => number): TableLease;
+export interface AutoReviewDeps extends Omit<DraftDeps, "now"> {
+    /** The watched skill folders, for the apply checks. */
+    folders: readonly string[];
+    lease: TableLease;
+}
+export interface AutoReviewReport {
+    /** Why the run stopped before or between reviews. */
+    skipped?: "not-configured" | "backoff" | "busy" | "superseded";
+    /** One entry for each skill reviewed: `applied`, `no-change`, `stale` or a failure code. */
+    reviews: Array<{
+        skillPath: string;
+        code: string;
+    }>;
+}
+/**
+ * One automatic review pass (design §6). Drafts and applies an improvement
+ * for each due skill in automatic mode. Starts no draft during the skill
+ * draft wait, and runs only while it holds the `skill_review_lease`, so one
+ * review runs at a time across processes.
+ */
+export declare function runAutoReview(deps: AutoReviewDeps, now: number): Promise<AutoReviewReport>;
+/**
+ * Runs `runAutoReview` every 10 minutes. `makeDeps` returns null while skill
+ * learning is off, and the tick then does nothing. A tick never overlaps the
+ * one before it. The timer does not keep the process alive. Returns a stop
+ * function.
+ */
+export declare function startAutoReviewLoop(makeDeps: () => Promise<AutoReviewDeps | null>, intervalMs?: number): () => void;