@litfamily/litgrok 1.0.0

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

@@ -0,0 +1,2087 @@
+#!/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; });
+}