@hasna/hooks 0.5.0 → 0.6.1

package/dist/lib/custom-install.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Custom hook install — sources outside the bundled registry.
+ *
+ * git URL  -> shallow clone, read manifest, copy into the custom dir
+ * local    -> copy a directory containing manifest.json
+ * https    -> fetch manifest.json (+ relative script file when needed)
+ */
+export type CustomSourceKind = "git" | "local" | "url";
+export interface CustomInstallResult {
+    name: string;
+    version: string;
+    kind: CustomSourceKind;
+    source: string;
+    dir: string;
+    scriptPath: string;
+}
+export declare function isCustomSource(value: string): boolean;
+export declare function installCustomSource(source: string): Promise<CustomInstallResult>;
+export declare function ensureCustomDir(): string;

package/dist/lib/manifest.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Hook manifest model — the contract for custom/remote hooks.
+ */
+import { z } from "zod";
+export declare const HOOK_NAME_RE: RegExp;
+export declare const manifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    events: z.ZodArray<z.ZodString, "many">;
+    script: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    events: string[];
+    name: string;
+    script: string;
+    description?: string | undefined;
+    args?: string[] | undefined;
+    timeout_ms?: number | undefined;
+}, {
+    version: string;
+    events: string[];
+    name: string;
+    script: string;
+    description?: string | undefined;
+    args?: string[] | undefined;
+    timeout_ms?: number | undefined;
+}>;
+export type HookManifest = z.infer<typeof manifestSchema>;
+export interface ParsedManifest {
+    manifest: HookManifest;
+    scriptPath: string;
+    scriptContent: string;
+    scriptIsInline: boolean;
+}
+export declare function parseManifest(json: string): HookManifest;
+export declare function normalizeManifestName(name: string): string;
+export declare function shortManifestName(name: string): string;
+/**
+ * A manifest script path resolved outside its hook's own directory.
+ * Carries the offending path so callers can surface it verbatim.
+ */
+export declare class ScriptContainmentError extends Error {
+    constructor(path: string, hookDir: string, raw?: string);
+}
+/**
+ * Full containment check (lexical + symlink resolution). Requires `root` to
+ * exist. For write targets that do not exist yet, call
+ * assertContainedLexical first (before creating anything), then create the
+ * root, then call assertContainedReal.
+ */
+export declare function assertContained(target: string, root: string, raw?: string): string;
+/**
+ * Resolve a manifest's script to (relative path, content).
+ * A script value containing a newline is inline content; anything else is a
+ * relative path resolved against the manifest directory.
+ */
+export declare function resolveScript(manifest: HookManifest, manifestDir: string): {
+    path: string;
+    content: string;
+};
+export declare function customHookDir(name: string): string;
+export declare function readCustomManifest(name: string): ParsedManifest | undefined;
+export declare function listCustomHooks(): ParsedManifest[];
+export declare function writeCustomHook(name: string, manifest: HookManifest, scriptContent: string, scriptRelPath: string): {
+    dir: string;
+    scriptPath: string;
+};

package/dist/lib/resolve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hook resolution — custom directory first, bundled registry second.
+ * A custom hook that collides with a bundled name shadows it.
+ */
+import { type HookMeta } from "./registry.js";
+export type HookSource = "custom" | "bundled";
+export interface ResolvedHook {
+    name: string;
+    source: HookSource;
+    version: string;
+    events: string[];
+    description: string;
+    scriptPath: string;
+    meta: HookMeta;
+}
+export declare function resolveHookDir(name: string): string | undefined;
+export declare function resolveScriptPath(name: string): string | undefined;
+export declare function resolveHookMeta(name: string): HookMeta | undefined;
+export declare function resolveHook(name: string): ResolvedHook | undefined;

package/dist/lib/run.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Verified hook execution — the verified bytes are the executed bytes.
+ *
+ * The trust check hashes the script content once; executing a PATH afterwards
+ * would re-open the file and could run different bytes (TOCTOU). So the
+ * verified content is written to a runner-owned temp file next to the original
+ * script and that file is executed. The original path is never opened for
+ * execution after verification.
+ *
+ * The temp file sits in the script's own directory so the hook's relative
+ * imports resolve exactly as they do today (bundled hooks import shared
+ * modules like ../../../src/lib/db-writer). A temp file in the system tmp dir
+ * would break that resolution.
+ */
+export interface VerifiedRunOptions {
+    /** Registered hook name (for error messages) */
+    name: string;
+    /**
+     * The hook's on-disk script path. Only its directory and basename are used:
+     * the path itself is never re-opened for execution.
+     */
+    scriptPath: string;
+    /** The verified bytes to execute — exactly what was hashed and trusted */
+    content: Buffer;
+    /** Args passed through to the hook script */
+    args?: string[];
+    /** Input passed to the hook on stdin */
+    stdin: string;
+    env?: Record<string, string | undefined>;
+    timeout?: number;
+}
+export interface VerifiedRunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare function executeVerifiedScript(options: VerifiedRunOptions): Promise<VerifiedRunResult>;

package/dist/lib/store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Hook store — SQLite hooks table + hooks.lock pin file.
+ *
+ * The DB record and the lock pin are written together so a verified hash is
+ * never trusted on one surface only. The lock file is the portable pin that a
+ * remote registry sync compares against.
+ */
+import type { Database } from "bun:sqlite";
+export interface HookRecord {
+    id: string;
+    name: string;
+    version: string;
+    sha256: string;
+    source_type: string;
+    source_ref: string | null;
+    installed_at: string;
+    enabled: number;
+    last_verified_at: string | null;
+}
+export interface LockEntry {
+    version: string;
+    sha256: string;
+    source: string;
+}
+export interface LockFile {
+    hooks: Record<string, LockEntry>;
+}
+export declare function sha256Of(input: Buffer | string): string;
+export declare function sha256File(path: string): Promise<string>;
+export declare function getHookRecord(db: Database, name: string): HookRecord | null;
+export declare function listHookRecords(db: Database): HookRecord[];
+export declare function upsertHookRecord(db: Database, record: {
+    name: string;
+    version: string;
+    sha256: string;
+    source_type: string;
+    source_ref?: string | null;
+    enabled?: number;
+    last_verified_at?: string | null;
+}): void;
+export declare function removeHookRecord(db: Database, name: string): boolean;
+export declare function readLock(): LockFile;
+export declare function writeLock(lock: LockFile): string;
+export declare function setPinnedHook(name: string, entry: LockEntry): string;
+export declare function getPinnedHook(name: string): LockEntry | undefined;
+export declare function removePinnedHook(name: string): boolean;
+export interface TrustCheck {
+    ok: boolean;
+    pinned: boolean;
+    expected: string | null;
+    actual: string;
+    name: string;
+}
+/**
+ * Check a hook script's content hash against the trusted record.
+ * No record exists (first run) => pin the current hash and pass.
+ * Record or pin exists and differs => refuse.
+ *
+ * Takes a precomputed hash so callers can verify the exact bytes they are
+ * about to execute (content-based verification), instead of re-reading a path.
+ */
+export declare function checkScriptHash(name: string, actual: string): TrustCheck;
+/**
+ * Verify a hook script's content hash against the trusted record, reading the
+ * script from disk. Execution paths should prefer checkScriptHash with the
+ * bytes they already hold so the verified bytes are the executed bytes.
+ */
+export declare function verifyScriptHash(name: string, scriptPath: string): Promise<TrustCheck>;
+export declare function retrustHook(name: string, scriptPath: string, version: string, source: string): TrustCheck;

package/dist/lib/sync.d.ts

@@ -0,0 +1,35 @@
+/**
+ * hooks sync — reconcile the local store against the remote registry (when an
+ * API URL is configured) or the bundled registry (otherwise).
+ *
+ * Fail-closed: every network read happens before anything is written, so a
+ * failure mid-sync leaves the local store untouched. Local-only hooks are
+ * never deleted by a remote sync.
+ */
+export interface SyncDiff {
+    added: string[];
+    updated: string[];
+    unchanged: string[];
+    skipped: string[];
+}
+export interface SyncPlan {
+    apiUrl: string | null;
+    dryRun: boolean;
+    diff: SyncDiff;
+}
+export interface ArtifactResponse {
+    manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        events: string[];
+        script: string;
+        args?: string[];
+        timeout_ms?: number;
+    };
+    script: string;
+}
+export declare function planSync(): Promise<SyncPlan>;
+export declare function syncHooks(options?: {
+    dryRun?: boolean;
+}): Promise<SyncPlan>;

package/dist/serve.d.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * hooks serve — the local registry HTTP API.
+ *
+ * Catalog and artifact reads are open; publishing (PUT) requires the API key.
+ * The published set is hooks.lock, the same pin file the client syncs from.
+ */
+export declare const DEFAULT_SERVE_PORT = 39428;
+export declare const SERVE_HOST = "127.0.0.1";
+export declare const SERVE_SERVICE_NAME = "hooks-registry";
+export interface CatalogEntry {
+    name: string;
+    version: string;
+    sha256: string;
+    events: string[];
+    description: string;
+    source: string;
+}
+export interface ArtifactPayload {
+    manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        events: string[];
+        script: string;
+        args?: string[];
+        timeout_ms?: number;
+    };
+    script: string;
+}
+export declare function handleServeRequest(req: Request, apiKey: string | undefined): Promise<Response>;
+export declare function startServeServer(options: {
+    port?: number;
+    host?: string;
+    apiKey?: string;
+}): ReturnType<typeof Bun.serve>;

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-export { HOOKS_STORAGE_ENV, HOOKS_STORAGE_FALLBACK_ENV, HOOKS_STORAGE_MODE_ENV, HOOKS_STORAGE_MODE_FALLBACK_ENV, HOOKS_STORAGE_TABLES, STORAGE_DATABASE_ENV, STORAGE_MODE_ENV, STORAGE_TABLES, getStorageDatabaseEnv, getStorageDatabaseEnvName, getStorageDatabaseUrl, getStorageMode, getStoragePg, getStorageStatus, getSyncMetaAll, parseStorageTables, resolveTables, runStorageMigrations, storagePull, storagePush, storageSync, } from "./db/storage-sync.js";
-export type { StorageEnv, StorageMode, StorageStatus, SyncMeta, SyncResult } from "./db/storage-sync.js";
+export { HOOKS_STORAGE_ENV, HOOKS_STORAGE_FALLBACK_ENV, HOOKS_STORAGE_BACKEND_ENV, HOOKS_STORAGE_BACKEND_FALLBACK_ENV, HOOKS_STORAGE_TABLES, RETIRED_STORAGE_MODE_ENV, STORAGE_BACKENDS, STORAGE_BACKEND_ENV, STORAGE_DATABASE_ENV, STORAGE_TABLES, getStorageBackend, getStorageDatabaseEnv, getStorageDatabaseEnvName, getStorageDatabaseUrl, getStoragePg, getStorageStatus, getSyncMetaAll, parseStorageTables, resolveTables, runStorageMigrations, storagePull, storagePush, storageSync, } from "./db/storage-sync.js";
+export type { StorageBackend, StorageEnv, StorageStatus, SyncMeta, SyncResult } from "./db/storage-sync.js";
 export { PgAdapterAsync } from "./db/remote-storage.js";
 export { PG_MIGRATIONS } from "./db/pg-migrations.js";

package/dist/storage.js

@@ -15,12 +15,6 @@ var __export = (target, all) => {
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
-// src/db/index.ts
-import { Database } from "bun:sqlite";
-import { existsSync as existsSync2, mkdirSync, cpSync } from "fs";
-import { join as join2 } from "path";
-import { homedir as homedir2 } from "os";
-
 // src/db/schema.ts
 var CREATE_HOOK_EVENTS_TABLE = `
   CREATE TABLE IF NOT EXISTS hook_events (
@@ -37,14 +31,16 @@ var CREATE_HOOK_EVENTS_TABLE = `
     project_dir  TEXT,
     metadata     TEXT
   )
-`;
-var CREATE_INDEXES = [
-  `CREATE INDEX IF NOT EXISTS idx_hook_events_timestamp  ON hook_events (timestamp)`,
-  `CREATE INDEX IF NOT EXISTS idx_hook_events_session_id ON hook_events (session_id)`,
-  `CREATE INDEX IF NOT EXISTS idx_hook_events_hook_name  ON hook_events (hook_name)`,
-  `CREATE INDEX IF NOT EXISTS idx_hook_events_event_type ON hook_events (event_type)`,
-  `CREATE INDEX IF NOT EXISTS idx_hook_events_errors     ON hook_events (timestamp) WHERE error IS NOT NULL`
-];
+`, CREATE_INDEXES;
+var init_schema = __esm(() => {
+  CREATE_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_hook_events_timestamp  ON hook_events (timestamp)`,
+    `CREATE INDEX IF NOT EXISTS idx_hook_events_session_id ON hook_events (session_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_hook_events_hook_name  ON hook_events (hook_name)`,
+    `CREATE INDEX IF NOT EXISTS idx_hook_events_event_type ON hook_events (event_type)`,
+    `CREATE INDEX IF NOT EXISTS idx_hook_events_errors     ON hook_events (timestamp) WHERE error IS NOT NULL`
+  ];
+});
 
 // src/db/migrations/001_initial.ts
 function up(db) {
@@ -53,6 +49,9 @@ function up(db) {
     db.exec(idx);
   }
 }
+var init_001_initial = __esm(() => {
+  init_schema();
+});
 
 // src/db/migrations/002_session_events.ts
 function up2(db) {
@@ -79,6 +78,9 @@ function up2(db) {
     throw err;
   }
 }
+var init_002_session_events = __esm(() => {
+  init_schema();
+});
 
 // src/db/migrations/003_user_prompt_submit_event.ts
 function up3(db) {
@@ -105,13 +107,37 @@ function up3(db) {
     throw err;
   }
 }
+var init_003_user_prompt_submit_event = __esm(() => {
+  init_schema();
+});
+
+// src/db/migrations/004_hooks_table.ts
+function up4(db) {
+  db.exec(CREATE_HOOKS_TABLE);
+  for (const idx of CREATE_HOOKS_INDEXES) {
+    db.exec(idx);
+  }
+}
+var CREATE_HOOKS_TABLE = `
+  CREATE TABLE IF NOT EXISTS hooks (
+    id               TEXT PRIMARY KEY,
+    name             TEXT NOT NULL,
+    version          TEXT NOT NULL,
+    sha256           TEXT NOT NULL,
+    source_type      TEXT NOT NULL,
+    source_ref       TEXT,
+    installed_at     TEXT NOT NULL,
+    enabled          INTEGER NOT NULL DEFAULT 1,
+    last_verified_at TEXT
+  )
+`, CREATE_HOOKS_INDEXES;
+var init_004_hooks_table = __esm(() => {
+  CREATE_HOOKS_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_hooks_name ON hooks (name)`
+  ];
+});
 
 // src/db/migrations/index.ts
-var MIGRATIONS = [
-  { version: "001_initial", up },
-  { version: "002_session_events", up: up2 },
-  { version: "003_user_prompt_submit_event", up: up3 }
-];
 function ensureMigrationsTable(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
@@ -137,12 +163,24 @@ function runMigrations(db) {
     ]);
   }
 }
+var MIGRATIONS;
+var init_migrations = __esm(() => {
+  init_001_initial();
+  init_002_session_events();
+  init_003_user_prompt_submit_event();
+  init_004_hooks_table();
+  MIGRATIONS = [
+    { version: "001_initial", up },
+    { version: "002_session_events", up: up2 },
+    { version: "003_user_prompt_submit_event", up: up3 },
+    { version: "004_hooks_table", up: up4 }
+  ];
+});
 
 // src/db/legacy-import.ts
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-var META_KEY = "legacy_import_done";
 function ensureMetaTable(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS _meta (
@@ -216,12 +254,12 @@ function importErrorsLog(db, filePath) {
   } catch {}
   return count;
 }
-function runLegacyImport(db) {
+function runLegacyImport(db, homeDir = homedir()) {
   try {
     if (isAlreadyDone(db))
       return;
     let total = 0;
-    const claudeProjectsDir = join(homedir(), ".claude", "projects");
+    const claudeProjectsDir = join(homeDir, ".claude", "projects");
     if (existsSync(claudeProjectsDir)) {
       try {
         const projectDirs = readdirSync(claudeProjectsDir);
@@ -251,6 +289,8 @@ function runLegacyImport(db) {
 `);
   }
 }
+var META_KEY = "legacy_import_done";
+var init_legacy_import = () => {};
 
 // src/db/retention.ts
 function runRetention(db, days) {
@@ -267,7 +307,10 @@ function runRetention(db, days) {
 }
 
 // src/db/index.ts
-var instance = null;
+import { Database } from "bun:sqlite";
+import { existsSync as existsSync2, mkdirSync, cpSync } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
 function resolveDataDir() {
   const explicit = process.env.HASNA_HOOKS_DATA_DIR ?? process.env.HOOKS_DATA_DIR;
   if (explicit)
@@ -318,6 +361,14 @@ function getDb() {
   }
   return instance;
 }
+var instance = null;
+var init_db = __esm(() => {
+  init_migrations();
+  init_legacy_import();
+});
+
+// src/db/storage-sync.ts
+init_db();
 
 // src/db/pg-migrations.ts
 var PG_MIGRATIONS = [
@@ -402,12 +453,14 @@ var STORAGE_TABLES = [
   "feedback"
 ];
 var HOOKS_STORAGE_TABLES = STORAGE_TABLES;
+var STORAGE_BACKENDS = ["sqlite", "postgresql"];
 var HOOKS_STORAGE_ENV = "HASNA_HOOKS_DATABASE_URL";
 var HOOKS_STORAGE_FALLBACK_ENV = "HOOKS_DATABASE_URL";
-var HOOKS_STORAGE_MODE_ENV = "HASNA_HOOKS_STORAGE_MODE";
-var HOOKS_STORAGE_MODE_FALLBACK_ENV = "HOOKS_STORAGE_MODE";
+var HOOKS_STORAGE_BACKEND_ENV = "HASNA_HOOKS_STORAGE_BACKEND";
+var HOOKS_STORAGE_BACKEND_FALLBACK_ENV = "HOOKS_STORAGE_BACKEND";
 var STORAGE_DATABASE_ENV = [HOOKS_STORAGE_ENV, HOOKS_STORAGE_FALLBACK_ENV];
-var STORAGE_MODE_ENV = [HOOKS_STORAGE_MODE_ENV, HOOKS_STORAGE_MODE_FALLBACK_ENV];
+var STORAGE_BACKEND_ENV = [HOOKS_STORAGE_BACKEND_ENV, HOOKS_STORAGE_BACKEND_FALLBACK_ENV];
+var RETIRED_STORAGE_MODE_ENV = ["HASNA_HOOKS_STORAGE_MODE", "HOOKS_STORAGE_MODE"];
 var PRIMARY_KEYS = {
   hook_events: ["id"],
   schema_migrations: ["version"],
@@ -418,11 +471,46 @@ function readEnv(name) {
   const value = process.env[name]?.trim();
   return value || undefined;
 }
-function normalizeStorageMode(value) {
-  const normalized = value?.trim().toLowerCase();
-  if (normalized === "local" || normalized === "hybrid" || normalized === "remote")
-    return normalized;
-  return;
+var RETIRED_MODE_REPLACEMENT = {
+  local: "sqlite",
+  hybrid: "postgresql",
+  remote: "postgresql",
+  self_hosted: "postgresql",
+  "self-hosted": "postgresql",
+  selfhosted: "postgresql",
+  cloud: "postgresql"
+};
+var BACKEND_ALIASES = {
+  sqlite: "sqlite",
+  sqlite3: "sqlite",
+  postgresql: "postgresql",
+  postgres: "postgresql",
+  pg: "postgresql"
+};
+function assertNoRetiredModeEnv() {
+  for (const name of RETIRED_STORAGE_MODE_ENV) {
+    const value = readEnv(name);
+    if (!value)
+      continue;
+    const replacement = RETIRED_MODE_REPLACEMENT[value.trim().toLowerCase()];
+    const mapping = replacement ? `${value} maps to ${replacement}` : `use one of ${STORAGE_BACKENDS.join(", ")}`;
+    throw new Error(`${name} is a retired deployment-mode variable and is no longer read. ` + `Hooks storage is a data-backend switch, not a deployment mode: ` + `set ${HOOKS_STORAGE_BACKEND_ENV} to ${STORAGE_BACKENDS.join(" or ")} instead (${mapping}), ` + `then unset ${name}.`);
+  }
+}
+function normalizeStorageBackend(value, envName) {
+  if (value === undefined)
+    return;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "")
+    return;
+  const backend = BACKEND_ALIASES[normalized];
+  if (backend)
+    return backend;
+  const replacement = RETIRED_MODE_REPLACEMENT[normalized];
+  if (replacement) {
+    throw new Error(`${envName}=${value} names a retired deployment mode. ` + `local/hybrid/remote/self_hosted/cloud were removed: hooks storage now selects a data ` + `backend only. Set ${envName}=${replacement} instead.`);
+  }
+  throw new Error(`${envName}=${value} is not a known hooks storage backend. ` + `Set ${HOOKS_STORAGE_BACKEND_ENV} to one of ${STORAGE_BACKENDS.join(", ")}.`);
 }
 function getStorageDatabaseEnvName() {
   for (const name of STORAGE_DATABASE_ENV) {
@@ -439,11 +527,12 @@ function getStorageDatabaseUrl() {
   const env = getStorageDatabaseEnv();
   return env ? readEnv(env.name) ?? null : null;
 }
-function getStorageMode() {
-  const mode = normalizeStorageMode(readEnv(HOOKS_STORAGE_MODE_ENV)) ?? normalizeStorageMode(readEnv(HOOKS_STORAGE_MODE_FALLBACK_ENV));
-  if (mode)
-    return mode;
-  return getStorageDatabaseUrl() ? "hybrid" : "local";
+function getStorageBackend() {
+  assertNoRetiredModeEnv();
+  const backend = normalizeStorageBackend(readEnv(HOOKS_STORAGE_BACKEND_ENV), HOOKS_STORAGE_BACKEND_ENV) ?? normalizeStorageBackend(readEnv(HOOKS_STORAGE_BACKEND_FALLBACK_ENV), HOOKS_STORAGE_BACKEND_FALLBACK_ENV);
+  if (backend)
+    return backend;
+  return getStorageDatabaseUrl() ? "postgresql" : "sqlite";
 }
 async function getStoragePg() {
   const url = getStorageDatabaseUrl();
@@ -501,7 +590,7 @@ function getStorageStatus() {
   const activeEnv = getStorageDatabaseEnv();
   return {
     configured: Boolean(activeEnv),
-    mode: getStorageMode(),
+    backend: getStorageBackend(),
     env: STORAGE_DATABASE_ENV,
     activeEnv: activeEnv?.name ?? null,
     service: "hooks",
@@ -679,18 +768,20 @@ export {
   getSyncMetaAll,
   getStorageStatus,
   getStoragePg,
-  getStorageMode,
   getStorageDatabaseUrl,
   getStorageDatabaseEnvName,
   getStorageDatabaseEnv,
+  getStorageBackend,
   STORAGE_TABLES,
-  STORAGE_MODE_ENV,
   STORAGE_DATABASE_ENV,
+  STORAGE_BACKEND_ENV,
+  STORAGE_BACKENDS,
+  RETIRED_STORAGE_MODE_ENV,
   PgAdapterAsync,
   PG_MIGRATIONS,
   HOOKS_STORAGE_TABLES,
-  HOOKS_STORAGE_MODE_FALLBACK_ENV,
-  HOOKS_STORAGE_MODE_ENV,
   HOOKS_STORAGE_FALLBACK_ENV,
-  HOOKS_STORAGE_ENV
+  HOOKS_STORAGE_ENV,
+  HOOKS_STORAGE_BACKEND_FALLBACK_ENV,
+  HOOKS_STORAGE_BACKEND_ENV
 };

package/hooks/codewith-native-common.test.ts

@@ -1675,7 +1675,14 @@ describe("destructive shell guard - rm -rf /* incident regression", () => {
       expect(result.block).toBe(true);
       expect(performance.now() - started).toBeLessThan(3000);
     }
-  });
+    // Three iterations, each gated at 3000ms above, so this test's own assertions permit up to
+    // 9000ms and still pass. The runner budget therefore has to sit strictly ABOVE 9000 or the
+    // runner kills a run the assertions consider passing, and a genuine regression reads as an
+    // infrastructure timeout rather than as the assertion's message — the same failure the
+    // oversized-command test below was given a budget for. Building the 70k-element flood sits
+    // outside the timed regions and is unmeasured by them. Measured 3.5-4.1s in total alone at
+    // load ~15; 20000 is over twice what its own assertions already allow.
+  }, 20000);
 
   test("an unpinnable target says why it was refused", async () => {
     // Reporting only "targets /" for `rm -rf /var[.]log` is wrong and gets a guard switched
@@ -1779,7 +1786,13 @@ describe("destructive shell guard - rm -rf /* incident regression", () => {
     expect((await classify(`${oversized}; rm -rf /*`)).block).toBe(true);
     expect((await classify(oversized.replace(/cd /g, "echo "))).block).toBe(false);
     expect(performance.now() - started).toBeLessThan(15000);
-  });
+    // The 15000ms assertion above is this test's real gate, so the runner budget must sit
+    // strictly ABOVE it: at bun's 5000ms default the runner kills the test at 5s and the
+    // assertion never gets to speak, which reads as an infrastructure timeout rather than
+    // as the regression it is. Measured cost is ~10.0-11.0s on a contended 20-core box
+    // (load ~30); 30000 is double the assertion and ~3x the observed need, so a slow run
+    // still fails on the assertion's message and only a true hang reaches this backstop.
+  }, 30000);
 
   // -------------------------------------------------------------------------------------
   // Adversarial review round 11. All three bounds added the round before turned into root