@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/dist/skill-loop/hook.js

@@ -0,0 +1,435 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, opendirSync, openSync, readSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { normalizeSessionId } from "../state-paths.js";
+import { SkillLoopError } from "./types.js";
+const PENDING_SCHEMA = "litcodex.skill-review-pending/v1";
+const MAX_GOALS_BYTES = 64_000;
+const MAX_SESSION_DIRECTORY_ENTRIES = 64;
+const MAX_SESSION_DIRECTORIES = 16;
+const SOURCE_FILE_CAPS = new Map([
+    ["brief.md", 64_000],
+    ["goals.json", MAX_GOALS_BYTES],
+    ["ledger.jsonl", 256_000],
+]);
+const MAX_SESSION_SOURCE_BYTES = 384_000;
+const ANCHORED_PENDING_WRITE = `
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+
+const [expectedRealPath, expectedDev, expectedIno, expectedUid, expectedMode, expectedBirthtimeMs] = process.argv.slice(1);
+const matches = () => {
+  const stat = lstatSync(".");
+  return stat.isDirectory() &&
+    !stat.isSymbolicLink() &&
+    String(stat.dev) === expectedDev &&
+    String(stat.ino) === expectedIno &&
+    String(stat.uid) === expectedUid &&
+    String(stat.mode) === expectedMode &&
+    String(stat.birthtimeMs) === expectedBirthtimeMs &&
+    (stat.mode & 0o022) === 0 &&
+    realpathSync.native(".") === expectedRealPath;
+};
+
+if (!matches()) process.exit(41);
+const bytes = readFileSync(0);
+if (bytes.byteLength > 16_384) process.exit(42);
+const temporary = ".pending-review.json.litcodex-" + process.pid + "-" + randomBytes(8).toString("hex");
+let fileDescriptor;
+let directoryDescriptor;
+try {
+  fileDescriptor = openSync(
+    temporary,
+    constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+    0o600,
+  );
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const written = writeSync(fileDescriptor, bytes, offset, bytes.byteLength - offset, null);
+    if (written <= 0) throw new Error("short write");
+    offset += written;
+  }
+  fsyncSync(fileDescriptor);
+  closeSync(fileDescriptor);
+  fileDescriptor = undefined;
+  if (!matches()) throw new Error("directory authority changed before rename");
+  renameSync(temporary, "pending-review.json");
+  directoryDescriptor = openSync(".", constants.O_RDONLY | constants.O_NOFOLLOW);
+  fsyncSync(directoryDescriptor);
+  closeSync(directoryDescriptor);
+  directoryDescriptor = undefined;
+  if (!matches()) throw new Error("directory authority changed after rename");
+} finally {
+  if (fileDescriptor !== undefined) closeSync(fileDescriptor);
+  if (directoryDescriptor !== undefined) closeSync(directoryDescriptor);
+  if (existsSync(temporary)) unlinkSync(temporary);
+}
+`;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sameStat(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.uid === right.uid &&
+        left.mode === right.mode &&
+        left.nlink === right.nlink &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs &&
+        left.ctimeMs === right.ctimeMs &&
+        left.birthtimeMs === right.birthtimeMs);
+}
+function captureDirectoryPin(path, expectedRealPath) {
+    const stat = lstatSync(path);
+    const uid = typeof process.getuid === "function" ? process.getuid() : stat.uid;
+    if (stat.isSymbolicLink() ||
+        !stat.isDirectory() ||
+        (stat.uid !== uid && stat.uid !== 0) ||
+        (stat.mode & 0o022) !== 0 ||
+        realpathSync.native(path) !== expectedRealPath) {
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop directory authority is unsafe");
+    }
+    return {
+        path,
+        realPath: expectedRealPath,
+        dev: stat.dev,
+        ino: stat.ino,
+        uid: stat.uid,
+        mode: stat.mode,
+        birthtimeMs: stat.birthtimeMs,
+    };
+}
+function sameDirectoryPin(left, right) {
+    return (left.path === right.path &&
+        left.realPath === right.realPath &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.uid === right.uid &&
+        left.mode === right.mode &&
+        left.birthtimeMs === right.birthtimeMs);
+}
+function verifyDirectoryAuthority(authority) {
+    for (const expected of authority) {
+        let current;
+        try {
+            current = captureDirectoryPin(expected.path, expected.realPath);
+        }
+        catch {
+            throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop directory authority changed");
+        }
+        if (!sameDirectoryPin(current, expected)) {
+            throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop directory authority changed");
+        }
+    }
+}
+function appendDirectoryAuthority(authority, path, expectedRealPath) {
+    verifyDirectoryAuthority(authority);
+    let pin;
+    try {
+        pin = captureDirectoryPin(path, expectedRealPath);
+    }
+    catch {
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop directory authority is unsafe");
+    }
+    verifyDirectoryAuthority(authority);
+    return [...authority, pin];
+}
+function workspaceAuthority(workspaceRoot) {
+    const workspace = resolve(workspaceRoot);
+    let physical;
+    try {
+        physical = realpathSync.native(workspace);
+    }
+    catch {
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "the workspace authority is unavailable");
+    }
+    return [captureDirectoryPin(workspace, physical)];
+}
+function childAuthorityOrNull(authority, path, expectedRealPath) {
+    verifyDirectoryAuthority(authority);
+    try {
+        lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            verifyDirectoryAuthority(authority);
+            return null;
+        }
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop directory could not be inspected safely");
+    }
+    return appendDirectoryAuthority(authority, path, expectedRealPath);
+}
+function pinnedBytes(path, cap, authority, beforeRead) {
+    verifyDirectoryAuthority(authority);
+    let before;
+    try {
+        before = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            verifyDirectoryAuthority(authority);
+            return null;
+        }
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop source could not be inspected safely");
+    }
+    if (before.size > cap)
+        throw new SkillLoopError("REVIEW_SESSION_LIMIT", "a lit-loop source exceeded its byte cap");
+    const uid = typeof process.getuid === "function" ? process.getuid() : before.uid;
+    if (before.isSymbolicLink() ||
+        !before.isFile() ||
+        before.nlink !== 1 ||
+        (before.uid !== uid && before.uid !== 0) ||
+        dirname(path) !== authority.at(-1)?.path) {
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop source path is unsafe");
+    }
+    beforeRead?.(path);
+    verifyDirectoryAuthority(authority);
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const opened = fstatSync(descriptor);
+        const current = lstatSync(path);
+        if (!opened.isFile() ||
+            opened.isSymbolicLink() ||
+            opened.nlink !== 1 ||
+            !sameStat(opened, before) ||
+            !sameStat(current, before)) {
+            throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop source changed before descriptor read");
+        }
+        const bytes = Buffer.alloc(opened.size);
+        let total = 0;
+        while (total < opened.size) {
+            const count = readSync(descriptor, bytes, total, opened.size - total, total);
+            if (count === 0)
+                break;
+            total += count;
+        }
+        const after = fstatSync(descriptor);
+        const pathAfter = lstatSync(path);
+        verifyDirectoryAuthority(authority);
+        if (!sameStat(after, before) || !sameStat(pathAfter, before)) {
+            throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop source changed during descriptor read");
+        }
+        return bytes.subarray(0, total);
+    }
+    catch (error) {
+        if (error instanceof SkillLoopError)
+            throw error;
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop source could not be opened without following links");
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function validatedSession(session, loopRoot, beforeRead) {
+    const directory = session.path;
+    const goalsPath = join(directory, "goals.json");
+    const bytes = pinnedBytes(goalsPath, MAX_GOALS_BYTES, session.authority, beforeRead);
+    if (bytes === null)
+        return null;
+    let goals;
+    try {
+        goals = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!record(goals) || goals["version"] !== 1 || !Array.isArray(goals["goals"]) || goals["goals"].length === 0) {
+        return null;
+    }
+    if (goals["goals"].some((goal) => !record(goal) ||
+        typeof goal["id"] !== "string" ||
+        !["pending", "in_progress", "complete", "failed", "blocked"].includes(goal["status"]))) {
+        return null;
+    }
+    if (directory === loopRoot)
+        return "unscoped";
+    const directoryId = basename(directory);
+    const declared = typeof goals["sessionId"] === "string" ? normalizeSessionId(goals["sessionId"]) : directoryId;
+    return declared === directoryId ? directoryId : null;
+}
+function sessionDirectories(workspaceRoot, beforeRead, afterEnumerate) {
+    const workspace = resolve(workspaceRoot);
+    const stateRoot = join(workspace, ".litcodex");
+    const loopRoot = join(stateRoot, "lit-loop");
+    const baseAuthority = workspaceAuthority(workspace);
+    const physicalWorkspace = baseAuthority[0]?.realPath;
+    const stateAuthority = childAuthorityOrNull(baseAuthority, stateRoot, join(physicalWorkspace, ".litcodex"));
+    if (stateAuthority === null)
+        return [];
+    const loopAuthority = childAuthorityOrNull(stateAuthority, loopRoot, join(physicalWorkspace, ".litcodex", "lit-loop"));
+    if (loopAuthority === null)
+        return [];
+    const directories = [{ path: loopRoot, authority: loopAuthority }];
+    const handle = opendirSync(loopRoot);
+    let visited = 0;
+    try {
+        for (let entry = handle.readSync(); entry !== null; entry = handle.readSync()) {
+            visited += 1;
+            if (visited > MAX_SESSION_DIRECTORY_ENTRIES) {
+                throw new SkillLoopError("REVIEW_SESSION_LIMIT", "the lit-loop session directory cap was exceeded");
+            }
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            if (directories.length >= MAX_SESSION_DIRECTORIES) {
+                throw new SkillLoopError("REVIEW_SESSION_LIMIT", "the lit-loop session count cap was exceeded");
+            }
+            const path = join(loopRoot, entry.name);
+            const relation = relative(loopRoot, path);
+            if (relation.length === 0 || relation.includes(sep) || relation === ".." || relation.startsWith(`..${sep}`)) {
+                throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "a lit-loop session path escaped its root");
+            }
+            const authority = appendDirectoryAuthority(loopAuthority, path, join(loopAuthority.at(-1)?.realPath, relation));
+            directories.push({ path, authority });
+        }
+    }
+    finally {
+        handle.closeSync();
+    }
+    for (const directory of directories)
+        verifyDirectoryAuthority(directory.authority);
+    afterEnumerate?.();
+    for (const directory of directories)
+        verifyDirectoryAuthority(directory.authority);
+    return directories.filter((directory) => validatedSession(directory, loopRoot, beforeRead) !== null);
+}
+function readPending(session, beforeRead) {
+    const path = join(session.path, "pending-review.json");
+    const bytes = pinnedBytes(path, 16_384, session.authority, beforeRead);
+    if (bytes === null)
+        return null;
+    try {
+        const value = JSON.parse(bytes.toString("utf8"));
+        if (value.schema !== PENDING_SCHEMA ||
+            typeof value.sessionRef !== "string" ||
+            typeof value.createdAt !== "string" ||
+            (value.status !== "pending" && value.status !== "reviewed")) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function writePending(session, pending, beforeWrite, afterWriteVerify) {
+    const path = join(session.path, "pending-review.json");
+    verifyDirectoryAuthority(session.authority);
+    beforeWrite?.(path);
+    verifyDirectoryAuthority(session.authority);
+    afterWriteVerify?.(path);
+    const pin = session.authority.at(-1);
+    if (pin === undefined)
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "the pending write authority is missing");
+    const content = `${JSON.stringify(pending, null, 2)}\n`;
+    if (Buffer.byteLength(content) > 16_384) {
+        throw new SkillLoopError("REVIEW_SESSION_LIMIT", "the pending review state exceeded its byte cap");
+    }
+    const result = spawnSync(process.execPath, [
+        "--input-type=module",
+        "--eval",
+        ANCHORED_PENDING_WRITE,
+        pin.realPath,
+        String(pin.dev),
+        String(pin.ino),
+        String(pin.uid),
+        String(pin.mode),
+        String(pin.birthtimeMs),
+    ], {
+        cwd: session.path,
+        env: {},
+        input: content,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        maxBuffer: 1_024,
+        timeout: 5_000,
+    });
+    if (result.error !== undefined || result.status !== 0) {
+        throw new SkillLoopError("REVIEW_SESSION_UNSAFE", "the anchored pending-state write was refused");
+    }
+    verifyDirectoryAuthority(session.authority);
+}
+function sourceDigest(session, beforeRead) {
+    const hash = createHash("sha256");
+    let aggregate = 0;
+    for (const [name, cap] of SOURCE_FILE_CAPS) {
+        const path = join(session.path, name);
+        const bytes = pinnedBytes(path, cap, session.authority, beforeRead);
+        if (bytes === null)
+            continue;
+        if (aggregate + bytes.byteLength > MAX_SESSION_SOURCE_BYTES) {
+            throw new SkillLoopError("REVIEW_SESSION_LIMIT", "a lit-loop session source exceeded its byte cap");
+        }
+        aggregate += bytes.byteLength;
+        hash.update(name);
+        hash.update(bytes);
+    }
+    return hash.digest("hex");
+}
+export function markPendingReviews(workspaceRoot, input, options = {}) {
+    void input;
+    if (options.env?.["LITFAMILY_SKILL_REVIEW"] === "1")
+        return { marked: 0, skipped: 0 };
+    let marked = 0;
+    let skipped = 0;
+    const loopRoot = join(resolve(workspaceRoot), ".litcodex", "lit-loop");
+    for (const session of sessionDirectories(workspaceRoot, options.beforeRead, options.afterEnumerate)) {
+        const existing = readPending(session, options.beforeRead);
+        const digest = sourceDigest(session, options.beforeRead);
+        if (existing !== null && (existing.status === "pending" || existing.sourceDigest === digest)) {
+            skipped += 1;
+            continue;
+        }
+        const sessionRef = validatedSession(session, loopRoot, options.beforeRead);
+        if (sessionRef === null) {
+            skipped += 1;
+            continue;
+        }
+        writePending(session, {
+            schema: PENDING_SCHEMA,
+            sessionRef,
+            createdAt: (options.now ?? (() => new Date()))().toISOString(),
+            status: "pending",
+            sourceDigest: digest,
+        }, options.beforeWrite, options.afterWriteVerify);
+        marked += 1;
+    }
+    return { marked, skipped };
+}
+export function pendingReviewNotice(workspaceRoot, options = {}) {
+    const pending = sessionDirectories(workspaceRoot, options.beforeRead, options.afterEnumerate)
+        .map((session) => ({ session, value: readPending(session, options.beforeRead) }))
+        .filter((item) => item.value !== null && item.value.status === "pending" && item.value.surfacedAt === undefined);
+    if (pending.length === 0)
+        return null;
+    const timestamp = (options.now ?? (() => new Date()))().toISOString();
+    for (const item of pending)
+        writePending(item.session, { ...item.value, surfacedAt: timestamp }, options.beforeWrite, options.afterWriteVerify);
+    return `${pending.length} skill review${pending.length === 1 ? "" : "s"} pending — run \`litcodex skill-loop review\`.`;
+}
+export function pendingReviewDirectories(workspaceRoot, options = {}) {
+    return sessionDirectories(workspaceRoot, options.beforeRead, options.afterEnumerate)
+        .filter((session) => readPending(session, options.beforeRead)?.status === "pending")
+        .map((session) => session.path);
+}
+export function markReviewsComplete(workspaceRoot, timestamp) {
+    for (const session of sessionDirectories(workspaceRoot)) {
+        const pending = readPending(session);
+        if (pending?.status === "pending")
+            writePending(session, { ...pending, status: "reviewed", reviewedAt: timestamp });
+    }
+}

package/node_modules/@litcodex/lit-loop/dist/skill-loop/ownership.d.ts

@@ -0,0 +1,6 @@
+import type { skillLoopPaths } from "./paths.js";
+import type { SkillSnapshotItem } from "./types.js";
+export declare function markerPresent(content: string): boolean;
+export declare function stampMarker(content: string, skillId: string): string;
+export declare function decodeSkillItem(paths: ReturnType<typeof skillLoopPaths>, item: SkillSnapshotItem): string;
+export declare function snapshotIsAgentOwned(paths: ReturnType<typeof skillLoopPaths>, snapshot: readonly SkillSnapshotItem[]): boolean;

package/node_modules/@litcodex/lit-loop/dist/skill-loop/ownership.js

@@ -0,0 +1,145 @@
+import { TextDecoder } from "node:util";
+import { readBlob } from "./store.js";
+import { SkillLoopError } from "./types.js";
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+const MARKER_KEY = "litcodexAgentGenerated";
+const metadataEntry = /^metadata\s*:\s*$/u;
+const markerEntry = new RegExp(`^${MARKER_KEY}:\\s*(true|false)\\s*$`, "u");
+const exactMetadataKeys = new Set(["metadata"]);
+const exactMarkerKeys = new Set(["litcodexAgentGenerated"]);
+function mappingKey(line) {
+    const indent = /^ */u.exec(line)?.[0].length ?? 0;
+    const body = line.slice(indent);
+    const colon = body.indexOf(":");
+    if (colon < 0)
+        return null;
+    return { indent, key: body.slice(0, colon).trim() };
+}
+function hasUnsafeSemanticAlias(line, expectedIndent) {
+    const parsed = mappingKey(line);
+    if (parsed === null || (expectedIndent !== undefined && parsed.indent !== expectedIndent))
+        return false;
+    if (parsed.key.includes("\\"))
+        return true;
+    const normalized = parsed.key.normalize("NFKC");
+    if (parsed.indent === 0 && normalized.toLocaleLowerCase("en-US").includes("metadata")) {
+        return !exactMetadataKeys.has(parsed.key);
+    }
+    if (normalized.toLocaleLowerCase("en-US").includes("litcodexagentgenerated")) {
+        return !exactMarkerKeys.has(parsed.key);
+    }
+    return false;
+}
+function hasUnsupportedYamlSyntax(line) {
+    const body = line.trim();
+    if (body === "" || body.startsWith("#"))
+        return false;
+    if (/^[?%{[]/u.test(body))
+        return true;
+    const parsed = mappingKey(line);
+    if (parsed === null)
+        return false;
+    if (parsed.key === "<<" || /^[&*!{[]/u.test(parsed.key))
+        return true;
+    const colon = line.indexOf(":");
+    const value = colon < 0 ? "" : line.slice(colon + 1).trimStart();
+    return (/^(?:[!{[]|\*[^\s]+)/u.test(value) ||
+        /(?:^|\s)&[A-Za-z0-9_-]+(?:\s|$)/u.test(value) ||
+        /(?:^|\s)\*[A-Za-z0-9_-]+(?:\s|$)/u.test(value));
+}
+export function markerPresent(content) {
+    if (!content.startsWith("---\n"))
+        return false;
+    const lines = content.split("\n");
+    const end = lines.indexOf("---", 1);
+    if (end < 0)
+        return false;
+    const frontmatter = lines.slice(1, end);
+    if (frontmatter.some((line) => hasUnsupportedYamlSyntax(line) || hasUnsafeSemanticAlias(line)))
+        return false;
+    const metadataEntries = frontmatter
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => /^metadata\s*:/u.test(line));
+    if (metadataEntries.length !== 1 || !metadataEntry.test(metadataEntries[0]?.line ?? ""))
+        return false;
+    const metadata = metadataEntries[0]?.index;
+    if (metadata === undefined)
+        return false;
+    let directIndent;
+    let markerCount = 0;
+    let markerIsTrue = false;
+    for (let index = metadata + 1; index < frontmatter.length; index += 1) {
+        const line = frontmatter[index] ?? "";
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        const indent = /^ */u.exec(line)?.[0].length ?? 0;
+        if (indent === 0)
+            break;
+        directIndent ??= indent;
+        if (indent === directIndent) {
+            if (hasUnsafeSemanticAlias(line, directIndent))
+                return false;
+            const direct = line.slice(indent);
+            if (mappingKey(line)?.key !== MARKER_KEY)
+                continue;
+            markerCount += 1;
+            const marker = markerEntry.exec(direct);
+            if (marker === null || marker[1] !== "true")
+                return false;
+            markerIsTrue = true;
+        }
+    }
+    return markerCount === 1 && markerIsTrue;
+}
+export function stampMarker(content, skillId) {
+    if (markerPresent(content))
+        return content;
+    if (!content.startsWith("---\n")) {
+        return `---\nname: ${skillId}\ndescription: Agent-owned reusable skill.\nmetadata:\n  litcodexAgentGenerated: true\n---\n\n${content}`;
+    }
+    const lines = content.split("\n");
+    const end = lines.indexOf("---", 1);
+    if (end < 0)
+        throw new SkillLoopError("TARGET_MARKER_INVALID", "SKILL.md frontmatter is incomplete");
+    const frontmatter = lines.slice(1, end);
+    if (frontmatter.some((line) => hasUnsupportedYamlSyntax(line) || hasUnsafeSemanticAlias(line))) {
+        throw new SkillLoopError("TARGET_MARKER_INVALID", "SKILL.md metadata contains a noncanonical YAML key");
+    }
+    const metadataEntries = frontmatter
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => /^metadata\s*:/u.test(line));
+    if (metadataEntries.length > 1 ||
+        (metadataEntries[0] !== undefined && !metadataEntry.test(metadataEntries[0].line))) {
+        throw new SkillLoopError("TARGET_MARKER_INVALID", "SKILL.md metadata must be a direct YAML mapping");
+    }
+    const metadata = metadataEntries[0]?.index;
+    if (metadata === undefined)
+        frontmatter.push("metadata:", "  litcodexAgentGenerated: true");
+    else {
+        let indent = "  ";
+        for (let index = metadata + 1; index < frontmatter.length; index += 1) {
+            const line = frontmatter[index] ?? "";
+            if (line.trim() === "" || line.trimStart().startsWith("#"))
+                continue;
+            const current = /^ */u.exec(line)?.[0] ?? "";
+            if (current.length === 0)
+                break;
+            indent = current;
+            break;
+        }
+        frontmatter.splice(metadata + 1, 0, `${indent}litcodexAgentGenerated: true`);
+    }
+    return ["---", ...frontmatter, "---", ...lines.slice(end + 1)].join("\n");
+}
+export function decodeSkillItem(paths, item) {
+    try {
+        return utf8.decode(readBlob(paths, item));
+    }
+    catch {
+        throw new SkillLoopError("TARGET_TEXT_INVALID", "the target skill file is not valid UTF-8");
+    }
+}
+export function snapshotIsAgentOwned(paths, snapshot) {
+    const skillFile = snapshot.find((item) => item.file === "SKILL.md");
+    return skillFile !== undefined && markerPresent(decodeSkillItem(paths, skillFile));
+}

package/node_modules/@litcodex/lit-loop/dist/skill-loop/paths.d.ts

@@ -0,0 +1,18 @@
+export interface SkillLoopPaths {
+    readonly workspaceRoot: string;
+    readonly stateRoot: string;
+    readonly proposalsDir: string;
+    readonly ledgerPath: string;
+    readonly blobsDir: string;
+    readonly lockPath: string;
+    readonly agentMutationLockPath: string;
+    readonly transactionPath: string;
+    readonly agentRoot: string;
+    readonly usagePath: string;
+    readonly archiveRoot: string;
+    readonly curatorBackupsRoot: string;
+}
+export declare function agentSkillRoot(env?: NodeJS.ProcessEnv): string;
+export declare function skillLoopPaths(workspaceRoot: string, env?: NodeJS.ProcessEnv): SkillLoopPaths;
+export declare function isWithin(root: string, candidate: string): boolean;
+export declare function targetSkillDir(paths: SkillLoopPaths, skillId: string): string;

package/node_modules/@litcodex/lit-loop/dist/skill-loop/paths.js

@@ -0,0 +1,43 @@
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { SkillLoopError } from "./types.js";
+export function agentSkillRoot(env = process.env) {
+    const home = env["HOME"]?.trim();
+    if (!home || !isAbsolute(home)) {
+        throw new SkillLoopError("HOME_INVALID", "the skill-loop HOME is unavailable");
+    }
+    return resolve(home, ".agents", "skills");
+}
+export function skillLoopPaths(workspaceRoot, env = process.env) {
+    if (!isAbsolute(workspaceRoot)) {
+        throw new SkillLoopError("WORKSPACE_ROOT_INVALID", "the skill-loop workspace root must be absolute");
+    }
+    const root = resolve(workspaceRoot);
+    const stateRoot = join(root, ".litcodex");
+    const agentRoot = agentSkillRoot(env);
+    return {
+        workspaceRoot: root,
+        stateRoot,
+        proposalsDir: join(stateRoot, "skill-proposals"),
+        ledgerPath: join(stateRoot, "skill-ledger.jsonl"),
+        blobsDir: join(stateRoot, "skill-ledger-blobs"),
+        lockPath: join(stateRoot, "skill-loop.lock"),
+        agentMutationLockPath: join(resolve(agentRoot, ".."), ".litcodex-skill-loop-mutation.lock"),
+        transactionPath: join(stateRoot, "skill-transaction.json"),
+        agentRoot,
+        usagePath: join(agentRoot, ".litcodex-usage.json"),
+        archiveRoot: join(agentRoot, ".litcodex-archive"),
+        curatorBackupsRoot: join(agentRoot, ".litcodex-curator-backups"),
+    };
+}
+export function isWithin(root, candidate) {
+    const normalizedRoot = resolve(root);
+    const normalizedCandidate = resolve(candidate);
+    return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}${sep}`);
+}
+export function targetSkillDir(paths, skillId) {
+    const target = resolve(paths.agentRoot, skillId);
+    if (!isWithin(paths.agentRoot, target) || target === paths.agentRoot) {
+        throw new SkillLoopError("TARGET_NOT_AGENT_OWNED", "the proposal target is not agent-owned");
+    }
+    return target;
+}

package/node_modules/@litcodex/lit-loop/dist/skill-loop/review.d.ts

@@ -0,0 +1,28 @@
+export interface ReviewOptions {
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly now?: () => Date;
+    readonly spawn?: ReviewSpawn;
+    /** Test-only race seam; production callers leave this unset. */
+    readonly beforeRead?: ((path: string) => void) | undefined;
+}
+export interface ReviewSpawnOptions {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly encoding: "utf8";
+    readonly stdio: ["ignore", "pipe", "pipe"];
+    readonly maxBuffer: number;
+    readonly timeout: number;
+}
+export interface ReviewSpawnResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: Error;
+}
+export type ReviewSpawn = (command: string, args: readonly string[], options: ReviewSpawnOptions) => ReviewSpawnResult;
+export declare function buildReviewPacket(workspaceRoot: string, options?: Pick<ReviewOptions, "env" | "beforeRead">): string;
+export declare function runCodexReview(workspaceRoot: string, options?: ReviewOptions): {
+    readonly ok: true;
+    readonly proposalIds: readonly string[];
+    readonly noOp: boolean;
+};