akm-cli 0.9.0 → 0.9.1-beta.1

package/dist/core/path-access.js

@@ -0,0 +1,107 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Tell "this path is not there" apart from "I am not allowed to look at it"
+ * (issue #791).
+ *
+ * # Why this exists
+ *
+ * `fs.existsSync()` answers `false` for BOTH cases: it swallows every error,
+ * so `ENOENT` (genuinely absent) and `EACCES` (present, unreadable) are
+ * indistinguishable. akm used `existsSync` as its "is there an index?" gate on
+ * the read path, so an index the caller could not read was reported as an index
+ * that did not exist — `akm search` and `akm curate` returned
+ * `hits: []` with the tip *"No search index available. Run 'akm index' to build
+ * one."* at exit 0, for a populated index sitting right there on disk.
+ *
+ * That is the worst possible shape for a failure. A non-zero exit is a problem
+ * the operator can see; an empty-but-successful result is a lie that a
+ * consuming agent will confidently relay to its user. In the report that
+ * prompted this module, exactly that happened: an agent told its user akm's
+ * "vector service is unavailable and its maintenance lock is read-only" — a
+ * story it invented to explain results that claimed to be fine.
+ *
+ * # Contract
+ *
+ * `absent` means the path (or a parent component) genuinely is not there, which
+ * is a legitimate first-run state every caller already handles. `inaccessible`
+ * means the path may well exist and this process cannot determine that or read
+ * it — a caller must NEVER degrade that to an empty-but-successful result.
+ */
+import fs from "node:fs";
+function errnoOf(error) {
+    const code = error?.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Classify `target` as {@link PathAccess}.
+ *
+ * `ENOENT`/`ENOTDIR` are `absent` — the path cannot exist as named. Everything
+ * else that fails is `inaccessible`, carrying its errno: a permission error is
+ * the common case, but a symlink loop or an I/O error are equally "present as
+ * far as anyone knows, and unusable", and silently treating them as "no index"
+ * is the bug this module exists to prevent.
+ *
+ * Statting is not enough — a file can be `stat`-able through a searchable
+ * parent while being unreadable itself — so a successful stat is confirmed with
+ * an `R_OK` access check.
+ */
+export function classifyPathAccess(target) {
+    try {
+        fs.statSync(target);
+    }
+    catch (error) {
+        const code = errnoOf(error);
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { access: "absent" };
+        return { access: "inaccessible", ...(code ? { code } : {}) };
+    }
+    try {
+        fs.accessSync(target, fs.constants.R_OK);
+    }
+    catch (error) {
+        const code = errnoOf(error);
+        return { access: "inaccessible", ...(code ? { code } : {}) };
+    }
+    return { access: "present" };
+}
+/** True when the path is genuinely absent — the ordinary "not built yet" state. */
+export function isPathAbsent(target) {
+    return classifyPathAccess(target).access === "absent";
+}
+/**
+ * A diagnostic line naming everything an operator needs to fix a permission
+ * problem without a second round trip: the path, the errno, the mode and owner
+ * of whatever akm *could* stat along the way, and the uid actually running.
+ *
+ * Deliberately best-effort — this runs on an error path, so a failure to gather
+ * detail must never mask the error being described.
+ */
+export function describeInaccessiblePath(target, code) {
+    const parts = [target];
+    if (code)
+        parts.push(`(${code})`);
+    try {
+        const stat = fs.statSync(target);
+        parts.push(`mode ${(stat.mode & 0o777).toString(8).padStart(3, "0")}, owner uid ${stat.uid}`);
+    }
+    catch {
+        // Cannot stat the file itself — describe the closest parent we CAN see,
+        // which is usually where the missing permission actually is.
+        const parent = target.slice(0, Math.max(0, target.lastIndexOf("/")));
+        if (parent) {
+            try {
+                const stat = fs.statSync(parent);
+                parts.push(`parent ${parent} is mode ${(stat.mode & 0o777).toString(8).padStart(3, "0")}, owner uid ${stat.uid}`);
+            }
+            catch {
+                // Nothing further to say.
+            }
+        }
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid !== undefined)
+        parts.push(`running as uid ${uid}`);
+    return parts.join("; ");
+}

package/dist/core/redaction.js

@@ -297,6 +297,26 @@ function addMappedMatches(coverageDelta, haystack, needle) {
         offset = match + Math.max(needle.length, 1);
     }
 }
+/**
+ * Mark every occurrence of `needle` in `text` — no encoding normalization, for
+ * text that contains neither `%` nor `+` and so cannot carry an encoded form.
+ *
+ * Matching against the ORIGINAL text (rather than an accumulator being rewritten
+ * in place) is the whole point: see {@link redactSensitiveText}.
+ */
+function addPlainMatches(coverageDelta, text, needle) {
+    if (!needle)
+        return;
+    let offset = 0;
+    while (offset <= text.length - needle.length) {
+        const match = text.indexOf(needle, offset);
+        if (match < 0)
+            break;
+        coverageDelta[match] = coverageDelta[match] + 1;
+        coverageDelta[match + needle.length] = coverageDelta[match + needle.length] - 1;
+        offset = match + needle.length;
+    }
+}
 /**
  * Redact credential-shaped substrings from arbitrary text by pattern alone —
  * unlike {@link redactSensitiveText}, which requires the exact secret value
@@ -332,8 +352,20 @@ export function redactCredentialPatterns(input) {
         .replace(/(hooks\.slack\.com\/services\/[A-Za-z0-9]+\/[A-Za-z0-9]+\/)[A-Za-z0-9]+/gi, "$1[REDACTED]"));
 }
 /**
- * Replace exact sensitive values in text. Longer values are replaced first so
- * an overlapping prefix cannot expose the suffix of a longer credential.
+ * Replace exact sensitive values in text.
+ *
+ * Every match is located against the ORIGINAL text and the result is emitted
+ * once, so overlapping matches merge into a single `[REDACTED]` and no needle
+ * can ever match inside a token an earlier needle produced.
+ *
+ * That last property is load-bearing. This function used to take a `replaceAll`
+ * fast path that chained over a *mutating* accumulator, which meant any needle
+ * drawn from the letters of `[REDACTED]` re-matched the tokens already injected
+ * and the output grew geometrically: `redactSensitiveText("a".repeat(50),
+ * ["a","E","D","T","C","R"])` returned 32,450 characters — 649x the input. On a
+ * path where the needle set is derived from configuration or the environment,
+ * that is a memory-exhaustion hazard reachable from ordinary command output.
+ * The encoded-form path never had the bug because it always worked this way.
  */
 export function redactSensitiveText(text, sensitiveValues) {
     const values = [...new Set(sensitiveValues)]
@@ -341,22 +373,24 @@ export function redactSensitiveText(text, sensitiveValues) {
         .sort((a, b) => b.length - a.length || a.localeCompare(b));
     if (values.length === 0)
         return text;
-    if (!text.includes("%") && !text.includes("+")) {
-        let redacted = text;
+    const coverageDelta = new Int32Array(text.length + 1);
+    if (text.includes("%") || text.includes("+")) {
+        // Percent-/plus-encoded text: match needle and haystack in their decoded
+        // forms, mapping hits back to source offsets.
+        const addMatchesForMode = (plusAsSpace) => {
+            const haystack = normalizeEncodedText(text, plusAsSpace);
+            for (const value of values) {
+                addMappedMatches(coverageDelta, haystack, normalizeEncodedText(value, plusAsSpace).text);
+            }
+        };
+        addMatchesForMode(false);
+        if (text.includes("+"))
+            addMatchesForMode(true);
+    }
+    else {
         for (const value of values)
-            redacted = redacted.replaceAll(value, "[REDACTED]");
-        return redacted;
+            addPlainMatches(coverageDelta, text, value);
     }
-    const coverageDelta = new Int32Array(text.length + 1);
-    const addMatchesForMode = (plusAsSpace) => {
-        const haystack = normalizeEncodedText(text, plusAsSpace);
-        for (const value of values) {
-            addMappedMatches(coverageDelta, haystack, normalizeEncodedText(value, plusAsSpace).text);
-        }
-    };
-    addMatchesForMode(false);
-    if (text.includes("+"))
-        addMatchesForMode(true);
     let redacted = "";
     let coverage = 0;
     let offset = 0;
@@ -384,7 +418,20 @@ export function redactSensitiveValue(value, sensitiveValues) {
         if (Array.isArray(entry))
             return entry.map(redact);
         if (entry && typeof entry === "object") {
-            return Object.fromEntries(Object.entries(entry).map(([key, child]) => [redactSensitiveText(key, values), redact(child)]));
+            const out = {};
+            for (const [key, child] of Object.entries(entry)) {
+                const redactedKey = redactSensitiveText(key, values);
+                // Two DISTINCT keys can redact to the same string (`{a, b, ab}` under
+                // needles `a`/`b` all collapse toward `[REDACTED]`). Building this with
+                // `Object.fromEntries` kept only the last of each colliding group, so a
+                // field was silently DROPPED rather than redacted — data loss disguised
+                // as redaction. Suffix instead: the value stays, the key stays hidden.
+                let finalKey = redactedKey;
+                for (let n = 2; Object.hasOwn(out, finalKey); n++)
+                    finalKey = `${redactedKey} (${n})`;
+                out[finalKey] = redact(child);
+            }
+            return out;
         }
         return entry;
     };

package/dist/core/spawn-env.js

@@ -0,0 +1,234 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The ONE allowlist-based child-environment primitive.
+ *
+ * Two akm code paths spawn a child from an explicit list of environment
+ * variable NAMES — the agent-CLI spawn wrapper
+ * (`integrations/agent/spawn.ts`, `profile.envPassthrough`) and the workflow
+ * `exec` unit runner (`workflows/exec/exec-unit.ts`) — and both start from an
+ * EMPTY environment and copy through named entries with
+ * {@link collectAllowlistedEnv}. Keeping that in one leaf module is what makes
+ * "allowlist" a single reviewable mechanism instead of two implementations
+ * that drift apart.
+ *
+ * NOT covered: the opencode-sdk server spawn
+ * (`integrations/harnesses/opencode-sdk/sdk-runner.ts`) keeps its own
+ * hard-coded name list and does not route through here, so it gets neither the
+ * platform floor below nor PATH supplementation.
+ *
+ * A LEAF: node built-ins only, so both the integrations layer and the workflow
+ * engine can import it without opening a cycle.
+ *
+ * @module core/spawn-env
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * The baseline env names every allowlisted akm child receives regardless of
+ * what it runs: process identity (`HOME`, `USER`), tool resolution (`PATH`),
+ * locale (`LANG`, `LC_ALL`), terminal (`TERM`), scratch space (`TMPDIR`), and
+ * akm's own event provenance (`AKM_EVENT_SOURCE` — machine traffic, never a
+ * secret). BOTH allowlists extend it — the agent-CLI profiles'
+ * `COMMON_PASSTHROUGH` (`integrations/agent/profiles.ts`) and the workflow
+ * exec unit's `EXEC_DEFAULT_ENV_PASSTHROUGH` (`workflows/exec/exec-unit.ts`)
+ * — so a baseline name cannot drift into one child-spawn path but not the
+ * other. NOTE: profile `envPassthrough` is frozen into workflow engine
+ * snapshots, so growing this list changes frozen-plan content — extend
+ * deliberately.
+ */
+export const COMMON_SPAWN_ENV_PASSTHROUGH = [
+    "HOME",
+    "PATH",
+    "USER",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "TMPDIR",
+    "AKM_EVENT_SOURCE",
+];
+/**
+ * The names Windows itself requires of ANY child, whatever the caller's
+ * allowlist says. Applied at build time rather than added to
+ * {@link COMMON_SPAWN_ENV_PASSTHROUGH} because profile `envPassthrough` is
+ * frozen into workflow engine snapshots: growing the shared list would change
+ * the bytes — and so the hashes — of every plan already on disk, to express
+ * something that is not a policy choice at all.
+ *
+ * `SystemRoot`, `SystemDrive` and `WINDIR` are what PROCESS CREATION reads;
+ * without them the loader cannot find system DLLs and the spawn fails before
+ * the command runs. Without `PATHEXT` Windows never tries `bun.exe`/`bun.cmd`,
+ * so a `bin: "bun"` profile is unresolvable, and `COMSPEC` is how `.bat`/`.cmd`
+ * targets resolve at all. The rest are the win32 analogues of baseline names
+ * the POSIX side already grants — `HOME` (`USERPROFILE`, `HOMEDRIVE`,
+ * `HOMEPATH`) and `TMPDIR` (`TEMP`, `TMP`). None is a secret.
+ *
+ * Config and install roots (`APPDATA`, `LOCALAPPDATA`, `ProgramFiles`, …) are
+ * deliberately NOT here: a child can be created and can resolve its command
+ * without them, so which allowlist wants them stays a per-caller decision.
+ *
+ * THE definition of the floor. The workflow exec allowlist
+ * (`EXEC_DEFAULT_ENV_PASSTHROUGH`) spreads this constant rather than
+ * re-spelling it, because that list is also consumed on POSIX — where
+ * {@link spawnEnvNamesFor} appends nothing — and the names still have to be
+ * requestable there for a win32 run of the same workflow.
+ */
+export const WIN32_SPAWN_ENV_FLOOR = [
+    "SystemRoot",
+    "SystemDrive",
+    "WINDIR",
+    "COMSPEC",
+    "PATHEXT",
+    "USERPROFILE",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "TEMP",
+    "TMP",
+];
+/**
+ * The effective allowlist for `platform`: the caller's names, plus any floor
+ * the operating system requires of every child regardless of allowlist.
+ * Exported for tests, which must be able to ask for a platform they are not
+ * running on.
+ */
+export function spawnEnvNamesFor(names, platform = process.platform) {
+    const effective = [...names];
+    if (platform !== "win32")
+        return effective;
+    // Deduped by EXACT spelling, never case-folded: {@link collectAllowlistedEnv}
+    // looks each surviving name up with exactly this case, and a `source` that is
+    // a plain object — the agent spawn's `envSource` seam — does not case-fold.
+    // Suppressing `SystemRoot` because the caller happened to write `SYSTEMROOT`
+    // would therefore drop the loader-critical variable the floor exists to
+    // guarantee. Keeping both spellings is harmless: the win32 environment is
+    // itself case-insensitive, so they resolve to the same value.
+    const present = new Set(effective);
+    for (const name of WIN32_SPAWN_ENV_FLOOR) {
+        if (!present.has(name))
+            effective.push(name);
+    }
+    return effective;
+}
+/**
+ * Build a child environment from an allowlist: start EMPTY and copy through
+ * exactly the named variables that exist in `source`. Names absent from the
+ * source are simply absent from the child (never an empty string, which many
+ * tools treat as "set but blank").
+ *
+ * `PATH`, when it comes through, is supplemented for scheduler contexts — see
+ * {@link supplementPathForSchedulerContext}. That happens here rather than in
+ * each caller so a child spawned from cron/launchd/Task Scheduler can find the
+ * user's toolchain no matter which spawn path reached it. On win32 the names
+ * in {@link WIN32_SPAWN_ENV_FLOOR} come through too, for the same reason: the
+ * spawn cannot succeed without them, whichever caller built the list.
+ */
+export function collectAllowlistedEnv(names, source = process.env) {
+    const env = {};
+    for (const name of spawnEnvNamesFor(names)) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    if (env.PATH !== undefined) {
+        env.PATH = supplementPathForSchedulerContext(env.PATH);
+    }
+    return env;
+}
+/**
+ * Answers already computed by {@link supplementPathForSchedulerContext}, keyed
+ * by the input PATH and the home directory it was computed against.
+ *
+ * Correctness envelope: the answer is a pure function of those two, the
+ * platform, and which candidate directories exist on disk. The platform cannot
+ * change under a running process, and the other two are in the key — so the one
+ * thing the memo assumes is that a candidate directory does not APPEAR while
+ * akm runs. Answering the rest of a run the way its start was answered is what
+ * a shell's own command-path caching already does, and the cost of not
+ * memoizing is paid on every child-env build: two PATH splits and up to seven
+ * SYNCHRONOUS `existsSync` probes, on the event loop a 10 000-unit fan-out
+ * shares with the run's lease heartbeat.
+ *
+ * Bounded so a caller that somehow varies its PATH cannot grow it without
+ * limit; a spawn path only ever sees a handful of distinct PATH strings, so
+ * the reset is effectively unreachable in practice.
+ */
+const supplementedPaths = new Map();
+const SUPPLEMENTED_PATH_MEMO_MAX = 64;
+/**
+ * Supplement `existingPath` with well-known user binary directories when
+ * running in a scheduler context (cron/launchd) where PATH is stripped.
+ *
+ * Detection heuristic: if the current PATH does not contain the user's home
+ * directory, we are likely in a stripped scheduler env. In an interactive
+ * shell the user's home almost always appears (e.g. ~/.bun/bin, ~/.cargo/bin).
+ *
+ * Only directories that actually exist on disk are prepended, and only if
+ * they are not already present, so interactive-shell PATH ordering is never
+ * disturbed.
+ *
+ * Memoized per input PATH — see {@link supplementedPaths} for what that
+ * assumes.
+ */
+export function supplementPathForSchedulerContext(existingPath) {
+    const home = os.homedir();
+    // NUL-joined so no pair of (home, PATH) can collide onto one key: no path
+    // component can contain a NUL.
+    const key = `${home}\u0000${existingPath}`;
+    const memoized = supplementedPaths.get(key);
+    if (memoized !== undefined)
+        return memoized;
+    const supplemented = computeSupplementedPath(existingPath, home);
+    if (supplementedPaths.size >= SUPPLEMENTED_PATH_MEMO_MAX)
+        supplementedPaths.clear();
+    supplementedPaths.set(key, supplemented);
+    return supplemented;
+}
+function computeSupplementedPath(existingPath, home) {
+    // A home of `/` (system crontab, launchd, service accounts) or of `""`
+    // prefixes EVERY entry, so a prefix test would read the most stripped
+    // environments there are as interactive and skip the repair they exist for.
+    const comparableHome = home === "" || home === path.sep ? undefined : home;
+    // If PATH already contains the home directory, we are in an interactive
+    // shell — skip supplementation entirely. Compared on a path boundary: a
+    // sibling home (`/home/alice` next to `/home/al`) is not this user's.
+    const isUnderHome = (dir) => comparableHome !== undefined && (dir === comparableHome || dir.startsWith(comparableHome + path.sep));
+    if (existingPath.split(path.delimiter).some(isUnderHome)) {
+        return existingPath;
+    }
+    const candidates = pathCandidatesForCurrentPlatform(home);
+    const existing = new Set(existingPath.split(path.delimiter).filter(Boolean));
+    const toAdd = candidates.filter((d) => !existing.has(d) && fs.existsSync(d));
+    if (toAdd.length === 0)
+        return existingPath;
+    return [...toAdd, existingPath].filter(Boolean).join(path.delimiter);
+}
+function pathCandidatesForCurrentPlatform(home) {
+    if (process.platform === "win32") {
+        // Windows: Bun + Cargo + Scoop + Chocolatey + system tools. Order favors
+        // user-local installs over machine-global so the user's chosen toolchain
+        // wins. These paths are commonly stripped from Task Scheduler / service
+        // environments, mirroring the cron/launchd problem on POSIX.
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        const userProfile = process.env.USERPROFILE ?? home;
+        const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+        return [
+            path.join(userProfile, ".bun", "bin"),
+            path.join(localAppData, "Programs", "bun"),
+            path.join(userProfile, ".cargo", "bin"),
+            path.join(localAppData, "Programs", "Git", "cmd"),
+            path.join(userProfile, "scoop", "shims"),
+            path.join(programFiles, "Git", "cmd"),
+            "C:\\ProgramData\\chocolatey\\bin",
+        ];
+    }
+    return [
+        path.join(home, ".bun", "bin"),
+        path.join(home, ".cargo", "bin"),
+        path.join(home, ".local", "bin"),
+        "/opt/homebrew/bin",
+        "/opt/homebrew/sbin",
+        "/usr/local/bin",
+    ];
+}

package/dist/core/state-db-scope.js

@@ -0,0 +1,134 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Ambient, run-scoped state.db connection reuse.
+ *
+ * `openStateDatabase` is NOT cheap: every call registers a `state-db`
+ * maintenance activity (a lockfile create under the maintenance barrier), opens
+ * a throwaway read-only preflight handle to assert the migration ledger, then
+ * opens the real handle and applies pragmas. Paying that per repository call
+ * — twice per dispatched workflow unit (insert + finish), plus once per
+ * `appendEvent` (two events per unit) — is the dominant cost of a wide `map`
+ * fan-out.
+ *
+ * This module adds the ONE thing the codebase was missing: a way to say "for
+ * the duration of this async operation, everything that talks to state.db
+ * shares a single handle". It deliberately does NOT introduce a pool, a cache
+ * with an eviction policy, or a background keep-alive timer — those all leak
+ * handles across the test harness's per-test data-dir swaps. The scope owns
+ * exactly one connection and closes it in a `finally`.
+ *
+ * ## Why this is safe
+ *
+ * SQLite connections must not be shared across THREADS. This is a single
+ * process running a single-threaded JS event loop: `bun:sqlite` statement
+ * execution and `withImmediateTransaction`'s `BEGIN IMMEDIATE … COMMIT` bodies
+ * are fully synchronous, so two logically concurrent units can never interleave
+ * statements on the shared handle — the runtime cannot preempt a synchronous
+ * transaction body. Sharing one handle therefore REMOVES in-process writer
+ * contention (`SQLITE_BUSY` against ourselves) rather than creating it.
+ * Cross-process behaviour is untouched: WAL mode, the 30 s `busy_timeout` and
+ * the run-lease protocol all still arbitrate between processes exactly as
+ * before.
+ *
+ * The one hazard of an {@link AsyncLocalStorage}-carried handle is async work
+ * that ESCAPES the scope: the context propagates into a promise that settles
+ * after the scope's `finally` closed the handle. {@link borrowScopedStateDb}
+ * guards that with a `closed` flag — once a scope is torn down it stops
+ * lending, and escapee callers transparently fall back to opening their own
+ * connection (the pre-existing behaviour). A use-after-close is structurally
+ * impossible.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { getStateDbPath, openStateDatabase } from "./state-db.js";
+const scopeStorage = new AsyncLocalStorage();
+/** Every scope with a live handle, so the exit backstop can close them all. */
+const liveScopes = new Set();
+let exitHookInstalled = false;
+function installExitBackstop() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    // Idempotent, synchronous backstop: a process that exits mid-scope (a
+    // `process.exit()` from a command, an uncaught fatal) still releases the
+    // handle and its maintenance-activity lockfile. Normal teardown happens in
+    // the scope's own `finally`, which removes the scope from `liveScopes`
+    // first, so this never double-closes.
+    process.on("exit", closeAllStateDbScopes);
+}
+/**
+ * Close every scope-owned handle. Idempotent and safe to call at any time: a
+ * closed scope stops lending, so in-flight borrowers fall back to their own
+ * connections instead of using a dead handle. Module-private: the per-scope
+ * `finally` plus the process-exit backstop above are what guarantee no handle
+ * leak — export this the day a caller actually wires deterministic teardown.
+ */
+function closeAllStateDbScopes() {
+    for (const scope of [...liveScopes])
+        closeScope(scope);
+}
+function closeScope(scope) {
+    scope.closed = true;
+    liveScopes.delete(scope);
+    const db = scope.db;
+    scope.db = undefined;
+    if (!db)
+        return;
+    try {
+        db.close();
+    }
+    catch {
+        // A close failure must never mask the caller's own error (or wedge exit).
+    }
+}
+/**
+ * The ambient scoped handle for `dbPath` (default: the canonical state.db), or
+ * `undefined` when there is no live scope for that exact path.
+ *
+ * The path comparison matters: the test harness repoints `AKM_DATA_DIR` between
+ * tests, and a scope entered against one data dir must never lend its handle to
+ * a caller resolving a different one.
+ */
+export function borrowScopedStateDb(dbPath) {
+    const scope = scopeStorage.getStore();
+    if (!scope || scope.closed)
+        return undefined;
+    if (path.resolve(dbPath ?? getStateDbPath()) !== scope.dbPath)
+        return undefined;
+    scope.db ??= openStateDatabase(scope.dbPath);
+    liveScopes.add(scope);
+    return scope.db;
+}
+/**
+ * Run `fn` with one shared state.db connection ambient for its whole async
+ * extent. The handle is opened on FIRST borrow (never eagerly) and closed once
+ * `fn` settles.
+ *
+ * Nesting is a no-op join: an inner scope for the same path reuses the outer
+ * scope's handle and does not close it, so a caller can enter a scope without
+ * knowing whether an outer frame already did.
+ */
+export async function withStateDbScope(fn, opts) {
+    const dbPath = path.resolve(opts?.path ?? getStateDbPath());
+    const outer = scopeStorage.getStore();
+    if (outer && !outer.closed && outer.dbPath === dbPath)
+        return fn();
+    const scope = { dbPath, db: undefined, closed: false };
+    installExitBackstop();
+    try {
+        return await scopeStorage.run(scope, fn);
+    }
+    finally {
+        closeScope(scope);
+    }
+}
+/** Test seam: how many scope-owned handles are currently open. Must return to 0. */
+export function openScopedStateDbCount() {
+    let count = 0;
+    for (const scope of liveScopes)
+        if (scope.db)
+            count++;
+    return count;
+}