@nanonets/graft 0.23.1 → 0.24.1

package/dist/skills/staleness.js

@@ -0,0 +1,178 @@
+/**
+ * Cue misses and 60 days unused (design 1.3, 4.19, spec 13, P26, P27).
+ *
+ * A cue miss is a block a `job` cue brought in whose steps the agent never
+ * ran. Two in a row for one asks phrase drop that phrase from
+ * `metadata.asks`, only when Trail wrote the file last (its hash is the one
+ * in state) and never the last phrase; a hand-edited skill is never edited,
+ * the count just stays. Phrases are never added. A phrase can be the
+ * person's own words (D71 b), so outside SKILL.md it is only ever its
+ * `phraseSha`: 8 hex of sha256 (R30).
+ *
+ * A skill unused for 60 days leaves the index line; its cues still fire on a
+ * typed ask, and its folder stays.
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { appendLedger } from './ledger.js';
+import { getSkillState, updateSkillState } from './state.js';
+import { listAllPersonal } from './store.js';
+import { parseSkillMd, skillHash } from './skillmd.js';
+import { localDate } from './settings.js';
+import { flatLine } from '../notes/flatten.js';
+import { writePrivate } from '../util/private-fs.js';
+import { tryStoreLock, MAX_SKILL_BYTES } from './store-fs.js';
+export const UNUSED_DAYS = 60;
+const DROP_AT = 2;
+const MAX_KEYS = 20;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** 8 hex of sha256 of the phrase, its spaces collapsed and lower-cased (R30). */
+export function phraseSha(phrase) {
+    const t = String(phrase ?? '').normalize('NFC').trim().replace(/\s+/g, ' ').toLowerCase();
+    return createHash('sha256').update(t).digest('hex').slice(0, 8);
+}
+const counts = (st) => {
+    const c = st.cueMisses;
+    if (!c || typeof c !== 'object' || Array.isArray(c))
+        return {};
+    return Object.fromEntries(Object.entries(c).filter(([k, v]) => /^[0-9a-f]{8}$/.test(k) && typeof v === 'number' && Number.isFinite(v) && v > 0));
+};
+/** At credit flush (4.19). Returns whether the phrase should be dropped now. Changes st.cueMisses only. */
+export function noteCueResult(st, phraseSha, followed) {
+    if (!phraseSha || !/^[0-9a-f]{8}$/.test(phraseSha))
+        return { drop: false };
+    const c = counts(st);
+    if (followed)
+        delete c[phraseSha];
+    else
+        c[phraseSha] = (c[phraseSha] ?? 0) + 1;
+    const keys = Object.keys(c);
+    for (const k of keys.slice(0, Math.max(0, keys.length - MAX_KEYS)))
+        if (k !== phraseSha)
+            delete c[k];
+    st.cueMisses = c;
+    return { drop: !followed && (c[phraseSha] ?? 0) >= DROP_AT };
+}
+const ASKS_LINE = /^ {2}asks: .*$/m;
+/**
+ * Removes the asks phrase whose phraseSha matches when the file's hash equals st.hash; never the last phrase.
+ * Updates st.hash. Never writes through a link (the skill's folder or its SKILL.md). The caller holds the locks.
+ */
+export function dropPhrase(ref, st, sha) {
+    try {
+        if (lstatSync(ref.dir).isSymbolicLink())
+            return false;
+        const f = lstatSync(ref.file);
+        if (!f.isFile() || f.size > MAX_SKILL_BYTES)
+            return false;
+        const text = readFileSync(ref.file, 'utf8');
+        if (!st.hash || skillHash(text) !== st.hash)
+            return false;
+        const parsed = parseSkillMd(text, ref.name);
+        if (!parsed || parsed.meta.trail !== ref.id)
+            return false;
+        const phrases = String(parsed.meta.asks ?? '').split(',').map((p) => p.trim()).filter(Boolean);
+        const keep = phrases.filter((p) => phraseSha(p) !== sha);
+        if (keep.length === phrases.length || keep.length === 0)
+            return false;
+        const front = text.slice(0, text.indexOf('\n---', 3) + 1);
+        if (!front || (front.match(new RegExp(ASKS_LINE.source, 'gm')) ?? []).length !== 1)
+            return false;
+        const asks = keep.join(', ');
+        const next = text.slice(0, front.length).replace(ASKS_LINE, `  asks: ${JSON.stringify(flatLine(asks, 1024))}`) + text.slice(front.length);
+        const back = parseSkillMd(next, ref.name);
+        if (!back || back.meta.asks !== asks || back.meta.trail !== ref.id || back.steps.length !== parsed.steps.length)
+            return false;
+        writePrivate(ref.file, next);
+        st.hash = skillHash(next);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 4.19 at a credit flush, with the locks: the count in state, and at 2 misses in a row the drop (store lock, then
+ * the state lock, as a save takes them), its ledger `cue` line. Fails closed: nothing dropped.
+ */
+export function cueFlush(skillId, sha, followed, env, now = new Date()) {
+    if (!sha || !/^[0-9a-f]{8}$/.test(sha))
+        return { dropped: false };
+    const had = getSkillState(skillId, env);
+    if (!had || (followed && !counts(had)[sha]))
+        return { dropped: false };
+    let drop = false;
+    updateSkillState(skillId, (s) => {
+        if (!s)
+            return s;
+        drop = noteCueResult(s, sha, followed).drop;
+        return s;
+    }, env);
+    if (!drop)
+        return { dropped: false };
+    const ref = listAllPersonal(env).find((r) => r.id === skillId);
+    if (!ref)
+        return { dropped: false };
+    let dropped = false;
+    try {
+        tryStoreLock(env, () => updateSkillState(skillId, (s) => {
+            if (s && dropPhrase(ref, s, sha)) {
+                dropped = true;
+                const c = counts(s);
+                delete c[sha];
+                s.cueMisses = c;
+            }
+            return s;
+        }, env));
+    }
+    catch {
+        return { dropped: false };
+    }
+    if (dropped) {
+        try {
+            appendLedger(skillId, { at: now.toISOString(), event: 'cue', skill: skillId, phraseSha: sha, change: 'dropped' }, env);
+        }
+        catch { /* state is the truth */ }
+    }
+    return { dropped };
+}
+/** The date it was last used or saved when that is 60+ days ago, else null. */
+export function unusedSince(st, now = new Date()) {
+    // A date that can't be read, or one after now (a clock that moved back, a hand edit), says nothing: the next one does.
+    const ok = (d) => typeof d === 'string' && !Number.isNaN(Date.parse(d)) && Date.parse(d) <= now.getTime() + DAY_MS;
+    const base = [st.lastUsedAt, st.addedAt].find(ok);
+    if (!base || now.getTime() - Date.parse(base) < UNUSED_DAYS * DAY_MS)
+        return null;
+    return localDate(base);
+}
+/** skill_stale{unused} is due: once per unused stretch (a use after it was said starts a new one). Sets unusedSaidAt. */
+export function markUnusedSaid(skillId, env, now = new Date()) {
+    let due = false;
+    updateSkillState(skillId, (s) => {
+        if (!s || !unusedSince(s, now))
+            return s;
+        const said = s.unusedSaidAt ? Date.parse(s.unusedSaidAt) : NaN;
+        const used = Date.parse(s.lastUsedAt || s.addedAt);
+        if (!Number.isNaN(said) && !(used > said))
+            return s;
+        s.unusedSaidAt = now.toISOString();
+        due = true;
+        return s;
+    }, env);
+    return due;
+}
+/** skill_stale{missing} is due: once per skill per local day (4.18). Sets missingSaidAt. */
+export function markMissingSaid(skillId, env, now = new Date()) {
+    let due = false;
+    updateSkillState(skillId, (s) => {
+        if (!s)
+            return s;
+        if (s.missingSaidAt && localDate(s.missingSaidAt) === localDate(now))
+            return s;
+        s.missingSaidAt = now.toISOString();
+        due = true;
+        return s;
+    }, env);
+    return due;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/skills/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../../src/skills/staleness.ts"],"names":[],"mappings":"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"}

package/dist/skills/state.d.ts

@@ -0,0 +1,36 @@
+import type { LedgerUse, SkillState, SkillsStateFile } from './types.js';
+export declare function skillsStatePath(env?: NodeJS.ProcessEnv): string;
+export declare function readSkillsState(env?: NodeJS.ProcessEnv): SkillsStateFile;
+export declare function getSkillState(id: string, env?: NodeJS.ProcessEnv): SkillState | null;
+/**
+ * Locked read-modify-write of one entry. Return undefined from fn to delete. undefined also when the lock timed out,
+ * or when the state folder is a link (never written through, own-folder.ts): nothing changed either way.
+ */
+export declare function updateSkillState(id: string, fn: (s: SkillState | undefined) => SkillState | undefined, env?: NodeJS.ProcessEnv): SkillState | undefined;
+/**
+ * 4.8, after the caller wrote the ledger `use` line: uses, lastUsedAt/Repo; a passed check counts as a checked use,
+ * sets lastWorked (local date) and makes a candidate active; the failed step joins lastFails (the last two), and two
+ * at the same step make it needs-fix; a use with no failed step empties lastFails. Ready probes never count.
+ */
+export declare function recordUse(id: string, use: LedgerUse, env?: NodeJS.ProcessEnv): SkillState | undefined;
+/**
+ * The person corrected a use within 2 prompts (3.2 step 5): one ledger `corrected` line per use, and when the use
+ * right before or after it in the ledger was corrected too, needs-fix (spec 13: two uses in a row corrected).
+ * The ledger is read and the line written under the state lock, so two hooks correcting neighbouring uses at once
+ * each see the other's line. undefined when the skill has no state or no such use, or the ledger can't be written.
+ */
+export declare function recordCorrected(id: string, useId: string, env?: NodeJS.ProcessEnv, now?: Date): SkillState | undefined;
+/**
+ * A needs-fix skill whose SKILL.md changed by hand after it was marked (its hash is not the one kept at the mark,
+ * `fixHash`, D65; the hash Trail wrote when no mark hash was kept) was fixed: it goes back to what it was (4.8;
+ * candidate when that is unknown), with its failures forgotten. An edit made before the failures is not a fix, so
+ * it can't bring the skill back read after read. `hash` stays the one Trail wrote (spec 6: hand edits are phase 2's
+ * to propose a diff for). Any other status is left alone.
+ */
+export declare function handEdited(id: string, fileHash: string, env?: NodeJS.ProcessEnv, now?: Date): SkillState | undefined;
+/** The skill used most recently in any of repoKeys, with when (for the check cue). A retired skill never answers. */
+export declare function lastUsedIn(repoKeys: string[], env?: NodeJS.ProcessEnv): {
+    id: string;
+    at: string;
+} | null;
+//# sourceMappingURL=state.d.ts.map

package/dist/skills/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/skills/state.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAe,eAAe,EAAE,MAAM,YAAY,CAAC;AAgBtF,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAE/D;AA8CD,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,eAAe,CAExE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,UAAU,GAAG,IAAI,CAEpF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,KAAK,UAAU,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,UAAU,GAAG,SAAS,CAiBvJ;AA4CD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,UAAU,GAAG,SAAS,CAqBrG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,UAAU,GAAG,SAAS,CA0BlI;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,UAAU,GAAG,SAAS,CAgBhI;AAED,qHAAqH;AACrH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQzG"}

package/dist/skills/state.js

@@ -0,0 +1,259 @@
+/**
+ * `~/.trail/state/skills.json` (design 2.2, spec 6): what changes often
+ * about each skill, per person, keyed by the skill id, for every scope:
+ * status, where it came from, uses and checked uses, when it last worked,
+ * the hash of the file as Trail last wrote it, and the failed step of the
+ * last two uses. The SKILL.md holds only what describes the skill.
+ *
+ * Status moves (4.8, spec 13): a candidate becomes active on its first use
+ * whose check passed; two uses in a row that failed at the same step, or
+ * that the person corrected, make it needs-fix (never injected; the index
+ * says why), and it goes back to what it was when its SKILL.md is changed by
+ * hand. A failed ready probe never counts against it. Every move is a ledger
+ * `status` line, written after the state file.
+ *
+ * Every write is a locked read-modify-write; a lock that can't be had in
+ * time changes nothing. Keys a later version adds are kept.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { readJsonSafe, trailPath, withLock, writePrivate } from '../util/private-fs.js';
+import { appendLedger, readLedger } from './ledger.js';
+import { localDate } from './settings.js';
+import { parseSkillMd, skillHash } from './skillmd.js';
+import { isLinked } from './own-folder.js';
+import { dirname } from 'node:path';
+const STATUSES = new Set(['candidate', 'active', 'needs-fix', 'retired']);
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** 'Nov 2', in local time. */
+const monthDay = (iso) => {
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? 'an earlier day' : `${MONTHS[d.getMonth()]} ${d.getDate()}`;
+};
+export function skillsStatePath(env) {
+    return trailPath(env, 'state', 'skills.json');
+}
+const isMap = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const strOr = (v, d) => (typeof v === 'string' ? v : d);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0);
+/** An entry as read: null when it isn't one; missing newer fields get their defaults; unknown keys stay. */
+function entryOf(v) {
+    if (!isMap(v) || typeof v.name !== 'string' || !STATUSES.has(v.status))
+        return null;
+    const src = isMap(v.source) && typeof v.source.at === 'string' ? { commands: num(v.source.commands), failed: num(v.source.failed), at: v.source.at } : null;
+    const fails = Array.isArray(v.lastFails)
+        ? v.lastFails.filter((f) => isMap(f) && typeof f.step === 'number' && typeof f.at === 'string').slice(-2)
+        : [];
+    const { fixHash, ...rest } = v;
+    return {
+        ...rest,
+        ...(typeof fixHash === 'string' ? { fixHash } : {}),
+        name: v.name,
+        scope: v.scope === 'repo' || v.scope === 'team' ? v.scope : 'personal',
+        status: v.status,
+        from: v.from === 'init' || v.from === 'repeated' || v.from === 'repaired' ? v.from : 'asked',
+        runId: strOr(v.runId, null),
+        addedAt: strOr(v.addedAt, ''),
+        lastWorked: strOr(v.lastWorked, null),
+        lastUsedAt: strOr(v.lastUsedAt, null),
+        lastUsedRepo: strOr(v.lastUsedRepo, null),
+        uses: num(v.uses),
+        checkedUses: num(v.checkedUses),
+        hash: strOr(v.hash, ''),
+        source: src,
+        lastFails: fails.map((f) => ({ step: f.step, at: f.at })),
+        promoteOffers: isMap(v.promoteOffers) ? v.promoteOffers : {},
+    };
+}
+function fileOf(raw) {
+    const skills = {};
+    if (isMap(raw) && isMap(raw.skills)) {
+        for (const [id, v] of Object.entries(raw.skills)) {
+            const e = entryOf(v);
+            if (e)
+                skills[id] = e;
+        }
+    }
+    return { v: 1, skills };
+}
+export function readSkillsState(env) {
+    return fileOf(readJsonSafe(skillsStatePath(env)));
+}
+export function getSkillState(id, env) {
+    return readSkillsState(env).skills[id] ?? null;
+}
+/**
+ * Locked read-modify-write of one entry. Return undefined from fn to delete. undefined also when the lock timed out,
+ * or when the state folder is a link (never written through, own-folder.ts): nothing changed either way.
+ */
+export function updateSkillState(id, fn, env) {
+    const path = skillsStatePath(env);
+    if (isLinked(dirname(path)))
+        return undefined;
+    const done = withLock(path, () => {
+        const raw = readJsonSafe(path);
+        const keep = isMap(raw) ? raw : {};
+        const file = fileOf(raw);
+        const had = file.skills[id];
+        const next = fn(had === undefined ? undefined : structuredClone(had));
+        if (next === undefined) {
+            if (had === undefined)
+                return undefined;
+            delete file.skills[id];
+        }
+        else
+            file.skills[id] = next;
+        writePrivate(path, `${JSON.stringify({ ...keep, v: 1, skills: file.skills }, null, 2)}\n`);
+        return next;
+    });
+    return done.ok ? done.value : undefined;
+}
+/** updateSkillState, then the ledger status lines fn collected, only once the state is written. */
+function change(id, env, fn) {
+    const moves = [];
+    const next = updateSkillState(id, (s) => (s ? fn(s, moves) : undefined), env);
+    if (next)
+        for (const m of moves) {
+            try {
+                appendLedger(id, { event: 'status', skill: id, ...m }, env);
+            }
+            catch { /* the state is the truth; the ledger is its record */ }
+        }
+    return next;
+}
+/**
+ * The hash of the personal skill's SKILL.md as it is now (`skills/<name>/SKILL.md`, a regular file of at most
+ * 64 KB that is still this skill's), or undefined. D65: kept when the skill is marked needs-fix, so a hand edit
+ * made before the failures is not taken for a fix.
+ */
+function fileHashOf(id, name, env) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name) || name.includes('..'))
+        return undefined; // one folder name only
+    try {
+        const file = trailPath(env, 'skills', name, 'SKILL.md');
+        const st = statSync(file);
+        if (!st.isFile() || st.size > 64 * 1024)
+            return undefined;
+        const text = readFileSync(file, 'utf8');
+        return parseSkillMd(text, name)?.meta.trail === id ? skillHash(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** To needs-fix from candidate or active, keeping what it was and the file's hash right now. */
+function markNeedsFix(id, s, why, at, moves, env) {
+    if (s.status !== 'candidate' && s.status !== 'active')
+        return;
+    moves.push({ at, from: s.status, to: 'needs-fix', reason: 'failed-twice' });
+    s.prevStatus = s.status;
+    s.status = 'needs-fix';
+    s.statusWhy = why;
+    const now = fileHashOf(id, s.name, env);
+    if (now)
+        s.fixHash = now;
+    else
+        delete s.fixHash;
+}
+/**
+ * 4.8, after the caller wrote the ledger `use` line: uses, lastUsedAt/Repo; a passed check counts as a checked use,
+ * sets lastWorked (local date) and makes a candidate active; the failed step joins lastFails (the last two), and two
+ * at the same step make it needs-fix; a use with no failed step empties lastFails. Ready probes never count.
+ */
+export function recordUse(id, use, env) {
+    return change(id, env, (s, moves) => {
+        s.uses += 1;
+        s.lastUsedAt = use.at;
+        s.lastUsedRepo = use.repo;
+        if (use.check === 'passed') {
+            s.checkedUses += 1;
+            s.lastWorked = localDate(use.at);
+            if (s.status === 'candidate') {
+                moves.push({ at: use.at, from: 'candidate', to: 'active', reason: 'checked-use' });
+                s.status = 'active';
+            }
+        }
+        if (use.failedStep === null)
+            s.lastFails = [];
+        else {
+            s.lastFails = [...s.lastFails, { step: use.failedStep, at: use.at }].slice(-2);
+            const [a, b] = s.lastFails;
+            if (a && b && a.step === b.step)
+                markNeedsFix(id, s, `step ${b.step} failed on ${monthDay(a.at)} and ${monthDay(b.at)}`, use.at, moves, env);
+        }
+        return s;
+    });
+}
+/**
+ * The person corrected a use within 2 prompts (3.2 step 5): one ledger `corrected` line per use, and when the use
+ * right before or after it in the ledger was corrected too, needs-fix (spec 13: two uses in a row corrected).
+ * The ledger is read and the line written under the state lock, so two hooks correcting neighbouring uses at once
+ * each see the other's line. undefined when the skill has no state or no such use, or the ledger can't be written.
+ */
+export function recordCorrected(id, useId, env, now = new Date()) {
+    const at = now.toISOString();
+    let found = false;
+    const next = change(id, env, (s, moves) => {
+        const lines = readLedger(id, env);
+        const uses = lines.filter((l) => l.event === 'use');
+        const i = uses.findIndex((u) => u.useId === useId);
+        if (i < 0)
+            return s;
+        const corrected = new Set(lines.flatMap((l) => (l.event === 'corrected' ? [l.useId] : [])));
+        if (!corrected.has(useId)) {
+            try {
+                appendLedger(id, { at, event: 'corrected', skill: id, useId }, env);
+            }
+            catch {
+                return s;
+            }
+            corrected.add(useId);
+        }
+        found = true;
+        const pair = [uses[i - 1], uses[i + 1]].find((u) => u && corrected.has(u.useId));
+        if (pair) {
+            const [a, b] = Date.parse(pair.at) < Date.parse(uses[i].at) ? [pair, uses[i]] : [uses[i], pair];
+            markNeedsFix(id, s, `corrected after its use on ${monthDay(a.at)} and ${monthDay(b.at)}`, at, moves, env);
+        }
+        return s;
+    });
+    return found ? next : undefined;
+}
+/**
+ * A needs-fix skill whose SKILL.md changed by hand after it was marked (its hash is not the one kept at the mark,
+ * `fixHash`, D65; the hash Trail wrote when no mark hash was kept) was fixed: it goes back to what it was (4.8;
+ * candidate when that is unknown), with its failures forgotten. An edit made before the failures is not a fix, so
+ * it can't bring the skill back read after read. `hash` stays the one Trail wrote (spec 6: hand edits are phase 2's
+ * to propose a diff for). Any other status is left alone.
+ */
+export function handEdited(id, fileHash, env, now = new Date()) {
+    // Checked before the lock (most reads change nothing) and again under it.
+    const edited = (e) => e.status === 'needs-fix' && fileHash !== (e.fixHash ?? e.hash);
+    const s = getSkillState(id, env);
+    if (!s || !edited(s))
+        return s ?? undefined;
+    return change(id, env, (e, moves) => {
+        if (!edited(e))
+            return e;
+        const back = e.prevStatus && e.prevStatus !== 'needs-fix' && e.prevStatus !== 'retired' ? e.prevStatus : 'candidate';
+        moves.push({ at: now.toISOString(), from: 'needs-fix', to: back, reason: 'restore' });
+        e.status = back;
+        e.lastFails = [];
+        delete e.statusWhy;
+        delete e.prevStatus;
+        delete e.fixHash;
+        return e;
+    });
+}
+/** The skill used most recently in any of repoKeys, with when (for the check cue). A retired skill never answers. */
+export function lastUsedIn(repoKeys, env) {
+    const keys = new Set(repoKeys.map((k) => k.toLowerCase()));
+    let best = null;
+    for (const [id, s] of Object.entries(readSkillsState(env).skills)) {
+        if (s.status === 'retired' || !s.lastUsedAt || !s.lastUsedRepo || !keys.has(s.lastUsedRepo.toLowerCase()))
+            continue;
+        if (!best || Date.parse(s.lastUsedAt) > Date.parse(best.at))
+            best = { id, at: s.lastUsedAt };
+    }
+    return best;
+}
+//# sourceMappingURL=state.js.map

package/dist/skills/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/skills/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAc,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;AACvF,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACpG,8BAA8B;AAC9B,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,EAAE;IAC/B,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;AACjG,CAAC,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,OAAO,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,CAAU,EAAgC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACrH,MAAM,KAAK,GAAG,CAAI,CAAU,EAAE,CAAI,EAAc,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnF,MAAM,GAAG,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAExG,4GAA4G;AAC5G,SAAS,OAAO,CAAC,CAAU;IACzB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAqB,CAAC;QAAE,OAAO,IAAI,CAAC;IACnG,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5J,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QACtC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5I,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/B,OAAO;QACL,GAAG,IAAI;QACP,GAAG,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU;QACtE,MAAM,EAAE,CAAC,CAAC,MAAqB;QAC/B,IAAI,EAAE,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;QAC5F,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC;QAC3B,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7B,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC;QACrC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC;QACrC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,YAAY,EAAE,IAAI,CAAC;QACzC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACjB,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC;QAC/B,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG;QACX,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACzD,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,aAA6C,CAAC,CAAC,CAAC,EAAE;KAChF,CAAC;AAClB,CAAC;AAED,SAAS,MAAM,CAAC,GAAY;IAC1B,MAAM,MAAM,GAA+B,EAAE,CAAC;IAC9C,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACrB,IAAI,CAAC;gBAAE,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,OAAO,MAAM,CAAC,YAAY,CAAU,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,GAAuB;IAC/D,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAU,EAAE,EAAyD,EAAE,GAAuB;IAC7H,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE;QAC/B,MAAM,GAAG,GAAG,YAAY,CAAU,IAAI,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACxC,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;;YAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QAC9B,YAAY,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3F,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAID,mGAAmG;AACnG,SAAS,MAAM,CAAC,EAAU,EAAE,GAAkC,EAAE,EAAkE;IAChI,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9E,IAAI,IAAI;QAAE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC;gBAAC,YAAY,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,sDAAsD,CAAC,CAAC;QACvI,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,EAAU,EAAE,IAAY,EAAE,GAAuB;IACnE,IAAI,CAAC,mCAAmC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC,CAAC,uBAAuB;IACrH,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACxD,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxC,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,gGAAgG;AAChG,SAAS,YAAY,CAAC,EAAU,EAAE,CAAa,EAAE,GAAW,EAAE,EAAU,EAAE,KAAmB,EAAE,GAAuB;IACpH,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO;IAC9D,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;IAC5E,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACxB,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC;IACvB,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC;IAClB,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,GAAG;QAAE,CAAC,CAAC,OAAO,GAAG,GAAG,CAAC;;QACpB,OAAO,CAAC,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,GAAc,EAAE,GAAuB;IAC3E,OAAO,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QAClC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,EAAE,CAAC;QACtB,CAAC,CAAC,YAAY,GAAG,GAAG,CAAC,IAAI,CAAC;QAC1B,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC3B,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;YACnB,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjC,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;gBACnF,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC;YACtB,CAAC;QACH,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI;YAAE,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC;aACzC,CAAC;YACJ,CAAC,CAAC,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,UAAU,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/E,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;gBAAE,YAAY,CAAC,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,cAAc,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/I,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU,EAAE,KAAa,EAAE,GAAuB,EAAE,MAAY,IAAI,IAAI,EAAE;IACxG,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAC7B,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACpE,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACnD,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5F,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC;YACtE,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,CAAC;YACX,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,KAAK,GAAG,IAAI,CAAC;QACb,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACjF,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,CAAC;YACnG,YAAY,CAAC,EAAE,EAAE,CAAC,EAAE,8BAA8B,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC5G,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,QAAgB,EAAE,GAAuB,EAAE,MAAY,IAAI,IAAI,EAAE;IACtG,0EAA0E;IAC1E,MAAM,MAAM,GAAG,CAAC,CAAa,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,QAAQ,KAAK,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;IACjG,MAAM,CAAC,GAAG,aAAa,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,IAAI,SAAS,CAAC;IAC5C,OAAO,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QAClC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;QACzB,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,KAAK,WAAW,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QACrH,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QACtF,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC;QACjB,OAAO,CAAC,CAAC,SAAS,CAAC;QACnB,OAAO,CAAC,CAAC,UAAU,CAAC;QACpB,OAAO,CAAC,CAAC,OAAO,CAAC;QACjB,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,UAAU,CAAC,QAAkB,EAAE,GAAuB;IACpE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3D,IAAI,IAAI,GAAsC,IAAI,CAAC;IACnD,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;YAAE,SAAS;QACpH,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,IAAI,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;IAC/F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/skills/store-fs.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The file side of the skill store (store.ts, store-held.ts): private
+ * folders that never chmod or write through a link, capped reads, the one
+ * store lock, a skill folder written whole, and the state entry and ledger
+ * line a new personal skill starts with.
+ *
+ * A name reaches here from an agent's command line or a person's, so every
+ * name is checked to be one folder name before it is joined to a path.
+ */
+import { type Stats } from 'node:fs';
+import type { CompiledSkill, SkillFrom, SkillRef, SkillState } from './types.js';
+import { type Locked } from '../util/private-fs.js';
+/** SKILL.md is at most 60 lines; anything this big is not one. */
+export declare const MAX_SKILL_BYTES: number;
+/** How long a person's command waits for the store; a hook's bookkeeping waits less. */
+export declare const PERSON_WAIT_MS = 1000;
+export declare const HOOK_WAIT_MS = 200;
+/** One folder name: no separators, no dot start, no `..`. Wider than NAME_RE so hand-made folders can be named back. */
+export declare const safeName: (name: string) => boolean;
+export declare const lstatOrNull: (p: string) => Stats | null;
+export declare const statOrNull: (p: string) => Stats | null;
+/** A folder of ours: made 0700 when missing, tightened when it is a real folder; a link is left as it is (never chmod through it). */
+export declare function privateDir(dir: string): void;
+/** The file's text when it is a regular file (links followed) of at most 64 KB; null otherwise. */
+export declare function readCapped(file: string): string | null;
+export declare const skillsDir: (env?: NodeJS.ProcessEnv) => string;
+export declare const heldDir: (env?: NodeJS.ProcessEnv) => string;
+export declare const retiredDir: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * Every change to skills/ or held/ runs under one lock (`skills/.store.lock`). Throws when it can't be had in time,
+ * and before anything is written when one of Trail's own folders is a link (own-folder.ts).
+ */
+export declare function underStoreLock<T>(env: NodeJS.ProcessEnv | undefined, fn: () => T, waitMs?: number): T;
+/** The same lock for a hook's bookkeeping: `{ ok: false }` when busy or when one of Trail's own folders is a link; nothing changed. */
+export declare function tryStoreLock<T>(env: NodeJS.ProcessEnv | undefined, fn: () => T, waitMs?: number): Locked<T>;
+/**
+ * A skill's folder, written whole into a folder that must not exist yet (made here, 0700): SKILL.md (0600), each
+ * helper in scripts/ (0700), and an empty lessons/ when asked. Throws on a folder already there (a link included),
+ * a bad name, or a helper whose file name is not one plain file name.
+ */
+export declare function writeSkillFolder(dir: string, c: CompiledSkill, text: string, opts: {
+    lessons: boolean;
+}): void;
+export declare function newSkillId(): string;
+/**
+ * The id to save under: the compiled one, unless another skill already holds it, a retired one included (restoring
+ * it brings its state back under that id, so two skills must never share one).
+ */
+export declare function freeId(id: string, name: string, env?: NodeJS.ProcessEnv): string;
+/** Throws unless the name can be a saved skill's: NAME_RE, no `--` or trailing dash, not one of Trail's own words. */
+export declare function checkSaveName(name: string): void;
+/** The skill folders other tools keep in the person's home (`~/.claude/skills`, `~/.agents/skills`, `$CLAUDE_CONFIG_DIR/skills`). */
+export declare function homeSkillDirs(env?: NodeJS.ProcessEnv): string[];
+/** What keeping or restoring a skill would collide with, without a checkout: built in, a personal skill, a host's skill. */
+export declare function takenAtHome(name: string, env?: NodeJS.ProcessEnv): 'built-in' | 'personal' | 'host' | null;
+export declare function personalRef(id: string, name: string, applies: string | null, env?: NodeJS.ProcessEnv): SkillRef;
+/**
+ * A new personal skill's state (candidate, uses 0) and its ledger `saved` line. Throws when the state can't be
+ * written (its lock busy, as a hook that died holding it leaves it for 10 s): a skill with no state entry would be
+ * recalled but could never count a use, so the caller undoes the save.
+ */
+export declare function startSkill(id: string, init: {
+    name: string;
+    from: SkillFrom;
+    runId: string | null;
+    hash: string;
+    source: SkillState['source'];
+    version: string;
+    consent: 'offer-yes' | 'asked' | 'init';
+    stepsVerified: number;
+    stepsTotal: number;
+    now: Date;
+    env?: NodeJS.ProcessEnv;
+}): void;
+/** Compiled steps plus a check that is not itself a step (4.9 step 10). */
+export declare const stepsTotal: (c: Pick<CompiledSkill, "steps" | "check" | "checkIsStep">) => number;
+//# sourceMappingURL=store-fs.d.ts.map

package/dist/skills/store-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-fs.d.ts","sourceRoot":"","sources":["../../src/skills/store-fs.ts"],"names":[],"mappings":"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"}