agent-procedures 0.3.0 → 0.3.2

package/dist/runtime.js

@@ -1,4 +1,4 @@
-// Generated by agent-procedures@0.3.0. Do not edit.
+// Generated by agent-procedures@0.3.2. Do not edit.
 // To upgrade: npx agent-procedures init
 
 // lib/main.js
@@ -9,16 +9,59 @@ import { fileURLToPath } from "node:url";
 // lib/store.js
 import fs from "node:fs";
 import path from "node:path";
+var GROOM_LOCK_STALE_MS = 15 * 60 * 1e3;
 function paths(reflexDir) {
   return {
     reflexDir,
     tracesDir: path.join(reflexDir, "traces"),
-    proceduresFile: path.join(reflexDir, "procedures.jsonl")
+    proceduresFile: path.join(reflexDir, "procedures.jsonl"),
+    pendingFile: path.join(reflexDir, "pending.jsonl"),
+    processingFile: path.join(reflexDir, "processing.jsonl"),
+    groomerLockFile: path.join(reflexDir, "groomer.lock")
   };
 }
 function readJsonl(file) {
   if (!fs.existsSync(file)) return [];
-  return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((l) => {
+    try {
+      return JSON.parse(l);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function renameWithRetry(from, to, attempts = 8) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      fs.renameSync(from, to);
+      return;
+    } catch (e) {
+      const retryable = e.code === "EBUSY" || e.code === "EPERM" || e.code === "EACCES";
+      if (!retryable || i === attempts - 1) throw e;
+      sleepSync(15 * (i + 1));
+    }
+  }
+}
+function unlinkWithRetry(file, attempts = 8) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      if (fs.existsSync(file)) fs.unlinkSync(file);
+      return;
+    } catch (e) {
+      const retryable = e.code === "EBUSY" || e.code === "EPERM" || e.code === "EACCES";
+      if (!retryable || i === attempts - 1) throw e;
+      sleepSync(15 * (i + 1));
+    }
+  }
+}
+function writeJsonlAtomic(file, nodes) {
+  const content = nodes.length ? nodes.map((n) => JSON.stringify(n)).join("\n") + "\n" : "";
+  const tmp = file + ".tmp";
+  fs.writeFileSync(tmp, content, "utf8");
+  renameWithRetry(tmp, file);
 }
 function traceFile(reflexDir, sessionId, promptId) {
   return path.join(paths(reflexDir).tracesDir, sessionId, `${promptId}.jsonl`);
@@ -39,17 +82,326 @@ function readTrace(reflexDir, sessionId, promptId) {
 function deleteTrace(reflexDir, sessionId, promptId) {
   try {
     fs.unlinkSync(traceFile(reflexDir, sessionId, promptId));
-  } catch (e) {
+  } catch {
   }
 }
 function readProcedures(reflexDir) {
   return readJsonl(paths(reflexDir).proceduresFile);
 }
-function appendProcedure(reflexDir, node) {
-  const file = paths(reflexDir).proceduresFile;
-  if (!fs.existsSync(file)) fs.writeFileSync(file, "", "utf8");
+function readPending(reflexDir) {
+  return readJsonl(paths(reflexDir).pendingFile);
+}
+function readProcessing(reflexDir) {
+  return readJsonl(paths(reflexDir).processingFile);
+}
+function readAllProcedures(reflexDir) {
+  return [
+    ...readProcedures(reflexDir),
+    ...readPending(reflexDir),
+    ...readProcessing(reflexDir)
+  ];
+}
+function countIngest(reflexDir) {
+  return readPending(reflexDir).length + readProcessing(reflexDir).length;
+}
+function appendPending(reflexDir, node) {
+  const file = paths(reflexDir).pendingFile;
+  fs.mkdirSync(reflexDir, { recursive: true });
   fs.appendFileSync(file, JSON.stringify(node) + "\n", "utf8");
 }
+function migrateLegacyPending(reflexDir) {
+  const p = paths(reflexDir);
+  if (!fs.existsSync(p.proceduresFile)) return { moved: 0 };
+  const nodes = readJsonl(p.proceduresFile);
+  const pending = nodes.filter((n) => n.status === "pending_review");
+  if (pending.length === 0) return { moved: 0 };
+  const stable = nodes.filter((n) => n.status !== "pending_review");
+  for (const node of pending) appendPending(reflexDir, node);
+  writeJsonlAtomic(p.proceduresFile, stable);
+  return { moved: pending.length };
+}
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readLock(lockFile) {
+  try {
+    return JSON.parse(fs.readFileSync(lockFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isGroomerLocked(reflexDir, now = Date.now()) {
+  const lockFile = paths(reflexDir).groomerLockFile;
+  if (!fs.existsSync(lockFile)) return false;
+  const lock = readLock(lockFile);
+  if (!lock) return false;
+  const age = typeof lock.startedAt === "number" ? now - lock.startedAt : Infinity;
+  if (age >= GROOM_LOCK_STALE_MS) return false;
+  return pidAlive(lock.pid);
+}
+function tryAcquireGroomerLock(reflexDir, now = Date.now()) {
+  const lockFile = paths(reflexDir).groomerLockFile;
+  fs.mkdirSync(reflexDir, { recursive: true });
+  if (fs.existsSync(lockFile)) {
+    if (isGroomerLocked(reflexDir, now)) return false;
+    try {
+      fs.unlinkSync(lockFile);
+    } catch {
+      return false;
+    }
+  }
+  try {
+    const fd = fs.openSync(lockFile, "wx");
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: now }) + "\n", "utf8");
+    fs.closeSync(fd);
+    return true;
+  } catch (e) {
+    if (e.code === "EEXIST") return false;
+    throw e;
+  }
+}
+function releaseGroomerLock(reflexDir) {
+  const lockFile = paths(reflexDir).groomerLockFile;
+  try {
+    const lock = readLock(lockFile);
+    if (lock && lock.pid !== process.pid) return;
+    fs.unlinkSync(lockFile);
+  } catch {
+  }
+}
+function claimPendingBatch(reflexDir) {
+  const { pendingFile, processingFile } = paths(reflexDir);
+  if (fs.existsSync(processingFile)) return processingFile;
+  if (!fs.existsSync(pendingFile)) return null;
+  const stat = fs.statSync(pendingFile);
+  if (stat.size === 0) {
+    unlinkWithRetry(pendingFile);
+    return null;
+  }
+  renameWithRetry(pendingFile, processingFile);
+  return processingFile;
+}
+
+// lib/sanitize.js
+var PROVIDER_RULES = [
+  ["anthropic-api-key", /\b(sk-ant-api03-[a-zA-Z0-9_-]{93}AA)(?:[\x60'"\s;]|\\[nr]|$)/],
+  ["aws-access-token", /\b((?:A3T[A-Z0-9]|AKIA|ASIA|ABIA|ACCA)[A-Z2-7]{16})\b/],
+  ["cloudflare-api-key", /[\w.-]{0,50}?(?:cloudflare)(?:[ \t\w.-]{0,20})[\s'"]{0,3}(?:=|>|:{1,3}=|\|\||:|=>|\?=|,)[\x60'"\s=]{0,5}([a-z0-9_-]{40})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["datadog-access-token", /[\w.-]{0,50}?(?:datadog)(?:[ \t\w.-]{0,20})[\s'"]{0,3}(?:=|>|:{1,3}=|\|\||:|=>|\?=|,)[\x60'"\s=]{0,5}([a-z0-9]{40})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["digitalocean-access-token", /\b(doo_v1_[a-f0-9]{64})(?:[\x60'"\s;]|\\[nr]|$)/],
+  ["discord-api-token", /[\w.-]{0,50}?(?:discord)(?:[ \t\w.-]{0,20})[\s'"]{0,3}(?:=|>|:{1,3}=|\|\||:|=>|\?=|,)[\x60'"\s=]{0,5}([a-f0-9]{64})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["dropbox-short-lived-api-token", /[\w.-]{0,50}?(?:dropbox)(?:[ \t\w.-]{0,20})[\s'"]{0,3}(?:=|>|:{1,3}=|\|\||:|=>|\?=|,)[\x60'"\s=]{0,5}(sl\.[a-z0-9\-=_]{135})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["gcp-api-key", /\b(AIza[\w-]{35})(?:[\x60'"\s;]|\\[nr]|$)/],
+  ["github-pat", /ghp_[0-9a-zA-Z]{36}/],
+  ["gitlab-pat", /glpat-[\w-]{20}/],
+  ["heroku-api-key-v2", /\b((HRKU-AA[0-9a-zA-Z_-]{58}))(?:[\x60'"\s;]|\\[nr]|$)/],
+  ["mailgun-private-api-token", /[\w.-]{0,50}?(?:mailgun)(?:[ \t\w.-]{0,20})[\s'"]{0,3}(?:=|>|:{1,3}=|\|\||:|=>|\?=|,)[\x60'"\s=]{0,5}(key-[a-f0-9]{32})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["npm-access-token", /\b(npm_[a-z0-9]{36})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["openai-api-key", /\b(sk-(?:proj|svcacct|admin)-(?:[A-Za-z0-9_-]{74}|[A-Za-z0-9_-]{58})T3BlbkFJ(?:[A-Za-z0-9_-]{74}|[A-Za-z0-9_-]{58})\b|sk-[a-zA-Z0-9]{20}T3BlbkFJ[a-zA-Z0-9]{20})(?:[\x60'"\s;]|\\[nr]|$)/],
+  ["pypi-upload-token", /pypi-AgEIcHlwaS5vcmc[\w-]{50,1000}/],
+  ["sendgrid-api-token", /\b(SG\.[a-z0-9=_\-.]{66})(?:[\x60'"\s;]|\\[nr]|$)/i],
+  ["shopify-access-token", /shpat_[a-fA-F0-9]{32}/],
+  ["slack-bot-token", /xoxb-[0-9]{10,13}-[0-9]{10,13}[a-zA-Z0-9-]*/],
+  ["stripe-access-token", /\b((?:sk|rk)_(?:test|live|prod)_[a-zA-Z0-9]{10,99})(?:[\x60'"\s;]|\\[nr]|$)/],
+  ["twilio-api-key", /SK[0-9a-fA-F]{32}/],
+  ["private-key", /-----BEGIN[ A-Z0-9_-]{0,100}PRIVATE KEY(?: BLOCK)?-----[\s\S-]{64,}?KEY(?: BLOCK)?-----/i],
+  ["jwt", /\b(ey[a-zA-Z0-9]{17,}\.ey[a-zA-Z0-9/\\_-]{17,}\.(?:[a-zA-Z0-9/\\_-]{10,}={0,2})?)(?:[\x60'"\s;]|\\[nr]|$)/]
+];
+var SENSITIVE_NAME = /(?:^|_)(?:API_?)?(?:KEY|TOKEN|SECRET|PASS|PASSWORD|AUTH|CREDENTIALS?|DATABASE_URL|DB_URL|CONNECTION_STRING|DSN)(?:_|$)/i;
+var ASSIGNMENT = /\b(export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(?:"([^"]*)"|'([^']*)'|([^\s;&|"']+))(\s*)/g;
+var CREDENTIAL_URL = /^[a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:[^@\s/]+@/i;
+function result(text, requiresEnv = [], unsafe = false) {
+  return { text, requiresEnv: [...new Set(requiresEnv)], unsafe };
+}
+function replaceDetectedSecrets(input) {
+  let text = input;
+  let unsafe = false;
+  for (const [id, regex] of PROVIDER_RULES) {
+    let match;
+    while (match = regex.exec(text)) {
+      const secret = match[1] || match[0];
+      const offset = match[0].indexOf(secret);
+      const start = match.index + offset;
+      text = text.slice(0, start) + `[secret:${id}]` + text.slice(start + secret.length);
+      unsafe = true;
+    }
+  }
+  return { text, unsafe };
+}
+function sanitizeText(input = "") {
+  const detected = replaceDetectedSecrets(String(input));
+  return result(detected.text, [], detected.unsafe);
+}
+function sanitizeCommand(input = "") {
+  let text = String(input);
+  const requiresEnv = [];
+  let removedAssignment = false;
+  text = text.replace(ASSIGNMENT, (match, exported, name, double, single, bare, trailing, offset, source) => {
+    const value = double ?? single ?? bare ?? "";
+    const valueIsSecret = SENSITIVE_NAME.test(name) || CREDENTIAL_URL.test(value) || PROVIDER_RULES.some(([, regex]) => regex.test(value));
+    if (!valueIsSecret) return match;
+    requiresEnv.push(name);
+    const before = source.slice(0, offset);
+    const isCommandAssignment = exported || !before.trim() || /(?:&&|\|\||;)\s*$/.test(before);
+    if (isCommandAssignment) {
+      removedAssignment = true;
+      return "";
+    }
+    const placeholder = bare !== void 0 ? `\${${name}}` : `"\${${name}}"`;
+    return `${name}=${placeholder}${trailing}`;
+  });
+  text = text.replace(
+    /'(\bAuthorization\s*:\s*Bearer\s+)([^']+)'/gi,
+    (_match, prefix) => {
+      requiresEnv.push("AUTH_TOKEN");
+      return `"${prefix}\${AUTH_TOKEN}"`;
+    }
+  );
+  text = text.replace(
+    /'(\bAuthorization\s*:\s*Basic\s+)([^']+)'/gi,
+    (_match, prefix) => {
+      requiresEnv.push("BASIC_AUTH");
+      return `"${prefix}\${BASIC_AUTH}"`;
+    }
+  );
+  text = text.replace(
+    /'([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)([^@']+)(@[^']+)'/gi,
+    (_match, prefix, _password, suffix) => {
+      requiresEnv.push("PASSWORD");
+      return `"${prefix}\${PASSWORD}${suffix}"`;
+    }
+  );
+  text = text.replace(
+    /(\bAuthorization\s*:\s*Bearer\s+)([^"'\s]+)/gi,
+    (_match, prefix) => {
+      requiresEnv.push("AUTH_TOKEN");
+      return `${prefix}\${AUTH_TOKEN}`;
+    }
+  );
+  text = text.replace(
+    /(\bAuthorization\s*:\s*Basic\s+)([^"'\s]+)/gi,
+    (_match, prefix) => {
+      requiresEnv.push("BASIC_AUTH");
+      return `${prefix}\${BASIC_AUTH}`;
+    }
+  );
+  text = text.replace(
+    /([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)([^@\s/]+)(@)/gi,
+    (_match, prefix, _password, suffix) => {
+      requiresEnv.push("PASSWORD");
+      return `${prefix}\${PASSWORD}${suffix}`;
+    }
+  );
+  text = text.replace(
+    /(--(?:password|passwd|token|secret|api-key|key)(?:=|\s+))(["']?)([^"'\s;&|]+)\2/gi,
+    (_match, prefix, quote) => {
+      const name = prefix.match(/^--([a-z-]+)/i)[1].replace(/-/g, "_").toUpperCase();
+      requiresEnv.push(name);
+      const safeQuote = quote === "'" ? '"' : quote;
+      return `${prefix}${safeQuote}\${${name}}${safeQuote}`;
+    }
+  );
+  if (removedAssignment) {
+    text = text.replace(/^\s*(?:&&|\|\||;)\s*/, "").replace(/\s*(?:&&|\|\||;)\s*$/, "").replace(/(?:&&|\|\||;)\s*(?=(?:&&|\|\||;))/g, "").trim();
+  }
+  const detected = replaceDetectedSecrets(text);
+  return result(detected.text, requiresEnv, detected.unsafe);
+}
+
+// lib/recall.js
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "to",
+  "in",
+  "on",
+  "please",
+  "can",
+  "you",
+  "my",
+  "this",
+  "for",
+  "with"
+]);
+function tokenize(text) {
+  if (!text) return [];
+  return text.toLowerCase().replace(/[^\w\s]+/g, " ").split(/\s+/).filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+}
+function scoreTarget(promptTokens, targetString) {
+  const targetTokens = tokenize(targetString);
+  if (targetTokens.length === 0) return { coverage: 0, matchCount: 0, targetLen: 0 };
+  let matchCount = 0;
+  let hasHighValueWord = false;
+  for (const tWord of targetTokens) {
+    const isMatch = promptTokens.some(
+      (pWord) => pWord === tWord || tWord.length >= 3 && pWord.startsWith(tWord)
+    );
+    if (isMatch) {
+      matchCount++;
+      if (tWord.length >= 6) hasHighValueWord = true;
+    }
+  }
+  const coverage = matchCount / targetTokens.length;
+  const isReliable = coverage >= 0.75 && (matchCount >= 2 || hasHighValueWord);
+  if (!isReliable) return { coverage: 0, matchCount: 0, targetLen: 0 };
+  return { coverage, matchCount, targetLen: targetTokens.length };
+}
+function isBetter(a, b) {
+  if (a.coverage !== b.coverage) return a.coverage > b.coverage;
+  if (a.matchCount !== b.matchCount) return a.matchCount > b.matchCount;
+  return a.targetLen > b.targetLen;
+}
+function scoreProcedure(promptTokens, node) {
+  let best = scoreTarget(promptTokens, node.trigger || "");
+  if (Array.isArray(node.aliases)) {
+    for (const alias of node.aliases) {
+      const next = scoreTarget(promptTokens, alias);
+      if (isBetter(next, best)) best = next;
+    }
+  }
+  return best;
+}
+function formatSteps(steps, requiresEnv = []) {
+  const required = requiresEnv.length > 0 ? `Requires environment: ${requiresEnv.join(", ")}
+
+` : "";
+  return required + steps.map((s) => `- ${s.t}: ${s.target}`).join("\n");
+}
+function recall(prompt, procs) {
+  if (!prompt) return null;
+  const promptTokens = tokenize(prompt);
+  let best = null;
+  let bestScore = { coverage: 0, matchCount: 0, targetLen: 0 };
+  for (const node of procs) {
+    if (node.enabled === false || node.parent_id) continue;
+    const score = scoreProcedure(promptTokens, node);
+    if (isBetter(score, bestScore)) {
+      bestScore = score;
+      best = node;
+    }
+  }
+  if (!best) return null;
+  let text = formatSteps(best.steps, best.requires_env);
+  const alt = procs.find((e) => e.parent_id === best.id && e.type === "alt" && e.enabled !== false);
+  if (alt) text += "\n\nAlternative path that worked:\n" + formatSteps(alt.steps, alt.requires_env);
+  const label = best.trigger || "procedure";
+  return {
+    node: best,
+    text: `Reflex memory found a procedure for this task:
+
+${text}
+
+Follow these steps instead of figuring it out from scratch.`,
+    notice: `Reflex recalled: "${label}"`
+  };
+}
 
 // lib/engine.js
 function handleEvent(evt, reflexDir, deps = {}) {
@@ -62,84 +414,83 @@ function handleEvent(evt, reflexDir, deps = {}) {
 var GROOM_THRESHOLD = 5;
 function onPrompt(evt, reflexDir) {
   const { sessionId, promptId, prompt } = evt;
-  startTrace(reflexDir, sessionId, promptId, { t: "Goal", prompt });
-  const hit = recall(prompt, readProcedures(reflexDir));
-  if (!hit) return { context: null };
+  const sanitized = sanitizeCommand(prompt);
+  startTrace(reflexDir, sessionId, promptId, {
+    t: "Goal",
+    prompt: sanitized.text,
+    ...sanitized.requiresEnv.length > 0 ? { requires_env: sanitized.requiresEnv } : {},
+    ...sanitized.unsafe ? { contains_unresolvable_secret: true } : {}
+  });
+  const hit = recall(sanitized.text, readAllProcedures(reflexDir));
+  if (!hit) return { context: null, notice: null };
   appendTrace(reflexDir, sessionId, promptId, { t: "Recall", hit: hit.node.id });
-  return { context: hit.text };
-}
-function recall(prompt, procs) {
-  if (!prompt) return null;
-  const p = prompt.toLowerCase();
-  const fmt = (steps) => steps.map((s) => `- ${s.t}: ${s.target}`).join("\n");
-  for (const node of procs) {
-    if (node.enabled === false || node.parent_id) continue;
-    let match = node.trigger && p.includes(node.trigger.toLowerCase());
-    if (!match && Array.isArray(node.aliases)) {
-      match = node.aliases.some((a) => p.includes(a.toLowerCase()));
-    }
-    if (!match) continue;
-    let text = fmt(node.steps);
-    const alt = procs.find((e) => e.parent_id === node.id && e.type === "alt" && e.enabled !== false);
-    const onFail = procs.find((e) => e.parent_id === node.id && e.type === "on_fail" && e.enabled !== false);
-    if (alt) text += "\n\nAlternative path that worked:\n" + fmt(alt.steps);
-    if (onFail) text += "\n\nIf it fails, this recovery worked:\n" + fmt(onFail.steps);
-    return {
-      node,
-      text: `Reflex memory found a procedure for this task:
-
-${text}
-
-Follow these steps instead of figuring it out from scratch.`
-    };
-  }
-  return null;
+  return { context: hit.text, notice: hit.notice };
 }
 function onTool(evt, reflexDir) {
-  appendTrace(reflexDir, evt.sessionId, evt.promptId, { t: evt.tool, target: evt.target || "", ok: evt.ok });
+  const sanitized = evt.tool === "Bash" || evt.tool === "bash" ? sanitizeCommand(evt.target) : sanitizeText(evt.target);
+  appendTrace(reflexDir, evt.sessionId, evt.promptId, {
+    t: evt.tool,
+    target: sanitized.text,
+    ok: evt.ok,
+    ...sanitized.requiresEnv.length > 0 ? { requires_env: sanitized.requiresEnv } : {},
+    ...sanitized.unsafe ? { contains_unresolvable_secret: true } : {}
+  });
   return { context: null };
 }
 function onStop(evt, reflexDir, deps) {
   const { sessionId, promptId } = evt;
   const lines = readTrace(reflexDir, sessionId, promptId);
   if (lines.length === 0) return { context: null };
+  if (lines.some((line) => line.contains_unresolvable_secret)) {
+    deleteTrace(reflexDir, sessionId, promptId);
+    return { context: null };
+  }
   let goal = "";
   let recallHit = null;
+  let hasGoal = false;
   for (const l of lines) {
-    if (l.t === "Goal") goal = l.prompt;
+    if (l.t === "Goal") {
+      goal = l.prompt;
+      hasGoal = true;
+    }
     if (l.t === "Recall" && l.hit) recallHit = l.hit;
   }
+  if (!hasGoal) {
+    deleteTrace(reflexDir, sessionId, promptId);
+    return { context: null };
+  }
   if (judge(lines, evt)) {
-    const steps = synthesize(lines);
+    const { steps, requiresEnv } = synthesize(lines);
     if (steps.length > 0) {
+      const id = Math.random().toString(36).slice(2, 11);
       if (!recallHit) {
-        appendProcedure(reflexDir, {
-          id: Math.random().toString(36).slice(2, 11),
+        appendPending(reflexDir, {
+          id,
           title: goal,
           trigger: goal,
           steps,
+          ...requiresEnv.length > 0 ? { requires_env: requiresEnv } : {},
           enabled: true,
-          hits: 0,
-          last_used_at: (/* @__PURE__ */ new Date()).toISOString(),
           created_at: (/* @__PURE__ */ new Date()).toISOString(),
           status: "pending_review"
         });
       } else {
-        const parent = readProcedures(reflexDir).find((p) => p.id === recallHit);
+        const parent = readAllProcedures(reflexDir).find((p) => p.id === recallHit);
         const parentSteps = parent ? parent.steps : [];
         const same = parentSteps.length === steps.length && parentSteps.every((s, i) => s.t === steps[i].t && s.target === steps[i].target);
         if (!same) {
-          appendProcedure(reflexDir, {
+          appendPending(reflexDir, {
+            id,
             parent_id: recallHit,
             type: "alt",
             steps,
+            ...requiresEnv.length > 0 ? { requires_env: requiresEnv } : {},
             created_at: (/* @__PURE__ */ new Date()).toISOString(),
             status: "pending_review"
           });
         }
       }
-      const pending = readProcedures(reflexDir).filter((p) => p.status === "pending_review").length;
-      if (pending >= GROOM_THRESHOLD && deps.spawnGroomer) deps.spawnGroomer();
+      if (countIngest(reflexDir) >= GROOM_THRESHOLD && deps.spawnGroomer) deps.spawnGroomer();
     }
   }
   deleteTrace(reflexDir, sessionId, promptId);
@@ -174,17 +525,20 @@ function judge(lines, evt) {
 }
 function synthesize(lines) {
   const steps = [];
+  const requiresEnv = /* @__PURE__ */ new Set();
   for (const l of lines) {
+    for (const name of l.requires_env || []) requiresEnv.add(name);
     if (l.t === "Goal" || l.t === "Recall" || l.ok === false) continue;
     if (l.t === "Read" || l.t === "View") continue;
     if (l.t === "Bash" || l.t === "bash") {
       const target = l.target || "";
+      if (!target.trim()) continue;
       if (PURE_READ_CMDS.includes(target.trim().split(" ")[0])) continue;
       if (/^git (status|log|diff)/.test(target)) continue;
     }
     steps.push({ t: l.t, target: l.target });
   }
-  return steps;
+  return { steps, requiresEnv: [...requiresEnv] };
 }
 
 // lib/groomer.js
@@ -345,48 +699,37 @@ function resolveCredentials(env = process.env) {
 }
 
 // lib/groomer.js
-function logError(proceduresFile, msg) {
-  const reflexDir = path3.dirname(proceduresFile);
+var GROOM_MAX_ATTEMPTS = 3;
+function logError(reflexDir, msg) {
   const logFile = path3.join(reflexDir, "worker.log");
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   try {
     fs3.appendFileSync(logFile, `[${timestamp}] ${msg}
 `, "utf8");
-  } catch (e) {
+  } catch {
   }
 }
-async function runGroomer(proceduresFile) {
-  let creds;
-  try {
-    creds = resolveCredentials();
-  } catch (e) {
-    logError(proceduresFile, e.message);
-    return;
+function mergeStable(stable, batchIds, keptFromBatch) {
+  const withoutBatch = stable.filter((n) => !n.id || !batchIds.has(n.id));
+  const byId = /* @__PURE__ */ new Map();
+  const anonymous = [];
+  for (const n of [...withoutBatch, ...keptFromBatch]) {
+    if (n.id) byId.set(n.id, n);
+    else anonymous.push(n);
   }
-  if (!creds) {
-    logError(
-      proceduresFile,
-      "No API key found. Run `npx agent-procedures auth login` or set ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY."
-    );
-    return;
+  return [...byId.values(), ...anonymous];
+}
+async function processBatch(reflexDir, processingFile, creds) {
+  const batch = readProcessing(reflexDir);
+  if (batch.length === 0) {
+    unlinkWithRetry(processingFile);
+    return { ok: true, deferred: 0 };
   }
-  const { provider, apiKey, model } = creds;
-  if (!fs3.existsSync(proceduresFile)) return;
-  const lines = fs3.readFileSync(proceduresFile, "utf8").split("\n").filter(Boolean);
-  const nodes = lines.map((l) => {
-    try {
-      return JSON.parse(l);
-    } catch (e) {
-      return null;
-    }
-  }).filter(Boolean);
-  const pending = nodes.filter((n) => n.status === "pending_review");
-  if (pending.length === 0) return;
   const prompt = `
-Here are ${pending.length} new execution nodes/edges added by a coding agent.
+Here are ${batch.length} new execution nodes/edges added by a coding agent.
 
 <edges>
-${JSON.stringify(pending, null, 2)}
+${JSON.stringify(batch, null, 2)}
 </edges>
 
 For each item:
@@ -408,46 +751,77 @@ Return ONLY a JSON array of objects with this schema:
 `;
   let responseText;
   try {
-    responseText = await PROVIDERS[provider].complete(apiKey, model, prompt);
+    responseText = await PROVIDERS[creds.provider].complete(creds.apiKey, creds.model, prompt);
   } catch (err) {
-    logError(proceduresFile, err.message);
-    return;
+    logError(reflexDir, err.message);
+    return { ok: false, deferred: 0 };
   }
   let actions = [];
   try {
     const jsonStr = responseText.replace(/```json/g, "").replace(/```/g, "").trim();
     actions = JSON.parse(jsonStr);
-  } catch (e) {
-    logError(
-      proceduresFile,
-      "Failed to parse LLM JSON response: " + responseText
-    );
-    return;
+  } catch {
+    logError(reflexDir, "Failed to parse LLM JSON response.");
+    return { ok: false, deferred: 0 };
   }
-  const newNodes = [];
-  for (const node of nodes) {
-    if (node.status === "pending_review") {
-      const actionDef = actions.find((a) => a.id === node.id);
-      if (actionDef) {
-        if (actionDef.action === "DROP") {
-          continue;
-        } else {
-          delete node.status;
-          if (!node.parent_id && actionDef.aliases) {
-            node.aliases = actionDef.aliases;
-          }
-        }
-      }
+  const kept = [];
+  const deferred = [];
+  for (const node of batch) {
+    const actionDef = actions.find((a) => a.id === node.id);
+    if (!actionDef) {
+      const attempts = (node.groom_attempts || 0) + 1;
+      if (attempts < GROOM_MAX_ATTEMPTS) deferred.push({ ...node, groom_attempts: attempts });
+      continue;
     }
-    newNodes.push(node);
+    if (actionDef.action === "DROP") continue;
+    const next = { ...node };
+    delete next.status;
+    delete next.groom_attempts;
+    if (!next.parent_id && Array.isArray(actionDef.aliases)) {
+      next.aliases = actionDef.aliases;
+    }
+    kept.push(next);
   }
-  const newFileContent = newNodes.map((n) => JSON.stringify(n)).join("\n") + "\n";
-  const tmpFile = proceduresFile + ".tmp";
+  const resolvedIds = new Set(
+    batch.filter((n) => actions.some((a) => a.id === n.id)).map((n) => n.id).filter(Boolean)
+  );
+  const merged = mergeStable(readProcedures(reflexDir), resolvedIds, kept);
+  writeJsonlAtomic(paths(reflexDir).proceduresFile, merged);
+  unlinkWithRetry(processingFile);
+  for (const node of deferred) appendPending(reflexDir, node);
+  return { ok: true, deferred: deferred.length };
+}
+async function runGroomer(reflexDir) {
+  if (!tryAcquireGroomerLock(reflexDir)) return { ran: false, reason: "locked" };
   try {
-    fs3.writeFileSync(tmpFile, newFileContent, "utf8");
-    fs3.renameSync(tmpFile, proceduresFile);
-  } catch (err) {
-    logError(proceduresFile, `Failed atomic write: ${err.message}`);
+    migrateLegacyPending(reflexDir);
+    let creds;
+    try {
+      creds = resolveCredentials();
+    } catch (e) {
+      logError(reflexDir, e.message);
+      return { ran: false, reason: "creds" };
+    }
+    if (!creds) {
+      logError(
+        reflexDir,
+        "No API key found. Run `npx agent-procedures auth login` or set ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY."
+      );
+      return { ran: false, reason: "creds" };
+    }
+    let batches = 0;
+    while (batches < 8) {
+      const processingFile = claimPendingBatch(reflexDir);
+      if (!processingFile) break;
+      const { ok, deferred } = await processBatch(reflexDir, processingFile, creds);
+      if (!ok) break;
+      batches++;
+      if (deferred > 0) break;
+      if (countIngest(reflexDir) === 0) break;
+    }
+    return { ran: true, batches };
+  } finally {
+    releaseGroomerLock(reflexDir);
   }
 }
 
@@ -500,19 +874,21 @@ var claude_default = {
       return {
         type: "stop",
         ...base,
-        interrupted: payload.stop_hook_active === true,
+        interrupted: false,
         busy: Array.isArray(payload.background_tasks) && payload.background_tasks.length > 0
       };
     }
     return null;
   },
   /** Engine result → what to print on stdout for Claude. */
-  render(evt, result) {
+  render(evt, result2) {
     if (evt.type !== "prompt") return "";
-    if (!result.context) return "{}";
-    return JSON.stringify({
-      hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: result.context }
-    });
+    if (!result2.context) return "{}";
+    const out = {
+      hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: result2.context }
+    };
+    if (result2.notice) out.systemMessage = result2.notice;
+    return JSON.stringify(out);
   }
 };
 
@@ -539,6 +915,7 @@ function readStdin() {
   });
 }
 function spawnGroomer() {
+  if (isGroomerLocked(REFLEX_DIR)) return;
   const child = spawn(process.argv[0], [process.argv[1], "Groom"], { detached: true, stdio: "ignore" });
   child.unref();
 }
@@ -546,7 +923,7 @@ async function run(harnessId, argv = process.argv.slice(2)) {
   const [eventName] = argv;
   if (!eventName) return;
   if (eventName === "Groom") {
-    await runGroomer(path5.join(REFLEX_DIR, "procedures.jsonl"));
+    await runGroomer(REFLEX_DIR);
     return;
   }
   const raw = await readStdin();
@@ -560,8 +937,8 @@ async function run(harnessId, argv = process.argv.slice(2)) {
   const harness = getHarness(harnessId);
   const evt = harness.normalize(eventName, payload);
   if (!evt) return;
-  const result = handleEvent(evt, REFLEX_DIR, { spawnGroomer });
-  const out = harness.render(evt, result);
+  const result2 = handleEvent(evt, REFLEX_DIR, { spawnGroomer });
+  const out = harness.render(evt, result2);
   if (out) process.stdout.write(out + "\n");
 }
 export {