@litfamily/litclaude 1.0.6 → 1.0.8

package/plugins/litclaude/lib/skill-loop/hook-runtime.mjs

@@ -1,188 +0,0 @@
-import { spawn } from "node:child_process";
-import { lstatSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-
-import { containsSecret } from "../secret-shapes.mjs";
-import { recordObservation } from "../skill-observer.mjs";
-import { SKILL_ID } from "./common.mjs";
-import { readSkillLoopConfig } from "./config.mjs";
-import { runCurator, SESSION_START_CURATOR_LIMITS } from "./curator.mjs";
-import {
-  disableSessionRecording,
-  readLatestHookActivity,
-  readHookState,
-  recordCorrectionSignal,
-  recordToolIteration,
-  requestPendingReview,
-} from "./hook-state.mjs";
-import { listProposals } from "./proposals.mjs";
-import { recordSkillConsult } from "./usage.mjs";
-import {
-  createSnapshotWorkBudget,
-  SESSION_START_LEDGER_WORK_LIMITS,
-} from "./ledger.mjs";
-
-const CORRECTION_SIGNAL = /\b(?:don't|do not|stop|never|why\s+(?:do\s+you\s+)?keep)\b|그만|하지\s*마|왜\s*자꾸/iu;
-const SESSION_RECORDING_OPTOUT = /^\s*(?:don't\s+record\s+this\s+session|do\s+not\s+record\s+this\s+session|이\s+세션(?:을)?\s+기록하지\s+마(?:세요)?)\s*[.!]?\s*$/iu;
-const MAX_CORRECTION_CHARS = 1000;
-const MAX_READ_PATH_CHARS = 4096;
-
-const contained = (root, child) => {
-  const rel = relative(root, child);
-  return rel !== "" && !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`);
-};
-
-function lexicalAliasFor(realRoot, requested) {
-  let current = dirname(requested);
-  while (true) {
-    try {
-      if (realpathSync.native(current) === realRoot) return current;
-    } catch {
-      return null;
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-function resolveInsideSkillRoot(skillRoot, requested) {
-  const rootDetails = lstatSync(skillRoot, { throwIfNoEntry: false });
-  if (!rootDetails?.isDirectory() || rootDetails.isSymbolicLink()) return null;
-  const absolute = resolve(requested);
-  let realRoot;
-  let realFile;
-  try {
-    realRoot = realpathSync.native(skillRoot);
-    realFile = realpathSync.native(absolute);
-  } catch {
-    return null;
-  }
-  if (!contained(realRoot, realFile)) return null;
-  const lexicalRoot = lexicalAliasFor(realRoot, absolute);
-  if (lexicalRoot === null || !contained(lexicalRoot, absolute)) return null;
-  const rel = relative(lexicalRoot, absolute);
-  let current = lexicalRoot;
-  for (const component of rel.split(/[\\/]/u)) {
-    current = join(current, component);
-    const details = lstatSync(current, { throwIfNoEntry: false });
-    if (!details || details.isSymbolicLink()) return null;
-  }
-  const details = lstatSync(absolute, { throwIfNoEntry: false });
-  if (!details?.isFile() || details.isSymbolicLink() || details.nlink !== 1) return null;
-  const [skillId] = relative(realRoot, realFile).split(/[\\/]/u);
-  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(skillId) ? skillId : null;
-}
-
-function skillIdFromSkillTool(raw) {
-  if (typeof raw !== "string") return null;
-  const separator = raw.indexOf(":");
-  if (separator === -1) return SKILL_ID.test(raw) ? raw : null;
-  const plugin = raw.slice(0, separator);
-  const name = raw.slice(separator + 1);
-  if (plugin.length === 0 || name.length === 0 || name.includes(":")) return null;
-  return SKILL_ID.test(name) ? name : null;
-}
-
-export function skillIdFromToolUse(input, workspaceRoot, pluginRoot) {
-  if (input?.tool_name === "Skill") {
-    return skillIdFromSkillTool(input?.tool_input?.skill);
-  }
-  if (input?.tool_name !== "Read" || typeof input?.tool_input?.file_path !== "string"
-    || input.tool_input.file_path.length < 1 || input.tool_input.file_path.length > MAX_READ_PATH_CHARS) return null;
-  const requested = isAbsolute(input.tool_input.file_path)
-    ? input.tool_input.file_path
-    : resolve(workspaceRoot, input.tool_input.file_path);
-  return resolveInsideSkillRoot(join(workspaceRoot, ".claude", "skills"), requested)
-    ?? resolveInsideSkillRoot(join(pluginRoot, "skills"), requested);
-}
-
-export function observePreToolUse(root, input, pluginRoot) {
-  if (typeof input?.session_id !== "string") return null;
-  const skillId = skillIdFromToolUse(input, root, pluginRoot);
-  const recorded = recordToolIteration(root, input.session_id, skillId ?? undefined);
-  if (recorded && skillId) recordSkillConsult(root, skillId);
-  return recorded ? skillId : null;
-}
-
-export function observeCorrection(root, input) {
-  const prompt = typeof input?.prompt === "string" ? input.prompt : "";
-  if (typeof input?.session_id !== "string") return false;
-  if (SESSION_RECORDING_OPTOUT.test(prompt)) {
-    disableSessionRecording(root, input.session_id);
-    return false;
-  }
-  if (!CORRECTION_SIGNAL.test(prompt) || containsSecret(prompt)) return false;
-  const state = readHookState(root, input.session_id);
-  if (state.recordingDisabled || state.consultedSkills.length === 0 || state.proposalCount >= 3) return false;
-  const skillId = state.consultedSkills.at(-1);
-  const observed = prompt.slice(0, MAX_CORRECTION_CHARS);
-  recordObservation(root, {
-    signal: "correction",
-    skillId,
-    observed,
-    proposal: `Review ${skillId} against this bounded correction and queue only a reusable pending change.`,
-  });
-  return recordCorrectionSignal(root, input.session_id);
-}
-
-export function scheduleStopReview(root, input, runnerPath) {
-  if (typeof input?.session_id !== "string" || typeof input?.transcript_path !== "string") return false;
-  const state = readHookState(root, input.session_id);
-  if (state.recordingDisabled) return false;
-  const config = readSkillLoopConfig(root);
-  const reasons = [];
-  if (state.correctionCount > 0) reasons.push("correction");
-  if (state.toolIterations >= config.nudgeInterval) reasons.push("nudge-interval");
-  if (reasons.length === 0 || state.proposalCount >= 3) return false;
-  const request = requestPendingReview(root, input.session_id, input.transcript_path, reasons);
-  if (!request.created) return false;
-  const child = spawn(process.execPath, [runnerPath, root], {
-    detached: true,
-    stdio: "ignore",
-    cwd: root,
-    env: { ...process.env, LITFAMILY_SKILL_REVIEW: "1" },
-  });
-  child.unref();
-  return true;
-}
-
-export function pendingProposalNotice(root, {
-  ledgerWorkLimits = SESSION_START_LEDGER_WORK_LIMITS,
-} = {}) {
-  const count = listProposals(root, { ledgerWorkLimits }).filter(({ status }) => status === "pending").length;
-  return count > 0
-    ? `${count} skill proposals pending — \`/litclaude:skill-observer list\``
-    : "";
-}
-
-export function runSessionStartCurator(root, {
-  now = new Date().toISOString(),
-  workLimits = SESSION_START_CURATOR_LIMITS,
-} = {}) {
-  const usagePath = join(resolve(root), ".litclaude", "skill-usage.json");
-  const usage = lstatSync(usagePath, { throwIfNoEntry: false });
-  if (!usage) return { reason: "NO_USAGE_STATE", transitions: [] };
-  if (!usage.isFile() || usage.isSymbolicLink() || usage.nlink !== 1) {
-    return { reason: "USAGE_STATE_UNSAFE", transitions: [] };
-  }
-  const snapshotWork = createSnapshotWorkBudget();
-  let lastActivityAt;
-  try {
-    lastActivityAt = readLatestHookActivity(root, {
-      mutationRecoveryOptions: workLimits === null ? undefined : {
-        snapshotOptions: { workLimits, work: snapshotWork },
-      },
-    });
-  } catch (error) {
-    if (error?.code === "SNAPSHOT_WORK_CAP_EXCEEDED") {
-      return {
-        reason: "WORK_CAP_EXCEEDED",
-        transitions: [],
-        advisory: "Skill curator deferred: SessionStart work cap exceeded; run `/litclaude:skill-observer curator run` explicitly.",
-      };
-    }
-    throw error;
-  }
-  return runCurator(root, { now, lastActivityAt, workLimits, snapshotWork });
-}

package/plugins/litclaude/lib/skill-loop/hook-state.mjs

@@ -1,484 +0,0 @@
-import { lstatSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-
-import {
-  assertNoSecretStrings,
-  assertRegularSingleLink,
-  atomicWriteJson,
-  ensureSafeDirectoryChain,
-  isPlainObject,
-  parseTimestamp,
-  prettyJsonBytes,
-  readStrictJsonFile,
-  RECORD_ID,
-  requireExactKeys,
-  SKILL_ID,
-  withSkillLoopLock,
-} from "./common.mjs";
-import { validateProposal } from "./proposal-record.mjs";
-import {
-  assertProposalCapacityUnlocked,
-  listProposalRecords,
-  normalizeProposalTargetRoot,
-} from "./proposal-store.mjs";
-import {
-  beginReviewTransactionUnlocked,
-  clearReviewTransactionUnlocked,
-  markReviewTransactionCommittedUnlocked,
-  publishReviewTransactionUnlocked,
-  recoverReviewTransactionUnlocked,
-  stageReviewTransactionUnlocked,
-} from "./review-transaction.mjs";
-import { recoverSkillMutationTransactionUnlocked } from "./mutation-transaction.mjs";
-
-export class SkillLoopHookStateError extends Error {
-  constructor(code, message = code) {
-    super(`${code}: ${message}`);
-    this.name = "SkillLoopHookStateError";
-    this.code = code;
-  }
-}
-
-const MAX_STATE_BYTES = 64 * 1024;
-const MAX_SESSIONS = 32;
-const MAX_CONSULTED_SKILLS = 32;
-const MAX_PROPOSALS_PER_SESSION = 3;
-const REVIEW_REASONS = new Set(["correction", "nudge-interval"]);
-const SKIP_SESSION_WRITE = Symbol("skip-session-write");
-const skipSessionWrite = (value) => ({ [SKIP_SESSION_WRITE]: true, value });
-const stateFile = (root, name, create) => {
-  const state = ensureSafeDirectoryChain(root, [".litclaude"], {
-    create,
-    ErrorType: SkillLoopHookStateError,
-    code: "HOOK_STATE_UNSAFE",
-  });
-  return state === null ? null : join(state, name);
-};
-const nowIso = () => new Date().toISOString();
-const emptyStore = () => ({
-  schema: "litclaude.skill-loop-state/v1",
-  updatedAt: "1970-01-01T00:00:00.000Z",
-  sessions: {},
-});
-const freshSession = (sessionId, now = nowIso()) => ({
-  sessionId,
-  toolIterations: 0,
-  consultedSkills: [],
-  correctionCount: 0,
-  proposalCount: 0,
-  pendingReview: false,
-  recordingDisabled: false,
-  lastActivityAt: now,
-});
-const fail = (code, message) => { throw new SkillLoopHookStateError(code, message); };
-
-function validateSession(entry, key) {
-  if (!requireExactKeys(entry, [
-    "sessionId", "toolIterations", "consultedSkills", "correctionCount", "proposalCount",
-    "pendingReview", "lastActivityAt",
-  ], ["recordingDisabled"]) || entry.sessionId !== key || !RECORD_ID.test(entry.sessionId)
-    || !Number.isSafeInteger(entry.toolIterations) || entry.toolIterations < 0 || entry.toolIterations > 1_000_000
-    || !Array.isArray(entry.consultedSkills) || entry.consultedSkills.length > MAX_CONSULTED_SKILLS
-    || entry.consultedSkills.some((skill) => !SKILL_ID.test(skill))
-    || new Set(entry.consultedSkills).size !== entry.consultedSkills.length
-    || !Number.isSafeInteger(entry.correctionCount) || entry.correctionCount < 0 || entry.correctionCount > 1_000_000
-    || !Number.isSafeInteger(entry.proposalCount) || entry.proposalCount < 0
-    || entry.proposalCount > MAX_PROPOSALS_PER_SESSION
-    || typeof entry.pendingReview !== "boolean"
-    || (Object.hasOwn(entry, "recordingDisabled") && typeof entry.recordingDisabled !== "boolean")
-    || parseTimestamp(entry.lastActivityAt) === null) {
-    fail("HOOK_STATE_INVALID", "session state is invalid");
-  }
-}
-
-function validateStore(store) {
-  let bytes;
-  try { bytes = prettyJsonBytes(store); } catch { fail("HOOK_STATE_INVALID"); }
-  if (bytes.length > MAX_STATE_BYTES) fail("HOOK_STATE_TOO_LARGE");
-  if (!requireExactKeys(store, ["schema", "updatedAt", "sessions"])
-    || store.schema !== "litclaude.skill-loop-state/v1" || parseTimestamp(store.updatedAt) === null
-    || !isPlainObject(store.sessions) || Object.keys(store.sessions).length > MAX_SESSIONS) {
-    fail("HOOK_STATE_INVALID", "session store is invalid");
-  }
-  for (const [key, entry] of Object.entries(store.sessions)) validateSession(entry, key);
-  assertNoSecretStrings(store, () => fail("HOOK_STATE_SECRET_REFUSED"));
-  return store;
-}
-
-function readStoreUnlocked(root) {
-  const path = stateFile(root, "skill-loop-state.json", false);
-  if (path === null || !lstatSync(path, { throwIfNoEntry: false })) return emptyStore();
-  try {
-    return validateStore(readStrictJsonFile(path, SkillLoopHookStateError, "HOOK_STATE_UNSAFE", {
-      maxBytes: MAX_STATE_BYTES,
-      parseCode: "HOOK_STATE_INVALID",
-    }));
-  } catch (error) {
-    if (error instanceof SkillLoopHookStateError) throw error;
-    fail("HOOK_STATE_INVALID");
-  }
-}
-
-function writeStoreUnlocked(root, store) {
-  validateStore(store);
-  atomicWriteJson(stateFile(root, "skill-loop-state.json", true), store,
-    SkillLoopHookStateError, "HOOK_STATE_UNSAFE");
-  return store;
-}
-
-function updateSession(root, sessionId, operation, now = nowIso()) {
-  if (!RECORD_ID.test(sessionId) || parseTimestamp(now) === null) fail("HOOK_SESSION_INVALID");
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const session = structuredClone(store.sessions[sessionId] ?? freshSession(sessionId, now));
-    const result = operation(session);
-    if (result?.[SKIP_SESSION_WRITE]) return result.value;
-    session.lastActivityAt = now;
-    store.sessions[sessionId] = session;
-    const ordered = Object.values(store.sessions)
-      .sort((left, right) => parseTimestamp(right.lastActivityAt) - parseTimestamp(left.lastActivityAt));
-    store.sessions = Object.fromEntries(ordered.slice(0, MAX_SESSIONS).map((entry) => [entry.sessionId, entry]));
-    store.updatedAt = now;
-    writeStoreUnlocked(root, store);
-    return result ?? structuredClone(session);
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function readHookState(root, sessionId) {
-  if (!RECORD_ID.test(sessionId)) fail("HOOK_SESSION_INVALID");
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    return structuredClone(store.sessions[sessionId] ?? freshSession(sessionId, store.updatedAt));
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function readLatestHookActivity(root, { mutationRecoveryOptions } = {}) {
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root, mutationRecoveryOptions);
-    const store = readStoreUnlocked(root);
-    return Object.values(store.sessions).reduce(
-      (latest, session) => parseTimestamp(session.lastActivityAt) > parseTimestamp(latest)
-        ? session.lastActivityAt
-        : latest,
-      "1970-01-01T00:00:00.000Z",
-    );
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function recordToolIteration(root, sessionId, skillId, { now = nowIso() } = {}) {
-  if (skillId !== undefined && !SKILL_ID.test(skillId)) fail("HOOK_SKILL_INVALID");
-  return updateSession(root, sessionId, (session) => {
-    if (session.recordingDisabled) return skipSessionWrite(false);
-    session.toolIterations += 1;
-    if (skillId && !session.consultedSkills.includes(skillId)) {
-      session.consultedSkills.push(skillId);
-      if (session.consultedSkills.length > MAX_CONSULTED_SKILLS) session.consultedSkills.shift();
-    }
-    return true;
-  }, now);
-}
-
-export function recordCorrectionSignal(root, sessionId, { now = nowIso() } = {}) {
-  return updateSession(root, sessionId, (session) => {
-    if (session.recordingDisabled || session.consultedSkills.length === 0
-      || session.proposalCount >= MAX_PROPOSALS_PER_SESSION) return skipSessionWrite(false);
-    session.correctionCount += 1;
-    return true;
-  }, now);
-}
-
-export function disableSessionRecording(root, sessionId, { now = nowIso() } = {}) {
-  if (!RECORD_ID.test(sessionId) || parseTimestamp(now) === null) fail("HOOK_SESSION_INVALID");
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const session = structuredClone(store.sessions[sessionId] ?? freshSession(sessionId, now));
-    session.recordingDisabled = true;
-    session.toolIterations = 0;
-    session.consultedSkills = [];
-    session.correctionCount = 0;
-    session.pendingReview = false;
-    session.lastActivityAt = now;
-    store.sessions[sessionId] = session;
-    const pending = readPendingUnlocked(root);
-    const ordered = Object.values(store.sessions)
-      .sort((left, right) => parseTimestamp(right.lastActivityAt) - parseTimestamp(left.lastActivityAt));
-    store.sessions = Object.fromEntries(ordered.slice(0, MAX_SESSIONS).map((entry) => [entry.sessionId, entry]));
-    store.updatedAt = now;
-    writeStoreUnlocked(root, store);
-    if (pending?.sessionId === sessionId && ["pending", "claimed"].includes(pending.status)) {
-      removePendingUnlocked(root);
-    }
-    return true;
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function pendingProposalAllowance(root, sessionId) {
-  return Math.max(0, MAX_PROPOSALS_PER_SESSION - readHookState(root, sessionId).proposalCount);
-}
-
-function validatePending(value) {
-  let bytes;
-  try { bytes = prettyJsonBytes(value); } catch { fail("PENDING_REVIEW_INVALID"); }
-  if (bytes.length > MAX_STATE_BYTES) fail("PENDING_REVIEW_TOO_LARGE");
-  if (!requireExactKeys(value, [
-    "schema", "sessionId", "createdAt", "transcriptPath", "reasons", "consultedSkills",
-    "remainingAllowance", "status", "claimedAt", "completedAt", "queuedProposalIds",
-  ]) || value.schema !== "litclaude.pending-skill-review/v1" || !RECORD_ID.test(value.sessionId)
-    || parseTimestamp(value.createdAt) === null || typeof value.transcriptPath !== "string"
-    || value.transcriptPath.length < 1 || value.transcriptPath.length > 4096
-    || !Array.isArray(value.reasons) || value.reasons.length < 1 || value.reasons.length > 2
-    || value.reasons.some((reason) => !REVIEW_REASONS.has(reason)) || new Set(value.reasons).size !== value.reasons.length
-    || !Array.isArray(value.consultedSkills) || value.consultedSkills.length > MAX_CONSULTED_SKILLS
-    || value.consultedSkills.some((skill) => !SKILL_ID.test(skill))
-    || new Set(value.consultedSkills).size !== value.consultedSkills.length
-    || !Number.isSafeInteger(value.remainingAllowance) || value.remainingAllowance < 0
-    || value.remainingAllowance > MAX_PROPOSALS_PER_SESSION
-    || !["pending", "claimed", "completed"].includes(value.status)
-    || !(value.claimedAt === null || parseTimestamp(value.claimedAt) !== null)
-    || !(value.completedAt === null || parseTimestamp(value.completedAt) !== null)
-    || !Array.isArray(value.queuedProposalIds) || value.queuedProposalIds.length > MAX_PROPOSALS_PER_SESSION
-    || value.queuedProposalIds.some((id) => !RECORD_ID.test(id))
-    || new Set(value.queuedProposalIds).size !== value.queuedProposalIds.length) fail("PENDING_REVIEW_INVALID");
-  if ((value.status === "pending" && (value.claimedAt !== null || value.completedAt !== null))
-    || (value.status === "claimed" && (value.claimedAt === null || value.completedAt !== null))
-    || (value.status === "completed" && value.completedAt === null)) fail("PENDING_REVIEW_INVALID");
-  assertNoSecretStrings(value, () => fail("PENDING_REVIEW_SECRET_REFUSED"));
-  return value;
-}
-
-function readPendingUnlocked(root) {
-  const path = stateFile(root, "pending-review.json", false);
-  if (path === null || !lstatSync(path, { throwIfNoEntry: false })) return null;
-  return validatePending(readStrictJsonFile(path, SkillLoopHookStateError, "HOOK_STATE_UNSAFE", {
-    maxBytes: MAX_STATE_BYTES,
-    parseCode: "PENDING_REVIEW_INVALID",
-  }));
-}
-
-function writePendingUnlocked(root, value) {
-  validatePending(value);
-  atomicWriteJson(stateFile(root, "pending-review.json", true), value,
-    SkillLoopHookStateError, "HOOK_STATE_UNSAFE");
-  return value;
-}
-
-function removePendingUnlocked(root) {
-  const path = stateFile(root, "pending-review.json", false);
-  const before = path === null ? null : lstatSync(path, { throwIfNoEntry: false });
-  if (!before) return null;
-  assertRegularSingleLink(path, SkillLoopHookStateError, "HOOK_STATE_UNSAFE", { maxBytes: MAX_STATE_BYTES });
-  const after = lstatSync(path, { throwIfNoEntry: false });
-  if (!after?.isFile() || after.isSymbolicLink() || after.nlink !== 1
-    || after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size
-    || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
-    fail("HOOK_STATE_UNSAFE");
-  }
-  try { unlinkSync(path); } catch { fail("HOOK_STATE_UNSAFE"); }
-  return null;
-}
-
-function cancelDisabledPendingUnlocked(root, store, pending) {
-  if (pending && ["pending", "claimed"].includes(pending.status)
-    && store.sessions[pending.sessionId]?.recordingDisabled) {
-    return removePendingUnlocked(root);
-  }
-  return pending;
-}
-
-export function readPendingReview(root) {
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    return structuredClone(cancelDisabledPendingUnlocked(root, store, readPendingUnlocked(root)));
-  },
-    SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function requestPendingReview(root, sessionId, transcriptPath, reasons, { now = nowIso() } = {}) {
-  if (!RECORD_ID.test(sessionId) || parseTimestamp(now) === null) fail("PENDING_REVIEW_INVALID");
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const current = cancelDisabledPendingUnlocked(root, store, readPendingUnlocked(root));
-    if (current && current.status !== "completed") return { created: false, pending: current };
-    const session = store.sessions[sessionId];
-    if (!session || session.recordingDisabled) return { created: false, pending: null };
-    const remainingAllowance = Math.max(0, MAX_PROPOSALS_PER_SESSION - session.proposalCount);
-    if (remainingAllowance === 0) return { created: false, pending: null };
-    const pending = validatePending({
-      schema: "litclaude.pending-skill-review/v1",
-      sessionId,
-      createdAt: now,
-      transcriptPath,
-      reasons: [...new Set(reasons)],
-      consultedSkills: [...session.consultedSkills],
-      remainingAllowance,
-      status: "pending",
-      claimedAt: null,
-      completedAt: null,
-      queuedProposalIds: [],
-    });
-    session.pendingReview = true;
-    session.lastActivityAt = now;
-    store.updatedAt = now;
-    writeStoreUnlocked(root, store);
-    writePendingUnlocked(root, pending);
-    return { created: true, pending };
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function claimPendingReview(root, { now = nowIso() } = {}) {
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const pending = cancelDisabledPendingUnlocked(root, store, readPendingUnlocked(root));
-    const reclaimable = pending?.status === "claimed"
-      && parseTimestamp(now) - parseTimestamp(pending.claimedAt) >= 10 * 60 * 1000;
-    if (!pending || store.sessions[pending.sessionId]?.recordingDisabled
-      || (pending.status !== "pending" && !reclaimable)) fail("PENDING_REVIEW_NOT_AVAILABLE");
-    return writePendingUnlocked(root, { ...pending, status: "claimed", claimedAt: now });
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function releasePendingReview(root) {
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const pending = cancelDisabledPendingUnlocked(root, store, readPendingUnlocked(root));
-    if (!pending || pending.status !== "claimed") return pending;
-    return writePendingUnlocked(root, { ...pending, status: "pending", claimedAt: null });
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function completePendingReview(root, queuedProposalIds, { now = nowIso() } = {}) {
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const pending = cancelDisabledPendingUnlocked(root, store, readPendingUnlocked(root));
-    if (!pending || pending.status !== "claimed" || queuedProposalIds.length > pending.remainingAllowance) {
-      fail("PENDING_REVIEW_INVALID");
-    }
-    const session = store.sessions[pending.sessionId];
-    if (!session || session.proposalCount + queuedProposalIds.length > MAX_PROPOSALS_PER_SESSION) {
-      fail("HOOK_STATE_INVALID");
-    }
-    session.proposalCount += queuedProposalIds.length;
-    session.toolIterations = 0;
-    session.correctionCount = 0;
-    session.pendingReview = false;
-    session.lastActivityAt = now;
-    store.updatedAt = now;
-    writeStoreUnlocked(root, store);
-    return writePendingUnlocked(root, {
-      ...pending,
-      status: "completed",
-      completedAt: now,
-      queuedProposalIds: [...queuedProposalIds],
-    });
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}
-
-export function commitPendingReviewBatch(root, proposals, {
-  now = nowIso(),
-  afterStageCreate,
-  afterStageWrite,
-  afterProposalWrite,
-  afterStateWrite,
-  afterPendingWrite,
-  afterTransactionCommit,
-} = {}) {
-  if (!Array.isArray(proposals) || parseTimestamp(now) === null) fail("PENDING_REVIEW_INVALID");
-  return withSkillLoopLock(root, "transaction", () => {
-    recoverReviewTransactionUnlocked(root);
-    recoverSkillMutationTransactionUnlocked(root);
-    const store = readStoreUnlocked(root);
-    const pending = cancelDisabledPendingUnlocked(root, store, readPendingUnlocked(root));
-    if (!pending || pending.status !== "claimed" || proposals.length > pending.remainingAllowance) {
-      fail("PENDING_REVIEW_INVALID");
-    }
-    const persistedProposals = proposals.map((proposal) => normalizeProposalTargetRoot(root, proposal));
-    const ids = new Set();
-    for (const proposal of persistedProposals) {
-      if (proposal.status !== "pending" || proposal.sessionRef !== pending.sessionId || ids.has(proposal.id)) {
-        fail("PENDING_REVIEW_INVALID");
-      }
-      ids.add(proposal.id);
-    }
-    const existingIds = new Set(listProposalRecords(root).map(({ id }) => id));
-    if (persistedProposals.some(({ id }) => existingIds.has(id))) fail("PENDING_REVIEW_INVALID");
-    assertProposalCapacityUnlocked(root, persistedProposals.length);
-
-    const session = store.sessions[pending.sessionId];
-    if (!session || session.recordingDisabled
-      || session.proposalCount + persistedProposals.length > MAX_PROPOSALS_PER_SESSION) {
-      fail("HOOK_STATE_INVALID");
-    }
-    const nextStore = structuredClone(store);
-    const nextSession = nextStore.sessions[pending.sessionId];
-    nextSession.proposalCount += persistedProposals.length;
-    nextSession.toolIterations = 0;
-    nextSession.correctionCount = 0;
-    nextSession.pendingReview = false;
-    nextSession.lastActivityAt = now;
-    nextStore.updatedAt = now;
-    validateStore(nextStore);
-    const nextPending = validatePending({
-      ...pending,
-      status: "completed",
-      completedAt: now,
-      queuedProposalIds: persistedProposals.map(({ id }) => id),
-    });
-
-    const storePath = stateFile(root, "skill-loop-state.json", false);
-    const pendingPath = stateFile(root, "pending-review.json", false);
-    if (storePath === null || pendingPath === null) fail("HOOK_STATE_INVALID");
-    const originalStoreBytes = assertRegularSingleLink(storePath, SkillLoopHookStateError, "HOOK_STATE_UNSAFE", {
-      maxBytes: MAX_STATE_BYTES,
-    });
-    const originalPendingBytes = assertRegularSingleLink(pendingPath, SkillLoopHookStateError, "HOOK_STATE_UNSAFE", {
-      maxBytes: MAX_STATE_BYTES,
-    });
-    const rollbackPending = validatePending({ ...pending, status: "pending", claimedAt: null });
-    let transaction;
-    try {
-      transaction = beginReviewTransactionUnlocked(root, {
-        beforeState: originalStoreBytes,
-        activePending: originalPendingBytes,
-        rollbackPending: prettyJsonBytes(rollbackPending),
-        afterState: prettyJsonBytes(nextStore),
-        afterPending: prettyJsonBytes(nextPending),
-        proposals: persistedProposals,
-        now,
-      });
-      stageReviewTransactionUnlocked(root, transaction, afterStageWrite, afterStageCreate);
-      publishReviewTransactionUnlocked(root, transaction, afterProposalWrite);
-      writeStoreUnlocked(root, nextStore);
-      afterStateWrite?.();
-      writePendingUnlocked(root, nextPending);
-      afterPendingWrite?.();
-      markReviewTransactionCommittedUnlocked(root, transaction);
-      afterTransactionCommit?.();
-      clearReviewTransactionUnlocked(root);
-      return nextPending;
-    } catch (error) {
-      if (transaction) {
-        let recovery;
-        try { recovery = recoverReviewTransactionUnlocked(root); } catch { fail("REVIEW_TRANSACTION_ROLLBACK_FAILED"); }
-        if (recovery.status === "finalized") return nextPending;
-      }
-      throw error;
-    }
-  }, SkillLoopHookStateError, "HOOK_STATE_LOCK_FAILED");
-}