@snack-ai/opencode 1.0.3 → 1.0.5

package/README.md

@@ -12,7 +12,10 @@ afterwards.
 
 That difference matters more than it sounds. Some things simply do not survive to disk — a prompt
 the provider refuses outright can leave no durable trace in OpenCode's own database, and a refusal
-SNACK cannot see is a refusal it cannot learn from. The plugin catches those as they happen.
+SNACK cannot see is a refusal it cannot learn from. The plugin catches those as they happen — when
+OpenCode reports one with a status code. OpenCode `1.18.15` retries a 429 itself and reports the
+retry only as the provider's free text, so for such a turn the plugin states no ending at all and
+leaves it to SNACK's reading of the database.
 
 It is deliberately tiny. It appends one line of JSON per event to a private file and gets out of the
 way. It never opens a database, never imports the SNACK CLI, never phones anywhere, and never —
@@ -23,7 +26,7 @@ under any failure — gets between you and your prompt.
 The SNACK CLI registers it in OpenCode's own configuration for you:
 
 ```bash
-npm install -g @snack-ai/cli
+npm install -g --allow-scripts=better-sqlite3 @snack-ai/cli   # builds the SQLite driver; npm 12 skips it otherwise
 snack setup opencode --install-plugin
 ```
 
@@ -42,11 +45,12 @@ metadata:
 
 - which prompt and session it belongs to, by identifier;
 - the provider and model, and when it happened;
-- how it ended: completed, cancelled, an operational error, or an observed restriction and its
-  class;
-- token counts and cost as the provider reported them.
+- how it ended: completed, cancelled, an operational error, or an observed restriction and its class
+  — once per prompt, and not at all for a turn OpenCode retried.
 
-There is no field for prompt text or response text, and the schema refuses unknown fields outright.
+Token counts and cost are not among them: the schema has room for usage, but the plugin leaves it
+empty and SNACK takes usage from OpenCode's database. There is no field for prompt text or response
+text, and the schema refuses unknown fields outright.
 
 With `--enable-prospective-analysis`, each prompt additionally carries a few non-semantic shape
 features: an estimated token count, a bucketed line count, a bucketed count of fenced code blocks,
@@ -75,12 +79,22 @@ would carry an invented meaning downstream for as long as it lived.
 
 Events are appended as NDJSON to segment files with `0600` permissions in a `0700` directory. Append
 is the only write operation; nothing is ever rewritten in place, which is what makes a crash
-mid-write recoverable rather than corrupting.
+mid-write recoverable rather than corrupting. A write that fails is cut back to where it began, and
+an append to a segment that ends mid-line starts on a fresh line, so a broken line never takes the
+next event with it.
 
 A line cut short by a crash is exactly what truncation recovery expects: the reader validates each
 line, discards the incomplete one with a sanitized diagnostic, and keeps everything before it. The
 count of refused records surfaces in `snack sync` as `rejected_invalid` rather than disappearing.
 
+Each append takes a writer lock for the milliseconds it lasts. A lock older than two minutes was
+abandoned, so the plugin and `snack sync` take it over whatever process id it names, and
+`snack doctor` warns with `spool_lock:<alias>` while one is there. The takeover is atomic: two
+writers that judge the same lock abandoned at once never both hold it, and a failed append is
+truncated back only by a writer that still holds the lock. Age is read from the wall clock, so a
+clock jump of more than two minutes, or a laptop resumed mid-append, can take over a lock still
+held; that costs at most the event being written.
+
 Segments are removed only after **every configured source has committed past them**. A cursor that
 advanced without its transaction committing would silently drop history, so cursors move only inside
 the committing transaction.
@@ -104,7 +118,8 @@ and driven through the capture path in tests; a canary reaching any written byte
 
 The provider's own error **code** is stored on purpose — it is what distinguishes a rate limit from
 a timeout, and classifying that difference correctly is the entire reason SNACK does not treat your
-flaky Wi-Fi as a quota event. The error _message_ is not stored.
+flaky Wi-Fi as a quota event. The error _message_ is not stored. A retry status is read for its type
+alone; its message is never kept or classified.
 
 ## Compatibility
 
@@ -113,5 +128,10 @@ Requires Node.js 24 and a `@snack-ai/cli` that accepts `spool-event-v1`. Event `
 version of this plugin. `snack doctor` reports a registration pinned at an older version as outdated
 rather than incompatible, and re-running `snack setup opencode --install-plugin` updates the pin.
 
+On OpenCode `1.18.15`, use `1.0.5` or later. Earlier versions file the first prompt of every session
+under the provider of OpenCode's `small_model`, which names the session, follow a cancelled prompt
+with `success` events, and leave the model name empty. A current `snack sync` keeps the exclusion
+OpenCode's database records for such a cancellation.
+
 Apache-2.0. Security reports go through the private channel in
 [SECURITY.md](https://github.com/Duck1201/snack/blob/main/SECURITY.md).

package/README.pt-BR.md

@@ -12,7 +12,9 @@ O OpenCode já anota o que você fez. Este plugin assiste isso acontecer, em vez
 Essa diferença importa mais do que parece. Algumas coisas simplesmente não sobrevivem até o disco —
 um prompt que o provedor recusa de cara pode não deixar rastro durável no banco do próprio OpenCode,
 e uma recusa que o SNACK não enxerga é uma recusa com a qual ele não aprende. O plugin pega essas no
-ato.
+ato — quando o OpenCode reporta uma com código de status. O OpenCode `1.18.15` repete sozinho um 429
+e reporta a nova tentativa só como texto livre do provedor, então nesse turno o plugin não declara
+desfecho algum e deixa isso para a leitura que o SNACK faz do banco.
 
 Ele é propositalmente minúsculo. Acrescenta uma linha de JSON por evento num arquivo privado e sai
 da frente. Nunca abre banco, nunca importa a CLI do SNACK, nunca liga para lugar nenhum, e nunca —
@@ -23,7 +25,7 @@ sob falha alguma — entra entre você e o seu prompt.
 A CLI do SNACK registra o plugin na configuração do próprio OpenCode para você:
 
 ```bash
-npm install -g @snack-ai/cli
+npm install -g --allow-scripts=better-sqlite3 @snack-ai/cli   # compila o driver SQLite; o npm 12 pula sem isso
 snack setup opencode --install-plugin
 ```
 
@@ -42,12 +44,12 @@ byte-idêntica. Todo campo é metadado:
 
 - a qual prompt e sessão pertence, por identificador;
 - o provedor e o modelo, e quando aconteceu;
-- como terminou: completado, cancelado, um erro operacional, ou uma restrição observada e sua
-  classe;
-- contagens de tokens e custo, como o provedor reportou.
+- como terminou: completado, cancelado, um erro operacional, ou uma restrição observada e sua classe
+  — uma vez por prompt, e nenhuma para um turno que o OpenCode repetiu.
 
-Não existe campo para texto de prompt nem de resposta, e o schema recusa campos desconhecidos de
-forma categórica.
+Contagens de tokens e custo não estão entre eles: o schema tem lugar para uso, mas o plugin o deixa
+vazio e o SNACK tira o uso do banco do OpenCode. Não existe campo para texto de prompt nem de
+resposta, e o schema recusa campos desconhecidos de forma categórica.
 
 Com `--enable-prospective-analysis`, cada prompt carrega também algumas features não semânticas de
 formato: contagem estimada de tokens, contagem de linhas em faixas, contagem de blocos de código em
@@ -77,13 +79,24 @@ não reconhece carregaria um significado inventado rio abaixo por todo o tempo e
 
 Eventos são acrescentados como NDJSON em arquivos de segmento com permissão `0600` num diretório
 `0700`. Acrescentar é a única operação de escrita; nada é reescrito no lugar, e é isso que torna uma
-queda no meio da escrita recuperável em vez de corruptora.
+queda no meio da escrita recuperável em vez de corruptora. Uma escrita que falha é cortada de volta
+até onde começou, e um acréscimo a um segmento que termina no meio de uma linha começa numa linha
+nova, então uma linha quebrada nunca leva o evento seguinte junto.
 
 Uma linha cortada por uma queda é exatamente o que a recuperação de truncamento espera: o leitor
 valida cada linha, descarta a incompleta com um diagnóstico sanitizado, e mantém tudo que veio
 antes. A contagem de registros recusados aparece no `snack sync` como `rejected_invalid` em vez de
 sumir.
 
+Cada acréscimo segura um lock de escrita pelos milissegundos que dura. Um lock com mais de dois
+minutos foi abandonado, então o plugin e o `snack sync` o assumem seja qual for o id de processo que
+ele nomeia, e o `snack doctor` avisa com `spool_lock:<alias>` enquanto houver um. A tomada é
+atômica: dois escritores que julgam o mesmo lock abandonado ao mesmo tempo nunca o seguram juntos, e
+um acréscimo que falhou só é truncado de volta por um escritor que ainda segura o lock. A idade é
+lida no relógio de parede, então um salto de relógio de mais de dois minutos, ou um notebook que
+volta da suspensão no meio de um acréscimo, pode tomar um lock ainda em uso; isso custa no máximo o
+evento sendo escrito.
+
 Segmentos só são removidos depois que **toda fonte configurada commitou além deles**. Um cursor que
 avançasse sem sua transação commitar descartaria histórico em silêncio, então cursores só se movem
 dentro da transação que commita.
@@ -108,7 +121,8 @@ qualquer byte escrito quebra o build.
 
 O **código** de erro do provedor é armazenado de propósito — é o que distingue um rate limit de um
 timeout, e classificar essa diferença corretamente é a razão inteira de o SNACK não tratar o seu
-Wi-Fi instável como evento de quota. A _mensagem_ de erro não é armazenada.
+Wi-Fi instável como evento de quota. A _mensagem_ de erro não é armazenada. Um status de nova
+tentativa é lido só pelo seu tipo; a mensagem dele nunca é guardada nem classificada.
 
 ## Compatibilidade
 
@@ -117,5 +131,10 @@ Requer Node.js 24 e uma `@snack-ai/cli` que aceite `spool-event-v1`. O `schema_v
 publicada dele. O `snack doctor` reporta um registro fixado numa versão antiga como desatualizado, e
 não como incompatível; rodar `snack setup opencode --install-plugin` de novo atualiza o pin.
 
+No OpenCode `1.18.15`, use a `1.0.5` ou posterior. As versões anteriores registram o primeiro prompt
+de toda sessão sob o provedor do `small_model` do OpenCode, que dá nome à sessão, gravam eventos de
+`success` depois de um prompt cancelado, e deixam o nome do modelo vazio. Um `snack sync` atual
+mantém a exclusão que o banco do OpenCode registra para esse cancelamento.
+
 Apache-2.0. Relatos de segurança vão pelo canal privado descrito em
 [SECURITY.md](https://github.com/Duck1201/snack/blob/main/SECURITY.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snack-ai/opencode",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Fail-open OpenCode metadata capture for SNACK",
   "license": "Apache-2.0",
   "repository": {

package/src/plugin.js

@@ -1,25 +1,42 @@
-import { randomUUID } from "node:crypto";
-import { chmod, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
-import process from "node:process";
-import { setTimeout as delay } from "node:timers/promises";
 
-const spoolFilename = "current.open";
+import { appendEvent } from "./spool-writer.js";
+
 const maxPendingWrites = 100;
-const maxSegmentBytes = 1024 * 1024;
+
+/**
+ * Agents OpenCode runs on the side of a prompt, on models of their own: `title` names the session
+ * with `small_model` on its first prompt, `compaction` and `summary` rewrite history. Their
+ * `chat.params` describe a call the prompt did not ask for, so they never route one.
+ */
+const auxiliaryAgents = new Set(["title", "compaction", "summary"]);
+
+/**
+ * @typedef {object} PromptState
+ * @property {string} promptId
+ * @property {string | null} agent
+ * @property {string | null} provider
+ * @property {string | null} model
+ * @property {string} spoolDirectory
+ * @property {boolean} retried
+ * @property {Record<string, unknown>[]} buffered
+ */
 
 /**
  * Fail-open OpenCode plugin entrypoint.
  *
  * @param {unknown} _context
- * @param {{installation_id?: unknown, spool_directory?: unknown, prospective_analysis?: unknown, source_bindings?: unknown}} [options]
+ * @param {{installation_id?: unknown, spool_directory?: unknown, prospective_analysis?: unknown, source_bindings?: unknown} | null} [options]
  */
 export async function SnackOpenCodePlugin(_context, options = {}) {
-  const installationId = stringOrNull(options.installation_id);
-  const spoolDirectory = stringOrNull(options.spool_directory);
-  const captureFeatures = options.prospective_analysis === true;
-  const sourceBindings = bindingMap(options.source_bindings);
-  /** @type {Map<string, {promptId: string, provider: string | null, model: string | null, spoolDirectory: string, buffered: Record<string, unknown>[]}>} */
+  // OpenCode passes whatever the configuration tuple holds, `null` and non-objects included; an
+  // initializer that throws there takes the host down with it.
+  const settings = recordOrNull(options) ?? {};
+  const installationId = stringOrNull(settings.installation_id);
+  const spoolDirectory = stringOrNull(settings.spool_directory);
+  const captureFeatures = settings.prospective_analysis === true;
+  const sourceBindings = bindingMap(settings.source_bindings);
+  /** @type {Map<string, PromptState>} */
   const prompts = new Map();
   let writes = Promise.resolve();
   let pendingWrites = 0;
@@ -59,13 +76,14 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
   /**
    * Route a session's spool directory once its provider is known.
    *
-   * OpenCode declares `model` optional on `chat.message` and does not send it on `1.18.10`, so the
-   * routing decision cannot be taken there. An event written to `_pending` is never attributed and
-   * never revisited, so a prompt whose provider is still unknown is held rather than misfiled, and
-   * released as soon as `chat.params` names one. A prompt whose provider never arrives is released
-   * to `_pending` at the terminal event, which is where it would have gone anyway.
+   * OpenCode declares `model` optional on `chat.message` and does not send it on `1.18.10` or
+   * `1.18.15`; the user message on the hook's output names it there, and older hosts may not. An
+   * event written to `_pending` is never attributed and never revisited, so a prompt whose provider
+   * is still unknown is held rather than misfiled, and released as soon as the prompt's own
+   * `chat.params` names one. A prompt whose provider never arrives is released to `_pending` at
+   * its terminal event, or when the next prompt of its session replaces it.
    *
-   * @param {{provider: string | null, model: string | null, spoolDirectory: string, buffered: Record<string, unknown>[]}} prompt
+   * @param {PromptState} prompt
    */
   const release = (prompt) => {
     for (const event of prompt.buffered.splice(0)) {
@@ -75,19 +93,33 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
 
   return {
     async dispose() {
-      for (const prompt of prompts.values()) release(prompt);
-      await writes;
+      try {
+        for (const prompt of prompts.values()) release(prompt);
+        prompts.clear();
+        await writes;
+      } catch {
+        // Capture must never change OpenCode shutdown behavior.
+      }
     },
     async "chat.params"(/** @type {Record<string, unknown>} */ input) {
       try {
         const sessionId = stringOrNull(input.sessionID);
         const prompt = sessionId ? prompts.get(sessionId) : undefined;
         if (!prompt || prompt.provider || !spoolDirectory) return;
+        // Only the call that answers this prompt routes it. On 1.18.15 the session title is
+        // generated with `small_model` -- possibly another provider -- and its `chat.params`
+        // arrives first, on the first prompt of every session.
+        const agent = stringOrNull(input.agent);
+        if (agent !== null && auxiliaryAgents.has(agent)) return;
+        if (prompt.agent !== null && agent !== null && agent !== prompt.agent) return;
+        const answered = stringOrNull(recordOrNull(input.message)?.id);
+        if (answered !== null && answered !== prompt.promptId) return;
         const model = recordOrNull(input.model);
         const provider = stringOrNull(model?.providerID);
         if (!provider) return;
         prompt.provider = provider;
-        prompt.model = stringOrNull(model?.modelID);
+        // `chat.params` carries the provider's model record, which names the model `id`.
+        prompt.model = stringOrNull(model?.id) ?? stringOrNull(model?.modelID);
         prompt.spoolDirectory = sourceBindings.get(provider) ?? join(spoolDirectory, "_pending");
         release(prompt);
       } catch {
@@ -103,20 +135,27 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
         const outputMessage = recordOrNull(recordOrNull(output)?.message);
         const promptId = stringOrNull(input.messageID) ?? stringOrNull(outputMessage?.id);
         if (!sessionId || !promptId || !spoolDirectory) return;
-        const model = recordOrNull(input.model);
+        const model = recordOrNull(input.model) ?? recordOrNull(outputMessage?.model);
         const provider = stringOrNull(model?.providerID);
         const modelId = stringOrNull(model?.modelID);
         const targetDirectory = provider
           ? (sourceBindings.get(provider) ?? join(spoolDirectory, "_pending"))
           : join(spoolDirectory, "_pending");
         if (!targetDirectory) return;
+        /** @type {PromptState} */
         const prompt = {
           promptId,
+          agent: stringOrNull(input.agent) ?? stringOrNull(outputMessage?.agent),
           provider,
           model: modelId,
           spoolDirectory: targetDirectory,
-          /** @type {Record<string, unknown>[]} */ buffered: [],
+          retried: false,
+          buffered: [],
         };
+        // A prompt queued behind one still held for its provider replaces it here; what the
+        // earlier one buffered is released, to `_pending`, rather than dropped.
+        const previous = prompts.get(sessionId);
+        if (previous) release(previous);
         prompts.set(sessionId, prompt);
         const occurredAt = new Date().toISOString();
         const started = {
@@ -148,15 +187,32 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
       try {
         const event = recordOrNull(input.event);
         const type = stringOrNull(event?.type);
-        if (type !== "session.idle" && type !== "session.error") return;
+        if (type !== "session.idle" && type !== "session.error" && type !== "session.status")
+          return;
         const properties = recordOrNull(event?.properties) ?? {};
         const sessionId = stringOrNull(properties.sessionID);
         const prompt = sessionId ? prompts.get(sessionId) : undefined;
         if (!sessionId || !prompt) return;
+        if (type === "session.status") {
+          // Only the status's type is read. Its `message` is the provider's free text and is
+          // never kept, compared, or classified.
+          if (stringOrNull(recordOrNull(properties.status)?.type) === "retry")
+            prompt.retried = true;
+          return;
+        }
+        // One terminal per prompt. 1.18.15 emits `session.idle` after `session.error`, twice after
+        // an abort, and again after every later `/shell` or `/summarize`: a prompt still in the map
+        // would be re-emitted, each time later than the last.
+        prompts.delete(sessionId);
+        release(prompt);
+        // OpenCode retries a 429 itself and reports it only as `session.status` `retry`, which
+        // carries no structured status code; the turn then ends in `session.idle` whether it
+        // succeeded or was cancelled. `spool-event-v1` lets `session_idle` say only `success`, so a
+        // retried turn states no terminal at all and backfill, which reads how it ended, decides.
+        if (type === "session.idle" && prompt.retried) return;
         const occurredAt = timestampOrNow(properties.time);
         const error = recordOrNull(properties.error);
         const restricted = type === "session.error" && isExplicitRateLimit(error);
-        release(prompt);
         append(prompt.spoolDirectory, {
           schema_version: 1,
           event_id: `${type}:${sessionId}:${prompt.promptId}:${occurredAt}`,
@@ -191,103 +247,6 @@ export async function SnackOpenCodePlugin(_context, options = {}) {
   };
 }
 
-/** @param {string} spoolDirectory @param {Record<string, unknown>} event */
-async function appendEvent(spoolDirectory, event) {
-  await mkdir(spoolDirectory, { recursive: true, mode: 0o700 });
-  await chmod(spoolDirectory, 0o700);
-  const release = await acquireSpoolLock(spoolDirectory);
-  try {
-    const file = join(spoolDirectory, spoolFilename);
-    try {
-      if ((await stat(file)).size >= maxSegmentBytes) {
-        await rename(file, join(spoolDirectory, `segment-${Date.now()}-${randomUUID()}.ndjson`));
-      }
-    } catch (error) {
-      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
-    }
-    const handle = await open(file, "a", 0o600);
-    try {
-      await handle.writeFile(`${JSON.stringify(event)}\n`, "utf8");
-      await handle.sync();
-    } finally {
-      await handle.close();
-    }
-    await chmod(file, 0o600);
-  } finally {
-    await release();
-  }
-}
-
-/** @param {string} spoolDirectory */
-async function acquireSpoolLock(spoolDirectory) {
-  const lock = join(spoolDirectory, ".writer.lock");
-  const token = randomUUID();
-  for (let attempt = 0; attempt < 4; attempt += 1) {
-    try {
-      const handle = await open(lock, "wx", 0o600);
-      await handle.writeFile(`${JSON.stringify({ pid: process.pid, token })}\n`, "utf8");
-      await handle.sync();
-      if ((await readSpoolLock(lock))?.token !== token) {
-        await handle.close();
-        if (attempt < 3) continue;
-        throw new Error("Spool writer lost lock ownership.");
-      }
-      return async () => {
-        await handle.close();
-        if ((await readSpoolLock(lock))?.token === token) await rm(lock, { force: true });
-      };
-    } catch (error) {
-      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
-      const owner = await readSpoolLock(lock);
-      if (owner !== null && !processIsAlive(owner.pid)) {
-        await rm(lock, { force: true });
-        continue;
-      }
-      if (owner === null && (await lockIsStale(lock))) {
-        await rm(lock, { force: true });
-        continue;
-      }
-      if (attempt < 3) await delay(2);
-    }
-  }
-  throw new Error("Spool writer is busy.");
-}
-
-/** @param {string} lock */
-async function lockIsStale(lock) {
-  try {
-    return Date.now() - (await stat(lock)).mtimeMs > 120_000;
-  } catch {
-    return false;
-  }
-}
-
-/** @param {string} lock */
-async function readSpoolLock(lock) {
-  try {
-    const value = JSON.parse(await readFile(lock, "utf8"));
-    return recordOrNull(value) &&
-      typeof value.pid === "number" &&
-      Number.isSafeInteger(value.pid) &&
-      value.pid > 0 &&
-      typeof value.token === "string"
-      ? { pid: value.pid, token: value.token }
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-/** @param {number} pid */
-function processIsAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error instanceof Error && "code" in error && error.code === "EPERM";
-  }
-}
-
 /** @param {unknown} output */
 function analyzePrompt(output) {
   const parts = recordOrNull(output)?.parts;
@@ -346,8 +305,13 @@ function isExplicitRateLimit(error) {
 
 /** @param {unknown} value */
 function timestampOrNow(value) {
-  if (typeof value === "string" && !Number.isNaN(Date.parse(value)))
-    return new Date(value).toISOString();
+  if (typeof value === "string") {
+    const parsed = new Date(value);
+    const year = parsed.getUTCFullYear();
+    // `toISOString` spells a year outside 0000-9999 with a sign and six digits, which the schema's
+    // `date-time` refuses -- the line would be read back as corruption.
+    if (!Number.isNaN(parsed.getTime()) && year >= 0 && year <= 9999) return parsed.toISOString();
+  }
   return new Date().toISOString();
 }
 

package/src/spool-writer.js

@@ -0,0 +1,229 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import * as nodeFs from "node:fs/promises";
+import { join } from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+
+const spoolFilename = "current.open";
+const maxSegmentBytes = 1024 * 1024;
+/**
+ * A lock is held for the milliseconds one append takes; one this old was abandoned. Judged by the
+ * wall clock against the lock's mtime, so a clock jump of more than this, or a laptop resumed
+ * mid-append, can take over a lock still held. That costs at most one event; the takeover below
+ * and the check before a truncate keep it from costing another writer's.
+ */
+const staleLockMs = 120_000;
+
+/**
+ * The file operations the writer performs, injectable so a test can interleave two writers.
+ *
+ * @typedef {Pick<typeof import("node:fs/promises"), "chmod" | "link" | "mkdir" | "open" | "readFile" | "rename" | "rm" | "stat">} SpoolFs
+ */
+
+/**
+ * Append one event to a spool directory's open segment, under its writer lock.
+ *
+ * @param {string} spoolDirectory
+ * @param {Record<string, unknown>} event
+ * @param {SpoolFs} [fs]
+ */
+export async function appendEvent(spoolDirectory, event, fs = nodeFs) {
+  await fs.mkdir(spoolDirectory, { recursive: true, mode: 0o700 });
+  await fs.chmod(spoolDirectory, 0o700);
+  const lock = await acquireSpoolLock(spoolDirectory, fs);
+  try {
+    const file = join(spoolDirectory, spoolFilename);
+    try {
+      if ((await fs.stat(file)).size >= maxSegmentBytes) {
+        await fs.rename(file, join(spoolDirectory, `segment-${Date.now()}-${randomUUID()}.ndjson`));
+      }
+    } catch (error) {
+      if (!hasCode(error, "ENOENT")) throw error;
+    }
+    const handle = await fs.open(file, "a+", 0o600);
+    try {
+      // A write cut short -- a full disk, a file-size limit, a killed host -- leaves a line with no
+      // newline, and the next event appended to it is glued on and lost with it. Starting on a
+      // fresh line confines the damage to the line that was already broken.
+      const { size } = await handle.stat();
+      const separator = size > 0 && !(await endsWithNewline(handle, size)) ? "\n" : "";
+      try {
+        await handle.writeFile(`${separator}${JSON.stringify(event)}\n`, "utf8");
+        await handle.sync();
+      } catch (error) {
+        // Take back whatever part of this event landed, so the failure leaves no partial line --
+        // only while this writer still holds the lock. One whose lock was taken over may share the
+        // file with the writer that took it, and cutting back to `size` would erase that writer's
+        // line; a partial line is the lesser loss, and it rejects only itself.
+        if (await lock.holds()) await handle.truncate(size).catch(() => {});
+        throw error;
+      }
+    } finally {
+      await handle.close();
+    }
+    await fs.chmod(file, 0o600);
+  } finally {
+    await lock.release();
+  }
+}
+
+/**
+ * Take a spool directory's writer lock.
+ *
+ * A lock whose writer is gone, or which is older than any append, is taken over. Two writers can
+ * judge the same lock abandoned at once, and removing it by path let the slower one delete the lock
+ * the faster one had just created in its place, so both held it. A takeover therefore moves the
+ * lock aside to a name of its own -- `rename` moves exactly one file -- and only proceeds when what
+ * it moved is the lock it judged. Having moved a lock another writer took in the meantime, it puts
+ * that lock back with `link`, which never replaces a lock created since.
+ *
+ * @param {string} spoolDirectory
+ * @param {SpoolFs} [fs]
+ * @returns {Promise<{holds: () => Promise<boolean>, release: () => Promise<void>}>}
+ */
+export async function acquireSpoolLock(spoolDirectory, fs = nodeFs) {
+  const lock = join(spoolDirectory, ".writer.lock");
+  const token = randomUUID();
+  const holds = async () => (await inspectLock(fs, lock))?.owner?.token === token;
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    /** @type {import("node:fs/promises").FileHandle} */
+    let handle;
+    try {
+      handle = await fs.open(lock, "wx", 0o600);
+    } catch (error) {
+      if (!hasCode(error, "EEXIST")) throw error;
+      const held = await inspectLock(fs, lock);
+      // Our own token in a lock we gave up on is a lock a takeover moved and put back while we
+      // were checking it: it is abandoned by definition.
+      if (held !== null && (held.owner?.token === token || isAbandoned(held))) {
+        await takeOver(fs, lock, held);
+        continue;
+      }
+      if (attempt < 3) await delay(2);
+      continue;
+    }
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, token })}\n`, "utf8");
+    await handle.sync();
+    if (!(await holds())) {
+      await handle.close();
+      continue;
+    }
+    return {
+      holds,
+      async release() {
+        await handle.close();
+        const held = await inspectLock(fs, lock);
+        if (held?.owner?.token === token) await takeOver(fs, lock, held);
+      },
+    };
+  }
+  throw new Error("Spool writer is busy.");
+}
+
+/**
+ * Remove the lock `judged` described, and nothing else.
+ *
+ * @param {SpoolFs} fs
+ * @param {string} lock
+ * @param {LockState} judged
+ */
+async function takeOver(fs, lock, judged) {
+  const tombstone = `${lock}.${randomUUID()}.stale`;
+  try {
+    await fs.rename(lock, tombstone);
+  } catch (error) {
+    // Another writer moved it first; whatever is there now is judged afresh.
+    if (hasCode(error, "ENOENT")) return;
+    throw error;
+  }
+  const moved = await inspectLock(fs, tombstone);
+  if (
+    moved !== null &&
+    moved.ino === judged.ino &&
+    moved.mtimeMs === judged.mtimeMs &&
+    moved.owner?.token === judged.owner?.token
+  ) {
+    await fs.rm(tombstone, { force: true });
+    return;
+  }
+  // Not the lock that was judged: a writer that took over first holds it. Put it back, unless a
+  // lock was created in its place meanwhile, which then stands.
+  try {
+    await fs.link(tombstone, lock);
+  } catch (error) {
+    if (!hasCode(error, "EEXIST")) await fs.rename(tombstone, lock).catch(() => {});
+  }
+  await fs.rm(tombstone, { force: true });
+}
+
+/**
+ * @typedef {{ino: number, mtimeMs: number, owner: {pid: number, token: string} | null}} LockState
+ */
+
+/**
+ * @param {SpoolFs} fs
+ * @param {string} lock
+ * @returns {Promise<LockState | null>}
+ */
+async function inspectLock(fs, lock) {
+  let stats;
+  try {
+    stats = await fs.stat(lock);
+  } catch {
+    return null;
+  }
+  return { ino: stats.ino, mtimeMs: stats.mtimeMs, owner: await readOwner(fs, lock) };
+}
+
+/**
+ * Age decides before the pid does: a pid that answers `kill(pid, 0)` may have been reused, or
+ * belong to another user, and a lock held that long is not being used by anyone.
+ *
+ * @param {LockState} held
+ */
+function isAbandoned(held) {
+  return (
+    (held.owner !== null && !processIsAlive(held.owner.pid)) ||
+    Date.now() - held.mtimeMs > staleLockMs
+  );
+}
+
+/** @param {SpoolFs} fs @param {string} lock */
+async function readOwner(fs, lock) {
+  try {
+    const value = JSON.parse(await fs.readFile(lock, "utf8"));
+    return typeof value === "object" &&
+      value !== null &&
+      typeof value.pid === "number" &&
+      Number.isSafeInteger(value.pid) &&
+      value.pid > 0 &&
+      typeof value.token === "string"
+      ? { pid: value.pid, token: value.token }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {import("node:fs/promises").FileHandle} handle @param {number} size */
+async function endsWithNewline(handle, size) {
+  const last = Buffer.alloc(1);
+  await handle.read(last, 0, 1, size - 1);
+  return last[0] === 0x0a;
+}
+
+/** @param {number} pid */
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return hasCode(error, "EPERM");
+  }
+}
+
+/** @param {unknown} error @param {string} code */
+function hasCode(error, code) {
+  return error instanceof Error && "code" in error && error.code === code;
+}