@litfamily/litgrok 1.0.2 → 1.0.3

package/.grok/skills/skill-observer/scripts/skill-loop.mjs

@@ -1,2087 +0,0 @@
-#!/usr/bin/env node
-
-import { createHash, randomUUID } from 'node:crypto';
-import {
-  chmodSync,
-  closeSync,
-  constants,
-  copyFileSync,
-  existsSync,
-  fstatSync,
-  fsyncSync,
-  lstatSync,
-  linkSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  readdirSync,
-  realpathSync,
-  renameSync,
-  rmSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-  writeSync,
-} from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const SCRIPT_PATH = fileURLToPath(import.meta.url);
-const RUNTIME_PLATFORM = process.platform;
-const SCRIPT_DIRECTORY = dirname(SCRIPT_PATH);
-const OBSERVER_DIRECTORY = dirname(SCRIPT_DIRECTORY);
-const PACKAGED_SKILLS_ROOT = dirname(OBSERVER_DIRECTORY);
-const PROPOSAL_SCHEMA = 'litfamily.skill-proposal/v1';
-const LEDGER_SCHEMA = 'litfamily.skill-ledger/v1';
-const USAGE_SCHEMA = 'litfamily.skill-usage/v1';
-const PENDING_SCHEMA = 'litgrok.pending-review/v1';
-const TRANSACTION_SCHEMA = 'litgrok.skill-transaction/v1';
-const TRANSACTION_AUTHORITY_SCHEMA = 'litgrok.skill-transaction-authority/v1';
-const TRANSACTION_COMPLETION_SCHEMA = 'litgrok.skill-transaction-completion/v1';
-const MARKER = 'metadata: { litgrokAgentGenerated: "true" }';
-const MAX_JSON_BYTES = 1024 * 1024;
-const MAX_PROPOSALS = 128;
-const MAX_SKILL_FILES = 256;
-const MAX_FILE_BYTES = 2 * 1024 * 1024;
-const MAX_SNAPSHOT_BYTES = 16 * 1024 * 1024;
-const LOCK_SCHEMA = 'litgrok.state-lock/v1';
-const LOCK_SCHEMA_V2 = 'litgrok.state-lock/v2';
-const STALE_LOCK_MS = 30_000;
-const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
-const SKILL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const DEVICE_PATTERN = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
-const SECRET_PATTERN = /(?:authorization\s*:\s*bearer\s+\S+|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\b(?:api[_ -]?key|password|secret|token)\s*[:=]\s*["']?[A-Za-z0-9_./+:-]{8,}|\b(?:sk|xai)-[A-Za-z0-9_-]{12,}|\b(?:gh[pousr]_[A-Za-z0-9]{20,255}|github_pat_[A-Za-z0-9_]{20,255}|npm_[A-Za-z0-9]{20,255})\b|\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b)/i;
-const INVISIBLE_SECRET_SEPARATOR_PATTERN = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/g;
-const decoder = new TextDecoder('utf-8', { fatal: true });
-
-export class SkillLoopError extends Error {
-  constructor(code, detail = '') {
-    super(detail ? `${code}: ${detail}` : code);
-    this.code = code;
-  }
-}
-
-function fail(code, detail = '') {
-  throw new SkillLoopError(code, detail);
-}
-
-export function isLearningLoopPlatformUnsupported(runtimePlatform, forcedPlatform) {
-  return runtimePlatform === 'win32' || forcedPlatform === 'win32';
-}
-
-export function assertLearningLoopSupported(options = {}) {
-  if (isLearningLoopPlatformUnsupported(RUNTIME_PLATFORM, options.platform)) fail('WINDOWS_SKILL_LOOP_UNSUPPORTED');
-}
-
-function isObject(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function requireObject(value, code) {
-  if (!isObject(value)) fail(code);
-  return value;
-}
-
-function requireString(value, code, max = 8192) {
-  if (typeof value !== 'string' || value.length === 0 || value.length > max || value.includes('\0')) fail(code);
-  return value;
-}
-
-function requireExactKeys(value, allowed, required, code) {
-  const object = requireObject(value, code);
-  for (const key of Object.keys(object)) if (!allowed.includes(key)) fail(code, `unknown field ${key}`);
-  for (const key of required) if (!Object.hasOwn(object, key)) fail(code, `missing field ${key}`);
-}
-
-function requireTimestamp(value, code = 'TIMESTAMP_INVALID') {
-  requireString(value, code, 64);
-  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(value)) fail(code);
-  const time = Date.parse(value);
-  if (!Number.isFinite(time)) fail(code);
-  return time;
-}
-
-function posixOwnerToken() {
-  const uid = process.getuid?.();
-  if (!Number.isSafeInteger(uid) || uid < 0) fail('PLATFORM_IDENTITY_UNAVAILABLE');
-  return `uid:${uid}`;
-}
-
-function platformOwnerForDirectory(path, options = {}) {
-  if (process.platform === 'win32') {
-    const status = lstatSync(path);
-    if (!status.isDirectory() || status.isSymbolicLink() || realpathSync(path) !== resolve(path)) {
-      fail(options.code ?? 'STATE_PATH_UNSAFE', path);
-    }
-    return 'windows-local';
-  }
-  const token = posixOwnerToken();
-  const uid = Number(token.slice(4));
-  const status = lstatSync(path);
-  if (!status.isDirectory() || status.isSymbolicLink() || status.uid !== uid || realpathSync(path) !== resolve(path)
-    || (status.mode & 0o022) !== 0) {
-    fail(options.code ?? 'STATE_PATH_UNSAFE', path);
-  }
-  return token;
-}
-
-export function validateStateLockOwner(record, identity) {
-  requireObject(identity, 'STATE_LOCK_INVALID');
-  const platform = requireString(identity.platform, 'STATE_LOCK_INVALID', 32);
-  const ownerToken = requireString(identity.ownerToken, 'STATE_LOCK_INVALID', 256);
-  if (platform === 'win32') fail('WINDOWS_SKILL_LOOP_UNSUPPORTED');
-  if (record?.schema === LOCK_SCHEMA_V2) {
-    requireExactKeys(record, ['schema', 'pid', 'ownerToken', 'createdAt', 'nonce'], ['schema', 'pid', 'ownerToken', 'createdAt', 'nonce'], 'STATE_LOCK_INVALID');
-    if (!Number.isSafeInteger(record.pid) || record.pid < 1 || !ID_PATTERN.test(record.nonce ?? '')) fail('STATE_LOCK_INVALID');
-    requireTimestamp(record.createdAt, 'STATE_LOCK_INVALID');
-    if (!/^uid:\d+$/.test(record.ownerToken)) fail('STATE_LOCK_INVALID', 'POSIX owner token');
-    if (record.ownerToken !== ownerToken) fail('STATE_LOCK_OWNER_MISMATCH');
-    return record;
-  }
-  if (record?.schema === LOCK_SCHEMA) {
-    requireExactKeys(record, ['schema', 'pid', 'ownerUid', 'createdAt', 'nonce'], ['schema', 'pid', 'ownerUid', 'createdAt', 'nonce'], 'STATE_LOCK_INVALID');
-    if (!Number.isSafeInteger(record.pid) || record.pid < 1 || !Number.isSafeInteger(record.ownerUid) || record.ownerUid < 0
-      || !ID_PATTERN.test(record.nonce ?? '')) fail('STATE_LOCK_INVALID');
-    requireTimestamp(record.createdAt, 'STATE_LOCK_INVALID');
-    if (`uid:${record.ownerUid}` !== ownerToken) fail('STATE_LOCK_OWNER_MISMATCH');
-    return record;
-  }
-  fail('STATE_LOCK_INVALID', 'owner schema');
-}
-
-function safeMkdir(path, mode = 0o700) {
-  if (!existsSync(path)) {
-    const parent = dirname(path);
-    if (parent !== path) safeMkdir(parent, mode);
-  }
-  try {
-    mkdirSync(path, { mode });
-  } catch (error) {
-    if (error?.code !== 'EEXIST') throw error;
-  }
-  const status = lstatSync(path);
-  if (!status.isDirectory() || status.isSymbolicLink()) fail('STATE_PATH_UNSAFE', path);
-}
-
-function ensureBelow(root, segments) {
-  let current = root;
-  const rootStatus = lstatSync(root);
-  if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink()) fail('STATE_PATH_UNSAFE', root);
-  for (const segment of segments) {
-    current = join(current, segment);
-    safeMkdir(current);
-  }
-  return current;
-}
-
-function canonicalExistingDirectory(path, code) {
-  const resolved = resolve(path);
-  const status = lstatSync(resolved);
-  if (!status.isDirectory() || status.isSymbolicLink()) fail(code, resolved);
-  return realpathSync(resolved);
-}
-
-export function createLoopContext(options = {}) {
-  if (!options.stateOnly) assertLearningLoopSupported(options);
-  const env = options.env ?? process.env;
-  const cwd = options.cwd ?? process.cwd();
-  const workspaceInput = env.LITGROK_WORKSPACE_ROOT || cwd;
-  const workspaceRoot = canonicalExistingDirectory(workspaceInput, 'WORKSPACE_ROOT_UNSAFE');
-  const homeInput = env.HOME || env.USERPROFILE || homedir();
-  if (!isAbsolute(resolve(homeInput))) fail('HOME_UNSAFE');
-  safeMkdir(resolve(homeInput));
-  const home = canonicalExistingDirectory(homeInput, 'HOME_UNSAFE');
-  const grokRoot = options.stateOnly ? join(home, '.grok') : ensureBelow(home, ['.grok']);
-  const userRoot = options.stateOnly ? join(grokRoot, 'skills') : ensureBelow(grokRoot, ['skills']);
-  const stateRoot = options.readOnlyState ? join(workspaceRoot, '.grok', 'litgrok') : ensureBelow(workspaceRoot, ['.grok', 'litgrok']);
-  return { cwd, env, grokRoot, home, stateRoot, userRoot, workspaceRoot };
-}
-
-function readBytes(path, max = MAX_JSON_BYTES) {
-  const status = lstatSync(path);
-  if (!status.isFile() || status.isSymbolicLink() || status.size > max) fail('FILE_UNSAFE', path);
-  return readFileSync(path);
-}
-
-function readText(path, max = MAX_JSON_BYTES) {
-  try {
-    return decoder.decode(readBytes(path, max));
-  } catch (error) {
-    if (error instanceof SkillLoopError) throw error;
-    fail('UTF8_INVALID', path);
-  }
-}
-
-function readJson(path, code = 'JSON_INVALID') {
-  try {
-    return JSON.parse(readText(path));
-  } catch (error) {
-    if (error instanceof SkillLoopError) throw error;
-    fail(code, path);
-  }
-}
-
-function assertSafeFileTarget(path) {
-  if (!existsSync(path)) return;
-  const status = lstatSync(path);
-  if (!status.isFile() || status.isSymbolicLink()) fail('STATE_PATH_UNSAFE', path);
-}
-
-function pathEntryExists(path) {
-  try {
-    lstatSync(path);
-    return true;
-  } catch (error) {
-    if (error?.code === 'ENOENT') return false;
-    throw error;
-  }
-}
-
-function syncDirectory(path) {
-  if (process.platform === 'win32') return;
-  const descriptor = openSync(path, constants.O_RDONLY);
-  try {
-    fsyncSync(descriptor);
-  } finally {
-    closeSync(descriptor);
-  }
-}
-
-function atomicWrite(path, bytes, mode = 0o600) {
-  safeMkdir(dirname(path));
-  assertSafeFileTarget(path);
-  const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
-  const descriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, mode);
-  try {
-    writeSync(descriptor, bytes);
-    fsyncSync(descriptor);
-  } finally {
-    closeSync(descriptor);
-  }
-  renameSync(temporary, path);
-  syncDirectory(dirname(path));
-}
-
-function atomicJson(path, value) {
-  atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
-}
-
-function wait(milliseconds) {
-  const buffer = new SharedArrayBuffer(4);
-  Atomics.wait(new Int32Array(buffer), 0, 0, milliseconds);
-}
-
-function processIsAlive(pid) {
-  if (!Number.isSafeInteger(pid) || pid < 1) fail('STATE_LOCK_INVALID', 'pid');
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    if (error?.code === 'ESRCH') return false;
-    if (error?.code === 'EPERM') return true;
-    fail('STATE_LOCK_INVALID', 'pid probe');
-  }
-}
-
-function lockIdentity(path) {
-  return {
-    platform: process.platform,
-    ownerToken: platformOwnerForDirectory(dirname(path), { code: 'STATE_LOCK_OWNERSHIP_UNVERIFIED' }),
-  };
-}
-
-function validateLockFileSecurity(path, identity) {
-  const status = lstatSync(path);
-  if (!status.isFile() || status.isSymbolicLink() || status.size > 4096 || status.nlink !== 1) fail('STATE_LOCK_INVALID', path);
-  if (identity.platform !== 'win32') {
-    const ownerUid = Number(identity.ownerToken.slice(4));
-    if (status.uid !== ownerUid) fail('STATE_LOCK_OWNER_MISMATCH', path);
-    if ((status.mode & 0o7777) !== 0o600 || realpathSync(path) !== resolve(path)) fail('STATE_LOCK_INVALID', path);
-  }
-  return status;
-}
-
-function sameLockIdentity(left, right) {
-  return left.isFile() === right.isFile()
-    && left.isSymbolicLink() === right.isSymbolicLink()
-    && 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.ctimeMs === right.ctimeMs
-    && left.birthtimeMs === right.birthtimeMs;
-}
-
-function sameLockHandle(left, right) {
-  return left.isFile() === right.isFile()
-    && left.isSymbolicLink() === right.isSymbolicLink()
-    && left.dev === right.dev
-    && left.ino === right.ino
-    && left.uid === right.uid
-    && left.mode === right.mode
-    && left.nlink === right.nlink
-    && left.size === right.size;
-}
-
-function sameLockLocation(left, right) {
-  return left.isFile() === right.isFile()
-    && left.isSymbolicLink() === right.isSymbolicLink()
-    && left.dev === right.dev
-    && left.ino === right.ino
-    && left.uid === right.uid
-    && left.nlink === right.nlink;
-}
-
-function inspectLockAgainstDescriptor(path, descriptor, identity, secure) {
-  const named = secure ? validateLockFileSecurity(path, identity) : lstatSync(path);
-  if (!named.isFile() || named.isSymbolicLink() || named.size > 4096 || named.nlink !== 1) fail('STATE_LOCK_INVALID', path);
-  const held = fstatSync(descriptor);
-  if (held.size > 4096) fail('STATE_LOCK_INVALID', path);
-  let reader;
-  try {
-    reader = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(reader);
-    if (!sameLockLocation(opened, held) || opened.size !== named.size) fail('STATE_LOCK_RACE', path);
-    const bytes = readFileSync(reader);
-    const current = secure ? validateLockFileSecurity(path, identity) : lstatSync(path);
-    if (!sameLockLocation(current, held) || current.size !== opened.size) fail('STATE_LOCK_RACE', path);
-    return { bytes, digest: createHash('sha256').update(bytes).digest('hex'), status: current };
-  } finally {
-    if (reader !== undefined) closeSync(reader);
-  }
-}
-
-function restoreMovedLock(path, tombstone) {
-  try {
-    linkSync(tombstone, path);
-    unlinkSync(tombstone);
-  } catch (error) {
-    if (error?.code !== 'EEXIST') throw error;
-  }
-}
-
-function removePinnedLock(path, descriptor, identity, expected, expectedBytes, code, {
-  secure = false,
-  tokenWritten = true,
-  bytesWritten = Buffer.byteLength(expectedBytes, 'utf8'),
-  faultInjector,
-  phase,
-} = {}) {
-  const bytes = Buffer.from(expectedBytes, 'utf8');
-  const prefix = bytes.subarray(0, bytesWritten);
-  const matches = (entry, beforeRename) => {
-    const identityMatches = secure ? sameLockHandle(entry.status, expected) : sameLockLocation(entry.status, expected);
-    if (!identityMatches) return false;
-    if (tokenWritten ? !entry.bytes.equals(bytes) : !entry.bytes.equals(prefix)) return false;
-    return !beforeRename || tokenWritten || bytesWritten > 0 || sameLockIdentity(entry.status, expected);
-  };
-  let checked;
-  try {
-    checked = inspectLockAgainstDescriptor(path, descriptor, identity, secure);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return 'vanished';
-    throw error;
-  }
-  if (!matches(checked, true)) fail(code, path);
-  faultInjector?.(phase, { path, descriptor, expectedBytes });
-  checked = inspectLockAgainstDescriptor(path, descriptor, identity, secure);
-  if (!matches(checked, true)) fail(code, path);
-  const tombstone = `${path}.cleanup-${process.pid}-${randomUUID()}`;
-  try {
-    renameSync(path, tombstone);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return 'vanished';
-    throw error;
-  }
-  let moved;
-  try {
-    moved = inspectLockAgainstDescriptor(tombstone, descriptor, identity, secure);
-  } catch (error) {
-    restoreMovedLock(path, tombstone);
-    throw error;
-  }
-  if (!matches(moved, false)) {
-    restoreMovedLock(path, tombstone);
-    fail(code, path);
-  }
-  unlinkSync(tombstone);
-  return 'removed';
-}
-
-function readSecureLock(path, identity, options = {}) {
-  let expected;
-  try {
-    expected = options.expectedStatus ?? validateLockFileSecurity(path, identity);
-  } catch (error) {
-    if (options.missingLock === 'propagate' && error?.code === 'ENOENT') throw error;
-    throw error instanceof SkillLoopError ? error : new SkillLoopError('STATE_LOCK_INVALID', path);
-  }
-  let descriptor;
-  try {
-    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile() || opened.size > 4096 || opened.nlink !== 1 || !sameLockIdentity(opened, expected)) {
-      fail('STATE_LOCK_INVALID', path);
-    }
-    const bytes = readFileSync(descriptor);
-    const contents = bytes.toString('utf8').trim();
-    const digest = createHash('sha256').update(bytes).digest('hex');
-    const current = validateLockFileSecurity(path, identity);
-    if (!sameLockIdentity(current, opened)) fail('STATE_LOCK_RACE', path);
-    return { contents, digest, status: current };
-  } catch (error) {
-    if (error instanceof SkillLoopError) throw error;
-    if (options.missingLock === 'propagate' && error?.code === 'ENOENT') throw error;
-    fail('STATE_LOCK_INVALID', path);
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
-  }
-}
-
-function reclaimStaleLock(path, identity, options = {}) {
-  if (identity.platform === 'win32') return false;
-  options.faultInjector?.('reclaim-check', { path });
-  let initial;
-  try {
-    initial = validateLockFileSecurity(path, identity);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return 'vanished';
-    throw error;
-  }
-  const fileAge = Date.now() - initial.mtimeMs;
-  if (fileAge < -5_000) fail('STATE_LOCK_INVALID', 'future timestamp');
-  if (fileAge < STALE_LOCK_MS) return false;
-  options.faultInjector?.('reclaim-read', { path });
-  let secureRead;
-  try {
-    secureRead = readSecureLock(path, identity, { missingLock: 'propagate', expectedStatus: initial });
-  } catch (error) {
-    if (error?.code === 'ENOENT') return 'vanished';
-    throw error;
-  }
-  const { contents, digest, status } = secureRead;
-  let record;
-  if (/^[1-9][0-9]{0,14}$/.test(contents)) {
-    if (identity.platform === 'win32') fail('STATE_LOCK_INVALID', 'legacy owner unavailable');
-    record = {
-      schema: LOCK_SCHEMA,
-      pid: Number(contents),
-      ownerUid: Number(identity.ownerToken.slice(4)),
-      createdAt: new Date(status.mtimeMs).toISOString(),
-      nonce: 'legacy-numeric-pid',
-    };
-  } else {
-    try {
-      record = JSON.parse(contents);
-    } catch {
-      fail('STATE_LOCK_INVALID', path);
-    }
-    validateStateLockOwner(record, identity);
-  }
-  const createdAt = requireTimestamp(record.createdAt, 'STATE_LOCK_INVALID');
-  const age = Date.now() - createdAt;
-  if (age < -5_000) fail('STATE_LOCK_INVALID', 'future timestamp');
-  if (age < STALE_LOCK_MS || processIsAlive(record.pid)) return false;
-
-  const tombstone = `${path}.stale-${process.pid}-${randomUUID()}`;
-  try {
-    renameSync(path, tombstone);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return 'vanished';
-    throw error;
-  }
-  const moved = readSecureLock(tombstone, identity);
-  if (!sameLockHandle(moved.status, status) || moved.contents !== contents || moved.digest !== digest) {
-    restoreMovedLock(path, tombstone);
-    fail('STATE_LOCK_RACE', path);
-  }
-  unlinkSync(tombstone);
-  return 'reclaimed';
-}
-
-function cleanupFailedLockAcquisition(path, descriptor, created, expectedBytes, tokenWritten, bytesWritten, identity, options = {}) {
-  try {
-    try {
-      removePinnedLock(path, descriptor, identity, created, expectedBytes, 'STATE_LOCK_ACQUISITION_CLEANUP_FAILED', {
-        tokenWritten,
-        bytesWritten,
-        faultInjector: options.faultInjector,
-        phase: 'before-acquisition-cleanup-rename',
-      });
-    } catch (error) {
-      if (error?.code === 'STATE_LOCK_ACQUISITION_CLEANUP_FAILED') throw error;
-      fail('STATE_LOCK_ACQUISITION_CLEANUP_FAILED', error?.code ?? 'retargeted');
-    }
-  } finally {
-    try {
-      closeSync(descriptor);
-    } catch {
-      fail('STATE_LOCK_ACQUISITION_CLEANUP_FAILED', 'descriptor');
-    }
-  }
-}
-
-export function withStateLock(path, operation, attempts = 200, options = {}) {
-  safeMkdir(dirname(path));
-  const identity = lockIdentity(path);
-  let descriptor;
-  let ownerBytes;
-  for (let index = 0; index < attempts; index += 1) {
-    let created;
-    let expectedBytes;
-    let tokenWritten = false;
-    let bytesWritten = 0;
-    try {
-      descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
-      created = fstatSync(descriptor);
-      expectedBytes = `${JSON.stringify({
-        schema: LOCK_SCHEMA_V2,
-        pid: process.pid,
-        ownerToken: identity.ownerToken,
-        createdAt: new Date().toISOString(),
-        nonce: randomUUID(),
-      })}\n`;
-      ownerBytes = expectedBytes;
-      const bytes = Buffer.from(expectedBytes, 'utf8');
-      let offset = 0;
-      while (offset < bytes.length) {
-        options.faultInjector?.('before-token-write', { descriptor, path });
-        const written = writeSync(descriptor, bytes, offset, bytes.length - offset);
-        if (!Number.isSafeInteger(written) || written < 1) fail('STATE_LOCK_WRITE_FAILED');
-        offset += written;
-        bytesWritten = offset;
-      }
-      tokenWritten = true;
-      fsyncSync(descriptor);
-      options.faultInjector?.('after-create', { descriptor, path });
-      validateLockFileSecurity(path, identity);
-      break;
-    } catch (error) {
-      if (descriptor !== undefined) {
-        cleanupFailedLockAcquisition(path, descriptor, created, expectedBytes, tokenWritten, bytesWritten, identity, options);
-        descriptor = undefined;
-      }
-      if (error?.code !== 'EEXIST') throw error;
-      const reclaimed = reclaimStaleLock(path, identity, options);
-      if (reclaimed) {
-        if (reclaimed === 'reclaimed') index -= 1;
-        continue;
-      }
-      if (index === attempts - 1) fail('STATE_LOCK_BUSY', path);
-      wait(5);
-    }
-  }
-  if (descriptor === undefined) fail('STATE_LOCK_BUSY', path);
-  const owned = fstatSync(descriptor);
-  try {
-    return operation();
-  } finally {
-    try {
-      removePinnedLock(path, descriptor, identity, owned, ownerBytes, 'STATE_LOCK_OWNERSHIP_LOST', {
-        secure: true,
-        faultInjector: options.faultInjector,
-        phase: 'before-release-rename',
-      });
-    } catch (error) {
-      if (error?.code !== 'ENOENT') throw error;
-    } finally {
-      closeSync(descriptor);
-    }
-  }
-}
-
-function globalLock(context) {
-  return join(context.stateRoot, 'skill-loop.lock');
-}
-
-function sessionKey(sessionId) {
-  return createHash('sha256').update(requireString(sessionId, 'SESSION_ID_INVALID', 512)).digest('hex').slice(0, 32);
-}
-
-function pendingDirectory(context) {
-  return ensureBelow(context.stateRoot, ['pending-review']);
-}
-
-function pendingPath(context, sessionId) {
-  return join(pendingDirectory(context), `${sessionKey(sessionId)}.json`);
-}
-
-function pendingLockPath(context, sessionId) {
-  return join(pendingDirectory(context), `${sessionKey(sessionId)}.lock`);
-}
-
-function readPendingAt(path, sessionId) {
-  if (!existsSync(path)) {
-    return {
-      schema: PENDING_SCHEMA,
-      sessionId,
-      pending: false,
-      turnEndedCount: 0,
-      reviewedTurnCount: 0,
-      lastProposalTurnCount: 0,
-      turnsSinceLastProposal: 0,
-      proposalsRecorded: 0,
-      updatedAt: new Date(0).toISOString(),
-    };
-  }
-  const state = readJson(path, 'PENDING_STATE_INVALID');
-  requireExactKeys(
-    state,
-    ['schema', 'sessionId', 'pending', 'turnEndedCount', 'reviewedTurnCount', 'lastProposalTurnCount', 'turnsSinceLastProposal', 'proposalsRecorded', 'updatedAt'],
-    ['schema', 'sessionId', 'pending', 'turnEndedCount', 'reviewedTurnCount', 'lastProposalTurnCount', 'turnsSinceLastProposal', 'proposalsRecorded', 'updatedAt'],
-    'PENDING_STATE_INVALID',
-  );
-  if (state.schema !== PENDING_SCHEMA || state.sessionId !== sessionId || typeof state.pending !== 'boolean') fail('PENDING_STATE_INVALID');
-  for (const key of ['turnEndedCount', 'reviewedTurnCount', 'lastProposalTurnCount', 'turnsSinceLastProposal', 'proposalsRecorded']) {
-    if (!Number.isSafeInteger(state[key]) || state[key] < 0) fail('PENDING_STATE_INVALID', key);
-  }
-  if (state.turnsSinceLastProposal !== state.turnEndedCount - state.lastProposalTurnCount) fail('PENDING_STATE_INVALID', 'counter mismatch');
-  requireTimestamp(state.updatedAt);
-  return state;
-}
-
-export function recordTurnEnded(options = {}) {
-  const context = options.context ?? createLoopContext({ ...options, stateOnly: true });
-  const sessionId = requireString(options.sessionId, 'SESSION_ID_INVALID', 512);
-  const path = pendingPath(context, sessionId);
-  return withStateLock(pendingLockPath(context, sessionId), () => {
-    const state = readPendingAt(path, sessionId);
-    state.pending = true;
-    state.turnEndedCount += 1;
-    state.turnsSinceLastProposal = state.turnEndedCount - state.lastProposalTurnCount;
-    state.updatedAt = new Date().toISOString();
-    atomicJson(path, state);
-    return state;
-  });
-}
-
-export function pendingReviewState(options = {}) {
-  const context = options.context ?? createLoopContext({ ...options, readOnlyState: true, stateOnly: true });
-  const sessionId = requireString(options.sessionId, 'SESSION_ID_INVALID', 512);
-  const directory = join(context.stateRoot, 'pending-review');
-  if (!existsSync(directory)) return readPendingAt(join(directory, `${sessionKey(sessionId)}.json`), sessionId);
-  const status = lstatSync(directory);
-  if (!status.isDirectory() || status.isSymbolicLink()) fail('STATE_PATH_UNSAFE', directory);
-  return readPendingAt(join(directory, `${sessionKey(sessionId)}.json`), sessionId);
-}
-
-export function pendingSessions(options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  const directory = pendingDirectory(context);
-  const states = [];
-  for (const entry of readdirSync(directory, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
-    const value = readJson(join(directory, entry.name), 'PENDING_STATE_INVALID');
-    states.push(readPendingAt(join(directory, entry.name), requireString(value.sessionId, 'PENDING_STATE_INVALID', 512)));
-  }
-  return states.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
-}
-
-export function finishReviewState(options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  const sessionId = requireString(options.sessionId, 'SESSION_ID_INVALID', 512);
-  const count = options.proposalCount ?? 0;
-  if (!Number.isSafeInteger(count) || count < 0 || count > 3) fail('PROPOSAL_BATCH_INVALID');
-  const path = pendingPath(context, sessionId);
-  return withStateLock(pendingLockPath(context, sessionId), () => {
-    const state = readPendingAt(path, sessionId);
-    state.pending = false;
-    state.reviewedTurnCount = state.turnEndedCount;
-    if (count > 0) {
-      state.lastProposalTurnCount = state.turnEndedCount;
-      state.proposalsRecorded += count;
-    }
-    state.turnsSinceLastProposal = state.turnEndedCount - state.lastProposalTurnCount;
-    state.updatedAt = new Date().toISOString();
-    atomicJson(path, state);
-    return state;
-  });
-}
-
-function portableIdentity(path) {
-  return path.split('/').map((segment) => segment.normalize('NFKC').toLowerCase().replace(/[. ]+$/g, '')).join('/');
-}
-
-function validateSkillName(value, code = 'TARGET_SKILL_INVALID') {
-  requireString(value, code, 128);
-  if (!SKILL_PATTERN.test(value) || value.normalize('NFKC') !== value || /[. ]$/.test(value) || DEVICE_PATTERN.test(value)) fail(code, value);
-  return value;
-}
-
-function validateRelativeFile(value, targetSkill) {
-  requireString(value, 'PROPOSAL_PATH_INVALID', 1024);
-  if (value.includes('\\') || /^[A-Za-z]:/.test(value) || value.startsWith('/') || value.startsWith('//')) fail('PROPOSAL_PATH_INVALID', value);
-  if (/[\u0000-\u001f\u007f-\u009f:*?"<>|]/.test(value) || value.includes('//')) fail('PROPOSAL_PATH_INVALID', value);
-  const segments = value.split('/');
-  if (segments.some((segment) => !segment || segment === '.' || segment === '..' || /[. ]$/.test(segment) || DEVICE_PATTERN.test(segment))) {
-    fail('PROPOSAL_PATH_INVALID', value);
-  }
-  const identity = portableIdentity(value);
-  const skillIdentity = portableIdentity(targetSkill);
-  if (identity === skillIdentity || identity.startsWith(`${skillIdentity}/`)) fail('PROPOSAL_PATH_INVALID', 'file must be relative to the target skill');
-  return value;
-}
-
-function assertNoSecret(value) {
-  function visit(item) {
-    if (typeof item === 'string' && SECRET_PATTERN.test(item.replace(INVISIBLE_SECRET_SEPARATOR_PATTERN, ''))) fail('SECRET_SHAPED_DATA');
-    if (Array.isArray(item)) for (const child of item) visit(child);
-    if (isObject(item)) for (const child of Object.values(item)) visit(child);
-  }
-  visit(value);
-}
-
-function shippedSkillIds() {
-  return new Set(readdirSync(PACKAGED_SKILLS_ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name));
-}
-
-function markerPresent(content) {
-  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
-  return Boolean(frontmatter && /^metadata:\s*\{[^}\n]*\blitgrokAgentGenerated:\s*["']true["'][^}\n]*\}\s*$/m.test(frontmatter));
-}
-
-function safeTargetDirectory(context, targetSkill) {
-  validateSkillName(targetSkill);
-  const identity = portableIdentity(targetSkill);
-  if ([...shippedSkillIds()].some((skill) => portableIdentity(skill) === identity)) fail('TARGET_NOT_AGENT_OWNED', targetSkill);
-  for (const entry of readdirSync(context.userRoot, { withFileTypes: true })) {
-    if (entry.name !== targetSkill && portableIdentity(entry.name) === identity) fail('TARGET_PATH_COLLISION', targetSkill);
-  }
-  const target = join(context.userRoot, targetSkill);
-  if (!existsSync(target)) return { exists: false, target };
-  const status = lstatSync(target);
-  if (!status.isDirectory() || status.isSymbolicLink()) fail('TARGET_PATH_UNSAFE', targetSkill);
-  const skillFile = join(target, 'SKILL.md');
-  if (!existsSync(skillFile)) fail('TARGET_NOT_AGENT_OWNED', targetSkill);
-  const skillStatus = lstatSync(skillFile);
-  if (!skillStatus.isFile() || skillStatus.isSymbolicLink()) fail('TARGET_PATH_UNSAFE', targetSkill);
-  if (!markerPresent(readText(skillFile, MAX_FILE_BYTES))) fail('TARGET_NOT_AGENT_OWNED', targetSkill);
-  return { exists: true, target };
-}
-
-function canonicalTargetRoot(context, proposed) {
-  requireString(proposed, 'TARGET_ROOT_MISMATCH', 2048);
-  let proposedReal;
-  try {
-    proposedReal = realpathSync(resolve(proposed));
-  } catch {
-    fail('TARGET_ROOT_MISMATCH');
-  }
-  const expected = realpathSync(context.userRoot);
-  if (proposedReal !== expected) fail('TARGET_ROOT_MISMATCH');
-  return expected;
-}
-
-const PROPOSAL_ALLOWED = [
-  'schema', 'id', 'createdAt', 'host', 'sessionRef', 'signal', 'targetSkill', 'targetRoot',
-  'action', 'patch', 'createSpec', 'rationale', 'evidenceRefs', 'status', 'ledgerEntryId',
-];
-const PROPOSAL_REQUIRED = [
-  'schema', 'id', 'createdAt', 'host', 'sessionRef', 'signal', 'targetSkill', 'targetRoot',
-  'action', 'rationale', 'evidenceRefs', 'status',
-];
-
-export function validateProposal(record, options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  requireExactKeys(record, PROPOSAL_ALLOWED, PROPOSAL_REQUIRED, 'PROPOSAL_INVALID');
-  if (record.schema !== PROPOSAL_SCHEMA || record.host !== 'litgrok') fail('PROPOSAL_INVALID', 'schema or host');
-  if (!ID_PATTERN.test(record.id)) fail('PROPOSAL_INVALID', 'id');
-  requireTimestamp(record.createdAt);
-  requireString(record.sessionRef, 'PROPOSAL_INVALID', 512);
-  requireString(record.signal, 'PROPOSAL_INVALID', 128);
-  validateSkillName(record.targetSkill);
-  const targetRoot = canonicalTargetRoot(context, record.targetRoot);
-  requireString(record.rationale, 'PROPOSAL_INVALID', 8192);
-  if (!Array.isArray(record.evidenceRefs) || record.evidenceRefs.length > 32 || new Set(record.evidenceRefs).size !== record.evidenceRefs.length) {
-    fail('PROPOSAL_INVALID', 'evidenceRefs');
-  }
-  for (const value of record.evidenceRefs) requireString(value, 'PROPOSAL_INVALID', 2048);
-  if (!['pending', 'approved', 'applied', 'rejected', 'rolled-back'].includes(record.status)) fail('PROPOSAL_INVALID', 'status');
-  if (['applied', 'rolled-back'].includes(record.status)) {
-    if (!ID_PATTERN.test(record.ledgerEntryId ?? '')) fail('PROPOSAL_INVALID', 'ledgerEntryId');
-  } else if (Object.hasOwn(record, 'ledgerEntryId')) fail('PROPOSAL_INVALID', 'ledgerEntryId forbidden');
-  if (options.queue === true && record.status !== 'pending') fail('PROPOSAL_NOT_PENDING');
-
-  const targetState = safeTargetDirectory(context, record.targetSkill);
-  if (!['patch', 'create', 'add-reference', 'archive'].includes(record.action)) fail('PROPOSAL_INVALID', 'action');
-  if (record.action === 'patch') {
-    requireExactKeys(record.patch, ['file', 'oldString', 'newString'], ['file', 'oldString', 'newString'], 'PROPOSAL_INVALID');
-    validateRelativeFile(record.patch.file, record.targetSkill);
-    requireString(record.patch.oldString, 'PROPOSAL_INVALID', 65536);
-    if (typeof record.patch.newString !== 'string' || record.patch.newString.length > 65536) fail('PROPOSAL_INVALID');
-    if (record.patch.oldString === record.patch.newString) fail('PATCH_NO_CHANGE');
-    if (Object.hasOwn(record, 'createSpec') || !targetState.exists) fail('TARGET_NOT_AGENT_OWNED', record.targetSkill);
-  } else if (record.action === 'create' || record.action === 'add-reference') {
-    if (Object.hasOwn(record, 'patch')) fail('PROPOSAL_INVALID');
-    requireExactKeys(record.createSpec, ['files'], ['files'], 'PROPOSAL_INVALID');
-    const files = record.createSpec.files;
-    if (!Array.isArray(files) || files.length < 1 || files.length > 64) fail('PROPOSAL_INVALID');
-    const identities = new Set();
-    for (const item of files) {
-      requireExactKeys(item, ['file', 'content'], ['file', 'content'], 'PROPOSAL_INVALID');
-      validateRelativeFile(item.file, record.targetSkill);
-      if (typeof item.content !== 'string' || item.content.length > 65536) fail('PROPOSAL_INVALID');
-      const identity = portableIdentity(item.file);
-      if (identities.has(identity)) fail('PROPOSAL_PATH_COLLISION', item.file);
-      identities.add(identity);
-    }
-    if (record.action === 'create') {
-      if (targetState.exists && ['pending', 'approved'].includes(record.status)) fail('TARGET_ALREADY_EXISTS', record.targetSkill);
-      if (!files.some((item) => portableIdentity(item.file) === 'skill.md')) fail('PROPOSAL_INVALID', 'create requires SKILL.md');
-    } else if (!targetState.exists) fail('TARGET_NOT_AGENT_OWNED', record.targetSkill);
-  } else {
-    if (Object.hasOwn(record, 'patch') || Object.hasOwn(record, 'createSpec')) fail('PROPOSAL_INVALID');
-    if (['pending', 'approved'].includes(record.status) && !targetState.exists) fail('TARGET_NOT_AGENT_OWNED', record.targetSkill);
-  }
-  assertNoSecret(record);
-  return { ...record, targetRoot };
-}
-
-function proposalDirectory(context) {
-  return ensureBelow(context.stateRoot, ['skill-proposals']);
-}
-
-function proposalPath(context, id) {
-  if (!ID_PATTERN.test(id)) fail('PROPOSAL_ID_INVALID');
-  return join(proposalDirectory(context), `${id}.json`);
-}
-
-function loadProposal(context, id) {
-  const path = proposalPath(context, id);
-  if (!existsSync(path)) fail('PROPOSAL_NOT_FOUND', id);
-  return validateProposal(readJson(path, 'PROPOSAL_INVALID'), { context });
-}
-
-export function queueProposalBatch(records, options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  if (!Array.isArray(records) || records.length < 1 || records.length > 3) fail('PROPOSAL_BATCH_INVALID');
-  return withStateLock(globalLock(context), () => {
-    const validated = records.map((record) => validateProposal(record, { context, queue: true }));
-    if (new Set(validated.map((record) => record.id)).size !== validated.length) fail('PROPOSAL_ALREADY_EXISTS');
-    for (const record of validated) if (existsSync(proposalPath(context, record.id))) fail('PROPOSAL_ALREADY_EXISTS', record.id);
-    for (const record of validated) atomicJson(proposalPath(context, record.id), record);
-    return validated;
-  });
-}
-
-export function queueProposal(record, options = {}) {
-  return queueProposalBatch([record], options)[0];
-}
-
-export function listProposals(options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  const directory = proposalDirectory(context);
-  const proposals = [];
-  for (const entry of readdirSync(directory, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
-    proposals.push(validateProposal(readJson(join(directory, entry.name), 'PROPOSAL_INVALID'), { context }));
-    if (proposals.length > MAX_PROPOSALS) fail('PROPOSAL_STORE_TOO_LARGE');
-  }
-  return proposals.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
-}
-
-function canonicalFileIdentity(file) {
-  validateRelativeFile(file, '__target__');
-  return portableIdentity(file);
-}
-
-function regularFiles(root) {
-  if (!existsSync(root)) return [];
-  const output = [];
-  function visit(directory, prefix = '') {
-    const status = lstatSync(directory);
-    if (!status.isDirectory() || status.isSymbolicLink()) fail('TARGET_PATH_UNSAFE', directory);
-    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
-      const path = join(directory, entry.name);
-      const file = prefix ? `${prefix}/${entry.name}` : entry.name;
-      const childStatus = lstatSync(path);
-      if (childStatus.isSymbolicLink()) fail('TARGET_PATH_UNSAFE', file);
-      if (childStatus.isDirectory()) visit(path, file);
-      else if (childStatus.isFile()) output.push({ file, path, size: childStatus.size });
-      else fail('TARGET_PATH_UNSAFE', file);
-      if (output.length > MAX_SKILL_FILES) fail('TARGET_TOO_LARGE');
-    }
-  }
-  visit(root);
-  const identities = new Set();
-  let bytes = 0;
-  for (const item of output) {
-    if (item.size > MAX_FILE_BYTES) fail('TARGET_TOO_LARGE', item.file);
-    bytes += item.size;
-    if (bytes > MAX_SNAPSHOT_BYTES) fail('TARGET_TOO_LARGE');
-    const identity = canonicalFileIdentity(item.file);
-    if (identities.has(identity)) fail('TARGET_PATH_COLLISION', item.file);
-    identities.add(identity);
-  }
-  return output;
-}
-
-function blobDirectory(context) {
-  return ensureBelow(context.stateRoot, ['skill-ledger-blobs']);
-}
-
-function persistBlob(context, bytes) {
-  const digest = createHash('sha256').update(bytes).digest('hex');
-  const path = join(blobDirectory(context), digest);
-  if (existsSync(path)) {
-    const existing = readBytes(path, MAX_FILE_BYTES);
-    if (createHash('sha256').update(existing).digest('hex') !== digest) fail('BLOB_CORRUPT', digest);
-  } else {
-    atomicWrite(path, bytes);
-  }
-  return { algorithm: 'sha256', digest, size: bytes.length };
-}
-
-export function captureSnapshot(context, root) {
-  assertLearningLoopSupported();
-  return regularFiles(root).map(({ file, path }) => ({ file, blob: persistBlob(context, readBytes(path, MAX_FILE_BYTES)) }));
-}
-
-function snapshotsEqual(left, right) {
-  return JSON.stringify(left) === JSON.stringify(right);
-}
-
-function jsonEqual(left, right) {
-  return JSON.stringify(left) === JSON.stringify(right);
-}
-
-function jsonClone(value) {
-  return value === null || value === undefined ? value : JSON.parse(JSON.stringify(value));
-}
-
-function ledgerPath(context) {
-  return join(context.stateRoot, 'skill-ledger.jsonl');
-}
-
-function validateSnapshot(context, snapshot, code = 'LEDGER_INVALID') {
-  if (!Array.isArray(snapshot) || snapshot.length > MAX_SKILL_FILES) fail(code);
-  const identities = new Set();
-  let total = 0;
-  for (const item of snapshot) {
-    requireExactKeys(item, ['file', 'blob'], ['file', 'blob'], code);
-    validateRelativeFile(item.file, '__target__');
-    const identity = portableIdentity(item.file);
-    if (identities.has(identity)) fail(code, 'duplicate snapshot path');
-    identities.add(identity);
-    requireExactKeys(item.blob, ['algorithm', 'digest', 'size'], ['algorithm', 'digest', 'size'], code);
-    if (item.blob.algorithm !== 'sha256' || !/^[a-f0-9]{64}$/.test(item.blob.digest) || !Number.isSafeInteger(item.blob.size) || item.blob.size < 0) fail(code);
-    total += item.blob.size;
-    if (item.blob.size > MAX_FILE_BYTES || total > MAX_SNAPSHOT_BYTES) fail(code);
-    const blob = join(blobDirectory(context), item.blob.digest);
-    if (!existsSync(blob)) fail('BLOB_MISSING', item.blob.digest);
-    const bytes = readBytes(blob, MAX_FILE_BYTES);
-    if (bytes.length !== item.blob.size || createHash('sha256').update(bytes).digest('hex') !== item.blob.digest) fail('BLOB_CORRUPT', item.blob.digest);
-  }
-}
-
-function validateLedgerEntry(context, entry) {
-  const allowed = ['schema', 'id', 'createdAt', 'proposalId', 'actor', 'operation', 'targetSkill', 'targetRoot', 'before', 'after', 'usageBefore', 'usageAfter', 'restoresLedgerEntryId', 'reason'];
-  const required = ['schema', 'id', 'createdAt', 'proposalId', 'actor', 'operation', 'targetSkill', 'targetRoot', 'before', 'after'];
-  requireExactKeys(entry, allowed, required, 'LEDGER_INVALID');
-  if (entry.schema !== LEDGER_SCHEMA || !ID_PATTERN.test(entry.id ?? '')) fail('LEDGER_INVALID');
-  requireTimestamp(entry.createdAt, 'LEDGER_INVALID');
-  validateSkillName(entry.targetSkill, 'LEDGER_INVALID');
-  canonicalTargetRoot(context, entry.targetRoot);
-  if (!['user', 'curator'].includes(entry.actor) || !['apply', 'reject', 'rollback', 'curator-transition'].includes(entry.operation)) fail('LEDGER_INVALID');
-  if (entry.operation === 'curator-transition') {
-    if (entry.actor !== 'curator' || entry.proposalId !== null) fail('LEDGER_INVALID');
-  } else {
-    if (entry.actor !== 'user') fail('LEDGER_INVALID');
-    if (entry.proposalId !== null && !ID_PATTERN.test(entry.proposalId ?? '')) fail('LEDGER_INVALID');
-    if (['apply', 'reject'].includes(entry.operation) && !ID_PATTERN.test(entry.proposalId ?? '')) fail('LEDGER_INVALID');
-  }
-  if (entry.operation === 'rollback') {
-    if (!ID_PATTERN.test(entry.restoresLedgerEntryId ?? '')) fail('LEDGER_INVALID');
-  } else if (Object.hasOwn(entry, 'restoresLedgerEntryId')) fail('LEDGER_INVALID');
-  if (Object.hasOwn(entry, 'reason') && (typeof entry.reason !== 'string' || entry.reason.length > 8192)) fail('LEDGER_INVALID');
-  validateSnapshot(context, entry.before);
-  validateSnapshot(context, entry.after);
-  if (Object.hasOwn(entry, 'usageBefore') || Object.hasOwn(entry, 'usageAfter')) {
-    if (!Object.hasOwn(entry, 'usageBefore') || !Object.hasOwn(entry, 'usageAfter')) fail('LEDGER_INVALID', 'incomplete usage transition');
-    validateUsageEntry(entry.usageBefore, 'LEDGER_INVALID');
-    validateUsageEntry(entry.usageAfter, 'LEDGER_INVALID');
-  }
-  return entry;
-}
-
-export function readLedger(context) {
-  assertLearningLoopSupported();
-  const path = ledgerPath(context);
-  if (!existsSync(path)) return [];
-  const status = lstatSync(path);
-  if (!status.isFile() || status.isSymbolicLink() || status.size > 8 * 1024 * 1024) fail('LEDGER_UNSAFE');
-  const entries = [];
-  for (const line of readText(path, 8 * 1024 * 1024).split(/\r?\n/).filter(Boolean)) {
-    let entry;
-    try { entry = JSON.parse(line); } catch { fail('LEDGER_INVALID'); }
-    entries.push(validateLedgerEntry(context, entry));
-  }
-  if (new Set(entries.map((entry) => entry.id)).size !== entries.length) fail('LEDGER_INVALID', 'duplicate id');
-  const prior = new Map();
-  for (const entry of entries) {
-    if (entry.operation === 'rollback') {
-      const source = prior.get(entry.restoresLedgerEntryId);
-      if (!source || !['apply', 'curator-transition', 'rollback'].includes(source.operation)) fail('LEDGER_INVALID', 'rollback reference');
-      if (source.targetSkill !== entry.targetSkill || source.targetRoot !== entry.targetRoot) fail('LEDGER_INVALID', 'rollback target');
-    }
-    prior.set(entry.id, entry);
-  }
-  return entries;
-}
-
-export function appendLedger(context, entry) {
-  assertLearningLoopSupported();
-  const existing = readLedger(context);
-  if (existing.some((item) => item.id === entry.id)) fail('LEDGER_INVALID', 'duplicate id');
-  const path = ledgerPath(context);
-  const prefix = existsSync(path) ? readText(path, 8 * 1024 * 1024) : '';
-  const normalized = prefix.length === 0 || prefix.endsWith('\n') ? prefix : `${prefix}\n`;
-  const bytes = `${normalized}${JSON.stringify(entry)}\n`;
-  if (Buffer.byteLength(bytes) > 8 * 1024 * 1024) fail('LEDGER_UNSAFE', 'size');
-  atomicWrite(path, bytes);
-  return entry;
-}
-
-function appendLedgerIdempotent(context, entry) {
-  const existing = readLedger(context).find((item) => item.id === entry.id);
-  if (existing) {
-    if (!jsonEqual(existing, entry)) fail('LEDGER_INVALID', 'id collision');
-    return existing;
-  }
-  return appendLedger(context, entry);
-}
-
-function newLedgerEntry({ actor, after, before, createdAt, operation, proposalId, reason, restoresLedgerEntryId, targetRoot, targetSkill, usageAfter, usageBefore }) {
-  const entry = {
-    schema: LEDGER_SCHEMA,
-    id: `ledger-${randomUUID()}`,
-    createdAt: createdAt ?? new Date().toISOString(),
-    proposalId,
-    actor,
-    operation,
-    targetSkill,
-    targetRoot,
-    before,
-    after,
-  };
-  if (usageBefore !== undefined || usageAfter !== undefined) {
-    entry.usageBefore = jsonClone(usageBefore ?? null);
-    entry.usageAfter = jsonClone(usageAfter ?? null);
-  }
-  if (restoresLedgerEntryId) entry.restoresLedgerEntryId = restoresLedgerEntryId;
-  if (reason) entry.reason = reason;
-  return entry;
-}
-
-function copyTree(source, destination) {
-  safeMkdir(destination);
-  for (const item of regularFiles(source)) {
-    const target = join(destination, ...item.file.split('/'));
-    safeMkdir(dirname(target));
-    copyFileSync(item.path, target, constants.COPYFILE_EXCL);
-    if (item.file.startsWith('scripts/')) chmodSync(target, 0o755);
-  }
-}
-
-function materializeSnapshot(context, snapshot, destination) {
-  safeMkdir(destination);
-  for (const item of snapshot) {
-    validateRelativeFile(item.file, '__target__');
-    const blob = join(blobDirectory(context), item.blob.digest);
-    const bytes = readBytes(blob, MAX_FILE_BYTES);
-    if (bytes.length !== item.blob.size || createHash('sha256').update(bytes).digest('hex') !== item.blob.digest) fail('BLOB_CORRUPT', item.blob.digest);
-    const target = join(destination, ...item.file.split('/'));
-    safeMkdir(dirname(target));
-    writeFileSync(target, bytes, { flag: 'wx', mode: item.file.startsWith('scripts/') ? 0o755 : 0o600 });
-  }
-}
-
-function stampMarker(content, targetSkill) {
-  if (markerPresent(content)) return content;
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
-  if (!match) fail('SKILL_FRONTMATTER_INVALID');
-  const declared = match[1].match(/^name:\s*(["']?)([^\n"']+)\1\s*$/m)?.[2]?.trim();
-  if (declared !== targetSkill) fail('SKILL_FRONTMATTER_INVALID', 'name mismatch');
-  if (/^metadata:/m.test(match[1])) fail('SKILL_FRONTMATTER_INVALID', 'metadata must be an inline string map');
-  const replacement = `---\n${match[1]}\n${MARKER}\n---\n`;
-  return `${replacement}${content.slice(match[0].length)}`;
-}
-
-function applyProposalToStage(record, stage) {
-  if (record.action === 'patch') {
-    const path = join(stage, ...record.patch.file.split('/'));
-    if (!existsSync(path)) fail('PATCH_PREIMAGE_MISMATCH');
-    const status = lstatSync(path);
-    if (!status.isFile() || status.isSymbolicLink()) fail('TARGET_PATH_UNSAFE');
-    const mode = status.mode & 0o777;
-    const content = readText(path, MAX_FILE_BYTES);
-    const first = content.indexOf(record.patch.oldString);
-    if (first < 0 || content.indexOf(record.patch.oldString, first + record.patch.oldString.length) >= 0) fail('PATCH_PREIMAGE_MISMATCH');
-    atomicWrite(path, content.slice(0, first) + record.patch.newString + content.slice(first + record.patch.oldString.length));
-    chmodSync(path, mode);
-  } else if (record.action === 'create' || record.action === 'add-reference') {
-    for (const item of record.createSpec.files) {
-      const path = join(stage, ...item.file.split('/'));
-      if (existsSync(path)) fail('TARGET_ALREADY_EXISTS', item.file);
-      safeMkdir(dirname(path));
-      const content = portableIdentity(item.file) === 'skill.md' ? stampMarker(item.content, record.targetSkill) : item.content;
-      atomicWrite(path, content, item.file.startsWith('scripts/') ? 0o755 : 0o600);
-      if (item.file.startsWith('scripts/')) chmodSync(path, 0o755);
-    }
-  } else {
-    fail('ARCHIVE_REQUIRES_CURATOR');
-  }
-  const skillFile = join(stage, 'SKILL.md');
-  if (!existsSync(skillFile) || !markerPresent(readText(skillFile, MAX_FILE_BYTES))) fail('TARGET_NOT_AGENT_OWNED');
-}
-
-function temporaryDirectory(context, label) {
-  const root = ensureBelow(context.grokRoot, ['litgrok', 'staging']);
-  const path = join(root, `${label}-${randomUUID()}`);
-  safeMkdir(path);
-  return path;
-}
-
-function transactionDirectory(context) {
-  return ensureBelow(context.stateRoot, ['skill-transactions']);
-}
-
-function transactionPath(context, id) {
-  if (!ID_PATTERN.test(id)) fail('TRANSACTION_INVALID', 'id');
-  return join(transactionDirectory(context), `${id}.json`);
-}
-
-function transactionScratch(context, id) {
-  if (!ID_PATTERN.test(id)) fail('TRANSACTION_INVALID', 'id');
-  return join(context.grokRoot, 'litgrok', 'transactions', id);
-}
-
-function transactionAuthorityPath(context, id) {
-  return join(transactionScratch(context, id), 'authority.json');
-}
-
-function transactionCompletionPath(context, id) {
-  if (!ID_PATTERN.test(id)) fail('TRANSACTION_INVALID', 'id');
-  return join(transactionDirectory(context), `${id}.complete`);
-}
-
-function transactionDigest(transaction) {
-  return createHash('sha256').update(JSON.stringify(transaction)).digest('hex');
-}
-
-function approvedTransactionAction(transaction) {
-  if (['apply', 'archive', 'reject'].includes(transaction.kind)) {
-    return `${transaction.kind}:${transaction.proposalBefore?.id ?? 'missing'}:${transaction.proposalBefore?.action ?? 'missing'}`;
-  }
-  if (transaction.kind === 'rollback') return `rollback:${transaction.ledger.restoresLedgerEntryId ?? 'missing'}`;
-  return transaction.kind;
-}
-
-function transactionReceipt(context, transaction, schema) {
-  return {
-    schema,
-    transactionId: transaction.id,
-    transactionDigest: transactionDigest(transaction),
-    workspaceRoot: realpathSync(context.workspaceRoot),
-    stateRoot: realpathSync(context.stateRoot),
-    targetSkill: transaction.targetSkill,
-    targetIdentity: portableIdentity(transaction.targetSkill),
-    targetRoot: transaction.targetRoot,
-    proposalId: transaction.proposalBefore?.id ?? null,
-    proposalAction: transaction.proposalBefore?.action ?? transaction.kind,
-    approvedAction: approvedTransactionAction(transaction),
-    createdAt: transaction.createdAt,
-  };
-}
-
-function transactionAuthority(context, transaction) {
-  return transactionReceipt(context, transaction, TRANSACTION_AUTHORITY_SCHEMA);
-}
-
-function transactionCompletion(context, transaction) {
-  return transactionReceipt(context, transaction, TRANSACTION_COMPLETION_SCHEMA);
-}
-
-const TRANSACTION_RECEIPT_FIELDS = [
-  'schema', 'transactionId', 'transactionDigest', 'workspaceRoot', 'stateRoot', 'targetSkill',
-  'targetIdentity', 'targetRoot', 'proposalId', 'proposalAction', 'approvedAction', 'createdAt',
-];
-
-function authorityDirectoryChain(context, transaction) {
-  const expectedGrokRoot = join(context.home, '.grok');
-  if (resolve(context.grokRoot) !== expectedGrokRoot) fail('TRANSACTION_AUTHORITY_PATH_UNTRUSTED', 'grok root');
-  return [
-    { path: context.home, private: false },
-    { path: context.grokRoot, private: false },
-    { path: join(context.grokRoot, 'litgrok'), private: true },
-    { path: join(context.grokRoot, 'litgrok', 'transactions'), private: true },
-    { path: transactionScratch(context, transaction.id), private: true },
-  ];
-}
-
-function validateAuthorityDirectoryChain(context, transaction) {
-  assertLearningLoopSupported();
-  const ownerToken = posixOwnerToken();
-  const ownerUid = Number(ownerToken.slice(4));
-  for (const item of authorityDirectoryChain(context, transaction)) {
-    let status;
-    try {
-      status = lstatSync(item.path);
-    } catch {
-      fail('TRANSACTION_AUTHORITY_PATH_UNTRUSTED', item.path);
-    }
-    const mode = status.mode & 0o7777;
-    let canonical;
-    try {
-      canonical = realpathSync(item.path);
-    } catch {
-      fail('TRANSACTION_AUTHORITY_PATH_UNTRUSTED', item.path);
-    }
-    if (!status.isDirectory() || status.isSymbolicLink() || canonical !== resolve(item.path) || status.uid !== ownerUid) {
-      fail('TRANSACTION_AUTHORITY_PATH_UNTRUSTED', item.path);
-    }
-    if ((item.private && mode !== 0o700) || (!item.private && (mode & 0o022) !== 0)) {
-      fail('TRANSACTION_AUTHORITY_PATH_UNTRUSTED', item.path);
-    }
-  }
-  return ownerToken;
-}
-
-function readTrustedAuthority(context, transaction) {
-  const ownerToken = validateAuthorityDirectoryChain(context, transaction);
-  const path = transactionAuthorityPath(context, transaction.id);
-  const ownerUid = Number(ownerToken.slice(4));
-  let expected;
-  try {
-    expected = lstatSync(path);
-  } catch {
-    fail('TRANSACTION_AUTHORITY_FILE_UNTRUSTED', path);
-  }
-  if (!expected.isFile() || expected.isSymbolicLink() || expected.uid !== ownerUid
-    || (expected.mode & 0o7777) !== 0o600 || expected.nlink !== 1 || expected.size > MAX_JSON_BYTES) {
-    fail('TRANSACTION_AUTHORITY_FILE_UNTRUSTED', path);
-  }
-  let descriptor;
-  try {
-    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    const opened = fstatSync(descriptor);
-    if (!opened.isFile() || opened.uid !== ownerUid || (opened.mode & 0o7777) !== 0o600 || opened.nlink !== 1
-      || opened.size > MAX_JSON_BYTES || opened.dev !== expected.dev || opened.ino !== expected.ino) {
-      fail('TRANSACTION_AUTHORITY_FILE_UNTRUSTED', path);
-    }
-    const bytes = readFileSync(descriptor);
-    const current = lstatSync(path);
-    if (!current.isFile() || current.isSymbolicLink() || current.dev !== opened.dev || current.ino !== opened.ino
-      || current.uid !== ownerUid || (current.mode & 0o7777) !== 0o600 || current.nlink !== 1
-      || bytes.length !== opened.size) fail('TRANSACTION_AUTHORITY_FILE_UNTRUSTED', path);
-    try {
-      return JSON.parse(decoder.decode(bytes));
-    } catch {
-      fail('TRANSACTION_AUTHORITY_INVALID', path);
-    }
-  } catch (error) {
-    if (error instanceof SkillLoopError) throw error;
-    fail('TRANSACTION_AUTHORITY_FILE_UNTRUSTED', path);
-  } finally {
-    if (descriptor !== undefined) closeSync(descriptor);
-  }
-}
-
-function validateTransactionAuthority(context, transaction) {
-  const scratch = transactionScratch(context, transaction.id);
-  const path = transactionAuthorityPath(context, transaction.id);
-  if (!existsSync(scratch) || !existsSync(path)) fail('TRANSACTION_AUTHORITY_MISSING', transaction.id);
-  const authority = readTrustedAuthority(context, transaction);
-  requireExactKeys(
-    authority,
-    TRANSACTION_RECEIPT_FIELDS,
-    TRANSACTION_RECEIPT_FIELDS,
-    'TRANSACTION_AUTHORITY_INVALID',
-  );
-  requireTimestamp(authority.createdAt, 'TRANSACTION_AUTHORITY_INVALID');
-  const expected = transactionAuthority(context, transaction);
-  if (!jsonEqual(authority, expected)) fail('TRANSACTION_AUTHORITY_MISMATCH', transaction.id);
-  return authority;
-}
-
-function validateTransactionCompletion(context, transaction) {
-  const path = transactionCompletionPath(context, transaction.id);
-  if (!existsSync(path)) return null;
-  const completion = readJson(path, 'TRANSACTION_COMPLETION_INVALID');
-  requireExactKeys(completion, TRANSACTION_RECEIPT_FIELDS, TRANSACTION_RECEIPT_FIELDS, 'TRANSACTION_COMPLETION_INVALID');
-  requireTimestamp(completion.createdAt, 'TRANSACTION_COMPLETION_INVALID');
-  if (!jsonEqual(completion, transactionCompletion(context, transaction))) fail('TRANSACTION_COMPLETION_MISMATCH', transaction.id);
-  return completion;
-}
-
-function removeOwnedTree(path) {
-  if (!existsSync(path)) return;
-  const status = lstatSync(path);
-  if (!status.isDirectory() || status.isSymbolicLink()) fail('TRANSACTION_PATH_UNSAFE', path);
-  rmSync(path, { recursive: true, force: true });
-  syncDirectory(dirname(path));
-}
-
-function validateTransaction(context, transaction) {
-  const allowed = [
-    'schema', 'id', 'createdAt', 'kind', 'targetSkill', 'targetRoot', 'before', 'after',
-    'ledger', 'proposalBefore', 'proposalAfter', 'usageBefore', 'usageAfter', 'archivePath',
-  ];
-  requireExactKeys(transaction, allowed, allowed, 'TRANSACTION_INVALID');
-  if (transaction.schema !== TRANSACTION_SCHEMA || !ID_PATTERN.test(transaction.id ?? '')) fail('TRANSACTION_INVALID');
-  requireTimestamp(transaction.createdAt, 'TRANSACTION_INVALID');
-  if (!['apply', 'archive', 'reject', 'rollback', 'curator-stale', 'curator-archive'].includes(transaction.kind)) fail('TRANSACTION_INVALID', 'kind');
-  validateSkillName(transaction.targetSkill, 'TRANSACTION_INVALID');
-  canonicalTargetRoot(context, transaction.targetRoot);
-  validateSnapshot(context, transaction.before, 'TRANSACTION_INVALID');
-  validateSnapshot(context, transaction.after, 'TRANSACTION_INVALID');
-  validateLedgerEntry(context, transaction.ledger);
-  validateUsageEntry(transaction.usageBefore, 'TRANSACTION_INVALID');
-  validateUsageEntry(transaction.usageAfter, 'TRANSACTION_INVALID');
-  if (!jsonEqual(transaction.ledger.usageBefore, transaction.usageBefore) || !jsonEqual(transaction.ledger.usageAfter, transaction.usageAfter)) {
-    fail('TRANSACTION_INVALID', 'usage mismatch');
-  }
-  if (!jsonEqual(transaction.ledger.before, transaction.before) || !jsonEqual(transaction.ledger.after, transaction.after)) {
-    fail('TRANSACTION_INVALID', 'snapshot mismatch');
-  }
-  if (transaction.ledger.targetSkill !== transaction.targetSkill || transaction.ledger.targetRoot !== transaction.targetRoot) {
-    fail('TRANSACTION_INVALID', 'ledger target');
-  }
-  const hasProposal = transaction.proposalBefore !== null || transaction.proposalAfter !== null;
-  if (hasProposal) {
-    const before = requireObject(transaction.proposalBefore, 'TRANSACTION_INVALID');
-    const after = requireObject(transaction.proposalAfter, 'TRANSACTION_INVALID');
-    if (before.id !== transaction.ledger.proposalId || after.id !== before.id || before.targetSkill !== transaction.targetSkill || after.targetSkill !== transaction.targetSkill) {
-      fail('TRANSACTION_INVALID', 'proposal target');
-    }
-    if (!['pending', 'approved', 'applied', 'rolled-back'].includes(before.status) || !['applied', 'rejected', 'rolled-back'].includes(after.status)) fail('TRANSACTION_INVALID', 'proposal status');
-    if (after.status === 'rejected') {
-      if (Object.hasOwn(after, 'ledgerEntryId')) fail('TRANSACTION_INVALID', 'rejected proposal ledger field');
-    } else if (after.ledgerEntryId !== transaction.ledger.id) fail('TRANSACTION_INVALID', 'proposal ledger');
-  } else if (transaction.proposalBefore !== null || transaction.proposalAfter !== null || transaction.ledger.proposalId !== null) {
-    fail('TRANSACTION_INVALID', 'proposal fields');
-  }
-  const archiveKind = ['archive', 'curator-archive'].includes(transaction.kind);
-  if (archiveKind) {
-    requireString(transaction.archivePath, 'TRANSACTION_INVALID', 4096);
-    const archiveRoot = resolve(context.grokRoot, 'litgrok', 'archive');
-    const resolvedArchive = resolve(transaction.archivePath);
-    const fromRoot = relative(archiveRoot, resolvedArchive);
-    if (!fromRoot || fromRoot.startsWith(`..${sep}`) || fromRoot === '..' || isAbsolute(fromRoot)) fail('TRANSACTION_INVALID', 'archive path');
-  } else if (transaction.archivePath !== null) fail('TRANSACTION_INVALID', 'archive path forbidden');
-  return transaction;
-}
-
-function validateSnapshotOwnership(context, snapshot, targetSkill) {
-  if (snapshot.length === 0) return;
-  const skillFile = snapshot.find((item) => portableIdentity(item.file) === 'skill.md');
-  if (!skillFile) fail('TRANSACTION_OWNERSHIP_INVALID', 'SKILL.md missing');
-  const content = readText(join(blobDirectory(context), skillFile.blob.digest), MAX_FILE_BYTES);
-  if (!markerPresent(content)) fail('TRANSACTION_OWNERSHIP_INVALID', targetSkill);
-  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
-  const declared = frontmatter?.match(/^name:\s*(["']?)([^\n"']+)\1\s*$/m)?.[2]?.trim();
-  if (declared !== targetSkill) fail('TRANSACTION_TARGET_IDENTITY_MISMATCH', targetSkill);
-}
-
-function validateProposalTransition(context, transaction, beforeStatuses, afterStatus) {
-  const before = requireObject(transaction.proposalBefore, 'TRANSACTION_AUTHORITY_INVALID');
-  const after = requireObject(transaction.proposalAfter, 'TRANSACTION_AUTHORITY_INVALID');
-  if (!beforeStatuses.includes(before.status) || after.status !== afterStatus) fail('TRANSACTION_AUTHORITY_INVALID', 'proposal status');
-  const path = proposalPath(context, before.id);
-  if (!existsSync(path)) fail('TRANSACTION_PROPOSAL_MISSING', before.id);
-  const current = readJson(path, 'PROPOSAL_INVALID');
-  if (!jsonEqual(current, before) && !jsonEqual(current, after)) fail('TRANSACTION_PROPOSAL_CAS_MISMATCH', before.id);
-  return { after, before };
-}
-
-function validateUsagePinInvariant(transaction) {
-  const before = transaction.usageBefore;
-  const after = transaction.usageAfter;
-  if (before !== null && after !== null && before.pinned !== after.pinned) fail('TRANSACTION_PIN_INVARIANT');
-  if (before === null && after !== null && after.pinned !== false) fail('TRANSACTION_PIN_INVARIANT');
-}
-
-function validateApplyTransaction(context, transaction) {
-  const { before: proposal } = validateProposalTransition(context, transaction, ['approved'], 'applied');
-  if (transaction.ledger.operation !== 'apply' || transaction.ledger.actor !== 'user') fail('TRANSACTION_AUTHORITY_INVALID', 'apply ledger');
-  if (transaction.kind === 'archive') {
-    if (proposal.action !== 'archive' || transaction.before.length === 0 || transaction.after.length !== 0) fail('TRANSACTION_AUTHORITY_INVALID', 'archive action');
-    const expectedUsage = jsonClone(transaction.usageBefore);
-    if (expectedUsage !== null) {
-      expectedUsage.state = 'archived';
-      expectedUsage.archived_at = transaction.ledger.createdAt;
-    }
-    if (!jsonEqual(expectedUsage, transaction.usageAfter)) fail('TRANSACTION_AUTHORITY_INVALID', 'archive usage');
-    return;
-  }
-  if (!['patch', 'create', 'add-reference'].includes(proposal.action)) fail('TRANSACTION_AUTHORITY_INVALID', 'apply action');
-  if (proposal.action === 'create' && transaction.before.length !== 0) fail('TRANSACTION_AUTHORITY_INVALID', 'create preimage');
-  if (proposal.action !== 'create' && transaction.before.length === 0) fail('TRANSACTION_AUTHORITY_INVALID', 'owned preimage');
-  if (transaction.after.length === 0) fail('TRANSACTION_AUTHORITY_INVALID', 'apply result');
-  const expectedUsage = usageAfterApply(transaction.usageBefore, transaction.ledger.createdAt);
-  if (!jsonEqual(expectedUsage, transaction.usageAfter)) fail('TRANSACTION_AUTHORITY_INVALID', 'apply usage');
-}
-
-function expectedAppliedSnapshot(context, proposal, before) {
-  const stage = temporaryDirectory(context, 'verify-applied');
-  try {
-    if (before.length > 0) materializeSnapshot(context, before, stage);
-    applyProposalToStage(proposal, stage);
-    return captureSnapshot(context, stage);
-  } finally {
-    if (existsSync(stage)) rmSync(stage, { recursive: true, force: true });
-  }
-}
-
-function resolveAppliedLedger(context, proposal) {
-  if (proposal.status !== 'applied' || !ID_PATTERN.test(proposal.ledgerEntryId ?? '')) fail('PROPOSAL_INVALID', 'applied decision shape');
-  const ledger = readLedger(context).find((entry) => entry.id === proposal.ledgerEntryId);
-  if (!ledger) fail('APPLIED_LEDGER_UNRESOLVED', proposal.id);
-  if (ledger.operation !== 'apply' || ledger.actor !== 'user' || ledger.proposalId !== proposal.id
-    || ledger.targetSkill !== proposal.targetSkill || ledger.targetRoot !== proposal.targetRoot
-    || !Object.hasOwn(ledger, 'usageBefore') || !Object.hasOwn(ledger, 'usageAfter')
-    || Date.parse(ledger.createdAt) < Date.parse(proposal.createdAt)) {
-    fail('APPLIED_LEDGER_MISMATCH', proposal.id);
-  }
-  validateUsagePinInvariant({ usageBefore: ledger.usageBefore, usageAfter: ledger.usageAfter });
-  const target = join(context.userRoot, proposal.targetSkill);
-  if (proposal.action === 'archive') {
-    if (ledger.before.length === 0 || ledger.after.length !== 0) fail('APPLIED_LEDGER_MISMATCH', 'archive shape');
-    if (pathEntryExists(target)) fail('APPLIED_STATE_MISMATCH', 'archived target');
-    validateSnapshotOwnership(context, ledger.before, proposal.targetSkill);
-    const expectedUsage = jsonClone(ledger.usageBefore);
-    if (expectedUsage !== null) {
-      expectedUsage.state = 'archived';
-      expectedUsage.archived_at = ledger.createdAt;
-    }
-    if (!jsonEqual(expectedUsage, ledger.usageAfter)) fail('APPLIED_LEDGER_MISMATCH', 'archive usage');
-    const archive = join(context.grokRoot, 'litgrok', 'archive', `${proposal.targetSkill}-${ledger.id}`);
-    if (!existsSync(archive) || !snapshotsEqual(captureSnapshot(context, archive), ledger.before)) {
-      fail('APPLIED_STATE_MISMATCH', 'archive');
-    }
-  } else {
-    if ((proposal.action === 'create' && ledger.before.length !== 0)
-      || (proposal.action !== 'create' && ledger.before.length === 0) || ledger.after.length === 0) {
-      fail('APPLIED_LEDGER_MISMATCH', 'action shape');
-    }
-    validateSnapshotOwnership(context, ledger.before, proposal.targetSkill);
-    validateSnapshotOwnership(context, ledger.after, proposal.targetSkill);
-    let expectedAfter;
-    try {
-      expectedAfter = expectedAppliedSnapshot(context, proposal, ledger.before);
-    } catch (error) {
-      if (error instanceof SkillLoopError && ['BLOB_MISSING', 'BLOB_CORRUPT'].includes(error.code)) throw error;
-      fail('APPLIED_LEDGER_MISMATCH', 'action replay');
-    }
-    if (!snapshotsEqual(expectedAfter, ledger.after)) fail('APPLIED_LEDGER_MISMATCH', 'action result');
-    const expectedUsage = usageAfterApply(ledger.usageBefore, ledger.createdAt);
-    if (!jsonEqual(expectedUsage, ledger.usageAfter)) fail('APPLIED_LEDGER_MISMATCH', 'apply usage');
-    if (!snapshotsEqual(captureSnapshot(context, target), ledger.after)) fail('APPLIED_STATE_MISMATCH', 'target');
-  }
-  const terminalUsage = readUsage(context).skills[proposal.targetSkill] ?? null;
-  if (!jsonEqual(terminalUsage, ledger.usageAfter)) fail('APPLIED_STATE_MISMATCH', 'usage');
-  return ledger;
-}
-
-function resolveRejectDecisionLedger(context, proposal) {
-  if (proposal.status !== 'rejected' || Object.hasOwn(proposal, 'ledgerEntryId')) fail('PROPOSAL_INVALID', 'rejected decision shape');
-  const matches = readLedger(context).filter((entry) => entry.operation === 'reject'
-    && entry.actor === 'user'
-    && entry.proposalId === proposal.id
-    && entry.targetSkill === proposal.targetSkill
-    && entry.targetRoot === proposal.targetRoot
-    && entry.before.length === 0
-    && entry.after.length === 0
-    && (!Object.hasOwn(entry, 'usageBefore') || (entry.usageBefore === null && entry.usageAfter === null))
-    && Date.parse(entry.createdAt) >= Date.parse(proposal.createdAt));
-  if (matches.length !== 1) fail(matches.length === 0 ? 'REJECT_LEDGER_UNRESOLVED' : 'REJECT_LEDGER_AMBIGUOUS', proposal.id);
-  return matches[0];
-}
-
-function validateRejectTransaction(context, transaction) {
-  validateProposalTransition(context, transaction, ['pending'], 'rejected');
-  if (transaction.ledger.operation !== 'reject' || transaction.ledger.actor !== 'user') fail('TRANSACTION_AUTHORITY_INVALID', 'reject ledger');
-  if (transaction.before.length !== 0 || transaction.after.length !== 0 || transaction.usageBefore !== null || transaction.usageAfter !== null) {
-    fail('TRANSACTION_AUTHORITY_INVALID', 'reject mutation');
-  }
-}
-
-function validateRollbackTransaction(context, transaction) {
-  if (transaction.ledger.operation !== 'rollback' || transaction.ledger.actor !== 'user') fail('TRANSACTION_AUTHORITY_INVALID', 'rollback ledger');
-  const entries = readLedger(context);
-  const source = entries.find((entry) => entry.id === transaction.ledger.restoresLedgerEntryId);
-  if (!source || !['apply', 'curator-transition', 'rollback'].includes(source.operation)) fail('TRANSACTION_AUTHORITY_INVALID', 'rollback source');
-  if (source.targetSkill !== transaction.targetSkill || source.targetRoot !== transaction.targetRoot
-    || !jsonEqual(transaction.before, source.after) || !jsonEqual(transaction.after, source.before)
-    || !jsonEqual(transaction.usageBefore, source.usageAfter) || !jsonEqual(transaction.usageAfter, source.usageBefore)) {
-    fail('TRANSACTION_AUTHORITY_INVALID', 'rollback inverse');
-  }
-  if (source.proposalId === null) {
-    if (transaction.proposalBefore !== null || transaction.proposalAfter !== null) fail('TRANSACTION_AUTHORITY_INVALID', 'rollback proposal');
-  } else {
-    validateProposalTransition(context, transaction, ['applied', 'rolled-back'], 'rolled-back');
-  }
-}
-
-function validateCuratorTransaction(transaction) {
-  if (transaction.ledger.operation !== 'curator-transition' || transaction.ledger.actor !== 'curator'
-    || transaction.proposalBefore !== null || transaction.proposalAfter !== null) fail('TRANSACTION_AUTHORITY_INVALID', 'curator ledger');
-  if (transaction.usageBefore === null || transaction.usageAfter === null || transaction.usageBefore.pinned || transaction.usageAfter.pinned) {
-    fail('TRANSACTION_PIN_INVARIANT');
-  }
-  const expectedUsage = jsonClone(transaction.usageBefore);
-  if (transaction.kind === 'curator-stale') {
-    if (transaction.usageBefore.state !== 'active' || !jsonEqual(transaction.before, transaction.after)) fail('TRANSACTION_AUTHORITY_INVALID', 'curator stale source');
-    expectedUsage.state = 'stale';
-    expectedUsage.archived_at = null;
-  } else {
-    if (transaction.usageBefore.state !== 'stale' || transaction.before.length === 0 || transaction.after.length !== 0) fail('TRANSACTION_AUTHORITY_INVALID', 'curator archive source');
-    expectedUsage.state = 'archived';
-    expectedUsage.archived_at = transaction.ledger.createdAt;
-  }
-  if (!jsonEqual(expectedUsage, transaction.usageAfter)) fail('TRANSACTION_AUTHORITY_INVALID', 'curator usage');
-}
-
-function validateTransactionIntent(context, transaction) {
-  if (transaction.kind !== 'reject') {
-    safeTargetDirectory(context, transaction.targetSkill);
-    validateSnapshotOwnership(context, transaction.before, transaction.targetSkill);
-    validateSnapshotOwnership(context, transaction.after, transaction.targetSkill);
-    validateUsagePinInvariant(transaction);
-  }
-  if (['apply', 'archive'].includes(transaction.kind)) validateApplyTransaction(context, transaction);
-  if (transaction.kind === 'reject') validateRejectTransaction(context, transaction);
-  if (transaction.kind === 'rollback') validateRollbackTransaction(context, transaction);
-  if (['curator-stale', 'curator-archive'].includes(transaction.kind)) validateCuratorTransaction(transaction);
-}
-
-function validateAuthorizedTransaction(context, transaction) {
-  validateTransactionAuthority(context, transaction);
-  validateTransactionIntent(context, transaction);
-}
-
-function checkpoint(options, phase, transaction) {
-  if (typeof options.faultInjector === 'function') options.faultInjector(phase, transaction);
-}
-
-function cleanupScratch(context, transaction) {
-  readTrustedAuthority(context, transaction);
-  removeOwnedTree(transactionScratch(context, transaction.id));
-}
-
-function recoverArchiveFilesystem(context, transaction) {
-  const target = join(context.userRoot, transaction.targetSkill);
-  const archive = transaction.archivePath;
-  safeMkdir(dirname(archive));
-  if (existsSync(target)) {
-    if (!snapshotsEqual(captureSnapshot(context, target), transaction.before)) fail('TRANSACTION_CAS_MISMATCH', transaction.targetSkill);
-    if (existsSync(archive)) fail('TRANSACTION_ARCHIVE_CONFLICT', archive);
-    renameSync(target, archive);
-    syncDirectory(context.userRoot);
-    syncDirectory(dirname(archive));
-  }
-  if (!existsSync(archive) || !snapshotsEqual(captureSnapshot(context, archive), transaction.before)) {
-    fail('TRANSACTION_RECOVERY_FAILED', transaction.targetSkill);
-  }
-  if (!snapshotsEqual(captureSnapshot(context, target), transaction.after)) fail('TRANSACTION_RECOVERY_FAILED', transaction.targetSkill);
-}
-
-function recoverSnapshotFilesystem(context, transaction) {
-  const target = join(context.userRoot, transaction.targetSkill);
-  const scratch = transactionScratch(context, transaction.id);
-  const stage = join(scratch, 'stage');
-  const backup = join(scratch, 'backup');
-  const current = captureSnapshot(context, target);
-  if (snapshotsEqual(current, transaction.after)) {
-    if (existsSync(backup)) removeOwnedTree(backup);
-    if (existsSync(stage)) removeOwnedTree(stage);
-    return;
-  }
-  const hasBackup = existsSync(backup);
-  if (!snapshotsEqual(current, transaction.before)) {
-    if (!existsSync(target) && hasBackup && snapshotsEqual(captureSnapshot(context, backup), transaction.before)) {
-      // Resume after the original target was moved to the deterministic backup.
-    } else {
-      fail('TRANSACTION_CAS_MISMATCH', transaction.targetSkill);
-    }
-  }
-  safeMkdir(scratch);
-  if (transaction.after.length > 0) {
-    if (existsSync(stage)) {
-      if (!snapshotsEqual(captureSnapshot(context, stage), transaction.after)) fail('TRANSACTION_STAGE_CORRUPT', transaction.id);
-    } else {
-      materializeSnapshot(context, transaction.after, stage);
-    }
-  }
-  if (existsSync(target)) {
-    if (existsSync(backup)) fail('TRANSACTION_BACKUP_CONFLICT', transaction.id);
-    renameSync(target, backup);
-    syncDirectory(context.userRoot);
-    syncDirectory(scratch);
-  } else if (transaction.before.length > 0 && !existsSync(backup)) {
-    fail('TRANSACTION_RECOVERY_FAILED', transaction.targetSkill);
-  }
-  if (transaction.after.length > 0 && !existsSync(target)) {
-    renameSync(stage, target);
-    syncDirectory(scratch);
-    syncDirectory(context.userRoot);
-  }
-  const restored = captureSnapshot(context, target);
-  if (!snapshotsEqual(restored, transaction.after)) fail('TRANSACTION_RECOVERY_FAILED', transaction.targetSkill);
-  if (existsSync(backup)) removeOwnedTree(backup);
-  if (existsSync(stage)) removeOwnedTree(stage);
-}
-
-function transitionUsage(context, transaction) {
-  const usage = readUsage(context);
-  const current = usage.skills[transaction.targetSkill] ?? null;
-  if (jsonEqual(current, transaction.usageAfter)) return;
-  if (!jsonEqual(current, transaction.usageBefore)) fail('TRANSACTION_USAGE_CAS_MISMATCH', transaction.targetSkill);
-  if (transaction.usageAfter === null) delete usage.skills[transaction.targetSkill];
-  else usage.skills[transaction.targetSkill] = jsonClone(transaction.usageAfter);
-  const updated = Math.max(Date.parse(usage.updatedAt), Date.parse(transaction.ledger.createdAt));
-  usage.updatedAt = new Date(updated).toISOString();
-  writeUsage(context, usage);
-}
-
-function transitionProposal(context, transaction) {
-  if (transaction.proposalBefore === null) return;
-  const path = proposalPath(context, transaction.proposalBefore.id);
-  if (!existsSync(path)) fail('TRANSACTION_PROPOSAL_MISSING', transaction.proposalBefore.id);
-  const current = readJson(path, 'PROPOSAL_INVALID');
-  if (jsonEqual(current, transaction.proposalAfter)) return;
-  if (!jsonEqual(current, transaction.proposalBefore)) fail('TRANSACTION_PROPOSAL_CAS_MISMATCH', transaction.proposalBefore.id);
-  atomicJson(path, transaction.proposalAfter);
-}
-
-function validateCommittedTransactionState(context, transaction) {
-  validateTransactionIntent(context, transaction);
-  if (transaction.kind !== 'reject') {
-    const current = captureSnapshot(context, join(context.userRoot, transaction.targetSkill));
-    if (!snapshotsEqual(current, transaction.after)) fail('TRANSACTION_COMPLETION_STATE_MISMATCH', 'filesystem');
-    if (['archive', 'curator-archive'].includes(transaction.kind)) {
-      if (!existsSync(transaction.archivePath)
-        || !snapshotsEqual(captureSnapshot(context, transaction.archivePath), transaction.before)) {
-        fail('TRANSACTION_COMPLETION_STATE_MISMATCH', 'archive');
-      }
-    }
-    const usage = readUsage(context).skills[transaction.targetSkill] ?? null;
-    if (!jsonEqual(usage, transaction.usageAfter)) fail('TRANSACTION_COMPLETION_STATE_MISMATCH', 'usage');
-  }
-  const ledger = readLedger(context).filter((entry) => entry.id === transaction.ledger.id);
-  if (ledger.length !== 1 || !jsonEqual(ledger[0], transaction.ledger)) fail('TRANSACTION_COMPLETION_STATE_MISMATCH', 'ledger');
-  if (transaction.proposalAfter !== null) {
-    const proposal = readJson(proposalPath(context, transaction.proposalAfter.id), 'PROPOSAL_INVALID');
-    if (!jsonEqual(proposal, transaction.proposalAfter)) fail('TRANSACTION_COMPLETION_STATE_MISMATCH', 'proposal');
-  }
-}
-
-function finalizeProjectTransaction(context, transaction) {
-  const journal = transactionPath(context, transaction.id);
-  const completion = transactionCompletionPath(context, transaction.id);
-  if (existsSync(journal)) unlinkSync(journal);
-  if (existsSync(completion)) unlinkSync(completion);
-  syncDirectory(dirname(journal));
-}
-
-function recoverTransaction(context, transaction, options = {}) {
-  validateTransaction(context, transaction);
-  const completion = validateTransactionCompletion(context, transaction);
-  if (!existsSync(transactionAuthorityPath(context, transaction.id))) {
-    if (completion === null) fail('TRANSACTION_AUTHORITY_MISSING', transaction.id);
-    validateCommittedTransactionState(context, transaction);
-    finalizeProjectTransaction(context, transaction);
-    return transaction;
-  }
-  validateAuthorizedTransaction(context, transaction);
-  if (['archive', 'curator-archive'].includes(transaction.kind)) recoverArchiveFilesystem(context, transaction);
-  else if (transaction.kind !== 'reject') recoverSnapshotFilesystem(context, transaction);
-  checkpoint(options, 'after-filesystem', transaction);
-  if (transaction.kind !== 'reject') transitionUsage(context, transaction);
-  checkpoint(options, 'after-usage', transaction);
-  appendLedgerIdempotent(context, transaction.ledger);
-  checkpoint(options, 'after-ledger', transaction);
-  transitionProposal(context, transaction);
-  checkpoint(options, 'after-proposal', transaction);
-  atomicJson(transactionCompletionPath(context, transaction.id), transactionCompletion(context, transaction));
-  cleanupScratch(context, transaction);
-  checkpoint(options, 'after-authority-cleanup', transaction);
-  finalizeProjectTransaction(context, transaction);
-  return transaction;
-}
-
-export function recoverTransactions(context, options = {}) {
-  assertLearningLoopSupported(options);
-  const directory = transactionDirectory(context);
-  for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
-    if (!entry.name.endsWith('.json')) continue;
-    if (!entry.isFile()) fail('TRANSACTION_INVALID', entry.name);
-    recoverTransaction(context, validateTransaction(context, readJson(join(directory, entry.name), 'TRANSACTION_INVALID')));
-  }
-}
-
-function executeTransaction(context, transaction, options = {}) {
-  validateTransaction(context, transaction);
-  validateTransactionIntent(context, transaction);
-  const path = transactionPath(context, transaction.id);
-  if (existsSync(path)) fail('TRANSACTION_ALREADY_EXISTS', transaction.id);
-  const scratch = transactionScratch(context, transaction.id);
-  if (existsSync(scratch)) fail('TRANSACTION_AUTHORITY_CONFLICT', transaction.id);
-  safeMkdir(scratch);
-  validateAuthorityDirectoryChain(context, transaction);
-  atomicJson(transactionAuthorityPath(context, transaction.id), transactionAuthority(context, transaction));
-  validateTransactionAuthority(context, transaction);
-  try {
-    atomicJson(path, transaction);
-  } catch (error) {
-    cleanupScratch(context, transaction);
-    throw error;
-  }
-  return recoverTransaction(context, transaction, options);
-}
-
-function makeTransaction({ after, archivePath = null, before, kind, ledger, proposalAfter = null, proposalBefore = null, targetRoot, targetSkill, usageAfter, usageBefore }) {
-  return {
-    schema: TRANSACTION_SCHEMA,
-    id: `transaction-${randomUUID()}`,
-    createdAt: new Date().toISOString(),
-    kind,
-    targetSkill,
-    targetRoot,
-    before,
-    after,
-    ledger,
-    proposalBefore,
-    proposalAfter,
-    usageBefore: jsonClone(usageBefore ?? null),
-    usageAfter: jsonClone(usageAfter ?? null),
-    archivePath,
-  };
-}
-
-function usageAfterApply(usageBefore, now) {
-  const entry = jsonClone(usageBefore) ?? {
-    state: 'active', use_count: 0, view_count: 0, patch_count: 0, created_at: now,
-    created_by: 'agent', last_used_at: null, last_viewed_at: null, last_patched_at: null,
-    archived_at: null, pinned: false,
-  };
-  entry.state = 'active';
-  entry.patch_count += 1;
-  entry.last_patched_at = now;
-  entry.archived_at = null;
-  return entry;
-}
-
-function applyArchiveProposal(context, record, proposalBefore, options) {
-  const target = safeTargetDirectory(context, record.targetSkill).target;
-  const before = captureSnapshot(context, target);
-  const usageBefore = jsonClone(readUsage(context).skills[record.targetSkill] ?? null);
-  const createdAt = new Date().toISOString();
-  const usageAfter = jsonClone(usageBefore);
-  if (usageAfter) {
-    usageAfter.state = 'archived';
-    usageAfter.archived_at = createdAt;
-  }
-  const ledger = newLedgerEntry({
-    actor: 'user', createdAt, operation: 'apply', proposalId: record.id, targetSkill: record.targetSkill,
-    targetRoot: record.targetRoot, before, after: [], reason: 'approved archive; package preserved outside discovery',
-    usageBefore, usageAfter,
-  });
-  const proposalAfter = { ...record, status: 'applied', ledgerEntryId: ledger.id };
-  const destination = join(ensureBelow(context.grokRoot, ['litgrok', 'archive']), `${record.targetSkill}-${ledger.id}`);
-  executeTransaction(context, makeTransaction({
-    kind: 'archive', targetSkill: record.targetSkill, targetRoot: record.targetRoot,
-    before, after: [], ledger, proposalBefore, proposalAfter, usageBefore, usageAfter,
-    archivePath: destination,
-  }), options);
-  return { ok: true, id: record.id, ledgerEntryId: ledger.id, targetSkill: record.targetSkill };
-}
-
-export function applyProposal(id, options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  return withStateLock(globalLock(context), () => {
-    recoverTransactions(context);
-    let record = loadProposal(context, id);
-    if (record.status === 'applied') {
-      const decision = resolveAppliedLedger(context, record);
-      return { ok: true, id, ledgerEntryId: decision.id, targetSkill: record.targetSkill, recovered: true };
-    }
-    if (!['pending', 'approved'].includes(record.status)) fail('PROPOSAL_NOT_APPLICABLE', record.status);
-    if (record.status === 'pending') {
-      record = validateProposal({ ...record, status: 'approved' }, { context });
-      atomicJson(proposalPath(context, id), record);
-    } else record = validateProposal(record, { context });
-    const proposalBefore = record;
-    if (record.action === 'archive') return applyArchiveProposal(context, record, proposalBefore, options);
-    const targetState = safeTargetDirectory(context, record.targetSkill);
-    const before = captureSnapshot(context, targetState.target);
-    const stage = temporaryDirectory(context, 'apply');
-    try {
-      if (targetState.exists) copyTree(targetState.target, stage);
-      applyProposalToStage(record, stage);
-      const after = captureSnapshot(context, stage);
-      const usageBefore = jsonClone(readUsage(context).skills[record.targetSkill] ?? null);
-      const createdAt = new Date().toISOString();
-      const usageAfter = usageAfterApply(usageBefore, createdAt);
-      const ledger = newLedgerEntry({
-        actor: 'user', createdAt, operation: 'apply', proposalId: record.id, targetSkill: record.targetSkill,
-        targetRoot: record.targetRoot, before, after, usageBefore, usageAfter,
-      });
-      const proposalAfter = { ...record, status: 'applied', ledgerEntryId: ledger.id };
-      executeTransaction(context, makeTransaction({
-        kind: 'apply', targetSkill: record.targetSkill, targetRoot: record.targetRoot,
-        before, after, ledger, proposalBefore, proposalAfter, usageBefore, usageAfter,
-      }), options);
-      return { ok: true, id, ledgerEntryId: ledger.id, targetSkill: record.targetSkill };
-    } finally {
-      if (existsSync(stage)) rmSync(stage, { recursive: true, force: true });
-    }
-  });
-}
-
-export function rejectProposal(id, options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  return withStateLock(globalLock(context), () => {
-    recoverTransactions(context);
-    const record = loadProposal(context, id);
-    if (record.status === 'rejected') {
-      const decision = resolveRejectDecisionLedger(context, record);
-      return { ok: true, id, ledgerEntryId: decision.id, recovered: true };
-    }
-    if (record.status !== 'pending') fail('PROPOSAL_NOT_REJECTABLE', record.status);
-    const ledger = newLedgerEntry({
-      actor: 'user', operation: 'reject', proposalId: record.id, targetSkill: record.targetSkill,
-      targetRoot: record.targetRoot, before: [], after: [], reason: options.reason ?? 'rejected by user',
-      usageBefore: null, usageAfter: null,
-    });
-    const proposalAfter = { ...record, status: 'rejected' };
-    executeTransaction(context, makeTransaction({
-      kind: 'reject', targetSkill: record.targetSkill, targetRoot: record.targetRoot,
-      before: [], after: [], ledger, proposalBefore: record, proposalAfter,
-      usageBefore: null, usageAfter: null,
-    }), options);
-    return { ok: true, id, ledgerEntryId: ledger.id };
-  });
-}
-
-export function rollbackLedger(id, options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  return withStateLock(globalLock(context), () => {
-    recoverTransactions(context);
-    const entries = readLedger(context);
-    const source = entries.find((entry) => entry.id === id);
-    if (!source || !['apply', 'curator-transition', 'rollback'].includes(source.operation)) fail('LEDGER_NOT_ROLLBACK_ELIGIBLE', id);
-    const priorRollback = entries.find((entry) => entry.operation === 'rollback' && entry.restoresLedgerEntryId === source.id);
-    if (priorRollback) {
-      const currentUsage = readUsage(context).skills[source.targetSkill] ?? null;
-      if (!snapshotsEqual(captureSnapshot(context, join(context.userRoot, source.targetSkill)), source.before)
-        || !jsonEqual(currentUsage, source.usageBefore ?? null)) fail('ROLLBACK_RECOVERY_MISMATCH');
-      return { ok: true, ledgerEntryId: priorRollback.id, restoresLedgerEntryId: source.id, targetSkill: source.targetSkill, recovered: true };
-    }
-    if (!Object.hasOwn(source, 'usageBefore') || !Object.hasOwn(source, 'usageAfter')) fail('LEDGER_USAGE_TRANSITION_MISSING', id);
-    const targetRoot = canonicalTargetRoot(context, source.targetRoot);
-    const target = join(context.userRoot, source.targetSkill);
-    const current = captureSnapshot(context, target);
-    if (!snapshotsEqual(current, source.after)) fail('ROLLBACK_CAS_MISMATCH');
-    const usageBefore = jsonClone(readUsage(context).skills[source.targetSkill] ?? null);
-    if (!jsonEqual(usageBefore, source.usageAfter)) fail('ROLLBACK_USAGE_CAS_MISMATCH');
-    const usageAfter = jsonClone(source.usageBefore);
-    const createdAt = new Date().toISOString();
-    const ledger = newLedgerEntry({
-      actor: 'user', createdAt, operation: 'rollback', proposalId: source.proposalId ?? null,
-      targetSkill: source.targetSkill, targetRoot, before: current, after: source.before,
-      restoresLedgerEntryId: source.id, usageBefore, usageAfter,
-    });
-    let proposalBefore = null;
-    let proposalAfter = null;
-    if (source.proposalId) {
-      proposalBefore = loadProposal(context, source.proposalId);
-      proposalAfter = { ...proposalBefore, status: 'rolled-back', ledgerEntryId: ledger.id };
-    }
-    executeTransaction(context, makeTransaction({
-      kind: 'rollback', targetSkill: source.targetSkill, targetRoot,
-      before: current, after: source.before, ledger, proposalBefore, proposalAfter,
-      usageBefore, usageAfter,
-    }), options);
-    return { ok: true, ledgerEntryId: ledger.id, restoresLedgerEntryId: source.id, targetSkill: source.targetSkill };
-  });
-}
-
-export function applyCuratorTransition(options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  const skill = validateSkillName(options.skill);
-  const action = options.action;
-  if (!['stale', 'archive'].includes(action)) fail('CURATOR_TRANSITION_INVALID');
-  const createdAt = requireString(options.now, 'TIMESTAMP_INVALID', 64);
-  requireTimestamp(createdAt);
-  const target = safeTargetDirectory(context, skill).target;
-  const before = captureSnapshot(context, target);
-  const usageBefore = jsonClone(readUsage(context).skills[skill] ?? null);
-  if (!usageBefore) fail('CURATOR_USAGE_MISSING', skill);
-  if (action === 'stale' && usageBefore.state !== 'active') fail('CURATOR_TRANSITION_INVALID', 'stale source');
-  if (action === 'archive' && usageBefore.state !== 'stale') fail('CURATOR_TRANSITION_INVALID', 'archive source');
-  const usageAfter = jsonClone(usageBefore);
-  usageAfter.state = action === 'stale' ? 'stale' : 'archived';
-  usageAfter.archived_at = action === 'archive' ? createdAt : null;
-  const after = action === 'stale' ? before : [];
-  const ledger = newLedgerEntry({
-    actor: 'curator', createdAt, operation: 'curator-transition', proposalId: null,
-    targetSkill: skill, targetRoot: realpathSync(context.userRoot), before, after,
-    reason: action === 'stale' ? 'marked stale after 30 idle days' : 'archived after 90 idle days; package preserved',
-    usageBefore, usageAfter,
-  });
-  const archivePath = action === 'archive'
-    ? (options.archivePath ?? join(ensureBelow(context.grokRoot, ['litgrok', 'archive']), `${skill}-${ledger.id}`))
-    : null;
-  executeTransaction(context, makeTransaction({
-    kind: action === 'archive' ? 'curator-archive' : 'curator-stale',
-    targetSkill: skill, targetRoot: ledger.targetRoot, before, after, ledger,
-    usageBefore, usageAfter, archivePath,
-  }), options);
-  return ledger;
-}
-
-function usagePath(context) {
-  return join(context.stateRoot, 'skill-usage.json');
-}
-
-function validateUsageEntry(entry, code = 'USAGE_INVALID', updated = null) {
-  if (entry === null) return null;
-  requireExactKeys(
-    entry,
-    ['state', 'use_count', 'view_count', 'patch_count', 'created_at', 'created_by', 'last_used_at', 'last_viewed_at', 'last_patched_at', 'archived_at', 'pinned'],
-    ['state', 'use_count', 'view_count', 'patch_count', 'created_at', 'created_by', 'last_used_at', 'last_viewed_at', 'last_patched_at', 'archived_at', 'pinned'],
-    code,
-  );
-  if (!['active', 'stale', 'archived'].includes(entry.state) || !['agent', 'user', 'installed', 'curator', null].includes(entry.created_by)) fail(code);
-  if (typeof entry.pinned !== 'boolean') fail(code);
-  const created = requireTimestamp(entry.created_at, code);
-  if (updated !== null && created > updated) fail(code);
-  for (const [countKey, timeKey] of [['use_count', 'last_used_at'], ['view_count', 'last_viewed_at'], ['patch_count', 'last_patched_at']]) {
-    if (!Number.isSafeInteger(entry[countKey]) || entry[countKey] < 0) fail(code);
-    if (entry[timeKey] !== null) {
-      const time = requireTimestamp(entry[timeKey], code);
-      if (time < created || (updated !== null && time > updated)) fail(code);
-    } else if (entry[countKey] > 0) fail(code);
-  }
-  if (entry.state === 'archived') {
-    if (entry.archived_at === null) fail(code);
-    const archived = requireTimestamp(entry.archived_at, code);
-    if (archived < created || (updated !== null && archived > updated)) fail(code);
-  } else if (entry.archived_at !== null) fail(code);
-  return entry;
-}
-
-export function readUsage(context) {
-  assertLearningLoopSupported();
-  const path = usagePath(context);
-  if (!existsSync(path)) return { schema: USAGE_SCHEMA, updatedAt: new Date(0).toISOString(), skills: {} };
-  const usage = readJson(path, 'USAGE_INVALID');
-  requireExactKeys(usage, ['schema', 'updatedAt', 'skills'], ['schema', 'updatedAt', 'skills'], 'USAGE_INVALID');
-  if (usage.schema !== USAGE_SCHEMA || !isObject(usage.skills)) fail('USAGE_INVALID');
-  const updated = requireTimestamp(usage.updatedAt, 'USAGE_INVALID');
-  for (const [skill, entry] of Object.entries(usage.skills)) {
-    validateSkillName(skill, 'USAGE_INVALID');
-    validateUsageEntry(entry, 'USAGE_INVALID', updated);
-  }
-  return usage;
-}
-
-export function writeUsage(context, usage) {
-  assertLearningLoopSupported();
-  atomicJson(usagePath(context), usage);
-}
-
-export function copySkillTree(source, destination) {
-  assertLearningLoopSupported();
-  return copyTree(source, destination);
-}
-
-export function isAgentOwnedSkill(context, skill) {
-  assertLearningLoopSupported();
-  return safeTargetDirectory(context, skill).exists;
-}
-
-export function agentSkillCatalog(options = {}) {
-  assertLearningLoopSupported(options);
-  const context = options.context ?? createLoopContext(options);
-  const catalog = [];
-  for (const entry of readdirSync(context.userRoot, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
-    if (!entry.isDirectory() || shippedSkillIds().has(entry.name)) continue;
-    try {
-      const state = safeTargetDirectory(context, entry.name);
-      if (!state.exists) continue;
-      catalog.push({ name: entry.name, skill: readText(join(state.target, 'SKILL.md'), 65536) });
-    } catch (error) {
-      if (!(error instanceof SkillLoopError)) throw error;
-    }
-    if (catalog.length >= 32) break;
-  }
-  return catalog;
-}
-
-function parseCli(args) {
-  const [command, ...rest] = args;
-  if (command === 'propose' && rest.length === 1) return { command, file: rest[0] };
-  if (command === 'list' && rest.length === 0) return { command };
-  if (['apply', 'reject', 'rollback'].includes(command) && rest.length === 1) return { command, id: rest[0] };
-  if (command === 'review' && rest.length <= 1) return { command, sessionId: rest[0] };
-  if (command === 'curator') {
-    let now;
-    let force = false;
-    for (let index = 0; index < rest.length; index += 1) {
-      if (rest[index] === '--force') force = true;
-      else if (rest[index] === '--now' && rest[index + 1]) now = rest[++index];
-      else return null;
-    }
-    return { command, force, now };
-  }
-  return null;
-}
-
-export async function runSkillLoop(args, options = {}) {
-  const stdout = options.stdout ?? process.stdout;
-  const stderr = options.stderr ?? process.stderr;
-  try {
-    const parsed = parseCli(args);
-    if (!parsed) fail('USAGE', 'skill-loop propose <file>|list|apply <id>|reject <id>|rollback <ledger-id>|review [session-id]|curator [--now <RFC3339>] [--force]');
-    assertLearningLoopSupported(options);
-    const context = createLoopContext(options);
-    let result;
-    if (parsed.command === 'propose') result = { ok: true, id: queueProposal(readJson(resolve(options.cwd ?? process.cwd(), parsed.file), 'PROPOSAL_INVALID'), { context }).id };
-    if (parsed.command === 'list') result = { proposals: listProposals({ context }) };
-    if (parsed.command === 'apply') result = applyProposal(parsed.id, { context });
-    if (parsed.command === 'reject') result = rejectProposal(parsed.id, { context });
-    if (parsed.command === 'rollback') result = rollbackLedger(parsed.id, { context });
-    if (parsed.command === 'review') {
-      const { runForegroundReview } = await import('./review.mjs');
-      result = await runForegroundReview({ context, sessionId: parsed.sessionId });
-    }
-    if (parsed.command === 'curator') {
-      const { runCurator } = await import('./curator.mjs');
-      result = runCurator({ context, force: parsed.force, now: parsed.now });
-    }
-    stdout.write(`${JSON.stringify(result)}\n`);
-    return 0;
-  } catch (error) {
-    const code = error instanceof SkillLoopError ? error.code : 'SKILL_LOOP_FAILED';
-    stderr.write(`LitGrok skill loop: ${code}${error instanceof SkillLoopError && error.message !== code ? ` (${error.message.slice(code.length + 2)})` : ''}\n`);
-    return error instanceof SkillLoopError ? 2 : 1;
-  }
-}
-
-if (process.argv[1] && realpathSync(resolve(process.argv[1])) === SCRIPT_PATH) {
-  void runSkillLoop(process.argv.slice(2)).then((code) => { process.exitCode = code; });
-}