@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/learning/observation-store.js

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { stateFile } from "../agent-paths.js";
+import { isWorkerSession } from "../session-role.js";
+import { withFileLockSync, writeFileAtomicSync } from "../util/atomic-file.js";
 /**
- * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a
+ * Durable, BOUNDED evidence-strength store for the learning gate. The gate auto-applies a
  * durable change only once it has been *observed* enough times; a single reflection pass sees a
  * lesson once, so without persistence every proposal would look brand-new and never accumulate the
  * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by
@@ -26,11 +28,13 @@ export function observationKey(layer, summary) {
 }
 export class ObservationStore {
     filePath;
-    constructor(filePath) {
+    readOnly;
+    constructor(filePath, options) {
         this.filePath = filePath;
+        this.readOnly = options?.readOnly ?? isWorkerSession();
     }
-    static forAgentDir(agentDir) {
-        return new ObservationStore(join(agentDir, "state", "learning-observations.json"));
+    static forAgentDir(agentDir, options) {
+        return new ObservationStore(stateFile(agentDir, "learning-observations.json"), options);
     }
     load() {
         try {
@@ -66,8 +70,7 @@ export class ObservationStore {
         return { version: 1, observations: {} };
     }
     save(file) {
-        mkdirSync(dirname(this.filePath), { recursive: true });
-        writeFileSync(this.filePath, `${JSON.stringify(file, null, "\t")}\n`, "utf-8");
+        writeFileAtomicSync(this.filePath, `${JSON.stringify(file, null, "\t")}\n`);
     }
     /** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */
     evict(file) {
@@ -83,15 +86,27 @@ export class ObservationStore {
             delete file.observations[key];
         }
     }
-    /** Record one more observation of `key` and return the new (capped) count. */
+    /**
+     * Record one more observation of `key` and return the new (capped) count. Load-mutate-save runs
+     * under a single exclusive lock so two concurrent increments (e.g. two reflection passes across
+     * sessions sharing an agentDir) can't both read the old count and drop one increment.
+     */
     increment(key, at) {
-        const file = this.load();
+        if (this.readOnly) {
+            // Zero-footprint (worker session): no lock, no dir, no write -- just the pure-read
+            // equivalent of what a real increment would have returned.
+            const file = this.load();
+            return Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
+        }
         const now = at ?? new Date().toISOString();
-        const count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
-        file.observations[key] = { count, lastAt: now };
-        this.evict(file);
-        this.save(file);
-        return count;
+        return withFileLockSync(this.filePath, () => {
+            const file = this.load();
+            const count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);
+            file.observations[key] = { count, lastAt: now };
+            this.evict(file);
+            this.save(file);
+            return count;
+        });
     }
     /** Current observation count for `key` (0 if never observed). */
     get(key) {

package/dist/core/learning/observation-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"observation-store.js","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate (G6). The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\n\tconstructor(filePath: string) {\n\t\tthis.filePath = filePath;\n\t}\n\n\tstatic forAgentDir(agentDir: string): ObservationStore {\n\t\treturn new ObservationStore(join(agentDir, \"state\", \"learning-observations.json\"));\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\tmkdirSync(dirname(this.filePath), { recursive: true });\n\t\twriteFileSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`, \"utf-8\");\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/** Record one more observation of `key` and return the new (capped) count. */\n\tincrement(key: string, at?: string): number {\n\t\tconst file = this.load();\n\t\tconst now = at ?? new Date().toISOString();\n\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\tfile.observations[key] = { count, lastAt: now };\n\t\tthis.evict(file);\n\t\tthis.save(file);\n\t\treturn count;\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}
+{"version":3,"file":"observation-store.js","sourceRoot":"","sources":["../../../src/core/learning/observation-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { stateFile } from \"../agent-paths.ts\";\nimport { isWorkerSession } from \"../session-role.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/**\n * Durable, BOUNDED evidence-strength store for the learning gate. The gate auto-applies a\n * durable change only once it has been *observed* enough times; a single reflection pass sees a\n * lesson once, so without persistence every proposal would look brand-new and never accumulate the\n * repeated evidence the gate requires. This store counts how many times the SAME lesson (keyed by\n * its durable layer + normalized summary) has been proposed across passes and sessions.\n *\n * File layout mirrors {@link ../models/fitness-store.ts}: a versioned JSON object under\n * `<agentDir>/state/`, best-effort writes, and a corrupt/missing file recovers as a fresh store.\n */\n\n/** Cap per-key counts so a hot lesson can't grow unbounded (the gate only needs a small threshold). */\nconst MAX_COUNT = 100;\n/** Cap the number of tracked keys; least-recently-incremented keys are evicted past this bound. */\nconst MAX_KEYS = 500;\n\ninterface ObservationEntry {\n\tcount: number;\n\t/** ISO timestamp of the most recent increment; drives least-recently-incremented eviction. */\n\tlastAt: string;\n}\n\ninterface ObservationStoreFile {\n\tversion: 1;\n\t/** observationKey -> accumulated evidence for that lesson. */\n\tobservations: Record<string, ObservationEntry>;\n}\n\n/**\n * Stable evidence key for a durable-change proposal: sha256 of the layer plus its summary,\n * lowercased and whitespace-collapsed, truncated to 24 hex chars. Normalization means the same\n * lesson re-observed with reworded whitespace/casing accumulates onto one key instead of scattering.\n */\nexport function observationKey(layer: string, summary: string): string {\n\tconst normalized = summary.toLowerCase().replace(/\\s+/g, \" \").trim();\n\treturn createHash(\"sha256\").update(`${layer}\\n${normalized}`).digest(\"hex\").slice(0, 24);\n}\n\nexport class ObservationStore {\n\tprivate readonly filePath: string;\n\tprivate readonly readOnly: boolean;\n\n\tconstructor(filePath: string, options?: { readOnly?: boolean }) {\n\t\tthis.filePath = filePath;\n\t\tthis.readOnly = options?.readOnly ?? isWorkerSession();\n\t}\n\n\tstatic forAgentDir(agentDir: string, options?: { readOnly?: boolean }): ObservationStore {\n\t\treturn new ObservationStore(stateFile(agentDir, \"learning-observations.json\"), options);\n\t}\n\n\tprivate load(): ObservationStoreFile {\n\t\ttry {\n\t\t\tif (!existsSync(this.filePath)) return { version: 1, observations: {} };\n\t\t\tconst parsed = JSON.parse(readFileSync(this.filePath, \"utf-8\")) as ObservationStoreFile;\n\t\t\tif (\n\t\t\t\tparsed &&\n\t\t\t\tparsed.version === 1 &&\n\t\t\t\tparsed.observations &&\n\t\t\t\ttypeof parsed.observations === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.observations)\n\t\t\t) {\n\t\t\t\t// Sanitize per-entry so a partially-mangled file still yields a usable store rather than\n\t\t\t\t// leaking NaN/undefined counts into the gate.\n\t\t\t\tconst clean: ObservationStoreFile = { version: 1, observations: {} };\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.observations)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\tvalue &&\n\t\t\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).count === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite((value as ObservationEntry).count) &&\n\t\t\t\t\t\ttypeof (value as ObservationEntry).lastAt === \"string\"\n\t\t\t\t\t) {\n\t\t\t\t\t\tclean.observations[key] = {\n\t\t\t\t\t\t\tcount: Math.min(Math.max(0, Math.floor((value as ObservationEntry).count)), MAX_COUNT),\n\t\t\t\t\t\t\tlastAt: (value as ObservationEntry).lastAt,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn clean;\n\t\t\t}\n\t\t} catch {\n\t\t\t// Unreadable/corrupt store: start fresh in memory; the next increment rewrites the file.\n\t\t}\n\t\treturn { version: 1, observations: {} };\n\t}\n\n\tprivate save(file: ObservationStoreFile): void {\n\t\twriteFileAtomicSync(this.filePath, `${JSON.stringify(file, null, \"\\t\")}\\n`);\n\t}\n\n\t/** Evict least-recently-incremented keys until the store is back within {@link MAX_KEYS}. */\n\tprivate evict(file: ObservationStoreFile): void {\n\t\tconst keys = Object.keys(file.observations);\n\t\tif (keys.length <= MAX_KEYS) return;\n\t\tkeys.sort((a, b) => {\n\t\t\tconst la = file.observations[a]!.lastAt;\n\t\t\tconst lb = file.observations[b]!.lastAt;\n\t\t\treturn la < lb ? -1 : la > lb ? 1 : 0;\n\t\t});\n\t\tfor (const key of keys.slice(0, keys.length - MAX_KEYS)) {\n\t\t\tdelete file.observations[key];\n\t\t}\n\t}\n\n\t/**\n\t * Record one more observation of `key` and return the new (capped) count. Load-mutate-save runs\n\t * under a single exclusive lock so two concurrent increments (e.g. two reflection passes across\n\t * sessions sharing an agentDir) can't both read the old count and drop one increment.\n\t */\n\tincrement(key: string, at?: string): number {\n\t\tif (this.readOnly) {\n\t\t\t// Zero-footprint (worker session): no lock, no dir, no write -- just the pure-read\n\t\t\t// equivalent of what a real increment would have returned.\n\t\t\tconst file = this.load();\n\t\t\treturn Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\t}\n\t\tconst now = at ?? new Date().toISOString();\n\t\treturn withFileLockSync(this.filePath, () => {\n\t\t\tconst file = this.load();\n\t\t\tconst count = Math.min((file.observations[key]?.count ?? 0) + 1, MAX_COUNT);\n\t\t\tfile.observations[key] = { count, lastAt: now };\n\t\t\tthis.evict(file);\n\t\t\tthis.save(file);\n\t\t\treturn count;\n\t\t});\n\t}\n\n\t/** Current observation count for `key` (0 if never observed). */\n\tget(key: string): number {\n\t\treturn this.load().observations[key]?.count ?? 0;\n\t}\n}\n"]}

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

@@ -54,7 +54,11 @@ export declare class SkillCurator {
     private readonly archiveDir;
     private readonly usageFile;
     constructor(skillsDir: string);
-    /** Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort. */
+    /**
+     * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.
+     * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions
+     * loading the same skill around the same time) can't both read the old usage map and drop a count.
+     */
     recordUse(name: string, now: number): void;
     /** Build the proposals from the current promoted-skill corpus. */
     proposeCuration(now: number, options?: Partial<Omit<CuratorOptions, "now">>): CurationProposals;

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

@@ -1 +1 @@
-{"version":3,"file":"skill-curator.d.ts","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,uFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAG/D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sGAAsG;IACtG,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAgC7G;AAWD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,SAAS,EAAE,MAAM,EAI5B;IAED,2FAA2F;IAC3F,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CASzC;IAED,kEAAkE;IAClE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,iBAAiB,CAOlG;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAezG;IAED,qFAAqF;IACrF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,kBAAkB,IAAI,iBAAiB,EAAE,CA+BxC;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAOjB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/** Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort. */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\tconst usage = this.loadUsage();\n\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\twriteFileSync(this.usageFile, JSON.stringify(usage, null, 2), \"utf-8\");\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\tlet release: (() => Promise<void>) | undefined;\n\t\ttry {\n\t\t\trelease = await lockfile.lock(this.skillsDir, { realpath: false, retries: 2 });\n\t\t\tconst archived: string[] = [];\n\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t}\n\t\t\treturn archived;\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t} finally {\n\t\t\tif (release) await release().catch(() => {});\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}
+{"version":3,"file":"skill-curator.d.ts","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,uFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAG/D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sGAAsG;IACtG,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAgC7G;AAWD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,SAAS,EAAE,MAAM,EAI5B;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWzC;IAED,kEAAkE;IAClE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,iBAAiB,CAOlG;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBzG;IAED,qFAAqF;IACrF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,kBAAkB,IAAI,iBAAiB,EAAE,CA+BxC;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAOjB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\nimport { withFileLock, withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/**\n\t * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.\n\t * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions\n\t * loading the same skill around the same time) can't both read the old usage map and drop a count.\n\t */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\twithFileLockSync(this.usageFile, () => {\n\t\t\t\tconst usage = this.loadUsage();\n\t\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\t\twriteFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));\n\t\t\t});\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\ttry {\n\t\t\treturn await withFileLock(\n\t\t\t\tthis.skillsDir,\n\t\t\t\t() => {\n\t\t\t\t\tconst archived: string[] = [];\n\t\t\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t\t\t}\n\t\t\t\t\treturn archived;\n\t\t\t\t},\n\t\t\t\t{ retries: 2 },\n\t\t\t);\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}

package/dist/core/learning/skill-curator.js

@@ -7,10 +7,10 @@
  * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable
  * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
-import lockfile from "proper-lockfile";
 import { jaccard, tokenize } from "../tools/skill-audit.js";
+import { withFileLock, withFileLockSync, writeFileAtomicSync } from "../util/atomic-file.js";
 export const DEFAULT_CURATOR_OPTIONS = {
     staleDays: 30,
     overlapThreshold: 0.5,
@@ -68,13 +68,19 @@ export class SkillCurator {
         this.archiveDir = join(skillsDir, ".archive");
         this.usageFile = join(skillsDir, ".usage.json");
     }
-    /** Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort. */
+    /**
+     * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.
+     * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions
+     * loading the same skill around the same time) can't both read the old usage map and drop a count.
+     */
     recordUse(name, now) {
         try {
-            const usage = this.loadUsage();
-            const prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };
-            usage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };
-            writeFileSync(this.usageFile, JSON.stringify(usage, null, 2), "utf-8");
+            withFileLockSync(this.usageFile, () => {
+                const usage = this.loadUsage();
+                const prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };
+                usage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };
+                writeFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));
+            });
         }
         catch {
             // usage tracking must never disrupt a turn
@@ -98,23 +104,19 @@ export class SkillCurator {
     async autoArchiveStale(now, options = {}) {
         if (!existsSync(this.skillsDir))
             return [];
-        let release;
         try {
-            release = await lockfile.lock(this.skillsDir, { realpath: false, retries: 2 });
-            const archived = [];
-            for (const a of this.proposeCuration(now, options).archive) {
-                if (this.archiveSkill(a.name))
-                    archived.push(a.name);
-            }
-            return archived;
+            return await withFileLock(this.skillsDir, () => {
+                const archived = [];
+                for (const a of this.proposeCuration(now, options).archive) {
+                    if (this.archiveSkill(a.name))
+                        archived.push(a.name);
+                }
+                return archived;
+            }, { retries: 2 });
         }
         catch {
             return []; // another session holds the lock, or fs error — skip this run
         }
-        finally {
-            if (release)
-                await release().catch(() => { });
-        }
     }
     /** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */
     archiveSkill(name) {

package/dist/core/learning/skill-curator.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-curator.js","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport lockfile from \"proper-lockfile\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/** Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort. */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\tconst usage = this.loadUsage();\n\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\twriteFileSync(this.usageFile, JSON.stringify(usage, null, 2), \"utf-8\");\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\tlet release: (() => Promise<void>) | undefined;\n\t\ttry {\n\t\t\trelease = await lockfile.lock(this.skillsDir, { realpath: false, retries: 2 });\n\t\t\tconst archived: string[] = [];\n\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t}\n\t\t\treturn archived;\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t} finally {\n\t\t\tif (release) await release().catch(() => {});\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}
+{"version":3,"file":"skill-curator.js","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\nimport { withFileLock, withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/**\n\t * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.\n\t * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions\n\t * loading the same skill around the same time) can't both read the old usage map and drop a count.\n\t */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\twithFileLockSync(this.usageFile, () => {\n\t\t\t\tconst usage = this.loadUsage();\n\t\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\t\twriteFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));\n\t\t\t});\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\ttry {\n\t\t\treturn await withFileLock(\n\t\t\t\tthis.skillsDir,\n\t\t\t\t() => {\n\t\t\t\t\tconst archived: string[] = [];\n\t\t\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t\t\t}\n\t\t\t\t\treturn archived;\n\t\t\t\t},\n\t\t\t\t{ retries: 2 },\n\t\t\t);\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}

package/dist/core/local-runtime-controller.d.ts

@@ -12,12 +12,16 @@ import type { Api, AssistantMessage, Model } from "@caupulican/pi-ai";
 import type { AgentSessionEvent } from "./agent-session.ts";
 import type { RouteDecision } from "./autonomy/contracts.ts";
 import type { ExtensionUIContext } from "./extensions/index.ts";
+import { type PrismLlamaCppDeps, PrismLlamaCppRuntime } from "./models/llamacpp-runtime.ts";
 import { type LocalRuntimeDeps, OllamaRuntime, TransformersRuntime } from "./models/local-runtime.ts";
 export interface LocalRuntimeControllerDeps {
     /** Root directory OllamaRuntime instances are scoped under — fixed for the session's lifetime. */
     agentDir: string;
     /** Test-injectable seams for OllamaRuntime's own fetch/spawn/exists calls; unset in production. */
     localRuntimeDeps?: LocalRuntimeDeps;
+    /** Test-injectable seams for PrismLlamaCppRuntime's own fetch/spawn/exists calls; unset in
+     * production (see {@link getPrismLlamaCppRuntime}). */
+    prismLlamaCppDeps?: PrismLlamaCppDeps;
     /** The session's last assistant message, to detect a just-failed local call and drop a stale
      * "confirmed up" flag. */
     getLastAssistantMessage(): AssistantMessage | undefined;
@@ -36,6 +40,12 @@ export declare class LocalRuntimeController {
     private readonly _runtimes;
     /** Lazy, cached by model+baseUrl so the router and `/models` share one sidecar handle per HF model. */
     private readonly _transformersRuntimes;
+    /** Lazy, cached (not baseUrl-keyed like the two above — pi's prism install is a single managed
+     * instance under agentDir, never an externally-configured server) so `/models add`, `/models
+     * stop`, `/models remove`, and the readiness gate below all share the SAME instance and can
+     * reliably reattach to a process this session started (`stop()`/`isRunning()` rely on in-memory
+     * child-process state). */
+    private _prismLlamaCppRuntime;
     /** Server URLs confirmed reachable THIS session — skips the health-check round trip on every
      * local-routed turn once warm. Keyed the same way as _runtimes. */
     private readonly _confirmedUp;
@@ -52,15 +62,32 @@ export declare class LocalRuntimeController {
      */
     getLocalRuntime(baseUrl?: string): OllamaRuntime;
     getTransformersRuntime(modelId: string, baseUrl?: string): TransformersRuntime;
+    /**
+     * Shared {@link PrismLlamaCppRuntime} for pi's own managed prism install — lazily created, cached
+     * for the controller's lifetime so `/models` (add/stop/remove) and the readiness gate below
+     * always see and can stop the SAME pi-managed process.
+     */
+    getPrismLlamaCppRuntime(): PrismLlamaCppRuntime;
     /** models.json registers a local model's baseUrl as `<server>/v1` (OpenAI-compat); the runtime's
      * own health/boot endpoints are on the Ollama-native server root. */
     deriveOllamaServerUrl(modelBaseUrl: string): string;
     private deriveOpenAICompatServerUrl;
     private isManagedLocalProvider;
+    /** Ollama/Transformers (provider-scoped) OR a pi-registered prism llama.cpp model (id-scoped —
+     * see {@link isPiManagedPrismLlamaCppModel}, which never matches a user's own hand-configured
+     * `llama-cpp` entry such as the built-in `llama-cpp/local` catalog model). */
+    private isManagedLocalModel;
+    private ensureManagedLocalReadiness;
+    private maybeInstallManagedLocalOnConsent;
     /**
-     * If the last assistant message in this session was an error from THIS exact local server, a
-     * cached "confirmed up" flag would be stale (the server may have died mid-session) — drop it so
-     * the next ensure-check is a real one instead of trusting stale state.
+     * ALWAYS scoped to both the server AND the exact model — never bare `serverUrl`. A single Ollama
+     * (or prism) server can host several models, and a serverUrl-only key let the FIRST model
+     * confirmed on a server silently wave through every other model requested on that same server:
+     * the cache hit at {@link ensureLocalModelReady}/{@link ensurePrismLlamaCppModelReady} short-
+     * circuits BEFORE the installed-model check and the residency arbiter run, so a genuinely missing
+     * model surfaced as a raw runtime error instead of `model_missing_on_server`, and residency
+     * bookkeeping silently skipped a model it never actually admitted. Transformers already had this
+     * right (one server per model, by construction); this makes every provider consistent.
      */
     private confirmationKey;
     private invalidateIfLastCallFailed;
@@ -95,6 +122,7 @@ export declare class LocalRuntimeController {
         reason: string;
         installGuide?: string[];
     }>;
+    private ensurePrismLlamaCppModelReady;
     private maybeInstallOllamaOnConsent;
     private maybeInstallTransformersOnConsent;
     /**
@@ -121,5 +149,39 @@ export declare class LocalRuntimeController {
         decision: RouteDecision;
         model: Model<Api>;
     } | undefined>;
+    /**
+     * Stop every pi-spawned local runtime (Ollama, Transformers, prism llama.cpp) that no longer
+     * backs any model in `eligibleModels` — the caller's post-reload/profile-switch configuration
+     * (typically: the foreground model plus whatever the model router's tiers still resolve to).
+     * Called by the reload path so a local model dropped from the live configuration doesn't leave
+     * its child process running untracked for the rest of the process lifetime.
+     *
+     * Never touches a server this session merely DETECTED (a user/system-run Ollama server, or any
+     * server that was already up when first probed): {@link OllamaRuntime.stop}/
+     * {@link TransformersRuntime.stop}/{@link PrismLlamaCppRuntime.stop} already no-op unless the
+     * instance holds a live pi-spawned child-process handle (see each class's own `stop()`), so
+     * calling `stop()` unconditionally on every cached instance below is safe by construction — it
+     * can never kill a process pi didn't start.
+     *
+     * Never stops a runtime still backing an eligible model. Eligibility is checked at the SAME
+     * granularity each map is keyed at: `_runtimes` is keyed by Ollama serverUrl (one server can host
+     * several models), so it survives as long as ANY eligible model still points at that server;
+     * `_transformersRuntimes` is keyed by (modelId, serverUrl) — one runtime per model, so eligibility
+     * is exact; the prism runtime is a single pi-owned instance that survives while ANY eligible model
+     * is pi-managed prism.
+     *
+     * The `_confirmedUp` cache is pruned separately, in ONE pass over every provider: since
+     * `confirmationKey` is uniformly `${serverUrl}\0${model.id}` across every provider, a single
+     * eligible-keys set built the same way covers all three providers. This also correctly drops a
+     * model's stale confirmation even when its SERVER survives (e.g. two Ollama models on one server,
+     * only one still eligible) — a case the coarser per-server runtime eviction above can't see on
+     * its own.
+     */
+    reconcile(eligibleModels: readonly Model<Api>[]): void;
+    /** Full teardown of every pi-spawned local runtime — reconcile against an empty eligible set. */
+    dispose(): void;
+    /** Shared cache-key shape for {@link _transformersRuntimes}, factored out so
+     * {@link getTransformersRuntime} and {@link reconcile} can never drift apart. */
+    private _transformersRuntimeKey;
 }
 //# sourceMappingURL=local-runtime-controller.d.ts.map