@sigrun/sigrun 0.6.0 → 0.7.0

package/dist/curation/migrate.js

@@ -0,0 +1,96 @@
+/**
+ * Curation history migration (tabs+skills plan, Task 9): a per-user
+ * one-shot import of the pre-git curation store into the user's git
+ * history repo.
+ *
+ * Runs at boot for every directory user AND lazily the first time
+ * `curationOf` constructs a user's stores (users created after boot).
+ * The marker `curation/history/MIGRATED` is written LAST: without it,
+ * any partial `user.git` is discarded and the import is redone. The
+ * legacy artifacts (`feed.jsonl`, `versions/`) are never touched — they
+ * stay read-only on disk and outside the repo's pathspec.
+ *
+ * The discard + import run inside `GitHistory.freshImport` (the
+ * per-repo lock): a store write concurrent with the migration either
+ * lands before the discard (its commit is discarded and its content is
+ * re-imported from disk — nothing lost) or after the import (its own
+ * commit on top). The unlocked rm of an earlier revision could delete
+ * a repo a concurrent write had just committed (review I3).
+ *
+ * A "nothing" result ALSO writes the marker (whole-branch review C1):
+ * without it, an empty user's first write commits fine, but the NEXT
+ * boot's sweep sees a non-empty pathspec with no marker and freshImport
+ * would discard that entire first-session history. The marker's "nothing
+ * was imported" form is the same file; marker-last ordering is trivially
+ * preserved (nothing precedes it).
+ *
+ * The residual failure window: a crash AFTER freshImport's commit but
+ * BEFORE the marker write leaves an unmarked repo holding real import
+ * commits — the next boot discards it and re-imports from disk (the
+ * content is safe), but any feed entry / undo anchor / review link that
+ * already recorded the discarded commits' shas dangles (their trailers
+ * are lost with the discarded commits). The window is one writeFile
+ * wide; closing it would need the marker inside the commit itself.
+ */
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { historyDir, userRepoSpec } from "./paths.js";
+/**
+ * Import the user's current curation store into the history repo.
+ * "already" when the marker exists; "nothing" when the user has no
+ * tracked content at all (the marker IS written — review C1: an
+ * unmarked empty user loses their first write's history on the next
+ * boot's sweep); "migrated" otherwise.
+ *
+ * A `user.git` without the marker on a repo this call did not just
+ * build is a partial migration: it is discarded and the import runs
+ * fresh.
+ */
+export async function migrateUserCuration(userArea, history) {
+    const marker = join(historyDir(userArea), "MIGRATED");
+    if (await present(marker))
+        return "already";
+    if (!(await pathspecContent(userArea))) {
+        // Nothing to import — but the marker must exist anyway: an
+        // unmarked user's first write commits into a repo the next boot
+        // would treat as a partial migration and discard (review C1).
+        await mkdir(historyDir(userArea), { recursive: true });
+        await writeFile(marker, `${new Date().toISOString()}\n`);
+        return "nothing";
+    }
+    // The discard + import are ONE locked operation (GitHistory.
+    // freshImport): a concurrent store write either lands before the
+    // discard (its content is re-imported from disk — nothing lost) or
+    // after the import (its own commit on top). The work tree must exist
+    // before the git dir can init inside it.
+    await mkdir(historyDir(userArea), { recursive: true });
+    const sha = await history.freshImport({
+        actor: { kind: "outside" },
+        summary: "Imported from the curation store",
+    });
+    if (sha === undefined) {
+        // Git failed (fail-soft): no commit, no marker — the next boot
+        // retries the whole import.
+        return "nothing";
+    }
+    await mkdir(historyDir(userArea), { recursive: true });
+    await writeFile(marker, `${new Date().toISOString()}\n`);
+    return "migrated";
+}
+/** Whether any pathspec entry exists in the work tree. */
+async function pathspecContent(userArea) {
+    for (const entry of userRepoSpec(userArea).pathspec) {
+        if (await present(join(userArea, entry)))
+            return true;
+    }
+    return false;
+}
+async function present(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/curation/overlays.js

@@ -17,17 +17,25 @@
  * {@link OverlayStore.markOrphans} (present again clears the mark), and
  * removable.
  *
- * Every overlay change is recorded in the SAME per-user change feed the
- * {@link SkillStore} owns (A4): an entry with action `"overlay"` (the
- * union member exists for exactly this), appended through the store's
- * feed seam so retention and the per-user lock hold. The feed is the
- * audit record and the P8 view's data; `OverlayStore` owns the files.
+ * Every overlay change commits to the user's curation history repo
+ * (tabs+skills Task 9): one commit per put/remove with the Sigrun-*
+ * trailers, so overlay changes appear in the same feed as learned-skill
+ * changes. `OverlayStore` owns the files.
  */
 import { randomUUID, createHash } from "node:crypto";
 import { lstat, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { curationDir, learnedSkillsDir } from "./paths.js";
 import { validSkillName } from "./names.js";
+/** The Sigrun actor shape for a history commit. */
+function historyActor(actor, user) {
+    switch (actor) {
+        case "user": return { kind: "user", user };
+        case "curator": return { kind: "curator" };
+        case "agent": return { kind: "agent" };
+        case "outside": return { kind: "outside" };
+    }
+}
 /**
  * The heading the served overlay follows: upstream body, then this
  * heading, then the overlay text (one blank line each side of the
@@ -123,23 +131,52 @@ export class OverlayStore {
      */
     async put(key, text, upstreamHash, meta) {
         this.requireUser();
+        await this.options.ready?.();
         checkKey(key);
         if (await exists(join(learnedSkillsDir(this.options.userArea), key.skill))) {
             throw new Error(`an overlay never applies to a learned skill: ${key.skill}`);
         }
+        // The repo's work tree must exist before the git dir can init.
+        await mkdir(curationDir(this.options.userArea), { recursive: true });
         const overlay = { key, text, upstreamHash };
-        await writeFileAtomic(this.fileOf(key), `${JSON.stringify(overlay, null, 2)}\n`);
-        return this.appendFeed(key, meta, meta.reason ?? "overlay written");
+        const summary = `overlay ${key.root}:${key.skill}`;
+        const sha = await this.options.history.write({
+            actor: historyActor(meta.actor, this.options.user),
+            summary,
+            action: "overlay",
+            skill: key.skill,
+            ...(meta.reason === undefined ? {} : { reason: meta.reason }),
+            ...(meta.reviewId === undefined ? {} : { reviewId: meta.reviewId }),
+            ...(meta.conversationId === undefined ? {} : { conversationId: meta.conversationId }),
+        }, async () => {
+            this.requireUser();
+            await writeFileAtomic(this.fileOf(key), `${JSON.stringify(overlay, null, 2)}\n`);
+        }, { kind: "outside" });
+        return this.entry(key, sha, meta, summary);
     }
     /** Remove the overlay for a key; returns the feed entry. Throws when none is stored. */
     async remove(key, meta) {
         this.requireUser();
+        await this.options.ready?.();
         checkKey(key);
         const file = this.fileOf(key);
         if (!(await exists(file)))
             throw new Error(`unknown overlay: ${keyString(key)}`);
-        await rm(file);
-        return this.appendFeed(key, meta, meta.reason ?? "overlay removed");
+        await mkdir(curationDir(this.options.userArea), { recursive: true });
+        const summary = `overlay ${key.root}:${key.skill}`;
+        const sha = await this.options.history.write({
+            actor: historyActor(meta.actor, this.options.user),
+            summary,
+            action: "overlay",
+            skill: key.skill,
+            ...(meta.reason === undefined ? {} : { reason: meta.reason }),
+            ...(meta.reviewId === undefined ? {} : { reviewId: meta.reviewId }),
+            ...(meta.conversationId === undefined ? {} : { conversationId: meta.conversationId }),
+        }, async () => {
+            this.requireUser();
+            await rm(file);
+        }, { kind: "outside" });
+        return this.entry(key, sha, meta, summary);
     }
     /** Every stored overlay (present upstreams and orphans alike), sorted by root then name. */
     async list() {
@@ -215,20 +252,19 @@ export class OverlayStore {
             ...(typeof value.orphanedSince === "string" ? { orphanedSince: value.orphanedSince } : {}),
         };
     }
-    /** Record one overlay change in the skill store's feed (the `"overlay"` action). */
-    async appendFeed(key, meta, summary) {
-        const entry = {
-            id: randomUUID(),
+    /** Record one overlay change in the user repo as an `"overlay"` entry. */
+    entry(key, sha, meta, summary) {
+        return {
+            id: sha ?? `(no-commit-${randomUUID()})`,
             at: new Date().toISOString(),
             actor: meta.actor,
             action: "overlay",
             skill: key.skill,
-            reason: summary,
+            reason: meta.reason ?? summary,
             ...(meta.reviewId === undefined ? {} : { reviewId: meta.reviewId }),
             ...(meta.conversationId === undefined ? {} : { conversationId: meta.conversationId }),
+            ...(sha === undefined ? {} : { after: sha }),
         };
-        await this.options.feed.appendFeedEntry(entry);
-        return entry;
     }
 }
 /**

package/dist/curation/paths.js

@@ -15,3 +15,25 @@ export function learnedSkillsDir(userArea) {
 export function curationDir(userArea) {
     return join(userArea, "curation");
 }
+/**
+ * The owner's curation history root: `<userArea>/curation/history`
+ * (tabs+skills Task 9). Holds `user.git` (the per-user curation repo),
+ * later `workspace.git` (Task 10), and the `MIGRATED` marker. A plain
+ * directory, never a git work tree.
+ */
+export function historyDir(userArea) {
+    return join(userArea, "curation", "history");
+}
+/**
+ * The ONE per-user curation repo (tabs+skills Task 9): skills,
+ * archive, overlays and state in one history, with `userArea` as the
+ * work tree. `feed.jsonl` and `versions/` are deliberately OUTSIDE the
+ * pathspec — read-only legacy after migration.
+ */
+export function userRepoSpec(userArea) {
+    return {
+        gitDir: join(historyDir(userArea), "user.git"),
+        workTree: userArea,
+        pathspec: ["skills", "curation/archive", "curation/overlays", "curation/state.json"],
+    };
+}

package/dist/curation/runs.js

@@ -433,28 +433,45 @@ export async function driveRun(deps, prepare, opts, parent) {
     }
 }
 /** Collect the run's `details.curation` changes, in entry order. */
+/** Scan bound for collectChanges' cursor walk (a broken cursor loops, a count does not). */
+const COLLECT_SCAN_LIMIT = 10_000;
 async function collectChanges(conversation) {
-    const page = await conversation.entries({ order: "ascending" }, 500, undefined, BACKGROUND_CONTEXT);
     const changes = [];
-    for (const entry of page.items) {
-        if (entry.kind !== ToolResultEntry.kind)
-            continue;
-        for (const message of entry.model ?? []) {
-            if (message.role !== "toolResult")
-                continue;
-            const details = message.details;
-            const curation = details?.curation;
-            if (curation === undefined ||
-                typeof curation.changeId !== "string" ||
-                typeof curation.summary !== "string") {
+    // Cursor-complete walk (the A9 ruling): a run with more tool results
+    // than one page loses nothing — pages until exhaustion, bounded so
+    // a cursor bug cannot loop forever.
+    let cursor;
+    let scanned = 0;
+    for (;;) {
+        const page = await conversation.entries({ order: "ascending" }, 500, cursor, BACKGROUND_CONTEXT);
+        for (const entry of page.items) {
+            scanned += 1;
+            if (entry.kind !== ToolResultEntry.kind)
                 continue;
+            for (const message of entry.model ?? []) {
+                if (message.role !== "toolResult")
+                    continue;
+                const details = message.details;
+                const curation = details?.curation;
+                if (curation === undefined ||
+                    typeof curation.changeId !== "string" ||
+                    typeof curation.summary !== "string") {
+                    continue;
+                }
+                changes.push({
+                    changeId: curation.changeId,
+                    summary: curation.summary,
+                    target: targetOfTool(message.toolName),
+                });
             }
-            changes.push({
-                changeId: curation.changeId,
-                summary: curation.summary,
-                target: targetOfTool(message.toolName),
-            });
         }
+        if (page.next === undefined || page.items.length === 0)
+            break;
+        if (scanned >= COLLECT_SCAN_LIMIT) {
+            console.warn(`curation: collectChanges hit the ${COLLECT_SCAN_LIMIT}-entry scan guard — the run's change list is a PREFIX (later changes are unreported)`);
+            break;
+        }
+        cursor = page.next;
     }
     return changes;
 }

package/dist/curation/skill-tool.js

@@ -29,6 +29,7 @@ import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-durable";
 import { OVERLAY_HEADING, withOverlay, } from "./overlays.js";
 import { curationRun, markViewed } from "./run-doc.js";
+import { SKILL_MANAGE_READ_ACTIONS } from "./targets.js";
 import { SessionMetaDoc } from "../server/session-meta.js";
 /** The tool's parameter union (the brief's exact shape). */
 const skillManageParameters = Type.Object({
@@ -111,7 +112,10 @@ async function viewUpstreamOnly(deps, stores, args, env, ctx) {
     };
     const upstream = await deps.upstreamOf(key, env, ctx).catch(() => undefined);
     if (stored === undefined && upstream === undefined) {
-        return `unknown skill "${args.name}" — no learned copy, no stored overlay, and no upstream resolved in the ${key.root} root.`;
+        return {
+            found: false,
+            message: `unknown skill "${args.name}" — no learned copy, no stored overlay, and no upstream resolved in the ${key.root} root.`,
+        };
     }
     const notes = [
         `(no learned copy of "${args.name}"; showing the ${key.root} upstream${stored === undefined ? "" : " with the stored overlay"})`,
@@ -129,7 +133,7 @@ async function viewUpstreamOnly(deps, stores, args, env, ctx) {
     else {
         body = withOverlay(upstream.body, stored.text);
     }
-    return `${notes.join(" ")}\n\n${body}`;
+    return { found: true, body: `${notes.join(" ")}\n\n${body}` };
 }
 /** Render the store's `list` result as the model-facing text. */
 function renderList(skills) {
@@ -155,7 +159,7 @@ export function buildSkillManageTool(deps) {
             // Ownerless conversations: nothing to read (and no user to write
             // for — the mutating refusal below covers those too, but the read
             // answer is the one the brief pins).
-            if (args.action === "list" || args.action === "view") {
+            if (SKILL_MANAGE_READ_ACTIONS.has(args.action)) {
                 if (owner === undefined) {
                     return error("This conversation has no owner, so there are no learned skills to inspect.");
                 }
@@ -169,18 +173,29 @@ export function buildSkillManageTool(deps) {
                 }
                 if (args.name === undefined)
                     return error("view requires a skill name.");
-                const learned = await stores.store
-                    .view(args.name, args.file_path ?? "SKILL.md")
-                    .then((body) => body, () => undefined);
+                // The learned read: ENOENT (no learned copy) falls through to
+                // the upstream/overlay serving below; ANY OTHER store failure
+                // (a permissions error, a corrupt root) must surface, never
+                // fail open into a phantom "unknown skill".
+                let learned;
+                try {
+                    learned = await stores.store.view(args.name, args.file_path ?? "SKILL.md");
+                }
+                catch (cause) {
+                    if (cause?.code !== "ENOENT") {
+                        throw cause;
+                    }
+                    learned = undefined;
+                }
                 if (learned === undefined) {
                     // Upstream-only names (the overlay lifecycle): serve the stored
                     // overlay and/or the live upstream — without this fallback the
                     // learned-root ENOENT traps an overlay update/remove in an
                     // unrecoverable "view X first" → "unknown skill" loop.
                     const served = await viewUpstreamOnly(deps, stores, { name: args.name, overlay_root: args.overlay_root }, api.env, context);
-                    if (served.startsWith("unknown skill"))
-                        return error(served);
-                    api.output(served);
+                    if (!served.found)
+                        return error(served.message);
+                    api.output(served.body);
                 }
                 else {
                     api.output(learned);
@@ -223,6 +238,16 @@ export function buildSkillManageTool(deps) {
                 conversationId: api.conversationId,
                 ...(args.reason === undefined ? {} : { reason: args.reason }),
             };
+            // Empty content: a create/write_file carrying no text records a
+            // phantom empty entry (the cleanup-pass C1). Refuse UP FRONT, at
+            // the tool boundary, naming the empty content — the store's
+            // frontmatter check would otherwise answer a create with the
+            // misleading "frontmatter is required", and a write_file would
+            // silently land an empty support file plus its feed entry.
+            if ((args.action === "create" || args.action === "write_file") &&
+                (args.content ?? "") === "") {
+                return error(`${args.action} ${args.name}: empty content — nothing to write.`);
+            }
             // Read-before-write: an existing item must carry its name in the
             // run doc's viewed ledger. A skill that does not exist yet (a
             // create, or a first overlay) needs no prior view.