@tpsdev-ai/flair 0.6.0 → 0.6.2

package/dist/bridges/runtime/allow-list.js

@@ -0,0 +1,198 @@
+/**
+ * Trust allow-list for npm code-plugin bridges.
+ *
+ * A Shape B bridge is arbitrary JavaScript fetched from npm. The spec §7
+ * requires explicit operator opt-in on first use: `flair bridge allow <name>`
+ * records the approval; subsequent invocations see the bridge on the
+ * allow-list and skip the prompt. `flair bridge revoke <name>` removes it.
+ *
+ * Approvals are pinned to a concrete package location and its package.json
+ * content digest. A name-only approval is not enough: a malicious package
+ * squatting on an allowed short-name in a different `node_modules` tree
+ * (e.g. the user approved `mem0` in ProjectA, then cd'd into ProjectB which
+ * ships a planted `node_modules/flair-bridge-mem0`) would otherwise load
+ * under the existing trust record. Each entry therefore captures:
+ *
+ *   - packageDir:        canonical (realpath) directory where the approved
+ *                        package lives on disk at allow-time.
+ *   - packageJsonSha256: hex sha256 of the package's package.json content.
+ *   - version:           the package's self-reported version (display only;
+ *                        the sha is what enforces identity).
+ *
+ * At load-time, `verifyAllow(discovered)` re-checks all three. A change in
+ * any triggers a BridgeRuntimeError pointing the operator back at
+ * `flair bridge allow` — either the move is intentional (re-approve) or
+ * it is a squat (refuse).
+ *
+ * Design notes:
+ *  - YAML (Shape A) + built-in bridges skip this gate entirely. They don't
+ *    execute arbitrary JS.
+ *  - The store is a simple JSON file at ~/.flair/bridges-allowed.json.
+ *    No separate DB, no Harper dependency — the trust decision should
+ *    still work when Flair's own service is down.
+ *  - Migration: older entries from 0.6.0/0.6.1 carry only {name, allowedAt}.
+ *    `verifyAllow` treats those as invalid and forces re-approval on next
+ *    load. Acceptable cost — no known external consumers pre-1.0.
+ */
+import { promises as fsp } from "node:fs";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+function resolvePath(opts) {
+    return opts?.path ?? join(homedir(), ".flair", "bridges-allowed.json");
+}
+function hasEntryFields(e) {
+    return (typeof e?.name === "string" &&
+        typeof e?.allowedAt === "string" &&
+        typeof e?.packageDir === "string" &&
+        typeof e?.packageJsonSha256 === "string");
+}
+async function read(path) {
+    if (!existsSync(path))
+        return { allowed: [] };
+    try {
+        const raw = await fsp.readFile(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.allowed))
+            return { allowed: [] };
+        // Keep structurally valid entries only. Legacy name-only rows are
+        // dropped here so `verifyAllow` reports not-allowed (forcing re-approve).
+        return {
+            allowed: parsed.allowed.filter(hasEntryFields).map((e) => ({
+                name: e.name,
+                allowedAt: e.allowedAt,
+                packageDir: e.packageDir,
+                packageJsonSha256: e.packageJsonSha256,
+                ...(typeof e.version === "string" ? { version: e.version } : {}),
+            })),
+        };
+    }
+    catch {
+        return { allowed: [] };
+    }
+}
+async function write(path, data) {
+    await fsp.mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    await fsp.rename(tmp, path);
+}
+/**
+ * Canonicalize a filesystem path. Resolves symlinks so node_modules hoisting
+ * and pnpm-style content-addressed stores still hash-match reliably.
+ */
+async function canonical(path) {
+    try {
+        return await fsp.realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Hash a package's package.json file. The sha changes whenever the package
+ * contents "change enough to matter" — version bumps, name changes, and
+ * realistically most substantive updates touch package.json. It is NOT a
+ * hash of every file in the package; that would be slower and more fragile
+ * without closing the meaningful attack paths (since a squatter needs the
+ * right package.json anyway to survive discovery).
+ */
+export async function digestPackage(packageDir) {
+    const canonicalDir = await canonical(packageDir);
+    const pkgJsonPath = join(canonicalDir, "package.json");
+    const raw = await fsp.readFile(pkgJsonPath, "utf-8");
+    const sha = createHash("sha256").update(raw).digest("hex");
+    let version;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.version === "string")
+            version = parsed.version;
+    }
+    catch {
+        // A malformed package.json is itself a refusal signal — but leave that
+        // to the import path; here we just decline to record a version.
+    }
+    return { canonicalDir, sha256: sha, version };
+}
+/**
+ * Check if a name appears in the allow-list. Useful for UI listings; NOT a
+ * trust decision — use `verifyAllow` for load-time security checks.
+ */
+export async function isAllowed(name, opts) {
+    const data = await read(resolvePath(opts));
+    return data.allowed.some((e) => e.name === name);
+}
+/**
+ * Load-time trust check. Verifies the discovered package still matches the
+ * approval record by canonical path AND package.json sha. Anything else is
+ * a refusal — the operator must re-run `flair bridge allow <name>`.
+ */
+export async function verifyAllow(discovered, opts) {
+    const data = await read(resolvePath(opts));
+    const entry = data.allowed.find((e) => e.name === discovered.name);
+    if (!entry)
+        return { ok: false, reason: "not-allowed" };
+    // Guard: if we ever loaded a partial record, refuse. Belt-and-braces;
+    // read() already filters these, but if someone hand-edits the file we
+    // don't want to silently bypass the check.
+    if (!entry.packageDir || !entry.packageJsonSha256) {
+        return { ok: false, reason: "entry-incomplete", entry };
+    }
+    let observed;
+    try {
+        observed = await digestPackage(discovered.path);
+    }
+    catch {
+        return { ok: false, reason: "package-missing", entry };
+    }
+    if (observed.canonicalDir !== entry.packageDir) {
+        return { ok: false, reason: "path-mismatch", entry, observedPath: observed.canonicalDir };
+    }
+    if (observed.sha256 !== entry.packageJsonSha256) {
+        return { ok: false, reason: "digest-mismatch", entry, observedDigest: observed.sha256 };
+    }
+    return { ok: true, entry };
+}
+/**
+ * Approve a package for code-plugin execution. `packageDir` must be the
+ * directory holding the package.json — typically discovered via
+ * `flair bridge list` and passed through by the CLI layer.
+ */
+export async function allow(name, packageDir, opts) {
+    const listPath = resolvePath(opts);
+    const data = await read(listPath);
+    const { canonicalDir, sha256, version } = await digestPackage(packageDir);
+    const now = new Date().toISOString();
+    const existing = data.allowed.find((e) => e.name === name);
+    if (existing && existing.packageDir === canonicalDir && existing.packageJsonSha256 === sha256) {
+        return { alreadyAllowed: true, updated: false, entry: existing };
+    }
+    const entry = {
+        name,
+        allowedAt: now,
+        packageDir: canonicalDir,
+        packageJsonSha256: sha256,
+        ...(version ? { version } : {}),
+    };
+    data.allowed = data.allowed.filter((e) => e.name !== name);
+    data.allowed.push(entry);
+    data.allowed.sort((a, b) => a.name.localeCompare(b.name));
+    await write(listPath, data);
+    return { alreadyAllowed: false, updated: !!existing, entry };
+}
+export async function revoke(name, opts) {
+    const path = resolvePath(opts);
+    const data = await read(path);
+    const before = data.allowed.length;
+    data.allowed = data.allowed.filter((e) => e.name !== name);
+    if (data.allowed.length === before) {
+        return { wasAllowed: false };
+    }
+    await write(path, data);
+    return { wasAllowed: true };
+}
+export async function list(opts) {
+    const data = await read(resolvePath(opts));
+    return data.allowed;
+}

package/dist/bridges/runtime/import-runner.js

@@ -26,7 +26,11 @@ export async function runImport(opts) {
     let total = 0;
     let imported = 0;
     let skipped = 0;
-    for await (const m of importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })) {
+    const iterable = opts.source
+        ?? (opts.descriptor
+            ? importFromYaml(opts.descriptor, { cwd: opts.cwd, ctx: opts.ctx })
+            : (() => { throw new BridgeRuntimeError({ bridge: opts.bridgeName, op: "import", field: "(source)", expected: "descriptor or source", got: "neither", hint: "runImport requires exactly one of opts.descriptor (YAML) or opts.source (AsyncIterable)" }); })());
+    for await (const m of iterable) {
         total++;
         const resolvedAgent = m.agentId ?? opts.agentId;
         if (!resolvedAgent) {
@@ -35,7 +39,7 @@ export async function runImport(opts) {
             // the operator should know whether this is a descriptor bug or a
             // missing flag.
             throw new BridgeRuntimeError({
-                bridge: opts.descriptor.name,
+                bridge: opts.bridgeName,
                 op: "import",
                 field: "agentId",
                 expected: "set on record OR provided via --agent",
@@ -86,7 +90,7 @@ export async function runImport(opts) {
         catch (err) {
             // Wrap PUT errors so they read consistently with other BridgeRuntimeErrors.
             throw new BridgeRuntimeError({
-                bridge: opts.descriptor.name,
+                bridge: opts.bridgeName,
                 op: "import",
                 record: total,
                 field: "(write)",

package/dist/bridges/runtime/load-bridge.js

@@ -0,0 +1,126 @@
+/**
+ * Unified loader for all bridge sources (replaces load-descriptor.ts).
+ *
+ * Returns a `LoadedBridge` discriminated union. Runners dispatch on
+ * `.kind`:
+ *   - "yaml": use the existing YAML runtime (applyMap, parseRecords, etc.)
+ *   - "code": call the plugin's bridge.import() / bridge.export() directly
+ *
+ * For code-plugin sources (npm packages), the allow-list gate runs first:
+ * if not allowed, throw a BridgeRuntimeError pointing the operator at
+ * `flair bridge allow <name>`.
+ */
+import { BridgeRuntimeError } from "../types.js";
+import { loadYamlDescriptor } from "./yaml-loader.js";
+import { BUILTIN_BY_NAME } from "../builtins/index.js";
+import { loadCodePlugin } from "./load-plugin.js";
+import { verifyAllow } from "./allow-list.js";
+export async function loadBridge(discovered, opts = {}) {
+    switch (discovered.source) {
+        case "builtin": {
+            const builtin = BUILTIN_BY_NAME.get(discovered.name);
+            if (!builtin) {
+                throw new BridgeRuntimeError({
+                    bridge: discovered.name,
+                    op: "import",
+                    field: "(builtin)",
+                    expected: "registered built-in name",
+                    got: discovered.name,
+                    hint: `built-in "${discovered.name}" not in the registry — likely code drift between discover.ts and builtins/index.ts`,
+                });
+            }
+            return { kind: "yaml", descriptor: builtin.descriptor, source: discovered };
+        }
+        case "project-yaml":
+        case "user-yaml": {
+            const descriptor = await loadYamlDescriptor(discovered.path);
+            return { kind: "yaml", descriptor, source: discovered };
+        }
+        case "npm-package": {
+            if (!opts.skipAllowCheck) {
+                const verdict = await verifyAllow(discovered, { path: opts.allowListPath });
+                if (!verdict.ok) {
+                    throw new BridgeRuntimeError({
+                        bridge: discovered.name,
+                        op: "import",
+                        path: discovered.path,
+                        field: "(trust)",
+                        expected: verdict.reason === "not-allowed" ? "allow-listed code plugin" : "approved package at recorded location/digest",
+                        got: verdict.reason,
+                        hint: trustHint(discovered.name, verdict),
+                        context: trustContext(discovered, verdict),
+                    });
+                }
+            }
+            const plugin = await loadCodePlugin(discovered, { importer: opts.importer });
+            return { kind: "code", plugin, source: discovered };
+        }
+    }
+}
+function trustContext(discovered, verdict) {
+    switch (verdict.reason) {
+        case "not-allowed":
+            return { name: discovered.name };
+        case "path-mismatch":
+            return {
+                name: discovered.name,
+                approvedPath: verdict.entry.packageDir,
+                observedPath: verdict.observedPath,
+                approvedVersion: verdict.entry.version ?? "(unknown)",
+                approvedAt: verdict.entry.allowedAt,
+            };
+        case "digest-mismatch":
+            return {
+                name: discovered.name,
+                packagePath: verdict.entry.packageDir,
+                approvedVersion: verdict.entry.version ?? "(unknown)",
+                approvedDigest: verdict.entry.packageJsonSha256,
+                observedDigest: verdict.observedDigest,
+                approvedAt: verdict.entry.allowedAt,
+            };
+        case "entry-incomplete":
+            return { name: discovered.name };
+        case "package-missing":
+            return {
+                name: discovered.name,
+                approvedPath: verdict.entry?.packageDir ?? "(unknown)",
+                discoveredPath: discovered.path,
+            };
+    }
+}
+function trustHint(name, verdict) {
+    const reapprove = `flair bridge allow ${name}`;
+    switch (verdict.reason) {
+        case "not-allowed":
+            return `npm code plugins run arbitrary JavaScript. First-use approval required. Run: ${reapprove}`;
+        case "path-mismatch":
+            return `approved package lives at ${verdict.entry.packageDir}, but a different package with the same name was discovered at ${verdict.observedPath}. This is how local squatting attacks present. If the new location is intentional, re-run: ${reapprove}`;
+        case "digest-mismatch":
+            return `package.json contents changed since approval (recorded sha ${verdict.entry.packageJsonSha256.slice(0, 12)}…, observed ${verdict.observedDigest.slice(0, 12)}…). Re-run if the update is intentional: ${reapprove}`;
+        case "entry-incomplete":
+            return `allow-list entry for "${name}" is missing a location/digest (likely from a pre-fix Flair version). Re-run: ${reapprove}`;
+        case "package-missing":
+            return `package at ${verdict.entry?.packageDir ?? "(unknown)"} could not be read; allow-list verification cannot proceed`;
+    }
+}
+/**
+ * Kept as a shim for code paths that still call the old name. Remove once
+ * all call sites move to loadBridge directly.
+ *
+ * Returns the YAML descriptor when the source produces one; throws for
+ * code plugins (they don't have a YamlBridgeDescriptor representation).
+ */
+export async function loadDescriptor(discovered) {
+    const loaded = await loadBridge(discovered);
+    if (loaded.kind === "yaml")
+        return loaded.descriptor;
+    throw new BridgeRuntimeError({
+        bridge: discovered.name,
+        op: "import",
+        path: discovered.path,
+        field: "(kind)",
+        expected: "yaml descriptor",
+        got: "code plugin",
+        hint: "this code path expected a YAML descriptor; the bridge is a code plugin — caller should dispatch on loadBridge().kind instead",
+    });
+}

package/dist/bridges/runtime/load-plugin.js

@@ -0,0 +1,127 @@
+/**
+ * Dynamic loader for Shape B code-plugin bridges.
+ *
+ * Given a discovered `npm-package` source, dynamic-import the package,
+ * validate that it exports a `MemoryBridge`, and return the loaded module.
+ * The import is done via `createRequire` relative to the package root so
+ * scoped packages and deep nested deps resolve correctly.
+ *
+ * Validation is deliberately minimal: `name`, `version`, `kind`, and at
+ * least one of `import` / `export` must be present and look right. The
+ * spec §6 contract is "duck-type at runtime, strict error messages."
+ */
+import { pathToFileURL } from "node:url";
+import { BridgeRuntimeError } from "../types.js";
+const DEFAULT_IMPORTER = (spec) => import(spec);
+export async function loadCodePlugin(discovered, opts = {}) {
+    if (discovered.source !== "npm-package") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            field: "source",
+            expected: "npm-package",
+            got: discovered.source,
+            hint: "loadCodePlugin only handles Shape B (npm code plugin) bridges; YAML descriptors go through the YAML loader",
+        });
+    }
+    const importer = opts.importer ?? DEFAULT_IMPORTER;
+    // Package root path — the entry point is resolved by Node's package.json
+    // "main"/"exports" fields. Use a file:// URL so Node resolves it as a
+    // filesystem path rather than a bare specifier.
+    const spec = pathToFileURL(discovered.path + "/").href;
+    let mod;
+    try {
+        mod = await importer(spec);
+    }
+    catch (err) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "(import)",
+            expected: "importable npm package",
+            got: err?.code ?? "import error",
+            hint: `could not dynamic-import ${spec}: ${err?.message ?? err}`,
+        });
+    }
+    const candidate = pickBridgeExport(mod);
+    if (!candidate) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "exports",
+            expected: "named `bridge` export or default export implementing MemoryBridge",
+            got: typeof mod === "object" && mod !== null ? `exports=${Object.keys(mod).join(",") || "(empty)"}` : typeof mod,
+            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See specs/FLAIR-BRIDGES.md §6`,
+        });
+    }
+    // Validate the shape. Keep this minimal — we trust the plugin author
+    // to build a working MemoryBridge; we just need enough to route calls.
+    validateBridge(discovered, candidate);
+    return candidate;
+}
+function pickBridgeExport(mod) {
+    if (!mod || typeof mod !== "object")
+        return null;
+    const m = mod;
+    if (isBridgeLike(m.bridge))
+        return m.bridge;
+    if (isBridgeLike(m.default))
+        return m.default;
+    if (isBridgeLike(m))
+        return m;
+    return null;
+}
+function isBridgeLike(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const o = x;
+    return typeof o.name === "string" && (typeof o.import === "function" || typeof o.export === "function");
+}
+function validateBridge(discovered, b) {
+    if (typeof b.name !== "string" || !b.name) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "name",
+            expected: "non-empty string",
+            got: JSON.stringify(b.name),
+            hint: "MemoryBridge.name must be a non-empty string matching the npm package's flair-bridge-<name>",
+        });
+    }
+    if (b.name !== discovered.name) {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "name",
+            expected: `"${discovered.name}" (from package name flair-bridge-${discovered.name})`,
+            got: `"${b.name}"`,
+            hint: "MemoryBridge.name must match the npm package's public name suffix — mismatch would surprise discovery and allow-list lookups",
+        });
+    }
+    if (b.kind !== "file" && b.kind !== "api") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "kind",
+            expected: `"file" | "api"`,
+            got: JSON.stringify(b.kind),
+            hint: "MemoryBridge.kind must be 'file' or 'api'",
+        });
+    }
+    if (typeof b.import !== "function" && typeof b.export !== "function") {
+        throw new BridgeRuntimeError({
+            bridge: discovered.name,
+            op: "import",
+            path: discovered.path,
+            field: "(methods)",
+            expected: "at least one of `import` or `export`",
+            got: "neither",
+            hint: "MemoryBridge needs at least one of import/export implemented. See spec §6",
+        });
+    }
+}

package/dist/bridges/runtime/roundtrip.js

@@ -0,0 +1,154 @@
+/**
+ * Round-trip test harness for bridges.
+ *
+ * A bridge passes the round-trip test iff:
+ *   1. Parse the fixture (or descriptor's first import.source.path) → pass1 BridgeMemory[]
+ *   2. Apply export.targets[0]: when-filter → map → write to tmp in the
+ *      target's format
+ *   3. Re-import the tmp file using import.sources[0] → pass2 BridgeMemory[]
+ *   4. pass1 and pass2 must agree on the round-trip-stable fields from the
+ *      spec (§8): content, subject, tags, durability.
+ *
+ * This exercises the full mapper + predicate + writer + parser chain —
+ * if a bridge author's descriptor has mapping bugs, the round-trip
+ * surfaces them before memories ever reach Flair.
+ *
+ * Implementation note: does NOT talk to Flair. Fixture-to-fixture only.
+ * Lives here so slice-3c code plugins can reuse the same harness.
+ */
+import { promises as fsp } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { BridgeRuntimeError } from "../types.js";
+import { parseRecords } from "./formats.js";
+import { applyMap } from "./mapper.js";
+import { evaluatePredicate } from "./predicate.js";
+import { writeRecords } from "./writers.js";
+/** Fields the spec (§8) requires to survive round-trip. */
+export const ROUND_TRIP_STABLE_FIELDS = ["content", "subject", "tags", "durability"];
+export async function runRoundTrip(opts) {
+    const { descriptor, cwd } = opts;
+    if (!descriptor.import || descriptor.import.sources.length === 0) {
+        throw new BridgeRuntimeError({
+            bridge: descriptor.name,
+            op: "test",
+            field: "import",
+            expected: "descriptor with at least one import source",
+            got: "missing or empty",
+            hint: "round-trip needs an import block to start from. Add `import.sources:` to the descriptor.",
+        });
+    }
+    if (!descriptor.export || descriptor.export.targets.length === 0) {
+        throw new BridgeRuntimeError({
+            bridge: descriptor.name,
+            op: "test",
+            field: "export",
+            expected: "descriptor with at least one export target",
+            got: "missing or empty",
+            hint: "round-trip needs an export block to round-trip through. Add `export.targets:` to the descriptor.",
+        });
+    }
+    const importSource = descriptor.import.sources[0];
+    const exportTarget = descriptor.export.targets[0];
+    const resolvedFixture = resolvePath(cwd, opts.fixturePath ?? importSource.path);
+    const tmpDir = await fsp.mkdtemp(join(tmpdir(), `flair-bridge-test-${descriptor.name}-`));
+    const tmpPath = join(tmpDir, `roundtrip.${suffixForFormat(exportTarget.format)}`);
+    // Pass 1: fixture → BridgeMemory[]
+    const pass1 = [];
+    for await (const { record } of parseRecords(descriptor.name, resolvedFixture, importSource.format)) {
+        const mapped = applyMap(importSource.map, record);
+        pass1.push(mapped);
+    }
+    // Filter pass1 by the export target's when: (records filtered out wouldn't make it to the target).
+    const expected = [];
+    for (const m of pass1) {
+        if (!exportTarget.when || exportTarget.when.trim() === "") {
+            expected.push(m);
+            continue;
+        }
+        const result = evaluatePredicate(exportTarget.when, m);
+        if (result === "match" || result === "unparsable")
+            expected.push(m);
+    }
+    // Export phase: apply export.map, write to tmp
+    const shaped = [];
+    for (const m of expected) {
+        const out = applyMap(exportTarget.map, m);
+        if (Object.keys(out).length === 0)
+            continue;
+        shaped.push(out);
+    }
+    await writeRecords(descriptor.name, tmpPath, exportTarget.format, shaped);
+    // Pass 2: re-import the tmp using import.sources[0]'s map + format
+    // (round-trip requires the bridge's own import map applied to what export wrote).
+    const pass2 = [];
+    for await (const { record } of parseRecords(descriptor.name, tmpPath, importSource.format)) {
+        const mapped = applyMap(importSource.map, record);
+        pass2.push(mapped);
+    }
+    // Match pass1[expected] with pass2 by key (foreignId if present, else content)
+    // and diff the stable fields.
+    const keyOf = (m) => m.foreignId ?? (m.content ? `content:${m.content}` : "");
+    const pass2ByKey = new Map();
+    for (const m of pass2)
+        pass2ByKey.set(keyOf(m), m);
+    const mismatches = [];
+    const missingInPass2 = [];
+    for (let i = 0; i < expected.length; i++) {
+        const a = expected[i];
+        const key = keyOf(a);
+        const b = pass2ByKey.get(key);
+        if (!b) {
+            missingInPass2.push({ ordinal: i + 1, key });
+            continue;
+        }
+        for (const field of ROUND_TRIP_STABLE_FIELDS) {
+            if (!deepEqualField(a[field], b[field])) {
+                mismatches.push({ ordinal: i + 1, key, field, expected: a[field], got: b[field] });
+            }
+        }
+        // Matched this pass2 entry; remove so leftover tracking works
+        pass2ByKey.delete(key);
+    }
+    const unexpectedInPass2 = Array.from(pass2ByKey.keys()).map((key) => ({ key }));
+    const passed = mismatches.length === 0 && missingInPass2.length === 0 && unexpectedInPass2.length === 0;
+    return {
+        passed,
+        expectedCount: expected.length,
+        actualCount: pass2.length,
+        mismatches,
+        missingInPass2,
+        unexpectedInPass2,
+        tmpExportPath: tmpPath,
+    };
+}
+function deepEqualField(a, b) {
+    // tags is the only array-valued stable field today; deep-equal shallowly
+    // (order matters per our mapping; if a bridge re-orders tags, that's a
+    // round-trip regression worth catching).
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (a[i] !== b[i])
+                return false;
+        return true;
+    }
+    // string / number / boolean / undefined: strict equality
+    return a === b;
+}
+function suffixForFormat(format) {
+    switch (format) {
+        case "jsonl": return "jsonl";
+        case "json": return "json";
+        case "yaml": return "yaml";
+        case "markdown-frontmatter": return "md";
+        default: return "out";
+    }
+}
+function resolvePath(cwd, p) {
+    return isAbsolute(p) ? p : join(cwd, p);
+}
+// Keep randomUUID imported; future slice may use it for named tmp files.
+void randomUUID;

package/dist/cli.js

@@ -324,6 +324,51 @@ async function seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, adminUser, adm
         throw new Error(`Operations API insert failed (${res.status}): ${text}`);
     }
 }
+// ─── Upgrade presence probes ──────────────────────────────────────────────────
+//
+// `flair upgrade` previously called `npm list -g <pkg>` to detect the installed
+// version. That assumed the default npm global prefix and failed (silently,
+// reporting "not installed") for mise / fnm / nvm / volta users whose prefix
+// lives elsewhere — including for the running flair binary itself, which is
+// clearly installed somewhere. These probes locate the package regardless of
+// install path.
+export function probeBinVersion(execFileSync, bin) {
+    // Run the binary's --version via argv (no shell). PATH resolution still
+    // happens (so we find the binary wherever npm/mise/fnm installed it),
+    // but there's no shell-string to inject into. CodeQL-safe and simpler.
+    try {
+        const out = execFileSync(bin, ["--version"], {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!out)
+            return null;
+        // Accept either "0.6.0" on its own or a line containing a semver.
+        const m = out.match(/\b(\d+\.\d+\.\d+(?:[\d.a-z.-]*)?)\b/);
+        return m ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function probeLibVersion(pkgName) {
+    // Resolve the package's package.json from the running flair's module graph.
+    // If the lib is installed anywhere Node can see (including bundled as a
+    // dep of flair itself, sibling global install, or linked workspace), this
+    // finds it. If it's truly missing, require.resolve throws → null.
+    try {
+        const { createRequire } = require("node:module");
+        const req = createRequire(import.meta.url);
+        const pkgJsonPath = req.resolve(`${pkgName}/package.json`);
+        const { readFileSync } = require("node:fs");
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function templateSoul(choice) {
     const templates = {
         "1": [
@@ -2363,52 +2408,80 @@ program
     .option("--check", "Only check for updates, don't install")
     .option("--restart", "Restart Flair after upgrade")
     .action(async (opts) => {
-    const { execSync } = await import("node:child_process");
+    const { execSync, execFileSync } = await import("node:child_process");
     const checkOnly = opts.check ?? false;
     console.log("Checking for updates...\n");
+    // Per-package install probes. `npm list -g` assumed the default global
+    // prefix and silently mis-reported "not installed" for anyone using
+    // mise / fnm / nvm / volta / non-default-prefix npm — including the
+    // running flair binary itself, which was obviously installed. Each
+    // entry now has a locator that works regardless of install path:
+    //
+    //   - For packages with a bin: shell out to the bin with --version
+    //     (same PATH lookup that got them invokable in the first place).
+    //   - For library packages: require.resolve the package.json from the
+    //     running flair's module graph (works whether it's a sibling
+    //     global install or a bundled dep).
     const packages = [
-        "@tpsdev-ai/flair",
-        "@tpsdev-ai/flair-client",
-        "@tpsdev-ai/flair-mcp",
+        {
+            name: "@tpsdev-ai/flair",
+            probe: () => probeBinVersion(execFileSync, "flair"),
+        },
+        {
+            name: "@tpsdev-ai/flair-client",
+            probe: () => probeLibVersion("@tpsdev-ai/flair-client"),
+        },
+        {
+            name: "@tpsdev-ai/flair-mcp",
+            probe: () => probeBinVersion(execFileSync, "flair-mcp"),
+        },
     ];
-    const upgrades = [];
-    for (const pkg of packages) {
+    const findings = [];
+    for (const { name, probe } of packages) {
         try {
-            const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, { signal: AbortSignal.timeout(5000) });
+            const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(5000) });
             if (!res.ok)
                 continue;
             const data = await res.json();
             const latest = data.version ?? "unknown";
-            let installed = "not installed";
-            try {
-                const out = execSync(`npm list -g ${pkg} --depth=0 2>/dev/null || true`, { encoding: "utf-8" }).trim();
-                const match = out.match(/@(\d+\.\d+[\d.a-z-]*)/);
-                installed = match ? match[1] : "not installed";
-            }
-            catch { /* best effort */ }
-            const upToDate = installed === latest;
-            const icon = upToDate ? "✅" : "⬆️";
-            console.log(`  ${icon} ${pkg}: ${installed} → ${latest}${upToDate ? " (current)" : ""}`);
-            if (!upToDate && installed !== "not installed") {
-                upgrades.push({ pkg, installed, latest });
-            }
+            const installed = probe();
+            const status = installed === null ? "missing" : installed === latest ? "current" : "outdated";
+            findings.push({ name, installed, latest, status });
+            const icon = status === "current" ? "✅" : status === "outdated" ? "⬆️" : "❔";
+            const installedLabel = installed ?? "not detected";
+            const suffix = status === "current" ? " (current)" : status === "missing" ? " (run: npm install -g)" : "";
+            console.log(`  ${icon} ${name}: ${installedLabel} → ${latest}${suffix}`);
         }
         catch { /* skip unavailable packages */ }
     }
-    if (upgrades.length === 0) {
+    const outdated = findings.filter((f) => f.status === "outdated");
+    const missing = findings.filter((f) => f.status === "missing");
+    const upgrades = outdated.map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
+    if (outdated.length === 0 && missing.length === 0) {
         console.log("\n✅ Everything is up to date.");
         return;
     }
+    if (missing.length > 0 && outdated.length === 0) {
+        console.log(`\n❔ ${missing.length} package${missing.length > 1 ? "s" : ""} not detected — all detected packages are up to date.`);
+        console.log(`   Install missing: npm install -g ${missing.map((f) => f.name).join(" ")}`);
+        return;
+    }
     if (checkOnly) {
-        console.log(`\n${upgrades.length} update${upgrades.length > 1 ? "s" : ""} available. Run: flair upgrade`);
+        console.log(`\n${outdated.length} update${outdated.length > 1 ? "s" : ""} available. Run: flair upgrade`);
+        if (missing.length > 0) {
+            console.log(`${missing.length} package${missing.length > 1 ? "s" : ""} not detected${missing.length > 0 ? ": " + missing.map((f) => f.name).join(", ") : ""}.`);
+        }
         return;
     }
-    // Perform upgrade
+    // Perform upgrade. `latest` comes from the npm registry's HTTP
+    // response, so CodeQL (correctly) treats it as untrusted input.
+    // Use execFileSync with argv — the spec `<name>@<version>` becomes a
+    // single argument to npm, no shell to inject into.
     console.log(`\nUpgrading ${upgrades.length} package${upgrades.length > 1 ? "s" : ""}...\n`);
     for (const { pkg, latest } of upgrades) {
         try {
             console.log(`  Installing ${pkg}@${latest}...`);
-            execSync(`npm install -g ${pkg}@${latest}`, { stdio: "pipe" });
+            execFileSync("npm", ["install", "-g", `${pkg}@${latest}`], { stdio: "pipe" });
             console.log(`  ✅ ${pkg}@${latest} installed`);
         }
         catch (err) {
@@ -3471,7 +3544,7 @@ bridge
     const cwd = opts.cwd ?? srcArg ?? process.cwd();
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runImport } = await import("./bridges/runtime/import-runner.js");
     const { makeContext } = await import("./bridges/runtime/context.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
@@ -3481,9 +3554,9 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
@@ -3518,10 +3591,10 @@ bridge
         if (ev.type === "done") {
             const noun = (n) => `${n} ${n === 1 ? "memory" : "memories"}`;
             if (opts.dryRun) {
-                console.log(`\n${descriptor.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
+                console.log(`\n${target.name}: would import ${noun(ev.total)}. Re-run without --dry-run to write to Flair.`);
             }
             else {
-                console.log(`\n${descriptor.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
+                console.log(`\n${target.name}: imported ${ev.imported}/${ev.total} memories${ev.skipped > 0 ? ` (${ev.skipped} skipped)` : ""}.`);
             }
             return;
         }
@@ -3538,15 +3611,40 @@ bridge
         }
     };
     try {
-        await runImport({
-            descriptor,
-            cwd,
-            agentId,
-            dryRun: !!opts.dryRun,
-            putMemory,
-            onProgress,
-            ctx,
-        });
+        if (loaded.kind === "yaml") {
+            await runImport({
+                bridgeName: target.name,
+                descriptor: loaded.descriptor,
+                cwd,
+                agentId,
+                dryRun: !!opts.dryRun,
+                putMemory,
+                onProgress,
+                ctx,
+            });
+        }
+        else {
+            // Code plugin: invoke bridge.import(opts, ctx) directly; the plugin
+            // returns an AsyncIterable of BridgeMemory that runImport processes.
+            if (!loaded.plugin.import) {
+                console.error(`Bridge "${name}" is a code plugin without an import() function — can only export through it.`);
+                process.exit(1);
+            }
+            // Code-plugin options: pass through all --X flags as a single object.
+            // The plugin's declared `options` descriptor validates what it actually cares about.
+            const pluginOpts = { ...opts };
+            const source = loaded.plugin.import(pluginOpts, ctx);
+            await runImport({
+                bridgeName: target.name,
+                source,
+                cwd,
+                agentId,
+                dryRun: !!opts.dryRun,
+                putMemory,
+                onProgress,
+                ctx,
+            });
+        }
     }
     catch (err) {
         if (err instanceof BridgeRuntimeError) {
@@ -3578,7 +3676,7 @@ bridge
     const cwd = opts.cwd ?? dst;
     const { discover } = await import("./bridges/discover.js");
     const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
-    const { loadDescriptor } = await import("./bridges/runtime/load-descriptor.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
     const { runExport } = await import("./bridges/runtime/export-runner.js");
     const { makeContext } = await import("./bridges/runtime/context.js");
     const { BridgeRuntimeError } = await import("./bridges/types.js");
@@ -3588,18 +3686,22 @@ bridge
         console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
         process.exit(1);
     }
-    let descriptor;
+    let loaded;
     try {
-        descriptor = await loadDescriptor(target);
+        loaded = await loadBridge(target);
     }
     catch (err) {
         printBridgeError(err);
         process.exit(1);
     }
-    if (!descriptor.export) {
+    if (loaded.kind === "yaml" && !loaded.descriptor.export) {
         console.error(`Bridge "${name}" has no export block — cannot export through it.`);
         process.exit(1);
     }
+    if (loaded.kind === "code" && !loaded.plugin.export) {
+        console.error(`Bridge "${name}" is a code plugin without an export() function — can only import through it.`);
+        process.exit(1);
+    }
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     const ctx = makeContext({ bridge: name });
     // Memory fetcher — paginates GET /Memory?agentId=... applying any
@@ -3637,10 +3739,10 @@ bridge
     const onProgress = (ev) => {
         if (ev.type === "done") {
             if (opts.dryRun) {
-                console.log(`\n${descriptor.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
+                console.log(`\n${target.name}: would export ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total. Re-run without --dry-run to write.`);
             }
             else {
-                console.log(`\n${descriptor.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
+                console.log(`\n${target.name}: exported ${ev.exported} memor${ev.exported === 1 ? "y" : "ies"} from ${ev.total} total.`);
             }
             return;
         }
@@ -3660,15 +3762,28 @@ bridge
         process.stdout.write(`\r  filtering memory ${ev.ordinal}...`.padEnd(60));
     };
     try {
-        await runExport({
-            descriptor,
-            cwd,
-            fetchMemories,
-            filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
-            dryRun: !!opts.dryRun,
-            ctx,
-            onProgress,
-        });
+        if (loaded.kind === "yaml") {
+            await runExport({
+                descriptor: loaded.descriptor,
+                cwd,
+                fetchMemories,
+                filters: { agentId, subject: opts.subject, source: opts.source, since: opts.since },
+                dryRun: !!opts.dryRun,
+                ctx,
+                onProgress,
+            });
+        }
+        else {
+            // Code plugin export: invoke plugin.export(memoryStream, opts, ctx) directly.
+            // Plugin writes to its target however it likes (HTTP, file, etc.).
+            if (opts.dryRun) {
+                console.log(`${target.name}: dry-run not supported for code-plugin exports; aborting before invoking plugin.export().`);
+                process.exit(2);
+            }
+            const pluginOpts = { ...opts };
+            await loaded.plugin.export(fetchMemories({ agentId, subject: opts.subject, source: opts.source, since: opts.since }), pluginOpts, ctx);
+            console.log(`${target.name}: code-plugin export completed. Record count not reported by the plugin.`);
+        }
     }
     catch (err) {
         if (err instanceof BridgeRuntimeError) {
@@ -3679,21 +3794,170 @@ bridge
         process.exit(1);
     }
 });
-// `test` still stubbed — round-trip harness lands in slice 3b.
 bridge
-    .command("test <name> [args...]")
-    .description("test a bridge — not yet implemented (slice 3b of FLAIR-BRIDGES)")
-    .allowUnknownOption()
-    .action(() => {
-    console.error(`\`flair bridge test\` is not yet implemented — landing in slice 3b of FLAIR-BRIDGES.`);
-    console.error(`Slice 3a ships export (Shape A YAML); the round-trip test harness pairs with it.`);
-    process.exit(2);
+    .command("test <name>")
+    .description("Round-trip a bridge through its fixture: import → export → re-import → diff. Pass iff the stable fields (content/subject/tags/durability) match.")
+    .option("--fixture <path>", "Override the import source path (defaults to descriptor's import.sources[0].path)")
+    .option("--cwd <dir>", "Filesystem root the descriptor's relative paths resolve against (default: cwd)")
+    .option("--json", "Emit the full RoundTripResult as JSON on stdout")
+    .action(async (name, opts) => {
+    const cwd = opts.cwd ?? process.cwd();
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { loadBridge } = await import("./bridges/runtime/load-bridge.js");
+    const { runRoundTrip } = await import("./bridges/runtime/roundtrip.js");
+    const { BridgeRuntimeError } = await import("./bridges/types.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    let loaded;
+    try {
+        loaded = await loadBridge(target);
+    }
+    catch (err) {
+        printBridgeError(err);
+        process.exit(1);
+    }
+    if (loaded.kind === "code") {
+        console.error(`Bridge "${name}" is a code plugin — round-trip testing for code plugins lands in slice 3d (requires mocked fetch transport).`);
+        console.error(`For now, code plugins should ship their own tests alongside the npm package.`);
+        process.exit(2);
+    }
+    try {
+        const result = await runRoundTrip({ descriptor: loaded.descriptor, cwd, fixturePath: opts.fixture });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(result.passed ? 0 : 1);
+        }
+        if (result.passed) {
+            console.log(`✅ ${target.name} round-trip passed (${result.expectedCount} record${result.expectedCount === 1 ? "" : "s"}).`);
+            process.exit(0);
+        }
+        console.log(`❌ ${target.name} round-trip failed.`);
+        console.log(`   expected ${result.expectedCount} records, got ${result.actualCount} back.`);
+        if (result.missingInPass2.length > 0) {
+            console.log(`   missing from re-import (${result.missingInPass2.length}):`);
+            for (const m of result.missingInPass2.slice(0, 5))
+                console.log(`     - ${m.key}`);
+            if (result.missingInPass2.length > 5)
+                console.log(`     ... ${result.missingInPass2.length - 5} more`);
+        }
+        if (result.unexpectedInPass2.length > 0) {
+            console.log(`   unexpected extras in re-import (${result.unexpectedInPass2.length}):`);
+            for (const m of result.unexpectedInPass2.slice(0, 5))
+                console.log(`     - ${m.key}`);
+            if (result.unexpectedInPass2.length > 5)
+                console.log(`     ... ${result.unexpectedInPass2.length - 5} more`);
+        }
+        if (result.mismatches.length > 0) {
+            console.log(`   field mismatches (${result.mismatches.length}):`);
+            for (const m of result.mismatches.slice(0, 10)) {
+                console.log(`     - record ${m.ordinal} (${m.key}) field ${m.field}: expected ${JSON.stringify(m.expected)}, got ${JSON.stringify(m.got)}`);
+            }
+            if (result.mismatches.length > 10)
+                console.log(`     ... ${result.mismatches.length - 10} more`);
+        }
+        console.log(`\n   Intermediate export at: ${result.tmpExportPath}`);
+        process.exit(1);
+    }
+    catch (err) {
+        if (err instanceof BridgeRuntimeError) {
+            printBridgeError(err);
+            process.exit(1);
+        }
+        console.error(`Bridge test failed: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+});
+bridge
+    .command("allow <name>")
+    .description("Approve an npm code-plugin bridge for execution. Approval is pinned to the package's location and package.json contents — a malicious package squatting on the same name in a different node_modules tree will be refused at load-time.")
+    .action(async (name) => {
+    const { discover } = await import("./bridges/discover.js");
+    const { builtinDiscoveryRecords } = await import("./bridges/builtins/index.js");
+    const { allow } = await import("./bridges/runtime/allow-list.js");
+    const found = await discover({ builtins: builtinDiscoveryRecords() });
+    const target = found.find((b) => b.name === name);
+    if (!target) {
+        console.error(`No bridge named "${name}" — run \`flair bridge list\` to see installed bridges.`);
+        process.exit(1);
+    }
+    if (target.source !== "npm-package") {
+        console.error(`"${name}" is a ${target.source} bridge; only npm code plugins require allow-list approval.`);
+        console.error(`YAML and built-in bridges run via the descriptor runtime and don't execute arbitrary JS.`);
+        process.exit(1);
+    }
+    try {
+        const result = await allow(name, target.path);
+        if (result.alreadyAllowed) {
+            console.log(`${name} was already allowed at ${result.entry.packageDir} — no change.`);
+            return;
+        }
+        const verb = result.updated ? "re-approved" : "allowed";
+        console.log(`✓ ${name} ${verb}.`);
+        console.log(`  location: ${result.entry.packageDir}`);
+        console.log(`  version:  ${result.entry.version ?? "(not declared)"}`);
+        console.log(`  digest:   ${result.entry.packageJsonSha256.slice(0, 16)}…`);
+        console.log(`  If the package later moves or its package.json content changes, execution is refused until you re-run this command.`);
+        console.log(`  Revoke anytime with: flair bridge revoke ${name}`);
+    }
+    catch (err) {
+        console.error(`Failed to approve "${name}": ${err?.message ?? err}`);
+        process.exit(1);
+    }
+});
+bridge
+    .command("revoke <name>")
+    .description("Revoke approval for an npm code-plugin bridge (future invocations will require `flair bridge allow <name>` again)")
+    .action(async (name) => {
+    const { revoke } = await import("./bridges/runtime/allow-list.js");
+    const result = await revoke(name);
+    if (!result.wasAllowed) {
+        console.log(`${name} was not on the allow-list — no change.`);
+        return;
+    }
+    console.log(`✓ ${name} revoked. Future invocations require \`flair bridge allow ${name}\` again.`);
+});
+bridge
+    .command("allow-list")
+    .description("Show the allow-listed code-plugin bridges")
+    .option("--json", "Emit raw JSON")
+    .action(async (opts) => {
+    const { list: listAllowed } = await import("./bridges/runtime/allow-list.js");
+    const entries = await listAllowed();
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log("No code-plugin bridges are allow-listed yet.");
+        console.log("Allow one with: flair bridge allow <name>");
+        return;
+    }
+    const nameW = Math.max(4, ...entries.map((e) => e.name.length));
+    const verW = Math.max(7, ...entries.map((e) => (e.version ?? "—").length));
+    console.log(`  ${"name".padEnd(nameW)}  ${"version".padEnd(verW)}  allowed-at               location / digest`);
+    for (const e of entries) {
+        console.log(`  ${e.name.padEnd(nameW)}  ${(e.version ?? "—").padEnd(verW)}  ${e.allowedAt}  ${e.packageDir}`);
+        console.log(`  ${" ".repeat(nameW)}  ${" ".repeat(verW)}  ${" ".repeat(24)}  sha256:${e.packageJsonSha256.slice(0, 16)}…`);
+    }
 });
 function printBridgeError(err) {
     // Pretty-print BridgeRuntimeError as the structured shape from §10 of the
     // spec, plus a one-line human summary so the operator gets both.
     const detail = err?.detail;
     if (detail && typeof detail === "object") {
+        // Trust-check failures get a dedicated, operator-facing rendering.
+        // Dumping the full spec-§10 JSON is useful when an operator is
+        // debugging a broken YAML descriptor; for trust errors it buries the
+        // one thing that matters — the command to re-approve.
+        if (detail.field === "(trust)") {
+            printTrustError(detail);
+            return;
+        }
         console.error(`Bridge error: ${detail.hint ?? err.message}`);
         console.error(JSON.stringify(detail, null, 2));
     }
@@ -3701,6 +3965,73 @@ function printBridgeError(err) {
         console.error(`Bridge error: ${err.message ?? String(err)}`);
     }
 }
+function printTrustError(detail) {
+    const name = detail.bridge ?? "(unknown)";
+    const ctx = detail.context ?? {};
+    const reapprove = `  flair bridge allow ${name}`;
+    const bar = "─".repeat(60);
+    const header = (title) => {
+        console.error("");
+        console.error(`⚠ ${title} — ${name}`);
+        console.error(bar);
+    };
+    const footer = (label) => {
+        console.error("");
+        console.error(`${label}:`);
+        console.error(reapprove);
+        console.error("");
+    };
+    switch (detail.got) {
+        case "not-allowed":
+            header("Approval required");
+            console.error("This bridge is an npm code plugin — it runs arbitrary JavaScript.");
+            console.error("First-use approval is required before Flair will execute it.");
+            footer("Approve it with");
+            return;
+        case "path-mismatch":
+            header("Trust check failed: package location changed");
+            console.error("A different package with the same name was discovered. This is how");
+            console.error("local squatting attacks present — a planted `node_modules/flair-bridge-*`");
+            console.error("in an unrelated project tree.");
+            console.error("");
+            console.error(`  approved: ${ctx.approvedPath ?? "(unknown)"}`);
+            console.error(`            version ${ctx.approvedVersion ?? "?"} at ${ctx.approvedAt ?? "?"}`);
+            console.error(`  now:      ${ctx.observedPath ?? "(unknown)"}`);
+            footer("If the new location is intentional, re-approve");
+            return;
+        case "digest-mismatch":
+            header("Trust check failed: package contents changed");
+            console.error("The package.json at the approved location has changed since you");
+            console.error("approved this bridge. This fires on every upgrade — it's a trust");
+            console.error("event, not an error. If the update is intentional, re-approve.");
+            console.error("");
+            console.error(`  location:          ${ctx.packagePath ?? "(unknown)"}`);
+            console.error(`  approved version:  ${ctx.approvedVersion ?? "?"}   (at ${ctx.approvedAt ?? "?"})`);
+            console.error(`  approved digest:   sha256:${(ctx.approvedDigest ?? "").slice(0, 16)}…`);
+            console.error(`  observed digest:   sha256:${(ctx.observedDigest ?? "").slice(0, 16)}…`);
+            footer("Re-approve");
+            return;
+        case "entry-incomplete":
+            header("Trust check failed: approval record is incomplete");
+            console.error("The allow-list entry for this bridge is missing a location or digest.");
+            console.error("This usually means the record was created by a pre-fix Flair version");
+            console.error("(0.6.0 / 0.6.1) that only stored the name. Re-approve to upgrade.");
+            footer("Re-approve");
+            return;
+        case "package-missing":
+            header("Trust check failed: approved package missing on disk");
+            console.error("The package location recorded at allow-time is no longer readable.");
+            console.error("");
+            console.error(`  approved at:  ${ctx.approvedPath ?? "(unknown)"}`);
+            console.error(`  discovered:   ${ctx.discoveredPath ?? "(unknown)"}`);
+            footer("Reinstall the package, then re-approve");
+            return;
+        default:
+            // Unknown trust sub-reason — fall back to the raw structured print.
+            console.error(`Bridge error (trust): ${detail.hint ?? detail.got ?? "unknown"}`);
+            console.error(JSON.stringify(detail, null, 2));
+    }
+}
 // ─── flair backup ────────────────────────────────────────────────────────────
 program
     .command("backup")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",

package/dist/bridges/runtime/load-descriptor.js

@@ -1,46 +0,0 @@
-/**
- * Unified descriptor loader.
- *
- * Given a discovered bridge, resolve it into a `YamlBridgeDescriptor`
- * that the runtime executor can drive — regardless of whether the
- * descriptor came from the in-tree built-in registry, a project-local
- * YAML, a user-scoped YAML, or an npm package.
- *
- * Code-plugin bridges (Shape B, npm packages) are not supported in
- * slice 2 — calling `loadDescriptor` on one returns a structured error
- * pointing at slice 3.
- */
-import { BridgeRuntimeError } from "../types.js";
-import { loadYamlDescriptor } from "./yaml-loader.js";
-import { BUILTIN_BY_NAME } from "../builtins/index.js";
-export async function loadDescriptor(discovered) {
-    switch (discovered.source) {
-        case "builtin": {
-            const builtin = BUILTIN_BY_NAME.get(discovered.name);
-            if (!builtin) {
-                throw new BridgeRuntimeError({
-                    bridge: discovered.name,
-                    op: "import",
-                    field: "(builtin)",
-                    expected: `registered built-in name`,
-                    got: discovered.name,
-                    hint: `discovery surfaced built-in "${discovered.name}" but the registry has no entry — likely a code drift between discover.ts and builtins/index.ts`,
-                });
-            }
-            return builtin.descriptor;
-        }
-        case "project-yaml":
-        case "user-yaml":
-            return await loadYamlDescriptor(discovered.path);
-        case "npm-package":
-            throw new BridgeRuntimeError({
-                bridge: discovered.name,
-                op: "import",
-                path: discovered.path,
-                field: "(kind)",
-                expected: "yaml file or built-in",
-                got: "npm code plugin",
-                hint: "code-plugin bridge runtime ships in slice 3 of FLAIR-BRIDGES (alongside the `flair bridge allow` trust prompt). Use a YAML descriptor in the meantime, or wait for slice 3.",
-            });
-    }
-}