carthagent 0.0.0-stage → 1.0.7

package/lib/opencode/evaluation-budget-plugin/index.ts

@@ -0,0 +1,147 @@
+import { Plugin } from '@opencode/plugin';
+
+type Turn = { id: string; finish: string; productive: boolean };
+const ledgerKey = (sessionID: string) => `evaluation/${sessionID}/turns`;
+const budgetKey = 'ctg.evaluation.budget';
+const retryKey = (sessionID: string) => `evaluation/${sessionID}/retries`;
+
+/** Durable per-session admission boundary for productive OpenCode model requests. */
+export default Plugin.define({
+  id: 'ctg.evaluation-budget',
+  async setup(ctx) {
+    const maxTurns = Number(process.env.CTG_EVALUATION_MAX_TURNS);
+    const maxCost = Number(process.env.CTG_EVALUATION_MAX_COST);
+    const maxRetries = Number(process.env.CTG_EVALUATION_MAX_RETRIES ?? 8);
+    if (!Number.isInteger(maxTurns) || maxTurns < 1 || maxTurns > 1000) throw Error('Invalid evaluation turn limit');
+    if (!Number.isFinite(maxCost) || maxCost <= 0) throw Error('Invalid evaluation cost limit');
+    if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 100) throw Error('Invalid evaluation retry limit');
+
+    // Durable, ID-keyed session events populate the persistent ledger. The
+    // storage ledger survives compaction and service restarts; message IDs make
+    // repeated delivery idempotent and prevent double-counting completed turns.
+    const turnsBySession = new Map<string, Map<string, Turn>>();
+    const eventAbort = new AbortController();
+    const pendingWrites = new Map<string, Promise<void>>();
+    const retriesBySession = new Map<string, number>();
+    const eventTask = (async () => {
+      for await (const event of ctx.event.subscribe({ signal: eventAbort.signal })) {
+        if (!event.type.startsWith('session.') || !('sessionID' in event.data)) continue;
+        const sessionID = event.data.sessionID;
+        if (event.type === 'session.step.ended' || event.type === 'session.step.failed') {
+          const messageID = event.data.assistantMessageID;
+          const turns = await loadTurns(sessionID);
+          const failed = event.type === 'session.step.failed' || event.data.finish === 'error';
+          turns.set(messageID, { id: messageID, finish: failed ? 'error' : event.data.finish ?? 'error', productive: !failed });
+          await saveTurns(sessionID, turns);
+        } else if (event.type === 'session.execution.failed') {
+          // Retry exhaustion can terminate an execution without a final step event.
+          // It does not count as productive work, but remains separately bounded.
+          await ctx.storage.set(retryKey(sessionID), retriesBySession.get(sessionID) ?? 0);
+        } else if (event.type === 'session.compaction.ended') {
+          const transcript = await ctx.session.context({ sessionID });
+          const turns = await loadTurns(sessionID);
+          for (const message of transcript) {
+            if (message.type !== 'assistant' || !message.finish) continue;
+            if (message.finish === 'error') turns.set(message.id, { id: message.id, finish: 'error', productive: false });
+            else turns.set(message.id, { id: message.id, finish: message.finish, productive: true });
+          }
+          await saveTurns(sessionID, turns);
+        }
+      }
+    })();
+    // Async iteration normally exits when cleanup aborts its subscription. Keep a
+    // terminal rejection observed so it cannot become an unhandled plugin error.
+    void eventTask.catch(() => undefined);
+
+    async function loadTurns(sessionID: string) {
+      await pendingWrites.get(sessionID);
+      const turns = new Map<string, Turn>();
+      const persisted = await ctx.storage.get(ledgerKey(sessionID));
+      if (Array.isArray(persisted)) {
+        for (const item of persisted) {
+          if (item && typeof item === 'object' && 'id' in item && 'finish' in item && 'productive' in item
+            && typeof item.id === 'string' && typeof item.finish === 'string' && typeof item.productive === 'boolean') turns.set(item.id, item as Turn);
+        }
+      }
+      for (const [id, turn] of turnsBySession.get(sessionID) ?? []) turns.set(id, turn);
+      turnsBySession.set(sessionID, turns);
+      return turns;
+    }
+
+    async function saveTurns(sessionID: string, turns: Map<string, Turn>) {
+      const before = pendingWrites.get(sessionID) ?? Promise.resolve();
+      const write = before.catch(() => undefined).then(() => ctx.storage.set(ledgerKey(sessionID), [...turns.values()]));
+      pendingWrites.set(sessionID, write);
+      try { await write; }
+      finally { if (pendingWrites.get(sessionID) === write) pendingWrites.delete(sessionID); }
+    }
+
+    let modelRequest;
+    let retry;
+    try {
+      modelRequest = await ctx.session.hook('model.request', async event => {
+        if (event.kind !== 'primary') return;
+        await pendingWrites.get(event.sessionID);
+        const session = await ctx.session.get({ sessionID: event.sessionID });
+        const configured = session.metadata?.[budgetKey];
+        if (!configured || typeof configured !== 'object'
+          || configured.maxTurns !== maxTurns || configured.maxCost !== maxCost) {
+          throw Error('Evaluation session budget handshake is missing or differs from the active admission guard');
+        }
+        const turns = await loadTurns(event.sessionID);
+        // Reconcile the host's durable session projection before every admission.
+        // The storage ledger retains pre-compaction IDs; context contributes any
+        // completed assistant turns written before a service/plugin restart.
+        const transcript = await ctx.session.context({ sessionID:event.sessionID });
+        for (const message of transcript) {
+          if (message.type !== 'assistant' || !message.finish) continue;
+          // A retained compacted summary is a new assistant message, but never
+          // an admitted model request; only IDs seen in durable step events count.
+          if (message.metadata?.synthetic === true || message.content?.some(part => part.type === 'compaction')) continue;
+          turns.set(message.id, { id:message.id, finish:message.finish, productive:message.finish !== 'error' });
+        }
+        await saveTurns(event.sessionID, turns);
+        const usedTurns = [...turns.values()].filter(turn => turn.productive).length;
+        if (usedTurns >= maxTurns) throw Error('Evaluation productive model-turn budget exhausted before request admission');
+
+        const info = session;
+        const model = (await ctx.model.list({ location: { directory: ctx.location.directory } })).data
+          .find(candidate => candidate.providerID === event.model.providerID && candidate.id === event.model.id);
+        const rates = model?.cost;
+        if (!Number.isFinite(info.cost) || !rates?.length || !Number.isFinite(model?.limit?.context) || !Number.isFinite(model?.limit?.output)) {
+          throw Error('Evaluation usage or model pricing limits unavailable; refusing request admission');
+        }
+        const maxInputRate = Math.max(...rates.map(rate => rate.input), ...rates.map(rate => rate.cache.read));
+        const maxOutputRate = Math.max(...rates.map(rate => rate.output), ...rates.map(rate => rate.cache.write));
+        const worstCaseCost = (model.limit.context * maxInputRate + model.limit.output * maxOutputRate) / 1_000_000;
+        if (!Number.isFinite(worstCaseCost) || info.cost + worstCaseCost > maxCost) throw Error('Evaluation cost budget exhausted before request admission');
+      });
+      retry = await ctx.session.hook('retry', async event => {
+        if (event.attempt >= maxRetries) {
+          event.decision = { retry: false };
+          return;
+        }
+        const persisted = await ctx.storage.get(retryKey(event.sessionID));
+        const total = Math.max(retriesBySession.get(event.sessionID) ?? 0, typeof persisted === 'number' ? persisted : 0) + 1;
+        retriesBySession.set(event.sessionID, total);
+        await ctx.storage.set(retryKey(event.sessionID), total);
+        if (total > maxRetries) event.decision = { retry: false };
+      });
+    } catch (error) {
+      eventAbort.abort();
+      await retry?.dispose();
+      await modelRequest?.dispose();
+      throw error;
+    }
+    return async () => {
+      try { await retry.dispose(); }
+      finally {
+        try { await modelRequest.dispose(); }
+        finally {
+          eventAbort.abort();
+          await eventTask.catch(() => undefined);
+        }
+      }
+    };
+  },
+});

package/lib/opencode/evaluation.mjs

@@ -0,0 +1,242 @@
+import { OpenCode } from '@opencode/client';
+import { createHash } from 'node:crypto';
+
+export const NATIVE_EVALUATION_RUNTIME = 'opencode-2';
+export const EVALUATION_BUDGET_PLUGIN = 'ctg.evaluation-budget';
+export const EVALUATION_BUDGET_METADATA = 'ctg.evaluation.budget';
+export const hashFile = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function positive(value, label, maximum = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isFinite(value) || value <= 0 || value > maximum) throw Error(`Invalid ${label}`);
+  return value;
+}
+const assistantMessages = messages => messages.filter(message => message.type === 'assistant');
+
+async function allMessages(api, sessionID, options = {}) {
+  const messages = [];
+  let cursor;
+  do {
+    const page = await api.message.list({ sessionID, limit: 200, ...(cursor ? { cursor } : { order:'asc' }) }, options);
+    messages.push(...page.data);
+    cursor = page.cursor.next;
+  } while (cursor);
+  return messages;
+}
+
+async function bounded(promise, milliseconds, fallback) {
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve(promise),
+      new Promise(resolve => { timer = setTimeout(() => resolve(fallback), milliseconds); }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Run one native OpenCode session with fail-closed accounting and cancellation. */
+export async function runNativeEvaluation({ directory, prompt, systemPrompt = '', model, provider, timeoutSeconds = 600, maxTurns = 100, maxCost = 3,
+  signal, onEvent = () => {}, client, baseUrl = process.env.CTG_OPENCODE_URL, headers = {}, version = '2.0.32', outcomeTimeoutSeconds = 10 }) {
+  positive(timeoutSeconds, 'timeoutSeconds', 3600);
+  positive(maxTurns, 'maxTurns', 1000);
+  positive(maxCost, 'maxCost');
+  positive(outcomeTimeoutSeconds, 'outcomeTimeoutSeconds', 60);
+  if (!directory || !prompt || !model || !provider) throw Error('directory, prompt, provider, and model are required');
+  if (!client && !baseUrl) throw Error('CTG_OPENCODE_URL must identify the isolated native OpenCode service; shared service discovery is disabled.');
+  if (!client && !Object.keys(headers).length && process.env.CTG_OPENCODE_AUTHORIZATION) headers = { authorization: process.env.CTG_OPENCODE_AUTHORIZATION };
+  const api = client || OpenCode.make({ baseUrl, headers });
+  const controller = new AbortController();
+  const eventController = new AbortController();
+  const abort = () => controller.abort(signal?.reason || new Error('Evaluation stopped'));
+  if (signal?.aborted) abort();
+  else signal?.addEventListener('abort', abort, { once: true });
+  controller.signal.addEventListener('abort', () => eventController.abort(), { once: true });
+  const timer = setTimeout(() => controller.abort(new Error('Evaluation wall-time limit')), timeoutSeconds * 1000);
+  const started = Date.now();
+  const state = { turns: 0, productiveTurns: 0, providerErrors: 0, cost: null, tokens: 0, tools: {}, errors: [], lastStop: null, budgetReason: null, deliveryStatus: null };
+  let session, streamTask, streamError, outcome;
+  let interruptionStatus = 'not-needed';
+  let finished = false;
+  let stopAfterIdle = false;
+  const toolByCallID = new Map();
+
+  const onEventStream = async () => {
+    try {
+      for await (const event of api.event.subscribe({ signal: eventController.signal })) {
+        if (finished) break;
+        const data = event.data;
+        // Native session events are scoped only by their typed data.sessionID.
+        // Ignore missing IDs as well as neighbors; never infer scope from V1 fields.
+        if (event.type.startsWith('session.') && data?.sessionID !== session.id) continue;
+        if (event.type === 'session.step.ended') {
+          state.turns++;
+          if (data.finish === 'error') state.providerErrors++;
+          else state.productiveTurns++;
+          state.lastStop = data.finish;
+        } else if (event.type === 'session.execution.failed') {
+          state.providerErrors++;
+          state.errors.push(data.error?.message || 'OpenCode execution failed');
+        } else if (event.type === 'session.tool.called') {
+          toolByCallID.set(data.id, data);
+          const name = data.tool || data.name;
+          if (name) state.tools[name] = (state.tools[name] || 0) + 1;
+        } else if (event.type === 'session.tool.success') {
+          const call = toolByCallID.get(data.id);
+          if (call?.tool === 'delivery_finish' || call?.name === 'delivery_finish') {
+            const text = (data.content || []).filter(item => item.type === 'text').map(item => item.text).join('\n');
+            try { state.deliveryStatus = JSON.parse(text).status || null; } catch {}
+          }
+        } else if (event.type === 'session.tool.failed') {
+          const call = toolByCallID.get(data.id);
+          if (call?.tool === 'delivery_finish' || call?.name === 'delivery_finish') state.deliveryStatus = null;
+        }
+        onEvent(event);
+        if (event.type === 'session.idle' && data.sessionID === session.id) {
+          if (stopAfterIdle) break;
+        }
+      }
+    } catch (error) {
+      if (!eventController.signal.aborted) streamError = error;
+    }
+  };
+
+  const pollOutcome = async () => {
+    const deadline=Date.now()+outcomeTimeoutSeconds*1000;
+    do {
+      const info=await api.session.get({sessionID:session.id},{signal:AbortSignal.timeout(5000)});
+      if(info.outcome) return info;
+      if(Date.now()>=deadline) throw Error('OpenCode session terminal outcome did not become available');
+      await new Promise(resolve=>setTimeout(resolve,25));
+    } while(true);
+  };
+
+  try {
+    if (controller.signal.aborted) throw controller.signal.reason;
+    const info = await api.server.info({ signal: controller.signal });
+    if (info.version && !info.version.startsWith('2.')) throw Error(`OpenCode 2 required, received ${info.version}`);
+    const plugins = await api.plugin.list({ location: { directory } }, { signal: controller.signal });
+    const guard = plugins.data.find(plugin => plugin.id === EVALUATION_BUDGET_PLUGIN);
+    if (guard?.state.status !== 'active') throw Error(`Evaluation admission guard ${EVALUATION_BUDGET_PLUGIN} is not active`);
+    session = await api.session.create({
+      model: { providerID: provider, id: model },
+      location: { directory },
+      title: `CTG evaluation ${NATIVE_EVALUATION_RUNTIME}`,
+      metadata: { [EVALUATION_BUDGET_METADATA]: { maxTurns, maxCost } },
+    }, { signal: controller.signal });
+    streamTask = onEventStream();
+    // Subscription has no replay; allow its connection to establish before admission.
+    await new Promise(resolve => setTimeout(resolve, 50));
+    if (controller.signal.aborted) throw controller.signal.reason;
+    await api.session.prompt({ sessionID: session.id, text: `${systemPrompt ? `${systemPrompt}\n\n` : ''}${prompt}` }, { signal: controller.signal });
+    await api.session.wait({ sessionID: session.id }, { signal: controller.signal });
+    stopAfterIdle = true;
+    if (streamTask) await Promise.race([streamTask, new Promise(resolve => setTimeout(resolve, 200))]);
+    finished = true;
+    eventController.abort(); // wait() is authoritative; snapshot below reconciles a missed idle.
+    await bounded(streamTask, 250, undefined);
+
+    // wait() may beat durable projection updates. Poll this exact session until its
+    // authoritative terminal outcome is visible; absence is never success.
+    const sessionInfo = await pollOutcome();
+    outcome = sessionInfo.outcome;
+    if (outcome !== 'succeeded') state.errors.push(`OpenCode session ended with authoritative outcome: ${outcome}`);
+
+    // Fetch only this session's assistant transcript; /session/stats is project-wide.
+    const transcript = await allMessages(api, session.id, { signal: AbortSignal.timeout(15000) });
+    const assistant = assistantMessages(transcript);
+    state.turns = assistant.filter(message => message.finish !== undefined).length;
+    state.productiveTurns = assistant.filter(message => message.finish !== undefined && message.finish !== 'error').length;
+    state.providerErrors = Math.max(state.providerErrors, assistant.filter(message => message.finish === 'error').length);
+    state.lastStop = assistant.at(-1)?.finish || null;
+    state.tools = {};
+    for (const message of assistant) for (const part of message.content || []) {
+      if (part.type === 'tool') state.tools[part.name] = (state.tools[part.name] || 0) + 1;
+      if (part.type === 'tool' && part.name === 'delivery_finish' && part.state?.status === 'completed') {
+        const text=(part.state.content || []).filter(item=>item.type==='text').map(item=>item.text).join('\n');
+        try { state.deliveryStatus=JSON.parse(text).status || null; } catch {}
+      }
+    }
+    const tokenUsage = sessionInfo.tokens;
+    if (!Number.isFinite(sessionInfo.cost) || sessionInfo.cost < 0 || !tokenUsage || !['input','output','reasoning'].every(key => Number.isFinite(tokenUsage[key]) && tokenUsage[key] >= 0) || !tokenUsage.cache || !['read','write'].every(key => Number.isFinite(tokenUsage.cache[key]) && tokenUsage.cache[key] >= 0)) {
+      throw Error('OpenCode session aggregate usage is unavailable; refusing evaluation without enforceable max-cost');
+    }
+    state.cost = sessionInfo.cost;
+    state.tokens = tokenUsage.input + tokenUsage.output + tokenUsage.reasoning + tokenUsage.cache.read + tokenUsage.cache.write;
+    if (state.cost >= maxCost) state.budgetReason = 'reported cost limit';
+    if (state.productiveTurns > maxTurns) state.budgetReason = 'productive model turn limit exceeded';
+    if (outcome !== 'succeeded' && !state.budgetReason) {
+      state.budgetReason = `session ${outcome}`;
+    }
+    if (!state.budgetReason && (state.turns !== state.productiveTurns + state.providerErrors)) {
+      state.budgetReason = 'incomplete turn accounting';
+      state.errors.push('Transcript did not reconcile all completed assistant turns.');
+    }
+  } catch (error) {
+    if (!state.budgetReason) {
+      if (controller.signal.aborted && Date.now() - started >= timeoutSeconds * 1000) state.budgetReason = 'wall-time limit';
+      else if (controller.signal.aborted && signal?.aborted && /wall.?time/i.test(String(signal.reason?.message || signal.reason || ''))) state.budgetReason = 'wall-time limit';
+      else if (controller.signal.aborted && signal?.aborted) state.budgetReason = 'cancelled';
+      else state.budgetReason = 'native OpenCode request failed';
+    }
+    state.errors.push(error instanceof Error ? error.message : String(error));
+    if (session && !outcome) {
+      try {
+        if (!controller.signal.aborted) {
+          await api.session.wait({ sessionID:session.id }, { signal:AbortSignal.timeout(outcomeTimeoutSeconds * 1000) });
+          const info=await pollOutcome();
+          outcome=info.outcome;
+        }
+      } catch {}
+    }
+    if (session) {
+      try {
+        const info = await api.session.get({ sessionID:session.id }, { signal:AbortSignal.timeout(3000) });
+        if (Number.isFinite(info.cost) && info.cost >= 0) state.cost = info.cost;
+        const usage = info.tokens;
+        if (usage && ['input','output','reasoning'].every(key=>Number.isFinite(usage[key])) && usage.cache && Number.isFinite(usage.cache.read) && Number.isFinite(usage.cache.write)) state.tokens = usage.input+usage.output+usage.reasoning+usage.cache.read+usage.cache.write;
+      } catch {}
+    }
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', abort);
+    finished = true;
+    eventController.abort();
+    if (session && !outcome) {
+      const cleanupMs = 1000;
+      const interruptResult = await bounded(
+        Promise.resolve().then(() => api.session.interrupt(
+          { sessionID: session.id, resume: false },
+          { signal: AbortSignal.timeout(cleanupMs) },
+        )).then(() => true, () => false),
+        cleanupMs,
+        false,
+      );
+      interruptionStatus = interruptResult ? 'requested' : 'unknown';
+      if (!outcome) {
+        const terminal = await bounded(
+          Promise.resolve().then(() => api.session.get(
+            { sessionID: session.id },
+            { signal: AbortSignal.timeout(cleanupMs) },
+          )).catch(() => null),
+          cleanupMs,
+          null,
+        );
+        if (terminal?.outcome) {
+          outcome = terminal.outcome;
+          interruptionStatus = outcome === 'interrupted' ? 'confirmed' : 'unknown';
+        } else {
+          interruptionStatus = 'unknown';
+        }
+      } else {
+        interruptionStatus = outcome === 'interrupted' ? 'confirmed' : 'unknown';
+      }
+    }
+    if (streamTask) await bounded(streamTask.catch(() => {}), 250, undefined);
+  }
+  if (!outcome && !state.budgetReason) {
+    state.budgetReason = 'missing terminal session outcome';
+    state.errors.push('OpenCode session has no authoritative terminal outcome.');
+  }
+  return { ...state, outcome: outcome || null, interruptionStatus, exitCode: state.budgetReason || streamError ? 1 : 0, timedOut: state.budgetReason === 'wall-time limit', durationMs: Date.now() - started, sessionID: session?.id || null, runtime: NATIVE_EVALUATION_RUNTIME, opencodeVersion: version };
+}

package/lib/opencode/file-lock.mjs

@@ -0,0 +1,86 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const alive = pid => {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === 'EPERM'; }
+};
+
+function timeoutError(file, owner) {
+  return new Error(`Timed out waiting for CTG credential lock ${file}${owner?.pid ? ` held by process ${owner.pid}` : ''}. If recovery is stuck, inspect the lock and recovery files before retrying.`);
+}
+
+/** Acquire a cross-process lock with bounded wait and serialized dead-lock recovery. */
+export async function acquireFileLock(file, options = {}) {
+  const timeout = options.timeout ?? 15_000;
+  const deadline = Date.now() + timeout;
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  let handle;
+  const token = randomUUID();
+  while (!handle) {
+    if (Date.now() >= deadline) throw timeoutError(file);
+    try {
+      handle = await open(file, 'wx', 0o600);
+      await handle.writeFile(JSON.stringify({ pid: process.pid, token, startedAt: Date.now() }));
+      await handle.sync();
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        await handle?.close().catch(() => {});
+        handle = undefined;
+        throw error;
+      }
+      let owner;
+      let observed;
+      try { observed = await readFile(file, 'utf8'); owner = JSON.parse(observed); } catch {}
+      const abandoned = owner?.pid
+        ? !alive(owner.pid)
+        : await stat(file).then(details => Date.now() - details.mtimeMs >= (options.staleLockAge ?? 5000)).catch(() => false);
+      if (abandoned) {
+        let recovery;
+        try { recovery = await open(`${file}.recovery`, 'wx', 0o600); }
+        catch (lockError) {
+          if (lockError.code !== 'EEXIST') throw lockError;
+          await new Promise(resolve => setTimeout(resolve, Math.min(options.pollInterval ?? 40, Math.max(1, deadline - Date.now()))));
+          continue;
+        }
+        const recoveryToken = JSON.stringify({ pid: process.pid, token: randomUUID() });
+        try {
+          await recovery.writeFile(recoveryToken);
+          await recovery.sync();
+          const latest = await readFile(file, 'utf8').catch(() => '');
+          let latestOwner;
+          try { latestOwner = JSON.parse(latest); } catch {}
+          if (latest === observed) {
+            const stillAbandoned = latestOwner?.pid
+              ? !alive(latestOwner.pid)
+              : await stat(file).then(details => Date.now() - details.mtimeMs >= (options.staleLockAge ?? 5000)).catch(() => false);
+            if (stillAbandoned) await rm(file, { force: true });
+          }
+        } finally {
+          const currentRecovery = await readFile(`${file}.recovery`, 'utf8').catch(() => '');
+          try { if (currentRecovery === recoveryToken) await rm(`${file}.recovery`, { force: true }); } catch {}
+          await recovery.close();
+        }
+        continue;
+      }
+      if (Date.now() >= deadline) throw timeoutError(file, owner);
+      await new Promise(resolve => setTimeout(resolve, Math.min(options.pollInterval ?? 40, Math.max(1, deadline - Date.now()))));
+    }
+  }
+  let released = false;
+  return async () => {
+    if (released) return;
+    released = true;
+    const owner = await readFile(file, 'utf8').catch(() => '');
+    try { if (JSON.parse(owner).token === token) await rm(file, { force: true }); } catch {}
+    await handle.close();
+  };
+}
+
+/** Cross-process critical section; lock ownership is always released in finally. */
+export async function withFileLock(file, action, options = {}) {
+  const release = await acquireFileLock(file, options);
+  try { return await action(); }
+  finally { await release(); }
+}