@agentdocumentformat/cli 0.7.8 → 0.8.1

package/dist/chunks/{chunk-HSBV6YFU.mjs → chunk-LVF2DRBR.mjs}

@@ -7,11 +7,19 @@ const __dirname = __adfDirname(__filename);
 import {
   DEFAULT_AGENT_CONFIG,
   DOCS_GUIDES_URL
-} from "./chunk-G6PH7RPW.mjs";
+} from "./chunk-E7LC6SHP.mjs";
 import {
   nanoid
 } from "./chunk-3GNIDM53.mjs";
 import {
+  applyFileRefChanges,
+  isAudioInputMime,
+  isFileRefBlock,
+  isVideoInputMime,
+  isVisionMime
+} from "./chunk-LKFHERRV.mjs";
+import {
+  AUDIT_DEFAULTS,
   CODE_EXECUTION_DEFAULTS,
   DEFAULT_MIND_CONTENT,
   DEFAULT_MIND_LOG_CONTENT,
@@ -20,8 +28,9 @@ import {
   LOOP_PROHIBITED_TOOLS,
   META_PROTECTION_LEVELS,
   SETTABLE_STATES,
-  getDefaultDocumentContent
-} from "./chunk-CD3ATSXE.mjs";
+  getDefaultDocumentContent,
+  hasLoopGoal
+} from "./chunk-BR3AD5QZ.mjs";
 import {
   __esm,
   __export
@@ -211,38 +220,6 @@ var TEXT_MIME_PREFIXES = ["text/"], TEXT_MIME_EXACT = /* @__PURE__ */ new Set([
 function isTextMime(mime) {
   return mime ? TEXT_MIME_PREFIXES.some((p) => mime.startsWith(p)) || /\+(json|xml|yaml)$/.test(mime) ? !0 : TEXT_MIME_EXACT.has(mime) : !1;
 }
-var VISION_MIMES = /* @__PURE__ */ new Set([
-  "image/png",
-  "image/jpeg",
-  "image/gif",
-  "image/webp"
-]);
-function isVisionMime(mime) {
-  return mime ? VISION_MIMES.has(mime) : !1;
-}
-var AUDIO_INPUT_MIMES = /* @__PURE__ */ new Set([
-  "audio/wav",
-  "audio/mpeg",
-  "audio/mp3",
-  "audio/aiff",
-  "audio/aac",
-  "audio/ogg",
-  "audio/flac",
-  "audio/x-m4a",
-  "audio/webm"
-]);
-function isAudioInputMime(mime) {
-  return mime ? AUDIO_INPUT_MIMES.has(mime) : !1;
-}
-var VIDEO_INPUT_MIMES = /* @__PURE__ */ new Set([
-  "video/mp4",
-  "video/mpeg",
-  "video/quicktime",
-  "video/webm"
-]);
-function isVideoInputMime(mime) {
-  return mime ? VIDEO_INPUT_MIMES.has(mime) : !1;
-}
 var AUDIO_FORMAT_MAP = {
   "audio/wav": "wav",
   "audio/mpeg": "mp3",
@@ -462,7 +439,7 @@ var catHandler = {
   async execute(ctx) {
     if (ctx.args.length < 2) return err("cp: usage: cp <src> <dst>");
     let src = vfsPath(ctx.args[0]), dst = vfsPath(ctx.args[1]), [content, readErr] = await shellReadFile(ctx.toolRegistry, ctx.workspace, src);
-    if (readErr) return err(`cp: ${readErr}`);
+    if (readErr !== null) return err(`cp: ${readErr}`);
     let write = await ctx.toolRegistry.executeTool("fs_write", { mode: "write", path: dst, content }, ctx.workspace);
     return write.isError ? err(`cp: ${write.content}`) : ok("");
   }
@@ -717,7 +694,7 @@ var duHandler = {
       let bytes = parseInt(raw, 10), content = ctx.stdin;
       if (ctx.args.length > 0) {
         let [fileContent, error] = await shellReadFile(ctx.toolRegistry, ctx.workspace, vfsPath(ctx.args[0]));
-        if (error) return err(`head: ${error}`);
+        if (error !== null) return err(`head: ${error}`);
         content = fileContent;
       }
       return content ? ok(Buffer.from(content, "utf8").subarray(0, bytes).toString("utf8")) : ok("");
@@ -729,7 +706,7 @@ var duHandler = {
     let text = ctx.stdin;
     if (ctx.args.length > 0) {
       let [content, error] = await shellReadFile(ctx.toolRegistry, ctx.workspace, vfsPath(ctx.args[0]), { end_line: n });
-      return error ? err(`head: ${error}`) : ok(content);
+      return error !== null ? err(`head: ${error}`) : ok(content);
     }
     if (!text) return ok("");
     let lines = text.split(`
@@ -761,7 +738,7 @@ var duHandler = {
       let fromByte = raw.startsWith("+"), bytes = parseInt(raw, 10), content = ctx.stdin;
       if (ctx.args.length > 0) {
         let [fileContent, error] = await shellReadFile(ctx.toolRegistry, ctx.workspace, vfsPath(ctx.args[0]));
-        if (error) return err(`tail: ${error}`);
+        if (error !== null) return err(`tail: ${error}`);
         content = fileContent;
       }
       if (!content) return ok("");
@@ -779,7 +756,7 @@ var duHandler = {
     let text = ctx.stdin;
     if (ctx.args.length > 0) {
       let [content, error] = await shellReadFile(ctx.toolRegistry, ctx.workspace, vfsPath(ctx.args[0]));
-      if (error) return err(`tail: ${error}`);
+      if (error !== null) return err(`tail: ${error}`);
       text = content;
     }
     if (!text) return ok("");
@@ -1217,7 +1194,7 @@ var GREP_KNOWN_FLAGS = /* @__PURE__ */ new Set([
       for (let file of files) {
         if (file.mime_type && !isTextMime(file.mime_type)) continue;
         let [content, readErr] = await shellReadFile(ctx.toolRegistry, ctx.workspace, file.path);
-        if (readErr) continue;
+        if (readErr !== null) continue;
         let lines2 = splitLines(content), sel2 = await select(lines2, content?.length ?? 0);
         if ("failure" in sel2) return sel2.failure;
         let fileMatches = sel2.idx.length;
@@ -1236,7 +1213,7 @@ var GREP_KNOWN_FLAGS = /* @__PURE__ */ new Set([
     let text = ctx.stdin;
     if (fileArgs.length === 1) {
       let [content, readErr] = await shellReadFile(ctx.toolRegistry, ctx.workspace, vfsPath2(fileArgs[0]));
-      if (readErr) return err(`grep: ${fileArgs[0]}: No such file or directory`);
+      if (readErr !== null) return err(`grep: ${fileArgs[0]}: No such file or directory`);
       text = content;
     }
     if (!text)
@@ -1320,7 +1297,7 @@ var SED_KNOWN_FLAGS = /* @__PURE__ */ new Set(["i", "E", "r"]), sedHandler = {
     if (ctx.args.length > 1) {
       filePath = vfsPath2(ctx.args[1]);
       let [sedContent, sedErr] = await shellReadFile(ctx.toolRegistry, ctx.workspace, filePath);
-      if (sedErr) return err(`sed: ${filePath}: No such file or directory`);
+      if (sedErr !== null) return err(`sed: ${filePath}: No such file or directory`);
       text = sedContent;
     } else if (!text)
       return ok("");
@@ -1585,7 +1562,7 @@ var xargsHandler = {
       batchSize = n;
     }
     if (!text) return ok("");
-    let { parse } = await import("./parser-JVY2PWSM.mjs"), { executeNode } = await import("./pipeline-executor-O77NTGLP.mjs"), subCtx = {
+    let { parse } = await import("./parser-7GARNT5L.mjs"), { executeNode } = await import("./pipeline-executor-DRYEEFDR.mjs"), subCtx = {
       workspace: ctx.workspace,
       toolRegistry: ctx.toolRegistry,
       config: ctx.config,
@@ -2405,7 +2382,7 @@ async function executeShellScript(path, ctx) {
     authorized = ctx.workspace.isFileAuthorized(path);
   } catch {
   }
-  let gate = { ...ctx.gate ?? {}, authorized }, base = baseRegistry(ctx.toolRegistry), toolRegistry = gate.authorized ? authorizedRegistry(base) : base, { parse } = await import("./parser-JVY2PWSM.mjs"), { executeNode, MAX_SHELL_DEPTH } = await import("./pipeline-executor-O77NTGLP.mjs"), depth = (ctx.depth ?? 0) + 1;
+  let gate = { ...ctx.gate ?? {}, authorized }, base = baseRegistry(ctx.toolRegistry), toolRegistry = gate.authorized ? authorizedRegistry(base) : base, { parse } = await import("./parser-7GARNT5L.mjs"), { executeNode, MAX_SHELL_DEPTH } = await import("./pipeline-executor-DRYEEFDR.mjs"), depth = (ctx.depth ?? 0) + 1;
   if (depth > MAX_SHELL_DEPTH)
     return err(`./${path}: script nesting too deep (${MAX_SHELL_DEPTH}) \u2014 possible infinite recursion`);
   try {
@@ -2621,9 +2598,105 @@ import { createPrivateKey as createPrivateKey3, createPublicKey as createPublicK
 // src/main/adf/adf-database.ts
 import Database from "better-sqlite3";
 import * as sqliteVec from "sqlite-vec";
-import { existsSync as existsSync2, unlinkSync, renameSync, copyFileSync, readdirSync, readFileSync as readFileSync3, openSync, closeSync, lstatSync, fstatSync, promises as fsp } from "fs";
+import { existsSync as existsSync2, unlinkSync, renameSync, copyFileSync, readdirSync, readFileSync as readFileSync3, openSync, closeSync, lstatSync, fstatSync, fsyncSync, statSync, promises as fsp } from "fs";
+import { createHash } from "crypto";
 import { brotliDecompressSync } from "zlib";
-import { join as join2, resolve, sep } from "path";
+import { basename, dirname as dirname2, join as join2, resolve, sep } from "path";
+
+// src/main/adf/file-ref-registry.ts
+var MediaPayloadCache = class {
+  constructor(maxChars) {
+    this.maxChars = maxChars;
+  }
+  maxChars;
+  entries = /* @__PURE__ */ new Map();
+  chars = 0;
+  get(path) {
+    let entry = this.entries.get(path);
+    if (entry)
+      return this.entries.delete(path), this.entries.set(path, entry), entry;
+  }
+  set(path, entry) {
+    if (this.delete(path), !(entry.payload.length > this.maxChars)) {
+      this.entries.set(path, entry), this.chars += entry.payload.length;
+      for (let [oldest, value] of this.entries) {
+        if (this.chars <= this.maxChars) break;
+        this.entries.delete(oldest), this.chars -= value.payload.length;
+      }
+    }
+  }
+  delete(path) {
+    let entry = this.entries.get(path);
+    entry && (this.entries.delete(path), this.chars -= entry.payload.length);
+  }
+  clear() {
+    this.entries.clear(), this.chars = 0;
+  }
+  get size() {
+    return this.entries.size;
+  }
+}, MEDIA_CACHE_MAX_CHARS = 48 * 1024 * 1024, FileRefRegistry = class {
+  /**
+   * Paths some transcript row references. Null until first needed: built by
+   * one scan of adf_loop, then kept current by every loop write. May hold
+   * paths whose rows are gone (cleared, compacted); that only costs a scan.
+   */
+  referenced = null;
+  media = new MediaPayloadCache(MEDIA_CACHE_MAX_CHARS);
+  /** Bumped when a file a request has carried changes, so resolved requests rebuild. */
+  generation = 0;
+  /** Paths a request has carried. */
+  resolved = /* @__PURE__ */ new Set();
+  holders = /* @__PURE__ */ new Set();
+  addHolder(holder) {
+    this.holders.add(new WeakRef(holder));
+  }
+  /** Record the references in a loop row just written. */
+  noteContent(content) {
+    if (this.referenced)
+      for (let block of content)
+        isFileRefBlock(block) && !block.file_ref.deleted && this.referenced.add(block.file_ref.path);
+  }
+  /** Whether any of these changes names a referenced path (`referenced` must be built). */
+  affects(changes) {
+    let referenced = this.referenced;
+    return referenced ? changes.some((change) => referenced.has(change.op === "rename" ? change.from : change.path)) : !0;
+  }
+  /** Keep `referenced` current after the rows were rewritten. */
+  noteChanges(changes) {
+    let referenced = this.referenced;
+    if (referenced)
+      for (let change of changes)
+        change.op !== "rename" || !referenced.has(change.from) || (referenced.delete(change.from), referenced.add(change.to));
+  }
+  /** Rewrite the references every live session holds. */
+  notifyHolders(changes) {
+    for (let ref of this.holders) {
+      let holder = ref.deref();
+      if (!holder) {
+        this.holders.delete(ref);
+        continue;
+      }
+      try {
+        holder.applyFileRefChanges(changes);
+      } catch (error) {
+        console.error("[FileRefRegistry] A session could not apply a file change:", error);
+      }
+    }
+  }
+  /** A file was written, renamed or deleted: its loaded bytes are stale. */
+  invalidate(path) {
+    this.media.delete(path), this.resolved.has(path) && this.generation++;
+  }
+}, byFile = /* @__PURE__ */ new Map(), byDatabase = /* @__PURE__ */ new WeakMap();
+function fileRefRegistry(database, canonicalPath) {
+  if (canonicalPath === null) {
+    let registry4 = byDatabase.get(database);
+    return registry4 || (registry4 = new FileRefRegistry(), byDatabase.set(database, registry4)), registry4;
+  }
+  let registry3 = byFile.get(canonicalPath);
+  return registry3 || (registry3 = new FileRefRegistry(), byFile.set(canonicalPath, registry3)), registry3;
+}
 
 // src/shared/constants/agent-icons.ts
 var AGENT_ICON_POOL = [
@@ -2834,7 +2907,20 @@ function didToPublicKey(did) {
 }
 
 // src/main/adf/adf-database.ts
-var nanoid2 = () => nanoid(10), LOOP_TOOLS_BACKFILL_META = "adf_loop_tools_backfilled", LEGACY_ESSENTIAL_LOOP_TOOLS = ["loop_send", "loop_list"], ADF_LATEST_SCHEMA_VERSION = 32, CLEAN_CLOSE_META_KEY = "adf_clean_close", SNAPSHOT_DEADLINE_MS = 3e4, OPFLAG_P2ISREG = 16;
+var nanoid2 = () => nanoid(10), LOOP_TOOLS_BACKFILL_META = "adf_loop_tools_backfilled", LEGACY_ESSENTIAL_LOOP_TOOLS = ["loop_send", "loop_list"], ADF_LATEST_SCHEMA_VERSION = 32, ADF_OLDEST_MIGRATABLE_SCHEMA_VERSION = 3, AdfSchemaTooOldError = class extends Error {
+  constructor(filePath, schemaVersion, opts = {}) {
+    let name = basename(filePath);
+    super(
+      (schemaVersion > 0 ? `${name} uses schema v${schemaVersion}, which this version cannot upgrade` : `${name} has no schema version and an older layout, which this version cannot upgrade`) + ` (it upgrades v${ADF_OLDEST_MIGRATABLE_SCHEMA_VERSION} and later; no released version upgrades older files).${opts.unchanged === !1 ? "" : " The file was not changed."} See "An agent file uses schema v2" in the ADF troubleshooting guide.`
+    );
+    this.filePath = filePath;
+    this.schemaVersion = schemaVersion;
+    this.name = "AdfSchemaTooOldError";
+  }
+  filePath;
+  schemaVersion;
+  code = "schema_too_old";
+}, CLEAN_CLOSE_META_KEY = "adf_clean_close", SNAPSHOT_DEADLINE_MS = 3e4, OPFLAG_P2ISREG = 16;
 function formatMetaNumber(n) {
   return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(10)));
 }
@@ -3144,7 +3230,12 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   /** Page cap for getLogsAfterId — pollers carry a cursor, so pages catch up. */
   static MAX_LOGS_AFTER_ID = 5e3;
   constructor(db, filePath) {
-    this.db = db, this.filePath = filePath, _AdfDatabase.incrementOpen(filePath), this.applyPragmas(), this.prepareStatements();
+    this.db = db, this.filePath = filePath, _AdfDatabase.incrementOpen(filePath);
+    try {
+      this.applyPragmas(), this.prepareStatements();
+    } catch (err2) {
+      throw _AdfDatabase.decrementOpen(filePath), err2;
+    }
   }
   // ===========================================================================
   // Static Factory Methods
@@ -3154,6 +3245,36 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
     let code = err2?.code;
     return typeof code == "string" && (code.startsWith("SQLITE_BUSY") || code === "SQLITE_LOCKED");
   }
+  /**
+   * The file's schema version: `adf_schema_version`, else the older
+   * `schema_version`, else 0. Null when there is no adf_meta table. Reads only.
+   */
+  static readSchemaVersion(db) {
+    if (!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='adf_meta'").get()) return null;
+    let r = db.prepare("SELECT value FROM adf_meta WHERE key = 'adf_schema_version'").get(), parse = (v) => {
+      let n = parseInt(v, 10);
+      return Number.isFinite(n) ? n : 0;
+    };
+    if (r) return parse(r.value);
+    let r2 = db.prepare("SELECT value FROM adf_meta WHERE key = 'schema_version'").get();
+    return r2 ? parse(r2.value) : 0;
+  }
+  /**
+   * The schema version open() refuses for this file, or null when it may be
+   * opened (and migrated). 1 <= v < 3 is refused. No version at all (0, or
+   * unparsable) is refused unless the file has a clone's layout: a clone
+   * whose adf_meta was deselected (before clone-fixup restamped the version)
+   * has `adf_audit`, `adf_loop.loop` and no `adf_archive`. Null too without
+   * an adf_meta table (the v0.2 check reports that). Reads only.
+   */
+  static refusedSchemaVersion(db) {
+    let sv = _AdfDatabase.readSchemaVersion(db);
+    if (sv === null) return null;
+    if (sv > 0 && sv < ADF_OLDEST_MIGRATABLE_SCHEMA_VERSION) return sv;
+    if (sv > 0) return null;
+    let tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((t) => t.name)), loopCols = tables.has("adf_loop") ? new Set(db.prepare("PRAGMA table_info(adf_loop)").all().map((c) => c.name)) : /* @__PURE__ */ new Set();
+    return tables.has("adf_audit") && !tables.has("adf_archive") && loopCols.has("loop") ? null : 0;
+  }
   /** Retryable lock-contention error — distinct from the corruption path. */
   static lockedError(filePath) {
     return new Error(
@@ -3224,18 +3345,146 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   }
   /** Synchronous backup — only for `open()`, which cannot await mid-migration.
    *  A file copy is safe HERE and only here: open() runs before any writer of
-   *  this connection exists, so nothing can checkpoint underneath it. */
+   *  this connection exists, so nothing can checkpoint underneath it.
+   *  `complete`: the checkpoint folded the whole WAL first, so the copy holds
+   *  every committed write (a failed open may restore from it).
+   *  `reused`: a `.bak` already on disk has the same size and SHA-256 as the
+   *  checkpointed file (a migration that failed before and rolled back), so
+   *  it is kept as is instead of being moved aside and copied again. The
+   *  copy is fsynced. */
   static backupBeforeDestructiveSync(db, filePath) {
-    let backupPath = filePath + ".bak";
+    let backupPath = filePath + ".bak", complete = !1;
+    try {
+      let [ck] = db.pragma("wal_checkpoint(TRUNCATE)");
+      complete = ck?.busy === 0;
+    } catch {
+    }
+    if (_AdfDatabase.sameFileContent(filePath, backupPath)) return { backupPath, complete, reused: !0 };
     try {
       renameSync(backupPath, _AdfDatabase.staleBackupName(backupPath));
     } catch {
     }
+    return copyFileSync(filePath, backupPath), _AdfDatabase.fsyncFileSync(backupPath), { backupPath, complete, reused: !1 };
+  }
+  /** Both files exist with the same size and SHA-256. */
+  static sameFileContent(a, b) {
     try {
-      db.pragma("wal_checkpoint(TRUNCATE)");
+      if (statSync(a).size !== statSync(b).size) return !1;
+      let hash = (p) => createHash("sha256").update(readFileSync3(p)).digest("hex");
+      return hash(a) === hash(b);
     } catch {
+      return !1;
     }
-    return copyFileSync(filePath, backupPath), backupPath;
+  }
+  static fsyncFileSync(path) {
+    let fd = openSync(path, "r+");
+    try {
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+  }
+  /** POSIX: make a rename in `dir` durable. Windows cannot open a directory for fsync. */
+  static fsyncDirSync(dir) {
+    if (process.platform !== "win32")
+      try {
+        let fd = openSync(dir, "r");
+        try {
+          fsyncSync(fd);
+        } finally {
+          closeSync(fd);
+        }
+      } catch {
+      }
+  }
+  /**
+   * After a failure that followed a committed migration (the constructor):
+   * put the file back as its pre-migration backup. The `.bak` is kept (it is
+   * removed only after a fully successful open). Null when restored, else
+   * why not (the caller says so in its error).
+   *
+   * Only when no other connection can hold the file: none in this process,
+   * no -wal left beside it (SQLite removes it at the last close), and an
+   * exclusive lock taken with busy_timeout 0. The copy is fsynced before the
+   * rename. On POSIX the rename happens while that lock is held, so nothing
+   * can open the old file in between (a connection that opened it earlier
+   * would have held a lock). On Windows the lock's own handle would block the
+   * rename, so the probe closes first: the rename itself then fails while any
+   * other program has the file open.
+   *
+   * Known POSIX residual (tracker §6, W5-H): the probe closes after the
+   * rename, and SQLite's close unlinks `<file>-wal` by path. A program that
+   * opens the restored file and writes in that window can lose its WAL.
+   * Closing first would drop the lock, and better-sqlite3 cannot keep the
+   * WAL on close (no SQLITE_FCNTL_PERSIST_WAL), so the window is not closed.
+   */
+  static restoreBackupSync(filePath) {
+    let backupPath = filePath + ".bak";
+    if (!existsSync2(backupPath)) return "there is no backup";
+    let busy = "another connection has the file open";
+    if (_AdfDatabase.openCounts.has(_AdfDatabase.canonicalKey(filePath)) || existsSync2(`${filePath}-wal`)) return busy;
+    let restorePath = `${filePath}.restore`, probe = null;
+    try {
+      copyFileSync(backupPath, restorePath), _AdfDatabase.fsyncFileSync(restorePath);
+      try {
+        probe = new Database(filePath, { fileMustExist: !0 }), probe.pragma("busy_timeout = 0"), probe.pragma("locking_mode = EXCLUSIVE"), probe.exec("BEGIN IMMEDIATE; COMMIT");
+      } catch {
+        try {
+          probe?.close();
+        } catch {
+        }
+        probe = null;
+        try {
+          unlinkSync(restorePath);
+        } catch {
+        }
+        return busy;
+      }
+      process.platform === "win32" && (probe.close(), probe = null);
+      try {
+        unlinkSync(`${filePath}-shm`);
+      } catch {
+      }
+      return renameSync(restorePath, filePath), _AdfDatabase.fsyncDirSync(dirname2(filePath)), null;
+    } catch (err2) {
+      try {
+        unlinkSync(restorePath);
+      } catch {
+      }
+      let code = err2?.code;
+      return code === "EPERM" || code === "EBUSY" || code === "EACCES" ? busy : `the restore failed (${err2 instanceof Error ? err2.message : String(err2)})`;
+    } finally {
+      try {
+        probe?.close();
+      } catch {
+      }
+    }
+  }
+  /**
+   * A failed open(): roll back is the caller's; here the connection is
+   * closed, the file is put back from the backup when `restore` (the failure
+   * followed a committed migration), and the sidecars this open created are
+   * reaped. Returns the sentence to add to the error when the file could not
+   * be restored, else null.
+   */
+  static abandonOpen(db, filePath, opts) {
+    try {
+      db.close();
+    } catch {
+    }
+    let note = null;
+    if (opts.backup && !opts.restore)
+      console.error(`[AdfDatabase] Open failed; the migration was rolled back, the file is unchanged. Backup kept at: ${filePath}.bak`);
+    else if (opts.restore) {
+      let why = opts.backup ? opts.backup.complete ? _AdfDatabase.restoreBackupSync(filePath) : "the backup may lack writes another connection had not checkpointed" : "there is no backup";
+      why === null ? console.error(`[AdfDatabase] Open failed after migrating; restored ${filePath} from its backup, kept at ${filePath}.bak`) : (note = `${basename(filePath)} was migrated and could not be put back from its backup because ${why}; the backup is kept at ${filePath}.bak`, console.error(`[AdfDatabase] ${note}`));
+    }
+    if (!opts.walExistedBeforeOpen)
+      try {
+        _AdfDatabase.reapSidecars(filePath);
+      } catch {
+      }
+    return note;
   }
   /** Remove a transient .bak file after a successful destructive operation. */
   static async removeBackup(filePath) {
@@ -3290,6 +3539,29 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
    *   'reaped'      — WAL folded into the main file, sidecars removed
    *   'error'       — open/checkpoint/unlink failed; sidecars left in place
    */
+  /**
+   * True when no other connection holds `filePath`'s write lock: a probe
+   * connection takes it with BEGIN IMMEDIATE (waiting at most
+   * `busyTimeoutMs`) and gives it back at once. False on SQLITE_BUSY. Lets a
+   * background job (the boot envelope sweep) pass over a file another
+   * connection is writing instead of blocking in AdfWorkspace.open, whose
+   * maintenance writes wait the full busy_timeout. Other errors throw.
+   */
+  static writeLockFree(filePath, busyTimeoutMs) {
+    let db = null;
+    try {
+      return db = new Database(filePath, { fileMustExist: !0 }), db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`), db.exec("BEGIN IMMEDIATE; ROLLBACK"), !0;
+    } catch (err2) {
+      let code = err2?.code;
+      if (typeof code == "string" && code.startsWith("SQLITE_BUSY")) return !1;
+      throw err2;
+    } finally {
+      try {
+        db?.close();
+      } catch {
+      }
+    }
+  }
   static reapSidecars(filePath) {
     let walPath = `${filePath}-wal`, shmPath = `${filePath}-shm`;
     if (!existsSync2(walPath) && !existsSync2(shmPath)) return "no-sidecars";
@@ -3376,7 +3648,40 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         }
   }
   static open(filePath, options) {
-    let walExistedBeforeOpen = existsSync2(`${filePath}-wal`) || existsSync2(`${filePath}-shm`), db = new Database(filePath), needsMigration = !1, integrityMode = "full";
+    let walExistedBeforeOpen = existsSync2(`${filePath}-wal`) || existsSync2(`${filePath}-shm`);
+    if (walExistedBeforeOpen) {
+      let ro = null, refused = null;
+      try {
+        ro = new Database(filePath, { readonly: !0, fileMustExist: !0 }), refused = _AdfDatabase.refusedSchemaVersion(ro);
+      } catch (err2) {
+        if (_AdfDatabase.isBusyError(err2)) throw _AdfDatabase.lockedError(filePath);
+      } finally {
+        try {
+          ro?.close();
+        } catch {
+        }
+      }
+      if (refused !== null) throw new AdfSchemaTooOldError(filePath, refused);
+    }
+    let db = new Database(filePath), needsMigration = !1, backup = null, migrated = !1, repaired = !1;
+    if (!walExistedBeforeOpen) {
+      let refused = null;
+      try {
+        refused = _AdfDatabase.refusedSchemaVersion(db);
+      } catch (err2) {
+        if (_AdfDatabase.isBusyError(err2))
+          throw db.close(), _AdfDatabase.lockedError(filePath);
+      }
+      if (refused !== null) {
+        db.close();
+        try {
+          _AdfDatabase.reapSidecars(filePath);
+        } catch {
+        }
+        throw new AdfSchemaTooOldError(filePath, refused);
+      }
+    }
+    let integrityMode = "full";
     if (!options?.forceIntegrityCheck) {
       let closedCleanly = !1;
       try {
@@ -3392,7 +3697,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
       let checkPragma = integrityMode === "quick" ? "quick_check" : "integrity_check", status = (integrityMode === "none" ? [{ [checkPragma]: "ok" }] : db.pragma(checkPragma))[0]?.[checkPragma];
       if (status !== "ok")
         if (console.warn(`[AdfDatabase] Integrity check failed: ${status}`), db.close(), _AdfDatabase.tryRepair(filePath)) {
-          if (db = new Database(filePath), db.pragma("integrity_check")[0]?.integrity_check !== "ok")
+          if (db = new Database(filePath), repaired = !0, db.pragma("integrity_check")[0]?.integrity_check !== "ok")
             throw db.close(), new Error(
               `ADF file is corrupt and auto-repair failed. A backup was saved at: ${filePath}.corrupt`
             );
@@ -3412,7 +3717,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         throw _AdfDatabase.lockedError(filePath);
       }
       if (console.warn("[AdfDatabase] Integrity check threw:", error), db.close(), _AdfDatabase.tryRepair(filePath))
-        db = new Database(filePath);
+        db = new Database(filePath), repaired = !0;
       else
         throw new Error(
           "ADF file is corrupt and could not be repaired. Please delete and recreate the file."
@@ -3425,16 +3730,22 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         throw db.close(), new Error(
           "This ADF file does not have the v0.2 schema. Please delete and recreate the file."
         );
+      let refused;
+      try {
+        refused = _AdfDatabase.refusedSchemaVersion(db);
+      } catch (err2) {
+        throw _AdfDatabase.isBusyError(err2) ? _AdfDatabase.lockedError(filePath) : new Error(
+          `Cannot read the schema version of ${basename(filePath)}: ${err2 instanceof Error ? err2.message : String(err2)}. The file was not migrated.`,
+          { cause: err2 }
+        );
+      }
+      if (refused !== null)
+        throw new AdfSchemaTooOldError(filePath, refused, { unchanged: !walExistedBeforeOpen && !repaired });
       try {
         db.prepare("DELETE FROM adf_meta WHERE key = ?").run(CLEAN_CLOSE_META_KEY), db.pragma("wal_checkpoint(PASSIVE)");
       } catch {
       }
-      let sv = (() => {
-        let r = db.prepare("SELECT value FROM adf_meta WHERE key = 'adf_schema_version'").get();
-        if (r) return parseInt(r.value, 10);
-        let r2 = db.prepare("SELECT value FROM adf_meta WHERE key = 'schema_version'").get();
-        return r2 ? parseInt(r2.value, 10) : 0;
-      })();
+      let sv = _AdfDatabase.readSchemaVersion(db) ?? 0;
       if (needsMigration = sv < ADF_LATEST_SCHEMA_VERSION, !needsMigration) {
         if (sv > ADF_LATEST_SCHEMA_VERSION) {
           let msg = `[AdfDatabase] Schema version ${sv} is newer than this runtime's v${ADF_LATEST_SCHEMA_VERSION} for ${filePath}. Opening without migration; writes from an older runtime may not maintain newer invariants.`;
@@ -3450,11 +3761,13 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
       }
       if (needsMigration)
         try {
-          _AdfDatabase.backupBeforeDestructiveSync(db, filePath), console.log(`[AdfDatabase] Backup created before migration (v${sv} \u2192 v${ADF_LATEST_SCHEMA_VERSION}): ${filePath}.bak`);
+          let made = _AdfDatabase.backupBeforeDestructiveSync(db, filePath);
+          backup = made, console.log(made.reused ? `[AdfDatabase] Backup before migration (v${sv} \u2192 v${ADF_LATEST_SCHEMA_VERSION}) already on disk, unchanged: ${filePath}.bak` : `[AdfDatabase] Backup created before migration (v${sv} \u2192 v${ADF_LATEST_SCHEMA_VERSION}): ${filePath}.bak`);
         } catch (e) {
           console.warn("[AdfDatabase] Could not create pre-migration backup:", e);
         }
-      let cols = db.prepare("PRAGMA table_info(adf_loop)").all();
+      db.exec("BEGIN IMMEDIATE");
+      let unversionedClone = sv === 0, cols = db.prepare("PRAGMA table_info(adf_loop)").all();
       new Set(cols.map((c) => c.name)).has("created_at") || (db.exec("ALTER TABLE adf_loop ADD COLUMN model TEXT"), db.exec("ALTER TABLE adf_loop ADD COLUMN tokens INTEGER"), db.exec("ALTER TABLE adf_loop ADD COLUMN created_at INTEGER NOT NULL DEFAULT 0")), db.exec("DROP TABLE IF EXISTS adf_archive"), db.prepare(
         "SELECT name FROM sqlite_master WHERE type='table' AND name='adf_audit'"
       ).get() || db.exec(`
@@ -3972,11 +4285,24 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         }
       } catch {
       }
-      needsMigration && _AdfDatabase.removeBackupSync(filePath);
+      if (!db.inTransaction) throw new Error(`The migration of ${basename(filePath)} was rolled back by SQLite.`);
+      unversionedClone && (db.prepare("INSERT INTO adf_meta (key, value, protection) VALUES ('adf_schema_version', ?, 'readonly') ON CONFLICT(key) DO UPDATE SET value = excluded.value, protection = 'readonly'").run(String(ADF_LATEST_SCHEMA_VERSION)), console.log(`[AdfDatabase] Stamped schema v${ADF_LATEST_SCHEMA_VERSION} on an unversioned clone: ${filePath}`)), db.exec("COMMIT"), migrated = !0;
     } catch (error) {
-      throw needsMigration && console.error(`[AdfDatabase] Migration failed. Backup preserved at: ${filePath}.bak`), db.close(), error;
+      if (db.inTransaction)
+        try {
+          db.exec("ROLLBACK");
+        } catch {
+        }
+      throw _AdfDatabase.abandonOpen(db, filePath, { backup, restore: !1, walExistedBeforeOpen }), error;
     }
-    return new _AdfDatabase(db, filePath);
+    let opened;
+    try {
+      opened = new _AdfDatabase(db, filePath);
+    } catch (error) {
+      let note = _AdfDatabase.abandonOpen(db, filePath, { backup, restore: migrated, walExistedBeforeOpen });
+      throw note ? new Error(`${error instanceof Error ? error.message : String(error)}. ${note}`, { cause: error }) : error;
+    }
+    return backup && _AdfDatabase.removeBackupSync(filePath), opened;
   }
   /**
    * Create a new ADF without replacing an existing destination.
@@ -4048,7 +4374,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         let overrideMap = new Map(options.tools.map((t) => [t.name, t]));
         tools = tools.map((t) => overrideMap.has(t.name) ? { ...t, ...overrideMap.get(t.name) } : t);
         for (let t of options.tools)
-          tools.some((dt) => dt.name === t.name) || tools.push(t);
+          tools.some((dt) => dt.name === t.name) || tools.push({ visible: !0, ...t });
       }
       let mergedTriggers = { ...base.triggers };
       if (options.triggers)
@@ -4075,7 +4401,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         context: {
           ...base.context,
           ...options.context,
-          audit: { ...base.context.audit, ...options.context?.audit },
+          audit: { ...AUDIT_DEFAULTS, ...base.context.audit, ...options.context?.audit },
           dynamic_instructions: { ...base.context.dynamic_instructions, ...options.context?.dynamic_instructions }
         },
         tools,
@@ -4085,6 +4411,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
         messaging: { ...base.messaging, ...options.messaging },
         audit: { ...base.audit, ...options.audit },
         pre_llm_hook: options.pre_llm_hook ?? base.pre_llm_hook,
+        commands: options.commands ?? base.commands,
         code_execution: { ...base.code_execution, ...options.code_execution },
         compute: { ...base.compute },
         logging: { ...base.logging, ...options.logging },
@@ -4160,10 +4487,10 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
    * crash leftovers owned by the sweeps — left untouched here. Errors from
    * `fn` (and the open) propagate to the caller's existing catch.
    */
-  static peekReadonly(filePath, fn) {
+  static peekReadonly(filePath, fn, busyTimeoutMs) {
     let hadSidecars = existsSync2(`${filePath}-wal`) || existsSync2(`${filePath}-shm`), db = null;
     try {
-      return db = new Database(filePath, { readonly: !0 }), fn(db);
+      return db = new Database(filePath, { readonly: !0 }), busyTimeoutMs !== void 0 && db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`), fn(db);
     } finally {
       try {
         db?.close();
@@ -4198,6 +4525,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
             throw new Error(
               "Snapshot timed out: the agent is being written to continuously \u2014 stop it and try again"
             );
+          return 100;
         }
       });
     } finally {
@@ -4363,6 +4691,23 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
       return null;
     }
   }
+  /**
+   * What the boot envelope sweep decides on before opening a file, read
+   * read-only: its schema version (null without an adf_meta table, 0 with no
+   * version) and its agent id (null without a config). Errors propagate;
+   * `busyTimeoutMs` bounds the wait for a lock (the sweep's 25 ms).
+   */
+  static peekSweepStatus(filePath, busyTimeoutMs) {
+    return _AdfDatabase.peekReadonly(filePath, (db) => {
+      let schemaVersion = _AdfDatabase.readSchemaVersion(db), row = !!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='adf_config'").get() ? db.prepare("SELECT config_json FROM adf_config WHERE id = 1").get() : void 0, agentId = null;
+      try {
+        let id = row ? JSON.parse(row.config_json).id : void 0;
+        typeof id == "string" && id && (agentId = id);
+      } catch {
+      }
+      return { schemaVersion, agentId };
+    }, busyTimeoutMs);
+  }
   static peekBootStatusDetailed(filePath) {
     try {
       return _AdfDatabase.peekReadonly(filePath, (db) => {
@@ -4528,8 +4873,8 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   static peekIdentityPurposes(filePath, prefix) {
     try {
       return _AdfDatabase.peekReadonly(filePath, (db) => db.prepare(
-        "SELECT purpose FROM adf_identity WHERE purpose LIKE ? || '%'"
-      ).all(prefix).map((r) => r.purpose));
+        "SELECT purpose FROM adf_identity WHERE substr(purpose, 1, length(?)) = ?"
+      ).all(prefix, prefix).map((r) => r.purpose));
     } catch {
       return [];
     }
@@ -4584,6 +4929,8 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
       "INSERT INTO adf_loop (seq, role, content_json, model, tokens, created_at, ord, loop) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
     ), this.stmts.clearLoop = this.db.prepare("DELETE FROM adf_loop WHERE loop = ?"), this.stmts.getLoopCount = this.db.prepare("SELECT COUNT(*) as count FROM adf_loop WHERE loop = ?"), this.stmts.getLastAssistantTokens = this.db.prepare(
       "SELECT tokens FROM adf_loop WHERE loop = ? AND role = 'assistant' AND tokens IS NOT NULL ORDER BY COALESCE(ord, seq) DESC, seq DESC LIMIT 1"
+    ), this.stmts.getAssistantTokenRows = this.db.prepare(
+      "SELECT seq, tokens FROM adf_loop WHERE loop = ? AND role = 'assistant' AND tokens IS NOT NULL ORDER BY COALESCE(ord, seq), seq"
     ), this.stmts.getInboxMessages = this.db.prepare(
       "SELECT * FROM adf_inbox ORDER BY received_at DESC"
     ), this.stmts.getInboxByStatus = this.db.prepare(
@@ -4666,7 +5013,7 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
     ), this.stmts.deleteIdentity = this.db.prepare(
       "DELETE FROM adf_identity WHERE purpose = ?"
     ), this.stmts.listIdentityByPrefix = this.db.prepare(
-      "SELECT purpose FROM adf_identity WHERE purpose LIKE ? || '%'"
+      "SELECT purpose FROM adf_identity WHERE substr(purpose, 1, length(?)) = ?"
     ), this.stmts.getIdentityFull = this.db.prepare(
       "SELECT purpose, value, encryption_algo, salt, kdf_params, code_access FROM adf_identity WHERE purpose = ?"
     ), this.stmts.getAllIdentityFull = this.db.prepare(
@@ -4703,6 +5050,8 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
       "UPDATE adf_tasks SET requires_authorization = 1 WHERE id = ?"
     ), this.stmts.setTaskExecutorManaged = this.db.prepare(
       "UPDATE adf_tasks SET executor_managed = 1 WHERE id = ?"
+    ), this.stmts.setTaskApprovalMeta = this.db.prepare(
+      "UPDATE adf_tasks SET approval_meta = ? WHERE id = ?"
     ), this.stmts.updateTaskArgs = this.db.prepare(
       "UPDATE adf_tasks SET args = ? WHERE id = ?"
     ), this.stmts.getTasksByStatus = this.db.prepare(
@@ -4781,11 +5130,16 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   deleteIdentity(purpose) {
     return this.stmts.deleteIdentity.run(purpose).changes > 0;
   }
+  /**
+   * Prefix matches are exact and case-sensitive (substr, not LIKE): with LIKE,
+   * `_` and `%` in a server or adapter name were wildcards and ASCII case was
+   * ignored, so detaching one server deleted another's credentials.
+   */
   deleteIdentityByPrefix(prefix) {
-    return this.db.prepare("DELETE FROM adf_identity WHERE purpose LIKE ? || '%'").run(prefix).changes;
+    return this.db.prepare("DELETE FROM adf_identity WHERE substr(purpose, 1, length(?)) = ?").run(prefix, prefix).changes;
   }
   listIdentityPurposes(prefix) {
-    return prefix ? this.stmts.listIdentityByPrefix.all(prefix).map((r) => r.purpose) : this.stmts.listAllIdentityPurposes.all().map((r) => r.purpose);
+    return prefix ? this.stmts.listIdentityByPrefix.all(prefix, prefix).map((r) => r.purpose) : this.stmts.listAllIdentityPurposes.all().map((r) => r.purpose);
   }
   // --- Encrypted identity methods ---
   /**
@@ -4879,6 +5233,17 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   deleteAllAttestations() {
     this.db.prepare("DELETE FROM adf_attestations").run();
   }
+  /**
+   * Re-sign rows in place: each row whose signature is `from` takes `to`
+   * (same issuer, subject and role), keeping its id and place. A row changed
+   * or removed meanwhile matches nothing and is left as it is. Returns the
+   * rows updated.
+   */
+  resignAttestations(updates) {
+    let stmt = this.db.prepare("UPDATE adf_attestations SET signature = ?, raw_json = ? WHERE signature = ?"), changed = 0;
+    for (let { from, to } of updates) changed += stmt.run(to.signature, JSON.stringify(to), from).changes;
+    return changed;
+  }
   deleteAllIdentity() {
     this.db.prepare("DELETE FROM adf_identity").run();
   }
@@ -4909,9 +5274,27 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
     }
     return added && this.setConfig(config), config;
   }
+  /**
+   * setConfig calls through this connection: with dataVersion(), a cheap "did
+   * the config change" check for callers that cache it (RuntimeService's
+   * running-agent config).
+   */
+  configWrites = 0;
+  dataVersionStmt = null;
+  configWriteCount() {
+    return this.configWrites;
+  }
+  /**
+   * SQLite's `PRAGMA data_version`: changes when another connection (another
+   * process, or another handle in this one) commits to the file; this
+   * connection's own writes leave it unchanged (configWriteCount counts those).
+   */
+  dataVersion() {
+    return this.dataVersionStmt ??= this.db.prepare("PRAGMA data_version").pluck(), this.dataVersionStmt.get();
+  }
   setConfig(config) {
     let now = (/* @__PURE__ */ new Date()).toISOString();
-    config.metadata.updated_at = now, this.stmts.setConfig.run(JSON.stringify(config), now), this.setMeta("adf_name", config.name), config.handle && this.setMeta("adf_handle", config.handle), this.setMeta("adf_updated_at", now);
+    config.metadata.updated_at = now, this.stmts.setConfig.run(JSON.stringify(config), now), this.configWrites++, this.setMeta("adf_name", config.name), config.handle && this.setMeta("adf_handle", config.handle), this.setMeta("adf_updated_at", now);
   }
   // ===========================================================================
   // Loop Table
@@ -4970,7 +5353,25 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
       opts?.ord ?? null,
       loop
     );
-    return this.bumpLoopRevision(loop), Number(result.lastInsertRowid);
+    return this.bumpLoopRevision(loop), content.some((block) => block.type === "file_ref") && this.getFileRefRegistry().noteContent(content), Number(result.lastInsertRowid);
+  }
+  /** File-reference state of this file, shared by every connection to it (see file-ref-registry.ts). */
+  getFileRefRegistry() {
+    return fileRefRegistry(this, this.filePath === ":memory:" ? null : _AdfDatabase.canonicalKey(this.filePath));
+  }
+  /**
+   * Rows of every loop that hold a `file_ref` block (a prefilter: the caller
+   * parses and checks). One scan of adf_loop; callers run it only when a
+   * referenced file is renamed or deleted.
+   */
+  getLoopRowsWithFileRefs() {
+    return this.db.prepare(
+      `SELECT seq, loop, content_json FROM adf_loop WHERE instr(content_json, '"file_ref"') > 0`
+    ).all();
+  }
+  /** Replace one row's content in place (file references rewritten on rename/delete). */
+  updateLoopContent(loop, seq, content) {
+    this.db.prepare("UPDATE adf_loop SET content_json = ? WHERE seq = ? AND loop = ?").run(JSON.stringify(content), seq, loop), this.bumpLoopRevision(loop);
   }
   /** Wipe ONE stream. The whole-table wipe is clearAllLoops(). */
   clearLoop(loop) {
@@ -4999,6 +5400,15 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
     let row = this.stmts.getLastAssistantTokens.get(loop);
     return _AdfDatabase.parseLoopTokens(row?.tokens);
   }
+  /** Every assistant row's usage record, in loop order (oldest first). */
+  getAssistantTokenRows(loop) {
+    let rows = this.stmts.getAssistantTokenRows.all(loop), out = [];
+    for (let row of rows) {
+      let tokens = _AdfDatabase.parseLoopTokens(row.tokens);
+      tokens && out.push({ seq: row.seq, tokens });
+    }
+    return out;
+  }
   /** Loop rows in display order: each row's seq plus its ordering key
    *  (COALESCE(ord, seq)). Positional operations resolve boundaries against
    *  ordKey, never raw seq — an ord'd summary sorts at its override position. */
@@ -5086,6 +5496,24 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   transaction(fn) {
     return this.db.transaction(fn)();
   }
+  /**
+   * `fn` in a BEGIN IMMEDIATE transaction: the file's write lock is taken
+   * before `fn` reads, so a check-then-write in it is atomic against every
+   * other connection (another process provisioning the same file). Inside a
+   * transaction already, a savepoint. `busyTimeoutMs`: how long BEGIN waits
+   * for another connection's write lock before SQLITE_BUSY (the connection's
+   * own busy_timeout, 5 s, otherwise).
+   */
+  immediateTransaction(fn, busyTimeoutMs) {
+    if (busyTimeoutMs === void 0 || this.db.inTransaction) return this.db.transaction(fn).immediate();
+    let before = this.db.pragma("busy_timeout", { simple: !0 });
+    this.db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
+    try {
+      return this.db.transaction(fn).immediate();
+    } finally {
+      this.db.pragma(`busy_timeout = ${before}`);
+    }
+  }
   // ===========================================================================
   // Inbox
   // ===========================================================================
@@ -5482,6 +5910,9 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   setTaskExecutorManaged(id, _value) {
     this.stmts.setTaskExecutorManaged.run(id);
   }
+  setTaskApprovalMeta(id, approvalMeta) {
+    this.stmts.setTaskApprovalMeta.run(approvalMeta, id);
+  }
   updateTaskArgs(id, args) {
     this.stmts.updateTaskArgs.run(args, id);
   }
@@ -5624,7 +6055,9 @@ CREATE INDEX IF NOT EXISTS idx_adf_logs_origin ON adf_logs(origin);
   }
   close() {
     if (this.closed) return;
-    if (this.closed = !0, _AdfDatabase.decrementOpen(this.filePath) === 0)
+    this.closed = !0;
+    let remaining = _AdfDatabase.decrementOpen(this.filePath);
+    if (remaining === 0 && this.getFileRefRegistry().media.clear(), remaining === 0)
       try {
         this.db.prepare(
           "INSERT INTO adf_meta (key, value, protection) VALUES (?, ?, 'readonly') ON CONFLICT(key) DO UPDATE SET value = excluded.value"
@@ -5970,12 +6403,12 @@ function buildLoopPreamble(loopName, agentHandle, grantedTools = []) {
 
 ${reachParagraph}
 
-A timer, a trigger, or a message from another loop woke you. Do that work, write tersely, and end your turn.`;
+A timer, a trigger, a message from another loop, or the human writing to you directly woke you. Do that work, write tersely, and end your turn.`;
 }
 var LOOP_GOAL_SUMMARY_CHARS = 160;
 function summarizeGoal(goal) {
-  let flat = goal.replace(/\s+/g, " ").trim();
-  return flat.length <= LOOP_GOAL_SUMMARY_CHARS ? flat : `${flat.slice(0, LOOP_GOAL_SUMMARY_CHARS - 1).trimEnd()}\u2026`;
+  let flat = (goal ?? "").replace(/\s+/g, " ").trim();
+  return flat ? flat.length <= LOOP_GOAL_SUMMARY_CHARS ? flat : `${flat.slice(0, LOOP_GOAL_SUMMARY_CHARS - 1).trimEnd()}\u2026` : "(no goal)";
 }
 var LOOP_ARCHETYPES = `Use an inner loop when a piece of thinking should run on its own stream: tending memory on a timer, a sub-task that needs your full context, reviewing a draft before you act, thinking while nothing external is happening. Name each one for what it does for you. Guide: ${DOCS_GUIDES_URL}/inner-loops.md`;
 function buildMainLoopsSection(loops, options) {
@@ -6081,12 +6514,12 @@ function deriveLoopConfig(parent, loop) {
     throw new Error("deriveLoopConfig: 'main' is the host loop \u2014 use the raw agent config");
   let derived = cloneJson(parent);
   derived.tools = deriveTools(parent, loop);
-  let grantedNames = derived.tools.filter((t) => t.enabled).map((t) => t.name);
-  return derived.instructions = `${buildLoopPreamble(loop.name, parent.handle || parent.name, grantedNames)}
+  let grantedNames = derived.tools.filter((t) => t.enabled).map((t) => t.name), preamble = buildLoopPreamble(loop.name, parent.handle || parent.name, grantedNames);
+  return derived.instructions = hasLoopGoal(loop) ? `${preamble}
 
 Your goal:
 
-${loop.goal}`, derived.model = cloneJson(loop.model ?? parent.model), derived.autonomous = loop.autonomous === !0, loop.compact_threshold != null && (derived.context = { ...derived.context, compact_threshold: loop.compact_threshold }), derived.triggers = deriveTriggers(parent, loop.name), derived.code_execution = {
+${loop.goal}` : preamble, derived.model = cloneJson(loop.model ?? parent.model), derived.autonomous = loop.autonomous === !0, loop.compact_threshold != null && (derived.context = { ...derived.context, compact_threshold: loop.compact_threshold }), derived.triggers = deriveTriggers(parent, loop.name), derived.code_execution = {
     ...deriveLoopCodeExecutionFlags(parent),
     // No inherited packages. A pure-JS package is loaded in the sandbox worker
     // through a worker-scope `createRequire` with an UNRESTRICTED `require` —
@@ -6145,6 +6578,14 @@ var CODE_FORBIDDEN_WRITE_RE = /^crypto:/;
 function isCodeForbiddenIdentityWrite(purpose) {
   return CODE_FORBIDDEN_WRITE_RE.test(purpose);
 }
+function parseLoopContent(json) {
+  try {
+    let parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
 var AdfWorkspace = class _AdfWorkspace {
   db;
   filePath;
@@ -6812,6 +7253,14 @@ var AdfWorkspace = class _AdfWorkspace {
   getAgentConfig() {
     return this.db.getConfig();
   }
+  /** Config writes through this file's connection so far (AdfDatabase.configWriteCount); no SQLite read. */
+  configWriteCount() {
+    return this.db.configWriteCount();
+  }
+  /** Commits by other connections to this file (AdfDatabase.dataVersion); no table read. */
+  dataVersion() {
+    return this.db.dataVersion();
+  }
   setAgentConfig(config) {
     let previous = null;
     try {
@@ -7151,6 +7600,10 @@ var AdfWorkspace = class _AdfWorkspace {
   getLastAssistantTokens() {
     return this.db.getLastAssistantTokens(this.boundLoop);
   }
+  /** Every assistant row's usage record in loop order — see AdfDatabase.getAssistantTokenRows. */
+  getAssistantTokenRows() {
+    return this.db.getAssistantTokenRows(this.boundLoop);
+  }
   /** Meta key of this loop's context baseline: bare for main, `:<loop>`-suffixed
    *  for side loops (one baseline per cognition stream). */
   contextBaselineKey() {
@@ -7522,12 +7975,12 @@ var AdfWorkspace = class _AdfWorkspace {
       let deleted2 = !1;
       return this.db.transaction(() => {
         archive && this.db.insertAudit("file", { ref: relativePath, entryCount: 1, sizeBytes: archive.json.length, data: archive.data }), opts?.force && entry && this.db.setFileProtection(relativePath, "none"), deleted2 = this.db.deleteFile(relativePath);
-      }), deleted2 && (this.emitUmbilical("file.deleted", { path: relativePath }), this.emitFileChange(relativePath, "deleted", void 0, entry?.content, metadata)), deleted2;
+      }), deleted2 && (this.emitUmbilical("file.deleted", { path: relativePath }), this.emitFileChange(relativePath, "deleted", void 0, entry?.content, metadata), this.rewriteFileRefs([{ op: "delete", path: relativePath }])), deleted2;
     }
     let previous = this.onFileChangeCallback ? this.db.readFile(relativePath)?.content : void 0;
     opts?.force && this.db.fileExists(relativePath) && this.db.setFileProtection(relativePath, "none");
     let deleted = this.db.deleteFile(relativePath);
-    return deleted && (this.emitUmbilical("file.deleted", { path: relativePath }), this.emitFileChange(relativePath, "deleted", void 0, previous, metadata)), deleted;
+    return deleted && (this.emitUmbilical("file.deleted", { path: relativePath }), this.emitFileChange(relativePath, "deleted", void 0, previous, metadata), this.rewriteFileRefs([{ op: "delete", path: relativePath }])), deleted;
   }
   getFileMeta(path) {
     return this.db.getFileMeta(path);
@@ -7547,7 +8000,10 @@ var AdfWorkspace = class _AdfWorkspace {
     return this.db.fileExists(relativePath);
   }
   renameInternalFile(oldPath, newPath) {
-    let previous = this.onFileChangeCallback ? this.db.readFile(oldPath)?.content : void 0, metadata = this.fileChangeMeta(oldPath), renamed = this.db.renameFile(oldPath, newPath);
+    let previous = this.onFileChangeCallback ? this.db.readFile(oldPath)?.content : void 0, metadata = this.fileChangeMeta(oldPath), renamed = this.db.transaction(() => {
+      let done = this.db.renameFile(oldPath, newPath);
+      return done && this.rewriteFileRefs([{ op: "rename", from: oldPath, to: newPath }]), done;
+    });
     return renamed && (this.emitFileChange(oldPath, "deleted", void 0, previous, metadata), this.emitFileChange(newPath, "created", previous, void 0, this.fileChangeMeta(newPath))), renamed;
   }
   renameFolder(oldPrefix, newPrefix) {
@@ -7555,14 +8011,15 @@ var AdfWorkspace = class _AdfWorkspace {
       path: file.path,
       content: notify ? this.db.readFile(file.path)?.content : void 0,
       metadata: notify ? this.getFileMeta(file.path) : null
-    })), count = this.db.renameFolder(oldPrefix, newPrefix);
-    if (count > 0) {
-      let replacementPrefix = newPrefix.endsWith("/") ? newPrefix : `${newPrefix}/`;
+    })), replacementPrefix = newPrefix.endsWith("/") ? newPrefix : `${newPrefix}/`, count = this.db.transaction(() => {
+      let changed = this.db.renameFolder(oldPrefix, newPrefix);
+      return changed > 0 && this.rewriteFileRefs(moved.map((file) => ({ op: "rename", from: file.path, to: replacementPrefix + file.path.slice(prefix.length) }))), changed;
+    });
+    if (count > 0)
       for (let file of moved) {
         let newPath = replacementPrefix + file.path.slice(prefix.length);
         this.emitFileChange(file.path, "deleted", void 0, file.content, file.metadata), this.emitFileChange(newPath, "created", file.content, void 0, this.fileChangeMeta(newPath));
       }
-    }
     return count;
   }
   // The sinks are per-agent, not per-loop: registering through a forLoop() view
@@ -7597,8 +8054,38 @@ var AdfWorkspace = class _AdfWorkspace {
     } catch {
     }
   }
+  /**
+   * Keep file references (`file_ref` blocks) pointing at the right file: a
+   * rename or move rewrites the path, a delete leaves a tombstone. Rewrites
+   * every loop row that names the file, then every live session's copy. Only
+   * files some row references cost a scan; the set of referenced paths is
+   * built once per process and kept current by loop writes.
+   */
+  rewriteFileRefs(changes) {
+    if (changes.length === 0) return;
+    let registry3 = this.db.getFileRefRegistry();
+    try {
+      if (!registry3.referenced) {
+        let referenced = /* @__PURE__ */ new Set();
+        for (let row of this.db.getLoopRowsWithFileRefs())
+          for (let block of parseLoopContent(row.content_json))
+            isFileRefBlock(block) && !block.file_ref.deleted && referenced.add(block.file_ref.path);
+        registry3.referenced = referenced;
+      }
+      if (!registry3.affects(changes)) return;
+      this.db.transaction(() => {
+        for (let row of this.db.getLoopRowsWithFileRefs()) {
+          let content = parseLoopContent(row.content_json), next = applyFileRefChanges(content, changes);
+          next !== content && this.db.updateLoopContent(row.loop, row.seq, next);
+        }
+      }), registry3.noteChanges(changes);
+    } catch (error) {
+      console.error("[AdfWorkspace] Could not update file references:", error);
+    }
+    registry3.notifyHolders(changes);
+  }
   emitFileChange(path, operation, content, previousContent, metadata) {
-    if (this.skillIndexer.notifyPath(path), !this.onFileChangeCallback) return;
+    if (this.db.getFileRefRegistry().invalidate(path), this.skillIndexer.notifyPath(path), this.emitDataChange("files"), !this.onFileChangeCallback) return;
     let mimeType = metadata?.mime_type ?? this.getMimeType(path);
     this.onFileChangeCallback({
       path,
@@ -7738,6 +8225,9 @@ var AdfWorkspace = class _AdfWorkspace {
   setTaskExecutorManaged(id, value) {
     this.db.setTaskExecutorManaged(id, value);
   }
+  setTaskApprovalMeta(id, approvalMeta) {
+    this.db.setTaskApprovalMeta(id, approvalMeta);
+  }
   updateTaskArgs(id, args) {
     this.db.updateTaskArgs(id, args);
   }
@@ -7884,8 +8374,39 @@ var AdfWorkspace = class _AdfWorkspace {
   transaction(fn) {
     return this.db.transaction(fn);
   }
+  /** AdfDatabase.immediateTransaction: an atomic check-then-write against other connections to the file. */
+  immediateTransaction(fn, busyTimeoutMs) {
+    return this.db.immediateTransaction(fn, busyTimeoutMs);
+  }
 };
 
+// src/main/runtime/loop-usage.ts
+function summarizeLoopUsage(entries) {
+  let totals = createUsageTotals(), byModel = /* @__PURE__ */ new Map(), usageRows = 0, estimatedRows = 0;
+  for (let entry of entries) {
+    if (!entry.tokens) continue;
+    usageRows++, hasReportedUsage(entry.tokens) || estimatedRows++, addUsage(totals, entry.tokens);
+    let model = entry.model ?? "unknown", bucket = byModel.get(model);
+    bucket || (bucket = { model, rows: 0, ...createUsageTotals() }, byModel.set(model, bucket)), bucket.rows++, addUsage(bucket, entry.tokens);
+  }
+  return {
+    loopRows: entries.length,
+    usageRows,
+    estimatedRows,
+    totals,
+    byModel: Array.from(byModel.values()).sort((a, b) => b.total - a.total)
+  };
+}
+function createUsageTotals() {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+}
+function addUsage(target, usage) {
+  target.input += usage.input ?? 0, target.output += usage.output ?? 0, target.cacheRead += usage.cache_read ?? 0, target.cacheWrite += usage.cache_write ?? 0, target.total = target.input + target.output;
+}
+function hasReportedUsage(t) {
+  return t.estimated ? !1 : t.cache_read !== void 0 || t.cache_write !== void 0 || t.reasoning !== void 0 || t.cost_usd !== void 0;
+}
+
 // src/main/tools/shell/commands/status.ts
 function staticArgValue3(arg) {
   if (!arg) return null;
@@ -8062,7 +8583,7 @@ async function configTools(ctx) {
 var statusHandler = {
   name: "status",
   summary: "Show agent status summary",
-  helpText: "status               State, token usage, budget remaining",
+  helpText: "status               State, model, token usage in the current loop",
   category: "identity",
   resolvedTools: ["sys_get_config"],
   async execute(ctx) {
@@ -8072,7 +8593,7 @@ var statusHandler = {
       `Model:     ${config.model?.provider ?? ""}/${config.model?.model_id ?? ""}`,
       `Autonomy:  ${config.autonomous ? "enabled" : "disabled"}`
     ];
-    return config.limits?.token_budget && lines.push(`Budget:    ${config.limits.token_budget} tokens`), ok(lines.join(`
+    return lines.push(`Tokens:    ${tokenUsageLine(ctx)}`), ok(lines.join(`
 `));
   }
 }, stateHandler = {
@@ -8231,6 +8752,17 @@ var statusHandler = {
   falseHandler,
   sleepHandler
 ];
+function tokenUsageLine(ctx) {
+  let usage;
+  try {
+    usage = summarizeLoopUsage(ctx.workspace.getLoop());
+  } catch {
+    return "unavailable";
+  }
+  if (usage.usageRows === 0) return "none recorded in the current loop";
+  let n = (v) => v.toLocaleString("en-US"), { input, output, cacheRead, total } = usage.totals, cached = cacheRead > 0 ? ` (${n(cacheRead)} cached)` : "", estimated = usage.estimatedRows > 0 ? ` (${usage.estimatedRows} estimated)` : "", calls = `${usage.usageRows} call${usage.usageRows === 1 ? "" : "s"}${estimated}`;
+  return `${n(total)} total: ${n(input)} in${cached}, ${n(output)} out; ${calls} in the current loop`;
+}
 
 // src/main/tools/shell/commands/meta.ts
 var metaHandler = {
@@ -8426,7 +8958,7 @@ var CATEGORY_ORDER = [
   resolvedTools: [],
   async execute(ctx) {
     if (ctx.args.length > 0) {
-      let { getCommand: getCommand2 } = await import("./commands-KPJWFRUE.mjs"), handler = getCommand2(ctx.args[0]);
+      let { getCommand: getCommand2 } = await import("./commands-KOMPXJZS.mjs"), handler = getCommand2(ctx.args[0]);
       return handler ? ok(handler.helpText) : ok(`Unknown command: ${ctx.args[0]}`);
     }
     let commands = getAllCommands(), grouped = /* @__PURE__ */ new Map();
@@ -8495,10 +9027,13 @@ export {
   verifyEd25519,
   rawPublicKeyToSpki,
   didToPublicKey,
+  ADF_LATEST_SCHEMA_VERSION,
   AdfDatabase,
   withSource,
   withLoop,
   withTurn,
+  currentTurnId,
+  currentAgentId,
   currentSourceOrUnknown,
   init_execution_context,
   SKILLS_REGISTRY_PATH,
@@ -8509,6 +9044,7 @@ export {
   rawX25519PrivateToPkcs8,
   rawX25519PublicToSpki,
   extractRawX25519PublicKey,
+  openKeySlot,
   sealWithDek,
   openWithDek,
   envelopeFromAlgo,
@@ -8532,12 +9068,11 @@ export {
   isCodeForbiddenIdentityWrite,
   AdfWorkspace,
   isTextMime,
-  isVisionMime,
-  isAudioInputMime,
-  isVideoInputMime,
   mimeToAudioFormat,
   formatSize,
   mimeToExt,
+  summarizeLoopUsage,
+  hasReportedUsage,
   EXIT,
   err,
   shellReadFile,