@tpsdev-ai/flair 0.9.0 → 0.10.1

package/dist/rem/restore.js

@@ -101,8 +101,20 @@ export async function applySnapshot(opts) {
         rmSync(tmp, { recursive: true, force: true });
         return result;
     }
-    // 3. Verify agent id matches.
-    if (metadata.agentId && metadata.agentId !== opts.agentId) {
+    // 3. Verify agent id matches. Hard-fail on missing OR mismatched —
+    //    the previous `metadata.agentId && ...` short-circuited on missing,
+    //    which means a snapshot crafted without metadata.agentId would bypass
+    //    the cross-agent guard entirely. v0.9.0+ snapshots always write
+    //    metadata.agentId (see src/rem/snapshot.ts), so the missing case can
+    //    only originate from pre-v0.9.0 snapshots or external/hand-edited
+    //    input — both of which we must reject.
+    if (!metadata.agentId) {
+        errors.push(`snapshot is missing metadata.agentId — refusing to restore (pre-v0.9.0 or untrusted snapshot)`);
+        result.status = "failed";
+        rmSync(tmp, { recursive: true, force: true });
+        return result;
+    }
+    if (metadata.agentId !== opts.agentId) {
         errors.push(`snapshot agentId (${metadata.agentId}) does not match target (${opts.agentId}) — refusing to restore cross-agent`);
         result.status = "failed";
         rmSync(tmp, { recursive: true, force: true });
@@ -197,6 +209,54 @@ export async function applySnapshot(opts) {
             errors.push(`put-soul ${s.id}: ${err?.message ?? String(err)}`);
         }
     }
+    // 7. Verify post-restore state (default on; opt-out via verifyPostRestore=false).
+    //    Catches silent failures: Harper schema coercion, 4xx responses the
+    //    apiCall layer masked as ok, partial-DELETE leftovers. Per-ID diff,
+    //    not just counts — count parity can hide simultaneous PUT+DELETE
+    //    failures that wash out numerically. See ops-90dq.
+    if (opts.verifyPostRestore !== false) {
+        try {
+            const verifyMem = asArray(await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`));
+            const verifySouls = asArray(await opts.apiCall("GET", `/Soul?agentId=${encodeURIComponent(opts.agentId)}`));
+            const expectedMemoryIds = memories.filter((m) => m?.id).map((m) => String(m.id));
+            const expectedSoulIds = souls.filter((s) => s?.id).map((s) => String(s.id));
+            const actualMemoryIds = verifyMem.filter((m) => m?.id).map((m) => String(m.id));
+            const actualSoulIds = verifySouls.filter((s) => s?.id).map((s) => String(s.id));
+            const expMem = new Set(expectedMemoryIds);
+            const expSoul = new Set(expectedSoulIds);
+            const actMem = new Set(actualMemoryIds);
+            const actSoul = new Set(actualSoulIds);
+            const missingMemoryIds = [...expMem].filter((id) => !actMem.has(id));
+            const missingSoulIds = [...expSoul].filter((id) => !actSoul.has(id));
+            const extraMemoryIds = [...actMem].filter((id) => !expMem.has(id));
+            const extraSoulIds = [...actSoul].filter((id) => !expSoul.has(id));
+            result.verified = {
+                expectedMemoryIds,
+                expectedSoulIds,
+                actualMemoryIds,
+                actualSoulIds,
+                missingMemoryIds,
+                missingSoulIds,
+                extraMemoryIds,
+                extraSoulIds,
+            };
+            if (missingMemoryIds.length > 0) {
+                errors.push(`post-restore-verify: ${missingMemoryIds.length} memory rows missing (e.g. ${missingMemoryIds.slice(0, 3).join(", ")})`);
+            }
+            if (missingSoulIds.length > 0) {
+                errors.push(`post-restore-verify: ${missingSoulIds.length} soul rows missing (e.g. ${missingSoulIds.slice(0, 3).join(", ")})`);
+            }
+            if (extraMemoryIds.length > 0) {
+                errors.push(`post-restore-verify: ${extraMemoryIds.length} unexpected memory rows present (e.g. ${extraMemoryIds.slice(0, 3).join(", ")})`);
+            }
+            if (extraSoulIds.length > 0) {
+                errors.push(`post-restore-verify: ${extraSoulIds.length} unexpected soul rows present (e.g. ${extraSoulIds.slice(0, 3).join(", ")})`);
+            }
+        }
+        catch (err) {
+            errors.push(`post-restore-verify: ${err?.message ?? String(err)}`);
+        }
+    }
     rmSync(tmp, { recursive: true, force: true });
     if (errors.length > 0) {
         result.status = "failed";

package/dist/render.js

@@ -0,0 +1,168 @@
+// CLI output renderer — color, tables, icons, spinner, output-mode resolution.
+//
+// Two output modes coexist across every command:
+//
+//   human  — pretty default, ANSI color when stdout is a TTY and NO_COLOR/
+//            FLAIR_NO_COLOR aren't set
+//   json   — agent-default, also auto-selected when stdout is piped
+//
+// Precedence: --json flag > FLAIR_OUTPUT=json env > non-TTY stdout > TTY (human).
+// Setting FLAIR_OUTPUT=human forces human mode even when piped.
+//
+// No third-party deps — minimal ANSI by hand keeps the dependency tree flat
+// (the rest of the flair runtime already runs ANSI-free; we don't need
+// chalk/picocolors' edge-case coverage for SGR codes we don't use).
+const stdoutIsTTY = !!process.stdout.isTTY;
+const stderrIsTTY = !!process.stderr.isTTY;
+const noColorEnv = process.env.NO_COLOR != null || process.env.FLAIR_NO_COLOR != null;
+const enableColor = stdoutIsTTY && !noColorEnv;
+const C = (code) => (enableColor ? `\x1b[${code}m` : "");
+export const c = {
+    reset: C("0"),
+    bold: C("1"),
+    dim: C("2"),
+    italic: C("3"),
+    underline: C("4"),
+    red: C("31"),
+    green: C("32"),
+    yellow: C("33"),
+    blue: C("34"),
+    magenta: C("35"),
+    cyan: C("36"),
+    white: C("37"),
+    gray: C("90"),
+};
+export function wrap(color, text) {
+    if (!color)
+        return text;
+    return `${color}${text}${c.reset}`;
+}
+export function resolveOutputMode(opts) {
+    if (opts.json)
+        return "json";
+    const envOut = process.env.FLAIR_OUTPUT;
+    if (envOut === "json")
+        return "json";
+    if (envOut === "human")
+        return "human";
+    // No explicit selection — pipe-friendly default: non-TTY stdout → json.
+    return stdoutIsTTY ? "human" : "json";
+}
+export const icons = {
+    ok: wrap(c.green, "✓"),
+    warn: wrap(c.yellow, "⚠"),
+    error: wrap(c.red, "✗"),
+    info: wrap(c.cyan, "ℹ"),
+    bullet: wrap(c.gray, "·"),
+    pending: wrap(c.gray, "○"),
+    arrow: wrap(c.gray, "→"),
+};
+// Status header: bullet + bold label. Use for top-level command titles.
+export function header(label) {
+    return wrap(c.bold, label);
+}
+// Section divider — used between groups inside one command's output.
+// Subtle line + bold label, no big ═══ banners (those compete with content).
+export function section(label) {
+    return `\n${wrap(c.bold, label)}\n${wrap(c.gray, "─".repeat(Math.min(60, label.length + 8)))}`;
+}
+// Key/value pair with aligned label. Default label width 14 cols.
+export function kv(label, value, labelWidth = 14) {
+    return `  ${wrap(c.dim, label.padEnd(labelWidth))} ${value}`;
+}
+export function table(columns, rows) {
+    if (rows.length === 0)
+        return wrap(c.dim, "  (no rows)");
+    const widths = columns.map((col) => col.label.length);
+    const cells = rows.map((row) => columns.map((col, i) => {
+        const raw = row[col.key];
+        const formatted = col.format ? col.format(raw, row) : raw == null ? "—" : String(raw);
+        // Visible-width calculation — strip our own ANSI escapes before counting
+        const visibleLen = formatted.replace(/\x1b\[[0-9;]*m/g, "").length;
+        if (visibleLen > widths[i])
+            widths[i] = visibleLen;
+        return formatted;
+    }));
+    const align = (str, width, side) => {
+        const visibleLen = str.replace(/\x1b\[[0-9;]*m/g, "").length;
+        const pad = " ".repeat(Math.max(0, width - visibleLen));
+        return side === "right" ? pad + str : str + pad;
+    };
+    const headerRow = "  " +
+        columns.map((col, i) => wrap(c.dim, align(col.label, widths[i], col.align))).join("  ");
+    const bodyRows = cells
+        .map((row) => "  " + row.map((cell, i) => align(cell, widths[i], columns[i].align)).join("  "))
+        .join("\n");
+    return `${headerRow}\n${bodyRows}`;
+}
+export function spinner(label) {
+    if (!stderrIsTTY || noColorEnv) {
+        process.stderr.write(`${label}...\n`);
+        return {
+            stop: (final) => {
+                if (final)
+                    process.stderr.write(`${final}\n`);
+            },
+            update: (next) => {
+                process.stderr.write(`${next}...\n`);
+            },
+        };
+    }
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let current = label;
+    let i = 0;
+    const handle = setInterval(() => {
+        process.stderr.write(`\r${wrap(c.cyan, frames[i])} ${current}`);
+        i = (i + 1) % frames.length;
+    }, 80);
+    return {
+        stop: (final) => {
+            clearInterval(handle);
+            process.stderr.write("\r\x1b[K");
+            if (final)
+                process.stderr.write(`${final}\n`);
+        },
+        update: (next) => {
+            current = next;
+        },
+    };
+}
+// Canonical JSON output: 2-space indent, trailing newline omitted by caller.
+export function asJSON(value) {
+    return JSON.stringify(value, null, 2);
+}
+// Bytes → human readable. Mirror of humanBytes in cli.ts; centralizing here
+// so render-aware code shares the same format.
+export function humanBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "—";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+// ISO timestamp → "12m ago" / "2h ago" / "5d ago" / "—" (null) / fallback.
+export function relativeTime(iso) {
+    if (!iso)
+        return "—";
+    const ago = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(ago) || ago < 0)
+        return "—";
+    const mins = Math.floor(ago / 60000);
+    const hrs = Math.floor(ago / 3600000);
+    const days = Math.floor(ago / 86400000);
+    return days > 0 ? `${days}d ago` : hrs > 0 ? `${hrs}h ago` : mins > 0 ? `${mins}m ago` : "just now";
+}
+// Convenience: print the right shape for the resolved output mode.
+// Caller passes both representations and the resolveOutputMode result.
+export function print(mode, jsonValue, humanText) {
+    if (mode === "json") {
+        console.log(asJSON(jsonValue));
+    }
+    else {
+        console.log(humanText);
+    }
+}

package/dist/resources/A2AAdapter.js

@@ -265,9 +265,15 @@ function statusFromOrgEvent(event) {
         null);
 }
 export class A2AAdapter extends Resource {
-    // A2A discovery surface — agent cards and adapter metadata are intentionally
-    // public so other agents/clients can discover this Flair as a memory peer.
-    // Handler enforces auth on actual A2A actions (POST below).
+    // A2A discovery surface — agent-card metadata (GET) is intentionally
+    // public so other agents/clients can discover this Flair as a memory
+    // peer. POST is JSON-RPC for actions (message/send writes OrgEvents,
+    // tasks/list reads Beads issues, message/stream subscribes to events)
+    // and is auth-gated upstream by auth-middleware's narrowed allow-list
+    // (GET /a2a passes through; POST /a2a must carry TPS-Ed25519 or admin
+    // Basic). The post() handler below additionally enforces sender ==
+    // params.agentId for message/send so an authenticated caller can only
+    // act AS themselves, not impersonate another agent.
     allowRead() { return true; }
     allowCreate() { return true; }
     async get() {
@@ -310,6 +316,20 @@ export class A2AAdapter extends Resource {
         }
         const id = body.id ?? null;
         const params = body.params ?? {};
+        // Defense-in-depth: auth-middleware narrows the /a2a allow-list so
+        // POSTs only reach here after TPS-Ed25519 or admin Basic succeeds,
+        // which sets request.tpsAgent / tpsAgentIsAdmin. If middleware was
+        // misconfigured or someone added a back-door allow-list entry, fail
+        // closed here. Pattern matches WorkspaceState/Memory/etc.
+        const ctx = this.getContext?.() ?? _context ?? {};
+        const ctxRequest = ctx.request ?? ctx;
+        const callerAgent = ctxRequest?.tpsAgent;
+        const callerIsAdmin = ctxRequest?.tpsAgentIsAdmin === true;
+        if (!callerAgent && !callerIsAdmin) {
+            return rpcError(id, -32001, "Unauthorized", {
+                detail: "POST /a2a requires TPS-Ed25519 or admin Basic auth",
+            });
+        }
         try {
             if (body.method === "message/stream") {
                 const agentId = cleanText(params.agentId);
@@ -407,6 +427,16 @@ export class A2AAdapter extends Resource {
                 if (!agentId || !message || typeof message !== "object") {
                     return rpcError(id, -32602, "Invalid params: agentId and message are required");
                 }
+                // Sender must match params.agentId — you can only send AS yourself.
+                // Admin agents may send as anyone (operational convenience).
+                // Without this check, an authenticated agent could forge OrgEvents
+                // attributed to any other agent — defeats the whole signed-envelopes
+                // model that delegationChain enforces for TPS mail.
+                if (!callerIsAdmin && callerAgent !== agentId) {
+                    return rpcError(id, -32001, "Forbidden", {
+                        detail: `caller ${callerAgent ?? "(anon)"} cannot send as ${agentId}`,
+                    });
+                }
                 const agent = await databases.flair.Agent.get(agentId).catch(() => null);
                 if (!agent) {
                     return rpcError(id, -32004, "Agent not found", { agentId });

package/dist/resources/AdminInstance.js

@@ -13,17 +13,49 @@ import { fileURLToPath } from "node:url";
  * 127.0.0.1 binding address Harper sees internally — so the Endpoints
  * table is copy-pasteable.
  *
- * Fall back to `http://127.0.0.1:${HTTP_PORT}` for local-only installs.
+ * Resolution order:
+ *   1. `FLAIR_PUBLIC_URL` env var (explicit override, always wins)
+ *   2. Request headers (X-Forwarded-Proto + X-Forwarded-Host, or Host)
+ *      — derives from how the operator actually reached the page
+ *   3. `http://127.0.0.1:${HTTP_PORT}` — local-only installs fallback
+ *
+ * The request-header path closes the common case from flair#404:
+ * remote/Fabric deployments without FLAIR_PUBLIC_URL set rendered
+ * localhost URLs that operators couldn't copy-paste. Trusting the Host
+ * header is correct when Harper terminates TLS directly; behind a
+ * reverse proxy that doesn't set X-Forwarded-* headers correctly, the
+ * operator should set FLAIR_PUBLIC_URL explicitly (which wins).
  */
-function resolvePublicUrl() {
-    // Explicit override wins. Production deployments (Fabric, VPS-hosted)
-    // should set FLAIR_PUBLIC_URL in their launchd / systemd unit so the
-    // admin pane shows the URL operators actually type, not the binding
-    // address Harper sees internally. Auto-detecting from request headers
-    // is brittle across reverse-proxy configurations.
+function resolvePublicUrl(request) {
     if (process.env.FLAIR_PUBLIC_URL) {
         return process.env.FLAIR_PUBLIC_URL.replace(/\/$/, "");
     }
+    // Best-effort header derivation. Harper's request.headers exposes
+    // both .get(name) and .asObject (case-insensitive). Prefer X-Forwarded-*
+    // when present (caller is behind a proxy that set them); fall back
+    // to the direct Host header.
+    const getHeader = (name) => {
+        const h = request?.headers;
+        if (!h)
+            return undefined;
+        if (typeof h.get === "function")
+            return h.get(name) ?? h.get(name.toLowerCase()) ?? undefined;
+        if (typeof h === "object") {
+            const obj = h.asObject ?? h;
+            return obj[name] ?? obj[name.toLowerCase()] ?? undefined;
+        }
+        return undefined;
+    };
+    const fwdProto = getHeader("X-Forwarded-Proto");
+    const fwdHost = getHeader("X-Forwarded-Host");
+    const host = fwdHost ?? getHeader("Host");
+    if (host && /^[\w.\-:]+$/.test(host)) {
+        const scheme = fwdProto && (fwdProto === "http" || fwdProto === "https") ? fwdProto : "https";
+        // If no proxy headers and host has no port, assume http for safety —
+        // most production deployments are behind a proxy with X-Forwarded-Proto.
+        const effectiveScheme = fwdProto ? scheme : (host.includes(":") ? "http" : scheme);
+        return `${effectiveScheme}://${host}`;
+    }
     return `http://127.0.0.1:${process.env.HTTP_PORT ?? "19926"}`;
 }
 /**
@@ -55,7 +87,11 @@ function resolveVersion() {
 export class AdminInstance extends Resource {
     async get() {
         const version = resolveVersion();
-        const publicUrl = resolvePublicUrl();
+        // Pass the request through so URL resolution can derive from
+        // X-Forwarded-* / Host headers when FLAIR_PUBLIC_URL isn't set.
+        const ctx = this.getContext?.() ?? {};
+        const request = ctx.request ?? ctx;
+        const publicUrl = resolvePublicUrl(request);
         // Try to read instance public key
         let publicKey = "—";
         const keyDir = join(homedir(), ".flair", "keys");

package/dist/resources/AgentCard.js

@@ -1,10 +1,5 @@
 import { Resource, databases } from "@harperfast/harper";
-function readSoulKind(entry) {
-    return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
-}
-function readSoulContent(entry) {
-    return String(entry.content ?? entry.value ?? "").trim();
-}
+import { selectPublicDescription, selectPublicSkills } from "./agentcard-fields.js";
 export class AgentCard extends Resource {
     async get(pathInfo) {
         const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
@@ -25,19 +20,15 @@ export class AgentCard extends Resource {
             if (row?.agentId === agentId)
                 souls.push(row);
         }
-        const descriptionEntry = souls.find((s) => readSoulKind(s) === "description" && readSoulContent(s)) ??
-            souls.find((s) => readSoulContent(s));
-        const skills = souls
-            .filter((s) => readSoulKind(s) === "capability")
-            .map((s) => readSoulContent(s))
-            .filter(Boolean);
         return {
             name: String(agent.name ?? agent.id ?? agentId),
-            description: descriptionEntry ? readSoulContent(descriptionEntry) : "",
+            // Only an explicit kind="description" soul publishes — no private-soul
+            // fallback (ops-vz6j). See agentcard-fields.ts for the security rationale.
+            description: selectPublicDescription(souls),
             url: String(agent.url ?? ""),
             version: String(agent.version ?? "1.0.0"),
             capabilities: agent.capabilities && typeof agent.capabilities === "object" ? agent.capabilities : {},
-            skills,
+            skills: selectPublicSkills(souls),
             defaultInputModes: ["text"],
             defaultOutputModes: ["text"],
         };

package/dist/resources/Federation.js

@@ -3,6 +3,8 @@ import { randomBytes } from "node:crypto";
 import nacl from "tweetnacl";
 import { canonicalize, signBody, verifyBodySignature, signBodyFresh, verifyBodySignatureFresh, createNonceStore, generateNonce, } from "./federation-crypto.js";
 import { initFederationCleanup } from "./federation-cleanup.js";
+import { classifyRecord } from "./federation-classify.js";
+export { classifyRecord } from "./federation-classify.js";
 // Module-level nonce store for federation anti-replay.
 // Shared across FederationPair + FederationSync — nonces are globally unique
 // (generated by signBodyFresh per request with 128-bit random nonces).
@@ -268,6 +270,12 @@ export class FederationSync extends Resource {
         const startTime = Date.now();
         let merged = 0;
         let skipped = 0;
+        const skippedReasons = {};
+        const mergeErrors = [];
+        function recordSkip(reason) {
+            skipped++;
+            skippedReasons[reason] = (skippedReasons[reason] ?? 0) + 1;
+        }
         // Table name → Harper database table mapping
         const tableMap = {
             Memory: databases.flair.Memory,
@@ -275,66 +283,88 @@ export class FederationSync extends Resource {
             Agent: databases.flair.Agent,
             Relationship: databases.flair.Relationship,
         };
+        const knownTables = new Set(Object.keys(tableMap));
         for (const record of records) {
-            const table = tableMap[record.table];
-            if (!table) {
-                skipped++;
-                continue;
-            }
-            // Originator enforcement: peers can only push records they originated.
-            // The hub can relay records from other peers (role === "hub"),
-            // but spokes can only push their own records.
-            const originator = record.originatorInstanceId ?? instanceId;
-            if (originator !== instanceId && peer.role !== "hub") {
-                skipped++;
-                continue;
-            }
             try {
-                const local = await table.get(record.id);
-                // Timestamp ceiling: reject records with updatedAt more than 5 minutes in the future.
-                // Prevents attackers from using far-future timestamps to permanently win LWW.
-                const fiveMinFromNow = new Date(Date.now() + 5 * 60 * 1000).toISOString();
-                if (record.updatedAt > fiveMinFromNow) {
-                    skipped++;
+                const table = tableMap[record.table];
+                const local = table ? await table.get(record.id) : null;
+                const decision = classifyRecord(record, peer.role, instanceId, local, knownTables);
+                if (decision.action === "skip") {
+                    recordSkip(decision.reason);
                     continue;
                 }
                 const mergedData = mergeRecord(local, record);
-                // Preserve originator for provenance
-                mergedData._originatorInstanceId = originator;
+                mergedData._originatorInstanceId = decision.originator;
                 mergedData._syncedFrom = instanceId;
                 mergedData._syncedAt = new Date().toISOString();
                 await table.put(mergedData);
                 merged++;
             }
-            catch {
-                skipped++;
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                recordSkip("merge_error");
+                // Cap the captured-error list so a hostile/buggy peer can't blow up
+                // the SyncLog row, but ALWAYS log to console so operators don't lose
+                // the per-record signal — the silent-swallow is the bug we're fixing.
+                if (mergeErrors.length < 10) {
+                    mergeErrors.push(`${record.table}/${record.id}: ${msg}`);
+                }
+                console.warn(`[Federation] merge error for ${record.table}/${record.id} from ${instanceId}: ${msg}`);
             }
         }
-        // Update peer sync cursor
-        await databases.flair.Peer.put({
+        // Peer cursor update — distinguish liveness from progress:
+        //   lastSyncAt → "we heard from this peer just now" (always update)
+        //   lastMergeAt → "data actually flowed in" (only when merged > 0)
+        // Conflating them produced the "green dashboard while burning" failure
+        // mode — dogfood pass 2026-05-26 surfaced unconditional update masking
+        // 100%-skip syncs.
+        const nowIso = new Date().toISOString();
+        const peerUpdate = {
             ...peer,
-            lastSyncAt: new Date().toISOString(),
-            lastSyncCursor: lamportClock?.toString() ?? new Date().toISOString(),
+            lastSyncAt: nowIso,
+            lastSyncCursor: lamportClock?.toString() ?? nowIso,
             status: "connected",
-            updatedAt: new Date().toISOString(),
-        });
-        // Log sync operation
+            updatedAt: nowIso,
+        };
+        if (merged > 0) {
+            peerUpdate.lastMergeAt = nowIso;
+        }
+        await databases.flair.Peer.put(peerUpdate);
+        // Log sync operation with skip-reason breakdown so the partial state
+        // is debuggable instead of a black box.
         try {
+            const errorParts = [];
+            if (Object.keys(skippedReasons).length > 0) {
+                errorParts.push("skipped: " +
+                    Object.entries(skippedReasons)
+                        .map(([reason, n]) => `${n} ${reason}`)
+                        .join(", "));
+            }
+            if (mergeErrors.length > 0) {
+                errorParts.push("merge_errors: " + mergeErrors.join("; "));
+            }
+            const errorSummary = errorParts.length > 0 ? errorParts.join(" | ") : undefined;
+            const status = mergeErrors.length > 0
+                ? "partial"
+                : skipped > 0 ? "partial" : "success";
             await databases.flair.SyncLog.put({
                 id: `sync_${Date.now()}_${randomBytes(4).toString("hex")}`,
                 peerId: instanceId,
                 direction: "pull",
                 recordCount: merged,
-                status: skipped > 0 ? "partial" : "success",
-                error: skipped > 0 ? `${skipped} records skipped` : undefined,
+                skippedCount: skipped,
+                skippedReasons: JSON.stringify(skippedReasons),
+                status,
+                error: errorSummary,
                 durationMs: Date.now() - startTime,
-                createdAt: new Date().toISOString(),
+                createdAt: nowIso,
             });
         }
         catch { /* non-fatal */ }
         return {
             merged,
             skipped,
+            skippedReasons,
             total: records.length,
             durationMs: Date.now() - startTime,
         };
@@ -354,6 +384,7 @@ export class FederationPeers extends Resource {
                     status: p.status,
                     endpoint: p.endpoint,
                     lastSyncAt: p.lastSyncAt,
+                    lastMergeAt: p.lastMergeAt,
                     relayOnly: p.relayOnly,
                     pairedAt: p.pairedAt,
                 });

package/dist/resources/agentcard-fields.js

@@ -0,0 +1,40 @@
+// Pure selection logic for what an agent's public AgentCard exposes.
+//
+// SECURITY: `GET /AgentCard/{id}` is intentionally UNAUTHENTICATED (A2A spec —
+// agent cards are public discovery metadata, and the auth-middleware allow-list
+// lets it bypass auth). Everything these helpers return is therefore world-
+// readable. They must publish ONLY explicitly-kinded souls — never an implicit
+// fallback that could surface a private soul (an operator's internal note,
+// prompt fragment, or credential reminder) on the public endpoint.
+//
+// Kept free of any @harperfast/harper import so the real logic is unit-testable
+// without spinning up Harper (avoids the simulator-pattern that let the
+// description-fallback leak ship untested — ops-vz6j).
+export function readSoulKind(entry) {
+    return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
+}
+export function readSoulContent(entry) {
+    return String(entry.content ?? entry.value ?? "").trim();
+}
+/**
+ * The public description is ONLY an explicit `kind="description"` soul.
+ *
+ * There is deliberately no fallback to "the first soul with any content": that
+ * was the ops-vz6j leak — an agent with no description soul would publish an
+ * arbitrary private soul on the unauthenticated card. Absent an explicit
+ * description, publish nothing.
+ */
+export function selectPublicDescription(souls) {
+    const entry = souls.find((s) => readSoulKind(s) === "description" && readSoulContent(s));
+    return entry ? readSoulContent(entry) : "";
+}
+/**
+ * Public skills are ONLY `kind="capability"` souls — an explicit, operator-
+ * intended allow-list. Any other soul kind is never published.
+ */
+export function selectPublicSkills(souls) {
+    return souls
+        .filter((s) => readSoulKind(s) === "capability")
+        .map((s) => readSoulContent(s))
+        .filter(Boolean);
+}