arisa 5.2.17 → 5.2.20

package/LOW-MEMORY.md

@@ -0,0 +1,37 @@
+# Low-memory operation
+
+Arisa can use swap to keep cold pages out of RAM. Swap occupancy alone does not indicate failure: sustained swap-in/out, memory PSI, disk wait, worker restarts and operation latency are the useful signals. Do not run `swapoff` to clear swap on a constrained host, or increase every Node heap to mask an allocation problem.
+
+## Artifact index
+
+The artifact store uses Node's bundled SQLite support (Node >=22.19) and the chat-scoped `getChatArtifactsDatabaseFile(chatId)` path helper. `getChatArtifactsIndexFile(chatId)` still identifies the legacy JSON file, not the live database. Tools must access artifacts through Arisa IPC, not parse storage files.
+
+- Each operation opens its database, uses a 1 MiB page cache with mmap disabled, then closes it. There is no resident history cache per chat.
+- Writes insert one artifact. ID lookups and recent-item queries use indexes; history size does not determine their JS heap consumption.
+- `listRecent` accepts integer limits from 0 to 1000; 0 returns no items. Results are read incrementally and rejected if their combined serialized size exceeds 16 MiB; callers can reduce the limit or retrieve individual IDs. Memory still depends on individual record size.
+- SQLite serializes writes across processes. FULL synchronous commits and rollback journaling preserve atomic writes without accumulating an unbounded WAL.
+- The CLI loads agent, bootstrap, slave and TUI modules only in the branches that need them. The persistent service supervisor does not load the worker's agent dependencies.
+
+### Migration and backups
+
+First access to an uninitialized database streams the legacy JSON array one object at a time into a single transaction. Artifact IDs, scope, all fields and insertion order are preserved. Duplicate IDs, invalid chat identities or malformed/truncated input abort the whole migration. A failed migration leaves the original unchanged and can be retried after repairing the input. Memory scales with the largest individual legacy record, not total history size.
+
+A committed database has schema version 1. Subsequent operations do not read or import the legacy JSON again. The original JSON is retained unchanged as a pre-migration backup, but **does not contain later writes**. Never delete a live database assuming that the legacy file is current.
+
+Back up the SQLite database with SQLite's backup API, or stop all writers and copy it along with any journal files. Preserve artifact files separately. A rollback to an older JSON-only core requires stopping all writers, backing up the database, and streaming `SELECT data FROM artifacts ORDER BY seq` into a new JSON array. Fsync and atomically replace the legacy index only after export succeeds. Do not simply revert the code and resume writes to the old JSON snapshot.
+
+## Daemons
+
+Keep external ingress daemons running. Request-driven tools should use `autoStart: false` in both their manifest and runtime registration, start through the shared runtime when invoked, and stop when idle. Otherwise the supervisor will repeatedly restart a daemon that deliberately stopped for inactivity. Do not disable ingress or drop sessions to improve a memory benchmark.
+
+## Verification
+
+Run the test suite serially on 1 GiB hosts:
+
+```sh
+node --test --test-concurrency=1
+```
+
+`test/artifact-index-memory.test.js` migrates a 100 MiB index and runs 300 subsequent operations in a child with a 48 MiB V8 heap. Migration tests cover UTF-8 chunk boundaries, escaping, corruption, rollback/retry, stable IDs, ordering and concurrent writers in separate processes. `test/cli-memory.test.js` runs the status command with a 24 MiB heap.
+
+After deployment, check a real scheduled tool result, PID continuity, daemon health, `free -h`, `vmstat 1`, and `/proc/pressure/memory`. Short observations cannot establish long-term stability or guarantee that every browser workload fits this host.

package/README.md

@@ -102,7 +102,8 @@ Global:
 
 Per chat (`~/.arisa/chats/<chatId>/`):
 - artifact files are stored under `artifacts/`
-- the artifact index is stored in `state/artifacts.json`
+- the artifact index is stored in `state/artifacts.sqlite`; the legacy `state/artifacts.json` is imported once, incrementally, and retained unchanged as a migration backup
+- artifact reads and writes use indexed SQLite operations rather than loading the chat's complete history into memory; see [low-memory operation and migration](LOW-MEMORY.md)
 - Pi sessions live under `state/pi-sessions/<revision>/`
 - chat-scoped tool config overrides live in `config/tools/<tool>/config.js`
 - chat-scoped daemon infrastructure lives in `state/tools/<tool>/daemon/`; persistent tool data stays beside it
@@ -127,8 +128,10 @@ Slave runs only the IPC host, daemon supervisor and installed tools. Connections
 are authenticated, encrypted, initiated by Slave and restricted by per-Slave
 roots and capability grants.
 
-Linux with systemd is the first supported Slave target. Bootstrap uses a
-single-use URL issued by Master:
+Arisa Slave supports Linux with systemd, macOS with launchd, and Windows with
+Task Scheduler. On desktop systems, run bootstrap as the normal user so the
+persistent background task retains access to that user's browser profile.
+Bootstrap uses a single-use URL issued by Master:
 
 ```bash
 npm i -g arisa && arisa slave tcp://198.51.100.12:4719/arisa_secret_v1_<secret>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arisa",
-  "version": "5.2.17",
+  "version": "5.2.20",
   "description": "Telegram + Pi Agent modular assistant",
   "type": "module",
   "main": "src/index.js",
@@ -29,7 +29,7 @@
   "author": "Martin Clasen",
   "license": "MIT",
   "engines": {
-    "node": ">=22.8.0"
+    "node": ">=22.19.0"
   },
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
   },
   "homepage": "https://arisa.sh",
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.6",
+    "@earendil-works/pi-coding-agent": "0.85.1",
     "@sinclair/typebox": "^0.34.41",
     "grammy": "^1.42.0"
   },

package/pnpm-workspace.yaml

@@ -1,11 +1,13 @@
 allowBuilds:
   '@google/genai': false
+  esbuild: true
 
 minimumReleaseAgeExclude:
-  - '@earendil-works/pi-agent-core@0.80.6'
-  - '@earendil-works/pi-ai@0.80.6'
-  - '@earendil-works/pi-coding-agent@0.80.6'
-  - '@earendil-works/pi-tui@0.80.6'
+  - '@earendil-works/pi-agent-core@0.85.1'
+  - '@earendil-works/pi-ai@0.85.1'
+  - '@earendil-works/pi-coding-agent@0.85.1'
+  - '@earendil-works/pi-tui@0.85.1'
+  - '@earendil-works/chord@0.85.1'
 
 overrides:
   'node-fetch@2.7.0>whatwg-url': '13.0.0'
@@ -14,7 +16,7 @@ overrides:
   basic-ftp@<=5.2.2: '>=5.3.0'
   basic-ftp@<=5.3.0: '>=5.3.1'
   basic-ftp@=5.2.0: '>=5.2.1'
-  brace-expansion@>=5.0.0 <5.0.6: '>=5.0.6'
+  brace-expansion@>=4.0.0 <5.0.9: '5.0.9'
   ip-address@<=10.1.0: '>=10.1.1'
   protobufjs@<7.5.5: '>=7.5.5'
   protobufjs@<=7.5.5: '>=7.5.6'

package/src/core/agent/agent-manager.js

@@ -323,22 +323,21 @@ export class AgentManager {
 
   async validatePiAgent(config = this.config) {
     this.logger?.log("agent", "validating Pi session");
-    const { authStorage, modelRegistry } = createPiRuntime({
+    const modelRuntime = await createPiRuntime({
       provider: config.pi.provider,
       apiKey: config.pi.apiKey
     });
-    const model = modelRegistry.find(config.pi.provider, config.pi.model);
+    const model = modelRuntime.getModel(config.pi.provider, config.pi.model);
     if (!model) {
       throw new Error(`Model not found: ${config.pi.provider}/${config.pi.model}`);
     }
-    if (requiresProviderAuth(model) && !config.pi.apiKey && !hasProviderAuth(config.pi.provider, { authStorage, modelRegistry })) {
+    if (requiresProviderAuth(model) && !config.pi.apiKey && !hasProviderAuth(config.pi.provider, modelRuntime)) {
       throw new Error(`No auth found for ${config.pi.provider}. Provide a Pi API key in bootstrap, or authenticate with Pi login for this provider during bootstrap.`);
     }
 
     const settingsManager = createPiSettingsManager(config);
     const { session } = await createAgentSession({
-      authStorage,
-      modelRegistry,
+      modelRuntime,
       model,
       settingsManager,
       sessionManager: SessionManager.inMemory()
@@ -386,13 +385,13 @@ export class AgentManager {
       this.pendingNewSessions.add(sessionKey);
     }
 
-    const { authStorage, modelRegistry } = createPiRuntime({
+    const modelRuntime = await createPiRuntime({
       provider: this.config.pi.provider,
       apiKey: this.config.pi.apiKey
     });
-    const model = modelRegistry.find(this.config.pi.provider, effectiveModelId);
+    const model = modelRuntime.getModel(this.config.pi.provider, effectiveModelId);
     if (!model) throw new Error(`Model not found: ${this.config.pi.provider}/${effectiveModelId}`);
-    if (requiresProviderAuth(model) && !this.config.pi.apiKey && !hasProviderAuth(this.config.pi.provider, { authStorage, modelRegistry })) {
+    if (requiresProviderAuth(model) && !this.config.pi.apiKey && !hasProviderAuth(this.config.pi.provider, modelRuntime)) {
       throw new Error(`No auth found for ${this.config.pi.provider}. Re-run bootstrap and complete login for this provider before Telegram starts.`);
     }
     const thinkingLevel = clampModelThinkingLevel(model, modelSelection.thinkingLevel);
@@ -418,7 +417,8 @@ export class AgentManager {
       initializeForumTopic: (...args) => telegramTarget.current.initializeForumTopic(...args),
       prepareRestartReceipt: (...args) => telegramTarget.current.prepareRestartReceipt(...args),
       cancelRestartReceipt: (...args) => telegramTarget.current.cancelRestartReceipt(...args),
-      getTaskContext: (...args) => telegramTarget.current.getTaskContext?.(...args) || null
+      getTaskContext: (...args) => telegramTarget.current.getTaskContext?.(...args) || null,
+      getAgentTaskExecution: (...args) => telegramTarget.current.getAgentTaskExecution?.(...args) || null
     };
     const assertAccess = () => accessGuardTarget.current();
     const customTools = guardTools([
@@ -440,8 +440,7 @@ export class AgentManager {
       cwd: policy.workspaceDir,
       agentDir: arisaHomeDir,
       resourceLoader,
-      authStorage,
-      modelRegistry,
+      modelRuntime,
       model,
       thinkingLevel,
       tools: policy.tools,
@@ -450,8 +449,8 @@ export class AgentManager {
       settingsManager,
       sessionManager
     });
-    const speedController = createModelSpeedController(session.agent.streamFn, speed);
-    session.agent.streamFn = speedController.streamFn;
+    const speedController = createModelSpeedController(session.agent.streamFunction, speed);
+    session.agent.streamFunction = speedController.streamFn;
 
     if (!hasExistingSession) {
       this.logger?.log("agent", `created new session for chat ${sessionKey}`);
@@ -479,7 +478,7 @@ export class AgentManager {
 
   async getAvailableModels(chatId) {
     const { listProviderModels } = await import("./pi-runtime.js");
-    const runtime = createPiRuntime({ provider: this.config.pi.provider, apiKey: this.config.pi.apiKey });
+    const runtime = await createPiRuntime({ provider: this.config.pi.provider, apiKey: this.config.pi.apiKey });
     return listProviderModels(this.config.pi.provider, runtime);
   }
 

package/src/core/agent/auth-flow.js

@@ -33,8 +33,8 @@ export function getPiAuthIssue(error) {
   return null;
 }
 
-export function getPiAuthStatus(config, chatId = null) {
-  const runtime = createPiRuntime({
+export async function getPiAuthStatus(config, chatId = null) {
+  const runtime = await createPiRuntime({
     provider: config.pi.provider,
     apiKey: config.pi.apiKey
   });
@@ -51,8 +51,8 @@ export function getPiAuthStatus(config, chatId = null) {
   };
 }
 
-export function buildPiAuthTelegramMessage({ config, chatId = null, issue = null, verified = false }) {
-  const status = getPiAuthStatus(config, chatId);
+export async function buildPiAuthTelegramMessage({ config, chatId = null, issue = null, verified = false }) {
+  const status = await getPiAuthStatus(config, chatId);
   let title = `Pi authentication status for ${status.provider}/${status.model}.`;
   if (issue) {
     title = `Pi authentication needs attention for ${status.provider}/${status.model}.`;
@@ -95,8 +95,8 @@ export function buildPiAuthTelegramMessage({ config, chatId = null, issue = null
   return lines.join("\n");
 }
 
-export function buildPiAuthRecoveryBlockedMessage({ config, chatId = null, issue = null, renewalActive = false }) {
-  const status = getPiAuthStatus(config, chatId);
+export async function buildPiAuthRecoveryBlockedMessage({ config, chatId = null, issue = null, renewalActive = false }) {
+  const status = await getPiAuthStatus(config, chatId);
   const lines = [
     `Pi authentication is not ready for ${status.provider}/${status.model}.`,
     "I did not send your message to the agent."

package/src/core/agent/model-selection.js

@@ -1,4 +1,4 @@
-import { normalizeModelSpeed } from "./model-speed.js";
+import { modelFastSpeed, normalizeModelSpeed } from "./model-speed.js";
 
 function chatKey(chatId) {
   return String(chatId);
@@ -49,9 +49,10 @@ export function resolveChatThinkingLevel(config, chatId) {
 }
 
 export function resolveChatSpeed(config, chatId) {
-  const speed = resolveChatModelSelection(config, chatId).speed;
+  const { speed, model } = resolveChatModelSelection(config, chatId);
   if (speed === undefined) throw new Error("Model speed is not configured for the active runtime");
-  return speed;
+  // Preserve legacy fast selections while displaying the model-specific multiplier.
+  return speed > 1 ? modelFastSpeed(model) : speed;
 }
 
 export function selectChatModel(config, chatId, model, { thinkingLevel, speed } = {}) {

package/src/core/agent/model-speed.js

@@ -1,4 +1,4 @@
-export const MODEL_SPEEDS = Object.freeze([1, 1.5]);
+export const MODEL_SPEEDS = Object.freeze([1, 1.5, 2]);
 
 export function normalizeModelSpeed(speed) {
   const value = Number(speed);
@@ -17,16 +17,25 @@ export function modelSupportsSpeed(model) {
       || model.id === "gpt-5.5"
       || model.id === "gpt-5.6"
       || model.id.startsWith("gpt-5.6-")
+      || model.id === "gpt-6-astra"
     );
 }
 
+export function modelFastSpeed(modelId) {
+  return modelId === "gpt-6-astra" ? 2 : 1.5;
+}
+
+export function listModelSpeeds(model) {
+  return modelSupportsSpeed(model) ? [1, modelFastSpeed(model.id)] : [1];
+}
+
 export function clampModelSpeed(model, speed) {
   const normalized = normalizeModelSpeed(speed);
-  return normalized === 1.5 && !modelSupportsSpeed(model) ? 1 : normalized;
+  return normalized > 1 && modelSupportsSpeed(model) ? modelFastSpeed(model.id) : 1;
 }
 
 export function speedToServiceTier(speed) {
-  return normalizeModelSpeed(speed) === 1.5 ? "priority" : "default";
+  return normalizeModelSpeed(speed) > 1 ? "priority" : "default";
 }
 
 export function createModelSpeedController(streamFn, initialSpeed) {
@@ -40,6 +49,7 @@ export function createModelSpeedController(streamFn, initialSpeed) {
       speed = normalizeModelSpeed(nextSpeed);
     },
     streamFn(model, context, options) {
+      if (!modelSupportsSpeed(model)) return streamFn(model, context, options);
       const serviceTier = speedToServiceTier(speed);
       const onPayload = options?.onPayload;
       return streamFn(model, context, {

package/src/core/agent/pi-auth-login.js

@@ -1,13 +1,6 @@
-import { AuthStorage } from "@earendil-works/pi-coding-agent";
-import { piAuthFile } from "../../platform/paths.js";
+import { createPiRuntime, supportsProviderOAuth } from "./pi-runtime.js";
 
 export function createPiOAuthLogin({ provider, onAuth, onDeviceCode, onPrompt, onProgress, onSelect } = {}) {
-  const authStorage = AuthStorage.create(piAuthFile);
-  const oauthProvider = authStorage.getOAuthProviders().find((item) => item.id === provider);
-  if (!oauthProvider) {
-    throw new Error(`No internal OAuth login flow is available for ${provider}.`);
-  }
-
   let resolveManualCode;
   const manualCodePromise = new Promise((resolve) => {
     resolveManualCode = resolve;
@@ -15,7 +8,6 @@ export function createPiOAuthLogin({ provider, onAuth, onDeviceCode, onPrompt, o
 
   const controller = {
     provider,
-    oauthProvider,
     manualInputRequested: false,
     submitManualCode(value) {
       if (!resolveManualCode) return false;
@@ -31,25 +23,33 @@ export function createPiOAuthLogin({ provider, onAuth, onDeviceCode, onPrompt, o
     promise: null
   };
 
-  controller.promise = authStorage.login(provider, {
-    onAuth: async (params) => {
-      await onAuth?.({ ...params, controller });
-    },
-    onDeviceCode: async (params) => {
-      await onDeviceCode?.({ ...params, controller });
-    },
-    onPrompt: async (params) => {
-      if (!onPrompt) return "";
-      return onPrompt({ ...params, controller });
-    },
-    onProgress: (message) => {
-      onProgress?.(message);
-    },
-    onSelect: async (params) => {
-      if (!onSelect) return params.options?.[0]?.id;
-      return onSelect({ ...params, controller });
-    },
-    onManualCodeInput: () => controller.waitForManualCode()
+  controller.promise = createPiRuntime().then(async (runtime) => {
+    if (!supportsProviderOAuth(provider, runtime)) {
+      throw new Error(`No internal OAuth login flow is available for ${provider}.`);
+    }
+    let notifications = Promise.resolve();
+    let notificationError;
+    const credential = await runtime.login(provider, "oauth", {
+      notify(event) {
+        notifications = notifications.then(async () => {
+          if (event.type === "auth_url") await onAuth?.({ ...event, controller });
+          else if (event.type === "device_code") await onDeviceCode?.({ ...event, controller });
+          else await onProgress?.(event.message);
+        }).catch((error) => { notificationError = error; });
+      },
+      async prompt(params) {
+        await notifications;
+        if (notificationError) throw notificationError;
+        if (params.type === "select") {
+          return onSelect ? onSelect({ ...params, controller }) : params.options?.[0]?.id;
+        }
+        if (params.type === "manual_code") return controller.waitForManualCode();
+        return onPrompt ? onPrompt({ ...params, controller }) : "";
+      }
+    });
+    await notifications;
+    if (notificationError) throw notificationError;
+    return credential;
   }).finally(() => {
     controller.submitManualCode("");
   });

package/src/core/agent/pi-capability-tools.js

@@ -47,6 +47,7 @@ export function createPiCapabilityTools({ capabilityService, telegram, chatId, p
     context: {
       ...baseContext,
       taskContext: telegram.getTaskContext(),
+      agentTaskExecution: telegram.getAgentTaskExecution?.() || null,
       ...context
     }
   });

package/src/core/agent/pi-runtime.js

@@ -1,34 +1,29 @@
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { piAuthFile } from "../../platform/paths.js";
 
 function compareText(a, b) {
   return a.localeCompare(b, undefined, { sensitivity: "base", numeric: true });
 }
 
-export function createPiRuntime({ provider, apiKey } = {}) {
-  const authStorage = AuthStorage.create(piAuthFile);
+export async function createPiRuntime({ provider, apiKey } = {}) {
+  const runtime = await ModelRuntime.create({ authPath: piAuthFile });
   if (provider && apiKey) {
-    authStorage.setRuntimeApiKey(provider, apiKey);
+    await runtime.setRuntimeApiKey(provider, apiKey);
   }
-  const modelRegistry = ModelRegistry.create(authStorage);
-  const oauthProviders = authStorage.getOAuthProviders();
-  return { authStorage, modelRegistry, oauthProviders };
+  return runtime;
 }
 
-export function hasProviderAuth(provider, { authStorage, modelRegistry }) {
-  return modelRegistry.hasConfiguredAuth(provider) || authStorage.hasAuth(provider);
+export function hasProviderAuth(provider, runtime) {
+  return runtime.getProviderAuthStatus(provider).configured;
 }
 
-export function supportsProviderOAuth(provider, { oauthProviders }) {
-  return oauthProviders.some((item) => item.id === provider);
+export function supportsProviderOAuth(provider, runtime) {
+  return Boolean(runtime.getProvider(provider)?.auth.oauth);
 }
 
-export function listPiProviders(runtime = createPiRuntime()) {
-  const { modelRegistry, oauthProviders } = runtime;
-  const allModels = modelRegistry.getAll();
-  const oauthIds = new Set(oauthProviders.map((item) => item.id));
+export function listPiProviders(runtime) {
   const counts = new Map();
-  for (const model of allModels) {
+  for (const model of runtime.getModels()) {
     counts.set(model.provider, (counts.get(model.provider) || 0) + 1);
   }
 
@@ -36,7 +31,7 @@ export function listPiProviders(runtime = createPiRuntime()) {
     .map((provider) => ({
       provider,
       authConfigured: hasProviderAuth(provider, runtime),
-      supportsOAuth: oauthIds.has(provider),
+      supportsOAuth: supportsProviderOAuth(provider, runtime),
       modelCount: counts.get(provider) || 0
     }))
     .sort((a, b) => {
@@ -46,10 +41,8 @@ export function listPiProviders(runtime = createPiRuntime()) {
     });
 }
 
-export function listProviderModels(provider, runtime = createPiRuntime()) {
-  return runtime.modelRegistry
-    .getAll()
-    .filter((model) => model.provider === provider)
+export function listProviderModels(provider, runtime) {
+  return [...runtime.getModels(provider)]
     .sort((a, b) => compareText(a.name || a.id, b.name || b.id));
 }
 

package/src/core/artifacts/artifact-index.js

@@ -0,0 +1,107 @@
+import { mkdir, open } from "node:fs/promises";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { readLegacyArtifacts } from "./legacy-artifact-reader.js";
+
+const operations = new Map();
+
+async function serialize(file, operation) {
+  const previous = operations.get(file) || Promise.resolve();
+  const current = previous.catch(() => {}).then(operation);
+  operations.set(file, current);
+  try {
+    return await current;
+  } finally {
+    if (operations.get(file) === current) operations.delete(file);
+  }
+}
+
+async function createPrivateFile(file) {
+  await mkdir(path.dirname(file), { recursive: true });
+  try {
+    const handle = await open(file, "wx", 0o600);
+    await handle.close();
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+}
+
+function insertArtifact(db, artifact) {
+  db.prepare("INSERT INTO artifacts (id, data) VALUES (?, ?)")
+    .run(artifact.id, JSON.stringify(artifact));
+}
+
+async function importLegacy(db, legacyFile, chatId) {
+  const insert = db.prepare("INSERT INTO artifacts (id, data) VALUES (?, ?)");
+  try {
+    for await (const artifact of readLegacyArtifacts(legacyFile)) {
+      if (!artifact || typeof artifact.id !== "string" || !artifact.id
+        || String(artifact.chatId) !== chatId) {
+        throw new Error("Invalid artifact identity or chat scope");
+      }
+      insert.run(artifact.id, JSON.stringify(artifact));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw new Error(`Artifact index is unreadable: ${legacyFile}`, { cause: error });
+    }
+  }
+}
+
+async function initialize(db, legacyFile, chatId) {
+  const version = () => db.prepare("PRAGMA user_version").get().user_version;
+  if (version() === 1) return;
+  if (version() !== 0) throw new Error("Unsupported artifact database version");
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    // Another process may have completed migration while this connection waited.
+    if (version() === 0) {
+      db.exec("CREATE TABLE artifacts (seq INTEGER PRIMARY KEY, id TEXT NOT NULL UNIQUE, data TEXT NOT NULL)");
+      await importLegacy(db, legacyFile, chatId);
+      db.exec("PRAGMA user_version = 1");
+    }
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+// Open only for the operation: no per-chat resident history or idle DB cache.
+// SQLite transactions coordinate separate Arisa processes as well as store instances.
+export function withArtifactIndex({ databaseFile, legacyFile, chatId }, operation) {
+  return serialize(databaseFile, async () => {
+    await createPrivateFile(databaseFile);
+    const db = new DatabaseSync(databaseFile);
+    try {
+      db.exec("PRAGMA busy_timeout = 30000; PRAGMA cache_size = -1024; PRAGMA mmap_size = 0; PRAGMA synchronous = FULL");
+      await initialize(db, legacyFile, chatId);
+      return await operation(db);
+    } finally {
+      db.close();
+    }
+  });
+}
+
+export function appendArtifact(db, artifact) {
+  insertArtifact(db, artifact);
+  return artifact;
+}
+
+export function getArtifact(db, id) {
+  const row = db.prepare("SELECT data FROM artifacts WHERE id = ?").get(id);
+  return row ? JSON.parse(row.data) : null;
+}
+
+export function listRecentArtifacts(db, limit) {
+  const artifacts = [];
+  let bytes = 0;
+  for (const row of db.prepare("SELECT data FROM artifacts ORDER BY seq DESC LIMIT ?").iterate(limit)) {
+    bytes += Buffer.byteLength(row.data, "utf8");
+    if (bytes > 16 * 1024 * 1024) {
+      throw new RangeError("Recent artifacts exceed 16 MiB; request a smaller limit or retrieve individual IDs");
+    }
+    artifacts.push(JSON.parse(row.data));
+  }
+  return artifacts;
+}