aiden-runtime 4.0.1 → 4.1.0

package/dist/core/v4/providerFallback.js

@@ -412,6 +412,31 @@ class FallbackAdapter {
         }
         this.activeSlotId = slotId;
     }
+    /**
+     * Phase v4.1-subagent — clone the adapter with FRESH mutable state
+     * but SHARED slot configs. Subagent fanout uses this so each
+     * subagent gets its own rate-limit bookkeeping (slotState,
+     * cooldownUntil, requestCount, activeSlotId all reset) without
+     * paying for slot-config rebuilds. The slot list and the cooldownMs
+     * / clock / observer callbacks are read-only and safely shared
+     * across clones.
+     *
+     * One subagent hitting a 429 marks ITS clone's slot as cooled-down;
+     * the parent and sibling clones still see the slot as available.
+     * That's a deliberate tradeoff: tighter contention on the same
+     * provider key, but isolation prevents one slow subagent from
+     * starving siblings via parent-side cooldown state.
+     */
+    clone() {
+        return new FallbackAdapter({
+            apiMode: this.apiMode,
+            slots: this.slots,
+            cooldownMs: this.cooldownMs,
+            now: this.clock,
+            onRateLimit: this.onRateLimit,
+            onFallback: this.onFallback,
+        });
+    }
     /**
      * Diagnostic snapshot for `/providers`. Per-slot cooldown is reported
      * in seconds remaining (0 when the slot is fresh) so the slash command

package/dist/core/v4/skillLoader.js

@@ -74,15 +74,31 @@ class SkillLoader {
         return { ...this.lastCounts, skippedPaths: [...this.lastCounts.skippedPaths] };
     }
     async load(name) {
-        // Honour the cache when available so we don't re-walk for a
-        // single-skill lookup. Falls through to disk on a miss so newly
-        // dropped skills still resolve in long-running processes (the cache
-        // never sees them otherwise — that's the whole point of `invalidate`).
+        // Phase v4.1-cross-platform: case-insensitive cache lookup so a
+        // skill registered as `WebSearch` resolves the same on Linux
+        // (case-sensitive FS) as on Windows (case-insensitive FS). The
+        // ON-DISK directory name still has to match in case for the
+        // disk-fallback path to work, so we ALSO loadAll first when the
+        // case-insensitive cache hit succeeds — that gives us the actual
+        // file-system path and the loader can serve it from cache.
+        const target = name.toLowerCase();
+        if (!this.cache) {
+            // Trigger a one-time scan so case-insensitive lookup has data.
+            try {
+                await this.loadAll();
+            }
+            catch { /* ignore — fall through to disk */ }
+        }
         if (this.cache) {
-            const hit = this.cache.find((s) => s.frontmatter.name === name);
+            const hit = this.cache.find((s) => (s.frontmatter.name ?? '').toLowerCase() === target);
             if (hit)
                 return hit;
         }
+        // Disk fallback: try the verbatim name, then a lowercase variant
+        // (covers case where the cache failed to populate but the on-disk
+        // dir uses lowercase). On case-sensitive filesystems neither will
+        // hit if the directory case doesn't match the requested name —
+        // that's fine, the cache lookup above is the authoritative path.
         const dirSkill = node_path_1.default.join(this.paths.skillsDir, name, 'SKILL.md');
         const fileSkill = node_path_1.default.join(this.paths.skillsDir, `${name}.md`);
         return (await this.tryParse(dirSkill)) ?? (await this.tryParse(fileSkill));

package/dist/core/v4/skillMining/candidateStore.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/candidateStore.ts — Phase v4.1-skill-mining
+ *
+ * Atomic JSON queue for mined skill candidates and rejection
+ * fingerprints. Two files under `<aidenHome>/skills/learned/`:
+ *
+ *   - `.candidates.json` — pending review queue, append-only via
+ *     this module. `/skills review` reads it; `/skills accept`
+ *     and `/skills reject` mutate it.
+ *
+ *   - `.rejected.json` — fingerprint set the dedup gate consults
+ *     so a user-rejected workflow doesn't get re-proposed on the
+ *     next matching turn. Keyed by fingerprint, not id, so the
+ *     dedup survives across the candidate's lifecycle.
+ *
+ * Concurrency: a per-process write queue serialises every mutation
+ * (mirrors the BundledManifest pattern at
+ * `core/v4/skillBundledManifest.ts:50-53`). Cross-process safety
+ * is non-goal — the agent is a single-user CLI.
+ *
+ * Atomicity: writes go to a sibling `.tmp` file then `rename` over
+ * the live path. Windows rename is atomic on the same volume so a
+ * crash mid-write never leaves a partial JSON file.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CandidateStore = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("../paths");
+const ENVELOPE_VERSION = 1;
+class CandidateStore {
+    constructor() {
+        this.writeQueue = Promise.resolve();
+    }
+    /** `<aidenHome>/skills/learned/`. */
+    dir() {
+        return node_path_1.default.join((0, paths_1.resolveAidenPaths)().skillsDir, 'learned');
+    }
+    candidatesPath() {
+        return node_path_1.default.join(this.dir(), '.candidates.json');
+    }
+    rejectedPath() {
+        return node_path_1.default.join(this.dir(), '.rejected.json');
+    }
+    async ensureDir() {
+        await node_fs_1.promises.mkdir(this.dir(), { recursive: true });
+    }
+    async readJson(p, fallback) {
+        try {
+            const raw = await node_fs_1.promises.readFile(p, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /** Atomic `tmp` + rename. */
+    async writeJsonAtomic(p, data) {
+        await this.ensureDir();
+        const tmp = `${p}.tmp`;
+        await node_fs_1.promises.writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
+        await node_fs_1.promises.rename(tmp, p);
+    }
+    /** Append a candidate to the pending queue. Returns the assigned id. */
+    async append(candidate) {
+        return new Promise((resolve, reject) => {
+            this.writeQueue = this.writeQueue.then(async () => {
+                try {
+                    const env = await this.readJson(this.candidatesPath(), {
+                        version: ENVELOPE_VERSION,
+                        candidates: [],
+                    });
+                    env.version = ENVELOPE_VERSION;
+                    env.candidates.push(candidate);
+                    await this.writeJsonAtomic(this.candidatesPath(), env);
+                    resolve(candidate);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+    }
+    /** Read the full pending queue, newest last. */
+    async list() {
+        const env = await this.readJson(this.candidatesPath(), {
+            version: ENVELOPE_VERSION,
+            candidates: [],
+        });
+        return env.candidates ?? [];
+    }
+    /** Fetch a single candidate by id, or undefined. */
+    async get(id) {
+        const all = await this.list();
+        return all.find((c) => c.id === id);
+    }
+    /** Remove a candidate by id. No-op if missing. */
+    async remove(id) {
+        return new Promise((resolve, reject) => {
+            this.writeQueue = this.writeQueue.then(async () => {
+                try {
+                    const env = await this.readJson(this.candidatesPath(), {
+                        version: ENVELOPE_VERSION,
+                        candidates: [],
+                    });
+                    env.version = ENVELOPE_VERSION;
+                    env.candidates = env.candidates.filter((c) => c.id !== id);
+                    await this.writeJsonAtomic(this.candidatesPath(), env);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+    }
+    /** Append a rejection fingerprint (with optional reason). */
+    async recordRejection(fingerprint, reason) {
+        return new Promise((resolve, reject) => {
+            this.writeQueue = this.writeQueue.then(async () => {
+                try {
+                    const env = await this.readJson(this.rejectedPath(), {
+                        version: ENVELOPE_VERSION,
+                        rejected: [],
+                    });
+                    env.version = ENVELOPE_VERSION;
+                    env.rejected.push({
+                        fingerprint,
+                        reason,
+                        rejectedAt: new Date().toISOString(),
+                    });
+                    await this.writeJsonAtomic(this.rejectedPath(), env);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+    }
+    /** Return the set of rejected fingerprints (for dedup). */
+    async loadRejected() {
+        const env = await this.readJson(this.rejectedPath(), {
+            version: ENVELOPE_VERSION,
+            rejected: [],
+        });
+        return new Set((env.rejected ?? []).map((r) => r.fingerprint));
+    }
+    /** Test/reset hook: drop the in-process write queue. Disk untouched. */
+    _resetForTests() {
+        this.writeQueue = Promise.resolve();
+    }
+}
+exports.CandidateStore = CandidateStore;

package/dist/core/v4/skillMining/extractorPrompt.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/extractorPrompt.ts — Phase v4.1-skill-mining
+ *
+ * Optional LLM refinement pass on top of `proposalBuilder.draft()`.
+ * The skeleton SKILL.md the builder produces is already a valid
+ * v4 skill; the refiner only polishes prose. Two hard rules:
+ *
+ *   1. Structural fields are sacred — name, description, version,
+ *      metadata.aiden.* must round-trip unchanged. We re-parse the
+ *      refined output and discard it if any required field drifts.
+ *
+ *   2. Never write attribution tokens (hermes / nous / "portions
+ *      adapted from" / "original copyright"). The permanent
+ *      attribution sweep validates this; if a refined output
+ *      contains any forbidden token, we fall back to the skeleton.
+ *
+ * If the auxiliary client is unavailable, the call times out, or
+ * the refined output fails validation, the function returns the
+ * skeleton unchanged. Mining works fully offline — refinement is
+ * best-effort polish.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refine = refine;
+const skillSpec_1 = require("../skillSpec");
+const FORBIDDEN_TOKENS_RE = /\b(hermes|nous|portions adapted from|original copyright)\b/i;
+const REFINER_SYSTEM_PROMPT = `
+You polish auto-generated skill markdown for a local-first AI agent.
+
+Your job is to improve the WORDING ONLY of an already-valid SKILL.md
+file. The frontmatter (everything between the leading "---" markers)
+must round-trip BYTE-FOR-BYTE unchanged. The "# <name>" heading must
+stay first in the body. The numbered "## Steps" list must remain
+numbered and in the same order; you may rephrase step descriptions
+but must NOT add or remove steps.
+
+Hard rules:
+- Output the COMPLETE SKILL.md, not a diff.
+- Do not add boilerplate, citations, or attribution to any other
+  agent or codebase. The skill is 100% the user's own.
+- Do not introduce mock/fake values into commands.
+- Keep total length under 6000 characters.
+`.trim();
+/**
+ * Refine `skeleton` via the auxiliary client. Always returns a
+ * valid SKILL.md string — either the refined output (if it passes
+ * round-trip + no-attribution validation) or the original skeleton.
+ */
+async function refine(skeleton, opts = {}) {
+    const client = opts.client;
+    if (!client || client.isUnavailable()) {
+        return skeleton;
+    }
+    // Parse the skeleton up front to lock the canonical frontmatter
+    // shape we'll require the refined output to match.
+    let skeletonParsed;
+    try {
+        skeletonParsed = (0, skillSpec_1.parseSkillContent)(skeleton);
+    }
+    catch {
+        // If the skeleton itself is invalid, refining can only make it
+        // worse; bubble the skeleton out and let the caller decide.
+        return skeleton;
+    }
+    const prompt = `${REFINER_SYSTEM_PROMPT}\n\n` +
+        `INPUT SKILL.md:\n\`\`\`\n${skeleton}\n\`\`\`\n\n` +
+        `Output the refined SKILL.md only — no commentary, no code fences.`;
+    let refined;
+    try {
+        const result = await client.call({
+            purpose: 'skill_describe',
+            prompt,
+            maxTokens: opts.maxTokens ?? 1500,
+            timeoutMs: opts.timeoutMs ?? 20000,
+        });
+        refined = (result.content ?? '').trim();
+    }
+    catch {
+        return skeleton;
+    }
+    if (refined.length === 0)
+        return skeleton;
+    // Strip a wrapping ```...``` if the model returned one.
+    refined = refined.replace(/^```(?:markdown|md)?\s*\n/, '').replace(/\n```\s*$/, '');
+    // Validation 1 — attribution sweep. Refined output must not
+    // contain any forbidden token. The permanent sweep would catch
+    // this at ship time; we catch it earlier so a single noisy
+    // refinement doesn't pollute the candidate queue.
+    if (FORBIDDEN_TOKENS_RE.test(refined))
+        return skeleton;
+    // Validation 2 — round-trip through parseSkillContent and verify
+    // the canonical fields match the skeleton.
+    let refinedParsed;
+    try {
+        refinedParsed = (0, skillSpec_1.parseSkillContent)(refined);
+    }
+    catch {
+        return skeleton;
+    }
+    if (refinedParsed.frontmatter.name !== skeletonParsed.frontmatter.name ||
+        refinedParsed.frontmatter.version !== skeletonParsed.frontmatter.version) {
+        return skeleton;
+    }
+    return refined;
+}

package/dist/core/v4/skillMining/proposalBuilder.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/proposalBuilder.ts — Phase v4.1-skill-mining
+ *
+ * Pure-function skeleton SKILL.md generator from a successful tool-
+ * call trace. Used by skillMiner BEFORE optional LLM refinement —
+ * the skeleton must already be a valid v4 skill (parseSkillContent
+ * round-trips), so that mining works offline when the auxiliary
+ * client is unavailable.
+ *
+ * Invariants:
+ *   - emits required fields `name`, `description`, `version`
+ *   - emits `metadata.aiden` with the mining provenance fields
+ *   - body is numbered tool-call steps in markdown
+ *   - never writes hermes/nous/copyright attribution strings — the
+ *     permanent attribution sweep validates this
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveName = deriveName;
+exports.deriveDescription = deriveDescription;
+exports.draft = draft;
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'to', 'for', 'of', 'on', 'at', 'in', 'by', 'and', 'or', 'but', 'with',
+    'from', 'please', 'can', 'you', 'will', 'do', 'does', 'my', 'our', 'this', 'that', 'these',
+    'is', 'are', 'be', 'was', 'were', 'it', 'its', 'as', 'if', 'then', 'else', 'some', 'any',
+    'me', 'i', 'your', 'their', 'his', 'her', 'him',
+]);
+/**
+ * Derive a kebab-case skill-name from the first user message.
+ * Conservative — keeps only [a-z0-9-], collapses runs, max 40 chars.
+ * Falls back to `learned-skill-<short-fingerprint>` if extraction
+ * yields nothing usable.
+ */
+function deriveName(firstUserPrompt, fingerprint) {
+    const lowered = firstUserPrompt.toLowerCase();
+    // Pull out non-stopword tokens, max 5 of them.
+    const tokens = lowered
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !STOP_WORDS.has(t))
+        .slice(0, 5);
+    let stem = tokens.join('-');
+    // Strict alphanum-and-dash, collapse multiple dashes, trim leading/trailing.
+    stem = stem.replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+    if (stem.length === 0) {
+        return `learned-skill-${fingerprint.slice(0, 8)}`;
+    }
+    return stem.slice(0, 40);
+}
+/**
+ * Build the description line — single sentence summarising what the
+ * trace did. Keep it under 200 chars (the skill loader caps the
+ * displayed description in /skills list).
+ */
+function deriveDescription(trace) {
+    if (trace.length === 0)
+        return 'Learned workflow.';
+    const tools = trace.map((e) => e.name).filter(Boolean);
+    const distinct = Array.from(new Set(tools));
+    if (distinct.length === 1) {
+        return `Learned workflow: ${distinct[0]} (${tools.length}x).`;
+    }
+    const head = distinct.slice(0, 4).join(' → ');
+    const more = distinct.length > 4 ? ` (+${distinct.length - 4} more)` : '';
+    return `Learned workflow: ${head}${more}.`;
+}
+/**
+ * Render the body as numbered tool-call steps. Args are JSON-stringified
+ * and clipped at 120 chars per step so a chatty trace doesn't bloat
+ * SKILL.md to multi-MB.
+ */
+function renderBody(trace) {
+    if (trace.length === 0) {
+        return '## Steps\n\n_(empty trace)_\n';
+    }
+    const out = ['## Steps', ''];
+    trace.forEach((entry, i) => {
+        const idx = i + 1;
+        const argSummary = (() => {
+            if (entry.args == null || typeof entry.args !== 'object')
+                return '';
+            try {
+                const json = JSON.stringify(entry.args);
+                if (json.length <= 120)
+                    return `  \\\`${json}\\\``;
+                return `  \\\`${json.slice(0, 117)}…\\\``;
+            }
+            catch {
+                return '';
+            }
+        })();
+        out.push(`${idx}. **${entry.name}**${argSummary}`);
+    });
+    out.push('');
+    out.push('## Notes', '');
+    out.push('Mined from a successful turn — review the steps above before relying on it.');
+    out.push('');
+    return out.join('\n');
+}
+/**
+ * Build a full SKILL.md (frontmatter + body) ready for parseSkillContent.
+ * The output is deterministic for a given (trace, context) input —
+ * smokes assert this for stable round-trip behaviour.
+ */
+function draft(trace, ctx) {
+    const name = ctx.nameOverride?.trim() || deriveName(ctx.firstUserPrompt, ctx.traceFingerprint);
+    const description = deriveDescription(trace);
+    const version = '0.1.0';
+    const createdAt = new Date().toISOString();
+    // YAML frontmatter — keep field order stable so smokes can pin
+    // shape without depending on YAML library output ordering.
+    const frontmatter = [
+        '---',
+        `name: ${name}`,
+        `description: ${JSON.stringify(description)}`,
+        `version: ${version}`,
+        'category: learned',
+        'metadata:',
+        '  aiden:',
+        '    learned: true',
+        `    sourceSessionId: ${JSON.stringify(ctx.sourceSessionId)}`,
+        `    sourceTurnIdx: ${ctx.sourceTurnIdx}`,
+        `    createdAt: ${JSON.stringify(createdAt)}`,
+        `    traceFingerprint: ${JSON.stringify(ctx.traceFingerprint)}`,
+        `    candidateConfidence: ${ctx.candidateConfidence.toFixed(3)}`,
+        '---',
+        '',
+        `# ${name}`,
+        '',
+        description,
+        '',
+    ].join('\n');
+    return frontmatter + renderBody(trace);
+}

package/dist/core/v4/skillMining/skillMiner.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/skillMiner.ts — Phase v4.1-skill-mining
+ *
+ * Orchestrator for the skill-mining post-turn observation. Sits next
+ * to `moat/skillTeacher.ts:observeTurn` in the agent loop hook
+ * (`core/v4/aidenAgent.ts:440-468`); the two are complementary.
+ * SkillTeacher proposes inline (immediate accept/reject); SkillMiner
+ * stages a candidate for `/skills review` so the user can audit
+ * before any disk-mutation lands in the live skills directory.
+ *
+ * Programmatic gates (in order — first failure short-circuits):
+ *   1. trace length < 3                        → skip
+ *   2. any tool errored                        → skip
+ *   3. finishReason !== 'stop'                 → skip
+ *   4. session candidate count >= SESSION_SKILL_LIMIT → skip
+ *   5. user opt-out phrase in conversation     → skip (reuse OPT_OUT_RE)
+ *   6. fingerprint matches pending candidate   → skip (dedup)
+ *   7. fingerprint matches rejected list       → skip (dedup)
+ *
+ * Pass-through pipeline:
+ *   - compute confidence score from programmatic features
+ *   - draft skeleton via proposalBuilder
+ *   - refine via extractorPrompt (best-effort; falls back to
+ *     skeleton)
+ *   - validate via parseSkillContent round-trip
+ *   - append to candidateStore
+ *   - return ObservationResult so chatSession can notify
+ *
+ * MCP serve mode: caller (aidenAgent) MUST gate on
+ * !isMcpServeMode() before invoking observeTurn — the mining
+ * subsystem itself doesn't write to stdout but a candidate
+ * notification would, and serve mode owns stdout for JSON-RPC.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillMiner = exports.SESSION_SKILL_LIMIT = void 0;
+exports.computeConfidence = computeConfidence;
+const node_crypto_1 = require("node:crypto");
+const skillSpec_1 = require("../skillSpec");
+const candidateStore_1 = require("./candidateStore");
+const traceFingerprint_1 = require("./traceFingerprint");
+const proposalBuilder_1 = require("./proposalBuilder");
+const extractorPrompt_1 = require("./extractorPrompt");
+/** Per-session candidate cap — port from v3's `SESSION_SKILL_LIMIT`. */
+exports.SESSION_SKILL_LIMIT = 2;
+/** Minimum trace length to consider mining at all. */
+const MIN_TRACE_LENGTH = 3;
+/**
+ * Opt-out phrases that suppress mining for the current turn. Match
+ * the SkillTeacher pattern at `moat/skillTeacher.ts:110` so a user
+ * who silences SkillTeacher also silences mining.
+ */
+const OPT_OUT_RE = /\b(stop|don['']?t|no|never)\s+(suggest|propose|create|save|learn|remember)\w*\b/i;
+/**
+ * Compute a 0..1 confidence score from programmatic trace features.
+ * Used to sort `/skills review` so the most promising candidates
+ * surface first.
+ *
+ * Components:
+ *   - lengthScore : trace length sweet spot is 5..15 (peaks at 10)
+ *   - errorRate   : already gated to 0 (no errors in trace) but the
+ *                   feature is computed for forward-compat with
+ *                   future "soft" mining that admits some errors
+ *   - distinctSet : more distinct tools = more reusable workflow
+ *   - distinctTools: simple toolset diversity
+ */
+function computeConfidence(trace) {
+    if (trace.length === 0)
+        return 0;
+    // Length score — peaks at 10, falls off at extremes.
+    const len = trace.length;
+    const lengthScore = len < 3 ? 0 :
+        len <= 10 ? len / 10 :
+            len <= 15 ? 1 - (len - 10) * 0.04 :
+                Math.max(0.4, 1 - (len - 10) * 0.05);
+    // Error rate (0 = best, 1 = worst).
+    const errors = trace.filter((e) => e.error != null).length;
+    const errorRate = errors / trace.length;
+    // Distinct tool diversity.
+    const distinctTools = new Set(trace.map((e) => e.name)).size;
+    const diversityScore = Math.min(1, distinctTools / 4);
+    // Distinct toolsets diversity (some traces tag entries).
+    const distinctSets = new Set(trace.map((e) => e.toolset ?? '').filter(Boolean)).size;
+    const setBonus = Math.min(0.2, distinctSets * 0.1);
+    // Weighted average — length and diversity dominate, error penalty
+    // proportional to rate.
+    const raw = 0.55 * lengthScore + 0.35 * diversityScore + setBonus - errorRate;
+    return Math.max(0, Math.min(1, Number(raw.toFixed(3))));
+}
+/** Single-trace orchestrator. Stateless except for the per-session counter. */
+class SkillMiner {
+    constructor(opts = {}) {
+        this.perSessionCount = new Map();
+        this.store = opts.store ?? new candidateStore_1.CandidateStore();
+        this.auxiliaryClient = opts.auxiliaryClient;
+        this.sessionCap = opts.sessionCap ?? exports.SESSION_SKILL_LIMIT;
+        this.skeletonOnly = opts.skeletonOnly ?? false;
+    }
+    /** Test/reset hook. */
+    _resetForTests() {
+        this.perSessionCount.clear();
+    }
+    /** Returns the count of pending candidates already attributed to a session. */
+    countForSession(sessionId) {
+        return this.perSessionCount.get(sessionId) ?? 0;
+    }
+    async observeTurn(obs) {
+        // Gate 1 — short trace.
+        if (!obs.trace || obs.trace.length < MIN_TRACE_LENGTH) {
+            return { status: 'short-trace' };
+        }
+        // Gate 2 — any tool errored.
+        if (obs.trace.some((e) => e.error != null)) {
+            return { status: 'tool-error' };
+        }
+        // Gate 3 — turn was aborted.
+        if (obs.finishReason !== 'stop') {
+            return { status: 'abort' };
+        }
+        // Gate 4 — session cap.
+        if (this.countForSession(obs.sessionId) >= this.sessionCap) {
+            return { status: 'session-cap' };
+        }
+        // Gate 5 — user opt-out anywhere in this turn's conversation.
+        for (const msg of obs.history) {
+            if (msg.role === 'user' && typeof msg.content === 'string' && OPT_OUT_RE.test(msg.content)) {
+                return { status: 'opt-out' };
+            }
+        }
+        // Fingerprint + dedup.
+        const fpEntries = obs.trace.map((e) => ({ name: e.name, args: e.args }));
+        const fingerprint = (0, traceFingerprint_1.traceFingerprint)(fpEntries);
+        const pending = await this.store.list();
+        if (pending.some((c) => c.fingerprint === fingerprint)) {
+            return { status: 'dedup-pending' };
+        }
+        const rejected = await this.store.loadRejected();
+        if (rejected.has(fingerprint)) {
+            return { status: 'dedup-rejected' };
+        }
+        // Compute confidence + first user prompt for skeleton seeding.
+        const confidence = computeConfidence(obs.trace);
+        const firstUserPrompt = (() => {
+            for (const m of obs.history) {
+                if (m.role === 'user' && typeof m.content === 'string' && m.content.trim().length > 0) {
+                    return m.content.trim();
+                }
+            }
+            return '';
+        })();
+        const ctx = {
+            firstUserPrompt,
+            sourceSessionId: obs.sessionId,
+            sourceTurnIdx: obs.sourceTurnIdx,
+            traceFingerprint: fingerprint,
+            candidateConfidence: confidence,
+        };
+        let skill = (0, proposalBuilder_1.draft)(obs.trace, ctx);
+        if (!this.skeletonOnly) {
+            skill = await (0, extractorPrompt_1.refine)(skill, { client: this.auxiliaryClient });
+        }
+        // Final validation — must round-trip through parseSkillContent
+        // (the canonical loader parser). If it doesn't, drop the
+        // candidate rather than poison the queue.
+        try {
+            (0, skillSpec_1.parseSkillContent)(skill);
+        }
+        catch {
+            return { status: 'invalid-skill', confidence };
+        }
+        const candidate = {
+            id: (0, node_crypto_1.randomUUID)(),
+            fingerprint,
+            sourceSessionId: obs.sessionId,
+            sourceTurnIdx: obs.sourceTurnIdx,
+            createdAt: new Date().toISOString(),
+            candidateConfidence: confidence,
+            skillContent: skill,
+        };
+        await this.store.append(candidate);
+        this.perSessionCount.set(obs.sessionId, this.countForSession(obs.sessionId) + 1);
+        return { status: 'queued', candidate, confidence };
+    }
+}
+exports.SkillMiner = SkillMiner;