@nanonets/graft 0.24.0 → 0.24.1

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":"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"}

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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"}

package/dist/skills/store-fs.js

@@ -0,0 +1,194 @@
+/**
+ * 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 { chmodSync, lstatSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { trailPath, withLock, writePrivate } from '../util/private-fs.js';
+import { BUILT_IN_NAMES, goodName } from './compile-words.js';
+import { appendLedger } from './ledger.js';
+import { getSkillState, updateSkillState } from './state.js';
+import { localDate } from './settings.js';
+import { randomBytes } from 'node:crypto';
+import { linkedOwnFolder, ownFolder } from './own-folder.js';
+const POSIX = process.platform !== 'win32';
+/** SKILL.md is at most 60 lines; anything this big is not one. */
+export const MAX_SKILL_BYTES = 64 * 1024;
+/** How long a person's command waits for the store; a hook's bookkeeping waits less. */
+export const PERSON_WAIT_MS = 1000;
+export 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 const safeName = (name) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(String(name)) && !String(name).includes('..');
+export const lstatOrNull = (p) => {
+    try {
+        return lstatSync(p);
+    }
+    catch {
+        return null;
+    }
+};
+export const statOrNull = (p) => {
+    try {
+        return statSync(p);
+    }
+    catch {
+        return 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 function privateDir(dir) {
+    if (!lstatOrNull(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = lstatOrNull(dir);
+    if (POSIX && st?.isDirectory()) {
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch { /* not ours to change */ }
+    }
+}
+/** The file's text when it is a regular file (links followed) of at most 64 KB; null otherwise. */
+export function readCapped(file) {
+    const st = statOrNull(file);
+    if (!st?.isFile() || st.size > MAX_SKILL_BYTES)
+        return null;
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export const skillsDir = (env) => trailPath(env, 'skills');
+export const heldDir = (env) => trailPath(env, 'held');
+export const retiredDir = (env) => join(skillsDir(env), '.retired');
+/**
+ * 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 function underStoreLock(env, fn, waitMs = PERSON_WAIT_MS) {
+    const linked = linkedOwnFolder(env);
+    if (linked)
+        ownFolder(trailPath(env, linked));
+    const done = tryStoreLock(env, fn, waitMs);
+    if (!done.ok)
+        throw new Error('trail: the skill store is busy (another trail command is changing it). Try again.');
+    return done.value;
+}
+/** 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 function tryStoreLock(env, fn, waitMs = HOOK_WAIT_MS) {
+    if (linkedOwnFolder(env))
+        return { ok: false };
+    privateDir(trailPath(env));
+    privateDir(skillsDir(env));
+    return withLock(join(skillsDir(env), '.store'), fn, waitMs);
+}
+/**
+ * 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 function writeSkillFolder(dir, c, text, opts) {
+    for (const h of c.helpers)
+        if (!safeName(h.file))
+            throw new Error(`trail: a helper script needs a plain file name: ${JSON.stringify(h.file).slice(0, 60)}`);
+    try {
+        mkdirSync(dir, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            throw new Error(`trail: a skill folder called ${c.name} is already there`);
+        throw e;
+    }
+    try {
+        privateDir(dir);
+        writePrivate(join(dir, 'SKILL.md'), text);
+        if (c.helpers.length || opts.lessons)
+            privateDir(join(dir, 'scripts'));
+        for (const h of c.helpers)
+            writePrivate(join(dir, 'scripts', h.file), h.content, 0o700);
+        if (opts.lessons)
+            privateDir(join(dir, 'lessons'));
+    }
+    catch (e) {
+        // Half a skill (a full disk) would hold the name and never list: the folder made above goes.
+        rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+}
+export function newSkillId() {
+    return `s-${randomBytes(3).toString('hex')}`;
+}
+/**
+ * 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 function freeId(id, name, env) {
+    const held = (x) => {
+        const s = getSkillState(x, env);
+        return s !== null && s.name !== name;
+    };
+    let out = id;
+    for (let i = 0; i < 64 && held(out); i++)
+        out = newSkillId();
+    return out;
+}
+/** Throws unless the name can be a saved skill's: NAME_RE, no `--` or trailing dash, not one of Trail's own words. */
+export function checkSaveName(name) {
+    if (!goodName(name))
+        throw new Error(`trail: not a skill name: ${JSON.stringify(name).slice(0, 60)}`);
+}
+/** The skill folders other tools keep in the person's home (`~/.claude/skills`, `~/.agents/skills`, `$CLAUDE_CONFIG_DIR/skills`). */
+export function homeSkillDirs(env) {
+    const e = env ?? process.env;
+    const home = e.HOME || homedir();
+    const dirs = [join(home, '.claude', 'skills'), join(home, '.agents', 'skills')];
+    if (e.CLAUDE_CONFIG_DIR)
+        dirs.push(join(e.CLAUDE_CONFIG_DIR, 'skills'));
+    return dirs;
+}
+/** What keeping or restoring a skill would collide with, without a checkout: built in, a personal skill, a host's skill. */
+export function takenAtHome(name, env) {
+    if (BUILT_IN_NAMES.has(name))
+        return 'built-in';
+    if (lstatOrNull(join(skillsDir(env), name)))
+        return 'personal';
+    if (homeSkillDirs(env).some((d) => lstatOrNull(join(d, name))))
+        return 'host';
+    return null;
+}
+export function personalRef(id, name, applies, env) {
+    const dir = join(skillsDir(env), name);
+    return { id, name, scope: 'personal', applies, dir, file: join(dir, 'SKILL.md') };
+}
+/**
+ * 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 function startSkill(id, init) {
+    const at = init.now.toISOString();
+    const written = updateSkillState(id, () => ({
+        name: init.name, scope: 'personal', status: 'candidate', from: init.from, runId: init.runId, addedAt: at,
+        lastWorked: init.source ? localDate(init.source.at) : null, lastUsedAt: null, lastUsedRepo: null, uses: 0, checkedUses: 0,
+        hash: init.hash, source: init.source, lastFails: [], promoteOffers: {},
+    }), init.env);
+    if (!written)
+        throw new Error('trail: the skill state is busy (a hook is writing it). Try again in a few seconds.');
+    try {
+        appendLedger(id, {
+            at, event: 'saved', skill: id, v: init.version, from: init.from, scope: 'personal',
+            receipt: { consent: init.consent, stepsVerified: init.stepsVerified, stepsTotal: init.stepsTotal },
+        }, init.env);
+    }
+    catch { /* the state is the truth; the ledger is its record */ }
+}
+/** Compiled steps plus a check that is not itself a step (4.9 step 10). */
+export const stepsTotal = (c) => c.steps.length + (c.check && !c.checkIsStep ? 1 : 0);
+//# sourceMappingURL=store-fs.js.map

package/dist/skills/store-fs.js.map

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

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

@@ -0,0 +1,44 @@
+import type { JobClass } from '../trace/types.js';
+import type { CompiledSkill, SkillRef } from './types.js';
+import type { PersonCheck } from './person.js';
+export interface HeldItem {
+    name: string;
+    why: 'no-yes' | 'host';
+    host: string;
+    job: JobClass | null;
+    repoKey: string;
+    at: string;
+    shownAt: string | null;
+    dir: string;
+    /** The run it was compiled from (D65: a live save for the same run drops the held item instead of being refused). Null when held.json lacks it. */
+    runId?: string | null;
+    /** D93: sha256(sessionId).slice(0, 12) of the session that held it; null when held.json lacks it (written before). */
+    session?: string | null;
+}
+/** Every held item Trail wrote, whatever its age, oldest first. */
+export declare function allHeld(env?: NodeJS.ProcessEnv): HeldItem[];
+/** Writes held/<name>/SKILL.md (+ scripts/) and held.json, replacing a held item of the same name. */
+export declare function saveHeld(c: CompiledSkill, why: HeldItem['why'], meta: {
+    host: string;
+    job: JobClass | null;
+    repoKey: string;
+    session?: string | null;
+}, env?: NodeJS.ProcessEnv, now?: Date): HeldItem;
+/** Held items not shown yet, and shown ones younger than 24 h (still keepable). */
+export declare function listHeld(env?: NodeJS.ProcessEnv, now?: Date): HeldItem[];
+/** Hook bookkeeping (SessionStart): a busy store leaves it unshown, to be shown next time. */
+export declare function markHeldShown(name: string, env?: NodeJS.ProcessEnv, now?: Date): void;
+export declare function dropHeld(name: string, env?: NodeJS.ProcessEnv): void;
+/**
+ * The person keeps a held item: it moves into skills/<name> as a candidate they asked for (ledger `saved`, consent
+ * `asked`, no steps verified: the transcript was not read again). Refused for anyone but the person, an unknown or
+ * expired item, or a name a personal skill, a host's skill or Trail itself already uses.
+ */
+export declare function keepHeld(name: string, person: PersonCheck, env?: NodeJS.ProcessEnv, now?: Date): {
+    ok: true;
+    ref: SkillRef;
+} | {
+    ok: false;
+    reason: 'not-a-person' | 'unknown' | 'name-taken';
+};
+//# sourceMappingURL=store-held.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-held.d.ts","sourceRoot":"","sources":["../../src/skills/store-held.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ/C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAC3I,mJAAmJ;IACnJ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sHAAsH;IACtH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAkCD,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,QAAQ,EAAE,CAW3D;AAED,sGAAsG;AACtG,wBAAgB,QAAQ,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,QAAQ,CAclN;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,QAAQ,EAAE,CAEpF;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG,IAAI,CAOjG;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,IAAI,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,GAAE,IAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,YAAY,CAAA;CAAE,CAwC3M"}