@nanonets/graft 0.24.0 → 0.24.1

package/dist/skills/directive-words.js

@@ -0,0 +1,33 @@
+/**
+ * What every skills directive an agent reads opens with (D88, D101): who it
+ * is from, and the person's own words it answers.
+ *
+ * An agent follows hook text it can trust and refuses the rest as prompt
+ * injection. Trusted text says who it is from, ties itself to what the person
+ * asked, gives the reason, never tells the agent to skip asking the person,
+ * and never claims an approval it can't show. These are the shared pieces.
+ *
+ * The person's words are quoted in the hook output only, never written to
+ * disk (design 0 rule 6): one line, at most 120 characters, through
+ * `flatLine`, with its double quotes turned to single ones, so a quote can
+ * neither close early nor open a `[trail]` line of its own.
+ */
+import { flatLine } from '../notes/flatten.js';
+/** The sentence a directive opens with, after its `[trail]` marker. */
+export const FROM_TRAIL = 'From Trail, the tool this person installed to keep commands that worked as skills.';
+/** The longest quote of the person's words a directive carries. */
+export const QUOTE_MAX = 120;
+/** The person's words as one quotable line: '' when there are none. */
+export function quoteOf(typed) {
+    return flatLine(typed, QUOTE_MAX).replace(/"/g, "'");
+}
+/** `They typed: "save this as a skill".`, or '' when there are no words to quote. */
+export function typedWords(typed) {
+    const q = quoteOf(typed);
+    return q ? `They typed: "${q}".` : '';
+}
+/** `[trail] From Trail, ... They typed: "...". <rest>`: the opening, the quote when there is one, then the rest. */
+export function directive(typed, rest) {
+    return ['[trail]', FROM_TRAIL, typedWords(typed), rest].filter(Boolean).join(' ');
+}
+//# sourceMappingURL=directive-words.js.map

package/dist/skills/directive-words.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-words.js","sourceRoot":"","sources":["../../src/skills/directive-words.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG,oFAAoF,CAAC;AAE/G,mEAAmE;AACnE,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAE7B,uEAAuE;AACvE,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,IAAY;IACpD,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpF,CAAC"}

package/dist/skills/fidelity.d.ts

@@ -0,0 +1,42 @@
+import type { RunCall, SkillInjection } from '../trace/types.js';
+import type { FidelityCounts, ParsedSkill } from './types.js';
+/** after: the last skill step matched by a call before it (0: before step 1). id: the call's tool_use id. */
+export interface ExtraStep {
+    callIx: number;
+    after: number;
+    sha: string;
+    id: string;
+}
+/** callIx and id: the passing call that did step `step` another way. */
+export interface ChangedStep {
+    step: number;
+    callIx: number;
+    id: string;
+}
+export interface Fidelity {
+    ran: number[];
+    missing: number[];
+    extra: ExtraStep[];
+    changed: ChangedStep[];
+}
+/** Where the run was: the checkout's key (else the key of the calls that ran its steps), and the paths extraKey puts back. */
+export interface FidelityWhere {
+    repoKey?: string | null;
+    repoRoot?: string;
+    home?: string;
+}
+/**
+ * R10: the one key for an extra step, at the flush and in planFold. 8 hex of sha256 of the call's stored text with repo
+ * and home paths put back (`where`), the filled values put back as `{name}`, normalised: the same command in two
+ * releases of two versions gives one key.
+ */
+export declare function extraKey(call: RunCall, params: Record<string, string>, where?: {
+    repoRoot?: string;
+    home?: string;
+}): string;
+/** A command's program key and verb: `npm publish`, `git push` (the first word after the program that isn't a flag). */
+export declare function programVerb(cmd: string): string | null;
+/** 4.1. `inj` gives the filled params (and `at`, as credit reads it); `calls` are the use's run sheet calls. Never throws. */
+export declare function fidelityOf(skill: Pick<ParsedSkill, 'steps' | 'check' | 'params'>, inj: Pick<SkillInjection, 'params' | 'steps'> & Partial<Pick<SkillInjection, 'at' | 'check' | 'handed'>>, calls: RunCall[], where?: FidelityWhere): Fidelity;
+export declare function fidelityCounts(f: Fidelity): FidelityCounts;
+//# sourceMappingURL=fidelity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity.d.ts","sourceRoot":"","sources":["../../src/skills/fidelity.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAO9D,6GAA6G;AAC7G,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACrF,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACzE,MAAM,WAAW,QAAQ;IAAG,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE;AAE1G,8HAA8H;AAC9H,MAAM,WAAW,aAAa;IAAG,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;AAiB5F;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG5H;AAED,wHAAwH;AACxH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAatD;AAID,8HAA8H;AAC9H,wBAAgB,UAAU,CACxB,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC,EACtD,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC,CAAC,EACxG,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,GAAE,aAAkB,GACxB,QAAQ,CAiEV;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,cAAc,CAE1D"}

package/dist/skills/fidelity.js

@@ -0,0 +1,138 @@
+/**
+ * Next-run fidelity (phase 2 design 4.1, spec 24, P2, P3): what a run a
+ * skill's block drove did against the skill's steps. Which steps ran (the
+ * same set credit gives), which failed and were then done another way that
+ * passed, which passing steps of the job the skill lacks, and which steps
+ * neither ran nor failed.
+ *
+ * Computed at each credit flush from the calls and filled params credit uses,
+ * so a use and its fidelity agree. Counts, step numbers and 8-hex shas of a
+ * compiled command only reach the use line: never a command or a prompt.
+ * Fidelity never changes a use's outcome or a skill's status (P3).
+ *
+ * Pure: no disk, no clock.
+ */
+import { createHash } from 'node:crypto';
+import { callText } from '../trace/checks.js';
+import { envPrefix, normalizeCommand, programOf, relativizePaths } from '../trace/shell.js';
+import { ranAs } from './ledger.js';
+import { fillParams } from './params.js';
+import { doesLess, onlyRehearsed } from './ran-less.js';
+/** Credit's slack before a block's `at` (ledger.ts SLACK_MS): the same calls count for both. */
+const SLACK_MS = 5000;
+const escapeRe = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Filled values of 2+ characters back to `{name}`, longest first, never inside a longer word or number. */
+function putBack(text, params) {
+    const pairs = Object.entries(params ?? {})
+        .filter(([, v]) => typeof v === 'string' && v.length >= 2 && !v.startsWith('$('))
+        .sort((a, b) => b[1].length - a[1].length);
+    let out = text;
+    for (const [name, v] of pairs)
+        out = out.replace(new RegExp(`(?<![0-9A-Za-z_.])v?${escapeRe(v)}(?![0-9A-Za-z_])`, 'g'), (m) => (m.startsWith('v') && !v.startsWith('v') ? `v{${name}}` : `{${name}}`));
+    return out;
+}
+/**
+ * R10: the one key for an extra step, at the flush and in planFold. 8 hex of sha256 of the call's stored text with repo
+ * and home paths put back (`where`), the filled values put back as `{name}`, normalised: the same command in two
+ * releases of two versions gives one key.
+ */
+export function extraKey(call, params, where) {
+    const rel = relativizePaths(callText(call), where?.repoRoot ?? '', where?.home ?? '');
+    return createHash('sha256').update(normalizeCommand(putBack(rel, params))).digest('hex').slice(0, 8);
+}
+/** A command's program key and verb: `npm publish`, `git push` (the first word after the program that isn't a flag). */
+export function programVerb(cmd) {
+    const prog = programOf(cmd);
+    if (!prog)
+        return null;
+    const words = envPrefix(normalizeCommand(cmd).replace(/^\(+/, '')).rest.split(/\s+/);
+    const at = words.findIndex((w) => w === prog || w.endsWith(`/${prog}`));
+    if (at < 0)
+        return prog.toLowerCase();
+    for (let i = at + 1; i < words.length; i++) {
+        const w = words[i];
+        if (prog === 'git' && /^-[Cc]$/.test(w)) {
+            i++;
+            continue;
+        }
+        if (w.startsWith('-'))
+            continue;
+        return `${prog.toLowerCase()} ${w}`;
+    }
+    return prog.toLowerCase();
+}
+const steps1 = (n) => Array.from({ length: n }, (_, i) => i + 1);
+/** 4.1. `inj` gives the filled params (and `at`, as credit reads it); `calls` are the use's run sheet calls. Never throws. */
+export function fidelityOf(skill, inj, calls, where = {}) {
+    const count = Array.isArray(skill?.steps) ? skill.steps.length : 0;
+    try {
+        const params = inj.params ?? {};
+        const steps = Array.isArray(inj.steps) && inj.steps.length === count ? inj.steps : skill.steps.map((s) => fillParams(s.cmd, params));
+        const check = inj.check ?? (skill.check ? fillParams(skill.check, params) : null);
+        const from = inj.at ? Date.parse(inj.at) : NaN;
+        const list = calls
+            .map((c, ix) => ({ c, ix }))
+            .filter(({ c }) => typeof c.tool !== 'string' && (Number.isNaN(from) || Date.parse(c.at) >= from - SLACK_MS));
+        // Credit's own reading: each call goes to the first step it matches; a step's last outcome wins.
+        const text = list.map(({ c }) => callText(c));
+        const match = text.map((t) => (t ? steps.findIndex((s) => ranAs(s, t, params)) : -1));
+        const last = new Map();
+        const firstFail = new Map();
+        // D137: as credit reads it, a gated step handed to the person ran (theirs to run), and its denied call is no failure.
+        const handed = new Set((inj.handed ?? []).map((h) => h.n).filter((n) => Number.isInteger(n) && n >= 1 && n <= count));
+        for (const n of handed)
+            last.set(n, true);
+        match.forEach((i, p) => {
+            if (i < 0)
+                return;
+            const ok = !list[p].c.failed || handed.has(i + 1);
+            last.set(i + 1, ok);
+            if (!ok && !firstFail.has(i + 1))
+                firstFail.set(i + 1, p);
+        });
+        const ran = [...last].filter(([, ok]) => ok).map(([n]) => n).sort((a, b) => a - b);
+        const key = where.repoKey ?? list.find((_, p) => match[p] >= 0)?.c.key ?? null;
+        const inside = (c) => c.cwd !== null && (key === null || c.key === key);
+        const isCheck = (t) => !!check && ranAs(check, t, params);
+        // Passed: not failed, and a result came (its line, or a PostToolUse mark). A call whose result never came
+        // (killed, still running, a host that never wrote it) never passed, whatever `failed` starts as (review).
+        const passed = (c) => !c.failed && (c.src?.result != null || c.fromMark === true);
+        const loose = (p) => {
+            const c = list[p].c;
+            return passed(c) && c.kind === 'step' && match[p] < 0 && !!text[p] && inside(c) && !isCheck(text[p]) && !onlyRehearsed(text[p]);
+        };
+        // A step that failed, then a passing call of the same program and verb that is no step: done another way.
+        const used = new Set();
+        const changed = [];
+        for (const [n, f] of [...firstFail].sort((a, b) => a[0] - b[0])) {
+            const verb = programVerb(steps[n - 1]);
+            if (!verb)
+                continue;
+            for (let p = f + 1; p < list.length; p++) {
+                if (used.has(p) || !loose(p) || programVerb(text[p]) !== verb || doesLess(steps[n - 1], text[p]))
+                    continue;
+                used.add(p);
+                changed.push({ step: n, callIx: list[p].ix, id: list[p].c.id });
+                break;
+            }
+        }
+        const extra = [];
+        let after = 0;
+        list.forEach(({ c, ix }, p) => {
+            if (!used.has(p) && loose(p))
+                extra.push({ callIx: ix, after, sha: extraKey(c, params, where), id: c.id });
+            if (match[p] >= 0)
+                after = Math.max(after, match[p] + 1);
+        });
+        const isTheCheck = (n) => !!check && normalizeCommand(steps[n - 1]) === normalizeCommand(check);
+        const missing = steps1(count).filter((n) => !last.has(n) && !isTheCheck(n));
+        return { ran, missing, extra, changed };
+    }
+    catch {
+        return { ran: [], missing: steps1(count), extra: [], changed: [] };
+    }
+}
+export function fidelityCounts(f) {
+    return { ran: f.ran.length, missing: f.missing.length, extra: f.extra.length, changed: f.changed.length };
+}
+//# sourceMappingURL=fidelity.js.map

package/dist/skills/fidelity.js.map

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

package/dist/skills/forget-notice.d.ts

@@ -0,0 +1,44 @@
+/**
+ * D117 (2): `trail forget` stays open to agents (1a: turning things off is open
+ * to anyone; the harm is bounded, it only removes). So the person still hears
+ * of it: when an agent runs it, the CLI notes what was dropped and how to bring
+ * it back in `~/.trail/state/forgot.jsonl`, and the next Stop, in any session,
+ * tells the person once, in one line. A Stop that already blocks (an offer), or
+ * a turn a block continued, leaves it for the next one.
+ *
+ * The person's own forget at their terminal (or from their own script) notes
+ * nothing: they know what they did. Never "memory", no em dashes.
+ */
+import type { Host } from '../trace/host.js';
+import type { HookOut } from './types.js';
+export type DroppedKind = 'skill' | 'lesson' | 'learning' | 'guardrail';
+export interface Dropped {
+    at: string;
+    what: DroppedKind;
+    name: string;
+    back: string;
+}
+export declare const forgotPath: (env: NodeJS.ProcessEnv) => string;
+/** The CLI half: an agent's forget that worked. Never throws (the forget itself already happened). */
+export declare function noteAgentForget(d: Omit<Dropped, 'at'>, env: NodeJS.ProcessEnv, now: Date): void;
+/**
+ * The Stop half: the notes, taken once. The file is renamed first, so two Stops at the same instant can't both say
+ * it; a link in its place is removed, never followed.
+ */
+export declare function takeForgets(env: NodeJS.ProcessEnv, now: Date): Dropped[];
+/** One line for the person: `trail: an agent ran trail forget: the skill x (bring it back: ...); ...`. */
+export declare function forgetLine(ds: Dropped[]): string;
+/**
+ * The Stop's answer with the notes added: a notice where the host shows one (joined to the skills part's), else a
+ * block whose reason asks the agent to tell the person once. `out` is the skills part's answer; a block there, or a
+ * continued turn, leaves the notes for the next Stop.
+ */
+export declare function withForgetNotice(out: HookOut, opts: {
+    env: NodeJS.ProcessEnv;
+    now: Date;
+    active: boolean;
+    stopNotice: boolean;
+}): HookOut;
+/** The Stop handler's call (skills on or off): Trail's clock and the host's facts for this env. */
+export declare function forgetNoticeAtStop(out: HookOut, env: NodeJS.ProcessEnv, host?: Host): HookOut;
+//# sourceMappingURL=forget-notice.d.ts.map

package/dist/skills/forget-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forget-notice.d.ts","sourceRoot":"","sources":["../../src/skills/forget-notice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAI1C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AACxE,MAAM,WAAW,OAAO;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAStF,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,CAAC,UAAU,KAAG,MAAiD,CAAC;AAEtG,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAS/F;AA8BD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,EAAE,CA4BxE;AAID,0GAA0G;AAC1G,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,MAAM,CAIhD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,GAAG,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CASzI;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAE7F"}

package/dist/skills/forget-notice.js

@@ -0,0 +1,131 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, rmSync } from 'node:fs';
+import { flatLine } from '../notes/flatten.js';
+import { appendPrivateLine, trailPath } from '../util/private-fs.js';
+import { FROM_TRAIL } from './directive-words.js';
+import { hostFacts } from './host-facts.js';
+import { trailNow } from './settings.js';
+const KINDS = new Set(['skill', 'lesson', 'learning', 'guardrail']);
+/** A note older than a day is dropped unsaid: the person has moved on, and a stale line would only confuse. */
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const MAX_SHOWN = 3;
+/** The file is never read past this, and no note is added once it is this big. */
+const MAX_BYTES = 16 * 1024;
+export const forgotPath = (env) => trailPath(env, 'state', 'forgot.jsonl');
+/** The CLI half: an agent's forget that worked. Never throws (the forget itself already happened). */
+export function noteAgentForget(d, env, now) {
+    try {
+        const path = forgotPath(env);
+        try {
+            if (lstatSync(path).size >= MAX_BYTES)
+                return;
+        }
+        catch { /* not there yet */ }
+        const entry = { at: now.toISOString(), what: d.what, name: flatLine(d.name, 60), back: flatLine(d.back, 200) };
+        appendPrivateLine(path, JSON.stringify(entry));
+    }
+    catch { /* the line is a courtesy; the forget stands */ }
+}
+function valid(v, now) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const d = v;
+    if (typeof d.what !== 'string' || !KINDS.has(d.what) || typeof d.name !== 'string' || !d.name || typeof d.back !== 'string' || !d.back)
+        return false;
+    const t = typeof d.at === 'string' ? Date.parse(d.at) : Number.NaN;
+    return Number.isFinite(t) && now.getTime() - t <= MAX_AGE_MS && t - now.getTime() <= 60_000;
+}
+/** Reads at most MAX_BYTES of a regular file, never through a link or into a FIFO. */
+function readSmall(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    }
+    catch {
+        return null;
+    }
+    try {
+        if (!fstatSync(fd).isFile())
+            return null;
+        const buf = Buffer.alloc(MAX_BYTES);
+        const n = readSync(fd, buf, 0, MAX_BYTES, 0);
+        return buf.subarray(0, n).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * The Stop half: the notes, taken once. The file is renamed first, so two Stops at the same instant can't both say
+ * it; a link in its place is removed, never followed.
+ */
+export function takeForgets(env, now) {
+    const path = forgotPath(env);
+    try {
+        if (lstatSync(path).isSymbolicLink()) {
+            rmSync(path, { force: true });
+            return [];
+        }
+    }
+    catch {
+        return [];
+    }
+    const claimed = `${path}.${process.pid}.${Math.random().toString(16).slice(2, 8)}.taken`;
+    try {
+        renameSync(path, claimed);
+    }
+    catch {
+        return [];
+    }
+    const text = readSmall(claimed);
+    try {
+        rmSync(claimed, { force: true });
+    }
+    catch { /* left for housekeeping */ }
+    if (text === null)
+        return [];
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const v = JSON.parse(line);
+            if (valid(v, now))
+                out.push(v);
+        }
+        catch { /* a broken line */ }
+    }
+    return out;
+}
+const WHAT = { skill: 'the skill', lesson: 'the lesson', learning: 'the learning', guardrail: 'the guardrail' };
+/** One line for the person: `trail: an agent ran trail forget: the skill x (bring it back: ...); ...`. */
+export function forgetLine(ds) {
+    const shown = ds.slice(-MAX_SHOWN).map((d) => `${WHAT[d.what] ?? 'the item'} ${flatLine(d.name, 60)} (bring it back: ${flatLine(d.back, 200)})`);
+    const more = ds.length > MAX_SHOWN ? ` and ${ds.length - MAX_SHOWN} more` : '';
+    return flatLine(`trail: an agent ran trail forget: ${shown.join('; ')}${more}`, 900);
+}
+/**
+ * The Stop's answer with the notes added: a notice where the host shows one (joined to the skills part's), else a
+ * block whose reason asks the agent to tell the person once. `out` is the skills part's answer; a block there, or a
+ * continued turn, leaves the notes for the next Stop.
+ */
+export function withForgetNotice(out, opts) {
+    if (out.block || opts.active)
+        return out;
+    const ds = takeForgets(opts.env, opts.now);
+    if (!ds.length)
+        return out;
+    const line = forgetLine(ds);
+    if (opts.stopNotice)
+        return { ...out, notice: out.notice ? `${out.notice}\n${line}` : line };
+    const block = `[trail] ${FROM_TRAIL} An agent ran trail forget, which only removes, so Trail tells the person what went and how to bring it back. `
+        + `So they know, tell them once: "${line.replace(/^trail: /, '').replace(/"/g, "'")}"`;
+    return { block };
+}
+/** The Stop handler's call (skills on or off): Trail's clock and the host's facts for this env. */
+export function forgetNoticeAtStop(out, env, host) {
+    return withForgetNotice(out, { env, now: trailNow(env), active: false, stopNotice: hostFacts(env, host).stopNotice });
+}
+//# sourceMappingURL=forget-notice.js.map

package/dist/skills/forget-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forget-notice.js","sourceRoot":"","sources":["../../src/skills/forget-notice.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC7G,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAKzC,MAAM,KAAK,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AACzF,+GAA+G;AAC/G,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACvC,MAAM,SAAS,GAAG,CAAC,CAAC;AACpB,kFAAkF;AAClF,MAAM,SAAS,GAAG,EAAE,GAAG,IAAI,CAAC;AAE5B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAsB,EAAU,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;AAEtG,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,CAAsB,EAAE,GAAsB,EAAE,GAAS;IACvF,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC;YACH,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,SAAS;gBAAE,OAAO;QAChD,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAY,EAAE,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACxH,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC,CAAC,+CAA+C,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,KAAK,CAAC,CAAU,EAAE,GAAS;IAClC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,CAAC,GAAG,CAA4B,CAAC;IACvC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACrJ,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACnE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,UAAU,IAAI,CAAC,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,MAAM,CAAC;AAC9F,CAAC;AAED,sFAAsF;AACtF,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,GAAG,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;IACtG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;YAAE,OAAO,IAAI,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC7C,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAsB,EAAE,GAAS;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC;QACH,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9B,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;IACzF,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC;QAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,2BAA2B,CAAC,CAAC;IAC/E,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,IAAI,GAAgC,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;AAE7I,0GAA0G;AAC1G,MAAM,UAAU,UAAU,CAAC,EAAa;IACtC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,UAAU,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACjJ,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,OAAO,QAAQ,CAAC,qCAAqC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY,EAAE,IAAiF;IAC9H,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,GAAG,CAAC;IACzC,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,CAAC,MAAM;QAAE,OAAO,GAAG,CAAC;IAC3B,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7F,MAAM,KAAK,GAAG,WAAW,UAAU,gHAAgH;UAC/I,kCAAkC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC;IACzF,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,kBAAkB,CAAC,GAAY,EAAE,GAAsB,EAAE,IAAW;IAClF,OAAO,gBAAgB,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;AACxH,CAAC"}

package/dist/skills/found-skill.d.ts

@@ -0,0 +1,35 @@
+export interface FoundSkill {
+    name: string;
+    title: string;
+    /** `team`: written into the repo. `you`: kept on this machine. */
+    for: "team" | "you";
+    /** What to do, in order: 2 to 8 commands or actions. */
+    steps: string[];
+    /** Sessions the cited quotes were found in, newest first. */
+    sessions: string[];
+    quotes: string[];
+}
+/** A skill's SKILL.md: where it is, and whether this run wrote it (`false`: one of that name was already there). */
+export interface SavedSkill {
+    skill: FoundSkill;
+    path: string;
+    created: boolean;
+}
+/** SKILL.md for a found skill: the frontmatter every skill has, then its steps as a numbered list. */
+export declare function renderFoundSkill(s: FoundSkill): string;
+/**
+ * The lines init prints for found skills it didn't write because one of that
+ * name already exists (in the repo or on this machine), one per skill.
+ */
+export declare function skippedSkillLines(repo: string, found: FoundSkill[], written: SavedSkill[]): string[];
+/**
+ * Write the skill, and return the path of its SKILL.md and whether this call
+ * wrote it. A skill of that name the repo or this machine already has is left
+ * as it is: its path comes back with `created: false`, and it isn't ours to
+ * report or send anywhere.
+ */
+export declare function saveFoundSkill(repo: string, s: FoundSkill): {
+    path: string;
+    created: boolean;
+};
+//# sourceMappingURL=found-skill.d.ts.map

package/dist/skills/found-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"found-skill.d.ts","sourceRoot":"","sources":["../../src/skills/found-skill.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IACpB,wDAAwD;IACxD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,oHAAoH;AACpH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAItD;AAYD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,CAQpG;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAY9F"}

package/dist/skills/found-skill.js

@@ -0,0 +1,66 @@
+/**
+ * A skill found in past sessions: a procedure the person walked Claude through
+ * in two or more of them, written to a SKILL.md at `trail init` so the next
+ * session can follow it without being walked through it again.
+ *
+ * The team's go in the repo's `.claude/skills/`, where Claude Code loads them
+ * for everyone who pulls; the person's own go in this repo's skills under
+ * ~/.trail. A skill of that name that already exists is never touched.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureRepoHome } from "../notes/home.js";
+import { skillDirs, skillName } from "./skills.js";
+/** SKILL.md for a found skill: the frontmatter every skill has, then its steps as a numbered list. */
+export function renderFoundSkill(s) {
+    const name = skillName(s.name);
+    const steps = s.steps.map((step, i) => `${i + 1}. ${step}`).join("\n");
+    return `---\nname: ${name}\ndescription: ${JSON.stringify(s.title)}\nversion: 1\n---\n\n# ${s.title}\n\n${steps}\n`;
+}
+/** The SKILL.md a skill of this name already has, in the repo or on this machine; null when there's none. */
+function existingSkillFile(repo, name) {
+    const dirs = skillDirs(repo);
+    for (const d of [dirs.repo, dirs.home]) {
+        const there = join(d, name, "SKILL.md");
+        if (existsSync(there))
+            return there;
+    }
+    return null;
+}
+/**
+ * The lines init prints for found skills it didn't write because one of that
+ * name already exists (in the repo or on this machine), one per skill.
+ */
+export function skippedSkillLines(repo, found, written) {
+    const out = [];
+    for (const skill of found) {
+        const name = skillName(skill.name);
+        if (!name || written.some((w) => w.skill === skill) || !existingSkillFile(repo, name))
+            continue;
+        out.push(`· Skipped skill ${name}: one already exists.`);
+    }
+    return out;
+}
+/**
+ * Write the skill, and return the path of its SKILL.md and whether this call
+ * wrote it. A skill of that name the repo or this machine already has is left
+ * as it is: its path comes back with `created: false`, and it isn't ours to
+ * report or send anywhere.
+ */
+export function saveFoundSkill(repo, s) {
+    const name = skillName(s.name);
+    if (!name)
+        throw new Error("a skill needs a name");
+    const dirs = skillDirs(repo);
+    const there = existingSkillFile(repo, name);
+    if (there)
+        return { path: there, created: false };
+    if (s.for === "you")
+        ensureRepoHome(repo);
+    const dir = join(s.for === "you" ? dirs.home : dirs.repo, name);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "SKILL.md");
+    writeFileSync(file, renderFoundSkill(s));
+    return { path: file, created: true };
+}
+//# sourceMappingURL=found-skill.js.map

package/dist/skills/found-skill.js.map

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

package/dist/skills/front-version.d.ts

@@ -0,0 +1,12 @@
+/** The version `data` (a SKILL.md's front matter) says: `metadata.version`, else the old top-level `version`, else 1. */
+export declare function versionOf(data: Record<string, unknown>): number;
+/**
+ * The front matter `lines` (without the `---` fences) with `metadata.version`
+ * set to `version`, and any old top-level `version` gone. With `mark`, a
+ * metadata without a `trail` key gets `trail: "<mark>"`; one it already has is
+ * kept. A block `metadata:` gets the lines replaced or added at its own
+ * indent; a flow one (`metadata: { … }`) is written out as a block, its other
+ * values kept as strings; none at all gets one.
+ */
+export declare function withMetadataVersion(lines: string[], version: number, mark?: string): string[];
+//# sourceMappingURL=front-version.d.ts.map

package/dist/skills/front-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"front-version.d.ts","sourceRoot":"","sources":["../../src/skills/front-version.ts"],"names":[],"mappings":"AAWA,yHAAyH;AACzH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAQ/D;AAeD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAuC7F"}