wotann 0.5.85 → 0.5.86

package/dist/cli/commands/skills-curator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `wotann skills curator <verb>` — thin CLI shell around skill-curator.
+ *
+ * Verbs:
+ *   status                   — render scheduler state + per-skill lifecycle
+ *   run [--dry-run]          — execute a pass (or preview without mutating)
+ *   pause / resume           — toggle the paused flag
+ *   pin <name> / unpin <name>— bypass auto-transitions for a specific skill
+ *
+ * No side effects at import time. The src/index.ts skillsCmd dispatcher
+ * lazy-imports this module so the CLI cold path stays slim.
+ */
+import { applyAutomaticTransitions, type CuratorState } from "../../learning/skill-curator.js";
+export interface StatusOptions {
+    /** Inject a writer for testability. Defaults to console.log. */
+    readonly write?: (line: string) => void;
+    /** Anchor "now" for the time-ago math. */
+    readonly now?: Date;
+}
+export declare function runStatus(opts?: StatusOptions): number;
+export interface RunOptions {
+    readonly dryRun?: boolean;
+    readonly write?: (line: string) => void;
+    readonly now?: Date;
+}
+export declare function runRun(opts?: RunOptions): number;
+export declare function runPause(opts?: {
+    write?: (line: string) => void;
+}): number;
+export declare function runResume(opts?: {
+    write?: (line: string) => void;
+}): number;
+export declare function runPin(skillName: string, opts?: {
+    write?: (line: string) => void;
+}): number;
+export declare function runUnpin(skillName: string, opts?: {
+    write?: (line: string) => void;
+}): number;
+/**
+ * Daemon-friendly entry point: applies auto-transitions WITHOUT
+ * rendering anything. Returns counts so the caller can log / emit
+ * telemetry on its own terms.
+ *
+ * Used by the (future) kairos idle-detector wire. Manual CLI runs
+ * go through {@link runRun} which writes the summary string.
+ */
+export declare function runSilentPass(now?: Date): {
+    readonly transitions: ReturnType<typeof applyAutomaticTransitions>;
+    readonly stateAfter: CuratorState;
+};

package/dist/cli/commands/skills-curator.js

@@ -0,0 +1,162 @@
+/**
+ * `wotann skills curator <verb>` — thin CLI shell around skill-curator.
+ *
+ * Verbs:
+ *   status                   — render scheduler state + per-skill lifecycle
+ *   run [--dry-run]          — execute a pass (or preview without mutating)
+ *   pause / resume           — toggle the paused flag
+ *   pin <name> / unpin <name>— bypass auto-transitions for a specific skill
+ *
+ * No side effects at import time. The src/index.ts skillsCmd dispatcher
+ * lazy-imports this module so the CLI cold path stays slim.
+ */
+import chalk from "chalk";
+import { applyAutomaticTransitions, isPaused, listAgentSkills, loadState, runCurator, saveState, setPaused, setPinned, } from "../../learning/skill-curator.js";
+// ── Time-ago formatter (Hermes-style) ─────────────────────────────
+function formatTimeAgo(iso, now = new Date()) {
+    if (iso === null)
+        return "never";
+    const ms = now.getTime() - new Date(iso).getTime();
+    if (!Number.isFinite(ms))
+        return "unknown";
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ago`;
+    if (seconds < 86_400)
+        return `${Math.floor(seconds / 3600)}h ago`;
+    return `${Math.floor(seconds / 86_400)}d ago`;
+}
+export function runStatus(opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    const now = opts.now ?? new Date();
+    const state = loadState();
+    const skills = listAgentSkills();
+    write(chalk.bold(formatHeader(state)));
+    write(`  runs:           ${state.runCount}`);
+    write(`  last run:       ${formatTimeAgo(state.lastRunAt, now)}`);
+    write(`  last summary:   ${state.lastRunSummary ?? "(none)"}`);
+    if (state.lastRunDurationSeconds !== null) {
+        write(`  last duration:  ${state.lastRunDurationSeconds}s`);
+    }
+    const buckets = {
+        active: [],
+        stale: [],
+        archived: [],
+    };
+    const pinned = [];
+    for (const skill of skills) {
+        buckets[skill.state].push(skill);
+        if (skill.pinned)
+            pinned.push(skill.name);
+    }
+    write("");
+    if (skills.length === 0) {
+        write(chalk.dim("  no agent-created skills"));
+        return 0;
+    }
+    write(`  agent-created skills: ${skills.length}`);
+    for (const state_ of ["active", "stale", "archived"]) {
+        write(`    ${state_.padEnd(10)} ${buckets[state_].length}`);
+    }
+    if (pinned.length > 0) {
+        write("");
+        write(`  pinned (${pinned.length}): ${pinned.join(", ")}`);
+    }
+    const leastActive = [...buckets.active]
+        .sort((a, b) => {
+        const aT = a.lastActivityAt ?? a.createdAt;
+        const bT = b.lastActivityAt ?? b.createdAt;
+        return aT.localeCompare(bT);
+    })
+        .slice(0, 5);
+    if (leastActive.length > 0) {
+        write("");
+        write("  least recently active (top 5):");
+        for (const skill of leastActive) {
+            write(`    ${skill.name.padEnd(40)}  ` +
+                `use=${String(skill.useCount).padStart(3)}  ` +
+                `view=${String(skill.viewCount).padStart(3)}  ` +
+                `last=${formatTimeAgo(skill.lastActivityAt, now)}`);
+        }
+    }
+    return 0;
+}
+function formatHeader(state) {
+    if (state.paused)
+        return "curator: PAUSED";
+    return "curator: ENABLED";
+}
+export function runRun(opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    if (isPaused() && opts.dryRun !== true) {
+        write(chalk.yellow("curator is paused. Resume with `wotann skills curator resume`."));
+        return 1;
+    }
+    const result = runCurator(opts.now ?? new Date(), { dryRun: opts.dryRun === true });
+    write(chalk.bold(result.dryRun ? "DRY RUN — no mutations" : "Curator pass"));
+    write(`  ${result.summary}`);
+    write(`  duration: ${result.durationSeconds.toFixed(2)}s`);
+    return 0;
+}
+// ── pause / resume ────────────────────────────────────────────────
+export function runPause(opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    setPaused(true);
+    write(chalk.yellow("curator paused"));
+    return 0;
+}
+export function runResume(opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    setPaused(false);
+    write(chalk.green("curator resumed"));
+    return 0;
+}
+// ── pin / unpin ───────────────────────────────────────────────────
+export function runPin(skillName, opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    if (skillName.length === 0) {
+        write(chalk.red("usage: wotann skills curator pin <name>"));
+        return 2;
+    }
+    if (setPinned(skillName, true)) {
+        write(chalk.green(`pinned: ${skillName}`));
+        return 0;
+    }
+    write(chalk.red(`no agent-created skill on disk: ${skillName}`));
+    return 1;
+}
+export function runUnpin(skillName, opts = {}) {
+    const write = opts.write ?? ((line) => console.log(line));
+    if (skillName.length === 0) {
+        write(chalk.red("usage: wotann skills curator unpin <name>"));
+        return 2;
+    }
+    if (setPinned(skillName, false)) {
+        write(chalk.green(`unpinned: ${skillName}`));
+        return 0;
+    }
+    write(chalk.red(`no agent-created skill on disk: ${skillName}`));
+    return 1;
+}
+// ── transition-only (kairos / daemon entry point) ─────────────────
+/**
+ * Daemon-friendly entry point: applies auto-transitions WITHOUT
+ * rendering anything. Returns counts so the caller can log / emit
+ * telemetry on its own terms.
+ *
+ * Used by the (future) kairos idle-detector wire. Manual CLI runs
+ * go through {@link runRun} which writes the summary string.
+ */
+export function runSilentPass(now = new Date()) {
+    const transitions = applyAutomaticTransitions(now);
+    const prev = loadState();
+    saveState({
+        ...prev,
+        lastRunAt: now.toISOString(),
+        lastRunSummary: `silent: checked ${transitions.checked}, archived ${transitions.archived}`,
+        runCount: prev.runCount + 1,
+    });
+    return { transitions, stateAfter: loadState() };
+}

package/dist/index.js

@@ -3578,6 +3578,58 @@ skillsCmd
     if (out.exitCode !== 0)
         process.exit(out.exitCode);
 });
+// ── wotann skills curator ────────────────────────────────────
+//
+// Hermes Gap 1 port — inactivity-triggered lifecycle manager for
+// agent-created skills. State machine lives in src/learning/
+// skill-curator.ts; this is the thin CLI wrapper. See the module
+// docblock there for the full lifecycle / invariants discussion.
+const curatorCmd = skillsCmd
+    .command("curator")
+    .description("Manage the inactivity-triggered skill lifecycle (active/stale/archived)");
+curatorCmd
+    .command("status")
+    .description("Show curator scheduler state + per-skill lifecycle counts")
+    .action(async () => {
+    const mod = await import("./cli/commands/skills-curator.js");
+    process.exit(mod.runStatus());
+});
+curatorCmd
+    .command("run")
+    .description("Execute one curator pass (apply auto-transitions)")
+    .option("--dry-run", "Compute would-be transitions without mutating the library")
+    .action(async (opts) => {
+    const mod = await import("./cli/commands/skills-curator.js");
+    process.exit(mod.runRun({ dryRun: opts.dryRun === true }));
+});
+curatorCmd
+    .command("pause")
+    .description("Pause the curator (scheduler will not run automatic passes)")
+    .action(async () => {
+    const mod = await import("./cli/commands/skills-curator.js");
+    process.exit(mod.runPause());
+});
+curatorCmd
+    .command("resume")
+    .description("Resume the curator after a pause")
+    .action(async () => {
+    const mod = await import("./cli/commands/skills-curator.js");
+    process.exit(mod.runResume());
+});
+curatorCmd
+    .command("pin <name>")
+    .description("Pin a skill so it bypasses auto-transitions (stale + archive)")
+    .action(async (name) => {
+    const mod = await import("./cli/commands/skills-curator.js");
+    process.exit(mod.runPin(name));
+});
+curatorCmd
+    .command("unpin <name>")
+    .description("Unpin a skill so it resumes auto-transitions")
+    .action(async (name) => {
+    const mod = await import("./cli/commands/skills-curator.js");
+    process.exit(mod.runUnpin(name));
+});
 // ── wotann cost ──────────────────────────────────────────────
 //
 // Wave 4G: the cost command now accepts an optional `period` argument

package/dist/learning/skill-curator.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Skill Curator — inactivity-triggered skill lifecycle manager.
+ *
+ * Port of Hermes' `agent/curator.py` (NousResearch/hermes-agent, MIT).
+ * The Hermes curator runs background reviews of agent-created skills,
+ * auto-transitioning them between lifecycle states (active → stale →
+ * archived) based on real activity timestamps, and pinning bypasses
+ * the auto-transitions entirely. Hermes' full curator also spawns a
+ * forked AIAgent to do LLM-graded review; we ship the pure-function
+ * scheduler + state machine first and wire the LLM review later when
+ * the auxiliary-credential pattern lands.
+ *
+ * Lifecycle:
+ *   active  → stale       (no activity for STALE_AFTER_DAYS, default 30)
+ *   stale   → archived    (no activity for ARCHIVE_AFTER_DAYS, default 90)
+ *   stale   → active      (activity recorded after marked stale = reactivation)
+ *   pinned  → bypasses all auto-transitions
+ *
+ * Strict invariants:
+ *   - Only touches AGENT-CREATED skills (those living under
+ *     ~/.wotann/skills/agent/ — the directory `skill-forge.ts`
+ *     promotes into). The curated/scientific registries are static
+ *     data and out of scope.
+ *   - Never auto-deletes. Archive moves the directory to
+ *     ~/.wotann/skills/.archive/<name>/ which is recoverable by hand.
+ *   - State writes are atomic (writeFileAtomic) so a crashed run
+ *     never leaves a half-written .curator_state.
+ *
+ * Persistence layout (under WOTANN_HOME):
+ *   skills/.curator_state               — global curator scheduler state
+ *   skills/agent/<name>/                — promoted agent-created skill
+ *   skills/agent/<name>/.activity.json  — per-skill activity record
+ *   skills/.archive/<name>/             — archived (recoverable) skills
+ *
+ * Quality bars:
+ *   QB#6 honest failures: corrupt state files return defaults rather
+ *        than crashing the curator; ENOENT on a missing skill dir is
+ *        the expected steady-state, not an error.
+ *   QB#7 per-call state: every function reads from disk on each call
+ *        and writes back atomically. No module-global caches.
+ *   QB#11 sibling-site scan: `applyAutomaticTransitions` is the ONE
+ *        place state mutations live — CLI status/run/pin paths all
+ *        funnel through it so the bug class "two writers race on the
+ *        same skill" cannot regress.
+ */
+/** 7 days — Hermes default. Override via {@link CuratorConfig.intervalHours}. */
+export declare const DEFAULT_INTERVAL_HOURS: number;
+/** 2 hours of agent inactivity before the curator considers running. */
+export declare const DEFAULT_MIN_IDLE_HOURS = 2;
+/** Skill marked `stale` after this many days without activity. */
+export declare const DEFAULT_STALE_AFTER_DAYS = 30;
+/** Skill `archived` after this many days without activity. */
+export declare const DEFAULT_ARCHIVE_AFTER_DAYS = 90;
+export type SkillState = "active" | "stale" | "archived";
+/** Global curator scheduler state — persisted at `.curator_state`. */
+export interface CuratorState {
+    readonly lastRunAt: string | null;
+    readonly lastRunDurationSeconds: number | null;
+    readonly lastRunSummary: string | null;
+    readonly paused: boolean;
+    readonly runCount: number;
+}
+/** Per-skill activity record — persisted at `agent/<name>/.activity.json`. */
+export interface SkillActivity {
+    readonly name: string;
+    readonly state: SkillState;
+    readonly pinned: boolean;
+    readonly lastActivityAt: string | null;
+    readonly createdAt: string;
+    readonly useCount: number;
+    readonly viewCount: number;
+}
+/** Aggregate counts emitted by {@link applyAutomaticTransitions}. */
+export interface TransitionCounts {
+    readonly checked: number;
+    readonly markedStale: number;
+    readonly archived: number;
+    readonly reactivated: number;
+}
+export interface CuratorConfig {
+    readonly intervalHours?: number;
+    readonly staleAfterDays?: number;
+    readonly archiveAfterDays?: number;
+}
+export interface RunResult {
+    readonly counts: TransitionCounts;
+    readonly durationSeconds: number;
+    readonly summary: string;
+    readonly dryRun: boolean;
+}
+/**
+ * Load the global curator scheduler state. Returns sensible defaults
+ * on missing or corrupt files — never throws.
+ */
+export declare function loadState(): CuratorState;
+/** Write the global curator state atomically. Creates the parent dir if needed. */
+export declare function saveState(state: CuratorState): void;
+export declare function setPaused(paused: boolean): void;
+export declare function isPaused(): boolean;
+/**
+ * Record a use (the user actually invoked the skill in an agent turn).
+ * Bumps {@link SkillActivity.useCount}, updates `lastActivityAt`, and
+ * reactivates archived skills (the skill clearly isn't dead).
+ */
+export declare function recordSkillUse(skillName: string, now?: Date): void;
+/**
+ * Record a view (the user inspected the skill via `/skills view` or
+ * the palette). Views ALSO count as activity per the Hermes design —
+ * a recently-inspected skill shouldn't immediately archive.
+ */
+export declare function recordSkillView(skillName: string, now?: Date): void;
+/**
+ * Pin or unpin a skill. Pinned skills bypass all auto-transitions.
+ * Returns false when the skill has no on-disk presence (we don't
+ * silently create a phantom activity record).
+ */
+export declare function setPinned(skillName: string, pinned: boolean, now?: Date): boolean;
+/**
+ * Walk `~/.wotann/skills/agent/` and return one activity record per
+ * agent-created skill. Skills with no activity file yet are seeded
+ * with defaults derived from their directory mtime so the first
+ * curator pass has somewhere to anchor lifecycle math.
+ */
+export declare function listAgentSkills(): SkillActivity[];
+/**
+ * Walk every agent-created skill and move active/stale/archived based
+ * on the latest activity timestamp. Pinned skills are never touched.
+ * Archived skills move on disk to `.archive/<name>/`. Returns aggregate
+ * counts so the CLI can render a summary.
+ */
+export declare function applyAutomaticTransitions(now?: Date, config?: CuratorConfig): TransitionCounts;
+/**
+ * Returns true when the curator should run NOW. Gates:
+ *   - not paused
+ *   - last_run_at present AND older than intervalHours
+ *
+ * First-run behavior: a missing `last_run_at` SEEDS the timestamp and
+ * returns false (defer the first real pass by one full interval —
+ * matches Hermes' "deferred first run" pattern so the very first
+ * background tick after `wotann update` doesn't immediately mutate
+ * the library).
+ *
+ * The min-idle-hours gate is intentionally NOT applied here — callers
+ * (kairos idle detector, CLI manual `run`) know their own idle state
+ * and apply it at the call site.
+ */
+export declare function shouldRunNow(now?: Date, intervalHours?: number): boolean;
+/**
+ * Execute one curator pass. When `dryRun` is true, computes what would
+ * change but does NOT mutate the skill library or the curator state.
+ * Otherwise applies transitions and persists `lastRunAt`/`runCount`/
+ * `lastRunSummary` for the next status render.
+ */
+export declare function runCurator(now?: Date, config?: CuratorConfig & {
+    dryRun?: boolean;
+}): RunResult;

package/dist/learning/skill-curator.js

@@ -0,0 +1,402 @@
+/**
+ * Skill Curator — inactivity-triggered skill lifecycle manager.
+ *
+ * Port of Hermes' `agent/curator.py` (NousResearch/hermes-agent, MIT).
+ * The Hermes curator runs background reviews of agent-created skills,
+ * auto-transitioning them between lifecycle states (active → stale →
+ * archived) based on real activity timestamps, and pinning bypasses
+ * the auto-transitions entirely. Hermes' full curator also spawns a
+ * forked AIAgent to do LLM-graded review; we ship the pure-function
+ * scheduler + state machine first and wire the LLM review later when
+ * the auxiliary-credential pattern lands.
+ *
+ * Lifecycle:
+ *   active  → stale       (no activity for STALE_AFTER_DAYS, default 30)
+ *   stale   → archived    (no activity for ARCHIVE_AFTER_DAYS, default 90)
+ *   stale   → active      (activity recorded after marked stale = reactivation)
+ *   pinned  → bypasses all auto-transitions
+ *
+ * Strict invariants:
+ *   - Only touches AGENT-CREATED skills (those living under
+ *     ~/.wotann/skills/agent/ — the directory `skill-forge.ts`
+ *     promotes into). The curated/scientific registries are static
+ *     data and out of scope.
+ *   - Never auto-deletes. Archive moves the directory to
+ *     ~/.wotann/skills/.archive/<name>/ which is recoverable by hand.
+ *   - State writes are atomic (writeFileAtomic) so a crashed run
+ *     never leaves a half-written .curator_state.
+ *
+ * Persistence layout (under WOTANN_HOME):
+ *   skills/.curator_state               — global curator scheduler state
+ *   skills/agent/<name>/                — promoted agent-created skill
+ *   skills/agent/<name>/.activity.json  — per-skill activity record
+ *   skills/.archive/<name>/             — archived (recoverable) skills
+ *
+ * Quality bars:
+ *   QB#6 honest failures: corrupt state files return defaults rather
+ *        than crashing the curator; ENOENT on a missing skill dir is
+ *        the expected steady-state, not an error.
+ *   QB#7 per-call state: every function reads from disk on each call
+ *        and writes back atomically. No module-global caches.
+ *   QB#11 sibling-site scan: `applyAutomaticTransitions` is the ONE
+ *        place state mutations live — CLI status/run/pin paths all
+ *        funnel through it so the bug class "two writers race on the
+ *        same skill" cannot regress.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../utils/atomic-io.js";
+import { resolveWotannHomeSubdir } from "../utils/wotann-home.js";
+// ── Constants (Hermes defaults) ──────────────────────────────────
+/** 7 days — Hermes default. Override via {@link CuratorConfig.intervalHours}. */
+export const DEFAULT_INTERVAL_HOURS = 24 * 7;
+/** 2 hours of agent inactivity before the curator considers running. */
+export const DEFAULT_MIN_IDLE_HOURS = 2;
+/** Skill marked `stale` after this many days without activity. */
+export const DEFAULT_STALE_AFTER_DAYS = 30;
+/** Skill `archived` after this many days without activity. */
+export const DEFAULT_ARCHIVE_AFTER_DAYS = 90;
+// ── Path helpers ──────────────────────────────────────────────────
+function stateFilePath() {
+    return resolveWotannHomeSubdir("skills", ".curator_state");
+}
+function agentSkillsDir() {
+    return resolveWotannHomeSubdir("skills", "agent");
+}
+function archiveDir() {
+    return resolveWotannHomeSubdir("skills", ".archive");
+}
+function activityFilePath(skillName) {
+    return resolveWotannHomeSubdir("skills", "agent", skillName, ".activity.json");
+}
+// ── Global state I/O ──────────────────────────────────────────────
+function defaultState() {
+    return {
+        lastRunAt: null,
+        lastRunDurationSeconds: null,
+        lastRunSummary: null,
+        paused: false,
+        runCount: 0,
+    };
+}
+/**
+ * Load the global curator scheduler state. Returns sensible defaults
+ * on missing or corrupt files — never throws.
+ */
+export function loadState() {
+    const path = stateFilePath();
+    if (!existsSync(path))
+        return defaultState();
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed !== null && typeof parsed === "object") {
+            return { ...defaultState(), ...parsed };
+        }
+    }
+    catch {
+        // Corrupt JSON — return defaults rather than crash the run.
+    }
+    return defaultState();
+}
+/** Write the global curator state atomically. Creates the parent dir if needed. */
+export function saveState(state) {
+    writeFileAtomic(stateFilePath(), JSON.stringify(state, null, 2) + "\n");
+}
+export function setPaused(paused) {
+    saveState({ ...loadState(), paused });
+}
+export function isPaused() {
+    return loadState().paused;
+}
+// ── Per-skill activity ────────────────────────────────────────────
+function loadActivity(skillName) {
+    const path = activityFilePath(skillName);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed !== null && typeof parsed === "object" && typeof parsed.name === "string") {
+            return {
+                name: parsed.name,
+                state: parsed.state ?? "active",
+                pinned: parsed.pinned === true,
+                lastActivityAt: typeof parsed.lastActivityAt === "string" ? parsed.lastActivityAt : null,
+                createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : new Date().toISOString(),
+                useCount: typeof parsed.useCount === "number" ? parsed.useCount : 0,
+                viewCount: typeof parsed.viewCount === "number" ? parsed.viewCount : 0,
+            };
+        }
+    }
+    catch {
+        // Corrupt activity file — treat as missing.
+    }
+    return null;
+}
+function saveActivity(activity) {
+    writeFileAtomic(activityFilePath(activity.name), JSON.stringify(activity, null, 2) + "\n");
+}
+/**
+ * Record a use (the user actually invoked the skill in an agent turn).
+ * Bumps {@link SkillActivity.useCount}, updates `lastActivityAt`, and
+ * reactivates archived skills (the skill clearly isn't dead).
+ */
+export function recordSkillUse(skillName, now = new Date()) {
+    const existing = loadActivity(skillName);
+    saveActivity({
+        name: skillName,
+        state: existing?.state === "archived" ? "active" : (existing?.state ?? "active"),
+        pinned: existing?.pinned ?? false,
+        lastActivityAt: now.toISOString(),
+        createdAt: existing?.createdAt ?? now.toISOString(),
+        useCount: (existing?.useCount ?? 0) + 1,
+        viewCount: existing?.viewCount ?? 0,
+    });
+}
+/**
+ * Record a view (the user inspected the skill via `/skills view` or
+ * the palette). Views ALSO count as activity per the Hermes design —
+ * a recently-inspected skill shouldn't immediately archive.
+ */
+export function recordSkillView(skillName, now = new Date()) {
+    const existing = loadActivity(skillName);
+    saveActivity({
+        name: skillName,
+        state: existing?.state ?? "active",
+        pinned: existing?.pinned ?? false,
+        lastActivityAt: now.toISOString(),
+        createdAt: existing?.createdAt ?? now.toISOString(),
+        useCount: existing?.useCount ?? 0,
+        viewCount: (existing?.viewCount ?? 0) + 1,
+    });
+}
+/**
+ * Pin or unpin a skill. Pinned skills bypass all auto-transitions.
+ * Returns false when the skill has no on-disk presence (we don't
+ * silently create a phantom activity record).
+ */
+export function setPinned(skillName, pinned, now = new Date()) {
+    const existing = loadActivity(skillName);
+    if (existing !== null) {
+        saveActivity({ ...existing, pinned });
+        return true;
+    }
+    const skillDir = join(agentSkillsDir(), skillName);
+    if (!existsSync(skillDir))
+        return false;
+    saveActivity({
+        name: skillName,
+        state: "active",
+        pinned,
+        lastActivityAt: null,
+        createdAt: now.toISOString(),
+        useCount: 0,
+        viewCount: 0,
+    });
+    return true;
+}
+// ── Discovery ─────────────────────────────────────────────────────
+/**
+ * Walk `~/.wotann/skills/agent/` and return one activity record per
+ * agent-created skill. Skills with no activity file yet are seeded
+ * with defaults derived from their directory mtime so the first
+ * curator pass has somewhere to anchor lifecycle math.
+ */
+export function listAgentSkills() {
+    const dir = agentSkillsDir();
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        // Skip dotfile dirs (.archive, .scratch, etc.).
+        if (entry.name.startsWith("."))
+            continue;
+        const activity = loadActivity(entry.name);
+        if (activity !== null) {
+            out.push(activity);
+            continue;
+        }
+        // Skill exists on disk but no activity record yet — seed one.
+        let createdAt;
+        try {
+            createdAt = statSync(join(dir, entry.name)).birthtime.toISOString();
+        }
+        catch {
+            createdAt = new Date().toISOString();
+        }
+        const seeded = {
+            name: entry.name,
+            state: "active",
+            pinned: false,
+            lastActivityAt: null,
+            createdAt,
+            useCount: 0,
+            viewCount: 0,
+        };
+        try {
+            saveActivity(seeded);
+        }
+        catch {
+            // Best-effort seed — if write fails (read-only fs in CI), still
+            // surface the skill in the report.
+        }
+        out.push(seeded);
+    }
+    return out;
+}
+// ── Auto-transitions (pure function over time) ────────────────────
+/**
+ * Walk every agent-created skill and move active/stale/archived based
+ * on the latest activity timestamp. Pinned skills are never touched.
+ * Archived skills move on disk to `.archive/<name>/`. Returns aggregate
+ * counts so the CLI can render a summary.
+ */
+export function applyAutomaticTransitions(now = new Date(), config = {}) {
+    const staleAfter = config.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+    const archiveAfter = config.archiveAfterDays ?? DEFAULT_ARCHIVE_AFTER_DAYS;
+    const nowMs = now.getTime();
+    const staleCutoff = nowMs - staleAfter * 86_400_000;
+    const archiveCutoff = nowMs - archiveAfter * 86_400_000;
+    let checked = 0;
+    let markedStale = 0;
+    let archived = 0;
+    let reactivated = 0;
+    for (const skill of listAgentSkills()) {
+        checked++;
+        if (skill.pinned)
+            continue;
+        const anchorIso = skill.lastActivityAt ?? skill.createdAt;
+        const anchor = new Date(anchorIso).getTime();
+        if (!Number.isFinite(anchor))
+            continue;
+        if (anchor <= archiveCutoff && skill.state !== "archived") {
+            if (archiveSkillOnDisk(skill.name)) {
+                archived++;
+            }
+        }
+        else if (anchor <= staleCutoff && skill.state === "active") {
+            saveActivity({ ...skill, state: "stale" });
+            markedStale++;
+        }
+        else if (anchor > staleCutoff && skill.state === "stale") {
+            saveActivity({ ...skill, state: "active" });
+            reactivated++;
+        }
+    }
+    return { checked, markedStale, archived, reactivated };
+}
+/**
+ * Move `skills/agent/<name>/` to `skills/.archive/<name>/`. If the
+ * archive slot is already occupied (re-archive after manual restore),
+ * suffix with the current timestamp so nothing is overwritten.
+ * Returns false when the source doesn't exist (skill already gone).
+ */
+function archiveSkillOnDisk(skillName) {
+    const src = join(agentSkillsDir(), skillName);
+    if (!existsSync(src))
+        return false;
+    mkdirSync(archiveDir(), { recursive: true });
+    let dst = join(archiveDir(), skillName);
+    if (existsSync(dst)) {
+        dst = `${dst}.${Date.now()}`;
+    }
+    renameSync(src, dst);
+    return true;
+}
+// ── Scheduler ─────────────────────────────────────────────────────
+/**
+ * Returns true when the curator should run NOW. Gates:
+ *   - not paused
+ *   - last_run_at present AND older than intervalHours
+ *
+ * First-run behavior: a missing `last_run_at` SEEDS the timestamp and
+ * returns false (defer the first real pass by one full interval —
+ * matches Hermes' "deferred first run" pattern so the very first
+ * background tick after `wotann update` doesn't immediately mutate
+ * the library).
+ *
+ * The min-idle-hours gate is intentionally NOT applied here — callers
+ * (kairos idle detector, CLI manual `run`) know their own idle state
+ * and apply it at the call site.
+ */
+export function shouldRunNow(now = new Date(), intervalHours = DEFAULT_INTERVAL_HOURS) {
+    const state = loadState();
+    if (state.paused)
+        return false;
+    if (state.lastRunAt === null) {
+        // Seed without running. Defer first pass by one interval.
+        saveState({ ...state, lastRunAt: now.toISOString() });
+        return false;
+    }
+    const last = new Date(state.lastRunAt).getTime();
+    if (!Number.isFinite(last))
+        return true; // corrupt timestamp → run
+    const intervalMs = intervalHours * 3_600_000;
+    return now.getTime() - last >= intervalMs;
+}
+// ── Run ───────────────────────────────────────────────────────────
+/**
+ * Execute one curator pass. When `dryRun` is true, computes what would
+ * change but does NOT mutate the skill library or the curator state.
+ * Otherwise applies transitions and persists `lastRunAt`/`runCount`/
+ * `lastRunSummary` for the next status render.
+ */
+export function runCurator(now = new Date(), config = {}) {
+    const start = Date.now();
+    const dryRun = config.dryRun === true;
+    const counts = dryRun
+        ? computeWouldTransition(now, config)
+        : applyAutomaticTransitions(now, config);
+    const end = Date.now();
+    const summary = formatSummary(counts, dryRun);
+    if (!dryRun) {
+        const prev = loadState();
+        saveState({
+            ...prev,
+            lastRunAt: now.toISOString(),
+            lastRunDurationSeconds: Math.max(0, Math.round((end - start) / 1000)),
+            lastRunSummary: summary,
+            runCount: prev.runCount + 1,
+        });
+    }
+    return {
+        counts,
+        durationSeconds: (end - start) / 1000,
+        summary,
+        dryRun,
+    };
+}
+function computeWouldTransition(now, config) {
+    const staleAfter = config.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+    const archiveAfter = config.archiveAfterDays ?? DEFAULT_ARCHIVE_AFTER_DAYS;
+    const nowMs = now.getTime();
+    const staleCutoff = nowMs - staleAfter * 86_400_000;
+    const archiveCutoff = nowMs - archiveAfter * 86_400_000;
+    let checked = 0;
+    let markedStale = 0;
+    let archived = 0;
+    let reactivated = 0;
+    for (const skill of listAgentSkills()) {
+        checked++;
+        if (skill.pinned)
+            continue;
+        const anchor = new Date(skill.lastActivityAt ?? skill.createdAt).getTime();
+        if (!Number.isFinite(anchor))
+            continue;
+        if (anchor <= archiveCutoff && skill.state !== "archived")
+            archived++;
+        else if (anchor <= staleCutoff && skill.state === "active")
+            markedStale++;
+        else if (anchor > staleCutoff && skill.state === "stale")
+            reactivated++;
+    }
+    return { checked, markedStale, archived, reactivated };
+}
+function formatSummary(counts, dryRun) {
+    const prefix = dryRun ? "[dry-run] " : "";
+    return (`${prefix}checked ${counts.checked}, ` +
+        `marked stale ${counts.markedStale}, ` +
+        `archived ${counts.archived}, ` +
+        `reactivated ${counts.reactivated}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wotann",
-  "version": "0.5.85",
+  "version": "0.5.86",
   "description": "WOTANN — The All-Father of AI Agent Harnesses",
   "type": "module",
   "main": "dist/index.js",